@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -0,0 +1,304 @@
+/**
+ * THE single pack compiler: one validated {@link PackDefinition} → a set of
+ * {@link VerbSpec}s, projected by the CLI and MCP projectors like any other
+ * verb. This closes fork F3 (two pack compilers → one) — `list`, extra
+ * list-shaped verbs, `lookup`, and `sample` all compile here, and the fetch
+ * source (`sparql`/`graphql`) is a run-body detail invisible to the projectors.
+ *
+ * Pure, storeless spec-generation: it builds paths, params, formatters, and run
+ * closures without touching the store or zod, so it runs on the
+ * `--help`/`__complete` fast path (the distribution's declared stories compile
+ * at import, in `capabilities/distribution.ts`; the dynamic merge is
+ * `collect.assembleEffectiveModules`/`loadEffectiveModules`).
+ * The heavy work is deferred into the run closures (behind the lazy runtime
+ * facade).
+ */
+import { BIN_NAME } from "../../constants.js";
+import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
+import { asVerb } from "../spec/asVerb.js";
+import { listFormatters, lookupFormatters, sampleFormatters, } from "./renderPack.js";
+import { MAX_SAMPLE_COUNT, MIN_SAMPLE_COUNT, sampleDefaultCount, } from "./sample.js";
+// The run bodies pull the SPARQL/GraphQL fetch layer; they are dynamic-imported
+// per invocation so `compilePack` (reached on the storeless --help/__complete
+// fast path via capabilities/index) never statically loads them.
+const runBodies = () => import("./runBodies.js");
+/** The read capability every pack verb carries (store-backed, exposed to MCP). */
+const READ_CAPABILITY = {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+        expose: true,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+};
+/**
+ * Compile a validated pack definition into its verbs.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display compaction.
+ * @returns The compiled verbs (list, extra verbs, lookup, sample), in order.
+ */
+export function compilePack(definition, source, prefixes) {
+    const { noun } = definition;
+    const verbs = [];
+    if (definition.list) {
+        verbs.push(compileListVerb(definition.list, {
+            noun,
+            verb: "list",
+            summary: definition.description ?? `List ${noun} entries.`,
+            doc: definition.toolDescription,
+            source,
+            prefixes,
+        }));
+    }
+    for (const verb of definition.verbs ?? []) {
+        verbs.push(compileListVerb(verb, {
+            noun,
+            verb: verb.verb,
+            summary: verb.description ?? `List ${noun} ${verb.verb}.`,
+            doc: verb.toolDescription,
+            source,
+            prefixes,
+        }));
+    }
+    if (definition.lookup) {
+        verbs.push(compileLookupVerb(definition.lookup, noun, source, prefixes));
+        if (definition.lookup.sample) {
+            verbs.push(compileSampleVerb(definition.lookup, noun, source, prefixes));
+        }
+    }
+    return verbs;
+}
+/**
+ * Derive a story's MCP resource listing from the types its lookup addresses.
+ *
+ * ZERO new authoring: a read story ALREADY declares its type set
+ * (`lookup.type` / `lookup.types`) because that is what its name resolve is
+ * constrained by, so the slice of the index the noun contributes to the listing
+ * IS that declaration read a second time by a different reader — never written
+ * a second time by the author. Each type contributes ONE collection entry (its
+ * class entry, carrying the instance count); the individuals stay reachable
+ * through the `{+uri}` template and its autocomplete.
+ *
+ * Returns `undefined` for a story with no lookup (a list-only noun addresses no
+ * class, so it can name no slice).
+ *
+ * @param definition - A validated pack definition.
+ * @returns Its declared listing, or `undefined` when it declares no types.
+ */
+export function compileListable(definition) {
+    const lookup = definition.lookup;
+    if (!lookup)
+        return undefined;
+    const types = lookup.types ?? (lookup.type ? [lookup.type] : []);
+    if (types.length === 0)
+        return undefined;
+    // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but the
+    // listing is keyed on the index's PREFIXED types. Copied verbatim, a lookup
+    // legitimately constrained to `https://…/Widget` compiles clean and then
+    // matches no class and no weight — a story that is valid everywhere else and
+    // silently contributes nothing here. Compacted against the same map
+    // `resolveUri` expands with, so the two directions agree.
+    const compact = (type) => compactUri(type, DEFAULT_PREFIX_MAP);
+    const weights = Object.fromEntries(Object.entries(lookup.weights ?? {}).map(([type, weight]) => [
+        compact(type),
+        weight,
+    ]));
+    return {
+        sources: types.map(compact).map((type) => ({
+            type,
+            as: "collection",
+            // Unlisted types weigh 1 — the default is "as important as any other",
+            // so a story that declares no weights needs no weights.
+            weight: weights[type] ?? 1,
+        })),
+    };
+}
+/**
+ * Compile a story into the capability module that carries it.
+ *
+ * The ONE place a {@link PackDefinition} becomes a {@link CapabilityModule} —
+ * the distribution's static stories and the dynamic (config/package) ones come
+ * through here alike, so a module-level projection derived from the story
+ * (today: {@link compileListable}) cannot reach one tier and miss the other.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display compaction.
+ * @returns The module: the compiled verbs plus the story's module-level data.
+ */
+export function compileStoryModule(definition, source, prefixes) {
+    const listable = compileListable(definition);
+    return {
+        name: definition.noun,
+        story: true,
+        verbs: compilePack(definition, source, prefixes),
+        colophon: definition.colophon,
+        ...(listable ? { mcpListable: listable } : {}),
+    };
+}
+/** Compile the `list` verb or an extra list-shaped verb. */
+function compileListVerb(shape, meta) {
+    const params = [
+        ...projectFilters(shape.filters),
+        ...projectSearch(shape.search),
+    ];
+    const filterExample = shape.filters?.find((f) => f.values !== undefined);
+    const verb = {
+        path: [meta.noun, meta.verb],
+        summary: meta.summary,
+        ...(meta.doc ? { doc: meta.doc } : {}),
+        params,
+        output: {
+            formatters: listFormatters(shape, {
+                heading: `${capitalize(meta.noun)}${meta.verb === "list" ? "" : ` ${meta.verb}`}`,
+                noun: meta.noun,
+                prefixes: meta.prefixes,
+            }),
+        },
+        examples: [
+            { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb}` },
+            ...(filterExample
+                ? [
+                    {
+                        cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --${filterExample.param} ${quoteExample(filterExample.values?.at(0) ?? "")}`,
+                    },
+                ]
+                : []),
+            { cmd: `${BIN_NAME} ${meta.noun} ${meta.verb} --format llm` },
+        ],
+        capability: READ_CAPABILITY,
+        run: (params, rt) => runBodies().then((m) => m.makeListRun(shape, { source: meta.source })(params, rt)),
+    };
+    return asVerb(verb);
+}
+/** Compile the `lookup` verb (variadic names → resolved entities). */
+function compileLookupVerb(lookup, noun, source, prefixes) {
+    // Derive-by-default: every lookup completes its `<name>` from the pack index
+    // (empty type = any, the reader handles it), UNLESS the pack opts out
+    // (`completion.enabled:false`). `match`/`minChars` tune the derived heuristic.
+    const completeType = lookup.type ?? lookup.types?.at(0) ?? "";
+    const completion = lookup.completion;
+    const nameParam = {
+        kind: "string[]",
+        name: "name",
+        doc: `${capitalize(noun)} names, prefixed names/IRIs, or glob patterns.`,
+        positional: true,
+        required: true,
+        ...(completion?.enabled === false
+            ? {}
+            : {
+                complete: {
+                    kind: "names",
+                    source: {
+                        from: "index",
+                        ...(completeType ? { type: completeType } : {}),
+                    },
+                    ...(completion?.match ? { match: completion.match } : {}),
+                    ...(completion?.minChars !== undefined
+                        ? { minChars: completion.minChars }
+                        : {}),
+                },
+            }),
+    };
+    const verb = {
+        path: [noun, "lookup"],
+        summary: lookup.description ?? `Look up ${noun} details by name, IRI, or glob.`,
+        ...(lookup.toolDescription ? { doc: lookup.toolDescription } : {}),
+        params: [nameParam],
+        output: { formatters: lookupFormatters(lookup, prefixes) },
+        examples: [{ cmd: `${BIN_NAME} ${noun} lookup <name>` }],
+        ...(lookup.disclosure
+            ? { disclosure: disclosureSpec(lookup.disclosure) }
+            : {}),
+        capability: READ_CAPABILITY,
+        run: (params, rt) => runBodies().then((m) => m.makeLookupRun(lookup, noun, source, prefixes)(params, rt)),
+    };
+    return asVerb(verb);
+}
+/** Compile the `sample` verb (N random exemplars at the highest level). */
+function compileSampleVerb(lookup, noun, source, prefixes) {
+    const defaultCount = sampleDefaultCount(lookup);
+    const config = lookup.sample === true ? undefined : lookup.sample;
+    // Most samples take a `[count]` positional; where the covenant freezes a
+    // no-argument sample the pack sets `fixedCount`, so the compiler omits it and
+    // the sample always returns the default count.
+    const countParam = config?.fixedCount
+        ? []
+        : [
+            {
+                kind: "string",
+                name: "count",
+                doc: `Number of samples (${MIN_SAMPLE_COUNT}–${MAX_SAMPLE_COUNT}, default ${defaultCount}).`,
+                positional: true,
+            },
+        ];
+    const verb = {
+        path: [noun, "sample"],
+        summary: config?.description ??
+            `Return randomly selected complete ${noun} entries as exemplars.`,
+        ...(config?.toolDescription ? { doc: config.toolDescription } : {}),
+        params: countParam,
+        output: { formatters: sampleFormatters(lookup, noun, prefixes) },
+        examples: [
+            { cmd: `${BIN_NAME} ${noun} sample` },
+            ...(config?.fixedCount ? [] : [{ cmd: `${BIN_NAME} ${noun} sample 3` }]),
+        ],
+        capability: READ_CAPABILITY,
+        run: (params, rt) => runBodies().then((m) => m.makeSampleRun(lookup, noun, source, prefixes, defaultCount)(params, rt)),
+    };
+    return asVerb(verb);
+}
+/** Normalize a pack disclosure into a {@link DisclosureSpec} (default → base). */
+function disclosureSpec(disclosure) {
+    const levels = disclosure?.levels ?? [];
+    return {
+        levels: [...levels],
+        default: disclosure?.default ?? levels[0] ?? "summary",
+    };
+}
+/** Project declared filters onto verb params (enum for a value set, else string). */
+function projectFilters(filters) {
+    return (filters ?? []).map((filter) => {
+        const doc = filter.description ??
+            (filter.values
+                ? `Filter by ${filter.variable} (${filter.values.join(", ")}).`
+                : `Filter by ${filter.variable}.`);
+        if (filter.values) {
+            return {
+                kind: "enum",
+                name: filter.param,
+                doc,
+                values: [...filter.values],
+                repeatable: true,
+            };
+        }
+        return {
+            kind: "string",
+            name: filter.param,
+            doc,
+            repeatable: true,
+        };
+    });
+}
+/** Project a declared free-text search onto the `search` param. */
+function projectSearch(search) {
+    if (!search)
+        return [];
+    return [
+        {
+            kind: "string",
+            name: "search",
+            doc: search.description ?? `Search in ${search.variables.join(", ")}.`,
+        },
+    ];
+}
+/** Quote a filter example value when it is not a bare word. */
+function quoteExample(value) {
+    return /^[\w.-]+$/.test(value) ? value : JSON.stringify(value);
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+//# sourceMappingURL=compile.js.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * Canonical progressive-disclosure gating for pack lookups.
+ *
+ * A pack declares an ordered subset of the canonical levels
+ * (`constants.DETAIL_LEVELS`: `summary` < `standard` < `detailed`). A field or
+ * expand tags itself with the minimum canonical level at which it appears, and
+ * gating is by CANONICAL index — so a pack whose levels are `[summary, detailed]`
+ * still gates a `detailed`-tagged value at canonical index 2, and a
+ * `[summary, standard, detailed]` pack gates by the same scale. This is the
+ * single gating rule the SPARQL and GraphQL fetch paths share.
+ *
+ * The effective level is resolved through PR1's uniform {@link resolveDetail}:
+ * `--detail`/injected MCP `detail` (flag) > explicit config `detail` > the pack's
+ * `disclosure.default` > the canonical default. The config value counts only when
+ * the user actually set it (origin ≠ `default`) so a pack's declared default —
+ * block's `detailed`, standard's `summary` — is honoured under default config
+ * rather than shadowed by the built-in `detail: "standard"`.
+ */
+import { DETAIL_LEVELS } from "../../constants.js";
+import { resolveDetail } from "../render/index.js";
+/** The canonical level names, lowest → highest. */
+const CANONICAL = DETAIL_LEVELS;
+/** The gating index of a level name (unknown/undefined → base level 0). */
+function levelIndex(level) {
+    if (level === undefined)
+        return 0;
+    const index = CANONICAL.indexOf(level);
+    return index === -1 ? 0 : index;
+}
+/**
+ * Whether an entry tagged `entryLevel` is active at the resolved `activeLevel`.
+ *
+ * `activeLevel` undefined means "everything" (no disclosure requested — the
+ * sample path, and lookups without a declared disclosure).
+ */
+export function isActiveAtLevel(entryLevel, activeLevel) {
+    if (activeLevel === undefined)
+        return true;
+    return levelIndex(activeLevel) >= levelIndex(entryLevel);
+}
+/** The flat values (fields + sections) active at a level, by canonical index. */
+export function activeFields(lookup, activeLevel) {
+    return [...(lookup.fields ?? []), ...(lookup.sections ?? [])].filter((field) => isActiveAtLevel(field.level, activeLevel));
+}
+/** The expands active at a level, by canonical index (same rule as fields). */
+export function activeExpands(lookup, activeLevel) {
+    return (lookup.expand ?? []).filter((expand) => isActiveAtLevel(expand.level, activeLevel));
+}
+/**
+ * Resolve the effective canonical level for a lookup invocation.
+ *
+ * @param rt - The runtime (global flags + config loader).
+ * @param disclosure - The lookup's declared disclosure, if any.
+ * @returns The resolved canonical level, or `undefined` when the lookup declares
+ *   no disclosure (everything is fetched).
+ * @note Impure — awaits the memoized config load.
+ */
+export async function resolvePackDetail(rt, disclosure) {
+    if (disclosure === undefined)
+        return undefined;
+    const layers = await rt.loadConfig();
+    // Only an explicitly-set config detail outranks the pack's declared default;
+    // the built-in `detail: "standard"` is the last-resort fallback, not an
+    // override, so per-pack defaults survive under default config.
+    const configDetail = layers.origins.detail !== "default" ? layers.config.detail : undefined;
+    return resolveDetail({
+        flag: rt.globalFlags.detail,
+        config: configDetail,
+        // Mirror the projector's normalization (compile.disclosureSpec): a pack that
+        // declares `levels` but omits `default` defaults to its FIRST declared level,
+        // not the canonical `standard`. Without this the advertised default (help /
+        // MCP `detail` param) and the resolved fetch level diverge for dynamic packs.
+        specDefault: disclosure.default ?? disclosure.levels[0],
+    });
+}
+//# sourceMappingURL=disclosure.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure.js","sourceRoot":"","sources":["../../../../src/kernel/packs/disclosure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD,mDAAmD;AACnD,MAAM,SAAS,GAAsB,aAAa,CAAC;AAEnD,2EAA2E;AAC3E,SAAS,UAAU,CAAC,KAAyB;IAC3C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA8B,EAC9B,WAA+B;IAE/B,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,UAAU,CAAC,WAAW,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;AAC3D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAC1B,MAA0E,EAC1E,WAA+B;IAE/B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAClE,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CACrD,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAC3B,MAA0C,EAC1C,WAA+B;IAE/B,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAC7C,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAiB,EACjB,UAAsC;IAEtC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,UAAU,EAAE,CAAC;IACrC,6EAA6E;IAC7E,wEAAwE;IACxE,+DAA+D;IAC/D,MAAM,YAAY,GAChB,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,OAAO,aAAa,CAAC;QACnB,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM;QAC3B,MAAM,EAAE,YAAY;QACpB,6EAA6E;QAC7E,8EAA8E;QAC9E,4EAA4E;QAC5E,8EAA8E;QAC9E,WAAW,EAAE,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;KACxD,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,38 @@
+/**
+ * Glob expansion for pack lookups (`react/component/*`, `Nav*`, trailing `.`).
+ *
+ * Ported from the v1 suggester. A glob expands against the pack's known entity
+ * names; a non-glob passes through unchanged so callers can pipe the result
+ * straight into the lookup batch.
+ */
+/** Whether a string contains glob meta-characters (`*` or a trailing `.`). */
+export function isGlobPattern(name) {
+    if (name === "")
+        return false;
+    return name.includes("*") || name.endsWith(".");
+}
+/** Expand a glob against candidate names; a non-glob returns `[pattern]`. */
+export function expandGlob(pattern, candidates) {
+    if (!isGlobPattern(pattern))
+        return [pattern];
+    const normalized = pattern.endsWith(".") ? `${pattern}*` : pattern;
+    const regex = globToRegex(normalized);
+    return candidates.filter((name) => regex.test(name));
+}
+function globToRegex(glob) {
+    let pattern = "";
+    for (const char of glob) {
+        if (char === "*") {
+            pattern += ".*";
+            // biome-ignore lint/suspicious/noTemplateCurlyInString: regex meta-characters to escape, not a JS template
+        }
+        else if (".+^${}()|[]\\".includes(char)) {
+            pattern += `\\${char}`;
+        }
+        else {
+            pattern += char;
+        }
+    }
+    return new RegExp(`^${pattern}$`, "i");
+}
+//# sourceMappingURL=glob.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../../../src/kernel/packs/glob.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,UAA6B;IAE7B,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;IACnE,MAAM,KAAK,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACtC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,OAAO,IAAI,IAAI,CAAC;YAChB,2GAA2G;QAC7G,CAAC;aAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,OAAO,IAAI,KAAK,IAAI,EAAE,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC"}