frappe-builder 1.1.0-dev.19 → 1.1.0-dev.22

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-28T11:15:20.689Z
+updated_at: 2026-03-28T14:14:28.658Z
 
 components:
   - id: final-comp
     sort_order: 0
     status: complete
-    completed_at: 2026-03-28T11:15:20.689Z
+    completed_at: 2026-03-28T14:14:28.658Z
 
 progress:
   done: 1

package/AGENTS.md

@@ -13,18 +13,19 @@ You are Frappe-Nexus, the primary orchestrator for frappe-builder — a Frappe/E
 
 ## Context Window Protection (MANDATORY)
 
-**Always use context-mode MCP tools.** Raw tool output floods the context window and degrades performance. This is non-negotiable.
+**Always use context-mode via mcp2cli.** Pi has no native MCP support — call context-mode tools by running `mcp2cli @context-mode <tool>` in a Bash command. Raw output floods the context window and degrades performance. This is non-negotiable.
 
-| Instead of… | Use… |
+| Instead of… | Run this Bash command… |
 |---|---|
-| Reading a file to analyse it | `ctx_execute_file(path, ...)` |
-| Running bash commands with long output | `ctx_execute(language: "shell", code: "...")` |
-| Searching the codebase | `ctx_batch_execute(commands, queries)` or `ctx_search(queries)` |
-| Fetching a URL | `ctx_fetch_and_index(url)` then `ctx_search(...)` |
+| Reading a file to analyse it | `mcp2cli @context-mode ctx_execute_file --path /abs/path --language python --code "print(FILE_CONTENT)"` |
+| Running bash commands with long output | `mcp2cli @context-mode ctx_execute --language shell --code "your-command"` |
+| Searching the codebase | `mcp2cli @context-mode ctx_batch_execute --commands '["grep -r X ."]' --queries '["what does X do"]'` |
+| Follow-up questions after indexing | `mcp2cli @context-mode ctx_search --queries '["question 1", "question 2"]'` |
+| Fetching a URL | `mcp2cli @context-mode ctx_fetch_and_index --url https://...` then `ctx_search` |
 
-**Only use direct Read/Bash when you are about to Edit the file** — the Edit tool needs file content in context. All other reads must go through context-mode.
+**Only use direct Read when you are about to Edit the file** — the Edit tool needs file content in context. All other reads must go through `mcp2cli @context-mode`.
 
-After every `ctx_batch_execute` or `ctx_execute`, summarise findings in 3–5 bullet points. Never dump raw output into your response.
+After every context-mode call, summarise findings in 3–5 bullet points. Never dump raw output into your response.
 
 ## Constraints
 - Never auto-pilot: every significant action must be visible to the developer

package/dist/cli.mjs

@@ -14,7 +14,7 @@ import { existsSync } from "node:fs";
 */
 const cmd = process.argv[2];
 if (cmd === "init") {
-	const { runInit } = await import("./init-BYJy3ztn.mjs");
+	const { runInit } = await import("./init-BUkSYk2l.mjs");
 	await runInit();
 	process.exit(0);
 }

package/dist/{init-BYJy3ztn.mjs → init-BUkSYk2l.mjs}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
@@ -57,7 +58,8 @@ function patchGitignore(projectRoot, entry) {
 }
 async function runInit(opts = {}) {
 	const projectRoot = opts.projectRoot ?? process.cwd();
-	const globalConfigDir = join(homedir(), ".frappe-builder");
+	const homeDir = homedir();
+	const globalConfigDir = join(homeDir, ".frappe-builder");
 	const globalConfigPath = join(globalConfigDir, "config.json");
 	const projectConfigPath = join(projectRoot, ".frappe-builder-config.json");
 	console.log("\n=== frappe-builder Setup ===\n");
@@ -144,6 +146,8 @@ async function runInit(opts = {}) {
 	if (gitignoreResult === "patched") written.push(".gitignore (patched)");
 	else if (gitignoreResult === "created") written.push(".gitignore (created)");
 	else skipped.push(".gitignore (entry already present)");
+	await setupContextMode(homeDir);
+	setupMcp2cli(homeDir);
 	console.log("\nFiles written:");
 	for (const f of written) console.log(`  ✓ ${f}`);
 	if (skipped.length > 0) {
@@ -155,5 +159,125 @@ async function runInit(opts = {}) {
 function printCancelled() {
 	console.log("\nSetup cancelled. No files were written.\n");
 }
+/**
+* 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.
+*
+* 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");
+	console.log("\n[context-mode MCP extension]");
+	if (existsSync(extDir)) console.log("  ✓ context-mode already installed at ~/.pi/extensions/context-mode");
+	else {
+		console.log("  context-mode not found — installing (requires git + Node.js)...");
+		mkdirSync(join(homeDir, ".pi", "extensions"), { recursive: true });
+		const clone = spawnSync("git", [
+			"clone",
+			"https://github.com/mksglu/context-mode.git",
+			extDir
+		], { stdio: "pipe" });
+		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;
+		}
+		const install = spawnSync("npm", ["install"], {
+			cwd: extDir,
+			stdio: "pipe"
+		});
+		if (install.status !== 0) {
+			console.warn(`  ⚠ npm install failed: ${install.stderr?.toString().trim()}`);
+			return;
+		}
+		const build = spawnSync("npm", ["run", "build"], {
+			cwd: extDir,
+			stdio: "pipe"
+		});
+		if (build.status !== 0) {
+			console.warn(`  ⚠ npm run build failed: ${build.stderr?.toString().trim()}`);
+			return;
+		}
+		console.log("  ✓ context-mode installed and built");
+	}
+	mkdirSync(mcpSettingsDir, { recursive: true });
+	let mcpConfig = {};
+	if (existsSync(mcpSettingsPath)) try {
+		mcpConfig = JSON.parse(readFileSync(mcpSettingsPath, "utf-8"));
+	} catch {}
+	const servers = mcpConfig.mcpServers ?? {};
+	if (servers["context-mode"]) {
+		console.log("  ✓ context-mode already in ~/.pi/settings/mcp.json");
+		return;
+	}
+	servers["context-mode"] = {
+		command: "node",
+		args: [startScript]
+	};
+	mcpConfig.mcpServers = servers;
+	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.");
+}
+/**
+* Installs the mcp2cli Claude Code skill and bakes the context-mode connection
+* so the agent can call `mcp2cli @context-mode <tool>` without repeating flags.
+*
+* 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");
+	console.log("\n[mcp2cli skill + context-mode bake]");
+	if (spawnSync("mcp2cli", ["--version"], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli already installed");
+	else {
+		console.log("  Installing mcp2cli...");
+		if (spawnSync("uv", [
+			"tool",
+			"install",
+			"mcp2cli"
+		], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli installed via uv");
+		else if (spawnSync("pip", ["install", "mcp2cli"], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli installed via pip");
+		else {
+			console.warn("  ⚠ mcp2cli install failed (tried uv and pip)");
+			console.warn("  Install manually: uv tool install mcp2cli");
+		}
+	}
+	const skillAdd = spawnSync("npx", [
+		"skills",
+		"add",
+		"knowsuchagency/mcp2cli",
+		"--skill",
+		"mcp2cli"
+	], { stdio: "pipe" });
+	if (skillAdd.status !== 0) {
+		console.warn(`  ⚠ mcp2cli skill install failed: ${skillAdd.stderr?.toString().trim()}`);
+		console.warn("  Install manually: npx skills add knowsuchagency/mcp2cli --skill mcp2cli");
+	} else console.log("  ✓ mcp2cli skill installed");
+	if (spawnSync("mcp2cli", [
+		"bake",
+		"show",
+		"context-mode"
+	], { stdio: "pipe" }).status === 0) {
+		console.log("  ✓ mcp2cli @context-mode already baked");
+		return;
+	}
+	if (!existsSync(startScript)) {
+		console.warn("  ⚠ context-mode start.mjs not found — skipping bake (run init again after context-mode installs)");
+		return;
+	}
+	const bakeCreate = spawnSync("mcp2cli", [
+		"bake",
+		"create",
+		"context-mode",
+		"--mcp-stdio",
+		`node ${startScript}`
+	], { stdio: "pipe" });
+	if (bakeCreate.status !== 0) console.warn(`  ⚠ mcp2cli bake failed: ${bakeCreate.stderr?.toString().trim()}`);
+	else console.log("  ✓ mcp2cli @context-mode baked — agent can now call: mcp2cli @context-mode <tool>");
+}
 //#endregion
 export { runInit };

package/extensions/frappe-session.ts

@@ -239,8 +239,9 @@ export function buildStateInjection(ctx: SessionContext): string {
     `Progress: ${progress}`,
     `Last action: ${ctx.lastTool ?? "none"}`,
     "======================================",
-    "CONTEXT WINDOW RULE: Use ctx_execute_file / ctx_execute / ctx_batch_execute / ctx_search for ALL",
-    "reads and searches. Only use Read directly when you are about to Edit that file.",
+    "CONTEXT WINDOW RULE: Run `mcp2cli @context-mode <tool>` for ALL reads and searches.",
+    "Use ctx_execute_file, ctx_execute, ctx_batch_execute, ctx_search via mcp2cli.",
+    "Only use Read directly when you are about to Edit that file.",
   );
   return lines.join("\n");
 }

package/extensions/frappe-tools.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import { startFeature, completeComponent } from "../tools/feature-tools.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";
@@ -54,6 +54,26 @@ export default function (pi: any) {
     },
   });
 
+  pi.registerTool({
+    name: "create_component",
+    label: "Create Component",
+    description:
+      "Registers a planned unit of work as an in-progress component for the active feature. Call this BEFORE writing any code — one component per logical deliverable. Updates sprint-status.yaml and sets the active component on the session. Valid in planning and implementation phases.",
+    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', 'po-doctype')" }),
+      description: Type.Optional(Type.String({ description: "Short description of what this component implements" })),
+      sortOrder: Type.Optional(Type.Number({ description: "Order within the feature (lower = earlier)" })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = createComponent(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",
@@ -126,7 +146,7 @@ export default function (pi: any) {
     name: "scaffold_doctype",
     label: "Scaffold DocType",
     description:
-      "Creates a new Frappe DocType via bench. Valid only in the 'implementation' phase. (Story 4.2 deferred)",
+      "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')" }),
@@ -144,7 +164,7 @@ export default function (pi: any) {
     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)",
+      "NOT YET IMPLEMENTED (Epic 6 deferred). Returns an error. Use bench_execute with 'bench run-tests --app {app}' instead.",
     parameters: Type.Object({
       featureId: Type.Optional(Type.String({ description: "Feature ID to scope tests (optional)" })),
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.19",
+  "version": "1.1.0-dev.22",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {