agent-trellis 0.8.2 → 0.9.0

package/dist/commands/rollback.js

@@ -13,6 +13,7 @@ import { readlink, rm, symlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { backupsRoot } from "../lib/backup.js";
+import { directoryDigest } from "../lib/dirDigest.js";
 function sha256(content) {
     return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
@@ -99,15 +100,25 @@ async function planOperation(homeDir, runId, op) {
             }
             return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
         }
-        // Directory conflict detection is existence-only, not a deep content
-        // hash (see BackupOperation's "dir-create"/"dir-remove" doc comment
-        // in backup.ts) — a real, documented simplification, not an
-        // oversight: something touching a file inside an otherwise-untouched
-        // directory won't be caught as a conflict.
+        // Historical `dir-remove` operations remain existence-only because they
+        // predate directory manifests. New directory creates/replacements carry a
+        // deterministic digest, so remote Skill rollback refuses an edited tree.
         case "dir-create": {
             if (!existsSync(op.path)) {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
+            if (op.afterDigest !== undefined) {
+                let digest;
+                try {
+                    digest = directoryDigest(op.path);
+                }
+                catch {
+                    return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
+                }
+                if (digest !== op.afterDigest) {
+                    return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+                }
+            }
             return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
         }
         case "dir-remove": {
@@ -116,6 +127,22 @@ async function planOperation(homeDir, runId, op) {
             }
             return { action: "restore", path: op.path, description: `recreate ${op.path} from its content before this run (${join(runDir, op.beforeDir)})` };
         }
+        case "dir-replace": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            let digest;
+            try {
+                digest = directoryDigest(op.path);
+            }
+            catch {
+                return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
+            }
+            if (digest !== op.afterDigest) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+            }
+            return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeDir)})` };
+        }
     }
 }
 export async function collectRollbackPlan(homeDirInput, runIdInput) {
@@ -153,6 +180,10 @@ async function restoreOperation(homeDir, runId, op) {
         case "dir-remove":
             cpSync(join(runDir, op.beforeDir), op.path, { recursive: true });
             return;
+        case "dir-replace":
+            rmSync(op.path, { recursive: true, force: true });
+            cpSync(join(runDir, op.beforeDir), op.path, { recursive: true });
+            return;
     }
 }
 export async function applyRollbackPlan(homeDir, runId, manifest, items) {

package/dist/commands/skill.d.ts

@@ -10,6 +10,7 @@
 import type { AgentId } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
 import type { SyncReport } from "./sync.js";
+import type { RemoteSkillLockEntry } from "../lib/remoteSkillLock.js";
 export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
 export interface BuiltinSkillUpdatePlan {
     name: "trellis-runtime";
@@ -29,6 +30,7 @@ export declare function runSkillUpdateBuiltin(opts?: {
 export interface SkillListEntry {
     name: string;
     scope: readonly AgentId[];
+    remote?: Pick<RemoteSkillLockEntry, "source" | "requestedRef" | "commit" | "subdirectory" | "digest">;
 }
 export declare function collectSkillList(homeDir?: string): SkillListEntry[];
 export declare function runSkillList(opts?: {

package/dist/commands/skill.js

@@ -19,6 +19,7 @@ import { resolveScope } from "../core/types.js";
 import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+import { remoteSkillProvenance } from "./remoteSkill.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -57,9 +58,11 @@ export function runSkillUpdateBuiltin(opts = {}) {
 }
 export function collectSkillList(homeDir = homedir()) {
     const canonical = loadCanonicalSource(homeDir);
+    const provenance = remoteSkillProvenance(homeDir);
     return canonical.skills.filter((skill) => !isBuiltinSkillName(skill.name)).map((skill) => ({
         name: skill.name,
         scope: resolveScope(skill.scope, canonical.managedAgents),
+        ...(provenance[skill.name] ? { remote: provenance[skill.name] } : {}),
     }));
 }
 export function runSkillList(opts = {}) {
@@ -71,8 +74,9 @@ export function runSkillList(opts = {}) {
         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)"}`);
+        for (const { name, scope, remote } of entries) {
+            const provenance = remote ? ` — remote: ${remote.source}@${remote.commit.slice(0, 12)}` : "";
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}${provenance}`);
         }
     }
     return { exitCode: 0 };

package/dist/core/canonical.d.ts

@@ -4,7 +4,7 @@
  * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
  * canonical-source-loading/spec.md for the exact contract this implements.
  */
-import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef } from "./types.js";
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRoute, McpServerDef, Scope } from "./types.js";
 import type { BackupSession } from "../lib/backup.js";
 /**
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
@@ -28,6 +28,22 @@ export type ServersYamlWriteResult = {
     ok: false;
     error: string;
 };
+export type ScopeYamlWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Read-only preflight for a later scope edit.  Remote import calls this
+ * before creating canonical content so an invalid hand-authored scope file
+ * cannot leave a half-applied import behind. */
+export declare function validateSkillScopeYaml(path: string): ScopeYamlWriteResult;
+/**
+ * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
+ * scope entries.  `undefined` removes this Skill's explicit entry and
+ * therefore restores the normal all-managed default.
+ */
+export declare function writeSkillScopeYaml(path: string, name: string, scope: Scope, backup?: BackupSession): ScopeYamlWriteResult;
 export declare function upsertServerYaml(path: string, name: string, def: McpServerDef, backup?: BackupSession): ServersYamlWriteResult;
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */

package/dist/core/canonical.js

@@ -176,6 +176,60 @@ function persistText(path, content, backup) {
     else
         writeFileSync(path, content);
 }
+/** Read-only preflight for a later scope edit.  Remote import calls this
+ * before creating canonical content so an invalid hand-authored scope file
+ * cannot leave a half-applied import behind. */
+export function validateSkillScopeYaml(path) {
+    if (!existsSync(path))
+        return { ok: true };
+    try {
+        const doc = parseDocument(readFileSync(path, "utf-8"));
+        if (doc.errors.length > 0)
+            throw new Error(doc.errors.map((error) => error.message).join("; "));
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
+ * scope entries.  `undefined` removes this Skill's explicit entry and
+ * therefore restores the normal all-managed default.
+ */
+export function writeSkillScopeYaml(path, name, scope, backup) {
+    if (!existsSync(path) && scope === undefined)
+        return { ok: true };
+    let doc;
+    try {
+        doc = existsSync(path) ? parseDocument(readFileSync(path, "utf-8")) : parseDocument("");
+        if (doc.errors.length > 0)
+            throw new Error(doc.errors.map((error) => error.message).join("; "));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const current = doc.getIn(["skills", name], true);
+    if (scope === undefined) {
+        if (current === undefined)
+            return { ok: true };
+        doc.deleteIn(["skills", name]);
+        const skills = doc.get("skills", true);
+        if (isMap(skills) && skills.items.length === 0)
+            doc.delete("skills");
+    }
+    else {
+        const currentJson = current && typeof current === "object" && "toJSON" in current && typeof current.toJSON === "function" ? current.toJSON() : current;
+        if (Array.isArray(currentJson) && currentJson.length === scope.length && currentJson.every((agent, index) => agent === scope[index])) {
+            return { ok: true };
+        }
+        doc.setIn(["skills", name], [...scope]);
+        forceBlockStyle(doc.get("skills", true));
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
 export function upsertServerYaml(path, name, def, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };

package/dist/lib/backup.d.ts

@@ -33,14 +33,13 @@ export type BackupOperation = {
     beforeLinkTarget: string;
 }
 /** A whole directory created where none existed — e.g. `skill add`
- * copying a canonical skill in. Unlike `file-create`, there is no
- * `afterHash`: hashing an arbitrary directory tree for drift detection
- * is deliberately not attempted here (see `dir-remove`'s doc comment
- * for why); rollback for this kind only checks existence, same
- * simplification both directions. */
+ * copying a canonical Skill in. New operations carry the resulting
+ * directory digest so rollback can refuse a tree edited after the run;
+ * the optional field preserves compatibility with old backup manifests. */
  | {
     kind: "dir-create";
     path: string;
+    afterDigest?: string;
 }
 /** A whole directory removed — e.g. `skill remove`. `beforeDir` is a
  * full recursive copy of the directory's pre-removal content, stored
@@ -55,6 +54,15 @@ export type BackupOperation = {
     kind: "dir-remove";
     path: string;
     beforeDir: string;
+}
+/** A whole directory replaced in-place.  The before-tree snapshot and the
+ * exact after-tree digest let rollback refuse a locally edited remote Skill
+ * instead of overwriting it. */
+ | {
+    kind: "dir-replace";
+    path: string;
+    beforeDir: string;
+    afterDigest: string;
 };
 export interface BackupManifest {
     runId: string;
@@ -74,6 +82,10 @@ export interface BackupSession {
     /** Snapshots `path`'s current content into this run's own storage,
      * then removes it, and records it as a `dir-remove`. */
     removeDir(path: string): void;
+    /** Snapshots an existing directory then copies `sourceDir` in its place,
+     * recorded as one operation so rollback can restore it without an
+     * intermediate same-path conflict. */
+    replaceDirFromSource(path: string, sourceDir: string): void;
     hasOperations(): boolean;
     /** Writes manifest.json. No-op (creates nothing) if zero operations
      * were ever recorded. */

package/dist/lib/backup.js

@@ -9,9 +9,10 @@
  * that never records anything creates nothing on disk.
  */
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { readlink, rm, symlink } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { directoryDigest } from "./dirDigest.js";
 function sha256(content) {
     return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
@@ -88,7 +89,12 @@ export function openBackupSession(homeDir, command) {
             else {
                 operations.push({ kind: "file-create", path, afterHash });
             }
-            writeFileSync(path, content);
+            // A lock/provenance update must not leave a partially-written JSON file
+            // if the process stops mid-write.  This also strengthens the existing
+            // backup-aware file writes without changing their manifest contract.
+            const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${fileIndex}.tmp`);
+            writeFileSync(temporary, content);
+            renameSync(temporary, path);
         },
         async createSymlink(path, linkTarget) {
             ensureDir();
@@ -111,7 +117,7 @@ export function openBackupSession(homeDir, command) {
             ensureDir();
             mkdirSync(path, { recursive: true });
             cpSync(sourceDir, path, { recursive: true });
-            operations.push({ kind: "dir-create", path });
+            operations.push({ kind: "dir-create", path, afterDigest: directoryDigest(path) });
         },
         removeDir(path) {
             ensureDir();
@@ -121,6 +127,18 @@ export function openBackupSession(homeDir, command) {
             rmSync(path, { recursive: true, force: true });
             operations.push({ kind: "dir-remove", path, beforeDir: relSnapshot });
         },
+        replaceDirFromSource(path, sourceDir) {
+            if (!existsSync(path))
+                throw new Error(`Cannot replace missing directory: ${path}`);
+            ensureDir();
+            const relSnapshot = join("dirs", `${dirIndex}-${basename(path)}`);
+            dirIndex += 1;
+            cpSync(path, join(runDir, relSnapshot), { recursive: true });
+            rmSync(path, { recursive: true, force: true });
+            mkdirSync(path, { recursive: true });
+            cpSync(sourceDir, path, { recursive: true });
+            operations.push({ kind: "dir-replace", path, beforeDir: relSnapshot, afterDigest: directoryDigest(path) });
+        },
         hasOperations() {
             return operations.length > 0;
         },

package/dist/lib/dirDigest.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A deterministic digest for a directory tree.  Paths, empty directories,
+ * file bytes, and link targets all contribute to the digest so it can be
+ * used for provenance and for detecting edits before a remote update.
+ */
+/**
+ * Hashes a tree without following symbolic links.  A caller that needs a
+ * stricter source policy can reject links separately; keeping their target in
+ * this digest means a locally added link is still detected as drift.
+ */
+export declare function directoryDigest(dir: string): string;

package/dist/lib/dirDigest.js

@@ -0,0 +1,52 @@
+/**
+ * A deterministic digest for a directory tree.  Paths, empty directories,
+ * file bytes, and link targets all contribute to the digest so it can be
+ * used for provenance and for detecting edits before a remote update.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+function portablePath(path) {
+    return path.split(sep).join("/");
+}
+function addPart(hash, value) {
+    hash.update(String(Buffer.byteLength(value)));
+    hash.update(":");
+    hash.update(value);
+    hash.update("\0");
+}
+/**
+ * Hashes a tree without following symbolic links.  A caller that needs a
+ * stricter source policy can reject links separately; keeping their target in
+ * this digest means a locally added link is still detected as drift.
+ */
+export function directoryDigest(dir) {
+    const hash = createHash("sha256");
+    const walk = (current) => {
+        const rel = portablePath(relative(dir, current)) || ".";
+        const stat = lstatSync(current);
+        if (stat.isDirectory()) {
+            addPart(hash, "directory");
+            addPart(hash, rel);
+            for (const name of readdirSync(current).sort((a, b) => a.localeCompare(b))) {
+                walk(join(current, name));
+            }
+            return;
+        }
+        if (stat.isFile()) {
+            addPart(hash, "file");
+            addPart(hash, rel);
+            addPart(hash, readFileSync(current));
+            return;
+        }
+        if (stat.isSymbolicLink()) {
+            addPart(hash, "symlink");
+            addPart(hash, rel);
+            addPart(hash, readlinkSync(current));
+            return;
+        }
+        throw new Error(`Cannot digest unsupported filesystem entry: ${current}`);
+    };
+    walk(dir);
+    return `sha256:${hash.digest("hex")}`;
+}

package/dist/lib/remoteSkillLock.d.ts

@@ -0,0 +1,26 @@
+/** Durable provenance for remote Skills in ~/.trellis/skills.lock.json. */
+import type { BackupSession } from "./backup.js";
+export declare const REMOTE_SKILL_LOCK_VERSION = 1;
+export interface RemoteSkillLockEntry {
+    source: string;
+    requestedRef: string;
+    commit: string;
+    subdirectory: string;
+    digest: string;
+}
+export interface RemoteSkillLock {
+    version: typeof REMOTE_SKILL_LOCK_VERSION;
+    skills: Record<string, RemoteSkillLockEntry>;
+}
+export type RemoteSkillLockRead = {
+    ok: true;
+    lock: RemoteSkillLock;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function remoteSkillLockPath(homeDir: string): string;
+export declare function emptyRemoteSkillLock(): RemoteSkillLock;
+export declare function readRemoteSkillLock(homeDir: string): RemoteSkillLockRead;
+export declare function serializeRemoteSkillLock(lock: RemoteSkillLock): string;
+export declare function writeRemoteSkillLock(homeDir: string, lock: RemoteSkillLock, backup?: BackupSession): void;

package/dist/lib/remoteSkillLock.js

@@ -0,0 +1,88 @@
+/** Durable provenance for remote Skills in ~/.trellis/skills.lock.json. */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const REMOTE_SKILL_LOCK_VERSION = 1;
+export function remoteSkillLockPath(homeDir) {
+    return join(homeDir, ".trellis", "skills.lock.json");
+}
+export function emptyRemoteSkillLock() {
+    return { version: REMOTE_SKILL_LOCK_VERSION, skills: {} };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validSource(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:"
+            && parsed.hostname === "github.com"
+            && !parsed.username
+            && !parsed.password
+            && !parsed.search
+            && !parsed.hash
+            && /^\/[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9_.-]+\.git$/.test(parsed.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function validEntry(value) {
+    if (!isObject(value))
+        return false;
+    const keys = Object.keys(value).sort();
+    if (keys.join(",") !== "commit,digest,requestedRef,source,subdirectory")
+        return false;
+    return validSource(value.source)
+        && typeof value.requestedRef === "string" && value.requestedRef.length > 0 && !/[\0\r\n]/.test(value.requestedRef)
+        && typeof value.commit === "string" && /^[0-9a-f]{40}$/.test(value.commit)
+        && typeof value.subdirectory === "string" && value.subdirectory.length > 0 && !value.subdirectory.startsWith("/") && !value.subdirectory.split("/").includes("..")
+        && typeof value.digest === "string" && /^sha256:[0-9a-f]{64}$/.test(value.digest);
+}
+function validateLock(value) {
+    if (!isObject(value) || value.version !== REMOTE_SKILL_LOCK_VERSION || !isObject(value.skills) || Object.keys(value).some((key) => key !== "version" && key !== "skills")) {
+        throw new Error("expected version 1 and a skills object");
+    }
+    const skills = {};
+    for (const [name, entry] of Object.entries(value.skills)) {
+        if (!name || name.includes("/") || name.includes("\\") || !validEntry(entry)) {
+            throw new Error(`invalid provenance entry for Skill ${JSON.stringify(name)}`);
+        }
+        skills[name] = entry;
+    }
+    return { version: REMOTE_SKILL_LOCK_VERSION, skills };
+}
+export function readRemoteSkillLock(homeDir) {
+    const path = remoteSkillLockPath(homeDir);
+    try {
+        if (!existsSync(path))
+            return { ok: true, lock: emptyRemoteSkillLock() };
+        return { ok: true, lock: validateLock(JSON.parse(readFileSync(path, "utf8"))) };
+    }
+    catch (error) {
+        return { ok: false, error: `Cannot use ${path}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function serializeRemoteSkillLock(lock) {
+    const valid = validateLock(lock);
+    const skills = Object.fromEntries(Object.entries(valid.skills).sort(([a], [b]) => a.localeCompare(b)));
+    return `${JSON.stringify({ version: REMOTE_SKILL_LOCK_VERSION, skills }, null, 2)}\n`;
+}
+export function writeRemoteSkillLock(homeDir, lock, backup) {
+    const path = remoteSkillLockPath(homeDir);
+    const content = serializeRemoteSkillLock(lock);
+    mkdirSync(dirname(path), { recursive: true });
+    if (backup) {
+        backup.writeFile(path, content);
+        return;
+    }
+    const temporary = join(dirname(path), `.${path.split("/").pop()}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        writeFileSync(temporary, content, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}

package/dist/lib/remoteSkillSource.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Remote Skill source handling.  The public command accepts only GitHub
+ * identities, while the lower-level fetch function intentionally accepts a
+ * repository URL so unit and sandbox tests can use a local bare Git remote.
+ * No command in this module evaluates checked-out content.
+ */
+export interface GitHubRepository {
+    source: string;
+    url: string;
+    owner: string;
+    repository: string;
+}
+export interface RemoteSkillCandidate {
+    name: string;
+    directory: string;
+    subdirectory: string;
+}
+export interface SelectedRemoteSkill extends RemoteSkillCandidate {
+    digest: string;
+}
+export interface FetchedRemoteRepository {
+    repository: {
+        url: string;
+    };
+    requestedRef: string;
+    commit: string;
+    root: string;
+    candidates: readonly RemoteSkillCandidate[];
+    select(name: string): SelectedRemoteSkill;
+    dispose(): void;
+}
+/** Accept the exact two source syntaxes Trellis documents, with no URL state
+ * that could put a credential in the provenance lock. */
+export declare function normalizeGitHubRepository(source: string): GitHubRepository;
+/**
+ * Fetches a single immutable commit into a system temporary directory.  It is
+ * exported with a URL-shaped repository argument to let tests exercise the
+ * real Git protocol against a local bare repo; CLI callers first use
+ * normalizeGitHubRepository and therefore cannot pass arbitrary hosts.
+ */
+export declare function fetchRemoteRepository(repository: {
+    url: string;
+}, opts?: {
+    branch?: string;
+}): FetchedRemoteRepository;