ferst-core 0.6.0 → 0.6.2

package/bin/ferst-update.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+// ferst-update — bring a seeded thin-client repo up to date, from the repo alone:
+//
+//   1. latest template SCAFFOLD   (via git: overwrite the template-owned paths)
+//   2. latest ENGINE (ferst-core) (via npm: install @latest, align coreRange)
+//   3. VERIFY                      (npm run build && npm run check:thin)
+//
+// Run it in a client repo root:
+//
+//   npx --no-install ferst-update            # sync scaffold + bump core + verify
+//   npx --no-install ferst-update --dry-run  # fetch + show what WOULD change; no writes
+//   npx --no-install ferst-update --no-core  # scaffold sync only; skip the npm bump
+//
+// The template-owned paths and the git upstream come from the repo's own
+// `ferst-template.json` (the ownership manifest). Client paths are NEVER touched —
+// the scaffold sync is a per-path OVERWRITE from upstream, conflict-free by
+// construction (see docs/CLIENT-TEMPLATE-ARCHITECTURE.md, Workstream D). It never
+// merges/rebases (the CMS bot commits to client repos continuously; a history merge
+// would race live content).
+//
+// On a failed build/check after a `@latest` bump the tree is LEFT AS-IS and the exit
+// is non-zero: a failed latest bump is a real incompatibility to surface for a
+// human/agent to fix, not to hide behind a silent revert.
+import { readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * True when this file is being run as a CLI (not imported). Handles npm's
+ * `node_modules/.bin` **symlink**: there `process.argv[1]` is the symlink path but
+ * `import.meta.url` is the realpath, so a plain `===` check silently skips `main()`
+ * — the bug this guards against.
+ */
+export function isDirectInvocation(argv1) {
+  if (!argv1) return false;
+  if (import.meta.url === pathToFileURL(argv1).href) return true;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+  } catch {
+    return false;
+  }
+}
+
+/** Fallback template upstream when the manifest doesn't pin one (the template is the SSOT). */
+export const DEFAULT_UPSTREAM = 'https://github.com/MyAI4WebDev/ferst-client-template.git';
+/** The ownership manifest a seeded client repo carries at its root. */
+export const MANIFEST = 'ferst-template.json';
+/** The per-site provenance/config file a client repo carries at its root (gitBase, etc.). */
+export const SITE_META = 'ferst-site.json';
+
+// ── pure helpers (unit-tested; no shell, no fs writes) ───────────────────────────
+
+/** Parse the flags this bin understands. Pass `process.argv`. */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  return {
+    dryRun: args.includes('--dry-run'),
+    noCore: args.includes('--no-core'),
+    help: args.includes('--help') || args.includes('-h'),
+  };
+}
+
+/** Parse + shallow-validate the manifest JSON. Throws with a clear message. */
+export function parseManifest(raw) {
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`ferst-update: ${MANIFEST} is not valid JSON — ${e.message}`);
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`ferst-update: ${MANIFEST} must be a JSON object.`);
+  }
+  return obj;
+}
+
+/** The template-owned paths to overwrite from upstream. Throws if missing/empty. */
+export function resolveOwnedPaths(manifest) {
+  const owned = manifest.ownedPaths;
+  if (!Array.isArray(owned) || owned.length === 0) {
+    throw new Error(`ferst-update: ${MANIFEST} declares no "ownedPaths" — nothing to sync.`);
+  }
+  if (owned.some((p) => typeof p !== 'string' || !p.trim())) {
+    throw new Error(`ferst-update: ${MANIFEST} "ownedPaths" must all be non-empty strings.`);
+  }
+  return owned;
+}
+
+/**
+ * The template git URL to sync the scaffold from. Uses the manifest's `upstream`
+ * when present; otherwise falls back to the canonical template repo and flags it so
+ * the caller can warn (older templates predate the `upstream` field).
+ * @returns {{ url: string, defaulted: boolean }}
+ */
+export function resolveUpstream(manifest) {
+  const u = manifest.upstream;
+  if (typeof u === 'string' && u.trim()) return { url: u.trim(), defaulted: false };
+  return { url: DEFAULT_UPSTREAM, defaulted: true };
+}
+
+/** The caret range that pins an installed version to its major.minor (e.g. 0.6.3 → ^0.6). */
+export function coreRangeFor(version) {
+  const m = String(version).trim().replace(/^v/, '').match(/^(\d+)\.(\d+)/);
+  if (!m) throw new Error(`ferst-update: could not parse ferst-core version "${version}".`);
+  return `^${m[1]}.${m[2]}`;
+}
+
+/** Read the `version` out of a package.json's text. Throws if absent. */
+export function extractVersion(pkgJsonText) {
+  let v;
+  try {
+    v = JSON.parse(pkgJsonText)?.version;
+  } catch (e) {
+    throw new Error(`ferst-update: could not parse installed package.json — ${e.message}`);
+  }
+  if (typeof v !== 'string' || !v.trim()) {
+    throw new Error('ferst-update: installed ferst-core has no version.');
+  }
+  return v.trim();
+}
+
+/**
+ * Decide whether/what the manifest's `coreRange` should become for a freshly
+ * installed version. Pure: the write is the caller's job.
+ * @returns {{ next: string, changed: boolean }}
+ */
+export function computeCoreRangeUpdate(currentRange, installedVersion) {
+  const next = coreRangeFor(installedVersion);
+  return { next, changed: currentRange !== next };
+}
+
+/**
+ * Replace the manifest's `coreRange` value in place, preserving the file's exact
+ * formatting/comments (regex, like ferst-set-cms-branch stamps `branch:`). Returns
+ * the new text, or null when there is no `coreRange` field to replace.
+ */
+export function replaceCoreRange(raw, next) {
+  const RANGE = /("coreRange"\s*:\s*")[^"]*(")/;
+  if (!RANGE.test(raw)) return null;
+  return raw.replace(RANGE, `$1${next}$2`);
+}
+
+/**
+ * The default branch name from `git ls-remote --symref <remote> HEAD` output
+ * (`ref: refs/heads/<branch>\tHEAD`). Null when it can't be read. Pure.
+ */
+export function parseDefaultBranch(symrefOutput) {
+  if (!symrefOutput) return null;
+  const m = symrefOutput.match(/ref:\s+refs\/heads\/(\S+)\s+HEAD/);
+  return m ? m[1] : null;
+}
+
+/** The last `n` lines of a (possibly huge) command output, for a concise failure tail. */
+export function tail(text, n = 40) {
+  const lines = String(text ?? '').replace(/\s+$/, '').split(/\r?\n/);
+  return lines.slice(-n).join('\n');
+}
+
+/**
+ * Build the provenance "drift stamp" for a completed update: WHICH template commit and
+ * core version this repo landed on, and when. Pure — the write is the caller's job.
+ * @param {{ upstream?: string, commit?: string|null, coreVersion?: string|null, now?: Date|string }} p
+ * @returns {{ templateUpstream: string|null, templateCommit: string|null, coreVersion: string|null, at: string }}
+ */
+export function buildProvenance({ upstream, commit, coreVersion, now = new Date() } = {}) {
+  return {
+    templateUpstream: upstream ?? null,
+    templateCommit: commit ?? null,
+    coreVersion: coreVersion ?? null,
+    at: typeof now === 'string' ? now : now.toISOString(),
+  };
+}
+
+/**
+ * Merge a provenance stamp into an existing ferst-site.json object under `lastUpdate`,
+ * preserving every other field (gitBase, productionBranch, unknown keys) and overwriting
+ * any prior `lastUpdate`. Pass null (no ferst-site.json yet) → a fresh object with just
+ * the stamp. Pure — never mutates the input.
+ * @returns {object} the object to write back
+ */
+export function mergeSiteMeta(existing, provenance) {
+  const base = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
+  return { ...base, lastUpdate: provenance };
+}
+
+// ── thin side-effecting shell (kept out of the pure helpers above) ────────────────
+
+const exec = (cmd, cwd) => execSync(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const tryExec = (cmd, cwd) => { try { return exec(cmd, cwd); } catch { return null; } };
+const git = (args, cwd) => exec(`git ${args}`, cwd);
+const tryGit = (args, cwd) => tryExec(`git ${args}`, cwd);
+const q = (s) => `"${s}"`;
+
+/** Run a command capturing combined stdout+stderr and the exit code (never throws). */
+function capture(cmd, cwd) {
+  try {
+    return { code: 0, out: exec(cmd, cwd) };
+  } catch (e) {
+    return { code: typeof e.status === 'number' ? e.status : 1, out: `${e.stdout ?? ''}${e.stderr ?? ''}` };
+  }
+}
+
+/** The ferst-core version currently installed in the client's node_modules, or null. */
+function readInstalledCoreVersion(cwd) {
+  try {
+    return extractVersion(readFileSync(resolve(cwd, 'node_modules/ferst-core/package.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** The repo's ferst-site.json parsed to an object, or null when absent/unreadable/non-object. */
+function readSiteMeta(cwd) {
+  try {
+    const parsed = JSON.parse(readFileSync(resolve(cwd, SITE_META), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Ensure an `upstream` remote points at `url` (add, or set-url if it already exists). */
+function ensureUpstream(url, cwd) {
+  const remotes = (tryGit('remote', cwd) || '').split(/\r?\n/).map((s) => s.trim());
+  if (remotes.includes('upstream')) git(`remote set-url upstream ${q(url)}`, cwd);
+  else git(`remote add upstream ${q(url)}`, cwd);
+}
+
+function printHelp() {
+  console.log(`ferst-update — bring a seeded thin-client repo up to date (scaffold + ferst-core).
+
+Usage (run in a client repo root):
+  ferst-update            sync template scaffold, bump ferst-core@latest, then build + check:thin
+  ferst-update --dry-run  fetch upstream and show what WOULD change; make no writes
+  ferst-update --no-core  scaffold sync only; skip the ferst-core npm bump
+  ferst-update --help     show this help
+
+Reads ferst-template.json for the upstream template URL and the template-owned paths.
+Client paths are never touched. On build/check failure the tree is left as-is (exit 1).`);
+}
+
+function main() {
+  const { dryRun, noCore, help } = parseArgs(process.argv);
+  if (help) { printHelp(); return; }
+  const cwd = process.cwd();
+
+  // 1. Read + validate the ownership manifest.
+  const manifestPath = resolve(cwd, MANIFEST);
+  let raw;
+  try {
+    raw = readFileSync(manifestPath, 'utf8');
+  } catch {
+    console.error(`ferst-update: no ${MANIFEST} in ${cwd} — run this in a seeded client repo root.`);
+    process.exit(1);
+  }
+  let manifest, ownedPaths, upstream;
+  try {
+    manifest = parseManifest(raw);
+    ownedPaths = resolveOwnedPaths(manifest);
+    upstream = resolveUpstream(manifest);
+  } catch (e) {
+    console.error(String(e.message ?? e));
+    process.exit(1);
+  }
+  if (upstream.defaulted) {
+    console.warn(`ferst-update: ${MANIFEST} has no "upstream" — defaulting to ${DEFAULT_UPSTREAM}`);
+  }
+
+  // 2. Git scaffold sync — overwrite the template-owned paths from upstream's default
+  //    branch. Never a merge/rebase; path-checkout works across unrelated histories.
+  try {
+    ensureUpstream(upstream.url, cwd);
+    console.log(`ferst-update: fetching ${upstream.url} ...`);
+    git('fetch upstream', cwd);
+  } catch (e) {
+    console.error(`ferst-update: git fetch failed — ${tail(e.stderr || e.message, 10)}`);
+    process.exit(1);
+  }
+  const branch = parseDefaultBranch(tryGit('ls-remote --symref upstream HEAD', cwd)) || 'main';
+  console.log(`ferst-update: upstream default branch = ${branch}`);
+  // The exact template commit this run syncs from (for the provenance stamp / #18 ledger).
+  const templateCommit = (tryGit(`rev-parse upstream/${branch}`, cwd) || '').trim() || null;
+
+  let scaffoldCount = 0; // files the scaffold sync touched (counted BEFORE the npm churn)
+  if (dryRun) {
+    const spec = ownedPaths.map(q).join(' ');
+    const diff = (tryGit(`diff --stat upstream/${branch} -- ${spec}`, cwd) || '').trim();
+    console.log('ferst-update: --dry-run — scaffold changes that WOULD apply:');
+    console.log(diff ? diff : '  (no scaffold changes)');
+  } else {
+    for (const p of ownedPaths) {
+      // Per-path so one path that upstream no longer ships (pathspec no-match) can't
+      // abort the whole sync — warn and continue.
+      if (tryGit(`checkout upstream/${branch} -- ${q(p)}`, cwd) === null) {
+        console.warn(`ferst-update: could not sync "${p}" (not present upstream?) — skipped.`);
+      }
+    }
+    const status = (tryGit('status --short', cwd) || '').trim();
+    scaffoldCount = status ? status.split(/\r?\n/).filter(Boolean).length : 0;
+    console.log('ferst-update: scaffold synced. git status --short:');
+    console.log(status ? status : '  (working tree clean — scaffold already current)');
+  }
+
+  // 3. Engine (ferst-core) update.
+  let coreBump = null; // { before, after } once bumped
+  let dryLatest = null; // dry-run only: the version `@latest` WOULD install (for the stamp preview)
+  if (noCore) {
+    console.log('ferst-update: --no-core — skipping the ferst-core npm bump.');
+  } else if (dryRun) {
+    dryLatest = (tryExec('npm view ferst-core version', cwd) || '').trim() || null;
+    const current = readInstalledCoreVersion(cwd);
+    console.log(`ferst-update: ferst-core installed=${current ?? '(none)'} latest=${dryLatest || '(unknown)'}`);
+  } else {
+    const before = readInstalledCoreVersion(cwd);
+    console.log('ferst-update: npm install ferst-core@latest --save ...');
+    const r = capture('npm install ferst-core@latest --save', cwd);
+    if (r.code !== 0) {
+      console.error(`ferst-update: FAILED at "npm install ferst-core@latest" (exit ${r.code}).`);
+      console.error(tail(r.out, 40));
+      process.exit(1);
+    }
+    const after = readInstalledCoreVersion(cwd);
+    if (!after) {
+      console.error('ferst-update: ferst-core not found in node_modules after install.');
+      process.exit(1);
+    }
+    coreBump = { before, after };
+
+    // Align the manifest's coreRange to the installed major.minor.
+    const currentRange = typeof manifest.coreRange === 'string' ? manifest.coreRange : '';
+    const { next, changed } = computeCoreRangeUpdate(currentRange, after);
+    if (changed) {
+      const rewritten = replaceCoreRange(raw, next);
+      if (rewritten) {
+        writeFileSync(manifestPath, rewritten);
+        console.log(`ferst-update: coreRange ${currentRange || '(unset)'} → ${next}`);
+      } else {
+        console.warn(`ferst-update: no "coreRange" field in ${MANIFEST} to update (installed ${after}).`);
+      }
+    }
+  }
+
+  // 4. Verify — a failed @latest bump is a real incompatibility to surface, so on
+  //    failure we print the tail and exit non-zero WITHOUT reverting.
+  if (dryRun) {
+    const wouldCommit = templateCommit ? templateCommit.slice(0, 7) : '(unknown)';
+    const wouldCore = (noCore ? readInstalledCoreVersion(cwd) : dryLatest) ?? '(unknown)';
+    console.log(`ferst-update: --dry-run — WOULD stamp ${SITE_META}: template ${wouldCommit}, core ${wouldCore} (no write).`);
+    console.log('ferst-update: --dry-run complete (no writes, no verify).');
+    return;
+  }
+  for (const step of ['build', 'check:thin']) {
+    console.log(`ferst-update: npm run ${step} ...`);
+    const r = capture(`npm run ${step}`, cwd);
+    if (r.code !== 0) {
+      console.error(`ferst-update: FAILED at "npm run ${step}" (exit ${r.code}). Tree left as-is for a human/agent to fix.`);
+      console.error(tail(r.out, 40));
+      process.exit(1);
+    }
+  }
+
+  // 5. Provenance drift stamp — record WHICH template commit + core version this repo
+  //    landed on (only after a fully-successful update), so the repo and the future fleet
+  //    drift ledger (#18) always know its state. MERGE: preserve gitBase/productionBranch
+  //    and any other existing ferst-site.json fields.
+  const coreVersion = coreBump?.after ?? readInstalledCoreVersion(cwd);
+  const provenance = buildProvenance({ upstream: upstream.url, commit: templateCommit, coreVersion });
+  writeFileSync(
+    resolve(cwd, SITE_META),
+    `${JSON.stringify(mergeSiteMeta(readSiteMeta(cwd), provenance), null, 2)}\n`,
+  );
+  const stampSha = templateCommit ? templateCommit.slice(0, 7) : '(unknown)';
+
+  // 6. Summary.
+  const coreLine = coreBump
+    ? `ferst-core ${coreBump.before ?? '(none)'} → ${coreBump.after}`
+    : 'ferst-core unchanged (--no-core)';
+  console.log(
+    `ferst-update: DONE — scaffold files updated: ${scaffoldCount}; ${coreLine}; ` +
+      `stamped ${SITE_META}: template ${stampSha}, core ${coreVersion ?? '(unknown)'}; build + check:thin green.`,
+  );
+}
+
+// Run when invoked directly as a bin — including via npm's node_modules/.bin symlink.
+if (isDirectInvocation(process.argv[1])) {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",
@@ -50,7 +50,8 @@
   "bin": {
     "ferst-check-thin": "bin/check-thin.mjs",
     "ferst-set-cms-branch": "bin/set-cms-branch.mjs",
-    "ferst-cms-config": "bin/cms-config.mjs"
+    "ferst-cms-config": "bin/cms-config.mjs",
+    "ferst-update": "bin/ferst-update.mjs"
   },
   "dependencies": {
     "zod": "^3.25.0"