@impetik/xeer-mcp 0.2.12 → 0.2.14

package/README.md

@@ -71,18 +71,19 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer_promote` | `promote.operator` | `operator` | Promote an exact review receipt in operator mode. | `directory?`: `string`<br>`receiptId`: `string`<br>`controlUrl?`: `string` | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | A human must review the exact artifact and start xeer-mcp with XEER_MCP_PROFILE=operator. |
 | `xeer_auth_status` | `auth.status` | `author` / `operator` | Report builder credential metadata. | `controlUrl?`: `string` | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 | `xeer_inspect` | `inspect` | `author` / `operator` | Read a running application manifest. | `previewUrl`: `string`<br>`view?`: `manifest` / `state` / `logs` / `export`; default `manifest`<br>`after?`: `string` | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | none |
-| `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
+| `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`share?`: `boolean`<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
 | `xeer_dev_status` | `dev.status` | `author` / `operator` | Read new events from a local development session. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0`<br>`waitMilliseconds?`: `integer` [0..600000]; default `0`<br>`limit?`: `integer` [1..1000]; default `200` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
 | `xeer_dev_stop` | `dev.stop` | `author` / `operator` | Stop a local development session and release its lease. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0` | `run-local` | writes; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
 | `xeer_diagnostics` | `diagnostics` | `author` / `operator` | Explain one emitted diagnostic code. | `code`: `string` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 
-**CLI actions intentionally excluded from MCP (34).**
+**CLI actions intentionally excluded from MCP (35).**
 
 | CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `xeer agent setup` | `agent.setup` | Install or verify project-confined agent adapters. | `read-source`<br>`write-source` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer deploy` | `deploy` | Build and deploy an application artifact. | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | MCP exposes a separate preview-only deploy action; direct production deploy stays CLI-only. |
 | `xeer promote` | `promote` | Promote a preview artifact to production. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | MCP promotion is a separate action available only when the server starts in operator profile. |
+| `xeer tunnel` | `tunnel.start` | Expose a loopback HTTP server through an authenticated tunnel. | `run-local`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `none` | `xeer.tunnel.cli.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer link` | `link` | Link a checkout to an application the builder owns. | `read-source`<br>`write-source`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Human identity and project ownership decisions are not delegated through MCP. |
 | `xeer deployments` | `deployments` | List deployment history for an application. | `network-read`<br>`read-state`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer rollback` | `rollback` | Redeploy a previously deployed artifact. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |

package/dist/dev-session.d.ts

@@ -34,6 +34,11 @@ export interface DevSessionSummary {
     generation?: number;
     artifactId?: string;
     preview?: PreviewUrls;
+    tunnel?: {
+        url: string;
+        tunnelId: string;
+        leaseExpiresAt: string;
+    };
     /** Diagnostics from the most recent compile attempt. Empty once a rebuild is accepted. */
     openDiagnostics: Diagnostic[];
     exit?: {
@@ -51,6 +56,7 @@ export interface DevSessionOptions {
     directory: string;
     host?: string;
     port?: number;
+    share?: boolean;
 }
 export declare class DevSession {
     #private;

package/dist/dev-session.js

@@ -21,6 +21,8 @@ export class DevSession {
     #cursor = 0;
     #status = 'starting';
     #preview;
+    #tunnel;
+    #expectsTunnel;
     #generation;
     #artifactId;
     #openDiagnostics = [];
@@ -35,10 +37,12 @@ export class DevSession {
     constructor(sessionId, options) {
         this.sessionId = sessionId;
         this.directory = options.directory;
+        this.#expectsTunnel = options.share === true;
         // Port 0 is the documented automation mode: the OS picks a free port and the
         // preview.ready event reports it, so parallel sessions cannot collide.
         const args = ['dev', options.directory, '--json',
-            '--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 0)];
+            '--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 0),
+            ...(options.share ? ['--share'] : [])];
         this.#child = fork(resolveXeerCli(), args, {
             cwd: options.directory,
             stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
@@ -140,9 +144,22 @@ export class DevSession {
                 break;
             case 'preview.ready':
                 this.#preview = event.data;
-                this.#status = 'ready';
+                if (!this.#expectsTunnel)
+                    this.#status = 'ready';
                 this.#compiling = false;
                 break;
+            case 'tunnel.ready': {
+                const data = event.data;
+                if (typeof data.url === 'string' && typeof data.tunnelId === 'string'
+                    && typeof data.leaseExpiresAt === 'string') {
+                    this.#tunnel = { url: data.url, tunnelId: data.tunnelId, leaseExpiresAt: data.leaseExpiresAt };
+                    this.#status = 'ready';
+                }
+                break;
+            }
+            case 'tunnel.closed':
+                this.#tunnel = undefined;
+                break;
             case 'process.exit': {
                 const data = event.data;
                 this.#exit = { ...(typeof data.code === 'number' ? { code: data.code } : {}), ...(data.reason ? { reason: data.reason } : {}) };
@@ -219,6 +236,7 @@ export class DevSession {
             ...(this.#generation === undefined ? {} : { generation: this.#generation }),
             ...(this.#artifactId === undefined ? {} : { artifactId: this.#artifactId }),
             ...(this.#preview ? { preview: this.#preview } : {}),
+            ...(this.#tunnel ? { tunnel: this.#tunnel } : {}),
             openDiagnostics: [...this.#openDiagnostics],
             ...(this.#exit ? { exit: this.#exit } : {}),
             droppedEvents: this.#dropped,

package/dist/server.js

@@ -433,6 +433,11 @@ export function createXeerMcpServer(options = {}) {
             debugUrl: z.string(),
             logsUrl: z.string(),
         }).loose().optional(),
+        tunnel: z.object({
+            url: z.string(),
+            tunnelId: z.string(),
+            leaseExpiresAt: z.string(),
+        }).loose().optional(),
         openDiagnostics: z.array(diagnosticSchema),
         exit: z.object({ code: z.number().optional(), reason: z.string().optional() }).loose().optional(),
         droppedEvents: z.number(),
@@ -454,13 +459,14 @@ export function createXeerMcpServer(options = {}) {
     server.registerTool('xeer_dev_start', {
         ...toolPolicy('dev.start'),
         outputSchema: wrappedOutput(z.object(sessionOutput).loose()),
-    }, async ({ directory, host, port, timeoutMilliseconds }) => withDirectory(directory, 'dev.start', async (resolved) => {
+    }, async ({ directory, host, port, share, timeoutMilliseconds }) => withDirectory(directory, 'dev.start', async (resolved) => {
         let session;
         try {
             session = devSessions.start({
                 directory: resolved,
                 ...(host ? { host } : {}),
                 ...(port === undefined ? {} : { port }),
+                ...(share === undefined ? {} : { share }),
             });
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.12"
+    "@impetik/xeer": "0.2.14"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -47,8 +47,12 @@ export interface XeerActionDefinition {
     readonly command: readonly string[];
     readonly aliases?: readonly (readonly string[])[];
     readonly summary: string;
+    /** Optional command-specific detail rendered only by focused `xeer <command> --help`. */
+    readonly description?: string;
     /** Help syntax without the `xeer ` prefix. May contain `{{templates}}`. */
     readonly usage: readonly string[];
+    /** Optional abbreviated syntax for the global command list. Full usage remains authoritative. */
+    readonly globalUsage?: readonly string[];
     readonly hiddenFromHelp?: boolean;
     readonly helpOrder?: number;
     readonly outputProtocol: string;
@@ -71,6 +75,15 @@ export interface XeerActionDefinition {
         readonly mcpExclusion?: string;
     };
 }
+export interface XeerCliCommandGroupDefinition {
+    readonly command: string;
+    readonly summary: string;
+}
+/**
+ * Human-facing summaries for command families. Membership and ordering still come from the action
+ * registry; this only supplies the sentence that no individual subcommand can describe honestly.
+ */
+export declare const XEER_CLI_COMMAND_GROUPS: readonly XeerCliCommandGroupDefinition[];
 export interface XeerCliOptionDefinition {
     readonly name: string;
     readonly takesValue: boolean;
@@ -180,6 +193,7 @@ declare const actions: readonly [{
     readonly id: "new";
     readonly command: readonly ["new"];
     readonly summary: "Create a new project from a supported scaffold.";
+    readonly description: string;
     readonly usage: readonly ["new <directory> [--template {{templates}}] [--json]"];
     readonly helpOrder: 30;
     readonly outputProtocol: "xeer.command.v0";
@@ -329,6 +343,7 @@ declare const actions: readonly [{
     readonly id: "deploy";
     readonly command: readonly ["deploy"];
     readonly summary: "Build and deploy an application artifact.";
+    readonly description: string;
     readonly usage: readonly ["deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 50;
     readonly outputProtocol: "xeer.command.v0";
@@ -346,6 +361,7 @@ declare const actions: readonly [{
     readonly id: "promote";
     readonly command: readonly ["promote"];
     readonly summary: "Promote a preview artifact to production.";
+    readonly description: string;
     readonly usage: readonly [string];
     readonly helpOrder: 80;
     readonly outputProtocol: "xeer.command.v0";
@@ -464,6 +480,7 @@ declare const actions: readonly [{
     readonly id: "inspect";
     readonly command: readonly ["inspect"];
     readonly summary: "Read a running application manifest.";
+    readonly description: string;
     readonly usage: readonly ["inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 230;
     readonly outputProtocol: "xeer.command.v0";
@@ -503,10 +520,10 @@ declare const actions: readonly [{
     readonly id: "dev.start";
     readonly command: readonly ["dev"];
     readonly summary: "Start a local development session.";
-    readonly usage: readonly ["dev [directory] [--host <host>] [--port <port>] [--json]"];
+    readonly usage: readonly [string];
     readonly helpOrder: 220;
     readonly outputProtocol: "xeer.dev.v0";
-    readonly effects: readonly ["read-source", "write-generated", "run-local", "write-state"];
+    readonly effects: readonly ["read-source", "write-generated", "run-local", "write-state", "network-read", "network-write"];
     readonly idempotent: false;
     readonly reversible: true;
     readonly destructive: false;
@@ -530,6 +547,10 @@ declare const actions: readonly [{
                     readonly minimum: 0;
                     readonly maximum: 65535;
                 };
+                readonly share: {
+                    readonly description: "Publish the session through an authenticated Xeer tunnel.";
+                    readonly type: "boolean";
+                };
                 readonly timeoutMilliseconds: {
                     readonly type: "integer";
                     readonly minimum: 1000;
@@ -543,6 +564,24 @@ declare const actions: readonly [{
         readonly mcpTool: "xeer_dev_start";
         readonly mcpProfiles: readonly ["author", "operator"];
     };
+}, {
+    readonly id: "tunnel.start";
+    readonly command: readonly ["tunnel"];
+    readonly summary: "Expose a loopback HTTP server through an authenticated tunnel.";
+    readonly usage: readonly [string];
+    readonly globalUsage: readonly ["tunnel <port|loopback-url> [options]"];
+    readonly helpOrder: 225;
+    readonly outputProtocol: "xeer.tunnel.cli.v0";
+    readonly effects: readonly ["run-local", "network-read", "network-write"];
+    readonly idempotent: false;
+    readonly reversible: true;
+    readonly destructive: false;
+    readonly humanPrerequisites: readonly ["A human must sign in and deliberately keep the public tunnel process running."];
+    readonly pathPolicy: "none";
+    readonly surfaces: {
+        readonly cli: true;
+        readonly mcpExclusion: "Not exposed through MCP v0; use the CLI deliberately.";
+    };
 }, {
     readonly id: "dev.status";
     readonly command: readonly ["dev"];
@@ -676,6 +715,7 @@ declare const actions: readonly [{
     readonly id: "deployments";
     readonly command: readonly ["deployments"];
     readonly summary: "List deployment history for an application.";
+    readonly description: string;
     readonly usage: readonly ["deployments [app|directory] [--limit <n>] [--control-url <url>] [--json]"];
     readonly helpOrder: 70;
     readonly outputProtocol: "xeer.command.v0";
@@ -693,6 +733,7 @@ declare const actions: readonly [{
     readonly id: "rollback";
     readonly command: readonly ["rollback"];
     readonly summary: "Redeploy a previously deployed artifact.";
+    readonly description: string;
     readonly usage: readonly ["rollback [app|directory] <artifactId> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 90;
     readonly outputProtocol: "xeer.command.v0";
@@ -710,6 +751,7 @@ declare const actions: readonly [{
     readonly id: "disable";
     readonly command: readonly ["disable"];
     readonly summary: "Take an application offline without deleting its data.";
+    readonly description: string;
     readonly usage: readonly ["disable [app|directory] [--control-url <url>] [--json]"];
     readonly helpOrder: 100;
     readonly outputProtocol: "xeer.command.v0";
@@ -744,6 +786,7 @@ declare const actions: readonly [{
     readonly id: "delete";
     readonly command: readonly ["delete"];
     readonly summary: "Permanently delete an application and all of its data.";
+    readonly description: string;
     readonly usage: readonly ["delete [app|directory] --confirm <application> [--control-url <url>] [--json]"];
     readonly helpOrder: 120;
     readonly outputProtocol: "xeer.command.v0";
@@ -848,6 +891,7 @@ declare const actions: readonly [{
     readonly id: "state.read";
     readonly command: readonly ["state"];
     readonly summary: "Read record counts from a running application.";
+    readonly description: string;
     readonly usage: readonly ["state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 260;
     readonly outputProtocol: "xeer.command.v0";
@@ -882,6 +926,7 @@ declare const actions: readonly [{
     readonly id: "logs";
     readonly command: readonly ["logs"];
     readonly summary: "Read the bounded log ring of a running application.";
+    readonly description: string;
     readonly usage: readonly ["logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]"];
     readonly helpOrder: 280;
     readonly outputProtocol: "xeer.command.v0";
@@ -899,6 +944,7 @@ declare const actions: readonly [{
     readonly id: "export";
     readonly command: readonly ["export"];
     readonly summary: "Export application state to a document.";
+    readonly description: string;
     readonly usage: readonly ["export <local-url|app> [--environment prod|preview] [--out <file>] [--control-url <url>] [--json]", "export --state <dev|preview> [directory] [--out <file>] [--json]"];
     readonly helpOrder: 290;
     readonly outputProtocol: "xeer.command.v0";
@@ -916,6 +962,7 @@ declare const actions: readonly [{
     readonly id: "import";
     readonly command: readonly ["import"];
     readonly summary: "Replace local or preview state from an export document.";
+    readonly description: string;
     readonly usage: readonly ["import <preview-url> <file> [--json]", "import --state <dev|preview> [directory] <file> [--json]"];
     readonly helpOrder: 300;
     readonly outputProtocol: "xeer.command.v0";

package/vendor/spec/actions.js

@@ -4,6 +4,20 @@ export const ACTION_REGISTRY_PROTOCOL = 'xeer.actions.v0';
 export const XEER_MCP_PROFILES = ['author', 'operator'];
 export const XEER_ARTIFACT_ID_PATTERN = '^sha256:[a-f0-9]{64}$';
 export const MCP_INPUT_SCHEMA_DRAFT = 'http://json-schema.org/draft-07/schema#';
+/**
+ * Human-facing summaries for command families. Membership and ordering still come from the action
+ * registry; this only supplies the sentence that no individual subcommand can describe honestly.
+ */
+export const XEER_CLI_COMMAND_GROUPS = Object.freeze([
+    { command: 'agent', summary: 'Set up agent integrations and inspect normalized project context.' },
+    { command: 'docs', summary: 'Search the documentation bundled with this Xeer version.' },
+    { command: 'auth', summary: 'Manage builder credentials and local development personas.' },
+    { command: 'domains', summary: 'Manage an application\'s platform and custom domains.' },
+    { command: 'state', summary: 'Inspect running application state or reset local state.' },
+    { command: 'env', summary: 'Manage application environment values and secrets.' },
+    { command: 'token', summary: 'Manage service builder tokens.' },
+    { command: 'db', summary: 'Inspect and query a running application database.' },
+]);
 const NOT_EXPOSED_V0 = 'Not exposed through MCP v0; use the CLI deliberately.';
 const HUMAN_IDENTITY = 'Human identity and project ownership decisions are not delegated through MCP.';
 const SECRET_VALUES = 'Secret values are intentionally unreachable through MCP; env pull returns plaintext.';
@@ -179,6 +193,9 @@ const actions = [
     },
     {
         id: 'new', command: ['new'], summary: 'Create a new project from a supported scaffold.',
+        description: 'Creates a complete project that checks, tests, and builds clean. Templates do not '
+            + 'scaffold sign-in UI: every visitor already has a verified identity, and the generated README '
+            + 'explains how to opt in to a persistent account.',
         usage: ['new <directory> [--template {{templates}}] [--json]'], helpOrder: 30,
         outputProtocol: 'xeer.command.v0', effects: ['write-source'], idempotent: false,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
@@ -250,6 +267,8 @@ const actions = [
     },
     {
         id: 'deploy', command: ['deploy'], summary: 'Build and deploy an application artifact.',
+        description: 'Deploys to production by default. Use --environment preview for a separate preview '
+            + 'Worker, URL, environment values, and disposable data so you can review a release before it goes live.',
         usage: ['deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 50,
         outputProtocol: 'xeer.command.v0',
         effects: ['read-source', 'write-generated', 'run-local', 'network-read', 'network-write', 'production-change'],
@@ -259,6 +278,9 @@ const actions = [
     },
     {
         id: 'promote', command: ['promote'], summary: 'Promote a preview artifact to production.',
+        description: 'Makes the exact artifact serving in preview live in production without rebuilding it. '
+            + '--receipt uses the immutable review record from a preview deploy; --from-artifact is the direct '
+            + 'human override for a retained artifact.',
         usage: ['promote [app|directory] [--receipt <receiptId> | --from-artifact <artifactId>] '
                 + '[--control-url <url>] [--json]'], helpOrder: 80,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
@@ -315,6 +337,9 @@ const actions = [
     },
     {
         id: 'inspect', command: ['inspect'], summary: 'Read a running application manifest.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 230,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -337,8 +362,9 @@ const actions = [
     },
     {
         id: 'dev.start', command: ['dev'], summary: 'Start a local development session.',
-        usage: ['dev [directory] [--host <host>] [--port <port>] [--json]'], helpOrder: 220,
-        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
+        usage: ['dev [directory] [--host <host>] [--port <port>] [--share] [--control-url <url>] '
+                + '[--tunnel-bootstrap <file>] [--json]'], helpOrder: 220,
+        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state', 'network-read', 'network-write'],
         idempotent: false, reversible: true, destructive: false, humanPrerequisites: [],
         pathPolicy: 'project-relative', surfaces: {
             cli: true, mcpTool: 'xeer_dev_start', mcpProfiles: XEER_MCP_PROFILES,
@@ -347,10 +373,24 @@ const actions = [
                     directory: PROJECT_DIRECTORY_INPUT,
                     host: { description: 'Defaults to 127.0.0.1.', type: 'string' },
                     port: { description: 'Defaults to 0 (OS-assigned).', type: 'integer', minimum: 0, maximum: 65_535 },
+                    share: { description: 'Publish the session through an authenticated Xeer tunnel.', type: 'boolean' },
                     timeoutMilliseconds: { type: 'integer', minimum: 1_000, maximum: 600_000 },
                 } },
         },
     },
+    {
+        id: 'tunnel.start', command: ['tunnel'], summary: 'Expose a loopback HTTP server through an authenticated tunnel.',
+        usage: ['tunnel <port|loopback-url> [--label <name>] [--host-header <preserve|rewrite|host>] '
+                + '[--request-header-add <name:value>] [--request-header-remove <name>] '
+                + '[--response-header-add <name:value>] [--response-header-remove <name>] '
+                + '[--upstream-tls-insecure] [--lifetime <seconds>] [--control-url <url>] [--json]'],
+        globalUsage: ['tunnel <port|loopback-url> [options]'],
+        helpOrder: 225, outputProtocol: 'xeer.tunnel.cli.v0',
+        effects: ['run-local', 'network-read', 'network-write'], idempotent: false,
+        reversible: true, destructive: false,
+        humanPrerequisites: ['A human must sign in and deliberately keep the public tunnel process running.'],
+        pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
     {
         id: 'dev.status', command: ['dev'], summary: 'Read new events from a local development session.',
         usage: [], outputProtocol: 'xeer.dev.v0', effects: [], idempotent: true, reversible: true,
@@ -408,6 +448,8 @@ const actions = [
     },
     {
         id: 'deployments', command: ['deployments'], summary: 'List deployment history for an application.',
+        description: 'Lists the newest deployments first and marks the version serving each environment. '
+            + 'With no target, it uses the application linked to the current directory.',
         usage: ['deployments [app|directory] [--limit <n>] [--control-url <url>] [--json]'], helpOrder: 70,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state', 'secret-metadata'],
         idempotent: true, reversible: true, destructive: false,
@@ -416,6 +458,8 @@ const actions = [
     },
     {
         id: 'rollback', command: ['rollback'], summary: 'Redeploy a previously deployed artifact.',
+        description: 'Creates a new deployment from a retained artifact instead of rewriting history. Use the '
+            + 'artifact ID from xeer deployments; current environment values are injected at deployment time.',
         usage: ['rollback [app|directory] <artifactId> [--environment prod|preview] [--control-url <url>] [--json]'],
         helpOrder: 90, outputProtocol: 'xeer.command.v0',
         effects: ['network-read', 'network-write', 'production-change'], idempotent: false,
@@ -425,6 +469,8 @@ const actions = [
     },
     {
         id: 'disable', command: ['disable'], summary: 'Take an application offline without deleting its data.',
+        description: 'Returns 410 Gone for application requests while preserving the Worker, stored data, and '
+            + 'environment values. Run xeer enable to restore service.',
         usage: ['disable [app|directory] [--control-url <url>] [--json]'], helpOrder: 100,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
         idempotent: true, reversible: true, destructive: false,
@@ -441,6 +487,8 @@ const actions = [
     },
     {
         id: 'delete', command: ['delete'], summary: 'Permanently delete an application and all of its data.',
+        description: 'Destroys the deployed Worker and stored data, stops the origin resolving, and permanently '
+            + 'retires the app ID. The exact application name is required with --confirm.',
         usage: ['delete [app|directory] --confirm <application> [--control-url <url>] [--json]'], helpOrder: 120,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'write-state', 'production-change'],
         idempotent: false, reversible: false, destructive: true,
@@ -490,6 +538,9 @@ const actions = [
     },
     {
         id: 'state.read', command: ['state'], summary: 'Read record counts from a running application.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 260,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -505,6 +556,9 @@ const actions = [
     },
     {
         id: 'logs', command: ['logs'], summary: 'Read the bounded log ring of a running application.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]'],
         helpOrder: 280, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'],
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -512,6 +566,8 @@ const actions = [
     },
     {
         id: 'export', command: ['export'], summary: 'Export application state to a document.',
+        description: 'Reads a local URL directly or a deployed application through the signed-in builder. '
+            + 'Use --state to export from the xeer dev or xeer preview server running for a project directory.',
         usage: [
             'export <local-url|app> [--environment prod|preview] [--out <file>] [--control-url <url>] [--json]',
             'export --state <dev|preview> [directory] [--out <file>] [--json]',
@@ -522,6 +578,8 @@ const actions = [
     },
     {
         id: 'import', command: ['import'], summary: 'Replace local or preview state from an export document.',
+        description: 'Replaces the selected state wholesale. Direct URLs must point to preview; --state imports '
+            + 'into the xeer dev or xeer preview server running for a project directory. Production import is refused.',
         usage: [
             'import <preview-url> <file> [--json]',
             'import --state <dev|preview> [directory] <file> [--json]',

package/vendor/spec/index.d.ts

@@ -19,3 +19,4 @@ export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
 export * from './template.js';
+export * from './tunnel.js';

package/vendor/spec/index.js

@@ -19,3 +19,4 @@ export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
 export * from './template.js';
+export * from './tunnel.js';

package/vendor/spec/tunnel.d.ts

@@ -0,0 +1,109 @@
+export declare const TUNNEL_PROTOCOL: "xeer.tunnel.v0";
+export declare const TUNNEL_GRANT_AUDIENCE: "xeer-tunnel";
+export declare const TUNNEL_GRANT_TYP: "xeer-tunnel-grant+jws";
+export declare const TUNNEL_FALLBACK_AUDIENCE: "xeer-tunnel-fallback";
+export declare const TUNNEL_FALLBACK_TYP: "xeer-tunnel-fallback+jws";
+export declare const TUNNEL_TICKET_HEADER: "x-xeer-tunnel-ticket";
+export declare const TUNNEL_CONTROL_HEADER: "x-xeer-tunnel-control";
+export declare const TUNNEL_SHARED_HEADER: "x-xeer-shared-dev";
+export declare const TUNNEL_SHARED_HOST_HEADER: "x-xeer-shared-host";
+export declare const TUNNEL_PROFILES: readonly ["shared-dev", "raw-http"];
+export type TunnelProfile = (typeof TUNNEL_PROFILES)[number];
+export declare const TUNNEL_BINARY_HEADER_BYTES = 12;
+export declare const TUNNEL_MAX_FRAME_PAYLOAD = 65536;
+export type TunnelBinaryOpcode = 0x01 | 0x02 | 0x03;
+export interface TunnelBinaryFrame {
+    readonly opcode: TunnelBinaryOpcode;
+    readonly final: boolean;
+    readonly streamId: number;
+    /** Starts at zero and advances independently per sender and stream. */
+    readonly seq: number;
+    readonly payload: Uint8Array;
+}
+export interface TunnelLimits {
+    readonly maxBandwidthBytes: number;
+    readonly maxLifetimeSeconds: number;
+    readonly maxConcurrentStreams: number;
+    readonly connectionWindowBytes: number;
+    readonly streamWindowBytes: number;
+    readonly streamIdleSeconds: number;
+}
+export interface TunnelAgentBootstrap {
+    readonly protocol: typeof TUNNEL_PROTOCOL;
+    readonly profile: TunnelProfile;
+    readonly tunnelId: string;
+    readonly url: string;
+    readonly resumeSecret: string;
+    readonly connect: {
+        readonly url: string;
+        readonly ticket: string;
+        readonly ticketExpiresAt: string;
+    };
+    readonly leaseExpiresAt: string;
+    readonly issuerEpoch: number;
+    readonly limits: TunnelLimits;
+}
+export interface TunnelAllocation extends TunnelAgentBootstrap {
+    readonly slug: string;
+    readonly controlSecret: string;
+}
+export type TunnelControlFrame = {
+    readonly t: 'hello';
+    readonly protocol: typeof TUNNEL_PROTOCOL;
+    readonly tunnelId: string;
+    readonly takeover: boolean;
+} | {
+    readonly t: 'ready';
+    readonly tunnelId: string;
+    readonly leaseExpiresAt: string;
+    readonly limits: TunnelLimits;
+    readonly credit: {
+        readonly connectionBytes: number;
+        readonly streamBytes: number;
+    };
+} | {
+    readonly t: 'open';
+    readonly streamId: number;
+    readonly method: string;
+    readonly path: string;
+    readonly headers: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'upgrade';
+    readonly streamId: number;
+    readonly path: string;
+    readonly headers: readonly (readonly [string, string])[];
+    readonly protocols: readonly string[];
+} | {
+    readonly t: 'head';
+    readonly streamId: number;
+    readonly status: number;
+    readonly headers: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'upgrade.result';
+    readonly streamId: number;
+    readonly accepted: boolean;
+    readonly protocol?: string;
+    readonly headers?: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'end';
+    readonly streamId: number;
+} | {
+    readonly t: 'ws.close';
+    readonly streamId: number;
+    readonly code: number;
+    readonly reason: string;
+} | {
+    readonly t: 'window.update';
+    readonly streamId: number;
+    readonly bytes: number;
+} | {
+    readonly t: 'reset';
+    readonly streamId: number;
+    readonly reason: TunnelResetReason;
+};
+export type TunnelResetReason = 'visitor_disconnect' | 'agent_error' | 'agent_refused' | 'revoked' | 'lease_expired' | 'slow_consumer' | 'flow_control_violation' | 'protocol_error' | 'replaced';
+export declare function encodeTunnelBinaryFrame(frame: TunnelBinaryFrame): Uint8Array;
+export declare function decodeTunnelBinaryFrame(input: ArrayBuffer | ArrayBufferView): TunnelBinaryFrame;
+export declare function parseTunnelControlFrame(input: string): TunnelControlFrame;
+export declare function sanitizeTunnelRequestHeaders(headers: Headers, profile?: TunnelProfile): Array<[string, string]>;
+export declare function sanitizeTunnelResponseHeaders(headers: readonly (readonly [string, string])[], profile?: TunnelProfile): Headers;

package/vendor/spec/tunnel.js

@@ -0,0 +1,228 @@
+export const TUNNEL_PROTOCOL = 'xeer.tunnel.v0';
+export const TUNNEL_GRANT_AUDIENCE = 'xeer-tunnel';
+export const TUNNEL_GRANT_TYP = 'xeer-tunnel-grant+jws';
+export const TUNNEL_FALLBACK_AUDIENCE = 'xeer-tunnel-fallback';
+export const TUNNEL_FALLBACK_TYP = 'xeer-tunnel-fallback+jws';
+export const TUNNEL_TICKET_HEADER = 'x-xeer-tunnel-ticket';
+export const TUNNEL_CONTROL_HEADER = 'x-xeer-tunnel-control';
+export const TUNNEL_SHARED_HEADER = 'x-xeer-shared-dev';
+export const TUNNEL_SHARED_HOST_HEADER = 'x-xeer-shared-host';
+export const TUNNEL_PROFILES = ['shared-dev', 'raw-http'];
+export const TUNNEL_BINARY_HEADER_BYTES = 12;
+export const TUNNEL_MAX_FRAME_PAYLOAD = 65_536;
+function uint32(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new RangeError(`${field} must be a uint32.`);
+    }
+}
+export function encodeTunnelBinaryFrame(frame) {
+    uint32(frame.streamId, 'streamId');
+    if (frame.streamId === 0)
+        throw new RangeError('streamId zero is reserved for connection control.');
+    uint32(frame.seq, 'seq');
+    if (![0x01, 0x02, 0x03].includes(frame.opcode))
+        throw new RangeError('Unknown tunnel binary opcode.');
+    if (frame.payload.byteLength > TUNNEL_MAX_FRAME_PAYLOAD) {
+        throw new RangeError(`Tunnel payload exceeds ${TUNNEL_MAX_FRAME_PAYLOAD} bytes.`);
+    }
+    const encoded = new Uint8Array(TUNNEL_BINARY_HEADER_BYTES + frame.payload.byteLength);
+    const view = new DataView(encoded.buffer);
+    view.setUint8(0, 0);
+    view.setUint8(1, frame.opcode);
+    view.setUint8(2, frame.final ? 1 : 0);
+    view.setUint8(3, 0);
+    view.setUint32(4, frame.streamId);
+    view.setUint32(8, frame.seq);
+    encoded.set(frame.payload, TUNNEL_BINARY_HEADER_BYTES);
+    return encoded;
+}
+export function decodeTunnelBinaryFrame(input) {
+    const bytes = input instanceof ArrayBuffer
+        ? new Uint8Array(input)
+        : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    if (bytes.byteLength < TUNNEL_BINARY_HEADER_BYTES)
+        throw new RangeError('Tunnel binary frame is truncated.');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint8(0) !== 0 || view.getUint8(3) !== 0 || (view.getUint8(2) & 0xfe) !== 0) {
+        throw new RangeError('Tunnel binary frame header is invalid.');
+    }
+    const opcode = view.getUint8(1);
+    if (opcode !== 0x01 && opcode !== 0x02 && opcode !== 0x03) {
+        throw new RangeError('Unknown tunnel binary opcode.');
+    }
+    const streamId = view.getUint32(4);
+    if (streamId === 0)
+        throw new RangeError('streamId zero is reserved for connection control.');
+    const payload = bytes.slice(TUNNEL_BINARY_HEADER_BYTES);
+    if (payload.byteLength > TUNNEL_MAX_FRAME_PAYLOAD)
+        throw new RangeError('Tunnel binary payload is too large.');
+    return { opcode, final: view.getUint8(2) === 1, streamId, seq: view.getUint32(8), payload };
+}
+export function parseTunnelControlFrame(input) {
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch {
+        throw new TypeError('Tunnel control frame is not JSON.');
+    }
+    if (!value || typeof value !== 'object' || typeof value.t !== 'string') {
+        throw new TypeError('Tunnel control frame has no type.');
+    }
+    const frame = value;
+    const streamId = (allowZero = false) => {
+        if (!Number.isSafeInteger(frame.streamId) || frame.streamId < (allowZero ? 0 : 1)
+            || frame.streamId > 0xffff_ffff)
+            invalidControlFrame();
+    };
+    const text = (field, maximum = 8_192, allowEmpty = false) => {
+        const candidate = frame[field];
+        if (typeof candidate !== 'string' || (!allowEmpty && candidate.length === 0)
+            || candidate.length > maximum)
+            invalidControlFrame();
+    };
+    const headers = (field = 'headers', optional = false) => {
+        const candidate = frame[field];
+        if (optional && candidate === undefined)
+            return;
+        if (!Array.isArray(candidate) || candidate.some((header) => !Array.isArray(header)
+            || header.length !== 2 || typeof header[0] !== 'string' || typeof header[1] !== 'string'
+            || !HEADER_NAME.test(header[0]) || /[\0\r\n]/u.test(header[1]))) {
+            invalidControlFrame();
+        }
+    };
+    switch (frame.t) {
+        case 'hello':
+            text('tunnelId', 256);
+            if (frame.protocol !== TUNNEL_PROTOCOL || typeof frame.takeover !== 'boolean')
+                invalidControlFrame();
+            break;
+        case 'ready': {
+            text('tunnelId', 256);
+            text('leaseExpiresAt', 64);
+            if (Number.isNaN(Date.parse(frame.leaseExpiresAt)) || !validLimits(frame.limits)
+                || !frame.credit || typeof frame.credit !== 'object')
+                invalidControlFrame();
+            const credit = frame.credit;
+            if (!positiveInteger(credit.connectionBytes) || !positiveInteger(credit.streamBytes))
+                invalidControlFrame();
+            break;
+        }
+        case 'open':
+            streamId();
+            text('method', 32);
+            text('path');
+            headers();
+            if (!frame.path.startsWith('/'))
+                invalidControlFrame();
+            break;
+        case 'upgrade':
+            streamId();
+            text('path');
+            headers();
+            if (!frame.path.startsWith('/') || !Array.isArray(frame.protocols)
+                || frame.protocols.some((protocol) => typeof protocol !== 'string' || protocol.length > 256)) {
+                invalidControlFrame();
+            }
+            break;
+        case 'head':
+            streamId();
+            headers();
+            if (!Number.isSafeInteger(frame.status) || frame.status < 100
+                || frame.status > 599)
+                invalidControlFrame();
+            break;
+        case 'upgrade.result':
+            streamId();
+            headers('headers', true);
+            if (typeof frame.accepted !== 'boolean'
+                || (frame.protocol !== undefined && (typeof frame.protocol !== 'string' || frame.protocol.length > 256))) {
+                invalidControlFrame();
+            }
+            break;
+        case 'end':
+            streamId();
+            break;
+        case 'ws.close':
+            streamId();
+            text('reason', 123, true);
+            if (!validWebSocketCloseCode(frame.code)
+                || new TextEncoder().encode(frame.reason).byteLength > 123)
+                invalidControlFrame();
+            break;
+        case 'window.update':
+            streamId(true);
+            if (!positiveInteger(frame.bytes))
+                invalidControlFrame();
+            break;
+        case 'reset':
+            streamId();
+            if (!RESET_REASONS.has(frame.reason))
+                invalidControlFrame();
+            break;
+        default:
+            invalidControlFrame();
+    }
+    return frame;
+}
+const RESET_REASONS = new Set([
+    'visitor_disconnect', 'agent_error', 'agent_refused', 'revoked', 'lease_expired',
+    'slow_consumer', 'flow_control_violation', 'protocol_error', 'replaced',
+]);
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
+function invalidControlFrame() {
+    throw new TypeError('Tunnel control frame is invalid.');
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0 && value <= 0xffff_ffff;
+}
+function positiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function validLimits(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const limits = value;
+    return ['maxBandwidthBytes', 'maxLifetimeSeconds', 'maxConcurrentStreams', 'connectionWindowBytes',
+        'streamWindowBytes', 'streamIdleSeconds'].every((field) => positiveSafeInteger(limits[field]));
+}
+function validWebSocketCloseCode(value) {
+    return Number.isSafeInteger(value)
+        && ((value >= 1000 && value <= 1014) || value >= 3000)
+        && value <= 4999
+        && ![1004, 1005, 1006, 1015].includes(value);
+}
+const HOP_BY_HOP = new Set([
+    'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer',
+    'transfer-encoding', 'upgrade',
+]);
+export function sanitizeTunnelRequestHeaders(headers, profile = 'shared-dev') {
+    const connectionNamed = new Set((headers.get('connection') ?? '').split(',').map((name) => name.trim().toLowerCase()).filter(Boolean));
+    const result = [];
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if ((profile === 'shared-dev' && (name === 'authorization' || name === 'cookie'))
+            || name === 'forwarded'
+            || name === 'x-real-ip' || name.startsWith('x-forwarded-')
+            || name.startsWith('cf-')
+            || name.startsWith('x-xeer-') || name.startsWith('xeer-')
+            || name.startsWith('proxy-') || HOP_BY_HOP.has(name) || connectionNamed.has(name))
+            continue;
+        result.push([name, value]);
+    }
+    return result;
+}
+export function sanitizeTunnelResponseHeaders(headers, profile = 'shared-dev') {
+    const connectionNamed = new Set(headers.filter(([name]) => name.toLowerCase() === 'connection')
+        .flatMap(([, value]) => value.split(',')).map((name) => name.trim().toLowerCase()).filter(Boolean));
+    const result = new Headers();
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if ((profile === 'shared-dev' && name === 'set-cookie') || name.startsWith('proxy-')
+            || HOP_BY_HOP.has(name) || connectionNamed.has(name))
+            continue;
+        result.append(name, value);
+    }
+    result.set('x-robots-tag', 'noindex');
+    return result;
+}