@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/docs/superpowers/plans/2026-10-01-ci.md

@@ -1,350 +0,0 @@
-# CI Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** GitHub Actions runs the typecheck, unit tests, browser tests (Firefox) and Trunk's code quality checks on every push to `main` and every pull request, using bun.
-
-**Architecture:** One workflow, `.github/workflows/ci.yml`, with four parallel jobs on `ubuntu-latest`. The three code jobs share a local composite action (`.github/actions/setup`) that installs bun 1.3.0, Node 26 and the locked dependencies. The `trunk` job uses `trunk-io/trunk-action@v1` with the repository's committed `.trunk/trunk.yaml`, checking only changed files.
-
-**Tech Stack:** GitHub Actions, bun 1.3.0, Node 26, tsx + Node's test runner (existing scripts), Firefox (preinstalled on the runner), Trunk CLI 1.25.0.
-
-**Spec:** `docs/superpowers/specs/2026-10-01-ci-design.md`
-
-## Global Constraints
-
-- bun, not npm: `bun install --frozen-lockfile`, `bun run <script>`, `bunx <bin>`. Never `npm`/`npx` in the workflow. Never replace `bun run test` with `bun test`.
-- `oven-sh/setup-bun@v2` with `bun-version: 1.3.0`; `actions/setup-node@v4` with `node-version: 26`; `actions/checkout@v4`; `actions/upload-artifact@v4`; `trunk-io/trunk-action@v1`.
-- Triggers: `push` to `main` and `pull_request`. `concurrency: { group: ci-${{ github.ref }}, cancel-in-progress: true }`. Workflow `permissions: contents: read`; the `trunk` job adds `checks: write`.
-- Job ids, names and timeouts: `typecheck` "Typecheck" 5 min; `unit` "Unit tests" 10 min; `browser` "Browser tests (Firefox)" 15 min; `trunk` "Code quality (Trunk)" 15 min. All `runs-on: ubuntu-latest`.
-- Browser job: a separate `firefox --version` step before `bun run test:browser`; on failure upload `logs/` and `result/` as artifact `browser-test-logs`, `retention-days: 7`, `if-no-files-found: ignore`.
-- Trunk checks changed files only (the action's default); no `--all`.
-- No changes to `src/`, `package.json` scripts or `bun.lock`.
-- Never run `bun run dev` / `src/index.ts` / `src/tests/index.spec.ts`: the example spec submits a real contact form.
-- A Trunk pre-commit hook formats staged files and a pre-push hook runs `trunk check`; let them run, and commit what they format.
-- Commit messages end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`. Stage only the files a task names; never `git add -A`.
-
-## Review Focus
-
-1. **`bun.lock` out of sync with `package.json`** — CI must fail at install with bun's frozen-lockfile error, not later with a missing module. Pinned in Task 2 Step 4 (local `bun install --frozen-lockfile` run, the exact command CI uses).
-2. **A browser run that hangs** — the job must stop at its `timeout-minutes`, not after GitHub's 6-hour default. Pinned in Task 2 Step 3 (actionlint check) and Step 6 (grep for every job's timeout).
-3. **Trunk's own tool folders committed by accident** (`.trunk/tools`, `.trunk/logs`, `.trunk/out` …) — they are large and machine-specific. Pinned in Task 1 Step 2 (`git check-ignore` on each).
-4. **Trunk's yamllint rejecting the workflow's `on:` key** (the `truthy` rule) — the `trunk` job would fail on its own workflow. Pinned in Task 3 Step 3 (local `trunk check` on the workflow, with the exact config fix if it fires).
-5. **A red CI run diagnosed by guessing** — every failing job on GitHub is read from its log (and the browser artifact) before any fix. Pinned in Task 4 Steps 3–4.
-
----
-
-## File Structure
-
-| File                               | Status                                | Responsibility                                                        |
-| ---------------------------------- | ------------------------------------- | --------------------------------------------------------------------- |
-| `.trunk/trunk.yaml`                | commit (exists, untracked)            | Trunk CLI version, linters, hooks — shared by local hooks and CI      |
-| `.trunk/.gitignore`                | commit (exists, untracked)            | keeps Trunk's caches out of git                                       |
-| `.trunk/configs/svgo.config.mjs`   | commit (exists, untracked)            | svgo linter config                                                    |
-| `.github/actions/setup/action.yml` | create                                | composite action: bun 1.3.0, Node 26, `bun install --frozen-lockfile` |
-| `.github/workflows/ci.yml`         | create                                | triggers, concurrency, the four jobs                                  |
-| `.trunk/configs/.yamllint.yaml`    | create only if Task 3 Step 3 needs it | yamllint rules for GitHub workflow syntax                             |
-
----
-
-### Task 1: Commit the Trunk configuration
-
-**Files:**
-
-- Commit: `.trunk/trunk.yaml`, `.trunk/.gitignore`, `.trunk/configs/svgo.config.mjs`
-
-**Interfaces:**
-
-- Produces: a tracked `.trunk/trunk.yaml` that the `trunk` job (Task 3) reads.
-
-- [ ] **Step 1: See what Trunk would add**
-
-Run: `git status --short --untracked-files=all .trunk`
-Expected: exactly these three lines (Trunk's `.gitignore` hides the rest):
-
-```text
-?? .trunk/.gitignore
-?? .trunk/configs/svgo.config.mjs
-?? .trunk/trunk.yaml
-```
-
-If more files show up, stop and report them instead of committing.
-
-- [ ] **Step 2: Check Trunk's caches stay ignored**
-
-Run: `for d in actions logs notifications out plugins tools; do git check-ignore -q .trunk/$d && echo "ignored $d" || echo "NOT IGNORED $d"; done`
-Expected: six `ignored …` lines.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add .trunk/trunk.yaml .trunk/.gitignore .trunk/configs/svgo.config.mjs
-git commit -m "chore: commit Trunk configuration
-
-The same trunk.yaml drives the local pre-commit/pre-push hooks and
-the CI code quality job.
-
-Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
-```
-
-Expected: the pre-commit hook may format the files; the commit succeeds.
-
----
-
-### Task 2: Workflow with typecheck, unit and browser jobs
-
-**Files:**
-
-- Create: `.github/actions/setup/action.yml`
-- Create: `.github/workflows/ci.yml`
-
-**Interfaces:**
-
-- Consumes: package scripts `test` and `test:browser` (unchanged), `bun.lock`.
-- Produces: `.github/workflows/ci.yml` with top-level `name`, `on`, `concurrency`, `permissions` and a `jobs:` map containing `typecheck`, `unit`, `browser`. Task 3 appends a `trunk` job to that map.
-
-- [ ] **Step 1: Write the shared setup action**
-
-Create `.github/actions/setup/action.yml`:
-
-```yaml
-name: Setup
-description: Install bun, Node and the locked dependencies
-
-runs:
-  using: composite
-  steps:
-    - uses: oven-sh/setup-bun@v2
-      with:
-        bun-version: 1.3.0
-    # The test scripts run tsx on Node's test runner, which needs Node 22+ (fs/promises glob)
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 26
-    - name: Install dependencies
-      shell: bash
-      run: bun install --frozen-lockfile
-```
-
-- [ ] **Step 2: Write the workflow**
-
-Create `.github/workflows/ci.yml`:
-
-```yaml
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  typecheck:
-    name: Typecheck
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Typecheck
-        run: bunx tsc --noEmit -p .
-
-  unit:
-    name: Unit tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Unit tests
-        run: bun run test
-
-  browser:
-    name: Browser tests (Firefox)
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@v4
-      - uses: ./.github/actions/setup
-      - name: Firefox version
-        run: firefox --version
-      - name: Browser tests
-        run: bun run test:browser
-      - name: Upload logs
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: browser-test-logs
-          path: |
-            logs/
-            result/
-          retention-days: 7
-          if-no-files-found: ignore
-```
-
-- [ ] **Step 3: Lint the workflow with actionlint**
-
-Run: `docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest -color`
-Expected: no output, exit 0. (actionlint resolves the local `./.github/actions/setup` action and checks `timeout-minutes`, expressions and action inputs.) If Docker is not running, say so in the report and rely on Step 5 plus the GitHub run in Task 4.
-
-- [ ] **Step 4: Run each job's commands locally with bun**
-
-Run, in order, and record each exit code:
-
-```bash
-bun install --frozen-lockfile
-bunx tsc --noEmit -p .
-bun run test
-perl -e 'alarm 900; exec @ARGV' bun run test:browser
-```
-
-Expected: install reports no changes; tsc prints nothing; `bun run test` ends with `ℹ fail 0`; `bun run test:browser` ends with `ℹ fail 0`. After the browser run, `ps -Ao command | grep browsers/profiles/firefox | grep -v grep` prints nothing. If `result/report.json` changed, restore it: `git checkout -- result/report.json`.
-
-- [ ] **Step 5: Trunk-check the new files**
-
-Run: `trunk check .github/actions/setup/action.yml .github/workflows/ci.yml`
-Expected: `No issues`, or only formatting that `trunk fmt` fixes (then run `trunk fmt` on the two files and re-check). Any yamllint `truthy` finding on `on:` is handled in Task 3 Step 3, not here — note it in the report.
-
-- [ ] **Step 6: Confirm every job has a timeout**
-
-Run: `grep -c "timeout-minutes" .github/workflows/ci.yml`
-Expected: `3`.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add .github/actions/setup/action.yml .github/workflows/ci.yml
-git commit -m "ci: typecheck, unit and browser tests on GitHub Actions
-
-Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: Trunk code quality job
-
-**Files:**
-
-- Modify: `.github/workflows/ci.yml` (append to `jobs:`)
-- Create (only if Step 3 requires it): `.trunk/configs/.yamllint.yaml`
-
-**Interfaces:**
-
-- Consumes: the `jobs:` map from Task 2; `.trunk/trunk.yaml` from Task 1.
-
-- [ ] **Step 1: Append the job**
-
-Add the `trunk` job at the end of `.github/workflows/ci.yml`, inside `jobs:`, indented like `browser:` (two spaces). Shown here under its parent so the indentation is unambiguous — add only the `trunk:` block:
-
-```yaml
-jobs:
-  # typecheck, unit and browser from Task 2 stay above, unchanged
-  trunk:
-    name: Code quality (Trunk)
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: read
-      checks: write
-    steps:
-      - uses: actions/checkout@v4
-      # Checks only what the PR or push changed; linters come from .trunk/trunk.yaml
-      - uses: trunk-io/trunk-action@v1
-```
-
-- [ ] **Step 2: Lint the workflow with actionlint**
-
-Run: `docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest -color`
-Expected: no output, exit 0.
-
-- [ ] **Step 3: Run Trunk on the workflow the way CI will**
-
-Run: `trunk check .github/workflows/ci.yml .github/actions/setup/action.yml .trunk/trunk.yaml`
-Expected: `No issues`.
-
-If yamllint reports `truthy value should be one of [false, true]` on the `on:` line, create `.trunk/configs/.yamllint.yaml`:
-
-```yaml
-extends: default
-rules:
-  # GitHub Actions' trigger key is `on:`
-  truthy:
-    allowed-values: ["true", "false"]
-    check-keys: false
-  document-start: disable
-  line-length: disable
-```
-
-then re-run the same `trunk check` command. Expected: `No issues`. Any other finding: fix the workflow (not the linter config) and say what you changed.
-
-- [ ] **Step 4: Confirm every job has a timeout**
-
-Run: `grep -c "timeout-minutes" .github/workflows/ci.yml`
-Expected: `4`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add .github/workflows/ci.yml
-# only if Step 3 created it:
-git add .trunk/configs/.yamllint.yaml
-git commit -m "ci: run Trunk code quality checks on changed files
-
-Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: First run on GitHub
-
-**Files:** none (verification; fixes found here go back to the task that owns the file).
-
-- [ ] **Step 1: Push the branch**
-
-```bash
-git push -u origin ci/github-actions
-```
-
-Expected: the pre-push hook runs `trunk check` and passes; the push succeeds.
-
-- [ ] **Step 2: Open the PR against the PR #6 branch**
-
-```bash
-gh pr create --base feat/test-api-alignment --head ci/github-actions \
-  --title "ci: typecheck, unit, browser and Trunk checks on GitHub Actions" \
-  --body-file <(printf '%s\n' \
-    "Adds GitHub Actions CI (spec: docs/superpowers/specs/2026-10-01-ci-design.md)." "" \
-    "- **typecheck**: \`bunx tsc --noEmit -p .\`" \
-    "- **unit**: \`bun run test\`" \
-    "- **browser**: \`bun run test:browser\` on the runner's Firefox; logs uploaded on failure" \
-    "- **trunk**: Trunk checks on changed files (\`.trunk/trunk.yaml\` is now committed)" "" \
-    "Based on #6; GitHub retargets this PR to \`main\` when #6 merges." "" \
-    "🤖 Generated with [Claude Code](https://claude.com/claude-code)")
-```
-
-Expected: a PR URL.
-
-- [ ] **Step 3: Watch the run**
-
-```bash
-gh run watch "$(gh run list --branch ci/github-actions --workflow CI --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status
-```
-
-Expected: all four jobs succeed.
-
-- [ ] **Step 4: If a job fails, read before fixing**
-
-```bash
-RUN=$(gh run list --branch ci/github-actions --workflow CI --limit 1 --json databaseId --jq '.[0].databaseId')
-gh run view "$RUN" --log-failed | tail -100
-# browser job only:
-gh run download "$RUN" -n browser-test-logs -D /tmp/browser-test-logs
-```
-
-Report the failing job, the error lines and the Firefox version from the `Firefox version` step. Fix only with evidence from the log; a Firefox-version-specific failure is reported (the spec's mitigation is a follow-up pin), not patched blindly.