agent-trellis 0.1.0 → 0.3.0

package/dist/lib/terminalPicker.js

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+function defaultStreams() {
+    return { input: process.stdin, output: process.stdout };
+}
+/**
+ * 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 function canUseInteractivePicker(streams = defaultStreams()) {
+    const input = streams.input;
+    const output = streams.output;
+    return Boolean(input.isTTY && output.isTTY && typeof input.setRawMode === "function");
+}
+/** Wrapping index navigation — pure, exported for direct unit testing. */
+export function nextIndex(current, delta, length) {
+    return ((current + delta) % length + length) % length;
+}
+/** Pure single-index toggle — exported for direct unit testing. */
+export function toggled(checked, index) {
+    const next = [...checked];
+    next[index] = !next[index];
+    return next;
+}
+const ESC = "\u001b";
+const CTRL_C = "\u0003";
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+/** Parses one raw input chunk into a single logical key — arrow escape
+ * sequences, j/k, space, enter, or Ctrl+C. Anything else is ignored. */
+function parseKey(chunk) {
+    if (chunk === CTRL_C)
+        return "cancel";
+    if (chunk === "\r" || chunk === "\n")
+        return "confirm";
+    if (chunk === " ")
+        return "toggle";
+    if (chunk === `${ESC}[A` || chunk === "k")
+        return "up";
+    if (chunk === `${ESC}[B` || chunk === "j")
+        return "down";
+    return null;
+}
+function withRawMode(streams, body) {
+    const input = streams.input;
+    const output = streams.output;
+    const canSetRawMode = typeof input.setRawMode === "function";
+    if (canSetRawMode)
+        input.setRawMode(true);
+    input.resume();
+    input.setEncoding("utf-8");
+    output.write(HIDE_CURSOR);
+    const restore = () => {
+        output.write(SHOW_CURSOR);
+        if (canSetRawMode)
+            input.setRawMode(false);
+        input.pause();
+    };
+    // Second-layer safety net (design.md D6): a thrown error the caller's
+    // own try/finally doesn't get a chance to run for (process killed
+    // externally) must still not leave the terminal in raw mode/cursor
+    // hidden.
+    process.once("exit", restore);
+    return body().finally(() => {
+        restore();
+        process.removeListener("exit", restore);
+    });
+}
+function moveCursorUp(output, lines) {
+    if (lines > 0)
+        output.write(`${ESC}[${lines}A`);
+}
+function clearLines(output, lines) {
+    for (let i = 0; i < lines; i++) {
+        output.write(`${ESC}[2K`);
+        if (i < lines - 1)
+            output.write(`${ESC}[1B`);
+    }
+    moveCursorUp(output, lines - 1);
+}
+function renderRows(output, rows, previousRowCount) {
+    if (previousRowCount > 0) {
+        clearLines(output, previousRowCount);
+    }
+    for (const row of rows) {
+        output.write(`${row}\n`);
+    }
+}
+function highlightRow(text, isHighlighted) {
+    return isHighlighted ? `> ${ESC}[7m${text}${ESC}[0m` : `  ${text}`;
+}
+/**
+ * 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 async function runSingleSelectPicker(items, streams = defaultStreams()) {
+    const { input, output } = streams;
+    return withRawMode(streams, () => {
+        return new Promise((resolve) => {
+            let highlighted = 0;
+            let rowCount = 0;
+            const draw = () => {
+                const rows = items.map((label, i) => highlightRow(label, i === highlighted));
+                renderRows(output, rows, rowCount);
+                rowCount = rows.length;
+            };
+            draw();
+            const onData = (chunk) => {
+                const key = parseKey(chunk.toString("utf-8"));
+                if (key === "up") {
+                    highlighted = nextIndex(highlighted, -1, items.length);
+                    draw();
+                }
+                else if (key === "down") {
+                    highlighted = nextIndex(highlighted, 1, items.length);
+                    draw();
+                }
+                else if (key === "confirm") {
+                    input.removeListener("data", onData);
+                    resolve(highlighted);
+                }
+                else if (key === "cancel") {
+                    input.removeListener("data", onData);
+                    resolve(null);
+                }
+            };
+            input.on("data", onData);
+        });
+    });
+}
+/**
+ * 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 async function runMultiSelectPicker(items, initiallyChecked, streams = defaultStreams()) {
+    const { input, output } = streams;
+    return withRawMode(streams, () => {
+        return new Promise((resolve) => {
+            let highlighted = 0;
+            let checked = [...initiallyChecked];
+            let rowCount = 0;
+            const draw = () => {
+                const rows = items.map((label, i) => highlightRow(`[${checked[i] ? "x" : " "}] ${label}`, i === highlighted));
+                renderRows(output, rows, rowCount);
+                rowCount = rows.length;
+            };
+            draw();
+            const onData = (chunk) => {
+                const key = parseKey(chunk.toString("utf-8"));
+                if (key === "up") {
+                    highlighted = nextIndex(highlighted, -1, items.length);
+                    draw();
+                }
+                else if (key === "down") {
+                    highlighted = nextIndex(highlighted, 1, items.length);
+                    draw();
+                }
+                else if (key === "toggle") {
+                    checked = toggled(checked, highlighted);
+                    draw();
+                }
+                else if (key === "confirm") {
+                    input.removeListener("data", onData);
+                    resolve(checked.flatMap((isChecked, i) => (isChecked ? [i] : [])));
+                }
+                else if (key === "cancel") {
+                    input.removeListener("data", onData);
+                    resolve(null);
+                }
+            };
+            input.on("data", onData);
+        });
+    });
+}

package/dist/lib/tomlSection.d.ts

@@ -23,10 +23,11 @@ export interface SectionRange {
  */
 export declare function findSection(content: string, header: string): SectionRange | null;
 /**
- * Returns the current stored text of `[mcp_servers.<name>]` (or `null` if
- * it doesn't exist), for comparing against `renderServerSection`'s output
- * to decide create/repair vs. no-op — exact text equality is enough here,
- * no parsing needed on either side.
+ * Returns the current stored text of a server's full owned range (see
+ * `findServerRange`) — or `null` if it doesn't exist — for comparing
+ * against `renderServerSection`'s output to decide create/repair vs.
+ * no-op. Exact text equality is enough here, no parsing needed on either
+ * side.
  */
 export declare function currentServerSectionText(content: string, name: string): string | null;
 /**
@@ -40,9 +41,22 @@ export declare function currentServerSectionText(content: string, name: string):
  * than this function silently rendering nothing for it.
  */
 export declare function codexBearerTokenEnvVar(def: McpServerDef): string | undefined;
-/** Renders a `[mcp_servers.<name>]` block for a bounded, known shape —
- * this is templating, not general TOML serialization. */
+/** Renders a `[mcp_servers.<name>]` block (plus, when `staticEnv` is set,
+ * an immediately-adjacent `[mcp_servers.<name>.env]` block — see
+ * `findServerRange`) for a bounded, known shape — this is templating,
+ * not general TOML serialization. */
 export declare function renderServerSection(name: string, def: McpServerDef): string;
+/**
+ * Reads a server's `[mcp_servers.<name>.env]` table's literal key-value
+ * pairs directly from real `config.toml` text — the exact inverse of
+ * `renderServerSection`'s own `static_env` block, the only piece of a
+ * Codex server's `static_env` that `codex mcp list --json` cannot ever
+ * report (it only exposes `env_vars`, i.e. names, from the *main*
+ * table — trellis-migrate-mcp-servers design.md D3). Returns `undefined`
+ * if the table doesn't exist; a malformed line inside it is skipped, not
+ * fatal, matching `parseMemoryGraph`'s own tolerant-parse precedent.
+ */
+export declare function readServerEnvTable(content: string, name: string): Record<string, string> | undefined;
 /**
  * Replaces an existing section in place, or appends a new one at EOF
  * (with a leading blank-line separator) if none exists yet. Never touches

package/dist/lib/tomlSection.js

@@ -36,6 +36,9 @@ function tomlStringArray(values) {
 function serverHeader(name) {
     return `mcp_servers.${tomlKeySegment(name)}`;
 }
+function envHeader(name) {
+    return `${serverHeader(name)}.env`;
+}
 /**
  * Finds an existing `[header]` table's exact line range: `start` is the
  * header line itself, `end` is the line before the next table header (any
@@ -70,14 +73,42 @@ export function findSection(content, header) {
     return { start, end };
 }
 /**
- * Returns the current stored text of `[mcp_servers.<name>]` (or `null` if
- * it doesn't exist), for comparing against `renderServerSection`'s output
- * to decide create/repair vs. no-op — exact text equality is enough here,
- * no parsing needed on either side.
+ * A server's full owned range: its main `[mcp_servers.<name>]` table,
+ * extended to also cover an immediately-following `[mcp_servers.<name>.env]`
+ * table (skipping only blank/comment padding in between — the same skip
+ * rule `findSection`'s own trailing trim already applies) when one is
+ * present. The two are rendered and managed as one atomic unit whenever
+ * `staticEnv` is set (trellis-mcp-static-env-and-disabled-servers
+ * design.md D3) — create/repair/remove must never touch one without the
+ * other.
+ */
+function findServerRange(content, name) {
+    const main = findSection(content, serverHeader(name));
+    if (!main) {
+        return null;
+    }
+    const lines = content.split("\n");
+    let i = main.end + 1;
+    while (i < lines.length && (lines[i].trim() === "" || lines[i].trim().startsWith("#"))) {
+        i += 1;
+    }
+    if (i < lines.length && lines[i].trim() === `[${envHeader(name)}]`) {
+        const envRange = findSection(content, envHeader(name));
+        if (envRange) {
+            return { start: main.start, end: envRange.end };
+        }
+    }
+    return main;
+}
+/**
+ * Returns the current stored text of a server's full owned range (see
+ * `findServerRange`) — or `null` if it doesn't exist — for comparing
+ * against `renderServerSection`'s output to decide create/repair vs.
+ * no-op. Exact text equality is enough here, no parsing needed on either
+ * side.
  */
 export function currentServerSectionText(content, name) {
-    const header = serverHeader(name);
-    const range = findSection(content, header);
+    const range = findServerRange(content, name);
     if (!range) {
         return null;
     }
@@ -103,8 +134,10 @@ export function codexBearerTokenEnvVar(def) {
         return undefined;
     return BEARER_TOKEN_VALUE_RE.exec(value)?.[1];
 }
-/** Renders a `[mcp_servers.<name>]` block for a bounded, known shape —
- * this is templating, not general TOML serialization. */
+/** Renders a `[mcp_servers.<name>]` block (plus, when `staticEnv` is set,
+ * an immediately-adjacent `[mcp_servers.<name>.env]` block — see
+ * `findServerRange`) for a bounded, known shape — this is templating,
+ * not general TOML serialization. */
 export function renderServerSection(name, def) {
     const lines = [`[${serverHeader(name)}]`];
     if (def.transport === "stdio") {
@@ -122,16 +155,50 @@ export function renderServerSection(name, def) {
         if (bearerEnvVar)
             lines.push(`bearer_token_env_var = ${tomlString(bearerEnvVar)}`);
     }
+    const staticEnvEntries = Object.entries(def.staticEnv ?? {});
+    if (staticEnvEntries.length > 0) {
+        lines.push(`[${envHeader(name)}]`);
+        for (const [key, value] of staticEnvEntries) {
+            lines.push(`${tomlKeySegment(key)} = ${tomlString(value)}`);
+        }
+    }
     return lines.join("\n");
 }
+const ENV_TABLE_LINE_RE = /^("(?:[^"\\]|\\.)*"|[A-Za-z0-9_-]+)\s*=\s*("(?:[^"\\]|\\.)*")\s*$/;
+/**
+ * Reads a server's `[mcp_servers.<name>.env]` table's literal key-value
+ * pairs directly from real `config.toml` text — the exact inverse of
+ * `renderServerSection`'s own `static_env` block, the only piece of a
+ * Codex server's `static_env` that `codex mcp list --json` cannot ever
+ * report (it only exposes `env_vars`, i.e. names, from the *main*
+ * table — trellis-migrate-mcp-servers design.md D3). Returns `undefined`
+ * if the table doesn't exist; a malformed line inside it is skipped, not
+ * fatal, matching `parseMemoryGraph`'s own tolerant-parse precedent.
+ */
+export function readServerEnvTable(content, name) {
+    const range = findSection(content, envHeader(name));
+    if (!range) {
+        return undefined;
+    }
+    const lines = content.split("\n").slice(range.start + 1, range.end + 1);
+    const result = {};
+    for (const line of lines) {
+        const match = ENV_TABLE_LINE_RE.exec(line.trim());
+        if (!match)
+            continue;
+        const rawKey = match[1];
+        const key = rawKey.startsWith('"') ? JSON.parse(rawKey) : rawKey;
+        result[key] = JSON.parse(match[2]);
+    }
+    return result;
+}
 /**
  * Replaces an existing section in place, or appends a new one at EOF
  * (with a leading blank-line separator) if none exists yet. Never touches
  * any line outside the section it locates or the single appended block.
  */
 export function upsertSection(content, name, def) {
-    const header = serverHeader(name);
-    const existing = findSection(content, header);
+    const existing = findServerRange(content, name);
     const newLines = renderServerSection(name, def).split("\n");
     if (existing) {
         const lines = content.split("\n");
@@ -147,8 +214,7 @@ export function upsertSection(content, name, def) {
  * No-op if the section doesn't exist — idempotent.
  */
 export function removeSection(content, name) {
-    const header = serverHeader(name);
-    const existing = findSection(content, header);
+    const existing = findServerRange(content, name);
     if (!existing) {
         return content;
     }