@guanlin4924/devflow-pi 0.1.94 → 0.1.96

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/paths.ts

@@ -8,8 +8,19 @@ export function packageRoot(): string {
   return path.resolve(import.meta.dir, "..");
 }
 
+/**
+ * DEVFLOW_HOME rule (shared with the Python readers and hooks): unset, empty or whitespace-only
+ * falls back to ~/.devflow-pi; otherwise a leading `~` is expanded and the path made absolute
+ * (path.resolve semantics, existence not required).
+ */
+export function normalizeDevflowHome(value: string | undefined): string {
+  if (value === undefined || value.trim() === "") return path.resolve(path.join(os.homedir(), ".devflow-pi"));
+  const expanded = value === "~" || value.startsWith("~/") ? os.homedir() + value.slice(1) : value;
+  return path.resolve(expanded);
+}
+
 export function devflowHome(): string {
-  return path.resolve(process.env.DEVFLOW_HOME || path.join(os.homedir(), ".devflow-pi"));
+  return normalizeDevflowHome(process.env.DEVFLOW_HOME);
 }
 
 export function devflowAgentDir(): string {

package/src/project-context.ts

@@ -172,13 +172,35 @@ async function atomicWriteJson(target: string, value: unknown): Promise<void> {
   await rename(temporary, target);
 }
 
+async function ensureTestRuntimeLayout(root: string, planningRoot: string): Promise<void> {
+  const environments = path.join(planningRoot, "test-environments");
+  const runs = path.join(root, ".devflow", "runs");
+  await mkdir(environments, { recursive: true });
+  await mkdir(runs, { recursive: true });
+  const example = path.join(environments, "local.example.json");
+  if (!(await exists(example))) {
+    await atomicWriteJson(example, {
+      profile: "local",
+      base_url: "http://127.0.0.1:3000",
+      navigation_origins: ["http://127.0.0.1:3000"],
+      api_origins: ["http://127.0.0.1:3000"],
+      subresources: { policy: "same-site-plus-declared", allowed_origins: [] },
+      secret_env: {},
+      trace: "on_failure",
+      screenshots: "on_failure",
+    });
+  }
+}
+
 export async function initializeProject(root: string): Promise<{ context: ProjectContext; created: boolean }> {
   const canonicalRoot = await canonicalDirectory(root);
   const { devflowRoot: devflowDir, manifestPath, planningRoot } = projectLayout(canonicalRoot);
   await mkdir(devflowDir, { recursive: true });
   await assertPlanningBoundary(canonicalRoot);
   if (await exists(manifestPath)) {
-    return { context: await loadProjectContext(canonicalRoot), created: false };
+    const context = await loadProjectContext(canonicalRoot);
+    await ensureTestRuntimeLayout(canonicalRoot, context.planningRoot);
+    return { context, created: false };
   }
   const manifest: ProjectManifest = {
     schemaVersion: PROJECT_SCHEMA_VERSION,
@@ -198,6 +220,7 @@ export async function initializeProject(root: string): Promise<{ context: Projec
   manifest.layoutVersion = PROJECT_LAYOUT_VERSION;
   await atomicWriteJson(manifestPath, manifest);
   await mkdir(planningRoot, { recursive: true });
+  await ensureTestRuntimeLayout(canonicalRoot, planningRoot);
   const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
   try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {

package/templates/omp/hook-config.json

@@ -13,6 +13,12 @@
   "gates": {
     "index_first": {
       "policy": ".agent-gates/index-first.json"
+    },
+    "control_store": {
+      "hook": "index_gate.py",
+      "enforcement": "always",
+      "protected": ["control.db* (all access)", "$DEVFLOW_HOME/projects/** (all access)", "SQL writes to approval_proposals/approvals/authority_state", "acceptance-results*.json under .devflow/planning/test-runs (write-only; Read tools allowed)"],
+      "extra_protected_paths": []
     }
   }
 }