@athsra/cli 0.1.0 → 1.0.0

package/src/commands/mcp.ts

@@ -0,0 +1,595 @@
+/**
+ * mcp.ts — `athsra mcp` 명령 (Model Context Protocol stdio server).
+ *
+ * Phase 2.7 (2026-05-26): Claude Code / 다른 MCP client 가 athsra envelope 을
+ * 도구로 직접 사용. AI agent 가 사용자 prompt 없이 envelope 메타데이터 조회 +
+ * manifest 검증 가능.
+ *
+ * 등록 (Claude Code `.mcp.json` 또는 `~/.claude/settings.json`):
+ *   "mcpServers": {
+ *     "athsra": { "command": "athsra", "args": ["mcp"] }
+ *   }
+ *
+ * Tools (v0 — read-only, 항상 노출):
+ *   - athsra_list_projects     — 모든 envelope 이름 + RBAC 적용된 접근 권한
+ *   - athsra_get_project_keys  — 특정 envelope 의 키 목록 (값 X — 보안)
+ *   - athsra_show_manifest     — sibling worker manifest (.athsra/secrets.json)
+ *   - athsra_validate_manifest — envelope vs manifest diff (onboarding gap)
+ *
+ * Tools (v1 — write, `ATHSRA_MCP_WRITE=1` env opt-in 시에만 노출):
+ *   - athsra_set_secret        — envelope KEY=value 추가/수정 (destructive)
+ *   - athsra_unset_secret      — envelope KEY 제거 (destructive)
+ *   - athsra_manifest_init     — sibling manifest 생성 (file write)
+ *   - athsra_manifest_modify   — manifest add/remove keys
+ *
+ * 정공법: McpServer high-level 의 zod generic 이 tsc inference OOM 유발 (SIGABRT).
+ * low-level `Server` + manual `setRequestHandler` 로 dispatch — JSON Schema literal,
+ * zod 의존성 제거. 단순 + 통제 + 메모리 안전.
+ *
+ * 보안:
+ *   - secret 값 자체는 노출 안 함 (Phase 2.7 v0). AI 가 값을 직접 보지 않음.
+ *   - write 동작 (set/unset/adopt) 은 Phase 2.7.1 에서 명시적 permission 추가.
+ *   - stdio MCP 는 local-only — process.stdout 으로 protocol JSON 만 통신.
+ *     모든 로그/에러는 console.error (stderr) 로.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { inferAdoptContext, type WrangerWorker } from '../lib/adopt-context.ts';
+import { loadAuthContext } from '../lib/auth-context.ts';
+import { readPlain, writePlain } from '../lib/envelope.ts';
+import {
+  applyManifest,
+  createManifest,
+  loadManifest,
+  saveManifest,
+} from '../lib/secrets-manifest.ts';
+
+const USAGE = [
+  'usage: athsra mcp [--help]',
+  '',
+  'Model Context Protocol stdio server — Claude Code / MCP client 가 envelope',
+  '을 도구로 사용. stdio JSON-RPC. 다른 출력 X (logs → stderr).',
+  '',
+  'Claude Code 등록 예시 (~/.claude/settings.json or .mcp.json):',
+  '  "mcpServers": {',
+  '    "athsra": { "command": "athsra", "args": ["mcp"] }',
+  '  }',
+  '',
+  'Tools (v0 read-only):',
+  '  athsra_list_projects     — envelope 이름 목록',
+  '  athsra_get_project_keys  — envelope 키 목록 (값 X)',
+  '  athsra_show_manifest     — sibling worker manifest 조회',
+  '  athsra_validate_manifest — envelope vs manifest diff',
+].join('\n');
+
+const VERSION = '1.0.0';
+
+/** Write tools opt-in via env var. 기본 false — secret 변경은 명시적 ack 필요. */
+const WRITE_ENABLED = process.env.ATHSRA_MCP_WRITE === '1';
+
+interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: { destructiveHint?: boolean; readOnlyHint?: boolean };
+}
+
+const READ_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_list_projects',
+    description:
+      'List all envelope (project) names accessible to the current athsra user. ' +
+      'Requires prior `athsra login`. Returns string array of project names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        detail: {
+          type: 'boolean',
+          description: 'If true, return extended rows (versions, last update, etc.).',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_get_project_keys',
+    description:
+      'Return the list of secret keys stored in a given envelope. ' +
+      'Values are NOT returned for security — only key names. ' +
+      'Use `athsra run <project> -- <cmd>` (outside MCP) to inject values into a process.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1, description: 'Envelope name.' },
+      },
+      required: ['project'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_show_manifest',
+    description:
+      'Read the secrets manifest (.athsra/secrets.json) for a sibling worker. ' +
+      'The manifest enumerates the keys that opt-in to wrangler secrets sync ' +
+      '(Phase 2.6 default-deny / Option γ). Resolves worker by `cwd` argument; ' +
+      'falls back to process cwd if absent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Path inside the sibling repo (default: process cwd).' },
+        worker: {
+          type: 'string',
+          description: 'CF worker name if multiple wrangler.jsonc are present.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_validate_manifest',
+    description:
+      'Compare a sibling worker manifest against the envelope to identify onboarding gaps. ' +
+      'Returns three sets: `allowed` (manifest ∩ envelope — will sync), ' +
+      '`missing` (manifest \\ envelope — onboarding gap, sibling needs `athsra set`), ' +
+      '`excluded` (envelope \\ manifest — intentionally not synced).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+      },
+      required: ['project'],
+      additionalProperties: false,
+    },
+  },
+];
+
+const WRITE_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_set_secret',
+    description:
+      'Add or overwrite a secret key=value in an envelope (E2EE encrypted with master pw). ' +
+      'DESTRUCTIVE — invoke only with explicit user intent. Value is NEVER echoed back. ' +
+      'Use this to onboard new keys identified by athsra_validate_manifest missing list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        key: { type: 'string', minLength: 1, pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+        value: { type: 'string', description: 'Secret value (not logged, not echoed).' },
+      },
+      required: ['project', 'key', 'value'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_unset_secret',
+    description:
+      'Remove a secret key from an envelope. DESTRUCTIVE. Value is irrecoverable unless ' +
+      'a prior version is restored via `athsra rollback`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        key: { type: 'string', minLength: 1 },
+      },
+      required: ['project', 'key'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_manifest_init',
+    description:
+      'Create a new sibling worker manifest (.athsra/secrets.json) with the given keys. ' +
+      'Fails if manifest already exists (use `athsra_manifest_modify` for updates). ' +
+      'Honors host repo biome.json indent style (Phase 2.6.1).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+        keys: {
+          type: 'array',
+          items: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+          minItems: 1,
+        },
+      },
+      required: ['keys'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_manifest_modify',
+    description:
+      "Add or remove keys from an existing sibling manifest. `op` = 'add' or 'remove'.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', enum: ['add', 'remove'] },
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+        keys: {
+          type: 'array',
+          items: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+          minItems: 1,
+        },
+      },
+      required: ['op', 'keys'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+];
+
+const TOOLS: ToolDef[] = WRITE_ENABLED ? [...READ_TOOLS, ...WRITE_TOOLS] : READ_TOOLS;
+
+const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS.map((t) => t.name));
+
+/**
+ * MCP `CallToolResult` 의 subset — content + isError. SDK 의 zod-derived 타입을
+ * 직접 import 하면 tsc inference OOM (SIGABRT) 가 발생하므로 manual 정의.
+ * MCP spec 2025-06-18 의 CallToolResult 와 호환.
+ */
+interface ToolTextResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+function jsonOk(data: unknown): ToolTextResult {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+function jsonError(message: string): ToolTextResult {
+  return { isError: true, content: [{ type: 'text', text: `error: ${message}` }] };
+}
+
+function pickWorker(
+  workers: WrangerWorker[],
+  explicit?: string,
+): WrangerWorker | { error: string } {
+  if (explicit) {
+    const found = workers.find((w) => w.name === explicit);
+    if (found) return found;
+    const names = workers.map((w) => w.name).join(', ') || '(none)';
+    return { error: `worker '${explicit}' not found. available: ${names}` };
+  }
+  if (workers.length === 0) {
+    return { error: 'no wrangler.jsonc found in cwd' };
+  }
+  if (workers.length === 1) {
+    const [only] = workers;
+    if (!only) return { error: 'no wrangler.jsonc found' };
+    return only;
+  }
+  return {
+    error: `multiple workers found. specify worker: ${workers.map((w) => w.name).join(', ')}`,
+  };
+}
+
+function readString(args: Record<string, unknown> | undefined, key: string): string | undefined {
+  const v = args?.[key];
+  return typeof v === 'string' ? v : undefined;
+}
+
+function readBoolean(args: Record<string, unknown> | undefined, key: string): boolean | undefined {
+  const v = args?.[key];
+  return typeof v === 'boolean' ? v : undefined;
+}
+
+async function handleListProjects(args: Record<string, unknown> | undefined): Promise<ToolTextResult> {
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return jsonError('athsra not logged in — run `athsra login` first');
+  }
+  const detail = readBoolean(args, 'detail');
+  if (detail) {
+    const rows = await ctx.client.listProjectsExtended();
+    return jsonOk({ projects: rows });
+  }
+  const names = await ctx.client.listProjects();
+  return jsonOk({ projects: names, count: names.length });
+}
+
+async function handleGetProjectKeys(args: Record<string, unknown> | undefined): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  if (!project) return jsonError('missing required arg: project');
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return jsonError('athsra not logged in — run `athsra login` first');
+  }
+  const env = await readPlain(ctx, project);
+  if (!env) {
+    return jsonError(`envelope '${project}' not found`);
+  }
+  const keys = Object.entries(env)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([k]) => k)
+    .sort();
+  return jsonOk({ project, keys, count: keys.length });
+}
+
+function handleShowManifest(args: Record<string, unknown> | undefined): ToolTextResult {
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) {
+    return jsonError(picked.error);
+  }
+  const loaded = loadManifest({ workerCwd: picked.cwd });
+  if (loaded.error) {
+    return jsonError(`manifest invalid (${loaded.path}): ${loaded.error}`);
+  }
+  if (!loaded.manifest) {
+    return jsonError(
+      `no manifest at ${loaded.path}. create via: athsra manifest init --keys=K1,K2`,
+    );
+  }
+  return jsonOk({
+    worker: picked.name,
+    manifestPath: loaded.path,
+    secrets: loaded.manifest.secrets,
+    count: loaded.manifest.secrets.length,
+  });
+}
+
+async function handleValidateManifest(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  if (!project) return jsonError('missing required arg: project');
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return jsonError('athsra not logged in — run `athsra login` first');
+  }
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) {
+    return jsonError(picked.error);
+  }
+  const loaded = loadManifest({ workerCwd: picked.cwd });
+  if (loaded.error) {
+    return jsonError(`manifest invalid (${loaded.path}): ${loaded.error}`);
+  }
+  if (!loaded.manifest) {
+    return jsonError(`no manifest at ${loaded.path}`);
+  }
+  const env = await readPlain(ctx, project);
+  if (!env) {
+    return jsonError(`envelope '${project}' not found`);
+  }
+  const envelopeKeys = Object.entries(env)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([k]) => k);
+  const applied = applyManifest(loaded.manifest, envelopeKeys);
+  return jsonOk({
+    worker: picked.name,
+    project,
+    manifestPath: loaded.path,
+    allowed: applied.allowed,
+    missing: applied.missing,
+    excluded: applied.excluded,
+    counts: {
+      allowed: applied.allowed.length,
+      missing: applied.missing.length,
+      excluded: applied.excluded.length,
+    },
+  });
+}
+
+function readStringArray(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string[] | undefined {
+  const v = args?.[key];
+  if (!Array.isArray(v)) return undefined;
+  const out: string[] = [];
+  for (const item of v) {
+    if (typeof item !== 'string') return undefined;
+    out.push(item);
+  }
+  return out;
+}
+
+async function handleSetSecret(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  const key = readString(args, 'key');
+  const value = readString(args, 'value');
+  if (!project || !key || value === undefined) {
+    return jsonError('missing required args: project, key, value');
+  }
+  const ctx = await loadAuthContext();
+  if (!ctx) return jsonError('athsra not logged in — run `athsra login` first');
+  if (ctx.kind !== 'user') {
+    return jsonError('service token cannot write — user token (master pw) required');
+  }
+  const existing = (await readPlain(ctx, project)) ?? {};
+  const updated: Record<string, string> = { ...existing, [key]: value };
+  await writePlain(ctx, project, updated);
+  // 보안: value 는 응답에 절대 포함 X — 키 이름만 confirm
+  return jsonOk({ project, key, action: 'set', total_keys: Object.keys(updated).length });
+}
+
+async function handleUnsetSecret(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  const key = readString(args, 'key');
+  if (!project || !key) return jsonError('missing required args: project, key');
+  const ctx = await loadAuthContext();
+  if (!ctx) return jsonError('athsra not logged in — run `athsra login` first');
+  if (ctx.kind !== 'user') {
+    return jsonError('service token cannot write — user token (master pw) required');
+  }
+  const existing = await readPlain(ctx, project);
+  if (!existing) return jsonError(`envelope '${project}' not found`);
+  if (!(key in existing)) {
+    return jsonOk({ project, key, action: 'noop', reason: 'key not present' });
+  }
+  const updated: Record<string, string> = { ...existing };
+  delete updated[key];
+  await writePlain(ctx, project, updated);
+  return jsonOk({ project, key, action: 'unset', total_keys: Object.keys(updated).length });
+}
+
+function handleManifestInit(args: Record<string, unknown> | undefined): ToolTextResult {
+  const keys = readStringArray(args, 'keys');
+  if (!keys || keys.length === 0) return jsonError('missing required arg: keys (non-empty array)');
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) return jsonError(picked.error);
+  const existing = loadManifest({ workerCwd: picked.cwd });
+  if (existing.manifest) {
+    return jsonError(`manifest already exists at ${existing.path} — use athsra_manifest_modify`);
+  }
+  if (existing.error) {
+    return jsonError(`manifest invalid (${existing.path}): ${existing.error}`);
+  }
+  try {
+    const manifest = createManifest(keys);
+    const saved = saveManifest(picked.cwd, manifest);
+    return jsonOk({
+      worker: picked.name,
+      manifestPath: saved,
+      secrets: manifest.secrets,
+      count: manifest.secrets.length,
+    });
+  } catch (err) {
+    return jsonError(`createManifest failed: ${(err as Error).message}`);
+  }
+}
+
+function handleManifestModify(args: Record<string, unknown> | undefined): ToolTextResult {
+  const op = readString(args, 'op');
+  const keys = readStringArray(args, 'keys');
+  if (!op || (op !== 'add' && op !== 'remove')) {
+    return jsonError("invalid 'op' — must be 'add' or 'remove'");
+  }
+  if (!keys || keys.length === 0) return jsonError('missing required arg: keys (non-empty array)');
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) return jsonError(picked.error);
+  const existing = loadManifest({ workerCwd: picked.cwd });
+  if (existing.error) {
+    return jsonError(`manifest invalid (${existing.path}): ${existing.error}`);
+  }
+  if (!existing.manifest) {
+    return jsonError(`no manifest at ${existing.path} — use athsra_manifest_init`);
+  }
+  const set = new Set(existing.manifest.secrets);
+  const before = set.size;
+  for (const k of keys) {
+    if (op === 'add') set.add(k);
+    else set.delete(k);
+  }
+  if (set.size === before) {
+    return jsonOk({ worker: picked.name, op, action: 'noop', secrets: existing.manifest.secrets });
+  }
+  try {
+    const manifest = createManifest(Array.from(set));
+    const saved = saveManifest(picked.cwd, manifest);
+    return jsonOk({
+      worker: picked.name,
+      op,
+      manifestPath: saved,
+      secrets: manifest.secrets,
+      count: manifest.secrets.length,
+    });
+  } catch (err) {
+    return jsonError(`createManifest failed: ${(err as Error).message}`);
+  }
+}
+
+async function dispatch(
+  name: string,
+  args: Record<string, unknown> | undefined,
+  writeEnabled: boolean = WRITE_ENABLED,
+): Promise<ToolTextResult> {
+  if (WRITE_TOOL_NAMES.has(name) && !writeEnabled) {
+    return jsonError(
+      `write tool '${name}' disabled. Set ATHSRA_MCP_WRITE=1 in the MCP server env to enable.`,
+    );
+  }
+  switch (name) {
+    case 'athsra_list_projects':
+      return handleListProjects(args);
+    case 'athsra_get_project_keys':
+      return handleGetProjectKeys(args);
+    case 'athsra_show_manifest':
+      return handleShowManifest(args);
+    case 'athsra_validate_manifest':
+      return handleValidateManifest(args);
+    case 'athsra_set_secret':
+      return handleSetSecret(args);
+    case 'athsra_unset_secret':
+      return handleUnsetSecret(args);
+    case 'athsra_manifest_init':
+      return handleManifestInit(args);
+    case 'athsra_manifest_modify':
+      return handleManifestModify(args);
+    default:
+      return jsonError(`unknown tool: ${name}`);
+  }
+}
+
+function buildServer(): Server {
+  const server = new Server(
+    { name: 'athsra', version: VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    return dispatch(name, args);
+  });
+
+  return server;
+}
+
+export async function mcpCmd(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.error(USAGE);
+    return 0;
+  }
+  // stdio MCP — all logs to stderr; stdout reserved for protocol JSON
+  console.error(`athsra MCP v${VERSION} starting on stdio…`);
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // server runs until transport closes (parent process exits)
+  return 0;
+}
+
+/** test helpers — buildServer + dispatch exposed for in-process MCP testing. */
+export const __test = {
+  buildServer,
+  dispatch,
+  TOOLS,
+  READ_TOOLS,
+  WRITE_TOOLS,
+  WRITE_ENABLED,
+};

package/src/commands/migrate-envelopes.ts

@@ -0,0 +1,113 @@
+import { migrateV1ToV2 } from '@athsra/crypto';
+import { loadAuthContext } from '../lib/auth-context.ts';
+
+const USAGE = [
+  'usage: athsra migrate-envelopes [--apply] [--include=p1,p2,...]',
+  '',
+  '모든 v1 envelope 를 v2 (DEK + master recipient) 로 일괄 마이그레이션.',
+  '  - default dry-run — read-only survey, 어떤 project 가 마이그레이션될지만 출력.',
+  '  - --apply        — 실제 PUT. 각 project 는 새 version 으로 기록 (versions 보존).',
+  '  - --include=...  — 특정 project 만 (쉼표 구분, 점진 적용용).',
+  '',
+  'service token 추가 전 사전 작업으로 권장 (자동 migrate 도 동작하지만 일괄 처리가 운영',
+  '가시성 ↑). 이미 v2 인 project 는 자동 skip — idempotent.',
+].join('\n');
+
+export async function migrateEnvelopesCmd(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const apply = args.includes('--apply');
+  let include: Set<string> | null = null;
+  for (const a of args) {
+    if (a.startsWith('--include=')) {
+      const list = a
+        .slice('--include='.length)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      include = new Set(list);
+    } else if (a.startsWith('-') && a !== '--apply') {
+      console.error(`Unknown flag: ${a}`);
+      console.error(USAGE);
+      return 2;
+    }
+  }
+
+  const ctx = await loadAuthContext();
+  if (!ctx) return 1;
+  if (ctx.kind !== 'user') {
+    console.error('athsra migrate-envelopes 는 user token (master pw) 가 필요합니다.');
+    return 1;
+  }
+  const { client, masterPw } = ctx;
+
+  const projects = (await client.listProjects()).sort();
+  const targets = include ? projects.filter((p) => include.has(p)) : projects;
+  if (include) {
+    const missing = [...include].filter((p) => !projects.includes(p));
+    if (missing.length > 0) {
+      console.error(`--include 의 일부 project 가 존재하지 않습니다: ${missing.join(', ')}`);
+      return 1;
+    }
+  }
+
+  console.log(`${apply ? 'APPLY' : 'DRY-RUN'} — migrate-envelopes, ${targets.length} projects\n`);
+
+  let v1Count = 0;
+  let v2Count = 0;
+  let migrated = 0;
+  let errored = 0;
+  const errors: string[] = [];
+
+  for (const project of targets) {
+    let env: Awaited<ReturnType<typeof client.getEnvelope>>;
+    try {
+      env = await client.getEnvelope(project);
+    } catch (err) {
+      errored++;
+      errors.push(`${project}: getEnvelope ${(err as Error).message}`);
+      console.log(`  ✗ ${project}: getEnvelope error — ${(err as Error).message}`);
+      continue;
+    }
+    if (!env) {
+      console.log(`  =  ${project}: envelope 없음 — skip`);
+      continue;
+    }
+    if (env.version === 2) {
+      v2Count++;
+      console.log(`  =  ${project}: already v2 — skip`);
+      continue;
+    }
+    v1Count++;
+    if (!apply) {
+      console.log(`  ○  ${project}: v1 → v2 (dry-run)`);
+      continue;
+    }
+    try {
+      const v2 = await migrateV1ToV2(env, masterPw);
+      await client.putEnvelope(project, v2);
+      migrated++;
+      console.log(`  ✏  ${project}: v1 → v2 (version ${v2.version_id.slice(0, 12)}…)`);
+    } catch (err) {
+      errored++;
+      errors.push(`${project}: ${(err as Error).message}`);
+      console.log(`  ✗ ${project}: migrate error — ${(err as Error).message}`);
+    }
+  }
+
+  console.log(
+    `\n요약: v1=${v1Count} v2=${v2Count} ${apply ? `migrated=${migrated}` : '(dry-run — 변경 없음)'} errored=${errored}`,
+  );
+  if (errored > 0) {
+    console.log('\n실패:');
+    for (const e of errors) console.log(`  ${e}`);
+    return 1;
+  }
+  if (!apply && v1Count > 0) {
+    console.log('\n적용: athsra migrate-envelopes --apply');
+  }
+  return 0;
+}