mandrel 2.78.0 → 2.80.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/README.md +6 -1
- package/.agents/agents/auditor.md +8 -3
- package/.agents/audit-checklists/architecture.md +1 -0
- package/.agents/audit-checklists/clean-code.md +1 -0
- package/.agents/audit-checklists/data-model.md +9 -1
- package/.agents/audit-checklists/devops.md +4 -1
- package/.agents/audit-checklists/security.md +1 -1
- package/.agents/docs/agentrc-reference.json +3 -0
- package/.agents/docs/configuration.md +2 -2
- package/.agents/docs/workflows.md +1 -1
- package/.agents/schemas/agentrc.schema.json +20 -2
- package/.agents/schemas/audit-rules.json +5 -1
- package/.agents/scripts/bootstrap.js +87 -16
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
- package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
- package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
- package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
- package/.agents/scripts/lib/close-validation/commands.js +33 -0
- package/.agents/scripts/lib/close-validation/gates.js +11 -4
- package/.agents/scripts/lib/config/explain.js +3 -2
- package/.agents/scripts/lib/config-settings-schema.js +20 -2
- package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
- package/.agents/scripts/lib/findings/route-finding.js +4 -3
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
- package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
- package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
- package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
- package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
- package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
- package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
- package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
- package/.agents/scripts/lib/test-run-credit.js +46 -17
- package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
- package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
- package/.agents/workflows/audit-architecture.md +20 -4
- package/.agents/workflows/audit-clean-code.md +17 -1
- package/.agents/workflows/audit-data-model.md +94 -10
- package/.agents/workflows/audit-devops.md +58 -14
- package/.agents/workflows/audit-performance.md +22 -0
- package/.agents/workflows/audit-quality.md +30 -0
- package/.agents/workflows/audit-security.md +23 -8
- package/.agents/workflows/audit-to-stories.md +22 -7
- package/.agents/workflows/helpers/audit-lens-core.md +56 -7
- package/.agents/workflows/helpers/plan-reference.md +11 -3
- package/README.md +13 -1
- package/docs/CHANGELOG.md +24 -0
- package/lib/cli/registry.js +85 -12
- package/lib/cli/uninstall.js +34 -18
- package/lib/cli/update.js +37 -6
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
- package/package.json +1 -1
package/.agents/README.md
CHANGED
|
@@ -269,7 +269,12 @@ and the prompt falls through to manual free-text entry — so a missing or
|
|
|
269
269
|
stale `gh` never breaks the run.
|
|
270
270
|
|
|
271
271
|
For non-interactive (CI) installs, pass `--owner`, `--repo`, and
|
|
272
|
-
`--assume-yes`; pass `--skip-github` to defer the remote half.
|
|
272
|
+
`--assume-yes`; pass `--skip-github` to defer the remote half. A
|
|
273
|
+
non-interactive run creates no Projects V2 board unless one is stored in
|
|
274
|
+
`.agentrc.json` or named with `--project-number <name>`; `--no-project` (or an
|
|
275
|
+
empty / `none` `--project-number` or `GH_PROJECT_NUMBER`) skips it explicitly,
|
|
276
|
+
and labels are still provisioned. Interactively declining a new project also
|
|
277
|
+
continues without a board.
|
|
273
278
|
|
|
274
279
|
After bootstrap, every Mandrel command is generated into a flat
|
|
275
280
|
`.claude/commands/` tree by `npm run sync:commands` (kept current at install
|
|
@@ -68,9 +68,14 @@ file is its standalone-agent form.
|
|
|
68
68
|
(e.g. `perf-baseline.json`).
|
|
69
69
|
- Running **non-mutating** measurements/scanners the lens calls for (profilers,
|
|
70
70
|
timers, `npm audit`, read-only status commands) is permitted; running
|
|
71
|
-
anything that installs, mutates git/labels, edits source
|
|
72
|
-
|
|
73
|
-
|
|
71
|
+
anything that installs, mutates git/labels, or edits source is forbidden.
|
|
72
|
+
A lens that names a stricter carve-out tightens this for that lens.
|
|
73
|
+
- **Databases.** Never connect to a production database, under any
|
|
74
|
+
configuration. Connect to any other database only when the lens body
|
|
75
|
+
provides for it **and** that environment opts in via `allowAudit`, through
|
|
76
|
+
the environment variable named by `urlEnv`, read-only, with
|
|
77
|
+
`default_transaction_read_only=on` on any session you open. Never run a
|
|
78
|
+
migration or any statement that writes.
|
|
74
79
|
|
|
75
80
|
## Scope
|
|
76
81
|
|
|
@@ -13,6 +13,7 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
13
13
|
- [ ] Cycle detection.
|
|
14
14
|
- [ ] Dead-export detection.
|
|
15
15
|
- [ ] Hotspot ranking.
|
|
16
|
+
- [ ] Non-JS ecosystems.
|
|
16
17
|
- [ ] LLM triage on top.
|
|
17
18
|
- [ ] Documented architecture boundaries
|
|
18
19
|
- [ ] Automated boundary checks
|
|
@@ -19,6 +19,7 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
19
19
|
- [ ] Dynamic imports
|
|
20
20
|
- [ ] Test-only seams
|
|
21
21
|
- [ ] Framework/registration hooks
|
|
22
|
+
- [ ] Non-JS ecosystems.
|
|
22
23
|
- [ ] Churn-by-complexity hotspot cap.
|
|
23
24
|
- [ ] Logic Complexity
|
|
24
25
|
- [ ] Duplication
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# Data Model & Persistence Audit — authoring checklist
|
|
8
8
|
|
|
9
|
-
> Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity,
|
|
9
|
+
> Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-…
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
@@ -20,3 +20,11 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
20
20
|
- [ ] Migration hygiene
|
|
21
21
|
- [ ] Type fidelity
|
|
22
22
|
- [ ] Access-pattern fit
|
|
23
|
+
- [ ] Dead schema
|
|
24
|
+
- [ ] Unused schema
|
|
25
|
+
- [ ] Schema gap
|
|
26
|
+
- [ ] Provisional until corroborated
|
|
27
|
+
- [ ] Common identifiers are runtime-only
|
|
28
|
+
- [ ] Introspection diff
|
|
29
|
+
- [ ] Migration ledger
|
|
30
|
+
- [ ] Catalog statistics (Postgres)
|
|
@@ -10,10 +10,13 @@
|
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
13
|
-
- [ ] Workflow static analysis (`actionlint
|
|
13
|
+
- [ ] Workflow static analysis (`actionlint`, GitHub Actions only).
|
|
14
14
|
- [ ] Workflow security posture (`zizmor`).
|
|
15
15
|
- [ ] Container linting (`hadolint`), presence-gated on Dockerfiles.
|
|
16
16
|
- [ ] Pipeline reliability history (`gh run list`).
|
|
17
|
+
- [ ] Google Cloud Build (gated: `cloudbuild*.yaml` present).
|
|
18
|
+
- [ ] GitLab CI (gated: `.gitlab-ci.yml` present).
|
|
19
|
+
- [ ] Python toolchain (gated: Python manifests present).
|
|
17
20
|
- [ ] Redundancy & Duplication
|
|
18
21
|
- [ ] Performance Gaps
|
|
19
22
|
- [ ] Security & Compliance
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
13
|
-
- [ ] Dependency CVEs
|
|
13
|
+
- [ ] Dependency CVEs, per detected ecosystem.
|
|
14
14
|
- [ ] Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.
|
|
15
15
|
- [ ] Grep battery (deterministic fallback / augmentation).
|
|
16
16
|
- [ ] Manual surface review.
|
|
@@ -85,7 +85,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
85
85
|
| `paths.tempRoot` | Yes | `string` | `"temp"` | Repo-relative gitignored scratch root. Every temporary artifact — gate transcripts, audit reports, plan authoring dirs — lands under it. |
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
87
|
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
|
|
88
|
-
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command
|
|
88
|
+
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution). |
|
|
89
89
|
| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it. |
|
|
90
90
|
| `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
|
|
91
91
|
| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
|
|
@@ -264,7 +264,7 @@ Agent-driven QA harness contract (Epic #3214; environment-keyed by Epic #4326).
|
|
|
264
264
|
| --- | --- | --- | --- | --- |
|
|
265
265
|
| `featureRoot` | No | `string` | `"tests/features"` | Directory holding the Gherkin feature files the QA sweep drives. |
|
|
266
266
|
| `fixturesManifest` | No | `string` | `"tests/fixtures/personas.json"` | Path to the persona/fixture manifest the harness seeds from. |
|
|
267
|
-
| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`. |
|
|
267
|
+
| `environments` | No | `object<map>` | `{"local":{"baseUrl":"http://localhost:3000","signInSeam":{"urlTemplate":"/dev/sign-in-as/{persona}"},"database":{"urlEnv":"DATABASE_URL"}},"staging":{"baseUrl":"https://staging.example.test","allowWrites":false}}` | Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`. |
|
|
268
268
|
| `personas` | No | one of: `array`, `object` | `{"admin":{"credentialRef":"QA_ADMIN_CREDENTIAL"},"member":{"credentialRef":"QA_MEMBER_CREDENTIAL"}}` | Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam. |
|
|
269
269
|
| `gherkinLint` | No | `object` | `{"scopes":{"web":{"featureRoots":["apps/web/tests/features"],"stepRoots":["apps/web/tests/steps"]}},"exemptionTags":["@skip"],"stepWaivers":[]}` | Static Gherkin corpus gate (Story #5013). Optional; the gate runs only when this block is present, so an upgrade never reddens the lint of a consumer that never asked the framework to police its `.feature` files. Inside the opt-in it fails closed: an unresolvable `@cucumber/gherkin` parser, or a scope resolving zero step definitions, exits 1 rather than reporting a clean run. |
|
|
270
270
|
| `gherkinLint.scopes` | Yes | `object<map>` | — | Binding scopes, keyed by name. Each scope resolves its own features against its own step definitions only — pooling every step root into one matcher list is what makes a cross-app false bind possible, where a step defined solely in app B silently vouches for app A. The scope name appears verbatim in every unbound finding. |
|
|
@@ -41,7 +41,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
41
41
|
| `/audit-architecture` | Audit architectural boundaries, module coupling, layering violations, and shipped-but-uncalled seams; emit a structured findings report keyed to the canonical severity scale. |
|
|
42
42
|
| `/audit-baselines` | Audit the committed baseline surface — dead instruments, stale baselines, cross-gate hotspot clusters, trend drift, and floor-tightening headroom — and emit findings whose remediation burns the measured debt down and tightens the ratchet behind it. |
|
|
43
43
|
| `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
|
|
44
|
-
| `/audit-data-model` | Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity,
|
|
44
|
+
| `/audit-data-model` | Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-less repos skip cleanly. |
|
|
45
45
|
| `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
|
|
46
46
|
| `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
|
|
47
47
|
| `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
"pattern": "([;&|`]|\\$\\()"
|
|
82
82
|
},
|
|
83
83
|
"minLength": 1,
|
|
84
|
-
"description": "Full test-suite command
|
|
84
|
+
"description": "Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution).",
|
|
85
85
|
"default": "npm test"
|
|
86
86
|
},
|
|
87
87
|
"typecheck": {
|
|
@@ -1439,12 +1439,15 @@
|
|
|
1439
1439
|
},
|
|
1440
1440
|
"environments": {
|
|
1441
1441
|
"type": "object",
|
|
1442
|
-
"description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.",
|
|
1442
|
+
"description": "Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. An optional `database` object `{ urlEnv, allowAudit? }` names the environment variable holding that target's database connection string (the name only, never the URL) for the `/audit-data-model` live-schema pass; `allowAudit` gates that read-only pass and, like `allowWrites`, defaults to true only for `local`. Point `urlEnv` at a role granted catalog read only. A production database is never audited live, whatever this block says. Replaces the retired top-level single `signInSeam`.",
|
|
1443
1443
|
"default": {
|
|
1444
1444
|
"local": {
|
|
1445
1445
|
"baseUrl": "http://localhost:3000",
|
|
1446
1446
|
"signInSeam": {
|
|
1447
1447
|
"urlTemplate": "/dev/sign-in-as/{persona}"
|
|
1448
|
+
},
|
|
1449
|
+
"database": {
|
|
1450
|
+
"urlEnv": "DATABASE_URL"
|
|
1448
1451
|
}
|
|
1449
1452
|
},
|
|
1450
1453
|
"staging": {
|
|
@@ -1499,6 +1502,21 @@
|
|
|
1499
1502
|
},
|
|
1500
1503
|
"allowWrites": {
|
|
1501
1504
|
"type": "boolean"
|
|
1505
|
+
},
|
|
1506
|
+
"database": {
|
|
1507
|
+
"type": "object",
|
|
1508
|
+
"description": "Database target for the `/audit-data-model` read-only live-schema pass. `urlEnv` is the name of the environment variable carrying the connection string — never the URL itself. `allowAudit` opts the environment in to that pass; it defaults to true only for `local`.",
|
|
1509
|
+
"properties": {
|
|
1510
|
+
"urlEnv": {
|
|
1511
|
+
"type": "string",
|
|
1512
|
+
"pattern": "^[A-Z_][A-Z0-9_]*$"
|
|
1513
|
+
},
|
|
1514
|
+
"allowAudit": {
|
|
1515
|
+
"type": "boolean"
|
|
1516
|
+
}
|
|
1517
|
+
},
|
|
1518
|
+
"required": ["urlEnv"],
|
|
1519
|
+
"additionalProperties": false
|
|
1502
1520
|
}
|
|
1503
1521
|
},
|
|
1504
1522
|
"required": ["baseUrl"],
|
|
@@ -48,7 +48,13 @@ Flags:
|
|
|
48
48
|
private | public | internal (default: private)
|
|
49
49
|
--operator-handle <name> GitHub handle for github.operatorHandle
|
|
50
50
|
--base-branch <name> Base branch (default: origin/HEAD or 'main')
|
|
51
|
-
--project-number <n> Projects V2 number/name (optional)
|
|
51
|
+
--project-number <n> Projects V2 number/name (optional). An empty
|
|
52
|
+
value or \`none\` skips the board. A non-
|
|
53
|
+
interactive run with no stored number skips it
|
|
54
|
+
unless a name/number is given.
|
|
55
|
+
--no-project Skip the Projects V2 board (labels are still
|
|
56
|
+
provisioned). GH_PROJECT_NUMBER set to empty or
|
|
57
|
+
\`none\` does the same.
|
|
52
58
|
--assume-yes Accept every default + approve GitHub-admin
|
|
53
59
|
mutations. A non-TTY run requires this (or
|
|
54
60
|
--approve-github-admin) — there is no operator
|
|
@@ -405,8 +411,25 @@ async function createGithubProject(state, execImpl = exec) {
|
|
|
405
411
|
return number;
|
|
406
412
|
}
|
|
407
413
|
|
|
408
|
-
/**
|
|
409
|
-
|
|
414
|
+
/** A stored number first, so a re-run never reads as a new board. */
|
|
415
|
+
function projectDefault(defaults, flags, opts) {
|
|
416
|
+
if (defaults.projectNumber) return defaults.projectNumber;
|
|
417
|
+
const interactive = opts.interactive ?? !flags?.['assume-yes'];
|
|
418
|
+
return interactive ? defaults.repo : null;
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* The Step 3 question list. `opts.interactive` (default: no `--assume-yes`)
|
|
423
|
+
* picks the project default: a non-interactive run never creates a board
|
|
424
|
+
* from the repo name — only a stored number or an explicit value selects one.
|
|
425
|
+
*/
|
|
426
|
+
export function buildQuestions(
|
|
427
|
+
defaults,
|
|
428
|
+
flags,
|
|
429
|
+
env = process.env,
|
|
430
|
+
lists = {},
|
|
431
|
+
opts = {},
|
|
432
|
+
) {
|
|
410
433
|
const owner = resolveOwnerForPicker(defaults, flags, env);
|
|
411
434
|
// Pre-fetched lists are empty when the owner was unknown up front, so the
|
|
412
435
|
// pickers fall back to a live fetch keyed off the typed `answers.owner`.
|
|
@@ -473,11 +496,11 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
|
|
|
473
496
|
key: 'projectNumber',
|
|
474
497
|
flag: 'project-number',
|
|
475
498
|
env: 'GH_PROJECT_NUMBER',
|
|
499
|
+
skipFlag: 'no-project',
|
|
476
500
|
message: 'New GitHub Project V2 name',
|
|
477
501
|
pickerMessage:
|
|
478
502
|
'GitHub Project V2 name - Select existing or press ENTER to create',
|
|
479
|
-
|
|
480
|
-
default: defaults.projectNumber || defaults.repo,
|
|
503
|
+
default: projectDefault(defaults, flags, opts),
|
|
481
504
|
required: false,
|
|
482
505
|
picker: {
|
|
483
506
|
list: (answers) => {
|
|
@@ -769,14 +792,51 @@ async function resolveOptIns(state) {
|
|
|
769
792
|
return optIns;
|
|
770
793
|
}
|
|
771
794
|
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
795
|
+
/**
|
|
796
|
+
* Approve each new resource separately. A declined repo aborts (nothing can
|
|
797
|
+
* continue without it); a declined project clears `projectNumber` and the run
|
|
798
|
+
* continues without a board, so labels are still provisioned.
|
|
799
|
+
*
|
|
800
|
+
* @returns {Promise<boolean>} false only when repo creation is declined.
|
|
801
|
+
*/
|
|
802
|
+
export async function approveCreation(
|
|
803
|
+
state,
|
|
804
|
+
answers,
|
|
805
|
+
creation,
|
|
806
|
+
confirm = confirmYesNo,
|
|
807
|
+
) {
|
|
808
|
+
if (state.flags['dry-run']) return true;
|
|
809
|
+
if (!(await approveNewRepo(state, answers, creation, confirm))) return false;
|
|
810
|
+
await approveNewProject(state, answers, creation, confirm);
|
|
811
|
+
return true;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
async function approveNewRepo(state, answers, creation, confirm) {
|
|
815
|
+
if (!creation.newRepo) return true;
|
|
816
|
+
const ok = await confirm(
|
|
817
|
+
`Create the new GitHub repo ${answers.owner}/${answers.repo}?`,
|
|
818
|
+
state.interactive,
|
|
819
|
+
);
|
|
820
|
+
if (!ok) {
|
|
821
|
+
Logger.error(
|
|
822
|
+
'[Bootstrap] Repo creation declined — cannot continue without the repo. Exiting.',
|
|
823
|
+
);
|
|
775
824
|
}
|
|
776
|
-
return
|
|
777
|
-
|
|
825
|
+
return ok;
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
async function approveNewProject(state, answers, creation, confirm) {
|
|
829
|
+
if (!creation.newProject) return;
|
|
830
|
+
const ok = await confirm(
|
|
831
|
+
`Create the new GitHub Project V2 "${answers.projectNumber}"?`,
|
|
778
832
|
state.interactive,
|
|
779
833
|
);
|
|
834
|
+
if (ok) return;
|
|
835
|
+
answers.projectNumber = '';
|
|
836
|
+
creation.newProject = false;
|
|
837
|
+
Logger.info(
|
|
838
|
+
'[Bootstrap] Project creation declined — skipping the Projects V2 board and continuing.',
|
|
839
|
+
);
|
|
780
840
|
}
|
|
781
841
|
|
|
782
842
|
async function confirmSummary(state, answers, creation, projectsList) {
|
|
@@ -819,6 +879,7 @@ export async function collectAndConfirm(state) {
|
|
|
819
879
|
state.flags,
|
|
820
880
|
process.env,
|
|
821
881
|
lists,
|
|
882
|
+
{ interactive: state.interactive },
|
|
822
883
|
),
|
|
823
884
|
flags: state.flags,
|
|
824
885
|
interactive: state.interactive,
|
|
@@ -844,10 +905,7 @@ export async function collectAndConfirm(state) {
|
|
|
844
905
|
silentAccept = [];
|
|
845
906
|
continue;
|
|
846
907
|
}
|
|
847
|
-
if (!(await approveCreation(state, creation))) {
|
|
848
|
-
Logger.error(
|
|
849
|
-
'[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
|
|
850
|
-
);
|
|
908
|
+
if (!(await approveCreation(state, answers, creation))) {
|
|
851
909
|
return { ok: false, exit: 1 };
|
|
852
910
|
}
|
|
853
911
|
const optIns = await resolveOptIns(state);
|
|
@@ -855,7 +913,7 @@ export async function collectAndConfirm(state) {
|
|
|
855
913
|
}
|
|
856
914
|
}
|
|
857
915
|
|
|
858
|
-
function renderDryRunPlan(state) {
|
|
916
|
+
export function renderDryRunPlan(state) {
|
|
859
917
|
const a = state.answers ?? {};
|
|
860
918
|
const c = state.creation ?? {};
|
|
861
919
|
const flagList = Object.entries(state.flags ?? {}).map(([k, v]) =>
|
|
@@ -994,6 +1052,19 @@ export function persistProjectNumber(state) {
|
|
|
994
1052
|
return { ok: true, payload: {} };
|
|
995
1053
|
}
|
|
996
1054
|
|
|
1055
|
+
/**
|
|
1056
|
+
* `--with-project-board` decorates a board only when one was selected: with
|
|
1057
|
+
* the project skipped, `runBootstrap` would otherwise create one.
|
|
1058
|
+
*/
|
|
1059
|
+
export function resolveBoardDecoration(state) {
|
|
1060
|
+
if (state.withProjectBoard !== true) return false;
|
|
1061
|
+
if (String(state.answers?.projectNumber ?? '').length > 0) return true;
|
|
1062
|
+
Logger.info(
|
|
1063
|
+
'[Bootstrap] Projects V2 board skipped — skipping board decoration (--with-project-board ignored).',
|
|
1064
|
+
);
|
|
1065
|
+
return false;
|
|
1066
|
+
}
|
|
1067
|
+
|
|
997
1068
|
/** Step 6b — GitHub-side bootstrap. Honours `--skip-github`. */
|
|
998
1069
|
export async function executeGithubBootstrap(state) {
|
|
999
1070
|
if (state.flags['skip-github']) {
|
|
@@ -1004,7 +1075,7 @@ export async function executeGithubBootstrap(state) {
|
|
|
1004
1075
|
state.report.github = await runGithubBootstrap(state.answers, {
|
|
1005
1076
|
assumeYes: state.assumeYes,
|
|
1006
1077
|
githubAdminApproved: state.githubAdminApproved === true,
|
|
1007
|
-
withProjectBoard: state
|
|
1078
|
+
withProjectBoard: resolveBoardDecoration(state),
|
|
1008
1079
|
reapConflictingWorkflows: Boolean(
|
|
1009
1080
|
state.flags['reap-conflicting-workflows'],
|
|
1010
1081
|
),
|
|
@@ -3,11 +3,18 @@
|
|
|
3
3
|
* Pure: returns a string.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
+
import { auditFindingRecord } from '../findings/audit-finding-record.js';
|
|
7
|
+
import { semanticKeyFor } from '../findings/route-finding.js';
|
|
6
8
|
import { SEVERITIES, sortBySeverity } from '../findings/severity.js';
|
|
7
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
auditLabelFooterForFindings,
|
|
11
|
+
definesAuditLabel,
|
|
12
|
+
} from './audit-label-taxonomy.js';
|
|
13
|
+
import { auditLabelsForFindings } from './audit-lenses.js';
|
|
8
14
|
import {
|
|
9
15
|
renderFingerprintFooter,
|
|
10
16
|
renderSemanticKeyFooter,
|
|
17
|
+
toCanonicalFinding,
|
|
11
18
|
} from './finding-adapter.js';
|
|
12
19
|
import { findingBullets, SEED_FINDING_FIELDS } from './finding-bullets.js';
|
|
13
20
|
|
|
@@ -126,6 +133,29 @@ function formatDedupFooters(groups) {
|
|
|
126
133
|
.join('\n');
|
|
127
134
|
}
|
|
128
135
|
|
|
136
|
+
/**
|
|
137
|
+
* One `audit-finding` record per fingerprinted finding, so an N>1 plan can
|
|
138
|
+
* attribute each identity to the Stories that cover its files instead of
|
|
139
|
+
* smearing the group footers across every Story. Seed-only.
|
|
140
|
+
*
|
|
141
|
+
* @param {object[]} groups
|
|
142
|
+
* @returns {string}
|
|
143
|
+
*/
|
|
144
|
+
function formatFindingRecords(groups) {
|
|
145
|
+
return groups
|
|
146
|
+
.flatMap((g) => (Array.isArray(g.findings) ? g.findings : []))
|
|
147
|
+
.filter((f) => typeof f?.fingerprint?.full === 'string')
|
|
148
|
+
.map((f) =>
|
|
149
|
+
auditFindingRecord({
|
|
150
|
+
sha: f.fingerprint.full,
|
|
151
|
+
key: semanticKeyFor(toCanonicalFinding(f)),
|
|
152
|
+
label: auditLabelsForFindings([f]).find(definesAuditLabel) ?? null,
|
|
153
|
+
files: Array.isArray(f.files) ? f.files : [],
|
|
154
|
+
}),
|
|
155
|
+
)
|
|
156
|
+
.join('\n');
|
|
157
|
+
}
|
|
158
|
+
|
|
129
159
|
function formatKeyFiles(groups) {
|
|
130
160
|
const files = new Set();
|
|
131
161
|
for (const g of groups) for (const f of g.files) files.add(f);
|
|
@@ -168,7 +198,12 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
|
|
|
168
198
|
const scope = formatFindingsList(findings);
|
|
169
199
|
const files = formatKeyFiles(groups);
|
|
170
200
|
const assumptions = formatKeyAssumptions(sourceReports);
|
|
171
|
-
const dedupFooters =
|
|
201
|
+
const dedupFooters = [
|
|
202
|
+
formatDedupFooters(groups),
|
|
203
|
+
formatFindingRecords(groups),
|
|
204
|
+
]
|
|
205
|
+
.filter(Boolean)
|
|
206
|
+
.join('\n');
|
|
172
207
|
|
|
173
208
|
return [
|
|
174
209
|
'# Idea Seed: Audit Remediation',
|
|
@@ -11,8 +11,9 @@ import fs from 'node:fs';
|
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
|
-
* Mirrors what the bootstrap writes; `.claude/commands/`
|
|
15
|
-
*
|
|
14
|
+
* Mirrors what the bootstrap writes; the `.claude/commands/` and
|
|
15
|
+
* `.claude/agents/` projections are generated by `prepare` and gitignored,
|
|
16
|
+
* so both are absent.
|
|
16
17
|
*
|
|
17
18
|
* @type {readonly string[]}
|
|
18
19
|
*/
|
|
@@ -81,7 +81,7 @@ export function buildMutationManifest(ctx = {}) {
|
|
|
81
81
|
target: rel('.gitignore'),
|
|
82
82
|
action: 'merge',
|
|
83
83
|
detail:
|
|
84
|
-
'Ignore .claude/commands/ (generated), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
|
|
84
|
+
'Ignore the .claude/commands/ and .claude/agents/ projections (generated by prepare), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
|
|
85
85
|
reversible: true,
|
|
86
86
|
},
|
|
87
87
|
);
|
|
@@ -101,7 +101,7 @@ export function buildMutationManifest(ctx = {}) {
|
|
|
101
101
|
target: rel('package.json'),
|
|
102
102
|
action: 'merge',
|
|
103
103
|
detail:
|
|
104
|
-
'Seed/merge the sync:commands, prepare, and bootstrap npm scripts.',
|
|
104
|
+
'Seed/merge the sync:commands, sync:agents, prepare, and bootstrap npm scripts. `prepare` is guarded: it exits 0 without writing when .agents/scripts/ is absent (a manifest-only container `npm ci`), and otherwise regenerates the .claude/commands/ and .claude/agents/ projections — both gitignored.',
|
|
105
105
|
reversible: true,
|
|
106
106
|
},
|
|
107
107
|
{
|
|
@@ -29,6 +29,19 @@ export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
|
|
|
29
29
|
|
|
30
30
|
export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
|
|
31
31
|
|
|
32
|
+
/** The pre-guard `prepare` form; bootstrap and the 2.79.0 migration upgrade it. */
|
|
33
|
+
export const LEGACY_PREPARE_COMMAND = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Exits 1 when `.agents/scripts/` exists so `||` runs the projections, and 0
|
|
37
|
+
* otherwise so a manifest-only `npm ci` (no `.agents/` yet) skips them. Only
|
|
38
|
+
* `node -e` and `||`/`&&`/`()` — portable across npm's sh and cmd shells.
|
|
39
|
+
*/
|
|
40
|
+
const PREPARE_GUARD = `node -e "process.exit(require('fs').existsSync('.agents/scripts')?1:0)"`;
|
|
41
|
+
|
|
42
|
+
/** The `prepare` script bootstrap writes: guarded, then both projections. */
|
|
43
|
+
export const PREPARE_COMMAND = `${PREPARE_GUARD} || (${LEGACY_PREPARE_COMMAND})`;
|
|
44
|
+
|
|
32
45
|
export { SYSTEM_PROMPT_BLOCK, SYSTEM_PROMPT_IMPORT };
|
|
33
46
|
|
|
34
47
|
/** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
|
|
@@ -40,6 +53,11 @@ export const GITIGNORE_BLOCKS = Object.freeze({
|
|
|
40
53
|
block:
|
|
41
54
|
'\n# Claude Code command projection is generated from .agents/workflows/ — do not commit.\n.claude/commands/\n',
|
|
42
55
|
},
|
|
56
|
+
agents: {
|
|
57
|
+
pattern: /^\s*\.claude\/agents\/?\s*$/m,
|
|
58
|
+
block:
|
|
59
|
+
'\n# Claude Code agent projection is generated from .agents/agents/ by `prepare` — do not commit.\n.claude/agents/\n',
|
|
60
|
+
},
|
|
43
61
|
mcp: {
|
|
44
62
|
pattern: /^\s*\.mcp\.json\s*$/m,
|
|
45
63
|
block:
|
|
@@ -137,22 +155,38 @@ function ensureScript(scripts, key, command) {
|
|
|
137
155
|
return 'added';
|
|
138
156
|
}
|
|
139
157
|
|
|
140
|
-
/**
|
|
141
|
-
|
|
158
|
+
/** Each projection `prepare` must run: [script file it names, its command]. */
|
|
159
|
+
const PREPARE_PROJECTIONS = Object.freeze([
|
|
160
|
+
['sync-claude-commands.js', SYNC_COMMAND],
|
|
161
|
+
['sync-claude-agents.js', SYNC_AGENTS_COMMAND],
|
|
162
|
+
]);
|
|
163
|
+
|
|
164
|
+
/** Outcomes that mean `ensurePackageJson` changed the manifest. */
|
|
165
|
+
const PACKAGE_JSON_MUTATIONS = new Set([true, 'added', 'appended', 'upgraded']);
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Seed the guarded `prepare`, upgrade the exact legacy bare form to it, and
|
|
169
|
+
* otherwise append each missing projection so a partial prepare gains the
|
|
170
|
+
* other. An operator `prepare` already naming both scripts is left alone.
|
|
171
|
+
*
|
|
172
|
+
* @param {Record<string, string>} scripts - Mutated in place.
|
|
173
|
+
* @returns {'added'|'upgraded'|'appended'|'already-present'}
|
|
174
|
+
*/
|
|
175
|
+
export function ensurePrepareScript(scripts) {
|
|
142
176
|
const prepare = scripts.prepare;
|
|
143
177
|
if (!prepare) {
|
|
144
|
-
scripts.prepare =
|
|
178
|
+
scripts.prepare = PREPARE_COMMAND;
|
|
145
179
|
return 'added';
|
|
146
180
|
}
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
}
|
|
151
|
-
if (!next.includes('sync-claude-agents.js')) {
|
|
152
|
-
next = `${next} && ${SYNC_AGENTS_COMMAND}`;
|
|
181
|
+
if (prepare === LEGACY_PREPARE_COMMAND) {
|
|
182
|
+
scripts.prepare = PREPARE_COMMAND;
|
|
183
|
+
return 'upgraded';
|
|
153
184
|
}
|
|
154
|
-
|
|
155
|
-
|
|
185
|
+
const missing = PREPARE_PROJECTIONS.filter(
|
|
186
|
+
([script]) => !prepare.includes(script),
|
|
187
|
+
).map(([, command]) => command);
|
|
188
|
+
if (missing.length === 0) return 'already-present';
|
|
189
|
+
scripts.prepare = [prepare, ...missing].join(' && ');
|
|
156
190
|
return 'appended';
|
|
157
191
|
}
|
|
158
192
|
|
|
@@ -190,8 +224,8 @@ export function ensurePackageJson(ctx) {
|
|
|
190
224
|
scriptsPrepare: ensurePrepareScript(pkg.scripts),
|
|
191
225
|
scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
|
|
192
226
|
};
|
|
193
|
-
const mutated = Object.values(outcomes).some(
|
|
194
|
-
(v)
|
|
227
|
+
const mutated = Object.values(outcomes).some((v) =>
|
|
228
|
+
PACKAGE_JSON_MUTATIONS.has(v),
|
|
195
229
|
);
|
|
196
230
|
if (mutated) writeJson(pkgPath, pkg, fsImpl);
|
|
197
231
|
return { ...outcomes, path: pkgPath, mutated };
|
|
@@ -309,8 +343,9 @@ async function validateAgentrc(ctx) {
|
|
|
309
343
|
*
|
|
310
344
|
* @param {object} ctx
|
|
311
345
|
* @param {typeof fs} [ctx.fsImpl]
|
|
346
|
+
* @param {readonly string[]} [keys] - Restrict to these block keys (default: all).
|
|
312
347
|
*/
|
|
313
|
-
export function ensureGitignore(ctx) {
|
|
348
|
+
export function ensureGitignore(ctx, keys = Object.keys(GITIGNORE_BLOCKS)) {
|
|
314
349
|
const { fsImpl = fs } = ctx;
|
|
315
350
|
const target = path.join(ctx.projectRoot, '.gitignore');
|
|
316
351
|
const existing = fsImpl.existsSync(target)
|
|
@@ -318,7 +353,8 @@ export function ensureGitignore(ctx) {
|
|
|
318
353
|
: '';
|
|
319
354
|
let body = existing;
|
|
320
355
|
const outcomes = {};
|
|
321
|
-
for (const
|
|
356
|
+
for (const key of keys) {
|
|
357
|
+
const def = GITIGNORE_BLOCKS[key];
|
|
322
358
|
if (def.pattern.test(body)) {
|
|
323
359
|
outcomes[key] = 'already-present';
|
|
324
360
|
continue;
|