@xano/cli 1.3.3 → 1.3.5-beta.0

package/dist/utils/object-fetch.d.ts

@@ -0,0 +1,86 @@
+import { type SyncFileEntry, type SyncTargetIdentity, type SyncTargetState } from './sync-state.js';
+export declare const PER_OBJECT_FETCH_LIMIT = 25;
+export declare const PER_OBJECT_CONCURRENCY = 6;
+export type ObjectType = 'addon' | 'agent' | 'function' | 'query' | 'table' | 'task' | 'tool';
+export interface TypeSpec {
+    hasBranchField: boolean;
+    listPath: (workspaceId: string, extra?: {
+        groupId?: number;
+    }) => string;
+    objectPath: (workspaceId: string, id: number, extra?: {
+        groupId?: number;
+    }) => string;
+}
+export declare const OBJECT_TYPE_SPECS: Record<ObjectType, TypeSpec>;
+export declare function isObjectType(type: string): type is ObjectType;
+export declare function typesWithoutBranchField(types: string[]): string[];
+/**
+ * Insert a guid line before the final `}`, matching `syncGuidToFile`.
+ * A blank line is inserted before it when the previous non-empty line is a
+ * closing `}` or `]` (the multidoc export's layout, measured in Phase 0b).
+ */
+export declare function insertGuidLine(content: string, guid: string): string;
+export declare function restoreGuidFromLocal(remoteContent: string, localContent: string): string;
+export declare function readXanoscript(body: unknown): {
+    branch?: string;
+    status: string;
+    text: string;
+} | {
+    error: string;
+};
+export interface ResolvedObjectId {
+    groupId?: number;
+    id: number;
+}
+export type ObjectGet = (pathname: string, query?: Record<string, string>) => Promise<{
+    json: unknown;
+    ok: boolean;
+    status: number;
+}>;
+export declare function lookupObjectId(get: ObjectGet, workspaceId: string, parsed: {
+    apiGroup?: string;
+    name: string;
+    type: string;
+    verb?: string;
+}): Promise<null | ResolvedObjectId>;
+export interface PushedObject {
+    content: string;
+    filePath: string;
+    relPath: string;
+}
+export interface FetchFormattedResult {
+    content: string;
+    filePath: string;
+    id: number;
+    relPath: string;
+}
+export type FetchFormattedFailure = {
+    error: string;
+    filePath: string;
+};
+export declare function canUsePerObjectFetch(args: {
+    isLiveBranch: boolean;
+    limit?: number;
+    pushed: PushedObject[];
+}): {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+};
+export declare function fetchFormattedObjects(args: {
+    get: ObjectGet;
+    isLiveBranch: boolean;
+    limit?: number;
+    pushed: PushedObject[];
+    state: null | SyncTargetState;
+    target: SyncTargetIdentity;
+    workspaceId: string;
+}): Promise<{
+    ids: Record<string, SyncFileEntry>;
+    ok: true;
+    results: FetchFormattedResult[];
+} | {
+    ok: false;
+    reason: string;
+}>;

package/dist/utils/object-fetch.js

@@ -0,0 +1,265 @@
+import { mapWithConcurrency } from './concurrency.js';
+import { buildDocumentKey, parseDocument } from './document-parser.js';
+import { normalizeListResponse } from './paging.js';
+export const PER_OBJECT_FETCH_LIMIT = 25;
+export const PER_OBJECT_CONCURRENCY = 6;
+export const OBJECT_TYPE_SPECS = {
+    addon: {
+        hasBranchField: true,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/addon`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/addon/${id}`,
+    },
+    agent: {
+        hasBranchField: false,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/agent`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/agent/${id}`,
+    },
+    function: {
+        hasBranchField: true,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/function`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/function/${id}`,
+    },
+    query: {
+        hasBranchField: false,
+        listPath: (workspaceId, extra) => extra?.groupId === undefined
+            ? `/workspace/${workspaceId}/apigroup`
+            : `/workspace/${workspaceId}/apigroup/${extra.groupId}/api`,
+        objectPath: (workspaceId, id, extra) => `/workspace/${workspaceId}/apigroup/${extra?.groupId}/api/${id}`,
+    },
+    table: {
+        hasBranchField: false,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/table`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/table/${id}`,
+    },
+    task: {
+        hasBranchField: true,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/task`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/task/${id}`,
+    },
+    tool: {
+        hasBranchField: true,
+        listPath: (workspaceId) => `/workspace/${workspaceId}/tool`,
+        objectPath: (workspaceId, id) => `/workspace/${workspaceId}/tool/${id}`,
+    },
+};
+const GUID_REGEX = /guid\s*=\s*(["'])([^"']*)\1/;
+export function isObjectType(type) {
+    return type in OBJECT_TYPE_SPECS;
+}
+export function typesWithoutBranchField(types) {
+    return types.filter((type) => isObjectType(type) && !OBJECT_TYPE_SPECS[type].hasBranchField);
+}
+/**
+ * Insert a guid line before the final `}`, matching `syncGuidToFile`.
+ * A blank line is inserted before it when the previous non-empty line is a
+ * closing `}` or `]` (the multidoc export's layout, measured in Phase 0b).
+ */
+export function insertGuidLine(content, guid) {
+    if (GUID_REGEX.test(content)) {
+        return content.replace(GUID_REGEX, `guid = "${guid}"`);
+    }
+    const lines = content.split('\n');
+    let insertIndex = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            insertIndex = i;
+            break;
+        }
+    }
+    if (insertIndex === -1)
+        return content;
+    let indent = '  ';
+    let previousNonEmpty = '';
+    for (let i = insertIndex - 1; i >= 0; i--) {
+        if (lines[i].trim()) {
+            previousNonEmpty = lines[i].trim();
+            const indentMatch = lines[i].match(/^(\s+)/);
+            if (indentMatch)
+                indent = indentMatch[1];
+            break;
+        }
+    }
+    const guidLine = `${indent}guid = "${guid}"`;
+    if (previousNonEmpty === '}' || previousNonEmpty === ']') {
+        lines.splice(insertIndex, 0, '', guidLine);
+    }
+    else {
+        lines.splice(insertIndex, 0, guidLine);
+    }
+    return lines.join('\n');
+}
+export function restoreGuidFromLocal(remoteContent, localContent) {
+    const localGuid = localContent.match(GUID_REGEX);
+    if (!localGuid)
+        return remoteContent;
+    if (GUID_REGEX.test(remoteContent))
+        return remoteContent;
+    return insertGuidLine(remoteContent, localGuid[2]);
+}
+export function readXanoscript(body) {
+    if (!body || typeof body !== 'object')
+        return { error: 'response is not an object' };
+    const record = body;
+    const xs = record.xanoscript;
+    if (!xs || typeof xs !== 'object')
+        return { error: 'xanoscript is missing' };
+    const script = xs;
+    if (script.status !== 'ok' || typeof script.value !== 'string') {
+        return { error: `xanoscript.status is ${String(script.status)}` };
+    }
+    return {
+        branch: typeof record.branch === 'string' ? record.branch : undefined,
+        status: 'ok',
+        text: script.value,
+    };
+}
+function itemsOf(json) {
+    try {
+        return normalizeListResponse(json, [
+            'functions',
+            'tables',
+            'tasks',
+            'agents',
+            'tools',
+            'addons',
+            'apigroups',
+            'apis',
+        ]).items.filter((item) => typeof item === 'object' && item !== null);
+    }
+    catch {
+        return [];
+    }
+}
+async function searchExact(get, pathname, name, extraMatch) {
+    const response = await get(pathname, { include_draft: 'false', page: '1', per_page: '50', search: name });
+    if (!response.ok)
+        return null;
+    const matches = itemsOf(response.json).filter((item) => item.name === name && (extraMatch ? extraMatch(item) : true));
+    if (matches.length !== 1 || typeof matches[0].id !== 'number')
+        return null;
+    return matches[0];
+}
+export async function lookupObjectId(get, workspaceId, parsed) {
+    if (!isObjectType(parsed.type))
+        return null;
+    const spec = OBJECT_TYPE_SPECS[parsed.type];
+    if (parsed.type === 'query') {
+        if (!parsed.apiGroup)
+            return null;
+        const group = await searchExact(get, spec.listPath(workspaceId), parsed.apiGroup);
+        if (!group || typeof group.id !== 'number')
+            return null;
+        const verb = parsed.verb ? String(parsed.verb).toUpperCase() : undefined;
+        const api = await searchExact(get, spec.listPath(workspaceId, { groupId: group.id }), parsed.name, (item) => verb ? String(item.verb ?? '').toUpperCase() === verb : true);
+        if (!api || typeof api.id !== 'number')
+            return null;
+        return { groupId: group.id, id: api.id };
+    }
+    const found = await searchExact(get, spec.listPath(workspaceId), parsed.name);
+    if (!found || typeof found.id !== 'number')
+        return null;
+    return { id: found.id };
+}
+export function canUsePerObjectFetch(args) {
+    const limit = args.limit ?? PER_OBJECT_FETCH_LIMIT;
+    if (args.pushed.length === 0)
+        return { ok: false, reason: 'no pushed documents' };
+    if (args.pushed.length > limit) {
+        return { ok: false, reason: `push has ${args.pushed.length} documents (limit ${limit})` };
+    }
+    const types = new Set();
+    for (const entry of args.pushed) {
+        const parsed = parseDocument(entry.content);
+        if (!parsed || !isObjectType(parsed.type)) {
+            return { ok: false, reason: `type ${parsed?.type ?? 'unknown'} is not in the per-object table` };
+        }
+        types.add(parsed.type);
+    }
+    if (!args.isLiveBranch) {
+        const missing = typesWithoutBranchField([...types]);
+        if (missing.length > 0) {
+            return { ok: false, reason: `types without a branch field on a non-live branch: ${missing.join(', ')}` };
+        }
+    }
+    return { ok: true };
+}
+export async function fetchFormattedObjects(args) {
+    const gate = canUsePerObjectFetch({ isLiveBranch: args.isLiveBranch, limit: args.limit, pushed: args.pushed });
+    if (!gate.ok)
+        return gate;
+    const ids = {};
+    const resolved = [];
+    for (const entry of args.pushed) {
+        const parsed = parseDocument(entry.content);
+        if (!parsed || !isObjectType(parsed.type)) {
+            return { ok: false, reason: `unparseable document ${entry.relPath}` };
+        }
+        const key = buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup);
+        const recorded = args.state?.files[entry.relPath];
+        let id;
+        let groupId;
+        const cachedId = recorded?.id !== undefined && recorded.key === key ? recorded.id : undefined;
+        if (parsed.type === 'query' || cachedId === undefined) {
+            // Sequential: stop on the first miss instead of firing every lookup.
+            // eslint-disable-next-line no-await-in-loop
+            const lookedUp = await lookupObjectId(args.get, args.workspaceId, parsed);
+            if (!lookedUp)
+                return { ok: false, reason: `could not look up id for ${entry.relPath}` };
+            id = cachedId ?? lookedUp.id;
+            groupId = lookedUp.groupId;
+        }
+        else {
+            id = cachedId;
+        }
+        resolved.push({ ...entry, groupId, id, key });
+    }
+    const fetched = await mapWithConcurrency(resolved, PER_OBJECT_CONCURRENCY, async (entry) => {
+        const parsed = parseDocument(entry.content);
+        const spec = OBJECT_TYPE_SPECS[parsed.type];
+        const pathname = spec.objectPath(args.workspaceId, entry.id, { groupId: entry.groupId });
+        const response = await args.get(pathname, { include_draft: 'false', include_xanoscript: 'true' });
+        if (!response.ok) {
+            return { error: `HTTP ${response.status} for ${entry.relPath}`, filePath: entry.filePath };
+        }
+        const xs = readXanoscript(response.json);
+        if ('error' in xs) {
+            return { error: `${entry.relPath}: ${xs.error}`, filePath: entry.filePath };
+        }
+        if (spec.hasBranchField && xs.branch !== args.target.branch) {
+            return {
+                error: `${entry.relPath}: branch ${xs.branch ?? '(missing)'} != ${args.target.branch}`,
+                filePath: entry.filePath,
+            };
+        }
+        const restored = restoreGuidFromLocal(xs.text, entry.content);
+        const restoredParsed = parseDocument(restored);
+        if (!restoredParsed) {
+            return { error: `${entry.relPath}: fetched document did not parse`, filePath: entry.filePath };
+        }
+        const restoredKey = buildDocumentKey(restoredParsed.type, restoredParsed.name, restoredParsed.verb, restoredParsed.apiGroup);
+        if (restoredKey !== entry.key) {
+            return { error: `${entry.relPath}: fetched key ${restoredKey} != ${entry.key}`, filePath: entry.filePath };
+        }
+        return {
+            content: restored,
+            filePath: entry.filePath,
+            id: entry.id,
+            relPath: entry.relPath,
+        };
+    });
+    const results = [];
+    for (const item of fetched) {
+        if ('error' in item) {
+            return { ok: false, reason: item.error ?? 'unknown fetch error' };
+        }
+        results.push(item);
+    }
+    for (const entry of resolved) {
+        ids[entry.relPath] = {
+            id: entry.id,
+            key: entry.key,
+            sha256: '',
+        };
+    }
+    return { ids, ok: true, results };
+}

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[];