@athsra/cli 0.1.0 → 1.0.0

package/src/commands/adopt.ts

@@ -0,0 +1,490 @@
+/**
+ * adopt.ts — sibling repo 의 athsra 통합 onboarding 한 줄 명령.
+ *
+ * 호출 예 (sibling repo 디렉토리 안에서):
+ *   cd /home/mod/code/modfolio-press
+ *   athsra adopt
+ *
+ * 자동 추론:
+ *   project = basename(cwd) 또는 .athsra / package.json (auto-project.ts)
+ *   gh-repo = git remote origin
+ *   cf-worker, root_directory = wrangler.jsonc 자동 발견 + name 추출
+ *
+ * 명시 override:
+ *   --project=<x>, --cf-worker=<name>, --root=<dir>, --gh-repo=<org/repo>,
+ *   --branch=<name>, --build=<cmd>, --deploy=<cmd>, --env=<KEY1,KEY2>,
+ *   --cf-token-project=<envelope>, --skip-sync, --skip-builds, --manual-build, --dry-run
+ *
+ * 흐름 (각 step 멱등):
+ *   1. envelope 확인 (없으면 안내)
+ *   2. CF token 확보 (envelope 또는 환경변수 또는 --cf-token-project)
+ *   3. wrangler secrets sync (envelope → worker)
+ *   4. Workers Builds setup:
+ *      a. worker_tag GET (없으면 wrangler deploy 안내)
+ *      b. repo connection (idempotent PUT)
+ *      c. latest build token
+ *      d. trigger upsert (있으면 PATCH, 없으면 POST)
+ *      e. env vars PATCH (default GITHUB_TOKEN)
+ *   5. (manual-build flag 시) 1차 build 트리거
+ *
+ * canon: modfolio-ecosystem/knowledge/canon/{cf-workers-builds-api,secret-store}.md
+ */
+
+import {
+  type AdoptInferred,
+  fetchGhRepoMeta,
+  inferAdoptContext,
+  type WrangerWorker,
+} from '../lib/adopt-context.ts';
+import { loadAuthContext } from '../lib/auth-context.ts';
+import { resolveProject } from '../lib/auto-project.ts';
+import { readPlain } from '../lib/envelope.ts';
+import { createManifest, loadManifest, saveManifest } from '../lib/secrets-manifest.ts';
+import {
+  ensureRepoConnection,
+  getLatestBuildToken,
+  getWorkerTag,
+  setTriggerEnvVars,
+  triggerManualBuild,
+  upsertTrigger,
+} from '../lib/workers-builds.ts';
+import {
+  ManifestInvalidError,
+  ManifestRequiredError,
+  syncWranglerSecrets,
+} from '../lib/wrangler-sync.ts';
+
+const USAGE = [
+  'usage: athsra adopt [<project>] [options]',
+  '',
+  'sibling repo 의 athsra envelope ↔ CF Worker + Workers Builds 한 줄 onboarding.',
+  '',
+  '자동 추론 (cwd 기반):',
+  '  project    = basename(cwd) (또는 --project=<x> / .athsra / package.json)',
+  '  gh-repo    = git remote origin',
+  '  cf-worker  = wrangler.jsonc 의 name (cwd 하위 발견된 첫 worker)',
+  '  root       = wrangler.jsonc 위치 (repoRoot 기준 상대 경로)',
+  '',
+  '옵션:',
+  '  --cf-worker=<name>       명시 (다중 wrangler.jsonc 시 필수)',
+  '  --root=<dir>             Workers Builds root_directory (default: 자동 추론)',
+  '  --gh-repo=<org/repo>     GitHub repo (default: git remote)',
+  '  --branch=<name>          default main',
+  '  --build=<cmd>            default "bun run build"',
+  '  --deploy=<cmd>           default "bunx wrangler deploy"',
+  '  --env=<KEY1,KEY2>        Workers Builds trigger env vars (default GITHUB_TOKEN)',
+  '  --cf-token-project=<x>   CF API token 출처 envelope (default: project 자체 / env)',
+  '  --skip-sync              wrangler secrets sync 생략',
+  '  --skip-builds            Workers Builds setup 생략',
+  '  --manual-build           setup 후 1차 build 즉시 트리거 (검증)',
+  '  --auto-manifest          manifest 없으면 envelope 전체 키로 자동 생성 후 진행 (sibling 1줄 onboarding)',
+  '  --allow-all              manifest 없을 때 envelope 전체 sync (legacy, manifest 미생성)',
+  '  --dry-run                전체 흐름 mutate 없이 미리보기',
+  '',
+  'Phase 2.6 (Option γ): default-deny + manifest opt-in.',
+  '  manifest 위치: <worker.cwd>/.athsra/secrets.json',
+  '  없으면 sync 거부. `athsra manifest init` 또는 `athsra adopt --auto-manifest`.',
+].join('\n');
+
+interface ParsedArgs {
+  cfWorker?: string;
+  root?: string;
+  ghRepo?: string;
+  branch: string;
+  build: string;
+  deploy: string;
+  envKeys: string[];
+  cfTokenProject?: string;
+  skipSync: boolean;
+  skipBuilds: boolean;
+  manualBuild: boolean;
+  allowAll: boolean;
+  autoManifest: boolean;
+  dryRun: boolean;
+}
+
+function parseAdoptArgs(rest: string[]): ParsedArgs {
+  const flags: Record<string, string | boolean> = {};
+  for (const a of rest) {
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else flags[a.slice(2)] = true;
+    }
+  }
+  return {
+    cfWorker: typeof flags['cf-worker'] === 'string' ? flags['cf-worker'] : undefined,
+    root: typeof flags.root === 'string' ? flags.root : undefined,
+    ghRepo: typeof flags['gh-repo'] === 'string' ? flags['gh-repo'] : undefined,
+    branch: typeof flags.branch === 'string' ? flags.branch : 'main',
+    build: typeof flags.build === 'string' ? flags.build : 'bun run build',
+    deploy: typeof flags.deploy === 'string' ? flags.deploy : 'bunx wrangler deploy',
+    envKeys: (typeof flags.env === 'string' ? flags.env : 'GITHUB_TOKEN')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+    cfTokenProject:
+      typeof flags['cf-token-project'] === 'string' ? flags['cf-token-project'] : undefined,
+    skipSync: flags['skip-sync'] === true,
+    skipBuilds: flags['skip-builds'] === true,
+    manualBuild: flags['manual-build'] === true,
+    allowAll: flags['allow-all'] === true,
+    autoManifest: flags['auto-manifest'] === true,
+    dryRun: flags['dry-run'] === true,
+  };
+}
+
+function chooseWorker(
+  inferred: AdoptInferred,
+  explicitName: string | undefined,
+  explicitRoot: string | undefined,
+): WrangerWorker | { error: string } {
+  if (explicitName) {
+    const found = inferred.workers.find((w) => w.name === explicitName);
+    if (found) return found;
+    // 명시한 worker 가 wrangler.jsonc 에 없으면, 사용자 신뢰 후 root 명시 요구.
+    if (!explicitRoot) {
+      return {
+        error: `worker '${explicitName}' 가 cwd 의 wrangler.jsonc 에서 발견되지 않음. --root=<dir> 명시 필요`,
+      };
+    }
+    return { name: explicitName, cwd: inferred.repoRoot, rootDirectory: explicitRoot };
+  }
+  const [first] = inferred.workers;
+  if (!first) {
+    return {
+      error:
+        'wrangler.jsonc 발견 안 됨. --cf-worker=<name> + --root=<dir> 명시 필요 또는 sibling repo 안에서 호출',
+    };
+  }
+  if (inferred.workers.length === 1) return first;
+  const list = inferred.workers.map((w) => `  - ${w.name} (root=${w.rootDirectory})`).join('\n');
+  return {
+    error: `다수의 wrangler.jsonc 발견. --cf-worker=<name> 명시:\n${list}`,
+  };
+}
+
+interface CfCreds {
+  accountId: string;
+  apiToken: string;
+  /** 어디서 가져왔는지 — 보고용 */
+  source: string;
+}
+
+async function resolveCfCreds(
+  ctx: import('../lib/auth-context.ts').AuthContext,
+  project: string,
+  cfTokenProject: string | undefined,
+): Promise<CfCreds | { error: string }> {
+  // 1. 환경변수 우선 (athsra run 으로 wrap 한 경우 자동 inject 된 상태)
+  const envAcc = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const envTok = process.env.CLOUDFLARE_API_TOKEN;
+  if (envAcc && envTok) {
+    return { accountId: envAcc, apiToken: envTok, source: 'env (CLOUDFLARE_*)' };
+  }
+  // 2. --cf-token-project 명시 envelope
+  const tokenProject = cfTokenProject ?? project;
+  const env = await readPlain(ctx, tokenProject);
+  if (!env) {
+    return {
+      error: `CF token 출처 envelope '${tokenProject}' not found. --cf-token-project=<x> 명시 또는 athsra set ${tokenProject} CLOUDFLARE_ACCOUNT_ID=... CLOUDFLARE_API_TOKEN=...`,
+    };
+  }
+  const acc = env.CLOUDFLARE_ACCOUNT_ID;
+  const tok = env.CLOUDFLARE_API_TOKEN;
+  if (!acc || !tok) {
+    return {
+      error: `envelope '${tokenProject}' 에 CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN 누락. athsra set ${tokenProject} CLOUDFLARE_ACCOUNT_ID=... CLOUDFLARE_API_TOKEN=...`,
+    };
+  }
+  return { accountId: acc, apiToken: tok, source: `envelope '${tokenProject}'` };
+}
+
+export async function adoptCmd(args: string[]): Promise<number> {
+  const { project, rest, source } = resolveProject(args);
+  if (!project) {
+    console.error(USAGE);
+    return 2;
+  }
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(USAGE);
+    return 0;
+  }
+  const parsed = parseAdoptArgs(rest);
+
+  if (source !== 'positional' && source !== 'flag') {
+    console.log(`(project=${project} auto-detected from ${source})`);
+  }
+
+  // auth
+  const ctx = await loadAuthContext();
+  if (!ctx) return 1;
+  if (ctx.kind !== 'user') {
+    console.error('athsra adopt 은 user token (master pw) 가 필요합니다.');
+    return 1;
+  }
+
+  // 1. envelope 확인
+  const envelope = await readPlain(ctx, project);
+  if (!envelope) {
+    console.error(`✗ envelope '${project}' not found.`);
+    console.error(`  먼저 시크릿을 추가: athsra set ${project} KEY=value`);
+    console.error(`  또는 web UI: https://athsra.com/projects`);
+    return 1;
+  }
+
+  // 2. 자동 추론
+  const cwd = process.cwd();
+  const inferred = inferAdoptContext(cwd);
+  const workerPick = chooseWorker(inferred, parsed.cfWorker, parsed.root);
+  if ('error' in workerPick) {
+    console.error(`✗ ${workerPick.error}`);
+    return 2;
+  }
+  const worker = workerPick;
+  const root = parsed.root ?? worker.rootDirectory;
+  const ghRepo = parsed.ghRepo ?? inferred.ghRepo;
+
+  console.log(`=== athsra adopt: ${project} → ${worker.name} ===`);
+  console.log(`  envelope keys: ${Object.keys(envelope).filter((k) => envelope[k]).length}`);
+  console.log(`  worker:        ${worker.name}`);
+  console.log(`  worker cwd:    ${worker.cwd}`);
+  console.log(`  root:          ${root}`);
+  console.log(`  gh-repo:       ${ghRepo ?? '(none — Workers Builds skip)'}`);
+  console.log(`  branch:        ${parsed.branch}`);
+  console.log(`  build:         ${parsed.build}`);
+  console.log(`  deploy:        ${parsed.deploy}`);
+  console.log(`  env vars:      ${parsed.envKeys.join(', ')}`);
+  console.log(`  skip-sync:     ${parsed.skipSync}`);
+  console.log(`  skip-builds:   ${parsed.skipBuilds}`);
+  console.log(
+    `  auto-manifest: ${parsed.autoManifest} (manifest 없으면 envelope 전체로 자동 생성)`,
+  );
+  console.log(`  allow-all:     ${parsed.allowAll} (manifest bypass — legacy)`);
+  console.log(`  dry-run:       ${parsed.dryRun}`);
+  console.log('');
+
+  // Phase 2.5 — snapshot 캡처 (마지막에 athsra worker D1 mapping 등록용)
+  let syncedAt: string | undefined;
+  let syncedCount: number | undefined;
+  let syncOutcome: 'success' | 'fail' | undefined;
+  let triggerUuidCaptured: string | undefined;
+  let buildUuidCaptured: string | undefined;
+  let buildAtCaptured: string | undefined;
+
+  // 3. wrangler secrets sync
+  if (!parsed.skipSync) {
+    console.log(`-- step 1/2: wrangler secrets sync (envelope → ${worker.name}) --`);
+
+    // Phase 2.7.2 (2026-05-26): --auto-manifest 면 manifest 없을 때 envelope 전체 키로 자동 생성.
+    if (parsed.autoManifest) {
+      const existing = loadManifest({ workerCwd: worker.cwd });
+      if (existing.error) {
+        console.error(`✗ manifest invalid (${existing.path}): ${existing.error}`);
+        return 1;
+      }
+      if (!existing.manifest) {
+        const envelopeKeys = Object.entries(envelope)
+          .filter(([, v]) => typeof v === 'string' && v.length > 0)
+          .map(([k]) => k);
+        if (envelopeKeys.length === 0) {
+          console.error('✗ --auto-manifest: envelope 에 캡처할 키가 없음');
+          return 1;
+        }
+        if (parsed.dryRun) {
+          console.log(
+            `  (dry-run) would create manifest with ${envelopeKeys.length} keys at ${existing.path}`,
+          );
+        } else {
+          const created = createManifest(envelopeKeys);
+          const saved = saveManifest(worker.cwd, created);
+          console.log(`  ✓ manifest auto-created: ${saved} (${created.secrets.length} keys)`);
+        }
+      } else {
+        console.log(
+          `  manifest exists (${existing.manifest.secrets.length} keys) — auto-manifest skip`,
+        );
+      }
+    }
+
+    try {
+      const syncResult = await syncWranglerSecrets({
+        cwd: worker.cwd,
+        envelope,
+        workerName: worker.name,
+        dryRun: parsed.dryRun,
+        allowAll: parsed.allowAll,
+      });
+      if (!parsed.dryRun) {
+        syncedAt = new Date().toISOString();
+        syncedCount = syncResult.syncedKeys;
+        syncOutcome = 'success';
+      }
+    } catch (err) {
+      syncOutcome = 'fail';
+      if (err instanceof ManifestRequiredError) {
+        // 친절한 안내 — describeMissingManifest 가 메시지 본문
+        console.error('');
+        console.error((err as Error).message);
+        return 2;
+      }
+      if (err instanceof ManifestInvalidError) {
+        console.error(`✗ ${(err as Error).message}`);
+        console.error('  수정 후 재시도: athsra manifest show / athsra manifest validate');
+        return 1;
+      }
+      console.error(`✗ wrangler sync failed: ${(err as Error).message}`);
+      return 1;
+    }
+    console.log('');
+  } else {
+    console.log('-- step 1/2: wrangler secrets sync (--skip-sync) --\n');
+  }
+
+  // 4. Workers Builds
+  if (parsed.skipBuilds) {
+    console.log('-- step 2/2: Workers Builds (--skip-builds) --\n');
+    console.log('=== Done. ===');
+    return 0;
+  }
+  if (!ghRepo) {
+    console.log('-- step 2/2: Workers Builds (skipped — gh-repo 없음) --\n');
+    console.log('=== Done (Workers Builds 미설정). ===');
+    return 0;
+  }
+  console.log('-- step 2/2: Workers Builds setup --');
+
+  // CF creds
+  const creds = await resolveCfCreds(ctx, project, parsed.cfTokenProject);
+  if ('error' in creds) {
+    console.error(`✗ ${creds.error}`);
+    return 1;
+  }
+  console.log(`  CF creds: ${creds.source}`);
+
+  if (parsed.dryRun) {
+    console.log(
+      '  (dry-run) would: worker_tag GET → repo connection PUT → token GET → trigger upsert → env vars PATCH',
+    );
+    console.log('\n=== Done (dry-run). ===');
+    return 0;
+  }
+
+  try {
+    // worker_tag
+    const workerTag = await getWorkerTag(creds.accountId, creds.apiToken, worker.name);
+    if (!workerTag) {
+      console.error(`✗ worker '${worker.name}' not found on CF.`);
+      console.error(`  먼저 1회 deploy: cd ${worker.cwd} && bunx wrangler deploy`);
+      return 1;
+    }
+    console.log(`  worker_tag: ${workerTag}`);
+
+    // repo meta (gh API)
+    const meta = fetchGhRepoMeta(ghRepo);
+    if (!meta) {
+      console.error(`✗ gh api /repos/${ghRepo} 실패. gh CLI 인증 확인: gh auth status`);
+      return 1;
+    }
+    console.log(`  gh: ${ghRepo} (repo_id=${meta.repoId}, owner_id=${meta.ownerId})`);
+
+    // repo connection
+    const repoName = ghRepo.split('/')[1];
+    if (!repoName) {
+      console.error(`✗ gh-repo '${ghRepo}' 형식 오류 — 'org/repo' 필요`);
+      return 2;
+    }
+    const conn = await ensureRepoConnection(creds.accountId, creds.apiToken, {
+      providerAccountId: meta.ownerId,
+      providerAccountName: meta.ownerLogin,
+      repoId: meta.repoId,
+      repoName,
+    });
+    console.log(`  repo_connection_uuid: ${conn.repo_connection_uuid}`);
+
+    // build token
+    const tok = await getLatestBuildToken(creds.accountId, creds.apiToken);
+    console.log(`  build_token: ${tok.build_token_name} (${tok.build_token_uuid})`);
+
+    // trigger upsert
+    const { trigger, created } = await upsertTrigger(creds.accountId, creds.apiToken, {
+      externalScriptId: workerTag,
+      repoConnectionUuid: conn.repo_connection_uuid,
+      buildTokenUuid: tok.build_token_uuid,
+      triggerName: `Deploy ${worker.name} (${parsed.branch})`,
+      buildCommand: parsed.build,
+      deployCommand: parsed.deploy,
+      rootDirectory: root,
+      branchIncludes: [parsed.branch],
+    });
+    console.log(`  trigger: ${trigger.trigger_uuid} (${created ? 'created' : 'updated'})`);
+    triggerUuidCaptured = trigger.trigger_uuid;
+
+    // env vars
+    if (parsed.envKeys.length > 0) {
+      const envVarsBody: Record<string, { value: string; is_secret: boolean }> = {};
+      for (const key of parsed.envKeys) {
+        const val = envelope[key];
+        if (!val) {
+          console.error(
+            `✗ env var '${key}' 가 envelope '${project}' 에 없음. athsra set ${project} ${key}=...`,
+          );
+          return 1;
+        }
+        envVarsBody[key] = { value: val, is_secret: true };
+      }
+      await setTriggerEnvVars(creds.accountId, creds.apiToken, trigger.trigger_uuid, envVarsBody);
+      console.log(`  env vars: ${parsed.envKeys.join(', ')} (is_secret=true)`);
+    }
+
+    // manual build (옵션)
+    if (parsed.manualBuild) {
+      const build = await triggerManualBuild(
+        creds.accountId,
+        creds.apiToken,
+        trigger.trigger_uuid,
+        parsed.branch,
+      );
+      console.log(`  manual build queued: ${build.build_uuid} (status=${build.status})`);
+      buildUuidCaptured = build.build_uuid;
+      buildAtCaptured = new Date().toISOString();
+    }
+  } catch (err) {
+    console.error(`✗ Workers Builds setup failed: ${(err as Error).message}`);
+    return 1;
+  }
+
+  // 5. athsra worker D1 mapping 등록 (best-effort — endpoint 미 deploy 시 silent skip)
+  if (!parsed.dryRun) {
+    try {
+      const cwResult = await ctx.client.registerCwWorker(project, {
+        workerName: worker.name,
+        accountId: creds.accountId,
+        rootDirectory: root,
+        branch: parsed.branch,
+        triggerUuid: triggerUuidCaptured,
+      });
+      if (cwResult === null) {
+        console.log(
+          '\n  (athsra worker /v1/workers endpoint 미 deploy — D1 매핑 skip, 다음 worker deploy 후 자동 등록)',
+        );
+      } else {
+        await ctx.client.updateCwWorker(project, worker.name, {
+          lastSyncedAt: syncedAt,
+          lastSyncOutcome: syncOutcome,
+          lastSyncKeyCount: syncedCount,
+          lastBuildUuid: buildUuidCaptured,
+          lastBuildAt: buildAtCaptured,
+        });
+        console.log(
+          `\n  mapping: id=${cwResult.id} (${cwResult.created ? 'registered' : 'updated'}) — dashboard /projects/${project} 에서 확인`,
+        );
+      }
+    } catch (err) {
+      console.log(`\n  (mapping 등록 실패 — silent: ${(err as Error).message})`);
+    }
+  }
+
+  console.log(`\n=== Done. push to ${parsed.branch} → CF auto-deploy. ===`);
+  return 0;
+}

package/src/commands/audit.ts

@@ -0,0 +1,156 @@
+/**
+ * Phase 1.x.9 (2026-05-25) — `athsra audit` CLI 명령.
+ *
+ * worker `/v1/audit` 호출 → 출력 형식 변환 (table/json/jsonl).
+ * 권한: user token (master pw) 또는 service token with audit:read scope.
+ *
+ * 예시:
+ *   athsra audit                                 — 최근 100 entries (table)
+ *   athsra audit --actor=machine-A               — 특정 머신 활동
+ *   athsra audit --action=rate-limit.throttled   — 특정 이벤트 타임라인
+ *   athsra audit --status=429 --from=2026-05-25T00:00:00Z
+ *   athsra audit --all --format=jsonl            — 전체 (cursor 자동) JSONL 출력
+ */
+
+import { loadAuthContext } from '../lib/auth-context.ts';
+import type { AuditEntry } from '../lib/client.ts';
+
+const USAGE = [
+  'usage:',
+  '  athsra audit [--actor=<id>] [--action=<a>] [--status=<n>] [--from=<iso>] [--to=<iso>] [--limit=<n>] [--all] [--format=table|json|jsonl]',
+  '',
+  '권한: user token (master pw) 또는 service token with audit:read scope.',
+  '',
+  '필터:',
+  '  --actor    machineId / "anonymous" / "ip:<ip>" / "token:<hash>" 일치',
+  '  --action   "register.bootstrap", "rate-limit.throttled" 등 일치',
+  '  --status   100..599 정수 일치',
+  '  --from     ISO 8601 (>= 비교, 예: 2026-05-25T00:00:00Z)',
+  '  --to       ISO 8601 (<= 비교, 예: 2026-05-25T23:59:59Z)',
+  '',
+  '페이지네이션 / 출력:',
+  '  --limit    페이지 크기 (default 100, max 1000)',
+  '  --all      모든 page (cursor 자동 follow 후 일괄 출력)',
+  '  --format   table (default) | json | jsonl',
+].join('\n');
+
+interface AuditOpts {
+  actor?: string;
+  action?: string;
+  status?: number;
+  from?: string;
+  to?: string;
+  limit?: number;
+  all: boolean;
+  format: 'table' | 'json' | 'jsonl';
+}
+
+interface ParseError {
+  error: string;
+}
+
+function parseOpts(args: string[]): AuditOpts | ParseError {
+  const opts: AuditOpts = { all: false, format: 'table' };
+  for (const a of args) {
+    if (a === '--all') {
+      opts.all = true;
+    } else if (a.startsWith('--actor=')) {
+      opts.actor = a.slice('--actor='.length);
+    } else if (a.startsWith('--action=')) {
+      opts.action = a.slice('--action='.length);
+    } else if (a.startsWith('--status=')) {
+      const n = Number(a.slice('--status='.length));
+      if (!Number.isInteger(n) || n < 100 || n > 599) {
+        return { error: '--status must be integer 100..599' };
+      }
+      opts.status = n;
+    } else if (a.startsWith('--from=')) {
+      opts.from = a.slice('--from='.length);
+    } else if (a.startsWith('--to=')) {
+      opts.to = a.slice('--to='.length);
+    } else if (a.startsWith('--limit=')) {
+      const n = Number(a.slice('--limit='.length));
+      if (!Number.isInteger(n) || n < 1 || n > 1000) {
+        return { error: '--limit must be integer 1..1000' };
+      }
+      opts.limit = n;
+    } else if (a.startsWith('--format=')) {
+      const v = a.slice('--format='.length);
+      if (v !== 'table' && v !== 'json' && v !== 'jsonl') {
+        return { error: '--format must be table|json|jsonl' };
+      }
+      opts.format = v;
+    } else if (a === '--help' || a === '-h') {
+      // caller 가 처리
+    } else if (a.startsWith('-')) {
+      return { error: `Unknown flag: ${a}` };
+    }
+  }
+  return opts;
+}
+
+function printTable(rows: AuditEntry[]): void {
+  if (rows.length === 0) {
+    console.log('(no audit entries match the given filters)');
+    return;
+  }
+  console.log(`${rows.length} entries (newest first):`);
+  console.log('');
+  for (const r of rows) {
+    const actor = r.actor.padEnd(20);
+    const status = String(r.status).padStart(3);
+    console.log(`${r.ts}  ${actor}  ${status}  ${r.action}`);
+    if (r.request_method || r.request_path) {
+      console.log(`    ${r.request_method ?? ''} ${r.request_path ?? ''}`.trimEnd());
+    }
+    if (r.meta) {
+      console.log(`    meta: ${JSON.stringify(r.meta)}`);
+    }
+  }
+}
+
+export async function auditCmd(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const parsed = parseOpts(args);
+  if ('error' in parsed) {
+    console.error(parsed.error);
+    console.error('');
+    console.error(USAGE);
+    return 2;
+  }
+  const opts = parsed;
+
+  const ctx = await loadAuthContext();
+  if (!ctx) return 1;
+  const { client } = ctx;
+
+  const all: AuditEntry[] = [];
+  let cursor: string | undefined;
+  do {
+    const res = await client.queryAudit({
+      actor: opts.actor,
+      action: opts.action,
+      status: opts.status,
+      from: opts.from,
+      to: opts.to,
+      limit: opts.limit,
+      cursor,
+    });
+    all.push(...res.entries);
+    cursor = opts.all && res.nextCursor ? res.nextCursor : undefined;
+  } while (cursor);
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify({ entries: all, count: all.length }, null, 2));
+  } else if (opts.format === 'jsonl') {
+    for (const r of all) console.log(JSON.stringify(r));
+  } else {
+    printTable(all);
+  }
+
+  return 0;
+}