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

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

package/AGENTS.md

@@ -17,7 +17,7 @@ You are Frappe-Nexus, the primary orchestrator for frappe-builder — a Frappe/E
 
 | 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())"` |
+| 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"]'` |

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-dY-MHOgS.mjs");
+	const { runInit } = await import("./init-Gp1MgJD2.mjs");
 	await runInit();
 	process.exit(0);
 }

package/dist/{init-dY-MHOgS.mjs → init-Gp1MgJD2.mjs}

@@ -148,6 +148,7 @@ async function runInit(opts = {}) {
 	else skipped.push(".gitignore (entry already present)");
 	await setupContextMode(homeDir);
 	setupMcp2cli(homeDir);
+	setupContext7();
 	console.log("\nFiles written:");
 	for (const f of written) console.log(`  ✓ ${f}`);
 	if (skipped.length > 0) {
@@ -232,6 +233,20 @@ async function setupContextMode(homeDir) {
 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",
@@ -262,10 +277,51 @@ function setupMcp2cli(homeDir) {
 		"--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>");
+	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>");
+}
+/**
+* Bakes the context7 cloud MCP server as @context7 and installs the
+* netresearch context7 Claude Code skill for general-purpose library research.
+*
+* Non-fatal — failures are logged as warnings, never abort init.
+*/
+function setupContext7() {
+	console.log("\n[context7 MCP bake + skill]");
+	if (spawnSync("mcp2cli", [
+		"bake",
+		"show",
+		"context7"
+	], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli @context7 already baked");
+	else {
+		const bakeCreate = spawnSync("mcp2cli", [
+			"bake",
+			"create",
+			"context7",
+			"--mcp",
+			"https://mcp.context7.com/mcp"
+		], { stdio: "pipe" });
+		if (bakeCreate.status !== 0) {
+			console.warn(`  ⚠ context7 bake failed: ${bakeCreate.stderr?.toString().trim()}`);
+			console.warn("  Install mcp2cli first: uv tool install mcp2cli");
+		} else console.log("  ✓ mcp2cli @context7 baked — agent can now call: mcp2cli @context7 resolve-library-id");
+	}
+	spawnSync("npx", [
+		"skills",
+		"add",
+		"knowsuchagency/mcp2cli",
+		"--skill",
+		"mcp2cli"
+	], { stdio: "pipe" });
+	if (spawnSync("claude", [
+		"plugin",
+		"marketplace",
+		"add",
+		"netresearch/claude-code-marketplace"
+	], { stdio: "pipe" }).status !== 0) {
+		console.warn("  ⚠ context7 skill install failed (netresearch marketplace unavailable)");
+		console.warn("  Install manually: claude plugin marketplace add netresearch/claude-code-marketplace");
+	} else console.log("  ✓ context7 Claude Code skill installed — use /context7 for library research");
 }
 //#endregion
 export { runInit };

package/extensions/frappe-tools.ts

@@ -6,7 +6,7 @@ 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";
+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
@@ -212,12 +212,31 @@ export default function (pi: any) {
     },
   });
 
-  // 9th tool — outside the 8 core Frappe-semantic tools; bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  // General-purpose library docs tool via context7 — bypasses phase guard via ALWAYS_ALLOWED_TOOLS
+  pi.registerTool({
+    name: "get_library_docs",
+    label: "Get Library Docs",
+    description:
+      "Retrieves up-to-date documentation for any library via context7 MCP (React, Next.js, Frappe, ERPNext, Python, etc.). Raw web content never enters the LLM context. Valid in any phase.",
+    parameters: Type.Object({
+      query: Type.String({ description: "What you want to know (e.g. 'how do hooks work', 'useEffect cleanup')" }),
+      library: Type.Optional(Type.String({ description: "Library name (e.g. 'frappe', 'react', 'nextjs'). Defaults to 'frappe'." })),
+    }),
+    execute: async (_toolCallId: string, params: ToolParams) => {
+      const result = await getLibraryDocs(params);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: result,
+      };
+    },
+  });
+
+  // Frappe-specific alias kept for backwards compatibility
   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)",
+      "Retrieves Frappe/ERPNext documentation via context7. Alias for get_library_docs with library='frappe'. Valid in any phase.",
     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')" })),

package/extensions/frappe-workflow.ts

@@ -51,7 +51,7 @@ 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_audit_log", "get_project_status"];
+const ALWAYS_ALLOWED_TOOLS = ["invoke_debugger", "end_debug", "spawn_agent", "get_frappe_docs", "get_library_docs", "get_audit_log", "get_project_status"];
 
 export function beforeToolCall(
   toolName: string,

package/package.json

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

package/tools/frappe-context7.ts

@@ -1,70 +1,66 @@
 import { execa } from "execa";
 
-export interface FrappeDocsArgs {
-  topic: string;
-  version?: string;
+export interface GetLibraryDocsArgs {
+  query: string;
+  library?: string;
 }
 
-export interface FrappeDocsResult {
+export interface GetLibraryDocsResult {
   snippet?: string;
-  topic?: string;
+  query?: string;
+  library?: string;
   source?: "context7";
   error?: string;
   fallback?: string;
 }
 
-const CONTEXT7_UNAVAILABLE: FrappeDocsResult = {
+const CONTEXT7_UNAVAILABLE: GetLibraryDocsResult = {
   error: "context7 unavailable",
-  fallback: "search frappe.io manually",
+  fallback: "search library docs manually",
 };
 
 /**
- * Retrieves compressed Frappe/ERPNext documentation via context7 MCP subprocess.
- * Raw web content never enters the LLM context — only the compressed snippet is returned.
+ * Retrieves up-to-date documentation via context7 MCP for any library.
+ * Raw web content never enters the LLM context — only the snippet is returned.
  * Returns a graceful error on any failure (timeout, MCP unavailable, not found).
  * Never throws.
  *
  * Flow:
- *   1. Resolve Frappe library ID via context7 resolve-library-id
- *   2. Fetch compressed docs for topic via context7 get-library-docs
+ *   1. Resolve library ID via context7 resolve-library-id
+ *   2. Fetch docs for query via context7 query-docs
  */
-export async function getFrappeDocs({ topic, version }: FrappeDocsArgs): Promise<FrappeDocsResult> {
+export async function getLibraryDocs({ query, library = "frappe" }: GetLibraryDocsArgs): Promise<GetLibraryDocsResult> {
   try {
-    // Step 1: resolve Frappe library ID
-    const libraryName = version ? `frappe@${version}` : "frappe";
+    // Step 1: resolve library ID
     const resolveResult = await execa(
       "mcp2cli",
-      ["context7", "resolve-library-id", "--libraryName", libraryName],
+      ["@context7", "resolve-library-id", "--library-name", library, "--query", query],
       { timeout: 10_000 }
     );
 
-    let libraryId: string;
-    try {
-      const parsed = JSON.parse(resolveResult.stdout) as { libraryId?: string };
-      if (!parsed.libraryId) return CONTEXT7_UNAVAILABLE;
-      libraryId = parsed.libraryId;
-    } catch {
-      return CONTEXT7_UNAVAILABLE;
-    }
+    // Response is plain text listing — extract first library ID via regex
+    const idMatch = resolveResult.stdout.match(/Context7-compatible library ID:\s*(\S+)/);
+    if (!idMatch?.[1]) return CONTEXT7_UNAVAILABLE;
+    const libraryId = idMatch[1];
 
-    // Step 2: fetch compressed docs for topic (~90% token reduction via 5000 token limit)
+    // Step 2: fetch docs for the query
     const docsResult = await execa(
       "mcp2cli",
-      [
-        "context7",
-        "get-library-docs",
-        "--libraryId", libraryId,
-        "--topic", topic,
-        "--tokens", "5000",
-      ],
+      ["@context7", "query-docs", "--library-id", libraryId, "--query", query],
       { timeout: 15_000 }
     );
 
     const snippet = docsResult.stdout?.trim();
     if (!snippet) return CONTEXT7_UNAVAILABLE;
 
-    return { snippet, topic, source: "context7" };
+    return { snippet, query, library, source: "context7" };
   } catch {
     return CONTEXT7_UNAVAILABLE;
   }
 }
+
+/** Backwards-compatible alias for Frappe-specific doc lookups. */
+export async function getFrappeDocs({ topic, version }: { topic: string; version?: string }): Promise<GetLibraryDocsResult> {
+  const library = version ? `frappe@${version}` : "frappe";
+  return getLibraryDocs({ query: topic, library });
+}