stagent 0.1.11 → 0.1.13

package/src/__tests__/e2e/helpers.ts

@@ -0,0 +1,286 @@
+/**
+ * E2E test helpers — HTTP client utilities for calling Stagent API endpoints.
+ *
+ * These helpers call the live Next.js dev/prod server. The base URL defaults
+ * to http://localhost:3000 and can be overridden via E2E_BASE_URL env var.
+ */
+
+export const BASE_URL = process.env.E2E_BASE_URL ?? "http://localhost:3000";
+
+// ---------------------------------------------------------------------------
+// Generic fetch wrapper
+// ---------------------------------------------------------------------------
+
+interface ApiResponse<T = unknown> {
+  status: number;
+  ok: boolean;
+  data: T;
+}
+
+async function api<T = unknown>(
+  path: string,
+  options?: RequestInit
+): Promise<ApiResponse<T>> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+  });
+  const data = (await res.json().catch(() => null)) as T;
+  return { status: res.status, ok: res.ok, data };
+}
+
+// ---------------------------------------------------------------------------
+// Projects
+// ---------------------------------------------------------------------------
+
+export interface ProjectPayload {
+  name: string;
+  description?: string;
+  workingDirectory?: string;
+}
+
+export async function createProject(payload: ProjectPayload) {
+  return api<{ id: string; name: string }>(
+    "/api/projects",
+    { method: "POST", body: JSON.stringify(payload) }
+  );
+}
+
+export async function deleteProject(id: string) {
+  return api(`/api/projects/${id}`, { method: "DELETE" });
+}
+
+// ---------------------------------------------------------------------------
+// Tasks
+// ---------------------------------------------------------------------------
+
+export interface TaskPayload {
+  title: string;
+  description?: string;
+  projectId?: string;
+  priority?: number;
+  assignedAgent?: string;
+  agentProfile?: string;
+}
+
+export interface TaskRow {
+  id: string;
+  title: string;
+  status: string;
+  result: string | null;
+  assignedAgent: string | null;
+  agentProfile: string | null;
+  projectId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export async function createTask(payload: TaskPayload) {
+  return api<TaskRow>("/api/tasks", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function getTask(id: string) {
+  return api<TaskRow>(`/api/tasks/${id}`);
+}
+
+export async function updateTask(id: string, payload: Partial<TaskPayload & { status: string }>) {
+  return api<TaskRow>(`/api/tasks/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function deleteTask(id: string) {
+  return api(`/api/tasks/${id}`, { method: "DELETE" });
+}
+
+export async function executeTask(id: string) {
+  return api<{ message: string }>(`/api/tasks/${id}/execute`, {
+    method: "POST",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Workflows
+// ---------------------------------------------------------------------------
+
+export interface WorkflowStep {
+  id: string;
+  name: string;
+  prompt: string;
+  requiresApproval?: boolean;
+  dependsOn?: string[];
+  assignedAgent?: string;
+  agentProfile?: string;
+}
+
+export interface WorkflowPayload {
+  name: string;
+  projectId?: string;
+  definition: {
+    pattern: string;
+    steps: WorkflowStep[];
+  };
+}
+
+export interface WorkflowRow {
+  id: string;
+  name: string;
+  status: string;
+  definition: string;
+  projectId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export async function createWorkflow(payload: WorkflowPayload) {
+  return api<WorkflowRow>("/api/workflows", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function getWorkflow(id: string) {
+  return api<WorkflowRow>(`/api/workflows/${id}`);
+}
+
+export async function executeWorkflow(id: string) {
+  return api<{ status: string; workflowId: string }>(
+    `/api/workflows/${id}/execute`,
+    { method: "POST" }
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Blueprints
+// ---------------------------------------------------------------------------
+
+export async function listBlueprints() {
+  return api<unknown[]>("/api/blueprints");
+}
+
+export async function instantiateBlueprint(
+  blueprintId: string,
+  variables: Record<string, string>,
+  projectId?: string
+) {
+  return api<{ workflow: WorkflowRow }>(
+    `/api/blueprints/${blueprintId}/instantiate`,
+    {
+      method: "POST",
+      body: JSON.stringify({ variables, projectId }),
+    }
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Profiles
+// ---------------------------------------------------------------------------
+
+export async function listProfiles() {
+  return api<unknown[]>("/api/profiles");
+}
+
+// ---------------------------------------------------------------------------
+// Runtime connectivity
+// ---------------------------------------------------------------------------
+
+export async function checkRuntimeConnectivity(runtimeId: string) {
+  return api<{ connected: boolean; method?: string }>(
+    `/api/settings/connectivity?runtime=${runtimeId}`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Polling helpers
+// ---------------------------------------------------------------------------
+
+const POLL_INTERVAL_MS = 3_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+const TERMINAL_TASK_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+const TERMINAL_WORKFLOW_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+export async function pollTaskUntilDone(
+  taskId: string,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+): Promise<TaskRow> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const { data } = await getTask(taskId);
+    if (data && TERMINAL_TASK_STATUSES.has(data.status)) {
+      return data;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(
+    `Task ${taskId} did not reach a terminal status within ${timeoutMs}ms`
+  );
+}
+
+export async function pollWorkflowUntilDone(
+  workflowId: string,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+): Promise<WorkflowRow> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const { data } = await getWorkflow(workflowId);
+    if (data && TERMINAL_WORKFLOW_STATUSES.has(data.status)) {
+      return data;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(
+    `Workflow ${workflowId} did not reach a terminal status within ${timeoutMs}ms`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if a runtime is available by calling the connectivity endpoint.
+ * Returns true if the runtime responds as connected.
+ */
+export async function isRuntimeAvailable(
+  runtimeId: string
+): Promise<boolean> {
+  try {
+    const { ok, data } = await checkRuntimeConnectivity(runtimeId);
+    return ok && !!data?.connected;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the Stagent server is reachable.
+ */
+export async function isServerReachable(): Promise<boolean> {
+  try {
+    const res = await fetch(`${BASE_URL}/api/projects`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

package/src/__tests__/e2e/parallel-workflow.test.ts

@@ -0,0 +1,120 @@
+/**
+ * E2E: Parallel workflow execution.
+ *
+ * Tests that parallel workflows run branches concurrently and
+ * synthesis steps wait for all dependencies before executing.
+ */
+
+import {
+  setupE2E,
+  teardownE2E,
+  testProjectId,
+  claudeAvailable,
+  codexAvailable,
+} from "./setup";
+import {
+  createWorkflow,
+  executeWorkflow,
+  pollWorkflowUntilDone,
+} from "./helpers";
+
+beforeAll(async () => {
+  await setupE2E();
+});
+
+afterAll(async () => {
+  await teardownE2E();
+});
+
+describe("Parallel Workflow — Claude Code", () => {
+  it.skipIf(!claudeAvailable)(
+    "runs branches concurrently with synthesis",
+    async () => {
+      const { ok, data: workflow } = await createWorkflow({
+        name: "E2E Parallel Test",
+        projectId: testProjectId,
+        definition: {
+          pattern: "parallel",
+          steps: [
+            {
+              id: "metrics",
+              name: "Code Metrics",
+              prompt:
+                "Count the number of TypeScript files and total lines of code in the project.",
+              agentProfile: "general",
+            },
+            {
+              id: "deps",
+              name: "Dependency Check",
+              prompt:
+                "List all dependencies and devDependencies from package.json with their versions.",
+              agentProfile: "general",
+            },
+            {
+              id: "synthesize",
+              name: "Summary Report",
+              prompt:
+                "Combine the code metrics and dependency information into a brief project summary.",
+              agentProfile: "document-writer",
+              dependsOn: ["metrics", "deps"],
+            },
+          ],
+        },
+      });
+      expect(ok).toBe(true);
+
+      const exec = await executeWorkflow(workflow!.id);
+      expect(exec.status).toBe(202);
+
+      const result = await pollWorkflowUntilDone(workflow!.id);
+      expect(result.status).toBe("completed");
+    }
+  );
+});
+
+describe("Parallel Workflow — Codex", () => {
+  it.skipIf(!codexAvailable)(
+    "runs parallel branches via Codex runtime",
+    async () => {
+      const { ok, data: workflow } = await createWorkflow({
+        name: "E2E Codex Parallel Test",
+        projectId: testProjectId,
+        definition: {
+          pattern: "parallel",
+          steps: [
+            {
+              id: "files",
+              name: "List Files",
+              prompt: "List all files in the project directory.",
+              assignedAgent: "codex",
+              agentProfile: "general",
+            },
+            {
+              id: "structure",
+              name: "Describe Structure",
+              prompt: "Describe the project directory structure and purpose of each file.",
+              assignedAgent: "codex",
+              agentProfile: "general",
+            },
+            {
+              id: "combine",
+              name: "Combined Report",
+              prompt:
+                "Combine the file list and structure description into a single overview.",
+              assignedAgent: "codex",
+              agentProfile: "document-writer",
+              dependsOn: ["files", "structure"],
+            },
+          ],
+        },
+      });
+      expect(ok).toBe(true);
+
+      const exec = await executeWorkflow(workflow!.id);
+      expect(exec.status).toBe(202);
+
+      const result = await pollWorkflowUntilDone(workflow!.id);
+      expect(result.status).toBe("completed");
+    }
+  );
+});

package/src/__tests__/e2e/sequence-workflow.test.ts

@@ -0,0 +1,109 @@
+/**
+ * E2E: Sequence workflow execution.
+ *
+ * Tests that multi-step sequence workflows execute steps in order,
+ * pass context between steps, and produce combined results.
+ */
+
+import {
+  setupE2E,
+  teardownE2E,
+  testProjectId,
+  claudeAvailable,
+  codexAvailable,
+} from "./setup";
+import {
+  createWorkflow,
+  executeWorkflow,
+  pollWorkflowUntilDone,
+  createTask,
+  getTask,
+} from "./helpers";
+
+beforeAll(async () => {
+  await setupE2E();
+});
+
+afterAll(async () => {
+  await teardownE2E();
+});
+
+describe("Sequence Workflow — Claude Code", () => {
+  it.skipIf(!claudeAvailable)(
+    "executes steps in order with context passing",
+    async () => {
+      const { ok, data: workflow } = await createWorkflow({
+        name: "E2E Sequence Test",
+        projectId: testProjectId,
+        definition: {
+          pattern: "sequence",
+          steps: [
+            {
+              id: "analyze",
+              name: "Analyze Code",
+              prompt:
+                "Analyze the TypeScript code in the project. List the main functions and any bugs you find.",
+              agentProfile: "general",
+            },
+            {
+              id: "suggest",
+              name: "Suggest Tests",
+              prompt:
+                "Based on the analysis from the previous step, suggest specific test cases that would catch the bugs identified.",
+              agentProfile: "code-reviewer",
+              dependsOn: ["analyze"],
+            },
+          ],
+        },
+      });
+      expect(ok).toBe(true);
+
+      const exec = await executeWorkflow(workflow!.id);
+      expect(exec.status).toBe(202);
+
+      const result = await pollWorkflowUntilDone(workflow!.id);
+      expect(result.status).toBe("completed");
+    }
+  );
+});
+
+describe("Sequence Workflow — Codex", () => {
+  it.skipIf(!codexAvailable)(
+    "executes sequence steps via Codex runtime",
+    async () => {
+      const { ok, data: workflow } = await createWorkflow({
+        name: "E2E Codex Sequence Test",
+        projectId: testProjectId,
+        definition: {
+          pattern: "sequence",
+          steps: [
+            {
+              id: "describe",
+              name: "Describe Code",
+              prompt:
+                "Describe the TypeScript code in the project. List the main functions.",
+              assignedAgent: "codex",
+              agentProfile: "general",
+            },
+            {
+              id: "review",
+              name: "Review Code",
+              prompt:
+                "Based on the description from the previous step, review the code for bugs.",
+              assignedAgent: "codex",
+              agentProfile: "code-reviewer",
+              dependsOn: ["describe"],
+            },
+          ],
+        },
+      });
+      expect(ok).toBe(true);
+
+      const exec = await executeWorkflow(workflow!.id);
+      expect(exec.status).toBe(202);
+
+      const result = await pollWorkflowUntilDone(workflow!.id);
+      expect(result.status).toBe("completed");
+    }
+  );
+});

package/src/__tests__/e2e/setup.ts

@@ -0,0 +1,156 @@
+/**
+ * E2E test setup — creates a test project and sandbox, tears down after all tests.
+ *
+ * This file is imported by test files that need a shared project context.
+ * It does NOT run as a vitest setupFile — each test suite imports it explicitly.
+ */
+
+import { mkdirSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  createProject,
+  deleteProject,
+  isServerReachable,
+  isRuntimeAvailable,
+} from "./helpers";
+
+// ---------------------------------------------------------------------------
+// Shared test state
+// ---------------------------------------------------------------------------
+
+export let testProjectId = "";
+export let sandboxDir = "";
+export let claudeAvailable = false;
+export let codexAvailable = false;
+
+// ---------------------------------------------------------------------------
+// Sandbox files — minimal TypeScript project for agents to analyze
+// ---------------------------------------------------------------------------
+
+const SANDBOX_FILES: Record<string, string> = {
+  "package.json": JSON.stringify(
+    {
+      name: "stagent-e2e-sandbox",
+      version: "1.0.0",
+      scripts: { build: "tsc" },
+      devDependencies: { typescript: "^5.5.0" },
+    },
+    null,
+    2
+  ),
+  "tsconfig.json": JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        outDir: "dist",
+        strict: true,
+      },
+      include: ["src"],
+    },
+    null,
+    2
+  ),
+  "src/index.ts": `
+export interface Task {
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+const tasks: Task[] = [];
+
+export function addTask(title: string): Task {
+  // Deliberate bug: ID based on array length → duplicates after deletion
+  const task: Task = { id: tasks.length, title, completed: false };
+  tasks.push(task);
+  return task;
+}
+
+export function completeTask(id: number): boolean {
+  const task = tasks.find((t) => t.id === id);
+  if (task) {
+    task.completed = true;
+    return true;
+  }
+  return false;
+}
+
+export function getIncompleteTasks(): Task[] {
+  return tasks.filter((t) => !t.completed);
+}
+`.trimStart(),
+  "src/utils.ts": `
+export function formatDate(date: Date): string {
+  // Deliberate bug: getMonth() is zero-based
+  return \`\${date.getFullYear()}-\${date.getMonth()}-\${date.getDate()}\`;
+}
+
+export function parseCSV(csv: string): string[][] {
+  // Deliberate bug: naive parsing — no quoted field support
+  return csv.split("\\n").map((line) => line.split(","));
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "");
+}
+`.trimStart(),
+};
+
+// ---------------------------------------------------------------------------
+// Setup & Teardown
+// ---------------------------------------------------------------------------
+
+export async function setupE2E(): Promise<void> {
+  // 1. Check server reachability
+  const reachable = await isServerReachable();
+  if (!reachable) {
+    throw new Error(
+      "Stagent server is not reachable at the configured URL. " +
+        "Start the dev server with `npm run dev` before running E2E tests."
+    );
+  }
+
+  // 2. Create sandbox directory with test files
+  sandboxDir = join(tmpdir(), `stagent-e2e-${Date.now()}`);
+  mkdirSync(join(sandboxDir, "src"), { recursive: true });
+
+  for (const [relativePath, content] of Object.entries(SANDBOX_FILES)) {
+    const fullPath = join(sandboxDir, relativePath);
+    const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(fullPath, content, "utf-8");
+  }
+
+  // 3. Create test project pointing at the sandbox
+  const { ok, data } = await createProject({
+    name: `E2E Test ${new Date().toISOString().slice(0, 19)}`,
+    description: "Automated E2E test project — safe to delete",
+    workingDirectory: sandboxDir,
+  });
+  if (!ok || !data?.id) {
+    throw new Error("Failed to create E2E test project");
+  }
+  testProjectId = data.id;
+
+  // 4. Detect runtime availability
+  claudeAvailable = await isRuntimeAvailable("claude-code");
+  codexAvailable = await isRuntimeAvailable("openai-codex-app-server");
+}
+
+export async function teardownE2E(): Promise<void> {
+  // Clean up test project
+  if (testProjectId) {
+    await deleteProject(testProjectId).catch(() => {});
+  }
+
+  // Clean up sandbox directory
+  if (sandboxDir && existsSync(sandboxDir)) {
+    rmSync(sandboxDir, { recursive: true, force: true });
+  }
+}