@xulthekl/team-flow 0.44.0 → 0.45.0

package/scripts/lib/glaf4-delegation.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+/**
+ * glaf4-delegation — GLAF4 委托协议 CLI（v2.1 §6.6/§6.3/§6.7，P2 实施委托全链路）
+ *
+ * 用法：
+ *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--json]
+ *       运行时探测（v2.1 §4 接口①，C1 修复接线）：三态检测 + 写 .team-flow/team-flow.config.json 的 glaf4_dev 段。
+ *       contract-builder 产出 execution-contract 时（DP-4 前）显式调用此命令，recommend 才能读到 glaf4_dev。
+ *   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json> [--json]
+ *       DP-4 委托方案确认：mode 枚举标量入 state，write_set_boundary 落 .superpowers/glaf4/write-set.json，
+ *       state 只存引用 hash（writeState 硬编码字段列表 + parseYaml 仅标量，文件清单数组无法往返）。
+ *   tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir> [--target-root <root>] [--json]
+ *       write-set 对账（门禁级 FAIL，阻断 closing）：glaf4-dev 实际写入 ⊆ change 边界 + 允许集。
+ *   tf glaf4-delegation verify-tasks <change-dir> [--json]
+ *       task 完成度对账（审计输出 WARN）：tasks.md targets 注解 vs delegation_status。
+ *   tf glaf4-delegation record-partial <change-dir> --run-dir <run-dir> [--json]
+ *       6.7 partial writes 落盘清单：BLOCKED 时扫 run 实际写入写 delegation_partial_writes（人工核对从扫盘降为确认清单）。
+ *   tf glaf4-delegation reset <change-dir> [--json]
+ *       6.7 官方降级：删 plan 重走 DP-4（删除 .superpowers/sdd/execution-plan.json + 清理 execution_plan_hash + dp_4/delegation 字段）。
+ *
+ * 允许集（v2.1 §6.3 write-set 对账）：pom.xml/build.gradle、src/test/java/**、src/test/resources/**、
+ * .glaf4-dev/runs/**、test-environment.json。这是唯一约束 change 边界的机械机制。
+ */
+
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
+import { readState, writeState } from './state-loader.mjs';
+import { getOverlayPaths } from './sdd-overlay.mjs';
+import { detectGlaf4Delegation, writeGlaf4DevConfig } from './conventions-generator.mjs';
+
+// DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
+export const GLAF4_DELEGATION_MODES = [
+  'FEATURE_TDD',
+  'BUGFIX_REGRESSION',
+  'REFACTOR_PROTECTED',
+  'COMPLETE_UNIT_TESTS',
+  'COMPLETE_INTEGRATION_TESTS',
+  'TEST_BOOTSTRAP',
+];
+
+// write-set 对账允许集（v2.1 §6.3）——change 边界之外、允许 glaf4-dev 写入的附加区域
+const WRITE_SET_ALLOWED = [
+  'pom.xml',
+  'build.gradle',
+  'build.gradle.kts',
+  'src/test/java',
+  'src/test/resources',
+  '.glaf4-dev/runs',
+  'test-environment.json',
+];
+
+/**
+ * write-set.json 的固定落盘路径（.superpowers/glaf4/write-set.json）
+ */
+function writeSetPath(changeDir) {
+  return join(changeDir, '.superpowers', 'glaf4', 'write-set.json');
+}
+
+/**
+ * 计算 write-set 引用 hash（state 只存 hash，文件清单不落 YAML）
+ */
+export function hashWriteSet(writeSet) {
+  const stable = JSON.stringify(writeSet, null, 2);
+  return `sha256:${createHash('sha256').update(stable).digest('hex')}`;
+}
+
+/**
+ * 运行时探测并写 config（v2.1 §4 接口①，C1 修复接线）
+ * @param {string} root 工程根目录
+ * @param {string} [delegationMode] 覆盖 delegation_mode（auto/manual/off）
+ * @returns {object} { ok, is_glaf4_java, glaf4_dev_available, glaf4_dev_version, delegation_mode, configPath }
+ */
+export function detectAndWriteConfig(root, delegationMode) {
+  const detection = detectGlaf4Delegation(root, { delegationMode });
+
+  // 复评 C1 嵌套工程根盲区（2026-08-18）：git root ≠ target_root（monorepo 布局）时，
+  // loadConfig(changeDir) 只查 changeDir→git root→home，不查 target_root → 委托链静默断裂。
+  // 写 git root 冗余副本保证从任意 changeDir 都能读到探测结果。gitRoot 提前解析供 mode 优先级使用。
+  let gitRoot = null;
+  try {
+    gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    // 非 git 仓库，跳过
+  }
+
+  // 第四轮复评 Important（2026-08-18）：delegation_mode 优先级链补全——显式 > 目标 root 已有 > git root 已有 > auto。
+  // 上轮只查目标 root，非 Java 服务无本地 config → 默认 auto → 覆盖 git root 副本的 off（用户 off 意图被静默翻转）。
+  let effectiveMode = delegationMode;
+  if (!effectiveMode) {
+    effectiveMode = readGlaf4DelegationMode(root)
+      || (gitRoot ? readGlaf4DelegationMode(gitRoot) : null)
+      || 'auto';
+  }
+  const info = {
+    enabled: detection.is_glaf4_java && detection.glaf4_dev_available,
+    version: detection.glaf4_dev_version,
+    delegationMode: effectiveMode,
+  };
+  writeGlaf4DevConfig(root, info);
+
+  let gitRootConfig = null;
+  if (gitRoot && gitRoot !== root) {
+    // 第三轮复评 Important①（2026-08-18）：多服务混合 monorepo 下 git root 副本 last-write-wins 污染——
+    // 非 Java 服务 detect 会把 Java 服务的 enabled=true 覆盖成 false。改为 OR 聚合：
+    // 项目级能力一旦声明（任一服务 enabled=true），不因后续非 Java 服务探测而丢失。
+    const existingEnabled = readGitRootGlaf4Enabled(gitRoot);
+    const aggregatedEnabled = info.enabled || existingEnabled;
+    // 第四轮复评：git root 副本 mode 保留已有值（显式传参才覆盖）——用户 off 意图不因新探测静默翻转。
+    const gitRootMode = readGlaf4DelegationMode(gitRoot);
+    const gitRootEffectiveMode = delegationMode || gitRootMode || effectiveMode;
+    writeGlaf4DevConfig(gitRoot, { ...info, enabled: aggregatedEnabled, delegationMode: gitRootEffectiveMode });
+    gitRootConfig = join(gitRoot, '.team-flow', 'team-flow.config.json');
+  }
+
+  return {
+    ok: true,
+    ...detection,
+    configPath: join(root, '.team-flow', 'team-flow.config.json'),
+    gitRootConfig,
+  };
+}
+
+/**
+ * 读 git root 现有 config 的 glaf4_dev.enabled（第三轮复评 Important① OR 聚合用）
+ * @param {string} gitRoot
+ * @returns {boolean}
+ */
+function readGitRootGlaf4Enabled(gitRoot) {
+  const cfgPath = join(gitRoot, '.team-flow', 'team-flow.config.json');
+  if (!existsSync(cfgPath)) return false;
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+    return cfg?.glaf4_dev?.enabled === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 读目标 root 现有 config 的 glaf4_dev.delegation_mode（第三轮复评 Minor：保留已有值）
+ * @param {string} root
+ * @returns {string|null}
+ */
+function readGlaf4DelegationMode(root) {
+  const cfgPath = join(root, '.team-flow', 'team-flow.config.json');
+  if (!existsSync(cfgPath)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+    const mode = cfg?.glaf4_dev?.delegation_mode;
+    return typeof mode === 'string' ? mode : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析 execution-contract.md `## GLAF4 Delegation` 段的 write_set_boundary 列表（v2.1 §6.2 权威源）
+ * @param {string} changeDir
+ * @returns {string[]|null} 契约段声明的边界文件清单（无段/无 write_set_boundary 时 null）
+ */
+export function readContractWriteSetBoundary(changeDir) {
+  const contractPath = join(changeDir, 'execution-contract.md');
+  if (!existsSync(contractPath)) return null;
+  const content = readFileSync(contractPath, 'utf-8');
+  // 复评 I1 表头盲区（2026-08-18）：模板表头为 `## GLAF4 Delegation（v2.1 §6.1/§6.2，…）`（带全角括号后缀）。
+  // 第四轮 Minor-2（2026-08-18）：精确表头锚定——表头仅允许裸 `GLAF4 Delegation` 或带全角/半角括号注释，
+  // 排除 `## GLAF4 Delegation Notes` 这类前缀标题劫持（Notes 非括号注释 → 不匹配）。
+  const headerRe = /##\s*GLAF4 Delegation(?:\s*[（(][^）)\n]*[）)])?\s*\n/;
+  const sections = [...content.matchAll(new RegExp(headerRe.source + '([\\s\\S]*?)(?=\\n##\\s|\\n#\\s|$)', 'g'))];
+  for (const section of sections) {
+    const boundaryMatch = section[1].match(/- write_set_boundary:\s*\n((?:[ \t]+- .+\n?)+)/);
+    if (boundaryMatch) {
+      return boundaryMatch[1].split('\n')
+        .map(l => l.trim().replace(/^- /, ''))
+        .filter(Boolean);
+    }
+  }
+  return null;
+}
+
+/**
+ * DP-4 委托方案确认
+ * @param {string} changeDir change 目录
+ * @param {object} input { mode, writeSet }
+ * @returns {object} { ok, dp_4_glaf4_mode, dp_4_write_set_hash, writeSetPath, contractBoundaryMismatch, preModeWarning }
+ */
+export function confirmDelegation(changeDir, { mode, writeSet }) {
+  if (!GLAF4_DELEGATION_MODES.includes(mode)) {
+    throw new Error(`--mode 必须为 GLAF4_DELEGATION_MODES 之一: ${GLAF4_DELEGATION_MODES.join(', ')}`);
+  }
+  if (!writeSet || !Array.isArray(writeSet.files) || writeSet.files.length === 0) {
+    throw new Error('--write-set 必须为 { files: string[] }，files 为 change 边界文件清单');
+  }
+
+  // L2（2026-08-18）：前置校验——确认前应已选 glaf4-delegation 执行模式（tf execution plan）
+  const state = readState(changeDir);
+  let preModeWarning = null;
+  if (state.execution_mode !== 'glaf4-delegation') {
+    preModeWarning = `state.execution_mode=${state.execution_mode || 'null'}，非 glaf4-delegation——请先执行 `
+      + '`tf execution plan --mode glaf4-delegation --confirm` 选定委托模式（v2.1 §6.6）';
+  }
+
+  const path = writeSetPath(changeDir);
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(writeSet, null, 2), 'utf-8');
+
+  // I1（2026-08-18）：契约段 write_set_boundary vs JSON diff，不一致 WARN（JSON 为机械权威，契约段为展示层）
+  const contractBoundary = readContractWriteSetBoundary(changeDir);
+  const contractBoundaryMismatch = [];
+  if (contractBoundary) {
+    const jsonFiles = (writeSet.files || []).map(f => normalize(f).replace(/\\/g, '/'));
+    const contractFiles = contractBoundary.map(f => normalize(f).replace(/\\/g, '/'));
+    for (const f of contractFiles) {
+      if (!jsonFiles.includes(f)) contractBoundaryMismatch.push(f);
+    }
+    for (const f of jsonFiles) {
+      if (!contractFiles.includes(f)) contractBoundaryMismatch.push(f);
+    }
+  }
+
+  const writeSetHash = hashWriteSet(writeSet);
+  state.dp_4_glaf4_mode = mode;
+  state.dp_4_write_set_hash = writeSetHash;
+  writeState(changeDir, state);
+
+  return {
+    ok: true,
+    dp_4_glaf4_mode: mode,
+    dp_4_write_set_hash: writeSetHash,
+    writeSetPath: path,
+    contractBoundaryMismatch: contractBoundaryMismatch.length ? contractBoundaryMismatch : null,
+    preModeWarning,
+  };
+}
+
+/**
+ * 从 run-dir 收集 glaf4-dev 实际写入文件（draft-result.json outputs.actual_files / claimed_files）
+ * @param {string} runDir glaf4-dev run 目录
+ * @returns {string[]} 相对 target_root 的文件路径（去重）
+ */
+export function collectActualWrites(runDir) {
+  const files = new Set();
+  const stagesDir = join(runDir, 'stages');
+  if (!existsSync(stagesDir)) return [...files];
+
+  const stages = readdirSync(stagesDir);
+  for (const stage of stages) {
+    const attemptsDir = join(stagesDir, stage, 'attempts');
+    if (!existsSync(attemptsDir)) continue;
+    const attempts = readdirSync(attemptsDir);
+    for (const attempt of attempts) {
+      const draftPath = join(attemptsDir, attempt, 'draft-result.json');
+      if (!existsSync(draftPath)) continue;
+      try {
+        const draft = JSON.parse(readFileSync(draftPath, 'utf-8'));
+        const actual = draft?.outputs?.actual_files || [];
+        const claimed = draft?.claimed_files || [];
+        for (const f of [...actual, ...claimed]) {
+          if (typeof f === 'string' && f.trim()) files.add(f.trim());
+        }
+      } catch {
+        // 损坏的 draft 忽略
+      }
+    }
+  }
+  return [...files];
+}
+
+/**
+ * 判断写入文件是否在允许集内（v2.1 §6.3）
+ * @param {string} file 相对 target_root 的文件路径（正斜杠分隔）
+ * @returns {boolean}
+ */
+export function isInAllowedSet(file) {
+  const norm = normalize(file).replace(/\\/g, '/');
+  for (const allowed of WRITE_SET_ALLOWED) {
+    const a = normalize(allowed).replace(/\\/g, '/');
+    if (norm === a || norm.startsWith(`${a}/`)) return true;
+  }
+  return false;
+}
+
+/**
+ * write-set 对账（门禁级）：glaf4-dev 实际写入 ⊆ change 边界 + 允许集
+ * @param {string} changeDir change 目录
+ * @param {string} runDir glaf4-dev run 目录
+ * @returns {object} { ok, violations[], actualWrites[], inBoundary, inAllowed }
+ */
+export function verifyWriteSet(changeDir, runDir) {
+  const wsPath = writeSetPath(changeDir);
+  if (!existsSync(wsPath)) {
+    return { ok: false, violations: ['write-set.json 缺失——先执行 glaf4-delegation confirm（DP-4 委托确认）'], actualWrites: [] };
+  }
+  const writeSet = JSON.parse(readFileSync(wsPath, 'utf-8'));
+  const boundary = new Set((writeSet.files || []).map(f => normalize(f).replace(/\\/g, '/')));
+
+  const actualWrites = collectActualWrites(runDir);
+  const violations = [];
+  let inBoundary = 0;
+  let inAllowed = 0;
+  for (const file of actualWrites) {
+    const norm = normalize(file).replace(/\\/g, '/');
+    if (boundary.has(norm) || [...boundary].some(b => norm.startsWith(`${b}/`))) {
+      inBoundary++;
+    } else if (isInAllowedSet(norm)) {
+      inAllowed++;
+    } else {
+      violations.push(norm);
+    }
+  }
+
+  return { ok: violations.length === 0, violations, actualWrites, inBoundary, inAllowed };
+}
+
+/**
+ * I4（2026-08-18）：partial writes 落盘清单（v2.1 §6.7）
+ * BLOCKED 终局时扫 run 实际写入写 delegation_partial_writes（JSON 字符串），
+ * 人工核对从"扫盘"降为"确认清单"。不改 delegation_status（由编排决定置 failed/其他）。
+ * @param {string} changeDir change 目录
+ * @param {string} runDir glaf4-dev run 目录
+ * @returns {object} { ok, partialWrites[], count }
+ */
+export function recordPartialWrites(changeDir, runDir) {
+  const partialWrites = collectActualWrites(runDir);
+  const state = readState(changeDir);
+  state.delegation_partial_writes = JSON.stringify(partialWrites);
+  writeState(changeDir, state);
+  return { ok: true, partialWrites, count: partialWrites.length };
+}
+
+/**
+ * task 完成度对账（审计输出）：tasks.md targets 注解统计
+ * @param {string} changeDir change 目录
+ * @returns {object} { ok, totalTasks, doneTasks, annotatedTasks, missingAnnotation }
+ */
+export function verifyTasks(changeDir) {
+  const tasksPath = join(changeDir, 'tasks.md');
+  if (!existsSync(tasksPath)) {
+    return { ok: false, totalTasks: 0, doneTasks: 0, annotatedTasks: 0, missingAnnotation: 0 };
+  }
+  const content = readFileSync(tasksPath, 'utf-8');
+  const taskLines = content.split('\n').filter(l => /^- \[[ xX]\] /.test(l));
+  const totalTasks = taskLines.length;
+  const doneTasks = taskLines.filter(l => /^- \[[xX]\] /.test(l)).length;
+  const annotatedTasks = taskLines.filter(l => /·\s*targets:\s*/.test(l)).length;
+
+  return {
+    ok: doneTasks === totalTasks && totalTasks > 0,
+    totalTasks,
+    doneTasks,
+    annotatedTasks,
+    missingAnnotation: totalTasks - annotatedTasks,
+  };
+}
+
+/**
+ * 6.7 官方降级：删 plan 重走 DP-4（revise 只允许 sdd，无法切换 → 删除 plan + 清理 execution_plan_hash）
+ * @param {string} changeDir change 目录
+ * @returns {object} { ok, deletedPlan, cleanedHash }
+ */
+export function resetDelegation(changeDir) {
+  const overlay = getOverlayPaths(changeDir);
+  const planPath = overlay.executionPlan;
+  let deletedPlan = false;
+  if (existsSync(planPath)) {
+    rmSync(planPath, { force: true });
+    deletedPlan = true;
+  }
+  // 同时清理 execution-recommendation receipt（删 plan 后需重新 recommend）
+  if (overlay.executionRecommendation && existsSync(overlay.executionRecommendation)) {
+    rmSync(overlay.executionRecommendation, { force: true });
+  }
+
+  const state = readState(changeDir);
+  state.execution_plan_hash = null;
+  state.execution_plan_revision = null;
+  state.execution_mode = null;
+  // L3（2026-08-18）：清理 dp_4 委托决策与 delegation 状态位，避免 failed 残留继续阻断 closing
+  state.dp_4_glaf4_mode = null;
+  state.dp_4_write_set_hash = null;
+  state.delegation_status = null;
+  state.delegation_retry_count = null;
+  state.delegation_partial_writes = null;
+  writeState(changeDir, state);
+
+  return { ok: true, deletedPlan, cleanedHash: state.execution_plan_hash === null };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+export async function run(args) {
+  const positionals = args.filter(a => !a.startsWith('--'));
+  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--json'));
+  const opt = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const subcommand = positionals[0];
+  const changeDir = positionals[1];
+  const json = flags.has('--json') || args.includes('--json');
+
+  const usage = `Usage:
+  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>]
+  tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json-file>
+  tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir>
+  tf glaf4-delegation verify-tasks <change-dir>
+  tf glaf4-delegation record-partial <change-dir> --run-dir <run-dir>
+  tf glaf4-delegation reset <change-dir>`;
+
+  if (!subcommand || !changeDir) {
+    console.error(usage);
+    process.exit(2);
+  }
+
+  const print = (ok, data, msg) => {
+    if (json) console.log(JSON.stringify({ ok, ...data }));
+    else console.log(`${ok ? '✅' : '❌'} ${msg}`);
+  };
+
+  try {
+    if (subcommand === 'detect') {
+      const mode = opt('delegation-mode');
+      // 第四轮复评 Minor-1（2026-08-18）：枚举校验——非法值（如 'foo'）等同 auto 放行会让用户配置失真
+      if (mode !== undefined && !['auto', 'manual', 'off'].includes(mode)) {
+        console.error(`--delegation-mode 必须为 auto/manual/off 之一（实际: ${mode}）`);
+        process.exit(2);
+      }
+      const result = detectAndWriteConfig(changeDir, mode);
+      const msg = result.glaf4_dev_available
+        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}`
+        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}`;
+      print(result.ok, result, msg);
+    } else if (subcommand === 'confirm') {
+      const mode = opt('mode');
+      const writeSetFile = opt('write-set');
+      if (!mode || !writeSetFile) { console.error('confirm 需要 --mode 与 --write-set'); process.exit(2); }
+      const writeSet = JSON.parse(readFileSync(resolve(writeSetFile), 'utf-8'));
+      const result = confirmDelegation(changeDir, { mode, writeSet });
+      print(result.ok, result, `DP-4 委托确认: mode=${result.dp_4_glaf4_mode}, write_set_hash=${result.dp_4_write_set_hash.slice(0, 12)}…`);
+      if (result.preModeWarning) {
+        console.warn(`⚠️  ${result.preModeWarning}`);
+      }
+      if (result.contractBoundaryMismatch) {
+        console.warn(`⚠️  execution-contract GLAF4 Delegation 段 write_set_boundary 与 write-set.json 不一致:\n    ${result.contractBoundaryMismatch.join('\n    ')}\n    建议同步契约段（JSON 为机械权威源）`);
+      }
+    } else if (subcommand === 'record-partial') {
+      const runDir = opt('run-dir');
+      if (!runDir) { console.error('record-partial 需要 --run-dir'); process.exit(2); }
+      const result = recordPartialWrites(changeDir, resolve(runDir));
+      print(result.ok, result, `partial writes 清单已记录 ${result.count} 个文件 → delegation_partial_writes`);
+    } else if (subcommand === 'verify-write-set') {
+      const runDir = opt('run-dir');
+      if (!runDir) { console.error('verify-write-set 需要 --run-dir'); process.exit(2); }
+      const result = verifyWriteSet(changeDir, resolve(runDir));
+      const msg = result.ok
+        ? `write-set 对账通过: ${result.inBoundary} 个边界内写入, ${result.inAllowed} 个允许集写入`
+        : `write-set 对账 FAIL: ${result.violations.length} 个越界文件\n    ${result.violations.join('\n    ')}`;
+      print(result.ok, result, msg);
+      if (!result.ok) process.exitCode = 1;
+    } else if (subcommand === 'verify-tasks') {
+      const result = verifyTasks(changeDir);
+      const msg = `task 审计: ${result.doneTasks}/${result.totalTasks} 完成, ${result.annotatedTasks} 含 targets 注解, ${result.missingAnnotation} 缺注解`;
+      print(result.ok, result, msg);
+    } else if (subcommand === 'reset') {
+      const result = resetDelegation(changeDir);
+      print(result.ok, result, `6.7 降级: plan ${result.deletedPlan ? '已删除' : '不存在'}, execution_plan_hash 已清理 → 重走 DP-4`);
+    } else {
+      console.error(`未知子命令: ${subcommand}`);
+      console.error(usage);
+      process.exit(2);
+    }
+  } catch (err) {
+    console.error(`❌ glaf4-delegation error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// 直接运行
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}