@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/custom-integrations.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerCustomIntegrationsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/custom-integrations.js

@@ -0,0 +1,140 @@
+import { parseJsonObject } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const CUSTOM_HTTP_MANIFEST_DOCS_URL = "https://oxygen-agent.com/docs/providers/custom-http";
+function readCustomIntegrationManifest(options) {
+    const manifestPath = readOption(options.manifest);
+    const manifestJson = readOption(options.manifestJson);
+    if (manifestPath && manifestJson) {
+        throw new OxygenError("invalid_request", "Pass either --manifest or --manifest-json, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!manifestPath && !manifestJson) {
+        throw new OxygenError("invalid_request", "Pass --manifest or --manifest-json.", {
+            exitCode: 1,
+        });
+    }
+    if (manifestJson)
+        return parseJsonObject(manifestJson);
+    const filePath = resolve(manifestPath ?? "");
+    let content;
+    try {
+        content = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        const notFound = error?.code === "ENOENT";
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new OxygenError("invalid_request", notFound
+            ? `Manifest file not found: ${filePath}. Pass --manifest <path.json> or --manifest-json '<json>'. See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`
+            : `Could not read manifest file ${filePath}: ${reason}. See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`, { details: { path: filePath }, exitCode: 1 });
+    }
+    try {
+        return parseJsonObject(content);
+    }
+    catch (error) {
+        if (error instanceof OxygenError) {
+            throw new OxygenError(error.code, `Manifest file ${filePath} is invalid: ${error.message} See ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`, {
+                details: { path: filePath, ...(isRecord(error.details) ? error.details : {}) },
+                exitCode: error.exitCode,
+            });
+        }
+        throw error;
+    }
+}
+const CUSTOM_INTEGRATION_SECRET_KEYS = ["API_KEY", "TOKEN", "PASSWORD", "SECRET"];
+function readCustomIntegrationSecret(options) {
+    const secretsFile = readOption(options.secretsFile);
+    if (!secretsFile) {
+        throw new OxygenError("invalid_request", "Pass --secrets-file.", {
+            exitCode: 1,
+        });
+    }
+    const entries = parseEnvFile(readFileSync(resolve(secretsFile), "utf8"));
+    const keys = Object.keys(entries);
+    if (keys.length === 0) {
+        throw new OxygenError("invalid_request", "Secrets file has no KEY=VALUE entries.", {
+            details: { file: secretsFile },
+            exitCode: 1,
+        });
+    }
+    if (keys.length === 1)
+        return entries[keys[0]];
+    const preferred = CUSTOM_INTEGRATION_SECRET_KEYS.find((key) => entries[key] !== undefined);
+    if (preferred)
+        return entries[preferred];
+    throw new OxygenError("invalid_request", "Secrets file is ambiguous: use a single entry or name one API_KEY, TOKEN, PASSWORD, or SECRET.", {
+        details: { file: secretsFile, keys },
+        exitCode: 1,
+    });
+}
+function parseEnvFile(content) {
+    const entries = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const separator = line.indexOf("=");
+        if (separator <= 0)
+            continue;
+        const key = line.slice(0, separator).trim().replace(/^export\s+/, "");
+        let value = line.slice(separator + 1).trim();
+        if ((value.startsWith("\"") && value.endsWith("\"") && value.length >= 2)
+            || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
+            value = value.slice(1, -1);
+        }
+        if (key && value)
+            entries[key] = value;
+    }
+    return entries;
+}
+export function registerCustomIntegrationsFamily(program, handleAsyncAction) {
+    program
+        .command("custom-integrations")
+        .description("Custom HTTP integration commands.")
+        .addCommand(new Command("apply")
+        .description(`Create or update a custom HTTP integration manifest. Attach credentials with \`custom-integrations connect\`. Manifest schema + worked examples: ${CUSTOM_HTTP_MANIFEST_DOCS_URL}`)
+        .option("--manifest <path>", "Path to a custom HTTP manifest JSON file.")
+        .option("--manifest-json <json>", "Custom HTTP manifest as a JSON object.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("custom-integrations apply", options, () => {
+            const manifest = readCustomIntegrationManifest(options);
+            return requestOxygen("/api/cli/custom-integrations", {
+                method: "POST",
+                body: { manifest },
+            });
+        });
+    }))
+        .addCommand(new Command("connect")
+        .description("Attach the credential (bearer token, API key, or basic password) for an applied custom HTTP integration.")
+        .argument("<slug>", "Custom integration slug from the applied manifest.")
+        .option("--secrets-file <path>", "Path to a .env-style file holding the credential (a single entry, or one named API_KEY/TOKEN/PASSWORD/SECRET).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("custom-integrations connect", options, () => {
+            const apiKey = readCustomIntegrationSecret(options);
+            return requestOxygen("/api/cli/custom-integrations/connect", {
+                method: "POST",
+                body: { slug, api_key: apiKey },
+            });
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List custom HTTP integrations for the active organization.")
+        .option("--slug <slug>", "Filter to one custom integration slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("custom-integrations list", options, () => {
+            const params = new URLSearchParams();
+            if (readOption(options.slug))
+                params.set("slug", readOption(options.slug) ?? "");
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/custom-integrations${suffix ? `?${suffix}` : ""}`);
+        });
+    }));
+}

package/dist/commands/dashboards.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerDashboardsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/dashboards.js

@@ -0,0 +1,240 @@
+import { parseJsonObject } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+/**
+ * A widget configuration from `--config` or `--config-file`.
+ *
+ * Both are accepted because the shape of a chart or a code widget is more than
+ * anyone wants to quote on one shell line, and `--config-file` is how an agent
+ * hands over a configuration it just generated. The SHAPE is validated server
+ * side by the shared widget registry, never here: a second validator is how the
+ * CLI and the web start disagreeing about what a valid widget is.
+ */
+async function readDashboardWidgetConfig(options) {
+    const inline = readOption(options.config);
+    const path = readOption(options.configFile);
+    if (inline && path) {
+        throw new OxygenError("invalid_request", "Pass either --config or --config-file, not both.", { exitCode: 1 });
+    }
+    if (inline)
+        return parseJsonObject(inline);
+    if (path) {
+        const fs = await import("node:fs/promises");
+        return parseJsonObject(await fs.readFile(path, "utf8"));
+    }
+    return {};
+}
+export function registerDashboardsFamily(program, handleAsyncAction) {
+    program
+        .command("dashboards")
+        .description("Your saved dashboards, plus the built-in GTM funnel. `summary` reads the built-in Command Center funnel across the sequencer, unibox and CRM; everything else creates and edits dashboards you save yourself and open again later, from charts, saved table views, notes, embeds and live sources.")
+        .addCommand(new Command("summary")
+        .description("Show the GTM funnel summary: touches → replies → positive → meetings → deals → won, with this-period revenue, channel split, and current needs-action triage. Unread replies across channels and interested email conversations are current inbox counts, independent of the selected range.")
+        .option("--range <range>", "Preset range: 7d, 14d, 28d, 30d, 90d, 180d, 365d, or all. Defaults to 14d.")
+        .option("--from <date>", "Custom start date (YYYY-MM-DD).")
+        .option("--to <date>", "Custom end date (YYYY-MM-DD).")
+        .option("--cold-deal-days <n>", "Days of no activity before an open deal counts as cold. Defaults to 14.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("dashboards summary", options, () => {
+            const params = new URLSearchParams();
+            const range = readOption(options.range);
+            const from = readOption(options.from);
+            const to = readOption(options.to);
+            const coldDealDays = readOption(options.coldDealDays);
+            if (range)
+                params.set("range", range);
+            if (from)
+                params.set("from", from);
+            if (to)
+                params.set("to", to);
+            if (coldDealDays)
+                params.set("cold_deal_days", coldDealDays);
+            const qs = params.toString();
+            return requestOxygen(`/api/cli/dashboards/summary${qs ? `?${qs}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List the dashboards saved in this workspace.")
+        .option("--tag <tag>", "Only dashboards carrying this workspace tag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("dashboards list", options, () => requestOxygen(`/api/cli/dashboards${options.tag ? `?tag=${encodeURIComponent(options.tag)}` : ""}`));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a saved dashboard. It starts with one empty tab; add widgets to it with `dashboards widgets add`.")
+        .argument("<name>", "Display name, e.g. \"Monday numbers\".")
+        .option("--slug <slug>", "URL handle. Defaults to a slug derived from the name.")
+        .option("--description <text>", "What this dashboard answers.")
+        .option("--icon <icon>", "Icon name shown beside it in the CRM sidebar.")
+        .option("--default", "Open this one when the dashboards page is opened with no dashboard named.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (name, options) => {
+        await handleAsyncAction("dashboards create", options, () => {
+            const body = { name };
+            const slug = readOption(options.slug);
+            const description = readOption(options.description);
+            const icon = readOption(options.icon);
+            if (slug)
+                body.slug = slug;
+            if (description)
+                body.description = description;
+            if (icon)
+                body.icon = icon;
+            if (options.default)
+                body.is_default = true;
+            return requestOxygen("/api/cli/dashboards", { method: "POST", body });
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Read one dashboard with its tabs and widgets.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, options) => {
+        await handleAsyncAction("dashboards get", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Rename a dashboard, change its description or icon, or make it the default.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .option("--name <name>", "New display name.")
+        .option("--description <text>", "New description. Pass an empty string to clear it.")
+        .option("--icon <icon>", "New icon name.")
+        .option("--default", "Make this the default dashboard.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, options) => {
+        await handleAsyncAction("dashboards update", options, () => {
+            const body = {};
+            if (options.name !== undefined)
+                body.name = options.name;
+            if (options.description !== undefined)
+                body.description = options.description;
+            if (options.icon !== undefined)
+                body.icon = options.icon;
+            if (options.default)
+                body.is_default = true;
+            return requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}`, {
+                method: "PATCH",
+                body,
+            });
+        });
+    }))
+        .addCommand(new Command("delete")
+        .description("Archive a dashboard. Its slug becomes free to reuse; the definition is kept, not destroyed.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, options) => {
+        await handleAsyncAction("dashboards delete", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}`, {
+            method: "DELETE",
+        }));
+    }))
+        .addCommand(new Command("tabs")
+        .description("Tabs inside a dashboard.")
+        .addCommand(new Command("add")
+        .description("Add a tab to a dashboard.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<title>", "Tab title.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, title, options) => {
+        await handleAsyncAction("dashboards tab create", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/tabs`, {
+            method: "POST",
+            body: { title },
+        }));
+    }))
+        .addCommand(new Command("remove")
+        .description("Remove a tab and every widget on it. A dashboard always keeps at least one tab.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<tab_id>", "Tab id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, tabId, options) => {
+        await handleAsyncAction("dashboards tab delete", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/tabs?tab=${encodeURIComponent(tabId)}`, { method: "DELETE" }));
+    })))
+        .addCommand(new Command("widgets")
+        .description("Widgets on a dashboard: charts, saved views, embeds, notes, custom code, and live sources. `kinds` shows every configuration shape; `data` reads back the numbers a widget actually draws.")
+        .addCommand(new Command("kinds")
+        .description("List the widget kinds, what each one shows, whether it can cost credits, and an example configuration.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("dashboards widget kinds", options, () => requestOxygen("/api/cli/dashboards/widget-kinds"));
+    }))
+        .addCommand(new Command("add")
+        .description("Add a widget. Kinds: chart, view, iframe, rich_text, code, live_source. The configuration shape depends on the kind — run `oxygen dashboards widgets kinds` to see each one with an example.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<kind>", "chart | view | iframe | rich_text | code | live_source")
+        .argument("<title>", "Widget title.")
+        .option("--tab <tab_id>", "Tab to place it on. Defaults to the dashboard's first tab.")
+        .option("--config <json>", "Widget configuration as JSON.")
+        .option("--config-file <path>", "Read the configuration JSON from a file.")
+        .option("--position <json>", "Grid placement as JSON, e.g. '{\"x\":0,\"y\":0,\"w\":6,\"h\":4}'.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, kind, title, options) => {
+        await handleAsyncAction("dashboards widget add", options, async () => {
+            const body = { kind, title };
+            const tab = readOption(options.tab);
+            if (tab)
+                body.tab = tab;
+            body.configuration = await readDashboardWidgetConfig(options);
+            const position = readOption(options.position);
+            if (position)
+                body.position = parseJsonObject(position);
+            return requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/widgets`, { method: "POST", body });
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Change a widget's title, configuration or placement, or pause/resume a live source.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<widget_id>", "Widget id.")
+        .option("--title <title>", "New title.")
+        .option("--config <json>", "Replacement configuration as JSON. Replaces the whole configuration, never merged.")
+        .option("--config-file <path>", "Read the replacement configuration JSON from a file.")
+        .option("--position <json>", "New grid placement as JSON.")
+        .option("--pause", "Stop a live-source widget refreshing. It keeps showing its last result.")
+        .option("--resume", "Let a paused live-source widget refresh again.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, widgetId, options) => {
+        await handleAsyncAction("dashboards widget update", options, async () => {
+            if (options.pause && options.resume) {
+                throw new OxygenError("invalid_request", "Choose one of --pause or --resume, not both.", { exitCode: 1 });
+            }
+            const body = { widget: widgetId };
+            if (options.title !== undefined)
+                body.title = options.title;
+            if (readOption(options.config) || readOption(options.configFile)) {
+                body.configuration = await readDashboardWidgetConfig(options);
+            }
+            const position = readOption(options.position);
+            if (position)
+                body.position = parseJsonObject(position);
+            if (options.pause)
+                body.is_paused = true;
+            if (options.resume)
+                body.is_paused = false;
+            return requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/widgets`, { method: "PATCH", body });
+        });
+    }))
+        .addCommand(new Command("remove")
+        .description("Remove a widget from a dashboard.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<widget_id>", "Widget id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, widgetId, options) => {
+        await handleAsyncAction("dashboards widget remove", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/widgets?widget=${encodeURIComponent(widgetId)}`, { method: "DELETE" }));
+    }))
+        .addCommand(new Command("refresh")
+        .description("Refresh a live-source widget now. This is the only dashboard command that can cost credits, bounded by the ceiling saved on the widget. Opening a dashboard never spends.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<widget_id>", "Widget id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, widgetId, options) => {
+        await handleAsyncAction("dashboards widget refresh", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/widgets/${encodeURIComponent(widgetId)}/refresh`, { method: "POST" }));
+    }))
+        .addCommand(new Command("data")
+        .description("Read the data behind one widget — the same numbers the web page draws.")
+        .argument("<dashboard>", "Dashboard slug or id.")
+        .argument("<widget_id>", "Widget id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (dashboard, widgetId, options) => {
+        await handleAsyncAction("dashboards widget data", options, () => requestOxygen(`/api/cli/dashboards/${encodeURIComponent(dashboard)}/widgets/${encodeURIComponent(widgetId)}/data`));
+    })));
+}

package/dist/commands/db.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerDbFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/db.js

@@ -0,0 +1,190 @@
+import { readPositiveInt } from "../cli-values.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { DATABASE_QUERY_FLAG_OVERLAY } from "../database-query-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { DATABASE_ATTACH_CONTRACT, DATABASE_MIGRATE_CONTRACT, DATABASE_QUERY_CONTRACT } from "@oxygen/shared/contracts/database";
+import { Command } from "commander";
+export function registerDbFamily(program, handleAsyncAction) {
+    program
+        .command("db")
+        .description("Tenant database commands.")
+        .addCommand(new Command("status")
+        .description("Read-only, 0 credits: show the current database host and status, including historical Neon IDs, recorded region labels, and plan-included hosting; staff can pass global --org.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db status", options, () => requestOxygen("/api/cli/db/status"));
+    }))
+        .addCommand(new Command("provision")
+        .description("Provision the current organization on a registered PostgreSQL shard. Staff can pass global --org to repair another org.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db provision", options, () => requestOxygen("/api/cli/db/provision", { method: "POST", body: {} }));
+    }))
+        .addCommand(addContractFlags(new Command("migrate")
+        .description("Apply pending tenant database migrations for the current organization."), DATABASE_MIGRATE_CONTRACT, { rotate_credentials: { noNegate: true } })
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db migrate", options, () => requestOxygen("/api/cli/db/migrate", {
+            method: "POST",
+            body: readContractFlags(options, DATABASE_MIGRATE_CONTRACT, { rotate_credentials: { noNegate: true } }),
+        }));
+    }))
+        .addCommand(new Command("migrate-all")
+        .description("Apply pending tenant database migrations across all ready tenants (staff only).")
+        .option("--limit <n>", "Maximum tenants to migrate in this batch. Defaults to 50; hard cap is 500.")
+        .option("--dry-run", "List pending tenants without applying migrations.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db migrate-all", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen("/api/cli/db/migrate-all", {
+                method: "POST",
+                body: {
+                    ...(limit !== undefined ? { limit } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("repair-preview")
+        .description("Preview tenant database repair issues without mutating production state (staff only).")
+        .option("--limit <n>", "Maximum tenant and provisioning issues to inspect. Defaults to 100; hard cap is 500.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db repair-preview", options, () => {
+            const limit = readPositiveInt(options.limit);
+            const query = new URLSearchParams();
+            if (limit !== undefined)
+                query.set("limit", String(limit));
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/db/repair-preview${suffix}`);
+        });
+    }))
+        .addCommand(new Command("reconcile")
+        .description("Inspect tenant database registry drift. Staff only; defaults to dry-run.")
+        .option("--dry-run", "Report drift without applying repairs. This is the default.")
+        .option("--apply", "Apply safe registry repairs. Requires --confirm.")
+        .option("--confirm", "Confirm --apply for safe registry repairs.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db reconcile", options, () => {
+            if (options.apply && !options.confirm) {
+                throw new OxygenError("confirmation_required", "Refusing to apply tenant database reconciliation without --confirm.", { exitCode: 1 });
+            }
+            return requestOxygen("/api/cli/db/reconcile", {
+                method: "POST",
+                body: {
+                    apply: Boolean(options.apply),
+                    dry_run: !options.apply,
+                    confirm: Boolean(options.confirm),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("backfill-upsert-indexes")
+        .description("Create missing upsert-key secondary indexes on customer tables. Staff only; defaults to dry-run.")
+        .option("--dry-run", "Report the index backfill plan without creating indexes. This is the default.")
+        .option("--apply", "Create the missing indexes (CONCURRENTLY). Requires --confirm.")
+        .option("--confirm", "Confirm --apply for index creation.")
+        .option("--org <id>", "Limit the backfill to a single organization id.")
+        .option("--limit <n>", "Maximum ready tenants to inspect in this batch. Defaults to 25; hard cap is 200.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db backfill-upsert-indexes", options, () => {
+            if (options.apply && !options.confirm) {
+                throw new OxygenError("confirmation_required", "Refusing to create upsert-key indexes without --confirm.", { exitCode: 1 });
+            }
+            const limit = readPositiveInt(options.limit);
+            // `--org` is also a root option; Commander hands it to the root when
+            // both define it, so this subcommand's value arrives empty. Read both
+            // scopes (as backfill-table-order-indexes does) or the filter is lost
+            // and the backfill silently covers every tenant.
+            const organizationId = readOption(options.org) ?? readOption(program.opts().org);
+            return requestOxygen("/api/cli/db/backfill-upsert-indexes", {
+                method: "POST",
+                body: {
+                    apply: Boolean(options.apply),
+                    dry_run: !options.apply,
+                    confirm: Boolean(options.confirm),
+                    ...(organizationId ? { organization_id: organizationId } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("backfill-table-order-indexes")
+        .description("Converge stable row-order indexes on existing customer tables. Staff only; the default dry-run uses 0 credits and makes no database changes.")
+        .option("--dry-run", "Report readiness without creating indexes or spending credits. This is the default.")
+        .option("--apply", "Create missing indexes with CREATE INDEX CONCURRENTLY. Requires --confirm.")
+        .option("--confirm", "Confirm --apply for concurrent index creation.")
+        .option("--org <id>", "Limit the backfill to a single organization id.")
+        .option("--limit <n>", "Maximum ready tenants to inspect in this batch. Defaults to 25; hard cap is 200.")
+        .option("--json", "Print per-table details plus table_count, needs_preparation_count, in_progress_count, and error_count; pipe through `jq '.data | del(.tables)'` for a compact audit.")
+        .action(async (options) => {
+        await handleAsyncAction("db backfill-table-order-indexes", options, () => {
+            if (options.apply && !options.confirm) {
+                throw new OxygenError("confirmation_required", "Refusing to create table-order indexes without --confirm.", { exitCode: 1 });
+            }
+            const limit = readPositiveInt(options.limit);
+            // `--org` is also a root option (workspace override). Commander may
+            // attach it to the root command even when it appears after this
+            // subcommand, so read both scopes for this staff target filter.
+            const organizationId = readOption(options.org) ?? readOption(program.opts().org);
+            return requestOxygen("/api/cli/db/backfill-table-order-indexes", {
+                method: "POST",
+                body: {
+                    apply: Boolean(options.apply),
+                    dry_run: !options.apply,
+                    confirm: Boolean(options.confirm),
+                    ...(organizationId ? { organization_id: organizationId } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("cost-policy")
+        .description("Read-only, 0 credits. Show the retired Neon cost-policy status. Its managed field describes the policy, not database hosting; PostgreSQL has no per-workspace sleep control.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db cost-policy", options, () => requestOxygen("/api/cli/db/cost-policy"));
+    }))
+        .addCommand(new Command("reconcile-cost-policy")
+        .description("Retired compatibility command: report that Neon endpoint controls no longer apply.")
+        .option("--suspend-idle", "Retired compatibility flag; does not suspend PostgreSQL.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db reconcile-cost-policy", options, () => requestOxygen("/api/cli/db/reconcile-cost-policy", {
+            method: "POST",
+            body: {
+                ...(options.suspendIdle ? { suspend_idle: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(addContractFlags(new Command("attach")
+        .description("Attach an existing Postgres database as the current organization's tenant database.")
+        .requiredOption("--database-url <url>", "Owner connection string for the tenant Postgres database."), DATABASE_ATTACH_CONTRACT, { database_url: { omit: true } })
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db attach", options, () => requestOxygen("/api/cli/db/attach", {
+            method: "POST",
+            body: readContractFlags(options, DATABASE_ATTACH_CONTRACT),
+        }));
+    }))
+        .addCommand(addContractFlags(new Command("query")
+        .description("Run one read-only SQL statement against the current tenant database.")
+        .requiredOption("--sql <sql>", "Single SELECT, WITH, or EXPLAIN statement."), DATABASE_QUERY_CONTRACT, DATABASE_QUERY_FLAG_OVERLAY)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("db query", options, () => {
+            return requestOxygen("/api/cli/db/query", {
+                method: "POST",
+                body: {
+                    sql: options.sql,
+                    ...readContractFlags(options, DATABASE_QUERY_CONTRACT, DATABASE_QUERY_FLAG_OVERLAY),
+                },
+            });
+        });
+    }));
+}

package/dist/commands/deliverability.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerDeliverabilityFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;