dexto 1.14.5 → 2.0.0-beta.0

package/dist/cli/auth/billing.d.ts

@@ -1,13 +1,7 @@
-import type { BillingCheckoutSessionResponse } from './api-client.js';
 export declare function buildDextoBillingUrl(options: {
     creditsUsd?: number | undefined;
     baseUrl?: string | undefined;
 }): string;
-export declare function getBillingBalanceForCurrentLogin(): Promise<number | null>;
-export declare function createBillingCheckoutForCurrentLogin(options: {
-    creditsUsd: number;
-    returnUrl?: string | undefined;
-}): Promise<BillingCheckoutSessionResponse>;
 export declare function openDextoBillingPage(options: {
     url?: string | undefined;
 }): Promise<void>;

package/dist/cli/auth/billing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/billing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAUtE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,GAAG,MAAM,CAQT;AAED,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ/E;AAED,wBAAsB,oCAAoC,CAAC,OAAO,EAAE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAU1C;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F"}
+{"version":3,"file":"billing.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/billing.ts"],"names":[],"mappings":"AAGA,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC1C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,GAAG,MAAM,CAQT;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F"}

package/dist/cli/auth/billing.js

@@ -1,10 +1,5 @@
-import { getDextoApiClient } from './api-client.js';
 import { openBrowserUrl } from './browser-launch.js';
 import { DEXTO_CREDITS_URL } from './constants.js';
-import { getAuthTokenQuietly } from './service.js';
-function notLoggedInError() {
-    return new Error('Not logged in to Dexto');
-}
 export function buildDextoBillingUrl(options) {
     const url = new URL(options.baseUrl ?? DEXTO_CREDITS_URL);
     if (typeof options.creditsUsd === 'number' && Number.isFinite(options.creditsUsd)) {
@@ -12,24 +7,6 @@ export function buildDextoBillingUrl(options) {
     }
     return url.toString();
 }
-export async function getBillingBalanceForCurrentLogin() {
-    const authToken = await getAuthTokenQuietly();
-    if (!authToken) {
-        return null;
-    }
-    const response = await getDextoApiClient().getBillingBalance(authToken, {});
-    return response.creditsUsd;
-}
-export async function createBillingCheckoutForCurrentLogin(options) {
-    const authToken = await getAuthTokenQuietly();
-    if (!authToken) {
-        throw notLoggedInError();
-    }
-    return getDextoApiClient().createBillingCheckoutSession(authToken, {
-        ...options,
-        returnUrl: options.returnUrl ?? DEXTO_CREDITS_URL,
-    });
-}
 export async function openDextoBillingPage(options) {
     await openBrowserUrl(options.url ?? DEXTO_CREDITS_URL);
 }

package/dist/cli/auth/constants.d.ts

@@ -1,35 +1,7 @@
-/**
- * Dexto's Supabase configuration for CLI authentication.
- *
- * SECURITY NOTE:
- * The Supabase anon key is safe to hardcode in distributed code because:
- * 1. It's designed for client-side use (web browsers, mobile apps, CLIs)
- * 2. It only grants anonymous access - real security is enforced by Row Level Security (RLS)
- * 3. This is standard practice (Vercel CLI, Supabase CLI, Firebase CLI all do the same)
- *
- * The service role key (which has admin access) is NEVER in this codebase.
- *
- * Environment variable overrides (for local development):
- * - SUPABASE_URL: Override Supabase URL (e.g., http://localhost:54321)
- * - SUPABASE_ANON_KEY: Override anon key (from `supabase start` output)
- * - DEXTO_API_URL: Override Dexto gateway URL for data-plane calls (e.g., http://localhost:3001)
- * - DEXTO_PLATFORM_URL: Override Dexto app URL for auth/key/account control-plane calls (e.g., http://localhost:3002)
- * - DEXTO_PUBLIC_API_URL: Override versioned public API URL (e.g., http://localhost:3002)
- */
-export declare const SUPABASE_URL: string;
-export declare const SUPABASE_ANON_KEY: string;
-/**
- * Dexto gateway URL for retained data-plane endpoints.
- */
-export declare const DEXTO_API_URL: string;
-/**
- * Dexto app URL for auth/key/account control-plane endpoints.
- */
-export declare const DEFAULT_DEXTO_PLATFORM_URL = "https://app.dexto.ai";
+/** The Dexto app a new sign-in goes to. */
 export declare const DEXTO_PLATFORM_URL: string;
+/** The versioned public API (`/v1`). */
 export declare const DEXTO_PUBLIC_API_URL: string;
-/**
- * Dexto Nova credits purchase URL
- */
+/** Where to buy Dexto credits. */
 export declare const DEXTO_CREDITS_URL: string;
 //# sourceMappingURL=constants.d.ts.map

package/dist/cli/auth/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/constants.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,QAAyE,CAAC;AACnG,eAAO,MAAM,iBAAiB,QAEwL,CAAC;AAEvN;;GAEG;AACH,eAAO,MAAM,aAAa,QAAsD,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AACjE,eAAO,MAAM,kBAAkB,QAA+D,CAAC;AAE/F,eAAO,MAAM,oBAAoB,QAA6D,CAAC;AAE/F;;GAEG;AACH,eAAO,MAAM,iBAAiB,QACwD,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/constants.ts"],"names":[],"mappings":"AAOA,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,QAA2D,CAAC;AAE3F,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,QAA6D,CAAC;AAE/F,kCAAkC;AAClC,eAAO,MAAM,iBAAiB,QACwD,CAAC"}

package/dist/cli/auth/constants.js

@@ -1,36 +1,12 @@
 // packages/cli/src/cli/auth/constants.ts
-/**
- * Dexto's Supabase configuration for CLI authentication.
- *
- * SECURITY NOTE:
- * The Supabase anon key is safe to hardcode in distributed code because:
- * 1. It's designed for client-side use (web browsers, mobile apps, CLIs)
- * 2. It only grants anonymous access - real security is enforced by Row Level Security (RLS)
- * 3. This is standard practice (Vercel CLI, Supabase CLI, Firebase CLI all do the same)
- *
- * The service role key (which has admin access) is NEVER in this codebase.
- *
- * Environment variable overrides (for local development):
- * - SUPABASE_URL: Override Supabase URL (e.g., http://localhost:54321)
- * - SUPABASE_ANON_KEY: Override anon key (from `supabase start` output)
- * - DEXTO_API_URL: Override Dexto gateway URL for data-plane calls (e.g., http://localhost:3001)
- * - DEXTO_PLATFORM_URL: Override Dexto app URL for auth/key/account control-plane calls (e.g., http://localhost:3002)
- * - DEXTO_PUBLIC_API_URL: Override versioned public API URL (e.g., http://localhost:3002)
- */
-export const SUPABASE_URL = process.env.SUPABASE_URL || 'https://gdfbxznhnnsamvsrtwjq.supabase.co';
-export const SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY ||
-    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImdkZmJ4em5obm5zYW12c3J0d2pxIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjQwNjkzNjksImV4cCI6MjA3OTY0NTM2OX0.j2NWOJDOy8gTT84XeomalkGSPpLdPvTCBnQMrTgdlI4';
-/**
- * Dexto gateway URL for retained data-plane endpoints.
- */
-export const DEXTO_API_URL = process.env.DEXTO_API_URL || 'https://app.dexto.ai';
-/**
- * Dexto app URL for auth/key/account control-plane endpoints.
- */
-export const DEFAULT_DEXTO_PLATFORM_URL = 'https://app.dexto.ai';
-export const DEXTO_PLATFORM_URL = process.env.DEXTO_PLATFORM_URL || DEFAULT_DEXTO_PLATFORM_URL;
+//
+// Where the CLI reaches Dexto. Environment overrides, for previews and local development:
+// - DEXTO_PLATFORM_URL: the Dexto app, home of its OAuth server and MCP (e.g. http://localhost:3002)
+// - DEXTO_PUBLIC_API_URL: the versioned public API (e.g. http://localhost:3002)
+// - DEXTO_CREDITS_URL: the page to buy credits on
+/** The Dexto app a new sign-in goes to. */
+export const DEXTO_PLATFORM_URL = process.env.DEXTO_PLATFORM_URL || 'https://app.dexto.ai';
+/** The versioned public API (`/v1`). */
 export const DEXTO_PUBLIC_API_URL = process.env.DEXTO_PUBLIC_API_URL || 'https://api.dexto.ai';
-/**
- * Dexto Nova credits purchase URL
- */
+/** Where to buy Dexto credits. */
 export const DEXTO_CREDITS_URL = process.env.DEXTO_CREDITS_URL || 'https://app.dexto.ai/dashboard/settings/billing';

package/dist/cli/auth/index.d.ts

@@ -1,10 +1,3 @@
-export { type AuthConfig, storeAuth, loadAuth, removeAuth, isAuthenticated, getAuthToken, getAuthTokenQuietly, getDextoApiKey, getAuthFilePath, } from './service.js';
-export { type OAuthResult } from './oauth.js';
-export { type DeviceApiKeyLoginResult } from './types.js';
-export { type DeviceLoginPrompt, performDeviceCodeLogin } from './device.js';
-export { type PersistOAuthLoginOptions, type PersistedLoginResult, persistDeviceApiKeyLoginResult, persistOAuthLoginResult, } from './login-persistence.js';
-export { type UsageSummaryResponse, DextoApiClient, getDextoApiClient } from './api-client.js';
-export { SUPABASE_URL, SUPABASE_ANON_KEY, DEXTO_API_URL, DEXTO_PLATFORM_URL, DEXTO_PUBLIC_API_URL, } from './constants.js';
-export { buildDextoBillingUrl, getBillingBalanceForCurrentLogin, createBillingCheckoutForCurrentLogin, openDextoBillingPage, } from './billing.js';
-export { type DextoApiKeyProvisionStatus, type DextoApiKeyProvisionStatusLevel, type EnsureDextoApiKeyOptions, ensureDextoApiKeyForAuthToken, saveDextoApiKeyToEnv, removeDextoApiKeyFromEnv, } from './dexto-api-key.js';
+export { DEXTO_PLATFORM_URL, DEXTO_PUBLIC_API_URL } from './constants.js';
+export { buildDextoBillingUrl, openDextoBillingPage } from './billing.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,UAAU,EACf,SAAS,EACT,QAAQ,EACR,UAAU,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,eAAe,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,KAAK,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EACH,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,8BAA8B,EAC9B,uBAAuB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,KAAK,oBAAoB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,EACH,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,oBAAoB,EACpB,gCAAgC,EAChC,oCAAoC,EACpC,oBAAoB,GACvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACH,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,wBAAwB,GAC3B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/cli/auth/index.js

@@ -1,9 +1,4 @@
 // packages/cli/src/cli/auth/index.ts
 // Public exports for auth module
-export { storeAuth, loadAuth, removeAuth, isAuthenticated, getAuthToken, getAuthTokenQuietly, getDextoApiKey, getAuthFilePath, } from './service.js';
-export { performDeviceCodeLogin } from './device.js';
-export { persistDeviceApiKeyLoginResult, persistOAuthLoginResult, } from './login-persistence.js';
-export { DextoApiClient, getDextoApiClient } from './api-client.js';
-export { SUPABASE_URL, SUPABASE_ANON_KEY, DEXTO_API_URL, DEXTO_PLATFORM_URL, DEXTO_PUBLIC_API_URL, } from './constants.js';
-export { buildDextoBillingUrl, getBillingBalanceForCurrentLogin, createBillingCheckoutForCurrentLogin, openDextoBillingPage, } from './billing.js';
-export { ensureDextoApiKeyForAuthToken, saveDextoApiKeyToEnv, removeDextoApiKeyFromEnv, } from './dexto-api-key.js';
+export { DEXTO_PLATFORM_URL, DEXTO_PUBLIC_API_URL } from './constants.js';
+export { buildDextoBillingUrl, openDextoBillingPage } from './billing.js';

package/dist/cli/auth/sign-in-runtime.d.ts

@@ -0,0 +1,12 @@
+import type { dextoSignIn } from '@dexto/agent-management';
+type RedirectListener = dextoSignIn.RedirectListener;
+type SignInRuntime = dextoSignIn.SignInRuntime;
+/**
+ * Listens on 127.0.0.1 at any free port for the browser's redirect to `/callback` (RFC 8252), and
+ * resolves with its query on the first one.
+ */
+export declare function listenForRedirect(): Promise<RedirectListener>;
+/** Signing in from this process: notes go to stderr so stdout stays for results. */
+export declare function nodeSignInRuntime(signal: AbortSignal): SignInRuntime;
+export {};
+//# sourceMappingURL=sign-in-runtime.d.ts.map

package/dist/cli/auth/sign-in-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-in-runtime.d.ts","sourceRoot":"","sources":["../../../src/cli/auth/sign-in-runtime.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,KAAK,gBAAgB,GAAG,WAAW,CAAC,gBAAgB,CAAC;AACrD,KAAK,aAAa,GAAG,WAAW,CAAC,aAAa,CAAC;AAM/C;;;GAGG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA6BnE;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAepE"}

package/dist/cli/auth/sign-in-runtime.js

@@ -0,0 +1,59 @@
+// The Node side of signing in: a loopback redirect listener, the browser and timers.
+import { createServer } from 'node:http';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { openBrowserUrl } from './browser-launch.js';
+const DONE_PAGE = `<!doctype html><meta charset="utf-8"><title>Dexto</title>
+<body style="font-family:system-ui;margin:4rem auto;max-width:28rem">
+<h1>Signed in</h1><p>You can close this tab and return to your terminal.</p></body>`;
+/**
+ * Listens on 127.0.0.1 at any free port for the browser's redirect to `/callback` (RFC 8252), and
+ * resolves with its query on the first one.
+ */
+export async function listenForRedirect() {
+    let deliver = () => undefined;
+    const result = new Promise((resolve) => {
+        deliver = resolve;
+    });
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        if (request.method !== 'GET' || url.pathname !== '/callback') {
+            response.writeHead(404).end();
+            return;
+        }
+        response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(DONE_PAGE);
+        deliver(url.searchParams);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve());
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('The sign-in listener has no port.');
+    return {
+        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        result,
+        close: () => {
+            server.closeAllConnections();
+            server.close();
+        },
+    };
+}
+/** Signing in from this process: notes go to stderr so stdout stays for results. */
+export function nodeSignInRuntime(signal) {
+    return {
+        fetch: globalThis.fetch,
+        signal,
+        note: (text) => process.stderr.write(`${text}\n`),
+        openBrowser: async (url) => {
+            try {
+                await openBrowserUrl(url);
+            }
+            catch {
+                // The URL was already printed; the person opens it by hand.
+            }
+        },
+        listenForRedirect,
+        sleep: (ms) => sleep(ms, undefined, { signal }),
+    };
+}

package/dist/cli/cloud/app-scopes.d.ts

@@ -0,0 +1,4 @@
+import type { CloudRuntime } from './runtime.js';
+/** Each app's operations by tool or action name, with their scopes; empty from an older server. */
+export declare function readAppScopes(runtime: CloudRuntime, appUrl: string): Promise<ReadonlyMap<string, Readonly<Record<string, readonly string[]>>>>;
+//# sourceMappingURL=app-scopes.d.ts.map

package/dist/cli/cloud/app-scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-scopes.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/app-scopes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAOjD,mGAAmG;AACnG,wBAAsB,aAAa,CAC/B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAS3E"}

package/dist/cli/cloud/app-scopes.js

@@ -0,0 +1,19 @@
+// Each workspace app's operations and the scopes each takes, from the MCP's published metadata,
+// so a command can sign in for an operation the sign-in can't see yet.
+import { z } from 'zod';
+const ProtectedResourceSchema = z.object({
+    /** Every scope each app's operations take; an older server publishes none. */
+    dexto_app_scopes: z.record(z.string(), z.record(z.string(), z.array(z.string()))).optional(),
+});
+/** Each app's operations by tool or action name, with their scopes; empty from an older server. */
+export async function readAppScopes(runtime, appUrl) {
+    const url = `${appUrl.replace(/\/+$/u, '')}/.well-known/oauth-protected-resource/mcp`;
+    const response = await runtime.fetch(url, {
+        headers: { accept: 'application/json' },
+        signal: runtime.signal,
+    });
+    if (!response.ok)
+        throw new Error(`${url} answered HTTP ${response.status}.`);
+    const metadata = ProtectedResourceSchema.parse(await response.json());
+    return new Map(Object.entries(metadata.dexto_app_scopes ?? {}));
+}

package/dist/cli/cloud/command.d.ts

@@ -0,0 +1,143 @@
+import type { CloudClient } from '@dexto/cloud-client';
+import type { Connection, ConnectionOverrides } from './connection.js';
+import type { Output } from './output.js';
+import type { CloudRuntime } from './runtime.js';
+export interface OptionSpec {
+    readonly description: string;
+    readonly multiple?: true;
+    readonly short?: string;
+    readonly type: 'boolean' | 'string';
+    /** The value's name in help, such as ID; string options only. */
+    readonly valueName?: string;
+}
+export interface Command {
+    /** Such as `<agent_id> [message...]`; `<x>` is required, `[x]` optional. */
+    readonly arguments?: string;
+    readonly options?: Readonly<Record<string, OptionSpec>>;
+    /** The words that select it, such as ["agents", "sessions", "list"]. */
+    readonly path: readonly string[];
+    readonly summary: string;
+    run(context: CommandContext, input: CommandInput): Promise<number | void>;
+}
+export interface CommandInput {
+    readonly positionals: readonly string[];
+    readonly values: Readonly<Record<string, string | boolean | (string | boolean)[] | undefined>>;
+}
+export interface CommandContext {
+    /** The /v1 client for the resolved credential; fails with how to sign in when there is none. */
+    client(): Promise<CloudClient>;
+    connection(): Promise<Connection>;
+    /** The words the command was run with, its connection options included and any key left out. */
+    readonly invocation: readonly string[];
+    readonly output: Output;
+    readonly overrides: ConnectionOverrides;
+    readonly runtime: CloudRuntime;
+}
+/** A mistake in how the command was called: printed with the command's usage. */
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+/** What kind of thing went wrong; each kind has an exit code an agent can branch on. */
+export type FailureKind = 'failed' | 'invalid_input' | 'needs_confirmation' | 'needs_permission' | 'needs_sign_in' | 'not_found' | 'waiting_on_person';
+export declare const EXIT_CODES: {
+    readonly failed: 1;
+    readonly invalid_input: 2;
+    readonly needs_confirmation: 4;
+    readonly needs_permission: 3;
+    readonly needs_sign_in: 3;
+    readonly not_found: 5;
+    readonly waiting_on_person: 6;
+    readonly usage: 2;
+};
+/** What each exit code means; frozen in 2.0 and shown in help. */
+export declare const EXIT_CODE_MEANINGS: {
+    readonly '0': "done";
+    readonly '1': "failed";
+    readonly '2': "usage or invalid input";
+    readonly '3': "needs sign-in or permission";
+    readonly '4': "needs confirmation: pass --yes once your person has agreed";
+    readonly '5': "not found";
+    readonly '6': "waiting on a person, such as an approval";
+};
+/** A failure that says what kind it is and, where there is one, the command that fixes it. */
+export declare class CommandFailure extends Error {
+    readonly fix: string | null;
+    readonly kind: FailureKind;
+    constructor(kind: FailureKind, message: string, fix: string | null);
+}
+/** A permission the sign-in lacks: signing in again for `scope` (one, or several comma-separated) fixes it. */
+export declare class MissingScopeFailure extends CommandFailure {
+    readonly scope: string;
+    constructor(context: SignInContext, scope: string, message: string);
+}
+export declare function stringOption(input: CommandInput, name: string): string | undefined;
+export declare function requiredOption(input: CommandInput, name: string): string;
+export declare function listOption(input: CommandInput, name: string): string[];
+export declare function flag(input: CommandInput, name: string): boolean;
+export declare function integerOption(input: CommandInput, name: string): number | undefined;
+export declare function argument(input: CommandInput, index: number, name: string): string;
+/** `--limit` and `--after`, which every list takes. */
+export declare const PAGE_OPTIONS: {
+    readonly after: {
+        readonly description: "Start after this cursor, from the previous page.";
+        readonly type: "string";
+        readonly valueName: "CURSOR";
+    };
+    readonly limit: {
+        readonly description: "How many to return.";
+        readonly type: "string";
+        readonly valueName: "N";
+    };
+};
+export declare function pageQuery(input: CommandInput): {
+    after?: string;
+    limit?: number;
+};
+/** `--data <json>` and `--file <path|->`, for request bodies too rich for flags. */
+export declare const BODY_OPTIONS: {
+    readonly data: {
+        readonly description: "The request body as JSON.";
+        readonly type: "string";
+        readonly valueName: "JSON";
+    };
+    readonly file: {
+        readonly description: "Read the request body from a JSON file, or - for stdin.";
+        readonly type: "string";
+        readonly valueName: "PATH";
+    };
+};
+/** The JSON body from --data or --file; null when neither was given. */
+export declare function readJsonBody(context: CommandContext, input: CommandInput): Promise<unknown>;
+export declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+/** A value the person types, hidden when secret, or piped on stdin. */
+export declare function readValue(context: CommandContext, question: string, secret: boolean): Promise<string>;
+/** Asks yes or no at a terminal; without one, only `--yes` agrees. */
+export declare function confirm(context: CommandContext, question: string): Promise<boolean>;
+export declare const YES_OPTION: {
+    readonly yes: {
+        readonly description: "Go ahead without being asked. Pass it only once your person has agreed.";
+        readonly type: "boolean";
+    };
+};
+/**
+ * Goes ahead with something that asks first: at once with `--yes`, after a yes at a terminal, and
+ * otherwise not at all, failing with the command that goes ahead.
+ */
+export declare function requireConsent(context: CommandContext, yes: boolean, what: string): Promise<void>;
+/** The command as it was run plus more words, quoted to paste into a shell. */
+export declare function rerunWith(context: CommandContext, ...extra: string[]): string;
+/**
+ * Whether a sign-in here should use a device code: no one is at this terminal, or it is an SSH
+ * session, whose loopback redirect a browser on the person's own device can't reach.
+ */
+export declare function signsInWithDevice(runtime: CloudRuntime): boolean;
+/** What saying how to sign in again needs: the process, and the profile `--profile` chose. */
+export type SignInContext = Pick<CommandContext, 'overrides' | 'runtime'>;
+/**
+ * How to sign in again, to the same app and profile, with a device code where a browser can't
+ * finish it.
+ */
+export declare function signInCommand(context: SignInContext, scope: string | null): string;
+/** A word as a shell reads it: quoted unless it is plain. */
+export declare function shellWord(word: string): string;
+//# sourceMappingURL=command.d.ts.map

package/dist/cli/cloud/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/command.ts"],"names":[],"mappings":"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"}

package/dist/cli/cloud/command.js

@@ -0,0 +1,202 @@
+// The shape every cloud command shares: its path, arguments, options and handler.
+import { readFile } from 'node:fs/promises';
+/** A mistake in how the command was called: printed with the command's usage. */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+export const EXIT_CODES = {
+    failed: 1,
+    invalid_input: 2,
+    needs_confirmation: 4,
+    needs_permission: 3,
+    needs_sign_in: 3,
+    not_found: 5,
+    waiting_on_person: 6,
+    usage: 2,
+};
+/** What each exit code means; frozen in 2.0 and shown in help. */
+export const EXIT_CODE_MEANINGS = {
+    '0': 'done',
+    '1': 'failed',
+    '2': 'usage or invalid input',
+    '3': 'needs sign-in or permission',
+    '4': 'needs confirmation: pass --yes once your person has agreed',
+    '5': 'not found',
+    '6': 'waiting on a person, such as an approval',
+};
+/** A failure that says what kind it is and, where there is one, the command that fixes it. */
+export class CommandFailure extends Error {
+    fix;
+    kind;
+    constructor(kind, message, fix) {
+        super(message);
+        this.name = 'CommandFailure';
+        this.fix = fix;
+        this.kind = kind;
+    }
+}
+/** A permission the sign-in lacks: signing in again for `scope` (one, or several comma-separated) fixes it. */
+export class MissingScopeFailure extends CommandFailure {
+    scope;
+    constructor(context, scope, message) {
+        super('needs_permission', message, signInCommand(context, scope));
+        this.name = 'MissingScopeFailure';
+        this.scope = scope;
+    }
+}
+export function stringOption(input, name) {
+    const value = input.values[name];
+    return typeof value === 'string' ? value : undefined;
+}
+export function requiredOption(input, name) {
+    const value = stringOption(input, name);
+    if (value === undefined)
+        throw new UsageError(`--${name} is required.`);
+    return value;
+}
+export function listOption(input, name) {
+    const value = input.values[name];
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+export function flag(input, name) {
+    return input.values[name] === true;
+}
+export function integerOption(input, name) {
+    const value = stringOption(input, name);
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed))
+        throw new UsageError(`--${name} must be a whole number.`);
+    return parsed;
+}
+export function argument(input, index, name) {
+    const value = input.positionals[index];
+    if (value === undefined)
+        throw new UsageError(`Missing ${name}.`);
+    return value;
+}
+/** `--limit` and `--after`, which every list takes. */
+export const PAGE_OPTIONS = {
+    after: {
+        description: 'Start after this cursor, from the previous page.',
+        type: 'string',
+        valueName: 'CURSOR',
+    },
+    limit: { description: 'How many to return.', type: 'string', valueName: 'N' },
+};
+export function pageQuery(input) {
+    const after = stringOption(input, 'after');
+    const limit = integerOption(input, 'limit');
+    return {
+        ...(after === undefined ? {} : { after }),
+        ...(limit === undefined ? {} : { limit }),
+    };
+}
+/** `--data <json>` and `--file <path|->`, for request bodies too rich for flags. */
+export const BODY_OPTIONS = {
+    data: { description: 'The request body as JSON.', type: 'string', valueName: 'JSON' },
+    file: {
+        description: 'Read the request body from a JSON file, or - for stdin.',
+        type: 'string',
+        valueName: 'PATH',
+    },
+};
+/** The JSON body from --data or --file; null when neither was given. */
+export async function readJsonBody(context, input) {
+    const data = stringOption(input, 'data');
+    const file = stringOption(input, 'file');
+    if (data !== undefined && file !== undefined)
+        throw new UsageError('Pass --data or --file, not both.');
+    const text = data ??
+        (file === undefined
+            ? null
+            : file === '-'
+                ? await context.runtime.readStdin()
+                : await readFile(file, 'utf8'));
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError(`The request body is not valid JSON${file ? ` (${file})` : ''}.`);
+    }
+}
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A value the person types, hidden when secret, or piped on stdin. */
+export async function readValue(context, question, secret) {
+    const value = context.runtime.prompt === null
+        ? (await context.runtime.readStdin()).replace(/\r?\n$/u, '')
+        : await context.runtime.prompt(question, { secret });
+    if (value.length === 0)
+        throw new UsageError('No value was given.');
+    return value;
+}
+/** Asks yes or no at a terminal; without one, only `--yes` agrees. */
+export async function confirm(context, question) {
+    if (context.runtime.prompt === null)
+        return false;
+    const answer = await context.runtime.prompt(`${question} [y/N] `, { secret: false });
+    return /^y(es)?$/iu.test(answer.trim());
+}
+export const YES_OPTION = {
+    yes: {
+        description: 'Go ahead without being asked. Pass it only once your person has agreed.',
+        type: 'boolean',
+    },
+};
+/**
+ * Goes ahead with something that asks first: at once with `--yes`, after a yes at a terminal, and
+ * otherwise not at all, failing with the command that goes ahead.
+ */
+export async function requireConsent(context, yes, what) {
+    if (yes)
+        return;
+    if (context.runtime.prompt !== null) {
+        if (await confirm(context, `${what} Go ahead?`))
+            return;
+        throw new CommandFailure('needs_confirmation', 'Not done.', null);
+    }
+    throw new CommandFailure('needs_confirmation', `${what} Run it again with --yes once your person has agreed.`, rerunWith(context, '--yes'));
+}
+/** The command as it was run plus more words, quoted to paste into a shell. */
+export function rerunWith(context, ...extra) {
+    return ['dexto', ...context.invocation, ...extra].map(shellWord).join(' ');
+}
+/**
+ * Whether a sign-in here should use a device code: no one is at this terminal, or it is an SSH
+ * session, whose loopback redirect a browser on the person's own device can't reach.
+ */
+export function signsInWithDevice(runtime) {
+    return (runtime.prompt === null ||
+        runtime.environment.SSH_CONNECTION !== undefined ||
+        runtime.environment.SSH_TTY !== undefined);
+}
+/**
+ * How to sign in again, to the same app and profile, with a device code where a browser can't
+ * finish it.
+ */
+export function signInCommand(context, scope) {
+    const profile = context.overrides.profile;
+    return [
+        'dexto',
+        'login',
+        ...(profile === null ? [] : ['--profile', profile]),
+        ...(signsInWithDevice(context.runtime) ? ['--device'] : []),
+        ...(scope === null ? [] : ['--scope', scope]),
+    ]
+        .map(shellWord)
+        .join(' ');
+}
+/** A word as a shell reads it: quoted unless it is plain. */
+export function shellWord(word) {
+    return /^[\w@%+=:,./-]+$/u.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}