agent-trellis 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,150 @@
+/**
+ * `trellis init` — bootstraps a minimal, valid `~/.trellis/` if one
+ * doesn't already exist, per-file (never overwrites an existing file;
+ * fills in only what's missing — trellis-cli-init). `loadCanonicalSource`
+ * only actually requires the `.trellis/` directory itself to exist; this
+ * command exists because an empty directory gives a new user nothing to
+ * act on.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import * as claudeCodeProbe from "../probes/claude-code.js";
+import * as codexProbe from "../probes/codex.js";
+import * as kiroProbe from "../probes/kiro.js";
+import * as piProbe from "../probes/pi.js";
+import { ALL_AGENTS } from "../core/types.js";
+/** Exported so `migrate` can byte-compare canonical `agents.md` against
+ * this exact string (design.md D3, trellis-cli-migrate) rather than
+ * retyping an equivalent one that could silently drift from this. */
+export const AGENTS_MD_TEMPLATE = `# Shared instructions
+
+Write what every agent should know here — communication preferences,
+project conventions, anything you'd otherwise repeat per agent.
+
+Already using Claude Code, Codex, Kiro, or pi? \`trellis migrate --from
+<agent>\` imports its real instructions and skills instead of starting
+from this placeholder.
+`;
+/**
+ * `known_host_injected` starts empty deliberately (design.md D3, D1):
+ * seeding it with any specific runtime's connector names (e.g. this
+ * project's own mirasim) would be actively wrong on a machine without
+ * that runtime. \`trellis doctor\`'s collision check reads this file's
+ * real value once it exists, so leaving it empty is not just a stub —
+ * it accurately means "nothing known to be host-injected here yet."
+ */
+function serversYamlTemplate() {
+    return `# See schema/servers.example.yaml for the full documented shape
+# (transports, env references, agent scoping, hub mode).
+servers: {}
+
+# Names a host environment (e.g. mirasim) injects into an agent process
+# at runtime. A same-name static definition here would collide with it —
+# on Codex that crashes the whole process at startup, not just that one
+# server. Leave empty until you know what your own host injects; run
+# \`trellis doctor\` to find out. See docs/research.md "Codex — three
+# hard constraints".
+known_host_injected: []
+`;
+}
+/**
+ * Reads schema/secrets.policy.example.yaml's own \`reject_patterns\`
+ * rather than retyping them — those patterns are reviewed, shipped
+ * content; duplicating them here would let the two drift (design.md D1).
+ */
+function secretsPolicyYamlTemplate() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const examplePath = join(here, "..", "..", "schema", "secrets.policy.example.yaml");
+    const parsed = parseYaml(readFileSync(examplePath, "utf-8"));
+    const patterns = parsed.reject_patterns ?? [];
+    const patternLines = patterns.map((p) => `  - '${p}'`).join("\n");
+    return `# See schema/secrets.policy.example.yaml for the full documented shape
+# (env_file, what it does and doesn't protect).
+allowed_vars: []
+
+# Seeded from schema/secrets.policy.example.yaml's own reviewed list —
+# generic credential shapes, not specific to any one project.
+reject_patterns:
+${patternLines}
+`;
+}
+/**
+ * Trellis never spawns an installer itself (global package installs are
+ * exactly the kind of irreversible, system-wide action that needs the
+ * user's own explicit "yes", not a silent trellis-init side effect) —
+ * these are printed as a pointer only. Verified against each project's
+ * own current install docs, same discipline as everything else here.
+ */
+export const INSTALL_HINTS = {
+    "claude-code": "npm install -g @anthropic-ai/claude-code",
+    codex: "npm install -g @openai/codex",
+    kiro: "https://kiro.dev/downloads/",
+    pi: "npm install -g @earendil-works/pi-coding-agent",
+};
+function ensureFile(path, template) {
+    if (existsSync(path)) {
+        return { path, action: "already-present" };
+    }
+    writeFileSync(path, template);
+    return { path, action: "create" };
+}
+export async function collectInitReport(homeDir = homedir()) {
+    const root = join(homeDir, ".trellis");
+    mkdirSync(root, { recursive: true });
+    mkdirSync(join(root, "mcp"), { recursive: true });
+    mkdirSync(join(root, "skills"), { recursive: true });
+    mkdirSync(join(root, "agents"), { recursive: true });
+    mkdirSync(join(root, "memories"), { recursive: true });
+    const files = [
+        ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE),
+        ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate()),
+        ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate()),
+    ];
+    const probes = [
+        { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir) },
+        { agent: "codex", run: () => codexProbe.probe(homeDir) },
+        { agent: "kiro", run: () => kiroProbe.probe(homeDir) },
+        { agent: "pi", run: () => piProbe.probe(homeDir) },
+    ];
+    const settled = await Promise.allSettled(probes.map((p) => p.run()));
+    const agents = settled.map((result, index) => {
+        const agent = ALL_AGENTS[index];
+        const present = result.status === "fulfilled" && result.value.present;
+        const message = present
+            ? `${agent} is present — run \`trellis migrate --from ${agent}\` to import its skills and instructions`
+            : `${agent} — not detected on this machine. Install: ${INSTALL_HINTS[agent]}`;
+        return { agent, present, message };
+    });
+    return { files, agents };
+}
+export async function runInit(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const report = await collectInitReport(homeDir);
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report);
+    }
+    return { exitCode: 0 };
+}
+function printReport(report) {
+    const created = report.files.filter((f) => f.action === "create");
+    if (created.length === 0) {
+        console.log("~/.trellis already fully initialized — nothing to create.");
+    }
+    else {
+        console.log(`Created ${created.length} file(s):`);
+        for (const f of created)
+            console.log(`  - ${f.path}`);
+    }
+    const alreadyPresent = report.files.filter((f) => f.action === "already-present");
+    for (const f of alreadyPresent)
+        console.log(`  - ${f.path} (already present, left untouched)`);
+    console.log("");
+    for (const a of report.agents)
+        console.log(a.message);
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `trellis mcp sync` — loads canonical once, runs every present agent's
+ * adapter, applies only the "mcp" slice of its plan, and reports what
+ * happened. Same create/repair/refuse shape as `src/commands/sync.ts`,
+ * kept as a separate command because MCP has no ownership marker for
+ * automatic removal yet (trellis-mcp-sync-p2 design.md D7) — folding it
+ * into bare `trellis sync` would blur that distinction.
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId } from "../core/types.js";
+export interface RunMcpSyncOptions {
+    json?: boolean;
+    /** Same test/sandbox-only seam as `RunSyncOptions.homeDir` — never a CLI
+     * flag. See docs/architecture.md's testing philosophy. */
+    homeDir?: string;
+}
+export interface AgentMcpSyncReport {
+    agent: AgentId;
+    present: boolean;
+    items: AdapterPlanItem[];
+}
+export interface McpSyncReport {
+    reports: AgentMcpSyncReport[];
+}
+export declare function collectMcpSyncReport(opts?: RunMcpSyncOptions): Promise<McpSyncReport>;
+export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/mcp.js

@@ -0,0 +1,70 @@
+/**
+ * `trellis mcp sync` — loads canonical once, runs every present agent's
+ * adapter, applies only the "mcp" slice of its plan, and reports what
+ * happened. Same create/repair/refuse shape as `src/commands/sync.ts`,
+ * kept as a separate command because MCP has no ownership marker for
+ * automatic removal yet (trellis-mcp-sync-p2 design.md D7) — folding it
+ * into bare `trellis sync` would blur that distinction.
+ */
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
+import { CodexAdapter } from "../adapters/codex.js";
+import { KiroAdapter } from "../adapters/kiro.js";
+import { PiAdapter } from "../adapters/pi.js";
+function buildAdapters(homeDir) {
+    return [new ClaudeCodeAdapter(homeDir), new CodexAdapter(homeDir), new KiroAdapter(homeDir), new PiAdapter(homeDir)];
+}
+export async function collectMcpSyncReport(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const canonical = loadCanonicalSource(homeDir);
+    const reports = [];
+    for (const adapter of buildAdapters(homeDir)) {
+        const probeResult = await adapter.probe();
+        if (!probeResult.present) {
+            reports.push({ agent: adapter.id, present: false, items: [] });
+            continue;
+        }
+        const items = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
+        await adapter.apply(items);
+        reports.push({ agent: adapter.id, present: true, items });
+    }
+    return { reports };
+}
+export async function runMcpSync(opts = {}) {
+    let report;
+    try {
+        report = await collectMcpSyncReport(opts);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report);
+    }
+    const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+function printReport(report) {
+    for (const { agent, present, items } of report.reports) {
+        if (!present) {
+            console.log(`—  ${agent} (not installed)`);
+            continue;
+        }
+        const created = items.filter((i) => i.action === "create");
+        const conflicts = items.filter((i) => i.action === "conflict");
+        if (created.length === 0 && conflicts.length === 0) {
+            console.log(`✅ ${agent} — already in sync`);
+            continue;
+        }
+        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+        console.log(`${icon} ${agent} — ${created.length} created/updated, ${conflicts.length} conflict(s)`);
+        for (const item of [...created, ...conflicts]) {
+            console.log(`   - [${item.action}] ${item.description}`);
+        }
+    }
+}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `trellis migrate --from <agent>` — imports an existing agent's real
+ * skills and instructions into canonical source (trellis-cli-migrate).
+ * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
+ * plan-then-apply split every adapter already uses.
+ */
+import type { AgentId } from "../core/types.js";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "already-migrated" | "conflict";
+export interface MigratePlanItem {
+    kind: "skill" | "instructions";
+    name: string;
+    action: MigrateAction;
+    detail: string;
+    /** Only set when action === "create"; consumed by applyMigratePlan. */
+    sourceDir?: string;
+    sourceContent?: string;
+}
+export interface MigratePlan {
+    agent: AgentId;
+    present: boolean;
+    items: MigratePlanItem[];
+}
+export declare function collectMigratePlan(agent: AgentId, homeDir?: string): Promise<MigratePlan>;
+export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string): void;
+export interface RunMigrateOptions {
+    from?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Defaults to the real `~`; overridable for tests only. */
+    homeDir?: string;
+}
+export declare function runMigrate(opts?: RunMigrateOptions): Promise<{
+    exitCode: number;
+}>;
+/** Exported so `onboard` prints a migrate plan identically to running
+ * `migrate` standalone, instead of a second, easily-drifting copy of
+ * this formatting (including the empty-plan "nothing to migrate" case). */
+export declare function printPlan(plan: MigratePlan, dryRun: boolean): void;

package/dist/commands/migrate.js

@@ -0,0 +1,132 @@
+/**
+ * `trellis migrate --from <agent>` — imports an existing agent's real
+ * skills and instructions into canonical source (trellis-cli-migrate).
+ * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
+ * plan-then-apply split every adapter already uses.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import * as claudeCodeProbe from "../probes/claude-code.js";
+import * as codexProbe from "../probes/codex.js";
+import * as kiroProbe from "../probes/kiro.js";
+import * as piProbe from "../probes/pi.js";
+import { AGENTS_MD_TEMPLATE } from "./init.js";
+import { dirContentsEqual } from "../lib/dirEquals.js";
+import { ALL_AGENTS } from "../core/types.js";
+const PROBES = {
+    "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
+    codex: (homeDir) => codexProbe.probe(homeDir),
+    kiro: (homeDir) => kiroProbe.probe(homeDir),
+    pi: (homeDir) => piProbe.probe(homeDir),
+};
+function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
+    if (isSymlink) {
+        return { kind: "skill", name, action: "skip-symlink", detail: "shared in from elsewhere, not this agent's own content" };
+    }
+    if (!caseCorrect) {
+        return { kind: "skill", name, action: "skip-case-broken", detail: "already undiscoverable on at least one other agent — fix on the source before migrating" };
+    }
+    if (!existsSync(canonicalDir)) {
+        return { kind: "skill", name, action: "create", detail: `will copy from ${sourceDir}`, sourceDir };
+    }
+    if (dirContentsEqual(sourceDir, canonicalDir)) {
+        return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
+    }
+    return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+}
+function planInstructions(snapshot, canonicalAgentsMd) {
+    if (!snapshot.instructionsFile)
+        return undefined;
+    if (snapshot.instructionsFile.isSymlink) {
+        return { kind: "instructions", name: "agents.md", action: "skip-symlink", detail: "source agent's instructions file is itself a symlink, nothing real to read" };
+    }
+    let sourceContent;
+    try {
+        sourceContent = readFileSync(snapshot.instructionsFile.path, "utf-8");
+    }
+    catch (err) {
+        return { kind: "instructions", name: "agents.md", action: "conflict", detail: `could not read source instructions: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!existsSync(canonicalAgentsMd)) {
+        return { kind: "instructions", name: "agents.md", action: "create", detail: "canonical agents.md does not exist yet", sourceContent };
+    }
+    const current = readFileSync(canonicalAgentsMd, "utf-8");
+    if (current === AGENTS_MD_TEMPLATE) {
+        return { kind: "instructions", name: "agents.md", action: "create", detail: "canonical agents.md is still trellis init's placeholder", sourceContent };
+    }
+    if (current === sourceContent) {
+        return { kind: "instructions", name: "agents.md", action: "already-migrated", detail: "canonical content is byte-identical" };
+    }
+    return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
+}
+export async function collectMigratePlan(agent, homeDir = homedir()) {
+    const snapshot = await PROBES[agent](homeDir);
+    if (!snapshot.present) {
+        return { agent, present: false, items: [] };
+    }
+    const canonicalRoot = join(homeDir, ".trellis");
+    const items = [];
+    for (const root of snapshot.skillRoots) {
+        for (const skill of root.skills) {
+            items.push(planSkill(skill.name, skill.dir, skill.isSymlink, skill.caseCorrect, join(canonicalRoot, "skills", skill.name)));
+        }
+    }
+    const instructionsItem = planInstructions(snapshot, join(canonicalRoot, "agents.md"));
+    if (instructionsItem)
+        items.push(instructionsItem);
+    return { agent, present: true, items };
+}
+export function applyMigratePlan(plan, homeDir = homedir()) {
+    const canonicalRoot = join(homeDir, ".trellis");
+    for (const item of plan.items) {
+        if (item.action !== "create")
+            continue;
+        if (item.kind === "skill" && item.sourceDir) {
+            const dest = join(canonicalRoot, "skills", item.name);
+            mkdirSync(dest, { recursive: true });
+            cpSync(item.sourceDir, dest, { recursive: true });
+        }
+        else if (item.kind === "instructions" && item.sourceContent !== undefined) {
+            mkdirSync(canonicalRoot, { recursive: true });
+            writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
+        }
+    }
+}
+export async function runMigrate(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (!opts.from || !ALL_AGENTS.includes(opts.from)) {
+        console.error(`--from must be one of: ${ALL_AGENTS.join(", ")} (got ${opts.from ?? "(none)"})`);
+        return { exitCode: 1 };
+    }
+    const agent = opts.from;
+    const plan = await collectMigratePlan(agent, homeDir);
+    if (!plan.present) {
+        console.error(`${agent} is not present on this machine — nothing to migrate.`);
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        applyMigratePlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        printPlan(plan, opts.dryRun ?? false);
+    }
+    const hasConflict = plan.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+/** Exported so `onboard` prints a migrate plan identically to running
+ * `migrate` standalone, instead of a second, easily-drifting copy of
+ * this formatting (including the empty-plan "nothing to migrate" case). */
+export function printPlan(plan, dryRun) {
+    console.log(`${dryRun ? "[dry run] " : ""}migrate --from ${plan.agent}`);
+    if (plan.items.length === 0) {
+        console.log("  nothing to migrate");
+        return;
+    }
+    for (const item of plan.items) {
+        console.log(`  [${item.action}] ${item.kind === "skill" ? `skill "${item.name}"` : "instructions"} — ${item.detail}`);
+    }
+}

package/dist/commands/onboard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `trellis onboard` — chains `init` → agent detection → base-agent
+ * resolution → `migrate` → `sync` into one guided flow
+ * (trellis-cli-onboard). Orchestrates existing commands' own
+ * plan/apply logic; no new skill-copy, symlink, or conflict-detection
+ * judgment is made here.
+ */
+import type { AgentId } from "../core/types.js";
+import type { MigratePlan } from "./migrate.js";
+import type { SyncReport } from "./sync.js";
+export interface OnboardAgentSummary {
+    agent: AgentId;
+    present: boolean;
+    skillCount: number;
+    skillNames: string[];
+    /** instructionsFile exists and isn't itself a symlink — real content
+     * of that agent's own to potentially migrate, not a judgment about
+     * its quality or length. */
+    hasRealInstructions: boolean;
+}
+export declare function collectOnboardSummary(homeDir?: string): Promise<OnboardAgentSummary[]>;
+export interface RunOnboardOptions {
+    agent?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Defaults to the real `~`; overridable for tests only. */
+    homeDir?: string;
+    /** Test-only: overrides the real `process.stdin.isTTY` check so the
+     * interactive-vs-refuse branch is exercisable without a real terminal. */
+    isTTY?: boolean;
+    /** Test-only: replaces the real readline prompt with a scripted
+     * answer, so the prompt path is exercisable without a real terminal. */
+    promptForAgent?: (present: OnboardAgentSummary[]) => Promise<string>;
+}
+export interface OnboardResult {
+    summary: OnboardAgentSummary[];
+    base?: AgentId;
+    baseReason?: "auto-selected" | "flag" | "prompt";
+    migratePlan?: MigratePlan;
+    syncReport?: SyncReport;
+    refusal?: string;
+    /** Only set when no agent is present — the same values `--json` and
+     * text output both surface, so a machine caller doesn't have to
+     * hardcode them a second time. */
+    installHints?: Record<AgentId, string>;
+}
+export declare function collectOnboardPlan(opts?: RunOnboardOptions): Promise<OnboardResult>;
+export declare function runOnboard(opts?: RunOnboardOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/onboard.js

@@ -0,0 +1,155 @@
+/**
+ * `trellis onboard` — chains `init` → agent detection → base-agent
+ * resolution → `migrate` → `sync` into one guided flow
+ * (trellis-cli-onboard). Orchestrates existing commands' own
+ * plan/apply logic; no new skill-copy, symlink, or conflict-detection
+ * judgment is made here.
+ */
+import { createInterface } from "node:readline/promises";
+import { homedir } from "node:os";
+import * as claudeCodeProbe from "../probes/claude-code.js";
+import * as codexProbe from "../probes/codex.js";
+import * as kiroProbe from "../probes/kiro.js";
+import * as piProbe from "../probes/pi.js";
+import { ALL_AGENTS } from "../core/types.js";
+import { INSTALL_HINTS, collectInitReport } from "./init.js";
+import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } from "./migrate.js";
+import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+const PROBES = {
+    "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
+    codex: (homeDir) => codexProbe.probe(homeDir),
+    kiro: (homeDir) => kiroProbe.probe(homeDir),
+    pi: (homeDir) => piProbe.probe(homeDir),
+};
+export async function collectOnboardSummary(homeDir = homedir()) {
+    return Promise.all(ALL_AGENTS.map(async (agent) => {
+        const snapshot = await PROBES[agent](homeDir);
+        if (!snapshot.present) {
+            return { agent, present: false, skillCount: 0, skillNames: [], hasRealInstructions: false };
+        }
+        const skillNames = snapshot.skillRoots.flatMap((root) => root.skills.map((s) => s.name));
+        const hasRealInstructions = snapshot.instructionsFile !== undefined && !snapshot.instructionsFile.isSymlink;
+        return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions };
+    }));
+}
+async function promptForAgentReal(present) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("Multiple agents detected:");
+        for (const s of present) {
+            const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
+            console.log(`  ${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`);
+        }
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const answer = (await rl.question("Choose a base agent to migrate from: ")).trim();
+            if (present.some((s) => s.agent === answer))
+                return answer;
+            console.log(`Not one of the present agents: ${present.map((s) => s.agent).join(", ")}`);
+        }
+        throw new Error("no valid agent chosen after 2 attempts");
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function collectOnboardPlan(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    await collectInitReport(homeDir);
+    const summary = await collectOnboardSummary(homeDir);
+    const present = summary.filter((s) => s.present);
+    if (present.length === 0) {
+        return { summary, installHints: { ...INSTALL_HINTS } };
+    }
+    let base;
+    let baseReason;
+    if (opts.agent) {
+        const match = present.find((s) => s.agent === opts.agent);
+        if (!match) {
+            return {
+                summary,
+                refusal: `"${opts.agent}" is not one of the present agents (${present.map((s) => s.agent).join(", ")})`,
+            };
+        }
+        base = match.agent;
+        baseReason = "flag";
+    }
+    else if (present.length === 1) {
+        base = present[0].agent;
+        baseReason = "auto-selected";
+    }
+    else {
+        const canPrompt = !opts.json && (opts.isTTY ?? process.stdin.isTTY === true);
+        if (!canPrompt) {
+            return {
+                summary,
+                refusal: `multiple agents detected (${present.map((s) => s.agent).join(", ")}) and no terminal to prompt in — pass --agent <id>`,
+            };
+        }
+        const prompt = opts.promptForAgent ?? promptForAgentReal;
+        try {
+            base = (await prompt(present));
+        }
+        catch (err) {
+            return { summary, refusal: err instanceof Error ? err.message : String(err) };
+        }
+        baseReason = "prompt";
+    }
+    const migratePlan = await collectMigratePlan(base, homeDir);
+    if (!opts.dryRun) {
+        applyMigratePlan(migratePlan, homeDir);
+    }
+    const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun });
+    return { summary, base, baseReason, migratePlan, syncReport };
+}
+export async function runOnboard(opts = {}) {
+    const result = await collectOnboardPlan(opts);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printResult(result, opts.dryRun ?? false);
+    }
+    if (result.refusal)
+        return { exitCode: 1 };
+    const hasConflict = (result.migratePlan?.items.some((i) => i.action === "conflict") ?? false) ||
+        (result.syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false);
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+function printResult(result, dryRun) {
+    if (dryRun)
+        console.log("[dry run]");
+    const present = result.summary.filter((s) => s.present);
+    if (present.length === 0) {
+        console.log("No agent detected on this machine yet. Install one, then re-run `trellis onboard`:");
+        for (const agent of ALL_AGENTS) {
+            console.log(`  ${agent}: ${INSTALL_HINTS[agent]}`);
+        }
+        return;
+    }
+    if (result.refusal) {
+        console.error(result.refusal);
+        return;
+    }
+    if (result.baseReason === "auto-selected") {
+        console.log(`Only ${result.base} detected — using it as the migration base.`);
+    }
+    else if (result.baseReason === "flag") {
+        console.log(`Using ${result.base} as the migration base (--agent).`);
+    }
+    else if (result.baseReason === "prompt") {
+        console.log(`Using ${result.base} as the migration base.`);
+    }
+    // Reuse `migrate`/`sync`'s own printing verbatim (including the
+    // "nothing to migrate" / "already in sync" cases) rather than a second,
+    // easily-drifting copy of this formatting. `dryRun: false` here since
+    // this function's own leading "[dry run]" line already said so once.
+    if (result.migratePlan) {
+        console.log("");
+        printMigratePlan(result.migratePlan, false);
+    }
+    if (result.syncReport) {
+        console.log("\nsync");
+        printSyncReport(result.syncReport, false);
+    }
+    console.log("\nNext: `trellis mcp sync` to distribute MCP servers, `trellis secrets audit` to check for leaked credentials.");
+}

package/dist/commands/secretsAudit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `trellis secrets audit` — reads every present, MCP-capable agent's real
+ * config file (never the canonical source) and checks it against
+ * `CanonicalSource.secretsPolicy`: a literal-value scan against
+ * `rejectPatterns`, and a declared-env-var-name check against
+ * `allowedVars`. Also checks, agent-agnostically, whether every env var
+ * name declared across canonical `mcp.servers[*].env` actually resolves
+ * to a value via the same `resolveSecretEnv` the pi bridge uses
+ * (trellis-secrets-env-management) — authoritative for pi, a best-effort
+ * proxy for the other three (design.md D3 in that change). Read-only —
+ * never writes anything. Fails non-zero on any finding
+ * (trellis-secrets-audit-p3).
+ */
+import type { AgentId } from "../core/types.js";
+export interface RunSecretsAuditOptions {
+    json?: boolean;
+    /** Same test/sandbox-only seam as every other command — never a CLI
+     * flag. See docs/architecture.md's testing philosophy. */
+    homeDir?: string;
+}
+export interface SecretsFinding {
+    /** "environment" for `missing-env-value` — that check isn't scoped to
+     * any single agent's config file (see module doc comment). */
+    agent: AgentId | "environment";
+    file: string;
+    kind: "literal-secret" | "unexpected-var-name" | "missing-env-value";
+    detail: string;
+}
+export interface SecretsAuditReport {
+    findings: SecretsFinding[];
+}
+export declare function collectSecretsAuditReport(opts?: RunSecretsAuditOptions): Promise<SecretsAuditReport>;
+export declare function runSecretsAudit(opts?: RunSecretsAuditOptions): Promise<{
+    exitCode: number;
+}>;