@shenlee/devcrew 0.1.3 → 0.1.4

package/README.md

@@ -35,7 +35,7 @@ Restart Codex, open the plugin directory, choose the DevCrew marketplace, and in
 The plugin starts the DevCrew MCP server with:
 
 ```bash
-npm exec --silent --yes --package=@shenlee/devcrew@0.1.3 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.4 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
 ```
 
 The plugin locks the MCP server to the published npm package version, so users do not need to clone the source or build TypeScript at install time. You only need Node.js and network access the first time Codex starts the MCP server.

package/README.zh-CN.md

@@ -35,7 +35,7 @@ codex plugin marketplace add lishen802/devcrew
 插件会用下面的命令启动 DevCrew MCP 服务：
 
 ```bash
-npm exec --silent --yes --package=@shenlee/devcrew@0.1.3 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.4 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
 ```
 
 插件会锁定到已发布的 npm 包版本，因此用户不需要克隆源码，也不需要在安装时编译 TypeScript；只需要本机有 Node.js，并且 Codex 第一次启动 MCP 服务时可以访问网络。

package/dist/packages/adapters/src/index.js

@@ -60,6 +60,143 @@ export function extractArchitectureReviewDecision(markdown) {
     const match = /^Decision:\s*(approved|changes_required)\s*$/im.exec(section);
     return match?.[1];
 }
+const STRUCTURED_RESULT_MARKER = "<!-- devcrew-role-result -->";
+const STRUCTURED_RESULT_BLOCK = /<!--\s*devcrew-role-result\s*-->\s*```json\s*\r?\n([\s\S]*?)\r?\n```/g;
+function structuredOutputError(role, reason) {
+    return new RoleOutputValidationError(role, [`marked structured role result: ${reason}`]);
+}
+function asRecord(value, role, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw structuredOutputError(role, `${field} must be an object`);
+    }
+    return value;
+}
+function asNonEmptyString(value, role, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw structuredOutputError(role, `${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function asStringArray(value, role, field) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+        throw structuredOutputError(role, `${field} must be an array of non-empty strings`);
+    }
+    return value.map((entry) => entry.trim());
+}
+function asEvidence(value, role) {
+    if (!Array.isArray(value)) {
+        throw structuredOutputError(role, "evidence must be an array");
+    }
+    return value.map((entry, index) => {
+        const evidence = asRecord(entry, role, `evidence[${index}]`);
+        const command = asNonEmptyString(evidence.command, role, `evidence[${index}].command`);
+        if (!Number.isInteger(evidence.exitCode)) {
+            throw structuredOutputError(role, `evidence[${index}].exitCode must be an integer`);
+        }
+        if (evidence.output !== undefined && typeof evidence.output !== "string") {
+            throw structuredOutputError(role, `evidence[${index}].output must be a string`);
+        }
+        return { command, exitCode: evidence.exitCode, output: evidence.output };
+    });
+}
+function asQuestions(value, role) {
+    if (!Array.isArray(value)) {
+        throw structuredOutputError(role, "questions must be an array");
+    }
+    const ids = new Set();
+    return value.map((entry, index) => {
+        const question = asRecord(entry, role, `questions[${index}]`);
+        const id = asNonEmptyString(question.id, role, `questions[${index}].id`);
+        if (ids.has(id)) {
+            throw structuredOutputError(role, `questions[${index}].id must be unique`);
+        }
+        ids.add(id);
+        const prompt = asNonEmptyString(question.prompt, role, `questions[${index}].prompt`);
+        if (question.context !== undefined && typeof question.context !== "string") {
+            throw structuredOutputError(role, `questions[${index}].context must be a string`);
+        }
+        return { id, prompt, context: question.context };
+    });
+}
+function parseStructuredRoleData(role, phase, raw) {
+    const value = asRecord(raw, role, "result");
+    if (value.schemaVersion !== 1) {
+        throw structuredOutputError(role, "schemaVersion must be 1");
+    }
+    if (value.role !== role) {
+        throw structuredOutputError(role, `role must be ${role}`);
+    }
+    const data = {
+        schemaVersion: 1,
+        role,
+        summary: asNonEmptyString(value.summary, role, "summary"),
+        risks: asStringArray(value.risks, role, "risks"),
+        evidence: asEvidence(value.evidence, role),
+    };
+    if (role === "pm") {
+        data.questions = asQuestions(value.questions, role);
+    }
+    else if (role === "architect") {
+        data.decisions = asStringArray(value.decisions, role, "decisions");
+        if (phase === "review") {
+            if (value.reviewDecision !== "approved" && value.reviewDecision !== "changes_required") {
+                throw structuredOutputError(role, "reviewDecision must be approved or changes_required");
+            }
+            data.reviewDecision = value.reviewDecision;
+        }
+    }
+    else if (role === "implementer") {
+        data.changedFiles = asStringArray(value.changedFiles, role, "changedFiles");
+    }
+    else {
+        if (!Array.isArray(value.testCases)) {
+            throw structuredOutputError(role, "testCases must be an array");
+        }
+        data.testCases = value.testCases.map((entry, index) => {
+            const testCase = asRecord(entry, role, `testCases[${index}]`);
+            const type = testCase.type;
+            if (type !== "happy" && type !== "edge" && type !== "failure" && type !== "regression") {
+                throw structuredOutputError(role, `testCases[${index}].type is invalid`);
+            }
+            return {
+                id: asNonEmptyString(testCase.id, role, `testCases[${index}].id`),
+                scenario: asNonEmptyString(testCase.scenario, role, `testCases[${index}].scenario`),
+                type,
+                expected: asNonEmptyString(testCase.expected, role, `testCases[${index}].expected`),
+            };
+        });
+    }
+    return data;
+}
+export function parseRoleResultOutput(role, phase, output) {
+    if (!output.includes(STRUCTURED_RESULT_MARKER)) {
+        return {
+            format: "legacy",
+            markdown: output,
+            questions: role === "pm" ? extractOpenQuestions(output) : undefined,
+            reviewDecision: phase === "review" ? extractArchitectureReviewDecision(output) : undefined,
+        };
+    }
+    const blocks = [...output.matchAll(STRUCTURED_RESULT_BLOCK)];
+    if (blocks.length !== 1) {
+        throw structuredOutputError(role, blocks.length === 0 ? "must use a JSON fenced block" : "must appear exactly once");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(blocks[0]?.[1] ?? "");
+    }
+    catch {
+        throw structuredOutputError(role, "contains invalid JSON");
+    }
+    const structured = parseStructuredRoleData(role, phase, raw);
+    return {
+        format: "structured",
+        markdown: output.slice(0, blocks[0]?.index).concat(output.slice((blocks[0]?.index ?? 0) + (blocks[0]?.[0].length ?? 0))).trim(),
+        structured,
+        questions: structured.questions?.map((question) => question.prompt),
+        reviewDecision: structured.reviewDecision,
+    };
+}
 export function renderRolePrompt(input) {
     const executionMode = input.executionMode ?? "plan";
     const answers = input.answers ?? [];
@@ -95,7 +232,7 @@ export function renderRolePrompt(input) {
             ? "You may run validation commands needed for the approved scope and report exact evidence."
             : "You may modify repository files needed for the approved scope and report changed files."
         : "Do not modify repository files. Return only the Markdown document content for the artifact.";
-    lines.push("", "Instructions:", `Act as the DevCrew ${input.role} role and produce a complete, well-structured Markdown document for the ${input.phase} phase.`, "Keep scope aligned with the approved gates and the selected DevCrew execution policy.", permissionInstruction, "", "Required Sections:", ...roleGuidance(input.role));
+    lines.push("", "Instructions:", `Act as the DevCrew ${input.role} role and produce a complete, well-structured Markdown document for the ${input.phase} phase.`, "Keep scope aligned with the approved gates and the selected DevCrew execution policy.", permissionInstruction, "", "Return this protocol block first:", STRUCTURED_RESULT_MARKER, "```json", `{\"schemaVersion\":1,\"role\":\"${input.role}\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}`, "```", "Then return the required Markdown H2 sections. Do not include a second marked result block.", "", "Required Sections:", ...roleGuidance(input.role));
     if (input.phase === "review") {
         lines.push("", "Architecture Review Decision:", "Add an exact H2 `## Review Decision` section containing exactly `Decision: approved` or `Decision: changes_required`.", "Use `changes_required` for any mismatch with the approved architecture; summarize the blocking mismatch in that section.");
     }
@@ -238,6 +375,7 @@ function fallbackResult(role, backend, title, summary) {
         summary,
         markdown: `# ${title}\n\n${summary}\n`,
         usedFallback: true,
+        format: "legacy",
     };
 }
 function shouldFailOnSdkError(input) {
@@ -257,18 +395,21 @@ export async function runRole(input, deps = {}) {
         const markdown = input.backend === "codex"
             ? await runWithCodex(input, prompt, loadModule)
             : await runWithClaude(input, prompt, loadModule);
-        assertRoleSections(input.role, markdown);
-        const reviewDecision = input.phase === "review" ? extractArchitectureReviewDecision(markdown) : undefined;
+        const parsed = parseRoleResultOutput(input.role, input.phase, markdown);
+        assertRoleSections(input.role, parsed.markdown);
+        const reviewDecision = parsed.reviewDecision;
         if (input.phase === "review" && !reviewDecision) {
             throw new RoleOutputValidationError(input.role, ["Review Decision"]);
         }
         return {
             role: input.role,
             backend: input.backend,
-            summary: `${input.role} produced ${title} using the ${input.backend} SDK.`,
-            markdown,
+            summary: parsed.structured?.summary ?? `${input.role} produced ${title} using the ${input.backend} SDK.`,
+            markdown: parsed.markdown,
             usedFallback: false,
-            questions: input.role === "pm" ? extractOpenQuestions(markdown) : undefined,
+            format: parsed.format,
+            structured: parsed.structured,
+            questions: parsed.questions,
             reviewDecision,
         };
     }

package/dist/packages/core/src/active-run.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
 import { activeRunPath, ensureProjectDirectories } from "./paths.js";
 export async function setActiveRun(cwd, runId) {
     await ensureProjectDirectories(cwd);
@@ -22,3 +22,15 @@ export async function getActiveRunId(cwd) {
     }
     throw new Error("No active DevCrew run. Pass runId or start a workflow first.");
 }
+export async function clearActiveRunIfMatches(cwd, runId) {
+    try {
+        if ((await getActiveRunId(cwd)) !== runId) {
+            return false;
+        }
+        await unlink(activeRunPath(cwd));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,5 +1,7 @@
 import { access, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { configPath, ensureProjectDirectories } from "./paths.js";
+import { BACKENDS, EXECUTION_MODES, GATES } from "./types.js";
 export const DEFAULT_CONFIG = {
     version: 1,
     defaultBackend: "host-preferred",
@@ -21,6 +23,90 @@ async function exists(path) {
         return false;
     }
 }
+function asRecord(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be an object`);
+    }
+    return value;
+}
+function assertKnownKeys(value, field, allowed) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            throw new Error(`Invalid .devcrew/config.json: ${field} has unknown key ${key}`);
+        }
+    }
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function parseCommandList(value, field) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be an array`);
+    }
+    return value.map((entry, index) => requiredString(entry, `${field}[${index}]`));
+}
+function parseGates(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.gates must be an array");
+    }
+    const gates = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || !GATES.includes(entry)) {
+            throw new Error(`Invalid .devcrew/config.json: workflow.gates[${index}] must be a known gate, received ${String(entry)}`);
+        }
+        if (gates.includes(entry)) {
+            throw new Error(`Invalid .devcrew/config.json: workflow.gates contains duplicate ${entry}`);
+        }
+        gates.push(entry);
+    }
+    return gates;
+}
+function parseArtifactDirectory(cwd, value) {
+    const artifactDirectory = requiredString(value, "workflow.artifactDirectory");
+    if (isAbsolute(artifactDirectory)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must be relative to the repository");
+    }
+    const projectRoot = resolve(cwd);
+    const target = resolve(projectRoot, artifactDirectory);
+    const fromProject = relative(projectRoot, target);
+    if (fromProject === ".." || fromProject.startsWith(`..${sep}`) || isAbsolute(fromProject)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must resolve inside the repository");
+    }
+    return artifactDirectory;
+}
+function parseConfig(cwd, value) {
+    const parsed = asRecord(value, "root");
+    assertKnownKeys(parsed, "root", ["version", "defaultBackend", "executionMode", "verifyCommands", "lintCommands", "coverageCommands", "workflow"]);
+    if (parsed.version !== 1) {
+        throw new Error("Unsupported .devcrew/config.json version");
+    }
+    if (typeof parsed.defaultBackend !== "string" || (parsed.defaultBackend !== "host-preferred" && !BACKENDS.includes(parsed.defaultBackend))) {
+        throw new Error("Invalid .devcrew/config.json: defaultBackend must be host-preferred, codex, claude, or local");
+    }
+    if (typeof parsed.executionMode !== "string" || !EXECUTION_MODES.includes(parsed.executionMode)) {
+        throw new Error("Invalid .devcrew/config.json: executionMode must be plan or apply");
+    }
+    const workflow = asRecord(parsed.workflow, "workflow");
+    assertKnownKeys(workflow, "workflow", ["gates", "artifactDirectory"]);
+    return {
+        version: 1,
+        defaultBackend: parsed.defaultBackend,
+        executionMode: parsed.executionMode,
+        verifyCommands: parseCommandList(parsed.verifyCommands, "verifyCommands"),
+        lintCommands: parseCommandList(parsed.lintCommands, "lintCommands"),
+        coverageCommands: parseCommandList(parsed.coverageCommands, "coverageCommands"),
+        workflow: {
+            gates: parseGates(workflow.gates),
+            artifactDirectory: parseArtifactDirectory(cwd, workflow.artifactDirectory),
+        },
+    };
+}
 export async function ensureConfig(cwd) {
     await ensureProjectDirectories(cwd);
     const path = configPath(cwd);
@@ -32,20 +118,5 @@ export async function ensureConfig(cwd) {
 }
 export async function readConfig(cwd) {
     const raw = await readFile(configPath(cwd), "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version !== 1) {
-        throw new Error("Unsupported .devcrew/config.json version");
-    }
-    return {
-        ...DEFAULT_CONFIG,
-        ...parsed,
-        executionMode: parsed.executionMode ?? "plan",
-        verifyCommands: Array.isArray(parsed.verifyCommands) ? parsed.verifyCommands : [],
-        lintCommands: Array.isArray(parsed.lintCommands) ? parsed.lintCommands : [],
-        coverageCommands: Array.isArray(parsed.coverageCommands) ? parsed.coverageCommands : [],
-        workflow: {
-            ...DEFAULT_CONFIG.workflow,
-            ...parsed.workflow,
-        },
-    };
+    return parseConfig(cwd, JSON.parse(raw));
 }

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

@@ -1,6 +1,7 @@
 export * from "./active-run.js";
 export * from "./artifacts.js";
 export * from "./config.js";
+export * from "./lock.js";
 export * from "./paths.js";
 export * from "./standards.js";
 export * from "./store.js";

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

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { devcrewDir, repositoryLockPath } from "./paths.js";
+function metadataPath(cwd) {
+    return `${repositoryLockPath(cwd)}/lock.json`;
+}
+async function readMetadata(cwd) {
+    try {
+        const parsed = JSON.parse(await readFile(metadataPath(cwd), "utf8"));
+        const pid = parsed.pid;
+        if (typeof parsed.ownerId !== "string" ||
+            typeof pid !== "number" ||
+            !Number.isInteger(pid) ||
+            typeof parsed.createdAt !== "string") {
+            return undefined;
+        }
+        return {
+            ownerId: parsed.ownerId,
+            pid,
+            createdAt: parsed.createdAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function processIsLive(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function releaseRepositoryLock(cwd, ownerId) {
+    const metadata = await readMetadata(cwd);
+    if (metadata?.ownerId === ownerId) {
+        await rm(repositoryLockPath(cwd), { recursive: true, force: true });
+    }
+}
+export async function withRepositoryLock(cwd, action) {
+    await mkdir(devcrewDir(cwd), { recursive: true });
+    const ownerId = randomUUID();
+    try {
+        await mkdir(repositoryLockPath(cwd));
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        const metadata = await readMetadata(cwd);
+        if (metadata && processIsLive(metadata.pid)) {
+            throw new Error("A DevCrew operation is already in progress for this repository");
+        }
+        throw new Error("A stale DevCrew repository lock exists; use devcrew_recover for explicit recovery");
+    }
+    await writeFile(metadataPath(cwd), `${JSON.stringify({ ownerId, pid: process.pid, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
+    try {
+        return await action();
+    }
+    finally {
+        await releaseRepositoryLock(cwd, ownerId);
+    }
+}
+export async function recoverRepositoryLock(cwd) {
+    const lockPath = repositoryLockPath(cwd);
+    const metadata = await readMetadata(cwd);
+    if (!metadata) {
+        try {
+            await rm(lockPath, { recursive: true, force: false });
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    if (processIsLive(metadata.pid)) {
+        throw new Error("Cannot recover a DevCrew repository lock held by a live process");
+    }
+    await rm(lockPath, { recursive: true, force: true });
+    return true;
+}

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

@@ -21,6 +21,9 @@ export function configPath(cwd) {
 export function activeRunPath(cwd) {
     return join(devcrewDir(cwd), "active-run.json");
 }
+export function repositoryLockPath(cwd) {
+    return join(devcrewDir(cwd), "lock");
+}
 export function standardsPath(cwd) {
     return join(devcrewDir(cwd), "standards.md");
 }

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

@@ -8,6 +8,15 @@ function enabledGatesFromState(value) {
         : [...GATES];
     return [...new Set([...configured, "implementation-review", "testing"])];
 }
+function roleResultsFromState(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((role) => typeof role === "object" && role !== null).map((role) => ({
+        ...role,
+        format: role.format === "structured" ? "structured" : "legacy",
+    }));
+}
 export async function saveState(state) {
     state.updatedAt = new Date().toISOString();
     await ensureRunDirectories(state.cwd, state.runId);
@@ -27,6 +36,7 @@ export async function loadState(cwd, runId) {
         ...parsed,
         executionMode: parsed.executionMode ?? "plan",
         executionPolicy: parsed.executionPolicy ?? "interactive-host",
+        roles: roleResultsFromState(parsed.roles),
         enabledGates: enabledGatesFromState(parsed.enabledGates),
         artifactDirectory: typeof parsed.artifactDirectory === "string" && parsed.artifactDirectory.trim().length > 0
             ? parsed.artifactDirectory

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

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

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

@@ -135,7 +135,8 @@ export async function continueWorkflow(input) {
     if (state.status === "awaiting_approval" ||
         state.status === "awaiting_input" ||
         state.status === "awaiting_execution" ||
-        state.status === "complete") {
+        state.status === "complete" ||
+        state.status === "aborted") {
         return state;
     }
     if (state.phase === "acceptance") {
@@ -163,6 +164,22 @@ export async function continueWorkflow(input) {
     await writeCurrentArtifact(state);
     return saveState(state);
 }
+export async function abortWorkflow(input) {
+    const state = await getWorkflowStatus(input);
+    if (state.status === "aborted") {
+        return state;
+    }
+    if (state.status === "complete") {
+        throw new Error("Completed DevCrew runs cannot be aborted");
+    }
+    state.abort = {
+        reason: parseWaiverReason(input.reason),
+        abortedAt: now(),
+    };
+    delete state.executionInstruction;
+    state.status = "aborted";
+    return saveState(state);
+}
 export async function validateWorkflowApproval(input) {
     const state = await getWorkflowStatus(input);
     const gate = parseGate(input.gate);
@@ -238,8 +255,8 @@ export async function waiveVerificationWorkflow(input) {
         state.phase !== "testing" ||
         state.status !== "awaiting_input" ||
         state.gates.testing !== "rejected" ||
-        state.verificationStatus !== "failed") {
-        throw new Error("A verification waiver is only available after failed apply-mode testing");
+        (state.verificationStatus !== "failed" && state.verificationStatus !== "not_run")) {
+        throw new Error("A verification waiver is only available after failed or missing apply-mode verification");
     }
     state.verificationWaiver = {
         reason: parseWaiverReason(input.reason),