surfcode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geetank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/surfcode-logo.gif" alt="SurfCode" width="480">
+
+### Ride the code.
+
+**A beautiful, provider-agnostic AI coding agent for your terminal.**
+One keyboard-driven TUI. Any model. Your keys, your machine, no telemetry.
+
+<br>
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea043?style=for-the-badge)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-3c873a?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=for-the-badge&logo=typescript&logoColor=white)](tsconfig.json)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4?style=for-the-badge)](CONTRIBUTING.md)
+
+[**Install**](#-install) · [**Quick start**](#-quick-start) · [**Features**](#-features) · [**Providers**](#-any-model-any-provider) · [**Headless**](#-headless--ci) · [**Full docs**](docs/REFERENCE.md)
+
+</div>
+
+<br>
+
+---
+
+## ✨ Why SurfCode?
+
+Most coding agents lock you to one vendor, one model, and one pricing page. SurfCode doesn't.
+
+| | |
+| :-- | :-- |
+| 🌊 **Provider-agnostic** | OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Ollama… **232 providers and 9,000+ models** from the [models.dev](https://models.dev) catalog, with an offline snapshot bundled. |
+| 🛡️ **You stay in control** | Reads are free, writes and shell commands ask first. A read-only **plan mode** lets the agent look but never touch. |
+| 🔒 **Local-first** | Keys, sessions and config never leave your machine. **No telemetry. No background uploads.** |
+| ⚡ **Fast and calm** | Alternate-screen TUI that only repaints what changed. Replies land complete; turn on live typing with `/stream on`. |
+| 🤖 **Scriptable** | `surf run` gives clean stdout, NDJSON events and deterministic exit codes, so it drops straight into pipes and CI. |
+
+<br>
+
+## 📦 Install
+
+> Requires **Node.js 22+** and a modern terminal (iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal, …).
+
+**From npm**
+
+```bash
+npm install -g surfcode
+surf --version
+```
+
+**Straight from GitHub**
+
+```bash
+npm install -g github:Official-SurfCode/surfcode
+```
+
+**From source**
+
+```bash
+git clone https://github.com/Official-SurfCode/surfcode.git
+cd surfcode
+npm install        # also builds dist/
+npm link           # puts `surf` and `surfcode` on your PATH
+```
+
+Both commands, **`surf`** and **`surfcode`**, do the same thing.
+
+<br>
+
+## 🚀 Quick start
+
+```bash
+surf
+```
+
+The first launch opens the full-screen UI. Then:
+
+```text
+/connect      pick a provider and paste a key (ctrl+v)
+/model        browse models from the providers you've connected
+/help         every command and shortcut
+```
+
+Prefer the shell?
+
+```bash
+surf auth anthropic                    # hidden key prompt
+surf models --provider openai          # browse the catalog
+surf run "explain src/core/agent.ts"   # one-shot, no UI
+```
+
+Already have `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GEMINI_API_KEY` in your environment? SurfCode finds it and picks a sensible default model on its own.
+
+<br>
+
+## 🧰 Features
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🖥️ A TUI worth living in
+- Alternate screen, smooth scrolling, markdown and syntax highlighting
+- **Six themes**: `aurora` · `dark` · `ember` · `forest` · `violet` · `mono`
+- A resizable **file explorer dock** with live previews
+- `@file` attachments and `!command` shell passthrough
+- Command palette, input history, tab completion
+
+</td>
+<td width="50%" valign="top">
+
+### 🔧 Real tool use
+- `read` · `write` · `edit` · `ls` · `glob` · `grep` · `bash` · `webfetch` · `todo_write`
+- Inline diffs for every edit
+- Non-interactive shell with timeouts and capped output
+- Project instructions from `SURFCODE.md`, `AGENTS.md` or `CLAUDE.md`
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🧠 Reasoning on tap
+- `/effort low|medium|high|auto`, mapped to each provider's native controls
+- Gemini 3 `thinkingLevel`, Gemini 2.5 budgets, Anthropic extended thinking, OpenAI `reasoning_effort`
+- `/thinking` shows or hides reasoning text
+
+</td>
+<td width="50%" valign="top">
+
+### 🎛️ Multi-model orchestration
+- `/agent add provider/model` keeps your model as the **head**
+- Up to **8 worker models** run in parallel via a read-only `delegate` tool
+- Workers never touch your files; the head verifies and synthesizes
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 💬 Side questions, no baggage
+- `/btw <question>` answers with the conversation as context
+- No tools, and it leaves nothing in the session or usage totals
+
+</td>
+<td width="50%" valign="top">
+
+### 📊 Honest usage and cost
+- Provider-reported input, output, reasoning and cache tokens
+- `/cost` and `/context` show where your budget is going
+- `/compact` summarizes history to free context
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🐙 GitHub publishing, on request
+- Log in with a token, then ask in plain language
+- Create a repo, upload a project, commit and push later
+- Never force-pushes, never rewrites history, never deletes a repo
+- Nothing is published unless you ask
+
+</td>
+<td width="50%" valign="top">
+
+### ☁️ Optional BYOK session sync
+- Run the tiny self-hosted sync server, or bring your own HTTPS endpoint
+- **Only session records sync.** API keys never leave your machine
+
+</td>
+</tr>
+</table>
+
+<br>
+
+## 🌊 Any model, any provider
+
+```text
+OpenAI · Anthropic · Google · Azure OpenAI · Vertex · OpenRouter · DeepSeek
+xAI · Mistral · Groq · Cerebras · Together · Fireworks · DeepInfra · Cohere
+Perplexity · Moonshot · Zhipu · GitHub Copilot · Cloudflare Workers AI  …and 200+ more
+```
+
+- Providers with a permanent free API tier are tagged **`[FREE API]`** in the picker.
+- **Local models just work.** Ollama, llama.cpp, vLLM and LM Studio are auto-detected when running.
+- Bring anything OpenAI-compatible with a custom `baseURL`.
+- `surf update-models` refreshes the catalog; the bundled snapshot is the offline fallback.
+
+<br>
+
+## ⌨️ Commands you'll use daily
+
+| Command | What it does |
+| :-- | :-- |
+| `/model` · `/connect` · `/provider` | Switch model, add a key, browse providers |
+| `/effort` · `/thinking` · `/stream` | Reasoning depth, visible thoughts, live typing |
+| `/plan` · `/build` | Toggle read-only plan mode (also `shift+tab`) |
+| `/agent` | Run worker models in parallel |
+| `/btw <q>` | Ask a side question without saving it |
+| `/explorer` · `/theme` · `/options` | File dock, themes, settings |
+| `/sessions` · `/new` · `/compact` · `/export` | Resume, restart, shrink, save as Markdown |
+| `/github` | Connect GitHub and publish code |
+| `/cost` · `/context` | Tokens, spend and context usage |
+
+<details>
+<summary><b>Keyboard shortcuts</b></summary>
+
+<br>
+
+| Key | Action |
+| :-- | :-- |
+| `enter` | Send prompt |
+| `ctrl+j` | New line |
+| `esc` | Stop generating / leave dock / close overlay |
+| `ctrl+c` | Interrupt (press twice to exit) |
+| `tab` | Complete a command or file |
+| `shift+tab` | Toggle plan / build mode |
+| `ctrl+t` | Cycle themes |
+| `ctrl+o` | Focus the file dock |
+| `ctrl+←` / `ctrl+→` | Resize the dock |
+| `ctrl+v` | Paste from the clipboard |
+| `pgup` / `pgdn` | Scroll the transcript |
+| `?` | Help (when the prompt is empty) |
+
+</details>
+
+<br>
+
+## 🛡️ Safe by default
+
+Every tool action is classified, and you decide what is allowed.
+
+| Action | Default |
+| :-- | :-- |
+| `read` · `fetch` | ✅ allow |
+| `write` · `shell` | ❓ ask first |
+| Outside the workspace | 🚫 off |
+| **Plan mode** | 🔒 read-only, nothing can mutate |
+
+- Choose **yes**, **always** or **no** at each prompt. Deny an action for good with `"permissions": { "shell": "deny" }`.
+- Destructive shell commands are flagged as high-risk in the prompt.
+- `/access full` is an explicit opt-in for trusted machines. A red badge shows while it's on.
+- `surf config` redacts keys, tokens and auth headers.
+
+<br>
+
+## 🤖 Headless & CI
+
+```bash
+surf run "summarize this repository"
+cat error.log | surf run "explain this failure"
+surf run --plan "map the auth flow before changing it"
+surf run --yes "run the tests and fix failures"
+surf run --json --yes "list the files" | jq -c 'select(.type == "result")'
+```
+
+Answers stream to **stdout**, tool progress to **stderr**, so pipes stay clean. With `--json` you get one NDJSON event per line. Exit codes are `0` success, `1` error, `130` interrupted.
+
+<br>
+
+## 🩺 Handy CLI
+
+```text
+surf                    open the TUI
+surf run [prompt]       one-shot headless run
+surf auth [provider]    connect a provider or GitHub
+surf models [query]     browse the model catalog
+surf providers          provider status (--all for the full catalog)
+surf sessions           list and manage saved sessions
+surf config             inspect or edit configuration
+surf doctor             diagnose problems (--network to test connectivity)
+surf update-models      refresh the models.dev catalog
+```
+
+<br>
+
+## 🏗️ Project layout
+
+```text
+src/
+  cli.tsx        command-line entry
+  cli/           auth, config, sessions, inspect, headless, interactive
+  core/          catalog, providers, chat dialects, agent loop, sessions
+  tools/         read, write, edit, grep, bash, webfetch, GitHub…
+  tui/           Ink UI, rendering, themes, overlays, file explorer
+  sync/          self-hosted session sync server
+  data/          bundled models.dev snapshot
+test/            unit and CLI integration tests (mock SSE servers, no keys needed)
+scripts/         catalog updates, logo rendering, asset copying
+docs/            full reference
+```
+
+<br>
+
+## 🤝 Contributing
+
+Contributions are welcome. The short version:
+
+```bash
+npm install
+npm run dev          # run from source
+npm run typecheck
+npm test             # no API keys required
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a tool or a new provider dialect.
+
+<br>
+
+## 📚 Documentation
+
+The **[full reference](docs/REFERENCE.md)** covers every setting and flag: configuration, custom endpoints, session sync, multi-model agents, GitHub publishing, JSON event schema, troubleshooting and more.
+
+<br>
+
+## 📄 License
+
+MIT © 2026 Geetank. See [LICENSE](LICENSE).
+
+<div align="center">
+
+<br>
+
+**If SurfCode saves you time, a ⭐ on the repo means a lot.**
+
+</div>

package/dist/cli/auth.js

@@ -0,0 +1,315 @@
+import { credentialStatus, isKeylessProvider, mask, removeProviderKey, saveProviderKey } from '../core/auth.js';
+import { loadCatalog } from '../core/catalog.js';
+import { loadConfig } from '../core/config.js';
+import { SurfError } from '../core/errors.js';
+import { FREE_API_HINT, FREE_API_LABEL, hasFreeApi } from '../core/free.js';
+import { githubTokenStatus, githubViewer } from '../core/github.js';
+import { providerHasEndpoint } from '../core/provider.js';
+import { accent, credentialUsable, danger, muted, oneLine, PRIORITY_PROVIDERS, providerStatusLabel, readSecret, success, table, title, warning, write } from './util.js';
+const PRIORITY = new Set(PRIORITY_PROVIDERS);
+export async function authCommand(options) {
+    const config = await loadConfig();
+    const catalog = await loadCatalog(config);
+    const providerArg = options.provider && options.provider !== 'list' ? options.provider : undefined;
+    if (!providerArg) {
+        if (options.remove || options.key || options.env) {
+            throw new SurfError('A provider is required for this option.', {
+                hint: 'Example: surf auth anthropic --key sk-ant-…'
+            });
+        }
+        return await listAuth(config, options);
+    }
+    if (providerArg.toLowerCase() === 'github') {
+        return await githubAuthCommand(options);
+    }
+    const provider = catalog.providers.find((entry) => entry.id === providerArg ||
+        entry.name.toLowerCase() === providerArg.toLowerCase());
+    if (!provider) {
+        throw new SurfError(`Unknown provider "${providerArg}"`, {
+            hint: 'Run `surf providers --all` to browse provider ids.'
+        });
+    }
+    const statuses = await credentialStatus([provider], config);
+    const status = statuses[0];
+    if (options.env) {
+        if (provider.env.length === 0) {
+            write(`${warning(provider.name)} does not use environment keys.`);
+            if (provider.local)
+                write(muted('  Local providers are keyless; start the server and use /connect.'));
+            return 0;
+        }
+        write(`${title(provider.name)} ${muted('environment variables')}`);
+        for (const name of provider.env) {
+            const value = process.env[name]?.trim();
+            write(`  ${value ? success('●') : muted('○')} ${accent(name)}${value ? muted(' · set') : ''}`);
+        }
+        return 0;
+    }
+    if (options.remove) {
+        const removed = await removeProviderKey(provider.id);
+        if (removed) {
+            write(`${success('✓')} Removed the saved key for ${provider.name}.`);
+        }
+        else {
+            write(muted(`No saved key for ${provider.name}.`));
+        }
+        if (config.providers[provider.id]?.apiKey || config.customProviders[provider.id]?.apiKey) {
+            const location = config.providers[provider.id]?.apiKey
+                ? `providers.${provider.id}.apiKey`
+                : `customProviders.${provider.id}.apiKey`;
+            write(warning(`  A key is still set in ${location} inside config.json. Remove it there too.`));
+        }
+        return 0;
+    }
+    if (options.key?.trim()) {
+        return await persistKey(provider, options.key, config, Boolean(options.json));
+    }
+    if (isKeylessProvider(provider)) {
+        write(`${success('✓')} ${provider.name} is keyless${provider.local ? ' when its local server is running' : ''}.`);
+        write(muted('  No API key is needed. Use `surf` and /connect, or select a model with --provider.'));
+        return 0;
+    }
+    if (!process.stdin.isTTY) {
+        throw new SurfError(`No key supplied for ${provider.name}`, {
+            hint: `Pass --key, or set ${provider.env[0] ?? 'the provider API key'} in the environment.`
+        });
+    }
+    write(`${title(provider.name)} ${muted('· paste your API key')}`);
+    if (provider.env[0])
+        write(muted(`  ${provider.env[0]} works too.`));
+    const key = await readSecret(`  key › `);
+    if (!key)
+        throw new SurfError('The key was empty.');
+    return await persistKey(provider, key, config, Boolean(options.json));
+}
+async function githubAuthCommand(options) {
+    const status = await githubTokenStatus();
+    if (options.env) {
+        write(`${title('GitHub')} ${muted('environment variables')}`);
+        for (const name of ['GITHUB_TOKEN', 'GH_TOKEN']) {
+            const value = process.env[name]?.trim();
+            write(`  ${value ? success('●') : muted('○')} ${accent(name)}${value ? muted(' · set') : ''}`);
+        }
+        if (status.source === 'auth') {
+            write(muted('  A token is also saved in auth.json.'));
+        }
+        return 0;
+    }
+    if (options.remove) {
+        const removed = await removeProviderKey('github');
+        const remaining = await githubTokenStatus();
+        if (!removed && !remaining.configured) {
+            write(muted('No saved GitHub token.'));
+            return 0;
+        }
+        if (removed)
+            write(`${success('✓')} Removed the saved GitHub token.`);
+        if (remaining.configured) {
+            write(warning(`  ${remaining.envName ?? 'An environment token'} is still set and will keep working.`));
+        }
+        else {
+            write(muted('  GitHub tools will ask you to connect again.'));
+        }
+        return 0;
+    }
+    if (options.key?.trim()) {
+        return await persistGithubKey(options.key, Boolean(options.json));
+    }
+    if (!process.stdin.isTTY) {
+        throw new SurfError('No GitHub token supplied', {
+            hint: 'Pass --key, or set GITHUB_TOKEN / GH_TOKEN in the environment.'
+        });
+    }
+    write(`${title('GitHub')} ${muted('· paste a personal access token')}`);
+    write(muted('  Classic scope: repo. Fine-grained: Contents + Administration read/write.'));
+    write(muted('  The token is stored in auth.json with mode 600 and is never printed in full.'));
+    const key = await readSecret('  token › ');
+    if (!key)
+        throw new SurfError('The token was empty.');
+    return await persistGithubKey(key, Boolean(options.json));
+}
+async function persistGithubKey(raw, json) {
+    const key = raw.trim();
+    if (!key)
+        throw new SurfError('The token was empty.');
+    if (/\s/.test(key)) {
+        throw new SurfError('That token contains whitespace.', {
+            hint: 'Copy it again without line breaks or spaces.'
+        });
+    }
+    const viewer = await githubViewer(key);
+    await saveProviderKey('github', key);
+    if (json) {
+        write(JSON.stringify({
+            provider: 'github',
+            configured: true,
+            source: 'auth',
+            login: viewer.login,
+            masked: mask(key)
+        }, null, 2));
+        return 0;
+    }
+    write(`${success('✓')} Connected to GitHub as ${accent(viewer.login)} ${muted(`· ${mask(key)}`)}`);
+    write(muted('  Ask the agent: “create a private repo for this project and upload everything”.'));
+    write(muted('  The agent can create repos, upload code, and commit only when you ask.'));
+    return 0;
+}
+async function persistKey(provider, raw, config, json) {
+    const key = raw.trim();
+    if (!key)
+        throw new SurfError('The key was empty.');
+    if (/\s/.test(key)) {
+        throw new SurfError('That key contains whitespace.', {
+            hint: 'Copy it again without line breaks or spaces.'
+        });
+    }
+    await saveProviderKey(provider.id, key);
+    if (json) {
+        write(JSON.stringify({
+            provider: provider.id,
+            configured: true,
+            source: 'auth',
+            masked: mask(key)
+        }, null, 2));
+        return 0;
+    }
+    write(`${success('✓')} Saved a key for ${provider.name} ${muted(`· ${mask(key)}`)}`);
+    if (!providerHasEndpoint(provider, config)) {
+        const location = config.customProviders[provider.id]
+            ? `customProviders.${provider.id}.baseURL`
+            : `providers.${provider.id}.baseURL`;
+        write(warning(`  This provider still needs an endpoint. Add ${location} to the config.`));
+    }
+    const configured = (await credentialStatus([provider], config))[0];
+    if (configured?.configured === false) {
+        write(warning('  The key was saved but the provider is not ready yet.'));
+    }
+    write(muted('  Start SurfCode with `surf`, or pick a model with `surf models`.'));
+    return 0;
+}
+async function listAuth(config, options) {
+    const catalog = await loadCatalog(config);
+    const statuses = await credentialStatus(catalog.providers, config);
+    const github = await githubTokenStatus();
+    const byId = new Map(statuses.map((status) => [status.provider.id, status]));
+    const configured = statuses.filter((status) => status.configured);
+    const ready = statuses.filter((status) => credentialUsable(status, config));
+    const readyIds = new Set(ready.map((status) => status.provider.id));
+    let providers = catalog.providers.filter((provider) => {
+        if (options.all)
+            return true;
+        const status = byId.get(provider.id);
+        return (readyIds.has(provider.id) ||
+            Boolean(status?.configured && status.source !== 'keyless') ||
+            PRIORITY.has(provider.id) ||
+            provider.id === config.provider ||
+            provider.custom);
+    });
+    providers.sort((a, b) => {
+        const readyOrder = Number(readyIds.has(b.id)) - Number(readyIds.has(a.id));
+        if (readyOrder !== 0)
+            return readyOrder;
+        const priority = (PRIORITY.has(a.id) ? PRIORITY_PROVIDERS.indexOf(a.id) : PRIORITY.size) -
+            (PRIORITY.has(b.id) ? PRIORITY_PROVIDERS.indexOf(b.id) : PRIORITY.size);
+        if (priority !== 0)
+            return priority;
+        return a.name.localeCompare(b.name);
+    });
+    if (options.json) {
+        write(JSON.stringify({
+            configured: configured.length,
+            ready: ready.length,
+            total: catalog.providers.length,
+            github: {
+                configured: github.configured,
+                source: github.source ?? null,
+                envName: github.envName ?? null,
+                masked: github.masked ?? null
+            },
+            providers: providers.map((provider) => {
+                const status = byId.get(provider.id);
+                return {
+                    id: provider.id,
+                    name: provider.name,
+                    configured: Boolean(status?.configured),
+                    usable: status ? credentialUsable(status, config) : false,
+                    source: status?.source ?? null,
+                    env: provider.env,
+                    envName: status?.envName ?? null,
+                    local: Boolean(provider.local),
+                    custom: Boolean(provider.custom),
+                    freeApi: hasFreeApi(provider.id)
+                };
+            })
+        }, null, 2));
+        return 0;
+    }
+    write(`${title('Authentication')} ${muted(`· ${ready.length} ready · ${catalog.providers.length} providers`)}`);
+    if (ready.length === 0) {
+        write();
+        write(muted('No provider credentials found. Add one with `surf auth <provider>`.'));
+        write(muted('Environment variables are also supported; run `surf auth <provider> --env`.'));
+    }
+    write();
+    table(['Provider', 'ID', 'Status', 'Source', 'Environment'], providers.map((provider) => {
+        const status = byId.get(provider.id);
+        const ready = status ? credentialUsable(status, config) : false;
+        let label = providerStatusLabel(status, provider, config);
+        if (status?.configured && !ready) {
+            label = warning(providerHasEndpoint(provider, config) ? 'key saved · not ready' : 'key saved · no endpoint');
+        }
+        const source = status?.configured
+            ? status.source === 'auth'
+                ? 'auth.json'
+                : status.source === 'env'
+                    ? oneLine(status.envName ?? 'environment', 20)
+                    : (status.source ?? '—')
+            : '—';
+        return [
+            `${provider.name}${hasFreeApi(provider.id) ? ` ${success(FREE_API_LABEL)}` : ''}`,
+            provider.id,
+            label,
+            muted(source),
+            muted(oneLine(provider.env.join(', ') || '—', 34))
+        ];
+    }), { protectFirst: true });
+    if (!options.all) {
+        write();
+        write(muted('Showing configured providers and popular defaults. Use --all to list all.'));
+    }
+    write();
+    write(`${github.configured ? success('●') : muted('○')} ${title('GitHub')} ${muted(github.configured
+        ? `· connected via ${github.source === 'env' ? github.envName : 'auth.json'} · ${github.masked ?? ''}`
+        : '· not connected · /github login or surf auth github')}`);
+    if (providers.some((provider) => hasFreeApi(provider.id))) {
+        write(muted(`${FREE_API_LABEL} = ${FREE_API_HINT}; model availability varies.`));
+    }
+    if (ready.length > 0) {
+        write();
+        write(`${success('●')} ${muted(`Ready: ${ready.slice(0, 12).map((status) => status.provider.id).join(', ')}${ready.length > 12 ? '…' : ''}`)}`);
+    }
+    return 0;
+}
+export function authHelpText() {
+    return [
+        `${title('surf auth')} ${muted('[provider]')}`,
+        muted('  Save an API key in auth.json, or inspect environment variables.'),
+        '',
+        `${muted('examples')}`,
+        `  surf auth anthropic`,
+        `  surf auth openai --key sk-…`,
+        `  surf auth google --env`,
+        `  surf auth openrouter --remove`,
+        `  surf auth github`,
+        `  surf auth github --key ghp_…`,
+        '',
+        `${muted('GitHub uses a personal access token for repository creation and publishing.')}`,
+        `${muted('keys are stored with mode 600 and are never printed in full.')}`
+    ].join('\n');
+}
+export function missingKeyHint(provider) {
+    return provider.env.length > 0
+        ? `Run \`surf auth ${provider.id}\` or set ${danger(provider.env.join(' or '))}.`
+        : `Run \`surf auth ${provider.id}\`.`;
+}
+//# sourceMappingURL=auth.js.map