gsd-pi 2.33.1 → 2.34.0-dev.0150ae9

package/dist/resources/extensions/gsd/triage-ui.js

@@ -0,0 +1,125 @@
+/**
+ * GSD Triage UI — Confirmation flow for programmatic triage results
+ *
+ * Used by auto-mode dispatch (S02) when triage fires between tasks.
+ * For manual `/gsd triage`, the LLM session handles confirmation directly.
+ *
+ * This module provides `showTriageConfirmation` which presents each
+ * triage result to the user via `showNextAction` and returns the
+ * confirmed classifications.
+ */
+import { showNextAction } from "../shared/mod.js";
+import { markCaptureResolved } from "./captures.js";
+// ─── Classification Labels ────────────────────────────────────────────────────
+const CLASSIFICATION_LABELS = {
+    "quick-task": {
+        label: "Quick task",
+        description: "Execute as a one-off at the next seam — no plan modification.",
+    },
+    "inject": {
+        label: "Inject into plan",
+        description: "Add a new task to the current slice plan.",
+    },
+    "defer": {
+        label: "Defer",
+        description: "Move to a future slice or milestone — not urgent now.",
+    },
+    "replan": {
+        label: "Replan slice",
+        description: "Remaining tasks need rewriting — triggers slice replan.",
+    },
+    "note": {
+        label: "Note",
+        description: "Informational only — no action needed.",
+    },
+};
+const ALL_CLASSIFICATIONS = [
+    "quick-task", "inject", "defer", "replan", "note",
+];
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Present triage results to the user for confirmation.
+ *
+ * For each capture:
+ * - note/defer: auto-confirm (no user interaction needed)
+ * - quick-task/inject/replan: show confirmation UI with proposed + alternatives
+ *
+ * Returns confirmed results with final classifications.
+ * Updates CAPTURES.md with resolved status.
+ *
+ * @param fileOverlaps - Map of captureId → list of planned task IDs whose files overlap
+ */
+export async function showTriageConfirmation(ctx, triageResults, captures, basePath, fileOverlaps) {
+    const confirmed = [];
+    const captureMap = new Map(captures.map(c => [c.id, c]));
+    for (const result of triageResults) {
+        const capture = captureMap.get(result.captureId);
+        if (!capture)
+            continue;
+        // Auto-confirm note and defer — low-impact, no plan modification
+        if (result.classification === "note" || result.classification === "defer") {
+            const resolution = result.classification === "note"
+                ? "acknowledged as note"
+                : `deferred${result.targetSlice ? ` to ${result.targetSlice}` : ""}`;
+            markCaptureResolved(basePath, result.captureId, result.classification, resolution, result.rationale);
+            confirmed.push({
+                captureId: result.captureId,
+                classification: result.classification,
+                rationale: result.rationale,
+                affectedFiles: result.affectedFiles,
+                targetSlice: result.targetSlice,
+                userOverride: false,
+            });
+            continue;
+        }
+        // Build summary lines for the confirmation UI
+        const summary = [
+            `"${capture.text}"`,
+            "",
+            `Proposed: **${CLASSIFICATION_LABELS[result.classification].label}** — ${result.rationale}`,
+        ];
+        // Add file overlap warning if present
+        const overlaps = fileOverlaps?.get(result.captureId);
+        if (overlaps && overlaps.length > 0) {
+            summary.push("");
+            summary.push(`⚠ Touches files planned for ${overlaps.join(", ")} — consider inject or defer`);
+        }
+        if (result.affectedFiles && result.affectedFiles.length > 0) {
+            summary.push("");
+            summary.push(`Files: ${result.affectedFiles.join(", ")}`);
+        }
+        // Build action options — proposed first (recommended), then alternatives
+        const proposed = result.classification;
+        const actions = ALL_CLASSIFICATIONS.map(cls => ({
+            id: cls,
+            label: CLASSIFICATION_LABELS[cls].label,
+            description: CLASSIFICATION_LABELS[cls].description,
+            recommended: cls === proposed,
+        }));
+        const choice = await showNextAction(ctx, {
+            title: `Triage: ${result.captureId}`,
+            summary,
+            actions,
+            notYetMessage: "Capture will remain pending for later triage.",
+        });
+        if (choice === "not_yet") {
+            // User skipped — leave capture pending
+            continue;
+        }
+        const finalClassification = choice;
+        const userOverride = finalClassification !== proposed;
+        const resolution = userOverride
+            ? `user chose ${finalClassification} (was ${proposed})`
+            : `confirmed as ${finalClassification}`;
+        markCaptureResolved(basePath, result.captureId, finalClassification, resolution, userOverride ? `User override: ${result.rationale}` : result.rationale);
+        confirmed.push({
+            captureId: result.captureId,
+            classification: finalClassification,
+            rationale: result.rationale,
+            affectedFiles: result.affectedFiles,
+            targetSlice: result.targetSlice,
+            userOverride,
+        });
+    }
+    return confirmed;
+}

package/dist/resources/extensions/gsd/types.js

@@ -0,0 +1,4 @@
+// GSD Extension — Core Type Definitions
+// Types consumed by state derivation, file parsing, and status display.
+// Pure interfaces — no logic, no runtime dependencies.
+export {};

package/dist/resources/extensions/gsd/undo.js

@@ -0,0 +1,205 @@
+// GSD Extension — Undo Last Unit
+// Rollback the most recent completed unit: revert git, remove state, uncheck plans.
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { nativeRevertCommit, nativeRevertAbort } from "./native-git-bridge.js";
+import { deriveState } from "./state.js";
+import { invalidateAllCaches } from "./cache.js";
+import { gsdRoot, resolveTasksDir, resolveSlicePath, buildTaskFileName } from "./paths.js";
+import { sendDesktopNotification } from "./notifications.js";
+/**
+ * Undo the last completed unit: revert git commits,
+ * delete summary artifacts, and uncheck the task in PLAN.
+ * deriveState() handles re-derivation after revert.
+ */
+export async function handleUndo(args, ctx, _pi, basePath) {
+    const force = args.includes("--force");
+    // Find the last GSD-related commit from git activity logs
+    const activityDir = join(gsdRoot(basePath), "activity");
+    if (!existsSync(activityDir)) {
+        ctx.ui.notify("Nothing to undo — no activity logs found.", "info");
+        return;
+    }
+    // Parse activity logs to find the most recent unit
+    const files = readdirSync(activityDir)
+        .filter(f => f.endsWith(".jsonl"))
+        .sort()
+        .reverse();
+    if (files.length === 0) {
+        ctx.ui.notify("Nothing to undo — no activity logs found.", "info");
+        return;
+    }
+    // Extract unit type and ID from the most recent activity log filename
+    // Format: <seq>-<unitType>-<unitId>.jsonl
+    const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
+    if (!match) {
+        ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
+        return;
+    }
+    const unitType = match[1];
+    const unitId = match[2].replace(/-/g, "/");
+    if (!force) {
+        ctx.ui.notify(`Will undo: ${unitType} (${unitId})\n` +
+            `This will:\n` +
+            `  - Delete summary artifacts\n` +
+            `  - Uncheck task in PLAN (if execute-task)\n` +
+            `  - Attempt to revert associated git commits\n\n` +
+            `Run /gsd undo --force to confirm.`, "warning");
+        return;
+    }
+    // 1. Delete summary artifact
+    const parts = unitId.split("/");
+    let summaryRemoved = false;
+    if (parts.length === 3) {
+        // Task-level: M001/S01/T01
+        const [mid, sid, tid] = parts;
+        const tasksDir = resolveTasksDir(basePath, mid, sid);
+        if (tasksDir) {
+            const summaryFile = join(tasksDir, buildTaskFileName(tid, "SUMMARY"));
+            if (existsSync(summaryFile)) {
+                unlinkSync(summaryFile);
+                summaryRemoved = true;
+            }
+        }
+    }
+    else if (parts.length === 2) {
+        // Slice-level: M001/S01
+        const [mid, sid] = parts;
+        const slicePath = resolveSlicePath(basePath, mid, sid);
+        if (slicePath) {
+            for (const suffix of ["SUMMARY", "COMPLETE"]) {
+                const candidates = findFileWithPrefix(slicePath, sid, suffix);
+                for (const f of candidates) {
+                    unlinkSync(f);
+                    summaryRemoved = true;
+                }
+            }
+        }
+    }
+    // 2. Uncheck task in PLAN if execute-task
+    let planUpdated = false;
+    if (unitType === "execute-task" && parts.length === 3) {
+        const [mid, sid, tid] = parts;
+        planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+    }
+    // 3. Try to revert git commits from activity log
+    let commitsReverted = 0;
+    try {
+        const commits = findCommitsForUnit(activityDir, unitType, unitId);
+        if (commits.length > 0) {
+            for (const sha of commits.reverse()) {
+                try {
+                    nativeRevertCommit(basePath, sha);
+                    commitsReverted++;
+                }
+                catch {
+                    // Revert conflict or already reverted — skip
+                    try {
+                        nativeRevertAbort(basePath);
+                    }
+                    catch { /* no-op */ }
+                    break;
+                }
+            }
+        }
+    }
+    finally {
+        // 4. Re-derive state — always invalidate caches even if git operations fail
+        invalidateAllCaches();
+        await deriveState(basePath);
+    }
+    // Build result message
+    const results = [`Undone: ${unitType} (${unitId})`];
+    if (summaryRemoved)
+        results.push(`  - Deleted summary artifact`);
+    if (planUpdated)
+        results.push(`  - Unchecked task in PLAN`);
+    if (commitsReverted > 0) {
+        results.push(`  - Reverted ${commitsReverted} commit(s) (staged, not committed)`);
+        results.push(`  Review with 'git diff --cached' then 'git commit' or 'git reset HEAD'`);
+    }
+    ctx.ui.notify(results.join("\n"), "success");
+    sendDesktopNotification("GSD", `Undone: ${unitType} (${unitId})`, "info", "complete");
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+export function uncheckTaskInPlan(basePath, mid, sid, tid) {
+    const slicePath = resolveSlicePath(basePath, mid, sid);
+    if (!slicePath)
+        return false;
+    // Find the PLAN file
+    const planCandidates = findFileWithPrefix(slicePath, sid, "PLAN");
+    if (planCandidates.length === 0)
+        return false;
+    const planFile = planCandidates[0];
+    let content = readFileSync(planFile, "utf-8");
+    // Match checked task line: - [x] **T01** or - [x] T01:
+    const regex = new RegExp(`^(\\s*-\\s*)\\[x\\](\\s*\\**${tid}\\**[:\\s])`, "mi");
+    if (regex.test(content)) {
+        content = content.replace(regex, "$1[ ]$2");
+        writeFileSync(planFile, content, "utf-8");
+        return true;
+    }
+    return false;
+}
+function findFileWithPrefix(dir, prefix, suffix) {
+    try {
+        const files = readdirSync(dir);
+        return files
+            .filter(f => f.includes(suffix) && (f.startsWith(prefix) || f.startsWith(`${prefix}-`)))
+            .map(f => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+export function findCommitsForUnit(activityDir, unitType, unitId) {
+    const safeUnitId = unitId.replace(/\//g, "-");
+    const commitSet = new Set();
+    const commits = [];
+    try {
+        const files = readdirSync(activityDir)
+            .filter(f => f.includes(unitType) && f.includes(safeUnitId) && f.endsWith(".jsonl"))
+            .sort()
+            .reverse();
+        if (files.length === 0)
+            return [];
+        // Parse the most recent activity log for this unit
+        const content = readFileSync(join(activityDir, files[0]), "utf-8");
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                // Look for tool results containing git commit output
+                if (entry?.message?.content) {
+                    const blocks = Array.isArray(entry.message.content) ? entry.message.content : [];
+                    for (const block of blocks) {
+                        if (block.type === "tool_result" && typeof block.content === "string") {
+                            for (const sha of extractCommitShas(block.content)) {
+                                if (!commitSet.has(sha)) {
+                                    commitSet.add(sha);
+                                    commits.push(sha);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch { /* malformed JSON line — skip */ }
+        }
+    }
+    catch { /* activity dir issues — skip */ }
+    return commits;
+}
+export function extractCommitShas(content) {
+    const seen = new Set();
+    const commits = [];
+    for (const match of content.matchAll(/\[[\w/.-]+\s+([a-f0-9]{7,40})\]/g)) {
+        const sha = match[1];
+        if (sha && !seen.has(sha)) {
+            seen.add(sha);
+            commits.push(sha);
+        }
+    }
+    return commits;
+}

package/dist/resources/extensions/gsd/unit-id.js

@@ -0,0 +1,7 @@
+// GSD Extension — Unit ID Parsing
+// Centralizes the milestone/slice/task decomposition of unit ID strings.
+/** Parse a unit ID string (e.g. "M1/S1/T1") into its milestone, slice, and task components. */
+export function parseUnitId(unitId) {
+    const [milestone, slice, task] = unitId.split("/");
+    return { milestone: milestone, slice, task };
+}

package/dist/resources/extensions/gsd/unit-runtime.js

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot, relSliceFile, relTaskFile, resolveSliceFile, resolveTaskFile, } from "./paths.js";
+import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
+function runtimeDir(basePath) {
+    return join(gsdRoot(basePath), "runtime", "units");
+}
+function runtimePath(basePath, unitType, unitId) {
+    const sanitizedUnitType = unitType.replace(/[\/]/g, "-");
+    const sanitizedUnitId = unitId.replace(/[\/]/g, "-");
+    return join(runtimeDir(basePath), `${sanitizedUnitType}-${sanitizedUnitId}.json`);
+}
+export function writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, updates = {}) {
+    const dir = runtimeDir(basePath);
+    mkdirSync(dir, { recursive: true });
+    const path = runtimePath(basePath, unitType, unitId);
+    const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const next = {
+        version: 1,
+        unitType,
+        unitId,
+        startedAt,
+        updatedAt: Date.now(),
+        phase: updates.phase ?? prev?.phase ?? "dispatched",
+        wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+        continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
+        timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+        lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+        progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+        lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+        recovery: updates.recovery ?? prev?.recovery,
+        recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+        lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+    };
+    writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+    return next;
+}
+export function readUnitRuntimeRecord(basePath, unitType, unitId) {
+    const path = runtimePath(basePath, unitType, unitId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function clearUnitRuntimeRecord(basePath, unitType, unitId) {
+    const path = runtimePath(basePath, unitType, unitId);
+    if (existsSync(path))
+        unlinkSync(path);
+}
+/**
+ * Return all runtime records currently on disk for `basePath`.
+ * Returns an empty array if the runtime directory does not exist.
+ */
+export function listUnitRuntimeRecords(basePath) {
+    const dir = runtimeDir(basePath);
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, file), "utf-8");
+            const record = JSON.parse(raw);
+            results.push(record);
+        }
+        catch {
+            // Skip malformed files
+        }
+    }
+    return results;
+}
+export async function inspectExecuteTaskDurability(basePath, unitId) {
+    const [mid, sid, tid] = unitId.split("/");
+    if (!mid || !sid || !tid)
+        return null;
+    const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");
+    const summaryAbs = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+    const stateAbs = join(gsdRoot(basePath), "STATE.md");
+    const planPath = relSliceFile(basePath, mid, sid, "PLAN");
+    const summaryPath = relTaskFile(basePath, mid, sid, tid, "SUMMARY");
+    const planContent = planAbs ? await loadFile(planAbs) : null;
+    const stateContent = existsSync(stateAbs) ? readFileSync(stateAbs, "utf-8") : "";
+    const summaryExists = !!(summaryAbs && existsSync(summaryAbs));
+    const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
+    const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+    // Must-have coverage: load task plan and count mentions in summary
+    let mustHaveCount = 0;
+    let mustHavesMentionedInSummary = 0;
+    const taskPlanAbs = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+    if (taskPlanAbs) {
+        const taskPlanContent = await loadFile(taskPlanAbs);
+        if (taskPlanContent) {
+            const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+            mustHaveCount = mustHaves.length;
+            if (mustHaveCount > 0 && summaryExists && summaryAbs) {
+                const summaryContent = await loadFile(summaryAbs);
+                if (summaryContent) {
+                    mustHavesMentionedInSummary = countMustHavesMentionedInSummary(mustHaves, summaryContent);
+                }
+            }
+        }
+    }
+    return {
+        planPath,
+        summaryPath,
+        summaryExists,
+        taskChecked,
+        nextActionAdvanced,
+        mustHaveCount,
+        mustHavesMentionedInSummary,
+    };
+}
+export function formatExecuteTaskRecoveryStatus(status) {
+    const missing = [];
+    if (!status.summaryExists)
+        missing.push(`summary missing (${status.summaryPath})`);
+    if (!status.taskChecked)
+        missing.push(`task checkbox unchecked in ${status.planPath}`);
+    if (!status.nextActionAdvanced)
+        missing.push("state next action still points at the timed-out task");
+    if (status.mustHaveCount > 0 && status.mustHavesMentionedInSummary < status.mustHaveCount) {
+        missing.push(`must-have gap: ${status.mustHavesMentionedInSummary} of ${status.mustHaveCount} must-haves addressed in summary`);
+    }
+    return missing.length > 0 ? missing.join("; ") : "all durable task artifacts present";
+}

package/dist/resources/extensions/gsd/validate-directory.js

@@ -0,0 +1,143 @@
+/**
+ * GSD Directory Validation — Safeguards against running in dangerous directories.
+ *
+ * Prevents GSD from creating .gsd/ structures in system paths, home directories,
+ * or other locations where writing project scaffolding would be harmful.
+ */
+import { realpathSync, readdirSync } from "node:fs";
+import { homedir, platform, tmpdir } from "node:os";
+import { resolve } from "node:path";
+// ─── Blocked Paths ──────────────────────────────────────────────────────────────
+/** Paths where GSD must never create .gsd/ — no override possible. */
+const UNIX_BLOCKED_PATHS = new Set([
+    "/",
+    "/bin",
+    "/sbin",
+    "/usr",
+    "/usr/bin",
+    "/usr/sbin",
+    "/usr/lib",
+    "/usr/local",
+    "/usr/local/bin",
+    "/etc",
+    "/var",
+    "/var/tmp",
+    "/dev",
+    "/proc",
+    "/sys",
+    "/boot",
+    "/lib",
+    "/lib64",
+    // macOS-specific
+    "/System",
+    "/Library",
+    "/Applications",
+    "/Volumes",
+    "/private",
+    "/private/var",
+    "/private/etc",
+    "/private/tmp",
+]);
+const WINDOWS_BLOCKED_PATHS = new Set([
+    "C:\\",
+    "C:\\Windows",
+    "C:\\Windows\\System32",
+    "C:\\Program Files",
+    "C:\\Program Files (x86)",
+]);
+// ─── Core Validation ────────────────────────────────────────────────────────────
+/**
+ * Validate whether a directory is safe for GSD to operate in.
+ *
+ * Checks in order:
+ * 1. Blocked system paths (hard stop)
+ * 2. Home directory itself (hard stop)
+ * 3. Temp directory root (hard stop)
+ * 4. High entry count heuristic (warning)
+ */
+export function validateDirectory(dirPath) {
+    // Resolve to absolute + follow symlinks so aliases can't bypass checks
+    let resolved;
+    try {
+        resolved = realpathSync(resolve(dirPath));
+    }
+    catch {
+        // If we can't resolve, use the raw resolved path
+        resolved = resolve(dirPath);
+    }
+    // Normalize trailing slashes for consistent comparison.
+    // Special cases: "/" → "/" (not ""), "C:\" → "C:\" (not "C:")
+    let normalized = resolved.replace(/[/\\]+$/, "");
+    if (normalized === "") {
+        normalized = "/";
+    }
+    else if (/^[A-Za-z]:$/.test(normalized)) {
+        normalized = normalized + "\\";
+    }
+    // ── Check 1: Blocked system paths ──────────────────────────────────────
+    const blockedPaths = platform() === "win32" ? WINDOWS_BLOCKED_PATHS : UNIX_BLOCKED_PATHS;
+    if (blockedPaths.has(normalized)) {
+        return {
+            safe: false,
+            severity: "blocked",
+            reason: `Refusing to run in system directory: ${normalized}. GSD must be run inside a project directory.`,
+        };
+    }
+    // ── Check 2: Home directory itself (not subdirs) ───────────────────────
+    let resolvedHome;
+    try {
+        resolvedHome = realpathSync(resolve(homedir())).replace(/[/\\]+$/, "");
+    }
+    catch {
+        resolvedHome = resolve(homedir()).replace(/[/\\]+$/, "");
+    }
+    if (normalized === resolvedHome) {
+        return {
+            safe: false,
+            severity: "blocked",
+            reason: `Refusing to run in your home directory (${normalized}). GSD must be run inside a project directory, not $HOME.`,
+        };
+    }
+    // ── Check 3: Temp directory root ───────────────────────────────────────
+    let resolvedTmp;
+    try {
+        resolvedTmp = realpathSync(resolve(tmpdir())).replace(/[/\\]+$/, "");
+    }
+    catch {
+        resolvedTmp = resolve(tmpdir()).replace(/[/\\]+$/, "");
+    }
+    if (normalized === resolvedTmp) {
+        return {
+            safe: false,
+            severity: "blocked",
+            reason: `Refusing to run in the system temp directory (${normalized}). Use a project subdirectory instead.`,
+        };
+    }
+    // ── Check 4: Suspiciously large directory (heuristic warning) ──────────
+    try {
+        const entries = readdirSync(normalized);
+        if (entries.length > 200) {
+            return {
+                safe: false,
+                severity: "warning",
+                reason: `This directory has ${entries.length} entries, which suggests it may not be a project directory. Are you sure you want to initialize GSD here?`,
+            };
+        }
+    }
+    catch {
+        // Can't read directory — let downstream handle the error
+    }
+    return { safe: true, severity: "ok" };
+}
+/**
+ * Assert that a directory is safe for GSD operations.
+ * Throws with a descriptive message if the directory is blocked.
+ * Returns the validation result for warnings (caller decides how to handle).
+ */
+export function assertSafeDirectory(dirPath) {
+    const result = validateDirectory(dirPath);
+    if (result.severity === "blocked") {
+        throw new Error(result.reason);
+    }
+    return result;
+}