@glw907/cairn-cms 0.60.0 → 0.62.1

package/dist/content/advisories.js

@@ -0,0 +1,79 @@
+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';
+/** Append a row under its permalink, creating the bucket on first use. */
+function push(index, permalink, entry) {
+    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, token, concepts, manifest) {
+    const index = 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) => {
+        // 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, self, address) {
+    const rows = index.get(address) ?? [];
+    return rows.find((row) => row.concept !== self.concept || row.id !== self.id) ?? null;
+}

package/dist/content/compose.d.ts

@@ -1,8 +1,10 @@
 import type { CairnAdapter, CairnExtension, CairnRuntime } from './types.js';
 import { 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;

package/dist/content/compose.js

@@ -28,6 +28,7 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }) {
         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/dist/content/excerpt.js

@@ -1,8 +1,10 @@
 // cairn-cms: excerpt and word count for content summaries (public-delivery design, decision
 // 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) {
     return md
         .replace(/```[\s\S]*?```/g, ' ')

package/dist/content/getting-started.d.ts

@@ -0,0 +1,18 @@
+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 declare function deriveGettingStarted(manifest: Manifest, pending: {
+    concept: string;
+    id: string;
+}[]): GettingStarted;

package/dist/content/getting-started.js

@@ -0,0 +1,12 @@
+/**
+ * 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, pending) {
+    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/dist/content/links.d.ts

@@ -3,20 +3,28 @@ export interface CairnRef {
     concept: string;
     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. */
 export declare function parseCairnToken(href: string): CairnRef | null;
-/** 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 declare function formatCairnToken(ref: CairnRef): string;
-/** 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 declare function escapeLinkText(text: string): string;
-/** 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 declare function extractCairnLinks(body: string): CairnRef[];
 /**
  * Rewrite every cairn: link whose href is exactly `oldHref` so its href becomes `newHref`, keeping

package/dist/content/links.js

@@ -21,19 +21,25 @@ export function parseCairnToken(href) {
         return 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) {
     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) {
     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) {
     const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
     const seen = new Set();

package/dist/content/manifest.d.ts

@@ -10,9 +10,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[];
 }
 /** The whole corpus as one committed file. `version` guards a future shape migration. */
@@ -29,22 +31,28 @@ export interface LinkTarget {
     date?: string;
     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 declare function manifestEntryFromFile(descriptor: ConceptDescriptor, file: {
     path: string;
     raw: string;
 }): ManifestEntry;
 /** An empty manifest, the starting point when no committed file exists yet. */
 export declare function emptyManifest(): Manifest;
-/** 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 declare function serializeManifest(manifest: Manifest): string;
-/** 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 declare function parseManifest(raw: string): Manifest;
 /** A changed entry and the fields that differ between the built and committed manifests. */
 export interface ManifestEntryDiff {
@@ -58,17 +66,23 @@ export interface ManifestDiff {
     removed: ManifestEntry[];
     changed: ManifestEntryDiff[];
 }
-/** 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 declare function diffManifests(built: Manifest, committed: Manifest): ManifestDiff;
-/** 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 declare 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 declare function upsertEntry(manifest: Manifest, entry: ManifestEntry): Manifest;
 /** Drop the entry with the given concept and id, if present. The delete path's patch. */
 export declare function removeEntry(manifest: Manifest, concept: string, id: string): Manifest;
@@ -79,12 +93,16 @@ export interface InboundLink {
     title: string;
     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 declare function inboundLinks(manifest: Manifest, concept: string, id: string): InboundLink[];
-/** 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 declare function manifestLinkResolver(targets: {
     concept: string;
     id: string;

package/dist/content/manifest.js

@@ -8,9 +8,11 @@ import { deriveExcerpt } from './excerpt.js';
 import { entryIdentity, asString } from './identity.js';
 import { extractCairnLinks } from './links.js';
 import { extractMediaRefs } from './media-refs.js';
-/** 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, file) {
     const { frontmatter, body } = parseMarkdown(file.raw);
     const { id, date, permalink } = entryIdentity(descriptor, file.path, frontmatter);
@@ -38,8 +40,10 @@ export function emptyManifest() {
 function compareRef(a, b) {
     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) {
     const entries = [...manifest.entries].sort(compareRef).map((e) => ({
         id: e.id,
@@ -54,10 +58,12 @@ export function serializeManifest(manifest) {
     }));
     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) {
     const data = JSON.parse(raw);
     if (!data || typeof data !== 'object') {
@@ -108,9 +114,11 @@ export function parseManifest(raw) {
     return { version: 1, entries: obj.entries };
 }
 const keyOf = (e) => `${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, committed) {
     const builtByKey = new Map(built.entries.map((e) => [keyOf(e), e]));
     const committedByKey = new Map(committed.entries.map((e) => [keyOf(e), e]));
@@ -141,10 +149,12 @@ function formatDiff(d) {
         lines.push(`  ~ ${e.concept}/${e.id} (${e.fields.join(', ')})`);
     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, committedRaw) {
     const builtRaw = serializeManifest(built);
     if (committedRaw === builtRaw)
@@ -181,8 +191,10 @@ export function verifyManifest(built, committedRaw) {
         formatDiff(diff) +
         '\nRegenerate it (npm run cairn:manifest) and commit the result.');
 }
-/** 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, entry) {
     const entries = manifest.entries.filter((e) => !(e.concept === entry.concept && e.id === entry.id));
     entries.push(entry);
@@ -192,17 +204,21 @@ export function upsertEntry(manifest, entry) {
 export function removeEntry(manifest, concept, id) {
     return { version: 1, entries: manifest.entries.filter((e) => !(e.concept === concept && e.id === id)) };
 }
-/** 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, concept, id) {
     return manifest.entries
         .filter((e) => !(e.concept === concept && e.id === id))
         .filter((e) => e.links.some((l) => l.concept === concept && l.id === id))
         .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) {
     const byKey = new Map(targets.map((t) => [`${t.concept}/${t.id}`, t.permalink]));
     return (ref) => byKey.get(`${ref.concept}/${ref.id}`);

package/dist/content/media-refs.d.ts

@@ -1,7 +1,9 @@
 import type { FrontmatterField } 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 declare function extractMediaRefs(frontmatter: Record<string, unknown>, body: string, fields: FrontmatterField[]): string[];

package/dist/content/media-refs.js

@@ -18,11 +18,13 @@ import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import { visit } from 'unist-util-visit';
 import { parseMediaToken } from '../media/reference.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, body, fields) {
     const seen = new Set();
     const hashes = [];

package/dist/content/media-rewrite.d.ts

@@ -24,12 +24,16 @@ export interface RepointResult {
  * untouched. Pure and node-safe.
  */
 export declare function repointMediaRef(markdown: string, oldHash: string, newToken: string): RepointResult;
-/** Which alt bucket a placement falls in: an empty alt always gets filled, a non-empty (custom) alt is
- *  reported and only overwritten on opt-in, and a decorative hero is never touched. */
+/**
+ * Which alt bucket a placement falls in: an empty alt always gets filled, a non-empty (custom) alt is
+ *  reported and only overwritten on opt-in, and a decorative hero is never touched.
+ */
 export type AltBucket = 'will-fill' | 'customized' | 'decorative-skipped';
-/** One placement of the target hash and what the alt-fill does to it: which surface it lives on, its
+/**
+ * One placement of the target hash and what the alt-fill does to it: which surface it lives on, its
  *  bucket, the existing alt, and the alt after the transform (unchanged for a customized alt left as
- *  is and for a decorative hero). */
+ *  is and for a decorative hero).
+ */
 export interface AltPlacement {
     kind: 'body' | 'figure' | 'hero';
     bucket: AltBucket;