@kunlv/atdc 1.0.0

package/bin/atdc.js

@@ -0,0 +1,460 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { HOME, MEMORY_DIR, PACKAGE_DIR, TERMINAL_CONFIGS } = require('../src/constants');
+const { exists, mkdirp, resolvePackageDir, replaceAllInDir } = require('../src/utils');
+const evidence = require('../src/evidence');
+
+const installers = {
+  claude: require('../src/installers/claude'),
+  opencode: require('../src/installers/opencode'),
+  codex: require('../src/installers/codex'),
+};
+
+const ALL_TARGETS = ['claude', 'opencode', 'codex'];
+
+function usage() {
+  console.log(`atdc — AI coding workflow orchestration kit
+
+Usage:
+  atdc install [--claude|--opencode|--codex|--all]   Register to AI terminals
+  atdc uninstall [--all]                               Remove registrations
+  atdc status                                          Show installation status
+  atdc guardrails                                      Install git pre-push hook
+  atdc guard <phase>                                   Validate phase transition preconditions
+  atdc validate                                        Validate .phase-state.json schema
+  atdc handoff <change>                                Generate compressed context package
+  atdc run [--hotfix|--tweak|--bugfix]                  Quick-run with preset workflow
+  atdc archive <change> [--dry-run]                    Archive a completed change
+  atdc hook install                                    Install phase write guard to OpenCode
+  atdc ponytail scan [--diff]                          Scan project for over-engineering patterns
+  atdc ponytail guard [--strict|--warn]                Enforce ponytail rules before build
+  atdc ponytail fix [--dry-run] --pattern=<id>         Apply generic refactor (crud|rpc|di)
+  atdc evidence events <change> [--type=<t>] [--limit=<n>]   List evidence events
+  atdc evidence stats <change>                                Event statistics
+  atdc evidence timing <change>                               Stage timing report
+  atdc evidence metrics <change> [--snapshot|--commit]        AI draft metrics
+  atdc evidence canvas <change> [--out=<path>]                Generate evidence dashboard
+  atdc evidence record <change> <type>                        Record an evidence event
+  atdc evidence all <change>                                  Full evidence summary
+
+Options:
+  --claude    Claude Code only
+  --opencode  OpenCode only
+  --codex     Codex only
+  --all       All detected terminals (default for install)
+`);
+}
+
+function parseTargets(args) {
+  const targets = new Set();
+  for (const a of args) {
+    if (a === '--all') { ALL_TARGETS.forEach(t => targets.add(t)); }
+    else if (a === '--claude') targets.add('claude');
+    else if (a === '--opencode') targets.add('opencode');
+    else if (a === '--codex') targets.add('codex');
+  }
+  if (targets.size === 0) targets.add('all');
+  return targets;
+}
+
+function runForTargets(targets, fnName) {
+  const hasAll = targets.has('all');
+  const results = [];
+
+  for (const t of ALL_TARGETS) {
+    if (!hasAll && !targets.has(t)) continue;
+    const cfg = TERMINAL_CONFIGS[t];
+    console.log(`\n${cfg.name}:`);
+    const r = installers[t][fnName]();
+    if (!r.ok) {
+      console.log(`  ⚠ ${r.error}`);
+      results.push({ target: t, ok: false, error: r.error });
+    } else if (r.results) {
+      r.results.forEach(line => console.log(line));
+      results.push({ target: t, ok: true });
+    } else if (r.details) {
+      for (const [k, v] of Object.entries(r.details)) {
+        const icon = v === 'ok' ? '✓' : v === 'conflict' ? '⚠' : '✗';
+        console.log(`  ${icon} ${k}: ${v}`);
+      }
+      results.push({ target: t, ok: true });
+    }
+  }
+
+  return results;
+}
+
+function cmdInstall(args) {
+  const targets = parseTargets(args);
+  const pkgDir = resolvePackageDir();
+
+  replaceAllInDir(path.join(pkgDir, 'commands'), '{{ATDC_DIR}}', pkgDir);
+
+  mkdirp(MEMORY_DIR);
+
+  console.log(`atdc dir : ${pkgDir}`);
+  console.log(`memory dir  : ${MEMORY_DIR}`);
+
+  runForTargets(targets, 'install');
+
+  console.log(`\nDone. Triggers:`);
+  console.log(`  Claude Code  /atdc:1-spec <需求>`);
+  console.log(`  OpenCode     /atdc:1-spec <需求>`);
+  console.log(`  Codex        atd:1-spec <需求>`);
+  console.log('');
+}
+
+function cmdUninstall(args) {
+  const targets = parseTargets(args);
+  const pkgDir = resolvePackageDir();
+
+  runForTargets(targets, 'uninstall');
+
+  replaceAllInDir(path.join(pkgDir, 'commands'), pkgDir, '{{ATDC_DIR}}');
+
+  console.log('\nUninstall complete. Run `npm uninstall -g atdc` to remove package files.');
+}
+
+function cmdStatus() {
+  console.log(`atdc dir : ${resolvePackageDir()}`);
+
+  for (const t of ALL_TARGETS) {
+    const cfg = TERMINAL_CONFIGS[t];
+    console.log(`\n${cfg.name}:`);
+    const r = installers[t].status();
+    if (!r.installed) {
+      console.log(`  not detected`);
+      continue;
+    }
+    for (const [k, v] of Object.entries(r.details)) {
+      const icon = v === 'ok' ? '✓' : v === 'conflict' ? '⚠' : '✗';
+      console.log(`  ${icon} ${k}: ${v}`);
+    }
+  }
+  console.log('');
+}
+
+function cmdGuardrails() {
+  const pkgDir = resolvePackageDir();
+  const hookSrc = path.join(pkgDir, 'hooks', 'guardrails.sh');
+
+  let gitDir;
+  try {
+    const { execSync } = require('child_process');
+    gitDir = execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+  } catch {
+    console.log('Not a git repository. Run inside a git project.');
+    process.exit(1);
+  }
+
+  const hookPath = path.resolve(gitDir, 'hooks', 'pre-push');
+
+  if (exists(hookPath)) {
+    const { isSymlink, getSymlinkTarget } = require('../src/utils');
+    if (isSymlink(hookPath) && getSymlinkTarget(hookPath) === hookSrc) {
+      console.log('✓ git-guardrails already installed');
+      return;
+    }
+    console.log(`⚠ Existing pre-push hook found. Manual merge needed.`);
+    console.log(`  Reference: ${hookSrc}`);
+    process.exit(1);
+  }
+
+  fs.symlinkSync(hookSrc, hookPath);
+  console.log(`✓ git-guardrails installed → .git/hooks/pre-push`);
+}
+
+function runScript(script, ...args) {
+  const { execSync } = require('child_process');
+  const pkgDir = resolvePackageDir();
+  const scriptPath = path.join(pkgDir, 'hooks', script);
+  if (!exists(scriptPath)) {
+    console.log(`Script not found: ${scriptPath}`);
+    process.exit(1);
+  }
+  try {
+    const result = execSync(`sh "${scriptPath}" ${args.join(' ')}`, { encoding: 'utf8' });
+    console.log(result.trim());
+  } catch (e) {
+    console.error(e.stderr || e.stdout || e.message);
+    process.exit(e.status || 1);
+  }
+}
+
+function findActiveChange() {
+  const changesDir = 'openspec/changes';
+  if (!exists(changesDir)) return null;
+  const entries = fs.readdirSync(changesDir).filter(e => {
+    if (e === 'archive') return false;
+    const stat = fs.statSync(path.join(changesDir, e));
+    return stat.isDirectory();
+  });
+  // prefer changes with .phase-state.json
+  const phaseState = entries.filter(e => exists(path.join(changesDir, e, '.phase-state.json')));
+  if (phaseState.length === 1) return phaseState[0];
+  if (phaseState.length > 1) return phaseState[0];
+  return entries.length === 1 ? entries[0] : (entries.length > 0 ? entries[0] : null);
+}
+
+function cmdGuard(args) {
+  const phase = args[0];
+  if (!phase) { console.log('Usage: atdc guard <phase>'); process.exit(1); }
+  const change = findActiveChange();
+  if (!change) { console.log('No active change found. Run atdc run first.'); process.exit(1); }
+  runScript('phase-guard.sh', change, phase);
+}
+
+function cmdValidate(args) {
+  const { execSync } = require('child_process');
+  const pkgDir = resolvePackageDir();
+  const validator = path.join(pkgDir, 'src', 'validators', 'state-validate.js');
+  if (!exists(validator)) { console.log('Validator not found. Install atdc first.'); process.exit(1); }
+  try {
+    const result = execSync(`node "${validator}"`, { encoding: 'utf8' });
+    console.log(result.trim());
+  } catch (e) {
+    console.error(e.stderr || e.stdout || e.message);
+    process.exit(e.status || 1);
+  }
+}
+
+function cmdHandoff(args) {
+  const change = args[0] || findActiveChange();
+  if (!change) { console.log('Usage: atdc handoff <change-name>'); process.exit(1); }
+  runScript('handoff-compress.sh', change);
+}
+
+function cmdRun(args) {
+  let mode = 'full';
+  if (args.includes('--bugfix')) mode = 'bugfix';
+  else if (args.includes('--hotfix')) mode = 'hotfix';
+  else if (args.includes('--tweak')) mode = 'tweak';
+
+  const { execSync } = require('child_process');
+  const ts = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  const changeName = `${mode}-${ts}`;
+  const changeDir = `openspec/changes/${changeName}`;
+
+  mkdirp(changeDir);
+  mkdirp(`${changeDir}/specs`);
+
+  if (mode === 'bugfix') {
+    console.log('🐛 Bugfix mode: feedback loop → root cause → fix → post-mortem');
+    runScript('atd-state.sh', 'init', changeName, 'bugfix');
+    runScript('atd-state.sh', 'set', changeName, 'phase', '"build"');
+  } else if (mode === 'hotfix') {
+    console.log('⚡ Hotfix mode: skipping brainstorm + design');
+    runScript('atd-state.sh', 'init', changeName, 'hotfix');
+    runScript('atd-state.sh', 'set', changeName, 'phase', '"build"');
+  } else if (mode === 'tweak') {
+    console.log('🔧 Tweak mode: skipping brainstorm + full plan');
+    runScript('atd-state.sh', 'init', changeName, 'tweak');
+    runScript('atd-state.sh', 'set', changeName, 'phase', '"build"');
+  } else {
+    runScript('atd-state.sh', 'init', changeName, 'full');
+  }
+
+  console.log(`Change created: ${changeName} (mode: ${mode})`);
+}
+
+function cmdArchive(args) {
+  const dryRun = args.includes('--dry-run');
+  const change = args.filter(a => a !== '--dry-run')[0] || findActiveChange();
+  if (!change) { console.log('Usage: atdc archive <change-name> [--dry-run]'); process.exit(1); }
+  const extra = dryRun ? '--dry-run' : '';
+  runScript('atd-archive.sh', extra, change);
+}
+
+function cmdHook(args) {
+  const sub = args[0];
+  if (sub !== 'install') { console.log('Usage: atdc hook install'); process.exit(1); }
+  const { execSync } = require('child_process');
+  const pkgDir = resolvePackageDir();
+  const guardPath = path.join(pkgDir, 'hooks', 'phase-write-guard.sh');
+  const evidencePath = path.join(pkgDir, 'hooks', 'evidence-hook.sh');
+
+  // Check OpenCode config paths
+  const configPaths = [
+    path.join(process.cwd(), '.opencode', 'config.json'),
+    path.join(process.cwd(), '.opencode', 'opencode.json'),
+    path.join(HOME, '.config', 'opencode', 'opencode.json'),
+  ];
+
+  const configFile = configPaths.find(p => exists(p));
+  if (!configFile) {
+    console.log('No OpenCode config found. Skipping hook install.');
+    console.log('Supported paths: .opencode/config.json, .opencode/opencode.json, ~/.config/opencode/opencode.json');
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch {
+    console.log('Failed to parse OpenCode config file.');
+    process.exit(1);
+  }
+
+  if (!config.hooks) config.hooks = {};
+  if (!config.hooks.PreToolUse) config.hooks.PreToolUse = [];
+
+  // phase-write-guard (PreToolUse)
+  if (!config.hooks.PreToolUse.some(h => typeof h === 'string' && h.includes('phase-write-guard'))) {
+    config.hooks.PreToolUse.push(`sh ${guardPath}`);
+    console.log('✓ phase-write-guard hook installed');
+  } else {
+    console.log('✓ phase-write-guard hook already installed');
+  }
+
+  // evidence-hook (PostToolUse — fires AFTER writes, detects state changes)
+  if (!config.hooks.PostToolUse) config.hooks.PostToolUse = [];
+  if (!config.hooks.PostToolUse.some(h => typeof h === 'string' && h.includes('evidence-hook'))) {
+    config.hooks.PostToolUse.push(`sh ${evidencePath}`);
+    console.log('✓ evidence-hook installed (auto-records state changes)');
+  } else {
+    console.log('✓ evidence-hook already installed');
+  }
+
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + '\n');
+  console.log(`✓ hooks updated → ${configFile}`);
+}
+
+function cmdEvidence(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  if (!sub) {
+    console.log('Usage: atdc evidence {events|stats|timing|metrics|canvas|record|all} ...');
+    process.exit(1);
+  }
+
+  switch (sub) {
+    case 'events': {
+      const change = rest.filter(a => !a.startsWith('--'))[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const type = rest.find(a => a.startsWith('--type='))?.split('=')[1];
+      const limit = parseInt(rest.find(a => a.startsWith('--limit='))?.split('=')[1] || '50');
+      const dir = evidence.resolveChangeDir(change);
+      const events = evidence.listEvents(dir, { type, limit });
+      if (events.length === 0) {
+        console.log('No events found.');
+      } else {
+        events.forEach(({ event }) => {
+          console.log(`[${event.timestamp.slice(0, 19)}] ${event.event_type} · phase=${event.phase} · ${event.event_id.slice(0, 8)}`);
+        });
+        console.log(`\n${events.length} events total.`);
+      }
+      break;
+    }
+    case 'stats': {
+      const change = rest[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const dir = evidence.resolveChangeDir(change);
+      const stats = evidence.eventStats(dir);
+      console.log(JSON.stringify(stats, null, 2));
+      break;
+    }
+    case 'timing': {
+      const change = rest[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const dir = evidence.resolveChangeDir(change);
+      const report = evidence.stageReport(dir);
+      console.log(JSON.stringify(report, null, 2));
+      break;
+    }
+    case 'metrics': {
+      const change = rest.filter(a => !a.startsWith('--'))[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const dir = evidence.resolveChangeDir(change);
+      if (rest.includes('--snapshot')) {
+        const result = evidence.captureDraftSnapshot(dir);
+        console.log(JSON.stringify(result, null, 2));
+      } else if (rest.includes('--commit')) {
+        const result = evidence.captureCommitDiff(dir);
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const report = evidence.metricsReport(dir);
+        console.log(JSON.stringify(report, null, 2));
+      }
+      break;
+    }
+    case 'canvas': {
+      const change = rest.filter(a => !a.startsWith('--'))[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const outArg = rest.find(a => a.startsWith('--out='));
+      const outPath = outArg ? outArg.split('=')[1] : null;
+      const dir = evidence.resolveChangeDir(change);
+      const dest = evidence.writeCanvas(dir, outPath);
+      console.log(`Canvas written to: ${dest}`);
+      break;
+    }
+    case 'record': {
+      const change = rest[0];
+      const type = rest[1];
+      if (!change || !type) {
+        console.log('Usage: atdc evidence record <change> <type> [--phase=<p>] [--key=value...]');
+        process.exit(1);
+      }
+      const dir = evidence.resolveChangeDir(change);
+      const phase = rest.find(a => a.startsWith('--phase='))?.split('=')[1] || 'unknown';
+      const metadata = {};
+      rest.forEach(a => {
+        if (a.startsWith('--') && a.includes('=') && !a.startsWith('--phase=')) {
+          const [k, v] = a.slice(2).split('=');
+          metadata[k] = v;
+        }
+      });
+      const result = evidence.writeEvent(dir, type, metadata, { change, phase });
+      console.log(`Event recorded: ${result.filepath}`);
+      break;
+    }
+    case 'all': {
+      const change = rest[0] || findActiveChange();
+      if (!change) { console.log('No active change found.'); process.exit(1); }
+      const dir = evidence.resolveChangeDir(change);
+      const result = evidence.allEvidence(change);
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+    case 'link':
+      cmdEvidenceLink();
+      break;
+    default:
+      console.log('Usage: atdc evidence {events|stats|timing|metrics|canvas|record|all|link} ...');
+  }
+}
+
+function cmdEvidenceLink() {
+  const linkScript = path.join(HOME, 'atdc', 'central', 'link.sh');
+  if (!exists(linkScript)) { console.log('~/atdc/central/link.sh not found'); process.exit(1); }
+  const { execSync } = require('child_process');
+  try {
+    const result = execSync(`sh "${linkScript}" --status`, { encoding: 'utf8' });
+    console.log(result.trim());
+    execSync(`sh "${linkScript}"`, { encoding: 'utf8', stdio: 'inherit' });
+  } catch (e) {
+    console.error(e.stderr || e.message);
+    process.exit(1);
+  }
+}
+
+const [,, cmd, ...args] = process.argv;
+
+switch (cmd) {
+  case 'install': cmdInstall(args); break;
+  case 'uninstall': cmdUninstall(args); break;
+  case 'status': cmdStatus(); break;
+  case 'guardrails': cmdGuardrails(); break;
+  case 'guard': cmdGuard(args); break;
+  case 'validate': cmdValidate(args); break;
+  case 'handoff': cmdHandoff(args); break;
+  case 'run': cmdRun(args); break;
+  case 'archive': cmdArchive(args); break;
+  case 'hook': cmdHook(args); break;
+  case 'ponytail': cmdPonytail(args); break;
+  case 'evidence': cmdEvidence(args); break;
+  default: usage(); break;
+}

package/bin/cls.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+const client = require('../src/cls/client');
+
+const HELP = `cls — CLS 日志查询 CLI
+
+用法:
+  cls --init                          初始化配置文件
+  cls --list-accounts                 列出可用账号
+  cls <account> <query> [options]     查询 CLS 日志
+
+选项:
+  --limit N        返回条数（默认 200，最大 1000）
+  --out DIR        输出目录（默认当前目录）
+  --from TIME      开始时间（默认 15m 前，支持 "2026-07-17 10:00"）
+  --to TIME        结束时间（默认当前）
+  --type TYPE      topic 类型（默认 error）
+  --regions R      地域（默认 gz,bj）
+  --format FORMAT  输出格式 json|jsonl（默认 jsonl）
+  --fetch          全量落地（调 cls_fetch_bulk.py）
+  --max N          全量最大条数（默认 5000）
+  --quiet          静默模式（不输出进度）
+  --help           显示此帮助
+
+示例:
+  cls tcs "callTencentMusicAPI AND done"
+  cls tcs "order AND pay*" --limit 500 --out /tmp/logs/
+  cls tcs "order AND pay*" --fetch --max 10000`;
+
+function usage() {
+  console.log(HELP);
+  process.exit(0);
+}
+
+function fail(msg) {
+  console.error(`cls: ${msg}`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes('--help')) {
+  if (args.length === 0) {
+    try { client.loadConfig(); } catch { client.initConfig(); console.log('配置已生成: ~/.cls/config.json'); process.exit(0); }
+  }
+  usage();
+}
+
+if (args[0] === '--init') {
+  const r = client.initConfig();
+  console.log(r.msg);
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (args[0] === '--list-accounts') {
+  try {
+    const accounts = client.listAccounts();
+    console.log('可用账号:');
+    Object.entries(accounts).forEach(([alias, name]) => console.log(`  ${alias} → ${name}`));
+  } catch (e) { fail(e.message); }
+  process.exit(0);
+}
+
+const [account, query] = args;
+if (!account || !query) fail('用法: cls <account> <query> [options]');
+
+const opts = {};
+for (let i = 2; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--limit') opts.limit = parseInt(args[++i]);
+  else if (a === '--out') opts.out_dir = args[++i];
+  else if (a === '--from') opts.from = args[++i];
+  else if (a === '--to') opts.to = args[++i];
+  else if (a === '--type') opts.type = args[++i];
+  else if (a === '--regions') opts.regions = args[++i];
+  else if (a === '--format') opts.format = args[++i];
+  else if (a === '--max') opts.max = parseInt(args[++i]);
+  else if (a === '--fetch') opts.fetch = true;
+  else if (a === '--quiet') opts.quiet = true;
+}
+
+try {
+  if (opts.fetch) {
+    const result = client.fetchSync(account, query, opts);
+    console.log(`→ ${result.output_file} (${result.total} 条)`);
+  } else {
+    const result = client.searchSync(account, query, opts);
+    console.log(`→ ${result.output_file} (${result.count} 条)`);
+  }
+} catch (e) {
+  if (e.message && e.message.includes('配置文件') && e.message.includes('不存在')) {
+    client.initConfig();
+    console.log('配置已生成: ~/.cls/config.json，请重试命令');
+  } else {
+    fail(e.stderr || e.message);
+  }
+}

package/central/link.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# ~/atdc/central/link.sh — unified worktree symlink manager
+# Called from GO.md Step 0b at every session start. Idempotent.
+#
+# Pattern:
+#   Main repo → hosts real dirs
+#   Worktree  → symlink to main repo's dirs
+#   Already linked → skip
+
+set -euo pipefail
+
+DIRS=(
+  .code-review-graph
+  .codegraph
+  .hc
+  .test_plans
+  .handoffs
+  .evidence
+)
+
+# ── Find main worktree ──
+MAIN=$(git worktree list --porcelain 2>/dev/null | awk '
+  /^worktree / { p=$2 }
+  /^bare /    { bare=($2=="true") }
+  /^HEAD /    { head=$2 }
+  /^$/        { if(bare!="true" && p!="") print p; p=""; bare=""; head="" }
+' | head -1)
+
+[ -z "$MAIN" ] && MAIN=$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')
+[ -z "$MAIN" ] && exit 0
+
+CURRENT="$(pwd)"
+
+# ── Link each dir ──
+for dir in "${DIRS[@]}"; do
+  # Already valid symlink → skip
+  if [ -L "$dir" ]; then
+    [ -d "$(readlink "$dir")" ] && continue
+    rm -f "$dir"
+  fi
+
+  # Main worktree: ensure real dir exists (hosting)
+  if [ "$CURRENT" = "$MAIN" ]; then
+    [ -d "$dir" ] || mkdir -p "$dir"
+    continue
+  fi
+
+  # Worktree: main must have dir, then symlink
+  [ -d "$MAIN/$dir" ] || mkdir -p "$MAIN/$dir"
+
+  # Migrate stray real dir → main
+  if [ -d "$dir" ] && [ ! -L "$dir" ]; then
+    mv "$dir"/* "$MAIN/$dir/" 2>/dev/null || true
+    rm -rf "$dir"
+  fi
+
+  ln -s "$MAIN/$dir" "$dir"
+done
+
+exit 0