@brawnen/agent-harness-cli 0.1.0

package/src/commands/docs.js

@@ -0,0 +1,251 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { normalizeOutputPolicy } from "../lib/output-policy.js";
+import { loadProjectConfig } from "../lib/project-config.js";
+import { requireTaskState, resolveTaskId } from "../lib/state-store.js";
+
+const VALID_TYPES = new Set(["design-note", "adr"]);
+
+export function runDocs(argv) {
+  const [subcommand, ...rest] = argv;
+
+  if (!subcommand) {
+    console.error("缺少 docs 子命令。可用: scaffold");
+    return 1;
+  }
+
+  if (subcommand === "scaffold") {
+    return runDocsScaffold(rest);
+  }
+
+  console.error(`未知 docs 子命令: ${subcommand}。可用: scaffold`);
+  return 1;
+}
+
+function runDocsScaffold(argv) {
+  const parsed = parseDocsScaffoldArgs(argv);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  try {
+    const cwd = process.cwd();
+    const taskId = resolveTaskId(cwd, parsed.options.taskId);
+    const taskState = requireTaskState(cwd, taskId);
+    const projectConfig = loadProjectConfig(cwd);
+    const outputPolicy = normalizeOutputPolicy(projectConfig?.output_policy);
+    const plan = buildScaffoldPlan(cwd, taskState, outputPolicy, parsed.options);
+
+    if (!parsed.options.force && fs.existsSync(plan.absolutePath)) {
+      throw new Error(`文档已存在，请使用 --force 覆盖: ${plan.relativePath}`);
+    }
+
+    fs.mkdirSync(path.dirname(plan.absolutePath), { recursive: true });
+    fs.writeFileSync(plan.absolutePath, plan.content, "utf8");
+
+    console.log(`${JSON.stringify({
+      task_id: taskId,
+      type: parsed.options.type,
+      path: plan.relativePath,
+      title: plan.title
+    }, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+}
+
+function parseDocsScaffoldArgs(argv) {
+  const options = {
+    force: false,
+    path: null,
+    taskId: null,
+    title: null,
+    type: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--task-id") {
+      options.taskId = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--type") {
+      const value = argv[index + 1] ?? null;
+      if (!VALID_TYPES.has(value)) {
+        return { ok: false, error: "无效的 --type 参数。可选值: design-note, adr" };
+      }
+      options.type = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--path") {
+      options.path = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      options.title = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (!options.type) {
+    return { ok: false, error: "需要 --type 参数。可选值: design-note, adr" };
+  }
+
+  return { ok: true, options };
+}
+
+function buildScaffoldPlan(cwd, taskState, outputPolicy, options) {
+  const context = buildTaskContext(taskState);
+  const relativePath = options.path ?? buildDefaultDocPath(options.type, taskState.task_id, context, outputPolicy);
+  const absolutePath = path.join(cwd, relativePath);
+  const title = options.title ?? buildDefaultTitle(options.type, context.goal);
+  const content = buildTemplate(options.type, title, context);
+
+  return {
+    title,
+    relativePath,
+    absolutePath,
+    content
+  };
+}
+
+function buildDefaultDocPath(type, taskId, context, outputPolicy) {
+  const directory = type === "design-note"
+    ? outputPolicy.design_note.directory
+    : outputPolicy.adr.directory;
+  const datePrefix = new Date().toISOString().slice(0, 10);
+  const slug = slugify(taskId || context.goal || type);
+  const suffix = type === "design-note" ? "design-note" : "adr";
+  return path.posix.join(directory.replace(/\\/g, "/"), `${datePrefix}-${slug}-${suffix}.md`);
+}
+
+function buildDefaultTitle(type, goal) {
+  const normalizedGoal = String(goal ?? "").trim();
+  if (!normalizedGoal) {
+    return type === "design-note" ? "Design Note" : "ADR";
+  }
+  return type === "design-note"
+    ? `Design Note: ${normalizedGoal}`
+    : `ADR: ${normalizedGoal}`;
+}
+
+function buildTemplate(type, title, context) {
+  if (type === "adr") {
+    return buildAdrTemplate(title, context);
+  }
+  return buildDesignNoteTemplate(title, context);
+}
+
+function buildDesignNoteTemplate(title, context) {
+  return [
+    `# ${title}`,
+    "",
+    "## 背景",
+    "",
+    `- task_id: \`${context.task_id}\``,
+    `- intent: \`${context.intent}\``,
+    `- risk_level: \`${context.risk_level}\``,
+    "",
+    "## 目标",
+    "",
+    context.goal ? `- ${context.goal}` : "- 待补充",
+    "",
+    "## 作用范围",
+    "",
+    ...toBulletLines(context.scope),
+    "",
+    "## 方案",
+    "",
+    "- 待补充",
+    "",
+    "## 风险与权衡",
+    "",
+    "- 待补充",
+    "",
+    "## 验证计划",
+    "",
+    "- 待补充",
+    ""
+  ].join("\n");
+}
+
+function buildAdrTemplate(title, context) {
+  return [
+    `# ${title}`,
+    "",
+    "## 状态",
+    "",
+    "Proposed",
+    "",
+    "## 背景",
+    "",
+    `- task_id: \`${context.task_id}\``,
+    `- intent: \`${context.intent}\``,
+    `- risk_level: \`${context.risk_level}\``,
+    context.goal ? `- goal: ${context.goal}` : "- goal: 待补充",
+    "",
+    "## 决策",
+    "",
+    "- 待补充",
+    "",
+    "## 后果",
+    "",
+    "- 正面影响：待补充",
+    "- 代价与风险：待补充",
+    "",
+    "## 影响范围",
+    "",
+    ...toBulletLines(context.scope),
+    ""
+  ].join("\n");
+}
+
+function buildTaskContext(taskState) {
+  const contract = taskState?.confirmed_contract ?? {};
+  const draft = taskState?.task_draft ?? {};
+  return {
+    task_id: taskState?.task_id ?? "",
+    goal: String(contract.goal ?? draft.goal ?? "").trim(),
+    intent: String(contract.intent ?? draft.intent ?? "unknown"),
+    risk_level: String(contract.risk_level ?? draft?.derived?.risk_level ?? "medium"),
+    scope: normalizeStringArray(contract.scope ?? draft.scope)
+  };
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => String(item ?? "").trim())
+    .filter(Boolean);
+}
+
+function toBulletLines(items) {
+  if (items.length === 0) {
+    return ["- 待补充"];
+  }
+  return items.map((item) => `- ${item}`);
+}
+
+function slugify(value) {
+  const normalized = String(value ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "task";
+}

package/src/commands/gate.js

@@ -0,0 +1,236 @@
+import path from "node:path";
+
+import { appendAuditEntry } from "../lib/audit-store.js";
+import { loadProjectConfig } from "../lib/project-config.js";
+import { getTaskState, resolveActiveTaskId } from "../lib/state-store.js";
+
+const EXIT_ALLOW = 0;
+const EXIT_BLOCK = 1;
+const EXIT_REQUIRE_CONFIRM = 2;
+
+const WRITE_TOOLS = new Set(["Write", "Edit", "Bash", "NotebookEdit"]);
+
+export function runGate(argv) {
+  const [subcommand, ...rest] = argv;
+
+  if (subcommand !== "before-tool") {
+    console.error("gate 目前只支持 before-tool");
+    return 1;
+  }
+
+  const parsed = parseBeforeToolArgs(rest);
+  if (!parsed.ok) {
+    console.error(parsed.error);
+    return 1;
+  }
+
+  const result = beforeTool(process.cwd(), parsed.options);
+  console.log(`${JSON.stringify(result, null, 2)}\n`);
+  return result.exit_code;
+}
+
+function parseBeforeToolArgs(argv) {
+  const options = {
+    filePath: null,
+    taskId: null,
+    tool: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--tool") {
+      options.tool = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--task-id") {
+      options.taskId = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--file-path") {
+      options.filePath = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+
+    return { ok: false, error: `未知参数: ${arg}` };
+  }
+
+  if (!options.tool) {
+    return { ok: false, error: "需要 --tool 参数" };
+  }
+
+  return { ok: true, options };
+}
+
+function beforeTool(cwd, options) {
+  const taskId = options.taskId ?? resolveActiveTaskId(cwd);
+  const taskState = taskId ? getTaskState(cwd, taskId) : null;
+  const config = loadProjectConfig(cwd);
+
+  if (!taskState) {
+    if (taskId) {
+      appendAuditEntry(cwd, {
+        description: "State 文件不存在，降级允许执行",
+        event_type: "gate_violation",
+        phase: "execute",
+        risk_at_time: "unknown",
+        signal: "proceed_to_execute",
+        task_id: taskId
+      });
+    }
+    return allow("State 文件不存在，降级允许");
+  }
+
+  const currentState = taskState.current_state;
+  const currentPhase = taskState.current_phase;
+  const filePath = normalizeFilePath(cwd, options.filePath);
+  const riskAssessment = deriveRiskAssessment(taskState, config, filePath);
+  const riskLevel = riskAssessment.level;
+
+  if (currentState === "needs_clarification" && isWriteTool(options.tool)) {
+    return block(cwd, taskState.task_id, currentPhase, riskLevel, "任务处于 needs_clarification 状态，禁止执行写入操作");
+  }
+
+  if (currentState === "draft" && isWriteTool(options.tool)) {
+    return block(cwd, taskState.task_id, currentPhase, riskLevel, "任务合同未闭合（draft 状态），禁止执行写入操作");
+  }
+
+  if (["blocked", "failed", "done", "suspended"].includes(currentState) && isWriteTool(options.tool)) {
+    return block(cwd, taskState.task_id, currentPhase, riskLevel, `任务处于 ${currentState} 状态，禁止执行写入操作`);
+  }
+
+  if (riskAssessment.requiresConfirmation && isWriteTool(options.tool) && !hasRiskConfirmation(taskState)) {
+    return requireConfirmation(cwd, taskState.task_id, currentPhase, "high", "任务命中高风险范围，需要用户确认后继续");
+  }
+
+  if (filePath && config && isWriteTool(options.tool) && config.protected_paths.some((pattern) => pathMatch(filePath, pattern))) {
+    return block(cwd, taskState.task_id, currentPhase, riskLevel, `目标路径 ${filePath} 命中 protected_paths，禁止写入`);
+  }
+
+  if (filePath && isWriteTool(options.tool)) {
+    const scope = taskState?.confirmed_contract?.scope ?? taskState?.task_draft?.scope ?? [];
+    const pathScopes = scope.filter((item) => item.includes("/") || item.includes("*"));
+    if (pathScopes.length > 0 && !pathScopes.some((pattern) => pathMatch(filePath, pattern))) {
+      return block(cwd, taskState.task_id, currentPhase, riskLevel, `目标路径 ${filePath} 超出任务 scope: ${pathScopes.join(", ")}`);
+    }
+  }
+
+  return allow("门禁通过");
+}
+
+function deriveRiskAssessment(taskState, config, filePath) {
+  const baseLevel = normalizeRiskLevel(
+    taskState?.confirmed_contract?.risk_level ?? taskState?.task_draft?.derived?.risk_level ?? "medium"
+  );
+  const matchedRule = matchRiskRule(config?.risk_rules, filePath);
+  const effectiveLevel = pickHigherRiskLevel(baseLevel, matchedRule?.level ?? null);
+
+  return {
+    level: effectiveLevel,
+    requiresConfirmation: baseLevel === "high" || matchedRule?.requiresConfirmation === true
+  };
+}
+
+function matchRiskRule(riskRules, filePath) {
+  if (!riskRules || typeof riskRules !== "object" || !filePath) {
+    return null;
+  }
+
+  for (const level of ["high", "medium", "low"]) {
+    const rule = riskRules[level];
+    if (!rule || typeof rule !== "object") {
+      continue;
+    }
+
+    const patterns = Array.isArray(rule.path_matches) ? rule.path_matches : [];
+    if (patterns.some((pattern) => pathMatch(filePath, String(pattern)))) {
+      return {
+        level,
+        requiresConfirmation: rule.requires_confirmation === true
+      };
+    }
+  }
+
+  return null;
+}
+
+function pickHigherRiskLevel(current, next) {
+  const order = ["low", "medium", "high"];
+  const currentIndex = order.indexOf(normalizeRiskLevel(current));
+  const nextIndex = order.indexOf(normalizeRiskLevel(next));
+  return currentIndex >= nextIndex ? normalizeRiskLevel(current) : normalizeRiskLevel(next);
+}
+
+function normalizeRiskLevel(value) {
+  if (value === "low" || value === "medium" || value === "high") {
+    return value;
+  }
+  return "medium";
+}
+
+function hasRiskConfirmation(taskState) {
+  return Array.isArray(taskState?.override_history) &&
+    taskState.override_history.some((item) => item.event_type === "manual_confirmation");
+}
+
+function isWriteTool(toolName) {
+  return WRITE_TOOLS.has(toolName);
+}
+
+function normalizeFilePath(cwd, filePath) {
+  if (!filePath) {
+    return null;
+  }
+
+  const absolute = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+  return path.relative(cwd, absolute).replace(/\\/g, "/");
+}
+
+function pathMatch(filePath, pattern) {
+  const relative = filePath.replace(/^\.\//, "");
+  const normalizedPattern = pattern.replace(/^\.\//, "");
+  const regex = globToRegExp(normalizedPattern);
+  return regex.test(relative) || relative.startsWith(normalizedPattern.replace(/\*+$/, "").replace(/\/$/, ""));
+}
+
+function globToRegExp(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "::DOUBLE_STAR::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLE_STAR::/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+function allow(reason) {
+  return { exit_code: EXIT_ALLOW, reason, signal: "proceed_to_execute" };
+}
+
+function block(cwd, taskId, phase, risk, reason) {
+  appendAuditEntry(cwd, {
+    description: reason,
+    event_type: "gate_violation",
+    phase,
+    risk_at_time: risk,
+    signal: "block_execution",
+    task_id: taskId
+  });
+  return { exit_code: EXIT_BLOCK, phase, reason, risk, signal: "block_execution" };
+}
+
+function requireConfirmation(cwd, taskId, phase, risk, reason) {
+  appendAuditEntry(cwd, {
+    description: reason,
+    event_type: "gate_violation",
+    phase,
+    risk_at_time: risk,
+    signal: "require_confirmation",
+    task_id: taskId
+  });
+  return { exit_code: EXIT_REQUIRE_CONFIRM, phase, reason, risk, signal: "require_confirmation" };
+}