@xano/cli 1.3.4 → 1.3.5-beta.1

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

@@ -0,0 +1,138 @@
+import type { ProfileConfig } from '../../base-command.js';
+import type { PolicyFinding } from './types.js';
+/** The release the tenant deploy gate judges. */
+export interface GateRelease {
+    /** Whether the release was cut with its policies; one cut without them has no check. */
+    carried?: boolean;
+    counts?: null | {
+        advisory?: number;
+        blocking?: number;
+        errors?: number;
+        findings?: number;
+    };
+    id?: number;
+    name?: string;
+    /** The release's stored policy run, 0 when it has none. */
+    run_id?: number;
+    status?: string;
+}
+/**
+ * The tenant deploy gate's answer: what `GET tenant/{name}/policy_gate` previews, and the payload of
+ * the 403 a refused deploy answers (with `code: policy_gate`). The gate judges the release alone, by
+ * its own policy check, so the same release gets the same verdict on every tenant; only `gated`
+ * differs. The findings come only to a credential that reads the workspace's policies.
+ */
+export interface PolicyGateAnswer {
+    can_override?: boolean;
+    code?: string;
+    /** The first of the release's blocking findings. */
+    findings?: PolicyFinding[];
+    /** `tenant_deploy`, or `tenant_approve` when an approval completes the deploy. */
+    gate?: string;
+    /** False for an ephemeral or sandbox tenant: the verdict is reported but never refuses. */
+    gated?: boolean;
+    message?: string;
+    override_denied?: boolean;
+    release?: GateRelease | null;
+    run_id?: number;
+    /** `pass`, `blocked`, `overridden`, `not_applicable`, `not_carried`, `disabled` or `unavailable`. */
+    status?: string;
+    /** Every blocking finding the release has, listed or not. */
+    total?: number;
+    truncated?: boolean;
+}
+/**
+ * A gate that measures a change against the live branch (set-live, publish, a live-branch save): its
+ * blocking findings split by why they block.
+ */
+export interface LiveGateAnswer extends Omit<PolicyGateAnswer, 'gated' | 'release'> {
+    changed?: number;
+    existing?: number;
+    introduced?: number;
+}
+/** The refusal code a policy gate's 403 carries in `payload.code`. */
+export declare const GATE_REFUSAL = "policy_gate";
+/** 2 when the gate refuses this deploy (blocked on a gated tenant); every other verdict is 0. */
+export declare function gateExitCode(answer?: null | PolicyGateAnswer): number;
+/**
+ * The gate's verdict on stdout: a headline with its sentence, the release it judged, how many of its
+ * findings block, and the first of them. Every blocking finding of the release counts, whatever the
+ * tenant runs today.
+ */
+export declare function gateLines(answer: PolicyGateAnswer): string[];
+/**
+ * The line a completed deploy prints about its gate. A blocked verdict on an ephemeral or sandbox
+ * tenant refused nothing (the deploy went ahead), so it says so rather than reading as a failure.
+ */
+export declare function deployedGateLine(answer: PolicyGateAnswer): string;
+/**
+ * The verdict of a gate that measures a change against the live branch (set-live, publish): its
+ * status, what blocks, and the first blocking findings. `subject` is what changes: a branch set live,
+ * the branch a release was deployed as (`release deploy --set_live`), or an object saved to live.
+ */
+export declare function liveGateLines(answer: LiveGateAnswer, subject: 'branch' | 'release' | 'save'): string[];
+/**
+ * A save the live-branch publish gate refused (`function create`, `function edit`): what goes on
+ * stdout (the verdict, or under `-o json` `{created|updated: false, message, policy_gate}`) and the
+ * error the command exits 2 with, saying nothing was saved and how to proceed (`rerun` is the same
+ * command with `--policy-override`).
+ */
+export declare function publishRefusal(refused: GateRefused, options: {
+    json: boolean;
+    outcome: 'created' | 'updated';
+    rerun: string;
+}): {
+    lines: string[];
+    message: string;
+};
+/** The refusal of a `--policy-override` given without a reason, before any request is made. */
+export declare const BLANK_POLICY_OVERRIDE = "--policy-override needs a reason: say why this change may proceed past the policy gate.";
+/** True when `--policy-override` was given but holds only whitespace. */
+export declare function blankPolicyOverride(reason?: string): boolean;
+/** A value quoted for the shell when it needs it. */
+export declare function quoted(value: string): string;
+/**
+ * What to do about a refusal: override it (the credential may, and `command` is how), or ask for
+ * the permission. A refusal whose override was denied already says so in its message.
+ */
+export declare function gateOverrideHint(answer: PolicyGateAnswer, command: string): string;
+/** A deploy the policy gate refused: the platform's sentence and the gate's answer. */
+export interface GateRefused {
+    answer: PolicyGateAnswer;
+    message: string;
+}
+/**
+ * What a command the gate refused prints on stdout: the verdict, or under `-o json` the refusal as
+ * `{deployed: false, message, policy_gate}`. The command then exits 2 with the message.
+ */
+export declare function gateRefusalOutput(refused: GateRefused, json: boolean): string[];
+/** A policy gate's refusal read from a failed response: its message and answer, or `null` for any other failure. */
+export declare function gateRefusal(response: Response): Promise<GateRefused | null>;
+/** What a gate preview needs from the command that asks for it. */
+export interface GateHost {
+    verboseFetch(url: string, options: RequestInit, verbose: boolean, authToken?: string): Promise<Response>;
+}
+/** A preview the platform could not answer: the HTTP status, its message and the refusal's payload. */
+export interface GateUnavailable {
+    message: string;
+    payload?: unknown;
+    status: number;
+}
+/**
+ * `GET workspace/{ws}/tenant/{tenant}/policy_gate?release_name=`: what the gate would decide for the
+ * release on the tenant, without deploying. A refusal (the Policies feature is off, the credential
+ * cannot read policies, no such tenant or release) is answered as `unavailable` rather than thrown.
+ */
+export declare function fetchPolicyGate(host: GateHost, target: {
+    profile: ProfileConfig;
+    release: string;
+    tenant: string;
+    verbose: boolean;
+    workspace: string;
+}): Promise<{
+    answer: PolicyGateAnswer;
+} | {
+    unavailable: GateUnavailable;
+}>;
+/** Why a preview is not available, in a few words for a line that must not fail its command. */
+export declare function unavailableReason(unavailable: GateUnavailable): string;

package/dist/utils/policy/gate.js

@@ -0,0 +1,193 @@
+import { describePolicyError } from './errors.js';
+import { findingLine } from './findings.js';
+/** The refusal code a policy gate's 403 carries in `payload.code`. */
+export const GATE_REFUSAL = 'policy_gate';
+/** 2 when the gate refuses this deploy (blocked on a gated tenant); every other verdict is 0. */
+export function gateExitCode(answer) {
+    return answer?.status === 'blocked' && answer.gated !== false ? 2 : 0;
+}
+function releaseLine(release, status) {
+    if (!release)
+        return '  Release: unknown';
+    const name = release.name?.trim() || (release.id ? `#${release.id}` : 'unknown');
+    const detail = status === 'not_carried' || release.status === 'not_carried'
+        ? 'cut without its policies'
+        : [release.run_id ? `policy run ${release.run_id}` : '', release.status ?? ''].filter(Boolean).join(', ');
+    return `  Release: ${name}${detail ? ` (${detail})` : ''}`;
+}
+/** The first of the release's blocking findings, and where the rest of its findings are. */
+function findingLines(answer) {
+    const findings = answer.findings ?? [];
+    if (findings.length === 0) {
+        const withheld = answer.findings === undefined && (answer.total ?? 0) > 0;
+        return withheld ? ['  The findings are listed only for a credential that reads policies (workspace:policy read).'] : [];
+    }
+    const total = answer.total ?? findings.length;
+    const releaseName = answer.release?.name?.trim();
+    return [
+        `  Blocking findings (${total > findings.length ? `first ${findings.length} of ${total}` : findings.length}):`,
+        ...findings.map(finding => `  ${findingLine(finding, new Map())}`),
+        ...(releaseName ? [`  Every finding of the release: xano policy runs --release ${quoted(releaseName)}`] : []),
+    ];
+}
+/**
+ * The gate's verdict on stdout: a headline with its sentence, the release it judged, how many of its
+ * findings block, and the first of them. Every blocking finding of the release counts, whatever the
+ * tenant runs today.
+ */
+export function gateLines(answer) {
+    const status = answer.status?.trim() || 'unknown';
+    const lines = [`Policy gate: ${status}`];
+    if (answer.message?.trim())
+        lines.push(`  ${answer.message.trim()}`);
+    if (answer.release !== undefined)
+        lines.push(releaseLine(answer.release, status));
+    // Listed findings carry their own count; otherwise say how many there are.
+    if (['blocked', 'overridden', 'pass'].includes(status) && typeof answer.total === 'number' && (answer.findings ?? []).length === 0) {
+        lines.push(`  Blocking findings in this release: ${answer.total}`);
+    }
+    lines.push(...findingLines(answer));
+    if (answer.gated === false)
+        lines.push('  Not gated: this tenant is ephemeral or a sandbox, so the verdict never refuses a deploy to it.');
+    return lines;
+}
+/**
+ * The line a completed deploy prints about its gate. A blocked verdict on an ephemeral or sandbox
+ * tenant refused nothing (the deploy went ahead), so it says so rather than reading as a failure.
+ */
+export function deployedGateLine(answer) {
+    const status = answer.status?.trim() || 'unknown';
+    return status === 'blocked' && answer.gated === false
+        ? 'Policy gate: blocked (not gated: this tenant is ephemeral or a sandbox, so the deploy went ahead)'
+        : `Policy gate: ${status}`;
+}
+/**
+ * The verdict of a gate that measures a change against the live branch (set-live, publish): its
+ * status, what blocks, and the first blocking findings. `subject` is what changes: a branch set live,
+ * the branch a release was deployed as (`release deploy --set_live`), or an object saved to live.
+ */
+export function liveGateLines(answer, subject) {
+    const lines = [`Policy gate: ${answer.status?.trim() || 'unknown'}`];
+    if (typeof answer.total === 'number') {
+        lines.push(`  Blocking findings: ${answer.total} (${answer.introduced ?? 0} introduced, ${answer.changed ?? 0} on objects the ${subject} changes); ${answer.existing ?? 0} already on the live branch never block`);
+    }
+    const findings = answer.findings ?? [];
+    if (findings.length > 0) {
+        lines.push(...findings.map(finding => `  ${findingLine(finding, new Map())}`));
+        if (answer.truncated)
+            lines.push('  Only the first findings are listed.');
+    }
+    else if (answer.findings === undefined && (answer.total ?? 0) > 0) {
+        lines.push('  The findings are listed only for a credential that reads policies (workspace:policy read).');
+    }
+    return lines;
+}
+/**
+ * A save the live-branch publish gate refused (`function create`, `function edit`): what goes on
+ * stdout (the verdict, or under `-o json` `{created|updated: false, message, policy_gate}`) and the
+ * error the command exits 2 with, saying nothing was saved and how to proceed (`rerun` is the same
+ * command with `--policy-override`).
+ */
+export function publishRefusal(refused, options) {
+    const lines = options.json
+        ? [JSON.stringify({ message: refused.message, [options.outcome]: false, policy_gate: refused.answer }, null, 2)]
+        : liveGateLines(refused.answer, 'save');
+    return { lines, message: `Nothing was saved. ${refused.message}${gateOverrideHint(refused.answer, options.rerun)}` };
+}
+/** The refusal of a `--policy-override` given without a reason, before any request is made. */
+export const BLANK_POLICY_OVERRIDE = '--policy-override needs a reason: say why this change may proceed past the policy gate.';
+/** True when `--policy-override` was given but holds only whitespace. */
+export function blankPolicyOverride(reason) {
+    return reason !== undefined && !reason.trim();
+}
+/** A value quoted for the shell when it needs it. */
+export function quoted(value) {
+    return /^[\w.@%+=:,/-]+$/.test(value) ? value : `"${value.replaceAll(/(["\\$`])/g, String.raw `\$1`)}"`;
+}
+/**
+ * What to do about a refusal: override it (the credential may, and `command` is how), or ask for
+ * the permission. A refusal whose override was denied already says so in its message.
+ */
+export function gateOverrideHint(answer, command) {
+    if (answer.override_denied)
+        return '';
+    if (answer.can_override)
+        return `\nTo proceed past the policy gate with a reason (audited): ${command}`;
+    return '\nOverriding the policy gate needs the `workspace:policy` update permission; ask someone who has it.';
+}
+/**
+ * What a command the gate refused prints on stdout: the verdict, or under `-o json` the refusal as
+ * `{deployed: false, message, policy_gate}`. The command then exits 2 with the message.
+ */
+export function gateRefusalOutput(refused, json) {
+    return json
+        ? [JSON.stringify({ deployed: false, message: refused.message, policy_gate: refused.answer }, null, 2)]
+        : gateLines(refused.answer);
+}
+/** A 403 whose `payload.code` is `code`: its trimmed message (`''` for none) and payload, or `null` for any other failure. The body is left unread. */
+async function coded403(response, code) {
+    if (response.status !== 403)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(await response.clone().text());
+    }
+    catch {
+        return null;
+    }
+    const payload = body && typeof body === 'object' ? body.payload : undefined;
+    if (!payload || typeof payload !== 'object' || payload.code !== code)
+        return null;
+    const { message } = body;
+    return { message: typeof message === 'string' ? message.trim() : '', payload: payload };
+}
+/** A policy gate's refusal read from a failed response: its message and answer, or `null` for any other failure. */
+export async function gateRefusal(response) {
+    const refused = await coded403(response, GATE_REFUSAL);
+    if (!refused)
+        return null;
+    const answer = refused.payload;
+    return { answer, message: refused.message || (answer.message ?? 'Refused by the policy gate.') };
+}
+/**
+ * `GET workspace/{ws}/tenant/{tenant}/policy_gate?release_name=`: what the gate would decide for the
+ * release on the tenant, without deploying. A refusal (the Policies feature is off, the credential
+ * cannot read policies, no such tenant or release) is answered as `unavailable` rather than thrown.
+ */
+export async function fetchPolicyGate(host, target) {
+    const { profile, release, tenant, verbose, workspace } = target;
+    const query = new URLSearchParams({ release_name: release });
+    const url = `${profile.instance_origin}/api:meta/workspace/${workspace}/tenant/${encodeURIComponent(tenant)}/policy_gate?${query}`;
+    const response = await host.verboseFetch(url, { headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` }, method: 'GET' }, verbose, profile.access_token);
+    const text = (await response.text()).replaceAll(profile.access_token, '[REDACTED]');
+    if (!response.ok) {
+        const { message, payload } = describePolicyError(text, response.status, url);
+        return { unavailable: { message, payload, status: response.status } };
+    }
+    try {
+        return { answer: JSON.parse(text) };
+    }
+    catch {
+        return { unavailable: { message: `The policy gate answered a ${response.status} that is not JSON.`, status: response.status } };
+    }
+}
+/** Why a preview is not available, in a few words for a line that must not fail its command. */
+export function unavailableReason(unavailable) {
+    const code = unavailable.payload && typeof unavailable.payload === 'object' ? unavailable.payload.code : undefined;
+    switch (code) {
+        case 'policy_feature_disabled': {
+            return 'the Policies feature is off on this instance';
+        }
+        case 'policy_permission_required': {
+            return 'your role lacks the `workspace:policy` read permission';
+        }
+        case 'policy_scope_required': {
+            return 'this Metadata API token lacks the `workspace:policy` scope';
+        }
+        default: {
+            if (unavailable.status === 401)
+                return 'the Metadata API token was not accepted';
+            return unavailable.message.replace(/^[a-z_]+: /i, '') || `the server answered ${unavailable.status}`;
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+/** Guidance appended to a refused policy request, given the HTTP status and the refusal's payload. */
+export declare function policyPermissionGuidance(status: number, payload: unknown): string;
+/**
+ * Guidance for a `workspace push` (or its preview) refused because it would change policies, or
+ * `undefined` for any other refusal.
+ */
+export declare function policyFilePushGuidance(payload: unknown): string | undefined;

package/dist/utils/policy/permission.js

@@ -0,0 +1,55 @@
+const TOKEN_SETTINGS = 'Instance settings → Metadata API & MCP Server → Manage Access Tokens';
+function refusalOf(payload) {
+    return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
+}
+/** `workspace:policy create`, or just `workspace:policy` when the refusal names no level. */
+function permissionAt(refusal) {
+    return `\`workspace:policy\`${typeof refusal.level === 'string' && refusal.level ? ` ${refusal.level}` : ''}`;
+}
+/** Guidance appended to a refused policy request, given the HTTP status and the refusal's payload. */
+export function policyPermissionGuidance(status, payload) {
+    if (status === 401) {
+        return `\nThe Metadata API token was not accepted: it is missing, expired or revoked. Check the active profile (xano profile list) or create a new token: ${TOKEN_SETTINGS}.`;
+    }
+    const refusal = refusalOf(payload);
+    switch (refusal.code) {
+        case 'policy_feature_disabled': {
+            return '\nThe Policies feature is turned off for this instance, so no token or permission can reach it. Ask your Xano contact to enable Policies.';
+        }
+        case 'policy_object_permission_required': {
+            const permission = typeof refusal.permission === 'string' && refusal.permission ? `\`${refusal.permission}\` read` : 'read';
+            // The platform raises this code for a role (or its per-workspace override) and for a Metadata API
+            // token whose scope map lacks the permission alike, so the remedy names both.
+            return `\nYour role or this token lacks the ${permission} permission for this object. An instance admin grants it to your role; a Metadata API token needs that scope, so create one that has it: ${TOKEN_SETTINGS}. An object's policy coverage needs only that, not \`workspace:policy\`.`;
+        }
+        case 'policy_permission_required': {
+            return `\nYour role on this workspace lacks the ${permissionAt(refusal)} permission. Your token is fine — reissuing it will not help. Ask an instance admin to grant it.${refusal.level === 'read' ? '' : ' Reading policies and running checks need only read.'}`;
+        }
+        case 'policy_scope_required': {
+            return `\nThis Metadata API token was created without the ${permissionAt(refusal)} scope. Create a token that has it: ${TOKEN_SETTINGS}.`;
+        }
+        default: {
+            return '';
+        }
+    }
+}
+/**
+ * Guidance for a `workspace push` (or its preview) refused because it would change policies, or
+ * `undefined` for any other refusal.
+ */
+export function policyFilePushGuidance(payload) {
+    const refusal = refusalOf(payload);
+    if (!Array.isArray(refusal.policies) || refusal.policies.length === 0)
+        return undefined;
+    const remedy = {
+        policy_permission_required: '\n  - To change a policy, ask someone with that permission to push it or to run xano policy publish.',
+        policy_scope_required: `\n  - To change a policy yourself, create a token with that scope: ${TOKEN_SETTINGS}.`,
+    }[String(refusal.code)];
+    if (!remedy)
+        return undefined;
+    return (`\nThis push contains policy files that differ from the policies on the branch, and changing them needs the ${permissionAt(refusal)} ${refusal.code === 'policy_scope_required' ? 'scope on your token' : 'permission'}.` +
+        '\nNothing was imported. Policy files that are unchanged never cause this.' +
+        '\n  - To push everything else, leave the policy files out:  xano workspace push -e "policies/*"' +
+        '\n  - To discard your local policy edits, pull again:        xano workspace pull' +
+        remedy);
+}

package/dist/utils/policy/push-gate.d.ts

@@ -0,0 +1,5 @@
+/** Preserve a gate refusal through shared push and operational-error wrappers. */
+export declare class PushPolicyGateError extends Error {
+    readonly payload: Record<string, unknown>;
+    constructor(payload: Record<string, unknown>, message?: string);
+}

package/dist/utils/policy/push-gate.js

@@ -0,0 +1,43 @@
+import { findingLine } from './findings.js';
+/**
+ * One blocking finding of a refused push: its rule, policy, object and message (a finding's message
+ * rarely names its object), and whether the push introduced it or changed its object.
+ */
+function refusedFindingLine(finding) {
+    const reason = typeof finding.gate_reason === 'string' && finding.gate_reason.trim() ? ` (${finding.gate_reason.trim()})` : '';
+    return `${findingLine(finding, new Map())}${reason}`;
+}
+/**
+ * The refusal's headline. The platform's sentence names the policies the blocking findings come from,
+ * to every caller (`Push refused: 2 blocking policy findings from AUTH-010 and PII-001 (1 introduced
+ * by this change, 1 on objects it changes).`), so it is printed as it is; without one, the counts.
+ */
+function headline(payload, message) {
+    const sentence = message?.trim() ?? '';
+    if (sentence.startsWith('Push refused:'))
+        return sentence;
+    const count = (key) => typeof payload[key] === 'number' ? payload[key] : 0;
+    const total = count('total');
+    return `Push refused: ${total} blocking policy finding${total === 1 ? '' : 's'} (${count('introduced')} introduced, ${count('changed')} on changed objects).`;
+}
+/** Preserve a gate refusal through shared push and operational-error wrappers. */
+export class PushPolicyGateError extends Error {
+    payload;
+    constructor(payload, message) {
+        const findings = Array.isArray(payload.findings) ? payload.findings.slice(0, 100) : [];
+        const lines = findings.flatMap(finding => finding && typeof finding === 'object' ? [refusedFindingLine(finding)] : []);
+        // The findings come only to a caller who reads the workspace's policies; anyone else gets the counts.
+        const withheld = payload.findings === undefined && typeof payload.total === 'number' && payload.total > 0;
+        const guidance = payload.can_override === true && payload.override_denied !== true
+            ? 'To proceed with an audited reason, retry with --policy-override "reason".'
+            : 'Fix the findings or ask someone with workspace:policy update permission to override with a reason.';
+        super([
+            `${headline(payload, message)} Nothing was imported.`,
+            ...lines,
+            ...(withheld ? ['The findings are listed only for a credential that reads policies (workspace:policy read).'] : []),
+            ...(payload.truncated ? ['Only the first findings are listed.'] : []),
+            guidance,
+        ].join('\n'));
+        this.payload = payload;
+    }
+}

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

@@ -0,0 +1,85 @@
+import type { PolicyRunHead } from './types.js';
+import { type PolicyRequestHost, type PolicyRequestRoute } from './request.js';
+/**
+ * One release's stored check as `GET release/policy_check` lists it, the read behind Studio's
+ * Policies column: the run, its status, when it finished, its finding counts and how many policies
+ * the release ships. A release without a stored run is not listed at all.
+ */
+export interface ReleasePolicyCheck {
+    counts?: {
+        advisory?: number;
+        blocking?: number;
+        errors?: number;
+        findings?: number;
+    };
+    finished_at?: string;
+    /** How many policies the release ships, inactive ones included. */
+    policies?: number;
+    release_id?: number;
+    run_id?: number;
+    /** `pass`, `fail` (a rule found something, advisory or not) or `error` (a rule could not run). */
+    status?: string;
+}
+/**
+ * The stored checks of these releases, by release id, or `null` when they could not be read: the
+ * Policies feature is off, the credential lacks `workspace:policy` read, the platform has no such
+ * route, or the request failed. A release the answer leaves out has no stored check. The read
+ * stores nothing and never checks a release on demand.
+ */
+export declare function readReleasePolicyChecks(host: Omit<PolicyRequestHost, 'error'>, route: Omit<PolicyRequestRoute, 'label' | 'path'>, releaseIds: number[]): Promise<Map<number, ReleasePolicyCheck> | null>;
+/**
+ * A release's stored check as a tag on its list line, worded as Studio's Policies column: the
+ * findings it holds (`2 blocking, 1 advisory`, or `11 advisory`), `passed` when it holds none,
+ * `none shipped` when the release carries no policies, `could not check` when a rule could not
+ * run, and `not checked` for a release with no stored check. The tag is the release's own check,
+ * its code against the policies it ships; whether a deploy is held is each tenant's question
+ * (`tenant deploy_release --check`), so it never says blocked.
+ */
+export declare function releasePolicyCheckTag(check: null | ReleasePolicyCheck | undefined): string;
+/**
+ * The policy check a release cut stored (`policy_run` on the create, multidoc push and import
+ * answers): whether one was recorded (`recorded`, or `disabled`, `skipped` or `error` with a
+ * message), the run, its verdict and how many of its findings block. `null` for a credential that
+ * cannot read policies; absent from a platform that does not check releases.
+ */
+export interface ReleasePolicyRun {
+    advisory?: number;
+    blocking?: number;
+    message?: string;
+    run_id?: number;
+    /** `pass`, `fail` or `error`; empty when nothing was recorded. */
+    run_status?: string;
+    status?: string;
+}
+/** A release's stored run, as `GET release/{id}/policy_run` serves it: a run summary plus the release's own keys. */
+export interface ReleaseRunHead extends PolicyRunHead {
+    release?: {
+        branch?: {
+            id?: number;
+            label?: string;
+        };
+        id?: number;
+    };
+    /** Every policy the release carries, inactive ones included. */
+    shipped?: Array<{
+        active?: boolean;
+        enforcement?: string;
+        key?: string;
+        title?: string;
+    }>;
+}
+/**
+ * The cut's policy check as summary lines under a release's own (indented), or none when the answer
+ * carries none. A cut is never refused: blocking findings are judged per tenant at deploy, so the
+ * lines point at the deploy preview and the release's findings.
+ */
+export declare function releasePolicyRunLines(policyRun: unknown, releaseName?: string, releaseId?: number): string[];
+/** The release's own facts about its check: where it was cut from and the policies it ships. */
+export declare function releaseRunLines(releaseName: string, releaseId: number, run: ReleaseRunHead): string[];
+/**
+ * A `release import` the platform refused for the policies the archive carries, as one message with
+ * its remedy, or `null` for any other failure. An archive that says it carries policies needs the
+ * `workspace:policy` create and update permission to import (`policy_permission_required` for the
+ * role, `policy_scope_required` for the token), and nothing is stored without it.
+ */
+export declare function releaseImportRefusal(text: string, status: number, url: string): null | string;

package/dist/utils/policy/release.js

@@ -0,0 +1,117 @@
+import { describePolicyError } from './errors.js';
+import { quoted } from './gate.js';
+import { policyPermissionGuidance } from './permission.js';
+import { policyRequest } from './request.js';
+/** The most releases one `release/policy_check` request may name (the platform refuses more). */
+const CHECKS_PER_REQUEST = 200;
+/** A request host's `error` that throws instead of exiting, for a read that may fail quietly. */
+function fail(message) {
+    throw new Error(message);
+}
+/**
+ * The stored checks of these releases, by release id, or `null` when they could not be read: the
+ * Policies feature is off, the credential lacks `workspace:policy` read, the platform has no such
+ * route, or the request failed. A release the answer leaves out has no stored check. The read
+ * stores nothing and never checks a release on demand.
+ */
+export async function readReleasePolicyChecks(host, route, releaseIds) {
+    const ids = [...new Set(releaseIds.filter(id => Number.isSafeInteger(id) && id > 0))];
+    const checks = new Map();
+    if (ids.length === 0)
+        return checks;
+    const request = policyRequest({ ...host, error: fail }, { ...route, label: 'Release policy check', path: '' });
+    try {
+        for (let start = 0; start < ids.length; start += CHECKS_PER_REQUEST) {
+            const batch = ids.slice(start, start + CHECKS_PER_REQUEST).map(String);
+            // Each batch is one request; the list is far shorter than a batch in practice.
+            // eslint-disable-next-line no-await-in-loop
+            const answer = await request('/release/policy_check', 'GET', undefined, { release_id: batch });
+            const items = answer && typeof answer === 'object' ? answer.items : undefined;
+            if (!Array.isArray(items))
+                return null;
+            for (const item of items) {
+                if (item && typeof item === 'object' && typeof item.release_id === 'number')
+                    checks.set(item.release_id, item);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return checks;
+}
+/**
+ * A release's stored check as a tag on its list line, worded as Studio's Policies column: the
+ * findings it holds (`2 blocking, 1 advisory`, or `11 advisory`), `passed` when it holds none,
+ * `none shipped` when the release carries no policies, `could not check` when a rule could not
+ * run, and `not checked` for a release with no stored check. The tag is the release's own check,
+ * its code against the policies it ships; whether a deploy is held is each tenant's question
+ * (`tenant deploy_release --check`), so it never says blocked.
+ */
+export function releasePolicyCheckTag(check) {
+    return `[policies: ${releasePolicyCheckLabel(check)}]`;
+}
+function releasePolicyCheckLabel(check) {
+    if (!check)
+        return 'not checked';
+    const findings = Math.max(0, check.counts?.findings ?? 0);
+    const blocking = Math.max(0, check.counts?.blocking ?? 0);
+    const advisory = Math.max(0, check.counts?.advisory ?? findings - blocking);
+    const counts = [blocking > 0 ? `${blocking} blocking` : '', advisory > 0 ? `${advisory} advisory` : ''].filter(Boolean);
+    if (check.status === 'error')
+        return ['could not check', ...counts].join(', ');
+    if (counts.length > 0)
+        return counts.join(', ');
+    return (check.policies ?? 0) > 0 ? 'passed' : 'none shipped';
+}
+/**
+ * The cut's policy check as summary lines under a release's own (indented), or none when the answer
+ * carries none. A cut is never refused: blocking findings are judged per tenant at deploy, so the
+ * lines point at the deploy preview and the release's findings.
+ */
+export function releasePolicyRunLines(policyRun, releaseName, releaseId) {
+    if (!policyRun || typeof policyRun !== 'object')
+        return [];
+    const check = policyRun;
+    const status = check.status?.trim() || 'unknown';
+    if (status === 'disabled')
+        return [];
+    if (status !== 'recorded') {
+        return [`  Policy check ${status}: ${check.message?.trim() || 'no message returned.'}`];
+    }
+    const blocking = check.blocking ?? 0;
+    const advisory = check.advisory ?? 0;
+    const findings = blocking + advisory === 0 ? 'no findings' : `${blocking} blocking, ${advisory} advisory ${blocking + advisory === 1 ? 'finding' : 'findings'}`;
+    const lines = [`  Policy check: ${check.run_status || 'recorded'} (run ${check.run_id ?? '?'}), ${findings}`];
+    if (check.message?.trim())
+        lines.push(`    ${check.message.trim()}`);
+    const name = releaseName?.trim() ? quoted(releaseName.trim()) : '<release_name>';
+    const target = releaseName?.trim() || !releaseId ? `--release ${name}` : `--release-id ${releaseId}`;
+    if (blocking + advisory > 0)
+        lines.push(`    Findings: xano policy runs ${target}`);
+    if (blocking > 0 && releaseName?.trim())
+        lines.push(`    Its blocking findings block a deploy to a standard or run tenant: xano tenant deploy_release <tenant> --release ${name} --check`);
+    return lines;
+}
+/** The release's own facts about its check: where it was cut from and the policies it ships. */
+export function releaseRunLines(releaseName, releaseId, run) {
+    const shipped = run.shipped ?? [];
+    const keys = shipped.map(policy => policy.key ?? '').filter(Boolean);
+    const from = run.release?.branch?.label?.trim();
+    return [
+        `Release ${releaseName} (ID ${releaseId}): ships ${keys.length} ${keys.length === 1 ? 'policy' : 'policies'}${keys.length > 0 ? ` (${keys.join(', ')})` : ''}${from ? `; checked as cut from branch ${from}` : ''}`,
+    ];
+}
+/**
+ * A `release import` the platform refused for the policies the archive carries, as one message with
+ * its remedy, or `null` for any other failure. An archive that says it carries policies needs the
+ * `workspace:policy` create and update permission to import (`policy_permission_required` for the
+ * role, `policy_scope_required` for the token), and nothing is stored without it.
+ */
+export function releaseImportRefusal(text, status, url) {
+    const { message, payload } = describePolicyError(text, status, url);
+    const code = payload && typeof payload === 'object' ? payload.code : undefined;
+    if (typeof code !== 'string' || !code.startsWith('policy_'))
+        return null;
+    return `${message}${policyPermissionGuidance(status, payload)}`;
+}