@embrasure/ember 0.2.0

package/dist/plugin-edits.d.ts

@@ -0,0 +1,125 @@
+import type { EmbrasureApiClient } from "@embrasure/api-client";
+import type { PluginCatalogEdit, PluginIngestionEdit } from "./types.js";
+export declare function editPluginCatalog(client: EmbrasureApiClient, workspaceId: string, input: PluginCatalogEdit): Promise<{
+    preview: boolean;
+    key: string;
+    title: string;
+    summary: string;
+    object_ids: string[];
+    warnings: string[];
+    jobs: {
+        kind: string;
+        status: string;
+    }[];
+    object_id?: undefined;
+    current?: undefined;
+    changes?: undefined;
+    object?: undefined;
+} | {
+    preview: boolean;
+    object_id: string;
+    current: {
+        object_id: string;
+        title: unknown;
+        summary: unknown;
+        verification_status: unknown;
+        truth_kind: unknown;
+    };
+    changes: {
+        note?: string | undefined;
+        summary?: string | undefined;
+        title?: string | undefined;
+    };
+    key?: undefined;
+    title?: undefined;
+    summary?: undefined;
+    object_ids?: undefined;
+    warnings?: undefined;
+    jobs?: undefined;
+    object?: undefined;
+} | {
+    preview: boolean;
+    object_id: string;
+    object: {
+        object_id: string;
+        title: unknown;
+        summary: unknown;
+        verification_status: unknown;
+        truth_kind: unknown;
+    };
+    warnings: unknown;
+    key?: undefined;
+    title?: undefined;
+    summary?: undefined;
+    object_ids?: undefined;
+    jobs?: undefined;
+    current?: undefined;
+    changes?: undefined;
+}>;
+export declare function editPluginIngestion(client: EmbrasureApiClient, workspaceId: string, input: PluginIngestionEdit): Promise<{
+    ingestion_run_id: string;
+    table: {
+        table_id: string;
+        source_schema: string;
+        source_table: string;
+        destination_schema: string;
+        destination_table: string;
+        selected_columns: string[];
+        primary_key_columns: string[];
+        cursor_column: string | null | undefined;
+        status: string;
+        source_columns: {};
+        schema_change_status: string;
+    };
+    preview?: undefined;
+    table_id?: undefined;
+    source_schema?: undefined;
+    source_table?: undefined;
+    current_columns?: undefined;
+    requested_columns?: undefined;
+    effective_columns?: undefined;
+    primary_key_columns?: undefined;
+    cursor_column?: undefined;
+    warning?: undefined;
+    status?: undefined;
+} | {
+    preview: boolean;
+    ingestion_run_id: string;
+    table_id: string;
+    source_schema: string;
+    source_table: string;
+    current_columns: string[];
+    requested_columns: string[];
+    effective_columns: string[];
+    primary_key_columns: string[];
+    cursor_column: string | null | undefined;
+    warning: string;
+    table?: undefined;
+    status?: undefined;
+} | {
+    preview: boolean;
+    ingestion_run_id: string;
+    table_id: string;
+    status: string;
+    table: {
+        table_id: string;
+        source_schema: string;
+        source_table: string;
+        destination_schema: string;
+        destination_table: string;
+        selected_columns: string[];
+        primary_key_columns: string[];
+        cursor_column: string | null | undefined;
+        status: string;
+        source_columns: {};
+        schema_change_status: string;
+    };
+    source_schema?: undefined;
+    source_table?: undefined;
+    current_columns?: undefined;
+    requested_columns?: undefined;
+    effective_columns?: undefined;
+    primary_key_columns?: undefined;
+    cursor_column?: undefined;
+    warning?: undefined;
+}>;

package/dist/plugin-edits.js

@@ -0,0 +1,73 @@
+export async function editPluginCatalog(client, workspaceId, input) {
+    const preview = input.preview !== false;
+    if (input.action === "save") {
+        // Namespace stable keys so saving plugin notes cannot overwrite catalog anchors.
+        const ref = `embrasure-plugin:${input.key}`;
+        const data = await client.writeContext({
+            workspace_id: workspaceId, source: { kind: "manual", ref }, mode: "append",
+            processing_mode: "sync", apply_policy: preview ? "dry_run" : "auto",
+            content: { objects: [{
+                        stable_key: ref, object_type: "memory", title: input.title, summary: input.summary,
+                        truth_kind: "semantic_claim", verification_status: "observed", confidence: 1,
+                    }] },
+            infer: { objects: false, relationships: false, semantic_definitions: false, taxonomy_links: false, extract_facts: false },
+        });
+        return { preview, key: input.key, title: input.title, summary: input.summary,
+            object_ids: data.applied.object_ids, warnings: data.warnings,
+            jobs: data.jobs.map(({ kind, status }) => ({ kind, status })) };
+    }
+    if (input.title === undefined && input.summary === undefined)
+        throw new Error("Provide a title or summary to correct.");
+    if (preview) {
+        const current = await client.getContextObject(workspaceId, input.object_id);
+        return { preview: true, object_id: input.object_id, current: contextSummary(current.object), changes: {
+                ...(input.title !== undefined ? { title: input.title } : {}),
+                ...(input.summary !== undefined ? { summary: input.summary } : {}),
+                ...(input.note !== undefined ? { note: input.note } : {}),
+            } };
+    }
+    const data = await client.request(`/v1/context/objects/${encodeURIComponent(input.object_id)}/correct`, {
+        method: "POST", body: { workspace_id: workspaceId, title: input.title, summary: input.summary, note: input.note },
+    });
+    if (data.ok !== true || data.object_id !== input.object_id)
+        throw new Error("The API did not confirm this context edit. Inspect the object before retrying.");
+    return { preview: false, object_id: input.object_id, object: contextSummary(data.object), warnings: data.warnings };
+}
+function contextSummary(value) {
+    const object = value;
+    if (!object || typeof object.id !== "string")
+        throw new Error("The API did not return the context object. Inspect the catalog before retrying.");
+    return { object_id: object.id, title: object.title, summary: object.summary, verification_status: object.verification_status, truth_kind: object.truth_kind };
+}
+export async function editPluginIngestion(client, workspaceId, input) {
+    const connection = await client.getWarehouseIngestionConnection(workspaceId, input.ingestion_run_id);
+    const table = connection.tables.find((item) => item.id === input.table_id);
+    if (!table)
+        throw new Error("Ingestion table was not found in this connection and workspace.");
+    const describeTable = (value) => ({
+        table_id: value.id, source_schema: value.source_schema, source_table: value.source_table,
+        destination_schema: value.destination_schema, destination_table: value.destination_table,
+        selected_columns: value.selected_columns, primary_key_columns: value.primary_key_columns,
+        cursor_column: value.cursor_column, status: value.status,
+        source_columns: value.metadata?.all_source_columns ?? value.metadata?.source_columns ?? [],
+        schema_change_status: value.schema_change_status,
+    });
+    if (input.action === "inspect_table")
+        return { ingestion_run_id: input.ingestion_run_id, table: describeTable(table) };
+    if (input.preview !== false) {
+        return {
+            preview: true, ingestion_run_id: input.ingestion_run_id, table_id: input.table_id,
+            source_schema: table.source_schema, source_table: table.source_table,
+            current_columns: table.selected_columns, requested_columns: input.selected_columns,
+            effective_columns: [...new Set([...input.selected_columns, ...table.primary_key_columns, ...(table.cursor_column ? [table.cursor_column] : [])])],
+            primary_key_columns: table.primary_key_columns, cursor_column: table.cursor_column,
+            warning: "Required key and cursor columns are retained. Removing columns can affect downstream queries. Flow stages changes for resync; inspect the returned status before claiming they are active.",
+        };
+    }
+    const data = await client.updateWarehouseIngestionTable(workspaceId, input.ingestion_run_id, input.table_id, { selected_columns: input.selected_columns });
+    const updated = data.tables.find((item) => item.id === input.table_id);
+    if (!updated)
+        throw new Error("The API did not return the edited table. Inspect ingestion status before retrying.");
+    return { preview: false, ingestion_run_id: input.ingestion_run_id, table_id: input.table_id,
+        status: data.status, table: describeTable(updated) };
+}

package/dist/plugin-policy.d.ts

@@ -0,0 +1,71 @@
+import type { EmbrasureApiClient } from "@embrasure/api-client";
+import type { PluginPolicyInput } from "./types.js";
+/** Requirements and reported evidence only; this never executes customer code. */
+export declare function operatePluginPolicy(client: EmbrasureApiClient, workspaceId: string, input: PluginPolicyInput): Promise<import("@embrasure/api-client").DataPolicyContext | import("@embrasure/api-client").SaveDataPolicyResponse | import("@embrasure/api-client").RecordDataPolicyAssessmentResponse | {
+    assessments: import("@embrasure/api-client").DataPolicyAssessment[];
+    assessment_history: {
+        total_count: number;
+        omitted_count: number;
+        selection: string;
+        policy_url: string;
+    };
+    policy_id: string;
+    key: string;
+    title: string;
+    revision: string;
+    source: {
+        content: string;
+        url: string | null;
+    };
+    requirements: import("@embrasure/api-client").DataPolicyRequirement[];
+    object_ids: string[];
+    assets: import("@embrasure/api-client").DataPolicyAsset[];
+    edges: Array<Record<string, unknown>>;
+    coverage: {
+        status: "bounded";
+        gaps: string[];
+        fingerprint: string;
+    };
+    implementation_guidance: string[];
+    synthetic?: boolean;
+    execution?: import("@embrasure/api-client").DataPolicyDemoState;
+    prepared_implementation?: {
+        status: "ready" | "needs_review";
+        implementation_revision: string;
+        source_path: string;
+        requirement_ids: string[];
+        unresolved_requirement_ids: string[];
+        blockers: string[];
+        steps: Array<{
+            id: string;
+            title: string;
+            requirement_ids: string[];
+            operation: string;
+            verification: string;
+        }>;
+    };
+    preview?: undefined;
+    requirement_count?: undefined;
+    assessment?: undefined;
+} | {
+    preview: boolean;
+    policy_id: string;
+    revision: string;
+    title: string;
+    requirement_count: number;
+    assessment?: undefined;
+} | {
+    preview: boolean;
+    policy_id: string;
+    revision: string;
+    assessment: {
+        id: string;
+        status: "reported";
+        policy_revision: string;
+        code_revision: string;
+        check_count: number;
+        created_at: string;
+    };
+    title?: undefined;
+    requirement_count?: undefined;
+}>;

package/dist/plugin-policy.js

@@ -0,0 +1,47 @@
+/** Requirements and reported evidence only; this never executes customer code. */
+export async function operatePluginPolicy(client, workspaceId, input) {
+    if (input.action === "policy_context") {
+        const data = await client.getDataPolicyContext(workspaceId, input.policy_id);
+        if (data.policy_id !== input.policy_id)
+            throw new Error("The API did not return the selected policy. Inspect the policy handle before retrying.");
+        // Older API responses may omit history; preserve that shape rather than inventing an empty assessment.
+        if (!Array.isArray(data.assessments))
+            return data;
+        const assessments = [...data.assessments].sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at)).slice(0, 1);
+        return {
+            ...data,
+            assessments,
+            assessment_history: {
+                total_count: data.assessments.length,
+                omitted_count: Math.max(0, data.assessments.length - assessments.length),
+                selection: "Latest recorded assessment; older assessments are available on the policy page. This does not establish current or complete coverage.",
+                policy_url: `https://app.embrasure.ai/context/policies?policy=${encodeURIComponent(data.policy_id)}&view=evidence`,
+            },
+        };
+    }
+    if (input.action === "save_requirements") {
+        const { action: _action, ...body } = input;
+        const data = await client.saveDataPolicy(workspaceId, body);
+        if (data.preview !== (input.preview !== false) || !data.policy_id || !data.revision || data.context?.policy_id !== data.policy_id) {
+            throw new Error("The API did not confirm this requirement source. Read its context before retrying or claiming it was saved.");
+        }
+        return data.preview ? data : {
+            preview: false, policy_id: data.policy_id, revision: data.revision,
+            title: data.context.title, requirement_count: data.context.requirements.length,
+        };
+    }
+    const { action: _action, policy_id, ...body } = input;
+    const data = await client.recordDataPolicyAssessment(workspaceId, policy_id, body);
+    if (data.preview !== (input.preview !== false) || data.assessment?.status !== "reported"
+        || data.assessment.policy_revision !== input.policy_revision || data.assessment.code_revision !== input.code_revision
+        || data.assessment.scope_fingerprint !== input.scope_fingerprint
+        || data.context?.policy_id !== policy_id) {
+        throw new Error("The API did not confirm the reported assessment. Read policy context before retrying. Reported results are not independent verification.");
+    }
+    return data.preview ? data : {
+        preview: false, policy_id, revision: data.context.revision,
+        assessment: { id: data.assessment.id, status: data.assessment.status,
+            policy_revision: data.assessment.policy_revision, code_revision: data.assessment.code_revision,
+            check_count: data.assessment.checks.length, created_at: data.assessment.created_at },
+    };
+}

package/dist/program.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createProgram(): Command;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/program.js

@@ -0,0 +1,274 @@
+import { EMBER_VERSION } from "./version.js";
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { Command, Option } from "commander";
+import { browserLogin, logout, resolveRuntime } from "./auth.js";
+import { serveEmberMcpStdio } from "./mcp.js";
+import { EmberOperator } from "./operator.js";
+function globals(command) { return command.optsWithGlobals(); }
+async function runtime(command) {
+    const options = globals(command);
+    return resolveRuntime({ apiBaseUrl: options.apiUrl, webBaseUrl: options.webUrl, workspaceId: options.workspace });
+}
+function operator(current) {
+    if (!current.accessToken)
+        throw new Error("Not signed in. Run `ember auth login` or set EMBER_API_TOKEN.");
+    if (!current.workspaceId)
+        throw new Error("No workspace selected. Sign in again or set EMBER_WORKSPACE_ID.");
+    return new EmberOperator({ apiBaseUrl: current.apiBaseUrl, accessToken: current.accessToken, workspaceId: current.workspaceId, clientName: "ember-cli" });
+}
+function output(command, value, human) {
+    const options = globals(command);
+    if (options.quiet)
+        return;
+    process.stdout.write(options.json ? `${JSON.stringify(value)}\n` : `${human ?? render(value)}\n`);
+}
+function render(value, indent = 0) {
+    if (value === null || typeof value !== "object")
+        return String(value);
+    if (Array.isArray(value))
+        return value.map((item) => `${" ".repeat(indent)}- ${render(item, indent + 2)}`).join("\n");
+    return Object.entries(value).map(([key, item]) => {
+        if (item && typeof item === "object")
+            return `${" ".repeat(indent)}${key}:\n${render(item, indent + 2)}`;
+        return `${" ".repeat(indent)}${key}: ${String(item)}`;
+    }).join("\n");
+}
+export function createProgram() {
+    const program = new Command().name("ember").description("Operate your Ember data warehouse.").version(EMBER_VERSION)
+        .option("--api-url <url>", "Embrasure API URL", process.env.EMBER_API_BASE_URL)
+        .option("--web-url <url>", "Embrasure app URL", process.env.EMBER_WEB_BASE_URL)
+        .option("--workspace <id>", "Workspace ID", process.env.EMBER_WORKSPACE_ID)
+        .option("--json", "Write one JSON document to stdout")
+        .option("--quiet", "Suppress normal output");
+    program.command("setup")
+        .description("Idempotently set up the managed Ember warehouse and show MCP configuration")
+        .addOption(new Option("--client <client>", "MCP client").choices(["auto", "codex", "claude", "cursor", "generic"]).default("auto"))
+        .option("--plan", "Show the setup plan without applying it")
+        .action(async (options, command) => {
+        const result = await operator(await runtime(command)).setup({ action: options.plan ? "plan" : "apply" });
+        const mcp = options.plan ? clientSetupInstructions(options.client) : await configureClient(options.client);
+        output(command, { ...result, mcp }, `${render(result)}\n\nMCP: ${mcp.instruction}`);
+    });
+    const auth = program.command("auth").description("Manage the saved browser session");
+    auth.command("login").option("--no-open", "Do not open the browser").action(async (options, command) => {
+        const next = await browserLogin(await runtime(command), options.open);
+        output(command, { authenticated: true, workspace_id: next.workspaceId }, `Signed in. Workspace: ${next.workspaceId}`);
+    });
+    auth.command("status").action(async (_options, command) => {
+        const current = await runtime(command);
+        const authenticated = Boolean(current.accessToken);
+        output(command, { authenticated, workspace_id: current.workspaceId, api_base_url: current.apiBaseUrl }, authenticated ? `Signed in. Workspace: ${current.workspaceId}` : "Not signed in.");
+        if (!authenticated)
+            process.exitCode = 2;
+    });
+    auth.command("logout").action(async (_options, command) => { const result = await logout(); output(command, { authenticated: false, session_revoked: result.sessionRevoked }, result.sessionRevoked ? "Signed out and revoked the session." : "Signed out locally."); });
+    program.command("status").description("Show warehouse readiness and freshness")
+        .option("--watch", "Poll until ready or the watch limit is reached")
+        .option("--interval <seconds>", "Polling interval", "5")
+        .option("--max-wait <seconds>", "Maximum watch time", "300")
+        .action(async (options, command) => {
+        const ember = operator(await runtime(command));
+        let result = await ember.status();
+        if (options.watch) {
+            const maxWait = numericOption(options.maxWait, "max wait", 5, 1800);
+            const interval = numericOption(options.interval, "polling interval", 1, 60);
+            const deadline = Date.now() + maxWait * 1000;
+            const controller = new AbortController();
+            const stop = () => controller.abort();
+            process.once("SIGINT", stop);
+            try {
+                while (!controller.signal.aborted && Date.now() < deadline && result.data.phase !== "ready") {
+                    if (!globals(command).quiet)
+                        process.stderr.write("Waiting for Ember...\n");
+                    await delay(interval * 1000, controller.signal);
+                    if (!controller.signal.aborted)
+                        result = await ember.status();
+                }
+            }
+            finally {
+                process.removeListener("SIGINT", stop);
+            }
+            if (controller.signal.aborted)
+                process.exitCode = 130;
+            else if (result.data.phase !== "ready")
+                process.exitCode = 3;
+        }
+        output(command, result);
+    });
+    const source = program.command("source").description("Connect and inspect data sources");
+    source.command("types").action(run((ember) => ember.sources({ action: "types" })));
+    source.command("list").action(run((ember) => ember.sources({ action: "list" })));
+    source.command("connect <kind>").description("Connect a source through a browser handoff or credentials read from env/stdin")
+        .option("--name <name>").option("--mode <mode>").option("--credential-env <name>", "Read credentials from an environment variable")
+        .option("--credential-stdin", "Read credentials from stdin").option("--no-open", "Do not open browser handoffs")
+        .option("--max-wait <seconds>", "Maximum OAuth wait time", "300")
+        .action(async (kind, options, command) => {
+        const current = await runtime(command);
+        const ember = operator(current);
+        if (options.credentialEnv || options.credentialStdin) {
+            if (!["postgres", "supabase"].includes(String(kind).toLowerCase())) {
+                throw new Error("Environment and stdin credentials are only supported for Postgres and Supabase. Use the browser handoff for this source.");
+            }
+            const raw = options.credentialEnv ? process.env[options.credentialEnv] : await readStdin();
+            if (!raw)
+                throw new Error("The credential reference was empty.");
+            const credentials = parseCredentials(raw);
+            const connection = await ember.client.createConnector({ workspace_id: ember.workspaceId, name: options.name ?? `${kind} source`, kind, connector_usage: "warehouse_ingestion" });
+            await ember.client.upsertConnectorCredentials(connection.id, { workspace_id: ember.workspaceId, credentials, scope: "workspace" });
+            const result = await ember.sources({ action: "verify", connection_id: connection.id });
+            output(command, result);
+            return;
+        }
+        const result = await ember.sources({ action: "connect", kind, name: options.name, mode: options.mode });
+        const url = typeof result.data.authorization_url === "string" ? result.data.authorization_url : null;
+        if (url && !globals(command).quiet)
+            process.stderr.write(`Open to connect ${kind}:\n${url}\n`);
+        if (url && options.open)
+            await openUrl(url);
+        const connectionId = typeof result.data.connector_id === "string" ? result.data.connector_id : null;
+        if (result.data.auth_strategy === "oauth" && connectionId) {
+            const watched = await waitForSourceConnection(ember, connectionId, numericOption(options.maxWait, "max wait", 5, 1800), command);
+            output(command, { ...result, data: { ...result.data, connection: watched.data } });
+            return;
+        }
+        output(command, result);
+    });
+    source.command("status <connection-id>").action(run((ember, id) => ember.sources({ action: "status", connection_id: required(id, "connection id") })));
+    source.command("verify <connection-id>").action(run((ember, id) => ember.sources({ action: "verify", connection_id: required(id, "connection id") })));
+    const ingest = program.command("ingest").description("Plan and control ingestion");
+    for (const action of ["plan", "start"])
+        ingest.command(`${action} <connection-id>`)
+            .requiredOption("--source-kind <kind>").option("--name <name>").option("--database-id <id>")
+            .addOption(new Option("--engine <engine>", "Ingestion engine").choices(["worker_batch", "aws_dms_firehose", "embrasure_flow"]).default("worker_batch")).option("--cadence <minutes>")
+            .option("--tables <json-or-file>", "Override recommended tables with a JSON array or @path")
+            .action(async (connectionId, options, command) => {
+            const tables = options.tables ? await jsonArgument(options.tables) : undefined;
+            const result = await operator(await runtime(command)).ingestion({ action, connection_id: connectionId, source_kind: options.sourceKind, name: options.name, database_id: options.databaseId, ingestion_engine: options.engine, cadence_minutes: options.cadence ? numericOption(options.cadence, "cadence", 15, 10080) : undefined, tables });
+            output(command, result);
+        });
+    ingest.command("status [ingestion-run-id]").action(run((ember, id) => ember.ingestion({ action: "status", ingestion_run_id: id })));
+    for (const action of ["sync", "pause", "resume"])
+        ingest.command(`${action} <ingestion-run-id>`).action(run((ember, id) => ember.ingestion({ action, ingestion_run_id: required(id, "ingestion run id") })));
+    const query = program.command("query").description("Run read-only SQL against qualified warehouse relations and inspect query handles");
+    query.command("run <sql>").option("--database <name>", "Default database", "ember").option("--max-rows <number>", "Retained-result cap (10000); use SQL LIMIT for fewer rows")
+        .action(async (sql, options, command) => output(command, await operator(await runtime(command)).query({ action: "run", sql, database: options.database, max_result_rows: options.maxRows ? numericOption(options.maxRows, "max rows", 1, 10000) : undefined })));
+    query.command("status <query-id>").action(run((ember, id) => ember.query({ action: "status", query_id: required(id, "query id") })));
+    query.command("results <query-id>").option("--limit <number>").option("--next-token <token>")
+        .action(async (id, options, command) => output(command, await operator(await runtime(command)).query({ action: "results", query_id: id, limit: options.limit ? numericOption(options.limit, "limit", 1, 100) : undefined, next_token: options.nextToken })));
+    query.command("history").option("--limit <number>").action(async (options, command) => output(command, await operator(await runtime(command)).query({ action: "history", limit: options.limit ? numericOption(options.limit, "limit", 1, 100) : undefined })));
+    query.command("cancel <query-id>").action(run((ember, id) => ember.query({ action: "cancel", query_id: required(id, "query id") })));
+    const warehouse = program.command("warehouse").description("Set up the warehouse and inspect readiness or usage");
+    for (const action of ["plan", "apply"]) {
+        warehouse.command(action).option("--database <name>").action(async (options, command) => output(command, await operator(await runtime(command)).execute({ tool: "warehouse", input: { action, database: options.database } })));
+    }
+    warehouse.command("status").action(run((ember) => ember.execute({ tool: "warehouse", input: { action: "status" } })));
+    warehouse.command("usage").addOption(new Option("--window <window>").choices(["month_to_date", "7d", "30d", "90d"]).default("month_to_date")).action(async (options, command) => output(command, await operator(await runtime(command)).execute({ tool: "warehouse", input: { action: "usage", window: options.window } })));
+    const catalog = program.command("catalog").description("Search business definitions and inspect selected warehouse schemas");
+    catalog.command("search <query>").option("--limit <number>", "Maximum matches", "10").option("--refs <refs...>", "Source or relation references to anchor retrieval")
+        .action(async (query, options, command) => output(command, await operator(await runtime(command)).execute({ tool: "catalog", input: { action: "search", query, limit: numericOption(options.limit, "limit", 1, 20), refs: options.refs } })));
+    catalog.command("describe <object-id>").option("--no-related", "Return only the selected definition")
+        .action(async (id, options, command) => output(command, await operator(await runtime(command)).execute({ tool: "catalog", input: { action: "describe", target: "context", object_id: id, include_related: options.related } })));
+    catalog.command("tables <database>").option("--limit <number>", "Page size", "20").option("--next-token <token>")
+        .action(async (database, options, command) => output(command, await operator(await runtime(command)).execute({ tool: "catalog", input: { action: "list", database, limit: numericOption(options.limit, "limit", 1, 100), next_token: options.nextToken } })));
+    catalog.command("table <database> <table>").option("--column-limit <number>", "Column page size", "50").option("--column-offset <number>", "Column offset", "0")
+        .action(async (database, table, options, command) => output(command, await operator(await runtime(command)).execute({ tool: "catalog", input: { action: "describe", target: "table", database, table, column_limit: numericOption(options.columnLimit, "column limit", 1, 100), column_offset: numericOption(options.columnOffset, "column offset", 0, 100000) } })));
+    program.command("mcp").description("MCP transport commands").command("serve").description("Serve the five Ember tools over stdio").action(async (_options, command) => {
+        operator(await runtime(command));
+        serveEmberMcpStdio(async (signal) => {
+            const current = await runtime(command);
+            if (!current.accessToken || !current.workspaceId)
+                return operator(current);
+            return new EmberOperator({ apiBaseUrl: current.apiBaseUrl, accessToken: current.accessToken, workspaceId: current.workspaceId, clientName: "ember-mcp-stdio", signal });
+        });
+    });
+    return program;
+}
+export async function runCli(argv = process.argv) { await createProgram().parseAsync(argv); }
+function run(action) {
+    return async (...args) => { const command = args.at(-1); const first = typeof args[0] === "string" ? args[0] : undefined; output(command, await action(operator(await runtime(command)), first)); };
+}
+function clientSetupInstructions(client) {
+    const selected = client === "auto" ? "generic" : client;
+    const remoteUrl = "https://embrasure.ai/api/mcp/ember";
+    const instructions = { codex: "Run `codex mcp login ember` to approve the workspace.", claude: "Open `/mcp` in Claude Code to approve the workspace.", cursor: `Add {\"ember\":{\"url\":\"${remoteUrl}\"}} to Cursor MCP settings.`, generic: `Connect your MCP client to ${remoteUrl}, or run: ember mcp serve` };
+    return { client: selected, configured: false, remote_url: remoteUrl, stdio_command: "ember mcp serve", instruction: instructions[selected] ?? instructions.generic };
+}
+async function configureClient(client) {
+    const selected = client === "auto" ? await detectedClient() : client;
+    const setup = clientSetupInstructions(selected);
+    if (selected === "codex" && await commandExists("codex")) {
+        await addMcpServer("codex", ["mcp", "add", "ember", "--url", setup.remote_url]);
+        return { ...setup, configured: true };
+    }
+    if (selected === "claude" && await commandExists("claude")) {
+        await addMcpServer("claude", ["mcp", "add", "--transport", "http", "-s", "user", "ember", setup.remote_url]);
+        return { ...setup, configured: true };
+    }
+    return setup;
+}
+async function addMcpServer(command, args) {
+    try {
+        await runProcess(command, args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/already (exists|configured|registered)|duplicate/i.test(message))
+            throw error;
+    }
+}
+async function detectedClient() { if (await commandExists("codex"))
+    return "codex"; if (await commandExists("claude"))
+    return "claude"; return "generic"; }
+function commandExists(command) { return runProcess("sh", ["-c", `command -v ${command}`]).then(() => true).catch(() => false); }
+function runProcess(command, args) { return new Promise((resolve, reject) => { const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] }); let stderr = ""; child.stderr.on("data", (chunk) => { stderr += chunk; }); child.once("error", reject); child.once("close", (code) => code === 0 ? resolve() : reject(new Error(stderr.trim() || `${command} failed.`))); }); }
+async function jsonArgument(value) { return JSON.parse(value.startsWith("@") ? await readFile(value.slice(1), "utf8") : value); }
+function parseCredentials(raw) { try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error();
+    return parsed;
+}
+catch {
+    return { database_url: raw.trim() };
+} }
+async function readStdin() { let value = ""; process.stdin.setEncoding("utf8"); for await (const chunk of process.stdin)
+    value += chunk; return value.trim(); }
+function openUrl(url) { const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open"; const args = process.platform === "win32" ? ["/c", "start", "", url] : [url]; return new Promise((resolve) => { const child = spawn(command, args, { detached: true, stdio: "ignore" }); child.once("error", () => resolve()); child.once("spawn", () => { child.unref(); resolve(); }); }); }
+function clamp(value, min, max) { return Number.isFinite(value) ? Math.min(Math.max(value, min), max) : min; }
+function numericOption(value, label, min, max) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        throw new Error(`${label} must be an integer from ${min} to ${max}.`);
+    }
+    return parsed;
+}
+function required(value, label) { if (!value)
+    throw new Error(`Missing ${label}.`); return value; }
+function delay(ms, signal) { return new Promise((resolve) => { const timeout = setTimeout(resolve, ms); signal.addEventListener("abort", () => { clearTimeout(timeout); resolve(); }, { once: true }); }); }
+async function waitForSourceConnection(ember, connectionId, maxWaitSeconds, command) {
+    const deadline = Date.now() + clamp(maxWaitSeconds, 5, 1800) * 1000;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    let result = await ember.sources({ action: "status", connection_id: connectionId });
+    try {
+        while (!controller.signal.aborted && Date.now() < deadline && result.data.status !== "connected") {
+            if (!globals(command).quiet)
+                process.stderr.write("Waiting for source authorization...\n");
+            await delay(2_000, controller.signal);
+            if (!controller.signal.aborted)
+                result = await ember.sources({ action: "status", connection_id: connectionId });
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+    }
+    if (controller.signal.aborted) {
+        process.exitCode = 130;
+        return result;
+    }
+    if (result.data.status !== "connected")
+        process.exitCode = 3;
+    return result;
+}

package/dist/query-response.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export declare const queryResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        queued: "queued";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$loose>;
+export declare const queryHistoryResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        queued: "queued";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$loose>>;
+export declare const queryResultsResponseSchema: z.ZodObject<{
+    query: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodLiteral<"succeeded">;
+    }, z.core.$loose>;
+    columns: z.ZodArray<z.ZodString>;
+    column_types: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    next_token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;

package/dist/query-response.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+// Validate only the fields Ember needs to identify an operation or read its page.
+// Keep additional API fields so optional metadata can evolve independently.
+export const queryResponseSchema = z.looseObject({
+    id: z.string().min(1).max(128).regex(/^\S+$/),
+    status: z.enum(["queued", "running", "succeeded", "failed", "cancelled"]),
+});
+export const queryHistoryResponseSchema = z.array(queryResponseSchema);
+export const queryResultsResponseSchema = z.looseObject({
+    query: queryResponseSchema.extend({ status: z.literal("succeeded") }),
+    columns: z.array(z.string()),
+    column_types: z.record(z.string(), z.string()).optional(),
+    rows: z.array(z.record(z.string(), z.unknown())),
+    next_token: z.string().min(1).max(4096).nullable().optional(),
+});