@oxy-hq/cli 0.2.0 → 0.4.0

package/template/README.md

@@ -17,7 +17,7 @@ Start a session scoped to this customer with:
 | `semantics/topics/` | `*.topic.yml` — question areas: a base view plus the views it may join to. Not one per table. |
 | `pipelines/` | `*.airway.yml` — Airway ELT pipelines. Credentials live in the secret manager, never in the YAML. |
 | `workflows/` | `*.automation.yml` — automations. `.automation.yml` is the canonical extension; `.procedure.yml` is legacy and still accepted, so do not start new files with it. |
-| `apps/` | Custom app bundles (React + Vite, shipped with `oxy publish`). |
+| `apps/` | Custom app bundles (React + Vite, shipped with `oxyc publish`). |
 | `config.yml` | Workspace root config — models, databases, defaults. |
 | `.github/workflows/` | GitHub Actions CI for this repo. Not the same thing as `workflows/` above, which holds oxy automations — the two are one letter of context apart and easy to confuse. |
 | `.github/scripts/` | Shell the workflows call. Kept out of the YAML because a `run:` block can only ever be executed on a runner, while a script can be run — and tested — anywhere. |
@@ -86,7 +86,7 @@ running it against **a real oxy in the cloud** — there is no local warehouse,
 no fixture data, and no local `oxy serve` to point at. From the repo root:
 
 ```bash
-oxy login --env dev      # once per env; opens a browser, caches a token
+oxyc login --env dev     # once per env; opens a browser, caches a token
 pnpm dev --env dev       # starts everything
 ```
 
@@ -97,7 +97,7 @@ stops both together when you press Ctrl-C.
 **`--env` is required, and that is deliberate.** It says which oxy the app
 reads from — `dev`, `staging`, `production`, a full URL
 (`--env https://acme.oxygen-hq.com`), or any name the app's own `oxy-app.json`
-declares under `environments`. The underlying `oxy proxy` defaults to
+declares under `environments`. The underlying `oxyc proxy` defaults to
 **production** if nothing says otherwise, and a `pnpm dev` that quietly serves
 a customer's live data is not something this repo will do. `--env production`
 additionally needs `--yes`.
@@ -113,7 +113,7 @@ pnpm dev --env dev sales-dashboard
 
 | Process | Port | What it is |
 | --- | --- | --- |
-| `oxy proxy --env <env>` | `3000` | Background. Every `/api` call the app makes goes through here, signed with the token `oxy login` cached, and out to the cloud. It stands in for a local `oxy serve`, which is why the port is not configurable — the Vite plugin already proxies `/api` to `3000`. |
+| `oxyc proxy --env <env>` | `3000` | Background. Every `/api` call the app makes goes through here, signed with the token `oxyc login` cached, and out to the cloud. It stands in for a local `oxy serve`, which is why the port is not configurable — the Vite plugin already proxies `/api` to `3000`. Each Oxy Function call prints a `↳ <status> fn <name>  request_id=…  trace_id=…` line — the ids to look up when one fails. |
 | `pnpm dev` in the app | `5173` | Foreground. Vite, with hot reload. **This is the URL you open**: <http://localhost:5173>. |
 
 Ctrl-C stops both, and it always returns: a proxy that ignores the polite
@@ -139,9 +139,11 @@ that an afternoon of local clicking cannot change what the customer sees:
 ### If something is wrong
 
 - **Requests come back 401** — the cached token for that env has expired.
-  `oxy login --env <env>` again.
-- **`the 'oxy' CLI is not on your PATH`** — install it with
-  `curl -sSfL https://get.oxy.tech | bash`; it lands in `~/.local/bin`.
+  `oxyc login --env <env>` again.
+- **`the 'oxyc' CLI is not on your PATH`** — install it with
+  `npm install -g @oxy-hq/cli`. A global install, not `npx`: Ctrl-C stops the
+  proxy by pid, and a wrapper process in between keeps the signal from reaching
+  it.
 - **`this repo has no custom apps yet`** — expected on a fresh repo, and it is
   not an error. The message says how to add one.
 - **A change to `apps/` does not show up** — Vite serves the app, but the data
@@ -160,8 +162,8 @@ a long-lived credential sitting in it.
 From the app's own directory under `apps/`:
 
 ```bash
-oxy login --env dev        # once per env; opens a browser, caches a token
-oxy publish --env dev      # a draft, to the dev environment
+oxyc login --env dev       # once per env; opens a browser, caches a token
+oxyc publish --env dev     # a draft, to the dev environment
 ```
 
 `--env` is not optional in practice. The CLI defaults it to **production**, so
@@ -212,14 +214,14 @@ opted in.
 ### Where an opted-in CI publishes
 
 `.github/workflows/publish.yaml` builds every bundle under `apps/` and ships
-it with `oxy publish`. It runs on a push to `main` that touches `apps/`, the
+it with `oxyc publish`. It runs on a push to `main` that touches `apps/`, the
 lockfile, or the workflow itself, and it can be run by hand from the Actions
 tab.
 
 **Where it publishes is decided by how it was triggered, and it is always
 said out loud:**
 
-| Trigger | Event | `oxy publish --env` | Channel | Reviewers |
+| Trigger | Event | `oxyc publish --env` | Channel | Reviewers |
 | --- | --- | --- | --- | --- |
 | push to `main` | `push` | `dev` | draft | none |
 | Actions tab (**Run workflow**) | `workflow_dispatch` | `production` | draft, or live with **Promote** | whatever `production` requires |
@@ -231,7 +233,7 @@ by `customer-tooling`'s own suite.
 
 That mapping lives in `.github/scripts/publish-env.sh`, and a trigger it has
 no entry for **fails the run** rather than picking one. The reason is worth
-knowing, because it was a live bug in this workflow: `oxy publish` defaults
+knowing, because it was a live bug in this workflow: `oxyc publish` defaults
 `--env` to **production**, so an invocation that leaves the flag off does not
 publish "nowhere in particular" — it publishes at the customer's live
 environment. Every publish here names its environment explicitly, and there
@@ -250,7 +252,7 @@ tidiness one. `build` runs `pnpm install` and `pnpm -r build` — which is to
 say it executes the postinstall and build scripts of every dependency your
 apps pull in — and holds no publish credential at all. It hands the built
 output to `publish` as a workflow artifact. `publish` holds `OXY_TOKEN`, and
-runs no package script: `oxy publish --dir` uploads a pre-built directory
+runs no package script: `oxyc publish --dir` uploads a pre-built directory
 as-is instead of building anything. So a compromised dependency in an app's
 tree never runs on a runner where the token exists.
 
@@ -325,8 +327,8 @@ worth knowing exactly what the two ways of doing it are:
   reviewed a draft and want that exact bundle live, this is the one you want.
 - **The Actions tab**, running this workflow with a **Ref** and **Promote**
   ticked, **rebuilds that ref and publishes the result live**. It does not
-  promote an existing draft — no command in the `oxy` CLI can, so the
-  workflow cannot either. If `main` has moved since the draft you reviewed,
+  promote an existing draft — `oxyc publish` cannot, so the workflow cannot
+  either. If `main` has moved since the draft you reviewed,
   this ships the newer commit, under a new build id.
 
 That is why the ref is an explicit, required input rather than something the

package/template/_gitignore

@@ -15,7 +15,7 @@
 # committed.
 node_modules/
 
-# Build output. `out/` is oxy publish's default outDir; `dist/` and `build/`
+# Build output. `out/` is oxyc publish's default outDir; `dist/` and `build/`
 # are what a Vite or Next app writes when its oxy-app.json names one instead.
 out/
 dist/

package/template/scripts/dev.sh

@@ -6,9 +6,9 @@
 # why this file exists at all. Before it, running an app locally needed three
 # commands in two terminals and knowledge that was written down nowhere:
 #
-#   oxy proxy --env <env>     background, listens on :3000. Forwards the app's
+#   oxyc proxy --env <env>    background, listens on :3000. Forwards the app's
 #                             /api calls to the cloud, signed with the token
-#                             `oxy login --env <env>` cached.
+#                             `oxyc login --env <env>` cached.
 #   pnpm dev  (in the app)    foreground, Vite on :5173, which proxies /api to
 #                             :3000. That target is the Vite plugin's default,
 #                             so the proxy's port is not really negotiable —
@@ -36,7 +36,7 @@ root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 # that also uses it looks for it.
 DISCOVER="$root/.github/scripts/discover-apps.sh"
 
-# `oxy proxy`'s own default, and what @oxy-hq/vite-plugin proxies /api to.
+# `oxyc proxy`'s own default, and what @oxy-hq/vite-plugin proxies /api to.
 PROXY_PORT=3000
 # Vite's default. Printed, never bound by this script.
 DEV_PORT=5173
@@ -60,7 +60,7 @@ Run one of this repo's custom apps locally, against a cloud oxy's real data.
   pnpm dev --env <env> [app] [--allow-writes] [--allow-events] [--yes]
 
   --env <env>     REQUIRED. Which oxy to proxy to. There is deliberately no
-                  default: \`oxy proxy\`'s own default is production, and a
+                  default: \`oxyc proxy\`'s own default is production, and a
                   \`pnpm dev\` that silently reads production is not something
                   this repo will do. One of:
                     dev  staging  production
@@ -73,7 +73,7 @@ Run one of this repo's custom apps locally, against a cloud oxy's real data.
   --yes           Confirm that --env production is really what you meant.
   -h, --help      This text.
 
-First run, once per env:  oxy login --env <env>
+First run, once per env:  oxyc login --env <env>
 EOF
 }
 
@@ -315,13 +315,13 @@ if [ -z "$env_name" ]; then
       "a full URL (--env https://acme.oxygen-hq.com), or a name the app's" \
       "oxy-app.json declares under \"environments\"." \
       "" \
-      "There is no default on purpose. 'oxy proxy' defaults to PRODUCTION, and" \
+      "There is no default on purpose. 'oxyc proxy' defaults to PRODUCTION, and" \
       "a 'pnpm dev' that silently serves production data is not a thing this" \
       "repo will do quietly."
 fi
 
 if [ "$env_name" = "production" ] && [ "$confirm_yes" -ne 1 ]; then
-  # `oxy proxy` refuses a production target without --yes on its own. Catching
+  # `oxyc proxy` refuses a production target without --yes on its own. Catching
   # it here matters because the proxy runs in the BACKGROUND: its refusal (or
   # its prompt) would scroll past under Vite's banner, and the app would just
   # fail every request with nothing on screen explaining why.
@@ -335,12 +335,13 @@ fi
 
 # --- preconditions ----------------------------------------------------------
 
-if ! command -v oxy >/dev/null 2>&1; then
-  die "the 'oxy' CLI is not on your PATH, and the proxy is oxy." \
+if ! command -v oxyc >/dev/null 2>&1; then
+  die "the 'oxyc' CLI is not on your PATH, and the proxy is oxyc." \
       "" \
-      "  curl -sSfL https://get.oxy.tech | bash" \
+      "  npm install -g @oxy-hq/cli" \
       "" \
-      "It installs to ~/.local/bin; add that to PATH if it is not already there."
+      "A global install, not npx: the proxy is killed by pid on Ctrl-C, and a" \
+      "wrapper process in between would keep the signal from reaching it."
 fi
 
 if ! command -v pnpm >/dev/null 2>&1; then
@@ -371,7 +372,7 @@ read_port_holder "$PROXY_PORT"
 if [ -n "$port_holder" ]; then
   die "port $PROXY_PORT is already taken by: $port_holder" \
       "" \
-      "'oxy proxy' has to listen there — the app's dev server proxies /api to" \
+      "'oxyc proxy' has to listen there — the app's dev server proxies /api to" \
       "that exact port — so this cannot just move out of the way. Usually it is" \
       "a proxy from an earlier run that outlived its terminal, or a local" \
       "'oxy serve'. Stop it and try again:" \
@@ -389,7 +390,7 @@ if [ "$confirm_yes" -eq 1 ]; then proxy_args+=(--yes); fi
 say "" \
     "  app     $app_dir" \
     "  env     $env_name" \
-    "  proxy   oxy ${proxy_args[*]}   ->  http://localhost:$PROXY_PORT" \
+    "  proxy   oxyc ${proxy_args[*]}   ->  http://localhost:$PROXY_PORT" \
     "  dev     pnpm dev in $app_dir   ->  http://localhost:$DEV_PORT" \
     ""
 
@@ -410,23 +411,26 @@ else
   say "  Tracking events are DROPPED, so local clicking never shows up in the" \
       "  customer's analytics. Pass --allow-events to forward them."
 fi
-say "" "  Ctrl-C stops both. If requests come back 401, run: oxy login --env $env_name" ""
+say "" "  Ctrl-C stops both. If requests come back 401, run: oxyc login --env $env_name" ""
 
-oxy "${proxy_args[@]}" &
+oxyc "${proxy_args[@]}" &
 proxy_pid=$!
 
-# A proxy that dies on the first second — no cached token, a bad --env — would
+# A proxy that dies on the first second — a bad --env, a production host
+# without --yes — would
 # otherwise leave Vite up and every request failing, with the reason scrolled
 # off the top. One second is enough to catch the immediate exits and cannot
 # produce a false alarm: a proxy still running after it is simply left alone.
 sleep 1
 if process_finished "$proxy_pid"; then
   proxy_pid=""
-  die "'oxy proxy --env $env_name' exited immediately — see its output above." \
+  die "'oxyc proxy --env $env_name' exited immediately — see its output above." \
       "" \
-      "Most often there is no cached token for that env yet:" \
+      "Most often --env did not resolve to a deployment, or it names a" \
+      "production host (an org URL under oxygen-hq.com) and needs --yes." \
+      "If it did start but every request is a 401, cache a token for it:" \
       "" \
-      "  oxy login --env $env_name"
+      "  oxyc login --env $env_name"
 fi
 
 # The dev server, in the foreground, and the LAST statement in this file.

package/dist/mcp-VdontkUr.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-VdontkUr.mjs","names":[],"sources":["../src/commands/mcp.ts"],"sourcesContent":["/**\n * `oxyc mcp` — the Oxy API as MCP tools, over stdio.\n *\n * NOT THE SAME THING AS `oxy mcp`. That one is workspace tooling: it takes a\n * local checkout and exposes the semantic model, automations and `.sql` files\n * in it. This one takes a TOKEN and exposes the deployment's HTTP API — the\n * same surface `oxyc api` reaches, for an agent that would rather call a tool\n * than shell out. Different input, different audience, no overlap.\n *\n * FOUR TOOLS, NOT SIX HUNDRED — the design decision that makes this affordable.\n *\n * The obvious shape is one tool per endpoint, and it is the wrong one: the API\n * has ~670 routes, an agent runtime ships every tool's JSON schema in every\n * request, and that is tens of kilobytes of context spent on each turn before\n * a single question is asked. It would also go stale on every deploy, since\n * the tool list would be baked into this package rather than read from the\n * deployment.\n *\n * So discovery stays a QUESTION the agent asks (`routes`, `schema`) rather\n * than a payload it carries, exactly as the CLI does it. Four tools cost a few\n * hundred bytes per turn and reach every endpoint, including ones added after\n * this package was published.\n *\n * Auth, target resolution and placeholder substitution are the CLI's — the\n * same `Context`, so a token cached by `oxyc login` (or `oxy login`) works\n * here with no separate setup, and `{org}` / `{workspace}` resolve the same\n * way.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport { loadCatalog, loadOpenApi, searchRoutes } from \"../api/catalog.js\";\nimport { paramsToQuery, parseFields } from \"../api/fields.js\";\nimport { runJq } from \"../api/output.js\";\nimport { isExternalSurface, normalizePath, substitutePlaceholders } from \"../api/paths.js\";\nimport { parseJson, request } from \"../api/request.js\";\nimport type { Context } from \"../context/resolve.js\";\nimport { CliError, ExitCode } from \"../util/errors.js\";\nimport { comparablePath } from \"./discover.js\";\n\n/**\n * Package version, reported in the MCP handshake.\n *\n * Read from `package.json` rather than restated, so a release bump cannot\n * leave the server announcing a version nobody shipped.\n */\nconst VERSION: string = (() => {\n  try {\n    const here = dirname(fileURLToPath(import.meta.url));\n    for (const candidate of [\n      resolve(here, \"..\", \"package.json\"),\n      resolve(here, \"..\", \"..\", \"package.json\")\n    ]) {\n      if (existsSync(candidate)) {\n        return (\n          (JSON.parse(readFileSync(candidate, \"utf8\")) as { version?: string }).version ?? \"0.0.0\"\n        );\n      }\n    }\n  } catch {\n    // A packaging shape we did not anticipate. The handshake needs a string,\n    // not an accurate one.\n  }\n  return \"0.0.0\";\n})();\n\n/**\n * A tool result. MCP wants content blocks; everything here is text, because\n * the caller is a language model and the payloads are JSON or markdown.\n */\nfunction text(body: string, isError = false) {\n  return { content: [{ type: \"text\" as const, text: body }], isError };\n}\n\nconst TOOLS = [\n  {\n    name: \"oxy_routes\",\n    description:\n      \"List the API endpoints this Oxy deployment mounts, with what each one does. \" +\n      \"ALWAYS call this before oxy_request rather than guessing a path. \" +\n      \"Pass a filter (matched against method, path, surface and description) to narrow it — \" +\n      \"unfiltered is ~670 routes. Above 60 matches the descriptions are dropped and only \" +\n      \"method, path and credential come back, so narrow enough to stay under that when you \" +\n      \"need to know what an endpoint does; past ~400 it is refused outright.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        filter: {\n          type: \"string\",\n          description: \"Substring to narrow by, e.g. 'threads', 'sql', 'admin', 'semantic'.\"\n        },\n        all: {\n          type: \"boolean\",\n          description:\n            \"Include ide-only and worker-only routes. Off by default: those are mounted on one \" +\n            \"instance of the fleet, so a caller hitting the load balancer cannot reach them directly.\"\n        }\n      }\n    }\n  },\n  {\n    name: \"oxy_schema\",\n    description:\n      \"The request and response schema for ONE endpoint, so a body can be built correctly. \" +\n      \"Covers the data plane (SQL, semantic query, and the org/workspace lookups); a blank \" +\n      \"result means undocumented, not nonexistent — use oxy_routes to confirm the endpoint exists.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        path: { type: \"string\", description: \"Endpoint path, e.g. '{workspace}/sql/query'.\" },\n        method: { type: \"string\", description: \"Narrow to one HTTP method.\" }\n      },\n      required: [\"path\"]\n    }\n  },\n  {\n    name: \"oxy_request\",\n    description:\n      \"Make an authenticated request to the Oxy API. The credential is picked from the path \" +\n      \"(/api/** takes a bearer, /external/api/** an API key). Placeholders {org}, {workspace}, \" +\n      \"{project}, {customer} and {me} are substituted from context. \" +\n      \"Read freely; ask the human before any mutating request against production.\",\n    inputSchema: {\n      type: \"object\",\n      properties: {\n        path: { type: \"string\", description: \"Path relative to /api, e.g. '{org}/workspaces'.\" },\n        method: {\n          type: \"string\",\n          description: \"HTTP method. Defaults to GET, or POST with fields.\"\n        },\n        fields: {\n          type: \"object\",\n          description:\n            \"Request parameters. Sent as a JSON body on POST/PUT/PATCH, or as query parameters \" +\n            \"on GET/HEAD/DELETE. Values keep their JSON type.\"\n        },\n        jq: {\n          type: \"string\",\n          description:\n            \"A jq program to reduce the response before it is returned. Use it — a full list \" +\n            \"response is far more context than the two fields you need.\"\n        }\n      },\n      required: [\"path\"]\n    }\n  },\n  {\n    name: \"oxy_whoami\",\n    description:\n      \"Which deployment this is pointed at and who the token belongs to. \" +\n      \"Use it when a call returns 401/403, or a 200 with a null body — on this API an expired \" +\n      \"session answers 200 null rather than 401, and this tells the two apart.\",\n    inputSchema: { type: \"object\", properties: {} }\n  }\n];\n\n/**\n * Above this many matches, `oxy_routes` drops the descriptions.\n *\n * DEGRADES, IT DOES NOT REFUSE — the same shape as `oxyc routes`, which picks\n * `renderDetailed` under 40 matches and the compact method+path table above it\n * (`discover.ts`). The expensive field is `description`, not the row: a trimmed\n * row is a few tens of bytes, so several hundred still fit in a result an agent\n * can read, while the descriptions are what turn a broad match into hundreds of\n * KB of context spent before a question is asked.\n *\n * The threshold is on the COUNT, not on whether a `filter` was supplied — a\n * filter is not evidence of narrowing. `searchRoutes` matches a substring of\n * method, path, surface or description, so `\"admin\"`, `\"workspace\"` and\n * `\"query\"` are all filters a model reaches for in good faith that clear this.\n */\nconst MAX_DESCRIBED_ROUTES = 60;\n\n/**\n * And above THIS many, there is nothing useful to return at all.\n *\n * Deliberately far above the threshold that drops descriptions: refusing is the\n * answer only when even the trimmed listing would be a context dump, which for\n * a deployment of ~670 routes means \"you asked for effectively all of them\".\n */\nconst MAX_ROUTES_PER_RESULT = 400;\n\n/** `{ a: 1 }` → the `-f`/`-F` pairs `parseFields` understands. */\nfunction fieldPairs(fields: Record<string, unknown> | undefined): string[] {\n  if (!fields) return [];\n  return Object.entries(fields).map(([k, v]) => `${k}=${JSON.stringify(v)}`);\n}\n\n/**\n * Check the arguments the schema says are required.\n *\n * `inputSchema.required` is ADVISORY on the low-level `Server` — it is handed\n * to the model, not enforced by the transport. Without this, `oxy_schema` with\n * no `path` matched every path and returned the whole OpenAPI document, and\n * `oxy_request` with none built a request to `/api/`.\n */\nfunction requireArgs(name: string, args: Record<string, unknown>, required: string[]): void {\n  const missing = required.filter((k) => {\n    const v = args[k];\n    return v === undefined || v === null || (typeof v === \"string\" && v.trim() === \"\");\n  });\n  if (missing.length > 0) {\n    throw new CliError(`${name} needs ${missing.join(\", \")}`, { code: ExitCode.USAGE });\n  }\n}\n\nasync function callTool(ctx: Context, name: string, args: Record<string, unknown>) {\n  switch (name) {\n    case \"oxy_routes\": {\n      const catalog = await loadCatalog({ target: ctx.target(), bearer: ctx.maybeBearer() });\n      const filter = (args.filter as string | undefined)?.trim();\n      let matches = searchRoutes(catalog, filter || undefined);\n      if (!args.all) matches = matches.filter((r) => r.role === \"fleet-ok\");\n\n      // A cache stale enough to be wrong is worth saying INSIDE the result:\n      // `loadCatalog` warns on stderr, which an MCP client never shows anyone.\n      const staleNote = catalog.stale\n        ? \"NOTE: this route table came from a stale local cache; the deployment was unreachable.\\n\\n\"\n        : \"\";\n\n      const asked = filter ? ` ${JSON.stringify(filter)}` : \"\";\n\n      // Only a match set too large even to LIST is refused. Below that the\n      // result degrades instead, because a filter like \"admin\" or \"query\" can\n      // clear the description threshold in good faith and \"guess something\n      // narrower\" is a dead end for a model with no way to see what it hit.\n      if (matches.length > MAX_ROUTES_PER_RESULT) {\n        return text(\n          `${staleNote}${matches.length} routes match${asked}, which is effectively the whole ` +\n            `deployment. Call oxy_routes again with a narrower \\`filter\\` (matched against ` +\n            `method, path, surface and description), e.g. \"threads\", \"sql\", \"semantic\", \"admin\".`,\n          true\n        );\n      }\n\n      if (matches.length === 0) {\n        // An empty array reads as \"this deployment has no such endpoint\",\n        // which is usually false — the filter was wrong, or the route is\n        // ide-only and hidden by default.\n        return text(\n          `${staleNote}No route matches ${JSON.stringify(filter ?? \"\")}. Try a broader filter, ` +\n            `or pass all=true to include ide-only and worker-only mounts.`,\n          true\n        );\n      }\n      // Trimmed to the fields that help a caller build a request. The full\n      // record carries the handler path and mount notes, which are for a\n      // maintainer reading source, not for an agent composing a call.\n      const described = matches.length <= MAX_DESCRIBED_ROUTES;\n      // `credential` SURVIVES THE TRIM. It is what separates the bearer mount\n      // from the `/external/api` API-key one, so a caller composing a request\n      // needs it in either form — and `renderCompact`, the CLI shape this\n      // mirrors, keeps it as a per-surface heading. It is also not the\n      // expensive field: ~25 bytes a row, ~10 KB across the whole ceiling,\n      // against descriptions that run to hundreds of KB.\n      const trimmed = matches.map((r) =>\n        described\n          ? { method: r.method, path: r.path, credential: r.credential, description: r.description }\n          : { method: r.method, path: r.path, credential: r.credential }\n      );\n      // The note says the listing is trimmed AND how to get the descriptions\n      // back. Without it a model reads a description-less row as an endpoint\n      // that has no documentation, rather than one it did not ask narrowly\n      // enough to see.\n      const trimNote = described\n        ? \"\"\n        : `NOTE: ${matches.length} routes match${asked} — too many to describe, so each row is ` +\n          `method, path and credential WITHOUT its description. Narrow the \\`filter\\` to ` +\n          `${MAX_DESCRIBED_ROUTES} or fewer matches to get the descriptions back.\\n\\n`;\n      return text(`${staleNote}${trimNote}${JSON.stringify(trimmed)}`);\n    }\n\n    case \"oxy_schema\": {\n      requireArgs(\"oxy_schema\", args, [\"path\"]);\n      const doc = (await loadOpenApi({ target: ctx.target(), bearer: ctx.maybeBearer() })) as {\n        paths?: Record<string, Record<string, unknown>>;\n        components?: unknown;\n      };\n      const wanted = String(args.path ?? \"\");\n      const method = args.method as string | undefined;\n      // `comparablePath` is imported from `discover.ts` rather than copied:\n      // a second reduction of the same two spellings is a second thing to keep\n      // in step, and the copy here was untested. Exact first, then substring —\n      // the order `runSchema` uses, so the two commands answer alike.\n      const paths = Object.entries(doc.paths ?? {});\n      const exact = paths.filter(([p]) => comparablePath(p) === comparablePath(wanted));\n      const hit =\n        exact.length > 0\n          ? exact\n          : paths.filter(([p]) => comparablePath(p).includes(comparablePath(wanted)));\n      if (hit.length === 0) {\n        return text(\n          `No documented schema for ${wanted}. The OpenAPI document covers the data plane only — ` +\n            `call oxy_routes with a filter to confirm the endpoint exists.`,\n          true\n        );\n      }\n      const selected = Object.fromEntries(\n        hit.map(([p, ops]) => [\n          p,\n          method\n            ? Object.fromEntries(\n                Object.entries(ops).filter(([verb]) => verb.toLowerCase() === method.toLowerCase())\n              )\n            : ops\n        ])\n      );\n      return text(JSON.stringify({ paths: selected, components: doc.components }, null, 2));\n    }\n\n    case \"oxy_request\": {\n      requireArgs(\"oxy_request\", args, [\"path\"]);\n      const raw = String(args.path ?? \"\");\n      const method = String(args.method ?? \"\").toUpperCase() || undefined;\n      const fields = parseFields([], fieldPairs(args.fields as Record<string, unknown>));\n      const verb = method ?? (fields.present ? \"POST\" : \"GET\");\n      const carriesBody = ![\"GET\", \"HEAD\", \"DELETE\"].includes(verb);\n\n      let path = substitutePlaceholders(normalizePath(raw), ctx.placeholders());\n      let body: string | undefined;\n      if (fields.present) {\n        if (carriesBody) body = JSON.stringify(fields.params);\n        else {\n          const query = paramsToQuery(fields.params);\n          if (query) path += (path.includes(\"?\") ? \"&\" : \"?\") + query;\n        }\n      }\n\n      const apiKey = ctx.apiKey();\n      const external = isExternalSurface(path);\n      const response = await request({\n        target: ctx.target(),\n        path,\n        method: verb,\n        body,\n        bearer: external && apiKey ? ctx.maybeBearer() : ctx.bearer(),\n        apiKey\n      });\n\n      if (response.status < 200 || response.status >= 300) {\n        // The STATUS and the body, not a thrown error: the model can act on\n        // \"403, here is what the server said\" and cannot act on a transport\n        // exception. It is marked `isError` so the runtime shows it as one.\n        return text(`HTTP ${response.status} ${response.statusText}\\n${response.body}`, true);\n      }\n\n      if (response.body.trim() === \"null\") {\n        return text(\n          \"null\\n\\n(NOTE: a 200 with a null body can mean an expired session on this API, \" +\n            \"not 'no such thing'. Call oxy_whoami to tell them apart.)\"\n        );\n      }\n\n      const jq = args.jq as string | undefined;\n      if (jq) return text(runJq(response.body, jq));\n      return text(response.body);\n    }\n\n    case \"oxy_whoami\": {\n      const target = ctx.target();\n      const response = await request({\n        target,\n        path: \"/api/user\",\n        method: \"GET\",\n        bearer: ctx.bearer()\n      });\n      const payload = parseJson(response.body);\n      if (payload === null || payload === undefined) {\n        return text(\n          `target: ${target}\\nThe token no longer resolves to a user — the session has expired. ` +\n            `Ask the human to run \\`oxyc login\\`.`,\n          true\n        );\n      }\n      return text(JSON.stringify({ target, user: payload }, null, 2));\n    }\n\n    default:\n      return text(`unknown tool: ${name}`, true);\n  }\n}\n\n/**\n * Serve MCP on stdio until the client disconnects.\n *\n * STDIO IS THE WHOLE TRANSPORT, deliberately. An HTTP/SSE server would need a\n * port, a lifetime and an auth story of its own; stdio is what every agent\n * runtime already launches, and the process inherits the caller's environment\n * — which is where the token and the target come from.\n *\n * NOTHING MAY BE WRITTEN TO STDOUT except protocol frames. `log.info` and\n * friends already go to stderr, which is why this can share the CLI's own\n * plumbing without corrupting the stream.\n */\nexport async function runMcp(ctx: Context): Promise<void> {\n  const server = new Server({ name: \"oxyc\", version: VERSION }, { capabilities: { tools: {} } });\n\n  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));\n\n  server.setRequestHandler(CallToolRequestSchema, async (req) => {\n    try {\n      return await callTool(\n        ctx,\n        req.params.name,\n        (req.params.arguments ?? {}) as Record<string, unknown>\n      );\n    } catch (cause) {\n      // A throw here would kill the session. The model can act on a message;\n      // it cannot act on a dead transport.\n      const message = (cause as Error).message ?? String(cause);\n      // BOTH CHANNELS. A model gets one string, so there is no marker to\n      // distinguish them — but reading `hint` alone drops the one line that\n      // says what to DO, which is the half a model can act on.\n      const { hint, remedy } = cause as { hint?: string; remedy?: string };\n      // Blank line between them, the way every other renderer of these two\n      // separates them — a model given two consecutive imperatives with no\n      // boundary loses the distinction the second field exists to make.\n      // `!== undefined` for the narrowing TS gives it, and a length check\n      // because an empty string would open the block with a blank line —\n      // `filter(Boolean)` covered that and cost the narrowing, so both.\n      const extra = [hint, remedy].filter((line) => line !== undefined && line !== \"\").join(\"\\n\\n\");\n      return text(extra ? `${message}\\n\\n${extra}` : message, true);\n    }\n  });\n\n  await server.connect(new StdioServerTransport());\n\n  // `connect` returns once the transport is wired; the process must stay up\n  // until the client closes stdin.\n  await new Promise<void>((resolve) => {\n    process.stdin.on(\"close\", resolve);\n    server.onclose = resolve;\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,MAAM,iBAAyB;CAC7B,IAAI;EACF,MAAM,OAAO,QAAQ,cAAc,YAAY,GAAG,CAAC;EACnD,KAAK,MAAM,aAAa,CACtB,QAAQ,MAAM,MAAM,cAAc,GAClC,QAAQ,MAAM,MAAM,MAAM,cAAc,CAC1C,GACE,IAAI,WAAW,SAAS,GACtB,OACG,KAAK,MAAM,aAAa,WAAW,MAAM,CAAC,CAAC,CAA0B,WAAW;CAIzF,QAAQ,CAGR;CACA,OAAO;AACT,EAAC,CAAE;;;;;AAMH,SAAS,KAAK,MAAc,UAAU,OAAO;CAC3C,OAAO;EAAE,SAAS,CAAC;GAAE,MAAM;GAAiB,MAAM;EAAK,CAAC;EAAG;CAAQ;AACrE;AAEA,MAAM,QAAQ;CACZ;EACE,MAAM;EACN,aACE;EAMF,aAAa;GACX,MAAM;GACN,YAAY;IACV,QAAQ;KACN,MAAM;KACN,aAAa;IACf;IACA,KAAK;KACH,MAAM;KACN,aACE;IAEJ;GACF;EACF;CACF;CACA;EACE,MAAM;EACN,aACE;EAGF,aAAa;GACX,MAAM;GACN,YAAY;IACV,MAAM;KAAE,MAAM;KAAU,aAAa;IAA+C;IACpF,QAAQ;KAAE,MAAM;KAAU,aAAa;IAA6B;GACtE;GACA,UAAU,CAAC,MAAM;EACnB;CACF;CACA;EACE,MAAM;EACN,aACE;EAIF,aAAa;GACX,MAAM;GACN,YAAY;IACV,MAAM;KAAE,MAAM;KAAU,aAAa;IAAkD;IACvF,QAAQ;KACN,MAAM;KACN,aAAa;IACf;IACA,QAAQ;KACN,MAAM;KACN,aACE;IAEJ;IACA,IAAI;KACF,MAAM;KACN,aACE;IAEJ;GACF;GACA,UAAU,CAAC,MAAM;EACnB;CACF;CACA;EACE,MAAM;EACN,aACE;EAGF,aAAa;GAAE,MAAM;GAAU,YAAY,CAAC;EAAE;CAChD;AACF;;;;;;;;;;;;;;;;AAiBA,MAAM,uBAAuB;;;;;;;;AAS7B,MAAM,wBAAwB;;AAG9B,SAAS,WAAW,QAAuD;CACzE,IAAI,CAAC,QAAQ,OAAO,CAAC;CACrB,OAAO,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,EAAE,GAAG,KAAK,UAAU,CAAC,GAAG;AAC3E;;;;;;;;;AAUA,SAAS,YAAY,MAAc,MAA+B,UAA0B;CAC1F,MAAM,UAAU,SAAS,QAAQ,MAAM;EACrC,MAAM,IAAI,KAAK;EACf,OAAO,MAAM,UAAa,MAAM,QAAS,OAAO,MAAM,YAAY,EAAE,KAAK,MAAM;CACjF,CAAC;CACD,IAAI,QAAQ,SAAS,GACnB,MAAM,IAAI,SAAS,GAAG,KAAK,SAAS,QAAQ,KAAK,IAAI,KAAK,EAAE,MAAM,SAAS,MAAM,CAAC;AAEtF;AAEA,eAAe,SAAS,KAAc,MAAc,MAA+B;CACjF,QAAQ,MAAR;EACE,KAAK,cAAc;GACjB,MAAM,UAAU,MAAM,YAAY;IAAE,QAAQ,IAAI,OAAO;IAAG,QAAQ,IAAI,YAAY;GAAE,CAAC;GACrF,MAAM,SAAU,KAAK,QAA+B,KAAK;GACzD,IAAI,UAAU,aAAa,SAAS,UAAU,MAAS;GACvD,IAAI,CAAC,KAAK,KAAK,UAAU,QAAQ,QAAQ,MAAM,EAAE,SAAS,UAAU;GAIpE,MAAM,YAAY,QAAQ,QACtB,8FACA;GAEJ,MAAM,QAAQ,SAAS,IAAI,KAAK,UAAU,MAAM,MAAM;GAMtD,IAAI,QAAQ,SAAS,uBACnB,OAAO,KACL,GAAG,YAAY,QAAQ,OAAO,eAAe,MAAM,qMAGnD,IACF;GAGF,IAAI,QAAQ,WAAW,GAIrB,OAAO,KACL,GAAG,UAAU,mBAAmB,KAAK,UAAU,UAAU,EAAE,EAAE,uFAE7D,IACF;GAKF,MAAM,YAAY,QAAQ,UAAU;GAOpC,MAAM,UAAU,QAAQ,KAAK,MAC3B,YACI;IAAE,QAAQ,EAAE;IAAQ,MAAM,EAAE;IAAM,YAAY,EAAE;IAAY,aAAa,EAAE;GAAY,IACvF;IAAE,QAAQ,EAAE;IAAQ,MAAM,EAAE;IAAM,YAAY,EAAE;GAAW,CACjE;GAUA,OAAO,KAAK,GAAG,YALE,YACb,KACA,SAAS,QAAQ,OAAO,eAAe,MAAM,wHAE1C,qBAAqB,uDACU,KAAK,UAAU,OAAO,GAAG;EACjE;EAEA,KAAK,cAAc;GACjB,YAAY,cAAc,MAAM,CAAC,MAAM,CAAC;GACxC,MAAM,MAAO,MAAM,YAAY;IAAE,QAAQ,IAAI,OAAO;IAAG,QAAQ,IAAI,YAAY;GAAE,CAAC;GAIlF,MAAM,SAAS,OAAO,KAAK,QAAQ,EAAE;GACrC,MAAM,SAAS,KAAK;GAKpB,MAAM,QAAQ,OAAO,QAAQ,IAAI,SAAS,CAAC,CAAC;GAC5C,MAAM,QAAQ,MAAM,QAAQ,CAAC,OAAO,eAAe,CAAC,MAAM,eAAe,MAAM,CAAC;GAChF,MAAM,MACJ,MAAM,SAAS,IACX,QACA,MAAM,QAAQ,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,SAAS,eAAe,MAAM,CAAC,CAAC;GAC9E,IAAI,IAAI,WAAW,GACjB,OAAO,KACL,4BAA4B,OAAO,oHAEnC,IACF;GAEF,MAAM,WAAW,OAAO,YACtB,IAAI,KAAK,CAAC,GAAG,SAAS,CACpB,GACA,SACI,OAAO,YACL,OAAO,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,UAAU,KAAK,YAAY,MAAM,OAAO,YAAY,CAAC,CACpF,IACA,GACN,CAAC,CACH;GACA,OAAO,KAAK,KAAK,UAAU;IAAE,OAAO;IAAU,YAAY,IAAI;GAAW,GAAG,MAAM,CAAC,CAAC;EACtF;EAEA,KAAK,eAAe;GAClB,YAAY,eAAe,MAAM,CAAC,MAAM,CAAC;GACzC,MAAM,MAAM,OAAO,KAAK,QAAQ,EAAE;GAClC,MAAM,SAAS,OAAO,KAAK,UAAU,EAAE,CAAC,CAAC,YAAY,KAAK;GAC1D,MAAM,SAAS,YAAY,CAAC,GAAG,WAAW,KAAK,MAAiC,CAAC;GACjF,MAAM,OAAO,WAAW,OAAO,UAAU,SAAS;GAClD,MAAM,cAAc,CAAC;IAAC;IAAO;IAAQ;GAAQ,CAAC,CAAC,SAAS,IAAI;GAE5D,IAAI,OAAO,uBAAuB,cAAc,GAAG,GAAG,IAAI,aAAa,CAAC;GACxE,IAAI;GACJ,IAAI,OAAO,SAAS;IAClB,IAAI,aAAa,OAAO,KAAK,UAAU,OAAO,MAAM;SAC/C;KACH,MAAM,QAAQ,cAAc,OAAO,MAAM;KACzC,IAAI,OAAO,SAAS,KAAK,SAAS,GAAG,IAAI,MAAM,OAAO;IACxD;GACF;GAEA,MAAM,SAAS,IAAI,OAAO;GAC1B,MAAM,WAAW,kBAAkB,IAAI;GACvC,MAAM,WAAW,MAAM,QAAQ;IAC7B,QAAQ,IAAI,OAAO;IACnB;IACA,QAAQ;IACR;IACA,QAAQ,YAAY,SAAS,IAAI,YAAY,IAAI,IAAI,OAAO;IAC5D;GACF,CAAC;GAED,IAAI,SAAS,SAAS,OAAO,SAAS,UAAU,KAI9C,OAAO,KAAK,QAAQ,SAAS,OAAO,GAAG,SAAS,WAAW,IAAI,SAAS,QAAQ,IAAI;GAGtF,IAAI,SAAS,KAAK,KAAK,MAAM,QAC3B,OAAO,KACL,0IAEF;GAGF,MAAM,KAAK,KAAK;GAChB,IAAI,IAAI,OAAO,KAAK,MAAM,SAAS,MAAM,EAAE,CAAC;GAC5C,OAAO,KAAK,SAAS,IAAI;EAC3B;EAEA,KAAK,cAAc;GACjB,MAAM,SAAS,IAAI,OAAO;GAC1B,MAAM,WAAW,MAAM,QAAQ;IAC7B;IACA,MAAM;IACN,QAAQ;IACR,QAAQ,IAAI,OAAO;GACrB,CAAC;GACD,MAAM,UAAU,UAAU,SAAS,IAAI;GACvC,IAAI,YAAY,QAAQ,YAAY,QAClC,OAAO,KACL,WAAW,OAAO,2GAElB,IACF;GAEF,OAAO,KAAK,KAAK,UAAU;IAAE;IAAQ,MAAM;GAAQ,GAAG,MAAM,CAAC,CAAC;EAChE;EAEA,SACE,OAAO,KAAK,iBAAiB,QAAQ,IAAI;CAC7C;AACF;;;;;;;;;;;;;AAcA,eAAsB,OAAO,KAA6B;CACxD,MAAM,SAAS,IAAI,OAAO;EAAE,MAAM;EAAQ,SAAS;CAAQ,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;CAE7F,OAAO,kBAAkB,wBAAwB,aAAa,EAAE,OAAO,MAAM,EAAE;CAE/E,OAAO,kBAAkB,uBAAuB,OAAO,QAAQ;EAC7D,IAAI;GACF,OAAO,MAAM,SACX,KACA,IAAI,OAAO,MACV,IAAI,OAAO,aAAa,CAAC,CAC5B;EACF,SAAS,OAAO;GAGd,MAAM,UAAW,MAAgB,WAAW,OAAO,KAAK;GAIxD,MAAM,EAAE,MAAM,WAAW;GAOzB,MAAM,QAAQ,CAAC,MAAM,MAAM,CAAC,CAAC,QAAQ,SAAS,SAAS,UAAa,SAAS,EAAE,CAAC,CAAC,KAAK,MAAM;GAC5F,OAAO,KAAK,QAAQ,GAAG,QAAQ,MAAM,UAAU,SAAS,IAAI;EAC9D;CACF,CAAC;CAED,MAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;CAI/C,MAAM,IAAI,SAAe,YAAY;EACnC,QAAQ,MAAM,GAAG,SAAS,OAAO;EACjC,OAAO,UAAU;CACnB,CAAC;AACH"}