gemiterm 2.0.0

package/openspec/specs/auth/spec.md

@@ -0,0 +1,394 @@
+## Purpose
+
+The interactive authentication capability for `gemiterm`. It owns the end-to-end login flow (launching a headed Chromium via `playwright-cli`, polling a running browser session for Google's sign-out indicator, capturing the `__Secure-1PSID` and `__Secure-1PSIDTS` cookies, persisting them to the profile storage, and closing the browser). It also owns the multi-profile management CLI surface (`auth` command) and the `playwright-cli` driver abstraction that auto-detects the local install (direct binary or `bunx @playwright/cli`).
+
+## Requirements
+
+### Requirement: AuthService.authenticate orchestrates the full login flow
+The `AuthService.authenticate(profileName?)` method MUST be the single entry point for the login flow. When called, it MUST resolve the profile name (using the provided name, or the configured default), validate it, log an info-level "Starting authentication" message, and then in order: print a one-shot headed-browser notification, launch the browser via `PlaywrightCliDriver.openHeaded("https://gemini.google.com/app", profileName, profileName)`, wait up to 300000 ms (5 minutes) for the cookie monitor to report auth cookies, save the captured cookies via the cookie storage, compute the session expiry from `__Secure-1PSIDTS.expires`, and print a confirmation message containing the cookie count and the expiration date (when known). The browser session MUST always be closed in a `finally` block, even if the wait or save step throws.
+
+#### Scenario: Successful authentication returns cookies and expiry
+- **WHEN** `authenticate("test-profile")` is called and the cookie monitor reports both `__Secure-1PSID` and `__Secure-1PSIDTS` before the timeout
+- **THEN** the method resolves with an `AuthResult` whose `cookies` array has length 2, whose `expiresAt` is a `Date` derived from `__Secure-1PSIDTS.expires * 1000`, the driver `openHeaded` is called exactly once with the Gemini app URL, the cookie monitor `start` is called exactly once, the cookie storage `save` is called exactly once, and the driver `closeSession` is called exactly once with the profile name
+
+#### Scenario: Driver is opened with the Gemini app URL and the profile as session
+- **WHEN** `launchBrowser("my-profile")` is called via the public flow
+- **THEN** the driver `openHeaded` is invoked with `"https://gemini.google.com/app"` as the URL, `"my-profile"` as the profile, and `"my-profile"` as the session identifier
+
+#### Scenario: Browser is closed in a finally block on error
+- **WHEN** `authenticate("test-profile")` is called and `waitForLogin` throws (e.g. timeout)
+- **THEN** the driver `closeSession` is still invoked with the profile name (verified by `expect(driver.closeSession).toHaveBeenCalledWith("test-profile")`)
+
+#### Scenario: Invalid profile name is rejected
+- **WHEN** `authenticate("bad name!")` is called
+- **THEN** the method rejects with an error whose message contains `invalid characters`
+
+#### Scenario: Authentication timeout is surfaced as AuthServiceTimeoutError
+- **WHEN** `waitForLogin` is called and the cookie monitor never invokes its callback before the timeout fires
+- **THEN** the method rejects with an `AuthServiceTimeoutError` whose message contains the configured timeout in milliseconds and the substring `No auth cookies detected`, and the cookie monitor `stop` has been called
+
+### Requirement: AuthService prints headed-browser notification (no Enter-block)
+The `AuthService.notifyUser(profileName)` method MUST print a one-shot UI message to the console before launching the browser. The message MUST contain the substring `Opening headed browser`, the Gemini app URL `https://gemini.google.com/app`, and the substring `auto-detect`. The method MUST NOT block on an Enter key press — once the messages are printed, the call MUST return and the caller MUST proceed directly to launch the browser. The single-line "Press Enter to launch browser" prompt described in earlier design notes is not implemented; the current flow runs the launch immediately after the notification.
+
+#### Scenario: Notification includes URL and auto-detect hint
+- **WHEN** `notifyUser("default")` is called
+- **THEN** the combined console output contains the substrings `Opening headed browser`, `https://gemini.google.com/app`, and `auto-detect`
+
+#### Scenario: Notification does not block waiting for input
+- **WHEN** the auth flow calls `notifyUser` followed by `launchBrowser`
+- **THEN** `launchBrowser` runs without the user pressing Enter (no `readline` or stdin reader is involved in the path)
+
+### Requirement: AuthService prints a confirmation with cookie count and expiry
+The `AuthService.confirmAuthSuccess(cookieCount, expiresAt, cookies)` method MUST print a success block to the console. The block MUST contain the substrings `Login auto-detected`, `Authentication successful`, and `<cookieCount> cookies`. When `expiresAt` is a `Date`, the block MUST additionally contain the substring `Session expires` followed by the localized date. The block MUST also report the presence of `__Secure-1PSID` in the supplied cookies with a `✅` (present) or `❌` (absent) marker.
+
+#### Scenario: Success block with expiry
+- **WHEN** `confirmAuthSuccess(2, new Date("2026-12-31T00:00:00Z"), makeAuthCookies())` is called
+- **THEN** the combined output contains `Login auto-detected`, `Authentication successful`, `2 cookies`, `Session expires`, `__Secure-1PSID`, and the `✅` marker
+
+#### Scenario: Success block without expiry
+- **WHEN** `confirmAuthSuccess(1, null, [])` is called
+- **THEN** the combined output contains `Authentication successful` and `1 cookies` but does NOT contain the substring `Session expires`
+
+#### Scenario: Success block with missing __Secure-1PSID
+- **WHEN** `confirmAuthSuccess(0, null, [])` is called
+- **THEN** the combined output contains `__Secure-1PSID` and the `❌` marker
+
+### Requirement: CookieMonitor polls every 2 seconds using a sign-out-link JS probe
+The `CookieMonitor.start(session, onCookiesFound, timeoutMs?)` method MUST begin polling the browser session identified by `session` for the presence of the auth cookies. The poll cadence MUST be a 2-second interval (`POLL_INTERVAL_MS = 2000`). On each tick the monitor MUST run a JavaScript probe that detects a logged-in state by checking for the presence of `a[href^="https://accounts.google.com/SignOutOptions"]`; the probe expression MUST be exactly `document.querySelector('a[href^="https://accounts.google.com/SignOutOptions"]') !== null`. Only when the probe returns `true` (matched as a trimmed string `"true"`) MUST the monitor then read the cookie list and require BOTH `__Secure-1PSID` and `__Secure-1PSIDTS` to be present before invoking the `onCookiesFound` callback. The monitor MUST also accept a `timeoutMs` parameter (default 300000 ms / 5 minutes) and MUST apply `.unref()` to the timeout handle so it does not block CLI process exit.
+
+#### Scenario: Monitor fires callback on first tick where probe and cookies are both ready
+- **WHEN** `start("sess1", cb, 10000)` is called and every 2-second tick returns `true` from the probe and returns both required cookies from `cookieList`
+- **THEN** `cb` is invoked exactly once with the auth cookies, `isRunning` is `false`, and the interval has been cleared
+
+#### Scenario: Monitor does not call driver immediately on start
+- **WHEN** `start("sess1", cb, 10000)` is called
+- **THEN** `driver.evalJs` is NOT called synchronously — the first eval call is scheduled by the interval and only happens after the 2-second delay
+
+#### Scenario: Monitor does not call callback when probe returns false
+- **WHEN** `start("sess1", cb, 10000)` is called and every tick returns `false` from the probe
+- **THEN** `cb` is never invoked and `isRunning` is `false` after `stop()`
+
+#### Scenario: Monitor swallows repeated eval throws
+- **WHEN** `start("sess1", cb, 10000)` is called and every tick's `evalJs` rejects
+- **THEN** `start` resolves successfully, `cb` is never invoked, and the monitor continues running (does not reject)
+
+#### Scenario: Timeout handle is unref'd so CLI can exit
+- **WHEN** `start("sess1", cb, 10000)` is called
+- **THEN** the `setTimeout` handle used for the hard timeout has `unref()` called on it (the monitor must not keep the event loop alive past the timeout)
+
+### Requirement: CookieMonitor exposes checkLoggedIn and checkCookies helpers
+The `CookieMonitor.checkLoggedIn(session)` method MUST return `true` when the sign-out-link probe evaluates to the string `"true"` (with surrounding whitespace allowed) and MUST return `false` for any other return value, including probe errors. The `CookieMonitor.checkCookies(session)` method MUST call `driver.cookieList(session)`, filter the result to entries whose `name` is `__Secure-1PSID` or `__Secure-1PSIDTS`, and return the filtered list when both required cookies are present; otherwise it MUST return an empty array. Both helpers MUST swallow driver errors and return `false` / `[]` respectively.
+
+#### Scenario: checkLoggedIn returns true on probe success
+- **WHEN** `driver.evalJs` returns the string `"true"`
+- **THEN** `checkLoggedIn("sess1")` resolves with `true`
+
+#### Scenario: checkLoggedIn returns false on whitespace-padded true
+- **WHEN** `driver.evalJs` returns the string `"  true  \n"`
+- **THEN** `checkLoggedIn("sess1")` resolves with `true` (whitespace is trimmed)
+
+#### Scenario: checkLoggedIn returns false on probe throw
+- **WHEN** `driver.evalJs` rejects
+- **THEN** `checkLoggedIn("sess1")` resolves with `false` (does not throw)
+
+#### Scenario: checkCookies returns required cookies when both present
+- **WHEN** `driver.cookieList` returns an array containing both `__Secure-1PSID` and `__Secure-1PSIDTS`
+- **THEN** `checkCookies("sess1")` resolves with a length-2 array containing both required cookie names
+
+#### Scenario: checkCookies returns empty when only one required cookie present
+- **WHEN** `driver.cookieList` returns only `__Secure-1PSID`
+- **THEN** `checkCookies("sess1")` resolves with `[]`
+
+### Requirement: CookieMonitor.stop is idempotent and clears the interval
+The `CookieMonitor.stop()` method MUST clear the active polling interval and timeout handle, set the internal `_stopped` flag, and log a `Cookie monitor stopped` info message. Subsequent calls to `stop()` MUST be no-ops (verified by the `stop is idempotent` test). After `stop()` is called, `isRunning` MUST be `false`.
+
+#### Scenario: stop prevents further polling
+- **WHEN** `start` is called and then `stop` is called before the first tick fires
+- **THEN** the callback is never invoked and `isRunning` is `false`
+
+#### Scenario: stop is idempotent
+- **WHEN** `stop()` is called three consecutive times on a monitor that was never started
+- **THEN** none of the calls throw and `isRunning` is `false`
+
+### Requirement: CookieStorageService loads and validates per-profile cookies
+The `CookieStorageService.loadCookiesForProfile(profileName)` method MUST return a `LoadedCookies` object with two fields: `secure_1psid: string` and `secure_1psidts: string | null`. The method MUST read cookies from the underlying `CookieStorage.load(profileName)`, build a name-to-value map, and extract the values for `__Secure-1PSID` and `__Secure-1PSIDTS`. If `__Secure-1PSID` is missing, the method MUST throw an `Error` whose message contains `Missing required cookie __Secure-1PSID` and mentions the profile name and `gemiterm auth`. The `secure_1psidts` field MUST be `null` when the cookie is absent.
+
+#### Scenario: Load returns both cookie values
+- **WHEN** the profile's storage contains both `__Secure-1PSID` and `__Secure-1PSIDTS`
+- **THEN** `loadCookiesForProfile("default")` returns `{ secure_1psid: "<psid value>", secure_1psidts: "<psidts value>" }`
+
+#### Scenario: Load returns null for missing 1PSIDTS
+- **WHEN** the profile's storage contains only `__Secure-1PSID`
+- **THEN** `loadCookiesForProfile("default")` returns `{ secure_1psid: "<psid value>", secure_1psidts: null }`
+
+#### Scenario: Load throws when __Secure-1PSID is missing
+- **WHEN** the profile's storage contains only `__Secure-1PSIDTS`
+- **THEN** `loadCookiesForProfile("default")` throws an error whose message contains `Missing required cookie`
+
+### Requirement: CookieStorageService validates and computes cookie freshness
+The `CookieStorageService.validateCookies(cookies)` method MUST return `true` when the cookie array contains entries for BOTH `__Secure-1PSID` and `__Secure-1PSIDTS`, and MUST return `false` for any other case (including empty arrays). The `CookieStorageService.checkCookieFreshness(cookies)` method MUST return `true` only when `__Secure-1PSIDTS.expires` is a positive number AND the resulting expiry is more than 7 days (604800000 ms) in the future; it MUST return `false` for expired cookies, cookies expiring within 7 days, and cookies with no expiry timestamp.
+
+#### Scenario: validateCookies returns true when both required cookies are present
+- **WHEN** `validateCookies` is called with an array containing both `__Secure-1PSID` and `__Secure-1PSIDTS`
+- **THEN** it returns `true`
+
+#### Scenario: validateCookies returns false when 1PSIDTS is missing
+- **WHEN** `validateCookies` is called with an array containing only `__Secure-1PSID`
+- **THEN** it returns `false`
+
+#### Scenario: checkCookieFreshness returns true for cookies expiring far in the future
+- **WHEN** `checkCookieFreshness` is called with cookies whose `__Secure-1PSIDTS.expires` is more than 7 days from now
+- **THEN** it returns `true`
+
+#### Scenario: checkCookieFreshness returns false for cookies expiring within 7 days
+- **WHEN** `checkCookieFreshness` is called with cookies whose `__Secure-1PSIDTS.expires` is 3 days from now
+- **THEN** it returns `false`
+
+#### Scenario: checkCookieFreshness returns false for expired cookies
+- **WHEN** `checkCookieFreshness` is called with cookies whose `__Secure-1PSIDTS.expires` is in the past
+- **THEN** it returns `false`
+
+### Requirement: CookieStorageService computes cookie expiry
+The `CookieStorageService.getCookieExpiry(cookies)` method MUST return a `Date` derived from `__Secure-1PSIDTS.expires * 1000` (Unix seconds to JS ms) when the cookie has a positive `expires` value. The method MUST return `null` when the cookie array is empty or when no cookie has a positive `expires` value.
+
+#### Scenario: getCookieExpiry returns Date for valid expiry
+- **WHEN** `getCookieExpiry` is called with cookies that include `__Secure-1PSIDTS` having a positive `expires`
+- **THEN** it returns a `Date` whose time is greater than the current time
+
+#### Scenario: getCookieExpiry returns null when 1PSIDTS has no positive expires
+- **WHEN** `getCookieExpiry` is called with cookies that include `__Secure-1PSIDTS` having `expires <= 0`
+- **THEN** it returns `null`
+
+#### Scenario: getCookieExpiry returns null for empty cookies
+- **WHEN** `getCookieExpiry([])` is called
+- **THEN** it returns `null`
+
+### Requirement: ProfileAuthManager.ensureAuthenticated returns cookies or throws
+The `ProfileAuthManager.ensureAuthenticated(profileName?)` method MUST resolve the profile name (provided value, or the configured default), validate it, and check that the profile has valid cookies. If `profileManager.hasValidCookies(name)` returns `false`, the method MUST throw an `AuthenticationError` whose message contains `No valid session for profile '<name>'` and the substring `gemiterm login`. If the cookies are valid, the method MUST return the result of `cookieStorageService.loadCookiesForProfile(name)`.
+
+#### Scenario: Returns cookies for a profile with valid session
+- **WHEN** `ensureAuthenticated("default")` is called and the default profile has fresh cookies
+- **THEN** it returns a `LoadedCookies` object whose `secure_1psid` and `secure_1psidts` match the stored values
+
+#### Scenario: Throws AuthenticationError when no valid cookies
+- **WHEN** `ensureAuthenticated("default")` is called and the profile has no cookies
+- **THEN** it throws an `AuthenticationError` whose message contains `No valid session`
+
+#### Scenario: Throws AuthenticationError with expired cookies
+- **WHEN** `ensureAuthenticated("default")` is called and the profile's cookies are expired
+- **THEN** it throws an `AuthenticationError` whose message contains `No valid session`
+
+#### Scenario: Uses default profile when none specified
+- **WHEN** `ensureAuthenticated()` is called with no argument and the configured default profile has valid cookies
+- **THEN** it returns the loaded cookies for the default profile
+
+#### Scenario: Throws on invalid profile name
+- **WHEN** `ensureAuthenticated("bad name!")` is called
+- **THEN** it throws an error whose message contains `invalid characters`
+
+### Requirement: ProfileAuthManager.getActiveProfiles filters to valid sessions
+The `ProfileAuthManager.getActiveProfiles()` method MUST return the names of all profiles that have valid cookies. The method MUST return `string[]`, MUST be empty when no profiles exist, and MUST NOT include profiles whose cookies are expired or invalid.
+
+#### Scenario: Returns only profiles with valid cookies
+- **WHEN** two profiles exist, one with fresh cookies and one with expired cookies
+- **THEN** `getActiveProfiles()` returns a list containing the fresh profile and not the expired one
+
+#### Scenario: Returns empty array when no profiles have valid cookies
+- **WHEN** profiles exist but all have expired cookies
+- **THEN** `getActiveProfiles()` returns `[]`
+
+#### Scenario: Returns empty array when no profiles exist
+- **WHEN** no profiles are configured
+- **THEN** `getActiveProfiles()` returns `[]`
+
+### Requirement: ProfileAuthManager.findProfileForConversation returns the profile that owns the conversation
+
+The `ProfileAuthManager.findProfileForConversation(conversationId)` method MUST iterate over all profiles in `profileManager.list()` order and, for each, call `geminiClient.profileHasConversation(name, conversationId)` to check whether the conversation appears in that profile's chat list. It MUST return the name of the first profile whose helper returns `true`. When no profile owns the conversation, the method MUST return `null`. The `conversationId` argument MUST be passed to the lookup helper; it MUST NOT be ignored. The method MUST NOT throw on a missing or unknown conversation id.
+
+#### Scenario: Returns the profile that owns the conversation
+- **WHEN** `findProfileForConversation("conv-123")` is called and conversation `conv-123` exists in profile `work` but not in profile `personal`
+- **THEN** the method returns the string `"work"`
+
+#### Scenario: Returns null when conversation is not in any profile
+- **WHEN** `findProfileForConversation("conv-456")` is called and conversation `conv-456` does not exist in any profile's chat list
+- **THEN** the method returns `null`
+
+#### Scenario: Returns null when no profiles exist
+- **WHEN** `findProfileForConversation("conv-789")` is called and no profiles are configured
+- **THEN** the method returns `null`
+
+#### Scenario: Returns first profile in list order when multiple profiles report ownership
+- **WHEN** `findProfileForConversation("conv-shared")` is called and conversation `conv-shared` exists in both profile `profile1` and profile `profile3`, and `profileManager.list()` returns `["profile1", "profile2", "profile3"]` in that order
+- **THEN** the method returns the string `"profile1"` (the first profile in list order that reports ownership)
+
+### Requirement: PlaywrightCliDriver auto-detects between direct and bunx strategies
+The `PlaywrightCliDriver` constructor MUST default the underlying `PlaywrightRunner` to a `BunPlaywrightRunner` with strategy `"direct"` (invoking the `playwright-cli` binary directly). The first time `runCli` is needed, the driver MUST probe the available install: it MUST first try `playwright-cli --version`; if that exits with code 0, the strategy is `direct`. If the direct probe fails, the driver MUST try `bunx @playwright/cli --version`; on success, the strategy is `bunx`. If both probes fail, the driver MUST emit a warning and `runCli` MUST continue to throw `PlaywrightCliError` on any call. The probe MUST time out after 5000 ms (`PROBE_TIMEOUT_MS`) per attempt.
+
+#### Scenario: Strategy exposes the runner's resolved strategy
+- **WHEN** the driver is constructed with a runner of strategy `"direct"`
+- **THEN** `driver.strategy` returns `"direct"`; the same holds for strategy `"bunx"`
+
+#### Scenario: Driver picks up the direct runner when probe succeeds
+- **WHEN** the constructor is given no runner and the live probe of `playwright-cli --version` returns exit code 0
+- **THEN** `driver.strategy` is `"direct"`
+
+### Requirement: PlaywrightCliDriver exposes the standard browser-driver methods
+The `PlaywrightCliDriver` class MUST expose the following async methods, each of which MUST construct its argument array with `withSession(session, [...])` (which prepends `-s=<session>`) for the session-scoped methods:
+- `runCli(args)` returns the trimmed `stdout` string on success, or throws `PlaywrightCliError(command, exitCode, stderr)` on non-zero exit codes.
+- `openHeaded(url, profile, session?)` builds the args `["open", "--browser=chromium", "--headed", "--persistent", "--profile=<profileDir>", url]`, prepending `-s=<session>` when supplied, and resolves the profile dir through the injected `profileDirResolver` (defaulting to `getProfileDir(profile)`).
+- `evalJs(session, expression)` invokes `playwright-cli eval <expression> --raw` and returns the raw output string.
+- `cookieList(session)` invokes `playwright-cli cookie-list --json` and returns a parsed `Cookie[]` (the JSON-array path is preferred; a non-JSON, non-array response yields `[]`).
+- `stateSave(session, path)` and `stateLoad(session, path)` invoke `playwright-cli state-save <path>` and `state-load <path>` respectively.
+- `closeSession(session)` invokes `playwright-cli close`; if the error is a `PlaywrightCliError` whose message contains `not found` (case-insensitive), the call resolves successfully instead of throwing.
+- `closeAll()` invokes `playwright-cli close-all` with no session flag.
+
+#### Scenario: runCli resolves with stdout on success
+- **WHEN** `runCli(["--version"])` is called and the underlying runner returns exit code 0 with stdout `v1.2.3`
+- **THEN** the method resolves with the string `v1.2.3`
+
+#### Scenario: runCli throws PlaywrightCliError on non-zero exit
+- **WHEN** `runCli(["nonexistent-command"])` is called and the underlying runner returns exit code 1
+- **THEN** the method rejects with a `PlaywrightCliError` whose message contains the command name and the stderr text
+
+#### Scenario: openHeaded builds expected args with the session flag
+- **WHEN** `openHeaded("https://gemini.google.com/app", "p1", "s1")` is called
+- **THEN** the runner is invoked once with args beginning with `-s=s1`, containing `open`, `https://gemini.google.com/app`, `--browser=chromium`, `--headed`, `--persistent`, and `--profile=<dir>/p1` as the last few flags
+
+#### Scenario: evalJs includes --raw and returns stdout
+- **WHEN** `evalJs("test-session", "() => document.title")` is called
+- **THEN** the runner is invoked with `["-s=test-session", "eval", "() => document.title", "--raw"]` and the result is the runner's stdout
+
+#### Scenario: cookieList parses JSON array output
+- **WHEN** `cookieList("sess1")` is called and the runner returns a JSON array of cookie objects
+- **THEN** the method resolves with a `Cookie[]` whose length and fields match the input
+
+#### Scenario: cookieList returns empty array for non-JSON output
+- **WHEN** `cookieList("sess1")` is called and the runner returns the string `not-json`
+- **THEN** the method resolves with `[]`
+
+#### Scenario: closeSession swallows "not found" errors
+- **WHEN** `closeSession("sess1")` is called and the runner returns exit code 1 with stderr `session not found`
+- **THEN** the method resolves successfully (does not throw)
+
+#### Scenario: closeSession propagates other PlaywrightCliError failures
+- **WHEN** `closeSession("sess1")` is called and the runner returns exit code 1 with stderr `something else failed`
+- **THEN** the method rejects with a `PlaywrightCliError`
+
+#### Scenario: closeAll runs without a session flag
+- **WHEN** `closeAll()` is called
+- **THEN** the runner is invoked exactly once with args equal to `["close-all"]` and no `-s=` flag
+
+### Requirement: AuthCommand is registered as the "auth" command
+The `AuthCommand` class MUST be registered with the CLI as the command named `"auth"`. Its `description` field MUST be the string `"Authenticate with Google Gemini"`. The `name` and `description` properties are part of the public `CliCommand` contract.
+
+#### Scenario: AuthCommand metadata
+- **WHEN** an `AuthCommand` instance is constructed
+- **THEN** `command.name === "auth"` and `command.description === "Authenticate with Google Gemini"`
+
+### Requirement: AuthCommand shows usage on --help
+When the `auth` command is invoked with `--help` or `-h` as any argument, the command MUST print a usage block to the console containing the substring `gemiterm auth`, the description `Authenticate with Google Gemini.`, and the option row `  -h, --help    Show this help message`. The command MUST NOT proceed to the authentication flow when help is requested.
+
+#### Scenario: --help shows usage and skips auth
+- **WHEN** the user invokes `gemiterm auth --help`
+- **THEN** the console output contains the substrings `gemiterm auth`, `Authenticate with Google Gemini.`, and `-h, --help`, and the auth flow is not entered (no driver or monitor interactions)
+
+#### Scenario: -h shows usage and skips auth
+- **WHEN** the user invokes `gemiterm auth -h`
+- **THEN** the same usage block is printed and the auth flow is not entered
+
+### Requirement: AuthCommand auto-creates the default profile on first run
+When `AuthCommand.execute` is called and `listProfiles()` returns zero profiles, the command MUST create the default profile (using `getDefaultProfileName()`) and call `authenticateWithProfile` with `createFirst=true`. When exactly one profile exists, the command MUST authenticate that profile with `createFirst=false`.
+
+#### Scenario: First run authenticates the default profile and creates it
+- **WHEN** `auth` is invoked and no profiles exist
+- **THEN** `authenticateWithProfile` is called with the default profile name and `createFirst=true`
+
+#### Scenario: Single-profile setup authenticates that profile without creating
+- **WHEN** `auth` is invoked and only one profile exists
+- **THEN** `authenticateWithProfile` is called with that profile's name and `createFirst=false`
+
+### Requirement: AuthCommand shows the multi-profile management menu when 2+ profiles exist
+When `AuthCommand.execute` is called and `listProfiles()` returns 2 or more profile names, the command MUST render a `Profile Management` section that includes:
+- A profile table rendered by `formatProfileTable` containing the statuses of the existing profiles.
+- A list of options, each formatted as `  [X] <label>`, with keys and labels: `[A] Add new profile`, `[D] Delete profile`, `[S] Set default`, `[R] Rename profile`, `[X] Exit and continue with current default`.
+
+The command MUST prompt the user with the text `Select an option` and route the response (case-insensitive, trimmed) to the matching handler. Any unrecognized key (or `X`) MUST be treated as `Exit` and the command MUST print the substring `Continuing with current default profile.` and return without invoking the auth flow.
+
+#### Scenario: Multi-profile run opens the menu
+- **WHEN** `auth` is invoked and multiple profiles exist
+- **THEN** `showProfileMenu` is called with the list of profile names and a `ProfileManager` instance
+
+#### Scenario: Menu renders all five options
+- **WHEN** the menu is rendered for any 2+ profile setup
+- **THEN** the combined output contains the substrings `[A] Add new profile`, `[D] Delete profile`, `[S] Set default`, `[R] Rename profile`, and `[X] Exit`
+
+#### Scenario: Unknown option exits to default
+- **WHEN** the user enters `Z` (or any non-matching key) at the menu prompt
+- **THEN** the command prints `Continuing with current default profile.` and returns without calling `authenticateWithProfile`
+
+#### Scenario: X option exits to default
+- **WHEN** the user enters `X` at the menu prompt
+- **THEN** the command prints `Continuing with current default profile.` and returns without calling `authenticateWithProfile`
+
+### Requirement: AuthCommand "Add new profile" menu option
+When the user selects `A` at the menu prompt, the command MUST prompt for a profile name, validate it via `validateProfileName`, reject duplicates with a `GemitermError` whose message contains `already exists`, create the profile with `profileManager.create(name)`, and return the new profile name to the caller (which triggers `authenticateWithProfile` for that name).
+
+#### Scenario: Adding a new profile triggers auth with the new name
+- **WHEN** the user selects `A` and enters a fresh profile name
+- **THEN** the new profile is created and `authenticateWithProfile` is called with the new name
+
+#### Scenario: Duplicate profile name is rejected
+- **WHEN** the user selects `A` and enters a name that already exists
+- **THEN** the command throws a `GemitermError` whose message contains `already exists`
+
+#### Scenario: Invalid profile name is rejected
+- **WHEN** the user selects `A` and enters a name with invalid characters (e.g. `bad name!!`)
+- **THEN** the command throws an error whose message contains `invalid characters`
+
+### Requirement: AuthCommand "Delete profile" menu option
+When the user selects `D` at the menu prompt, the command MUST prompt for the profile name to delete, reject unknown profiles with a `GemitermError` whose message contains `does not exist`, then prompt `Delete profile '<name>'? [y/N]` and only delete the profile (via `profileManager.delete`) when the answer starts with `y` (case-insensitive). Any other answer MUST cancel the delete (printing `Cancelled.`) and return without invoking the auth flow.
+
+#### Scenario: Deleting an existing profile removes it
+- **WHEN** the user selects `D`, enters an existing profile name, and confirms with a `y`-prefixed answer
+- **THEN** `profileManager.delete(name)` is called and the command returns without authenticating
+
+#### Scenario: Deleting a non-existent profile throws
+- **WHEN** the user selects `D` and enters a profile name not in `listProfiles()`
+- **THEN** the command throws a `GemitermError` whose message contains `does not exist`
+
+#### Scenario: Cancelling the delete confirmation preserves the profile
+- **WHEN** the user selects `D`, enters an existing profile name, and answers the confirmation with `n` (or anything not starting with `y`)
+- **THEN** the delete is not performed and the command returns without authenticating
+
+### Requirement: AuthCommand "Set default" menu option
+When the user selects `S` at the menu prompt, the command MUST prompt for a profile name, reject unknown profiles with a `GemitermError` whose message contains `does not exist`, then call BOTH `profileManager.setDefault(name)` and `setDefaultProfileName(name)`, print the substring `Default profile set to '<name>'.`, and return without invoking the auth flow.
+
+#### Scenario: Setting default updates both the manager and the global marker
+- **WHEN** the user selects `S` and enters a valid existing profile name
+- **THEN** `profileManager.setDefault(name)` and `setDefaultProfileName(name)` are both called with the same name
+
+#### Scenario: Setting default for unknown profile throws
+- **WHEN** the user selects `S` and enters a profile name not in `listProfiles()`
+- **THEN** the command throws a `GemitermError` whose message contains `does not exist`
+
+### Requirement: AuthCommand "Rename profile" menu option
+When the user selects `R` at the menu prompt, the command MUST prompt for the current profile name (rejecting unknown names with a `GemitermError` whose message contains `does not exist`), then prompt for the new name, validate the new name via `validateProfileName`, call `profileManager.rename(oldName, newName)`, and return the new name to the caller (which triggers `authenticateWithProfile` for the new name).
+
+#### Scenario: Renaming a profile triggers auth with the new name
+- **WHEN** the user selects `R` and enters a valid existing old name and a valid new name
+- **THEN** `profileManager.rename(oldName, newName)` is called and `authenticateWithProfile` is called with the new name
+
+#### Scenario: Renaming with invalid new name throws
+- **WHEN** the user selects `R` and enters a new name that fails `validateProfileName`
+- **THEN** the command throws an error whose message contains `invalid characters`
+
+#### Scenario: Renaming an unknown profile throws
+- **WHEN** the user selects `R` and enters an old name not in `listProfiles()`
+- **THEN** the command throws a `GemitermError` whose message contains `does not exist`
+
+### Requirement: AuthCommand propagates authentication errors
+When `AuthCommand.authenticateWithProfile` (or its delegates) throws, the command MUST propagate the error to the caller so the process exits non-zero. The error message is the original error's message (e.g. `Browser launch failed` from the integration test fixture).
+
+#### Scenario: Auth flow errors are propagated
+- **WHEN** the auth flow rejects with an error whose message is `Browser launch failed`
+- **THEN** `execute` rejects with an error whose message contains `Browser launch failed`

package/openspec/specs/cli/spec.md

@@ -0,0 +1,108 @@
+## Purpose
+
+The CLI entry point for the `gemiterm` application. It provides the executable shebang, parses global flags, registers the 11 top-level commands, prints help and version output, and dispatches subcommand execution to a `CommandRegistry`. The CLI is the only public face of the application and is the process entry point launched by the user.
+
+## Requirements
+
+### Requirement: Bun Shebang Entry Point
+The CLI source file MUST begin with the shebang line `#!/usr/bin/env bun` so the file is executable directly by the Bun runtime when invoked as a script or compiled binary. The shebang MUST appear on the first line of `src/cli/index.ts`.
+
+#### Scenario: Inspecting the shebang line
+- **WHEN** the file `src/cli/index.ts` is read
+- **THEN** the first line is exactly `#!/usr/bin/env bun`
+
+### Requirement: Global Flags Parsing
+The system MUST parse global flags from the raw process arguments and expose a `GlobalFlags` object with three boolean fields: `verbose`, `version`, and `help`. The parser MUST recognize `--verbose` and its short alias `-v` as setting `verbose=true`, MUST recognize `--version` as setting `version=true`, and MUST recognize `--help` and its short alias `-h` as setting `help=true` (only when no subcommand has been seen yet). All non-flag arguments MUST be returned as `remaining` args.
+
+#### Scenario: Verbose flag sets verbose
+- **WHEN** the user invokes `gemiterm --verbose list`
+- **THEN** `parseGlobalFlags` returns `flags.verbose === true` and `remaining === ["list"]`
+
+#### Scenario: Verbose short alias works
+- **WHEN** the user invokes `gemiterm -v list`
+- **THEN** `flags.verbose === true` and `remaining === ["list"]`
+
+#### Scenario: Version flag sets version
+- **WHEN** the user invokes `gemiterm --version`
+- **THEN** `flags.version === true` and `remaining === []`
+
+#### Scenario: Help flag sets help
+- **WHEN** the user invokes `gemiterm --help`
+- **THEN** `flags.help === true` and `remaining === []`
+
+#### Scenario: Help short alias works
+- **WHEN** the user invokes `gemiterm -h`
+- **THEN** `flags.help === true` and `remaining === []`
+
+### Requirement: Verbose Flag Enables Debug Logging
+When the global `--verbose` flag is set, the system MUST call `Logger.setVerbose(true)` so that `debug()` output from every `Logger` instance is emitted.
+
+#### Scenario: Verbose flag enables debug
+- **WHEN** the user runs `gemiterm --verbose <command>`
+- **THEN** `Logger.setVerbose(true)` is invoked before the command handler runs
+
+### Requirement: Version Output From Package Metadata
+When the `--version` global flag is set, the system MUST print `gemiterm v<version>` to stdout and exit the process with code 0, where `<version>` is read from the `version` field of the `package.json` at the project root.
+
+#### Scenario: Version output
+- **WHEN** the user invokes `gemiterm --version`
+- **THEN** the process prints a line of the form `gemiterm v2.0.0` to stdout and exits with code 0
+
+### Requirement: No-Args Behavior Prints Help
+When the user invokes `gemiterm` with no arguments (after global flag parsing), the system MUST print the help screen via `showHelp(registry)` and exit the process with code 0.
+
+#### Scenario: No arguments prints help
+- **WHEN** the user invokes `gemiterm` with no arguments
+- **THEN** `showHelp(registry)` is called and the process exits with code 0
+
+### Requirement: Unknown Subcommand Suggestion
+When the user invokes a subcommand that is not registered with the `CommandRegistry`, the system MUST print an `Unknown command` message to stderr. If at least one command is registered, the system MUST also print a `Did you mean one of: <names>?` suggestion line listing the registered command names. If no commands are registered, the system MUST print a fallback message directing the user to `--help`. In both cases the system MUST exit with code 1.
+
+#### Scenario: Unknown subcommand with registered names
+- **WHEN** the user invokes `gemiterm not-a-command` and the registry contains registered names
+- **THEN** stderr receives `Unknown command: 'not-a-command'` followed by a line starting with `Did you mean one of:` and the process exits with code 1
+
+#### Scenario: Unknown subcommand with empty registry
+- **WHEN** the user invokes `gemiterm not-a-command` and the registry is empty
+- **THEN** stderr receives `Unknown command: 'not-a-command'` and a fallback suggesting `--help`, and the process exits with code 1
+
+### Requirement: CommandRegistry Public Surface
+The `CommandRegistry` class MUST expose a `register(commandName, handler)` method that throws if the name is already registered, a `getHandler(commandName)` method that returns the handler or `undefined`, a `has(commandName)` boolean check, a `getRegisteredNames()` method returning all registered names, and a `registerAllCommands()` method that wires up the full default command set.
+
+#### Scenario: Register a new command
+- **WHEN** `register("x", handler)` is called on a registry that does not yet contain `"x"`
+- **THEN** `has("x")` returns `true` and `getHandler("x")` returns the registered handler
+
+#### Scenario: Re-registering the same name throws
+- **WHEN** `register("x", handler)` is called twice with the same name
+- **THEN** the second call throws an error whose message mentions the duplicate name
+
+#### Scenario: getHandler for missing name returns undefined
+- **WHEN** `getHandler("missing")` is called on a registry that does not contain it
+- **THEN** the result is `undefined`
+
+#### Scenario: getRegisteredNames returns the registered keys
+- **WHEN** commands `"a"`, `"b"`, and `"c"` are registered
+- **THEN** `getRegisteredNames()` returns a list containing all three names
+
+### Requirement: Default Command Set Registration
+`CommandRegistry.registerAllCommands()` MUST explicitly register exactly 11 commands: `auth`, `profile`, `status`, `list`, `fetch`, `continue`, `new`, `delete`, `export`, `export-all`, and `install-browser`. Each registration MUST be performed by direct, hand-written `register()` calls — the system MUST NOT use any auto-discovery or glob-based mechanism to populate the registry.
+
+#### Scenario: After registerAllCommands the registry has 11 entries
+- **WHEN** a fresh `CommandRegistry` has `registerAllCommands()` invoked
+- **THEN** `getRegisteredNames()` returns exactly the names `auth`, `profile`, `status`, `list`, `fetch`, `continue`, `new`, `delete`, `export`, `export-all`, and `install-browser`
+
+#### Scenario: Each registered name resolves to a handler
+- **WHEN** `registerAllCommands()` has been called
+- **THEN** `getHandler(name)` returns a non-`undefined` `CliCommand` for each of the 11 names
+
+### Requirement: Help Output
+The system MUST expose a `showHelp(registry?)` function in `src/cli/commands/help.ts` that, when a registry is provided, prints the registered command names with their descriptions, then prints the three global options (`--version`, `--help, -h`, `--verbose, -v`) with their descriptions, and finally prints a hint to run `gemiterm <command> --help` for more information.
+
+#### Scenario: Help with a registry
+- **WHEN** `showHelp(registry)` is called with a registry containing 11 commands
+- **THEN** the output contains the application name `GemiTerm`, a `Commands:` section listing all 11 names and their descriptions, a `Global Options:` section listing the three global flags, and the hint about `<command> --help`
+
+#### Scenario: Help with no registry
+- **WHEN** `showHelp()` is called with no arguments
+- **THEN** the output still includes the application name, the `Global Options:` section, and the command-specific help hint (the `Commands:` section is empty)