paseo-req-kit 0.0.0-stage → 1.8.0-beta.3

package/engine/src/gate.ts

@@ -0,0 +1,157 @@
+// The quality gate: project checks (lint, type check, tests, build) that the engine runs
+// itself after the steps that change code, instead of trusting the agent's own report.
+// Only checks that passed before the change and fail after it block; see ADR 0023.
+
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { CheckDef } from "./config.js";
+import type { CheckOutcome } from "./state.js";
+
+function git(repo: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+}
+
+export function headCommit(repo: string): string | null {
+  return git(repo, ["rev-parse", "HEAD"])?.trim() || null;
+}
+
+/**
+ * Files changed since `base`: committed, staged, unstaged and untracked (repository-relative,
+ * "/" separators). Null when it cannot be told (not a git repository, unknown base).
+ */
+export function changedFiles(repo: string, base: string | null): string[] | null {
+  if (!base) return null;
+  const diff = git(repo, ["diff", "--name-only", base]);
+  if (diff === null) return null;
+  const untracked = git(repo, ["ls-files", "--others", "--exclude-standard"]) ?? "";
+  const files = new Set([...diff.split("\n"), ...untracked.split("\n")].map((f) => f.trim()).filter(Boolean));
+  return [...files].sort();
+}
+
+/**
+ * Which of `files` changed since `commit` (committed or not); null when the commit is not
+ * in this repository. Used to tell whether acceptance tests committed first were changed later.
+ */
+export function changedSince(repo: string, commit: string, files: string[]): string[] | null {
+  if (git(repo, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`]) === null) return null;
+  const out = git(repo, ["diff", "--name-only", commit, "--", ...files]);
+  if (out === null) return null;
+  return out.split("\n").map((f) => f.trim()).filter(Boolean).sort();
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === "*" && pattern[i + 1] === "*") {
+      re += ".*";
+      i += 1;
+      if (pattern[i + 1] === "/") i += 1;
+    } else if (c === "*") re += "[^/]*";
+    else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** Whether a repository-relative file falls under a path: "web/" (a directory), "src/a.ts", or a glob with *. */
+export function matchesPath(file: string, pattern: string): boolean {
+  const p = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  if (p === "" || p === "." || p === "/") return true;
+  if (p.includes("*") || p.includes("?")) return globToRegExp(p).test(file);
+  if (p.endsWith("/")) return file.startsWith(p);
+  return file === p || file.startsWith(`${p}/`);
+}
+
+/** The paths a check watches; empty: the whole repository. */
+export function checkPaths(check: CheckDef): string[] {
+  if (check.paths && check.paths.length > 0) return check.paths;
+  if (check.cwd && check.cwd !== ".") return [`${check.cwd.replace(/\\/g, "/").replace(/\/$/, "")}/`];
+  return [];
+}
+
+/** Whether a check applies to a change; with the changed files unknown, every check applies. */
+export function checkApplies(check: CheckDef, files: string[] | null): boolean {
+  const paths = checkPaths(check);
+  if (paths.length === 0 || files === null) return true;
+  return files.some((f) => paths.some((p) => matchesPath(f, p)));
+}
+
+export interface CheckRun {
+  outcome: CheckOutcome;
+  /** Exit code, or null when it was stopped (timeout) or could not start. */
+  exitCode: number | null;
+  timedOut: boolean;
+  /** Combined output, trimmed to the end. */
+  output: string;
+  seconds: number;
+}
+
+const MAX_OUTPUT = 200_000;
+
+/** Runs one check through the system shell, in the repository (or its cwd). Never throws. */
+export function runCheck(check: CheckDef, repo: string, defaultTimeoutMinutes: number): Promise<CheckRun> {
+  const started = Date.now();
+  const cwd = path.join(repo, check.cwd ?? ".");
+  const timeoutMs = (check.timeoutMinutes ?? defaultTimeoutMinutes) * 60_000;
+  return new Promise((resolve) => {
+    let output = "";
+    const append = (chunk: Buffer) => {
+      output += chunk.toString("utf8");
+      if (output.length > MAX_OUTPUT * 2) output = output.slice(-MAX_OUTPUT);
+    };
+    const finish = (exitCode: number | null, timedOut: boolean, extra = "") => {
+      const text = `${output}${extra}`.slice(-MAX_OUTPUT);
+      resolve({ outcome: exitCode === 0 && !timedOut ? "pass" : "fail", exitCode, timedOut, output: text, seconds: Math.round((Date.now() - started) / 1000) });
+    };
+    if (!fs.existsSync(cwd)) {
+      finish(null, false, `检查的目录不存在：${cwd}`);
+      return;
+    }
+    let child;
+    try {
+      // CI=1: test runners stay non-interactive (no watch mode, no prompts).
+      child = spawn(check.command, { cwd, shell: true, env: { ...process.env, CI: process.env.CI ?? "1" }, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" });
+    } catch (error) {
+      finish(null, false, `无法启动：${(error as Error).message}`);
+      return;
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        // The whole process group: a test runner's own children too.
+        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL");
+        else child.kill("SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }, timeoutMs);
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      finish(null, false, `\n无法启动：${error.message}`);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish(code, timedOut, timedOut ? `\n（超过 ${check.timeoutMinutes ?? defaultTimeoutMinutes} 分钟，已停止）` : "");
+    });
+  });
+}
+
+/** The last lines of a check's output, for a message to the agent. */
+export function tail(text: string, lines = 60): string {
+  const all = text.trimEnd().split(/\r?\n/);
+  return (all.length > lines ? ["…", ...all.slice(-lines)] : all).join("\n");
+}
+
+/** A file name for a check's log. */
+export function logName(name: string): string {
+  return `${name.replace(/[^\p{L}\p{N}._-]+/gu, "-").replace(/^-+|-+$/g, "") || "check"}.log`;
+}

package/engine/src/git.ts

@@ -0,0 +1,30 @@
+import { execFileSync } from "node:child_process";
+
+export interface GitInfo {
+  isRepo: boolean;
+  /** Current branch; null when not a repository or HEAD is detached. */
+  branch: string | null;
+  detached: boolean;
+  /** Branches that must never receive the pipeline's commits. */
+  protectedBranches: string[];
+}
+
+function git(repo: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function gitInfo(repo: string): GitInfo {
+  if (git(repo, ["rev-parse", "--is-inside-work-tree"]) !== "true") {
+    return { isRepo: false, branch: null, detached: false, protectedBranches: [] };
+  }
+  // symbolic-ref works before the first commit, unlike rev-parse --abbrev-ref HEAD.
+  const branch = git(repo, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  const protectedBranches = new Set(["main", "master"]);
+  const originHead = git(repo, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (originHead) protectedBranches.add(originHead.replace(/^origin\//, ""));
+  return { isRepo: true, branch, detached: branch === null, protectedBranches: [...protectedBranches] };
+}

package/engine/src/joint.ts

@@ -0,0 +1,173 @@
+// Joint requirements (ADR 0025): one requirement that also changes other repositories
+// (e.g. the backend of a frontend project). The run in the chat's repository coordinates:
+// it designs the whole change and the interface contract, then each other repository gets
+// a Paseo worktree on the requirement's branch where its own implementation, code review
+// and fixes run (in parallel with this repository's); handoff, verification and the report
+// stay here. Everything is committed locally only.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { type CheckDef, type RelatedRepo, resolveRelatedRepo } from "./config.js";
+import type { AgentRuntime } from "./runtime.js";
+import { ensurePipelineDir, hashFile, type JointRepo, type PipelineState } from "./state.js";
+
+/** At most this many other repositories in one requirement (three in all). */
+export const MAX_JOINT = 2;
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** Where a step runs: this repository (no target) or one of the joint repositories. */
+export interface StepTarget {
+  name: string;
+  slug: string;
+  repo: string;
+  featureDir: string;
+  workspaceId: string | null;
+  branch: string | null;
+  joint: JointRepo;
+}
+
+/** An ASCII suffix for step keys, from the repository's directory name. */
+export function slugFor(dir: string, taken: string[]): string {
+  const base = path.basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "repo";
+  let slug = base;
+  for (let i = 2; taken.includes(slug); i++) slug = `${base}-${i}`;
+  return slug;
+}
+
+/** Problems with the spec's "联合开发" names for this configuration, or null. */
+export function jointProblem(names: string[], related: RelatedRepo[], projectDir: string): string | null {
+  if (names.length === 0) return null;
+  if (names.length > MAX_JOINT) return `联合开发最多再涉及 ${MAX_JOINT} 个仓库（一共 ${MAX_JOINT + 1} 个），需求说明里写了 ${names.length} 个：${names.join("、")}`;
+  for (const name of names) {
+    const r = related.find((x) => x.name === name);
+    if (!r) {
+      return `需求说明的"联合开发"中有「${name}」，但项目配置的 relatedRepos 里没有登记这个仓库${related.length > 0 ? `（已登记：${related.map((x) => x.name).join("、")}）` : ""}。请在 .requirement-pipeline.json 中登记，或改正需求说明`;
+    }
+    const dir = resolveRelatedRepo(r, projectDir);
+    if (!fs.existsSync(dir)) return `联合开发的仓库「${name}」不在这台机器上：${dir}`;
+    try {
+      git(dir, "rev-parse", "--git-dir");
+    } catch {
+      return `联合开发的仓库「${name}」不是 git 仓库：${dir}`;
+    }
+  }
+  return null;
+}
+
+/** The joint repositories this run works in: those the spec names now, in that order. */
+export function activeJoint(state: Pick<PipelineState, "joint">, names: string[]): JointRepo[] {
+  return names.map((n) => (state.joint ?? []).find((j) => j.name === n)).filter((j): j is JointRepo => j !== undefined);
+}
+
+/**
+ * Creates the worktree of each named repository that does not have one yet, on the branch
+ * feature/<requirement>, cut from what that repository has checked out. Returns the entries.
+ */
+export async function ensureJointRepos(input: {
+  runtime: Pick<AgentRuntime, "createWorktree">;
+  state: PipelineState;
+  featureDir: string;
+  names: string[];
+  related: RelatedRepo[];
+  projectDir: string;
+  title: string;
+  log: (message: string) => void;
+}): Promise<JointRepo[]> {
+  const { state } = input;
+  state.joint ??= [];
+  for (const name of input.names) {
+    if (state.joint.some((j) => j.name === name)) continue;
+    const r = input.related.find((x) => x.name === name);
+    if (!r) throw new Error(`联合开发的仓库「${name}」没有在 relatedRepos 中登记`);
+    const sourceRepo = fs.realpathSync(resolveRelatedRepo(r, input.projectDir));
+    const branch = `feature/${path.basename(input.featureDir)}`;
+    let exists = true;
+    try {
+      git(sourceRepo, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`);
+    } catch {
+      exists = false;
+    }
+    if (exists) {
+      throw new Error(`联合开发的仓库「${name}」（${sourceRepo}）里已经有分支 ${branch}。可能是之前开始过这个需求：请在那个仓库确认后删除或改名这个分支，再继续`);
+    }
+    const head = git(sourceRepo, "rev-parse", "--abbrev-ref", "HEAD");
+    const baseRef = head === "HEAD" ? git(sourceRepo, "rev-parse", "HEAD") : head;
+    const created = await input.runtime.createWorktree({
+      sourceRepo,
+      baseRef,
+      branchName: branch,
+      title: `${input.title}（${name}）`,
+      callerAgentId: state.originAgentId,
+    });
+    const repo = fs.realpathSync(created.directory);
+    ensurePipelineDir(repo, input.featureDir);
+    const entry: JointRepo = {
+      name,
+      slug: slugFor(sourceRepo, state.joint.map((j) => j.slug)),
+      sourceRepo,
+      repo,
+      workspaceId: created.workspaceId,
+      branch,
+      specHash: null,
+    };
+    state.joint.push(entry);
+    input.log(`联合开发：为「${name}」新建了工作区 ${repo}（分支 ${branch}，从 ${baseRef} 切出）`);
+  }
+  return activeJoint(state, input.names);
+}
+
+/**
+ * Copies the requirement's documents (spec, design, contract, preview) from this repository's
+ * feature directory into each joint repository's, and commits them there when they changed,
+ * so whoever reviews and merges that repository reads them next to its code.
+ */
+export function syncJointDocs(entries: JointRepo[], mainRepo: string, featureDir: string, files: string[], title: string, log: (message: string) => void): void {
+  const from = path.join(mainRepo, featureDir);
+  for (const entry of entries) {
+    const to = path.join(entry.repo, featureDir);
+    fs.mkdirSync(to, { recursive: true });
+    ensurePipelineDir(entry.repo, featureDir);
+    const copied: string[] = [];
+    for (const file of files) {
+      const src = path.join(from, file);
+      if (!fs.existsSync(src)) continue;
+      fs.cpSync(src, path.join(to, file), { recursive: true });
+      copied.push(path.join(featureDir, file));
+    }
+    const spec = path.join(from, "spec.md");
+    if (fs.existsSync(spec)) entry.specHash = hashFile(spec);
+    if (copied.length === 0) continue;
+    try {
+      git(entry.repo, "add", "--", ...copied);
+      if (git(entry.repo, "diff", "--cached", "--name-only", "--", ...copied)) {
+        git(entry.repo, "commit", "-q", "-m", `docs(req): ${title} 的需求说明和方案（同步自主仓库）`, "--", ...copied);
+        log(`联合开发：已把 ${files.filter((f) => fs.existsSync(path.join(from, f))).join("、")} 同步到「${entry.name}」并提交`);
+      }
+    } catch (error) {
+      const stderr = (error as { stderr?: Buffer | string }).stderr?.toString().trim();
+      log(`联合开发：同步到「${entry.name}」后提交失败（${stderr || (error as Error).message}），文件已复制，步骤照常可以读到`);
+    }
+  }
+}
+
+/** The quality-gate checks a joint repository defines in its own project configuration. */
+export function loadProjectChecks(repo: string, log: (message: string) => void): CheckDef[] {
+  const file = path.join(repo, ".requirement-pipeline.json");
+  if (!fs.existsSync(file)) return [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as { checks?: unknown };
+    if (!Array.isArray(raw.checks)) return [];
+    const checks = raw.checks.filter(
+      (c): c is CheckDef => typeof c === "object" && c !== null && typeof (c as CheckDef).name === "string" && typeof (c as CheckDef).command === "string",
+    );
+    if (checks.length !== raw.checks.length) log(`${file} 中有写法不对的检查，已跳过`);
+    return checks;
+  } catch (error) {
+    log(`读不了 ${file}：${(error as Error).message}，这个仓库不运行质量门`);
+    return [];
+  }
+}