gsd-pi 2.29.0-dev.77f06e2 → 2.29.0-dev.f08b4fe

package/dist/resources/extensions/gsd/commands-extensions.ts

@@ -0,0 +1,328 @@
+/**
+ * GSD Extensions Command — /gsd extensions
+ *
+ * Manage the extension registry: list, enable, disable, info.
+ * Self-contained — no imports outside the extensions tree (extensions are loaded
+ * via jiti at runtime from ~/.gsd/agent/, not compiled by tsc).
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// ─── Types (mirrored from extension-registry.ts) ────────────────────────────
+
+interface ExtensionManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  tier: "core" | "bundled" | "community";
+  requires: { platform: string };
+  provides?: {
+    tools?: string[];
+    commands?: string[];
+    hooks?: string[];
+    shortcuts?: string[];
+  };
+  dependencies?: {
+    extensions?: string[];
+    runtime?: string[];
+  };
+}
+
+interface ExtensionRegistryEntry {
+  id: string;
+  enabled: boolean;
+  source: "bundled" | "user" | "project";
+  disabledAt?: string;
+  disabledReason?: string;
+}
+
+interface ExtensionRegistry {
+  version: 1;
+  entries: Record<string, ExtensionRegistryEntry>;
+}
+
+// ─── Registry I/O ───────────────────────────────────────────────────────────
+
+function getRegistryPath(): string {
+  return join(homedir(), ".gsd", "extensions", "registry.json");
+}
+
+function getAgentExtensionsDir(): string {
+  return join(homedir(), ".gsd", "agent", "extensions");
+}
+
+function loadRegistry(): ExtensionRegistry {
+  const filePath = getRegistryPath();
+  try {
+    if (!existsSync(filePath)) return { version: 1, entries: {} };
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && parsed.version === 1 && typeof parsed.entries === "object") {
+      return parsed as ExtensionRegistry;
+    }
+    return { version: 1, entries: {} };
+  } catch {
+    return { version: 1, entries: {} };
+  }
+}
+
+function saveRegistry(registry: ExtensionRegistry): void {
+  const filePath = getRegistryPath();
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = filePath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(registry, null, 2), "utf-8");
+    renameSync(tmp, filePath);
+  } catch { /* non-fatal */ }
+}
+
+function isEnabled(registry: ExtensionRegistry, id: string): boolean {
+  const entry = registry.entries[id];
+  if (!entry) return true;
+  return entry.enabled;
+}
+
+function readManifest(dir: string): ExtensionManifest | null {
+  const mPath = join(dir, "extension-manifest.json");
+  if (!existsSync(mPath)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(mPath, "utf-8"));
+    if (typeof raw?.id === "string" && typeof raw?.name === "string") return raw as ExtensionManifest;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function discoverManifests(): Map<string, ExtensionManifest> {
+  const extDir = getAgentExtensionsDir();
+  const manifests = new Map<string, ExtensionManifest>();
+  if (!existsSync(extDir)) return manifests;
+  for (const entry of readdirSync(extDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const m = readManifest(join(extDir, entry.name));
+    if (m) manifests.set(m.id, m);
+  }
+  return manifests;
+}
+
+// ─── Command Handler ────────────────────────────────────────────────────────
+
+export async function handleExtensions(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parts = args.split(/\s+/).filter(Boolean);
+  const subCmd = parts[0] ?? "list";
+
+  if (subCmd === "list") {
+    handleList(ctx);
+    return;
+  }
+
+  if (subCmd === "enable") {
+    handleEnable(parts[1], ctx);
+    return;
+  }
+
+  if (subCmd === "disable") {
+    handleDisable(parts[1], parts.slice(2).join(" "), ctx);
+    return;
+  }
+
+  if (subCmd === "info") {
+    handleInfo(parts[1], ctx);
+    return;
+  }
+
+  ctx.ui.notify(
+    `Unknown: /gsd extensions ${subCmd}. Usage: /gsd extensions [list|enable|disable|info]`,
+    "warning",
+  );
+}
+
+function handleList(ctx: ExtensionCommandContext): void {
+  const manifests = discoverManifests();
+  const registry = loadRegistry();
+
+  if (manifests.size === 0) {
+    ctx.ui.notify("No extension manifests found.", "warning");
+    return;
+  }
+
+  // Sort: core first, then alphabetical
+  const sorted = [...manifests.values()].sort((a, b) => {
+    if (a.tier === "core" && b.tier !== "core") return -1;
+    if (b.tier === "core" && a.tier !== "core") return 1;
+    return a.id.localeCompare(b.id);
+  });
+
+  const lines: string[] = [];
+  const hdr = padRight("Extensions", 38) + padRight("Status", 10) + padRight("Tier", 10) + padRight("Tools", 7) + "Commands";
+  lines.push(hdr);
+  lines.push("─".repeat(hdr.length));
+
+  for (const m of sorted) {
+    const enabled = isEnabled(registry, m.id);
+    const status = enabled ? "enabled" : "disabled";
+    const toolCount = m.provides?.tools?.length ?? 0;
+    const cmdCount = m.provides?.commands?.length ?? 0;
+    const label = `${m.id} (${m.name})`;
+
+    lines.push(
+      padRight(label, 38) +
+      padRight(status, 10) +
+      padRight(m.tier, 10) +
+      padRight(String(toolCount), 7) +
+      String(cmdCount),
+    );
+
+    if (!enabled) {
+      lines.push(`  ↳ gsd extensions enable ${m.id}`);
+    }
+  }
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function handleEnable(id: string | undefined, ctx: ExtensionCommandContext): void {
+  if (!id) {
+    ctx.ui.notify("Usage: /gsd extensions enable <id>", "warning");
+    return;
+  }
+
+  const manifests = discoverManifests();
+  if (!manifests.has(id)) {
+    ctx.ui.notify(`Extension "${id}" not found. Run /gsd extensions list to see available extensions.`, "warning");
+    return;
+  }
+
+  const registry = loadRegistry();
+  if (isEnabled(registry, id)) {
+    ctx.ui.notify(`Extension "${id}" is already enabled.`, "info");
+    return;
+  }
+
+  const entry = registry.entries[id];
+  if (entry) {
+    entry.enabled = true;
+    delete entry.disabledAt;
+    delete entry.disabledReason;
+  } else {
+    registry.entries[id] = { id, enabled: true, source: "bundled" };
+  }
+  saveRegistry(registry);
+  ctx.ui.notify(`Enabled "${id}". Restart GSD to activate.`, "info");
+}
+
+function handleDisable(id: string | undefined, reason: string, ctx: ExtensionCommandContext): void {
+  if (!id) {
+    ctx.ui.notify("Usage: /gsd extensions disable <id>", "warning");
+    return;
+  }
+
+  const manifests = discoverManifests();
+  const manifest = manifests.get(id) ?? null;
+
+  if (!manifests.has(id)) {
+    ctx.ui.notify(`Extension "${id}" not found. Run /gsd extensions list to see available extensions.`, "warning");
+    return;
+  }
+
+  if (manifest?.tier === "core") {
+    ctx.ui.notify(`Cannot disable "${id}" — it is a core extension.`, "warning");
+    return;
+  }
+
+  const registry = loadRegistry();
+  if (!isEnabled(registry, id)) {
+    ctx.ui.notify(`Extension "${id}" is already disabled.`, "info");
+    return;
+  }
+
+  const entry = registry.entries[id];
+  if (entry) {
+    entry.enabled = false;
+    entry.disabledAt = new Date().toISOString();
+    entry.disabledReason = reason || undefined;
+  } else {
+    registry.entries[id] = {
+      id,
+      enabled: false,
+      source: "bundled",
+      disabledAt: new Date().toISOString(),
+      disabledReason: reason || undefined,
+    };
+  }
+  saveRegistry(registry);
+  ctx.ui.notify(`Disabled "${id}". Restart GSD to deactivate.`, "info");
+}
+
+function handleInfo(id: string | undefined, ctx: ExtensionCommandContext): void {
+  if (!id) {
+    ctx.ui.notify("Usage: /gsd extensions info <id>", "warning");
+    return;
+  }
+
+  const manifests = discoverManifests();
+  const manifest = manifests.get(id);
+  if (!manifest) {
+    ctx.ui.notify(`Extension "${id}" not found.`, "warning");
+    return;
+  }
+
+  const registry = loadRegistry();
+  const enabled = isEnabled(registry, id);
+  const entry = registry.entries[id];
+
+  const lines: string[] = [
+    `${manifest.name} (${manifest.id})`,
+    "",
+    `  Version:     ${manifest.version}`,
+    `  Description: ${manifest.description}`,
+    `  Tier:        ${manifest.tier}`,
+    `  Status:      ${enabled ? "enabled" : "disabled"}`,
+  ];
+
+  if (entry?.disabledAt) {
+    lines.push(`  Disabled at: ${entry.disabledAt}`);
+  }
+  if (entry?.disabledReason) {
+    lines.push(`  Reason:      ${entry.disabledReason}`);
+  }
+
+  if (manifest.provides) {
+    lines.push("");
+    lines.push("  Provides:");
+    if (manifest.provides.tools?.length) {
+      lines.push(`    Tools:     ${manifest.provides.tools.join(", ")}`);
+    }
+    if (manifest.provides.commands?.length) {
+      lines.push(`    Commands:  ${manifest.provides.commands.join(", ")}`);
+    }
+    if (manifest.provides.hooks?.length) {
+      lines.push(`    Hooks:     ${manifest.provides.hooks.join(", ")}`);
+    }
+    if (manifest.provides.shortcuts?.length) {
+      lines.push(`    Shortcuts: ${manifest.provides.shortcuts.join(", ")}`);
+    }
+  }
+
+  if (manifest.dependencies) {
+    lines.push("");
+    lines.push("  Dependencies:");
+    if (manifest.dependencies.extensions?.length) {
+      lines.push(`    Extensions: ${manifest.dependencies.extensions.join(", ")}`);
+    }
+    if (manifest.dependencies.runtime?.length) {
+      lines.push(`    Runtime:    ${manifest.dependencies.runtime.join(", ")}`);
+    }
+  }
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+function padRight(str: string, len: number): string {
+  return str.length >= len ? str + " " : str + " ".repeat(len - str.length);
+}

package/dist/resources/extensions/gsd/commands-handlers.ts

@@ -9,6 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { deriveState } from "./state.js";
+import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import {
@@ -136,7 +137,7 @@ export async function handleCapture(args: string, ctx: ExtensionCommandContext):
   const basePath = process.cwd();
 
   // Ensure .gsd/ exists — capture should work even without a milestone
-  const gsdDir = join(basePath, ".gsd");
+  const gsdDir = gsdRoot(basePath);
   if (!existsSync(gsdDir)) {
     mkdirSync(gsdDir, { recursive: true });
   }

package/dist/resources/extensions/gsd/commands.ts

@@ -6,8 +6,10 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import type { GSDState } from "./types.js";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { enableDebug } from "./debug-logger.js";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
@@ -100,6 +102,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "update", desc: "Update GSD to the latest version" },
         { cmd: "start", desc: "Start a workflow template (bugfix, spike, feature, etc.)" },
         { cmd: "templates", desc: "List available workflow templates" },
+        { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -321,6 +324,47 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
           .map((c) => ({ value: `templates ${c.value}`, label: c.label, description: c.description }));
       }
 
+      if (parts[0] === "extensions") {
+        if (parts.length <= 2) {
+          const subPrefix = parts[1] ?? "";
+          const subs = [
+            { cmd: "list", desc: "List all extensions and their status" },
+            { cmd: "enable", desc: "Enable a disabled extension" },
+            { cmd: "disable", desc: "Disable an extension" },
+            { cmd: "info", desc: "Show extension details" },
+          ];
+          return subs
+            .filter((s) => s.cmd.startsWith(subPrefix))
+            .map((s) => ({ value: `extensions ${s.cmd}`, label: s.cmd, description: s.desc }));
+        }
+        if (parts.length === 3 && ["enable", "disable", "info"].includes(parts[1])) {
+          const idPrefix = parts[2] ?? "";
+          try {
+            const extDir = join(homedir(), ".gsd", "agent", "extensions");
+            const ids: { id: string; name: string }[] = [];
+            for (const entry of readdirSync(extDir, { withFileTypes: true })) {
+              if (!entry.isDirectory()) continue;
+              const mPath = join(extDir, entry.name, "extension-manifest.json");
+              if (!existsSync(mPath)) continue;
+              try {
+                const m = JSON.parse(readFileSync(mPath, "utf-8"));
+                if (typeof m?.id === "string") ids.push({ id: m.id, name: m.name ?? m.id });
+              } catch { /* skip malformed */ }
+            }
+            return ids
+              .filter((e) => e.id.startsWith(idPrefix))
+              .map((e) => ({
+                value: `extensions ${parts[1]} ${e.id}`,
+                label: e.id,
+                description: e.name,
+              }));
+          } catch {
+            return [];
+          }
+        }
+        return [];
+      }
+
       if (parts[0] === "doctor") {
         const modePrefix = parts[1] ?? "";
         const modes = [
@@ -698,7 +742,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (trimmed === "new-milestone") {
         const basePath = projectRoot();
-        const headlessContextPath = join(basePath, ".gsd", "runtime", "headless-context.md");
+        const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
         if (existsSync(headlessContextPath)) {
           const seedContext = readFileSync(headlessContextPath, "utf-8");
           try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }
@@ -829,6 +873,12 @@ Examples:
         return;
       }
 
+      if (trimmed === "extensions" || trimmed.startsWith("extensions ")) {
+        const { handleExtensions } = await import("./commands-extensions.js");
+        await handleExtensions(trimmed.replace(/^extensions\s*/, "").trim(), ctx);
+        return;
+      }
+
       ctx.ui.notify(
         `Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`,
         "warning",
@@ -877,6 +927,7 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd config         Set API keys for external tools",
     "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
     "  /gsd hooks          Show post-unit hook configuration",
+    "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",

package/dist/resources/extensions/gsd/detection.ts

@@ -9,6 +9,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { gsdRoot } from "./paths.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -214,7 +215,7 @@ export function detectV1Planning(basePath: string): V1Detection | null {
 // ─── V2 GSD Detection ──────────────────────────────────────────────────────────
 
 function detectV2Gsd(basePath: string): V2Detection | null {
-  const gsdPath = join(basePath, ".gsd");
+  const gsdPath = gsdRoot(basePath);
 
   if (!existsSync(gsdPath)) return null;
 

package/dist/resources/extensions/gsd/doctor-checks.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join, sep } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
@@ -13,6 +13,7 @@ import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelet
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { ensureGitignore } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
+import { recoverFailedMigration } from "./migrate-external.js";
 
 export async function checkGitHealth(
   basePath: string,
@@ -508,6 +509,53 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — gitignore check failed
   }
+
+  // ── External state symlink health ──────────────────────────────────────
+  try {
+    const localGsd = join(basePath, ".gsd");
+    if (existsSync(localGsd)) {
+      const stat = lstatSync(localGsd);
+
+      // Check for .gsd.migrating (failed migration)
+      const migratingPath = join(basePath, ".gsd.migrating");
+      if (existsSync(migratingPath)) {
+        issues.push({
+          severity: "error",
+          code: "failed_migration",
+          scope: "project",
+          unitId: "project",
+          message: "Found .gsd.migrating — a previous external state migration failed. State may be incomplete.",
+          file: ".gsd.migrating",
+          fixable: true,
+        });
+
+        if (shouldFix("failed_migration")) {
+          if (recoverFailedMigration(basePath)) {
+            fixesApplied.push("recovered failed migration (.gsd.migrating → .gsd)");
+          }
+        }
+      }
+
+      // Check symlink target exists
+      if (stat.isSymbolicLink()) {
+        try {
+          realpathSync(localGsd);
+        } catch {
+          issues.push({
+            severity: "error",
+            code: "broken_symlink",
+            scope: "project",
+            unitId: "project",
+            message: ".gsd symlink target does not exist. External state directory may have been deleted.",
+            file: ".gsd",
+            fixable: false,
+          });
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — external state check failed
+  }
 }
 
 /**

package/dist/resources/extensions/gsd/doctor-types.ts

@@ -30,7 +30,9 @@ export type DoctorIssueCode =
   | "state_file_stale"
   | "state_file_missing"
   | "gitignore_missing_patterns"
-  | "unresolvable_dependency";
+  | "unresolvable_dependency"
+  | "failed_migration"
+  | "broken_symlink";
 
 /**
  * Issue codes that represent expected completion-transition states.

package/dist/resources/extensions/gsd/extension-manifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "gsd",
+  "name": "GSD Workflow",
+  "version": "1.0.0",
+  "description": "Core GSD workflow engine — milestone planning, execution, and tracking",
+  "tier": "core",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": [
+      "bash", "write", "read", "edit",
+      "gsd_save_decision", "gsd_save_summary",
+      "gsd_update_requirement", "gsd_generate_milestone_id"
+    ],
+    "commands": ["gsd", "kill", "worktree", "exit"],
+    "hooks": ["session_start"],
+    "shortcuts": ["Ctrl+Alt+G"]
+  }
+}

package/dist/resources/extensions/gsd/forensics.ts

@@ -268,7 +268,7 @@ function resolveActivityDirs(basePath: string, activeMilestone?: string | null):
   if (activeMilestone) {
     const wtPath = getAutoWorktreePath(basePath, activeMilestone);
     if (wtPath) {
-      const wtActivityDir = join(wtPath, ".gsd", "activity");
+      const wtActivityDir = join(gsdRoot(wtPath), "activity");
       if (existsSync(wtActivityDir)) {
         dirs.push(wtActivityDir);
       }
@@ -285,7 +285,7 @@ function resolveActivityDirs(basePath: string, activeMilestone?: string | null):
 // ─── Completed Keys Loader ────────────────────────────────────────────────────
 
 function loadCompletedKeys(basePath: string): string[] {
-  const file = join(basePath, ".gsd", "completed-units.json");
+  const file = join(gsdRoot(basePath), "completed-units.json");
   try {
     if (existsSync(file)) {
       return JSON.parse(readFileSync(file, "utf-8"));

package/dist/resources/extensions/gsd/git-service.ts

@@ -11,6 +11,7 @@
 import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 import {
@@ -193,7 +194,7 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
  * Format: .gsd/milestones/<MID>/<MID>-META.json
  */
 function milestoneMetaPath(basePath: string, milestoneId: string): string {
-  return join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-META.json`);
+  return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 
 /**
@@ -237,7 +238,7 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
   if (existingBranch === branch) return;
 
   const metaFile = milestoneMetaPath(basePath, milestoneId);
-  mkdirSync(join(basePath, ".gsd", "milestones", milestoneId), { recursive: true });
+  mkdirSync(join(gsdRoot(basePath), "milestones", milestoneId), { recursive: true });
 
   // Merge with existing metadata if present
   let existing: Record<string, unknown> = {};