@twentyoz/alexx-cli 0.3.0

package/README.md

@@ -0,0 +1,120 @@
+# `alexx` — Alexx CLI
+
+AI 에이전트(및 사람)가 터미널에서 Alexx 를 조작하기 위한 CLI. **Front Backend REST API(`/api`)** 를 호출하므로 인증·권한·UUIDv47 facade·비즈니스 로직을 그대로 따른다 (DB 직접 접근 없음).
+
+## 설계 (AI 친화)
+
+- **기본 출력은 JSON** (stdout, 단일 객체/배열). `--pretty` 로 들여쓰기
+- **에러는 구조화 JSON** (stderr): `{"error":{"code","message","hint"}}`. `hint` 가 다음 행동을 안내
+- **Exit code**: `0` 성공 / `1` 일반 / `2` 사용법 / `3` 인증 / `4` not found
+- **비대화형 기본**: 프롬프트 없음(파괴적 명령만 TTY 확인). 파괴적 명령은 비-TTY 에서 `--yes` 필요
+- **escape hatch**: `alexx api <METHOD> <path>` 로 CLI 가 감싸지 않은 엔드포인트도 직접 호출
+
+## 설치 / 환경(endpoint)
+
+endpoint 는 **빌드 시점에 baked** 되고 런타임/CLI 플래그/env 로는 **변경 불가** — AI 에이전트가 임의로 dev/prod 를 건드리지 못하게 하는 가드레일. `alexx --help` 에 현재 박힌 endpoint 가 표시된다.
+
+```bash
+# 일반 사용자 — npm 발행본 (운영 endpoint baked)
+npm i -g @twentyoz/alexx-cli
+
+# 로컬 개발 — 소스에서 빌드 (기본 local)
+make install-cli                 # env=local — npm install + build + 글로벌 link
+make install-cli env=dev         # dev 로 박아서 설치
+make build-cli env=prod          # 빌드만, prod 로 박기
+cd web/cli && ALEXX_ENV=dev npm run dev -- --help
+```
+
+환경별 URL 은 `.env` 의 `ALEXX_API_BASE_{LOCAL,DEV,PROD}` 에서 읽는다 (`.env.template` 참고).
+배포 빌드는 `ALEXX_API_BASE_URL` 직접 주입 가능(우선). **local 만 미설정 시 localhost 폴백, dev/prod 는 미해결 시 빌드 실패**(오발행 방지).
+
+### npm 발행
+
+```bash
+make release-cli                  # 현재 version 으로 발행 (운영 endpoint)
+make release-cli version=patch    # version bump 후 발행
+```
+
+- 발행본은 항상 **운영 endpoint baked** — `npm publish` 는 `ALEXX_ENV=prod` 일 때만 허용(`prepublishOnly` 가드)
+- 발행 머신의 `.env` 에 `ALEXX_API_BASE_PROD` 필요 (또는 `ALEXX_API_BASE_URL` 주입). 사전 `npm login` (스코프 `@twentyoz`)
+- 레지스트리는 public npmjs 기본(`publishConfig.access=public`). private/GitHub Packages 로 바꾸려면 `publishConfig.registry` 추가
+
+| 환경 | 기본 URL (`.env.template`) |
+|------|----------------------------|
+| local | `http://localhost:30042/api` |
+| dev | `https://alexx.twentyoz.dev/api` |
+| prod | `https://alexx.app/api` |
+
+## 인증
+
+| 항목 | 우선순위 |
+|------|----------|
+| 토큰 | `--token` / `ALEXX_TOKEN`(access only, refresh 없음) > 저장 토큰(`alexx auth login`, 401 시 자동 refresh) |
+
+저장 위치: `${XDG_CONFIG_HOME:-~/.config}/alexx/config.json` (권한 0600). endpoint 는 baked 라 저장하지 않음.
+
+로그인은 **브라우저 위임만** 지원한다(captcha·Google·이메일/비번 모두 브라우저에서). 비밀번호를 CLI
+인자/env 로 직접 받지 않는다 — argv/`ps` 노출과 captcha 우회를 막기 위함. 헤드리스/CI 는 `ALEXX_TOKEN`.
+
+```bash
+# 대화형 로그인 (브라우저 자동 오픈 → loopback 으로 토큰 수신)
+alexx auth login
+alexx auth whoami
+
+# SSH/헤드리스: 브라우저를 띄울 수 없으면 코드 붙여넣기 (자동 감지되며, 강제하려면 --code)
+alexx auth login --code
+
+# CI/에이전트(비대화형): 토큰 직접 주입 (refresh 없음)
+ALEXX_TOKEN=<access_jwt> alexx auth whoami
+```
+
+## 워크플로 (Search → Fetch → Act)
+
+```bash
+alexx rec ls --limit 10                 # 또는: alexx rec search "분기 회의"
+alexx rec upload meeting.m4a --wait     # 완료까지 대기(진행은 stderr) 후 상세 JSON
+alexx rec transcript <id> --text        # 화자: 발화
+alexx rec summarize <id> --language ko  # AI 요약 재생성
+alexx rec chat <id> "핵심 결정사항만 정리해줘"
+```
+
+## 명령
+
+| 명령 | 설명 |
+|------|------|
+| `alexx auth login\|logout\|whoami` | 인증/토큰 |
+| `alexx rec ls [--cursor --limit --tag --trash --all]` | 목록 (alias: `alexx ls`). `--trash` = 휴지통 목록(`collection=trash`, 항목에 `deleted_at`·`purge_at` 포함) |
+| `alexx rec search <query> [--limit --tag]` | 전문검색 |
+| `alexx rec get <id> [--waveform]` | 상세 (기본 waveform 생략, alias: `alexx get`) |
+| `alexx rec status <id>` | 경량 상태/진행률 (폴링용) |
+| `alexx rec upload <file> [--wait --skip-summary --template --timezone --force --context]` | 업로드 (alias: `alexx upload`). `--context` = 주제·참석자·고유명사 배경 설명(≤2000자) — AI 후처리(다듬기·요약·화자 분석)가 표기 근거로 사용. 업로드 후 수정은 `alexx api PATCH /recs/<id> --data '{"context":"..."}'` |
+| `alexx rec watch <id>` | 진행률 SSE → JSON 라인 스트림 |
+| `alexx rec transcript <id> [--text]` | 전사 결과 |
+| `alexx rec notes <id> [--ai]` | 노트 (`--ai` 로 AI 요약만) |
+| `alexx rec summarize <id> [--language --template --data]` | 요약 재생성 |
+| `alexx rec chat <id> <message...> [--thread --language --data]` | AI 채팅 (alias: `alexx chat`) |
+| `alexx rec retry <id>` | 재시도 |
+| `alexx rec rm <id> [--permanent --yes]` | 휴지통으로 이동(30일 뒤 자동 영구 삭제, 확인 없음). `--permanent` = 즉시 영구 삭제(DB+S3, 이때만 `--yes`/확인 프롬프트) |
+| `alexx rec restore <id>` | 휴지통에서 복구 |
+| `alexx rec empty-trash [--yes]` | 휴지통 비우기 — 전부 영구 삭제 (비-TTY 는 `--yes` 필수) |
+| `alexx templates` / `tags` | 읽기 전용 보조 |
+| `alexx api <METHOD> <path> [--data <json\|@file> -q k=v ...]` | escape hatch |
+
+### `--data` / `api` 예시
+
+```bash
+alexx rec chat <id> --data '{"message":"요약","language":"en"}'
+alexx api POST /recs/<id>/split --data @body.json
+alexx api GET /recs -q limit=5 -q tag=<tagId>
+alexx api PATCH /recs/<id>/speakers --data '{"name_map":{"s1":"홍길동"}}'
+```
+
+긴 꼬리 엔드포인트(split, detect-boundaries, speakers 변경, contacts, shares, tier, note/template CRUD)는 `alexx api` 로 호출한다.
+
+## MCP
+
+AI 도구 연동은 CLI 가 아니라 원격 MCP 서버(`https://alexx.app/mcp`, OAuth 로그인)를 쓴다. 등록 방법은 공개 문서 `/docs/mcp` 를 따른다.
+
+## 검증
+
+`npm test`로 SSE의 한글·CRLF 청크 경계와 콜백 오류·조기 종료 시 연결 정리, rec id 경로 인코딩을 검증한다. 실제 API 호출은 없다.

package/dist/action.js

@@ -0,0 +1,12 @@
+// commander action 공통 래퍼 — 모든 서브명령이 반복하던
+// `handler(async (..., command) => { const client = clientFromCommand(command); ... })`
+// 보일러플레이트를 흡수한다. 마지막 인자(Command)에서 클라이언트를 만들어 첫 인자로 주입.
+import { clientFromCommand } from "./client.js";
+import { handler } from "./output.js";
+export function withClient(fn) {
+    return handler(async (...args) => {
+        const command = args[args.length - 1];
+        const rest = args.slice(0, -1);
+        await fn(clientFromCommand(command), ...rest);
+    });
+}

package/dist/cli-login.js

@@ -0,0 +1,185 @@
+// 브라우저 위임 로그인 — captcha·Google OAuth·이메일/비번을 전부 브라우저에서 처리하고
+// 토큰만 CLI 로 돌려받는다(gh auth login 방식). CLI 는 자격증명·captcha 를 직접 다루지 않는다.
+//
+//   loopback (기본): 127.0.0.1 임시 포트에 서버를 띄우고 브라우저가 /cli-login 에서 로그인하면
+//                    토큰이 http://127.0.0.1:<port>/callback 로 redirect 돼 자동 수신.
+//   code (--code)  : loopback 불가 환경(SSH 등). 브라우저에서 받은 코드를 터미널에 붙여넣기.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { ApiClient } from "./client.js";
+import { resolveBaseUrl } from "./config.js";
+import { AppError } from "./output.js";
+import { prompt } from "./prompt.js";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+/** CLI 는 API base 만 baked 로 알고 FE origin 은 모르므로 BE 에서 받아온다. */
+async function fetchFrontFeUrl() {
+    const client = new ApiClient({ baseUrl: resolveBaseUrl(), useStore: false });
+    const cfg = await client.request("GET", "/auth/cli/config", { auth: false });
+    const url = cfg.front_fe_url?.replace(/\/$/, "");
+    if (!url) {
+        throw new AppError("config", "Server did not return a web URL for CLI login.", {
+            hint: "Use a personal token instead: ALEXX_TOKEN=<token> alexx …",
+        });
+    }
+    return url;
+}
+/**
+ * loopback 콜백이 닿을 수 있는 "로컬" 브라우저를 띄울 수 있는 환경인가.
+ * 원격(SSH)·헤드리스(Linux 무 DISPLAY)면 false — 이 경우 호출부가 코드 흐름으로 전환한다
+ * (원격에선 브라우저가 사용자 로컬 머신에 떠서 remote 127.0.0.1 에 못 닿기 때문).
+ */
+export function canOpenLocalBrowser() {
+    const env = process.env;
+    // SSH 원격 세션 — 브라우저는 사용자 로컬 머신, remote loopback 도달 불가.
+    if (env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT)
+        return false;
+    // Linux 무 디스플레이 — GUI 브라우저 자체가 없음 (macOS/Windows 는 DISPLAY 미사용).
+    // $BROWSER 가 있으면(원격개발 헬퍼 등) 띄울 수 있다고 본다.
+    if (process.platform === "linux" &&
+        !env.DISPLAY &&
+        !env.WAYLAND_DISPLAY &&
+        !env.BROWSER) {
+        return false;
+    }
+    return true;
+}
+/** 시스템 기본(또는 $BROWSER) 브라우저로 URL 열기. 자식 프로세스 반환(스폰 실패 시 null). */
+function spawnBrowser(url) {
+    const custom = process.env.BROWSER;
+    const [cmd, args] = custom
+        ? [custom, [url]]
+        : process.platform === "darwin"
+            ? ["open", [url]]
+            : process.platform === "win32"
+                ? // `cmd /c start` 는 URL 의 &(쿼리 구분자)를 명령 구분자로 오해해 첫 파라미터만 연다
+                    // (state/mode 유실 → 콜백 미수신 → 5분 타임아웃). rundll32 FileProtocolHandler 는
+                    // 셸 재파싱 없이 URL 전체를 기본 브라우저로 연다.
+                    ["rundll32", ["url.dll,FileProtocolHandler", url]]
+                : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.unref();
+        return child;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * loopback 흐름. 127.0.0.1 임시 포트에 일회성 서버를 띄우고, /cli-login 이 토큰을
+ * /cb 로 redirect 할 때까지 기다린다. `open=false` 면 자동 실행 없이 URL 만 안내한다.
+ */
+export async function loginViaLoopback(open = true) {
+    const frontFe = await fetchFrontFeUrl();
+    const state = randomBytes(16).toString("hex");
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            fn();
+        };
+        const server = createServer((req, res) => {
+            const u = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (u.pathname !== "/callback") {
+                res.writeHead(404, { connection: "close" });
+                res.end();
+                return;
+            }
+            const accessToken = u.searchParams.get("access_token");
+            const refreshToken = u.searchParams.get("refresh_token");
+            const st = u.searchParams.get("state");
+            const ok = st === state && !!accessToken && !!refreshToken;
+            // 토큰만 받고 브라우저는 FE 의 성공/에러 화면(로고·i18n)으로 302 되돌린다 — CLI 가 응답한
+            // 맨 HTML 을 사용자에게 안 보이게. Connection: close + 응답 후 소켓 정리로 keep-alive
+            // 소켓이 이벤트 루프를 붙잡아 프로세스가 안 끝나던 문제를 방지.
+            res.writeHead(302, {
+                location: `${frontFe}/cli-login?status=${ok ? "success" : "error"}`,
+                connection: "close",
+            });
+            res.on("finish", () => setTimeout(() => server.closeAllConnections?.(), 200));
+            res.end();
+            if (ok) {
+                finish(() => resolve({ access_token: accessToken, refresh_token: refreshToken }));
+            }
+            else {
+                finish(() => reject(new AppError("auth", "Login callback was invalid (state mismatch).", {
+                    exitCode: 3,
+                })));
+            }
+        });
+        server.on("error", (err) => finish(() => reject(new AppError("network", `Could not start local login server: ${err.message}`, {
+            hint: "Try `alexx auth login --code` (no local server, works over SSH).",
+        }))));
+        const timer = setTimeout(() => finish(() => reject(new AppError("timeout", "Login timed out.", {
+            hint: "Try `alexx auth login --code` — open the URL on any device and paste the code back.",
+            exitCode: 3,
+        }))), LOGIN_TIMEOUT_MS);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            const url = `${frontFe}/cli-login?port=${port}&state=${state}&mode=lb`;
+            process.stderr.write((open
+                ? "Opening your browser to sign in…\n"
+                : "Open this URL in your browser to sign in:\n") +
+                `  ${url}\n` +
+                "Waiting for you to finish in the browser… (Ctrl+C to cancel)\n");
+            if (open) {
+                const child = spawnBrowser(url);
+                // 브라우저를 못 띄우면 loopback 으로는 진행 불가 → 전용 코드로 즉시 reject 해 호출부가
+                // 코드 흐름으로 폴백하게 한다(5분 타임아웃 대기 X). 두 실패 경로를 모두 잡는다:
+                //   ① spawn 자체 실패(런처 부재 ENOENT 등) → 'error'
+                //   ② 런처는 떴지만 핸들러 없음/실패로 0 아닌 코드 종료(xdg-open 3/4, open 비0) → 'exit'
+                // 정상 핸드오프는 exit 0 이라 무시되고, 그 사이 /cb 가 먼저 오면 finish 가 멱등이라 안전.
+                const failOpen = () => finish(() => reject(new AppError("browser_open_failed", "Could not open a browser.", {
+                    exitCode: 3,
+                })));
+                if (!child) {
+                    failOpen();
+                }
+                else {
+                    child.on("error", failOpen);
+                    child.on("exit", (code) => {
+                        if (code)
+                            failOpen();
+                    });
+                }
+            }
+        });
+    });
+}
+/** code 흐름. 브라우저에서 로그인 후 표시되는 코드를 터미널에 붙여넣는다(loopback 불필요). */
+export async function loginViaCode() {
+    const frontFe = await fetchFrontFeUrl();
+    const state = randomBytes(16).toString("hex");
+    const url = `${frontFe}/cli-login?state=${state}&mode=code`;
+    process.stderr.write("Open this URL in any browser, sign in, then paste the code below:\n" + `  ${url}\n`);
+    const raw = await prompt("Paste code: ");
+    if (!raw) {
+        throw new AppError("usage", "No code provided.", {
+            hint: "Re-run `alexx auth login --code` and paste the code shown in the browser.",
+            exitCode: 2,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(raw.trim(), "base64url").toString("utf8"));
+    }
+    catch {
+        throw new AppError("usage", "The code could not be decoded.", {
+            hint: "Copy the full code from the browser and paste it again.",
+            exitCode: 2,
+        });
+    }
+    if (decoded.state !== state) {
+        throw new AppError("auth", "Code did not match this login session.", { exitCode: 3 });
+    }
+    if (!decoded.access_token || !decoded.refresh_token) {
+        throw new AppError("auth", "The code did not contain valid tokens.", { exitCode: 3 });
+    }
+    return { access_token: decoded.access_token, refresh_token: decoded.refresh_token };
+}

package/dist/client.js

@@ -0,0 +1,196 @@
+// HTTP 클라이언트: fetch 래퍼 + 401 자동 refresh + SSE + multipart 업로드 + 에러 정규화.
+// 외부 HTTP 의존성 없이 Node 22 내장 fetch/FormData/openAsBlob/ReadableStream 사용.
+import { openAsBlob } from "node:fs";
+import { basename } from "node:path";
+import { httpError } from "./errors.js";
+import { loadConfig, saveConfig, resolveBaseUrl, } from "./config.js";
+export class ApiClient {
+    baseUrl;
+    token;
+    refreshToken;
+    useStore;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl;
+        this.token = opts.token;
+        this.refreshToken = opts.refreshToken;
+        this.useStore = opts.useStore;
+    }
+    // ── URL 조립 ──
+    // baseUrl 은 .../api 를 포함. path 가 /api/ 로 시작하면 중복 제거.
+    // URL 파서가 `..` 를 정규화하므로 외부 입력 id 는 recPath() 처럼 인코딩해 넣는다.
+    buildUrl(path, query) {
+        let p = path.startsWith("/") ? path : "/" + path;
+        if (this.baseUrl.endsWith("/api") && p.startsWith("/api/")) {
+            p = p.slice(4);
+        }
+        const url = new URL(this.baseUrl + p);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, v);
+            }
+        }
+        return url;
+    }
+    async fetchOnce(method, url, opts, token) {
+        const headers = { ...(opts.headers ?? {}) };
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        let payload;
+        if (opts.form) {
+            payload = opts.form;
+        }
+        else if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(opts.body);
+        }
+        return fetch(url, { method, headers, body: payload });
+    }
+    /** 저장된 refresh_token 으로 토큰 재발급 후 config 갱신. 성공 시 true. */
+    async tryRefresh() {
+        if (!this.refreshToken)
+            return false;
+        try {
+            const res = await this.fetchOnce("POST", this.buildUrl("/auth/refresh").toString(), { body: { refresh_token: this.refreshToken }, headers: { "X-Client": "cli" } });
+            if (!res.ok)
+                return false;
+            const data = (await res.json());
+            this.token = data.access_token;
+            this.refreshToken = data.refresh_token;
+            const cfg = loadConfig();
+            saveConfig({
+                ...cfg,
+                access_token: data.access_token,
+                refresh_token: data.refresh_token,
+                user: data.user ?? cfg.user,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async request(method, path, opts = {}) {
+        const useAuth = opts.auth !== false;
+        const url = this.buildUrl(path, opts.query).toString();
+        let res = await this.fetchOnce(method, url, opts, useAuth ? this.token : undefined);
+        if (res.status === 401 && useAuth && this.useStore && (await this.tryRefresh())) {
+            res = await this.fetchOnce(method, url, opts, this.token);
+        }
+        return this.handle(res);
+    }
+    /** multipart 파일 업로드. `file` 필드 + 추가 문자열 필드. */
+    async upload(path, filePath, fields) {
+        const form = new FormData();
+        const blob = await openAsBlob(filePath);
+        form.append("file", blob, basename(filePath));
+        for (const [k, v] of Object.entries(fields)) {
+            if (v !== undefined)
+                form.append(k, v);
+        }
+        return this.request("POST", path, { form });
+    }
+    /** SSE 스트림. onEvent 가 true 를 반환하면 스트림 종료. */
+    async sse(path, onEvent) {
+        const url = this.buildUrl(path).toString();
+        const doFetch = (token) => fetch(url, {
+            headers: {
+                Accept: "text/event-stream",
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            },
+        });
+        let res = await doFetch(this.token);
+        if (res.status === 401 && this.useStore && (await this.tryRefresh())) {
+            res = await doFetch(this.token);
+        }
+        if (!res.ok || !res.body) {
+            await this.handle(res); // throws
+            return;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        let ended = false;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done) {
+                    ended = true;
+                    break;
+                }
+                buf = (buf + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+                let idx;
+                while ((idx = buf.indexOf("\n\n")) !== -1) {
+                    const chunk = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const ev = parseSseEvent(chunk);
+                    if (ev && onEvent(ev) === true)
+                        return;
+                }
+            }
+        }
+        finally {
+            if (!ended)
+                await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
+    async handle(res) {
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (res.ok)
+            return data;
+        let rawMsg;
+        if (data && typeof data === "object") {
+            rawMsg = data.message ?? data.error;
+        }
+        rawMsg = rawMsg ?? res.statusText ?? `HTTP ${res.status}`;
+        const message = Array.isArray(rawMsg) ? rawMsg.join(", ") : String(rawMsg);
+        throw httpError(res.status, message);
+    }
+}
+function parseSseEvent(chunk) {
+    let type = "message";
+    const dataLines = [];
+    for (const line of chunk.split("\n")) {
+        if (line.startsWith(":"))
+            continue; // comment
+        if (line.startsWith("event:"))
+            type = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+    }
+    if (dataLines.length === 0)
+        return null;
+    return { type, data: dataLines.join("\n") };
+}
+/**
+ * 클라이언트 구성. base URL 은 빌드 시 baked 된 고정값 (변경 불가).
+ * 토큰만 --token/ALEXX_TOKEN 으로 주입 가능 (access only, refresh 불가), 없으면 저장 토큰.
+ */
+export function makeClient(globalOpts) {
+    const baseUrl = resolveBaseUrl();
+    const envToken = globalOpts.token || process.env.ALEXX_TOKEN;
+    if (envToken) {
+        return new ApiClient({ baseUrl, token: envToken, useStore: false });
+    }
+    const cfg = loadConfig();
+    return new ApiClient({
+        baseUrl,
+        token: cfg.access_token,
+        refreshToken: cfg.refresh_token,
+        useStore: true,
+    });
+}
+export function clientFromCommand(cmd) {
+    const g = cmd.optsWithGlobals();
+    return makeClient({ token: g.token });
+}

package/dist/commands/api.js

@@ -0,0 +1,43 @@
+// api: escape hatch — 임의 /api 엔드포인트를 인증·refresh 적용해 직접 호출.
+// CLI 가 감싸지 않은 엔드포인트(split, detect-boundaries, speakers, contacts, shares,
+// tier, note/template CRUD 등)를 에이전트가 그대로 사용할 수 있게 한다.
+import { clientFromCommand } from "../client.js";
+import { AppError, printJson, handler } from "../output.js";
+import { parseDataOption } from "../data.js";
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+export function registerApi(program) {
+    program
+        .command("api <method> <path>")
+        .description("Call any /api endpoint directly (e.g. alexx api POST /recs/<id>/split --data @body.json)")
+        .option("--data <json>", "raw JSON body (@file / @- stdin)")
+        .option("-q, --query <kv...>", "query parameter k=v (repeatable)")
+        .action(handler(async (method, path, opts, command) => {
+        const m = method.toUpperCase();
+        if (!METHODS.has(m)) {
+            throw new AppError("usage", `Unsupported method: ${method}`, {
+                hint: `Use one of: ${[...METHODS].join(", ")}.`,
+                exitCode: 2,
+            });
+        }
+        const query = {};
+        for (const kv of opts.query ?? []) {
+            const i = kv.indexOf("=");
+            if (i === -1) {
+                throw new AppError("usage", `--query must be in k=v form: ${kv}`, {
+                    exitCode: 2,
+                });
+            }
+            const k = kv.slice(0, i);
+            const v = kv.slice(i + 1);
+            // 중복 키는 덮어쓰지 않고 콤마로 결합 — 서버가 ?ids=a,b,c 콤마 리스트를 지원하므로
+            // `-q ids=a -q ids=b` 가 ids=a,b 로 합쳐진다 (silent 손실 방지).
+            query[k] = k in query ? `${query[k]},${v}` : v;
+        }
+        const client = clientFromCommand(command);
+        const res = await client.request(m, path, {
+            query,
+            body: parseDataOption(opts.data),
+        });
+        printJson(res ?? null);
+    }));
+}

package/dist/commands/auth.js

@@ -0,0 +1,92 @@
+// auth: login / logout / whoami
+import { ApiClient, clientFromCommand } from "../client.js";
+import { resolveBaseUrl, saveConfig, clearConfig } from "../config.js";
+import { loginViaLoopback, loginViaCode, canOpenLocalBrowser, } from "../cli-login.js";
+import { AppError, printJson, handler } from "../output.js";
+/**
+ * 브라우저 위임 로그인 진입점. loopback(로컬 브라우저) 우선, 불가하면 코드 붙여넣기로 폴백.
+ *   --code            : 코드 흐름 강제 (SSH/헤드리스에서 가장 확실).
+ *   --no-browser      : 자동 실행만 끄고 URL 출력 후 loopback 대기 (같은 머신에서 직접 열기).
+ *   비대화형(no TTY)  : 브라우저·붙여넣기 둘 다 불가 → ALEXX_TOKEN 안내하며 종료.
+ *   원격/헤드리스 감지: 코드 흐름으로 자동 전환 (loopback 콜백이 안 닿으므로).
+ *   그 외(로컬)       : loopback 시도, 브라우저를 못 띄우면 코드 흐름으로 폴백.
+ */
+async function browserLogin(opts) {
+    if (opts.code)
+        return loginViaCode();
+    if (!process.stdin.isTTY) {
+        throw new AppError("no_tty", "No interactive terminal for browser login.", {
+            hint: "Set ALEXX_TOKEN=<token> for headless use, or run `alexx auth login` in an interactive terminal.",
+            exitCode: 3,
+        });
+    }
+    // --no-browser: 사용자가 같은 머신에서 URL 을 직접 연다 → 자동 실행만 끄고 loopback 대기.
+    if (opts.browser === false)
+        return loginViaLoopback(false);
+    // 원격(SSH)·헤드리스면 loopback 콜백이 안 닿으므로 코드 흐름으로 자동 전환.
+    if (!canOpenLocalBrowser()) {
+        process.stderr.write("No local browser available (remote/headless session) — using paste-code login.\n");
+        return loginViaCode();
+    }
+    // 로컬: loopback 시도. 브라우저를 못 띄우면 코드 흐름으로 폴백.
+    try {
+        return await loginViaLoopback(true);
+    }
+    catch (err) {
+        if (err?.code === "browser_open_failed") {
+            process.stderr.write("Couldn't open a browser — switching to paste-code login.\n");
+            return loginViaCode();
+        }
+        throw err;
+    }
+}
+export function registerAuth(program) {
+    const auth = program.command("auth").description("Authentication and token management");
+    auth
+        .command("login")
+        .description("Sign in via the browser (captcha + Google + email/password) and store tokens.\n" +
+        "For headless/CI use, set ALEXX_TOKEN=<token> instead.")
+        .option("--code", "paste-code flow instead of a local callback (works over SSH/headless)")
+        .option("--no-browser", "don't auto-open a browser; print the URL and wait (same machine)")
+        .action(handler(async (options) => {
+        // 브라우저 위임 로그인만 지원 — captcha·Google·이메일/비번 모두 브라우저에서 처리한다.
+        // 비밀번호를 CLI 인자/env 로 직접 받지 않는다(argv/ps 노출·captcha 우회 방지). loopback
+        // 우선, 원격/헤드리스/실패 시 코드 붙여넣기로 폴백. 헤드리스/CI 는 ALEXX_TOKEN 을 쓴다.
+        const tokens = await browserLogin(options);
+        // 토큰만 받았으므로 프로필을 조회해 저장/출력에 채운다.
+        const client = new ApiClient({
+            baseUrl: resolveBaseUrl(),
+            token: tokens.access_token,
+            useStore: false,
+        });
+        const user = await client.request("GET", "/auth/me");
+        saveConfig({
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            user,
+        });
+        printJson({ ok: true, user });
+    }));
+    auth
+        .command("logout")
+        .description("Revoke the server session and delete stored tokens")
+        .action(handler(async (_options, command) => {
+        // 서버측 세션을 먼저 폐기(베스트에포트) — 실패해도 로컬 토큰은 지운다.
+        try {
+            const client = clientFromCommand(command);
+            await client.request("POST", "/auth/logout", {});
+        }
+        catch {
+            /* 토큰 만료/네트워크 실패 등 — 무시 */
+        }
+        clearConfig();
+        printJson({ ok: true });
+    }));
+    auth
+        .command("whoami")
+        .description("Show the current signed-in user (GET /auth/me)")
+        .action(handler(async (_options, command) => {
+        const client = clientFromCommand(command);
+        printJson(await client.request("GET", "/auth/me"));
+    }));
+}

package/dist/commands/meta.js

@@ -0,0 +1,20 @@
+// meta: 읽기 전용 보조 — templates / tags
+// (모델 선택은 CLI 에서 제외 — admin 기본 모델만 사용. models 명령·--*-model 플래그 없음)
+import { clientFromCommand } from "../client.js";
+import { printJson, handler } from "../output.js";
+export function registerMeta(program) {
+    program
+        .command("templates")
+        .description("List summary templates (system + your own)")
+        .action(handler(async (_opts, command) => {
+        const client = clientFromCommand(command);
+        printJson(await client.request("GET", "/summary-templates"));
+    }));
+    program
+        .command("tags")
+        .description("List tags")
+        .action(handler(async (_opts, command) => {
+        const client = clientFromCommand(command);
+        printJson(await client.request("GET", "/tags"));
+    }));
+}