@topolo/cli 0.1.4 → 0.1.6

package/README.md

@@ -137,10 +137,29 @@ Both docs cover the same CLI surface: credential handling, the JSON invocation
 contract, the write-safety `--confirm` guardrail, and the cross-org isolation
 rules. Keep them in sync when adding new commands.
 
-## Phase 2 (planned)
+## Debug output
 
-- `topolo auth login` replaces the paste-API-key flow with an OAuth 2.1 device
-  authorization grant issued by TopoloAuth.
-- Refresh-token storage + automatic renewal.
-- OAuth client registration lives in TopoloDevelopers — consent UI will follow
-  the existing `@topolo/design-tokens` + `@topolo/ui-kit` patterns.
+Set `TOPOLO_DEBUG=1` to trace every SDK request to stderr (stdout stays clean
+so `--json` piping still works):
+
+```bash
+TOPOLO_DEBUG=1 topolo whoami
+# [topolo] → GET auth /api/auth/me (req=8f3...)
+# [topolo] ← 200 GET auth /api/auth/me (142ms, req=8f3...)
+```
+
+Request IDs match the `X-Topolo-Request-Id` header, so you can correlate a
+failing CLI call with the backend access log. Accepted truthy values:
+anything except `0` or `false`.
+
+## Token auto-refresh
+
+If the stored access token is within 60 s of expiry, the CLI transparently
+exchanges the stored refresh token for a new pair before making the request
+and rewrites the config — no user action required. The OAuth `client_id` used
+at login is persisted alongside the credential so refresh can re-authenticate.
+
+If refresh fails (network, rotated/revoked refresh token), the CLI proceeds
+with the stale credential and the request returns `auth_error` — run
+`topolo auth login` to re-authenticate. The stored config is not cleared on
+transient refresh failures.

package/dist/index.js

@@ -9,7 +9,7 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// ../packages/topolo-sdk/dist/index.js
+// node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -64,17 +64,38 @@ var TopoloHttpError = class extends TopoloSdkError {
     this.path = path;
   }
 };
-var DEFAULT_SERVICE_URLS = {
+var SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
-  crm: "https://topolo-crm-worker.topolo.workers.dev"
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mdm: "https://nodo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  "web.api": "https://web-api.topolo.app",
+  "web.runtime": "https://sites.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
   crm: "srv_iCwM4jGXcwlj"
 };
+var DEFAULT_SERVICE_URLS = SERVICES;
 function resolveServiceUrl(service, overrides) {
   const override = overrides?.[service];
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
   const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
   if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
@@ -87,6 +108,7 @@ var TopoloClient = class {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  debug;
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -96,6 +118,14 @@ var TopoloClient = class {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.debug = options.debug;
+  }
+  emit(event) {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+    }
   }
   /**
    * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
@@ -122,27 +152,56 @@ var TopoloClient = class {
     const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
-    applyAuditHeaders(headers, this.agent, generateRequestId());
+    const requestId = generateRequestId();
+    applyAuditHeaders(headers, this.agent, requestId);
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
     const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    const urlStr = url.toString();
+    const startedAt = Date.now();
+    this.emit({ phase: "request", method, service: opts.service, path: opts.path, url: urlStr, requestId });
     let res;
     try {
-      res = await this.fetchImpl(url.toString(), {
+      res = await this.fetchImpl(urlStr, {
         method,
         headers,
         body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
         signal
       });
+    } catch (err) {
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
     } finally {
       clearTimeout(timeoutId);
     }
     const contentType = res.headers.get("Content-Type") ?? "";
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
     if (!res.ok) {
+      const durationMs = Date.now() - startedAt;
+      const message = describeError(parsed, `HTTP ${res.status}`);
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs,
+        error: message,
+        status: res.status
+      });
       if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
       if (res.status === 403) {
         throw new TopoloPermissionError(
@@ -152,6 +211,16 @@ var TopoloClient = class {
       }
       throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
     }
+    this.emit({
+      phase: "response",
+      method,
+      service: opts.service,
+      path: opts.path,
+      url: urlStr,
+      requestId,
+      status: res.status,
+      durationMs: Date.now() - startedAt
+    });
     return parsed;
   }
   /**
@@ -712,9 +781,36 @@ async function buildClient(options) {
       agentName: resolveAgentName(config.agentName)
     },
     serviceUrls,
-    requireConfirmForWrites: options?.requireConfirmForWrites
+    requireConfirmForWrites: options?.requireConfirmForWrites,
+    ...isDebugEnabled() ? { debug: stderrDebugLogger } : {}
   });
 }
+function isDebugEnabled() {
+  const v = process.env.TOPOLO_DEBUG;
+  if (!v) return false;
+  return v !== "0" && v.toLowerCase() !== "false";
+}
+function stderrDebugLogger(event) {
+  if (event.phase === "request") {
+    process.stderr.write(
+      `[topolo] \u2192 ${event.method} ${event.service} ${event.path} (req=${event.requestId})
+`
+    );
+    return;
+  }
+  if (event.phase === "response") {
+    process.stderr.write(
+      `[topolo] \u2190 ${event.status} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${event.requestId})
+`
+    );
+    return;
+  }
+  const statusPart = event.status ? ` ${event.status}` : "";
+  process.stderr.write(
+    `[topolo] \u2717${statusPart} ${event.method} ${event.service} ${event.path} (${event.durationMs}ms, req=${event.requestId}): ${event.error}
+`
+  );
+}
 
 // src/commands/whoami.ts
 function registerWhoamiCommand(program2) {
@@ -810,24 +906,33 @@ function formatContact(c) {
 }
 
 // src/commands/api.ts
-var KNOWN_SERVICES = ["auth", "crm"];
+var KNOWN_SERVICES = Object.keys(DEFAULT_SERVICE_URLS).sort();
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var WRITE_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function registerApiCommand(program2) {
-  program2.command("api <service> <method> <path>").description("Generic passthrough to a Topolo service (escape hatch for untyped endpoints)").option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
+  program2.command("api <service> <method> <path>").description(
+    `Generic passthrough to a Topolo service. Known services: ${KNOWN_SERVICES.join(", ")}.`
+  ).option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option(
+    "-q, --query <kv...>",
+    "Query params as key=value (repeatable), e.g. --query source=cli page=2"
+  ).option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
     async (service, method, path, opts) => {
       const mode = resolveOutputMode(opts.json);
       try {
         const upperMethod = method.toUpperCase();
-        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(upperMethod)) {
-          throw new Error(`Unsupported method: ${method}`);
+        if (!HTTP_METHODS.includes(upperMethod)) {
+          throw new Error(
+            `Unsupported method "${method}". Known: ${HTTP_METHODS.join(", ")}`
+          );
         }
+        const httpMethod = upperMethod;
         if (!KNOWN_SERVICES.includes(service)) {
           throw new Error(
             `Unknown service "${service}". Known services: ${KNOWN_SERVICES.join(", ")}`
           );
         }
-        if (WRITE_METHODS2.has(upperMethod) && !opts.confirm) {
-          throw new Error(`Mutating ${upperMethod} requires --confirm.`);
+        if (WRITE_METHODS2.has(httpMethod) && !opts.confirm) {
+          throw new Error(`Mutating ${httpMethod} requires --confirm.`);
         }
         let body = void 0;
         if (opts.data) {
@@ -837,6 +942,7 @@ function registerApiCommand(program2) {
             throw new Error("--data must be valid JSON");
           }
         }
+        const query = parseQueryPairs(opts.query);
         const topolo = await buildClient();
         if (!topolo) {
           throw new Error(
@@ -845,9 +951,10 @@ function registerApiCommand(program2) {
         }
         const result = await topolo.client.request({
           service,
-          method: upperMethod,
+          method: httpMethod,
           path,
           body,
+          ...query ? { query } : {},
           confirm: opts.confirm === true
         });
         emit(result, mode, () => JSON.stringify(result, null, 2));
@@ -857,6 +964,55 @@ function registerApiCommand(program2) {
     }
   );
 }
+function parseQueryPairs(pairs) {
+  if (!pairs || pairs.length === 0) return void 0;
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`Invalid --query entry "${pair}". Expected key=value.`);
+    }
+    const key = pair.slice(0, eq);
+    const value = pair.slice(eq + 1);
+    out[key] = value;
+  }
+  return out;
+}
+
+// src/commands/services.ts
+function registerServicesCommand(program2) {
+  program2.command("services").description("List every Topolo service the SDK can route to").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action((opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const rows = Object.keys(DEFAULT_SERVICE_URLS).sort().map((id) => {
+        const defaultUrl = DEFAULT_SERVICE_URLS[id];
+        const effectiveUrl = resolveServiceUrl(id);
+        return {
+          id,
+          defaultUrl,
+          effectiveUrl,
+          overridden: defaultUrl !== effectiveUrl
+        };
+      });
+      emit({ services: rows }, mode, () => formatRows(rows));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatRows(rows) {
+  const idWidth = Math.max(3, ...rows.map((r) => r.id.length));
+  const urlWidth = Math.max(7, ...rows.map((r) => r.effectiveUrl.length));
+  const lines = [];
+  lines.push(`${"ID".padEnd(idWidth)}  ${"URL".padEnd(urlWidth)}  OVERRIDE`);
+  lines.push(`${"-".repeat(idWidth)}  ${"-".repeat(urlWidth)}  --------`);
+  for (const r of rows) {
+    lines.push(
+      `${r.id.padEnd(idWidth)}  ${r.effectiveUrl.padEnd(urlWidth)}  ${r.overridden ? "yes" : ""}`
+    );
+  }
+  return lines.join("\n");
+}
 
 // src/index.ts
 var program = new Command();
@@ -867,6 +1023,7 @@ registerAuthCommands(program);
 registerWhoamiCommand(program);
 registerCrmCommands(program);
 registerApiCommand(program);
+registerServicesCommand(program);
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Command-line interface for the Topolo platform. Designed for humans and for agents (Claude, Codex, etc.) that prefer shell invocation.",
   "type": "module",
   "bin": {
@@ -13,16 +13,19 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "file:../packages/topolo-sdk",
+    "@topolo/sdk": "latest",
     "@types/node": "^20.12.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
   },
   "engines": {
     "node": ">=20"