gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

package/dist/resources/extensions/gsd/commands-memory.js

@@ -0,0 +1,462 @@
+/**
+ * GSD Command — `/gsd memory`
+ *
+ * Subcommands:
+ *   list            — show recent active memories
+ *   show <id>       — print one memory
+ *   ingest <uri>    — persist a source row (file path, URL, or "-" for stdin-piped note)
+ *   note "<text>"   — persist an inline note as a source
+ *   forget <id>     — supersede a memory (CAP_EXCEEDED sentinel)
+ *   stats           — category / scope counts + source count
+ *   sources         — list recent memory_sources rows
+ *   extract <src>   — dispatch an agent turn that distils a source into memories
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { projectRoot } from "./commands/context.js";
+import { ingestFile, ingestNote, ingestUrl, summarizeIngest } from "./memory-ingest.js";
+import { getMemorySource, listMemorySources } from "./memory-source-store.js";
+import { createMemory, decayStaleMemories, enforceMemoryCap, getActiveMemories, getActiveMemoriesRanked, supersedeMemory, } from "./memory-store.js";
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { createMemoryRelation, listRelationsFor } from "./memory-relations.js";
+function parseArgs(raw) {
+    const tokens = splitArgs(raw);
+    const sub = (tokens.shift() ?? "list").toLowerCase();
+    const positional = [];
+    const tags = [];
+    let scope;
+    let extract = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (tok === "--tag" && i + 1 < tokens.length) {
+            tags.push(...tokens[++i].split(",").map((t) => t.trim()).filter(Boolean));
+            continue;
+        }
+        if (tok.startsWith("--tag=")) {
+            tags.push(...tok.slice("--tag=".length).split(",").map((t) => t.trim()).filter(Boolean));
+            continue;
+        }
+        if (tok === "--scope" && i + 1 < tokens.length) {
+            scope = tokens[++i];
+            continue;
+        }
+        if (tok.startsWith("--scope=")) {
+            scope = tok.slice("--scope=".length);
+            continue;
+        }
+        if (tok === "--extract") {
+            extract = true;
+            continue;
+        }
+        if (tok === "--no-extract") {
+            extract = false;
+            continue;
+        }
+        positional.push(tok);
+    }
+    return { sub, positional, tags, scope, extract };
+}
+function splitArgs(raw) {
+    const tokens = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let match;
+    while ((match = re.exec(raw)) !== null) {
+        tokens.push(match[1] ?? match[2] ?? match[3]);
+    }
+    return tokens;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+// ─── Handler ────────────────────────────────────────────────────────────────
+export async function handleMemory(args, ctx, pi) {
+    const parsed = parseArgs(args);
+    // `/gsd memory` or `/gsd memory help`
+    if (parsed.sub === "" || parsed.sub === "help") {
+        ctx.ui.notify(usage(), "info");
+        return;
+    }
+    // Most subcommands need the DB.
+    await ensureDb();
+    switch (parsed.sub) {
+        case "list":
+            handleList(ctx);
+            return;
+        case "show":
+            handleShow(ctx, parsed.positional[0]);
+            return;
+        case "forget":
+            handleForget(ctx, parsed.positional[0]);
+            return;
+        case "stats":
+            handleStats(ctx);
+            return;
+        case "sources":
+            handleSources(ctx);
+            return;
+        case "note":
+            await handleNote(ctx, parsed);
+            return;
+        case "ingest":
+            await handleIngest(ctx, parsed);
+            return;
+        case "extract":
+            handleExtractSource(ctx, pi, parsed.positional[0]);
+            return;
+        case "export":
+            handleExport(ctx, parsed.positional[0]);
+            return;
+        case "import":
+            handleImport(ctx, parsed.positional[0]);
+            return;
+        case "decay":
+            handleDecay(ctx);
+            return;
+        case "cap":
+            handleCap(ctx, parsed.positional[0]);
+            return;
+        default:
+            ctx.ui.notify(`Unknown subcommand "${parsed.sub}". ${usage()}`, "warning");
+            return;
+    }
+}
+function usage() {
+    return [
+        "Usage: /gsd memory <subcommand>",
+        "  list                    list recent active memories",
+        "  show <MEM###>           print one memory",
+        "  forget <MEM###>         supersede a memory",
+        "  stats                   counts by category / scope / sources / edges",
+        "  sources                 list recent memory_sources",
+        '  note "<text>"           ingest an inline note as a source',
+        "  ingest <path|url>       ingest a local file path or URL",
+        "  extract <SRC-xxx>       dispatch an LLM turn to extract memories from a source",
+        "  export <path.json>      dump memories + relations + sources to JSON",
+        "  import <path.json>      load a previous export (idempotent)",
+        "  decay                   run the stale-memory decay pass immediately",
+        "  cap [N]                 enforce the memory cap (default 50)",
+        "",
+        "Options: --tag a,b   --scope project|global|<custom>   --extract",
+    ].join("\n");
+}
+async function ensureDb() {
+    if (isDbAvailable())
+        return;
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    await ensureDbOpen();
+}
+function handleList(ctx) {
+    if (!isDbAvailable()) {
+        ctx.ui.notify("No GSD database available.", "warning");
+        return;
+    }
+    const memories = getActiveMemoriesRanked(50);
+    if (memories.length === 0) {
+        ctx.ui.notify("No active memories.", "info");
+        return;
+    }
+    const lines = memories.map((m) => `- [${m.id}] (${m.category}, conf ${m.confidence.toFixed(2)}, hits ${m.hit_count}${m.scope && m.scope !== "project" ? `, ${m.scope}` : ""}) ${truncate(m.content, 100)}`);
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+function handleShow(ctx, id) {
+    if (!id) {
+        ctx.ui.notify("Usage: /gsd memory show <MEM###>", "warning");
+        return;
+    }
+    const adapter = _getAdapter();
+    if (!adapter) {
+        ctx.ui.notify("No GSD database available.", "warning");
+        return;
+    }
+    const row = adapter.prepare("SELECT * FROM memories WHERE id = :id").get({ ":id": id });
+    if (!row) {
+        ctx.ui.notify(`Memory not found: ${id}`, "warning");
+        return;
+    }
+    const tags = row["tags"] ? safeJsonArray(row["tags"]) : [];
+    const lines = [
+        `ID: ${row["id"]}`,
+        `Category: ${row["category"]}`,
+        `Scope: ${row["scope"] ?? "project"}`,
+        `Confidence: ${Number(row["confidence"]).toFixed(2)}`,
+        `Hits: ${row["hit_count"]}`,
+        `Created: ${row["created_at"]}`,
+        `Updated: ${row["updated_at"]}`,
+        tags.length > 0 ? `Tags: ${tags.join(", ")}` : null,
+        row["superseded_by"] ? `Superseded by: ${row["superseded_by"]}` : null,
+        row["source_unit_type"] ? `Source: ${row["source_unit_type"]}/${row["source_unit_id"]}` : null,
+        "",
+        String(row["content"]),
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    ctx.ui.notify(lines, "info");
+}
+function handleForget(ctx, id) {
+    if (!id) {
+        ctx.ui.notify("Usage: /gsd memory forget <MEM###>", "warning");
+        return;
+    }
+    const ok = supersedeMemory(id, "CAP_EXCEEDED");
+    if (!ok) {
+        ctx.ui.notify(`Failed to forget ${id}.`, "warning");
+        return;
+    }
+    ctx.ui.notify(`Forgot ${id}.`, "info");
+}
+function handleStats(ctx) {
+    const adapter = _getAdapter();
+    if (!adapter) {
+        ctx.ui.notify("No GSD database available.", "warning");
+        return;
+    }
+    try {
+        const activeRow = adapter
+            .prepare("SELECT count(*) as cnt FROM memories WHERE superseded_by IS NULL")
+            .get();
+        const supersededRow = adapter
+            .prepare("SELECT count(*) as cnt FROM memories WHERE superseded_by IS NOT NULL")
+            .get();
+        const byCategory = adapter
+            .prepare("SELECT category, count(*) as cnt FROM memories WHERE superseded_by IS NULL GROUP BY category ORDER BY cnt DESC")
+            .all();
+        const byScope = adapter
+            .prepare("SELECT scope, count(*) as cnt FROM memories WHERE superseded_by IS NULL GROUP BY scope ORDER BY cnt DESC")
+            .all();
+        const sourcesRow = adapter.prepare("SELECT count(*) as cnt FROM memory_sources").get();
+        const sourcesByKind = adapter
+            .prepare("SELECT kind, count(*) as cnt FROM memory_sources GROUP BY kind ORDER BY cnt DESC")
+            .all();
+        const relationsRow = adapter.prepare("SELECT count(*) as cnt FROM memory_relations").get();
+        const relationsByRel = adapter
+            .prepare("SELECT rel, count(*) as cnt FROM memory_relations GROUP BY rel ORDER BY cnt DESC")
+            .all();
+        const embeddingsRow = adapter.prepare("SELECT count(*) as cnt FROM memory_embeddings").get();
+        const embeddedActiveRow = adapter
+            .prepare(`SELECT count(*) as cnt FROM memory_embeddings e
+         JOIN memories m ON m.id = e.memory_id
+         WHERE m.superseded_by IS NULL`)
+            .get();
+        const activeCount = activeRow?.["cnt"] ?? 0;
+        const embeddedActive = embeddedActiveRow?.["cnt"] ?? 0;
+        const coverage = activeCount > 0 ? `${Math.round((embeddedActive / activeCount) * 100)}%` : "n/a";
+        const out = [
+            `Active memories: ${activeCount}`,
+            `Superseded: ${supersededRow?.["cnt"] ?? 0}`,
+            "",
+            "By category:",
+            ...byCategory.map((row) => `  ${row["category"]}: ${row["cnt"]}`),
+            "",
+            "By scope:",
+            ...byScope.map((row) => `  ${row["scope"]}: ${row["cnt"]}`),
+            "",
+            `Memory sources: ${sourcesRow?.["cnt"] ?? 0}`,
+            ...sourcesByKind.map((row) => `  ${row["kind"]}: ${row["cnt"]}`),
+            "",
+            `Relations: ${relationsRow?.["cnt"] ?? 0}`,
+            ...relationsByRel.map((row) => `  ${row["rel"]}: ${row["cnt"]}`),
+            "",
+            `Embeddings: ${embeddingsRow?.["cnt"] ?? 0} total, ${embeddedActive} active (coverage ${coverage})`,
+        ].join("\n");
+        ctx.ui.notify(out, "info");
+    }
+    catch (err) {
+        ctx.ui.notify(`Stats failed: ${err.message}`, "warning");
+    }
+}
+function handleExport(ctx, target) {
+    if (!target) {
+        ctx.ui.notify("Usage: /gsd memory export <path.json>", "warning");
+        return;
+    }
+    try {
+        const active = getActiveMemories();
+        const relations = active.flatMap((m) => listRelationsFor(m.id).filter((r) => r.from === m.id));
+        const sources = listMemorySources(500);
+        const payload = {
+            version: 1,
+            exported_at: new Date().toISOString(),
+            memories: active.map((m) => ({
+                id: m.id,
+                category: m.category,
+                content: m.content,
+                confidence: m.confidence,
+                hit_count: m.hit_count,
+                scope: m.scope,
+                tags: m.tags,
+                source_unit_type: m.source_unit_type,
+                source_unit_id: m.source_unit_id,
+                created_at: m.created_at,
+                updated_at: m.updated_at,
+            })),
+            relations: relations.map((r) => ({
+                from: r.from,
+                to: r.to,
+                rel: r.rel,
+                confidence: r.confidence,
+            })),
+            sources,
+        };
+        const abs = resolvePath(process.cwd(), target);
+        writeFileSync(abs, JSON.stringify(payload, null, 2), "utf-8");
+        ctx.ui.notify(`Exported ${payload.memories.length} memories, ${payload.relations.length} relations, ${payload.sources.length} sources → ${abs}`, "info");
+    }
+    catch (err) {
+        ctx.ui.notify(`Export failed: ${err.message}`, "error");
+    }
+}
+function handleImport(ctx, target) {
+    if (!target) {
+        ctx.ui.notify("Usage: /gsd memory import <path.json>", "warning");
+        return;
+    }
+    try {
+        const abs = resolvePath(process.cwd(), target);
+        const raw = readFileSync(abs, "utf-8");
+        const parsed = JSON.parse(raw);
+        let memoryCount = 0;
+        let relationCount = 0;
+        for (const mem of parsed.memories ?? []) {
+            if (!mem.category || !mem.content)
+                continue;
+            // createMemory allocates a fresh seq → new MEM### id; imports replay
+            // content rather than preserving the old ID. Relations from the export
+            // file still reference the old IDs, so only lossless round-trips into
+            // an empty DB preserve the graph.
+            const id = createMemory({
+                category: mem.category,
+                content: mem.content,
+                confidence: mem.confidence,
+                scope: mem.scope,
+                tags: mem.tags,
+            });
+            if (id)
+                memoryCount++;
+        }
+        for (const rel of parsed.relations ?? []) {
+            if (!rel.from || !rel.to || !rel.rel)
+                continue;
+            if (createMemoryRelation(rel.from, rel.to, rel.rel, rel.confidence)) {
+                relationCount++;
+            }
+        }
+        ctx.ui.notify(`Imported ${memoryCount} memories and ${relationCount} relations.`, "info");
+    }
+    catch (err) {
+        ctx.ui.notify(`Import failed: ${err.message}`, "error");
+    }
+}
+function handleDecay(ctx) {
+    const decayed = decayStaleMemories(20);
+    if (decayed.length === 0) {
+        ctx.ui.notify("Decay pass: no stale memories found.", "info");
+        return;
+    }
+    ctx.ui.notify(`Decayed ${decayed.length} stale memor${decayed.length === 1 ? "y" : "ies"}: ${decayed.join(", ")}`, "info");
+}
+function handleCap(ctx, arg) {
+    const max = arg ? Number.parseInt(arg, 10) : 50;
+    if (!Number.isFinite(max) || max < 1) {
+        ctx.ui.notify("Usage: /gsd memory cap <max>  (default 50)", "warning");
+        return;
+    }
+    enforceMemoryCap(max);
+    ctx.ui.notify(`Enforced memory cap of ${max}.`, "info");
+}
+function handleSources(ctx) {
+    const sources = listMemorySources(30);
+    if (sources.length === 0) {
+        ctx.ui.notify("No memory sources yet. Use `/gsd memory ingest <path|url>` to add one.", "info");
+        return;
+    }
+    const lines = sources.map((s) => `- ${s.id} [${s.kind}${s.scope !== "project" ? `/${s.scope}` : ""}] ${truncate(s.title ?? s.uri ?? s.content, 100)}`);
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+async function handleNote(ctx, args) {
+    const text = args.positional.join(" ").trim();
+    if (!text) {
+        ctx.ui.notify('Usage: /gsd memory note "your note"', "warning");
+        return;
+    }
+    try {
+        const result = await ingestNote(text, null, {
+            scope: args.scope,
+            tags: args.tags,
+            extract: false,
+        });
+        ctx.ui.notify(summarizeIngest(result), "info");
+    }
+    catch (err) {
+        ctx.ui.notify(`Note ingest failed: ${err.message}`, "error");
+    }
+}
+async function handleIngest(ctx, args) {
+    const target = args.positional[0];
+    if (!target) {
+        ctx.ui.notify("Usage: /gsd memory ingest <path|url> [--tag a,b] [--scope project|global]", "warning");
+        return;
+    }
+    try {
+        const isUrl = /^https?:\/\//i.test(target);
+        const result = isUrl
+            ? await ingestUrl(target, null, { scope: args.scope, tags: args.tags, extract: false })
+            : await ingestFile(target, null, { scope: args.scope, tags: args.tags, extract: false });
+        ctx.ui.notify(summarizeIngest(result), "info");
+        if (args.extract && result.sourceId) {
+            // TODO (P3): dispatch agent turn to extract memories once source is stored.
+            ctx.ui.notify(`(Dispatching extraction turn — use \`/gsd memory extract ${result.sourceId}\` to trigger manually.)`, "info");
+        }
+    }
+    catch (err) {
+        ctx.ui.notify(`Ingest failed: ${err.message}`, "error");
+    }
+}
+function handleExtractSource(ctx, pi, id) {
+    if (!id) {
+        ctx.ui.notify("Usage: /gsd memory extract <SRC-xxx>", "warning");
+        return;
+    }
+    const source = getMemorySource(id);
+    if (!source) {
+        ctx.ui.notify(`Source not found: ${id}`, "warning");
+        return;
+    }
+    const prompt = buildExtractPrompt(source);
+    ctx.ui.notify(`Dispatching extraction turn for ${id}...`, "info");
+    pi.sendMessage({ customType: "gsd-memory-extract", content: prompt, display: false }, { triggerTurn: true });
+}
+function buildExtractPrompt(source) {
+    const header = [
+        `## Memory extraction request`,
+        ``,
+        `Source: ${source.id} (${source.kind})`,
+        source.title ? `Title: ${source.title}` : null,
+        source.uri ? `URI: ${source.uri}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return [
+        header,
+        "",
+        "Read the content below and call the `capture_thought` tool once per durable insight",
+        "(architecture, convention, gotcha, preference, environment, pattern). Skip one-off details,",
+        "temporary state, and anything secret. Keep each memory to 1–3 sentences.",
+        "",
+        "---",
+        "",
+        source.content,
+    ].join("\n");
+}
+function safeJsonArray(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter((t) => typeof t === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+// projectRoot is imported so tests can mock it via the same path as other commands.
+export const _internals = { projectRoot };

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -583,10 +583,20 @@ async function configureAdvanced(ctx, prefs) {
     }
 }
 // ─── Main wizard with category menu ─────────────────────────────────────────
-export async function handlePrefsWizard(ctx, scope) {
-    const path = scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath();
+export async function handlePrefsWizard(ctx, scope, prefill, opts) {
+    // pathOverride lets callers like /gsd init pass a basePath-derived target
+    // path so the wizard doesn't fall back to cwd-based getProjectGSDPreferencesPath
+    // when the init target diverges from the current working directory.
+    const path = opts?.pathOverride
+        ?? (scope === "project" ? getProjectGSDPreferencesPath() : getGlobalGSDPreferencesPath());
     const existing = scope === "project" ? loadProjectGSDPreferences() : loadGlobalGSDPreferences();
-    const prefs = existing?.preferences ? { ...existing.preferences } : {};
+    // Order: existing-on-disk values, overlaid with prefill (caller's seeded answers).
+    // Callers like /gsd init pass freshly-collected init answers as prefill so the
+    // wizard menu shows them populated and writeable in one place.
+    const prefs = {
+        ...(existing?.preferences ?? {}),
+        ...(prefill ?? {}),
+    };
     ctx.ui.notify(`GSD preferences (${scope}) — pick a category to configure.`, "info");
     while (true) {
         const summaries = buildCategorySummaries(prefs);
@@ -622,11 +632,24 @@ export async function handlePrefsWizard(ctx, scope) {
         else if (choice.startsWith("Advanced"))
             await configureAdvanced(ctx, prefs);
     }
-    // ─── Serialize to frontmatter ───────────────────────────────────────────
-    prefs.version = prefs.version || 1;
-    const frontmatter = serializePreferencesToFrontmatter(prefs);
-    // Preserve existing body content (everything after closing ---)
-    let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    await writePreferencesFile(path, prefs, ctx, { scope });
+}
+/**
+ * Single source of truth for writing a PREFERENCES.md file.
+ *
+ * Both `/gsd init` and the prefs wizard route through this helper so we can't
+ * drift on serialization, body preservation, or post-write reload. Callers
+ * pass `ctx` for the reload/notify side effects; the function is safe to call
+ * without a full UI context for tests via `ctx: null` (skips reload/notify).
+ */
+export async function writePreferencesFile(path, prefs, ctx, opts) {
+    const next = { ...prefs, version: prefs.version || 1 };
+    const frontmatter = serializePreferencesToFrontmatter(next);
+    const fallbackBody = opts?.defaultBody
+        ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+    // Preserve existing body content (everything after closing ---) so users
+    // who edited the markdown body don't lose their notes.
+    let body = fallbackBody;
     if (existsSync(path)) {
         const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8"));
         if (preserved)
@@ -634,9 +657,14 @@ export async function handlePrefsWizard(ctx, scope) {
     }
     const content = `---\n${frontmatter}---${body}`;
     await saveFile(path, content);
-    await ctx.waitForIdle();
-    await ctx.reload();
-    ctx.ui.notify(`Saved ${scope} preferences to ${path}`, "info");
+    if (ctx) {
+        await ctx.waitForIdle();
+        await ctx.reload();
+        if (opts?.notifyOnSave !== false) {
+            const scopeLabel = opts?.scope ? `${opts.scope} ` : "";
+            ctx.ui.notify(`Saved ${scopeLabel}preferences to ${path}`, "info");
+        }
+    }
 }
 /** Wrap a YAML value in double quotes if it contains special characters. */
 export function yamlSafeString(val) {
@@ -742,7 +770,7 @@ export async function ensurePreferencesFile(path, ctx, scope) {
 /**
  * Handle `/gsd language [code]` — set or clear the global language preference.
  * Without an argument, shows the current setting.
- * Project-level override can be set by editing `.gsd/preferences.md` directly
+ * Project-level override can be set by editing `.gsd/PREFERENCES.md` directly
  * (project language overrides global when both are set).
  */
 export async function handleLanguage(args, ctx) {

package/dist/resources/extensions/gsd/commands-scan.js

@@ -0,0 +1,94 @@
+/**
+ * GSD Command — /gsd scan
+ *
+ * Rapid codebase assessment — lightweight alternative to /gsd map-codebase.
+ * Spawns one focused AI analysis pass and writes structured documents to
+ * .gsd/codebase/ for use by planning and execution phases.
+ *
+ * Usage:
+ *   /gsd scan                   — tech+arch focus (default)
+ *   /gsd scan --focus tech      — technology stack + integrations only
+ *   /gsd scan --focus arch      — architecture + structure only
+ *   /gsd scan --focus quality   — conventions + testing patterns only
+ *   /gsd scan --focus concerns  — technical debt + concerns only
+ *   /gsd scan --focus tech+arch — explicit default (same as no flag)
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadPrompt } from "./prompt-loader.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const DEFAULT_FOCUS = "tech+arch";
+export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"];
+const FOCUS_DOCUMENTS = {
+    tech: ["STACK", "INTEGRATIONS"],
+    arch: ["ARCHITECTURE", "STRUCTURE"],
+    quality: ["CONVENTIONS", "TESTING"],
+    concerns: ["CONCERNS"],
+    "tech+arch": ["STACK", "INTEGRATIONS", "ARCHITECTURE", "STRUCTURE"],
+};
+// ─── Exported functions (exported for testing) ───────────────────────────────
+// Note: checkExistingDocuments reads the filesystem and is not purely functional.
+/**
+ * Parse --focus flag from raw args string.
+ * Returns default focus when flag is missing or the value is invalid.
+ * Shell-injection safe: only well-known values are accepted.
+ */
+export function parseScanArgs(args) {
+    const match = args.match(/--focus\s+([^\s]+)/i);
+    if (!match)
+        return { focus: DEFAULT_FOCUS };
+    const raw = match[1].toLowerCase();
+    if (VALID_FOCUS_AREAS.includes(raw)) {
+        return { focus: raw };
+    }
+    return { focus: DEFAULT_FOCUS };
+}
+/**
+ * Return the list of document names (without extension) to generate for a focus.
+ * Falls back to the default focus documents for unknown values.
+ */
+export function resolveScanDocuments(focus) {
+    return FOCUS_DOCUMENTS[focus] ?? FOCUS_DOCUMENTS[DEFAULT_FOCUS];
+}
+/**
+ * Build absolute output paths for the documents produced by a scan focus.
+ * All documents live under <basePath>/.gsd/codebase/
+ */
+export function buildScanOutputPaths(focus, basePath) {
+    const docs = resolveScanDocuments(focus);
+    return docs.map((doc) => join(basePath, ".gsd", "codebase", `${doc}.md`));
+}
+/**
+ * Return the subset of paths that already exist on disk.
+ */
+export function checkExistingDocuments(paths) {
+    return paths.filter((p) => existsSync(p));
+}
+// ─── Command handler ──────────────────────────────────────────────────────────
+export async function handleScan(args, ctx, pi) {
+    const basePath = process.cwd();
+    const { focus } = parseScanArgs(args);
+    const outputDir = join(basePath, ".gsd", "codebase");
+    const outputPaths = buildScanOutputPaths(focus, basePath);
+    const existing = checkExistingDocuments(outputPaths);
+    if (existing.length > 0) {
+        const names = existing.map((p) => relative(outputDir, p)).join(", ");
+        ctx.ui.notify(`Existing documents will be overwritten: ${names}\nContinuing scan with focus: ${focus}`, "warning");
+    }
+    mkdirSync(outputDir, { recursive: true });
+    const documents = resolveScanDocuments(focus);
+    ctx.ui.notify(`Running codebase scan (focus: ${focus})…`, "info");
+    try {
+        const prompt = loadPrompt("scan", {
+            focus,
+            documents: documents.join(", "),
+            outputDir: outputDir.replaceAll("\\", "/"),
+            workingDirectory: basePath,
+        });
+        pi.sendMessage({ customType: "gsd-scan", content: prompt, display: false }, { triggerTurn: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Failed to dispatch scan: ${msg}`, "error");
+    }
+}