skills-console 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) 的结构。正式发布版本采用语义化版本号。
+
+## [0.4.0] - 2026-07-17
+
+首个正式交付版本。
+
+### Added
+
+- 跨 Agent 本地 Skill 清单，覆盖用户、项目、共享、系统和 Codex 插件缓存根目录。
+- Dashboard、Skills、Agents、Doctor、Profiles 和 History 六个 TUI 页面。
+- 基于固定 `skills@1.5.17` 的来源预览、安装、更新和移除向导。
+- 写前事务快照、脱敏操作历史、执行后重新扫描验证和恢复工作流。
+- 目录名与 Skill 名不一致时的可逆 Doctor 修复。
+- `skills-profile.json` 导出、校验、期望状态 diff 和受保护的顺序应用。
+- 面向脚本的 inventory/profile CLI 与 JSON 输出。
+- MIT License、公开 npm 发行元数据和开源贡献/安全策略。
+- Node.js 22/24 CI 与基于 GitHub Actions OIDC 的 npm Trusted Publishing 工作流。
+
+### Security
+
+- 外部命令通过参数数组和 `shell: false` 执行。
+- 增加凭据脱敏、受管根目录写保护、恢复路径边界校验和上游 no-op 检测。
+- Codex 系统目录和插件缓存被标记为外部托管，只允许读取。
+
+### Known limitations
+
+- 更新后的验证只能确认安装仍存在，不能进行内容级版本证明。
+- Windows 原生环境尚未进入正式支持矩阵。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaoLiangqiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# Skills Console
+
+Skills Console 是一个本地优先的 Agent Skills 管理控制台。它用可视化 TUI 汇总当前用户和项目中的 Skills，通过固定版本的 [`skills`](https://github.com/vercel-labs/skills) CLI 执行安装、更新和移除，并为每次写操作保存可审计、可恢复的事务记录。
+
+当前正式版本为 `0.4.0`，以 MIT License 开源，通过 GitHub 提供源码，并以公开 npm 包和可安装 tarball 交付。
+
+## 产品形态
+
+- 一个命令启动的六页 TUI：Dashboard、Skills、Agents、Doctor、Profiles、History。
+- 一个面向自动化的只读 CLI：清单输出、Profile 导出、校验和 drift 检查。
+- 一个本地事务层：写前快照、脱敏历史、执行后扫描验证和 History 恢复。
+- 一个期望状态模型：用可版本控制的 `skills-profile.json` 描述项目需要的 Skills。
+- 零产品遥测、无后台服务、无云端账号；本地文件系统是状态事实来源。
+
+已内置识别 OpenAI Codex、Claude Code、Gemini CLI、Cursor、GitHub Copilot、OpenCode、Cline、Windsurf、Roo Code、Kiro CLI、Continue 和 Goose 的常见目录。只有已检测到的 Agent 目录会进入清单；Codex 系统 Skills 和插件缓存作为外部托管来源，只读展示。
+
+## 环境要求
+
+- Node.js `>=22`
+- npm `>=10`
+- 支持 Linux、macOS 和 WSL；Windows 原生环境尚未作为本版本发布平台验收
+- 交互模式需要 TTY；非交互环境请使用 CLI 子命令
+
+## 安装与运行
+
+直接运行或全局安装公开 npm 包：
+
+```bash
+npx skills-console
+npm install --global skills-console
+skills-console
+```
+
+从源码运行：
+
+```bash
+npm ci
+npm run dev
+```
+
+构建后运行：
+
+```bash
+npm run build
+npm start
+```
+
+从发布 tarball 安装：
+
+```bash
+npm pack
+npm install --global ./skills-console-0.4.0.tgz
+skills-console
+```
+
+包名、源码仓库、问题反馈地址和许可证均记录在 `package.json`。首次占用包名由维护者在认证终端完成；后续发布由带 OIDC 短期凭据的 GitHub Actions Trusted Publishing 工作流执行，不在仓库保存长期 npm token。
+
+## TUI 操作
+
+| 按键 | 操作 |
+| --- | --- |
+| `←` / `→` 或 `h` / `l` | 切换页面 |
+| `↑` / `↓` 或 `k` / `j` | 移动选择 |
+| `/` | 搜索 Skill |
+| `r` | 重新扫描 |
+| `i` | 安装 Skill |
+| `u` / `d` | 更新 / 移除当前 Skill |
+| `f` | 执行当前 Doctor 可逆修复 |
+| `p` | 导出或应用 Profile |
+| `z` | 恢复当前 History 操作 |
+| `q` | 退出或关闭当前向导 |
+
+安装向导先以只读方式列出来源中的 Skills，再选择 Skill、Agent、项目或用户作用域，以及 symlink 或 copy 模式。写操作会显示与实际执行同源的脱敏命令预览；用户确认后才会运行。
+
+## 非交互 CLI
+
+```bash
+# 文本清单摘要或完整 JSON 清单
+skills-console inventory
+skills-console inventory --json
+skills-console --json
+
+# 导出项目期望状态；默认写入 ./skills-profile.json
+skills-console profile export [path] [--include-user] [--json]
+
+# 校验与比较期望状态
+skills-console profile validate [path]
+skills-console profile diff [path] [--json]
+
+skills-console --version
+skills-console --help
+```
+
+通用退出码：`0` 表示成功或期望状态已满足，`1` 表示命令、配置或运行错误，`2` 仅用于 `profile diff` 表示存在可执行 drift。
+
+Profile 默认只管理当前项目作用域，不删除未声明 Skill。详细 schema 和安全语义见 [Profile 协议](docs/PROFILES.md)。
+
+## 安全与恢复
+
+- `skills@1.5.17` 是直接依赖；运行时使用已安装的精确版本，不临时下载 latest。
+- 子进程使用参数数组和 `shell: false`，预览文本与执行计划来自同一对象。
+- 工具不会运行 Skill 仓库内的脚本；来源预览只读取上游 CLI 返回的清单。
+- 写操作前备份所有匹配的可变安装，备份失败则不继续。
+- 恢复前校验目标位于记录的 Skill 根目录内；软链接目标丢失时恢复为普通目录。
+- 命令、日志和来源中的凭据会脱敏；History 最多保留每次执行的最后 200 行输出。
+- Doctor 只自动处理目标明确且可逆的目录名不一致；其余诊断保持只读。
+- 更新操作目前只能确认 Skill 仍然存在，不能证明内容版本确实变化，因此会标记为 `indeterminate`。
+
+运行数据保存在：
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/skills-console/history/
+${XDG_DATA_HOME:-~/.local/share}/skills-console/backups/
+```
+
+完整实现边界见 [架构说明](docs/ARCHITECTURE.md)，生产安装、验证、故障处理和发布步骤见 [运维与发布手册](docs/OPERATIONS.md)。
+
+## 开发与验证
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+测试必须只使用临时 HOME/XDG 目录或 fixture，不得修改开发者真实的 Skills。版本变化记录见 [CHANGELOG](CHANGELOG.md)。
+
+贡献流程见 [CONTRIBUTING](CONTRIBUTING.md)，安全漏洞请按 [SECURITY](SECURITY.md) 私下报告。本项目依据 [MIT License](LICENSE) 发布。

package/dist/adapters/filesystem/agent-registry.d.ts

@@ -0,0 +1,5 @@
+import type { AgentHost, EnvironmentInfo, SkillRoot } from '../../domain/types.js';
+export declare function resolveAgentRegistry(environment: EnvironmentInfo): Promise<{
+    agents: AgentHost[];
+    roots: SkillRoot[];
+}>;

package/dist/adapters/filesystem/agent-registry.js

@@ -0,0 +1,236 @@
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, normalize } from 'node:path';
+import { executableExists } from '../../platform/environment.js';
+async function pathState(path) {
+    try {
+        await stat(path);
+    }
+    catch {
+        return { exists: false, readable: false, writable: false };
+    }
+    let readable = false;
+    let writable = false;
+    try {
+        await access(path, constants.R_OK);
+        readable = true;
+    }
+    catch {
+        // Represent access failures in the returned state.
+    }
+    try {
+        await access(path, constants.W_OK);
+        writable = true;
+    }
+    catch {
+        // Represent access failures in the returned state.
+    }
+    return { exists: true, readable, writable };
+}
+function definitions(environment) {
+    const home = environment.homeDir;
+    const project = environment.projectRoot;
+    const user = (path, options = {}) => ({
+        path: join(home, path),
+        ...options,
+    });
+    const local = (path, options = {}) => ({
+        path: join(project, path),
+        ...options,
+    });
+    return [
+        {
+            id: 'codex',
+            displayName: 'OpenAI Codex',
+            commands: ['codex'],
+            markerPaths: [join(home, '.codex')],
+            userRoots: [
+                user('.codex/skills', { excludedDirectoryNames: ['.system'] }),
+                user('.codex/skills/.system', {
+                    kind: 'system',
+                    mutable: false,
+                    maxDepth: 3,
+                }),
+                user('.agents/skills', { kind: 'shared' }),
+                user('.codex/plugins/cache', {
+                    kind: 'plugin-cache',
+                    mutable: false,
+                    maxDepth: 9,
+                }),
+            ],
+            projectRoots: [local('.agents/skills', { kind: 'shared' }), local('.codex/skills')],
+        },
+        {
+            id: 'claude-code',
+            displayName: 'Claude Code',
+            commands: ['claude'],
+            markerPaths: [join(home, '.claude')],
+            userRoots: [user('.claude/skills')],
+            projectRoots: [local('.claude/skills')],
+        },
+        {
+            id: 'gemini-cli',
+            displayName: 'Gemini CLI',
+            commands: ['gemini'],
+            markerPaths: [join(home, '.gemini')],
+            userRoots: [user('.gemini/skills')],
+            projectRoots: [local('.agents/skills', { kind: 'shared' })],
+        },
+        {
+            id: 'cursor',
+            displayName: 'Cursor',
+            commands: ['cursor'],
+            markerPaths: [join(home, '.cursor')],
+            userRoots: [user('.cursor/skills')],
+            projectRoots: [local('.agents/skills', { kind: 'shared' })],
+        },
+        {
+            id: 'github-copilot',
+            displayName: 'GitHub Copilot',
+            commands: ['github-copilot'],
+            markerPaths: [join(home, '.copilot')],
+            userRoots: [user('.copilot/skills')],
+            projectRoots: [local('.agents/skills', { kind: 'shared' })],
+        },
+        {
+            id: 'opencode',
+            displayName: 'OpenCode',
+            commands: ['opencode'],
+            markerPaths: [join(home, '.config/opencode')],
+            userRoots: [user('.config/opencode/skills')],
+            projectRoots: [local('.agents/skills', { kind: 'shared' })],
+        },
+        {
+            id: 'cline',
+            displayName: 'Cline',
+            commands: [],
+            markerPaths: [join(home, '.cline')],
+            userRoots: [user('.agents/skills', { kind: 'shared' })],
+            projectRoots: [local('.agents/skills', { kind: 'shared' })],
+        },
+        {
+            id: 'windsurf',
+            displayName: 'Windsurf',
+            commands: ['windsurf'],
+            markerPaths: [join(home, '.codeium/windsurf')],
+            userRoots: [user('.codeium/windsurf/skills')],
+            projectRoots: [local('.windsurf/skills')],
+        },
+        {
+            id: 'roo',
+            displayName: 'Roo Code',
+            commands: [],
+            markerPaths: [join(home, '.roo')],
+            userRoots: [user('.roo/skills')],
+            projectRoots: [local('.roo/skills')],
+        },
+        {
+            id: 'kiro-cli',
+            displayName: 'Kiro CLI',
+            commands: ['kiro-cli', 'kiro'],
+            markerPaths: [join(home, '.kiro')],
+            userRoots: [user('.kiro/skills')],
+            projectRoots: [local('.kiro/skills')],
+        },
+        {
+            id: 'continue',
+            displayName: 'Continue',
+            commands: [],
+            markerPaths: [join(home, '.continue')],
+            userRoots: [user('.continue/skills')],
+            projectRoots: [local('.continue/skills')],
+        },
+        {
+            id: 'goose',
+            displayName: 'Goose',
+            commands: ['goose'],
+            markerPaths: [join(home, '.config/goose')],
+            userRoots: [user('.config/goose/skills')],
+            projectRoots: [local('.goose/skills')],
+        },
+    ];
+}
+async function markerExists(paths) {
+    const matches = [];
+    for (const path of paths) {
+        if ((await pathState(path)).exists) {
+            matches.push(`config:${path}`);
+        }
+    }
+    return matches;
+}
+async function commandMatches(commands) {
+    const matches = [];
+    for (const command of commands) {
+        if (await executableExists(command)) {
+            matches.push(`command:${command}`);
+        }
+    }
+    return matches;
+}
+function rootKey(candidate) {
+    return `${candidate.scope}:${normalize(candidate.path)}`;
+}
+export async function resolveAgentRegistry(environment) {
+    const resolvedAgents = [];
+    for (const definition of definitions(environment)) {
+        const reasons = [
+            ...(await markerExists(definition.markerPaths)),
+            ...(await commandMatches(definition.commands)),
+        ];
+        const ownRootExists = await Promise.all([...definition.userRoots, ...definition.projectRoots]
+            .filter((root) => root.kind !== 'shared')
+            .map(async (root) => (await pathState(root.path)).exists));
+        resolvedAgents.push({
+            definition,
+            detected: reasons.length > 0 || ownRootExists.some(Boolean),
+            reasons,
+        });
+    }
+    const candidates = [];
+    for (const agent of resolvedAgents.filter((item) => item.detected)) {
+        candidates.push(...agent.definition.userRoots.map((root) => ({
+            ...root,
+            scope: 'user',
+            agentId: agent.definition.id,
+        })), ...agent.definition.projectRoots.map((root) => ({
+            ...root,
+            scope: 'project',
+            agentId: agent.definition.id,
+        })));
+    }
+    const grouped = new Map();
+    for (const candidate of candidates) {
+        const key = rootKey(candidate);
+        grouped.set(key, [...(grouped.get(key) ?? []), candidate]);
+    }
+    const roots = [];
+    for (const [id, group] of grouped) {
+        const first = group[0];
+        if (!first) {
+            continue;
+        }
+        const state = await pathState(first.path);
+        roots.push({
+            id,
+            path: first.path,
+            scope: first.scope,
+            kind: first.kind ?? 'agent',
+            agentIds: [...new Set(group.map((item) => item.agentId))].sort(),
+            ...state,
+            mutable: first.mutable ?? true,
+            maxDepth: first.maxDepth ?? 5,
+            excludedDirectoryNames: first.excludedDirectoryNames ?? [],
+        });
+    }
+    roots.sort((a, b) => a.path.localeCompare(b.path));
+    const agents = resolvedAgents.map(({ definition, detected, reasons }) => ({
+        id: definition.id,
+        displayName: definition.displayName,
+        detected,
+        detectionReasons: reasons,
+        roots: roots.filter((root) => root.agentIds.includes(definition.id)),
+    }));
+    return { agents, roots };
+}
+//# sourceMappingURL=agent-registry.js.map

package/dist/adapters/filesystem/agent-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.js","sourceRoot":"","sources":["../../../src/adapters/filesystem/agent-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAE,IAAI,EAAC,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAClC,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAS1C,OAAO,EAAC,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAwB/D,KAAK,UAAU,SAAS,CAAC,IAAY;IAKnC,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAC,CAAC;IAC3D,CAAC;IAED,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,mDAAmD;IACrD,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,mDAAmD;IACrD,CAAC;IAED,OAAO,EAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAC,CAAC;AAC5C,CAAC;AAED,SAAS,WAAW,CAAC,WAA4B;IAC/C,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC;IACjC,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAO,GAA+B,EAAE,EAAgB,EAAE,CAAC,CAAC;QACtF,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;QACtB,GAAG,OAAO;KACX,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,OAAO,GAA+B,EAAE,EAAgB,EAAE,CAAC,CAAC;QACvF,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC;QACzB,GAAG,OAAO;KACX,CAAC,CAAC;IAEH,OAAO;QACL;YACE,EAAE,EAAE,OAAO;YACX,WAAW,EAAE,cAAc;YAC3B,QAAQ,EAAE,CAAC,OAAO,CAAC;YACnB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACnC,SAAS,EAAE;gBACT,IAAI,CAAC,eAAe,EAAE,EAAC,sBAAsB,EAAE,CAAC,SAAS,CAAC,EAAC,CAAC;gBAC5D,IAAI,CAAC,uBAAuB,EAAE;oBAC5B,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,KAAK;oBACd,QAAQ,EAAE,CAAC;iBACZ,CAAC;gBACF,IAAI,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC;gBACxC,IAAI,CAAC,sBAAsB,EAAE;oBAC3B,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,KAAK;oBACd,QAAQ,EAAE,CAAC;iBACZ,CAAC;aACH;YACD,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;SAClF;QACD;YACE,EAAE,EAAE,aAAa;YACjB,WAAW,EAAE,aAAa;YAC1B,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACpC,SAAS,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACnC,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;SACxC;QACD;YACE,EAAE,EAAE,YAAY;YAChB,WAAW,EAAE,YAAY;YACzB,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACpC,SAAS,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACnC,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;SAC1D;QACD;YACE,EAAE,EAAE,QAAQ;YACZ,WAAW,EAAE,QAAQ;YACrB,QAAQ,EAAE,CAAC,QAAQ,CAAC;YACpB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACpC,SAAS,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACnC,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;SAC1D;QACD;YACE,EAAE,EAAE,gBAAgB;YACpB,WAAW,EAAE,gBAAgB;YAC7B,QAAQ,EAAE,CAAC,gBAAgB,CAAC;YAC5B,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACrC,SAAS,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACpC,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;SAC1D;QACD;YACE,EAAE,EAAE,UAAU;YACd,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,CAAC,UAAU,CAAC;YACtB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;YAC7C,SAAS,EAAE,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YAC5C,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;SAC1D;QACD;YACE,EAAE,EAAE,OAAO;YACX,WAAW,EAAE,OAAO;YACpB,QAAQ,EAAE,EAAE;YACZ,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACnC,SAAS,EAAE,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;YACrD,YAAY,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAC,IAAI,EAAE,QAAQ,EAAC,CAAC,CAAC;SAC1D;QACD;YACE,EAAE,EAAE,UAAU;YACd,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,CAAC,UAAU,CAAC;YACtB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;YAC9C,SAAS,EAAE,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;YAC7C,YAAY,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;SAC1C;QACD;YACE,EAAE,EAAE,KAAK;YACT,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,EAAE;YACZ,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACjC,SAAS,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAChC,YAAY,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;SACrC;QACD;YACE,EAAE,EAAE,UAAU;YACd,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC;YAC9B,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAClC,SAAS,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACjC,YAAY,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;SACtC;QACD;YACE,EAAE,EAAE,UAAU;YACd,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,EAAE;YACZ,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YACtC,SAAS,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACrC,YAAY,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;SAC1C;QACD;YACE,EAAE,EAAE,OAAO;YACX,WAAW,EAAE,OAAO;YACpB,QAAQ,EAAE,CAAC,OAAO,CAAC;YACnB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;YAC1C,SAAS,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;YACzC,YAAY,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;SACvC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,KAAe;IACzC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,QAAkB;IAC9C,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,OAAO,CAAC,SAAwB;IACvC,OAAO,GAAG,SAAS,CAAC,KAAK,IAAI,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAA4B;IAIrE,MAAM,cAAc,GAIf,EAAE,CAAC;IAER,KAAK,MAAM,UAAU,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAClD,MAAM,OAAO,GAAG;YACd,GAAG,CAAC,MAAM,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;YAC/C,GAAG,CAAC,MAAM,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;SAC/C,CAAC;QACF,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,CAAC,GAAG,UAAU,CAAC,SAAS,EAAE,GAAG,UAAU,CAAC,YAAY,CAAC;aAClD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;aACxC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAC5D,CAAC;QAEF,cAAc,CAAC,IAAI,CAAC;YAClB,UAAU;YACV,QAAQ,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;YAC3D,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnE,UAAU,CAAC,IAAI,CACb,GAAG,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC3C,GAAG,IAAI;YACP,KAAK,EAAE,MAAe;YACtB,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE;SAC7B,CAAC,CAAC,EACH,GAAG,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9C,GAAG,IAAI;YACP,KAAK,EAAE,SAAkB;YACzB,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE;SAC7B,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC;YACT,EAAE;YACF,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,OAAO;YAC3B,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YAChE,GAAG,KAAK;YACR,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;YAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;YAC7B,sBAAsB,EAAE,KAAK,CAAC,sBAAsB,IAAI,EAAE;SAC3D,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAgB,cAAc,CAAC,GAAG,CAAC,CAAC,EAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAC,EAAE,EAAE,CAAC,CAAC;QACnF,EAAE,EAAE,UAAU,CAAC,EAAE;QACjB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,QAAQ;QACR,gBAAgB,EAAE,OAAO;QACzB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;KACrE,CAAC,CAAC,CAAC;IAEJ,OAAO,EAAC,MAAM,EAAE,KAAK,EAAC,CAAC;AACzB,CAAC"}

package/dist/adapters/filesystem/frontmatter.d.ts

@@ -0,0 +1,2 @@
+import type { SkillManifest } from '../../domain/types.js';
+export declare function parseSkillManifest(content: string): SkillManifest;

package/dist/adapters/filesystem/frontmatter.js

@@ -0,0 +1,73 @@
+import { parseDocument } from 'yaml';
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function sourceFromMetadata(metadata) {
+    const candidates = [
+        metadata.source,
+        metadata.repository,
+        metadata.sourceUrl,
+        metadata['source-url'],
+    ];
+    return candidates.map(optionalString).find(Boolean);
+}
+export function parseSkillManifest(content) {
+    const empty = {
+        name: undefined,
+        description: undefined,
+        license: undefined,
+        compatibility: undefined,
+        allowedTools: undefined,
+        metadata: {},
+        source: undefined,
+        valid: false,
+        errors: [],
+    };
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    if (!match?.[1]) {
+        return { ...empty, errors: ['Missing YAML frontmatter delimited by --- lines.'] };
+    }
+    const document = parseDocument(match[1], { logLevel: 'silent', prettyErrors: true });
+    const parseErrors = document.errors.map((error) => error.message);
+    const value = document.toJS();
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {
+            ...empty,
+            errors: [...parseErrors, 'Frontmatter must be a YAML mapping.'],
+        };
+    }
+    const record = value;
+    const metadata = record.metadata && typeof record.metadata === 'object' && !Array.isArray(record.metadata)
+        ? record.metadata
+        : {};
+    const name = optionalString(record.name);
+    const description = optionalString(record.description);
+    const errors = [...parseErrors];
+    if (!name) {
+        errors.push('Missing required name field.');
+    }
+    else if (!NAME_PATTERN.test(name) || name.length > 64) {
+        errors.push('Name must be 1-64 lowercase letters, numbers, or hyphen-separated words.');
+    }
+    if (!description) {
+        errors.push('Missing required description field.');
+    }
+    else if (description.length > 1024) {
+        errors.push('Description exceeds 1024 characters.');
+    }
+    return {
+        name,
+        description,
+        license: optionalString(record.license),
+        compatibility: optionalString(record.compatibility),
+        allowedTools: optionalString(record['allowed-tools']),
+        metadata,
+        source: optionalString(record.source) ??
+            optionalString(record.repository) ??
+            sourceFromMetadata(metadata),
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/adapters/filesystem/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../../src/adapters/filesystem/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/filesystem/skill-scanner.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic, SkillInstallation, SkillRoot } from '../../domain/types.js';
+interface ScanResult {
+    installations: SkillInstallation[];
+    diagnostics: Diagnostic[];
+}
+export declare function scanSkillRoot(root: SkillRoot): Promise<ScanResult>;
+export declare function scanSkillRoots(roots: SkillRoot[]): Promise<ScanResult>;
+export {};