ferst-core 0.6.1 → 0.7.0

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) ───────────────────────────
 
@@ -97,11 +99,17 @@ export function resolveUpstream(manifest) {
   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). */
+/**
+ * The caret range that pins an installed version to its major.minor, in the SAME
+ * canonical form the template ships (`^major.minor.0`, e.g. 0.6.3 → ^0.6.0). Emitting
+ * the `.0` matters: the template's manifest + package.json carry `^0.6.0`, so a matching
+ * canonical form makes the ownedPath resync + this rewrite idempotent — no per-update
+ * churn, and no `^0.6` vs `^0.6.0` drift between clients. (`^0.6.0` ≡ `^0.6` to npm.)
+ */
 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]}`;
+  return `^${m[1]}.${m[2]}.0`;
 }
 
 /** Read the `version` out of a package.json's text. Throws if absent. */
@@ -139,6 +147,42 @@ export function replaceCoreRange(raw, next) {
   return raw.replace(RANGE, `$1${next}$2`);
 }
 
+/**
+ * Set package.json's `ferst-core` dependency to the canonical range in place,
+ * formatting-preserving (same approach as replaceCoreRange). `npm install --save`
+ * would otherwise pin it to the exact installed patch (e.g. ^0.6.2), which churns
+ * against the template's `^0.6.0` on every resync; the exact version lives in the
+ * lockfile + the ferst-site.json drift stamp, so the dep range stays canonical.
+ * Returns the new text, or null when there is no `ferst-core` dependency to replace.
+ */
+export function replacePackageCoreDep(raw, next) {
+  const DEP = /("ferst-core"\s*:\s*")[^"]*(")/;
+  if (!DEP.test(raw)) return null;
+  return raw.replace(DEP, `$1${next}$2`);
+}
+
+/** package.json fields that describe the CLIENT's site, not the template's scaffold. */
+export const CLIENT_PACKAGE_FIELDS = ['name', 'description', 'version', 'private', 'author', 'homepage', 'repository'];
+
+/**
+ * After the scaffold sync overwrites package.json (a template-owned path), put the
+ * client's own identity fields back (name, description, …) so an update never renames
+ * the site. Keeps the synced file's indentation and key order. Returns the new text,
+ * or null when either side isn't valid JSON (then the synced file is left as is).
+ */
+export function keepClientPackageFields(syncedRaw, clientRaw) {
+  let synced, client;
+  try {
+    synced = JSON.parse(syncedRaw);
+    client = JSON.parse(clientRaw);
+  } catch {
+    return null;
+  }
+  for (const k of CLIENT_PACKAGE_FIELDS) if (k in client) synced[k] = client[k];
+  const indent = (syncedRaw.match(/\n([ \t]+)"/) || [, '  '])[1];
+  return JSON.stringify(synced, null, indent) + (syncedRaw.endsWith('\n') ? '\n' : '');
+}
+
 /**
  * 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.
@@ -155,6 +199,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 +252,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 +321,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) {
@@ -248,6 +331,10 @@ function main() {
     console.log('ferst-update: --dry-run — scaffold changes that WOULD apply:');
     console.log(diff ? diff : '  (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');
+    let clientPkg = null;
+    try { clientPkg = readFileSync(pkgPath, 'utf8'); } catch { /* none yet */ }
     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.
@@ -255,6 +342,16 @@ function main() {
         console.warn(`ferst-update: could not sync "${p}" (not present upstream?) — skipped.`);
       }
     }
+    if (clientPkg) {
+      try {
+        const synced = readFileSync(pkgPath, 'utf8');
+        const kept = keepClientPackageFields(synced, clientPkg);
+        if (kept && kept !== synced) {
+          writeFileSync(pkgPath, kept);
+          console.log("ferst-update: kept the site's own package.json name/description.");
+        }
+      } catch { /* package.json not synced — nothing to restore */ }
+    }
     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:');
@@ -263,12 +360,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 ...');
@@ -297,11 +395,29 @@ function main() {
         console.warn(`ferst-update: no "coreRange" field in ${MANIFEST} to update (installed ${after}).`);
       }
     }
+
+    // Normalise package.json's ferst-core dep to the same canonical range, undoing
+    // `--save`'s exact-patch pin (^0.6.2 → ^0.6.0) so it never churns against the
+    // template's ownedPath value. The exact version stays in the lock + drift stamp.
+    const pkgPath = resolve(cwd, 'package.json');
+    try {
+      const pkgRaw = readFileSync(pkgPath, 'utf8');
+      const pkgNext = replacePackageCoreDep(pkgRaw, next);
+      if (pkgNext && pkgNext !== pkgRaw) {
+        writeFileSync(pkgPath, pkgNext);
+        console.log(`ferst-update: package.json ferst-core → ${next}`);
+      }
+    } catch {
+      /* no root package.json (shouldn't happen in a client) — skip silently */
+    }
   }
 
   // 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 +431,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/components/BlockRenderer.astro

@@ -1,103 +1,107 @@
----
-/**
- * Renders an ordered list of blocks by mapping each block's `type` to its
- * component via a registry. Disabled blocks are skipped. The registry is typed
- * `Record<BlockType, …>`, so adding a block type to the union without a renderer
- * here is a compile error — no silent `undefined` component at runtime.
- */
-import type { Block, BlockType } from '../content/blocks';
-import Heading from './blocks/Heading.astro';
-import Prose from './blocks/Prose.astro';
-import ImageBlock from './blocks/ImageBlock.astro';
-import ButtonBlock from './blocks/ButtonBlock.astro';
-import Quote from './blocks/Quote.astro';
-import Divider from './blocks/Divider.astro';
-import Spacer from './blocks/Spacer.astro';
-import Badge from './blocks/Badge.astro';
-import Stat from './blocks/Stat.astro';
-import List from './blocks/List.astro';
-import Section from './blocks/Section.astro';
-import Grid from './blocks/Grid.astro';
-import Stack from './blocks/Stack.astro';
-import Hero from './recipes/Hero.astro';
-import FeatureCards from './recipes/FeatureCards.astro';
-import Cta from './recipes/Cta.astro';
-import Faq from './recipes/Faq.astro';
-import Gallery from './recipes/Gallery.astro';
-import Testimonial from './recipes/Testimonial.astro';
-import ContactForm from './recipes/ContactForm.astro';
-import Accordion from './recipes/Accordion.astro';
-import Tiles from './recipes/Tiles.astro';
-import Banner from './recipes/Banner.astro';
-import Stats from './recipes/Stats.astro';
-import Steps from './recipes/Steps.astro';
-import Pricing from './recipes/Pricing.astro';
-import Logos from './recipes/Logos.astro';
-import Tabs from './recipes/Tabs.astro';
-import Announcement from './recipes/Announcement.astro';
-import Bento from './recipes/Bento.astro';
-import Marquee from './recipes/Marquee.astro';
-import LatestPosts from './recipes/LatestPosts.astro';
-import MapEmbed from './recipes/MapEmbed.astro';
-import Table from './recipes/Table.astro';
-import Notice from './recipes/Notice.astro';
-import MediaCards from './recipes/MediaCards.astro';
-import ContactCard from './recipes/ContactCard.astro';
-import Locations from './recipes/Locations.astro';
-
-interface Props {
-  blocks: Block[];
-}
-
-const { blocks } = Astro.props;
-
-const registry: Record<BlockType, any> = {
-  heading: Heading,
-  prose: Prose,
-  image: ImageBlock,
-  button: ButtonBlock,
-  quote: Quote,
-  divider: Divider,
-  spacer: Spacer,
-  badge: Badge,
-  stat: Stat,
-  list: List,
-  section: Section,
-  grid: Grid,
-  stack: Stack,
-  hero: Hero,
-  featureCards: FeatureCards,
-  cta: Cta,
-  faq: Faq,
-  gallery: Gallery,
-  testimonial: Testimonial,
-  contactForm: ContactForm,
-  accordion: Accordion,
-  tiles: Tiles,
-  banner: Banner,
-  stats: Stats,
-  steps: Steps,
-  pricing: Pricing,
-  logos: Logos,
-  tabs: Tabs,
-  announcement: Announcement,
-  bento: Bento,
-  marquee: Marquee,
-  latestPosts: LatestPosts,
-  mapEmbed: MapEmbed,
-  table: Table,
-  notice: Notice,
-  mediaCards: MediaCards,
-  contactCard: ContactCard,
-  locations: Locations,
-};
----
-
-{
-  blocks
-    .filter((block) => block.enabled !== false)
-    .map((block) => {
-      const Component = registry[block.type];
-      return <Component {...block} />;
-    })
-}
+---
+/**
+ * Renders an ordered list of blocks by mapping each block's `type` to its
+ * component via a registry. Disabled blocks are skipped. The registry is typed
+ * `Record<BlockType, …>`, so adding a block type to the union without a renderer
+ * here is a compile error — no silent `undefined` component at runtime.
+ */
+import type { Block, BlockType } from '../content/blocks';
+import Heading from './blocks/Heading.astro';
+import Prose from './blocks/Prose.astro';
+import ImageBlock from './blocks/ImageBlock.astro';
+import ButtonBlock from './blocks/ButtonBlock.astro';
+import Quote from './blocks/Quote.astro';
+import Divider from './blocks/Divider.astro';
+import Spacer from './blocks/Spacer.astro';
+import Badge from './blocks/Badge.astro';
+import Stat from './blocks/Stat.astro';
+import List from './blocks/List.astro';
+import Section from './blocks/Section.astro';
+import Grid from './blocks/Grid.astro';
+import Stack from './blocks/Stack.astro';
+import Hero from './recipes/Hero.astro';
+import FeatureCards from './recipes/FeatureCards.astro';
+import Cta from './recipes/Cta.astro';
+import Faq from './recipes/Faq.astro';
+import Gallery from './recipes/Gallery.astro';
+import Testimonial from './recipes/Testimonial.astro';
+import ContactForm from './recipes/ContactForm.astro';
+import Accordion from './recipes/Accordion.astro';
+import Tiles from './recipes/Tiles.astro';
+import Banner from './recipes/Banner.astro';
+import Stats from './recipes/Stats.astro';
+import Steps from './recipes/Steps.astro';
+import Pricing from './recipes/Pricing.astro';
+import Logos from './recipes/Logos.astro';
+import Tabs from './recipes/Tabs.astro';
+import Announcement from './recipes/Announcement.astro';
+import Bento from './recipes/Bento.astro';
+import Marquee from './recipes/Marquee.astro';
+import LatestPosts from './recipes/LatestPosts.astro';
+import MapEmbed from './recipes/MapEmbed.astro';
+import Table from './recipes/Table.astro';
+import Notice from './recipes/Notice.astro';
+import MediaCards from './recipes/MediaCards.astro';
+import ContactCard from './recipes/ContactCard.astro';
+import Locations from './recipes/Locations.astro';
+import Video from './recipes/Video.astro';
+import Documents from './recipes/Documents.astro';
+
+interface Props {
+  blocks: Block[];
+}
+
+const { blocks } = Astro.props;
+
+const registry: Record<BlockType, any> = {
+  heading: Heading,
+  prose: Prose,
+  image: ImageBlock,
+  button: ButtonBlock,
+  quote: Quote,
+  divider: Divider,
+  spacer: Spacer,
+  badge: Badge,
+  stat: Stat,
+  list: List,
+  section: Section,
+  grid: Grid,
+  stack: Stack,
+  hero: Hero,
+  featureCards: FeatureCards,
+  cta: Cta,
+  faq: Faq,
+  gallery: Gallery,
+  testimonial: Testimonial,
+  contactForm: ContactForm,
+  accordion: Accordion,
+  tiles: Tiles,
+  banner: Banner,
+  stats: Stats,
+  steps: Steps,
+  pricing: Pricing,
+  logos: Logos,
+  tabs: Tabs,
+  announcement: Announcement,
+  bento: Bento,
+  marquee: Marquee,
+  latestPosts: LatestPosts,
+  mapEmbed: MapEmbed,
+  table: Table,
+  notice: Notice,
+  mediaCards: MediaCards,
+  contactCard: ContactCard,
+  locations: Locations,
+  video: Video,
+  documents: Documents,
+};
+---
+
+{
+  blocks
+    .filter((block) => block.enabled !== false)
+    .map((block) => {
+      const Component = registry[block.type];
+      return <Component {...block} />;
+    })
+}

package/components/blocks/Prose.astro

@@ -1,39 +1,56 @@
----
-interface Props {
-  text: string;
-}
-const { text } = Astro.props;
-// Blank lines separate paragraphs. (Markdown rendering upgrades this later.)
-const paragraphs = text
-  .split(/\n\s*\n/)
-  .map((p) => p.trim())
-  .filter(Boolean);
----
-
-<div class="b-prose">
-  {paragraphs.map((p) => <p>{p}</p>)}
-</div>
-
-<style>
-  .b-prose {
-    color: var(--fg);
-  }
-  .b-prose p {
-    margin: 0 0 1rem;
-    line-height: 1.7;
-    max-width: var(--max);
-  }
-  .b-prose p:last-child {
-    margin-bottom: 0;
-  }
-  /* The max-width reading column is left-anchored by default; when the page/
-     section is centred (or end-aligned) re-anchor it so the text reads as
-     deliberately centred, not centred inside a left column. Text-align itself
-     is inherited from the content-align cascade. */
-  :global([data-content-align='center']) .b-prose p {
-    margin-inline: auto;
-  }
-  :global([data-content-align='end']) .b-prose p {
-    margin-inline-start: auto;
-  }
-</style>
+---
+import { proseParts } from '../../lib/prose';
+interface Props {
+  text: string;
+}
+const { text } = Astro.props;
+// Blank lines separate paragraphs; `- ` / `1. ` lines make lists; links, bold and
+// italic are rendered safely (lib/prose.ts → inlineMarkdown).
+const parts = proseParts(text);
+---
+
+<div class="b-prose">
+  {parts.map((part) =>
+    part.kind === 'p' ? <p set:html={part.html} />
+    : part.kind === 'ul' ? <ul>{part.items.map((i) => <li set:html={i} />)}</ul>
+    : <ol>{part.items.map((i) => <li set:html={i} />)}</ol>
+  )}
+</div>
+
+<style>
+  .b-prose {
+    color: var(--fg);
+  }
+  .b-prose p,
+  .b-prose ul,
+  .b-prose ol {
+    margin: 0 0 1rem;
+    line-height: 1.7;
+    max-width: var(--max);
+  }
+  .b-prose ul,
+  .b-prose ol {
+    padding-inline-start: 1.4em;
+  }
+  .b-prose li + li {
+    margin-top: 0.25rem;
+  }
+  .b-prose > :last-child {
+    margin-bottom: 0;
+  }
+  .b-prose :global(a) {
+    color: var(--accent);
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+  /* The max-width reading column is left-anchored by default; when the page/
+     section is centred (or end-aligned) re-anchor it so the text reads as
+     deliberately centred, not centred inside a left column. Text-align itself
+     is inherited from the content-align cascade. */
+  :global([data-content-align='center']) .b-prose > * {
+    margin-inline: auto;
+  }
+  :global([data-content-align='end']) .b-prose > * {
+    margin-inline-start: auto;
+  }
+</style>