frappe-builder 1.1.0-dev.10

package/extensions/frappe-state.ts

@@ -0,0 +1,235 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { db, getCurrentPhase } from "../state/db.js";
+import { appendEntry } from "../state/journal.js";
+import { buildStateContext, loadSpecialist, loadDebuggerSpecialist } from "./frappe-session.js";
+import { loadCredentials } from "../config/loader.js";
+
+/** Reads current_phase and feature_id from the active session. */
+function readSessionState(): { currentPhase: string; activeFeatureId: string | null } {
+  const row = db
+    .prepare("SELECT current_phase, feature_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { current_phase: string; feature_id: string | null } | undefined;
+  return {
+    currentPhase: row?.current_phase ?? "idle",
+    activeFeatureId: row?.feature_id ?? null,
+  };
+}
+
+/** Queries the active session_id from SQLite, or returns a fallback. */
+function getActiveSessionId(): string {
+  const row = db
+    .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { session_id: string } | undefined;
+  return row?.session_id ?? "unknown";
+}
+
+/** Type guard for SpawnAgentResult from agent-tools.ts. */
+function isSpawnAgentResult(value: unknown): value is { status: string; skill: string; trigger: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    "skill" in value &&
+    "trigger" in value
+  );
+}
+
+/** Type guard for the return value of startFeature(). */
+function isStartFeatureResult(value: unknown): value is { mode: string; feature_id: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "mode" in value &&
+    "feature_id" in value &&
+    typeof (value as Record<string, unknown>).mode === "string" &&
+    typeof (value as Record<string, unknown>).feature_id === "string"
+  );
+}
+
+/**
+ * Atomically updates sessions.current_phase and features.current_phase in state.db.
+ * Throws on DB failure — caller (handleAfterToolCall) converts to banner.
+ */
+function applyPhaseTransition(featureId: string, newPhase: string): void {
+  db.transaction(() => {
+    db.prepare("UPDATE sessions SET current_phase = ? WHERE is_active = 1").run(newPhase);
+    db.prepare("UPDATE features SET current_phase = ? WHERE feature_id = ?").run(newPhase, featureId);
+  })();
+}
+
+/**
+ * Session start hook — validates gitignore and loads credentials before any session setup.
+ * Throws with AC error message if .frappe-builder-config.json is not gitignored.
+ * Call this early in the session_start lifecycle; on throw, halt and surface the message.
+ * projectRoot defaults to process.cwd() when not supplied by the pi extension system.
+ *
+ * TODO: wire this into the pi extension system's session_start event once the
+ * session_start hook type is confirmed in @mariozechner/pi-agent-core.
+ */
+export function handleSessionStart(projectRoot: string = process.cwd()): void {
+  loadCredentials(projectRoot);
+}
+
+/**
+ * afterToolCall hook — appends a JSONL journal entry and updates the sessions
+ * table in a single synchronous transaction after every tool call.
+ *
+ * Also handles FSM phase transition when start_feature fires (Story 3.3).
+ * Mode routing never touches gate execution — quality gates run independently
+ * in frappe-gates.ts regardless of mode (full or quick).
+ *
+ * Never throws. On write failure, appends a [STATE WRITE FAILED] banner to the
+ * tool result content instead of crashing the session.
+ */
+export async function handleAfterToolCall(
+  context: AfterToolCallContext,
+  _signal?: AbortSignal
+): Promise<AfterToolCallResult | undefined> {
+  const toolName = context.toolCall.name;
+  const phase = getCurrentPhase();
+  const sessionId = getActiveSessionId();
+
+  try {
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId,
+      type: "tool_call",
+      payload: {
+        tool: toolName,
+        phase,
+        result: (() => {
+          const first = context.result.content.find((c) => c.type === "text") as
+            | TextContent
+            | undefined;
+          return first?.text.slice(0, 200) ?? "";
+        })(),
+      },
+    });
+
+    db.transaction(() => {
+      db.prepare(
+        "UPDATE sessions SET last_tool = ? WHERE is_active = 1"
+      ).run(toolName);
+    })();
+
+    // FSM phase transition for start_feature (Story 3.3)
+    if (toolName === "start_feature") {
+      const firstText = context.result.content.find((c) => c.type === "text") as
+        | TextContent
+        | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try {
+          parsed = JSON.parse(firstText.text);
+        } catch {
+          // non-JSON result — skip phase transition silently
+        }
+        if (isStartFeatureResult(parsed)) {
+          const newPhase = parsed.mode === "quick" ? "implementation" : "requirements";
+          applyPhaseTransition(parsed.feature_id, newPhase);
+
+          // Specialist auto-load after phase transition (Story 3.4) — non-fatal
+          try {
+            const specCtx = buildStateContext(parsed.feature_id, toolName);
+            const specialistBlock = loadSpecialist(newPhase, specCtx);
+            if (specialistBlock) {
+              const specialistContent: TextContent = {
+                type: "text",
+                text: `\n\n${specialistBlock}`,
+              };
+              return { content: [...context.result.content, specialistContent] };
+            }
+          } catch (specialistErr) {
+            console.error(`[frappe-state] specialist load failed: ${specialistErr}`);
+            // non-fatal — session continues without specialist block
+          }
+        }
+      }
+    }
+
+    // Debugger specialist invocation (Story 3.5) — no phase transition
+    if (toolName === "invoke_debugger") {
+      const { currentPhase, activeFeatureId } = readSessionState();
+      appendEntry({
+        ts: new Date().toISOString(),
+        sessionId,
+        type: "tool_call",
+        payload: { tool: "invoke_debugger", phase_preserved: currentPhase },
+      });
+      try {
+        const specCtx = buildStateContext(activeFeatureId, toolName);
+        const debuggerBlock = loadDebuggerSpecialist(specCtx);
+        if (debuggerBlock) {
+          const content: TextContent = { type: "text", text: `\n\n${debuggerBlock}` };
+          return { content: [...context.result.content, content] };
+        }
+      } catch (debuggerErr) {
+        console.error(`[frappe-state] debugger specialist load failed: ${debuggerErr}`);
+      }
+    }
+
+    // Sub-agent spawn JSONL logging (Story 3.6) — no phase transition, no specialist change
+    if (toolName === "spawn_agent") {
+      const firstText = context.result.content.find((c) => c.type === "text") as TextContent | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try { parsed = JSON.parse(firstText.text); } catch { /* skip */ }
+        if (isSpawnAgentResult(parsed)) {
+          try {
+            const approved = parsed.status === "spawned";
+            const entry: Record<string, unknown> = {
+              type: "sub_agent",
+              skill: parsed.skill,
+              trigger: parsed.trigger,
+              approved,
+            };
+            if (parsed.status === "disabled") entry.reason = "disabled";
+            if (parsed.status === "requires_approval") entry.reason = "awaiting_approval";
+            appendEntry({
+              ts: new Date().toISOString(),
+              sessionId,
+              type: "tool_call",
+              payload: entry,
+            });
+          } catch (spawnErr) {
+            console.error(`[frappe-state] spawn_agent log failed: ${spawnErr}`);
+          }
+        }
+      }
+    }
+
+    // End debug — restore previous phase specialist (Story 3.5) — no phase transition
+    if (toolName === "end_debug") {
+      const { currentPhase, activeFeatureId } = readSessionState();
+      appendEntry({
+        ts: new Date().toISOString(),
+        sessionId,
+        type: "tool_call",
+        payload: { tool: "end_debug", phase_restored: currentPhase },
+      });
+      try {
+        const specCtx = buildStateContext(activeFeatureId, toolName);
+        const specialistBlock = loadSpecialist(currentPhase, specCtx);
+        if (specialistBlock) {
+          const content: TextContent = { type: "text", text: `\n\n${specialistBlock}` };
+          return { content: [...context.result.content, content] };
+        }
+      } catch (endDebugErr) {
+        console.error(`[frappe-state] end_debug specialist restore failed: ${endDebugErr}`);
+      }
+    }
+
+    return undefined;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[frappe-state] afterToolCall write failed: ${msg}`);
+
+    const banner: TextContent = {
+      type: "text",
+      text: `\n\n[STATE WRITE FAILED: ${msg}]`,
+    };
+
+    return { content: [...context.result.content, banner] };
+  }
+}

package/extensions/frappe-tools.ts

@@ -0,0 +1,278 @@
+import { Type } from "@sinclair/typebox";
+import { startFeature, completeComponent } from "../tools/feature-tools.js";
+import { setActiveProject, getProjectStatus } from "../tools/project-tools.js";
+import { getAuditLog } from "../state/journal.js";
+import { invokeDebugger, endDebug } from "../tools/debug-tools.js";
+import { spawnAgent } from "../tools/agent-tools.js";
+import { scaffoldDoctype, benchExecute, runTests } from "../tools/bench-tools.js";
+import { frappeQuery } from "../tools/frappe-query-tools.js";
+import { getFrappeDocs } from "../tools/frappe-context7.js";
+
+// pi.registerTool's execute callback is untyped (pi is `any`); params are
+// enforced at runtime via TypeBox schemas. One explicit-any alias avoids
+// noImplicitAny errors across all callbacks without per-line suppressions.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ToolParams = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.registerTool({
+    name: "start_feature",
+    label: "Start Feature",
+    description:
+      "Creates and names a new feature within the active project, initialising its state in state.db. Valid only in the 'idle' phase.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Feature name (e.g. 'PO Approval')" }),
+      mode: Type.Union([Type.Literal("full"), Type.Literal("quick")], {
+        description: "Workflow mode: 'full' for all phases, 'quick' for rapid delivery",
+      }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = startFeature(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "complete_component",
+    label: "Complete Component",
+    description:
+      "Marks a feature component as complete in state.db and creates an automatic git checkpoint commit. Valid only in the 'implementation' phase.",
+    parameters: Type.Object({
+      featureId: Type.String({ description: "Feature ID (kebab-case slug, e.g. 'po-approval')" }),
+      componentId: Type.String({ description: "Component ID (e.g. 'auth-module')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await completeComponent(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "set_active_project",
+    label: "Set Active Project",
+    description:
+      "Switches the active Frappe project and site. Flushes current session state, creates a new session for the target project (restoring prior phase if known), and reloads the system prompt context. Available in any phase.",
+    parameters: Type.Object({
+      projectId: Type.String({ description: "Project identifier (e.g. 'my-frappe-site')" }),
+      sitePath: Type.String({ description: "Absolute path to the Frappe bench site (e.g. '/home/user/frappe-bench/sites/site1.local')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await setActiveProject(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "invoke_debugger",
+    label: "Invoke Debugger",
+    description:
+      "Loads the frappe-debugger specialist without triggering a phase transition. Valid in any phase (FR34).",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = invokeDebugger();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "end_debug",
+    label: "End Debug",
+    description:
+      "Exits the debugger session and restores the specialist for the preserved phase. Valid in any phase.",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = endDebug();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "spawn_agent",
+    label: "Spawn Agent",
+    description:
+      "Spawns a sub-agent for parallel work. Requires explicit user approval when requirePermission is true in config. Valid in any phase.",
+    parameters: Type.Object({
+      skill: Type.String({ description: "Sub-agent skill name (e.g. 'dev-agent')" }),
+      trigger: Type.String({ description: "Trigger reason (e.g. 'scaffold')" }),
+      reason: Type.String({ description: "Human-readable reason for spawning" }),
+      approved: Type.Optional(Type.Boolean({ description: "User approval decision (set after permission prompt)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await spawnAgent(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "scaffold_doctype",
+    label: "Scaffold DocType",
+    description:
+      "Creates a new Frappe DocType via bench. Valid only in the 'implementation' phase. (Story 4.2 deferred)",
+    parameters: Type.Object({
+      name: Type.String({ description: "DocType name in PascalCase (e.g. 'Purchase Order')" }),
+      module: Type.String({ description: "Frappe module name (e.g. 'Buying')" }),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = scaffoldDoctype(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "run_tests",
+    label: "Run Tests",
+    description:
+      "Runs the Frappe test suite for the active feature via bench. Valid only in the 'testing' phase. (Epic 6)",
+    parameters: Type.Object({
+      featureId: Type.Optional(Type.String({ description: "Feature ID to scope tests (optional)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = runTests(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "get_project_status",
+    label: "Get Project Status",
+    description:
+      "Returns a dashboard summary of the active project: features, components, phase, and progress. Available in any phase. (Story 5.2)",
+    parameters: Type.Object({}),
+    execute: async (_toolCallId: string, _params: ToolParams) => {
+      const result = getProjectStatus();
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "frappe_query",
+    label: "Frappe Query",
+    description:
+      "Queries Frappe data via mcp2cli subprocess. Output is routed through the context-mode sandbox — raw payloads never enter the LLM context. Available in any phase.",
+    parameters: Type.Object({
+      doctype: Type.String({ description: "Frappe DocType to query (e.g. 'Sales Order')" }),
+      filters: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: "Filter key-value pairs (e.g. { status: 'Draft' })",
+      })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await frappeQuery(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // 9th tool — outside the 8 core Frappe-semantic tools; bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  pi.registerTool({
+    name: "get_frappe_docs",
+    label: "Get Frappe Docs",
+    description:
+      "Retrieves compressed Frappe/ERPNext documentation via context7 MCP. Raw web content never enters the LLM context (~90% token reduction). Valid in any phase. (Story 4.4)",
+    parameters: Type.Object({
+      topic: Type.String({ description: "Documentation topic (e.g. 'DocType', 'hooks', 'frappe.db')" }),
+      version: Type.Optional(Type.String({ description: "Frappe version to scope docs (e.g. 'v15')" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await getFrappeDocs(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "get_audit_log",
+    label: "Get Audit Log",
+    description:
+      "Queries JSONL audit log entries from session files. Supports filtering by sessionId, featureId, and limit. Available in any phase. (Story 5.3)",
+    parameters: Type.Object({
+      sessionId: Type.Optional(Type.String({ description: "Session ID to query (omit for all sessions)" })),
+      featureId: Type.Optional(Type.String({ description: "Feature ID to filter entries by payload.feature" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of entries to return (default: all)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = getAuditLog(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // /status slash command — displays project dashboard (FR21, Story 5.2)
+  // Defensive: pi.registerCommand may not be available in all pi-mono versions
+  if (typeof pi.registerCommand === "function") {
+    pi.registerCommand("status", {
+      description: "Show project dashboard: features, components, phase, and progress",
+      handler: async (_args: string, ctx: Record<string, unknown>) => {
+        const status = getProjectStatus();
+        const lines: string[] = [];
+        if (status.message) {
+          lines.push(status.message);
+        } else {
+          for (const f of status.features) {
+            lines.push(`[${f.phase}] ${f.name} (${f.componentsDone}/${f.componentsTotal} done)`);
+            for (const c of f.components) {
+              const mark = c.status === "complete" ? "✓" : "·";
+              lines.push(`  ${mark} ${c.componentId}`);
+            }
+          }
+        }
+        const output = lines.join("\n") || "No project data";
+        if (ctx.hasUI && ctx.ui && typeof (ctx.ui as Record<string, unknown>).notify === "function") {
+          (ctx.ui as { notify: (msg: string, sev: string) => void }).notify(output, "info");
+        }
+        return output;
+      },
+    });
+  }
+
+  pi.registerTool({
+    name: "bench_execute",
+    label: "Bench Execute",
+    description:
+      "Runs a whitelisted bench command via subprocess. Output sandboxed through context-mode. Valid only in the 'implementation' phase. (Story 4.3)",
+    parameters: Type.Object({
+      command: Type.String({ description: "Bench command (e.g. 'migrate')" }),
+      args: Type.Optional(Type.Array(Type.String(), { description: "Additional arguments" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = benchExecute(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+}

package/extensions/frappe-ui.ts

@@ -0,0 +1,119 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+import { db, getCurrentPhase } from "../state/db.js";
+
+interface FooterState {
+  projectId: string | null;
+  featureName: string | null;
+  phase: string;
+  tokenCount: number;
+}
+
+function readFooterState(): FooterState {
+  try {
+    const session = db
+      .prepare(
+        `SELECT s.project_id, f.name AS feature_name, s.current_phase
+         FROM sessions s
+         LEFT JOIN features f ON f.feature_id = s.feature_id
+         WHERE s.is_active = 1 LIMIT 1`
+      )
+      .get() as
+      | { project_id: string | null; feature_name: string | null; current_phase: string }
+      | undefined;
+
+    // Token count: count journal_entries for active session; table may not exist yet
+    let tokenCount = 0;
+    try {
+      const tokenRow = db
+        .prepare(
+          `SELECT COUNT(*) as count FROM journal_entries
+           WHERE session_id = (SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1)`
+        )
+        .get() as { count: number } | undefined;
+      tokenCount = tokenRow?.count ?? 0;
+    } catch {
+      // journal_entries table not yet created — default to 0
+    }
+
+    return {
+      projectId: session?.project_id ?? null,
+      featureName: session?.feature_name ?? null,
+      phase: session?.current_phase ?? "idle",
+      tokenCount,
+    };
+  } catch {
+    return { projectId: null, featureName: null, phase: "idle", tokenCount: 0 };
+  }
+}
+
+/**
+ * Pure formatting function — no I/O, no side effects.
+ * Exported for unit testing.
+ */
+export function formatFooter(state: FooterState): string {
+  if (!state.projectId) {
+    return `No active project | Phase: ${state.phase}`;
+  }
+  if (!state.featureName) {
+    return `Project: ${state.projectId} | No active feature | Phase: ${state.phase}`;
+  }
+  return `Project: ${state.projectId} | Feature: ${state.featureName} | Phase: ${state.phase} | Tokens: ${state.tokenCount}`;
+}
+
+function renderFooter(): void {
+  try {
+    const state = readFooterState();
+    const line = formatFooter(state);
+    process.stderr.write(`\r\x1b[2K[frappe-builder] ${line}\n`);
+  } catch {
+    // Silently swallow all rendering errors — footer is non-critical
+  }
+}
+
+/**
+ * beforeToolCall announcement hook — writes "→ Calling {tool} [{phase}]" to stderr.
+ * Always returns undefined — this hook only announces, never blocks.
+ * Wrap in try/catch so announcement failure never crashes the session.
+ *
+ * Load order note: frappe-ui must load before frappe-workflow so this fires
+ * before the FSM guard. Load order is controlled by the pi extension list;
+ * package.json "pi" field is currently empty so order is determined by the
+ * pi CLI -e flags at startup.
+ */
+export function handleBeforeToolCall(toolName: string): undefined {
+  try {
+    const phase = getCurrentPhase();
+    process.stderr.write(`→ Calling ${toolName} [${phase}]\n`);
+  } catch {
+    // Swallow — announcement is non-critical, must never block or crash
+  }
+  return undefined;
+}
+
+/**
+ * afterToolCall hook — renders the footer and returns undefined so the
+ * original tool result passes through unmodified.
+ */
+export async function handleAfterToolCall(
+  _context: AfterToolCallContext,
+  _signal?: AbortSignal
+): Promise<AfterToolCallResult | undefined> {
+  renderFooter();
+  return undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("session_start", () => {
+    renderFooter();
+  });
+
+  // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
+  pi.on("tool_call", (event: { toolName?: string }) => {
+    return handleBeforeToolCall(event.toolName ?? "");
+  });
+
+  pi.on("after_tool_call", async (context: AfterToolCallContext) => {
+    return await handleAfterToolCall(context);
+  });
+}