@glw907/cairn-cms 0.60.0 → 0.62.1

package/src/lib/content/advisories.ts

@@ -0,0 +1,141 @@
+// cairn-cms: the entry editor's internal advisory channel (editor-help pass 3). An advisory is a
+// non-blocking, serializable notice that rides EditData across the SSR boundary, so it carries data
+// only and never a callback. Today's one notice is the cross-branch address collision: a warning,
+// not a gate, that another entry already resolves to the same public address (last-write-wins).
+//
+// The address index mirrors buildUsageIndex (src/lib/media/usage.ts): a main arm that reads each
+// manifest entry's resolved permalink with no per-file read, and a branch arm that lists every open
+// cairn/* branch, reconstructs each edited entry's path from the branch name, reads that one file,
+// and resolves its permalink. The map is keyed by permalink, so every entry that resolves to a given
+// address shares one bucket. The build fails open: a branch read that throws, or a dated entry whose
+// permalink cannot resolve, is skipped rather than thrown, so a transient failure degrades to no
+// notice and never blocks the editor or the publish.
+import type { ConceptDescriptor } from './types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from './manifest.js';
+import { listBranches } from '../github/branches.js';
+import { readRaw } from '../github/repo.js';
+import { PENDING_PREFIX, parsePendingBranch } from './pending.js';
+import { findConcept } from './concepts.js';
+import { isValidId, filenameFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { entryIdentity } from './identity.js';
+
+/** One action an advisory offers, as a label and an optional link target. */
+export interface AdvisoryAction {
+  /** The action's button or link label. */
+  label: string;
+  /** The link target, when the action navigates. */
+  href?: string;
+}
+
+/** A non-blocking editor notice, serializable so it can ride EditData across the SSR boundary. */
+export interface AdvisoryNotice {
+  /** The notice kind, e.g. "address-collision". */
+  kind: string;
+  /** The advisory severity; warn-and-allow, never a gate. */
+  severity: 'warn';
+  /** The notice text shown to the editor. */
+  message: string;
+  /** The notice's offered actions, when any. */
+  actions?: AdvisoryAction[];
+}
+
+/** One entry that resolves to an address, in a shape the collision check and the message read. */
+export interface AddressEntry {
+  /** The concept id, e.g. "pages". */
+  concept: string;
+  /** The entry id (its filename stem). */
+  id: string;
+  /** The entry title for display, from the manifest (main) or frontmatter (branch). */
+  title: string;
+  /** The published corpus on main, or an open cairn/* edit branch. */
+  source: 'main' | 'branch';
+}
+
+/** Permalink to the distinct entries that resolve to it, across main and every open branch. */
+export type AddressIndex = Map<string, AddressEntry[]>;
+
+/** Append a row under its permalink, creating the bucket on first use. */
+function push(index: AddressIndex, permalink: string, entry: AddressEntry): void {
+  const rows = index.get(permalink);
+  if (rows) rows.push(entry);
+  else index.set(permalink, [entry]);
+}
+
+/**
+ * Build the permalink-keyed address index over main (from each manifest entry's resolved permalink)
+ * plus every open cairn/* branch (resolved from its edited markdown).
+ *
+ * The build fails open: a branch read that throws and a permalink that cannot resolve are both caught
+ * and skipped, so a transient failure degrades to a thinner index, never a thrown editor or a blocked
+ * publish. The branches are read in one Promise.all, the way buildUsageIndex reads them.
+ */
+export async function buildAddressIndex(
+  repo: RepoRef,
+  token: string,
+  concepts: ConceptDescriptor[],
+  manifest: Manifest,
+): Promise<AddressIndex> {
+  const index: AddressIndex = new Map();
+
+  // The main arm: the manifest already carries each entry's resolved permalink, so this is a pure
+  // reverse map with no per-file read.
+  for (const entry of manifest.entries) {
+    push(index, entry.permalink, {
+      concept: entry.concept,
+      id: entry.id,
+      title: entry.title,
+      source: 'main',
+    });
+  }
+
+  // The branch arm: read each open cairn/* branch's one edited file and resolve its permalink. The
+  // path is derivable from the branch name, so no tree-listing is needed.
+  const names = await listBranches(repo, PENDING_PREFIX, token);
+  const perBranch = await Promise.all(
+    names.map(async (name): Promise<{ permalink: string; entry: AddressEntry } | null> => {
+      // Resolve the branch name with the branch tooling's guard: a malformed name, an id that fails
+      // the slug rule, or an unconfigured concept is skipped with no read attempted.
+      const ref = parsePendingBranch(name);
+      if (!ref || !isValidId(ref.id)) return null;
+      const concept = findConcept(concepts, ref.concept);
+      if (!concept) return null;
+
+      const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+      try {
+        const raw = await readRaw({ ...repo, branch: name }, path, token);
+        if (raw === null) return null; // The file is absent on the branch: nothing to resolve.
+        const { frontmatter } = parseMarkdown(raw);
+        const fmTitle = frontmatter.title;
+        const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+        // entryIdentity throws for a dated entry with no date; that branch is caught and skipped.
+        const { permalink } = entryIdentity(concept, path, frontmatter);
+        return { permalink, entry: { concept: concept.id, id: ref.id, title, source: 'branch' } };
+      } catch {
+        // A failed branch read or an unresolvable permalink degrades this one branch, fail open.
+        return null;
+      }
+    }),
+  );
+
+  // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+  for (const row of perBranch) {
+    if (row) push(index, row.permalink, row.entry);
+  }
+
+  return index;
+}
+
+/**
+ * Find the first other entry that already resolves to an address, or null when the address is free
+ * or holds only the entry itself. The self entry is identified by its concept and id together.
+ */
+export function addressCollision(
+  index: AddressIndex,
+  self: { concept: string; id: string },
+  address: string,
+): AddressEntry | null {
+  const rows = index.get(address) ?? [];
+  return rows.find((row) => row.concept !== self.concept || row.id !== self.id) ?? null;
+}

package/src/lib/content/compose.ts

@@ -8,9 +8,11 @@ import { resolveConcepts } from './concepts.js';
 import { normalizeAssets } from '../media/config.js';
 import { dictionaryFileForDialect, type SiteConfig } from '../nav/site-config.js';
 
-/** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
+/**
+ * The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
  *  always derived from one source and can never be silently dropped. `extensions` fold in after the
- *  adapter's concepts. */
+ *  adapter's concepts.
+ */
 export interface ComposeInput {
   adapter: CairnAdapter;
   siteConfig: SiteConfig;
@@ -40,6 +42,7 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }: Compose
     concepts: resolveConcepts(content, siteConfig),
     backend: adapter.backend,
     sender: adapter.sender,
+    supportContact: adapter.supportContact,
     render: adapter.render,
     manifestPath: adapter.manifestPath ?? 'src/content/.cairn/index.json',
     registry: adapter.registry,

package/src/lib/content/excerpt.ts

@@ -2,8 +2,10 @@
 // 5). A light markdown strip keeps summaries cheap, so a list card, an og:description, and a
 // summary-mode feed read one derived excerpt without a full render.
 
-/** Reduce markdown to readable plain text: drop fenced code, images, and markup; unwrap inline
- * code and links to their text; collapse whitespace. */
+/**
+ * Reduce markdown to readable plain text: drop fenced code, images, and markup; unwrap inline
+ * code and links to their text; collapse whitespace.
+ */
 function toPlainText(md: string): string {
   return md
     .replace(/```[\s\S]*?```/g, ' ')

package/src/lib/content/getting-started.ts

@@ -0,0 +1,31 @@
+// cairn-cms: the Help home getting-started progress, derived from the committed manifest and the
+// pending-branch list rather than stored. An entry in the manifest is published to main; a pending
+// item is written on an open cairn/ branch. The three step states fall out of those two inputs, so
+// the count the editor sees is always the real state of the corpus.
+import type { Manifest } from './manifest.js';
+
+/** The three getting-started steps, their completion count, and the fixed step total. */
+export interface GettingStarted {
+  wrotePost: boolean;
+  publishedPost: boolean;
+  createdPage: boolean;
+  doneCount: number;
+  total: 3;
+}
+
+/**
+ * Map the manifest and the pending-branch list to the three getting-started step states. Writing a
+ *  post (published or pending) completes the first step; publishing one completes the second; a page
+ *  (published or pending) completes the third.
+ */
+export function deriveGettingStarted(
+  manifest: Manifest,
+  pending: { concept: string; id: string }[],
+): GettingStarted {
+  const publishedPost = manifest.entries.some((e) => e.concept === 'posts');
+  const wrotePost = publishedPost || pending.some((p) => p.concept === 'posts');
+  const createdPage =
+    manifest.entries.some((e) => e.concept === 'pages') || pending.some((p) => p.concept === 'pages');
+  const doneCount = Number(wrotePost) + Number(publishedPost) + Number(createdPage);
+  return { wrotePost, publishedPost, createdPage, doneCount, total: 3 };
+}

package/src/lib/content/links.ts

@@ -15,8 +15,10 @@ export interface CairnRef {
   id: string;
 }
 
-/** Resolve a reference to its live permalink. Returns undefined when the target is missing (the
- *  preview marks it); the build resolver throws instead, so a dangling token fails the build. */
+/**
+ * Resolve a reference to its live permalink. Returns undefined when the target is missing (the
+ *  preview marks it); the build resolver throws instead, so a dangling token fails the build.
+ */
 export type LinkResolve = (ref: CairnRef) => string | undefined;
 
 /** Parse a `cairn:<concept>/<id>` href, or null for any other href or a malformed token. */
@@ -31,21 +33,27 @@ export function parseCairnToken(href: string): CairnRef | null {
   return { concept, id };
 }
 
-/** Write the `cairn:<concept>/<id>` token for a ref. The inverse of parseCairnToken, so the editor
- *  link picker and the autocomplete write exactly the form the resolver reads back. */
+/**
+ * Write the `cairn:<concept>/<id>` token for a ref. The inverse of parseCairnToken, so the editor
+ *  link picker and the autocomplete write exactly the form the resolver reads back.
+ */
 export function formatCairnToken(ref: CairnRef): string {
   return `cairn:${ref.concept}/${ref.id}`;
 }
 
-/** Escape the characters that would break a markdown link's display text: a backslash and the
+/**
+ * Escape the characters that would break a markdown link's display text: a backslash and the
  *  square brackets that delimit the text. Used where a content title becomes link display text,
- *  so an unbalanced bracket in a title cannot truncate the generated link. */
+ *  so an unbalanced bracket in a title cannot truncate the generated link.
+ */
 export function escapeLinkText(text: string): string {
   return text.replace(/[\\[\]]/g, (ch) => `\\${ch}`);
 }
 
-/** The cairn links a markdown body points at, in first-occurrence order, deduped by concept/id.
- *  Parses the body as mdast, so a token inside a code span or fence is never matched. */
+/**
+ * The cairn links a markdown body points at, in first-occurrence order, deduped by concept/id.
+ *  Parses the body as mdast, so a token inside a code span or fence is never matched.
+ */
 export function extractCairnLinks(body: string): CairnRef[] {
   const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
   const seen = new Set<string>();

package/src/lib/content/manifest.ts

@@ -20,9 +20,11 @@ export interface ManifestEntry {
   summary?: string;
   draft: boolean;
   links: CairnRef[];
-  /** The content hashes of the media this entry references (its hero plus its body images). The
+  /**
+   * The content hashes of the media this entry references (its hero plus its body images). The
    *  main side of the media where-used index. Additive and optional: an entry with no media omits
-   *  the key, and a manifest committed before this field still parses (absent reads as no refs). */
+   *  the key, and a manifest committed before this field still parses (absent reads as no refs).
+   */
   mediaRefs?: string[];
 }
 
@@ -42,9 +44,11 @@ export interface LinkTarget {
   draft: boolean;
 }
 
-/** Build one manifest entry from a content file. Drafts are included and flagged. The id, date, and
+/**
+ * Build one manifest entry from a content file. Drafts are included and flagged. The id, date, and
  *  permalink come from entryIdentity, the same source content-index uses, so a cairn: link resolves to
- *  one URL whether the admin preview reads the manifest or the public build reads the content index. */
+ *  one URL whether the admin preview reads the manifest or the public build reads the content index.
+ */
 export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { path: string; raw: string }): ManifestEntry {
   const { frontmatter, body } = parseMarkdown(file.raw);
   const { id, date, permalink } = entryIdentity(descriptor, file.path, frontmatter);
@@ -75,8 +79,10 @@ function compareRef(a: CairnRef, b: CairnRef): number {
   return a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
 }
 
-/** Serialize canonically: entries sorted by concept then id, links sorted and deduped, a fixed key
- *  order, two-space pretty, and a trailing newline, so the committed file diffs cleanly in a PR. */
+/**
+ * Serialize canonically: entries sorted by concept then id, links sorted and deduped, a fixed key
+ *  order, two-space pretty, and a trailing newline, so the committed file diffs cleanly in a PR.
+ */
 export function serializeManifest(manifest: Manifest): string {
   const entries = [...manifest.entries].sort(compareRef).map((e) => ({
     id: e.id,
@@ -92,10 +98,12 @@ export function serializeManifest(manifest: Manifest): string {
   return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
 }
 
-/** Parse a committed manifest. Throws on malformed JSON, a wrong version, or a malformed entry, so
+/**
+ * Parse a committed manifest. Throws on malformed JSON, a wrong version, or a malformed entry, so
  *  every reader (the save guard, the delete path, the preview) sees a well-formed graph or a clear
  *  error. The build regenerates the manifest, so a real file is always canonical; this guards a
- *  hand-edited or truncated one. */
+ *  hand-edited or truncated one.
+ */
 export function parseManifest(raw: string): Manifest {
   const data = JSON.parse(raw) as unknown;
   if (!data || typeof data !== 'object') {
@@ -163,9 +171,11 @@ export interface ManifestDiff {
 
 const keyOf = (e: ManifestEntry) => `${e.concept}/${e.id}`;
 
-/** Compare a built manifest against a committed one, keyed by concept+id (the same identity
+/**
+ * Compare a built manifest against a committed one, keyed by concept+id (the same identity
  *  upsertEntry and removeEntry use). A changed entry names the fields that differ. Pure, so it is
- *  unit-tested apart from any build. */
+ *  unit-tested apart from any build.
+ */
 export function diffManifests(built: Manifest, committed: Manifest): ManifestDiff {
   const builtByKey = new Map(built.entries.map((e) => [keyOf(e), e]));
   const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
@@ -195,10 +205,12 @@ function formatDiff(d: ManifestDiff): string {
   return lines.join('\n');
 }
 
-/** Throw if the committed manifest drifts from what the corpus says. The canonical serialized form
+/**
+ * Throw if the committed manifest drifts from what the corpus says. The canonical serialized form
  *  is the fast-path equality guard, so semantic equality never spuriously fails. On a mismatch the
  *  error names the added, removed, and changed entries, so a raw-git content edit that leaves the
- *  committed manifest stale fails the build loudly with what drifted. */
+ *  committed manifest stale fails the build loudly with what drifted.
+ */
 export function verifyManifest(built: Manifest, committedRaw: string): void {
   const builtRaw = serializeManifest(built);
   if (committedRaw === builtRaw) return;
@@ -236,8 +248,10 @@ export function verifyManifest(built: Manifest, committedRaw: string): void {
   );
 }
 
-/** Replace the entry with the same concept and id, or add it. Order does not matter, since
- *  serializeManifest sorts. This is the save path's incremental patch. */
+/**
+ * Replace the entry with the same concept and id, or add it. Order does not matter, since
+ *  serializeManifest sorts. This is the save path's incremental patch.
+ */
 export function upsertEntry(manifest: Manifest, entry: ManifestEntry): Manifest {
   const entries = manifest.entries.filter((e) => !(e.concept === entry.concept && e.id === entry.id));
   entries.push(entry);
@@ -257,9 +271,11 @@ export interface InboundLink {
   permalink: string;
 }
 
-/** Every entry whose outbound edges point at the target, excluding the target itself. The delete
+/**
+ * Every entry whose outbound edges point at the target, excluding the target itself. The delete
  *  guard reads this to name "what links here"; the backlinks panel will reuse it. Pure over the
- *  manifest, so the request-time delete path and a unit test call it the same way. */
+ *  manifest, so the request-time delete path and a unit test call it the same way.
+ */
 export function inboundLinks(manifest: Manifest, concept: string, id: string): InboundLink[] {
   return manifest.entries
     .filter((e) => !(e.concept === concept && e.id === id))
@@ -267,8 +283,10 @@ export function inboundLinks(manifest: Manifest, concept: string, id: string): I
     .map((e) => ({ concept: e.concept, id: e.id, title: e.title, permalink: e.permalink }));
 }
 
-/** A resolver backed by manifest targets, for the admin preview. A miss returns undefined, so the
- *  render step marks the link broken rather than throwing. The build resolver throws instead. */
+/**
+ * A resolver backed by manifest targets, for the admin preview. A miss returns undefined, so the
+ *  render step marks the link broken rather than throwing. The build resolver throws instead.
+ */
 export function manifestLinkResolver(targets: { concept: string; id: string; permalink: string }[]): LinkResolve {
   const byKey = new Map(targets.map((t) => [`${t.concept}/${t.id}`, t.permalink]));
   return (ref) => byKey.get(`${ref.concept}/${ref.id}`);

package/src/lib/content/media-refs.ts

@@ -20,11 +20,13 @@ import { visit } from 'unist-util-visit';
 import { parseMediaToken } from '../media/reference.js';
 import type { FrontmatterField, ImageValue } from './types.js';
 
-/** The content hashes one entry references, in first-occurrence order, deduped by hash. Reads the
+/**
+ * The content hashes one entry references, in first-occurrence order, deduped by hash. Reads the
  *  frontmatter hero `image.src` for each `image`-typed field plus every body image node. A
  *  non-media or malformed token is skipped, never thrown, so a stray `![](/x.png)` does not break
  *  the manifest build. The body is parsed as mdast, so a `media:` token inside a code span or fence
- *  is never matched. */
+ *  is never matched.
+ */
 export function extractMediaRefs(
   frontmatter: Record<string, unknown>,
   body: string,