@driftdev/cli 0.42.0 → 1.0.0

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(/^\.\//, "");
@@ -1798,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);
@@ -1870,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,
@@ -2169,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,
@@ -3055,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}` : "";
@@ -3088,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(`
@@ -3125,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 {};
   }
 }
@@ -3632,7 +3664,7 @@ import {
 } 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`));
@@ -3657,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(`
 `);
@@ -3739,7 +3774,9 @@ function registerLintCommand(program) {
             });
           }
         }
-      } catch {}
+      } 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",
@@ -4220,7 +4257,7 @@ import {
 } 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}` : "";
@@ -4251,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(`
 `);
@@ -4282,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 {};
   }
 }
@@ -4385,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());
@@ -4602,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" }
     }
   };
 }
@@ -4654,6 +4697,10 @@ for (const cmd of program.commands) {
     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)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "0.42.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.42.0",
+    "@driftdev/sdk": "^1.0.0",
     "@openpkg-ts/sdk": "^0.37.0",
     "@openpkg-ts/spec": "^0.37.0",
     "chalk": "^5.4.1",