@glw907/cairn-cms 0.17.0 → 0.18.0

package/src/lib/github/repo.ts

@@ -136,3 +136,106 @@ export async function commitFile(
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
+export interface FileChange {
+  path: string;
+  content: string | null;
+}
+
+/** A Git Trees API change entry: a blob written from raw content, or a `sha: null` delete. */
+interface TreeChange {
+  path: string;
+  mode: '100644';
+  type: 'blob';
+  content?: string;
+  sha?: null;
+}
+
+/** A Git Data API URL under the repo's `git/` namespace. */
+function gitUrl(repo: RepoRef, suffix: string): string {
+  return `${API}/repos/${repo.owner}/${repo.repo}/git/${suffix}`;
+}
+
+/** The branch head commit sha, through the Git Data API single-ref read. */
+async function headCommitSha(repo: RepoRef, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `ref/heads/${encodeURIComponent(repo.branch)}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub ref ${repo.branch} failed: ${res.status}`);
+  return ((await res.json()) as { object: { sha: string } }).object.sha;
+}
+
+/** The base tree sha of a commit. */
+async function commitTreeSha(repo: RepoRef, commitSha: string, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `commits/${commitSha}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub commit ${commitSha} failed: ${res.status}`);
+  return ((await res.json()) as { tree: { sha: string } }).tree.sha;
+}
+
+/** Map file changes to Git Trees API entries, encoding a null content as a delete. */
+function treeChanges(changes: FileChange[]): TreeChange[] {
+  return changes.map((c) =>
+    c.content === null
+      ? { path: c.path, mode: '100644', type: 'blob', sha: null }
+      : { path: c.path, mode: '100644', type: 'blob', content: c.content },
+  );
+}
+
+/** Retries after the initial attempt when the branch moves under an atomic commit. */
+const COMMIT_RETRIES = 3;
+
+/**
+ * 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.
+ * Builds the new tree on the current head's tree, so paths not named here are preserved.
+ *
+ * Caller preconditions this layer cannot enforce (the save and lifecycle paths must): every
+ * `path` is confined to the site's content directories (the App token can write anywhere in the
+ * repo), and `author` is derived from the verified server-side session, never request input.
+ *
+ * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
+ * site redeploy for no content change.
+ */
+export async function commitFiles(
+  repo: RepoRef,
+  changes: FileChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  if (changes.length === 0) throw new Error('commitFiles: no changes to commit');
+  const tree = treeChanges(changes);
+  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) throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+    const newTree = ((await treeRes.json()) as { sha: string }).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()) as { sha: string }).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;
+    // 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()}`);
+  }
+  throw new CommitConflictError(`${repo.branch} (atomic commit)`);
+}

package/src/lib/index.ts

@@ -49,6 +49,22 @@ export {
   composeDatedId,
 } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
+// Internal-link token and the committed content manifest (content-graph design). The corpus
+// builder and the request-time resolver ship from the delivery entry; this surface is the
+// grammar, the manifest operations, and their types a migrating site adopts.
+export { parseCairnToken, extractCairnLinks } from './content/links.js';
+export type { CairnRef, LinkResolve } from './content/links.js';
+export {
+  serializeManifest,
+  parseManifest,
+  emptyManifest,
+  verifyManifest,
+  upsertEntry,
+  removeEntry,
+  manifestEntryFromFile,
+  manifestLinkResolver,
+} from './content/manifest.js';
+export type { Manifest, ManifestEntry, LinkTarget } from './content/manifest.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
 export { defineRegistry, emptyValues } from './render/registry.js';
 export type {

package/src/lib/render/pipeline.ts

@@ -8,10 +8,13 @@ import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-sanitize';
 import type { Schema } from 'hast-util-sanitize';
+import { VFile } from 'vfile';
 import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
+import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import type { ComponentRegistry } from './registry.js';
+import type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
   /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
@@ -33,7 +36,7 @@ export interface RendererOptions {
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
-  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
   // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
   // before the dispatch (so the site's trusted build() output and its inline SVG icons are never
   // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
@@ -57,6 +60,9 @@ export function createRenderer(registry: ComponentRegistry, options: RendererOpt
   return {
     remarkPlugins,
     rehypePlugins,
-    renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+    renderMarkdown: async (content: string, opts: { resolve?: LinkResolve } = {}): Promise<string> => {
+      const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+      return String(await processor.process(file));
+    },
   };
 }

package/src/lib/render/resolve-links.ts

@@ -0,0 +1,42 @@
+// cairn-cms: the cairn: link resolver, an mdast step in the render pipeline (content-graph design).
+// It runs before remark-rehype, so the rewritten href passes through the sanitize floor exactly as
+// any other anchor. The per-call resolver is read off the VFile (set by renderMarkdown), so the
+// processor is still built once. A miss either marks the link broken (preview) or throws (build),
+// decided by the injected resolver.
+import { visit } from 'unist-util-visit';
+import type { VFile } from 'vfile';
+import { parseCairnToken, type LinkResolve } from '../content/links.js';
+
+/** The VFile data key the renderer sets the per-call resolver under. */
+export const CAIRN_RESOLVE = 'cairnResolve';
+
+interface LinkNode {
+  url: string;
+  data?: { hProperties?: Record<string, unknown> };
+}
+
+/** Resolve cairn: link nodes against the VFile's resolver. A non-cairn href and a malformed token
+ *  pass through. A missing target is marked with the cairn-broken-link class (the resolver returns
+ *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+export function remarkResolveCairnLinks() {
+  return (tree: unknown, file: VFile): void => {
+    const resolve = file.data[CAIRN_RESOLVE] as LinkResolve | undefined;
+    if (!resolve) return;
+    visit(tree as Parameters<typeof visit>[0], 'link', (node: LinkNode) => {
+      const ref = parseCairnToken(node.url);
+      if (!ref) return;
+      const url = resolve(ref); // may throw (build backstop); propagates out of render
+      if (url) {
+        node.url = url;
+        return;
+      }
+      // Missing target in the preview: mark it broken and neutralize the href, keeping the text.
+      node.url = '#';
+      node.data = node.data ?? {};
+      const props = (node.data.hProperties = node.data.hProperties ?? {});
+      const existing = Array.isArray(props.className) ? (props.className as string[]) : [];
+      props.className = [...existing, 'cairn-broken-link'];
+      props.title = 'Broken internal link';
+    });
+  };
+}

package/src/lib/render/sanitize-schema.ts

@@ -29,6 +29,11 @@ export function buildSanitizeSchema(
   const anchorAttrs = (attributes.a ?? []).filter(
     (entry) => !(Array.isArray(entry) && entry[0] === 'className'),
   );
+  // Admit the inert `cairn:` href scheme on top of the default protocol allowlist. The render
+  // resolver rewrites a `cairn:` link to a live permalink before delivery; an unresolved one
+  // survives the floor in its inert token form (a visible unresolved-link signal), never as an
+  // executable vector. The dangerous-protocol strip (javascript:, data:) is preserved.
+  const protocols = defaultSchema.protocols ?? {};
   const schema: Schema = {
     ...defaultSchema,
     tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
@@ -37,6 +42,10 @@ export function buildSanitizeSchema(
       '*': [...(attributes['*'] ?? []), 'className', ...markers],
       a: [...anchorAttrs, 'className', 'target', 'rel'],
     },
+    protocols: {
+      ...protocols,
+      href: [...(protocols.href ?? []), 'cairn'],
+    },
   };
   return extend ? extend(schema) : schema;
 }

package/src/lib/sveltekit/content-routes.ts

@@ -7,8 +7,9 @@ import { findConcept } from '../content/concepts.js';
 import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
 import { isValidId, slugify, filenameFromId, composeDatedId } from '../content/ids.js';
 import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
+import { listMarkdown, readRaw, commitFiles } from '../github/repo.js';
 import { cachedInstallationToken } from '../github/signing.js';
+import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, type LinkTarget } from '../content/manifest.js';
 import { CommitConflictError } from '../github/types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
@@ -63,6 +64,8 @@ export interface EditData {
   isNew: boolean;
   saved: boolean;
   error: string | null;
+  /** The site's link targets, for the preview resolver and the link picker; from the committed manifest. */
+  linkTargets: LinkTarget[];
 }
 
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
@@ -207,6 +210,20 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
     const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
     const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
+
+    let linkTargets: LinkTarget[] = [];
+    const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+    if (manifestRaw !== null) {
+      linkTargets = parseManifest(manifestRaw).entries.map((e) => ({
+        concept: e.concept,
+        id: e.id,
+        permalink: e.permalink,
+        title: e.title,
+        date: e.date,
+        draft: e.draft,
+      }));
+    }
+
     return {
       conceptId: concept.id,
       id,
@@ -218,6 +235,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       isNew,
       saved: event.url.searchParams.get('saved') === '1',
       error: event.url.searchParams.get('error'),
+      linkTargets,
     };
   }
 
@@ -249,11 +267,25 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
     const markdown = serializeMarkdown(result.data, body);
     const token = await mintToken(event.platform?.env ?? {});
+
+    // Read the committed manifest, upsert this entry's row, and commit content and manifest in one
+    // commit. A missing manifest starts empty (first save on a fresh repo). The build regenerates
+    // and verifies the manifest, so this incremental patch is the cheap request-time path. On a
+    // 422 retry commitFiles re-sends this manifest blob last-writer-wins. A concurrent save can then
+    // leave the committed manifest stale, which the next build rejects via verifyManifest; regenerate
+    // it with npm run cairn:manifest to recover.
+    const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+    const manifest = manifestRaw === null ? emptyManifest() : parseManifest(manifestRaw);
+    const row = manifestEntryFromFile(concept, { path, raw: markdown });
+    const nextManifest = serializeManifest(upsertEntry(manifest, row));
+
     try {
-      await commitFile(
+      await commitFiles(
         runtime.backend,
-        path,
-        markdown,
+        [
+          { path, content: markdown },
+          { path: runtime.manifestPath, content: nextManifest },
+        ],
         { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } },
         token,
       );

package/src/lib/sveltekit/public-routes.ts

@@ -9,11 +9,13 @@ import type { SiteIndex } from '../delivery/site-index.js';
 import { buildSeoMeta } from '../delivery/seo.js';
 import type { SeoMeta } from '../delivery/seo.js';
 import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
+import { buildLinkResolver } from '../delivery/manifest.js';
+import type { LinkResolve } from '../content/links.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
   site: SiteIndex;
-  render: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
+  render: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
   origin: string;
   /** Site name for og:site_name and the SEO head. */
   siteName: string;
@@ -85,7 +87,7 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
       ...(fields.author ? { author: fields.author } : {}),
       ...(entry.date ? { feeds } : {}),
     });
-    return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl, seo, newer, older };
+    return { entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */