agent-trellis 0.14.0 → 0.15.0

package/dist/lib/workspace.js

@@ -0,0 +1,158 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { oauthClientMetadata } from "../core/types.js";
+import { fromServerDefYaml } from "../core/mcpServerDef.js";
+export const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export const WORKSPACE_CONFIG_VERSION = 1;
+const CONFIG_SOURCE_LABEL = ".agents/config.json";
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export function findWorkspaceRoot(startDir) {
+    const home = resolve(homedir());
+    let dir = resolve(startDir);
+    while (true) {
+        if (dir === home)
+            return null;
+        const candidate = join(dir, WORKSPACE_DIR_NAME);
+        try {
+            if (statSync(candidate).isDirectory())
+                return dir;
+        }
+        catch {
+            // not present or unreadable — keep walking
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function isTombstone(def) {
+    return def.enabled === false && def.transport === undefined;
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export function loadWorkspaceLayer(workspaceDir, policy) {
+    const layerRoot = join(workspaceDir, WORKSPACE_DIR_NAME);
+    const diagnostics = [];
+    const layer = { root: workspaceDir, servers: {}, tombstones: [], skills: [], diagnostics };
+    const configPath = join(layerRoot, "config.json");
+    if (existsSync(configPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch (err) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: invalid JSON — ${err.message}`);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: top level must be an object { "version", "mcp" }`);
+        }
+        const { version, mcp, ...extra } = parsed;
+        const configVersion = version === undefined ? WORKSPACE_CONFIG_VERSION : version;
+        if (typeof configVersion !== "number" || !Number.isInteger(configVersion) || configVersion < 1) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: "version" must be a positive integer, got ${JSON.stringify(version)}`);
+        }
+        if (configVersion > WORKSPACE_CONFIG_VERSION) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: schema version ${configVersion} is newer than this Trellis understands (${WORKSPACE_CONFIG_VERSION}) — upgrade Trellis`);
+        }
+        for (const key of Object.keys(extra)) {
+            diagnostics.push(`${CONFIG_SOURCE_LABEL}: unrecognized top-level key "${key}" — ignored`);
+        }
+        if (mcp !== undefined) {
+            if (typeof mcp !== "object" || mcp === null || typeof mcp.servers !== "object" || mcp.servers === null || Array.isArray(mcp.servers)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "mcp.servers" must be an object mapping server names to definitions`);
+            }
+            for (const [name, rawDef] of Object.entries(mcp.servers)) {
+                if (typeof rawDef !== "object" || rawDef === null) {
+                    throw new Error(`${CONFIG_SOURCE_LABEL}: "${name}" must be a server definition object or { "enabled": false }`);
+                }
+                if (isTombstone(rawDef)) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                // enabled:false WITH a transport is tombstone semantics too — it
+                // disables the same-ID global entry and renders nothing.
+                if (rawDef.enabled === false) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                layer.servers[name] = fromServerDefYaml(name, rawDef, CONFIG_SOURCE_LABEL);
+            }
+        }
+    }
+    const instructionsPath = join(layerRoot, "AGENTS.md");
+    if (existsSync(instructionsPath)) {
+        layer.instructionsFile = instructionsPath;
+    }
+    const skillsRoot = join(layerRoot, "skills");
+    let skillEntries = [];
+    try {
+        skillEntries = readdirSync(skillsRoot);
+    }
+    catch {
+        // no skills/ — optional, same as every other layer file
+    }
+    for (const name of skillEntries) {
+        const dir = join(skillsRoot, name);
+        try {
+            if (statSync(dir).isDirectory())
+                layer.skills.push({ name, dir });
+        }
+        catch {
+            // unreadable/broken entry — skip, not a load failure
+        }
+    }
+    assertWorkspaceSecretsClean(layer.servers, policy);
+    return layer;
+}
+/** An exact `${NAME}` value is a reference to the global secret store, not
+ * a literal — the only credential-shaped content allowed in a committable
+ * project layer (same classification as mcpMigrateRead.ts). */
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * Load-time secrets boundary for the project layer (workspace-scope spec
+ * "Secrets stay global-only"): scans the fields a pasted secret could
+ * reach — `env` entries, `staticEnv` values, `headers` values, and OAuth
+ * client metadata — and refuses the load, naming the server and field but
+ * never echoing the value.
+ */
+function assertWorkspaceSecretsClean(servers, policy) {
+    const check = (server, field, value) => {
+        if (value === undefined || VAR_REF_RE.test(value))
+            return;
+        for (const pattern of policy.rejectPatterns) {
+            if (pattern.test(value)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "${server}" ${field} matches a secrets.policy.yaml reject pattern — the project layer is committable and must carry only \${VAR} references; move the value to the global secret store (the offending value is intentionally not printed)`);
+            }
+        }
+    };
+    for (const [name, def] of Object.entries(servers)) {
+        for (const entry of def.env ?? [])
+            check(name, "env", entry);
+        for (const [key, value] of Object.entries(def.staticEnv ?? {}))
+            check(name, `static_env.${key}`, value);
+        for (const [key, value] of Object.entries(def.headers ?? {}))
+            check(name, `headers.${key}`, value);
+        const meta = oauthClientMetadata(def.auth);
+        check(name, "auth.client_id", meta.clientId);
+        check(name, "auth.client_secret_env", meta.clientSecretEnv);
+    }
+}

package/dist/lib/workspaceConfig.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting a server into `.agents/config.json` (`mcp add --workspace`).
+ *
+ * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
+ * same file, same schema, one validator (via `toServerDefYaml`, so a
+ * `McpServerDef` serializes to the exact snake_case shape the loader
+ * validates back). Everything written here is committable by design:
+ * only `${VAR}` references ever land in `config.json`, never values
+ * (the loader refuses literals at read time; these helpers never
+ * resolve anything in the first place).
+ */
+import type { McpServerDef } from "../core/types.js";
+import { type McpServerDefYaml } from "../core/mcpServerDef.js";
+import type { BackupSession } from "./backup.js";
+export interface WorkspaceConfigJson {
+    version?: number;
+    mcp?: {
+        servers?: Record<string, McpServerDefYaml>;
+    };
+    [key: string]: unknown;
+}
+export declare function workspaceConfigPath(workspaceRoot: string): string;
+/** `{}` when the file doesn't exist yet (a workspace may carry only
+ * skills/AGENTS.md); a clear error naming the file when it exists but
+ * doesn't parse — never a raw JSON stack. */
+export declare function readWorkspaceConfigJson(workspaceRoot: string): WorkspaceConfigJson;
+export declare function writeWorkspaceConfigJson(workspaceRoot: string, config: WorkspaceConfigJson, backup?: BackupSession): void;
+/** Insert or replace `mcp.servers.<name>` with the def serialized through
+ * the shared YAML/JSON translator. `version` is filled in when absent —
+ * an existing file's version (and any unknown keys) is preserved. */
+export declare function upsertWorkspaceServer(workspaceRoot: string, name: string, def: McpServerDef, backup?: BackupSession): void;
+export interface WorkspaceScaffoldFile {
+    path: string;
+    action: "create" | "already-present";
+}
+/** Exported for `migrate --workspace`: a `.agents/AGENTS.md` holding
+ * exactly this template is treated as still-empty scaffolding that an
+ * instructions import may replace, not as user content to conflict on. */
+export declare const WORKSPACE_AGENTS_MD_TEMPLATE = "# Project instructions\n\nShared instructions for every agent working in this repository. Trellis\ndelivers this file to agents that don't read `.agents/AGENTS.md`\nnatively (Codex/pi/Kimi do; Kiro gets a steering copy; Claude Code keeps\nits own CLAUDE.md).\n";
+/** Fill-missing-only scaffold of `.agents/`: never overwrites anything
+ * that already exists, so re-running is a no-op (idempotent by
+ * construction, same posture as global `trellis init`). */
+export declare function scaffoldWorkspace(workspaceRoot: string, write?: boolean): WorkspaceScaffoldFile[];

package/dist/lib/workspaceConfig.js

@@ -0,0 +1,98 @@
+/**
+ * Write-side helpers for the workspace layer (trellis-workspace-scope
+ * tasks 3.3/3.4): scaffolding `.agents/` (`init --workspace`) and
+ * upserting a server into `.agents/config.json` (`mcp add --workspace`).
+ *
+ * The read side lives in src/lib/workspace.ts (`loadWorkspaceLayer`) —
+ * same file, same schema, one validator (via `toServerDefYaml`, so a
+ * `McpServerDef` serializes to the exact snake_case shape the loader
+ * validates back). Everything written here is committable by design:
+ * only `${VAR}` references ever land in `config.json`, never values
+ * (the loader refuses literals at read time; these helpers never
+ * resolve anything in the first place).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { toServerDefYaml } from "../core/mcpServerDef.js";
+import { WORKSPACE_CONFIG_VERSION, WORKSPACE_DIR_NAME } from "./workspace.js";
+export function workspaceConfigPath(workspaceRoot) {
+    return join(workspaceRoot, WORKSPACE_DIR_NAME, "config.json");
+}
+/** `{}` when the file doesn't exist yet (a workspace may carry only
+ * skills/AGENTS.md); a clear error naming the file when it exists but
+ * doesn't parse — never a raw JSON stack. */
+export function readWorkspaceConfigJson(workspaceRoot) {
+    const path = workspaceConfigPath(workspaceRoot);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("top level must be an object");
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function writeWorkspaceConfigJson(workspaceRoot, config, backup) {
+    const path = workspaceConfigPath(workspaceRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const content = `${JSON.stringify(config, null, 2)}\n`;
+    if (backup) {
+        backup.writeFile(path, content);
+        return;
+    }
+    writeFileSync(path, content);
+}
+/** Insert or replace `mcp.servers.<name>` with the def serialized through
+ * the shared YAML/JSON translator. `version` is filled in when absent —
+ * an existing file's version (and any unknown keys) is preserved. */
+export function upsertWorkspaceServer(workspaceRoot, name, def, backup) {
+    const config = readWorkspaceConfigJson(workspaceRoot);
+    const servers = { ...(config.mcp?.servers ?? {}), [name]: toServerDefYaml(def) };
+    const next = {
+        ...config,
+        version: config.version ?? WORKSPACE_CONFIG_VERSION,
+        mcp: { ...(config.mcp ?? {}), servers },
+    };
+    writeWorkspaceConfigJson(workspaceRoot, next, backup);
+}
+/** Exported for `migrate --workspace`: a `.agents/AGENTS.md` holding
+ * exactly this template is treated as still-empty scaffolding that an
+ * instructions import may replace, not as user content to conflict on. */
+export const WORKSPACE_AGENTS_MD_TEMPLATE = `# Project instructions
+
+Shared instructions for every agent working in this repository. Trellis
+delivers this file to agents that don't read \`.agents/AGENTS.md\`
+natively (Codex/pi/Kimi do; Kiro gets a steering copy; Claude Code keeps
+its own CLAUDE.md).
+`;
+/** Fill-missing-only scaffold of `.agents/`: never overwrites anything
+ * that already exists, so re-running is a no-op (idempotent by
+ * construction, same posture as global `trellis init`). */
+export function scaffoldWorkspace(workspaceRoot, write = true) {
+    const agentsDir = join(workspaceRoot, WORKSPACE_DIR_NAME);
+    const configPath = workspaceConfigPath(workspaceRoot);
+    const skillsDir = join(agentsDir, "skills");
+    const agentsMdPath = join(agentsDir, "AGENTS.md");
+    if (write) {
+        mkdirSync(agentsDir, { recursive: true });
+        mkdirSync(skillsDir, { recursive: true });
+    }
+    const files = [];
+    files.push(existsSync(configPath)
+        ? { path: configPath, action: "already-present" }
+        : { path: configPath, action: "create" });
+    if (!existsSync(configPath) && write) {
+        writeFileSync(configPath, `${JSON.stringify({ version: WORKSPACE_CONFIG_VERSION, mcp: { servers: {} } }, null, 2)}\n`);
+    }
+    files.push(existsSync(agentsMdPath)
+        ? { path: agentsMdPath, action: "already-present" }
+        : { path: agentsMdPath, action: "create" });
+    if (!existsSync(agentsMdPath) && write) {
+        writeFileSync(agentsMdPath, WORKSPACE_AGENTS_MD_TEMPLATE);
+    }
+    return files;
+}

package/dist/lib/workspaceDoctor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Workspace attribution for `trellis doctor` (trellis-workspace-scope
+ * task 3.5): given the workspace-merged canonical source, reports which
+ * layer each MCP server / skill comes from, what the workspace shadowed
+ * or tombstoned, which `${VAR}` references in workspace server defs
+ * don't resolve under the current secrets policy, which project-level
+ * native config files hold entries Trellis never rendered (the
+ * `migrate --workspace` hint), and zcode's reverse-precedence deviation
+ * (task 2.5's doctor half). Read-only by construction — it computes
+ * from the already-loaded canonical source and file reads only.
+ */
+import type { AgentId, CanonicalSource, LayerProvenance } from "../core/types.js";
+export interface WorkspaceLayerEntry {
+    name: string;
+    layer: LayerProvenance;
+}
+export interface WorkspaceUnmigratedHint {
+    agent: AgentId;
+    path: string;
+    /** Entry names present in the file with no Trellis manifest record. */
+    entries: string[];
+}
+export interface WorkspaceDoctorSection {
+    root: string;
+    mcp: WorkspaceLayerEntry[];
+    skills: WorkspaceLayerEntry[];
+    /** `mcp:name` / `skill:name` entries the workspace layer overrode. */
+    shadowed: string[];
+    /** `mcp:name` entries the workspace layer tombstoned (global entry
+     * disabled for this project). Subset of `shadowed`. */
+    tombstoned: string[];
+    /** `${VAR}` references in workspace server defs that resolve to
+     * nothing under the current secrets policy. Names only — never
+     * values. */
+    unresolvedVars: {
+        server: string;
+        field: string;
+        name: string;
+    }[];
+    unmigrated: WorkspaceUnmigratedHint[];
+    /** zcode's user-level-first deviation notices (empty otherwise). */
+    precedenceWarnings: string[];
+}
+export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): WorkspaceDoctorSection | undefined;

package/dist/lib/workspaceDoctor.js

@@ -0,0 +1,94 @@
+/**
+ * Workspace attribution for `trellis doctor` (trellis-workspace-scope
+ * task 3.5): given the workspace-merged canonical source, reports which
+ * layer each MCP server / skill comes from, what the workspace shadowed
+ * or tombstoned, which `${VAR}` references in workspace server defs
+ * don't resolve under the current secrets policy, which project-level
+ * native config files hold entries Trellis never rendered (the
+ * `migrate --workspace` hint), and zcode's reverse-precedence deviation
+ * (task 2.5's doctor half). Read-only by construction — it computes
+ * from the already-loaded canonical source and file reads only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolveSecretEnv } from "./secretEnv.js";
+import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+function collectVarRefs(canonical) {
+    const provenance = canonical.workspace?.mcpProvenance ?? {};
+    const refs = [];
+    for (const [name, def] of Object.entries(canonical.mcp.servers)) {
+        if (provenance[name] !== "workspace")
+            continue;
+        for (const envName of def.env ?? []) {
+            refs.push({ server: name, field: "env", name: envName });
+        }
+        for (const [key, value] of Object.entries(def.staticEnv ?? {})) {
+            const match = VAR_REF_RE.exec(value);
+            if (match)
+                refs.push({ server: name, field: `static_env.${key}`, name: match[1] });
+        }
+        for (const [key, value] of Object.entries(def.headers ?? {})) {
+            const match = VAR_REF_RE.exec(value);
+            if (match)
+                refs.push({ server: name, field: `headers.${key}`, name: match[1] });
+        }
+    }
+    return refs;
+}
+/** Entry names a JSON `mcpServers` file / Codex TOML / zcode nested
+ * config holds beyond what the in-repo manifest records Trellis
+ * rendering. Regex-parses Codex TOML section headers — doctor only
+ * needs names for a hint, not a full TOML AST. */
+function unmarkedEntries(agentId, configPath, recorded) {
+    if (!existsSync(configPath))
+        return [];
+    let names = [];
+    if (agentId === "codex") {
+        const content = readFileSync(configPath, "utf-8");
+        const re = /^\[mcp_servers\.([^\]]+)\]\s*$/gm;
+        let match;
+        while ((match = re.exec(content)) !== null)
+            names.push(match[1]);
+    }
+    else {
+        try {
+            const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+            const servers = agentId === "zcode"
+                ? (parsed.mcp?.servers ?? {})
+                : (parsed.mcpServers ?? {});
+            names = Object.keys(servers);
+        }
+        catch {
+            return []; // unparsable file is the sync guard's finding, not doctor's
+        }
+    }
+    return names.filter((name) => recorded[name] === undefined);
+}
+export function collectWorkspaceDoctorSection(canonical) {
+    const workspace = canonical.workspace;
+    if (!workspace)
+        return undefined;
+    const mcp = Object.keys(canonical.mcp.servers)
+        .map((name) => ({ name, layer: workspace.mcpProvenance[name] ?? "global" }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const skills = canonical.skills
+        .map((s) => ({ name: s.name, layer: workspace.skillProvenance[s.name] ?? "global" }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    // A shadowed mcp entry that no longer exists in the merged source was
+    // tombstoned; one still present (with workspace provenance) was
+    // overridden.
+    const tombstoned = workspace.shadowed.filter((entry) => entry.startsWith("mcp:") && canonical.mcp.servers[entry.slice(4)] === undefined);
+    const refs = collectVarRefs(canonical);
+    const resolved = resolveSecretEnv([...new Set(refs.map((r) => r.name))], canonical.secretsPolicy);
+    const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
+    const manifest = loadWorkspaceRendered(workspace.root);
+    const unmigrated = [];
+    for (const agentId of canonical.managedAgents) {
+        const configPath = workspaceMcpConfigPath(agentId, workspace.root);
+        const entries = unmarkedEntries(agentId, configPath, manifest.mcp?.[agentId] ?? {});
+        if (entries.length > 0)
+            unmigrated.push({ agent: agentId, path: configPath, entries });
+    }
+    const precedenceWarnings = canonical.managedAgents.flatMap((id) => workspacePrecedenceWarnings(id, canonical));
+    return { root: workspace.root, mcp, skills, shadowed: workspace.shadowed, tombstoned, unresolvedVars, unmigrated, precedenceWarnings };
+}

package/dist/lib/workspaceFiles.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace (project-level) skills & instructions delivery
+ * (trellis-workspace-scope design D4/D5). Unlike global delivery (symlinks
+ * into `~/.trellis/`), workspace skills are COPIED into the agent's
+ * project-level directory — rendered artifacts must be committable to the
+ * repo and usable on filesystems without symlink support.
+ *
+ * A copy has no symlink-realpath ownership proof, so ownership mirrors the
+ * MCP ledger instead: one `.trellis-workspace.json` per destination root
+ * maps skill name → { source, sourceDigest, destDigest }. A delivered
+ * directory is "ours" only while its current digest still equals the
+ * recorded `destDigest`; a hand-edited copy is a conflict, never touched —
+ * the same posture mcpOwnership gives bare JSON/TOML keys.
+ *
+ * Instructions are delivered as marker-headed file copies: root `AGENTS.md`
+ * (read natively by Codex, pi, and Kimi Code) and Kiro's
+ * `.kiro/steering/trellis-workspace.md`. Claude Code reads `CLAUDE.md`, not
+ * `AGENTS.md`, and a repo's `CLAUDE.md` is almost always user-authored —
+ * v1 deliberately writes no Claude instructions file (documented
+ * limitation; `migrate --workspace` is the path for absorbing one).
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId, CanonicalSource } from "../core/types.js";
+import type { BackupSession } from "./backup.js";
+/** Per-destination-root ledger of Trellis-owned workspace copies. */
+export type WorkspaceCopyLedger = Record<string, {
+    source: string;
+    sourceDigest: string;
+    destDigest: string;
+}>;
+/** Exported for `migrate --workspace` (trellis-workspace-scope task 4.x):
+ * absorbing a root `AGENTS.md` rewrites it marker-headed in place, which
+ * must be byte-identical to what a later sync would render. */
+export declare const INSTRUCTIONS_MARKER = "<!-- generated by trellis from .agents/AGENTS.md \u2014 do not edit; run `trellis sync` to refresh -->";
+export declare function planWorkspaceFiles(agentId: AgentId, canonical: CanonicalSource): AdapterPlanItem[];
+/** Executes a `planWorkspaceFiles` result through the run's backup session
+ * and rewrites the copy ledger for every destination root it touched. */
+export declare function applyWorkspaceFiles(agentId: AgentId, canonical: CanonicalSource, items: AdapterPlanItem[], backup: BackupSession): void;