frappe-builder 1.1.0-dev.26 → 1.1.0-dev.28

package/.frappe-builder/po-approval/implementation-artifacts/sprint-status.yaml

@@ -2,13 +2,13 @@ feature_id: po-approval
 feature_name: "PO Approval"
 mode: full
 phase: testing
-updated_at: 2026-03-28T14:38:26.634Z
+updated_at: 2026-03-28T16:59:13.498Z
 
 components:
   - id: final-comp
     sort_order: 0
     status: complete
-    completed_at: 2026-03-28T14:38:26.633Z
+    completed_at: 2026-03-28T16:59:13.498Z
 
 progress:
   done: 1

package/README.md

@@ -18,17 +18,14 @@ npm install -g frappe-builder
 
 ## Initial Setup
 
-Run once per project after installation:
+Run once per machine after installation:
 
 ```bash
 cd /path/to/your-frappe-project
 frappe-builder init
 ```
 
-This will:
-- Prompt for your LLM API key → saves to `~/.frappe-builder/config.json`
-- Prompt for your Frappe site URL and API credentials → saves to `.frappe-builder-config.json`
-- Automatically add `.frappe-builder-config.json` to `.gitignore`
+This installs and configures the agent toolchain (context-mode, mcp2cli, context7) and patches `.gitignore` with `.fb/`. No credential prompts — site credentials are provided at runtime via `set_active_project`.
 
 After setup, start a session with:
 
@@ -36,6 +33,18 @@ After setup, start a session with:
 frappe-builder
 ```
 
+See [docs/user/getting-started.md](docs/user/getting-started.md) for the full walkthrough.
+
+## Documentation
+
+- **[docs/index.md](docs/index.md)** — full documentation index (user guides + contributor guides)
+- **[docs/user/getting-started.md](docs/user/getting-started.md)** — install, init, first feature
+- **[docs/contributor/architecture.md](docs/contributor/architecture.md)** — how frappe-builder works internally
+
+## Contributing
+
+See [docs/contributor/architecture.md](docs/contributor/architecture.md) for the design overview, then [docs/contributor/adding-a-gate.md](docs/contributor/adding-a-gate.md) or [docs/contributor/adding-a-tool.md](docs/contributor/adding-a-tool.md) to contribute a gate or tool.
+
 ## Development
 
 See [docs/dev-mode.md](docs/dev-mode.md) for the hot-reload dev workflow.
@@ -46,22 +55,6 @@ npm test           # run all tests
 npm run typecheck  # TypeScript compile check
 ```
 
-## Configuration
-
-frappe-builder requires two config files before starting:
-
-| File | Location | Contents |
-|---|---|---|
-| Global config | `~/.frappe-builder/config.json` | LLM API key, provider |
-| Site credentials | `{project}/.frappe-builder-config.json` | Frappe site URL, API key/secret |
-
-The site credentials file **must** be listed in your project's `.gitignore` before the session will start:
-
-```
-# .gitignore
-.frappe-builder-config.json
-```
-
 ## Upgrading
 
 To update to the latest stable release:

package/config/constants.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared constants — single source of truth for values referenced across multiple modules.
+ * Centralised here to eliminate silent divergence bugs.
+ */
+
+/** Tools that bypass the phase guard entirely and are valid in every phase (FR34). */
+export const ALWAYS_ALLOWED_TOOLS = new Set([
+  "invoke_debugger",
+  "end_debug",
+  "spawn_agent",
+  "get_frappe_docs",
+  "get_library_docs",
+  "get_audit_log",
+  "get_project_status",
+]);
+
+/** Tools that mutate files, run shell commands, or write state.
+ *  Subject to default-mode confirmation and plan-mode blocking. */
+export const WRITE_TOOLS = new Set([
+  "Write", "Edit", "NotebookEdit",
+  "Bash",
+  "bench_execute",
+  "create_component", "complete_component",
+]);
+
+/** File-write tools that trigger quality gate scans. Strict subset of WRITE_TOOLS. */
+export const FILE_WRITE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
+
+/** frappe-builder state directory (relative to project root). */
+export const FB_DIR = ".fb";
+
+/** JSONL chain event log filename inside FB_DIR. */
+export const CHAIN_EVENTS_FILE = "chain_events.jsonl";
+
+/** Planning artifacts subdirectory name (inside feature artifact dir). */
+export const PLANNING_ARTIFACTS_DIR = "planning-artifacts";
+
+/** Implementation artifacts subdirectory name (inside feature artifact dir). */
+export const IMPL_ARTIFACTS_DIR = "implementation-artifacts";
+
+/** Per-step timeout for agent chain subprocesses — 10 minutes. */
+export const CHAIN_STEP_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** Minimum bytes an artifact file must contain to be considered substantive. */
+export const ARTIFACT_MIN_BYTES = 100;

package/config/defaults.ts

@@ -14,6 +14,7 @@ export interface AppConfig {
   defaultMode?: "full" | "quick";  // default feature mode: "quick" skips planning phases
   chainModel?: string;         // model for chain subprocess agents (inherits parent model when unset)
   permissionMode?: PermissionMode; // agent autonomy level: auto | default | plan
+  gateStrictMode?: boolean;    // when true, unimplemented gates block writes instead of warning
 }
 
 export const defaults: AppConfig = {

package/dist/cli.mjs

@@ -15,7 +15,7 @@ import { homedir } from "node:os";
 */
 const cmd = process.argv[2];
 if (cmd === "init") {
-	const { runInit } = await import("./init-CkLSZ_3g.mjs");
+	const { runInit } = await import("./init-DvtJrAiJ.mjs");
 	await runInit();
 	process.exit(0);
 }

package/dist/{init-CkLSZ_3g.mjs → init-DvtJrAiJ.mjs}

@@ -41,8 +41,7 @@ async function runInit(opts = {}) {
 	const written = [];
 	if (gitignoreResult === "patched") written.push(".gitignore (patched with .fb/)");
 	else if (gitignoreResult === "created") written.push(".gitignore (created with .fb/)");
-	await setupContextMode(homeDir);
-	setupMcp2cli(homeDir);
+	setupMcp2cli(homeDir, await setupContextMode(homeDir));
 	setupContext7();
 	if (written.length > 0) {
 		console.log("\nFiles written:");
@@ -51,17 +50,32 @@ async function runInit(opts = {}) {
 	console.log("\nReady. Run: frappe-builder\n");
 }
 /**
+* Resolves the actual path to context-mode's start.mjs after build.
+* Checks candidates in order: repo root, dist/, dist/index, node_modules self-ref.
+* Returns the first path that exists, or the first candidate as a fallback for mcp.json.
+*/
+function resolveContextModeStartScript(extDir) {
+	const candidates = [
+		join(extDir, "start.mjs"),
+		join(extDir, "dist", "start.mjs"),
+		join(extDir, "dist", "index.mjs"),
+		join(extDir, "node_modules", "context-mode", "start.mjs")
+	];
+	return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+/**
 * Installs and configures the context-mode pi MCP extension.
 * Clones https://github.com/mksglu/context-mode into ~/.pi/extensions/context-mode,
 * builds it, and patches ~/.pi/settings/mcp.json with the server entry.
 *
+* Returns the resolved start.mjs path (for use by setupMcp2cli).
 * Non-fatal — failures are logged as warnings, never abort init.
 */
 async function setupContextMode(homeDir) {
 	const extDir = join(homeDir, ".pi", "extensions", "context-mode");
 	const mcpSettingsDir = join(homeDir, ".pi", "settings");
 	const mcpSettingsPath = join(mcpSettingsDir, "mcp.json");
-	const startScript = join(extDir, "node_modules", "context-mode", "start.mjs");
+	const startScript = resolveContextModeStartScript(extDir);
 	console.log("\n[context-mode MCP extension]");
 	if (existsSync(extDir)) console.log("  ✓ context-mode already installed at ~/.pi/extensions/context-mode");
 	else {
@@ -75,7 +89,7 @@ async function setupContextMode(homeDir) {
 		if (clone.status !== 0) {
 			console.warn(`  ⚠ git clone failed: ${clone.stderr?.toString().trim()}`);
 			console.warn("  Skipping context-mode setup. Install manually: https://github.com/mksglu/context-mode");
-			return;
+			return startScript;
 		}
 		const install = spawnSync("npm", ["install"], {
 			cwd: extDir,
@@ -83,7 +97,7 @@ async function setupContextMode(homeDir) {
 		});
 		if (install.status !== 0) {
 			console.warn(`  ⚠ npm install failed: ${install.stderr?.toString().trim()}`);
-			return;
+			return startScript;
 		}
 		const build = spawnSync("npm", ["run", "build"], {
 			cwd: extDir,
@@ -91,7 +105,7 @@ async function setupContextMode(homeDir) {
 		});
 		if (build.status !== 0) {
 			console.warn(`  ⚠ npm run build failed: ${build.stderr?.toString().trim()}`);
-			return;
+			return startScript;
 		}
 		console.log("  ✓ context-mode installed and built");
 	}
@@ -103,7 +117,7 @@ async function setupContextMode(homeDir) {
 	const servers = mcpConfig.mcpServers ?? {};
 	if (servers["context-mode"]) {
 		console.log("  ✓ context-mode already in ~/.pi/settings/mcp.json");
-		return;
+		return startScript;
 	}
 	servers["context-mode"] = {
 		command: "node",
@@ -113,15 +127,17 @@ async function setupContextMode(homeDir) {
 	writeAtomic(mcpSettingsPath, JSON.stringify(mcpConfig, null, 2) + "\n");
 	console.log("  ✓ Added context-mode to ~/.pi/settings/mcp.json");
 	console.log("  Restart pi (or frappe-builder) for context-mode to activate.");
+	return startScript;
 }
 /**
 * Installs the mcp2cli Claude Code skill and bakes the context-mode connection
 * so the agent can call `mcp2cli @context-mode <tool>` without repeating flags.
 *
+* startScript is passed in from setupContextMode so both functions use the same resolved path.
 * Non-fatal — failures are logged as warnings, never abort init.
 */
-function setupMcp2cli(homeDir) {
-	const startScript = join(homeDir, ".pi", "extensions", "context-mode", "node_modules", "context-mode", "start.mjs");
+function setupMcp2cli(homeDir, startScript) {
+	if (!startScript) startScript = resolveContextModeStartScript(join(homeDir, ".pi", "extensions", "context-mode"));
 	console.log("\n[mcp2cli skill + context-mode bake]");
 	if (spawnSync("mcp2cli", ["--version"], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli already installed");
 	else {

package/extensions/agent-chain.ts

@@ -4,12 +4,18 @@ import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { appendFileSync } from "node:fs";
 import { db } from "../state/db.js";
+import {
+  FB_DIR,
+  CHAIN_EVENTS_FILE,
+  PLANNING_ARTIFACTS_DIR,
+  IMPL_ARTIFACTS_DIR,
+  CHAIN_STEP_TIMEOUT_MS,
+  ARTIFACT_MIN_BYTES,
+} from "../config/constants.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AGENTS_DIR = resolve(__dirname, "../agents");
-const CHAIN_EVENTS_PATH = join(".fb", "chain_events.jsonl");
-const STEP_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes per step
-const ARTIFACT_MIN_BYTES = 100;
+const CHAIN_EVENTS_PATH = join(FB_DIR, CHAIN_EVENTS_FILE);
 const PREV_ARTIFACT_MAX_CHARS = 4096;
 
 interface ChainStep {
@@ -75,7 +81,7 @@ const PHASE_TASKS: Record<string, string> = {
 
 function appendChainEvent(entry: Record<string, unknown>): void {
   try {
-    mkdirSync(".fb", { recursive: true });
+    mkdirSync(FB_DIR, { recursive: true });
     appendFileSync(CHAIN_EVENTS_PATH, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n", "utf-8");
   } catch { /* non-fatal */ }
 }
@@ -154,7 +160,7 @@ function runSubprocess(
     proc.stderr?.on("data", (chunk: string) => stderrChunks.push(chunk));
 
     // Hard timeout per step
-    const timer = setTimeout(() => proc.kill("SIGTERM"), STEP_TIMEOUT_MS);
+    const timer = setTimeout(() => proc.kill("SIGTERM"), CHAIN_STEP_TIMEOUT_MS);
 
     proc.on("close", (code) => {
       clearTimeout(timer);
@@ -195,8 +201,8 @@ export async function spawnChain(
     appendChainEvent({ featureId, phase: step.phase, status: "started" });
 
     // Ensure artifact subdirs exist
-    const planningDir = join(artifactDir, "planning-artifacts");
-    const implDir = join(artifactDir, "implementation-artifacts");
+    const planningDir = join(artifactDir, PLANNING_ARTIFACTS_DIR);
+    const implDir = join(artifactDir, IMPL_ARTIFACTS_DIR);
     mkdirSync(planningDir, { recursive: true });
     mkdirSync(implDir, { recursive: true });
 

package/extensions/frappe-gates.ts

@@ -14,6 +14,9 @@ import { getCurrentPhase, db } from "../state/db.js";
 import { appendEntry } from "../state/journal.js";
 import { checkFrappeNative } from "../gates/frappe-native-check.js";
 import type { GateFn, GateContext, GateResult } from "../gates/types.js";
+import { FILE_WRITE_TOOLS as FILE_WRITE_TOOLS_CONST } from "../config/constants.js";
+import { loadConfig } from "../config/loader.js";
+import type { PiPlugin } from "./pi-types.js";
 
 // Adapt frappe-native-check's custom result type to the standard GateResult
 function nativeAdapter(code: string, _context: GateContext): GateResult {
@@ -30,12 +33,30 @@ function nativeAdapter(code: string, _context: GateContext): GateResult {
   };
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyModule = Record<string, any>;
+type AnyModule = Record<string, unknown>;
 
-function tryLoadGate(mod: AnyModule, exportName: string, gateName: string): { name: string; fn: GateFn } | null {
+/**
+ * Loads a gate function from a module.
+ * In strict mode: returns a blocking gate if the export is missing (write is denied).
+ * In default mode: logs a warning and returns null (gate is skipped).
+ */
+function tryLoadGate(
+  mod: AnyModule,
+  exportName: string,
+  gateName: string,
+  strictMode: boolean,
+): { name: string; fn: GateFn } | null {
   const fn = mod[exportName];
   if (typeof fn === "function") return { name: gateName, fn: fn as GateFn };
+  if (strictMode) {
+    return {
+      name: gateName,
+      fn: (_code: string, _ctx: GateContext): GateResult => ({
+        passed: false,
+        violations: [{ reason: `${gateName} gate is not implemented — blocked in strict mode` }],
+      }),
+    };
+  }
   console.warn(`[GATE WARNING: ${gateName} gate not yet implemented — skipping]`);
   return null;
 }
@@ -51,6 +72,9 @@ const GATE_REGISTRY: Array<{ name: string; fn: GateFn }> = [
   { name: "frappe_native", fn: nativeAdapter },
 ];
 
+let gateStrictMode = false;
+try { gateStrictMode = loadConfig().gateStrictMode ?? false; } catch { /* non-fatal — default false */ }
+
 for (const [mod, exportName, gateName] of [
   [permCheckMod, "permissionCheck", "permission_check"],
   [queryCheckMod, "queryCheck", "query_check"],
@@ -58,11 +82,12 @@ for (const [mod, exportName, gateName] of [
   [coverageCheckMod, "coverageCheck", "coverage_check"],
   [styleCheckMod, "styleCheck", "style_check"],
 ] as [AnyModule, string, string][]) {
-  const entry = tryLoadGate(mod, exportName, gateName);
+  const entry = tryLoadGate(mod, exportName, gateName, gateStrictMode);
   if (entry) GATE_REGISTRY.push(entry);
 }
 
-export const FILE_WRITE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
+// FILE_WRITE_TOOLS imported from config/constants.ts — re-exported for consumers
+export const FILE_WRITE_TOOLS = FILE_WRITE_TOOLS_CONST;
 
 export interface BlockedGateResponse {
   blocked: true;
@@ -152,8 +177,7 @@ export function runGates(
   return undefined;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
+export default function (pi: PiPlugin) {
   pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
     return runGates(event.toolName ?? "", event.input ?? {});
   });

package/extensions/frappe-session.ts

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { db } from "../state/db.js";
 import { createFsmAtPhase, type Phase } from "../state/fsm.js";
+import type { PiPlugin } from "./pi-types.js";
 
 /** Maps FSM phases to their specialist names. frappe-debugger is manually invoked (Story 3.5). */
 export const PHASE_TO_SPECIALIST: Record<string, string | null> = {
@@ -315,8 +316,7 @@ export async function handleSessionStart(): Promise<string> {
   }
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
+export default function (pi: PiPlugin) {
   pi.on("session_start", async () => {
     await handleSessionStart();
   });

package/extensions/frappe-state.ts

@@ -3,14 +3,13 @@ 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 type { PiPlugin, PiUiContext } from "./pi-types.js";
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
+export default function (pi: PiPlugin) {
   pi.on("after_tool_call", handleAfterToolCall);
 
   // Session-end guard: warn the agent about untracked features before shutdown.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pi.on("session_shutdown", (_event: any, ctx: any) => {
+  pi.on("session_shutdown", (_event?: unknown, ctx?: PiUiContext) => {
     try {
       const orphans = db
         .prepare(
@@ -23,7 +22,7 @@ export default function (pi: any) {
         const list = orphans.map((f) => `  • ${f.name} [${f.feature_id}] (${f.mode})`).join("\n");
         const warning = `\n⚠ Session ending with ${orphans.length} feature(s) that have no components tracked:\n${list}\n\nCall create_component() + complete_component() before the next session to preserve work history.`;
         try {
-          ctx.ui.setStatus("frappe-builder", `⚠ ${orphans.length} untracked feature(s) — run create_component`);
+          ctx?.ui.setStatus?.("frappe-builder", `⚠ ${orphans.length} untracked feature(s) — run create_component`);
         } catch { /* non-fatal */ }
         console.error(warning);
       }

package/extensions/frappe-tools.ts

@@ -1,21 +1,20 @@
 import { Type } from "@sinclair/typebox";
+import type { PiPlugin } from "./pi-types.js";
 import { startFeature, completeComponent, createComponent } 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 { benchExecute, runTests } from "../tools/bench-tools.js";
 import { frappeQuery } from "../tools/frappe-query-tools.js";
 import { getLibraryDocs, 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.
+// pi.registerTool's execute callback params are enforced at runtime via TypeBox schemas.
+// ToolParams = any avoids noImplicitAny 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) {
+export default function (pi: PiPlugin) {
   pi.registerTool({
     name: "start_feature",
     label: "Start Feature",
@@ -145,24 +144,6 @@ export default function (pi: any) {
     },
   });
 
-  pi.registerTool({
-    name: "scaffold_doctype",
-    label: "Scaffold DocType",
-    description:
-      "NOT YET IMPLEMENTED (Story 4.2 deferred). Returns an error. Do not call — create DocType JSON fixtures directly instead.",
-    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",

package/extensions/frappe-ui.ts

@@ -2,6 +2,7 @@ import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi
 import { db, getCurrentPhase } from "../state/db.js";
 import { loadConfig } from "../config/loader.js";
 import { DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+import type { PiPlugin, PiUiContext } from "./pi-types.js";
 
 interface DashboardState {
   projectId: string | null;
@@ -110,11 +111,10 @@ export function formatFooter(state: FooterState): string {
   return `Project: ${state.projectId} | Feature: ${state.featureName} | Component: ${state.componentId}`;
 }
 
-function renderWidget(ctx: unknown): void {
+function renderWidget(ctx: PiUiContext | undefined): void {
   try {
     const lines = formatDashboard(readDashboardState());
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (ctx as any).ui.setWidget("frappe-builder", lines, { placement: "aboveEditor" });
+    ctx?.ui.setWidget?.("frappe-builder", lines, { placement: "aboveEditor" });
   } catch {
     // Fallback: write to stderr if widget API unavailable
     try {
@@ -155,30 +155,25 @@ export async function handleAfterToolCall(
   return undefined;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pi.on("session_start", (_event: any, ctx: any) => {
+export default function (pi: PiPlugin) {
+  pi.on("session_start", (_event?: unknown, ctx?: PiUiContext) => {
     renderWidget(ctx);
   });
 
   // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pi.on("tool_call", (event: any, ctx: any) => {
+  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }, ctx?: PiUiContext) => {
     try {
       const state = readDashboardState();
       const lines = formatDashboard(state);
       const callLine = `→ ${event.toolName ?? "tool"} [${state.phase}]`;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      (ctx as any).ui.setWidget("frappe-builder", [...lines, callLine], { placement: "aboveEditor" });
+      ctx?.ui.setWidget?.("frappe-builder", [...lines, callLine], { placement: "aboveEditor" });
     } catch {
       handleBeforeToolCall(event.toolName ?? "");
     }
   });
 
   // "tool_result" fires after each tool completes — update the persistent widget.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pi.on("tool_result", (_event: any, ctx: any) => {
+  pi.on("tool_result", (_event?: unknown, ctx?: PiUiContext) => {
     renderWidget(ctx);
   });
 }

package/extensions/frappe-workflow.ts

@@ -3,20 +3,14 @@ import { isToolAllowedInPhase, getValidPhase, type Phase } from "../state/fsm.js
 import { appendEntry } from "../state/journal.js";
 import { loadConfig } from "../config/loader.js";
 import { type PermissionMode, DEFAULT_PERMISSION_MODE } from "../config/defaults.js";
+import { ALWAYS_ALLOWED_TOOLS, WRITE_TOOLS } from "../config/constants.js";
+import type { PiPlugin, PiUiContext } from "./pi-types.js";
 
 // Re-export for use in tests and other modules
 export type { PermissionMode };
 
-/**
- * Tools that mutate files, run shell commands, or write state.
- * These are subject to default-mode confirmation and plan-mode blocking.
- */
-export const WRITE_TOOLS = new Set([
-  "Write", "Edit", "NotebookEdit",
-  "Bash",
-  "scaffold_doctype", "bench_execute",
-  "create_component", "complete_component",
-]);
+// WRITE_TOOLS imported from config/constants.ts — single source of truth
+export { WRITE_TOOLS };
 
 interface BlockedResponse {
   blocked: true;
@@ -50,15 +44,14 @@ function buildBlockedResponse(
  *
  * Never throws — always returns a value or undefined.
  */
-// Tools valid in all phases — never blocked by the phase guard (FR34)
-const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_library_docs", "get_audit_log", "get_project_status"];
+// ALWAYS_ALLOWED_TOOLS imported from config/constants.ts — single source of truth
 
 export function beforeToolCall(
   toolName: string,
   args: Record<string, unknown>
 ): BlockedResponse | undefined {
   // Always-allowed bypass — checked before everything else
-  if (ALWAYS_ALLOWED_TOOLS.includes(toolName)) return undefined;
+  if (ALWAYS_ALLOWED_TOOLS.has(toolName)) return undefined;
 
   const currentPhase = getCurrentPhase() as Phase;
 
@@ -102,8 +95,7 @@ export function beforeToolCall(
 export async function checkPermissionMode(
   toolName: string,
   mode: PermissionMode,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ctx?: any,
+  ctx?: PiUiContext,
 ): Promise<BlockedResponse | undefined> {
   if (!WRITE_TOOLS.has(toolName)) return undefined;
   if (mode === "auto") return undefined;
@@ -121,7 +113,7 @@ export async function checkPermissionMode(
   // default mode: prompt via ctx.ui.input()
   if (ctx) {
     try {
-      const answer: string = await ctx.ui.input(`Allow ${toolName}? (yes/no)`);
+      const answer = await ctx.ui.input?.(`Allow ${toolName}? (yes/no)`);
       if (!["yes", "y"].includes(answer?.toLowerCase?.() ?? "")) {
         return {
           blocked: true,
@@ -139,10 +131,8 @@ export async function checkPermissionMode(
   return undefined;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export default function (pi: any) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pi.on("tool_call", async (event: { toolName?: string; input?: Record<string, unknown> }, ctx: any) => {
+export default function (pi: PiPlugin) {
+  pi.on("tool_call", async (event: { toolName?: string; input?: Record<string, unknown> }, ctx?: PiUiContext) => {
     const toolName = event.toolName ?? "";
 
     // Phase guard

package/extensions/pi-types.ts

@@ -0,0 +1,53 @@
+import type { AfterToolCallContext, AfterToolCallResult } from "@mariozechner/pi-agent-core";
+
+/** Minimal structural type for the pi event context — covers all current usages.
+ *  Methods are optional because the pi API is unversioned and tests use partial mocks.
+ *  All call sites wrap invocations in try-catch or use optional chaining. */
+export interface PiUiContext {
+  ui: Partial<{
+    setWidget(name: string, lines: string[], options?: { placement?: string }): void;
+    setStatus(name: string, message: string): void;
+    notify(message: string, severity: string): void;
+    input(prompt: string): Promise<string>;
+  }>;
+}
+
+/** Structural type for the `pi` plugin object passed to each extension's default export.
+ *  Derived from observed pi-agent-core v0.62.0 behaviour; no published schema exists. */
+export interface PiPlugin {
+  on(event: "session_start", handler: (event?: unknown, ctx?: PiUiContext) => void | Promise<void>): void;
+  on(event: "session_shutdown", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "tool_call",
+    handler: (
+      event: { toolName?: string; input?: Record<string, unknown> },
+      ctx?: PiUiContext,
+    ) => unknown,
+  ): void;
+  on(event: "tool_result", handler: (event?: unknown, ctx?: PiUiContext) => void): void;
+  on(
+    event: "after_tool_call",
+    handler: (
+      ctx: AfterToolCallContext,
+      signal?: AbortSignal,
+    ) => AfterToolCallResult | undefined | Promise<AfterToolCallResult | undefined>,
+  ): void;
+  registerTool(definition: PiToolDefinition): void;
+  registerCommand?: (name: string, definition: PiCommandDefinition) => void;
+}
+
+export interface PiToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (toolCallId: string, params: unknown) => Promise<{
+    content: Array<{ type: string; text: string }>;
+    details?: unknown;
+  }>;
+}
+
+export interface PiCommandDefinition {
+  description: string;
+  handler: (args: string, ctx: Record<string, unknown>) => Promise<string>;
+}

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.26",
+  "version": "1.1.0-dev.28",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {
     "frappe-builder": "./dist/cli.mjs"
   },
   "pi": {
-    "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
     "extensions": [
       "./extensions/frappe-session.ts",
       "./extensions/frappe-state.ts",

package/state/fsm.ts

@@ -1,4 +1,5 @@
 import { createMachine, state, transition } from "robot3";
+import { ALWAYS_ALLOWED_TOOLS } from "../config/constants.js";
 
 export type Phase =
   | "idle"
@@ -41,10 +42,14 @@ function buildMachineStates() {
 type FsmPhase = "idle" | "implementation" | "testing" | "documentation";
 const FSM_PHASES = new Set<string>(["idle", "implementation", "testing", "documentation"]);
 
+function isFsmPhase(p: string): p is FsmPhase {
+  return FSM_PHASES.has(p);
+}
+
 /** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay.
  *  Non-FSM phases (chain_running, requirements, architecture, planning) fall back to idle. */
 export function createFsmAtPhase(phase: Phase) {
-  const fsmPhase: FsmPhase = FSM_PHASES.has(phase) ? (phase as FsmPhase) : "idle";
+  const fsmPhase: FsmPhase = isFsmPhase(phase) ? phase : "idle";
   return createMachine(fsmPhase, buildMachineStates());
 }
 
@@ -57,21 +62,13 @@ const TOOL_PHASE_MAP: Record<string, Phase | Phase[] | "any"> = {
   start_feature: "idle",          // blocked in chain_running to prevent double-start
   create_component: ["planning", "implementation"],
   complete_component: "implementation",
-  scaffold_doctype: "implementation",
   run_tests: "testing",
   get_project_status: "any",
   frappe_query: "any",
   bench_execute: "any",
 };
 
-/** Always-allowed tools that bypass phase guard entirely. */
-const ALWAYS_ALLOWED_TOOLS = new Set([
-  "invoke_debugger",
-  "end_debug",
-  "spawn_agent",
-  "get_project_status",
-  "get_frappe_docs",
-]);
+// ALWAYS_ALLOWED_TOOLS imported from config/constants.ts — single source of truth
 
 /** Returns true if toolName is allowed to run in the given phase. Unknown tools are always allowed. */
 export function isToolAllowedInPhase(toolName: string, phase: Phase): boolean {

package/state/schema.ts

@@ -70,6 +70,11 @@ export function migrateSchema(db: Database): void {
     "ALTER TABLE sessions ADD COLUMN api_secret TEXT",
   ];
   for (const sql of alters) {
-    try { db.exec(sql); } catch { /* column already exists — safe to ignore */ }
+    try {
+      db.exec(sql);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!msg.includes("duplicate column name")) throw err;
+    }
   }
 }

package/tools/agent-tools.ts

@@ -1,4 +1,12 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConfig } from "../config/loader.js";
+import { CHAIN_STEP_TIMEOUT_MS } from "../config/constants.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = resolve(__dirname, "../agents");
 
 export interface SpawnAgentArgs {
   skill: string;
@@ -17,11 +25,69 @@ export interface SpawnAgentResult {
 }
 
 /**
- * Stub: no sub-agent spawn API found in @mariozechner/pi-agent-core at this version.
- * Returns spawned status with null result — replace body with actual API when available.
+ * Spawns an isolated `pi` subprocess for the given skill.
+ * The sub-agent gets its own context window. Reads system prompt from agents/{skill}.md.
+ * Uses `reason` as the task prompt. Times out after CHAIN_STEP_TIMEOUT_MS.
  */
-async function doSpawn(skill: string, trigger: string): Promise<SpawnAgentResult> {
-  return { status: "spawned", skill, trigger, result: null };
+async function doSpawn(skill: string, trigger: string, reason: string): Promise<SpawnAgentResult> {
+  const agentFile = join(AGENTS_DIR, `${skill}.md`);
+  let systemPrompt: string;
+  try {
+    systemPrompt = readFileSync(agentFile, "utf-8");
+  } catch {
+    return {
+      status: "disabled",
+      skill,
+      trigger,
+      error: `No agent definition found for skill "${skill}" (expected ${agentFile})`,
+    };
+  }
+
+  return new Promise((resolvePromise) => {
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-extensions",
+      "--append-system-prompt", systemPrompt,
+      reason,
+    ];
+
+    const proc = spawn("pi", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    const stderrChunks: string[] = [];
+    proc.stderr?.setEncoding("utf-8");
+    proc.stderr?.on("data", (chunk: string) => stderrChunks.push(chunk));
+
+    const timer = setTimeout(() => proc.kill("SIGTERM"), CHAIN_STEP_TIMEOUT_MS);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolvePromise({ status: "spawned", skill, trigger });
+      } else {
+        const stderr = stderrChunks.slice(-20).join("").slice(-2000);
+        resolvePromise({
+          status: "disabled",
+          skill,
+          trigger,
+          error: `Agent "${skill}" exited with code ${code ?? 1}${stderr ? `: ${stderr}` : ""}`,
+        });
+      }
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolvePromise({
+        status: "disabled",
+        skill,
+        trigger,
+        error: `Failed to spawn pi process: ${err.message}`,
+      });
+    });
+  });
 }
 
 /**
@@ -56,5 +122,5 @@ export async function spawnAgent(args: SpawnAgentArgs): Promise<SpawnAgentResult
     return { status: "rejected", skill: args.skill, trigger: args.trigger };
   }
 
-  return doSpawn(args.skill, args.trigger);
+  return doSpawn(args.skill, args.trigger, args.reason);
 }

package/tools/bench-tools.ts

@@ -52,12 +52,8 @@ export async function benchExecute({
   }
 }
 
-/** Stub — full implementation deferred (Story 4.2). */
-export function scaffoldDoctype(_args: unknown): { error: string } {
-  return { error: "scaffold_doctype: not yet implemented — Story 4.2 (deferred)" };
-}
-
-/** Stub — full implementation Epic 6. */
-export function runTests(_args: unknown): { error: string } {
-  return { error: "run_tests: not yet implemented — Epic 6" };
+/** @NOT_IMPLEMENTED Epic 6 (deferred). Use bench_execute with 'bench run-tests --app {app}' instead. */
+export function runTests(_args: unknown): { error: string; _stub: true } {
+  console.warn("[bench-tools] run_tests called but not yet implemented (Epic 6)");
+  return { error: "run_tests: not yet implemented — Epic 6", _stub: true };
 }

package/tools/frappe-query-tools.ts

@@ -17,6 +17,41 @@ interface SessionCredentials {
   api_secret: string | null;
 }
 
+/**
+ * Retries a fetch on transient server errors (5xx) and rate limiting (429).
+ * Uses linear backoff (1s × attempt). Passes through 4xx client errors immediately.
+ */
+async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3): Promise<Response> {
+  let lastResponse: Response | undefined;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const response = await fetch(url, options);
+    if (response.ok || (response.status >= 400 && response.status < 500 && response.status !== 429)) {
+      return response;
+    }
+    lastResponse = response;
+    if (attempt < maxRetries) {
+      await new Promise((r) => setTimeout(r, 1000 * attempt));
+    }
+  }
+  return lastResponse!;
+}
+
+/**
+ * Builds and validates the Frappe REST resource URL.
+ * Strips trailing slash from siteUrl, uses URL constructor for validation.
+ * Returns null if siteUrl is not a valid URL.
+ */
+function buildResourceUrl(siteUrl: string, doctype: string, params: URLSearchParams): string | null {
+  try {
+    const base = siteUrl.replace(/\/$/, "");
+    const url = new URL(`${base}/api/resource/${encodeURIComponent(doctype)}`);
+    url.search = params.toString();
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Queries Frappe data via direct REST API call using credentials stored in the
  * active session (set via set_active_project).
@@ -41,8 +76,12 @@ export async function frappeQuery({ doctype, filters }: FrappeQueryArgs): Promis
       params.set("filters", JSON.stringify(filters));
     }
 
-    const url = `${session.site_url}/api/resource/${encodeURIComponent(doctype)}?${params.toString()}`;
-    const response = await fetch(url, {
+    const url = buildResourceUrl(session.site_url, doctype, params);
+    if (!url) {
+      return { error: `Invalid site_url: "${session.site_url}". Must be a valid URL (e.g. http://site1.localhost).` };
+    }
+
+    const response = await fetchWithRetry(url, {
       headers: {
         Authorization: `token ${session.api_key}:${session.api_secret}`,
         "Content-Type": "application/json",