@oddessentials/odd-docs 2.0.0

package/dist/cli/index.js

@@ -0,0 +1,1481 @@
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/generate.ts
+import { writeFile, mkdir } from "fs/promises";
+import { join as join2, resolve } from "path";
+
+// src/core/parser/manifestParser.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function parseManifest(repoPath) {
+  const manifestPath = join(repoPath, "manifest.json");
+  let content;
+  try {
+    content = await readFile(manifestPath, "utf-8");
+  } catch {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(content);
+  } catch {
+    throw new Error(`Invalid JSON in manifest: ${manifestPath}`);
+  }
+  if (!manifest.tool_id) {
+    throw new Error("Manifest missing required field: tool_id");
+  }
+  if (!manifest.version) {
+    throw new Error("Manifest missing required field: version");
+  }
+  const capabilities = [];
+  if (manifest.capabilities) {
+    for (const [type, values] of Object.entries(manifest.capabilities)) {
+      if (Array.isArray(values) && values.length > 0) {
+        capabilities.push({ type, values, provenance: "manifest" });
+      }
+    }
+  }
+  const result = {
+    entity: {
+      type: "tool",
+      id: manifest.tool_id,
+      version: manifest.version,
+      description: manifest.description
+    },
+    inputs: {
+      schema: manifest.parameters,
+      provenance: "manifest"
+    }
+  };
+  if (capabilities.length > 0 || manifest.timeout_ms || manifest.resource_limits) {
+    result.constraints = {
+      capabilities: capabilities.length > 0 ? capabilities : void 0,
+      timeoutMs: manifest.timeout_ms,
+      resourceLimits: manifest.resource_limits ? {
+        memoryMb: manifest.resource_limits.memory_mb,
+        cpuCores: manifest.resource_limits.cpu_cores
+      } : void 0
+    };
+  }
+  if (manifest.deprecation) {
+    result.lifecycle = {
+      version: manifest.version,
+      deprecation: {
+        deprecatedAt: manifest.deprecation.deprecated_at,
+        sunsetDate: manifest.deprecation.sunset_date,
+        migrationUrl: manifest.deprecation.migration_url
+      }
+    };
+  }
+  return result;
+}
+
+// src/core/ir/builder.ts
+import { createHash } from "crypto";
+
+// src/core/parser/schemaParser.ts
+function parseSchema(schema) {
+  if (!schema) return [];
+  const jsonSchema = schema;
+  const parameters = [];
+  const required = new Set(jsonSchema.required ?? []);
+  if (jsonSchema.properties) {
+    for (const [name, propSchema] of Object.entries(jsonSchema.properties)) {
+      parameters.push(parseProperty(name, propSchema, required.has(name)));
+    }
+  }
+  return parameters;
+}
+function parseProperty(name, schema, isRequired) {
+  const param = {
+    name,
+    type: resolveType(schema),
+    required: isRequired
+  };
+  if (schema.description) {
+    param.description = schema.description;
+  }
+  if (schema.default !== void 0) {
+    param.default = schema.default;
+  }
+  if (schema.enum) {
+    param.enum = schema.enum;
+  }
+  const constraints = buildConstraints(schema);
+  if (constraints) {
+    param.constraints = constraints;
+  }
+  return param;
+}
+function resolveType(schema) {
+  if (schema.$ref) {
+    const refParts = schema.$ref.split("/");
+    return refParts[refParts.length - 1];
+  }
+  if (schema.enum) {
+    return "enum";
+  }
+  if (schema.type === "array" && schema.items) {
+    return `${resolveType(schema.items)}[]`;
+  }
+  return schema.type ?? "unknown";
+}
+function buildConstraints(schema) {
+  const parts = [];
+  if (schema.minimum !== void 0) {
+    parts.push(`min: ${schema.minimum}`);
+  }
+  if (schema.maximum !== void 0) {
+    parts.push(`max: ${schema.maximum}`);
+  }
+  if (schema.minLength !== void 0) {
+    parts.push(`minLength: ${schema.minLength}`);
+  }
+  if (schema.maxLength !== void 0) {
+    parts.push(`maxLength: ${schema.maxLength}`);
+  }
+  if (schema.pattern) {
+    parts.push(`pattern: ${schema.pattern}`);
+  }
+  return parts.length > 0 ? parts.join(", ") : void 0;
+}
+function enrichSchemaSection(section) {
+  return {
+    ...section,
+    parameters: parseSchema(section.schema)
+  };
+}
+
+// src/core/ir/builder.ts
+function buildDocIR(manifest) {
+  const enrichedInputs = enrichSchemaSection(manifest.inputs);
+  const ir = {
+    version: "1.0.0",
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    determinismKey: "",
+    // Computed below
+    entity: manifest.entity,
+    inputs: enrichedInputs,
+    constraints: manifest.constraints,
+    lifecycle: manifest.lifecycle,
+    provenance: {
+      entity: "manifest",
+      inputs: "manifest"
+    }
+  };
+  ir.determinismKey = computeDeterminismKey(ir);
+  return ir;
+}
+function computeDeterminismKey(ir) {
+  const canonical = JSON.stringify({
+    entity: ir.entity,
+    inputs: ir.inputs,
+    constraints: ir.constraints,
+    lifecycle: ir.lifecycle
+  });
+  const hash = createHash("sha256").update(canonical).digest("hex");
+  return `sha256:${hash}`;
+}
+
+// src/core/renderer/markdownRenderer.ts
+function renderMarkdown(ir) {
+  const lines = [];
+  lines.push(`# ${ir.entity.id}`);
+  lines.push("");
+  lines.push(`**Version:** ${ir.entity.version}  `);
+  lines.push(`**Type:** ${ir.entity.type}  `);
+  if (ir.entity.description) {
+    lines.push("");
+    lines.push(ir.entity.description);
+  }
+  lines.push("");
+  if (ir.overview) {
+    lines.push("## Overview");
+    lines.push("");
+    if (ir.overview.intent) {
+      lines.push(`**Intent:** ${ir.overview.intent}`);
+      lines.push("");
+    }
+    if (ir.overview.useCases?.length) {
+      lines.push("### Use Cases");
+      lines.push("");
+      for (const useCase of ir.overview.useCases) {
+        lines.push(`- ${useCase}`);
+      }
+      lines.push("");
+    }
+    if (ir.overview.sideEffects?.length) {
+      lines.push("### Side Effects");
+      lines.push("");
+      for (const effect of ir.overview.sideEffects) {
+        lines.push(
+          `- **${effect.type}**: ${effect.description} ${provenanceBadge(effect.provenance)}`
+        );
+      }
+      lines.push("");
+    }
+  }
+  if (ir.inputs?.parameters?.length) {
+    lines.push("## Inputs");
+    lines.push("");
+    lines.push(provenanceBadge(ir.inputs.provenance));
+    lines.push("");
+    lines.push(renderParameterTable(ir.inputs.parameters));
+    lines.push("");
+  }
+  if (ir.outputs?.parameters?.length) {
+    lines.push("## Outputs");
+    lines.push("");
+    lines.push(provenanceBadge(ir.outputs.provenance));
+    lines.push("");
+    lines.push(renderParameterTable(ir.outputs.parameters));
+    lines.push("");
+  }
+  if (ir.constraints) {
+    lines.push("## Constraints");
+    lines.push("");
+    if (ir.constraints.capabilities?.length) {
+      lines.push("### Capabilities");
+      lines.push("");
+      for (const cap of ir.constraints.capabilities) {
+        const values = cap.values?.join(", ") ?? "enabled";
+        lines.push(`- **${cap.type}**: ${values} ${provenanceBadge(cap.provenance)}`);
+      }
+      lines.push("");
+    }
+    if (ir.constraints.timeoutMs) {
+      lines.push(`**Timeout:** ${ir.constraints.timeoutMs}ms`);
+      lines.push("");
+    }
+    if (ir.constraints.resourceLimits) {
+      lines.push("### Resource Limits");
+      lines.push("");
+      if (ir.constraints.resourceLimits.memoryMb) {
+        lines.push(`- Memory: ${ir.constraints.resourceLimits.memoryMb} MB`);
+      }
+      if (ir.constraints.resourceLimits.cpuCores) {
+        lines.push(`- CPU: ${ir.constraints.resourceLimits.cpuCores} cores`);
+      }
+      lines.push("");
+    }
+  }
+  if (ir.errors?.length) {
+    lines.push("## Errors");
+    lines.push("");
+    lines.push("| Code | Description | Recovery |");
+    lines.push("|------|-------------|----------|");
+    for (const err of ir.errors) {
+      lines.push(`| \`${err.code}\` | ${err.description ?? ""} | ${err.recovery ?? ""} |`);
+    }
+    lines.push("");
+  }
+  if (ir.lifecycle?.deprecation) {
+    lines.push("## Lifecycle");
+    lines.push("");
+    lines.push("> [!WARNING]");
+    lines.push(`> This tool is deprecated as of ${ir.lifecycle.deprecation.deprecatedAt}.`);
+    lines.push(`> Sunset date: ${ir.lifecycle.deprecation.sunsetDate}`);
+    if (ir.lifecycle.deprecation.migrationUrl) {
+      lines.push(`> Migration guide: ${ir.lifecycle.deprecation.migrationUrl}`);
+    }
+    lines.push("");
+  }
+  if (ir.narrative?.examples?.length) {
+    lines.push("## Examples");
+    lines.push("");
+    for (const example of ir.narrative.examples) {
+      if (example.title) {
+        lines.push(`### ${example.title}`);
+        lines.push("");
+      }
+      if (example.description) {
+        lines.push(example.description);
+        lines.push("");
+      }
+      if (example.input) {
+        lines.push("**Input:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(example.input, null, 2));
+        lines.push("```");
+        lines.push("");
+      }
+      if (example.output) {
+        lines.push("**Output:**");
+        lines.push("```json");
+        lines.push(JSON.stringify(example.output, null, 2));
+        lines.push("```");
+        lines.push("");
+      }
+    }
+  }
+  if (ir.narrative?.notes?.length) {
+    lines.push("## Notes");
+    lines.push("");
+    lines.push("*[author notes]*");
+    lines.push("");
+    for (const note of ir.narrative.notes) {
+      lines.push(note);
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(`*Generated at ${ir.generatedAt}*  `);
+  lines.push(`*Determinism key: \`${ir.determinismKey}\`*`);
+  return lines.join("\n");
+}
+function renderParameterTable(params) {
+  const lines = [];
+  lines.push("| Name | Type | Required | Default | Description |");
+  lines.push("|------|------|----------|---------|-------------|");
+  for (const param of params) {
+    const required = param.required ? "\u2713" : "";
+    const defaultVal = param.default !== void 0 ? `\`${JSON.stringify(param.default)}\`` : "";
+    const desc = param.description ?? "";
+    lines.push(`| \`${param.name}\` | \`${param.type}\` | ${required} | ${defaultVal} | ${desc} |`);
+  }
+  return lines.join("\n");
+}
+function provenanceBadge(source) {
+  if (!source) return "";
+  const badges = {
+    introspection: "`[from introspection]`",
+    manifest: "`[from schema]`",
+    overlay: "`[from overlay]`",
+    narrative: "`[author notes]`"
+  };
+  return badges[source] ?? "";
+}
+
+// src/core/renderer/htmlRenderer.ts
+import { marked } from "marked";
+function renderHTML(ir) {
+  const markdown = renderMarkdown(ir);
+  const htmlContent = marked.parse(markdown);
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="description" content="${escapeHtml(ir.entity.description ?? `Documentation for ${ir.entity.id}`)}">
+  <title>${escapeHtml(ir.entity.id)} - odd-docs</title>
+  <style>
+${getThemeStyles()}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <nav class="breadcrumb">
+        <a href="index.html">Home</a> / <span>${escapeHtml(ir.entity.id)}</span>
+      </nav>
+    </header>
+    <main class="content">
+${htmlContent}
+    </main>
+    <footer>
+      <p class="meta">
+        Generated by <a href="https://github.com/oddessentials/odd-docs">odd-docs</a> at ${ir.generatedAt}
+      </p>
+      <p class="determinism">
+        <code>${ir.determinismKey}</code>
+      </p>
+    </footer>
+  </div>
+  <script>
+${getThemeScript()}
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function getThemeStyles() {
+  return `
+    /* CSS Variables for theming */
+    :root {
+      /* Colors - neutral palette */
+      --color-bg: #ffffff;
+      --color-bg-secondary: #f8f9fa;
+      --color-text: #1a1a2e;
+      --color-text-muted: #6c757d;
+      --color-border: #dee2e6;
+      --color-link: #0066cc;
+      --color-link-hover: #004499;
+      --color-accent: #0066cc;
+      --color-success: #28a745;
+      --color-warning: #ffc107;
+      --color-error: #dc3545;
+      
+      /* Typography */
+      --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+      --font-mono: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+      --font-size-base: 16px;
+      --line-height: 1.6;
+      
+      /* Spacing */
+      --space-xs: 0.25rem;
+      --space-sm: 0.5rem;
+      --space-md: 1rem;
+      --space-lg: 1.5rem;
+      --space-xl: 2rem;
+      
+      /* Layout */
+      --max-width: 800px;
+      --border-radius: 4px;
+    }
+    
+    [data-theme="dark"] {
+      --color-bg: #1a1a2e;
+      --color-bg-secondary: #16213e;
+      --color-text: #e8e8e8;
+      --color-text-muted: #a0a0a0;
+      --color-border: #3a3a5e;
+      --color-link: #66b3ff;
+      --color-link-hover: #99ccff;
+    }
+    
+    /* Reset */
+    *, *::before, *::after {
+      box-sizing: border-box;
+    }
+    
+    body {
+      margin: 0;
+      padding: 0;
+      font-family: var(--font-sans);
+      font-size: var(--font-size-base);
+      line-height: var(--line-height);
+      color: var(--color-text);
+      background: var(--color-bg);
+    }
+    
+    /* Container */
+    .container {
+      max-width: var(--max-width);
+      margin: 0 auto;
+      padding: var(--space-lg);
+    }
+    
+    /* Typography */
+    h1, h2, h3, h4, h5, h6 {
+      margin-top: var(--space-xl);
+      margin-bottom: var(--space-md);
+      line-height: 1.3;
+    }
+    
+    h1 { font-size: 2rem; }
+    h2 { font-size: 1.5rem; border-bottom: 1px solid var(--color-border); padding-bottom: var(--space-sm); }
+    h3 { font-size: 1.25rem; }
+    
+    p { margin: var(--space-md) 0; }
+    
+    a {
+      color: var(--color-link);
+      text-decoration: none;
+    }
+    
+    a:hover {
+      color: var(--color-link-hover);
+      text-decoration: underline;
+    }
+    
+    /* Code */
+    code {
+      font-family: var(--font-mono);
+      font-size: 0.9em;
+      background: var(--color-bg-secondary);
+      padding: var(--space-xs) var(--space-sm);
+      border-radius: var(--border-radius);
+    }
+    
+    pre {
+      background: var(--color-bg-secondary);
+      padding: var(--space-md);
+      border-radius: var(--border-radius);
+      overflow-x: auto;
+    }
+    
+    pre code {
+      background: none;
+      padding: 0;
+    }
+    
+    /* Tables */
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: var(--space-md) 0;
+    }
+    
+    th, td {
+      padding: var(--space-sm) var(--space-md);
+      border: 1px solid var(--color-border);
+      text-align: left;
+    }
+    
+    th {
+      background: var(--color-bg-secondary);
+      font-weight: 600;
+    }
+    
+    /* Provenance badges */
+    code[class*="from"] {
+      font-size: 0.75em;
+      color: var(--color-text-muted);
+      background: transparent;
+    }
+    
+    /* Blockquotes (for warnings/notes) */
+    blockquote {
+      margin: var(--space-md) 0;
+      padding: var(--space-md);
+      border-left: 4px solid var(--color-warning);
+      background: var(--color-bg-secondary);
+    }
+    
+    blockquote p:first-child { margin-top: 0; }
+    blockquote p:last-child { margin-bottom: 0; }
+    
+    /* Lists */
+    ul, ol {
+      padding-left: var(--space-lg);
+    }
+    
+    li { margin: var(--space-sm) 0; }
+    
+    /* Doc list (index page) */
+    .doc-list {
+      list-style: none;
+      padding: 0;
+    }
+    
+    .doc-list li {
+      padding: var(--space-md);
+      border: 1px solid var(--color-border);
+      border-radius: var(--border-radius);
+      margin-bottom: var(--space-md);
+    }
+    
+    .doc-list a {
+      display: flex;
+      align-items: center;
+      gap: var(--space-sm);
+    }
+    
+    .doc-list .version {
+      color: var(--color-text-muted);
+      font-size: 0.875em;
+    }
+    
+    .doc-list p {
+      margin: var(--space-sm) 0 0;
+      color: var(--color-text-muted);
+    }
+    
+    /* Header */
+    header {
+      margin-bottom: var(--space-lg);
+    }
+    
+    .breadcrumb {
+      font-size: 0.875em;
+      color: var(--color-text-muted);
+    }
+    
+    .breadcrumb a {
+      color: inherit;
+    }
+    
+    /* Footer */
+    footer {
+      margin-top: var(--space-xl);
+      padding-top: var(--space-lg);
+      border-top: 1px solid var(--color-border);
+      font-size: 0.875em;
+      color: var(--color-text-muted);
+    }
+    
+    .determinism code {
+      font-size: 0.75em;
+    }
+    
+    /* Theme toggle */
+    .theme-toggle {
+      position: fixed;
+      top: var(--space-md);
+      right: var(--space-md);
+      padding: var(--space-sm) var(--space-md);
+      border: 1px solid var(--color-border);
+      border-radius: var(--border-radius);
+      background: var(--color-bg);
+      cursor: pointer;
+      font-size: 0.875em;
+    }
+    
+    /* Responsive */
+    @media (max-width: 600px) {
+      .container { padding: var(--space-md); }
+      h1 { font-size: 1.5rem; }
+      h2 { font-size: 1.25rem; }
+      table { font-size: 0.875em; }
+    }
+  `;
+}
+function getThemeScript() {
+  return `
+    // Theme toggle
+    const toggle = document.createElement('button');
+    toggle.className = 'theme-toggle';
+    toggle.textContent = '\u{1F319}';
+    toggle.onclick = () => {
+      const html = document.documentElement;
+      const isDark = html.dataset.theme === 'dark';
+      html.dataset.theme = isDark ? 'light' : 'dark';
+      toggle.textContent = isDark ? '\u{1F319}' : '\u2600\uFE0F';
+      localStorage.setItem('theme', html.dataset.theme);
+    };
+    document.body.appendChild(toggle);
+    
+    // Restore saved theme
+    const saved = localStorage.getItem('theme');
+    if (saved) {
+      document.documentElement.dataset.theme = saved;
+      toggle.textContent = saved === 'dark' ? '\u2600\uFE0F' : '\u{1F319}';
+    } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      document.documentElement.dataset.theme = 'dark';
+      toggle.textContent = '\u2600\uFE0F';
+    }
+  `;
+}
+
+// src/cli/commands/generate.ts
+async function generate(repoPath, options = {}) {
+  const absPath = resolve(repoPath);
+  const format = options.format ?? "md";
+  const outputDir = options.output ? resolve(options.output) : join2(absPath, "docs", "generated");
+  console.log(`Generating documentation for: ${absPath}`);
+  const manifestResult = await parseManifest(absPath);
+  console.log(`  Entity: ${manifestResult.entity.id}@${manifestResult.entity.version}`);
+  const ir = buildDocIR(manifestResult);
+  console.log(`  Determinism key: ${ir.determinismKey}`);
+  await mkdir(outputDir, { recursive: true });
+  if (format === "md" || format === "both") {
+    const markdown = renderMarkdown(ir);
+    const mdPath = join2(outputDir, `${ir.entity.id}.md`);
+    await writeFile(mdPath, markdown, "utf-8");
+    console.log(`  \u2713 Markdown: ${mdPath}`);
+  }
+  if (format === "html" || format === "both") {
+    const html = renderHTML(ir);
+    const htmlPath = join2(outputDir, `${ir.entity.id}.html`);
+    await writeFile(htmlPath, html, "utf-8");
+    console.log(`  \u2713 HTML: ${htmlPath}`);
+  }
+  const irPath = join2(outputDir, `${ir.entity.id}.ir.json`);
+  await writeFile(irPath, JSON.stringify(ir, null, 2), "utf-8");
+  console.log(`  \u2713 Doc IR: ${irPath}`);
+  console.log("Done!");
+}
+
+// src/cli/commands/validate.ts
+import { resolve as resolve2 } from "path";
+
+// src/core/capabilities.ts
+var KNOWN_CAPABILITIES = [
+  "network",
+  "filesystem",
+  "secrets",
+  "exec",
+  "subprocess",
+  "database",
+  "queue"
+];
+var SAFETY_AFFECTING_PATTERNS = ["network", "exec", "subprocess", "write", "delete"];
+function isKnownCapability(capability) {
+  return KNOWN_CAPABILITIES.includes(capability);
+}
+function isSafetyAffecting(capability) {
+  return SAFETY_AFFECTING_PATTERNS.some(
+    (pattern) => capability.toLowerCase().includes(pattern.toLowerCase())
+  );
+}
+
+// src/core/ir/validator.ts
+function validateDocIR(ir, options = {}) {
+  const issues = [];
+  if (!ir.entity.id) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_TOOL_ID",
+      message: "Tool ID is required",
+      path: "entity.id"
+    });
+  }
+  if (!ir.entity.version) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_VERSION",
+      message: "Version is required",
+      path: "entity.version"
+    });
+  }
+  if (!ir.inputs?.schema && !ir.inputs?.parameters?.length) {
+    issues.push({
+      severity: "error",
+      code: "MISSING_PARAMETERS_SCHEMA",
+      message: "Parameters schema is required",
+      path: "inputs"
+    });
+  }
+  if (ir.constraints?.capabilities) {
+    for (const cap of ir.constraints.capabilities) {
+      if (!isKnownCapability(cap.type)) {
+        const isSafety = isSafetyAffecting(cap.type);
+        issues.push({
+          severity: options.strict && isSafety ? "error" : "warning",
+          code: "UNKNOWN_CAPABILITY",
+          message: `Unknown capability: ${cap.type}${isSafety ? " (safety-affecting)" : ""}`,
+          path: `constraints.capabilities.${cap.type}`,
+          provenance: cap.provenance
+        });
+      }
+    }
+  }
+  issues.push(...checkStructuralContradictions(ir));
+  const hasErrors = issues.some((i) => i.severity === "error");
+  return {
+    valid: !hasErrors,
+    issues
+  };
+}
+function checkStructuralContradictions(ir) {
+  const issues = [];
+  if (ir.narrative?.notes && ir.inputs?.parameters) {
+    const schemaParams = new Set(ir.inputs.parameters.map((p) => p.name.toLowerCase()));
+    for (const note of ir.narrative.notes) {
+      const paramMentions = note.match(/(?:parameter|param)\s+[`"']?(\w+)[`"']?/gi) ?? [];
+      const theParamMentions = note.match(/the\s+[`"']?(\w+)[`"']?\s+parameter/gi) ?? [];
+      for (const match of [...paramMentions, ...theParamMentions]) {
+        const paramName = match.replace(/.*?[`"']?(\w+)[`"']?.*/i, "$1").toLowerCase();
+        if (paramName && !schemaParams.has(paramName) && paramName !== "parameter") {
+          issues.push({
+            severity: "error",
+            code: "NARRATIVE_REFERENCES_UNDEFINED_PARAM",
+            message: `Narrative references parameter "${paramName}" not in schema`,
+            path: "narrative.notes",
+            provenance: "narrative"
+          });
+        }
+      }
+    }
+  }
+  if (ir.narrative?.examples && ir.inputs?.parameters) {
+    const schemaParams = new Set(ir.inputs.parameters.map((p) => p.name));
+    for (const example of ir.narrative.examples) {
+      if (example.input && typeof example.input === "object") {
+        for (const key of Object.keys(example.input)) {
+          if (!schemaParams.has(key)) {
+            issues.push({
+              severity: "warning",
+              code: "EXAMPLE_USES_UNDEFINED_PARAM",
+              message: `Example uses parameter "${key}" not in schema`,
+              path: `narrative.examples.${example.title ?? "unnamed"}`,
+              provenance: "narrative"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (ir.overview?.sideEffects && ir.constraints?.capabilities) {
+    const capTypes = new Set(ir.constraints.capabilities.map((c) => c.type));
+    for (const effect of ir.overview.sideEffects) {
+      const expectedCap = mapSideEffectToCapability(effect.type);
+      if (expectedCap && !capTypes.has(expectedCap)) {
+        issues.push({
+          severity: "error",
+          code: "SIDE_EFFECT_CAPABILITY_MISMATCH",
+          message: `Side effect "${effect.type}" requires capability "${expectedCap}" which is not declared`,
+          path: `overview.sideEffects.${effect.type}`,
+          provenance: effect.provenance
+        });
+      }
+    }
+  }
+  return issues;
+}
+function mapSideEffectToCapability(effectType) {
+  const mapping = {
+    filesystem: "filesystem",
+    network: "network",
+    secrets: "secrets",
+    exec: "exec",
+    subprocess: "subprocess",
+    database: "database",
+    queue: "queue"
+  };
+  return mapping[effectType] ?? null;
+}
+function formatValidationResult(result, repoPath) {
+  const lines = [];
+  lines.push(`Validating: ${repoPath}`);
+  lines.push("");
+  if (result.valid) {
+    lines.push("\u2713 Validation passed");
+  } else {
+    lines.push("\u2717 Validation failed");
+  }
+  lines.push("");
+  const errors = result.issues.filter((i) => i.severity === "error");
+  const warnings = result.issues.filter((i) => i.severity === "warning");
+  if (errors.length > 0) {
+    lines.push(`Errors (${errors.length}):`);
+    for (const issue of errors) {
+      lines.push(`  \u2717 [${issue.code}] ${issue.message}`);
+      if (issue.path) {
+        lines.push(`    at ${issue.path}`);
+      }
+    }
+    lines.push("");
+  }
+  if (warnings.length > 0) {
+    lines.push(`Warnings (${warnings.length}):`);
+    for (const issue of warnings) {
+      lines.push(`  \u26A0 [${issue.code}] ${issue.message}`);
+      if (issue.path) {
+        lines.push(`    at ${issue.path}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/cli/commands/validate.ts
+async function validate(repoPath, options = {}) {
+  const absPath = resolve2(repoPath);
+  console.log(`Validating: ${absPath}`);
+  console.log(`Mode: ${options.strict ? "strict" : "normal"}`);
+  console.log("");
+  try {
+    const manifestResult = await parseManifest(absPath);
+    const ir = buildDocIR(manifestResult);
+    const result = validateDocIR(ir, { strict: options.strict });
+    console.log(formatValidationResult(result, absPath));
+    return result.valid;
+  } catch (error) {
+    console.error("\u2717 Validation failed");
+    console.error("");
+    console.error(`Error: ${error instanceof Error ? error.message : error}`);
+    return false;
+  }
+}
+
+// src/cli/commands/serve.ts
+import { existsSync } from "fs";
+import { join as join4, resolve as resolve3 } from "path";
+
+// src/server/index.ts
+import { createServer } from "http";
+
+// src/server/fileServer.ts
+import { createReadStream, statSync } from "fs";
+import { realpath } from "fs/promises";
+import { join as join3, extname, relative, isAbsolute } from "path";
+import { createHash as createHash2 } from "crypto";
+var MAX_RESPONSE_SIZE = 50 * 1024 * 1024;
+var MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf"
+};
+var FileServer = class {
+  rootDir;
+  resolvedRoot = null;
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  async serve(req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    let pathname = decodeURIComponent(url.pathname);
+    if (pathname === "/" || pathname.endsWith("/")) {
+      pathname = join3(pathname, "index.html");
+    }
+    const filePath = await this.resolvePath(pathname);
+    if (!filePath) {
+      res.statusCode = 403;
+      res.end("Forbidden: Path traversal blocked");
+      return;
+    }
+    let stats;
+    try {
+      stats = statSync(filePath);
+    } catch {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    if (!stats.isFile()) {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    if (stats.size > MAX_RESPONSE_SIZE) {
+      res.statusCode = 413;
+      res.end("File too large");
+      return;
+    }
+    const etag = this.computeETag(filePath, stats.mtime, stats.size);
+    const ifNoneMatch = req.headers["if-none-match"];
+    if (ifNoneMatch === etag) {
+      res.statusCode = 304;
+      res.end();
+      return;
+    }
+    const ext = extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+    res.setHeader("Content-Type", contentType);
+    res.setHeader("Content-Length", stats.size);
+    res.setHeader("ETag", etag);
+    res.setHeader("Cache-Control", "no-cache");
+    const stream = createReadStream(filePath);
+    stream.pipe(res);
+    stream.on("error", () => {
+      res.statusCode = 500;
+      res.end("Error reading file");
+    });
+  }
+  /**
+   * Resolve path with traversal protection
+   */
+  async resolvePath(pathname) {
+    if (!this.resolvedRoot) {
+      try {
+        this.resolvedRoot = await realpath(this.rootDir);
+      } catch {
+        return null;
+      }
+    }
+    const targetPath = join3(this.rootDir, pathname);
+    let resolvedTarget;
+    try {
+      resolvedTarget = await realpath(targetPath);
+    } catch {
+      return null;
+    }
+    const rel = relative(this.resolvedRoot, resolvedTarget);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      console.warn(`[odd-docs] Path traversal blocked: ${pathname}`);
+      return null;
+    }
+    return resolvedTarget;
+  }
+  computeETag(path, mtime, size) {
+    const hash = createHash2("md5").update(`${path}:${mtime.getTime()}:${size}`).digest("hex").slice(0, 16);
+    return `"${hash}"`;
+  }
+};
+
+// src/server/livereload.ts
+import { watch } from "fs";
+var LiveReload = class {
+  options;
+  watcher = null;
+  sseClients = /* @__PURE__ */ new Set();
+  lastChangeTime = Date.now();
+  debounceTimer = null;
+  constructor(options) {
+    this.options = {
+      pollInterval: 5e3,
+      ...options
+    };
+  }
+  async start() {
+    const usePolling = process.env.CHOKIDAR_USEPOLLING === "1" || this.options.mode === "poll";
+    this.watcher = watch(
+      this.options.outputDir,
+      { recursive: true, persistent: true },
+      (_eventType, filename) => {
+        if (filename) {
+          this.onFileChange(filename);
+        }
+      }
+    );
+    if (usePolling) {
+      console.log("[odd-docs] Using poll-based file watching");
+    }
+    console.log(`[odd-docs] Live reload started (mode: ${this.options.mode})`);
+  }
+  async stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    if (this.watcher) {
+      this.watcher.close();
+    }
+    for (const client of this.sseClients) {
+      client.end();
+    }
+    this.sseClients.clear();
+  }
+  onFileChange(filename) {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.lastChangeTime = Date.now();
+      console.log(`[odd-docs] Change detected: ${filename}`);
+      this.notifyClients();
+    }, 100);
+  }
+  notifyClients() {
+    const message = JSON.stringify({ type: "reload", time: this.lastChangeTime });
+    for (const client of this.sseClients) {
+      client.write(`data: ${message}
+
+`);
+    }
+  }
+  async handleRequest(req, res) {
+    const mode = this.options.mode;
+    if (mode === "sse") {
+      res.setHeader("Content-Type", "text/event-stream");
+      res.setHeader("Cache-Control", "no-cache");
+      res.setHeader("Connection", "keep-alive");
+      res.setHeader("X-Accel-Buffering", "no");
+      res.write(": ping\n\n");
+      this.sseClients.add(res);
+      req.on("close", () => {
+        this.sseClients.delete(res);
+      });
+    } else if (mode === "poll") {
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ lastChange: this.lastChangeTime }));
+    } else {
+      res.statusCode = 404;
+      res.end("Live reload not available in this mode");
+    }
+  }
+  /**
+   * Get client-side script for live reload
+   */
+  static getClientScript(mode, pollInterval = 5e3) {
+    if (mode === "none") return "";
+    if (mode === "sse") {
+      return `
+<script>
+(function() {
+  const es = new EventSource('/__livereload');
+  es.onmessage = function(e) {
+    const data = JSON.parse(e.data);
+    if (data.type === 'reload') {
+      console.log('[odd-docs] Reloading...');
+      location.reload();
+    }
+  };
+  es.onerror = function() {
+    console.log('[odd-docs] SSE connection lost, will retry...');
+  };
+})();
+</script>`;
+    }
+    if (mode === "poll") {
+      return `
+<script>
+(function() {
+  let lastChange = 0;
+  setInterval(async () => {
+    try {
+      const res = await fetch('/__livereload');
+      const data = await res.json();
+      if (lastChange && data.lastChange > lastChange) {
+        console.log('[odd-docs] Reloading...');
+        location.reload();
+      }
+      lastChange = data.lastChange;
+    } catch (e) {}
+  }, ${pollInterval});
+})();
+</script>`;
+    }
+    return `
+<script>
+(function() {
+  const ws = new WebSocket('ws://' + location.host + '/__ws');
+  ws.onmessage = function(e) {
+    const data = JSON.parse(e.data);
+    if (data.type === 'reload') {
+      console.log('[odd-docs] Reloading...');
+      location.reload();
+    }
+  };
+  ws.onclose = function() {
+    console.log('[odd-docs] WebSocket closed, will retry in 3s...');
+    setTimeout(() => location.reload(), 3000);
+  };
+})();
+</script>`;
+  }
+};
+
+// src/server/api.ts
+var MAX_IR_SIZE = 10 * 1024 * 1024;
+var ApiHandler = class {
+  state;
+  options;
+  constructor(state, options) {
+    this.state = state;
+    this.options = options;
+  }
+  async handle(req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    switch (path) {
+      case "/api/health":
+        return this.handleHealth(res);
+      case "/api/ready":
+        return this.handleReady(res);
+      case "/api/introspection":
+        return this.handleIntrospection(res);
+      case "/api/docs":
+        return this.handleDocs(res);
+      case "/api/ir":
+        return this.handleIR(res);
+      case "/api/capabilities":
+        return this.handleCapabilities(res);
+      case "/api/regenerate":
+        if (method === "POST") {
+          return this.handleRegenerate(req, res);
+        }
+        return this.methodNotAllowed(res);
+      default:
+        return this.notFound(res);
+    }
+  }
+  /**
+   * GET /api/health - Liveness probe
+   * Returns 200 if process is running
+   */
+  handleHealth(res) {
+    this.json(res, {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /**
+   * GET /api/ready - Readiness probe
+   * Returns 200 if last generate succeeded and output is accessible
+   */
+  handleReady(res) {
+    const ready = this.state.lastGenerateSuccess && this.state.outputDirAccessible;
+    if (!ready) {
+      res.statusCode = 503;
+    }
+    this.json(res, {
+      ready,
+      lastGenerateSuccess: this.state.lastGenerateSuccess,
+      lastGenerateTime: this.state.lastGenerateTime,
+      outputDirAccessible: this.state.outputDirAccessible
+    });
+  }
+  /**
+   * GET /api/introspection - Introspection status
+   */
+  handleIntrospection(res) {
+    this.json(res, {
+      connected: this.state.introspectionConnected,
+      lastPollTime: this.state.lastIntrospectionTime ?? null
+    });
+  }
+  /**
+   * GET /api/docs - List documentation sections
+   */
+  handleDocs(res) {
+    this.json(res, {
+      sections: [],
+      message: "Not implemented yet"
+    });
+  }
+  /**
+   * GET /api/ir - Full IR dump (capped at 10MB)
+   */
+  handleIR(res) {
+    const ir = { tools: [], prompts: [], resources: [] };
+    const irJson = JSON.stringify(ir);
+    if (irJson.length > MAX_IR_SIZE) {
+      this.json(res, {
+        truncated: true,
+        message: `IR exceeds ${MAX_IR_SIZE / 1024 / 1024}MB limit`,
+        partial: null
+      });
+      return;
+    }
+    res.setHeader("Content-Type", "application/json");
+    res.end(irJson);
+  }
+  /**
+   * GET /api/capabilities - Tool capabilities summary
+   */
+  handleCapabilities(res) {
+    this.json(res, {
+      serve: {
+        host: this.options.host,
+        port: this.options.port,
+        reloadMode: this.options.reloadMode,
+        mutationsEnabled: this.options.enableMutations
+      }
+    });
+  }
+  /**
+   * POST /api/regenerate - Trigger manual regeneration
+   * Requires --enable-mutations and valid token
+   */
+  handleRegenerate(req, res) {
+    if (!this.options.enableMutations) {
+      res.statusCode = 403;
+      this.json(res, {
+        error: "Mutations disabled",
+        message: "Start server with --enable-mutations to use this endpoint"
+      });
+      return;
+    }
+    const token = req.headers["x-mutation-token"];
+    if (token !== this.options.mutationToken) {
+      res.statusCode = 401;
+      this.json(res, {
+        error: "Unauthorized",
+        message: "Invalid or missing X-Mutation-Token header"
+      });
+      return;
+    }
+    this.json(res, {
+      status: "queued",
+      message: "Regeneration triggered",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  json(res, data) {
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(data, null, 2));
+  }
+  notFound(res) {
+    res.statusCode = 404;
+    this.json(res, { error: "Not Found" });
+  }
+  methodNotAllowed(res) {
+    res.statusCode = 405;
+    this.json(res, { error: "Method Not Allowed" });
+  }
+};
+
+// src/server/index.ts
+var DEFAULT_OPTIONS = {
+  port: 3e3,
+  host: "localhost",
+  watch: true,
+  reloadMode: "ws",
+  enableMutations: false,
+  requestTimeout: 3e4
+};
+var OddDocsServer = class {
+  server = null;
+  fileServer;
+  liveReload = null;
+  apiHandler;
+  options;
+  state;
+  constructor(options) {
+    this.options = {
+      ...DEFAULT_OPTIONS,
+      ...options,
+      // Auto-switch to SSE for non-localhost binding (safer for K8s)
+      reloadMode: options.reloadMode ?? (options.host && options.host !== "localhost" ? "sse" : DEFAULT_OPTIONS.reloadMode)
+    };
+    this.options.host = process.env.ODD_DOCS_HOST ?? this.options.host;
+    this.options.port = parseInt(process.env.ODD_DOCS_PORT ?? String(this.options.port), 10);
+    this.options.mutationToken = process.env.ODD_DOCS_MUTATION_TOKEN ?? this.options.mutationToken;
+    this.state = {
+      lastGenerateSuccess: true,
+      lastGenerateTime: (/* @__PURE__ */ new Date()).toISOString(),
+      outputDirAccessible: true,
+      introspectionConnected: false
+    };
+    this.fileServer = new FileServer(this.options.outputDir);
+    this.apiHandler = new ApiHandler(this.state, this.options);
+  }
+  async start() {
+    if (this.options.enableMutations && !this.options.mutationToken) {
+      throw new Error(
+        "Mutation token required when --enable-mutations is set. Set ODD_DOCS_MUTATION_TOKEN or --mutation-token"
+      );
+    }
+    this.server = createServer((req, res) => this.handleRequest(req, res));
+    this.server.timeout = this.options.requestTimeout;
+    if (this.options.watch && this.options.reloadMode !== "none") {
+      this.liveReload = new LiveReload({
+        outputDir: this.options.outputDir,
+        mode: this.options.reloadMode,
+        server: this.server
+      });
+      await this.liveReload.start();
+    }
+    return new Promise((resolve4, reject) => {
+      this.server.listen(this.options.port, this.options.host, () => {
+        console.log(
+          `[odd-docs] Server started at http://${this.options.host}:${this.options.port}`
+        );
+        console.log(`[odd-docs] Serving: ${this.options.outputDir}`);
+        if (this.liveReload) {
+          console.log(`[odd-docs] Live reload: ${this.options.reloadMode}`);
+        }
+        resolve4();
+      });
+      this.server.on("error", reject);
+    });
+  }
+  async stop() {
+    if (this.liveReload) {
+      await this.liveReload.stop();
+    }
+    if (this.server) {
+      return new Promise((resolve4) => {
+        this.server.close(() => resolve4());
+      });
+    }
+  }
+  async handleRequest(req, res) {
+    const url = req.url ?? "/";
+    try {
+      if (url.startsWith("/api/")) {
+        await this.apiHandler.handle(req, res);
+        return;
+      }
+      if (this.liveReload && url === "/__livereload") {
+        await this.liveReload.handleRequest(req, res);
+        return;
+      }
+      await this.fileServer.serve(req, res);
+    } catch (error) {
+      console.error("[odd-docs] Request error:", error);
+      res.statusCode = 500;
+      res.end("Internal Server Error");
+    }
+  }
+  updateState(updates) {
+    Object.assign(this.state, updates);
+  }
+};
+
+// src/cli/commands/serve.ts
+async function serve(repoPath, options = {}) {
+  const resolvedPath = resolve3(repoPath);
+  const outputDir = options.output ? resolve3(options.output) : join4(resolvedPath, "docs", "generated");
+  if (!existsSync(outputDir)) {
+    console.log("[odd-docs] Documentation not found, generating...");
+    await generate(repoPath, { output: outputDir, format: "html" });
+  }
+  let reloadMode = options.reload ?? "ws";
+  if (options.watchMode === "poll" || process.env.CHOKIDAR_USEPOLLING === "1") {
+    reloadMode = "poll";
+    console.log("[odd-docs] Using poll-based watching (CPU intensive)");
+  }
+  const host = options.host ?? "localhost";
+  const port = options.port ?? 3e3;
+  if (host !== "localhost" && options.reload === void 0) {
+    reloadMode = "sse";
+    console.log("[odd-docs] Using SSE for non-localhost binding");
+  }
+  const serverOptions = {
+    outputDir,
+    host,
+    port,
+    watch: options.watch !== false,
+    reloadMode,
+    enableMutations: options.enableMutations ?? false,
+    mutationToken: options.mutationToken
+  };
+  const server = new OddDocsServer(serverOptions);
+  const shutdown = async () => {
+    console.log("\n[odd-docs] Shutting down...");
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  try {
+    await server.start();
+    if (options.open !== false && host === "localhost") {
+      const url = `http://${host}:${port}`;
+      try {
+        const { default: open } = await import("open");
+        await open(url);
+      } catch {
+        console.log(`[odd-docs] Open browser manually: ${url}`);
+      }
+    }
+  } catch (error) {
+    console.error("[odd-docs] Failed to start server:", error);
+    process.exit(1);
+  }
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("odd-docs").description("MCP-native documentation generator").version("0.1.0");
+program.command("generate").description("Generate documentation for an MCP repo").argument("<repo-path>", "Path to the repository").option("-f, --format <format>", "Output format: md, html, or both", "md").option("-o, --output <dir>", "Output directory").option("--introspect <url>", "MCP server URL for live introspection").action(async (repoPath, options) => {
+  try {
+    await generate(repoPath, {
+      format: options.format,
+      output: options.output,
+      introspect: options.introspect
+    });
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+});
+program.command("validate").description("Validate documentation inputs for an MCP repo").argument("<repo-path>", "Path to the repository").option("-s, --strict", "Fail on unknown safety-affecting capabilities").action(async (repoPath, options) => {
+  try {
+    const valid = await validate(repoPath, { strict: options.strict });
+    process.exit(valid ? 0 : 1);
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+});
+program.command("serve").description("Start a local dev server for generated documentation").argument("<repo-path>", "Path to the repository").option("-p, --port <port>", "Port to listen on", "3000").option("-H, --host <host>", "Host to bind (default: localhost for safety)", "localhost").option("-o, --output <dir>", "Documentation output directory").option("--no-watch", "Disable file watching").option("--watch-mode <mode>", "Watch mode: auto or poll (use poll for Docker/NFS)", "auto").option("--reload <mode>", "Reload mechanism: ws, sse, poll, none", "ws").option("--no-open", "Do not open browser on start").option("--introspect <target>", "MCP target: http://host:port or stdio:<cmd>").option("--enable-mutations", "Enable mutation API endpoints (requires token)").option("--mutation-token <token>", "Token for mutation endpoints (or ODD_DOCS_MUTATION_TOKEN)").action(async (repoPath, options) => {
+  try {
+    await serve(repoPath, {
+      port: parseInt(options.port, 10),
+      host: options.host,
+      output: options.output,
+      watch: options.watch,
+      watchMode: options.watchMode,
+      reload: options.reload,
+      open: options.open,
+      introspect: options.introspect,
+      enableMutations: options.enableMutations,
+      mutationToken: options.mutationToken
+    });
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+});
+program.parse();
+//# sourceMappingURL=index.js.map