@guanlin4924/devflow-pi 0.1.95 → 0.1.97

package/src/mcp/core.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+
+import { packageRoot } from "../paths.ts";
+import type { CoreRunner, CoreResult } from "./types.ts";
+
+export const runnerScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py");
+export const dslScript = path.join(packageRoot(), "plugins/devflow-core/skills/workflow-orchestrator/scripts/dsl_draft.py");
+
+const DEFAULT_TIMEOUT_MS = 7_200_000;
+const TERMINATION_GRACE_MS = 5_000;
+const PROGRESS_INTERVAL_MS = 10_000;
+
+function terminateProcessGroup(pid: number | undefined, signal: "SIGTERM" | "SIGKILL"): void {
+  if (pid === undefined) return;
+  try { process.kill(-pid, signal); } catch { /* process group may already be gone */ }
+}
+
+async function settleText(value: Promise<string>, timeoutMs: number): Promise<string> {
+  return Promise.race([
+    value,
+    new Promise<string>(resolve => setTimeout(() => resolve(""), timeoutMs)),
+  ]);
+}
+
+export const runPython: CoreRunner = async (script, args, cwd, stdin, timeoutMs = DEFAULT_TIMEOUT_MS, onProgress) => {
+  // -E/-s ignore PYTHON* variables and user site-packages.  Not -I: isolated mode also drops the
+  // script directory from sys.path, and the Core scripts import their sibling modules.
+  const child = Bun.spawn(["python3", "-E", "-s", script, ...args], {
+    cwd,
+    detached: true,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const stdoutPromise = new Response(child.stdout).text();
+  const stderrPromise = new Response(child.stderr).text();
+  if (stdin !== undefined) child.stdin.write(stdin);
+  child.stdin.end();
+  const progressTimer = onProgress === undefined ? undefined : setInterval(() => {
+    void Promise.resolve(onProgress()).catch(() => undefined);
+  }, PROGRESS_INTERVAL_MS);
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const timeoutPromise = new Promise<"timeout">(resolve => {
+    timeoutHandle = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const exitPromise = child.exited.then(exitCode => ({ exitCode }));
+  const winner = await Promise.race([exitPromise, timeoutPromise]);
+  if (winner === "timeout") {
+    timedOut = true;
+    terminateProcessGroup(child.pid, "SIGTERM");
+    try { child.kill("SIGTERM"); } catch { /* already exited */ }
+    await new Promise(resolve => setTimeout(resolve, TERMINATION_GRACE_MS));
+    terminateProcessGroup(child.pid, "SIGKILL");
+    try { child.kill("SIGKILL"); } catch { /* already exited */ }
+    if (progressTimer !== undefined) clearInterval(progressTimer);
+    clearTimeout(timeoutHandle);
+    return {
+      exitCode: null,
+      stdout: await settleText(stdoutPromise, 100),
+      stderr: await settleText(stderrPromise, 100),
+      timedOut,
+    };
+  }
+
+  if (progressTimer !== undefined) clearInterval(progressTimer);
+  clearTimeout(timeoutHandle);
+  return {
+    exitCode: winner.exitCode,
+    stdout: await stdoutPromise,
+    stderr: await stderrPromise,
+    timedOut,
+  };
+};
+
+export async function invokeCore(
+  runner: CoreRunner,
+  action: string,
+  project: string,
+  feature: string,
+  timeoutMs?: number,
+  onProgress?: () => void | Promise<void>,
+): Promise<CoreResult> {
+  const result = await runner(
+    runnerScript,
+    [action, "--feature", feature, "--json", ...(action === "run" ? ["--write"] : [])],
+    project,
+    undefined,
+    timeoutMs,
+    onProgress,
+  );
+  if (result.timedOut) return { ok: false, reason: "mcp_run_timeout", error_code: "mcp_run_timeout" };
+  try {
+    return JSON.parse(result.stdout) as CoreResult;
+  } catch {
+    // Keep the tail of the diagnostic (where Python tracebacks end), without project paths.
+    const detail = (result.stderr || result.stdout || `Core exited ${result.exitCode}`).slice(-1000)
+      .replace(/(?:[A-Za-z]:)?[^\s,;()"']+[\/][^\s,;()"']+/g, "<path>");
+    return { ok: false, reason: "core_failed", error_code: "core_failed", errors: [detail] };
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,193 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { devflowHome } from "../paths.ts";
+import { authorize, FEATURE_RE, loadAuthorization, MAX_DSL_BYTES, McpError, requestHash } from "./auth.ts";
+import { dslScript, invokeCore, runPython } from "./core.ts";
+import type { CoreRunner, McpServerOptions, McpToolName } from "./types.ts";
+
+const RESPONSE_LIMIT = 64 * 1024;
+
+type ProgressCallback = () => void | Promise<void>;
+
+function bounded(value: unknown): string {
+  const text = JSON.stringify(value);
+  if (text.length <= RESPONSE_LIMIT) return text;
+  return JSON.stringify({
+    ok: false,
+    reason: "response_truncated",
+    truncated: true,
+    output: text.slice(0, RESPONSE_LIMIT - 80),
+  });
+}
+
+function toolResult(value: unknown) {
+  return {
+    content: [{ type: "text" as const, text: bounded(value) }],
+    isError: Boolean(value && typeof value === "object" && (value as { ok?: unknown }).ok === false),
+  };
+}
+
+async function audit(home: string, row: Record<string, unknown>): Promise<void> {
+  const directory = path.join(home, "mcp-audit");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${new Date().toISOString().slice(0, 7)}.jsonl`);
+  await appendFile(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+}
+
+function collectEnvironmentProfiles(value: unknown): Set<string> {
+  const profiles = new Set<string>();
+  const visit = (current: unknown): void => {
+    if (Array.isArray(current)) {
+      current.forEach(visit);
+      return;
+    }
+    if (!current || typeof current !== "object") return;
+    const record = current as Record<string, unknown>;
+    if ((record.kind === "devflow_playwright" || record.adapter_kind === "devflow_playwright") && typeof record.environment_profile === "string") {
+      profiles.add(record.environment_profile);
+    }
+    Object.values(record).forEach(visit);
+  };
+  visit(value);
+  return profiles;
+}
+
+const MAX_FAILURE_ERRORS = 50;
+const MAX_FAILURE_ERROR_CHARS = 500;
+
+// Failure details must not expose project or run locations (same rule as the Core report).
+function scrubPaths(text: string): string {
+  return text
+    .replace(/(?:[A-Za-z]:)?[^\s,;()"']+[\/][^\s,;()"']+/g, "<path>")
+    .slice(0, MAX_FAILURE_ERROR_CHARS);
+}
+
+// A run that executed TCs always answers with the Core report, even when TCs failed or are
+// blocked: the report's gate says whether acceptance passed.  Only runs that never produced
+// results (lock held, invalid bindings/approvals, Core crash) short-circuit with an error.
+function runFailure(value: Record<string, unknown>): Record<string, unknown> {
+  const code = typeof value.error_code === "string" ? value.error_code
+    : typeof value.reason === "string" && value.reason ? value.reason
+    : Array.isArray(value.errors) && value.errors.length > 0 ? "acceptance_validation_failed"
+    : "core_failed";
+  const errors = Array.isArray(value.errors) ? value.errors.slice(0, MAX_FAILURE_ERRORS).map(item => scrubPaths(String(item))) : [];
+  return { ok: false, error_code: code, reason: code, errors };
+}
+
+export async function createMcpServer(options: McpServerOptions) {
+  const home = options.home ?? devflowHome();
+  const config = await loadAuthorization(options.client, home);
+  const runner: CoreRunner = options.runner ?? runPython;
+  let running = false;
+
+  const server = new McpServer({ name: "devflow-acceptance", version: "1.0.0" });
+
+  const call = async (tool: McpToolName, args: Record<string, unknown>, onProgress?: ProgressCallback): Promise<Record<string, unknown>> => {
+    const started = Date.now();
+    let ok = false;
+    let reason: string | null = null;
+    try {
+      if (tool === "dsl_draft_validate") {
+        const dslText = JSON.stringify(args.dsl);
+        if (typeof dslText !== "string" || Buffer.byteLength(dslText) > MAX_DSL_BYTES) {
+          throw new McpError("mcp_input_invalid", "DSL exceeds 2 MiB or is not JSON");
+        }
+        const auth = await authorize(config, options.client, tool, args.project ?? process.cwd());
+        const raw = await runner(dslScript, [], auth.project, JSON.stringify({ dsl: args.dsl, tc_data: args.tc_data }));
+        if (raw.timedOut) return { ok: false, error_code: "core_failed", reason: "core_failed" };
+        try {
+          const parsed = JSON.parse(raw.stdout) as Record<string, unknown>;
+          ok = parsed.ok === true;
+          return parsed;
+        } catch {
+          return { ok: false, error_code: "core_failed", reason: raw.stderr || raw.stdout };
+        }
+      }
+
+      const feature = args.feature;
+      const auth = await authorize(config, options.client, tool, args.project, feature);
+      if (tool === "run_feature" && running) throw new McpError("mcp_busy", "another run_feature is in progress");
+
+      if (tool === "run_feature") {
+        const bindingFile = path.join(auth.project, ".devflow/planning/features", String(feature), "acceptance-test-bindings.json");
+        let bindings: unknown;
+        try {
+          bindings = JSON.parse(await readFile(bindingFile, "utf8"));
+        } catch {
+          throw new McpError("mcp_input_invalid", "acceptance-test-bindings.json is missing or invalid");
+        }
+        const profiles = collectEnvironmentProfiles(bindings);
+        if ([...profiles].some(profile => !auth.grant.environment_profiles.includes(profile))) {
+          throw new McpError("mcp_environment_not_allowed", "environment profile is not authorized");
+        }
+
+        running = true;
+        try {
+          const runResult = await invokeCore(
+            runner,
+            "run",
+            auth.project,
+            String(feature),
+            Math.min(7_200_000, Math.max(1, options.runTimeoutSeconds ?? 7200) * 1000),
+            onProgress,
+          );
+          if (!Array.isArray(runResult.results)) return runFailure(runResult);
+          const report = await invokeCore(runner, "report", auth.project, String(feature));
+          ok = report.ok === true;
+          return report;
+        } finally {
+          running = false;
+        }
+      }
+
+      const coreResult = await invokeCore(runner, tool === "validate_feature" ? "validate" : "report", auth.project, String(feature));
+      ok = coreResult.ok === true;
+      return coreResult;
+    } catch (error) {
+      const mcpError = error instanceof McpError
+        ? error
+        : new McpError("core_failed", error instanceof Error ? error.message : String(error));
+      reason = mcpError.code;
+      return { ok: false, error_code: mcpError.code, reason: mcpError.message };
+    } finally {
+      await audit(home, {
+        ts: new Date().toISOString(),
+        client: options.client,
+        project_id: typeof args.project === "string" ? requestHash(path.resolve(args.project)) : null,
+        tool,
+        feature: args.feature ?? null,
+        ok,
+        reason,
+        duration_ms: Date.now() - started,
+        request_sha256: requestHash(args),
+      });
+    }
+  };
+
+  const input = z.object({ project: z.string(), feature: z.string().regex(FEATURE_RE) });
+  const withProgress = (tool: McpToolName) => (args: any, extra: any) => {
+    const token = extra._meta?.progressToken;
+    const progress = token === undefined
+      ? undefined
+      : () => extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: Date.now(), message: "run_feature is still running" } });
+    return call(tool, args, progress).then(toolResult);
+  };
+
+  server.registerTool("validate_feature", { description: "Validate a feature; no artifacts are returned.", inputSchema: input.shape }, withProgress("validate_feature"));
+  server.registerTool("run_feature", { description: "Run a feature, then return only the Core report. Approval is never confirmed here; blocked tests require /devflow.", inputSchema: input.shape }, withProgress("run_feature"));
+  server.registerTool("get_feature_report", { description: "Get the Core feature report; no artifacts are returned.", inputSchema: input.shape }, withProgress("get_feature_report"));
+  server.registerTool("dsl_draft_validate", { description: "Validate DSL schema and coverage only; this does not make the draft executable and does not check approvals or manifests.", inputSchema: { project: z.string(), dsl: z.unknown(), tc_data: z.unknown() } }, withProgress("dsl_draft_validate"));
+
+  Object.assign(server, { invoke: call, boundedForTest: bounded });
+  return server;
+}
+
+export async function startMcpServer(options: McpServerOptions): Promise<void> {
+  const server = await createMcpServer(options);
+  await server.connect(new StdioServerTransport());
+}

package/src/mcp/types.ts

@@ -0,0 +1,5 @@
+export type McpToolName = "validate_feature" | "run_feature" | "get_feature_report" | "dsl_draft_validate";
+export type CoreResult = { ok: boolean; [key: string]: unknown };
+export type CoreRunnerResult = { exitCode: number | null; stdout: string; stderr: string; timedOut?: boolean };
+export type CoreRunner = (script: string, args: string[], cwd: string, stdin?: string, timeoutMs?: number, onProgress?: () => void | Promise<void>) => Promise<CoreRunnerResult>;
+export type McpServerOptions = { client: string; runTimeoutSeconds?: number; runner?: CoreRunner; home?: string };

package/src/startup-briefing.ts

@@ -0,0 +1,109 @@
+export type StartupIssue = { code?: unknown; detail?: unknown; path?: unknown };
+
+type StartupFacts = {
+  feature?: unknown;
+  phase?: unknown;
+  step?: { id?: unknown; label?: unknown; skill?: unknown; description?: unknown };
+  progress?: { index?: unknown; total?: unknown };
+  inputs?: Array<{ path?: unknown; required?: unknown; exists?: unknown }>;
+  outputs?: unknown[];
+  allowed_paths?: unknown[];
+  contract_id?: unknown;
+};
+
+type StartupHandoff = {
+  previous_step?: { id?: unknown; label?: unknown; outputs?: Array<{ path?: unknown }> };
+  carry?: { user_notes?: unknown[]; agent_report?: unknown };
+};
+
+type StartupMeta = { revision?: unknown; handoffProvided?: boolean };
+
+const issueDescriptions: Record<string, (issue: StartupIssue) => string> = {
+  PREVIOUS_OUTPUT_CHANGED: issue => `上一步的产物 ${String(issue.path ?? "未知路径")} 在交接后被修改过`,
+  PREVIOUS_OUTPUT_MISSING: issue => `上一步的产物 ${String(issue.path ?? "未知路径")} 不存在`,
+  HANDOFF_UNAVAILABLE: issue => `无法读取或校验交接单${issue.path ? ` ${String(issue.path)}` : ""}`,
+  STEP_UNAVAILABLE: () => "当前步骤不在工作流中",
+  MISSING_INPUT_FACT: issue => `本步需要的输入 ${String(issue.path ?? "未知路径")} 不存在`,
+  STALE_EXECUTION_CONTRACT: () => "执行合同已过期，请重新激活",
+  STALE_WORKFLOW_SNAPSHOT: () => "工作流快照已变化，执行合同不再有效",
+  STALE_STATE_SNAPSHOT: () => "STATE 快照已变化，执行合同不再有效",
+  UNREACHABLE_OBLIGATION: issue => `执行合同不允许产出 ${String(issue.path ?? "该必需产物")}`,
+  CONTRACT_TARGET_MISMATCH: () => "执行合同与当前 Feature 或步骤不匹配",
+  STARTUP_PREFLIGHT_INPUT_UNAVAILABLE: issue => `开工预检输入不可用${issue.detail ? `：${String(issue.detail)}` : ""}`,
+};
+
+export function describeStartupIssue(issue: StartupIssue): string {
+  const code = typeof issue.code === "string" && issue.code ? issue.code : "UNKNOWN_ISSUE";
+  return issueDescriptions[code]?.(issue) ?? `${code}：${String(issue.detail ?? "无详细信息")}`;
+}
+
+function strings(values: unknown[] | undefined): string[] {
+  return Array.isArray(values) ? values.filter((value): value is string => typeof value === "string" && value.length > 0) : [];
+}
+
+function truncate(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  return limit <= 1 ? "…".slice(0, limit) : `${value.slice(0, limit - 1)}…`;
+}
+
+export function renderStartupBriefing(facts: StartupFacts, handoff: StartupHandoff = {}, meta: StartupMeta = {}): string {
+  const render = (report: string, notes: string[]): string => {
+    const sections: string[] = [];
+    const step = facts.step;
+    const progress = facts.progress;
+    if (facts.feature && step?.id && step.label && progress?.index !== undefined && progress.total !== undefined) {
+      sections.push(`【需求】${String(facts.feature)} · 第 ${String(progress.index)} / ${String(progress.total)} 步：${String(step.label)}（${String(step.id)}）`);
+    }
+    if (step?.description) sections.push(`【本步目标】${String(step.description)}`);
+
+    const previous = handoff.previous_step;
+    const previousOutputs = previous?.outputs?.flatMap(item => typeof item?.path === "string" ? [item.path] : []) ?? [];
+    const handoffLines: string[] = [];
+    if (previous?.label) {
+      handoffLines.push(`- 上一步「${String(previous.label)}」已完成，产物：${previousOutputs.join("、") || "无已记录产物"}`);
+    }
+    if (notes.length > 0) {
+      handoffLines.push("- 用户在上一步审查期间的意见：", ...notes.map(note => `- ${note}`));
+    }
+    if (report) handoffLines.push(`- 上一步 AI 报告摘要：${report}`);
+    if (handoffLines.length > 0) sections.push(["【上一棒交接】", ...handoffLines].join("\n"));
+
+    const work: string[] = [];
+    if (step?.skill) work.push(`- 使用技能：skill://${String(step.skill)}`);
+    const inputText = facts.inputs?.flatMap(input => {
+      if (typeof input?.path !== "string") return [];
+      if (input.required === true && input.exists === true) return [`${input.path} ✓`];
+      if (input.required === false && input.exists !== true) return [`${input.path}（可选，缺失）`];
+      return [input.path];
+    }) ?? [];
+    if (inputText.length > 0) work.push(`- 已核对的输入：${inputText.join("／")}`);
+    const outputs = strings(facts.outputs);
+    if (outputs.length > 0) work.push(`- 必须产出：${outputs.join("、")}`);
+    const allowedPaths = strings(facts.allowed_paths);
+    if (allowedPaths.length > 0) work.push(`- 只允许写入：${allowedPaths.join("、")}`);
+    if (facts.contract_id) work.push(`- 执行合同已由 Runtime 激活：${String(facts.contract_id)}（不要再次 inspect 或 activate）`);
+    if (work.length > 0) sections.push(["【这一步你要做】", ...work].join("\n"));
+
+    sections.push("【完成标准】产出完成后，报告证据、未决项和验证结果并停止，等待用户回复\"批准执行\"。");
+    if (meta.revision !== undefined || facts.contract_id) {
+      sections.push(`【预检记录】STATE revision ${String(meta.revision ?? "未知")} · 环境体检通过 · 交接单校验${meta.handoffProvided ? "通过" : "不适用"} · 合同 ${String(facts.contract_id ?? "无")}`);
+    }
+    return sections.join("\n");
+  };
+
+  let report = typeof handoff.carry?.agent_report === "string" ? handoff.carry.agent_report : "";
+  let notes = handoff.carry?.user_notes?.flatMap(note => typeof note === "string" ? [note] : []) ?? [];
+  let result = render(report, notes);
+  if (result.length > 6000 && report) {
+    report = truncate(report, Math.max(0, report.length - (result.length - 6000)));
+    result = render(report, notes);
+  }
+  while (result.length > 6000 && notes.length > 0) {
+    const last = notes.at(-1)!;
+    const excess = result.length - 6000;
+    if (last.length > excess + 1) notes = [...notes.slice(0, -1), truncate(last, last.length - excess)];
+    else notes = notes.slice(0, -1);
+    result = render(report, notes);
+  }
+  return result.length <= 6000 ? result : truncate(result, 6000);
+}