@liuovo/skills 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @liuovo/skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+自己的 Skills，加上一份精选的外部引用清单。用一个向导选择本次要安装的内容，真正的安装交给固定版本的 [`skills`](https://github.com/vercel-labs/skills)。
+
+**当前状态：本地可开发、构建和打包，尚未发布 npm。** `@liuovo/skills` 是拟用包名，未核实 npm 所有权和可用性。
+
+## 本地使用
+
+需要 Node.js >= 22.20.0、pnpm，以及安装远程来源时可用的 Git / GitHub 网络。
+
+```bash
+pnpm install
+
+# 无参数：搜索多选 Skills → 项目/全局 → Agent → 确认
+pnpm dev
+
+# 查看全部引用，不下载上游内容
+pnpm dev list
+
+# 只生成安装计划，不下载、不写入
+pnpm dev --skill handoff grilling --project --agent codex --dry-run
+
+# 参数只跳过对应问题：这里仍会询问 Skills 和 Agent
+pnpm dev --global
+
+# 明确的非交互安装
+pnpm dev --skill handoff --global --agent codex -y
+```
+
+项目级安装以**启动命令时的工作目录**为准。在本仓库运行 `pnpm dev --project` 就是安装到本仓库。构建后，可以在另一个项目中调用 CLI 文件的绝对路径：
+
+```bash
+pnpm build
+cd /path/to/target-project
+node /path/to/this-repository/dist/cli.js
+```
+
+发布后，用户入口才是：
+
+```bash
+pnpx @liuovo/skills
+```
+
+`-y` 只跳过交互与确认，不代表全选，也不允许覆盖。无终端、CI、`--json` 或 `-y` 模式必须明确 Skills、范围和 Agent。安装还需要 `-y` 确认；预览不需要。
+
+### 中文分类选择
+
+仅 Skill 的一句话描述和分类名称使用中文；向导问题、键盘操作提示、帮助、确认、安装结果和错误信息使用英文。Skill 名称、命令参数和 JSON 状态值保留原名，便于复制命令及脚本调用。
+
+| 分类           | 内容                                   |
+| -------------- | -------------------------------------- |
+| 方案推敲       | 通过追问和质询完善方案、检验决策       |
+| 协作与表达     | 对话交接、Agent 文档、减少阅读干扰     |
+| 代码设计与重构 | 模块设计、代码改进、重复代码治理       |
+| 前端设计       | 界面视觉与交互设计                     |
+| Vue 开发       | Vue、路由、Pinia、测试、调试与组合函数 |
+
+选择界面显示分类标题和每项的一句话中文用途。直接输入名称、中文用途、分类或仓库名即可搜索；多个关键词以空格分隔。`↑/↓` 移动，`Tab` 勾选或取消，`Enter` 确认，`Esc` 退出。切换搜索词会保留之前勾选的项目，可以跨分类选择。
+
+## 安装规则
+
+- 不传 `--skill` 时搜索多选；`--all` 才选择本清单全部条目，不会安装上游仓库全部 Skills。
+- `--project` 和 `--global` 互斥；缺省时询问，不猜测全局范围。
+- 第一版只适配并验证 `codex`、`claude-code`、`opencode`。其他 Agent 不会直接透传给底层。
+- 默认跳过所有已有同名路径，包括手写目录、文件和失效符号链接。锁文件中的来源只用于展示，不被当作“可安全覆盖”的证明。
+- `--overwrite` 明确允许替换已有目标目录及其中的用户修改；可先与 `--dry-run` 组合查看。已有目录的内容不会自动备份。
+- 父目录含符号链接、锁文件损坏或版本不兼容时拒绝安装。即使传 `--overwrite` 也不会绕过这些检查。
+- 已有旧位置的同名 Codex / OpenCode Skill 时，要求手动核对；本工具不会帮你迁移、删除它们。
+- 未勾选不等于卸载；移除清单引用也不会清理机器上的已有安装。
+- 安装按来源串行执行，一项失败会明确报告；已成功的安装不会因其他来源失败被删除。
+- Ctrl+C 停止当前安装并不再启动后续来源。安装不是事务，超时或中断后可能留下部分文件，需要查看结果后重试。
+
+安装前检查会在确认后、每个来源启动前再次执行，但不能与其他独立进程的写入形成原子事务。**不要同时运行多个安装／更新命令操作同一个目标目录。**
+
+### Agent 目录
+
+固定的 `skills@1.7.2` 使用以下布局：
+
+| Agent       | 项目级                                 | 全局                                     |
+| ----------- | -------------------------------------- | ---------------------------------------- |
+| Codex       | `.agents/skills/<name>`                | `~/.agents/skills/<name>`                |
+| OpenCode    | 与 Codex 共用                          | 与 Codex 共用                            |
+| Claude Code | `.claude/skills/<name>` 链接到共享目录 | `~/.claude/skills/<name>` 链接到共享目录 |
+
+全局 Claude Code 遵循 `CLAUDE_CONFIG_DIR`。`CODEX_HOME`、`XDG_CONFIG_HOME` 用于检查旧位置冲突；它们不会改变此版本安装器的共享目录。
+
+选择 Agent **不代表对其他 Agent 隔离**；其他会扫描共享目录的 Agent 也可能发现这些 Skills。第一版固定使用安装器默认的规范目录加符号链接模式，不提供持久依赖 `pnpx` 临时目录的本地链接。
+
+项目锁文件由底层维护为 `skills-lock.json`；全局锁默认是 `~/.agents/.skill-lock.json`，设置 `XDG_STATE_HOME` 时位于其 `skills/` 子目录。封装不维护第二套锁文件，不自动恢复或重写损坏的旧锁。
+
+## 维护清单
+
+外部引用的唯一列表是 `package.json` 的 `skills` 字段，格式借鉴 [`antfu/skills-pack`](https://github.com/antfu/skills-pack)：
+
+```json
+{
+  "skills": [
+    {
+      "source": "mattpocock/skills",
+      "skills": ["handoff", "grilling"]
+    }
+  ]
+}
+```
+
+`skillsPack.metadata["owner/repo@skill-name"]` 保存一句话中文 `description`、分类 `category` 和上游目录 `path`。`skillsPack.categories` 控制分类顺序；新增分类时也要加入此数组。没有分类的条目归入“其他”，自有内容归入“自有 Skills”。**路径必须指向上游，中文说明只是本地展示元数据，不改写上游 Skill 正文。**
+
+当前有 15 个引用，来自 Matt Pocock、shadcn、kucherenko、ayghri、vuejs-ai 和 Anthropic。用 `pnpm dev list` 查看完整目录，或 `pnpm dev list --json` 获取名称、来源、说明和链接。
+
+第一版的来源支持 GitHub `owner/repo`，按上游默认分支安装；尚不支持清单级固定 ref、嵌套技能包或预设组合。外部内容和许可归各上游，本项目的引用不重新许可这些内容。
+
+### 添加自己的 Skill
+
+将自己的完整 Skill 目录放进 `skills/`，例如 `skills/my-workflow/SKILL.md`。CLI 递归发现其中带合法 `name`、`description` 的 YAML frontmatter；脚本和参考文件可以放在旁边。
+
+本仓库目前没有自有 Skill 正文，也没有示例 Skill 混入安装列表。
+
+自有项的安装来源由 `skillsPack.ownSource` 指定，当前是 `liuc-c/skills`。**CLI 读取本地／npm 包中的自有目录来展示，但实际安装仍从这个 GitHub 仓库获取；未推送的自有内容不会被安装。** 先推送自有内容、再发布目录包，确保目录与上游一致。开发中的未推送 Skill 可用底层 `skills add` 的本地路径模式单独测试。
+
+同名不同来源可以在目录中共存，但选择时必须用 `owner/repo@name` 消歧；同一次安装不能选择两个同名项，因为底层目标目录按 Skill 名称命名。
+
+`pnpx skills add liuc-c/skills` 只发现仓库中的实际自有 Skills，不是本包混合引用目录的入口。
+
+## 更新、验证与发布
+
+包版本、引用清单版本和上游内容版本是不同的东西：
+
+- 更新 `@liuovo/skills` 获得新的目录和 CLI；不会自动更新机器上的 Skills。
+- 重装明确选中的内容，需要显式 `--overwrite`；获取的是那次执行时的上游内容，不保证和上次相同。
+- 现有底层锁文件仍可由 `skills` 的原生命令使用，但其更新行为不经过本封装的冲突检查。
+- 没有定时镜像、自动同步删除、自动安装钩子或后台任务。
+
+```bash
+pnpm check       # 类型、单元测试、真实安装器隔离测试、格式
+pnpm build
+pnpm pack       # 构建并生成本地 tarball，不发布
+```
+
+测试使用临时项目和隔离 HOME / XDG / Agent 配置，真实调用固定版本安装器安装本地 fixture，覆盖项目级与全局落盘、复制参考文件、符号链接、锁文件、保留用户修改和显式覆盖，不需要 GitHub 网络，也不修改开发者的真实 Skills。
+
+升级 `skills` 依赖时，同时更新 `src/install.ts` 的版本约束，并重新核对目录布局、JSON 返回结构及锁文件版本，再运行隔离测试。不要无验证升级到浮动版本。
+
+发布前还需要确认 npm 包名所有权、选择本项目许可证，并准备远程仓库。目前 `license: UNLICENSED`，表示本项目尚未授予开源许可，不影响引用指向上游各自的许可。
+
+### 使用 bumpp 发布到 npm
+
+发布开发环境需要满足 `bumpp` 的 Node.js 要求：`^22.18.0 || ^24.11.0 || >=26.0.0`，并同时满足本项目的 `>=22.20.0`。例如可使用 Node.js 22.20+（22.x）或 24.11+（24.x）。
+
+首次发布前：
+
+1. 确认拥有 npm 的 `@liuovo` scope 和 `@liuovo/skills` 发布权限，使用 `npm login --registry=https://registry.npmjs.org/` 登录；发布时按 npm 提示完成认证。
+2. 配置 Git remote，并先将 `main` 推送、建立 upstream（例如确认远程地址后执行 `git push -u origin main`）。
+3. 确认包名、仓库地址和许可证，提交所有待发布改动，保持工作区干净。
+
+```bash
+# 检查、构建并预览 npm 包内容；不改版本、不提交、不推送、不发布
+pnpm release:check
+
+# 交互选择版本并确认，然后提交、打标签、推送、发布 npm
+pnpm release
+```
+
+`pnpm release` 使用固定版本的 bumpp，读取 `bump.config.ts`：
+
+- 拒绝未提交的改动；变更版本前检查分支 upstream，并执行 `pnpm check`。
+- 只更新 `package.json` 的版本，生成 `chore: release v<版本号>` 提交和 `v<版本号>` 标签。
+- 先推送当前分支，再推送标签；沿用 bumpp 的 `git push --tags` 行为，会推送所有尚未同步的本地标签，发布前请核对。
+- 只有 bumpp 成功结束才执行 `pnpm publish`；取消选择、检查失败或推送失败都不会进入 npm 发布。
+- npm 发布前再次检查，由 `prepack` 构建 `dist`；目标固定为 npm 官方 registry，scoped 包公开发布。
+
+直接运行交互式 `pnpm release` 即可，**不要在后面追加 `patch` / `minor` 等参数**，这条串联脚本不会把参数传给 bumpp。版本选择在向导里完成。当前版本为 `0.1.0`，正常选择 patch 会发布 `0.1.1`；如果首次希望发布现有的 `0.1.0`，完成上述准备后单独执行 `pnpm publish`，不会自动生成 Git 标签。
+
+Git 推送与 npm 发布不是一个事务。如果推送成功、npm 发布失败，提交和标签会保留：先确认该版本是否已经出现在 npm，再排查认证／权限等问题；未发布成功时可以直接重试 `pnpm publish`，不要为了重试再次增加版本号。若 bumpp 在提交、打标签或推送阶段中断，也应先检查本地版本、提交、标签和远程状态，再决定如何继续。

package/dist/args.d.ts

@@ -0,0 +1,14 @@
+import { type Agent, type Scope } from "./types.js";
+export interface Options {
+    command: "install" | "list" | "help" | "version";
+    names: string[];
+    agents: Agent[];
+    scope?: Scope;
+    all: boolean;
+    yes: boolean;
+    dryRun: boolean;
+    overwrite: boolean;
+    json: boolean;
+}
+export declare function parseArgs(args: string[]): Options;
+export declare const help = "Usage: liuovo-skills [install] [options]\n       liuovo-skills list [--json]\n\nNo arguments: choose skills, scope, and agents interactively.\n\n  -s, --skill <names...>   Select names or owner/repo@name identifiers\n      --all               Select the entire curated catalog (not all upstream skills)\n  -g, --global            Install for the current user\n      --project           Install in the current working directory\n  -a, --agent <agents...>  codex, claude-code, opencode\n  -y, --yes               Skip prompts; requires skills, scope, and agents\n      --overwrite         Explicitly allow replacing existing skill paths\n      --dry-run           Inspect the plan; no downloads or writes\n      --json              Machine-readable list, plan, or results; no prompts\n  -h, --help              Show help\n  -v, --version           Show package version\n\nExisting skills are skipped unless --overwrite is provided.\n--yes does not select all skills or authorize overwrites.\nCodex and OpenCode share .agents/skills in the pinned installer.\n";

package/dist/args.js

@@ -0,0 +1,99 @@
+import { AGENTS } from "./types.js";
+export function parseArgs(args) {
+    const options = {
+        command: "install",
+        names: [],
+        agents: [],
+        all: false,
+        yes: false,
+        dryRun: false,
+        overwrite: false,
+        json: false,
+    };
+    let i = 0;
+    if (["install", "list"].includes(args[0] ?? "")) {
+        options.command = args[0];
+        i++;
+    }
+    for (; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h")
+            options.command = "help";
+        else if (arg === "--version" || arg === "-v")
+            options.command = "version";
+        else if (arg === "--global" || arg === "-g" || arg === "--project") {
+            const scope = arg === "--project" ? "project" : "global";
+            if (options.scope && options.scope !== scope) {
+                throw new Error("--project and --global are mutually exclusive.");
+            }
+            options.scope = scope;
+        }
+        else if (arg === "--all")
+            options.all = true;
+        else if (arg === "--yes" || arg === "-y")
+            options.yes = true;
+        else if (arg === "--dry-run")
+            options.dryRun = true;
+        else if (arg === "--overwrite")
+            options.overwrite = true;
+        else if (arg === "--json")
+            options.json = true;
+        else if (["--skill", "-s", "--agent", "-a"].includes(arg)) {
+            const values = [];
+            while (args[i + 1] && !args[i + 1].startsWith("-")) {
+                values.push(args[++i]);
+            }
+            if (!values.length)
+                throw new Error(`${arg} requires at least one value.`);
+            if (arg === "--skill" || arg === "-s")
+                options.names.push(...values);
+            else {
+                for (const value of values) {
+                    if (!AGENTS.includes(value)) {
+                        throw new Error(`Unknown agent "${value}". Supported: ${AGENTS.join(", ")}`);
+                    }
+                    options.agents.push(value);
+                }
+            }
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}. Run --help for usage.`);
+        }
+    }
+    if (options.all && options.names.length) {
+        throw new Error("--all and --skill are mutually exclusive.");
+    }
+    if (options.command === "list" &&
+        (options.all ||
+            options.names.length ||
+            options.agents.length ||
+            options.scope ||
+            options.yes ||
+            options.dryRun ||
+            options.overwrite)) {
+        throw new Error("list only accepts --json.");
+    }
+    options.agents = [...new Set(options.agents)];
+    return options;
+}
+export const help = `Usage: liuovo-skills [install] [options]
+       liuovo-skills list [--json]
+
+No arguments: choose skills, scope, and agents interactively.
+
+  -s, --skill <names...>   Select names or owner/repo@name identifiers
+      --all               Select the entire curated catalog (not all upstream skills)
+  -g, --global            Install for the current user
+      --project           Install in the current working directory
+  -a, --agent <agents...>  codex, claude-code, opencode
+  -y, --yes               Skip prompts; requires skills, scope, and agents
+      --overwrite         Explicitly allow replacing existing skill paths
+      --dry-run           Inspect the plan; no downloads or writes
+      --json              Machine-readable list, plan, or results; no prompts
+  -h, --help              Show help
+  -v, --version           Show package version
+
+Existing skills are skipped unless --overwrite is provided.
+--yes does not select all skills or authorize overwrites.
+Codex and OpenCode share .agents/skills in the pinned installer.
+`;

package/dist/catalog.d.ts

@@ -0,0 +1,6 @@
+import type { Skill } from "./types.js";
+export declare const packageRoot: string;
+export declare function validateName(name: unknown): asserts name is string;
+export declare function loadCatalog(root?: string): Promise<Skill[]>;
+export declare function groupByCategory(catalog: Skill[]): Map<string, Skill[]>;
+export declare function selectSkills(catalog: Skill[], names: string[]): Skill[];

package/dist/catalog.js

@@ -0,0 +1,162 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+export const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function validateName(name) {
+    if (typeof name !== "string" ||
+        !/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(name) ||
+        name.length > 64) {
+        throw new Error(`Invalid skill name: ${String(name)}`);
+    }
+}
+function validateSource(source) {
+    if (typeof source !== "string" ||
+        !/^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+$/.test(source)) {
+        throw new Error(`Expected a GitHub owner/repo source: ${String(source)}`);
+    }
+}
+export async function loadCatalog(root = packageRoot) {
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    if (!record(pkg) ||
+        !Array.isArray(pkg.skills) ||
+        !record(pkg.skillsPack) ||
+        !record(pkg.skillsPack.metadata)) {
+        throw new Error("Invalid package.json skills / skillsPack configuration.");
+    }
+    const metadata = pkg.skillsPack.metadata;
+    const categories = pkg.skillsPack.categories ?? [];
+    if (!Array.isArray(categories) ||
+        categories.some((category) => typeof category !== "string" || !category.trim()) ||
+        new Set(categories).size !== categories.length) {
+        throw new Error("skillsPack.categories must be an array of unique, non-empty category names.");
+    }
+    const categoryOrder = ["自有 Skills", ...categories, "其他"];
+    validateSource(pkg.skillsPack.ownSource);
+    const ownSource = pkg.skillsPack.ownSource;
+    const catalog = [];
+    for (const group of pkg.skills) {
+        if (!record(group) || !Array.isArray(group.skills)) {
+            throw new Error("Each skills entry needs a source and a skills array.");
+        }
+        validateSource(group.source);
+        for (const name of group.skills) {
+            validateName(name);
+            const id = `${group.source}@${name}`;
+            const meta = metadata[id];
+            if (!record(meta) ||
+                typeof meta.description !== "string" ||
+                !meta.description.trim() ||
+                typeof meta.path !== "string" ||
+                !/^skills\/[a-zA-Z0-9_/-]+$/.test(meta.path) ||
+                meta.path.split("/").some((part) => !part)) {
+                throw new Error(`Missing or invalid display metadata for ${id}.`);
+            }
+            const category = meta.category ?? "其他";
+            if (typeof category !== "string" || !category.trim()) {
+                throw new Error(`Category must be a non-empty string for ${id}.`);
+            }
+            if (categories.length && !categoryOrder.includes(category)) {
+                throw new Error(`Category for ${id} is not declared in skillsPack.categories: ${category}`);
+            }
+            catalog.push({
+                id,
+                name,
+                source: group.source,
+                kind: "external",
+                description: meta.description,
+                category,
+                url: `https://github.com/${group.source}/blob/HEAD/${meta.path}/SKILL.md`,
+            });
+        }
+    }
+    async function walk(directory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        if (entries.some((entry) => entry.name === "SKILL.md" && entry.isFile())) {
+            const text = await readFile(join(directory, "SKILL.md"), "utf8");
+            const header = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+            const data = header === undefined ? undefined : parse(header);
+            if (!record(data) ||
+                typeof data.description !== "string" ||
+                !data.description.trim()) {
+                throw new Error(`Invalid skill frontmatter: ${directory}/SKILL.md`);
+            }
+            validateName(data.name);
+            catalog.push({
+                id: `${ownSource}@${data.name}`,
+                name: data.name,
+                description: data.description,
+                category: "自有 Skills",
+                source: ownSource,
+                kind: "own",
+                url: `https://github.com/${ownSource}/blob/HEAD/${relative(root, directory).split(sep).join("/")}/SKILL.md`,
+            });
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() &&
+                !entry.name.startsWith(".") &&
+                entry.name !== "node_modules") {
+                await walk(join(directory, entry.name));
+            }
+        }
+    }
+    await walk(join(root, "skills"));
+    const ids = new Set();
+    for (const skill of catalog) {
+        if (ids.has(skill.id))
+            throw new Error(`Duplicate catalog entry: ${skill.id}`);
+        ids.add(skill.id);
+    }
+    const categoryRank = (category) => {
+        const rank = categoryOrder.indexOf(category);
+        return rank === -1 ? categoryOrder.length : rank;
+    };
+    return catalog.sort((a, b) => categoryRank(a.category) - categoryRank(b.category) ||
+        a.category.localeCompare(b.category, "zh-CN") ||
+        a.source.localeCompare(b.source) ||
+        a.name.localeCompare(b.name));
+}
+export function groupByCategory(catalog) {
+    const groups = new Map();
+    for (const skill of catalog) {
+        const group = groups.get(skill.category) ?? [];
+        group.push(skill);
+        groups.set(skill.category, group);
+    }
+    return groups;
+}
+export function selectSkills(catalog, names) {
+    const selected = names.map((name) => {
+        const matches = catalog.filter((skill) => skill.id === name || skill.name === name);
+        if (matches.length === 0)
+            throw new Error(`Unknown skill: ${name}`);
+        if (matches.length > 1) {
+            throw new Error(`Ambiguous skill "${name}". Use one of: ${matches.map((s) => s.id).join(", ")}`);
+        }
+        return matches[0];
+    });
+    const unique = [
+        ...new Map(selected.map((skill) => [skill.id, skill])).values(),
+    ];
+    const installedNames = new Set();
+    for (const skill of unique) {
+        if (installedNames.has(skill.name)) {
+            throw new Error(`Multiple sources selected for "${skill.name}". Choose only one.`);
+        }
+        installedNames.add(skill.name);
+    }
+    return unique;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs, help } from "./args.js";
+import { groupByCategory, loadCatalog, packageRoot } from "./catalog.js";
+import { createPlan, publicPlan } from "./plan.js";
+import { executePlan, INSTALLER_VERSION } from "./install.js";
+import { Cancelled, choose, confirmInstall } from "./ui.js";
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.command === "help") {
+        console.log(help);
+        return;
+    }
+    if (options.command === "version") {
+        const pkg = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+        console.log(`${pkg.name} ${pkg.version} (skills ${INSTALLER_VERSION})`);
+        return;
+    }
+    const catalog = await loadCatalog();
+    if (options.command === "list") {
+        if (options.json)
+            console.log(JSON.stringify(catalog, null, 2));
+        else {
+            for (const [category, skills] of groupByCategory(catalog)) {
+                console.log(`\n${category} (${skills.length} skills)`);
+                for (const skill of skills) {
+                    console.log(`  ${skill.name} — ${skill.description}\n    Source: ${skill.source}${skill.kind === "own" ? " (own)" : ""}`);
+                }
+            }
+            console.log(`\n${catalog.length} skills. External content is fetched only when installing.`);
+        }
+        return;
+    }
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) &&
+        !options.yes &&
+        !options.json &&
+        (!process.env.CI || process.env.CI === "false");
+    const context = {
+        cwd: await realpath(process.cwd()),
+        home: homedir(),
+        env: { ...process.env },
+    };
+    const selection = await choose(options, catalog, context, interactive);
+    const plan = await createPlan(selection, context);
+    if (!options.json) {
+        console.log(`\nScope: ${selection.scope} (${selection.scope === "global" ? context.home : context.cwd})`);
+        console.log(`Agents: ${selection.agents.join(", ")}. Shared store: .agents/skills.`);
+        for (const item of plan.items) {
+            console.log(`\n${item.action.toUpperCase()} ${item.skill.id}`);
+            for (const path of item.paths)
+                console.log(`  -> ${path}`);
+            if (item.previousSource)
+                console.log(`  Tracked source: ${item.previousSource}`);
+            if (item.reason)
+                console.log(`  ${item.reason}`);
+        }
+    }
+    if (options.dryRun) {
+        if (options.json)
+            console.log(JSON.stringify(publicPlan(plan), null, 2));
+        else
+            console.log("\nDry run: no downloads or writes.");
+        if (plan.items.some((item) => item.action === "blocked"))
+            process.exitCode = 1;
+        return;
+    }
+    const runnable = plan.items.some((item) => item.action === "install" || item.action === "overwrite");
+    if (runnable && !options.yes) {
+        if (!interactive) {
+            throw new Error("Use --yes to confirm a non-interactive installation, or --dry-run to preview.");
+        }
+        if (!(await confirmInstall()))
+            throw new Cancelled("Cancelled; nothing installed.");
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    let results;
+    try {
+        results = await executePlan(plan, {
+            signal: controller.signal,
+            onSource: (source) => {
+                if (!options.json)
+                    console.log(`\nInstalling from ${source}...`);
+            },
+        });
+    }
+    finally {
+        process.off("SIGINT", abort);
+        process.off("SIGTERM", abort);
+    }
+    if (options.json)
+        console.log(JSON.stringify({ results }, null, 2));
+    else {
+        console.log("");
+        for (const result of results) {
+            console.log(`${result.status.toUpperCase()} ${result.id}\n  ${result.message}`);
+        }
+        const count = (status) => results.filter((result) => result.status === status).length;
+        console.log(`\n${count("installed")} installed, ${count("skipped")} skipped, ${count("failed")} failed.`);
+    }
+    if (controller.signal.aborted)
+        process.exitCode = 130;
+    else if (results.some((result) => result.status === "failed"))
+        process.exitCode = 1;
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes("--json")) {
+        console.log(JSON.stringify({ error: message }));
+    }
+    else {
+        console.error(`${error instanceof Cancelled ? "" : "Error: "}${message}`);
+    }
+    process.exitCode = error instanceof Cancelled ? 130 : 1;
+});

package/dist/install.d.ts

@@ -0,0 +1,14 @@
+import type { Context, InstallResult, Plan } from "./types.js";
+export declare const INSTALLER_VERSION = "1.7.2";
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type Runner = (args: string[], context: Context, signal?: AbortSignal) => Promise<CommandResult>;
+export declare const runSkills: Runner;
+export declare function executePlan(plan: Plan, { run, signal, onSource, }?: {
+    run?: Runner;
+    signal?: AbortSignal;
+    onSource?: (source: string) => void;
+}): Promise<InstallResult[]>;