@shenlee/devcrew 0.1.0

package/packages/core/src/workflow.ts

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+
+import { ensureConfig } from "./config.js";
+import { readArtifact, writeArtifact } from "./artifacts.js";
+import { discoverStandards } from "./standards.js";
+import { loadState, saveState } from "./store.js";
+import {
+  parseAnswer,
+  parseArtifactName,
+  parseBackend,
+  parseCwd,
+  parseExecutionMode,
+  parseFeedback,
+  parseGate,
+  parseHost,
+  parseOptionalNote,
+  parseRequest,
+  parseRunId,
+  parseWorkflowMode,
+} from "./validation.js";
+import type {
+  AnswerWorkflowInput,
+  ApproveWorkflowInput,
+  ArtifactName,
+  ArtifactReadResult,
+  ArtifactRef,
+  GateName,
+  RejectWorkflowInput,
+  RunRef,
+  RunState,
+  StartWorkflowInput,
+} from "./types.js";
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function newRunId(): string {
+  return `dc-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}
+
+export function nextPhaseAfterGate(gate: GateName): RunState["phase"] {
+  const nextByGate: Record<GateName, RunState["phase"]> = {
+    requirements: "architecture",
+    architecture: "implementation",
+    implementation: "testing",
+    testing: "acceptance",
+  };
+  return nextByGate[gate];
+}
+
+export function artifactForPhase(phase: RunState["phase"]): ArtifactName {
+  const artifactByPhase: Record<RunState["phase"], ArtifactName> = {
+    requirements: "requirements",
+    architecture: "architecture",
+    implementation: "implementation-plan",
+    testing: "test-report",
+    acceptance: "acceptance",
+    complete: "acceptance",
+  };
+  return artifactByPhase[phase];
+}
+
+export function gateForPhase(phase: RunState["phase"]): GateName | undefined {
+  if (phase === "requirements" || phase === "architecture" || phase === "implementation" || phase === "testing") {
+    return phase;
+  }
+  return undefined;
+}
+
+function assertCurrentGate(state: RunState, gate: GateName): void {
+  const expected = gateForPhase(state.phase);
+  if (expected && expected !== gate) {
+    throw new Error(`Cannot act on ${gate} while current gate is ${expected}`);
+  }
+}
+
+async function writeCurrentArtifact(state: RunState): Promise<RunState> {
+  const artifact = artifactForPhase(state.phase);
+  const path = await writeArtifact(artifact, state);
+  state.artifacts[artifact] = path;
+  return state;
+}
+
+export interface WorkflowMutationOptions {
+  skipArtifactWrite?: boolean;
+}
+
+export async function startWorkflow(input: StartWorkflowInput, options: WorkflowMutationOptions = {}): Promise<RunState> {
+  const cwd = parseCwd(input.cwd);
+  const host = parseHost(input.host);
+  const mode = parseWorkflowMode(input.mode);
+  const request = parseRequest(input.request);
+  const config = await ensureConfig(cwd);
+  const backend = input.backend ? parseBackend(input.backend) : config.defaultBackend === "host-preferred" ? host : config.defaultBackend;
+  const executionMode = input.executionMode ? parseExecutionMode(input.executionMode) : config.executionMode;
+  const createdAt = now();
+  const state: RunState = {
+    version: 1,
+    runId: newRunId(),
+    cwd,
+    host,
+    mode,
+    executionMode,
+    backend,
+    request,
+    phase: "requirements",
+    status: "awaiting_approval",
+    createdAt,
+    updatedAt: createdAt,
+    gates: {
+      requirements: "pending",
+      architecture: "not_started",
+      implementation: "not_started",
+      testing: "not_started",
+    },
+    artifacts: {},
+    roles: [],
+    answers: [],
+    approvals: [],
+    feedback: [],
+    standards: await discoverStandards(cwd),
+    changedFiles: [],
+    implementationDiff: "",
+    verification: [],
+    lintResults: [],
+  };
+
+  if (!options.skipArtifactWrite) {
+    await writeCurrentArtifact(state);
+  }
+  return saveState(state);
+}
+
+export async function getWorkflowStatus(input: RunRef): Promise<RunState> {
+  return loadState(parseCwd(input.cwd), parseRunId(input.runId));
+}
+
+export async function continueWorkflow(input: RunRef): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  if (state.status === "awaiting_approval" || state.status === "awaiting_input" || state.status === "complete") {
+    return state;
+  }
+
+  if (state.phase === "acceptance") {
+    await writeCurrentArtifact(state);
+    state.phase = "complete";
+    state.status = "complete";
+    return saveState(state);
+  }
+
+  const gate = gateForPhase(state.phase);
+  if (!gate) {
+    state.status = "complete";
+    return saveState(state);
+  }
+  state.gates[gate] = "pending";
+  state.status = "awaiting_approval";
+  await writeCurrentArtifact(state);
+  return saveState(state);
+}
+
+export async function approveWorkflow(input: ApproveWorkflowInput): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  const gate = parseGate(input.gate);
+  assertCurrentGate(state, gate);
+  state.gates[gate] = "approved";
+  state.approvals.push({
+    gate,
+    note: parseOptionalNote(input.note),
+    createdAt: now(),
+  });
+
+  const nextPhase = nextPhaseAfterGate(gate);
+  state.phase = nextPhase;
+  state.status = "ready";
+  return saveState(state);
+}
+
+export async function rejectWorkflow(input: RejectWorkflowInput): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  const gate = parseGate(input.gate);
+  assertCurrentGate(state, gate);
+  state.gates[gate] = "rejected";
+  state.status = "awaiting_input";
+  state.feedback.push({
+    gate,
+    message: parseFeedback(input.feedback),
+    createdAt: now(),
+  });
+  return saveState(state);
+}
+
+export async function answerWorkflow(input: AnswerWorkflowInput, options: WorkflowMutationOptions = {}): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  state.answers.push({
+    answer: parseAnswer(input.answer),
+    createdAt: now(),
+  });
+  const gate = gateForPhase(state.phase);
+  if (gate) {
+    state.gates[gate] = "pending";
+    state.status = "awaiting_approval";
+  }
+  if (!options.skipArtifactWrite) {
+    await writeCurrentArtifact(state);
+  }
+  return saveState(state);
+}
+
+export async function getArtifact(input: ArtifactRef): Promise<ArtifactReadResult> {
+  const state = await getWorkflowStatus(input);
+  return readArtifact(state, parseArtifactName(input.name));
+}

package/packages/orchestrator/src/index.ts

@@ -0,0 +1,469 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve as resolvePath } from "node:path";
+
+import { runRole } from "../../adapters/src/index.js";
+import type { RoleRunInput } from "../../adapters/src/index.js";
+import {
+  answerWorkflow,
+  artifactForPhase,
+  artifactPath,
+  ARTIFACTS,
+  discoverCoverageCommands,
+  discoverLintCommands,
+  discoverVerifyCommands,
+  gateForPhase,
+  getWorkflowStatus,
+  readConfig,
+  rejectWorkflow,
+  renderArtifact,
+  saveState,
+  startWorkflow,
+  type AnswerWorkflowInput,
+  type ArtifactName,
+  type Phase,
+  type RejectWorkflowInput,
+  type RoleResult,
+  type RunRef,
+  type RunState,
+  type StartWorkflowInput,
+  type VerificationResult,
+} from "../../core/src/index.js";
+
+// Hard cap so a hung apply/verify command cannot block the serialized MCP loop.
+const COMMAND_TIMEOUT_MS = 300_000;
+
+type RoleRunner = (input: RoleRunInput) => Promise<RoleResult>;
+
+function roleForPhase(phase: Phase): RoleResult["role"] | undefined {
+  const roles: Partial<Record<Phase, RoleResult["role"]>> = {
+    requirements: "pm",
+    architecture: "architect",
+    implementation: "implementer",
+    testing: "tester",
+  };
+  return roles[phase];
+}
+
+function conductorDecision(state: RunState, role: RoleResult["role"], gate: string): RoleResult {
+  const summary = `Conductor routed ${state.phase} phase to ${role} and prepared the ${gate} gate.`;
+  return {
+    role: "conductor",
+    backend: state.backend,
+    summary,
+    markdown: `# Conductor Decision\n\n${summary}\n`,
+    usedFallback: false,
+  };
+}
+
+function priorArtifactNamesForPhase(phase: Phase): ArtifactName[] {
+  const current = artifactForPhase(phase);
+  const currentIndex = ARTIFACTS.indexOf(current);
+  if (currentIndex <= 0) {
+    return [];
+  }
+  return ARTIFACTS.slice(0, currentIndex);
+}
+
+async function writeMarkdownArtifact(state: RunState, artifact: ArtifactName, markdown: string): Promise<string> {
+  const path = artifactPath(state.cwd, state.runId, artifact);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, markdown, "utf8");
+  return path;
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function fallbackNotice(result: RoleResult): string {
+  if (!result.usedFallback) {
+    return "";
+  }
+  if (result.backend === "local") {
+    return `> DevCrew local fallback: this artifact uses the deterministic local planning template because the local backend does not call an external SDK.\n\n`;
+  }
+  const reason = result.summary.includes("output failed validation")
+    ? `the ${result.backend} SDK did not return a valid artifact`
+    : `the ${result.backend} SDK was unavailable`;
+  return `> DevCrew SDK fallback: this artifact uses the deterministic planning template because ${reason}.\n> Reason: ${result.summary}\n\n`;
+}
+
+async function readPriorArtifacts(state: RunState): Promise<Record<string, string>> {
+  const priorArtifacts: Record<string, string> = {};
+  for (const name of priorArtifactNamesForPhase(state.phase)) {
+    const path = state.artifacts[name];
+    if (!path) {
+      continue;
+    }
+    priorArtifacts[name] = await readFile(path, "utf8");
+  }
+  return priorArtifacts;
+}
+
+export async function runShellCommand(
+  command: string,
+  cwd: string,
+  timeoutMs: number = COMMAND_TIMEOUT_MS,
+): Promise<VerificationResult> {
+  const startedAt = now();
+  return new Promise((resolveResult) => {
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const chunks: Buffer[] = [];
+    const maxOutputBytes = 64_000;
+    let collected = 0;
+    let timedOut = false;
+    let settled = false;
+
+    function collect(chunk: Buffer): void {
+      if (collected >= maxOutputBytes) {
+        return;
+      }
+      const slice = chunk.subarray(0, Math.max(0, maxOutputBytes - collected));
+      chunks.push(slice);
+      collected += slice.length;
+    }
+
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+    }, timeoutMs);
+    killTimer.unref();
+
+    function finish(result: VerificationResult): void {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(killTimer);
+      resolveResult(result);
+    }
+
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.on("error", (error) => {
+      finish({ command, exitCode: 1, output: error.message, startedAt, completedAt: now() });
+    });
+    child.on("close", (code) => {
+      const base = Buffer.concat(chunks).toString("utf8").replace(/\s+$/u, "");
+      const output = timedOut
+        ? `${base}\n[devcrew] command timed out after ${timeoutMs}ms`.trim()
+        : base;
+      finish({ command, exitCode: timedOut ? 124 : code ?? 1, output, startedAt, completedAt: now() });
+    });
+  });
+}
+
+async function runGit(args: string[], cwd: string): Promise<{ exitCode: number; stdout: string }> {
+  return new Promise((resolveResult) => {
+    const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", () => resolveResult({ exitCode: 1, stdout: "" }));
+    child.on("close", (code) => resolveResult({ exitCode: code ?? 1, stdout: stdout || stderr }));
+  });
+}
+
+async function listChangedLines(cwd: string, options: { requireGit?: boolean } = {}): Promise<string[]> {
+  const result = await runShellCommand("git status --porcelain -uall", cwd, 30_000);
+  if (result.exitCode !== 0) {
+    if (options.requireGit) {
+      throw new Error("DevCrew apply mode requires a git repository so implementation changes can be reviewed and reverted.");
+    }
+    return [];
+  }
+  return result.output
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .filter((line) => {
+      const path = line.slice(3);
+      return !path.startsWith(".devcrew/") && !path.startsWith("docs/devcrew/");
+    });
+}
+
+async function assertCleanApplyWorkspace(cwd: string): Promise<void> {
+  const changedLines = await listChangedLines(cwd, { requireGit: true });
+  if (changedLines.length === 0) {
+    return;
+  }
+  const visibleLines = changedLines.slice(0, 20).join(", ");
+  const suffix = changedLines.length > 20 ? `, and ${changedLines.length - 20} more` : "";
+  throw new Error(
+    `DevCrew apply mode requires a clean working tree before implementation. Commit, stash, or remove these files: ${visibleLines}${suffix}`,
+  );
+}
+
+async function collectImplementationDiff(cwd: string): Promise<string> {
+  const result = await runShellCommand("git diff --no-ext-diff --", cwd, 30_000);
+  if (result.exitCode !== 0) {
+    return "";
+  }
+  return result.output;
+}
+
+// Files attributable to this run are the porcelain lines that appeared (or
+// changed status) since the baseline captured before the role executed. This
+// keeps a user's pre-existing uncommitted edits out of the changed-files list.
+// The porcelain status prefix is preserved for review (?? = new, M = modified).
+export function changedSinceBaseline(baseline: string[], current: string[]): string[] {
+  const baselineLines = new Set(baseline);
+  return current.filter((line) => !baselineLines.has(line));
+}
+
+// Strip the two-character porcelain status plus its separating space. For
+// rename entries ("R  old -> new") the destination path is what remains
+// relevant, so keep only the post-arrow path when present.
+export function porcelainPath(line: string): string {
+  const raw = line.slice(3).trim();
+  const arrow = raw.indexOf(" -> ");
+  return arrow >= 0 ? raw.slice(arrow + 4) : raw;
+}
+
+export interface RevertDeps {
+  runGit?: (args: string[], cwd: string) => Promise<{ exitCode: number; stdout: string }>;
+  removeFile?: (absolutePath: string) => Promise<void>;
+}
+
+// Roll back implementer edits when an apply-mode gate is rejected.
+// Only the files this run introduced/changed are reverted, so unrelated work in
+// the repository is preserved. Tracked files are restored from HEAD; files that
+// did not exist in HEAD are deleted. Failures are surfaced to the MCP caller.
+export async function revertChangedFiles(
+  cwd: string,
+  changedFiles: string[],
+  deps: RevertDeps = {},
+): Promise<void> {
+  const git = deps.runGit ?? runGit;
+  const removeFile = deps.removeFile ?? ((absolutePath: string) => rm(absolutePath, { force: true }));
+  for (const line of changedFiles) {
+    const file = porcelainPath(line);
+    if (!file) {
+      continue;
+    }
+    const tracked = await git(["cat-file", "-e", `HEAD:${file}`], cwd);
+    if (tracked.exitCode === 0) {
+      const restored = await git(["restore", "--source=HEAD", "--", file], cwd);
+      if (restored.exitCode !== 0) {
+        throw new Error(`Failed to restore ${file}: ${restored.stdout || "git restore failed"}`);
+      }
+    } else {
+      try {
+        await removeFile(resolvePath(cwd, file));
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to remove ${file}: ${message}`);
+      }
+    }
+  }
+}
+
+async function runCommands(commands: string[], cwd: string): Promise<VerificationResult[]> {
+  const results: VerificationResult[] = [];
+  for (const command of commands) {
+    results.push(await runShellCommand(command, cwd));
+  }
+  return results;
+}
+
+function uniqueCommands(commands: string[]): string[] {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const command of commands) {
+    if (seen.has(command)) {
+      continue;
+    }
+    seen.add(command);
+    unique.push(command);
+  }
+  return unique;
+}
+
+// Tester verification runs the normal verification path first, then coverage
+// as supplemental evidence. Configured commands win per category; otherwise
+// DevCrew discovers common project commands.
+async function runConfiguredVerification(state: RunState): Promise<VerificationResult[]> {
+  const config = await readConfig(state.cwd);
+  const configuredVerify = config.verifyCommands.filter((command) => command.trim().length > 0);
+  const configuredCoverage = (config.coverageCommands ?? []).filter((command) => command.trim().length > 0);
+  const verifyCommands = configuredVerify.length > 0 ? configuredVerify : await discoverVerifyCommands(state.cwd);
+  const coverageCommands = configuredCoverage.length > 0 ? configuredCoverage : await discoverCoverageCommands(state.cwd);
+  const commands = uniqueCommands([...verifyCommands, ...coverageCommands]);
+  return runCommands(commands, state.cwd);
+}
+
+// Implementer apply runs lint/format/typecheck so reviewers see standards
+// compliance evidence. Configured lintCommands win, otherwise discover them.
+async function runConfiguredLint(state: RunState): Promise<VerificationResult[]> {
+  const config = await readConfig(state.cwd);
+  const configuredLint = (config.lintCommands ?? []).filter((command) => command.trim().length > 0);
+  const commands = configuredLint.length > 0 ? configuredLint : await discoverLintCommands(state.cwd);
+  return runCommands(commands, state.cwd);
+}
+
+function changedFilesBlock(changedFiles: string[]): string {
+  if (changedFiles.length === 0) {
+    return "No changed files were detected.";
+  }
+  return changedFiles.map((file) => `- ${file}`).join("\n");
+}
+
+function verificationBlock(results: VerificationResult[]): string {
+  if (results.length === 0) {
+    return "No verification commands were configured.";
+  }
+  return results
+    .map(
+      (result) =>
+        `### ${result.command}\n\nExit Code: ${result.exitCode}\n\nOutput:\n\n\`\`\`text\n${result.output || "(no output)"}\n\`\`\``,
+    )
+    .join("\n\n");
+}
+
+function lintBlock(results: VerificationResult[]): string {
+  if (results.length === 0) {
+    return "No lint or format commands were detected.";
+  }
+  return verificationBlock(results);
+}
+
+function appendExecutionSections(artifact: ArtifactName, markdown: string, state: RunState): string {
+  if (artifact === "implementation-plan") {
+    let next = markdown.trim();
+    if (!next.includes("## Recorded Changes")) {
+      next = `${next}\n\n## Recorded Changes\n\n${changedFilesBlock(state.changedFiles)}`;
+    }
+    if (!next.includes("## Lint Results")) {
+      next = `${next}\n\n## Lint Results\n\n${lintBlock(state.lintResults)}`;
+    }
+    return `${next}\n`;
+  }
+  if (artifact === "test-report" && !markdown.includes("## Acceptance Evidence")) {
+    return `${markdown.trim()}\n\n## Acceptance Evidence\n\n${verificationBlock(state.verification)}\n`;
+  }
+  return markdown;
+}
+
+async function runCurrentPhaseRole(state: RunState, runner: RoleRunner = runRole): Promise<RunState> {
+  const gate = gateForPhase(state.phase);
+  const role = roleForPhase(state.phase);
+  if (!gate || !role) {
+    const artifact = artifactForPhase(state.phase);
+    const markdown = renderArtifact(artifact, state);
+    state.artifacts[artifact] = await writeMarkdownArtifact(state, artifact, markdown);
+    state.phase = "complete";
+    state.status = "complete";
+    return saveState(state);
+  }
+
+  const artifact = artifactForPhase(state.phase);
+  const path = artifactPath(state.cwd, state.runId, artifact);
+
+  // Apply-mode implementation starts from a clean tree, so changed files after
+  // the role runs are attributable to the current DevCrew run.
+  const applyingImplementation = state.executionMode === "apply" && state.phase === "implementation";
+  const implementationBaseline: string[] = [];
+  if (applyingImplementation) {
+    await assertCleanApplyWorkspace(state.cwd);
+  }
+
+  state.roles.push(conductorDecision(state, role, gate));
+
+  const result = await runner({
+    backend: state.backend,
+    role,
+    phase: state.phase,
+    request: state.request,
+    mode: state.mode,
+    executionMode: state.executionMode,
+    cwd: state.cwd,
+    standards: state.standards.combined,
+    artifactPath: path,
+    answers: state.answers.map((entry) => entry.answer),
+    feedback: state.feedback.map((entry) => `${entry.gate}: ${entry.message}`),
+    priorArtifacts: await readPriorArtifacts(state),
+  });
+
+  if (applyingImplementation) {
+    state.changedFiles = changedSinceBaseline(implementationBaseline, await listChangedLines(state.cwd));
+    state.implementationDiff = await collectImplementationDiff(state.cwd);
+    state.lintResults = await runConfiguredLint(state);
+  }
+  if (state.executionMode === "apply" && state.phase === "testing") {
+    state.verification = await runConfiguredVerification(state);
+  }
+
+  // When the backend cannot run a real SDK we keep a single deterministic
+  // artifact source by rendering the rich phase template from the core layer.
+  const baseMarkdown = result.usedFallback ? `${fallbackNotice(result)}${renderArtifact(artifact, state)}` : result.markdown;
+  const markdown = appendExecutionSections(artifact, baseMarkdown, state);
+  state.roles.push({ ...result, markdown });
+  state.artifacts[artifact] = await writeMarkdownArtifact(state, artifact, markdown);
+  if (artifact === "implementation-plan") {
+    state.artifacts["implementation-review"] = await writeMarkdownArtifact(
+      state,
+      "implementation-review",
+      renderArtifact("implementation-review", state),
+    );
+  }
+  state.gates[gate] = "pending";
+  state.status = "awaiting_approval";
+  return saveState(state);
+}
+
+export async function startOrchestratedWorkflow(input: StartWorkflowInput, runner: RoleRunner = runRole): Promise<RunState> {
+  const state = await startWorkflow(input, { skipArtifactWrite: true });
+  return runCurrentPhaseRole(state, runner);
+}
+
+export async function continueOrchestratedWorkflow(input: RunRef, runner: RoleRunner = runRole): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  if (state.status === "awaiting_approval" || state.status === "awaiting_input" || state.status === "complete") {
+    return state;
+  }
+
+  return runCurrentPhaseRole(state, runner);
+}
+
+export async function rejectOrchestratedWorkflow(input: RejectWorkflowInput): Promise<RunState> {
+  const before = await getWorkflowStatus(input);
+  const state = await rejectWorkflow(input);
+
+  // Roll back implementer edits when an apply-mode implementation gate is
+  // rejected so the next attempt starts from a clean working tree.
+  if (
+    before.executionMode === "apply" &&
+    before.phase === "implementation" &&
+    before.changedFiles.length > 0
+  ) {
+    await revertChangedFiles(before.cwd, before.changedFiles);
+    state.changedFiles = [];
+    return saveState(state);
+  }
+
+  return state;
+}
+
+export async function answerOrchestratedWorkflow(input: AnswerWorkflowInput, runner: RoleRunner = runRole): Promise<RunState> {
+  const state = await answerWorkflow(input, { skipArtifactWrite: true });
+  const gate = gateForPhase(state.phase);
+  const role = roleForPhase(state.phase);
+  if (!gate || !role) {
+    return state;
+  }
+
+  // Re-run the current phase role so the artifact reflects the new answer and
+  // any rejection feedback, instead of reverting to the static template.
+  return runCurrentPhaseRole(state, runner);
+}