frappe-builder 1.1.0-dev.13 → 1.1.0-dev.16

package/state/artifacts.ts

@@ -2,9 +2,17 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { db } from "./db.js";
 
-/** Returns the artifact directory for a feature, rooted in the current working directory. */
+/**
+ * Returns the artifact directory for a feature.
+ * When app_path is set: {app_path}/.frappe-builder/{featureId}/
+ * Fallback (no app_path): {cwd}/.frappe-builder/{featureId}/
+ */
 export function getArtifactDir(featureId: string): string {
-  return join(process.cwd(), ".frappe-builder-artifacts", featureId);
+  const row = db
+    .prepare("SELECT app_path FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { app_path: string | null } | undefined;
+  const root = row?.app_path ?? process.cwd();
+  return join(root, ".frappe-builder", featureId);
 }
 
 /**
@@ -71,6 +79,7 @@ progress:
 `;
 
   const artifactDir = getArtifactDir(featureId);
-  mkdirSync(artifactDir, { recursive: true });
-  writeFileSync(join(artifactDir, "sprint-status.yaml"), yaml, "utf-8");
+  const implDir = join(artifactDir, "implementation-artifacts");
+  mkdirSync(implDir, { recursive: true });
+  writeFileSync(join(implDir, "sprint-status.yaml"), yaml, "utf-8");
 }

package/state/db.ts

@@ -25,9 +25,9 @@ export function setDb(instance: DatabaseType): void {
  * 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.
+ * sitePath and appPath are optional so existing callers without them continue to work.
  */
-export function switchProject(newProjectId: string, sitePath?: string): void {
+export function switchProject(newProjectId: string, sitePath?: string, appPath?: string): void {
   db.transaction(() => {
     // 1. Read current active session before closing
     const current = db
@@ -63,12 +63,13 @@ export function switchProject(newProjectId: string, sitePath?: string): void {
 
     // 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)"
+      "INSERT INTO sessions (session_id, project_id, current_phase, site_path, app_path, started_at, is_active) VALUES (?, ?, ?, ?, ?, ?, 1)"
     ).run(
       crypto.randomUUID(),
       newProjectId,
       prior?.current_phase ?? "idle",
       sitePath ?? null,
+      appPath ?? null,
       new Date().toISOString()
     );
   })();

package/state/fsm.ts

@@ -7,7 +7,8 @@ export type Phase =
   | "planning"
   | "implementation"
   | "testing"
-  | "documentation";
+  | "documentation"
+  | "chain_running";  // sentinel: full-mode chain active externally, not an in-session FSM node
 
 export const ALL_PHASES: Phase[] = [
   "idle",
@@ -17,26 +18,34 @@ export const ALL_PHASES: Phase[] = [
   "implementation",
   "testing",
   "documentation",
+  "chain_running",
 ];
 
 function buildMachineStates() {
   return {
+    // Quick mode only: idle → implementation.
+    // Full mode phases (requirements, architecture, planning, testing, documentation)
+    // are handled by agent-chain.ts subprocesses — not in-session FSM transitions.
     idle: state(
-      transition("start_full", "requirements"),
-      transition("start_quick", "implementation") as never // quick mode bypass (Story 3.3)
+      transition("start_quick", "implementation")
     ),
-    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")),
+    // chain_running is a storage sentinel — not a FSM node with transitions.
+    // The parent session cannot transition out of chain_running via FSM events;
+    // the chain runner updates the DB directly when the chain completes.
   };
 }
 
-/** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay. */
+type FsmPhase = "idle" | "implementation" | "testing" | "documentation";
+const FSM_PHASES = new Set<string>(["idle", "implementation", "testing", "documentation"]);
+
+/** Creates a Robot3 FSM starting at the given phase — fast-forward, no event replay.
+ *  Non-FSM phases (chain_running, requirements, architecture, planning) fall back to idle. */
 export function createFsmAtPhase(phase: Phase) {
-  return createMachine(phase, buildMachineStates());
+  const fsmPhase: FsmPhase = FSM_PHASES.has(phase) ? (phase as FsmPhase) : "idle";
+  return createMachine(fsmPhase, buildMachineStates());
 }
 
 /**
@@ -45,18 +54,30 @@ export function createFsmAtPhase(phase: Phase) {
  */
 const TOOL_PHASE_MAP: Record<string, Phase | Phase[] | "any"> = {
   set_active_project: "any",
-  start_feature: "idle",
+  start_feature: "idle",          // blocked in chain_running to prevent double-start
   create_component: ["planning", "implementation"],
   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)
+  bench_execute: "any",
 };
 
+/** Always-allowed tools that bypass phase guard entirely. */
+const ALWAYS_ALLOWED_TOOLS = new Set([
+  "invoke_debugger",
+  "end_debug",
+  "spawn_agent",
+  "get_project_status",
+  "get_frappe_docs",
+]);
+
 /** 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 {
+  if (ALWAYS_ALLOWED_TOOLS.has(toolName)) return true;
+  // chain_running: only always-allowed tools pass; all others (including start_feature) are blocked
+  if (phase === "chain_running") return false;
   const validPhase = TOOL_PHASE_MAP[toolName];
   if (validPhase === undefined) return true; // unknown tool — do not block
   if (validPhase === "any") return true;

package/state/schema.ts

@@ -35,6 +35,9 @@ export function initSchema(db: Database): void {
       project_id    TEXT NOT NULL,
       current_phase TEXT NOT NULL DEFAULT 'idle',
       site_path     TEXT,
+      app_path      TEXT,
+      chain_step    TEXT,
+      chain_pid     INTEGER,
       feature_id    TEXT,
       component_id  TEXT,
       last_tool     TEXT,
@@ -56,6 +59,9 @@ export function migrateSchema(db: Database): void {
     "ALTER TABLE components ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0",
     "ALTER TABLE components ADD COLUMN created_at TEXT",
     "ALTER TABLE sessions ADD COLUMN component_id TEXT",
+    "ALTER TABLE sessions ADD COLUMN app_path TEXT",
+    "ALTER TABLE sessions ADD COLUMN chain_step TEXT",
+    "ALTER TABLE sessions ADD COLUMN chain_pid INTEGER",
   ];
   for (const sql of alters) {
     try { db.exec(sql); } catch { /* column already exists — safe to ignore */ }

package/tools/feature-tools.ts

@@ -4,6 +4,7 @@ import { appendEntry } from "../state/journal.js";
 import { loadConfig } from "../config/loader.js";
 import { coverageCheck } from "../gates/coverage-check.js";
 import { getArtifactDir, regenerateSprintStatus } from "../state/artifacts.js";
+import { spawnChain } from "../extensions/agent-chain.js";
 
 interface StartFeatureArgs {
   name: string;
@@ -15,11 +16,18 @@ function toFeatureId(name: string): string {
 }
 
 /**
- * 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.
+ * Creates a new feature row in state.db, applies the FSM phase transition,
+ * and links the feature to the active session.
+ *
+ * Phase transition is applied inside the tool (not deferred to afterToolCall) so
+ * the returned JSON reflects the actual post-transition phase. The agent reads
+ * this value directly — returning "idle" caused session confusion.
+ *
+ * quick mode → implementation immediately (in-session).
+ * full mode → chain_running (agent chain spawned as background process).
+ * Default mode is "quick".
  */
-export function startFeature({ name, mode = "full" }: StartFeatureArgs) {
+export async function startFeature({ name, mode = "quick" }: StartFeatureArgs) {
   const featureId = toFeatureId(name);
   const createdAt = new Date().toISOString();
 
@@ -27,18 +35,56 @@ export function startFeature({ name, mode = "full" }: StartFeatureArgs) {
     .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
     .get() as { session_id: string } | undefined;
 
+  if (mode === "quick") {
+    const newPhase = "implementation";
+    db.prepare(
+      "INSERT INTO features (feature_id, name, created_at, mode, current_phase) VALUES (?, ?, ?, ?, ?)"
+    ).run(featureId, name, createdAt, mode, newPhase);
+
+    db.transaction(() => {
+      db.prepare(
+        "UPDATE sessions SET feature_id = ?, current_phase = ? WHERE is_active = 1"
+      ).run(featureId, newPhase);
+    })();
+
+    appendEntry({
+      ts: createdAt,
+      sessionId: session?.session_id ?? "unknown",
+      type: "state_transition",
+      payload: { from: "idle", to: newPhase, feature: name, mode },
+    });
+
+    return { feature_id: featureId, name, mode, current_phase: newPhase, created_at: createdAt };
+  }
+
+  // Full mode: insert feature at "requirements", set session to chain_running, fire chain
   db.prepare(
-    "INSERT INTO features (feature_id, name, created_at, mode, current_phase) VALUES (?, ?, ?, ?, 'idle')"
-  ).run(featureId, name, createdAt, mode);
+    "INSERT INTO features (feature_id, name, created_at, mode, current_phase) VALUES (?, ?, ?, ?, ?)"
+  ).run(featureId, name, createdAt, mode, "requirements");
+
+  db.transaction(() => {
+    db.prepare(
+      "UPDATE sessions SET feature_id = ?, current_phase = ? WHERE is_active = 1"
+    ).run(featureId, "chain_running");
+  })();
 
   appendEntry({
     ts: createdAt,
     sessionId: session?.session_id ?? "unknown",
     type: "state_transition",
-    payload: { from: "idle", to: "feature_started", feature: name },
+    payload: { from: "idle", to: "chain_running", feature: name, mode },
+  });
+
+  const artifactDir = getArtifactDir(featureId);
+
+  // Fire-and-forget: chain runs independently in the background
+  setImmediate(() => {
+    Promise.resolve(spawnChain(featureId, name, artifactDir)).catch((err: unknown) => {
+      console.error(`[agent-chain] chain failed for ${featureId}: ${err}`);
+    });
   });
 
-  return { feature_id: featureId, name, mode, current_phase: "idle", created_at: createdAt };
+  return { feature_id: featureId, name, mode, current_phase: "chain_running", chain_started: true, created_at: createdAt };
 }
 
 interface CreateComponentArgs {

package/tools/project-tools.ts

@@ -77,6 +77,7 @@ export function getProjectStatus(_args?: unknown): ProjectStatus {
 interface SetActiveProjectArgs {
   projectId: string;
   sitePath: string;
+  appPath?: string;
 }
 
 /**
@@ -86,9 +87,9 @@ interface SetActiveProjectArgs {
  * The state_transition JSONL entry is written inside switchProject() —
  * no second appendEntry() call here.
  */
-export async function setActiveProject({ projectId, sitePath }: SetActiveProjectArgs) {
+export async function setActiveProject({ projectId, sitePath, appPath }: SetActiveProjectArgs) {
   // Flush current state + create new session (JSONL entry written internally)
-  switchProject(projectId, sitePath);
+  switchProject(projectId, sitePath, appPath);
 
   // Reload system prompt with new project context
   await reloadSessionContext();
@@ -101,6 +102,7 @@ export async function setActiveProject({ projectId, sitePath }: SetActiveProject
   return {
     project_id: projectId,
     site_path: sitePath,
+    app_path: appPath ?? null,
     phase: session?.current_phase ?? "idle",
     context_reloaded: true,
   };