@xano/cli 1.3.0 → 1.3.1-beta.0

package/dist/commands/branch/set_live/index.js

@@ -1,5 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import BaseCommand from '../../../base-command.js';
+import { BLANK_POLICY_OVERRIDE, blankPolicyOverride, gateOverrideHint, gateRefusal, liveGateLines, quoted, weakeningRefusal, } from '../../../utils/policy/gate.js';
+import { policyWeakeningGuidance } from '../../../utils/policy/permission.js';
 export default class BranchSetLive extends BaseCommand {
     static args = {
         branch_label: Args.string({
@@ -7,7 +9,7 @@ export default class BranchSetLive extends BaseCommand {
             required: true,
         }),
     };
-    static description = '[IMPORTANT] ALWAYS confirm with the user before changing the live branch. Sets a branch as the live (active) branch for API requests.';
+    static description = '[IMPORTANT] ALWAYS confirm with the user before changing the live branch. Sets a branch as the live (active) branch for API requests. The set-live policy gate checks the branch against its own policies, which live will have once it is set live: when blocking findings refuse it, the command exits 2 unless --policy-override gives a reason. A branch that weakens a mandatory policy of the live branch needs workspace:policy update; without it the command exits 1.';
     static examples = [
         `$ xano branch set-live staging
 Are you sure you want to set 'staging' as the live branch? (y/N) y
@@ -24,6 +26,7 @@ Branch 'v1' is now live
   "live": true
 }
 `,
+        `$ xano branch set_live rollback --force --policy-override "Rollback approved; finding tracked in JIRA-12"`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -40,14 +43,27 @@ Branch 'v1' is now live
             options: ['summary', 'json'],
             required: false,
         }),
+        'policy-override': Flags.string({ description: 'Set the branch live past a blocking set-live policy gate with an audited reason (requires workspace:policy update)' }),
         workspace: Flags.integer({
             char: 'w',
             description: 'Workspace ID (uses profile workspace if not provided)',
             required: false,
         }),
     };
+    /** Set once the platform refuses for a weakened mandatory policy: already explained, it exits 1 as it is. */
+    refusedByPermission = false;
+    /** Set once the set-live policy gate refuses, the one failure that exits 2. */
+    refusedByPolicyGate = false;
+    /** Exit 2 is the set-live gate's refusal; every other failure, flag errors included, exits 1. */
+    async catch(error) {
+        if (this.refusedByPolicyGate)
+            return super.catch(error);
+        return this.catchAsOperational(error);
+    }
     async run() {
         const { args, flags } = await this.parse(BranchSetLive);
+        if (blankPolicyOverride(flags['policy-override']))
+            this.error(BLANK_POLICY_OVERRIDE);
         const { profile } = this.resolveProfile(flags);
         // Get workspace ID from flag or profile
         const workspaceId = flags.workspace || profile.workspace;
@@ -66,16 +82,26 @@ Branch 'v1' is now live
         }
         // Construct the API URL
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/branch/${encodeURIComponent(branchLabel)}/live`;
+        // A reason from someone with workspace:policy update sets the branch live past a blocking gate.
+        const overrideReason = flags['policy-override']?.trim();
         // Set branch as live via the API
         try {
             const response = await this.verboseFetch(apiUrl, {
+                ...(overrideReason ? { body: JSON.stringify({ override_reason: overrideReason }) } : {}),
                 headers: {
                     'accept': 'application/json',
                     'Authorization': `Bearer ${profile.access_token}`,
+                    ...(overrideReason ? { 'Content-Type': 'application/json' } : {}),
                 },
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
+                const refused = await gateRefusal(response);
+                if (refused)
+                    this.refuseSetLive(refused, flags, branchLabel);
+                const weakening = await weakeningRefusal(response);
+                if (weakening)
+                    this.refuseWeakening(weakening, flags, branchLabel);
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
@@ -89,6 +115,8 @@ Branch 'v1' is now live
             }
         }
         catch (error) {
+            if (this.refusedByPolicyGate || this.refusedByPermission)
+                throw error;
             if (error instanceof Error) {
                 this.error(`Failed to set branch as live: ${error.message}`);
             }
@@ -111,4 +139,35 @@ Branch 'v1' is now live
             });
         });
     }
+    /**
+     * The set-live gate refused: the verdict on stdout (under `-o json`, `{set_live: false, message,
+     * policy_gate}`), then the platform's message and how to proceed, exiting 2.
+     */
+    refuseSetLive(refused, flags, branchLabel) {
+        if (flags.output === 'json') {
+            this.log(JSON.stringify({ message: refused.message, policy_gate: refused.answer, set_live: false }, null, 2));
+        }
+        else {
+            for (const line of liveGateLines(refused.answer, 'branch'))
+                this.log(line);
+        }
+        const workspace = flags.workspace ? ` -w ${flags.workspace}` : '';
+        const hint = gateOverrideHint(refused.answer, `xano branch set_live ${quoted(branchLabel)}${workspace} --policy-override "<why>"`);
+        this.refusedByPolicyGate = true;
+        this.error(`${refused.message}${hint}`, { exit: 2 });
+    }
+    /**
+     * The branch weakens a mandatory policy of the live branch (or lacks one), and the credential lacks
+     * `workspace:policy` update. That is a permission refusal, not a blocking finding: it exits 1 (under
+     * `-o json` as `{error}`) with the platform's sentence and how to go on. The live branch is unchanged.
+     */
+    refuseWeakening(refused, flags, branchLabel) {
+        const workspace = flags.workspace ? ` -w ${flags.workspace}` : '';
+        this.refusedByPermission = true;
+        const again = `xano branch set_live ${quoted(branchLabel)}${workspace}`;
+        const way = refused.payload.unavailable === true
+            ? `The check may read them next time: ${again}`
+            : `To set it live yourself, give ${quoted(branchLabel)} the live branch's version of those policies, then run: ${again}`;
+        this.error(`${refused.message}${policyWeakeningGuidance(refused.payload, [way], true)}`);
+    }
 }

package/dist/commands/ephemeral/push/index.js

@@ -4,6 +4,7 @@ import { resolve } from 'node:path';
 import BaseCommand from '../../../base-command.js';
 import { isAwaited, waitForMicroservices, } from '../../../utils/microservice-wait.js';
 import { executePush } from '../../../utils/multidoc-push.js';
+import { policiesSkippedNotice } from '../../../utils/policy/feedback.js';
 /** Status glyph for one microservice row in the `--wait` progress block. */
 const icon = (e) => {
     if (!isAwaited(e))
@@ -168,13 +169,17 @@ Skip preview and push immediately
             truncate: flags.truncate,
             verbose: flags.verbose,
         };
-        await executePush({
+        const result = await executePush({
             accessToken: profile.access_token,
             branch: '',
             command: this,
             inputDir,
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
+        // When the platform leaves policy files out, it says so once.
+        const skipped = policiesSkippedNotice(result.response ?? result.preview);
+        if (skipped)
+            this.warn(skipped);
         // --wait: after a real push, poll the tenant's live microservice status until
         // every auto-deployed microservice (tenant_deploy="auto") is ready or the
         // wait times out. Skipped on --dry-run (nothing was deployed).

package/dist/commands/function/create/index.d.ts

@@ -7,13 +7,28 @@ export default class FunctionCreate extends BaseCommand {
         edit: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'policy-override': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    private refusedByPolicyGate;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     run(): Promise<void>;
     private editFile;
     private readStdin;
+    /**
+     * The live-branch publish gate refused the new function: the verdict on stdout (under `-o json`,
+     * `{created: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    private refusePublish;
 }

package/dist/commands/function/create/index.js

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import path from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { BLANK_POLICY_OVERRIDE, blankPolicyOverride, gateRefusal, publishRefusal, quoted } from '../../../utils/policy/gate.js';
 export default class FunctionCreate extends BaseCommand {
     static args = {};
     static description = 'Create a new function in a workspace';
@@ -36,6 +37,7 @@ Name: my_function
   ...
 }
 `,
+        `$ xano function:create -f function.xs --policy-override "Exception approved; finding tracked in JIRA-12"`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -59,6 +61,7 @@ Name: my_function
             options: ['summary', 'json'],
             required: false,
         }),
+        'policy-override': Flags.string({ description: 'Create the function past a blocking live-branch publish policy gate with an audited reason (requires workspace:policy update)' }),
         stdin: Flags.boolean({
             char: 's',
             default: false,
@@ -72,8 +75,18 @@ Name: my_function
             required: false,
         }),
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    refusedByPolicyGate = false;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    async catch(error) {
+        if (this.refusedByPolicyGate)
+            return super.catch(error);
+        return this.catchAsOperational(error);
+    }
     async run() {
         const { flags } = await this.parse(FunctionCreate);
+        if (blankPolicyOverride(flags['policy-override']))
+            this.error(BLANK_POLICY_OVERRIDE);
         const { profile, profileName } = this.resolveProfile(flags);
         // Determine workspace_id from flag or profile
         let workspaceId;
@@ -133,6 +146,10 @@ Name: my_function
         const queryParams = new URLSearchParams({
             include_xanoscript: 'false',
         });
+        // A reason from someone with workspace:policy update saves past a blocking publish gate.
+        const overrideReason = flags['policy-override']?.trim();
+        if (overrideReason)
+            queryParams.set('override_reason', overrideReason);
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/function?${queryParams.toString()}`;
         // Create function via API
         try {
@@ -146,6 +163,9 @@ Name: my_function
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
+                const refused = await gateRefusal(response);
+                if (refused)
+                    this.refusePublish(refused, flags);
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
@@ -166,6 +186,8 @@ Name: my_function
             }
         }
         catch (error) {
+            if (this.refusedByPolicyGate)
+                throw error;
             if (error instanceof Error) {
                 this.error(`Failed to create function: ${error.message}`);
             }
@@ -239,4 +261,22 @@ Name: my_function
             process.stdin.resume();
         });
     }
+    /**
+     * The live-branch publish gate refused the new function: the verdict on stdout (under `-o json`,
+     * `{created: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    refusePublish(refused, flags) {
+        const workspace = flags.workspace ? ` -w ${quoted(flags.workspace)}` : '';
+        const source = flags.file ? ` -f ${quoted(flags.file)}` : ' --stdin';
+        const { lines, message } = publishRefusal(refused, {
+            json: flags.output === 'json',
+            outcome: 'created',
+            rerun: `xano function create${workspace}${source} --policy-override "<why>"`,
+        });
+        for (const line of lines)
+            this.log(line);
+        this.refusedByPolicyGate = true;
+        this.error(message, { exit: 2 });
+    }
 }

package/dist/commands/function/edit/index.d.ts

@@ -9,6 +9,7 @@ export default class FunctionEdit extends BaseCommand {
         edit: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'policy-override': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         publish: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -16,10 +17,24 @@ export default class FunctionEdit extends BaseCommand {
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    private refusedByPolicyGate;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    protected catch(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
     run(): Promise<void>;
     private editFile;
     private editFunctionContent;
     private fetchFunctionCode;
     private promptForFunctionId;
     private readStdin;
+    /**
+     * The live-branch publish gate refused the update: the verdict on stdout (under `-o json`,
+     * `{updated: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    private refusePublish;
 }

package/dist/commands/function/edit/index.js

@@ -5,6 +5,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import path from 'node:path';
 import BaseCommand, { buildUserAgent } from '../../../base-command.js';
+import { BLANK_POLICY_OVERRIDE, blankPolicyOverride, gateRefusal, publishRefusal, quoted } from '../../../utils/policy/gate.js';
 export default class FunctionEdit extends BaseCommand {
     static args = {
         function_id: Args.string({
@@ -59,6 +60,7 @@ Name: my_function
   ...
 }
 `,
+        `$ xano function:edit 163 -f function.xs --policy-override "Exception approved; finding tracked in JIRA-12"`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -81,6 +83,7 @@ Name: my_function
             options: ['summary', 'json'],
             required: false,
         }),
+        'policy-override': Flags.string({ description: 'Publish past a blocking live-branch publish policy gate with an audited reason (requires workspace:policy update)' }),
         publish: Flags.boolean({
             default: true,
             description: 'Publish the function after editing',
@@ -99,8 +102,18 @@ Name: my_function
             required: false,
         }),
     };
+    /** Set once the publish policy gate refuses, the one failure that exits 2. */
+    refusedByPolicyGate = false;
+    /** Exit 2 is the publish gate's refusal; every other failure, flag errors included, exits 1. */
+    async catch(error) {
+        if (this.refusedByPolicyGate)
+            return super.catch(error);
+        return this.catchAsOperational(error);
+    }
     async run() {
         const { args, flags } = await this.parse(FunctionEdit);
+        if (blankPolicyOverride(flags['policy-override']))
+            this.error(BLANK_POLICY_OVERRIDE);
         const { profile, profileName } = this.resolveProfile(flags);
         // Validate flag combinations
         if (flags.edit && !flags.file) {
@@ -175,6 +188,10 @@ Name: my_function
             include_xanoscript: 'false',
             publish: flags.publish ? 'true' : 'false',
         });
+        // A reason from someone with workspace:policy update publishes past a blocking publish gate.
+        const overrideReason = flags['policy-override']?.trim();
+        if (overrideReason)
+            queryParams.set('override_reason', overrideReason);
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/function/${functionId}?${queryParams.toString()}`;
         // Update function via API
         try {
@@ -188,6 +205,9 @@ Name: my_function
                 method: 'PUT',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
+                const refused = await gateRefusal(response);
+                if (refused)
+                    this.refusePublish(refused, flags, functionId);
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
@@ -208,6 +228,8 @@ Name: my_function
             }
         }
         catch (error) {
+            if (this.refusedByPolicyGate)
+                throw error;
             if (error instanceof Error) {
                 this.error(`Failed to update function: ${error.message}`);
             }
@@ -428,4 +450,22 @@ Name: my_function
             process.stdin.resume();
         });
     }
+    /**
+     * The live-branch publish gate refused the update: the verdict on stdout (under `-o json`,
+     * `{updated: false, message, policy_gate}`), then the platform's message and how to proceed,
+     * exiting 2.
+     */
+    refusePublish(refused, flags, functionId) {
+        const workspace = flags.workspace ? ` -w ${quoted(flags.workspace)}` : '';
+        const source = flags.file ? ` -f ${quoted(flags.file)}` : flags.stdin ? ' --stdin' : '';
+        const { lines, message } = publishRefusal(refused, {
+            json: flags.output === 'json',
+            outcome: 'updated',
+            rerun: `xano function edit ${quoted(functionId)}${workspace}${source} --policy-override "<why>"`,
+        });
+        for (const line of lines)
+            this.log(line);
+        this.refusedByPolicyGate = true;
+        this.error(message, { exit: 2 });
+    }
 }

package/dist/commands/policy/catalogue/index.d.ts

@@ -0,0 +1,15 @@
+import PolicyCommand from '../../../policy-command.js';
+export default class PolicyCatalogue extends PolicyCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        check: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, 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>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/policy/catalogue/index.js

@@ -0,0 +1,29 @@
+import { Flags } from '@oclif/core';
+import PolicyCommand from '../../../policy-command.js';
+import { policyCatalogueSummary, selectCatalogueCheck } from '../../../utils/policy/catalogue.js';
+import { listItems } from '../../../utils/policy/request.js';
+export default class PolicyCatalogue extends PolicyCommand {
+    static description = 'List built-in policy checks and their parameter schemas';
+    static examples = ['$ xano policy catalogue -o json', '$ xano policy catalogue --check object.auth_required'];
+    static flags = {
+        ...PolicyCommand.policyFlags,
+        check: Flags.string({ description: 'Show only this check id (an unknown id names the closest matches)' }),
+    };
+    async run() {
+        const { flags } = await this.parse(PolicyCatalogue);
+        const { request } = this.policyTarget(flags);
+        const result = await request('/check');
+        if (flags.check) {
+            // `--check` narrows both output modes, so `-o json` stays pipeable for one check too.
+            const selected = selectCatalogueCheck(listItems(result), flags.check);
+            this.log(flags.output === 'json' ? JSON.stringify(selected, null, 2) : policyCatalogueSummary(selected).join('\n'));
+        }
+        else if (flags.output === 'json') {
+            this.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            for (const line of policyCatalogueSummary(listItems(result)))
+                this.log(line);
+        }
+    }
+}

package/dist/commands/policy/create/index.d.ts

@@ -0,0 +1,18 @@
+import PolicyCommand from '../../../policy-command.js';
+export default class PolicyCreate extends PolicyCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        goal: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        key: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        param: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        message: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, 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>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/policy/create/index.js

@@ -0,0 +1,39 @@
+import { Flags } from '@oclif/core';
+import PolicyCommand from '../../../policy-command.js';
+import { policyFromGoal } from '../../../utils/policy/goal.js';
+import { listAllPolicies } from '../../../utils/policy/request.js';
+export default class PolicyCreate extends PolicyCommand {
+    static description = 'Create an independent policy from a platform goal';
+    static examples = [
+        '$ xano policy create --goal endpoints_need_login -b dev',
+        `$ xano policy create --goal no_pii_in_responses --key DATA-020 --param 'fields=["email","ssn"]'`,
+    ];
+    static flags = {
+        ...PolicyCommand.policyFlags,
+        ...PolicyCommand.publishFlags,
+        goal: Flags.string({ description: 'Goal id from policy catalogue -o json', required: true }),
+        key: Flags.string({ description: 'New policy key (default: the goal key with a free numeric suffix if taken)' }),
+        param: Flags.string({ description: 'Parameter override: N.path=JSON, 1-based rule number; path=JSON for a single-rule goal', multiple: true }),
+    };
+    async run() {
+        const { flags } = await this.parse(PolicyCreate);
+        const target = this.policyTarget(flags);
+        const { request } = target;
+        const catalogue = await request('/check');
+        const goal = catalogue.goals?.find(item => item.id === flags.goal);
+        if (!goal)
+            this.error(`Unknown goal "${flags.goal}". Run xano policy catalogue -o json to see this instance's goals.`);
+        const keys = (await listAllPolicies(request)).map(policy => policy.key);
+        // The key is checked against the pattern this instance's catalogue serves.
+        const document = policyFromGoal(goal, keys, { key: flags.key, keyRule: catalogue.document?.key, overrides: flags.param });
+        const parsed = await this.parseSource(request, { data: document });
+        const saved = await request('', 'POST', { data: { source: parsed.source }, ...(flags.message ? { message: flags.message } : {}) });
+        if (typeof saved?.id !== 'number')
+            this.error('The platform did not return the saved policy. Check xano policy list before retrying.');
+        this.logRuleWarnings(parsed);
+        if (flags.output === 'json')
+            this.log(JSON.stringify(saved, null, 2));
+        else
+            this.log(`Created ${parsed.policy.key} (Version ${saved.version}) in ${this.where(target)}.`);
+    }
+}

package/dist/commands/policy/delete/index.d.ts

@@ -0,0 +1,19 @@
+import PolicyCommand from '../../../policy-command.js';
+export default class PolicyDelete extends PolicyCommand {
+    static args: {
+        policy: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, 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>;
+    };
+    /** `workspace push` is additive, so deleting a policy file leaves the policy in place; this removes it. */
+    run(): Promise<void>;
+}

package/dist/commands/policy/delete/index.js

@@ -0,0 +1,61 @@
+import { Args, Flags } from '@oclif/core';
+import PolicyCommand from '../../../policy-command.js';
+import { confirm } from '../../../utils/multidoc-push.js';
+import { listAllPolicies, sameKey } from '../../../utils/policy/request.js';
+export default class PolicyDelete extends PolicyCommand {
+    static args = {
+        policy: Args.string({
+            description: 'Policy key (AUTH-001) or ID to delete',
+            required: true,
+        }),
+    };
+    static description = 'Delete a policy from a branch; its Version History is kept. Deleting an active, mandatory policy also needs the workspace:policy update permission.';
+    static examples = [
+        `$ xano policy delete TMP-DX-001
+Delete policy TMP-DX-001 (ID: 922, Version 2) from workspace 3? Its Version History is kept. (y/N) y
+Deleted policy TMP-DX-001 (ID: 922) from workspace 3.
+`,
+        '$ xano policy delete 922 --force',
+        '$ xano policy delete TMP-DX-001 -w 3 --force -o json',
+    ];
+    static flags = {
+        ...PolicyCommand.policyFlags,
+        force: Flags.boolean({
+            char: 'f',
+            default: false,
+            description: '[IMPORTANT] NEVER run without explicit user confirmation. Skips the confirmation prompt.',
+        }),
+    };
+    /** `workspace push` is additive, so deleting a policy file leaves the policy in place; this removes it. */
+    async run() {
+        const { args, flags } = await this.parse(PolicyDelete);
+        const target = this.policyTarget(flags);
+        const wanted = args.policy.trim();
+        if (!wanted)
+            this.error('Provide the policy key or ID to delete.');
+        const policies = await listAllPolicies(target.request);
+        const matched = policies.find((policy) => sameKey(policy.key, wanted))
+            ?? (/^\d+$/.test(wanted) ? policies.find((policy) => policy.id === Number(wanted)) : undefined);
+        if (!matched) {
+            const known = policies.map((policy) => policy.key).sort();
+            this.error(`No policy "${wanted}" on ${this.where(target)}.${known.length > 0 ? ` This branch has: ${known.join(', ')}.` : ' This branch has no policies.'}`);
+        }
+        if (!flags.force) {
+            // Nobody can answer the prompt: refuse rather than report a cancel as success.
+            if (!process.stdin.isTTY)
+                this.error('Non-interactive environment detected. Use --force to skip confirmation.');
+            const confirmed = await confirm(`Delete policy ${matched.key} (ID: ${matched.id}, Version ${matched.version}) from ${this.where(target)}? Its Version History is kept.`);
+            if (!confirmed) {
+                this.log('Deletion cancelled.');
+                return;
+            }
+        }
+        // The policy as listed is what the prompt named: a delete of a policy changed since is refused (`policy_stale`).
+        const staleCheck = matched.updated_at ? { last_updated_at: String(matched.updated_at) } : {};
+        await target.request(`/${matched.id}`, 'DELETE', undefined, staleCheck);
+        if (flags.output === 'json')
+            this.log(JSON.stringify({ deleted: true, id: matched.id, key: matched.key }, null, 2));
+        else
+            this.log(`Deleted policy ${matched.key} (ID: ${matched.id}) from ${this.where(target)}.`);
+    }
+}

package/dist/commands/policy/evaluate/index.d.ts

@@ -0,0 +1,32 @@
+import PolicyCommand from '../../../policy-command.js';
+/** One rule's clear objects in a trial's answer: the first ones and how many there are. */
+type TrialClear = {
+    items?: Array<{
+        name?: string;
+    }>;
+    policy_key?: string;
+    rule_id?: string;
+    total?: number;
+};
+/**
+ * What a trial says it is, then each rule's clear objects: the objects it examined and found
+ * nothing on. A trial is never stored, so its answer is all there is to show.
+ */
+export declare function trialLines(key: string, clear: TrialClear[] | undefined): string[];
+export default class PolicyEvaluate extends PolicyCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        policy: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'run-detail': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        summary: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, 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>;
+    };
+    run(): Promise<void>;
+}
+export {};