frappe-builder 1.1.0-dev.8

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/extensions/frappe-gates.ts

@@ -0,0 +1,160 @@
+/**
+ * extensions/frappe-gates.ts — Quality Gate Orchestrator (Story 6.1)
+ *
+ * Intercepts Write/Edit/NotebookEdit tool calls and runs all gates in gates/
+ * sequentially before the file write executes. Blocks on first failure.
+ *
+ * Extension load order (beforeToolCall chain):
+ *   1. frappe-ui.ts       → announces "→ Calling {tool} [{phase}]"
+ *   2. frappe-workflow.ts → FSM phase guard (may block out-of-phase calls)
+ *   3. frappe-gates.ts    → quality gate scan (this file — may block bad code)
+ *   4. [tool executes]
+ */
+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";
+
+// Adapt frappe-native-check's custom result type to the standard GateResult
+function nativeAdapter(code: string, _context: GateContext): GateResult {
+  const r = checkFrappeNative(code);
+  if (r.passed) return { passed: true };
+  return {
+    passed: false,
+    violations: [
+      {
+        reason: (r as { message: string }).message,
+        detectedPatterns: (r as { detectedPatterns: string[] }).detectedPatterns,
+      },
+    ],
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyModule = Record<string, any>;
+
+function tryLoadGate(mod: AnyModule, exportName: string, gateName: string): { name: string; fn: GateFn } | null {
+  const fn = mod[exportName];
+  if (typeof fn === "function") return { name: gateName, fn: fn as GateFn };
+  console.warn(`[GATE WARNING: ${gateName} gate not yet implemented — skipping]`);
+  return null;
+}
+
+import * as permCheckMod from "../gates/permission-check.js";
+import * as queryCheckMod from "../gates/query-check.js";
+import * as serverCheckMod from "../gates/server-side-check.js";
+import * as coverageCheckMod from "../gates/coverage-check.js";
+import * as styleCheckMod from "../gates/style-check.js";
+
+// Gate registry — frappe_native always present (Story 4.5); others optional until 6.2–6.6
+const GATE_REGISTRY: Array<{ name: string; fn: GateFn }> = [
+  { name: "frappe_native", fn: nativeAdapter },
+];
+
+for (const [mod, exportName, gateName] of [
+  [permCheckMod, "permissionCheck", "permission_check"],
+  [queryCheckMod, "queryCheck", "query_check"],
+  [serverCheckMod, "serverSideCheck", "server_side_check"],
+  [coverageCheckMod, "coverageCheck", "coverage_check"],
+  [styleCheckMod, "styleCheck", "style_check"],
+] as [AnyModule, string, string][]) {
+  const entry = tryLoadGate(mod, exportName, gateName);
+  if (entry) GATE_REGISTRY.push(entry);
+}
+
+export const FILE_WRITE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
+
+export interface BlockedGateResponse {
+  blocked: true;
+  tool: string;
+  gate: string;
+  file: string;
+  violations: Array<{ line?: number; reason: string; [key: string]: unknown }>;
+  message: string;
+}
+
+function getActiveSessionId(): string {
+  try {
+    const row = db
+      .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { session_id: string } | undefined;
+    return row?.session_id ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Runs all registered gates against the code being written. Returns a block
+ * response on the first gate failure, or undefined to allow the write.
+ * Exported for unit testing.
+ */
+export function runGates(
+  toolName: string,
+  args: Record<string, unknown>
+): BlockedGateResponse | undefined {
+  if (!FILE_WRITE_TOOLS.has(toolName)) return undefined;
+
+  const file = (args.file_path ?? args.notebook_path ?? args.path ?? "") as string;
+  const code = (args.content ?? args.new_string ?? "") as string;
+
+  let phase = "idle";
+  try { phase = getCurrentPhase(); } catch { /* swallow */ }
+
+  const sessionId = getActiveSessionId();
+  const context: GateContext = { file, phase, sessionId };
+
+  for (const gate of GATE_REGISTRY) {
+    let result: GateResult;
+
+    try {
+      result = gate.fn(code, context);
+      if (typeof result !== "object" || result === null || !("passed" in result)) {
+        console.warn(`[GATE WARNING: ${gate.name} returned unexpected shape]`);
+        appendEntry({
+          ts: new Date().toISOString(),
+          sessionId,
+          type: "quality_gate",
+          payload: { gate: gate.name, result: "error", file, error: "unexpected result shape" },
+        });
+        continue;
+      }
+    } catch (err) {
+      appendEntry({
+        ts: new Date().toISOString(),
+        sessionId,
+        type: "quality_gate",
+        payload: { gate: gate.name, result: "error", file, error: String(err) },
+      });
+      continue;
+    }
+
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId,
+      type: "quality_gate",
+      payload: { gate: gate.name, result: result.passed ? "pass" : "blocked", file },
+    });
+
+    if (!result.passed) {
+      const violations = result.violations;
+      return {
+        blocked: true,
+        tool: toolName,
+        gate: gate.name,
+        file,
+        violations,
+        message: `${gate.name} gate blocked write to ${file}: ${violations[0]?.reason ?? "violation"}`,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("tool_call", (event: { toolName?: string; input?: Record<string, unknown> }) => {
+    return runGates(event.toolName ?? "", event.input ?? {});
+  });
+}