@xano/cli 1.3.4 → 1.3.5-beta.0

package/dist/utils/multidoc-push.js

@@ -1,4 +1,4 @@
-import { ux } from '@oclif/core';
+import { Errors, ux } from '@oclif/core';
 import { minimatch } from 'minimatch';
 import * as fs from 'node:fs';
 import { join, relative } from 'node:path';
@@ -7,9 +7,21 @@ import { compareLocalToExport, indexLocalDocuments, parseExportDocuments, resolv
 import { flattenBundleFile } from './flatten.js';
 import { collectKnowledgeObjects, fetchKnowledge, knowledgePreview, pushKnowledge, syncGuidToFrontmatter, toPushItems, } from './knowledge-sync.js';
 import { fetchFormattedObjects, } from './object-fetch.js';
+import { PushPolicyGateError } from './policy/push-gate.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
 import { invalidateSandboxMarkerForOrigin, readMarkerToken, sandboxMarkerExists, writeMarkerToken, } from './sandbox-marker.js';
 import { hashBytes, hashFile, instanceHost, loadSyncState, recordEntriesForContents, resolveTarget, sandboxTargetIdentity, saveSyncState, syncStateExists, toRelPath, } from './sync-state.js';
+/**
+ * A push that failed after its multidoc import landed. The import is not rolled back, so the error
+ * carries what it did for the calling command to report beside the failure.
+ */
+export class FailedAfterImportError extends Errors.CLIError {
+    imported;
+    constructor(message, imported) {
+        super(message);
+        this.imported = imported;
+    }
+}
 /**
  * Filter document entries down to the ones the dry-run preview reports as changed,
  * used to send only the changed documents during a partial (non-`--sync`) push.
@@ -712,7 +724,9 @@ function mergeKnowledgePreview(preview, knowledge) {
  */
 export async function executePush(ctx, target, flags) {
     const { accessToken, command, inputDir, verboseFetch } = ctx;
-    const log = command.log.bind(command);
+    const log = ctx.log ?? command.log.bind(command);
+    let dryRunPreview = null;
+    const stop = (stopped) => ({ knowledge: { deleted: 0, imported: 0 }, preview: dryRunPreview, sent: [], stopped });
     if (flags.fast && flags.sync) {
         command.error('--fast cannot be used with --sync');
     }
@@ -781,7 +795,7 @@ export async function executePush(ctx, target, flags) {
                 const doFlatten = await confirm('Flatten these file(s) in place and continue the push?');
                 if (!doFlatten) {
                     log('Push cancelled. Run `xano flatten <file>` yourself, or re-run to be prompted again.');
-                    return;
+                    return stop('cancelled');
                 }
             }
             else {
@@ -949,7 +963,7 @@ export async function executePush(ctx, target, flags) {
                     }
                     log('');
                     log('No changes to push.');
-                    return;
+                    return stop('no-changes');
                 }
                 documentEntries = candidates;
                 recordSourceEntries = [...documentEntries];
@@ -994,7 +1008,7 @@ export async function executePush(ctx, target, flags) {
             recordSourceEntries = [...documentEntries];
             if (documentEntries.length === 0 && knowledgeObjects.length === 0) {
                 log('No local changes since last sync');
-                return;
+                return stop('no-changes');
             }
             multidoc = documentEntries.map((entry) => entry.content).join('\n---\n');
             documentFileMap.clear();
@@ -1048,7 +1062,6 @@ export async function executePush(ctx, target, flags) {
         'Content-Type': 'text/x-xanoscript',
     };
     // ── Dry-run / Preview ─────────────────────────────────────────────────
-    let dryRunPreview = null;
     const dryRunUrl = knowledgeOnly ? null : target.buildDryRunUrl(queryParams);
     if (dryRunUrl && (flags['dry-run'] || !flags.force)) {
         const dryRunParams = new URLSearchParams(queryParams);
@@ -1140,7 +1153,7 @@ export async function executePush(ctx, target, flags) {
                         log('');
                         log(ux.colorize('red', `Push blocked: ${criticalOps.length} critical error(s) found.`));
                         if (!flags.force) {
-                            return;
+                            return stop('blocked');
                         }
                         log(ux.colorize('yellow', 'Proceeding anyway due to --force flag.'));
                     }
@@ -1173,10 +1186,10 @@ export async function executePush(ctx, target, flags) {
                         if (persistRecord) {
                             commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(recordSourceEntries.map((entry) => entry.filePath)), { pruneMissing, replace: replaceRecord() }, (message) => command.warn(message));
                         }
-                        return;
+                        return stop('no-changes');
                     }
                     if (flags['dry-run']) {
-                        return;
+                        return stop('dry-run');
                     }
                     // Warn when the sandbox currently holds a different source workspace than the one being
                     // pushed. The backend compares the source workspace id we sent against the id stored on
@@ -1194,7 +1207,7 @@ export async function executePush(ctx, target, flags) {
                             const proceed = await confirm('Continue with push anyway?');
                             if (!proceed) {
                                 log('Push cancelled. Run `xano sandbox reset` then retry.');
-                                return;
+                                return stop('cancelled');
                             }
                             mismatchConfirmed = true;
                         }
@@ -1215,7 +1228,7 @@ export async function executePush(ctx, target, flags) {
                             const confirmed = await confirm(message);
                             if (!confirmed) {
                                 log('Push cancelled.');
-                                return;
+                                return stop('cancelled');
                             }
                         }
                         else {
@@ -1232,15 +1245,17 @@ export async function executePush(ctx, target, flags) {
                 }
             }
             else {
-                await handleDryRunError(dryRunResponse, command, flags, target);
+                await handleDryRunError(dryRunResponse, command, target, { log, verbose: flags.verbose });
                 // If we get here, the user confirmed to proceed without preview
             }
         }
         catch (error) {
             // Ctrl+C or SIGINT
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error.name === 'AbortError' || error.code === 'ERR_USE_AFTER_CLOSE') {
                 log('\nPush cancelled.');
-                return;
+                return stop('cancelled');
             }
             // Re-throw oclif errors
             if (error instanceof Error && 'oclif' in error) {
@@ -1271,16 +1286,16 @@ export async function executePush(ctx, target, flags) {
         if (!hasChanges) {
             log('');
             log('No changes to push.');
-            return;
+            return stop('no-changes');
         }
         if (flags['dry-run']) {
-            return;
+            return stop('dry-run');
         }
         if (process.stdin.isTTY) {
             const confirmed = await confirm('Proceed with push?');
             if (!confirmed) {
                 log('Push cancelled.');
-                return;
+                return stop('cancelled');
             }
         }
         else {
@@ -1296,24 +1311,24 @@ export async function executePush(ctx, target, flags) {
         }
     }
     // ── Partial push: filter to changed documents only ────────────────────
-    let pushedEntries = documentEntries;
+    let sent = documentEntries;
     if (!knowledgeOnly && isPartial && dryRunPreview) {
-        pushedEntries = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
-        if (pushedEntries.length === 0 && knowledgeObjects.length === 0) {
+        sent = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
+        if (sent.length === 0 && knowledgeObjects.length === 0) {
             log('No changes to push.');
             if (persistRecord) {
                 commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(recordSourceEntries.map((entry) => entry.filePath)), { pruneMissing: false, replace: replaceRecord() }, (message) => command.warn(message));
             }
-            return;
+            return stop('no-changes');
         }
-        multidoc = pushedEntries.length > 0 ? pushedEntries.map((d) => d.content).join('\n---\n') : '';
+        multidoc = sent.map((d) => d.content).join('\n---\n');
     }
     const persist = () => {
         if (!persistRecord || !ctx.syncTarget)
             return;
         const paths = [
             ...recordSourceEntries.map((entry) => entry.filePath),
-            ...pushedEntries.map((entry) => entry.filePath),
+            ...sent.map((entry) => entry.filePath),
         ];
         commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(paths), { pruneMissing, replace: replaceRecord() }, (message) => command.warn(message));
     };
@@ -1325,6 +1340,7 @@ export async function executePush(ctx, target, flags) {
     }
     const startTime = Date.now();
     let pushedDocCount = 0;
+    let pushResponse;
     if (!knowledgeOnly && multidoc) {
         const apiUrl = target.buildPushUrl(queryParams);
         try {
@@ -1334,14 +1350,19 @@ export async function executePush(ctx, target, flags) {
                 method: 'POST',
             }, flags.verbose, accessToken);
             if (!response.ok) {
-                handlePushError(response, await response.text(), documentEntries, inputDir, command);
+                const errorText = await response.text();
+                refuseIfExplained(command, target, response.status, errorText);
+                handlePushError(response, errorText, documentEntries, inputDir, command);
             }
             // Parse response for GUID map
             const responseText = await response.text();
             let guidMap = [];
+            pushResponse = {};
             if (responseText && responseText !== 'null') {
                 try {
                     const responseJson = JSON.parse(responseText);
+                    if (responseJson && typeof responseJson === 'object')
+                        pushResponse = responseJson;
                     if (responseJson?.guid_map && Array.isArray(responseJson.guid_map)) {
                         guidMap = responseJson.guid_map;
                     }
@@ -1367,7 +1388,7 @@ export async function executePush(ctx, target, flags) {
                 let updatedCount = 0;
                 let canonicalCount = 0;
                 for (const entry of guidMap) {
-                    if (!entry.guid)
+                    if (!entry.guid || entry.type === 'policy')
                         continue;
                     const key = buildDocumentKey(entry.type, entry.name, entry.verb, entry.api_group);
                     let filePath = documentFileMap.get(key);
@@ -1416,6 +1437,8 @@ export async function executePush(ctx, target, flags) {
             pushedDocCount = multidoc.split('\n---\n').length;
         }
         catch (error) {
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
@@ -1435,8 +1458,9 @@ export async function executePush(ctx, target, flags) {
             includeRecords: flags.records,
             inputDir,
             isLiveBranch: resolved.isLiveBranch,
+            log,
             pushedBytes,
-            pushedEntries,
+            pushedEntries: sent,
             resolvedTarget,
             syncState: loadedState,
             target,
@@ -1455,6 +1479,12 @@ export async function executePush(ctx, target, flags) {
     // ── Push knowledge ────────────────────────────────────────────────────
     let knowledgeImported = 0;
     let knowledgeDeleted = 0;
+    const pushed = () => ({
+        knowledge: { deleted: knowledgeDeleted, imported: knowledgeImported },
+        preview: dryRunPreview,
+        response: pushResponse,
+        sent: pushResponse ? sent : [],
+    });
     if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
         const listUrl = ctx.knowledge.listUrl();
         try {
@@ -1492,7 +1522,10 @@ export async function executePush(ctx, target, flags) {
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
-            command.error(`Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`);
+            const message = `Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`;
+            if (pushResponse)
+                throw new FailedAfterImportError(message, pushed());
+            command.error(message);
         }
     }
     const elapsed = (Math.max(0, Date.now() - startTime - writebackMs) / 1000).toFixed(1);
@@ -1507,11 +1540,12 @@ export async function executePush(ctx, target, flags) {
     }
     persist();
     log(`Pushed ${parts.join(' + ')} to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
+    return pushed();
 }
 export async function writeBackFormattedDocuments(args) {
     const started = Date.now();
     const { accessToken, branch, command, includeEnv, includeRecords, inputDir, isLiveBranch = !branch, pushedBytes, resolvedTarget, syncState, target, verbose, verboseFetch, workspaceId, writebackDiff, writebackObjectLimit, } = args;
-    const log = command.log.bind(command);
+    const log = args.log ?? command.log.bind(command);
     const elapsedLabel = () => ` (${((Date.now() - started) / 1000).toFixed(1)}s)`;
     const ids = {};
     const written = [];
@@ -1774,10 +1808,37 @@ function formatFailureDuration(elapsedMs) {
         ? ` (failed after ~${human}, near a common ${boundaries.find((b) => Math.abs(totalSeconds - b) <= b * 0.05)}s timeout — likely a server or proxy cutoff)`
         : ` (failed after ${human})`;
 }
-async function handleDryRunError(response, command, flags, target) {
-    const log = command.log.bind(command);
+/** Stop with the target's own guidance when it recognises this refusal. */
+function refuseIfExplained(command, target, status, body) {
+    let message = body;
+    let payload;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.message === 'string')
+            message = parsed.message;
+        payload = parsed?.payload;
+    }
+    catch {
+        // Not JSON
+    }
+    const refusal = payload;
+    if (status === 403 && refusal?.code === 'policy_gate')
+        throw new PushPolicyGateError(refusal, message === body ? undefined : message);
+    // The plan's policy cap: the platform's message names the plan, its cap and the remedy, and the
+    // push itself would be refused the same way, so the preview stops here rather than skipping.
+    if (status === 403 && refusal?.code === 'policy_plan_limit')
+        command.error(`Push refused (${status}): ${message}`);
+    if (refusal?.code === 'policy_gate_transaction_required') {
+        command.error('Push refused: the live branch policy gate requires a transaction. Remove --no-transaction and retry. Nothing was imported.');
+    }
+    const guidance = target.explainRefusal?.(status, payload);
+    if (guidance)
+        command.error(`Push refused (${status}): ${message}${guidance}`);
+}
+async function handleDryRunError(response, command, target, { log, verbose }) {
+    const errorText = await response.text();
+    refuseIfExplained(command, target, response.status, errorText);
     if (response.status === 404) {
-        const errorText = await response.text();
         try {
             const errorJson = JSON.parse(errorText);
             if (errorJson.message) {
@@ -1795,7 +1856,6 @@ async function handleDryRunError(response, command, flags, target) {
         log('');
     }
     else {
-        const errorText = await response.text();
         // Check if push is disabled
         try {
             const errorJson = JSON.parse(errorText);
@@ -1818,8 +1878,17 @@ async function handleDryRunError(response, command, flags, target) {
         catch {
             // Not JSON, fall through
         }
-        command.warn(`Push preview failed (${response.status}). Skipping preview.`);
-        if (flags.verbose) {
+        let reason = '';
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (typeof errorJson?.message === 'string' && errorJson.message.trim())
+                reason = `: ${errorJson.message.trim().replace(/\.$/, '')}`;
+        }
+        catch {
+            // Not JSON
+        }
+        command.warn(`Push preview failed (${response.status})${reason}. Skipping preview.`);
+        if (verbose) {
             log(ux.colorize('dim', errorText));
         }
     }

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

@@ -0,0 +1,85 @@
+import type { PolicyTemplate } from './template.js';
+import type { PolicyCatalogueEntry } from './types.js';
+/**
+ * `--check` narrows the catalogue to one check. An id that is not in it names the closest matches
+ * instead of reprinting the whole list: the usual mistake is a typo one character from a real id.
+ */
+export declare function selectCatalogueCheck(checks: PolicyCatalogueEntry[], id: string): PolicyCatalogueEntry[];
+/** `--recipe` narrows the catalogue's recipes to one, refusing an unknown id as `--check` does. */
+export declare function selectCatalogueRecipe(recipes: PolicyRecipe[], id: string): PolicyRecipe[];
+/**
+ * The checks as a table of id, label and description, object kinds and required params, each row
+ * followed by the check's `uses`: a goal, the params that achieve it (one line of JSON to copy) and
+ * its note.
+ */
+export declare function policyCatalogueSummary(checks: PolicyCatalogueEntry[]): string[];
+/** The catalogue's `template_categories`: the groups templates are filed under, in the order to offer them. */
+export interface PolicyTemplateCategory {
+    id: string;
+    label: string;
+}
+/** The catalogue's `template_frameworks`: the framework tags a template can carry, in order, with their labels. */
+export interface PolicyTemplateFramework {
+    id: string;
+    label: string;
+}
+/**
+ * The catalogue's templates, grouped under their `category` in the order `template_categories`
+ * lists them, each group named by its label. A category the list does not name follows in the order
+ * first seen, named by its id; a template without one (an older instance) is listed under "Other".
+ * Each row names the id `policy create --template` takes, the title, what it would create and its
+ * framework tags by label (an unknown id as itself). When any row has a tag, the catalogue's
+ * `template_frameworks_note` follows the heading, worded by the platform rather than here; an
+ * instance that serves no note gets no tags, since a tag must never show without it.
+ */
+export declare function policyTemplateSummary(templates: PolicyTemplate[], categories?: PolicyTemplateCategory[], frameworks?: PolicyTemplateFramework[], frameworksNote?: string): string[];
+/**
+ * One of the catalogue's `recipes`: a goal spanning several templates, served as data. There is no
+ * recipe object and no create action: an author creates its `templates` in order, one policy each,
+ * then its `rules` together in a policy of their own.
+ */
+export interface PolicyRecipe {
+    /** Framework tag ids, as a template's: topics it relates to, never a compliance claim. */
+    frameworks?: string[];
+    id: string;
+    keywords?: string[];
+    /** `not_checkable` ids: what no rule in the recipe can see. */
+    limits?: string[];
+    /** What the author does first: the tags, fields and functions the rules depend on. */
+    prerequisites?: string[];
+    /** Rules no template covers, shaped like a template's; `needs` are the params the author fills. */
+    rules?: Array<{
+        check: string;
+        needs?: string[];
+        params?: Record<string, unknown> | unknown[];
+        title: string;
+    }>;
+    summary?: string;
+    /** Template ids, in the order to create them. */
+    templates?: string[];
+    /** The goal, never a framework name. */
+    title: string;
+}
+/** One of the catalogue's `not_checkable` entries: a topic no check can see, and why. */
+export interface PolicyNotCheckable {
+    id: string;
+    keywords?: string[];
+    topic: string;
+    why: string;
+}
+/** What the recipe section reads beside the recipes: templates by id, tags, and the not-checkable topics. */
+export interface PolicyRecipeContext {
+    frameworks?: PolicyTemplateFramework[];
+    frameworksNote?: string;
+    notCheckable?: PolicyNotCheckable[];
+    templates?: PolicyTemplate[];
+}
+/**
+ * The catalogue's recipes, each with its title, tags, summary, what to do first, its templates in
+ * order (each with its key and title, so `policy create --template` can take it from here), the rules
+ * no template covers (their params as JSON and what the author fills in) and the topics no rule in it
+ * can see. The framework note follows the heading when any recipe shows a tag, as for templates.
+ */
+export declare function policyRecipeSummary(recipes: PolicyRecipe[], context?: PolicyRecipeContext): string[];
+/** The catalogue's `not_checkable`: each topic no check can see, by id, with why. */
+export declare function policyNotCheckableSummary(entries: PolicyNotCheckable[]): string[];

package/dist/utils/policy/catalogue.js

@@ -0,0 +1,196 @@
+/**
+ * `--check` narrows the catalogue to one check. An id that is not in it names the closest matches
+ * instead of reprinting the whole list: the usual mistake is a typo one character from a real id.
+ */
+export function selectCatalogueCheck(checks, id) {
+    return selectById(checks, id, 'a policy check');
+}
+/** `--recipe` narrows the catalogue's recipes to one, refusing an unknown id as `--check` does. */
+export function selectCatalogueRecipe(recipes, id) {
+    return selectById(recipes, id, 'a recipe');
+}
+function selectById(entries, id, noun) {
+    const wanted = id.trim().toLowerCase();
+    const exact = entries.filter(entry => entry.id.toLowerCase() === wanted);
+    if (exact.length > 0)
+        return exact;
+    const near = entries.map(entry => entry.id).filter(known => {
+        const lower = known.toLowerCase();
+        return lower.includes(wanted) || wanted.includes(lower) || editDistanceWithin(lower, wanted, 2);
+    }).sort();
+    throw new Error(`"${id}" is not ${noun}.${near.length > 0
+        ? ` Did you mean ${near.join(', ')}?`
+        : ' Run `xano policy catalogue` for the full list.'}`);
+}
+/** Cheap bounded Levenshtein: true when `a` and `b` are at most `max` edits apart. */
+function editDistanceWithin(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return false;
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = a[i - 1] === b[j - 1]
+                ? previous[j - 1]
+                : 1 + Math.min(previous[j - 1], previous[j], current[j - 1]);
+        }
+        if (Math.min(...current) > max)
+            return false;
+        previous = current;
+    }
+    return previous[b.length] <= max;
+}
+/** How wide a full-width line (a use, a recipe) is wrapped; the check table is its own columns. */
+const LINE_WIDTH = 120;
+/**
+ * The checks as a table of id, label and description, object kinds and required params, each row
+ * followed by the check's `uses`: a goal, the params that achieve it (one line of JSON to copy) and
+ * its note.
+ */
+export function policyCatalogueSummary(checks) {
+    if (checks.length === 0)
+        return ['No policy checks found.'];
+    const rows = [
+        ['Check ID', 'Label / Description', 'Object kinds', 'Required params'],
+        ...checks.map(check => [
+            check.id,
+            [check.label.trim(), check.description, check.fix_hint && `Fix hint: ${check.fix_hint}`].filter(Boolean).join('\n'),
+            (check.object_kinds ?? []).join(', ') || '—',
+            requiredParams(check),
+        ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.min([36, 46, 24, 32][column], Math.max(...rows.map(row => row[column].length))));
+    return rows.flatMap((row, index) => {
+        const cells = row.map((cell, column) => cell.split('\n').flatMap(paragraph => wrap(paragraph, widths[column])));
+        const lines = Array.from({ length: Math.max(...cells.map(cell => cell.length)) }, (_, line) => cells.map((cell, column) => (cell[line] ?? '').padEnd(widths[column])).join('  ').trimEnd());
+        return index === 0 ? lines : [...lines, ...useLines(checks[index - 1].uses)];
+    });
+}
+/** A check's uses under its row: `Use: goal`, the params as JSON, then `Note: …` when it has one. */
+function useLines(uses) {
+    if (!Array.isArray(uses))
+        return [];
+    return uses.flatMap(use => [
+        ...hanging('  Use: ', use.goal),
+        `       ${JSON.stringify(Array.isArray(use.params) ? {} : use.params ?? {})}`,
+        ...(use.note ? hanging('       Note: ', use.note, '       ') : []),
+    ]);
+}
+/** Words wrapped at `width`; a word longer than the width keeps a line of its own. */
+function wrap(text, width) {
+    const lines = [''];
+    for (const word of text.split(/\s+/)) {
+        const last = lines.length - 1;
+        if (lines[last] && lines[last].length + word.length + 1 > width)
+            lines.push(word);
+        else
+            lines[last] += `${lines[last] ? ' ' : ''}${word}`;
+    }
+    return lines;
+}
+/** `text` after `first`, wrapped at the line width, its later lines indented as `rest` (default: as wide as `first`). */
+function hanging(first, text, rest = ' '.repeat(first.length)) {
+    return wrap(text, LINE_WIDTH - first.length).map((line, index) => `${index === 0 ? first : rest}${line}`);
+}
+/** The params a rule must set: each required one, and any "one of" group. */
+function requiredParams(check) {
+    const required = Object.entries(check.params ?? {}).filter(([, schema]) => schema.required)
+        .map(([name, schema]) => `${name}: ${schema.type ?? 'any'}`);
+    const oneOf = check.requires_one_of ?? [];
+    if (oneOf.length > 0)
+        required.push(`one of: ${oneOf.join(' | ')}`);
+    return required.join(', ') || 'none';
+}
+/**
+ * The catalogue's templates, grouped under their `category` in the order `template_categories`
+ * lists them, each group named by its label. A category the list does not name follows in the order
+ * first seen, named by its id; a template without one (an older instance) is listed under "Other".
+ * Each row names the id `policy create --template` takes, the title, what it would create and its
+ * framework tags by label (an unknown id as itself). When any row has a tag, the catalogue's
+ * `template_frameworks_note` follows the heading, worded by the platform rather than here; an
+ * instance that serves no note gets no tags, since a tag must never show without it.
+ */
+export function policyTemplateSummary(templates, categories = [], frameworks = [], frameworksNote = '') {
+    if (templates.length === 0)
+        return [];
+    const labels = new Map(categories.map(category => [category.id, category.label]));
+    const tags = frameworkTags(frameworks, frameworksNote);
+    const note = templates.some(template => tags(template).length > 0) ? [frameworksNote.trim()] : [];
+    const groups = new Map(categories.map(category => [category.id, []]));
+    for (const template of templates) {
+        const category = template.category?.trim() || '';
+        groups.set(category, [...(groups.get(category) ?? []), template]);
+    }
+    const width = Math.min(36, Math.max(...templates.map(template => template.id.length)));
+    return [
+        'Templates (xano policy create --template <id>):',
+        ...note,
+        ...[...groups].filter(([, members]) => members.length > 0).flatMap(([category, members]) => [
+            '',
+            labels.get(category) ?? (category || 'Other'),
+            ...members.map(template => {
+                const rules = template.rules.length === 1 ? '1 rule' : `${template.rules.length} rules`;
+                const tagged = tags(template).length > 0 ? ` [${tags(template).join(', ')}]` : '';
+                return `  ${template.id.padEnd(width)}  ${template.title} (${template.key}, ${template.severity}, ${rules})${tagged}`;
+            }),
+        ]),
+    ];
+}
+/**
+ * Framework tag labels for a template or recipe (an unknown id as itself). Tags are shown only
+ * beside the platform's sentence on what they mean: an instance that serves no note gets none.
+ */
+function frameworkTags(frameworks, frameworksNote) {
+    const labels = new Map(frameworks.map(framework => [framework.id, framework.label]));
+    return entry => frameworksNote.trim() === '' || !Array.isArray(entry.frameworks) ? [] : entry.frameworks.map(id => labels.get(id) ?? id);
+}
+/**
+ * The catalogue's recipes, each with its title, tags, summary, what to do first, its templates in
+ * order (each with its key and title, so `policy create --template` can take it from here), the rules
+ * no template covers (their params as JSON and what the author fills in) and the topics no rule in it
+ * can see. The framework note follows the heading when any recipe shows a tag, as for templates.
+ */
+export function policyRecipeSummary(recipes, context = {}) {
+    if (recipes.length === 0)
+        return [];
+    const { frameworks = [], frameworksNote = '', notCheckable = [], templates = [] } = context;
+    const tags = frameworkTags(frameworks, frameworksNote);
+    const note = recipes.some(recipe => tags(recipe).length > 0) ? [frameworksNote.trim()] : [];
+    const byId = new Map(templates.map(template => [template.id, template]));
+    const topics = new Map(notCheckable.map(entry => [entry.id, entry.topic]));
+    return [
+        'Recipes (goals that span several templates; nothing creates a recipe: create its templates, then its rules):',
+        ...note,
+        ...recipes.flatMap(recipe => {
+            const tagged = tags(recipe).length > 0 ? ` [${tags(recipe).join(', ')}]` : '';
+            const steps = recipe.templates ?? [];
+            const rules = recipe.rules ?? [];
+            const limits = recipe.limits ?? [];
+            return [
+                '',
+                `  ${recipe.id}  ${recipe.title}${tagged}`,
+                ...(recipe.summary ? hanging('    ', recipe.summary) : []),
+                ...((recipe.prerequisites ?? []).length > 0 ? ['    First:', ...(recipe.prerequisites ?? []).flatMap(step => hanging('      - ', step))] : []),
+                ...(steps.length > 0 ? ['    Templates, in order (xano policy create --template <id>, one policy each):', ...steps.map((id, index) => {
+                        const template = byId.get(id);
+                        return `      ${index + 1}. ${id}${template ? `  ${template.title} (${template.key})` : ''}`;
+                    })] : []),
+                ...(rules.length > 0 ? ['    Rules no template covers, together in one policy of your own:', ...rules.flatMap(rule => [
+                        ...hanging('      - ', `${rule.title}: ${rule.check}`),
+                        `        ${JSON.stringify(Array.isArray(rule.params) ? {} : rule.params ?? {})}`,
+                        ...((rule.needs ?? []).length > 0 ? [`        You fill in: ${(rule.needs ?? []).join(', ')}`] : []),
+                    ])] : []),
+                ...(limits.length > 0 ? hanging('    No rule here can see: ', `${limits.map(id => topics.get(id) ?? id).join('; ')}.`, '      ') : []),
+            ];
+        }),
+    ];
+}
+/** The catalogue's `not_checkable`: each topic no check can see, by id, with why. */
+export function policyNotCheckableSummary(entries) {
+    if (entries.length === 0)
+        return [];
+    return [
+        'What no check can see (recipes name these under "No rule here can see"):',
+        ...entries.flatMap(entry => ['', `  ${entry.id}  ${entry.topic}`, ...hanging('    ', entry.why)]),
+    ];
+}

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

@@ -0,0 +1,19 @@
+import type { ObjectCoverage } from './types.js';
+/** An object as findings name it, `type:id` (`query:42`), or `null` when the text is not one. */
+export declare function parseObjectRef(text: string): null | {
+    id: number;
+    type: string;
+};
+/** The object coverage chip, worded as Studio's object panel words it. */
+export declare function coverageChip(summary: ObjectCoverage['summary']): string;
+/**
+ * The policies that apply with no finding here, counted from the summary as Studio's panel words its
+ * line under the findings: "6 passing · 1 couldn't check · 1 not checked yet". Empty when it counts none.
+ */
+export declare function coverageCounts(summary: ObjectCoverage['summary']): string;
+/**
+ * An object's coverage on stdout: the chip, the run it reads, the findings Blocking then Advisory,
+ * each with its fix, the policies that apply (counted, then each with its status and why), and the
+ * platform's note.
+ */
+export declare function coverageLines(answer: ObjectCoverage): string[];