@opengsd/gsd-core 1.9.1 → 1.10.0

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -61,6 +61,78 @@ function sha256Text(value) {
  * the correct outcome — refusing to proceed beats silently copying referent
  * bytes.
  */
+/**
+ * Evaluate and, if safe, perform a `remove-empty-dir` action against `fullPath`.
+ *
+ * This is deliberately WEAKER than a recursive directory-removal primitive
+ * (which 003's docblock records as an intentional absence in the ADR-0008
+ * design): it only ever calls `fs.rmdirSync` — never `fs.rmSync`, never
+ * `{ recursive: true }`, never `{ force: true }` — so a non-empty directory
+ * fails the underlying syscall rather than being swept. The emptiness check
+ * immediately above the call is what turns that failure mode into a
+ * deliberate, non-error "left in place" outcome instead of surfacing ENOTEMPTY.
+ *
+ * Guards, in order:
+ *   - lstat (not stat): a symlinked directory is refused outright, never
+ *     followed. A missing target is reported distinctly so callers can tell
+ *     "nothing was ever there" from "something was there and is left alone".
+ *   - must actually be a directory (not a file masquerading under the relPath).
+ *   - containment: the REALPATH of the target must resolve strictly inside the
+ *     REALPATH of configDir — never equal to it (removing the config root
+ *     itself is never in scope) and never escaping it (e.g. via an ancestor
+ *     symlink the lstat check alone would not catch).
+ *   - emptiness, re-checked here rather than trusted from planning time: a
+ *     directory that still holds any entry (managed-but-undeleted, unknown,
+ *     or created between plan and apply) is left in place. This is reported
+ *     as 'skipped-not-empty', a successful no-op, not a failure.
+ *
+ * Any unexpected error along the way (EACCES, EBUSY, a race that removes the
+ * target between the lstat and the rmdir, etc.) degrades to 'left-in-place'.
+ * This action must never throw out of the executor, matching every sibling
+ * action type's failure posture.
+ */
+function evaluateRemoveEmptyDir(configDir, fullPath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.lstatSync(fullPath);
+    }
+    catch {
+        return 'missing';
+    }
+    if (stat.isSymbolicLink())
+        return 'left-in-place';
+    if (!stat.isDirectory())
+        return 'left-in-place';
+    let resolvedRoot;
+    let resolvedTarget;
+    try {
+        resolvedRoot = node_fs_1.default.realpathSync(configDir);
+        resolvedTarget = node_fs_1.default.realpathSync(fullPath);
+    }
+    catch {
+        return 'left-in-place';
+    }
+    if (resolvedTarget === resolvedRoot || !resolvedTarget.startsWith(resolvedRoot + node_path_1.default.sep)) {
+        // Refuses both "target IS configDir" and "target escaped configDir".
+        return 'left-in-place';
+    }
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(fullPath);
+    }
+    catch {
+        return 'left-in-place';
+    }
+    if (entries.length > 0)
+        return 'skipped-not-empty';
+    try {
+        node_fs_1.default.rmdirSync(fullPath);
+        return 'removed';
+    }
+    catch {
+        return 'left-in-place';
+    }
+}
 function copyPreservingSymlink(srcPath, destPath) {
     if (node_fs_1.default.lstatSync(srcPath).isSymbolicLink()) {
         // symlinkSync fails with EEXIST on an occupied path, so clear it first.
@@ -643,7 +715,8 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                 action.type !== 'backup-and-remove' &&
                 action.type !== 'rewrite-json' &&
                 action.type !== 'record-baseline' &&
-                action.type !== 'baseline-preserve-user') {
+                action.type !== 'baseline-preserve-user' &&
+                action.type !== 'remove-empty-dir') {
                 throw new Error(`unsupported migration action type: ${action.type}`);
             }
             const { normalized, fullPath } = ensureInsideConfig(configDir, action.relPath);
@@ -655,6 +728,18 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                 journal.actions.push(journalAction(action, action.type === 'record-baseline' ? 'recorded' : 'preserved'));
                 continue;
             }
+            if (action.type === 'remove-empty-dir') {
+                // Directory actions never enter the file-copy/rollback machinery below:
+                // there is nothing to snapshot-and-restore for a directory node itself
+                // (its former CONTENTS were already snapshotted by their own file-level
+                // actions before this one runs), and rollback of a removed empty
+                // directory is simply re-creating it, which the rollback path below
+                // does not model. Non-recursive by construction (evaluateRemoveEmptyDir
+                // only ever calls fs.rmdirSync), so there is nothing destructive to undo
+                // beyond an mkdir the next install/migration run will happily redo.
+                journal.actions.push(journalAction(action, evaluateRemoveEmptyDir(configDir, fullPath)));
+                continue;
+            }
             const rollbackPath = node_path_1.default.join(rollbackRoot, normalized);
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(rollbackPath), { recursive: true });
             copyPreservingSymlink(fullPath, rollbackPath);
@@ -853,6 +938,7 @@ module.exports = {
     applyInstallerMigrationPlan,
     classifyArtifact,
     discoverInstallerMigrations,
+    evaluateRemoveEmptyDir,
     migrationChecksum,
     planInstallerMigrations,
     readInstallManifest,

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

@@ -118,6 +118,22 @@ function writeAllSync(fd, data) {
         }
     }
 }
+/**
+ * The wire form of a JSON result: the exact bytes `output()` emits for it.
+ *
+ * Exported because a caller that has to reason about the size of its own
+ * response — graphify's `--budget` accounting (#2738) — must measure the string
+ * this function produces rather than a second, privately-maintained
+ * serialization that can drift from it. One definition, so estimator and
+ * emitter cannot disagree about indentation or shape.
+ *
+ * The `@file:` redirection in `output()` is a transport detail, not a payload
+ * change: the caller still consumes these bytes, so these are the right ones to
+ * measure.
+ */
+function serializeForOutput(result) {
+    return JSON.stringify(result, null, 2);
+}
 function output(result, raw, rawValue) {
     let data;
     if (raw && rawValue !== undefined) {
@@ -125,7 +141,7 @@ function output(result, raw, rawValue) {
         data = String(rawValue);
     }
     else {
-        const json = JSON.stringify(result, null, 2);
+        const json = serializeForOutput(result);
         // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
         // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
         if (json.length > 50000) {
@@ -168,6 +184,7 @@ const ERROR_REASON = Object.freeze({
     // workflow / phase
     PHASE_NOT_FOUND: 'phase_not_found',
     PHASE_VERIFICATION_INCOMPLETE: 'phase_verification_incomplete',
+    PHASE_PLAN_COVERAGE_INCOMPLETE: 'phase_plan_coverage_incomplete',
     SUMMARY_NO_PLANNING: 'summary_no_planning',
     // graphify
     GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
@@ -198,10 +215,17 @@ function getJsonErrorMode() { return _jsonErrorMode; }
  * process is in JSON-error mode, stderr receives `{ ok: false, reason,
  * message }` so callers can parse it; otherwise stderr keeps the plain
  * text form for human operators.
+ *
+ * `extra` (optional) lets a caller attach additional structured fields
+ * (e.g. `{ verification_stale_check_indeterminate: true }`) onto the
+ * JSON-error-mode payload, spread alongside `ok`/`reason`/`message`, so a
+ * test can assert on the value directly instead of regexing `message`'s
+ * human-readable text. Ignored entirely in plain-text mode — the human
+ * message is the only thing an operator sees there.
  */
-function error(message, reason = ERROR_REASON.UNKNOWN) {
+function error(message, reason = ERROR_REASON.UNKNOWN, extra) {
     if (_jsonErrorMode) {
-        const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
+        const payload = JSON.stringify({ ok: false, reason, message, ...(extra || {}) }) + '\n';
         writeAllSync(2, payload);
     }
     else {
@@ -214,6 +238,7 @@ module.exports = {
     ensureGsdTempDir,
     reapStaleTempFiles,
     output,
+    serializeForOutput,
     ERROR_REASON,
     setJsonErrorMode,
     getJsonErrorMode,

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripFencedCode = stripFencedCode;
 exports.stripInlineCode = stripInlineCode;
 exports.scanInlineCodeSpans = scanInlineCodeSpans;
+exports.scanFencedBlocks = scanFencedBlocks;
 exports.extractFencedBlock = extractFencedBlock;
 exports.tokenizeHeadings = tokenizeHeadings;
 exports.collectSections = collectSections;
@@ -206,6 +207,11 @@ function stripInlineCodeLine(line) {
  * Tracked duplication (same status as `tokenizeHeadings`'s copy, see its
  * comment above): this is a second independent copy of the fence state
  * machine, pending a T-tier consolidation.
+ *
+ * Exported so `context-predicates.cts` can consume this seam directly for its
+ * line-preserving fenced-line skip detection, instead of carrying a third
+ * independent copy of the fence state machine (see that module's doc
+ * comment).
  */
 function scanFencedBlocks(lines) {
     const delimRe = /^( {0,3})(`{3,}|~{3,})(.*)$/;