@xulthekl/team-flow 0.22.4

package/scripts/lib/cmd-install-workbuddy.mjs

@@ -0,0 +1,359 @@
+// tf install-workbuddy — deploy team-flow as a WorkBuddy marketplace plugin.
+//
+// WorkBuddy's marketplace plugin model (verified from existing plugins like
+// `finance` and `modern-webapp` in cb_teams_marketplace):
+//
+//   ~/.workbuddy/plugins/marketplaces/<marketplace>/plugins/<plugin-name>/
+//   ├── .codebuddy-plugin/plugin.json   ← manifest (name, version, skills[])
+//   ├── skills/<skill-name>/SKILL.md    ← skills with ${CLAUDE_PLUGIN_ROOT} rewritten
+//   ├── rules/phase-guard.md            ← phase-guard rule (auto-included)
+//   ├── scripts/  docs/  templates/     ← runtime deps (${CLAUDE_PLUGIN_ROOT})
+//   ├── dist/  hooks/                   ← (continued)
+//
+// enabledPlugins key in ~/.workbuddy/settings.json: `<plugin-name>@<marketplace>`
+//
+// This installer mirrors the shared install.mjs logic (RUNTIME_DIRS copy,
+// ${CLAUDE_PLUGIN_ROOT} rewrite, phase-guard rule) but targets the marketplace
+// plugin structure instead of a project-local `.platform/` directory.
+
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cp, writeFile, mkdtemp } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { shellQuote } from './shell-quote.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultPluginRoot = resolve(__dirname, '..', '..'); // repo root when run from clone
+
+const DEFAULT_MARKETPLACE = 'cb_teams_marketplace';
+const PLUGIN_NAME = 'team-flow';
+const GITHUB_REPO = 'MageByte-Zero/team-flow';
+const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+const RUNTIME_DIRS = ['scripts', 'docs', 'templates', 'dist', 'hooks'];
+
+// ─── helpers ──────────────────────────────────────────────
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function readJsonIfExists(filePath) {
+  if (!existsSync(filePath)) return {};
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+function listSkillNames(skillsDir) {
+  if (!existsSync(skillsDir)) {
+    throw new Error(`skills/ directory not found at ${skillsDir}`);
+  }
+  return readdirSync(skillsDir)
+    .filter(name => {
+      const dir = join(skillsDir, name);
+      return statSync(dir).isDirectory() && existsSync(join(dir, 'SKILL.md'));
+    })
+    .sort();
+}
+
+/** Recursively copy a directory. */
+async function copyDir(src, dst) {
+  if (!existsSync(src)) return 0;
+  ensureDir(dst);
+  const entries = readdirSync(src);
+  for (const name of entries) {
+    const srcPath = join(src, name);
+    const dstPath = join(dst, name);
+    const st = statSync(srcPath);
+    if (st.isDirectory()) {
+      await copyDir(srcPath, dstPath);
+    } else {
+      await cp(srcPath, dstPath, { force: true });
+    }
+  }
+  return entries.length;
+}
+
+/**
+ * Copy skills to <pluginRoot>/skills/, replacing ${CLAUDE_PLUGIN_ROOT}
+ * with the absolute plugin root path so skill instructions resolve.
+ */
+async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
+  // Clean old skill directories.
+  if (existsSync(targetSkills)) {
+    for (const name of readdirSync(targetSkills)) {
+      rmSync(join(targetSkills, name), { recursive: true, force: true });
+    }
+  }
+  ensureDir(targetSkills);
+  const entries = readdirSync(sourceSkills).filter(name => {
+    try { return statSync(join(sourceSkills, name)).isDirectory(); } catch { return false; }
+  });
+
+  function rewriteRoot(filePath) {
+    if (!existsSync(filePath)) return;
+    let content = readFileSync(filePath, 'utf-8');
+    if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
+      content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
+    }
+    content = content.replace(
+      /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
+      `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+    );
+    writeFileSync(filePath, content, 'utf-8');
+  }
+
+  for (const name of entries) {
+    const src = join(sourceSkills, name);
+    const dst = join(targetSkills, name);
+    await cp(src, dst, { recursive: true, force: true });
+    rewriteRoot(join(dst, 'SKILL.md'));
+    // Also fix sub-prompt / reference markdown files in the skill dir.
+    for (const sub of readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md')) {
+      rewriteRoot(join(dst, sub));
+    }
+  }
+  return entries.length;
+}
+
+/** Phase-guard rule content for WorkBuddy (md format). */
+function phaseGuardContent() {
+  return `# Phase Guard — team-flow (workbuddy)
+
+## 入口规则
+
+- 所有工作必须从 "/workflow-start" 入口开始。
+- 在 .team-flow.yaml 中确认当前 state 和 workflow 模式之前，不要开始写代码。
+
+## 全局禁止
+
+- 没有 execution-contract.md 或未经用户明确批准，不得进入实现。
+- full/hotfix 必须先运行 tf execution plan <change-dir> ...；没有 current execution plan 不得开始实现。
+- 只有 all pass review receipts 后才可 closing；不得把未审查的 wave 当作完成。
+- 上述 plan/receipt gates 仅适用于 full/hotfix；tweak 免除这些 gates (tweak exempt)。
+- 执行过程中如果发现需求/范围变化，必须回退到 specifying 或 bridging，而不是直接改代码。
+- 不要直接调用执行类 skill（如 "/build-executor"），必须通过入口路由。
+
+## 决策点协议
+
+- DP-0：设计前确认
+- DP-1：需求确认
+- DP-2：工件审查
+- DP-3：是否批准 execution contract？
+- DP-4：先运行 tf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
+- DP-5：调试升级
+- DP-6：验证失败
+- DP-7：是否收口归档？
+
+> 本文件由 team-flow 安装脚本生成（platform: workbuddy）；
+> 对具体变更的 guard 内容请运行 \`tf inject <change-dir>\` 更新。
+`;
+}
+
+/** Plugin manifest for the marketplace. */
+function pluginManifest(skillNames, version) {
+  return {
+    name: PLUGIN_NAME,
+    version: version || '0.0.0',
+    description: 'Spec-Superflow — OpenSpec 规划引擎 + Superpowers 执行纪律的任务工作流。',
+    author: { name: 'MageByte-Zero' },
+    homepage: { url: `https://github.com/${GITHUB_REPO}`, type: 'github' },
+    license: 'MIT',
+    skills: skillNames.map(name => `./skills/${name}`),
+  };
+}
+
+// ─── release fetch / clone ────────────────────────────────
+
+async function fetchLatestTag() {
+  const res = await fetch(GITHUB_API_URL);
+  if (!res.ok) throw new Error(`GitHub API failed: ${res.status} ${res.statusText}`);
+  const data = await res.json();
+  if (!data.tag_name) throw new Error('GitHub API response missing tag_name');
+  return data.tag_name;
+}
+
+async function cloneRelease(tag) {
+  const tmpDir = await mkdtemp(join('/tmp', 'team-flow-'));
+  const url = `https://github.com/${GITHUB_REPO}.git`;
+  console.log(`📥 Cloning ${tag} into ${tmpDir} ...`);
+  execFileSync('git', ['clone', '--depth', '1', '--branch', tag, url, tmpDir], {
+    stdio: 'inherit',
+  });
+  return tmpDir;
+}
+
+function readVersion(pluginRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// ─── plan ─────────────────────────────────────────────────
+
+function planInstall({ pluginRoot = defaultPluginRoot, homeDir = homedir(), marketplaceName = DEFAULT_MARKETPLACE } = {}) {
+  const root = resolve(pluginRoot);
+  const skillsDir = join(root, 'skills');
+  const skillNames = listSkillNames(skillsDir);
+  const workbuddyRoot = join(homeDir, '.workbuddy');
+  const pluginsDir = join(workbuddyRoot, 'plugins', 'marketplaces', marketplaceName, 'plugins');
+  const targetPluginDir = join(pluginsDir, PLUGIN_NAME);
+  const targetSkills = join(targetPluginDir, 'skills');
+  const targetRules = join(targetPluginDir, 'rules');
+  const manifestDir = join(targetPluginDir, '.codebuddy-plugin');
+  const settingsPath = join(workbuddyRoot, 'settings.json');
+  const enabledPluginKey = `${PLUGIN_NAME}@${marketplaceName}`;
+  const version = readVersion(root);
+  const pluginRootAbs = resolve(targetPluginDir);
+
+  return {
+    pluginRoot: root,
+    skillsDir,
+    skillNames,
+    workbuddyRoot,
+    pluginsDir,
+    targetPluginDir,
+    targetSkills,
+    targetRules,
+    manifestDir,
+    settingsPath,
+    marketplaceName,
+    enabledPluginKey,
+    version,
+    pluginRootAbs,
+  };
+}
+
+// ─── install ──────────────────────────────────────────────
+
+async function installWorkBuddy({ pluginRoot, homeDir, marketplaceName }) {
+  const plan = planInstall({ pluginRoot, homeDir, marketplaceName });
+  const { skillNames, targetPluginDir, targetSkills, targetRules, manifestDir, settingsPath, enabledPluginKey, version, pluginRootAbs } = plan;
+
+  // 0. Clean old plugin dir.
+  if (existsSync(targetPluginDir)) {
+    rmSync(targetPluginDir, { recursive: true, force: true });
+  }
+  ensureDir(targetPluginDir);
+
+  // 1. Copy runtime dependencies (scripts/docs/templates/dist/hooks).
+  console.log('📋 Copying runtime dependencies...');
+  for (const dir of RUNTIME_DIRS) {
+    const src = join(plan.pluginRoot, dir);
+    const dst = join(targetPluginDir, dir);
+    if (existsSync(src)) {
+      const count = await copyDir(src, dst);
+      console.log(`   ${dir}/ → ${dst} (${count} entries)`);
+    } else {
+      console.log(`   ${dir}/ — skipped (not found)`);
+    }
+  }
+
+  // 2. Copy skills with ${CLAUDE_PLUGIN_ROOT} rewriting.
+  const count = await copySkillsWithRoot(plan.skillsDir, targetSkills, pluginRootAbs);
+  console.log(`   skills/ → ${targetSkills} (${count} skills, paths rewritten)`);
+
+  // 3. Write phase-guard rule.
+  ensureDir(targetRules);
+  await writeFile(join(targetRules, 'phase-guard.md'), phaseGuardContent(), 'utf-8');
+  console.log(`   phase-guard → ${join(targetRules, 'phase-guard.md')}`);
+
+  // 4. Write plugin manifest.
+  ensureDir(manifestDir);
+  await writeFile(join(manifestDir, 'plugin.json'), JSON.stringify(pluginManifest(skillNames, version), null, 2) + '\n', 'utf-8');
+  console.log(`   manifest → ${join(manifestDir, 'plugin.json')}`);
+
+  // 5. Enable plugin in settings.json.
+  ensureDir(plan.workbuddyRoot);
+  const settings = readJsonIfExists(settingsPath);
+  settings.enabledPlugins = settings.enabledPlugins && typeof settings.enabledPlugins === 'object'
+    ? settings.enabledPlugins
+    : {};
+  // Remove old per-skill keys (migration from v0.8.13 and earlier).
+  for (const name of skillNames) {
+    delete settings.enabledPlugins[`${name}@${marketplaceName}`];
+  }
+  settings.enabledPlugins[enabledPluginKey] = true;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`   settings → ${enabledPluginKey} enabled`);
+
+  return plan;
+}
+
+// ─── CLI entry ────────────────────────────────────────────
+
+export async function run(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      local: { type: 'string' },
+      home: { type: 'string' },
+      marketplace: { type: 'string' },
+      tag: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+    },
+  });
+
+  const marketplaceName = values.marketplace || DEFAULT_MARKETPLACE;
+
+  // Dry-run: show plan and exit.
+  if (values['dry-run']) {
+    const plan = planInstall({
+      pluginRoot: values.local || defaultPluginRoot,
+      homeDir: values.home || homedir(),
+      marketplaceName,
+    });
+    console.log('WorkBuddy install plan:');
+    console.log(`  Plugin:      ${PLUGIN_NAME} v${plan.version}`);
+    console.log(`  Skills:      ${plan.skillNames.length} (${plan.skillNames.join(', ')})`);
+    console.log(`  Marketplace: ${plan.marketplaceName}`);
+    console.log(`  Target:      ${plan.targetPluginDir}`);
+    console.log(`  Rules:       ${plan.targetRules}/phase-guard.md`);
+    console.log(`  Settings:    ${plan.enabledPluginKey}`);
+    return;
+  }
+
+  // Resolve source: --local <path> | --tag <tag> | latest release.
+  let pluginRoot = defaultPluginRoot;
+  let isTemp = false;
+  let installedTag = null;
+
+  if (values.local) {
+    pluginRoot = resolve(values.local);
+    console.log(`📁 Using local repo: ${pluginRoot}`);
+  } else {
+    installedTag = values.tag || await fetchLatestTag();
+    console.log(`⬆️  Installing team-flow ${installedTag} for WorkBuddy ...`);
+    pluginRoot = await cloneRelease(installedTag);
+    isTemp = true;
+  }
+
+  try {
+    const plan = await installWorkBuddy({
+      pluginRoot,
+      homeDir: values.home || homedir(),
+      marketplaceName,
+    });
+
+    console.log(`\n✅ WorkBuddy install complete:`);
+    console.log(`   Plugin:      ${PLUGIN_NAME} v${plan.version}`);
+    console.log(`   Skills:      ${plan.skillNames.length}`);
+    console.log(`   Marketplace: ${plan.marketplaceName}`);
+    console.log(`   Target:      ${plan.targetPluginDir}`);
+    console.log(`   Rules:       ${plan.targetRules}/phase-guard.md`);
+    if (installedTag) {
+      console.log(`   Version:     ${installedTag}`);
+    }
+    console.log(`\nNext: restart WorkBuddy and try "用 workflow-start 开始".`);
+  } finally {
+    if (isTemp) {
+      rmSync(pluginRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+export { planInstall, installWorkBuddy, PLUGIN_NAME };

package/scripts/lib/cmd-install-zcode.mjs

@@ -0,0 +1,14 @@
+// tf install-zcode — deploy team-flow skills/rules/scripts for ZCODE
+// Delegates to scripts/install-zcode.mjs
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const installScript = join(__dirname, '..', 'install-zcode.mjs');
+
+export async function run(args) {
+  execFileSync(process.execPath, [installScript, ...args], {
+    stdio: 'inherit',
+  });
+}

package/scripts/lib/cmd-isolate.mjs

@@ -0,0 +1,37 @@
+// scripts/lib/cmd-isolate.mjs — `tf isolate` CLI wrapper around ensure-branch.mjs
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ENSURE = join(__dirname, '..', 'ensure-branch.mjs');
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: { force: { type: 'boolean', default: false } },
+  });
+  const changeDir = positionals[0];
+  const changeName = positionals[1];
+  if (!changeDir) {
+    console.error('Usage: tf isolate <change-dir> [change-name] [--force]');
+    process.exit(2);
+  }
+  const extra = values.force ? ['--force'] : [];
+  // Literal command ('node') + literal argument array, no shell — same safe form
+  // as cmd-install-*.mjs. execFileSync throws on non-zero exit; propagate its status.
+  const nodeArgs = [ENSURE, changeDir];
+  if (changeName !== undefined) nodeArgs.push(changeName);
+  for (const a of extra) nodeArgs.push(a);
+  try {
+    execFileSync('node', nodeArgs, {
+      stdio: 'inherit',
+      timeout: 15000,
+    });
+    process.exit(0);
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+}

package/scripts/lib/cmd-list.mjs

@@ -0,0 +1,71 @@
+// tf list — scan changes/ and report status
+import { readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from './config-loader.mjs';
+import { readState } from './state-loader.mjs';
+
+function detectChangeStatus(changeDir) {
+  // Prefer the state file over file-existence heuristics.
+  // The state file is maintained by tf state transition and is the
+  // authoritative source for the current workflow phase.
+  const stateFile = join(changeDir, '.team-flow.yaml');
+  if (existsSync(stateFile)) {
+    const state = readState(changeDir);
+    const st = state.state || 'exploring';
+    const workflow = state.workflow || 'full';
+    const detail = workflow === 'full' ? '' : ` (${workflow})`;
+    const STATUS_MAP = {
+      exploring: 'EXPLORING',
+      specifying: 'SPECIFYING',
+      bridging: 'BRIDGED',
+      'approved-for-build': 'APPROVED',
+      executing: 'EXECUTING',
+      debugging: 'DEBUGGING',
+      closing: 'CLOSED',
+      abandoned: 'ABANDONED',
+    };
+    return {
+      status: STATUS_MAP[st] || 'UNKNOWN',
+      detail: `${st}${detail}`,
+    };
+  }
+
+  // Fallback: infer from file existence when no state file exists
+  const hasProposal = existsSync(join(changeDir, 'proposal.md'));
+  const hasContract = existsSync(join(changeDir, 'execution-contract.md'));
+  const hasAbandonment = existsSync(join(changeDir, 'abandonment-summary.md'));
+
+  if (hasAbandonment) return { status: 'ABANDONED', detail: 'Change was abandoned' };
+  if (!hasProposal) return { status: 'INCOMPLETE', detail: 'Missing proposal.md' };
+  if (!hasContract) return { status: 'SPECIFYING', detail: 'Planning in progress (no state file)' };
+  return { status: 'UNKNOWN', detail: 'Has artifacts but no state file — run tf state init' };
+}
+
+export { detectChangeStatus };
+
+export async function run(args) {
+  const config = loadConfig(process.cwd());
+  const changesDir = join(process.cwd(), 'changes');
+
+  if (!existsSync(changesDir)) {
+    console.log('No changes/ directory found.');
+    return;
+  }
+
+  const dirs = readdirSync(changesDir).filter(f => {
+    try { return statSync(join(changesDir, f)).isDirectory(); } catch { return false; }
+  });
+
+  if (dirs.length === 0) {
+    console.log('No changes found in changes/');
+    return;
+  }
+
+  console.log('Changes:');
+  for (const dir of dirs) {
+    const changeDir = join(changesDir, dir);
+    const { status, detail } = detectChangeStatus(changeDir);
+    const icon = status === 'CLOSED' ? '✅' : status === 'ABANDONED' ? '🚫' : status === 'APPROVED' ? '🔒' : status === 'EXECUTING' ? '⚡' : status === 'DEBUGGING' ? '🐛' : status === 'EXPLORING' ? '🔍' : status === 'SPECIFYING' ? '📝' : status === 'BRIDGED' ? '🌉' : status === 'UNKNOWN' ? '❓' : '⚠️';
+    console.log(`  ${icon} ${dir}  [${status}]  ${detail}`);
+  }
+}

package/scripts/lib/cmd-runtime.mjs

@@ -0,0 +1,85 @@
+// tf runtime — portable, root-independent operations used by canonical skills.
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const ASSETS = new Set([
+  'docs/artifact-contract.md',
+  'docs/decision-points.md',
+  'docs/state-machine.md',
+  'skills/build-executor/implementer-prompt.md',
+  'skills/build-executor/task-reviewer-prompt.md',
+  'templates/design.md',
+  'templates/execution-contract.md',
+  'templates/proposal.md',
+  'templates/spec.md',
+  'templates/tasks.md',
+]);
+
+export async function run(args) {
+  const [operation, ...rest] = args;
+
+  switch (operation) {
+    case 'check-update':
+      return runScript('scripts/check-update.mjs', rest);
+    case 'infer':
+      return runScript('scripts/infer-workflow.mjs', rest);
+    case 'guard':
+      return runScript('scripts/guard/guard.mjs', rest);
+    case 'config':
+      return runReadOnlyConfig(rest);
+    case 'asset':
+      return readAsset(rest);
+    default:
+      return usage(`Unknown runtime operation: ${operation || '(missing)'}`);
+  }
+}
+
+function runScript(relativeScript, args) {
+  const result = spawnSync(process.execPath, [join(ROOT, relativeScript), ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: 'inherit',
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exitCode = result.status ?? 1;
+}
+
+async function runReadOnlyConfig(args) {
+  if (args.includes('--set')) {
+    return usage('runtime config is read-only; use the main tf config command to change configuration');
+  }
+  const { run: runConfig } = await import('./cmd-config.mjs');
+  await runConfig(args);
+}
+
+function readAsset(args) {
+  if (args[0] !== 'read' || args.length !== 2) {
+    return usage('Usage: tf runtime asset read <allowed-relative-path>');
+  }
+
+  const assetPath = args[1];
+  if (!ASSETS.has(assetPath)) {
+    return usage(`Asset is not in the runtime allowlist: ${assetPath}`);
+  }
+
+  process.stdout.write(readFileSync(join(ROOT, assetPath), 'utf8'));
+}
+
+function usage(message) {
+  console.error(message);
+  console.error(`Usage:
+  tf runtime check-update
+  tf runtime infer <change-dir>
+  tf runtime guard check <change-dir> <from-state> <to-state> [--json]
+  tf runtime config [--get <path>|--resolve-model <profile>]
+  tf runtime asset read <allowed-relative-path>`);
+  process.exitCode = 2;
+}
+
+export { ASSETS };

package/scripts/lib/cmd-solutions.mjs

@@ -0,0 +1,71 @@
+// scripts/lib/cmd-solutions.mjs - tf solutions 复利贯穿机制命令组（v0.5）
+//
+// 设计说明（v0.5 / 2026-07-21）：
+// - 与 checkpoint / handoff / execution 一致，采用「单 COMMANDS key + 内部子命令分发」模式。
+// - 4 个底层脚本 solutions-{index-gen,inject,capture,promote}.mjs 的 run(args) 接收「对象」参数，
+//   而 CLI 入口传入的是「字符串数组」。本分发器用 parseArgs 把数组解析成各脚本需要的对象后再调用，
+//   完成 数组 → 对象 的桥接。
+import { parseArgs } from 'node:util';
+
+const USAGE = 'Usage: tf solutions <index-gen|inject|capture|promote> [options]';
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      dir: { type: 'string' },
+      phase: { type: 'string' },
+      domain: { type: 'string' },
+      type: { type: 'string' },
+      severity: { type: 'string' },
+      summary: { type: 'string' },
+      source: { type: 'string' },
+    },
+  });
+
+  const subcommand = positionals[0];
+  if (!subcommand) usage();
+
+  if (subcommand === 'index-gen') {
+    const mod = await import('./solutions-index-gen.mjs');
+    mod.run({ dir: values.dir });
+    return;
+  }
+
+  if (subcommand === 'inject') {
+    const mod = await import('./solutions-inject.mjs');
+    mod.run({ phase: values.phase, domain: values.domain, dir: values.dir });
+    return;
+  }
+
+  if (subcommand === 'capture') {
+    const mod = await import('./solutions-capture.mjs');
+    mod.run({
+      phase: values.phase,
+      domain: values.domain,
+      type: values.type,
+      severity: values.severity,
+      summary: values.summary,
+      source: values.source,
+      dir: values.dir,
+    });
+    return;
+  }
+
+  if (subcommand === 'promote') {
+    const changeDir = positionals[1];
+    if (!changeDir) usage('Usage: tf solutions promote <change-dir> [--dir <solutions-dir>]');
+    const mod = await import('./solutions-promote.mjs');
+    mod.run({ _: [changeDir], changeDir, dir: values.dir });
+    return;
+  }
+
+  console.error(`Unknown solutions subcommand: ${subcommand}. Valid: index-gen, inject, capture, promote`);
+  process.exit(2);
+}
+
+function usage(message = USAGE) {
+  console.error(message);
+  process.exit(2);
+}