ferst-core 0.9.5 → 0.9.7

package/bin/cms-config.mjs

@@ -60,53 +60,10 @@ export function repoSlug() {
   return '';
 }
 
-export const PROD_GIT_BASE = 'https://signin.ferst.co.uk';
-export const DEV_GIT_BASE = 'https://signin-dev.ferst.co.uk';
-
-/**
- * The platform git-proxy origin (CMS `base_url` / `api_root`) for THIS build:
- *   1. `FERST_GIT_BASE` env — explicit override, always wins.
- *   2. committed `ferst-site.json` `gitBase` — an explicit per-site pin (e.g. a
- *      custom proxy); a BYO/seeded site can hard-bind its origin this way.
- *   3. otherwise DERIVE from the deploy environment: the production branch talks to
- *      the prod git-proxy, every other (preview/dev) branch talks to the dev
- *      git-proxy. So a templated repo self-configures per environment on deploy — a
- *      dev-branch build points its CMS at the dev worker and main at prod — with NO
- *      per-client config. (The production branch defaults to `main`; override via
- *      `FERST_PROD_BRANCH` env or `ferst-site.json` `productionBranch`.)
- * This restores the "site respects the environment it's deployed in" binding the old
- * per-branch site config gave, without a per-client file to maintain.
- */
-export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch()) {
-  const fromEnv = env('FERST_GIT_BASE');
-  if (fromEnv) return fromEnv;
-  let prodBranch = env('FERST_PROD_BRANCH') || 'main';
-  try {
-    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
-    if (site && typeof site.gitBase === 'string' && site.gitBase.trim()) return site.gitBase.trim();
-    if (!env('FERST_PROD_BRANCH') && site && typeof site.productionBranch === 'string' && site.productionBranch.trim()) {
-      prodBranch = site.productionBranch.trim();
-    }
-  } catch {
-    /* no ferst-site.json (e.g. the template repo itself) — derive from the branch */
-  }
-  return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
-}
-
-/** The deployment branch: CF Pages env → current git branch → main. */
-export function deploymentBranch() {
-  const cf = env('CF_PAGES_BRANCH');
-  if (cf) return cf;
-  try {
-    const git = execSync('git rev-parse --abbrev-ref HEAD', {
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).toString().trim();
-    if (git && git !== 'HEAD') return git;
-  } catch {
-    /* not a git checkout — fall through */
-  }
-  return 'main';
-}
+// The git-proxy origin lives in lib/git-base.mjs, which components can import: this file is a
+// build-time script whose module scope needs a real filesystem (TEMPLATE_PATH).
+export { PROD_GIT_BASE, DEV_GIT_BASE, resolveGitBase, deploymentBranch } from '../lib/git-base.mjs';
+import { resolveGitBase, deploymentBranch } from '../lib/git-base.mjs';
 
 /** Ferst's managed GitHub org: its sites are on the Basic plan. */
 const MANAGED_OWNER = 'myai4webdev';

package/bin/ferst-modules.mjs

@@ -12,7 +12,7 @@
 import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { resolveGitBase } from './cms-config.mjs';
+import { resolveGitBase } from '../lib/git-base.mjs';
 
 /**
  * True when THIS file is run as a CLI (not imported). Each bin needs its own copy:

package/bin/ferst-update.mjs

@@ -294,6 +294,30 @@ export function mergeSiteMeta(existing, provenance) {
   return { ...base, lastUpdate: provenance };
 }
 
+/**
+ * What the update would leave in one template-owned file: the template's copy, then the
+ * same adjustments the real run makes (package.json keeps the site's own name/description and
+ * takes the canonical engine range; the manifest takes the canonical coreRange). The dry run
+ * compares this, not the raw template copy, with the site's file, so it reports only real
+ * changes (CTK #20, OLR #23). Pure.
+ */
+export function scaffoldFileAfterUpdate(path, upstreamRaw, currentRaw, coreRange) {
+  let out = upstreamRaw;
+  if (path === 'package.json') {
+    if (currentRaw != null) out = keepClientPackageFields(out, currentRaw) ?? out;
+    if (coreRange) out = replacePackageCoreDep(out, coreRange) ?? out;
+  } else if (path === MANIFEST && coreRange) {
+    out = replaceCoreRange(out, coreRange) ?? out;
+  }
+  return out;
+}
+
+/** Whether a new drift stamp records a different state than the last (the time alone isn't). */
+export function stampChanged(previous, next) {
+  if (!previous || typeof previous !== 'object') return true;
+  return ['templateUpstream', 'templateCommit', 'templateVersion', 'coreVersion'].some((k) => (previous[k] ?? null) !== (next[k] ?? null));
+}
+
 // ── thin side-effecting shell (kept out of the pure helpers above) ────────────────
 
 const exec = (cmd, cwd) => execSync(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
@@ -413,11 +437,25 @@ function main() {
 
   let templateVersion = null; // the template version this sync brought (for the manifest + stamp)
   let scaffoldCount = 0; // files the scaffold sync touched (counted BEFORE the npm churn)
+  let dryScaffold = []; // dry-run only: the files the update would really change
   if (dryRun) {
+    // Compare what the update would leave (the site's package identity, the canonical engine
+    // range), not the raw template copy, so only real changes count (CTK #20, OLR #23).
     const spec = syncPaths.map(q).join(' ');
-    const diff = (tryGit(`diff --stat ${TEMPLATE_REMOTE}/${branch} -- ${spec}`, cwd) || '').trim();
+    const target = noCore
+      ? readInstalledCoreVersion(cwd)
+      : (tryExec('npm view ferst-core version', cwd) || '').trim() || readInstalledCoreVersion(cwd);
+    const range = target ? coreRangeFor(target) : null;
+    const candidates = (tryGit(`diff --name-only ${TEMPLATE_REMOTE}/${branch} -- ${spec}`, cwd) || '').split(/\r?\n/).filter(Boolean);
+    for (const f of candidates) {
+      const upstreamRaw = tryGit(`show ${TEMPLATE_REMOTE}/${branch}:${f}`, cwd);
+      let current = null;
+      try { current = readFileSync(resolve(cwd, f), 'utf8'); } catch { /* a file the site doesn't have yet */ }
+      const lf = (t) => t.replace(/\r\n/g, '\n'); // a checkout's line endings aren't a change
+      if (upstreamRaw === null || current === null || lf(scaffoldFileAfterUpdate(f, lf(upstreamRaw), lf(current), range)) !== lf(current)) dryScaffold.push(f);
+    }
     console.log('ferst-update: --dry-run — scaffold changes that WOULD apply:');
-    console.log(diff ? diff : '  (no scaffold changes)');
+    console.log(dryScaffold.length ? dryScaffold.map((f) => `  ${f}`).join('\n') : '  (no scaffold changes)');
   } else {
     // package.json is template-owned, but its identity fields are the client's — keep them.
     const pkgPath = resolve(cwd, 'package.json');
@@ -430,6 +468,10 @@ function main() {
         console.warn(`ferst-update: could not sync "${p}" (not present upstream?) — skipped.`);
       }
     }
+    // `git checkout <tree> -- path` also stages the template's copy. Unstage it, so the index
+    // never holds a copy that the steps below put back (OLR #23 saw `MM`), and a commit takes
+    // only what the update really changed.
+    tryGit(`reset -q -- ${syncPaths.map(q).join(' ')}`, cwd);
     if (clientPkg) {
       try {
         const synced = readFileSync(pkgPath, 'utf8');
@@ -522,7 +564,10 @@ function main() {
   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).`);
+    const prev = readSiteMeta(cwd)?.lastUpdate;
+    const wouldMove = stampChanged(prev, { ...(prev ?? {}), templateCommit: templateCommit ?? null, coreVersion: wouldCore === '(unknown)' ? prev?.coreVersion ?? null : wouldCore });
+    if (!dryScaffold.length && !wouldMove) console.log('ferst-update: --dry-run — nothing to update (scaffold and engine current).');
+    else 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;
   }
@@ -542,10 +587,15 @@ function main() {
   //    and any other existing ferst-site.json fields.
   const coreVersion = coreBump?.after ?? readInstalledCoreVersion(cwd);
   const provenance = buildProvenance({ upstream: upstream.url, commit: templateCommit, coreVersion, templateVersion: templateVersion ?? readTemplateVersion(raw) });
-  writeFileSync(
-    resolve(cwd, SITE_META),
-    `${JSON.stringify(mergeSiteMeta(readSiteMeta(cwd), provenance), null, 2)}\n`,
-  );
+  // Only when the site actually moved: re-stamping just the time left a pointless commit (and
+  // a test-copy redeploy) on every scheduled run.
+  const existingMeta = readSiteMeta(cwd);
+  const restamp = stampChanged(existingMeta?.lastUpdate, provenance);
+  if (restamp) {
+    writeFileSync(resolve(cwd, SITE_META), `${JSON.stringify(mergeSiteMeta(existingMeta, provenance), null, 2)}\n`);
+  } else {
+    console.log(`ferst-update: ${SITE_META} already records this template and engine — not re-stamped.`);
+  }
   const stampSha = templateCommit ? templateCommit.slice(0, 7) : '(unknown)';
 
   // 6. Summary.
@@ -554,7 +604,7 @@ function main() {
     : '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.`,
+      `${restamp ? 'stamped' : 'already recorded in'} ${SITE_META}: template ${stampSha}, core ${coreVersion ?? '(unknown)'}; build + check:thin green.`,
   );
 }
 

package/components/recipes/Form.astro

@@ -7,7 +7,7 @@
  */
 import ContactForm from './ContactForm.astro';
 import { loadFormDefinition } from '../../lib/forms';
-import { resolveGitBase } from '../../bin/cms-config.mjs';
+import { resolveGitBase } from '../../lib/git-base.mjs';
 
 interface Props {
   form: string;

package/lib/git-base.mjs

@@ -0,0 +1,62 @@
+/**
+ * The platform git-proxy origin for this build (the CMS `base_url`, and where the Form block
+ * reads a form's fields). Kept apart from bin/cms-config.mjs so components can import it: that
+ * file is a build-time script whose module scope needs a real filesystem, which an on-request
+ * renderer (Cloudflare Workers) doesn't have. Nothing here runs at import time.
+ */
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+function env(name) {
+  const v = typeof process !== 'undefined' ? process.env?.[name] : undefined;
+  return v && v.trim() ? v.trim() : '';
+}
+
+export const PROD_GIT_BASE = 'https://signin.ferst.co.uk';
+export const DEV_GIT_BASE = 'https://signin-dev.ferst.co.uk';
+
+/**
+ * The platform git-proxy origin (CMS `base_url` / `api_root`) for THIS build:
+ *   1. `FERST_GIT_BASE` env — explicit override, always wins.
+ *   2. committed `ferst-site.json` `gitBase` — an explicit per-site pin (e.g. a
+ *      custom proxy); a BYO/seeded site can hard-bind its origin this way.
+ *   3. otherwise DERIVE from the deploy environment: the production branch talks to
+ *      the prod git-proxy, every other (preview/dev) branch talks to the dev
+ *      git-proxy. So a templated repo self-configures per environment on deploy — a
+ *      dev-branch build points its CMS at the dev worker and main at prod — with NO
+ *      per-client config. (The production branch defaults to `main`; override via
+ *      `FERST_PROD_BRANCH` env or `ferst-site.json` `productionBranch`.)
+ * This restores the "site respects the environment it's deployed in" binding the old
+ * per-branch site config gave, without a per-client file to maintain.
+ */
+export function resolveGitBase(cwd = process.cwd(), branch = deploymentBranch()) {
+  const fromEnv = env('FERST_GIT_BASE');
+  if (fromEnv) return fromEnv;
+  let prodBranch = env('FERST_PROD_BRANCH') || 'main';
+  try {
+    const site = JSON.parse(readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8'));
+    if (site && typeof site.gitBase === 'string' && site.gitBase.trim()) return site.gitBase.trim();
+    if (!env('FERST_PROD_BRANCH') && site && typeof site.productionBranch === 'string' && site.productionBranch.trim()) {
+      prodBranch = site.productionBranch.trim();
+    }
+  } catch {
+    /* no ferst-site.json (e.g. the template repo itself) — derive from the branch */
+  }
+  return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
+}
+
+/** The deployment branch: CF Pages env → current git branch → main. */
+export function deploymentBranch() {
+  const cf = env('CF_PAGES_BRANCH');
+  if (cf) return cf;
+  try {
+    const git = execSync('git rev-parse --abbrev-ref HEAD', {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim();
+    if (git && git !== 'HEAD') return git;
+  } catch {
+    /* not a git checkout — fall through */
+  }
+  return 'main';
+}

package/package.json

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