pi-crew 0.3.9 → 0.5.0

package/src/state/crew-init.ts

@@ -0,0 +1,121 @@
+/**
+ * Auto-initialize .crew directory structure and .gitignore entries.
+ * Called on first team run in a workspace to ensure all required
+ * directories and files exist.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { updateGitignore } from "./gitignore-manager.ts";
+
+/** README content for the .crew directory. */
+const CREW_README = `# .crew — pi-crew Runtime Directory
+
+This directory contains pi-crew runtime state and artifacts.
+
+## What's Here
+
+| Directory | Purpose | Commit? |
+|-----------|---------|---------|
+| \`state/runs/\` | Run manifests, tasks, events | No |
+| \`state/subagents/\` | Subagent state | No |
+| \`artifacts/\` | Run outputs (test files, docs, etc.) | Optional |
+| \`cache/\` | Cached run results (fingerprint-based) | No |
+| \`graphs/\` | Archived run graphs | Optional |
+| \`audit/\` | Security event logs | No |
+
+## Cleanup
+
+To prune old runs:
+\`\`\`bash
+team action='prune' keep=5
+\`\`\`
+
+To clear cache:
+\`\`\`bash
+team action='cache' action='clear'
+\`\`\`
+`;
+
+/**
+ * Ensure the .crew directory structure exists with all required subdirectories,
+ * placeholder files, README, and .gitignore entries.
+ *
+ * Uses `projectCrewRoot()` to resolve the correct root (`.crew/` or `.pi/teams/`
+ * for legacy projects). Idempotent — safe to call multiple times.
+ */
+export async function ensureCrewDirectory(cwd: string): Promise<void> {
+	const crewRoot = projectCrewRoot(cwd);
+
+	// 1. Create directory structure
+	const dirs = [
+		crewRoot,
+		path.join(crewRoot, "state", "runs"),
+		path.join(crewRoot, "state", "subagents"),
+		path.join(crewRoot, "artifacts"),
+		path.join(crewRoot, "cache"),
+		path.join(crewRoot, "graphs"),
+		path.join(crewRoot, "audit"),
+	];
+
+	for (const dir of dirs) {
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+	}
+
+	// 2. Create .gitkeep placeholders in directories that should be tracked
+	const placeholders = [
+		path.join(crewRoot, "artifacts", ".gitkeep"),
+		path.join(crewRoot, "cache", ".gitkeep"),
+		path.join(crewRoot, "graphs", ".gitkeep"),
+		path.join(crewRoot, "audit", ".gitkeep"),
+	];
+
+	for (const placeholder of placeholders) {
+		if (!fs.existsSync(placeholder)) {
+			fs.writeFileSync(placeholder, "", "utf-8");
+		}
+	}
+
+	// 3. Write README.md (always overwrite to keep it current)
+	fs.writeFileSync(path.join(crewRoot, "README.md"), CREW_README, "utf-8");
+
+	// 4. Update .gitignore — resolve project root to place .gitignore correctly
+	// Find the repo root to place .gitignore at the project root (not inside .crew)
+	const repoRoot = findRepoRootForGitignore(cwd);
+	if (repoRoot) {
+		const gitignorePath = path.join(repoRoot, ".gitignore");
+		await updateGitignore(gitignorePath);
+	}
+}
+
+/**
+ * Find the appropriate project root for placing the .gitignore.
+ * Walks up from cwd to find a directory with project markers.
+ */
+function findRepoRootForGitignore(cwd: string): string | undefined {
+	// Use the same project root markers as paths.ts
+	const dirMarkers = [".git", ".pi", ".crew", ".hg", ".svn"];
+	const fileMarkers = [
+		"package.json",
+		"pyproject.toml",
+		"Cargo.toml",
+		"go.mod",
+	];
+	const root = path.parse(cwd).root;
+	let current = path.resolve(cwd);
+	while (current !== root) {
+		for (const marker of dirMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		for (const marker of fileMarkers) {
+			if (fs.existsSync(path.join(current, marker))) return current;
+		}
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	// No project root found — don't create .gitignore
+	return undefined;
+}

package/src/state/gitignore-manager.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage .gitignore entries for the .crew directory.
+ * Only adds entries if not already present; preserves existing content.
+ */
+import * as fs from "node:fs";
+
+/**
+ * Entries to add to .gitignore for .crew directory management.
+ *
+ * - `/.crew/` and `/.crew` ignore the core state directory.
+ * - Exceptions allow optional commit of artifacts/ and graphs/ (including their .gitkeep).
+ */
+const CREW_GITIGNORE_ENTRIES = [
+	"/.crew/",
+	"/.crew",
+	"!.crew/artifacts/",
+	"!.crew/graphs/",
+	"!.crew/artifacts/.gitkeep",
+	"!.crew/graphs/.gitkeep",
+];
+
+/**
+ * Update .gitignore with .crew entries. Creates the file if it doesn't exist.
+ * Preserves all existing content.
+ */
+export async function updateGitignore(gitignorePath: string): Promise<void> {
+	if (!fs.existsSync(gitignorePath)) {
+		fs.writeFileSync(
+			gitignorePath,
+			CREW_GITIGNORE_ENTRIES.join("\n") + "\n",
+			"utf-8",
+		);
+		return;
+	}
+
+	const current = fs.readFileSync(gitignorePath, "utf-8");
+	const existingLines = new Set(
+		current.split("\n").map((line) => line.trim()),
+	);
+
+	let appended = "";
+	for (const entry of CREW_GITIGNORE_ENTRIES) {
+		if (!existingLines.has(entry)) {
+			appended += `\n${entry}`;
+		}
+	}
+
+	if (appended) {
+		fs.writeFileSync(gitignorePath, current + appended, "utf-8");
+	}
+}

package/src/state/run-cache.ts

@@ -0,0 +1,176 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { projectCrewRoot } from "../utils/paths.ts";
+import type { TeamTaskState } from "./types.ts";
+
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export interface CacheEntry {
+  key: string;
+  runId: string;
+  status: string;
+  tasks: TeamTaskState[];
+  cachedAt: number;
+  expiresAt: number;
+  goal: string;
+  team: string;
+}
+
+interface CacheIndex {
+  [cacheKey: string]: string;
+}
+
+/**
+ * Compute a cache key from run parameters.
+ * Uses SHA-256 hash of normalized goal + team + workflow.
+ */
+export function computeRunCacheKey(goal: string, team: string, workflow: string, _cwd: string): string {
+  const normalized = goal.trim().toLowerCase().replace(/\s+/g, " ");
+  return crypto.createHash("sha256")
+    .update(normalized)
+    .update(team)
+    .update(workflow)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * Get the cache directory path.
+ */
+function cacheDir(cwd: string): string {
+  return path.join(projectCrewRoot(cwd), "cache");
+}
+
+/**
+ * Get cached run result if exists and valid.
+ * Returns null if cache miss or expired.
+ */
+export function getCachedRun(cwd: string, cacheKey: string): CacheEntry | null {
+  const dir = cacheDir(cwd);
+  const indexPath = path.join(dir, "index.json");
+
+  if (!fs.existsSync(indexPath)) return null;
+
+  try {
+    const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+    const entryPath = index[cacheKey];
+
+    if (!entryPath || !fs.existsSync(entryPath)) return null;
+
+    const entry = JSON.parse(fs.readFileSync(entryPath, "utf-8")) as CacheEntry;
+
+    if (Date.now() > entry.expiresAt) {
+      // Remove expired entry
+      try {
+        fs.unlinkSync(entryPath);
+      } catch { /* ignore */ }
+      delete index[cacheKey];
+      fs.writeFileSync(indexPath, JSON.stringify(index), "utf-8");
+      return null;
+    }
+
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save run result to cache.
+ */
+export function saveRunToCache(
+  cwd: string,
+  cacheKey: string,
+  runId: string,
+  status: string,
+  tasks: TeamTaskState[],
+  goal: string,
+  team: string,
+  ttlMs: number = DEFAULT_CACHE_TTL_MS,
+): void {
+  const dir = cacheDir(cwd);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const entry: CacheEntry = {
+    key: cacheKey,
+    runId,
+    status,
+    tasks,
+    cachedAt: Date.now(),
+    expiresAt: Date.now() + ttlMs,
+    goal,
+    team,
+  };
+
+  const entryPath = path.join(dir, `${cacheKey}.json`);
+  fs.writeFileSync(entryPath, JSON.stringify(entry), "utf-8");
+
+  // Update index
+  const indexPath = path.join(dir, "index.json");
+  const index: CacheIndex = fs.existsSync(indexPath)
+    ? JSON.parse(fs.readFileSync(indexPath, "utf-8"))
+    : {};
+
+  index[cacheKey] = entryPath;
+  fs.writeFileSync(indexPath, JSON.stringify(index), "utf-8");
+}
+
+/**
+ * Clear all cache entries.
+ */
+export function clearCache(cwd: string): void {
+  const dir = cacheDir(cwd);
+  if (!fs.existsSync(dir)) return;
+
+  const indexPath = path.join(dir, "index.json");
+  if (fs.existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+      for (const entryPath of Object.values(index)) {
+        try {
+          fs.unlinkSync(entryPath);
+        } catch { /* ignore */ }
+      }
+      fs.unlinkSync(indexPath);
+    } catch { /* ignore */ }
+  }
+
+  // Remove entry files not in index
+  const entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  for (const entry of entries) {
+    try {
+      fs.unlinkSync(path.join(dir, entry));
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Get cache stats.
+ */
+export function getCacheStats(cwd: string): { entries: number; sizeBytes: number } {
+  const dir = cacheDir(cwd);
+  if (!fs.existsSync(dir)) return { entries: 0, sizeBytes: 0 };
+
+  let sizeBytes = 0;
+  let entries = 0;
+  const indexPath = path.join(dir, "index.json");
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(fs.readFileSync(indexPath, "utf-8")) as CacheIndex;
+      entries = Object.keys(index).length;
+      for (const entryPath of Object.values(index)) {
+        try {
+          const stat = fs.statSync(entryPath);
+          sizeBytes += stat.size;
+        } catch { /* ignore */ }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return { entries, sizeBytes };
+}

package/src/state/run-graph.ts

@@ -0,0 +1,199 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest, TeamTaskState } from "./types.ts";
+
+export interface RunGraphNode {
+  id: string;
+  type: "run" | "task" | "agent" | "artifact" | "file";
+  name: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RunGraphEdge {
+  source: string;
+  target: string;
+  type: "dependsOn" | "produces" | "runs" | "contains";
+  weight?: number;
+}
+
+export interface RunGraphLayer {
+  name: string;
+  nodeIds: string[];
+}
+
+export interface RunGraph {
+  version: "1.0.0";
+  runId: string;
+  team: string;
+  workflow: string;
+  createdAt: string;
+  completedAt?: string;
+  status: string;
+  nodes: RunGraphNode[];
+  edges: RunGraphEdge[];
+  layers: RunGraphLayer[];
+}
+
+/**
+ * Build a unified run graph from manifest + tasks.
+ * Consolidates state into a single graph JSON for dashboard/API use.
+ */
+export function buildRunGraph(
+  manifest: TeamRunManifest,
+  tasks: TeamTaskState[],
+): RunGraph {
+  const nodes: RunGraphNode[] = [];
+  const edges: RunGraphEdge[] = [];
+  const nodeIds = new Set<string>();
+
+  // Add run node
+  const runId = manifest.runId;
+  nodes.push({
+    id: `run:${runId}`,
+    type: "run",
+    name: manifest.goal ?? runId,
+    metadata: {
+      team: manifest.team,
+      workflow: manifest.workflow,
+      status: manifest.status,
+      createdAt: manifest.createdAt,
+      completedAt: (manifest as Record<string, unknown>).completedAt,
+    },
+  });
+  nodeIds.add(`run:${runId}`);
+
+  // Add task nodes
+  for (const task of tasks) {
+    const taskId = `task:${task.id}`;
+    if (nodeIds.has(taskId)) continue;
+    nodeIds.add(taskId);
+
+    nodes.push({
+      id: taskId,
+      type: "task",
+      name: task.role,
+      metadata: {
+        phase: (task as Record<string, unknown>).phase,
+        status: task.status,
+        agentModel: (task as Record<string, unknown>).agentModel,
+        usage: (task as Record<string, unknown>).usage,
+        startedAt: task.startedAt,
+        finishedAt: task.finishedAt,
+      },
+    });
+
+    // Edge from run to task
+    edges.push({
+      source: `run:${runId}`,
+      target: taskId,
+      type: "contains",
+    });
+
+    // Edges from dependencies
+    for (const dep of task.dependsOn ?? []) {
+      edges.push({
+        source: `task:${dep}`,
+        target: taskId,
+        type: "dependsOn",
+        weight: 1.0,
+      });
+    }
+
+    // Edge from task to agent (if we have agent model info)
+    const agentModel = (task as Record<string, unknown>).agentModel as string | undefined;
+    if (agentModel) {
+      const agentId = `agent:${agentModel.replace(/[^a-zA-Z0-9-_]/g, "_")}`;
+      if (!nodeIds.has(agentId)) {
+        nodeIds.add(agentId);
+        nodes.push({ id: agentId, type: "agent", name: agentModel });
+      }
+      edges.push({
+        source: agentId,
+        target: taskId,
+        type: "runs",
+        weight: 0.9,
+      });
+    }
+  }
+
+  // Group by layer (based on phase)
+  const layerMap = new Map<string, string[]>();
+  for (const task of tasks) {
+    const phase = ((task as Record<string, unknown>).phase as string) ?? "unknown";
+    if (!layerMap.has(phase)) layerMap.set(phase, []);
+    layerMap.get(phase)!.push(`task:${task.id}`);
+  }
+
+  const layers: RunGraphLayer[] = [...layerMap.entries()].map(([name, nodeIdList]) => ({
+    name,
+    nodeIds: nodeIdList,
+  }));
+
+  return {
+    version: "1.0.0",
+    runId,
+    team: manifest.team ?? "unknown",
+    workflow: manifest.workflow ?? "unknown",
+    createdAt: manifest.createdAt,
+    completedAt: (manifest as Record<string, unknown>).completedAt as string | undefined,
+    status: manifest.status,
+    nodes,
+    edges,
+    layers,
+  };
+}
+
+/**
+ * Save run graph to disk in .crew/graphs/
+ */
+export function saveRunGraph(graph: RunGraph, cwd: string): string {
+  const crewRoot = path.join(cwd, ".crew");
+  const graphsDir = path.join(crewRoot, "graphs");
+
+  if (!fs.existsSync(graphsDir)) {
+    fs.mkdirSync(graphsDir, { recursive: true });
+  }
+
+  const graphPath = path.join(graphsDir, `${graph.runId}.json`);
+  fs.writeFileSync(graphPath, JSON.stringify(graph, null, 2), "utf-8");
+
+  return graphPath;
+}
+
+/**
+ * Load run graph from disk.
+ */
+export function loadRunGraph(cwd: string, runId: string): RunGraph | null {
+  const graphPath = path.join(cwd, ".crew", "graphs", `${runId}.json`);
+  if (!fs.existsSync(graphPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(graphPath, "utf-8")) as RunGraph;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all archived run graphs.
+ */
+export function listRunGraphs(cwd: string): string[] {
+  const graphsDir = path.join(cwd, ".crew", "graphs");
+  if (!fs.existsSync(graphsDir)) return [];
+
+  return fs.readdirSync(graphsDir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => f.replace(/\.json$/, ""));
+}
+
+/**
+ * Build and save run graph from manifest + tasks.
+ */
+export function buildAndSaveRunGraph(
+  manifest: TeamRunManifest,
+  tasks: TeamTaskState[],
+  cwd: string,
+): string {
+  const graph = buildRunGraph(manifest, tasks);
+  return saveRunGraph(graph, cwd);
+}