canopycms 0.0.65 → 0.0.66-int.82

package/README.md

@@ -316,9 +316,7 @@ This convention is applied consistently across the API:
 | `readByUrlPath`    | Automatically tries `slug: 'index'` as a fallback when the direct entry doesn't match. Works for all paths including `/`. A path whose last segment is an index slug (any case) skips the direct-entry attempt, so an index entry is reachable only at its collapsed path. |
 | `buildContentTree` | Default `buildPath` collapses index entries so tree node paths match the URLs consumers would use.                                                                                                                                                                         |
 
-The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does. (Ordinary entries keep case-insensitive matching on the final slug segment.)
-
-One known exception, still open: an entry-type name is also resolvable as a URL segment, so an index entry additionally answers at `/<collection>/<entryTypeName>` -- e.g. a root index entry at both `/` and `/home`. Nothing advertises that URL (it is absent from `listEntries` and from static-param generation), so it only matters if you serve a catch-all route. See the `readbyurlpath-entry-type-candidate-phantom-url` task in the CanopyCMS repo.
+The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does, nor does an entry-type name -- `readByUrlPath` only accepts a candidate whose collection segment is an actual collection, so `/<collection>/<entryTypeName>` (e.g. a root index entry answering at both `/` and `/home`) is not a second URL for it. (Ordinary entries keep case-insensitive matching on the final slug segment.)
 
 Two different entries can still compute the same `urlPath` — an entry whose slug matches a sibling collection that also has an `index` entry, or two slugs differing only by case. Only one of them can be served, so a production build fails and names them. `findDuplicateUrlPaths` (exported from `canopycms/server`) runs the same scan on demand.
 

package/dist/ai/generate.d.ts

@@ -17,6 +17,19 @@ export interface GenerateOptions {
     config?: AIContentConfig;
     /** Custom URL resolver for entry links. */
     entryLinkUrl?: EntryLinkUrlResolver;
+    /**
+     * ISO-8601 timestamp to record as the manifest's `generated`. Defaults to now.
+     *
+     * Passed in rather than read from the environment here so this stays a pure function of its
+     * arguments: the runtime route handler wants a live clock, the build path wants a pinned or
+     * omitted value, and only the caller knows which it is.
+     */
+    generatedAt?: string;
+    /**
+     * Artifact identifier to record as the manifest's `buildId`. Supplying this WITHOUT
+     * `generatedAt` omits `generated` entirely — see `AIManifest.generated`.
+     */
+    buildId?: string;
 }
 export interface GenerateResult {
     manifest: AIManifest;

package/dist/ai/generate.js

@@ -22,7 +22,7 @@ import { resolveEntryLinksInText } from '../entry-link-resolver.js';
  * bundle files, and a manifest.
  */
 export async function generateAIContent(options) {
-    const { store, flatSchema, contentRoot, config, entryLinkUrl } = options;
+    const { store, flatSchema, contentRoot, config, entryLinkUrl, generatedAt, buildId } = options;
     const files = new Map();
     // Build content ID index for entry link resolution
     const idIndex = await store.idIndex();
@@ -87,9 +87,15 @@ export async function generateAIContent(options) {
             }
         }
     }
-    // Build manifest
+    // Build manifest.
+    //
+    // `generated` is emitted unless the caller named an artifact but no timestamp: a build id says
+    // "this content is identified by an artifact, not by when a runner happened to build it", and a
+    // wall clock alongside it would be a claim the artifact cannot support months later. Key order
+    // is fixed (id before date) so the JSON is byte-stable across runs.
     const manifest = {
-        generated: new Date().toISOString(),
+        ...(buildId ? { buildId } : {}),
+        ...(generatedAt || !buildId ? { generated: generatedAt || new Date().toISOString() } : {}),
         entries: rootEntries,
         collections: manifestCollections,
         bundles: manifestBundles,

package/dist/ai/to-plain-text.js

@@ -287,6 +287,10 @@ function collapseWhitespace(text) {
  * indexes genuinely diverge (see docs/adopter-migration.md).
  */
 export function toPlainText(markdown) {
+    // Destructures `content` only: never touches `.data` (so the shared-instance
+    // hazard cannot apply) and never needs `.matter` (so the cache-hit hazard
+    // cannot apply either).
+    // eslint-disable-next-line no-restricted-syntax
     const { content } = matter(markdown);
     const withoutImports = stripMdxImports(content);
     const { masked, restore } = maskCode(withoutImports);

package/dist/ai/types.d.ts

@@ -215,7 +215,26 @@ export interface AIManifestBundle {
 }
 /** Top-level manifest for AI content */
 export interface AIManifest {
-    generated: string;
+    /**
+     * When this content was generated, ISO-8601.
+     *
+     * OPTIONAL, and absent whenever the manifest carries a `buildId` and no usable
+     * `SOURCE_DATE_EPOCH` (unset, blank, or malformed — a rejected value does not fall back to a
+     * live clock, it leaves the field absent):
+     * under build-once-promote one artifact is built once and may be served months later, so a
+     * build clock describes the runner that produced it rather than the content, and anything
+     * reading it as "how fresh is this?" is misled by design. An adopter who has declared a build
+     * id has told us the date is not the identifying fact, so it is omitted rather than filled in
+     * with something arbitrary. Present unconditionally when neither env var is set.
+     */
+    generated?: string;
+    /**
+     * Identifies the artifact this content was built into (`CANOPY_BUILD_ID`). Absent unless that
+     * variable is set to a usable value — 1-255 characters of `[A-Za-z0-9._-]`, not `.` or `..`,
+     * since it must also serve as a single path segment. This — not `generated` — is what a
+     * content-addressed deployment keys on.
+     */
+    buildId?: string;
     /** Root-level entries (outside any collection) */
     entries: AIManifestEntry[];
     collections: AIManifestCollection[];

package/dist/api/admin-branch-health.js

@@ -14,6 +14,9 @@ import path from 'node:path';
 import { z } from 'zod';
 import { simpleGit } from 'simple-git';
 import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+// Same constants the reader uses, rather than a second copy of the two string
+// literals -- they were declared independently here until 2026-08-23.
+import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
 import { scanBranchHealth } from '../branch-health.js';
 import { ContentIdIndex } from '../content-id-index.js';
 import { invalidateContentIndexesDurable } from '../content-index-generation.js';
@@ -30,8 +33,6 @@ import { defineEndpoint } from './route-builder.js';
 const PROVISIONING_LOCK_FRESH_MS = 5 * 60_000;
 /** An orphan dir younger than this may still be a clone in progress; corrupt dirs are exempt. */
 const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
-const BRANCH_META_DIR = '.canopy-meta';
-const BRANCH_META_FILE = 'branch.json';
 // ============================================================================
 // Zod schemas
 // ============================================================================
@@ -102,7 +103,7 @@ const getBranchHealthHandler = async (_gc, ctx, _req) => {
  * Purge a corrupt-metadata or orphan branch directory by renaming it into a
  * dot-prefixed trash name (reversible -- nothing is deleted here; the worker
  * sweeps trash older than 30 days, see cleanupTrashedBranchDirs in
- * worker/cms-worker.ts).
+ * worker/rebase.ts).
  *
  * Safety rails (see the PR's design review for the finding IDs):
  * - [always] the base branch directory can never be purged.
@@ -111,7 +112,7 @@ const getBranchHealthHandler = async (_gc, ctx, _req) => {
  * - [H1] a fresh provisioning init-lock blocks purge; a stale one does not.
  * - an orphan (not corrupt) dir younger than 15 minutes is presumed to be a
  *   clone in progress and is not purgeable yet.
- * - [H2] the purge itself runs under a zero-retry provisioning lock, so a
+ * - the purge itself runs under a zero-retry provisioning lock, so a
  *   real in-flight provisioner (whose lock is therefore fresh, and would
  *   already have 409'd above) can never race the rename; a same-instant
  *   contender simply 409s.
@@ -178,7 +179,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
             };
         }
     }
-    // [H2] Zero-retry provisioning lock: fails fast (409) on genuine live
+    // Zero-retry provisioning lock: fails fast (409) on genuine live
     // contention instead of hanging the request for ~5 minutes.
     let releaseProvisioningLock;
     try {
@@ -248,7 +249,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
  * (exiting the withOccFileLock callback) before save() runs -- calling
  * save() while still holding the lock would deadlock against itself.
  *
- * [MEDIUM-1] The provisioning lock is held across the ENTIRE archive+save
+ * The provisioning lock is held across the ENTIRE archive+save
  * sequence (acquired before withOccFileLock, released only after save()
  * completes), same lock order as purge (provisioning -> branch.json) so the
  * two can never deadlock against each other. Without this, a concurrent
@@ -306,8 +307,8 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
             ? { ok: false, status: 409, error: 'Metadata is healthy' }
             : { ok: false, status: 409, error: 'No metadata file -- use purge for orphans' };
     }
-    // [MEDIUM-1] Zero-retry provisioning lock, mirroring purge's [H2]: fails
-    // fast (409) on genuine live contention instead of hanging the request.
+    // Zero-retry provisioning lock, mirroring purge's: fails fast (409) on
+    // genuine live contention instead of hanging the request.
     // Held until the `finally` below, AFTER save() completes.
     let releaseProvisioningLock;
     try {
@@ -348,14 +349,14 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
                 error: `Could not lock branch metadata: ${getErrorMessage(err)}`,
             };
         }
-        // [MEDIUM-3] Prefer the clone's actual checked-out branch over the
+        // Prefer the clone's actual checked-out branch over the
         // (possibly sanitized) directory name -- see resolveRepairedBranchName.
         const branchName = await resolveRepairedBranchName(dirPath, params.dirName);
         // Lock released above (we're outside the withOccFileLock callback now) --
         // save() takes its own hold on the same lock internally. Its defaults
         // path fabricates the rest of BranchMetadata and invalidates the
-        // registry. Still under the provisioning lock acquired above -- see
-        // [MEDIUM-1] in the docstring.
+        // registry. Still under the provisioning lock acquired above -- see the
+        // lock-ordering note in this handler's docstring.
         const manager = getBranchMetadataFileManager(dirPath, baseRoot);
         const saved = await manager.save({
             branch: { name: branchName, status: 'editing', createdBy: req.user.userId },
@@ -385,7 +386,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
     }
 };
 /**
- * [MEDIUM-3] Best-effort read of the branch actually checked out in the
+ * Best-effort read of the branch actually checked out in the
  * clone at `dirPath`, falling back to `dirName` on any failure (no `.git`,
  * detached HEAD, corrupt repo, etc.). Workspace directory names are
  * sanitized (slashes stripped, see paths/branch.ts's `sanitizeBranchName`),

package/dist/api/branch.js

@@ -134,7 +134,7 @@ export const createBranchHandler = async (ctx, req, body) => {
         // Reserve the WHOLE canopycms-settings- namespace, not just this
         // deployment's own settings branch name. Two CanopyCMS deployments can
         // share one GitHub repo, each with its own settings branch under this
-        // prefix; the worker (worker/cms-worker.ts) treats any
+        // prefix; the worker (worker/git-sync.ts) treats any
         // `canopycms-settings-*` ref specially (orphan-branch reconcile/push
         // logic), so another deployment's settings branch is a real name that
         // must not be claimable as a content branch here either.
@@ -203,7 +203,7 @@ export const createBranchHandler = async (ctx, req, body) => {
         // (PRIVATE_ISOLATED subnets, no NAT -- see AGENTS.md), so a synchronous
         // GitHub API call at branch-create time is not possible. But remote.git
         // is BOTH this deployment's local git origin AND a mirror of GitHub's
-        // view of the repo: cms-worker.ts's syncGit() fetches GitHub into it
+        // view of the repo: worker/git-sync.ts's syncGit() fetches GitHub into it
         // (see GITHUB_TRACKING_REF_PREFIX's doc comment in git-manager.ts) and
         // then reconciles refs/heads/* non-destructively, so it carries both
         // this deployment's local heads and GitHub's view -- readable offline by

package/dist/branch-health.js

@@ -112,7 +112,7 @@ export async function scanBranchHealth(baseRoot, opts) {
             // branch.json, etc.) land here: all are "needs admin attention",
             // and none may throw out of the scan.
             //
-            // [MEDIUM-2] parseError is served to the browser via the admin
+            // [REDACT] parseError is served to the browser via the admin
             // branch-health endpoint, so it must never leak the absolute
             // workspace path. BranchMetadataCorruptError carries `parseCause`
             // (the raw JSON.parse message, path-free) for exactly this --

package/dist/branch-metadata-file.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reading `branch.json` — the file format, nothing else.
+ *
+ * Deliberately a LEAF: it imports only node built-ins, a type, and the error
+ * helper. That is the whole point of the file.
+ *
+ * `branch-registry.ts` scans every branch directory and reads each one's
+ * `branch.json`; `branch-metadata.ts` owns writing it and, after a write,
+ * invalidates the registry cache. Both of those are correct, but together they
+ * were a runtime import cycle (`branch-metadata` -> `branch-registry` ->
+ * `branch-metadata`), with value imports on both edges — the only cycle in the
+ * package when `no-circular` was first turned on, 2026-08-23.
+ *
+ * Hoisting the READ here breaks it without changing either module's behavior:
+ * the registry gets its reader from a leaf, and the metadata manager keeps its
+ * invalidation edge. `BranchMetadataFileManager.loadOnly` stays as a thin
+ * delegate so its ~16 existing call sites are untouched.
+ */
+import type { BranchMetadata } from './types.js';
+export declare const BRANCH_META_DIR = ".canopy-meta";
+export declare const BRANCH_META_FILE = "branch.json";
+export interface BranchMetadataFile {
+    schemaVersion: number;
+    version: number;
+    writeId?: string;
+    branch: BranchMetadata;
+}
+/**
+ * branch.json exists but its content is not valid JSON. Distinguished from
+ * provisioning/IO failures so callers can degrade instead of failing hard:
+ * the registry scan quarantines the branch, and the request handler keeps
+ * serving (with empty internal groups) when the BASE branch is the corrupt
+ * one — otherwise the admin recovery surface would be unreachable exactly
+ * when it is needed.
+ */
+export declare class BranchMetadataCorruptError extends Error {
+    readonly branchRoot: string;
+    /**
+     * [REDACT] The raw JSON.parse failure message (e.g. "Unexpected token
+     * ..."), with no embedded path. `message` above deliberately keeps the
+     * full `branchRoot`-qualified text for server logs; `parseCause` is what
+     * callers should surface to clients (see branch-health.ts's `parseError`)
+     * so the admin branch-health scan never leaks the absolute workspace path.
+     */
+    readonly parseCause: string;
+    constructor(branchRoot: string, cause: string);
+}
+/** Absolute path to a branch workspace's `branch.json`. */
+export declare const branchMetadataFilePath: (branchRoot: string) => string;
+/**
+ * Read and parse `branch.json`, with no locking, no OCC and no side effects.
+ *
+ * Returns `null` when the file does not exist (an un-provisioned or
+ * non-branch directory), throws `BranchMetadataCorruptError` on malformed
+ * JSON, and rethrows every other IO failure unchanged — callers distinguish
+ * all three.
+ */
+export declare function readBranchMetadataFile(branchRoot: string): Promise<BranchMetadataFile | null>;

package/dist/branch-metadata-file.js

@@ -0,0 +1,65 @@
+/**
+ * Reading `branch.json` — the file format, nothing else.
+ *
+ * Deliberately a LEAF: it imports only node built-ins, a type, and the error
+ * helper. That is the whole point of the file.
+ *
+ * `branch-registry.ts` scans every branch directory and reads each one's
+ * `branch.json`; `branch-metadata.ts` owns writing it and, after a write,
+ * invalidates the registry cache. Both of those are correct, but together they
+ * were a runtime import cycle (`branch-metadata` -> `branch-registry` ->
+ * `branch-metadata`), with value imports on both edges — the only cycle in the
+ * package when `no-circular` was first turned on, 2026-08-23.
+ *
+ * Hoisting the READ here breaks it without changing either module's behavior:
+ * the registry gets its reader from a leaf, and the metadata manager keeps its
+ * invalidation edge. `BranchMetadataFileManager.loadOnly` stays as a thin
+ * delegate so its ~16 existing call sites are untouched.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isNotFoundError } from './utils/error.js';
+export const BRANCH_META_DIR = '.canopy-meta';
+export const BRANCH_META_FILE = 'branch.json';
+/**
+ * branch.json exists but its content is not valid JSON. Distinguished from
+ * provisioning/IO failures so callers can degrade instead of failing hard:
+ * the registry scan quarantines the branch, and the request handler keeps
+ * serving (with empty internal groups) when the BASE branch is the corrupt
+ * one — otherwise the admin recovery surface would be unreachable exactly
+ * when it is needed.
+ */
+export class BranchMetadataCorruptError extends Error {
+    constructor(branchRoot, cause) {
+        super(`Corrupt branch metadata in '${branchRoot}': ${cause}`);
+        this.name = 'BranchMetadataCorruptError';
+        this.branchRoot = branchRoot;
+        this.parseCause = cause;
+    }
+}
+/** Absolute path to a branch workspace's `branch.json`. */
+export const branchMetadataFilePath = (branchRoot) => path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE);
+/**
+ * Read and parse `branch.json`, with no locking, no OCC and no side effects.
+ *
+ * Returns `null` when the file does not exist (an un-provisioned or
+ * non-branch directory), throws `BranchMetadataCorruptError` on malformed
+ * JSON, and rethrows every other IO failure unchanged — callers distinguish
+ * all three.
+ */
+export async function readBranchMetadataFile(branchRoot) {
+    const resolvedRoot = path.resolve(branchRoot);
+    try {
+        const raw = await fs.readFile(branchMetadataFilePath(resolvedRoot), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (isNotFoundError(err)) {
+            return null;
+        }
+        if (err instanceof SyntaxError) {
+            throw new BranchMetadataCorruptError(resolvedRoot, err.message);
+        }
+        throw err;
+    }
+}

package/dist/branch-metadata.d.ts

@@ -1,34 +1,10 @@
 import type { BranchContext, BranchMetadata } from './types.js';
+import { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, type BranchMetadataFile } from './branch-metadata-file.js';
 import { type OperatingMode } from './operating-mode/index.js';
-export interface BranchMetadataFile {
-    schemaVersion: number;
-    version: number;
-    writeId?: string;
-    branch: BranchMetadata;
-}
+export { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, type BranchMetadataFile, };
 export declare class BranchMetadataConflictError extends Error {
     constructor(message?: string);
 }
-/**
- * branch.json exists but its content is not valid JSON. Distinguished from
- * provisioning/IO failures so callers can degrade instead of failing hard:
- * the registry scan quarantines the branch, and the request handler keeps
- * serving (with empty internal groups) when the BASE branch is the corrupt
- * one — otherwise the admin recovery surface would be unreachable exactly
- * when it is needed.
- */
-export declare class BranchMetadataCorruptError extends Error {
-    readonly branchRoot: string;
-    /**
-     * [MEDIUM-2] The raw JSON.parse failure message (e.g. "Unexpected token
-     * ..."), with no embedded path. `message` above deliberately keeps the
-     * full `branchRoot`-qualified text for server logs; `parseCause` is what
-     * callers should surface to clients (see branch-health.ts's `parseError`)
-     * so the admin branch-health scan never leaks the absolute workspace path.
-     */
-    readonly parseCause: string;
-    constructor(branchRoot: string, cause: string);
-}
 /**
  * Manages branch.json — branch status and access ACLs, both security-adjacent
  * state — under `.canopy-meta/` in a branch workspace.

package/dist/branch-metadata.js

@@ -1,12 +1,15 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { BranchRegistry } from './branch-registry.js';
+import { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, } from './branch-metadata-file.js';
 import { resolveBranchPath } from './paths/index.js';
 import { isNotFoundError } from './utils/error.js';
 import { withLock } from './utils/async-mutex.js';
 import { writeOccJsonFile, withOccRetry, withOccFileLock, OccWriteConflictError, } from './utils/occ-json-write.js';
-const BRANCH_META_DIR = '.canopy-meta';
-const BRANCH_META_FILE = 'branch.json';
+// The file format itself lives in the leaf so branch-registry.ts can read
+// branch.json without importing this module (which imports it back). Re-exported
+// here so the existing importers of these names do not have to move.
+export { BRANCH_META_DIR, BRANCH_META_FILE, BranchMetadataCorruptError, readBranchMetadataFile, };
 const CURRENT_SCHEMA_VERSION = 1;
 export class BranchMetadataConflictError extends Error {
     constructor(message = 'Concurrent modification detected in branch metadata') {
@@ -14,22 +17,6 @@ export class BranchMetadataConflictError extends Error {
         this.name = 'BranchMetadataConflictError';
     }
 }
-/**
- * branch.json exists but its content is not valid JSON. Distinguished from
- * provisioning/IO failures so callers can degrade instead of failing hard:
- * the registry scan quarantines the branch, and the request handler keeps
- * serving (with empty internal groups) when the BASE branch is the corrupt
- * one — otherwise the admin recovery surface would be unreachable exactly
- * when it is needed.
- */
-export class BranchMetadataCorruptError extends Error {
-    constructor(branchRoot, cause) {
-        super(`Corrupt branch metadata in '${branchRoot}': ${cause}`);
-        this.name = 'BranchMetadataCorruptError';
-        this.branchRoot = branchRoot;
-        this.parseCause = cause;
-    }
-}
 /**
  * Manages branch.json — branch status and access ACLs, both security-adjacent
  * state — under `.canopy-meta/` in a branch workspace.
@@ -69,21 +56,7 @@ export class BranchMetadataFileManager {
      * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
      */
     static async loadOnly(branchRoot) {
-        const resolvedRoot = path.resolve(branchRoot);
-        const filePath = path.join(resolvedRoot, BRANCH_META_DIR, BRANCH_META_FILE);
-        try {
-            const raw = await fs.readFile(filePath, 'utf8');
-            return JSON.parse(raw);
-        }
-        catch (err) {
-            if (isNotFoundError(err)) {
-                return null;
-            }
-            if (err instanceof SyntaxError) {
-                throw new BranchMetadataCorruptError(resolvedRoot, err.message);
-            }
-            throw err;
-        }
+        return readBranchMetadataFile(branchRoot);
     }
     /**
      * Get a BranchMetadataFileManager instance configured for registry invalidation.

package/dist/branch-registry.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { BranchMetadataFileManager } from './branch-metadata.js';
+// The leaf, NOT './branch-metadata' — that module imports this one back, and
+// the pair was the package's only runtime import cycle. See branch-metadata-file.ts.
+import { readBranchMetadataFile } from './branch-metadata-file.js';
 import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 // canopyLogWarn, not console.warn: registry regeneration is reached from every
@@ -243,7 +245,7 @@ export class BranchRegistry {
                 // branch-health surface to report and repair.
                 let meta;
                 try {
-                    meta = await BranchMetadataFileManager.loadOnly(branchRoot);
+                    meta = await readBranchMetadataFile(branchRoot);
                 }
                 catch (err) {
                     canopyLogWarn(`CanopyCMS: Skipping branch directory '${entry.name}' during registry scan: ${getErrorMessage(err)}`);

package/dist/build/generate-ai-content.js

@@ -67,6 +67,108 @@ async function removeEmptyDirsUpward(startDir, stopAt) {
         current = path.dirname(current);
     }
 }
+/**
+ * A `CANOPY_BUILD_ID` usable as a build id: it becomes a single path segment under
+ * `_next/static/`, so a value like `heads/main` (what `git describe --all` returns) would nest
+ * that directory, and one containing `..` would climb out of it.
+ *
+ * Deliberately duplicated in `canopycms-next`'s `with-canopy.ts` rather than shared. That file is
+ * loaded by `next.config.ts` before any bundler runs, which is why it ships pre-built and imports
+ * nothing from this package; importing a constant from here would pull this module's graph —
+ * `node:fs` included — into a config file that must be plain executable JavaScript. The two
+ * copies must agree, and the tests on both sides assert the same set of values.
+ */
+const SAFE_BUILD_ID = /^[A-Za-z0-9._-]{1,255}$/;
+/** The message every rejection uses, so the stated rule and the enforced rule cannot drift. */
+const BUILD_ID_RULE = 'must be 1-255 characters of [A-Za-z0-9._-] and not "." or ".."';
+function isUsableBuildId(value) {
+    // `.` and `..` clear the character class but are not names — as a path segment they resolve to
+    // the static directory itself or its parent. `a..b` is an ordinary filename and stays allowed.
+    // The 255 bound is the same rule: a longer segment fails at `mkdir` with ENAMETOOLONG.
+    return SAFE_BUILD_ID.test(value) && value !== '.' && value !== '..';
+}
+/**
+ * What an unusable `SOURCE_DATE_EPOCH` actually costs, which depends on whether a build id is set.
+ *
+ * Worth spelling out rather than saying "unpinned": with a build id, `generated` is not merely
+ * un-pinned but ABSENT, and a field silently vanishing from a published artifact is the outcome an
+ * operator most needs told.
+ */
+function unpinnedConsequence(buildId) {
+    return buildId
+        ? 'omitting `generated` from the manifest entirely (a build id is set, so no build clock is recorded).'
+        : 'recording the current time in `generated` instead.';
+}
+/**
+ * Resolve the manifest's build stamp from the environment.
+ *
+ * This lives at the BUILD boundary, not inside `generateAIContent`, because the same generator
+ * also serves the runtime route — where a live clock is the correct answer and a
+ * `SOURCE_DATE_EPOCH` that happens to be exported in a server environment must not freeze a
+ * response's timestamp.
+ *
+ * `SOURCE_DATE_EPOCH` is the Reproducible Builds convention (decimal seconds since the epoch),
+ * kept under its standard name so a harness that already exports it for tar/gzip/rpm gets this
+ * for free. `CANOPY_BUILD_ID` is ours: Next has no such variable of its own.
+ *
+ * That id is validated here against a rule justified by Next's `_next/static/<id>/` layout, even
+ * though this module is framework-agnostic. Deliberate: the variable's whole purpose is that the
+ * manifest's `buildId` and the framework's build id name the SAME artifact, so a value one reader
+ * would reject is not useful to the other. The cost is that a non-Next adopter cannot use, say, an
+ * ISO timestamp as a build id — revisit this rule, in both copies, when a second framework lands.
+ *
+ * Every rejection warns and is ignored rather than failing the build — same stance as
+ * `readGeneratedRecord` above. Both variables treat "set but unusable" as a broken pipeline
+ * (`SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)` with a failing command) and say so, while
+ * "unset" is a deliberate opt-out and says nothing.
+ *
+ * Note what ignoring a bad `SOURCE_DATE_EPOCH` means when a build id IS set: `generatedAt` stays
+ * undefined, so `generated` is omitted rather than falling back to a live clock. A bad value must
+ * not resurrect a field the adopter's configuration says is meaningless — which is also why that
+ * case warns rather than failing silently, since the field simply disappears.
+ */
+function resolveBuildStamp() {
+    // Trimmed and shape-checked with the same rule `withCanopy` applies, so that when an adopter
+    // pins BOTH halves of a build the manifest's `buildId` and Next's `_next/static/<id>/` agree.
+    // (They are independent readers of one variable: a host-supplied `generateBuildId`, or the CMS
+    // flavor of a dual build, can still leave Next on a different id — this only guarantees that
+    // the variable itself is read identically.)
+    const rawBuildId = process.env.CANOPY_BUILD_ID;
+    const trimmedBuildId = rawBuildId?.trim();
+    let buildId;
+    if (rawBuildId === undefined) {
+        buildId = undefined;
+    }
+    else if (!trimmedBuildId) {
+        console.warn('CanopyCMS: CANOPY_BUILD_ID is set but blank — recording no buildId in the manifest.');
+    }
+    else if (!isUsableBuildId(trimmedBuildId)) {
+        console.warn(`CanopyCMS: ignoring CANOPY_BUILD_ID="${trimmedBuildId}": it ${BUILD_ID_RULE}, so that ` +
+            "the manifest's buildId can match the build id Next stores for the same artifact.");
+    }
+    else {
+        buildId = trimmedBuildId;
+    }
+    const rawEpoch = process.env.SOURCE_DATE_EPOCH;
+    const trimmedEpoch = rawEpoch?.trim();
+    if (rawEpoch !== undefined && !trimmedEpoch) {
+        console.warn(`CanopyCMS: SOURCE_DATE_EPOCH is set but blank — ${unpinnedConsequence(buildId)}`);
+    }
+    if (!trimmedEpoch)
+        return { buildId };
+    // Digits only, applied AFTER trimming: surrounding whitespace is a plausible accident in a
+    // shell-exported variable and the intent is unambiguous, but `Number('0x10')` also parses and
+    // `0x10` is not a SOURCE_DATE_EPOCH. The `Number.isNaN` check below also catches values large
+    // enough that `* 1000` overflows the Date range.
+    const seconds = /^\d+$/.test(trimmedEpoch) ? Number(trimmedEpoch) : Number.NaN;
+    const date = new Date(seconds * 1000);
+    if (Number.isNaN(date.getTime())) {
+        console.warn(`CanopyCMS: ignoring SOURCE_DATE_EPOCH="${trimmedEpoch}" (expected decimal seconds since ` +
+            `the Unix epoch) — ${unpinnedConsequence(buildId)}`);
+        return { buildId };
+    }
+    return { generatedAt: date.toISOString(), buildId };
+}
 /**
  * Generate AI content files and write them to disk.
  *
@@ -105,6 +207,7 @@ export async function generateAIContentFiles(options) {
         contentRoot: contentRootName,
         config: aiConfig,
         entryLinkUrl: config.entryLinkUrl,
+        ...resolveBuildStamp(),
     });
     // Write files to disk
     const absoluteOutputDir = path.resolve(outputDir) + path.sep;