@xano/cli 1.3.1-beta.0 → 1.3.1

package/dist/utils/policy/goal.js

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

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

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

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

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

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

package/dist/utils/policy/release.js

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

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

@@ -1,55 +0,0 @@
-import type { ProfileConfig } from '../../base-command.js';
-import type { Policy } from './types.js';
-/** Query params; a list is sent as PHP reads one (`policy[0]=A&policy[1]=B`). */
-export type PolicyQuery = Record<string, string | string[]>;
-/** One request against a policy-family route: a path under it, a method, a JSON body and query params. */
-export type PolicyRequest = (path?: string, method?: string, body?: unknown, query?: PolicyQuery) => Promise<unknown>;
-/** What a request needs from the command that makes it. */
-export interface PolicyRequestHost {
-    error(message: string): never;
-    logToStderr(message: string): void;
-    verboseFetch(url: string, options: RequestInit, verbose: boolean, authToken?: string): Promise<Response>;
-}
-export interface PolicyRequestRoute {
-    branch: string;
-    /** How a failure introduces itself: `Policy request failed (403): …`. */
-    label: string;
-    /** The route under the workspace, e.g. `/policy`. */
-    path: string;
-    profile: ProfileConfig;
-    verbose: boolean;
-    workspace: string;
-}
-/** The route the `policy *` commands request. */
-export declare const POLICY_ROUTE: Pick<PolicyRequestRoute, 'label' | 'path'>;
-/** The workspace and branch a command targets: its flags first, then the profile. `-b ''` selects live. */
-export declare function policyScope(flags: {
-    branch?: string;
-    workspace?: string;
-}, profile: ProfileConfig): {
-    branch: string;
-    workspace: string;
-};
-/**
- * A request against a route gated by `workspace:policy`: failures are folded to the platform's code,
- * message and position, the token is redacted, and a coded refusal says what to do about it.
- */
-export declare function policyRequest(host: PolicyRequestHost, route: PolicyRequestRoute): PolicyRequest;
-/** What the policy list route answers this credential: it lists, the Policies feature is off, or it may not. */
-export type PolicyListing = 'feature_off' | 'listed' | 'refused';
-/**
- * Whether this credential can list the branch's policies. An export leaves out the policies its
- * credential cannot read, and every policy while the Policies feature is off, without refusing, so
- * this tells an export without policies from one that withheld them, and names the feature when
- * the platform's refusal does (`policy_feature_disabled`). Any other failure answers `refused`.
- */
-export declare function policyListing(host: Omit<PolicyRequestHost, 'error'>, route: Omit<PolicyRequestRoute, 'label' | 'path'>): Promise<PolicyListing>;
-/** The `items` of a list envelope, as every policy list route answers. */
-export declare function listItems<T>(data: unknown): T[];
-/**
- * Every policy on the target branch. The list route pages them (`page`, `nextPage`), so each page is
- * read in turn until the route names no next one.
- */
-export declare function listAllPolicies(request: PolicyRequest): Promise<Policy[]>;
-/** Whether two policy keys name the same policy: keys are unique on a branch without regard to case. */
-export declare function sameKey(key: string | undefined, other: string): boolean;

package/dist/utils/policy/request.js

@@ -1,115 +0,0 @@
-import { describePolicyError, policyCodeGuidance } from './errors.js';
-import { policyPermissionGuidance } from './permission.js';
-/** The route the `policy *` commands request. */
-export const POLICY_ROUTE = { label: 'Policy', path: '/policy' };
-/** The workspace and branch a command targets: its flags first, then the profile. `-b ''` selects live. */
-export function policyScope(flags, profile) {
-    // A workspace from profile.yaml or the credentials file can arrive from YAML as a number.
-    return { branch: flags.branch ?? profile.branch ?? '', workspace: String(flags.workspace || profile.workspace || '') };
-}
-/**
- * A request against a route gated by `workspace:policy`: failures are folded to the platform's code,
- * message and position, the token is redacted, and a coded refusal says what to do about it.
- */
-export function policyRequest(host, route) {
-    const { branch, label, profile, verbose, workspace } = route;
-    const base = `${profile.instance_origin}/api:meta/workspace/${workspace}${route.path}`;
-    return async (path = '', method = 'GET', body, query = {}) => {
-        const url = `${base}${path}?${queryString({ branch, ...query })}`;
-        const response = await host.verboseFetch(url, {
-            body: body === undefined ? undefined : JSON.stringify(body),
-            headers: {
-                accept: 'application/json',
-                Authorization: `Bearer ${profile.access_token}`,
-                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
-            },
-            method,
-        }, verbose, profile.access_token);
-        if (!response.ok) {
-            const text = (await response.text()).replaceAll(profile.access_token, '[REDACTED]');
-            if (verbose && text)
-                host.logToStderr(text);
-            const { message, payload } = describePolicyError(text, response.status, url);
-            const guidance = `${policyPermissionGuidance(response.status, payload)}${policyCodeGuidance(payload)}`;
-            host.error(`${label} request failed (${response.status}): ${message}${guidance}`);
-        }
-        // The DELETE route can answer with no body at all; every other route sends JSON.
-        const text = await response.text();
-        if (text.trim() === '')
-            return {};
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            return host.error(`${label} request to ${path || '/'} returned a ${response.status} that is not JSON.`);
-        }
-    };
-}
-function queryString(query) {
-    const params = new URLSearchParams();
-    for (const [name, value] of Object.entries(query)) {
-        if (Array.isArray(value))
-            for (const [index, item] of value.entries())
-                params.append(`${name}[${index}]`, item);
-        else
-            params.append(name, value);
-    }
-    return params;
-}
-/** A request host's `error` for a caller that asks rather than fails: it throws instead of exiting. */
-function fail(message) {
-    throw new Error(message);
-}
-/**
- * Whether this credential can list the branch's policies. An export leaves out the policies its
- * credential cannot read, and every policy while the Policies feature is off, without refusing, so
- * this tells an export without policies from one that withheld them, and names the feature when
- * the platform's refusal does (`policy_feature_disabled`). Any other failure answers `refused`.
- */
-export async function policyListing(host, route) {
-    let refusal;
-    const verboseFetch = async (...args) => {
-        const response = await host.verboseFetch(...args);
-        if (!response.ok)
-            refusal = await response.clone().json().catch(() => null);
-        return response;
-    };
-    const list = policyRequest({ ...host, error: fail, verboseFetch }, { ...route, ...POLICY_ROUTE });
-    return list().then(() => 'listed', () => refusalCode(refusal) === 'policy_feature_disabled' ? 'feature_off' : 'refused');
-}
-/** The `payload.code` of a refusal body, if it carries one. */
-function refusalCode(body) {
-    const payload = body && typeof body === 'object' ? body.payload : undefined;
-    return payload && typeof payload === 'object' ? payload.code : undefined;
-}
-/** The `items` of a list envelope, as every policy list route answers. */
-export function listItems(data) {
-    if (data && typeof data === 'object' && 'items' in data && Array.isArray(data.items))
-        return data.items;
-    throw new Error('The platform answered a list request without an items array.');
-}
-/**
- * Every policy on the target branch. The list route pages them (`page`, `nextPage`), so each page is
- * read in turn until the route names no next one.
- */
-export async function listAllPolicies(request) {
-    const policies = [];
-    let page = 1;
-    while (true) {
-        // Each page number comes from the previous response.
-        // eslint-disable-next-line no-await-in-loop
-        const listed = await request('', 'GET', undefined, { page: String(page) });
-        policies.push(...listItems(listed));
-        const { nextPage } = listed;
-        if (nextPage === undefined || nextPage === null)
-            return policies;
-        if (typeof nextPage !== 'number' || !Number.isSafeInteger(nextPage) || nextPage <= page) {
-            throw new Error('The platform returned an invalid next policy page.');
-        }
-        page = nextPage;
-    }
-}
-/** Whether two policy keys name the same policy: keys are unique on a branch without regard to case. */
-export function sameKey(key, other) {
-    return typeof key === 'string' && key.toLowerCase() === other.toLowerCase();
-}

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

@@ -1,30 +0,0 @@
-import type { PolicyRun, PolicyRunHead, PolicyRunSummary } from './types.js';
-/** The retained runs, as the run list summarises them, in a table, header first. */
-export declare function policyRunTable(runs: PolicyRunSummary[]): string[];
-/** Where a page of a run's findings sits among the findings that match its filters. */
-export interface PolicyRunPage {
-    /** Whether a filter narrowed the findings. */
-    filtered: boolean;
-    /** The command that reads this run's next page; `xano policy runs <id>` unless another is named. */
-    next?: string;
-    offset: number;
-    /** The findings that match, listed or not. */
-    total: number;
-}
-/**
- * One stored run. A run records its findings, results and the enforcement each policy had;
- * `policy_check.blocking` is the gate's verdict at the time and is not stored. With `page`, the
- * run's findings are one page of them (`GET run/{id}/findings`) and its counts are the summary's.
- */
-export declare function policyRunSummary(run: PolicyRunHead, page?: PolicyRunPage): string[];
-/**
- * The resolved settings a check ran with, as `settings: name=value, …`, sorted by name so output
- * is stable. Values that resolved to nothing are already omitted by the platform.
- */
-export declare function policySettings(params: unknown): string;
-/**
- * What a stored run recorded about the policies it evaluated: each policy's description as written
- * then, and each rule's name, settings and how many objects it inspected. Empty for a run that
- * evaluated no policy.
- */
-export declare function policyRunDetail(run?: PolicyRun): string[];