abelworkflow 0.6.3 → 0.6.5

package/.gitignore

@@ -13,3 +13,4 @@ skills/dev-browser/tmp/
 .codex/
 *pycache*/
 .codex
+openspec/

package/commands/oc/plan.md

@@ -77,7 +77,7 @@ argument-hint: [change_name]
 - Use `openspec list --specs` to check for conflicts with existing specifications.
 - Search existing patterns with `rg -n "INVARIANT:|PROPERTY:|Constraint:" openspec/` before defining new ones.
 - For complex proposals, consider running steps 2-4 iteratively on sub-components.
-- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
+- Ask the user directly for ANY ambiguity—do not assume or guess.
 
 **Exit Criteria**
 A proposal is ready to exit the Plan phase only when:

package/commands/oc/research.md

@@ -26,7 +26,7 @@ Produce constraint sets that narrow the solution space, plus measurable success
 
 ## Phase 0 — Requirement Intake Gate (MANDATORY)
 - **MUST** confirm the user’s requirement exists and is clear **before** any research/action.
-- If missing/unclear, **MUST** use `AskUserQuestions` to collect: goal, in-scope area, top scenarios, non-goals, known constraints, success signals.
+- If missing/unclear, **MUST** ask the user directly in a concise grouped message to collect: goal, in-scope area, top scenarios, non-goals, known constraints, success signals.
 - **MUST NOT** run `/opsx:new`, any codebase retrieval, spawn subagents, or generate artifacts until the user confirms a brief requirement summary.
 
 ---
@@ -97,7 +97,7 @@ All explore subagents MUST return valid JSON using this schema:
 
 ## Phase 7 — User Interaction for Ambiguity Resolution
 - Compile prioritized list of open questions from aggregated reports.
-- Use `AskUserQuestions` tool to present questions systematically:
+- Present questions directly to the user in a concise grouped message:
   * Group related questions together.
   * Provide context for each question.
   * Suggest default answers when applicable.
@@ -122,5 +122,5 @@ All explore subagents MUST return valid JSON using this schema:
   - `openspec status --change <name>` - Check artifact completion status
   - `openspec instructions proposal --change <name>` - Get proposal instructions
 - Validate subagent outputs conform to template before aggregation.
-- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
-<!-- OC:RESEARCH:END -->
+- Ask the user directly for ANY ambiguity—do not assume or guess.
+<!-- OC:RESEARCH:END -->

package/lib/cli/logic.mjs

@@ -0,0 +1,130 @@
+const interactiveMenuDescriptors = [
+  { value: "full-init", label: "完整初始化：同步工作流 + 可选安装/配置 Claude Code、Codex、技能环境" },
+  { value: "install", label: "仅同步/更新工作流到 ~/.agents 并重新链接 Claude/Codex" },
+  { value: "grok-search", label: "配置 grok-search 环境变量" },
+  { value: "context7", label: "配置 context7-auto-research 环境变量" },
+  { value: "prompt-enhancer", label: "配置 prompt-enhancer 环境变量" },
+  { value: "claude-install", label: "安装或更新 Claude Code CLI" },
+  { value: "claude-api", label: "配置 Claude Code 第三方 API" },
+  { value: "codex-install", label: "安装或更新 Codex CLI" },
+  { value: "codex-api", label: "配置 Codex 第三方 API" },
+  { value: "exit", label: "退出" }
+];
+
+const interactiveMenuDefaultValue = "full-init";
+
+function parseArgs(argv, { defaultAgentsDir, resolvePath }) {
+  const options = {
+    agentsDir: defaultAgentsDir,
+    force: false,
+    relinkOnly: false,
+    command: "menu"
+  };
+  const positional = [];
+  let helpRequested = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--force" || arg === "-f") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--link-only") {
+      options.relinkOnly = true;
+      continue;
+    }
+    if (arg === "--agents-dir") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--agents-dir requires a path");
+      }
+      options.agentsDir = resolvePath(value);
+      i += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h" || arg === "help") {
+      helpRequested = true;
+      options.command = "help";
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Unknown argument: ${positional.slice(1).join(" ")}`);
+  }
+
+  if (positional[0]) {
+    if (["menu", "init"].includes(positional[0])) {
+      if (!helpRequested) {
+        options.command = "menu";
+      }
+    } else if (["install", "sync"].includes(positional[0])) {
+      if (!helpRequested) {
+        options.command = "install";
+      }
+    } else {
+      throw new Error(`Unknown command: ${positional[0]}`);
+    }
+  }
+
+  if (options.command !== "install" && (options.force || options.relinkOnly || options.agentsDir !== defaultAgentsDir)) {
+    throw new Error("`--force`、`--link-only`、`--agents-dir` 仅能与 `install` 命令一起使用");
+  }
+
+  return options;
+}
+
+function assertInteractiveMenuSupported({ command, inputIsTTY, outputIsTTY }) {
+  if (command === "menu" && (!inputIsTTY || !outputIsTTY)) {
+    throw new Error("交互式菜单需要 TTY 终端；非交互场景请显式使用 `npx abelworkflow install`");
+  }
+}
+
+function resolvePromptValue(answer, { defaultValue, allowEmpty = false } = {}) {
+  const value = String(answer).trim();
+  if (!value && defaultValue !== undefined) {
+    return { ok: true, value: defaultValue };
+  }
+  if (!value && !allowEmpty) {
+    return { ok: false, error: "此项不能为空。" };
+  }
+  return { ok: true, value };
+}
+
+function resolveSelectValue(answer, choices) {
+  const index = Number(answer) - 1;
+  if (Number.isInteger(index) && index >= 0 && index < choices.length) {
+    return { ok: true, value: choices[index].value };
+  }
+  const direct = choices.find((choice) => choice.value === answer);
+  if (direct) {
+    return { ok: true, value: direct.value };
+  }
+  return { ok: false, error: "无效选择，请重新输入。" };
+}
+
+function shouldUseVisibleSecretFallback({ inputIsTTY, platform }) {
+  return !inputIsTTY || platform === "win32";
+}
+
+function getRunCommandSpawnOptions(platform = process.env.ABELWORKFLOW_TEST_PLATFORM || process.platform) {
+  return {
+    stdio: "inherit",
+    shell: platform === "win32"
+  };
+}
+
+export {
+  assertInteractiveMenuSupported,
+  getRunCommandSpawnOptions,
+  interactiveMenuDefaultValue,
+  interactiveMenuDescriptors,
+  parseArgs,
+  resolvePromptValue,
+  resolveSelectValue,
+  shouldUseVisibleSecretFallback
+};

package/lib/cli.mjs

@@ -5,6 +5,16 @@ import { dirname, join, relative, resolve } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import {
+  assertInteractiveMenuSupported,
+  getRunCommandSpawnOptions,
+  interactiveMenuDefaultValue,
+  interactiveMenuDescriptors,
+  parseArgs,
+  resolvePromptValue,
+  resolveSelectValue,
+  shouldUseVisibleSecretFallback
+} from "./cli/logic.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const packageRoot = dirname(dirname(__filename));
@@ -87,83 +97,6 @@ const ignoredSkillPathPatterns = [
   /^dev-browser\/profiles(\/|$)/,
   /^dev-browser\/tmp(\/|$)/
 ];
-const menuChoices = [
-  { value: "full-init", label: "完整初始化：同步工作流 + 可选安装/配置 Claude Code、Codex、技能环境" },
-  { value: "install", label: "仅同步/更新工作流到 ~/.agents 并重新链接 Claude/Codex" },
-  { value: "grok-search", label: "配置 grok-search 环境变量" },
-  { value: "context7", label: "配置 context7-auto-research 环境变量" },
-  { value: "prompt-enhancer", label: "配置 prompt-enhancer 环境变量" },
-  { value: "claude-install", label: "安装或更新 Claude Code CLI" },
-  { value: "claude-api", label: "配置 Claude Code 第三方 API" },
-  { value: "codex-install", label: "安装或更新 Codex CLI" },
-  { value: "codex-api", label: "配置 Codex 第三方 API" },
-  { value: "exit", label: "退出" }
-];
-
-function parseArgs(argv) {
-  const options = {
-    agentsDir: defaultAgentsDir,
-    force: false,
-    relinkOnly: false,
-    command: "menu"
-  };
-  const positional = [];
-  let helpRequested = false;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === "--force" || arg === "-f") {
-      options.force = true;
-      continue;
-    }
-    if (arg === "--link-only") {
-      options.relinkOnly = true;
-      continue;
-    }
-    if (arg === "--agents-dir") {
-      const value = argv[i + 1];
-      if (!value) {
-        throw new Error("--agents-dir requires a path");
-      }
-      options.agentsDir = resolve(value);
-      i += 1;
-      continue;
-    }
-    if (arg === "--help" || arg === "-h" || arg === "help") {
-      helpRequested = true;
-      options.command = "help";
-      continue;
-    }
-    if (arg.startsWith("-")) {
-      throw new Error(`Unknown argument: ${arg}`);
-    }
-    positional.push(arg);
-  }
-
-  if (positional.length > 1) {
-    throw new Error(`Unknown argument: ${positional.slice(1).join(" ")}`);
-  }
-
-  if (positional[0]) {
-    if (["menu", "init"].includes(positional[0])) {
-      if (!helpRequested) {
-        options.command = "menu";
-      }
-    } else if (["install", "sync"].includes(positional[0])) {
-      if (!helpRequested) {
-        options.command = "install";
-      }
-    } else {
-      throw new Error(`Unknown command: ${positional[0]}`);
-    }
-  }
-
-  if (options.command === "menu" && (options.force || options.relinkOnly || options.agentsDir !== defaultAgentsDir)) {
-    throw new Error("`--force`、`--link-only`、`--agents-dir` 仅能与 `install` 命令一起使用");
-  }
-
-  return options;
-}
 
 function printHelp() {
   console.log(`AbelWorkflow installer
@@ -982,22 +915,18 @@ async function promptText(message, options = {}) {
       rl.close();
     }
 
-    const value = answer.trim();
-    if (!value && defaultValue !== undefined) {
-      return defaultValue;
-    }
-    if (!value && !allowEmpty) {
-      console.log("此项不能为空。");
-      continue;
+    const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
+    if (resolved.ok) {
+      return resolved.value;
     }
-    return value;
+    console.log(resolved.error);
   }
 }
 
 async function promptSecret(message, options = {}) {
   const { defaultValue, allowEmpty = false } = options;
 
-  if (!input.isTTY || isWindows()) {
+  if (shouldUseVisibleSecretFallback({ inputIsTTY: input.isTTY, platform: getPlatform() })) {
     while (true) {
       const suffix = defaultValue !== undefined && defaultValue !== ""
         ? " [直接回车保留现有值]"
@@ -1010,15 +939,11 @@ async function promptSecret(message, options = {}) {
         rl.close();
       }
 
-      const value = answer.trim();
-      if (!value && defaultValue !== undefined) {
-        return defaultValue;
-      }
-      if (!value && !allowEmpty) {
-        console.log("此项不能为空。");
-        continue;
+      const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
+      if (resolved.ok) {
+        return resolved.value;
       }
-      return value;
+      console.log(resolved.error);
     }
   }
 
@@ -1037,15 +962,11 @@ async function promptSecret(message, options = {}) {
       rl.close();
     }
 
-    const value = answer.trim();
-    if (!value && defaultValue !== undefined) {
-      return defaultValue;
+    const resolved = resolvePromptValue(answer, { defaultValue, allowEmpty });
+    if (resolved.ok) {
+      return resolved.value;
     }
-    if (!value && !allowEmpty) {
-      console.log("此项不能为空。");
-      continue;
-    }
-    return value;
+    console.log(resolved.error);
   }
 }
 
@@ -1060,15 +981,11 @@ async function promptSelect(message, choices, options = {}) {
   while (true) {
     const fallbackValue = defaultIndex >= 0 ? String(defaultIndex + 1) : undefined;
     const answer = await promptText("请输入序号", { defaultValue: fallbackValue, allowEmpty: defaultIndex >= 0 });
-    const index = Number(answer) - 1;
-    if (Number.isInteger(index) && index >= 0 && index < choices.length) {
-      return choices[index].value;
+    const resolved = resolveSelectValue(answer, choices);
+    if (resolved.ok) {
+      return resolved.value;
     }
-    const direct = choices.find((choice) => choice.value === answer);
-    if (direct) {
-      return direct.value;
-    }
-    console.log("无效选择，请重新输入。");
+    console.log(resolved.error);
   }
 }
 
@@ -1086,16 +1003,9 @@ function commandExists(command) {
   return result.status === 0;
 }
 
-function getRunCommandSpawnOptions(platform = getPlatform()) {
-  return {
-    stdio: "inherit",
-    shell: platform === "win32"
-  };
-}
-
 async function runCommand(command, args) {
   await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(command, args, getRunCommandSpawnOptions());
+    const child = spawn(command, args, getRunCommandSpawnOptions(getPlatform()));
     child.on("error", rejectPromise);
     child.on("close", (code) => {
       if (code === 0) {
@@ -1871,8 +1781,8 @@ function buildCodexConfigContent(currentContent, {
     content = mergeCodexTemplateDefaults(content, effectiveTemplateContent);
   }
   const lineEnding = detectLineEnding(content);
-  if (includeSubagentDefaults && readTopLevelTomlString(content, "approvals_reviewer") === "guardian_subagent") {
-    content = updateTopLevelTomlField(content, "approvals_reviewer", "reviewer");
+  if (includeSubagentDefaults && readTopLevelTomlString(content, "approvals_reviewer") === "reviewer") {
+    content = updateTopLevelTomlField(content, "approvals_reviewer", "guardian_subagent");
   }
   content = updateTopLevelTomlField(content, "model_provider", providerId);
   content = updateTopLevelTomlField(content, "preferred_auth_method", "apikey");
@@ -1965,57 +1875,39 @@ async function runInteractiveMenu(options) {
   console.log("AbelWorkflow Setup");
   console.log(`工作流目录: ${pathToLabel(options.agentsDir)}`);
 
-  while (true) {
-    const choice = await promptSelect("请选择操作", menuChoices, { defaultValue: "full-init" });
+  const menuChoices = interactiveMenuDescriptors.map(({ value, label }) => ({ value, label }));
+  const menuActions = {
+    "full-init": async () => runFullInit(options),
+    install: async () => installManagedWorkflow({
+      agentsDir: options.agentsDir,
+      force: options.force,
+      relinkOnly: options.relinkOnly
+    }),
+    "grok-search": async () => configureGrokSearchEnv(options.agentsDir),
+    context7: async () => configureContext7Env(options.agentsDir),
+    "prompt-enhancer": async () => configurePromptEnhancerEnv(options.agentsDir),
+    "claude-install": async () => installCliTool("claude"),
+    "claude-api": async () => configureClaudeApi(),
+    "codex-install": async () => installCliTool("codex"),
+    "codex-api": async () => configureCodexApi()
+  };
 
-    if (choice === "exit") {
+  while (true) {
+    const choice = await promptSelect("请选择操作", menuChoices, { defaultValue: interactiveMenuDefaultValue });
+    const descriptor = interactiveMenuDescriptors.find((item) => item.value === choice);
+    if (descriptor?.value === "exit") {
       return;
     }
 
-    if (choice === "full-init") {
-      await runFullInit(options);
-      continue;
-    }
-    if (choice === "install") {
-      await installManagedWorkflow({
-        agentsDir: options.agentsDir,
-        force: options.force,
-        relinkOnly: options.relinkOnly
-      });
-      continue;
-    }
-    if (choice === "grok-search") {
-      await configureGrokSearchEnv(options.agentsDir);
-      continue;
-    }
-    if (choice === "context7") {
-      await configureContext7Env(options.agentsDir);
-      continue;
-    }
-    if (choice === "prompt-enhancer") {
-      await configurePromptEnhancerEnv(options.agentsDir);
-      continue;
-    }
-    if (choice === "claude-install") {
-      await installCliTool("claude");
-      continue;
-    }
-    if (choice === "claude-api") {
-      await configureClaudeApi();
-      continue;
-    }
-    if (choice === "codex-install") {
-      await installCliTool("codex");
-      continue;
-    }
-    if (choice === "codex-api") {
-      await configureCodexApi();
-    }
+    await menuActions[descriptor.value]();
   }
 }
 
 async function main() {
-  const options = parseArgs(process.argv.slice(2));
+  const options = parseArgs(process.argv.slice(2), {
+    defaultAgentsDir,
+    resolvePath: resolve
+  });
 
   if (options.command === "help") {
     printHelp();
@@ -2027,9 +1919,11 @@ async function main() {
     return;
   }
 
-  if (!input.isTTY || !output.isTTY) {
-    throw new Error("交互式菜单需要 TTY 终端；非交互场景请显式使用 `npx abelworkflow install`");
-  }
+  assertInteractiveMenuSupported({
+    command: options.command,
+    inputIsTTY: input.isTTY,
+    outputIsTTY: output.isTTY
+  });
 
   await runInteractiveMenu(options);
 }
@@ -2043,12 +1937,3 @@ export {
   resolveExistingCodexApiConfig,
   updateTomlSectionFields
 };
-
-const isDirectExecution = process.argv[1] ? resolve(process.argv[1]) === __filename : false;
-
-if (isDirectExecution) {
-  main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  });
-}

package/lib/templates/codex/config-base.toml

@@ -2,7 +2,7 @@ personality = "pragmatic"
 model_provider = "abelworkflow"
 disable_response_storage = true
 preferred_auth_method = "apikey"
-approvals_reviewer = "reviewer"
+approvals_reviewer = "guardian_subagent"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 service_tier = "fast"

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "abelworkflow",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
   "type": "module",
+  "scripts": {
+    "test:contracts": "node --test test/runtime-doc-contracts.test.mjs test/cli-contracts.test.mjs"
+  },
   "bin": {
     "abelworkflow": "bin/abelworkflow.mjs"
   },