@scrappycoco/cli 0.5.0 → 0.7.0

package/README.md

@@ -17,12 +17,10 @@ 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.
+Ordinary commands never mutate installed agent instructions. Setup installs
+the matching skill release. Run `scrappycoco skill status` to inspect the
+active target and `scrappycoco skill update` to explicitly install a newer
+hash-verified release, then reload or restart the agent.
 
 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
@@ -42,6 +40,8 @@ Individual commands remain available:
 
 ```sh
 npx --yes @scrappycoco/cli@latest auth login
+npx --yes @scrappycoco/cli@latest skill status
+npx --yes @scrappycoco/cli@latest skill update
 npx --yes @scrappycoco/cli@latest doctor --json
 npx --yes @scrappycoco/cli@latest catalog list --available --json
 npx --yes @scrappycoco/cli@latest catalog inspect web.extract_content --json
@@ -74,7 +74,8 @@ compact execution summary remains on stdout.
 
 For a long run, add `--detach` to return a job ID immediately, then finish with
 `scrappycoco jobs wait <job-id> --output results.json`. Use
-`scrappycoco jobs get <job-id>` for a single status check. Set
+`scrappycoco jobs get <job-id>` for a single status check or
+`scrappycoco jobs cancel <job-id>` to stop it. Set
 `SCRAPPYCOCO_JOB_TIMEOUT_MS` to change the default 20-minute foreground wait.
 Run `scrappycoco doctor --json` only when authentication, connectivity, or
 installation is unclear.

package/dist/index.js

@@ -576,6 +576,13 @@ var ApiClient = class {
           job
         );
       }
+      if (job.status === "cancelled") {
+        throw new CliError(
+          `Job ${job.job_id} was cancelled.`,
+          EXIT.cancelled,
+          job
+        );
+      }
       const remainingBeforeDelay = deadline - Date.now();
       if (remainingBeforeDelay <= 0) throw jobTimeoutError(job, timeoutMs);
       await new Promise((resolve) => setTimeout(resolve, Math.min(delayMs, remainingBeforeDelay)));
@@ -869,30 +876,66 @@ function installedSkillCandidates() {
     join2(homedir2(), ".cursor", "skills", SKILL_NAME, "SKILL.md")
   ];
 }
-async function isSkillInstalled() {
-  for (const path of installedSkillCandidates()) {
-    try {
-      await access(path);
-      return true;
-    } catch {
-    }
+function configuredTargetPath(agent) {
+  const directory = agent === "codex" ? ".codex" : agent === "claude-code" ? ".claude" : agent === "cursor" ? ".cursor" : ".agents";
+  return join2(homedir2(), directory, "skills", SKILL_NAME, "SKILL.md");
+}
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
   }
-  return false;
 }
-async function loadInstalledDigest() {
+async function activeSkillTarget() {
+  const configured = configuredTargetPath(await detectSkillInstallerAgent());
+  if (await pathExists(configured)) return configured;
+  const shared = configuredTargetPath("universal");
+  if (await pathExists(shared)) return shared;
+  return configured;
+}
+async function isSkillInstalled() {
+  return pathExists(await activeSkillTarget());
+}
+async function loadSkillReleaseState() {
   try {
     const state = JSON.parse(
       await readFile3(skillReleaseStatePath(), "utf8")
     );
-    return typeof state.digest === "string" && SHA256_DIGEST.test(state.digest) ? state.digest : null;
+    return {
+      targets: Object.fromEntries(
+        Object.entries(state.targets || {}).filter(
+          ([path, value]) => Boolean(path) && typeof value?.digest === "string" && SHA256_DIGEST.test(value.digest)
+        )
+      )
+    };
   } catch {
-    return null;
+    return { targets: {} };
   }
 }
+async function loadInstalledDigest() {
+  const target = await activeSkillTarget();
+  const entry = (await loadSkillReleaseState()).targets[target];
+  return entry?.digest || null;
+}
 async function installedSkillDiagnostics() {
+  const target = await activeSkillTarget();
+  const state = await loadSkillReleaseState();
+  const installedTargets = (await Promise.all(
+    installedSkillCandidates().map(async (path) => ({
+      path,
+      installed: await pathExists(path)
+    }))
+  )).filter((item) => item.installed);
   return {
-    installed: await isSkillInstalled(),
-    digest: await loadInstalledDigest()
+    installed: installedTargets.some((item) => item.path === target),
+    digest: state.targets[target]?.digest || null,
+    target,
+    targets: installedTargets.map(({ path }) => ({
+      path,
+      digest: state.targets[path]?.digest || null
+    }))
   };
 }
 async function writePrivateJson2(path, value) {
@@ -908,10 +951,23 @@ async function writePrivateJson2(path, value) {
   }
 }
 async function saveInstalledDigest(digest) {
-  await writePrivateJson2(skillReleaseStatePath(), {
-    digest,
-    updated_at: (/* @__PURE__ */ new Date()).toISOString()
-  });
+  const target = await activeSkillTarget();
+  const state = await loadSkillReleaseState();
+  await writePrivateJson2(
+    skillReleaseStatePath(),
+    recordTargetDigest(state, target, digest)
+  );
+}
+function recordTargetDigest(state, target, digest, updatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  return {
+    targets: {
+      ...state.targets,
+      [target]: {
+        digest,
+        updated_at: updatedAt
+      }
+    }
+  };
 }
 async function fetchPublishedSkillDigest(fetcher = fetch) {
   const response = await fetcher(SKILL_INDEX_URL, {
@@ -922,7 +978,7 @@ async function fetchPublishedSkillDigest(fetcher = fetch) {
     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);
+  const entry = index.skills?.find((skill2) => skill2.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.");
   }
@@ -993,13 +1049,7 @@ async function withSkillUpdateLock(operation) {
     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" };
+async function updateInstalledSkill() {
   let result;
   try {
     result = await withSkillUpdateLock(() => checkAndInstallSkillUpdate());
@@ -1060,10 +1110,6 @@ program.command("setup").description("Authenticate, install the Scrappycoco skil
   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) {
@@ -1092,80 +1138,7 @@ async function emitExecution(response, options, command) {
   const jsonMode = globals(command).json || false;
   if (options.output) {
     await emit(response, jsonMode, options.output, formatRecords(records, options.format));
-    const summary = { ...response };
-    delete summary.records;
-    delete summary.items;
-    delete summary.normalized_schema;
-    summary.truncated_count = records.filter((record) => {
-      const metadata = record.metadata;
-      return metadata && typeof metadata === "object" && !Array.isArray(metadata) && metadata.truncated === true;
-    }).length;
-    if (summary.usage) {
-      summary.usage = selectFields(summary.usage, [
-        "billing_status",
-        "payg_charge_usd_exact",
-        "provider_cost_usd_exact",
-        "unresolved_cost_count"
-      ]);
-    }
-    if (Array.isArray(summary.attempts)) {
-      summary.attempts = summary.attempts.map((attempt) => selectFields(attempt, [
-        "provider",
-        "status",
-        "result_count",
-        "latency_ms",
-        "estimated_cost_usd",
-        "error"
-      ]));
-    }
-    const providerResults = summary.provider_results;
-    if (providerResults && typeof providerResults === "object" && !Array.isArray(providerResults)) {
-      const counts = Object.fromEntries(
-        Object.entries(providerResults).map(([provider, values]) => [
-          provider,
-          Array.isArray(values) ? values.length : 0
-        ])
-      );
-      if (Object.keys(counts).length) summary.provider_result_counts = counts;
-      delete summary.provider_results;
-    }
-    if (Array.isArray(response.items)) {
-      summary.item_count = response.items.length;
-      summary.failed_item_count = response.items.filter(
-        (item) => item && typeof item === "object" && item.status === "failed"
-      ).length;
-    }
-    if (Array.isArray(summary.routes)) {
-      summary.routes = summary.routes.map((value) => {
-        if (!value || typeof value !== "object" || Array.isArray(value)) return value;
-        const route = { ...value };
-        const routeResults = route.provider_results;
-        if (routeResults && typeof routeResults === "object" && !Array.isArray(routeResults)) {
-          const counts = Object.fromEntries(
-            Object.entries(routeResults).map(([provider, values]) => [
-              provider,
-              Array.isArray(values) ? values.length : 0
-            ])
-          );
-          if (Object.keys(counts).length) route.provider_result_counts = counts;
-          delete route.provider_results;
-        }
-        if (Array.isArray(route.attempts)) {
-          route.attempts = route.attempts.map((attempt) => selectFields(attempt, [
-            "provider",
-            "status",
-            "result_count",
-            "latency_ms",
-            "estimated_cost_usd",
-            "error"
-          ]));
-        }
-        return route;
-      });
-    }
-    for (const field of ["cursor", "monitor"]) {
-      if (summary[field] === null) delete summary[field];
-    }
+    const summary = executionSummary(response);
     summary.output = {
       path: options.output,
       format: options.format,
@@ -1178,6 +1151,96 @@ async function emitExecution(response, options, command) {
   }
   await emit(response, jsonMode);
 }
+function executionSummary(response) {
+  const records = "records" in response && Array.isArray(response.records) ? response.records : response.items;
+  const summary = { ...response };
+  delete summary.records;
+  delete summary.items;
+  delete summary.normalized_schema;
+  summary.truncated_count = records.filter((record) => {
+    const metadata = record.metadata;
+    return metadata && typeof metadata === "object" && !Array.isArray(metadata) && metadata.truncated === true;
+  }).length;
+  if (summary.usage) {
+    summary.usage = selectFields(summary.usage, [
+      "billing_status",
+      "payg_charge_usd_exact",
+      "provider_cost_usd_exact",
+      "unresolved_cost_count"
+    ]);
+  }
+  if (Array.isArray(summary.attempts)) {
+    summary.attempts = summary.attempts.map((attempt) => selectFields(attempt, [
+      "provider",
+      "status",
+      "result_count",
+      "latency_ms",
+      "estimated_cost_usd",
+      "error"
+    ]));
+  }
+  const providerResults = summary.provider_results;
+  if (providerResults && typeof providerResults === "object" && !Array.isArray(providerResults)) {
+    const counts = Object.fromEntries(
+      Object.entries(providerResults).map(([provider, values]) => [
+        provider,
+        Array.isArray(values) ? values.length : 0
+      ])
+    );
+    if (Object.keys(counts).length) summary.provider_result_counts = counts;
+    delete summary.provider_results;
+  }
+  if (Array.isArray(response.items)) summary.item_count = response.items.length;
+  if (Array.isArray(summary.routes)) {
+    summary.routes = summary.routes.map((value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+      const route = { ...value };
+      const routeResults = route.provider_results;
+      if (routeResults && typeof routeResults === "object" && !Array.isArray(routeResults)) {
+        const counts = Object.fromEntries(
+          Object.entries(routeResults).map(([provider, values]) => [
+            provider,
+            Array.isArray(values) ? values.length : 0
+          ])
+        );
+        if (Object.keys(counts).length) route.provider_result_counts = counts;
+        delete route.provider_results;
+      }
+      if (Array.isArray(route.attempts)) {
+        route.attempts = route.attempts.map((attempt) => selectFields(attempt, [
+          "provider",
+          "status",
+          "result_count",
+          "latency_ms",
+          "estimated_cost_usd",
+          "error"
+        ]));
+      }
+      return route;
+    });
+  }
+  for (const field of ["cursor", "monitor"]) {
+    if (summary[field] === null) delete summary[field];
+  }
+  return summary;
+}
+function compactCatalog(items) {
+  return items.map((item) => ({
+    id: item.id,
+    source: item.source,
+    capability: item.capability,
+    label: item.label,
+    description: item.description,
+    execution_mode: item.execution_mode,
+    providers: Array.isArray(item.providers) ? item.providers.map((provider) => selectFields(provider, [
+      "id",
+      "label",
+      "available",
+      "reason",
+      "pricing"
+    ])) : []
+  }));
+}
 async function executeQueuedJob(path, payload, options, command) {
   if (options.detach && options.output) {
     throw new CliError(
@@ -1271,6 +1334,20 @@ auth.command("logout").action(async (_options, command) => {
   await clearRefreshToken2();
   await emit({ authenticated: false }, globals(command).json || false);
 });
+var skill = program.command("skill").description("Inspect or explicitly update the installed skill");
+skill.command("status").action(async (_options, command) => {
+  await emit(await installedSkillDiagnostics(), globals(command).json || false);
+});
+skill.command("update").action(async (_options, command) => {
+  const result = await updateInstalledSkill();
+  await emit(
+    result.status === "failed" ? { status: result.status, error: result.error.message } : result,
+    globals(command).json || false
+  );
+  if (result.status === "failed" || result.status === "unavailable") {
+    process.exitCode = EXIT.api;
+  }
+});
 program.command("doctor").description("Check the CLI, authentication, installed skill, API, and live catalog").action(async (_options, command) => {
   const usingApiKey = Boolean(process.env.SCRAPPYCOCO_API_KEY);
   const usingOAuth = !usingApiKey && Boolean(await loadRefreshToken());
@@ -1287,7 +1364,7 @@ program.command("doctor").description("Check the CLI, authentication, installed
       catalogError = error instanceof Error ? error.message : String(error);
     }
   }
-  const skill = await installedSkillDiagnostics();
+  const skill2 = await installedSkillDiagnostics();
   const ok = authentication.configured && catalogError === null;
   await emit(
     {
@@ -1306,7 +1383,7 @@ program.command("doctor").description("Check the CLI, authentication, installed
         available_capabilities: catalog2.length,
         error: catalogError
       },
-      skill,
+      skill: skill2,
       next_action: ok ? "Scrappycoco is ready." : authentication.configured ? "Check the API connection, then run doctor again." : "Run `scrappycoco setup`."
     },
     globals(command).json || false
@@ -1332,13 +1409,13 @@ scrapers.command("inspect <scraper-id>").action(async (scraperId, _options, comm
   );
 });
 var catalog = program.command("catalog").description("Inspect capabilities, provider schemas, options, and pricing");
-catalog.command("list").option("--source <source>", "filter by web, x, reddit, or filings").option("--provider <provider>", "filter by provider implementation").option("--available", "only include available providers").action(async (options, command) => {
+catalog.command("list").option("--source <source>", "filter by web, x, reddit, or filings").option("--provider <provider>", "filter by provider implementation").option("--available", "only include configured providers; this is not a live health check").option("--full", "include input/output and provider option schemas in JSON output").action(async (options, command) => {
   const query = new URLSearchParams();
   if (options.source) query.set("source", options.source);
   if (options.provider) query.set("provider", options.provider);
   if (options.available) query.set("available_only", "true");
   const items = await client(command).get(`/scrapers${query.size ? `?${query}` : ""}`);
-  if (globals(command).json) await emit(items, true);
+  if (globals(command).json) await emit(options.full ? items : compactCatalog(items), true);
   else process.stdout.write(formatCatalog(items));
 });
 catalog.command("inspect <capability-id>").action(async (capabilityId, _options, command) => {
@@ -1421,6 +1498,15 @@ jobs.command("wait <job-id>").description("Wait for a queued job and return its
     command
   );
 });
+jobs.command("cancel <job-id>").description("Cancel a pending or running queued job").action(async (jobId, _options, command) => {
+  await emit(
+    await client(command).post(
+      `/jobs/${encodeURIComponent(jobId)}/cancel`,
+      {}
+    ),
+    globals(command).json || false
+  );
+});
 var providers = program.command("providers", { hidden: true }).description("Legacy provider commands");
 providers.command("list").option("--available", "only include available provider-capability routes").action(async (options, command) => {
   await emit(
@@ -1473,7 +1559,7 @@ discoveries.command("delete <discovery-id>").requiredOption("--yes", "confirm pe
   await client(command).delete(`/discoveries/${encodeURIComponent(discoveryId)}`);
   await emit({ deleted: true, discovery_id: discoveryId }, globals(command).json || false);
 });
-program.command("discover").description("Save, sample-test, or finalize an agent-authored configuration").option("-f, --file <path>", "create from agent-authored discovery JSON").option("--id <discovery-id>", "existing discovery ID").option("--test", "run a representative provider sample test").option("--input <json>", "sample runtime input JSON").option("--update <path>", "replace fields or configuration from agent-authored JSON").option("--finalize", "mark the current explicit configuration finalized").option("--idempotency-key <key>", "stable sample retry key").action(async (options, command) => {
+program.command("discover").description("Save, sample-test, or finalize an agent-authored configuration").option("-f, --file <path>", "create from agent-authored discovery JSON").option("--id <discovery-id>", "existing discovery ID").option("--test", "run a representative provider sample test").option("--input <json>", "sample runtime input JSON").option("--update <path>", "replace fields or configuration from agent-authored JSON").option("--finalize", "mark the current explicit configuration finalized").option("--idempotency-key <key>", "stable sample retry key").option("-o, --output <path>", "write complete sample-test evidence to a JSON file").action(async (options, command) => {
   const selected = Number(Boolean(options.file)) + Number(Boolean(options.test)) + Number(Boolean(options.update)) + Number(Boolean(options.finalize));
   if (selected !== 1) {
     throw new CliError(
@@ -1481,6 +1567,9 @@ program.command("discover").description("Save, sample-test, or finalize an agent
       EXIT.usage
     );
   }
+  if (options.output && !options.test) {
+    throw new CliError("--output is supported only with --test.", EXIT.usage);
+  }
   if (options.file) {
     await emit(
       await client(command).post("/discoveries", await readJsonFile(options.file)),
@@ -1515,6 +1604,25 @@ program.command("discover").description("Save, sample-test, or finalize an agent
     { input, limit: 25 },
     options.idempotencyKey || randomUUID4()
   );
+  if (options.output) {
+    await emit(
+      response,
+      true,
+      options.output,
+      `${JSON.stringify(response, null, 2)}
+`
+    );
+    const summary = executionSummary(response);
+    summary.output = {
+      path: options.output,
+      format: "json",
+      kind: "discovery_evidence"
+    };
+    await emit(summary, globals(command).json || false);
+    process.stderr.write(`Saved complete Discovery evidence to ${options.output}
+`);
+    return;
+  }
   await emit(response, globals(command).json || false);
 });
 program.configureOutput({ writeErr: (text) => process.stderr.write(text) });

package/package.json

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