rovecode 0.4.0-beta.2 → 0.4.0

package/src/plugins/load.ts

@@ -0,0 +1,149 @@
+/** Plugins: activation. For every ACTIVE plugin, import its entry module (Bun runs TypeScript natively:
+ *  `await import()`, no build step — the .rovecode/hooks.ts idiom, the same trust class), validate the
+ *  default export, and resolve the declarative contributions (commands dir, skills dir, MCP servers).
+ *  The result is a set of already-typed things the runtime drops onto existing seams:
+ *    tools → ToolRegistry.register (the same policy path as built-ins: kind → action, deny-default)
+ *    hooks → HookRunner.add(set, source) (timeout-bounded and isolated by the runner, like hook files)
+ *    commandsDir / skillsDir → the commands and skills loaders' extra roots
+ *    mcp → appended to loadMcpConfig's servers
+ *  A module that fails, hangs or lies about its version costs ONE warning and that plugin's code
+ *  contributions — never a throw, never the other plugins. Disabled/untrusted/broken plugins are
+ *  returned with empty contributions so `plugin list` can still show them. */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { HOOK_NAMES, type HookSet } from "../core/hooks.ts";
+import type { Tool, ToolContext, ToolKind, ToolOutput } from "../core/types.ts";
+import { isRecord } from "../mcp/config.ts";
+import type { DiscoveredPlugin } from "./discover.ts";
+import { PLUGIN_API_VERSION } from "./manifest.ts";
+
+/** what the entry module receives when `tools` is a function */
+export interface PluginCtx { cwd: string; home: string; pluginDir: string }
+
+/** the entry module's default export */
+export interface PluginModule {
+  api: number;
+  tools?: Tool[] | ((ctx: PluginCtx) => Tool[] | Promise<Tool[]>);
+  hooks?: HookSet;
+}
+
+/** a discovered plugin plus what its entry module contributed (empty unless status is active) */
+export interface LoadedPlugin extends DiscoveredPlugin {
+  tools: Tool[];
+  hooks: HookSet | null;
+}
+
+export interface ActivateOptions { cwd: string; home: string; /** import + tools() budget per plugin (default: ROVECODE_PLUGIN_TIMEOUT_MS, else 5000) */ timeoutMs?: number }
+export const DEFAULT_PLUGIN_TIMEOUT_MS = 5000;
+/** ROVECODE_PLUGIN_TIMEOUT_MS: blank/invalid/< 1 → default (the hooks.ts hookTimeoutMs rule) */
+export function pluginTimeoutMs(env: Record<string, string | undefined> = process.env): number {
+  const n = Number(env.ROVECODE_PLUGIN_TIMEOUT_MS);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_PLUGIN_TIMEOUT_MS;
+}
+
+const KINDS: readonly ToolKind[] = ["read", "write", "execute", "spawn", "memory", "network", "custom"];
+const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** kind → policy action, the same table core/tools.ts actionFor uses. `tool.<name>` has no
+ *  declaration: a plugin's OWN name is its identity, not a capability. */
+const KIND_ACTION: Partial<Record<ToolKind, string>> = {
+  read: "file.read", write: "file.write", execute: "shell.exec", spawn: "spawn", memory: "memory.write", network: "net.fetch",
+};
+
+/** Permission declaration (manifest.permissions, sdk-blueprint.md §6.5): a plugin that declares
+ *  permissions gets each tool wrapped — a call whose kind-action the manifest did not declare is
+ *  refused BEFORE execute, with a message naming the plugin and the missing declaration. The user
+ *  reads the declaration at install time (plugin show / market info); this wrap makes the promise
+ *  true at run time. No declaration = legacy unrestricted (no wrap). */
+function wrapPermissions(tool: Tool, declared: string[] | undefined, tag: string): Tool {
+  if (declared === undefined) return tool;
+  const action = KIND_ACTION[tool.kind];
+  if (action === undefined) return tool; // custom `tool.<name>` — no capability to declare
+  if (declared.includes(action) || declared.includes("*")) return tool;
+  return {
+    ...tool,
+    execute: async (_args: unknown, _ctx: ToolContext): Promise<ToolOutput> => ({
+      ok: false,
+      output: `Permission denied: plugin '${tag}' did not declare '${action}' — add it to the manifest's "permissions" and re-install, or remove this tool`,
+    }),
+  };
+}
+const TIMED_OUT = Symbol("timed-out");
+
+async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> {
+  let t: ReturnType<typeof setTimeout> | undefined;
+  const timer = new Promise<typeof TIMED_OUT>((r) => { t = setTimeout(() => r(TIMED_OUT), ms); });
+  try { return await Promise.race([p, timer]); } finally { if (t !== undefined) clearTimeout(t); }
+}
+const errText = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+export async function activatePlugins(found: readonly DiscoveredPlugin[], opts: ActivateOptions): Promise<{ plugins: LoadedPlugin[]; warnings: string[] }> {
+  const warnings: string[] = [];
+  const plugins: LoadedPlugin[] = [];
+  for (const p of found) plugins.push(await activateOne(p, opts, warnings));
+  return { plugins, warnings };
+}
+
+async function activateOne(p: DiscoveredPlugin, opts: ActivateOptions, warnings: string[]): Promise<LoadedPlugin> {
+  const out: LoadedPlugin = { ...p, tools: [], hooks: null };
+  if (p.status !== "active" || p.manifest === null) return out; // untrusted / disabled / broken: nothing of theirs runs
+  const m = p.manifest, tag = `plugin ${p.name}`;
+  if (!m.entry) return out;
+  const entry = join(p.dir, m.entry);
+  if (!existsSync(entry)) { warnings.push(`${tag}: entry ${m.entry} does not exist — no tools or hooks loaded`); return out; }
+  const ms = opts.timeoutMs ?? pluginTimeoutMs();
+  let mod: unknown;
+  try { mod = await withTimeout(import(pathToFileURL(entry).href), ms); }
+  catch (e) { warnings.push(`${tag}: ${m.entry} failed to load — ${errText(e)}`); return out; }
+  if (mod === TIMED_OUT) { warnings.push(`${tag}: ${m.entry} load timed out after ${ms}ms (top-level await?) — skipped`); return out; }
+  const dflt: unknown = isRecord(mod) ? mod["default"] : undefined;
+  if (!isRecord(dflt)) { warnings.push(`${tag}: ${m.entry} must \`export default { api: ${PLUGIN_API_VERSION}, tools?, hooks? }\` — skipped`); return out; }
+  if (dflt["api"] !== PLUGIN_API_VERSION) { warnings.push(`${tag}: ${m.entry} declares api ${String(dflt["api"])}; this rovecode speaks ${PLUGIN_API_VERSION} — skipped`); return out; }
+  for (const key of Object.keys(dflt)) if (!["api", "tools", "hooks"].includes(key)) warnings.push(`${tag}: ${m.entry} exports unknown member "${key}" — ignored`);
+  // tools: an array, or a factory that gets the plugin's ctx (its own folder for data files, the cwd, the home)
+  if (dflt["tools"] !== undefined) {
+    let list: unknown;
+    try {
+      const raw = dflt["tools"];
+      list = typeof raw === "function" ? await withTimeout(Promise.resolve((raw as (c: PluginCtx) => unknown)({ cwd: opts.cwd, home: opts.home, pluginDir: p.dir })), ms) : raw;
+    } catch (e) { warnings.push(`${tag}: tools() threw — ${errText(e)}`); list = []; }
+    if (list === TIMED_OUT) { warnings.push(`${tag}: tools() timed out after ${ms}ms — no tools loaded`); list = []; }
+    if (!Array.isArray(list)) { warnings.push(`${tag}: "tools" must be an array (or a function returning one) — ignored`); list = []; }
+    const seen = new Set<string>();
+    for (const t of list as unknown[]) {
+      const ok = validateTool(t, tag, warnings);
+      if (!ok) continue;
+      if (seen.has(ok.schema.name)) { warnings.push(`${tag}: tool "${ok.schema.name}" declared twice — first kept`); continue; }
+      seen.add(ok.schema.name); out.tools.push(wrapPermissions(ok, m.permissions, tag));
+    }
+  }
+  // hooks: the HookSet shape hooks.ts validates for files — unknown names and non-functions dropped, the rest kept
+  if (dflt["hooks"] !== undefined) {
+    if (!isRecord(dflt["hooks"])) warnings.push(`${tag}: "hooks" must be an object of hook functions — ignored`);
+    else {
+      const set: Record<string, unknown> = {};
+      for (const [name, fn] of Object.entries(dflt["hooks"])) {
+        if (!(HOOK_NAMES as readonly string[]).includes(name)) { warnings.push(`${tag}: unknown hook "${name}" ignored (known: ${HOOK_NAMES.join(", ")})`); continue; }
+        if (typeof fn !== "function") { warnings.push(`${tag}: hook "${name}" is not a function — ignored`); continue; }
+        set[name] = fn;
+      }
+      if (Object.keys(set).length) out.hooks = set as HookSet;
+    }
+  }
+  return out;
+}
+
+/** a Tool as core/types.ts defines it; anything else is named and dropped */
+function validateTool(t: unknown, tag: string, warnings: string[]): Tool | null {
+  if (!isRecord(t) || !isRecord(t["schema"])) { warnings.push(`${tag}: a tool without a schema was dropped`); return null; }
+  const s = t["schema"];
+  const name = s["name"];
+  if (typeof name !== "string" || !TOOL_NAME_RE.test(name)) { warnings.push(`${tag}: tool name ${JSON.stringify(name)} must match ${TOOL_NAME_RE} — dropped`); return null; }
+  if (typeof s["description"] !== "string" || !s["description"].trim()) { warnings.push(`${tag}: tool "${name}" needs a description — dropped`); return null; }
+  if (!isRecord(s["args"])) { warnings.push(`${tag}: tool "${name}" needs a JSON-Schema "args" object — dropped`); return null; }
+  if (!KINDS.includes(t["kind"] as ToolKind)) { warnings.push(`${tag}: tool "${name}" kind ${JSON.stringify(t["kind"])} is not one of ${KINDS.join("|")} — dropped (the kind is its permission class)`); return null; }
+  if (typeof t["execute"] !== "function") { warnings.push(`${tag}: tool "${name}" has no execute() — dropped`); return null; }
+  return t as unknown as Tool;
+}

package/src/plugins/manifest.ts

@@ -0,0 +1,106 @@
+/** Plugins: the manifest. A plugin is a FOLDER with a `plugin.json` that names what the folder
+ *  contributes — an in-process entry module (tools + hooks), a directory of custom commands, a
+ *  directory of skills, MCP servers. Nothing here is a new extension API: every contribution lands on
+ *  a seam rovecode already has (core/hooks.ts HookSet, core/tools.ts ToolRegistry, tui/commands.ts,
+ *  skills/index.ts, mcp/config.ts). The plugin is the package, not the surface (ADR-013: no 1.8k-line
+ *  extension API — a small typed set, versioned; the manifest is versioned the same way hooks are).
+ *
+ *  Pure: text in, manifest or null out, every rejection a warning that names the file and the field.
+ *  Paths in the manifest are RELATIVE and may not climb out of the plugin folder — a manifest is data
+ *  from a checkout, and "../../.rovecode/hooks.ts" is not a plugin's to name. */
+
+import { isRecord } from "../mcp/config.ts";
+
+export const PLUGIN_API_VERSION = 1;
+export const MANIFEST_FILE = "plugin.json";
+/** `rovecode plugin list` and the palette show this; a paragraph is not a description */
+export const MAX_DESCRIPTION_CHARS = 200;
+
+export interface PluginManifest {
+  /** identity: folder-safe, lowercase, unique per scope — `conventional-commits`, `safety-net` */
+  name: string;
+  version: string;
+  description: string;
+  /** manifest/API version gate; this rovecode speaks PLUGIN_API_VERSION */
+  api: number;
+  /** relative path of the in-process module (`export default { api: 1, tools, hooks }`); .ts or .js */
+  entry?: string;
+  /** relative directory of `*.md` custom commands (tui/commands.ts format) */
+  commands?: string;
+  /** relative directory walked for SKILL.md files (skills/index.ts format) */
+  skills?: string;
+  /** MCP servers keyed by name, `.rovecode/mcp.json` entry shape */
+  mcp?: Record<string, unknown>;
+  /** Permission declaration (sdk-blueprint.md §6.5): the policy actions this plugin's tools
+   *  may take — file.read, file.write, shell.exec, spawn, memory.write, net.fetch. A plugin
+   *  tool whose kind maps outside the declaration is refused at activation-time wrapping:
+   *  the user reads this list BEFORE installing (plugin show / market info) and a quiet
+   *  capability grab becomes a loud load-time refusal. Absent = legacy unrestricted. */
+  permissions?: string[];
+}
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ENTRY_RE = /\.(?:[cm]?[jt]s)$/i;
+
+/** a relative path that stays inside the plugin: no absolute, no drive, no `..` segment */
+export function insidePlugin(p: string): boolean {
+  if (p.length === 0 || p.startsWith("/") || p.startsWith("\\") || /^[A-Za-z]:/.test(p)) return false;
+  return !p.split(/[\\/]/).some((seg) => seg === "..");
+}
+
+/** `plugin.json` text → manifest, or null with the reasons appended to `warnings`. A wrong or missing
+ *  `api` is a hard skip (the version gate); everything else that is off is dropped field by field so
+ *  a typo in `skills` does not lose the plugin's tools. */
+export function parseManifest(text: string, file: string, warnings: string[]): PluginManifest | null {
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch (e) { warnings.push(`${file}: not valid JSON — ${(e as Error).message}`); return null; }
+  if (!isRecord(raw)) { warnings.push(`${file}: must be an object`); return null; }
+  const api = raw["api"];
+  if (api !== PLUGIN_API_VERSION) {
+    const shown = api === undefined ? "missing" : typeof api === "string" ? JSON.stringify(api) : String(api);
+    warnings.push(`${file}: plugin API version ${shown} is not supported (this rovecode speaks ${PLUGIN_API_VERSION}) — skipped`);
+    return null;
+  }
+  const name = raw["name"];
+  if (typeof name !== "string" || !NAME_RE.test(name)) { warnings.push(`${file}: "name" must match ${NAME_RE} — skipped`); return null; }
+  const version = typeof raw["version"] === "string" && raw["version"].trim() ? raw["version"].trim().slice(0, 40) : null;
+  if (version === null) { warnings.push(`${file}: "version" must be a non-empty string — skipped`); return null; }
+  const m: PluginManifest = { name, version, description: "", api: PLUGIN_API_VERSION };
+  if (raw["description"] !== undefined) {
+    if (typeof raw["description"] === "string") m.description = raw["description"].replace(/\s+/g, " ").trim().slice(0, MAX_DESCRIPTION_CHARS);
+    else warnings.push(`${file}: "description" is not a string — ignored`);
+  }
+  for (const key of ["entry", "commands", "skills"] as const) {
+    const v = raw[key];
+    if (v === undefined) continue;
+    if (typeof v !== "string" || !insidePlugin(v)) { warnings.push(`${file}: "${key}" must be a relative path inside the plugin — ignored`); continue; }
+    if (key === "entry" && !ENTRY_RE.test(v)) { warnings.push(`${file}: "entry" must be a .ts or .js module — ignored`); continue; }
+    m[key] = v.replace(/\\/g, "/");
+  }
+  if (raw["mcp"] !== undefined) {
+    if (isRecord(raw["mcp"])) m.mcp = raw["mcp"];
+    else warnings.push(`${file}: "mcp" must be an object of servers keyed by name — ignored`);
+  }
+  if (raw["permissions"] !== undefined) {
+    const p = raw["permissions"];
+    if (Array.isArray(p) && p.every((x) => typeof x === "string" && /^[a-z][a-z0-9.*-]{0,63}$/.test(x))) {
+      m.permissions = p.slice(0, 16);
+      if (p.length > 16) warnings.push(`${file}: "permissions" capped at 16 entries`);
+    } else warnings.push(`${file}: "permissions" must be an array of action names (e.g. "shell.exec") — ignored`);
+  }
+  for (const key of Object.keys(raw)) {
+    if (!["name", "version", "description", "api", "entry", "commands", "skills", "mcp", "permissions"].includes(key)) warnings.push(`${file}: unknown field "${key}" ignored`);
+  }
+  return m;
+}
+
+/** what a manifest says it brings, for `plugin list` / `plugin show` / the trust prompt */
+export function contributions(m: PluginManifest): string[] {
+  const out: string[] = [];
+  if (m.entry) out.push(`code: ${m.entry}`);
+  if (m.commands) out.push(`commands: ${m.commands}/`);
+  if (m.skills) out.push(`skills: ${m.skills}/`);
+  if (m.mcp) out.push(`mcp: ${Object.keys(m.mcp).join(", ") || "(none)"}`);
+  if (m.permissions) out.push(`permissions: ${m.permissions.length > 0 ? m.permissions.join(", ") : "(none — read-only)"}`);
+  return out;
+}

package/src/plugins/state.ts

@@ -0,0 +1,83 @@
+/** Plugins: what the human decided about them — `~/.rovecode/plugins.json`. Two facts only:
+ *  which plugins are switched off, and which PROJECT plugins this machine trusts, by folder and by a
+ *  digest of the folder's contents.
+ *
+ *  Why a digest and why in the USER home: a project plugin lives in a checkout, and a checkout is
+ *  data from the network. Recording "trusted: true" inside `<cwd>/.rovecode/settings.json` would let the
+ *  repository trust itself; recording it here, keyed by the plugin's absolute folder and the hash of
+ *  every file in it, means the human said yes to THIS code on THIS machine, and a `git pull` that
+ *  changes the plugin asks again. User-scope plugins need no record: `rovecode plugin add` copying a
+ *  folder into `~/.rovecode/plugins` IS the human's yes.
+ *
+ *  A missing, unreadable or malformed file reads as "nothing decided" — never an error. */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+export interface PluginState {
+  /** plugin names switched off in every scope */
+  disabled: string[];
+  /** absolute project-plugin folder → digest the human approved */
+  trusted: Record<string, string>;
+}
+
+export const STATE_FILE = "plugins.json";
+export const statePath = (home: string): string => join(home, STATE_FILE);
+
+const SKIP_DIRS = new Set(["node_modules", ".git"]);
+
+export function loadState(home: string): PluginState {
+  const out: PluginState = { disabled: [], trusted: {} };
+  let raw: unknown;
+  try { raw = JSON.parse(readFileSync(statePath(home), "utf8")); } catch { return out; }
+  if (typeof raw !== "object" || raw === null) return out;
+  const r = raw as Record<string, unknown>;
+  if (Array.isArray(r["disabled"])) out.disabled = r["disabled"].filter((v): v is string => typeof v === "string");
+  if (typeof r["trusted"] === "object" && r["trusted"] !== null && !Array.isArray(r["trusted"])) {
+    for (const [k, v] of Object.entries(r["trusted"] as Record<string, unknown>)) if (typeof v === "string") out.trusted[k] = v;
+  }
+  return out;
+}
+
+export function saveState(home: string, state: PluginState): string {
+  const path = statePath(home);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ disabled: [...state.disabled].sort(), trusted: state.trusted }, null, 2) + "\n");
+  return path;
+}
+
+/** every regular file under the plugin folder (node_modules/.git skipped), sorted, relative posix paths */
+export function pluginFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string): void => {
+    let entries: import("node:fs").Dirent[];
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile()) out.push(relative(dir, p).replace(/\\/g, "/"));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/** sha256 over `<relative path>\0<bytes>\0` for every file — the same folder gives the same digest on
+ *  every machine, and one changed byte in one file changes it */
+export function pluginDigest(dir: string): string {
+  const h = createHash("sha256");
+  for (const rel of pluginFiles(dir)) {
+    h.update(rel); h.update("\0");
+    try { h.update(readFileSync(join(dir, rel))); } catch { /* vanished mid-walk: the digest still moves */ }
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+export const trustKey = (dir: string): string => resolve(dir).replace(/\\/g, "/");
+export function isTrusted(state: PluginState, dir: string, digest: string): boolean { return state.trusted[trustKey(dir)] === digest; }
+
+/** a folder exists and is a directory */
+export function isDir(p: string): boolean { try { return statSync(p).isDirectory(); } catch { return false; } }

package/src/providers/auth.ts

@@ -0,0 +1,293 @@
+/** Provider credential store (port #37): backing for `rovecode auth set/list/remove`.
+ *
+ *  Ported from opencode packages/opencode/src/auth/index.ts @ ebece6e (MIT):
+ *  - one JSON object keyed by provider id, entries discriminated by `type` (index.ts:14-36)
+ *  - the "api" variant carries the secret in `key` (index.ts:23-27); the provider loader
+ *    consumes it as the apiKey (provider.ts:1596-1601)
+ *  - file written with mode 0o600 (index.ts:79,88)
+ *  - a missing/corrupt file reads as {} and malformed entries are dropped per-entry, never
+ *    fatal (index.ts:65-66, Record.filterMap over the schema decode)
+ *  Deviations: the file lives at ~/.rovecode/credentials.json (bar) instead of opencode's
+ *  <data>/auth.json; entries carry an rovecode-only optional `keyName` (which env var the
+ *  secret stands in for); only the "api" variant is implemented — entries with other
+ *  `type` values (a future oauth port) round-trip through save/remove unharmed but are
+ *  not listed or resolved.
+ *
+ *  Also home to readSecret (the `rovecode auth set` prompt) so its TTY path is unit-testable
+ *  in-process — main.ts cannot be imported by tests (it dispatches on load).
+ *
+ *  SECRETS ARE NEVER LOGGED from this module: the only terminal output is readSecret's
+ *  prompt text plus cursor-control sequences, error messages never embed the credential
+ *  value, and the store itself prints nothing. Rendering (redacted) is the caller's job
+ *  via listProviders()/redactSecret().
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, cpSync, existsSync, rmSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+
+/** The provider index, loaded ONLY when something asks for a key name.
+ *
+ *  Two things were wrong here and they compounded. The import was at the top of the module, and what it
+ *  imported was the full models.dev snapshot: 63 MB resident, for one call site (`keyNameFor`). Meanwhile
+ *  `rovecodeHome`, three lines of path arithmetic in this same file, is imported by hooks.ts, settings.ts,
+ *  runtime.ts, the plugin loader and half the TUI — so all of them paid 63 MB to learn where `~/.rovecode`
+ *  is, and the TUI paid it at startup before drawing a frame.
+ *
+ *  Now it is deferred, and it reads the trimmed index (src/providers/models-index.json, the same file the
+ *  catalog reads) rather than the upstream snapshot. Only `env[0]` is ever used from it.
+ *
+ *  `require` rather than `await import` because `keyNameFor` is synchronous and called from synchronous
+ *  code; making it async would push the change through a dozen call sites to save nothing extra. */
+let snapshotCache: Record<string, { env?: string[] } | undefined> | null = null;
+function snapshotProvidersLazy(): Record<string, { env?: string[] } | undefined> {
+  if (snapshotCache === null) {
+    const req = createRequire(import.meta.url);
+    const m = req("./models-index.json") as { providers?: Record<string, { env?: string[] }> };
+    snapshotCache = m.providers ?? {};
+  }
+  return snapshotCache;
+}
+
+export interface StoredCredential {
+  type: "api";
+  /** the secret itself (upstream field name — auth/index.ts:24) */
+  key: string;
+  /** rovecode extension: env var name this secret stands in for (e.g. ANTHROPIC_API_KEY) */
+  keyName?: string;
+}
+
+/** User-scope rovecode dir: ROVECODE_HOME overrides ~/.rovecode wholesale (tests point it at a temp
+ *  dir). homedir() already respects HOME on POSIX and USERPROFILE on Windows. Mirrors the
+ *  skills store's user-scope default (skills/index.ts: join(homedir(), ".rovecode", ...)). */
+/** what node's homedir() promises, spelled out so every runtime agrees on every host: HOME on POSIX,
+ *  USERPROFILE on Windows, the OS account's directory only when neither is set (tests point HOME at a
+ *  scratch dir and expect the home to follow) */
+const userHome = (): string => (process.platform === "win32" ? process.env.USERPROFILE : process.env.HOME) || homedir();
+
+export function rovecodeHome(): string {
+  const explicit = process.env.ROVECODE_HOME;
+  const home = explicit ?? join(userHome(), ".rovecode");
+  migrateLegacyHome(home, { explicit: explicit !== undefined });
+  return home;
+}
+
+/** The config directory used to be `~/.cumulus` (the project was called nimbus). A rename must not
+ *  cost anyone their stored API keys and providers, so the first call that resolves the new home
+ *  COPIES the old one into it — copy, not move: the old directory is left exactly as it was, so
+ *  downgrading to an older build keeps working and nothing is destroyed if this goes wrong.
+ *
+ *  Runs once per process, only when the new home does not exist yet and the old one does, and ONLY for
+ *  the default home. An explicit ROVECODE_HOME used to be migrated the same way "which is what makes it
+ *  testable", and that was a real hazard rather than a convenience: pointing ROVECODE_HOME at a fresh
+ *  path — the ordinary way to get an isolated home for a test, a script or a clean-room check — silently
+ *  filled it with a copy of the old credentials. It billed two real API calls during this repository's
+ *  own release verification (2026-09-06) before anyone noticed the scratch home was not scratch. Tests
+ *  that need to exercise the migration pass `legacyDir`; nothing else copies a user's keys into a path
+ *  they chose for isolation.
+ *
+ *  Any failure is swallowed: a migration that cannot run must not stop the agent from starting — the
+ *  user simply sees "no provider configured" and runs `rovecode connect`. */
+let migrated = false;
+export function migrateLegacyHome(home: string, opts: { explicit?: boolean; legacyDir?: string; note?: (line: string) => void } = {}): void {
+  if (migrated && opts.legacyDir === undefined) return;
+  if (opts.legacyDir === undefined) migrated = true;
+  try {
+    if (existsSync(home)) return;                        // already living in the new place
+    const legacy = opts.legacyDir ?? join(userHome(), ".cumulus");
+    // an explicit ROVECODE_HOME is a request for THIS directory, not for a copy of another one. The
+    // injected legacyDir does not override it: a test that wants the explicit case must SEE the refusal.
+    if (opts.explicit === true) return;
+    if (home === legacy || !existsSync(legacy)) return;
+    cpSync(legacy, home, { recursive: true });
+    // and it says so: a copy of someone's credentials appearing in a new directory is not a silent event
+    (opts.note ?? ((l: string) => console.error(l)))(`migrated ${legacy} → ${home} (the config directory was renamed; the old one is untouched)`);
+    // the credentials file carries the 0600 the old one had only on POSIX; re-assert it here
+    const creds = join(home, "credentials.json");
+    if (existsSync(creds) && process.platform !== "win32") chmodSync(creds, 0o600);
+  } catch { /* best effort: a failed migration is a fresh config, never a crash */ }
+}
+
+export function credentialsPath(): string {
+  return join(rovecodeHome(), "credentials.json");
+}
+
+/** Raw file contents: every entry as stored, including unknown `type`s. Missing file,
+ *  unreadable file, or non-object JSON -> {} (upstream orElseSucceed idiom). */
+function readRaw(): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  return parsed as Record<string, unknown>;
+}
+
+function isApiCredential(value: unknown): value is StoredCredential {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as { type?: unknown; key?: unknown; keyName?: unknown };
+  // whitespace-only counts as empty: a hand-edited `"key": " "` must not shadow a valid env key
+  if (v.type !== "api" || typeof v.key !== "string" || v.key.trim().length === 0) return false;
+  return v.keyName === undefined || typeof v.keyName === "string";
+}
+
+/** Valid "api" credentials only, keyed by provider id (malformed entries dropped). */
+export function loadCredentials(): Record<string, StoredCredential> {
+  const out: Record<string, StoredCredential> = {};
+  for (const [id, value] of Object.entries(readRaw())) {
+    if (isApiCredential(value)) out[id] = value;
+  }
+  return out;
+}
+
+/** Write the store with restrictive permissions.
+ *
+ *  Windows honesty note: fs mode bits on win32 map only onto the FILE_ATTRIBUTE_READONLY
+ *  flag — 0o600 does NOT create owner-only protection there. Real isolation on Windows
+ *  comes from the NTFS ACL on %USERPROFILE% (inherited by ~/.rovecode), which by default
+ *  denies other non-admin users. So this is best-effort hardening on POSIX (where the
+ *  0o600/0o700 bits are enforced) and effectively a no-op on Windows beyond the profile
+ *  ACL it inherits — we do not claim otherwise. */
+function writeStore(data: Record<string, unknown>): void {
+  const path = credentialsPath();
+  mkdirSync(rovecodeHome(), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600); // `mode` above only applies on create; re-assert on rewrites
+  } catch {
+    // best-effort (see Windows note) — a failed chmod must not lose the write
+  }
+}
+
+/** Store/replace the credential for a provider. `secret` is never echoed or thrown. */
+export function saveCredential(provider: string, secret: string, keyName?: string): void {
+  const id = provider.trim();
+  if (id.length === 0) throw new Error("provider id must not be empty");
+  if (secret.trim().length === 0) throw new Error(`refusing to store an empty secret for ${id}`);
+  const data = readRaw();
+  const entry: StoredCredential = { type: "api", key: secret, keyName: keyName ?? keyNameFor(id) };
+  data[id] = entry;
+  writeStore(data);
+}
+
+/** Remove a provider's entry. Returns false (and leaves the file alone) when absent.
+ *  Removing the last entry deletes the file rather than leaving an empty {} around. */
+export function removeCredential(provider: string): boolean {
+  const data = readRaw();
+  if (!(provider in data)) return false;
+  delete data[provider];
+  if (Object.keys(data).length === 0) {
+    try {
+      rmSync(credentialsPath());
+    } catch {
+      writeStore(data);
+    }
+    return true;
+  }
+  writeStore(data);
+  return true;
+}
+
+/** First 4 chars + "…" (bar wording). Secrets of 8 chars or fewer collapse to "…" alone —
+ *  half of a short key is most of the key, so nothing of it is shown. */
+export function redactSecret(secret: string): string {
+  return secret.length > 8 ? secret.slice(0, 4) + "…" : "…";
+}
+
+/** Redacted listing for `rovecode auth list`: provider + key NAME + redacted prefix.
+ *  The full secret value never appears in the returned records. */
+export function listProviders(): { provider: string; keyName: string; redacted: string }[] {
+  return Object.entries(loadCredentials())
+    .map(([provider, cred]) => ({
+      provider,
+      keyName: cred.keyName ?? keyNameFor(provider),
+      redacted: redactSecret(cred.key),
+    }))
+    .sort((a, b) => a.provider.localeCompare(b.provider));
+}
+
+/** rovecode provider id -> models.dev provider key, mirroring catalog.ts PROVIDER_MAP for the
+ *  non-identity ids (together -> "togetherai", fireworks -> "fireworks-ai") plus an
+ *  auth-only alias: moonshot -> "moonshotai" (models.dev has no bare "moonshot" key — the
+ *  catalog reaches it via VENDOR_PREFIX_MAP on model ids instead, which auth cannot use).
+ *  Identity ids (anthropic/openai/deepseek/openrouter/...) need no entry: keyNameFor tries
+ *  the id itself against the snapshot first. */
+const AUTH_PROVIDER_MAP: Record<string, string> = {
+  together: "togetherai",
+  fireworks: "fireworks-ai",
+  moonshot: "moonshotai",
+};
+
+/** Which env var / key name a provider expects. models.dev drives this (snapshot
+ *  Provider.env, e.g. anthropic -> ANTHROPIC_API_KEY — same source opencode's provider
+ *  loader reads at provider.ts:1583 @ ebece6e); providers absent from models.dev (kaesra,
+ *  ollama, moondream, vllm) fall back to <ID>_API_KEY, which matches every envKey in
+ *  stream.ts builtinProviders by construction. */
+export function keyNameFor(providerId: string): string {
+  const key = AUTH_PROVIDER_MAP[providerId] ?? providerId;
+  const env = snapshotProvidersLazy()[key]?.env;
+  if (env !== undefined && env.length > 0 && env[0]) return env[0];
+  return providerId.toUpperCase().replace(/[^A-Z0-9]+/g, "_") + "_API_KEY";
+}
+
+// ---------- secret prompt (`rovecode auth set`) ----------
+
+type SecretInput = NodeJS.ReadableStream & { isTTY?: boolean; isRaw?: boolean };
+type SecretOutput = NodeJS.WritableStream & { columns?: number };
+/** Streams readSecret talks to — injectable so tests can drive a fake TTY in-process. */
+export interface SecretPromptIO { input?: SecretInput; output?: SecretOutput }
+
+/** Cursor-control sequence for the cooked-mode fallback: after Enter the terminal has echoed
+ *  prompt+line and moved to the next row, so erase ONE row per wrapped row the echo occupied
+ *  (cursor-up + erase-line each), then "\r". A single row is not enough — a 33-col prompt plus
+ *  a 108-char Anthropic key wraps on any terminal narrower than 141 columns. Pure: pinned by
+ *  the headless-xterm test at 80 and 120 columns. Unknown/zero width assumes 80. */
+export function echoScrubSequence(promptLen: number, lineLen: number, columns: number): string {
+  const cols = columns > 0 ? Math.floor(columns) : 80;
+  const rows = Math.max(1, Math.ceil((promptLen + lineLen) / cols));
+  return "\x1b[1A\x1b[2K".repeat(rows) + "\r";
+}
+
+/** Read one secret line for `rovecode auth set`. What is guaranteed:
+ *  - TTY stdin: the prompt goes to stderr and readline runs in terminal mode, which calls
+ *    setRawMode(true): the terminal driver's echo is OFF and readline's own echo goes to a
+ *    sink, so the keystrokes are never written to the terminal at all. Verified on a real
+ *    Windows console under Bun 1.3.14 — the console input mode drops ENABLE_ECHO_INPUT and
+ *    ENABLE_LINE_INPUT, the screen buffer stays clean, and the mode is restored on close.
+ *  - Fallback, only if raw mode did not take (no/failing setRawMode, input.isRaw stays false):
+ *    the driver echoed, so after Enter every row the prompt+echo wrapped onto is erased
+ *    (echoScrubSequence). A terminal that ignores VT cursor sequences keeps that echo.
+ *  - Piped stdin (scripts, tests): one line, no prompt, nothing written to any stream.
+ *  The value is returned trimmed and is never logged or embedded in an error. */
+export function readSecret(promptText: string, io: SecretPromptIO = {}): Promise<string> {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stderr;
+  const tty = input.isTTY === true;
+  if (tty) output.write(promptText);
+  const rl = tty
+    ? createInterface({ input, output: new Writable({ write: (_c, _e, cb) => cb() }), terminal: true })
+    : createInterface({ input });
+  const raw = tty && input.isRaw === true;
+  return new Promise((resolve) => {
+    let settled = false; // rl.close() emits "close" SYNCHRONOUSLY — guard the race
+    rl.once("line", (line) => {
+      if (settled) return;
+      settled = true;
+      // raw: nothing was echoed, just end the prompt line; not raw: erase the echoed rows
+      if (tty) output.write(raw ? "\n" : echoScrubSequence(promptText.length, line.length, output.columns ?? 80));
+      rl.close();
+      resolve(line.trim());
+    });
+    rl.once("close", () => { // EOF / Ctrl+C / Ctrl+D without a line
+      if (settled) return;
+      settled = true;
+      if (tty) output.write("\n");
+      resolve("");
+    });
+  });
+}