@drawnagency/primitives 0.1.113 → 0.1.115

package/src/lib/loader.ts

@@ -3,52 +3,38 @@ import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-c
 import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
 import { upgradeLegacySection } from "./migrate-sections-transform";
-import { NavEntrySchema, type NavEntry } from "../schemas/nav";
+import type { NavEntry } from "../schemas/nav";
+import type { TagEntry } from "../schemas/tags";
+import type { SidecarRead } from "./sidecars";
 
 export interface LoadedSection {
   section: Section;
   meta: SectionMeta;
+  /** Set only on render-time copies a Reference pulled in (resolveReference):
+   *  the id of that Reference. Never loaded or persisted. */
+  referencedBy?: string;
 }
 
 export interface SiteContent {
   sections: LoadedSection[];
   index: SiteIndex;
-  /** True when nav.json was present but held entries this package version could
-   *  not represent (unknown kinds, invalid shapes) — the returned nav is missing
-   *  them. Writers must treat a degraded nav as read-only: wholesale-replacing
-   *  nav.json from a degraded read permanently destroys the entries this
-   *  version dropped. */
+  /** A Degraded read of nav.json (see SidecarRead): the returned nav is missing
+   *  entries, so writers treat it as read-only — wholesale-replacing nav.json
+   *  from it permanently destroys the entries this version dropped. */
   navDegraded: boolean;
+  /** Same contract as navDegraded, for tags.json: a degraded read is
+   *  read-only for tags. */
+  tagsDegraded: boolean;
 }
 
 /**
- * Parse the nav.json sidecar defensively, entry by entry. A malformed sidecar
- * must degrade, never brick the site — nav.json is optional content, and the
- * whole point of the sidecar is that it tolerates writers that don't understand
- * it. Tolerance is PER ENTRY: one unknown entry kind (a newer package version's
- * addition, or an authoring typo) drops that entry alone, not every group on
- * the site. Any drop is reported as `degraded` so write paths can refuse to
- * persist the lossy tree back over the original.
+ * The Sidecars a load read, from the Sidecar module's readers. A Sidecar the
+ * load did not look for is omitted. Tags then stay unattached ("not loaded":
+ * writers leave tags.json alone, where an attached `[]` saved back would delete
+ * every tag). Nav is attached as `[]` either way — the editor has no nav gate
+ * yet to make "not loaded" safe for nav (exploration B).
  */
-function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolean } {
-  if (!navFile) return { entries: [], degraded: false };
-  const rawEntries = (navFile as { entries?: unknown }).entries;
-  if (!Array.isArray(rawEntries)) {
-    console.warn("Invalid nav.json, falling back to a flat navigation");
-    return { entries: [], degraded: true };
-  }
-  const entries: NavEntry[] = [];
-  let dropped = 0;
-  for (const raw of rawEntries) {
-    const result = NavEntrySchema.safeParse(raw);
-    if (result.success) entries.push(result.data);
-    else dropped++;
-  }
-  if (dropped > 0) {
-    console.warn(`nav.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; navigation is degraded`);
-  }
-  return { entries, degraded: dropped > 0 };
-}
+export type SidecarReads = { nav?: SidecarRead<NavEntry>; tags?: SidecarRead<TagEntry> };
 
 /**
  * Merge a validated index with raw section file contents.
@@ -58,7 +44,7 @@ function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolea
 export function mergeSiteContent(
   index: SiteIndex,
   sectionFiles: Record<string, unknown>,
-  navFile?: unknown,
+  sidecars: SidecarReads = {},
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
@@ -111,8 +97,13 @@ export function mergeSiteContent(
     }
   }
 
-  const nav = parseNavFile(navFile);
-  return { sections, index: { ...index, nav: nav.entries }, navDegraded: nav.degraded };
+  const { nav, tags } = sidecars;
+  return {
+    sections,
+    index: { ...index, nav: nav?.entries ?? [], ...(tags ? { tags: tags.entries } : {}) },
+    navDegraded: nav?.degraded ?? false,
+    tagsDegraded: tags?.degraded ?? false,
+  };
 }
 
 /**
@@ -123,7 +114,7 @@ export function mergeSiteContent(
 export function loadStaticSiteContent(
   index: SiteIndex,
   sectionGlob: Record<string, unknown>,
-  navFile?: unknown,
+  sidecars: SidecarReads = {},
 ): SiteContent {
   const sectionFiles: Record<string, unknown> = {};
   for (const [path, data] of Object.entries(sectionGlob)) {
@@ -131,56 +122,5 @@ export function loadStaticSiteContent(
     const id = filename.replace(".json", "");
     sectionFiles[id] = data;
   }
-  return mergeSiteContent(index, sectionFiles, navFile);
-}
-
-/**
- * Load site content from the filesystem.
- * For use in scripts and tests — Astro pages should use import.meta.glob instead.
- */
-export async function loadSiteContent(contentDir: string): Promise<SiteContent> {
-  const fs = await import("node:fs/promises");
-  const path = await import("node:path");
-
-  const indexPath = path.join(contentDir, "index.json");
-  const indexRaw = JSON.parse(await fs.readFile(indexPath, "utf-8"));
-  const index = IndexSchema.parse(indexRaw);
-
-  const sectionFiles: Record<string, unknown> = {};
-  for (const id of index.pages.flatMap((p: SiteIndex["pages"][number]) => p.order)) {
-    const sectionPath = path.join(contentDir, "sections", `${id}.json`);
-    sectionFiles[id] = JSON.parse(await fs.readFile(sectionPath, "utf-8"));
-  }
-
-  // nav.json is an optional sidecar — absent (every portal predating page
-  // groups) or unreadable must degrade to a flat nav, never fail the load.
-  //
-  // ABSENT and UNREADABLE are not the same answer, though: absent is the normal
-  // case and safe to overwrite, while a present-but-unparseable sidecar holds
-  // groups this load cannot see. Collapsing both to `undefined` reported
-  // navDegraded: false, so the next nav-touching save wholesale-wrote a flat
-  // nav.json over a file that was still hand-recoverable. Mirrors the
-  // GitHub-backed loader's navRaw/navFile split in @drawnagency/core.
-  let navRaw: string | undefined;
-  let readFailed = false;
-  try {
-    navRaw = await fs.readFile(path.join(contentDir, "nav.json"), "utf-8");
-  } catch (err) {
-    // Only a genuinely missing file is "absent". A permissions/IO error leaves
-    // the sidecar's contents unknown, which must not license overwriting it.
-    readFailed = (err as { code?: string })?.code !== "ENOENT";
-  }
-
-  let navFile: unknown;
-  let parseFailed = false;
-  if (navRaw !== undefined) {
-    try {
-      navFile = JSON.parse(navRaw);
-    } catch {
-      parseFailed = true;
-    }
-  }
-
-  const content = mergeSiteContent(index, sectionFiles, navFile);
-  return readFailed || parseFailed ? { ...content, navDegraded: true } : content;
+  return mergeSiteContent(index, sectionFiles, sidecars);
 }

package/src/lib/media-ops.ts

@@ -0,0 +1,112 @@
+import type { MediaItem, MediaManifest } from "../schemas/media";
+import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
+
+// Media intents (CONTEXT.md: Index op / Media intent): a change to the media
+// library stated as what to do, applied by the write path to its own fresh read
+// of the manifests. A writer that sent a whole manifest instead could only
+// send back what it had read — dropping another writer's images, or `folders`,
+// the moment its copy was stale. Intents leave everything they do not name as
+// the branch has it. Pure: the write path does the reads and the commit.
+
+export type MediaBlob = { path: string; base64: string };
+
+export type MediaOp =
+  /**
+   * A new image and its variant files, keyed by its id (the content hash).
+   * `alt` is the caller's alt text, if it sent one — the only alt applied when
+   * the image turns out to be in the library already (`entry.alt` is just the
+   * new entry's default).
+   */
+  | { op: "addImage"; entry: MediaItem; blobs: MediaBlob[]; alt?: string }
+  | { op: "setImageAlt"; imageId: string; alt: string }
+  | { op: "deleteImage"; imageId: string }
+  /**
+   * A document's manifest entry, with its bytes when they ride in the commit
+   * (git tier; bucket-tier bytes are uploaded beforehand). For an id already in
+   * the library — git-tier ids are the content hash, so the same bytes — only
+   * the filename is applied: its stored bytes and path stay. That is how a
+   * rename lands.
+   */
+  | { op: "putDocument"; documentId: string; entry: DocumentManifestEntry; blob?: MediaBlob };
+
+/**
+ * Per op, in order. `existed` means `addImage` found the image already in the
+ * library: its bytes are not committed again, and only a differing alt text is
+ * applied.
+ */
+export type MediaOpOutcome = "added" | "existed" | "updated" | "deleted";
+
+export type AppliedMediaOps = {
+  ok: true;
+  images: MediaManifest;
+  /** Null when no op touched documents, so the write leaves that file alone. */
+  documents: DocumentManifest | null;
+  uploads: { item: { id: string; folder: string }; blobs: MediaBlob[] }[];
+  /** Images whose variant folders the write deletes. */
+  deletions: { id: string; folder: string }[];
+  outcomes: MediaOpOutcome[];
+};
+
+export function applyMediaOps(
+  manifests: { images: MediaManifest; documents: DocumentManifest },
+  ops: MediaOp[],
+): AppliedMediaOps | { ok: false; code: "not_found"; error: string } {
+  const images: MediaManifest = { ...manifests.images, images: { ...manifests.images.images } };
+  let documents: DocumentManifest | null = null;
+  const uploads: AppliedMediaOps["uploads"] = [];
+  const deletions: AppliedMediaOps["deletions"] = [];
+  const outcomes: MediaOpOutcome[] = [];
+
+  // Keys are content hashes and normally equal the entry's id; find by id so a
+  // caller naming the id it was given always reaches the right entry.
+  const keyOf = (imageId: string) =>
+    imageId in images.images ? imageId : Object.keys(images.images).find((key) => images.images[key].id === imageId);
+  const notFound = (imageId: string) =>
+    ({ ok: false, code: "not_found", error: `No media with imageId "${imageId}" in the site's media library.` }) as const;
+
+  for (const op of ops) {
+    switch (op.op) {
+      case "addImage": {
+        const key = keyOf(op.entry.id);
+        if (key === undefined) {
+          images.images[op.entry.id] = op.entry;
+          uploads.push({ item: { id: op.entry.id, folder: op.entry.folder }, blobs: op.blobs });
+          outcomes.push("added");
+        } else {
+          if (op.alt !== undefined) images.images[key] = { ...images.images[key], alt: op.alt };
+          outcomes.push("existed");
+        }
+        break;
+      }
+      case "setImageAlt": {
+        const key = keyOf(op.imageId);
+        if (key === undefined) return notFound(op.imageId);
+        images.images[key] = { ...images.images[key], alt: op.alt };
+        outcomes.push("updated");
+        break;
+      }
+      case "deleteImage": {
+        const key = keyOf(op.imageId);
+        if (key === undefined) return notFound(op.imageId);
+        deletions.push({ id: key, folder: images.images[key].folder });
+        delete images.images[key];
+        outcomes.push("deleted");
+        break;
+      }
+      case "putDocument": {
+        documents ??= { ...manifests.documents };
+        const existing = documents[op.documentId];
+        if (existing) {
+          documents[op.documentId] = { ...existing, filename: op.entry.filename };
+          outcomes.push(existing.filename === op.entry.filename ? "existed" : "updated");
+        } else {
+          documents[op.documentId] = op.entry;
+          if (op.blob) uploads.push({ item: { id: op.documentId, folder: op.blob.path.split("/")[2] ?? "" }, blobs: [op.blob] });
+          outcomes.push("added");
+        }
+        break;
+      }
+    }
+  }
+  return { ok: true, images, documents, uploads, deletions, outcomes };
+}

package/src/lib/nav-tree.ts

@@ -1,5 +1,6 @@
 import type { NavEntry, NavGroupEntry } from "../schemas/nav";
 import type { Page, SiteIndex } from "../schemas/site-config";
+import { diagnosticsCollector, type SidecarDiagnostic } from "./sidecar-diagnostics";
 
 /**
  * Repair an authored nav against the current page set.
@@ -19,6 +20,15 @@ import type { Page, SiteIndex } from "../schemas/site-config";
  * prior state and defeat identity-based re-render checks.
  */
 export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
+  return reconcileNavReport(entries, pages).entries;
+}
+
+/** reconcileNav plus what the repair changed — what a validator reports. */
+export function reconcileNavReport(
+  entries: NavEntry[],
+  pages: Page[],
+): { entries: NavEntry[]; diagnostics: SidecarDiagnostic[] } {
+  const report = diagnosticsCollector();
   const entryList = Array.isArray(entries) ? entries : [];
   const pageList = Array.isArray(pages) ? pages : [];
 
@@ -33,7 +43,14 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
 
   for (const entry of entryList) {
     if (entry?.kind === "page") {
-      if (!validIds.has(entry.pageId) || placed.has(entry.pageId)) continue;
+      if (!validIds.has(entry.pageId)) {
+        report.add("dangling", entry.pageId);
+        continue;
+      }
+      if (placed.has(entry.pageId)) {
+        report.add("duplicate-member", entry.pageId);
+        continue;
+      }
       placed.add(entry.pageId);
       result.push({ ...entry });
       continue;
@@ -46,12 +63,23 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
     // and "total" would be a lie. Dropping it spills its members to the tail
     // append below: a group lost, never a page.
     if (typeof entry.id !== "string" || entry.id === "") continue;
-    if (seenGroupIds.has(entry.id)) continue;
+    if (seenGroupIds.has(entry.id)) {
+      report.add("duplicate-id", entry.id);
+      continue;
+    }
     seenGroupIds.add(entry.id);
 
     const claimed = Array.isArray(entry.pageIds) ? entry.pageIds : [];
     const pageIds = claimed.filter((id) => {
-      if (typeof id !== "string" || !validIds.has(id) || placed.has(id)) return false;
+      if (typeof id !== "string") return false;
+      if (!validIds.has(id)) {
+        report.add("dangling", id);
+        return false;
+      }
+      if (placed.has(id)) {
+        report.add("duplicate-member", id);
+        return false;
+      }
       placed.add(id);
       return true;
     });
@@ -70,10 +98,11 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
   for (const p of pageList) {
     if (!p?.id || placed.has(p.id)) continue;
     placed.add(p.id);
+    report.add("unlisted", p.id);
     result.push({ kind: "page", pageId: p.id });
   }
 
-  return result;
+  return { entries: result, diagnostics: report.list() };
 }
 
 /**
@@ -204,3 +233,74 @@ export function moveNavEntry(index: SiteIndex, from: NavLocation, to: NavLocatio
 
   return withNav(index, entries);
 }
+
+/**
+ * "Moved <label> to position N of M" for the aria-live reorder announcement,
+ * covering both `moveNavEntry` callers: drag (PagesModal/NavGroupRow) and the
+ * Move up/down buttons. `prevIndex` resolves WHO moved and its label (read
+ * before the move, since `from` is a position, not an id); `nextIndex` (the
+ * result of `moveNavEntry(prevIndex, from, to)`) is searched by id for where
+ * it actually landed — robust to `moveNavEntry`'s own clamping, so the caller
+ * never has to replicate that math. Returns null if `from` didn't resolve to
+ * a real row (defensive; ordinary callers always pass a live location).
+ */
+/** A top-level entry counts toward "N of M" iff it's a group (always visible)
+ *  or a page that isn't archived — mirrors the PagesModal Move up/down rows,
+ *  which skip archived pages entirely rather than render an inert slot. */
+function isLiveTopEntry(index: SiteIndex, entry: NavEntry): boolean {
+  if (entry.kind === "group") return true;
+  const page = index.pages.find((p) => p.id === entry.pageId);
+  return page?.status === "live";
+}
+
+export function describeNavMove(prevIndex: SiteIndex, nextIndex: SiteIndex, from: NavLocation): string | null {
+  const prevEntries = navEntries(prevIndex);
+  let label: string;
+  let pageId: string | null = null;
+  let groupId: string | null = null;
+
+  if (from.groupId === null) {
+    const entry = prevEntries[from.index];
+    if (!entry) return null;
+    if (entry.kind === "group") {
+      label = groupDisplayLabel(entry.label);
+      groupId = entry.id;
+    } else {
+      const page = prevIndex.pages.find((p) => p.id === entry.pageId);
+      if (!page) return null;
+      label = page.title || "Untitled";
+      pageId = page.id;
+    }
+  } else {
+    const group = prevEntries.find((e) => e.kind === "group" && e.id === from.groupId);
+    if (!group || group.kind !== "group") return null;
+    const id = group.pageIds[from.index];
+    if (!id) return null;
+    const page = prevIndex.pages.find((p) => p.id === id);
+    if (!page) return null;
+    label = page.title || "Untitled";
+    pageId = page.id;
+  }
+
+  const nextEntries = navEntries(nextIndex);
+  const liveTopEntries = nextEntries.filter((e) => isLiveTopEntry(nextIndex, e));
+
+  if (groupId !== null) {
+    const i = liveTopEntries.findIndex((e) => e.kind === "group" && e.id === groupId);
+    if (i === -1) return null;
+    return `Moved ${label} to position ${i + 1} of ${liveTopEntries.length}`;
+  }
+
+  if (pageId === null) return null;
+
+  const topIndex = liveTopEntries.findIndex((e) => e.kind === "page" && e.pageId === pageId);
+  if (topIndex !== -1) return `Moved ${label} to position ${topIndex + 1} of ${liveTopEntries.length}`;
+  for (const e of nextEntries) {
+    if (e.kind === "group") {
+      const liveMemberIds = e.pageIds.filter((id) => nextIndex.pages.find((p) => p.id === id)?.status === "live");
+      const gi = liveMemberIds.indexOf(pageId);
+      if (gi !== -1) return `Moved ${label} to position ${gi + 1} of ${liveMemberIds.length}`;
+    }
+  }
+  return null;
+}