@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/register-reads.js

@@ -0,0 +1,187 @@
+import { readPositiveInt, readJsonObjectOption, readNonNegativeInt } from "../../cli-values.js";
+import { writeListCapNotice, readFilterJsonOption, readFormulaValuesOption, readCsvOption } from "../../command-support.js";
+import { addContractFlags, readContractFlags } from "../../contract-flags.js";
+import { requestOxygen } from "../../http-client.js";
+import { writeExclusiveJson } from "../../json-output.js";
+import { readOption } from "../../util.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { TABLE_LIST_QUERY_CONTRACT, tableListQueryParams } from "@oxygen/shared/contracts/table-list";
+import { TABLE_QUERY_GRID_CONTRACT } from "@oxygen/shared/contracts/table-query-grid";
+import { TABLE_QUERY_CLI_DEFAULT_LIMIT, TABLE_QUERY_CLI_DEFAULT_MAX_CHARS, tableQueryRawResultFits, tableQueryRawRecovery } from "@oxygen/shared/contracts/table-query-raw";
+import { FILTER_TREE_OPERATORS } from "@oxygen/shared/table-filter-operators";
+import { Command } from "commander";
+import { handleTablesTidySuggestAction } from "./display.js";
+import { readSortJsonOption } from "./automation.js";
+export function registerReads({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(addContractFlags(new Command("list").description("List workspace tables in the current tenant database."), TABLE_LIST_QUERY_CONTRACT, {
+        project: { help: "Project id or slug to filter by." },
+        tag: { help: "Only tables carrying this workspace tag (see `oxygen tags list`)." },
+        include_archived: {
+            help: "Also list archived, delete-scheduled and purging tables (the trash; each carries a lifecycle with purge_scheduled_at, and one with purgeStartedAt is being purged and can no longer be restored).",
+        },
+        limit: { help: "Maximum tables to list. Defaults to 200; hard cap is 1000.", valueName: "<n>" },
+    })
+        .option("--all", "List every table instead of the newest window.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nLists the 200 newest tables by default. Follow nextCursor with --cursor and the same filters, or pass --all. --query searches names across every table; --projection summary keeps results compact. rowCount is null when not reconciled; measure unknown counts with `tables describe <table> --stats`.\n")
+        .action(async (options) => {
+        await handleAsyncAction("tables list", options, async () => {
+            const params = tableListQueryParams(readContractFlags(options, TABLE_LIST_QUERY_CONTRACT));
+            if (options.all)
+                params.set("all", "true");
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/tables${qs}`);
+            // A capped list is where a blind agent filtered 200 rows locally to find
+            // one table by name (acceptance run, 2026-09-18); name the native lookup.
+            if (!options.json)
+                writeListCapNotice(data, "table(s)", "continue with --cursor <nextCursor>, or find a name with --query <text>");
+            return data;
+        });
+    }));
+    tablesCommand.addCommand(addContractFlags(new Command("query"), TABLE_QUERY_GRID_CONTRACT, {
+        format: { valueName: "<format>", help: "Grid cell previews/state: default 50, cap 200, optional stats/fill/window. Omit for raw filters, fields, search, sorts or offsets. JSON cells are null; their digests live in __oxygen_grid_cell_previews. Use tables rows inspect --projection value for complete values." },
+        max_chars: { help: "Maximum compact JSON envelope characters for raw or grid reads (1,000-100,000). Raw defaults to 12,000." },
+    })
+        .description("Read raw Table rows or --format grid cell previews/state with grid.nextCursor, in a JSON envelope. Use tables preview --summary-only for fill rates; tables export <table> --format table renders raw rows. Grid supports stats/fill/window options and refuses raw selectors.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Raw: default 20, native cap 2000; --full restores default 100. Grid: default 50, cap 200.")
+        .option("--cursor <cursor>", "Pagination cursor returned by a previous query. Walks forward one page at a time; mutually exclusive with --offset.")
+        .option("--offset <n>", "Skip this many rows and start there — jump straight to a row without paging to it. Mutually exclusive with --cursor.")
+        .option("--fields <columns>", "Comma-separated column keys or ids to include.")
+        .option("--filter-json <json>", "Legacy filter object or array, e.g. '{\"column\":\"mobile_phone_e164\",\"op\":\"is_null\"}'. Mutually exclusive with --filter-tree-json/--sort-json.")
+        .option("--filter-tree-json <json>", `Airtable-style filter group, e.g. '{\"type\":\"group\",\"conjunction\":\"and\",\"children\":[{\"type\":\"leaf\",\"columnKey\":\"stage\",\"operator\":\"is\",\"value\":\"won\"}]}'. Add \"path\":\"a.b\" to a leaf to match a key inside a JSON cell, e.g. the rows one Function run touched: {\"columnKey\":\"<function_column>\",\"path\":\"action_run_id\",\"operator\":\"is\",\"value\":\"<run_id>\"}. Leaf operators: ${FILTER_TREE_OPERATORS.join(", ")} (is_true/is_false need a checkbox column; --filter-json's is_null/is_not_null are is_empty/is_not_empty here). Mutually exclusive with --filter-json.`)
+        .option("--search <text>", "Find rows by one piece of text, matched against every text, number, date and checkbox column at once — the grid's magnifier. Combines with --filter-tree-json (both must hold). Use --filter-tree-json when you know which column to match.")
+        .option("--formula-values <mode>", "Formula filters are refused by default because displayed formulas are evaluated live. Refresh the formula's stored cells with `columns run <table> <column> --force` (0 credits), then pass 'materialized'; filtering uses that stored snapshot and returns a freshness note. A fill-empty field a bundle adds (definition fill: \"empty\", such as Headcount or Job title) is stored, not live: its cell is the value, so 'materialized' filters it exactly.")
+        .option("--sort-json <json>", "Ordered sort rules, e.g. '[{\"columnKey\":\"_created_at\",\"direction\":\"desc\"}]'. Earlier rules dominate. Mutually exclusive with --filter-json.")
+        .option("--no-system-fields", "Omit _row_id, _created_at, and _updated_at from returned rows (included by default).")
+        .option("--full", "Read legacy full rows without the default character limit.")
+        .option("--output <path>", "Write full JSON for this page to a new local file; print a small receipt.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables query", options, async () => {
+            const gridArgs = readContractFlags(options, TABLE_QUERY_GRID_CONTRACT);
+            if (gridArgs.format !== "grid" && Object.keys(gridArgs).some((key) => key !== "max_chars")) {
+                throw new OxygenError("invalid_request", "Grid options require --format grid.", { exitCode: 1 });
+            }
+            const full = options.full || Boolean(options.output);
+            if (full && options.format === "grid")
+                throw new OxygenError("invalid_request", "--full/--output require raw rows; omit --format grid.", { exitCode: 2 });
+            const limit = readPositiveInt(options.limit) ?? (options.format !== "grid" && !full ? TABLE_QUERY_CLI_DEFAULT_LIMIT : undefined);
+            if (options.format !== "grid" && !full && gridArgs.max_chars === undefined)
+                gridArgs.max_chars = TABLE_QUERY_CLI_DEFAULT_MAX_CHARS;
+            const filters = readFilterJsonOption(options.filterJson);
+            const filterTree = readJsonObjectOption(options.filterTreeJson);
+            const formulaValues = readFormulaValuesOption(options.formulaValues);
+            const sorts = readSortJsonOption(options.sortJson);
+            const offset = readNonNegativeInt(options.offset);
+            if (filters && (filterTree || sorts)) {
+                throw new OxygenError("invalid_filter", "Pass either --filter-json (legacy) or --filter-tree-json/--sort-json, not both.", { exitCode: 1 });
+            }
+            if (formulaValues && !filters && !filterTree) {
+                throw new OxygenError("invalid_filter", "--formula-values requires --filter-json or --filter-tree-json.", { exitCode: 1 });
+            }
+            if (readOption(options.cursor) && offset !== undefined) {
+                throw new OxygenError("invalid_request", "Pass either --cursor or --offset, not both.", { exitCode: 1 });
+            }
+            if (options.format === "grid" && (readCsvOption(options.fields).length > 0 || filters?.length || filterTree ||
+                readOption(options.search) || formulaValues || sorts?.length || (offset !== undefined && offset > 0))) {
+                throw new OxygenError("invalid_request", '--format grid takes only table, --limit, --cursor and optional --include-stats/--include-fill; omit --format for filters, fields, search, sorts or offsets.', { exitCode: 1 });
+            }
+            const data = await requestOxygen("/api/cli/tables/query", {
+                method: "POST",
+                body: {
+                    table,
+                    ...gridArgs,
+                    ...(limit ? { limit } : {}),
+                    ...(readOption(options.cursor) ? { cursor: readOption(options.cursor) } : {}),
+                    ...(offset !== undefined ? { offset } : {}),
+                    ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
+                    ...(filters ? { filters } : {}),
+                    ...(filterTree ? { filterTree } : {}),
+                    ...(readOption(options.search) ? { search: readOption(options.search) } : {}),
+                    ...(formulaValues ? { formula_values: formulaValues } : {}),
+                    ...(sorts ? { sorts } : {}),
+                    ...(options.systemFields === false ? { include_system_fields: false } : {}),
+                },
+            });
+            // Enforce the window even against an older compatible serving API.
+            if (options.format !== "grid" && !tableQueryRawResultFits(data, typeof gridArgs.max_chars === "number" ? gridArgs.max_chars : undefined)) {
+                const firstRow = Array.isArray(data.rows) ? data.rows[0] : undefined;
+                throw new OxygenError("table_query_result_too_large", "Table rows exceed the requested result window.", {
+                    details: { max_chars: gridArgs.max_chars, ...tableQueryRawRecovery(table, typeof firstRow?._row_id === "string" ? firstRow._row_id : undefined) }, exitCode: 2,
+                });
+            }
+            if (!options.output)
+                return data;
+            const output = await writeExclusiveJson(options.output, success("tables query", data), process.argv.includes("--pretty"));
+            return { output, returned_count: data.returned_count ?? data.returnedCount, total_count: data.total_count ?? data.totalCount, hasMore: data.hasMore, nextCursor: data.nextCursor, web_url: data.web_url };
+        });
+    }));
+    tablesCommand.addCommand(new Command("preview")
+        .description("Preview a workspace table with projected rows and summary stats.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum preview rows to return. Defaults to 25; hard cap is 1000.")
+        .option("--fields <columns>", "Comma-separated column keys or ids to include.")
+        .option("--include-system-fields", "Include _row_id, _created_at, and _updated_at in preview rows.")
+        .option("--include-cell-states", "Include per-cell run state in the preview response.")
+        .option("--summary-only", "Return per-column fill stats plus table metadata, without row JSON. Stats cover the whole table independent of --limit: exact up to 20,000 rows, then a 2,000-row sample labelled summary.statsSampled; rowCount stays exact. Higher fidelity than `tables describe --stats`, which samples at 100. fillRate counts non-null cells, nonEmptyRate also excludes blank strings. 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables preview", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen("/api/cli/tables/preview", {
+                method: "POST",
+                body: {
+                    table,
+                    ...(limit ? { limit } : {}),
+                    ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
+                    ...(options.includeSystemFields ? { include_system_fields: true } : {}),
+                    ...(options.includeCellStates ? { include_cell_states: true } : {}),
+                    ...(options.summaryOnly ? { summary_only: true } : {}),
+                },
+            });
+        });
+    }));
+    tablesCommand.addCommand(new Command("describe")
+        .alias("get")
+        .description("Describe a workspace table and its columns. Add --stats for row count and per-column fill rates (0 credits). Next: `tools search --for-table <table>` lists what these columns can be enriched with and what each costs per row (0 credits).")
+        .argument("<table>", "Table id or slug.")
+        .option("--include-archived", "Include archived columns, and read a table that is archived, scheduled for deletion or being purged.")
+        .option("--stats", "Include stats.rowCount (also summary.rowCount) and per-column fill rates. Row count is exact; above 100 rows fill rates use a 100-row sample (stats.statsSampled). For whole-table fill rates on a bigger list use `tables preview <table> --summary-only` \u2014 exact up to 20,000 rows, 2,000-row sample above. 0 credits.")
+        .option("--column <key>", "Describe just this one column (its kind, definition and whether auto-run includes it) instead of every column.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables describe", options, () => requestOxygen("/api/cli/tables/describe", {
+            method: "POST",
+            body: {
+                table,
+                ...(options.includeArchived ? { include_archived: true } : {}),
+                ...(options.stats ? { include_stats: true } : {}),
+                ...(readOption(options.column) ? { column: readOption(options.column) } : {}),
+            },
+        }));
+    }));
+    tablesCommand.addCommand(new Command("tidy-suggest")
+        .description("Read-only tidy analysis for a workspace table: duplicate columns, formatting issues, hide candidates, and value-sanity findings.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum rows to sample for the analysis. Defaults to and is capped at 5000.")
+        .option("--categories <csv>", "Comma-separated subset of duplicates,formatting,hide,valueSanity. Defaults to all four.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleTablesTidySuggestAction(table, options);
+    }));
+    tablesCommand.addCommand(new Command("activity")
+        .description("Show background runs active on a workspace table right now, with a worker-queue health rollup.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum active runs to return (1-100). Defaults to 20.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables activity", options, () => {
+            const params = new URLSearchParams({ table });
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                params.set("limit", String(limit));
+            return requestOxygen(`/api/cli/tables/activity?${params.toString()}`);
+        });
+    }));
+}

package/dist/command-families/tables/register-relations.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerRelations({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-relations.js

@@ -0,0 +1,244 @@
+import { emitCliFailure, emitSuccess } from "../../cli-output.js";
+import { readPositiveInt } 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";
+import { writeTableLinkPreview } from "./display.js";
+import { normalizePromotePolicy, parsePromoteMapOption } from "./automation.js";
+export function registerRelations({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(new Command("relate")
+        .description("Link two tables (the web's \"Link to another table\"): creates an empty linked-record column on BOTH tables, so links show and can be removed from either side; matching values are not required. `oxygen tables relate contacts --to accounts --live` names them from the tables (account on contacts, contacts on accounts) and re-running it finds the same link. Then use `oxygen tables link` to populate row-to-row edges. Works on any workspace table; plain tables stay plain and are never registered as CRM objects. Defaults to dry-run.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("[slug]", "Relation slug — also the relation column key on the source, such as client. Omit it to name the relation from the target table (or reuse the one relation that already links them).")
+        .option("--to <table>", "Table to link to: id or slug. May also be a CRM object table (companies, people, deals).")
+        .option("--target-table <table>", "Same as --to.")
+        .option("--display-name <name>", "Display name for the relation column. Defaults to the target table's name, or the slug in Title Case when you name the slug.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many (source:target). Default many_to_many. one_to_many means each source row links many target rows and each target row links back to one source.")
+        .option("--inverse-slug <slug>", "Key of the linked-record column on the target table. Defaults to a name from the source table; a standard CRM object target (companies, people, deals) gets no column there.")
+        .option("--inverse-display-name <name>", "Display name for the inverse side.")
+        .option("--dry-run", "Preview the relation plan without writing.")
+        .option("--live", "Apply the relation. Default is dry-run.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, slug, options) => {
+        await handleAsyncAction("tables relate", options, () => {
+            const to = readOption(options.to);
+            const targetTable = readOption(options.targetTable);
+            if (to && targetTable && to !== targetTable) {
+                throw new OxygenError("invalid_request", "--to and --target-table name different tables; pass one.", { exitCode: 1 });
+            }
+            if (!to && !targetTable) {
+                throw new OxygenError("invalid_request", "Name the table to link to with --to <table>.", { exitCode: 1 });
+            }
+            return requestOxygen("/api/cli/tables/relations", {
+                method: "POST",
+                body: {
+                    table,
+                    relationship: {
+                        ...(readOption(slug) ? { slug: readOption(slug) } : {}),
+                        target_table: to ?? targetTable,
+                        ...(options.displayName ? { display_name: options.displayName } : {}),
+                        ...(options.cardinality ? { cardinality: options.cardinality } : {}),
+                        ...(options.inverseSlug ? { inverse_slug: options.inverseSlug } : {}),
+                        ...(options.inverseDisplayName ? { inverse_display_name: options.inverseDisplayName } : {}),
+                    },
+                    mode: options.live ? "live" : "dry_run",
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("relations")
+        .description("Inspect and manage native Tables-owned relation definitions.")
+        .addCommand(new Command("list")
+        .description("List the native relations visible from one table, including cardinality, target, and active link count.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables relations list", options, () => {
+            const params = new URLSearchParams({ table });
+            return requestOxygen(`/api/cli/tables/relations?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Rename either side of a relation or change its cardinality. Endpoints and slugs stay immutable. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--display-name <name>", "New display name on this table.")
+        .option("--inverse-display-name <name>", "New display name on the other table.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many from this table's perspective.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations update", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "PATCH",
+            body: {
+                table,
+                relation,
+                ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
+                ...(readOption(options.inverseDisplayName)
+                    ? { inverse_display_name: readOption(options.inverseDisplayName) }
+                    : {}),
+                ...(readOption(options.cardinality) ? { cardinality: readOption(options.cardinality) } : {}),
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a native relation, its active links, and both relation columns while preserving history. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations archive", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "DELETE",
+            body: {
+                table,
+                relation,
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    })))
+        .addCommand(new Command("unlink")
+        .description("Unlink one exact pair of rows by archiving their relation edge. The relation definition and both rows remain. Previews by default.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("<row_id>", "Source row id.")
+        .requiredOption("--relation <slug>", "Relation slug as seen from the source table.")
+        .requiredOption("--target-row-id <row_id>", "Linked row id to remove.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--live", "Alias for --approved.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables unlink", options, () => requestOxygen("/api/cli/tables/relations/unlink", {
+            method: "POST",
+            body: {
+                table,
+                row_id: rowId,
+                relation: options.relation,
+                target_row_id: options.targetRowId,
+                mode: (options.approved || options.live) && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("link")
+        .description("Link two tables: Oxygen finds the column that joins them, works out the direction, shows you how many rows will match, and on approval links every row. Free. Previews by default; --approved queues a background run and records each row's outcome in a system link_status_<relation> column. Wait for that run with `oxygen table-runs wait <run_id>`. (Also links one row to one row — see --relation.)")
+        .argument("<table>", "Table id or slug to link FROM.")
+        .argument("[row_id]", "Row form only: the source row id to link. Omit for the whole-table form.")
+        .option("--to <table>", "Table id or slug to link TO. May be a CRM object table (companies, people, deals).")
+        .option("--on <column>", "Pin one table's column by name or key. Oxygen must still find a compatible column on the other table: generic text needs a strongly similar label, while domains, emails, LinkedIn URLs, and external IDs pair by semantic role.")
+        .option("--approved", "Queue the bulk link after inspecting the preview; then wait with `oxygen table-runs wait <run_id>`.")
+        .option("--create-missing", "Also create target rows for unmatched source keys (CRM records when filling an existing CRM relationship). Free.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 250; native --create-missing runs serialize target-row creation safely.")
+        .option("--undo <run_id>", "Undo a previous link run, archiving only the links that run created.")
+        .option("--relation <slug>", "Row form: relation slug defined on the source table, such as client.")
+        .option("--target-row-id <row_id>", "Row form: target row id in the related table.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--live", "Row form: apply the single-row link.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        const wholeTableForm = Boolean(readOption(options.to) || readOption(options.undo));
+        const rowForm = Boolean(rowId || readOption(options.relation) || readOption(options.targetRowId));
+        // Usage errors go through emitCliFailure like every other command, NOT a
+        // bare throw: a raw throw escapes commander's action handler as an
+        // uncaught exception, which prints a Node stack trace to stderr instead
+        // of the `{ok:false,error}` envelope every other command emits, and lets
+        // Node's generic exit code override the error's own. This is the first
+        // thing a user sees when they half-remember the command, so it has to be
+        // the standard shape.
+        const usageError = (message) => new OxygenError("invalid_request", message, { exitCode: 1 });
+        // Neither shape is complete: print BOTH rather than guessing which the
+        // user meant. A bare `oxygen tables link people` is far more likely a
+        // half-remembered whole-table command than a malformed row link.
+        if (!wholeTableForm && !rowForm) {
+            emitCliFailure("tables link", usageError([
+                "Say which table to link to, or which two rows to link.",
+                "",
+                `  Link two tables:  oxygen tables link ${table} --to <table>`,
+                `  Link two rows:    oxygen tables link ${table} <row_id> --relation <slug> --target-row-id <id>`,
+            ].join("\n")));
+            return;
+        }
+        if (wholeTableForm && rowForm) {
+            emitCliFailure("tables link", usageError("Use either the whole-table form (--to) or the row form (<row_id> --relation --target-row-id), not both."));
+            return;
+        }
+        if (rowForm) {
+            if (!rowId || !readOption(options.relation) || !readOption(options.targetRowId)) {
+                emitCliFailure("tables link", usageError(`Linking two rows needs all three: oxygen tables link ${table} <row_id> --relation <slug> --target-row-id <id>`));
+                return;
+            }
+            await handleAsyncAction("tables link", options, () => requestOxygen("/api/cli/tables/relations/link", {
+                method: "POST",
+                body: {
+                    table,
+                    row_id: rowId,
+                    relation: options.relation,
+                    target_row_id: options.targetRowId,
+                    // --approved is accepted as an alias for --live so one verb does
+                    // not teach two different confirm words.
+                    mode: options.live || options.approved ? "live" : "dry_run",
+                },
+            }));
+            return;
+        }
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        const undoRunId = readOption(options.undo);
+        const approved = Boolean(options.approved) && !options.dryRun;
+        const result = await requestOxygen("/api/cli/tables/link", {
+            method: "POST",
+            body: {
+                table,
+                ...(undoRunId ? { undo_run_id: undoRunId } : { to: readOption(options.to) }),
+                ...(readOption(options.on) ? { on: readOption(options.on) } : {}),
+                ...(approved ? { approved: true } : { dry_run: true }),
+                ...(options.createMissing ? { create_missing: true } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }).catch((error) => {
+            emitCliFailure("tables link", error);
+            return null;
+        });
+        if (!result)
+            return;
+        if (options.json) {
+            emitSuccess("tables link", result, options);
+            return;
+        }
+        writeTableLinkPreview(table, result, options);
+    }))
+        .addCommand(new Command("promote")
+        .description("Write bound rows' columns onto their matched CRM records (Records<->Tables). Free, but a truth write: previews by default, then re-run with --approved to write. Approved runs queue as a background run — watch with `oxygen table-runs wait <run_id>`.")
+        .argument("<table>", "Table id or slug whose bound rows to promote.")
+        .option("--object <slug>", "CRM object to promote onto (companies, people, deals, ...). Inferred when the table has exactly one bind column.")
+        .requiredOption("--map <pairs>", "Column-to-attribute mapping as column=attribute pairs (e.g. job_title=job_title,seniority=seniority) or a JSON array/object.")
+        .option("--policy <policy>", "Conflict policy: fill-empty-only (default), overwrite, or skip-conflicts.", "fill-empty-only")
+        .option("--row-id <id...>", "Promote only these row ids. Defaults to every bound row.")
+        .option("--dry-run", "Preview per-field would_fill/would_overwrite/conflicts without writing (the default when --approved is absent).")
+        .option("--approved", "Confirm the truth write onto CRM records after inspecting the preview.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        if (options.dryRun && options.approved) {
+            throw new OxygenError("invalid_promote", "Pass either --dry-run or --approved, not both.", { exitCode: 1 });
+        }
+        const mappings = parsePromoteMapOption(options.map);
+        const policy = normalizePromotePolicy(options.policy);
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        await handleAsyncAction("tables promote", options, () => requestOxygen("/api/cli/tables/promote", {
+            method: "POST",
+            body: {
+                table,
+                ...(readOption(options.object) ? { object: readOption(options.object) } : {}),
+                mappings,
+                policy,
+                ...(options.rowId && options.rowId.length > 0 ? { row_ids: options.rowId } : {}),
+                // Preview by default; --approved is the only path that writes.
+                ...(options.approved ? { approved: true } : { dry_run: true }),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }));
+    }));
+}

package/dist/command-families/tables/register-row-actions.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerRowActions({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;

package/dist/command-families/tables/register-row-actions.js

@@ -0,0 +1,53 @@
+import { emitCliFailure, emitSuccess } from "../../cli-output.js";
+import { collectRepeatable } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { Command } from "commander";
+import { buildDedupeRequest } from "./automation.js";
+import { buildTablesSendRequest, writeTablesSendHint } from "./send.js";
+export function registerRowActions({ tablesCommand, handleAsyncAction }) {
+    tablesCommand.addCommand(new Command("dedupe")
+        .description("Collapse duplicate rows by normalized (email/domain/linkedin) or fuzzy-label keys, or cross-check a column against another table. Previews by default; --apply --approved deletes losers (kept in row history).")
+        .argument("<table>", "Table id or slug to dedupe.")
+        .requiredOption("--on <cols>", "Key column(s): one column, or two comma-separated for a composite key (e.g. email or first_name,company).")
+        .option("--normalize <mode>", "Match mode: exact (default), email, domain, linkedin, or fuzzy-label. Fuzzy allowed only as a single key.", "exact")
+        .option("--keep <policy>", "Survivor per duplicate group: oldest (default), newest, or most-complete.", "oldest")
+        .option("--merge-values <mode>", "With --apply, fill the survivor's blank cells from the losers first: fill-empty.")
+        .option("--scan-limit <n>", "Max rows to scan. Defaults to 50000, capped at 200000.")
+        .option("--apply", "Delete the duplicate rows (losers). Without this flag the command only previews.")
+        .option("--approved", "Confirm the deletion (required with --apply); without it the API returns the preview to inspect first.")
+        .option("--against <table>", "Cross-table check: report rows whose --on value already exists in this other table (read-only).")
+        .option("--against-column <col>", "Column in the --against table to match against. Required with --against.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables dedupe", options, () => {
+            const request = buildDedupeRequest(table, options);
+            return requestOxygen(request.endpoint, { method: "POST", body: request.body });
+        });
+    }));
+    tablesCommand.addCommand(new Command("send")
+        .description("Copy rows from one table into another as a durable background run (free, resumable). Map columns with --map (or --automap), optionally flatten an array column into one row per element, and insert or upsert. --dry-run previews the resolved mapping, row estimate, and sample rows without writing.")
+        .argument("<source>", "Source table id or slug.")
+        .argument("<target>", "Target table id or slug (must be a different table).")
+        .option("--map <pairs>", "target=source column pairs, comma-separated and/or repeated (e.g. --map company=company_name,website=domain).", collectRepeatable, [])
+        .option("--mapping <json>", 'Full mapping JSON array for literals and dot-paths, e.g. [{"target":"email","source":{"type":"column","key":"$element"},"path":"email"}]. Escape hatch when --map is not enough.')
+        .option("--automap", "Match columns automatically (exact key, then case-insensitive label). The resolved mapping is echoed back.")
+        .option("--flatten <column>", 'Source column whose array value emits one target row per element (the element is mapping source key "$element"); non-array values pass through as one row.')
+        .option("--flatten-path <path>", "Dot-path to the array inside the --flatten column's value.")
+        .option("--filter <json>", 'Source-row filters JSON, e.g. [{"column":"domain","op":"is_not_null"}]. Ops: eq, neq, is_null, is_not_null, in, not_in.')
+        .option("--mode <mode>", "insert (append, default) or upsert (requires --upsert-key).", "insert")
+        .option("--upsert-key <key>", "Mapped target column that identifies existing rows for upsert.")
+        .option("--page-size <n>", "Rows copied per durable page. Defaults to 500, max 2000.")
+        .option("--dry-run", "Validate and preview only; nothing is written.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (source, target, options) => {
+        try {
+            const body = buildTablesSendRequest(source, target, options);
+            const data = await requestOxygen("/api/cli/tables/send", { method: "POST", body });
+            emitSuccess("tables send", data, options);
+            writeTablesSendHint(data);
+        }
+        catch (error) {
+            emitCliFailure("tables send", error);
+        }
+    }));
+}

package/dist/command-families/tables/register-row-writes.d.ts

@@ -0,0 +1,2 @@
+import type { TablesRegistrationContext } from "./registration-context.js";
+export declare function registerRowWrites({ tablesCommand, handleAsyncAction }: TablesRegistrationContext): void;