@xano/cli 1.0.6-beta.2 → 1.0.6-beta.20

package/README.md

@@ -39,6 +39,38 @@ Destructive commands include imperative safety prefixes in their help text and f
 
 These warnings are layer 1 of broader push-safety work; ephemeral sandbox environments and push preview remain the structural safeguards.
 
+### Paging on list commands
+
+The Metadata API pages unevenly, so `list` commands differ in what they expose. Every command reports only what its endpoint actually returns — the CLI never guesses whether more results exist.
+
+| Commands | Flags | Footer |
+|---|---|---|
+| `function list`, `unit_test list`, `workflow_test list` (plus `sandbox` / `tenant` variants) | `--page`, `--per_page` | `Page 2 · 50 shown · next: --page 3` |
+| `static_host list`, `static_host build list` (plus `ephemeral` variants) | `--page` only | `Page 2 · 100 shown · 340 total` |
+| `branch list`, `workspace list`, `tenant snapshot list`, `sandbox env list`, `tenant env list` | none | `12 branches` |
+| `tenant list`, `release list`, `platform list`, `tenant cluster list`, `ephemeral list` | none | none |
+| `tenant backup list` | `--page` only (pre-existing) | none |
+
+Notes:
+
+- **`--per_page` is only offered where the endpoint accepts it.** Static-host endpoints hardcode 100 items per page server-side, so those commands take `--page` alone. `xano static_host list --per_page 10` previously parsed but did nothing; it is now rejected rather than silently ignored.
+- **All paged commands default `--per_page` to 50.** The test-list commands previously requested 10000 internally so nothing was ever cut off; now that the footer and the JSON envelope both report position, a page that stops at 50 is visible rather than silent. Raise it (up to 10000) when you want everything in one call.
+- **The last group has no CLI paging.** Those endpoints page server-side but return a plain array with no page or total metadata, so the CLI cannot tell you where you are. Rather than show a page number with no context — or infer "more available" from a full page, which is wrong exactly when the result count is a multiple of the page size — these commands are left as-is. **They return at most 25–50 items** (50 for tenants and ephemerals, 25 for releases, platforms, and tenant backups). If you have more than that, query the Metadata API directly until those endpoints return paging metadata.
+- **`--output json` returns an envelope, not a bare array.** Every list command emits `{items, ...}` using the Metadata API's own field names — `curPage`, `nextPage`, `prevPage`, `itemsTotal` — each included only when the endpoint actually reports it. `perPage` is the one field the CLI adds, since the API never echoes it back and it is otherwise invisible at its default. This is a **breaking change** for scripts that parsed the previous bare array — read `.items` instead.
+
+  ```jsonc
+  // xano function list -o json
+  {
+    "curPage": 2,
+    "perPage": 50,      // injected by the CLI; everything else mirrors the API
+    "nextPage": 3,      // absent on the last page — never inferred
+    "prevPage": 1,
+    "items": [ /* ... */ ]
+  }
+  ```
+
+  The point of the envelope is that a script gets the same honest stop condition a human gets from the footer, in the same shape the raw Metadata API returns. Without it the only signal available is `items.length < perPage`, which is wrong exactly when the result count is a multiple of the page size. Absence of `nextPage` means the server said there is no next page; it is never omitted as a guess.
+
 ### Authentication
 
 ```bash
@@ -197,6 +229,50 @@ xano workspace git pull -r https://github.com/owner/private-repo -t ghp_xxx
 xano workspace git pull -r https://github.com/owner/repo --path subdir
 ```
 
+**One workspace document per tree.** A push directory must contain at most one
+`workspace/*.xs` document. The server applies the first workspace document it
+receives to the workspace being pushed into and silently discards the rest,
+without checking that it describes that workspace — so a second one renames the
+destination to a foreign name while leaving its content untouched. `workspace push`
+and `sandbox push` refuse a tree carrying more than one, naming the offending
+files; there is no `--force` override, because only you know which workspace the
+tree is meant to be.
+
+Trees pick up a second one easily: `pull` names the file after the workspace
+itself (`workspace/{name}.xs`), so pulling a different workspace into the same
+directory *adds* a file rather than overwriting, and renaming a workspace leaves
+the old-name file behind. Delete the stale ones, keeping the single document that
+matches your target workspace.
+
+### Knowledge
+
+Knowledge items are user-authored docs and skills (e.g. `CLAUDE.md`, `AGENTS.md`, runbooks)
+attached to a workspace. Each knowledge item's **name is a path** (e.g. `some/thing/CLAUDE.md`):
+`pull` writes its content to that path under the output directory, and `push` turns each local
+file into a knowledge item named by its relative path.
+
+Push matches local files to remote items by name. Existing items are updated (content only —
+description, mode, tags, and other metadata are preserved); new files are created. The
+knowledge type for new items is inferred from the filename: `AGENTS.md` → `agents.md`,
+`SKILL.md` → `skill`, everything else → `doc`. Hidden files (dotfiles) and `node_modules`
+are skipped.
+
+```bash
+# Pull knowledge files to local paths (defaults to current directory)
+xano knowledge pull
+xano knowledge pull -d ./knowledge                       # Specify output directory
+xano knowledge pull -b dev                               # Specific branch
+
+# Push local files as knowledge (defaults to current directory, only changed files)
+xano knowledge push
+xano knowledge push -d ./knowledge                       # Push from a specific directory
+xano knowledge push --dry-run                            # Preview changes without pushing
+xano knowledge push --sync --delete                      # Full push + delete remote knowledge not included
+xano knowledge push --force                              # Skip preview and confirmation (for CI/CD)
+xano knowledge push -i "guides/*"                        # Push only matching files
+xano knowledge push -e "**/README.md"                    # Push all files except READMEs
+```
+
 ### Branches
 
 All branch commands use **branch labels** (e.g., `v1`, `dev`), not IDs.
@@ -262,6 +338,7 @@ xano function run <name> --data email=jo@x.com --data age:=30 --data active:=tru
 xano function run <name> --json @payload.json --data env=staging   # base payload + override
 echo '{"email":"jo@x.com"}' | xano function run <name> --stdin -o json | jq .result
 xano function run <name> --branch dev --logs            # run on a branch, show execution logs
+xano function run <name> --datasource test              # run against the 'test' data source
 ```
 
 Input flexibility for `function run` (assembled into one JSON `input` object):
@@ -274,6 +351,11 @@ Input flexibility for `function run` (assembled into one JSON `input` object):
 | `--json '<inline>'` / `--json @file.json` / `--json -` | a base JSON object (stdin with `-`) |
 | `--stdin` | read the JSON object from stdin (same as `--json -`) |
 
+`--datasource <label>` runs the function against a non-live data source by sending the
+`X-Data-Source` header, so table reads and writes hit that data source's tables. Omit it
+to run against `live`; an unknown label is rejected by the server with
+`Invalid data source.`
+
 Merge order is JSON base first, then `--data` overrides. Missing required inputs are
 prompted for on an interactive terminal; in a non-TTY (CI) context the command fails
 listing them. Output defaults to the raw `result` (`-o json`); the exit code is non-zero
@@ -372,9 +454,10 @@ xano platform get <platform_id>
 #### Unit Tests
 
 ```bash
-# List unit tests
+# List unit tests (returns all tests by default; --per_page narrows the page)
 xano unit_test list
 xano unit_test list --branch dev --obj-type function
+xano unit_test list --page 2 --per_page 25
 
 # Run a single unit test
 xano unit_test run <unit_test_id>
@@ -388,9 +471,10 @@ xano unit_test run_all --branch dev --obj-type function
 #### Workflow Tests
 
 ```bash
-# List workflow tests
+# List workflow tests (returns all tests by default; --per_page narrows the page)
 xano workflow_test list
 xano workflow_test list --branch dev
+xano workflow_test list --page 2 --per_page 25
 
 # Get workflow test details
 xano workflow_test get <workflow_test_id>
@@ -404,10 +488,77 @@ xano workflow_test run <workflow_test_id>
 xano workflow_test run_all
 xano workflow_test run_all --branch dev
 
+# Run tests in parallel (default is 1 — sequential)
+xano unit_test run_all --concurrency 4
+xano workflow_test run_all --concurrency 4
+
+# Sandbox and tenant variants take the same paging flags
+xano sandbox unit_test list --page 2 --per_page 25
+xano sandbox workflow_test list --page 2 --per_page 25
+xano tenant unit_test list my-tenant --page 2 --per_page 25
+xano tenant workflow_test list my-tenant --page 2 --per_page 25
+
 # Delete a workflow test
 xano workflow_test delete <workflow_test_id>
 ```
 
+#### Running tests in parallel
+
+Every `run_all` command takes `--concurrency` (default `1`):
+
+```bash
+xano unit_test run_all --concurrency 4
+xano tenant unit_test run_all --tenant my-tenant --concurrency 8
+```
+
+Output stays in test order regardless of concurrency, so a parallel run is still diffable against a sequential one, and the JSON `results` array keeps a stable order.
+
+`run_all` discovers the test list by paging at 100 per request rather than asking for the whole suite in one response, and stops when the API reports no next page.
+
+**The default is 1 on purpose.** These tests execute against a shared workspace database, so tests that touch the same tables or records can interfere with each other when run at the same time — producing failures that look like flakiness rather than a real regression. Raise `--concurrency` once you know your tests are independent.
+
+#### Exit codes
+
+Every `run` and `run_all` command — on all four surfaces (`unit_test`, `workflow_test`, `sandbox`, `tenant`) — uses the same exit codes:
+
+| Code | Meaning |
+|------|---------|
+| `0` | All tests passed, **or** there were no tests to run |
+| `1` | At least one test failed |
+| `2` | The command could not run the tests at all — bad workspace, auth failure, unreadable profile, or the test-list request failed |
+
+**This is identical for `-o json` and summary output.** Adding `-o json` to get machine-readable output does not change the exit code, so a CI job can rely on it in either mode.
+
+```bash
+xano workflow_test run_all -o json || echo "tests failed or the command errored"
+```
+
+**One asymmetry worth knowing about.** In `run`, a non-2xx response from the run endpoint is a CLI error and exits `2`. In `run_all`, a non-2xx response for an *individual* test is recorded as a failed test result with an `API error <status>` message and contributes to exit `1` — because `run_all`'s job is to finish the batch and report a roll-up rather than abort on one test's transport error. Exit `2` in `run_all` is reserved for failures that stop the batch from starting at all.
+
+If you need to tell a backend outage apart from a genuine assertion failure, the exit code alone will not do it — inspect `results[].message` for the `API error` prefix:
+
+```bash
+xano workflow_test run_all -o json | jq '[.results[] | select(.message // "" | startswith("API error"))] | length'
+```
+
+#### JSON output
+
+`run` returns the API's result object unchanged. Treat **any** `status` other than `"ok"` as a failure — several distinct non-`ok` values are returned in practice, so match on "not `ok`" rather than enumerating known failure values:
+
+```json
+{ "status": "exception", "timing": 0.02, "message": "Precondition failed." }
+```
+
+`run_all` returns a roll-up. A branch with no tests is a normal state — freshly created branches routinely have none — and still emits valid JSON rather than plain text, so `JSON.parse` is always safe:
+
+```json
+{ "passed": 0, "failed": 0, "results": [], "total_timing": 0 }
+```
+
+The `total_timing` field is currently emitted by `workflow_test run_all` only; the `unit_test`, `tenant`, and `sandbox` variants omit it. The empty-suite envelope always carries the same keys as that command's populated envelope.
+
+> **Changed in this release:** a failing `run` in summary mode previously exited `2` and printed a spurious `EEXIT: 1` line; it now exits `1` with clean output. A failing `run` with `-o json` previously exited `0`, which silently hid failures from CI. If you match on exit code `2` specifically to detect test failures, switch to a non-zero check.
+
 ### Tenants
 
 Manage tenants, their environment variables, backups, deployments, and clusters.
@@ -425,9 +576,12 @@ xano tenant get <tenant_name>
 xano tenant create "My Tenant"
 xano tenant create "My Tenant" -d "Description" --type tier2 --cluster_id 1 --platform_id 5
 xano tenant create "My Tenant" --type tier2 --cluster_id 1 --license ./license.yaml
+xano tenant create "Production" --required_reviewers 1 --allow_deploy_bypass
 
 # Edit a tenant
 xano tenant edit <tenant_name> --display "New Name" -d "New description"
+xano tenant edit <tenant_name> --required_reviewers 1
+xano tenant edit <tenant_name> --required_reviewers 0
 
 # Delete a tenant (confirmation required)
 xano tenant delete <tenant_name>
@@ -478,6 +632,60 @@ xano tenant deploy_release <tenant_name> --release v1.0
 xano tenant deploy_platform <tenant_name> --platform_id 5 --license ./license.yaml
 ```
 
+If a tenant has `required_reviewers` set above 0, `tenant deploy_release` fails with an
+error naming the `tenant_deploy_request` command to run instead — see below.
+
+#### Tenant Deploy Requests
+
+When a tenant has `required_reviewers` set above 0 (see `tenant create`/`tenant edit`
+above), a release may only be deployed to it through an **approved deploy request**,
+requiring that many distinct reviewer approvals. An author with no deploy permission
+opens a request; a named reviewer who does hold deploy permission on the tenant votes to
+approve it, and once enough reviewers have approved, it deploys as part of that action.
+
+```bash
+# List deploy requests in a workspace (results show the target tenant and release)
+xano tenant_deploy_request list
+xano tenant_deploy_request list --tenant prod --status pending
+xano tenant_deploy_request list --tenant prod --release v1.2
+xano tenant_deploy_request list --to-review
+
+# Get details of a specific deploy request
+xano tenant_deploy_request get <id>
+
+# Open a deploy request (submits for review immediately unless --draft is passed)
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --reviewers 12,45
+xano tenant_deploy_request create "Deploy v1.2 to prod" --tenant prod --release v1.2 --draft
+
+# Edit a deploy request's title, description or reviewers
+xano tenant_deploy_request edit <id> --title "Deploy v1.2.1 to prod"
+xano tenant_deploy_request edit <id> --reviewers 12,45,67
+
+# Change status: draft, submit, approve, request_changes, close, or reopen
+# (approve records one reviewer's vote; once enough votes are in it deploys the
+# release as part of that same call)
+xano tenant_deploy_request set_status <id> --status submit
+xano tenant_deploy_request set_status <id> --status approve
+xano tenant_deploy_request set_status <id> --status request_changes --reason "Needs a migration note"
+xano tenant_deploy_request set_status <id> --status close --reason "Superseded by a newer request"
+xano tenant_deploy_request set_status <id> --status reopen
+
+# Link a newer release to a request after changes were requested (author only)
+xano tenant_deploy_request revision <id> --release v1.2.1 --note "Added the missing migration"
+
+# Deploy past the approval gate under the deploy-bypass permission (requires the
+# tenant's allow_deploy_bypass to be enabled, and a separately-grantable RBAC
+# permission). Every use is audited.
+xano tenant_deploy_request bypass <id> --reason "Prod incident, reviewer unavailable"
+```
+
+CI example (e.g. a GitHub Action step):
+
+```bash
+xano tenant_deploy_request create "$PR_TITLE" --tenant prod --release v1.2 \
+  --description "$PR_BODY" --reviewers 12,45 -o json
+```
+
 #### Tenant License
 
 ```bash
@@ -566,7 +774,7 @@ xano tenant cluster license set <cluster_id> --file ./kubeconfig.yaml
 
 ### Ephemeral Tenants
 
-Manage ephemeral tenants — short-lived, auto-expiring tenants scoped to a workspace (default TTL 1h, max 72h). Unlike a sandbox, an ephemeral tenant requires a workspace.
+Manage ephemeral tenants — short-lived, auto-expiring tenants scoped to a workspace (default TTL 1h, max 24h). Unlike a sandbox, an ephemeral tenant requires a workspace.
 
 ```bash
 # List ephemeral tenants in the current workspace
@@ -579,7 +787,7 @@ xano ephemeral list --global
 # Create an ephemeral tenant (workspace required)
 xano ephemeral create "PR preview"
 xano ephemeral create "Demo" --expires-hours 24 -w 5
-xano ephemeral create "Load test" -d "48h soak" --expires-hours 48
+xano ephemeral create "Load test" -d "overnight soak" --expires-hours 24
 
 # Get / edit / delete
 xano ephemeral get <tenant_name>
@@ -664,16 +872,19 @@ xano sandbox reset --force
 ### Static Hosts
 
 ```bash
-# List static hosts
+# List static hosts. Page size is fixed at 100 by the API, so there is no
+# --per_page flag; the footer reports the true total.
 xano static_host list
+xano static_host list --page 2
 
 # Create / get / edit a static host
 xano static_host create marketing --description "Marketing site"
 xano static_host get marketing
 xano static_host edit marketing --name marketing-v2 --description "Updated"
 
-# List builds
+# List builds (--page only; page size is fixed at 100 by the API)
 xano static_host build list default
+xano static_host build list default --page 2
 
 # Get build details
 xano static_host build get default --build_id 52

package/dist/base-command.d.ts

@@ -15,6 +15,11 @@ export interface CredentialsFile {
     };
 }
 export declare function buildUserAgent(version: string): string;
+/**
+ * True when `error` is the "foreign dispatcher rejected by built-in fetch"
+ * failure (Node 26+). The real code lives on `error.cause.code`.
+ */
+export declare function isInvalidDispatcherError(error: unknown): boolean;
 export interface SandboxTenant {
     created_at?: string;
     description?: string;

package/dist/base-command.js

@@ -29,13 +29,46 @@ function resolveRequestTimeoutMs(env = process.env) {
         return DEFAULT_REQUEST_TIMEOUT_MS;
     return parsed;
 }
+/**
+ * Whether the built-in `fetch` on this runtime accepts a dispatcher built from
+ * our bundled userland `undici`. Node <= 24 accepts it; Node 26 rejects a
+ * foreign dispatcher with UND_ERR_INVALID_ARG, which `fetch` surfaces only as
+ * the generic "fetch failed" — breaking *every* command (DEV-7773).
+ *
+ * Starts optimistic (`true`); flipped to `false` the first time a request fails
+ * with UND_ERR_INVALID_ARG (see `verboseFetch`, which then retries without the
+ * dispatcher). Once flipped, every later request skips the dispatcher outright.
+ */
+let dispatcherSupported = true;
+/**
+ * True when `error` is the "foreign dispatcher rejected by built-in fetch"
+ * failure (Node 26+). The real code lives on `error.cause.code`.
+ */
+export function isInvalidDispatcherError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const { cause } = error;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? cause.code
+        : error.code;
+    return code === 'UND_ERR_INVALID_ARG';
+}
 /**
  * Lazily-built undici dispatcher whose header/body inactivity timeouts match our
  * request timeout, so undici's internal 300s default never fires first. Built
  * once and reused across requests. `timeout === 0` means "no bound".
+ *
+ * Returns `undefined` when this runtime has been found to reject a foreign
+ * dispatcher (Node 26+, DEV-7773). Dropping the dispatcher does NOT regress the
+ * large-push timeout: the per-request `AbortSignal.timeout(timeoutMs)` in
+ * `verboseFetch` already bounds the whole request (headers included) to the same
+ * 15-min ceiling the dispatcher enforced, so undici's hidden 300s
+ * `headersTimeout` is subsumed by it.
  */
 let sharedDispatcher;
 function getRequestDispatcher(timeoutMs) {
+    if (!dispatcherSupported)
+        return undefined;
     if (timeoutMs === 0) {
         sharedDispatcher ??= new Agent({ bodyTimeout: 0, headersTimeout: 0 });
         return sharedDispatcher;
@@ -324,15 +357,20 @@ export default class BaseCommand extends Command {
             ...options.headers,
         };
         const timeoutMs = resolveRequestTimeoutMs();
-        const fetchOptions = {
+        // Build the fetch options fresh each attempt: a retry needs a new
+        // AbortSignal (the first attempt's may already be aborted/consumed) and,
+        // when the dispatcher is the culprit, no dispatcher at all.
+        const buildFetchOptions = (withDispatcher) => ({
             ...options,
             // undici dispatcher: lifts the hidden 300s headers/body timeout to our bound
-            dispatcher: getRequestDispatcher(timeoutMs),
+            ...(withDispatcher ? { dispatcher: getRequestDispatcher(timeoutMs) } : {}),
             headers,
             // belt-and-suspenders hard ceiling that also covers DNS/connect stalls;
             // surfaces as a clean AbortError (see describeNetworkError). 0 = no bound.
+            // This alone bounds the whole request, so dropping the dispatcher (Node 26)
+            // does not lose the large-push timeout protection.
             ...(timeoutMs > 0 && !options.signal ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
-        };
+        });
         const contentType = headers['Content-Type'] || 'application/json';
         if (verbose) {
             this.log('');
@@ -349,7 +387,26 @@ export default class BaseCommand extends Command {
             }
         }
         const startTime = Date.now();
-        const response = await fetch(url, fetchOptions);
+        let response;
+        try {
+            response = await fetch(url, buildFetchOptions(dispatcherSupported));
+        }
+        catch (error) {
+            // Node 26+ rejects our userland-undici dispatcher with UND_ERR_INVALID_ARG,
+            // surfaced only as "fetch failed" (DEV-7773). Disable it for the rest of the
+            // process and retry once without it; the AbortSignal.timeout ceiling above
+            // still bounds the request, so the large-push protection is preserved.
+            if (dispatcherSupported && isInvalidDispatcherError(error)) {
+                dispatcherSupported = false;
+                if (verbose) {
+                    this.log('  (this Node runtime rejected undici dispatcher; retrying without it — see DEV-7773)');
+                }
+                response = await fetch(url, buildFetchOptions(false));
+            }
+            else {
+                throw error;
+            }
+        }
         const elapsed = Date.now() - startTime;
         if (verbose) {
             this.log(`← ${response.status} ${response.statusText} (${elapsed}ms)`);

package/dist/commands/branch/list/index.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { buildPagingJson, formatPagingFooter } from '../../../utils/paging.js';
 export function filterBackups(branches, includeBackups) {
     return includeBackups ? branches : branches.filter((b) => !b.backup);
 }
@@ -82,7 +83,7 @@ Available branches:
             const branches = filterBackups(allBranches, flags.backups);
             // Output results
             if (flags.output === 'json') {
-                this.log(JSON.stringify(branches, null, 2));
+                this.log(JSON.stringify(buildPagingJson({ items: branches }, { tier: 'none' }), null, 2));
             }
             else {
                 // summary format
@@ -97,6 +98,9 @@ Available branches:
                         this.log(`  - ${branch.label}${liveIndicator}${backupIndicator}`);
                     }
                 }
+                const footer = formatPagingFooter({ items: branches }, { noun: 'branch', nounPlural: 'branches', tier: 'none' });
+                if (footer)
+                    this.log(footer);
             }
         }
         catch (error) {

package/dist/commands/ephemeral/create/index.js

@@ -14,7 +14,7 @@ Created ephemeral tenant: PR preview (e4f2-9ab1-...) - ID: 42
   Expires: in 1 hour
 `,
         `$ xano ephemeral create "Demo" --expires-hours 24 -w 114`,
-        `$ xano ephemeral create "Load test" --description "48h soak" --expires-hours 48 -o json`,
+        `$ xano ephemeral create "Load test" --description "overnight soak" --expires-hours 24 -o json`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -25,8 +25,8 @@ Created ephemeral tenant: PR preview (e4f2-9ab1-...) - ID: 42
         }),
         'expires-hours': Flags.integer({
             default: 1,
-            description: 'Hours until the tenant auto-expires (1-72)',
-            max: 72,
+            description: 'Hours until the tenant auto-expires (1-24)',
+            max: 24,
             min: 1,
             required: false,
         }),

package/dist/commands/ephemeral/list/index.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { buildPagingJson } from '../../../utils/paging.js';
 export default class EphemeralList extends BaseCommand {
     static description = 'List ephemeral tenants in a workspace, or across the whole instance with --global';
     static examples = [
@@ -73,7 +74,7 @@ Ephemeral tenants (all workspaces):
                 this.error('Unexpected API response format');
             }
             if (flags.output === 'json') {
-                this.log(JSON.stringify(tenants, null, 2));
+                this.log(JSON.stringify(buildPagingJson({ items: tenants }, { tier: 'none' }), null, 2));
             }
             else if (tenants.length === 0) {
                 this.log('No ephemeral tenants found');

package/dist/commands/ephemeral/pull/index.d.ts

@@ -16,10 +16,4 @@ export default class EphemeralPull extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    /**
-     * Sanitize a document name for use as a filename.
-     * Strips quotes, replaces spaces with underscores, and removes
-     * characters that are unsafe in filenames.
-     */
-    private sanitizeFilename;
 }

package/dist/commands/ephemeral/pull/index.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import snakeCase from 'lodash.snakecase';
 import BaseCommand from '../../../base-command.js';
-import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+import { buildApiGroupFolderResolver, buildChannelServerResolver, parseDocument, resolveDocumentPath, } from '../../../utils/document-parser.js';
 export default class EphemeralPull extends BaseCommand {
     static args = {
         tenant_name: Args.string({
@@ -130,96 +130,19 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         fs.mkdirSync(outputDir, { recursive: true });
         // Resolve api_group names to unique folder names, disambiguating collisions
         const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
+        // Resolve a realtime v2 channel path -> owning realtime_server name, so
+        // messages can nest under their channel's server (see resolver docs).
+        const getChannelServer = buildChannelServerResolver(documents);
         // Track filenames per type to handle duplicates
         const filenameCounters = new Map();
         let writtenCount = 0;
         for (const doc of documents) {
-            let typeDir;
-            let baseName;
-            if (doc.type === 'workspace') {
-                // workspace → workspace/{name}.xs
-                typeDir = path.join(outputDir, 'workspace');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'workspace_trigger') {
-                // workspace_trigger → workspace/trigger/{name}.xs
-                typeDir = path.join(outputDir, 'workspace', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'error_trigger') {
-                // error_trigger → workspace/trigger/{name}.xs (singleton, colocated with workspace triggers)
-                typeDir = path.join(outputDir, 'workspace', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'agent') {
-                // agent → ai/agent/{name}.xs
-                typeDir = path.join(outputDir, 'ai', 'agent');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'mcp_server') {
-                // mcp_server → ai/mcp_server/{name}.xs
-                typeDir = path.join(outputDir, 'ai', 'mcp_server');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'tool') {
-                // tool → ai/tool/{name}.xs
-                typeDir = path.join(outputDir, 'ai', 'tool');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'agent_trigger') {
-                // agent_trigger → ai/agent/trigger/{name}.xs
-                typeDir = path.join(outputDir, 'ai', 'agent', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'mcp_server_trigger') {
-                // mcp_server_trigger → ai/mcp_server/trigger/{name}.xs
-                typeDir = path.join(outputDir, 'ai', 'mcp_server', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'table_trigger') {
-                // table_trigger → table/trigger/{name}.xs
-                typeDir = path.join(outputDir, 'table', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'realtime_channel') {
-                // realtime_channel → realtime/channel/{name}.xs
-                typeDir = path.join(outputDir, 'realtime', 'channel');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'realtime_trigger') {
-                // realtime_trigger → realtime/trigger/{name}.xs
-                typeDir = path.join(outputDir, 'realtime', 'trigger');
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'api_group') {
-                // api_group "test" → api/{resolved_folder}/{name}.xs
-                const groupFolder = getApiGroupFolder(doc.name);
-                typeDir = path.join(outputDir, 'api', groupFolder);
-                baseName = this.sanitizeFilename(doc.name);
-            }
-            else if (doc.type === 'query' && doc.apiGroup) {
-                // query in group "test" → api/{resolved_folder}/{query_name}.xs
-                const groupFolder = getApiGroupFolder(doc.apiGroup);
-                const nameParts = doc.name.split('/');
-                const leafName = nameParts.pop();
-                const folderParts = nameParts.map((part) => snakeCase(part));
-                typeDir = path.join(outputDir, 'api', groupFolder, ...folderParts);
-                baseName = this.sanitizeFilename(leafName);
-                if (doc.verb) {
-                    baseName = `${baseName}_${doc.verb}`;
-                }
-            }
-            else {
-                // Default: split folder path from name
-                const nameParts = doc.name.split('/');
-                const leafName = nameParts.pop();
-                const folderParts = nameParts.map((part) => snakeCase(part));
-                typeDir = path.join(outputDir, doc.type, ...folderParts);
-                baseName = this.sanitizeFilename(leafName);
-                if (doc.verb) {
-                    baseName = `${baseName}_${doc.verb}`;
-                }
-            }
+            const { baseName, typeDir } = resolveDocumentPath(doc, outputDir, {
+                getApiGroupFolder,
+                getChannelServer,
+                join: path.join,
+                snakeCase,
+            });
             fs.mkdirSync(typeDir, { recursive: true });
             // Track duplicates per directory
             const dirKey = path.relative(outputDir, typeDir);
@@ -238,12 +161,4 @@ Pulled 58 documents from tenant e4f2-9ab1-xyz1
         }
         this.log(`Pulled ${writtenCount} documents from tenant ${tenantName} to ${flags.directory}`);
     }
-    /**
-     * Sanitize a document name for use as a filename.
-     * Strips quotes, replaces spaces with underscores, and removes
-     * characters that are unsafe in filenames.
-     */
-    sanitizeFilename(name) {
-        return snakeCase(name.replaceAll('"', ''));
-    }
 }

package/dist/commands/ephemeral/push/index.d.ts

@@ -16,10 +16,20 @@ export default class EphemeralPush extends BaseCommand {
         sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         transaction: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         truncate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'wait-timeout': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * Poll GET .../tenant/{name}/microservice until auto microservices settle.
+     * Renders a one-line-per-microservice progress view that updates in place, then
+     * exits non-zero if any auto microservice failed or the wait timed out.
+     */
+    private waitForDeploy;
+    /** Number of lines the last progress render wrote (for in-place TTY updates). */
+    private lastRenderLines;
 }