agent-trellis 0.1.0 → 0.3.0

package/dist/lib/mcpMigrateRead.js

@@ -0,0 +1,188 @@
+/**
+ * Reads an agent's own real, already-configured MCP servers and converts
+ * each into canonical's `McpServerDef` shape — `trellis migrate --only
+ * mcp`'s read path (trellis-migrate-mcp-servers). Deliberately separate
+ * from each probe's own `AgentSnapshotMcpServer` (src/probes/*.ts) and its
+ * thin `{name, transport, probe?}` shape used by `doctor` — that shape
+ * discards exactly the fields this module needs, and extending it would
+ * risk `doctor`'s existing, extensively-tested behavior for no reason
+ * (design.md D1). pi has no static MCP config to read at all — no reader
+ * is defined for it; `migrate.ts` skips pi for the `mcp` category
+ * entirely, the same fact already established for skills/instructions.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile } from "./probeCommon.js";
+import { readServerEnvTable } from "./tomlSection.js";
+const EMPTY_RESULT = { entries: [], unsupported: [] };
+/**
+ * Trellis's own `env` (name-only reference) vs. `staticEnv` (literal
+ * value) split lives in one JSON object on disk (`jsonMcp.ts`'s
+ * `renderJsonServerEntry`) — a value is a "name" entry only when it's
+ * exactly `${KEY}` referencing its OWN key, matching exactly what that
+ * renderer ever produces; anything else (a literal value, or a `${...}`
+ * referencing a *different* name) is treated as a literal `staticEnv`
+ * value instead of guessed at.
+ */
+const SELF_VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+function splitJsonEnvMap(env) {
+    if (!env)
+        return {};
+    const names = [];
+    const literal = {};
+    for (const [key, value] of Object.entries(env)) {
+        const match = SELF_VAR_REF_RE.exec(value);
+        if (match && match[1] === key) {
+            names.push(key);
+        }
+        else {
+            literal[key] = value;
+        }
+    }
+    const result = {};
+    if (names.length > 0)
+        result.env = names;
+    if (Object.keys(literal).length > 0)
+        result.staticEnv = literal;
+    return result;
+}
+function fromRichJsonServerDef(raw) {
+    if (raw.url) {
+        const transport = raw.type === "sse" ? "sse" : "http";
+        const def = { transport, url: raw.url };
+        if (raw.headers && Object.keys(raw.headers).length > 0)
+            def.headers = raw.headers;
+        return def;
+    }
+    if (!raw.command)
+        return undefined;
+    const def = { transport: "stdio", command: raw.command };
+    if (raw.args && raw.args.length > 0)
+        def.args = raw.args;
+    Object.assign(def, splitJsonEnvMap(raw.env));
+    return def;
+}
+function readRichJsonMcpDefs(configPath) {
+    const parsed = readJsonFile(configPath);
+    const entries = [];
+    const unsupported = [];
+    for (const [name, raw] of Object.entries(parsed?.mcpServers ?? {})) {
+        const def = fromRichJsonServerDef(raw);
+        if (def) {
+            entries.push({ name, def });
+        }
+        else {
+            unsupported.push({ name, reason: "stdio entry has no command — malformed, skipped" });
+        }
+    }
+    return { entries, unsupported };
+}
+export function readClaudeCodeMcpDefs(homeDir) {
+    return readRichJsonMcpDefs(join(homeDir, ".claude.json"));
+}
+export function readKiroMcpDefs(homeDir) {
+    return readRichJsonMcpDefs(join(homeDir, ".kiro", "settings", "mcp.json"));
+}
+/**
+ * Pure conversion half — separated from the subprocess/file-read effects
+ * below so the stdio/non-stdio/malformed decision logic is unit-testable
+ * without a real `codex` binary on PATH (this codebase has no fake-codex
+ * fixture anywhere; codex's subprocess dependency is otherwise entirely
+ * untested at the unit level).
+ */
+export function buildCodexMcpReadResult(mcpEntries, tomlContent) {
+    const entries = [];
+    const unsupported = [];
+    for (const entry of mcpEntries) {
+        if (entry.transport.type !== "stdio") {
+            const remote = buildCodexRemoteDef(entry);
+            if (remote.def) {
+                entries.push({ name: entry.name, def: remote.def });
+            }
+            else {
+                unsupported.push({ name: entry.name, reason: remote.reason });
+            }
+            continue;
+        }
+        if (!entry.transport.command) {
+            unsupported.push({ name: entry.name, reason: "stdio entry has no command — malformed, skipped" });
+            continue;
+        }
+        const def = { transport: "stdio", command: entry.transport.command };
+        if (entry.transport.args && entry.transport.args.length > 0)
+            def.args = entry.transport.args;
+        if (entry.transport.env_vars && entry.transport.env_vars.length > 0)
+            def.env = entry.transport.env_vars;
+        if (tomlContent) {
+            const staticEnv = readServerEnvTable(tomlContent, entry.name);
+            if (staticEnv && Object.keys(staticEnv).length > 0)
+                def.staticEnv = staticEnv;
+        }
+        entries.push({ name: entry.name, def });
+    }
+    return { entries, unsupported };
+}
+/**
+ * A non-stdio Codex entry converts only when it's exactly `url` (+
+ * optional `bearer_token_env_var`) — the one shape this project has
+ * verified evidence for, and the only shape Trellis's own writer
+ * (`renderServerSection`'s else-branch) ever produces for Codex. Any of
+ * the three unexplained `*headers*` fields being non-null means the real
+ * server uses a mechanism this codebase has no verified shape for — that
+ * entry stays unsupported rather than silently dropping whatever those
+ * fields represent.
+ */
+function buildCodexRemoteDef(entry) {
+    const { url, bearer_token_env_var: bearerVar, http_headers, env_http_headers, http_headers_helper } = entry.transport;
+    if (http_headers != null || env_http_headers != null || http_headers_helper != null) {
+        return { reason: `codex migrate-in does not support this server's header mechanism (http_headers/env_http_headers/http_headers_helper) — no verified shape for it` };
+    }
+    if (!url) {
+        return { reason: `codex migrate-in: non-stdio entry has no url — malformed, skipped` };
+    }
+    const def = { transport: "http", url };
+    if (bearerVar) {
+        def.headers = { Authorization: `Bearer \${${bearerVar}}` };
+    }
+    return { def };
+}
+/**
+ * Stdio only (design.md D2) — `codex mcp list --json`'s own output never
+ * exposes `url`/`bearer_token_env_var` in this codebase's `CodexMcpEntry`
+ * (src/probes/codex.ts), and this codebase has no verified evidence for
+ * what that subprocess reports for a non-stdio server. Guessing at an
+ * external tool's unverified output shape is exactly what this project's
+ * "verify, don't assume" discipline exists to prevent — a non-stdio
+ * entry is reported as unsupported instead.
+ */
+export function readCodexMcpDefs(homeDir) {
+    let raw;
+    try {
+        // `codex` resolves its own config via $HOME (confirmed by running it
+        // with an overridden HOME against an empty scratch dir — it returns
+        // `[]`, not the real machine's servers), so this must be scoped to
+        // `homeDir` explicitly — `src/probes/codex.ts`'s own equivalent call
+        // has this same gap, unaddressed there; not touched by this change.
+        raw = execFileSync("codex", ["mcp", "list", "--json"], { encoding: "utf-8", timeout: 5_000, env: { ...process.env, HOME: homeDir } });
+    }
+    catch {
+        return EMPTY_RESULT;
+    }
+    let mcpEntries;
+    try {
+        mcpEntries = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY_RESULT;
+    }
+    const configToml = join(homeDir, ".codex", "config.toml");
+    let tomlContent;
+    try {
+        tomlContent = readFileSync(configToml, "utf-8");
+    }
+    catch {
+        tomlContent = undefined;
+    }
+    return buildCodexMcpReadResult(mcpEntries, tomlContent);
+}

package/dist/lib/mcpOwnership.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Persisted record of what `mcp sync` itself last wrote for each agent —
+ * the ownership marker a bare TOML/JSON key otherwise lacks (mcpPlan.ts's
+ * own D7 reasoning: unlike a skill's symlink, there's nothing on disk to
+ * prove Trellis, not the user, put a given entry there). This ledger is
+ * that proof, kept separately from canonical (`~/.trellis/mcp/
+ * servers.yaml`) since it's Trellis's own private bookkeeping, not
+ * user-authored content.
+ *
+ * Stores each entry as the exact *rendered* value written at the time
+ * (a plain object for JSON agents, a TOML section string for Codex) —
+ * deliberately not a hash, so the later "is this still what we wrote"
+ * check can reuse each format's own already-existing equality check
+ * (`deepEqual` for JSON, `===` for TOML text) instead of a second,
+ * parallel comparison mechanism.
+ */
+import type { AgentId } from "../core/types.js";
+export type McpOwnershipLedger = Record<string, Record<string, unknown>>;
+export declare function mcpOwnershipPath(homeDir: string): string;
+export declare function loadMcpOwnership(homeDir: string): McpOwnershipLedger;
+export declare function saveMcpOwnership(homeDir: string, ledger: McpOwnershipLedger): void;
+/** This agent's own slice — `{}` if nothing has ever been recorded for it. */
+export declare function ownedByAgent(ledger: McpOwnershipLedger, agentId: AgentId): Record<string, unknown>;
+export declare function recordOwned(ledger: McpOwnershipLedger, agentId: AgentId, name: string, rendered: unknown): McpOwnershipLedger;
+export declare function forgetOwned(ledger: McpOwnershipLedger, agentId: AgentId, name: string): McpOwnershipLedger;

package/dist/lib/mcpOwnership.js

@@ -0,0 +1,50 @@
+/**
+ * Persisted record of what `mcp sync` itself last wrote for each agent —
+ * the ownership marker a bare TOML/JSON key otherwise lacks (mcpPlan.ts's
+ * own D7 reasoning: unlike a skill's symlink, there's nothing on disk to
+ * prove Trellis, not the user, put a given entry there). This ledger is
+ * that proof, kept separately from canonical (`~/.trellis/mcp/
+ * servers.yaml`) since it's Trellis's own private bookkeeping, not
+ * user-authored content.
+ *
+ * Stores each entry as the exact *rendered* value written at the time
+ * (a plain object for JSON agents, a TOML section string for Codex) —
+ * deliberately not a hash, so the later "is this still what we wrote"
+ * check can reuse each format's own already-existing equality check
+ * (`deepEqual` for JSON, `===` for TOML text) instead of a second,
+ * parallel comparison mechanism.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function mcpOwnershipPath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "ownership.json");
+}
+export function loadMcpOwnership(homeDir) {
+    const path = mcpOwnershipPath(homeDir);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {}; // unreadable/corrupt ledger — treat as "nothing recorded yet", never crash a sync over it
+    }
+}
+export function saveMcpOwnership(homeDir, ledger) {
+    mkdirSync(join(homeDir, ".trellis", "mcp"), { recursive: true });
+    writeFileSync(mcpOwnershipPath(homeDir), `${JSON.stringify(ledger, null, 2)}\n`);
+}
+/** This agent's own slice — `{}` if nothing has ever been recorded for it. */
+export function ownedByAgent(ledger, agentId) {
+    return ledger[agentId] ?? {};
+}
+export function recordOwned(ledger, agentId, name, rendered) {
+    return { ...ledger, [agentId]: { ...(ledger[agentId] ?? {}), [name]: rendered } };
+}
+export function forgetOwned(ledger, agentId, name) {
+    if (!(name in (ledger[agentId] ?? {})))
+        return ledger;
+    const agentEntries = { ...ledger[agentId] };
+    delete agentEntries[name];
+    return { ...ledger, [agentId]: agentEntries };
+}

package/dist/lib/memoryGraph.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Converts canonical `memories/*.md` into `@modelcontextprotocol/
+ * server-memory`'s own on-disk JSON-lines knowledge-graph format, and
+ * upserts them into an existing graph file without disturbing anything
+ * else in it (trellis-memory-sync) — closing P6's explicitly-left-open
+ * "auto-ingesting memories/*.md content into the running memory
+ * server's store" gap.
+ *
+ * Each line in that file is one JSON object, either
+ * `{type:"entity", name, entityType, observations}` or
+ * `{type:"relation", from, to, relationType}` — the real, documented
+ * shape the official server persists and reads back on its own next
+ * startup (this project writes the file directly; it never spawns or
+ * talks to a running server process).
+ *
+ * `entityType: "trellis-memory"` is this project's own in-band ownership
+ * marker — simpler than a separate ledger file (unlike MCP server sync,
+ * every agent connected to this one server shares the exact same graph,
+ * so there's no per-agent rendering to track). An existing entity with
+ * the same name but a different `entityType` was created by something
+ * else (an agent's own runtime tool calls, most likely) and is left
+ * completely untouched — reported as a conflict, never overwritten.
+ */
+import type { CanonicalSource } from "../core/types.js";
+export interface MemoryEntity {
+    type: "entity";
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+export interface MemoryRelation {
+    type: "relation";
+    from: string;
+    to: string;
+    relationType: string;
+}
+export type MemoryGraphLine = MemoryEntity | MemoryRelation;
+export declare const TRELLIS_MEMORY_ENTITY_TYPE = "trellis-memory";
+export declare function parseMemoryGraph(content: string): MemoryGraphLine[];
+export declare function renderMemoryGraph(lines: readonly MemoryGraphLine[]): string;
+export type MemorySyncAction = "create" | "already-synced" | "remove" | "conflict";
+export interface MemorySyncItem {
+    name: string;
+    action: MemorySyncAction;
+    detail: string;
+}
+export interface MemorySyncPlan {
+    items: MemorySyncItem[];
+    /** The full graph content to write — `undefined` when there is
+     * nothing to change (no create/remove items). */
+    nextGraph?: MemoryGraphLine[];
+}
+/**
+ * Pure: computes the next graph state and a human-readable plan, given
+ * the current graph's raw content (or `undefined` if the file doesn't
+ * exist yet) and canonical's memory entries. Every non-`trellis-memory`
+ * entity and every relation passes through completely untouched,
+ * regardless of what canonical wants.
+ */
+export declare function planMemorySync(canonical: Pick<CanonicalSource, "memories">, currentGraphContent: string | undefined): MemorySyncPlan;

package/dist/lib/memoryGraph.js

@@ -0,0 +1,101 @@
+/**
+ * Converts canonical `memories/*.md` into `@modelcontextprotocol/
+ * server-memory`'s own on-disk JSON-lines knowledge-graph format, and
+ * upserts them into an existing graph file without disturbing anything
+ * else in it (trellis-memory-sync) — closing P6's explicitly-left-open
+ * "auto-ingesting memories/*.md content into the running memory
+ * server's store" gap.
+ *
+ * Each line in that file is one JSON object, either
+ * `{type:"entity", name, entityType, observations}` or
+ * `{type:"relation", from, to, relationType}` — the real, documented
+ * shape the official server persists and reads back on its own next
+ * startup (this project writes the file directly; it never spawns or
+ * talks to a running server process).
+ *
+ * `entityType: "trellis-memory"` is this project's own in-band ownership
+ * marker — simpler than a separate ledger file (unlike MCP server sync,
+ * every agent connected to this one server shares the exact same graph,
+ * so there's no per-agent rendering to track). An existing entity with
+ * the same name but a different `entityType` was created by something
+ * else (an agent's own runtime tool calls, most likely) and is left
+ * completely untouched — reported as a conflict, never overwritten.
+ */
+import { readFileSync } from "node:fs";
+export const TRELLIS_MEMORY_ENTITY_TYPE = "trellis-memory";
+export function parseMemoryGraph(content) {
+    const lines = [];
+    for (const raw of content.split("\n")) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.type === "entity" || parsed.type === "relation") {
+                lines.push(parsed);
+            }
+        }
+        catch {
+            // Not valid JSON — skip rather than fail the whole file; a
+            // hand-edited or partially-written line shouldn't block every
+            // other, unrelated line in the graph.
+        }
+    }
+    return lines;
+}
+export function renderMemoryGraph(lines) {
+    if (lines.length === 0)
+        return "";
+    return `${lines.map((line) => JSON.stringify(line)).join("\n")}\n`;
+}
+/**
+ * Pure: computes the next graph state and a human-readable plan, given
+ * the current graph's raw content (or `undefined` if the file doesn't
+ * exist yet) and canonical's memory entries. Every non-`trellis-memory`
+ * entity and every relation passes through completely untouched,
+ * regardless of what canonical wants.
+ */
+export function planMemorySync(canonical, currentGraphContent) {
+    const existingLines = currentGraphContent !== undefined ? parseMemoryGraph(currentGraphContent) : [];
+    const untouchedLines = existingLines.filter((line) => !(line.type === "entity" && line.entityType === TRELLIS_MEMORY_ENTITY_TYPE));
+    const existingTrellisEntities = new Map(existingLines.filter((line) => line.type === "entity" && line.entityType === TRELLIS_MEMORY_ENTITY_TYPE).map((e) => [e.name, e]));
+    const existingOtherEntityNames = new Set(existingLines.filter((line) => line.type === "entity" && line.entityType !== TRELLIS_MEMORY_ENTITY_TYPE).map((e) => e.name));
+    const items = [];
+    const nextTrellisEntities = [];
+    let changed = false;
+    const canonicalNames = new Set(canonical.memories.map((m) => m.name));
+    for (const memory of canonical.memories) {
+        if (existingOtherEntityNames.has(memory.name)) {
+            items.push({ name: memory.name, action: "conflict", detail: `an entity named "${memory.name}" already exists in the graph and wasn't created by Trellis — resolve by hand` });
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(memory.file, "utf-8");
+        }
+        catch (err) {
+            items.push({ name: memory.name, action: "conflict", detail: `could not read ${memory.file}: ${err instanceof Error ? err.message : String(err)}` });
+            continue;
+        }
+        const desired = { type: "entity", name: memory.name, entityType: TRELLIS_MEMORY_ENTITY_TYPE, observations: [content] };
+        const existing = existingTrellisEntities.get(memory.name);
+        nextTrellisEntities.push(desired);
+        if (existing && existing.observations.length === 1 && existing.observations[0] === content) {
+            items.push({ name: memory.name, action: "already-synced", detail: "graph content is already identical" });
+        }
+        else {
+            items.push({ name: memory.name, action: "create", detail: existing ? "will update the existing entity's observation" : "will create a new entity" });
+            changed = true;
+        }
+    }
+    for (const [name] of existingTrellisEntities) {
+        if (canonicalNames.has(name))
+            continue; // still wanted, handled above
+        items.push({ name, action: "remove", detail: "no longer in canonical — will be removed from the graph" });
+        changed = true;
+    }
+    if (!changed) {
+        return { items };
+    }
+    return { items, nextGraph: [...untouchedLines, ...nextTrellisEntities] };
+}

package/dist/lib/realHomeSnapshot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `--real` sandbox mode's allowlist (trellis-real-sandbox-verification
+ * design.md D1): every real dotfile path a probe (src/probes/*.ts) is
+ * already known to read, and nothing else. Allowlist, not denylist —
+ * anything this project doesn't already know to be structural (real
+ * OAuth token storage, session/history logs, credentials) is never
+ * copied out of a developer's real `$HOME` because it was never named
+ * here, not because it was excluded after the fact. Kept in sync with
+ * each probe's own `join(homeDir, ...)` calls by direct source
+ * cross-reference, not by assumption.
+ */
+export declare const REAL_HOME_ALLOWLIST: readonly string[];
+/**
+ * Copies only allowlisted paths that actually exist under `sourceHome`
+ * into `destHome` — a missing entry is a normal, expected state (not
+ * every agent is installed), never an error. `dereference: true` is
+ * required, not incidental: `sync`'s own real output is symlinks
+ * (skills, instructions) pointing back at `sourceHome`'s own
+ * `.trellis/` — a container mounting a snapshot that kept those
+ * symlinks as symlinks would get a dangling reference to a path that
+ * doesn't exist inside it. Copying real content instead is what makes
+ * the snapshot self-contained (found by actually running this against
+ * a real, already-synced machine — not by inspection). Returns the
+ * relative paths actually copied, for the caller to report.
+ */
+export declare function buildRealHomeSnapshot(sourceHome: string, destHome: string): string[];

package/dist/lib/realHomeSnapshot.js

@@ -0,0 +1,77 @@
+/**
+ * `--real` sandbox mode's allowlist (trellis-real-sandbox-verification
+ * design.md D1): every real dotfile path a probe (src/probes/*.ts) is
+ * already known to read, and nothing else. Allowlist, not denylist —
+ * anything this project doesn't already know to be structural (real
+ * OAuth token storage, session/history logs, credentials) is never
+ * copied out of a developer's real `$HOME` because it was never named
+ * here, not because it was excluded after the fact. Kept in sync with
+ * each probe's own `join(homeDir, ...)` calls by direct source
+ * cross-reference, not by assumption.
+ */
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const REAL_HOME_ALLOWLIST = [
+    // claude-code (src/probes/claude-code.ts)
+    ".claude.json",
+    ".claude/skills",
+    ".claude/agents",
+    ".claude/CLAUDE.md",
+    // codex (src/probes/codex.ts)
+    ".codex/config.toml",
+    ".agents/skills",
+    ".codex/skills",
+    // kiro (src/probes/kiro.ts)
+    ".kiro/settings/mcp.json",
+    ".kiro/skills",
+    ".kiro/steering/CLAUDE.md",
+    // pi (src/probes/pi.ts)
+    ".pi/agent/settings.json",
+    ".pi/agent/skills",
+    ".pi/agent/AGENTS.override.md",
+    ".pi/agent/AGENTS.md",
+    ".pi/agent/AGENTS.MD",
+    ".pi/agent/CLAUDE.md",
+    ".pi/agent/CLAUDE.MD",
+    // this machine's own real canonical source, if it already has one —
+    // Trellis's own managed data, not a third-party agent's.
+    ".trellis",
+];
+/**
+ * Copies only allowlisted paths that actually exist under `sourceHome`
+ * into `destHome` — a missing entry is a normal, expected state (not
+ * every agent is installed), never an error. `dereference: true` is
+ * required, not incidental: `sync`'s own real output is symlinks
+ * (skills, instructions) pointing back at `sourceHome`'s own
+ * `.trellis/` — a container mounting a snapshot that kept those
+ * symlinks as symlinks would get a dangling reference to a path that
+ * doesn't exist inside it. Copying real content instead is what makes
+ * the snapshot self-contained (found by actually running this against
+ * a real, already-synced machine — not by inspection). Returns the
+ * relative paths actually copied, for the caller to report.
+ */
+export function buildRealHomeSnapshot(sourceHome, destHome) {
+    const copied = [];
+    for (const rel of REAL_HOME_ALLOWLIST) {
+        const src = join(sourceHome, rel);
+        if (!existsSync(src))
+            continue;
+        const dest = join(destHome, rel);
+        // On a case-insensitive filesystem (macOS default), two distinct
+        // allowlist entries (e.g. `AGENTS.md`/`AGENTS.MD` — pi's own
+        // case-sensitive candidate list, src/probes/pi.ts) can resolve to
+        // the identical real file; a `dest` an earlier entry already
+        // created (case-insensitively) needs no second, redundant copy —
+        // found by actually running this against a real machine, where it
+        // also tripped a Node `cpSync` quirk re-copying a symlink onto its
+        // own already-materialized destination.
+        if (existsSync(dest)) {
+            copied.push(rel);
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        cpSync(src, dest, { recursive: true, dereference: true });
+        copied.push(rel);
+    }
+    return copied;
+}

package/dist/lib/terminalPicker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal, dependency-free arrow-key/checkbox terminal picker
+ * (trellis-onboard-interactive-picker design.md D1) — the interaction
+ * surface `trellis onboard`'s two prompts need (at most four rows, no
+ * search, no pagination) doesn't need a full prompt library; this
+ * hand-rolls just enough raw-mode key handling and ANSI rendering for
+ * that bounded case, matching the project's existing narrow-dependency
+ * precedent (src/lib/envVarNames.ts, src/lib/secretEnv.ts).
+ *
+ * `input`/`output` are injectable (never a CLI flag) purely so tests can
+ * drive the real key-parsing/render loop against a plain stream instead
+ * of a real TTY — same seam pattern (`homeDir`, etc.) used everywhere
+ * else in this project.
+ */
+import type { Readable, Writable } from "node:stream";
+export interface PickerStreams {
+    input: NodeJS.ReadStream | Readable;
+    output: NodeJS.WriteStream | Writable;
+}
+/**
+ * True only when both streams are real, raw-mode-capable terminals — the
+ * exact gate deciding picker vs. the pre-existing numbered-typing prompt
+ * (design.md D2). A stream lacking `setRawMode` (piped input, some
+ * minimal TTYs) always falls back, never hangs or guesses.
+ */
+export declare function canUseInteractivePicker(streams?: PickerStreams): boolean;
+/** Wrapping index navigation — pure, exported for direct unit testing. */
+export declare function nextIndex(current: number, delta: number, length: number): number;
+/** Pure single-index toggle — exported for direct unit testing. */
+export declare function toggled(checked: readonly boolean[], index: number): boolean[];
+/**
+ * Single-select: Up/Down/j/k moves the highlight, Enter confirms. Resolves
+ * the confirmed index, or `null` on Ctrl+C cancel. Caller (onboard.ts)
+ * must have already confirmed `canUseInteractivePicker()` — this function
+ * does not re-check, and assumes `streams.input` genuinely supports raw
+ * mode.
+ */
+export declare function runSingleSelectPicker(items: string[], streams?: PickerStreams): Promise<number | null>;
+/**
+ * Multi-select (checkbox): Up/Down/j/k moves the highlight, Space toggles
+ * the current row, Enter confirms. Resolves the checked indices at
+ * confirm time, or `null` on Ctrl+C cancel. Same precondition as
+ * `runSingleSelectPicker`.
+ */
+export declare function runMultiSelectPicker(items: string[], initiallyChecked: readonly boolean[], streams?: PickerStreams): Promise<number[] | null>;