ferst-core 0.9.4 → 0.9.6

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/cms/config.template.yml

@@ -212,6 +212,7 @@ collections:
         search_fields: [label]
         multiple: true
       - { name: heroImage, label: Hero image, widget: image, required: false }
+      - { name: heroImageAlt, label: Picture description, widget: string, required: false, hint: "Who or what the picture shows, in a short sentence, for people who can't see it (e.g. Parishioners outside the church after the Easter Vigil). Leave empty if it's only decoration." }
       - { name: attachment, label: Attachment (e.g. PDF), widget: file, required: false }
       - { name: draft, label: Draft, widget: boolean, default: false, required: false }
       - { name: body, label: Body, widget: markdown, required: false }

package/components/PostArticle.astro

@@ -10,6 +10,8 @@ interface Props {
   title: string;
   date: Date | string;
   heroImage?: string;
+  /** What the picture shows (its alt text); empty leaves it as decoration. */
+  heroImageAlt?: string;
   /** Optional downloadable file (e.g. a PDF newsletter) shown as a download link. */
   attachment?: string;
   /** Resolved tags for display + linking. */
@@ -20,7 +22,7 @@ interface Props {
   backHref?: string;
   backLabel?: string;
 }
-const { title, date, heroImage, attachment, tags = [], tagBase = '/tags', backHref, backLabel = 'Back to news' } = Astro.props;
+const { title, date, heroImage, heroImageAlt = '', attachment, tags = [], tagBase = '/tags', backHref, backLabel = 'Back to news' } = Astro.props;
 // A human label for the download link, hinting the file type from its extension.
 const attachmentExt = attachment ? attachment.split('.').pop()?.toUpperCase() : undefined;
 const attachmentLabel = attachmentExt && attachmentExt.length <= 4 ? `Download (${attachmentExt})` : 'Download attachment';
@@ -47,7 +49,7 @@ const display = Number.isNaN(d.valueOf())
         </ul>
       )}
     </div>
-    {heroImage && <img class="b-post__hero" src={heroImage} alt="" />}
+    {heroImage && <img class="b-post__hero" src={heroImage} alt={heroImageAlt} />}
   </header>
   <div class="b-post__body">
     <slot />

package/components/SiteFooter.astro

@@ -304,8 +304,7 @@ const year = new Date().getFullYear();
     font-weight: 600;
     letter-spacing: 0.1em;
     text-transform: uppercase;
-    color: var(--text-footer);
-    opacity: 0.8;
+    color: var(--text-footer); /* full strength: at 80% it fell below AA (3.8:1) */
   }
   .site-footer .footer-group ul {
     list-style: none;

package/components/recipes/Announcement.astro

@@ -35,7 +35,8 @@ const key = `ferst-dismissed-${id}`;
   }
   .b-announce[data-tone='accent'] { background: var(--gold); color: var(--on-brand); }
   .b-announce[data-tone='neutral'] { background: var(--bg-section); color: var(--fg); }
-  .b-announce__text { margin: 0; line-height: 1.4; }
+  /* Its text takes the band's colour (on-brand or ink), not the site's grey paragraph colour. */
+  .b-announce__text { margin: 0; line-height: 1.4; color: inherit; }
   .b-announce__link {
     color: inherit;
     font-weight: 700;

package/components/recipes/ContactForm.astro

@@ -11,6 +11,7 @@
  */
 import Heading from '../blocks/Heading.astro';
 import Button from '../Button.astro';
+import { autocompleteFor } from '../../lib/autocomplete';
 
 interface Field {
   name: string;
@@ -63,7 +64,7 @@ const headAlign = headingAlign ?? blockAlign ?? 'center';
           {type === 'textarea' ? (
             <textarea id={id} name={field.name} rows="5" required={field.required} placeholder={field.placeholder}></textarea>
           ) : (
-            <input id={id} type={type} name={field.name} required={field.required} placeholder={field.placeholder} />
+            <input id={id} type={type} name={field.name} required={field.required} placeholder={field.placeholder} autocomplete={autocompleteFor({ ...field, type })} />
           )}
         </div>
       );

package/content/posts.ts

@@ -30,6 +30,8 @@ export const postSchema = z.object({
   tags: z.array(z.string()).default([]),
   /** Optional hero / preview image. */
   heroImage: z.string().optional(),
+  /** What the picture shows, for people who can't see it (its alt text). Empty = decoration. */
+  heroImageAlt: z.string().optional(),
   /** Optional downloadable file attached to the post (e.g. a PDF newsletter or
    *  notice). Rendered as a download link on the post. */
   attachment: z.string().optional(),

package/lib/autocomplete.ts

@@ -0,0 +1,25 @@
+/**
+ * What a form field asks for about the person filling it in, as an HTML `autocomplete`
+ * token (WCAG 2.2 AA 1.3.5, identify input purpose), so browsers and assistive tools can fill
+ * it in. Only the person's own name, email and phone; anything else says nothing rather than
+ * guess (a child's or a parish's name isn't the person's). Pure, so it's unit-testable.
+ */
+export interface FieldLike {
+  name: string;
+  label: string;
+  type?: string;
+}
+
+export function autocompleteFor({ name, label, type }: FieldLike): string | undefined {
+  if (type === 'email') return 'email';
+  if (type === 'tel') return 'tel';
+  if (type === 'textarea') return undefined;
+  const words = `${name} ${label}`.toLowerCase().replace(/[_-]+/g, ' ');
+  const text = label.toLowerCase().trim();
+  if (/\b(e-?mail)\b/.test(words)) return 'email';
+  if (/\b(phone|telephone|mobile)\b/.test(words)) return 'tel';
+  if (/\b(first|given) name\b/.test(words)) return 'given-name';
+  if (/\b(last name|surname|family name)\b/.test(words)) return 'family-name';
+  if (/^(your |full )?name$/.test(text) || /^(full )?name$/.test(name.toLowerCase().replace(/[_-]+/g, ' '))) return 'name';
+  return undefined;
+}

package/package.json

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

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

@@ -20,6 +20,7 @@ const tags = await resolveTagLabels(entry.data.tags);
     title={entry.data.title}
     date={entry.data.date}
     heroImage={entry.data.heroImage}
+    heroImageAlt={entry.data.heroImageAlt}
     attachment={entry.data.attachment}
     tags={tags}
     tagBase="/posts/tag"