agent-trellis 0.8.2 → 0.9.1

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.1",
   "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",
@@ -23,7 +23,9 @@
   "files": [
     "dist",
     "schema",
-    "docs"
+    "docs/*.md",
+    "docs/assets/brand-v3",
+    "docs/assets/poster-series-v3"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build-pi-bridge.mjs",

package/docs/video/README.md

@@ -1,76 +0,0 @@
-# Trellis 分享视频 · 素材与录制清单
-
-> 本目录（`docs/video/`）在 `.gitignore` 中，所有内容只存在于本地，
-> 不会进入开源仓库。
-
-## 自动生成视频
-
-```bash
-node docs/video/generate-video.mjs   # 输出 docs/video/trellis-demo-video.mp4
-```
-
-一条命令完成：重置沙盒 → 真实跑一遍 CLI 并捕获输出 → 渲染终端帧与卡片
-（qlmanage）→ 系统 TTS 生成中文口播（Ting-Ting Enhanced）→ ffmpeg 合成
-1920×1080 mp4。改口播文案直接编辑脚本里的 `blocks[].narration`；终端帧
-内容来自真实命令输出，无需手改。依赖：ffmpeg（`brew install ffmpeg`）、
-macOS 自带的 qlmanage/sips/say/afinfo。
-
-## 演示沙盒（不碰真实配置）
-
-```bash
-bash scripts/video-demo-setup.sh        # 生成/重置演示环境到 /tmp/trellis-demo-home
-export HOME=/tmp/trellis-demo-home      # 之后所有 trellis 命令都在沙盒里运行
-```
-
-沙盒内容：Claude Code（1 份指令 + 2 个 Skill + 2 个 MCP 服务器）、
-Codex（config.toml + 1 个 MCP 服务器）。每次重录前重跑 setup 脚本即可
-回到初始状态。已验证全流程可跑通：`init → onboard --dry-run → onboard →
-doctor → rollback`。
-
-录制用命令（已跳过交互选择，流程不打断）：
-
-```bash
-trellis init
-trellis onboard --dry-run --agent claude-code --manage codex
-trellis onboard --agent claude-code --manage codex
-trellis doctor
-trellis rollback
-```
-
-## 终端与录屏设置
-
-| 项 | 建议 |
-|---|---|
-| 终端主题 | 浅色（手机端观看对比度更好） |
-| 字号 | 20–24pt，观众多用手机看 |
-| 提示符 | `export PS1='$ '`，干净无干扰 |
-| 窗口 | 1280×720 或 1440×810 逻辑分辨率 |
-| 录屏 | Kap / QuickTime；每条 take 前 `clear` |
-| 导出 | 横屏 1920×1080（B 站/YouTube）；竖屏 1080×1920（视频号/小红书）则后期裁切，注意命令别超出安全区 |
-
-## 分镜与素材对照
-
-| 场景 | 画面 | 素材 |
-|---|---|---|
-| 1 开场 | 终端/编辑器随意状态 | 现场录 |
-| 2 痛点 | `ls ~/.claude` `ls ~/.codex`（真实目录，只读） | 现场录 |
-| 3 方案 | 海报全屏 | [`../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png) |
-| 4 演示 | 终端实录 | 沙盒命令（见上） |
-| 5 设计点 | README Design principles 滚动 | github.com/paul-leo/Trellis |
-| 6 收尾 | GitHub 仓库首页 + Star 按钮停留 2 秒 | 同上 |
-
-## 其他可用素材
-
-- 封面图/片尾卡：[`../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png)
-- Logo 叠层（角标）：[`../assets/brand-v3/trellis-mark-v3-a.svg`](../assets/brand-v3/trellis-mark-v3-a.svg)
-- 口播逐字稿：[voiceover.zh-CN.md](voiceover.zh-CN.md)
-- 场景大纲：[outline.zh-CN.md](outline.zh-CN.md)
-- 60 秒极简版：见 [outline.zh-CN.md](outline.zh-CN.md) 末尾
-
-## 录制前 Checklist
-
-- [ ] 重跑 `bash scripts/video-demo-setup.sh` 重置沙盒
-- [ ] `export HOME=/tmp/trellis-demo-home && export PS1='$ ' && clear`
-- [ ] 终端字号调大，关闭通知（勿扰模式）
-- [ ] 预演一遍场景 4，确认输出与口播一致
-- [ ] 麦克风电平测试 5 秒

package/docs/video/build/segments/01-opening.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'
-duration 11.053
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'

package/docs/video/build/segments/02-pain.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-1.png'
-duration 2.172
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'
-duration 5.068
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'

package/docs/video/build/segments/03-solution.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'
-duration 6.482
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'

package/docs/video/build/segments/04-install.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'
-duration 2.407
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'

package/docs/video/build/segments/04-setup.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-setup-4.png'
-duration 4.131
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-setup-4.png'

package/docs/video/build/segments/05-dryrun.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-dryrun-6.png'
-duration 7.031
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-dryrun-6.png'

package/docs/video/build/segments/05-init.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-init-5.png'
-duration 6.587
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-init-5.png'

package/docs/video/build/segments/05-interactive.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-5.png'
-duration 1.952
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-6.png'
-duration 4.556
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-6.png'

package/docs/video/build/segments/06-dryrun.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-dryrun-6.png'
-duration 14.763
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-dryrun-6.png'

package/docs/video/build/segments/06-onboard.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-7.png'
-duration 1.537
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-8.png'
-duration 3.587
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-8.png'