@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-init/README.md

@@ -0,0 +1,231 @@
+# Vibe Init
+
+`vibe-init` 用于把 Vibecoding Kit 第一阶段能力安装到目标项目。
+
+## 默认安装结构
+
+默认只在项目根目录生成平台会主动读取的入口文件，其余资产放到 `.vibecoding/`：
+
+```text
+CLAUDE.md          # Claude 平台入口，按需生成
+AGENTS.md          # Codex / Cursor 平台入口，按需生成
+.vibecoding/
+  skills/
+  hooks/
+  adapters/
+    claude/
+    codex/
+    cursor/
+    opencode/
+    pi/
+  VIBE-CODING.md   # 完整 Vibecoding 规则，来自 templates/VIBE-CODING.md
+  config.json
+```
+
+默认不安装到业务项目根目录：
+
+```text
+skills/
+adapters/
+hooks/
+docs/
+examples/
+README.md
+```
+
+入口文件来自安装模板：
+
+```text
+templates/CLAUDE.md
+templates/AGENTS.md
+templates/VIBE-CODING.md
+```
+
+根入口模板只保留低成本 agent 沙盒入口；完整交互协议、任务分流、质量底线和升级条件安装到 `.vibecoding/VIBE-CODING.md`。
+
+源码仓库根目录的 `CLAUDE.md` / `AGENTS.md` 只服务于 kit 自身开发，不会直接复制到业务项目。
+
+`docs/` 和 `examples/` 只有在 `--with-docs` 时安装到 `.vibecoding/`。
+
+## 使用
+
+推荐使用根 CLI wrapper。wrapper 只做命令路由，安装逻辑仍由 `tools/vibe-init/index.mjs` 执行。
+
+预览安装：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor --dry-run
+```
+
+实际安装：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor
+```
+
+在目标项目目录内安装时，`init` 默认 target 为当前目录：
+
+```bash
+node /path/to/vibecoding-kit/bin/vibe.mjs init --platform cursor
+```
+
+安装全部平台适配：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform all
+```
+
+安装前检查：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform auto --check
+```
+
+已有入口文件合并预览：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform auto --merge=preview
+```
+
+兼容别名 `--merge-preview` 仍可用，但文档和主 CLI 示例统一使用 `--merge=preview`。
+
+同时安装文档和 examples：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform all --with-docs
+```
+
+安装 installed runtime opt-in manifest：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor --with-runtime
+```
+
+兼容调用仍可用：
+
+```bash
+node tools/vibe-init/index.mjs --target ../my-project --platform cursor
+node tools/vibe-doctor/index.mjs ../my-project
+```
+
+`--with-runtime` 只会在目标项目的 `.vibecoding/runtime-installed.json` 写入 opt-in 元数据，不会把 `tools/vibe-runtime/` 或 `tools/vibe-doctor/` 复制进业务项目。
+运行 runtime / doctor 时，仍然应从 Vibecoding kit 源仓库或打包后的 CLI 分发位置调用，并把业务项目路径作为参数传入。
+
+安装会生成 `.vibecoding/config.json`，供后续生命周期命令使用：
+
+```bash
+node bin/vibe.mjs update --root ../my-project --dry-run
+node bin/vibe.mjs repair --root ../my-project --dry-run
+node bin/vibe.mjs uninstall --root ../my-project --dry-run
+```
+
+这些命令默认只输出计划；传入 `--confirm` 或 `--yes` 才会写入。`uninstall` 删除 managed block 和 `.vibecoding/`，但保留 `.vibecoding-state/`。
+
+## 单平台安装结果
+
+不同平台只生成对应入口和 adapter：
+
+- `--platform claude`：生成 `CLAUDE.md`，安装 `.vibecoding/adapters/claude/`。
+- `--platform cursor`：生成 `AGENTS.md`，安装 `.vibecoding/adapters/cursor/`。
+- `--platform codex`：生成 `AGENTS.md`，安装 `.vibecoding/adapters/codex/`。
+- `--platform opencode`：安装 `.vibecoding/adapters/opencode/`，不新增根入口文件。
+- `--platform pi`：安装 `.vibecoding/adapters/pi/`，不新增根入口文件。
+- `--platform all`：生成 `CLAUDE.md` 和 `AGENTS.md`，安装五个平台 adapter。
+
+Cursor 和 Codex 共用 `AGENTS.md` 入口文件。OpenCode 和 Pi 通过 adapter bootstrap contract 暴露 `.vibecoding/skills/`，不会把 hook 变成执行器。
+
+## 参数
+
+- `--target`：目标项目目录。使用 `node tools/vibe-init/index.mjs` 时必填；使用 `node bin/vibe.mjs init` 时默认是当前目录。
+- `--platform`：目标平台，支持 `claude`、`codex`、`cursor`、`opencode`、`pi`、`all`、`auto`，默认 `all`。`auto` 根据目标项目已有 `CLAUDE.md` / `AGENTS.md` 保守推断平台。
+- `--with-docs`：把 `docs/` 和 `examples/` 安装到 `.vibecoding/`。
+- `--with-runtime`：在 `.vibecoding/runtime-installed.json` 写入 Stage 55 installed runtime opt-in manifest。它只声明边界和建议调用方式，不会向业务项目安装本地 `tools/` 执行入口。
+- `--dry-run`：只预览，不写入文件。
+- `--check`：只检查目标项目当前接入状态，不写入文件。
+- `--merge`：已有入口文件的安全合并模式，支持 `preview`、`append`、`replace`、`manual`，默认 `manual`。
+- `--merge-preview`：`--merge=preview` 的兼容别名。
+- `--yes`：非交互确认。默认 merge mode 下等同于 `--merge=append`。
+- `--help`：显示帮助。
+
+## 覆盖策略
+
+入口文件使用 managed block 管理 Vibecoding 内容：
+
+```markdown
+<!-- vibecoding:start version=0.2.0 -->
+...
+<!-- vibecoding:end -->
+```
+
+默认策略：
+
+- 入口文件不存在：创建完整模板，模板自带 managed block。
+- 入口文件存在且已有 managed block：只替换 managed block 内的 Vibecoding 内容。
+- 入口文件存在但没有 managed block：默认 `manual`，不写入用户文件。
+- 显式 `--merge=append`：在文件末尾追加一个 managed block，不删除用户原内容。
+- 显式 `--merge=replace`：只替换已有 managed block；没有 block 时报告 conflict，不写入。
+- `--merge=preview` / `--merge-preview`：只输出可复制 managed block，不写入。
+
+最小合并方式：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform auto --merge=preview
+```
+
+然后：
+
+- 如果只想手动合并，从输出中复制对应 `managed block preview` 到现有入口文件。
+- 如果接受自动追加 managed block，运行 `node bin/vibe.mjs init --target ../my-project --platform auto --merge=append`。
+- 如果入口文件已有旧 managed block，运行默认安装或 `--merge=replace` 会只替换 block，不覆盖用户 block 外内容。
+
+合并后重新运行：
+
+```bash
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+兼容调用：
+
+```bash
+node tools/vibe-doctor/index.mjs ../my-project
+```
+
+如果入口文件未合并，doctor 会输出 `passed with warnings`，提示需要手动接入 Vibecoding 入口。
+
+如果安装了 `--with-runtime` 生成的 `.vibecoding/runtime-installed.json`，doctor 还会校验 Stage 55 manifest：
+
+- 只能声明 installed project 的 opt-in 元数据。
+- 不能声称业务项目本地存在 `tools/vibe-runtime/` 或 `tools/vibe-doctor/` 执行入口。
+- 建议命令必须把业务项目作为 `\<project-root\>` 参数，交给外部 Vibecoding kit 源仓库或打包 CLI 调用。
+
+## 安装后验收
+
+安装完成后，在源仓库或任意 Node 环境运行：
+
+```bash
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+如果目标项目完整，应看到：
+
+```text
+Result: passed
+```
+
+## 相关文档
+
+- `README.md`：快速安装、诊断和第一阶段边界。
+- `tools/vibe-doctor/README.md`：安装后诊断说明。
+- `tools/vibe-lifecycle/README.md`：update / repair / uninstall 生命周期说明。
+- `docs/acceptance-checklist.md`：固定验收命令序列。
+- `docs/release-guide.md`：发布包边界和发布前检查。
+
+## 第一阶段边界
+
+当前工具不做：
+
+- 覆盖用户非 managed 内容。
+- 在没有 `--merge=append` 或 `--yes` 时自动追加到已有无 block 入口文件。
+- 平台真实 runtime 验证。
+- MCP 安装。
+- memory 或 codebase index 初始化。

package/tools/vibe-init/index.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './init-cli-args.mjs';
+import {
+  entryFileMergePlan,
+  managedBlocks,
+  normalizedEntryTemplateText,
+} from './init-entry-merge-model.mjs';
+import {
+  installConfigManifest,
+  runtimeInstallManifest,
+} from './init-install-manifest-model.mjs';
+import {
+  entryFilesForPlatform,
+  selectedPlatforms,
+} from './init-platform-model.mjs';
+import {
+  printCheck,
+  printMergePreview,
+  printSummary,
+} from './init-presentation.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const kitDirectoryName = '.vibecoding';
+const runtimeManifestFileName = 'runtime-installed.json';
+const installConfigFileName = 'config.json';
+const managedBlockStart = '<!-- vibecoding:start version=0.2.0 -->';
+const managedBlockEnd = '<!-- vibecoding:end -->';
+
+function usage() {
+  return `Vibecoding Kit Init
+
+Usage:
+  node tools/vibe-init/index.mjs --target <path> [--platform claude|codex|cursor|opencode|pi|all|auto] [--automation-profile vibe-guided] [--with-docs] [--with-runtime] [--dry-run] [--check] [--merge=preview|append|replace|manual] [--yes]
+
+Options:
+  --target         Target project directory. Required.
+  --platform       Platform adapter to install. Default: all. Use auto to infer from existing entry files.
+  --automation-profile  Installed entry behavior profile. Default: vibe-guided. The legacy value default is accepted as an alias; maintainer-only compatibility profiles are documented in docs/maintainer-guide.md.
+  --with-docs      Also install docs/ and examples/ under .vibecoding/.
+  --with-runtime   Install runtime opt-in manifest only. It does not create .vibecoding-state/ or enable hooks, daemon, MCP, or automatic runtime actions.
+  --dry-run        Preview actions without writing files.
+  --check          Check target readiness without writing files.
+  --merge          Entry file merge mode for existing CLAUDE.md / AGENTS.md. Default: manual.
+                   preview prints managed block snippets; append appends a block when missing; replace only replaces an existing block; manual never writes existing entry files.
+  --merge-preview  Alias for --merge=preview.
+  --yes            Non-interactive consent. With default merge mode, treats existing entry files as --merge=append.
+  --help           Show this help.
+`;
+}
+
+function toNative(root, relativePath) {
+  return path.join(root, ...relativePath.split('/'));
+}
+
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+function ensureDirectory(directory, dryRun, actions) {
+  if (exists(directory)) return;
+
+  actions.push({ type: 'mkdir', target: directory });
+
+  if (!dryRun) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+}
+
+function listFilesRecursive(directory) {
+  const files = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const absolute = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(absolute));
+    } else if (entry.isFile()) {
+      files.push(absolute);
+    }
+  }
+
+  return files;
+}
+
+function copyFileNoOverwrite(source, target, dryRun, actions) {
+  if (exists(target)) {
+    actions.push({ type: 'skip', target, reason: 'exists' });
+    return;
+  }
+
+  actions.push({ type: 'copy', source, target });
+
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+  }
+}
+
+function copyDirectoryNoOverwrite(sourceDirectory, targetDirectory, dryRun, actions) {
+  ensureDirectory(targetDirectory, dryRun, actions);
+
+  for (const source of listFilesRecursive(sourceDirectory)) {
+    const relative = path.relative(sourceDirectory, source);
+    const target = path.join(targetDirectory, relative);
+    copyFileNoOverwrite(source, target, dryRun, actions);
+  }
+}
+
+function detectPlatform(target) {
+  const hasClaude = exists(toNative(target, 'CLAUDE.md'));
+  const hasAgents = exists(toNative(target, 'AGENTS.md'));
+
+  if (hasClaude && hasAgents) return 'all';
+  if (hasClaude) return 'claude';
+  if (hasAgents) return 'cursor';
+  return 'all';
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function writeText(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents, 'utf8');
+}
+
+function normalizedTemplateText(file) {
+  return normalizedEntryTemplateText(readText(templatePathForEntry(file)), {
+    managedBlockStart,
+    managedBlockEnd,
+  });
+}
+
+function templatePathForEntry(file) {
+  return toNative(repoRoot, `templates/${file}`);
+}
+
+function entryMarkers(file) {
+  if (file === 'CLAUDE.md') return ['Vibecoding Kit', '.vibecoding/skills/', 'using-vibecoding'];
+  if (file === 'AGENTS.md') return ['Vibecoding Kit', '.vibecoding/skills/'];
+  return [];
+}
+
+function checkTarget(options) {
+  const checks = [];
+  const targetExists = exists(options.target);
+  const kitRoot = installedPath(options.target);
+
+  checks.push({ status: targetExists ? 'ok' : 'warn', label: targetExists ? 'target exists' : 'target missing', detail: targetExists ? options.target : 'It will be created during install.' });
+  checks.push({ status: exists(kitRoot) ? 'ok' : 'info', label: exists(kitRoot) ? '.vibecoding exists' : '.vibecoding not installed yet', detail: exists(kitRoot) ? kitRoot : 'Install will create it.' });
+
+  for (const file of entryFilesForPlatform(options.platform)) {
+    const targetFile = toNative(options.target, file);
+    if (!exists(targetFile)) {
+      checks.push({ status: 'ok', label: `${file} available`, detail: 'Template can be copied without overwrite.' });
+      continue;
+    }
+
+    const text = readText(targetFile);
+    const missing = entryMarkers(file).filter((marker) => !text.includes(marker));
+    const blockCount = managedBlocks(text).length;
+    const blockDetail = blockCount === 1 ? 'managed block present' : blockCount > 1 ? `multiple managed blocks (${blockCount})` : 'managed block missing';
+    checks.push({
+      status: missing.length === 0 && blockCount <= 1 ? 'ok' : 'warn',
+      label: `${file} exists`,
+      detail: missing.length === 0 ? `Already references Vibecoding Kit; ${blockDetail}.` : `Needs merge. Missing marker(s): ${missing.join(', ')}; ${blockDetail}.`,
+    });
+  }
+
+  return checks;
+}
+
+function installedPath(target, relativePath = '') {
+  if (!relativePath) return toNative(target, kitDirectoryName);
+  return toNative(target, `${kitDirectoryName}/${relativePath}`);
+}
+
+function installEntryFile(file, options, actions) {
+  const source = templatePathForEntry(file);
+  const target = toNative(options.target, file);
+
+  if (!exists(target)) {
+    copyFileNoOverwrite(source, target, options.dryRun, actions);
+    return;
+  }
+
+  const plan = entryFileMergePlan({
+    currentText: readText(target),
+    template: normalizedTemplateText(file),
+    merge: options.merge,
+  });
+  const action = { type: plan.type, target };
+  if (plan.reason) action.reason = plan.reason;
+  if (plan.contents) action.contents = plan.contents;
+  actions.push(action);
+  if (plan.write && !options.dryRun) writeText(target, plan.contents);
+}
+
+function planCoreKitCopies(options, actions) {
+  const target = options.target;
+  const kitRoot = installedPath(target);
+
+  ensureDirectory(target, options.dryRun, actions);
+  ensureDirectory(kitRoot, options.dryRun, actions);
+
+  copyDirectoryNoOverwrite(
+    toNative(repoRoot, 'skills'),
+    installedPath(target, 'skills'),
+    options.dryRun,
+    actions,
+  );
+
+  copyDirectoryNoOverwrite(
+    toNative(repoRoot, 'hooks'),
+    installedPath(target, 'hooks'),
+    options.dryRun,
+    actions,
+  );
+
+  copyFileNoOverwrite(
+    toNative(repoRoot, 'templates/VIBE-CODING.md'),
+    installedPath(target, 'VIBE-CODING.md'),
+    options.dryRun,
+    actions,
+  );
+}
+
+function planPlatformAdapterCopies(options, actions) {
+  for (const platform of selectedPlatforms(options.platform)) {
+    copyDirectoryNoOverwrite(
+      toNative(repoRoot, `adapters/${platform}`),
+      installedPath(options.target, `adapters/${platform}`),
+      options.dryRun,
+      actions,
+    );
+  }
+}
+
+function planOptionalDocumentationCopies(options, actions) {
+  if (!options.withDocs) return;
+
+  copyDirectoryNoOverwrite(
+    toNative(repoRoot, 'docs'),
+    installedPath(options.target, 'docs'),
+    options.dryRun,
+    actions,
+  );
+
+  copyDirectoryNoOverwrite(
+    toNative(repoRoot, 'examples'),
+    installedPath(options.target, 'examples'),
+    options.dryRun,
+    actions,
+  );
+}
+
+function planRuntimeManifestWrite(options, actions) {
+  if (!options.withRuntime) return;
+
+  const runtimeManifestPath = installedPath(options.target, runtimeManifestFileName);
+  if (exists(runtimeManifestPath)) {
+    actions.push({ type: 'skip', target: runtimeManifestPath, reason: 'exists' });
+    return;
+  }
+
+  actions.push({
+    type: 'write',
+    target: runtimeManifestPath,
+    contents: runtimeInstallManifest({ kitDirectoryName, options, selectedPlatforms }),
+  });
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(runtimeManifestPath), { recursive: true });
+    fs.writeFileSync(
+      runtimeManifestPath,
+      runtimeInstallManifest({ kitDirectoryName, options, selectedPlatforms }),
+      'utf8',
+    );
+  }
+}
+
+function planEntryFileInstalls(options, actions) {
+  if (options.platform === 'all' || options.platform === 'claude') {
+    installEntryFile('CLAUDE.md', options, actions);
+  }
+
+  if (options.platform === 'all' || options.platform === 'cursor' || options.platform === 'codex') {
+    installEntryFile('AGENTS.md', options, actions);
+  }
+}
+
+function initInstallConfigContents(options, actions) {
+  return installConfigManifest({
+    entryFilesForPlatform,
+    exists,
+    installedPath,
+    kitDirectoryName,
+    managedBlocks,
+    options,
+    readText,
+    runtimeManifestFileName,
+    selectedPlatforms,
+    toNative,
+    actions,
+  });
+}
+
+function planInstallConfigWrite(options, actions) {
+  const installConfigPath = installedPath(options.target, installConfigFileName);
+  actions.push({ type: 'write', target: installConfigPath, contents: initInstallConfigContents(options, actions) });
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(installConfigPath), { recursive: true });
+    fs.writeFileSync(installConfigPath, initInstallConfigContents(options, actions), 'utf8');
+  }
+}
+
+function plannedCopies(options) {
+  const actions = [];
+
+  planCoreKitCopies(options, actions);
+  planPlatformAdapterCopies(options, actions);
+  planOptionalDocumentationCopies(options, actions);
+  planRuntimeManifestWrite(options, actions);
+  planEntryFileInstalls(options, actions);
+  planInstallConfigWrite(options, actions);
+
+  return actions;
+}
+
+function runInit(argv) {
+  const options = parseArgs(argv, { resolvePath: path.resolve });
+
+  if (options.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  if (options.platform === 'auto') {
+    const detected = detectPlatform(options.target);
+    options.platform = detected;
+  }
+
+  if (options.check) {
+    printCheck({ checkTarget, options, repoRoot, toNative });
+    process.exit(0);
+  }
+
+  if (options.mergePreview) {
+    printMergePreview({ entryFilesForPlatform, exists, normalizedTemplateText, options, toNative });
+    process.exit(0);
+  }
+
+  const actions = plannedCopies(options);
+  printSummary({ actions, entryFilesForPlatform, kitDirectoryName, options, repoRoot, runtimeManifestFileName, toNative });
+}
+
+try {
+  runInit(process.argv.slice(2));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('');
+  console.error(usage());
+  process.exit(1);
+}

package/tools/vibe-init/init-cli-args.mjs

@@ -0,0 +1,100 @@
+const platforms = new Set(['claude', 'codex', 'cursor', 'opencode', 'pi', 'all', 'auto']);
+const automationProfiles = new Set(['vibe-guided', 'default', 'superpowers-parity']);
+const mergeModes = new Set(['preview', 'append', 'replace', 'manual']);
+
+export const initCliArgsContractSync = Object.freeze({
+  runtime_check_owner: 'tools/vibe-runtime-check/index.mjs',
+  release_check_owner: 'tools/vibe-release-check',
+});
+
+function defaultOptions() {
+  return {
+    target: null,
+    platform: 'all',
+    automationProfile: 'vibe-guided',
+    withDocs: false,
+    withRuntime: false,
+    dryRun: false,
+    check: false,
+    mergePreview: false,
+    merge: 'manual',
+    yes: false,
+    help: false,
+  };
+}
+
+function takeValue(argv, index, name) {
+  const value = argv[index + 1];
+  if (!value) throw new Error(`${name} requires a value`);
+  return value;
+}
+
+function applyFlagOption(options, arg) {
+  if (arg === '--help' || arg === '-h') options.help = true;
+  else if (arg === '--dry-run') options.dryRun = true;
+  else if (arg === '--check') options.check = true;
+  else if (arg === '--merge-preview') {
+    options.mergePreview = true;
+    options.merge = 'preview';
+  } else if (arg === '--yes' || arg === '-y') options.yes = true;
+  else if (arg === '--with-docs') options.withDocs = true;
+  else if (arg === '--with-runtime') options.withRuntime = true;
+  else return false;
+  return true;
+}
+
+function applyInlineValueOption(options, arg) {
+  if (arg.startsWith('--merge=')) options.merge = arg.slice('--merge='.length);
+  else if (arg.startsWith('--target=')) options.target = arg.slice('--target='.length);
+  else if (arg.startsWith('--platform=')) options.platform = arg.slice('--platform='.length);
+  else if (arg.startsWith('--automation-profile=')) options.automationProfile = arg.slice('--automation-profile='.length);
+  else return false;
+  return true;
+}
+
+function applySeparatedValueOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--merge') options.merge = takeValue(argv, index, '--merge');
+  else if (arg === '--automation-profile') options.automationProfile = takeValue(argv, index, '--automation-profile');
+  else if (arg === '--target') options.target = takeValue(argv, index, '--target');
+  else if (arg === '--platform') options.platform = takeValue(argv, index, '--platform');
+  else return 0;
+  return 1;
+}
+
+function validateOptions(options) {
+  if (options.help) return;
+  if (!options.target) throw new Error('--target is required.');
+  if (!platforms.has(options.platform)) throw new Error(`Unsupported --platform: ${options.platform}`);
+  if (!automationProfiles.has(options.automationProfile)) throw new Error(`Unsupported --automation-profile: ${options.automationProfile}`);
+  if (!mergeModes.has(options.merge)) throw new Error(`Unsupported --merge: ${options.merge}`);
+}
+
+function normalizeOptions(options, resolvePath) {
+  if (options.help) return options;
+  if (options.yes && options.merge === 'manual') options.merge = 'append';
+  if (options.automationProfile === 'default') options.automationProfile = 'vibe-guided';
+  options.mergePreview = options.merge === 'preview';
+  options.target = resolvePath(options.target);
+  return options;
+}
+
+export function parseArgs(argv, { resolvePath } = {}) {
+  const options = defaultOptions();
+  const resolveTarget = resolvePath || ((value) => value);
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (applyFlagOption(options, arg)) continue;
+    if (applyInlineValueOption(options, arg)) continue;
+    const consumed = applySeparatedValueOption(options, argv, index);
+    if (consumed) {
+      index += consumed;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  validateOptions(options);
+  return normalizeOptions(options, resolveTarget);
+}