skvlt 0.9.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xi Xu
+
+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,199 @@
+# Skills Vault
+
+**_[汉语](./README.zh.md)_**
+
+[![npm version](https://img.shields.io/npm/v/skvlt)](https://www.npmjs.com/package/skvlt)
+[![CI](https://img.shields.io/github/actions/workflow/status/xixu-me/skills-vault/ci.yml?branch=main&label=ci)](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
+[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.3.11-f9f1e1)](https://bun.sh/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Skills Vault is a CLI for backing up and restoring [Agent Skills](https://agentskills.io).
+
+It is built for the common round-trip:
+
+1. snapshot what is installed today
+2. commit or move the manifest
+3. restore the same set of skill sources on another machine
+
+> [!IMPORTANT]
+> Bun-only runtime. Skills Vault is designed to be installed and run with [Bun](https://bun.com).
+
+## Why Skills Vault
+
+Skills Vault exists to fill the gap described in [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/729): a declarative manifest for portable, reproducible skill setups across machines and teams.
+
+- Back up installed skills into a deterministic `skvlt.yaml` file.
+- Restore from that manifest by source, by agent, or all at once.
+- Preview installs before making changes with `--dry-run`.
+- Check local setup quickly with `doctor`.
+- Generate completion scripts for `bash`, `zsh`, and `powershell`.
+
+## Quick Start
+
+Back up your current skills:
+
+```bash
+bunx skvlt backup
+```
+
+Preview what a restore would run:
+
+```bash
+bunx skvlt restore --dry-run
+```
+
+Restore everything recorded in the manifest:
+
+```bash
+bunx skvlt restore --all
+```
+
+If you want a curated, ready-to-use manifest, see [xixu-me/skvlt](https://github.com/xixu-me/skvlt), a maintained collection of `skvlt.yaml` snapshots.
+
+The default manifest is `./skvlt.yaml`. A typical file looks like this:
+
+```yaml
+total_sources: 2
+total_skills: 3
+scope: "global"
+
+sources:
+  "alpha/source":
+    count: 1
+    skills:
+      - "beta"
+
+  "beta/source":
+    count: 2
+    skills:
+      - "alpha"
+      - "zulu"
+```
+
+## Commands
+
+### `backup`
+
+Snapshot installed skills into `skvlt.yaml`.
+
+```bash
+bunx skvlt backup
+bunx skvlt backup --dry-run
+bunx skvlt backup --output ./skvlt.yaml
+bunx skvlt backup --project-scope --lock-file ./skills-lock.json
+```
+
+`backup` reads installed skill names, joins them with lock-file metadata, and writes a grouped manifest keyed by source.
+
+> [!NOTE]
+> Global backup reads from `~/.agents/.skill-lock.json` by default. Project-scope backup currently requires `--lock-file`.
+
+### `restore`
+
+Install skills from a manifest.
+
+```bash
+bunx skvlt restore --all
+bunx skvlt restore --only-source xixu-me/skills
+bunx skvlt restore --project-scope
+bunx skvlt restore --dry-run
+```
+
+By default, restore respects the scope recorded in the manifest. Use `--project-scope` to force a project install even when the manifest was created from global state.
+
+`--dry-run` prints the derived `bunx skills add ...` commands without running them. Live installs run in lock-safe mode and are serialized to avoid global lock-file races.
+
+For a curated manifest source, you can start from [xixu-me/skvlt](https://github.com/xixu-me/skvlt) and restore from the `skvlt.yaml` maintained there.
+
+### `doctor`
+
+Inspect the local Skills Vault environment and global skill state.
+
+```bash
+bunx skvlt doctor
+bunx skvlt doctor --manifest ./skvlt.yaml
+```
+
+`doctor` checks:
+
+- the Bun runtime
+- `bunx skills --help`
+- whether the manifest exists
+- whether the global lock file and skills directory are present
+- whether tracked and installed global skills still match
+
+### `completion`
+
+Print shell completion scripts.
+
+```bash
+bunx skvlt completion bash
+bunx skvlt completion zsh
+bunx skvlt completion powershell
+```
+
+## JSON Output
+
+All top-level commands support `--json` for structured output:
+
+```bash
+bunx skvlt --json doctor
+bunx skvlt --json backup --dry-run
+```
+
+Successful responses include `ok`, `command`, and `data`. Failures include `ok`, `command`, and a stable `error.code` plus message.
+
+## Local Development
+
+Install dependencies:
+
+```bash
+bun install --frozen-lockfile
+```
+
+Useful commands:
+
+```bash
+bun run ./src/cli.ts --help
+bun run ./src/cli.ts doctor
+bun run backup
+bun run restore
+bun run test
+bun run check
+```
+
+`bun run check` is the main verification gate. It runs formatting checks, the Bun test suite, and `npm pack --dry-run --json`.
+
+If you change workflow files, also run:
+
+```bash
+bunx prettier --check ".github/**/*.yml"
+```
+
+## Package And Release Notes
+
+The npm package publishes the `skvlt` bin from `src/cli.ts` and intentionally ships the `src` directory as its runtime payload.
+
+Before publishing, verify the tarball contents locally:
+
+```bash
+npm pack --dry-run --json
+```
+
+The release workflow uses trusted publishing. The publish step is:
+
+```bash
+npm publish --access public
+```
+
+## Troubleshooting
+
+- If restore reports a global state mismatch, inspect `~/.agents/.skill-lock.json` and `~/.agents/skills`.
+- If environment checks fail, start with `bunx skvlt doctor`.
+- If packaging checks fail, run `bun run check` and review the tarball output from `npm pack --dry-run --json`.
+
+For contribution, support, and security policy details, see [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`SUPPORT.md`](./SUPPORT.md), and [`SECURITY.md`](./SECURITY.md).
+
+## License
+
+Licensed under MIT. See [`LICENSE`](./LICENSE).

package/README.zh.md

@@ -0,0 +1,199 @@
+# Skills Vault
+
+**_[English](./README.md)_**
+
+[![npm version](https://img.shields.io/npm/v/skvlt)](https://www.npmjs.com/package/skvlt)
+[![CI](https://img.shields.io/github/actions/workflow/status/xixu-me/skills-vault/ci.yml?branch=main&label=ci)](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
+[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.3.11-f9f1e1)](https://bun.sh/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Skills Vault 是一个用于备份和恢复 [Agent Skills](https://agentskills.io) 的 CLI。
+
+它主要服务于这样一个常见流程：
+
+1. 把当前机器上已安装的 skills 快照出来
+2. 提交或移动这个 manifest
+3. 在另一台机器上恢复同一组 skill source
+
+> [!IMPORTANT]
+> 仅支持 Bun 运行时。Skills Vault 设计上就是通过 [Bun](https://bun.com) 安装和运行的。
+
+## 为什么需要 Skills Vault
+
+Skills Vault 的存在，是为了补上 [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/729) 里提到的缺口：缺少一种声明式 manifest，来支持可移植、可复现的 skills 配置。
+
+- 把已安装的 skills 备份为确定性的 `skvlt.yaml`
+- 按 source、按 agent，或者一次性从 manifest 恢复
+- 通过 `--dry-run` 在真正改动前先预览
+- 用 `doctor` 快速检查本地环境
+- 为 `bash`、`zsh` 和 `powershell` 生成补全脚本
+
+## 快速开始
+
+备份当前已安装的 skills：
+
+```bash
+bunx skvlt backup
+```
+
+预览一次 restore 将会执行什么：
+
+```bash
+bunx skvlt restore --dry-run
+```
+
+恢复 manifest 中记录的全部内容：
+
+```bash
+bunx skvlt restore --all
+```
+
+如果你想直接使用一个精选好的 manifest，可以查看 [xixu-me/skvlt](https://github.com/xixu-me/skvlt)，这是一个持续维护的 `skvlt.yaml` 集合。
+
+默认 manifest 路径是 `./skvlt.yaml`。一个典型文件如下：
+
+```yaml
+total_sources: 2
+total_skills: 3
+scope: "global"
+
+sources:
+  "alpha/source":
+    count: 1
+    skills:
+      - "beta"
+
+  "beta/source":
+    count: 2
+    skills:
+      - "alpha"
+      - "zulu"
+```
+
+## 命令
+
+### `backup`
+
+把已安装的 skills 快照到 `skvlt.yaml`。
+
+```bash
+bunx skvlt backup
+bunx skvlt backup --dry-run
+bunx skvlt backup --output ./skvlt.yaml
+bunx skvlt backup --project-scope --lock-file ./skills-lock.json
+```
+
+`backup` 会先读取已安装的 skill 名称，再结合 lock file 元数据，最终按 source 分组写出 manifest。
+
+> [!NOTE]
+> 全局备份默认读取 `~/.agents/.skill-lock.json`。项目级备份目前仍然需要显式传入 `--lock-file`。
+
+### `restore`
+
+从 manifest 安装 skills。
+
+```bash
+bunx skvlt restore --all
+bunx skvlt restore --only-source xixu-me/skills
+bunx skvlt restore --project-scope
+bunx skvlt restore --dry-run
+```
+
+默认情况下，`restore` 会遵循 manifest 中记录的 scope。如果希望即使 manifest 来自全局状态，也强制恢复到项目作用域，可以使用 `--project-scope`。
+
+`--dry-run` 会打印推导出的 `bunx skills add ...` 命令，但不会真正执行。实际安装时会采用 lock-safe 模式串行执行，以避免全局 lock file 竞争。
+
+如果你想从一个精选 manifest 起步，也可以直接使用 [xixu-me/skvlt](https://github.com/xixu-me/skvlt) 中维护的 `skvlt.yaml`。
+
+### `doctor`
+
+检查本地 Skills Vault 环境和全局 skill 状态。
+
+```bash
+bunx skvlt doctor
+bunx skvlt doctor --manifest ./skvlt.yaml
+```
+
+`doctor` 会检查：
+
+- Bun 运行时
+- `bunx skills --help`
+- manifest 是否存在
+- 全局 lock file 和 skills 目录是否存在
+- lock file 中追踪的技能与实际安装状态是否一致
+
+### `completion`
+
+输出 shell 补全脚本。
+
+```bash
+bunx skvlt completion bash
+bunx skvlt completion zsh
+bunx skvlt completion powershell
+```
+
+## JSON 输出
+
+所有顶层命令都支持 `--json` 结构化输出：
+
+```bash
+bunx skvlt --json doctor
+bunx skvlt --json backup --dry-run
+```
+
+成功时会返回 `ok`、`command` 和 `data`。失败时会返回 `ok`、`command`，以及稳定的 `error.code` 和错误消息。
+
+## 本地开发
+
+安装依赖：
+
+```bash
+bun install --frozen-lockfile
+```
+
+常用命令：
+
+```bash
+bun run ./src/cli.ts --help
+bun run ./src/cli.ts doctor
+bun run backup
+bun run restore
+bun run test
+bun run check
+```
+
+`bun run check` 是主要的发布前校验入口。它会运行格式检查、完整的 Bun 测试，以及 `npm pack --dry-run --json`。
+
+如果你修改了 workflow 文件，也请额外运行：
+
+```bash
+bunx prettier --check ".github/**/*.yml"
+```
+
+## 打包与发布说明
+
+npm 包会把 `src/cli.ts` 作为 `skvlt` 可执行入口，并且有意只将 `src` 目录作为运行时载荷发布。
+
+发布前，可以先在本地检查 tarball 内容：
+
+```bash
+npm pack --dry-run --json
+```
+
+Release workflow 使用 trusted publishing。实际发布步骤为：
+
+```bash
+npm publish --access public
+```
+
+## 故障排查
+
+- 如果 restore 报告全局状态不一致，请检查 `~/.agents/.skill-lock.json` 和 `~/.agents/skills`
+- 如果环境检查失败，先运行 `bunx skvlt doctor`
+- 如果打包检查失败，运行 `bun run check`，并检查 `npm pack --dry-run --json` 的输出
+
+关于贡献、支持和安全策略，请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)、[`SUPPORT.md`](./SUPPORT.md) 和 [`SECURITY.md`](./SECURITY.md)。
+
+## 许可证
+
+基于 MIT 许可证发布。详见 [`LICENSE`](./LICENSE)。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "skvlt",
+  "version": "0.9.9",
+  "description": "The CLI for backing up and restoring Agent Skills",
+  "author": "Xi Xu",
+  "bin": {
+    "skvlt": "src/cli.ts"
+  },
+  "license": "MIT",
+  "keywords": [
+    "cli",
+    "skills",
+    "agents",
+    "backup",
+    "restore",
+    "bun"
+  ],
+  "homepage": "https://github.com/xixu-me/skills-vault#readme",
+  "bugs": {
+    "url": "https://github.com/xixu-me/skills-vault/issues"
+  },
+  "funding": {
+    "url": "https://xi-xu.me/#sponsorships"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xixu-me/skills-vault.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "packageManager": "bun@1.3.11",
+  "private": false,
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "backup": "bun run ./src/cli.ts backup",
+    "backup:dry-run": "bun run ./src/cli.ts backup --dry-run",
+    "check": "bun run format:check && bun test && npm pack --dry-run --json",
+    "format": "prettier --write \"package.json\" \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"package.json\" \"src/**/*.ts\" \"test/**/*.ts\"",
+    "publish:check": "bun run check",
+    "prepublishOnly": "bun run publish:check",
+    "restore": "bun run ./src/cli.ts restore",
+    "restore:dry-run": "bun run ./src/cli.ts restore --dry-run",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.1"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env bun
+
+import packageJson from "../package.json" with { type: "json" };
+import { runBackup } from "./commands/backup";
+import { runCompletion } from "./commands/completion";
+import { runDoctor } from "./commands/doctor";
+import { runRestore } from "./commands/restore";
+import {
+  bold,
+  dimGray,
+  textGray,
+  helpFooter,
+  helpExample,
+  helpHeading,
+  page,
+  stripAnsi,
+} from "./internal/cli/theme";
+
+type CliResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  errorCode?: string;
+  payload?: unknown;
+};
+
+type RunCliOptions = {
+  reportProgress?: (chunk: string) => void;
+  streamOutput?: boolean;
+};
+
+function printHelp(): string {
+  return `\n${[
+    "The CLI for backing up and restoring Agent Skills",
+    "",
+    helpHeading("Usage"),
+    "  bunx skvlt <command> [options]",
+    "",
+    helpHeading("Commands"),
+    "  backup                Backup installed skills into a manifest",
+    "  completion            Print shell completion scripts",
+    "  doctor                Inspect the local environment and skill state",
+    "  restore               Restore skills from a manifest",
+    "",
+    helpHeading("Global Options"),
+    "  -h, --help            Show top-level help",
+    "  -j, --json            Print structured JSON output",
+    "  -v, --version         Print the installed package version",
+    "",
+    helpHeading("Examples"),
+    helpExample("bunx skvlt backup --output ./skvlt.yaml"),
+    helpExample("bunx skvlt completion bash"),
+    helpExample("bunx skvlt doctor"),
+    helpExample("bunx skvlt restore --all"),
+    helpExample("bunx skvlt restore --only-source xixu-me/skills"),
+    helpFooter("https://github.com/xixu-me/skills-vault"),
+  ].join("\n")}`;
+}
+
+function landingCommand(command: string, description: string): string {
+  return `  ${dimGray("$")} ${textGray(command.padEnd(28))} ${dimGray(description)}`;
+}
+
+function printLanding(): string {
+  return `\n${[
+    dimGray("The CLI for backing up and restoring Agent Skills"),
+    "",
+    landingCommand("bunx skvlt backup", "Backup installed skills"),
+    landingCommand("bunx skvlt restore", "Restore from skvlt.yaml"),
+    landingCommand("bunx skvlt doctor", "Inspect local setup"),
+    landingCommand("bunx skvlt completion", "Print shell completions"),
+    "",
+    `${dimGray("Explore the open-source repo at")} ${textGray("https://github.com/xixu-me/skills-vault")}\n`,
+  ].join("\n")}`;
+}
+
+function extractGlobalFlags(argv: string[]) {
+  const positional: string[] = [];
+  let json = false;
+
+  for (const arg of argv) {
+    if (arg === "--json" || arg === "-j") {
+      json = true;
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  return { argv: positional, json };
+}
+
+function toJsonResult(
+  command: string,
+  result: CliResult,
+  fallbackData?: unknown,
+): CliResult {
+  const body =
+    result.exitCode === 0
+      ? {
+          ok: true,
+          command,
+          data: result.payload ?? fallbackData ?? null,
+        }
+      : {
+          ok: false,
+          command,
+          error: {
+            code: result.errorCode ?? "CLI_ERROR",
+            message: stripAnsi(result.stderr || result.stdout).trim(),
+          },
+        };
+
+  return {
+    ...result,
+    stdout: `${JSON.stringify(body, null, 2)}\n`,
+    stderr: "",
+  };
+}
+
+/**
+ * Dispatches the top-level CLI command and normalizes text or JSON output.
+ */
+export async function runCli(
+  argv: string[],
+  options: RunCliOptions = {},
+): Promise<CliResult> {
+  const extracted = extractGlobalFlags(argv);
+  const [command] = extracted.argv;
+  if (!command) {
+    const result: CliResult = {
+      exitCode: 0,
+      stdout: `${printLanding()}\n`,
+      stderr: "",
+      payload: { text: stripAnsi(printLanding()) },
+    };
+    return extracted.json ? toJsonResult("landing", result) : result;
+  }
+  if (command === "--help" || command === "-h") {
+    const result: CliResult = { exitCode: 0, stdout: printHelp(), stderr: "" };
+    return extracted.json
+      ? toJsonResult("help", result, { text: printHelp().trimEnd() })
+      : result;
+  }
+  if (command === "--version" || command === "-v") {
+    const result: CliResult = {
+      exitCode: 0,
+      stdout: `${packageJson.version}\n`,
+      stderr: "",
+      payload: { version: packageJson.version },
+    };
+    return extracted.json ? toJsonResult("version", result) : result;
+  }
+  if (command === "backup") {
+    const result = await runBackup(extracted.argv.slice(1), {
+      reportProgress: extracted.json ? undefined : options.reportProgress,
+      streamOutput: extracted.json ? false : options.streamOutput,
+    });
+    return extracted.json ? toJsonResult("backup", result) : result;
+  }
+  if (command === "doctor") {
+    const result = await runDoctor(extracted.argv.slice(1));
+    return extracted.json ? toJsonResult("doctor", result) : result;
+  }
+  if (command === "completion") {
+    const result = await runCompletion(extracted.argv.slice(1));
+    return extracted.json ? toJsonResult("completion", result) : result;
+  }
+  if (command === "restore") {
+    const result = await runRestore(extracted.argv.slice(1), {
+      reportProgress: extracted.json ? undefined : options.reportProgress,
+      streamOutput: extracted.json ? false : options.streamOutput,
+    });
+    return extracted.json ? toJsonResult("restore", result) : result;
+  }
+  const result: CliResult = {
+    exitCode: 1,
+    stdout: "",
+    stderr: page(
+      `Unknown command: ${command}\nRun ${bold("bunx skvlt --help")} for usage.`,
+    ),
+    errorCode: "UNKNOWN_COMMAND",
+  };
+  return extracted.json ? toJsonResult(command, result) : result;
+}
+
+/**
+ * Executes the CLI entrypoint and writes buffered output to the process streams.
+ */
+export async function main(
+  argv: string[] = process.argv.slice(2),
+): Promise<number> {
+  const result = await runCli(argv, {
+    reportProgress: (chunk) => {
+      process.stdout.write(chunk);
+    },
+    streamOutput: true,
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    console.error(result.stderr.trimEnd());
+  }
+  return result.exitCode;
+}
+
+if (import.meta.main) {
+  const exitCode = await main();
+  process.exit(exitCode);
+}