@caphub/cli 0.1.0 → 0.1.2

package/bin/caphub.js

@@ -13,6 +13,8 @@ const CONFIG_PATH = resolve(CONFIG_DIR, "config.json");
 
 const ROOT_HELP = `caphub
 
+Caphub is hosted infrastructure for agent-ready capabilities such as search and query expansion.
+
 purpose: root CLI for Caphub agent capabilities
 auth: CAPHUB_API_KEY env or ${CONFIG_PATH}
 api: ${DEFAULT_API_URL}
@@ -21,18 +23,43 @@ commands:
   help                  explain the platform and command layout
   help <capability>     show capability-specific help from the API
   capabilities          list live capabilities with short descriptions
-  auth login            save api key locally for future runs
+  auth                  show current login state
+  auth login            website login flow; stores api key locally after approval
   auth whoami           verify the current api key against the API
   auth logout           remove stored api key from local config
   <capability> <json>   run a capability directly, e.g. search or search-ideas
 
+agent workflow:
+  1. caphub capabilities
+  2. caphub help <capability>
+  3. caphub auth login
+  4. caphub <capability> '<json>'
+
+recovery:
+  no api key            caphub auth login
+  invalid api key       generate a new key in https://caphub.io/dashboard/
+  insufficient credits  top up in https://caphub.io/dashboard/
+  bad json              caphub help <capability>
+  capability unknown    caphub capabilities
+
 examples:
+  caphub auth
   caphub capabilities
+  caphub auth login
   caphub auth login --api-key csk_live_...
   caphub help search
   caphub search '{"queries":["site:github.com awesome ai agents"]}'
 `;
 
+class ApiError extends Error {
+  constructor(message, status = 0, data = null) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.data = data;
+  }
+}
+
 function readConfig() {
   try {
     return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
@@ -82,22 +109,27 @@ async function fetchJson(url, { method = "GET", body, apiKey = "" } = {}) {
   const headers = { "Content-Type": "application/json" };
   if (apiKey) headers["X-API-Key"] = apiKey;
 
-  const resp = await fetch(url, {
-    method,
-    headers,
-    ...(body ? { body: JSON.stringify(body) } : {}),
-  });
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method,
+      headers,
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (error) {
+    throw new ApiError(`request failed: ${error.message}`, 0, null);
+  }
 
   const text = await resp.text();
   let data;
   try {
     data = text ? JSON.parse(text) : {};
   } catch {
-    throw new Error(`non-JSON response from ${url} (HTTP ${resp.status})`);
+    throw new ApiError(`non-JSON response from ${url} (HTTP ${resp.status})`, resp.status, null);
   }
 
   if (!resp.ok) {
-    throw new Error(data?.error || `HTTP ${resp.status}`);
+    throw new ApiError(data?.error || `HTTP ${resp.status}`, resp.status, data);
   }
 
   return data;
@@ -109,8 +141,71 @@ function parseFlag(args, name) {
   return args[idx + 1] || "";
 }
 
+function buildRecoveryHints(error, context = {}) {
+  const hints = [];
+  const capability = context.capability || "<capability>";
+  const message = String(error?.message || "").toLowerCase();
+  const status = Number(error?.status || 0);
+
+  if (status === 401 || message.includes("missing x-api-key header")) {
+    hints.push("login: caphub auth login");
+  }
+
+  if (status === 403 || message.includes("invalid api key")) {
+    hints.push("generate a new key in https://caphub.io/dashboard/");
+    hints.push("login again: caphub auth login --api-key csk_live_...");
+  }
+
+  if (status === 402 || message.includes("insufficient credits")) {
+    hints.push("top up credits in https://caphub.io/dashboard/");
+    hints.push("check account state: caphub auth whoami");
+  }
+
+  if (
+    status === 400 ||
+    message.includes("queries array is required") ||
+    message.includes("unsupported function") ||
+    message.includes("input must be valid json") ||
+    message.includes("input json is required")
+  ) {
+    hints.push(`capability contract: caphub help ${capability}`);
+  }
+
+  if (message.includes("request failed:")) {
+    hints.push(`api url: ${getApiUrl()}`);
+    hints.push(`health: curl -sS ${getApiUrl()}/health`);
+  }
+
+  if (!hints.length) {
+    hints.push("discover capabilities: caphub capabilities");
+    hints.push(`capability contract: caphub help ${capability}`);
+  }
+
+  return hints;
+}
+
+function failWithHints(message, error, context = {}) {
+  const lines = [`Error: ${message}`];
+  const hints = buildRecoveryHints(error, context);
+  if (hints.length) {
+    lines.push("", "next:");
+    for (const hint of hints) lines.push(`  - ${hint}`);
+  }
+  fail(lines.join("\n"));
+}
+
+function sleep(ms) {
+  return new Promise((resolveWait) => setTimeout(resolveWait, ms));
+}
+
 function printCapabilities(payload) {
-  const lines = ["caphub capabilities", ""];
+  const lines = [
+    "caphub capabilities",
+    "",
+    "Live capabilities available through the current API.",
+    "Use 'caphub help <capability>' before first use.",
+    "",
+  ];
   for (const capability of payload.capabilities || []) {
     lines.push(`/${capability.capability} - ${capability.purpose}`);
     if (capability.credits) lines.push(`  credits: ${capability.credits}`);
@@ -137,6 +232,15 @@ function printCapabilityHelp(payload) {
     "",
     "output:",
     JSON.stringify(payload.output_contract, null, 2),
+    payload.notes_for_agents?.length ? "" : null,
+    payload.notes_for_agents?.length ? "notes:" : null,
+    ...(payload.notes_for_agents || []).map((note) => `- ${note}`),
+    "",
+    "common recovery:",
+    "- auth missing: caphub auth login",
+    "- auth invalid: generate a new key in https://caphub.io/dashboard/",
+    "- low credits: top up in https://caphub.io/dashboard/",
+    `- bad payload: caphub help ${payload.capability}`,
   ].filter(Boolean);
   process.stdout.write(`${lines.join("\n")}\n`);
 }
@@ -167,10 +271,92 @@ async function commandAuth(args) {
   const sub = args[0];
   const config = readConfig();
 
+  if (!sub) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+      process.stdout.write([
+        "caphub auth",
+        "",
+        "status: not logged in",
+        "",
+        "next:",
+        "  - caphub auth login",
+        "  - or for headless/cloud agents: caphub auth login --api-key csk_live_...",
+        "",
+      ].join("\n"));
+      return;
+    }
+
+    try {
+      const payload = await fetchJson(`${getApiUrl()}/v1/me`, { apiKey });
+      process.stdout.write([
+        "caphub auth",
+        "",
+        "status: logged in",
+        `email: ${payload.user.email}`,
+        `user_id: ${payload.user.id}`,
+        `credits_remaining: ${payload.total_usage.credits_remaining}`,
+        `total_credits_used: ${payload.total_usage.total_credits_used}`,
+        "",
+        "next:",
+        "  - caphub capabilities",
+        "  - caphub help search",
+        "",
+      ].join("\n"));
+      return;
+    } catch (error) {
+      failWithHints("stored credentials are not valid", error, { capability: "search" });
+    }
+  }
+
   if (sub === "login") {
-    const apiKey = parseFlag(args, "--api-key") || getApiKey();
+    const explicitApiKey = parseFlag(args, "--api-key");
+    if (!explicitApiKey && !args.includes("--api-key")) {
+      const apiUrl = getApiUrl();
+      const started = await fetchJson(`${apiUrl}/v1/auth/cli/start`, { method: "POST", body: {} });
+      process.stdout.write([
+        "caphub auth login",
+        "",
+        "Open this URL in your browser and finish sign-in:",
+        started.approval_url,
+        "",
+        `code: ${started.code}`,
+        `expires_in_seconds: ${started.expires_in_seconds}`,
+        "",
+        "Waiting for website approval...",
+        "",
+      ].join("\n"));
+
+      const deadline = Date.now() + Number(started.expires_in_seconds || 600) * 1000;
+      const intervalMs = Number(started.poll_interval_seconds || 2) * 1000;
+      while (Date.now() < deadline) {
+        const polled = await fetchJson(`${apiUrl}/v1/auth/cli/poll`, {
+          method: "POST",
+          body: {
+            session_id: started.session_id,
+            poll_token: started.poll_token,
+          },
+        });
+
+        if (polled.status === "approved" && polled.api_key) {
+          writeConfig({
+            ...config,
+            api_key: polled.api_key,
+            api_url: apiUrl,
+          });
+          process.stdout.write(`${JSON.stringify({ ok: true, config_path: CONFIG_PATH, api_url: apiUrl }, null, 2)}\n`);
+          return;
+        }
+
+        await sleep(intervalMs);
+      }
+
+      fail("Error: login approval timed out.\n\nnext:\n  - rerun: caphub auth login\n  - or open https://caphub.io/dashboard/");
+    }
+
+    const apiKey = explicitApiKey || getApiKey();
     const apiUrl = parseFlag(args, "--api-url") || getApiUrl();
-    if (!apiKey) fail("Error: auth login requires --api-key or CAPHUB_API_KEY.");
+    if (!apiKey) fail("Error: auth login requires --api-key or CAPHUB_API_KEY.\n\nnext:\n  - caphub auth login --api-key csk_live_...");
     writeConfig({
       ...config,
       api_key: apiKey,
@@ -182,7 +368,7 @@ async function commandAuth(args) {
 
   if (sub === "whoami") {
     const apiKey = getApiKey();
-    if (!apiKey) fail(`Error: no api key configured. Use 'caphub auth login --api-key ...' or set ${CONFIG_PATH}.`);
+    if (!apiKey) fail(`Error: no api key configured.\n\nnext:\n  - caphub auth login --api-key csk_live_...\n  - or set api_key in ${CONFIG_PATH}`);
     const payload = await fetchJson(`${getApiUrl()}/v1/me`, { apiKey });
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     return;
@@ -201,7 +387,11 @@ async function commandAuth(args) {
 
 async function commandCapability(capability, args) {
   const apiKey = getApiKey();
-  if (!apiKey) fail(`Error: CAPHUB_API_KEY is required, or set api_key in ${CONFIG_PATH}.`);
+  if (!apiKey) {
+    fail(
+      `Error: no api key configured for capability "${capability}".\n\nnext:\n  - caphub auth login --api-key csk_live_...\n  - then retry: caphub ${capability} '<json>'\n  - contract: caphub help ${capability}`
+    );
+  }
 
   if (args[0] === "--help" || args[0] === "help") {
     await commandHelp([capability]);
@@ -211,14 +401,14 @@ async function commandCapability(capability, args) {
   const arg = args[0];
   const rawInput = arg ?? (process.stdin.isTTY ? "" : await readStdin());
   if (!rawInput.trim()) {
-    fail(`Error: input JSON is required. Run 'caphub help ${capability}' for the contract.`);
+    fail(`Error: input JSON is required.\n\nnext:\n  - caphub help ${capability}\n  - then run: caphub ${capability} '<json>'`);
   }
 
   let body;
   try {
     body = JSON.parse(rawInput);
   } catch {
-    fail("Error: input must be valid JSON.");
+    fail(`Error: input must be valid JSON.\n\nnext:\n  - caphub help ${capability}\n  - pass exactly one JSON object`);
   }
 
   if (!("function" in body)) body.function = capability;
@@ -258,4 +448,10 @@ async function main() {
   await commandCapability(cmd, args.slice(1));
 }
 
-await main().catch((error) => fail(`Error: ${error.message}`));
+await main().catch((error) => {
+  const cmd = process.argv[2];
+  const capability = cmd && !["help", "--help", "-h", "capabilities", "auth", "--version", "-v", "version"].includes(cmd)
+    ? cmd
+    : undefined;
+  failWithHints(error.message || "unknown error", error, { capability });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caphub/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Root CLI for Caphub agent capabilities",
   "type": "module",
   "bin": {