@scrappycoco/cli 0.4.1 → 0.4.2

package/README.md

@@ -7,7 +7,7 @@ judgment.
 Run the published package directly with `npx`:
 
 ```sh
-npx --yes @scrappycoco/cli setup
+npx --yes @scrappycoco/cli@latest setup
 ```
 
 `setup` opens OAuth in the browser. New users can create an account in that
@@ -16,12 +16,19 @@ the live catalog, and tells you when to reload or restart your agent. Browser
 authorization is not complete until the terminal confirms that the credential
 was saved and the catalog check succeeded.
 
+Before every ordinary command, the CLI compares the installed Scrappycoco skill
+with the digest in the hash-verified public feed. When the digest changes, it
+automatically refreshes the skill and prints a reload/restart notice to stderr.
+Release-check or installer failures do not block the requested CLI command.
+CLI-only users without an installed skill are not modified. Set
+`SCRAPPYCOCO_DISABLE_SKILL_AUTO_UPDATE=1` to opt out.
+
 When the CLI runs on a remote or headless host whose `127.0.0.1` is not the
 browser's localhost, keep the command running and use the manual callback
 flow:
 
 ```sh
-npx --yes @scrappycoco/cli setup --no-browser --manual-callback
+npx --yes @scrappycoco/cli@latest setup --no-browser --manual-callback
 ```
 
 Open the printed authorization URL, then paste the browser's final callback
@@ -33,14 +40,14 @@ URL.
 Individual commands remain available:
 
 ```sh
-npx --yes @scrappycoco/cli auth login
-npx --yes @scrappycoco/cli catalog list --available --json
-npx --yes @scrappycoco/cli catalog inspect web.extract_content --json
-npx --yes @scrappycoco/cli run web.extract_content --file request.json --json
-npx --yes @scrappycoco/cli discover --file discovery.json --json
-npx --yes @scrappycoco/cli discover --id DISCOVERY_ID --test --input '{"url":"https://example.com"}' --json
-npx --yes @scrappycoco/cli discover --id DISCOVERY_ID --finalize --json
-npx --yes @scrappycoco/cli run --config DISCOVERY_ID --input '{}' --json
+npx --yes @scrappycoco/cli@latest auth login
+npx --yes @scrappycoco/cli@latest catalog list --available --json
+npx --yes @scrappycoco/cli@latest catalog inspect web.extract_content --json
+npx --yes @scrappycoco/cli@latest run web.extract_content --file request.json --json
+npx --yes @scrappycoco/cli@latest discover --file discovery.json --json
+npx --yes @scrappycoco/cli@latest discover --id DISCOVERY_ID --test --input '{"url":"https://example.com"}' --json
+npx --yes @scrappycoco/cli@latest discover --id DISCOVERY_ID --finalize --json
+npx --yes @scrappycoco/cli@latest run --config DISCOVERY_ID --input '{}' --json
 ```
 
 From a repository checkout, use `npm ci`, `npm run build`, and
@@ -70,6 +77,9 @@ and `options`, so one discovery can test both `zyte-http` with
 `{"browser_html":false}` and `zyte-browser` with
 `{"browser_html":true}` against the same input.
 
+The distributed skill includes a Discovery workbook with complete direct-Run,
+comparison, update, finalization, fallback, and audit-handoff examples.
+
 Use `scrappycoco --help` for the complete command reference. See the
 [Scrappycoco API documentation](https://scrappycoco.ai/docs) for the public
 contract.

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import { readFileSync } from "fs";
 import { Command, CommanderError, Option } from "commander";
 
@@ -671,7 +671,7 @@ import { determineAgent } from "@vercel/detect-agent";
 var SKILL_SOURCE = "https://scrappycoco.ai";
 var SKILL_INSTALL_ARGS = [
   "--yes",
-  "skills",
+  "skills@latest",
   "add",
   SKILL_SOURCE,
   "--skill",
@@ -710,7 +710,7 @@ function skillInstallInvocation(agent = "universal", npmExecPath = process.env.n
       args: [
         npmExecPath,
         "dlx",
-        "skills",
+        "skills@latest",
         ...SKILL_INSTALL_ARGS.slice(2),
         "--agent",
         agent
@@ -839,6 +839,185 @@ async function performSetup(options, dependencies = defaultDependencies(options.
   };
 }
 
+// src/skill-update.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { access, chmod as chmod2, mkdir as mkdir2, open as open3, readFile as readFile3, rename as rename2, rm as rm2, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+var SKILL_NAME = "scrappycoco";
+var SKILL_INDEX_URL = `${SKILL_SOURCE}/.well-known/agent-skills/index.json`;
+var SKILL_UPDATE_TIMEOUT_MS = 3e3;
+var SKILL_UPDATE_LOCK_STALE_MS = 5 * 6e4;
+var SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/i;
+function skillReleaseStatePath() {
+  return join2(dirname2(fallbackCredentialPath()), "skill-release.json");
+}
+function skillUpdateLockPath() {
+  return `${skillReleaseStatePath()}.lock`;
+}
+function installedSkillCandidates() {
+  return [
+    join2(homedir2(), ".agents", "skills", SKILL_NAME, "SKILL.md"),
+    join2(homedir2(), ".codex", "skills", SKILL_NAME, "SKILL.md"),
+    join2(homedir2(), ".claude", "skills", SKILL_NAME, "SKILL.md"),
+    join2(homedir2(), ".cursor", "skills", SKILL_NAME, "SKILL.md")
+  ];
+}
+async function isSkillInstalled() {
+  for (const path of installedSkillCandidates()) {
+    try {
+      await access(path);
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+async function loadInstalledDigest() {
+  try {
+    const state = JSON.parse(
+      await readFile3(skillReleaseStatePath(), "utf8")
+    );
+    return typeof state.digest === "string" && SHA256_DIGEST.test(state.digest) ? state.digest : null;
+  } catch {
+    return null;
+  }
+}
+async function writePrivateJson2(path, value) {
+  await mkdir2(dirname2(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.${process.pid}.${randomUUID3()}.tmp`;
+  try {
+    await writeFile3(temporary, JSON.stringify(value), { mode: 384 });
+    if (process.platform !== "win32") await chmod2(temporary, 384);
+    await rename2(temporary, path);
+    if (process.platform !== "win32") await chmod2(path, 384);
+  } finally {
+    await rm2(temporary, { force: true });
+  }
+}
+async function saveInstalledDigest(digest) {
+  await writePrivateJson2(skillReleaseStatePath(), {
+    digest,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function fetchPublishedSkillDigest(fetcher = fetch) {
+  const response = await fetcher(SKILL_INDEX_URL, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(SKILL_UPDATE_TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    throw new Error(`Skill release check returned HTTP ${response.status}.`);
+  }
+  const index = await response.json();
+  const entry = index.skills?.find((skill) => skill.name === SKILL_NAME);
+  if (!entry || typeof entry.digest !== "string" || !SHA256_DIGEST.test(entry.digest)) {
+    throw new Error("Skill release index did not contain a valid Scrappycoco digest.");
+  }
+  return entry.digest.toLowerCase();
+}
+function defaultDependencies2() {
+  return {
+    isInstalled: isSkillInstalled,
+    loadInstalledDigest,
+    fetchPublishedDigest: fetchPublishedSkillDigest,
+    install: installSkill,
+    saveInstalledDigest
+  };
+}
+async function checkAndInstallSkillUpdate(dependencies = defaultDependencies2()) {
+  if (!await dependencies.isInstalled()) return { status: "not_installed" };
+  let publishedDigest;
+  try {
+    publishedDigest = await dependencies.fetchPublishedDigest();
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (await dependencies.loadInstalledDigest() === publishedDigest) {
+    return { status: "current" };
+  }
+  try {
+    await dependencies.install();
+  } catch (error) {
+    return {
+      status: "failed",
+      error: error instanceof Error ? error : new Error(String(error))
+    };
+  }
+  let stateSaved = true;
+  try {
+    await dependencies.saveInstalledDigest(publishedDigest);
+  } catch {
+    stateSaved = false;
+  }
+  return { status: "updated", digest: publishedDigest, state_saved: stateSaved };
+}
+async function withSkillUpdateLock(operation) {
+  const path = skillUpdateLockPath();
+  await mkdir2(dirname2(path), { recursive: true, mode: 448 });
+  let handle;
+  try {
+    handle = await open3(path, "wx", 384);
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      return { status: "unavailable" };
+    }
+    try {
+      const lock = await stat2(path);
+      if (Date.now() - lock.mtimeMs <= SKILL_UPDATE_LOCK_STALE_MS) {
+        return { status: "busy" };
+      }
+      await rm2(path, { force: true });
+      handle = await open3(path, "wx", 384);
+    } catch {
+      return { status: "busy" };
+    }
+  }
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid, created_at: Date.now() }));
+    return await operation();
+  } finally {
+    await handle.close();
+    await rm2(path, { force: true });
+  }
+}
+function autoUpdateDisabled() {
+  return ["1", "true", "yes"].includes(
+    (process.env.SCRAPPYCOCO_DISABLE_SKILL_AUTO_UPDATE || "").toLowerCase()
+  );
+}
+async function autoUpdateInstalledSkill() {
+  if (autoUpdateDisabled()) return { status: "disabled" };
+  let result;
+  try {
+    result = await withSkillUpdateLock(() => checkAndInstallSkillUpdate());
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (result.status === "updated") {
+    process.stderr.write(
+      "Updated the Scrappycoco skill. Reload or restart the agent to use the new instructions.\n"
+    );
+    if (!result.state_saved) {
+      process.stderr.write(
+        "Warning: the skill update succeeded, but its release state could not be saved.\n"
+      );
+    }
+  } else if (result.status === "failed") {
+    process.stderr.write(
+      `Warning: could not update the Scrappycoco skill; continuing with the installed copy: ${result.error.message}
+`
+    );
+  }
+  return result;
+}
+async function rememberInstalledSkillRelease() {
+  try {
+    await saveInstalledDigest(await fetchPublishedSkillDigest());
+  } catch {
+  }
+}
+
 // src/index.ts
 var packageMetadata = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8")
@@ -860,8 +1039,13 @@ program.command("setup").description("Authenticate, install the Scrappycoco skil
     noBrowser: options.browser === false,
     manualCallback: options.manualCallback
   });
+  await rememberInstalledSkillRelease();
   await emit(result, globals(command).json || false);
 });
+program.hook("preAction", async (_thisCommand, actionCommand) => {
+  if (actionCommand.name() === "setup") return;
+  await autoUpdateInstalledSkill();
+});
 function splitScraperId(value) {
   const separator = value.indexOf(".");
   if (separator <= 0 || separator === value.length - 1) {
@@ -985,7 +1169,7 @@ function executionCommand(name) {
     const response = await client(command).postJob(
       name === "run" ? "/scrapers/jobs" : "/scrapers/compare/jobs",
       payload,
-      options.idempotencyKey || randomUUID3()
+      options.idempotencyKey || randomUUID4()
     );
     await emitExecution(response, options, command);
   });
@@ -1000,7 +1184,7 @@ program.command("run [capability-id]").description("Run a capability directly; d
     const response2 = await client(command).postJob(
       `/runs/${encodeURIComponent(options.retryFailed)}/retry-failed`,
       {},
-      options.idempotencyKey || randomUUID3()
+      options.idempotencyKey || randomUUID4()
     );
     await emitExecution(response2, options, command);
     return;
@@ -1018,7 +1202,7 @@ program.command("run [capability-id]").description("Run a capability directly; d
         input,
         limit: Number(options.limit ?? fromFile.limit ?? 25)
       },
-      options.idempotencyKey || randomUUID3()
+      options.idempotencyKey || randomUUID4()
     );
     await emitExecution(response2, options, command);
     return;
@@ -1031,7 +1215,7 @@ program.command("run [capability-id]").description("Run a capability directly; d
   const response = await client(command).postJob(
     "/scrapers/jobs",
     payload,
-    options.idempotencyKey || randomUUID3()
+    options.idempotencyKey || randomUUID4()
   );
   await emitExecution(response, options, command);
 });
@@ -1086,7 +1270,7 @@ discoveries.command("run <discovery-id>").option("-f, --file <path>", "request J
   const response = await client(command).postJob(
     `/discoveries/${encodeURIComponent(discoveryId)}/jobs`,
     payload,
-    options.idempotencyKey || randomUUID3()
+    options.idempotencyKey || randomUUID4()
   );
   await emitExecution(response, options, command);
 });
@@ -1134,7 +1318,7 @@ program.command("discover").description("Save, sample-test, or finalize an agent
   const response = await client(command).postJob(
     `/discoveries/${encodeURIComponent(options.id)}/jobs`,
     { input, limit: 25 },
-    options.idempotencyKey || randomUUID3()
+    options.idempotencyKey || randomUUID4()
   );
   await emit(response, globals(command).json || false);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrappycoco/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "CLI for Scrappycoco scraper discovery and execution",
   "type": "module",
   "bin": {