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

package/.frappe-builder-artifacts/po-approval/sprint-status.yaml

@@ -0,0 +1,15 @@
+feature_id: po-approval
+feature_name: "PO Approval"
+mode: full
+phase: testing
+updated_at: 2026-03-28T07:56:22.695Z
+
+components:
+  - id: final-comp
+    sort_order: 0
+    status: complete
+    completed_at: 2026-03-28T07:56:22.695Z
+
+progress:
+  done: 1
+  total: 1

package/extensions/frappe-state.ts

@@ -5,6 +5,11 @@ import { appendEntry } from "../state/journal.js";
 import { buildStateContext, loadSpecialist, loadDebuggerSpecialist } from "./frappe-session.js";
 import { loadCredentials } from "../config/loader.js";
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function (pi: any) {
+  pi.on("after_tool_call", handleAfterToolCall);
+}
+
 /** Reads current_phase and feature_id from the active session. */
 function readSessionState(): { currentPhase: string; activeFeatureId: string | null } {
   const row = db
@@ -24,6 +29,29 @@ function getActiveSessionId(): string {
   return row?.session_id ?? "unknown";
 }
 
+/** Type guard for createComponent() return value. */
+function isCreateComponentResult(value: unknown): value is { feature_id: string; component_id: string; artifact_dir: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "feature_id" in value &&
+    "component_id" in value &&
+    "artifact_dir" in value
+  );
+}
+
+/** Type guard for completeComponent() success return value. */
+function isCompleteComponentResult(value: unknown): value is { feature_id: string; component_id: string; status: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "feature_id" in value &&
+    "component_id" in value &&
+    "status" in value &&
+    (value as Record<string, unknown>).status === "complete"
+  );
+}
+
 /** Type guard for SpawnAgentResult from agent-tools.ts. */
 function isSpawnAgentResult(value: unknown): value is { status: string; skill: string; trigger: string } {
   return (
@@ -199,6 +227,51 @@ export async function handleAfterToolCall(
       }
     }
 
+    // create_component JSONL logging — no phase transition, no specialist change
+    if (toolName === "create_component") {
+      const firstText = context.result.content.find((c) => c.type === "text") as TextContent | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try { parsed = JSON.parse(firstText.text); } catch { /* skip */ }
+        if (isCreateComponentResult(parsed)) {
+          appendEntry({
+            ts: new Date().toISOString(),
+            sessionId,
+            type: "tool_call",
+            payload: { tool: "create_component", feature: parsed.feature_id, component: parsed.component_id },
+          });
+        }
+      }
+    }
+
+    // complete_component — check if all components done and inject completion hint
+    if (toolName === "complete_component") {
+      const firstText = context.result.content.find((c) => c.type === "text") as TextContent | undefined;
+      if (firstText) {
+        let parsed: unknown = null;
+        try { parsed = JSON.parse(firstText.text); } catch { /* skip */ }
+        if (isCompleteComponentResult(parsed)) {
+          appendEntry({
+            ts: new Date().toISOString(),
+            sessionId,
+            type: "tool_call",
+            payload: { tool: "complete_component", feature: parsed.feature_id, component: parsed.component_id },
+          });
+          // Check if all components for this feature are now complete
+          const feature = db
+            .prepare("SELECT progress_done, progress_total FROM features WHERE feature_id = ?")
+            .get(parsed.feature_id) as { progress_done: number; progress_total: number } | undefined;
+          if (feature && feature.progress_total > 0 && feature.progress_done >= feature.progress_total) {
+            const hint: TextContent = {
+              type: "text",
+              text: `\n\n✓ All ${feature.progress_total} components complete for this feature. Ready to advance to the next phase.`,
+            };
+            return { content: [...context.result.content, hint] };
+          }
+        }
+      }
+    }
+
     // End debug — restore previous phase specialist (Story 3.5) — no phase transition
     if (toolName === "end_debug") {
       const { currentPhase, activeFeatureId } = readSessionState();

package/extensions/frappe-ui.ts

@@ -4,45 +4,29 @@ import { db, getCurrentPhase } from "../state/db.js";
 interface FooterState {
   projectId: string | null;
   featureName: string | null;
-  phase: string;
-  tokenCount: number;
+  componentId: string | null;
 }
 
 function readFooterState(): FooterState {
   try {
     const session = db
       .prepare(
-        `SELECT s.project_id, f.name AS feature_name, s.current_phase
+        `SELECT s.project_id, f.name AS feature_name, s.component_id
          FROM sessions s
          LEFT JOIN features f ON f.feature_id = s.feature_id
          WHERE s.is_active = 1 LIMIT 1`
       )
       .get() as
-      | { project_id: string | null; feature_name: string | null; current_phase: string }
+      | { project_id: string | null; feature_name: string | null; component_id: string | null }
       | undefined;
 
-    // Token count: count journal_entries for active session; table may not exist yet
-    let tokenCount = 0;
-    try {
-      const tokenRow = db
-        .prepare(
-          `SELECT COUNT(*) as count FROM journal_entries
-           WHERE session_id = (SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1)`
-        )
-        .get() as { count: number } | undefined;
-      tokenCount = tokenRow?.count ?? 0;
-    } catch {
-      // journal_entries table not yet created — default to 0
-    }
-
     return {
       projectId: session?.project_id ?? null,
       featureName: session?.feature_name ?? null,
-      phase: session?.current_phase ?? "idle",
-      tokenCount,
+      componentId: session?.component_id ?? null,
     };
   } catch {
-    return { projectId: null, featureName: null, phase: "idle", tokenCount: 0 };
+    return { projectId: null, featureName: null, componentId: null };
   }
 }
 
@@ -52,12 +36,15 @@ function readFooterState(): FooterState {
  */
 export function formatFooter(state: FooterState): string {
   if (!state.projectId) {
-    return `No active project | Phase: ${state.phase}`;
+    return `No active project`;
   }
   if (!state.featureName) {
-    return `Project: ${state.projectId} | No active feature | Phase: ${state.phase}`;
+    return `Project: ${state.projectId} | No active feature`;
   }
-  return `Project: ${state.projectId} | Feature: ${state.featureName} | Phase: ${state.phase} | Tokens: ${state.tokenCount}`;
+  if (!state.componentId) {
+    return `Project: ${state.projectId} | Feature: ${state.featureName}`;
+  }
+  return `Project: ${state.projectId} | Feature: ${state.featureName} | Component: ${state.componentId}`;
 }
 
 function renderFooter(): void {
@@ -104,16 +91,35 @@ export async function handleAfterToolCall(
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function (pi: any) {
-  pi.on("session_start", () => {
-    renderFooter();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("session_start", (_event: any, ctx: any) => {
+    try {
+      ctx.ui.setStatus("frappe-builder", formatFooter(readFooterState()));
+    } catch {
+      renderFooter();
+    }
   });
 
   // Announcement hook — fires before FSM guard in frappe-workflow.ts (FR25)
-  pi.on("tool_call", (event: { toolName?: string }) => {
-    return handleBeforeToolCall(event.toolName ?? "");
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("tool_call", (event: any, ctx: any) => {
+    try {
+      const phase = getCurrentPhase();
+      ctx.ui.setStatus("frappe-builder", `→ Calling ${event.toolName ?? ""} [${phase}]`);
+    } catch {
+      handleBeforeToolCall(event.toolName ?? "");
+    }
   });
 
-  pi.on("after_tool_call", async (context: AfterToolCallContext) => {
-    return await handleAfterToolCall(context);
+  // "tool_result" is the pi-coding-agent ExtensionAPI event name for after-tool hooks.
+  // Using ctx.ui.setStatus() injects into pi's native footer row instead of writing
+  // raw bytes to stderr (which pi's TUI redraws over).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pi.on("tool_result", (_event: any, ctx: any) => {
+    try {
+      ctx.ui.setStatus("frappe-builder", formatFooter(readFooterState()));
+    } catch {
+      renderFooter();
+    }
   });
 }

package/extensions/frappe-workflow.ts

@@ -6,21 +6,22 @@ interface BlockedResponse {
   blocked: true;
   tool: string;
   current_phase: Phase;
-  valid_phase: Phase | "any";
+  valid_phase: string;
   message: string;
 }
 
 function buildBlockedResponse(
   tool: string,
   currentPhase: Phase,
-  validPhase: Phase | "any"
+  validPhase: Phase | Phase[] | "any"
 ): BlockedResponse {
+  const validLabel = Array.isArray(validPhase) ? validPhase.join(", ") : validPhase;
   return {
     blocked: true,
     tool,
     current_phase: currentPhase,
-    valid_phase: validPhase,
-    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validPhase}`,
+    valid_phase: validLabel,
+    message: `${tool} is not available in ${currentPhase} phase. Available in: ${validLabel}`,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.11",
+  "version": "1.1.0-dev.13",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {

package/state/artifacts.ts

@@ -0,0 +1,76 @@
+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. */
+export function getArtifactDir(featureId: string): string {
+  return join(process.cwd(), ".frappe-builder-artifacts", featureId);
+}
+
+/**
+ * Regenerates sprint-status.yaml for the given feature from current DB state.
+ * Called after every create_component and complete_component.
+ * Creates the artifact directory if it does not exist.
+ * Non-fatal — caller should catch any errors.
+ */
+export function regenerateSprintStatus(featureId: string): void {
+  const feature = db
+    .prepare("SELECT feature_id, name, mode, current_phase FROM features WHERE feature_id = ?")
+    .get(featureId) as
+    | { feature_id: string; name: string; mode: string; current_phase: string }
+    | undefined;
+
+  if (!feature) return;
+
+  const components = db
+    .prepare(
+      `SELECT component_id, description, sort_order, status, completed_at
+       FROM components WHERE feature_id = ?
+       ORDER BY sort_order ASC, component_id ASC`
+    )
+    .all(featureId) as Array<{
+      component_id: string;
+      description: string | null;
+      sort_order: number;
+      status: string;
+      completed_at: string | null;
+    }>;
+
+  const done = components.filter((c) => c.status === "complete").length;
+  const total = components.length;
+
+  const componentLines = components
+    .map((c) => {
+      const descLine = c.description
+        ? `    description: "${c.description.replace(/"/g, '\\"')}"`
+        : "";
+      return [
+        `  - id: ${c.component_id}`,
+        descLine,
+        `    sort_order: ${c.sort_order}`,
+        `    status: ${c.status}`,
+        `    completed_at: ${c.completed_at ?? "null"}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+
+  const yaml = `feature_id: ${feature.feature_id}
+feature_name: "${feature.name.replace(/"/g, '\\"')}"
+mode: ${feature.mode}
+phase: ${feature.current_phase}
+updated_at: ${new Date().toISOString()}
+
+components:
+${componentLines || "  []"}
+
+progress:
+  done: ${done}
+  total: ${total}
+`;
+
+  const artifactDir = getArtifactDir(featureId);
+  mkdirSync(artifactDir, { recursive: true });
+  writeFileSync(join(artifactDir, "sprint-status.yaml"), yaml, "utf-8");
+}

package/state/db.ts

@@ -1,7 +1,7 @@
 import Database from "better-sqlite3";
 import type { Database as DatabaseType } from "better-sqlite3";
 import { mkdirSync } from "node:fs";
-import { initSchema } from "./schema.js";
+import { initSchema, migrateSchema } from "./schema.js";
 import { appendEntry } from "./journal.js";
 
 mkdirSync(".fb", { recursive: true });
@@ -10,6 +10,7 @@ mkdirSync(".fb", { recursive: true });
 export let db: DatabaseType = new Database(".fb/state.db");
 
 initSchema(db);
+migrateSchema(db);
 
 /**
  * Replaces the db singleton — intended for test use only.

package/state/fsm.ts

@@ -43,9 +43,10 @@ export function createFsmAtPhase(phase: Phase) {
  * 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"> = {
+const TOOL_PHASE_MAP: Record<string, Phase | Phase[] | "any"> = {
   set_active_project: "any",
   start_feature: "idle",
+  create_component: ["planning", "implementation"],
   complete_component: "implementation",
   scaffold_doctype: "implementation",
   run_tests: "testing",
@@ -59,10 +60,11 @@ 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;
+  if (Array.isArray(validPhase)) return validPhase.includes(phase);
   return validPhase === phase;
 }
 
 /** Returns the phase where toolName is valid, or 'any' for unrestricted/unknown tools. */
-export function getValidPhase(toolName: string): Phase | "any" {
+export function getValidPhase(toolName: string): Phase | Phase[] | "any" {
   return TOOL_PHASE_MAP[toolName] ?? "any";
 }

package/state/schema.ts

@@ -18,9 +18,13 @@ export function initSchema(db: Database): void {
     );
 
     CREATE TABLE IF NOT EXISTS components (
-      component_id TEXT NOT NULL,
-      feature_id   TEXT NOT NULL,
-      status       TEXT NOT NULL DEFAULT 'in-progress',
+      component_id TEXT    NOT NULL,
+      feature_id   TEXT    NOT NULL,
+      status       TEXT    NOT NULL DEFAULT 'in-progress'
+        CHECK (status IN ('in-progress', 'complete')),
+      description  TEXT,
+      sort_order   INTEGER NOT NULL DEFAULT 0,
+      created_at   TEXT,
       completed_at TEXT,
       PRIMARY KEY (feature_id, component_id),
       FOREIGN KEY (feature_id) REFERENCES features(feature_id)
@@ -32,6 +36,7 @@ export function initSchema(db: Database): void {
       current_phase TEXT NOT NULL DEFAULT 'idle',
       site_path     TEXT,
       feature_id    TEXT,
+      component_id  TEXT,
       last_tool     TEXT,
       started_at    TEXT NOT NULL,
       ended_at      TEXT,
@@ -39,3 +44,20 @@ export function initSchema(db: Database): void {
     );
   `);
 }
+
+/**
+ * Adds new columns to existing databases without dropping data.
+ * Safe to call on any DB version — ignores "duplicate column" errors.
+ * Call this after initSchema() in db.ts.
+ */
+export function migrateSchema(db: Database): void {
+  const alters = [
+    "ALTER TABLE components ADD COLUMN description TEXT",
+    "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",
+  ];
+  for (const sql of alters) {
+    try { db.exec(sql); } catch { /* column already exists — safe to ignore */ }
+  }
+}

package/tools/feature-tools.ts

@@ -3,6 +3,7 @@ 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";
+import { getArtifactDir, regenerateSprintStatus } from "../state/artifacts.js";
 
 interface StartFeatureArgs {
   name: string;
@@ -40,6 +41,72 @@ export function startFeature({ name, mode = "full" }: StartFeatureArgs) {
   return { feature_id: featureId, name, mode, current_phase: "idle", created_at: createdAt };
 }
 
+interface CreateComponentArgs {
+  featureId: string;
+  componentId: string;
+  description?: string;
+  sortOrder?: number;
+}
+
+/**
+ * Explicitly creates a component for a feature with status 'in-progress'.
+ * Sets this component as the active component on the session (for footer display).
+ * Regenerates sprint-status.yaml in .frappe-builder-artifacts/{featureId}/.
+ *
+ * Call this during the planning phase (full mode) or at the start of implementation
+ * (quick mode) — before work begins, not at completion time.
+ */
+export function createComponent({ featureId, componentId, description, sortOrder = 0 }: CreateComponentArgs) {
+  const createdAt = new Date().toISOString();
+
+  const feature = db
+    .prepare("SELECT feature_id FROM features WHERE feature_id = ?")
+    .get(featureId) as { feature_id: string } | undefined;
+
+  if (!feature) {
+    return { error: `Feature '${featureId}' not found. Call start_feature first.` };
+  }
+
+  const session = db
+    .prepare("SELECT session_id FROM sessions WHERE is_active = 1 LIMIT 1")
+    .get() as { session_id: string } | undefined;
+
+  const existing = db
+    .prepare("SELECT component_id FROM components WHERE feature_id = ? AND component_id = ?")
+    .get(featureId, componentId) as { component_id: string } | undefined;
+
+  db.prepare(`
+    INSERT INTO components (feature_id, component_id, status, description, sort_order, created_at)
+    VALUES (?, ?, 'in-progress', ?, ?, ?)
+    ON CONFLICT(feature_id, component_id)
+    DO UPDATE SET description = excluded.description, sort_order = excluded.sort_order
+  `).run(featureId, componentId, description ?? null, sortOrder, createdAt);
+
+  if (!existing) {
+    db.prepare("UPDATE features SET progress_total = progress_total + 1 WHERE feature_id = ?")
+      .run(featureId);
+  }
+
+  db.prepare("UPDATE sessions SET component_id = ? WHERE is_active = 1")
+    .run(componentId);
+
+  regenerateSprintStatus(featureId);
+
+  appendEntry({
+    ts: createdAt,
+    sessionId: session?.session_id ?? "unknown",
+    type: "state_transition",
+    payload: { feature: featureId, component: componentId, action: "create_component", status: "in-progress" },
+  });
+
+  return {
+    feature_id: featureId,
+    component_id: componentId,
+    status: "in-progress",
+    artifact_dir: getArtifactDir(featureId),
+  };
+}
+
 interface CompleteComponentArgs {
   featureId: string;
   componentId: string;
@@ -105,6 +172,10 @@ export async function completeComponent({ featureId, componentId }: CompleteComp
     DO UPDATE SET status = 'complete', completed_at = excluded.completed_at
   `).run(featureId, componentId, completedAt);
 
+  db.prepare("UPDATE sessions SET component_id = NULL WHERE is_active = 1").run();
+  db.prepare("UPDATE features SET progress_done = progress_done + 1 WHERE feature_id = ?").run(featureId);
+  regenerateSprintStatus(featureId);
+
   appendEntry({
     ts: completedAt,
     sessionId,