@takazudo/zudo-doc 5.8.0 → 5.10.0

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[];

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

@@ -0,0 +1,255 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  renderTableRow,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function freshState() {
+  return { quote: null, triple: false, escaped: false, comment: false };
+}
+function advanceState(text, index, state) {
+  const char = text[index] ?? "";
+  if (state.comment) {
+    if (char === "\n") state.comment = false;
+    return 1;
+  }
+  if (state.quote !== null) {
+    if (state.escaped) {
+      state.escaped = false;
+      return 1;
+    }
+    if (char === "\\") {
+      state.escaped = true;
+      return 1;
+    }
+    if (state.triple && text.slice(index, index + 3) === state.quote.repeat(3)) {
+      state.quote = null;
+      state.triple = false;
+      return 3;
+    }
+    if (!state.triple && char === state.quote) state.quote = null;
+    return 1;
+  }
+  if (char === "#") {
+    state.comment = true;
+    return 1;
+  }
+  if (char === "'" || char === '"') {
+    state.quote = char;
+    state.triple = text.slice(index, index + 3) === char.repeat(3);
+    return state.triple ? 3 : 1;
+  }
+  return 1;
+}
+function findPrefixRuleBodies(source) {
+  const bodies = [];
+  const state = freshState();
+  let index = 0;
+  while (index < source.length) {
+    if (state.quote === null && !state.comment && source.startsWith("prefix_rule", index)) {
+      const before = source[index - 1];
+      const after = source[index + "prefix_rule".length];
+      if ((!before || !/[\w]/.test(before)) && (!after || !/[\w]/.test(after))) {
+        let open = index + "prefix_rule".length;
+        while (/\s/.test(source[open] ?? "")) open++;
+        if (source[open] === "(") {
+          const callState = freshState();
+          let depth = 1;
+          let cursor = open + 1;
+          const bodyStart = cursor;
+          while (cursor < source.length) {
+            if (callState.quote === null && !callState.comment) {
+              if (source[cursor] === "(") depth++;
+              if (source[cursor] === ")") {
+                depth--;
+                if (depth === 0) break;
+              }
+            }
+            cursor += advanceState(source, cursor, callState);
+          }
+          bodies.push(source.slice(bodyStart, cursor));
+          index = cursor < source.length ? cursor + 1 : source.length;
+          continue;
+        }
+      }
+    }
+    index += advanceState(source, index, state);
+  }
+  return bodies;
+}
+function splitTopLevel(text, delimiter) {
+  const parts = [];
+  const state = freshState();
+  let square = 0;
+  let round = 0;
+  let curly = 0;
+  let start = 0;
+  let index = 0;
+  while (index < text.length) {
+    if (state.quote === null && !state.comment) {
+      const char = text[index];
+      if (char === "[") square++;
+      else if (char === "]") square--;
+      else if (char === "(") round++;
+      else if (char === ")") round--;
+      else if (char === "{") curly++;
+      else if (char === "}") curly--;
+      else if (char === delimiter && square === 0 && round === 0 && curly === 0) {
+        parts.push(text.slice(start, index));
+        start = index + 1;
+      }
+    }
+    index += advanceState(text, index, state);
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+function parseStringLiteral(value) {
+  const text = value.trim();
+  const quote = text[0];
+  if (quote !== '"' && quote !== "'" || text.at(-1) !== quote) return void 0;
+  if (text.startsWith(quote.repeat(3)) && text.endsWith(quote.repeat(3))) {
+    return text.slice(3, -3);
+  }
+  const inner = text.slice(1, -1);
+  let result = "";
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+    if (char !== "\\") {
+      result += char;
+      continue;
+    }
+    const next = inner[++i];
+    if (next === void 0) return void 0;
+    const escapes = {
+      n: "\n",
+      r: "\r",
+      t: "	",
+      "\\": "\\",
+      "'": "'",
+      '"': '"'
+    };
+    result += escapes[next] ?? next;
+  }
+  return result;
+}
+function parsePatternValue(text) {
+  const trimmed = text.trim();
+  const stringValue = parseStringLiteral(trimmed);
+  if (stringValue !== void 0) return stringValue;
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return void 0;
+  const inner = trimmed.slice(1, -1);
+  if (inner.trim() === "") return [];
+  const values = [];
+  for (const part of splitTopLevel(inner, ",")) {
+    if (part.trim() === "") continue;
+    const parsed = parsePatternValue(part);
+    if (parsed === void 0) return void 0;
+    values.push(parsed);
+  }
+  return values;
+}
+function formatPattern(value) {
+  if (!Array.isArray(value)) return value;
+  const parts = [];
+  for (const element of value) {
+    if (Array.isArray(element)) {
+      if (element.some(Array.isArray)) return void 0;
+      parts.push(element.join("|"));
+    } else {
+      parts.push(element);
+    }
+  }
+  return parts.join(" ");
+}
+function parseRule(body) {
+  const args = /* @__PURE__ */ new Map();
+  for (const part of splitTopLevel(body, ",")) {
+    const assignment = splitTopLevel(part, "=");
+    if (assignment.length !== 2) continue;
+    const key = assignment[0]?.trim();
+    const value = assignment[1];
+    if (key && value !== void 0) args.set(key, value.trim());
+  }
+  const rawPattern = args.get("pattern");
+  const parsedPattern = rawPattern === void 0 ? void 0 : parsePatternValue(rawPattern);
+  const decision = args.has("decision") ? parseStringLiteral(args.get("decision") ?? "") : "allow";
+  return {
+    pattern: parsedPattern === void 0 ? void 0 : formatPattern(parsedPattern),
+    decision,
+    justification: args.has("justification") ? parseStringLiteral(args.get("justification") ?? "") : void 0
+  };
+}
+function generateRulesCategory(config) {
+  const rulesDir = path.join(config.codexDir, "rules");
+  const outputDir = path.join(config.docsDir, "codex-rules");
+  cleanDir(outputDir);
+  if (!fs.existsSync(rulesDir)) return [];
+  let files;
+  try {
+    files = fs.readdirSync(rulesDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".rules")).map((entry) => entry.name).sort();
+  } catch (error) {
+    warn(rulesDir, `unable to read rules 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(rulesDir, filename);
+    const slug = filename.replace(/\.rules$/, "");
+    assertUniqueSlug("rule", slug, filePath, emitted);
+    let source;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+    } catch (error) {
+      warn(filePath, `unable to read rules file, skipping it: ${String(error)}`);
+      continue;
+    }
+    const rows = findPrefixRuleBodies(source).map(parseRule);
+    const body = [
+      "## Rules",
+      "",
+      "| Pattern | Decision | Justification |",
+      "| --- | --- | --- |",
+      ...rows.length > 0 ? rows.map(
+        (row) => renderTableRow([row.pattern, row.decision, row.justification])
+      ) : [renderTableRow(Array.from({ length: 3 }))],
+      "",
+      "## Source",
+      "",
+      renderCodeFence(source, "python")
+    ].join("\n");
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: filename,
+      description: `Command approval rules from ${filename}`,
+      sidebarLabel: filename,
+      body
+    });
+    items.push({ filename, slug });
+  }
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Rules",
+      909,
+      "Command approval rules",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateRulesCategory
+};

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

@@ -0,0 +1,2 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export declare function generateSkillsCategoryDocs(config: CodexResourcesConfig): import("../resource-docs-shared/skills.js").SkillItem[];

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

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import {
+  escapeForMdx,
+  formatFrontmatterString,
+  generateSkillsCategory
+} from "../resource-docs-shared/index.js";
+import { isRecord, warn } from "./utils.js";
+function optionalMetadataString(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 renderOpenAiMetadata(skillAbsDir) {
+  const filePath = path.join(skillAbsDir, "agents", "openai.yaml");
+  if (!fs.existsSync(filePath)) return "";
+  let data;
+  try {
+    const yaml = fs.readFileSync(filePath, "utf8");
+    data = matter(`---
+${yaml}
+---
+`).data;
+  } catch (error) {
+    warn(filePath, `unable to parse YAML, omitting metadata: ${String(error)}`);
+    return "";
+  }
+  if (!isRecord(data)) {
+    warn(filePath, "YAML root must be an object; omitting metadata");
+    return "";
+  }
+  let interfaceData;
+  if (data.interface !== void 0) {
+    if (isRecord(data.interface)) interfaceData = data.interface;
+    else warn(filePath, "interface must be an object; omitting interface metadata");
+  }
+  let policy;
+  if (data.policy !== void 0) {
+    if (isRecord(data.policy)) policy = data.policy;
+    else warn(filePath, "policy must be an object; omitting policy metadata");
+  }
+  const displayName = interfaceData ? optionalMetadataString(interfaceData, "display_name", filePath) : void 0;
+  const shortDescription = interfaceData ? optionalMetadataString(interfaceData, "short_description", filePath) : void 0;
+  let explicitOnly = false;
+  if (policy?.allow_implicit_invocation !== void 0) {
+    if (typeof policy.allow_implicit_invocation === "boolean") {
+      explicitOnly = policy.allow_implicit_invocation === false;
+    } else {
+      warn(
+        filePath,
+        "policy.allow_implicit_invocation must be a boolean; omitting invocation metadata"
+      );
+    }
+  }
+  return [
+    displayName ? `**Display name:** ${escapeForMdx(displayName)}` : "",
+    shortDescription ? `**Short description:** ${escapeForMdx(shortDescription)}` : "",
+    explicitOnly ? `**Invocation:** explicit only (\`$${path.basename(skillAbsDir)}\`)` : ""
+  ].filter(Boolean).join("\n");
+}
+function generateSkillsCategoryDocs(config) {
+  const projectRoot = config.projectRoot ?? config.codexDir;
+  const scanRoot = config.scanRoot ?? projectRoot;
+  return generateSkillsCategory({
+    skillsDirs: [
+      path.join(config.codexDir, "skills"),
+      path.join(projectRoot, ".agents", "skills"),
+      path.join(scanRoot, ".agents", "skills")
+    ],
+    outputDir: path.join(config.docsDir, "codex-skills"),
+    label: "Skills",
+    position: 910,
+    description: "Skill packages",
+    sourceLabel: ".codex/skills",
+    renderExtraHeader: renderOpenAiMetadata,
+    renderFrontmatterString: formatFrontmatterString
+  });
+}
+export {
+  generateSkillsCategoryDocs
+};

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

@@ -0,0 +1,14 @@
+export declare function warn(filePath: string, message: string): void;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function filenameSlug(filename: string): string;
+export declare function renderTableRow(values: unknown[]): string;
+export declare function assertUniqueSlug(resource: string, slug: string, filePath: string, emitted: Map<string, string>): void;
+export declare function writeGeneratedPage({ outputPath, title, description, sidebarLabel, sidebarPosition, body, }: {
+    outputPath: string;
+    title: string;
+    description: string;
+    sidebarLabel?: string;
+    sidebarPosition?: number;
+    body: string;
+}): void;
+export declare function languageForFilename(filename: string): string;