@geoly-ai/skills-hub 0.1.0

package/src/commands/locks.mjs

@@ -0,0 +1,197 @@
+// 加锁 —— 04-install.md §5.1「加锁顺序（全序，防死锁）」。
+//
+//     metadata 锁（仅验证与推进 trust floor，用完立即释放）
+//       → repo 锁（仅项目级；保护 lockfile 重算与写入）
+//         → target 锁（多个时按 (st_dev, st_ino) 字节序升序）
+//
+// 🔴 **不得存在任何「先 target 后 repo」的路径。**
+//
+// 🔴 metadata 锁**不由本模块取**。`trust.advanceTrustFloor()` 自己 acquire/release
+//    （src/trust.mjs），而 `src/lock.mjs` **禁止重入** —— 命令面再包一层就会在
+//    第二次 acquire 时直接抛「本进程已持有」。因此正确的形状是：
+//      ① 先跑完解析阶段（`snapshot.resolveCurrent()`，metadata 锁在它内部起落）；
+//      ② 解析返回之后，再按 repo → target 取事务锁。
+//    全序仍然成立：metadata 的持有区间整个位于 repo/target 之前。
+//
+// 🔴 后续取锁失败时，对已持有的锁**逐一 ROLLBACK + close 再退出**，
+//    不得带着半套锁做任何事。
+
+import { statSync, lstatSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { acquire } from '../lock.mjs';
+import { mkdirChainFsync } from '../atomic-fs.mjs';
+import { STATE_DIR } from '../adapters/index.mjs';
+import { assertNoSymlinkInChain } from '../safe-fs.mjs';
+import { EXIT, UnsupportedError } from '../exit-codes.mjs';
+
+/** repo 锁的位置（§8.1）。 */
+export const repoLockPath = (projectRoot) => join(projectRoot, '.geoly-skills.lock.db');
+
+/** target 锁的位置（§5.1.1）：**target 自身的一部分**，别名路径打开同一个 inode。 */
+export const targetLockPath = (target) => join(target, STATE_DIR, 'lock.db');
+
+/**
+ * (st_dev, st_ino) 的定宽排序键。
+ *
+ * 🔴 **不是按 realpath 排序**：bind alias 下 realpath 不稳定，
+ *    两个进程可能算出相反顺序而互相卡死（§5.1 明确禁止）。
+ * 🔴 定宽 hex 才等价于「字节序」：`String(dev)` 会让 9 排在 10 后面。
+ */
+function physicalKey(dev, ino) {
+  const h = (n) => BigInt(n).toString(16).padStart(20, '0');
+  return `${h(dev)}:${h(ino)}`;
+}
+
+/**
+ * 按 §5.1 对 target 集合**去重 + 排序**。
+ *
+ * @param {string[]} targets  绝对路径。**必须已经存在** —— `--create-missing` 的建目录
+ *        动作发生在这之前（见 `install.mjs` 的注释：它是本次运行的第一个磁盘写入，
+ *        失败时留下的是一个空的客户端目录，而不是半个事务）。
+ * @returns {{path:string, key:string, dev:number, ino:number, aliases:string[]}[]}
+ */
+export function orderTargets(targets) {
+  const byKey = new Map();
+  for (const t of targets) {
+    const st = statSync(t);   // target 用 stat：它可以是被 realpath 过的正常目录
+    const key = physicalKey(st.dev, st.ino);
+    const cur = byKey.get(key);
+    if (cur) { cur.aliases.push(t); continue; }   // 🔴 bind-alias 去重
+    byKey.set(key, { path: t, key, dev: st.dev, ino: st.ino, aliases: [] });
+  }
+  return [...byKey.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+/**
+ * 🔴 **取锁之前**的窄门：`.geoly/` 与三个锁文件都不许是 symlink。
+ *
+ * 为什么不能等到 §5.2 第 3 步的预检：锁**就在 `.geoly/` 里面**（§5.1.1），
+ * 而取锁是第 1 步。`new DatabaseSync(path)` 会**跟随** symlink ——
+ * 把 `.geoly` 或 `lock.db` 换成指向别处的软链，我们就会在 target 之外
+ * 创建并写入 holder 表，而内核那道 `assertStatePathsNoSymlink()` 要到第 2 步才跑。
+ * 那不只是「错误码落错格」，是一个**写入路径穿越**。
+ *
+ * ⚠️ **这是窄门，不是完整的 §3.4 检查**：它只覆盖取锁这一步真正会打开的那几个路径，
+ * 而且与 R-1 / R-2 同样是 TOCTOU 的（Node 不暴露 `openat`）。
+ * 完整的路径链检查仍然在第 3 步的 `precheckTarget()` 里。
+ */
+function assertLockPathsNotSymlink(target, base = null) {
+  const reject = (msg) => {
+    // 🔴 这是 §3.4 那一类（路径安全），按 §6 第 9 条落 **9**，不是 5。
+    //    早先它被命名成 Corrupt 因而落 5 —— 那会把「路径穿越」报成「需要 recover」。
+    throw new UnsupportedError(msg, { telemetryReason: 'unknown' });
+  };
+  // ① 整条路径链：从可信 base 一路查到 target 自己。
+  //    只查最后一个节点是不够的 —— 父级被换成软链同样能把状态写到 target 之外。
+  if (base) {
+    const rel = target.startsWith(base + sep) ? target.slice(base.length + 1) : null;
+    if (rel === null) reject(`target 不在可信 base 之下：${target} 不在 ${base} 里`);
+    try { assertNoSymlinkInChain(base, rel); } catch (e) { reject(`取锁前的路径链检查不通过：${e.message}`); }
+  }
+  // ② 取锁这一步真正会 open 的那几个路径，逐个 lstat 无跟随
+  const state = join(target, STATE_DIR);
+  for (const p of [state, join(state, 'lock.db'), join(state, 'lock.db-wal'), join(state, 'lock.db-shm')]) {
+    let st;
+    try { st = lstatSync(p); } catch (e) {
+      if (e?.code === 'ENOENT') continue;      // 还没有 —— 稍后由我们自己建
+      reject(`取锁前无法 lstat ${p}（${e.code}）—— 看不见就不能声称它是安全的`);
+    }
+    if (st.isSymbolicLink()) {
+      reject(`拒绝取锁：${p} 是 symlink（04-install.md §3.4）。`
+        + '锁文件由 SQLite 直接打开，会跟随软链把状态写到 target 之外。');
+    }
+  }
+  const st = lstatSync(target);
+  if (!st.isDirectory()) reject(`拒绝取锁：${target} 不是普通目录（lstat 无跟随判定）`);
+}
+
+/** repo 锁也要过同一道门 —— 它同样是被 SQLite 直接 open 的。 */
+function assertRepoLockNotSymlink(projectRoot) {
+  const base = repoLockPath(projectRoot);
+  for (const p of [base, `${base}-wal`, `${base}-shm`]) {
+    let st;
+    try { st = lstatSync(p); } catch (e) {
+      if (e?.code === 'ENOENT') continue;
+      throw new UnsupportedError(`取 repo 锁前无法 lstat ${p}（${e.code}）`, { telemetryReason: 'unknown' });
+    }
+    if (st.isSymbolicLink()) {
+      throw new UnsupportedError(
+        `拒绝取 repo 锁：${p} 是 symlink（04-install.md §3.4）`, { telemetryReason: 'unknown' },
+      );
+    }
+  }
+}
+
+/**
+ * 按全序取 repo → target 锁，跑 `fn`，然后**逆序**释放。
+ *
+ * @param {object} o
+ * @param {string|null} o.projectRoot  非 null 时取 repo 锁
+ * @param {string[]}    o.targets      物理 target 目录（已存在）
+ * @param {(held:{targets:object[], repo:string|null}) => any} fn
+ *
+ * 🔴 `fn` 抛错时锁按 `commit: true` 释放。理由：holder 行是**诊断信息**，
+ *    不是事务数据；ROLLBACK 掉它只会让下一个人看到更旧的 pid。
+ *    真正需要 ROLLBACK 的是**取锁过程中途失败**那条路径（见下面的 catch）——
+ *    那时半套锁一个都不该留下痕迹。
+ */
+export function withOrderedLocks({ projectRoot = null, targets = [], baseFor = () => null }, fn) {
+  const ordered = orderTargets(targets);
+  const held = [];
+  try {
+    // ① repo 锁（仅项目级）
+    if (projectRoot !== null) {
+      assertRepoLockNotSymlink(projectRoot);
+      held.push(acquire(repoLockPath(projectRoot)));
+    }
+    // ② target 锁，去重后按 (st_dev, st_ino) 升序
+    for (const t of ordered) {
+      // 🔴 `<target>/.geoly/` 由取锁这一步建出来（锁就在它里面，§5.1.1）。
+      //    这是**规范自身的形状**，不是我们多建的：崩在这里会留下一个空的
+      //    `.geoly/lock.db`，下一次运行照常取锁、照常继续 —— 幂等，不是半截事务。
+      // 🔴 建不出 `.geoly/` 就是 §6 第 10 条那一格（「target 不可写（无法创建
+      //    `<target>/.geoly/`）」）—— 那正是这条退出码的字面定义。
+      //    不映射的话它会以一条裸 EACCES 的身份落到「认不出来的错」里去。
+      //    ⚠️ 这道判定发生在**第 1 步**（取锁），比 §5.2 第 3 步的预检更早 ——
+      //    因为锁就在 `.geoly/` 里面，建不出来就根本进不到预检。
+      assertLockPathsNotSymlink(t.path, baseFor(t.path));
+      try {
+        mkdirChainFsync(join(t.path, STATE_DIR));
+      } catch (e) {
+        // 🔴 并发建目录：`mkdirChainFsync` 是 existsSync → mkdirSync，不是原子的。
+        //    两个进程同时启动时输家会拿到裸 EEXIST —— 那不是错误，目录已经在了。
+        if (e?.code === 'EEXIST') {
+          // 🔴 EEXIST 只说明「那个名字被占了」，**不说明占它的是一个普通目录**。
+          //    一律放行的话，一个抢在我们前面建出来的 symlink / 普通文件就穿过了窄门。
+          const st = lstatSync(join(t.path, STATE_DIR));
+          if (st.isSymbolicLink() || !st.isDirectory()) {
+            throw new UnsupportedError(
+              `${join(t.path, STATE_DIR)} 被一个非普通目录占用（并发竞态或有人塞了东西）`,
+              { telemetryReason: 'unknown' },
+            );
+          }
+        }
+        else if (e?.code === 'EACCES' || e?.code === 'EPERM' || e?.code === 'EROFS') {
+          const err = new Error(
+            `target 不可写：建不出 ${join(t.path, STATE_DIR)}（${e.code}）。`
+            + '锁与全部事务状态都在这个目录里，建不出来就无从开始（04-install.md §3.6 / §5.1.1）。',
+          );
+          err.name = 'TargetNotWritable';
+          err.exitCode = EXIT.NOT_WRITABLE;
+          err.telemetryReason = 'target-not-writable';
+          throw err;
+        } else throw e;
+      }
+      held.push(acquire(targetLockPath(t.path)));
+    }
+  } catch (e) {
+    // 🔴 半套锁：逐一 ROLLBACK + close 再把错抛出去
+    for (const r of held.reverse()) { try { r({ commit: false }); } catch { /* 已经坏了 */ } }
+    throw e;
+  }
+  try {
+    return fn({ targets: ordered, repo: projectRoot === null ? null : repoLockPath(projectRoot) });
+  } finally {
+    for (const r of held.reverse()) { try { r(); } catch { /* 释放尽力而为 */ } }
+  }
+}

package/src/commands/output.mjs

@@ -0,0 +1,127 @@
+// 输出契约 —— 09-cli.md §7。
+//
+//   · 人类输出 stdout；进度与告警 stderr。
+//   · `--json` 时 stdout **只有**一个 JSON 对象 —— 🔴 **成功、用法错误、解析失败、
+//     锁被占用、内部错误，每一条路径都是**。只在成功路径上给一个 JSON 对象，
+//     等于让脚本在失败时读到空 stdout 然后自己去猜。
+//   · 每次 `install` 结尾必须打印逐 target 结果表，即使全部成功。**不允许只打一句 done。**
+//   · stale / offline / yanked / degraded / shadowed 必须在**每一次**相关输出里重复标注。
+//     🔴 因此这些标注挂在**每一个** target / artifact 结果对象上，不是只挂顶层一份 ——
+//     顶层一份的话，一份逐行表格里没有一行看得出自己是 stale 的。
+//
+// 🔴 **JSON 的 schema 名不是 wire contract 的一部分。**
+//    11-wire-contract.md §1 的适用对象清单里**没有** CLI 的 `--json` 输出。
+//    这里复用 §3 的 canonical 生成规则（同一个 `stringify`，schema 首位、字节序、
+//    2 空格、结尾一个 \n、非 ASCII 小写 hex 转义），但 `geoly.skills.cli.<cmd>/1`
+//    这个名字与它的字段表**尚未登记进规范**。这条写进交付汇报，由规格侧决定是否收编。
+
+import { stringify } from '../canonical-json.mjs';
+
+/** 每个命令一个 schema 名。🔴 见上：**未登记**，不得对外宣称是 wire contract。 */
+export const CLI_SCHEMA = (cmd) => `geoly.skills.cli.${cmd}/1`;
+
+/** 🔴 canonical JSON 不接受 `undefined`（`enc` 会抛「不支持的类型」）。递归剔除。 */
+export function pruneUndefined(v) {
+  if (Array.isArray(v)) return v.map(pruneUndefined);
+  if (v !== null && typeof v === 'object') {
+    const out = {};
+    for (const [k, val] of Object.entries(v)) if (val !== undefined) out[k] = pruneUndefined(val);
+    return out;
+  }
+  return v;
+}
+
+/**
+ * 标注集合。🔴 挂在**每一个**结果对象上，不是只挂顶层。
+ * 值一律是布尔，`false` 也写出来 —— 「字段缺席」在这里会被误读成「查过了，没事」。
+ */
+export function annotations({ stale = false, offline = false, yanked = false, degraded = false, shadowed = false } = {}) {
+  return { degraded, offline, shadowed, stale, yanked };
+}
+
+/** 人类可读的标注后缀，例如 ` [stale] [offline] [yanked]`。空则返回空串。 */
+export function annotationSuffix(a) {
+  const on = [];
+  if (a.stale) on.push('stale');
+  if (a.offline) on.push('offline');
+  if (a.yanked) on.push('yanked');
+  if (a.degraded) on.push('degraded');
+  if (a.shadowed) on.push('shadowed');
+  return on.length ? ` ${on.map((s) => `[${s}]`).join(' ')}` : '';
+}
+
+export class Output {
+  constructor({ json = false, stdout = process.stdout, stderr = process.stderr } = {}) {
+    this.json = json;
+    this._out = stdout;
+    this._err = stderr;
+    this._warnings = [];
+    this._emitted = false;
+  }
+
+  /** 进度 —— 永远 stderr。`--json` 下也照常输出（stdout 才是被要求干净的那个）。 */
+  note(msg) { this._err.write(`${msg}\n`); }
+
+  /**
+   * 告警 —— stderr，**并且**进 JSON 的 `warnings`。
+   * `planTargets()` 的 `duplicate-catalog` 走这条：09-cli.md 要求展示给用户，不得吞掉。
+   */
+  warn(obj) {
+    const w = typeof obj === 'string' ? { kind: 'general', message: obj } : obj;
+    this._warnings.push(w);
+    this._err.write(`⚠️ ${w.message}\n`);
+    return w;
+  }
+
+  warnings() { return this._warnings.slice(); }
+
+  /** 人类行 —— stdout。`--json` 下**一个字节都不写**（stdout 只能有那一个对象）。 */
+  line(msg = '') { if (!this.json) this._out.write(`${msg}\n`); }
+
+  /**
+   * 收尾。`--json` 时写出**唯一**那个对象；否则什么都不写（人类输出已经逐行打过了）。
+   * 🔴 只允许调一次 —— 调两次就破了「stdout 只有一个 JSON 对象」。
+   */
+  emit(cmd, body, exitCode) {
+    if (this._emitted) throw new Error('输出契约：一次运行只能 emit 一个 JSON 对象');
+    this._emitted = true;
+    if (!this.json) return exitCode;
+    const doc = pruneUndefined({
+      schema: CLI_SCHEMA(cmd),
+      command: cmd,
+      exit_code: exitCode,
+      ok: exitCode === 0,
+      warnings: this._warnings,
+      ...body,
+    });
+    this._out.write(stringify(doc));
+    return exitCode;
+  }
+
+  /**
+   * 失败收尾。`--json` 下同样只有一个对象。
+   * @param {string} cmd
+   * @param {{code:number, unclassified:boolean}} cls  `exit-codes.classify()` 的产物
+   */
+  emitError(cmd, cls, err, extra = {}) {
+    const message = err?.message ?? String(err);
+    if (!this.json) {
+      this._err.write(`${cls.unclassified ? '内部错误（CLI 自身的 bug，不是制品有问题）：' : ''}${message}\n`);
+    }
+    return this.emit(cmd, {
+      error: pruneUndefined({
+        exit_code: cls.code,
+        // 机器可读的错误名：内核错误用它自己的 name，我们自己的用类名
+        name: err?.name ?? 'Error',
+        message,
+        unclassified: cls.unclassified,
+        // 预检聚合错带全部违规项 —— 🔴 JSON 里**始终保留全部**，不只报优先级最高那条
+        violations: Array.isArray(err?.violations)
+          ? err.violations.map((v) => ({ code: v.code, message: v.message, path: v.path }))
+          : undefined,
+        candidates: Array.isArray(err?.candidates) ? err.candidates : undefined,
+      }),
+      ...extra,
+    }, cls.code);
+  }
+}

package/src/commands/query.mjs

@@ -0,0 +1,266 @@
+// `list` / `search` / `why` —— 09-cli.md §1。
+//
+// 取锁表（§5.1）：这三个命令 **只取 metadata 锁，且仅在需要验签时** ——
+// 而 metadata 锁在 `trust.advanceTrustFloor()` 内部起落，命令面不碰。
+// **不取 repo 锁、不取 target 锁**：它们只读。
+//
+// 🔴 只读也要如实标注：stale / offline / yanked / degraded / shadowed
+//    在**每一次**相关输出里重复出现（§7），因此挂在每一行上，不是只挂顶层。
+
+import { existsSync } from 'node:fs';
+import { layout, readLedger } from '../ledger.mjs';
+import { planTargets, assertPlanOk, getAdapter } from '../adapters/index.mjs';
+import { UsageError, EXIT } from '../exit-codes.mjs';
+import { resolveSnapshotForCommand, isDegradable } from './snapshot-access.mjs';
+import { annotations, annotationSuffix } from './output.mjs';
+
+/** 枚举本次命令覆盖到的 target（不要求存在 .geoly）。 */
+export function targetsFor(ctx, out) {
+  const tplan = planTargets({
+    clients: ctx.clients,
+    scope: ctx.scope,
+    home: ctx.home,
+    env: ctx.env,
+    projectRoot: ctx.projectRoot,
+  });
+  for (const w of tplan.warnings) out.warn(w);
+  assertPlanOk(tplan);
+  return tplan;
+}
+
+/** 读一个 target 的账本；没有就返回 null（不是错）。 */
+export function ledgerOf(target) {
+  const P = layout(target);
+  if (!existsSync(P.ledger)) return null;
+  return readLedger(P.ledger);
+}
+
+/** 已装清单：`[{ client, scope, target, name, entry }]` */
+export function installedEntries(tplan) {
+  const rows = [];
+  for (const t of tplan.selected) {
+    const L = ledgerOf(t.target);
+    if (!L) continue;
+    for (const [name, e] of Object.entries(L.entries)) {
+      rows.push({ client: t.client, scope: t.scope, target: t.target, name, entry: e });
+    }
+  }
+  return rows;
+}
+
+/** §8.2：项目级/全局并存 —— 如实报告，🔴 **不声称哪份生效**。 */
+export function shadowMap(ctx, tplan) {
+  const m = new Map();
+  if (ctx.scope !== 'project') return m;
+  for (const t of tplan.selected) {
+    const g = getAdapter(t.client).root({ scope: 'global', home: ctx.home, env: ctx.env });
+    const L = ledgerOf(g);
+    if (!L) continue;
+    for (const name of Object.keys(L.entries)) {
+      if (!m.has(name)) m.set(name, []);
+      m.get(name).push({ client: t.client, globalTarget: g, artifact: L.entries[name].artifact });
+    }
+  }
+  return m;
+}
+
+export async function cmdList(ctx, argv, out) {
+  const o = { packs: false, installed: false, outdated: false };
+  for (const a of argv) {
+    if (a === '--packs') o.packs = true;
+    else if (a === '--installed') o.installed = true;
+    else if (a === '--outdated') o.outdated = true;
+    else throw new UsageError(`list 不认得 ${a}`);
+  }
+  const tplan = targetsFor(ctx, out);
+  const installed = installedEntries(tplan);
+  const shadowed = shadowMap(ctx, tplan);
+
+  // 🔴 `--installed` 是纯本地的：**不解析快照**，因此离线也一定能跑。
+  //    `--outdated` 与默认列表要拿当前快照对照。
+  let snap = null;
+  let stale = false;
+  let snapError = null;
+  if (!o.installed || o.outdated) {
+    try {
+      const r = await resolveSnapshotForCommand(ctx);
+      snap = r.snapshot;
+      stale = r.stale;
+    } catch (e) {
+      // 🔴 只有「取不到」（退出码 6）可以降级。stale（8）、完整性（2）、
+      //    min-cli（11）必须原样抛出去 —— 吞掉它们等于让 `list` 在一张过期或
+      //    被篡改的信任根上照常绿灯。
+      if (!isDegradable(e)) throw e;
+      // 离线 / 缓存未命中不该让 `list` 整个失败，但**绝不能**默默当成
+      // 「没有更新」。如实降级：只列本地，并把每一行标成 offline。
+      snapError = e;
+      out.warn(`取不到当前快照（${e.message.split('\n')[0]}）：只列本地已装，远端信息标为未知`);
+    }
+  }
+  if (stale) out.warn('timestamp 已过期：以下每一行都按 stale 处理');
+
+  const rows = [];
+  if (o.installed || snap === null) {
+    for (const r of installed) {
+      rows.push({
+        annotations: annotations({
+          stale,
+          offline: ctx.offline || snapError !== null,
+          shadowed: shadowed.has(r.name),
+        }),
+        artifact: r.entry.artifact,
+        client: r.client,
+        installed: true,
+        latest: null,
+        name: r.name,
+        scope: r.scope,
+        snapshot: r.entry.snapshot,
+        target: r.target,
+      });
+    }
+  } else {
+    const kind = o.packs ? 'pack' : 'skill';
+    const byName = new Map(installed.map((r) => [`${r.client} ${r.name}`, r]));
+    for (const rec of snap.artifacts) {
+      if (rec.kind !== kind) continue;
+      // 每个 name 只列它的 latest 那一行（latest 投影已由 parseSnapshot 校验自洽）
+      if (snap.latest[`${rec.kind}:${rec.namespace}/${rec.name}`] !== rec.version) continue;
+      for (const t of tplan.selected) {
+        const hit = byName.get(`${t.client} ${rec.name}`);
+        const isOutdated = hit ? hit.entry.artifact !== rec.id : false;
+        if (o.outdated && !isOutdated) continue;
+        rows.push({
+          annotations: annotations({
+            stale,
+            offline: ctx.offline,
+            yanked: rec.status === 'yanked',
+            degraded: rec.status === 'degraded',
+            shadowed: shadowed.has(rec.name),
+          }),
+          artifact: hit ? hit.entry.artifact : null,
+          client: t.client,
+          installed: Boolean(hit),
+          latest: rec.id,
+          name: rec.name,
+          scope: t.scope,
+          snapshot: hit ? hit.entry.snapshot : null,
+          target: t.target,
+        });
+      }
+    }
+  }
+
+  out.line(`list（${rows.length} 行${snap ? `，快照 ${snap.snapshot}` : '，仅本地'}）：`);
+  for (const r of rows) {
+    const state = r.installed
+      ? (r.latest && r.latest !== r.artifact ? 'outdated' : 'installed')
+      : 'available';
+    out.line(`  ${state.padEnd(10)}${r.client}/${r.scope}  ${r.name}  `
+      + `${r.artifact ?? r.latest}${annotationSuffix(r.annotations)}`);
+  }
+  // §8.2：如实并列，**不声称哪份生效**
+  for (const [name, hits] of shadowed) {
+    out.line(`  [!] ${name} 项目级与全局并存（全局在 ${hits[0].globalTarget}）——`
+      + '生效者取决于客户端，本工具不做判断（04-install.md §8.2）');
+  }
+  return out.emit('list', {
+    rows,
+    shadowed: [...shadowed.keys()].sort(),
+    snapshot: snap ? snap.snapshot : undefined,
+    snapshot_unavailable: snapError ? snapError.message : undefined,
+  }, EXIT.OK);
+}
+
+export async function cmdSearch(ctx, argv, out) {
+  for (const a of argv) if (a.startsWith('-')) throw new UsageError(`search 不认得 ${a}`);
+  const kws = argv.filter((a) => !a.startsWith('-'));
+  if (kws.length === 0) throw new UsageError('用法：skills-hub search <kw>');
+  const { snapshot: snap, stale } = await resolveSnapshotForCommand(ctx);
+  if (stale) out.warn('timestamp 已过期：以下每一行都按 stale 处理');
+
+  // 🔴 规格说搜 name / description，但 `description` 在**载荷 manifest** 里，
+  //    快照 record 一个字段都没有它（见 snapshot.mjs 的 RECORD_KEYS）。
+  //    因此这里只搜 name 与 id，并**如实说明**，不假装搜过 description。
+  const needle = kws.map((k) => k.toLowerCase());
+  const hits = snap.artifacts.filter(
+    (r) => needle.every((k) => r.name.includes(k) || r.id.toLowerCase().includes(k)),
+  );
+  out.warn('只搜了 name/id：description 在制品的载荷 manifest 里，快照 record 不携带它。');
+  out.line(`search（${hits.length} 命中，快照 ${snap.snapshot}）：`);
+  const mk = (r) => annotations({
+    stale,
+    offline: ctx.offline,
+    yanked: r.status === 'yanked',
+    degraded: r.status === 'degraded',
+  });
+  for (const r of hits) {
+    out.line(`  ${r.id}  status=${r.status}  `
+      + `clients=${r.clients.join(',') || '(未声明)'}${annotationSuffix(mk(r))}`);
+  }
+  return out.emit('search', {
+    hits: hits.map((r) => ({
+      annotations: mk(r),
+      artifact: r.id,
+      clients: r.clients,
+      name: r.name,
+      status: r.status,
+    })),
+    searched_fields: ['id', 'name'],
+    snapshot: snap.snapshot,
+  }, EXIT.OK);
+}
+
+/** `why <name>` —— 谁请求装的（读账本 `roots` + `requested_by`）。纯本地，不取快照。 */
+export async function cmdWhy(ctx, argv, out) {
+  for (const a of argv) if (a.startsWith('-')) throw new UsageError(`why 不认得 ${a}`);
+  const names = argv.filter((a) => !a.startsWith('-'));
+  if (names.length !== 1) throw new UsageError('用法：skills-hub why <name>（恰好一个）');
+  const name = names[0];
+  const tplan = targetsFor(ctx, out);
+  const shadowed = shadowMap(ctx, tplan);
+
+  const found = [];
+  for (const t of tplan.selected) {
+    const L = ledgerOf(t.target);
+    if (!L) continue;
+    const e = L.entries[name];
+    if (!e) continue;
+    found.push({
+      annotations: annotations({ offline: ctx.offline, shadowed: shadowed.has(name) }),
+      artifact: e.artifact,
+      client: t.client,
+      generation: e.generation,
+      installed_at: e.installed_at,
+      requested_by: e.requested_by.map((rk) => ({
+        // root 可能已经被删（refcount 归零前后的中间态），如实报告成悬挂边
+        record: L.roots[rk] ?? null,
+        root: rk,
+      })),
+      scope: t.scope,
+      snapshot: e.snapshot,
+      state: e.state,
+      target: t.target,
+    });
+  }
+
+  if (found.length === 0) {
+    out.line(`${name} 不在任何被检查的 target 的账本里。`);
+    return out.emit('why', { entries: [], name }, EXIT.OK);
+  }
+  out.line(`why ${name}：`);
+  for (const f of found) {
+    out.line(`  ${f.client}/${f.scope}  ${f.target}${annotationSuffix(f.annotations)}`);
+    out.line(`    artifact=${f.artifact}  snapshot=${f.snapshot}  `
+      + `第 ${f.generation} 代  state=${f.state}  installed_at=${f.installed_at}`);
+    for (const r of f.requested_by) {
+      out.line(`    <- ${r.root}${r.record ? '' : '（该 root 已不在账本里 —— 悬挂边）'}`);
+      if (r.record) {
+        out.line(`        kind=${r.record.kind} snapshot=${r.record.snapshot} `
+          + `intent={no_bundled:${r.record.intent.no_bundled}, pre:${r.record.intent.pre}`
+          + `${r.record.intent.allow_yanked ? ', allow_yanked:true' : ''}} `
+          + `requested_at=${r.record.requested_at}`);
+      }
+    }
+  }
+  return out.emit('why', { entries: found, name }, EXIT.OK);
+}