@xano/cli 1.3.4 → 1.3.5-beta.0

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

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

@@ -0,0 +1,119 @@
+import { describePolicyError, policyCodeGuidance, policyRefusal } 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);
+            // A refusal that names policies reads as the CLI's own sentence, not the coded message.
+            const plain = policyRefusal(payload);
+            if (plain)
+                host.error(plain);
+            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

@@ -0,0 +1,30 @@
+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[];

package/dist/utils/policy/runs.js

@@ -0,0 +1,101 @@
+import { findingLine, hasNoObjects, policyResultSummary, policyRuleName, ruleKey, snapshotRules } from './findings.js';
+const RUN_COLUMNS = [6, 8, 14, 12, 9, 0];
+const runRow = (cells) => cells.map((cell, index) => cell.padEnd(RUN_COLUMNS[index])).join('').trimEnd();
+/** The retained runs, as the run list summarises them, in a table, header first. */
+export function policyRunTable(runs) {
+    return [
+        runRow(['Run', 'Status', 'Findings', 'Checked', 'Trigger', 'Started']),
+        ...runs.map((run) => runRow([
+            String(run.id),
+            run.status,
+            `${run.counts.findings} findings`,
+            `${run.objects_checked} objects`,
+            run.trigger ?? '',
+            run.started_at ?? '',
+        ])),
+    ];
+}
+/**
+ * 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 function policyRunSummary(run, page) {
+    const when = [run.started_at, run.finished_at].filter(Boolean).join(' → ');
+    const checked = typeof run.objects_checked === 'number' ? `  ${run.objects_checked} objects checked` : '';
+    const lines = [`Run ${run.id ?? '?'}  ${run.status ?? 'unknown'}${run.trigger ? `  ${run.trigger}` : ''}${when ? `  ${when}` : ''}${checked}`];
+    const rules = snapshotRules(run.policies ?? []);
+    const findings = run.findings ?? [];
+    if (page)
+        lines.push(...pageLines(run, page));
+    else if (findings.length > 0)
+        lines.push(`Findings (${findings.length}):`, ...findings.map(finding => findingLine(finding, rules)));
+    else
+        lines.push('No findings.');
+    lines.push(...policyResultSummary(run.results));
+    return lines;
+}
+/** The run's counts, then one page of its findings and how to read the next. */
+function pageLines(run, page) {
+    const rules = snapshotRules(run.policies ?? []);
+    const findings = run.findings ?? [];
+    const { counts } = run;
+    const lines = counts && counts.findings > 0
+        ? [`Findings: ${counts.findings} (${counts.blocking} blocking, ${counts.advisory ?? counts.findings - counts.blocking} advisory)`]
+        : [];
+    if (findings.length === 0) {
+        lines.push(page.total > 0 ? `No findings from offset ${page.offset}: ${page.total} ${page.filtered ? 'match' : 'in all'}.`
+            : (page.filtered ? 'No findings match.' : 'No findings.'));
+        return lines;
+    }
+    const next = page.offset + findings.length;
+    // A page that is not every finding says so, and how to read the rest.
+    const partial = page.offset > 0 || next < page.total;
+    lines.push(`Findings ${page.offset + 1}-${next} of ${page.total}${page.filtered ? ' matching' : ''}${partial ? ' (one page)' : ''}:`, ...findings.map(finding => findingLine(finding, rules)));
+    if (next < page.total) {
+        lines.push(`Next page: \`${page.next ?? `xano policy runs ${run.id}`} --offset ${next}\`, or --all for all ${page.total}${page.filtered ? ', with the same filters' : ''}.`);
+    }
+    return lines;
+}
+function settingValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map(item => settingValue(item)).join(', ')}]`;
+    if (value !== null && typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * 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 function policySettings(params) {
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return '';
+    const entries = Object.entries(params).sort(([a], [b]) => a.localeCompare(b));
+    return entries.length === 0 ? '' : `settings: ${entries.map(([name, value]) => `${name}=${settingValue(value)}`).join(', ')}`;
+}
+/**
+ * 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 function policyRunDetail(run) {
+    const results = new Map((run?.results ?? []).map(result => [ruleKey(result.policy_key, result.check_id), result]));
+    const body = (run?.policies ?? []).flatMap(policy => {
+        const statement = policy.statement?.trim();
+        const rules = (policy.rules ?? []).map(rule => {
+            // The name falls back to the id, which the line already carries.
+            const name = policyRuleName(rule);
+            const result = results.get(ruleKey(policy.key, rule.id));
+            const inspected = result?.checked === undefined ? '' : (hasNoObjects(result) ? 'no objects checked' : `checked ${result.checked}`);
+            return `    ${[rule.id, name === rule.id ? '' : name, policySettings(rule.params) || 'settings: none', inspected]
+                .filter(Boolean).join('  ')}`;
+        });
+        return [`  ${policy.key ?? 'policy'}${statement ? `  ${statement}` : ''}`, ...rules];
+    });
+    if (body.length === 0)
+        return [];
+    const provenance = [run?.trigger, run?.started_at].filter(Boolean).join(', ');
+    const heading = run?.id ? `Run ${run.id} as recorded` : 'This evaluation, which was not stored';
+    return [`${heading}${provenance ? ` (${provenance})` : ''}:`, ...body];
+}

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

@@ -0,0 +1,55 @@
+import type { Policy, PolicyRunHead } from './types.js';
+/**
+ * Where a policy stands against the latest run. `stale` means the run evaluated a different
+ * version; `not_evaluated` that it has no result for every rule.
+ */
+export type PolicyStatus = 'error' | 'fail' | 'inactive' | 'no_checks' | 'no_objects_checked' | 'not_evaluated' | 'pass' | 'stale';
+export interface PolicyStatusRow {
+    /** Whether the policy is active. */
+    active: boolean;
+    /**
+     * Whether the latest run's findings on this policy block a merge: the run evaluated it, in its
+     * current version, as active and blocking (the platform's `latest_run.enforcement`), and found something.
+     */
+    blocking: boolean;
+    checked: number;
+    /** Whether `findings` and `checked` come from the latest run: only for an active policy it evaluated in its current version. */
+    counted: boolean;
+    /** The policy's own enforcement (`blocking` / `advisory`). */
+    enforcement: string;
+    findings: number;
+    key: string;
+    /** Completed rules that inspected no objects. */
+    rules_unchecked: number;
+    /** The platform's answer: the latest run evaluated a different version of this policy. */
+    stale: boolean;
+    status: PolicyStatus;
+    title?: string;
+}
+/** How a row's status reads in the summary table. */
+export declare function statusLabel(row: PolicyStatusRow): string;
+/** The policy's own enforcement, in Studio's words. Whether its findings block is `findingsLabel`'s to say. */
+export declare function enforcementLabel(enforcement: string): string;
+/**
+ * The enforcement column of a status row, worded as Studio's list words it: an inactive policy
+ * reads `Inactive` whatever its enforcement, so it never reads as blocking.
+ */
+export declare function enforcementColumn(row: Pick<PolicyStatusRow, 'active' | 'enforcement'>): string;
+/**
+ * `3 findings`, marked blocking when they block. A row the latest run did not count says so: an active
+ * policy is `not checked yet` (never evaluated, or changed since), an inactive one `not checked`.
+ */
+export declare function findingsLabel(row: PolicyStatusRow): string;
+/**
+ * Combine the branch's policies with the latest stored run. Whether the run is still evidence for a
+ * policy is the platform's `latest_run` answer; only an active policy the run evaluated in its
+ * current version carries counts.
+ */
+export declare function computeStatusRows(policies: Policy[], run?: PolicyRunHead): PolicyStatusRow[];
+/**
+ * `--fail-on-findings`: 2 for a current blocking finding, whatever else is true, as push and evaluate
+ * exit; otherwise 1 for stale, missing or errored evidence.
+ */
+export declare function statusExitCode(rows: PolicyStatusRow[]): number;
+/** Why `--fail-on-findings` failed, in one line naming the policies, or `null` when it did not. */
+export declare function statusExitReason(rows: PolicyStatusRow[]): null | string;

package/dist/utils/policy/status.js

@@ -0,0 +1,127 @@
+import { hasNoObjects } from './findings.js';
+/** How a row's status reads in the summary table. */
+export function statusLabel(row) {
+    switch (row.status) {
+        case 'inactive': {
+            return 'inactive; not evaluated';
+        }
+        case 'pass': {
+            return row.rules_unchecked > 0
+                ? `pass; ${row.rules_unchecked} rule${row.rules_unchecked === 1 ? '' : 's'} no objects checked`
+                : 'pass';
+        }
+        case 'stale': {
+            return 'outdated; evaluate again';
+        }
+        default: {
+            return row.status.replaceAll('_', ' ');
+        }
+    }
+}
+/** The policy's own enforcement, in Studio's words. Whether its findings block is `findingsLabel`'s to say. */
+export function enforcementLabel(enforcement) {
+    if (enforcement === 'blocking')
+        return 'Blocking';
+    if (enforcement === 'advisory')
+        return 'Advisory';
+    return enforcement.trim() || '—';
+}
+/**
+ * The enforcement column of a status row, worded as Studio's list words it: an inactive policy
+ * reads `Inactive` whatever its enforcement, so it never reads as blocking.
+ */
+export function enforcementColumn(row) {
+    return row.active ? enforcementLabel(row.enforcement) : 'Inactive';
+}
+/**
+ * `3 findings`, marked blocking when they block. A row the latest run did not count says so: an active
+ * policy is `not checked yet` (never evaluated, or changed since), an inactive one `not checked`.
+ */
+export function findingsLabel(row) {
+    if (!row.counted)
+        return row.status === 'inactive' ? 'not checked' : 'not checked yet';
+    return `${row.findings} findings${row.blocking ? ' (blocking)' : ''}`;
+}
+/** Where an active policy stands, given its rule results in a run that is still evidence for it. */
+function ruleStatus(results, ruleCount, checked) {
+    if (ruleCount === 0)
+        return 'no_checks';
+    if (results.length === 0)
+        return 'not_evaluated';
+    if (results.some((result) => !['fail', 'no_objects', 'pass'].includes(result.status ?? '')))
+        return 'error';
+    if (results.some((result) => result.status === 'fail'))
+        return 'fail';
+    if (results.length < ruleCount)
+        return 'not_evaluated';
+    return checked === 0 ? 'no_objects_checked' : 'pass';
+}
+/**
+ * A policy's finding count in a run: its verdict in the run summary, which counts them all without
+ * listing them, or, from a whole run, its findings counted.
+ */
+function findingCount(run, key) {
+    const verdict = (run?.policies ?? []).find((policy) => policy.key === key);
+    if (typeof verdict?.findings === 'number')
+        return verdict.findings;
+    return (run?.findings ?? []).filter((finding) => finding.policy_key === key).length;
+}
+/**
+ * Combine the branch's policies with the latest stored run. Whether the run is still evidence for a
+ * policy is the platform's `latest_run` answer; only an active policy the run evaluated in its
+ * current version carries counts.
+ */
+export function computeStatusRows(policies, run) {
+    return policies.map((policy) => {
+        const ids = new Set((policy.rules ?? []).map((rule) => rule.id));
+        const active = policy.active !== false;
+        const stale = policy.latest_run?.stale === true;
+        const counted = active && policy.latest_run?.included === true && !stale;
+        const results = counted
+            ? (run?.results ?? []).filter((result) => result.policy_key === policy.key && ids.has(result.check_id ?? ''))
+            : [];
+        const checked = results.reduce((sum, result) => sum + (result.checked ?? 0), 0);
+        const findings = counted ? findingCount(run, policy.key) : 0;
+        let status = 'inactive';
+        if (active)
+            status = stale ? 'stale' : ruleStatus(results, ids.size, checked);
+        return {
+            active: policy.active,
+            blocking: counted && policy.latest_run?.enforcement === 'blocking' && findings > 0,
+            checked,
+            counted,
+            enforcement: policy.enforcement,
+            findings,
+            key: policy.key,
+            rules_unchecked: status === 'pass' ? results.filter((result) => hasNoObjects(result)).length : 0,
+            stale,
+            status,
+            title: policy.title,
+        };
+    });
+}
+/** The rows whose evidence cannot be relied on: stale, missing or errored. An inactive policy is never evaluated. */
+function unreliableRows(rows) {
+    return rows.filter((row) => ['error', 'not_evaluated', 'stale'].includes(row.status));
+}
+/**
+ * `--fail-on-findings`: 2 for a current blocking finding, whatever else is true, as push and evaluate
+ * exit; otherwise 1 for stale, missing or errored evidence.
+ */
+export function statusExitCode(rows) {
+    if (rows.some((row) => row.blocking))
+        return 2;
+    return unreliableRows(rows).length > 0 ? 1 : 0;
+}
+/** Why `--fail-on-findings` failed, in one line naming the policies, or `null` when it did not. */
+export function statusExitReason(rows) {
+    const unreliable = unreliableRows(rows);
+    const evidence = unreliable.map((row) => `${row.key} ${statusLabel(row)}`).join(', ');
+    const blocking = rows.filter((row) => row.blocking);
+    if (blocking.length === 0) {
+        return unreliable.length > 0 ? `Evaluation evidence is stale, missing or errored (${evidence}); exit 1.` : null;
+    }
+    const findings = blocking.reduce((sum, row) => sum + row.findings, 0);
+    // A prediction, not a verdict: the merge gate evaluates the branch again.
+    return `The latest run has ${findings} blocking finding${findings === 1 ? '' : 's'} (${blocking.map((row) => row.key).join(', ')}); the merge gate evaluates the branch again before a merge.${unreliable.length > 0 ? ` Evidence is also stale, missing or errored (${evidence}).` : ''}`;
+}

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

@@ -0,0 +1,66 @@
+import type { PolicyRecipe } from './catalogue.js';
+import type { PolicyCatalogueEntry } from './types.js';
+/** Templates and sparse parameter seeds come from the instance's catalogue. */
+export interface PolicyTemplate {
+    /** The id of the group the catalogue files the template under (`access_control`…; labels in `template_categories`). */
+    category?: string;
+    /** Example values that fit this template, by `needs` path: a hint for `--param`, never a value it fills. */
+    examples?: Record<string, unknown>;
+    /** Framework tag ids (`soc2`…; labels in `template_frameworks`): topics the template relates to, never a compliance claim. */
+    frameworks?: string[];
+    id: string;
+    key: string;
+    /** `needs`: the param paths the author fills, every one of them unless `needs_any` says one is enough. */
+    rules: Array<{
+        check: string;
+        needs: string[];
+        needs_any?: boolean;
+        params: Record<string, unknown>;
+        title: string;
+    }>;
+    severity: string;
+    summary: string;
+    /** Becomes the policy title. */
+    title: string;
+}
+/**
+ * The refusal of a recipe id given to `--template`: recipes have no create action, so it names the
+ * recipe's templates in the order to create them and, when it has rules no template covers, where
+ * they are shown.
+ */
+export declare function recipeRefusal(recipe: PolicyRecipe): 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 template becomes a policy: the key, the catalogue's key rule and the `--param` assignments. */
+export interface TemplatePolicyOptions {
+    /** The fetched catalogue's checks: a need the template gives no example for shows its check's own `example`. */
+    checks?: PolicyCatalogueEntry[];
+    /** `--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 template becomes, for the parse route's `data`. */
+export interface TemplatePolicyDocument {
+    key: string;
+    rules: Array<{
+        check: string;
+        params: Record<string, unknown>;
+        title: string;
+    }>;
+    severity: string;
+    statement: string;
+    title: string;
+}
+/**
+ * The policy document for a template: its sparse settings with the `--param` assignments applied, every
+ * `needs` path filled (at least one of a rule's when it says `needs_any`), and a key no policy on the
+ * branch holds (compared case-insensitively). A taken template key gets a free numeric suffix; a taken or
+ * malformed `--key` is refused.
+ */
+export declare function policyFromTemplate(template: PolicyTemplate, takenKeys: string[], options?: TemplatePolicyOptions): TemplatePolicyDocument;