@athsra/cli 0.1.0 → 1.0.0

package/src/commands/versions.ts

@@ -1,20 +1,26 @@
 import { loadAuthContext } from '../lib/auth-context.ts';
+import { resolveProject } from '../lib/auto-project.ts';
 
-const USAGE = 'usage: athsra versions <project>';
+const USAGE = [
+  'usage: athsra versions [<project>]',
+  '',
+  '<project> 자동 감지 (cwd 기반): basename(cwd) > .athsra > package.json athsra.project',
+].join('\n');
 
 /**
- * athsra versions <project>
+ * athsra versions [<project>]
  *   - 모든 version + tombstone 상태 출력
  *   - current version 은 * 표시
  *   - tombstone 있으면 (deleted) 헤더로 표시
+ *   - <project> 생략 시 cwd 기반 자동 감지
  */
 export async function versionsCmd(args: string[]): Promise<number> {
-  const project = args[0];
+  const { project } = resolveProject(args);
   if (!project) {
     console.error(USAGE);
     return 2;
   }
-  const ctx = loadAuthContext();
+  const ctx = await loadAuthContext();
   if (!ctx) return 1;
   const { client } = ctx;
 

package/src/index.ts

@@ -1,11 +1,19 @@
 #!/usr/bin/env bun
+import { projectCmd, roleCmd, usersCmd } from './commands/admin.ts';
+import { adoptCmd } from './commands/adopt.ts';
+import { auditCmd } from './commands/audit.ts';
+import { completionCmd } from './commands/completion.ts';
 import { deleteCmd } from './commands/delete.ts';
 import { doctorCmd } from './commands/doctor.ts';
 import { getCmd } from './commands/get.ts';
 import { handoffCmd } from './commands/handoff.ts';
 import { initCmd } from './commands/init.ts';
 import { loginCmd } from './commands/login.ts';
+import { logoutCmd } from './commands/logout.ts';
 import { lsCmd } from './commands/ls.ts';
+import { manifestCmd } from './commands/manifest.ts';
+import { mcpCmd } from './commands/mcp.ts';
+import { migrateEnvelopesCmd } from './commands/migrate-envelopes.ts';
 import { newPhraseCmd } from './commands/new-phrase.ts';
 import { purgeCmd } from './commands/purge.ts';
 import { restoreCmd } from './commands/restore.ts';
@@ -13,21 +21,32 @@ import { revokeCmd } from './commands/revoke.ts';
 import { rollbackCmd } from './commands/rollback.ts';
 import { rotateMasterCmd } from './commands/rotate-master.ts';
 import { runCmd } from './commands/run.ts';
+import { serviceTokenCmd } from './commands/service-token.ts';
 import { setCmd } from './commands/set.ts';
 import { unsetCmd } from './commands/unset.ts';
 import { versionsCmd } from './commands/versions.ts';
 
-const VERSION = '0.1.0';
+const VERSION = '1.0.0';
 
 const commands: Record<string, (args: string[]) => Promise<number>> = {
   login: loginCmd,
+  logout: logoutCmd,
   init: initCmd,
+  adopt: adoptCmd,
   set: setCmd,
   unset: unsetCmd,
   get: getCmd,
   ls: lsCmd,
+  manifest: manifestCmd,
+  mcp: mcpCmd,
   run: runCmd,
   doctor: doctorCmd,
+  'service-token': serviceTokenCmd,
+  audit: auditCmd,
+  users: usersCmd,
+  role: roleCmd,
+  project: projectCmd,
+  'migrate-envelopes': migrateEnvelopesCmd,
   'rotate-master': rotateMasterCmd,
   'new-phrase': newPhraseCmd,
   handoff: handoffCmd,
@@ -37,6 +56,7 @@ const commands: Record<string, (args: string[]) => Promise<number>> = {
   delete: deleteCmd,
   restore: restoreCmd,
   purge: purgeCmd,
+  completion: completionCmd,
 };
 
 const args = Bun.argv.slice(2);
@@ -47,13 +67,25 @@ if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
 
 Usage:
   athsra login                              master pw 입력 + 머신 등록 (Bearer token 발급)
+  athsra logout [--full]                    keyring clear (worker token 유지). --full 시 config 도 삭제
   athsra init <project>                     신규 project 안내
+  athsra adopt [<project>] [opts]           sibling repo envelope ↔ CF Worker + Workers Builds 1줄 onboarding
   athsra set <project> KEY=value            secret 추가/수정 (다건 가능)
   athsra unset <project> KEY [...]          특정 key 제거 (envelope 유지)
   athsra get <project> [KEY]                값 출력 (single 또는 dump)
   athsra ls [project] [--all]               project 또는 key 목록 (--all=deleted 포함)
+  athsra manifest {init|show|validate|add|remove}  sibling worker 의 secrets opt-in manifest (Option γ)
+  athsra mcp                                Model Context Protocol stdio server (AI agent 통합)
   athsra run <project> -- <cmd>             env inject 후 명령 실행 (Doppler-style)
-  athsra doctor                             환경 검증 (keyring/dbus/worker phase)
+  athsra doctor [--audit]                   환경 검증 (keyring/dbus/worker). --audit=전 project 빈 값 키 스캔
+  athsra service-token create <p> --label=<l>  scoped service token 발급 (master pw 없이도 복호, headless 용)
+  athsra service-token list [<project>]     발급한 service token 메타 (revoke·만료 점검용)
+  athsra service-token revoke <token>       service token 무효화
+  athsra audit [--actor=...] [--action=...]  audit log 조회 (--all=cursor follow, --format=table|json|jsonl)
+  athsra users {list|invite <id> [--role=R]}  RBAC: user 목록 / 신규 invite (admin role 필요)
+  athsra role {grant|revoke} <user_id> <R>    role 부여/제거 (admin/dev/viewer/auditor/sa)
+  athsra project {share|unshare} <p> <uid>    per-project ACL share/unshare (--perms=read|write)
+  athsra migrate-envelopes [--apply]        모든 v1 envelope → v2 일괄 마이그레이션 (idempotent)
 
   athsra versions <project>                 모든 version + tombstone 상태
   athsra rollback <project> <version_id>    특정 version 으로 current 복원
@@ -65,6 +97,7 @@ Usage:
   athsra new-phrase                         BIP-39 12-word phrase 생성 (master pw 권장)
   athsra handoff [--accept]                 새 머신 추가 (issue / accept)
   athsra revoke [<atk_*>]                   self 또는 명시 token revoke
+  athsra completion {bash|zsh|fish}         shell completion script 출력
 
 Files / Storage:
   ~/.athsra/config.json                     worker URL + machine_id
@@ -77,7 +110,10 @@ Env vars (CI):
   ATHSRA_PURGE_CONFIRMED=1     skip purge double-confirm
   ATHSRA_ROLLBACK_CONFIRMED=1  skip rollback confirm
 
-Phase 1.x.1 = Bearer auth + keyring + soft-delete + version history.
+Headless (service token — master pw 없이 scoped 복호):
+  ATHSRA_TOKEN=ats_...  ATHSRA_WORKER_URL=https://...  athsra run <project> -- <cmd>
+
+Phase 1.x.8 = envelope v2 (DEK + multi-recipient) + service tokens for headless hosts.
 docs: github.com/modfolio/athsra
 `);
   process.exit(0);
@@ -90,10 +126,49 @@ if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
 
 const handler = commands[cmd];
 if (!handler) {
-  console.error(`Unknown command: ${cmd}\nRun \`athsra --help\` for usage.`);
+  // Levenshtein distance 1-2 까지 suggestion ("Did you mean?")
+  const suggestions = suggestCommand(cmd, Object.keys(commands));
+  let msg = `Unknown command: ${cmd}\n`;
+  if (suggestions.length > 0) {
+    msg += `Did you mean: ${suggestions.map((s) => `\`${s}\``).join(' or ')}?\n`;
+  }
+  msg += 'Run `athsra --help` for usage.';
+  console.error(msg);
   process.exit(2);
 }
 
+/**
+ * Levenshtein distance 기반 명령 typo 추천. distance ≤ 2 + sorted by distance.
+ * Bun/Node 표준 — DP 2D matrix, O(m*n) time, O(min) space (단순 구현).
+ */
+function suggestCommand(input: string, available: string[]): string[] {
+  const scored: { name: string; dist: number }[] = [];
+  for (const name of available) {
+    const dist = levenshtein(input, name);
+    if (dist <= 2) scored.push({ name, dist });
+  }
+  return scored.sort((a, b) => a.dist - b.dist).map((s) => s.name);
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  // DP — prev row + cur row
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    const cur = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur.push(Math.min((prev[j] ?? 0) + 1, (cur[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost));
+    }
+    prev = cur;
+  }
+  return prev[n] ?? 0;
+}
+
 handler(args.slice(1))
   .then((code) => process.exit(code))
   .catch((err: Error) => {

package/src/lib/adopt-context.ts

@@ -0,0 +1,183 @@
+/**
+ * adopt-context.ts — sibling repo 의 자동 추론 (wrangler.jsonc, git remote, app root).
+ *
+ * `athsra adopt` 가 매번 사용자에게 worker/repo/root 를 물어보지 않게, cwd 의 파일
+ * 시스템 + git 정보로 합리적 기본값 추론. 사용자 명시 --cf-worker / --gh-repo / --root
+ * override 우선.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+export interface AdoptInferred {
+  /** 발견된 모든 wrangler.jsonc / wrangler.toml 경로 + 추출된 name */
+  workers: WrangerWorker[];
+  /** git remote 에서 추출한 modfolio/<repo> (없으면 undefined) */
+  ghRepo?: string;
+  /** sibling repo 의 monorepo root (package.json workspaces 또는 git toplevel) */
+  repoRoot: string;
+}
+
+export interface WrangerWorker {
+  /** wrangler.jsonc 의 `name` */
+  name: string;
+  /** wrangler.jsonc 가 있는 디렉토리의 absolute 경로 */
+  cwd: string;
+  /** repoRoot 기준 상대 경로 (Workers Builds root_directory). repo root 면 "." */
+  rootDirectory: string;
+}
+
+/** JSONC (comments 허용) 안전 파싱 — wrangler.jsonc 가 표준 JSONC 사용. */
+function parseJsonc(text: string): unknown {
+  // 단순 cleanup: line comments (//) + block comments (/* */) 제거.
+  // 문자열 내부 // 는 보존 — 정공법은 proper JSONC parser 인데 의존성 추가 회피.
+  let cleaned = '';
+  let i = 0;
+  let inString = false;
+  let escaped = false;
+  while (i < text.length) {
+    const c = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      cleaned += c;
+      if (escaped) escaped = false;
+      else if (c === '\\') escaped = true;
+      else if (c === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      cleaned += c;
+      i++;
+      continue;
+    }
+    if (c === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      i += 2;
+      while (i < text.length - 1 && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    cleaned += c;
+    i++;
+  }
+  // trailing commas 제거 (objects + arrays). 단순 regex.
+  cleaned = cleaned.replace(/,\s*([}\]])/g, '$1');
+  return JSON.parse(cleaned);
+}
+
+/** wrangler.jsonc / wrangler.toml 의 name field. 없으면 null. */
+function readWranglerName(path: string): string | null {
+  try {
+    const text = readFileSync(path, 'utf-8');
+    if (path.endsWith('.toml')) {
+      const m = text.match(/^\s*name\s*=\s*"([^"]+)"/m);
+      return m?.[1] ?? null;
+    }
+    const obj = parseJsonc(text) as { name?: unknown };
+    return typeof obj.name === 'string' ? obj.name : null;
+  } catch {
+    return null;
+  }
+}
+
+/** repo root 찾기 — git rev-parse, 실패 시 cwd 자체. */
+function findRepoRoot(cwd: string): string {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd,
+    encoding: 'utf-8',
+  });
+  if (result.status === 0) {
+    return result.stdout.trim();
+  }
+  return resolve(cwd);
+}
+
+/** repo root 의 git remote origin 에서 modfolio/<repo> 형식 추출. */
+function readGhRepo(repoRoot: string): string | undefined {
+  const result = spawnSync('git', ['remote', 'get-url', 'origin'], {
+    cwd: repoRoot,
+    encoding: 'utf-8',
+  });
+  if (result.status !== 0) return undefined;
+  const url = result.stdout.trim();
+  // 패턴: https://github.com/org/repo.git, git@github.com:org/repo.git, ssh://...:port/org/repo.git
+  const httpsMatch = url.match(/github\.com[/:]([^/]+)\/([^/.\s]+)(?:\.git)?$/);
+  if (httpsMatch) return `${httpsMatch[1]}/${httpsMatch[2]}`;
+  return undefined;
+}
+
+/** repo 안에서 wrangler 설정 파일 모두 발견 (apps/* 및 root). node_modules 제외. */
+function findWranglerConfigs(repoRoot: string, maxDepth = 4): string[] {
+  const results: string[] = [];
+  function walk(dir: string, depth: number): void {
+    if (depth > maxDepth) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (name === 'node_modules' || name === '.git' || name.startsWith('.')) continue;
+      const full = join(dir, name);
+      let s: ReturnType<typeof statSync>;
+      try {
+        s = statSync(full);
+      } catch {
+        continue;
+      }
+      if (s.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (name === 'wrangler.jsonc' || name === 'wrangler.toml') {
+        results.push(full);
+      }
+    }
+  }
+  walk(repoRoot, 0);
+  return results;
+}
+
+export function inferAdoptContext(cwd: string): AdoptInferred {
+  const repoRoot = findRepoRoot(cwd);
+  const ghRepo = readGhRepo(repoRoot);
+  const configs = findWranglerConfigs(repoRoot);
+  const workers: WrangerWorker[] = [];
+  for (const path of configs) {
+    const name = readWranglerName(path);
+    if (!name) continue;
+    const dir = dirname(path);
+    const rel = relative(repoRoot, dir) || '.';
+    workers.push({ name, cwd: dir, rootDirectory: rel });
+  }
+  return { workers, ghRepo, repoRoot };
+}
+
+/** GitHub API 로 repo id + owner id 가져오기 (gh CLI 사용). */
+export function fetchGhRepoMeta(
+  ghRepo: string,
+): { repoId: string; ownerId: string; ownerLogin: string } | null {
+  const result = spawnSync('gh', ['api', `/repos/${ghRepo}`], { encoding: 'utf-8' });
+  if (result.status !== 0) return null;
+  try {
+    const meta = JSON.parse(result.stdout) as {
+      id: number;
+      owner: { id: number; login: string };
+    };
+    return {
+      repoId: String(meta.id),
+      ownerId: String(meta.owner.id),
+      ownerLogin: meta.owner.login,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** test helpers — 단순 export */
+export const __test = { parseJsonc, readWranglerName, findWranglerConfigs };

package/src/lib/auth-context.ts

@@ -2,19 +2,54 @@ import { AthsraClient } from './client.ts';
 import { type Config, loadConfig } from './config.ts';
 import { getMasterPw, getToken } from './keyring.ts';
 
-export interface AuthContext {
+/** User token mode — keyring 의 master pw + Bearer token 보유, full access. */
+export interface UserAuthContext {
+  kind: 'user';
   config: Config;
   masterPw: string;
   token: string;
   client: AthsraClient;
 }
 
+/** Service token mode — ATHSRA_TOKEN env, scoped + read/write, master pw 없이 envelope 복호. */
+export interface ServiceAuthContext {
+  kind: 'service';
+  /** ats_* token 문자열 — 동시에 Argon2id 의 wrap secret. */
+  tokenSecret: string;
+  /** envelope.recipients[].id — 헤들리스 unwrap 시 매칭. */
+  recipientId: string;
+  /** scope: 단일 project. */
+  scopeProject: string;
+  /** scope: read 또는 write. */
+  scopePerms: 'read' | 'write';
+  client: AthsraClient;
+  workerUrl: string;
+}
+
+export type AuthContext = UserAuthContext | ServiceAuthContext;
+
 /**
- * 모든 인증 요구 commands (set/get/ls/run/doctor 부분) 의 공통 진입점.
+ * 모든 인증 요구 commands 의 공통 진입점. 두 모드 자동 dispatch:
+ *
+ *   - **user (기본)** — `~/.athsra/config.json` + OS keyring 의 master pw + token.
+ *     keyring 없으면 → null + 안내 (athsra login).
  *
- * 실패 시 적절한 에러 메시지 출력 + null 반환. 호출자는 `return 1` 만.
+ *   - **service (headless)** — `ATHSRA_TOKEN=ats_*` env 가 있으면 keyring/config 우회.
+ *     worker URL 은 `ATHSRA_WORKER_URL` env 또는 config.json fallback.
+ *     worker `/auth/whoami` 로 scope (project + perms + recipient_id) 확인.
+ *     NAS / CI 등 헤들리스 호스트 용 — master pw 없이 scoped 복호 가능.
+ *
+ * 실패 시 stderr 에 안내 + null 반환. 호출자는 `return 1` 만.
  */
-export function loadAuthContext(): AuthContext | null {
+export async function loadAuthContext(): Promise<AuthContext | null> {
+  const envToken = process.env.ATHSRA_TOKEN;
+  if (envToken?.startsWith('ats_')) {
+    return loadServiceContext(envToken);
+  }
+  return loadUserContext();
+}
+
+function loadUserContext(): UserAuthContext | null {
   const config = loadConfig();
   if (!config) {
     console.error('Not logged in. Run `athsra login` first.');
@@ -27,9 +62,47 @@ export function loadAuthContext(): AuthContext | null {
     return null;
   }
   return {
+    kind: 'user',
     config,
     masterPw,
     token,
     client: new AthsraClient(config.workerUrl, token),
   };
 }
+
+async function loadServiceContext(token: string): Promise<ServiceAuthContext | null> {
+  const config = loadConfig(); // optional in service mode
+  const workerUrl = process.env.ATHSRA_WORKER_URL ?? config?.workerUrl;
+  if (!workerUrl) {
+    console.error(
+      'service token 모드인데 worker URL 모름. `ATHSRA_WORKER_URL=https://...` 환경변수 또는 `~/.athsra/config.json` 필요.',
+    );
+    return null;
+  }
+  const client = new AthsraClient(workerUrl, token);
+  let me: Awaited<ReturnType<typeof client.whoami>>;
+  try {
+    me = await client.whoami();
+  } catch (err) {
+    console.error(`service token 검증 실패 (worker /auth/whoami): ${(err as Error).message}`);
+    return null;
+  }
+  if (
+    me.kind !== 'service' ||
+    !me.scopeProject ||
+    (me.scopePerms !== 'read' && me.scopePerms !== 'write') ||
+    !me.recipientId
+  ) {
+    console.error('whoami 응답에 service token scope 정보 없음 — worker 갱신 필요 (Phase 1.x.8+).');
+    return null;
+  }
+  return {
+    kind: 'service',
+    tokenSecret: token,
+    recipientId: me.recipientId,
+    scopeProject: me.scopeProject,
+    scopePerms: me.scopePerms,
+    client,
+    workerUrl,
+  };
+}

package/src/lib/auto-project.ts

@@ -0,0 +1,131 @@
+/**
+ * auto-project.ts — cwd 기반 athsra project 자동 감지.
+ *
+ * Doppler 의 `--project` flag 와 동일한 UX 격차 해소. modfolio universe 의 23 sibling
+ * repo 안에서 `cd ~/code/<repo>` 후 매 명령마다 `<project>` 인자 입력 마찰 제거.
+ *
+ * Precedence (높은 → 낮은):
+ *   1. --project=<x> flag (explicit override, args 에서 추출)
+ *   2. positional <project> arg (기존 동작 그대로 — 인자 첫 자리 + `=` 없음)
+ *   3. .athsra file (sibling repo 루트, KEY=value 형식 — project=<name> 한 줄)
+ *   4. package.json 의 athsra.project field
+ *   5. basename(cwd) (마지막 fallback — 23 sibling 의 표준 패턴 = repo 명 = project 명)
+ *
+ * 사용 (각 command 의 첫 줄):
+ *   const { project, rest, source } = resolveProject(args);
+ *   if (!project) { console.error(USAGE); return 2; }
+ *
+ * 정공법: args 첫 자리가 KEY=value 패턴이면 project 가 아닌 KEY=value 로 인식 → auto-detect.
+ *         첫 자리가 project name 이면 (= 없음) explicit 로 인식. 호환성 유지 (기존 명령 그대로).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+export interface ProjectResolution {
+  project: string | undefined;
+  /** project 명이 args 에서 빠진 나머지 args (KEY=value pairs 또는 다른 인자) */
+  rest: string[];
+  /** 어디서 감지했는가 — 디버깅 / 사용자 안내용 */
+  source: 'flag' | 'positional' | 'athsra-file' | 'package-json' | 'cwd' | 'none';
+}
+
+/**
+ * args 에서 --project=<x> flag 추출 + 나머지 args 반환.
+ */
+function extractProjectFlag(args: string[]): { project?: string; rest: string[] } {
+  const rest: string[] = [];
+  let project: string | undefined;
+  for (const arg of args) {
+    if (arg.startsWith('--project=')) {
+      project = arg.slice('--project='.length);
+    } else if (arg === '--project') {
+    } else {
+      rest.push(arg);
+    }
+  }
+  return project ? { project, rest } : { rest };
+}
+
+/**
+ * cwd 의 .athsra file 읽기 — `project=<name>` 한 줄 (다른 키 무시, 단순 KEY=value).
+ */
+function readAthsraFile(cwd: string): string | undefined {
+  const path = join(cwd, '.athsra');
+  if (!existsSync(path)) return undefined;
+  try {
+    const text = readFileSync(path, 'utf-8');
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq < 0) continue;
+      const key = trimmed.slice(0, eq).trim();
+      const value = trimmed.slice(eq + 1).trim();
+      if (key === 'project' && value) return value;
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/**
+ * cwd 의 package.json 의 athsra.project field 읽기.
+ */
+function readPackageJsonProject(cwd: string): string | undefined {
+  const path = join(cwd, 'package.json');
+  if (!existsSync(path)) return undefined;
+  try {
+    const pkg = JSON.parse(readFileSync(path, 'utf-8')) as { athsra?: { project?: string } };
+    return pkg.athsra?.project;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * args 에서 project 를 추출 (positional 또는 flag) + auto-detect fallback.
+ *
+ * @param args - command 호출 args (e.g. set 의 경우 ['modfolio-pay', 'KEY=val'] 또는 ['KEY=val'])
+ * @param opts.cwd - 자동 감지 시작 디렉토리 (기본 process.cwd())
+ * @param opts.requirePositional - true 면 positional 만 인식 (auto-detect 비활성). default false.
+ */
+export function resolveProject(
+  args: string[],
+  opts?: { cwd?: string; requirePositional?: boolean },
+): ProjectResolution {
+  // 1. --project=<x> flag 우선
+  const flagResult = extractProjectFlag(args);
+  if (flagResult.project) {
+    return { project: flagResult.project, rest: flagResult.rest, source: 'flag' };
+  }
+
+  const remaining = flagResult.rest;
+
+  // 2. positional <project> arg — 첫 자리 + `=` 없으면 project 로 인식
+  if (remaining.length > 0 && remaining[0] !== undefined && !remaining[0].includes('=')) {
+    return { project: remaining[0], rest: remaining.slice(1), source: 'positional' };
+  }
+
+  if (opts?.requirePositional) {
+    return { project: undefined, rest: remaining, source: 'none' };
+  }
+
+  // 3. .athsra file (auto-detect)
+  const cwd = opts?.cwd ?? process.cwd();
+  const fromFile = readAthsraFile(cwd);
+  if (fromFile) return { project: fromFile, rest: remaining, source: 'athsra-file' };
+
+  // 4. package.json athsra.project
+  const fromPkg = readPackageJsonProject(cwd);
+  if (fromPkg) return { project: fromPkg, rest: remaining, source: 'package-json' };
+
+  // 5. basename(cwd) — 23 sibling 표준 = repo 명 = project 명
+  const base = basename(cwd);
+  if (base && base !== '/' && base !== '~' && base !== '.') {
+    return { project: base, rest: remaining, source: 'cwd' };
+  }
+
+  return { project: undefined, rest: remaining, source: 'none' };
+}