@topolo/cli 0.1.1

package/README.md

@@ -0,0 +1,131 @@
+# TopoloCli
+
+Command-line interface for the Topolo platform. Designed for both humans and
+third-party agents (Claude Code, Codex, Cursor, etc.) that prefer to interact
+via `stdin`/`stdout`.
+
+## Phase 1 scope
+
+- API-key authentication (long-lived, service-scoped).
+- Access-token authentication (short-lived, cross-service — used for dev/testing).
+- Commands: `auth login/logout/status`, `whoami`, `crm contacts:list`, `crm contacts:get`, generic `api` passthrough.
+- OAuth2 authorization-code + device flows will arrive in Phase 2; until then, `auth login` expects a paste-in API key minted at the Topolo Developers console.
+
+## Install
+
+```bash
+npm install -g @topolo/cli
+# or run ad-hoc:
+npx @topolo/cli whoami
+```
+
+## Configure
+
+Credentials come from (in priority order):
+
+1. `TOPOLO_API_KEY` env var
+2. `TOPOLO_ACCESS_TOKEN` env var
+3. Config file (`$XDG_CONFIG_HOME/topolo/config.json`, mode `0600`)
+
+For interactive use:
+
+```bash
+topolo auth login            # prompts for API key
+topolo auth status           # shows which source is active
+topolo auth logout           # clears the stored credential
+```
+
+## Cross-org isolation
+
+The CLI **never accepts an `orgId` argument**. Every command is scoped to the
+organization embedded in the credential. This is enforced in two places:
+
+1. The SDK does not expose any `orgId` parameter on any public method.
+2. Each Topolo backend app re-derives `orgId` from the credential on every request and binds it to SQL query filters.
+
+There is no code path in the CLI that could ever let you read or mutate another
+organization's data.
+
+## Audit headers
+
+Every outbound request carries:
+
+- `X-Topolo-Client: topolo-cli/<version>`
+- `X-Topolo-Agent: <label>` (if `TOPOLO_AGENT_NAME` is set)
+- `X-Topolo-Request-Id: <uuid>`
+
+The platform logs these for traceability.
+
+## Write-action gating
+
+The SDK defaults to requiring an explicit `--confirm` flag on any mutating
+request. The generic `topolo api` passthrough enforces this too:
+
+```bash
+topolo api crm POST /api/contacts --data '{"email":"a@b.co"}' --confirm
+```
+
+## Commands
+
+### `topolo whoami`
+
+Prints the user, organization, and granted scopes.
+
+```bash
+topolo whoami           # pretty
+topolo whoami --json    # machine-readable
+```
+
+### `topolo crm contacts:list`
+
+```bash
+topolo crm contacts:list
+topolo crm contacts:list -q "acme" -p 2 -s 50 --json
+```
+
+### `topolo crm contacts:get <id>`
+
+```bash
+topolo crm contacts:get contact_abc123
+```
+
+### `topolo api <service> <method> <path>`
+
+Escape hatch for endpoints without typed modules yet.
+
+```bash
+topolo api auth GET /api/me
+topolo api crm POST /api/contacts --data '{"first":"Jane"}' --confirm
+```
+
+## Output modes
+
+- Pretty when stdout is a TTY.
+- JSON when piped or redirected.
+- Force either with `--json` / `--no-json`.
+
+## Exit codes
+
+| Code | Meaning                 |
+| ---- | ----------------------- |
+| 0    | Success                 |
+| 1    | Generic error           |
+| 2    | Auth error              |
+| 3    | Permission denied       |
+
+## Development
+
+```bash
+cd TopoloCli
+npm install
+npm run build
+node dist/index.js whoami
+```
+
+## Phase 2 (planned)
+
+- `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.

package/dist/index.js

@@ -0,0 +1,486 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/auth.ts
+import { spawn } from "child_process";
+import { platform as platform2 } from "os";
+import { createInterface } from "readline/promises";
+import { stdin as input } from "process";
+import { TopoloOAuth, TopoloAuthError } from "@topolo/sdk";
+
+// src/config.ts
+import { mkdir, readFile, writeFile, chmod } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+function configPath() {
+  const override = process.env.TOPOLO_CONFIG_PATH;
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "config.json");
+}
+async function readConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeConfig(config) {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  if (platform() !== "win32") {
+    try {
+      await chmod(path, 384);
+    } catch {
+    }
+  }
+}
+async function resolveCredential() {
+  const apiKey = process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: "api_key", apiKey };
+  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: "access_token", accessToken };
+  const config = await readConfig();
+  return config.credential ?? null;
+}
+function resolveAgentName(configAgentName) {
+  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
+}
+function resolveServiceUrls(configUrls) {
+  const merged = { ...configUrls ?? {} };
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith("TOPOLO_SERVICE_URL_") && v) {
+      merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
+    }
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+
+// src/output.ts
+function resolveOutputMode(override) {
+  if (override === true) return "json";
+  if (override === false) return "pretty";
+  return process.stdout.isTTY ? "pretty" : "json";
+}
+function emit(data, mode, pretty) {
+  if (mode === "json") {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  } else {
+    process.stdout.write(pretty() + "\n");
+  }
+}
+function fail(err, mode) {
+  const payload = normalizeError(err);
+  if (mode === "json") {
+    process.stderr.write(JSON.stringify({ error: payload }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`Error: ${payload.message}
+`);
+    if (payload.code) process.stderr.write(`Code:  ${payload.code}
+`);
+    if (payload.hint) process.stderr.write(`Hint:  ${payload.hint}
+`);
+  }
+  process.exit(payload.exitCode);
+}
+function normalizeError(err) {
+  if (err instanceof Error) {
+    const code = err.code;
+    const hintMap = {
+      auth_error: "Run `topolo auth login` or set TOPOLO_API_KEY.",
+      permission_denied: "Check your API key scopes or role assignments in TopoloDevelopers."
+    };
+    return {
+      message: err.message,
+      code,
+      hint: code ? hintMap[code] : void 0,
+      exitCode: code === "auth_error" ? 2 : code === "permission_denied" ? 3 : 1
+    };
+  }
+  return { message: String(err), exitCode: 1 };
+}
+
+// src/commands/auth.ts
+var API_KEY_ISSUANCE_URL = "https://developers.topolo.app/credentials";
+var OAUTH_CLIENT_REGISTRATION_URL = "https://developers.topolo.app/developers/oauth-clients";
+function registerAuthCommands(program2) {
+  const auth = program2.command("auth").description("Manage Topolo credentials");
+  auth.command("login").description("Authenticate with Topolo via OAuth device flow (default) or store an API key").option("--api-key <key>", "Store an API key directly, skipping the OAuth flow").option("--client-id <id>", "OAuth client_id (or set TOPOLO_CLI_CLIENT_ID)").option("--scope <scope>", "Scopes to request (space-separated)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(
+    async (opts) => {
+      const mode = resolveOutputMode(opts.json);
+      try {
+        if (opts.apiKey) {
+          await storeApiKey(opts.apiKey.trim(), mode);
+          return;
+        }
+        const clientId = opts.clientId ?? process.env.TOPOLO_CLI_CLIENT_ID;
+        if (!clientId) {
+          if (!input.isTTY) {
+            throw new Error(
+              `No OAuth client_id configured and stdin is not a TTY. Either register an OAuth client at ${OAUTH_CLIENT_REGISTRATION_URL} and export TOPOLO_CLI_CLIENT_ID, or pass --api-key <key> (mint one at ${API_KEY_ISSUANCE_URL}).`
+            );
+          }
+          process.stderr.write(
+            `No OAuth client_id configured. Falling back to API key.
+Visit ${API_KEY_ISSUANCE_URL} to mint one, or configure an OAuth client at ${OAUTH_CLIENT_REGISTRATION_URL} and set TOPOLO_CLI_CLIENT_ID.
+`
+          );
+          const rl = createInterface({ input, output: process.stderr });
+          const apiKey = (await rl.question("Paste API key: ")).trim();
+          rl.close();
+          if (!apiKey) throw new Error("API key is required");
+          await storeApiKey(apiKey, mode);
+          return;
+        }
+        await runDeviceFlow({ clientId, scope: opts.scope, mode });
+      } catch (err) {
+        fail(err, mode);
+      }
+    }
+  );
+  auth.command("logout").description("Remove stored credentials from this machine").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const config = await readConfig();
+      delete config.credential;
+      await writeConfig(config);
+      emit({ ok: true }, mode, () => "Logged out.");
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  auth.command("status").description("Show which credential source is in use (env vs config file)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const source = process.env.TOPOLO_API_KEY ? "env:TOPOLO_API_KEY" : process.env.TOPOLO_ACCESS_TOKEN ? "env:TOPOLO_ACCESS_TOKEN" : (await readConfig()).credential ? "config-file" : "none";
+      emit({ source }, mode, () => `Credential source: ${source}`);
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+async function storeApiKey(apiKey, mode) {
+  if (!apiKey) throw new Error("API key is required");
+  const config = await readConfig();
+  config.credential = { kind: "api_key", apiKey };
+  await writeConfig(config);
+  emit(
+    { ok: true, credential: { kind: "api_key" } },
+    mode,
+    () => "Stored API key. Run `topolo whoami` to verify."
+  );
+}
+async function runDeviceFlow(options) {
+  const config = await readConfig();
+  const oauth = new TopoloOAuth({
+    serviceUrls: resolveServiceUrls(config.serviceUrls)
+  });
+  const start = await oauth.requestDeviceCode({
+    clientId: options.clientId,
+    ...options.scope ? { scope: options.scope } : {}
+  });
+  const verifyUrl = start.verification_uri_complete ?? start.verification_uri;
+  const expiresMin = Math.round(start.expires_in / 60);
+  const opened = options.mode === "pretty" ? tryOpenBrowser(verifyUrl) : false;
+  if (options.mode === "pretty") {
+    process.stderr.write(
+      `
+  Sign in to Topolo
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+` + (opened ? `  Opening your browser to approve...
+` : `  Open this link in your browser:
+`) + `  ${verifyUrl}
+
+  The page will show this code \u2014 confirm it matches:
+
+      ${start.user_code}
+
+  Waiting for approval (expires in ${expiresMin} min)`
+    );
+  }
+  const spinner = options.mode === "pretty" ? startSpinner() : null;
+  let token;
+  try {
+    token = await pollUntilApproved({
+      oauth,
+      clientId: options.clientId,
+      deviceCode: start.device_code,
+      intervalSeconds: start.interval,
+      expiresAtMs: Date.now() + start.expires_in * 1e3
+    });
+  } finally {
+    spinner?.stop();
+  }
+  const updated = await readConfig();
+  updated.credential = {
+    kind: "access_token",
+    accessToken: token.access_token,
+    ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
+    expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
+  };
+  await writeConfig(updated);
+  emit(
+    {
+      ok: true,
+      credential: {
+        kind: "access_token",
+        expiresIn: token.expires_in,
+        scope: token.scope
+      }
+    },
+    options.mode,
+    () => "\n  \u2713 Signed in. Run `topolo whoami` to see your identity."
+  );
+}
+function tryOpenBrowser(url) {
+  try {
+    const os = platform2();
+    const cmd = os === "darwin" ? "open" : os === "win32" ? "start" : "xdg-open";
+    const args = os === "win32" ? ["", url] : [url];
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: "ignore",
+      ...os === "win32" ? { shell: true } : {}
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+function startSpinner() {
+  if (!process.stderr.isTTY) return null;
+  const frames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+  let i = 0;
+  process.stderr.write(" ");
+  const timer = setInterval(() => {
+    process.stderr.write(`\b${frames[i++ % frames.length]}`);
+  }, 80);
+  return {
+    stop: () => {
+      clearInterval(timer);
+      process.stderr.write("\b \n");
+    }
+  };
+}
+async function pollUntilApproved(params) {
+  let interval = Math.max(params.intervalSeconds, 1);
+  while (Date.now() < params.expiresAtMs) {
+    await sleep(interval * 1e3);
+    try {
+      const token = await params.oauth.pollDeviceToken({
+        clientId: params.clientId,
+        deviceCode: params.deviceCode
+      });
+      return token;
+    } catch (err) {
+      if (err instanceof TopoloAuthError) {
+        if (err.code === "authorization_pending") continue;
+        if (err.code === "slow_down") {
+          interval += 2;
+          continue;
+        }
+        if (err.code === "access_denied") {
+          throw new Error("Authorization was denied.");
+        }
+        if (err.code === "expired_token") {
+          throw new Error("Device code expired. Run `topolo auth login` again.");
+        }
+      }
+      throw err;
+    }
+  }
+  throw new Error("Device code expired. Run `topolo auth login` again.");
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+import { createTopolo } from "@topolo/sdk";
+
+// src/version.ts
+var CLI_VERSION = "0.1.0";
+
+// src/client.ts
+async function buildClient(options) {
+  const credential = await resolveCredential();
+  if (!credential) return null;
+  const config = await readConfig();
+  const serviceUrls = resolveServiceUrls(config.serviceUrls);
+  return createTopolo({
+    credential,
+    agent: {
+      clientName: "topolo-cli",
+      clientVersion: CLI_VERSION,
+      agentName: resolveAgentName(config.agentName)
+    },
+    serviceUrls,
+    requireConfirmForWrites: options?.requireConfirmForWrites
+  });
+}
+
+// src/commands/whoami.ts
+function registerWhoamiCommand(program2) {
+  program2.command("whoami").description("Show the user, organization, and scopes attached to the current credential").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const info = await topolo.identity.whoami();
+      emit(info, mode, () => formatPretty(info));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatPretty(info) {
+  const lines = [];
+  lines.push(`User:         ${info.user.name ?? "(unnamed)"} <${info.user.email}>`);
+  lines.push(`Role:         ${info.user.role}`);
+  lines.push(
+    `Organization: ${info.organization ? `${info.organization.name} (${info.organization.slug})` : "(none)"}`
+  );
+  lines.push(`Credential:   ${info.kind}`);
+  lines.push(`Scopes:       ${info.user.permissions.length === 0 ? "(none)" : ""}`);
+  for (const p of info.user.permissions) lines.push(`  - ${p}`);
+  return lines.join("\n");
+}
+
+// src/commands/crm.ts
+function registerCrmCommands(program2) {
+  const crm = program2.command("crm").description("TopoloCRM operations");
+  crm.command("contacts:list").description("List contacts in the authenticated organization").option("-q, --query <text>", "Full-text search").option("-p, --page <n>", "Page number (1-indexed)", (v) => parseInt(v, 10), 1).option("-s, --page-size <n>", "Page size", (v) => parseInt(v, 10), 25).option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const result = await topolo.crm.listContacts({
+        q: opts.query,
+        page: opts.page,
+        pageSize: opts.pageSize
+      });
+      emit(result, mode, () => formatContactsTable(result.contacts, result.total, result.page));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  crm.command("contacts:get <id>").description("Fetch a single contact by id").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (id, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const contact = await topolo.crm.getContact(id);
+      if (!contact) throw new Error(`Contact not found: ${id}`);
+      emit(contact, mode, () => formatContact(contact));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatContactsTable(rows, total, page) {
+  if (rows.length === 0) return "No contacts found.";
+  const lines = [];
+  lines.push(`Showing ${rows.length} of ${total} contacts (page ${page})`);
+  lines.push("");
+  for (const row of rows) {
+    const name = [row.firstName, row.lastName].filter(Boolean).join(" ") || "(no name)";
+    const parts = [name];
+    if (row.email) parts.push(row.email);
+    if (row.company) parts.push(`@ ${row.company}`);
+    if (row.leadStatus) parts.push(`[${row.leadStatus}]`);
+    lines.push(`  ${row.id}  ${parts.join(" \xB7 ")}`);
+  }
+  return lines.join("\n");
+}
+function formatContact(c) {
+  const name = [c.firstName, c.lastName].filter(Boolean).join(" ") || "(no name)";
+  return [
+    `ID:             ${c.id}`,
+    `Name:           ${name}`,
+    `Email:          ${c.email ?? "-"}`,
+    `Phone:          ${c.phone ?? "-"}`,
+    `Company:        ${c.company ?? "-"}`,
+    `Lead status:    ${c.leadStatus ?? "-"}`,
+    `Lifecycle:      ${c.lifecycleStage ?? "-"}`,
+    `Updated at:     ${c.updatedAt ?? "-"}`
+  ].join("\n");
+}
+
+// src/commands/api.ts
+var KNOWN_SERVICES = ["auth", "crm"];
+var WRITE_METHODS = /* @__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(
+    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 (!KNOWN_SERVICES.includes(service)) {
+          throw new Error(
+            `Unknown service "${service}". Known services: ${KNOWN_SERVICES.join(", ")}`
+          );
+        }
+        if (WRITE_METHODS.has(upperMethod) && !opts.confirm) {
+          throw new Error(`Mutating ${upperMethod} requires --confirm.`);
+        }
+        let body = void 0;
+        if (opts.data) {
+          try {
+            body = JSON.parse(opts.data);
+          } catch {
+            throw new Error("--data must be valid JSON");
+          }
+        }
+        const topolo = await buildClient();
+        if (!topolo) {
+          throw new Error(
+            "No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY."
+          );
+        }
+        const result = await topolo.client.request({
+          service,
+          method: upperMethod,
+          path,
+          body,
+          confirm: opts.confirm === true
+        });
+        emit(result, mode, () => JSON.stringify(result, null, 2));
+      } catch (err) {
+        fail(err, mode);
+      }
+    }
+  );
+}
+
+// src/index.ts
+var program = new Command();
+program.name("topolo").description(
+  "Topolo platform CLI. Every command is scoped to the authenticated organization \u2014 there is no way to target a different org."
+).version(CLI_VERSION);
+registerAuthCommands(program);
+registerWhoamiCommand(program);
+registerCrmCommands(program);
+registerApiCommand(program);
+program.parseAsync(process.argv).catch((err) => {
+  process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@topolo/cli",
+  "version": "0.1.1",
+  "description": "Command-line interface for the Topolo platform. Designed for humans and for agents (Claude, Codex, etc.) that prefer shell invocation.",
+  "type": "module",
+  "bin": {
+    "topolo": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@topolo/sdk": "file:../packages/topolo-sdk",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}