@xano/cli 1.2.0 → 1.3.1-beta.0

package/dist/utils/policy/gate.js

@@ -0,0 +1,201 @@
+import { describePolicyError } from './errors.js';
+import { findingLine } from './findings.js';
+import { WEAKENING_REFUSAL } from './permission.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.') };
+}
+/** The weakening refusal read from a failed response, or `null` for any other failure. */
+export async function weakeningRefusal(response) {
+    const refused = await coded403(response, WEAKENING_REFUSAL);
+    if (!refused)
+        return null;
+    return { message: refused.message || 'Refused: the change weakens a mandatory policy.', payload: refused.payload };
+}
+/**
+ * `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/goal.d.ts

@@ -0,0 +1,46 @@
+/** Goals and sparse parameter seeds come from the instance's catalogue. */
+export interface PolicyGoal {
+    goal: string;
+    id: string;
+    key: string;
+    rules: Array<{
+        check: string;
+        needs: string[];
+        params: Record<string, unknown>;
+        title: string;
+    }>;
+    severity: string;
+    summary: string;
+}
+/** The catalogue's `document.key`: the platform's key pattern, and its refusal with `%s` for the key. */
+export interface PolicyKeyRule {
+    message?: string;
+    pattern?: string;
+}
+/** How a goal becomes a policy: the key, the catalogue's key rule and the `--param` assignments. */
+export interface GoalPolicyOptions {
+    /** `--key`: the new policy's key; refused when a policy already holds it. */
+    key?: string;
+    /** The fetched catalogue's `document.key`; the offline pattern stands in for an instance that serves none. */
+    keyRule?: null | PolicyKeyRule;
+    /** `--param N.path=JSON` assignments. */
+    overrides?: string[];
+}
+/** The policy document a goal becomes, for the parse route's `data`. */
+export interface GoalPolicyDocument {
+    key: string;
+    rules: Array<{
+        check: string;
+        params: Record<string, unknown>;
+        title: string;
+    }>;
+    severity: string;
+    statement: string;
+    title: string;
+}
+/**
+ * The policy document for a goal: its sparse settings with the `--param` assignments applied, every
+ * `needs` path filled, and a key no policy on the branch holds (compared case-insensitively). A taken
+ * goal key gets a free numeric suffix; a taken or malformed `--key` is refused.
+ */
+export declare function policyFromGoal(goal: PolicyGoal, takenKeys: string[], options?: GoalPolicyOptions): GoalPolicyDocument;

package/dist/utils/policy/goal.js

@@ -0,0 +1,95 @@
+import { POLICY_KEY_PATTERN } from '../document-parser.js';
+/**
+ * The policy document for a goal: its sparse settings with the `--param` assignments applied, every
+ * `needs` path filled, and a key no policy on the branch holds (compared case-insensitively). A taken
+ * goal key gets a free numeric suffix; a taken or malformed `--key` is refused.
+ */
+export function policyFromGoal(goal, takenKeys, options = {}) {
+    const { key, keyRule, overrides = [] } = options;
+    const taken = new Set(takenKeys.map(value => value.toLowerCase()));
+    let chosen = key ?? goal.key;
+    if (!keyPattern(keyRule).test(chosen))
+        throw new Error(keyRefusal(keyRule, chosen));
+    if (key !== undefined && taken.has(chosen.toLowerCase()))
+        throw new Error(`Policy ${chosen} already exists. Choose a new --key or use policy publish to update it.`);
+    for (let suffix = 2; taken.has(chosen.toLowerCase()); suffix++)
+        chosen = `${goal.key.slice(0, 63 - String(suffix).length)}-${suffix}`;
+    const rules = goal.rules.map(rule => ({ check: rule.check, params: Array.isArray(rule.params) ? {} : structuredClone(rule.params), title: rule.title }));
+    for (const assignment of overrides)
+        applyOverride(rules, assignment);
+    const missing = goal.rules.flatMap((rule, index) => (rule.needs ?? []).filter(path => !filled(readPath(rules[index].params, path))).map(path => `${index + 1}.${path}`));
+    if (missing.length > 0)
+        throw new Error(`Fill the goal's required settings with --param 'N.path=JSON': ${missing.join(', ')}.`);
+    return { key: chosen, rules, severity: goal.severity, statement: goal.summary, title: goal.goal };
+}
+/** The catalogue's key pattern, or the offline copy when the catalogue serves none (or one that does not compile). */
+function keyPattern(rule) {
+    if (typeof rule?.pattern !== 'string' || rule.pattern === '')
+        return POLICY_KEY_PATTERN;
+    try {
+        return new RegExp(rule.pattern);
+    }
+    catch {
+        return POLICY_KEY_PATTERN;
+    }
+}
+/** The catalogue's refusal for a malformed key, naming it, or the offline sentence. */
+function keyRefusal(rule, key) {
+    return typeof rule?.message === 'string' && rule.message.trim()
+        ? rule.message.replaceAll('%s', key)
+        : 'A policy key must be 1–64 letters, digits, dots, underscores or hyphens, starting with a letter or digit.';
+}
+/** The value at a dotted path of a rule's params, or undefined when any step is missing. */
+function readPath(params, path) {
+    let value = params;
+    for (const part of path.split('.')) {
+        if (!value || typeof value !== 'object' || !Object.hasOwn(value, part))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+/** Whether a `needs` value is set: not empty, null or blank; `false` and `0` count as set. */
+function filled(value) {
+    if (Array.isArray(value))
+        return value.some(item => filled(item));
+    if (value && typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return value !== undefined && value !== null && (typeof value !== 'string' || value.trim() !== '');
+}
+/** Apply one `--param [N.]path=JSON` assignment to its rule's params, refusing unsafe paths and non-JSON values. */
+function applyOverride(rules, assignment) {
+    const equals = assignment.indexOf('=');
+    if (equals < 1)
+        throw new Error('Use --param path=JSON or --param N.path=JSON (rule numbers start at 1).');
+    const parts = assignment.slice(0, equals).split('.');
+    let index = 0;
+    if (/^\d+$/.test(parts[0]))
+        index = Number(parts.shift()) - 1;
+    else if (rules.length !== 1)
+        throw new Error('Include the rule number in --param N.path=JSON for a goal with multiple rules.');
+    if (!Number.isSafeInteger(index) || !rules[index])
+        throw new Error(`Rule ${index + 1} does not exist in this goal.`);
+    if (parts.length === 0 || parts.some(part => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part) || ['__proto__', 'constructor', 'prototype'].includes(part)))
+        throw new Error('Invalid parameter path. Use parameter names separated by dots.');
+    let value;
+    try {
+        value = JSON.parse(assignment.slice(equals + 1), (_key, parsed) => {
+            if (typeof parsed === 'number' && !Number.isFinite(parsed))
+                throw new Error('Numbers must be finite.');
+            return parsed;
+        });
+    }
+    catch {
+        throw new Error(`The value for ${assignment.slice(0, equals)} must be JSON: a quoted string, finite number, boolean, array or object.`);
+    }
+    let target = rules[index].params;
+    for (const part of parts.slice(0, -1)) {
+        if (target[part] === undefined)
+            target[part] = {};
+        if (!target[part] || typeof target[part] !== 'object' || Array.isArray(target[part]))
+            throw new Error(`Cannot set a nested parameter inside ${part}.`);
+        target = target[part];
+    }
+    target[parts.at(-1)] = value;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * The refusal of a change that weakens a policy active and mandatory on the branch (demotes,
+ * deactivates or deletes it, or loosens one of its rules; for a set-live, a live policy the branch
+ * lacks) from a caller without the `workspace:policy` update permission. It is a permission refusal,
+ * not a blocking finding, so a command exits 1 on it. `payload.policies` names the policies.
+ */
+export declare const WEAKENING_REFUSAL = "policy_weakening_permission_required";
+/** 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
+ * because its policy files weaken a mandatory policy of the live branch, or `undefined` for any
+ * other refusal.
+ */
+export declare function policyFilePushGuidance(payload: unknown): string | undefined;
+/**
+ * Guidance for a change refused with `policy_weakening_permission_required`. The platform's sentence
+ * already names the policies and what was left alone; this says why (a delete of a mandatory policy,
+ * or a check that could not read the policies and so fails closed), that `--policy-override` does
+ * not stand in for the permission when the command has that flag (`overrideFlag`), and how to go on:
+ * `ways` are the command's own, before the fallback of asking someone who holds the permission.
+ */
+export declare function policyWeakeningGuidance(payload: unknown, ways?: string[], overrideFlag?: boolean): string;

package/dist/utils/policy/permission.js

@@ -0,0 +1,84 @@
+const TOKEN_SETTINGS = 'Instance settings → Metadata API & MCP Server → Manage Access Tokens';
+/**
+ * The refusal of a change that weakens a policy active and mandatory on the branch (demotes,
+ * deactivates or deletes it, or loosens one of its rules; for a set-live, a live policy the branch
+ * lacks) from a caller without the `workspace:policy` update permission. It is a permission refusal,
+ * not a blocking finding, so a command exits 1 on it. `payload.policies` names the policies.
+ */
+export const WEAKENING_REFUSAL = 'policy_weakening_permission_required';
+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_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}.`;
+        }
+        case WEAKENING_REFUSAL: {
+            return policyWeakeningGuidance(payload);
+        }
+        default: {
+            return '';
+        }
+    }
+}
+/**
+ * Guidance for a `workspace push` (or its preview) refused because it would change policies, or
+ * because its policy files weaken a mandatory policy of the live branch, or `undefined` for any
+ * other refusal.
+ */
+export function policyFilePushGuidance(payload) {
+    const refusal = refusalOf(payload);
+    if (refusal.code === WEAKENING_REFUSAL) {
+        return policyWeakeningGuidance(payload, [
+            'To push everything else, leave the policy files out:  xano workspace push -e "policies/*"',
+            'To discard your local policy edits, pull again:        xano workspace pull',
+        ], true);
+    }
+    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);
+}
+/**
+ * Guidance for a change refused with `policy_weakening_permission_required`. The platform's sentence
+ * already names the policies and what was left alone; this says why (a delete of a mandatory policy,
+ * or a check that could not read the policies and so fails closed), that `--policy-override` does
+ * not stand in for the permission when the command has that flag (`overrideFlag`), and how to go on:
+ * `ways` are the command's own, before the fallback of asking someone who holds the permission.
+ */
+export function policyWeakeningGuidance(payload, ways = [], overrideFlag = false) {
+    const refusal = refusalOf(payload);
+    const permission = `${permissionAt({ level: refusal.level ?? 'update' })} permission`;
+    const why = refusal.unavailable === true
+        ? `The policies could not be read to check this, so only someone with the ${permission} may proceed.`
+        : refusal.gate === 'delete'
+            ? `Deleting a policy that is active and mandatory weakens it, so it needs the ${permission}, not only delete.`
+            : `Weakening means demoting, deactivating or deleting a mandatory policy, or loosening one of its rules, and it needs the ${permission}.`;
+    return (`\n${why}${overrideFlag ? ' --policy-override does not stand in for it.' : ''}` +
+        [...ways, `${ways.length > 0 ? 'Or ask' : 'Ask'} someone who holds that permission to make this change, or an instance admin to grant it to your role.`].map(way => `\n  - ${way}`).join(''));
+}

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>);
+}

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

@@ -0,0 +1,29 @@
+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}`;
+}
+/** Preserve a gate refusal through shared push and operational-error wrappers. */
+export class PushPolicyGateError extends Error {
+    payload;
+    constructor(payload) {
+        const count = (key) => typeof payload[key] === 'number' ? payload[key] : 0;
+        const findings = Array.isArray(payload.findings) ? payload.findings.slice(0, 100) : [];
+        const lines = findings.flatMap(finding => finding && typeof finding === 'object' ? [refusedFindingLine(finding)] : []);
+        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.';
+        const total = count('total');
+        super([
+            `Push refused: ${total} blocking policy finding${total === 1 ? '' : 's'} (${count('introduced')} introduced, ${count('changed')} on changed objects). Nothing was imported.`,
+            ...lines,
+            ...(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;