@xano/cli 1.3.1-beta.1 → 1.3.1

package/dist/utils/policy/feedback.js

@@ -1,165 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-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;

package/dist/utils/policy/gate.js

@@ -1,201 +0,0 @@
-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

@@ -1,46 +0,0 @@
-/** 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;