@jslee124/forge 0.3.0 → 0.3.2

package/resources/docs/en/AUTHENTICATION.md

@@ -0,0 +1,224 @@
+# Authentication Model
+
+简体中文 · Documentation index
+
+## Status
+
+Forge supports DeepSeek and OpenAI API-key authentication through
+`DEEPSEEK_API_KEY` and `OPENAI_API_KEY`, plus ChatGPT subscription
+authentication through the official Codex App Server.
+User-scoped provider routes additionally support an explicitly selected bearer
+credential or no authentication for local/self-hosted endpoints.
+Forge presents the login command and browser/device-code instructions, while
+Codex owns OAuth, credential persistence, refresh, and revocation.
+
+## Supported and planned methods
+
+| Method | Intended use | Status |
+| --- | --- | --- |
+| DeepSeek API key | Local development and automation | Implemented |
+| OpenAI API key | Optional usage-based OpenAI API access | Implemented |
+| Provider route bearer key | OpenAI-compatible gateways | Implemented |
+| Provider route without authentication | Local Ollama/vLLM-style servers | Implemented |
+| Sign in with ChatGPT | OpenAI subscription access through Codex App Server | Implemented |
+| Codex access token | Trusted enterprise automation | Deferred |
+
+DeepSeek's official API uses `https://api.deepseek.com` and the initial adapter
+uses the official AI SDK provider package. The model ID remains configurable
+because provider model names have a different lifecycle from the Forge release.
+
+Official DeepSeek references:
+
+- [DeepSeek API model documentation](https://api-docs.deepseek.com/quick_start/pricing/)
+- [AI SDK DeepSeek provider](https://ai-sdk.dev/providers/ai-sdk-providers/deepseek)
+
+OpenAI now documents Codex App Server as the integration protocol for embedding
+Codex into a product. Its account surface supports managed ChatGPT browser and
+device-code login. Forge uses that public surface rather than copying OpenCode's
+OAuth client ID or rewriting requests to an undocumented ChatGPT endpoint.
+
+Official reference:
+[OpenAI Codex App Server](https://developers.openai.com/codex/app-server)
+
+## Architectural boundary
+
+The two execution paths have different ownership boundaries:
+
+```text
+Forge Engine: Forge Runtime -> Model Adapter -> DeepSeek or OpenAI API
+
+Codex Engine: Forge CLI -> Codex App Server -> ChatGPT subscription
+```
+
+The Codex Engine is not wrapped as a Forge `ModelAdapter`: App Server owns a
+complete agent runtime, including turns, tools, sandboxing, approvals, and
+history. Treating it as a raw model transport would obscure which runtime made
+security and execution decisions.
+
+The provider-neutral authentication manager resolves API keys from an explicit
+environment variable first, then from Forge's owner-readable user credential
+store. Missing credentials produce an actionable error without printing the
+key or a stack trace. Keys are never copied into Forge configuration, prompts,
+traces, plugin events, or repository files.
+
+## OpenAI-compatible provider routes
+
+Routes are declared under `providers` in `$FORGE_HOME/config.json`. They name a
+wire protocol, canonical endpoint, explicit authentication mode, and model
+profiles. Repository `.forge/config.json` files may not define routes because
+that would let untrusted project content decide where a user credential is
+sent.
+
+```json
+{
+  "schemaVersion": 1,
+  "providers": {
+    "my-gateway": {
+      "api": "openai-responses",
+      "baseUrl": "https://gateway.example/openai/v1",
+      "auth": { "type": "bearer", "apiKeyEnv": "GATEWAY_API_KEY" },
+      "models": [
+        {
+          "id": "reasoning-model",
+          "contextWindow": 128000,
+          "maxOutputTokens": 8192,
+          "reasoningGears": { "none": "none", "high": "high" }
+        }
+      ]
+    }
+  }
+}
+```
+
+`auth.type` is mandatory. `bearer` reads the declared variable, or derives
+`FORGE_<ROUTE>_API_KEY`, before consulting Forge's stored credential. `none`
+does not read or send any API key. Stored route credentials are bound to the
+canonical `baseUrl`; after an endpoint change Forge refuses the old key until a
+new one is saved.
+
+Remote endpoints require HTTPS. Plain HTTP is accepted only for loopback hosts.
+URLs containing credentials, query strings, or fragments are rejected. Model
+discovery does not follow redirects, remains bounded to 4 MiB and 15 seconds,
+and is optional because model IDs can be entered manually.
+
+Forge treats an omitted reasoning setting as **provider default**, which is not
+the same as disabling reasoning. Each `reasoningGears` entry maps a Forge UI
+level to the exact wire value sent to the provider, so an explicit
+`"none": "none"` is required when the endpoint supports disabling reasoning.
+Legacy version-1 `null` mappings are read as their canonical key to avoid
+silently turning `none` into provider default.
+
+Model discovery also accepts bounded optional reasoning metadata such as
+`reasoning_efforts`, `supported_reasoning_efforts`, or
+`capabilities.reasoning.efforts`. These fields are non-standard extensions:
+when they are absent Forge reports capabilities as unknown and keeps provider
+defaults instead of guessing or issuing paid probe requests. The setup screen
+prefills advertised levels and lets the user override them before saving.
+
+An OpenAI API key is optional and is billed independently of ChatGPT. A ChatGPT
+Plus, Pro, Business, or other subscription does not cause Forge to select the
+API path. Users who only want subscription access should keep
+`model.provider = "deepseek"` or use `forge codex`; they do not need to create
+or export `OPENAI_API_KEY`.
+
+## Compatibility requirements
+
+The selected App Server integration satisfies these requirements:
+
+- The flow is publicly documented for embedding Codex into a product
+- Forge never supplies or copies an OAuth client identity
+- Codex performs token exchange, refresh, revocation, and account selection
+- The user-facing description accurately distinguishes subscription access from
+  usage-based API access
+
+Forge must not:
+
+- Copy another application's client secret or identity
+- Treat reverse-engineered endpoints as a permanent API contract
+- Ask users to paste access or refresh tokens into chat
+- Read, import, or modify `~/.codex/auth.json` directly
+- Store credentials inside the current repository
+
+## Credential storage
+
+The interactive `/login` flow can persist API keys in
+`$FORGE_HOME/auth.json`. The directory is mode `0700`, the file is mode `0600`,
+updates are atomic, and environment variables take precedence. This is a
+plaintext filesystem-protected fallback rather than an OS keychain. ChatGPT
+subscription credentials remain owned entirely by Codex App Server.
+The interactive `/logout` picker lists authenticated providers, removes the
+selected stored API credential, or asks Codex App Server to sign out the
+ChatGPT subscription. A logged-out third-party route remains visible as signed
+out in `/login`, where it can be authenticated again. The route management
+screen has a separate confirmed **Remove provider** action that deletes the
+route, its models, and its stored credential. It reports any provider
+environment variable that remains active; Forge cannot unset a variable in the
+parent shell.
+
+The current runtime lookup order is:
+
+1. The provider's explicit or conventional environment variable
+2. `$FORGE_HOME/auth.json`, outside the project with owner-only permissions
+
+An operating-system credential store would be preferable to plaintext file
+storage and remains a future improvement. Environment variables remain the
+recommended injection mechanism for automation.
+
+Credentials must be excluded from prompts, run events, JSONL traces, plugin
+events, telemetry, and ordinary error messages.
+
+## Refresh and concurrency
+
+Codex App Server owns subscription token refresh and persistence. Forge never
+receives OAuth access or refresh tokens. The App Server may use the Codex
+credential-store configuration shared with other local Codex clients.
+
+Credential updates must be atomic. A failed refresh must not destroy the last
+known credential before the error is handled.
+
+## Commands
+
+The CLI exposes:
+
+```text
+forge auth login openai
+forge auth status openai
+forge auth status openai-api
+forge auth logout openai
+forge models list --provider openai
+forge codex "Inspect this repository" --model <id> --reasoning-effort <effort>
+forge run "Inspect this repository" --provider openai --model gpt-5.4-mini --reasoning-effort low
+```
+
+Use `forge auth login openai --method device-code` for a headless login. Forge
+prints the official verification URL and code and waits for App Server's
+completion notification. Browser callback validation and PKCE are owned by
+Codex. Cancelling Forge asks App Server to cancel the pending login.
+
+Sign-in URLs are much wider than a terminal window. Terminals that linkify
+plain text do so one display line at a time, so a wrapped URL would stay
+clickable only up to its first wrap. Forge therefore emits the URL as a single
+OSC 8 hyperlink on terminals known to support it, including VS Code, Ghostty,
+WezTerm, iTerm2, Kitty, Windows Terminal, Konsole, and VTE 5000 or newer. The
+visible label remains the complete address, so an unsupported terminal still
+shows a copyable URL. Redirected output, `TERM=dumb`, and `NO_COLOR` always
+produce the bare URL. Set `FORCE_HYPERLINK=1` to opt an unrecognized terminal
+in, or `FORCE_HYPERLINK=0` to opt out.
+
+`forge auth logout openai` operates on the shared Codex account and can sign
+other local Codex clients out. Forge does not claim that these are Forge-owned
+credentials.
+
+`forge auth status openai-api` reports whether an environment or stored
+credential is active; it never validates the key with a paid request.
+`forge auth login openai-api` directs the user to the masked interactive
+`/login` flow or `OPENAI_API_KEY` because the plain subcommand never reads a
+secret from command arguments. The interactive `/model` picker discovers the current Codex catalog
+and also shows native API adapters without duplicating models by reasoning
+effort. The separate `/effort` picker and Shift+Tab shortcut use the selected
+model's supported levels. Forge persists these ordinary
+engine/provider/model/reasoning settings under `$FORGE_HOME/config.json`;
+credentials remain separate in the environment, `$FORGE_HOME/auth.json`, or
+Codex-owned storage.
+Selecting a ChatGPT entry routes subsequent interactive prompts through Codex
+Engine.

package/resources/docs/en/CLI_UI.md

@@ -0,0 +1,266 @@
+# Interactive CLI UI
+
+简体中文 · Documentation index
+
+## Status
+
+This document defines the implemented Milestone 4.6 terminal experience. Ink
+now provides the interactive renderer while the non-interactive commands and
+Forge-owned runtime retain their existing boundaries.
+
+## Goals
+
+The interactive CLI should make common coding-agent actions discoverable
+without moving the agent loop, tools, or policy decisions out of Forge core.
+The terminal UI should provide:
+
+- A multi-line prompt editor
+- Discoverable slash-command completion
+- Workspace-file completion with `@`
+- Clear streamed reasoning, answers, tool activity, and run state
+- Terminal-native Markdown for headings, lists, quotes, links, inline code,
+  emphasis, and fenced code blocks
+- A readable diff review before file-write approval
+- Keyboard-only operation with predictable cancellation
+- A startup capability summary inside the blue Forge frame
+
+Ink is the renderer for the interactive CLI. Commander remains
+responsible for process-level command parsing. React and Ink must stay inside
+`apps/cli`; `@forge/core` must remain independent of the terminal framework.
+Forge uses full-frame Ink updates so terminal reflow during a resize cannot
+leave stale rows from the previous width.
+
+## Startup capability summary
+
+Before the first prompt, the blue Forge frame lists enabled user plugins,
+project plugins with `trusted` or `untrusted, skipped` state, and discovered
+built-in, user, and project Skills. Compact category labels follow Pi's resource-list pattern while
+preserving Forge's explicit trust semantics.
+
+Startup detection reads plugin manifests and Skill metadata only. It must not
+import a project plugin merely to display its name. Actual plugin activation
+remains part of a native Forge Engine run. Native runs advertise bounded Skill
+metadata and lazily load matching Skills; explicit `$skill-name` remains an
+override. The Codex Engine owns a separate tool
+runtime, so the listing describes Forge resources rather than Codex tools.
+
+`/plugins` opens a metadata-only review panel. It shows each project plugin's
+version, capabilities, and current workspace trust state. Trust requires a
+second `y` confirmation after an in-process privilege warning; revocation is
+available from the same panel. A successful decision refreshes the blue startup
+frame immediately, while plugin activation remains deferred until the next
+native Forge Engine task.
+
+## Interaction states
+
+The UI owns an explicit state machine so menus, streaming output, and approval
+prompts never compete for the same terminal input:
+
+```text
+editing
+ |-- "/" --> selecting_command -- execute/insert --> editing
+ |-- "@" --> selecting_file ---- insert ---------> editing
+ `-- submit --> running --> awaiting_approval --> running --> editing
+                    `---------------- completed ------------^
+```
+
+Only the active state consumes keyboard input. Ctrl+C closes an open completion
+menu first, cancels an active run second, and preserves the existing deliberate
+session-exit behavior when Forge is otherwise idle.
+
+## Prompt editor
+
+- Enter submits a non-empty prompt when no completion or approval menu owns the
+  key.
+- Shift+Enter inserts a newline without submitting. Terminal integrations that
+  encode it as Meta+Enter (`ESC+Enter`) are treated the same way.
+- Because some legacy terminals do not distinguish Shift+Enter from Enter,
+  Ctrl+J also inserts a newline as a portable fallback. The input footer should
+  advertise the shortcut that is available.
+- Forge directly enables the enhanced keyboard protocol in known-compatible
+  terminals such as VS Code and Ghostty, avoiding a startup capability query
+  that some terminals echo as input. Older or unknown terminals continue to
+  use Ctrl+J or Meta+Enter as fallbacks.
+- The editor preserves newlines exactly when constructing the user message.
+- Left/right movement, backspace, delete, Home/End, paste, Unicode text, and
+  terminal resize must not corrupt the buffer or display.
+- Up/down keys navigate an open completion menu. When no menu is open, they may
+  later be used for prompt history; history is not required for Milestone 4.6.
+- Shift+Tab cycles through the active model's supported thinking-effort levels.
+
+## Slash-command completion
+
+Typing `/` as the first non-whitespace character opens a list of available
+commands. Additional characters filter the list by command name.
+
+Each command is defined once with its name, description, and handler. The same
+registry drives completion and `/help`, preventing the two surfaces from
+drifting. The registry contains `/help`, `/new`, `/clear`, `/context`,
+`/compact`, `/plugins`, `/login`, `/logout`, `/model`, `/delete-model`,
+`/effort`, `/resume`, and `/exit`.
+`/plugins` opens the project-plugin trust review described above. `/model`
+opens a keyboard picker, discovers current
+ChatGPT/Codex models, includes configured API providers, and saves one model
+entry without multiplying it by effort level. `/effort` opens a separate
+model-specific effort picker; `/effort <level>` sets a supported level directly.
+Both selections are atomically saved to user configuration.
+`/logout` lists authenticated providers and removes a selected stored
+credential without pretending to unset a parent-shell environment variable.
+`/delete-model` shows only user-configured provider models, requires
+confirmation, retains the provider route and credential, and refuses to delete
+the active model until another is selected.
+The `/login` picker always lists configured third-party routes, including their
+full Base URL, API type, authentication mode, status, and model count. Selecting
+a route opens provider management: add or restore a model, delete one configured
+model, log out when a stored credential is active, or remove the provider.
+Deleting a model keeps the route and credential so it can be added again
+immediately. Logout leaves a signed-out
+route visible. Remove provider is a separate confirmed action that deletes the
+route, its models, and its stored credential; it refuses to remove the active
+provider and cannot unset a parent-shell environment variable.
+
+Model setup prefills reasoning levels only when `/models` returns recognized,
+bounded capability metadata. It labels the source as discovered or manual;
+with no metadata, Enter keeps the provider default. Forge does not infer that
+missing metadata means a non-reasoning model and does not make paid capability
+probe requests. Provider management separately labels the protocol-supported
+tool surface and the provider's end-to-end agent loop as unverified.
+
+- Up/Down changes the highlighted command.
+- Enter executes the highlighted command.
+- Tab completes its name without executing it.
+- Escape closes the menu without changing the input.
+- A slash elsewhere in ordinary prose or a filesystem path does not open the
+  command menu.
+
+## Workspace-file mentions
+
+Typing `@` opens a bounded list of files beneath the selected workspace. Text
+after the active `@` token filters candidates by relative path using
+case-insensitive fuzzy matching.
+
+- Candidate paths are workspace-relative and use `/` as the display separator.
+- `.git`, dependency directories, build output, and paths outside the canonical
+  workspace are excluded.
+- The menu shows at most 10 ranked candidates and indicates when more matches
+  exist.
+- Up/Down changes the highlighted file; Enter or Tab inserts it; Escape closes
+  the menu.
+- Selecting a file inserts a visible mention while retaining a structured
+  `{ path }` reference in editor state. Paths with spaces must not depend on
+  reparsing the rendered prompt.
+- File discovery is read-only, bounded, cancellable, and does not invoke the
+  model or run an external shell command for every keystroke.
+
+On submission, Forge sends the user's text plus an explicit list of referenced
+workspace-relative paths to the model. Selecting a mention does not
+automatically inject the complete file contents. The model can use `read_file`
+through the normal tool, policy, and trace path when it needs the contents.
+
+## Pasted image attachments
+
+When a bracketed paste or terminal drag-and-drop begins with an absolute image
+path, Forge removes that path from the text and shows a compact
+`[Image #N] filename` attachment. This supports OS and terminal clipboard
+helpers that materialize screenshots beneath temporary directories such as
+`/var/.../T/otty-paste/`. Quoted paths, shell-escaped spaces, and `file://`
+paths are accepted. Backspace removes the most recent attachment when the text
+composer is empty.
+
+This is an explicit user action, so the attachment may be outside the selected
+workspace. Forge does not scan arbitrary prompt prose for image paths, and this
+does not widen the workspace boundary used by model file tools. The active
+model must support image input.
+
+Example logical message:
+
+```text
+Please explain the cancellation behavior.
+
+Referenced files:
+- apps/cli/src/session.ts
+```
+
+## Diff review
+
+File-write approval must present the exact proposed change in a dedicated,
+readable panel before the user decides. The renderer should show:
+
+- Operation and path: create, modify, or delete
+- A compact file summary and changed-line counts
+- Unified diff hunks with old/new line numbers
+- Added lines in green with `+`, removed lines in red with `-`, and subdued
+  context lines
+- Clear file and hunk headers that remain understandable without color
+- Syntax highlighting when the file type is known, without allowing syntax
+  color to obscure addition/removal meaning
+- An explicit truncation message when a safety display limit is reached
+
+Approval must never rely on color alone. `--no-color`, a non-color terminal,
+and common color-vision deficiencies must retain the `+`/`-`, headers, and line
+number cues. A diff that exceeds the safe review limit remains unapprovable;
+visual truncation must not silently turn partial content into approval for an
+unseen patch.
+
+The approval controls are visible next to the diff and describe their scope.
+For example, approving the first workspace write covers later workspace writes
+only in the current run, while process commands continue to require separate
+approval.
+
+Process-command approval uses the same dedicated panel. It renders a
+shell-readable `$ command` line followed by clearly labelled working-directory
+and timeout rows; these details must not appear as detached transcript text.
+
+Network-tool approval also uses the dedicated panel. It shows the registered
+tool name and the bounded URL or search query that will be sent externally.
+Plugin-specific secrets and arbitrary input objects are never rendered as an
+approval preview.
+
+## Sign-in panel
+
+A pending browser sign-in is a dedicated panel, not transcript text. The Codex
+auth surface reports the URL as a structured `login` output event carrying the
+address as its own field, so the UI never re-parses it out of a text chunk.
+
+Sign-in URLs are several times wider than a terminal window. The panel wraps
+the address in a single OSC 8 hyperlink, which keeps the whole URL clickable
+after Ink wraps it; terminals that linkify plain text do so one display line at
+a time and would otherwise leave only the first wrapped line clickable. The
+visible label stays the complete address so an unsupported terminal still shows
+a copyable URL, and escape sequences must not count toward display width or the
+panel border would fall out of alignment.
+
+## Rendering boundaries
+
+The CLI may turn runtime events into components such as message blocks, tool
+activity rows, status indicators, and diff panels. It must not infer execution
+success from presentation state or parse previously rendered terminal text.
+
+Core events and approval requests remain the source of truth. Interactive and
+non-interactive commands continue to share the same Forge-owned runtime,
+workspace validation, policy gateway, and tool execution behavior.
+
+Model Markdown is rendered as a bounded terminal-native subset rather than
+HTML. The renderer must tolerate incomplete constructs while text is streaming
+and strip model-supplied ANSI control sequences before styling output.
+
+## Test strategy
+
+Milestone 4.6 should include deterministic tests for:
+
+- Slash-menu opening, filtering, navigation, selection, and dismissal
+- File candidate filtering, ignored directories, result limits, spaces, and
+  prevention of workspace escape
+- Structured file mentions and the exact model message assembled from them
+- Enter submission versus Shift+Enter, Meta+Enter, and Ctrl+J newline insertion
+- Multi-line editing, paste, Unicode, resize, and cancellation
+- State transitions between editing, completion, running, and approval
+- Startup plugin/Skill listing, trust labels, and metadata-only discovery
+- Diff rendering for create and modify operations, multiple hunks, no-color
+  output, truncation, and approval scope
+
+No UI test may require a paid model request. Component tests should consume
+scripted input and events, while a small pseudo-terminal integration test proves
+the supported key sequences in representative terminals.
+
+`/resources` shows every discovered Skill's source, description, automatic or explicit-only status, shadowing, and bounded diagnostics. It does not import plugin entries or eagerly load Skill bodies. `/plugins` remains limited to executable plugins and points users to `/resources` for Skills.