feat(workers): deploy native bundles with consistent plans and resource references

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.21"
+  ".": "0.1.23"
 }

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.1.23](https://github.com/xapi-labs/xapi-cli/compare/v0.1.22...v0.1.23) (2026-09-21)
+
+
+### Features
+
+* **skill:** bundle CLI-native provider workflows ([#29](https://github.com/xapi-labs/xapi-cli/issues/29)) ([fe1551a](https://github.com/xapi-labs/xapi-cli/commit/fe1551a3b302cef584154b61f3c45da10267a353))
+* **workers:** add managed project deployment workflows ([e002970](https://github.com/xapi-labs/xapi-cli/commit/e0029701152c9ad73277bef9e0750284e03c884d))
+* **workers:** add read-only environment inspection ([f5e7245](https://github.com/xapi-labs/xapi-cli/commit/f5e7245e7bc8b01f62a1a9c2669ea1dbf9c48c9d))
+* **workers:** add safe secret management workflows ([#32](https://github.com/xapi-labs/xapi-cli/issues/32)) ([0f0ec1b](https://github.com/xapi-labs/xapi-cli/commit/0f0ec1b498a012f35e6b5133fde2ec4c346c9ad6))
+* **workers:** make deployment plans exact ([45aeac2](https://github.com/xapi-labs/xapi-cli/commit/45aeac24d2081b1496bc882fa27a313ab9f21250))
+* **workers:** preserve native deployments and exact plans ([3b83be2](https://github.com/xapi-labs/xapi-cli/commit/3b83be2ac19061b53dbb1869a8a0061dbb5d9acf))
+
+
+### Bug Fixes
+
+* **workers:** clarify project deployment commands ([555dcb4](https://github.com/xapi-labs/xapi-cli/commit/555dcb4ff88d1633bf23d6709a56abb30f187104))
+* **workers:** preserve native deployment intent during import ([74148a4](https://github.com/xapi-labs/xapi-cli/commit/74148a48351772a54457fca143d0eaa87f73db7b))
+
+## [0.1.22](https://github.com/xapi-labs/xapi-cli/compare/v0.1.21...v0.1.22) (2026-09-17)
+
+
+### Features
+
+* **provider:** import API contracts and wait for publication ([#14](https://github.com/xapi-labs/xapi-cli/issues/14)) ([0b17d43](https://github.com/xapi-labs/xapi-cli/commit/0b17d43b5f24536f6a4b50d29de65a4045b81369))
+* **provider:** manage per-user service rate limits ([49c974b](https://github.com/xapi-labs/xapi-cli/commit/49c974b82d42decb6fb55c7034f8cd562b2c9d03))
+* **skill:** add domain and Web3 service guides ([86de0d1](https://github.com/xapi-labs/xapi-cli/commit/86de0d11f89a4a9d52fa1d407541150d71addefe))
+* **skill:** document domains and GPT Live ([7466f4d](https://github.com/xapi-labs/xapi-cli/commit/7466f4db1ce8ea8172f85a4ce286e151aa0688c8))
+
+
+### Bug Fixes
+
+* **oauth:** enforce hard polling deadlines ([86e6828](https://github.com/xapi-labs/xapi-cli/commit/86e6828c411df85acbb6ad471951d38b31693590))
+* **skill:** harden live service guidance ([137e8ab](https://github.com/xapi-labs/xapi-cli/commit/137e8ab7b32febe176e2f619d6c472655bbcb244))
+
 ## [0.1.21](https://github.com/xapi-labs/xapi-cli/compare/v0.1.20...v0.1.21) (2026-08-28)
 
 

README.md

@@ -31,6 +31,14 @@ AI services through this CLI. Then just ask
 — "what's the price of BTC" — and it takes it from there. Set up a key first;
 see [Quick Start](#quick-start).
 
+Providers can install the CLI-native [`xapi-provider` skill](skills/xapi-provider/SKILL.md),
+which covers service registration, billing and WebSocket configuration,
+revision publishing, observability, earnings, and linked usage Skills:
+
+```bash
+npx skills add xapi-labs/xapi-cli --skill xapi-provider
+```
+
 Workers projects can also install the standalone [`xapi-workers` skill](skills/xapi-workers/SKILL.md), covering deployment, all six managed resource types, complete consumption queries and cleanup:
 
 ```bash
@@ -118,6 +126,13 @@ WebSocket client. Active SSE and raw downloads may run longer than 60 seconds,
 but abort after 60 seconds without data by default. Set
 `XAPI_TRANSFER_IDLE_TIMEOUT_MS` to change that idle timeout.
 
+GPT Live is a WebSocket protocol and cannot be invoked with `xapi-to call`.
+Read [the WebSocket Gateway guide](skills/xapi/guides/ws_gateway.md) and use a
+real WebSocket client. The packaged
+[`examples/openai-gpt-live-text.mjs`](examples/openai-gpt-live-text.mjs)
+demonstrates `session.start`, managed Responses delegation, text events, and a
+graceful `session.close` without placing an xAPI key in source or CLI arguments.
+
 ### Async Task Commands
 
 Task helpers built on top of the `task.poll` capability.
@@ -128,6 +143,114 @@ xapi-to task wait 550e8400-e29b-41d4-a716-446655440000                 # wait un
 xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
 ```
 
+### Provider: Import → Configure → Submit → Wait
+
+`provider` manages APIs owned by your account. It uses `XAPI_API_HOST`
+(default `api.xapi.to`) and the same saved or environment API key as other
+commands. In the xAPI Console API Keys settings, grant `service:create`,
+`service:read`, `service:update`, and `service:publish`. Legacy `allowRegister`
+only grants creation, not the remaining lifecycle permissions. Missing
+permissions return a nonzero exit with the required scope.
+
+Start from [examples/provider/openapi.json](examples/provider/openapi.json),
+replace its upstream URL, service details, and endpoint contract, then run:
+
+```bash
+# Inspect current rules; no API key required
+xapi-to provider spec-rules --format pretty
+
+# Import a raw OpenAPI 3.0.3 JSON object (not a {openApiSpec: ...} envelope)
+xapi-to provider import --file openapi.json > imported.json
+
+# Use the serviceId and revisionId from imported.json (jq is optional)
+PROVIDER_SERVICE_ID=$(jq -er '.serviceId' imported.json)
+PROVIDER_REVISION_ID=$(jq -er '.revisionId' imported.json)
+
+# Save version configuration to move the draft revision to SANDBOX.
+# config.json can be {"description":"Initial release"} when the imported
+# endpoints, authentication, and pricing are already complete.
+xapi-to provider update "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --file config.json
+
+# Submit the specified revision, then wait for the actual publication result
+xapi-to provider submit "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --changelog "Initial release"
+xapi-to provider wait "$PROVIDER_SERVICE_ID" \
+  --revision "$PROVIDER_REVISION_ID" --interval 2s --timeout 10m
+
+# Inspect owned services, configuration, version overview, or review reports
+xapi-to provider list --format table
+xapi-to provider get "$PROVIDER_SERVICE_ID" --format pretty
+xapi-to provider versions "$PROVIDER_SERVICE_ID" --format pretty
+xapi-to provider review "$PROVIDER_SERVICE_ID" --revision "$PROVIDER_REVISION_ID"
+```
+
+When scripting these steps, stop on nonzero exit (for example, use `set -e`).
+Import returns the backend validation/preview plus `serviceId`, `revisionId`,
+and `state`. An HTTP 201 with `success: false` is a validation failure and exits
+nonzero; its structured validation errors are preserved. Registration creates
+a new service each time. If a response is lost, inspect `provider list` before
+retrying to avoid duplicate services.
+
+For an authenticated upstream, store credentials in a local JSON object such
+as `{"Authorization":"Bearer YOUR_UPSTREAM_KEY"}` and pass
+`--private-headers-file private-headers.json` to `provider import`. Keep this
+file out of version control. `--file -` and `--private-headers-file -` accept
+stdin, but only one input can consume stdin per command. Files must be JSON;
+YAML and URL imports are not supported in this command group.
+
+`provider update --revision <id>` reads a version configuration object, using the backend
+fields `description`, `baseUrl`, `baseUrls`, `authType`, `privateHeaders`,
+`authConfig`, `openApiSpec`, `endpoints`, and `status`. Prefer structured
+`privateHeaders` for upstream credentials. Endpoint fields include billing
+configuration such as `billingType` and `costPerCall`. Update does not accept
+a raw OpenAPI document; the nested backend field is `openApiSpec: {spec: ...}`.
+Saving that field alone does not re-import endpoint definitions; configure
+`endpoints` explicitly when changing the contract.
+
+- `--mode merge` (default) sends PATCH and preserves omitted fields/endpoints.
+  Existing endpoint edits require `id`, e.g.
+  `{"endpoints":[{"id":"ENDPOINT_ID","costPerCall":"0.002"}]}`.
+- `--allow-new-endpoints` explicitly permits ID-less merge entries to create
+  endpoints. Repeating such a merge can create duplicates.
+- `--mode replace` sends PUT. If `endpoints` is provided, it replaces the
+  endpoint list; include every endpoint you intend to keep. Omitted fields
+  otherwise follow backend PUT semantics. Use full configuration for replacement.
+
+`get` retains its existing service response; `--version v1.0` selects the
+configuration returned by the backend. Find endpoint IDs in
+`currentVersion.endpoints`; `provider versions` returns working revision IDs
+in `majors[].working.id`. For an already-published API, use the existing
+`provider revision start <service-id> <major>` command to create a working revision.
+`provider update` without `--revision` continues to update service metadata
+and rate limits. Existing `version update`, `publish`, and positional `review`
+commands remain available. The `submit` and `review --revision` forms are
+additional onboarding commands.
+
+Updates to `IN_REVIEW`, `PUBLISHED`, or `SUSPENDED` revisions return a conflict;
+the backend enforces this check under a transaction lock. When updating
+`privateHeaders`, send the complete desired map: it replaces the old map and
+rebuilds the derived authentication configuration. An empty map without an
+explicit `authConfig` clears those credentials. Omitting both fields preserves them.
+
+`submit` returns `{serviceId, revisionId, submission}`. A successful submission
+does not guarantee publication. `wait` checks the requested revision, succeeds
+only for `PUBLISHED`, and outputs the review report with `success` and `reason`.
+`--changelog` is limited to 2,000 characters by both the CLI and backend.
+Rejection, a draft/sandbox/suspended revision, or a legacy manual-review hold
+exit nonzero. Pending review continues until publication, the timeout (default
+10 minutes), or optional `--max-attempts`. Timeout and attempt-limit results
+include the last received report; polling can be resumed with the same IDs.
+The deadline also bounds in-flight HTTP requests and retry delays.
+
+Reads retry transient errors; writes are never automatically retried. The CLI
+redacts credential fields and known credential values from provider output.
+Redacted reads are for inspection and must not be submitted unchanged as
+configuration. After an ambiguous write failure, use `list`, `get`, or `review`
+to inspect the result before repeating the operation. No npm release is implied
+by a local source checkout; use `bun run src/index.ts provider ...` or build and
+run `node dist/index.js provider ...` while testing unreleased changes.
+
 ### Sandbox Commands
 
 Sandbox commands provide an AI-friendly cloud computer lifecycle. The fastest
@@ -382,7 +505,10 @@ xapi workers push --env preview
 The initializer adds `xapi:build`, `xapi:worker:build`, and
 `xapi:worker:dev`, plus a small `xapi-worker/index.ts`, `wrangler.jsonc`, and
 `xapi.worker.json`. `xapi:worker:dev` is only a package script around Wrangler;
-there is no separate xAPI local runtime. Use `--framework react|vite|vue|next`
+there is no separate xAPI local runtime. For workspace packages, `init` walks
+to the repository root and honors its declared `packageManager` or lockfile;
+the printed install and build commands are therefore safe for Yarn and pnpm
+monorepos as well as npm and Bun projects. Use `--framework react|vite|vue|next`
 only when automatic package detection is ambiguous. `init` is a one-time
 adapter setup, not a synchronization command; after it creates
 `xapi.worker.json`, use resource commands and `plan` to manage state.
@@ -410,9 +536,26 @@ through xAPI as Cloudflare native static assets:
 `workers plan` shows whether the selected environment has a dedicated hostname.
 When `webAppReady` is false, production promotion asks you to review the base
 path, root-relative routes, and OAuth callbacks without blocking applications
-that deliberately support path-prefix hosting. The current JSON Artifact
-transport accepts 12 MiB of decoded Worker modules and static assets per
-deployment.
+that deliberately support path-prefix hosting. Project bundles use one
+authenticated multipart request: modules and static assets are not uploaded as
+independent deployments. Limits are 200 modules / 10 MiB module content,
+10,000 assets / 25 MiB per asset, and 100 MiB total decoded project content.
+
+Environment placement is declared beside the budget. Workers remain globally
+deployed; the data location is inherited only by newly created D1/R2 resources,
+and Smart Placement lets Cloudflare optimize execution near backends:
+
+```json
+{
+  "dailyBudgetUsd": 0.25,
+  "defaultResourceLocation": "apac",
+  "placementMode": "smart"
+}
+```
+
+Use `xapi workers environment <worker-id> preview --data-location apac
+--placement smart` for an already linked project. This changes the environment
+default and deployment metadata; it does not move existing D1/R2 data.
 
 Templates are versioned packages shipped with the CLI, not remote code fetched
 during `init`. `persistent-agent` includes buildable source plus KV, D1, R2,
@@ -472,9 +615,9 @@ make both environments share one physical resource.
 `push` creates missing preview resources only after its full plan passes.
 `promote` performs the same production preflight and, after confirmation,
 creates missing production declarations before activating the exact tested
-preview Artifact. A budget mismatch, missing Secret, incompatible binding, or
-undeclared production resource blocks the command before any resource or
-deployment write. If creation requires an accepted freeze quote, pass its exact
+preview Artifact. A budget mismatch, missing required Secret or incompatible binding blocks activation.
+An undeclared production resource is retained and unbound by the next deployment.
+If creation requires an accepted freeze quote, pass its exact
 version with `--retention-price-version`.
 
 `resources update` requires the resource type because it replaces the complete
@@ -493,13 +636,14 @@ git diff -- xapi.worker.json
 xapi workers plan --env preview
 ```
 
-`pull` performs an additive, all-or-nothing merge. It preserves local-only
-declarations, writes no provider IDs, deletes nothing, and rejects unhealthy,
-unsupported, duplicate, or conflicting remote bindings. `--env both` reads and
-merges preview and production independently.
+`pull` imports compatible live declarations initially, then uses a metadata-only
+`.xapi/resource-sync-*` baseline for a three-way merge. Local edits and removed
+bindings are preserved; remote-only changes are adopted; conflicting edits abort
+without overwriting JSON. It changes no native resources and copies no Secret
+values. `--env both` uses independent environment baselines.
 
 Use `resources remove --env ... --binding ...` only when the live resource must
-remain. `plan` then marks it `MANUAL`, and `resources pull` can adopt it again.
+remain. `plan` explains that the next deployment removes its binding only.
 To delete data, back it up first and run:
 
 ```bash
@@ -509,18 +653,19 @@ xapi workers resources destroy --env preview --binding FILES --yes
 `destroy` accepts one environment at a time, removes the local declaration
 before requesting deletion, and reports deletion as requested until the live
 resource disappears. If the request fails, the live resource remains visible
-and `resources pull` restores the declaration. `resources list/create/delete
+and the user can inspect and explicitly retry deletion. `resources list/create/delete
 <worker-id> ...` remain low-level recovery primitives and do not update project
 files.
 
 Deployment identity includes the code Artifact, remote resource identities,
-Secret versions, environment bindings and compatibility settings. Changing only
+environment bindings and compatibility settings. Secret values are independent
+and do not trigger a code deployment. Changing only
 resources or compatibility settings therefore deploys again; repeating an
 unchanged push reuses the current activation. Older deployments without this
 configuration fingerprint require one deployment to establish the baseline.
 
 Removing a resource from `xapi.worker.json` does **not** destroy it: `plan`
-reports `MANUAL`, and the resource remains billable. `resources destroy` is the
+shows the unbinding consequence, and the resource remains billable. `resources destroy` is the
 project-aware destructive operation. Preserve a backup before using it and wait
 until `resources list` no longer returns the binding. A successful deployment
 alone is not proof of deletion or final billing settlement.