@glw907/cairn-cms 0.57.1 → 0.59.0

package/dist/media/reconcile.js

@@ -1,6 +1,7 @@
 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}$/;
 /** The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
  *  both orphan directions. A stored key that does not match the media-key grammar is ignored, since
  *  it is not a content-addressed media object this reconcile owns. */

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

@@ -0,0 +1,65 @@
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from '../content/manifest.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 declare 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>>;

package/dist/media/rewrite-plan.js

@@ -0,0 +1,61 @@
+import { findConcept } from '../content/concepts.js';
+import { filenameFromId } from '../content/ids.js';
+import { readRaw } from '../github/repo.js';
+import { buildUsageIndex } from './usage.js';
+/**
+ * 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(args) {
+    // 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) => {
+        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 !== 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();
+    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 = [...byBranch].map(([branch, branchEntries]) => ({ branch, entries: branchEntries }));
+    return { entries, branchDelta, affectedCount: entries.length };
+}

package/dist/sveltekit/cairn-admin.d.ts

@@ -81,6 +81,14 @@ export declare function createCairnAdmin(runtime: CairnRuntime, deps?: CairnAdmi
         delete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         mediaDelete: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
         mediaUpdate: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaUpload: (event: AdminEvent) => Promise<import("./content-routes.js").UploadResult | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaReplacePreview: (event: AdminEvent) => Promise<import("./content-routes.js").MediaReplacePreviewPlan | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaReplace: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaAltPreview: (event: AdminEvent) => Promise<import("./content-routes.js").MediaAltPreviewPlan | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaAltPropagate: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaBulkDelete: (event: AdminEvent) => Promise<import("./content-routes.js").MediaBulkDeleteResult | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaOrphanScan: (event: AdminEvent) => Promise<import("../media/orphan-scan.js").OrphanScan | import("@sveltejs/kit").ActionFailure<unknown>>;
+        mediaPurge: (event: AdminEvent) => Promise<import("./content-routes.js").MediaOrphanPurgeResult | import("@sveltejs/kit").ActionFailure<unknown>>;
         publishAll: (event: AdminEvent) => Promise<never>;
         addEditor: (event: AdminEvent) => Promise<import("@sveltejs/kit").ActionFailure<{
             error: string;

package/dist/sveltekit/cairn-admin.js

@@ -125,6 +125,21 @@ export function createCairnAdmin(runtime, deps = {}) {
             : content.listDeleteAction(contentEvent(event, { concept: view.concept.id }))),
         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)),

package/dist/sveltekit/content-routes.d.ts

@@ -4,6 +4,10 @@ import { type LinkTarget, type InboundLink } from '../content/manifest.js';
 import type { MediaEntry } from '../media/manifest.js';
 import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js';
 import type { UsageEntry } from '../media/usage.js';
+import { type OrphanScan } from '../media/orphan-scan.js';
+import type { RepointPlacement, AltPlacement } from '../content/media-rewrite.js';
+import type { BranchRef } from '../media/rewrite-plan.js';
+import type { BulkDeleteSkip } from '../media/bulk-delete-plan.js';
 import type { CookieJar, EventBase } from './types.js';
 import type { CairnRuntime, FrontmatterField, ResolvedPreview } from '../content/types.js';
 import type { Role } from '../auth/types.js';
@@ -133,8 +137,10 @@ export interface MediaLibraryData {
      *  redirected commit conflict never overwrite each other. */
     error: string | null;
     /** The success flash a redirected action carries: `deleted` from `?deleted=1`, `updated` from
-     *  `?updated=1`, null otherwise. The component renders a polite success strip for each. */
-    flash: 'deleted' | 'updated' | null;
+     *  `?updated=1`, `replaced` from `?replaced=1`, `altPropagated` from `?altPropagated=1`,
+     *  `bulkDeleted` from `?bulkDeleted=1`, `orphansPurged` from `?orphansPurged=1`, null otherwise.
+     *  The component renders a polite success strip for each. */
+    flash: 'deleted' | 'updated' | 'replaced' | 'altPropagated' | 'bulkDeleted' | 'orphansPurged' | null;
     /** A redirected action's conflict error read from `?error=` (a commit-conflict bounce). Kept in
      *  its own slot rather than the degraded-load `error` above, so the two never collide. */
     flashError: string | null;
@@ -194,11 +200,112 @@ export interface MediaUpdateFailure {
     /** The one-line human summary every action failure carries. */
     error: string;
 }
+/** A refused media replace: `fail(409)` when a fresh usage read finds the asset still in use and the
+ *  typed-slug override was not given, or `fail(503)` when usage cannot be verified (fail closed) or the
+ *  bucket is unbound. Mirrors MediaDeleteRefusal: the asset hash, the where-used rows, and the count. */
+export interface MediaReplaceFailure {
+    error: string;
+    hash: string;
+    usage: UsageEntry[];
+    foundIn: number;
+}
+/** A refused media alt-propagation: `fail(503)` when usage cannot be verified across main and every
+ *  open branch (fail closed), or the bucket is unbound. Just the one-line summary; alt fill has no
+ *  typed-slug gate. */
+export interface MediaAltPropagateFailure {
+    error: string;
+}
+/** A refused media bulk delete or orphan purge: `fail(503)` for the fail-closed strict-usage refusal
+ *  (the whole batch refuses) or media-off / a missing bucket binding. The per-item outcomes ride the
+ *  returned summary, not a fail. */
+export interface MediaBulkFailure {
+    error: string;
+}
+/** The bulk-delete outcome the component renders: the deleted hashes, the skipped rows from the
+ *  partition (with their reason and where-used), and any per-object R2 delete failure. Admin-internal,
+ *  not on the package subpath, so no reference page. */
+export interface MediaBulkDeleteResult {
+    deleted: string[];
+    skipped: BulkDeleteSkip[];
+    failed: {
+        hash: string;
+        error: string;
+    }[];
+}
+/** The orphan-purge outcome: the purged R2 keys, the keys skipped because their hash was claimed by a
+ *  manifest row since the scan, and any per-object delete failure. Admin-internal, no reference page. */
+export interface MediaOrphanPurgeResult {
+    purged: string[];
+    skippedClaimed: string[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+/** One entry the replace preview will rewrite, enriched with its display title and permalink from the
+ *  content manifest (the planner's PlannedEntry carries neither). The screen lists these as the
+ *  confirm dialog's where-touched preview, and the apply re-derives its own plan rather than trusting
+ *  this. Admin-internal: exported from content-routes for the bundled Media Library component, not
+ *  added to the package's sveltekit subpath, so it carries no reference page. */
+export interface MediaReplacePreviewEntry {
+    /** The concept id, e.g. "posts". */
+    concept: string;
+    /** The entry id (its filename stem). */
+    id: string;
+    /** The entry's display title, from the content manifest. */
+    title: string;
+    /** The entry's public permalink, from the content manifest. */
+    permalink?: string;
+    /** The per-reference diff for this entry: one placement per repointed `media:` token. */
+    placements: RepointPlacement[];
+}
+/** The replace preview plan: the affected main entries (enriched), the distinct affected count, and
+ *  the report-only cross-branch delta (open cairn/* branches that reference the same bytes; an apply
+ *  rewrites main only). Display-only: the apply re-derives a fresh plan and never trusts this. */
+export interface MediaReplacePreviewPlan {
+    affectedCount: number;
+    entries: MediaReplacePreviewEntry[];
+    branchDelta: BranchRef[];
+}
+/** One entry the alt-propagation preview reports, enriched with its display title and permalink from
+ *  the content manifest. Its placements carry every reference of the asset on this entry, each tagged
+ *  with the bucket it falls in (a will-fill, a customized alt left as-is, or a decorative hero), so
+ *  the screen can show what would change. Admin-internal: exported from content-routes for the bundled
+ *  Media Library component, not added to the package's sveltekit subpath, so it carries no reference
+ *  page. */
+export interface MediaAltPreviewEntry {
+    /** The concept id, e.g. "posts". */
+    concept: string;
+    /** The entry id (its filename stem). */
+    id: string;
+    /** The entry's display title, from the content manifest. */
+    title: string;
+    /** The entry's public permalink, from the content manifest. */
+    permalink?: string;
+    /** The per-reference diff for this entry: one placement per reference of the asset. */
+    placements: AltPlacement[];
+}
+/** The alt-propagation preview plan: every entry that references the asset (enriched), the report-only
+ *  cross-branch delta, and the bucket counts aggregated across every placement. Display-only: the
+ *  apply re-derives a fresh plan and never trusts this. The preview reports an entry even when its
+ *  only placements are reported-but-unchanged (a kept custom alt, a decorative hero), so the screen
+ *  can show every bucket; the apply commits only the entries it actually changes. */
+export interface MediaAltPreviewPlan {
+    entries: MediaAltPreviewEntry[];
+    branchDelta: BranchRef[];
+    /** The placement counts by bucket, summed across all entries. */
+    counts: {
+        willFill: number;
+        customized: number;
+        decorativeSkipped: number;
+    };
+}
 /** What a route's single `form` export presents to a view component: whichever content action
  *  last failed, merged with every field optional. `error` is always set on a failure; the richer
  *  keys identify which guard refused. The media refusals ride here too, so the Media Library's one
- *  `form` prop carries a `?/mediaDelete` or `?/mediaUpdate` refusal without a second type. */
-export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure>;
+ *  `form` prop carries a `?/mediaDelete`, `?/mediaUpdate`, `?/mediaReplace`, or `?/mediaAltPropagate`
+ *  refusal without a second type. */
+export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure & MediaBulkFailure>;
 /** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
  *  optimistic client state and commits with the entry at Save (the upload itself commits nothing).
  *  `reused` is true when identical bytes were already stored, so the second upload did no second put;
@@ -225,6 +332,13 @@ export declare function createContentRoutes(runtime: CairnRuntime, deps?: Conten
     renameAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
     uploadAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | UploadResult>;
     mediaDeleteAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
+    mediaBulkDelete: (event: ContentEvent) => Promise<ReturnType<typeof fail> | MediaBulkDeleteResult>;
+    mediaOrphanScan: (event: ContentEvent) => Promise<ReturnType<typeof fail> | OrphanScan>;
+    mediaPurgeOrphans: (event: ContentEvent) => Promise<ReturnType<typeof fail> | MediaOrphanPurgeResult>;
     mediaUpdateAction: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
+    mediaReplacePreview: (event: ContentEvent) => Promise<ReturnType<typeof fail> | MediaReplacePreviewPlan>;
+    mediaReplaceApply: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
+    mediaAltPreview: (event: ContentEvent) => Promise<ReturnType<typeof fail> | MediaAltPreviewPlan>;
+    mediaAltApply: (event: ContentEvent) => Promise<ReturnType<typeof fail> | never>;
     mintToken: (env: GithubKeyEnv) => string | Promise<string>;
 };