@glw907/cairn-cms 0.57.1 → 0.59.0

package/src/lib/media/orphan-scan.ts

@@ -0,0 +1,74 @@
+// cairn-cms: the orphan-scan projection, the pure model behind the admin Media Library's scan
+// surface. It folds reconcileMedia's two directions together with the usage index into the two rows
+// the screen renders: the purgeable byte-rows and the read-only broken-reference rows (manifest rows
+// whose bytes are gone). It only projects; no path here reads R2, the manifest, or git. The module
+// is engine-internal and on no public subpath.
+//
+// An orphaned byte is a stored R2 object whose hash has NO manifest row AND appears in NO usage row,
+// so it is referenced nowhere across main and every open branch. Reconcile only checks main's
+// manifest, so a branch-only upload (bytes in R2, manifest row only on the open cairn/* branch) gets
+// flagged as an orphaned object even though a colleague's in-progress draft references it. The byte
+// purge is irreversible, so we intersect reconcile's verdict with the strict cross-branch usage
+// index here: any hash the index references is in use and is dropped from orphanedBytes, which keeps
+// a live draft's bytes from ever reaching the purge surface.
+import { MEDIA_KEY_RE, type ReconcileResult } from './reconcile.js';
+import type { MediaManifest } from './manifest.js';
+import type { UsageEntry, UsageIndex } from './usage.js';
+
+/** A purgeable orphan: a stored R2 key with no manifest row, plus the 16-hex hash parsed from it. */
+export interface OrphanByteRow {
+  /** The full R2 object key, e.g. "media/ff/ffffffffffffffff.webp". */
+  key: string;
+  /** The 16-hex content hash parsed from the key. */
+  hash: string;
+}
+
+/** A broken reference: a manifest row whose bytes are gone. Read-only, since purging it would drop a
+ *  still-referenced asset's record; the screen shows where it is used so an operator can re-ingest. */
+export interface BrokenRefRow {
+  /** The 16-hex content hash of the manifest row whose bytes are missing. */
+  hash: string;
+  /** The manifest row's display slug, or '' when the row is somehow absent. */
+  slug: string;
+  /** Where the asset is referenced, from the usage index. Empty when no reference was found. */
+  usage: UsageEntry[];
+}
+
+/** The scan surface model: the two row sets the Library renders. */
+export interface OrphanScan {
+  orphanedBytes: OrphanByteRow[];
+  brokenRefs: BrokenRefRow[];
+}
+
+/**
+ * Project a reconcile read plus the usage index into the scan surface model.
+ *
+ * `orphanedBytes` come from `reconcile.orphanedObjects`: each key is parsed to its hash via the
+ * shared media-key grammar, and a key that does not match (so it is not a content-addressed media
+ * object) is skipped. A key whose hash the usage index references is also skipped: it is referenced
+ * on main or some open branch, so its bytes are in use, not orphaned. `brokenRefs` come from
+ * `reconcile.missingObjects`: each hash carries its
+ * manifest slug (falling back to '' when the row is absent) and its where-used rows from the index
+ * (an empty list when no reference was found). Both directions keep their input order.
+ */
+export function buildOrphanScan(
+  reconcile: ReconcileResult,
+  manifest: MediaManifest,
+  index: UsageIndex,
+): OrphanScan {
+  const orphanedBytes: OrphanByteRow[] = [];
+  for (const key of reconcile.orphanedObjects) {
+    const hash = MEDIA_KEY_RE.exec(key)?.[1];
+    if (hash === undefined) continue;
+    if (index.has(hash)) continue;
+    orphanedBytes.push({ key, hash });
+  }
+
+  const brokenRefs: BrokenRefRow[] = reconcile.missingObjects.map((hash) => ({
+    hash,
+    slug: manifest[hash]?.slug ?? '',
+    usage: index.get(hash) ?? [],
+  }));
+
+  return { orphanedBytes, brokenRefs };
+}

package/src/lib/media/reconcile.ts

@@ -8,8 +8,9 @@
 import type { MediaManifest } from './manifest.js';
 import { log } from '../log/index.js';
 
-/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. */
-const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
+ *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar. */
+export const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
 
 /** What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
  *  has no manifest row; `missingObjects` are manifest hashes with no stored object. */

package/src/lib/media/rewrite-plan.ts

@@ -0,0 +1,122 @@
+// cairn-cms: the server-side media rewrite planner, the shared core behind the media-library bulk
+// rewrite preview and apply (replace-in-place and fill-alt). Given an asset content hash and a per
+// entry transform (the closure already carries the new token or the default alt), it resolves which
+// published main entries reference the hash, runs the transform over each, and returns a preview
+// plan: the affected entries with their rewritten markdown and per-placement diff, plus the affected
+// count. It also returns a report-only cross-branch delta, the open cairn/* edit branches that
+// reference the same bytes, so the screen can warn that an apply touches main only and the drafts
+// keep their own copy of the reference until they publish.
+//
+// It is fail-closed. The usage read runs in strict mode, so a transient branch-read failure throws
+// out of here rather than degrading to an "absent reference" the way the Library display tolerates.
+// A planner that fed a partial usage view into an apply would rewrite some references and silently
+// leave others, so it must reject instead. This is the same gate the 3c safe-delete uses.
+//
+// It lives in its own node-safe module (no @codemirror, no DOM, no @sveltejs/kit): the transform is
+// injected, so the planner never imports the editor surface. It is internal, exported from no package
+// subpath, so it carries no reference page.
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from '../content/manifest.js';
+import { findConcept } from '../content/concepts.js';
+import { filenameFromId } from '../content/ids.js';
+import { readRaw } from '../github/repo.js';
+import { buildUsageIndex } from './usage.js';
+
+/** One main entry the rewrite will touch: its identity, its file path, the transform's per-placement
+ *  diff, and the rewritten markdown a later apply commits. `P` is the transform's placement type
+ *  (a RepointPlacement for replace, an AltPlacement for fill-alt). */
+export interface PlannedEntry<P = unknown> {
+  /** The concept id, e.g. "posts". */
+  concept: string;
+  /** The entry id (its filename stem). */
+  id: string;
+  /** The entry's repo path, `${concept.dir}/${filenameFromId(id)}`. */
+  path: string;
+  /** The transform's diff for this entry: one placement per rewritten reference. */
+  placements: P[];
+  /** The entry's markdown after the transform, byte-identical to the source apart from the rewrite. */
+  newMarkdown: string;
+}
+
+/** One open edit branch that also references the asset, with the entries on it. Report-only: an apply
+ *  rewrites main, never a branch, so the screen surfaces these as a delta the editor handles by
+ *  republishing the draft. */
+export interface BranchRef {
+  /** The cairn/* branch name. */
+  branch: string;
+  /** The entries on that branch that reference the asset. */
+  entries: { concept: string; id: string }[];
+}
+
+/** The preview plan: the main entries to rewrite, the report-only branch delta, and the distinct
+ *  count of affected main entries (the entries the transform actually changed). */
+export interface RewritePlan<P = unknown> {
+  entries: PlannedEntry<P>[];
+  branchDelta: BranchRef[];
+  affectedCount: number;
+}
+
+/**
+ * Plan a media rewrite for one asset hash. Builds the cross-branch usage index in strict mode (so an
+ * unverifiable branch read rejects, failing closed), then splits the rows for `args.hash` by origin:
+ *
+ * - Published rows are the main work. Each entry's file is read in parallel and run through
+ *   `args.transform`. An entry is included only when the transform reports at least one placement, so
+ *   a row whose body holds the token in a non-image position (a code span, raw HTML) drops out rather
+ *   than committing an unchanged file. A row whose concept is not configured, or whose file read
+ *   returns null (a stale manifest row), is skipped.
+ * - Branch rows are the report-only delta, grouped by branch in first-seen order. Branch rows are
+ *   never the published origin, so main never appears in the delta.
+ *
+ * `affectedCount` is the number of distinct entries in `entries` (the ones the transform changed). The
+ * planner does not read the media manifest: the transform closure already carries the new token or
+ * the default alt, so the planner needs only the entry markdown and the usage index. Pure of the
+ * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
+ */
+export async function planMediaRewrite<P = unknown>(args: {
+  backend: RepoRef;
+  token: string;
+  concepts: ConceptDescriptor[];
+  contentManifest: Manifest;
+  hash: string;
+  transform: (markdown: string) => { markdown: string; placements: P[] };
+}): Promise<RewritePlan<P>> {
+  // Strict so an unverifiable branch read rejects here rather than degrading to an absent reference.
+  // Do NOT wrap this: the throw is the fail-closed contract the apply relies on.
+  const index = await buildUsageIndex(args.backend, args.token, args.concepts, args.contentManifest, {
+    strict: true,
+  });
+  const rows = index.get(args.hash) ?? [];
+
+  // The main arm: read each referencing published entry in parallel (one round-trip latency floor,
+  // mirroring buildUsageIndex's per-branch batch), run the transform, and keep only the entries it
+  // changed. A null is a row whose concept is not configured or whose file is absent: it is skipped.
+  const published = rows.filter((row) => row.origin.kind === 'published');
+  const planned = await Promise.all(
+    published.map(async (row): Promise<PlannedEntry<P> | null> => {
+      const concept = findConcept(args.concepts, row.concept);
+      if (!concept) return null;
+      const path = `${concept.dir}/${filenameFromId(row.id)}`;
+      const markdown = await readRaw(args.backend, path, args.token);
+      if (markdown === null) return null;
+      const result = args.transform(markdown);
+      if (result.placements.length === 0) return null;
+      return { concept: row.concept, id: row.id, path, placements: result.placements, newMarkdown: result.markdown };
+    }),
+  );
+  const entries = planned.filter((entry): entry is PlannedEntry<P> => entry !== null);
+
+  // The branch arm: group the branch rows by branch in first-seen order, preserving the row order the
+  // index emits within each group. Branch rows are never the published origin, so main never appears.
+  const byBranch = new Map<string, { concept: string; id: string }[]>();
+  for (const row of rows) {
+    if (row.origin.kind !== 'branch') continue;
+    const list = byBranch.get(row.origin.branch);
+    if (list) list.push({ concept: row.concept, id: row.id });
+    else byBranch.set(row.origin.branch, [{ concept: row.concept, id: row.id }]);
+  }
+  const branchDelta: BranchRef[] = [...byBranch].map(([branch, branchEntries]) => ({ branch, entries: branchEntries }));
+
+  return { entries, branchDelta, affectedCount: entries.length };
+}

package/src/lib/sveltekit/cairn-admin.ts

@@ -177,6 +177,21 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
     ),
     mediaDelete: viewAction(['media'], (event) => content.mediaDeleteAction(contentEvent(event, {}))),
     mediaUpdate: viewAction(['media'], (event) => content.mediaUpdateAction(contentEvent(event, {}))),
+    // The Library is not entry-scoped, so a replace uploads its new file through the same content-
+    // addressed ingest mounted media-scoped (uploadAction reads no concept/id), then previews and
+    // applies the repoint. Alt propagation previews and applies the alt fill. The preview pair are 2a
+    // fetch actions; the apply pair are form posts. All gate on the media view.
+    mediaUpload: viewAction(['media'], (event) => content.uploadAction(contentEvent(event, {}))),
+    mediaReplacePreview: viewAction(['media'], (event) => content.mediaReplacePreview(contentEvent(event, {}))),
+    mediaReplace: viewAction(['media'], (event) => content.mediaReplaceApply(contentEvent(event, {}))),
+    mediaAltPreview: viewAction(['media'], (event) => content.mediaAltPreview(contentEvent(event, {}))),
+    mediaAltPropagate: viewAction(['media'], (event) => content.mediaAltApply(contentEvent(event, {}))),
+    // Pass C library actions: a multi-select bulk delete, the on-demand orphan scan, and the
+    // irreversible byte purge. The component posts to `?/mediaBulkDelete`, `?/mediaOrphanScan`, and
+    // `?/mediaPurge` (the purge key is short of its content method name). All gate on the media view.
+    mediaBulkDelete: viewAction(['media'], (event) => content.mediaBulkDelete(contentEvent(event, {}))),
+    mediaOrphanScan: viewAction(['media'], (event) => content.mediaOrphanScan(contentEvent(event, {}))),
+    mediaPurge: viewAction(['media'], (event) => content.mediaPurgeOrphans(contentEvent(event, {}))),
     publishAll: viewAction(authedViews, (event) => content.publishAllAction(contentEvent(event, {}))),
     addEditor: viewAction(['editors'], (event) => editors.addEditorAction(event)),
     removeEditor: viewAction(['editors'], (event) => editors.removeEditorAction(event)),