yadflow 4.0.0-next.3 → 4.0.0

package/cli/commit.mjs

@@ -1,35 +1,48 @@
 // `yad commit` — commit by the SDLC conventions (CONTRIBUTING.md / config.yaml build).
 // Subject is Conventional Commits; trailers are emitted in the fixed order
-// Task -> Contract-Change -> Co-Authored-By. The human git author OWNS the commit; the AI is only a
-// co-author (flagged with --ai, or `none` for human-only). An atomic-commit guard keeps diffs small.
+// Task -> Contract-Change -> Ledger-Override -> Co-Authored-By. The human git author OWNS the commit;
+// the AI is only a co-author (flagged with --ai, or `none` for human-only). An atomic-commit guard keeps diffs small.
 // An explicit --task id is validated against the spec-link gate contract (<story>-T<NN>) so a
 // malformed trailer fails locally rather than after a push.
+//
+// `--manual --reason` (E49) is the door past the Product's local ledger hook (E48): the commit runs with
+// the hook's skip switch, and the reason is recorded as a `Ledger-Override:` trailer so the reviewer —
+// and the CI `ledger-guard` check, which quotes it — can see why. It opens this machine's hook and
+// nothing more: CI still fails the commit, because anyone can type a trailer.
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, run, exists } from './lib.mjs';
 import {
   COMMIT_TYPES, AI_COAUTHORS, ATOMIC_FILE_LIMIT,
-  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, TASK_ID_RE,
+  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, LEDGER_OVERRIDE_TRAILER, COAUTHOR_TRAILER, TASK_ID_RE,
   productConfigPath,
 } from './manifest.mjs';
+import { OWNING_COMMIT_ENV, stagedLedgerHits } from './hook.mjs';
 
 // PURE — unit tested directly. Build the full commit message text.
-export function buildCommitMessage({ type, subject, task, contractChange = false, ai = 'none', body = '' }) {
+export function buildCommitMessage({ type, subject, task, contractChange = false, ai = 'none', body = '', override = null }) {
   if (!COMMIT_TYPES.includes(type)) throw new Error(`invalid commit type "${type}" (one of: ${COMMIT_TYPES.join(', ')})`);
   if (!subject || !subject.trim()) throw new Error('commit subject is required');
   if (!(ai in AI_COAUTHORS)) throw new Error(`unknown --ai "${ai}" (one of: ${Object.keys(AI_COAUTHORS).join(', ')})`);
   if (/\.$/.test(subject.trim())) throw new Error('subject must not end with a period');
   // A malformed task id (e.g. a bare story `EP-x-S01` with no -T<NN>) commits fine locally but
   // then fails the spec-link CI gate — forcing a history rewrite + force-push. Reject it here so
-  // it never enters a trailer. Well-formed branch-derived ids (taskFromBranch) are stricter and pass;
-  // a lowercase-suffix branch is caught here, matching the case-sensitive spec-link grep.
+  // it never enters a trailer. A branch-derived id (taskFromBranch, which matches without case) is
+  // validated the same way, so `feat/EP-Demo-S01-T01` is caught here too, as spec-link would.
   if (task && !TASK_ID_RE.test(task)) {
-    throw new Error(`invalid --task "${task}" (expected <story>-T<NN>, e.g. EP-x-S01-T02) — the spec-link CI gate would reject it`);
+    throw new Error(`invalid --task "${task}" (expected EP-<slug>-S<n>-T<NN> with a lowercase slug, e.g. EP-x-S01-T02) — the spec-link CI gate would reject it`);
+  }
+
+  // A trailer is one line: a newline in the reason would end it early and start a line git reads as
+  // body text or as a trailer of its own.
+  if (override !== null && (typeof override !== 'string' || !override.trim() || /[\r\n]/.test(override))) {
+    throw new Error('--reason must be one non-empty line (it becomes the Ledger-Override trailer)');
   }
 
   const trailers = [];
   if (task) trailers.push(`${TASK_TRAILER}: ${task}`);
   if (contractChange) trailers.push(`${CONTRACT_CHANGE_TRAILER}: yes`);
+  if (override !== null) trailers.push(`${LEDGER_OVERRIDE_TRAILER}: ${override.trim()}`);
   const co = AI_COAUTHORS[ai];
   if (co) trailers.push(`${COAUTHOR_TRAILER}: ${co.name} <${co.email}>`);
 
@@ -47,11 +60,31 @@ export function taskFromBranch(branch = '') {
 
 export async function runCommit(root, opts = {}) {
   log(c.bold('\nyad commit'));
-  if (!exists(path.join(root, '.git'))) { fail('not a git repo'); process.exitCode = 1; return; }
+  // The repo's top, like every other yad command that commits — except the ledger door: a Product can be a
+  // subfolder of its repo, and the hook's refusal sends the person to `--manual` from there. Only there,
+  // because `--manual` also needs a staged file that hook refuses, so it cannot commit into a parent repo
+  // by accident; and `yad ship` (whose open-pr step needs the top) refuses `--manual`.
+  const inRepo = exists(path.join(root, '.git')) || (opts.manual && run('git', ['rev-parse', '--show-toplevel'], { cwd: root }).ok);
+  if (!inRepo) { fail('not a git repo'); process.exitCode = 1; return; }
+  // --manual and --reason come as a pair: an override with no reason records nothing, and a reason with
+  // no --manual would be silently dropped.
+  if (opts.manual && opts.reason === undefined) { fail('--manual needs --reason "<why>" — the reason is recorded in the commit as a Ledger-Override trailer'); process.exitCode = 1; return; }
+  if (!opts.manual && opts.reason !== undefined) { fail('--reason is only for --manual (the ledger override)'); process.exitCode = 1; return; }
 
   const staged = run('git', ['diff', '--cached', '--name-only'], { cwd: root }).stdout.split('\n').filter(Boolean);
   if (!staged.length) { fail('nothing staged — `git add` your atomic change first'); process.exitCode = 1; return; }
 
+  // An override is recorded only when there is something to override: a staged file the Product's
+  // ledger hook refuses. In a code repo, on a local ledger, or for a new epic's seed, nothing is.
+  // Asked without the skip switch: a YAD_HOOK_DISABLE left set in the shell would hide every hit.
+  const hookEnv = { ...process.env };
+  delete hookEnv.YAD_HOOK_DISABLE;
+  if (opts.manual && !stagedLedgerHits({ cwd: root, env: hookEnv }).hits.length) {
+    fail('--manual: nothing staged here is a file the ledger hook refuses (it guards the CI-owned ledger on a verified Product) — commit without --manual and --reason');
+    process.exitCode = 1;
+    return;
+  }
+
   if (staged.length > ATOMIC_FILE_LIMIT && !opts.force) {
     fail(`${staged.length} files staged (atomic guard: ≤${ATOMIC_FILE_LIMIT}). Split the change, or pass --force.`);
     for (const f of staged) info(f);
@@ -64,8 +97,8 @@ export async function runCommit(root, opts = {}) {
   if (!task) {
     // spec-link is a code-repo gate (REPO_WIRING.common), not a Product gate — so a missing Task trailer
     // is expected on a Product PR (Shape artifact review or Product tooling) and only matters on a repo.
-    const onHub = exists(productConfigPath(root));
-    warn(onHub
+    const onProduct = exists(productConfigPath(root));
+    warn(onProduct
       ? 'no Task trailer (none given and branch has no -S0N-T0N) — fine for a Product PR; required on code-repo tasks (spec-link gate)'
       : 'no Task trailer (none given and branch has no -S0N-T0N) — spec-link gate will fail on a code repo');
   }
@@ -75,17 +108,20 @@ export async function runCommit(root, opts = {}) {
     message = buildCommitMessage({
       type: opts.type, subject: opts.message, task,
       contractChange: !!opts.contractChange, ai: opts.ai || 'none',
+      override: opts.manual ? String(opts.reason) : null,
     });
   } catch (e) { fail(e.message); process.exitCode = 1; return; }
 
   // The --json answer (E1): what was (or would be) committed.
-  const answer = { message, task: task || null, files: staged, contractChange: !!opts.contractChange };
+  const answer = { message, task: task || null, files: staged, contractChange: !!opts.contractChange, manual: !!opts.manual, reason: opts.manual ? String(opts.reason).trim() : null };
   if (opts.dryRun) { log('\n' + c.dim(message) + '\n'); info('dry run — not committed'); return { ...answer, committed: false, dryRun: true }; }
 
-  const r = run('git', ['commit', '-m', message], { cwd: root });
+  // Only yad's own hook is skipped — any other pre-commit hook (husky, lint-staged) still runs.
+  const r = run('git', ['commit', '-m', message], { cwd: root, ...(opts.manual ? { env: OWNING_COMMIT_ENV() } : {}) });
   if (!r.ok) { fail(`git commit failed — ${r.stderr.split('\n')[0] || r.code}`); process.exitCode = 1; return { ...answer, committed: false, dryRun: false }; }
   ok(`committed ${staged.length} file(s)${task ? ` for ${task}` : ''}`);
   if (opts.contractChange) warn('Contract-Change: yes — this routes back to the architecture gate');
+  if (opts.manual) warn('Ledger-Override recorded — the ledger-guard check on the pull request still fails this commit; the reason is there for the reviewer');
   const sha = run('git', ['rev-parse', 'HEAD'], { cwd: root });
   return { ...answer, committed: true, dryRun: false, commit: sha.ok ? sha.stdout : null };
 }

package/cli/docs.mjs

@@ -6,12 +6,12 @@
 // and the manifest-hash staleness check (reusing the head-sha idea from repo.mjs). It NEVER touches
 // epic state, approvals, or the contract lock — docs are an output enrichment, not a gate.
 //
-// Pure mapping fns (deployTargetFromHub / siteBasePath / docsArtifactHash / docsStale / pagesWorkflow)
+// Pure mapping fns (deployTargetFromProduct / siteBasePath / docsArtifactHash / docsStale / pagesWorkflow)
 // are exported for unit tests; the side-effecting runDocs orchestrates them.
 import path from 'node:path';
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
-import { c, log, ok, info, warn, hand, fail, readJSON, run, has, exists } from './lib.mjs';
+import { c, log, ok, info, warn, hand, fail, readJSON, runLauncher, has, exists } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import { detectPlatform, platformReady } from './platform.mjs';
 import { gitHead } from './setup.mjs';
@@ -35,8 +35,8 @@ export function manifestPath(root, { epic, overview } = {}) {
 
 // ---- pure: platform/target + base path ----------------------------------------------------------
 // hub.json platform -> the default Pages target (github-pages | gitlab-pages | none/build-only).
-export function deployTargetFromHub(hub = {}) {
-  const platform = hub?.platform || detectPlatform(hub?.git_url || '');
+export function deployTargetFromProduct(productConfig = {}) {
+  const platform = productConfig?.platform || detectPlatform(productConfig?.git_url || '');
   if (platform === 'github') return 'github-pages';
   if (platform === 'gitlab') return 'gitlab-pages';
   return 'none';
@@ -175,31 +175,33 @@ on:
   workflow_dispatch:
 permissions:
   contents: read
-  pages: write
-  id-token: write
 concurrency:
   group: yad-docs-pages
   cancel-in-progress: true
 jobs:
   build-deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write # publish the site
+      id-token: write # prove to Pages that this run is the deploy
     environment:
       name: github-pages
       url: \${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 20
       - name: Build the overview + per-epic sites into ./public
         run: |
 ${BUILD_PUBLIC.map((l) => `          ${l}`).join('\n')}
-      - uses: actions/configure-pages@v6
-      - uses: actions/upload-pages-artifact@v5
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: public
       - id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
 `;
 }
 export function pagesWorkflowPath(platform) {
@@ -233,8 +235,8 @@ function buildSite(root, t, { npmOptional = false } = {}) {
   const install = exists(path.join(dir, 'package-lock.json')) ? ['ci'] : ['install'];
   const again = 'fix the error npm printed above, then run the command again';
   log(`  ${c.dim('$')} npm ${install[0]} ${c.dim(`(${rel})`)}`);
-  if (!run('npm', install, { cwd: dir, stdio: 'inherit' }).ok) return failed(`${site}: npm ${install[0]} failed`, again);
-  if (!run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' }).ok) return failed(`${site}: npm run build failed`, again);
+  if (!runLauncher('npm', install, { cwd: dir, stdio: 'inherit' }).ok) return failed(`${site}: npm ${install[0]} failed`, again);
+  if (!runLauncher('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' }).ok) return failed(`${site}: npm run build failed`, again);
   ok(`built ${site} ${c.dim('→ ' + path.relative(root, path.join(dir, 'dist')))}`);
   return { site, built: true, error: null };
 }