frappe-builder 1.1.0-dev.10

package/_bmad/core/tasks/bmad-create-prd/steps-c/step-12-complete.md

@@ -0,0 +1,115 @@
+# Step 12: Workflow Completion
+
+**Final Step - Complete the PRD**
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ THIS IS A FINAL STEP - Workflow completion required
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🛑 NO content generation - this is a wrap-up step
+- 📋 FINALIZE document and update workflow status
+- 💬 FOCUS on completion, validation options, and next steps
+- 🎯 UPDATE workflow status files with completion information
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Update the main workflow status file with completion information (if exists)
+- 📖 Offer validation workflow options to user
+- 🚫 DO NOT load additional steps after this one
+
+## TERMINATION STEP PROTOCOLS:
+
+- This is a FINAL step - workflow completion required
+- Update workflow status file with finalized document
+- Suggest validation and next workflow steps
+- Mark workflow as complete in status tracking
+
+## CONTEXT BOUNDARIES:
+
+- Complete and polished PRD document is available from all previous steps
+- Workflow frontmatter shows all completed steps including polish
+- All collaborative content has been generated, saved, and optimized
+- Focus on completion, validation options, and next steps
+
+## YOUR TASK:
+
+Complete the PRD workflow, update status files, offer validation options, and suggest next steps for the project.
+
+## WORKFLOW COMPLETION SEQUENCE:
+
+### 1. Announce Workflow Completion
+
+Inform user that the PRD is complete and polished:
+- Celebrate successful completion of comprehensive PRD
+- Summarize all sections that were created
+- Highlight that document has been polished for flow and coherence
+- Emphasize document is ready for downstream work
+
+### 2. Workflow Status Update
+
+Update the main workflow status file if there is one:
+
+- Check workflow configuration for a status file (if one exists)
+- Update workflow_status["prd"] = "{outputFile}"
+- Save file, preserving all comments and structure
+- Mark current timestamp as completion time
+
+### 3. Validation Workflow Options
+
+Offer validation workflows to ensure PRD is ready for implementation:
+
+**Available Validation Workflows:**
+
+**Option 1: Check Implementation Readiness** (`skill:bmad-check-implementation-readiness`)
+- Validates PRD has all information needed for development
+- Checks epic coverage completeness
+- Reviews UX alignment with requirements
+- Assesses epic quality and readiness
+- Identifies gaps before architecture/design work begins
+
+**When to use:** Before starting technical architecture or epic breakdown
+
+**Option 2: Skip for Now**
+- Proceed directly to next workflows (architecture, UX, epics)
+- Validation can be done later if needed
+- Some teams prefer to validate during architecture reviews
+
+### 4. Suggest Next Workflows
+
+PRD complete. Invoke the `bmad-help` skill.
+
+### 5. Final Completion Confirmation
+
+- Confirm completion with user and summarize what has been accomplished
+- Document now contains: Executive Summary, Success Criteria, User Journeys, Domain Requirements (if applicable), Innovation Analysis (if applicable), Project-Type Requirements, Functional Requirements (capability contract), Non-Functional Requirements, and has been polished for flow and coherence
+- Ask if they'd like to run validation workflow or proceed to next workflows
+
+## SUCCESS METRICS:
+
+✅ PRD document contains all required sections and has been polished
+✅ All collaborative content properly saved and optimized
+✅ Workflow status file updated with completion information (if exists)
+✅ Validation workflow options clearly presented
+✅ Clear next step guidance provided to user
+✅ Document quality validation completed
+✅ User acknowledges completion and understands next options
+
+## FAILURE MODES:
+
+❌ Not updating workflow status file with completion information (if exists)
+❌ Not offering validation workflow options
+❌ Missing clear next step guidance for user
+❌ Not confirming document completeness with user
+❌ Workflow not properly marked as complete in status tracking (if applicable)
+❌ User unclear about what happens next or what validation options exist
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## FINAL REMINDER to give the user:
+
+The polished PRD serves as the foundation for all subsequent product development activities. All design, architecture, and development work should trace back to the requirements and vision documented in this PRD - update it also as needed as you continue planning.
+
+**Congratulations on completing the Product Requirements Document for {{project_name}}!** 🎉

package/_bmad/core/tasks/bmad-create-prd/templates/prd-template.md

@@ -0,0 +1,10 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'prd'
+---
+
+# Product Requirements Document - {{project_name}}
+
+**Author:** {{user_name}}
+**Date:** {{date}}

package/_bmad/core/tasks/bmad-create-prd/workflow.md

@@ -0,0 +1,62 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+outputFile: '{planning_artifacts}/prd.md'
+---
+
+# PRD Create Workflow
+
+**Goal:** Create comprehensive PRDs through structured workflow facilitation.
+
+**Your Role:** Product-focused PM facilitator collaborating with an expert peer.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {main_config} and resolve:
+
+- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### 2. Route to Create Workflow
+
+"**Create Mode: Creating a new PRD from scratch.**"
+
+Read fully and follow: `./steps-c/step-01-init.md`

package/config/allowed-commands.ts

@@ -0,0 +1,39 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+
+const CONFIG_DIR = join(homedir(), ".frappe-builder");
+const WHITELIST_PATH = join(CONFIG_DIR, "allowed-commands.json");
+
+export const DEFAULT_BENCH_COMMANDS: string[] = [
+  "bench migrate",
+  "bench build",
+  "bench install",
+  "bench update",
+  "bench run-tests",
+  "bench restart",
+  "bench clear-cache",
+  "bench console",
+];
+
+/**
+ * Loads the bench command whitelist from ~/.frappe-builder/allowed-commands.json.
+ * On first run (file missing): writes defaults to disk and returns them.
+ * On malformed JSON: logs warning and returns defaults — never throws.
+ */
+export function loadAllowedCommands(): string[] {
+  if (!existsSync(WHITELIST_PATH)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(WHITELIST_PATH, JSON.stringify(DEFAULT_BENCH_COMMANDS, null, 2), "utf-8");
+    return [...DEFAULT_BENCH_COMMANDS];
+  }
+  try {
+    const raw = readFileSync(WHITELIST_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) throw new Error("Expected JSON array");
+    return parsed.map(String);
+  } catch {
+    console.warn("[WHITELIST WARNING: allowed-commands.json is malformed — using defaults]");
+    return [...DEFAULT_BENCH_COMMANDS];
+  }
+}

package/config/defaults.ts

@@ -0,0 +1,19 @@
+export interface SpawnRule {
+  trigger: string;
+  delegate: string;
+}
+
+export interface AppConfig {
+  autoGitCheckpoint: boolean;
+  allowSubAgents: boolean;
+  requirePermission: boolean;
+  rules: SpawnRule[];
+  frappeMcpUrl?: string; // URL of Frappe MCP server for frappe_query (e.g. "http://localhost:8000")
+}
+
+export const defaults: AppConfig = {
+  autoGitCheckpoint: true,
+  allowSubAgents: false,      // opt-in — disabled by default
+  requirePermission: true,    // always prompt unless explicitly disabled
+  rules: [],
+};

package/config/loader.ts

@@ -0,0 +1,105 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { defaults } from "./defaults.js";
+import type { AppConfig } from "./defaults.js";
+
+// ── Credential config types (NFR6, NFR9) ────────────────────────────────────
+
+export interface GlobalConfig {
+  llm_api_key: string;
+  llm_provider?: string;
+  [key: string]: unknown;
+}
+
+export interface ProjectConfig {
+  site_url: string;
+  api_key: string;
+  api_secret: string;
+  [key: string]: unknown;
+}
+
+export interface CredentialConfig {
+  global: GlobalConfig;
+  project: ProjectConfig;
+  sessionLogDir: string;
+}
+
+/** Always ~/.frappe-builder/sessions/ — never the project directory (NFR9). */
+export const SESSION_LOG_DIR = join(homedir(), ".frappe-builder", "sessions");
+
+const GITIGNORE_ERROR =
+  "Site credentials file is not gitignored. Add .frappe-builder-config.json to .gitignore before proceeding.";
+
+/**
+ * Validates that {projectRoot}/.gitignore lists .frappe-builder-config.json.
+ * Throws with the exact AC error message if missing or absent.
+ */
+export function validateGitignore(projectRoot: string): void {
+  const gitignorePath = join(projectRoot, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    throw new Error(GITIGNORE_ERROR);
+  }
+  const contents = readFileSync(gitignorePath, "utf8");
+  const lines = contents.split("\n").map((l) => l.trim());
+  if (!lines.includes(".frappe-builder-config.json")) {
+    throw new Error(GITIGNORE_ERROR);
+  }
+}
+
+/**
+ * Reads LLM API keys from ~/.frappe-builder/config.json (user-global, never project).
+ * Creates ~/.frappe-builder/ on first run. Returns empty defaults if file absent.
+ */
+export function loadGlobalConfig(): GlobalConfig {
+  const configDir = join(homedir(), ".frappe-builder");
+  mkdirSync(configDir, { recursive: true });
+  const configPath = join(configDir, "config.json");
+  if (!existsSync(configPath)) return { llm_api_key: "" };
+  try {
+    return JSON.parse(readFileSync(configPath, "utf8")) as GlobalConfig;
+  } catch {
+    return { llm_api_key: "" };
+  }
+}
+
+/**
+ * Reads Frappe site credentials from {projectRoot}/.frappe-builder-config.json.
+ * Returns empty defaults if file absent (caller should surface a warning).
+ */
+export function loadProjectConfig(projectRoot: string): ProjectConfig {
+  const configPath = join(projectRoot, ".frappe-builder-config.json");
+  if (!existsSync(configPath)) return { site_url: "", api_key: "", api_secret: "" };
+  try {
+    return JSON.parse(readFileSync(configPath, "utf8")) as ProjectConfig;
+  } catch {
+    return { site_url: "", api_key: "", api_secret: "" };
+  }
+}
+
+/**
+ * Full credential loader: validates gitignore, loads global + project configs.
+ * Throws if .frappe-builder-config.json is not gitignored.
+ * API keys are only ever read from ~/.frappe-builder/ — never from projectRoot.
+ */
+export function loadCredentials(projectRoot: string): CredentialConfig {
+  validateGitignore(projectRoot);
+  const global = loadGlobalConfig();
+  const project = loadProjectConfig(projectRoot);
+  return { global, project, sessionLogDir: SESSION_LOG_DIR };
+}
+
+/**
+ * Loads ~/.frappe-builder/config.json and merges with defaults.
+ * Never throws — returns defaults on any read/parse failure.
+ */
+export function loadConfig(): AppConfig {
+  const configPath = join(homedir(), ".frappe-builder", "config.json");
+  if (!existsSync(configPath)) return { ...defaults };
+  try {
+    const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Partial<AppConfig>;
+    return { ...defaults, ...raw };
+  } catch {
+    return { ...defaults };
+  }
+}

package/dist/cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+//#region src/cli.ts
+/**
+* src/cli.ts — frappe-builder CLI entry point
+*
+* Commands:
+*   frappe-builder init    — interactive setup wizard (run once per project)
+*   frappe-builder         — start a pi session with frappe-builder extensions loaded
+*/
+const cmd = process.argv[2];
+if (cmd === "init") {
+	const { runInit } = await import("./init-BYJy3ztn.mjs");
+	await runInit();
+	process.exit(0);
+}
+if (cmd === "--help" || cmd === "-h") {
+	console.log(`
+Usage: frappe-builder [command]
+
+Commands:
+  init    Configure frappe-builder for this project (run once per project)
+  (none)  Start a frappe-builder session
+
+Options:
+  --help, -h   Show this help message
+`);
+	process.exit(0);
+}
+if (!existsSync(resolve(process.cwd(), ".frappe-builder-config.json"))) {
+	console.error("frappe-builder is not configured in this directory.");
+	console.error("Run: frappe-builder init");
+	process.exit(1);
+}
+const pkgRoot = resolve(fileURLToPath(import.meta.url), "..", "..");
+const extensions = [
+	"frappe-session",
+	"frappe-state",
+	"frappe-workflow",
+	"frappe-tools",
+	"frappe-gates",
+	"frappe-ui"
+].map((name) => resolve(pkgRoot, "extensions", `${name}.ts`));
+const agentsFile = resolve(pkgRoot, "AGENTS.md");
+const require = createRequire(import.meta.url);
+let piCli;
+try {
+	piCli = require.resolve("@mariozechner/pi-coding-agent/dist/cli.js");
+} catch {
+	console.error("Could not locate pi CLI.");
+	console.error("Try reinstalling: npm install -g frappe-builder@dev");
+	process.exit(1);
+}
+const extArgs = extensions.flatMap((e) => ["-e", e]);
+const result = spawnSync(process.execPath, [
+	piCli,
+	...extArgs,
+	"--append-system-prompt",
+	agentsFile
+], { stdio: "inherit" });
+process.exit(result.status ?? 0);
+//#endregion
+export {};

package/dist/init-BYJy3ztn.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+//#region src/init.ts
+/**
+* src/init.ts — interactive setup wizard for frappe-builder
+*
+* Handles: global config (~/.frappe-builder/config.json),
+*          project config (.frappe-builder-config.json),
+*          and .gitignore patching.
+*
+* No imports from state/, extensions/, or gates/.
+* Uses Node.js built-ins only — no external prompt libraries.
+*/
+let cancelled = false;
+process.on("SIGINT", () => {
+	cancelled = true;
+});
+function promptLine(question) {
+	return new Promise((resolve) => {
+		if (cancelled) {
+			resolve("");
+			return;
+		}
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer);
+		});
+	});
+}
+async function promptYN(question) {
+	const answer = await promptLine(question + " (y/N): ");
+	return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+}
+function writeAtomic(filePath, content) {
+	const tmp = filePath + ".tmp";
+	writeFileSync(tmp, content, "utf-8");
+	renameSync(tmp, filePath);
+}
+/** Patches .gitignore to include the exact entry if not already present. */
+function patchGitignore(projectRoot, entry) {
+	const gitignorePath = join(projectRoot, ".gitignore");
+	if (!existsSync(gitignorePath)) {
+		writeFileSync(gitignorePath, entry + "\n", "utf-8");
+		return "created";
+	}
+	const content = readFileSync(gitignorePath, "utf-8");
+	if (content.split("\n").includes(entry)) return "already-present";
+	writeFileSync(gitignorePath, content.endsWith("\n") ? content + entry + "\n" : content + "\n" + entry + "\n", "utf-8");
+	return "patched";
+}
+async function runInit(opts = {}) {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	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");
+	console.log(`[Global config: ${globalConfigPath}]`);
+	let globalConfig = {};
+	let globalAction = "written";
+	if (existsSync(globalConfigPath)) {
+		try {
+			globalConfig = JSON.parse(readFileSync(globalConfigPath, "utf-8"));
+		} catch {}
+		if (!cancelled) {
+			const overwrite = await promptYN(`Overwrite existing ${globalConfigPath}?`);
+			if (cancelled) {
+				printCancelled();
+				return;
+			}
+			if (!overwrite) {
+				globalAction = "skipped";
+				console.log("  Keeping existing global config.\n");
+			}
+		}
+	}
+	if (!cancelled && globalAction === "written") {
+		const llmKey = await promptLine("LLM API key (leave blank to skip): ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		globalConfig.llm_api_key = llmKey.trim();
+	}
+	console.log(`\n[Project config: ${projectConfigPath}]`);
+	let projectConfig = {};
+	let projectAction = "written";
+	if (existsSync(projectConfigPath)) {
+		try {
+			projectConfig = JSON.parse(readFileSync(projectConfigPath, "utf-8"));
+		} catch {}
+		if (!cancelled) {
+			const overwrite = await promptYN(`Overwrite existing ${projectConfigPath}?`);
+			if (cancelled) {
+				printCancelled();
+				return;
+			}
+			if (!overwrite) {
+				projectAction = "skipped";
+				console.log("  Keeping existing project config.\n");
+			}
+		}
+	}
+	if (!cancelled && projectAction === "written") {
+		const siteUrl = await promptLine("Frappe site URL (e.g. http://site1.localhost): ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		const apiKey = await promptLine("Frappe API key: ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		const apiSecret = await promptLine("Frappe API secret: ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		projectConfig = {
+			site_url: siteUrl.trim(),
+			api_key: apiKey.trim(),
+			api_secret: apiSecret.trim()
+		};
+	}
+	const written = [];
+	const skipped = [];
+	if (globalAction === "written") {
+		mkdirSync(globalConfigDir, { recursive: true });
+		writeAtomic(globalConfigPath, JSON.stringify(globalConfig, null, 2) + "\n");
+		written.push(`~/.frappe-builder/config.json`);
+	} else skipped.push(`~/.frappe-builder/config.json`);
+	if (projectAction === "written") {
+		writeAtomic(projectConfigPath, JSON.stringify(projectConfig, null, 2) + "\n");
+		written.push(`.frappe-builder-config.json`);
+	} else skipped.push(`.frappe-builder-config.json`);
+	const gitignoreResult = patchGitignore(projectRoot, ".frappe-builder-config.json");
+	if (gitignoreResult === "patched") written.push(".gitignore (patched)");
+	else if (gitignoreResult === "created") written.push(".gitignore (created)");
+	else skipped.push(".gitignore (entry already present)");
+	console.log("\nFiles written:");
+	for (const f of written) console.log(`  ✓ ${f}`);
+	if (skipped.length > 0) {
+		console.log("Skipped:");
+		for (const f of skipped) console.log(`  - ${f}`);
+	}
+	console.log("\nReady. Run: frappe-builder\n");
+}
+function printCancelled() {
+	console.log("\nSetup cancelled. No files were written.\n");
+}
+//#endregion
+export { runInit };