@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/kernel/packs/iri.js

@@ -0,0 +1,110 @@
+/**
+ * IRI utilities for pack lookups addressed by prefixed name or absolute IRI.
+ *
+ * `resolveUri` expands a prefixed name through the store's merged prefix map (a
+ * registered prefix always wins; a foreign absolute IRI passes through);
+ * `isEmbeddableIri` is the stricter `scheme://…` shape a resolved IRI must match
+ * before it can be interpolated into a generated `<iri>` query token.
+ */
+import { cliRecovery, PragmaError } from "../error/index.js";
+/** Characters not allowed inside a SPARQL `<IRI>`. */
+const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
+/** A general absolute IRI: `scheme://…` (http, https, …) or a `urn:` opaque IRI. */
+const ABSOLUTE_IRI_PATTERN = /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|urn:)\S/i;
+/** The embeddable-IRI shape: an authority-bearing `scheme://…` with no IRI-breakers. */
+const EMBEDDABLE_IRI_PATTERN = /^[A-Za-z][\w+.-]*:\/\/[^<>"\s]+$/;
+/** Whether a resolved IRI is safe to embed as a `<iri>` query token. */
+export function isEmbeddableIri(value) {
+    return EMBEDDABLE_IRI_PATTERN.test(value);
+}
+/**
+ * Resolve a prefixed or absolute URI to its full form.
+ *
+ * A value that fails to resolve and carries a `%` is retried once decoded, so a
+ * client that percent-encodes the URI it addresses (`ds%3AComponent`) is served
+ * rather than rejected. Every diagnostic names the value the CALLER supplied —
+ * the safety check runs on the expansion, but nobody typed the expansion.
+ *
+ * @param uri - A full or prefixed URI string.
+ * @param prefixes - The store's merged prefix→namespace map.
+ * @returns The fully expanded URI.
+ * @throws PragmaError INVALID_INPUT when the format is invalid or the prefix is unknown.
+ */
+export function resolveUri(uri, prefixes) {
+    const direct = tryResolveUri(uri, prefixes);
+    if (typeof direct === "string")
+        return direct;
+    const decoded = uri.includes("%") ? decodeOnce(uri) : undefined;
+    if (decoded !== undefined && decoded !== uri) {
+        const viaDecoded = tryResolveUri(decoded, prefixes);
+        if (typeof viaDecoded === "string")
+            return viaDecoded;
+    }
+    // Report the input as given, never the decoded or expanded form.
+    throw direct;
+}
+/**
+ * One resolution attempt: the expanded IRI, or the error describing `uri`.
+ *
+ * @param uri - The candidate URI, as the caller wrote it.
+ * @param prefixes - The store's merged prefix→namespace map.
+ * @returns The expanded IRI on success, else the PragmaError to report.
+ */
+function tryResolveUri(uri, prefixes) {
+    const colonIdx = uri.indexOf(":");
+    if (colonIdx === -1) {
+        return PragmaError.invalidInput("uri", uri, {
+            recovery: {
+                message: 'Use a prefixed URI (e.g. "prefix:name") or a full URI.',
+            },
+        });
+    }
+    const prefix = uri.slice(0, colonIdx);
+    const namespace = prefixes[prefix];
+    if (namespace !== undefined) {
+        const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
+        return unsafeIriError(uri, resolved) ?? resolved;
+    }
+    if (ABSOLUTE_IRI_PATTERN.test(uri)) {
+        return unsafeIriError(uri, uri) ?? uri;
+    }
+    return PragmaError.invalidInput("prefix", prefix, {
+        validOptions: Object.keys(prefixes),
+        recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
+            tool: "ontology_list",
+        }),
+    });
+}
+/**
+ * Guard the EXPANSION, name the INPUT: the check is on the IRI that would reach
+ * a query, the message is about the value the caller actually typed.
+ *
+ * @param input - The URI as the caller wrote it.
+ * @param resolved - The expanded IRI the check runs against.
+ * @returns The error when `resolved` carries IRI-breaking characters, else undefined.
+ */
+function unsafeIriError(input, resolved) {
+    if (!UNSAFE_IRI_PATTERN.test(resolved))
+        return undefined;
+    return PragmaError.invalidInput("uri", input, {
+        recovery: { message: "URI contains characters not allowed in IRIs." },
+    });
+}
+/**
+ * Percent-decode a value, tolerating malformed encodings.
+ *
+ * `decodeURIComponent` throws `URIError` on a stray `%` — a decode ATTEMPT must
+ * never turn a reportable input error into a crash.
+ *
+ * @param value - The possibly percent-encoded value.
+ * @returns The decoded value, or undefined when it cannot be decoded.
+ */
+function decodeOnce(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=iri.js.map

package/dist/src/kernel/packs/iri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iri.js","sourceRoot":"","sources":["../../../../src/kernel/packs/iri.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/renderPack.js

@@ -0,0 +1,129 @@
+/**
+ * Project a pack definition onto PR1 render option bags and the three-mode
+ * {@link Formatters} each compiled verb carries.
+ *
+ * List rows, looked-up entities, and sample exemplars all render through the
+ * shared generic renderers with a baked prefix map (display compaction only —
+ * the fetch layer already resolved full IRIs). The formatters are pure and
+ * zod-free, built once at compile time; the run body decides WHAT data reaches
+ * them (disclosure gates the fetch), never HOW it is laid out.
+ */
+import { BIN_NAME, RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { compactUri } from "../render/index.js";
+import { renderListEmptyNotice, renderListLlm, renderListPlain, renderLookupLlm, renderLookupPlain, } from "../render/renderers.js";
+/**
+ * The default empty-state hint when a pack authors no `emptyRecovery`: an empty
+ * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
+ * first) means "nothing matched", so point at both possible fixes.
+ */
+const DEFAULT_EMPTY_HINT = `Build the store with \`${BIN_NAME} sources update\`, or broaden the filter or channel.`;
+/** Build the list formatters for a list-shaped verb (list or an extra verb). */
+export function listFormatters(shape, meta) {
+    const columns = shape.columns.map((column) => ({
+        key: column.field,
+        label: column.label ?? column.field,
+    }));
+    // Zero results is a calm success, not an error (see runBodies.makeListRun):
+    // render a non-blank message, exit 0, JSON stays []. A pack's authored
+    // `emptyRecovery` becomes the hint; otherwise the generic build/broaden hint.
+    const emptyHint = shape.emptyRecovery
+        ? `${shape.emptyRecovery.message}${shape.emptyRecovery.cli
+            ? ` Run \`${RECOVERY_CLI_PREFIX}${shape.emptyRecovery.cli}\`.`
+            : ""}`
+        : DEFAULT_EMPTY_HINT;
+    const options = {
+        heading: meta.heading,
+        columns,
+        prefixes: meta.prefixes,
+        emptyMessage: `No ${meta.noun} entries found.`,
+        emptyHint,
+    };
+    return {
+        plain: (rows, context) => renderListPlain(rows, options, context),
+        llm: (rows) => renderListLlm(rows, options),
+        json: (rows) => JSON.stringify(rows, null, 2),
+        // Zero rows: the dispatcher routes this to stderr (exit 0) so the plain
+        // stdout stream stays pure data; llm/json keep their own empty shapes.
+        emptyNotice: (rows) => rows.length === 0 ? renderListEmptyNotice(options) : undefined,
+    };
+}
+/** Build the shared per-entity render options for a lookup (reused by sample). */
+export function lookupOptions(lookup, prefixes) {
+    const fields = (lookup.fields ?? []).map((field) => ({
+        label: field.label ?? field.name,
+        value: (entity) => entity[field.name],
+    }));
+    const flatSections = (lookup.sections ?? []).map((section) => ({
+        key: section.name,
+        heading: section.label ?? section.name,
+        kind: section.kind ?? "field",
+    }));
+    const expandSections = (lookup.expand ?? []).map((expand) => ({
+        key: expand.name,
+        heading: expand.heading ?? expand.name,
+        kind: expand.kind ?? "list",
+        ...(expand.showWhenEmpty ? { showWhenEmpty: true } : {}),
+    }));
+    return {
+        // An entity reached by IRI need not carry a `by` value, so the IRI is a
+        // real title, not a fallback nobody hits — and it is titled in the form the
+        // user addressed it with, not the expanded one they never typed.
+        title: (entity) => scalar(entity.name) ?? compactScalar(entity.uri, prefixes) ?? "(unnamed)",
+        fields,
+        sections: [...flatSections, ...expandSections],
+        prefixes,
+    };
+}
+/** Build the lookup formatters (renders every resolved entity, then any errors). */
+export function lookupFormatters(lookup, prefixes) {
+    const options = lookupOptions(lookup, prefixes);
+    return {
+        plain: (output) => renderOutput(output, (entity) => renderLookupPlain(entity, options)),
+        llm: (output) => renderOutput(output, (entity) => renderLookupLlm(entity, options), "llm"),
+        json: (output) => JSON.stringify(output, null, 2),
+    };
+}
+/** Build the sample formatters (renders each exemplar, then the follow-ups). */
+export function sampleFormatters(lookup, noun, prefixes) {
+    const options = lookupOptions(lookup, prefixes);
+    return {
+        plain: (data) => {
+            const body = data.samples
+                .map((entity) => renderLookupPlain(entity, options))
+                .join("\n\n");
+            const steps = data.nextSteps.map((step) => `  - ${step}`).join("\n");
+            return `${noun} sample (${data.samples.length} of ${data.totalCount})\n\n${body}${steps ? `\n\nNext steps:\n${steps}` : ""}`.trimEnd();
+        },
+        llm: (data) => {
+            const body = data.samples
+                .map((entity) => renderLookupLlm(entity, options))
+                .join("\n\n");
+            const steps = data.nextSteps.map((step) => `- ${step}`).join("\n");
+            return `## ${capitalize(noun)} sample (${data.samples.length} of ${data.totalCount})\n\n${body}${steps ? `\n\n### Next steps\n${steps}` : ""}`.trimEnd();
+        },
+        json: (data) => JSON.stringify(data, null, 2),
+    };
+}
+/** Render each result entity, appending a compact note for any error entries. */
+function renderOutput(output, render, mode = "plain") {
+    const bodies = output.results.map(render);
+    if (output.errors.length > 0) {
+        const bullet = mode === "llm" ? "- " : "  ";
+        const lines = output.errors.map((error) => `${bullet}${error.query}: ${error.message}`);
+        bodies.push(`${mode === "llm" ? "### Not found" : "Not found:"}\n${lines.join("\n")}`);
+    }
+    return bodies.join("\n\n").trimEnd();
+}
+/** Return a value only when it is a scalar string (expands hold arrays). */
+function scalar(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** A scalar URI in its prefixed display form, or undefined when it is neither. */
+function compactScalar(value, prefixes) {
+    const uri = scalar(value);
+    return uri === undefined ? undefined : compactUri(uri, prefixes);
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+//# sourceMappingURL=renderPack.js.map

package/dist/src/kernel/packs/renderPack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderPack.js","sourceRoot":"","sources":["../../../../src/kernel/packs/renderPack.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/resolveEntity.js

@@ -0,0 +1,223 @@
+/**
+ * Look up one or more pack entities by name, prefixed name, absolute IRI, or
+ * glob, via the fetch strategy the pack declares.
+ *
+ * The resolve is ALWAYS generated SPARQL (an escaped literal or a validated
+ * `<iri>` BIND) regardless of `source`; from the resolved IRI, values are
+ * fetched either through more generated SELECTs (`sparql`) or one generated
+ * GraphQL document (`graphql`). One poisoned query never discards the batch —
+ * per-query failures are collected as structured error entries.
+ *
+ * WHICH query is chosen is decided by the ARGUMENT'S SHAPE first and the pack's
+ * `source` second, and both dispatches live here. Getting that order wrong is
+ * not a style question: it is what made an IRI reach a name FILTER on every
+ * graphql-sourced pack, and what left an IRI-shaped glob expanding against a
+ * population of names. The shape a user typed is a fact about the argument; the
+ * fetch strategy is a fact about the pack, and it cannot change what the
+ * argument means.
+ *
+ * Reached only behind a dynamic import from the lookup run body, so its imports
+ * (including the GraphQL path) stay off the storeless fast path.
+ */
+import { cliRecovery, PragmaError } from "../error/index.js";
+import { suggestNames } from "../project/cli/suggestNames.js";
+import { compactUri } from "../render/index.js";
+import { activeExpands } from "./disclosure.js";
+import { expandGlob, isGlobPattern } from "./glob.js";
+import { fetchGraphqlLookup } from "./graphql/fetchGraphqlLookup.js";
+import { isEmbeddableIri, resolveUri } from "./iri.js";
+import { buildExpandQuery, buildIriResolveQuery, buildLookupByIriQuery, buildLookupIrisQuery, buildLookupNamesQuery, buildLookupQuery, buildNameResolveQuery, } from "./sparql/buildLookupQuery.js";
+import { runSelect } from "./sparql/runSelect.js";
+/**
+ * Resolve a batch of lookup queries, collecting per-query failures.
+ *
+ * @throws PragmaError INVALID_INPUT when the batch is empty.
+ */
+export async function resolveLookup(rt, lookup, noun, queries, source, prefixes, level) {
+    if (queries.length === 0) {
+        throw PragmaError.invalidInput("names", "(empty)", {
+            recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+                tool: `${noun}_list`,
+            }),
+        });
+    }
+    const expanded = await expandQueries(rt, lookup, noun, source, queries, prefixes);
+    const results = [];
+    const errors = [...expanded.globErrors];
+    const settled = await Promise.allSettled(expanded.names.map((query) => lookupOne(rt, lookup, noun, query, source, prefixes, level)));
+    for (const [index, outcome] of settled.entries()) {
+        const query = expanded.names[index];
+        if (query === undefined)
+            continue;
+        if (outcome.status === "fulfilled") {
+            results.push(outcome.value);
+            continue;
+        }
+        const error = outcome.reason;
+        if (error instanceof PragmaError) {
+            errors.push({
+                query,
+                code: error.code,
+                message: error.message,
+                ...(error.suggestions.length > 0
+                    ? { suggestions: error.suggestions }
+                    : {}),
+            });
+        }
+        else {
+            errors.push({
+                query,
+                code: "INTERNAL_ERROR",
+                message: `Internal error: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    return { results, errors };
+}
+/**
+ * Expand glob queries against the population their own shape addresses;
+ * literals pass through.
+ *
+ * A name glob expands over the `by` values, an IRI glob over the entity IRIs —
+ * the same split {@link buildResolveQuery} makes, because a glob is just a
+ * lookup argument with a `*` in it. Expanding an IRI pattern over names was why
+ * `ds:global.component.but*` matched nothing on any pack while shell completion
+ * offered nothing BUT those IRIs. Each population is fetched at most once, and
+ * only when a glob of that shape is actually present.
+ */
+async function expandQueries(rt, lookup, noun, source, queries, prefixes) {
+    if (!queries.some(isGlobPattern))
+        return { names: [...queries], globErrors: [] };
+    const globs = queries.filter(isGlobPattern);
+    const byIri = globs.some(looksLikeIri)
+        ? await listEntityIriSpellings(rt, lookup, source, prefixes)
+        : new Map();
+    const byName = globs.some((glob) => !looksLikeIri(glob))
+        ? await listEntityNames(rt, lookup, source)
+        : [];
+    const names = [];
+    const globErrors = [];
+    for (const query of queries) {
+        if (!isGlobPattern(query)) {
+            names.push(query);
+            continue;
+        }
+        // An IRI glob expands over every spelling, then collapses to the entity:
+        // matching `ds:button` and its absolute twin must not list it twice.
+        const matches = looksLikeIri(query)
+            ? [
+                ...new Set(expandGlob(query, [...byIri.keys()]).map((spelling) => byIri.get(spelling) ?? spelling)),
+            ]
+            : expandGlob(query, byName);
+        if (matches.length === 0) {
+            globErrors.push({
+                query,
+                code: "EMPTY_RESULTS",
+                message: `No ${noun} entries matching "${query}".`,
+            });
+        }
+        else {
+            names.push(...matches);
+        }
+    }
+    return { names, globErrors };
+}
+/** Look up one entity, dispatching to the pack's declared fetch source. */
+async function lookupOne(rt, lookup, noun, query, source, prefixes, level) {
+    const graphqlSourced = lookup.source === "graphql";
+    const rows = await runSelect(rt, buildResolveQuery(lookup, query, prefixes, level), source);
+    const base = rows.at(0);
+    if (!base?.uri) {
+        const candidates = await listEntityNames(rt, lookup, source);
+        throw PragmaError.notFound(noun, query, {
+            suggestions: suggestNames(query, candidates),
+            recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
+                tool: `${noun}_list`,
+            }),
+        });
+    }
+    if (graphqlSourced) {
+        return fetchGraphqlLookup(rt, lookup, base.uri, base.name ?? query, 
+        // The GraphQL lane's only use of the source is CONFIG_ERROR attribution,
+        // which is right for any origin — so it takes the label, not provenance.
+        source.label, prefixes, level);
+    }
+    const entity = { ...base };
+    for (const expand of activeExpands(lookup, level)) {
+        entity[expand.name] = (await runSelect(rt, buildExpandQuery(expand, base.uri), source));
+    }
+    return entity;
+}
+/**
+ * Build the resolve SELECT for one lookup argument: shape first, source second.
+ *
+ * The four cells of that 2×2 are the whole dispatch. A graphql-sourced pack
+ * resolves to an IRI and fetches everything else through its document, so both
+ * of its queries are the minimal `?uri ?name` pair; a sparql-sourced pack reads
+ * its fields in the same SELECT, so both of its queries carry the level-gated
+ * projection.
+ */
+function buildResolveQuery(lookup, query, prefixes, level) {
+    const graphqlSourced = lookup.source === "graphql";
+    if (!looksLikeIri(query)) {
+        return graphqlSourced
+            ? buildNameResolveQuery(lookup, query)
+            : buildLookupQuery(lookup, query, level);
+    }
+    const resolved = resolveUri(query, prefixes);
+    if (!isEmbeddableIri(resolved)) {
+        throw PragmaError.invalidInput("name", query, {
+            recovery: {
+                message: "Use an absolute IRI (https://…), a prefixed name (prefix:local), or a plain entity name.",
+            },
+        });
+    }
+    return graphqlSourced
+        ? buildIriResolveQuery(lookup, resolved)
+        : buildLookupByIriQuery(lookup, resolved, level);
+}
+/** Whether a lookup query addresses an entity by IRI or prefixed name. */
+function looksLikeIri(query) {
+    return (query.startsWith("http://") ||
+        query.startsWith("https://") ||
+        // Neither an IRI nor a SPARQL prefixed name may contain whitespace, so a
+        // colon in a spaced string is part of a plain entity name — e.g. the
+        // concept "Foundations: Grid" — not a prefix separator.
+        (query.includes(":") && !/\s/.test(query)));
+}
+/**
+ * Every SPELLING an IRI-shaped glob may be written against, mapped to the one
+ * entity it addresses.
+ *
+ * An entity under a registered prefix has two legal spellings — the compact
+ * `ds:button` shell completion offers, and the absolute
+ * `https://ds.canonical.com/button` a user pastes from a browser. Both resolve
+ * to the same entity in a literal lookup, so a glob must expand over both;
+ * offering only the compact form made `https://ds.canonical.com/but*` return
+ * EMPTY_RESULTS while the literal IRI it generalises succeeded.
+ *
+ * The map is spelling → CANONICAL IRI precisely so a pattern that matches an
+ * entity under both spellings still yields it once. Matching over a flat list
+ * of both would render the entity twice, which is why the previous shape
+ * offered only one.
+ */
+async function listEntityIriSpellings(rt, lookup, source, prefixes) {
+    const rows = await runSelect(rt, buildLookupIrisQuery(lookup), source);
+    const spellings = new Map();
+    for (const row of rows) {
+        const uri = row.uri ?? "";
+        if (uri === "")
+            continue;
+        spellings.set(uri, uri);
+        const compact = compactUri(uri, prefixes);
+        if (compact !== uri)
+            spellings.set(compact, uri);
+    }
+    return spellings;
+}
+/** List every entity name the lookup can address (miss suggestions + sample/glob). */
+export async function listEntityNames(rt, lookup, source) {
+    const rows = await runSelect(rt, buildLookupNamesQuery(lookup), source);
+    return rows.map((row) => row.name ?? "").filter((name) => name !== "");
+}
+//# sourceMappingURL=resolveEntity.js.map

package/dist/src/kernel/packs/resolveEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveEntity.js","sourceRoot":"","sources":["../../../../src/kernel/packs/resolveEntity.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/runBodies.js

@@ -0,0 +1,87 @@
+/**
+ * The shared run bodies a compiled pack verb closes over.
+ *
+ * Each factory returns a `VerbSpec.run` closure. Reads are plain async: the list
+ * body runs the pack's SELECT then applies post-query filters/search; the lookup
+ * body resolves names → IRIs and fetches per the declared source, gated by the
+ * resolved disclosure level; the sample body draws N random entities at the
+ * highest level. All store access is through the runtime facade (lazy), so these
+ * factories carry no heavy static import.
+ */
+import { cliRecovery, PragmaError } from "../error/index.js";
+import { resolvePackDetail } from "./disclosure.js";
+import { listEntityNames, resolveLookup, } from "./resolveEntity.js";
+import { parseSampleCount, pickRandom } from "./sample.js";
+import { applyPackFilters } from "./sparql/applyFilters.js";
+import { applyPackSearch } from "./sparql/applySearch.js";
+import { runSelect } from "./sparql/runSelect.js";
+/** The highest canonical level — sample fetches everything for shape discovery. */
+const HIGHEST_LEVEL = "detailed";
+/**
+ * Build the run body for a list-shaped verb (`list` or an extra verb).
+ *
+ * Zero rows is a plain empty list — a SUCCESS, not an error. It returns `[]`
+ * (JSON stays `[]`, exit 0); the formatter turns the emptiness into a non-blank
+ * message (a pack's `emptyRecovery` becomes that message's hint). Routing zero
+ * results through EMPTY_RESULTS would map to exit 1 and break the uniform
+ * `ok:true` list contract, so the run body never throws on emptiness.
+ */
+export function makeListRun(shape, meta) {
+    return async (params, rt) => applyPackSearch(applyPackFilters(await runSelect(rt, shape.query, meta.source), shape.filters, params), shape.search, params);
+}
+/** Build the run body for a lookup verb (variadic names → resolved entities). */
+export function makeLookupRun(lookup, noun, source, prefixes) {
+    return async (params, rt) => {
+        const names = readNames(params);
+        const level = await resolvePackDetail(rt, lookup.disclosure);
+        const output = await resolveLookup(rt, lookup, noun, names, source, prefixes, level);
+        // A total miss (single or all-miss) exits non-zero; a partial batch renders
+        // the results it found and notes the misses.
+        if (output.results.length === 0 && output.errors.length > 0) {
+            const first = output.errors[0];
+            if (first) {
+                throw new PragmaError({
+                    code: first.code,
+                    message: first.message,
+                    suggestions: first.suggestions ? [...first.suggestions] : undefined,
+                    recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, { tool: `${noun}_list` }),
+                });
+            }
+        }
+        return output;
+    };
+}
+/** Build the run body for a sample verb (N random entities at the highest level). */
+export function makeSampleRun(lookup, noun, source, prefixes, defaultCount) {
+    return async (params, rt) => {
+        const count = parseSampleCount(params.count ?? defaultCount);
+        const names = await listEntityNames(rt, lookup, source);
+        // An empty population is a clean EMPTY_RESULTS (nothing to sample), not the
+        // "(empty)" INVALID_INPUT resolveLookup would raise on a zero-length batch.
+        if (names.length === 0) {
+            throw PragmaError.emptyResults(noun, {
+                message: `No ${noun} entries to sample.`,
+                recovery: cliRecovery(`${noun} list`, `List available ${noun} entries.`, { tool: `${noun}_list` }),
+            });
+        }
+        const selected = pickRandom(names, count);
+        const output = await resolveLookup(rt, lookup, noun, selected, source, prefixes, HIGHEST_LEVEL);
+        return {
+            samples: output.results,
+            totalCount: names.length,
+            nextSteps: [
+                `These are ${output.results.length} of ${names.length} total ${noun} entries.`,
+                `Use ${noun}_lookup to inspect specific entries by name.`,
+                `Use ${noun}_list to browse all entries.`,
+            ],
+        };
+    };
+}
+/** Read the variadic `name` positional as a string array. */
+function readNames(params) {
+    const raw = params.name;
+    if (Array.isArray(raw))
+        return raw.filter((n) => typeof n === "string");
+    return typeof raw === "string" ? [raw] : [];
+}
+//# sourceMappingURL=runBodies.js.map

package/dist/src/kernel/packs/runBodies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runBodies.js","sourceRoot":"","sources":["../../../../src/kernel/packs/runBodies.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/sample.js

@@ -0,0 +1,56 @@
+/**
+ * Sample-count parsing and uniform random selection for the `sample` verb.
+ *
+ * Ported from the v1 shared helpers: a missing count falls back to the default,
+ * a non-integer is rejected as invalid input, and a valid integer is clamped to
+ * the supported 1–5 range. Selection is a Fisher-Yates partial shuffle.
+ */
+import { PragmaError } from "../error/index.js";
+/** Smallest number of samples the `sample` verb returns. */
+export const MIN_SAMPLE_COUNT = 1;
+/** Largest number of samples the `sample` verb returns. */
+export const MAX_SAMPLE_COUNT = 5;
+/** Number of samples returned when the count is omitted. */
+export const DEFAULT_SAMPLE_COUNT = 2;
+/** The default sample count a lookup declares, or the built-in default. */
+export function sampleDefaultCount(lookup) {
+    const sample = lookup.sample;
+    if (sample && sample !== true && typeof sample.count === "number") {
+        return sample.count;
+    }
+    return DEFAULT_SAMPLE_COUNT;
+}
+/**
+ * Resolve the raw `count` arg into a clamped sample count.
+ *
+ * @throws PragmaError INVALID_INPUT when `raw` is present but not an integer.
+ */
+export function parseSampleCount(raw) {
+    if (raw === undefined || raw === null || raw === "") {
+        return DEFAULT_SAMPLE_COUNT;
+    }
+    const text = String(raw).trim();
+    if (!/^-?\d+$/.test(text)) {
+        throw PragmaError.invalidInput("count", String(raw), {
+            recovery: {
+                message: `Provide an integer between ${MIN_SAMPLE_COUNT} and ${MAX_SAMPLE_COUNT}.`,
+            },
+        });
+    }
+    return Math.max(MIN_SAMPLE_COUNT, Math.min(MAX_SAMPLE_COUNT, Number(text)));
+}
+/** Pick `count` random items without replacement (Fisher-Yates partial shuffle). */
+export function pickRandom(arr, count) {
+    const n = Math.min(count, arr.length);
+    if (n === 0)
+        return [];
+    const copy = [...arr];
+    for (let i = 0; i < n; i++) {
+        const j = i + Math.floor(Math.random() * (copy.length - i));
+        const tmp = copy[i];
+        copy[i] = copy[j];
+        copy[j] = tmp;
+    }
+    return copy.slice(0, n);
+}
+//# sourceMappingURL=sample.js.map

package/dist/src/kernel/packs/sample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample.js","sourceRoot":"","sources":["../../../../src/kernel/packs/sample.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAClE,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpD,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,WAAW,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE;YACnD,QAAQ,EAAE;gBACR,OAAO,EAAE,8BAA8B,gBAAgB,QAAQ,gBAAgB,GAAG;aACnF;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAI,GAAiB,EAAE,KAAa;IAC5D,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;QACvB,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1B,CAAC"}