frappe-builder 1.1.0-dev.10

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";
+}

package/state/journal.ts

@@ -0,0 +1,164 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  mkdirSync,
+  appendFileSync,
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
+import { db, getCurrentPhase } from "./db.js";
+
+/** Typed journal entry appended to the JSONL session log. */
+export interface JournalEntry {
+  ts: string;
+  sessionId: string;
+  type: "tool_call" | "state_transition" | "quality_gate" | "checkpoint";
+  payload: Record<string, unknown>;
+}
+
+/**
+ * Module-level sessions directory — overridable in tests to avoid writing to ~/.frappe-builder/.
+ * Set this before calling appendEntry or compactIfNeeded in test code.
+ */
+let sessionsDir: string | null = null;
+
+/** Returns the resolved sessions directory path. */
+function getSessionsDir(): string {
+  return sessionsDir ?? join(homedir(), ".frappe-builder", "sessions");
+}
+
+/** Returns the JSONL journal path for a given session. */
+function getJournalPath(sessionId: string): string {
+  return join(getSessionsDir(), `${sessionId}.jsonl`);
+}
+
+/** Returns the archive path for a given session. */
+function getArchivePath(sessionId: string): string {
+  return join(getSessionsDir(), `${sessionId}.jsonl.archive`);
+}
+
+/**
+ * Overrides the sessions directory — intended for test use only.
+ * Pass null to reset to the default ~/.frappe-builder/sessions path.
+ */
+export function setSessionsDir(dir: string | null): void {
+  sessionsDir = dir;
+}
+
+/**
+ * Appends a JournalEntry to the session's JSONL log file.
+ * Synchronous write — required by NFR3 (writes complete before tool result returned).
+ */
+export function appendEntry(entry: JournalEntry): void {
+  const dir = getSessionsDir();
+  mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify(entry) + "\n";
+  appendFileSync(getJournalPath(entry.sessionId), line, "utf-8");
+}
+
+/**
+ * Compacts the session journal if entries exceed 500 or the oldest is > 30 days old.
+ * Archives raw entries to .jsonl.archive, then overwrites .jsonl with a single checkpoint entry.
+ */
+export function compactIfNeeded(sessionId: string): void {
+  const journalPath = getJournalPath(sessionId);
+  const raw = readFileSync(journalPath, "utf-8");
+  const entries: JournalEntry[] = raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as JournalEntry);
+
+  const now = Date.now();
+  const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+  const oldest = Math.min(...entries.map((e) => new Date(e.ts).getTime()));
+  const needsCompaction =
+    entries.length > 500 || now - oldest > thirtyDaysMs;
+
+  if (!needsCompaction) return;
+
+  copyFileSync(journalPath, getArchivePath(sessionId));
+
+  const checkpoint: JournalEntry = {
+    ts: new Date().toISOString(),
+    sessionId,
+    type: "checkpoint",
+    payload: {
+      state_snapshot: getCurrentPhase(),
+      features: db
+        .prepare("SELECT feature_id, name, current_phase FROM features")
+        .all(),
+      component_statuses: db
+        .prepare("SELECT component_id, feature_id, status FROM components")
+        .all(),
+    },
+  };
+
+  writeFileSync(journalPath, JSON.stringify(checkpoint) + "\n", "utf-8");
+}
+
+export interface AuditLogQuery {
+  sessionId?: string;
+  featureId?: string;
+  limit?: number;
+}
+
+/**
+ * Queries JSONL audit log files from the sessions directory.
+ * Includes both active (.jsonl) and archived (.jsonl.archive) files.
+ * Never throws — returns [] on any file error.
+ */
+export function getAuditLog(query: AuditLogQuery = {}): JournalEntry[] {
+  const { sessionId, featureId, limit } = query;
+  const dir = getSessionsDir();
+
+  const filePaths: string[] = [];
+
+  if (sessionId) {
+    const main = getJournalPath(sessionId);
+    const archive = getArchivePath(sessionId);
+    if (existsSync(main)) filePaths.push(main);
+    if (existsSync(archive)) filePaths.push(archive);
+  } else {
+    try {
+      const files = readdirSync(dir);
+      for (const f of files) {
+        if (f.endsWith(".jsonl") && !f.endsWith(".jsonl.archive")) {
+          filePaths.push(join(dir, f));
+        }
+        if (f.endsWith(".jsonl.archive")) {
+          filePaths.push(join(dir, f));
+        }
+      }
+    } catch {
+      return [];
+    }
+  }
+
+  const entries: JournalEntry[] = [];
+  for (const filePath of filePaths) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      for (const line of raw.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          entries.push(JSON.parse(line) as JournalEntry);
+        } catch {
+          // Skip malformed lines
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  entries.sort((a, b) => a.ts.localeCompare(b.ts));
+
+  const filtered = featureId
+    ? entries.filter((e) => (e.payload as Record<string, unknown>).feature === featureId)
+    : entries;
+
+  return limit !== undefined ? filtered.slice(0, limit) : filtered;
+}

package/state/schema.ts

@@ -0,0 +1,41 @@
+import type { Database } from "better-sqlite3";
+
+/**
+ * Runs all CREATE TABLE IF NOT EXISTS statements against the provided database.
+ * Safe to call multiple times — idempotent by design.
+ */
+export function initSchema(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS features (
+      feature_id     TEXT PRIMARY KEY,
+      name           TEXT NOT NULL,
+      mode           TEXT NOT NULL DEFAULT 'full' CHECK (mode IN ('full', 'quick')),
+      current_phase  TEXT NOT NULL DEFAULT 'idle',
+      created_at     TEXT NOT NULL,
+      updated_at     TEXT,
+      progress_done  INTEGER DEFAULT 0,
+      progress_total INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS components (
+      component_id TEXT NOT NULL,
+      feature_id   TEXT NOT NULL,
+      status       TEXT NOT NULL DEFAULT 'in-progress',
+      completed_at TEXT,
+      PRIMARY KEY (feature_id, component_id),
+      FOREIGN KEY (feature_id) REFERENCES features(feature_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id    TEXT PRIMARY KEY,
+      project_id    TEXT NOT NULL,
+      current_phase TEXT NOT NULL DEFAULT 'idle',
+      site_path     TEXT,
+      feature_id    TEXT,
+      last_tool     TEXT,
+      started_at    TEXT NOT NULL,
+      ended_at      TEXT,
+      is_active     INTEGER NOT NULL DEFAULT 1
+    );
+  `);
+}

package/tools/agent-tools.ts

@@ -0,0 +1,60 @@
+import { loadConfig } from "../config/loader.js";
+
+export interface SpawnAgentArgs {
+  skill: string;
+  trigger: string;
+  reason: string;
+  approved?: boolean;
+}
+
+export interface SpawnAgentResult {
+  status: "requires_approval" | "rejected" | "disabled" | "spawned";
+  skill: string;
+  trigger: string;
+  prompt?: string;
+  error?: string;
+  result?: unknown;
+}
+
+/**
+ * Stub: no sub-agent spawn API found in @mariozechner/pi-agent-core at this version.
+ * Returns spawned status with null result — replace body with actual API when available.
+ */
+async function doSpawn(skill: string, trigger: string): Promise<SpawnAgentResult> {
+  return { status: "spawned", skill, trigger, result: null };
+}
+
+/**
+ * Handles the two-call permission flow for sub-agent spawning.
+ * Call 1 (no approved): returns requires_approval prompt if requirePermission === true.
+ * Call 2 (approved: true/false): spawns or rejects.
+ * Autonomous mode (requirePermission: false): spawns on first call.
+ * Does NOT write JSONL — that belongs in afterToolCall (frappe-state.ts).
+ */
+export async function spawnAgent(args: SpawnAgentArgs): Promise<SpawnAgentResult> {
+  const config = loadConfig();
+
+  if (!config.allowSubAgents) {
+    return {
+      status: "disabled",
+      skill: args.skill,
+      trigger: args.trigger,
+      error: "Sub-agent spawning is disabled in config",
+    };
+  }
+
+  if (config.requirePermission && args.approved === undefined) {
+    return {
+      status: "requires_approval",
+      skill: args.skill,
+      trigger: args.trigger,
+      prompt: `Agent wants to spawn ${args.skill} for ${args.reason}. Allow? [Y/n]`,
+    };
+  }
+
+  if (args.approved === false) {
+    return { status: "rejected", skill: args.skill, trigger: args.trigger };
+  }
+
+  return doSpawn(args.skill, args.trigger);
+}

package/tools/bench-tools.ts

@@ -0,0 +1,63 @@
+import { execa } from "execa";
+import { loadAllowedCommands } from "../config/allowed-commands.js";
+import { routeThroughContextMode } from "./context-sandbox.js";
+
+export interface BenchExecuteArgs {
+  command: string;
+  args?: string[];
+}
+
+export type BenchExecuteResult =
+  | { output: string; command: string; exit_code: number }
+  | { blocked: true; command: string; reason: string }
+  | { error: string; command: string; stderr: string };
+
+function isAllowed(command: string, whitelist: string[]): boolean {
+  const normalised = command.trim().toLowerCase();
+  return whitelist.some((w) => w.trim().toLowerCase() === normalised);
+}
+
+/**
+ * Executes a whitelisted bench command via execa subprocess.
+ * Async (non-blocking) — bench commands can run for 30+ seconds (NFR16).
+ * Output routed through context-mode sandbox — raw stdout never returned directly.
+ * Returns structured error on failure, never throws.
+ */
+export async function benchExecute({
+  command,
+  args = [],
+}: BenchExecuteArgs): Promise<BenchExecuteResult> {
+  const whitelist = loadAllowedCommands();
+
+  if (!isAllowed(command, whitelist)) {
+    return { blocked: true, command, reason: "not in whitelist" };
+  }
+
+  // Split "bench migrate" → binary="bench", subParts=["migrate"]
+  const [binary, ...subParts] = command.trim().split(/\s+/);
+  const fullArgs = [...subParts, ...args];
+
+  try {
+    // execa with args array — NO shell expansion (security: prevents injection)
+    const { stdout, exitCode } = await execa(binary, fullArgs);
+    const sandboxed = await routeThroughContextMode(stdout);
+    return { output: sandboxed, command, exit_code: exitCode ?? 0 };
+  } catch (err: unknown) {
+    const e = err as { message?: string; stderr?: string };
+    return {
+      error: e.message ?? String(err),
+      command,
+      stderr: e.stderr ?? "",
+    };
+  }
+}
+
+/** Stub — full implementation deferred (Story 4.2). */
+export function scaffoldDoctype(_args: unknown): { error: string } {
+  return { error: "scaffold_doctype: not yet implemented — Story 4.2 (deferred)" };
+}
+
+/** Stub — full implementation Epic 6. */
+export function runTests(_args: unknown): { error: string } {
+  return { error: "run_tests: not yet implemented — Epic 6" };
+}

package/tools/context-sandbox.ts

@@ -0,0 +1,31 @@
+/**
+ * Context-mode sandbox routing 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.
+ *
+ * NFR17: truncation is NEVER silent — warning is always prepended.
+ */
+
+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.
+ * 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);
+}
+
+/**
+ * Truncates raw output at ~8K tokens and prepends a visible warning.
+ * Returns raw unchanged if under the limit.
+ * Exported for direct use and testing.
+ */
+export function applyTruncationFallback(raw: string): string {
+  if (raw.length <= CHAR_LIMIT) return raw;
+  return `[CONTEXT-MODE UNAVAILABLE: output truncated at 8K tokens]\n\n${raw.slice(0, CHAR_LIMIT)}`;
+}

package/tools/debug-tools.ts

@@ -0,0 +1,12 @@
+/**
+ * Debug tool handlers — invoke_debugger and end_debug.
+ * These tools do NOT write state; all state/JSONL work happens in afterToolCall (frappe-state.ts).
+ */
+
+export function invokeDebugger(): { tool: string; timestamp: string } {
+  return { tool: "invoke_debugger", timestamp: new Date().toISOString() };
+}
+
+export function endDebug(): { tool: string; timestamp: string } {
+  return { tool: "end_debug", timestamp: new Date().toISOString() };
+}

package/tools/feature-tools.ts

@@ -0,0 +1,126 @@
+import { execa } from "execa";
+import { db } from "../state/db.js";
+import { appendEntry } from "../state/journal.js";
+import { loadConfig } from "../config/loader.js";
+import { coverageCheck } from "../gates/coverage-check.js";
+
+interface StartFeatureArgs {
+  name: string;
+  mode?: "full" | "quick";
+}
+
+function toFeatureId(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+/**
+ * Creates a new feature row in state.db and writes a state_transition JSONL entry.
+ * Returns the feature data directly — no wrapper object.
+ * mode defaults to "full" — feature row always stores an explicit mode value.
+ */
+export function startFeature({ name, mode = "full" }: StartFeatureArgs) {
+  const featureId = toFeatureId(name);
+  const createdAt = new Date().toISOString();
+
+  const session = db
+    .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { session_id: string } | undefined;
+
+  db.prepare(
+    "INSERT INTO features (feature_id, name, created_at, mode, current_phase) VALUES (?, ?, ?, ?, 'idle')"
+  ).run(featureId, name, createdAt, mode);
+
+  appendEntry({
+    ts: createdAt,
+    sessionId: session?.session_id ?? "unknown",
+    type: "state_transition",
+    payload: { from: "idle", to: "feature_started", feature: name },
+  });
+
+  return { feature_id: featureId, name, mode, current_phase: "idle", created_at: createdAt };
+}
+
+interface CompleteComponentArgs {
+  featureId: string;
+  componentId: string;
+}
+
+/**
+ * Marks a component as complete in state.db, writes a JSONL state_transition entry,
+ * and optionally creates a git checkpoint commit.
+ * Git checkpoint is best-effort — DB write is never rolled back on git failure.
+ */
+export async function completeComponent({ featureId, componentId }: CompleteComponentArgs) {
+  const completedAt = new Date().toISOString();
+  const config = loadConfig();
+
+  const session = db
+    .prepare("SELECT session_id, current_phase FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { session_id: string; current_phase: string } | undefined;
+  const sessionId = session?.session_id ?? "unknown";
+  const currentPhase = session?.current_phase ?? "idle";
+
+  // Determine if this is the final in-progress component for this feature
+  const pending = db
+    .prepare(
+      "SELECT COUNT(*) as cnt FROM components WHERE feature_id = ? AND status = 'in-progress' AND component_id != ?"
+    )
+    .get(featureId, componentId) as { cnt: number };
+  const isFinalComponent = pending.cnt === 0;
+
+  // Coverage gate: runs only when completing the final component in testing phase
+  if (isFinalComponent && currentPhase === "testing") {
+    const coverageResult = await coverageCheck({ file: `feature:${featureId}`, phase: currentPhase, sessionId });
+
+    // Log quality_gate JSONL regardless of pass/fail
+    appendEntry({
+      ts: new Date().toISOString(),
+      sessionId,
+      type: "quality_gate",
+      payload: {
+        gate: "coverage_check",
+        result: coverageResult.passed ? "pass" : "blocked",
+        coverage: coverageResult.coverage,
+        file: `feature:${featureId}`,
+      },
+    });
+
+    if (!coverageResult.passed) {
+      return {
+        blocked: true,
+        tool: "complete_component",
+        gate: "coverage_check",
+        coverage: coverageResult.coverage,
+        required: coverageResult.required,
+        message: `Coverage gate blocked: ${coverageResult.coverage}% coverage < 70% required. Fix tests and retry.`,
+      };
+    }
+  }
+
+  // Gate passed (or not applicable) — update component status
+  db.prepare(`
+    INSERT INTO components (feature_id, component_id, status, completed_at)
+    VALUES (?, ?, 'complete', ?)
+    ON CONFLICT(feature_id, component_id)
+    DO UPDATE SET status = 'complete', completed_at = excluded.completed_at
+  `).run(featureId, componentId, completedAt);
+
+  appendEntry({
+    ts: completedAt,
+    sessionId,
+    type: "state_transition",
+    payload: { feature: featureId, component: componentId, status: "complete" },
+  });
+
+  if (config.autoGitCheckpoint !== false) {
+    const message = `feat(frappe-builder): ${featureId}/${componentId} completed [phase: ${currentPhase}]`;
+    try {
+      await execa("git", ["commit", "-am", message]);
+      return { feature_id: featureId, component_id: componentId, status: "complete", completed_at: completedAt, git_checkpoint: true };
+    } catch (err) {
+      return { feature_id: featureId, component_id: componentId, status: "complete", completed_at: completedAt, git_checkpoint: false, git_error: (err as Error).message };
+    }
+  }
+
+  return { feature_id: featureId, component_id: componentId, status: "complete", completed_at: completedAt, git_checkpoint: false };
+}