diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..07bdda1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,47 @@ +name: Bug report +description: Report a defect in @code-first-agents/tool +title: "[Bug]: " +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. Please fill in the + sections below so the issue can be reproduced and fixed. + - type: input + id: version + attributes: + label: Package version + description: Which version of `@code-first-agents/tool` are you using? + placeholder: "0.1.3" + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: A minimal, self-contained way to trigger the bug. + placeholder: | + 1. Define a tool with ... + 2. Run `bun run tool.ts ...` + 3. See error + validations: + required: true + - type: textarea + id: expected-actual + attributes: + label: Expected vs. actual behavior + description: What did you expect to happen, and what actually happened? + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Runtime, OS, and Zod version. + placeholder: | + - Bun: 1.2.x + - OS: macOS 14 + - Zod: 4.0.x + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8167fe6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Code-First Agents spec & docs + url: https://code-first-agents.com + about: Read the pattern spec and documentation before opening an issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6778062 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,40 @@ +name: Feature request +description: Suggest an enhancement for @code-first-agents/tool +title: "[Feature]: " +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. Please describe the problem and your + proposal so the change can be evaluated against the spec. + - type: textarea + id: problem + attributes: + label: Problem + description: What problem or limitation are you running into? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the change or feature you'd like to see. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches or workarounds you've thought about. + validations: + required: false + - type: textarea + id: spec-alignment + attributes: + label: Spec alignment + description: >- + How does this fit the Code-First Agents pattern + (https://code-first-agents.com)? Note any tension with the tool contract. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..1e2f9a0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ +## Summary + + + +Closes # + +## Checklist + +- [ ] Linked to an issue (`Closes #NN` above) +- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, …) +- [ ] `bun test` passes +- [ ] `bunx biome check .` passes +- [ ] `bunx tsc --noEmit` passes +- [ ] `bun run build` succeeds +- [ ] Scope is focused — unrelated changes split into separate PRs diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..0994935 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,39 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + target-branch: main + open-pull-requests-limit: 5 + commit-message: + prefix: chore + labels: + - chore + groups: + npm-dependencies: + patterns: + - "*" + update-types: + - minor + - patch + - major + + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + target-branch: main + open-pull-requests-limit: 5 + commit-message: + prefix: chore + labels: + - chore + groups: + github-actions: + patterns: + - "*" + update-types: + - minor + - patch + - major diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7f4420b..854a3f4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,6 +10,11 @@ jobs: ci: name: Check & Test runs-on: ubuntu-latest + permissions: + contents: read + concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} steps: - name: Checkout diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f5c9a21 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,84 @@ +# 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 beogip@gmail.com. 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..7fcef09 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing + +Thanks for your interest in `@code-first-agents/tool`! This project implements the +[Code-First Agents](https://code-first-agents.com/patterns/deterministic-tools.html) +tool contract. Contributions are welcome — please read this guide first. + +> This project is maintained in spare time. Reviews and responses are best-effort, +> so thank you for your patience. + +## Issue-first workflow + +Please **open an issue before sending a pull request**. This keeps the work +lightweight and avoids duplicated or unwanted effort: + +1. Open an issue describing the bug or feature (use the issue forms). +2. Wait for a quick confirmation that the change is wanted and the approach is sound. +3. Fork, branch, and open a PR that links back to the issue. + +Small, obvious fixes (typos, broken links) can skip straight to a PR. + +## Development setup + +**Prerequisites:** [Bun](https://bun.sh) >= 1.0 + +```bash +git clone https://github.com/beogip/code-first-agents-tool.git +cd code-first-agents-tool +bun install +``` + +`bun install` runs the `prepare` script, which installs the +[Lefthook](https://github.com/evilmartians/lefthook) git hooks (pre-commit Biome +checks and commit-message validation). + +### Commands + +| Command | Description | +| ---------------- | --------------------------------- | +| `bun install` | Install deps + install git hooks | +| `bun run dev` | Re-run `src/index.ts` on change (watch mode) | +| `bun run build` | Compile to `dist/` (bun + tsc) | +| `bun test` | Run tests | +| `bun run lint` | Lint (Biome) | +| `bun run format` | Format (Biome, auto-fix) | +| `bun run check` | Lint + format (Biome, auto-fix) | + +Before opening a PR, make sure the pipeline is green: + +```bash +bun test +bunx biome check . +bunx tsc --noEmit +bun run build +``` + +## Commit messages + +This repository enforces [Conventional Commits](https://www.conventionalcommits.org/) +via the `commit-msg` git hook. Each commit message must start with one of these types: + +`feat` | `fix` | `docs` | `style` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert` + +Examples: + +``` +feat: add user authentication +fix(auth): handle token expiry +chore!: drop support for Node 16 +``` + +A `!` (or a `BREAKING CHANGE:` footer) marks a breaking change. Releases are +automated via semantic-release, so commit types directly drive version bumps: +`feat` → minor, `fix` → patch, breaking → major. + +## License + +This project is licensed under the [MIT License](LICENSE). By contributing, you agree +that your contributions are licensed under the same terms (inbound = outbound). diff --git a/README.md b/README.md index 7aea0a8..e1cd939 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ TypeScript implementation of the [Code-First Agents](https://code-first-agents.c **Key idea:** deterministic work lives in code (Tools), the LLM orchestrates judgment (Skills). This library is the Tool side. +> ℹ️ This project is maintained in spare time. Issues and pull requests are very +> welcome — please bear with best-effort response times. + ## Installation ```bash @@ -173,6 +176,28 @@ bun run examples/changeset.ts size --files 12 --additions 340 --deletions 50 `examples/changeset.ts` is one tool that demonstrates all three output levels (L1 data, L2 classification, L3 instructions). See [`examples/README.md`](examples/README.md) for the full walkthrough. +## API Reference + +All exports come from the package root (`@code-first-agents/tool`). See the +[spec](https://code-first-agents.com/patterns/deterministic-tools.html) for the +contract these implement. + +| Export | Kind | Purpose | +| ---------------------------- | -------- | ---------------------------------------------------------------------------------------- | +| `Tool` | class | The orchestrator. Construct with `{ name, description }`, register subcommands, dispatch. | +| `tool.subcommand(config)` | method | Register a subcommand with Zod `input`/`output` schemas and a `handler`. | +| `tool.run(argv)` | method | Parse CLI args, dispatch, print the JSON envelope, and `process.exit(0)`. | +| `tool.invoke(name, args)` | method | Call a subcommand in-process; returns the envelope object (useful in tests). | +| `l1Output(shape)` | function | Build an **L1 (data)** output schema — raw signals for the LLM to interpret. | +| `l2Output(classification, fields?)` | function | Build an **L2 (classification)** output schema — a discrete category to branch on. `classification` is any Zod type (commonly `z.enum(...)`). | +| `l3Output(fields?)` | function | Build an **L3 (instructions)** output schema — a verbatim procedure for the LLM. Fields are optional. | +| `ToolError` | class | Throw inside a handler for domain-specific errors: `new ToolError(code, message, detail?)`. Optional `detail` (string or object) is included in the error envelope's `detail` field. | +| `schema` (builtin) | command | Auto-registered. Emits JSON Schema for every subcommand. Not user-overridable. | +| `help` (builtin) | command | Auto-registered. Emits a human-readable subcommand listing. Not user-overridable. | + +Every successful result is the envelope `{ ok: true, message, ... }`; every error is +`{ ok: false, error, ... }` with exit code `0`. + ## Development **Prerequisites:** [Bun](https://bun.sh) >= 1.0 @@ -185,7 +210,7 @@ bun install | Command | Description | | ---------------- | ------------------------------- | -| `bun run dev` | Run with file watcher | +| `bun run dev` | Re-run `src/index.ts` on change (watch) | | `bun run build` | Compile to `dist/` (bun + tsc) | | `bun test` | Run tests | | `bun run check` | Lint + format (Biome, auto-fix) | diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b833e62 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +## Supported Versions + +This project follows a rolling-release model. Only the **latest published release** +of `@code-first-agents/tool` on npm receives security fixes. Please upgrade to the +most recent version before reporting a vulnerability. + +| Version | Supported | +| ------------------ | ------------------ | +| Latest release | :white_check_mark: | +| Any older release | :x: | + +## Reporting a Vulnerability + +**Please do not report security vulnerabilities through public GitHub issues.** + +The preferred channel is GitHub's [private vulnerability reporting][gh-advisory]: + +1. Go to the [**Security** tab][gh-advisory] of this repository. +2. Click **Report a vulnerability** and fill in the advisory form. + +This keeps the report private and links it directly to a draft security advisory. + +If you are unable to use private vulnerability reporting, email +**beogip@gmail.com** instead. + +When reporting, please include: + +- A description of the vulnerability and its impact. +- Steps to reproduce (a minimal proof of concept is ideal). +- The affected version and your environment (runtime, OS). + +You can expect an initial acknowledgement within a few days. Because this project +is maintained in spare time, response and fix timelines are best-effort. Coordinated +disclosure is appreciated — please give the maintainer a reasonable window to ship a +fix before any public disclosure. + +[gh-advisory]: https://github.com/beogip/code-first-agents-tool/security/advisories/new diff --git a/docs/specs/issue-22-add-missing-oss-hygiene-files.md b/docs/specs/issue-22-add-missing-oss-hygiene-files.md new file mode 100644 index 0000000..20b6bbd --- /dev/null +++ b/docs/specs/issue-22-add-missing-oss-hygiene-files.md @@ -0,0 +1,132 @@ +--- +issue_number: 22 +issue_title: "Add missing OSS hygiene files" +repo: "beogip/code-first-agents-tool" +labels: [P1, pre-launch] +plan_level: "lean" +depth: "medium" +branch_name: "chore/22-oss-hygiene-files" +created_at: "2026-06-07T16:41:42Z" +updated_at: "2026-06-07T17:05:00Z" +--- + +# Implementation Plan: #22 — Add missing OSS hygiene files + +> Refined via a grill-me interview (8 sequential decisions). Scope was expanded beyond the +> literal issue to include CODE_OF_CONDUCT.md and PULL_REQUEST_TEMPLATE.md per maintainer choice. + +## Decisions (grill-me) +| # | Decision | Choice | +|---|----------|--------| +| 1 | Scope | Issue's 6 items **+ CODE_OF_CONDUCT.md + PULL_REQUEST_TEMPLATE.md** | +| 2 | CI concurrency | Job-level on `ci`; `cancel-in-progress: ${{ github.event_name == 'pull_request' }}` (cancel on PRs, never on main → never skips a release) | +| 3 | Dependabot | Group **everything incl. majors**, weekly, `npm` + `github-actions`, target `main`, label `chore`, `commit-message.prefix: chore`, `open-pull-requests-limit: 5` | +| 4 | SECURITY channel | **Enable** GitHub private vulnerability reporting via `gh api`, cite it as primary + beogip@gmail.com fallback; Supported Versions = latest release only | +| 5 | Issue forms | bug → title `[Bug]: ` + label `bug`; feature → `[Feature]: ` + label `enhancement`; `config.yml` `blank_issues_enabled: false` + contact_link to spec (Discussions are disabled) | +| 6 | CONTRIBUTING | Issue-first (lightweight), Conventional Commits, bun commands, `bun install` installs lefthook, inbound=outbound MIT | +| 7 | README | Maintenance note near the intro; concise `## API Reference` after Usage (export signatures + one-liner + spec link) | +| 8 | Delivery | One PR on `chore/22-oss-hygiene-files`, multiple commits grouped by area (`docs:`, `ci:`, `chore:`) — all non-release types, so semantic-release does not bump | + +## Files +| # | Action | Path | Purpose | +|---|--------|------|---------| +| 1 | create | `SECURITY.md` | Disclosure policy. Supported Versions = only the latest published release. Report via GitHub private vulnerability reporting (primary) + beogip@gmail.com (fallback). | +| 2 | create | `CONTRIBUTING.md` | Issue-first flow, full Conventional Commit type list (from `lefthook.yml`), bun dev commands (`install/dev/build/test/lint/format/check`), note that `bun install` installs lefthook hooks, inbound=outbound MIT. | +| 3 | create | `CODE_OF_CONDUCT.md` | Contributor Covenant v2.1, enforcement contact = beogip@gmail.com. | +| 4 | create | `.github/ISSUE_TEMPLATE/config.yml` | `blank_issues_enabled: false` + contact_link to https://code-first-agents.com. | +| 5 | create | `.github/ISSUE_TEMPLATE/bug_report.yml` | YAML form, `title: "[Bug]: "`, `labels: [bug]`, fields id'd, ≥1 required (version, repro, expected/actual, environment). | +| 6 | create | `.github/ISSUE_TEMPLATE/feature_request.yml` | YAML form, `title: "[Feature]: "`, `labels: [enhancement]`, fields id'd, ≥1 required (problem, proposal, alternatives, spec alignment). | +| 7 | create | `.github/PULL_REQUEST_TEMPLATE.md` | Short checklist: linked issue, Conventional Commit title, tests/lint/build green, scope of change. | +| 8 | create | `.github/dependabot.yml` | v2; `npm` + `github-actions`, weekly, `groups` covering all update types incl. major, `open-pull-requests-limit: 5`, `commit-message.prefix: chore`, `labels: [chore]`. | +| 9 | modify | `.github/workflows/ci.yml` | Add `permissions: contents: read` to the `ci` job; add **job-level** `concurrency` under `jobs.ci` (group `ci-${{ github.ref }}`, `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`). Release job byte-identical. | +| 10 | modify | `README.md` | Add a "maintained in spare time" note near the intro + `## API Reference` after Usage (`Tool`, `.run`/`.invoke`, `l1/l2/l3Output`, `ToolError`, `schema`/`help` builtins, link to spec). | + +**Non-file action (implementation phase):** enable GitHub private vulnerability reporting — +`gh api -X PUT repos/beogip/code-first-agents-tool/private-vulnerability-reporting` — before SECURITY.md cites it. Outward repo-settings change, authorized by maintainer (grill 4). + +## Codebase Context +- **Conventional Commit types** from the `commit-msg` regex in `lefthook.yml`: `feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert`. CONTRIBUTING.md must mirror this exactly. +- **Dev scripts** (`package.json`): `dev, build, test, lint, format, check`; `prepare` runs `lefthook install` on `bun install`. +- **Existing labels**: `bug`, `enhancement`, `documentation`, `chore`, `api`, `packaging`, `P0/P1/P2`, `pre-launch` exist. There is **no** `dependencies` label → Dependabot uses `chore`. +- **Discussions disabled** → `config.yml` contact_link points to the spec site, not Discussions. +- `.github/workflows/ci.yml`: jobs `ci` (no permissions/concurrency today) and `release` (`semantic-release` on push to `main`, `needs: ci`, full permissions). Concurrency scoped to `ci` so a fast second push to main never cancels a release. +- `.github/workflows/claude.yml` already uses concurrency (reference only; its group is per-issue). +- **Dependabot ecosystems**: `npm` (`package.json` + `bun.lock`) and `github-actions` (`ci.yml`, `claude.yml`). +- **Public exports** (CLAUDE.md): `Tool` class with `.run()`/`.invoke()`, `l1Output`/`l2Output`/`l3Output`, `ToolError`, builtins `schema`/`help`. +- **Package**: `@code-first-agents/tool` v0.1.3, MIT © 2026 Juan Gipponi, homepage code-first-agents.com, runtime Bun, peer dep Zod v4. + +## Steps +1. **Enable private vulnerability reporting** via `gh api -X PUT repos/beogip/code-first-agents-tool/private-vulnerability-reporting`. **Done when:** the API call returns success (or already-enabled), confirmed by `gh api repos/beogip/code-first-agents-tool/private-vulnerability-reporting`. +2. **Create SECURITY.md.** **Done when:** has "Reporting a Vulnerability" (GitHub private reporting primary + email fallback) and "Supported Versions" stating only the latest published release is supported. +3. **Create CONTRIBUTING.md.** **Done when:** lists every Conventional type matching `lefthook.yml`, the bun dev commands, the issue-first flow, the lefthook-via-`bun install` note, and an inbound=outbound MIT statement. +4. **Create CODE_OF_CONDUCT.md.** **Done when:** Contributor Covenant text present with beogip@gmail.com as the enforcement contact. +5. **Create the 3 ISSUE_TEMPLATE files.** **Done when:** all parse as YAML; `config.yml` has `blank_issues_enabled: false` + a contact_link; each form has `name`/`description`/`title`/`labels`/`body`, every body field has an `id`, ≥1 has `validations.required: true`; bug uses `[Bug]: `+`bug`, feature uses `[Feature]: `+`enhancement`. +6. **Create .github/PULL_REQUEST_TEMPLATE.md.** **Done when:** contains a checklist covering linked issue, Conventional Commit title, and tests/lint/build green. +7. **Create .github/dependabot.yml.** **Done when:** `version: 2`, two `updates` (`npm` + `github-actions`) weekly, each with a `groups` block matching all `update-types` (incl. major), `open-pull-requests-limit: 5`, `commit-message.prefix: chore`, `labels: [chore]`, `target-branch: main`. +8. **Modify .github/workflows/ci.yml.** **Done when:** `jobs.ci` has `permissions: contents: read` and a nested `concurrency` block with `cancel-in-progress: ${{ github.event_name == 'pull_request' }}`; no top-level `concurrency` key; `release` job byte-identical; file parses as valid YAML. +9. **Modify README.md.** **Done when:** a "maintained in spare time" note exists near the intro and a `## API Reference` section after Usage documents the public exports with one-line purposes + a spec link. + +## Interfaces +N/A — all artifacts are Markdown/YAML. No TypeScript data structures introduced. + +## Function Design +N/A — no functions added or modified; documentation/configuration only. No `src/` changes. + +## Acceptance Criteria (EARS) +- **AC-1.** The repository shall contain a root `SECURITY.md` describing vulnerability reporting (GitHub private reporting + email) and supported versions. +- **AC-2.** The repository shall contain `CONTRIBUTING.md` documenting the Conventional Commit types, the bun dev/test/build commands, the issue-first flow, and the inbound=outbound license. +- **AC-3.** The repository shall contain `CODE_OF_CONDUCT.md` with a reachable enforcement contact. +- **AC-4.** The repository shall contain `.github/ISSUE_TEMPLATE/` with a bug report and a feature request as YAML issue forms (with auto-labels and title prefixes) plus a `config.yml` that disables blank issues. +- **AC-5.** The repository shall contain `.github/PULL_REQUEST_TEMPLATE.md` with a contributor checklist. +- **AC-6.** The repository shall contain `.github/dependabot.yml` covering the `npm` and `github-actions` ecosystems weekly, grouping all update types, with `commit-message.prefix: chore`. +- **AC-7.** When the ci workflow runs, the `ci` job shall declare `permissions: contents: read`. +- **AC-8.** When a new ci run starts for the same ref on a **pull_request**, the workflow shall cancel the superseded ci run; when the event is a **push to main**, it shall NOT cancel the in-progress ci run (so `release` is never skipped). +- **AC-9.** The README shall include an API Reference section and a "maintained in spare time" note near the intro. +- **AC-10.** GitHub private vulnerability reporting shall be enabled for the repository. + +## Out of Scope +- `FUNDING.yml` — not requested. +- Top-level `permissions: read-all` workflow default — issue scopes hardening to the `ci` job; release job keeps its explicit block. +- Pinning ci.yml actions to commit SHAs or pinning `bun-version` — Dependabot (github-actions) will surface action updates. +- Any source-code or test-code changes under `src/` or `tests/`. + +## Edge Cases + Error Handling +| # | Scenario | Source | Handling | +|---|----------|--------|----------| +| 1 | Fast second push to main cancels the `ci` of an earlier commit → its `release` never runs | [from issue] / [inferred] | `cancel-in-progress` gated to `pull_request` only; main pushes never cancel (AC-8). | +| 2 | Dependabot commits must satisfy Conventional Commits | [inferred] | `commit-message.prefix: chore` → `chore(deps): …`. lefthook runs locally only, so Dependabot/CI unaffected regardless. | +| 3 | Grouping majors can bundle a breaking bump into the weekly PR | [inferred] | Accepted by maintainer (grill 3); the grouped PR is reviewed before merge, and CI must pass first. | +| 4 | Invalid YAML breaks GitHub features silently | [inferred] | Parse-validate every new/modified YAML file. | +| 5 | SECURITY.md cites private reporting while the toggle is off | [inferred] | Step 1 enables it via `gh api` before the doc cites it (AC-10). | +| 6 | Discussions disabled → a contact_link to Discussions would 404 | [inferred] | config.yml contact_link points to the spec site instead. | +| 7 | `contents: read` too restrictive for checkout `fetch-depth: 0` | [inferred] | Sufficient for read-only checkout; future write-needing steps must elevate; release job unaffected. | +| 8 | CONTRIBUTING type list drifts from the hook | [inferred] | Cross-check against `lefthook.yml`; grep-verify every type string present. | +| 9 | Issue forms parse as YAML but fail GitHub's form schema | [inferred] | Structural-validate: each body field has `id`, ≥1 `validations.required: true`, top-level `name`/`description`/`body` present. | + +## Done Criteria per Feature +| Feature | Done when | +|---------|-----------| +| SECURITY.md + private reporting | AC-1, AC-10 | +| CONTRIBUTING.md | AC-2 | +| CODE_OF_CONDUCT.md | AC-3 | +| Issue templates | AC-4 | +| PR template | AC-5 | +| Dependabot | AC-6 | +| CI hardening | AC-7, AC-8 | +| README | AC-9 | + +## Risks +- **Concurrency cancels a release** → gated to PRs only (Edge 1 / AC-8); assert no top-level `concurrency`. +- **Grouped major bump breaks the weekly PR** → CI gates the PR; review before merge (Edge 3). +- **YAML syntax/schema errors** → parse + structural validation (Edge 4, 9). +- **Security contact goes stale** → email is fallback; repo-tied private reporting is primary (enabled in Step 1). +- **`gh api` private-reporting call fails** (permissions) → surface the error; SECURITY.md still ships with email fallback, re-run the toggle later. + +## Test Strategy +- No unit tests (docs/config only). Verify the pipeline stays green: `bun test`, `bunx biome check .`, `bunx tsc --noEmit`, `bun run build`. +- Parse-validate every new/modified YAML file (issue forms, dependabot.yml, ci.yml). +- Structural-validate issue forms: top-level `name`/`description`/`body`; each field has `id`; ≥1 `validations.required: true`; correct `title` prefix + `labels`. +- Assert ci.yml `jobs.ci.concurrency` present, root `concurrency` absent, `release` job unchanged (scoped `git diff`). +- grep-verify: CONTRIBUTING.md contains every Conventional type; dependabot.yml `commit-message.prefix` is `chore`. +- Confirm private vulnerability reporting is enabled via `gh api`. +- Manual (best-effort, post-merge): GitHub renders the issue forms; ci job shows read-only permission.