gemiterm 2.0.0

package/openspec/specs/conversations/spec.md

@@ -0,0 +1,139 @@
+## Purpose
+
+The Gemini API client wrapper. It owns the `GeminiClientService` class that implements both the `IGeminiClientService` (used by command handlers for mutations: delete, send, start-new) and the `IGeminiClientQueryService` (used by query handlers for reads: list chats, fetch chat, list models) interfaces. The wrapper issues authenticated `fetch` requests against `https://gemini.google.com`, attaching the `__Secure-1PSID` and `__Secure-1PSIDTS` cookies, and translates Gemini API responses into the domain types `ChatInfo` and `Message`.
+
+## Requirements
+
+### Requirement: GeminiClientService is constructed from cookies and a logger
+The `GeminiClientService` constructor MUST accept two arguments: a config object with `secure1psid: string` and an optional `secure1psidts?: string | null`, and a `Logger` instance. The `authenticated` flag MUST be initialized to `true` when `secure1psid` is a non-empty string and `false` otherwise. The class MUST implement BOTH `IGeminiClientService` and `IGeminiClientQueryService`.
+
+#### Scenario: Service initializes as authenticated with a 1PSID
+- **WHEN** a `GeminiClientService` is constructed with `{ secure1psid: "abc" }` and a logger
+- **THEN** `isAuthenticated()` returns `true`
+
+#### Scenario: Service initializes as unauthenticated without a 1PSID
+- **WHEN** a `GeminiClientService` is constructed with `{ secure1psid: "" }` and a logger
+- **THEN** `isAuthenticated()` returns `false`
+
+### Requirement: GeminiClientService builds the cookie header from the configured cookies
+For every authenticated request, the service MUST build a `Cookie` header that includes `__Secure-1PSID=<value>` and, when `secure1psidts` is non-null/non-empty, an additional `__Secure-1PSIDTS=<value>` segment joined by `; `. The header MUST be combined with the default headers `Content-Type: application/x-www-form-urlencoded` and a Chrome User-Agent string.
+
+#### Scenario: Cookie header includes both cookies when present
+- **WHEN** the service is configured with both `secure1psid` and `secure1psidts`
+- **THEN** outgoing requests carry a `Cookie` header whose value is `__Secure-1PSID=<psid>; __Secure-1PSIDTS=<psidts>`
+
+#### Scenario: Cookie header includes only 1PSID when 1PSIDTS is absent
+- **WHEN** the service is configured with `secure1psid` and `secure1psidts: null`
+- **THEN** outgoing requests carry a `Cookie` header whose value is `__Secure-1PSID=<psid>` (no 1PSIDTS segment)
+
+### Requirement: GeminiClientService.listChats returns ChatInfo sorted by recency
+The `listChats(options?)` method MUST GET `/app/api/chat/history` and parse the response JSON. Each entry in the `chats` array MUST be mapped to a `ChatInfo` object with fields:
+- `id: string` (from the API's `cid`)
+- `title: string` (from the API's `title`, defaulting to `"Untitled"` when missing)
+- `isPinned: boolean` (from the API's `is_pinned`, defaulting to `false` when missing)
+- `timestamp: number` (from the API's `timestamp`, defaulting to `0` when missing)
+
+The `ChatInfo` type MUST NOT include a `profile` field at this time. After mapping, the method MUST sort the array by `timestamp` descending, apply an in-memory `search` filter on the lowercased `title` when `options.search` is provided, then apply `options.offset` (skip) and `options.limit` (truncate) in that order. Network errors MUST be re-thrown as `GeminiAPIError`; HTTP 401/403 MUST be re-thrown as `AuthenticationError` with the message `Session expired or invalid. Please run 'gemiterm login' again.` and the service MUST mark itself unauthenticated.
+
+#### Scenario: listChats maps API response to ChatInfo
+- **WHEN** `/app/api/chat/history` returns a JSON object with a `chats` array of objects with `cid`, `title`, `is_pinned`, and `timestamp` fields
+- **THEN** the method resolves with a `ChatInfo[]` whose elements have `id` (from `cid`), `title`, `isPinned` (from `is_pinned`), and `timestamp` fields, and no `profile` field is present on any element
+
+#### Scenario: listChats sorts results by timestamp descending
+- **WHEN** the API returns chats with timestamps `1000` and `2000`
+- **THEN** the resolved array is ordered with the `timestamp: 2000` entry first and the `timestamp: 1000` entry second
+
+#### Scenario: listChats applies the search filter
+- **WHEN** `listChats({ search: "hello" })` is called and the response contains chats with mixed titles
+- **THEN** the resolved array contains only chats whose lowercased title includes the substring `hello`
+
+#### Scenario: listChats applies limit and offset in order
+- **WHEN** `listChats({ offset: 5, limit: 10 })` is called and the sorted response has 20 entries
+- **THEN** the resolved array has length 10 and is the slice of the sorted response from index 5 to index 14 (inclusive)
+
+#### Scenario: listChats surfaces 401/403 as AuthenticationError
+- **WHEN** the upstream API responds with HTTP 401 or 403
+- **THEN** the method rejects with an `AuthenticationError` whose message contains `Session expired` and `isAuthenticated()` returns `false` thereafter
+
+### Requirement: GeminiClientService.fetchChat returns ordered messages
+The `fetchChat(conversationId)` method MUST GET `/app/api/chat/history/<encoded-conversationId>` and parse the `turns` array. Each turn MUST be converted to a `Message` with:
+- `role: "user" | "model"` (mapped from the turn's `role`; non-`"user"` roles are normalized to `"model"`)
+- `content: string` (built from `turn.text` when present, else by joining `turn.parts[].text` strings, else the empty string)
+- `conversationId: string` (the same conversation id passed to the method)
+
+Errors from the underlying fetch MUST be wrapped in `GeminiAPIError` unless they are already a `GeminiAPIError` or `AuthenticationError`.
+
+#### Scenario: fetchChat returns messages with role and content
+- **WHEN** `/app/api/chat/history/<id>` returns a `turns` array with user and model turns
+- **THEN** the method resolves with a `Message[]` whose entries have the correct `role` (`"user"` or `"model"`) and `content`, and whose `conversationId` matches the input
+
+#### Scenario: fetchChat builds content from parts when text is absent
+- **WHEN** a turn has no `text` field but has `parts: [{ text: "a" }, { text: "b" }]`
+- **THEN** the resulting `Message.content` is the string `"ab"` (parts joined)
+
+### Requirement: GeminiClientService.deleteChat removes a conversation
+The `deleteChat(conversationId)` method MUST issue `DELETE /app/api/chat/history/<encoded-conversationId>`. Errors MUST be wrapped in `GeminiAPIError` unless they are already a `GeminiAPIError` or `AuthenticationError`.
+
+#### Scenario: deleteChat issues a DELETE to the history endpoint
+- **WHEN** `deleteChat("conv-1")` is called
+- **THEN** the underlying request is `DELETE https://gemini.google.com/app/api/chat/history/conv-1`
+
+#### Scenario: deleteChat surfaces upstream errors as GeminiAPIError
+- **WHEN** the upstream API responds with a non-2xx status other than 401/403
+- **THEN** the method rejects with a `GeminiAPIError` whose message contains the status code
+
+### Requirement: GeminiClientService.sendMessage returns the model response text
+The `sendMessage(conversationId, message)` method MUST POST `/app/api/chat/<encoded-conversationId>/send` with a URL-encoded form body of `message=<message>`. The response JSON MUST be read, and the method MUST return the value of the `response` field, falling back to the `text` field, falling back to the empty string.
+
+#### Scenario: sendMessage returns the response field
+- **WHEN** the API responds with `{ "response": "Hello!" }`
+- **THEN** the method resolves with the string `Hello!`
+
+#### Scenario: sendMessage falls back to the text field
+- **WHEN** the API responds with `{ "text": "Hi" }` and no `response` field
+- **THEN** the method resolves with the string `Hi`
+
+#### Scenario: sendMessage returns empty string when neither field is present
+- **WHEN** the API responds with `{}`
+- **THEN** the method resolves with the string `""`
+
+### Requirement: GeminiClientService.startNewChat returns response and conversation id
+The `startNewChat(message)` method MUST POST `/app/api/chat/new` with a URL-encoded form body of `message=<message>`. The response MUST be read and a `{ response, conversationId }` object returned, where `response` is `data.response ?? data.text ?? ""` and `conversationId` is `data.cid ?? data.conversation_id ?? ""`. Errors MUST be wrapped in `GeminiAPIError` unless they are already a `GeminiAPIError` or `AuthenticationError`.
+
+#### Scenario: startNewChat returns the new conversation id
+- **WHEN** the API responds with `{ "response": "Hi", "cid": "new-conv" }`
+- **THEN** the method resolves with `{ response: "Hi", conversationId: "new-conv" }`
+
+#### Scenario: startNewChat falls back to conversation_id and text
+- **WHEN** the API responds with `{ "text": "Hello", "conversation_id": "fallback-id" }`
+- **THEN** the method resolves with `{ response: "Hello", conversationId: "fallback-id" }`
+
+#### Scenario: startNewChat returns empty strings when fields are absent
+- **WHEN** the API responds with `{}`
+- **THEN** the method resolves with `{ response: "", conversationId: "" }`
+
+### Requirement: GeminiClientService.listModels returns model display names
+The `listModels()` method MUST GET `/app/api/models` and parse the `models` array. For each entry, the method MUST return `display_name` when present, else `name`. When the response has no `models` field, the method MUST return `[]`.
+
+#### Scenario: listModels returns display names
+- **WHEN** the API responds with `{ "models": [{ "name": "x", "display_name": "Gemini Pro" }, { "name": "y" }] }`
+- **THEN** the method resolves with `["Gemini Pro", "y"]`
+
+#### Scenario: listModels returns empty array when no models field
+- **WHEN** the API responds with `{}`
+- **THEN** the method resolves with `[]`
+
+### Requirement: GeminiClientService.isAuthenticated reports the current session state
+The `isAuthenticated()` method MUST return the value of the internal `authenticated` flag. The flag MUST be initialized based on the constructor config and MUST be reset to `false` whenever a request surfaces a 401/403 response (so subsequent calls to mutating/querying methods throw `AuthenticationError`).
+
+#### Scenario: Returns true after successful construction
+- **WHEN** the service is constructed with a non-empty `secure1psid`
+- **THEN** `isAuthenticated()` returns `true`
+
+#### Scenario: Returns false after a 401/403 response
+- **WHEN** any method issues a request that returns 401 or 403
+- **THEN** the subsequent `isAuthenticated()` call returns `false`
+
+#### Scenario: Mutating methods throw AuthenticationError when not authenticated
+- **WHEN** the service is constructed with an empty `secure1psid` and `deleteChat`, `sendMessage`, or `startNewChat` is called
+- **THEN** the call rejects with an `AuthenticationError` (no network call is made)

package/openspec/specs/domain-model/spec.md

@@ -0,0 +1,128 @@
+## Purpose
+
+The shared domain types and error hierarchy used across the core, services, infrastructure, and CLI layers. The domain model defines the shape of cookies, messages, conversations, chat metadata, profile status, and the typed error classes that every layer raises and handles.
+
+## Requirements
+
+### Requirement: Profile Status Type
+The system MUST export a `ProfileStatus` interface with five fields: `name: string`, `exists: boolean`, `isActive: boolean`, `expiresAt: string | null`, and `isDefault: boolean`. The interface MUST be used to communicate the state of a single profile directory on disk and its cookies.
+
+#### Scenario: Constructing a profile status
+- **WHEN** a profile `"work"` exists, has fresh cookies, and is the default
+- **THEN** a value of `{ name: "work", exists: true, isActive: true, expiresAt: "<iso>", isDefault: true }` satisfies the `ProfileStatus` interface
+
+### Requirement: Chat Info Type
+The system MUST export a `ChatInfo` interface with four fields: `id: string`, `title: string`, `isPinned: boolean`, and `timestamp: number`. The interface MUST represent one entry in the user's conversation list.
+
+#### Scenario: Constructing a chat info entry
+- **WHEN** a chat has identifier `"abc"`, title `"Hello"`, is pinned, and a numeric timestamp
+- **THEN** `{ id: "abc", title: "Hello", isPinned: true, timestamp: 1718000000000 }` satisfies the `ChatInfo` interface
+
+### Requirement: Message Type
+The system MUST export a `Message` interface with three fields: `role: "user" | "model"`, `content: string`, and an optional `conversationId?: string`. The `role` field MUST be a string-literal union restricted to `"user"` or `"model"`.
+
+#### Scenario: Constructing a user message
+- **WHEN** a user submits `"Hi there"` to conversation `"c1"`
+- **THEN** `{ role: "user", content: "Hi there", conversationId: "c1" }` satisfies the `Message` interface
+
+#### Scenario: Constructing a model message
+- **WHEN** the model responds with `"Hello!"` and no conversation id is bound
+- **THEN** `{ role: "model", content: "Hello!" }` satisfies the `Message` interface
+
+### Requirement: Conversation Type
+The system MUST export a `Conversation` interface with three fields: `id: string`, `title: string`, and `messages: Message[]`. The `messages` array MUST be ordered chronologically (oldest first).
+
+#### Scenario: Constructing a conversation
+- **WHEN** a conversation has identifier `"c1"`, title `"Demo"`, and two messages
+- **THEN** `{ id: "c1", title: "Demo", messages: [{ role: "user", content: "Hi" }, { role: "model", content: "Hello" }] }` satisfies the `Conversation` interface
+
+### Requirement: Auth Result Type
+The system MUST export an `AuthResult` interface with two fields: `cookies: Cookie[]` and `expiresAt: Date | null`. The interface MUST be the return type of a successful authentication flow.
+
+#### Scenario: Constructing an auth result
+- **WHEN** an authentication flow returns two cookies and a known expiry date
+- **THEN** `{ cookies: [...], expiresAt: new Date(...) }` satisfies the `AuthResult` interface
+
+### Requirement: Cookie Type
+The system MUST export a `Cookie` interface with eight fields: `name: string`, `value: string`, `domain: string`, `path: string`, `expires: number` (Unix seconds), `httpOnly: boolean`, `secure: boolean`, and `sameSite: "Strict" | "Lax" | "None"`. The `sameSite` field MUST be the string-literal union `"Strict" | "Lax" | "None"`.
+
+#### Scenario: Constructing a strict same-site cookie
+- **WHEN** a cookie named `"SID"` with `sameSite: "Strict"` is created
+- **THEN** the value satisfies the `Cookie` interface and the `sameSite` field is one of the three allowed literals
+
+#### Scenario: Constructing a lax same-site cookie
+- **WHEN** a cookie with `sameSite: "Lax"` is created
+- **THEN** the value satisfies the `Cookie` interface
+
+#### Scenario: Constructing a none same-site cookie
+- **WHEN** a cookie with `sameSite: "None"` is created
+- **THEN** the value satisfies the `Cookie` interface
+
+### Requirement: Base GemitermError Class
+The system MUST export a `GemitermError` class that extends the built-in `Error` class. The constructor MUST accept a `message: string` and store it on `this.message`. The constructor MUST set `this.name` to the literal string `"GemitermError"`. `GemitermError` MUST be the base class for every other domain error in the system.
+
+#### Scenario: GemitermError preserves message
+- **WHEN** a caller constructs `new GemitermError("oops")`
+- **THEN** `err.message === "oops"`, `err.name === "GemitermError"`, and `err instanceof GemitermError === true`
+
+#### Scenario: GemitermError is an Error
+- **WHEN** a `GemitermError` is constructed
+- **THEN** it is also an instance of the built-in `Error` class
+
+### Requirement: AuthenticationError Class
+The system MUST export an `AuthenticationError` class that extends `GemitermError`. The constructor MUST accept an optional `message` string. When no message is supplied, the default MUST be the literal string `Not authenticated. Please run 'gemiterm login' first.`. The constructor MUST set `this.name` to `"AuthenticationError"`.
+
+#### Scenario: Default authentication error
+- **WHEN** `new AuthenticationError()` is constructed
+- **THEN** `err.message` is the default auth message, `err.name === "AuthenticationError"`, and `err instanceof GemitermError` is `true`
+
+#### Scenario: Custom authentication error
+- **WHEN** `new AuthenticationError("token invalid")` is constructed
+- **THEN** `err.message === "token invalid"`
+
+### Requirement: CookieExpiredError Class
+The system MUST export a `CookieExpiredError` class that extends `GemitermError`. The constructor MUST accept an optional `message` string. When no message is supplied, the default MUST be the literal string `Session has expired. Please run 'gemiterm login' again.`. The constructor MUST set `this.name` to `"CookieExpiredError"`.
+
+#### Scenario: Default cookie-expired error
+- **WHEN** `new CookieExpiredError()` is constructed
+- **THEN** `err.message` is the default expiry message, `err.name === "CookieExpiredError"`, and `err instanceof GemitermError` is `true`
+
+#### Scenario: Custom cookie-expired error
+- **WHEN** `new CookieExpiredError("expired at 12:00")` is constructed
+- **THEN** `err.message === "expired at 12:00"`
+
+### Requirement: GeminiAPIError Class
+The system MUST export a `GeminiAPIError` class that extends `GemitermError`. The constructor MUST accept a required `message: string` and store it. The constructor MUST set `this.name` to `"GeminiAPIError"`.
+
+#### Scenario: API error with custom message
+- **WHEN** `new GeminiAPIError("rate limit exceeded")` is constructed
+- **THEN** `err.message === "rate limit exceeded"`, `err.name === "GeminiAPIError"`, and `err instanceof GemitermError` is `true`
+
+### Requirement: ConversationNotFoundError Class
+The system MUST export a `ConversationNotFoundError` class that extends `GemitermError`. The constructor MUST accept a required `conversationId: string` and MUST compose the message as `Conversation '<conversationId>' not found.`. The constructor MUST set `this.name` to `"ConversationNotFoundError"`.
+
+#### Scenario: Conversation-not-found error with id
+- **WHEN** `new ConversationNotFoundError("conv-123")` is constructed
+- **THEN** `err.message === "Conversation 'conv-123' not found."`, `err.name === "ConversationNotFoundError"`, and `err instanceof GemitermError` is `true`
+
+### Requirement: ConversationPendingError Class
+The system MUST export a `ConversationPendingError` class that extends `GemitermError`. The constructor MUST accept an optional `message` string. When no message is supplied, the default MUST be the literal string `Conversation operation is still pending.`. The constructor MUST set `this.name` to `"ConversationPendingError"`.
+
+#### Scenario: Default conversation-pending error
+- **WHEN** `new ConversationPendingError()` is constructed
+- **THEN** `err.message` is the default pending message, `err.name === "ConversationPendingError"`, and `err instanceof GemitermError` is `true`
+
+#### Scenario: Custom conversation-pending error
+- **WHEN** `new ConversationPendingError("still generating")` is constructed
+- **THEN** `err.message === "still generating"`
+
+### Requirement: All Domain Errors Extend GemitermError
+Every concrete error class in the domain hierarchy (`AuthenticationError`, `CookieExpiredError`, `GeminiAPIError`, `ConversationNotFoundError`, `ConversationPendingError`) MUST be a subclass of `GemitermError`. As a consequence, every domain error MUST also be an instance of the built-in `Error` class.
+
+#### Scenario: Every domain error is a GemitermError
+- **WHEN** a test iterates over `AuthenticationError`, `CookieExpiredError`, `GeminiAPIError`, `ConversationNotFoundError`, and `ConversationPendingError` with default-constructible arguments
+- **THEN** every constructed instance is `instanceof GemitermError`
+
+#### Scenario: Every domain error is an Error
+- **WHEN** the same iteration is performed
+- **THEN** every constructed instance is also `instanceof Error`

package/openspec/specs/formatters/spec.md

@@ -0,0 +1,158 @@
+## Purpose
+
+Output formatters that turn in-memory domain values (chats, conversations, profile statuses) into human-readable terminal output. The module provides markdown rendering for exporting a single conversation, JSON rendering for machine-readable export, and colored table rendering for listing profiles and chats in the terminal.
+
+## Requirements
+
+### Requirement: formatChatAsMarkdown Produces a Markdown Document
+The system MUST export a `formatChatAsMarkdown(messages, title, conversationId?, includeMetadata?): string` function that builds a single markdown document. The first line of the document MUST be a level-1 heading `# <title>` followed by a blank line. For each message, the function MUST emit a bold role label on its own line (`**You:**` for `role === "user"`, `**Gemini:**` for `role === "model"`), a blank line, the message `content`, a blank line, and a horizontal rule `---` on its own line, followed by a blank line.
+
+#### Scenario: Title heading is rendered
+- **WHEN** `formatChatAsMarkdown(messages, "Test Chat")` is called
+- **THEN** the result starts with `# Test Chat\n\n`
+
+#### Scenario: User message label
+- **WHEN** the messages contain a `{ role: "user", content: "Hello" }` entry
+- **THEN** the result contains `**You:**` followed by the content
+
+#### Scenario: Model message label
+- **WHEN** the messages contain a `{ role: "model", content: "Hi" }` entry
+- **THEN** the result contains `**Gemini:**` followed by the content
+
+#### Scenario: Horizontal rule between messages
+- **WHEN** the messages array has N entries
+- **THEN** the result contains exactly N `---` separator lines
+
+#### Scenario: Empty messages array
+- **WHEN** `formatChatAsMarkdown([], "Empty")` is called
+- **THEN** the result still contains `# Empty` and does NOT contain `**You:**` or `**Gemini:**`
+
+#### Scenario: Single-message array
+- **WHEN** the messages array has exactly one entry
+- **THEN** the result contains that message's label, the message content, and exactly one `---` separator
+
+### Requirement: formatChatAsMarkdown Optional Metadata Block
+When `includeMetadata === true` AND a `conversationId` is supplied, `formatChatAsMarkdown` MUST prepend a metadata block (placed after the title heading, before the first message) of three blockquote lines: `> Conversation ID: <conversationId>`, `> Messages: <count>`, and `> Exported: <iso>`. When `includeMetadata` is `false` or `undefined`, or when `conversationId` is missing, the metadata block MUST NOT appear.
+
+#### Scenario: Metadata included when both flags are set
+- **WHEN** `formatChatAsMarkdown(messages, "Test", "conv-123", true)` is called
+- **THEN** the result contains `> Conversation ID: conv-123`, `> Messages: <N>`, and `> Exported:`
+
+#### Scenario: Metadata excluded when includeMetadata is false
+- **WHEN** `formatChatAsMarkdown(messages, "Test", "conv-123", false)` is called
+- **THEN** the result does NOT contain `> Conversation ID:`
+
+#### Scenario: Metadata excluded when includeMetadata is undefined
+- **WHEN** `formatChatAsMarkdown(messages, "Test", "conv-123")` is called (no fourth arg)
+- **THEN** the result does NOT contain `> Conversation ID:`
+
+#### Scenario: Metadata excluded when conversationId is missing
+- **WHEN** `formatChatAsMarkdown(messages, "Test", undefined, true)` is called
+- **THEN** the result does NOT contain `> Conversation ID:`
+
+### Requirement: formatChatAsJson Produces a Conversation Document
+The system MUST export a `formatChatAsJson(messages, conversationId): string` function that returns a JSON string of the form `{ "conversationId": "<id>", "messages": <messages> }`. The function MUST produce valid JSON and MUST use 2-space pretty-printing. The order of `messages` in the output MUST match the order of the input array.
+
+#### Scenario: Output is valid JSON
+- **WHEN** `formatChatAsJson(messages, "conv-1")` is called
+- **THEN** `JSON.parse(result)` does not throw
+
+#### Scenario: conversationId is present
+- **WHEN** the function is called with `conversationId === "conv-1"`
+- **THEN** the parsed object has `conversationId === "conv-1"`
+
+#### Scenario: messages array is preserved
+- **WHEN** the function is called with an N-element messages array
+- **THEN** the parsed object has `messages.length === N` and the entries appear in the input order with their `role` and `content` intact
+
+#### Scenario: Pretty-printed with 2-space indentation
+- **WHEN** the function is called with non-empty input
+- **THEN** the raw string contains `  "conversationId"` (2 spaces of indentation before the key)
+
+#### Scenario: Empty messages array
+- **WHEN** `formatChatAsJson([], "conv-empty")` is called
+- **THEN** the parsed object has `messages: []` and `conversationId === "conv-empty"`
+
+### Requirement: formatProfileTable Renders a 4-Column Status Table
+The system MUST export a `formatProfileTable(statuses: ProfileStatus[]): string` function. The output MUST contain a header row with the four columns `NAME`, `ACTIVE`, `EXPIRES`, and `DEFAULT` (in that order), followed by a separator row of horizontal-line characters. The function MUST return the placeholder message `No profiles found. Run 'gemiterm login' to create one.` (dimmed) when the input array is empty.
+
+#### Scenario: Empty array returns a placeholder
+- **WHEN** `formatProfileTable([])` is called
+- **THEN** the result contains `No profiles found` and `gemiterm login`
+
+#### Scenario: Header row contains all four columns
+- **WHEN** `formatProfileTable([{ name: "default", exists: true, isActive: true, expiresAt: null, isDefault: false }])` is called
+- **THEN** the result contains `NAME`, `ACTIVE`, `EXPIRES`, and `DEFAULT`
+
+#### Scenario: Separator row follows the header
+- **WHEN** the table has at least one status
+- **THEN** the line immediately after the header is a row composed entirely of horizontal-line characters
+
+### Requirement: formatProfileTable Per-Status Coloring
+For each `ProfileStatus` row, the formatter MUST render the `ACTIVE` column with a green check (`✓`) when `isActive === true`, a red cross (`✗`) when `exists === true && isActive === false`, and an em-dash (`—`) when `!exists`. The formatter MUST render the `EXPIRES` column with a localized date when `expiresAt` is non-null, and with the text `N/A` when `expiresAt` is `null`. The formatter MUST append a `*` to the default profile's `NAME` and render the `DEFAULT` column as `Yes` for the default profile (empty for non-defaults). A footer line MUST read `* = default profile`.
+
+#### Scenario: Active check
+- **WHEN** a status has `isActive: true`
+- **THEN** the row's ACTIVE cell contains the check glyph
+
+#### Scenario: Inactive cross
+- **WHEN** a status has `exists: true, isActive: false`
+- **THEN** the row's ACTIVE cell contains the cross glyph
+
+#### Scenario: Missing profile
+- **WHEN** a status has `exists: false`
+- **THEN** the row's ACTIVE cell contains an em-dash
+
+#### Scenario: Expiry date rendering
+- **WHEN** a status has `expiresAt: "2026-12-31T00:00:00Z"`
+- **THEN** the row's EXPIRES cell contains `2026` (the year of the parsed date)
+
+#### Scenario: Null expiry
+- **WHEN** a status has `expiresAt: null`
+- **THEN** the row's EXPIRES cell contains `N/A`
+
+#### Scenario: Default marker and footer
+- **WHEN** a status has `isDefault: true`
+- **THEN** the rendered table contains `Yes` in the DEFAULT cell and the footer `* = default profile` is present
+
+### Requirement: formatChatList Renders a 4-Column Chat Table
+The system MUST export a `formatChatList(chats: ChatInfo[]): string` function. The output MUST contain a header row with the four columns `ID`, `TITLE`, `DATE`, and `PIN` (in that order), followed by a separator row. The function MUST return the placeholder message `No conversations found.` (dimmed) when the input array is empty.
+
+#### Scenario: Empty array returns a placeholder
+- **WHEN** `formatChatList([])` is called
+- **THEN** the result contains `No conversations found`
+
+#### Scenario: Header row contains all four columns
+- **WHEN** `formatChatList` is called with at least one chat
+- **THEN** the result contains `ID`, `TITLE`, `DATE`, and `PIN`
+
+#### Scenario: Separator row follows the header
+- **WHEN** the table has at least one row
+- **THEN** the line immediately after the header is composed entirely of horizontal-line characters
+
+### Requirement: formatChatList Per-Chat Rendering
+For each `ChatInfo`, the formatter MUST render the `ID` cell as the chat id (dimmed), the `TITLE` cell as the chat title truncated with an ellipsis (`…`) when it exceeds the column width, the `DATE` cell as a localized timestamp derived from `chat.timestamp`, and the `PIN` cell as a yellow pushpin emoji when `chat.isPinned === true` (empty otherwise). A footer line MUST report the total count, using the singular form `conversation` for exactly one entry and the plural form `conversations` otherwise.
+
+#### Scenario: Chat id appears in the table
+- **WHEN** a chat has `id === "abc123"`
+- **THEN** the result contains `abc123`
+
+#### Scenario: Long title is truncated
+- **WHEN** a chat has a 100-character title
+- **THEN** the result contains the ellipsis character `…` (the title has been truncated)
+
+#### Scenario: Pinned chat shows a pushpin
+- **WHEN** a chat has `isPinned: true`
+- **THEN** the result contains the pushpin emoji glyph in that row's PIN cell
+
+#### Scenario: Current year appears in the DATE cell
+- **WHEN** a chat has `timestamp: Date.now()`
+- **THEN** the result contains the current calendar year (i.e. the formatted date is rendered)
+
+#### Scenario: Plural footer
+- **WHEN** the chats array has 3 entries
+- **THEN** the footer reads `Total: 3 conversations`
+
+#### Scenario: Singular footer
+- **WHEN** the chats array has exactly 1 entry
+- **THEN** the footer reads `Total: 1 conversation` (no trailing `s`)

package/openspec/specs/install-browser/spec.md

@@ -0,0 +1,146 @@
+## Purpose
+
+The browser installation capability. It owns the `InstallBrowserService` that locates an existing system browser (Edge or Chrome on Windows, Chrome/Chromium/Edge on Linux, and Windows-hosted Edge/Chrome from inside WSL) and, when no system browser is found, shells out to `bunx @playwright/cli install chromium` to download a managed copy. It also owns the `install-browser` CLI command that surfaces the install to the user with friendly progress and error messaging.
+
+## Requirements
+
+### Requirement: InstallBrowserService.install prefers an existing system browser
+The `InstallBrowserService.install()` method MUST first call `findSystemBrowser()`. When the result has `found === true`, the method MUST log an info-level "Found existing browser" message that includes the browser name and resolved path, print the user-visible string `Using existing <browserName> installation.` to the console, and return successfully without spawning any install subprocess.
+
+#### Scenario: install short-circuits when a system browser is found
+- **WHEN** `install()` is called and `findSystemBrowser()` returns `{ found: true, browserName: "Microsoft Edge", path: "<path>" }`
+- **THEN** the method resolves successfully, the console receives a line containing `Using existing Microsoft Edge installation.`, and no `bunx @playwright/cli install` subprocess is spawned
+
+### Requirement: InstallBrowserService.install runs bunx playwright install when needed
+When `findSystemBrowser()` returns `found === false`, `install()` MUST print the string `No suitable browser found. Installing Chromium via Playwright...` to the console, log an info message containing `bunx @playwright/cli install chromium`, and then run the install subprocess. When the subprocess exits with code 0, the method MUST log the captured stdout, print `Chromium installed successfully.` to the console, and resolve successfully.
+
+#### Scenario: install runs the bunx subprocess and succeeds
+- **WHEN** `findSystemBrowser()` returns `{ found: false, browserName: "none" }` and the subprocess exits with code 0
+- **THEN** `install()` resolves successfully, the console receives `No suitable browser found. Installing Chromium via Playwright...` and `Chromium installed successfully.`, and the logger receives an info message containing `Browser installation output:`
+
+### Requirement: InstallBrowserService.install throws InstallBrowserError on failure
+When the install subprocess fails (non-zero exit, spawn error, or any other failure), the `install()` method MUST throw an `InstallBrowserError`. The error's `cause` field MUST be set to the underlying `PlaywrightCliError` when the failure originates from the CLI subprocess, or to the originating `Error` for any other failure. The error's `message` MUST include the underlying error's message so that the caller can surface it to the user.
+
+#### Scenario: Wraps PlaywrightCliError with cause
+- **WHEN** the spawn or the `playwright-cli install` subprocess fails and the underlying error is a `PlaywrightCliError`
+- **THEN** `install()` rejects with an `InstallBrowserError` whose `cause` is the `PlaywrightCliError` and whose `message` contains the `PlaywrightCliError.message` text
+
+#### Scenario: Wraps generic Error with cause
+- **WHEN** the subprocess fails for any other reason (e.g. spawn error with a plain `Error`)
+- **THEN** `install()` rejects with an `InstallBrowserError` whose `cause` is the originating `Error` and whose `message` contains the substring `Failed to install Chromium:`
+
+#### Scenario: InstallBrowserError exposes name and cause
+- **WHEN** an `InstallBrowserError` is constructed with a message and an optional cause
+- **THEN** `error.name === "InstallBrowserError"`, `error.message` is the supplied message, and `error.cause` is the supplied cause (or `undefined` when omitted)
+
+### Requirement: InstallBrowserService.findSystemBrowser dispatches by platform
+The `findSystemBrowser()` method MUST dispatch to a platform-specific finder based on `process.platform`. On `win32` it MUST call `findWindowsBrowser()`; on `linux` it MUST call `findLinuxBrowser()`; on any other platform it MUST return `{ found: false, browserName: "none" }`.
+
+#### Scenario: Windows platform delegates to the Windows finder
+- **WHEN** `findSystemBrowser()` is called with `process.platform === "win32"`
+- **THEN** the method returns the result of `findWindowsBrowser()` and uses the Edge/Chrome path resolution
+
+#### Scenario: Linux platform delegates to the Linux finder
+- **WHEN** `findSystemBrowser()` is called with `process.platform === "linux"`
+- **THEN** the method returns the result of `findLinuxBrowser()`
+
+#### Scenario: Unknown platform returns not found
+- **WHEN** `findSystemBrowser()` is called with `process.platform` set to a value other than `win32` or `linux` (e.g. `aix`)
+- **THEN** the method returns `{ found: false, browserName: "none" }`
+
+### Requirement: InstallBrowserService Windows finder checks Edge and Chrome
+The Windows browser finder MUST check, in order, the following candidate paths for Microsoft Edge and Google Chrome, returning the first one that exists on disk:
+- Edge under `%LOCALAPPDATA%\Microsoft\Edge\Application\msedge.exe` (resolved via `process.env["LOCALAPPDATA"]`, falling back to `<USERPROFILE>\AppData\Local`)
+- Edge under `Program Files\...\Microsoft\Edge\Application\msedge.exe` (resolved via `process.env["ProgramFiles(x86)"]` ?? `process.env["ProgramFiles"]` ?? `C:\Program Files`)
+- Chrome under `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe` (same `LOCALAPPDATA` resolution)
+- Chrome under `Program Files\...\Google\Chrome\Application\chrome.exe` (same `ProgramFiles` resolution)
+
+The returned object MUST set `browserName` to `"Microsoft Edge"` for an Edge hit and `"Google Chrome"` for a Chrome hit, and MUST set `path` to the resolved path. When none of the paths exist, the method MUST return `{ found: false, browserName: "none" }`.
+
+#### Scenario: Windows finder returns Edge when its local-appdata path exists
+- **WHEN** Edge is installed at `<LOCALAPPDATA>\Microsoft\Edge\Application\msedge.exe`
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Microsoft Edge", path: <resolved path> }`
+
+#### Scenario: Windows finder returns Chrome when its Program Files path exists
+- **WHEN** Chrome is installed at `<ProgramFiles(x86)>\Google\Chrome\Application\chrome.exe` and Edge is not installed at any checked location
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Google Chrome", path: <resolved path> }`
+
+#### Scenario: Windows finder returns not found when neither browser is installed
+- **WHEN** none of the Edge or Chrome candidate paths exist on disk
+- **THEN** `findSystemBrowser()` returns `{ found: false, browserName: "none" }`
+
+### Requirement: InstallBrowserService Linux finder checks standard paths
+The Linux browser finder MUST check, in order, the following candidate paths and return the first one that exists:
+- `/usr/bin/google-chrome` (label `Google Chrome`)
+- `/usr/bin/google-chrome-beta` (label `Google Chrome (Beta)`)
+- `/usr/bin/chromium` (label `Chromium`)
+- `/usr/bin/chromium-browser` (label `Chromium Browser`)
+- `/usr/bin/microsoft-edge` (label `Microsoft Edge`)
+
+When none of these paths exist, the finder MUST delegate to the WSL finder if `isWsl()` returns `true`, and MUST otherwise return `{ found: false, browserName: "none" }`.
+
+#### Scenario: Linux finder returns Google Chrome when present
+- **WHEN** `/usr/bin/google-chrome` exists on disk
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Google Chrome", path: "/usr/bin/google-chrome" }`
+
+#### Scenario: Linux finder returns Chromium when no Chrome is present
+- **WHEN** no Chrome Beta/Chromium/Edge binary exists but `/usr/bin/chromium` does
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Chromium", path: "/usr/bin/chromium" }`
+
+#### Scenario: Linux finder delegates to WSL finder when no Linux browser is found
+- **WHEN** none of the candidate Linux paths exist and `isWsl()` returns `true`
+- **THEN** `findSystemBrowser()` returns the result of the WSL finder
+
+#### Scenario: Linux finder returns not found when no browser is installed
+- **WHEN** none of the candidate Linux paths exist and `isWsl()` returns `false`
+- **THEN** `findSystemBrowser()` returns `{ found: false, browserName: "none" }`
+
+### Requirement: InstallBrowserService WSL finder checks Windows paths from inside WSL
+The WSL browser finder MUST resolve a Windows root from `/proc/mounts` by finding a line that contains both the substrings `9p` and `drvfs` and using the second whitespace-separated field as the mount point (stripping any trailing `/` or path separator). When no such mount is found, the method MUST return `{ found: false, browserName: "none" }`. With a valid Windows root, the method MUST check, in order:
+- `<windowsRoot>/Program Files (x86)/Microsoft/Edge/Application/msedge.exe` (label `Microsoft Edge (Windows via WSL)`)
+- `<windowsRoot>/Program Files/Google/Chrome/Application/chrome.exe` (label `Google Chrome (Windows via WSL)`)
+
+The `isWsl()` helper MUST return `true` only when `/proc/version` exists AND its content (lower-cased) contains the substring `microsoft`; otherwise it MUST return `false`.
+
+#### Scenario: WSL finder resolves the Windows root from /proc/mounts
+- **WHEN** `/proc/mounts` contains a line matching `9p drvfs` whose mount point is `/mnt/c`
+- **THEN** the WSL finder treats `/mnt/c` as the Windows root for path resolution
+
+#### Scenario: WSL finder returns Edge when the Windows Edge path exists
+- **WHEN** the resolved Windows root is `/mnt/c` and `/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe` exists
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Microsoft Edge (Windows via WSL)", path: <resolved path> }`
+
+#### Scenario: WSL finder returns Chrome when only the Windows Chrome path exists
+- **WHEN** the resolved Windows root is `/mnt/c`, the Edge path does not exist, and `/mnt/c/Program Files/Google/Chrome/Application/chrome.exe` does exist
+- **THEN** `findSystemBrowser()` returns `{ found: true, browserName: "Google Chrome (Windows via WSL)", path: <resolved path> }`
+
+#### Scenario: WSL finder returns not found when no Windows browser is reachable
+- **WHEN** the resolved Windows root is `/mnt/c` and neither the Edge nor the Chrome path exists
+- **THEN** `findSystemBrowser()` returns `{ found: false, browserName: "none" }`
+
+#### Scenario: WSL finder returns not found when no 9p drvfs mount is present
+- **WHEN** `/proc/mounts` does not contain any `9p` `drvfs` line
+- **THEN** `findSystemBrowser()` returns `{ found: false, browserName: "none" }`
+
+### Requirement: InstallBrowserCommand wraps the install service for CLI invocation
+The `InstallBrowserCommand` class MUST be registered as the CLI command `"install-browser"` with a description that includes the word `Chromium`. The `execute(_args, _context)` method MUST instantiate an `InstallBrowserService` (passing a logger named `"install-browser-command"`), print the dim message `Checking browser installation...` to the console, call `service.install()`, and on success print the green message `Browser ready.` to the console.
+
+#### Scenario: InstallBrowserCommand metadata
+- **WHEN** an `InstallBrowserCommand` instance is constructed
+- **THEN** `command.name === "install-browser"` and `command.description` contains the substring `Chromium`
+
+#### Scenario: Successful install prints the ready message
+- **WHEN** `execute([], { verbose: false })` is called and `service.install()` resolves
+- **THEN** the console receives `Checking browser installation...` followed by `Browser ready.` and the method resolves successfully
+
+### Requirement: InstallBrowserCommand handles InstallBrowserError with a friendly message and exits non-zero
+When `service.install()` rejects with an `InstallBrowserError`, the `InstallBrowserCommand.execute` method MUST:
+- Log the error's message at error level via the logger.
+- When the error has a `cause`, log `Cause: <cause.message>` at error level via the logger.
+- Print the red message `Failed to install browser.` to stderr.
+- Print the dim message `You may need to run: bunx @playwright/cli install chromium` to stderr as remediation.
+- Call `process.exit(1)` to terminate the process with a non-zero exit code.
+
+#### Scenario: InstallBrowserError causes exit code 1
+- **WHEN** `service.install()` rejects with an `InstallBrowserError` whose message is `install failed`
+- **THEN** `execute` ultimately causes `process.exit` to be called with `1` and stderr receives the friendly failure and remediation messages

package/openspec/specs/interactive-prompt-loop/spec.md

@@ -0,0 +1,41 @@
+## Purpose
+
+This capability defines the interactive prompt loop utility used by CLI chat commands for continuous back-and-forth conversations.
+
+**Status:** TBD
+
+## ADDED Requirements
+
+### Requirement: Interactive prompt loop SHALL support continuous chat sessions
+The interactive prompt loop utility SHALL provide a reusable mechanism for chat commands to engage in continuous back-and-forth conversations with the user until explicitly terminated.
+
+#### Scenario: User sends multiple messages in a session
+- **WHEN** user starts an interactive session and enters a message
+- **THEN** the system processes the message and displays the response
+- **AND** the system prompts for the next message
+
+#### Scenario: User can exit the session
+- **WHEN** user types "/exit" or "/quit"
+- **THEN** the system displays "Goodbye." and terminates the session
+
+#### Scenario: Empty input is handled gracefully
+- **WHEN** user presses Enter without typing anything
+- **THEN** the system re-prompts without sending an empty message
+
+#### Scenario: Errors during message processing do not terminate the session
+- **WHEN** user enters a message but processing throws an error
+- **THEN** the system displays the error message
+- **AND** the system re-prompts for the next message
+
+### Requirement: Interactive prompt loop SHALL support command-specific message handling
+The utility SHALL accept a callback function that handles each message, allowing different commands to process messages differently.
+
+#### Scenario: New chat command creates new conversation
+- **WHEN** the new command uses the interactive loop with a message handler
+- **AND** user enters a message
+- **THEN** the system starts a new conversation and displays the response
+
+#### Scenario: Continue command sends to existing conversation
+- **WHEN** the continue command uses the interactive loop with a message handler
+- **AND** user enters a message
+- **THEN** the system sends the message to the existing conversation ID