@batadata/cli 0.1.13 → 0.1.14

package/dist/commands/powdb.d.ts

@@ -0,0 +1,173 @@
+/**
+ * `bata powdb pull` — Stage A of the PowDB lane (see
+ * docs/strategy/2026-07-04-production-readiness-and-powdb.md §5 feature #1 and
+ * docs/powdb.md). It pulls a BataDB branch's schema + data into a single,
+ * local, PowDB-loadable **PowQL script** so an agent can bootstrap a real copy
+ * of the database inside its own process — no network round-trips at query time.
+ *
+ * COMPAT-HONEST by construction. PowDB's Stage-A surface is narrower than
+ * Postgres, so instead of silently dropping what it can't represent, every
+ * unrepresentable / lossy column and constraint is reported per-object (in the
+ * human summary, the `--json` payload, AND as `# WARN:` comments in the
+ * artifact). No claim is made that PowDB is Postgres-compatible beyond the
+ * mapping below, and nothing here compares engine speed.
+ *
+ * The artifact is PowQL (not SQL) because the shipped `powdb-cli --exec` path
+ * executes PowQL; the SQL frontend is not wired into the CLI one-shot loader.
+ * See the upstream issues filed against the PowDB repo for the engine-side
+ * loader work Stage A wants next (statement-aware file import, uuid/bytes
+ * literals, a bootstrap contract for the embedded-addon sandbox).
+ */
+interface ColumnInfo {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    defaultValue: string | null;
+    isPrimaryKey: boolean;
+}
+interface ConstraintInfo {
+    name: string;
+    type: string;
+    columns: string[];
+    foreignTableSchema: string | null;
+    foreignTableName: string | null;
+    foreignColumnName: string | null;
+}
+interface IndexInfo {
+    name: string;
+    definition: string;
+}
+interface TableSchema {
+    schema: string;
+    name: string;
+    columns: ColumnInfo[];
+    indexes: IndexInfo[];
+    constraints: ConstraintInfo[];
+}
+/** The Stage-A PowDB types a static PowQL artifact can carry. */
+export type PowType = "int" | "float" | "str" | "bool" | "datetime";
+export interface TypeMapping {
+    /** null → PowDB has no Stage-A representation; the column is DROPPED. */
+    powType: PowType | null;
+    /** Honesty note, present whenever the mapping is lossy or the column drops. */
+    note?: string;
+}
+/**
+ * Map a Postgres data type (as reported by schema introspection) to the PowDB
+ * Stage-A type that best represents it — or `null` when PowDB has no honest
+ * Stage-A representation and the column must be dropped. Every non-faithful
+ * mapping carries a `note` so the caller can surface it per-object.
+ */
+export declare function mapPgType(dataType: string): TypeMapping;
+/**
+ * Sanitize a Postgres identifier into a valid PowQL identifier (leading
+ * alpha/underscore, then alphanumeric/underscore). Reports whether it had to be
+ * changed and whether it collides with a PowQL keyword, so the caller can flag
+ * the rename honestly rather than emit a name that means something else.
+ */
+export declare function powqlIdentifier(name: string): {
+    ident: string;
+    changed: boolean;
+    keyword: boolean;
+};
+/**
+ * Escape a string for a PowQL double-quoted literal. The engine lexer honors
+ * `\" \\ \n \t`; every other character passes through verbatim. Returns the
+ * inner content (no surrounding quotes).
+ */
+export declare function escapePowqlString(s: string): string;
+/** A raw string value that would break `powdb-cli --exec`'s naive `;`-split. */
+export declare function isLoadRiskyString(s: string): boolean;
+export type LiteralResult = {
+    literal: string;
+    risky: boolean;
+} | {
+    skip: true;
+    reason: string;
+};
+/**
+ * Render a JS value (as returned by SQL-over-HTTP, i.e. parsed JSON) as a PowQL
+ * literal of the given PowDB type. Returns `{ skip }` when the value cannot be
+ * represented (the field is then omitted from the insert, becoming null). Marks
+ * `risky` when the produced string literal contains a `;` or newline — data
+ * that the shipped `--exec` loader's `;`-split would corrupt (see upstream
+ * issue for a statement-aware loader).
+ */
+export declare function powqlLiteral(value: unknown, powType: PowType): LiteralResult;
+export type PgDefault = {
+    kind: "auto";
+} | {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "drop";
+    note: string;
+} | null;
+/**
+ * Interpret a Postgres column default for a given PowDB type. Only scalar
+ * literals map to a PowQL `default`; `nextval(...)` on an int maps to `auto`;
+ * expression defaults (now(), gen_random_uuid(), …) are dropped with a note so
+ * the omission is visible rather than silent.
+ */
+export declare function parsePgDefault(defaultValue: string | null, powType: PowType): PgDefault;
+export interface ColumnPlan {
+    pgName: string;
+    powName: string;
+    powType: PowType;
+    required: boolean;
+    unique: boolean;
+    auto: boolean;
+    defaultLiteral: string | null;
+}
+export interface TablePlan {
+    pgQualified: string;
+    pgSchema: string;
+    pgName: string;
+    powName: string;
+    columns: ColumnPlan[];
+    warnings: string[];
+}
+/**
+ * Build the per-table PowQL `type` plan from a Postgres table's schema,
+ * accumulating an honesty note for every column/constraint that can't be
+ * carried faithfully. Pure — no I/O — so the mapping is unit-tested directly.
+ */
+export declare function planTable(t: TableSchema): TablePlan;
+/** Render a table plan as a PowQL `type` DDL block. */
+export declare function renderTypeDdl(plan: TablePlan): string;
+export interface InsertResult {
+    statements: string[];
+    warnings: string[];
+    loadRisk: boolean;
+    skippedRows: number;
+}
+/**
+ * Render rows for one table as PowQL `insert` statements against its plan.
+ * Values that can't be represented are omitted (the field falls back to
+ * null/default), and each distinct skip reason is reported once per column.
+ */
+export declare function buildInserts(plan: TablePlan, rows: Array<Record<string, unknown>>): InsertResult;
+export interface PowdbPullArgs {
+    project?: string;
+    branch?: string;
+    out?: string;
+    limit?: string;
+    rest: string[];
+}
+/**
+ * Parse `powdb pull` args, consuming every value-taking flag (both ` ` and `=`
+ * forms) so a `--project` can never be mistaken for a positional. Mirrors the
+ * value-consuming discipline the other agent-facing commands use.
+ */
+export declare function parsePowdbPullArgs(args: string[]): PowdbPullArgs;
+/**
+ * Make a string safe to sit on a PowQL `#` comment line inside the artifact.
+ * `powdb-cli --exec` splits its whole input on `;` BEFORE lexing, so a `;`
+ * anywhere in a comment (our own prose, or an echoed Postgres default) would
+ * carve off a comment-only fragment that lexes to zero tokens — "expected
+ * statement, got end of input". Newlines would likewise smear a comment across
+ * a statement boundary. Neutralize both. Exported for unit testing.
+ */
+export declare function commentSafe(s: string): string;
+export declare function handlePowdb(args: string[]): Promise<void>;
+export {};

package/dist/commands/powdb.js

@@ -0,0 +1,697 @@
+import { writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { api, apiError } from "../api.js";
+import { requireToken, isJsonMode, loadConfig } from "../config.js";
+import { colors, log, json, spinner, heading, table } from "../utils/logger.js";
+import { emitError, isRetryable } from "../utils/errors.js";
+import { resolveProjectId, resolveBranchId } from "../link.js";
+// PowQL reserved words a column/table name must not collide with (from the
+// engine lexer keyword set). A colliding name is renamed and flagged rather
+// than silently producing a broken `type`/`insert`.
+const POWQL_KEYWORDS = new Set([
+    "type", "filter", "order", "limit", "offset", "insert", "update", "delete",
+    "default", "upsert", "returning", "group", "having", "distinct", "and", "or",
+    "not", "is", "null", "true", "false", "asc", "desc", "like", "in", "between",
+    "required", "unique", "auto", "count", "sum", "avg", "min", "max",
+]);
+/**
+ * Map a Postgres data type (as reported by schema introspection) to the PowDB
+ * Stage-A type that best represents it — or `null` when PowDB has no honest
+ * Stage-A representation and the column must be dropped. Every non-faithful
+ * mapping carries a `note` so the caller can surface it per-object.
+ */
+export function mapPgType(dataType) {
+    const t = dataType.trim().toLowerCase();
+    // Integer family (incl. serial, which is int + a nextval default).
+    if (["smallint", "integer", "bigint", "int", "int2", "int4", "int8",
+        "serial", "bigserial", "smallserial", "serial2", "serial4", "serial8"].includes(t)) {
+        return { powType: "int" };
+    }
+    // Floating point.
+    if (["real", "double precision", "float", "float4", "float8"].includes(t)) {
+        return { powType: "float" };
+    }
+    // Exact numeric — represented as float64, so NOT exact. Lossy, flagged.
+    if (t === "numeric" || t === "decimal" || t.startsWith("numeric(") || t.startsWith("decimal(")) {
+        return { powType: "float", note: "numeric/decimal represented as float64 — not exact; precision may be lost" };
+    }
+    // Text family.
+    if (["text", "character varying", "varchar", "character", "char", "bpchar",
+        "name", "citext", "\"char\""].includes(t) || t.startsWith("varchar(") || t.startsWith("character varying(") || t.startsWith("char(") || t.startsWith("character(")) {
+        return { powType: "str" };
+    }
+    // Boolean.
+    if (t === "boolean" || t === "bool") {
+        return { powType: "bool" };
+    }
+    // Temporal → PowDB `datetime` (i64 epoch). Stored as epoch SECONDS; timezone
+    // and sub-second precision are not modelled. Flagged.
+    if (["timestamp with time zone", "timestamp without time zone", "timestamptz",
+        "timestamp", "date"].includes(t) || t.startsWith("timestamp")) {
+        return { powType: "datetime", note: "stored as PowDB datetime (epoch seconds); timezone + sub-second precision not preserved" };
+    }
+    // time / interval have no PowDB type — carried as text.
+    if (["time", "time without time zone", "time with time zone", "timetz", "interval"].includes(t) || t.startsWith("time") || t.startsWith("interval")) {
+        return { powType: "str", note: `${t} has no PowDB type — carried as text (str)` };
+    }
+    // uuid — no static PowQL uuid literal exists, so it is carried as text.
+    if (t === "uuid") {
+        return { powType: "str", note: "uuid carried as text (str) — PowDB has no static uuid literal for a script load" };
+    }
+    // bytea — no static PowQL bytes literal exists; carried as hex text.
+    if (t === "bytea") {
+        return { powType: "str", note: "bytea carried as hex text (str) — PowDB has no static bytes literal for a script load" };
+    }
+    // json/jsonb — carried as text; no JSON operators.
+    if (t === "json" || t === "jsonb") {
+        return { powType: "str", note: `${t} carried as text (str) — no JSON operators in PowDB Stage A` };
+    }
+    // Everything else (arrays, enums, ranges, geometry, network, tsvector,
+    // composite/user-defined) has no honest Stage-A representation.
+    return { powType: null, note: `${dataType} has no PowDB Stage-A representation — column dropped` };
+}
+/**
+ * Sanitize a Postgres identifier into a valid PowQL identifier (leading
+ * alpha/underscore, then alphanumeric/underscore). Reports whether it had to be
+ * changed and whether it collides with a PowQL keyword, so the caller can flag
+ * the rename honestly rather than emit a name that means something else.
+ */
+export function powqlIdentifier(name) {
+    let ident = name.replace(/[^A-Za-z0-9_]/g, "_");
+    if (ident === "" || !/^[A-Za-z_]/.test(ident)) {
+        ident = "_" + ident;
+    }
+    const keyword = POWQL_KEYWORDS.has(ident.toLowerCase());
+    if (keyword) {
+        ident = ident + "_";
+    }
+    return { ident, changed: ident !== name, keyword };
+}
+/**
+ * Escape a string for a PowQL double-quoted literal. The engine lexer honors
+ * `\" \\ \n \t`; every other character passes through verbatim. Returns the
+ * inner content (no surrounding quotes).
+ */
+export function escapePowqlString(s) {
+    return s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\t/g, "\\t")
+        .replace(/\r/g, "\\n");
+}
+/** A raw string value that would break `powdb-cli --exec`'s naive `;`-split. */
+export function isLoadRiskyString(s) {
+    return s.includes(";") || s.includes("\n");
+}
+/**
+ * Render a JS value (as returned by SQL-over-HTTP, i.e. parsed JSON) as a PowQL
+ * literal of the given PowDB type. Returns `{ skip }` when the value cannot be
+ * represented (the field is then omitted from the insert, becoming null). Marks
+ * `risky` when the produced string literal contains a `;` or newline — data
+ * that the shipped `--exec` loader's `;`-split would corrupt (see upstream
+ * issue for a statement-aware loader).
+ */
+export function powqlLiteral(value, powType) {
+    if (value === null || value === undefined) {
+        return { skip: true, reason: "null" };
+    }
+    switch (powType) {
+        case "int": {
+            const n = typeof value === "number" ? value : Number(String(value));
+            if (!Number.isFinite(n))
+                return { skip: true, reason: `non-numeric int value ${JSON.stringify(value)}` };
+            return { literal: String(Math.trunc(n)), risky: false };
+        }
+        case "float": {
+            const n = typeof value === "number" ? value : Number(String(value));
+            if (!Number.isFinite(n))
+                return { skip: true, reason: `non-numeric float value ${JSON.stringify(value)}` };
+            // PowQL floats need a decimal point to lex as FloatLit.
+            const s = Number.isInteger(n) ? `${n}.0` : String(n);
+            return { literal: s, risky: false };
+        }
+        case "bool": {
+            if (typeof value === "boolean")
+                return { literal: value ? "true" : "false", risky: false };
+            const s = String(value).toLowerCase();
+            if (["true", "t", "1", "yes"].includes(s))
+                return { literal: "true", risky: false };
+            if (["false", "f", "0", "no"].includes(s))
+                return { literal: "false", risky: false };
+            return { skip: true, reason: `non-boolean value ${JSON.stringify(value)}` };
+        }
+        case "datetime": {
+            // Accept an epoch number or a parseable timestamp string and emit a bare
+            // epoch-SECONDS integer. PowDB stores datetime as an i64 epoch and coerces
+            // an int literal into a `datetime` column on insert — a `cast(...)`
+            // expression is rejected in insert value position (verified on 0.8.0).
+            let epoch;
+            if (typeof value === "number") {
+                epoch = Math.trunc(value);
+            }
+            else {
+                const ms = Date.parse(String(value));
+                if (!Number.isFinite(ms))
+                    return { skip: true, reason: `unparseable timestamp ${JSON.stringify(value)}` };
+                epoch = Math.floor(ms / 1000);
+            }
+            return { literal: String(epoch), risky: false };
+        }
+        case "str": {
+            // Objects/arrays (e.g. a json column) become their JSON text.
+            const raw = typeof value === "string" ? value : JSON.stringify(value);
+            return { literal: `"${escapePowqlString(raw)}"`, risky: isLoadRiskyString(raw) };
+        }
+    }
+}
+/**
+ * Interpret a Postgres column default for a given PowDB type. Only scalar
+ * literals map to a PowQL `default`; `nextval(...)` on an int maps to `auto`;
+ * expression defaults (now(), gen_random_uuid(), …) are dropped with a note so
+ * the omission is visible rather than silent.
+ */
+export function parsePgDefault(defaultValue, powType) {
+    if (!defaultValue)
+        return null;
+    const raw = defaultValue.trim();
+    // Sequence-backed (serial) → PowQL auto (int only).
+    if (/nextval\(/i.test(raw)) {
+        if (powType === "int")
+            return { kind: "auto" };
+        return { kind: "drop", note: `sequence default on a non-int column dropped (${raw})` };
+    }
+    // Strip a trailing ::type cast, e.g. 'active'::text  or  0::numeric.
+    const noCast = raw.replace(/::[A-Za-z0-9_ "\[\]]+$/, "").trim();
+    if (powType === "bool") {
+        const s = noCast.toLowerCase();
+        if (s === "true")
+            return { kind: "literal", text: "true" };
+        if (s === "false")
+            return { kind: "literal", text: "false" };
+        return { kind: "drop", note: `non-literal bool default dropped (${raw})` };
+    }
+    if (powType === "int") {
+        if (/^-?\d+$/.test(noCast))
+            return { kind: "literal", text: noCast };
+        return { kind: "drop", note: `expression default dropped (${raw})` };
+    }
+    if (powType === "float") {
+        if (/^-?\d+(\.\d+)?$/.test(noCast)) {
+            return { kind: "literal", text: noCast.includes(".") ? noCast : `${noCast}.0` };
+        }
+        return { kind: "drop", note: `expression default dropped (${raw})` };
+    }
+    // str/datetime: only a quoted string literal is a safe scalar default.
+    if (powType === "str") {
+        const m = /^'([\s\S]*)'$/.exec(noCast);
+        if (m)
+            return { kind: "literal", text: `"${escapePowqlString(m[1].replace(/''/g, "'"))}"` };
+        return { kind: "drop", note: `expression default dropped (${raw})` };
+    }
+    // datetime defaults are expressions (now(), CURRENT_TIMESTAMP) — never scalar.
+    return { kind: "drop", note: `expression default dropped (${raw})` };
+}
+/**
+ * Build the per-table PowQL `type` plan from a Postgres table's schema,
+ * accumulating an honesty note for every column/constraint that can't be
+ * carried faithfully. Pure — no I/O — so the mapping is unit-tested directly.
+ */
+export function planTable(t) {
+    const warnings = [];
+    const { ident: tPowName, changed: nameChanged, keyword } = powqlIdentifier(t.name);
+    if (nameChanged) {
+        warnings.push(`table renamed to \`${tPowName}\`${keyword ? " (collides with a PowQL keyword)" : " (name not a valid PowQL identifier)"}`);
+    }
+    // Single-column UNIQUE constraints → the PowQL `unique` modifier.
+    const singleUniqueCols = new Set();
+    for (const c of t.constraints ?? []) {
+        const type = c.type.toUpperCase();
+        if (type.includes("PRIMARY")) {
+            if (c.columns.length > 1)
+                warnings.push(`composite primary key (${c.columns.join(", ")}) not enforced — PowDB Stage A has no table constraints`);
+        }
+        else if (type.includes("UNIQUE")) {
+            if (c.columns.length === 1)
+                singleUniqueCols.add(c.columns[0]);
+            else
+                warnings.push(`composite unique constraint ${c.name} (${c.columns.join(", ")}) not enforced — PowDB uniqueness is per-column`);
+        }
+        else if (type.includes("FOREIGN")) {
+            warnings.push(`foreign key ${c.name} → ${c.foreignTableName ?? "?"} dropped — PowDB Stage A has no foreign keys`);
+        }
+        else if (type.includes("CHECK")) {
+            warnings.push(`check constraint ${c.name} dropped — PowDB Stage A has no check constraints`);
+        }
+    }
+    // Secondary (non-unique) indexes aren't carried — the type definition only
+    // expresses uniqueness, not standalone indexes.
+    for (const idx of t.indexes ?? []) {
+        if (!/unique/i.test(idx.definition)) {
+            warnings.push(`index ${idx.name} not carried — PowDB Stage A expresses only unique constraints, not secondary indexes`);
+        }
+    }
+    const columns = [];
+    for (const col of t.columns) {
+        const mapping = mapPgType(col.dataType);
+        if (mapping.powType === null) {
+            warnings.push(`column ${col.name}: ${mapping.note}`);
+            continue;
+        }
+        if (mapping.note) {
+            warnings.push(`column ${col.name}: ${mapping.note}`);
+        }
+        const { ident: colPowName, changed: colChanged, keyword: colKeyword } = powqlIdentifier(col.name);
+        if (colChanged) {
+            warnings.push(`column ${col.name} renamed to \`${colPowName}\`${colKeyword ? " (collides with a PowQL keyword)" : ""}`);
+        }
+        const def = parsePgDefault(col.defaultValue, mapping.powType);
+        let auto = false;
+        let defaultLiteral = null;
+        if (def?.kind === "auto")
+            auto = true;
+        else if (def?.kind === "literal")
+            defaultLiteral = def.text;
+        else if (def?.kind === "drop")
+            warnings.push(`column ${col.name}: ${def.note}`);
+        columns.push({
+            pgName: col.name,
+            powName: colPowName,
+            powType: mapping.powType,
+            // PowDB `auto` cannot combine with `default`; also `required` on an auto
+            // column is redundant. PK columns are required + unique.
+            required: (!col.isNullable || col.isPrimaryKey) && !auto,
+            unique: col.isPrimaryKey || singleUniqueCols.has(col.name),
+            auto,
+            defaultLiteral: auto ? null : defaultLiteral,
+        });
+    }
+    return {
+        pgQualified: `"${t.schema}"."${t.name}"`,
+        pgSchema: t.schema,
+        pgName: t.name,
+        powName: tPowName,
+        columns,
+        warnings,
+    };
+}
+/** Render a table plan as a PowQL `type` DDL block. */
+export function renderTypeDdl(plan) {
+    const lines = [`type ${plan.powName} {`];
+    const fieldLines = plan.columns.map((c) => {
+        const mods = [];
+        if (c.required)
+            mods.push("required");
+        if (c.unique)
+            mods.push("unique");
+        if (c.auto)
+            mods.push("auto");
+        const prefix = mods.length ? mods.join(" ") + " " : "";
+        const def = c.defaultLiteral ? ` default ${c.defaultLiteral}` : "";
+        return `  ${prefix}${c.powName}: ${c.powType}${def}`;
+    });
+    lines.push(fieldLines.join(",\n"));
+    lines.push("}");
+    return lines.join("\n");
+}
+/**
+ * Render rows for one table as PowQL `insert` statements against its plan.
+ * Values that can't be represented are omitted (the field falls back to
+ * null/default), and each distinct skip reason is reported once per column.
+ */
+export function buildInserts(plan, rows) {
+    const statements = [];
+    const skipNotes = new Map(); // colName → first skip reason
+    let loadRisk = false;
+    let skippedRows = 0;
+    for (const row of rows) {
+        const assigns = [];
+        let anyField = false;
+        for (const col of plan.columns) {
+            const res = powqlLiteral(row[col.pgName], col.powType);
+            if ("skip" in res) {
+                if (res.reason !== "null" && !skipNotes.has(col.pgName)) {
+                    skipNotes.set(col.pgName, res.reason);
+                }
+                continue;
+            }
+            if (res.risky)
+                loadRisk = true;
+            assigns.push(`${col.powName} := ${res.literal}`);
+            anyField = true;
+        }
+        if (!anyField) {
+            skippedRows++;
+            continue;
+        }
+        statements.push(`insert ${plan.powName} { ${assigns.join(", ")} };`);
+    }
+    const warnings = [];
+    for (const [col, reason] of skipNotes) {
+        warnings.push(`column ${col}: some values dropped — ${reason}`);
+    }
+    return { statements, warnings, loadRisk, skippedRows };
+}
+/**
+ * Parse `powdb pull` args, consuming every value-taking flag (both ` ` and `=`
+ * forms) so a `--project` can never be mistaken for a positional. Mirrors the
+ * value-consuming discipline the other agent-facing commands use.
+ */
+export function parsePowdbPullArgs(args) {
+    const out = { rest: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--project") {
+            out.project = args[++i];
+            continue;
+        }
+        if (a.startsWith("--project=")) {
+            out.project = a.slice("--project=".length);
+            continue;
+        }
+        if (a === "--branch") {
+            out.branch = args[++i];
+            continue;
+        }
+        if (a.startsWith("--branch=")) {
+            out.branch = a.slice("--branch=".length);
+            continue;
+        }
+        if (a === "--out" || a === "-o") {
+            out.out = args[++i];
+            continue;
+        }
+        if (a.startsWith("--out=")) {
+            out.out = a.slice("--out=".length);
+            continue;
+        }
+        if (a === "--limit") {
+            out.limit = args[++i];
+            continue;
+        }
+        if (a.startsWith("--limit=")) {
+            out.limit = a.slice("--limit=".length);
+            continue;
+        }
+        out.rest.push(a);
+    }
+    return out;
+}
+// ─── Command orchestration ────────────────────────────────────────────────────
+/** List a project's branches (GET /v1/projects/:id). Null on lookup failure. */
+async function listProjectBranches(projectId, token, teamId) {
+    const query = {};
+    if (teamId)
+        query.team_id = teamId;
+    const res = await api.get(`/v1/projects/${projectId}`, token, query);
+    if (!res.ok)
+        return null;
+    return { branches: res.data.branches ?? [], projectName: res.data.name };
+}
+/** Resolve a branch ref (id OR name) to a concrete id, or the primary branch. */
+async function resolveBranchTarget(projectId, token, teamId, ref) {
+    const result = await listProjectBranches(projectId, token, teamId);
+    if (!result) {
+        emitError("API_UNAVAILABLE", "Failed to list branches for this project.", "Check the project id and try again.");
+    }
+    const { branches, projectName } = result;
+    if (ref) {
+        const match = branches.find((b) => b.id === ref || b.name === ref);
+        if (!match) {
+            emitError("BRANCH_NOT_FOUND", `Branch "${ref}" not found in this project.`, "List branches with: bata db branches --json");
+        }
+        return { id: match.id, name: match.name, projectName };
+    }
+    const primary = branches.find((b) => b.isPrimary) ?? branches[0];
+    if (!primary) {
+        emitError("BRANCH_NOT_FOUND", "This project has no branches to pull.", "Create one with: bata db branch create <name>");
+    }
+    return { id: primary.id, name: primary.name, projectName };
+}
+/** Handle a failed schema/SQL request: retryable → COMPUTE_STARTING (exit 6). */
+function failRequest(res, fallback) {
+    const body = res.data;
+    if (isRetryable({ status: res.status, code: body?.code, message: body?.error })) {
+        emitError("COMPUTE_STARTING", apiError(res, fallback), "compute is starting; retry in a few seconds");
+    }
+    const code = res.status === 401 || res.status === 403 ? "INVALID_KEY"
+        : res.status === 404 ? "NO_PROJECT"
+            : "CLI_ERROR";
+    emitError(code, apiError(res, fallback), "");
+}
+async function powdbPull(args) {
+    const jsonMode = isJsonMode();
+    const { project: projectFlag, branch: branchFlag, out: outFlag, limit: limitFlag } = parsePowdbPullArgs(args);
+    let limit;
+    if (limitFlag !== undefined) {
+        const n = Number(limitFlag);
+        if (!Number.isInteger(n) || n <= 0) {
+            emitError("INVALID_FLAG", `Invalid --limit value "${limitFlag}".`, "Pass a positive integer, e.g. --limit 1000.");
+        }
+        limit = n;
+    }
+    const token = requireToken();
+    const config = loadConfig();
+    // Project precedence: --project flag > .batadata link > config default.
+    const projectId = resolveProjectId(projectFlag).projectId;
+    if (!projectId) {
+        emitError("NO_PROJECT", "No project for powdb pull.", "Pass --project <id>, or run `bata link <project>` to set a default.");
+    }
+    // Branch precedence: explicit --branch wins, else the pinned checkout branch,
+    // else the project's primary branch.
+    const branchRef = resolveBranchId(branchFlag).branchId;
+    const s = jsonMode ? null : spinner("Resolving branch");
+    const target = await resolveBranchTarget(projectId, token, config.defaultTeam, branchRef);
+    s?.update("Introspecting schema");
+    const schemaRes = await api.get(`/v1/schema/${projectId}`, token, { branch_id: target.id });
+    if (!schemaRes.ok) {
+        s?.stop();
+        failRequest(schemaRes, "Schema introspection failed");
+    }
+    const tables = schemaRes.data.schema.tables ?? [];
+    const parts = [];
+    const reports = [];
+    let totalRows = 0;
+    let anyLoadRisk = false;
+    for (const t of tables) {
+        s?.update(`Exporting ${t.schema}.${t.name}`);
+        const plan = planTable(t);
+        // Pull the table's rows over SQL-over-HTTP.
+        const sql = `SELECT * FROM ${plan.pgQualified}${limit ? ` LIMIT ${limit}` : ""}`;
+        const dataRes = await api.post("/v1/sql/execute", { branch_id: target.id, query: sql }, token);
+        if (!dataRes.ok) {
+            s?.stop();
+            failRequest(dataRes, `Failed to export data from ${t.schema}.${t.name}`);
+        }
+        if (dataRes.data.error) {
+            s?.stop();
+            emitError("CLI_ERROR", `Data export failed for ${t.schema}.${t.name}: ${dataRes.data.error}`, "");
+        }
+        const rows = dataRes.data.rows ?? [];
+        const ddl = renderTypeDdl(plan);
+        const inserts = buildInserts(plan, rows);
+        const warnings = [...plan.warnings, ...inserts.warnings];
+        if (inserts.skippedRows > 0) {
+            warnings.push(`${inserts.skippedRows} row(s) had no representable columns and were skipped`);
+        }
+        if (inserts.loadRisk)
+            anyLoadRisk = true;
+        // Emit the type DDL, its honesty notes, and the inserts for this table.
+        // Comments are `;`/newline-sanitized so they survive the `--exec` split.
+        parts.push(commentSafe(`# ── ${t.schema}.${t.name} → ${plan.powName} (${inserts.statements.length} row(s)) ──`));
+        for (const w of warnings)
+            parts.push(commentSafe(`# WARN: ${w}`));
+        if (plan.columns.length === 0) {
+            parts.push(`# (no representable columns — table skipped)`);
+            parts.push("");
+        }
+        else {
+            parts.push(ddl + ";");
+            parts.push("");
+            if (inserts.statements.length) {
+                parts.push(inserts.statements.join("\n"));
+                parts.push("");
+            }
+        }
+        totalRows += inserts.statements.length;
+        reports.push({
+            postgres: `${t.schema}.${t.name}`,
+            powdb: plan.powName,
+            columns: plan.columns.length,
+            rows: inserts.statements.length,
+            warnings,
+        });
+    }
+    s?.stop();
+    const header = buildArtifactHeader({
+        projectId,
+        projectName: target.projectName,
+        branchName: target.name,
+        branchId: target.id,
+        tableCount: tables.length,
+        rowCount: totalRows,
+        loadRisk: anyLoadRisk,
+        limit,
+    });
+    const artifact = header + "\n" + parts.join("\n") + "\n";
+    // Default output path is derived from the project + branch so repeated pulls
+    // are stable and self-describing.
+    const outPath = outFlag ?? `./${projectId}-${sanitizeForFile(target.name)}.powql`;
+    const isStdout = outFlag === "-";
+    if (!isStdout) {
+        writeFileSync(path.resolve(outPath), artifact, "utf8");
+    }
+    const warningsTotal = reports.reduce((n, r) => n + r.warnings.length, 0);
+    const loadCommand = isStdout
+        ? `powdb-cli --data-dir ./sandbox --exec "$(bata powdb pull ... )"`
+        : `powdb-cli --data-dir ./sandbox --exec "$(cat ${outPath})"`;
+    if (jsonMode) {
+        if (isStdout) {
+            // In --json + stdout mode the artifact rides in the payload, not raw.
+            json({
+                project_id: projectId,
+                branch: { id: target.id, name: target.name },
+                engine: "powdb",
+                stage: "A",
+                out: null,
+                artifact,
+                tables: reports,
+                row_count: totalRows,
+                warnings_total: warningsTotal,
+                load_risk: anyLoadRisk,
+                load_command: loadCommand,
+            });
+            return;
+        }
+        json({
+            project_id: projectId,
+            branch: { id: target.id, name: target.name },
+            engine: "powdb",
+            stage: "A",
+            out: path.resolve(outPath),
+            tables: reports,
+            row_count: totalRows,
+            warnings_total: warningsTotal,
+            load_risk: anyLoadRisk,
+            load_command: loadCommand,
+        });
+        return;
+    }
+    if (isStdout) {
+        process.stdout.write(artifact);
+        return;
+    }
+    renderPullSummary({ outPath: path.resolve(outPath), projectName: target.projectName, branchName: target.name, reports, totalRows, warningsTotal, loadRisk: anyLoadRisk, loadCommand });
+}
+/** Replace filesystem-unfriendly characters in a branch name for the out path. */
+function sanitizeForFile(name) {
+    return name.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+/**
+ * Make a string safe to sit on a PowQL `#` comment line inside the artifact.
+ * `powdb-cli --exec` splits its whole input on `;` BEFORE lexing, so a `;`
+ * anywhere in a comment (our own prose, or an echoed Postgres default) would
+ * carve off a comment-only fragment that lexes to zero tokens — "expected
+ * statement, got end of input". Newlines would likewise smear a comment across
+ * a statement boundary. Neutralize both. Exported for unit testing.
+ */
+export function commentSafe(s) {
+    return s.replace(/;/g, ",").replace(/[\r\n]+/g, " ");
+}
+function buildArtifactHeader(o) {
+    // PowQL comments start with `#` (the engine lexer's comment char — NOT `--`,
+    // which lexes as two minus signs and fails to parse).
+    const lines = [
+        "# PowDB Stage A export — generated by `bata powdb pull`",
+        "#",
+        `# Source project : ${o.projectName} (${o.projectId})`,
+        `# Source branch  : ${o.branchName} (${o.branchId})`,
+        `# Tables         : ${o.tableCount}   Rows: ${o.rowCount}${o.limit ? `  (--limit ${o.limit} per table)` : ""}`,
+        "#",
+        "# This is a PowQL script (PowDB's native language). Load it into a fresh",
+        "# local PowDB data dir and query it in-process — no network at query time:",
+        "#",
+        "#   powdb-cli --data-dir ./sandbox --exec \"$(cat <this-file>)\"",
+        "#",
+        "# COMPAT-HONEST: `# WARN:` lines below name every Postgres feature that",
+        "# PowDB Stage A cannot carry faithfully (foreign keys, check constraints,",
+        "# secondary indexes, unmapped types, expression defaults, lossy numerics).",
+        "# PowDB is NOT Postgres-compatible beyond this mapping; nothing here claims",
+        "# otherwise, and no engine-speed comparison is implied.",
+    ];
+    if (o.loadRisk) {
+        lines.push("#", "# LOAD CAVEAT: some string values contain ';' or a newline. The shipped", "# `powdb-cli --exec` splits input on ';', so those statements need a", "# statement-aware loader to load intact (tracked upstream in the PowDB repo).");
+    }
+    // Sanitize so no `;` in the prose (e.g. "beyond this mapping; nothing…")
+    // survives to break the loader's `;`-split.
+    return lines.map(commentSafe).join("\n");
+}
+function renderPullSummary(o) {
+    heading(`PowDB pull — ${o.projectName} / ${o.branchName}`);
+    if (o.reports.length === 0) {
+        log(`  ${colors.dim("No tables in this branch's schema.")}`);
+        log();
+        return;
+    }
+    table(["POSTGRES", "POWDB", "COLUMNS", "ROWS", "NOTES"], o.reports.map((r) => [
+        r.postgres,
+        r.powdb,
+        String(r.columns),
+        String(r.rows),
+        r.warnings.length ? colors.yellow(String(r.warnings.length)) : colors.dim("0"),
+    ]));
+    log();
+    if (o.warningsTotal > 0) {
+        log(`  ${colors.yellow(`${o.warningsTotal} compat note(s)`)} ${colors.dim("— PowDB Stage A can't carry every Postgres feature. Details are `# WARN:` lines in the artifact.")}`);
+    }
+    if (o.loadRisk) {
+        log(`  ${colors.yellow("!")} ${colors.dim("Some string data contains ';' or newlines — see the LOAD CAVEAT in the artifact header.")}`);
+    }
+    log();
+    log(`  ${colors.green(">")} Wrote ${colors.cyan(o.outPath)} ${colors.dim(`(${o.totalRows} row(s))`)}`);
+    log(`  ${colors.dim("Load it:")} ${colors.cyan(o.loadCommand)}`);
+    log();
+}
+// ─── Help + dispatch ──────────────────────────────────────────────────────────
+function powdbHelp() {
+    log();
+    log(`  ${colors.bold("bata powdb")} ${colors.dim("— PowDB embedded lane (Stage A)")}`);
+    log();
+    log(`  ${colors.dim("PowDB is an embedded engine: it runs inside your process, so a pulled")}`);
+    log(`  ${colors.dim("copy of a branch costs nothing to query and has no network round-trips.")}`);
+    log(`  ${colors.dim("BataDB branching / metering / server insights do NOT apply to it.")}`);
+    log();
+    log(`  ${colors.dim("Commands:")}`);
+    log(`    ${colors.cyan("pull")}    Pull a branch's schema + data into a local PowDB-loadable PowQL script`);
+    log();
+    log(`  ${colors.dim("Options (pull):")}`);
+    log(`    ${colors.dim("--project <id>       override the linked/default project")}`);
+    log(`    ${colors.dim("--branch <name|id>   branch to pull (default: primary)")}`);
+    log(`    ${colors.dim("--out <path|->       artifact path (default: ./<project>-<branch>.powql; - = stdout)")}`);
+    log(`    ${colors.dim("--limit <n>          cap rows exported per table")}`);
+    log(`    ${colors.dim("--json               machine-readable summary + per-table compat notes")}`);
+    log();
+    log(`  ${colors.dim("Example:")}`);
+    log(`    ${colors.dim("bata powdb pull --branch main --out ./sandbox.powql")}`);
+    log(`    ${colors.dim('powdb-cli --data-dir ./sandbox --exec "$(cat ./sandbox.powql)"')}`);
+    log();
+    log(`  ${colors.dim("Compat-honest: unrepresentable Postgres features are reported per-object")}`);
+    log(`  ${colors.dim("as `# WARN:` lines in the artifact — see docs/powdb.md.")}`);
+    log();
+}
+export async function handlePowdb(args) {
+    const sub = args[0];
+    if (sub === "--help" || sub === "-h" || args.includes("--help") || args.includes("-h")) {
+        powdbHelp();
+        return;
+    }
+    switch (sub) {
+        case "pull":
+            return powdbPull(args.slice(1));
+        case undefined:
+            powdbHelp();
+            return;
+        default:
+            emitError("INVALID_FLAG", `Unknown subcommand: powdb ${sub}`, "Available: pull. Run `bata powdb --help`.");
+    }
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { status } from "./commands/status.js";
 import { connect } from "./commands/connect.js";
 import { usage } from "./commands/usage.js";
 import { handleRestore } from "./commands/restore.js";
+import { handlePowdb } from "./commands/powdb.js";
 import { link, unlink } from "./commands/link.js";
 import { parseGlobalFlags } from "./args.js";
 import { isJsonMode } from "./config.js";
@@ -64,6 +65,9 @@ function help() {
     log(`    ${colors.cyan("schema check|dump|diff")}  Schema safety gate + introspection`);
     log(`    ${colors.cyan("migrate check")}      Gate a migration against live query traffic ${colors.dim("(exit 2 if breaking)")}`);
     log();
+    log(`  ${colors.bold("PowDB (embedded lane, Stage A)")}`);
+    log(`    ${colors.cyan("powdb pull")}         Pull a branch's schema + data into a local PowDB-loadable PowQL script`);
+    log();
     log(`  ${colors.bold("Development")}`);
     log(`    ${colors.cyan("dev")}                Local development setup guide`);
     log();
@@ -173,6 +177,10 @@ async function main() {
             case "schema":
                 await handleSchema(rest);
                 break;
+            // PowDB embedded lane (Stage A)
+            case "powdb":
+                await handlePowdb(rest);
+                break;
             // Generate
             case "generate":
                 await generate(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@batadata/cli",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "CLI for BataDB — serverless Postgres platform",
   "bin": {
     "bata": "./dist/index.js"