gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/gsd/native-parser-bridge.js

@@ -0,0 +1,156 @@
+// Native GSD Parser Bridge
+// Provides drop-in replacements for the JS parsing functions in files.ts,
+// backed by the Rust native parser for better performance on large projects.
+//
+// Functions fall back to JS implementations if the native module is unavailable.
+// Issue #453: auto-mode post-turn reconciliation must stay on the stable JS path
+// unless the native parser is explicitly requested.
+const NATIVE_GSD_PARSER_ENABLED = process.env.GSD_ENABLE_NATIVE_GSD_PARSER === "1";
+let nativeModule = null;
+let loadAttempted = false;
+function loadNative() {
+    if (loadAttempted)
+        return nativeModule;
+    loadAttempted = true;
+    if (!NATIVE_GSD_PARSER_ENABLED)
+        return nativeModule;
+    try {
+        // Dynamic import to avoid hard dependency - fails gracefully if native module not built
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('@gsd/native');
+        if (mod.parseFrontmatter && mod.extractSection && mod.batchParseGsdFiles) {
+            nativeModule = mod;
+        }
+    }
+    catch {
+        // Native module not available - all functions fall back to JS
+    }
+    return nativeModule;
+}
+/**
+ * Native-backed frontmatter splitting.
+ * Returns [parsedMetadata, body] where parsedMetadata is the parsed key-value map.
+ */
+export function nativeSplitFrontmatter(content) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    const result = native.parseFrontmatter(content);
+    return {
+        metadata: JSON.parse(result.metadata),
+        body: result.body,
+    };
+}
+/** Sentinel value indicating the native module is not available. */
+const NATIVE_UNAVAILABLE = Symbol('native-unavailable');
+/**
+ * Native-backed section extraction.
+ * Returns section content, null if not found, or NATIVE_UNAVAILABLE symbol
+ * if the native module isn't loaded.
+ */
+export function nativeExtractSection(content, heading, level = 2) {
+    const native = loadNative();
+    if (!native)
+        return NATIVE_UNAVAILABLE;
+    const result = native.extractSection(content, heading, level);
+    return result.found ? result.content : null;
+}
+export { NATIVE_UNAVAILABLE };
+/**
+ * Native-backed roadmap parsing.
+ * Returns a Roadmap object or null if native module unavailable.
+ */
+export function nativeParseRoadmap(content) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    const result = native.parseRoadmapFile(content);
+    return {
+        title: result.title,
+        vision: result.vision,
+        successCriteria: result.successCriteria,
+        slices: result.slices.map(s => ({
+            id: s.id,
+            title: s.title,
+            risk: s.risk,
+            depends: s.depends,
+            done: s.done,
+            demo: s.demo,
+        })),
+        boundaryMap: result.boundaryMap.map(b => ({
+            fromSlice: b.fromSlice,
+            toSlice: b.toSlice,
+            produces: b.produces,
+            consumes: b.consumes,
+        })),
+    };
+}
+/**
+ * Batch-parse all .md files in a .gsd/ directory tree using the native parser.
+ * Returns null if native module unavailable.
+ */
+export function nativeBatchParseGsdFiles(directory) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    const result = native.batchParseGsdFiles(directory);
+    return result.files.map(f => ({
+        path: f.path,
+        metadata: JSON.parse(f.metadata),
+        body: f.body,
+        sections: JSON.parse(f.sections),
+        rawContent: f.rawContent,
+    }));
+}
+/**
+ * Check if the native parser is available.
+ */
+export function isNativeParserAvailable() {
+    return loadNative() !== null;
+}
+/**
+ * Native-backed directory tree scan of a .gsd/ directory.
+ * Returns a flat list of all entries, or null if native module unavailable.
+ */
+export function nativeScanGsdTree(directory) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    return native.scanGsdTree(directory);
+}
+/**
+ * Native-backed JSONL tail parser. Reads the last `maxBytes` of a JSONL file
+ * and parses up to `maxEntries` entries with constant memory usage.
+ * Returns null if native module unavailable.
+ */
+export function nativeParseJsonlTail(filePath, maxBytes, maxEntries) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    const result = native.parseJsonlTail(filePath, maxBytes, maxEntries);
+    return {
+        entries: JSON.parse(result.entries),
+        count: result.count,
+        truncated: result.truncated,
+    };
+}
+/**
+ * Native-backed plan file parser.
+ * Returns structured plan data or null if native module unavailable.
+ */
+export function nativeParsePlanFile(content) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    return native.parsePlanFile(content);
+}
+/**
+ * Native-backed summary file parser.
+ * Returns structured summary data or null if native module unavailable.
+ */
+export function nativeParseSummaryFile(content) {
+    const native = loadNative();
+    if (!native)
+        return null;
+    return native.parseSummaryFile(content);
+}

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

@@ -0,0 +1,58 @@
+// GSD Extension — Desktop Notification Helper
+// Cross-platform desktop notifications for auto-mode events.
+import { execFileSync } from "node:child_process";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+/**
+ * Send a native desktop notification. Non-blocking, non-fatal.
+ * macOS: osascript, Linux: notify-send, Windows: skipped.
+ */
+export function sendDesktopNotification(title, message, level = "info", kind = "complete") {
+    if (!shouldSendDesktopNotification(kind))
+        return;
+    try {
+        const command = buildDesktopNotificationCommand(process.platform, title, message, level);
+        if (!command)
+            return;
+        execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
+    }
+    catch {
+        // Non-fatal — desktop notifications are best-effort
+    }
+}
+export function shouldSendDesktopNotification(kind, preferences = loadEffectiveGSDPreferences()?.preferences.notifications) {
+    if (preferences?.enabled === false)
+        return false;
+    switch (kind) {
+        case "error":
+            return preferences?.on_error ?? true;
+        case "budget":
+            return preferences?.on_budget ?? true;
+        case "milestone":
+            return preferences?.on_milestone ?? true;
+        case "attention":
+            return preferences?.on_attention ?? true;
+        case "complete":
+        default:
+            return preferences?.on_complete ?? true;
+    }
+}
+export function buildDesktopNotificationCommand(platform, title, message, level = "info") {
+    const normalizedTitle = normalizeNotificationText(title);
+    const normalizedMessage = normalizeNotificationText(message);
+    if (platform === "darwin") {
+        const sound = level === "error" ? 'sound name "Basso"' : 'sound name "Glass"';
+        const script = `display notification "${escapeAppleScript(normalizedMessage)}" with title "${escapeAppleScript(normalizedTitle)}" ${sound}`;
+        return { file: "osascript", args: ["-e", script] };
+    }
+    if (platform === "linux") {
+        const urgency = level === "error" ? "critical" : level === "warning" ? "normal" : "low";
+        return { file: "notify-send", args: ["-u", urgency, normalizedTitle, normalizedMessage] };
+    }
+    return null;
+}
+function normalizeNotificationText(s) {
+    return s.replace(/\r?\n/g, " ").trim();
+}
+function escapeAppleScript(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}

package/dist/resources/extensions/gsd/observability-validator.js

@@ -0,0 +1,398 @@
+import { loadFile } from "./files.js";
+import { resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveTaskFiles } from "./paths.js";
+function getSection(content, heading, level = 2) {
+    const prefix = "#".repeat(level) + " ";
+    const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`^${prefix}${escaped}\\s*$`, "m");
+    const match = regex.exec(content);
+    if (!match)
+        return null;
+    const start = match.index + match[0].length;
+    const rest = content.slice(start);
+    const nextHeading = rest.match(new RegExp(`^#{1,${level}} `, "m"));
+    const end = nextHeading ? nextHeading.index : rest.length;
+    return rest.slice(0, end).trim();
+}
+function getFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("---"))
+        return null;
+    const afterFirst = trimmed.indexOf("\n");
+    if (afterFirst === -1)
+        return null;
+    const rest = trimmed.slice(afterFirst + 1);
+    const endIdx = rest.indexOf("\n---");
+    if (endIdx === -1)
+        return null;
+    return rest.slice(0, endIdx);
+}
+function hasFrontmatterKey(content, key) {
+    const fm = getFrontmatter(content);
+    if (!fm)
+        return false;
+    return new RegExp(`^${key}:`, "m").test(fm);
+}
+function normalizeMeaningfulLines(text) {
+    return text
+        .split("\n")
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .filter(line => !line.startsWith("<!--"))
+        .filter(line => !line.endsWith("-->"))
+        .filter(line => !/^[-*]\s*\{\{.+\}\}$/.test(line))
+        .filter(line => !/^\{\{.+\}\}$/.test(line));
+}
+function sectionLooksPlaceholderOnly(text) {
+    if (!text)
+        return true;
+    const lines = normalizeMeaningfulLines(text)
+        .map(line => line.replace(/^[-*]\s+/, "").trim())
+        .filter(line => line.length > 0);
+    if (lines.length === 0)
+        return true;
+    return lines.every(line => {
+        const lower = line.toLowerCase();
+        return lower === "none" ||
+            lower.endsWith(": none") ||
+            lower.includes("{{") ||
+            lower.includes("}}") ||
+            lower.startsWith("required for non-trivial") ||
+            lower.startsWith("describe how a future agent") ||
+            lower.startsWith("prefer:") ||
+            lower.startsWith("keep this section concise");
+    });
+}
+function textSuggestsObservabilityRelevant(content) {
+    const lower = content.toLowerCase();
+    const needles = [
+        " api", "route", "server", "worker", "queue", "job", "sync", "import",
+        "webhook", "auth", "db", "database", "migration", "cache", "background",
+        "polling", "realtime", "socket", "stateful", "integration", "ui", "form",
+        "submit", "status", "service", "pipeline", "health endpoint", "error path"
+    ];
+    return needles.some(needle => lower.includes(needle));
+}
+function verificationMentionsDiagnostics(section) {
+    if (!section)
+        return false;
+    const lower = section.toLowerCase();
+    const needles = [
+        "error", "failure", "diagnostic", "status", "health", "inspect", "log",
+        "network", "console", "retry", "last error", "correlation", "readiness"
+    ];
+    return needles.some(needle => lower.includes(needle));
+}
+export function validateSlicePlanContent(file, content) {
+    const issues = [];
+    // ── Plan quality rules (always run, not gated by runtime relevance) ──
+    const tasksSection = getSection(content, "Tasks", 2);
+    if (tasksSection) {
+        const lines = tasksSection.split("\n");
+        const taskLinePattern = /^- \[[ x]\] \*\*T\d+:/;
+        const taskLineIndices = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (taskLinePattern.test(lines[i]))
+                taskLineIndices.push(i);
+        }
+        for (let t = 0; t < taskLineIndices.length; t++) {
+            const start = taskLineIndices[t];
+            const end = t + 1 < taskLineIndices.length ? taskLineIndices[t + 1] : lines.length;
+            // Check lines between this task header and the next (or section end)
+            const bodyLines = lines.slice(start + 1, end);
+            const meaningful = bodyLines.filter(l => l.trim().length > 0);
+            if (meaningful.length === 0) {
+                issues.push({
+                    severity: "warning",
+                    scope: "slice-plan",
+                    file,
+                    ruleId: "empty_task_entry",
+                    message: "Inline task entry has no description content beneath the checkbox line.",
+                    suggestion: "Add at least a Why/Files/Do/Verify summary so the task is self-describing.",
+                });
+            }
+        }
+    }
+    // ── Observability rules (gated by runtime relevance) ──
+    const relevant = textSuggestsObservabilityRelevant(content);
+    if (!relevant)
+        return issues;
+    const obs = getSection(content, "Observability / Diagnostics", 2);
+    const verification = getSection(content, "Verification", 2);
+    if (!obs) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "missing_observability_section",
+            message: "Slice plan appears non-trivial but is missing `## Observability / Diagnostics`.",
+            suggestion: "Add runtime signals, inspection surfaces, failure visibility, and redaction constraints.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(obs)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "observability_section_placeholder_only",
+            message: "Slice plan has `## Observability / Diagnostics` but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete signals and inspection surfaces a future agent should trust.",
+        });
+    }
+    if (!verificationMentionsDiagnostics(verification)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-plan",
+            file,
+            ruleId: "verification_missing_diagnostic_check",
+            message: "Slice verification does not appear to include any diagnostic or failure-path check.",
+            suggestion: "Add at least one verification step for inspectable failure state, structured error output, status surface, or equivalent.",
+        });
+    }
+    return issues;
+}
+export function validateTaskPlanContent(file, content) {
+    const issues = [];
+    // ── Plan quality rules (always run, not gated by runtime relevance) ──
+    // Rule: empty or missing Steps section
+    const stepsSection = getSection(content, "Steps", 2);
+    if (stepsSection === null || sectionLooksPlaceholderOnly(stepsSection)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "empty_steps_section",
+            message: "Task plan has an empty or missing `## Steps` section.",
+            suggestion: "Add concrete numbered implementation steps so execution has a clear sequence.",
+        });
+    }
+    // Rule: placeholder-only Verification section
+    const verificationSection = getSection(content, "Verification", 2);
+    if (verificationSection !== null && sectionLooksPlaceholderOnly(verificationSection)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "placeholder_verification",
+            message: "Task plan has `## Verification` but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete verification commands, test runs, or observable checks.",
+        });
+    }
+    // Rule: scope estimate thresholds
+    const fm = getFrontmatter(content);
+    if (fm) {
+        const stepsMatch = fm.match(/^estimated_steps:\s*(\d+)/m);
+        const filesMatch = fm.match(/^estimated_files:\s*(\d+)/m);
+        if (stepsMatch) {
+            const estimatedSteps = parseInt(stepsMatch[1], 10);
+            if (estimatedSteps >= 10) {
+                issues.push({
+                    severity: "warning",
+                    scope: "task-plan",
+                    file,
+                    ruleId: "scope_estimate_steps_high",
+                    message: `Task plan estimates ${estimatedSteps} steps (threshold: 10). Consider splitting into smaller tasks.`,
+                    suggestion: "Break the task into sub-tasks or reduce scope so each task stays focused and completable in one pass.",
+                });
+            }
+        }
+        if (filesMatch) {
+            const estimatedFiles = parseInt(filesMatch[1], 10);
+            if (estimatedFiles >= 12) {
+                issues.push({
+                    severity: "warning",
+                    scope: "task-plan",
+                    file,
+                    ruleId: "scope_estimate_files_high",
+                    message: `Task plan estimates ${estimatedFiles} files (threshold: 12). Consider splitting into smaller tasks.`,
+                    suggestion: "Break the task into sub-tasks or reduce scope to keep the change footprint manageable.",
+                });
+            }
+        }
+    }
+    // ── Observability rules (gated by runtime relevance) ──
+    const relevant = textSuggestsObservabilityRelevant(content);
+    if (!relevant)
+        return issues;
+    const obs = getSection(content, "Observability Impact", 2);
+    if (!obs) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "missing_observability_impact",
+            message: "Task plan appears runtime-relevant but is missing `## Observability Impact`.",
+            suggestion: "Explain what signals change, how a future agent inspects this task, and what failure state becomes visible.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(obs)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-plan",
+            file,
+            ruleId: "observability_impact_placeholder_only",
+            message: "Task plan has `## Observability Impact` but it still looks empty or placeholder-only.",
+            suggestion: "Fill in concrete inspection surfaces or explicitly justify why observability is not applicable.",
+        });
+    }
+    return issues;
+}
+export function validateTaskSummaryContent(file, content) {
+    const issues = [];
+    if (!hasFrontmatterKey(content, "observability_surfaces")) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "missing_observability_frontmatter",
+            message: "Task summary is missing `observability_surfaces` in frontmatter.",
+            suggestion: "List the durable status/log/error surfaces a future agent should use.",
+        });
+    }
+    const diagnostics = getSection(content, "Diagnostics", 2);
+    if (!diagnostics) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "missing_diagnostics_section",
+            message: "Task summary is missing `## Diagnostics`.",
+            suggestion: "Document how to inspect what this task built later.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(diagnostics)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "diagnostics_placeholder_only",
+            message: "Task summary diagnostics section still looks like placeholder text.",
+            suggestion: "Replace placeholders with concrete commands, endpoints, logs, error shapes, or failure artifacts.",
+        });
+    }
+    const evidence = getSection(content, "Verification Evidence", 2);
+    if (!evidence) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "evidence_block_missing",
+            message: "Task summary is missing `## Verification Evidence`.",
+            suggestion: "Add a verification evidence table showing gate check results (command, exit code, verdict, duration).",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(evidence)) {
+        issues.push({
+            severity: "warning",
+            scope: "task-summary",
+            file,
+            ruleId: "evidence_block_placeholder",
+            message: "Task summary verification evidence section still looks like placeholder text.",
+            suggestion: "Replace placeholders with actual gate results or note that no verification commands were discovered.",
+        });
+    }
+    return issues;
+}
+export function validateSliceSummaryContent(file, content) {
+    const issues = [];
+    if (!hasFrontmatterKey(content, "observability_surfaces")) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "missing_observability_frontmatter",
+            message: "Slice summary is missing `observability_surfaces` in frontmatter.",
+            suggestion: "List the authoritative diagnostics and durable inspection surfaces for this slice.",
+        });
+    }
+    const diagnostics = getSection(content, "Authoritative diagnostics", 3);
+    if (!diagnostics) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "missing_authoritative_diagnostics",
+            message: "Slice summary is missing `### Authoritative diagnostics` in Forward Intelligence.",
+            suggestion: "Tell future agents where to look first and why that signal is trustworthy.",
+        });
+    }
+    else if (sectionLooksPlaceholderOnly(diagnostics)) {
+        issues.push({
+            severity: "warning",
+            scope: "slice-summary",
+            file,
+            ruleId: "authoritative_diagnostics_placeholder_only",
+            message: "Slice summary includes authoritative diagnostics but it still looks like placeholder text.",
+            suggestion: "Replace placeholders with the real first-stop diagnostic surface for this slice.",
+        });
+    }
+    return issues;
+}
+export async function validatePlanBoundary(basePath, milestoneId, sliceId) {
+    const issues = [];
+    const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+    if (slicePlan) {
+        const content = await loadFile(slicePlan);
+        if (content)
+            issues.push(...validateSlicePlanContent(slicePlan, content));
+    }
+    const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    const taskPlans = tasksDir ? resolveTaskFiles(tasksDir, "PLAN") : [];
+    for (const file of taskPlans) {
+        const taskId = file.split("-")[0];
+        const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+        if (!taskPlan)
+            continue;
+        const content = await loadFile(taskPlan);
+        if (content)
+            issues.push(...validateTaskPlanContent(taskPlan, content));
+    }
+    return issues;
+}
+export async function validateExecuteBoundary(basePath, milestoneId, sliceId, taskId) {
+    const issues = [];
+    const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+    if (slicePlan) {
+        const content = await loadFile(slicePlan);
+        if (content)
+            issues.push(...validateSlicePlanContent(slicePlan, content));
+    }
+    const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+    if (taskPlan) {
+        const content = await loadFile(taskPlan);
+        if (content)
+            issues.push(...validateTaskPlanContent(taskPlan, content));
+    }
+    return issues;
+}
+export async function validateCompleteBoundary(basePath, milestoneId, sliceId) {
+    const issues = [];
+    const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    const taskSummaries = tasksDir ? resolveTaskFiles(tasksDir, "SUMMARY") : [];
+    for (const file of taskSummaries) {
+        const taskId = file.split("-")[0];
+        const taskSummary = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY");
+        if (!taskSummary)
+            continue;
+        const content = await loadFile(taskSummary);
+        if (content)
+            issues.push(...validateTaskSummaryContent(taskSummary, content));
+    }
+    const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+    if (sliceSummary) {
+        const content = await loadFile(sliceSummary);
+        if (content)
+            issues.push(...validateSliceSummaryContent(sliceSummary, content));
+    }
+    return issues;
+}
+export function formatValidationIssues(issues, limit = 4) {
+    if (issues.length === 0)
+        return "";
+    const lines = issues.slice(0, limit).map(issue => {
+        const fileName = issue.file.split("/").pop() || issue.file;
+        return `- ${fileName}: ${issue.message}`;
+    });
+    if (issues.length > limit)
+        lines.push(`- ...and ${issues.length - limit} more`);
+    return lines.join("\n");
+}