@topolo/cli 0.1.3 → 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;
   }
   /**
@@ -409,6 +457,37 @@ async function resolveCredential() {
   const config = await readConfig();
   return config.credential ?? null;
 }
+var REFRESH_SKEW_SECONDS = 60;
+async function refreshCredentialIfNeeded() {
+  if (process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+    return resolveCredential();
+  }
+  const config = await readConfig();
+  const cred = config.credential;
+  if (!cred || cred.kind !== "access_token") return cred ?? null;
+  if (!cred.refreshToken || !cred.expiresAt || !config.oauthClientId) return cred;
+  const now = Math.floor(Date.now() / 1e3);
+  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(config.serviceUrls)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: config.oauthClientId,
+      refreshToken: cred.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    await writeConfig({ ...config, credential: refreshed });
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
@@ -585,6 +664,7 @@ async function runDeviceFlow(options) {
     ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
     expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
   };
+  updated.oauthClientId = options.clientId;
   await writeConfig(updated);
   emit(
     {
@@ -664,11 +744,11 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.1.3";
+var CLI_VERSION = "0.1.4";
 
 // src/client.ts
 async function buildClient(options) {
-  const credential = await resolveCredential();
+  const credential = await refreshCredentialIfNeeded();
   if (!credential) return null;
   const config = await readConfig();
   const serviceUrls = resolveServiceUrls(config.serviceUrls);
@@ -680,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.3",
+  "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"