@takazudo/zudo-doc 5.7.0 → 5.9.0

package/dist/plugins/internal/codex-resources/agents.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "smol-toml";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  escapeForMdx,
+  escapeMarkdownTableCell,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  filenameSlug,
+  isRecord,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function optionalString(record, field, filePath) {
+  const value = record[field];
+  if (value === void 0) return void 0;
+  if (typeof value === "string") return value;
+  warn(filePath, `${field} must be a string; omitting it`);
+  return void 0;
+}
+function generateAgentsCategory(config) {
+  const agentsDir = path.join(config.codexDir, "agents");
+  const outputDir = path.join(config.docsDir, "codex-agents");
+  cleanDir(outputDir);
+  if (!fs.existsSync(agentsDir)) return [];
+  let files;
+  try {
+    files = fs.readdirSync(agentsDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".toml")).map((entry) => entry.name).sort();
+  } catch (error) {
+    warn(agentsDir, `unable to read agents directory: ${String(error)}`);
+    return [];
+  }
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  const emitted = /* @__PURE__ */ new Map();
+  for (const filename of files) {
+    const filePath = path.join(agentsDir, filename);
+    let source;
+    let parsed;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+      parsed = parse(source);
+    } catch (error) {
+      warn(filePath, `unable to parse TOML, skipping file: ${String(error)}`);
+      continue;
+    }
+    if (!isRecord(parsed)) {
+      warn(filePath, "parsed TOML root was not an object, skipping file");
+      continue;
+    }
+    const slug = filenameSlug(filename.replace(/\.toml$/, ""));
+    assertUniqueSlug("agent", slug, filename, emitted);
+    const name = optionalString(parsed, "name", filePath) ?? slug;
+    const description = optionalString(parsed, "description", filePath) ?? "";
+    const model = optionalString(parsed, "model", filePath);
+    const reasoning = optionalString(parsed, "model_reasoning_effort", filePath);
+    const sandbox = optionalString(parsed, "sandbox_mode", filePath);
+    const instructions = optionalString(parsed, "developer_instructions", filePath);
+    const badges = [
+      model ? `**Model:** ${escapeMarkdownTableCell(model)}` : "",
+      reasoning ? `**Reasoning effort:** ${escapeMarkdownTableCell(reasoning)}` : "",
+      sandbox ? `**Sandbox:** ${escapeMarkdownTableCell(sandbox)}` : ""
+    ].filter(Boolean);
+    const sections = [badges.join("\n")];
+    if (instructions !== void 0) {
+      sections.push(
+        `## Developer instructions
+
+${escapeForMdx(instructions.trim())}`
+      );
+    }
+    sections.push(`## Source
+
+${renderCodeFence(source, "toml")}`);
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: name,
+      description,
+      sidebarLabel: name,
+      body: sections.filter(Boolean).join("\n\n")
+    });
+    items.push({ filename, slug, name });
+  }
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Agents",
+      907,
+      "Custom subagents",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateAgentsCategory
+};

package/dist/plugins/internal/codex-resources/config.d.ts

@@ -0,0 +1,6 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface ConfigItem {
+    filename: string;
+    slug: string;
+}
+export declare function generateConfigCategory(config: CodexResourcesConfig): ConfigItem[];

package/dist/plugins/internal/codex-resources/config.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse, TomlDate } from "smol-toml";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  escapeMarkdownTableCell,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  filenameSlug,
+  isRecord,
+  renderTableRow,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function configFiles(codexDir) {
+  try {
+    return fs.readdirSync(codexDir, { withFileTypes: true }).filter(
+      (entry) => entry.isFile() && (entry.name === "config.toml" || entry.name === "config.toml.example" || entry.name.endsWith(".config.toml"))
+    ).map((entry) => entry.name).sort((a, b) => {
+      if (a === "config.toml") return -1;
+      if (b === "config.toml") return 1;
+      return a.localeCompare(b);
+    });
+  } catch (error) {
+    warn(codexDir, `unable to read config files: ${String(error)}`);
+    return [];
+  }
+}
+function renderValue(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) return JSON.stringify(value);
+  if (value instanceof TomlDate) return value.toISOString();
+  return String(value);
+}
+function generateConfigCategory(config) {
+  const outputDir = path.join(config.docsDir, "codex-config");
+  cleanDir(outputDir);
+  if (!fs.existsSync(config.codexDir)) return [];
+  const files = configFiles(config.codexDir);
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  const emitted = /* @__PURE__ */ new Map();
+  for (const filename of files) {
+    const filePath = path.join(config.codexDir, filename);
+    let source;
+    let parsed;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+      parsed = parse(source);
+    } catch (error) {
+      warn(filePath, `unable to parse TOML, skipping file: ${String(error)}`);
+      continue;
+    }
+    if (!isRecord(parsed)) {
+      warn(filePath, "parsed TOML root was not an object, skipping file");
+      continue;
+    }
+    const slug = filenameSlug(filename);
+    assertUniqueSlug("config", slug, filename, emitted);
+    const settings = Object.entries(parsed).filter(([, value]) => !isRecord(value) || value instanceof TomlDate).map(([key, value]) => renderTableRow([key, renderValue(value)]));
+    const sections = source.match(/^\s*\[\[?[^\]]+\]\]?/gm) ?? [];
+    const sectionList = sections.length === 0 ? "\u2014" : sections.map(
+      (section) => `- ${escapeMarkdownTableCell(section.trim())}`
+    ).join("\n");
+    const body = [
+      "## Settings",
+      "",
+      "| Key | Value |",
+      "| --- | --- |",
+      ...settings.length > 0 ? settings : [renderTableRow([void 0, void 0])],
+      "",
+      "## Sections",
+      "",
+      sectionList,
+      "",
+      "## Source",
+      "",
+      renderCodeFence(source, "toml")
+    ].join("\n");
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: filename,
+      description: `Codex configuration from ${filename}`,
+      sidebarLabel: filename,
+      body
+    });
+    items.push({ filename, slug });
+  }
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Config",
+      906,
+      "config.toml and profiles",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateConfigCategory
+};

package/dist/plugins/internal/codex-resources/generate.d.ts

@@ -0,0 +1,20 @@
+export interface CodexResourcesConfig {
+    codexDir: string;
+    /** The doc site's own root and the default value of `scanRoot`. */
+    projectRoot?: string;
+    /**
+     * Repo-wide discovery root for both the AGENTS.md walk and the repo-level
+     * `.agents/skills/` root. Also serves as the relative-path base for the
+     * generated AGENTS.md titles and slugs. Defaults to `projectRoot`.
+     */
+    scanRoot?: string;
+    docsDir: string;
+}
+export declare function generateCodexResourcesDocs(config: CodexResourcesConfig): {
+    agentsMd: number;
+    config: number;
+    agents: number;
+    hooks: number;
+    rules: number;
+    skills: number;
+};

package/dist/plugins/internal/codex-resources/generate.js

@@ -0,0 +1,34 @@
+import { generateAgentsMdCategory } from "./agents-md.js";
+import { generateAgentsCategory } from "./agents.js";
+import { generateConfigCategory } from "./config.js";
+import { generateHooksCategory } from "./hooks.js";
+import { generateOverview } from "./overview.js";
+import { generateRulesCategory } from "./rules.js";
+import { generateSkillsCategoryDocs } from "./skills.js";
+function generateCodexResourcesDocs(config) {
+  const agentsMd = generateAgentsMdCategory(config);
+  const configItems = generateConfigCategory(config);
+  const agents = generateAgentsCategory(config);
+  const hooks = generateHooksCategory(config);
+  const rules = generateRulesCategory(config);
+  const skills = generateSkillsCategoryDocs(config);
+  generateOverview(config, {
+    agentsMd: agentsMd.length > 0,
+    config: configItems.length > 0,
+    agents: agents.length > 0,
+    hooks: hooks.length > 0,
+    rules: rules.length > 0,
+    skills: skills.length > 0
+  });
+  return {
+    agentsMd: agentsMd.length,
+    config: configItems.length,
+    agents: agents.length,
+    hooks: hooks.length,
+    rules: rules.length,
+    skills: skills.length
+  };
+}
+export {
+  generateCodexResourcesDocs
+};

package/dist/plugins/internal/codex-resources/hooks.d.ts

@@ -0,0 +1,6 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface HookItem {
+    filename: string;
+    slug: string;
+}
+export declare function generateHooksCategory(config: CodexResourcesConfig): HookItem[];

package/dist/plugins/internal/codex-resources/hooks.js

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  getScriptDescription,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  filenameSlug,
+  isRecord,
+  languageForFilename,
+  renderTableRow,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function readHookRows(filePath, source) {
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    warn(filePath, `unable to parse JSON, skipping hooks.json page: ${String(error)}`);
+    return null;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.hooks)) {
+    warn(filePath, "hooks.hooks must be a non-null object; skipping hooks.json page");
+    return null;
+  }
+  const rows = [];
+  for (const [event, groups] of Object.entries(parsed.hooks)) {
+    if (!Array.isArray(groups)) {
+      warn(filePath, `hooks.${event} must be an array; skipping event`);
+      continue;
+    }
+    for (const [groupIndex, group] of groups.entries()) {
+      if (!isRecord(group) || !Array.isArray(group.hooks)) {
+        warn(
+          filePath,
+          `hooks.${event}[${groupIndex}].hooks must be an array; skipping group`
+        );
+        continue;
+      }
+      for (const [handlerIndex, handler] of group.hooks.entries()) {
+        if (!isRecord(handler) || typeof handler.command !== "string") {
+          warn(
+            filePath,
+            `hooks.${event}[${groupIndex}].hooks[${handlerIndex}] must be an object with a string command; skipping row`
+          );
+          continue;
+        }
+        rows.push({
+          event,
+          matcher: group.matcher,
+          type: handler.type,
+          command: handler.command,
+          timeout: handler.timeout,
+          async: handler.async
+        });
+      }
+    }
+  }
+  return rows;
+}
+function generateHooksJson(config, outputDir, emitted) {
+  const filePath = path.join(config.codexDir, "hooks.json");
+  if (!fs.existsSync(filePath)) return null;
+  let source;
+  try {
+    source = fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    warn(filePath, `unable to read hooks.json, skipping page: ${String(error)}`);
+    return null;
+  }
+  const rows = readHookRows(filePath, source);
+  if (rows === null) return null;
+  const slug = "hooks-json";
+  assertUniqueSlug("hook", slug, "hooks.json", emitted);
+  const tableRows = rows.map((row) => renderTableRow([
+    row.event,
+    row.matcher,
+    row.type,
+    row.command,
+    row.timeout,
+    row.async
+  ]));
+  const body = [
+    "| Event | Matcher | Type | Command | Timeout | Async |",
+    "| --- | --- | --- | --- | --- | --- |",
+    ...tableRows.length > 0 ? tableRows : [renderTableRow(Array.from({ length: 6 }))],
+    "",
+    "## Source",
+    "",
+    renderCodeFence(source, "json")
+  ].join("\n");
+  writeGeneratedPage({
+    outputPath: path.join(outputDir, `${slug}.mdx`),
+    title: "hooks.json",
+    description: "Codex lifecycle hook configuration",
+    sidebarLabel: "hooks.json",
+    body
+  });
+  return { filename: "hooks.json", slug };
+}
+function generateHookScripts(config, outputDir, emitted) {
+  const hooksDir = path.join(config.codexDir, "hooks");
+  if (!fs.existsSync(hooksDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(hooksDir, { withFileTypes: true });
+  } catch (error) {
+    warn(hooksDir, `unable to read hooks directory: ${String(error)}`);
+    return [];
+  }
+  const items = [];
+  for (const entry of entries.filter((item) => item.isFile()).sort(
+    (a, b) => a.name.localeCompare(b.name)
+  )) {
+    const filePath = path.join(hooksDir, entry.name);
+    const slug = filenameSlug(entry.name);
+    assertUniqueSlug("hook", slug, filePath, emitted);
+    let source;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+    } catch (error) {
+      warn(filePath, `unable to read hook script, skipping file: ${String(error)}`);
+      continue;
+    }
+    const scriptDescription = getScriptDescription(filePath).replace(/^ — /, "");
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: entry.name,
+      description: scriptDescription,
+      sidebarLabel: entry.name,
+      body: `## Source
+
+${renderCodeFence(
+        source,
+        languageForFilename(entry.name)
+      )}`
+    });
+    items.push({ filename: entry.name, slug });
+  }
+  return items;
+}
+function generateHooksCategory(config) {
+  const outputDir = path.join(config.docsDir, "codex-hooks");
+  cleanDir(outputDir);
+  const hasJson = fs.existsSync(path.join(config.codexDir, "hooks.json"));
+  const hasScripts = fs.existsSync(path.join(config.codexDir, "hooks"));
+  if (!hasJson && !hasScripts) return [];
+  ensureDir(outputDir);
+  const emitted = /* @__PURE__ */ new Map();
+  const jsonItem = generateHooksJson(config, outputDir, emitted);
+  const items = [
+    ...jsonItem ? [jsonItem] : [],
+    ...generateHookScripts(config, outputDir, emitted)
+  ];
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Hooks",
+      908,
+      "Lifecycle hooks",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateHooksCategory
+};

package/dist/plugins/internal/codex-resources/index.d.ts

@@ -0,0 +1,24 @@
+import { generateCodexResourcesDocs, type CodexResourcesConfig } from "./generate.js";
+export interface CodexResourcesPluginOptions {
+    /**
+     * Path to the project's `.codex/` directory. Resolved against
+     * `projectRoot` when relative.
+     */
+    codexDir: string;
+    /**
+     * Anchor for `codexDir`, `docsDir`, and relative `scanRoot` paths, and the
+     * default value of `scanRoot`. Defaults to `process.cwd()`.
+     */
+    projectRoot?: string;
+    /**
+     * Repo-wide discovery root, defaulting to `projectRoot`. It governs both the
+     * `AGENTS.md` / `AGENTS.override.md` walk (including relative titles/slugs)
+     * and the repo-level `.agents/skills/` root. `codexDir` and `docsDir` remain
+     * anchored to `projectRoot`.
+     */
+    scanRoot?: string;
+    /** Output directory, anchored to `projectRoot` when relative. */
+    docsDir?: string;
+}
+export declare function runCodexResourcesPreStep(options: CodexResourcesPluginOptions): ReturnType<typeof generateCodexResourcesDocs>;
+export { generateCodexResourcesDocs, type CodexResourcesConfig };

package/dist/plugins/internal/codex-resources/index.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import {
+  generateCodexResourcesDocs
+} from "./generate.js";
+function runCodexResourcesPreStep(options) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const codexDir = path.isAbsolute(options.codexDir) ? options.codexDir : path.resolve(projectRoot, options.codexDir);
+  const scanRoot = options.scanRoot === void 0 ? projectRoot : path.isAbsolute(options.scanRoot) ? options.scanRoot : path.resolve(projectRoot, options.scanRoot);
+  const docsDirInput = options.docsDir ?? "src/content/docs";
+  const docsDir = path.isAbsolute(docsDirInput) ? docsDirInput : path.resolve(projectRoot, docsDirInput);
+  return generateCodexResourcesDocs({
+    codexDir,
+    projectRoot,
+    scanRoot,
+    docsDir
+  });
+}
+export {
+  generateCodexResourcesDocs,
+  runCodexResourcesPreStep
+};

package/dist/plugins/internal/codex-resources/overview.d.ts

@@ -0,0 +1,10 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface CodexCategoryPresence {
+    agentsMd: boolean;
+    config: boolean;
+    agents: boolean;
+    hooks: boolean;
+    rules: boolean;
+    skills: boolean;
+}
+export declare function generateOverview(config: CodexResourcesConfig, presence: CodexCategoryPresence): void;

package/dist/plugins/internal/codex-resources/overview.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatFrontmatterString } from "../resource-docs-shared/index.js";
+import { cleanDir, ensureDir } from "../resource-docs-shared/index.js";
+function generateOverview(config, presence) {
+  const outputDir = path.join(config.docsDir, "codex");
+  cleanDir(outputDir);
+  ensureDir(outputDir);
+  const slugs = [];
+  if (presence.agentsMd) slugs.push("codex-agents-md");
+  if (presence.config) slugs.push("codex-config");
+  if (presence.agents) slugs.push("codex-agents");
+  if (presence.hooks) slugs.push("codex-hooks");
+  if (presence.rules) slugs.push("codex-rules");
+  if (presence.skills) slugs.push("codex-skills");
+  fs.writeFileSync(
+    path.join(outputDir, "index.mdx"),
+    `---
+title: ${formatFrontmatterString("Codex")}
+description: ${formatFrontmatterString("OpenAI Codex configuration reference.")}
+sidebar_position: 904
+generated: true
+---
+
+## Resources
+
+<CategoryNav categories={${JSON.stringify(slugs)}} />
+`
+  );
+}
+export {
+  generateOverview
+};

package/dist/plugins/internal/codex-resources/rules.d.ts

@@ -0,0 +1,6 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface RuleItem {
+    filename: string;
+    slug: string;
+}
+export declare function generateRulesCategory(config: CodexResourcesConfig): RuleItem[];