@neta-art/neta-search-cli 0.2.36 → 0.2.38

package/README.md

@@ -17,7 +17,7 @@ npx -y @neta-art/neta-search-cli@latest skills submit <name>             # submi
 
 `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` 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`, a handle or an id), `use` fetches the full skill it points to; with `metadata.neta-skill-version: verified` it fetches the version that passed Neta's review. `use <id> --verified` does the same directly: it fails if there is no reviewed version and never falls back to the latest.
 
 Every result has a trust level: `platform` (published by the Neta team), `verified` (made or reviewed by the Neta team) or `community` (shared by a Cohub user, not reviewed). `find --json` items carry it as `trust`, plus `basic: true` for built-in Cohub abilities and `author` for community skills. `use` and `add` say so when a skill is a community one; read those before relying on them.
 

package/neta-search.mjs

@@ -28305,13 +28305,17 @@ function parseTrust(v) {
 var ArchiveNotFound = class extends Error {
 };
 var DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
-async function fetchArchive(env, id, pin) {
-  let url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
-  if (pin) url += `&digest=${encodeURIComponent(pin)}`;
+async function fetchArchive(env, id, pin, verified = false) {
+  const url = archiveURL(env, id, pin, verified);
   const res = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(TIMEOUT_MS) });
-  if (res.status === 404) throw new ArchiveNotFound(pin ? `version ${pin} of ${id} is not available` : `${id} does not exist or has no released version`);
+  if (res.status === 404) {
+    throw new ArchiveNotFound(
+      pin ? `version ${pin} of ${id} is not available` : verified ? `${id} has no version that passed Neta's review (or does not exist)` : `${id} does not exist or has no released version`
+    );
+  }
   const location = res.headers.get("location");
   if (res.status < 300 || res.status >= 400 || !location) throw new Error(`failed to download ${id}: HTTP ${res.status}`);
+  if (verified) checkVerified(res, id);
   const digest = res.headers.get("x-skill-digest") ?? "";
   const name = res.headers.get("x-skill-name") ?? id.split("/").pop();
   if (!digest) throw new Error(`failed to download ${id}: the server did not return a version (x-skill-digest)`);
@@ -28323,12 +28327,13 @@ async function fetchArchive(env, id, pin) {
   const handle = res.headers.get("x-skill-handle") || void 0;
   return { id, handle, name, digest, trust: parseTrust(res.headers.get("x-skill-trust")), files };
 }
-async function archiveHead(env, id) {
-  const url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+async function archiveHead(env, id, verified = false) {
+  const url = archiveURL(env, id, void 0, verified);
   const res = await fetch(url, { method: "HEAD", redirect: "manual", signal: AbortSignal.timeout(1e4) });
   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(`failed to look up ${id}: HTTP ${res.status}`);
+  if (verified) checkVerified(res, id);
   return {
     id: res.headers.get("x-skill-id") ?? id,
     handle: res.headers.get("x-skill-handle") || void 0,
@@ -28337,6 +28342,17 @@ async function archiveHead(env, id) {
     trust: parseTrust(res.headers.get("x-skill-trust"))
   };
 }
+function archiveURL(env, id, pin, verified = false) {
+  let url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+  if (pin) url += `&digest=${encodeURIComponent(pin)}`;
+  if (verified) url += "&version=verified";
+  return url;
+}
+function checkVerified(res, id) {
+  if (res.headers.get("x-skill-version") !== "verified") {
+    throw new Error(`failed to get the reviewed version of ${id}: the server did not confirm it (x-skill-version); not using an unconfirmed version`);
+  }
+}
 async function download(url, id) {
   for (let attempt = 1; ; attempt++) {
     const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
@@ -28519,23 +28535,43 @@ function writeSkill(target, files, source) {
   }
   if (hadOld) rmSync(trash, { recursive: true, force: true });
 }
-var POINTER_RE = /^\s*neta-skill-id:\s*["']?(cohub:[^"'\s]+)["']?\s*$/m;
+var POINTER_KEY_RE = /^\s*neta-skill-id:(.*)$/m;
+var POINTER_VERSION_KEY_RE = /^\s*neta-skill-version:(.*)$/m;
+function yamlScalar(raw) {
+  let v = raw.trim();
+  if ((v.startsWith('"') || v.startsWith("'")) && v.indexOf(v[0], 1) > 0) return v.slice(1, v.indexOf(v[0], 1));
+  const hash = v.search(/\s#/);
+  if (hash >= 0) v = v.slice(0, hash);
+  if (v.startsWith("#")) v = "";
+  return v.trim();
+}
 function frontmatterOf(raw) {
   if (!raw.startsWith("---\n")) return "";
   const end = raw.indexOf("\n---", 4);
   return end < 0 ? "" : raw.slice(4, end);
 }
+function pointerOf(raw) {
+  const fm = frontmatterOf(raw);
+  const m = POINTER_KEY_RE.exec(fm);
+  const target = m ? yamlScalar(m[1]) : "";
+  if (!target) return null;
+  const v = POINTER_VERSION_KEY_RE.exec(fm);
+  const version = v ? yamlScalar(v[1]).toLowerCase() : "";
+  return { target, version: version || "latest" };
+}
 function pointerTargetOf(raw) {
-  const m = POINTER_RE.exec(frontmatterOf(raw));
-  return m ? m[1] : null;
+  return pointerOf(raw)?.target ?? null;
 }
-function pointerTarget(dir) {
+function pointerAt(dir) {
   try {
-    return pointerTargetOf(readFileSync3(join2(dir, "SKILL.md"), "utf8"));
+    return pointerOf(readFileSync3(join2(dir, "SKILL.md"), "utf8"));
   } catch {
     return null;
   }
 }
+function pointerTarget(dir) {
+  return pointerAt(dir)?.target ?? null;
+}
 function shareNotice(id, draft) {
   const name = id.split("/").pop();
   if (draft) {
@@ -28572,6 +28608,21 @@ async function cmdUse(idOrName, opts) {
   let notice = null;
   let found = null;
   let fetchId = parsed && !mine ? idOrName : null;
+  if (opts.verified && opts.digest !== void 0) {
+    console.error("Give either --digest or --verified, not both.");
+    return 1;
+  }
+  if (opts.verified) {
+    if (!parsed) {
+      console.error(
+        resolved.unreachable ? `Cannot reach the server (${env.apiBase}), so handle "${input}" could not be resolved. Try again later.` : `--verified needs a handle or an id (cohub:<space>/<name>); "${input}" is neither.`
+      );
+      return 1;
+    }
+    const r = await fromCacheOrDownload(env, idOrName, true);
+    if (!r) return 1;
+    return emit(env, r.found, r.handle ?? handle, name, { via, entry, viaPointer: false, notice: null, json: opts.json, pinned: false });
+  }
   const pin = opts.digest?.trim().toLowerCase();
   if (opts.digest !== void 0) {
     if (!pin || !DIGEST_RE.test(pin)) {
@@ -28609,19 +28660,37 @@ async function cmdUse(idOrName, opts) {
     if (r === "ambiguous") return 1;
     if (r) found = r;
   }
+  let wantVerified = false;
   if (found) {
-    const target = pointerTarget(found.path);
-    if (target !== null) {
+    const ptr = pointerAt(found.path);
+    if (ptr !== null) {
+      const at = join3(found.path, "SKILL.md");
+      if (ptr.version !== "verified" && ptr.version !== "latest") {
+        console.error(`${at} is a pointer, but its neta-skill-version is not verified or latest: ${ptr.version}`);
+        return 1;
+      }
+      let target = ptr.target;
+      if (isHandle(target)) {
+        const t = await resolveRefDetail(env, target);
+        if (!parseId(t.ref)) {
+          console.error(
+            t.unreachable ? `${at} is a pointer to ${target}, but the server (${env.apiBase}) cannot be reached to resolve it. Try again later.` : `${at} is a pointer to ${target}, but no skill has that handle.`
+          );
+          return 1;
+        }
+        target = t.ref;
+      }
       if (!parseId(target)) {
-        console.error(`${join3(found.path, "SKILL.md")} is a pointer, but its neta-skill-id is not a valid id: ${target}`);
+        console.error(`${at} is a pointer, but its neta-skill-id is not a valid handle or id: ${ptr.target}`);
         return 1;
       }
       viaPointer = true;
+      wantVerified = ptr.version === "verified";
       fetchId = target;
       found = null;
       notice = null;
       const p = parseId(target);
-      const r = findInMounts(p.spaceId, p.name);
+      const r = wantVerified ? null : findInMounts(p.spaceId, p.name);
       if (r && r !== "ambiguous" && pointerTarget(r.path) === null) {
         found = r;
         fetchId = null;
@@ -28629,7 +28698,7 @@ async function cmdUse(idOrName, opts) {
     }
   }
   if (!found && fetchId) {
-    const r = await fromCacheOrDownload(env, fetchId);
+    const r = await fromCacheOrDownload(env, fetchId, wantVerified);
     if (!r) return 1;
     found = r.found;
     handle = r.handle ?? handle;
@@ -28735,7 +28804,8 @@ async function pinnedFromCacheOrDownload(env, fetchId, pin) {
   }
   return download2(env, fetchId, pin, dir);
 }
-async function fromCacheOrDownload(env, fetchId) {
+async function fromCacheOrDownload(env, fetchId, verified = false) {
+  if (verified) return verifiedFromCacheOrDownload(env, fetchId);
   const p = parseId(fetchId);
   const cacheDir = join3(FETCH_ROOT, p.spaceId, p.name);
   const have = skillDirExists(cacheDir) ? readSource(cacheDir) : null;
@@ -28762,20 +28832,42 @@ async function fromCacheOrDownload(env, fetchId) {
   }
   return download2(env, fetchId);
 }
+var NO_REVIEWED = "Tell the user this skill is temporarily unavailable; do not substitute another skill or another version of it.";
+async function verifiedFromCacheOrDownload(env, fetchId) {
+  const p = parseId(fetchId);
+  let head;
+  try {
+    head = await archiveHead(env, fetchId, true);
+  } catch (e) {
+    console.error(`${String(e instanceof Error ? e.message : e)} (needs the reviewed version, so the local cache is not used). ${NO_REVIEWED}`);
+    return null;
+  }
+  if (head === null) {
+    console.error(`${fetchId} has no version that passed Neta's review (or does not exist). ${NO_REVIEWED}`);
+    return null;
+  }
+  const dir = pinnedDir(p.spaceId, p.name, head.digest);
+  const have = skillDirExists(dir) ? readSource(dir) : null;
+  if (have && have.id === fetchId && have.digest === head.digest) {
+    return { found: { path: dir, where: "cache", reportId: have.id, digest: have.digest, trust: head.trust ?? have.trust }, handle: head.handle ?? have.handle };
+  }
+  return download2(env, fetchId, void 0, void 0, true);
+}
 function sameVersion(dir, want) {
   if (!skillDirExists(dir)) return false;
   const have = readSource(dir);
   return !!have && have.id === want.id && have.digest === want.digest;
 }
-async function download2(env, fetchId, pin, target) {
+async function download2(env, fetchId, pin, target, verified = false) {
   try {
-    const a = await fetchArchive(env, fetchId, pin);
+    const a = await fetchArchive(env, fetchId, pin, verified);
     const skillMd = a.files.find((f) => f.path === "SKILL.md");
     if (skillMd && pointerTargetOf(skillMd.data.toString("utf8")) !== null) {
       console.error(`${fetchId} downloaded as another pointer; stopping here (pointers are followed only one level, to avoid loops).`);
       return null;
     }
     const q = parseId(a.id);
+    if (verified && !target) target = pinnedDir(q.spaceId, q.name, a.digest);
     const path = target ?? join3(FETCH_ROOT, q.spaceId, q.name);
     const record = { id: a.id, digest: a.digest, handle: a.handle, trust: a.trust };
     if (target) {
@@ -29174,7 +29266,7 @@ function scanLocal(dir) {
       continue;
     }
     const ptr = pointerTarget(path);
-    out.push(ptr ? { name: e.name, path, kind: "pointer", id: ptr } : { name: e.name, path, kind: "own" });
+    out.push(ptr ? { name: e.name, path, kind: "pointer", id: ptr, handle: isHandle(ptr) ? ptr : void 0 } : { name: e.name, path, kind: "own" });
   }
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -29286,7 +29378,7 @@ async function cmdUpdate(names, opts) {
     latest: (r) => `${r.name} is up to date`,
     unavailable: (r) => `${r.name} is no longer available from its source; keeping the local copy`,
     own_skipped: (r) => `${r.name} is your own skill; nothing to update`,
-    pointer_skipped: (r) => `${r.name} is a pointer; use always fetches the latest, nothing to update`,
+    pointer_skipped: (r) => `${r.name} is a pointer; use fetches the version it asks for, nothing to update`,
     not_found: (r) => `${opts.dir}/${r.name} does not exist`,
     error: (r) => `Failed to update ${r.name}: ${r.from ?? ""}`
   };
@@ -29333,7 +29425,7 @@ skills.command("find").description("search the ecosystem for skills").argument("
 skills.command("add").description("install a skill: an id or handle from find downloads its current release; a name from your drafts moves it into .agents/skills/").argument("<id-or-name>", "skill id or handle from find (e.g. neta-skills/holo-pack-opening), or the name of one of your drafts").option("--dir <dir>", "install directory", ".agents/skills").option("--json", "compact JSON output (for agents)").action(async (idOrName, opts) => {
   await run(cmdAdd(idOrName, opts));
 });
-skills.command("use").description("use a skill without installing it: prints the full SKILL.md and the skill directory (local copy, mounted mod, cache, or download)").argument("<id-or-name>", "skill id, handle (e.g. neta-skills/holo-pack-opening), or local skill name").option("--json", "compact JSON output (for agents)").option("--via <channel>", "where this use came from, recorded in usage stats (site / board-menu / skill-picker / find)").option("--entry <id>", "entry id (picker / menu entry), recorded in usage stats").addOption(new Option("--digest <sha256>", "use exactly this version (sha256:<hex>); needs a handle or id").hideHelp()).action(async (idOrName, opts) => {
+skills.command("use").description("use a skill without installing it: prints the full SKILL.md and the skill directory (local copy, mounted mod, cache, or download)").argument("<id-or-name>", "skill id, handle (e.g. neta-skills/holo-pack-opening), or local skill name").option("--json", "compact JSON output (for agents)").option("--via <channel>", "where this use came from, recorded in usage stats (site / board-menu / skill-picker / find)").option("--entry <id>", "entry id (picker / menu entry), recorded in usage stats").addOption(new Option("--digest <sha256>", "use exactly this version (sha256:<hex>); needs a handle or id").hideHelp()).option("--verified", "use the version that passed Neta's review; fails if there is none (never falls back to the latest); needs a handle or id").action(async (idOrName, opts) => {
   await run(cmdUse(idOrName, opts));
 });
 skills.command("submit").description("publish the current version of one of your skills (.agents/skills/<name>/ in this space) on the public skills site and wait for the result; only the space owner can publish. --withdraw takes it down").argument("<name>", "skill directory name under .agents/skills/").option("--withdraw", "take a published skill down (deleting the directory does not)").option("--wait <seconds>", "how long to wait for the server's result", "60").option("--json", "compact JSON output (for agents)").action(async (name, opts) => {

package/package.json

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