@driftdev/cli 0.41.0 → 1.0.0

package/README.md

@@ -95,7 +95,7 @@ Entry auto-detects from `package.json` (`types`, `exports`, `main`, `module`, `b
 
 ```bash
 # Machine-readable list of all commands + flags
-drift --capabilities
+drift --tools
 ```
 
 ## Global Options

package/dist/drift.js

@@ -578,7 +578,7 @@ function formatOutput(command, data, startTime, version, humanRenderer, next) {
     ...next ? { next } : {}
   };
   if (humanRenderer && shouldRenderHuman()) {
-    process.stdout.write(humanRenderer(data));
+    process.stdout.write(humanRenderer(data, next));
     process.stdout.write(`
 `);
   } else {
@@ -589,12 +589,16 @@ function formatOutput(command, data, startTime, version, humanRenderer, next) {
   }
   return envelope;
 }
-function formatError(command, error, startTime, version) {
+function formatError(command, error, startTime, version, suggestion) {
   const duration = Date.now() - startTime;
   if (shouldRenderHuman()) {
     process.stdout.write(`
   ${c.red("x")} ${error}
-
+`);
+    if (suggestion)
+      process.stdout.write(`  ${c.gray(suggestion)}
+`);
+    process.stdout.write(`
 `);
   } else {
     const envelope = {
@@ -609,6 +613,15 @@ function formatError(command, error, startTime, version) {
   }
   process.exitCode = 1;
 }
+function formatWarning(message) {
+  if (shouldRenderHuman()) {
+    process.stderr.write(`  ${c.yellow("!")} ${message}
+`);
+  } else {
+    process.stderr.write(`warning: ${message}
+`);
+  }
+}
 
 // src/utils/resolve-specs.ts
 import { readFileSync as readFileSync5 } from "node:fs";
@@ -845,35 +858,43 @@ function filterPublic(packages) {
 // src/utils/detect-entry.ts
 function detectEntry(cwd = process.cwd()) {
   const pkgPath = path6.join(cwd, "package.json");
+  const tried = [];
+  function tryResolve(source, filePath) {
+    const resolved = resolveToSource(cwd, filePath);
+    if (resolved)
+      return resolved;
+    tried.push(`${source}: ${filePath} -> not found`);
+    return null;
+  }
   if (existsSync6(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
       const typesField = pkg.types || pkg.typings;
       if (typesField && typeof typesField === "string") {
-        const resolved = resolveToSource(cwd, typesField);
+        const resolved = tryResolve("types", typesField);
         if (resolved)
           return resolved;
       }
       if (pkg.exports && typeof pkg.exports === "object") {
         const dot = pkg.exports["."];
         for (const candidate of collectExportCandidates(dot)) {
-          const resolved = resolveToSource(cwd, candidate);
+          const resolved = tryResolve('exports["."]', candidate);
           if (resolved)
             return resolved;
         }
       }
       if (pkg.main && typeof pkg.main === "string") {
-        const resolved = resolveToSource(cwd, pkg.main);
+        const resolved = tryResolve("main", pkg.main);
         if (resolved)
           return resolved;
       }
       if (pkg.module && typeof pkg.module === "string") {
-        const resolved = resolveToSource(cwd, pkg.module);
+        const resolved = tryResolve("module", pkg.module);
         if (resolved)
           return resolved;
       }
       for (const binPath of collectBinCandidates(pkg.bin)) {
-        const resolved = resolveToSource(cwd, binPath);
+        const resolved = tryResolve("bin", binPath);
         if (resolved)
           return resolved;
       }
@@ -892,22 +913,28 @@ function detectEntry(cwd = process.cwd()) {
     const full = path6.join(cwd, f);
     if (existsSync6(full))
       return full;
+    tried.push(`fallback: ${f} -> not found`);
   }
   const workspaces = detectWorkspaces(cwd);
   if (workspaces) {
     const dirs = resolveGlobs(cwd, workspaces);
-    const lines = ["Monorepo detected. Use --cwd <pkg> or --all.", "", "  Packages:"];
+    const lines2 = ["Monorepo detected. Use --cwd <pkg> or --all.", "", "  Packages:"];
     for (const dir of dirs) {
-      lines.push(`    ${dir}`);
+      lines2.push(`    ${dir}`);
     }
-    lines.push("", "  Examples:", `    drift coverage --cwd ${dirs[0] ?? "packages/foo"}`, "    drift coverage --all");
-    throw new Error(lines.join(`
+    lines2.push("", "  Examples:", `    drift coverage --cwd ${dirs[0] ?? "packages/foo"}`, "    drift coverage --all");
+    throw new Error(lines2.join(`
 `));
   }
-  throw new Error(`Could not detect entry point.
-
-  Try: drift list src/index.ts
-    or: cd my-package && drift list`);
+  const lines = ["Could not detect entry point."];
+  if (tried.length > 0) {
+    lines.push("", "  Tried:");
+    for (const t of tried)
+      lines.push(`    ${t}`);
+  }
+  lines.push("", "  Try: drift scan ./path/to/entry.ts");
+  throw new Error(lines.join(`
+`));
 }
 function resolveToSource(cwd, filePath) {
   const normalized = filePath.replace(/^\.\//, "");
@@ -1134,6 +1161,26 @@ function registerBreakingCommand(program) {
   });
 }
 
+// src/commands/commands.ts
+var GROUPS = {
+  Composed: ["scan", "ci", "health"],
+  Analysis: ["coverage", "lint", "examples"],
+  Extraction: ["extract", "list", "get"],
+  Comparison: ["diff", "breaking", "semver", "changelog"],
+  Setup: ["init", "config", "context"],
+  Plumbing: ["validate", "filter", "cache", "report", "release"]
+};
+function registerCommandsCommand(program) {
+  program.command("commands").description("List all available commands grouped by category").action(() => {
+    const maxGroup = Math.max(...Object.keys(GROUPS).map((g) => g.length));
+    for (const [group, cmds] of Object.entries(GROUPS)) {
+      const pad2 = " ".repeat(maxGroup - group.length);
+      process.stdout.write(`  ${group}${pad2}   ${cmds.join(", ")}
+`);
+    }
+  });
+}
+
 // src/formatters/cache.ts
 function renderCacheStatus(data) {
   const lines = [];
@@ -1392,11 +1439,11 @@ function renderContextMarkdown(data) {
       if (pkg.issues && pkg.issues.length > 0) {
         lines.push(`### ${pkg.name} — Issues`);
         lines.push("");
-        lines.push("| Export | Type | Location | Fixable |");
-        lines.push("|--------|------|----------|---------|");
+        lines.push("| Export | Type | Location |");
+        lines.push("|--------|------|----------|");
         for (const issue of pkg.issues) {
           const loc = issue.filePath ? `${issue.filePath}${issue.line ? `:${issue.line}` : ""}` : "—";
-          lines.push(`| ${issue.export} | ${issue.type} | ${loc} | ${issue.fixable ? "yes" : "no"} |`);
+          lines.push(`| ${issue.export} | ${issue.type} | ${loc} |`);
         }
         lines.push("");
       }
@@ -1778,7 +1825,9 @@ function registerCiCommand(program) {
               name = pkg.name;
             if (pkg.private === true)
               isPrivate = true;
-          } catch {}
+          } catch (err) {
+            formatWarning(`Could not parse package.json for ${dir}${err instanceof Error ? `: ${err.message}` : ""}`);
+          }
         }
         if (isPrivate && !options.private) {
           skipped.push(name);
@@ -1850,7 +1899,8 @@ function registerCiCommand(program) {
             diff,
             undocumented
           });
-        } catch {
+        } catch (err) {
+          formatWarning(`Analysis failed for ${name}: ${err instanceof Error ? err.message : String(err)}`);
           results.push({
             name,
             coverage: 0,
@@ -2063,7 +2113,7 @@ function registerConfigCommand(program) {
 import { execSync as execSync3 } from "node:child_process";
 import { readFileSync as readFileSync12 } from "node:fs";
 import * as path14 from "node:path";
-import { computeDrift as computeDrift2, isFixableDrift } from "@driftdev/sdk";
+import { computeDrift as computeDrift2 } from "@driftdev/sdk";
 
 // src/formatters/context.ts
 function renderContext(data) {
@@ -2116,8 +2166,7 @@ function buildPackageContext(name, spec) {
         type: drift.type,
         issue: drift.issue,
         filePath: drift.filePath ?? exp?.source?.file,
-        line: drift.line ?? exp?.source?.line,
-        fixable: isFixableDrift(drift)
+        line: drift.line ?? exp?.source?.line
       });
     }
   }
@@ -2150,7 +2199,8 @@ function registerContextCommand(program) {
             try {
               const { spec } = await cachedExtract(pkg.entry);
               packages.push(buildPackageContext(pkg.name, spec));
-            } catch {
+            } catch (err) {
+              formatWarning(`Extraction failed for ${pkg.name}: ${err instanceof Error ? err.message : String(err)}`);
               packages.push({
                 name: pkg.name,
                 coverage: 0,
@@ -3036,7 +3086,7 @@ import * as path21 from "node:path";
 import { computeDrift as computeDrift3 } from "@driftdev/sdk";
 
 // src/formatters/health.ts
-function renderHealth(data) {
+function renderHealth(data, next) {
   const lines = [""];
   if (data.packageName) {
     const ver = data.packageVersion ? ` v${data.packageVersion}` : "";
@@ -3069,8 +3119,8 @@ function renderHealth(data) {
   } else {
     lines.push(indent(`${c.green(sym.ok)} Health ${data.health}%`));
   }
-  if (data.health < 100) {
-    lines.push(indent(c.gray("Fix with /drift-fix in Claude Code, or see details: drift list --drifted")));
+  if (next) {
+    lines.push(indent(c.gray(`-> Next: ${next.suggested}  (${next.reason})`)));
   }
   lines.push("");
   return lines.join(`
@@ -3106,7 +3156,8 @@ function getPackageInfo(cwd) {
   try {
     const pkg = JSON.parse(readFileSync15(pkgPath, "utf-8"));
     return { name: pkg.name, version: pkg.version };
-  } catch {
+  } catch (err) {
+    formatWarning(`Could not parse package.json${err instanceof Error ? `: ${err.message}` : ""}`);
     return {};
   }
 }
@@ -3609,12 +3660,11 @@ import {
   buildExportRegistry,
   computeDrift as computeDrift4,
   detectProseDrift,
-  discoverMarkdownFiles,
-  isFixableDrift as isFixableDrift2
+  discoverMarkdownFiles
 } from "@driftdev/sdk";
 
 // src/formatters/lint.ts
-function renderLint(data) {
+function renderLint(data, next) {
   const lines = [""];
   if (data.count === 0) {
     lines.push(indent(`${c.green("ok")} No issues found`));
@@ -3639,6 +3689,9 @@ function renderLint(data) {
     lines.push("");
   }
   lines.push(indent(`${data.count} issue${data.count === 1 ? "" : "s"} found`));
+  if (next) {
+    lines.push(indent(c.gray(`-> Next: ${next.suggested}  (${next.reason})`)));
+  }
   lines.push("");
   return lines.join(`
 `);
@@ -3721,18 +3774,13 @@ function registerLintCommand(program) {
             });
           }
         }
-      } catch {}
-      const data = { issues, count: issues.length };
-      let fixableCount = 0;
-      for (const [, drifts] of driftResult.exports) {
-        for (const d of drifts) {
-          if (isFixableDrift2(d))
-            fixableCount++;
-        }
+      } 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",
-        reason: `${fixableCount} of ${issues.length} issues are auto-fixable`
+        reason: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`
       } : undefined;
       formatOutput("lint", data, startTime, version, renderLint, next);
       if (issues.length > 0) {
@@ -4205,12 +4253,11 @@ import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
   detectProseDrift as detectProseDrift2,
-  discoverMarkdownFiles as discoverMarkdownFiles2,
-  isFixableDrift as isFixableDrift3
+  discoverMarkdownFiles as discoverMarkdownFiles2
 } from "@driftdev/sdk";
 
 // src/formatters/scan.ts
-function renderScan(data) {
+function renderScan(data, next) {
   const lines = [""];
   if (data.packageName) {
     const ver = data.packageVersion ? ` v${data.packageVersion}` : "";
@@ -4241,6 +4288,9 @@ function renderScan(data) {
   } else {
     lines.push(indent(`${c.red(sym.x)} Scan failed`));
   }
+  if (next) {
+    lines.push(indent(c.gray(`-> Next: ${next.suggested}  (${next.reason})`)));
+  }
   lines.push("");
   return lines.join(`
 `);
@@ -4272,7 +4322,8 @@ function getPackageInfo2(cwd) {
   try {
     const pkg = JSON.parse(readFileSync20(pkgPath, "utf-8"));
     return { name: pkg.name, version: pkg.version };
-  } catch {
+  } catch (err) {
+    formatWarning(`Could not parse package.json${err instanceof Error ? `: ${err.message}` : ""}`);
     return {};
   }
 }
@@ -4375,7 +4426,9 @@ function registerScanCommand(program) {
             });
           }
         }
-      } catch {}
+      } catch (err) {
+        formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
       const healthIssues = issues.map((i) => ({ export: i.export, issue: i.issue }));
       const h = computeHealth(total, documented, healthIssues);
       const pkg = getPackageInfo2(process.cwd());
@@ -4395,16 +4448,9 @@ function registerScanCommand(program) {
       };
       let next;
       if (issues.length > 0) {
-        let fixableCount = 0;
-        for (const [, drs] of driftResult.exports) {
-          for (const d of drs) {
-            if (isFixableDrift3(d))
-              fixableCount++;
-          }
-        }
         next = {
           suggested: "drift-fix skill",
-          reason: `${fixableCount} of ${issues.length} issues are auto-fixable`
+          reason: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`
         };
       } else if (total - documented > 0) {
         next = {
@@ -4599,11 +4645,11 @@ function extractCapabilities(program) {
       }
     ],
     workflows: {
-      "detect-drift": ["extract", "lint"],
-      "full-scan": ["scan"],
-      "detect-and-enrich": ["scan", "context"],
-      "ci-pipeline": ["ci"],
-      "pre-release": ["scan", "breaking", "release"]
+      "detect-drift": { steps: ["extract", "lint"], description: "Find stale JSDoc and prose drift" },
+      "full-scan": { steps: ["scan"], description: "Coverage + lint + prose in one pass" },
+      "detect-and-enrich": { steps: ["scan", "context"], description: "Scan and generate agent context" },
+      "ci-pipeline": { steps: ["ci"], description: "Run CI checks on changed packages" },
+      "pre-release": { steps: ["scan", "breaking", "release"], description: "Full pre-release quality gate" }
     }
   };
 }
@@ -4644,12 +4690,17 @@ registerInitCommand(program);
 registerConfigCommand(program);
 registerContextCommand(program);
 registerCacheCommand(program);
-var HUMAN_COMMANDS = new Set(["scan", "ci", "init"]);
+registerCommandsCommand(program);
+var HUMAN_COMMANDS = new Set(["scan", "ci", "init", "commands"]);
 for (const cmd of program.commands) {
   if (!HUMAN_COMMANDS.has(cmd.name())) {
     cmd._hidden = true;
   }
 }
+program.addHelpText("after", `
+Agent mode:
+  drift --tools    JSON manifest of all commands for agent use
+`);
 if (process.argv.includes("--tools")) {
   const caps = extractCapabilities(program);
   process.stdout.write(`${JSON.stringify(caps, null, 2)}
@@ -4660,9 +4711,7 @@ var rawArgs = process.argv.slice(2);
 var hasHelpOrVersion = rawArgs.some((a) => ["-h", "--help", "-V", "--version", "--tools"].includes(a));
 var userArgs = rawArgs.filter((a) => !a.startsWith("-"));
 if (userArgs.length === 0 && !hasHelpOrVersion) {
-  const { configPath } = loadConfig();
-  const subcommand = configPath ? "scan" : "init";
-  process.argv.splice(2, 0, subcommand);
+  process.argv.splice(2, 0, "scan");
 }
 program.parseAsync().catch(() => {
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "0.41.0",
+  "version": "1.0.0",
   "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -43,7 +43,7 @@
     "dist"
   ],
   "dependencies": {
-    "@driftdev/sdk": "^0.41.0",
+    "@driftdev/sdk": "^1.0.0",
     "@openpkg-ts/sdk": "^0.37.0",
     "@openpkg-ts/spec": "^0.37.0",
     "chalk": "^5.4.1",