yadflow 3.18.1 → 4.0.0-next.1

package/cli/docs.mjs

@@ -12,7 +12,7 @@ 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 { PROJECT_FILES, VERSION } from './manifest.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
 import { detectPlatform, platformReady } from './platform.mjs';
 import { gitHead } from './setup.mjs';
 import { contractSurfaceHash } from './epic-state.mjs';
@@ -95,8 +95,33 @@ export function repoHeadsFor(root, repos = [], registry = { repos: [] }) {
   return out;
 }
 
+// The version of the docs shell a per-epic site is copied from: the `version` in the template's own
+// package.json. It moves only when the shell changes — cli/test.mjs pins it to a fingerprint of the
+// template, so an edit to the shell cannot land without a new version.
+//
+// It replaced the yad CLI VERSION here, which moves on EVERY release: each publish marked every docs site
+// "doc shell upgraded" whether or not the shell had changed. A manifest written before this carries that
+// CLI version as `templateVersion`, which is never compared. What such a manifest is read as instead is
+// LEGACY_SHELL_VERSION, below.
+//
+// Read when a freshness check asks, never at import: every `yad` command loads this module, and a copy of
+// the CLI without `skills/` beside it (a test harness, a partial checkout) must still start. No template
+// found means no shell version, so that one comparison is skipped.
+export function shellVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../skills/yad-docs/templates/app/package.json', import.meta.url), 'utf8')).version || null;
+  } catch { return null; }
+}
+
+// The shell version every site built before `shellVersion` existed was built on. Exact, not a guess: the
+// template's package.json has said `0.0.0` since its first commit, so a manifest that records only the old
+// `templateVersion` came from that shell. Reading it this way reports nothing today, and still reports
+// the first real shell upgrade — ignoring the old manifest instead would have missed that for ever,
+// because only a skill rewrites a manifest and nothing prompts one to.
+export const LEGACY_SHELL_VERSION = '0.0.0';
+
 // Compare a build manifest to the current world; list the concrete reasons it is stale.
-export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVersion } = {}) {
+export function docsStale(manifest, { artifactHash, repoHeads = {}, shellVersion } = {}) {
   const reasons = [];
   if (!manifest) return { stale: true, reasons: ['never built'] };
   if (artifactHash && manifest.artifactHash && artifactHash !== manifest.artifactHash) {
@@ -106,8 +131,9 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVers
     const was = (manifest.repoHeads || {})[repo];
     if (head && was && head !== was) reasons.push(`repo ${repo} HEAD advanced`);
   }
-  if (templateVersion && manifest.templateVersion && templateVersion !== manifest.templateVersion) {
-    reasons.push(`doc shell upgraded (${manifest.templateVersion} → ${templateVersion})`);
+  const builtOn = manifest.shellVersion || (manifest.templateVersion ? LEGACY_SHELL_VERSION : null);
+  if (shellVersion && builtOn && shellVersion !== builtOn) {
+    reasons.push(`doc shell upgraded (${builtOn} → ${shellVersion})`);
   }
   return { stale: reasons.length > 0, reasons };
 }
@@ -181,16 +207,36 @@ export function pagesWorkflowPath(platform) {
 }
 
 // ---- build (subprocess) -------------------------------------------------------------------------
-function buildSite(dir) {
-  if (!exists(dir)) { warn(`no generated site at ${path.relative(process.cwd(), dir)} — run the yad-docs skill first`); return { ok: false, missing: true }; }
-  if (!has('npm')) { warn('npm not on PATH — cannot build; the CI workflow will build on push'); return { ok: false, noNpm: true }; }
+// Builds one site and says what happened: `{ site, built, error }`, where `error` is why it was not
+// built (null when it was). Every caller — build, deploy, sync --refresh — reads that one row, so a
+// failure is said the same way on each path. A failure sets exit 1 and is a `fail` with its `hand`
+// right under it: under --json that pair IS the refusal, and a later `hand` (deploy's "no Pages
+// platform") can never become a failed build's hint. The one miss that is only a warning is npm not on
+// PATH for a deploy or a refresh, which the CI workflow builds on push (`npmOptional`).
+function buildSite(root, t, { npmOptional = false } = {}) {
+  const dir = siteDir(root, t);
+  const rel = path.relative(root, dir) || '.';
+  const site = label(t);
+  const failed = (error, next) => {
+    fail(error);
+    hand(next);
+    process.exitCode = 1;
+    return { site, built: false, error };
+  };
+  if (!exists(dir)) return failed(`${site}: no generated site at ${rel}`, `run the ${t.overview ? 'yad-docs-overview' : 'yad-docs'} skill first`);
+  if (!has('npm')) {
+    const error = `${site}: npm not on PATH — cannot build`;
+    if (!npmOptional) return failed(error, 'install npm (or put it on PATH), then run the command again');
+    warn(`${error}; the CI workflow will build on push`);
+    return { site, built: false, error };
+  }
   const install = exists(path.join(dir, 'package-lock.json')) ? ['ci'] : ['install'];
-  log(`  ${c.dim('$')} npm ${install[0]} ${c.dim(`(${path.relative(process.cwd(), dir)})`)}`);
-  const i = run('npm', install, { cwd: dir, stdio: 'inherit' });
-  if (!i.ok) { fail('npm install failed'); return { ok: false }; }
-  const b = run('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
-  if (!b.ok) { fail('npm run build failed'); return { ok: false }; }
-  return { ok: true, dist: path.join(dir, 'dist') };
+  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);
+  ok(`built ${site} ${c.dim('→ ' + path.relative(root, path.join(dir, 'dist')))}`);
+  return { site, built: true, error: null };
 }
 
 // ---- orchestration ------------------------------------------------------------------------------
@@ -205,49 +251,57 @@ export async function runDocs(root, { action = 'list', epic, overview, sync } =
       info(`target ${c.cyan(docs.target)}  scope ${docs.scope}  base ${docs.basePath}  ${docs.source === 'unavailable' ? c.yellow('(build-only)') : ''}`);
     }
     log(c.bold('\ngenerated sites'));
-    if (!targets.length) { info('none generated yet'); return { sites: 0 }; }
+    if (!targets.length) { info('none generated yet'); return { action, target: docs?.target ?? null, sites: [] }; }
     for (const t of targets) reportFreshness(root, t);
-    return { sites: targets.length };
+    return { action, target: docs?.target ?? null, sites: targets.map((t) => label(t)) };
   }
 
   if (action === 'build' || action === 'deploy') {
-    let built = 0;
-    for (const t of targets) {
-      const r = buildSite(siteDir(root, t));
-      if (r.ok) { built++; ok(`built ${label(t)} ${c.dim('→ ' + path.relative(root, r.dist))}`); }
-    }
+    // Every site is tried, even after one fails; the run exits 1 if any did (buildSite sets it).
+    const sites = targets.map((t) => buildSite(root, t, { npmOptional: action === 'deploy' }));
+    const built = sites.filter((s) => s.built).length;
     if (action === 'deploy') {
       const platform = docs ? (docs.target === 'gitlab-pages' ? 'gitlab' : docs.target === 'github-pages' ? 'github' : null) : null;
+      // Both arms say the same thing about what was built here; only a run where every site built ends on ✓.
+      const all = built > 0 && built === sites.length;
+      const here = all ? null : built ? `only ${built} of ${sites.length} sites built here` : 'nothing was built here';
       if (!platform || !platformReady(platform)) {
-        hand('no Pages platform/CLI — built locally only; commit + push so the CI workflow can publish (yad docs sync --wire)');
+        hand(`no Pages platform/CLI — ${here ?? 'built locally only'}; commit + push so the CI workflow can publish (yad docs sync --wire)`);
       } else {
-        ok(`deploy via the ${platform} Pages workflow on push (yad docs sync --wire installs it)`);
+        (all ? ok : info)(`${here ? `${here}; ` : ''}deploy via the ${platform} Pages workflow on push (yad docs sync --wire installs it)`);
         if (docs?.basePath) info(`will publish under ${docs.basePath}`);
       }
     }
-    return { built };
+    return { action, built, sites };
   }
 
   if (action === 'sync') {
     if (sync === 'wire') return wirePages(root, docs);
     // check (default) + refresh both compute staleness; refresh additionally rebuilds.
     const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
-    let stale = 0;
+    // One row per site. `built` is null when no build was tried (a check, or a fresh site), so it never
+    // reads as a failed build; a refresh that could not build a stale site exits 1, as a deploy does.
+    const sites = [];
     for (const t of targets) {
       const s = freshness(root, t, registry);
       if (s.stale) {
-        stale++;
         warn(`${label(t)} — ${c.yellow('stale')}: ${s.reasons.join('; ')}`);
-        if (sync === 'refresh') buildSite(siteDir(root, t));
-      } else ok(`${label(t)} ${c.dim('— fresh')}`);
+        const b = sync === 'refresh' ? buildSite(root, t, { npmOptional: true }) : { built: null, error: null };
+        sites.push({ site: label(t), stale: true, built: b.built, error: b.error });
+      } else {
+        ok(`${label(t)} ${c.dim('— fresh')}`);
+        sites.push({ site: label(t), stale: false, built: null, error: null });
+      }
     }
+    const stale = sites.filter((s) => s.stale).length;
+    const built = sites.filter((s) => s.built).length;
     if (stale && sync !== 'refresh') hand('regenerate content with the yad-docs / yad-docs-overview skill (the AI step), then `yad docs deploy`');
-    return { stale };
+    return { action, sync, stale, built, sites };
   }
 
   fail(`unknown docs action: ${action} (list | build | deploy | sync)`);
   process.exitCode = 1;
-  return {};
+  return { action };
 }
 
 // ---- helpers ------------------------------------------------------------------------------------
@@ -267,10 +321,12 @@ function label(t) { return t.overview ? 'overview (docs/sdlc-site)' : `epic ${t.
 function freshness(root, t, registry) {
   const manifest = readJSON(manifestPath(root, t), null);
   if (t.overview) {
-    // The overview is generated from the project pipeline definition, not an epic's artifacts.
+    // The overview is generated from the project pipeline definition, not an epic's artifacts. No shell
+    // version: the overview is copied from the shell once and updated in place after that
+    // (yad-docs-overview, Step 3), so a shell upgrade is not a reason to rebuild it.
     const files = ['skills/sdlc/config.yaml', 'skills/sdlc/module-help.csv', 'docs/diagrams/sdlc-overview.mmd']
       .map((f) => path.join(root, f)).filter(exists);
-    return docsStale(manifest, { artifactHash: docsArtifactHash(files), templateVersion: VERSION });
+    return docsStale(manifest, { artifactHash: docsArtifactHash(files) });
   }
   const epicMeta = readJSON(path.join(root, 'epics', t.epic, '.sdlc/state.json'), {});
   const repos = epicMeta.repos || [];
@@ -278,7 +334,7 @@ function freshness(root, t, registry) {
   return docsStale(manifest, {
     artifactHash: docsArtifactHash(docsArtifactFiles(root, t.epic), surface || ''),
     repoHeads: repoHeadsFor(root, repos, registry),
-    templateVersion: VERSION,
+    shellVersion: shellVersion(),
   });
 }
 function reportFreshness(root, t) {