@glw907/cairn-cms 0.68.0 → 0.76.0

package/dist/delivery/site-indexes.d.ts

@@ -1,5 +1,5 @@
 import type { CairnAdapter, ConceptConfig } from '../content/types.js';
-import type { Infer } from '../content/schema.js';
+import type { InferFieldset } from '../content/fieldset.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import type { ContentIndex } from './content-index.js';
 import type { SiteResolver } from './site-resolver.js';
@@ -12,7 +12,7 @@ export type SiteGlobs<A extends CairnAdapter> = {
  *  `site` is not supported, since `site` is the reserved resolver key.
  */
 export type SiteIndexes<A extends CairnAdapter> = {
-    [K in keyof A['content']]: ContentIndex<NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>>;
+    [K in keyof A['content']]: ContentIndex<NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? InferFieldset<S> : Record<string, unknown>>;
 } & {
     readonly site: SiteResolver;
 };

package/dist/delivery/site-resolver.d.ts

@@ -32,6 +32,31 @@ export interface SiteResolver {
 export declare function createSiteResolver(concepts: ConceptIndex[], opts?: {
     validate?: boolean;
 }): SiteResolver;
+/**
+ * A reference edge resolved to its target's identity, for a public route to render a linked target.
+ *  It reuses the target entry's own summary fields rather than re-deriving them, so a linked author
+ *  card reads the same title and permalink the target's own page does. `summary` is the target's
+ *  excerpt when present.
+ */
+export interface ResolvedReference {
+    id: string;
+    concept: string;
+    title: string;
+    permalink: string;
+    summary?: string;
+}
+/**
+ * Resolve a concept's `reference` and `array(reference)` frontmatter edges to their target identities,
+ * keyed by the field name, so a public route renders a reference as a link to its target's page. The
+ * resolution lives here because only the cross-concept resolver reaches a different concept's entries:
+ * a posts entry's `author` edge targets a pages entry, which the posts index alone cannot read. A
+ * single `reference` field resolves to one `ResolvedReference`, an `array(reference)` to a
+ * `ResolvedReference[]` in edge order. An id with no live target is dropped rather than thrown: the
+ * build's `verifyReferences` gate already fails a true dangling edge, so an unresolved id at request
+ * time is a mid-flight or draft target, not a hard error. Resolve per call, since the target entries
+ * exist only after every per-concept index is unioned into the resolver.
+ */
+export declare function resolveReferences(site: SiteResolver, descriptor: ConceptDescriptor, frontmatter: Record<string, unknown>): Record<string, ResolvedReference | ResolvedReference[]>;
 /**
  * A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
  *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks.

package/dist/delivery/site-resolver.js

@@ -1,3 +1,4 @@
+import { extractReferenceEdges } from '../content/references.js';
 /** Strip a trailing slash from a path, keeping the root "/" intact. */
 function normalizePath(path) {
     return path.length > 1 ? path.replace(/\/+$/, '') : path;
@@ -60,6 +61,54 @@ export function createSiteResolver(concepts, opts = {}) {
         },
     };
 }
+/** Project a resolved target entry into the identity a public route renders for a reference. */
+function projectReference(edge, target) {
+    const resolved = {
+        id: edge.id,
+        concept: edge.concept,
+        title: target.title,
+        permalink: target.permalink,
+    };
+    if (target.excerpt)
+        resolved.summary = target.excerpt;
+    return resolved;
+}
+/**
+ * Resolve a concept's `reference` and `array(reference)` frontmatter edges to their target identities,
+ * keyed by the field name, so a public route renders a reference as a link to its target's page. The
+ * resolution lives here because only the cross-concept resolver reaches a different concept's entries:
+ * a posts entry's `author` edge targets a pages entry, which the posts index alone cannot read. A
+ * single `reference` field resolves to one `ResolvedReference`, an `array(reference)` to a
+ * `ResolvedReference[]` in edge order. An id with no live target is dropped rather than thrown: the
+ * build's `verifyReferences` gate already fails a true dangling edge, so an unresolved id at request
+ * time is a mid-flight or draft target, not a hard error. Resolve per call, since the target entries
+ * exist only after every per-concept index is unioned into the resolver.
+ */
+export function resolveReferences(site, descriptor, frontmatter) {
+    const edges = extractReferenceEdges(frontmatter, descriptor.fields);
+    const resolved = {};
+    for (const field of descriptor.fields) {
+        const isSingle = field.type === 'reference';
+        const isArray = field.type === 'array' && field.item.type === 'reference';
+        if (!isSingle && !isArray)
+            continue;
+        const fieldEdges = edges.filter((edge) => edge.field === field.name);
+        const hits = [];
+        for (const edge of fieldEdges) {
+            const target = site.concept(edge.concept)?.byId(edge.id);
+            if (target)
+                hits.push(projectReference(edge, target));
+        }
+        if (isSingle) {
+            if (hits.length > 0)
+                resolved[field.name] = hits[0];
+        }
+        else {
+            resolved[field.name] = hits;
+        }
+    }
+    return resolved;
+}
 /**
  * A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
  *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks.

package/dist/doctor/checks-local.js

@@ -4,9 +4,7 @@
 import { fail, pass, skip } from './types.js';
 import { readWranglerConfig } from './wrangler-config.js';
 import { requireOrigin } from '../env.js';
-import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
-import { normalizeConcepts } from '../content/concepts.js';
-import { defineFields } from '../content/schema.js';
+import { parseSiteConfig } from '../nav/site-config.js';
 const NO_WRANGLER = skip('no wrangler.jsonc or wrangler.toml found');
 export const configBindings = {
     id: 'config.bindings',
@@ -147,14 +145,11 @@ export const configSiteConfig = {
         if (text === null)
             return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
         try {
-            const policy = urlPolicyFrom(parseSiteConfig(text));
-            // Run the engine's own URL-policy validation by declaring a synthetic empty concept
-            // per policy key. Routing is concept-fixed in the engine (CONCEPT_ROUTING, never the
-            // adapter), so the dated rules apply faithfully here. What a CLI cannot check without
-            // evaluating the adapter is whether each policy key names a concept the site declares.
-            const synthetic = Object.fromEntries(Object.keys(policy).map((id) => [id, { dir: '', schema: defineFields([]) }]));
-            normalizeConcepts(synthetic, policy);
-            return pass('parsed and URL policy validated (the adapter concept set is not checkable from the CLI)');
+            // Parse-only. parseSiteConfig validates the root shape and, since Contract v2, hard-errors on a
+            // stale per-concept `content:` block (URL policy moved onto defineConcept). The per-concept URL
+            // policy is now validated at the concept declaration, which a CLI cannot reach without the adapter.
+            parseSiteConfig(text);
+            return pass('parsed (per-concept URL policy lives on the adapter concepts, not checkable from the CLI)');
         }
         catch (err) {
             return fail(err instanceof Error ? err.message : String(err));

package/dist/github/backend.d.ts

@@ -0,0 +1,83 @@
+import type { FileChange } from './repo.js';
+import type { BackendEnv } from './credentials.js';
+import type { CommitAuthor, RepoFile } from './types.js';
+export type { BackendEnv };
+/**
+ * A live, connected content store pinned to a default branch. The GitHub implementation already
+ * holds a minted token behind it; the engine resolves one per request. Read, commit, and branch
+ * over files only: this interface never grows a query() method.
+ */
+export interface Backend {
+    /** The site's default branch, for example "main". Callers reading published state pass it as the ref. */
+    readonly defaultBranch: string;
+    /** Raw file contents at a ref, or null when the path does not exist. */
+    readFile(path: string, ref: string): Promise<string | null>;
+    /** The markdown entries directly in a concept directory at a ref, newest id first. */
+    readEntries(dir: string, ref: string): Promise<RepoFile[]>;
+    /** A branch's head commit sha, or null when the branch does not exist. */
+    branchHead(branch: string): Promise<string | null>;
+    /** Branch names under a prefix, sorted. */
+    listBranches(prefix: string): Promise<string[]>;
+    /**
+     * Commit a set of path changes atomically on a branch; returns the new commit sha. When
+     * `expectedHead` is given the commit is fail-closed: it makes one attempt and throws
+     * CommitConflictError if the branch head is not `expectedHead`. Omitting it keeps the head-merge
+     * retry the entry and publish paths rely on.
+     */
+    commit(branch: string, changes: FileChange[], author: CommitAuthor, message: string, expectedHead?: string): Promise<string>;
+    /** Create a branch at another branch's current head. */
+    createBranch(name: string, fromBranch: string): Promise<void>;
+    /** Delete a branch; a missing branch is success. */
+    deleteBranch(name: string): Promise<void>;
+}
+/** The adapter's backend value: a provider that connect()s to a live Backend given the Worker env. */
+export interface BackendProvider {
+    /** A stable tag for the implementation, for example "github-app". The non-request readers narrow on it. */
+    readonly kind: string;
+    /** The default branch, surfaced before connect() so compose-time code can read it. */
+    readonly branch: string;
+    /** Connect to a live Backend; the GitHub implementation mints and caches its token lazily. */
+    connect(env: BackendEnv): Backend;
+}
+/** What githubApp() returns: the generic provider plus the GitHub App's non-secret identity facts. */
+export interface GithubAppProvider extends BackendProvider {
+    readonly kind: 'github-app';
+    readonly owner: string;
+    readonly repo: string;
+    readonly appId: string;
+    readonly installationId: string;
+}
+/**
+ * Narrow a provider to the GitHub App provider on its `kind` tag. The non-request readers (the
+ * health self-test, the build-time facts) call this before reading the GitHub-specific identity,
+ * since `BackendProvider.kind` is a bare string the compiler cannot narrow on its own.
+ */
+export declare function isGithubApp(provider: BackendProvider): provider is GithubAppProvider;
+/** The non-secret GitHub App identity an adapter carries in source; the private key stays a Worker secret. */
+interface GithubAppConfig {
+    owner: string;
+    repo: string;
+    branch: string;
+    appId: string;
+    installationId: string;
+}
+/**
+ * The live GitHub Backend over the existing repo.ts and branches.ts transports. The token getter
+ * is injected rather than the env: connect() wires the production getter that mints and caches the
+ * installation token, and a unit test wires a literal so the in-memory fetch double intercepts the
+ * same GitHub URLs. Not barrel-exported; it is the internal test seam imported by path.
+ */
+export declare function makeGithubBackend(config: GithubAppConfig, getToken: () => string | Promise<string>): Backend;
+/**
+ * The default content backend: a GitHub App over a repo branch. Returns a provider carrying the
+ * App's non-secret identity (so the build-time, health, and doctor readers narrow on kind and read
+ * it) whose connect(env) mints and caches the installation token from the Worker's private-key
+ * secret. The missing-secret CairnError stays on first token use, inside connect.
+ */
+export declare function githubApp(config: {
+    owner: string;
+    repo: string;
+    branch: string;
+    appId: string;
+    installationId: string;
+}): GithubAppProvider;

package/dist/github/backend.js

@@ -0,0 +1,76 @@
+// cairn-cms: the Backend seam. A Backend is read, commit, and branch operations over files,
+// never a query(): that line is the constraint that keeps a store swappable and a database out.
+// The adapter holds a BackendProvider from githubApp(...); the engine resolves one live Backend
+// per request via connect(env), with the GitHub App installation token minted and cached behind
+// the seam. makeGithubBackend takes an injectable token getter so a test wires a literal token and
+// the in-memory fetch double intercepts the same GitHub URLs the production getter would reach.
+import { readRaw, listMarkdown, commitFiles } from './repo.js';
+import { branchHeadSha, createBranch as createBranchRef, deleteBranch, listBranches } from './branches.js';
+import { appCredentials } from './credentials.js';
+import { cachedInstallationToken } from './signing.js';
+import { CommitConflictError } from './types.js';
+/**
+ * Narrow a provider to the GitHub App provider on its `kind` tag. The non-request readers (the
+ * health self-test, the build-time facts) call this before reading the GitHub-specific identity,
+ * since `BackendProvider.kind` is a bare string the compiler cannot narrow on its own.
+ */
+export function isGithubApp(provider) {
+    return provider.kind === 'github-app';
+}
+/**
+ * The live GitHub Backend over the existing repo.ts and branches.ts transports. The token getter
+ * is injected rather than the env: connect() wires the production getter that mints and caches the
+ * installation token, and a unit test wires a literal so the in-memory fetch double intercepts the
+ * same GitHub URLs. Not barrel-exported; it is the internal test seam imported by path.
+ */
+export function makeGithubBackend(config, getToken) {
+    return {
+        defaultBranch: config.branch,
+        async readFile(path, ref) {
+            return readRaw({ ...config, branch: ref }, path, await getToken());
+        },
+        async readEntries(dir, ref) {
+            return listMarkdown({ ...config, branch: ref }, dir, await getToken());
+        },
+        async branchHead(branch) {
+            return branchHeadSha(config, branch, await getToken());
+        },
+        async listBranches(prefix) {
+            return listBranches(config, prefix, await getToken());
+        },
+        async commit(branch, changes, author, message, expectedHead) {
+            return commitFiles({ ...config, branch }, changes, { message, author }, await getToken(), expectedHead);
+        },
+        async createBranch(name, fromBranch) {
+            const tok = await getToken();
+            const head = await branchHeadSha(config, fromBranch, tok);
+            // A null head means the source branch is gone or unreadable. Throw a defined, catchable
+            // error the save path maps to its 500 rather than letting the createBranchRef POST fail raw.
+            if (head === null)
+                throw new CommitConflictError(`${fromBranch} (unreadable source)`);
+            await createBranchRef(config, name, head, tok);
+        },
+        async deleteBranch(name) {
+            await deleteBranch(config, name, await getToken());
+        },
+    };
+}
+/**
+ * The default content backend: a GitHub App over a repo branch. Returns a provider carrying the
+ * App's non-secret identity (so the build-time, health, and doctor readers narrow on kind and read
+ * it) whose connect(env) mints and caches the installation token from the Worker's private-key
+ * secret. The missing-secret CairnError stays on first token use, inside connect.
+ */
+export function githubApp(config) {
+    return {
+        kind: 'github-app',
+        branch: config.branch,
+        owner: config.owner,
+        repo: config.repo,
+        appId: config.appId,
+        installationId: config.installationId,
+        connect(env) {
+            return makeGithubBackend(config, () => cachedInstallationToken(appCredentials(config, env)));
+        },
+    };
+}

package/dist/github/credentials.d.ts

@@ -1,12 +1,18 @@
-import type { BackendConfig } from '../content/types.js';
 import type { AppCredentials } from './types.js';
-/** The Worker secret holding the GitHub App private key: base64 of the PEM, single line. */
-export interface GithubKeyEnv {
+/**
+ * The Worker secret carrier `Backend.connect` reads: the GitHub App private key as base64 of the
+ * PEM, single line. A consumer's `App.Platform.env` block names it. Aliased as the engine's
+ * `BackendEnv` since the backend seam owns the secret channel.
+ */
+export interface BackendEnv {
     GITHUB_APP_PRIVATE_KEY_B64?: string;
 }
 /**
- * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
+ * Assemble the `AppCredentials` the signer needs from the GitHub App's identity (app id,
  * installation) and the Worker's private-key secret. Throws a CairnError naming
  * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
-export declare function appCredentials(backend: Pick<BackendConfig, 'appId' | 'installationId'>, env: GithubKeyEnv): AppCredentials;
+export declare function appCredentials(identity: {
+    appId: string;
+    installationId: string;
+}, env: BackendEnv): AppCredentials;

package/dist/github/credentials.js

@@ -4,16 +4,16 @@
 // TypeError. Mirrors requireDb/requireOrigin in env.ts.
 import { CairnError } from '../diagnostics/index.js';
 /**
- * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
+ * Assemble the `AppCredentials` the signer needs from the GitHub App's identity (app id,
  * installation) and the Worker's private-key secret. Throws a CairnError naming
  * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
-export function appCredentials(backend, env) {
+export function appCredentials(identity, env) {
     const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
     if (!privateKeyB64) {
         throw new CairnError('github.app-unreachable', {
             message: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured',
         });
     }
-    return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
+    return { appId: identity.appId, installationId: identity.installationId, privateKeyB64 };
 }

package/dist/github/repo.d.ts

@@ -27,24 +27,6 @@ export declare function contentsUrl(repo: RepoRef, path: string): string;
  * approaches it (spec §7.3).
  */
 export declare function readRaw(repo: RepoRef, path: string, token?: string): Promise<string | null>;
-/** The current blob sha for a path, or null if the file does not yet exist. */
-export declare function fileSha(repo: RepoRef, path: string, token: string): Promise<string | null>;
-/**
- * Commit `content` to `path` on the configured branch through the contents API. The author is
- * the editor; the committer is omitted, so GitHub attributes it to the App (`cairn-cms[bot]`).
- * Updates the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`,
- * so the save fails safe: re-fetch and ask the editor to reapply, never a merge.
- *
- * Caller preconditions this layer cannot enforce, and the save action (Plan 05) must:
- * `path` is confined to the concept's configured directory (the App token can write anywhere
- * in the repo, so an unvalidated path could overwrite CI config or source), and `author` is
- * derived from the verified server-side session, never from request input.
- */
-export declare function commitFile(repo: RepoRef, path: string, content: string, opts: {
-    message: string;
-    author: CommitAuthor;
-}, token: string): Promise<string>;
 /** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
 export interface FileChange {
     path: string;
@@ -61,9 +43,16 @@ export interface FileChange {
  *
  * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
  * site redeploy for no content change.
+ *
+ * When `expectedHead` is supplied the commit is fail-closed: it makes a single attempt with no
+ * retry, throws a `CommitConflictError` when the branch head is not `expectedHead` (a concurrent
+ * commit landed), and otherwise commits onto that head. The nav and settings writes, which land on
+ * the default branch and trigger a deploy, pass it so a same-branch race surfaces the editor's
+ * reload-and-reapply prompt rather than a silent last-writer-wins. Omitting it keeps the
+ * head-merge retry the entry and publish paths rely on.
  */
 export declare function commitFiles(repo: RepoRef, changes: FileChange[], opts: {
     message: string;
     author: CommitAuthor;
-}, token: string): Promise<string>;
+}, token: string, expectedHead?: string): Promise<string>;
 export {};

package/dist/github/repo.js

@@ -75,51 +75,6 @@ export async function readRaw(repo, path, token) {
         throw new Error(`GitHub read ${path} failed: ${res.status}`);
     return res.text();
 }
-/** Standard (padded) base64 of UTF-8 text, the form the contents API expects. */
-function toBase64(text) {
-    return btoa(Array.from(new TextEncoder().encode(text), (b) => String.fromCharCode(b)).join(''));
-}
-/** The current blob sha for a path, or null if the file does not yet exist. */
-export async function fileSha(repo, path, token) {
-    const res = await fetch(contentsUrl(repo, path), { headers: ghHeaders('application/vnd.github+json', token) });
-    if (res.status === 404)
-        return null;
-    if (!res.ok)
-        throw new Error(`GitHub stat ${path} failed: ${res.status}`);
-    return (await res.json()).sha;
-}
-/**
- * Commit `content` to `path` on the configured branch through the contents API. The author is
- * the editor; the committer is omitted, so GitHub attributes it to the App (`cairn-cms[bot]`).
- * Updates the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`,
- * so the save fails safe: re-fetch and ask the editor to reapply, never a merge.
- *
- * Caller preconditions this layer cannot enforce, and the save action (Plan 05) must:
- * `path` is confined to the concept's configured directory (the App token can write anywhere
- * in the repo, so an unvalidated path could overwrite CI config or source), and `author` is
- * derived from the verified server-side session, never from request input.
- */
-export async function commitFile(repo, path, content, opts, token) {
-    const sha = await fileSha(repo, path, token);
-    const url = `${API}/repos/${repo.owner}/${repo.repo}/contents/${path.replace(/^\/+|\/+$/g, '')}`;
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            message: opts.message,
-            content: toBase64(content),
-            branch: repo.branch,
-            author: opts.author,
-            ...(sha ? { sha } : {}),
-        }),
-    });
-    if (res.status === 409)
-        throw new CommitConflictError(path);
-    if (!res.ok)
-        throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
-    return (await res.json()).commit.sha;
-}
 /** A Git Data API URL under the repo's `git/` namespace. */
 function gitUrl(repo, suffix) {
     return `${API}/repos/${repo.owner}/${repo.repo}/git/${suffix}`;
@@ -150,6 +105,57 @@ function treeChanges(changes) {
 }
 /** Retries after the initial attempt when the branch moves under an atomic commit. */
 const COMMIT_RETRIES = 3;
+/**
+ * Build a tree on `parent`'s tree, create the commit, and PATCH the branch ref to it. Returns the
+ * new commit sha, or null when the ref PATCH is a non-fast-forward (the head moved). A tree-create
+ * 422 (an unprocessable delete) becomes a `CommitConflictError`, and any other non-fast-forward
+ * detail is left to the caller to map.
+ */
+async function commitOnTree(repo, parent, tree, opts, token) {
+    const baseTree = await commitTreeSha(repo, parent, token);
+    const treeRes = await fetch(gitUrl(repo, 'trees'), {
+        method: 'POST',
+        headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+        body: JSON.stringify({ base_tree: baseTree, tree }),
+    });
+    if (!treeRes.ok) {
+        // A 422 means an entry is unprocessable against the base tree, which a delete of an
+        // already-removed path produces (a concurrent delete or rename got there first). Treat it as
+        // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
+        // reload-and-retry path instead of a raw 500.
+        if (treeRes.status === 422)
+            throw new CommitConflictError(`${repo.branch} (tree create)`);
+        throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+    }
+    const newTree = (await treeRes.json()).sha;
+    const commitRes = await fetch(gitUrl(repo, 'commits'), {
+        method: 'POST',
+        headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+        body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
+    });
+    if (!commitRes.ok)
+        throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
+    const newCommit = (await commitRes.json()).sha;
+    const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
+        method: 'PATCH',
+        headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sha: newCommit, force: false }),
+    });
+    if (refRes.ok)
+        return { sha: newCommit };
+    // A non-fast-forward means the branch moved; the caller decides whether to retry or fail closed.
+    // Any other failure is not a race, so surface it.
+    if (refRes.status !== 422)
+        throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+    return { conflict: true };
+}
+/** Fail-closed commit on a known head: a non-fast-forward becomes a `CommitConflictError`. */
+async function commitOnHead(repo, head, tree, opts, token) {
+    const result = await commitOnTree(repo, head, tree, opts, token);
+    if ('conflict' in result)
+        throw new CommitConflictError(`${repo.branch} (head moved)`);
+    return result.sha;
+}
 /**
  * Commit several path changes in one commit over the Git Data API. The author is the editor; the
  * committer is omitted, so GitHub attributes the commit to the App. Returns the new commit sha.
@@ -161,48 +167,31 @@ const COMMIT_RETRIES = 3;
  *
  * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
  * site redeploy for no content change.
+ *
+ * When `expectedHead` is supplied the commit is fail-closed: it makes a single attempt with no
+ * retry, throws a `CommitConflictError` when the branch head is not `expectedHead` (a concurrent
+ * commit landed), and otherwise commits onto that head. The nav and settings writes, which land on
+ * the default branch and trigger a deploy, pass it so a same-branch race surfaces the editor's
+ * reload-and-reapply prompt rather than a silent last-writer-wins. Omitting it keeps the
+ * head-merge retry the entry and publish paths rely on.
  */
-export async function commitFiles(repo, changes, opts, token) {
+export async function commitFiles(repo, changes, opts, token, expectedHead) {
     if (changes.length === 0)
         throw new Error('commitFiles: no changes to commit');
     const tree = treeChanges(changes);
+    if (expectedHead !== undefined) {
+        const head = await headCommitSha(repo, token);
+        if (head !== expectedHead)
+            throw new CommitConflictError(`${repo.branch} (head moved)`);
+        return commitOnHead(repo, head, tree, opts, token);
+    }
     for (let attempt = 0; attempt <= COMMIT_RETRIES; attempt++) {
         const parent = await headCommitSha(repo, token);
-        const baseTree = await commitTreeSha(repo, parent, token);
-        const treeRes = await fetch(gitUrl(repo, 'trees'), {
-            method: 'POST',
-            headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-            body: JSON.stringify({ base_tree: baseTree, tree }),
-        });
-        if (!treeRes.ok) {
-            // A 422 means an entry is unprocessable against the base tree, which a delete of an
-            // already-removed path produces (a concurrent delete or rename got there first). Treat it as
-            // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
-            // reload-and-retry path instead of a raw 500.
-            if (treeRes.status === 422)
-                throw new CommitConflictError(`${repo.branch} (tree create)`);
-            throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
-        }
-        const newTree = (await treeRes.json()).sha;
-        const commitRes = await fetch(gitUrl(repo, 'commits'), {
-            method: 'POST',
-            headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-            body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
-        });
-        if (!commitRes.ok)
-            throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
-        const newCommit = (await commitRes.json()).sha;
-        const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
-            method: 'PATCH',
-            headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sha: newCommit, force: false }),
-        });
-        if (refRes.ok)
-            return newCommit;
+        const result = await commitOnTree(repo, parent, tree, opts, token);
         // A non-fast-forward means the branch moved; retry on the new head so a concurrent commit
-        // is preserved. Any other failure is not a race, so surface it.
-        if (refRes.status !== 422)
-            throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+        // is preserved.
+        if ('sha' in result)
+            return result.sha;
     }
     throw new CommitConflictError(`${repo.branch} (atomic commit)`);
 }

package/dist/github/types.d.ts

@@ -1,4 +1,4 @@
-/** Repo coordinates pinned to a branch: the structural subset of `BackendConfig` the read and commit paths need. */
+/** Repo coordinates pinned to a branch: the `{ owner, repo, branch }` subset the read and commit paths need. */
 export interface RepoRef {
     owner: string;
     repo: string;

package/dist/github/types.js

@@ -1,7 +1,7 @@
-// cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
-// reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
-// `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is
-// wanted with no conversion.
+// cairn-cms: the GitHub backend's plain data types and its one typed error. The GitHub App
+// provider config (`githubApp`'s input) carries these repo coordinates; `RepoRef` is the
+// `{ owner, repo, branch }` subset the read and commit transports take, so the provider config
+// is assignable wherever a `RepoRef` is wanted with no conversion.
 /**
  * A concurrent edit lost the SHA race: the file changed between the read and the PUT, from
  * another editor or the site's own CI. Thrown so the save fails safe (re-fetch and ask the

package/dist/index.d.ts

@@ -2,26 +2,27 @@ export { requireOrigin } from './env.js';
 export type { Role, Editor, AuthEnv } from './auth/types.js';
 export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
 export { buildMagicLinkMessage, cloudflareSend } from './email.js';
-export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ImageField, ImageValue, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
-export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export type { CairnAdapter, ConceptConfig, NamedField, ImageValue, ValidationResult, ValidationIssue, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, SiteRender, AdminPanel, FieldTypeDef, } from './content/types.js';
+export { normalizeConcepts, findConcept, defineConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } from './content/compose.js';
 export { frontmatterFromForm, dateInputValue, serializeMarkdown, parseMarkdown, } from './content/frontmatter.js';
-export { defineFields } from './content/schema.js';
 export { defineAdapter } from './content/adapter.js';
-export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
+export type { StandardInput, StandardSchemaV1 } from './content/standard-schema.js';
 export { fields } from './content/fields.js';
-export type { FieldDescriptor } from './content/fields.js';
+export type { FieldDescriptor, TextField, TextareaField, NumberField, SelectField, MultiselectField, UrlField, EmailField, DateField, DatetimeField, BooleanField, IconField, ImageField, ObjectField, ReferenceField, ArrayField, } from './content/fields.js';
 export { fieldset, initialValues } from './content/fieldset.js';
-export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable } from './content/fieldset.js';
+export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable, FieldBehavior } from './content/fieldset.js';
 export { isValidId, idFromFilename, filenameFromId, slugify, slugFromId, composeDatedId, } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
 export { parseCairnToken, extractCairnLinks, formatCairnToken, escapeLinkText } from './content/links.js';
 export type { CairnRef, LinkResolve } from './content/links.js';
-export { serializeManifest, parseManifest, emptyManifest, verifyManifest, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
-export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } from './content/manifest.js';
-export { defineRegistry, emptyValues } from './render/registry.js';
-export type { ComponentDef, ComponentRegistry, FieldType, AttributeField, SlotKind, SlotDef, ComponentValues, } from './render/registry.js';
+export { serializeManifest, parseManifest, emptyManifest, verifyManifest, verifyReferences, diffManifests, upsertEntry, removeEntry, manifestEntryFromFile, manifestLinkResolver, inboundLinks, } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink, InboundReference } from './content/manifest.js';
+export type { ReferenceEdge } from './content/references.js';
+export type { ResolvedReference } from './delivery/site-resolver.js';
+export { defineRegistry, defineComponent, emptyValues } from './render/registry.js';
+export type { ComponentDef, ComponentRegistry, SlotKind, SlotDef, ComponentValues, } from './render/registry.js';
 export { serializeComponent, parseComponent } from './render/component-grammar.js';
 export { validateComponent } from './render/component-validate.js';
 export type { ComponentValidation } from './render/component-validate.js';
@@ -33,7 +34,10 @@ export type { IconSet } from './render/glyph.js';
 export { remarkDirectiveStamp } from './render/remark-directives.js';
 export { createRenderer } from './render/pipeline.js';
 export type { RendererOptions } from './render/pipeline.js';
-export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
+export type { RepoFile, CommitAuthor } from './github/types.js';
 export { CommitConflictError } from './github/types.js';
-export { parseSiteConfig, urlPolicyFrom, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
+export { githubApp } from './github/backend.js';
+export type { Backend, BackendProvider, GithubAppProvider, BackendEnv } from './github/backend.js';
+export type { FileChange } from './github/repo.js';
+export { parseSiteConfig, extractMenu, setMenu, validateNavTree, MAX_NAV_NODES, NavValidationError, SiteConfigError, } from './nav/site-config.js';
 export type { NavNode, SiteConfig } from './nav/site-config.js';