@topolo/cli 0.1.32 → 0.2.1

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.32",
+  "version": "0.2.1",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {
     "topolo": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
+    "build:sdk": "pnpm --dir ../topolo-sdk build",
+    "prebuild": "pnpm run build:sdk",
     "build": "tsup",
     "dev": "tsup --watch",
+    "pretypecheck": "pnpm run build:sdk",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
+    "pretest": "pnpm run build:sdk",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage"
@@ -22,7 +27,7 @@
     "commander": "^12.1.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "workspace:*",
+    "@topolo/sdk": "file:../topolo-sdk",
     "@types/node": "^20.12.0",
     "@vitest/coverage-v8": "^2.1.0",
     "tsup": "^8.0.0",

package/skills/codex/AGENTS.md

@@ -0,0 +1,155 @@
+# Topolo — agent guide (Codex / general-purpose agents)
+
+This file teaches an agent how to interact with the Topolo platform via the `topolo` CLI and, when available, the Topolo MCP server. It is intentionally short, shell-first, and stable across Codex, Cursor, and any other agent that reads `AGENTS.md`.
+
+## What the platform is
+
+Topolo is a multi-app SaaS platform. The CLI and MCP server both use `@topolo/sdk`; bundled app IDs come from the generated registry, and newly registered API/technical services can be resolved from the live Auth catalog.
+
+- Use `topolo apps --json` or the MCP `topolo_search_applications` tool to discover platform applications, including browser-only Worker apps.
+- Use `topolo apps requirements <application_id> --json` or the MCP `topolo_list_application_requirements` tool before creating or expanding a Topolo app.
+- Use `topolo apps audit <application_id> --json` or the MCP `topolo_audit_applications` tool to inspect current requirement conformance and migration work.
+- Use `topolo services --json` or the MCP `topolo_search_applications` tool to discover callable app ids and effective URLs.
+- Use `topolo actions --service <app> --json` or MCP `topolo_search_actions` to discover callable operations granted to the current credential; invoke automatic reads with `topolo_read_action` and confirmation-gated operations with `topolo_call_action`.
+- The generic `api` command and MCP `topolo_api_call` tool can reach bundled SDK services and live Auth-catalog API/technical services when no action contract exists yet.
+
+Every call is scoped to the organization embedded in the credential. There is no `--org` flag anywhere — attempting to target another org will fail.
+
+## Invocation contract
+
+Always call `topolo` with `--json` from an agent. JSON schemas are stable; human text is not.
+
+```bash
+topolo <command> [args] --json
+```
+
+Production is the default CLI environment. Use `--env staging` anywhere in the
+command, or set `TOPOLO_ENV=staging`, for internal staging auth, staging service
+discovery, or staging scaffold provisioning. Staging credentials are stored
+separately from production credentials.
+
+On success the command prints JSON to stdout and exits 0. On failure it prints `{"error":{"message","code","hint","exitCode"}}` to stderr and exits non-zero. Branch on `code` (not on message text).
+
+Exit codes:
+
+- `0` success
+- `1` generic error
+- `2` auth error → run `topolo auth login` and retry
+- `3` permission denied → the user's role/scopes are insufficient; surface to user, do not retry
+
+## Setup flow
+
+1. Check install: `command -v topolo || npm install -g @topolo/cli` (requires Node ≥ 20). To wire the skill + MCP into this agent, run `topolo skills install` (credential-free — the MCP reads the `topolo auth login` credential).
+2. Check credential: `topolo auth status --json`.
+3. For staging work, check credential with `topolo auth status --env staging --json`.
+4. If `source` is `none`, run `topolo auth login` (add `--env staging` for staging) and wait for the user to approve in the browser tab that opens. **No `--client-id` is needed** — the CLI has a built-in first-party client, so any Topolo user can sign in; capabilities are decided by their permissions. (`--client-id=<doac_…>` is only for advanced/self-hosted OAuth clients.) For service-agent / headless installs, use an API key with `topolo auth login --api-key=<key>` or set `TOPOLO_API_KEY` for a single invocation.
+5. Confirm identity once: `topolo whoami --json`. Reference the returned `organization.name` when explaining results to the user.
+6. To act in a different org or personal space: `topolo context ls --json` then `topolo context use <organization-name|personal> --json`. Each context has its own credential; the CLI + MCP run in the active one. This does not change the user's web context, and later web switches do not alter the issued credential.
+
+## Command surface
+
+### Identity
+
+```bash
+topolo whoami --json
+#=> { "user": {...}, "organization": {...}, "kind": "access_token" | "api_key" }
+
+topolo auth status --json
+topolo auth login [--api-key=...] [--client-id=... (advanced)] [--scope="..."]
+topolo auth logout
+```
+
+### Contexts (personal + multiple organizations)
+
+```bash
+topolo context ls --json                                 # personal + your orgs; marks the active one
+topolo context use <organization-name|personal> --json   # switch the active context (validated server-side)
+```
+
+There is no `--org` flag — switch context to act in a different organization. `topolo whoami` reflects the active context.
+The switch is local to the CLI/MCP credential store and its token refresh chain;
+it never changes the shared web preference.
+
+### Application and service discovery
+
+```bash
+topolo apps --json
+topolo apps get <application_id> --json
+topolo apps requirements <application_id> --json
+topolo apps audit <application_id> --json
+topolo services --json
+```
+
+Use `topolo apps` to understand which Topolo application you are dealing with.
+Use `topolo apps requirements` before building so the current platform contract
+is in the agent context.
+Use `topolo services` before `topolo api` so you pass an exact SDK app id
+such as `auth`, `crm`, `mail`, `calendar`, `web`, or `quro.redirect`.
+In staging, `topolo services --env staging --json` also shows
+`environmentSafe`; false means the service still resolves to a production SDK
+URL and the CLI will refuse `topolo api` calls until a staging override is set.
+
+### Credential-scoped actions
+
+```bash
+topolo actions --service mail --json
+topolo actions get app_topolo_mail.messages.send --json
+topolo actions call app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+`topolo actions` is the normal agent entrypoint for application-specific
+operations. It is filtered by the signed-in organization and the exact service
+permissions on the credential. Actions marked `authorizationMode: "runtime"`
+have input-dependent policy and are definitively authorized by the target app
+for the supplied organization, application, and resource at invocation time.
+
+### Generic passthrough
+
+For any endpoint without a typed subcommand:
+
+```bash
+topolo api <service> <GET|POST|PUT|PATCH|DELETE> <path> [--data '<json>'] [--query key=value] [--confirm] --json
+```
+
+- `<path>` begins with `/api/…` (no host).
+- Discover `<service>` with `topolo services --json`.
+- **Mutating methods require `--confirm`**. If omitted, the CLI refuses.
+
+## Write safety — mandatory
+
+Before any mutating call, you MUST:
+
+1. Print the exact method, path, and body you're about to send.
+2. Get explicit user confirmation.
+3. Only then run with `--confirm`.
+
+Do not batch writes. Do not retry a failed write without re-confirming. The `--confirm` flag exists so a mis-generated write fails loudly instead of silently mutating production data.
+
+## Credential handling
+
+- Never commit credentials. If a user shares an API key inline, use it for a single invocation via env var (`TOPOLO_API_KEY=… topolo whoami --json`) rather than writing it anywhere.
+- Prefer `TOPOLO_STAGING_API_KEY`, `TOPOLO_STAGING_ACCESS_TOKEN`, `TOPOLO_PRODUCTION_API_KEY`, or `TOPOLO_PRODUCTION_ACCESS_TOKEN` when a credential is meant for only one environment.
+- The stored config lives at `$XDG_CONFIG_HOME/topolo/config.json` (mode 0600). Don't read or modify it directly — use `topolo auth` commands.
+- Stored OAuth access tokens refresh automatically when the config contains a refresh token and OAuth client id. On `auth_error`, prompt the user to re-run `topolo auth login`.
+
+## Org isolation — do not try to bypass
+
+- There is no `orgId` argument on any command.
+- Do not add org hints to `topolo api` request bodies; the backend rederives org from the credential.
+- If the user asks you to access "another org's data", the correct response is: "I can only act as the signed-in user. Sign in with a credential for that org first."
+
+## Debugging
+
+- `--no-json` gives human-readable output (useful when showing something to the user directly).
+- `TOPOLO_DEBUG=1` writes request/response traces to stderr while keeping JSON stdout clean.
+- Every request carries `X-Topolo-Request-Id`; if the user reports a failure, ask them for the request-id so support can grep logs.
+- If you set `TOPOLO_AGENT_NAME=<yourAgentLabel>` in the shell before running `topolo`, it's recorded in `X-Topolo-Agent` for audit traceability.
+
+## Reference
+
+- Documentation: `https://docs.topolo.app` (guides, authentication, API reference).
+- Developers console (register apps / OAuth clients): `https://developers.topolo.app`
+- CLI README: the `README.md` alongside this file.
+- Schemas: `packages/topolo-sdk/src/modules/` in the monorepo.

package/skills/topolo/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: topolo
+description: Read and write Topolo platform data (identity, application/service discovery, credential-scoped actions, and any SDK-registered Topolo API) from the shell via the `topolo` CLI. Use whenever the user references their Topolo organization, a Topolo app/service, or asks to mint/inspect Topolo credentials.
+---
+
+# Topolo platform
+
+The `topolo` CLI is the agent-friendly entry point to the Topolo platform. Every command runs in the **active context** embedded in the current credential — the user's personal space or a specific organization. You cannot bypass the credential or forge a context; to act in a different organization (or personal), switch with `topolo context use` (see Contexts).
+
+## When this skill fires
+
+Use `topolo` whenever the user:
+
+- References records, messages, customers, or any other data stored in a Topolo app.
+- Asks about their Topolo identity ("who am I logged in as", "what org am I in", "what scopes do I have").
+- Wants to call an endpoint under a Topolo service from the shell.
+- Mentions a Topolo OAuth client (`doac_…`) or API key.
+
+If the user asks a platform question and `topolo` is not installed, install it: `npm install -g @topolo/cli`. Requires Node ≥ 20. To wire this skill and the MCP server into Claude Code / Codex in one step, run `topolo skills install` (copies the skill file, registers the `topolo` MCP; no API key needed — the MCP reads the same credential `topolo auth login` writes).
+
+## Credentials — always check first
+
+Before any data command, confirm a credential is configured:
+
+```bash
+topolo auth status --json
+```
+
+Production is the default environment. Use `--env staging` anywhere in the
+command, or set `TOPOLO_ENV=staging`, when the user is testing internal staging
+or provisioning a staging-only first-party app:
+
+```bash
+topolo auth status --env staging --json
+topolo auth login --env staging
+```
+
+Possible `source` values:
+
+| source | meaning |
+| --- | --- |
+| `env:TOPOLO_STAGING_API_KEY` / `env:TOPOLO_PRODUCTION_API_KEY` | Environment-specific service-scoped API key in env |
+| `env:TOPOLO_STAGING_ACCESS_TOKEN` / `env:TOPOLO_PRODUCTION_ACCESS_TOKEN` | Environment-specific short-lived access token in env |
+| `env:TOPOLO_API_KEY` | Shared service-scoped API key in env |
+| `env:TOPOLO_ACCESS_TOKEN` | Shared short-lived access token in env (dev/testing) |
+| `config-file` | Token stored in the selected environment profile at `$XDG_CONFIG_HOME/topolo/config.json` |
+| `none` | Not signed in — call `topolo auth login` |
+
+If `source: none`, run `topolo auth login` (add `--env staging` for staging) and
+tell the user to approve the device in the browser tab that opens. The CLI uses
+its **built-in first-party client**, so **no `--client-id` is needed** — any
+Topolo user can sign in; what they can then do is decided by their permissions.
+The CLI blocks until they approve, then stores the token in that environment's
+active-context profile. (`--client-id=<doac_…>` is only for advanced/self-hosted
+setups that register their own OAuth client.)
+
+For service-agent / headless installs, use an API key with
+`topolo auth login --api-key=<key>` or set `TOPOLO_API_KEY` only for the single
+command that needs it.
+
+## Output modes
+
+All commands support `--json` (machine) and `--no-json` (human). The CLI autodetects: pretty when stdout is a TTY, JSON when piped. **When you call `topolo` from an agent, always pass `--json`** — the JSON shape is stable; the pretty text is not.
+
+## Command reference
+
+### Identity
+
+```bash
+topolo whoami --json
+```
+
+Returns `{ user: { email, name, role, permissions }, organization: { name, slug } | null, kind }`.
+
+Use this once at the start of a session to confirm the active user + org — then reference that org context in subsequent explanations so the user doesn't have to re-orient.
+
+### Contexts (personal + multiple organizations)
+
+A user can act in their **personal** space or in any **organization** they belong to. Each context has its own credential; the CLI and MCP always operate in the **active** one.
+
+CLI/MCP context is credential-bound and independent from the user's web
+switcher preference. `topolo context use` does not move the browser session;
+switching in the browser does not alter any issued CLI/MCP token or refresh
+chain. Multiple cached personal/org credentials can therefore coexist safely.
+
+```bash
+topolo context ls --json                              # personal + your orgs, and which is active
+topolo context use <organization-name|personal> --json  # switch the active context
+```
+
+`topolo context use` activates a cached context or exchanges the current credential for a fresh token scoped to the target (membership is validated server-side). After switching, `topolo whoami` and every subsequent command run in that context. There is **no `--org` flag** — switch context instead. If a command returns a permission error, the user may need to switch to the org that owns the resource, or be granted access there.
+
+### Application and service discovery
+
+```bash
+topolo apps --json
+topolo apps get <application_id> --json
+topolo apps requirements <application_id> --json
+topolo apps audit <application_id> --json
+topolo services --json
+topolo actions --service <application_id_or_slug> --json
+```
+
+`topolo apps` returns every cataloged Topolo application, including browser-only
+Worker apps that do not expose a callable API. `topolo services` returns every
+SDK-app id with its default and effective URL. In staging, a
+service with `environmentSafe: false` still resolves to a production SDK URL and
+the CLI refuses `topolo api` calls for it until a staging URL override is set.
+`topolo apps requirements` returns the current versioned app-build contract and should be run
+before creating or expanding a Topolo app. `topolo apps audit` returns
+catalog-backed requirement scores and migration work. Run `topolo services`
+before `topolo api` when you are not using a cataloged action.
+
+### Credential-scoped actions
+
+```bash
+topolo actions --service mail --json
+topolo actions get app_topolo_mail.messages.send --json
+topolo actions call app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+`topolo actions` returns the credential-scoped action catalog. Static actions
+are filtered by the current organization and permissions. An action with
+`authorizationMode: "runtime"` has input-dependent policy; it remains
+discoverable, and the target app authorizes the concrete organization,
+application, and resource on every call. Prefer catalog actions over `topolo
+api` when the target app has published a machine contract through Topolo
+Developers. Writes require `--confirm`.
+
+For an app-local workspace or other resource boundary, pass the resource
+separately from the action input. Resource selection is per invocation: it does
+not switch the personal/organization credential context or the browser session.
+
+```bash
+topolo actions call app_topolo_inventory.dashboard.get \
+  --resource-type workspace \
+  --resource-id <workspace_id> \
+  --data '{}' --json
+```
+
+Use a published workspace-list action to discover IDs when the app has multiple
+workspaces. For a single default workspace, use the active organization ID from
+`topolo whoami --json` when that app defines its workspace as the organization
+boundary. Always provide `--resource-type` and `--resource-id` together.
+
+### Generic API passthrough
+
+For any endpoint that doesn't yet have a typed subcommand:
+
+```bash
+topolo api <service> <method> <path> [--data '<json>'] [--query key=value] [--confirm]
+```
+
+- `<service>`: any id from `topolo services --json`.
+- `<method>`: `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
+- `<path>`: starts with `/api/…` — don't include the host.
+- **Mutating calls require `--confirm`**. If you omit it, the CLI refuses and exits non-zero. This is intentional: confirm before sending writes.
+
+Examples:
+
+```bash
+# Read current user via auth service
+topolo api auth GET /api/me --json
+
+# Send mail through a published action (requires confirm)
+topolo actions call app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+## Error handling
+
+Exit codes:
+
+| Code | Meaning | Action |
+| --- | --- | --- |
+| 0 | Success | — |
+| 1 | Generic error | Surface message to user |
+| 2 | Auth error (expired, invalid token) | Run `topolo auth login` and retry |
+| 3 | Permission denied | User's role/scopes lack the capability — point them to the Developers console |
+
+In `--json` mode, errors come on stderr as `{"error":{"message","code","hint","exitCode"}}`. Parse `code` first when branching.
+
+Stored OAuth access tokens refresh automatically when the config contains both a refresh token and the OAuth client id used at login. If `whoami` still returns `auth_error`, have the user re-run `topolo auth login`.
+
+## Safety rules
+
+1. **Never run a mutating `topolo actions call …` or `topolo api … POST|PUT|PATCH|DELETE …` without surfacing the exact body to the user first** and confirming. The `--confirm` flag is a guardrail, not your approval.
+2. **Never write credentials to tracked files.** If a user pastes an API key inline, use it via env var for that invocation (`TOPOLO_API_KEY=… topolo whoami`) rather than committing it.
+3. **Cross-org isolation is built-in** — there is no `--org` flag anywhere, and the backend rederives the org from the credential (it ignores org hints in a request body). To act in a different organization, use `topolo context use <org>` to switch the active context — never try to fake one via the passthrough.
+4. Audit headers (`X-Topolo-Client`, `X-Topolo-Request-Id`, optional `X-Topolo-Agent`) are set by the CLI automatically. If `TOPOLO_AGENT_NAME` is already exported in the user's shell, leave it alone — it's the audit trail.
+
+## Common flows
+
+**"Show me the available Mail actions"**
+```bash
+topolo whoami --json   # confirm org
+topolo actions --service mail --json
+```
+
+**"Send a message through Mail"**
+```bash
+topolo actions call app_topolo_mail.messages.send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+**"What scopes does my CLI token have?"**
+```bash
+topolo whoami --json | jq '.user.permissions'
+```
+
+**"What app id should I use?"**
+```bash
+topolo apps --json
+topolo apps requirements <application_id> --json
+topolo apps audit <application_id> --json
+topolo services --json
+topolo actions --service mail --json
+```
+
+**"Sign me in fresh"**
+```bash
+topolo auth logout
+topolo auth login          # no --client-id needed; approve in the browser
+```
+
+**"Sign me in to staging"**
+```bash
+topolo auth logout --env staging
+topolo auth login --env staging
+topolo whoami --env staging --json
+```
+
+**"Switch to my <Acme> organization" / "work in my personal space"**
+```bash
+topolo context ls --json
+topolo context use acme --json      # or: topolo context use personal
+```
+
+## Where to learn more
+
+- **Topolo documentation:** https://docs.topolo.app — guides (authentication, quick start), API reference, and per-app docs. (Staging: https://docs.stg.topolo.us)
+- Register apps / OAuth clients: the Developers console at https://developers.topolo.app
+- CLI source (for an undocumented flag): `packages/topolo-cli/src/commands/` in the topolo-platform monorepo.
+- SDK package: `packages/topolo-sdk/src/` — authoritative client, dynamic action catalog, and shared response contracts.