@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/bundle-import.js

@@ -0,0 +1,260 @@
+import { readRecordString } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { resolve } from "node:path";
+import { SAFE_IMPORT_WRITE_BATCH_SIZE, normalizeImportBatchSize, tableWebUrl } from "./import-values.js";
+import { openTableBundle, readBundleBatches } from "./bundle-format.js";
+import { writeImportBatchWithAutoSplit } from "./import-batches.js";
+export async function importTableBundle(// skipcq: JS-R1005
+options, binaryName) {
+    const path = options.file;
+    if (!path || !path.trim()) {
+        throw new OxygenError("invalid_input", "--file is required.", { exitCode: 1 });
+    }
+    const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
+    const bundle = await openTableBundle(resolve(path));
+    // A native `relation` column is only half of a relation: the other half is a
+    // row in ox_tables.relation_definitions that ONLY `tables relate` writes. A
+    // bundle carries the column but not the definition, and its `target_table` is
+    // the SOURCE workspace's table id, which does not exist here. Importing it
+    // produced a column that pointed at a foreign workspace and that no surface
+    // could repair, rename, archive or delete — every column lifecycle command
+    // refuses a relation-shaped column, and the relation commands refuse a
+    // definition that was never written (OXY-4360). Skip them and say so;
+    // `tables relate` rebuilds a real relation on this side once both tables
+    // exist. Keyed on the NATIVE shape, not `kind === "relation"`: CRM
+    // relationship columns (`target_object`, no `storage`) are a different
+    // mechanism with their own lifecycle and must still import.
+    const isNativeRelationColumn = (column) => column.kind === "relation"
+        && (column.definition?.storage === "tables"
+            || typeof column.definition?.archived_relation_definition_id === "string");
+    const bundleColumns = bundle.columns.map(bundleColumnToCreateInput);
+    const skippedRelationColumns = bundleColumns
+        .filter(isNativeRelationColumn)
+        .map((column) => column.key ?? column.label);
+    const columns = bundleColumns.filter((column) => !isNativeRelationColumn(column));
+    if (bundleColumns.length === 0) {
+        throw new OxygenError("invalid_bundle", "Bundle has no columns; nothing to import.", { exitCode: 1 });
+    }
+    if (columns.length === 0) {
+        throw new OxygenError("invalid_bundle", "Bundle contains only native relation columns, which cannot be imported directly. Import the tables they point at, then run `tables relate`.", { details: { skipped_relation_columns: skippedRelationColumns }, exitCode: 1 });
+    }
+    const validColumnKeys = new Set(columns.map((column) => column.key).filter((key) => Boolean(key)));
+    const into = readOption(options.into);
+    const upsertKey = readOption(options.key);
+    // Resuming/appending into an existing table without an upsert key would
+    // duplicate every already-imported row. Require --key so the resume matches
+    // rows instead of re-inserting them.
+    if (into && !upsertKey) {
+        throw new OxygenError("invalid_input", "--into requires --key so rows already imported are matched instead of duplicated. Pass --key <uniqueColumn>.", { details: { into }, exitCode: 1 });
+    }
+    if (upsertKey) {
+        if (upsertKey.startsWith("_")) {
+            throw new OxygenError("invalid_input", "--key must be a workspace column key, not an internal field.", { details: { key: upsertKey }, exitCode: 1 });
+        }
+        if (validColumnKeys.size > 0 && !validColumnKeys.has(upsertKey)) {
+            throw new OxygenError("invalid_input", `--key ${upsertKey} is not a column in this bundle.`, { details: { key: upsertKey, available_keys: [...validColumnKeys] }, exitCode: 1 });
+        }
+    }
+    // Resolve the target table: resume into an existing one (--into), or create a
+    // fresh one from the bundle schema.
+    let newTableId;
+    let newTableSlug;
+    let createdTable;
+    if (into) {
+        const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table: into } });
+        const tableMeta = describe.table ?? null;
+        const resolvedId = tableMeta ? readRecordString(tableMeta, "id") : null;
+        if (!resolvedId) {
+            throw new OxygenError("table_not_found", `--into table ${into} was not found in this org.`, { details: { into }, exitCode: 1 });
+        }
+        newTableId = resolvedId;
+        newTableSlug = tableMeta ? readRecordString(tableMeta, "slug") ?? null : null;
+        createdTable = false;
+    }
+    else {
+        const tableName = readOption(options.name) ?? bundle.tableName;
+        if (!tableName) {
+            throw new OxygenError("invalid_bundle", "Bundle has no table.name and no --name override was provided.", { exitCode: 1 });
+        }
+        const createResponse = await requestOxygen("/api/cli/tables", {
+            method: "POST",
+            body: {
+                name: tableName,
+                columns,
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+            },
+        });
+        const created = readRecord(createResponse, "table");
+        const createdId = readRecordString(createResponse, "table_id")
+            ?? (created ? readRecordString(created, "id") : null);
+        if (!createdId) {
+            throw new OxygenError("invalid_response", "Table create response did not include an id; bundle import cannot proceed.", { exitCode: 1 });
+        }
+        newTableId = createdId;
+        newTableSlug = readRecordString(createResponse, "table_slug")
+            ?? (created ? readRecordString(created, "slug") : null);
+        createdTable = true;
+    }
+    // In upsert mode every row must carry the key value; otherwise the upsert
+    // route rejects the whole batch midway. A single-document bundle has every
+    // row in memory, so it is checked before anything is written and never
+    // leaves a half-imported table behind for a predictable data problem. A
+    // streamed bundle is checked row by row as it is read; a miss stops the
+    // import with the row number, and --key makes the rerun idempotent.
+    if (upsertKey && bundle.preloadedRows) {
+        const missingIndex = bundle.preloadedRows.findIndex((row) => row[upsertKey] === undefined || row[upsertKey] === null);
+        if (missingIndex >= 0) {
+            throw new OxygenError("invalid_bundle", `Row ${missingIndex + 1} is missing a value for the upsert key "${upsertKey}".`, { details: { key: upsertKey, row_number: missingIndex + 1 }, exitCode: 1 });
+        }
+    }
+    const resumeCommand = buildBundleResumeCommand({
+        file: path,
+        tableId: newTableId,
+        key: upsertKey ?? null,
+        batchSize: effectiveBatchSize,
+        binaryName,
+    });
+    let processed = 0;
+    let insertedCount = 0;
+    let updatedCount = 0;
+    const batches = readBundleBatches({
+        bundle,
+        validColumnKeys,
+        upsertKey: upsertKey ?? null,
+        batchSize: effectiveBatchSize,
+        tableId: newTableId,
+        resumeCommand,
+    });
+    for await (const batch of batches) {
+        try {
+            // Same byte-aware writer as `tables import`: a wide batch pre-splits (and a
+            // server 413 halves) instead of dead-ending the bundle at an unchanged
+            // resume batch size. No request_id — bundle resumes match on --key.
+            const result = await writeImportBatchWithAutoSplit({
+                tableRef: newTableId,
+                upsertKey: upsertKey ?? undefined,
+                rows: batch,
+            });
+            if (upsertKey) {
+                insertedCount += result.insertedCount;
+                updatedCount += result.updatedCount;
+            }
+            else {
+                insertedCount += batch.length;
+            }
+            processed += batch.length;
+        }
+        catch (error) {
+            // A mid-loop failure used to leave a partial table with no way forward.
+            // Surface exactly where it stopped and how to resume so the import is
+            // recoverable instead of a silent half-write.
+            const cause = error instanceof OxygenError
+                ? error.code
+                : error instanceof Error
+                    ? error.message
+                    : "unknown";
+            const recovery = upsertKey
+                ? `Re-run with --into ${newTableId} --key ${upsertKey} to resume — already-imported rows are matched by "${upsertKey}", not duplicated.`
+                : `Resume with: ${resumeCommand}`;
+            throw new OxygenError("bundle_import_incomplete", `Bundle import stopped after ${processed}/${bundle.rowCount} rows. ${recovery}`, {
+                details: {
+                    table_id: newTableId,
+                    table_slug: newTableSlug,
+                    rows_total: bundle.rowCount,
+                    rows_processed: processed,
+                    failed_batch_offset: processed,
+                    failed_batch_size: batch.length,
+                    mode: upsertKey ? "upsert" : "insert",
+                    ...(upsertKey ? { key: upsertKey } : {}),
+                    resume_command: resumeCommand,
+                    web_url: tableWebUrl(newTableSlug ?? newTableId),
+                    cause,
+                },
+                exitCode: 1,
+            });
+        }
+    }
+    return {
+        table_id: newTableId,
+        table_slug: newTableSlug ?? null,
+        created_table: createdTable,
+        column_count: columns.length,
+        row_count: processed,
+        mode: upsertKey ? "upsert" : "insert",
+        ...(skippedRelationColumns.length > 0
+            ? {
+                skipped_relation_columns: skippedRelationColumns,
+                note: `${skippedRelationColumns.length} native relation column(s) were not imported: a relation must be created on this side with \`tables relate\` once both tables exist.`,
+            }
+            : {}),
+        ...(upsertKey
+            ? { upsert_key: upsertKey, inserted_count: insertedCount, updated_count: updatedCount }
+            : {}),
+        source_table: bundle.tableSummary,
+        schema_version: bundle.schemaVersion,
+        web_url: tableWebUrl(newTableSlug ?? newTableId),
+    };
+}
+// Builds the exact CLI command that resumes a failed `import-bundle` into the
+// table it already created. Always targets that table with --into + --key so the
+// resume is idempotent; falls back to a <uniqueColumn> placeholder when the
+// original run had no key (insert mode can't be safely auto-resumed).
+export function buildBundleResumeCommand(input) {
+    const fileArg = /\s/.test(input.file) ? `"${input.file}"` : input.file;
+    const parts = [
+        // Must be the binary the user actually invoked. Hardcoding "oxygen" meant an
+        // `oxygen-dev` import printed a resume command that, pasted verbatim, re-ran
+        // a DEV bundle against PRODUCTION (OXY-4360).
+        `${input.binaryName} tables import-bundle`,
+        `--file ${fileArg}`,
+        `--into ${input.tableId}`,
+        `--key ${input.key ?? "<uniqueColumn>"}`,
+    ];
+    // 500 is the default in normalizeImportBatchSize; only echo --batch-size when
+    // the user picked something else, to keep the resume command minimal.
+    if (input.batchSize !== 500) {
+        parts.push(`--batch-size ${input.batchSize}`);
+    }
+    return parts.join(" ");
+}
+export function toBundleColumn(column) {
+    // Persist only the fields `tables create` knows how to ingest. Drop ids,
+    // physical column names, archivedAt — those are tenant-local and would
+    // collide on import.
+    return {
+        key: column.key,
+        ...(column.label !== undefined ? { label: column.label } : {}),
+        ...(column.dataType !== undefined ? { dataType: column.dataType } : {}),
+        ...(column.kind !== undefined ? { kind: column.kind } : {}),
+        ...(column.semanticType !== undefined ? { semanticType: column.semanticType } : {}),
+        ...(column.definition !== undefined ? { definition: column.definition } : {}),
+        ...(column.position !== undefined ? { position: column.position } : {}),
+    };
+}
+export function bundleColumnToCreateInput(column) {
+    const label = typeof column.label === "string" && column.label.trim()
+        ? column.label.trim()
+        : typeof column.key === "string"
+            ? column.key
+            : null;
+    if (!label) {
+        throw new OxygenError("invalid_bundle", "Bundle column is missing label/key.", {
+            details: { column },
+            exitCode: 1,
+        });
+    }
+    return {
+        label,
+        ...(typeof column.key === "string" ? { key: column.key } : {}),
+        ...(typeof column.dataType === "string" ? { dataType: column.dataType } : {}),
+        ...(typeof column.kind === "string" ? { kind: column.kind } : {}),
+        ...(typeof column.semanticType === "string" ? { semanticType: column.semanticType } : {}),
+        ...(column.definition && typeof column.definition === "object" && !Array.isArray(column.definition)
+            ? { definition: column.definition }
+            : {}),
+    };
+}

package/dist/command-families/tables/display.d.ts

@@ -0,0 +1,107 @@
+import { ansi } from "../../command-support.js";
+import { TablesLinkOptions, TablesTidySuggestOptions } from "./options.js";
+export type TableLinkCandidateResponse = {
+    matchExplanation?: string;
+    coverage?: number;
+    matchedRows?: number;
+    ambiguousRows?: number;
+    unmatchedRows?: number;
+    source?: {
+        columnLabel?: string;
+    };
+    target?: {
+        columnLabel?: string;
+    };
+    samplePairs?: Array<{
+        key?: string;
+    }>;
+};
+export type TableLinkResponse = {
+    dry_run?: boolean;
+    cardinalitySentence?: string;
+    chosen?: TableLinkCandidateResponse | null;
+    alternatives?: TableLinkCandidateResponse[];
+    sampled?: boolean;
+    source?: {
+        tableLabel?: string;
+        rowCount?: number;
+        scannedRows?: number;
+    };
+    target?: {
+        tableLabel?: string;
+        rowCount?: number;
+    };
+    relationStorage?: "tables" | "crm_legacy";
+    registersEntity?: boolean;
+    requiresDefinition?: boolean;
+    existingRelationshipSlug?: string | null;
+    blockers?: Array<{
+        code?: string;
+        message?: string;
+    }>;
+    next_action?: string;
+    web_url?: string;
+    action_run_id?: string;
+    workspace_run_id?: string;
+    archived_edge_count?: number;
+    edges_to_archive?: number;
+};
+export declare function linkBar(coverage: number, width?: number): string;
+export declare function writeTableLinkPreview(table: string, data: TableLinkResponse, options: TablesLinkOptions): void;
+export type TidyDuplicateSuggestion = {
+    survivorColumnId?: string;
+    survivorKey?: string;
+    loserColumnId?: string;
+    loserKey?: string;
+    similarity?: number;
+    dataType?: string;
+    sampledOverlap?: number;
+    loserHasUniqueValues?: boolean;
+    recommendation?: string;
+};
+export type TidyFormattingIssue = {
+    columnId?: string;
+    columnKey?: string;
+    issue?: string;
+    sampleRowIds?: string[];
+    detail?: string;
+};
+export type TidyHideSuggestion = {
+    columnId?: string;
+    columnKey?: string;
+    reason?: string;
+    fillRate?: number;
+    suggestedPosition?: number | null;
+};
+export type TidyValueSanityIssue = {
+    columnId?: string;
+    columnKey?: string;
+    rowId?: string;
+    value?: unknown;
+    reason?: string;
+};
+export type TidyNotComputedColumn = {
+    columnId?: string;
+    columnKey?: string;
+    reason?: string;
+    message?: string;
+};
+export type TidySuggestResponse = {
+    tableId?: string;
+    sampledRows?: number;
+    rowCount?: number;
+    duplicateColumns?: TidyDuplicateSuggestion[];
+    formattingIssues?: TidyFormattingIssue[];
+    hideSuggestions?: TidyHideSuggestion[];
+    valueSanity?: TidyValueSanityIssue[];
+    notComputed?: TidyNotComputedColumn[];
+    url?: string;
+    web_url?: string;
+    deepLink?: string;
+};
+export declare function handleTablesTidySuggestAction(table: string, options: TablesTidySuggestOptions): Promise<void>;
+export declare function formatTidyCount(value: unknown): string;
+export declare function formatTidyPercent(value: unknown): string;
+export declare function pushTidySection<T>(lines: string[], styles: ReturnType<typeof ansi>, title: string, items: T[], renderItem: (item: T) => string): void;
+export declare function formatTidySuggestions(data: TidySuggestResponse): string;
+export declare function writeRowDeleteWarnings(data: unknown): void;

package/dist/command-families/tables/display.js

@@ -0,0 +1,229 @@
+import { writeJson, emitCliFailure, asPayloadRecord } from "../../cli-output.js";
+import { readPositiveInt } from "../../cli-values.js";
+import { readCsvOption, ansi } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { success } from "@oxygen/shared/cli-result";
+import { stdout as output } from "node:process";
+export function linkBar(coverage, width = 36) {
+    const filled = Math.max(0, Math.min(width, Math.round(coverage * width)));
+    return `[${"#".repeat(filled)}${"-".repeat(width - filled)}]`;
+}
+export function writeTableLinkPreview(table, data, options) {
+    const out = (line = "") => process.stdout.write(`${line}\n`);
+    // Undo has no plan to render — just the count and what it touched.
+    if (typeof data.edges_to_archive === "number" || typeof data.archived_edge_count === "number") {
+        if (typeof data.archived_edge_count === "number") {
+            out(`Undone — ${data.archived_edge_count.toLocaleString()} links archived.`);
+            out("Links are archived, not deleted, and only the ones that run created were touched.");
+        }
+        else {
+            out(`This will archive ${(data.edges_to_archive ?? 0).toLocaleString()} links created by that run.`);
+            out(`Apply:  oxygen tables link ${table} --undo ${readOption(options.undo) ?? "<run_id>"} --approved`);
+        }
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    const blockers = data.blockers ?? [];
+    if (blockers.length > 0) {
+        for (const blocker of blockers)
+            out(blocker.message ?? blocker.code ?? "This link cannot run yet.");
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    // Approved run: it is queued, so print how to watch it, not the plan again.
+    // The two follow-ups take DIFFERENT ids and that is not cosmetic — undo
+    // archives by edge run_id, which is the parent workspace run.
+    const watchId = data.action_run_id ?? data.workspace_run_id;
+    const undoId = data.workspace_run_id;
+    if (!data.dry_run && watchId) {
+        out(`Linking rows in the background.`);
+        if (data.web_url)
+            out(`Run:    ${data.web_url}`);
+        out(`Watch:  oxygen table-runs wait ${watchId}`);
+        if (undoId)
+            out(`Undo:   oxygen tables link ${table} --undo ${undoId}`);
+        return;
+    }
+    const chosen = data.chosen ?? null;
+    const sourceLabel = data.source?.tableLabel ?? table;
+    const targetLabel = data.target?.tableLabel ?? readOption(options.to) ?? "the other table";
+    out(`Linking "${sourceLabel}" -> "${targetLabel}"`);
+    out();
+    if (!chosen) {
+        out("  No column in these two tables matches well enough to link them.");
+        out("  Add a shared value to both — a website, a domain, a LinkedIn URL, or an email.");
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    const pad = (label) => label.padEnd(14);
+    out(`  ${pad("Matching on")}${chosen.source?.columnLabel ?? "?"} -> ${chosen.target?.columnLabel ?? "?"}`);
+    if (chosen.matchExplanation)
+        out(`  ${pad("")}(${chosen.matchExplanation})`);
+    if (data.cardinalitySentence)
+        out(`  ${pad("Direction")}${data.cardinalitySentence}`);
+    const scanned = data.source?.scannedRows ?? 0;
+    const total = data.source?.rowCount ?? scanned;
+    // Always name the sample. `sampled` means the scan hit its bound, so these are
+    // estimates over a prefix of the table, not the whole thing.
+    if (data.sampled && scanned < total) {
+        out(`  ${pad("Measured on")}${scanned.toLocaleString()} of ${total.toLocaleString()} rows`);
+    }
+    else {
+        out(`  ${pad("Measured on")}all ${total.toLocaleString()} rows`);
+    }
+    out();
+    const coverage = chosen.coverage ?? 0;
+    out(`  ${linkBar(coverage)}  ${(chosen.matchedRows ?? 0).toLocaleString()} will link   ${Math.round(coverage * 100)}%`);
+    if ((chosen.ambiguousRows ?? 0) > 0) {
+        out(`  ${" ".repeat(38)}${(chosen.ambiguousRows ?? 0).toLocaleString()} ambiguous (skipped)`);
+    }
+    if ((chosen.unmatchedRows ?? 0) > 0) {
+        out(`  ${" ".repeat(38)}${(chosen.unmatchedRows ?? 0).toLocaleString()} with no match yet`);
+    }
+    out();
+    const samples = chosen.samplePairs ?? [];
+    if (samples.length > 0) {
+        for (const sample of samples.slice(0, 3))
+            out(`  matched on "${sample.key ?? ""}"`);
+        if (samples.length > 3)
+            out(`  ... ${samples.length - 3} more`);
+        out();
+    }
+    if ((chosen.ambiguousRows ?? 0) > 0) {
+        out(`  Ambiguous rows match more than one row on the other side, so they are left`);
+        out(`  unlinked rather than guessed. Fix the duplicates first:`);
+        out(`      oxygen tables dedupe ${targetLabel} --on <column>`);
+        out();
+    }
+    if ((chosen.unmatchedRows ?? 0) > 0 && !options.createMissing) {
+        out(`  Add --create-missing to create the missing target rows too (free).`);
+        out();
+    }
+    const alternatives = data.alternatives ?? [];
+    if (alternatives.length > 0) {
+        const best = alternatives[0];
+        if (best?.source?.columnLabel) {
+            out(`  Also measured: ${best.source.columnLabel} -> ${best.target?.columnLabel ?? "?"}  ${Math.round((best.coverage ?? 0) * 100)}%`);
+            out(`      retry with --on "${best.source.columnLabel}"`);
+            out();
+        }
+    }
+    if (data.relationStorage === "tables") {
+        out(`  Stored in Tables — neither table is registered as a CRM object.`);
+        out();
+    }
+    out("  Free — 0 credits. Nothing has been written.");
+    const applyFlags = [`--to ${readOption(options.to) ?? "<table>"}`];
+    if (readOption(options.on))
+        applyFlags.push(`--on "${readOption(options.on)}"`);
+    if (options.createMissing)
+        applyFlags.push("--create-missing");
+    out(`  Apply:  oxygen tables link ${table} ${applyFlags.join(" ")} --approved`);
+    if (data.web_url)
+        out(`  ${data.web_url}`);
+}
+// `tables tidy-suggest` is a read-only analysis (no credits, no writes): it
+// surfaces duplicate columns, formatting inconsistencies, hide candidates, and
+// value-sanity findings so the caller can pick which reversible cleanup to run
+// next. --json returns the raw report envelope; the default rendering compacts
+// the four sections for a terminal reader and echoes the deep-link.
+export async function handleTablesTidySuggestAction(table, options) {
+    try {
+        const limit = readPositiveInt(options.limit);
+        const categories = readCsvOption(options.categories);
+        const data = await requestOxygen("/api/cli/tables/tidy/suggest", {
+            method: "POST",
+            body: {
+                table,
+                ...(limit ? { limit } : {}),
+                ...(categories.length ? { categories } : {}),
+            },
+        });
+        if (options.json) {
+            writeJson(success("tables tidy-suggest", data));
+            return;
+        }
+        process.stdout.write(formatTidySuggestions(data));
+    }
+    catch (error) {
+        emitCliFailure("tables tidy-suggest", error);
+    }
+}
+export function formatTidyCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : "0";
+}
+export function formatTidyPercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "—";
+    return `${(value * 100).toFixed(0)}%`;
+}
+// Render one tidy-suggest section (header + count, then either a dim "None" or
+// one formatted line per item) into the shared `lines` buffer. Extracted so the
+// four sections share a single control-flow shape instead of repeating it.
+export function pushTidySection(lines, styles, title, items, renderItem) {
+    lines.push("", styles.bold(`${title} (${items.length})`));
+    if (items.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+        return;
+    }
+    for (const item of items) {
+        lines.push(renderItem(item));
+    }
+}
+export function formatTidySuggestions(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const duplicates = Array.isArray(data.duplicateColumns) ? data.duplicateColumns : [];
+    const formatting = Array.isArray(data.formattingIssues) ? data.formattingIssues : [];
+    const hide = Array.isArray(data.hideSuggestions) ? data.hideSuggestions : [];
+    const valueSanity = Array.isArray(data.valueSanity) ? data.valueSanity : [];
+    const notComputed = Array.isArray(data.notComputed) ? data.notComputed : [];
+    const lines = [
+        "",
+        `${styles.bold("Table tidy suggestions")} ${styles.dim(`(sampled ${formatTidyCount(data.sampledRows)} of ${formatTidyCount(data.rowCount)} rows)`)}`,
+    ];
+    pushTidySection(lines, styles, "Duplicate columns", duplicates, (dup) => {
+        const loser = dup.loserKey ?? dup.loserColumnId ?? "?";
+        const survivor = dup.survivorKey ?? dup.survivorColumnId ?? "?";
+        return `  ${loser} ${styles.dim("→ duplicate of")} ${survivor} ${styles.dim(`(${formatTidyPercent(dup.similarity)} match, ${dup.recommendation ?? "review"})`)}`;
+    });
+    pushTidySection(lines, styles, "Formatting issues", formatting, (issue) => {
+        const sampleCount = Array.isArray(issue.sampleRowIds) ? issue.sampleRowIds.length : 0;
+        const column = issue.columnKey ?? issue.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${issue.issue ?? "issue"}`)}${issue.detail ? `: ${issue.detail}` : ""} ${styles.dim(`(${sampleCount} sample row(s))`)}`;
+    });
+    pushTidySection(lines, styles, "Hide suggestions", hide, (suggestion) => {
+        const column = suggestion.columnKey ?? suggestion.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${suggestion.reason ?? "hide"} (${formatTidyPercent(suggestion.fillRate)} filled)`)}`;
+    });
+    pushTidySection(lines, styles, "Value-sanity findings", valueSanity, (finding) => {
+        const column = finding.columnKey ?? finding.columnId ?? "?";
+        return `  ${column} ${styles.dim(`row ${finding.rowId ?? "?"} — ${finding.reason ?? "check value"}`)}`;
+    });
+    // Printed even when empty, like the four finding sections: a reader who never
+    // sees this heading cannot tell a measured column from an unmeasured one.
+    pushTidySection(lines, styles, "Not measured", notComputed, (entry) => {
+        const column = entry.columnKey ?? entry.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${entry.message ?? entry.reason ?? "could not be measured"}`)}`;
+    });
+    const link = data.deepLink ?? data.web_url ?? data.url;
+    if (link) {
+        lines.push("", styles.dim(`View table: ${link}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// `tables delete-row|delete-rows` for a human reader: a deleted row's lead stays
+// enrolled in its campaigns, so name them where the delete was typed.
+export function writeRowDeleteWarnings(data) {
+    const payload = asPayloadRecord(data);
+    const warnings = Array.isArray(payload?.warnings) ? payload.warnings : [];
+    for (const entry of warnings) {
+        const warning = asPayloadRecord(entry);
+        if (warning && typeof warning.message === "string")
+            process.stderr.write(`Warning: ${warning.message}\n`);
+    }
+}

package/dist/command-families/tables/import-batches.d.ts

@@ -0,0 +1,26 @@
+export type ImportBatchWriteSummary = {
+    rowCount: number;
+    insertedCount: number;
+    updatedCount: number;
+    warningCount: number;
+    warnings: unknown[];
+    warningsTruncated: boolean;
+    writeRequestCount: number;
+    requestTooLargeRetries: number;
+    byteSplits: number;
+    minimumBatchSizeUsed: number;
+    lastResult: Record<string, unknown> | null;
+};
+export declare function writeImportBatchWithAutoSplit(input: {
+    tableRef: string;
+    upsertKey: string | undefined;
+    rows: Record<string, unknown>[];
+    requestId?: string;
+}): Promise<ImportBatchWriteSummary>;
+export declare function writeImportBatchHalves(input: Parameters<typeof writeImportBatchWithAutoSplit>[0], midpoint: number): Promise<[ImportBatchWriteSummary, ImportBatchWriteSummary]>;
+export declare function summarizeImportBatchWrite(result: Record<string, unknown>, batchSize: number): ImportBatchWriteSummary;
+export declare function combineImportBatchWriteSummaries(first: ImportBatchWriteSummary, second: ImportBatchWriteSummary, extra: {
+    requestTooLargeRetries?: number;
+    byteSplits?: number;
+}): ImportBatchWriteSummary;
+export declare function isRequestTooLargeError(error: unknown): boolean;