frappe-builder 1.1.0-dev.8

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

package/tools/frappe-context7.ts

@@ -0,0 +1,70 @@
+import { execa } from "execa";
+
+export interface FrappeDocsArgs {
+  topic: string;
+  version?: string;
+}
+
+export interface FrappeDocsResult {
+  snippet?: string;
+  topic?: string;
+  source?: "context7";
+  error?: string;
+  fallback?: string;
+}
+
+const CONTEXT7_UNAVAILABLE: FrappeDocsResult = {
+  error: "context7 unavailable",
+  fallback: "search frappe.io manually",
+};
+
+/**
+ * Retrieves compressed Frappe/ERPNext documentation via context7 MCP subprocess.
+ * Raw web content never enters the LLM context — only the compressed 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
+ */
+export async function getFrappeDocs({ topic, version }: FrappeDocsArgs): Promise<FrappeDocsResult> {
+  try {
+    // Step 1: resolve Frappe library ID
+    const libraryName = version ? `frappe@${version}` : "frappe";
+    const resolveResult = await execa(
+      "mcp2cli",
+      ["context7", "resolve-library-id", "--libraryName", libraryName],
+      { 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;
+    }
+
+    // Step 2: fetch compressed docs for topic (~90% token reduction via 5000 token limit)
+    const docsResult = await execa(
+      "mcp2cli",
+      [
+        "context7",
+        "get-library-docs",
+        "--libraryId", libraryId,
+        "--topic", topic,
+        "--tokens", "5000",
+      ],
+      { timeout: 15_000 }
+    );
+
+    const snippet = docsResult.stdout?.trim();
+    if (!snippet) return CONTEXT7_UNAVAILABLE;
+
+    return { snippet, topic, source: "context7" };
+  } catch {
+    return CONTEXT7_UNAVAILABLE;
+  }
+}

package/tools/frappe-query-tools.ts

@@ -0,0 +1,47 @@
+import { execa } from "execa";
+import { loadConfig } from "../config/loader.js";
+import { routeThroughContextMode } from "./context-sandbox.js";
+
+export interface FrappeQueryArgs {
+  doctype: string;
+  filters?: Record<string, unknown>;
+}
+
+export interface FrappeQueryResult {
+  summary?: string;
+  error?: string;
+}
+
+/**
+ * Dispatches a Frappe get_list query via mcp2cli subprocess.
+ * Raw output is routed through context-mode sandbox — never returned directly.
+ * Returns structured error on failure, never throws.
+ *
+ * Note: mcp2cli command syntax uses --mcp <url> --raw <tool_name> <json_args>.
+ * Adapt args array if actual mcp2cli CLI syntax differs.
+ */
+export async function frappeQuery({ doctype, filters }: FrappeQueryArgs): Promise<FrappeQueryResult> {
+  const config = loadConfig();
+
+  if (!config.frappeMcpUrl) {
+    return { error: "frappeMcpUrl not configured in ~/.frappe-builder/config.json" };
+  }
+
+  try {
+    const payload = JSON.stringify({ doctype, filters: filters ?? {} });
+    const { stdout, stderr } = await execa("mcp2cli", [
+      "--mcp", config.frappeMcpUrl,
+      "--raw",
+      "frappe_get_list",
+      payload,
+    ]);
+
+    if (stderr) console.warn(`[frappe_query mcp2cli stderr: ${stderr}]`);
+
+    const summary = await routeThroughContextMode(stdout);
+    return { summary };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { error: msg };
+  }
+}