@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/extensions/forgecli/health-check.js

@@ -6,13 +6,23 @@
 // function directly. sendUserMessage is NOT used here (skill §198 pitfall).
 //
 // Implements a programmatic subset of the checks listed in
-// forge/forge/commands/health.md (config-completeness + KB freshness +
-// store integrity). Full check output is returned as structured data;
-// the caller formats it for display.
+// forge/forge/commands/health.md. As of FORGE-S23-T07, covers 6/15 checks:
+//   1. Config completeness
+//   2. KB freshness
+//   3. Stale docs (NEW — architecture/*.md files older than STALE_DOCS_THRESHOLD_MS)
+//   8. Store integrity
+//   9. Modified generated files (NEW — generation-manifest.cjs list --modified)
+//  15. Plugin integrity (NEW — native TS hash check against forgeRoot/integrity.json)
+//
+// Full check output is returned as structured data; the caller formats it for
+// display. See forge-cli/doc/health-parity-audit.md for the full parity table.
 import { execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+// ── Constants ──────────────────────────────────────────────────────────────
+/** Architecture docs older than this are flagged as stale (90 days). */
+const STALE_DOCS_THRESHOLD_MS = 90 * 24 * 60 * 60 * 1000;
 // ── Required config fields ─────────────────────────────────────────────────
 const REQUIRED_TOP_LEVEL = ["version", "project", "stack", "commands", "paths"];
 const REQUIRED_PROJECT = ["name", "prefix"];
@@ -24,8 +34,9 @@ const REQUIRED_PATHS = ["engineering", "store", "workflows", "commands", "templa
  *
  * @param cwd - project working directory (where .forge/ lives)
  * @param bundleRoot - path to dist/forge-payload/ (contains tools/)
+ * @param forgeRoot - optional path to the installed Forge plugin root (for plugin integrity check)
  */
-export async function runHealthCheck(cwd, bundleRoot) {
+export async function runHealthCheck(cwd, bundleRoot, forgeRoot) {
     const gaps = [];
     // 1. Config-completeness check
     const configPath = path.join(cwd, ".forge", "config.json");
@@ -142,6 +153,17 @@ export async function runHealthCheck(cwd, bundleRoot) {
             });
         }
     }
+    // 4. Stale docs check — engineering/architecture/*.md files older than 90 days
+    // This check runs regardless of .forge/ presence (only needs cwd + engPath).
+    gaps.push(...checkStaleDocs(cwd, configRecord));
+    // 5. Modified generated files check — generation-manifest.cjs list --modified
+    // Only runs when config is present (manifest lives in .forge/).
+    gaps.push(...checkModifiedGeneratedFiles(cwd, bundleRoot));
+    // 6. Plugin integrity check — native TS hash check against forgeRoot/integrity.json
+    // Only runs when forgeRoot is provided.
+    if (forgeRoot) {
+        gaps.push(...checkPluginIntegrity(forgeRoot));
+    }
     const clean = gaps.length === 0;
     const summary = clean ? "〇 /forge:health: clean." : `△ /forge:health: ${gaps.length} gap(s) detected.`;
     return {
@@ -151,4 +173,155 @@ export async function runHealthCheck(cwd, bundleRoot) {
         summary,
     };
 }
+// ── Check: Stale docs ──────────────────────────────────────────────────────
+/**
+ * Check for architecture docs not updated in over 90 days.
+ * Returns one HealthGap per stale file.
+ * Silently returns [] if the architecture directory does not exist.
+ */
+export function checkStaleDocs(cwd, config) {
+    const gaps = [];
+    const engPath = config.paths?.engineering ?? "engineering";
+    const archDir = path.join(cwd, engPath, "architecture");
+    if (!fs.existsSync(archDir)) {
+        return gaps;
+    }
+    let files;
+    try {
+        files = fs.readdirSync(archDir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return gaps;
+    }
+    const now = Date.now();
+    for (const file of files) {
+        const filePath = path.join(archDir, file);
+        try {
+            const stat = fs.statSync(filePath);
+            const ageMs = now - stat.mtimeMs;
+            if (ageMs > STALE_DOCS_THRESHOLD_MS) {
+                const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+                gaps.push({
+                    check: "stale-docs",
+                    severity: "warning",
+                    message: `${engPath}/architecture/${file} not updated in ${ageDays} days — may be stale. Run /forge:collate to refresh.`,
+                });
+            }
+        }
+        catch {
+            // Skip files we can't stat
+        }
+    }
+    return gaps;
+}
+// ── Check: Modified generated files ───────────────────────────────────────
+/**
+ * Check for generated files that have been manually edited.
+ * Spawns generation-manifest.cjs list --modified from the bundled tools.
+ * Returns one HealthGap per modified/missing file.
+ * Silently returns [] if the tool is absent.
+ */
+export function checkModifiedGeneratedFiles(cwd, bundleRoot) {
+    const gaps = [];
+    const genManifestTool = path.join(bundleRoot, "tools", "generation-manifest.cjs");
+    if (!fs.existsSync(genManifestTool)) {
+        return gaps;
+    }
+    let stdout = "";
+    try {
+        stdout = execFileSync("node", [genManifestTool, "list", "--modified"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        // generation-manifest exits non-zero when modifications are found.
+        // Parse stdout from the error object.
+        const e = err;
+        stdout = e.stdout ?? "";
+    }
+    const lines = stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith("#"));
+    for (const line of lines) {
+        gaps.push({
+            check: "modified-generated-files",
+            severity: "warning",
+            message: `Generated file modified: ${line} — regeneration will warn before overwriting. Run /forge:regenerate to review.`,
+        });
+    }
+    return gaps;
+}
+/**
+ * Check plugin files against the integrity.json manifest.
+ * Natively implemented in TypeScript — no subprocess required.
+ * Returns one HealthGap per modified or missing file.
+ * Silently returns [] if forgeRoot is not provided or integrity.json is missing.
+ */
+export function checkPluginIntegrity(forgeRoot) {
+    const gaps = [];
+    const integrityPath = path.join(forgeRoot, "integrity.json");
+    if (!fs.existsSync(integrityPath)) {
+        gaps.push({
+            check: "plugin-integrity",
+            severity: "warning",
+            message: "integrity.json not found in forge plugin root — run /forge:update to restore.",
+        });
+        return gaps;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(integrityPath, "utf8"));
+    }
+    catch (err) {
+        const e = err;
+        gaps.push({
+            check: "plugin-integrity",
+            severity: "warning",
+            message: `integrity.json is not valid JSON: ${e.message}`,
+        });
+        return gaps;
+    }
+    if (!manifest.files || typeof manifest.files !== "object") {
+        gaps.push({
+            check: "plugin-integrity",
+            severity: "warning",
+            message: "integrity.json has no files section — run /forge:update to restore.",
+        });
+        return gaps;
+    }
+    for (const [relativePath, expectedHash] of Object.entries(manifest.files)) {
+        const absolutePath = path.join(forgeRoot, relativePath);
+        if (!fs.existsSync(absolutePath)) {
+            gaps.push({
+                check: "plugin-integrity",
+                severity: "warning",
+                message: `Plugin file missing: ${relativePath} — run /forge:update to restore.`,
+            });
+            continue;
+        }
+        try {
+            const content = fs.readFileSync(absolutePath);
+            const actualHash = crypto.createHash("sha256").update(content).digest("hex");
+            if (actualHash !== expectedHash) {
+                gaps.push({
+                    check: "plugin-integrity",
+                    severity: "warning",
+                    message: `Plugin file modified: ${relativePath} — run /forge:update to restore.`,
+                });
+            }
+        }
+        catch {
+            gaps.push({
+                check: "plugin-integrity",
+                severity: "warning",
+                message: `Cannot read plugin file: ${relativePath} — permission or I/O error.`,
+            });
+        }
+    }
+    return gaps;
+}
 //# sourceMappingURL=health-check.js.map

package/dist/extensions/forgecli/health-check.js.map

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

package/dist/extensions/forgecli/hook-dispatcher.d.ts

@@ -26,8 +26,32 @@ export interface SprintCollateCompleteEvent {
     /** Absolute path to the project root (process.cwd() at emit time). */
     cwd: string;
 }
+/**
+ * Payload for the migration-applied synthetic event (FORGE-S23-T01).
+ *
+ * Emitted by forge-update-command.ts after runMigrations() completes
+ * successfully. Enables future hook handlers to react to migration completion
+ * (e.g. trigger /forge:health checks, update-check resets).
+ *
+ * NOTE: No emitSyntheticEvent call is wired in this task — the event type is
+ * added to the union for forward compatibility. The interim emit path uses
+ * `store-cli emit SYS-migration` directly from forge-update-command.ts.
+ * event.schema.json is NOT modified in this task (system-migration type deferred
+ * to a follow-on task per PLAN.md §1D).
+ */
+export interface MigrationAppliedEvent {
+    type: "migration-applied";
+    /** Version the user was running before migration */
+    fromVersion: string;
+    /** Version the user upgraded to */
+    toVersion: string;
+    /** Number of migration entries applied */
+    appliedCount: number;
+    /** Absolute path to the project root */
+    cwd: string;
+}
 /** Union of all synthetic event payloads. Extend here as new events are added. */
-export type SyntheticEvent = InitCompleteEvent | SprintCollateCompleteEvent;
+export type SyntheticEvent = InitCompleteEvent | SprintCollateCompleteEvent | MigrationAppliedEvent;
 /**
  * Handler signature for synthetic events.
  * ctx is the ExtensionCommandContext of the emitting phase — callers must

package/dist/extensions/forgecli/hook-dispatcher.js

@@ -1,4 +1,4 @@
-// Pi-runtime hook adapter — FORGE-S18-T02 / FORGE-S18-T03 / FORGE-S21-T04
+// Pi-runtime hook adapter — FORGE-S18-T02 / FORGE-S18-T03 / FORGE-S21-T04 / FORGE-S23-T02 / FORGE-S23-T03
 //
 // Wires Forge's hook semantics onto pi's tool_call / tool_result events.
 // T02: Provides audit-only observation scaffolding.
@@ -8,6 +8,11 @@
 // T04: Adds typed synthetic event taxonomy (InitCompleteEvent) with
 //      onSyntheticEvent / emitSyntheticEvent for in-process hook dispatch
 //      that bridges deterministic TS handler phases to registered hook handlers.
+// T02 (S23): Adds full FS-level write-boundary schema guard via write-guard.ts —
+//      validates Write/Edit tool calls targeting .forge/store/**/*.json and
+//      .forge/config.json against Forge JSON schemas. Composed after two-layer-guard.
+// T03 (S23): Adds triage-error hook — on Bash tool_result with isError=true and a
+//      Forge-related command, injects ctx.ui.notify suggesting /forge:report-bug.
 //
 // Audit logging: set FORGE_HOOK_AUDIT=1 to write to .forge/logs/hooks.log.
 // In enforcement mode (default): violations are blocked.
@@ -16,10 +21,17 @@
 // --force scope:
 //   When --force is present in store-cli argv, transition-guard is bypassed.
 //   store-validator still runs — a malformed payload is always invalid.
+//
+// Write-guard bypass:
+//   FORGE_SKIP_WRITE_VALIDATION=1 bypasses checkWriteGuard for one turn.
+//   The write-guard itself handles this env var; hook-dispatcher defers to it.
 import { appendFileSync, mkdirSync } from "node:fs";
 import * as path from "node:path";
-import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { isBashToolResult, isToolCallEventType } from "@earendil-works/pi-coding-agent";
 import { checkTwoLayerBoundary } from "./hooks/two-layer-guard.js";
+import { applyPiEdits, checkWriteGuard } from "./hooks/write-guard.js";
+import { buildTriageMessage, isForgeRelated } from "./hooks/triage-error.js";
+import { matchForgePermission } from "./hooks/forge-permissions.js";
 import { validateStoreCLIPayload } from "./store-validator.js";
 import { checkTransition } from "./transition-guard.js";
 // Module-level registry. Pi extension processes are single-session; the
@@ -222,20 +234,87 @@ export function registerHookDispatcher(pi, forgeRoot) {
     // ── tool_call: fires before any tool executes ─────────────────────────────
     pi.on("tool_call", (event) => {
         appendAudit(logsDir, `[tool_call] toolName=${event.toolName} toolCallId=${event.toolCallId}`);
+        // ── Forge-permission auto-allow (FORGE-S23-T04) ───────────────────────
+        // Port of forge-permissions.js pattern-match logic. Pi has no PermissionRequest
+        // event, so matched patterns silently return undefined (no block) from the
+        // tool_call handler.
+        //
+        // Bash match:  full short-circuit — skip all downstream bash handling.
+        // Write/Edit:  skip two-layer-guard (sets skipTwoLayerGuard=true), but
+        //              FALL THROUGH to write-guard schema check (AC#4: an allowed
+        //              write to .forge/store/ that fails schema is still blocked).
+        //
+        // Security: this guard can only ALLOW, never DENY. Patterns are ported
+        // verbatim from forge-permissions.js including the node -e exclusion.
+        //
+        // Important: bash commands targeting store-cli.cjs must NOT be short-circuited
+        // here — they need to fall through to the store-cli schema/transition validation
+        // below. The node-tool BASH_PATTERN matches store-cli.cjs invocations, but the
+        // security invariant is: store-cli payloads are always validated against schema,
+        // regardless of permission match. Skip forge-permissions for store-cli commands.
+        if (isToolCallEventType("bash", event)) {
+            const bashCmd = event.input.command ?? "";
+            if (!bashCmd.includes("store-cli.cjs")) {
+                const bashRule = matchForgePermission("bash", { command: bashCmd });
+                if (bashRule !== null) {
+                    appendAudit(logsDir, `[forge-permissions] allowed bash: ${bashRule}`);
+                    return undefined;
+                }
+            }
+        }
+        let skipTwoLayerGuard = false;
+        if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+            const filePath = event.input.path ?? "";
+            const writeRule = matchForgePermission(event.toolName, { path: filePath });
+            if (writeRule !== null) {
+                appendAudit(logsDir, `[forge-permissions] allowed ${event.toolName}: ${writeRule}`);
+                skipTwoLayerGuard = true;
+            }
+        }
         // ── Two-layer boundary guard (FORGE-S20-T07) ───────────────────────────
         // Reject any write/edit whose target path resolves under
         // <cwd>/forge/forge/meta/. Two-layer rule: fixes to Forge itself go
         // through forge-engineer/forge-bugfixer against forge/, not via
         // forge-cli runtime edits. FORGE_HOOK_AUDIT=1 logs but never blocks.
+        // Skipped when forge-permissions already matched the path (skipTwoLayerGuard=true).
         if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
-            const verdict = checkTwoLayerBoundary(event.input.path, process.cwd());
-            if (!verdict.allowed) {
-                appendAudit(logsDir, `[two-layer-guard] decision=would-block path=${verdict.resolvedPath} reason=${verdict.reason}`);
+            if (!skipTwoLayerGuard) {
+                const verdict = checkTwoLayerBoundary(event.input.path, process.cwd());
+                if (!verdict.allowed) {
+                    appendAudit(logsDir, `[two-layer-guard] decision=would-block path=${verdict.resolvedPath} reason=${verdict.reason}`);
+                    if (auditEnabled()) {
+                        return undefined;
+                    }
+                    return { block: true, reason: verdict.reason };
+                }
+            }
+            // ── Write-boundary schema guard (FORGE-S23-T02) ─────────────────────
+            // After two-layer passes (or is skipped), validate the post-write contents
+            // against the Forge schema for the target path. Always runs regardless of
+            // skipTwoLayerGuard — AC#4: an allowed write to .forge/store/ that fails
+            // schema is still blocked. Only applies to .forge/store/** and
+            // .forge/config.json paths (registry-matched). Fail-open on internal errors.
+            // FORGE_SKIP_WRITE_VALIDATION=1 bypasses.
+            const resolvedPath = path.resolve(process.cwd(), event.input.path);
+            let postContents;
+            if (isToolCallEventType("write", event)) {
+                postContents = typeof event.input.content === "string" ? event.input.content : "";
+            }
+            else {
+                // Edit event: apply pi edits array to current file contents
+                const editsInput = event.input.edits;
+                const edits = Array.isArray(editsInput) ? editsInput : [];
+                postContents = applyPiEdits(resolvedPath, edits);
+            }
+            const guardResult = checkWriteGuard(resolvedPath, postContents, forgeRoot);
+            if (guardResult.block) {
+                appendAudit(logsDir, `[write-guard] decision=would-block path=${resolvedPath} reason=${guardResult.reason ?? "schema violation"}`);
                 if (auditEnabled()) {
                     return undefined;
                 }
-                return { block: true, reason: verdict.reason };
+                return { block: true, reason: guardResult.reason };
             }
+            appendAudit(logsDir, `[write-guard] decision=would-allow path=${resolvedPath}`);
         }
         // Bash interception: identify store-cli write/update-status calls.
         if (isToolCallEventType("bash", event)) {
@@ -292,10 +371,26 @@ export function registerHookDispatcher(pi, forgeRoot) {
         }
         return undefined;
     });
-    // ── tool_result: fires after any tool completes (observe-only) ──────────────
-    pi.on("tool_result", (event) => {
+    // ── tool_result: fires after any tool completes ───────────────────────────
+    pi.on("tool_result", (event, ctx) => {
         appendAudit(logsDir, `[tool_result] toolName=${event.toolName} toolCallId=${event.toolCallId}`);
-        // Audit-only in T02 — return void (no result replacement).
+        // ── Triage-error: post-Bash-failure context injection (FORGE-S23-T03) ──
+        // When a Bash command exits non-zero and matches Forge-related patterns,
+        // notify the user to file a bug via /forge:report-bug.
+        if (isBashToolResult(event) && event.isError) {
+            const command = typeof event.input.command === "string" ? event.input.command : "";
+            if (isForgeRelated(command)) {
+                const snippet = event.content
+                    .filter((c) => c.type === "text")
+                    .map((c) => c.text)
+                    .join("")
+                    .split("\n")
+                    .slice(0, 3)
+                    .join(" ")
+                    .trim();
+                ctx.ui.notify(buildTriageMessage(command, snippet), "warning");
+            }
+        }
     });
 }
 //# sourceMappingURL=hook-dispatcher.js.map

package/dist/extensions/forgecli/hook-dispatcher.js.map

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

package/dist/extensions/forgecli/hooks/check-update.d.ts

@@ -0,0 +1,81 @@
+export interface CheckUpdateOptions {
+    forgeRoot: string;
+    configPath: string;
+    cwd?: string;
+    homeDir?: string;
+}
+export interface ProjectCache {
+    migratedFrom?: string;
+    localVersion?: string;
+    distribution?: string;
+    forgeRoot?: string;
+    forgeRef?: string;
+    updateStatus?: "pending" | "complete";
+    pendingReason?: string | null;
+    pendingMigrations?: string[];
+}
+export interface InstallRecord {
+    path: string;
+    version: string;
+    distribution: string;
+    scope: "user" | "project" | "unknown";
+    enabled: boolean;
+}
+/**
+ * Derives the distribution name from a plugin root path.
+ * Ported verbatim from forge/forge/hooks/check-update.js `detectDistribution()`.
+ *
+ * Returns "forge@skillforge" for skillforge-marketplace installs,
+ * "forge@forge" for all others (direct forge installs).
+ */
+export declare function detectDistribution(root: string): string;
+/**
+ * Reads and parses the project-level update-check cache from .forge/update-check-cache.json.
+ * Returns null if the file is absent or malformed.
+ * Non-fatal — all errors are swallowed.
+ */
+export declare function readProjectCache(forgeDir: string): ProjectCache | null;
+/**
+ * Builds a Forge-awareness message if this project has a .forge/config.json.
+ * Corresponds to the forge-awareness context injection in check-update.js.
+ *
+ * In the plugin, this is emitted as {"additionalContext":"..."} to stdout.
+ * In forge-cli, the caller does ctx.ui.notify(msg, "info") — pi has no
+ * session_start additionalContext protocol.
+ *
+ * Returns null when configPath is missing or unreadable (e.g. outside-Forge project).
+ */
+export declare function buildForgeAwarenessMsg(configPath: string): string | null;
+/**
+ * Scans known plugin locations for all Forge installations.
+ * Ported from check-update.js scanPluginInstallations() with injectable options for testing.
+ *
+ * Returns an array of installation records with version, distribution, scope, enabled status.
+ */
+export declare function scanPluginInstallations(opts?: {
+    homeDir?: string;
+    cwd?: string;
+}): InstallRecord[];
+/**
+ * Builds a multi-plugin awareness message if multiple Forge installations are detected.
+ * Returns null if only one (or zero) installations found.
+ */
+export declare function buildMultiPluginMsg(opts: CheckUpdateOptions): string | null;
+/**
+ * Syncs paths.forgeRoot and paths.forgeRef in .forge/config.json if they drift.
+ * Detects distribution switches (forge@forge ↔ forge@skillforge) and returns a
+ * notification message if the distribution changed; returns null otherwise.
+ *
+ * Also updates the project-level cache (.forge/update-check-cache.json) with
+ * current distribution, forgeRoot, and forgeRef (preserving updateStatus, pendingMigrations).
+ *
+ * Corresponds to the "Distribution + forgeRoot/forgeRef sync" section in check-update.js.
+ */
+export declare function syncForgeRootAndRef(opts: CheckUpdateOptions): string | null;
+/**
+ * Surfaces a pending-migration warning if the project cache shows updateStatus === "pending".
+ * Returns the warning message string, or null if no pending state or cache absent.
+ *
+ * Corresponds to FR-002 pending-state surfacing in check-update.js.
+ */
+export declare function buildPendingMigrationMsg(configPath: string): string | null;