@oxy-hq/cli 0.1.0 → 0.4.0

package/dist/{mcp-VdontkUr.mjs → mcp-CIsyezzU.mjs}

@@ -32,7 +32,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 * this package was published.
 *
 * Auth, target resolution and placeholder substitution are the CLI's — the
-* same `Context`, so a token cached by `oxyc login` (or `oxy login`) works
+* same `Context`, so a token cached by `oxyc login` works
 * here with no separate setup, and `{org}` / `{workspace}` resolve the same
 * way.
 */
@@ -313,4 +313,4 @@ async function runMcp(ctx) {
 
 //#endregion
 export { runMcp };
-//# sourceMappingURL=mcp-VdontkUr.mjs.map
+//# sourceMappingURL=mcp-CIsyezzU.mjs.map

package/dist/mcp-CIsyezzU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-CIsyezzU.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` 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":"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"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@oxy-hq/cli",
-  "version": "0.1.0",
-  "description": "oxyc \u2014 the Oxy CLI: a gh-api-style client for the Oxy HTTP API, plus the customer-account tooling that scopes a session to one customer.",
+  "version": "0.4.0",
+  "description": "oxyc — the Oxy CLI: a gh-api-style client for the Oxy HTTP API, plus the customer-account tooling that scopes a session to one customer.",
   "type": "module",
   "bin": {
-    "oxyc": "./dist/main.mjs"
+    "oxyc": "dist/main.mjs"
   },
   "files": [
     "README.md",
@@ -23,7 +23,7 @@
     "directory": "sdk/cli"
   },
   "scripts": {
-    "codegen": "node scripts/sync-schemas.mjs && node scripts/embed-assets.mjs",
+    "codegen": "node scripts/emit-version.mjs && node scripts/sync-schemas.mjs && node scripts/embed-assets.mjs",
     "prebuild": "pnpm run codegen",
     "build": "tsdown",
     "build:watch": "tsdown --watch",
@@ -44,20 +44,20 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
+    "@clack/prompts": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "commander": "^14.0.2",
+    "commander": "^15.0.0",
     "picocolors": "^1.1.1",
     "yaml": "^2.8.1",
     "zod": "^3.25.28 || ^4"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.1",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=20"

package/skills/oxy-custom-apps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oxy-custom-apps
-description: Use when building, debugging, reviewing, or shipping an Oxy custom-app bundle (a code-first React/Vite app served by oxy), including writing Oxy Functions and driving them from the UI. Encodes the contract rules, pitfalls, performance guardrails, and the self-serve `oxy publish` ship flow.
+description: Use when building, debugging, reviewing, or shipping an Oxy custom-app bundle (a code-first React/Vite app served by oxy), including writing Oxy Functions and driving them from the UI. Encodes the contract rules, pitfalls, performance guardrails, and the self-serve `oxyc publish` ship flow.
 ---
 
 # Customer-app development
@@ -111,7 +111,7 @@ qualified.)
    `ctx` bridges to the data plane: `ctx.query` / `ctx.queryStream`,
    `ctx.semantic.query`, `ctx.warehouse.{insert,exec,upsert}`,
    `ctx.airway.run`, `ctx.fetch` (SSRF-allowlisted), `ctx.env`,
-   `ctx.user`, `ctx.log`. `oxy publish` bundles `functions/*.ts` with
+   `ctx.user`, `ctx.log`. `oxyc publish` bundles `functions/*.ts` with
    esbuild — no separate backend to stand up. Worked example +
    author-facing `ctx` types: `oxy-hq/customer-apps:
    examples/hello-oxy/functions/`.
@@ -119,7 +119,7 @@ qualified.)
 3. **`OXY_APP_BASE_PATH` must match the path the bundle is linked
    under.** `@oxy-hq/vite-plugin` resolves it from (in order):
    `OXY_APP_BASE_PATH` env → `orgSlug + slug` in `oxy-app.json` →
-   `/`. `oxy publish` sets that env to `/customer-apps/<org>/<slug>/`
+   `/`. `oxyc publish` sets that env to `/customer-apps/<org>/<slug>/`
    for the build automatically, and the vite-plugin derives the same
    from the manifest for `pnpm dev` / `pnpm build`. Mismatch → asset
    404s → blank dashboard.
@@ -270,16 +270,16 @@ asset base baked in.
 
 ## Publishing
 
-Ship with `oxy publish` — **no CI, no S3 sync, no folder picker**. From
+Ship with `oxyc publish` — **no CI, no S3 sync, no folder picker**. From
 the app directory (`oxy-hq/customer-apps: examples/hello-oxy/` is the worked
 shell; note its manifest deliberately carries no `orgSlug`, leaving the org to
 be resolved at publish time):
 
 ```bash
-oxy login --env production    # once; browser flow, caches a token,
-                              # and prints whether you're an app-admin
-oxy publish --env production           # build → tar → upload (draft channel)
-oxy publish --env production --promote # …straight to live
+oxyc login --env production    # once; browser flow, caches a token,
+                               # and prints whether you're an app-admin
+oxyc publish --env production           # build → tar → upload (draft channel)
+oxyc publish --env production --promote # …straight to live
 ```
 
 - **Identity** is the manifest's `slug` + `orgSlug` (override with
@@ -301,7 +301,7 @@ Full hands-on guide: `oxy-hq/customer-apps: docs/local-development.md`.
 ## Reading data while vibe-coding
 
 You don't need an `X-API-Key` to poke at the data API by hand — your
-`oxy login` token authenticates as a bearer. From an app directory:
+`oxyc login` token authenticates as a bearer. From an app directory:
 
 ```bash
 oxyc login --env local       # once; caches a token per host
@@ -319,7 +319,7 @@ curl -H "Authorization: Bearer $(oxyc token --env local)" \
 `oxyc api <path>` takes the path relative to `/api/`; `-X` sets the method
 (POST when a body is given), `-f`/`-F` set the body (string / JSON-typed),
 `--input` sends a raw one, `-i` includes response headers. `--env` resolves the
-same targets as `oxy publish` (`local` → the Vite dev server `:5173`, which
+same targets as `oxyc publish` (`local` → the Vite dev server `:5173`, which
 proxies `/api` → oxy `:3000`).
 
 Do not guess a path: `oxyc routes <filter>` lists what exists and

package/template/.github/scripts/ci-publish.sh

@@ -3,8 +3,8 @@
 #
 # OFF by default, and the default is the whole point. `customer-apps` — the
 # monorepo Oxy ships its own custom apps from — deleted its publish CI outright
-# and its engineers publish from their machines with `oxy login` and
-# `oxy publish`; its own docs say "there is no GitHub Actions / CI". A repo
+# and its engineers publish from their machines with `oxyc login` and
+# `oxyc publish`; its own docs say "there is no GitHub Actions / CI". A repo
 # scaffolded from this template therefore behaves the same way unless somebody
 # asks for CI publishing, rather than arriving demanding a long-lived token the
 # rest of the org has already decided it does not want.
@@ -64,7 +64,7 @@ case "$value" in
   # misreading of a switch that costs something.
   ''|false|no|off|0)
     printf 'off\n'
-    printf '::notice::CI publishing is off in this repo, which is the default. This run built the app bundles and published nothing. Publishing here is self-serve: from an app directory under apps/, run "oxy login --env dev" once and then "oxy publish --env dev" (or --env production). To publish from CI instead, add a repository VARIABLE named OXY_CI_PUBLISH with the value true — Settings, then Secrets and variables, then Actions, then the Variables tab — and give each GitHub environment its own OXY_TOKEN.\n' >&2
+    printf '::notice::CI publishing is off in this repo, which is the default. This run built the app bundles and published nothing. Publishing here is self-serve: from an app directory under apps/, run "oxyc login --env dev" once and then "oxyc publish --env dev" (or --env production). To publish from CI instead, add a repository VARIABLE named OXY_CI_PUBLISH with the value true — Settings, then Secrets and variables, then Actions, then the Variables tab — and give each GitHub environment its own OXY_TOKEN.\n' >&2
     ;;
   true|yes|on|1)
     printf 'on\n'

package/template/.github/scripts/discover-apps.sh

@@ -101,20 +101,16 @@ while IFS= read -r manifest; do
   app_dir="${manifest%/oxy-app.json}"
 
   if ! jq -e 'type == "object"' "$root/$manifest" >/dev/null 2>&1; then
-    printf '::error file=%s::%s is not a JSON object. oxy publish reads this file for the app identity and will not get past it.\n' \
+    printf '::error file=%s::%s is not a JSON object. oxyc publish reads this file for the app identity and will not get past it.\n' \
       "$manifest" "$manifest" >&2
     bad=1
     continue
   fi
 
-  # `oxy publish` resolves the app slug as `--app`, then OXY_APP, then the
-  # manifest, then the `<app>` segment of an `apps/<org>/<app>/` path — that
-  # is the IMPLEMENTATION's order (publish.rs:779-785). Note that
-  # `oxy publish --help` states a different one, manifest before OXY_APP; the
-  # code is what runs, and its own comment agrees with the code. It makes no
-  # difference here either way: this workflow sets neither the flag nor the
-  # env var, and both readings end `manifest, then path` — the only two links
-  # this check depends on.
+  # `oxyc publish` resolves the app slug as `--app`, then OXY_APP, then the
+  # manifest, then the `<app>` segment of an `apps/<org>/<app>/` path — its
+  # `--help` says the same. This workflow sets neither the flag nor the env
+  # var, so `manifest, then path` are the only two links this check depends on.
   slug="$(jq -r '.slug // ""' "$root/$manifest")"
   if [ -z "$slug" ] || [ "$slug" = "null" ]; then
     printf '::error file=%s::%s has no "slug". That is the app'"'"'s identity on the platform and there is nowhere else to get it.\n' \
@@ -123,11 +119,11 @@ while IFS= read -r manifest; do
     continue
   fi
 
-  # Same resolution chain for the org (publish.rs:773-778), with one
+  # Same resolution chain for the org, with one
   # difference that matters: the path fallback only fires for the nested
   # `apps/<org>/<app>/` layout. In the flat `apps/<app>/` layout there is no
   # `<org>` segment, so a manifest with no `orgSlug` leaves the org
-  # unresolvable — and `oxy publish` needs it to look the project up on the
+  # unresolvable — and `oxyc publish` needs it to look the project up on the
   # build-config endpoint.
   org="$(jq -r '.orgSlug // ""' "$root/$manifest")"
   nested=0
@@ -135,13 +131,13 @@ while IFS= read -r manifest; do
     apps/*/*) nested=1 ;;
   esac
   if { [ -z "$org" ] || [ "$org" = "null" ]; } && [ "$nested" -eq 0 ]; then
-    printf '::error file=%s::%s has no "orgSlug", and %s is not an apps/<org>/<app>/ path for oxy publish to infer one from. Add "orgSlug" to the manifest.\n' \
+    printf '::error file=%s::%s has no "orgSlug", and %s is not an apps/<org>/<app>/ path for oxyc publish to infer one from. Add "orgSlug" to the manifest.\n' \
       "$manifest" "$manifest" "$app_dir" >&2
     bad=1
     continue
   fi
 
-  # `build.outDir`, defaulting to `out` — the same default `oxy publish`
+  # `build.outDir`, defaulting to `out` — the same default `oxyc publish`
   # applies. Guarded with a type check because a manifest whose `build` is a
   # string (or a number) would make plain `.build.outDir` a jq error, and a jq
   # error under `set -e` would abort the whole scan on one malformed file

package/template/.github/scripts/publish-env.sh

@@ -8,7 +8,7 @@
 # unexecuted.
 #
 # It also has exactly one caller and one answer ON PURPOSE. The name printed
-# here is used TWICE by publish.yaml — as `oxy publish --env <name>` and as the
+# here is used TWICE by publish.yaml — as `oxyc publish --env <name>` and as the
 # GitHub Actions `environment:` whose secrets that publish authenticates with —
 # and those two must never disagree. Two ternaries in the YAML would have been
 # shorter and would have drifted the first time one of them was edited; one
@@ -21,7 +21,7 @@
 #   exit 0    only for a trigger this repo has a mapping for.
 #   exit 1    for anything else, INCLUDING an empty trigger.
 #
-# The refusal is the point. `oxy publish` defaults `--env` to **production**,
+# The refusal is the point. `oxyc publish` defaults `--env` to **production**,
 # so a workflow that omits the flag ships a customer's live environment while
 # looking like it did nothing in particular — which is exactly what this repo's
 # CI did before this file existed. Every publish now names its environment out
@@ -48,7 +48,7 @@ case "$trigger" in
     exit 1
     ;;
   *)
-    printf '::error::this repo publishes on "push" and "workflow_dispatch" only, and has no oxy environment mapped for "%s". Add one to .github/scripts/publish-env.sh — deliberately, because the alternative is a trigger nobody reviewed publishing to production, which is what "oxy publish" does when nothing names an environment.\n' \
+    printf '::error::this repo publishes on "push" and "workflow_dispatch" only, and has no oxy environment mapped for "%s". Add one to .github/scripts/publish-env.sh — deliberately, because the alternative is a trigger nobody reviewed publishing to production, which is what "oxyc publish" does when nothing names an environment.\n' \
       "$trigger" >&2
     exit 1
     ;;

package/template/.github/workflows/publish.yaml

@@ -1,4 +1,4 @@
-# Build and publish __NAME__'s custom apps with `oxy publish`.
+# Build and publish __NAME__'s custom apps with `oxyc publish`.
 #
 # On day one this repo has no apps, and this workflow is a deliberate no-op:
 # discovery finds nothing, every later step is skipped, the publish JOB is
@@ -14,7 +14,7 @@
 # compiles every bundle, needs no credential to do it, and so still catches a
 # bundle that stopped building before anyone ships it by hand — and the publish
 # JOB is skipped, green, with a notice naming the self-serve command
-# (`oxy login --env <env>`, then `oxy publish --env <env>`). That is how the
+# (`oxyc login --env <env>`, then `oxyc publish --env <env>`). That is how the
 # rest of this org already ships: `customer-apps`, Oxy's own monorepo of custom
 # apps, deleted its publish CI and its engineers publish from their laptops. A
 # scaffolded repo should behave like that on day one rather than arriving with a
@@ -32,7 +32,7 @@
 # Deliberately NOT modelled on pokehouse-oxy's `franchise-report-app.yml`
 # (Docker -> ECR -> ArgoCD). That is the only real, green CI on disk in this
 # org, which is exactly what makes it tempting; it is a legacy path for the
-# one app still on Next.js and has nothing to do with `oxy publish`.
+# one app still on Next.js and has nothing to do with `oxyc publish`.
 #
 # Auth is a static `OXY_TOKEN` secret, not GitHub OIDC trusted publishing.
 # Both appear in this org's examples and a workflow that MIXES them 403s.
@@ -43,13 +43,14 @@
 # `build` runs the bundles' own postinstall and build scripts — arbitrary
 # third-party code out of node_modules — and holds no publish credential.
 # `publish` holds `OXY_TOKEN`, downloads what `build` produced, and runs no
-# package script at all: `oxy publish --dir` is documented as "skip the build
-# and publish this pre-built directory as-is", so the credential and the
-# untrusted code are never in the same job, on the same runner, at the same
+# package script at all. That includes Oxy Functions: `build` bundles them with
+# `oxyc publish --build-only`, and `publish` runs `oxyc publish --prebuilt`,
+# which checks they arrived rather than running esbuild — so the credential and
+# the untrusted code are never in the same job, on the same runner, at the same
 # time.
 #
 # TWO ENVIRONMENTS, and `--env` is passed EXPLICITLY on every publish. This is
-# not tidiness either: `oxy publish` defaults `--env` to **production**, so the
+# not tidiness either: `oxyc publish` defaults `--env` to **production**, so the
 # earlier version of this workflow — which passed no `--env` at all — published
 # every push to main straight at the customer's live environment. Only ever as
 # a draft, so nothing went live, but into the wrong environment, and dev/prod
@@ -79,8 +80,8 @@ name: publish
 on:
   push:
     branches: [main]
-    # Without this filter every README edit would download a ~657 MB CLI to
-    # publish nothing. `workflow_dispatch` has no path filter, so the no-op
+    # Without this filter every README edit would install and build every app
+    # to publish nothing. `workflow_dispatch` has no path filter, so the no-op
     # path is still reachable by hand on a repo with no apps.
     paths:
       - "apps/**"
@@ -114,8 +115,7 @@ on:
     inputs:
       ref:
         # Explicit, and required, because of what Promote below actually
-        # does. There is no promote-an-existing-build command in this CLI —
-        # `oxy apps` offers show/create/list/delete and nothing else — so
+        # does. There is no promote-an-existing-build command in this CLI, so
         # "promote" can only mean "build this ref again and publish it live".
         # Leaving the ref implicit would let an operator who reviewed a draft
         # yesterday ship whatever landed on main since, believing they were
@@ -137,17 +137,11 @@ permissions:
   contents: read
 
 env:
-  # The same pin as validate.yaml, and it must stay the same: two pins in one
-  # repo drift, and the one nobody looks at is the one that breaks. Bump both
-  # together, after re-running the sequence. customer-tooling's own suite has
-  # a test that fails when they diverge, so this is enforced, not hoped for.
-  #
-  # This pin is also load-bearing for `--build-id`. Run-unique build ids
-  # arrived in 0.5.121; an older CLI defaults to a bare `$GITHUB_SHA`, which
-  # collides on a re-run or a promote and is rejected with HTTP 409. The
-  # publish step passes `--build-id` explicitly, so an older CLI would still
-  # work — the pin is the belt to that pair of braces.
-  OXY_VERSION: "0.5.126"
+  # The `@oxy-hq/cli` (`oxyc`) both jobs install, exactly. Its own pin, not
+  # validate.yaml's `OXY_VERSION`: that one is the Rust `oxy` that validates the
+  # workspace, a different tool on a different release line. `--build-only` and
+  # `--prebuilt`, which the two jobs below depend on, arrived in 0.4.0.
+  OXYC_VERSION: "0.4.0"
 
 jobs:
   build:
@@ -205,7 +199,7 @@ jobs:
           # keeps printf's own exit status, so a failing script inside the
           # substitution would be swallowed and this step would write an EMPTY
           # environment name — which downstream would read as "no environment"
-          # and, without the guard in the publish job, as `oxy publish`'s own
+          # and, without the guard in the publish job, as `oxyc publish`'s own
           # production default. An assignment carries the substitution's
           # status, so errexit catches it here.
           name="$(bash .github/scripts/publish-env.sh)"
@@ -248,7 +242,7 @@ jobs:
           # the dropdown alone builds the right code while GITHUB_SHA names
           # main's HEAD: the build id and the notice below would both be
           # confidently wrong, which is worse than vague. `git rev-parse HEAD`
-          # is also exactly what `oxy publish` records as the build's source
+          # is also exactly what `oxyc publish` records as the build's source
           # commit, so the two agree by construction.
           sha="$(git rev-parse HEAD)"
           printf 'sha=%s\n' "$sha" >> "$GITHUB_OUTPUT"
@@ -309,6 +303,27 @@ jobs:
         # exists and is non-empty before anything is uploaded.
         run: pnpm -r build
 
+      - name: Bundle each app's Oxy Functions
+        if: steps.discover.outputs.count != '0'
+        # HERE, in the job with no credential, because bundling runs the app's
+        # own esbuild out of node_modules. `--build-only --dir` skips the build
+        # that just ran, checks `functions/` is not holding frontend output, and
+        # writes `functions/<name>.js` into the out dir for every function the
+        # manifest declares — a no-op for an app that declares none. The publish
+        # job then checks they arrived instead of bundling again.
+        run: |
+          set -euo pipefail
+          npm install --prefix "$RUNNER_TEMP/oxyc" --no-audit --no-fund "@oxy-hq/cli@$OXYC_VERSION"
+          oxyc="$RUNNER_TEMP/oxyc/node_modules/.bin/oxyc"
+          status=0
+          while IFS="$(printf '\t')" read -r app_dir out; do
+            [ -n "$app_dir" ] || continue
+            echo "::group::oxyc publish --build-only $app_dir"
+            ( cd "$app_dir" && "$oxyc" publish --build-only --dir "$out" ) || status=1
+            echo "::endgroup::"
+          done < "$RUNNER_TEMP/apps.tsv"
+          exit "$status"
+
       - name: Stage the built bundles for the publish job
         if: steps.discover.outputs.count != '0'
         run: |
@@ -365,13 +380,13 @@ jobs:
           retention-days: 1
 
   publish:
-    name: oxy publish
+    name: oxyc publish
     runs-on: ubuntu-latest
     needs: build
     # Two gates, and they answer different questions. The first: does this repo
     # publish from CI at all? Absent `vars.OXY_CI_PUBLISH` it does not, and this
     # job is skipped with the notice the build job printed — the bundles were
-    # still built, and shipping them is `oxy publish`, run by a person. The
+    # still built, and shipping them is `oxyc publish`, run by a person. The
     # second: day one, or any repo with no apps, where discovery found nothing.
     # Either way a SKIP, which is green, not red, and does not prompt for
     # whatever approval the environment below may require.
@@ -387,7 +402,7 @@ jobs:
     if: needs.build.outputs.ci-publish == 'on' && needs.build.outputs.count != '0'
 
     # The gate, and the credential boundary. `dev` on a push, `production` on
-    # a manual dispatch — the SAME string this job passes to `oxy publish
+    # a manual dispatch — the SAME string this job passes to `oxyc publish
     # --env` below, resolved once in `build`, so the destination this job
     # publishes to and the environment it draws its secrets from are the same
     # thing by construction. Each environment holds its own `OXY_TOKEN`, and a
@@ -432,7 +447,7 @@ jobs:
         run: |
           set -euo pipefail
           # Put each bundle back exactly where the build left it, so
-          # `oxy publish` sees the tree it would have seen in a single job:
+          # `oxyc publish` sees the tree it would have seen in a single job:
           # oxy-app.json beside its own build output, git provenance intact.
           # Nothing is executed to do this — it is a copy.
           staging="$RUNNER_TEMP/bundles"
@@ -446,72 +461,45 @@ jobs:
             cp -R "$staging/$app_dir/$out/." "$app_dir/$out/"
           done < "$staging/apps.tsv"
 
-      - name: Install the pinned oxy CLI
+      - name: Install Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Install the pinned oxyc CLI
+        env:
+          # This job holds the publish credential (step-scoped, below), so the
+          # CLI's own dependencies run no install scripts here.
+          npm_config_ignore_scripts: "true"
         run: |
           set -euo pipefail
-          # NOT `bash <(curl ...)`, the form the docs use: process
-          # substitution hands bash an empty file when the download fails,
-          # and bash then exits 0 — a step that reports "installed" having
-          # installed nothing. Download to a file first so curl's own -f
-          # failure is the step's.
-          curl -sSfL https://get.oxy.tech -o "$RUNNER_TEMP/get-oxy.sh"
-          OXY_VERSION="$OXY_VERSION" bash "$RUNNER_TEMP/get-oxy.sh"
-
-          # And check the installer left something behind: it downloads the
-          # binary with `curl -L` (no -f) and exits 0 regardless.
-          if [ ! -x "$HOME/.local/bin/oxy" ]; then
-            echo "::error::the installer exited 0 but left no executable at $HOME/.local/bin/oxy." >&2
-            exit 1
-          fi
+          # Into a prefix of its own rather than -g: nothing else on the
+          # runner's global npm is in play, and the path below is exact.
+          npm install --prefix "$RUNNER_TEMP/oxyc" --no-audit --no-fund "@oxy-hq/cli@$OXYC_VERSION"
+          echo "$RUNNER_TEMP/oxyc/node_modules/.bin" >> "$GITHUB_PATH"
 
-          # The installer drops the binary in ~/.local/bin for a non-root
-          # user and edits shell rc files, which a GitHub step never reads.
-          # Put it on PATH explicitly instead of hoping.
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-
-      - name: Verify the oxy CLI
+      - name: Verify the oxyc CLI
         run: |
           set -euo pipefail
-          # The same guard validate.yaml runs, on purpose: one guard with one
-          # set of failure modes, not two that drift. Two silent failures
-          # make it load-bearing:
-          #   1. the installer runs `curl -L` WITHOUT -f, so a tag that does
-          #      not exist writes GitHub's 404 HTML page to the binary path,
-          #      chmod +x's it, and still exits 0;
-          #   2. this CLI falls through to `--help` with exit 0 on a
-          #      subcommand it does not have, so an old binary "succeeds" at
-          #      doing nothing.
-          if ! raw="$(oxy --version 2>&1)"; then
-            echo "::error::'oxy --version' failed — the installed binary is not runnable." >&2
-            printf '%s\n' "$raw" >&2
+          # Exact, not a floor: npm installed exactly the pin, so anything else
+          # means PATH found a different oxyc first.
+          have="$(oxyc --version)"
+          if [ "$have" != "$OXYC_VERSION" ]; then
+            echo "::error::oxyc $have is on PATH, not the pinned $OXYC_VERSION." >&2
             exit 1
           fi
-
-          have="$(printf '%s\n' "$raw" | sed -n 's/^oxy-app version: \([0-9][0-9.]*\).*/\1/p' | head -1)"
-          if [ -z "$have" ]; then
-            echo "::error::could not read a version out of 'oxy --version' — the install probably wrote a 404 page." >&2
-            printf '%s\n' "$raw" >&2
-            exit 1
-          fi
-
-          oldest="$(printf '%s\n%s\n' "$OXY_VERSION" "$have" | sort -t. -k1,1n -k2,2n -k3,3n | head -1)"
-          if [ "$oldest" != "$OXY_VERSION" ]; then
-            echo "::error::oxy $have is older than the pinned $OXY_VERSION." >&2
-            exit 1
-          fi
-
-          echo "oxy $have (pin $OXY_VERSION)"
+          echo "oxyc $have (pin $OXYC_VERSION)"
 
       - name: Publish each bundle
         env:
           # Step-scoped as well as job-isolated. The job split is what keeps
           # this token away from the bundles' own build scripts — those ran
           # in `build`, on a different runner, and nothing in THIS job runs a
-          # package script (`oxy publish --dir` publishes a pre-built
-          # directory as-is rather than running the manifest's build). The
-          # step scope is the cheap second layer: it keeps the token out of
-          # the environment of the install and verify steps above, which
-          # execute a downloaded shell script.
+          # package script (`oxyc publish --prebuilt --dir` publishes the
+          # directory as built, functions included, rather than running the
+          # manifest's build or esbuild). The step scope is the cheap second
+          # layer: it keeps the token out of the environment of the install
+          # and verify steps above, which run code fetched from npm.
           # Resolved against the ENVIRONMENT named above, where `dev` and
           # `production` each hold their own.
           #
@@ -531,7 +519,7 @@ jobs:
           # repository-level `OXY_TOKEN` after adding the environment ones.
           OXY_TOKEN: ${{ secrets.OXY_TOKEN }}
           # `dev` or `production`, resolved once in the build job. Passed to
-          # `oxy publish --env` below; the identical string selected the
+          # `oxyc publish --env` below; the identical string selected the
           # environment this job is running in.
           PUBLISH_ENV: ${{ needs.build.outputs.publish-env }}
           # Optional, and it OVERRIDES `--env` rather than refining it (the
@@ -553,7 +541,7 @@ jobs:
           set -euo pipefail
 
           # Fail closed on the environment before anything else. An empty
-          # PUBLISH_ENV would mean `oxy publish` fell back to its own default
+          # PUBLISH_ENV would mean `oxyc publish` fell back to its own default
           # — production — while every log line here said nothing at all, and
           # that silent fallback is the whole bug this workflow was fixed for.
           # It can only be empty if the build job's resolution step was
@@ -615,8 +603,12 @@ jobs:
             # publishes at the customer's live environment. It is the FIRST
             # argument for the same reason: anything appended below is a
             # refinement of a destination that has already been named.
-            args=(--env "$PUBLISH_ENV" --dir "$out" --build-id "$build_id")
-            # --org/--app/--project are deliberately absent: oxy publish
+            args=(--env "$PUBLISH_ENV" --dir "$out" --prebuilt --build-id "$build_id")
+            # `--prebuilt`: the build job bundled this app's functions into the
+            # out dir. The CLI refuses when a declared one did not arrive,
+            # rather than publishing a bundle whose function 404s at runtime.
+            #
+            # --org/--app/--project are deliberately absent: oxyc publish
             # reads the app's identity from the oxy-app.json in this
             # directory (discovery has already checked it is there and
             # complete) and resolves the project from the target's
@@ -629,8 +621,8 @@ jobs:
             # default — this workflow is not overriding platform behaviour.
             #
             # `--promote` publishes THIS build straight to live. It does not
-            # promote a build that already exists: nothing in this CLI can
-            # (`oxy apps` is show/create/list/delete). So the run rebuilt the
+            # promote a build that already exists: nothing in this CLI can.
+            # So the run rebuilt the
             # ref the operator named and is shipping that, under a new build
             # id — said out loud above, because "promote" invites the other
             # reading and the difference is a wrong version in front of
@@ -639,11 +631,11 @@ jobs:
               args+=(--promote)
             fi
 
-            echo "::group::oxy publish $app_dir"
+            echo "::group::oxyc publish $app_dir"
             # A subshell so the cd cannot leak into the next iteration.
-            # oxy publish reads oxy-app.json, resolves --dir, and captures
+            # oxyc publish reads oxy-app.json, resolves --dir, and captures
             # git provenance relative to its working directory.
-            ( cd "$app_dir" && oxy publish "${args[@]}" ) || status=1
+            ( cd "$app_dir" && oxyc publish "${args[@]}" ) || status=1
             echo "::endgroup::"
           done < "$RUNNER_TEMP/bundles/apps.tsv"