agent-trellis 0.2.0 → 0.4.0

package/dist/commands/skill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import type { AgentId } from "../core/types.js";
+export interface SkillListEntry {
+    name: string;
+    scope: readonly AgentId[];
+}
+export declare function collectSkillList(homeDir?: string): SkillListEntry[];
+export declare function runSkillList(opts?: {
+    homeDir?: string;
+    json?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillAddAction = "create" | "already-present" | "conflict" | "invalid-source";
+export interface SkillAddPlan {
+    name: string;
+    action: SkillAddAction;
+    detail: string;
+    sourceDir?: string;
+}
+export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
+export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string): void;
+export declare function runSkillAdd(name: string, fromPath: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillRemoveAction = "removed" | "not-found";
+export interface SkillRemovePlan {
+    name: string;
+    action: SkillRemoveAction;
+}
+export declare function collectSkillRemovePlan(name: string, homeDir?: string): SkillRemovePlan;
+export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string): void;
+export declare function runSkillRemove(name: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};

package/dist/commands/skill.js

@@ -0,0 +1,104 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { findSkillFile } from "../lib/skillFile.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
+export function collectSkillList(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return canonical.skills.map((skill) => ({
+        name: skill.name,
+        scope: resolveScope(skill.scope, canonical.managedAgents),
+    }));
+}
+export function runSkillList(opts = {}) {
+    const entries = collectSkillList(opts.homeDir ?? homedir());
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    else if (entries.length === 0) {
+        console.log("No skills in canonical source yet.");
+    }
+    else {
+        for (const { name, scope } of entries) {
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+        }
+    }
+    return { exitCode: 0 };
+}
+export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    const skillFile = findSkillFile(fromPath);
+    if (!skillFile) {
+        return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
+    }
+    if (!skillFile.caseCorrect) {
+        return { name, action: "invalid-source", detail: `${fromPath} has skill.md, not case-correct SKILL.md — fix the case first` };
+    }
+    const canonicalDir = join(homeDir, ".trellis", "skills", name);
+    switch (decideDirImport(fromPath, canonicalDir)) {
+        case "create":
+            return { name, action: "create", detail: `will copy from ${fromPath}`, sourceDir: fromPath };
+        case "already-present":
+            return { name, action: "already-present", detail: "canonical content is already byte-identical" };
+        case "conflict":
+            return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+    }
+}
+export function applySkillAddPlan(plan, homeDir = homedir()) {
+    if (plan.action !== "create" || !plan.sourceDir)
+        return;
+    const dest = join(homeDir, ".trellis", "skills", plan.name);
+    mkdirSync(dest, { recursive: true });
+    cpSync(plan.sourceDir, dest, { recursive: true });
+}
+export function runSkillAdd(name, fromPath, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    if (!opts.dryRun && plan.action === "create") {
+        applySkillAddPlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+    }
+    return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
+}
+export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    const dir = join(homeDir, ".trellis", "skills", name);
+    return { name, action: existsSync(dir) ? "removed" : "not-found" };
+}
+export function applySkillRemovePlan(plan, homeDir = homedir()) {
+    if (plan.action !== "removed")
+        return;
+    rmSync(join(homeDir, ".trellis", "skills", plan.name), { recursive: true, force: true });
+}
+export function runSkillRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillRemovePlan(name, homeDir);
+    if (!opts.dryRun) {
+        applySkillRemovePlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else if (plan.action === "not-found") {
+        console.error(`"${name}" is not a canonical skill — nothing to remove.`);
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}removed skill "${name}" from canonical source.`);
+    }
+    return { exitCode: plan.action === "not-found" ? 1 : 0 };
+}

package/dist/core/adapter.d.ts

@@ -20,14 +20,18 @@ export interface AdapterPlanItem {
     /**
      * "create" also covers repair (wrong symlink target, or an MCP server
      * definition that differs from canonical); "remove" is the delete half
-     * for skills/instructions — a Trellis-managed symlink whose canonical
-     * entry is gone or was just scoped away from this agent. MCP server
-     * items never use "remove" (see `kind: "mcp"` below — no ownership
-     * marker exists yet to make that provably safe, trellis-mcp-sync-p2
-     * design.md D7). "conflict" is either a real, non-symlink path
-     * occupying a spot Trellis would otherwise touch, or an MCP server
-     * refused for a collision/secrets-guard reason — reported, never acted
-     * on. See `plan()`'s doc below.
+     * for skills/instructions (a Trellis-managed symlink whose canonical
+     * entry is gone or was just scoped away from this agent) and, since
+     * trellis-mcp-lifecycle-parity, for MCP servers too — but only when
+     * `src/lib/mcpOwnership.ts`'s ledger proves the agent's current native
+     * entry is still exactly what Trellis itself last wrote there
+     * (mcpPlan.ts's own D7 reasoning: a bare TOML/JSON key has no ownership
+     * marker on its own, so this ledger is what makes removal provably
+     * safe instead of guessing). A name whose native content has since
+     * been hand-edited is left alone, never removed. "conflict" is either
+     * a real, non-symlink path occupying a spot Trellis would otherwise
+     * touch, or an MCP server refused for a collision/secrets-guard
+     * reason — reported, never acted on. See `plan()`'s doc below.
      */
     action: "create" | "remove" | "conflict";
     /** Lets `trellis sync skills` / `trellis sync instructions` /
@@ -64,6 +68,12 @@ export interface AdapterPlanItem {
         name: string;
         def: McpServerDef;
     };
+    /** Only set (and only meaningful) when `kind === "mcp"` and
+     * `action === "remove"`: the server name to delete from `target` via
+     * that agent's own mechanism. */
+    mcpRemove?: {
+        name: string;
+    };
     /** Only set (and only meaningful) when `kind === "kiro-approved-env-vars"`
      * and `action === "create"`: the full, already-deduplicated array to
      * write as `kiroAgent.mcpApprovedEnvVars` — a union of whatever was

package/dist/core/canonical.d.ts

@@ -4,7 +4,31 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { CanonicalSource } from "./types.js";
+import type { CanonicalSource, McpServerDef } from "./types.js";
+/**
+ * The on-disk shape for one server entry — `static_env` (snake_case, like
+ * every other multi-word key across `.trellis/*.yaml`) is translated to
+ * `McpServerDef.staticEnv` (camelCase) below; every other field happens
+ * to already be a single word, so no server-def field needed this
+ * treatment before (trellis-mcp-static-env-and-disabled-servers).
+ */
+type McpServerDefYaml = Omit<McpServerDef, "staticEnv"> & {
+    static_env?: Record<string, string>;
+};
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written YAML never gets a literal `null`
+ * for an omitted optional. */
+export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;
+export type ServersYamlWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function upsertServerYaml(path: string, name: string, def: McpServerDef): ServersYamlWriteResult;
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export declare function removeServerYaml(path: string, name: string): ServersYamlWriteResult;
 /**
  * `homeDir` defaults to the real `~` and is only ever overridden for tests
  * and `scripts/sandbox.sh` — the same seam P0's probes use
@@ -14,3 +38,4 @@ import type { CanonicalSource } from "./types.js";
  * parameter does not weaken.
  */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
+export {};

package/dist/core/canonical.js

@@ -4,11 +4,29 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { isMap, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS } from "./types.js";
+function fromServerDefYaml(def) {
+    const { static_env, ...rest } = def;
+    return static_env ? { ...rest, staticEnv: static_env } : rest;
+}
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written YAML never gets a literal `null`
+ * for an omitted optional. */
+export function toServerDefYaml(def) {
+    const { staticEnv, ...rest } = def;
+    const out = { ...rest };
+    if (staticEnv)
+        out.static_env = staticEnv;
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
 }
@@ -58,12 +76,72 @@ function loadServersYaml(path) {
         return { servers: {}, knownHostInjected: [] };
     }
     const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
     return {
-        servers: parsed.servers ?? {},
+        servers,
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
     };
 }
+/**
+ * Writes or replaces one server entry in `servers.yaml`, preserving
+ * every other entry's and comment's exact formatting (trellis-
+ * canonical-cli-crud design.md D3) — a `Document`-based edit
+ * (`setIn`), never `parse` + rebuild + `stringify`, which would
+ * re-serialize the whole file and lose anything hand-authored outside
+ * the touched entry. Refuses (no write) if the file doesn't exist yet
+ * (run `trellis init` first) or fails to parse.
+ */
+/**
+ * `trellis init`'s starter `servers.yaml` writes `servers: {}` — an empty
+ * flow-style map, since there's nothing to indent yet. `Document#setIn`
+ * inserting into an *existing* flow map keeps rendering it as flow, so
+ * the first `mcp add`/`migrate --only mcp` onto a fresh file — and every
+ * one after it — would render as one unreadable line (found via actually
+ * running the CLI against a fresh `init`, not by inspection). Forcing the
+ * touched map, and the newly-set entry's own map, to block style is a
+ * one-line, local fix — it never touches any sibling entry's own style,
+ * so a file someone deliberately kept flow-style elsewhere is untouched.
+ */
+function forceBlockStyle(node) {
+    if (isMap(node)) {
+        node.flow = false;
+    }
+}
+export function upsertServerYaml(path, name, def) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.setIn(["servers", name], toServerDefYaml(def));
+    forceBlockStyle(doc.get("servers", true));
+    forceBlockStyle(doc.getIn(["servers", name], true));
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
+/** Inverse of `upsertServerYaml` — same preservation guarantee, same
+ * refusal posture on a missing/unparseable file. */
+export function removeServerYaml(path, name) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    doc.deleteIn(["servers", name]);
+    writeFileSync(path, doc.toString());
+    return { ok: true };
+}
 function loadSecretsPolicyYaml(path, homeDir) {
     if (!existsSync(path)) {
         return { allowedVars: [], rejectPatterns: [] };

package/dist/core/types.d.ts

@@ -44,6 +44,23 @@ export interface McpServerDef {
      * docs/research.md "Secrets" and schema/secrets.policy.example.yaml.
      */
     env?: string[];
+    /**
+     * Literal, non-secret values written into the agent's config verbatim
+     * — distinct from `env`'s names-only, resolved-at-runtime contract.
+     * Still scanned against `reject_patterns` like every other literal
+     * field (trellis-mcp-static-env-and-disabled-servers design.md D2):
+     * this is for values that were never secrets (an email address, an
+     * environment tag), not an escape hatch for real credentials.
+     */
+    staticEnv?: Record<string, string>;
+    /**
+     * Defaults to `true`. `false` keeps the definition in canonical
+     * without writing it to any agent — matches a real host config's own
+     * "defined but currently off" state (e.g. Codex's `enabled = false`)
+     * that omitting the definition entirely can't represent, since that
+     * would also throw away the definition itself.
+     */
+    enabled?: boolean;
     /** Omit for "all agents" (the default). See `Scope`. */
     agents?: Scope;
 }

package/dist/lib/deepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/lib/deepEqual.js

@@ -0,0 +1,26 @@
+/**
+ * Structural equality for plain JSON-shaped values — shared by every
+ * "does this already match what Trellis would write/has written"
+ * comparison (jsonMcp.ts's create/remove decisions, migrate-in's
+ * conflict detection) so they can't silently drift apart into two
+ * different notions of "equal."
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}

package/dist/lib/dirEquals.d.ts

@@ -5,3 +5,12 @@
  * paths, same bytes per file; anything else is unequal.
  */
 export declare function dirContentsEqual(a: string, b: string): boolean;
+export type DirImportDecision = "create" | "already-present" | "conflict";
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export declare function decideDirImport(sourceDir: string, canonicalDir: string): DirImportDecision;

package/dist/lib/dirEquals.js

@@ -4,7 +4,7 @@
  * 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 { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 function listFilesRecursive(dir) {
     const results = [];
@@ -37,3 +37,17 @@ export function dirContentsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Shared create/already-present/conflict decision for copying a real
+ * directory into a canonical destination — used by both `migrate`'s
+ * own skill planning and `trellis skill add` (trellis-canonical-cli-crud
+ * design.md D2), so the two never silently drift apart on what counts
+ * as "safe to skip" vs. "a real conflict."
+ */
+export function decideDirImport(sourceDir, canonicalDir) {
+    if (!existsSync(canonicalDir))
+        return "create";
+    if (dirContentsEqual(sourceDir, canonicalDir))
+        return "already-present";
+    return "conflict";
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 type { McpServerDef } from "../core/types.js";
+export interface McpMigrateEntry {
+    name: string;
+    def: McpServerDef;
+}
+export interface McpMigrateUnsupported {
+    name: string;
+    reason: string;
+}
+export interface McpMigrateReadResult {
+    entries: McpMigrateEntry[];
+    unsupported: McpMigrateUnsupported[];
+}
+export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
+export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
+export interface CodexMcpEntryRich {
+    name: string;
+    enabled: boolean;
+    transport: {
+        type: string;
+        command?: string;
+        args?: string[];
+        env_vars?: string[];
+        /** Remote-transport fields. Confirmed by running the real,
+         * locally-installed `codex-cli 0.154.0` against a hand-written
+         * `url`-only server and a `url` + `bearer_token_env_var` server: the
+         * type string is `"streamable_http"` (not `"http"`), and the three
+         * `*headers*` fields come back `null` when unused. Codex's own
+         * config.toml schema (`tomlSection.ts`'s `renderServerSection`) has
+         * no way to distinguish `http` from `sse` at all — both render
+         * identically — so there is no lossy guess in always reading a
+         * remote entry back as `"http"`; that distinction was never stored. */
+        url?: string;
+        bearer_token_env_var?: string | null;
+        http_headers?: unknown;
+        env_http_headers?: unknown;
+        http_headers_helper?: unknown;
+    };
+}
+/**
+ * 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 declare function buildCodexMcpReadResult(mcpEntries: CodexMcpEntryRich[], tomlContent: string | undefined): McpMigrateReadResult;
+/**
+ * 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 declare function readCodexMcpDefs(homeDir: string): McpMigrateReadResult;