@topolo/cli 0.1.4 → 0.1.5

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);
@@ -87,6 +87,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 +97,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 +131,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 +190,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 +760,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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"