@syndicalt/snow-cli 1.0.0 → 1.1.0

package/dist/index.js

@@ -202,7 +202,7 @@ var init_client = __esm({
                   const retryAfterHeader = err.response?.headers["retry-after"];
                   const baseDelay = 1e3 * Math.pow(2, config._retryCount - 1);
                   const delayMs = retryAfterHeader ? Math.max(parseInt(String(retryAfterHeader), 10) * 1e3, baseDelay) : baseDelay;
-                  await new Promise((resolve) => setTimeout(resolve, delayMs));
+                  await new Promise((resolve2) => setTimeout(resolve2, delayMs));
                   return this.http.request(config);
                 }
                 const detail2 = err.response?.data?.error?.message ?? err.message;
@@ -663,82 +663,653 @@ init_client();
 import { Command as Command3 } from "commander";
 import chalk3 from "chalk";
 import ora2 from "ora";
-function schemaCommand() {
-  return new Command3("schema").description("Retrieve the field schema for a ServiceNow table").argument("<table>", "Table name (e.g. incident, sys_user)").option("--format <fmt>", "Output format: table or json", "table").option("-f, --filter <text>", "Filter fields by name or label (case-insensitive)").action(
-    async (table, opts) => {
-      const instance = requireActiveInstance();
-      const client = new ServiceNowClient(instance);
-      const spinner = ora2(`Loading schema for ${table}...`).start();
-      try {
-        const res = await client.get(
-          "/api/now/table/sys_dictionary",
-          {
-            params: {
-              sysparm_query: `name=${table}^elementISNOTEMPTY`,
-              sysparm_fields: "element,column_label,internal_type,max_length,mandatory,read_only,reference,default_value,comments",
-              sysparm_display_value: "all",
-              sysparm_limit: 500,
-              sysparm_exclude_reference_link: true
-            }
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2, resolve } from "path";
+
+// src/lib/llm.ts
+init_esm_shims();
+import axios2 from "axios";
+var OpenAIProvider = class {
+  constructor(apiKey, model, baseUrl = "https://api.openai.com/v1", name = "openai") {
+    this.apiKey = apiKey;
+    this.model = model;
+    this.baseUrl = baseUrl;
+    this.providerName = name;
+  }
+  providerName;
+  async complete(messages) {
+    const res = await axios2.post(
+      `${this.baseUrl.replace(/\/$/, "")}/chat/completions`,
+      { model: this.model, messages },
+      {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        timeout: 12e4
+      }
+    );
+    const content = res.data.choices[0]?.message.content;
+    if (!content) throw new Error("LLM returned an empty response");
+    return content;
+  }
+};
+var AnthropicProvider = class {
+  constructor(apiKey, model) {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+  providerName = "anthropic";
+  async complete(messages) {
+    const system = messages.find((m) => m.role === "system")?.content;
+    const conversation = messages.filter((m) => m.role !== "system");
+    const res = await axios2.post(
+      "https://api.anthropic.com/v1/messages",
+      {
+        model: this.model,
+        max_tokens: 8192,
+        ...system ? { system } : {},
+        messages: conversation
+      },
+      {
+        headers: {
+          "x-api-key": this.apiKey,
+          "anthropic-version": "2023-06-01",
+          "Content-Type": "application/json"
+        },
+        timeout: 12e4
+      }
+    );
+    const text = res.data.content.find((c) => c.type === "text")?.text;
+    if (!text) throw new Error("Anthropic returned an empty response");
+    return text;
+  }
+};
+var OllamaProvider = class {
+  constructor(model, baseUrl = "http://localhost:11434") {
+    this.model = model;
+    this.baseUrl = baseUrl;
+  }
+  providerName = "ollama";
+  async complete(messages) {
+    const res = await axios2.post(
+      `${this.baseUrl.replace(/\/$/, "")}/api/chat`,
+      { model: this.model, messages, stream: false },
+      { headers: { "Content-Type": "application/json" }, timeout: 3e5 }
+    );
+    const content = res.data.message.content;
+    if (!content) throw new Error("Ollama returned an empty response");
+    return content;
+  }
+};
+function buildProvider(name, model, apiKey, baseUrl) {
+  switch (name) {
+    case "anthropic":
+      if (!apiKey) throw new Error("Anthropic provider requires an API key (https://platform.claude.com/)");
+      return new AnthropicProvider(apiKey, model);
+    case "xai":
+      if (!apiKey) throw new Error("xAI provider requires an API key (https://platform.x.ai/)");
+      return new OpenAIProvider(
+        apiKey,
+        model,
+        baseUrl ?? "https://api.x.ai/v1",
+        "xai"
+      );
+    case "ollama":
+      return new OllamaProvider(model, baseUrl);
+    case "openai":
+    default:
+      if (!apiKey) throw new Error("OpenAI provider requires an API key (https://platform.openai.com/)");
+      return new OpenAIProvider(apiKey, model, baseUrl, name);
+  }
+}
+function extractJSON(raw) {
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenced) return fenced[1].trim();
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start !== -1 && end !== -1) return raw.slice(start, end + 1);
+  return raw.trim();
+}
+
+// src/commands/schema.ts
+async function fetchInboundReferences(client, tableName) {
+  const res = await client.get(
+    "/api/now/table/sys_dictionary",
+    {
+      params: {
+        sysparm_query: `internal_type=reference^reference=${tableName}^elementISNOTEMPTY`,
+        sysparm_fields: "name,element,column_label",
+        sysparm_display_value: "all",
+        sysparm_limit: 100,
+        sysparm_exclude_reference_link: true
+      }
+    }
+  );
+  return (res.result ?? []).map((e) => ({
+    refTable: e.name?.value ?? "",
+    fieldName: e.element?.value ?? "",
+    fieldLabel: e.column_label?.display_value ?? ""
+  })).filter((r) => r.refTable && r.fieldName);
+}
+async function fetchTableFields(client, tableName) {
+  const res = await client.get(
+    "/api/now/table/sys_dictionary",
+    {
+      params: {
+        sysparm_query: `name=${tableName}^elementISNOTEMPTY`,
+        sysparm_fields: "element,column_label,internal_type,max_length,mandatory,reference",
+        sysparm_display_value: "all",
+        sysparm_limit: 500,
+        sysparm_exclude_reference_link: true
+      }
+    }
+  );
+  return (res.result ?? []).map((e) => ({
+    name: e.element?.value ?? "",
+    label: e.column_label?.display_value ?? "",
+    type: e.internal_type?.value ?? "string",
+    maxLength: e.max_length?.value ? parseInt(e.max_length.value, 10) : void 0,
+    mandatory: e.mandatory?.value === "true",
+    reference: e.reference?.value || void 0
+  })).filter((f) => f.name);
+}
+async function fetchTableMeta(client, tableName) {
+  try {
+    const res = await client.get("/api/now/table/sys_db_object", {
+      params: {
+        sysparm_query: `name=${tableName}`,
+        sysparm_fields: "label,sys_scope",
+        sysparm_display_value: "all",
+        sysparm_limit: 1
+      }
+    });
+    if (res.result?.length > 0) {
+      return {
+        label: res.result[0].label?.display_value || tableName,
+        scope: res.result[0].sys_scope?.display_value || "Global"
+      };
+    }
+  } catch {
+  }
+  return { label: tableName, scope: "Global" };
+}
+async function crawlSchema(client, rootTable, maxDepth, showM2m, showInbound, onProgress) {
+  const tables = /* @__PURE__ */ new Map();
+  const edges = [];
+  const queue = [{ table: rootTable, depth: 0 }];
+  const visited = /* @__PURE__ */ new Set();
+  while (queue.length > 0) {
+    const { table, depth } = queue.shift();
+    if (visited.has(table)) continue;
+    visited.add(table);
+    onProgress(`  [depth ${depth}] ${table}`);
+    const [fields, { label, scope }] = await Promise.all([
+      fetchTableFields(client, table),
+      fetchTableMeta(client, table)
+    ]);
+    tables.set(table, { name: table, label, scope, fields });
+    if (depth < maxDepth) {
+      for (const field of fields) {
+        const isRef = field.type === "reference" && field.reference;
+        const isM2m = showM2m && field.type === "glide_list" && field.reference;
+        if (isRef || isM2m) {
+          const target = field.reference;
+          const alreadyEdge = edges.some((e) => e.from === table && e.field === field.name);
+          if (!alreadyEdge) {
+            edges.push({
+              from: table,
+              field: field.name,
+              fieldLabel: field.label,
+              to: target,
+              type: isRef ? "reference" : "glide_list"
+            });
+          }
+          if (!visited.has(target)) {
+            queue.push({ table: target, depth: depth + 1 });
           }
-        );
-        spinner.stop();
-        let entries = res.result ?? [];
-        if (opts.filter) {
-          const filterLower = opts.filter.toLowerCase();
-          entries = entries.filter(
-            (e) => e.element?.value?.toLowerCase().includes(filterLower) || e.column_label?.display_value?.toLowerCase().includes(filterLower)
-          );
         }
-        if (entries.length === 0) {
-          console.log(chalk3.dim(`No fields found for table "${table}".`));
-          return;
+      }
+      if (showInbound) {
+        const inbound = await fetchInboundReferences(client, table);
+        for (const { refTable, fieldName, fieldLabel } of inbound) {
+          const alreadyEdge = edges.some((e) => e.from === refTable && e.field === fieldName);
+          if (!alreadyEdge) {
+            edges.push({ from: refTable, field: fieldName, fieldLabel, to: table, type: "reference" });
+          }
+          if (!visited.has(refTable)) {
+            queue.push({ table: refTable, depth: depth + 1 });
+          }
         }
-        if (opts.format === "json") {
-          const mapped = entries.map((e) => ({
-            name: e.element?.value,
-            label: e.column_label?.display_value,
-            type: e.internal_type?.value,
-            maxLength: e.max_length?.value ? parseInt(e.max_length.value, 10) : void 0,
-            mandatory: e.mandatory?.value === "true",
-            readOnly: e.read_only?.value === "true",
-            reference: e.reference?.value || void 0,
-            defaultValue: e.default_value?.value || void 0,
-            comments: e.comments?.value || void 0
-          }));
-          console.log(JSON.stringify(mapped, null, 2));
-          return;
+      }
+    }
+  }
+  return { tables, edges, enums: /* @__PURE__ */ new Map() };
+}
+async function fetchChoiceValues(client, tableName, fieldName) {
+  try {
+    const res = await client.get("/api/now/table/sys_choice", {
+      params: {
+        sysparm_query: `name=${tableName}^element=${fieldName}^language=en^inactive=false`,
+        sysparm_fields: "value,label",
+        sysparm_display_value: "all",
+        sysparm_limit: 100,
+        sysparm_orderby: "sequence"
+      }
+    });
+    return (res.result ?? []).map((e) => ({ value: e.value?.value ?? "", label: e.label?.display_value ?? "" })).filter((e) => e.value !== "");
+  } catch {
+    return [];
+  }
+}
+async function fetchAllEnums(client, tables, onProgress) {
+  const pairs = [];
+  for (const [, node] of tables) {
+    for (const f of node.fields) {
+      if (f.type === "choice") pairs.push({ table: node.name, field: f.name });
+    }
+  }
+  onProgress(`  Fetching choices for ${pairs.length} choice field(s)\u2026`);
+  const enums = /* @__PURE__ */ new Map();
+  const CHUNK = 5;
+  for (let i = 0; i < pairs.length; i += CHUNK) {
+    const chunk = pairs.slice(i, i + CHUNK);
+    const results = await Promise.all(
+      chunk.map(({ table, field }) => fetchChoiceValues(client, table, field))
+    );
+    for (let j = 0; j < chunk.length; j++) {
+      if (results[j].length > 0) {
+        enums.set(`${chunk[j].table}__${chunk[j].field}`, results[j]);
+      }
+    }
+  }
+  return enums;
+}
+var MAX_EXPLAIN_CHARS = 12e3;
+async function explainSchema(graph, schemaContent, rootTable, fmt) {
+  const activeProvider = getActiveProvider();
+  if (!activeProvider) {
+    throw new Error("No AI provider configured. Run `snow provider set` to configure one.");
+  }
+  const llm = buildProvider(
+    activeProvider.name,
+    activeProvider.config.model,
+    activeProvider.config.apiKey,
+    activeProvider.config.baseUrl
+  );
+  const scopes = collectScopes(graph);
+  const scopeList = [...scopes.keys()].join(", ");
+  const truncated = schemaContent.length > MAX_EXPLAIN_CHARS;
+  const schemaSnippet = truncated ? schemaContent.slice(0, MAX_EXPLAIN_CHARS) + "\n... (truncated)" : schemaContent;
+  const messages = [
+    {
+      role: "system",
+      content: `You are a ServiceNow architect and data modeler. When given a schema map, provide a clear, practical explanation covering:
+1. The business domain this data model represents
+2. Key tables and their purpose (focus on the most important ones)
+3. Notable relationships \u2014 references, M2M links, self-referencing tables, hierarchies
+4. Any cross-scope dependencies that developers should be aware of
+5. A one-line summary suitable for documentation
+
+Be concise and practical. Assume the reader is a developer working with this schema. Format your response in Markdown.`
+    },
+    {
+      role: "user",
+      content: `Explain this ServiceNow schema map for table \`${rootTable}\` (${graph.tables.size} tables, scopes: ${scopeList}). Format: ${fmt.toUpperCase()}${truncated ? " [schema truncated]" : ""}
+
+\`\`\`
+${schemaSnippet}
+\`\`\``
+    }
+  ];
+  return llm.complete(messages);
+}
+var MERMAID_TYPES = {
+  integer: "int",
+  long: "bigint",
+  float: "float",
+  decimal: "float",
+  currency: "float",
+  boolean: "boolean",
+  date: "date",
+  glide_date: "date",
+  glide_date_time: "datetime",
+  reference: "string",
+  glide_list: "string"
+};
+var DBML_TYPES = {
+  integer: "int",
+  long: "bigint",
+  float: "float",
+  decimal: "decimal(15,4)",
+  currency: "decimal(15,2)",
+  boolean: "boolean",
+  date: "date",
+  glide_date: "date",
+  glide_date_time: "datetime",
+  reference: "varchar(32)",
+  glide_list: "text",
+  choice: "varchar(40)",
+  script: "text",
+  html: "text",
+  url: "varchar(1024)",
+  email: "varchar(255)",
+  phone_number: "varchar(40)"
+};
+function toMermaidType(t) {
+  return MERMAID_TYPES[t] ?? "string";
+}
+function toDBMLType(t) {
+  return DBML_TYPES[t] ?? "varchar(255)";
+}
+function collectScopes(graph) {
+  const scopes = /* @__PURE__ */ new Map();
+  for (const [, node] of graph.tables) {
+    const s = node.scope || "Global";
+    if (!scopes.has(s)) scopes.set(s, []);
+    scopes.get(s).push(node.name);
+  }
+  return scopes;
+}
+function collectStubTables(graph) {
+  const stubs = /* @__PURE__ */ new Set();
+  for (const [, node] of graph.tables) {
+    for (const f of node.fields) {
+      if (f.reference && !graph.tables.has(f.reference)) {
+        stubs.add(f.reference);
+      }
+    }
+  }
+  return stubs;
+}
+function renderMermaid(graph, rootTable) {
+  const scopes = collectScopes(graph);
+  const scopeSummary = [...scopes.entries()].map(([s, tables]) => `${s} (${tables.length})`).join(", ");
+  const lines = [
+    `---`,
+    `title: Schema map \u2014 ${rootTable}`,
+    `---`,
+    `erDiagram`,
+    ``,
+    `  %% Scopes: ${scopeSummary}`,
+    ...scopes.size > 1 ? [`  %% Warning: tables from ${scopes.size} scopes \u2014 cross-scope references present`] : []
+  ];
+  for (const [, node] of graph.tables) {
+    lines.push(`  ${node.name} {`);
+    for (const f of node.fields) {
+      if (f.type === "glide_list") continue;
+      const mType = toMermaidType(f.type);
+      const note = f.mandatory ? ' "M"' : "";
+      lines.push(`    ${mType} ${f.name}${note}`);
+    }
+    lines.push(`  }`);
+  }
+  lines.push("");
+  for (const edge of graph.edges) {
+    if (!graph.tables.has(edge.to)) continue;
+    const rel = edge.type === "glide_list" ? `}o--o{` : `}o--||`;
+    const safeLabel = edge.fieldLabel.replace(/"/g, "'");
+    lines.push(`  ${edge.from} ${rel} ${edge.to} : "${safeLabel}"`);
+  }
+  const stubs = collectStubTables(graph);
+  if (stubs.size > 0) {
+    lines.push("");
+    lines.push(`  %% Stub tables \u2014 referenced but not crawled (increase --depth to explore)`);
+    for (const stubName of [...stubs].sort()) {
+      lines.push(`  ${stubName} {`);
+      lines.push(`    string sys_id`);
+      lines.push(`  }`);
+    }
+    for (const [, node] of graph.tables) {
+      for (const f of node.fields) {
+        if (f.reference && stubs.has(f.reference)) {
+          const rel = f.type === "glide_list" ? `}o--o{` : `}o--||`;
+          const safeLabel = f.label.replace(/"/g, "'");
+          lines.push(`  ${node.name} ${rel} ${f.reference} : "${safeLabel}"`);
+        }
+      }
+    }
+  }
+  if (graph.enums.size > 0) {
+    lines.push("");
+    lines.push(`  %% Choice field enums`);
+    for (const [key, values] of graph.enums) {
+      const valStr = values.map((v) => `${v.value}=${v.label}`).join(", ");
+      lines.push(`  %% ${key}: ${valStr}`);
+    }
+  }
+  return lines.join("\n");
+}
+function renderDBML(graph, rootTable) {
+  const scopes = collectScopes(graph);
+  const scopeSummary = [...scopes.entries()].map(([s, tables]) => `${s} (${tables.length})`).join(", ");
+  const lines = [
+    `// Schema map \u2014 ${rootTable}`,
+    `// Generated by @syndicalt/snow-cli`,
+    `// Scopes: ${scopeSummary}`,
+    ...scopes.size > 1 ? [`// Warning: tables from ${scopes.size} scopes \u2014 cross-scope references present`] : [],
+    ""
+  ];
+  for (const [, node] of graph.tables) {
+    const safeLabel = node.label.replace(/'/g, "\\'");
+    const safeScope = node.scope.replace(/'/g, "\\'");
+    const safeNote = node.scope && node.scope !== "Global" ? `${safeLabel} | scope: ${safeScope}` : safeLabel;
+    lines.push(`Table ${node.name} [note: '${safeNote}'] {`);
+    for (const f of node.fields) {
+      const enumKey = `${node.name}__${f.name}`;
+      const dbType = f.type === "choice" && graph.enums.has(enumKey) ? enumKey : toDBMLType(f.type);
+      const annots = [];
+      if (f.name === "sys_id") annots.push("pk");
+      if (f.mandatory) annots.push("not null");
+      if (f.type === "reference" && f.reference) annots.push(`ref: > ${f.reference}.sys_id`);
+      const annotStr = annots.length ? ` [${annots.join(", ")}]` : "";
+      lines.push(`  ${f.name} ${dbType}${annotStr}`);
+    }
+    lines.push(`}`);
+    lines.push("");
+  }
+  for (const edge of graph.edges) {
+    if (edge.type === "glide_list" && graph.tables.has(edge.to)) {
+      lines.push(`Ref: ${edge.from}.${edge.field} <> ${edge.to}.sys_id // ${edge.fieldLabel}`);
+    }
+  }
+  const stubs = collectStubTables(graph);
+  if (stubs.size > 0) {
+    lines.push("");
+    lines.push(`// Placeholder tables \u2014 referenced but not crawled (increase --depth to explore)`);
+    for (const stubName of [...stubs].sort()) {
+      lines.push(`Table ${stubName} [note: 'not crawled'] {`);
+      lines.push(`  sys_id varchar(32) [pk]`);
+      lines.push(`}`);
+      lines.push("");
+    }
+  }
+  if (graph.enums.size > 0) {
+    lines.push("");
+    lines.push(`// Choice field enums`);
+    for (const [key, values] of graph.enums) {
+      lines.push(`Enum ${key} {`);
+      for (const v of values) {
+        const safeNote = v.label.replace(/'/g, "\\'");
+        lines.push(`  "${v.value}" [note: '${safeNote}']`);
+      }
+      lines.push(`}`);
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function schemaShowCommand() {
+  return new Command3("show").description("Show field schema for a ServiceNow table").argument("<table>", "Table name (e.g. incident, sys_user)").option("--format <fmt>", "Output format: table or json", "table").option("-f, --filter <text>", "Filter fields by name or label (case-insensitive)").action(async (table, opts) => {
+    const instance = requireActiveInstance();
+    const client = new ServiceNowClient(instance);
+    const spinner = ora2(`Loading schema for ${table}...`).start();
+    try {
+      const res = await client.get(
+        "/api/now/table/sys_dictionary",
+        {
+          params: {
+            sysparm_query: `name=${table}^elementISNOTEMPTY`,
+            sysparm_fields: "element,column_label,internal_type,max_length,mandatory,read_only,reference,default_value,comments",
+            sysparm_display_value: "all",
+            sysparm_limit: 500,
+            sysparm_exclude_reference_link: true
+          }
         }
-        console.log(chalk3.bold(`
+      );
+      spinner.stop();
+      let entries = res.result ?? [];
+      if (opts.filter) {
+        const filterLower = opts.filter.toLowerCase();
+        entries = entries.filter(
+          (e) => e.element?.value?.toLowerCase().includes(filterLower) || e.column_label?.display_value?.toLowerCase().includes(filterLower)
+        );
+      }
+      if (entries.length === 0) {
+        console.log(chalk3.dim(`No fields found for table "${table}".`));
+        return;
+      }
+      if (opts.format === "json") {
+        const mapped = entries.map((e) => ({
+          name: e.element?.value,
+          label: e.column_label?.display_value,
+          type: e.internal_type?.value,
+          maxLength: e.max_length?.value ? parseInt(e.max_length.value, 10) : void 0,
+          mandatory: e.mandatory?.value === "true",
+          readOnly: e.read_only?.value === "true",
+          reference: e.reference?.value || void 0,
+          defaultValue: e.default_value?.value || void 0,
+          comments: e.comments?.value || void 0
+        }));
+        console.log(JSON.stringify(mapped, null, 2));
+        return;
+      }
+      console.log(chalk3.bold(`
 Schema for ${chalk3.cyan(table)} (${entries.length} fields)
 `));
-        const colWidths = { name: 30, label: 30, type: 20, extra: 20 };
-        const header = [
-          "Field Name".padEnd(colWidths.name),
-          "Label".padEnd(colWidths.label),
-          "Type".padEnd(colWidths.type),
-          "Flags"
-        ].join("  ");
-        console.log(chalk3.bold(header));
-        console.log(chalk3.dim("-".repeat(header.length)));
-        for (const e of entries) {
-          const name = (e.element?.value ?? "").slice(0, colWidths.name).padEnd(colWidths.name);
-          const label = (e.column_label?.display_value ?? "").slice(0, colWidths.label).padEnd(colWidths.label);
-          const type = (e.internal_type?.value ?? "").slice(0, colWidths.type).padEnd(colWidths.type);
-          const flags = [];
-          if (e.mandatory?.value === "true") flags.push(chalk3.red("M"));
-          if (e.read_only?.value === "true") flags.push(chalk3.yellow("R"));
-          if (e.reference?.value) flags.push(chalk3.blue(`ref:${e.reference.value}`));
-          console.log(`${name}  ${label}  ${type}  ${flags.join(" ")}`);
+      const colWidths = { name: 30, label: 30, type: 20 };
+      const header = [
+        "Field Name".padEnd(colWidths.name),
+        "Label".padEnd(colWidths.label),
+        "Type".padEnd(colWidths.type),
+        "Flags"
+      ].join("  ");
+      console.log(chalk3.bold(header));
+      console.log(chalk3.dim("-".repeat(header.length)));
+      for (const e of entries) {
+        const name = (e.element?.value ?? "").slice(0, colWidths.name).padEnd(colWidths.name);
+        const label = (e.column_label?.display_value ?? "").slice(0, colWidths.label).padEnd(colWidths.label);
+        const type = (e.internal_type?.value ?? "").slice(0, colWidths.type).padEnd(colWidths.type);
+        const flags = [];
+        if (e.mandatory?.value === "true") flags.push(chalk3.red("M"));
+        if (e.read_only?.value === "true") flags.push(chalk3.yellow("R"));
+        if (e.reference?.value) flags.push(chalk3.blue(`ref:${e.reference.value}`));
+        console.log(`${name}  ${label}  ${type}  ${flags.join(" ")}`);
+      }
+      console.log(chalk3.dim("\nFlags: M=mandatory  R=read-only  ref=reference table"));
+    } catch (err) {
+      spinner.fail();
+      console.error(chalk3.red(err instanceof Error ? err.message : String(err)));
+      process.exit(1);
+    }
+  });
+}
+function schemaMapCommand() {
+  return new Command3("map").description("Crawl table references and generate a Mermaid or DBML schema map").argument("<table>", "Root table to start from (e.g. incident, x_myapp_request)").option("-d, --depth <n>", "Levels of references to follow", "2").option("--show-m2m", "Include glide_list fields as M2M relationships", false).option("--format <fmt>", "Output format: mermaid or dbml", "mermaid").option("--out <dir>", "Directory to write the output file", ".").option("--name <name>", "Base filename for the output file (default: <table>-schema)").option("--inbound", "Also crawl tables that reference this table (inbound references)", false).option("--enums", "Fetch choice field values and emit Enum blocks (DBML) or comments (Mermaid)", false).option("--explain", "Use the active AI provider to explain the schema in plain English", false).action(async (table, opts) => {
+    const instance = requireActiveInstance();
+    const client = new ServiceNowClient(instance);
+    const depth = Math.max(0, parseInt(opts.depth, 10) || 2);
+    const fmt = opts.format === "dbml" ? "dbml" : "mermaid";
+    console.log(
+      chalk3.bold(`
+Building schema map for ${chalk3.cyan(table)}`),
+      chalk3.dim(`(depth: ${depth}, m2m: ${opts.showM2m}, inbound: ${opts.inbound}, format: ${fmt})
+`)
+    );
+    if (opts.inbound && depth > 1) {
+      console.log(chalk3.yellow(
+        `  Advisory: --inbound with depth ${depth} can produce very large graphs for highly-referenced tables. Consider --depth 1 if the result is too large.
+`
+      ));
+    }
+    const spinner = ora2("Crawling\u2026").start();
+    try {
+      const graph = await crawlSchema(
+        client,
+        table,
+        depth,
+        opts.showM2m,
+        opts.inbound,
+        (msg) => {
+          spinner.text = msg;
         }
-        console.log(chalk3.dim("\nFlags: M=mandatory  R=read-only  ref=reference table"));
-      } catch (err) {
-        spinner.fail();
-        console.error(chalk3.red(err instanceof Error ? err.message : String(err)));
-        process.exit(1);
+      );
+      if (opts.enums) {
+        spinner.start("Fetching choice field values\u2026");
+        graph.enums = await fetchAllEnums(client, graph.tables, (msg) => {
+          spinner.text = msg;
+        });
+        spinner.stop();
+      } else {
+        spinner.stop();
+      }
+      const output = fmt === "dbml" ? renderDBML(graph, table) : renderMermaid(graph, table);
+      const ext = fmt === "dbml" ? ".dbml" : ".mmd";
+      const baseName = opts.name ?? `${table}-schema`;
+      const outDir = resolve(opts.out);
+      mkdirSync2(outDir, { recursive: true });
+      const outFile = join2(outDir, `${baseName}${ext}`);
+      writeFileSync2(outFile, output, "utf8");
+      const tableCount = graph.tables.size;
+      if (tableCount > 50) {
+        console.log(chalk3.yellow(
+          `
+  Warning: large graph (${tableCount} tables). Diagrams may be hard to read. Consider reducing --depth or scoping to a smaller root table.`
+        ));
+      }
+      const edgeCount = graph.edges.filter((e) => graph.tables.has(e.to)).length;
+      const m2mCount = graph.edges.filter((e) => e.type === "glide_list" && graph.tables.has(e.to)).length;
+      console.log(chalk3.green(`
+Schema map written to ${outFile}`));
+      const enumCount = graph.enums.size;
+      console.log(chalk3.dim(
+        `${tableCount} table${tableCount !== 1 ? "s" : ""}, ${edgeCount - m2mCount} reference${edgeCount - m2mCount !== 1 ? "s" : ""}` + (m2mCount ? `, ${m2mCount} M2M link${m2mCount !== 1 ? "s" : ""}` : "") + (enumCount ? `, ${enumCount} enum${enumCount !== 1 ? "s" : ""}` : "")
+      ));
+      if (fmt === "mermaid") {
+        console.log(chalk3.dim("\nOpen the .mmd file in any Mermaid viewer, or paste into https://mermaid.live"));
+      } else {
+        console.log(chalk3.dim("\nOpen the .dbml file in https://dbdiagram.io or any DBML-compatible tool"));
       }
+      if (opts.explain) {
+        const explainSpinner = ora2("Generating AI explanation\u2026").start();
+        try {
+          const explanation = await explainSchema(graph, output, table, fmt);
+          explainSpinner.stop();
+          const explainFile = join2(outDir, `${baseName}.explanation.md`);
+          writeFileSync2(explainFile, explanation, "utf8");
+          console.log(chalk3.green(`
+Explanation saved to ${explainFile}`));
+          console.log("\n" + explanation);
+        } catch (err) {
+          explainSpinner.stop();
+          console.log(chalk3.yellow(
+            `
+Note: AI explanation failed \u2014 ${err instanceof Error ? err.message : String(err)}`
+          ));
+        }
+      }
+    } catch (err) {
+      spinner.fail();
+      console.error(chalk3.red(err instanceof Error ? err.message : String(err)));
+      process.exit(1);
     }
-  );
+  });
+}
+function schemaCommand() {
+  const cmd = new Command3("schema").description("Schema inspection and mapping");
+  cmd.addCommand(schemaShowCommand(), { isDefault: true });
+  cmd.addCommand(schemaMapCommand());
+  return cmd;
 }
 
 // src/commands/script.ts
@@ -746,9 +1317,9 @@ init_esm_shims();
 init_config();
 init_client();
 import { Command as Command4 } from "commander";
-import { writeFileSync as writeFileSync2, readFileSync as readFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { writeFileSync as writeFileSync3, readFileSync as readFileSync2, mkdirSync as mkdirSync3, existsSync as existsSync2, readdirSync, statSync } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { spawnSync } from "child_process";
 import chalk4 from "chalk";
 import ora3 from "ora";
@@ -797,12 +1368,12 @@ function scriptCommand() {
       if (opts.out) {
         filePath = opts.out;
       } else {
-        const dir = join2(homedir2(), ".snow", "scripts");
-        if (!existsSync2(dir)) mkdirSync2(dir, { recursive: true });
+        const dir = join3(homedir2(), ".snow", "scripts");
+        if (!existsSync2(dir)) mkdirSync3(dir, { recursive: true });
         const safeName = `${table}_${sysId}_${field}`.replace(/[^a-z0-9_-]/gi, "_");
-        filePath = join2(dir, `${safeName}${extensionForField(field)}`);
+        filePath = join3(dir, `${safeName}${extensionForField(field)}`);
       }
-      writeFileSync2(filePath, content, "utf-8");
+      writeFileSync3(filePath, content, "utf-8");
       console.log(chalk4.green(`Saved to: ${filePath}`));
       if (opts.open === false) return;
       const editor = resolveEditor(opts.editor);
@@ -834,9 +1405,9 @@ function scriptCommand() {
     if (file) {
       filePath = file;
     } else {
-      const dir = join2(homedir2(), ".snow", "scripts");
+      const dir = join3(homedir2(), ".snow", "scripts");
       const safeName = `${table}_${sysId}_${field}`.replace(/[^a-z0-9_-]/gi, "_");
-      filePath = join2(dir, `${safeName}${extensionForField(field)}`);
+      filePath = join3(dir, `${safeName}${extensionForField(field)}`);
     }
     if (!existsSync2(filePath)) {
       console.error(chalk4.red(`File not found: ${filePath}`));
@@ -846,7 +1417,7 @@ function scriptCommand() {
     await pushScript(client, table, sysId, field, filePath);
   });
   cmd.command("list").alias("ls").description("List locally cached script files").action(() => {
-    const dir = join2(homedir2(), ".snow", "scripts");
+    const dir = join3(homedir2(), ".snow", "scripts");
     if (!existsSync2(dir)) {
       console.log(chalk4.dim("No scripts cached yet. Run `snow script pull` first."));
       return;
@@ -857,7 +1428,7 @@ function scriptCommand() {
       return;
     }
     for (const f of files) {
-      const stat = statSync(join2(dir, f));
+      const stat = statSync(join3(dir, f));
       const modified = stat.mtime.toLocaleString();
       console.log(`${chalk4.cyan(f)}  ${chalk4.dim(modified)}`);
     }
@@ -883,114 +1454,6 @@ init_config();
 import { Command as Command5 } from "commander";
 import chalk5 from "chalk";
 import ora4 from "ora";
-
-// src/lib/llm.ts
-init_esm_shims();
-import axios2 from "axios";
-var OpenAIProvider = class {
-  constructor(apiKey, model, baseUrl = "https://api.openai.com/v1", name = "openai") {
-    this.apiKey = apiKey;
-    this.model = model;
-    this.baseUrl = baseUrl;
-    this.providerName = name;
-  }
-  providerName;
-  async complete(messages) {
-    const res = await axios2.post(
-      `${this.baseUrl.replace(/\/$/, "")}/chat/completions`,
-      { model: this.model, messages },
-      {
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        timeout: 12e4
-      }
-    );
-    const content = res.data.choices[0]?.message.content;
-    if (!content) throw new Error("LLM returned an empty response");
-    return content;
-  }
-};
-var AnthropicProvider = class {
-  constructor(apiKey, model) {
-    this.apiKey = apiKey;
-    this.model = model;
-  }
-  providerName = "anthropic";
-  async complete(messages) {
-    const system = messages.find((m) => m.role === "system")?.content;
-    const conversation = messages.filter((m) => m.role !== "system");
-    const res = await axios2.post(
-      "https://api.anthropic.com/v1/messages",
-      {
-        model: this.model,
-        max_tokens: 8192,
-        ...system ? { system } : {},
-        messages: conversation
-      },
-      {
-        headers: {
-          "x-api-key": this.apiKey,
-          "anthropic-version": "2023-06-01",
-          "Content-Type": "application/json"
-        },
-        timeout: 12e4
-      }
-    );
-    const text = res.data.content.find((c) => c.type === "text")?.text;
-    if (!text) throw new Error("Anthropic returned an empty response");
-    return text;
-  }
-};
-var OllamaProvider = class {
-  constructor(model, baseUrl = "http://localhost:11434") {
-    this.model = model;
-    this.baseUrl = baseUrl;
-  }
-  providerName = "ollama";
-  async complete(messages) {
-    const res = await axios2.post(
-      `${this.baseUrl.replace(/\/$/, "")}/api/chat`,
-      { model: this.model, messages, stream: false },
-      { headers: { "Content-Type": "application/json" }, timeout: 3e5 }
-    );
-    const content = res.data.message.content;
-    if (!content) throw new Error("Ollama returned an empty response");
-    return content;
-  }
-};
-function buildProvider(name, model, apiKey, baseUrl) {
-  switch (name) {
-    case "anthropic":
-      if (!apiKey) throw new Error("Anthropic provider requires an API key (https://platform.claude.com/)");
-      return new AnthropicProvider(apiKey, model);
-    case "xai":
-      if (!apiKey) throw new Error("xAI provider requires an API key (https://platform.x.ai/)");
-      return new OpenAIProvider(
-        apiKey,
-        model,
-        baseUrl ?? "https://api.x.ai/v1",
-        "xai"
-      );
-    case "ollama":
-      return new OllamaProvider(model, baseUrl);
-    case "openai":
-    default:
-      if (!apiKey) throw new Error("OpenAI provider requires an API key (https://platform.openai.com/)");
-      return new OpenAIProvider(apiKey, model, baseUrl, name);
-  }
-}
-function extractJSON(raw) {
-  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
-  if (fenced) return fenced[1].trim();
-  const start = raw.indexOf("{");
-  const end = raw.lastIndexOf("}");
-  if (start !== -1 && end !== -1) return raw.slice(start, end + 1);
-  return raw.trim();
-}
-
-// src/commands/provider.ts
 var PROVIDER_NAMES = ["openai", "anthropic", "xai", "ollama"];
 var PROVIDER_DEFAULTS = {
   openai: { model: "gpt-4o" },
@@ -1142,8 +1605,8 @@ init_esm_shims();
 init_config();
 import { Command as Command6 } from "commander";
 import * as readline from "readline";
-import { writeFileSync as writeFileSync3, readFileSync as readFileSync3, existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2 } from "fs";
-import { join as join3, dirname, basename } from "path";
+import { writeFileSync as writeFileSync4, readFileSync as readFileSync3, existsSync as existsSync3, mkdirSync as mkdirSync4, readdirSync as readdirSync2 } from "fs";
+import { join as join4, dirname, basename } from "path";
 import { tmpdir as tmpdir2 } from "os";
 import { spawnSync as spawnSync2 } from "child_process";
 import chalk6 from "chalk";
@@ -2498,12 +2961,12 @@ function printBuildSummary(build, previous = null) {
 }
 function saveBuild(build, customDir) {
   const dir = customDir ?? slugify(build.name);
-  mkdirSync3(dir, { recursive: true });
+  mkdirSync4(dir, { recursive: true });
   const base = slugify(build.name);
-  const xmlFile = join3(dir, `${base}.xml`);
-  const manifestFile = join3(dir, `${base}.manifest.json`);
-  writeFileSync3(xmlFile, generateUpdateSetXML(build), "utf-8");
-  writeFileSync3(manifestFile, JSON.stringify(build, null, 2), "utf-8");
+  const xmlFile = join4(dir, `${base}.xml`);
+  const manifestFile = join4(dir, `${base}.manifest.json`);
+  writeFileSync4(xmlFile, generateUpdateSetXML(build), "utf-8");
+  writeFileSync4(manifestFile, JSON.stringify(build, null, 2), "utf-8");
   return dir;
 }
 function printSaveResult(dir, build) {
@@ -2596,7 +3059,7 @@ function resolveManifestPath(path2) {
   }
   if (existsSync3(path2) && !path2.includes(".")) {
     const files = readdirSync2(path2).filter((f) => f.endsWith(".manifest.json"));
-    if (files.length > 0) return join3(path2, files[0]);
+    if (files.length > 0) return join4(path2, files[0]);
   }
   console.error(chalk6.red(`Cannot resolve build manifest from: ${path2}`));
   console.error(chalk6.dim("Pass a build directory, a .xml file, or a .manifest.json file."));
@@ -2661,8 +3124,8 @@ async function runReview(build, buildDir) {
     console.log();
     const shouldEdit = await confirm2({ message: "Open in editor to edit?", default: false });
     if (shouldEdit) {
-      const tmpFile = join3(tmpdir2(), `snow-review-${Date.now()}${fieldDef.ext}`);
-      writeFileSync3(tmpFile, currentCode, "utf-8");
+      const tmpFile = join4(tmpdir2(), `snow-review-${Date.now()}${fieldDef.ext}`);
+      writeFileSync4(tmpFile, currentCode, "utf-8");
       const isWin = process.platform === "win32";
       spawnSync2(editor, [tmpFile], { stdio: "inherit", shell: isWin });
       const updatedCode = readFileSync3(tmpFile, "utf-8");
@@ -2670,10 +3133,10 @@ async function runReview(build, buildDir) {
         build.artifacts[selectedIndex].fields[fieldDef.field] = updatedCode;
         modified = true;
         const base = slugify(build.name);
-        const xmlFile = join3(buildDir, `${base}.xml`);
-        const manifestFile = join3(buildDir, `${base}.manifest.json`);
-        writeFileSync3(xmlFile, generateUpdateSetXML(build), "utf-8");
-        writeFileSync3(manifestFile, JSON.stringify(build, null, 2), "utf-8");
+        const xmlFile = join4(buildDir, `${base}.xml`);
+        const manifestFile = join4(buildDir, `${base}.manifest.json`);
+        writeFileSync4(xmlFile, generateUpdateSetXML(build), "utf-8");
+        writeFileSync4(manifestFile, JSON.stringify(build, null, 2), "utf-8");
         console.log(chalk6.green(`  \u2714 Saved changes to ${basename(manifestFile)}`));
       } else {
         console.log(chalk6.dim("  No changes made."));
@@ -2781,7 +3244,7 @@ function aiCommand() {
         console.error(chalk6.red(`No .manifest.json found in directory: ${path2}`));
         process.exit(1);
       }
-      manifestPath = join3(path2, files[0]);
+      manifestPath = join4(path2, files[0]);
     } else {
       console.error(chalk6.red(`Cannot resolve build from: ${path2}`));
       console.error(chalk6.dim("Pass a build directory, a .xml file, or a .manifest.json file."));
@@ -2963,13 +3426,13 @@ ${chalk6.dim("Slash commands:")}
 // src/index.ts
 import { readFileSync as readFileSync4 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join4, dirname as dirname2 } from "path";
+import { join as join5, dirname as dirname2 } from "path";
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname2(__filename2);
 function getVersion() {
   try {
     const pkg = JSON.parse(
-      readFileSync4(join4(__dirname2, "..", "package.json"), "utf-8")
+      readFileSync4(join5(__dirname2, "..", "package.json"), "utf-8")
     );
     return pkg.version;
   } catch {