ferst-core 0.2.1 → 0.2.3

package/bin/set-cms-branch.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// ferst-set-cms-branch — stamp the Sveltia CMS backend branch to match THIS
+// deployment's branch, so config.yml never drifts from the platform git-proxy's
+// branch policy (dev deploy → dev, main → main). Run it AFTER `astro build`:
+//
+//   "build": "astro build && ferst-set-cms-branch"
+//
+// It rewrites the built CMS config's `branch:` from CF_PAGES_BRANCH (Cloudflare
+// Pages), falling back to the current git branch, then `main`. The COMMITTED
+// config.yml stays a neutral placeholder, identical on every branch — no
+// per-branch config, no merge hazard.
+//
+// Why it matters: Sveltia READS content from `branch`, and the git-proxy rejects
+// writes whose branch != the project's branch policy. A wrong value = the CMS
+// shows no content and any save 403s. This makes that impossible to ship
+// silently — it fails the build loudly if it can't stamp.
+//
+// Config path: `dist/admin/config.yml` under the current working directory
+// (the client repo root at build time). Override with a first CLI arg.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const CONFIG = resolve(process.cwd(), process.argv[2] ?? 'dist/admin/config.yml');
+
+function deploymentBranch() {
+  const cf = process.env.CF_PAGES_BRANCH?.trim();
+  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';
+}
+
+const branch = deploymentBranch();
+
+let yml;
+try {
+  yml = readFileSync(CONFIG, 'utf8');
+} catch {
+  console.error(`ferst-set-cms-branch: ${CONFIG} not found — run this AFTER astro build.`);
+  process.exit(1);
+}
+
+// Check the `branch:` line EXISTS separately from whether it changed — stamping
+// the same value (e.g. main→main on the prod placeholder) is a valid no-op.
+const BRANCH_LINE = /^(\s*branch:\s*)\S.*$/m;
+if (!BRANCH_LINE.test(yml)) {
+  console.error('ferst-set-cms-branch: no "branch:" line found in the CMS config backend.');
+  process.exit(1);
+}
+writeFileSync(CONFIG, yml.replace(BRANCH_LINE, `$1${branch}`));
+console.log(`ferst-set-cms-branch: CMS backend branch → "${branch}"`);

package/components/blocks/Heading.astro

@@ -5,22 +5,26 @@ interface Props {
   align?: 'start' | 'center' | 'end';
   gradient?: boolean;
 }
-const { text, level = 2, align = 'start', gradient = false } = Astro.props;
+const { text, level = 2, align, gradient = false } = Astro.props;
 const Tag = `h${level}` as unknown as keyof HTMLElementTagNameMap;
 ---
 
 <Tag class="b-heading" data-align={align} data-gradient={gradient ? 'true' : 'false'}>{text}</Tag>
 
 <style>
-  /* A heading owns its own alignment via the `align` prop — it never depends on
-     an ancestor rule. (Base no longer force-centres headings, so a recipe that
-     asks for `start` really is left-aligned, and `center` really is centred,
-     wherever the block is placed — including AI-authored block JSON.) */
+  /* By default a heading INHERITS the page/section content alignment (the
+     `--content-align` cascade set on `.site-main` / a `section`), so a whole
+     template stays coherent. An explicit `align` prop overrides it for this one
+     heading. (`text-align` inherits, and inheritance carries the resolved
+     alignment; the `[data-align]` rules win over it when set.) */
   .b-heading {
     color: var(--fg);
     margin: 0;
     text-wrap: balance;
     line-height: 1.2;
+    text-align: inherit;
+  }
+  .b-heading[data-align='start'] {
     text-align: start;
   }
   .b-heading[data-align='center'] {

package/components/blocks/List.astro

@@ -29,6 +29,13 @@ const Tag = style === 'number' ? 'ol' : 'ul';
     gap: 0.6rem;
     color: var(--muted);
     line-height: 1.6;
+    text-align: start;
+  }
+  /* A bulleted/numbered list always reads left; on a centred page centre the
+     list as a block but keep the items left-aligned (centred markers read badly). */
+  :global([data-content-align='center']) .b-list {
+    width: fit-content;
+    margin-inline: auto;
   }
   .b-list__item {
     display: flex;

package/components/blocks/Prose.astro

@@ -26,4 +26,14 @@ const paragraphs = text
   .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>

package/components/blocks/Quote.astro

@@ -17,6 +17,12 @@ const { text, cite } = Astro.props;
     border-inline-start: 3px solid var(--gold);
     padding-inline-start: 1rem;
   }
+  /* On a centred page/section the left rule reads as off-axis — drop it so the
+     quote centres cleanly. (Inherits text-align from the content-align cascade.) */
+  :global([data-content-align='center']) .b-quote {
+    border-inline-start: none;
+    padding-inline-start: 0;
+  }
   .b-quote blockquote {
     margin: 0;
     color: var(--fg);

package/components/blocks/Section.astro

@@ -10,13 +10,15 @@ import BlockRenderer from '../BlockRenderer.astro';
 interface Props {
   background?: 'none' | 'muted' | 'accent';
   width?: 'normal' | 'wide' | 'full';
+  /** Override the page's content alignment for this section's subtree. */
+  align?: 'start' | 'center' | 'end';
   blocks?: any[];
 }
-const { background = 'none', width = 'normal', blocks = [] } = Astro.props;
+const { background = 'none', width = 'normal', align, blocks = [] } = Astro.props;
 ---
 
 <section class="b-section" data-bg={background}>
-  <div class="b-section__inner" data-width={width}>
+  <div class="b-section__inner" data-width={width} data-content-align={align}>
     <BlockRenderer blocks={blocks} />
   </div>
 </section>

package/content/blocks.ts

@@ -19,7 +19,9 @@ export const headingBlock = z.object({
   enabled: z.boolean().default(true),
   text: z.string(),
   level: z.number().int().min(1).max(6).default(2),
-  align: z.enum(['start', 'center', 'end']).default('start'),
+  /** Explicit per-heading alignment. OMITTED ⇒ inherit the page/section
+   *  `--content-align` cascade; set it only to override for this one heading. */
+  align: z.enum(['start', 'center', 'end']).optional(),
   /** Paint the text with a brand → accent-2 gradient (falls back to solid ink
    *  where background-clip:text is unsupported). A per-block opt-in effect. */
   gradient: z.boolean().default(false),
@@ -446,6 +448,8 @@ export const sectionBlock = z.object({
   enabled: z.boolean().default(true),
   background: z.enum(['none', 'muted', 'accent']).default('none'),
   width: z.enum(['normal', 'wide', 'full']).default('normal'),
+  /** Override the page's content alignment for this section's subtree. */
+  align: z.enum(['start', 'center', 'end']).optional(),
   blocks: z.lazy(() => z.array(blockSchema)).default([]),
 });
 
@@ -512,6 +516,15 @@ export const pageSchema = z.object({
   description: z.string().optional(),
   /** Preloaded as the LCP image (passed to the layout) when set. */
   heroImage: z.string().optional(),
+  /**
+   * Template-level content alignment — the default for text-bearing blocks on the
+   * page (headings, prose, quote). Cascades as `--content-align` so every recipe
+   * inherits one coherent alignment instead of each hard-coding its own. A
+   * `section` block can override it for its subtree; a `heading` can override per
+   * block. `start` (left) is the readable default for long-form; `center` suits
+   * short, hero-led pages.
+   */
+  align: z.enum(['start', 'center', 'end']).default('start'),
   /**
    * Provenance — the ferst-library template this page was instantiated from.
    * The triangular model (docs/BLOCK-ARCHITECTURE.md §5): lego box → a template

package/layouts/Base.astro

@@ -37,6 +37,9 @@ interface Props {
   footerClass?: string;
   /** Render the secondary logo centred at the bottom of the page content. */
   showSecondaryLogo?: boolean;
+  /** Template-level content alignment — cascades to text-bearing blocks via
+   *  `data-content-align` on <main>. `start` (default) keeps long-form readable. */
+  align?: 'start' | 'center' | 'end';
 }
 
 const {
@@ -47,6 +50,7 @@ const {
   mainClass,
   footerClass,
   showSecondaryLogo = false,
+  align = 'start',
 } = Astro.props;
 
 const settings = await loadSiteSettings();
@@ -144,7 +148,7 @@ const metaDescription = description ?? identity.description;
       dropdown={navigation.dropdown}
     />
 
-    <main class:list={['site-main', mainClass]}>
+    <main class:list={['site-main', mainClass]} data-content-align={align}>
       <slot name="hero" />
       <slot />
       {showSecondaryLogo && (secondaryLogoLight || secondaryLogoDark) && (
@@ -356,6 +360,23 @@ const metaDescription = description ?? identity.description;
         margin-block: 0;
       }
 
+      /* ── Content alignment cascade ──────────────────────────────────────
+         A page sets its default alignment via the `align` prop (→
+         data-content-align on <main>); a `section` block can override it for
+         its own subtree. Text-bearing blocks inherit `text-align` from here, so
+         a whole template stays on one alignment axis instead of each recipe
+         hard-coding its own. A few blocks adjust when centred so the result
+         reads as deliberately centred, not centred-inside-a-left-column.
+         `start` (left) is the readable default for long-form; a heading can
+         still override per-block via its own `align`. */
+      [data-content-align='start'] { text-align: start; }
+      [data-content-align='center'] { text-align: center; }
+      [data-content-align='end'] { text-align: end; }
+      /* Each content block owns how it ADJUSTS when centred/ended (re-centring
+         its reading column, dropping a left rule, etc.) in its own component,
+         so the rule out-specifies the block's own scoped styles. Here we only
+         set the inherited text-align axis. */
+
       /* ── Secondary logo block: centered ── */
       .secondary-logo {
         display: flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",
@@ -44,7 +44,8 @@
     "LICENSE-Apache-2.0"
   ],
   "bin": {
-    "ferst-check-thin": "bin/check-thin.mjs"
+    "ferst-check-thin": "bin/check-thin.mjs",
+    "ferst-set-cms-branch": "bin/set-cms-branch.mjs"
   },
   "dependencies": {
     "zod": "^3.25.0"