@neta-art/neta-search-cli 0.2.20 → 0.2.23

package/neta-search.mjs

@@ -27084,15 +27084,18 @@ var TIMEOUT_MS = 6e4;
 var MAX_TRIES = 4;
 var ArchiveNotFound = class extends Error {
 };
-async function fetchArchive(env, id) {
-  const url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+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)}`;
   const res = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(TIMEOUT_MS) });
-  if (res.status === 404) throw new ArchiveNotFound(`${id} does not exist or has no released version`);
+  if (res.status === 404) throw new ArchiveNotFound(pin ? `version ${pin} of ${id} is not available` : `${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}`);
   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)`);
+  if (pin && digest !== pin) throw new Error(`failed to download ${id}: asked for version ${pin}, the server offered ${digest}`);
   const body = await download(new URL(location, url).toString(), id);
   const files = untarGz(body);
   const got = digestOf(new Map(files.map((f) => [f.path, f.data])));
@@ -27116,12 +27119,19 @@ async function archiveHead(env, id) {
 async function download(url, id) {
   for (let attempt = 1; ; attempt++) {
     const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (res.status === 202 && attempt < MAX_TRIES) {
-      const body = await res.json().catch(() => ({}));
-      await new Promise((r) => setTimeout(r, Math.min(Math.max(body.retryAfterMs ?? 2e3, 250), 5e3)));
+    if ((res.status === 202 || res.status === 503) && attempt < MAX_TRIES) {
+      let wait = 2e3;
+      if (res.status === 202) {
+        const body = await res.json().catch(() => ({}));
+        wait = body.retryAfterMs ?? wait;
+      } else {
+        const sec = Number(res.headers.get("retry-after"));
+        if (Number.isFinite(sec) && sec > 0) wait = sec * 1e3;
+      }
+      await new Promise((r) => setTimeout(r, Math.min(Math.max(wait, 250), 5e3)));
       continue;
     }
-    if (!res.ok) throw new Error(`failed to download ${id}: registry returned HTTP ${res.status}`);
+    if (!res.ok) throw new Error(`failed to download ${id}: HTTP ${res.status}`);
     return Buffer.from(await res.arrayBuffer());
   }
 }
@@ -27247,7 +27257,12 @@ function writeSkill(target, files, source) {
   const trash = join2(dirname(target), `.trash-${target.split("/").pop()}-${process.pid}`);
   const hadOld = existsSync(target);
   if (hadOld) renameSync(target, trash);
-  renameSync(staging, target);
+  try {
+    renameSync(staging, target);
+  } catch (e) {
+    rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
   if (hadOld) rmSync(trash, { recursive: true, force: true });
 }
 var POINTER_RE = /^\s*neta-skill-id:\s*["']?(cohub:[^"'\s]+)["']?\s*$/m;
@@ -27392,6 +27407,22 @@ async function cmdUse(idOrName, opts) {
   let notice = null;
   let found = null;
   let fetchId = parsed && !mine ? idOrName : null;
+  const pin = opts.digest?.trim().toLowerCase();
+  if (opts.digest !== void 0) {
+    if (!pin || !DIGEST_RE.test(pin)) {
+      console.error(`--digest must look like sha256:<64 hex characters>, got "${opts.digest}".`);
+      return 1;
+    }
+    if (!parsed) {
+      console.error(
+        resolved.unreachable ? `Cannot reach the server (${env.apiBase}), so handle "${input}" could not be resolved. Try again later.` : `--digest needs a handle or an id (cohub:<space>/<name>); "${input}" is neither.`
+      );
+      return 1;
+    }
+    const r = await pinnedFromCacheOrDownload(env, idOrName, pin);
+    if (!r) return 1;
+    return emit(env, r.found, r.handle ?? handle, name, { via, entry, viaPointer: false, notice: null, json: opts.json, pinned: true });
+  }
   const installed = join4(SKILLS_DIR, name);
   const draft = join4(DRAFTS_DIR, name);
   if (skillDirExists(installed)) {
@@ -27446,16 +27477,21 @@ async function cmdUse(idOrName, opts) {
     console.error(`Skill "${idOrName}" is not available locally. Run neta-search skills find "${name}" to get its id.`);
     return 1;
   }
+  return emit(env, found, handle, name, { via, entry, viaPointer, notice, json: opts.json, pinned: false });
+}
+async function emit(env, found, handle, name, o) {
+  const { via, entry, viaPointer, notice } = o;
   const useId = randomUUID();
   const extra = { use_id: useId, where: found.where };
   if (via) extra["via"] = via;
   if (entry) extra["entry"] = entry;
+  if (o.pinned) extra["pinned"] = "true";
   const digest = found.where === "mod" ? "" : found.digest ?? skillDirDigest(found.path);
   const reported = found.reportId ? await reportSkillEvent(env, "use", found.reportId, digest, name, extra) : false;
   const skillMd = readFileSync4(join4(found.path, "SKILL.md"), "utf8");
   const dir = resolve(found.path);
   const shown = handle ?? found.reportId ?? name;
-  if (opts.json) {
+  if (o.json) {
     console.log(
       JSON.stringify({
         skill: found.reportId ?? name,
@@ -27513,6 +27549,18 @@ function findInMounts(spaceId, name) {
   }
   return hits[0] ?? null;
 }
+function pinnedDir(spaceId, name, digest) {
+  return join4(FETCH_ROOT, spaceId, `${name}@${digest.slice("sha256:".length, "sha256:".length + 12)}`);
+}
+async function pinnedFromCacheOrDownload(env, fetchId, pin) {
+  const p = parseId(fetchId);
+  const dir = pinnedDir(p.spaceId, p.name, pin);
+  const have = skillDirExists(dir) ? readSource(dir) : null;
+  if (have && have.id === fetchId && have.digest === pin) {
+    return { found: { path: dir, where: "cache", reportId: have.id, digest: have.digest }, handle: have.handle };
+  }
+  return download2(env, fetchId, pin, dir);
+}
 async function fromCacheOrDownload(env, fetchId) {
   const p = parseId(fetchId);
   const cacheDir = join4(FETCH_ROOT, p.spaceId, p.name);
@@ -27536,16 +27584,34 @@ async function fromCacheOrDownload(env, fetchId) {
     if (head.handle && head.handle !== have.handle) writeSource(cacheDir, { ...have, handle: head.handle });
     return { found: { path: cacheDir, where: "cache", reportId: have.id, digest: have.digest }, handle: head.handle ?? have.handle };
   }
+  return download2(env, fetchId);
+}
+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) {
   try {
-    const a = await fetchArchive(env, fetchId);
+    const a = await fetchArchive(env, fetchId, pin);
     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);
-    const path = join4(FETCH_ROOT, q.spaceId, q.name);
-    writeSkill(path, a.files, { id: a.id, digest: a.digest, handle: a.handle });
+    const path = target ?? join4(FETCH_ROOT, q.spaceId, q.name);
+    const record = { id: a.id, digest: a.digest, handle: a.handle };
+    if (target) {
+      if (sameVersion(path, record)) return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
+      try {
+        writeSkill(path, a.files, record);
+      } catch (e) {
+        if (!sameVersion(path, record)) throw e;
+      }
+      return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
+    }
+    writeSkill(path, a.files, record);
     return { found: { path, where: "fetched", reportId: a.id, digest: a.digest }, handle: a.handle };
   } catch (e) {
     console.error(e instanceof ArchiveNotFound ? `${e.message}.` : String(e instanceof Error ? e.message : e));
@@ -27778,7 +27844,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 / picker / find)").option("--entry <id>", "entry id (picker / menu entry), recorded in usage stats").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()).action(async (idOrName, opts) => {
   await run(cmdUse(idOrName, opts));
 });
 skills.command("list").alias("ls").description("list local skills (installed / pointer / your own) and check installed ones for updates").option("--dir <dir>", "skills directory", ".agents/skills").option("--offline", "do not check for updates online").option("--json", "compact JSON output (for agents)").action(async (opts) => {

package/package.json

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