@geoly-ai/skills-hub 0.1.0 → 0.3.0

package/src/cli.mjs

@@ -14,10 +14,10 @@ import { Output } from './commands/output.mjs';
 import { createCacheRegistry } from './commands/registry.mjs';
 import { EXIT, classify, UsageError } from './exit-codes.mjs';
 
-const HELP = `skills-hub —— geoly skill 分发（M1）
+const HELP = `skills-hub —— geoly skill 分发（M1 + M2 的命令面）
 
 命令：
-  install <spec>…                    装制品（direct；pack 与 --all 在 M2）
+  install <spec>… | install --all    装制品（skill / pack:；--all 见 09-cli.md §3）
   list [--packs|--installed|--outdated]
   search <kw>…
   check                              两阶段校验（字节 / 现在还该不该用）
@@ -25,6 +25,8 @@ const HELP = `skills-hub —— geoly skill 分发（M1）
   sync-lock                          在 repo 锁下重算 geoly-skills.lock.json
   recover [--continue|--rollback|--reinstall] [--from-generation N [--only x]…]
           [--reset-generation N] [--resume-cleanup]
+  vendor <pack-spec> --out <dir> [--layout flat]
+                                     把 pack 与全部成员物化成一棵目录树（不走安装账本）
 
   stats [--json] [--export <file>]   本地埋点报表
   telemetry <status|flush>           埋点/上报开关与队列
@@ -40,11 +42,22 @@ const HELP = `skills-hub —— geoly skill 分发（M1）
   --allow-yanked              仅取证；大声告警并写进账本（不放行 degraded）
   --replace <name>            点名替换未被账本认领的同名目录
   --no-bundled / --pre / --json / --yes
+  --yes-i-really-want-everything  仅 --all 在非交互下使用（--yes 不够）
   --keep-generations <N>      attic 保留代数，默认 3
 
 🔴 没有 --no-verify、--insecure、--force、--force-unlock、--assume-idle。
    验签与摘要校验不可关闭；替换必须点名；陈旧/yank/全量各有独立开关。
 
+埋点（docs/telemetry/00-spec.md）：
+  🔴 上报**默认开**（有内置默认端点）。**install 成功收尾后**会静默发一次
+     （24 小时最多一次，超时 1 秒，失败不影响安装）；别的命令只写本地，
+     也可以随时 \`telemetry flush\` 手动发。
+     采集面是穷举白名单 —— 不含路径、目录清单、文件内容、用户名。
+  GEOLY_TELEMETRY=0           完全关闭：本地一个字节都不写
+  GEOLY_TELEMETRY_UPLOAD=0    只留本地统计，不上报
+  GEOLY_TELEMETRY_ENDPOINT    改上报端点（必须 https；空值视为配置错误）
+  --offline                   单次命令禁止一切网络出口，埋点上报同样被否决
+
 退出码（§6）：0 成功 · 1 用法 · 2 完整性 · 3 冲突 · 4 部分失败 · 5 需 recover/锁忙
               6 网络 · 7 认证 · 8 陈旧 · 9 平台/文件系统 · 10 不可写 · 11 CLI 版本过低
 `;
@@ -58,6 +71,7 @@ const COMMANDS = {
   check: () => import('./commands/check.mjs').then((m) => m.cmdCheck),
   'sync-lock': () => import('./commands/sync-lock.mjs').then((m) => m.cmdSyncLock),
   recover: () => import('./commands/recover.mjs').then((m) => m.cmdRecover),
+  vendor: () => import('./commands/vendor.mjs').then((m) => m.cmdVendor),
 };
 
 /**
@@ -107,6 +121,17 @@ export async function main(argv, deps = {}) {
   const out = new Output({ json: globals.json, stdout, stderr });
   const cmd = rest[0];
 
+  // 🔴 首次运行的埋点告知。上报默认开（2026-09-01 拍板），所以**必须**在用户的
+  //    第一条命令上把「收什么 / 发到哪 / 怎么关」说清楚，且只说一次。
+  //    · 走 stderr：`--json` 下 stdout 只能有一个 JSON 对象（§7 输出契约）。
+  //    · 放在这里而不是各命令里：它要覆盖**所有**命令，漏一条就有人被绕过告知。
+  //    · 整个过程不许影响主命令（T-5），所以异常一律吞掉。
+  //    🔴 **它必须先于任何一次自动上报**（§5.1.1）——「先发了再告诉你」比不告知
+  //      更糟。这里的位置（命令分发之前）是第一道保证；第二道在 maybeAutoUpload
+  //      里：告知的标记文件不存在就不发。两道都在，是因为第一道只是**调用顺序**，
+  //      挪一行代码就能悄悄反过来而不会有任何东西变红。
+  await noticeOnce(stderr);
+
   if (cmd === undefined || cmd === '-h' || cmd === '--help' || cmd === 'help') {
     if (globals.json) return out.emit('help', { help: HELP }, EXIT.OK);
     stdout.write(HELP);
@@ -131,13 +156,70 @@ export async function main(argv, deps = {}) {
     const record = base.record ?? (await import('./telemetry.mjs')).record;
     const ctx = Object.freeze({ ...base, record, registry });
     const run = await load();
-    return await run(ctx, rest.slice(1), out);
+    const code = await run(ctx, rest.slice(1), out);
+    // 🔴 自动上报的**唯一**触发点（规格 §5.1.1，2026-09-01 拍板）。
+    //
+    // 判据两条，缺一不可：
+    //   · `cmd === 'install'` —— 只有安装，别的命令一律不出网；
+    //   · `code === EXIT.OK` —— 而且必须是**完全成功**。
+    //     ⚠️ `EXIT.PARTIAL`（4，部分 target 失败）**不算**：一次没装干净的
+    //        安装不该再替用户付一次网络代价。那批事件不会丢，留在本地等下一次
+    //        成功的 install 或用户手动 flush（§5.2.2）。
+    //     ⚠️ 抛错的路径根本走不到这里（下面的 catch 接住了），所以「失败不发」
+    //        不是靠记得写 if，而是靠控制流。
+    //
+    // 🔴 这里 `await`，不是发了就不管：进程一退，在途的 POST 就没了。
+    //    ⚠️ 代价是**这一次 install 会等它**。网络那一段有 1 秒上界
+    //    （AUTO_UPLOAD_TIMEOUT_MS），但**整段没有**：认领戳的 fsync、上报锁、
+    //    stage/reap 都是超时之外的同步 I/O。别把「最多多 1 秒」说成整体保证
+    //    （规格 §5.1.1 已按实话改写）。
+    //
+    // 🔴 返回值**故意丢弃**：不打印、不改退出码。一次成功的 install 绝不能
+    //    因为埋点失败而看起来像失败了。
+    // 🔴 走 `autoUploadQuietly` 而不是在这里直接 `await import(...)`：
+    //    这一段在 try 里，一个失败的动态 import 会被下面的 catch 接住、
+    //    走 emitError —— 于是**一次成功的 install 会被埋点变成一次失败的输出**。
+    //    正是本次拍板里那条硬要求要防的事。所以吞错要在调用点里面，不在外面。
+    if (cmd === 'install' && code === EXIT.OK) await autoUploadQuietly();
+    return code;
   } catch (err) {
     const cls = classify(err);
     return out.emitError(cmd, cls, err);
   }
 }
 
+/**
+ * install 成功收尾后的自动上报（规格 §5.1.1）。**整段完全静默。**
+ *
+ * 🔴 连 `import` 都包在 try 里：`maybeAutoUpload` 自己不抛，但把它取进来这一步
+ *    会（模块求值失败、文件被删）。差别不是理论上的 —— 调用点在 `main` 的 try 里，
+ *    漏出去的异常会被顶层 catch 变成 `emitError`，用户看到的是一次**失败的 install**，
+ *    而磁盘上其实一切正常。
+ */
+async function autoUploadQuietly() {
+  try {
+    const { maybeAutoUpload } = await import('./upload.mjs');
+    await maybeAutoUpload();   // 返回值故意不看：不打印、不改退出码
+  } catch { /* 埋点的任何问题都不许冒泡到主命令（T-5） */ }
+}
+
+/**
+ * 首次运行时打印埋点告知（只打一次）。任何失败都不得影响主命令。
+ *
+ * ⚠️ 端点在这里解析而不是在 telemetry.mjs 里：upload.mjs 依赖 telemetry.mjs，
+ *    反过来 import 会成环。
+ */
+async function noticeOnce(stderr) {
+  try {
+    const tm = await import('./telemetry.mjs');
+    if (!tm.enabled() || !tm.uploadEnabled()) return;   // 没有出网就没什么可告知的
+    const { endpoint } = await import('./upload.mjs');
+    let url = null;
+    try { url = endpoint(); } catch { return; }         // 端点配坏了 = 不会出网
+    tm.maybeNoticeUpload((s) => stderr.write(s), url);
+  } catch { /* 告知不是主命令的一部分（T-5） */ }
+}
+
 // ── 内部探针 ─────────────────────────────────────────────────────────────────
 
 async function warnProbe(stdout) {
@@ -190,7 +272,9 @@ async function cmdTelemetry(args, stdout, stderr) {
           : '关（GEOLY_TELEMETRY_UPLOAD=0）';
       stdout.write(`埋点      ${tm.enabled() ? '开' : '关（GEOLY_TELEMETRY=0）'}\n`);
       stdout.write(`上报      ${tm.uploadEnabled() ? '开' : uploadOff}\n`);
-      stdout.write(`端点      ${ep ?? '未配置 —— 纯本地'}\n`);
+      // 🔴 端点默认开（2026-09-01 拍板），所以「这是内置默认值」必须写在脸上：
+      //    用户有权知道数据默认发去哪，而不是去翻源码才发现有个默认端点。
+      stdout.write(`端点      ${ep ?? '无'}${ep && up.isDefaultEndpoint() ? '（内置默认值 —— 未配 GEOLY_TELEMETRY_ENDPOINT）' : ''}\n`);
       stdout.write(`待上报    ${tm.readAll().length} 条\n`);
       stdout.write(`报表历史  ${tm.readHistory().length} 条（上报不消费它）\n`);
       stdout.write(`状态目录  ${tm.stateDir()}\n`);
@@ -198,8 +282,14 @@ async function cmdTelemetry(args, stdout, stderr) {
     }
     case 'flush': {
       const r = await up.flush();
-      stdout.write(r.skipped ? `未上报：${r.reason}\n` : `已上报 ${r.sent} 条\n`);
-      return r.skipped && r.reason?.startsWith('error:') ? EXIT.USAGE : EXIT.OK;
+      stdout.write(r.skipped
+        ? `未上报：${r.reason}${r.detail ? `（${r.detail}）` : ''}\n`
+        : `已上报 ${r.sent} 条\n`);
+      // 🔴 `bad-endpoint` 也要非零退出：它是**配置错误**，不是「这次没什么可发的」。
+      //    退 0 意味着脚本永远发现不了「端点变量填空了、这台机器从此不上报」。
+      //    ⚠️ `offline` / `upload-disabled` / `empty` / `busy` 都是正常状态，退 0。
+      const bad = r.skipped && (r.reason === 'bad-endpoint' || r.reason?.startsWith('error:'));
+      return bad ? EXIT.USAGE : EXIT.OK;
     }
     default:
       stderr.write('用法：skills-hub telemetry <status|flush>\n');

package/src/commands/context.mjs

@@ -222,8 +222,21 @@ export function makeContext(globals, deps = {}) {
     verifier: deps.verifier ?? null,
     /** 注入点：测试用内存 registry，生产用 `registry.mjs` 的缓存适配器 */
     registryFactory: deps.registryFactory ?? null,
+    /**
+     * 注入点：出网。生产走内建 `fetch`（`src/download.mjs` 的默认值）。
+     * 🔴 与 `verifier` 一样**没有逃生口**：不给就是真出网，
+     *    不存在「测试忘了注入所以静默不出网」这种状态 ——
+     *    那会让「--offline 有没有被绕过」这个问题看起来被回答了，其实没有。
+     */
+    fetchImpl: deps.fetchImpl ?? null,
     /** 注入点：埋点。生产是 `telemetry.record` */
     record: deps.record ?? null,
+    /**
+     * 注入点：标准输入。**只有 `install --all` 的 §3 全量确认用它**。
+     * 🔴 交互与否的判据是 `isTTY`，不是「有没有 stdin」—— 管道进来的 stdin
+     *    照样可读，但那不是「用户正坐在终端前逐条看名单」。
+     */
+    stdin: deps.stdin ?? process.stdin,
   });
   return ctx;
 }