@davidbalzan/groundwork 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidbalzan/groundwork",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Groundwork — an installable AI development workflow (skills + doc methodology) you bolt onto any repo.",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   "author": "David Balzan",
   "license": "MIT",
   "dependencies": {
-    "@davidbalzan/groundwork-seam": "0.1.1"
+    "@davidbalzan/groundwork-seam": "0.1.2"
   },
   "scripts": {
     "groundwork": "node src/cli.mjs",

package/src/cli.mjs

@@ -55,7 +55,7 @@ function help() {
       `  --json             machine-readable output (doctor / status / list)`,
       "",
       bold("Examples:"),
-      dim("  npx github:davidbalzan/groundwork init"),
+      dim("  npm i -g @davidbalzan/groundwork && groundwork init"),
       dim("  groundwork init . --minimal"),
       dim("  groundwork add data-layer"),
       dim("  groundwork status"),

package/src/commands/doctor.mjs

@@ -26,8 +26,26 @@ export function collectDoctor(targetDir) {
 
   const checks = [];
   const push = (check, level, items) => checks.push({ check, level, items });
+  // A broken check degrades to a named skip instead of taking the whole doctor
+  // down (field crash 2026-08-21: a TypeError from one check aborted the run
+  // and every later check with it, including the pure-fs ones). Doctor never
+  // writes anything — a skipped check must not tempt anyone to "fix" a target
+  // into existence.
+  const skipped = [];
+  const guard = (name, fn) => {
+    try {
+      fn();
+    } catch (e) {
+      skipped.push(name);
+      push(name, "info", [
+        `check skipped — ${String(e?.message ?? e).split("\n")[0]} (doctor kept going; other checks are unaffected)`,
+      ]);
+    }
+  };
   const mdFiles = [...walk(docs)].filter((f) => f.endsWith(".md"));
+  const phaseDir = path.join(docs, "phases");
 
+  guard("orphan-wikilinks", () => {
   const valid = validLinkTargets(docs, mdFiles);
   const orphanItems = [];
   const seen = new Set();
@@ -42,8 +60,9 @@ export function collectDoctor(targetDir) {
     }
   }
   push("orphan-wikilinks", orphanItems.length ? "warn" : "ok", orphanItems.length ? orphanItems : ["all wikilinks resolve"]);
+  });
 
-  const phaseDir = path.join(docs, "phases");
+guard("phase-progress", () => {
   const roadmapText = exists(path.join(docs, "PRODUCTION_ROADMAP.md"))
     ? readText(path.join(docs, "PRODUCTION_ROADMAP.md"))
     : "";
@@ -71,7 +90,10 @@ export function collectDoctor(targetDir) {
   }
   if (!phaseItems.length) push("phase-progress", "ok", ["no phase task files yet (run /plan-phase)"]);
   else push("phase-progress", phaseWarn ? "warn" : "ok", phaseItems);
+  });
+
 
+guard("spec-coverage", () => {
   const coverageItems = [];
   if (exists(phaseDir)) {
     for (const dir of listDirs(phaseDir)) {
@@ -100,7 +122,10 @@ export function collectDoctor(targetDir) {
   const coverageInfoOnly = coverageItems.length === 1 && coverageItems[0].startsWith("no PRD");
   if (!coverageItems.length) push("spec-coverage", "ok", ["phase structure + PRD sections look complete"]);
   else push("spec-coverage", coverageInfoOnly ? "info" : "warn", coverageItems);
+  });
+
 
+guard("version-marker", () => {
   const marker = path.join(docs, ".groundwork", "VERSION");
   const cliV = pkgVersion();
   if (exists(marker)) {
@@ -109,7 +134,10 @@ export function collectDoctor(targetDir) {
       push("version-marker", "warn", [`installed v${got}, CLI is v${cliV} — run \`groundwork update --all --docs\``]);
     else push("version-marker", "ok", [`up to date (v${got})`]);
   } else push("version-marker", "warn", ["no VERSION marker — re-run `groundwork init`/`update`"]);
+  });
 
+
+guard("stack-map-freshness", () => {
   const sm = path.join(docs, "STACK_MAP.md");
   if (exists(sm)) {
     const m = readText(sm).match(/Last audited[^\d]*(\d{4})-(\d{2})-(\d{2})/);
@@ -120,7 +148,10 @@ export function collectDoctor(targetDir) {
       else push("stack-map-freshness", "ok", [`STACK_MAP audited ${days} days ago`]);
     }
   } else push("stack-map-freshness", "info", ["no STACK_MAP.md yet (run /kickstart)"]);
+  });
+
 
+guard("workstreams", () => {
   const wsFile = path.join(docs, "WORKSTREAMS.md");
   if (exists(wsFile)) {
     const wsDoc = parseWorkDoc(readText(wsFile));
@@ -128,15 +159,21 @@ export function collectDoctor(targetDir) {
     if (wsIssues.length) push("workstreams", "warn", wsIssues);
     else push("workstreams", "ok", ["write grammar is workstreams.v1"]);
   } else push("workstreams", "info", ["no WORKSTREAMS.md yet (run `groundwork update --docs`)"]);
+  });
+
 
+guard("queue", () => {
   const qFile = path.join(docs, "QUEUE.md");
   if (exists(qFile)) {
     const qIssues = workDocIssues(parseWorkDoc(readText(qFile)));
     if (qIssues.length) push("queue", "warn", qIssues);
     else push("queue", "ok", ["queue.v1 — one line per item"]);
   }
+  });
 
-  const factsFile = path.join(docs, "FACTS.md");
+
+const factsFile = path.join(docs, "FACTS.md");
+guard("facts-freshness", () => {
   if (exists(factsFile)) {
     const { entries, issues } = parseFactsDoc(readText(factsFile));
     if (issues.length) push("facts-freshness", "warn", issues);
@@ -147,7 +184,10 @@ export function collectDoctor(targetDir) {
         [entries.length ? `${entries.length} fact(s), all verified and fresh` : "no facts recorded yet"],
       );
   } else push("facts-freshness", "info", ["no FACTS.md yet (run `groundwork update --docs`)"]);
+  });
+
 
+guard("adr-tripwire", () => {
   const decisions = path.join(docs, "DECISIONS.md");
   if (exists(decisions)) {
     const acceptedIds = new Set();
@@ -169,9 +209,11 @@ export function collectDoctor(targetDir) {
     if (adrItems.length) push("adr-tripwire", "warn", adrItems);
     else push("adr-tripwire", "ok", ["no Accepted ADR contradicted by dependencies/paths"]);
   } else push("adr-tripwire", "info", ["no DECISIONS.md yet (run /kickstart)"]);
+  });
+
 
   const warnCount = checks.filter((c) => c.level === "warn").length;
-  return { ok: warnCount === 0, exit: warnCount === 0 ? 0 : 1, checks };
+  return { ok: warnCount === 0, exit: warnCount === 0 ? 0 : 1, checks, ...(skipped.length ? { skipped } : {}) };
 }
 
 export function doctor(targetDir, opts = {}) {
@@ -207,6 +249,8 @@ export function doctor(targetDir, opts = {}) {
     }
   }
   log.heading("Summary");
+  if (report.skipped?.length)
+    console.log(`  ${yellow("⚠")} ${report.skipped.length} check(s) skipped (${report.skipped.join(", ")}) — see above; fs-only checks still ran.`);
   if (report.ok) log.ok("No drift detected — docs match reality.");
   else console.log(`  ${yellow(String(report.checks.filter((c) => c.level === "warn").length))} issue(s) to look at.`);
   process.exitCode = report.exit;