ferst-core 0.5.2 → 0.6.1

package/bin/cms-config.mjs

@@ -60,25 +60,37 @@ 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 site:
- *   FERST_GIT_BASE env → committed `ferst-site.json` `gitBase` → prod default.
- * The seeder writes `ferst-site.json` with the origin of the worker that provisioned
- * the site, so a dev-provisioned site points its CMS backend at the dev worker and a
- * prod one at prod — the "site respects the portal it was generated from" binding,
- * restored at build time.
+ * 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()) {
+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 raw = readFileSync(resolve(cwd, 'ferst-site.json'), 'utf8');
-    const site = JSON.parse(raw);
+    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) — fall through to the default */
+    /* no ferst-site.json (e.g. the template repo itself) — derive from the branch */
   }
-  return 'https://signin.ferst.co.uk';
+  return branch === prodBranch ? PROD_GIT_BASE : DEV_GIT_BASE;
 }
 
 /** The deployment branch: CF Pages env → current git branch → main. */
@@ -123,9 +135,9 @@ function main() {
     console.error('ferst-cms-config: could not determine the repo — set GITHUB_REPOSITORY=owner/name.');
     process.exit(1);
   }
-  // The platform git-proxy origin for this site (env → ferst-site.json → prod default).
-  const base = resolveGitBase();
+  // Branch first, so the git-proxy origin can be derived from the deploy environment.
   const branch = deploymentBranch();
+  const base = resolveGitBase(process.cwd(), branch);
 
   let tpl;
   try {

package/bin/ferst-update.mjs

@@ -0,0 +1,330 @@
+#!/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';
+
+// ── 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');
+}
+
+// ── 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;
+  }
+}
+
+/** 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}`);
+
+  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
+  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();
+    const current = readInstalledCoreVersion(cwd);
+    console.log(`ferst-update: ferst-core installed=${current ?? '(none)'} latest=${latest || '(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) {
+    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. 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.`,
+  );
+}
+
+// Run when invoked directly as a bin — including via npm's node_modules/.bin symlink.
+if (isDirectInvocation(process.argv[1])) {
+  main();
+}

package/components/NewsList.astro

@@ -0,0 +1,52 @@
+---
+/**
+ * NewsList — a responsive grid of PostCards, shared by the posts index and tag
+ * pages. Promoted into core (from a client's src/custom/) so the ferst()
+ * integration can inject the blog routes for every client. Presentational: it
+ * renders whatever posts it is given (the route decides which — index, or a
+ * single tag). Core ships PostCard; this arranges them.
+ */
+import PostCard from './PostCard.astro';
+import { postLink } from '../content/posts';
+
+interface PostItem {
+  slug: string;
+  body?: string | null;
+  data: { title: string; date: Date | string; summary?: string; heroImage?: string; tags?: string[]; attachment?: string };
+}
+interface Props {
+  posts: PostItem[];
+  empty?: string;
+}
+const { posts, empty = 'No posts yet.' } = Astro.props;
+---
+
+{posts.length === 0 ? (
+  <p class="news-empty">{empty}</p>
+) : (
+  <div class="news-grid">
+    {posts.map((p) => {
+      // A post that is just an attached PDF (no body) links straight to the file.
+      const { href, newTab } = postLink(p);
+      return (
+        <PostCard
+          href={href}
+          newTab={newTab}
+          moreLabel={newTab ? 'Open PDF' : undefined}
+          title={p.data.title}
+          date={p.data.date}
+          summary={p.data.summary}
+          heroImage={p.data.heroImage}
+          tagLabels={p.data.tags}
+        />
+      );
+    })}
+  </div>
+)}
+
+<style>
+  .news-grid { display: grid; gap: 1.5rem; grid-template-columns: 1fr; }
+  @media (min-width: 40em) { .news-grid { grid-template-columns: repeat(2, 1fr); } }
+  @media (min-width: 60em) { .news-grid { grid-template-columns: repeat(3, 1fr); } }
+  .news-empty { color: var(--muted); }
+</style>

package/components/PostsFilter.astro

@@ -0,0 +1,73 @@
+---
+/**
+ * PostsFilter — a row of tag chips linking to each tag's page
+ * (/posts/tag/<slug>), with "All" back to /posts; the active tag is marked
+ * aria-current. No JS. Promoted into core (from a client's src/custom/) so the
+ * ferst() integration can inject the blog routes. Feed it core's getUsedTags
+ * (visible tags that actually have posts, with counts).
+ */
+interface Tag {
+  slug: string;
+  label: string;
+  count: number;
+}
+interface Props {
+  tags: Tag[];
+  /** The active tag slug; omit on the main index ("All"). */
+  active?: string;
+}
+const { tags, active } = Astro.props;
+---
+
+{tags.length > 0 && (
+  <nav class="posts-filter" aria-label="Filter posts by tag">
+    <a class:list={['posts-filter__chip', { 'is-active': !active }]} href="/posts" aria-current={!active ? 'page' : undefined}>
+      All
+    </a>
+    {tags.map((t) => (
+      <a
+        class:list={['posts-filter__chip', { 'is-active': active === t.slug }]}
+        href={`/posts/tag/${t.slug}`}
+        aria-current={active === t.slug ? 'page' : undefined}
+      >
+        {t.label}<span class="posts-filter__count">{t.count}</span>
+      </a>
+    ))}
+  </nav>
+)}
+
+<style>
+  .posts-filter {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+  .posts-filter__chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.4rem 0.9rem;
+    border: var(--card-border);
+    border-radius: var(--radius-pill);
+    background: var(--bg-surface);
+    color: var(--accent);
+    font-family: var(--font-heading);
+    font-size: 0.85rem;
+    font-weight: 600;
+    text-decoration: none;
+    transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
+  }
+  .posts-filter__chip:hover {
+    border-color: var(--gold);
+    color: var(--gold);
+  }
+  .posts-filter__chip.is-active {
+    background: var(--gold);
+    border-color: var(--gold);
+    color: var(--text-light);
+  }
+  .posts-filter__count {
+    font-size: 0.75em;
+    opacity: 0.7;
+  }
+</style>

package/integration.mjs

@@ -2,26 +2,30 @@
  * ferst() — the Astro integration that makes a client site's ROUTING package-owned.
  *
  * A thin client adds `integrations: [ferst()]` to astro.config.mjs and carries
- * ZERO page files: the page catch-all (which also owns the home page) and the
- * calendar route are injected from ferst-core. A routing fix then ships as a
- * package bump + rebuild — the same channel component fixes travel through — instead
- * of being hand-copied into every client repo.
+ * ZERO page files: the page catch-all (which also owns the home page), the
+ * calendar route and the blog routes are injected from ferst-core. A routing fix
+ * then ships as a package bump + rebuild — the same channel component fixes travel
+ * through — instead of being hand-copied into every client repo.
  *
  * Irreducible caveat (Astro 5): content collections must be defined in the CONSUMER,
  * so the one-line `src/content/config.ts` re-export stays. "Zero page files" is
  * reachable; "zero files" is not. Explicit client `.astro` routes still win over
  * these injected ones, so a one-off hand-built page is always possible.
  *
- * Blog routes (news index / posts / tags) are deliberately NOT injected yet — the
- * listing component (NewsList) is not in the package. They join once it is promoted
- * to core; individual routes would otherwise exist with no listing to reach them.
+ * The blog routes (posts index / individual post / tag pages) inject as a set:
+ * the listing components (NewsList, PostsFilter) now live in core, so `/posts`,
+ * `/posts/[...slug]` and `/posts/tag/[...tag]` all ship from the package. Turn
+ * the whole capability off with `blog: false` (then a client wanting posts hand-
+ * builds its own routes over `ferst-core/lib/posts`).
  *
  * @param {object} [options]
  * @param {boolean} [options.calendar=true] Inject the `/calendar` route.
+ * @param {boolean} [options.blog=true] Inject the blog routes (`/posts`,
+ *   `/posts/[...slug]`, `/posts/tag/[...tag]`).
  * @returns {import('astro').AstroIntegration}
  */
 export default function ferst(options = {}) {
-  const { calendar = true } = options;
+  const { calendar = true, blog = true } = options;
   return {
     name: 'ferst',
     hooks: {
@@ -38,6 +42,22 @@ export default function ferst(options = {}) {
             entrypoint: 'ferst-core/routes/calendar/index.astro',
           });
         }
+        if (blog) {
+          // The posts capability: index, individual post, and tag pages. Reads
+          // the `posts`/`tags`/`postsSettings` collections (content/collections.ts).
+          injectRoute({
+            pattern: '/posts',
+            entrypoint: 'ferst-core/routes/posts/index.astro',
+          });
+          injectRoute({
+            pattern: '/posts/[...slug]',
+            entrypoint: 'ferst-core/routes/posts/[...slug].astro',
+          });
+          injectRoute({
+            pattern: '/posts/tag/[...tag]',
+            entrypoint: 'ferst-core/routes/posts/tag/[...tag].astro',
+          });
+        }
       },
     },
   };

package/package.json

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

package/routes/posts/[...slug].astro

@@ -0,0 +1,31 @@
+---
+/**
+ * An individual post (`/posts/<slug>`) — INJECTED by the ferst() integration
+ * (blog option). Renders the markdown body via core's PostArticle; tags link to
+ * `/posts/tag/<slug>` to match the injected tag pages.
+ */
+import Base from '../../layouts/Base.astro';
+import PostArticle from '../../components/PostArticle.astro';
+import { getPostRoutes, resolveTagLabels } from '../../lib/posts';
+
+export const getStaticPaths = getPostRoutes;
+
+const { entry } = Astro.props;
+const { Content } = await entry.render();
+const tags = await resolveTagLabels(entry.data.tags);
+---
+
+<Base title={entry.data.title} description={entry.data.summary} heroImage={entry.data.heroImage}>
+  <PostArticle
+    title={entry.data.title}
+    date={entry.data.date}
+    heroImage={entry.data.heroImage}
+    attachment={entry.data.attachment}
+    tags={tags}
+    tagBase="/posts/tag"
+    backHref="/posts"
+    backLabel="All posts"
+  >
+    <Content />
+  </PostArticle>
+</Base>

package/routes/posts/index.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * Posts index (`/posts`) — INJECTED by the ferst() integration (blog option).
+ * The news / notices listing. Excludes any tag in postsSettings.excludeFromIndex
+ * (e.g. a newsletter series that has its own tag page). Content, not code — a
+ * client carries the post markdown + tag data; this route ships from core.
+ */
+import Base from '../../layouts/Base.astro';
+import NewsList from '../../components/NewsList.astro';
+import PostsFilter from '../../components/PostsFilter.astro';
+import { getIndexPosts, getPostsSettings, getUsedTags } from '../../lib/posts';
+
+const [posts, settings, tags] = await Promise.all([getIndexPosts(), getPostsSettings(), getUsedTags()]);
+---
+
+<Base title={settings.title} description={settings.intro || undefined}>
+  <section class="posts">
+    <header class="posts__head">
+      <h1>{settings.title}</h1>
+      {settings.intro && <p class="t-lead">{settings.intro}</p>}
+    </header>
+    <PostsFilter tags={tags} />
+    <NewsList posts={posts} empty="No posts yet." />
+  </section>
+</Base>
+
+<style>
+  .posts { display: flex; flex-direction: column; gap: 2rem; }
+  .posts__head { display: flex; flex-direction: column; gap: 0.5rem; }
+  .posts__head .t-lead { color: var(--muted); }
+</style>

package/routes/posts/tag/[...tag].astro

@@ -0,0 +1,37 @@
+---
+/**
+ * A tag page (`/posts/tag/<slug>`) — INJECTED by the ferst() integration (blog
+ * option). All posts carrying one tag. This is also how an excluded-from-index
+ * series (e.g. a newsletter) gets its own page.
+ */
+import Base from '../../../layouts/Base.astro';
+import NewsList from '../../../components/NewsList.astro';
+import PostsFilter from '../../../components/PostsFilter.astro';
+import { getTagRoutes, getPostsByTag, getUsedTags } from '../../../lib/posts';
+
+export const getStaticPaths = getTagRoutes;
+
+const { tag } = Astro.props;
+const [posts, tags] = await Promise.all([getPostsByTag(tag.slug), getUsedTags()]);
+---
+
+<Base title={tag.label} description={tag.description || undefined}>
+  <section class="posts">
+    <header class="posts__head">
+      <p class="posts__eyebrow">Tag</p>
+      <h1>{tag.label}</h1>
+      {tag.description && <p class="t-lead">{tag.description}</p>}
+    </header>
+    <PostsFilter tags={tags} active={tag.slug} />
+    <NewsList posts={posts} />
+    <a class="posts__back" href="/posts">&larr; All posts</a>
+  </section>
+</Base>
+
+<style>
+  .posts { display: flex; flex-direction: column; gap: 2rem; }
+  .posts__head { display: flex; flex-direction: column; gap: 0.35rem; }
+  .posts__eyebrow { margin: 0; font-family: var(--font-heading); font-size: 0.75rem; font-weight: 600; letter-spacing: 0.1em; text-transform: uppercase; color: var(--gold); }
+  .posts__head .t-lead { color: var(--muted); }
+  .posts__back { font-weight: 600; color: var(--gold); }
+</style>