@takazudo/zudo-doc 3.3.0 → 4.0.0

package/dist/theme-cli/config-rewriter.js

@@ -0,0 +1,141 @@
+import {
+  ConfigSyntaxError,
+  findMatchingBrace,
+  findZudoDocCallParens,
+  isPlainStringLiteralSpan,
+  skipWhitespaceAndComments,
+  splitTopLevelMembers
+} from "./config-scanner.js";
+function manualHint(slug) {
+  return `Add the field manually inside your zudoDoc({ ... }) call: themePack: ${JSON.stringify(slug)}`;
+}
+function refuse(reason, slug) {
+  return { ok: false, reason: `${reason} ${manualHint(slug)}` };
+}
+function detectIndent(source, members) {
+  const ref = members[0];
+  const refPos = ref ? ref.keyStart ?? ref.memberStart : null;
+  if (refPos !== null && refPos !== void 0) {
+    const newlineIdx = source.lastIndexOf("\n", refPos);
+    const lineStart = newlineIdx === -1 ? 0 : newlineIdx + 1;
+    const line = source.slice(lineStart, refPos);
+    if (/^[ \t]*$/.test(line) && line.length > 0) return line;
+  }
+  return "  ";
+}
+function applyThemePackToConfigSource(source, slug) {
+  let calls;
+  try {
+    calls = findZudoDocCallParens(source);
+  } catch (err) {
+    return refuse(
+      `could not parse zfb.config.ts (${err.message}).`,
+      slug
+    );
+  }
+  if (calls.length === 0) {
+    return refuse(
+      "no zudoDoc(...) call found in zfb.config.ts. This CLI only rewrites the canonical generated shape: export default defineConfig(zudoDoc({ ... })).",
+      slug
+    );
+  }
+  if (calls.length > 1) {
+    return refuse(
+      `found ${calls.length} zudoDoc(...) call sites in zfb.config.ts \u2014 cannot safely determine which one to rewrite.`,
+      slug
+    );
+  }
+  const openParenIdx = calls[0];
+  let braceOpenIdx;
+  let braceCloseIdx;
+  let afterBrace;
+  try {
+    braceOpenIdx = skipWhitespaceAndComments(source, openParenIdx + 1);
+    if (source[braceOpenIdx] !== "{") {
+      return refuse(
+        "zudoDoc(...) is not called with a plain object literal (found a computed or non-literal argument instead of zudoDoc({ ... })). This CLI only rewrites the canonical generated shape.",
+        slug
+      );
+    }
+    braceCloseIdx = findMatchingBrace(source, braceOpenIdx);
+    afterBrace = skipWhitespaceAndComments(source, braceCloseIdx + 1);
+  } catch (err) {
+    return refuse(
+      `could not parse zfb.config.ts (${err.message}).`,
+      slug
+    );
+  }
+  const afterOptionalComma = source[afterBrace] === "," ? skipWhitespaceAndComments(source, afterBrace + 1) : afterBrace;
+  if (source[afterOptionalComma] !== ")") {
+    return refuse(
+      "zudoDoc(...) is called with more than one argument \u2014 not the canonical single-object-literal shape.",
+      slug
+    );
+  }
+  let members;
+  try {
+    members = splitTopLevelMembers(source, braceOpenIdx + 1, braceCloseIdx);
+  } catch (err) {
+    return refuse(
+      `could not parse zfb.config.ts (${err.message}).`,
+      slug
+    );
+  }
+  const spread = members.find((m) => m.isSpread);
+  if (spread) {
+    return refuse(
+      "zudoDoc({ ...spread }) uses a spread argument \u2014 not the canonical generated shape. This CLI only rewrites a literal, hand-editable field list.",
+      slug
+    );
+  }
+  const newValueLiteral = JSON.stringify(slug);
+  const themePackMembers = members.filter((m) => m.key === "themePack");
+  if (themePackMembers.length > 1) {
+    return refuse(
+      'zfb.config.ts declares "themePack" more than once inside zudoDoc({ ... }). This CLI only rewrites a single canonical field; remove the duplicate and re-run.',
+      slug
+    );
+  }
+  const themePackMember = themePackMembers[0];
+  if (themePackMember) {
+    if (themePackMember.valueStart === null || themePackMember.valueEnd === null) {
+      return refuse(
+        'the existing "themePack" field in zfb.config.ts is not a simple `key: value` property this CLI understands.',
+        slug
+      );
+    }
+    if (!isPlainStringLiteralSpan(source, themePackMember.valueStart, themePackMember.valueEnd)) {
+      return refuse(
+        `the existing "themePack" field's value is not a plain string literal \u2014 cannot safely rewrite it without risking corruption.`,
+        slug
+      );
+    }
+    const newSource2 = source.slice(0, themePackMember.valueStart) + newValueLiteral + source.slice(themePackMember.valueEnd);
+    return { ok: true, source: newSource2, changed: newSource2 !== source, mode: "replaced" };
+  }
+  const colorModeMember = members.find((m) => m.key === "colorMode");
+  const colorSchemeMember = members.find((m) => m.key === "colorScheme");
+  const anchor = colorModeMember ?? colorSchemeMember ?? null;
+  const indent = detectIndent(source, members);
+  if (anchor) {
+    const insertAt2 = anchor.commaIndex !== null ? anchor.commaIndex + 1 : anchor.memberEnd;
+    const prefix = anchor.commaIndex !== null ? "" : ",";
+    const insertText2 = `${prefix}
+${indent}themePack: ${newValueLiteral},`;
+    const newSource2 = source.slice(0, insertAt2) + insertText2 + source.slice(insertAt2);
+    return {
+      ok: true,
+      source: newSource2,
+      changed: true,
+      mode: colorModeMember ? "inserted-after-color-mode" : "inserted-after-color-scheme"
+    };
+  }
+  const insertAt = braceOpenIdx + 1;
+  const insertText = `
+${indent}themePack: ${newValueLiteral},`;
+  const newSource = source.slice(0, insertAt) + insertText + source.slice(insertAt);
+  return { ok: true, source: newSource, changed: true, mode: "inserted-first" };
+}
+export {
+  applyThemePackToConfigSource
+};

package/dist/theme-cli/config-scanner.d.ts

@@ -0,0 +1,63 @@
+/** Thrown when the scanner hits config-file syntax it cannot safely reason
+ *  about. Callers MUST catch this and refuse cleanly (never proceed with a
+ *  partial/guessed rewrite). */
+export declare class ConfigSyntaxError extends Error {
+    constructor(message: string);
+}
+/** Skip a single/double-quoted string literal starting at `i`. Throws on an
+ *  unterminated string (including one broken by a literal, unescaped
+ *  newline — invalid in JS/TS for these quote kinds). */
+export declare function skipStringLiteral(source: string, i: number): number;
+/** Skip whitespace and comments starting at `i`, stopping at the first
+ *  "real" character (or `source.length`). */
+export declare function skipWhitespaceAndComments(source: string, i: number): number;
+/**
+ * Find every top-level `zudoDoc(` call site (outside strings/comments),
+ * returning the index of each call's opening `(`. An identifier match
+ * requires an exact `zudoDoc` token (not a substring of a longer
+ * identifier) immediately followed — modulo whitespace/comments — by `(`.
+ */
+export declare function findZudoDocCallParens(source: string): number[];
+/**
+ * Find the index of the `}` matching the `{` at `openIndex`, skipping
+ * strings/comments/template literals so their content can never be mistaken
+ * for structure. Throws `ConfigSyntaxError` if unterminated.
+ */
+export declare function findMatchingBrace(source: string, openIndex: number): number;
+/** One top-level member of an object literal body (a `key: value` property
+ *  or a `...spread` element). `key`/`valueStart`/`valueEnd` are `null` when
+ *  the member's shape is not a simple `key: value` this scanner recognizes
+ *  (e.g. a computed key, shorthand property) — such members are safe to
+ *  leave untouched but cannot be used as a rewrite target or anchor. */
+export interface TopLevelMember {
+    /** Start of this member's raw span (right after the previous comma, or
+     *  the object body's start). */
+    memberStart: number;
+    /** End of this member's raw span, trimmed of trailing whitespace (right
+     *  before its separating comma, or the object body's end). */
+    memberEnd: number;
+    /** Index of the comma separating this member from the next, or `null` if
+     *  this is the last member and has no trailing comma. */
+    commaIndex: number | null;
+    isSpread: boolean;
+    key: string | null;
+    keyStart: number | null;
+    keyEnd: number | null;
+    colonIndex: number | null;
+    /** Trimmed start/end of the value expression (after the colon). */
+    valueStart: number | null;
+    valueEnd: number | null;
+}
+/**
+ * Split an object literal's body (the span strictly between its `{`/`}`)
+ * into top-level members — commas nested inside arrays/objects/calls do not
+ * split. Throws `ConfigSyntaxError` on unbalanced brackets or unsupported
+ * syntax within the body.
+ */
+export declare function splitTopLevelMembers(source: string, bodyStart: number, bodyEnd: number): TopLevelMember[];
+/** True iff `source[start..end)` is EXACTLY one single/double-quoted string
+ *  literal (no surrounding characters). Used to confirm a field's existing
+ *  value is safe to replace wholesale. */
+export declare function isPlainStringLiteralSpan(source: string, start: number, end: number): boolean;
+/** Unquote a `"..."`/`'...'` string literal span into its raw string value. */
+export declare function unquoteStringLiteralSpan(source: string, start: number, end: number): string;

package/dist/theme-cli/config-scanner.js

@@ -0,0 +1,288 @@
+class ConfigSyntaxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigSyntaxError";
+  }
+}
+const IDENT_START_RE = /[A-Za-z_$]/;
+const IDENT_PART_RE = /[A-Za-z0-9_$]/;
+function isWhitespace(ch) {
+  return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+}
+function skipLineComment(source, i) {
+  let j = i + 2;
+  while (j < source.length && source[j] !== "\n") j++;
+  return j;
+}
+function skipBlockComment(source, i) {
+  const end = source.indexOf("*/", i + 2);
+  if (end === -1) {
+    throw new ConfigSyntaxError("unterminated block comment (/* ... */) in zfb.config.ts");
+  }
+  return end + 2;
+}
+function skipStringLiteral(source, i) {
+  const quote = source[i];
+  let j = i + 1;
+  while (j < source.length) {
+    const c = source[j];
+    if (c === "\\") {
+      j += 2;
+      continue;
+    }
+    if (c === quote) return j + 1;
+    if (c === "\n") break;
+    j++;
+  }
+  throw new ConfigSyntaxError(`unterminated string literal (${quote}...) in zfb.config.ts`);
+}
+function skipSimpleTemplateLiteral(source, i) {
+  let j = i + 1;
+  while (j < source.length) {
+    const c = source[j];
+    if (c === "\\") {
+      j += 2;
+      continue;
+    }
+    if (c === "`") return j + 1;
+    if (c === "$" && source[j + 1] === "{") {
+      throw new ConfigSyntaxError(
+        "template literal interpolation (`${...}`) in zfb.config.ts is not supported by the theme CLI's config parser"
+      );
+    }
+    j++;
+  }
+  throw new ConfigSyntaxError("unterminated template literal (`...`) in zfb.config.ts");
+}
+function trySkipToken(source, i) {
+  const c = source[i];
+  const c2 = source[i + 1];
+  if (c === "/" && c2 === "/") return skipLineComment(source, i);
+  if (c === "/" && c2 === "*") return skipBlockComment(source, i);
+  if (c === '"' || c === "'") return skipStringLiteral(source, i);
+  if (c === "`") return skipSimpleTemplateLiteral(source, i);
+  return null;
+}
+function skipWhitespaceAndComments(source, i) {
+  let pos = i;
+  while (pos < source.length) {
+    const c = source[pos];
+    if (isWhitespace(c)) {
+      pos++;
+      continue;
+    }
+    if (c === "/" && source[pos + 1] === "/") {
+      pos = skipLineComment(source, pos);
+      continue;
+    }
+    if (c === "/" && source[pos + 1] === "*") {
+      pos = skipBlockComment(source, pos);
+      continue;
+    }
+    break;
+  }
+  return pos;
+}
+function hasSignificantContent(source, start, end) {
+  return skipWhitespaceAndComments(source, start) < end;
+}
+function findZudoDocCallParens(source) {
+  const result = [];
+  let i = 0;
+  while (i < source.length) {
+    const skip = trySkipToken(source, i);
+    if (skip !== null) {
+      i = skip;
+      continue;
+    }
+    const c = source[i];
+    if (IDENT_START_RE.test(c)) {
+      let j = i + 1;
+      while (j < source.length && IDENT_PART_RE.test(source[j])) j++;
+      if (source.slice(i, j) === "zudoDoc") {
+        const parenIdx = skipWhitespaceAndComments(source, j);
+        if (source[parenIdx] === "(") result.push(parenIdx);
+      }
+      i = j;
+      continue;
+    }
+    i++;
+  }
+  return result;
+}
+function findMatchingBrace(source, openIndex) {
+  if (source[openIndex] !== "{") {
+    throw new ConfigSyntaxError("internal error: findMatchingBrace called at a non-'{' position");
+  }
+  let depth = 1;
+  let i = openIndex + 1;
+  while (i < source.length) {
+    const skip = trySkipToken(source, i);
+    if (skip !== null) {
+      i = skip;
+      continue;
+    }
+    const c = source[i];
+    if (c === "{") {
+      depth++;
+    } else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  throw new ConfigSyntaxError(
+    'unterminated object literal \u2014 missing closing "}" for the zudoDoc({...}) call'
+  );
+}
+function unquoteSimple(literal) {
+  if (literal.length < 2) return literal;
+  const quote = literal[0];
+  if (quote !== '"' && quote !== "'") return literal;
+  const inner = literal.slice(1, -1);
+  let out = "";
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (c === "\\") {
+      const next = inner[i + 1];
+      switch (next) {
+        case "n":
+          out += "\n";
+          break;
+        case "t":
+          out += "	";
+          break;
+        case "r":
+          out += "\r";
+          break;
+        default:
+          out += next ?? "";
+      }
+      i++;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+function parseMember(source, rawStart, rawEnd, commaIndex) {
+  const base = {
+    memberStart: rawStart,
+    commaIndex,
+    isSpread: false,
+    key: null,
+    keyStart: null,
+    keyEnd: null,
+    colonIndex: null,
+    valueStart: null,
+    valueEnd: null
+  };
+  let trimmedEnd = rawEnd;
+  while (trimmedEnd > rawStart && isWhitespace(source[trimmedEnd - 1])) trimmedEnd--;
+  const i0 = skipWhitespaceAndComments(source, rawStart);
+  if (i0 >= trimmedEnd) {
+    return { ...base, memberEnd: trimmedEnd };
+  }
+  if (source.slice(i0, i0 + 3) === "...") {
+    return { ...base, memberEnd: trimmedEnd, isSpread: true };
+  }
+  const c = source[i0];
+  let key = null;
+  let keyStart = null;
+  let keyEnd = null;
+  let i = i0;
+  if (c === '"' || c === "'") {
+    keyStart = i;
+    keyEnd = skipStringLiteral(source, i);
+    key = unquoteSimple(source.slice(keyStart, keyEnd));
+    i = keyEnd;
+  } else if (IDENT_START_RE.test(c)) {
+    keyStart = i;
+    let j = i + 1;
+    while (j < trimmedEnd && IDENT_PART_RE.test(source[j])) j++;
+    keyEnd = j;
+    key = source.slice(keyStart, keyEnd);
+    i = j;
+  } else {
+    return { ...base, memberEnd: trimmedEnd };
+  }
+  const afterKey = skipWhitespaceAndComments(source, i);
+  if (source[afterKey] !== ":") {
+    return { ...base, memberEnd: trimmedEnd, key, keyStart, keyEnd };
+  }
+  const colonIndex = afterKey;
+  const valueStart = skipWhitespaceAndComments(source, colonIndex + 1);
+  return {
+    ...base,
+    memberEnd: trimmedEnd,
+    key,
+    keyStart,
+    keyEnd,
+    colonIndex,
+    valueStart,
+    valueEnd: trimmedEnd
+  };
+}
+function splitTopLevelMembers(source, bodyStart, bodyEnd) {
+  const members = [];
+  let memberStart = bodyStart;
+  let depth = 0;
+  let i = bodyStart;
+  while (i < bodyEnd) {
+    const skip = trySkipToken(source, i);
+    if (skip !== null) {
+      i = Math.min(skip, bodyEnd);
+      continue;
+    }
+    const c = source[i];
+    if (c === "{" || c === "[" || c === "(") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (c === "}" || c === "]" || c === ")") {
+      depth--;
+      if (depth < 0) {
+        throw new ConfigSyntaxError(
+          "unbalanced brackets while scanning the zudoDoc({...}) object body"
+        );
+      }
+      i++;
+      continue;
+    }
+    if (c === "," && depth === 0) {
+      members.push(parseMember(source, memberStart, i, i));
+      i++;
+      memberStart = i;
+      continue;
+    }
+    i++;
+  }
+  if (hasSignificantContent(source, memberStart, bodyEnd)) {
+    members.push(parseMember(source, memberStart, bodyEnd, null));
+  }
+  return members;
+}
+function isPlainStringLiteralSpan(source, start, end) {
+  if (start >= end) return false;
+  const quote = source[start];
+  if (quote !== '"' && quote !== "'") return false;
+  try {
+    return skipStringLiteral(source, start) === end;
+  } catch {
+    return false;
+  }
+}
+function unquoteStringLiteralSpan(source, start, end) {
+  return unquoteSimple(source.slice(start, end));
+}
+export {
+  ConfigSyntaxError,
+  findMatchingBrace,
+  findZudoDocCallParens,
+  isPlainStringLiteralSpan,
+  skipStringLiteral,
+  skipWhitespaceAndComments,
+  splitTopLevelMembers,
+  unquoteStringLiteralSpan
+};

package/dist/theme-cli/index.d.ts

@@ -0,0 +1,7 @@
+export { listThemePacks, formatThemeList, type ThemeListRow, type ThemeListResult, type ListThemePacksOptions, } from "./list.js";
+export { applyThemePack, type ApplyThemePackOptions, type ApplyThemePackResult } from "./apply.js";
+export { loadInstalledThemePackCatalog, type LoadInstalledThemePackCatalogOptions, type ThemePackRegistry, type ThemePackRegistryEntry, } from "./registry.js";
+export { detectActiveThemePack, resolveZfbConfigPath, ZFB_CONFIG_FILENAME, type DetectActiveThemePackResult, } from "./config-io.js";
+export { applyThemePackToConfigSource, type ApplyThemePackToSourceOk, type ApplyThemePackToSourceRefusal, type ApplyThemePackToSourceResult, } from "./config-rewriter.js";
+export { readThemePackProvenance, writeThemePackProvenance, ZUDO_DOC_JSON_FILENAME, THEME_PACK_PROVENANCE_SCHEMA_VERSION, type ThemePackProvenance, } from "./provenance.js";
+export { ConfigSyntaxError } from "./config-scanner.js";

package/dist/theme-cli/index.js

@@ -0,0 +1,38 @@
+import {
+  listThemePacks,
+  formatThemeList
+} from "./list.js";
+import { applyThemePack } from "./apply.js";
+import {
+  loadInstalledThemePackCatalog
+} from "./registry.js";
+import {
+  detectActiveThemePack,
+  resolveZfbConfigPath,
+  ZFB_CONFIG_FILENAME
+} from "./config-io.js";
+import {
+  applyThemePackToConfigSource
+} from "./config-rewriter.js";
+import {
+  readThemePackProvenance,
+  writeThemePackProvenance,
+  ZUDO_DOC_JSON_FILENAME,
+  THEME_PACK_PROVENANCE_SCHEMA_VERSION
+} from "./provenance.js";
+import { ConfigSyntaxError } from "./config-scanner.js";
+export {
+  ConfigSyntaxError,
+  THEME_PACK_PROVENANCE_SCHEMA_VERSION,
+  ZFB_CONFIG_FILENAME,
+  ZUDO_DOC_JSON_FILENAME,
+  applyThemePack,
+  applyThemePackToConfigSource,
+  detectActiveThemePack,
+  formatThemeList,
+  listThemePacks,
+  loadInstalledThemePackCatalog,
+  readThemePackProvenance,
+  resolveZfbConfigPath,
+  writeThemePackProvenance
+};

package/dist/theme-cli/list.d.ts

@@ -0,0 +1,27 @@
+import { type LoadInstalledThemePackCatalogOptions } from "./registry.js";
+export interface ThemeListRow {
+    slug: string;
+    name: string;
+    mode: "light" | "dark";
+    version: string;
+    description: string;
+    active: boolean;
+}
+export interface ThemeListResult {
+    rows: ThemeListRow[];
+    activeSlug: string;
+    /** `false` when the active slug is a fallback (zfb.config.ts missing or
+     *  not confidently parseable) rather than a confirmed reading. */
+    activeDetected: boolean;
+}
+export interface ListThemePacksOptions extends LoadInstalledThemePackCatalogOptions {
+    cwd?: string;
+}
+/** Resolve the installed catalog + the project's active pack slug. Pure
+ *  data — see `formatThemeList` for the printable rendering. */
+export declare function listThemePacks(options?: ListThemePacksOptions): Promise<ThemeListResult>;
+/** Render a `ListThemePacksOptions` result as a human-readable table for
+ *  the terminal. Kept separate from `listThemePacks` so tests can assert on
+ *  structured data without scraping ANSI-colored strings, and separately on
+ *  this formatter's plain-text content. */
+export declare function formatThemeList(result: ThemeListResult): string;

package/dist/theme-cli/list.js

@@ -0,0 +1,64 @@
+import pc from "picocolors";
+import { detectActiveThemePack } from "./config-io.js";
+import {
+  loadInstalledThemePackCatalog
+} from "./registry.js";
+async function listThemePacks(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const catalog = loadInstalledThemePackCatalog(options);
+  const { slug: activeSlug, detected: activeDetected } = await detectActiveThemePack(cwd);
+  const rows = catalog.map((entry) => ({
+    slug: entry.slug,
+    name: entry.meta.name,
+    mode: entry.meta.mode,
+    version: entry.meta.version,
+    description: entry.meta.description,
+    active: entry.slug === activeSlug
+  }));
+  return { rows, activeSlug, activeDetected };
+}
+function padEnd(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function formatThemeList(result) {
+  const { rows, activeSlug, activeDetected } = result;
+  if (rows.length === 0) {
+    return pc.yellow("No theme packs found in the installed @takazudo/zudo-doc package.");
+  }
+  const slugWidth = Math.max(4, ...rows.map((r) => r.slug.length));
+  const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
+  const modeWidth = Math.max(4, ...rows.map((r) => r.mode.length));
+  const versionWidth = Math.max(7, ...rows.map((r) => r.version.length));
+  const lines = [];
+  lines.push(pc.bold(`Installed theme packs (${rows.length}):`));
+  lines.push("");
+  lines.push(
+    "  " + pc.dim(
+      `${padEnd("SLUG", slugWidth)}  ${padEnd("NAME", nameWidth)}  ${padEnd("MODE", modeWidth)}  ${padEnd("VERSION", versionWidth)}  DESCRIPTION`
+    )
+  );
+  for (const row of rows) {
+    const marker = row.active ? pc.green("*") : " ";
+    const activeSuffix = row.active ? pc.green("  (active)") : "";
+    lines.push(
+      `${marker} ${padEnd(row.slug, slugWidth)}  ${padEnd(row.name, nameWidth)}  ${padEnd(row.mode, modeWidth)}  ${padEnd(row.version, versionWidth)}  ${row.description}${activeSuffix}`
+    );
+  }
+  lines.push("");
+  if (activeDetected) {
+    lines.push(`Active theme pack: ${pc.bold(activeSlug)}`);
+  } else {
+    lines.push(
+      pc.dim(
+        `Active theme pack: ${activeSlug} (default \u2014 no zfb.config.ts "themePack" field found or readable)`
+      )
+    );
+  }
+  lines.push("");
+  lines.push(pc.dim("Run `zudo-doc theme apply <slug>` to switch."));
+  return lines.join("\n");
+}
+export {
+  formatThemeList,
+  listThemePacks
+};

package/dist/theme-cli/provenance.d.ts

@@ -0,0 +1,17 @@
+export declare const ZUDO_DOC_JSON_FILENAME = ".zudo-doc.json";
+export declare const THEME_PACK_PROVENANCE_SCHEMA_VERSION: 1;
+export interface ThemePackProvenance {
+    schemaVersion: typeof THEME_PACK_PROVENANCE_SCHEMA_VERSION;
+    slug: string;
+    packVersion: string;
+    /** ISO 8601 timestamp of the apply that produced this record. */
+    appliedAt: string;
+}
+/** Merge-write the `themePack` provenance key, preserving every other
+ *  top-level key already in `.zudo-doc.json` (notably `ejected` /
+ *  `packageVersion`, written by `zudo-doc eject`). Creates the file if
+ *  absent. */
+export declare function writeThemePackProvenance(cwd: string, entry: ThemePackProvenance): Promise<void>;
+/** Read back the current `themePack` provenance entry, or `null` if absent
+ *  / the file doesn't exist / the key is malformed. */
+export declare function readThemePackProvenance(cwd: string): Promise<ThemePackProvenance | null>;

package/dist/theme-cli/provenance.js

@@ -0,0 +1,35 @@
+import fs from "fs-extra";
+import path from "node:path";
+const ZUDO_DOC_JSON_FILENAME = ".zudo-doc.json";
+const THEME_PACK_PROVENANCE_SCHEMA_VERSION = 1;
+function provenancePath(cwd) {
+  return path.join(cwd, ZUDO_DOC_JSON_FILENAME);
+}
+async function readExisting(cwd) {
+  const filePath = provenancePath(cwd);
+  if (!await fs.pathExists(filePath)) return {};
+  try {
+    return await fs.readJson(filePath);
+  } catch {
+    return {};
+  }
+}
+async function writeThemePackProvenance(cwd, entry) {
+  const existing = await readExisting(cwd);
+  existing.themePack = entry;
+  await fs.writeJson(provenancePath(cwd), existing, { spaces: 2 });
+}
+async function readThemePackProvenance(cwd) {
+  const existing = await readExisting(cwd);
+  const themePack = existing.themePack;
+  if (themePack && typeof themePack === "object") {
+    return themePack;
+  }
+  return null;
+}
+export {
+  THEME_PACK_PROVENANCE_SCHEMA_VERSION,
+  ZUDO_DOC_JSON_FILENAME,
+  readThemePackProvenance,
+  writeThemePackProvenance
+};