frappe-builder 1.1.0-dev.8

package/gates/query-check.ts

@@ -0,0 +1,40 @@
+/**
+ * gates/query-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Detects SQL string concatenation patterns (f-strings, +, %) that
+ * could lead to SQL injection. Requires parameterised queries. (FR27)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const SQL_KEYWORD = /\b(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)\b/i;
+
+const INJECTION_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /f["'].*\{[^}]+\}.*["']/, label: "f-string interpolation" },
+  { pattern: /["']\s*\+\s*\w/, label: "string concatenation (+)" },
+  { pattern: /["']\s*%\s*\w/, label: "%-format interpolation" },
+];
+
+const REASON = "SQL string concatenation detected — use parameterised queries";
+
+export function queryCheck(code: string, context: GateContext): GateResult {
+  if (!context.file.endsWith(".py")) return { passed: true };
+
+  const lines = code.split("\n");
+  const violations: Array<{ line: number; pattern: string; reason: string }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!SQL_KEYWORD.test(line)) continue;
+
+    for (const { pattern, label } of INJECTION_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({ line: i + 1, pattern: label, reason: REASON });
+        break; // one violation per line — avoid duplicating the same line
+      }
+    }
+  }
+
+  return violations.length > 0 ? { passed: false, violations } : { passed: true };
+}

package/gates/server-side-check.ts

@@ -0,0 +1,67 @@
+/**
+ * gates/server-side-check.ts — Pure gate function, no side effects.
+ * No imports from state/, extensions/, or config/.
+ * No async, no db, no I/O. Same input always produces same output.
+ *
+ * Detects business logic patterns in client-side JavaScript/TypeScript that
+ * should live on the Python server instead. (FR28)
+ */
+import type { GateContext, GateResult } from "./types.js";
+
+const BUSINESS_LOGIC_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  // Arithmetic on financial/quantity fields — price/total calculations
+  {
+    pattern: /frm\.doc\.\w+\s*=\s*frm\.doc\.\w+\s*[*\/+\-]\s*frm\.doc\.\w+/,
+    label: "client-side financial calculation",
+  },
+  // Direct permission decisions based on user identity
+  {
+    pattern: /frappe\.session\.user\s*[=!]={1,2}\s*["']/,
+    label: "client-side permission decision (user identity)",
+  },
+  // Role-based access control in JS
+  {
+    pattern: /frappe\.user\.has_role\s*\(/,
+    label: "client-side permission decision (role check)",
+  },
+  // Direct user_roles access
+  {
+    pattern: /frappe\.user_roles\b/,
+    label: "client-side permission decision (user_roles)",
+  },
+  // Direct DB access from client side — should go via frappe.call
+  {
+    pattern: /frappe\.db\.(get_value|get_list|set_value|insert|delete_doc)\s*\(/,
+    label: "direct DB access from client-side (use frappe.call instead)",
+  },
+];
+
+const REASON = "business logic must be server-side";
+
+function isTestFile(file: string): boolean {
+  return file.includes("/test/") || file.includes(".test.") || file.includes(".spec.");
+}
+
+export function serverSideCheck(code: string, context: GateContext): GateResult {
+  // Only scan JS/TS files
+  if (!context.file.endsWith(".js") && !context.file.endsWith(".ts")) {
+    return { passed: true };
+  }
+  // Exempt test files
+  if (isTestFile(context.file)) return { passed: true };
+
+  const lines = code.split("\n");
+  const violations: Array<{ line: number; pattern: string; reason: string }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { pattern, label } of BUSINESS_LOGIC_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({ line: i + 1, pattern: label, reason: REASON });
+        break; // one violation per line
+      }
+    }
+  }
+
+  return violations.length > 0 ? { passed: false, violations } : { passed: true };
+}

package/gates/style-check.ts

@@ -0,0 +1,92 @@
+import path from 'node:path'
+import type { GateContext, GateResult } from './types.js'
+
+type Violation = { line?: number; reason: string; [key: string]: unknown }
+
+const DEF_LINE = /^([^\S\n]*)def\s+(\w+)\s*\([^)]*\)\s*:/gm
+const NON_DESCRIPTIVE = /^(\s*)(x|y|z|data|temp|tmp|val|var|foo|bar|test|obj|res|ret)\s*=/gm
+const SQL_STRING = /frappe\.db\.sql\s*\(\s*["'`]{1,3}([\s\S]*?)["'`]{1,3}/g
+const CAMEL_IDENTIFIER = /\b([a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*)\b/g
+
+const STUB_BODY = /^\s*(pass|return|return None|super\(\)\.__init__\(.*?\))\s*$/
+
+function lineNumber(code: string, index: number): number {
+  return code.slice(0, index).split('\n').length
+}
+
+function hasDocstring(code: string, defStart: number): boolean {
+  const bodyStart = code.indexOf('\n', defStart) + 1
+  const bodyTrimmed = code.slice(bodyStart).trimStart()
+  return bodyTrimmed.startsWith('"""') || bodyTrimmed.startsWith("'''")
+}
+
+function isStubBody(code: string, defStart: number): boolean {
+  const newline = code.indexOf('\n', defStart)
+  if (newline === -1) return true
+  const nextNewline = code.indexOf('\n', newline + 1)
+  const bodyLine = nextNewline === -1
+    ? code.slice(newline + 1)
+    : code.slice(newline + 1, nextNewline)
+  return STUB_BODY.test(bodyLine)
+}
+
+function checkPython(code: string, violations: Array<Violation>): void {
+  // 1. Docstring check
+  let m: RegExpExecArray | null
+  DEF_LINE.lastIndex = 0
+  while ((m = DEF_LINE.exec(code)) !== null) {
+    const fnName = m[2]
+    const defStart = m.index
+    if (!hasDocstring(code, defStart) && !isStubBody(code, defStart)) {
+      violations.push({ function: fnName, line: lineNumber(code, defStart), reason: 'missing docstring' })
+    }
+  }
+
+  // 2. Non-descriptive variable check
+  NON_DESCRIPTIVE.lastIndex = 0
+  while ((m = NON_DESCRIPTIVE.exec(code)) !== null) {
+    const varName = m[2]
+    violations.push({ line: lineNumber(code, m.index), variable: varName, reason: 'non-descriptive variable name' })
+  }
+
+  // 3. SQL camelCase column check
+  SQL_STRING.lastIndex = 0
+  while ((m = SQL_STRING.exec(code)) !== null) {
+    const sqlContent = m[1]
+    const sqlStart = m.index
+    CAMEL_IDENTIFIER.lastIndex = 0
+    let cm: RegExpExecArray | null
+    while ((cm = CAMEL_IDENTIFIER.exec(sqlContent)) !== null) {
+      violations.push({
+        line: lineNumber(code, sqlStart),
+        column: cm[1],
+        reason: 'SQL column must be snake_case',
+      })
+    }
+  }
+}
+
+function checkFilename(context: GateContext, violations: Array<Violation>): void {
+  const basename = path.basename(context.file)
+    .replace(/\.(test|spec)\.(ts|js)$/, '')
+    .replace(/\.(ts|js)$/, '')
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(basename)) {
+    violations.push({ file: context.file, reason: 'TypeScript filename must be kebab-case' })
+  }
+}
+
+export function styleCheck(code: string, context: GateContext): GateResult {
+  const violations: Array<Violation> = []
+  const ext = path.extname(context.file)
+
+  if (ext === '.py') {
+    checkPython(code, violations)
+  } else if (ext === '.ts' || ext === '.js') {
+    checkFilename(context, violations)
+  }
+
+  if (violations.length > 0) {
+    return { passed: false, violations }
+  }
+  return { passed: true }
+}

package/gates/types.ts

@@ -0,0 +1,13 @@
+/** Shared gate types — all Story 6.x gate implementations must satisfy this contract. */
+
+export interface GateContext {
+  file: string;
+  phase: string;
+  sessionId: string;
+}
+
+export type GateResult =
+  | { passed: true }
+  | { passed: false; violations: Array<{ line?: number; reason: string; [key: string]: unknown }> };
+
+export type GateFn = (code: string, context: GateContext) => GateResult;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "frappe-builder",
+  "version": "1.1.0-dev.8",
+  "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
+  "type": "module",
+  "pi": {
+    "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
+    "extensions": [
+      "./extensions/frappe-session.ts",
+      "./extensions/frappe-state.ts",
+      "./extensions/frappe-workflow.ts",
+      "./extensions/frappe-tools.ts",
+      "./extensions/frappe-gates.ts",
+      "./extensions/frappe-ui.ts"
+    ],
+    "agents": "./AGENTS.md"
+  },
+  "scripts": {
+    "build": "bun build --compile --minify src/cli.ts --outfile frappe-builder",
+    "build:ts": "tsdown",
+    "test": "vitest run",
+    "dev": "pi -e ./extensions/frappe-state.ts",
+    "typecheck": "tsc --noEmit",
+    "release": "node scripts/bump-version.mjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "0.62.0",
+    "@mariozechner/pi-ai": "0.62.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.8.0",
+    "execa": "^9.6.1",
+    "robot3": "^1.2.0"
+  }
+}

package/project-context.md

@@ -0,0 +1,146 @@
+# Project Context: frappe-builder
+
+> AI agent rules and project context for consistent implementation across sessions.
+> Generated: 2026-03-23 | Author: Riz
+
+---
+
+## What This Project Is
+
+**frappe-builder** is a pi-package CLI tool — a Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications. It upgrades the existing BMAD module by replacing all prompt-enforced state management with hook-based code enforcement.
+
+**The core shift:** State is owned by code, not conversation. Prompts cannot enforce anything. Hooks can.
+
+---
+
+## Project Type & Context
+
+- **Type:** Developer tool (CLI / AI agent extension for pi-mono)
+- **Context:** Brownfield — upgrading an existing BMAD module, not building from scratch
+- **Runtime:** TypeScript, Node.js 20+ LTS
+- **Primary platform:** pi-mono agent framework (pi-ai)
+
+---
+
+## Architecture Rules for AI Agents
+
+### State Management
+
+1. **JSONL is the immutable source of truth.** Every tool call appends to `~/.frappe-builder/sessions/{id}.jsonl`. Never overwrite or delete entries.
+2. **SQLite (`state.db`) is derived state.** It is rebuilt from JSONL on demand. Never treat it as authoritative over JSONL.
+3. **`afterToolCall` writes state unconditionally.** No tool call completes without a state write. There is no optional path.
+4. **Every startup is a resume.** There is no "new session" vs "resume" split. Session start always reads JSONL, reconstructs SQLite, and injects state context.
+5. **State injection must complete in <500ms** before the first LLM prompt is sent (NFR1).
+
+### Workflow Enforcement
+
+6. **Robot3 FSM governs all workflow transitions.** Valid states: `idle → requirements → architecture → planning → implementation → testing → documentation → idle`.
+7. **`beforeToolCall` blocks out-of-phase tools.** When blocking, the explanation must name: (a) the blocked tool, (b) the current FSM phase, (c) the phase where the tool becomes valid.
+8. **`--mode quick` bypasses the FSM phase cycle** but never bypasses quality gates. Quality gates are always active.
+9. **`--override-workflow` is the only valid escape hatch.** It must be logged to JSONL with a reason. It does not disable quality gates.
+
+### Quality Gates
+
+10. **Quality gates run before any code is written to disk.** They are static analysis scans — deterministic, not LLM judgement. The same violation always produces the same block.
+11. **Six gates are mandatory:**
+    - Every `@frappe.whitelist()` method must include permission checks
+    - No SQL string concatenation — parameterised queries only
+    - Business logic in Python server-side — no client-side business logic
+    - Frappe-native solution required first — non-Frappe solutions need explicit developer justification
+    - Test coverage ≥70% critical-path before feature marked complete
+    - Docstrings and naming conventions (no `x`, `data`, `temp` variable names)
+12. **No feature is marked complete until all quality gates pass.** No exceptions.
+
+### Frappe Integration
+
+13. **All Frappe tool outputs go through mcp2cli + context-mode.** Raw Frappe API payloads must never enter the LLM context directly.
+14. **Bench commands run via subprocess — whitelisted only.** No raw shell access through the tool layer.
+15. **context7 for Frappe/ERPNext documentation.** Never raw web fetch for docs.
+16. **Bench subprocess calls are non-blocking.** Long-running operations (migrate, build) must not freeze the TUI or agent loop.
+
+### Context Budget
+
+17. **LLM context window is a hard constraint.** Across any 50-turn session, total context must stay ≤80% of the active model's window.
+18. **State injection at session start must consume ≤15% of context window.**
+19. **context-mode degradation is graceful** — falls back to truncated direct output, never crashes.
+
+### Security
+
+20. **LLM API keys live exclusively in `~/.frappe-builder/config.json`.** Never in project files. Never in git.
+21. **Frappe site credentials live in `{project}/.frappe-builder-config.json`** — must be gitignored. System refuses to proceed if not gitignored.
+22. **JSONL session logs are local only** (`~/.frappe-builder/sessions/`). Never transmitted externally.
+
+### Code Style
+
+23. **Generated code is lean and self-documenting.** Descriptive names, no abbreviations. No `x`, `data`, `result`, `temp` variables.
+24. **Every function/method gets a docstring.** No exceptions in generated code.
+25. **Frappe-native patterns first.** Before reaching for an external library or custom solution, verify Frappe's built-in capability is insufficient.
+
+---
+
+## Specialist Agent Map
+
+| FSM Phase | Specialist Auto-Loaded |
+|---|---|
+| `requirements` | frappe-ba (Business Analyst) |
+| `architecture` | frappe-architect |
+| `planning` | frappe-planner |
+| `implementation` | frappe-dev |
+| `testing` | frappe-qa |
+| `documentation` | frappe-docs |
+| Any phase (manual) | frappe-debugger |
+| Base identity (always) | frappe-nexus (via AGENTS.md) |
+
+---
+
+## Tool API Surface
+
+| Tool | Phase Available | Purpose |
+|---|---|---|
+| `set_active_project` | Any | Switch active Frappe project/site |
+| `start_feature` | idle | Begin feature workflow (`--mode quick` for fast path) |
+| `complete_component` | implementation | Mark component done, trigger state cascade |
+| `scaffold_doctype` | implementation | Generate DocType scaffold via bench |
+| `run_tests` | testing | Execute Frappe test suite, record results |
+| `get_project_status` | Any | Read project dashboard from state.db |
+| `frappe_query` | Any | Query Frappe via mcp2cli (sandboxed) |
+| `bench_execute` | Any | Run whitelisted bench commands |
+
+---
+
+## Build Phases
+
+| Phase | Deliverable | Gate |
+|---|---|---|
+| 1 | Core State Infrastructure | start→tools→kill→restart→verify exact reconstruction |
+| 2 | Frappe Tool Layer | All 8 tools functional with mcp2cli + context-mode |
+| 3 | TUI & Visibility | Footer widget live; /status dashboard working |
+| 4 | Quality Gates & Knowledge Base | All 6 gates enforced; 8 specialists converted to pi skills |
+| 5 | Distribution | pi package + npm binary published |
+
+**Phase 1 is the critical path. Everything depends on it.**
+
+---
+
+## What This Is Replacing
+
+| Current (BMAD module) | Replacement |
+|---|---|
+| Prompt-enforced state | `afterToolCall` hook → JSONL + SQLite |
+| Bi-modal New/Resume split | Every startup is a resume |
+| `state/templates/*.yaml` | `state.db` (SQLite) |
+| `standards/state-management.md` | Hook enforcement |
+| `agents/*.agent.yaml` | AGENTS.md + pi skills |
+| `workflows/` step files | Robot3 FSM transitions |
+| STATE CASCADE in all 8 agents | Single `afterToolCall` hook |
+
+---
+
+## Measurable Success Criteria
+
+- Zero state drift incidents in sessions ≥50 turns
+- Agent orientation on resume: ≤1 turn to full context
+- State injection context footprint: <15% of context window
+- State injection latency: <500ms
+- All generated code passes quality gates before written to disk
+- No feature marked complete until all quality gates pass

package/state/db.ts

@@ -0,0 +1,85 @@
+import Database from "better-sqlite3";
+import type { Database as DatabaseType } from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { initSchema } from "./schema.js";
+import { appendEntry } from "./journal.js";
+
+mkdirSync(".fb", { recursive: true });
+
+/** Singleton SQLite connection — the only Database instance in the codebase. */
+export let db: DatabaseType = new Database(".fb/state.db");
+
+initSchema(db);
+
+/**
+ * Replaces the db singleton — intended for test use only.
+ * Pass a real in-memory Database(":memory:") seeded with initSchema().
+ */
+export function setDb(instance: DatabaseType): void {
+  db = instance;
+}
+
+/**
+ * Switches the active project: closes the current session atomically and opens
+ * a new session for newProjectId, restoring its last known phase if a prior
+ * session exists. Writes a "state_transition" JSONL entry before the close.
+ *
+ * sitePath is optional so existing callers without a site path continue to work.
+ */
+export function switchProject(newProjectId: string, sitePath?: string): void {
+  db.transaction(() => {
+    // 1. Read current active session before closing
+    const current = db
+      .prepare(
+        "SELECT session_id, project_id, current_phase FROM sessions WHERE is_active = 1 LIMIT 1"
+      )
+      .get() as
+      | { session_id: string; project_id: string; current_phase: string }
+      | undefined;
+
+    const previousProjectId = current?.project_id ?? "unknown";
+    const previousSessionId = current?.session_id ?? crypto.randomUUID();
+
+    // 2. Write JSONL transition entry (appendFileSync — safe inside transaction)
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId: previousSessionId,
+      type: "state_transition",
+      payload: { from: previousProjectId, to: newProjectId },
+    });
+
+    // 3. Close current session
+    db.prepare(
+      "UPDATE sessions SET is_active = 0, ended_at = ? WHERE is_active = 1"
+    ).run(new Date().toISOString());
+
+    // 4. Check for prior session on new project (for phase restoration)
+    const prior = db
+      .prepare(
+        "SELECT current_phase FROM sessions WHERE project_id = ? ORDER BY started_at DESC LIMIT 1"
+      )
+      .get(newProjectId) as { current_phase: string } | undefined;
+
+    // 5. Create new session, restoring prior phase if available; feature_id defaults to NULL
+    db.prepare(
+      "INSERT INTO sessions (session_id, project_id, current_phase, site_path, started_at, is_active) VALUES (?, ?, ?, ?, ?, 1)"
+    ).run(
+      crypto.randomUUID(),
+      newProjectId,
+      prior?.current_phase ?? "idle",
+      sitePath ?? null,
+      new Date().toISOString()
+    );
+  })();
+}
+
+/**
+ * Returns the current FSM phase from the active session row.
+ * Returns "idle" if no active session exists.
+ */
+export function getCurrentPhase(): string {
+  const row = db
+    .prepare("SELECT current_phase FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { current_phase: string } | undefined;
+  return row?.current_phase ?? "idle";
+}

package/state/fsm.ts

@@ -0,0 +1,68 @@
+import { createMachine, state, transition } from "robot3";
+
+export type Phase =
+  | "idle"
+  | "requirements"
+  | "architecture"
+  | "planning"
+  | "implementation"
+  | "testing"
+  | "documentation";
+
+export const ALL_PHASES: Phase[] = [
+  "idle",
+  "requirements",
+  "architecture",
+  "planning",
+  "implementation",
+  "testing",
+  "documentation",
+];
+
+function buildMachineStates() {
+  return {
+    idle: state(
+      transition("start_full", "requirements"),
+      transition("start_quick", "implementation") as never // quick mode bypass (Story 3.3)
+    ),
+    requirements: state(transition("approve", "architecture")),
+    architecture: state(transition("approve", "planning")),
+    planning: state(transition("approve", "implementation")),
+    implementation: state(transition("approve", "testing")),
+    testing: state(transition("approve", "documentation")),
+    documentation: state(transition("complete", "idle")),
+  };
+}
+
+/** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay. */
+export function createFsmAtPhase(phase: Phase) {
+  return createMachine(phase, buildMachineStates());
+}
+
+/**
+ * Maps each tool to its valid phase (or 'any').
+ * Tools not listed here are allowed in any phase — do not block unregistered tools.
+ */
+const TOOL_PHASE_MAP: Record<string, Phase | "any"> = {
+  set_active_project: "any",
+  start_feature: "idle",
+  complete_component: "implementation",
+  scaffold_doctype: "implementation",
+  run_tests: "testing",
+  get_project_status: "any",
+  frappe_query: "any",
+  bench_execute: "any",   // allowed in all phases — includes testing (bench run-tests) and implementation (bench migrate)
+};
+
+/** Returns true if toolName is allowed to run in the given phase. Unknown tools are always allowed. */
+export function isToolAllowedInPhase(toolName: string, phase: Phase): boolean {
+  const validPhase = TOOL_PHASE_MAP[toolName];
+  if (validPhase === undefined) return true; // unknown tool — do not block
+  if (validPhase === "any") return true;
+  return validPhase === phase;
+}
+
+/** Returns the phase where toolName is valid, or 'any' for unrestricted/unknown tools. */
+export function getValidPhase(toolName: string): Phase | "any" {
+  return TOOL_PHASE_MAP[toolName] ?? "any";
+}