gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/dist/resources/extensions/gsd/gsd-db.js

@@ -26,6 +26,7 @@ import { GSDError, GSD_STALE_STATE } from "./errors.js";
 import { getGateIdsForTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 const _require = createRequire(import.meta.url);
+const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
 let providerName = null;
 let providerModule = null;
 let loadAttempted = false;
@@ -63,7 +64,7 @@ function loadProvider() {
         // unavailable
     }
     try {
-        const mod = _require("better-sqlite3");
+        const mod = _require(BETTER_SQLITE3_PACKAGE);
         if (typeof mod === "function" || (mod && mod.default)) {
             providerModule = mod.default || mod;
             providerName = "better-sqlite3";
@@ -135,7 +136,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 23;
 function indexExists(db, name) {
     return !!db.prepare("SELECT 1 as present FROM sqlite_master WHERE type = 'index' AND name = ?").get(name);
 }
@@ -298,7 +299,8 @@ function initSchema(db, fileBacked) {
         verification_uat TEXT NOT NULL DEFAULT '',
         definition_of_done TEXT NOT NULL DEFAULT '[]',
         requirement_coverage TEXT NOT NULL DEFAULT '',
-        boundary_map_markdown TEXT NOT NULL DEFAULT ''
+        boundary_map_markdown TEXT NOT NULL DEFAULT '',
+        sequence INTEGER DEFAULT 0
       )
     `);
         db.exec(`
@@ -1130,6 +1132,16 @@ function migrateSchema(db) {
                 ":applied_at": new Date().toISOString(),
             });
         }
+        if (currentVersion < 23) {
+            // v23: milestone queue ordering moves into the canonical DB. The
+            // historical QUEUE-ORDER.json file remains a projection, but runtime
+            // derivation must not read it as authoritative state.
+            ensureColumn(db, "milestones", "sequence", "ALTER TABLE milestones ADD COLUMN sequence INTEGER DEFAULT 0");
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+                ":version": 23,
+                ":applied_at": new Date().toISOString(),
+            });
+        }
         db.exec("COMMIT");
     }
     catch (err) {
@@ -1144,6 +1156,193 @@ let _exitHandlerRegistered = false;
 let _dbOpenAttempted = false;
 let _lastDbError = null;
 let _lastDbPhase = null;
+/**
+ * Identity key of the workspace whose connection is currently active
+ * (currentDb). Set by openDatabaseByWorkspace(); null when the active
+ * connection was opened via the legacy openDatabase(path) path.
+ */
+let _currentIdentityKey = null;
+/**
+ * Workspace-scoped connection cache.
+ * Key: GsdWorkspace.identityKey (realpath-normalized project root).
+ * Value: the DB path and open adapter for that workspace.
+ *
+ * Sibling worktrees of the same project share the same identityKey (set by
+ * createWorkspace) and therefore reuse the same cached connection, preserving
+ * shared-WAL semantics. Different projects get distinct cache entries.
+ *
+ * NOTE: Only one connection is "active" at a time (currentDb/currentPath).
+ * The cache allows fast re-activation of a previously opened connection when
+ * callers switch between known workspaces via openDatabaseByWorkspace().
+ */
+const _dbCache = new Map();
+/** Test helper: expose the internal cache for inspection. Not for production use. */
+export function _getDbCache() {
+    return _dbCache;
+}
+/**
+ * Close and evict every entry in the workspace connection cache, then call
+ * closeDatabase() to close the active connection.
+ *
+ * Use this for test teardown or process-shutdown paths where every open
+ * connection must be flushed. Normal callers should use closeDatabase() or
+ * closeDatabaseByWorkspace() instead.
+ */
+export function closeAllDatabases() {
+    // Close all non-active cached connections first.
+    for (const [key, entry] of _dbCache) {
+        if (entry.db === currentDb)
+            continue; // handled by closeDatabase() below
+        _dbCache.delete(key);
+        try {
+            entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        }
+        catch { /* best-effort */ }
+        try {
+            entry.db.exec("PRAGMA incremental_vacuum(64)");
+        }
+        catch { /* best-effort */ }
+        try {
+            entry.db.close();
+        }
+        catch { /* best-effort */ }
+    }
+    closeDatabase();
+}
+/**
+ * Open (or reuse) the database connection scoped to the given workspace.
+ *
+ * Uses workspace.identityKey as the cache key, so sibling worktrees of the
+ * same project resolve to the same connection. On a cache hit the existing
+ * adapter is reactivated as the current connection without re-opening the
+ * file. On a cache miss, delegates to openDatabase() for the full
+ * open + schema-init + migration flow, then caches the result.
+ *
+ * When switching to a different workspace, the previously active connection
+ * is preserved in the cache (not closed), so callers can switch back to it
+ * cheaply via a subsequent openDatabaseByWorkspace() call.
+ *
+ * @param workspace A GsdWorkspace created by createWorkspace().
+ * @returns true if the connection is open and ready, false otherwise.
+ */
+export function openDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const dbPath = workspace.contract.projectDb;
+    const cached = _dbCache.get(key);
+    if (cached) {
+        // Reactivate the cached connection as the current singleton.
+        currentDb = cached.db;
+        currentPath = cached.dbPath;
+        currentPid = process.pid;
+        _dbOpenAttempted = true;
+        _currentIdentityKey = key;
+        return true;
+    }
+    // Cache miss — need to open a new connection.
+    //
+    // If there is a currently active workspace connection, stash it in the
+    // cache under its identity key before calling openDatabase(), because
+    // openDatabase() will call closeDatabase() when the path changes (which
+    // would destroy the existing adapter). By nulling out currentDb first,
+    // we prevent openDatabase() from closing the live adapter.
+    let oldDb = null;
+    let oldPath = null;
+    let oldPid = 0;
+    let oldKey = null;
+    if (currentDb !== null && _currentIdentityKey !== null) {
+        // Snapshot the old globals so we can restore them on failure.
+        oldDb = currentDb;
+        oldPath = currentPath;
+        oldPid = currentPid;
+        oldKey = _currentIdentityKey;
+        // Save the current connection so it stays alive in the cache.
+        _dbCache.set(_currentIdentityKey, {
+            dbPath: currentPath,
+            db: currentDb,
+        });
+        // Detach from globals so openDatabase() opens fresh without closing it.
+        currentDb = null;
+        currentPath = null;
+        currentPid = 0;
+        _currentIdentityKey = null;
+    }
+    // Run the full open/schema/migration flow for the new workspace.
+    // openDatabase() can throw on corrupt DB or permission error — catch so we
+    // can restore the previous connection rather than leaving globals null.
+    let opened;
+    try {
+        opened = openDatabase(dbPath);
+    }
+    catch (err) {
+        // Failed to open the new DB. Restore the previous workspace connection so
+        // the caller's workspace remains active (it is still safe in _dbCache).
+        if (oldDb !== null) {
+            currentDb = oldDb;
+            currentPath = oldPath;
+            currentPid = oldPid;
+            _currentIdentityKey = oldKey;
+        }
+        throw err;
+    }
+    if (opened && currentDb) {
+        _dbCache.set(key, { dbPath, db: currentDb });
+        _currentIdentityKey = key;
+    }
+    else if (!opened && oldDb !== null) {
+        // Restore the previous connection so the caller's workspace remains active.
+        // The failed attempt left no live adapter, so the globals stayed null.
+        currentDb = oldDb;
+        currentPath = oldPath;
+        currentPid = oldPid;
+        _currentIdentityKey = oldKey;
+    }
+    return opened;
+}
+/**
+ * Open (or reuse) the database connection scoped to the workspace in a
+ * MilestoneScope. Thin delegation to openDatabaseByWorkspace().
+ */
+export function openDatabaseByScope(scope) {
+    return openDatabaseByWorkspace(scope.workspace);
+}
+/**
+ * Close the database connection for the given workspace and remove it from
+ * the cache. If the workspace's connection is currently active (currentDb),
+ * performs a full closeDatabase() including WAL checkpoint. Otherwise only
+ * removes the cache entry (the adapter was already replaced by a later open).
+ */
+export function closeDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const cached = _dbCache.get(key);
+    if (!cached)
+        return;
+    _dbCache.delete(key);
+    if (currentDb === cached.db) {
+        // This workspace's connection is the active one — full close.
+        closeDatabase();
+    }
+    else {
+        // Connection was displaced by a later open; close the adapter directly.
+        try {
+            cached.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        }
+        catch (e) {
+            logWarning("db", `WAL checkpoint (byWorkspace) failed: ${e.message}`);
+        }
+        try {
+            cached.db.exec("PRAGMA incremental_vacuum(64)");
+        }
+        catch (e) {
+            logWarning("db", `incremental vacuum (byWorkspace) failed: ${e.message}`);
+        }
+        try {
+            cached.db.close();
+        }
+        catch (e) {
+            logWarning("db", `database close (byWorkspace) failed: ${e.message}`);
+        }
+    }
+}
 export function getDbProvider() {
     loadProvider();
     return providerName;
@@ -1191,7 +1390,7 @@ export function openDatabase(path) {
         // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
         if (providerName === "node:sqlite") {
             try {
-                const mod = _require("better-sqlite3");
+                const mod = _require(BETTER_SQLITE3_PACKAGE);
                 const Db = (mod && mod.default) ? mod.default : mod;
                 if (typeof Db === "function") {
                     rawDb = new Db(path);
@@ -1288,6 +1487,13 @@ export function closeDatabase() {
         catch (e) {
             logWarning("db", `database close failed: ${e.message}`);
         }
+        // If this connection was workspace-tracked, evict it from the cache so
+        // subsequent openDatabaseByWorkspace() calls re-open rather than reactivate
+        // a closed adapter.
+        if (_currentIdentityKey !== null) {
+            _dbCache.delete(_currentIdentityKey);
+            _currentIdentityKey = null;
+        }
         currentDb = null;
         currentPath = null;
         currentPid = 0;
@@ -1321,6 +1527,15 @@ export function checkpointDatabase() {
     }
 }
 let _txDepth = 0;
+/**
+ * Whether the current call is running inside an active SQLite transaction.
+ * Statement-time recovery paths (e.g. VACUUM retry on a malformed memory
+ * store) MUST gate on this — SQLite refuses VACUUM inside a transaction
+ * and would mask the original error with a secondary "cannot VACUUM" throw.
+ */
+export function isInTransaction() {
+    return _txDepth > 0;
+}
 export function transaction(fn) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -1335,8 +1550,8 @@ export function transaction(fn) {
             _txDepth--;
         }
     }
-    _txDepth++;
     currentDb.exec("BEGIN");
+    _txDepth++;
     try {
         const result = fn();
         currentDb.exec("COMMIT");
@@ -1369,8 +1584,8 @@ export function readTransaction(fn) {
             _txDepth--;
         }
     }
-    _txDepth++;
     currentDb.exec("BEGIN DEFERRED");
+    _txDepth++;
     try {
         const result = fn();
         currentDb.exec("COMMIT");
@@ -1508,6 +1723,31 @@ export function getActiveRequirements() {
         superseded_by: null,
     }));
 }
+export function getRequirementCounts() {
+    if (!currentDb) {
+        return { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+    }
+    const rows = currentDb
+        .prepare("SELECT lower(status) as status, COUNT(*) as count FROM requirements GROUP BY lower(status)")
+        .all();
+    const counts = { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+    for (const row of rows) {
+        const status = String(row["status"] ?? "");
+        const count = Number(row["count"] ?? 0);
+        counts.total += count;
+        if (status === "active")
+            counts.active += count;
+        else if (status === "validated")
+            counts.validated += count;
+        else if (status === "deferred")
+            counts.deferred += count;
+        else if (status === "out-of-scope" || status === "out_of_scope")
+            counts.outOfScope += count;
+        else if (status === "blocked")
+            counts.blocked += count;
+    }
+    return counts;
+}
 export function getDbOwnerPid() {
     return currentPid;
 }
@@ -2154,6 +2394,7 @@ function rowToMilestone(row) {
         definition_of_done: JSON.parse(row["definition_of_done"] || "[]"),
         requirement_coverage: row["requirement_coverage"] ?? "",
         boundary_map_markdown: row["boundary_map_markdown"] ?? "",
+        sequence: Number(row["sequence"] ?? 0),
     };
 }
 function rowToArtifact(row) {
@@ -2170,7 +2411,7 @@ function rowToArtifact(row) {
 export function getAllMilestones() {
     if (!currentDb)
         return [];
-    const rows = currentDb.prepare("SELECT * FROM milestones ORDER BY id").all();
+    const rows = currentDb.prepare("SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id").all();
     return rows.map(rowToMilestone);
 }
 export function getMilestone(id) {
@@ -2181,6 +2422,23 @@ export function getMilestone(id) {
         return null;
     return rowToMilestone(row);
 }
+export function setMilestoneQueueOrder(order) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb.exec("BEGIN IMMEDIATE");
+    try {
+        currentDb.prepare("UPDATE milestones SET sequence = 0").run();
+        const stmt = currentDb.prepare("UPDATE milestones SET sequence = :sequence WHERE id = :id");
+        order.forEach((id, index) => {
+            stmt.run({ ":id": id, ":sequence": index + 1 });
+        });
+        currentDb.exec("COMMIT");
+    }
+    catch (err) {
+        currentDb.exec("ROLLBACK");
+        throw err;
+    }
+}
 /**
  * Update a milestone's status in the database.
  * Used by park/unpark to keep the DB in sync with the filesystem marker.
@@ -2348,6 +2606,8 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
             // fall through to the main DB's existing value (not a literal default)
             // so reconcile never silently clears state the main tree has recorded.
             const hasDecisionSource = wtInfo.some((col) => col["name"] === "source");
+            const wtMilestoneInfo = adapter.prepare("PRAGMA wt.table_info('milestones')").all();
+            const hasMilestoneSequence = wtMilestoneInfo.some((col) => col["name"] === "sequence");
             const wtSliceInfo = adapter.prepare("PRAGMA wt.table_info('slices')").all();
             const hasIsSketch = wtSliceInfo.some((col) => col["name"] === "is_sketch");
             const hasSketchScope = wtSliceInfo.some((col) => col["name"] === "sketch_scope");
@@ -2405,7 +2665,7 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
             id, title, status, depends_on, created_at, completed_at,
             vision, success_criteria, key_risks, proof_strategy,
             verification_contract, verification_integration, verification_operational, verification_uat,
-            definition_of_done, requirement_coverage, boundary_map_markdown
+            definition_of_done, requirement_coverage, boundary_map_markdown, sequence
           )
           SELECT w.id, w.title,
                  CASE
@@ -2423,7 +2683,8 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
                  END,
                  w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
                  w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
-                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown
+                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown,
+                 ${hasMilestoneSequence ? "COALESCE(w.sequence, 0)" : "COALESCE(m.sequence, 0)"}
           FROM wt.milestones w
           LEFT JOIN milestones m ON m.id = w.id
         `).run());
@@ -2649,6 +2910,15 @@ export function getAssessment(path) {
     const row = currentDb.prepare(`SELECT * FROM assessments WHERE path = :path`).get({ ":path": path });
     return row ?? null;
 }
+export function getLatestAssessmentByScope(milestoneId, scope) {
+    if (!currentDb)
+        return null;
+    const row = currentDb.prepare(`SELECT * FROM assessments
+      WHERE milestone_id = :mid AND scope = :scope
+      ORDER BY created_at DESC
+      LIMIT 1`).get({ ":mid": milestoneId, ":scope": scope });
+    return row ?? null;
+}
 // ─── Quality Gates ───────────────────────────────────────────────────────
 function rowToGate(row) {
     return {
@@ -3017,10 +3287,10 @@ export function restoreManifest(manifest) {
         const msStmt = db.prepare(`INSERT INTO milestones (id, title, status, depends_on, created_at, completed_at,
         vision, success_criteria, key_risks, proof_strategy,
         verification_contract, verification_integration, verification_operational, verification_uat,
-        definition_of_done, requirement_coverage, boundary_map_markdown)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        definition_of_done, requirement_coverage, boundary_map_markdown, sequence)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
         for (const m of manifest.milestones) {
-            msStmt.run(m.id, m.title, m.status, JSON.stringify(m.depends_on), m.created_at, m.completed_at, m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks), JSON.stringify(m.proof_strategy), m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat, JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown);
+            msStmt.run(m.id, m.title, m.status, JSON.stringify(m.depends_on), m.created_at, m.completed_at, m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks), JSON.stringify(m.proof_strategy), m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat, JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown, m.sequence ?? 0);
         }
         // Restore slices (ADR-011 Phase 1: includes is_sketch + sketch_scope)
         const slStmt = db.prepare(`INSERT INTO slices (milestone_id, id, title, status, risk, depends, demo,

package/dist/resources/extensions/gsd/gsd-home.js

@@ -0,0 +1,29 @@
+/**
+ * GSD home directory resolution.
+ *
+ * Exports gsdHome() which returns the GSD configuration directory,
+ * defaulting to ~/.gsd with a GSD_HOME env var override.
+ *
+ * For the user's home directory, use os.homedir() directly — it handles
+ * platform-specific env lookup (USERPROFILE on Windows, HOME on POSIX)
+ * with appropriate fallbacks.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * Resolve the GSD home directory (typically ~/.gsd).
+ *
+ * `GSD_HOME` env var overrides the default location.
+ * Falls back to `homedir()/.gsd`.
+ *
+ * Always returns an absolute, normalized path — `resolve()` canonicalizes
+ * any relative or non-canonical `GSD_HOME` value so downstream comparison
+ * and redaction sites don't have to.
+ */
+export function gsdHome() {
+    return process.env.GSD_HOME
+        ? resolve(process.env.GSD_HOME)
+        : join(homedir(), ".gsd");
+}

package/dist/resources/extensions/gsd/guided-flow-queue.js

@@ -150,7 +150,7 @@ export async function showQueueAdd(ctx, pi, basePath, state) {
     ].join(" ");
     // ── Dispatch the queue prompt ───────────────────────────────────────
     // Activate the queue phase so the write-gate applies to CONTEXT.md writes
-    setQueuePhaseActive(true);
+    setQueuePhaseActive(true, basePath);
     const queueInlinedTemplates = inlineTemplate("context", "Context");
     const prompt = loadPrompt("queue", {
         preamble,