@athsra/cli 1.0.1 → 1.0.3

package/src/commands/mcp.ts

@@ -22,32 +22,42 @@
  *   - 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 의존성 제거. 단순 + 통제 + 메모리 안전.
+ * 2026-06-02 리팩토링: tool 정의(defs)·결과 헬퍼(result)·인자 파서(args)·핸들러(read/write)를
+ * lib/mcp-tools/ 로 추출. 이 파일은 orchestration (dispatch/buildServer/mcpCmd/__test) 만 유지.
+ *
+ * 정공법: 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 추가.
+ *   - write 동작 (set/unset/adopt) 은 ATHSRA_MCP_WRITE=1 opt-in.
  *   - 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 { READ_TOOLS, type ToolDef, WRITE_TOOLS } from '../lib/mcp-tools/defs.ts';
+import {
+  handleGetProjectKeys,
+  handleListProjects,
+  handleShowManifest,
+  handleValidateManifest,
+  handleWhoami,
+} from '../lib/mcp-tools/read.ts';
 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';
+  isAuthError,
+  jsonError,
+  notLoggedIn,
+  type ToolTextResult,
+} from '../lib/mcp-tools/result.ts';
 import {
-  applyManifest,
-  createManifest,
-  loadManifest,
-  saveManifest,
-} from '../lib/secrets-manifest.ts';
+  handleManifestInit,
+  handleManifestModify,
+  handleSetSecret,
+  handleUnsetSecret,
+} from '../lib/mcp-tools/write.ts';
 
 const USAGE = [
   'usage: athsra mcp [--help]',
@@ -60,11 +70,14 @@ const USAGE = [
   '    "athsra": { "command": "athsra", "args": ["mcp"] }',
   '  }',
   '',
-  'Tools (v0 read-only):',
+  'Tools (read-only, 항상 노출):',
+  '  athsra_whoami            — 인증 상태 + 신원 (미인증 시 `athsra login --sso` 안내). 온보딩 시 먼저 호출',
   '  athsra_list_projects     — envelope 이름 목록',
-  '  athsra_get_project_keys  — envelope 키 목록 (값 X)',
+  '  athsra_get_project_keys  — envelope 키 목록 (값 X — 값은 `athsra run` 으로 주입)',
   '  athsra_show_manifest     — sibling worker manifest 조회',
   '  athsra_validate_manifest — envelope vs manifest diff',
+  'Tools (write, ATHSRA_MCP_WRITE=1 opt-in):',
+  '  athsra_set_secret / athsra_unset_secret / athsra_manifest_init / athsra_manifest_modify',
 ].join('\n');
 
 const VERSION = '1.0.0';
@@ -72,454 +85,10 @@ 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,
@@ -530,33 +99,39 @@ async function dispatch(
       `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}`);
+  try {
+    switch (name) {
+      case 'athsra_whoami':
+        return await handleWhoami();
+      case 'athsra_list_projects':
+        return await handleListProjects(args);
+      case 'athsra_get_project_keys':
+        return await handleGetProjectKeys(args);
+      case 'athsra_show_manifest':
+        return handleShowManifest(args);
+      case 'athsra_validate_manifest':
+        return await handleValidateManifest(args);
+      case 'athsra_set_secret':
+        return await handleSetSecret(args);
+      case 'athsra_unset_secret':
+        return await handleUnsetSecret(args);
+      case 'athsra_manifest_init':
+        return handleManifestInit(args);
+      case 'athsra_manifest_modify':
+        return handleManifestModify(args);
+      default:
+        return jsonError(`unknown tool: ${name}`);
+    }
+  } catch (err) {
+    // 핸들러 throw (네트워크·401 등) 를 MCP error result 로 환원 — 미처리 throw → 프로토콜 에러 방지.
+    // 토큰 있어도 세션 만료(401) 면 재로그인 안내로 전환(AI 가 막히지 않게).
+    if (isAuthError(err)) return notLoggedIn();
+    return jsonError(err instanceof Error ? err.message : String(err));
   }
 }
 
 function buildServer(): Server {
-  const server = new Server(
-    { name: 'athsra', version: VERSION },
-    { capabilities: { tools: {} } },
-  );
+  const server = new Server({ name: 'athsra', version: VERSION }, { capabilities: { tools: {} } });
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
@@ -580,7 +155,16 @@ export async function mcpCmd(args: string[]): Promise<number> {
   const server = buildServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  // server runs until transport closes (parent process exits)
+  // connect() 는 stdin 리스너 등록 후 즉시 resolve — 여기서 return 하면 호출부 index.ts 의
+  // `.then((code) => process.exit(code))` 가 프로세스를 죽여 stdin 을 못 읽는다 (MCP 무응답).
+  // transport 가 닫힐 때까지 (MCP 클라이언트가 stdin 종료 = 부모 프로세스 종료) 살려둔다.
+  await new Promise<void>((resolve) => {
+    const prevOnClose = transport.onclose;
+    transport.onclose = () => {
+      prevOnClose?.();
+      resolve();
+    };
+  });
   return 0;
 }
 

package/src/commands/new-phrase.ts

@@ -1,4 +1,4 @@
-import { generatePhrase, wordCount } from '../lib/bip39.ts';
+import { generatePhrase, wordCount } from '@athsra/crypto';
 import { promptConfirm } from '../lib/prompt.ts';
 
 const USAGE = [