@driftdev/cli 1.4.0 → 1.5.0

package/dist/drift.js

@@ -52,7 +52,7 @@ var init_global = () => {};
 
 // src/drift.ts
 import { readFileSync as readFileSync22 } from "node:fs";
-import * as path29 from "node:path";
+import * as path30 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Command } from "commander";
 
@@ -1094,7 +1094,7 @@ function getVersion() {
   } catch {
     cached = "0.0.0";
   }
-  return cached;
+  return cached ?? "0.0.0";
 }
 
 // src/commands/breaking.ts
@@ -2259,7 +2259,7 @@ function registerContextCommand(program) {
 }
 
 // src/commands/coverage.ts
-import * as path15 from "node:path";
+import * as path16 from "node:path";
 
 // src/formatters/coverage.ts
 function renderCoverage(data) {
@@ -2286,12 +2286,114 @@ function renderCoverage(data) {
 `);
 }
 
+// src/utils/load-spec.ts
+import { existsSync as existsSync12, readFileSync as readFileSync13 } from "node:fs";
+import * as path15 from "node:path";
+import { fromSource } from "@driftdev/clarity-adapter";
+import { fromDocument } from "@driftdev/openapi-adapter";
+function getPackageInfo(cwd) {
+  const pkgPath = path15.join(cwd, "package.json");
+  if (!existsSync12(pkgPath))
+    return {};
+  try {
+    const pkg = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    return { name: pkg.name, version: pkg.version };
+  } catch (err) {
+    formatWarning(`Could not parse package.json${err instanceof Error ? `: ${err.message}` : ""}`);
+    return {};
+  }
+}
+function resolveLang(opts) {
+  if (opts.lang) {
+    if (opts.lang !== "typescript" && opts.lang !== "clarity" && opts.lang !== "openapi") {
+      throw new Error(`Unknown language: ${opts.lang}`);
+    }
+    return opts.lang;
+  }
+  if (opts.spec)
+    return "openapi";
+  if (opts.abi || opts.entry?.endsWith(".clar"))
+    return "clarity";
+  return "typescript";
+}
+function isUrl(value) {
+  return /^https?:\/\//.test(value);
+}
+async function readSpecDocument(specPath) {
+  if (isUrl(specPath)) {
+    const res = await fetch(specPath, { signal: AbortSignal.timeout(30000) });
+    if (!res.ok)
+      throw new Error(`Failed to fetch spec: ${res.status} ${res.statusText} (${specPath})`);
+    return res.text();
+  }
+  if (!existsSync12(specPath))
+    throw new Error(`Spec file not found: ${specPath}`);
+  return readFileSync13(specPath, "utf-8");
+}
+async function resolveTruth(opts) {
+  const lang = resolveLang(opts);
+  if (lang === "openapi") {
+    if (!opts.spec)
+      throw new Error("--spec is required when --lang openapi");
+    const specPath = isUrl(opts.spec) ? opts.spec : path15.resolve(process.cwd(), opts.spec);
+    const document = await readSpecDocument(specPath);
+    const name = isUrl(specPath) ? new URL(specPath).pathname.split("/").pop()?.replace(/\.[^.]*$/, "") || "openapi" : path15.basename(specPath, path15.extname(specPath));
+    const apiSpec = fromDocument(document);
+    if (!apiSpec.meta.name || apiSpec.meta.name === "openapi")
+      apiSpec.meta.name = name;
+    return {
+      apiSpec,
+      packageName: apiSpec.meta.name,
+      packageVersion: apiSpec.meta.version,
+      lang
+    };
+  }
+  if (lang === "clarity") {
+    if (!opts.abi)
+      throw new Error("--abi is required when --lang clarity");
+    if (!opts.entry)
+      throw new Error("Entry file required for --lang clarity");
+    const entryFile = path15.resolve(process.cwd(), opts.entry);
+    const abiPath = path15.resolve(process.cwd(), opts.abi);
+    if (!existsSync12(entryFile))
+      throw new Error(`Source file not found: ${entryFile}`);
+    if (!existsSync12(abiPath))
+      throw new Error(`ABI file not found: ${abiPath}`);
+    const source = readFileSync13(entryFile, "utf-8");
+    const abi = JSON.parse(readFileSync13(abiPath, "utf-8"));
+    const name = path15.basename(entryFile, path15.extname(entryFile));
+    const pkg2 = getPackageInfo(process.cwd());
+    const apiSpec = fromSource(source, abi, { name, version: pkg2.version });
+    return { apiSpec, packageName: pkg2.name ?? name, packageVersion: pkg2.version, lang };
+  }
+  if (!opts.entry)
+    throw new Error("Entry file required");
+  const { spec } = await cachedExtract(opts.entry);
+  const pkg = getPackageInfo(process.cwd());
+  return {
+    apiSpec: spec,
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+    lang
+  };
+}
+
 // src/commands/coverage.ts
 function registerCoverageCommand(program) {
-  program.command("coverage [entry]").description("Measure documentation coverage for a TypeScript entry file").option("--min <n>", "Minimum coverage threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (entry, options) => {
+  program.command("coverage [entry]").description("Measure documentation coverage").option("--min <n>", "Minimum coverage threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript" && options.all) {
+        formatError("coverage", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
+        return;
+      }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
         if (!allPackages || allPackages.length === 0) {
@@ -2333,8 +2435,16 @@ function registerCoverageCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const entryFile = entry ? path15.resolve(process.cwd(), entry) : config.entry ? path15.resolve(process.cwd(), config.entry) : detectEntry();
-      const { spec } = await cachedExtract(entryFile);
+      let entryFile = entry ? path16.resolve(process.cwd(), entry) : undefined;
+      if (lang === "typescript" && !entryFile) {
+        entryFile = config.entry ? path16.resolve(process.cwd(), config.entry) : detectEntry();
+      }
+      const { apiSpec: spec } = await resolveTruth({
+        entry: entryFile,
+        lang,
+        spec: options.spec,
+        abi: options.abi
+      });
       const exports = spec.exports ?? [];
       const total = exports.length;
       const undocumented = [];
@@ -2382,7 +2492,7 @@ function registerCoverageCommand(program) {
 }
 
 // src/commands/diff.ts
-import * as path16 from "node:path";
+import * as path17 from "node:path";
 import { extract as extract5 } from "@openpkg-ts/sdk";
 import { categorizeBreakingChanges as categorizeBreakingChanges4, diffSpec as diffSpec4, normalize as normalize5 } from "@openpkg-ts/spec";
 
@@ -2456,7 +2566,7 @@ function registerDiffCommand(program) {
         let totalAdded = 0;
         let totalChanged = 0;
         for (const pkg of packages) {
-          const relEntry = path16.relative(cwd, pkg.entry);
+          const relEntry = path17.relative(cwd, pkg.entry);
           const oldSpec2 = await extractSpecFromRef(options.base, relEntry, cwd);
           const newSpec2 = options.head ? await extractSpecFromRef(options.head, relEntry, cwd) : normalize5((await extract5({ entryFile: pkg.entry })).spec);
           const diff2 = diffSpec4(oldSpec2, newSpec2);
@@ -2526,8 +2636,8 @@ function registerDiffCommand(program) {
 }
 
 // src/commands/examples.ts
-import { readFileSync as readFileSync13 } from "node:fs";
-import * as path17 from "node:path";
+import { readFileSync as readFileSync14 } from "node:fs";
+import * as path18 from "node:path";
 import { validateExamples } from "@driftdev/sdk";
 
 // src/formatters/examples.ts
@@ -2606,16 +2716,16 @@ function renderExamples(data) {
 
 // src/commands/examples.ts
 function findPackagePath(entryFile) {
-  let dir = path17.dirname(entryFile);
-  while (dir !== path17.dirname(dir)) {
+  let dir = path18.dirname(entryFile);
+  while (dir !== path18.dirname(dir)) {
     try {
-      readFileSync13(path17.join(dir, "package.json"), "utf-8");
+      readFileSync14(path18.join(dir, "package.json"), "utf-8");
       return dir;
     } catch {
-      dir = path17.dirname(dir);
+      dir = path18.dirname(dir);
     }
   }
-  return path17.dirname(entryFile);
+  return path18.dirname(entryFile);
 }
 function registerExamplesCommand(program) {
   program.command("examples [entry]").description("Validate @example blocks on exports").option("--typecheck", "Type-check examples with TypeScript").option("--run", "Execute examples at runtime (implies --typecheck)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--min <n>", "Minimum presence threshold (exit 1 if below)").action(async (entry, options) => {
@@ -2683,7 +2793,7 @@ function registerExamplesCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const entryFile = entry ? path17.resolve(process.cwd(), entry) : config.entry ? path17.resolve(process.cwd(), config.entry) : detectEntry();
+      const entryFile = entry ? path18.resolve(process.cwd(), entry) : config.entry ? path18.resolve(process.cwd(), config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
       const packagePath = findPackagePath(entryFile);
@@ -2718,7 +2828,7 @@ function registerExamplesCommand(program) {
 }
 
 // src/commands/extract.ts
-import * as path18 from "node:path";
+import * as path19 from "node:path";
 import { Drift } from "@driftdev/sdk";
 import { normalize as normalize6 } from "@openpkg-ts/spec";
 
@@ -2735,10 +2845,37 @@ function renderExtract(data) {
 
 // src/commands/extract.ts
 function registerExtractCommand(program) {
-  program.command("extract [entry]").description("Extract OpenPkg spec from TypeScript entry file").option("-o, --output <file>", "Write JSON to file instead of stdout").option("--only <patterns>", "Include exports matching glob (comma-separated)").option("--ignore <patterns>", "Exclude exports matching glob (comma-separated)").option("--max-depth <n>", "Max type resolution depth", "10").option("--all", "Extract from all workspace packages").option("--private", "Include private packages in --all mode").action(async (entry, options) => {
+  program.command("extract [entry]").description("Extract API spec from a source of truth (TypeScript, Clarity, OpenAPI)").option("-o, --output <file>", "Write JSON to file instead of stdout").option("--only <patterns>", "Include exports matching glob (comma-separated)").option("--ignore <patterns>", "Exclude exports matching glob (comma-separated)").option("--max-depth <n>", "Max type resolution depth", "10").option("--all", "Extract from all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript") {
+        if (options.all || options.only || options.ignore) {
+          formatError("extract", `--all/--only/--ignore not yet supported for ${lang}`, startTime, version);
+          return;
+        }
+        const { apiSpec } = await resolveTruth({
+          entry,
+          lang,
+          spec: options.spec,
+          abi: options.abi
+        });
+        if (options.output) {
+          const { writeFileSync: writeFileSync5 } = await import("node:fs");
+          writeFileSync5(options.output, JSON.stringify(apiSpec, null, 2));
+          process.stderr.write(`drift extract: wrote ${options.output}
+`);
+        } else {
+          formatOutput("extract", apiSpec, startTime, version, renderExtract);
+        }
+        return;
+      }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
         if (!allPackages || allPackages.length === 0) {
@@ -2759,7 +2896,7 @@ function registerExtractCommand(program) {
         formatOutput("extract", { packages: specs, ...skipped.length > 0 ? { skipped } : {} }, startTime, version);
         return;
       }
-      const entryFile = entry ? path18.resolve(process.cwd(), entry) : detectEntry();
+      const entryFile = entry ? path19.resolve(process.cwd(), entry) : detectEntry();
       const hasFilters = !!(options.only || options.ignore);
       let spec;
       if (hasFilters) {
@@ -2798,8 +2935,8 @@ function registerExtractCommand(program) {
 }
 
 // src/commands/filter.ts
-import { readFileSync as readFileSync14 } from "node:fs";
-import * as path19 from "node:path";
+import { readFileSync as readFileSync15 } from "node:fs";
+import * as path20 from "node:path";
 import { filterSpec } from "@openpkg-ts/sdk";
 
 // src/formatters/filter.ts
@@ -2830,8 +2967,8 @@ function registerFilterCommand(program) {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const filePath = path19.resolve(process.cwd(), file);
-      const content = readFileSync14(filePath, "utf-8");
+      const filePath = path20.resolve(process.cwd(), file);
+      const content = readFileSync15(filePath, "utf-8");
       const spec = JSON.parse(content);
       const criteria = {};
       if (options.kind) {
@@ -2857,13 +2994,14 @@ function registerFilterCommand(program) {
 }
 
 // src/commands/get.ts
-import * as path20 from "node:path";
+import * as path21 from "node:path";
 import { getExport, listExports } from "@openpkg-ts/sdk";
 
 // src/formatters/get.ts
 function renderGet(data) {
   const lines = [""];
   const exp = data.export;
+  const schema = typeof exp.schema === "object" && exp.schema !== null ? exp.schema : undefined;
   lines.push(indent(`${c.bold(exp.name)}${" ".repeat(Math.max(2, 50 - exp.name.length))}${c.gray(exp.kind)}`));
   if (exp.deprecated) {
     lines.push(indent(c.yellow("deprecated")));
@@ -2876,24 +3014,24 @@ function renderGet(data) {
     lines.push(indent(`  ${exp.signature}`));
     lines.push("");
   }
-  const params = exp.parameters ?? extractParams(exp.schema);
+  const params = exp.parameters ?? extractParams(schema);
   if (params.length > 0) {
     lines.push(indent(c.gray("  PARAMETERS")));
     for (const p of params) {
       const req = p.required ? "required" : "optional";
       const type = p.type ?? "unknown";
       const desc = p.description ? `  ${c.dim(JSON.stringify(p.description))}` : "";
-      lines.push(indent(`  ${padRight(p.name, 16)}${padRight(type, 24)}${c.gray(req)}${desc}`));
+      lines.push(indent(`  ${padRight(p.name ?? "", 16)}${padRight(type, 24)}${c.gray(req)}${desc}`));
     }
     lines.push("");
   }
-  const returns = exp.returns ?? extractReturns(exp.schema);
+  const returns = exp.returns ?? extractReturns(schema);
   if (returns) {
     lines.push(indent(c.gray("  RETURNS")));
     lines.push(indent(`  ${returns.type ?? "void"}`));
     lines.push("");
   }
-  const members = exp.members ?? extractMembers(exp.schema);
+  const members = exp.members ?? extractMembers(schema);
   if (members.length > 0) {
     const shown = members.slice(0, 50);
     const remaining = members.length - shown.length;
@@ -2901,7 +3039,7 @@ function renderGet(data) {
     for (const m of shown) {
       const req = m.required ? "required" : "optional";
       const type = m.type ?? "";
-      lines.push(indent(`  ${padRight(m.name, 20)}${padRight(type, 20)}${c.gray(req)}`));
+      lines.push(indent(`  ${padRight(m.name ?? "", 20)}${padRight(type, 20)}${c.gray(req)}`));
     }
     if (remaining > 0) {
       lines.push(indent(c.gray(`  ... ${remaining} more`)));
@@ -2966,6 +3104,8 @@ function extractPropsFromSchema(schema) {
 function formatType(schema) {
   if (!schema)
     return "unknown";
+  if (typeof schema === "string")
+    return schema;
   if (schema.$ref)
     return schema.$ref.replace("#/types/", "");
   if (schema.type === "array" && schema.items)
@@ -3037,14 +3177,72 @@ function looksLikeFilePath(s) {
 
 // src/commands/get.ts
 function registerGetCommand(program) {
-  program.command("get <nameOrEntry> [name]").description("Get detailed spec for a single export").action(async (nameOrEntry, name) => {
+  program.command("get <nameOrEntry> [name]").description("Get detailed spec for a single export").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (nameOrEntry, name, options = {}) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry: name ? nameOrEntry : undefined,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript") {
+        const entryArg = name ? nameOrEntry : undefined;
+        const exportName2 = name ?? nameOrEntry;
+        const { apiSpec } = await resolveTruth({
+          entry: entryArg,
+          lang,
+          spec: options.spec,
+          abi: options.abi
+        });
+        const allExports = apiSpec.exports ?? [];
+        const exp = allExports.find((e) => e.name === exportName2 || e.id === exportName2);
+        if (!exp) {
+          const suggestions = fuzzyTop(exportName2, allExports);
+          renderNotFound(exportName2, suggestions, startTime, version);
+          return;
+        }
+        const sig = exp.signatures?.[0];
+        const data = {
+          export: {
+            name: exp.name,
+            kind: exp.kind,
+            ...exp.description ? { description: exp.description } : {},
+            ...exp.deprecated ? { deprecated: true } : {},
+            ...sig?.parameters ? {
+              parameters: sig.parameters.map((p) => ({
+                name: p.name,
+                type: schemaTypeString(p.schema),
+                required: p.required,
+                ...p.description ? { description: p.description } : {},
+                schema: p.schema
+              }))
+            } : {},
+            ...sig?.returns ? {
+              returns: {
+                type: schemaTypeString(sig.returns.schema),
+                ...sig.returns.description ? { description: sig.returns.description } : {},
+                schema: sig.returns.schema
+              }
+            } : {},
+            ...exp.members ? {
+              members: exp.members.map((m) => ({
+                name: m.name,
+                ...m.description ? { description: m.description } : {}
+              }))
+            } : {},
+            ...exp.schema ? { schema: exp.schema } : {},
+            ...exp.flags ? { flags: exp.flags } : {}
+          }
+        };
+        formatOutput("get", data, startTime, version, renderGet);
+        return;
+      }
       let entryFile;
       let exportName;
       if (name) {
-        entryFile = path20.resolve(process.cwd(), nameOrEntry);
+        entryFile = path21.resolve(process.cwd(), nameOrEntry);
         exportName = name;
       } else {
         entryFile = detectEntry();
@@ -3054,39 +3252,63 @@ function registerGetCommand(program) {
       if (!result.export) {
         const listResult = await listExports({ entryFile });
         const suggestions = fuzzyTop(exportName, listResult.exports);
-        if (suggestions.length > 0 && shouldRenderHuman()) {
-          const lines = [
-            "",
-            indent(`${c.red("x")} Export "${exportName}" not found.`),
-            "",
-            indent(c.gray("Similar:"))
-          ];
-          for (const s of suggestions) {
-            lines.push(indent(`  ${s}`));
-          }
-          lines.push("");
-          lines.push(indent(`drift get ${suggestions[0]}`));
-          lines.push("");
-          process.stdout.write(lines.join(`
-`));
-          process.exitCode = 1;
-        } else if (suggestions.length > 0) {
-          formatError("get", `Export '${exportName}' not found. Similar: ${suggestions.join(", ")}`, startTime, version);
-        } else {
-          formatError("get", `Export '${exportName}' not found`, startTime, version);
-        }
+        renderNotFound(exportName, suggestions, startTime, version);
         return;
       }
-      formatOutput("get", { export: result.export, types: result.types }, startTime, version, renderGet);
+      const types = Object.fromEntries((result.types ?? []).map((t) => [
+        t.name,
+        t.schema ?? {}
+      ]));
+      formatOutput("get", { export: result.export, types }, startTime, version, renderGet);
     } catch (err) {
       formatError("get", err instanceof Error ? err.message : String(err), startTime, version);
     }
   });
 }
+function schemaTypeString(schema) {
+  if (schema === undefined || schema === null)
+    return;
+  if (typeof schema === "string")
+    return schema;
+  if (typeof schema === "object") {
+    const s = schema;
+    if (typeof s.$ref === "string")
+      return s.$ref.split("/").pop();
+    if (typeof s.type === "string")
+      return s.type;
+    if (Array.isArray(s.oneOf))
+      return "oneOf";
+    if (Array.isArray(s.anyOf))
+      return "anyOf";
+  }
+  return;
+}
+function renderNotFound(exportName, suggestions, startTime, version) {
+  if (suggestions.length > 0 && shouldRenderHuman()) {
+    const lines = [
+      "",
+      indent(`${c.red("x")} Export "${exportName}" not found.`),
+      "",
+      indent(c.gray("Similar:"))
+    ];
+    for (const s of suggestions) {
+      lines.push(indent(`  ${s}`));
+    }
+    lines.push("");
+    lines.push(indent(`drift get ${suggestions[0]}`));
+    lines.push("");
+    process.stdout.write(lines.join(`
+`));
+    process.exitCode = 1;
+  } else if (suggestions.length > 0) {
+    formatError("get", `Export '${exportName}' not found. Similar: ${suggestions.join(", ")}`, startTime, version);
+  } else {
+    formatError("get", `Export '${exportName}' not found`, startTime, version);
+  }
+}
 
 // src/commands/health.ts
-import { existsSync as existsSync12, readFileSync as readFileSync15 } from "node:fs";
-import * as path21 from "node:path";
+import * as path22 from "node:path";
 import { computeDrift as computeDrift3 } from "@driftdev/sdk";
 
 // src/formatters/health.ts
@@ -3153,23 +3375,21 @@ function computeHealth(totalExports, documented, issues) {
 }
 
 // src/commands/health.ts
-function getPackageInfo(cwd) {
-  const pkgPath = path21.join(cwd, "package.json");
-  if (!existsSync12(pkgPath))
-    return {};
-  try {
-    const pkg = JSON.parse(readFileSync15(pkgPath, "utf-8"));
-    return { name: pkg.name, version: pkg.version };
-  } catch (err) {
-    formatWarning(`Could not parse package.json${err instanceof Error ? `: ${err.message}` : ""}`);
-    return {};
-  }
-}
 function registerHealthCommand(program) {
-  program.command("health [entry]").description("Show documentation health score").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (entry, options) => {
+  program.command("health [entry]").description("Show documentation health score").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript" && options.all) {
+        formatError("health", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
+        return;
+      }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
         if (!allPackages || allPackages.length === 0) {
@@ -3185,8 +3405,8 @@ function registerHealthCommand(program) {
         const rows = [];
         let totalDoc = 0;
         let totalAll = 0;
-        for (const pkg2 of packages) {
-          const { spec: spec2 } = await cachedExtract(pkg2.entry);
+        for (const pkg of packages) {
+          const { spec: spec2 } = await cachedExtract(pkg.entry);
           const exps = spec2.exports ?? [];
           let doc = 0;
           for (const e of exps) {
@@ -3194,7 +3414,7 @@ function registerHealthCommand(program) {
               doc++;
           }
           const score = exps.length > 0 ? Math.round(doc / exps.length * 100) : 100;
-          rows.push({ name: pkg2.name, exports: exps.length, score });
+          rows.push({ name: pkg.name, exports: exps.length, score });
           totalDoc += doc;
           totalAll += exps.length;
         }
@@ -3208,8 +3428,15 @@ function registerHealthCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const entryFile = entry ? path21.resolve(process.cwd(), entry) : config.entry ? path21.resolve(process.cwd(), config.entry) : detectEntry();
-      const { spec } = await cachedExtract(entryFile);
+      let entryFile = entry ? path22.resolve(process.cwd(), entry) : undefined;
+      if (lang === "typescript" && !entryFile) {
+        entryFile = config.entry ? path22.resolve(process.cwd(), config.entry) : detectEntry();
+      }
+      const {
+        apiSpec: spec,
+        packageName,
+        packageVersion
+      } = await resolveTruth({ entry: entryFile, lang, spec: options.spec, abi: options.abi });
       const exports = spec.exports ?? [];
       const total = exports.length;
       let documented = 0;
@@ -3226,11 +3453,10 @@ function registerHealthCommand(program) {
         }
       }
       const health = computeHealth(total, documented, issues);
-      const pkg = getPackageInfo(process.cwd());
       const data = {
         ...health,
-        packageName: pkg.name,
-        packageVersion: pkg.version
+        packageName,
+        packageVersion
       };
       let min = options.min ? parseInt(options.min, 10) : config.coverage?.min;
       if (min !== undefined && config.coverage?.ratchet) {
@@ -3267,7 +3493,7 @@ function registerHealthCommand(program) {
 // src/commands/init.ts
 init_global();
 import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync16, writeFileSync as writeFileSync5 } from "node:fs";
-import * as path22 from "node:path";
+import * as path23 from "node:path";
 import { extract as extract6 } from "@openpkg-ts/sdk";
 import { normalize as normalize7 } from "@openpkg-ts/spec";
 
@@ -3573,10 +3799,10 @@ ${detailLine}`);
 
 // src/commands/init.ts
 async function scanPackage(cwd, pkgDir) {
-  const absDir = path22.join(cwd, pkgDir);
+  const absDir = path23.join(cwd, pkgDir);
   if (!existsSync13(absDir))
     return null;
-  const pkgPath = path22.join(absDir, "package.json");
+  const pkgPath = path23.join(absDir, "package.json");
   let name = pkgDir;
   if (existsSync13(pkgPath)) {
     try {
@@ -3598,7 +3824,7 @@ async function scanPackage(cwd, pkgDir) {
     }
     const coverage = total > 0 ? Math.round(documented / total * 100) : 100;
     const health = Math.round(coverage * 0.5 + 100 * 0.5);
-    return { name, entry: path22.relative(cwd, entryFile), exports: total, coverage, health };
+    return { name, entry: path23.relative(cwd, entryFile), exports: total, coverage, health };
   } catch {
     return null;
   }
@@ -3634,7 +3860,7 @@ function registerInitCommand(program) {
         return;
       }
       const config = generateConfig(packages);
-      const configPath = opts.project ? path22.resolve(cwd, "drift.config.json") : getGlobalConfigPath();
+      const configPath = opts.project ? path23.resolve(cwd, "drift.config.json") : getGlobalConfigPath();
       if (!opts.project) {
         const globalDir = getGlobalDir();
         if (!existsSync13(globalDir))
@@ -3659,7 +3885,7 @@ function registerInitCommand(program) {
 
 // src/commands/lint.ts
 import { readFileSync as readFileSync17 } from "node:fs";
-import * as path23 from "node:path";
+import * as path24 from "node:path";
 import {
   buildExportRegistry,
   computeDrift as computeDrift4,
@@ -3703,10 +3929,20 @@ function renderLint(data, next) {
 
 // src/commands/lint.ts
 function registerLintCommand(program) {
-  program.command("lint [entry]").description("Cross-reference JSDoc against code for accuracy issues").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (entry, options) => {
+  program.command("lint [entry]").description("Cross-reference docs against the API surface for accuracy issues").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript" && options.all) {
+        formatError("lint", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
+        return;
+      }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
         if (!allPackages || allPackages.length === 0) {
@@ -3745,8 +3981,16 @@ function registerLintCommand(program) {
         formatOutput("lint", { issues: [], count: 0 }, startTime, version, renderLint);
         return;
       }
-      const entryFile = entry ? path23.resolve(process.cwd(), entry) : config.entry ? path23.resolve(process.cwd(), config.entry) : detectEntry();
-      const { spec } = await cachedExtract(entryFile);
+      let entryFile = entry ? path24.resolve(process.cwd(), entry) : undefined;
+      if (lang === "typescript" && !entryFile) {
+        entryFile = config.entry ? path24.resolve(process.cwd(), config.entry) : detectEntry();
+      }
+      const { apiSpec: spec } = await resolveTruth({
+        entry: entryFile,
+        lang,
+        spec: options.spec,
+        abi: options.abi
+      });
       const driftResult = computeDrift4(spec);
       const issues = [];
       for (const [exportName, drifts] of driftResult.exports) {
@@ -3760,27 +4004,28 @@ function registerLintCommand(program) {
           });
         }
       }
-      try {
-        const pkgJsonPath = path23.resolve(process.cwd(), "package.json");
-        const pkgJson = JSON.parse(readFileSync17(pkgJsonPath, "utf-8"));
-        const packageName = pkgJson.name;
-        if (packageName) {
-          const registry = buildExportRegistry(spec);
-          const markdownFiles = discoverMarkdownFiles(process.cwd(), config.docs);
-          const proseDrifts = detectProseDrift({ packageName, markdownFiles, registry });
-          for (const drift of proseDrifts) {
-            issues.push({
-              export: drift.target ?? "",
-              issue: drift.issue,
-              ...drift.suggestion ? { location: drift.suggestion } : {},
-              filePath: drift.filePath,
-              line: drift.line
-            });
+      if (lang === "typescript")
+        try {
+          const pkgJsonPath = path24.resolve(process.cwd(), "package.json");
+          const pkgJson = JSON.parse(readFileSync17(pkgJsonPath, "utf-8"));
+          const packageName = pkgJson.name;
+          if (packageName) {
+            const registry = buildExportRegistry(spec);
+            const markdownFiles = discoverMarkdownFiles(process.cwd(), config.docs);
+            const proseDrifts = detectProseDrift({ packageName, markdownFiles, registry });
+            for (const drift of proseDrifts) {
+              issues.push({
+                export: drift.target ?? "",
+                issue: drift.issue,
+                ...drift.suggestion ? { location: drift.suggestion } : {},
+                filePath: drift.filePath,
+                line: drift.line
+              });
+            }
           }
+        } catch (err) {
+          formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
         }
-      } catch (err) {
-        formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
-      }
       const data = { issues, count: issues.length };
       const next = issues.length > 0 ? {
         suggested: "drift-fix skill",
@@ -3804,7 +4049,7 @@ function registerLintCommand(program) {
 }
 
 // src/commands/list.ts
-import * as path24 from "node:path";
+import * as path25 from "node:path";
 import { computeDrift as computeDrift5 } from "@driftdev/sdk";
 import { listExports as listExports2 } from "@openpkg-ts/sdk";
 
@@ -3861,10 +4106,20 @@ function renderList(data) {
 
 // src/commands/list.ts
 function registerListCommand(program) {
-  program.command("list [searchOrEntry]").description("List exports (positional arg = search term or entry file)").option("--kind <kinds>", "Filter by kind (comma-separated)").option("--undocumented", "Only exports missing JSDoc").option("--drifted", "Only exports with stale JSDoc").option("--full", "Show full list (no truncation)").option("--all", "Run across all workspace packages").action(async (searchOrEntry, options) => {
+  program.command("list [searchOrEntry]").description("List exports (positional arg = search term or entry file)").option("--kind <kinds>", "Filter by kind (comma-separated)").option("--undocumented", "Only exports missing docs").option("--drifted", "Only exports with stale docs").option("--full", "Show full list (no truncation)").option("--all", "Run across all workspace packages").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (searchOrEntry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = resolveLang({
+        entry: searchOrEntry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
+      if (lang !== "typescript" && options.all) {
+        formatError("list", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
+        return;
+      }
       if (options.all) {
         const packages = discoverPackages(process.cwd());
         if (!packages || packages.length === 0) {
@@ -3884,23 +4139,50 @@ function registerListCommand(program) {
         formatOutput("list", { packages: rows, filter: filter2 }, startTime, version, renderBatchList);
         return;
       }
-      let entryFile;
       let searchTerm;
-      if (searchOrEntry && looksLikeFilePath(searchOrEntry)) {
-        entryFile = path24.resolve(process.cwd(), searchOrEntry);
-      } else if (searchOrEntry) {
-        entryFile = detectEntry();
-        searchTerm = searchOrEntry;
+      let exports;
+      let driftedNames;
+      if (lang !== "typescript") {
+        const entryArg = lang === "clarity" ? searchOrEntry : undefined;
+        if (lang === "openapi")
+          searchTerm = searchOrEntry;
+        const { apiSpec } = await resolveTruth({
+          entry: entryArg,
+          lang,
+          spec: options.spec,
+          abi: options.abi
+        });
+        exports = (apiSpec.exports ?? []).map((e) => ({
+          name: e.name,
+          kind: e.kind,
+          description: e.description,
+          ...e.deprecated ? { deprecated: true } : {}
+        }));
+        if (options.drifted) {
+          driftedNames = new Set(computeDrift5(apiSpec).exports.keys());
+        }
       } else {
-        entryFile = detectEntry();
+        let entryFile;
+        if (searchOrEntry && looksLikeFilePath(searchOrEntry)) {
+          entryFile = path25.resolve(process.cwd(), searchOrEntry);
+        } else if (searchOrEntry) {
+          entryFile = detectEntry();
+          searchTerm = searchOrEntry;
+        } else {
+          entryFile = detectEntry();
+        }
+        const result = await listExports2({ entryFile });
+        exports = result.exports.map((e) => ({
+          name: e.name,
+          kind: e.kind,
+          description: e.description,
+          ...e.deprecated ? { deprecated: true } : {}
+        }));
+        if (options.drifted) {
+          const { spec } = await cachedExtract(entryFile);
+          driftedNames = new Set(computeDrift5(spec).exports.keys());
+        }
       }
-      const result = await listExports2({ entryFile });
-      let exports = result.exports.map((e) => ({
-        name: e.name,
-        kind: e.kind,
-        description: e.description,
-        ...e.deprecated ? { deprecated: true } : {}
-      }));
       if (options.kind) {
         const kinds = new Set(options.kind.split(",").map((k) => k.trim().toLowerCase()));
         exports = exports.filter((e) => kinds.has(e.kind));
@@ -3908,11 +4190,9 @@ function registerListCommand(program) {
       if (options.undocumented) {
         exports = exports.filter((e) => !e.description || e.description.trim().length === 0);
       }
-      if (options.drifted) {
-        const { spec } = await cachedExtract(entryFile);
-        const driftResult = computeDrift5(spec);
-        const driftedNames = new Set(driftResult.exports.keys());
-        exports = exports.filter((e) => driftedNames.has(e.name));
+      if (driftedNames) {
+        const names = driftedNames;
+        exports = exports.filter((e) => names.has(e.name));
       }
       if (searchTerm) {
         const matches = fuzzySearch(searchTerm, exports);
@@ -3937,10 +4217,166 @@ function registerListCommand(program) {
   });
 }
 
+// src/commands/mcp.ts
+import { spawn } from "node:child_process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var truthShape = {
+  cwd: z.string().optional().describe("Directory to run in (project root; where package.json/config live)"),
+  entry: z.string().optional().describe("Entry file: TypeScript entry or Clarity .clar source. Omit for OpenAPI specs."),
+  lang: z.enum(["typescript", "clarity", "openapi"]).optional().describe("Source language override; inferred from spec/abi/.clar extension otherwise"),
+  spec: z.string().optional().describe("OpenAPI 3.x JSON document — local path or https URL. Implies lang=openapi."),
+  abi: z.string().optional().describe("Clarity ABI JSON path (required for Clarity sources)")
+};
+function truthFlags(args) {
+  const out = [];
+  if (args.lang)
+    out.push("--lang", args.lang);
+  if (args.spec)
+    out.push("--spec", args.spec);
+  if (args.abi)
+    out.push("--abi", args.abi);
+  return out;
+}
+function runDrift(cliArgs, cwd) {
+  return new Promise((resolve18) => {
+    const child = spawn(process.execPath, [process.argv[1], ...cliArgs, "--json"], {
+      cwd: cwd ?? process.cwd(),
+      env: { ...process.env, NO_COLOR: "1" },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => {
+      stdout += d;
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d;
+    });
+    child.on("close", (code) => {
+      const text = stdout.trim() || stderr.trim() || `drift exited with code ${code}`;
+      let ok = code === 0;
+      try {
+        ok = JSON.parse(stdout).ok === true;
+      } catch {}
+      resolve18({ text, ok });
+    });
+    child.on("error", (err) => resolve18({ text: `Failed to run drift: ${err.message}`, ok: false }));
+  });
+}
+function toResult({ text, ok }) {
+  return { content: [{ type: "text", text }], isError: !ok };
+}
+function registerMcpCommand(program) {
+  program.command("mcp").description("Run an MCP stdio server exposing drift tools to agents").action(async () => {
+    const server = new McpServer({ name: "drift", version: getVersion() });
+    server.registerTool("drift_extract", {
+      title: "Extract API spec",
+      description: "Extract the full machine-readable API spec from a source of truth: a TypeScript package (entry auto-detected from cwd), an OpenAPI 3.x document (spec path/URL), or a Clarity contract (entry .clar + abi). Returns every export with signatures, types, and docs. This is ground truth — use it instead of assuming what an API looks like.",
+      inputSchema: truthShape
+    }, async (args) => toResult(await runDrift(["extract", ...args.entry ? [args.entry] : [], ...truthFlags(args)], args.cwd)));
+    server.registerTool("drift_list", {
+      title: "List exports/operations",
+      description: "List every export (TypeScript), operation (OpenAPI), or function (Clarity) in an API surface: name, kind, one-line description, deprecated flag. Cheap way to check what exists before drilling in with drift_get. Supports filtering to undocumented or drifted items.",
+      inputSchema: {
+        ...truthShape,
+        search: z.string().optional().describe("Fuzzy search term"),
+        kind: z.string().optional().describe("Filter by kind (comma-separated)"),
+        undocumented: z.boolean().optional().describe("Only items missing docs"),
+        drifted: z.boolean().optional().describe("Only items whose docs drifted")
+      }
+    }, async (args) => {
+      const cli = ["list"];
+      if (args.entry)
+        cli.push(args.entry);
+      else if (args.search)
+        cli.push(args.search);
+      if (args.kind)
+        cli.push("--kind", args.kind);
+      if (args.undocumented)
+        cli.push("--undocumented");
+      if (args.drifted)
+        cli.push("--drifted");
+      cli.push("--full");
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
+    server.registerTool("drift_get", {
+      title: "Get one export/operation",
+      description: "Get the authoritative definition of a single export, endpoint operation, or contract function by name: parameters with types/required/descriptions, return shape, deprecation, referenced types. Use this to verify every claim a docs page makes — one drift_get per claim, never from memory. Unknown names return fuzzy suggestions.",
+      inputSchema: {
+        ...truthShape,
+        name: z.string().describe("Export/operation name (e.g. candidateInfo, transfer, createClient)")
+      }
+    }, async (args) => {
+      const cli = ["get"];
+      if (args.entry)
+        cli.push(args.entry, args.name);
+      else
+        cli.push(args.name);
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
+    server.registerTool("drift_scan", {
+      title: "Scan docs health",
+      description: "Full docs-drift scan of an API surface: coverage score, drift issues with file/line locations, health score. The one-shot summary — use drift_list/drift_get for targeted follow-up.",
+      inputSchema: {
+        ...truthShape,
+        min: z.number().optional().describe("Minimum health threshold (result.pass=false below it)")
+      }
+    }, async (args) => {
+      const cli = ["scan"];
+      if (args.entry)
+        cli.push(args.entry);
+      if (args.min !== undefined)
+        cli.push("--min", String(args.min));
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
+    server.registerTool("drift_diff", {
+      title: "Diff two API specs",
+      description: "Diff two extracted API specs (TypeScript only today): spec files or git refs. Reports added/removed/changed exports. Useful for changelog and release-note verification.",
+      inputSchema: {
+        cwd: truthShape.cwd,
+        old: z.string().optional().describe("Old spec file path"),
+        new: z.string().optional().describe("New spec file path"),
+        base: z.string().optional().describe("Git ref for old spec (alternative to files)"),
+        head: z.string().optional().describe("Git ref for new spec (default: working tree)"),
+        entry: z.string().optional().describe("Entry file for git ref extraction")
+      }
+    }, async (args) => toResult(await runDrift(diffArgs("diff", args), args.cwd)));
+    server.registerTool("drift_breaking", {
+      title: "Detect breaking changes",
+      description: "Detect breaking API changes between two specs or git refs (TypeScript only today). Use to check whether docs claiming compatibility are still true.",
+      inputSchema: {
+        cwd: truthShape.cwd,
+        old: z.string().optional().describe("Old spec file path"),
+        new: z.string().optional().describe("New spec file path"),
+        base: z.string().optional().describe("Git ref for old spec (alternative to files)"),
+        head: z.string().optional().describe("Git ref for new spec (default: working tree)"),
+        entry: z.string().optional().describe("Entry file for git ref extraction")
+      }
+    }, async (args) => toResult(await runDrift(diffArgs("breaking", args), args.cwd)));
+    await server.connect(new StdioServerTransport);
+  });
+}
+function diffArgs(command, args) {
+  const cli = [command];
+  if (args.old)
+    cli.push(args.old);
+  if (args.new)
+    cli.push(args.new);
+  if (args.base)
+    cli.push("--base", args.base);
+  if (args.head)
+    cli.push("--head", args.head);
+  if (args.entry)
+    cli.push("--entry", args.entry);
+  return cli;
+}
+
 // src/commands/release.ts
 import { execSync as execSync4 } from "node:child_process";
 import { existsSync as existsSync14, readFileSync as readFileSync18 } from "node:fs";
-import * as path25 from "node:path";
+import * as path26 from "node:path";
 import { computeDrift as computeDrift6 } from "@driftdev/sdk";
 
 // src/formatters/release.ts
@@ -3988,7 +4424,7 @@ function getLastTag() {
   }
 }
 function getPackageVersion(cwd) {
-  const pkgPath = path25.join(cwd, "package.json");
+  const pkgPath = path26.join(cwd, "package.json");
   if (!existsSync14(pkgPath))
     return null;
   try {
@@ -4004,7 +4440,7 @@ function registerReleaseCommand(program) {
     const cwd = process.cwd();
     try {
       const { config } = loadConfig();
-      const entryFile = entry ? path25.resolve(cwd, entry) : config.entry ? path25.resolve(cwd, config.entry) : detectEntry();
+      const entryFile = entry ? path26.resolve(cwd, entry) : config.entry ? path26.resolve(cwd, config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
       const total = exports.length;
@@ -4129,7 +4565,7 @@ function renderReport(data) {
 // src/utils/scan-packages.ts
 import { execSync as execSync5 } from "node:child_process";
 import { existsSync as existsSync15, readFileSync as readFileSync19 } from "node:fs";
-import * as path26 from "node:path";
+import * as path27 from "node:path";
 import { computeDrift as computeDrift7 } from "@driftdev/sdk";
 function detectPackageDirs2(cwd) {
   const workspaces = detectWorkspaces(cwd);
@@ -4148,11 +4584,11 @@ async function scanAllPackages(cwd) {
   const packageDirs = detectPackageDirs2(cwd);
   const results = [];
   for (const dir of packageDirs) {
-    const absDir = dir === "." ? cwd : path26.join(cwd, dir);
+    const absDir = dir === "." ? cwd : path27.join(cwd, dir);
     if (!existsSync15(absDir))
       continue;
     let name = dir;
-    const pkgPath = path26.join(absDir, "package.json");
+    const pkgPath = path27.join(absDir, "package.json");
     if (existsSync15(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
@@ -4251,10 +4687,8 @@ function registerReportCommand(program) {
 }
 
 // src/commands/scan.ts
-import { existsSync as existsSync16, readFileSync as readFileSync20 } from "node:fs";
-import * as path27 from "node:path";
-import { fromSource } from "@driftdev/clarity-adapter";
-import { fromDocument } from "@driftdev/openapi-adapter";
+import { readFileSync as readFileSync20 } from "node:fs";
+import * as path28 from "node:path";
 import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
@@ -4321,59 +4755,17 @@ function renderBatchScan(data) {
 }
 
 // src/commands/scan.ts
-function getPackageInfo2(cwd) {
-  const pkgPath = path27.join(cwd, "package.json");
-  if (!existsSync16(pkgPath))
-    return {};
-  try {
-    const pkg = JSON.parse(readFileSync20(pkgPath, "utf-8"));
-    return { name: pkg.name, version: pkg.version };
-  } catch (err) {
-    formatWarning(`Could not parse package.json${err instanceof Error ? `: ${err.message}` : ""}`);
-    return {};
-  }
-}
-async function loadSpec2(entryFile, lang, abiPath, specPath) {
-  if (lang === "openapi") {
-    if (!specPath)
-      throw new Error("--spec is required when --lang openapi");
-    if (!existsSync16(specPath))
-      throw new Error(`Spec file not found: ${specPath}`);
-    const document = readFileSync20(specPath, "utf-8");
-    const name = path27.basename(specPath, path27.extname(specPath));
-    const apiSpec = fromDocument(document);
-    if (!apiSpec.meta.name || apiSpec.meta.name === "openapi")
-      apiSpec.meta.name = name;
-    return { apiSpec, packageName: apiSpec.meta.name, packageVersion: apiSpec.meta.version };
-  }
-  if (lang === "clarity") {
-    if (!abiPath)
-      throw new Error("--abi is required when --lang clarity");
-    if (!existsSync16(entryFile))
-      throw new Error(`Source file not found: ${entryFile}`);
-    if (!existsSync16(abiPath))
-      throw new Error(`ABI file not found: ${abiPath}`);
-    const source = readFileSync20(entryFile, "utf-8");
-    const abi = JSON.parse(readFileSync20(abiPath, "utf-8"));
-    const name = path27.basename(entryFile, path27.extname(entryFile));
-    const pkg2 = getPackageInfo2(process.cwd());
-    const apiSpec = fromSource(source, abi, { name, version: pkg2.version });
-    return { apiSpec, packageName: pkg2.name ?? name, packageVersion: pkg2.version };
-  }
-  const { spec } = await cachedExtract(entryFile);
-  const pkg = getPackageInfo2(process.cwd());
-  return { apiSpec: spec, packageName: pkg.name, packageVersion: pkg.version };
-}
 function registerScanCommand(program) {
-  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language", "typescript").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document (required for --lang openapi)").action(async (entry, options) => {
+  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const lang = options.lang ?? "typescript";
-      if (lang !== "typescript" && lang !== "clarity" && lang !== "openapi") {
-        formatError("scan", `Unknown language: ${lang}`, startTime, version);
-        return;
-      }
+      const lang = resolveLang({
+        entry,
+        lang: options.lang,
+        spec: options.spec,
+        abi: options.abi
+      });
       if (lang !== "typescript" && options.all) {
         formatError("scan", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
         return;
@@ -4439,12 +4831,16 @@ function registerScanCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const specPath = options.spec ? path27.resolve(process.cwd(), options.spec) : undefined;
-      const entryFile = lang === "openapi" ? specPath : entry ? path27.resolve(process.cwd(), entry) : lang === "clarity" ? (() => {
-        throw new Error("Entry file required for --lang clarity");
-      })() : config.entry ? path27.resolve(process.cwd(), config.entry) : detectEntry();
-      const abiPath = options.abi ? path27.resolve(process.cwd(), options.abi) : undefined;
-      const { apiSpec, packageName, packageVersion } = await loadSpec2(entryFile, lang, abiPath, specPath);
+      let entryFile = entry ? path28.resolve(process.cwd(), entry) : undefined;
+      if (lang === "typescript" && !entryFile) {
+        entryFile = config.entry ? path28.resolve(process.cwd(), config.entry) : detectEntry();
+      }
+      const { apiSpec, packageName, packageVersion } = await resolveTruth({
+        entry: entryFile,
+        lang,
+        spec: options.spec,
+        abi: options.abi
+      });
       const exports = apiSpec.exports ?? [];
       const total = exports.length;
       let documented = 0;
@@ -4468,7 +4864,7 @@ function registerScanCommand(program) {
       }
       if (lang === "typescript") {
         try {
-          const pkgJsonPath = path27.resolve(process.cwd(), "package.json");
+          const pkgJsonPath = path28.resolve(process.cwd(), "package.json");
           const pkgJson = JSON.parse(readFileSync20(pkgJsonPath, "utf-8"));
           const pkgName = pkgJson.name;
           if (pkgName) {
@@ -4576,7 +4972,7 @@ function registerSemverCommand(program) {
 
 // src/commands/validate.ts
 import { readFileSync as readFileSync21 } from "node:fs";
-import * as path28 from "node:path";
+import * as path29 from "node:path";
 import { validateSpec } from "@openpkg-ts/spec";
 
 // src/formatters/validate.ts
@@ -4602,7 +4998,7 @@ function registerValidateCommand(program) {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const filePath = path28.resolve(process.cwd(), file);
+      const filePath = path29.resolve(process.cwd(), file);
       const content = readFileSync21(filePath, "utf-8");
       const spec = JSON.parse(content);
       const result = validateSpec(spec);
@@ -4728,13 +5124,13 @@ function extractCapabilities(program) {
 
 // src/drift.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname3 = path29.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync22(path29.join(__dirname3, "../package.json"), "utf-8"));
+var __dirname3 = path30.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync22(path30.join(__dirname3, "../package.json"), "utf-8"));
 var program = new Command;
-program.name("drift").description("drift — documentation quality for TypeScript, Clarity, and OpenAPI").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").option("--tools", "List all available tools for agent use (JSON)").hook("preAction", (_thisCommand) => {
+program.name("drift").description("drift — detect when your docs drift from your code").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").option("--tools", "List all available tools for agent use (JSON)").hook("preAction", (_thisCommand) => {
   const opts = program.opts();
   if (opts.cwd) {
-    process.chdir(path29.resolve(opts.cwd));
+    process.chdir(path30.resolve(opts.cwd));
   }
   setOutputMode({ json: opts.json, human: opts.human });
   setConfigPath(opts.config);
@@ -4763,6 +5159,7 @@ registerConfigCommand(program);
 registerContextCommand(program);
 registerCacheCommand(program);
 registerCommandsCommand(program);
+registerMcpCommand(program);
 var HUMAN_COMMANDS = new Set(["scan", "ci", "init", "commands"]);
 for (const cmd of program.commands) {
   if (!HUMAN_COMMANDS.has(cmd.name())) {

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.4.0",
-  "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
+  "version": "1.5.0",
+  "description": "Drift CLI - detect when your docs drift from your code",
   "keywords": [
     "typescript",
     "cli",
     "documentation",
     "drift",
     "docs-coverage",
-    "drift-detection"
+    "drift-detection",
+    "openapi",
+    "rest",
+    "api",
+    "agent",
+    "mcp"
   ],
   "homepage": "https://github.com/ryanwaits/drift#readme",
   "repository": {
@@ -42,10 +47,12 @@
     "@driftdev/clarity-adapter": "^1.0.1",
     "@driftdev/openapi-adapter": "^1.0.0",
     "@driftdev/sdk": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@openpkg-ts/sdk": "^0.38.0",
     "@openpkg-ts/spec": "^0.37.0",
     "chalk": "^5.4.1",
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "zod": "^4.2.1"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",