@xano/cli 1.3.0 → 1.3.1-beta.1

package/dist/policy-command.js

@@ -0,0 +1,94 @@
+import { Args, Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import BaseCommand from './base-command.js';
+import { POLICY_ROUTE, policyRequest, policyScope } from './utils/policy/request.js';
+import { policyRunDetail } from './utils/policy/runs.js';
+/** Shared flags, request helper and output for the `policy *` commands and `skills pull`. */
+export default class PolicyCommand extends BaseCommand {
+    static policyFlags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({ char: 'b', description: "Branch label (defaults to profile branch or live; -b '' selects live)" }),
+        output: Flags.string({ char: 'o', default: 'summary', description: 'Output format', options: ['summary', 'json'] }),
+        workspace: Flags.string({ char: 'w', description: 'Workspace ID (defaults to profile workspace)' }),
+    };
+    /** `publish -m`: the message on the Version History entry the save creates. */
+    static publishFlags = {
+        message: Flags.string({ char: 'm', description: 'Message stored on the Version History entry this save creates' }),
+    };
+    /** One positional, as CLAUDE.md requires: the file `--file` would otherwise name. */
+    static sourceArgs = {
+        file: Args.string({ description: 'Policy XanoScript file (same as --file)', ignoreStdin: true, required: false }),
+    };
+    static sourceFlags = {
+        file: Flags.string({ char: 'f', description: 'Policy XanoScript file', exclusive: ['stdin'] }),
+        stdin: Flags.boolean({ default: false, description: 'Read policy XanoScript from stdin', exclusive: ['file'] }),
+    };
+    /** Any failure exits 1; an error that is not the CLI's own names the command it broke. */
+    async catch(error) {
+        if ('oclif' in error)
+            return this.catchAsOperational(error);
+        const action = this.id?.split(':').at(-1) ?? 'command';
+        return this.catchAsOperational(new Error(`Policy ${action} failed: ${error.message}`));
+    }
+    /**
+     * Print each rule's warnings (a name, tag or value that makes the rule check nothing) to stderr,
+     * so piped source stays clean; nothing when there are none.
+     */
+    logRuleWarnings(parsed) {
+        const warned = parsed.rule_warnings ?? [];
+        if (warned.length === 0)
+            return;
+        this.logToStderr('Rule warnings (the rule may check nothing or everything; fix them before relying on it):');
+        for (const rule of warned) {
+            for (const warning of rule.warnings)
+                this.logToStderr(`  ${rule.rule_id || `rule[${rule.rule}]`}: ${warning}`);
+        }
+    }
+    /** Print a run's recorded detail, or say it evaluated no policy. */
+    logRunDetail(run) {
+        const detail = policyRunDetail(run);
+        for (const line of detail)
+            this.log(line);
+        if (detail.length === 0)
+            this.log(run.id ? `Run ${run.id} evaluated no policies.` : 'No policies were evaluated.');
+    }
+    /**
+     * Ask the parse route for the policy, its canonical source and each rule's warnings against the
+     * target branch, from XanoScript (`{source}`) or a policy document (`{data}`); the policy and source
+     * must come back.
+     */
+    async parseSource(request, input) {
+        const answer = (await request('/parse', 'POST', input));
+        if (!answer?.policy?.key || typeof answer.source !== 'string')
+            this.error('The platform did not return a parsed policy and canonical source.');
+        return { ...answer, rule_warnings: Array.isArray(answer.rule_warnings) ? answer.rule_warnings : [] };
+    }
+    /**
+     * The workspace and branch from the flags or the profile, and a request helper bound to them for
+     * a route gated by `workspace:policy`: `/policy` unless another is named.
+     */
+    policyTarget(flags, route = POLICY_ROUTE) {
+        const { profile } = this.resolveProfile(flags);
+        const { branch, workspace } = policyScope(flags, profile);
+        if (!workspace)
+            this.error('Workspace ID required. Use --workspace or set one in your profile.');
+        const request = policyRequest({ error: (message) => this.error(message), logToStderr: (message) => this.logToStderr(message), verboseFetch: (...args) => this.verboseFetch(...args) }, { ...route, branch, profile, verbose: flags.verbose, workspace });
+        return { branch, request, workspace };
+    }
+    /** Policy source from the positional, `--file` or `--stdin`; a file named twice must be named the same. */
+    readSource(flags, positional) {
+        const named = positional?.trim();
+        if (named && flags.stdin)
+            this.error('Provide policy source once: a file (positional or --file) or --stdin.');
+        if (named && flags.file && flags.file !== named)
+            this.error('Provide the file once: as a positional or as --file.');
+        const file = flags.file ?? named;
+        if (!file && !flags.stdin)
+            this.error('Provide the policy file (as an argument or --file) or --stdin.');
+        return fs.readFileSync(flags.stdin ? 0 : file, 'utf8');
+    }
+    /** `workspace 3 (feature)`, or just `workspace 3` for live. */
+    where({ branch, workspace }) {
+        return `workspace ${workspace}${branch ? ` (${branch})` : ''}`;
+    }
+}

package/dist/utils/document-parser.d.ts

@@ -11,6 +11,16 @@ export interface ParsedDocument {
     type: string;
     verb?: string;
 }
+/**
+ * The platform's policy key pattern, kept offline for file names. A command that already holds the
+ * catalogue validates a key against the catalogue's `document.key.pattern` instead.
+ */
+export declare const POLICY_KEY_PATTERN: RegExp;
+/**
+ * The file name, without `.xs`, for a policy key. The pattern is the platform's own key pattern, so a
+ * key from the server can never name a path outside `policies/`.
+ */
+export declare function policyBaseName(key: string): string;
 /**
  * Parse a single XanoScript document to extract its type, name, and optional verb/api_group.
  * Skips leading comment lines (starting with //) to find the first meaningful line.

package/dist/utils/document-parser.js

@@ -1,3 +1,17 @@
+/**
+ * The platform's policy key pattern, kept offline for file names. A command that already holds the
+ * catalogue validates a key against the catalogue's `document.key.pattern` instead.
+ */
+export const POLICY_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * The file name, without `.xs`, for a policy key. The pattern is the platform's own key pattern, so a
+ * key from the server can never name a path outside `policies/`.
+ */
+export function policyBaseName(key) {
+    if (!POLICY_KEY_PATTERN.test(key))
+        throw new Error(`Invalid policy key: ${key}`);
+    return key;
+}
 /**
  * Parse a single XanoScript document to extract its type, name, and optional verb/api_group.
  * Skips leading comment lines (starting with //) to find the first meaningful line.
@@ -33,6 +47,9 @@ export function parseDocument(content) {
     if (name.startsWith('"') && name.endsWith('"')) {
         name = name.slice(1, -1);
     }
+    // Policy bodies are opaque. Prose/parameters may mention guid or api_group; these are not document identity.
+    if (type === 'policy')
+        return { content, name, type };
     // Extract verb if present (e.g., verb=GET)
     let verb;
     const verbMatch = rest.match(/verb=(\S+)/);
@@ -162,6 +179,10 @@ export function sanitizeDocumentName(name, snakeCaseFn) {
 export function resolveDocumentPath(doc, outputDir, deps) {
     const { getApiGroupFolder, getChannelServer, join, snakeCase } = deps;
     const sanitize = (name) => sanitizeDocumentName(name, snakeCase);
+    if (doc.type === 'policy') {
+        // policy → policies/{key}.xs (the key is validated, never snake_cased)
+        return { baseName: policyBaseName(doc.name), typeDir: join(outputDir, 'policies') };
+    }
     if (doc.type === 'workspace') {
         // workspace → workspace/{name}.xs
         return { baseName: sanitize(doc.name), typeDir: join(outputDir, 'workspace') };

package/dist/utils/multidoc-push.d.ts

@@ -1,4 +1,4 @@
-import { Command } from '@oclif/core';
+import { Command, Errors } from '@oclif/core';
 import { type BadIndex, type BadReference } from './reference-checker.js';
 export interface PushFlags {
     delete: boolean;
@@ -21,6 +21,11 @@ export interface PushTarget {
     buildPushUrl: (queryParams: URLSearchParams) => string;
     /** CLI version string */
     cliVersion: string;
+    /**
+     * Guidance for a refusal this target recognises, given the HTTP status and the server's payload.
+     * A preview or import refused that way stops with the message and this guidance appended.
+     */
+    explainRefusal?: (status: number, payload: unknown) => string | undefined;
     /** Instance origin URL (e.g., "https://x123-abcd-1234.xano.io") */
     instanceOrigin: string;
     /** Human-readable label for log messages (e.g., "sandbox environment", "workspace 40") */
@@ -54,8 +59,56 @@ export interface PushContext {
     inputDir: string;
     /** Optional knowledge sync config. Only workspace push sets this. */
     knowledge?: KnowledgeConfig;
+    /** Where progress and diagnostics go; defaults to the command's stdout. */
+    log?: (message: string) => void;
     verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
 }
+export interface DryRunSummary {
+    created: number;
+    deleted: number;
+    truncated: number;
+    unchanged: number;
+    updated: number;
+}
+export interface DryRunOperation {
+    action: string;
+    details: string;
+    name: string;
+    reason?: string;
+    type: string;
+}
+export interface DryRunResult {
+    operations: DryRunOperation[];
+    /** True when the sandbox currently holds a different source workspace than the one being pushed. */
+    source_workspace_mismatch?: boolean;
+    summary: Record<string, DryRunSummary>;
+    workspace_name?: string;
+}
+/** What a push did, for the calling command to report. */
+export interface PushResult {
+    knowledge: {
+        deleted: number;
+        imported: number;
+    };
+    preview: DryRunResult | null;
+    /** The multidoc import's response body; absent when no multidoc was imported. */
+    response?: Record<string, unknown>;
+    /** The documents the multidoc import carried. */
+    sent: Array<{
+        content: string;
+        filePath: string;
+    }>;
+    /** Why the push stopped before writing anything, when it did. */
+    stopped?: 'blocked' | 'cancelled' | 'dry-run' | 'no-changes';
+}
+/**
+ * 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.
+ */
+export declare class FailedAfterImportError extends Errors.CLIError {
+    readonly imported: PushResult;
+    constructor(message: string, imported: PushResult);
+}
 /**
  * Filter document entries down to the ones the dry-run preview reports as changed,
  * used to send only the changed documents during a partial (non-`--sync`) push.
@@ -192,7 +245,7 @@ export declare function confirm(message: string): Promise<boolean>;
  * Execute a multidoc push with preview, validation, partial mode, and GUID sync.
  * Shared by both sandbox:push and workspace:push commands.
  */
-export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<void>;
+export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<PushResult>;
 /**
  * Turn a thrown fetch/network error into an actionable message.
  *

package/dist/utils/multidoc-push.js

@@ -1,11 +1,24 @@
-import { ux } from '@oclif/core';
+import { Errors, ux } from '@oclif/core';
 import { minimatch } from 'minimatch';
 import * as fs from 'node:fs';
 import { join, relative } from 'node:path';
 import { buildDocumentKey, findFilesWithGuid, parseDocument } from './document-parser.js';
 import { flattenBundleFile } from './flatten.js';
 import { collectKnowledgeObjects, fetchKnowledge, knowledgePreview, pushKnowledge, syncGuidToFrontmatter, toPushItems, } from './knowledge-sync.js';
+import { policyWeakeningGuidance, WEAKENING_REFUSAL } from './policy/permission.js';
+import { PushPolicyGateError } from './policy/push-gate.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.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.
+ */
+export class FailedAfterImportError extends Errors.CLIError {
+    imported;
+    constructor(message, imported) {
+        super(message);
+        this.imported = imported;
+    }
+}
 /**
  * Filter document entries down to the ones the dry-run preview reports as changed,
  * used to send only the changed documents during a partial (non-`--sync`) push.
@@ -579,7 +592,9 @@ function mergeKnowledgePreview(preview, knowledge) {
  */
 export async function executePush(ctx, target, flags) {
     const { accessToken, command, inputDir, verboseFetch } = ctx;
-    const log = command.log.bind(command);
+    const log = ctx.log ?? command.log.bind(command);
+    let dryRunPreview = null;
+    const stop = (stopped) => ({ knowledge: { deleted: 0, imported: 0 }, preview: dryRunPreview, sent: [], stopped });
     // ── Collect knowledge entries (before file check so knowledge-only push works) ─
     let knowledgeObjects = [];
     if (ctx.knowledge) {
@@ -638,7 +653,7 @@ export async function executePush(ctx, target, flags) {
                 const doFlatten = await confirm('Flatten these file(s) in place and continue the push?');
                 if (!doFlatten) {
                     log('Push cancelled. Run `xano flatten <file>` yourself, or re-run to be prompted again.');
-                    return;
+                    return stop('cancelled');
                 }
             }
             else {
@@ -741,7 +756,6 @@ export async function executePush(ctx, target, flags) {
         'Content-Type': 'text/x-xanoscript',
     };
     // ── Dry-run / Preview ─────────────────────────────────────────────────
-    let dryRunPreview = null;
     const dryRunUrl = knowledgeOnly ? null : target.buildDryRunUrl(queryParams);
     if (dryRunUrl && (flags['dry-run'] || !flags.force)) {
         const dryRunParams = new URLSearchParams(queryParams);
@@ -833,7 +847,7 @@ export async function executePush(ctx, target, flags) {
                         log('');
                         log(ux.colorize('red', `Push blocked: ${criticalOps.length} critical error(s) found.`));
                         if (!flags.force) {
-                            return;
+                            return stop('blocked');
                         }
                         log(ux.colorize('yellow', 'Proceeding anyway due to --force flag.'));
                     }
@@ -863,10 +877,10 @@ export async function executePush(ctx, target, flags) {
                     if (!hasChanges && !hasLocalRecords) {
                         log('');
                         log('No changes to push.');
-                        return;
+                        return stop('no-changes');
                     }
                     if (flags['dry-run']) {
-                        return;
+                        return stop('dry-run');
                     }
                     // Warn when the sandbox currently holds a different source workspace than the one being
                     // pushed. The backend compares the source workspace id we sent against the id stored on
@@ -884,7 +898,7 @@ export async function executePush(ctx, target, flags) {
                             const proceed = await confirm('Continue with push anyway?');
                             if (!proceed) {
                                 log('Push cancelled. Run `xano sandbox reset` then retry.');
-                                return;
+                                return stop('cancelled');
                             }
                             mismatchConfirmed = true;
                         }
@@ -905,7 +919,7 @@ export async function executePush(ctx, target, flags) {
                             const confirmed = await confirm(message);
                             if (!confirmed) {
                                 log('Push cancelled.');
-                                return;
+                                return stop('cancelled');
                             }
                         }
                         else {
@@ -922,15 +936,17 @@ export async function executePush(ctx, target, flags) {
                 }
             }
             else {
-                await handleDryRunError(dryRunResponse, command, flags, target);
+                await handleDryRunError(dryRunResponse, command, target, { log, verbose: flags.verbose });
                 // If we get here, the user confirmed to proceed without preview
             }
         }
         catch (error) {
             // Ctrl+C or SIGINT
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error.name === 'AbortError' || error.code === 'ERR_USE_AFTER_CLOSE') {
                 log('\nPush cancelled.');
-                return;
+                return stop('cancelled');
             }
             // Re-throw oclif errors
             if (error instanceof Error && 'oclif' in error) {
@@ -961,16 +977,16 @@ export async function executePush(ctx, target, flags) {
         if (!hasChanges) {
             log('');
             log('No changes to push.');
-            return;
+            return stop('no-changes');
         }
         if (flags['dry-run']) {
-            return;
+            return stop('dry-run');
         }
         if (process.stdin.isTTY) {
             const confirmed = await confirm('Proceed with push?');
             if (!confirmed) {
                 log('Push cancelled.');
-                return;
+                return stop('cancelled');
             }
         }
         else {
@@ -986,17 +1002,19 @@ export async function executePush(ctx, target, flags) {
         }
     }
     // ── Partial push: filter to changed documents only ────────────────────
+    let sent = documentEntries;
     if (!knowledgeOnly && isPartial && dryRunPreview) {
-        const filteredEntries = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
-        if (filteredEntries.length === 0 && knowledgeObjects.length === 0) {
+        sent = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
+        if (sent.length === 0 && knowledgeObjects.length === 0) {
             log('No changes to push.');
-            return;
+            return stop('no-changes');
         }
-        multidoc = filteredEntries.length > 0 ? filteredEntries.map((d) => d.content).join('\n---\n') : '';
+        multidoc = sent.map((d) => d.content).join('\n---\n');
     }
     // ── Execute the actual push ───────────────────────────────────────────
     const startTime = Date.now();
     let pushedDocCount = 0;
+    let pushResponse;
     if (!knowledgeOnly && multidoc) {
         const apiUrl = target.buildPushUrl(queryParams);
         try {
@@ -1006,14 +1024,19 @@ export async function executePush(ctx, target, flags) {
                 method: 'POST',
             }, flags.verbose, accessToken);
             if (!response.ok) {
-                handlePushError(response, await response.text(), documentEntries, inputDir, command);
+                const errorText = await response.text();
+                refuseIfExplained(command, target, response.status, errorText);
+                handlePushError(response, errorText, documentEntries, inputDir, command);
             }
             // Parse response for GUID map
             const responseText = await response.text();
             let guidMap = [];
+            pushResponse = {};
             if (responseText && responseText !== 'null') {
                 try {
                     const responseJson = JSON.parse(responseText);
+                    if (responseJson && typeof responseJson === 'object')
+                        pushResponse = responseJson;
                     if (responseJson?.guid_map && Array.isArray(responseJson.guid_map)) {
                         guidMap = responseJson.guid_map;
                     }
@@ -1039,7 +1062,7 @@ export async function executePush(ctx, target, flags) {
                 let updatedCount = 0;
                 let canonicalCount = 0;
                 for (const entry of guidMap) {
-                    if (!entry.guid)
+                    if (!entry.guid || entry.type === 'policy')
                         continue;
                     const key = buildDocumentKey(entry.type, entry.name, entry.verb, entry.api_group);
                     let filePath = documentFileMap.get(key);
@@ -1085,6 +1108,8 @@ export async function executePush(ctx, target, flags) {
             pushedDocCount = multidoc.split('\n---\n').length;
         }
         catch (error) {
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
@@ -1094,6 +1119,12 @@ export async function executePush(ctx, target, flags) {
     // ── Push knowledge ────────────────────────────────────────────────────
     let knowledgeImported = 0;
     let knowledgeDeleted = 0;
+    const pushed = () => ({
+        knowledge: { deleted: knowledgeDeleted, imported: knowledgeImported },
+        preview: dryRunPreview,
+        response: pushResponse,
+        sent: pushResponse ? sent : [],
+    });
     if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
         const listUrl = ctx.knowledge.listUrl();
         try {
@@ -1131,7 +1162,10 @@ export async function executePush(ctx, target, flags) {
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
-            command.error(`Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`);
+            const message = `Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`;
+            if (pushResponse)
+                throw new FailedAfterImportError(message, pushed());
+            command.error(message);
         }
     }
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
@@ -1145,6 +1179,7 @@ export async function executePush(ctx, target, flags) {
         parts.push(kParts.join(', '));
     }
     log(`Pushed ${parts.join(' + ')} to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
+    return pushed();
 }
 // ── Error Handlers ──────────────────────────────────────────────────────────
 /**
@@ -1223,10 +1258,43 @@ function formatFailureDuration(elapsedMs) {
         ? ` (failed after ~${human}, near a common ${boundaries.find((b) => Math.abs(totalSeconds - b) <= b * 0.05)}s timeout — likely a server or proxy cutoff)`
         : ` (failed after ${human})`;
 }
-async function handleDryRunError(response, command, flags, target) {
-    const log = command.log.bind(command);
+/** Stop with the target's own guidance when it recognises this refusal. */
+function refuseIfExplained(command, target, status, body) {
+    let message = body;
+    let payload;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.message === 'string')
+            message = parsed.message;
+        payload = parsed?.payload;
+    }
+    catch {
+        // Not JSON
+    }
+    const refusal = payload;
+    if (status === 403 && refusal?.code === 'policy_gate')
+        throw new PushPolicyGateError(refusal);
+    // Policy files that weaken a mandatory policy of the live branch, from a credential without
+    // workspace:policy update: a permission refusal (exit 1), not a blocking finding. The platform's
+    // sentence already reads "Push refused: … Nothing was imported.", so it is printed as it is.
+    if (status === 403 && refusal?.code === WEAKENING_REFUSAL) {
+        command.error(`${message}${target.explainRefusal?.(status, payload) ?? policyWeakeningGuidance(payload, [], true)}`);
+    }
+    // The plan's policy cap: the platform's message names the plan, its cap and the remedy, and the
+    // 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}`);
+    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.');
+    }
+    const guidance = target.explainRefusal?.(status, payload);
+    if (guidance)
+        command.error(`Push refused (${status}): ${message}${guidance}`);
+}
+async function handleDryRunError(response, command, target, { log, verbose }) {
+    const errorText = await response.text();
+    refuseIfExplained(command, target, response.status, errorText);
     if (response.status === 404) {
-        const errorText = await response.text();
         try {
             const errorJson = JSON.parse(errorText);
             if (errorJson.message) {
@@ -1244,7 +1312,6 @@ async function handleDryRunError(response, command, flags, target) {
         log('');
     }
     else {
-        const errorText = await response.text();
         // Check if push is disabled
         try {
             const errorJson = JSON.parse(errorText);
@@ -1267,8 +1334,17 @@ async function handleDryRunError(response, command, flags, target) {
         catch {
             // Not JSON, fall through
         }
-        command.warn(`Push preview failed (${response.status}). Skipping preview.`);
-        if (flags.verbose) {
+        let reason = '';
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (typeof errorJson?.message === 'string' && errorJson.message.trim())
+                reason = `: ${errorJson.message.trim().replace(/\.$/, '')}`;
+        }
+        catch {
+            // Not JSON
+        }
+        command.warn(`Push preview failed (${response.status})${reason}. Skipping preview.`);
+        if (verbose) {
             log(ux.colorize('dim', errorText));
         }
     }

package/dist/utils/policy/catalogue.d.ts

@@ -0,0 +1,7 @@
+import type { PolicyCatalogueEntry } from './types.js';
+/**
+ * `--check` narrows the catalogue to one check. An id that is not in it names the closest matches
+ * instead of reprinting the whole list: the usual mistake is a typo one character from a real id.
+ */
+export declare function selectCatalogueCheck(checks: PolicyCatalogueEntry[], id: string): PolicyCatalogueEntry[];
+export declare function policyCatalogueSummary(checks: PolicyCatalogueEntry[]): string[];

package/dist/utils/policy/catalogue.js

@@ -0,0 +1,72 @@
+/**
+ * `--check` narrows the catalogue to one check. An id that is not in it names the closest matches
+ * instead of reprinting the whole list: the usual mistake is a typo one character from a real id.
+ */
+export function selectCatalogueCheck(checks, id) {
+    const wanted = id.trim().toLowerCase();
+    const exact = checks.filter(check => check.id.toLowerCase() === wanted);
+    if (exact.length > 0)
+        return exact;
+    const near = checks.map(check => check.id).filter(known => {
+        const lower = known.toLowerCase();
+        return lower.includes(wanted) || wanted.includes(lower) || editDistanceWithin(lower, wanted, 2);
+    }).sort();
+    throw new Error(`"${id}" is not a policy check.${near.length > 0
+        ? ` Did you mean ${near.join(', ')}?`
+        : ' Run `xano policy catalogue` for the full list.'}`);
+}
+/** Cheap bounded Levenshtein: true when `a` and `b` are at most `max` edits apart. */
+function editDistanceWithin(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return false;
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = a[i - 1] === b[j - 1]
+                ? previous[j - 1]
+                : 1 + Math.min(previous[j - 1], previous[j], current[j - 1]);
+        }
+        if (Math.min(...current) > max)
+            return false;
+        previous = current;
+    }
+    return previous[b.length] <= max;
+}
+export function policyCatalogueSummary(checks) {
+    if (checks.length === 0)
+        return ['No policy checks found.'];
+    const rows = [
+        ['Check ID', 'Label / Description', 'Object kinds', 'Required params'],
+        ...checks.map(check => [
+            check.id,
+            [check.label.trim(), check.description, check.fix_hint && `Fix hint: ${check.fix_hint}`].filter(Boolean).join('\n'),
+            (check.object_kinds ?? []).join(', ') || '—',
+            requiredParams(check),
+        ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.min([36, 46, 24, 32][column], Math.max(...rows.map(row => row[column].length))));
+    return rows.flatMap(row => {
+        const cells = row.map((cell, column) => cell.split('\n').flatMap(paragraph => {
+            const lines = [''];
+            for (const word of paragraph.split(/\s+/)) {
+                const last = lines.length - 1;
+                if (lines[last] && lines[last].length + word.length + 1 > widths[column])
+                    lines.push(word);
+                else
+                    lines[last] += `${lines[last] ? ' ' : ''}${word}`;
+            }
+            return lines;
+        }));
+        return Array.from({ length: Math.max(...cells.map(cell => cell.length)) }, (_, line) => cells.map((cell, column) => (cell[line] ?? '').padEnd(widths[column])).join('  ').trimEnd());
+    });
+}
+/** The params a rule must set: each required one, and any "one of" group. */
+function requiredParams(check) {
+    const required = Object.entries(check.params ?? {}).filter(([, schema]) => schema.required)
+        .map(([name, schema]) => `${name}: ${schema.type ?? 'any'}`);
+    const oneOf = check.requires_one_of ?? [];
+    if (oneOf.length > 0)
+        required.push(`one of: ${oneOf.join(' | ')}`);
+    return required.join(', ') || 'none';
+}

package/dist/utils/policy/errors.d.ts

@@ -0,0 +1,12 @@
+/** Guidance appended to a refusal whose `payload.code` the CLI has advice for, or `''`. */
+export declare function policyCodeGuidance(payload: unknown): string;
+/** A failed policy-route response: one message to print, and the refusal's payload. */
+export interface PolicyError {
+    message: string;
+    payload?: unknown;
+}
+/**
+ * A failed policy-route response as one message: the platform's code and message, and where a parse
+ * error is. Traces are dropped, and an empty 404 names the branch the request selected.
+ */
+export declare function describePolicyError(text: string, status: number, requestUrl: string): PolicyError;