@topolo/cli 0.1.32 → 0.1.34

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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": "tsup",

package/skills/codex/AGENTS.md

@@ -0,0 +1,141 @@
+# 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_list_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_list_services` tool to discover callable app ids and effective URLs.
+- Use `topolo actions --json` or MCP dynamic action tools to discover callable operations granted to the current credential.
+- 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).
+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 --client-id=<doac_…>` plus the right `--env` flag and wait for the user to approve in the browser tab that opens. To get a client_id, direct the user to `https://developers.topolo.app/developers/oauth-clients` for production or `https://developers.stg.topolo.us/developers/oauth-clients` for staging and tell them to pick the **CLI / desktop / mobile** tile (that's what enables the device flow). For service-agent 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.
+
+## Command surface
+
+### Identity
+
+```bash
+topolo whoami --json
+#=> { "user": {...}, "organization": {...}, "kind": "access_token" | "api_key" }
+
+topolo auth status --json
+topolo auth login [--client-id=...] [--api-key=...] [--scope="..."]
+topolo auth logout
+```
+
+### 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 --json
+topolo actions --service mail --json
+topolo actions get topolo_mail_messages_send --json
+topolo actions call 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.
+
+### 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
+
+- Dev console (registration, scopes, 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,205 @@
+---
+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 is scoped to the organization embedded in the current credential — you cannot target another org, and you cannot bypass the credential.
+
+## 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.
+
+## 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 --client-id=<doac_…>
+```
+
+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 --client-id=<doac_…>` plus the right
+`--env` flag and tell the user to approve the device in the browser tab that
+opens. The CLI blocks until they approve, then stores the token in that
+environment profile.
+
+If you don't know the client_id, send them to `https://developers.topolo.app/developers/oauth-clients` for production or `https://developers.stg.topolo.us/developers/oauth-clients` for staging. Prefer a **public** (CLI/desktop/mobile) client — that's the tile that enables the device flow.
+
+For service-agent 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.
+
+### 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 --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 --json
+topolo actions --service mail --json
+topolo actions get topolo_mail_messages_send --json
+topolo actions call topolo_mail_messages_send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+`topolo actions` returns the callable action catalog filtered by the current
+credential's organization and permissions. Prefer it over `topolo api` when the
+target app has published a machine action contract through Topolo Developers.
+Writes require `--confirm`.
+
+### 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 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. Don't try to fake one via the passthrough; the backend ignores org hints in the body and rederives org from the credential.
+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 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 --json
+```
+
+**"Sign me in fresh"**
+```bash
+topolo auth logout
+topolo auth login --client-id=<doac_…>
+# Then wait for the user to approve in the browser.
+```
+
+**"Sign me in to staging"**
+```bash
+topolo auth logout --env staging
+topolo auth login --env staging --client-id=<doac_…>
+topolo whoami --env staging --json
+```
+
+## Where to learn more
+
+- Topolo Developers console: https://developers.topolo.app
+- CLI source (for when the user asks about an undocumented flag): `TopoloCli/src/commands/` in the PlatformApplications repo.
+- SDK package: `packages/topolo-sdk/src/` — authoritative client, dynamic action catalog, and shared response contracts.