@entelligentsia/forgecli 1.0.25 → 1.0.36

package/dist/extensions/forgecli/status-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-command.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/status-command.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-error-remediation.d.ts

@@ -0,0 +1,65 @@
+export interface RemediationResult {
+    /** One-line user-facing hint explaining the error and the fix. */
+    hint: string;
+    /** Optional copy-pasteable store-cli command. Empty string if N/A. */
+    command: string;
+}
+/**
+ * Infer the entity type from an entity name/ID string.
+ * Returns "task" as default if no match.
+ */
+export declare function inferEntityType(entity: string): string;
+/** Parsed breakdown of a validation error string. */
+interface ParsedError {
+    field: string;
+    errorKind: "enum" | "required" | "undeclared" | "type" | "pattern" | "datetime" | "length" | "other";
+    observed?: string;
+    enumValues?: string[];
+}
+/**
+ * Parse a single validation error line from validate.js / store-cli.
+ *
+ * Examples:
+ *   'status: value "verified" not in [reported, triaged, in-progress, fixed]'
+ *   'taskId: missing required field'
+ *   'xyz: undeclared field'
+ *   'sprintId: expected string, got number'
+ *   'title: value length 0 is below minLength 1'
+ *   'createdAt: value "today" is not a valid date-time'
+ *   'prefix: value "AB" does not match pattern ^[A-Z]+-[A-Z]$'
+ */
+export declare function parseValidationError(line: string): ParsedError;
+/**
+ * Given a single validation error line (from validate.js or store-cli),
+ * return a user-facing remediation hint and optional copy-pasteable command.
+ *
+ * @param errorLine  A single error line from validate.js / store-cli output.
+ * @param entityType  The entity type (task, sprint, bug, feature, event).
+ * @param entityId   The entity ID (e.g. "FORGE-S18-T02") — used for commands.
+ * @returns          RemediationResult with hint and command.
+ */
+export declare function remediateError(errorLine: string, entityType: string, entityId: string): RemediationResult;
+/**
+ * Parse a multi-line validation output (e.g. from store-cli validate or
+ * validate-store --dry-run) into individual error lines and return
+ * remediation for each.
+ *
+ * @param output    Raw multi-line output from validation tool.
+ * @param entityType Override entity type (inferred from output if not provided).
+ * @returns         Array of { errorLine, remediation } objects.
+ */
+export declare function remediateValidationOutput(output: string, entityType?: string): Array<{
+    errorLine: string;
+    remediation: RemediationResult;
+}>;
+/**
+ * Format a block message for a write-guard violation, appending remediation hints.
+ * Used by hook-dispatcher.ts for store-cli intercept blocks.
+ *
+ * @param rawReason  The raw reason string from validateStoreCLIPayload or checkWriteGuard.
+ * @param entityType  The entity type if known.
+ * @param entityId   The entity ID if known.
+ * @returns          Enhanced reason string with remediation hints appended.
+ */
+export declare function enhanceBlockMessage(rawReason: string, entityType?: string, entityId?: string): string;
+export {};

package/dist/extensions/forgecli/store-error-remediation.js

@@ -0,0 +1,307 @@
+// Store-error remediation — forge-cli#24
+// Moved from lib/store-error-remediation.ts to root by FORGE-S25-T22 (S-7: single-file lib/ dir).
+//
+// Shared remediation-hint surface for store validation errors.
+// Consumed by:
+//   - health-check.ts (per-error row in store-integrity output)
+//   - hooks/write-guard.ts (block-message body for schema violations)
+//   - hook-dispatcher.ts (store-cli intercept block messages)
+//   - store-validator.ts (structured result for hook callers)
+//
+// Error sources:
+//   1. validate.js (in-process via write-guard) — produces error strings like:
+//        "status: value "verified" not in [reported, triaged, in-progress, fixed]"
+//        "taskId: missing required field"
+//        "xyz: undeclared field"
+//   2. store-cli.cjs validate (subprocess via store-validator.ts) — same format,
+//      piped through stderr.
+//   3. validate-store.cjs --dry-run (subprocess via health-check.ts) — lines like:
+//        "ERROR  FORGE-S18-T02: status: value "verified" not in [reported, triaged, ...]"
+//        "WARN   FORGE-S18-T02: ..."
+//
+// This module parses those formats and returns a one-line user-facing hint
+// plus an optional copy-pasteable store-cli command.
+// ── Entity-type inference from entity name / ID ────────────────────────────────
+/** Map entity type to the corresponding schema's status enum values. */
+const STATUS_ENUMS = {
+    task: [
+        "draft",
+        "planned",
+        "plan-approved",
+        "implementing",
+        "implemented",
+        "review-approved",
+        "approved",
+        "committed",
+        "plan-revision-required",
+        "code-revision-required",
+        "blocked",
+        "escalated",
+        "abandoned",
+    ],
+    sprint: ["planning", "active", "completed", "retrospective-done", "partially-completed", "blocked", "abandoned"],
+    bug: ["reported", "triaged", "in-progress", "fixed"],
+    feature: ["proposed", "accepted", "in-progress", "delivered", "declined"],
+    event: [], // no status field
+};
+/** Known entity types that support write via store-cli. */
+const ENTITY_TYPES = new Set(["task", "sprint", "bug", "feature", "event"]);
+/**
+ * Infer the entity type from an entity name/ID string.
+ * Returns "task" as default if no match.
+ */
+export function inferEntityType(entity) {
+    const lower = entity.toLowerCase();
+    // Bug patterns: BUG-015, FORGE-BUG-015, bug-031
+    if (/\bbug/i.test(entity))
+        return "bug";
+    // Sprint patterns: S18 (standalone), sprint-01 — but NOT inside task IDs like FORGE-S18-T02
+    if (/^[A-Z]+-S\d+$/i.test(entity) || /\bsprint/i.test(entity))
+        return "sprint";
+    // Feature patterns: FORGE-F01
+    if (/\bf\d+\b/i.test(entity) || lower.includes("feat"))
+        return "feature";
+    // Event patterns
+    if (lower.includes("event"))
+        return "event";
+    // Task IDs: FORGE-S18-T02, PROJECT-T01
+    if (/\bt\d+\b/i.test(entity))
+        return "task";
+    // Default
+    return "task";
+}
+const STATUS_REMEDIATION = {
+    hint: "Set status to one of the legal values for this entity type.",
+    command: (entityType, entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <legal-value>`,
+};
+const REQUIRED_FIELD_REMEDIATION = {
+    hint: "Add the missing field with a valid value. Use the template command to see the canonical shape.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+};
+const UNDECLARED_FIELD_REMEDIATION = {
+    hint: "Remove the undeclared field, or check the schema for the correct property name.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const TYPE_MISMATCH_REMEDIATION = {
+    hint: "Use the correct type for this field. Use the describe command to see the expected type.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const PATTERN_REMEDIATION = {
+    hint: "The value must match the expected pattern (e.g. a date-time or ID format).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const DATE_TIME_REMEDIATION = {
+    hint: "Use an ISO 8601 date-time string (e.g. 2026-05-21T12:00:00Z).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const LENGTH_REMEDIATION = {
+    hint: "Adjust the value length to satisfy the schema constraint.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+/**
+ * Parse a single validation error line from validate.js / store-cli.
+ *
+ * Examples:
+ *   'status: value "verified" not in [reported, triaged, in-progress, fixed]'
+ *   'taskId: missing required field'
+ *   'xyz: undeclared field'
+ *   'sprintId: expected string, got number'
+ *   'title: value length 0 is below minLength 1'
+ *   'createdAt: value "today" is not a valid date-time'
+ *   'prefix: value "AB" does not match pattern ^[A-Z]+-[A-Z]$'
+ */
+export function parseValidationError(line) {
+    // Enum violation: 'field: value "X" not in [a, b, c]'
+    const enumMatch = line.match(/^(\w+):\s+value\s+"([^"]+)"\s+not in \[([^\]]+)\]/);
+    if (enumMatch) {
+        return {
+            field: enumMatch[1],
+            errorKind: "enum",
+            observed: enumMatch[2],
+            enumValues: enumMatch[3].split(",").map((s) => s.trim()),
+        };
+    }
+    // Required field: 'field: missing required field'
+    if (/\bmissing required field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "required" };
+    }
+    // Undeclared field: 'xyz: undeclared field'
+    if (/\bundeclared field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "undeclared" };
+    }
+    // Type mismatch: 'field: expected string, got number'
+    const typeMatch = line.match(/^(\w+):\s+expected\s+\S+,?\s+got\s+\S+/);
+    if (typeMatch) {
+        return { field: typeMatch[1], errorKind: "type" };
+    }
+    // Date-time format: 'field: value "..." is not a valid date-time'
+    if (/\bis not a valid date-time\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "datetime" };
+    }
+    // Pattern mismatch: 'field: value "..." does not match pattern ...'
+    if (/\bdoes not match pattern\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "pattern" };
+    }
+    // Length violations
+    if (/\blength\b.*\b(exceeds|below)\b/.test(line) || /\b(exceeds|below)\b.*\blength\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "length" };
+    }
+    // Generic: capture leading field name if present
+    const genericMatch = line.match(/^(\w+):/);
+    return { field: genericMatch?.[1] ?? "unknown", errorKind: "other" };
+}
+// ── Public API ──────────────────────────────────────────────────────────────────
+/**
+ * Given a single validation error line (from validate.js or store-cli),
+ * return a user-facing remediation hint and optional copy-pasteable command.
+ *
+ * @param errorLine  A single error line from validate.js / store-cli output.
+ * @param entityType  The entity type (task, sprint, bug, feature, event).
+ * @param entityId   The entity ID (e.g. "FORGE-S18-T02") — used for commands.
+ * @returns          RemediationResult with hint and command.
+ */
+export function remediateError(errorLine, entityType, entityId) {
+    const parsed = parseValidationError(errorLine);
+    switch (parsed.errorKind) {
+        case "enum": {
+            const legalValues = STATUS_ENUMS[entityType] ?? parsed.enumValues ?? [];
+            const isStatusField = parsed.field === "status" || parsed.field.toLowerCase().includes("status");
+            if (isStatusField && legalValues.length > 0) {
+                return {
+                    hint: `"${parsed.observed}" is not a legal ${entityType} status. Legal values: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <${legalValues.join("|")}>`,
+                };
+            }
+            if (legalValues.length > 0) {
+                return {
+                    hint: `Invalid value for "${parsed.field}". Allowed: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+                };
+            }
+            return {
+                hint: STATUS_REMEDIATION.hint,
+                command: STATUS_REMEDIATION.command(entityType, entityId),
+            };
+        }
+        case "required":
+            return {
+                hint: REQUIRED_FIELD_REMEDIATION.hint,
+                command: REQUIRED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "undeclared":
+            return {
+                hint: UNDECLARED_FIELD_REMEDIATION.hint,
+                command: UNDECLARED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "type":
+            return {
+                hint: TYPE_MISMATCH_REMEDIATION.hint,
+                command: TYPE_MISMATCH_REMEDIATION.command(entityType, entityId),
+            };
+        case "datetime":
+            return {
+                hint: DATE_TIME_REMEDIATION.hint,
+                command: DATE_TIME_REMEDIATION.command(entityType, entityId),
+            };
+        case "pattern":
+            return {
+                hint: PATTERN_REMEDIATION.hint,
+                command: PATTERN_REMEDIATION.command(entityType, entityId),
+            };
+        case "length":
+            return {
+                hint: LENGTH_REMEDIATION.hint,
+                command: LENGTH_REMEDIATION.command(entityType, entityId),
+            };
+        case "other":
+        default:
+            return {
+                hint: "Check the schema for the expected shape.",
+                command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+            };
+    }
+}
+/**
+ * Parse a multi-line validation output (e.g. from store-cli validate or
+ * validate-store --dry-run) into individual error lines and return
+ * remediation for each.
+ *
+ * @param output    Raw multi-line output from validation tool.
+ * @param entityType Override entity type (inferred from output if not provided).
+ * @returns         Array of { errorLine, remediation } objects.
+ */
+export function remediateValidationOutput(output, entityType) {
+    const lines = output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    const results = [];
+    for (const line of lines) {
+        // Strip "ERROR" / "WARN" prefix from validate-store --dry-run output
+        const cleaned = line.replace(/^(ERROR|WARN)\s+/, "");
+        if (!cleaned)
+            continue;
+        // Extract entity ID from lines like "FORGE-S18-T02: status: ..."
+        const entityIdMatch = cleaned.match(/^([A-Z]+-S?\d+-T?\d+|[A-Z]+-BUG-\d+|[A-Z]+-F\d+):/);
+        const entityId = entityIdMatch?.[1] ?? "unknown";
+        // If entity type not overridden, try to infer
+        const inferredType = entityType ?? inferEntityType(entityId);
+        // Skip non-error lines (hint lines from validate.js, blank lines, etc.)
+        if (cleaned.startsWith("(") || cleaned.startsWith("hint:") || cleaned.startsWith("#")) {
+            continue;
+        }
+        // Skip lines that are just an entity name without an error field
+        // (the real error is on the same line after the entity prefix)
+        const errorPart = entityIdMatch ? cleaned.slice(entityIdMatch[0].length).trim() : cleaned;
+        if (!errorPart || errorPart.length < 3)
+            continue;
+        results.push({
+            errorLine: cleaned,
+            remediation: remediateError(errorPart, inferredType, entityId),
+        });
+    }
+    return results;
+}
+/**
+ * Format a block message for a write-guard violation, appending remediation hints.
+ * Used by hook-dispatcher.ts for store-cli intercept blocks.
+ *
+ * @param rawReason  The raw reason string from validateStoreCLIPayload or checkWriteGuard.
+ * @param entityType  The entity type if known.
+ * @param entityId   The entity ID if known.
+ * @returns          Enhanced reason string with remediation hints appended.
+ */
+export function enhanceBlockMessage(rawReason, entityType, entityId) {
+    // Parse the raw reason into lines and try to add remediation to each error line.
+    const lines = rawReason.split("\n");
+    const enhanced = [];
+    for (const line of lines) {
+        // Strip leading list markers and bullet points
+        const stripped = line.replace(/^\s*[-•]\s*/, "").trim();
+        // Check if this line contains a recognizable validation error pattern
+        const parsed = parseValidationError(stripped);
+        // Also match lines that contain validation error patterns not caught by parseValidationError
+        const hasKnownError = parsed.errorKind !== "other" ||
+            /\bmissing required\b|\bnot in \[|\bundeclared\b|\bexpected\b.*\bgot\b/.test(stripped);
+        if (hasKnownError) {
+            const type = entityType ?? "task";
+            const id = entityId ?? "unknown";
+            const remediation = remediateError(stripped, type, id);
+            enhanced.push(line);
+            enhanced.push(`  💡 ${remediation.hint}`);
+            if (remediation.command) {
+                enhanced.push(`  → ${remediation.command}`);
+            }
+        }
+        else {
+            enhanced.push(line);
+        }
+    }
+    return enhanced.join("\n");
+}
+//# sourceMappingURL=store-error-remediation.js.map

package/dist/extensions/forgecli/store-error-remediation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-error-remediation.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-error-remediation.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-query.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface StoreQueryResult {
+    stdout: string;
+    ok: boolean;
+    errorMessage?: string;
+}
+/**
+ * Run store-cli in query or nlp mode.
+ * - Args starting with "--" → query branch: `store-cli query ...flags`
+ * - Otherwise → nlp branch: `store-cli nlp "<args>"`
+ *
+ * Returns raw stdout for display. Does NOT JSON-parse — caller renders as-is.
+ * Exported so orchestrators can call directly without going through sendUserMessage.
+ */
+export declare function runStoreQuery(args: string, forgeRoot: string, cwd: string): Promise<StoreQueryResult>;
+/**
+ * Register /forge:store-query.
+ * forgeRoot is nullable — null means we're outside a Forge project.
+ */
+export declare function registerStoreQuery(pi: ExtensionAPI, opts: {
+    forgeRoot: string | null;
+}): void;

package/dist/extensions/forgecli/store-query.js

@@ -0,0 +1,107 @@
+// store-query.ts — native atomic handler for /forge:store-query (FORGE-S23-T10)
+//
+// Dispatches to store-cli query (flags path) or store-cli nlp (intent path)
+// and emits raw stdout via ctx.ui.notify.
+//
+// Archetype: Atomic (no LLM in loop — pack-04 §Atomic).
+// Iron Laws:
+//   IL1 — new code lives in forge-cli/ only
+//   IL6 — no shell-string interpolation (argv-array throughout)
+//   IL7 — silent continuation past failures is never acceptable
+import { execFile } from "node:child_process";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { resolveToolDir } from "./store-resolver.js";
+const execFileAsync = promisify(execFile);
+// ── Usage message ─────────────────────────────────────────────────────────────
+const USAGE = `Usage: /forge:search <intent or flags>
+
+Examples:
+  /forge:search open bugs in S12
+  /forge:search FORGE-BUG-047
+  /forge:search --sprint FORGE-S12 --status in-progress
+  /forge:search --keyword auth
+  /forge:search schema`;
+/**
+ * Run store-cli in query or nlp mode.
+ * - Args starting with "--" → query branch: `store-cli query ...flags`
+ * - Otherwise → nlp branch: `store-cli nlp "<args>"`
+ *
+ * Returns raw stdout for display. Does NOT JSON-parse — caller renders as-is.
+ * Exported so orchestrators can call directly without going through sendUserMessage.
+ */
+export async function runStoreQuery(args, forgeRoot, cwd) {
+    const trimmed = args.trim();
+    const toolDir = resolveToolDir(forgeRoot);
+    const storeCliPath = path.join(toolDir, "store-cli.cjs");
+    let argv;
+    let timeoutMs;
+    if (trimmed.startsWith("--")) {
+        // Query branch: pass flags verbatim as argv tokens
+        const tokens = trimmed.split(/\s+/).filter(Boolean);
+        argv = ["query", ...tokens];
+        timeoutMs = 10_000;
+    }
+    else {
+        // NLP branch: pass entire trimmed arg string as single argument
+        argv = ["nlp", trimmed];
+        timeoutMs = 30_000;
+    }
+    try {
+        const result = await execFileAsync("node", [storeCliPath, ...argv], {
+            cwd,
+            encoding: "utf8",
+            timeout: timeoutMs,
+        });
+        return { stdout: result.stdout, ok: true };
+    }
+    catch (err) {
+        const e = err;
+        // execFile rejects on non-zero exit; stdout may still contain partial results
+        const stderr = e.stderr || e.message || String(err);
+        const stdout = e.stdout || "";
+        return {
+            stdout,
+            ok: false,
+            errorMessage: stderr.slice(0, 500),
+        };
+    }
+}
+// ── Register ─────────────────────────────────────────────────────────────────
+/**
+ * Register /forge:store-query.
+ * forgeRoot is nullable — null means we're outside a Forge project.
+ */
+export function registerStoreQuery(pi, opts) {
+    pi.registerCommand("forge:search", {
+        description: "Query the Forge store by natural language or exact flags. " +
+            "Use flags (--sprint, --task, --keyword) for exact queries; " +
+            "use plain text for NLP intent queries.",
+        async handler(args, ctx) {
+            const cwd = process.cwd();
+            // Outside-project guard
+            if (!opts.forgeRoot) {
+                ctx.ui.notify("× forge:search — not inside a Forge project. Run /forge:init first.", "error");
+                return;
+            }
+            const trimmed = args.trim();
+            if (!trimmed) {
+                ctx.ui.notify(USAGE, "info");
+                return;
+            }
+            ctx.ui.setStatus?.("forge:search", "Querying store…");
+            const result = await runStoreQuery(trimmed, opts.forgeRoot, cwd);
+            ctx.ui.setStatus?.("forge:search", undefined);
+            if (!result.ok && result.errorMessage) {
+                ctx.ui.notify(`× forge:search — ${result.errorMessage}`, "error");
+                // Still show partial stdout if available
+                if (result.stdout.trim()) {
+                    ctx.ui.notify(result.stdout.trim(), "info");
+                }
+                return;
+            }
+            ctx.ui.notify(result.stdout.trim() || "(no results)", "info");
+        },
+    });
+}
+//# sourceMappingURL=store-query.js.map

package/dist/extensions/forgecli/store-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-query.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-query.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-repair.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export interface ParsedStoreRepairArgs {
+    dryRun: boolean;
+    seed: string;
+    sourceLabel: string;
+}
+export declare function parseStoreRepairArgs(rawArgs: string, cwd: string): ParsedStoreRepairArgs;
+export interface ComposeStoreRepairKickoffOpts {
+    commandMd: string;
+    parsed: ParsedStoreRepairArgs;
+}
+export declare function composeStoreRepairKickoff(opts: ComposeStoreRepairKickoffOpts): string;
+export interface RegisterStoreRepairOptions {
+    forgeRoot: string | null;
+    cwd?: string;
+}
+export declare function registerStoreRepair(pi: ExtensionAPI, options: RegisterStoreRepairOptions): void;