@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/kernel/interactivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactivity.js","sourceRoot":"","sources":["../../../src/kernel/interactivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACvE,CAAC"}

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

@@ -0,0 +1,187 @@
+/**
+ * Assemble the EFFECTIVE capability modules at dispatch.
+ *
+ * The `--help`/`__complete` fast paths use the STATIC capabilities (the
+ * authored modules plus the stories `pragma.conf.ts` declares, compiled at
+ * module load) only. When a real command runs, this merges in the stories the
+ * PROJECT declares: one may override a story-backed noun (replacing that
+ * module) or introduce a new one; one that claims an authored, non-story noun
+ * (config, ontology, …) is a hard error, and any surviving `(noun, verb)`
+ * collision is caught by uniqueness.
+ *
+ * Precedence is config > package > static, and within config the closer
+ * declaration wins: `packs[].stories` (the story a declared pack supplies) is
+ * overridden by the top-level `stories` (the project's own, most specific,
+ * statement). PACKAGE stories — the `stories/*.json` the answering pack carries
+ * — are third-party data, so they go through {@link validateStories}, which
+ * drops a bad one with a reported problem, CANNOT throw, and lets a package
+ * ADD a noun but never replace one the CLI ships. Config stories stay fatal and
+ * may override: the user owns those, and a broken `pragma.config.ts` already
+ * fails every command.
+ *
+ * zod is reached only through {@link parsePackDefinition} (lazy) — this module
+ * is imported at dispatch, never on the fast path, so validating config stories
+ * costs nothing on `--help`/`__complete`.
+ */
+import { PragmaError } from "../error/index.js";
+import { compileStoryModule } from "./compile.js";
+import { parsePackDefinition } from "./schema.js";
+import { assertUniqueVerbs } from "./uniqueness.js";
+/**
+ * Turn pack-carried story records into usable entries, DROPPING (never throwing
+ * on) the ones that cannot be used.
+ *
+ * TOTAL by construction: `JSON.parse` and `parsePackDefinition` happen inside
+ * ONE try per record, so a malformed file and a schema-invalid one are handled
+ * identically. That is not a nicety — package stories reach dispatch before the
+ * command tree exists, so a throw here would fail EVERY command, including
+ * `sources update` and `doctor`, the only two that can recover from it.
+ *
+ * Two packages claiming one noun: the last declared wins and the shadowed one
+ * is reported, through this same channel.
+ *
+ * A package story may only introduce a NOUN THE CLI DOES NOT HAVE. Every static
+ * noun is reserved — the kernel's own AND the ones the distribution declares as
+ * stories — because the merge replaces a noun WHOLESALE: a package claiming
+ * `block` would swap this distribution's design-system reads for its own in a
+ * project that did nothing but declare a dependency. Overriding a shipped noun
+ * stays a CONFIG decision — that file is the user's own.
+ *
+ * @param records - The raw story records the answering pack carries.
+ * @param staticModules - The static capabilities, to detect a story claiming a
+ *   noun the CLI already ships.
+ * @returns The usable entries and the problems, both possibly empty.
+ */
+export function validateStories(records, staticModules) {
+    const reserved = new Set(staticModules.map((module) => module.name));
+    const byNoun = new Map();
+    const problems = [];
+    for (const record of records) {
+        try {
+            const definition = parsePackDefinition(JSON.parse(record.content), record.source);
+            if (reserved.has(definition.noun)) {
+                problems.push({
+                    source: record.source,
+                    message: `its noun "${definition.noun}" is a command this CLI already ships and cannot be replaced by a package.`,
+                });
+                continue;
+            }
+            const shadowed = byNoun.get(definition.noun);
+            if (shadowed) {
+                problems.push({
+                    source: shadowed.source,
+                    message: `its "${definition.noun}" story is shadowed by ${record.source}.`,
+                });
+            }
+            byNoun.set(definition.noun, { source: record.source, definition });
+        }
+        catch (error) {
+            problems.push({
+                source: record.source,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { entries: [...byNoun.values()], problems };
+}
+/**
+ * The PROJECT's config-declared stories, weakest tier first.
+ *
+ * A tier whose origin is `"default"` is the DISTRIBUTION's own declaration,
+ * which `capabilities/distribution.ts` has already compiled into the static
+ * modules — that is what keeps those nouns on the `--help`/`__complete` fast
+ * path. Merging it again would recompile and re-validate it on every dispatch,
+ * and would put the distribution's own declarations behind a validator whose
+ * failure is fatal. `readConfig`'s per-field pick replaces wholesale, so an
+ * origin off `"default"` means the project (or global layer) owns that field.
+ *
+ * @param layers - The resolved config layers.
+ * @returns The `packs[].stories` tier, then the top-level `stories` tier.
+ */
+function projectStoryTiers(layers) {
+    const packStories = layers.origins.packs === "default"
+        ? []
+        : (layers.config.packs ?? []).flatMap((pack) => typeof pack === "string" ? [] : (pack.stories ?? []));
+    const topLevel = layers.origins.stories === "default" ? [] : (layers.config.stories ?? []);
+    return [[...packStories], [...topLevel]];
+}
+/**
+ * Merge the package- and config-declared story packs into the static capabilities.
+ *
+ * @param staticModules - The static capabilities (authored + declared stories).
+ * @param layers - The resolved config layers (its `packs`, `stories`, `prefixes`).
+ * @param packageStories - The already-validated stories the answering pack
+ *   carries (see {@link validateStories}); weaker than either config tier.
+ * @returns The effective modules, uniqueness-checked.
+ * @throws PragmaError CONFIG_ERROR on an invalid CONFIG story, a config story
+ *   claiming an authored non-story noun, or a duplicate noun within one config
+ *   tier. Package stories were already screened and never throw here.
+ */
+export function assembleEffectiveModules(staticModules, layers, packageStories = []) {
+    const tiers = projectStoryTiers(layers);
+    if (packageStories.length === 0 && tiers.every((tier) => tier.length === 0)) {
+        return staticModules;
+    }
+    const prefixes = layers.config.prefixes ?? {};
+    // Only a module compiled from a story may be replaced by one; the authored
+    // nouns (config, ontology, doctor, …) are the CLI itself.
+    const overridable = new Set(staticModules.filter((module) => module.story).map((module) => module.name));
+    const staticNouns = new Set(staticModules.map((module) => module.name));
+    // Keyed by noun so the stronger tier REPLACES the weaker one — declaring a
+    // story both on its pack and at the top level is a refinement, not an error.
+    const dynamic = new Map();
+    for (const entry of packageStories) {
+        dynamic.set(entry.definition.noun, compileStoryModule(entry.definition, { label: entry.source, origin: "package" }, prefixes));
+    }
+    for (const tier of tiers) {
+        const seen = new Set();
+        for (const raw of tier) {
+            const definition = parsePackDefinition(raw, "config");
+            if (seen.has(definition.noun)) {
+                throw PragmaError.configError(`Duplicate story noun "${definition.noun}" in config.`);
+            }
+            if (staticNouns.has(definition.noun) &&
+                !overridable.has(definition.noun)) {
+                throw PragmaError.configError(`Story noun "${definition.noun}" collides with a built-in command.`);
+            }
+            seen.add(definition.noun);
+            dynamic.set(definition.noun, compileStoryModule(definition, { label: "config", origin: "config" }, prefixes));
+        }
+    }
+    // Drop the static module for any noun a config story overrides, then append
+    // the dynamic modules.
+    const kept = staticModules.filter((module) => !dynamic.has(module.name));
+    const effective = [...kept, ...dynamic.values()];
+    assertUniqueVerbs(effective.flatMap((module) => [...module.verbs]));
+    return effective;
+}
+/**
+ * Load the effective modules for a real invocation: read the layered config and
+ * the answering pack's carried stories, and merge both into the static
+ * capabilities.
+ *
+ * Reached only at DISPATCH (real command / MCP serve), never on the
+ * `--help`/`__complete` fast path, so the config read, the pack read and zod
+ * validation never cost the storeless paths. The runtime pieces are
+ * dynamic-imported to keep even this module's static graph free of them.
+ *
+ * @param staticModules - The static capabilities (authored + declared stories).
+ * @param cwd - The directory to resolve project config against.
+ * @returns The effective modules, plus the package stories that were ignored —
+ *   callers surface those on stderr rather than failing the command.
+ * @note Impure — reads the project/global config and the answering pack.
+ */
+export async function loadEffectiveModules(staticModules, cwd) {
+    const [{ readConfig }, { resolveSources }, { activeStories }] = await Promise.all([
+        import("../config/readConfig.js"),
+        import("../runtime/resolveSources.js"),
+        import("../runtime/graphpack/stories.js"),
+    ]);
+    const layers = await readConfig(cwd);
+    const { entries, problems } = validateStories(activeStories(resolveSources(layers, cwd)), staticModules);
+    return {
+        modules: assembleEffectiveModules(staticModules, layers, entries),
+        problems,
+    };
+}
+//# sourceMappingURL=collect.js.map

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

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

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"}