diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..083ccde --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,10 @@ +# Uncomment one or more lines below to enable funding links across Quirk Systems +# repositories. See: +# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository +# +# github: [quirk-systems] +# patreon: # Replace with a single Patreon username +# open_collective: # Replace with a single Open Collective username +# ko_fi: # Replace with a single Ko-fi username +# tidelift: # Replace with a single Tidelift platform-name/package-name +# custom: # Replace with up to 4 custom sponsorship URLs diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..7b02cb6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,75 @@ +name: Bug report +description: Report something that isn't working as expected. +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. The more detail you can give, the faster we can fix it. + - type: input + id: summary + attributes: + label: Summary + description: One-sentence description of the bug. + placeholder: e.g. "Vitest fails to find setup file when running with --coverage" + validations: + required: true + - type: textarea + id: repro + attributes: + label: Reproduction steps + description: Minimal steps to reproduce. Numbered list preferred. + placeholder: | + 1. Clone the repo + 2. Run `bun install` + 3. Run `bun run test:coverage` + 4. Observe the error + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include error messages and stack traces if relevant. Use code blocks. + validations: + required: true + - type: input + id: repo + attributes: + label: Repository + description: Which Quirk Systems repo is affected? + placeholder: e.g. project-scaffold + validations: + required: true + - type: input + id: version + attributes: + label: Version / commit + description: Tag, version number, or commit SHA. + validations: + required: false + - type: textarea + id: env + attributes: + label: Environment + description: OS, runtime versions (Node, Bun), browser if relevant. + placeholder: | + - OS: macOS 14.5 + - Bun: 1.1.30 + - Node: 20.18.0 + validations: + required: false + - type: textarea + id: logs + attributes: + label: Logs / screenshots + description: Paste relevant logs (use code blocks) or attach screenshots. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8d595d7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/quirk-systems/.github/security/policy + about: Please do not open a public issue for security vulnerabilities. See our security policy for private reporting instructions. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..97323ff --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,40 @@ +name: Feature request +description: Propose a new feature or enhancement. +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What problem are you trying to solve? Who hits it and how often? + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed solution + description: What would you like to see? Sketch the UX or API if possible. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about and why you ruled them out. + validations: + required: false + - type: input + id: repo + attributes: + label: Repository + description: Which Quirk Systems repo would this land in? + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional context + description: Mockups, links to related issues, prior art, etc. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d967dfa --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Summary + + + +- + +## Test plan + + + +- [ ] + +## Linked issues + + + +## Checklist + +- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/) +- [ ] Local validation passes (`bun run validate` or repo equivalent) +- [ ] Tests added/updated where it makes sense +- [ ] Docs updated where it makes sense diff --git a/.github/workflows/reusable-pr-title-lint.yml b/.github/workflows/reusable-pr-title-lint.yml new file mode 100644 index 0000000..a462435 --- /dev/null +++ b/.github/workflows/reusable-pr-title-lint.yml @@ -0,0 +1,16 @@ +name: Reusable PR title lint + +on: + workflow_call: + +permissions: + pull-requests: read + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Validate PR title against Conventional Commits + uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ github.token }} diff --git a/.github/workflows/reusable-validate.yml b/.github/workflows/reusable-validate.yml new file mode 100644 index 0000000..becd441 --- /dev/null +++ b/.github/workflows/reusable-validate.yml @@ -0,0 +1,118 @@ +name: Reusable validate + +on: + workflow_call: + inputs: + package-manager: + description: "Package manager: bun | pnpm | yarn | npm" + required: false + type: string + default: bun + node-version: + description: "Node.js version" + required: false + type: string + default: "20" + bun-version: + description: "Bun version (used when package-manager = bun)" + required: false + type: string + default: latest + working-directory: + description: "Directory to run commands from" + required: false + type: string + default: "." + test-script: + description: "Script name for one-shot tests (e.g. test:run, test)" + required: false + type: string + default: "test:run" + run-build: + description: "Run the build step" + required: false + type: boolean + default: true + run-e2e: + description: "Run Playwright e2e tests" + required: false + type: boolean + default: false + e2e-script: + description: "Script name for e2e tests" + required: false + type: string + default: "test:e2e" + +jobs: + validate: + runs-on: ubuntu-latest + env: + # Quirk Systems repos use t3-env; allow the build to skip strict env + # validation when secrets aren't configured in CI. + SKIP_ENV_VALIDATION: "1" + defaults: + run: + working-directory: ${{ inputs.working-directory }} + steps: + - uses: actions/checkout@v4 + + - name: Setup Bun + if: inputs.package-manager == 'bun' + uses: oven-sh/setup-bun@v2 + with: + bun-version: ${{ inputs.bun-version }} + + - name: Setup pnpm + if: inputs.package-manager == 'pnpm' + uses: pnpm/action-setup@v4 + + - name: Setup Node.js (with cache) + if: inputs.package-manager != 'bun' + uses: actions/setup-node@v4 + with: + node-version: ${{ inputs.node-version }} + cache: ${{ inputs.package-manager }} + + - name: Setup Node.js + if: inputs.package-manager == 'bun' + uses: actions/setup-node@v4 + with: + node-version: ${{ inputs.node-version }} + + - name: Install dependencies + run: | + case "${{ inputs.package-manager }}" in + bun) bun install --frozen-lockfile ;; + pnpm) pnpm install --frozen-lockfile ;; + yarn) yarn install --frozen-lockfile ;; + npm) npm ci ;; + *) echo "Unknown package manager: ${{ inputs.package-manager }}" && exit 1 ;; + esac + + - name: Lint + run: ${{ inputs.package-manager }} run lint + + - name: Type-check + run: ${{ inputs.package-manager }} run type-check + + - name: Test + run: ${{ inputs.package-manager }} run ${{ inputs.test-script }} + + - name: Build + if: inputs.run-build + run: ${{ inputs.package-manager }} run build + + - name: Install Playwright browsers + if: inputs.run-e2e + run: | + case "${{ inputs.package-manager }}" in + bun) bunx playwright install --with-deps ;; + pnpm) pnpm exec playwright install --with-deps ;; + yarn) yarn playwright install --with-deps ;; + npm) npx playwright install --with-deps ;; + esac + + - name: E2E tests + if: inputs.run-e2e + run: ${{ inputs.package-manager }} run ${{ inputs.e2e-script }} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bd46bd9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +****. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cdb627d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing to Quirk Systems + +Thanks for your interest in contributing! These guidelines apply to every repository under [@quirk-systems](https://github.com/quirk-systems). Individual repos may add a `CONTRIBUTING.md` of their own that supplements (but does not override) this one. + +## Code of Conduct + +Participation is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to uphold it. + +## Reporting issues + +- **Bugs:** open a [bug report](https://github.com/quirk-systems/.github/issues/new?template=bug_report.yml). Include reproduction steps, expected vs. actual behavior, and environment details. +- **Features:** open a [feature request](https://github.com/quirk-systems/.github/issues/new?template=feature_request.yml). +- **Security vulnerabilities:** see [SECURITY.md](SECURITY.md). Do **not** file a public issue. + +## Development workflow + +### Branch naming + +Use one of these prefixes: + +- `feature/` — new functionality +- `fix/` — bug fixes +- `chore/` — refactors, deps, tooling, docs + +### Commits + +Repos use [Conventional Commits](https://www.conventionalcommits.org/) enforced by [commitlint](https://commitlint.js.org/). Format: + +``` +(): +``` + +Common types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `perf`, `build`. Squash-merge PR titles must also follow this format — the org's reusable PR-title workflow enforces it. + +### Local hooks + +Repos that use [Lefthook](https://lefthook.dev/) install pre-commit and commit-msg hooks automatically when you install dependencies. They run lint, format checks, type-check, and commit-message validation. Don't bypass with `--no-verify` — fix the underlying issue. + +### Validation + +Each repo exposes a single command that runs the full local validation pipeline: + +| Repo | Command | +| --------------------------------------------------------------------- | ----------------------------------------------------- | +| [project-scaffold](https://github.com/quirk-systems/project-scaffold) | `bun run validate` (lint + type-check + test + build) | + +Run it before opening a PR. CI runs the same checks; passing locally first saves a round trip. + +## Pull requests + +Use the PR template — at minimum: + +- **Summary** of the change and the motivation. +- **Test plan** — how you verified it (commands, screenshots, links). +- **Linked issue** if one exists. + +Keep PRs focused. If a change grows, split it. + +## License + +By contributing you agree your contribution is licensed under the project's license (Apache 2.0 unless the repo specifies otherwise). diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..546aeee --- /dev/null +++ b/NOTICE @@ -0,0 +1,14 @@ +quirk-systems/.github +Copyright 2025-2026 Quirk Systems + +This repository contains the organization profile, community-health files, +and reusable GitHub Actions workflows for Quirk Systems +(https://github.com/quirk-systems). + +Licensed under the Apache License, Version 2.0 (the "License"). +A copy of the License is included in the LICENSE file at the root of +this repository, and is also available at: + + http://www.apache.org/licenses/LICENSE-2.0 + +This product includes software developed at Quirk Systems. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a4b0b53 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +Quirk Systems takes security seriously. We appreciate responsible disclosure and will work with you to investigate and address vulnerabilities. + +## Reporting a vulnerability + +**Do not open a public issue.** Instead: + +1. Email **** with a description, reproduction steps, and impact. +2. Optionally, request our PGP key from the same address to encrypt sensitive details. + +We will acknowledge your report within **72 hours** and provide a status update within **7 days**. We aim to ship a fix within **90 days** of confirmation, depending on severity and complexity. + +## Coordinated disclosure + +We follow a 90-day coordinated-disclosure window. We'll credit reporters in release notes unless anonymity is requested. Please give us reasonable time to ship a fix before public disclosure. + +## Supported versions + +We support and patch the latest released version of each project. Older versions receive critical-severity fixes only. + +| Version | Supported | +| ------- | ------------------- | +| latest | :white_check_mark: | +| older | critical fixes only | + +## Out of scope + +- Vulnerabilities in third-party services or dependencies (please report upstream). +- Issues that require physical access or stolen credentials. +- Social engineering of staff. +- Denial of service through resource exhaustion against personal infrastructure. diff --git a/profile/README.md b/profile/README.md new file mode 100644 index 0000000..4f54cc2 --- /dev/null +++ b/profile/README.md @@ -0,0 +1,12 @@ +# Quirk Systems + +Building tools and templates for AI-augmented product development. + +## Projects + +- **[project-scaffold](https://github.com/quirk-systems/project-scaffold)** — opinionated Next.js 15 boilerplate (Bun, TypeScript, Tailwind v4, shadcn/ui, Drizzle, Vitest, Playwright). +- **[quirk-generator](https://github.com/quirk-systems/quirk-generator)** — AI image generation app template using the Vercel AI SDK and Fal. + +## Contributing + +See [CONTRIBUTING](https://github.com/quirk-systems/.github/blob/main/CONTRIBUTING.md), our [Code of Conduct](https://github.com/quirk-systems/.github/blob/main/CODE_OF_CONDUCT.md), and the [security policy](https://github.com/quirk-systems/.github/blob/main/SECURITY.md).