@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/planning-snapshot.cjs

@@ -29,7 +29,7 @@ const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestoneInfo, extractCurrentMilestone } = roadmapParserMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
-const { listMilestonePhaseDirs } = phaseLocatorMod;
+const { listMilestonePhaseDirs, listAllPhaseDirs } = phaseLocatorMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
@@ -666,21 +666,25 @@ function buildPlanningRootFilesField(cwd) {
  * `phaseDirs` cannot). An absent `phases/` root is a real empty, not a
  * failure (mirrors `listMilestonePhaseDirs`'s own treatment); a present but
  * unreadable root degrades to `UNREADABLE` with an empty list.
+ *
+ * #3882 (ADR-3473 §8.3): delegates the actual disk scan to
+ * `listAllPhaseDirs(phasesDir, {includeSentinels: true})` — that function is
+ * the sole owner of "readdirSync the phases/ root, map to dir names, handle
+ * absent-vs-unreadable"; this field is one more consumer of that scan, not a
+ * second implementation of it. The two functions previously duplicated the
+ * same readdirSync + filter + map + absent/unreadable handling, which is
+ * exactly the defect class ADR-3473 §8.3 forbids.
+ *
+ * The RE-SORT below is deliberate, not leftover duplication:
+ * `listAllPhaseDirs` orders its `value` by `comparePhaseNum` (numeric phase
+ * order — its own documented contract), but `allPhaseDirNames`'s existing,
+ * externally-observable order is plain lexicographic `.sort()`, and W007's
+ * consumers depend on that order today. Re-sorting here preserves that
+ * contract without forking the underlying scan.
  */
 function buildAllPhaseDirNamesField(phasesDir) {
-    if (!node_fs_1.default.existsSync(phasesDir))
-        return { value: [], scope: SCOPE.COMPLETE };
-    try {
-        const value = node_fs_1.default
-            .readdirSync(phasesDir, { withFileTypes: true })
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name)
-            .sort();
-        return { value, scope: SCOPE.COMPLETE };
-    }
-    catch {
-        return { value: [], scope: SCOPE.UNREADABLE };
-    }
+    const { value, scope } = listAllPhaseDirs(phasesDir, { includeSentinels: true });
+    return { value: value.slice().sort(), scope };
 }
 /**
  * Resolve `archivedPhaseTokens` — every phase-number token belonging to a

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -120,6 +120,61 @@ function planningDir(cwd, ws, project) {
 function planningRoot(cwd) {
     return node_path_1.default.join(cwd, '.planning');
 }
+/**
+ * #3972: the ONE owner of "is this planning scope opted out of worktrees?" —
+ * the effective `workflow.use_worktrees === false` read every
+ * isolation-deciding surface must share (config-get's merged view is the
+ * contract). Ladder: the scoped config's OWN key wins (planningDir is
+ * project- and workstream-aware); otherwise the flat root's key, but only
+ * under the GSD_WORKSTREAM env gate — config-get deliberately does NOT
+ * inherit root under GSD_PROJECT alone, and this read must not diverge
+ * (#3963). Strict `=== false` (never coerced); any read failure degrades to
+ * "not opted out" (worktrees on — the fail-safe direction: the guard keeps
+ * enforcing). Direct file reads only — never loadConfig, which normalizes
+ * and rewrites config on paths that back sentinel writes.
+ */
+function worktreesOptedOut(cwd) {
+    // #3972 review: the WHOLE body is guarded — planningDir/planningRoot
+    // themselves throw on a GSD_PROJECT/GSD_WORKSTREAM value containing path
+    // separators or `..`, and this contract ("any failure degrades to not
+    // opted out — worktrees on, keep enforcing") must hold for that shape too.
+    try {
+        return worktreesOptedOutUnguarded(cwd);
+    }
+    catch {
+        return false;
+    }
+}
+function worktreesOptedOutUnguarded(cwd) {
+    const readCfg = (p) => {
+        try {
+            return JSON.parse(String(node_fs_1.default.readFileSync(p, 'utf8')));
+        }
+        catch {
+            return null;
+        }
+    };
+    const ownKey = (cfg) => {
+        if (cfg === null || typeof cfg !== 'object')
+            return { present: false, value: undefined };
+        const wf = cfg.workflow;
+        if (wf === null || typeof wf !== 'object' || Array.isArray(wf))
+            return { present: false, value: undefined };
+        const wfRec = wf;
+        return Object.prototype.hasOwnProperty.call(wfRec, 'use_worktrees')
+            ? { present: true, value: wfRec['use_worktrees'] }
+            : { present: false, value: undefined };
+    };
+    const scoped = ownKey(readCfg(node_path_1.default.join(planningDir(cwd), 'config.json')));
+    if (scoped.present)
+        return scoped.value === false;
+    if (process.env['GSD_WORKSTREAM']) {
+        const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
+        if (root.present)
+            return root.value === false;
+    }
+    return false;
+}
 // Sorted list of workstream directory names under `<root>/.planning/workstreams`,
 // or `[]` when the project is flat (no workstreams dir). Single source of truth
 // for the "workstream mode" detection shared by the #1912/#2028 fail-safe guards
@@ -431,6 +486,7 @@ function findContextMdIn(absDirOrFiles) {
     }
 }
 module.exports = {
+    worktreesOptedOut,
     createPlanningWorkspace,
     createSharedPointerAdapter,
     createSessionScopedPointerAdapter,

package/gsd-core/bin/lib/probe-core.cjs

@@ -43,6 +43,9 @@ exports.projectTruths = projectTruths;
 exports.dispositionForUnverifiableTruth = dispositionForUnverifiableTruth;
 exports.runProbeCli = runProbeCli;
 const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 /** The LOCKED set of valid lifecycle statuses (the re-cut: no covered/backstop). */
 exports.VALID_STATUS = ['resolved', 'dismissed', 'unresolved'];
 function errMessage(e) {
@@ -497,7 +500,7 @@ function runProbeCli(analyze, options) {
     const readFile = options.readFile ?? ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
     const write = options.write ?? ((s) => { process.stdout.write(s); });
     const writeErr = options.writeErr ?? ((s) => { process.stderr.write(s); });
-    const exit = options.exit ?? ((code) => { process.exit(code); });
+    const exit = options.exit ?? ((code) => { throw new ExitError(code); });
     const reqPath = argv[2];
     const resPath = argv[3];
     if (!reqPath) {

package/gsd-core/bin/lib/profile-pipeline-command-router.cjs

@@ -13,12 +13,55 @@
  * Async note: cmdExtractMessages and cmdProfileSample are async functions.
  * dispatchCapabilityCommand (gsd-tools.cjs:366-371) explicitly errors if a
  * router returns a Promise. Therefore these router functions call the async
- * function WITHOUT await and WITHOUT returning the Promise. The async functions
- * end with output() or process.exit() so the process terminates correctly once
- * the event loop drains. Unhandled rejections are caught by the .catch() wrapper
- * to surface errors via the error() callback.
+ * function WITHOUT await and WITHOUT returning the Promise; the event loop
+ * drains once the returned promise settles. Since ADR-3889 (#3910), the
+ * pipeline functions terminate by THROWING ExitError (never process.exit()
+ * directly), so a rejection surfacing here can carry either a genuine error
+ * OR a declared ExitError termination — the `.catch()` below must
+ * distinguish them: an ExitError sets process.exitCode directly (mirroring
+ * cli-exit.cjs's own runMain, the only other place ExitError is caught),
+ * while any other rejection is surfaced via the `error()` callback exactly
+ * as before. Calling `error(exitErr.message)` for an ExitError would be
+ * wrong on two counts: it discards the real exit code (error() always
+ * terminates at 1) and it re-derives a message from ExitError's generic
+ * "process exit N" constructor default rather than the (already emitted, or
+ * intentionally absent) stderr output the throwing call site controls.
  */
-const { ERROR_REASON } = require('./io.cjs');
+const { ERROR_REASON, getJsonErrorMode } = require('./io.cjs');
+const { ExitError } = require('./cli-exit.cjs');
+
+/**
+ * Interpret a rejection from a fire-and-forget async pipeline call: an
+ * ExitError sets process.exitCode (and, for a non-zero code carrying a user
+ * message, writes it to stderr) exactly like runMain does; anything else
+ * reproduces io.cjs's error() stderr output byte-for-byte and sets
+ * process.exitCode directly instead of calling error() itself.
+ *
+ * error() (src/io.cts) is `never`-typed: it always throws ExitError(1) after
+ * writing to stderr. Calling it from inside this `.catch()` callback would
+ * throw from a detached promise chain that nothing awaits or re-catches —
+ * an unhandled promise rejection that Node (>=15, this repo's
+ * engines.node >= 24 default is --unhandled-rejections=throw) dumps as a
+ * raw stack trace on top of the clean line error() already wrote. Writing
+ * the same bytes directly and setting process.exitCode = 1 in place gets
+ * the identical observable stderr + exit code without ever throwing here.
+ */
+function _handlePipelineRejection(e, error) {
+  void error;
+  if (e instanceof ExitError) {
+    if (e.hasUserMessage && e.code !== 0) process.stderr.write(`${e.message}\n`);
+    process.exitCode = e.code;
+    return;
+  }
+  const message = e && e.message ? e.message : String(e);
+  if (getJsonErrorMode()) {
+    const payload = JSON.stringify({ ok: false, reason: ERROR_REASON.UNKNOWN, message }) + '\n';
+    process.stderr.write(payload);
+  } else {
+    process.stderr.write('Error: ' + message + '\n');
+  }
+  process.exitCode = 1;
+}
 
 // ─── Pipeline phase commands ───────────────────────────────────────────────────
 
@@ -51,7 +94,7 @@ function routeExtractMessages({ args, cwd, raw, error, _pipeline }) {
   // The function ends with output() or process.exit(); the event loop will drain.
   void cwd;
   p.cmdExtractMessages(projectArg, { sessionId, limit }, raw, sessionsPath)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
@@ -67,7 +110,7 @@ function routeProfileSample({ args, cwd, raw, error, _pipeline }) {
   const maxChars = maxCharsIdx !== -1 ? parseInt(args[maxCharsIdx + 1], 10) : 500;
   // cmdProfileSample is async — do NOT return the Promise.
   p.cmdProfileSample(sessionsPath, { limit, maxPerProject, maxChars }, raw)
-    .catch(e => { error(e && e.message ? e.message : String(e)); });
+    .catch(e => { _handlePipelineRejection(e, error); });
 }
 
 // ─── Output phase commands ─────────────────────────────────────────────────────

package/gsd-core/bin/lib/profile-pipeline.cjs

@@ -22,6 +22,9 @@ const node_readline_1 = __importDefault(require("node:readline"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioModule = require("./io.cjs");
 const { output, error, reapStaleTempFiles, ensureGsdTempDir, GSD_TEMP_DIR } = ioModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 // ─── Session I/O Helpers ──────────────────────────────────────────────────────
 function getSessionsDir(overridePath) {
     const dir = overridePath || node_path_1.default.join(node_os_1.default.homedir(), '.claude', 'projects');
@@ -250,7 +253,7 @@ function cmdScanSessions(overridePath, options, raw) {
             }
         }
         process.stdout.write(`\nTotal: ${projects.length} projects\n`);
-        process.exit(0);
+        throw new ExitError(0);
     }
 }
 async function cmdExtractMessages(projectArg, options, raw, overridePath) {
@@ -376,11 +379,11 @@ async function cmdExtractMessages(projectArg, options, raw, overridePath) {
     };
     if (sessionsSkipped > 0 && sessionsProcessed > 0) {
         process.stdout.write(JSON.stringify(result, null, 2));
-        process.exit(2);
+        throw new ExitError(2);
     }
     else if (sessionsProcessed === 0 && sessionsSkipped > 0) {
         process.stdout.write(JSON.stringify(result, null, 2));
-        process.exit(1);
+        throw new ExitError(1);
     }
     else {
         output(result, raw, undefined);