agent-trellis 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Canonical schema types. These mirror the `.trellis/` directory layout
+ * documented in docs/architecture.md — this file is the source of truth
+ * for what a "canonical source" object looks like in memory; the YAML/MD
+ * files on disk are its serialization, not the other way around.
+ */
+export type Transport = "stdio" | "http" | "sse";
+export type AgentId = "claude-code" | "codex" | "kiro" | "pi";
+export declare const ALL_AGENTS: readonly AgentId[];
+/**
+ * Every scopable item (skill, subagent, memory entry, MCP server) defaults
+ * to "all four agents" when `scope` is omitted — sharing everywhere is the
+ * common case Trellis exists for; restricting to specific agents is the
+ * exception and must be declared explicitly. See docs/architecture.md
+ * "Private / agent-specific capabilities".
+ */
+export type Scope = AgentId[] | undefined;
+export declare function resolveScope(scope: Scope): readonly AgentId[];
+export interface McpServerDef {
+    transport: Transport;
+    /** stdio only */
+    command?: string;
+    args?: string[];
+    /** http/sse only */
+    url?: string;
+    /**
+     * http/sse only. Values are `${VAR}` references, same discipline as
+     * `env` — never a real value. Codex has no generic headers concept;
+     * only the single shape `{ Authorization: "Bearer ${VAR}" }` is
+     * expressible there (trellis-mcp-transport-auth design.md D4) — any
+     * other shape is a Codex-only conflict, not silently dropped.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Variable NAMES the server process needs, never values. See
+     * docs/research.md "Secrets" and schema/secrets.policy.example.yaml.
+     */
+    env?: string[];
+    /** Omit for "all agents" (the default). See `Scope`. */
+    agents?: Scope;
+}
+/**
+ * If set, every agent's adapter writes exactly ONE entry — this URL —
+ * instead of all N server definitions. What runs behind the URL (a
+ * self-hosted mcp-hub, a hosted mcp-router account, anything else
+ * speaking MCP over HTTP) is not Trellis's concern and not something
+ * adapter code branches on — there is no "engine" switch to maintain.
+ * See docs/architecture.md "MCP hub mode".
+ */
+export interface HubConfig {
+    url: string;
+}
+export interface McpConfig {
+    servers: Record<string, McpServerDef>;
+    /**
+     * Server names a host environment (e.g. mirasim) is known to inject at
+     * runtime. Checked against every server name Trellis would write per
+     * agent when `hub` is unset; against the single hub entry name only when
+     * `hub` is set (there's nothing else to collide) — see docs/research.md
+     * "Codex — three hard constraints" for why a same-name collision is not
+     * a soft failure on every agent.
+     */
+    knownHostInjected: string[];
+    /** Omit for direct mode (today's default: every agent gets all N server
+     * definitions written into its native config). See `HubConfig`. */
+    hub?: HubConfig;
+}
+export interface SkillRef {
+    name: string;
+    /** Absolute path to the skill's directory. Must contain `SKILL.md` — the
+     * filename is case-sensitive on at least one target agent (Codex). */
+    dir: string;
+    /**
+     * Omit for "all agents" (the default). Deliberately NOT read from
+     * SKILL.md's own frontmatter — Codex validates SKILL.md frontmatter
+     * against an allow-list of known keys and rejects unknown ones (see
+     * docs/research.md), so a Trellis-only field embedded there would break
+     * the skill on Codex specifically. Scope lives in `scope.yaml` instead,
+     * outside every artifact the agents themselves parse.
+     */
+    scope?: Scope;
+}
+export interface AgentProfile {
+    name: string;
+    /** Path to the profile's markdown file (Claude-style frontmatter today). */
+    file: string;
+    /**
+     * Omit for "all agents that support subagents" — today that's
+     * Claude Code only (see docs/research.md: Codex has no persistent
+     * subagent concept, Kiro/pi unconfirmed), so this is normally implicit,
+     * not something you write. Only set explicitly once more than one agent
+     * supports subagents and a profile should NOT go to all of them.
+     */
+    scope?: Scope;
+}
+export interface MemoryEntry {
+    name: string;
+    file: string;
+    /** Omit for "all agents" (the default). See `Scope`. */
+    scope?: Scope;
+}
+export interface SecretsPolicy {
+    allowedVars: string[];
+    rejectPatterns: RegExp[];
+    /**
+     * Absolute path to a dotenv-format file. When set, it is the SOLE
+     * source `resolveSecretEnv` consults for a declared name — never
+     * merged with `process.env` (src/lib/secretEnv.ts). Unset preserves
+     * ambient-`process.env` resolution, the only behavior that existed
+     * before this field did.
+     */
+    envFile?: string;
+}
+/**
+ * Result of one MCP stdio handshake probe (src/lib/mcpProbe.ts). `ok:
+ * false` always carries `error` — "configured but unreachable" and "never
+ * attempted" must stay distinguishable in an AgentSnapshot, so there's no
+ * silent-false path.
+ */
+export interface McpProbeResult {
+    ok: boolean;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    error?: string;
+    stderr?: string;
+}
+export interface AgentSnapshotSkillEntry {
+    name: string;
+    /** The skill's directory (what would be symlinked). */
+    dir: string;
+    /** Resolved realpath of `dir` — what duplication/drift comparison keys
+     * on (design.md D3), never `dir` itself. */
+    realDir: string;
+    isSymlink: boolean;
+    /** From `findSkillFile` — false means a same-named file exists with the
+     * wrong case and was NOT picked up by the target agent. */
+    caseCorrect: boolean;
+}
+export interface AgentSnapshotSkillRoot {
+    path: string;
+    isSymlink: boolean;
+    target?: string;
+    skills: AgentSnapshotSkillEntry[];
+}
+/**
+ * Every entry here came from an agent's own persisted, static config — a
+ * probe has no way to observe a host environment's runtime-only
+ * injection (e.g. mirasim's `-c` overrides never touch the config file
+ * probes read). The static-vs-known-host-injected classification spec.md
+ * describes is a comparison `trellis doctor` computes against
+ * `known_host_injected`, not a field a probe can set — see
+ * src/commands/doctor.ts's collision check.
+ */
+export interface AgentSnapshotMcpServer {
+    name: string;
+    transport?: Transport;
+    probe?: McpProbeResult;
+}
+export interface AgentSnapshotPathRef {
+    path: string;
+    isSymlink: boolean;
+    target?: string;
+}
+/**
+ * One shape for every agent (design.md D4) — agent-specific detail lives
+ * inside each probe(), never in this type, so comparison logic in
+ * src/commands/doctor.ts never special-cases an agent.
+ */
+export interface AgentSnapshot {
+    agent: AgentId;
+    present: boolean;
+    version?: string;
+    skillRoots: AgentSnapshotSkillRoot[];
+    mcpServers: AgentSnapshotMcpServer[];
+    instructionsFile?: AgentSnapshotPathRef;
+    subagentsDir?: AgentSnapshotPathRef & {
+        count: number;
+    };
+    /** Non-fatal issues hit while probing (e.g. a config file failed to
+     * parse) — a doctor finding, never silently swallowed. */
+    diagnostics: string[];
+}
+export interface CanonicalSource {
+    /**
+     * Global (`~/.trellis`) only for now. Project-local `.trellis/` and its
+     * merge-over-global precedence are an explicit non-goal until a later
+     * phase — see docs/roadmap.md. Don't build workspace resolution ahead of
+     * that decision.
+     */
+    instructionsFile: string;
+    skills: SkillRef[];
+    agents: AgentProfile[];
+    memories: MemoryEntry[];
+    mcp: McpConfig;
+    secretsPolicy: SecretsPolicy;
+    /** e.g. a `scope.yaml` entry naming a skill/agent/memory that doesn't
+     * exist — recorded, not a load failure. See `loadCanonicalSource`. */
+    diagnostics: string[];
+}

package/dist/core/types.js

@@ -0,0 +1,15 @@
+/**
+ * Canonical schema types. These mirror the `.trellis/` directory layout
+ * documented in docs/architecture.md — this file is the source of truth
+ * for what a "canonical source" object looks like in memory; the YAML/MD
+ * files on disk are its serialization, not the other way around.
+ */
+export const ALL_AGENTS = [
+    "claude-code",
+    "codex",
+    "kiro",
+    "pi",
+];
+export function resolveScope(scope) {
+    return scope ?? ALL_AGENTS;
+}

package/dist/lib/dirEquals.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Byte-for-byte directory content comparison (trellis-cli-migrate design.md
+ * D2) — "already migrated, safe to skip" vs. "a real conflict" is decided
+ * by this, not by name/mtime/hash-shortcut. Same set of relative file
+ * paths, same bytes per file; anything else is unequal.
+ */
+export declare function dirContentsEqual(a: string, b: string): boolean;

package/dist/lib/dirEquals.js

@@ -0,0 +1,39 @@
+/**
+ * Byte-for-byte directory content comparison (trellis-cli-migrate design.md
+ * D2) — "already migrated, safe to skip" vs. "a real conflict" is decided
+ * by this, not by name/mtime/hash-shortcut. Same set of relative file
+ * paths, same bytes per file; anything else is unequal.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+function listFilesRecursive(dir) {
+    const results = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current)) {
+            const full = join(current, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else {
+                results.push(relative(dir, full));
+            }
+        }
+    };
+    walk(dir);
+    return results.sort();
+}
+export function dirContentsEqual(a, b) {
+    const filesA = listFilesRecursive(a);
+    const filesB = listFilesRecursive(b);
+    if (filesA.length !== filesB.length)
+        return false;
+    for (let i = 0; i < filesA.length; i++) {
+        if (filesA[i] !== filesB[i])
+            return false;
+    }
+    for (const rel of filesA) {
+        if (!readFileSync(join(a, rel)).equals(readFileSync(join(b, rel))))
+            return false;
+    }
+    return true;
+}

package/dist/lib/envVarNames.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Extracts the environment-variable *names* an agent's real MCP config
+ * declares — not a general parser for either format, just the one shape
+ * each needs (trellis-secrets-audit-p3 design.md D1). Read-only: unlike
+ * src/lib/tomlSection.ts (a write-path module with a different job),
+ * there is no round-trip-fidelity concern here, but a full parser is
+ * still more machinery than this one narrow extraction needs.
+ */
+import type { McpServerDef } from "../core/types.js";
+/** Every `${NAME}` occurrence in a string — a header value can in
+ * principle reference more than one name (trellis-mcp-transport-auth
+ * design.md D6), same extraction `env`'s single-name-per-value case
+ * already needed, just generalized. */
+export declare function extractTemplateVarNames(value: string): string[];
+/** `env` names ∪ names embedded in `headers` values — what both the
+ * secrets-audit `missing-env-value` check and Kiro's approved-env-vars
+ * list need to know a canonical server references (trellis-mcp-
+ * transport-auth design.md D6): Kiro's own `${VAR}` substitution
+ * recurses into `headers` the same as `env`, so both features need the
+ * same answer to "what names does this def reference," not two
+ * separately-maintained collections. */
+export declare function declaredEnvNames(def: McpServerDef): string[];
+/** Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object keys plus names embedded in `headers` object
+ * *values* (unlike `env`, a header's key is an arbitrary header name,
+ * not a variable name — the variable name lives inside the `${...}`
+ * value). Returns `[]` (not a throw) on invalid JSON; that's a
+ * diagnostic for a different command, not this extractor's job. */
+export declare function extractJsonEnvVarNames(content: string): string[];
+/** Codex's config is TOML. The shapes audit needs: every `env_vars = [...]`
+ * line's quoted string contents, plus a `bearer_token_env_var = "VAR"`
+ * line's bare name (a name directly, not a `${VAR}` template — Codex's
+ * own field holds a name, same as `env_vars`). A five-line regex each,
+ * not a parser (design.md D1). */
+export declare function extractTomlEnvVarNames(content: string): string[];

package/dist/lib/envVarNames.js

@@ -0,0 +1,79 @@
+/**
+ * Extracts the environment-variable *names* an agent's real MCP config
+ * declares — not a general parser for either format, just the one shape
+ * each needs (trellis-secrets-audit-p3 design.md D1). Read-only: unlike
+ * src/lib/tomlSection.ts (a write-path module with a different job),
+ * there is no round-trip-fidelity concern here, but a full parser is
+ * still more machinery than this one narrow extraction needs.
+ */
+const TEMPLATE_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Every `${NAME}` occurrence in a string — a header value can in
+ * principle reference more than one name (trellis-mcp-transport-auth
+ * design.md D6), same extraction `env`'s single-name-per-value case
+ * already needed, just generalized. */
+export function extractTemplateVarNames(value) {
+    return [...value.matchAll(TEMPLATE_VAR_RE)].map((m) => m[1]);
+}
+/** `env` names ∪ names embedded in `headers` values — what both the
+ * secrets-audit `missing-env-value` check and Kiro's approved-env-vars
+ * list need to know a canonical server references (trellis-mcp-
+ * transport-auth design.md D6): Kiro's own `${VAR}` substitution
+ * recurses into `headers` the same as `env`, so both features need the
+ * same answer to "what names does this def reference," not two
+ * separately-maintained collections. */
+export function declaredEnvNames(def) {
+    const names = new Set(def.env ?? []);
+    for (const value of Object.values(def.headers ?? {})) {
+        for (const name of extractTemplateVarNames(value))
+            names.add(name);
+    }
+    return [...names];
+}
+/** Claude Code / Kiro's config is real JSON — parse it and walk each
+ * server's `env` object keys plus names embedded in `headers` object
+ * *values* (unlike `env`, a header's key is an arbitrary header name,
+ * not a variable name — the variable name lives inside the `${...}`
+ * value). Returns `[]` (not a throw) on invalid JSON; that's a
+ * diagnostic for a different command, not this extractor's job. */
+export function extractJsonEnvVarNames(content) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const server of Object.values(parsed.mcpServers ?? {})) {
+        names.push(...Object.keys(server.env ?? {}));
+        for (const value of Object.values(server.headers ?? {})) {
+            names.push(...extractTemplateVarNames(value));
+        }
+    }
+    return names;
+}
+const ENV_VARS_LINE_RE = /^\s*env_vars\s*=\s*\[(.*)\]\s*$/;
+const BEARER_TOKEN_ENV_VAR_LINE_RE = /^\s*bearer_token_env_var\s*=\s*"([^"]*)"\s*$/;
+const QUOTED_STRING_RE = /"((?:[^"\\]|\\.)*)"/g;
+/** Codex's config is TOML. The shapes audit needs: every `env_vars = [...]`
+ * line's quoted string contents, plus a `bearer_token_env_var = "VAR"`
+ * line's bare name (a name directly, not a `${VAR}` template — Codex's
+ * own field holds a name, same as `env_vars`). A five-line regex each,
+ * not a parser (design.md D1). */
+export function extractTomlEnvVarNames(content) {
+    const names = [];
+    for (const line of content.split("\n")) {
+        const envVarsMatch = ENV_VARS_LINE_RE.exec(line);
+        if (envVarsMatch) {
+            for (const stringMatch of envVarsMatch[1].matchAll(QUOTED_STRING_RE)) {
+                names.push(stringMatch[1]);
+            }
+            continue;
+        }
+        const bearerMatch = BEARER_TOKEN_ENV_VAR_LINE_RE.exec(line);
+        if (bearerMatch) {
+            names.push(bearerMatch[1]);
+        }
+    }
+    return names;
+}

package/dist/lib/fsIdentity.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Filesystem identity by realpath, never by string path or content hash.
+ * See design.md D3 (openspec/changes/trellis-doctor-p0): two physical
+ * copies of identical content are NOT the same thing to an agent's own
+ * discovery logic (Codex, pi both dedup this way independently) — only a
+ * symlink to the same target is.
+ */
+export declare function isSymlinkTo(path: string, target: string): boolean;
+/**
+ * Groups paths by realpath. Two ordinary directories with byte-identical
+ * content but no symlink between them land in separate buckets — that's
+ * the point, not a bug (see D3). A path that can't be resolved (broken
+ * symlink, missing) is bucketed on its own literal path instead, so it's
+ * never silently dropped from the result.
+ */
+export declare function realpathDedupe(paths: string[]): Map<string, string[]>;

package/dist/lib/fsIdentity.js

@@ -0,0 +1,53 @@
+/**
+ * Filesystem identity by realpath, never by string path or content hash.
+ * See design.md D3 (openspec/changes/trellis-doctor-p0): two physical
+ * copies of identical content are NOT the same thing to an agent's own
+ * discovery logic (Codex, pi both dedup this way independently) — only a
+ * symlink to the same target is.
+ */
+import { lstatSync, realpathSync } from "node:fs";
+export function isSymlinkTo(path, target) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink()) {
+        return false;
+    }
+    try {
+        return realpathSync(path) === realpathSync(target);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Groups paths by realpath. Two ordinary directories with byte-identical
+ * content but no symlink between them land in separate buckets — that's
+ * the point, not a bug (see D3). A path that can't be resolved (broken
+ * symlink, missing) is bucketed on its own literal path instead, so it's
+ * never silently dropped from the result.
+ */
+export function realpathDedupe(paths) {
+    const buckets = new Map();
+    for (const path of paths) {
+        let real;
+        try {
+            real = realpathSync(path);
+        }
+        catch {
+            real = path;
+        }
+        const bucket = buckets.get(real);
+        if (bucket) {
+            bucket.push(path);
+        }
+        else {
+            buckets.set(real, [path]);
+        }
+    }
+    return buckets;
+}

package/dist/lib/mcpProbe.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP stdio handshake probe: spawn, send `initialize`, resolve on the
+ * first `id: 1` response or process exit, whichever comes first. This is a
+ * direct port of the probe script used repeatedly by hand during this
+ * project's research (docs/research.md) — see design.md D1 for why this is
+ * hand-rolled JSON-RPC rather than `@modelcontextprotocol/sdk`'s client.
+ */
+import type { McpProbeResult } from "../core/types.js";
+export interface McpProbeTarget {
+    transport: "stdio" | "http";
+    command?: string;
+    args?: string[];
+}
+export declare function probeMcpServer(def: McpProbeTarget, env: NodeJS.ProcessEnv, timeoutMs?: number): Promise<McpProbeResult>;

package/dist/lib/mcpProbe.js

@@ -0,0 +1,96 @@
+/**
+ * MCP stdio handshake probe: spawn, send `initialize`, resolve on the
+ * first `id: 1` response or process exit, whichever comes first. This is a
+ * direct port of the probe script used repeatedly by hand during this
+ * project's research (docs/research.md) — see design.md D1 for why this is
+ * hand-rolled JSON-RPC rather than `@modelcontextprotocol/sdk`'s client.
+ */
+import { spawn } from "node:child_process";
+export function probeMcpServer(def, env, timeoutMs = 10_000) {
+    if (def.transport !== "stdio" || !def.command) {
+        return Promise.resolve({
+            ok: false,
+            error: `probeMcpServer only handshakes stdio servers with a command (got transport=${def.transport})`,
+        });
+    }
+    return new Promise((resolve) => {
+        const child = spawn(def.command, def.args ?? [], { env });
+        let settled = false;
+        let stdoutBuf = "";
+        let stderrBuf = "";
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.stdout?.removeAllListeners("data");
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // already exited
+            }
+            // A wrapper (npx, a shell shim) can absorb SIGTERM without forwarding
+            // it to the real server it launched. Escalate once, short grace
+            // period, so a probe never leaves a live process behind.
+            setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // already exited
+                }
+            }, 500).unref();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ ok: false, error: `no response within ${timeoutMs}ms`, stderr: stderrBuf || undefined });
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdoutBuf += chunk.toString("utf-8");
+            const lines = stdoutBuf.split("\n");
+            stdoutBuf = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(trimmed);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.id === 1) {
+                    if (msg.error) {
+                        finish({ ok: false, error: JSON.stringify(msg.error), stderr: stderrBuf || undefined });
+                    }
+                    else {
+                        finish({ ok: true, serverInfo: msg.result?.serverInfo, stderr: stderrBuf || undefined });
+                    }
+                    return;
+                }
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrBuf += chunk.toString("utf-8");
+        });
+        child.on("error", (err) => {
+            finish({ ok: false, error: err.message });
+        });
+        child.on("exit", (code) => {
+            finish({ ok: false, error: `process exited (code ${code}) before responding`, stderr: stderrBuf || undefined });
+        });
+        const request = {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-06-18",
+                capabilities: {},
+                clientInfo: { name: "trellis-doctor", version: "0.0.0" },
+            },
+        };
+        child.stdin?.write(`${JSON.stringify(request)}\n`);
+    });
+}

package/dist/lib/probeCommon.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { AgentSnapshotPathRef, AgentSnapshotSkillRoot } from "../core/types.js";
+export declare function pathRef(path: string): AgentSnapshotPathRef | undefined;
+/**
+ * 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 declare function scanSkillRoot(rootPath: string): AgentSnapshotSkillRoot | undefined;
+export declare function readJsonFile<T>(path: string): T | undefined;
+export declare function countDirEntries(dir: string): number;
+/**
+ * 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 declare function resolveEnvRefs(envSpec: Record<string, string> | string[] | undefined, base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;