@neta-art/neta-search-cli 0.2.16 → 0.2.18

package/README.md

@@ -3,21 +3,23 @@
 Command-line client for **neta-search**, the skill registry of the Cohub / Neta platform: search the ecosystem for a ready-made skill, try it without installing, or install it into your space.
 
 ```bash
-npx -y @neta-art/neta-search-cli@0.2 skills find "generate video"     # search (Chinese or English)
-npx -y @neta-art/neta-search-cli@0.2 skills find "browser automation" --json
-npx -y @neta-art/neta-search-cli@0.2 skills use  <id>                 # print the SKILL.md (pulled into a temp dir; no project files written)
-npx -y @neta-art/neta-search-cli@0.2 skills add  <id>                 # install into .agents/skills/
-npx -y @neta-art/neta-search-cli@0.2 skills list                      # what's in .agents/skills/, and which installed ones have updates
-npx -y @neta-art/neta-search-cli@0.2 skills update                    # update installed skills to their current release
-npx -y @neta-art/neta-search-cli@0.2 skills init <name>               # scaffold your own skill
+npx -y @neta-art/neta-search-cli@latest skills find "generate video"     # search (Chinese or English)
+npx -y @neta-art/neta-search-cli@latest skills find "browser automation" --json
+npx -y @neta-art/neta-search-cli@latest skills use  <id>                 # print the SKILL.md (pulled into a temp dir; no project files written)
+npx -y @neta-art/neta-search-cli@latest skills add  <id>                 # install into .agents/skills/
+npx -y @neta-art/neta-search-cli@latest skills list                      # what's in .agents/skills/, and which installed ones have updates
+npx -y @neta-art/neta-search-cli@latest skills update                    # update installed skills to their current release (or name some: handle, id or directory)
+npx -y @neta-art/neta-search-cli@latest skills init <name>               # scaffold your own skill
 ```
 
-`<id>` comes from `find` results, e.g. `cohub:<spaceId>/<name>`; a handle such as `neta-skills/holo-pack-opening` works too.
+`<id>` is what `find` prints: a handle such as `neta-skills/holo-pack-opening` or `cohub/agent-browser`. Skills without a handle are listed as `cohub:<spaceId>/<name>`, which works everywhere a handle does. `update` and `remove` also accept the directory name under `.agents/skills/`.
 
-`skills remove <name>` deletes an installed skill from `.agents/skills/`. Skills you wrote yourself (no install record) are left alone unless you pass `--force`.
+`remove` deletes installed skills only. Skills you wrote yourself (no install record) are left alone unless you pass `--force`.
 
 `use` prints the skill directory and the full SKILL.md, so an agent can follow it right away; relative paths in SKILL.md resolve against that directory. If the local entry is a pointer (frontmatter `metadata.neta-skill-id`), `use` fetches the full skill it points to.
 
+Use `@latest` (or an exact version): with a range such as `@0.2`, npx keeps running whatever matching version it cached earlier and never checks for a newer one.
+
 Inside a Cohub sandbox the CLI picks up the sandbox identity automatically; elsewhere it runs anonymously.
 
 Single file, no runtime dependencies. Node.js 20+.

package/neta-search.mjs

@@ -27075,7 +27075,8 @@ async function fetchArchive(env, id) {
   const files = untarGz(body);
   const got = digestOf(new Map(files.map((f) => [f.path, f.data])));
   if (got !== digest) throw new Error(`\u4E0B\u8F7D\u7684 ${id} \u5185\u5BB9\u6821\u9A8C\u5931\u8D25\uFF08\u671F\u671B ${digest}\uFF0C\u5B9E\u9645 ${got}\uFF09`);
-  return { id, name, digest, files };
+  const handle = res.headers.get("x-skill-handle") || void 0;
+  return { id, handle, name, digest, files };
 }
 async function archiveHead(env, id) {
   const url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
@@ -27083,7 +27084,12 @@ async function archiveHead(env, id) {
   if (res.status === 404) return null;
   const digest = res.headers.get("x-skill-digest") ?? "";
   if (res.status < 300 || res.status >= 400 || !digest) throw new Error(`\u67E5\u8BE2 ${id} \u5931\u8D25\uFF1AHTTP ${res.status}`);
-  return { id: res.headers.get("x-skill-id") ?? id, name: res.headers.get("x-skill-name") ?? id.split("/").pop(), digest };
+  return {
+    id: res.headers.get("x-skill-id") ?? id,
+    handle: res.headers.get("x-skill-handle") || void 0,
+    name: res.headers.get("x-skill-name") ?? id.split("/").pop(),
+    digest
+  };
 }
 async function download(url, id) {
   for (let attempt = 1; ; attempt++) {
@@ -27188,11 +27194,20 @@ function skillDirExists(p) {
 function readSource(dir) {
   try {
     const r = JSON.parse(readFileSync2(join2(dir, SOURCE_FILE), "utf8"));
-    return typeof r?.id === "string" && parseId(r.id) ? { id: r.id, digest: String(r.digest ?? "") } : null;
+    if (typeof r?.id !== "string" || !parseId(r.id)) return null;
+    const rec = { id: r.id, digest: String(r.digest ?? "") };
+    if (typeof r.handle === "string" && HANDLE_RE.test(r.handle)) rec.handle = r.handle;
+    return rec;
   } catch {
     return null;
   }
 }
+function writeSource(dir, rec) {
+  writeFileSync(join2(dir, SOURCE_FILE), JSON.stringify(rec, null, 2) + "\n");
+}
+function displayRef(rec, fallback2 = "") {
+  return rec?.handle || rec?.id || fallback2;
+}
 function writeSkill(target, files, source) {
   const staging = join2(dirname(target), `.staging-${target.split("/").pop()}-${process.pid}`);
   rmSync(staging, { recursive: true, force: true });
@@ -27275,10 +27290,10 @@ async function cmdAdd(idOrName, opts) {
     return 1;
   }
   mkdirSync2(opts.dir, { recursive: true });
-  writeSkill(target, archive.files, { id: archive.id, digest: archive.digest });
+  writeSkill(target, archive.files, { id: archive.id, digest: archive.digest, handle: archive.handle });
   const report = reportSkillEvent(env, "install", archive.id, archive.digest, name);
-  if (opts.json) console.log(JSON.stringify({ installed: archive.id, path: target, digest: archive.digest }));
-  else console.log(`\u5DF2\u5B89\u88C5 ${archive.id} \u2192 ${target}`);
+  if (opts.json) console.log(JSON.stringify({ installed: archive.id, handle: archive.handle, path: target, digest: archive.digest }));
+  else console.log(`\u5DF2\u5B89\u88C5 ${displayRef(archive)} \u2192 ${target}`);
   await report;
   return 0;
 }
@@ -27305,7 +27320,9 @@ import { join as join4 } from "node:path";
 var FETCH_ROOT = process.env["NETASEARCH_FETCH_ROOT"] ?? join4("/tmp", "neta-skills");
 async function cmdUse(idOrName, opts) {
   const env = detectEnv();
+  const input = idOrName;
   idOrName = await resolveRef(env, idOrName);
+  let handle = isHandle(input) && parseId(idOrName) ? input.toLowerCase() : void 0;
   const parsed = parseId(idOrName);
   const name = parsed?.name ?? idOrName;
   const mine = !parsed || parsed.spaceId === env.spaceId;
@@ -27322,6 +27339,7 @@ async function cmdUse(idOrName, opts) {
     if (src && (!parsed || src.id === idOrName)) {
       path = installed;
       reportId = src.id;
+      handle = handle ?? src.handle;
     } else if (!src && mine) {
       path = installed;
       reportId = ownId(env, name);
@@ -27365,8 +27383,9 @@ async function cmdUse(idOrName, opts) {
       const p = parseId(a.id);
       path = join4(FETCH_ROOT, p.spaceId, p.name);
       const have = readSource(path);
-      if (!skillDirExists(path) || have?.digest !== a.digest) writeSkill(path, a.files, { id: a.id, digest: a.digest });
+      if (!skillDirExists(path) || have?.digest !== a.digest) writeSkill(path, a.files, { id: a.id, digest: a.digest, handle: a.handle });
       reportId = a.id;
+      handle = a.handle ?? handle;
       where = "fetched";
     } catch (e) {
       console.error(e instanceof ArchiveNotFound ? `${e.message}\u3002` : String(e instanceof Error ? e.message : e));
@@ -27383,10 +27402,10 @@ async function cmdUse(idOrName, opts) {
   const reported = reportId ? await reportSkillEvent(env, "use", reportId, skillDirDigest(path), name, extra) : false;
   const skillMd = readFileSync3(join4(path, "SKILL.md"), "utf8");
   if (opts.json) {
-    console.log(JSON.stringify({ skill: reportId ?? name, path, where, use_id: reportId ? useId : void 0, skill_md: skillMd }));
+    console.log(JSON.stringify({ skill: reportId ?? name, handle, path, where, use_id: reportId ? useId : void 0, skill_md: skillMd }));
   } else {
     const label = { local: "\u672C\u5730", mod: "\u5E73\u53F0 mod", fetched: "\u5DF2\u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55" }[where];
-    console.log(`${reportId ?? name} \u5C31\u7EEA\uFF08${label}${via === "pointer" ? "\uFF0C\u7ECF\u6307\u9488" : ""}\uFF09`);
+    console.log(`${handle ?? reportId ?? name} \u5C31\u7EEA\uFF08${label}${via === "pointer" ? "\uFF0C\u7ECF\u6307\u9488" : ""}\uFF09`);
     console.log(`skill \u76EE\u5F55\uFF1A${path}`);
     console.log(`SKILL.md \u91CC\u7684\u76F8\u5BF9\u8DEF\u5F84\u90FD\u4ECE\u8FD9\u4E2A\u76EE\u5F55\u7B97\u8D77\u3002\u4E0B\u9762\u5C31\u662F SKILL.md \u7684\u5168\u6587\uFF0C\u7167\u7740\u505A\u5373\u53EF\uFF08\u4E0D\u7528\u518D\u8BFB\u4E00\u6B21\u6587\u4EF6\uFF09\u3002`);
     console.log(`
@@ -27469,7 +27488,7 @@ function scanLocal(dir) {
     if (!skillDirExists(path)) continue;
     const src = readSource(path);
     if (src) {
-      out.push({ name: e.name, path, kind: "installed", id: src.id, digest: src.digest });
+      out.push({ name: e.name, path, kind: "installed", id: src.id, handle: src.handle, digest: src.digest });
       continue;
     }
     const ptr = pointerTarget(path);
@@ -27477,12 +27496,21 @@ function scanLocal(dir) {
   }
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
+async function findLocal(env, local, input) {
+  if (!input.includes("/") && !input.startsWith(".")) {
+    const s = local.find((x) => x.name === input);
+    if (s) return [s];
+  }
+  const ref = parseId(input) ? input : await resolveRef(env, input);
+  const lower = input.toLowerCase();
+  return local.filter((x) => x.id !== void 0 && x.id === ref || x.handle !== void 0 && x.handle.toLowerCase() === lower);
+}
 async function statusOf(env, s) {
   if (s.kind !== "installed" || !s.id) return { status: "unknown" };
   try {
     const head = await archiveHead(env, s.id);
     if (!head) return { status: "unavailable" };
-    return { status: head.digest === s.digest ? "latest" : "outdated", latest: head.digest };
+    return { status: head.digest === s.digest ? "latest" : "outdated", latest: head.digest, handle: head.handle };
   } catch (e) {
     return { status: "unknown", error: e instanceof Error ? e.message : String(e) };
   }
@@ -27493,7 +27521,10 @@ async function cmdList(opts) {
   const env = detectEnv();
   const local = scanLocal(opts.dir);
   const rows = await Promise.all(
-    local.map(async (s) => ({ ...s, ...opts.offline ? { status: "unknown" } : await statusOf(env, s) }))
+    local.map(async (s) => {
+      const st = opts.offline ? { status: "unknown", handle: void 0 } : await statusOf(env, s);
+      return { ...s, ...st, handle: s.handle ?? st.handle };
+    })
   );
   if (opts.json) {
     console.log(JSON.stringify({ dir: opts.dir, count: rows.length, skills: rows }));
@@ -27506,7 +27537,7 @@ async function cmdList(opts) {
   console.log(`${opts.dir}/\uFF08${rows.length} \u4E2A\uFF09\uFF1A`);
   for (const r of rows) {
     const st = STATUS_LABEL[r.status] ? `  [${STATUS_LABEL[r.status]}]` : "";
-    const from = r.id ? `  ${r.id}` : "";
+    const from = r.id ? `  ${displayRef(r)}` : "";
     console.log(`  ${r.name.padEnd(28)} ${KIND_LABEL[r.kind]}${st}${from}`);
   }
   const outdated = rows.filter((r) => r.status === "outdated").length;
@@ -27517,7 +27548,6 @@ ${outdated} \u4E2A\u6709\u66F4\u65B0\uFF1Aneta-search skills update`);
 async function cmdUpdate(names, opts) {
   const env = detectEnv();
   const local = scanLocal(opts.dir);
-  const byName = new Map(local.map((s) => [s.name, s]));
   const targets = [];
   const results = [];
   let failed = 0;
@@ -27525,18 +27555,21 @@ async function cmdUpdate(names, opts) {
     targets.push(...local.filter((s) => s.kind === "installed"));
   } else {
     for (const n of names) {
-      const s = byName.get(n);
-      if (!s) {
+      const found = await findLocal(env, local, n);
+      if (found.length === 0) {
         results.push({ name: n, result: "not_found" });
         failed++;
-      } else if (s.kind !== "installed") {
-        results.push({ name: n, result: s.kind === "own" ? "own_skipped" : "pointer_skipped" });
-      } else targets.push(s);
+      }
+      for (const s of found) {
+        if (s.kind !== "installed") results.push({ name: s.name, result: s.kind === "own" ? "own_skipped" : "pointer_skipped" });
+        else if (!targets.includes(s)) targets.push(s);
+      }
     }
   }
   for (const s of targets) {
     const st = await statusOf(env, s);
     if (st.status === "latest") {
+      if (st.handle && st.handle !== s.handle) writeSource(s.path, { id: s.id, digest: s.digest, handle: st.handle });
       results.push({ name: s.name, result: "latest" });
       continue;
     }
@@ -27551,7 +27584,7 @@ async function cmdUpdate(names, opts) {
     }
     try {
       const a = await fetchArchive(env, s.id);
-      writeSkill(s.path, a.files, { id: s.id, digest: a.digest });
+      writeSkill(s.path, a.files, { id: s.id, digest: a.digest, handle: a.handle ?? s.handle });
       await reportSkillEvent(env, "install", s.id, a.digest, s.name);
       results.push({ name: s.name, result: "updated", from: s.digest, to: a.digest });
     } catch (e) {
@@ -27580,17 +27613,19 @@ function short(d) {
   return (d ?? "").replace(/^sha256:/, "").slice(0, 12) || "?";
 }
 async function cmdRemove(names, opts) {
-  const byName = new Map(scanLocal(opts.dir).map((s) => [s.name, s]));
+  const env = detectEnv();
+  const local = scanLocal(opts.dir);
   const results = [];
   for (const n of names) {
-    const s = byName.get(n);
-    if (!s || n.includes("/") || n.startsWith(".")) {
-      results.push({ name: n, result: "not_found" });
-    } else if (s.kind === "own" && !opts.force) {
-      results.push({ name: n, result: "own_refused" });
-    } else {
-      rmSync2(s.path, { recursive: true, force: true });
-      results.push({ name: n, result: "removed" });
+    const found = (await findLocal(env, local, n)).filter((s) => existsSync5(s.path));
+    if (found.length === 0) results.push({ name: n, result: "not_found" });
+    for (const s of found) {
+      if (s.kind === "own" && !opts.force) {
+        results.push({ name: s.name, result: "own_refused" });
+      } else {
+        rmSync2(s.path, { recursive: true, force: true });
+        results.push({ name: s.name, result: "removed" });
+      }
     }
   }
   const failed = results.filter((r) => r.result !== "removed").length;
@@ -27635,10 +27670,10 @@ skills.command("use").description("\u7528 skill\uFF08\u4E0D\u88C5\uFF1A\u6253\u5
 skills.command("list").alias("ls").description("\u5217\u51FA\u672C\u5730\u7684 skill\uFF08\u88C5\u6765\u7684 / \u6307\u9488 / \u81EA\u5DF1\u5199\u7684\uFF09\uFF0C\u88C5\u6765\u7684\u987A\u5E26\u67E5\u6709\u6CA1\u6709\u66F4\u65B0").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--offline", "\u4E0D\u8054\u7F51\u67E5\u66F4\u65B0").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (opts) => {
   await run(cmdList({ dir: opts.dir, offline: !!opts.offline, json: !!opts.json }));
 });
-skills.command("update").description("\u66F4\u65B0\u88C5\u6765\u7684 skill \u5230\u5F53\u524D\u4E0A\u67B6\u7684\u7248\u672C\uFF08\u4E0D\u7ED9\u540D\u5B57 = \u5168\u90E8\uFF1B\u81EA\u5DF1\u5199\u7684\u548C\u6307\u9488\u4E0D\u78B0\uFF09").argument("[names...]", "\u8981\u66F4\u65B0\u7684 skill \u540D\uFF08\u76EE\u5F55\u540D\uFF09").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
+skills.command("update").description("\u66F4\u65B0\u88C5\u6765\u7684 skill \u5230\u5F53\u524D\u4E0A\u67B6\u7684\u7248\u672C\uFF08\u4E0D\u7ED9\u540D\u5B57 = \u5168\u90E8\uFF1B\u81EA\u5DF1\u5199\u7684\u548C\u6307\u9488\u4E0D\u78B0\uFF09").argument("[names...]", "\u8981\u66F4\u65B0\u7684 skill\uFF1A\u76EE\u5F55\u540D\u3001handle\uFF08\u5982 neta-skills/holo-pack-opening\uFF09\u6216\u5B9A\u4F4D\u7B26").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
   await run(cmdUpdate(names, { dir: opts.dir, json: !!opts.json }));
 });
-skills.command("remove").alias("rm").description("\u5220\u9664\u672C\u5730 skill\uFF08\u88C5\u6765\u7684 / \u6307\u9488\uFF1B\u81EA\u5DF1\u5199\u7684\u8981 --force\uFF09").argument("<names...>", "\u8981\u5220\u7684 skill \u540D\uFF08\u76EE\u5F55\u540D\uFF09").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--force", "\u8FDE\u81EA\u5DF1\u5199\u7684\u4E5F\u5220").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
+skills.command("remove").alias("rm").description("\u5220\u9664\u672C\u5730 skill\uFF08\u88C5\u6765\u7684 / \u6307\u9488\uFF1B\u81EA\u5DF1\u5199\u7684\u8981 --force\uFF09").argument("<names...>", "\u8981\u5220\u7684 skill\uFF1A\u76EE\u5F55\u540D\u3001handle \u6216\u5B9A\u4F4D\u7B26").option("--dir <dir>", "\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--force", "\u8FDE\u81EA\u5DF1\u5199\u7684\u4E5F\u5220").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (names, opts) => {
   await run(cmdRemove(names, { dir: opts.dir, force: !!opts.force, json: !!opts.json }));
 });
 skills.command("init").description("\u521B\u5EFA skill \u811A\u624B\u67B6\uFF08SKILL.md + frontmatter \u89C4\u8303\uFF09").argument("[name]", "skill \u540D\uFF08kebab-case\uFF09").option("--here", "\u5728\u5F53\u524D\u76EE\u5F55\u751F\u6210\uFF08\u9ED8\u8BA4\u751F\u6210\u5230 ./<name>/ \u5B50\u76EE\u5F55\uFF09").action(async (name, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/neta-search-cli",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "neta-search CLI — find, try and install skills from the Cohub / Neta skill registry",
   "type": "module",
   "bin": {