hamster-wheel-cli 0.1.0

package/src/runtime-tracker.ts

@@ -0,0 +1,65 @@
+import { Logger } from './logger';
+import { RunMetadata, removeCurrentRegistry, upsertCurrentRegistry, writeRunMetadata } from './logs';
+
+export interface RunTracker {
+  readonly update: (round: number, tokenUsed: number) => Promise<void>;
+  readonly finalize: () => Promise<void>;
+}
+
+interface RunTrackerOptions {
+  readonly logFile?: string;
+  readonly command: string;
+  readonly path: string;
+  readonly logger?: Logger;
+}
+
+async function safeWrite(logFile: string, metadata: RunMetadata, logger?: Logger): Promise<void> {
+  try {
+    await writeRunMetadata(logFile, metadata);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger?.warn(`写入运行元信息失败: ${message}`);
+  }
+  try {
+    await upsertCurrentRegistry(logFile, metadata);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger?.warn(`更新 current.json 失败: ${message}`);
+  }
+}
+
+async function safeRemove(logFile: string, logger?: Logger): Promise<void> {
+  try {
+    await removeCurrentRegistry(logFile);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger?.warn(`清理 current.json 失败: ${message}`);
+  }
+}
+
+/**
+ * 创建运行中任务的追踪器（写入 JSON 元数据）。
+ */
+export async function createRunTracker(options: RunTrackerOptions): Promise<RunTracker | null> {
+  const { logFile, command, path, logger } = options;
+  if (!logFile) return null;
+
+  const update = async (round: number, tokenUsed: number): Promise<void> => {
+    const metadata: RunMetadata = {
+      command,
+      round,
+      tokenUsed,
+      path
+    };
+    await safeWrite(logFile, metadata, logger);
+  };
+
+  await update(0, 0);
+
+  return {
+    update,
+    finalize: async (): Promise<void> => {
+      await safeRemove(logFile, logger);
+    }
+  };
+}

package/src/summary.ts

@@ -0,0 +1,255 @@
+import { DeliverySummary, TestRunResult } from './types';
+
+/**
+ * 生成交付摘要提示的输入。
+ */
+export interface SummaryPromptInput {
+  readonly task: string;
+  readonly plan: string;
+  readonly notes: string;
+  readonly lastAiOutput: string;
+  readonly testResults: TestRunResult[] | null;
+  readonly gitStatus: string;
+  readonly diffStat: string;
+  readonly branchName?: string;
+}
+
+/**
+ * 兜底摘要输入。
+ */
+export interface SummaryFallbackInput {
+  readonly task: string;
+  readonly testResults: TestRunResult[] | null;
+}
+
+/**
+ * PR 文案兜底输入。
+ */
+export interface PrBodyFallbackInput {
+  readonly commitTitle: string;
+  readonly commitBody?: string;
+  readonly testResults: TestRunResult[] | null;
+}
+
+const REQUIRED_SECTIONS = ['# 变更摘要', '# 测试结果', '# 风险与回滚'] as const;
+
+function normalizeText(text: string): string {
+  return text.replace(/\r\n?/g, '\n');
+}
+
+function compactLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function trimTail(text: string, limit: number, emptyFallback: string): string {
+  const normalized = normalizeText(text).trim();
+  if (!normalized) return emptyFallback;
+  if (normalized.length <= limit) return normalized;
+  return `（内容过长，保留最后 ${limit} 字符）\n${normalized.slice(-limit)}`;
+}
+
+function formatTestResultLines(testResults: TestRunResult[] | null): string[] {
+  if (!testResults || testResults.length === 0) {
+    return ['- 未运行（本次未执行测试）'];
+  }
+  return testResults.map(result => {
+    const label = result.kind === 'unit' ? '单元测试' : 'e2e 测试';
+    const status = result.success ? '通过' : `失败（退出码 ${result.exitCode}）`;
+    const command = result.command ? `｜命令: ${result.command}` : '';
+    return `- ${label}: ${status} ${command}`.trim();
+  });
+}
+
+function formatTestResultsForPrompt(testResults: TestRunResult[] | null): string {
+  return formatTestResultLines(testResults).join('\n');
+}
+
+function buildSummaryLinesFromCommit(commitTitle: string, commitBody?: string): string[] {
+  const bulletLines = extractBulletLines(commitBody);
+  if (bulletLines.length > 0) return bulletLines;
+  const summary = stripCommitType(commitTitle);
+  return [`- ${summary}`];
+}
+
+function stripCommitType(title: string): string {
+  const trimmed = compactLine(title);
+  if (!trimmed) return '更新迭代产出';
+  const match = trimmed.match(/^[^:]+:\s*(.+)$/);
+  return match?.[1]?.trim() || trimmed;
+}
+
+function buildPrBody(summaryLines: string[], testLines: string[]): string {
+  const riskLines = ['- 风险：待评估', '- 回滚：git revert 对应提交或关闭 PR'];
+  return [
+    '# 变更摘要',
+    summaryLines.join('\n'),
+    '',
+    '# 测试结果',
+    testLines.join('\n'),
+    '',
+    '# 风险与回滚',
+    riskLines.join('\n')
+  ].join('\n');
+}
+
+/**
+ * 构建交付摘要提示词。
+ */
+export function buildSummaryPrompt(input: SummaryPromptInput): string {
+  const planSnippet = trimTail(input.plan, 2000, '（计划为空）');
+  const notesSnippet = trimTail(input.notes, 4000, '（notes 为空）');
+  const aiSnippet = trimTail(input.lastAiOutput, 3000, '（本轮无 AI 输出）');
+  const statusSnippet = trimTail(input.gitStatus, 1000, '（git status 为空）');
+  const diffSnippet = trimTail(input.diffStat, 1000, '（diff 统计为空）');
+  const testSummary = formatTestResultsForPrompt(input.testResults);
+
+  return [
+    '# 角色',
+    '你是资深工程师，需要为本次迭代生成提交信息与 PR 文案。',
+    '# 任务',
+    '基于输入信息输出严格 JSON（不要 markdown、不要代码块、不要多余文字）。',
+    '要求：',
+    '- 全部中文。',
+    '- commitTitle / prTitle 使用 Conventional Commits 格式：<type>: <概要>，简洁具体，不要出现“自动迭代提交/自动 PR”等字样。',
+    '- commitBody 为多行要点列表（可为空字符串）。',
+    '- prBody 为 Markdown，必须包含标题：# 变更摘要、# 测试结果、# 风险与回滚，并在变更摘要中体现工作总结。',
+    '- 不确定处可基于现有信息合理推断，但不要编造测试结果。',
+    '# 输出 JSON',
+    '{"commitTitle":"...","commitBody":"...","prTitle":"...","prBody":"..."}',
+    '# 输入信息',
+    `任务: ${compactLine(input.task) || '（空）'}`,
+    `分支: ${input.branchName ?? '（未知）'}`,
+    '计划（节选）:',
+    planSnippet,
+    'notes（节选）:',
+    notesSnippet,
+    '最近一次 AI 输出（节选）:',
+    aiSnippet,
+    '测试结果:',
+    testSummary,
+    'git status --short:',
+    statusSnippet,
+    'git diff --stat:',
+    diffSnippet
+  ].join('\n\n');
+}
+
+function pickString(record: Record<string, unknown>, keys: string[]): string | null {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+function extractJson(text: string): string | null {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) return fenced[1].trim();
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    return text.slice(start, end + 1).trim();
+  }
+  return null;
+}
+
+function normalizeTitle(title: string): string {
+  return compactLine(title);
+}
+
+function normalizeBody(body?: string | null): string | undefined {
+  if (!body) return undefined;
+  const normalized = normalizeText(body).trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function extractBulletLines(text?: string | null): string[] {
+  if (!text) return [];
+  const lines = normalizeText(text)
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean);
+  const bullets = lines.filter(line => line.startsWith('- ') || line.startsWith('* '));
+  return bullets.map(line => (line.startsWith('* ') ? `- ${line.slice(2).trim()}` : line));
+}
+
+/**
+ * 解析 AI 输出的交付摘要 JSON。
+ */
+export function parseDeliverySummary(output: string): DeliverySummary | null {
+  const jsonText = extractJson(output);
+  if (!jsonText) return null;
+  try {
+    const parsed = JSON.parse(jsonText) as Record<string, unknown>;
+    let commitTitle = pickString(parsed, ['commitTitle', 'commit_message', 'commitMessage', 'commit_title']);
+    let commitBody = pickString(parsed, ['commitBody', 'commit_body']);
+    let prTitle = pickString(parsed, ['prTitle', 'pr_title']);
+    let prBody = pickString(parsed, ['prBody', 'pr_body']);
+
+    const commitObj = parsed.commit;
+    if ((!commitTitle || !commitBody) && typeof commitObj === 'object' && commitObj !== null) {
+      const commitRecord = commitObj as Record<string, unknown>;
+      commitTitle = commitTitle ?? pickString(commitRecord, ['title', 'commitTitle']);
+      commitBody = commitBody ?? pickString(commitRecord, ['body', 'commitBody']);
+    }
+
+    const prObj = parsed.pr;
+    if ((!prTitle || !prBody) && typeof prObj === 'object' && prObj !== null) {
+      const prRecord = prObj as Record<string, unknown>;
+      prTitle = prTitle ?? pickString(prRecord, ['title', 'prTitle']);
+      prBody = prBody ?? pickString(prRecord, ['body', 'prBody']);
+    }
+
+    if (!commitTitle || !prTitle || !prBody) return null;
+
+    const normalizedCommitTitle = normalizeTitle(commitTitle);
+    const normalizedPrTitle = normalizeTitle(prTitle);
+    const normalizedCommitBody = normalizeBody(commitBody);
+    const normalizedPrBody = normalizeText(prBody).trim();
+
+    if (!normalizedCommitTitle || !normalizedPrTitle || !normalizedPrBody) return null;
+
+    return {
+      commitTitle: normalizedCommitTitle,
+      commitBody: normalizedCommitBody,
+      prTitle: normalizedPrTitle,
+      prBody: normalizedPrBody
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 构建兜底交付摘要。
+ */
+export function buildFallbackSummary(input: SummaryFallbackInput): DeliverySummary {
+  const taskLine = compactLine(input.task);
+  const shortTask = taskLine.length > 50 ? `${taskLine.slice(0, 50)}...` : taskLine;
+  const baseTitle = shortTask || '更新迭代产出';
+  const title = `chore: ${baseTitle}`;
+  const summaryLines = [`- ${baseTitle}`];
+  const testLines = formatTestResultLines(input.testResults);
+  const prBody = buildPrBody(summaryLines, testLines);
+  return {
+    commitTitle: title,
+    commitBody: summaryLines.join('\n'),
+    prTitle: title,
+    prBody
+  };
+}
+
+/**
+ * 确保 PR 文案包含必要章节。
+ */
+export function ensurePrBodySections(prBody: string, fallback: PrBodyFallbackInput): string {
+  const normalized = normalizeText(prBody).trim();
+  const hasAll = REQUIRED_SECTIONS.every(section => normalized.includes(section));
+  if (hasAll) return normalized;
+
+  const summaryLines = buildSummaryLinesFromCommit(fallback.commitTitle, fallback.commitBody);
+  const testLines = formatTestResultLines(fallback.testResults);
+  return buildPrBody(summaryLines, testLines);
+}

package/src/types.ts

@@ -0,0 +1,176 @@
+import type { Logger } from './logger';
+
+/**
+ * AI CLI 运行配置。
+ */
+export interface AiCliConfig {
+  readonly command: string;
+  readonly args: string[];
+  readonly promptArg?: string;
+}
+
+/**
+ * Token 使用统计。
+ */
+export interface TokenUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens: number;
+}
+
+/**
+ * AI 调用结果。
+ */
+export interface AiResult {
+  readonly output: string;
+  readonly usage: TokenUsage | null;
+}
+
+/**
+ * 提交信息结构。
+ */
+export interface CommitMessage {
+  readonly title: string;
+  readonly body?: string;
+}
+
+/**
+ * 交付内容摘要（提交 + PR）。
+ */
+export interface DeliverySummary {
+  readonly commitTitle: string;
+  readonly commitBody?: string;
+  readonly prTitle: string;
+  readonly prBody: string;
+}
+
+/**
+ * worktree 相关配置。
+ */
+export interface WorktreeConfig {
+  readonly useWorktree: boolean;
+  readonly branchName?: string;
+  readonly worktreePath?: string;
+  readonly baseBranch: string;
+}
+
+/**
+ * worktree 创建结果。
+ */
+export interface WorktreeResult {
+  readonly path: string;
+  readonly created: boolean;
+}
+
+/**
+ * 测试命令配置。
+ */
+export interface TestConfig {
+  readonly unitCommand?: string;
+  readonly e2eCommand?: string;
+}
+
+/**
+ * 测试执行结果。
+ */
+export interface TestRunResult {
+  readonly kind: 'unit' | 'e2e';
+  readonly command: string;
+  readonly success: boolean;
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * PR 配置。
+ */
+export interface PrConfig {
+  readonly enable: boolean;
+  readonly title?: string;
+  readonly bodyPath?: string;
+  readonly draft?: boolean;
+  readonly reviewers?: string[];
+}
+
+/**
+ * webhook 配置。
+ */
+export interface WebhookConfig {
+  readonly urls: string[];
+  readonly timeoutMs?: number;
+}
+
+/**
+ * 工作流文件路径。
+ */
+export interface WorkflowFiles {
+  readonly workflowDoc: string;
+  readonly notesFile: string;
+  readonly planFile: string;
+}
+
+/**
+ * 主循环配置。
+ */
+export interface LoopConfig {
+  readonly task: string;
+  readonly iterations: number;
+  readonly stopSignal: string;
+  readonly ai: AiCliConfig;
+  readonly workflowFiles: WorkflowFiles;
+  readonly git: WorktreeConfig;
+  readonly tests: TestConfig;
+  readonly pr: PrConfig;
+  readonly webhooks?: WebhookConfig;
+  readonly cwd: string;
+  readonly logFile?: string;
+  readonly verbose: boolean;
+  readonly runTests: boolean;
+  readonly runE2e: boolean;
+  readonly autoCommit: boolean;
+  readonly autoPush: boolean;
+  readonly skipInstall: boolean;
+}
+
+/**
+ * 命令执行配置。
+ */
+export interface CommandOptions {
+  readonly cwd?: string;
+  readonly env?: Record<string, string>;
+  readonly input?: string;
+  readonly logger?: Logger;
+  readonly verboseLabel?: string;
+  readonly verboseCommand?: string;
+  readonly stream?: StreamOptions;
+}
+
+/**
+ * 命令执行结果。
+ */
+export interface CommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+
+/**
+ * 命令执行输出流配置。
+ */
+export interface StreamOptions {
+  readonly enabled: boolean;
+  readonly stdoutPrefix?: string;
+  readonly stderrPrefix?: string;
+}
+
+/**
+ * 迭代记录。
+ */
+export interface IterationRecord {
+  readonly iteration: number;
+  readonly prompt: string;
+  readonly aiOutput: string;
+  readonly timestamp: string;
+  readonly testResults?: TestRunResult[];
+}

package/src/utils.ts

@@ -0,0 +1,179 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { CommandOptions, CommandResult } from './types';
+
+type ExecaModule = typeof import('execa');
+type ExecaError = import('execa').ExecaError;
+
+const importExeca = async (): Promise<ExecaModule> => {
+  // 通过运行时动态 import 兼容 CommonJS 下加载 ESM 包
+  const importer = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<ExecaModule>;
+  return importer('execa');
+};
+
+/**
+ * 执行外部命令，支持日志与流式输出。
+ */
+export async function runCommand(command: string, args: string[], options: CommandOptions = {}): Promise<CommandResult> {
+  const label = options.verboseLabel ?? 'cmd';
+  const displayCmd = options.verboseCommand ?? [command, ...args].join(' ');
+  const cwd = options.cwd ?? process.cwd();
+  options.logger?.debug(`[${label}] ${displayCmd} (cwd: ${cwd})`);
+
+  const logger = options.logger;
+  const streamEnabled = Boolean(options.stream?.enabled && logger);
+  const stdoutPrefix = options.stream?.stdoutPrefix ?? `[${label}] `;
+  const stderrPrefix = options.stream?.stderrPrefix ?? `[${label} stderr] `;
+
+  const createLineStreamer = (prefix: string) => {
+    let buffer = '';
+    const emit = (line: string): void => {
+      logger?.info(`${prefix}${line}`);
+    };
+    const push = (chunk: string | Buffer): void => {
+      const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      buffer += text.replace(/\r/g, '\n');
+      const parts = buffer.split('\n');
+      buffer = parts.pop() ?? '';
+      parts.forEach(emit);
+    };
+    const flush = (): void => {
+      if (buffer.length === 0) return;
+      emit(buffer);
+      buffer = '';
+    };
+    return { push, flush };
+  };
+
+  const attachStream = (stream: NodeJS.ReadableStream | null | undefined, streamer: ReturnType<typeof createLineStreamer>): void => {
+    if (!stream) return;
+    if (typeof stream.setEncoding === 'function') {
+      stream.setEncoding('utf8');
+    }
+    stream.on('data', streamer.push);
+    stream.on('end', streamer.flush);
+  };
+
+  const stdoutStreamer = streamEnabled ? createLineStreamer(stdoutPrefix) : null;
+  const stderrStreamer = streamEnabled ? createLineStreamer(stderrPrefix) : null;
+
+  try {
+    const { execa } = await importExeca();
+    const subprocess = execa(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      input: options.input,
+      all: false
+    });
+    if (stdoutStreamer) {
+      attachStream(subprocess.stdout, stdoutStreamer);
+    }
+    if (stderrStreamer) {
+      attachStream(subprocess.stderr, stderrStreamer);
+    }
+    const result = await subprocess;
+    stdoutStreamer?.flush();
+    stderrStreamer?.flush();
+    const commandResult: CommandResult = {
+      stdout: String(result.stdout ?? ''),
+      stderr: String(result.stderr ?? ''),
+      exitCode: result.exitCode ?? 0
+    };
+    if (logger) {
+      const stdout = commandResult.stdout.trim();
+      const stderr = commandResult.stderr.trim();
+      if (stdout.length > 0) {
+        logger.debug(`[${label}] stdout: ${stdout}`);
+      }
+      if (stderr.length > 0) {
+        logger.debug(`[${label}] stderr: ${stderr}`);
+      }
+      logger.debug(`[${label}] exit ${commandResult.exitCode}`);
+    }
+    return commandResult;
+  } catch (error) {
+    const execaError = error as ExecaError;
+    stdoutStreamer?.flush();
+    stderrStreamer?.flush();
+    const commandResult: CommandResult = {
+      stdout: String(execaError.stdout ?? ''),
+      stderr: String(execaError.stderr ?? String(error)),
+      exitCode: execaError.exitCode ?? 1
+    };
+    if (logger) {
+      const stdout = commandResult.stdout.trim();
+      const stderr = commandResult.stderr.trim();
+      if (stdout.length > 0) {
+        logger.debug(`[${label}] stdout: ${stdout}`);
+      }
+      if (stderr.length > 0) {
+        logger.debug(`[${label}] stderr: ${stderr}`);
+      }
+      logger.debug(`[${label}] exit ${commandResult.exitCode}`);
+    }
+    return commandResult;
+  }
+}
+
+/**
+ * 返回 ISO 格式时间戳。
+ */
+export function isoNow(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * 基于 cwd 解析相对路径。
+ */
+export function resolvePath(cwd: string, target: string): string {
+  return path.isAbsolute(target) ? target : path.join(cwd, target);
+}
+
+/**
+ * 确保目录存在。
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdirp(dirPath);
+}
+
+/**
+ * 确保文件存在（必要时创建）。
+ */
+export async function ensureFile(filePath: string, initialContent = ''): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  const exists = await fs.pathExists(filePath);
+  if (!exists) {
+    await fs.writeFile(filePath, initialContent, 'utf8');
+  }
+}
+
+/**
+ * 向文件末尾追加一段内容（包含换行）。
+ */
+export async function appendSection(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  await fs.appendFile(filePath, `\n${content}\n`, 'utf8');
+}
+
+/**
+ * 安全读取文件内容，若不存在则返回空字符串。
+ */
+export async function readFileSafe(filePath: string): Promise<string> {
+  const exists = await fs.pathExists(filePath);
+  if (!exists) return '';
+  return fs.readFile(filePath, 'utf8');
+}
+
+/**
+ * 格式化 Markdown 标题。
+ */
+export function formatHeading(title: string): string {
+  return `## ${title}\n`;
+}
+
+/**
+ * 补齐两位数字字符串。
+ */
+export function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}