pi-blueprint 0.2.0

package/src/storage.ts

@@ -0,0 +1,83 @@
+import { mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { renderPlanMarkdown } from "./plan-renderer.js";
+import type {
+  Blueprint,
+  BlueprintIndex,
+  HistoryEntry,
+  SessionsState,
+} from "./types.js";
+
+export function getBaseDir(baseDir?: string): string {
+  return baseDir ?? join(homedir(), ".pi", "blueprints");
+}
+
+export function getBlueprintDir(blueprintId: string, baseDir?: string): string {
+  return join(getBaseDir(baseDir), blueprintId);
+}
+
+export function ensureStorageLayout(blueprintId: string, baseDir?: string): void {
+  const dir = getBlueprintDir(blueprintId, baseDir);
+  mkdirSync(dir, { recursive: true });
+}
+
+export function ensureBaseDir(baseDir?: string): void {
+  mkdirSync(getBaseDir(baseDir), { recursive: true });
+}
+
+export function loadIndex(baseDir?: string): BlueprintIndex | null {
+  const path = join(getBaseDir(baseDir), "index.json");
+  return readJson<BlueprintIndex>(path);
+}
+
+export function saveIndex(index: BlueprintIndex, baseDir?: string): void {
+  ensureBaseDir(baseDir);
+  const path = join(getBaseDir(baseDir), "index.json");
+  writeFileSync(path, JSON.stringify(index, null, 2) + "\n");
+}
+
+export function loadBlueprint(blueprintId: string, baseDir?: string): Blueprint | null {
+  const path = join(getBlueprintDir(blueprintId, baseDir), "state.json");
+  return readJson<Blueprint>(path);
+}
+
+export function saveBlueprint(blueprint: Blueprint, baseDir?: string): void {
+  ensureStorageLayout(blueprint.id, baseDir);
+  const dir = getBlueprintDir(blueprint.id, baseDir);
+  writeFileSync(join(dir, "state.json"), JSON.stringify(blueprint, null, 2) + "\n");
+  writeFileSync(join(dir, "plan.md"), renderPlanMarkdown(blueprint));
+}
+
+export function appendHistory(
+  blueprintId: string,
+  entry: HistoryEntry,
+  baseDir?: string,
+): void {
+  ensureStorageLayout(blueprintId, baseDir);
+  const path = join(getBlueprintDir(blueprintId, baseDir), "history.jsonl");
+  appendFileSync(path, JSON.stringify(entry) + "\n");
+}
+
+export function loadSessions(blueprintId: string, baseDir?: string): SessionsState | null {
+  const path = join(getBlueprintDir(blueprintId, baseDir), "sessions.json");
+  return readJson<SessionsState>(path);
+}
+
+export function saveSessions(
+  blueprintId: string,
+  sessions: SessionsState,
+  baseDir?: string,
+): void {
+  ensureStorageLayout(blueprintId, baseDir);
+  const path = join(getBlueprintDir(blueprintId, baseDir), "sessions.json");
+  writeFileSync(path, JSON.stringify(sessions, null, 2) + "\n");
+}
+
+function readJson<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+export type TaskStatus = "pending" | "in_progress" | "completed" | "blocked" | "skipped";
+
+export type PhaseStatus = "pending" | "active" | "completed" | "verified";
+
+export type VerificationType = "tests_pass" | "typecheck_clean" | "user_approval" | "custom_command";
+
+export type BlueprintStatus = "draft" | "active" | "completed" | "abandoned";
+
+export type HistoryEventType =
+  | "blueprint_created"
+  | "task_started"
+  | "task_completed"
+  | "task_blocked"
+  | "task_skipped"
+  | "phase_started"
+  | "phase_completed"
+  | "phase_verified"
+  | "verification_passed"
+  | "verification_failed"
+  | "blueprint_completed"
+  | "blueprint_abandoned";
+
+export interface Task {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: TaskStatus;
+  readonly acceptance_criteria: readonly string[];
+  readonly file_targets: readonly string[];
+  readonly dependencies: readonly string[];
+  readonly started_at: string | null;
+  readonly completed_at: string | null;
+  readonly session_id: string | null;
+  readonly notes: string | null;
+}
+
+export interface VerificationGate {
+  readonly type: VerificationType;
+  readonly command: string | null;
+  readonly description: string;
+  readonly passed: boolean;
+  readonly last_checked_at: string | null;
+  readonly error_message: string | null;
+}
+
+export interface Phase {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: PhaseStatus;
+  readonly tasks: readonly Task[];
+  readonly verification_gates: readonly VerificationGate[];
+  readonly started_at: string | null;
+  readonly completed_at: string | null;
+}
+
+export interface Blueprint {
+  readonly id: string;
+  readonly objective: string;
+  readonly project_id: string;
+  readonly status: BlueprintStatus;
+  readonly created_at: string;
+  readonly updated_at: string;
+  readonly phases: readonly Phase[];
+  readonly active_phase_id: string | null;
+  readonly active_task_id: string | null;
+}
+
+export interface HistoryEntry {
+  readonly timestamp: string;
+  readonly event: HistoryEventType;
+  readonly phase_id: string | null;
+  readonly task_id: string | null;
+  readonly session_id: string;
+  readonly details: string;
+}
+
+export interface SessionRecord {
+  readonly session_id: string;
+  readonly started_at: string;
+  readonly ended_at: string | null;
+  readonly tasks_worked: readonly string[];
+  readonly tasks_completed: readonly string[];
+}
+
+export interface SessionsState {
+  readonly sessions: readonly SessionRecord[];
+}
+
+export interface BlueprintIndexEntry {
+  readonly id: string;
+  readonly objective: string;
+  readonly status: BlueprintStatus;
+  readonly created_at: string;
+  readonly project_id: string;
+}
+
+export interface BlueprintIndex {
+  readonly active_blueprint_id: string | null;
+  readonly blueprints: readonly BlueprintIndexEntry[];
+}
+
+export interface ProjectInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly root: string;
+}
+
+export interface BlueprintExtensionState {
+  readonly project: ProjectInfo | null;
+  readonly blueprint: Blueprint | null;
+  readonly sessionId: string;
+}
+
+export interface StateRef {
+  get: () => BlueprintExtensionState;
+  set: (s: BlueprintExtensionState) => void;
+}
+
+export interface VerificationResult {
+  readonly passed: boolean;
+  readonly output: string;
+  readonly duration_ms: number;
+}
+
+export function isTaskDone(task: Task): boolean {
+  return task.status === "completed" || task.status === "skipped";
+}
+
+export function getCompletedTaskIds(tasks: readonly Task[]): Set<string> {
+  return new Set(tasks.filter(isTaskDone).map((t) => t.id));
+}

package/src/verification.ts

@@ -0,0 +1,60 @@
+import { execSync } from "node:child_process";
+import type { VerificationGate, VerificationResult } from "./types.js";
+
+export function runGate(gate: VerificationGate, cwd: string): VerificationResult {
+  if (gate.type === "user_approval") {
+    return { passed: false, output: "Requires user approval", duration_ms: 0 };
+  }
+
+  const command = resolveCommand(gate);
+  if (!command) {
+    return { passed: false, output: `No command for gate type: ${gate.type}`, duration_ms: 0 };
+  }
+
+  const start = Date.now();
+  try {
+    const output = execSync(command, {
+      cwd,
+      encoding: "utf-8",
+      timeout: 120_000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { passed: true, output, duration_ms: Date.now() - start };
+  } catch (err: unknown) {
+    const duration_ms = Date.now() - start;
+    const output = extractExecError(err);
+    return { passed: false, output, duration_ms };
+  }
+}
+
+export function runAllGates(
+  gates: readonly VerificationGate[],
+  cwd: string,
+): readonly VerificationResult[] {
+  return gates
+    .filter((g) => g.type !== "user_approval")
+    .map((gate) => runGate(gate, cwd));
+}
+
+function resolveCommand(gate: VerificationGate): string | null {
+  switch (gate.type) {
+    case "tests_pass":
+      return "npm test";
+    case "typecheck_clean":
+      return "npx tsc --noEmit";
+    case "custom_command":
+      return gate.command;
+    case "user_approval":
+      return null;
+  }
+}
+
+function extractExecError(err: unknown): string {
+  if (err && typeof err === "object") {
+    const obj = err as Record<string, unknown>;
+    if (typeof obj["stderr"] === "string" && obj["stderr"]) return obj["stderr"];
+    if (typeof obj["stdout"] === "string" && obj["stdout"]) return obj["stdout"];
+    if (typeof obj["message"] === "string") return obj["message"];
+  }
+  return "Unknown error";
+}