frappe-builder 1.1.0-dev.10

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 ?? {});
+  });
+}

package/extensions/frappe-session.ts

@@ -0,0 +1,324 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { db } from "../state/db.js";
+import { createFsmAtPhase, type Phase } from "../state/fsm.js";
+
+/** Maps FSM phases to their specialist names. frappe-debugger is manually invoked (Story 3.5). */
+export const PHASE_TO_SPECIALIST: Record<string, string | null> = {
+  idle: null,
+  requirements: "frappe-ba",
+  architecture: "frappe-architect",
+  planning: "frappe-planner",
+  implementation: "frappe-dev",
+  testing: "frappe-qa",
+  documentation: "frappe-docs",
+};
+
+/** Context object injected into a specialist's activation block. */
+export interface SpecialistContext {
+  activeProject: string;
+  featureName: string;
+  currentPhase: string;
+  progressDone: number;
+  progressTotal: number;
+  lastTool: string;
+}
+
+/**
+ * Builds specialist context by reading the active session and feature from state.db.
+ * Synchronous (better-sqlite3). Never throws — returns safe defaults on any failure.
+ */
+export function buildStateContext(featureId: string | null, lastTool = ""): SpecialistContext {
+  const defaults: SpecialistContext = {
+    activeProject: "unknown",
+    featureName: "unknown",
+    currentPhase: "idle",
+    progressDone: 0,
+    progressTotal: 0,
+    lastTool: lastTool || "none",
+  };
+  try {
+    const session = db
+      .prepare(
+        "SELECT project_id, feature_id, current_phase, last_tool FROM sessions WHERE is_active = 1 LIMIT 1"
+      )
+      .get() as {
+        project_id: string;
+        feature_id: string | null;
+        current_phase: string;
+        last_tool: string | null;
+      } | undefined;
+
+    if (!session) return defaults;
+
+    const fid = featureId ?? session.feature_id ?? null;
+    const feature = fid
+      ? (db.prepare("SELECT name FROM features WHERE feature_id = ?").get(fid) as { name: string } | undefined)
+      : undefined;
+
+    const components = fid
+      ? (db.prepare("SELECT status FROM components WHERE feature_id = ?").all(fid) as { status: string }[])
+      : [];
+
+    const done = components.filter((c) => c.status === "complete").length;
+
+    return {
+      activeProject: session.project_id ?? "unknown",
+      featureName: feature?.name ?? "unknown",
+      currentPhase: session.current_phase ?? "idle",
+      progressDone: done,
+      progressTotal: components.length,
+      lastTool: lastTool || session.last_tool || "none",
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Returns a formatted specialist activation block for the given phase.
+ * Returns empty string for idle phase (no specialist) or unknown phases.
+ * Pure function — no DB access, no side effects.
+ */
+export function loadSpecialist(phase: string, ctx: SpecialistContext): string {
+  const specialistName = PHASE_TO_SPECIALIST[phase] ?? null;
+  if (!specialistName) return "";
+  return [
+    `## Active Specialist: ${specialistName}`,
+    `Project: ${ctx.activeProject} | Feature: ${ctx.featureName} | Phase: ${ctx.currentPhase}`,
+    `Progress: ${ctx.progressDone}/${ctx.progressTotal} components | Last tool: ${ctx.lastTool}`,
+  ].join("\n");
+}
+
+/**
+ * Returns a formatted activation block for the frappe-debugger specialist.
+ * frappe-debugger is NOT phase-driven — it is invoked directly (Story 3.5).
+ * Never throws — pure function, no DB access.
+ */
+export function loadDebuggerSpecialist(ctx: SpecialistContext): string {
+  return [
+    `## Active Specialist: frappe-debugger`,
+    `Project: ${ctx.activeProject} | Feature: ${ctx.featureName} | Phase: ${ctx.currentPhase}`,
+    `Progress: ${ctx.progressDone}/${ctx.progressTotal} components | Last tool: ${ctx.lastTool}`,
+  ].join("\n");
+}
+
+/** Row shapes returned from SQLite queries. */
+interface SessionRow {
+  session_id: string;
+  project_id: string;
+  site_path: string | null;
+  feature_id: string | null;
+  current_phase: string;
+  last_tool: string | null;
+  is_active: number;
+}
+
+interface FeatureRow {
+  feature_id: string;
+  name: string;
+  current_phase: string;
+}
+
+interface ComponentRow {
+  component_id: string;
+  feature_id: string;
+  status: string;
+}
+
+/** Reconstructed session context used for prompt injection. */
+export interface SessionContext {
+  projectId: string;
+  sitePath?: string | null;
+  featureName: string | null;
+  phase: string;
+  componentsDone: number;
+  componentsTotal: number;
+  lastTool: string | null;
+}
+
+/** Returns the sessions directory for JSONL files. */
+function getSessionsDir(): string {
+  return join(homedir(), ".frappe-builder", "sessions");
+}
+
+/** Reads the last N non-empty lines from a JSONL file efficiently. */
+function readLastLines(filePath: string, n: number): string[] {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  return content.split("\n").filter(Boolean).slice(-n);
+}
+
+/** Returns a blank session context for fresh/unknown starts. */
+function freshSession(): SessionContext {
+  return {
+    projectId: "unknown",
+    sitePath: null,
+    featureName: null,
+    phase: "idle",
+    componentsDone: 0,
+    componentsTotal: 0,
+    lastTool: null,
+  };
+}
+
+/** Creates a fresh session row in the sessions table. */
+function createFreshSession(projectId = "default"): void {
+  db.prepare(`
+    INSERT INTO sessions (session_id, project_id, current_phase, started_at, is_active)
+    VALUES (?, ?, 'idle', ?, 1)
+  `).run(randomUUID(), projectId, new Date().toISOString());
+}
+
+/**
+ * Reconstructs session context from SQLite state.
+ * On any error returns a fresh idle context and logs a warning — never throws.
+ */
+export async function reconstructSession(): Promise<SessionContext> {
+  try {
+    const session = db
+      .prepare("SELECT * FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as SessionRow | undefined;
+
+    if (!session) {
+      createFreshSession();
+      return freshSession();
+    }
+
+    const feature = session.feature_id
+      ? (db
+          .prepare("SELECT * FROM features WHERE feature_id = ?")
+          .get(session.feature_id) as FeatureRow | undefined)
+      : undefined;
+
+    const components = feature
+      ? (db
+          .prepare("SELECT * FROM components WHERE feature_id = ?")
+          .all(feature.feature_id) as ComponentRow[])
+      : [];
+
+    const done = components.filter((c) => c.status === "complete").length;
+
+    return {
+      projectId: session.project_id,
+      sitePath: session.site_path ?? null,
+      featureName: feature?.name ?? null,
+      phase: session.current_phase,
+      componentsDone: done,
+      componentsTotal: components.length,
+      lastTool: session.last_tool ?? null,
+    };
+  } catch (err) {
+    console.warn(
+      `[frappe-session] State reconstruction failed: ${err}. Starting fresh.`
+    );
+    return freshSession();
+  }
+}
+
+/**
+ * Builds the concise state injection string for the system prompt.
+ * Kept under 500 tokens to respect NFR2 (≤15% context window).
+ */
+export function buildStateInjection(ctx: SessionContext): string {
+  const progress =
+    ctx.componentsTotal > 0
+      ? `${ctx.componentsDone}/${ctx.componentsTotal} components complete`
+      : "no components tracked";
+
+  const lines = [
+    "=== FRAPPE-BUILDER SESSION CONTEXT ===",
+    `Project: ${ctx.projectId}`,
+  ];
+  if (ctx.sitePath) lines.push(`Site: ${ctx.sitePath}`);
+  lines.push(
+    `Feature: ${ctx.featureName ?? "none"}`,
+    `Phase: ${ctx.phase}`,
+    `Progress: ${progress}`,
+    `Last action: ${ctx.lastTool ?? "none"}`,
+    "======================================"
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Returns the current FSM phase from the active session, validated via the Robot3 FSM.
+ * Creates a fast-forward FSM instance to confirm the stored phase is a known state.
+ * Falls back to "idle" on any error.
+ */
+export function getRestoredPhase(): Phase {
+  try {
+    const row = db
+      .prepare("SELECT current_phase FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { current_phase: string } | undefined;
+    const phase = (row?.current_phase ?? "idle") as Phase;
+    createFsmAtPhase(phase); // validates phase is a known FSM state
+    return phase;
+  } catch {
+    return "idle";
+  }
+}
+
+/**
+ * Session start handler — reconstructs state from SQLite and returns the
+ * system prompt injection string. Call this at agent startup before the
+ * first LLM prompt is sent (NFR1: must complete in <500ms).
+ *
+ * Includes specialist activation block when phase is not idle (Story 3.4).
+ * Never throws — on any failure returns a fresh idle context.
+ */
+export async function handleSessionStart(): Promise<string> {
+  try {
+    const ctx = await reconstructSession();
+
+    // Read last 10 JSONL entries for additional context (last action detail)
+    const sessionRow = db
+      .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+      .get() as { session_id: string } | undefined;
+
+    if (sessionRow) {
+      const journalPath = join(
+        getSessionsDir(),
+        `${sessionRow.session_id}.jsonl`
+      );
+      readLastLines(journalPath, 10); // read for context; unused in prompt for now
+    }
+
+    const stateBlock = buildStateInjection(ctx);
+
+    // Specialist auto-load on session resume (Story 3.4)
+    // AGENTS.md base identity (Nexus) is loaded natively by pi from project root.
+    if (ctx.phase !== "idle") {
+      try {
+        const specCtx = buildStateContext(null, "session_start");
+        const specialistBlock = loadSpecialist(ctx.phase, specCtx);
+        if (specialistBlock) return `${stateBlock}\n\n${specialistBlock}`;
+      } catch (specialistErr) {
+        console.warn(`[frappe-session] specialist load failed at session start: ${specialistErr}`);
+      }
+    }
+
+    return stateBlock;
+  } catch (err) {
+    console.warn(`[frappe-session] handleSessionStart failed: ${err}. Using idle context.`);
+    return buildStateInjection(freshSession());
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("session_start", async () => {
+    await handleSessionStart();
+  });
+}
+
+/**
+ * Reloads session context after a project switch.
+ * Reconstructs state from SQLite and returns the updated prompt injection string.
+ * Called by setActiveProject() after switchProject() creates the new session.
+ */
+export async function reloadSessionContext(): Promise<void> {
+  await handleSessionStart();
+}