agent-trellis 0.8.2 → 0.9.0

package/dist/lib/remoteSkillSource.js

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+import { execFileSync } from "node:child_process";
+import { lstatSync, mkdtempSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { directoryDigest } from "./dirDigest.js";
+function git(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Git could not read the remote Skill source: ${detail}`);
+    }
+}
+/** Accept the exact two source syntaxes Trellis documents, with no URL state
+ * that could put a credential in the provenance lock. */
+export function normalizeGitHubRepository(source) {
+    const shorthand = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38})?)\/([A-Za-z0-9_.-]+)$/.exec(source);
+    if (shorthand) {
+        const [, owner, repository] = shorthand;
+        return { source, owner: owner, repository: repository, url: `https://github.com/${owner}/${repository}.git` };
+    }
+    let parsed;
+    try {
+        parsed = new URL(source);
+    }
+    catch {
+        throw new Error(`Remote Skill source must be GitHub owner/repository or an HTTPS github.com URL: ${source}`);
+    }
+    const parts = parsed.pathname.split("/").filter(Boolean);
+    if (parsed.protocol !== "https:"
+        || parsed.hostname.toLowerCase() !== "github.com"
+        || parsed.username
+        || parsed.password
+        || parsed.search
+        || parsed.hash
+        || parts.length !== 2
+        || !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})?$/.test(parts[0])
+        || !/^[A-Za-z0-9_.-]+(?:\.git)?$/.test(parts[1])) {
+        throw new Error(`Remote Skill source must be a credential-free HTTPS github.com repository URL: ${source}`);
+    }
+    const owner = parts[0];
+    const repository = parts[1].replace(/\.git$/i, "");
+    return { source, owner, repository, url: `https://github.com/${owner}/${repository}.git` };
+}
+function parseLsRemote(output) {
+    return output.split("\n").flatMap((line) => {
+        const match = /^([0-9a-f]{40})\t(.+)$/.exec(line.trim());
+        return match ? [{ hash: match[1], ref: match[2] }] : [];
+    });
+}
+function resolveDefaultRef(url) {
+    const output = git(["ls-remote", "--symref", url, "HEAD"]);
+    const branch = /^ref:\s+refs\/heads\/([^\s]+)\s+HEAD$/m.exec(output)?.[1];
+    const commit = parseLsRemote(output).find((entry) => entry.ref === "HEAD")?.hash;
+    if (!branch || !commit)
+        throw new Error(`Could not resolve the default branch for ${url}`);
+    return { requestedRef: branch, commit };
+}
+function resolveRequestedRef(url, requestedRef) {
+    if (!requestedRef || /[\0\r\n]/.test(requestedRef))
+        throw new Error("--branch must be a non-empty Git ref");
+    const entries = parseLsRemote(git(["ls-remote", url, requestedRef]));
+    const peeled = entries.find((entry) => entry.ref.endsWith("^{}"));
+    const direct = entries.find((entry) => !entry.ref.endsWith("^{}"));
+    const selected = peeled ?? direct;
+    if (!selected)
+        throw new Error(`Remote source has no ref named ${requestedRef}`);
+    return { requestedRef, commit: selected.hash };
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !rel.startsWith("..\/"));
+}
+function walkDirectories(root) {
+    const dirs = [];
+    const walk = (current) => {
+        dirs.push(current);
+        for (const name of readdirSync(current).sort((a, b) => a.localeCompare(b))) {
+            // The Git administration directory is implementation state, never
+            // source content to inspect for a Skill candidate.
+            if (current === root && name === ".git")
+                continue;
+            const entry = join(current, name);
+            const stat = lstatSync(entry);
+            if (stat.isDirectory())
+                walk(entry);
+        }
+    };
+    walk(root);
+    return dirs;
+}
+function candidatesIn(root) {
+    return walkDirectories(root).flatMap((directory) => {
+        const names = readdirSync(directory);
+        const exact = names.find((name) => name === "SKILL.md");
+        if (!exact)
+            return [];
+        const entry = join(directory, exact);
+        // A non-file `SKILL.md` is deliberately not advertised as a valid
+        // candidate; selecting this directory produces a precise error below.
+        if (!lstatSync(entry).isFile())
+            return [];
+        return [{ name: basename(directory), directory, subdirectory: relative(root, directory).split(sep).join("/") }];
+    });
+}
+function validateSelectedDirectory(root, directory, expectedName) {
+    if (basename(directory) !== expectedName)
+        throw new Error(`Selected remote Skill directory is not named ${expectedName}`);
+    const rootReal = realpathSync(root);
+    const walk = (current) => {
+        const stat = lstatSync(current);
+        if (stat.isSymbolicLink())
+            throw new Error(`Remote Skill ${expectedName} contains a symbolic link: ${current}`);
+        const resolved = realpathSync(current);
+        if (!isInside(rootReal, resolved))
+            throw new Error(`Remote Skill ${expectedName} resolves outside the fetched repository`);
+        if (!stat.isDirectory())
+            return;
+        for (const name of readdirSync(current))
+            walk(join(current, name));
+    };
+    const entry = join(directory, "SKILL.md");
+    const entryStat = lstatSync(entry);
+    if (entryStat.isSymbolicLink()) {
+        const resolvedEntry = realpathSync(entry);
+        if (!isInside(rootReal, resolvedEntry))
+            throw new Error(`Remote Skill ${expectedName} entry file resolves outside the fetched repository`);
+        throw new Error(`Remote Skill ${expectedName} entry file must not be a symbolic link`);
+    }
+    if (!entryStat.isFile())
+        throw new Error(`Remote Skill ${expectedName} has no regular, exact-case SKILL.md`);
+    walk(directory);
+    return {
+        name: expectedName,
+        directory,
+        subdirectory: relative(root, directory).split(sep).join("/"),
+        digest: directoryDigest(directory),
+    };
+}
+/**
+ * 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 function fetchRemoteRepository(repository, opts = {}) {
+    const resolvedRef = opts.branch === undefined ? resolveDefaultRef(repository.url) : resolveRequestedRef(repository.url, opts.branch);
+    const temp = mkdtempSync(join(tmpdir(), "trellis-remote-skill-"));
+    let disposed = false;
+    try {
+        git(["init", "--quiet"], temp);
+        git(["remote", "add", "origin", repository.url], temp);
+        git(["fetch", "--quiet", "--depth=1", "origin", resolvedRef.commit], temp);
+        git(["checkout", "--quiet", "--detach", "FETCH_HEAD"], temp);
+        const actualCommit = git(["rev-parse", "HEAD"], temp).trim();
+        if (!/^[0-9a-f]{40}$/.test(actualCommit))
+            throw new Error("Git did not produce an immutable commit identifier");
+        const root = resolve(temp);
+        const candidates = candidatesIn(root);
+        return {
+            repository: { url: repository.url },
+            requestedRef: resolvedRef.requestedRef,
+            commit: actualCommit,
+            root,
+            candidates,
+            select(name) {
+                const matchingDirectories = walkDirectories(root).filter((directory) => basename(directory) === name);
+                if (matchingDirectories.length === 0) {
+                    const available = candidates.map((candidate) => candidate.name).sort().join(", ") || "none";
+                    throw new Error(`Remote source has no Skill named ${name}. Available Skills: ${available}`);
+                }
+                const withEntry = matchingDirectories.filter((directory) => {
+                    try {
+                        return readdirSync(directory).includes("SKILL.md");
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (withEntry.length !== 1) {
+                    if (withEntry.length === 0)
+                        throw new Error(`Remote Skill ${name} has no regular, exact-case SKILL.md`);
+                    throw new Error(`Remote source contains multiple Skills named ${name}; select a repository with one matching Skill`);
+                }
+                return validateSelectedDirectory(root, withEntry[0], name);
+            },
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                rmSync(temp, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        rmSync(temp, { recursive: true, force: true });
+        throw error;
+    }
+}

package/docs/getting-started.md

@@ -614,6 +614,74 @@ trellis skill update-builtin
 The update is backed up and updates the canonical file in place; native Agent
 symlinks and Runtime providers then consume the same refreshed content.
 
+### Importing a GitHub Skill with Trellis ownership
+
+If you would normally run `npx skills add`, use Trellis's top-level `add`
+command instead. It is a remote-source importer, while `trellis skill add`
+remains the command for a local directory:
+
+```sh
+# Review exact-case SKILL.md candidates before selecting one.
+npx trellis add mattpocock/skills --list
+
+# Fetch and inspect the exact plan without writing canonical or Agent files.
+npx trellis add mattpocock/skills --skill loop-me --dry-run
+
+# Import to the user-level canonical store, then sync to every managed Agent.
+npx trellis add mattpocock/skills --skill loop-me --yes
+```
+
+The source may be `owner/repository` or a credential-free HTTPS
+`github.com` repository URL. Trellis fetches the selected ref into a system
+temporary directory, discovers a directory containing an exact-case
+`SKILL.md`, and copies that directory into
+`~/.trellis/skills/<name>/`. It does not run repository scripts, install
+dependencies, or write into `.agents/skills`, `~/.agents/skills`, or any
+Agent-specific Skill directory during import. Review the imported
+`SKILL.md` before relying on it in an Agent session.
+
+By default the imported Skill is unscoped, which means every Agent currently
+listed in `~/.trellis/managed.yaml` receives it on sync. Restrict delivery to
+managed Agents with `--agent`; comma-separated values and repeated flags are
+accepted. `--agent '*'` writes the current managed set as an explicit scope.
+An Agent that is installed but unmanaged is refused before any canonical or
+native write. Add it to Trellis's managed boundary first:
+
+```sh
+trellis manage add zcode
+npx trellis add mattpocock/skills --skill loop-me --agent zcode --yes
+```
+
+`--branch <ref>` selects a Git branch, tag, or ref. Without it, Trellis asks
+Git for the repository's default branch. `--global` is accepted for
+`skills`-CLI compatibility and still means Trellis's existing user-level
+canonical store; `--copy` and project-local modes are refused because they
+would create another Skill source outside Trellis.
+
+Each successful remote import writes
+`~/.trellis/skills.lock.json` in the same backup session as its canonical
+Skill directory. The lock records the normalized GitHub URL, requested ref,
+resolved immutable commit, source subdirectory, and deterministic content
+digest. It never records credentials or a temporary path. `trellis skill
+list` marks remote Skills with their source and short locked commit; JSON
+output includes the complete credential-free provenance record.
+
+Refresh tracked Skills with:
+
+```sh
+trellis update loop-me --dry-run
+trellis update loop-me
+trellis update                 # check every tracked remote Skill
+```
+
+Before replacement, `trellis update` compares the current canonical directory
+to its locked digest. A local canonical edit is a conflict and is never
+overwritten. A successful update preserves the Skill's scope, replaces its
+directory and provenance record in one backup session, and then runs Skill
+sync. Use `trellis rollback --list` to find a `remote-skill-add` or
+`remote-skill-update` run; rolling it back restores the previous directory
+and matching lock record when neither has changed since the run.
+
 ```
 $ trellis mcp list
 tanka (http) — codex, pi
@@ -1012,9 +1080,10 @@ scripts/agent-sandbox.sh --status kiro
 Git，也不会自动读取或删除宿主机凭据。清理时请明确执行
 `docker volume rm <volume-name>`。
 
-## `trellis rollback` — undoing a `sync`/`mcp sync`/`onboard` run
+## `trellis rollback` — undoing a managed write run
 
-Every real write those three commands perform is recorded, before it
+Every real `sync`, `mcp sync`, `onboard`, remote Skill import, and remote Skill
+update write is recorded, before it
 happens, to a structured run directory under `~/.trellis/backups/` — no
 flag needed, this is always on for any run that actually writes
 something. `--dry-run` never creates one, since nothing was written.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",