@theplato/tiro-cli 0.2.1 → 0.3.0

package/SPEC.md

@@ -1,364 +0,0 @@
-# tiro-cli v1 SPEC
-
-> Status: **Active design** (2026-05-06) — backend OAuth 인프라 조사 완료, 변경 0으로 진행 가능 확인됨
-> Owner: yeoul / @theplato
-
-## 0. 한 줄 정체성
-
-> **tiro-cli 는 에이전트의 발이다.** MCP가 컨텍스트 안에서 작은 데이터를 다루는 손이라면, CLI는 큰 데이터를 disk로 옮기고 shell pipe 로 흘려보내는 발.
-
-## 1. 정체성 / 비정체성
-
-### 정체성
-- **Agent-first** read/export/share tool. 인간 power user 도 동시 만족
-- **Filesystem-first**: 결과물을 disk에 떨어뜨리고 metadata 만 stdout으로
-- **MCP feature parity**: tiro-mcp-server 의 14개 도구를 모두 동등하게 노출 + filesystem 확장
-- **Self-describing**: agent 가 docs 없이 `tiro schema` 로 자기 발견
-
-### 비정체성
-- 음성 파일 업로드/다운로드 (MCP 에서 PR #21로 제거됨, 일관성 유지) — v2 검토
-- 인간 GUI 의 대체재 (folder CRUD 등 interactive task 는 web)
-- Backoffice / admin 도구 (별도 surface)
-
-## 2. 아키텍처
-
-```
-tiro Backend (Kotlin) — /v1/external/* 40+ endpoints, OpenAPI 3.1 SSoT
-                          (external-api-docs/openapi.yaml)
-                                    │
-        ┌─────────────────┬─────────┼─────────────────┐
-        ▼                 ▼                           ▼
-   ┌──────────┐    ┌──────────────┐            ┌──────────┐
-   │ MCP      │    │ tiro-cli     │            │ Web UI   │
-   │ 14 tools │    │ 17 commands  │            │          │
-   │  (no     │    │ (MCP parity  │            │          │
-   │  voice)  │    │  + file ops) │            │          │
-   └──────────┘    └──────────────┘            └──────────┘
-```
-
-## 3. 패키지 / 배포
-
-| 항목 | 값 |
-|---|---|
-| npm package | **`@theplato/tiro-cli`** |
-| bin name | **`tiro`** |
-| 언어 | TypeScript (Node 20+, ESM) |
-| 배포 채널 | npm (1차), Homebrew tap (2차) |
-| 설치 | `npm install -g @theplato/tiro-cli` |
-
-**근거**: `tiro` 단일 이름은 npm에 squatted (Zyao89, abandoned v0.0.0). `@tiro` / `@theplato` 모두 가용. **product brand 가 user-facing 인 경우 product 이름 우선** (Stripe `@stripe/*`, Bolta `@bolta-io/cli` 패턴). 향후 `@tiro/sdk`, `@tiro/mcp-server` (rename 후) 등 자연 확장.
-
-## 4. 인증
-
-### 흐름 (3-tier)
-```
-1. TIRO_TOKEN env var 있음? → 그것 사용 (CI / agent 비대화 컨텍스트)
-2. OS Keychain에 토큰 있음? → 그것 사용
-3. 둘 다 없음? → "tiro auth login" 안내, exit code 78 (EX_CONFIG)
-```
-
-### `tiro auth login` — Authorization Code Flow + PKCE + loopback redirect
-
-```
-1. POST /v1/mcp/oauth/register (RFC 7591 Dynamic Client Registration)
-   body: { client_name: "tiro-cli", redirect_uris: ["http://127.0.0.1:<port>/callback"],
-           grant_types: ["authorization_code"], response_types: ["code"],
-           token_endpoint_auth_method: "none" }
-   → { client_id }
-
-2. PKCE 생성: code_verifier (43~128자 랜덤), code_challenge = base64url(sha256(code_verifier))
-3. state 생성 (32바이트 랜덤)
-4. 임시 HTTP 서버 시작 (ephemeral port)
-5. 브라우저 자동 오픈:
-   GET /v1/mcp/oauth/authorize?response_type=code&client_id=...
-       &redirect_uri=http://127.0.0.1:<port>/callback&state=...
-       &code_challenge=...&code_challenge_method=S256
-
-6. 사용자 Google OAuth → backend google/callback → tiro-client web callback
-   → 최종 http://127.0.0.1:<port>/callback?code=...&state=... 으로 리다이렉트
-
-7. CLI 의 임시 서버가 callback 수신 → state 검증
-
-8. POST /v1/mcp/oauth/token (form-encoded)
-   body: grant_type=authorization_code&code=...&redirect_uri=...
-        &client_id=...&code_verifier=...
-   → { access_token: <JWT 180일>, token_type: "Bearer", expires_in: ... }
-
-9. JWT 디코드 → sub (userId), exp 추출
-10. OS Keychain 에 토큰 저장 (service: "io.tiro.cli", account: "default")
-```
-
-### Headless / SSH / CI 환경
-- `TIRO_TOKEN` env var 사용 (별도 머신에서 로그인 후 토큰 복사)
-- Device Flow (RFC 8628) 는 백엔드 미지원 → v1.x follow-up
-
-### 토큰 저장
-- macOS Keychain / Linux Secret Service / Windows Credential Manager via `@napi-rs/keyring`
-- Fallback: `~/.config/tiro/auth.json` (perm 600), 평문 경고 표시
-
-## 5. 명령 트리 (v1, 17개)
-
-### 5.1 Auth (3) — 모든 환경에서 작동
-```
-tiro auth login    [--no-browser]        # Authorization Code + loopback
-tiro auth status   [--json]              # 현재 계정 / scope / expires
-tiro auth logout                         # Keychain 정리
-```
-
-### 5.2 Notes (5) — read-heavy 본진 (MCP `list_notes`, `search_notes`, `get_note`, `get_note_transcript` + 파일 export)
-```
-tiro notes list                          # GET /v1/external/notes
-  --folder <id> --limit <n> --cursor <c> --json|--pretty
-
-tiro notes search [query]                # POST /v1/external/notes/search
-  --speaker <name> --since <date> --until <date>
-  --folder <id> --limit <n> --cursor <c>
-  → NDJSON output (1 line = 1 note metadata)
-
-tiro notes get <guid>                    # GET /v1/external/notes/{guid} + paragraphs
-  --output <path>                        # 파일 저장 (stdout = path만, agent 컨텍스트 절약)
-  --format md|json|txt                   # default: md (TTY) / json (pipe)
-  --include transcript,summary,documents,participants
-
-tiro notes transcript <guid>             # GET /v1/external/notes/{guid}/paragraphs
-  --output <path> --format md|json|txt
-
-tiro notes export                        # bulk 다운로드 — CLI 킬러 명령
-  --query <q> --speaker <n> --since <d> --until <d> --folder <id>
-  --output-dir <dir>                     # 필수
-  --include transcript,summary,documents,share-link
-  --format md|json --concurrency <n>
-  → 디렉토리 + manifest.jsonl
-```
-
-### 5.3 Document Templates (2) — MCP `list_document_templates`, `get_document_template`
-```
-tiro templates list                      # GET /v1/external/note-document-templates
-  --json|--pretty
-
-tiro templates get <id>                  # GET /v1/external/note-document-templates/{id}
-  --output <path> --format md|json
-```
-
-### 5.4 Share Links (3) — MCP `create_share_link`, `get_share_link`, `delete_share_link`
-```
-tiro share-links create <noteGuid>       # PUT /v1/external/notes/{guid}/share-link
-  --password <pw>                        # 옵션: 비밀번호 보호
-  --no-password                          # 기존 비밀번호 제거
-
-tiro share-links get <noteGuid>          # GET .../share-link
-  --password <pw>                        # 비밀번호 검증
-
-tiro share-links delete <noteGuid>       # DELETE .../share-link
-```
-
-### 5.5 Folders (2) — MCP `search_user_folders`, `search_team_folders`
-```
-tiro folders search [query]              # search_user_folders + search_team_folders 통합
-  --scope user|team|all                  # default: all
-  --limit <n>
-  --json|--pretty
-```
-
-### 5.6 Self-describe (1)
-```
-tiro schema [<command>]                  # 명령 트리 + 입출력 JSON Schema (agent self-introspection)
-```
-
-### 5.7 ChatGPT Deep Research aliases (2) — MCP `search`, `fetch`
-> MCP에 있지만 CLI 에는 별도 명령 안 만듦. `notes search` 와 `notes get` 이 같은 기능 제공.
-> 호환 필요 시 `tiro search` / `tiro fetch` 별칭 추가 검토 (v1.x).
-
-## 6. `tiro --help`
-
-```
-tiro — AI notes & transcripts CLI
-
-USAGE
-  tiro <command> [options]
-
-COMMANDS
-  auth login            Sign in via OAuth (browser-based, PKCE)
-  auth status           Show current account and scopes
-  auth logout           Sign out and clear stored token
-
-  notes list            List recent notes
-  notes search          Search notes by speaker / date / folder
-  notes get             Get a single note (stdout or file)
-  notes transcript      Get raw transcript paragraphs
-  notes export          Bulk-export notes to a directory
-
-  templates list        List note document templates
-  templates get         Get a specific template
-
-  share-links create    Create or update a share link for a note
-  share-links get       Get the share link of a note
-  share-links delete    Delete a share link
-
-  folders search        Search user or team folders by keyword
-
-  schema                Print JSON Schema of a command (for agents)
-
-GLOBAL OPTIONS
-  --hostname <url>      API base URL (default: https://api.tiro.ooo)
-  --json                Force JSON output
-  --pretty              Force pretty (human) output
-  --quiet               Suppress non-error output
-  --verbose             Verbose logging to stderr
-  --no-color            Disable ANSI colors
-  --help                Show help for a command
-  --version             Print version
-
-ENVIRONMENT
-  TIRO_TOKEN            Bearer token (overrides keychain)
-  TIRO_HOSTNAME         API base URL
-  TIRO_OUTPUT_DIR       Default --output-dir for export commands
-  NO_COLOR              Disable colors (https://no-color.org/)
-
-EXAMPLES
-  tiro auth login
-  tiro notes search "Q3 Planning" --since 7d --json
-  tiro notes get <guid> --output ./meeting.md --include transcript,summary
-  tiro notes export --query "..." --output-dir ./backup --include transcript,summary
-```
-
-## 7. 출력 / 파일 / 에러 계약
-
-### 7.1 형식 자동 선택
-- `process.stdout.isTTY` true → pretty
-- `process.stdout.isTTY` false (pipe / file redirect) → JSON
-- `--json` / `--pretty` 로 강제
-
-### 7.2 파일 저장 시 stdout 계약
-파일 저장 (`--output`, `--output-dir`) 시 stdout 은 metadata 만:
-```json
-{"saved":"./meeting.md","size":5234,"format":"md","guid":"note-guid-123"}
-```
-
-### 7.3 파일 형식
-- **`.md`**: 인간 친화. YAML frontmatter + 마크다운 본문 + 화자별 단락
-- **`.json`**: 구조화. 전체 객체 그대로 (agent 파싱 친화)
-- **`.txt`**: 토큰 절약 / embedding 친화. `[화자] 텍스트` 만
-
-### 7.4 NDJSON streaming
-list / search 결과는 line-delimited (한 줄에 한 객체) — agent 가 `head` / `jq` 로 점진 처리
-
-### 7.5 Manifest (`manifest.jsonl`)
-bulk export 자동 생성. 한 줄에 한 항목:
-```jsonl
-{"guid":"note-guid-123","title":"Weekly standup","path":"./n1.md","size":5234,"status":"ok"}
-{"guid":"note-guid-789","path":null,"error":{"code":"not_found","message":"..."}}
-```
-
-### 7.6 에러 계약 (Bolta 패턴)
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "auth_required",
-    "message": "Token expired. Run `tiro auth login` to refresh.",
-    "suggestion": "tiro auth login",
-    "errorType": "unauthorized",
-    "httpStatus": 401,
-    "requestId": "req_abc123"
-  }
-}
-```
-
-### 7.7 Exit codes (sysexits.h)
-| Code | 의미 |
-|---|---|
-| 0 | 성공 |
-| 1 | generic error |
-| 2 | usage error |
-| 4 | auth required |
-| 64 | EX_USAGE |
-| 65 | EX_DATAERR |
-| 78 | EX_CONFIG (자격증명 부재) |
-
-### 7.8 토큰 노출 방지
-- 절대 stdout 에 토큰 직접 출력 금지
-- 로그 (`--verbose`) 에 토큰 prefix 4글자만
-- error message 에 token 헤더 echo 금지
-
-## 8. 의존성
-
-| | 패키지 | 이유 |
-|---|---|---|
-| runtime | `commander@12` | 인자 파싱, 자동 help |
-| runtime | `@napi-rs/keyring@1` | OS keychain (keytar 보다 모던, prebuild 안정) |
-| runtime | `conf@13` | XDG 호환 config 파일 |
-| runtime | `open@10` | 브라우저 자동 오픈 |
-| runtime | `zod@3` | 응답 런타임 검증 (mcp-server 와 일관) |
-| dev | `typescript@5.6+` | 타입 |
-| dev | `tsup@8` | esbuild 기반 번들 |
-| dev | `tsx@4` | TS 직접 실행 (dev) |
-| dev | `vitest@2` | 단위 테스트 |
-| dev | `@types/node@20` | Node 타입 |
-
-> HTTP 는 Node 20 내장 fetch — 추가 dep 0
-> Color 는 ANSI 코드 + isTTY 체크 자체 구현 — chalk/ora 미사용
-
-## 9. 프로젝트 구조
-
-```
-tiro-cli/
-├── src/
-│   ├── bin/tiro.ts                 # entry + commander setup
-│   ├── commands/
-│   │   ├── auth/{login,logout,status}.ts
-│   │   ├── notes/{list,search,get,transcript,export}.ts
-│   │   ├── templates/{list,get}.ts
-│   │   ├── share-links/{create,get,delete}.ts
-│   │   ├── folders/search.ts
-│   │   └── schema.ts
-│   └── lib/
-│       ├── api/{client,types}.ts
-│       ├── auth/{flow,keychain,pkce,loopback,browser}.ts
-│       ├── output/{format,tty,manifest}.ts
-│       ├── error.ts
-│       └── config.ts
-├── test/
-├── package.json
-├── tsconfig.json
-└── SPEC.md / README.md
-```
-
-## 10. 출시 마일스톤
-
-**v0.1 (이번 작업)** — auth 흐름 작동 + `tiro --help`
-- `tiro auth login` (Authorization Code + PKCE + loopback)
-- `tiro auth status`
-- `tiro auth logout`
-- `tiro --help`, `tiro --version`
-
-**v0.2** — notes core
-- `tiro notes list / search / get / transcript`
-- `--output`, `--format md|json|txt`
-
-**v0.3** — bulk export (킬러)
-- `tiro notes export` (manifest.jsonl)
-
-**v0.4** — 나머지
-- `tiro templates / share-links / folders / schema`
-
-**v1.0** — 안정화
-- 단위 테스트 ≥80%, e2e (assert_cmd 패턴), npm publish
-
-## 11. 미결 (다음 회차)
-
-- [ ] OAuth `client_id` 캐싱 정책 (DCR 30일 TTL — 재등록 자동화?)
-- [ ] Homebrew tap (`plato-corp/tiro`) — npm 단독 vs 병행
-- [ ] 텔레메트리 정책 (opt-out by default? GitHub CLI 백래시 사례)
-- [ ] Device Flow (RFC 8628) 백엔드 추가 — headless/SSH 지원 시점
-- [ ] `tiro completion bash|zsh|fish` 셸 자동완성
-- [ ] OpenAPI codegen (`openapi-typescript` + `openapi-fetch`) 도입 시점
-
-## 12. 참고
-
-- 1차 회차 결정: project memory `project_tiro_cli_design.md`
-- 위키 분석: `mcp-vs-api-vs-cli-agent-hands-feet.md` (yeoul, blog raw material)
-- API SSoT: `external-api-docs/openapi.yaml`
-- MCP 현재: tiro-mcp-server PR #21 머지 후 14 tools (voice 제거됨)
-- Backend OAuth: `api/.../McpOAuthController.kt`, `core/.../McpJwtService.kt`, `DynamicClient.kt`
-- 레퍼런스: gh CLI (Auth Code + GH_TOKEN), Stripe CLI (Device Flow), Bolta (`@bolta-io/cli`, agent-first)