@ebalzan/ci 0.0.0-stage → 3.0.0

package/docs/AUTO_WORK_ITEMS_WORKFLOW.md

@@ -0,0 +1,305 @@
+# Auto Work Items Workflow Guide
+
+This document explains the automated branch workflow every repo using ebalzan/ci runs.
+
+## What It Does
+
+When you push to any branch other than `main` or `dev`, the workflow automatically:
+
+1. Creates or reuses a tracking **Issue** for the branch.
+2. Creates or reuses a ready-for-review **PR** from the branch to `dev` (the `base-branch` input).
+3. Links the PR to the issue (`Closes #<issue-number>`).
+4. Applies the exact label set to both issue and PR (removes stale extras).
+5. Applies milestone (if configured).
+6. Adds both issue and PR to GitHub Project (v2) (if `AUTO_PROJECT_NUMBER` is set).
+7. Assigns issue and PR to the latest commit author (if resolvable to a GitHub user).
+8. Updates project fields: `Start date`, `Target date`, `Priority`, `Estimate`, and `Size`.
+
+The process is idempotent and safe to run on every push.
+
+## Workflow Files
+
+- Reusable workflow: `.github/workflows/auto-work-items.yml` (this repo)
+- Composite action it runs: `actions/auto-work-items/action.yml`
+- Caller in each repo: `.github/workflows/auto-pr.yml` — only the trigger
+  (`push`, `branches-ignore: [main, dev]`), the permissions, and the `uses:` line.
+
+## Script Architecture
+
+The workflow is orchestrated by `actions/github-script`, but all logic is implemented in TypeScript modules.
+
+Source of truth:
+
+- `actions/auto-work-items/src/index.ts` (orchestrator)
+- `actions/auto-work-items/src/issue.ts`
+- `actions/auto-work-items/src/pr.ts`
+- `actions/auto-work-items/src/project.ts`
+- `actions/auto-work-items/src/config.ts`
+- `actions/auto-work-items/src/labels.ts`
+- `actions/auto-work-items/src/milestone.ts`
+- `actions/auto-work-items/src/utils.ts`
+- `actions/auto-work-items/src/types.ts`
+
+Runtime files used by GitHub Actions:
+
+- `actions/auto-work-items/dist/*.js`
+
+Why both exist:
+
+- `actions/github-script` executes JavaScript, not `.ts` directly.
+- We keep typed source in `src/` and compile to `dist/` for runtime.
+
+## Trigger Rules
+
+The caller (`auto-pr.yml`) runs it on:
+
+- `push` to any branch except `main` and `dev`
+- tags are ignored
+
+```yaml
+on:
+  push:
+    branches-ignore:
+      - main
+      - dev
+    tags-ignore:
+      - '**'
+```
+
+The reusable workflow also skips `chore/renovate-*` branches, whose PR
+Renovate owns.
+
+## Concurrency and Idempotency
+
+Concurrency is enabled per branch:
+
+- group: `auto-work-items-${{ github.ref }}`
+- in-progress run for the same branch is canceled
+
+Idempotency is handled by a marker in issue/PR bodies:
+
+- `Marker: auto-work-item:<branch-name>`
+
+If an issue/PR already exists for that branch, it is reused and updated.
+
+## End-to-End Flow
+
+1. Parse branch name and derive `branchType` (`feat`, `fix`, `chore`, etc.; any other prefix fails the run).
+2. Build titles, body content, marker, labels, and priority decision.
+3. Ensure labels exist and sync color/description to expected values.
+4. Resolve milestone by number (preferred) or exact title.
+5. Upsert tracking issue.
+6. Upsert PR (opened ready for review, not draft) to `AUTO_BASE_BRANCH` (`dev`).
+7. Ensure PR includes `Closes #<issue-number>`.
+8. Add issue and PR to configured Project v2.
+9. Resolve project fields by name (`Start date`, `Target date`, `Priority`, `Estimate`, `Size`).
+10. Set date fields and metadata fields on both items.
+11. Emit workflow notice with final issue/PR numbers.
+
+## Branch Type Mapping
+
+Current branch-type defaults:
+
+| Branch Type | PR Prefix | Type Label | Default Priority | Label Color |
+| ----------- | --------- | ---------- | ---------------- | ----------- |
+| `feat`      | `feat`    | `feat`     | `P2`             | `1D76DB`    |
+| `fix`       | `fix`     | `fix`      | `P1`             | `D73A4A`    |
+| `docs`      | `docs`    | `docs`     | `P3`             | `5319E7`    |
+| `style`     | `style`   | `style`    | `P4`             | `C2E0C6`    |
+| `refact`    | `refact`  | `refact`   | `P2`             | `FBCA04`    |
+| `perf`      | `perf`    | `perf`     | `P1`             | `F9D0C4`    |
+| `test`      | `test`    | `test`     | `P3`             | `0E8A16`    |
+| `build`     | `build`   | `build`    | `P3`             | `0052CC`    |
+| `ci`        | `ci`      | `ci`       | `P3`             | `0052CC`    |
+| `chore`     | `chore`   | `chore`    | `P4`             | `BFD4F2`    |
+| `revert`    | `revert`  | `revert`   | `P1`             | `E99695`    |
+
+These are the only accepted branch types. Any other prefix (`feature/`, `hotfix/`,
+`refactor/`, …) fails the run with no issue or PR created — rename the branch.
+
+## Labels Applied
+
+Always applied labels:
+
+- type label from branch type (for example `feat`, `refact`, `chore`)
+
+Optional extra labels from variables:
+
+- `AUTO_ISSUE_LABELS` (CSV)
+- `AUTO_PR_LABELS` (CSV)
+
+Note:
+
+- Reserved type labels (for example `feat`, `fix`, `chore`, `ci`) are controlled by branch type and filtered out from `AUTO_ISSUE_LABELS` and `AUTO_PR_LABELS`.
+
+Label color behavior:
+
+- Known labels (type labels) use configured fixed colors.
+- Custom/extra labels use a deterministic non-gray palette.
+- `priority:P0` through `priority:P4` map to priority-specific colors.
+- Existing labels are updated when current color/description drift from expected values.
+
+## Milestone Behavior
+
+Milestone resolution order:
+
+1. `AUTO_MILESTONE_NUMBER` (numeric)
+2. `AUTO_MILESTONE_TITLE` (exact case-insensitive title match)
+3. none only when both variables are unset
+
+When resolved, milestone is set on both issue and PR.
+A milestone that cannot be found (or is closed) produces a warning, not a
+failure.
+
+Setup guidance:
+
+- If you want stable pinning, set `AUTO_MILESTONE_NUMBER`.
+- If you want name-based matching, set `AUTO_MILESTONE_TITLE` and leave `AUTO_MILESTONE_NUMBER` unset.
+- Do not keep a stale `AUTO_MILESTONE_NUMBER`; it takes precedence over title.
+
+## Project v2 Behavior
+
+Project selection:
+
+- owner: `AUTO_PROJECT_OWNER` (defaults to repo owner)
+- project number: `AUTO_PROJECT_NUMBER` — unset means no board: the issue and
+  PR are still created, and the board step is skipped
+
+Field lookup is by name (case-insensitive):
+
+- `Start date`
+- `Target date`
+- `Priority` (single-select)
+- `Estimate`
+- `Size`
+
+There are no custom field-name variables in the current implementation.
+
+Date values:
+
+- Start = `today + AUTO_START_DATE_OFFSET_DAYS` (default `0`)
+- Target = `today + AUTO_TARGET_DATE_OFFSET_DAYS` (default `7`)
+
+Priority value:
+
+1. `AUTO_PRIORITY_MAP_JSON[branchType]`
+2. `AUTO_DEFAULT_PRIORITY`
+3. branch default from mapping table
+
+If the requested priority is unavailable in the project field options, the workflow falls back to the nearest available `P<number>` option.
+
+Size value:
+
+1. `AUTO_SIZE_MAP_JSON[branchType]`
+2. `AUTO_DEFAULT_SIZE`
+3. fallback: `M`
+
+Estimate value:
+
+1. `AUTO_ESTIMATE_MAP_JSON[branchType]`
+2. `AUTO_DEFAULT_ESTIMATE`
+3. fallback: `1`
+
+## Strict vs Non-Strict Metadata Mode
+
+`AUTO_STRICT_METADATA` controls failure behavior for project metadata sync.
+
+- `true` (default): with a board configured, a missing project, field or
+  option fails the workflow.
+- `false`: the same problems only emit warnings.
+- Without `AUTO_PROJECT_NUMBER` neither applies: the board is skipped.
+
+This is useful when metadata is mandatory for your process.
+
+## Variables and Secret Reference
+
+`auto-work-items.yml` passes the caller repo's variables whole
+(`REPO_VARS_JSON: ${{ toJSON(vars) }}`) — the repo's `.github/actions.env`,
+pushed by `ebalzan-ci bootstrap` — and the action takes their `AUTO_*` keys. A
+knob the repo leaves unset is filled from `config/actions.env` at the action's
+ref (`src/sharedVars.ts`), else the code default applies. So a knob is set in
+the repo's file (then the bootstrap) or in `config/actions.env` (then a release
+that moves the major tag) — never in the workflow. Defaults and meanings:
+[CONFIGURATION.md](CONFIGURATION.md#actions-variables).
+
+- `AUTO_BASE_BRANCH` (from the `base-branch` input, default `dev`)
+- `AUTO_ISSUE_LABELS`
+- `AUTO_PR_LABELS`
+- `AUTO_MILESTONE_NUMBER`
+- `AUTO_MILESTONE_TITLE`
+- `AUTO_PROJECT_OWNER`
+- `AUTO_PROJECT_NUMBER` (repo variable — one board per repo)
+- `AUTO_DEFAULT_PRIORITY`
+- `AUTO_PRIORITY_MAP_JSON`
+- `AUTO_DEFAULT_SIZE`
+- `AUTO_SIZE_MAP_JSON`
+- `AUTO_DEFAULT_ESTIMATE`
+- `AUTO_ESTIMATE_MAP_JSON`
+- `AUTO_START_DATE_OFFSET_DAYS`
+- `AUTO_TARGET_DATE_OFFSET_DAYS`
+- `AUTO_STRICT_METADATA` (defaults to `true` if unset)
+- `AUTO_DESCRIBE_MODEL`, `AUTO_DESCRIBE_EFFORT` (describe.ts)
+- secret `ANTHROPIC_API_KEY` (describe.ts; without it the body is a stub)
+
+Notes:
+
+- Without `AUTO_PROJECT_NUMBER` the board is skipped, whatever `AUTO_STRICT_METADATA` says.
+- `GH_PROJECT_TOKEN` is recommended when `github.token` cannot write Project v2 metadata.
+
+## Permissions Used
+
+Workflow permissions (the caller must grant them; a reusable workflow cannot
+raise its caller's):
+
+- `contents: read`
+- `issues: write`
+- `pull-requests: write`
+- `repository-projects: write`
+
+Token source used by workflow:
+
+- `secrets.GH_PROJECT_TOKEN` if present
+- otherwise falls back to `github.token`
+
+## Build and Maintenance
+
+Compile TypeScript workflow scripts:
+
+```bash
+npm run build   # in a checkout of ebalzan/ci
+```
+
+Important:
+
+- Commit both `src/` and `dist/` changes. CI (`npm run check`) fails when
+  `dist/` does not match `src/`.
+- Callers run `dist/` straight from the action download — nothing builds it on
+  the runner. A change reaches the repos only once the major tag moves
+  ([CONTRIBUTING → Releasing](../CONTRIBUTING.md#releasing-a-change)).
+
+## Troubleshooting
+
+### "Context access might be invalid"
+
+This warning usually comes from static editor validation, not Actions runtime.
+It is common with `vars.*` and `secrets.*` in workflow `env` blocks — which is
+why the workflows pass `toJSON(vars)` instead of naming each variable.
+
+### Common runtime failures
+
+- Unsupported branch prefix (`feature/`, `hotfix/`, `refactor/`, …): rename the branch
+- Project not found (`AUTO_PROJECT_OWNER` / `AUTO_PROJECT_NUMBER` mismatch)
+- Missing required fields in Project v2 (`Start date`, `Target date`, `Priority`, `Estimate`, `Size`)
+- Priority option text does not exist in the project field
+- Token missing permission for project updates
+- Milestone title not found
+- Stale `AUTO_MILESTONE_NUMBER` overriding `AUTO_MILESTONE_TITLE`
+
+### Quick verification checklist
+
+1. Push a test branch like `chore/workflow-test`.
+2. Confirm issue + PR are created.
+3. Confirm PR body includes `Closes #...`.
+4. Confirm issue and PR are added to the right project.
+5. Confirm issue and PR assignees are set to the latest commit author.
+6. Confirm `Start date`/`Target date`/`Priority`/`Estimate`/`Size` fields are set correctly.

package/docs/CI_FLOW.md

@@ -0,0 +1,205 @@
+# CI/CD Flow (shared stages)
+
+The branch → `dev` → `main` → release flow every repo using ebalzan/ci runs.
+This file covers the stages this repo owns; what happens **after** a release
+(a container rollout, a Vercel deploy, an app store build) and each repo's own
+build/test checks belong to that repo, chained on the stages below. This repo
+runs the same flow on itself (`.github/workflows/self-*.yml`), where the release
+also moves the major tag the other repos pin
+([CONTRIBUTING → Releasing](../CONTRIBUTING.md#releasing-a-change)).
+
+> **Model:** feature branch → `dev` → `main`.
+> `dev` is the integration branch. `main` is the release branch.
+> Every push to `main` produces a versioned release, which the repo then ships.
+
+---
+
+## 1. Branching model
+
+| Branch                          | Role                    | Receives merges from | Protected |
+| ------------------------------- | ----------------------- | -------------------- | --------- |
+| `main`                          | Releases                | `dev` only           | Yes ¹     |
+| `dev`                           | Integration of features | feature branches     | Yes ¹     |
+| `feat/*`, `fix/*`, `chore/*`, … | Short-lived work        | (you push to them)   | No        |
+
+Supported work-branch prefixes (each maps to a release type for the
+feature → `dev` PR check): `feat`, `fix`, `docs`, `style`, `refact`, `perf`,
+`test`, `build`, `ci`, `chore`, `revert`. Any other prefix fails both the PR
+check and the auto work-items run. A `refact/` branch takes a `refact:` title;
+there is no `refactor` type, and no `feature/` or `hotfix/` alias.
+
+¹ By the rulesets `bootstrap` applies: neither can be deleted, `main` cannot be
+force-pushed, and an opt-in ruleset requires PRs ([REPO_RULES.md](REPO_RULES.md)).
+
+---
+
+## 2. The flow at a glance
+
+```text
+  feature branch ── git push
+        │
+        ▼
+  (1) Auto Create Work Items     auto-work-items.yml
+        │  Issue + PR (base = dev) + project card
+        ▼
+  PR: feat → dev ── (2) PR Checks: pr-title.yml + the repo's own jobs
+        │  ✅ squash-merge into dev
+        ▼
+  (3) Promote dev to main        promote-dev-to-main.yml
+        │  ONE PR: dev → main (auto title + commit list)
+        ▼
+  PR: dev → main ── (2) PR Checks again (base = main)
+        │  ✅ squash-merge into main   ← this is the release approval
+        ▼
+  (4) Release                    release.yml
+        │  bump from commits → tag vX.Y.Z → GitHub Release → dev synced
+        ▼
+  (5) Ship — the repo's own job, chained on release.yml's `tag` / `sha` outputs
+```
+
+Each stage is a reusable workflow here, called from a thin file in the repo
+that holds only the trigger, the permissions and the `uses:` line.
+
+---
+
+## 3. Stage by stage
+
+### Stage 1 — Auto Create Work Items
+
+- **Reusable workflow:** `.github/workflows/auto-work-items.yml`
+- **Repo caller:** `.github/workflows/auto-pr.yml`, triggered on `push` to any
+  branch except `main` and `dev` (never on tags).
+- **What it does:** creates or updates (idempotent per branch) a GitHub
+  **Issue**, a **PR** into `dev`, and the **project card** with labels,
+  milestone, priority, size, estimate and dates. Details:
+  [AUTO_WORK_ITEMS_WORKFLOW.md](./AUTO_WORK_ITEMS_WORKFLOW.md).
+- **Token:** `GH_PROJECT_TOKEN` if present, else `github.token`. A classic PAT
+  with the `project` scope is required to write to a user-owned board, and so
+  that the created PR triggers Stage 2.
+
+### Stage 2 — PR Checks
+
+- **Repo file:** `.github/workflows/pr-checks.yml`, on `pull_request` into
+  `main` or `dev` (`opened`, `synchronize`, `reopened`, `ready_for_review`).
+- **Shared job** (`pr-title.yml` → `actions/pr-title`):
+  1. `validate-conventional-subject.sh` — the title must be a Conventional
+     Commits subject (e.g. `feat(search): add filters`).
+  2. `verify-pr-release-type.mjs` — checks the title's release type against the
+     **branch**:
+     - **Feature branch** (`feat/...` → `dev`): the title's type must match the
+       branch type, unless the title marks a breaking change with `!`.
+     - **Promotion** (`dev` → `main`): only requires a valid conventional title;
+       the bump is computed later from the promoted commits.
+  3. Managed-file drift: if the repo still keeps a (deprecated) local copy of a
+     `managed/` file, it must equal this version's ([CLI → sync-managed](CLI.md#sync-managed)).
+- **Repo jobs** (validate, build, image build, delivery preview, …) run in
+  parallel beside it. A bad title still fails the run.
+- The check is reported as **`<caller job id> / Validate PR Title`**. Name the
+  caller job `title` (the template does): `title / Validate PR Title` is the
+  context the `ci: require pull request` ruleset requires.
+
+### Stage 3 — Promote dev to main
+
+- **Reusable workflow:** `.github/workflows/promote-dev-to-main.yml`
+  (`scripts/release/promote-dev-to-main.mjs`)
+- **Repo caller:** `push` to `dev`, plus `workflow_dispatch`.
+- **What it does:**
+  1. Compares `main...dev`. If `dev` is not ahead, it stops.
+  2. Computes the bump from the promoted commits and creates or updates a
+     single `dev → main` PR titled with the most significant type among them
+     (`feat` > `fix` > `refact` > `perf` > `revert` > `build` > `ci` > `docs` >
+     `test` > `style` > `chore`, `!` for breaking) plus the projected version,
+     e.g. `refact: promote dev to main (v0.6.3)`. The body lists every commit.
+  3. Best-effort metadata (a failure warns, never fails the run): assignee = who
+     pushed to `dev`; labels `release` + each promoted commit type (only ever
+     added); the `AUTO_MILESTONE_TITLE` milestone and the project board, when
+     configured.
+- **Token:** `GH_PROJECT_TOKEN` if present, else `GITHUB_TOKEN`.
+  ⚠️ A PR opened with the default `GITHUB_TOKEN` does not trigger other
+  workflows — without the PAT, PR Checks will not run on the promotion PR until
+  you push to it or reopen it.
+
+### Stage 4 — Release
+
+- **Reusable workflow:** `.github/workflows/release.yml`
+  (`scripts/release/release-main.mjs`)
+- **Repo caller:** `push` to `main`.
+- **Skip guard:** skipped when the head commit starts with `chore(release):`,
+  so the release commit cannot release again.
+- **What it does:**
+  1. Reads the latest `vX.Y.Z` tag (none yet: the `package.json` version, or `0.0.0`).
+  2. Computes the bump from every Conventional Commit since it (§4).
+  3. With a `package.json`: bumps it (and the lockfile, if any), commits
+     `chore(release): X.Y.Z`, tags `vX.Y.Z`. Without one: tags the merged
+     commit as is (tag-only release). Pushes the branch and the tag.
+  4. Publishes a GitHub Release (associated PR + included commits).
+  5. `sync-dev`: force-points `dev` at the release commit (§4, "Squash
+     everything").
+- **Outputs:** `tag` (`vX.Y.Z`, empty when nothing was released) and `sha`
+  (the release commit). The repo's own ship jobs chain on them.
+
+---
+
+## 4. Version bump rules (commit-scan)
+
+The bump is derived from **the Conventional Commits landed on `main` since the
+previous tag**, not from any branch name. Highest wins:
+
+| Found in any commit since last tag                                                 | Bump              |
+| ---------------------------------------------------------------------------------- | ----------------- |
+| `!` after type, or `BREAKING CHANGE:` footer                                       | `major`           |
+| `feat:`                                                                            | `minor`           |
+| `fix`, `perf`, `docs`, `style`, `refact`, `test`, `build`, `ci`, `chore`, `revert` | `patch`           |
+| no Conventional Commit found                                                       | release **fails** |
+
+Implementation: `highestRelease()` in `scripts/release/release-utils.mjs`, used
+by both `release-main.mjs` (the bump) and `promote-dev-to-main.mjs` (the title
+preview).
+
+### Why this works for either merge method on `dev → main`
+
+- **Squash merge:** `main` gets one commit using the PR title; because the
+  promotion title is generated to carry the highest bump, the scan still yields
+  the right version. **This is the method every repo uses** — the shared
+  repo settings allow nothing else.
+- **Merge commit:** the feature commits flow into `main`; the scan (which skips
+  merge commits) sees each one.
+
+> **Squash everything.** A squash (or rebase) rewrites the promoted commits, so
+> `dev` and `main` end up with identical content under unrelated histories, and
+> the _next_ promotion would re-merge everything from the last common ancestor
+> and conflict against itself. `sync-dev` prevents that by force-pointing `dev`
+> at the release commit after each release. Consequence: if you have local
+> commits on `dev` that were not released, `git reset --hard origin/dev` after a
+> release and branch off it.
+
+---
+
+## 5. Developer flow (cheat sheet)
+
+```bash
+git checkout dev && git pull origin dev
+git checkout -b feat/your-change
+git commit -m "feat(search): add result filters"   # husky checks it
+git push -u origin feat/your-change   # Stage 1 opens Issue + PR into dev
+# merge into dev (squash) once PR Checks pass
+# Stage 3 opens/updates dev → main; merge it (squash) to release
+# Stage 4 versions, tags, releases; the repo ships the tag
+```
+
+You never edit versions, tags or release notes by hand.
+
+---
+
+## 6. Troubleshooting
+
+| Symptom                                                  | Likely cause / fix                                                                                                              |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Workflow fails to start: "workflow was not found"        | Wrong `uses:` path or ref, or the repo's Actions policy does not allow actions from other repos (Settings → Actions → General). |
+| "The nested job is requesting 'X', but is only allowed…" | The caller's `permissions:` lacks what the reusable job declares. Grant it in the caller.                                       |
+| No Issue/PR after pushing a feature branch               | Branch was `dev`/`main` (ignored), unsupported prefix, or `GH_PROJECT_TOKEN` missing/insufficient.                              |
+| `dev → main` PR exists but no checks ran                 | Opened with the default `GITHUB_TOKEN`. Set `GH_PROJECT_TOKEN`, or push to it.                                                  |
+| PR Checks: "differs from ebalzan/ci's managed copy"      | Delete the local copy and use the hook from the package ([CLI](CLI.md#commit-msg)).                                             |
+| Release failed: "Could not determine a release type"     | No Conventional Commit since the last tag.                                                                                      |
+| Behaviour did not change after editing ebalzan/ci        | Callers pin `@v2`: the change ships only once it is released and `v2` moves.                                                    |
+| Work items: "unsupported type"                           | The branch prefix is not one of the types above. Rename the branch.                                                             |