frappe-builder 1.1.0-dev.18 → 1.1.0-dev.21

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:05:52.239Z
+updated_at: 2026-03-28T14:09:32.555Z
 
 components:
   - id: final-comp
     sort_order: 0
     status: complete
-    completed_at: 2026-03-28T11:05:52.239Z
+    completed_at: 2026-03-28T14:09:32.555Z
 
 progress:
   done: 1

package/AGENTS.md

@@ -11,6 +11,22 @@ You are Frappe-Nexus, the primary orchestrator for frappe-builder — a Frappe/E
 - Surface state clearly: active project, feature, phase, progress — never work silently
 - Run quality gates before marking any feature complete
 
+## Context Window Protection (MANDATORY)
+
+**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… | Run this Bash command… |
+|---|---|
+| Reading a file to analyse it | `mcp2cli @context-mode ctx_execute_file --path /abs/path --language python --code "print(open('/abs/path').read())"` |
+| 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 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 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
 - Always prefer Frappe built-ins over custom solutions

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-dY-MHOgS.mjs");
 	await runInit();
 	process.exit(0);
 }

package/dist/{init-BYJy3ztn.mjs → init-dY-MHOgS.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,113 @@ 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]");
+	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()}`);
+		console.warn("  Install mcp2cli first: pip install mcp2cli");
+	} else console.log("  ✓ mcp2cli @context-mode baked — agent can now call: mcp2cli @context-mode <tool>");
+}
 //#endregion
 export { runInit };

package/extensions/frappe-session.ts

@@ -238,7 +238,10 @@ export function buildStateInjection(ctx: SessionContext): string {
     `Phase: ${ctx.phase}`,
     `Progress: ${progress}`,
     `Last action: ${ctx.lastTool ?? "none"}`,
-    "======================================"
+    "======================================",
+    "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.18",
+  "version": "1.1.0-dev.21",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {

package/tools/context-sandbox.ts

@@ -1,9 +1,14 @@
 /**
- * Context-mode sandbox routing for Frappe tool output.
+ * Output truncation guard for Frappe tool output.
  *
- * Context-mode MCP tools are accessible to the LLM session but not callable
- * directly from extension code. Until an HTTP endpoint is discoverable,
- * routeThroughContextMode applies the 8K truncation fallback.
+ * Context-mode MCP tools (ctx_execute, ctx_search, etc.) are only callable by
+ * the LLM agent — NOT from Node.js extension code. There is no HTTP endpoint
+ * to route to from here.
+ *
+ * This module is a last-resort truncation guard for bench_execute and
+ * frappe_query outputs that would otherwise flood the context window.
+ * The agent is instructed via AGENTS.md to use ctx_execute / ctx_batch_execute
+ * proactively instead of relying on this fallback.
  *
  * NFR17: truncation is NEVER silent — warning is always prepended.
  */
@@ -11,12 +16,11 @@
 const CHAR_LIMIT = 8192 * 4; // ~8K tokens at 4 chars/token
 
 /**
- * Routes raw tool output through the context-mode sandbox.
- * Falls back to 8K truncation with a visible warning if sandbox unavailable.
+ * Applies the 8K truncation guard to raw tool output.
+ * Named routeThroughContextMode for API compatibility with existing callers.
  * Never throws.
  */
 export async function routeThroughContextMode(raw: string): Promise<string> {
-  // TODO: wire to context-mode MCP HTTP endpoint when discoverable from extension code
   return applyTruncationFallback(raw);
 }