@takazudo/zudo-doc 3.2.0 → 4.0.0

package/bin/tags-suggest-runner.ts

@@ -0,0 +1,429 @@
+#!/usr/bin/env tsx
+/**
+ * Package-owned tags:suggest runner — optional local-LLM tag suggester.
+ *
+ * Reads one or more doc files, asks a local Ollama instance for up to 3 tag
+ * ids from the project vocabulary, and either opens an interactive approval
+ * prompt (default) or appends suggestions to `.tag-suggestions.jsonl`
+ * (`--batch`, also used automatically when stdout is not a TTY).
+ *
+ * Entirely developer-opt-in. Never runs in CI; never wired into b4push.
+ */
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import matter from "gray-matter";
+
+import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
+import {
+  loadTagCliConfig,
+  takeTagCliConfigInput,
+} from "./tag-cli-config.ts";
+
+const DEFAULT_HOST = "http://localhost:11434";
+const DEFAULT_MODEL = "qwen2.5:7b";
+const BODY_CHAR_LIMIT = 1500;
+const REQUEST_TIMEOUT_MS = 60_000;
+const BATCH_FILE = ".tag-suggestions.jsonl";
+
+interface Args {
+  files: string[];
+  host: string;
+  model: string;
+  batch: boolean;
+  help: boolean;
+}
+
+interface ParsedArgs extends Args {
+  configInput: string | undefined;
+}
+
+interface Suggestion {
+  file: string;
+  current: string[];
+  suggested: string[];
+}
+
+function printHelp(): void {
+  process.stdout.write(`Usage: tags-suggest --config <path> [options] <file...>
+
+Ask a local Ollama LLM to suggest up to 3 tag ids from the project
+vocabulary for each doc file. Opt-in developer tool — never runs in CI.
+
+Options:
+  --host <url>   Ollama endpoint (default: ${DEFAULT_HOST})
+  --model <id>   Ollama model id (default: ${DEFAULT_MODEL})
+  --batch        Append suggestions to ${BATCH_FILE} instead of prompting.
+                 Auto-enabled when stdout is not a TTY.
+  --help         Show this help.
+
+Ollama setup:
+  1. Install from https://ollama.com/
+  2. Pull a model: \`ollama pull ${DEFAULT_MODEL}\`
+  3. Ensure the daemon is running at ${DEFAULT_HOST}
+
+Model trade-offs:
+  - \`qwen2.5:7b\` (default) — balanced quality/speed; ~5 GB download.
+  - \`llama3.1:8b\`          — similar size, stronger English reasoning.
+  - \`qwen2.5:3b\` / \`llama3.2:3b\` — smaller/faster, noisier output.
+  Pass \`--model\` to override.
+
+Exit codes:
+  0  success
+  1  usage error
+  2  Ollama unreachable or returned unusable output
+`);
+}
+
+function parseCliArgs(argv: string[]): ParsedArgs {
+  const configArgs = takeTagCliConfigInput(argv);
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: configArgs.argv,
+      allowPositionals: true,
+      options: {
+        host: { type: "string", default: DEFAULT_HOST },
+        model: { type: "string", default: DEFAULT_MODEL },
+        batch: { type: "boolean", default: false },
+        help: { type: "boolean", default: false },
+      },
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`tags:suggest: ${msg}\n`);
+    process.exit(1);
+  }
+  return {
+    configInput: configArgs.configInput,
+    files: parsed.positionals,
+    host: String(parsed.values.host ?? DEFAULT_HOST),
+    model: String(parsed.values.model ?? DEFAULT_MODEL),
+    batch: Boolean(parsed.values.batch),
+    help: Boolean(parsed.values.help),
+  };
+}
+
+function buildPrompt(
+  entries: TagVocabularyEntry[],
+  title: string,
+  body: string,
+): string {
+  const vocabLines = entries
+    .map((e) => {
+      const label = e.label ?? e.id;
+      const desc = e.description ?? "";
+      const group = e.group ? ` [${e.group}]` : "";
+      return `- ${e.id}${group} — ${label}: ${desc}`.trim();
+    })
+    .join("\n");
+  const snippet = body.slice(0, BODY_CHAR_LIMIT);
+  return `You are tagging a documentation page.
+
+Vocabulary (pick ONLY from these ids):
+${vocabLines}
+
+Document title: ${title}
+
+Document excerpt:
+"""
+${snippet}
+"""
+
+Return a JSON array of AT MOST 3 tag ids that best fit this page. The
+array must contain only strings that exactly match ids from the
+vocabulary above. Respond with the JSON array and nothing else.`;
+}
+
+interface OllamaGenerateResponse {
+  response?: string;
+  error?: string;
+}
+
+async function callOllama(
+  host: string,
+  model: string,
+  prompt: string,
+): Promise<string> {
+  const url = `${host.replace(/\/$/, "")}/api/generate`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        model,
+        prompt,
+        stream: false,
+        format: "json",
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    if ((err as Error)?.name === "AbortError") {
+      throw new OllamaError(
+        `Ollama request timed out after ${REQUEST_TIMEOUT_MS / 1000}s at ${host}. Is \`ollama serve\` running?`,
+      );
+    }
+    // Any other fetch rejection (ECONNREFUSED, UND_ERR_CONNECT_TIMEOUT,
+    // DNS failure, bad port, …) means we could not talk to Ollama. Collapse
+    // them into one actionable message — the full stack isn't useful to
+    // the doc author running this CLI.
+    throw new OllamaUnreachableError(host, model);
+  }
+  clearTimeout(timer);
+
+  if (!res.ok) {
+    let detail = "";
+    try {
+      const body = (await res.json()) as OllamaGenerateResponse;
+      if (body?.error) detail = ` — ${body.error}`;
+    } catch {
+      // ignore; keep status line only
+    }
+    if (res.status === 404) {
+      throw new OllamaError(
+        `Ollama responded 404 at ${host}. Pull the model first: \`ollama pull ${model}\`.${detail}`,
+      );
+    }
+    throw new OllamaError(
+      `Ollama responded HTTP ${res.status} at ${host}.${detail}`,
+    );
+  }
+
+  let json: OllamaGenerateResponse;
+  try {
+    json = (await res.json()) as OllamaGenerateResponse;
+  } catch {
+    throw new OllamaError(`Ollama returned non-JSON response at ${host}.`);
+  }
+  if (typeof json.response !== "string") {
+    throw new OllamaError(`Ollama response missing 'response' field.`);
+  }
+  return json.response;
+}
+
+class OllamaError extends Error {
+  readonly friendly = true;
+}
+class OllamaUnreachableError extends OllamaError {
+  constructor(host: string, model: string) {
+    super(
+      `Ollama not reachable at ${host}. Install from https://ollama.com/ and run \`ollama pull ${model}\`.`,
+    );
+  }
+}
+
+function parseSuggestions(
+  raw: string,
+  allowedIds: Set<string>,
+): string[] {
+  const trimmed = raw.trim();
+  // Accept either a bare JSON array or a JSON object that wraps one.
+  // Some models return `{"tags": [...]}` even when asked for an array.
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    // Last-ditch: try to extract the first JSON array substring.
+    const match = trimmed.match(/\[[\s\S]*\]/);
+    if (!match) {
+      throw new OllamaError(
+        `Model output was not valid JSON. Raw: ${trimmed.slice(0, 200)}`,
+      );
+    }
+    parsed = JSON.parse(match[0]);
+  }
+  let arr: unknown[];
+  if (Array.isArray(parsed)) {
+    arr = parsed;
+  } else if (
+    parsed &&
+    typeof parsed === "object" &&
+    Array.isArray((parsed as { tags?: unknown }).tags)
+  ) {
+    arr = (parsed as { tags: unknown[] }).tags;
+  } else {
+    throw new OllamaError(`Model output is not a JSON array.`);
+  }
+  const ids = arr
+    .filter((v): v is string => typeof v === "string")
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0 && allowedIds.has(v));
+  // Dedupe, cap at 3.
+  return Array.from(new Set(ids)).slice(0, 3);
+}
+
+function asStringArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.filter((x): x is string => typeof x === "string");
+}
+
+async function writeFrontmatterTags(
+  filePath: string,
+  parsed: matter.GrayMatterFile<string>,
+  nextTags: string[],
+): Promise<void> {
+  const data = { ...parsed.data, tags: nextTags };
+  const rebuilt = matter.stringify(parsed.content, data);
+  await writeFile(filePath, rebuilt, "utf-8");
+}
+
+async function appendBatch(
+  repoRoot: string,
+  entry: Suggestion,
+): Promise<void> {
+  const outPath = resolve(repoRoot, BATCH_FILE);
+  await appendFile(outPath, JSON.stringify(entry) + "\n", "utf-8");
+}
+
+class UsageError extends Error {}
+
+function resolveFiles(repoRoot: string, inputs: string[]): string[] {
+  const out: string[] = [];
+  for (const raw of inputs) {
+    const abs = isAbsolute(raw) ? raw : resolve(repoRoot, raw);
+    if (!existsSync(abs)) {
+      throw new UsageError(`file not found: ${raw}`);
+    }
+    out.push(abs);
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const args = parseCliArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const repoRoot = process.cwd();
+  const { config } = await loadTagCliConfig(args.configInput, repoRoot);
+
+  if (args.files.length === 0) {
+    process.stderr.write(
+      "tags:suggest: no input files. Pass one or more `.mdx` paths, or run with --help.\n",
+    );
+    process.exit(1);
+  }
+
+  const files = resolveFiles(repoRoot, args.files);
+  const vocab = [...config.vocabulary];
+  const allowedIds = new Set(vocab.map((e) => e.id));
+
+  const isTty = Boolean(process.stdout.isTTY);
+  const batchMode = args.batch || !isTty;
+
+  // Dynamic import so the script's `--help` and arg parsing work even if
+  // `@inquirer/prompts` is momentarily unavailable in an odd environment.
+  type CheckboxFn = <V extends string>(config: {
+    message: string;
+    choices: { name: string; value: V; checked?: boolean }[];
+    loop?: boolean;
+  }) => Promise<V[]>;
+  let checkbox: CheckboxFn | null = null;
+  if (!batchMode) {
+    const mod = (await import("@inquirer/prompts")) as {
+      checkbox: CheckboxFn;
+    };
+    checkbox = mod.checkbox;
+  }
+
+  for (const filePath of files) {
+    const rel = relative(repoRoot, filePath);
+    const source = await readFile(filePath, "utf-8");
+    const parsed = matter(source);
+    const title =
+      typeof parsed.data.title === "string" ? parsed.data.title : rel;
+    const current = asStringArray(parsed.data.tags);
+
+    let suggested: string[];
+    try {
+      const prompt = buildPrompt(vocab, title, parsed.content);
+      const raw = await callOllama(args.host, args.model, prompt);
+      suggested = parseSuggestions(raw, allowedIds);
+    } catch (err) {
+      if (err instanceof OllamaError) {
+        process.stderr.write(`tags:suggest: ${err.message}\n`);
+        process.exit(2);
+      }
+      throw err;
+    }
+
+    if (suggested.length === 0) {
+      process.stdout.write(`${rel}: no vocabulary-matching suggestions\n`);
+      continue;
+    }
+
+    if (batchMode) {
+      await appendBatch(repoRoot, {
+        file: rel,
+        current,
+        suggested,
+      });
+      process.stdout.write(
+        `${rel}: recorded ${suggested.length} suggestion(s) to ${BATCH_FILE}\n`,
+      );
+      continue;
+    }
+
+    // Interactive approval: pre-check suggestions, show current tags for context.
+    const combined = Array.from(new Set([...current, ...suggested]));
+    const choices = combined.map((id) => {
+      const inSuggestion = suggested.includes(id);
+      const inCurrent = current.includes(id);
+      const label =
+        inSuggestion && inCurrent
+          ? `${id} (current, also suggested)`
+          : inSuggestion
+            ? `${id} (suggested)`
+            : `${id} (current)`;
+      return {
+        name: label,
+        value: id,
+        checked: inSuggestion || inCurrent,
+      };
+    });
+    if (!checkbox) {
+      // Should not happen — we set it above when !batchMode.
+      throw new Error("interactive prompt loader missing");
+    }
+    const picked = await checkbox<string>({
+      message: `${rel} — pick tags to write:`,
+      choices,
+      loop: false,
+    });
+    const nextTags = picked.slice();
+    if (
+      nextTags.length === current.length &&
+      nextTags.every((t, i) => t === current[i])
+    ) {
+      process.stdout.write(`${rel}: unchanged\n`);
+      continue;
+    }
+    await writeFrontmatterTags(filePath, parsed, nextTags);
+    process.stdout.write(
+      `${rel}: wrote tags [${nextTags.join(", ")}]\n`,
+    );
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof OllamaError) {
+    process.stderr.write(`tags:suggest: ${err.message}\n`);
+    process.exit(2);
+  }
+  if (err instanceof UsageError) {
+    process.stderr.write(`tags:suggest: ${err.message}\n`);
+    process.exit(1);
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`tags:suggest: ${msg}\n`);
+  process.exit(1);
+});

package/bin/tags-suggest.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Package bin: local-LLM suggestions from an explicit project tag config.
+
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const runnerPath = resolve(__dirname, "tags-suggest-runner.ts");
+const tsxCli = fileURLToPath(import.meta.resolve("tsx/cli"));
+
+const result = spawnSync(
+  process.execPath,
+  [tsxCli, runnerPath, ...process.argv.slice(2)],
+  {
+    stdio: "inherit",
+    env: process.env,
+    cwd: process.cwd(),
+  },
+);
+
+if (result.error) {
+  process.stderr.write(
+    `\n[tags-suggest] ERROR: Could not start the package tag-suggest runner.\n` +
+      `  Reinstall @takazudo/zudo-doc and try again.\n\n`,
+  );
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/bin/zudo-doc.mjs

@@ -1,24 +1,31 @@
 #!/usr/bin/env node
 // @takazudo/zudo-doc/bin/zudo-doc.mjs
 //
-// Package bin: `zudo-doc eject <component>` swizzle CLI.
+// Package bin: `zudo-doc eject <component>` swizzle CLI, plus
+// `zudo-doc theme list|apply <slug>` (issue #2824; ADR
+// docs/adr/theme-packs.md).
 //
-// Self-contained ESM — runs on plain `node` with NO `tsx` requirement. The eject
-// logic is imported from the package's COMPILED `../dist/eject/index.js`, and the
-// only runtime deps are `minimist` + `picocolors` (declared deps of this package,
-// so they are present transitively in any consumer's node_modules). This is the
-// key difference from the tsx-runner pattern used by `bin/tags-audit.mjs`:
+// Self-contained ESM — runs on plain `node` with NO `tsx` requirement. Both
+// the eject and theme-cli logic are imported from the package's COMPILED
+// `../dist/eject/index.js` / `../dist/theme-cli/index.js`, and the only
+// runtime deps are `minimist` + `picocolors` (declared deps of this package,
+// so they are present transitively in any consumer's node_modules). This is
+// the key difference from the tsx-runner pattern used by `bin/tags-audit.mjs`:
 // tags-audit must load the *project's* TypeScript config files at runtime (hence
-// tsx), whereas eject only copies files + rewrites imports — no TS eval needed —
-// so it works in a default generated project that never installed tsx (#2367).
+// tsx), whereas eject/theme-cli only copy files / rewrite text — no TS eval
+// needed — so both work in a default generated project that never installed
+// tsx (#2367).
 //
 // Usage:
 //   zudo-doc eject <component>   # eject a component's TS source into the project
+//   zudo-doc theme list          # list installed theme packs + the active one
+//   zudo-doc theme apply <slug>  # rewrite zfb.config.ts's themePack field
 //   zudo-doc --help              # show help
 
 import minimist from "minimist";
 import pc from "picocolors";
 import { eject, EJECTABLE } from "../dist/eject/index.js";
+import { applyThemePack, formatThemeList, listThemePacks } from "../dist/theme-cli/index.js";
 
 const argv = minimist(process.argv.slice(2), {
   boolean: ["help"],
@@ -31,8 +38,10 @@ function printHelp() {
 ${pc.bold("Usage:")} zudo-doc <subcommand> [options]
 
 ${pc.bold("Subcommands:")}
-  eject <component>   Copy a component's TS source into your project and
-                      rewrite imports so it resolves locally.
+  eject <component>    Copy a component's TS source into your project and
+                       rewrite imports so it resolves locally.
+  theme list           List the installed theme packs and which one is active.
+  theme apply <slug>   Rewrite zfb.config.ts's themePack field to <slug>.
 
 ${pc.bold("Ejectable components:")}
   ${validNames}
@@ -46,35 +55,79 @@ ${pc.bold("Examples:")}
 
   ${pc.dim("# Eject the theme-toggle component")}
   zudo-doc eject theme-toggle
+
+  ${pc.dim("# List installed theme packs")}
+  zudo-doc theme list
+
+  ${pc.dim("# Switch to the foundry theme pack")}
+  zudo-doc theme apply foundry
 `);
 }
 
-async function main() {
-  if (argv["help"] || argv._.length === 0) {
-    printHelp();
-    process.exit(0);
+async function runEject(componentArg) {
+  if (!componentArg) {
+    console.error(
+      pc.red(`Missing component name.`) +
+        `\nUsage: zudo-doc eject <component>` +
+        `\nRun \`zudo-doc --help\` for the list of ejectable components.`,
+    );
+    process.exit(1);
   }
 
-  const [subcommand, componentArg] = argv._;
+  await eject(componentArg, { cwd: process.cwd() });
+}
+
+async function runThemeList() {
+  const result = await listThemePacks({ cwd: process.cwd() });
+  console.log(formatThemeList(result));
+}
 
-  if (subcommand !== "eject") {
+async function runThemeApply(slugArg) {
+  if (!slugArg) {
     console.error(
-      pc.red(`Unknown subcommand "${subcommand}".`) +
-        `\nRun \`zudo-doc --help\` for usage.`,
+      pc.red(`Missing theme pack slug.`) + `\nUsage: zudo-doc theme apply <slug>`,
     );
     process.exit(1);
   }
 
-  if (!componentArg) {
-    console.error(
-      pc.red(`Missing component name.`) +
-        `\nUsage: zudo-doc eject <component>` +
-        `\nRun \`zudo-doc --help\` for the list of ejectable components.`,
-    );
+  const result = await applyThemePack(slugArg, { cwd: process.cwd() });
+  if (!result.ok) {
+    console.error(pc.red(result.message));
     process.exit(1);
   }
+  console.log(pc.green(result.message));
+}
 
-  await eject(componentArg, { cwd: process.cwd() });
+async function runTheme(themeArgs) {
+  const [action, arg] = themeArgs;
+
+  if (action === "list") return runThemeList();
+  if (action === "apply") return runThemeApply(arg);
+
+  console.error(
+    pc.red(`Unknown "theme" action "${action}".`) +
+      `\nUsage: zudo-doc theme list` +
+      `\n       zudo-doc theme apply <slug>`,
+  );
+  process.exit(1);
+}
+
+async function main() {
+  if (argv["help"] || argv._.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const [subcommand, ...rest] = argv._;
+
+  if (subcommand === "eject") return runEject(rest[0]);
+  if (subcommand === "theme") return runTheme(rest);
+
+  console.error(
+    pc.red(`Unknown subcommand "${subcommand}".`) +
+      `\nRun \`zudo-doc --help\` for usage.`,
+  );
+  process.exit(1);
 }
 
 main().catch((err) => {

package/dist/breadcrumb/breadcrumb.d.ts

@@ -1,7 +1,7 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 import type { ComponentChildren, VNode } from "preact";
-import type { BreadcrumbItem, SidebarNode } from "./types.js";
+import type { BreadcrumbItem, BreadcrumbNode } from "./types.js";
 /**
  * Convert a sidebar tree + the current page's id into the ordered list
  * of crumbs the renderer walks. The first crumb is the home rung
@@ -13,13 +13,13 @@ import type { BreadcrumbItem, SidebarNode } from "./types.js";
  * src/utils/docs.ts so the rendered output stays parity-equivalent
  * with the original Astro breadcrumb component.
  */
-export declare function buildBreadcrumbItems(tree: SidebarNode[], currentId: string, homeHref: string): BreadcrumbItem[];
+export declare function buildBreadcrumbItems(tree: BreadcrumbNode[], currentId: string, homeHref: string): BreadcrumbItem[];
 export interface BreadcrumbProps {
     /** Pre-built items, or omit and pass `tree` + `currentId` instead. */
     items?: BreadcrumbItem[];
     /** Sidebar tree to derive the trail from. Required when `items` is omitted. */
-    tree?: SidebarNode[];
-    /** Id of the current page (matches SidebarNode.id). Required when `items` is omitted. */
+    tree?: BreadcrumbNode[];
+    /** Id of the current page (matches BreadcrumbNode.id). Required when `items` is omitted. */
     currentId?: string;
     /** Href for the leading home rung. Defaults to "/". */
     homeHref?: string;

package/dist/breadcrumb/find-path.d.ts

@@ -1,4 +1,4 @@
-import type { BreadcrumbNode, SidebarNode } from "./types.js";
+import type { BreadcrumbNode } from "./types.js";
 /**
  * Walk the sidebar tree and return the chain of nodes from the root
  * level down to (and including) the node whose `id` matches `targetId`.
@@ -10,4 +10,4 @@ import type { BreadcrumbNode, SidebarNode } from "./types.js";
  * ancestry. The home/root crumb is the renderer's responsibility — this
  * helper deals strictly with the tree itself.
  */
-export declare function findPath<T extends BreadcrumbNode = SidebarNode>(nodes: readonly T[], targetId: string): T[];
+export declare function findPath<T extends BreadcrumbNode = BreadcrumbNode>(nodes: readonly T[], targetId: string): T[];

package/dist/breadcrumb/index.d.ts

@@ -1,4 +1,4 @@
 export { Breadcrumb, buildBreadcrumbItems } from "./breadcrumb.js";
 export type { BreadcrumbProps } from "./breadcrumb.js";
 export { findPath } from "./find-path.js";
-export type { BreadcrumbItem, SidebarNode } from "./types.js";
+export type { BreadcrumbItem, BreadcrumbNode } from "./types.js";

package/dist/breadcrumb/types.d.ts

@@ -15,11 +15,6 @@ export interface BreadcrumbNode {
     sidebar_position?: number;
     children?: readonly BreadcrumbNode[];
 }
-/**
- * Backward-compatible alias retained for callers that previously imported
- * `SidebarNode` from this subpath.
- */
-export type SidebarNode = BreadcrumbNode;
 /**
  * One rung of the breadcrumb trail. `href` is omitted on the final
  * (current-page) item so the renderer can present it as plain text.