ferst-core 0.6.1 → 0.6.2

package/bin/ferst-update.mjs

@@ -46,6 +46,8 @@ export function isDirectInvocation(argv1) {
 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) ───────────────────────────
 
@@ -155,6 +157,33 @@ export function tail(text, n = 40) {
   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'] });
@@ -181,6 +210,16 @@ function readInstalledCoreVersion(cwd) {
   }
 }
 
+/** 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());
@@ -240,6 +279,8 @@ function main() {
   }
   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) {
@@ -263,12 +304,13 @@ function main() {
 
   // 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) {
-    const latest = (tryExec('npm view ferst-core version', cwd) || '').trim();
+    dryLatest = (tryExec('npm view ferst-core version', cwd) || '').trim() || null;
     const current = readInstalledCoreVersion(cwd);
-    console.log(`ferst-update: ferst-core installed=${current ?? '(none)'} latest=${latest || '(unknown)'}`);
+    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 ...');
@@ -302,6 +344,9 @@ function main() {
   // 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;
   }
@@ -315,12 +360,25 @@ function main() {
     }
   }
 
-  // 5. Summary.
+  // 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}; build + check:thin green.`,
+    `ferst-update: DONE — scaffold files updated: ${scaffoldCount}; ${coreLine}; ` +
+      `stamped ${SITE_META}: template ${stampSha}, core ${coreVersion ?? '(unknown)'}; build + check:thin green.`,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.6.1",
+  "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",