@ait-co/console-cli 0.1.3 → 0.1.5

package/README.md

@@ -3,7 +3,7 @@
 > 🚧 **Pre-1.0 (`0.1.x`)** — published to npm but the surface is still small. `whoami` / `login` / `logout` / `upgrade` are usable today; `deploy` / `logs` / `status` are next on [TODO.md](./TODO.md).
 > 1.0 이전 단계입니다. 일부 명령(`whoami`/`login`/`logout`/`upgrade`)만 동작하고, `deploy`/`logs`/`status`는 진행 중입니다.
 
-`ait-console` is a community-maintained CLI for automating Apps in Toss developer console operations — log in once in a browser, then drive subsequent operations from your shell or from an AI coding agent via headless browser automation.
+`aitcc` is a community-maintained CLI for automating Apps in Toss developer console operations — log in once in a browser, then drive subsequent operations from your shell or from an AI coding agent via headless browser automation.
 
 앱인토스 콘솔을 CLI로 자동화하는 커뮤니티 도구. 최초 로그인만 브라우저로 하고, 이후 작업은 headless 브라우저로 처리한다. (MCP 모드는 후순위 — [TODO.md](./TODO.md) 참고.)
 
@@ -19,15 +19,15 @@
 curl -fsSL https://raw.githubusercontent.com/apps-in-toss-community/console-cli/main/install.sh | sh
 ```
 
-The installer detects OS (`uname -s`) and arch (`uname -m`), downloads the matching binary from the latest GitHub Release, verifies it against `SHA256SUMS`, and installs it to `$HOME/.local/bin/ait-console`. Node is **not** required.
+The installer detects OS (`uname -s`) and arch (`uname -m`), downloads the matching binary from the latest GitHub Release, verifies it against `SHA256SUMS`, and installs it to `$HOME/.local/bin/aitcc`. Node is **not** required.
 
 Pin a specific version:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/apps-in-toss-community/console-cli/main/install.sh | AIT_CONSOLE_VERSION=v0.1.1 sh
+curl -fsSL https://raw.githubusercontent.com/apps-in-toss-community/console-cli/main/install.sh | AITCC_VERSION=v0.1.1 sh
 ```
 
-Override the install directory with `AIT_CONSOLE_INSTALL_DIR=/custom/path` (default `$HOME/.local/bin`).
+Override the install directory with `AITCC_INSTALL_DIR=/custom/path` (default `$HOME/.local/bin`).
 
 ### npm (fallback)
 
@@ -43,38 +43,49 @@ This is the path that `agent-plugin` uses when a project already has Node instal
 ## Quick usage
 
 ```sh
-ait-console --version          # print the embedded version
-ait-console login              # open the browser, capture the OAuth callback on localhost, save the session
-ait-console login --no-browser # print the authorize URL instead of auto-opening a browser
-ait-console logout             # delete the local session file
-ait-console whoami             # show the currently logged-in user (exits non-zero if no session)
-ait-console whoami --json      # machine-readable output for scripts and agents
-ait-console upgrade            # self-update to the latest GitHub Release (binary installs only)
-ait-console upgrade --dry-run  # check for an update without downloading or replacing
-ait-console upgrade --force    # reinstall the latest release even if versions match
+aitcc --version          # print the embedded version
+aitcc login              # launch a browser window, sign in there, and capture the session cookies
+aitcc logout             # delete the local session file
+aitcc whoami             # show the currently logged-in user live from the console API
+aitcc whoami --offline   # use the cached identity without hitting the API
+aitcc whoami --json      # machine-readable output for scripts and agents
+aitcc upgrade            # self-update to the latest GitHub Release (binary installs only)
+aitcc upgrade --dry-run  # check for an update without downloading or replacing
+aitcc upgrade --force    # reinstall the latest release even if versions match
 ```
 
-`ait-console upgrade` respects `GITHUB_TOKEN` to avoid anonymous GitHub API rate limits.
+`aitcc upgrade` respects `GITHUB_TOKEN` to avoid anonymous GitHub API rate limits.
 
 Planned commands — `deploy`, `logs`, `status` — are tracked in [TODO.md](./TODO.md).
 
 ### Login details
 
-`ait-console login` spawns a short-lived HTTP server on `127.0.0.1:<random-port>` and waits for the OAuth provider to redirect back to `/callback` with a `code` and a `state` parameter. The `state` is a 32-byte crypto-random value generated per attempt and rechecked on arrival — any mismatch is rejected with a 400 and the login aborts. The server binds to the loopback interface only, listens for exactly one successful callback, and shuts down after either success or a 5-minute timeout (override with `--timeout <seconds>`).
+`aitcc login` launches a Chrome-family browser via the Chrome DevTools Protocol, navigates it to the Apps in Toss developer console sign-in URL, and waits for the main frame to reach the post-login workspace page. Once it does, the CLI dumps all cookies over CDP (including `HttpOnly` auth cookies that JavaScript can't see) and persists them to the local session file. The browser runs against a temporary, isolated `--user-data-dir` that is wiped on exit, so your everyday browser profile is never touched.
 
-The Apps in Toss developer console OAuth authorize URL is not publicly documented yet (see [CLAUDE.md](./CLAUDE.md) § "Open questions"). Until it is, set `AIT_CONSOLE_OAUTH_URL` (and optionally `AIT_CONSOLE_OAUTH_CLIENT_ID` / `AIT_CONSOLE_OAUTH_SCOPE`) to point at the real endpoint; without it, `login` exits with a usage error rather than calling a placeholder.
+The CLI looks for Chrome in the standard OS install locations (Google Chrome, Chromium, Microsoft Edge). Override the executable with `AITCC_BROWSER=/path/to/chrome` if your install is elsewhere; override the sign-in URL with `AITCC_OAUTH_URL` if you need to point at a staging environment. `--timeout <seconds>` controls how long the CLI will wait for sign-in to finish (default 300s).
 
 ## Session storage
 
 The local session lives at an XDG-compliant path with file mode `0600`:
 
-- Linux/macOS: `$XDG_CONFIG_HOME/ait-console/session.json` (fallback `~/.config/ait-console/session.json`)
-- Windows: `%APPDATA%\ait-console\session.json`
+- Linux/macOS: `$XDG_CONFIG_HOME/aitcc/session.json` (fallback `~/.config/aitcc/session.json`)
+- Windows: `%APPDATA%\aitcc\session.json`
 
-The containing directory is created with mode `0700`. Cookies and storage-state origins captured during login are **never** printed, logged, or attached to `--verbose` output — only `user.email` and `displayName` surface through `whoami`. Playwright screenshots are off by default.
+The containing directory is created with mode `0700`. Cookies captured during login are **never** printed, logged, or attached to `--verbose` output — only `user.email`, `name`, and workspace summary surface through `whoami`.
 
 See [CLAUDE.md](./CLAUDE.md) for the rationale behind using a plain `0600` file instead of an OS keychain.
 
+## Update notifications
+
+When running interactively, `aitcc` occasionally checks for a newer release and prints a one-line notice on stderr if one exists. The check is rate-limit friendly:
+
+- At most one network call every 24 hours, no matter how often you run commands.
+- Even a failed check updates the throttle window, so a broken network or a 403 from GitHub does not loop back within minutes.
+- Conditional GET (`If-None-Match`) — a 304 response does not consume the anonymous GitHub rate-limit bucket.
+- The check is skipped entirely when stdout is not a TTY, when `--json` is passed, or when `AITCC_NO_UPDATE_CHECK=1` is set.
+
+Cached state lives at `$XDG_CACHE_HOME/aitcc/upgrade-check.json` (fallback `~/.cache/aitcc/upgrade-check.json`).
+
 ## Machine-readable output (`--json`)
 
 Every command accepts `--json`. When set:
@@ -87,4 +98,4 @@ Every command accepts `--json`. When set:
 
 ## Status
 
-Scaffold complete. `whoami`, `login`, `logout`, and `upgrade` are implemented (`login` still needs the real Toss OAuth endpoint — override via `AIT_CONSOLE_OAUTH_URL`); `deploy`, `logs`, `status` are not yet — see [TODO.md](./TODO.md). See the [organization landing page](https://apps-in-toss-community.github.io/) for the full roadmap.
+`login`, `logout`, `whoami`, and `upgrade` are implemented end-to-end — `login` drives a real browser over CDP and `whoami` reads the live console member API. `deploy`, `logs`, `status` are next — see [TODO.md](./TODO.md). See the [organization landing page](https://apps-in-toss-community.github.io/) for the full roadmap.