agent-trellis 0.1.0

package/dist/lib/probeCommon.js

@@ -0,0 +1,108 @@
+/**
+ * Shared filesystem/JSON reading used by every per-agent probe
+ * (src/probes/*.ts) — kept here so all four agree on what "symlink status,"
+ * "skill root," and "resolve env var references" mean, rather than each
+ * probe reimplementing it slightly differently.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { findSkillFile } from "./skillFile.js";
+export function pathRef(path) {
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    if (!lstatSync(path).isSymbolicLink()) {
+        return { path, isSymlink: false };
+    }
+    try {
+        return { path, isSymlink: true, target: realpathSync(path) };
+    }
+    catch {
+        return { path, isSymlink: true };
+    }
+}
+/**
+ * One skill root = a directory of skill subdirectories, each expected to
+ * hold `SKILL.md`. Every agent as of design.md D5 uses this shape.
+ */
+export function scanSkillRoot(rootPath) {
+    const ref = pathRef(rootPath);
+    if (!ref) {
+        return undefined;
+    }
+    const skills = [];
+    let entries = [];
+    try {
+        entries = readdirSync(rootPath);
+    }
+    catch {
+        entries = [];
+    }
+    for (const name of entries) {
+        const dir = join(rootPath, name);
+        let isDirectory;
+        try {
+            isDirectory = statSync(dir).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDirectory) {
+            continue;
+        }
+        const skillFile = findSkillFile(dir);
+        if (!skillFile) {
+            continue;
+        }
+        let realDir;
+        try {
+            realDir = realpathSync(dir);
+        }
+        catch {
+            realDir = dir;
+        }
+        skills.push({
+            name,
+            dir,
+            realDir,
+            isSymlink: lstatSync(dir).isSymbolicLink(),
+            caseCorrect: skillFile.caseCorrect,
+        });
+    }
+    return { path: rootPath, isSymlink: ref.isSymlink, target: ref.target, skills };
+}
+export function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function countDirEntries(dir) {
+    try {
+        return readdirSync(dir).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Substitutes `${VAR}` against `base` (normally `process.env`) so a
+ * probe's handshake spawn gets the real value — configs only ever hold
+ * the variable NAME (docs/research.md "Secrets"), never a literal.
+ * Values given as a bare array (Codex's `env_vars` style: just names) need
+ * no substitution — the named var must already be in `base` for the
+ * spawned process to inherit it, which it will via object spread.
+ */
+export function resolveEnvRefs(envSpec, base) {
+    const out = { ...base };
+    if (!envSpec || Array.isArray(envSpec)) {
+        return out;
+    }
+    for (const [key, raw] of Object.entries(envSpec)) {
+        const match = /^\$\{(.+)\}$/.exec(raw);
+        out[key] = match ? base[match[1]] : raw;
+    }
+    return out;
+}

package/dist/lib/secretEnv.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared secret-value resolver (trellis-secrets-env-management). Both
+ * the pi bridge and `secrets audit` call this — never their own
+ * `process.env[name]` lookup — so they can never disagree about where a
+ * declared name's value comes from (design.md D1).
+ *
+ * Dependency-free by design, same as src/lib/envVarNames.ts: a full
+ * dotenv library's quoting/escaping/interpolation rules are more than
+ * this narrow need requires (design.md D4).
+ */
+import type { SecretsPolicy } from "../core/types.js";
+export declare function parseDotenv(content: string): Record<string, string>;
+/**
+ * `policy.envFile` set: it is the SOLE source — a name absent from it
+ * resolves to `undefined`, `process.env` is never consulted (a silent
+ * fallback would defeat the isolation this exists to offer). Unset:
+ * reads `process.env` directly, identical to every pre-existing caller.
+ */
+export declare function resolveSecretEnv(names: string[], policy: SecretsPolicy): Record<string, string | undefined>;

package/dist/lib/secretEnv.js

@@ -0,0 +1,46 @@
+/**
+ * Shared secret-value resolver (trellis-secrets-env-management). Both
+ * the pi bridge and `secrets audit` call this — never their own
+ * `process.env[name]` lookup — so they can never disagree about where a
+ * declared name's value comes from (design.md D1).
+ *
+ * Dependency-free by design, same as src/lib/envVarNames.ts: a full
+ * dotenv library's quoting/escaping/interpolation rules are more than
+ * this narrow need requires (design.md D4).
+ */
+import { existsSync, readFileSync } from "node:fs";
+const LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+export function parseDotenv(content) {
+    const result = {};
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const match = LINE_RE.exec(line);
+        if (match)
+            result[match[1]] = match[2];
+    }
+    return result;
+}
+function loadEnvFile(path) {
+    return existsSync(path) ? parseDotenv(readFileSync(path, "utf-8")) : {};
+}
+/**
+ * `policy.envFile` set: it is the SOLE source — a name absent from it
+ * resolves to `undefined`, `process.env` is never consulted (a silent
+ * fallback would defeat the isolation this exists to offer). Unset:
+ * reads `process.env` directly, identical to every pre-existing caller.
+ */
+export function resolveSecretEnv(names, policy) {
+    const result = {};
+    if (policy.envFile) {
+        const map = loadEnvFile(policy.envFile);
+        for (const name of names)
+            result[name] = map[name];
+    }
+    else {
+        for (const name of names)
+            result[name] = process.env[name];
+    }
+    return result;
+}

package/dist/lib/skillFile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Case-sensitive SKILL.md detection. A file saved as `skill.md` is silently
+ * dropped from discovery on at least one target agent (Codex — see
+ * docs/research.md) with no warning; `doctor` exists in part to catch this
+ * before an agent does, so the wrong-case case must be reported, not
+ * treated the same as "no skill file present at all."
+ */
+export interface SkillFileResult {
+    path: string;
+    caseCorrect: boolean;
+}
+export declare function findSkillFile(dir: string): SkillFileResult | null;

package/dist/lib/skillFile.js

@@ -0,0 +1,26 @@
+/**
+ * Case-sensitive SKILL.md detection. A file saved as `skill.md` is silently
+ * dropped from discovery on at least one target agent (Codex — see
+ * docs/research.md) with no warning; `doctor` exists in part to catch this
+ * before an agent does, so the wrong-case case must be reported, not
+ * treated the same as "no skill file present at all."
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+export function findSkillFile(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    if (entries.includes("SKILL.md")) {
+        return { path: join(dir, "SKILL.md"), caseCorrect: true };
+    }
+    const wrongCase = entries.find((name) => name.toLowerCase() === "skill.md");
+    if (wrongCase) {
+        return { path: join(dir, wrongCase), caseCorrect: false };
+    }
+    return null;
+}

package/dist/lib/syncArgs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pulled out of `src/cli.ts`'s `sync` dispatch branch specifically so it's
+ * directly unit-testable (test/unit/syncArgs.test.ts) without importing
+ * `cli.ts` itself — that file runs `main()` as a top-level side effect
+ * when it's the real entrypoint, which a symlink-safe "is this actually
+ * the entrypoint" check turned out not to be worth building (it broke the
+ * real npm-installed `trellis` bin, whose symlink target's realpath never
+ * equals `process.argv[1]`'s). A zero-side-effect module is the simpler
+ * fix. This exact class of bug (only `rest[0]` was ever checked, so a
+ * flag placed first was mistaken for an unknown target) had no test
+ * coverage before it was found by manual review, not a failing test.
+ */
+export declare function parseSyncArgs(rest: string[]): {
+    target?: "skills" | "instructions";
+    unknownArg?: string;
+};

package/dist/lib/syncArgs.js

@@ -0,0 +1,17 @@
+/**
+ * Pulled out of `src/cli.ts`'s `sync` dispatch branch specifically so it's
+ * directly unit-testable (test/unit/syncArgs.test.ts) without importing
+ * `cli.ts` itself — that file runs `main()` as a top-level side effect
+ * when it's the real entrypoint, which a symlink-safe "is this actually
+ * the entrypoint" check turned out not to be worth building (it broke the
+ * real npm-installed `trellis` bin, whose symlink target's realpath never
+ * equals `process.argv[1]`'s). A zero-side-effect module is the simpler
+ * fix. This exact class of bug (only `rest[0]` was ever checked, so a
+ * flag placed first was mistaken for an unknown target) had no test
+ * coverage before it was found by manual review, not a failing test.
+ */
+export function parseSyncArgs(rest) {
+    const target = rest.find((arg) => arg === "skills" || arg === "instructions");
+    const unknownArg = rest.find((arg) => !arg.startsWith("--") && arg !== "skills" && arg !== "instructions");
+    return { target, unknownArg };
+}

package/dist/lib/tomlSection.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Locate and splice a single `[mcp_servers.<name>]` section in Codex's
+ * `config.toml` — never a general TOML parser. Both realistic library
+ * candidates (`@iarna/toml`, `smol-toml`) were tested directly against a
+ * real fixture and silently drop comments + reformat arrays on a bare
+ * parse→stringify round-trip (design.md D2, trellis-mcp-sync-p2) — not
+ * safe for "touch nothing outside the target section." This module only
+ * ever needs to recognize table headers and render a bounded, known
+ * shape (`McpServerDef`), never general TOML.
+ */
+import type { McpServerDef } from "../core/types.js";
+export interface SectionRange {
+    /** Line index (0-based) of the `[header]` line itself. */
+    start: number;
+    /** Line index (0-based, inclusive) of the section's last line. */
+    end: number;
+}
+/**
+ * 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
+ * `[...]`/`[[...]]`, not just another mcp_servers one) or EOF, whichever
+ * comes first. Returns `null` if no such header exists.
+ */
+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.
+ */
+export declare function currentServerSectionText(content: string, name: string): string | null;
+/**
+ * The only `headers` shape Codex's own real schema can express — it has
+ * no generic headers concept, only this one purpose-built field
+ * (trellis-mcp-transport-auth design.md D4, matching what Codex's own
+ * `mcp add --bearer-token-env-var` CLI generates): exactly one entry,
+ * key `Authorization`, value exactly `Bearer ${VAR}`. Returns the var
+ * name, or `undefined` if `headers` is absent or any other shape —
+ * callers (mcpPlan.ts) refuse-and-conflict on "any other shape" rather
+ * 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. */
+export declare function renderServerSection(name: string, def: McpServerDef): string;
+/**
+ * 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 declare function upsertSection(content: string, name: string, def: McpServerDef): string;
+/**
+ * Removes an existing section (and one immediately-preceding blank line,
+ * if any, so repeated add/remove doesn't accumulate blank separators).
+ * No-op if the section doesn't exist — idempotent.
+ */
+export declare function removeSection(content: string, name: string): string;

package/dist/lib/tomlSection.js

@@ -0,0 +1,162 @@
+/**
+ * Locate and splice a single `[mcp_servers.<name>]` section in Codex's
+ * `config.toml` — never a general TOML parser. Both realistic library
+ * candidates (`@iarna/toml`, `smol-toml`) were tested directly against a
+ * real fixture and silently drop comments + reformat arrays on a bare
+ * parse→stringify round-trip (design.md D2, trellis-mcp-sync-p2) — not
+ * safe for "touch nothing outside the target section." This module only
+ * ever needs to recognize table headers and render a bounded, known
+ * shape (`McpServerDef`), never general TOML.
+ */
+/**
+ * Matches a TOML table header line, and *only* a table header line — the
+ * entire trimmed line must be exactly `[key.path]` or `[[key.path]]`,
+ * each path segment a bare key or a quoted string, nothing else on the
+ * line. Deliberately strict: a multi-line array literal elsewhere in the
+ * file (e.g. `[1, 2],` as a continuation line) must never be mistaken for
+ * a new table boundary — that line has trailing content (`,`) and its
+ * bracket contents aren't a valid key path, so this regex correctly
+ * rejects it. See tasks.md 2.8.
+ */
+const KEY_SEGMENT = String.raw `(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
+const TABLE_HEADER_RE = new RegExp(`^\\[{1,2}${KEY_SEGMENT}(?:\\.${KEY_SEGMENT})*\\]{1,2}$`);
+function isTableHeaderLine(line) {
+    return TABLE_HEADER_RE.test(line.trim());
+}
+/** Quotes a key segment if it isn't a valid bare TOML key. */
+function tomlKeySegment(name) {
+    return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+function serverHeader(name) {
+    return `mcp_servers.${tomlKeySegment(name)}`;
+}
+/**
+ * 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
+ * `[...]`/`[[...]]`, not just another mcp_servers one) or EOF, whichever
+ * comes first. Returns `null` if no such header exists.
+ */
+export function findSection(content, header) {
+    const lines = content.split("\n");
+    const headerLine = `[${header}]`;
+    const start = lines.findIndex((line) => line.trim() === headerLine);
+    if (start === -1) {
+        return null;
+    }
+    let end = lines.length - 1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (isTableHeaderLine(lines[i])) {
+            end = i - 1;
+            break;
+        }
+    }
+    // Don't include a trailing blank separator (or, at EOF, the empty
+    // sentinel element split() leaves after a file's final newline), and
+    // don't include a trailing comment-only block either — a comment
+    // immediately before the NEXT `[header]` documents that section, not
+    // this one (found via the sandbox fixture: a multi-line comment
+    // introducing `[mcp_servers.sentry]` was getting swallowed into the
+    // *previous* section's range and would have been deleted by an
+    // unrelated update to that prior section).
+    while (end > start && (lines[end].trim() === "" || lines[end].trim().startsWith("#"))) {
+        end -= 1;
+    }
+    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.
+ */
+export function currentServerSectionText(content, name) {
+    const header = serverHeader(name);
+    const range = findSection(content, header);
+    if (!range) {
+        return null;
+    }
+    return content.split("\n").slice(range.start, range.end + 1).join("\n");
+}
+const BEARER_TOKEN_VALUE_RE = /^Bearer \$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * The only `headers` shape Codex's own real schema can express — it has
+ * no generic headers concept, only this one purpose-built field
+ * (trellis-mcp-transport-auth design.md D4, matching what Codex's own
+ * `mcp add --bearer-token-env-var` CLI generates): exactly one entry,
+ * key `Authorization`, value exactly `Bearer ${VAR}`. Returns the var
+ * name, or `undefined` if `headers` is absent or any other shape —
+ * callers (mcpPlan.ts) refuse-and-conflict on "any other shape" rather
+ * than this function silently rendering nothing for it.
+ */
+export function codexBearerTokenEnvVar(def) {
+    const entries = Object.entries(def.headers ?? {});
+    if (entries.length !== 1)
+        return undefined;
+    const [key, value] = entries[0];
+    if (key !== "Authorization")
+        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. */
+export function renderServerSection(name, def) {
+    const lines = [`[${serverHeader(name)}]`];
+    if (def.transport === "stdio") {
+        if (def.command)
+            lines.push(`command = ${tomlString(def.command)}`);
+        if (def.args && def.args.length > 0)
+            lines.push(`args = ${tomlStringArray(def.args)}`);
+        if (def.env && def.env.length > 0)
+            lines.push(`env_vars = ${tomlStringArray(def.env)}`);
+    }
+    else {
+        if (def.url)
+            lines.push(`url = ${tomlString(def.url)}`);
+        const bearerEnvVar = codexBearerTokenEnvVar(def);
+        if (bearerEnvVar)
+            lines.push(`bearer_token_env_var = ${tomlString(bearerEnvVar)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 newLines = renderServerSection(name, def).split("\n");
+    if (existing) {
+        const lines = content.split("\n");
+        lines.splice(existing.start, existing.end - existing.start + 1, ...newLines);
+        return lines.join("\n");
+    }
+    const withoutTrailingNewlines = content.replace(/\n+$/, "");
+    return `${withoutTrailingNewlines}\n\n${newLines.join("\n")}\n`;
+}
+/**
+ * Removes an existing section (and one immediately-preceding blank line,
+ * if any, so repeated add/remove doesn't accumulate blank separators).
+ * No-op if the section doesn't exist — idempotent.
+ */
+export function removeSection(content, name) {
+    const header = serverHeader(name);
+    const existing = findSection(content, header);
+    if (!existing) {
+        return content;
+    }
+    const lines = content.split("\n");
+    let deleteStart = existing.start;
+    if (deleteStart > 0 && lines[deleteStart - 1].trim() === "") {
+        deleteStart -= 1;
+    }
+    lines.splice(deleteStart, existing.end - deleteStart + 1);
+    return lines.join("\n");
+}