@xano/cli 1.2.0 → 1.3.1-beta.0

package/dist/utils/paging.d.ts

@@ -16,7 +16,8 @@
  *                         so the item count IS the total.
  *
  * There is deliberately no tier for endpoints that page but return a bare array
- * with no metadata (tenants, releases, platforms, clusters, tenant backups). Those commands are left alone: the only has-more signal available
+ * with no metadata (tenants, releases, platforms, clusters, ephemerals, tenant
+ * backups). Those commands are left alone: the only has-more signal available
  * would be "the page came back full", which is a guaranteed false positive when
  * the result set is an exact multiple of the page size — sending the user to an
  * empty page. Better to offer nothing than to offer a lie.

package/dist/utils/paging.js

@@ -1,4 +1,3 @@
-/* eslint-disable camelcase */
 import { Flags } from '@oclif/core';
 function makePageFlag(description) {
     return Flags.integer({ default: 1, description, required: false });

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

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

package/dist/utils/policy/catalogue.js

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

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

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

package/dist/utils/policy/errors.js

@@ -0,0 +1,61 @@
+/** Keep backend implementation details out of ordinary command errors. */
+function withoutStack(text) {
+    return text.split(/\n\s*(?:Stack trace:|#\d+\s|at\s|file:\s*\/)/i, 1)[0];
+}
+/** Where a parse error is: the payload's 1-based `line` and `col`, printed as served, and the offending text. */
+function positionLine(payload) {
+    const text = [payload.error_line, payload.error_snippet, payload.snippet]
+        .find(value => typeof value === 'string' && value.trim() !== '');
+    const where = typeof payload.line === 'number' && Number.isFinite(payload.line)
+        ? `line ${payload.line}${typeof payload.col === 'number' && Number.isFinite(payload.col) ? `, col ${payload.col}` : ''}`
+        : '';
+    if (!where && text === undefined)
+        return '';
+    return `\n  ${where ? `at ${where}` : 'at'}${text === undefined ? '' : `: ${text}`}`;
+}
+/** An empty 404 from a branch-scoped request means the branch it named does not exist. */
+function missingBranch(requestUrl) {
+    const url = new URL(requestUrl);
+    const workspace = url.pathname.match(/\/workspace\/([^/]+)/)?.[1];
+    const branch = url.searchParams.get('branch');
+    return workspace && branch ? `Branch "${branch}" was not found in workspace ${decodeURIComponent(workspace)}.` : '';
+}
+/**
+ * What to do about a refusal of the request itself, keyed on the platform's `payload.code`:
+ *
+ *   policy_unknown_check   a rule names a check id this instance does not have
+ *   policy_stale           the policy changed after the command read it
+ *
+ * Permission refusals are explained by `policyPermissionGuidance`.
+ */
+const CODE_GUIDANCE = {
+    policy_stale: '\nThe policy changed after this command read it, so nothing was changed. Run the command again to act on its current version.',
+    policy_unknown_check: '\nRun `xano policy catalogue` to list every check id this instance has.',
+};
+/** Guidance appended to a refusal whose `payload.code` the CLI has advice for, or `''`. */
+export function policyCodeGuidance(payload) {
+    const code = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload.code : undefined;
+    return typeof code === 'string' && Object.hasOwn(CODE_GUIDANCE, code) ? CODE_GUIDANCE[code] : '';
+}
+/**
+ * A failed policy-route response as one message: the platform's code and message, and where a parse
+ * error is. Traces are dropped, and an empty 404 names the branch the request selected.
+ */
+export function describePolicyError(text, status, requestUrl) {
+    let data;
+    try {
+        data = JSON.parse(text.trim() || '{}');
+    }
+    catch {
+        return { message: withoutStack(text) };
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return { message: withoutStack(text) };
+    const { code, message: raw, payload } = data;
+    let message = typeof raw === 'string' ? withoutStack(raw) : '';
+    if (status === 404 && !message.trim())
+        message = missingBranch(requestUrl);
+    const headline = [typeof code === 'string' ? code : '', message].filter(Boolean).join(': ');
+    const position = payload && typeof payload === 'object' ? positionLine(payload) : '';
+    return { message: `${headline}${position}` || 'The server returned no message.', payload };
+}

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

@@ -0,0 +1,68 @@
+import type { PolicyEvaluation, PolicyFinding, PolicyRuleResult, PolicySnapshotPolicy, PolicyVerdict, PushPolicyCheck } from './types.js';
+/** 2 whenever the platform says a finding blocks, whatever the status; every other outcome is 0. */
+export declare function policyExitCode(check?: PolicyVerdict): number;
+/**
+ * The one warning line for feedback without a headline (`disabled`, `forbidden`, `unavailable`,
+ * `error`, an unknown status, or a pass or fail that does not say whether it blocks): the server's
+ * own status and message, or that none came back. `null` for headlined feedback.
+ */
+export declare function policyCheckWarning(check?: PolicyVerdict): null | string;
+/**
+ * What happened to the policy documents a push carried. The preview says, per policy, whether it was
+ * created, updated or left unchanged. Without a preview only the number sent is known: the import
+ * response reports an unchanged policy exactly as it reports a saved one.
+ */
+export declare function policyDocumentSummary(preview: null | {
+    operations: Array<{
+        action: string;
+        name: string;
+        type: string;
+    }>;
+}, sentPolicies: number): string[];
+/** What a verdict is about: its findings, which of them block, and the rule results. */
+export interface PolicyEvidence {
+    /** The ids of the findings that block. */
+    blocking: Set<string>;
+    /**
+     * When the answer lists only the first findings: how many there are in all, and how many block.
+     * The stored run (`runId`, 0 when nothing was stored) has them all.
+     */
+    cut?: {
+        blocking: number;
+        findings: number;
+        runId: number;
+    };
+    /** In the platform's order: blocking first, then by severity. */
+    findings: PolicyFinding[];
+    results: PolicyRuleResult[];
+    /** The run's own `policies[]`, which names unnamed rules; a push answers none. */
+    snapshot: PolicySnapshotPolicy[];
+}
+/**
+ * A push answers no run, so its `policy_check` carries the findings and results itself: the first
+ * 100 of each list, with `counts` and `total` saying what they are out of.
+ */
+export declare function pushEvidence(check?: PushPolicyCheck): PolicyEvidence;
+/**
+ * An evaluation answers the run, and its verdict names the blocking findings by id. Its summary
+ * answer (`--summary`) lists the first findings, and its counts say what they are out of.
+ */
+export declare function evaluationEvidence(evaluation: PolicyEvaluation): PolicyEvidence;
+/**
+ * The feedback on stdout: a headline with the server's message, then any findings, errors and
+ * warnings. Feedback without a headline is reported by `policyCheckWarning` instead.
+ */
+export declare function policySummary(check: PolicyVerdict | undefined, evidence: PolicyEvidence): string[];
+/**
+ * The platform's one notice that a push or its dry run left policy files out
+ * (`policies_skipped.message`): a push to a remote tenant or to a tenant without a policy table, a
+ * `release push` by a caller without `workspace:policy` create and update (its release carries the
+ * live branch's policies instead), and any push while the Policies feature is off. `null` when it
+ * left none out.
+ */
+export declare function policiesSkippedNotice(answer: unknown): null | string;
+/**
+ * The line for an evaluation that ran but was not recorded (the credential may read, not write), or
+ * `null`. A branch with nothing to evaluate stores nothing either, and its headline says so.
+ */
+export declare function notStoredLine(evaluation: PolicyEvaluation): null | string;

package/dist/utils/policy/feedback.js

@@ -0,0 +1,165 @@
+import { findingLine, hasNoObjects, policyResultSummary, snapshotRules } from './findings.js';
+/**
+ * Feedback printed as a headline: a pass or fail that says whether its findings block, or a branch
+ * with no active policy to evaluate. Everything else is reported by `policyCheckWarning`.
+ */
+function isHeadlined(check) {
+    if (check.status === 'not_applicable')
+        return true;
+    return ['fail', 'pass'].includes(check.status ?? '') && typeof check.blocking === 'boolean';
+}
+/** 2 whenever the platform says a finding blocks, whatever the status; every other outcome is 0. */
+export function policyExitCode(check) {
+    return check?.blocking === true ? 2 : 0;
+}
+/**
+ * The one warning line for feedback without a headline (`disabled`, `forbidden`, `unavailable`,
+ * `error`, an unknown status, or a pass or fail that does not say whether it blocks): the server's
+ * own status and message, or that none came back. `null` for headlined feedback.
+ */
+export function policyCheckWarning(check) {
+    if (!check)
+        return 'Policy check: no policy feedback returned.';
+    if (isHeadlined(check))
+        return null;
+    const status = typeof check.status === 'string' && check.status.trim() !== '' ? check.status.trim() : 'unknown';
+    const message = typeof check.message === 'string' && check.message.trim() !== ''
+        ? check.message.trim()
+        : (['fail', 'pass'].includes(status) ? 'the server did not say whether its findings block.' : 'no message returned.');
+    return `Policy check ${status}: ${message}`;
+}
+/**
+ * What happened to the policy documents a push carried. The preview says, per policy, whether it was
+ * created, updated or left unchanged. Without a preview only the number sent is known: the import
+ * response reports an unchanged policy exactly as it reports a saved one.
+ */
+export function policyDocumentSummary(preview, sentPolicies) {
+    const operations = (preview?.operations ?? []).filter((op) => op.type === 'policy');
+    if (operations.length === 0) {
+        return sentPolicies > 0
+            ? [`Policy documents: ${sentPolicies} sent without a preview, so which of them changed is not known`]
+            : [];
+    }
+    const named = (action) => operations.filter((op) => op.action === action).map((op) => op.name).sort();
+    const created = named('create');
+    const updated = named('update');
+    const unchanged = named('unchanged');
+    const parts = [
+        created.length > 0 && `${created.length} created (${created.join(', ')})`,
+        updated.length > 0 && `${updated.length} updated (${updated.join(', ')})`,
+        unchanged.length > 0 && `${unchanged.length} unchanged`,
+    ].filter(Boolean);
+    return parts.length > 0 ? [`Policy documents: ${parts.join(', ')}`] : [];
+}
+/**
+ * A push answers no run, so its `policy_check` carries the findings and results itself: the first
+ * 100 of each list, with `counts` and `total` saying what they are out of.
+ */
+export function pushEvidence(check) {
+    return {
+        blocking: new Set((check?.blocking_findings ?? []).map(finding => finding.id ?? '').filter(Boolean)),
+        ...(check?.truncated && check.counts
+            ? { cut: { blocking: check.counts.blocking, findings: check.total ?? check.counts.findings, runId: check.run_id ?? 0 } }
+            : {}),
+        findings: check?.findings ?? [],
+        results: check?.results ?? [],
+        snapshot: [],
+    };
+}
+/**
+ * An evaluation answers the run, and its verdict names the blocking findings by id. Its summary
+ * answer (`--summary`) lists the first findings, and its counts say what they are out of.
+ */
+export function evaluationEvidence(evaluation) {
+    const { counts } = evaluation;
+    return {
+        blocking: new Set(evaluation.policy_check?.blocking_finding_ids ?? []),
+        ...(evaluation.truncated && counts
+            ? { cut: { blocking: counts.blocking, findings: evaluation.total ?? counts.findings, runId: evaluation.stored === false ? 0 : (evaluation.id ?? 0) } }
+            : {}),
+        findings: evaluation.findings ?? [],
+        results: evaluation.results ?? [],
+        snapshot: evaluation.policies ?? [],
+    };
+}
+/** A list's count, or `first N of M` when the answer lists only the first of them. */
+function listed(count, all) {
+    return all !== undefined && all > count ? `first ${count} of ${all}` : String(count);
+}
+/** The headline's outcome. A pass whose rules inspected no object is never headlined as a plain pass. */
+function outcome(check, results) {
+    if (check.status === 'fail')
+        return check.blocking ? 'fail (blocking findings)' : 'advisory findings (not blocking)';
+    if (check.status !== 'pass')
+        return check.status ?? '';
+    const unchecked = results.filter((result) => hasNoObjects(result)).length;
+    if (unchecked === 0)
+        return 'pass';
+    return unchecked === results.length
+        ? 'pass, but no objects were checked'
+        : `pass, but ${unchecked} rule${unchecked === 1 ? '' : 's'} checked no objects`;
+}
+/**
+ * The feedback on stdout: a headline with the server's message, then any findings, errors and
+ * warnings. Feedback without a headline is reported by `policyCheckWarning` instead.
+ */
+export function policySummary(check, evidence) {
+    if (!check)
+        return [];
+    const lines = [];
+    if (isHeadlined(check)) {
+        lines.push(`Policy check: ${outcome(check, evidence.results)}`);
+        if (check.message)
+            lines.push(check.message);
+    }
+    const rules = snapshotRules(evidence.snapshot);
+    const { blocking, cut, findings } = evidence;
+    // A cut list is out of the counts; the ones the answer lists come first, blocking first.
+    const allBlocking = cut?.blocking;
+    const allAdvisory = cut ? cut.findings - cut.blocking : undefined;
+    if (cut)
+        lines.push(`Findings: ${cut.findings} (${cut.blocking} blocking, ${allAdvisory} advisory)`);
+    // The list splits only when some findings block and others do not.
+    const separated = blocking.size > 0 && findings.some(finding => !blocking.has(finding.id ?? ''));
+    if (separated) {
+        const blocked = findings.filter(finding => blocking.has(finding.id ?? ''));
+        const advisory = findings.filter(finding => !blocking.has(finding.id ?? ''));
+        lines.push(`Blocking findings (${listed(blocked.length, allBlocking)}) — active mandatory policies; a gate refuses a change that introduces one or changes its object:`, ...blocked.map(finding => findingLine(finding, rules)), `Advisory findings (${listed(advisory.length, allAdvisory)}) — reported, not blocking:`, ...advisory.map(finding => findingLine(finding, rules)));
+    }
+    else {
+        if (blocking.size > 0 && findings.length > 0)
+            lines.push(`Blocking findings (${listed(findings.length, allBlocking)}) — active mandatory policies; a gate refuses a change that introduces one or changes its object:`);
+        // Without a headline (an `error` status, say) nothing else says what these findings are.
+        else if (findings.length > 0 && !isHeadlined(check))
+            lines.push(`Advisory findings (${listed(findings.length, allAdvisory)}) — reported, not blocking:`);
+        lines.push(...findings.map(finding => findingLine(finding, rules)));
+    }
+    if (cut) {
+        lines.push(`Listed: the first ${findings.length} of ${cut.findings}; ${cut.runId > 0
+            ? `\`xano policy runs ${cut.runId}\` has them all.`
+            : 'this evaluation was not stored, so the rest cannot be listed.'}`);
+    }
+    lines.push(...policyResultSummary(evidence.results));
+    return lines;
+}
+/**
+ * The platform's one notice that a push or its dry run left policy files out
+ * (`policies_skipped.message`): a push to a remote tenant or to a tenant without a policy table, a
+ * `release push` by a caller without `workspace:policy` create and update (its release carries the
+ * live branch's policies instead), and any push while the Policies feature is off. `null` when it
+ * left none out.
+ */
+export function policiesSkippedNotice(answer) {
+    const skipped = answer && typeof answer === 'object' ? answer.policies_skipped : undefined;
+    const message = skipped && typeof skipped === 'object' ? skipped.message : undefined;
+    return typeof message === 'string' && message.trim() !== '' ? message.trim() : null;
+}
+/**
+ * The line for an evaluation that ran but was not recorded (the credential may read, not write), or
+ * `null`. A branch with nothing to evaluate stores nothing either, and its headline says so.
+ */
+export function notStoredLine(evaluation) {
+    if (evaluation.stored !== false || !['error', 'fail', 'pass'].includes(evaluation.policy_check?.status ?? ''))
+        return null;
+    return 'Not stored: this credential can run checks but not record runs, so `xano policy status` and `xano policy runs` will not show this one.';
+}

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

@@ -0,0 +1,23 @@
+import type { PolicyFinding, PolicyRuleResult, PolicySnapshotPolicy, PolicySnapshotRule } from './types.js';
+/**
+ * The platform's naming rule, shared with Studio: the author's title, then the check's human
+ * label, then the rule id. Pass `label` from the run snapshot, or from the catalogue entry for
+ * `check` when the caller already holds the catalogue; never fetch one just to name a rule.
+ */
+export declare function policyRuleName(rule: PolicySnapshotRule): string;
+/** Collision-free regardless of what a key or rule id contains. */
+export declare const ruleKey: (policyKey?: string, ruleId?: string) => string;
+export declare function snapshotRules(policies: PolicySnapshotPolicy[]): Map<string, PolicySnapshotRule>;
+/**
+ * One finding line. The rule id leads it, because the check's label is shared by every
+ * rule that uses that check — with two rules of one policy failing, the labels alone do
+ * not tell them apart, and the id is what `--run-detail` and the JSON cite.
+ */
+export declare function findingLine(finding: PolicyFinding, rules: Map<string, PolicySnapshotRule>): string;
+/** A completed rule with no objects checked, including older stored pass + checked 0 results. */
+export declare function hasNoObjects(result: PolicyRuleResult): boolean;
+/**
+ * Rule errors ("this rule could not run") and scope warnings ("part of your scope selected
+ * nothing") under their own headings, then the rules that inspected nothing.
+ */
+export declare function policyResultSummary(results?: PolicyRuleResult[]): string[];

package/dist/utils/policy/findings.js

@@ -0,0 +1,65 @@
+/**
+ * The platform's naming rule, shared with Studio: the author's title, then the check's human
+ * label, then the rule id. Pass `label` from the run snapshot, or from the catalogue entry for
+ * `check` when the caller already holds the catalogue; never fetch one just to name a rule.
+ */
+export function policyRuleName(rule) {
+    return rule.title?.trim() || rule.label?.trim() || rule.id?.trim() || '';
+}
+/** Collision-free regardless of what a key or rule id contains. */
+export const ruleKey = (policyKey = '', ruleId = '') => JSON.stringify([policyKey, ruleId]);
+export function snapshotRules(policies) {
+    return new Map(policies.flatMap(policy => (policy.rules ?? []).map(rule => [ruleKey(policy.key, rule.id), rule])));
+}
+/** A finding names its rule the way the platform does, falling back to what the run recorded. */
+function findingName(finding, rules) {
+    const recorded = rules.get(ruleKey(finding.policy_key, finding.rule_id)) ?? {};
+    return policyRuleName({
+        ...recorded,
+        id: finding.rule_id ?? recorded.id,
+        title: finding.rule_title || recorded.title,
+    }) || 'finding';
+}
+/**
+ * One finding line. The rule id leads it, because the check's label is shared by every
+ * rule that uses that check — with two rules of one policy failing, the labels alone do
+ * not tell them apart, and the id is what `--run-detail` and the JSON cite.
+ */
+export function findingLine(finding, rules) {
+    // A rule the author left unnamed is called by its check's label, and only then by its id.
+    const rule = findingName(finding, rules);
+    const id = finding.rule_id?.trim();
+    const policy = finding.policy_title || finding.policy_key || 'policy';
+    const severity = finding.severity?.trim() ? ` [${finding.severity.trim()}]` : '';
+    return `  ${[id, id === rule ? '' : rule].filter(Boolean).join('  ')}${severity} (${policy})  ${finding.object?.type ?? ''} ${finding.object?.name ?? ''}: ${finding.message ?? ''}`;
+}
+/** A completed rule with no objects checked, including older stored pass + checked 0 results. */
+export function hasNoObjects(result) {
+    return ['no_objects', 'pass'].includes(result.status ?? '') && (result.checked ?? 0) === 0;
+}
+/**
+ * Rule errors ("this rule could not run") and scope warnings ("part of your scope selected
+ * nothing") under their own headings, then the rules that inspected nothing.
+ */
+export function policyResultSummary(results = []) {
+    const where = (result) => `${result.policy_key ?? 'policy'} ${result.check_id ?? 'rule'}`;
+    const errors = results.filter(result => result.status === 'error')
+        .map(result => `  ${where(result)}: ${result.message ?? 'No diagnostic returned.'}`);
+    const warnings = results.flatMap(result => (result.warnings ?? []).map(warning => `  ${where(result)}: ${warning}`));
+    const lines = [];
+    if (errors.length > 0)
+        lines.push('Errors:', ...errors);
+    if (warnings.length > 0)
+        lines.push('Warnings:', ...warnings);
+    const checked = results.reduce((sum, result) => sum + (result.checked ?? 0), 0);
+    // When no rule checked anything, one sentence about the run says it all.
+    if (results.length > 0 && checked === 0) {
+        lines.push('No objects checked; this run does not demonstrate coverage.');
+        return lines;
+    }
+    const empty = results.filter(result => hasNoObjects(result));
+    if (empty.length > 0) {
+        lines.push('No objects checked (proves nothing about coverage):', ...empty.map(result => `  ${where(result)}: no objects checked`));
+    }
+    return lines;
+}

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

@@ -0,0 +1,161 @@
+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>;
+/**
+ * A change refused because it weakens a policy active and mandatory on the branch, from a caller
+ * without the `workspace:policy` update permission (`policy_weakening_permission_required`). A
+ * release deploy or archive import with set live adds the branch it landed, which stays.
+ */
+export interface WeakeningRefused {
+    message: string;
+    /** `unavailable`: the policies could not be read to check it, so only the permission proceeds (`policies` is empty). */
+    payload: {
+        branch?: {
+            id?: number;
+            label?: string;
+        };
+        code: string;
+        gate?: string;
+        level?: string;
+        permission?: string;
+        policies?: string[];
+        unavailable?: boolean;
+    };
+}
+/** The weakening refusal read from a failed response, or `null` for any other failure. */
+export declare function weakeningRefusal(response: Response): Promise<null | WeakeningRefused>;
+/** 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;