@xano/cli 1.3.5-beta.1 → 1.3.5-beta.2

package/README.md

@@ -447,6 +447,42 @@ when the function returns an error status.
 > denied with an access error — grant run/debug to the role (or use a token whose role has
 > it). `function list`/`get`/`create`/`edit` only need the Function permission.
 
+### Tables
+
+```bash
+# Export a table's audit trail (newest first; by table name or ID)
+xano table audit users                                  # the 50 newest events, as JSON
+xano table audit users --all -o csv -f users_audit.csv  # every event, as CSV, to a file
+xano table audit 42 --record 17 --op update --all       # every update of record 17
+xano table audit users --limit 100 --before 98765       # the page after cursor 98765
+xano table audit users --datasource test --all          # the trail on the 'test' data source
+```
+
+`table audit` is read-only: it exports what the database recorded for auditors and scripts.
+Auditing itself is turned on and off in the table's XanoScript `audit` block
+(`audit = {enabled: true, mask: [...], exclude: [...]}`) and goes through `workspace push`/`pull`.
+
+| Flag | Meaning |
+| --- | --- |
+| `--record <id>` | only the events of this record |
+| `--op <op>` | only `insert`, `update`, `delete`, `truncate` or `system` events |
+| `--limit <n>` | events per request (page size), 1-100, default 50. Without `--all` it is the number of events returned |
+| `--before <cursor>` | start after this cursor (the `next` value of a previous page) |
+| `--all` | follow the `next` cursor until every matching event is fetched |
+| `--datasource <label>` | read the trail of a non-live data source (sends `X-Data-Source`; default `live`) |
+| `-o, --output json\|csv` | `json` (default): the route's response (`enabled`, `available`, `log_table`, `items`, `next`), with every page's `items` joined under `--all`. `csv`: a header and one row per event |
+| `-f, --file <path>` | write the export to a file instead of stdout |
+
+CSV columns, in order: `id, created_at, tx_id, op, record_id, changed, old, new, context, db_user,
+app_name, client_addr`. `created_at` is ISO 8601 UTC with milliseconds; `changed`, `old`, `new` and
+`context` (who made the change: source, user, endpoint) are JSON strings. Without `--all`, when more
+events remain the command prints `More events: rerun with --before <next>` on stderr. When auditing is
+off for the table it says so on stderr (events recorded while it was on are still exported).
+
+On a plan without Content Record Audit, a push that would turn a table's auditing on is refused, and
+the CLI prints `Content Record Audit is not included in this plan. Upgrade to Pro or above to audit a
+table.`
+
 ### Knowledge
 
 ```bash

package/dist/base-command.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { Agent } from 'undici';
 import { checkForUpdate } from './update-check.js';
 import { applyLocalOverrides, findLocalProfilePath, formatLocalProfileBanner, parseLocalProfile, resolveProfileSelection, } from './utils/local-config.js';
+import { auditPlanRequiredMessage } from './utils/table-audit.js';
 export function buildUserAgent(version) {
     return `xano-cli/${version} (${process.platform}; ${process.arch}) node/${process.version}`;
 }
@@ -308,6 +309,8 @@ export default class BaseCommand extends Command {
             if (errorJson.message) {
                 message = errorJson.message;
             }
+            // turning on table audit on a plan without Content Record Audit (403, payload.code audit_plan_required)
+            message = auditPlanRequiredMessage(errorJson) ?? message;
         }
         catch {
             if (errorText) {

package/dist/commands/table/audit/index.d.ts

@@ -0,0 +1,35 @@
+import BaseCommand from '../../../base-command.js';
+/** True when the raw argv names an output file, so the data is not what stdout carries. */
+export declare function argvWritesFile(argv: string[]): boolean;
+export default class TableAudit extends BaseCommand {
+    static args: {
+        table: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        before: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        datasource: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        op: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        record: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    /** stdout carries the export unless it goes to a file: keep banners and verbose logs off it. */
+    protected isJsonOutput(): boolean;
+    run(): Promise<void>;
+    /** Say on stderr when the table is not being audited, so an empty export is not a mystery. */
+    private explainState;
+    private fetchPage;
+    /**
+     * A table ID as given, or the ID of the table with exactly this name (falling back to a single
+     * case-insensitive match). An all-digit argument is always an ID.
+     */
+    private resolveTableId;
+}

package/dist/commands/table/audit/index.js

@@ -0,0 +1,189 @@
+import { Args, Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import path from 'node:path';
+import BaseCommand from '../../../base-command.js';
+import { normalizeListResponse } from '../../../utils/paging.js';
+import { AUDIT_DEFAULT_LIMIT, AUDIT_MAX_LIMIT, AUDIT_OPS, AUDIT_PLAN_REQUIRED_MESSAGE, auditEventsToCsv, buildAuditQuery, normalizeAuditPage, } from '../../../utils/table-audit.js';
+/** True when the raw argv names an output file, so the data is not what stdout carries. */
+export function argvWritesFile(argv) {
+    return argv.some((arg) => arg === '-f' || arg === '--file' || arg.startsWith('--file=') || arg.startsWith('-f='));
+}
+export default class TableAudit extends BaseCommand {
+    static args = {
+        table: Args.string({
+            description: 'Table name or ID',
+            required: true,
+        }),
+    };
+    static description = "Export a table's audit trail (read-only), newest first. Auditing itself is turned on and off in the table's XanoScript `audit` block and goes through push/pull.";
+    static examples = [
+        `$ xano table audit users
+# The 50 newest events of the users table, as JSON`,
+        `$ xano table audit users --all -o csv -f users_audit.csv
+Saved 1234 events to /path/to/users_audit.csv`,
+        `$ xano table audit 42 --record 17 --op update --all
+# Every update of record 17 in table 42`,
+        `$ xano table audit users --limit 100 --before 98765
+# The page after the one whose next cursor was 98765`,
+        `$ xano table audit users --datasource test --all -o csv
+# The trail recorded on the 'test' data source`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        all: Flags.boolean({
+            default: false,
+            description: 'Follow the next cursor until every matching event is fetched',
+            required: false,
+        }),
+        before: Flags.integer({
+            description: 'Start after this cursor (the `next` value of a previous page)',
+            min: 1,
+            required: false,
+        }),
+        datasource: Flags.string({
+            description: 'Data source whose trail to read, e.g. test (defaults to live)',
+            required: false,
+        }),
+        file: Flags.string({
+            char: 'f',
+            description: 'Write the export to this file instead of stdout',
+            required: false,
+        }),
+        limit: Flags.integer({
+            default: AUDIT_DEFAULT_LIMIT,
+            description: `Events per request (page size), 1-${AUDIT_MAX_LIMIT}. Without --all this is the number of events returned`,
+            max: AUDIT_MAX_LIMIT,
+            min: 1,
+            required: false,
+        }),
+        op: Flags.string({
+            description: 'Only events of this operation',
+            options: [...AUDIT_OPS],
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'json',
+            description: 'Output format: json (the trail as the API returns it) or csv (one row per event)',
+            options: ['json', 'csv'],
+            required: false,
+        }),
+        record: Flags.string({
+            description: 'Only the events of this record ID',
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    /** stdout carries the export unless it goes to a file: keep banners and verbose logs off it. */
+    isJsonOutput() {
+        return !argvWritesFile(this.argv);
+    }
+    async run() {
+        const { args, flags } = await this.parse(TableAudit);
+        const { profile, profileName } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano table audit <table> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        const api = { profile, verbose: flags.verbose, workspaceId };
+        const tableId = await this.resolveTableId(api, args.table);
+        const dataSource = flags.datasource?.trim();
+        const items = [];
+        let first;
+        let { before } = flags;
+        let next = null;
+        /* eslint-disable no-await-in-loop -- each page's cursor comes from the page before */
+        while (true) {
+            const page = await this.fetchPage(api, tableId, {
+                before,
+                dataSource,
+                limit: flags.limit,
+                op: flags.op,
+                record: flags.record,
+            });
+            first ??= page;
+            items.push(...page.items);
+            next = page.next ?? null;
+            // a cursor that does not move would loop forever; stop rather than refetch the same page
+            if (!flags.all || next === null || next === before)
+                break;
+            before = next;
+        }
+        /* eslint-enable no-await-in-loop */
+        const trail = { ...first, items, next: flags.all ? null : next };
+        this.explainState(trail, args.table);
+        const content = flags.output === 'csv' ? auditEventsToCsv(items) : `${JSON.stringify(trail, null, 2)}\n`;
+        if (flags.file) {
+            const filePath = path.resolve(flags.file);
+            try {
+                fs.writeFileSync(filePath, content, 'utf8');
+            }
+            catch (error) {
+                this.error(`Failed to write ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            this.log(`Saved ${items.length} event${items.length === 1 ? '' : 's'} to ${filePath}`);
+        }
+        else {
+            this.log(content.replace(/\n$/, ''));
+        }
+        if (!flags.all && next !== null) {
+            this.logToStderr(`More events: rerun with --before ${next}, or with --all for every event.`);
+        }
+    }
+    /** Say on stderr when the table is not being audited, so an empty export is not a mystery. */
+    explainState(trail, table) {
+        if (trail.enabled !== false)
+            return;
+        const plan = trail.available === false ? ` ${AUDIT_PLAN_REQUIRED_MESSAGE}` : '';
+        this.warn(`Auditing is off for table '${table}'; any events listed were recorded while it was on. ` +
+            `Turn it on with the table's XanoScript audit block.${plan}`);
+    }
+    async fetchPage(api, tableId, query) {
+        const params = buildAuditQuery(query);
+        const url = `${api.profile.instance_origin}/api:meta/workspace/${api.workspaceId}/table/${tableId}/audit?${params.toString()}`;
+        const headers = {
+            accept: 'application/json',
+            Authorization: `Bearer ${api.profile.access_token}`,
+        };
+        // The route reads the trail recorded on the data source named by X-Data-Source (default live).
+        if (query.dataSource)
+            headers['X-Data-Source'] = query.dataSource;
+        const response = await this.verboseFetch(url, { headers, method: 'GET' }, api.verbose, api.profile.access_token);
+        if (!response.ok) {
+            this.error(await this.parseApiError(response, 'Failed to fetch the audit trail'));
+        }
+        return normalizeAuditPage(await response.json());
+    }
+    /**
+     * A table ID as given, or the ID of the table with exactly this name (falling back to a single
+     * case-insensitive match). An all-digit argument is always an ID.
+     */
+    async resolveTableId(api, table) {
+        const trimmed = table.trim();
+        if (/^\d+$/.test(trimmed))
+            return Number(trimmed);
+        const params = new URLSearchParams({ page: '1', per_page: '10000', search: trimmed });
+        const url = `${api.profile.instance_origin}/api:meta/workspace/${api.workspaceId}/table?${params.toString()}`;
+        const response = await this.verboseFetch(url, { headers: { accept: 'application/json', Authorization: `Bearer ${api.profile.access_token}` }, method: 'GET' }, api.verbose, api.profile.access_token);
+        if (!response.ok) {
+            this.error(await this.parseApiError(response, 'Failed to look up the table'));
+        }
+        const { items } = normalizeListResponse(await response.json());
+        const exact = items.filter((item) => item.name === trimmed);
+        const matches = exact.length > 0 ? exact : items.filter((item) => item.name?.toLowerCase() === trimmed.toLowerCase());
+        if (matches.length === 0) {
+            this.error(`Table '${trimmed}' not found in workspace ${api.workspaceId}.`);
+        }
+        if (matches.length > 1) {
+            const ids = matches.map((item) => item.id).join(', ');
+            this.error(`More than one table matches '${trimmed}' (IDs ${ids}). Pass the table ID instead.`);
+        }
+        return matches[0].id;
+    }
+}

package/dist/utils/multidoc-push.js

@@ -11,6 +11,7 @@ import { PushPolicyGateError } from './policy/push-gate.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
 import { invalidateSandboxMarkerForOrigin, readMarkerToken, sandboxMarkerExists, writeMarkerToken, } from './sandbox-marker.js';
 import { hashBytes, hashFile, instanceHost, loadSyncState, recordEntriesForContents, resolveTarget, sandboxTargetIdentity, saveSyncState, syncStateExists, toRelPath, } from './sync-state.js';
+import { auditPlanRequiredMessage } from './table-audit.js';
 /**
  * A push that failed after its multidoc import landed. The import is not rolled back, so the error
  * carries what it did for the calling command to report beside the failure.
@@ -1828,6 +1829,11 @@ function refuseIfExplained(command, target, status, body) {
     // push itself would be refused the same way, so the preview stops here rather than skipping.
     if (status === 403 && refusal?.code === 'policy_plan_limit')
         command.error(`Push refused (${status}): ${message}`);
+    // A table whose audit block turns auditing on, on a plan without Content Record Audit: the push
+    // would be refused the same way, so the preview stops here too.
+    const auditPlan = auditPlanRequiredMessage({ payload });
+    if (auditPlan)
+        command.error(`Push refused (${status}): ${auditPlan}`);
     if (refusal?.code === 'policy_gate_transaction_required') {
         command.error('Push refused: the live branch policy gate requires a transaction. Remove --no-transaction and retry. Nothing was imported.');
     }

package/dist/utils/table-audit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Helpers for `xano table audit`: the audit-trail route's shapes, its query string, the CSV
+ * rendering of its events, and the plan refusal a push or an API call can carry.
+ *
+ * The route is `GET /api:meta/workspace/{workspace_id}/table/{table_id}/audit` (MCP tool
+ * `getTableAuditTrail`). It pages newest first with a cursor: `next` is the id to pass as `before`
+ * for the page after, and is null on the last page.
+ */
+/** The `op` values the route accepts. */
+export declare const AUDIT_OPS: readonly ["insert", "update", "delete", "truncate", "system"];
+/** The route's largest page. */
+export declare const AUDIT_MAX_LIMIT = 100;
+/** The route's default page. */
+export declare const AUDIT_DEFAULT_LIMIT = 50;
+/** One recorded event, as the route returns it. */
+export interface AuditEvent {
+    app_name?: null | string;
+    changed?: null | string[];
+    client_addr?: null | string;
+    /** Who made the change, as Xano stamped it (source, user, endpoint, ...). */
+    context?: unknown;
+    /** Milliseconds since the epoch. */
+    created_at?: number;
+    db_user?: null | string;
+    id: number;
+    new?: unknown;
+    old?: unknown;
+    op?: string;
+    record_id?: null | string;
+    tx_id?: number;
+}
+/** One page of the route. */
+export interface AuditTrailPage {
+    [key: string]: unknown;
+    /** Whether the plan lets a table start being audited. Absent on an older instance. */
+    available?: boolean;
+    /** Whether auditing is on for this table. */
+    enabled?: boolean;
+    items: AuditEvent[];
+    /** The table's read-only audit log table, or null. */
+    log_table?: unknown;
+    /** The `before` cursor of the next page; null or absent on the last page. */
+    next?: null | number;
+}
+export interface AuditQuery {
+    before?: number;
+    limit?: number;
+    op?: string;
+    record?: string;
+}
+/** The route's query string. Only the filters that were given are sent. */
+export declare function buildAuditQuery(query: AuditQuery): URLSearchParams;
+/** The route's response, normalized: a missing items list is an empty one, a missing next is null. */
+export declare function normalizeAuditPage(data: unknown): AuditTrailPage;
+/** The CSV columns, in order. Stable: scripts and auditors key on them. */
+export declare const AUDIT_CSV_COLUMNS: readonly ["id", "created_at", "tx_id", "op", "record_id", "changed", "old", "new", "context", "db_user", "app_name", "client_addr"];
+/** One CSV field (RFC 4180): quoted when it holds a comma, a quote or a line break. */
+export declare function csvField(value: unknown): string;
+/**
+ * Events as CSV: a header row, then one row per event. old, new, changed and context are JSON
+ * strings. Values are written as recorded, without spreadsheet-formula escaping, so the export
+ * stays a faithful copy of the trail.
+ */
+export declare function auditEventsToCsv(events: AuditEvent[]): string;
+/** The refusal's `payload.code` when a plan does not include Content Record Audit. */
+export declare const AUDIT_PLAN_REQUIRED_CODE = "audit_plan_required";
+export declare const AUDIT_PLAN_REQUIRED_MESSAGE = "Content Record Audit is not included in this plan. Upgrade to Pro or above to audit a table.";
+/**
+ * The plan message when an API error body is the "turning on table audit needs a higher plan"
+ * refusal (a 403 with `payload.code` `audit_plan_required`), else undefined.
+ */
+export declare function auditPlanRequiredMessage(body: unknown): string | undefined;

package/dist/utils/table-audit.js

@@ -0,0 +1,90 @@
+/**
+ * Helpers for `xano table audit`: the audit-trail route's shapes, its query string, the CSV
+ * rendering of its events, and the plan refusal a push or an API call can carry.
+ *
+ * The route is `GET /api:meta/workspace/{workspace_id}/table/{table_id}/audit` (MCP tool
+ * `getTableAuditTrail`). It pages newest first with a cursor: `next` is the id to pass as `before`
+ * for the page after, and is null on the last page.
+ */
+/** The `op` values the route accepts. */
+export const AUDIT_OPS = ['insert', 'update', 'delete', 'truncate', 'system'];
+/** The route's largest page. */
+export const AUDIT_MAX_LIMIT = 100;
+/** The route's default page. */
+export const AUDIT_DEFAULT_LIMIT = 50;
+/** The route's query string. Only the filters that were given are sent. */
+export function buildAuditQuery(query) {
+    const params = new URLSearchParams();
+    if (query.record !== undefined && query.record !== '')
+        params.set('record_id', query.record);
+    if (query.op)
+        params.set('op', query.op);
+    if (query.before !== undefined)
+        params.set('before', String(query.before));
+    if (query.limit !== undefined)
+        params.set('limit', String(query.limit));
+    return params;
+}
+/** The route's response, normalized: a missing items list is an empty one, a missing next is null. */
+export function normalizeAuditPage(data) {
+    const record = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+    const items = Array.isArray(record.items) ? record.items : [];
+    const next = typeof record.next === 'number' ? record.next : null;
+    return { ...record, items, next };
+}
+/** The CSV columns, in order. Stable: scripts and auditors key on them. */
+export const AUDIT_CSV_COLUMNS = [
+    'id',
+    'created_at',
+    'tx_id',
+    'op',
+    'record_id',
+    'changed',
+    'old',
+    'new',
+    'context',
+    'db_user',
+    'app_name',
+    'client_addr',
+];
+/** One CSV field (RFC 4180): quoted when it holds a comma, a quote or a line break. */
+export function csvField(value) {
+    if (value === null || value === undefined)
+        return '';
+    const text = typeof value === 'string' ? value : typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function csvValue(event, column) {
+    if (column === 'created_at') {
+        // milliseconds since the epoch, written as ISO 8601 UTC (lossless: it keeps the milliseconds)
+        return typeof event.created_at === 'number' ? new Date(event.created_at).toISOString() : event.created_at;
+    }
+    return event[column];
+}
+/**
+ * Events as CSV: a header row, then one row per event. old, new, changed and context are JSON
+ * strings. Values are written as recorded, without spreadsheet-formula escaping, so the export
+ * stays a faithful copy of the trail.
+ */
+export function auditEventsToCsv(events) {
+    const rows = [AUDIT_CSV_COLUMNS.join(',')];
+    for (const event of events) {
+        rows.push(AUDIT_CSV_COLUMNS.map((column) => csvField(csvValue(event, column))).join(','));
+    }
+    return `${rows.join('\n')}\n`;
+}
+/** The refusal's `payload.code` when a plan does not include Content Record Audit. */
+export const AUDIT_PLAN_REQUIRED_CODE = 'audit_plan_required';
+export const AUDIT_PLAN_REQUIRED_MESSAGE = 'Content Record Audit is not included in this plan. Upgrade to Pro or above to audit a table.';
+/**
+ * The plan message when an API error body is the "turning on table audit needs a higher plan"
+ * refusal (a 403 with `payload.code` `audit_plan_required`), else undefined.
+ */
+export function auditPlanRequiredMessage(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const { payload } = body;
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    return payload.code === AUDIT_PLAN_REQUIRED_CODE ? AUDIT_PLAN_REQUIRED_MESSAGE : undefined;
+}