@shenlee/devcrew 0.1.0

package/dist/packages/core/src/types.js

@@ -0,0 +1,48 @@
+export const WORKFLOW_MODES = ["feature", "greenfield"];
+export const EXECUTION_MODES = ["plan", "apply"];
+export const HOSTS = ["codex", "claude"];
+export const BACKENDS = ["codex", "claude", "local"];
+export const PHASES = [
+    "requirements",
+    "architecture",
+    "implementation",
+    "testing",
+    "acceptance",
+    "complete",
+];
+export const GATES = ["requirements", "architecture", "implementation", "testing"];
+export const ARTIFACTS = [
+    "requirements",
+    "architecture",
+    "implementation-plan",
+    "implementation-review",
+    "test-report",
+    "acceptance",
+];
+export const ROLE_SECTIONS = {
+    pm: [
+        { heading: "Functional Scope", description: "explicit In Scope and Out of Scope lists" },
+        { heading: "Users and Scenarios", description: "primary users and their key scenarios" },
+        { heading: "Acceptance Criteria", description: "testable criteria written as Given / When / Then" },
+        { heading: "Priorities", description: "classify each requirement as Must / Should / Could / Won't (MoSCoW)" },
+        { heading: "Open Questions", description: "unresolved clarifications for the requester" },
+    ],
+    architect: [
+        { heading: "Technical Decisions", description: "for each key decision record Decision, Options Considered, Choice, Rationale, and Trade-offs" },
+        { heading: "Interface Contracts", description: "for each interface give the signature, request/response schema, error contract, and data model" },
+        { heading: "Data Flow and Deployment", description: "data flow, deployment expectations, and rollback strategy" },
+        { heading: "Architecture Review Checklist", description: "how the design traces back to the approved requirements" },
+    ],
+    implementer: [
+        { heading: "Implementation Summary", description: "the smallest change that satisfies the approved architecture" },
+        { heading: "Standards Compliance", description: "follow discovered standards and lint/format rules; run available lint/format/typecheck and report results" },
+        { heading: "Changed Files", description: "every file you created or modified" },
+        { heading: "Tests Added or Updated", description: "tests covering success, edge, and failure paths" },
+    ],
+    tester: [
+        { heading: "Test Cases", description: "enumerate cases as a table with ID, Scenario, Type (happy/edge/failure/regression), and Expected result" },
+        { heading: "Coverage", description: "run the coverage command and report the coverage summary plus any gaps" },
+        { heading: "Verification Evidence", description: "exact commands, exit codes, and key output" },
+        { heading: "Known Risks", description: "residual risks and follow-ups" },
+    ],
+};

package/dist/packages/core/src/validation.js

@@ -0,0 +1,52 @@
+import { ARTIFACTS, BACKENDS, EXECUTION_MODES, GATES, HOSTS, WORKFLOW_MODES, } from "./types.js";
+function assertString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function oneOf(value, field, values) {
+    if (typeof value !== "string" || !values.includes(value)) {
+        throw new Error(`${field} must be one of: ${values.join(", ")}`);
+    }
+    return value;
+}
+export function parseWorkflowMode(value) {
+    return oneOf(value, "mode", WORKFLOW_MODES);
+}
+export function parseExecutionMode(value) {
+    return oneOf(value, "executionMode", EXECUTION_MODES);
+}
+export function parseHost(value) {
+    return oneOf(value, "host", HOSTS);
+}
+export function parseBackend(value) {
+    return oneOf(value, "backend", BACKENDS);
+}
+export function parseGate(value) {
+    return oneOf(value, "gate", GATES);
+}
+export function parseArtifactName(value) {
+    return oneOf(value, "name", ARTIFACTS);
+}
+export function parseCwd(value) {
+    return assertString(value, "cwd");
+}
+export function parseRunId(value) {
+    return assertString(value, "runId");
+}
+export function parseRequest(value) {
+    return assertString(value, "request");
+}
+export function parseOptionalNote(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    return assertString(value, "note");
+}
+export function parseFeedback(value) {
+    return assertString(value, "feedback");
+}
+export function parseAnswer(value) {
+    return assertString(value, "answer");
+}

package/dist/packages/core/src/verification.js

@@ -0,0 +1,157 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+async function readIfExists(path) {
+    try {
+        await access(path);
+        return readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function packageVerifyCommands(cwd) {
+    const raw = await readIfExists(join(cwd, "package.json"));
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const scripts = parsed.scripts ?? {};
+        if (scripts.validate) {
+            return ["npm run validate"];
+        }
+        if (scripts.test) {
+            return ["npm test"];
+        }
+        const commands = [];
+        if (scripts.typecheck) {
+            commands.push("npm run typecheck");
+        }
+        if (scripts.lint) {
+            commands.push("npm run lint");
+        }
+        return commands;
+    }
+    catch {
+        return [];
+    }
+}
+async function pythonVerifyCommands(cwd) {
+    const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+    if (!pyproject) {
+        return [];
+    }
+    if (pyproject.includes("[tool.pytest") || pyproject.includes("pytest")) {
+        return ["python -m pytest"];
+    }
+    return [];
+}
+export async function discoverVerifyCommands(cwd) {
+    const packageCommands = await packageVerifyCommands(cwd);
+    if (packageCommands.length > 0) {
+        return packageCommands;
+    }
+    if (await exists(join(cwd, "go.mod"))) {
+        return ["go test ./..."];
+    }
+    if (await exists(join(cwd, "Cargo.toml"))) {
+        return ["cargo test"];
+    }
+    return pythonVerifyCommands(cwd);
+}
+export async function readPackageJson(cwd) {
+    const raw = await readIfExists(join(cwd, "package.json"));
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function packageLintCommands(cwd) {
+    const parsed = await readPackageJson(cwd);
+    if (!parsed) {
+        return [];
+    }
+    const scripts = parsed.scripts ?? {};
+    const commands = [];
+    if (scripts.typecheck) {
+        commands.push("npm run typecheck");
+    }
+    if (scripts.lint) {
+        commands.push("npm run lint");
+    }
+    if (scripts["format:check"]) {
+        commands.push("npm run format:check");
+    }
+    return commands;
+}
+export async function discoverLintCommands(cwd) {
+    const packageCommands = await packageLintCommands(cwd);
+    if (packageCommands.length > 0) {
+        return packageCommands;
+    }
+    const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+    if (pyproject) {
+        const commands = [];
+        if (pyproject.includes("ruff")) {
+            commands.push("ruff check .");
+        }
+        if (pyproject.includes("black")) {
+            commands.push("black --check .");
+        }
+        if (commands.length > 0) {
+            return commands;
+        }
+    }
+    if (await exists(join(cwd, "go.mod"))) {
+        return ["files=$(gofmt -l .) && test -z \"$files\" || { printf '%s\\n' \"$files\"; exit 1; }", "go vet ./..."];
+    }
+    if (await exists(join(cwd, "Cargo.toml"))) {
+        return ["cargo fmt --check", "cargo clippy"];
+    }
+    return [];
+}
+async function packageCoverageCommands(cwd) {
+    const parsed = await readPackageJson(cwd);
+    if (!parsed) {
+        return [];
+    }
+    const scripts = parsed.scripts ?? {};
+    if (scripts.coverage) {
+        return ["npm run coverage"];
+    }
+    const deps = { ...(parsed.dependencies ?? {}), ...(parsed.devDependencies ?? {}) };
+    const testScript = scripts.test ?? "";
+    const usesCoverageRunner = "jest" in deps || "vitest" in deps || testScript.includes("jest") || testScript.includes("vitest");
+    if (scripts.test && usesCoverageRunner) {
+        return ["npm test -- --coverage"];
+    }
+    return [];
+}
+export async function discoverCoverageCommands(cwd) {
+    const packageCommands = await packageCoverageCommands(cwd);
+    if (packageCommands.length > 0) {
+        return packageCommands;
+    }
+    const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+    if (pyproject && (pyproject.includes("[tool.pytest") || pyproject.includes("pytest"))) {
+        return ["python -m pytest --cov"];
+    }
+    if (await exists(join(cwd, "go.mod"))) {
+        return ["go test -cover ./..."];
+    }
+    return [];
+}

package/dist/packages/core/src/version.js

@@ -0,0 +1,2 @@
+export const DEVCREW_VERSION = "0.1.0";
+export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";

package/dist/packages/core/src/workflow.js

@@ -0,0 +1,166 @@
+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";
+function now() {
+    return new Date().toISOString();
+}
+function newRunId() {
+    return `dc-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}
+export function nextPhaseAfterGate(gate) {
+    const nextByGate = {
+        requirements: "architecture",
+        architecture: "implementation",
+        implementation: "testing",
+        testing: "acceptance",
+    };
+    return nextByGate[gate];
+}
+export function artifactForPhase(phase) {
+    const artifactByPhase = {
+        requirements: "requirements",
+        architecture: "architecture",
+        implementation: "implementation-plan",
+        testing: "test-report",
+        acceptance: "acceptance",
+        complete: "acceptance",
+    };
+    return artifactByPhase[phase];
+}
+export function gateForPhase(phase) {
+    if (phase === "requirements" || phase === "architecture" || phase === "implementation" || phase === "testing") {
+        return phase;
+    }
+    return undefined;
+}
+function assertCurrentGate(state, gate) {
+    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) {
+    const artifact = artifactForPhase(state.phase);
+    const path = await writeArtifact(artifact, state);
+    state.artifacts[artifact] = path;
+    return state;
+}
+export async function startWorkflow(input, options = {}) {
+    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 = {
+        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) {
+    return loadState(parseCwd(input.cwd), parseRunId(input.runId));
+}
+export async function continueWorkflow(input) {
+    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) {
+    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) {
+    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, options = {}) {
+    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) {
+    const state = await getWorkflowStatus(input);
+    return readArtifact(state, parseArtifactName(input.name));
+}