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

package/engine/src/notifiers.ts

@@ -0,0 +1,76 @@
+// External notifiers: local modules the engine calls at key events, in addition to
+// the message it sends into the originating chat. This is the slot for an internal
+// IM (or any other channel); see notifiers/im-template.mjs and contracts/notifier-event.md.
+//
+// A notifier never affects the pipeline: errors and timeouts are logged and ignored.
+
+import { pathToFileURL } from "node:url";
+
+export const NOTIFIER_EVENT_TYPES = ["milestone", "blocked", "permission", "failed", "completed", "digest", "phase_done"] as const;
+export type NotifierEventType = (typeof NOTIFIER_EVENT_TYPES)[number];
+
+export interface NotifierConfig {
+  /** Absolute path of the module (resolved when the config is loaded). */
+  module: string;
+  /** Events to send; all of them when omitted. */
+  events?: NotifierEventType[];
+  /** Passed to the module as its second argument, e.g. a webhook address or a group ID. */
+  options?: Record<string, unknown>;
+}
+
+export interface NotifierEvent {
+  /** Format version of this object. */
+  schema: 1;
+  type: NotifierEventType;
+  at: string;
+  kitVersion: string;
+  feature: { dir: string; name: string; title: string };
+  repo: string;
+  branch: string | null;
+  profile: string;
+  /** Chat agent the run reports to, if any. */
+  originAgentId: string | null;
+  /** One or two plain sentences, ready to post as is. */
+  text: string;
+  /** Type-specific fields; see contracts/notifier-event.md. */
+  details: Record<string, unknown>;
+}
+
+export type NotifierFunction = (event: NotifierEvent, options: Record<string, unknown>) => unknown;
+
+const TIMEOUT_MS = 15_000;
+
+async function loadNotifier(file: string): Promise<NotifierFunction> {
+  const module = (await import(pathToFileURL(file).href)) as { default?: unknown; notify?: unknown };
+  const fn = module.default ?? module.notify;
+  if (typeof fn !== "function") throw new Error(`${file} 没有导出 notify 函数（export default 或 export function notify）`);
+  return fn as NotifierFunction;
+}
+
+/** Calls every configured notifier that wants this event. Never throws. */
+export async function dispatchNotifiers(
+  notifiers: NotifierConfig[],
+  event: NotifierEvent,
+  log: (message: string) => void,
+): Promise<void> {
+  const wanted = notifiers.filter((n) => !n.events || n.events.includes(event.type));
+  await Promise.all(
+    wanted.map(async (n) => {
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        const fn = await loadNotifier(n.module);
+        await Promise.race([
+          Promise.resolve(fn(event, n.options ?? {})),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`超过 ${TIMEOUT_MS / 1000} 秒没有完成`)), TIMEOUT_MS);
+          }),
+        ]);
+        log(`外部通知已发送（${event.type}）：${n.module}`);
+      } catch (error) {
+        log(`外部通知失败（${event.type}，${n.module}）：${(error as Error).message}。不影响流水线。`);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }),
+  );
+}

package/engine/src/notify-test.ts

@@ -0,0 +1,97 @@
+// Sends one test event to every configured notifier: `req notify-test [--type blocked] [--repo <dir>]`.
+// Lets whoever implements the IM module check it without running a pipeline.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig } from "./config.js";
+import { defaultConfigPath, kitVersion } from "./locations.js";
+import { dispatchNotifiers, NOTIFIER_EVENT_TYPES, type NotifierEvent, type NotifierEventType } from "./notifiers.js";
+
+/** A realistic event of the given type, with the details the pipeline would send. */
+export function sampleEvent(type: NotifierEventType, repo: string): NotifierEvent {
+  const featureDir = "docs/features/20261012-sms-login";
+  const resume = `node "<req-kit>/bin/start-pipeline.mjs" --feature ${featureDir} --resume`;
+  const samples: Record<NotifierEventType, { text: string; details: Record<string, unknown> }> = {
+    milestone: { text: "技术方案已经确定（审核 1 轮），开始写代码。", details: { milestone: "design-settled" } },
+    blocked: {
+      text: "方案审核发现 1 个需要需求方决定的问题，流水线已暂停，请到发起的对话中回答。",
+      details: { questions: ["验证码有效期是 5 分钟还是 10 分钟？"], resumeCommand: resume },
+    },
+    permission: {
+      text: "「实现」步骤在等待权限批准，批准前会一直停在这里。",
+      details: { stepTitle: "实现", agentTitle: "实现 · 短信验证码登录", requests: ["运行 npm install"] },
+    },
+    failed: {
+      text: "开发流水线在「代码评审」步骤中断：agent 连续出错。",
+      details: { stepTitle: "代码评审", reason: "agent 连续出错", logPath: `${featureDir}/.pipeline/pipeline.log`, resumeCommand: resume },
+    },
+    digest: {
+      text: "【req-kit 需求总览】shop\n共 3 个需求：需要处理 1，待验收 1，开发中 1。",
+      details: { features: [{ name: "20261012-sms-login", title: "短信验证码登录", stage: "待验收" }] },
+    },
+    phase_done: {
+      text: `研发已完成，可以提测：提测说明在 ${featureDir}/handoff.md。`,
+      details: { handoffPath: `${featureDir}/handoff.md`, mode: "gated", verifyCommand: `${resume} --phase verify`, verifyAt: null, handbacks: 0 },
+    },
+    completed: {
+      text: "开发流水线已结束：已完成，可以验收。",
+      details: { outcome: "completed", summary: "6 条验收标准全部通过。", reportPath: `${featureDir}/report.md` },
+    },
+  };
+  return {
+    schema: 1,
+    type,
+    at: new Date().toISOString(),
+    kitVersion: kitVersion(),
+    feature: { dir: featureDir, name: "20261012-sms-login", title: "短信验证码登录（测试消息）" },
+    repo,
+    branch: "feature/20261012-sms-login",
+    profile: "standard",
+    originAgentId: null,
+    text: `【测试】${samples[type].text}`,
+    details: samples[type].details,
+  };
+}
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: { type: { type: "string", default: "completed" }, repo: { type: "string" }, config: { type: "string" } },
+  });
+  const type = values.type as NotifierEventType;
+  if (!NOTIFIER_EVENT_TYPES.includes(type)) {
+    console.error(`--type 只能是 ${NOTIFIER_EVENT_TYPES.join("、")} 之一`);
+    return 2;
+  }
+  const repo = path.resolve(values.repo ?? process.cwd());
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath();
+  const { config } = loadConfig(configPath, fs.existsSync(repo) ? repo : undefined);
+  if (config.notifiers.length === 0) {
+    console.log(`没有配置外部通知（${configPath} 中的 notifiers 为空）。写法见 notifiers/im-template.mjs 开头的说明。`);
+    return 1;
+  }
+  const wanted = config.notifiers.filter((n) => !n.events || n.events.includes(type));
+  if (wanted.length === 0) {
+    console.log(`配置的通知都没有订阅 ${type} 事件。可以用 --type 换一种，例如 --type ${config.notifiers[0].events?.[0] ?? "completed"}。`);
+    return 1;
+  }
+  let failed = false;
+  // Lets a module show what it would send (the template does) without a real IM.
+  process.env.REQ_KIT_NOTIFY_TEST = "1";
+  await dispatchNotifiers(config.notifiers, sampleEvent(type, repo), (message) => {
+    if (message.startsWith("外部通知失败")) failed = true;
+    console.log(message);
+  });
+  return failed ? 1 : 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main().then(
+    (code) => process.exit(code),
+    (error: Error) => {
+      console.error(error.message);
+      process.exit(1);
+    },
+  );
+}

package/engine/src/paseo-json.ts

@@ -0,0 +1,73 @@
+// paseo.json checks shared by the doctor.
+//
+// Paseo 0.11 runs project commands with a different shell on each system:
+//   worktree.setup: bash (macOS, Linux) / powershell -ExecutionPolicy Bypass (Windows)
+//   scripts:        the terminal's shell, $SHELL or /bin/sh (macOS, Linux) / cmd.exe (Windows)
+// paseo.json is committed and shared, so commands should work in all of them: plain program
+// invocations, with environment variables read by the program (see /req-setup's helpers).
+
+export type PaseoJson = { worktree?: { setup?: unknown }; scripts?: Record<string, { type?: string; command?: string; port?: number }> };
+
+export type ShellStyle = "posix" | "powershell" | "cmd";
+
+const STYLE_NAMES: Record<ShellStyle, string> = { posix: "bash/sh", powershell: "PowerShell", cmd: "cmd.exe" };
+
+/** Shell-specific syntax found in a command (empty: works the same everywhere). */
+export function shellStyles(command: string): ShellStyle[] {
+  const styles = new Set<ShellStyle>();
+  if (/\$env:[A-Za-z_]/i.test(command) || /\b(Test-Path|Copy-Item|Set-Location|Get-ChildItem|Remove-Item)\b/.test(command)) styles.add("powershell");
+  if (/%[A-Za-z_][A-Za-z0-9_]*%/.test(command)) styles.add("cmd");
+  if (/(^|[^:\w`])\$\{?(?!env:)[A-Za-z_]/i.test(command) || /\[\s+-[a-z]\s/.test(command) || /(^|\s)(cp|mv|rm|export)\s/.test(command) || /\|\||&&/.test(command)) {
+    // `&&` works in cmd and PowerShell 7 too, but not in Windows PowerShell 5.1, which Paseo uses for setup.
+    styles.add("posix");
+  }
+  return [...styles];
+}
+
+function setupCommands(raw: PaseoJson): string[] {
+  const setup = raw.worktree?.setup;
+  if (Array.isArray(setup)) return setup.map(String);
+  return typeof setup === "string" ? setup.split(/\r?\n/).filter((l) => l.trim()) : [];
+}
+
+export interface PaseoJsonIssue {
+  /** "fails": the command will not work on this machine; "portable": it only works on some systems. */
+  kind: "fails" | "portable";
+  text: string;
+  fix: string;
+}
+
+const FIX =
+  "改成各系统都一样的写法：准备命令用 node scripts/paseo/copy-local-files.mjs .env，服务用 node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}（/req-setup 会写入这两个脚本）";
+
+/** Problems of the project's paseo.json for the system Paseo runs on (process.platform by default). */
+export function paseoJsonIssues(raw: PaseoJson, platform: NodeJS.Platform = process.platform): PaseoJsonIssue[] {
+  const windows = platform === "win32";
+  const setupShell: ShellStyle = windows ? "powershell" : "posix";
+  const scriptShell: ShellStyle = windows ? "cmd" : "posix";
+  const issues: PaseoJsonIssue[] = [];
+  const check = (where: string, command: string, shell: ShellStyle) => {
+    const styles = shellStyles(command);
+    if (styles.length === 0) return;
+    const short = command.length > 60 ? `${command.slice(0, 60)}…` : command;
+    const foreign = styles.filter((s) => s !== shell);
+    if (foreign.length > 0) {
+      issues.push({
+        kind: "fails",
+        text: `${where}「${short}」是 ${foreign.map((s) => STYLE_NAMES[s]).join("、")} 写法，这台机器上 Paseo 用 ${STYLE_NAMES[shell]} 执行，会失败`,
+        fix: FIX,
+      });
+    } else {
+      issues.push({
+        kind: "portable",
+        text: `${where}「${short}」用了 ${STYLE_NAMES[shell]} 的写法，在这台机器上可以用，换到其他系统（Windows 和 macOS/Linux 之间）会失败`,
+        fix: FIX,
+      });
+    }
+  };
+  for (const cmd of setupCommands(raw)) check("paseo.json 的 worktree.setup 中", cmd, setupShell);
+  for (const [name, s] of Object.entries(raw.scripts ?? {})) {
+    check(`paseo.json 的${s.type === "service" ? "服务" : "脚本"} ${name}`, String(s.command ?? ""), scriptShell);
+  }
+  return issues;
+}

package/engine/src/paseo-profiles.ts

@@ -0,0 +1,133 @@
+// Paseo agent profiles: named launch bundles (provider, model, mode, thinking level,
+// features) that people set up once in Paseo's settings. req-kit roles and review
+// panel members can name one instead of spelling the settings out:
+//
+//   "builder": { "paseoProfile": "实现" }
+//   "reviewer": { "paseoProfile": "评审", "thinkingOptionId": "high" }   // own fields win
+//
+// The names are resolved against the daemon when a run starts, so changing the
+// profile in Paseo changes the next run without touching req-kit's config.
+
+import type { AgentProfile, PipelineConfig } from "./config.js";
+
+/** The fields of Paseo's AgentProfile that req-kit uses (protocol/src/agent-profile.ts). */
+export interface PaseoProfile {
+  id: string;
+  name: string;
+  provider: string;
+  model?: string;
+  modeId?: string;
+  thinkingOptionId?: string;
+  featureValues?: Record<string, unknown>;
+  notes?: string;
+}
+
+export class ProfileResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProfileResolutionError";
+  }
+}
+
+export function findPaseoProfile(name: string, available: PaseoProfile[]): PaseoProfile | null {
+  const wanted = name.trim();
+  return (
+    available.find((p) => p.name === wanted) ??
+    available.find((p) => p.name.toLowerCase() === wanted.toLowerCase()) ??
+    available.find((p) => p.id === wanted) ??
+    null
+  );
+}
+
+/**
+ * Turns a role that names a Paseo profile into concrete agent settings. Settings
+ * written next to `paseoProfile` override the profile's; feature values are merged.
+ * Roles without `paseoProfile` are returned unchanged.
+ */
+export function resolveAgentProfile(label: string, profile: AgentProfile, available: PaseoProfile[] | null): AgentProfile {
+  if (!profile.paseoProfile) return profile;
+  if (available === null) {
+    throw new ProfileResolutionError(`${label} 使用 Paseo profile「${profile.paseoProfile}」，但无法从 daemon 读取 profile 列表`);
+  }
+  const found = findPaseoProfile(profile.paseoProfile, available);
+  if (!found) {
+    const names = available.map((p) => `「${p.name}」`).join("、") || "（还没有任何 profile）";
+    throw new ProfileResolutionError(
+      `${label} 使用的 Paseo profile「${profile.paseoProfile}」不存在。现有的 profile：${names}。在 Paseo 的 设置 → Agents → Agent profiles 中查看或新建`,
+    );
+  }
+  if (!found.model) {
+    throw new ProfileResolutionError(`Paseo profile「${found.name}」没有选择模型，req-kit 需要明确的模型。请在 Paseo 设置中为它选择模型`);
+  }
+  const resolved: AgentProfile = { ...profile, provider: profile.provider ?? `${found.provider}/${found.model}` };
+  const modeId = profile.modeId ?? found.modeId;
+  const thinking = profile.thinkingOptionId ?? found.thinkingOptionId;
+  const features = found.featureValues || profile.featureValues ? { ...found.featureValues, ...profile.featureValues } : undefined;
+  if (modeId) resolved.modeId = modeId;
+  if (thinking) resolved.thinkingOptionId = thinking;
+  if (features) resolved.featureValues = features;
+  return resolved;
+}
+
+/** "Paseo profile「实现」→ claude/opus（模式 bypassPermissions）" */
+export function describeAgentProfile(profile: AgentProfile): string {
+  if (!profile.provider) return `Paseo profile「${profile.paseoProfile}」（运行时从 Paseo 读取设置）`;
+  const settings = `${profile.provider}${profile.modeId ? `（模式 ${profile.modeId}）` : ""}`;
+  return profile.paseoProfile ? `Paseo profile「${profile.paseoProfile}」→ ${settings}` : settings;
+}
+
+/** Reads the daemon's profiles from its config. Null when the daemon does not say. */
+export function profilesFromDaemonConfig(config: unknown): PaseoProfile[] | null {
+  if (typeof config !== "object" || config === null) return null;
+  const list = (config as { agentProfiles?: unknown }).agentProfiles;
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) return null;
+  return list.filter(
+    (p): p is PaseoProfile =>
+      typeof p === "object" && p !== null && typeof (p as PaseoProfile).name === "string" && typeof (p as PaseoProfile).provider === "string",
+  );
+}
+
+/** Whether any role or panel member names a Paseo profile. */
+export function usesPaseoProfiles(config: PipelineConfig): boolean {
+  return [
+    config.agents.builder,
+    config.agents.reviewer,
+    ...config.reviewPanel.members,
+    ...config.designProposals.members,
+    ...Object.values(config.phases.verify.agents),
+  ].some((p) =>
+    Boolean(p.paseoProfile),
+  );
+}
+
+/** The config with every Paseo profile name replaced by its settings. Throws ProfileResolutionError. */
+export function resolveConfigProfiles(config: PipelineConfig, available: PaseoProfile[] | null): PipelineConfig {
+  return {
+    ...config,
+    agents: {
+      builder: resolveAgentProfile("agents.builder", config.agents.builder, available),
+      reviewer: resolveAgentProfile("agents.reviewer", config.agents.reviewer, available),
+    },
+    reviewPanel: {
+      ...config.reviewPanel,
+      members: config.reviewPanel.members.map((m, i) => ({ ...m, ...resolveAgentProfile(`reviewPanel.members[${i}]`, m, available) })),
+    },
+    designProposals: {
+      ...config.designProposals,
+      members: config.designProposals.members.map((m, i) => ({
+        ...m,
+        ...resolveAgentProfile(`designProposals.members[${i}]`, m, available),
+      })),
+    },
+    phases: {
+      ...config.phases,
+      verify: {
+        ...config.phases.verify,
+        agents: Object.fromEntries(
+          Object.entries(config.phases.verify.agents).map(([role, p]) => [role, resolveAgentProfile(`phases.verify.agents.${role}`, p, available)]),
+        ),
+      },
+    },
+  };
+}