@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/registry/css-utilities-runtime.d.ts

@@ -0,0 +1,133 @@
+/**
+ * CSS-utility-class runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadCssUtilityManifestsResult} produced by the
+ * css-utilities loader with domain-friendly accessors so
+ * `dbx_css_class_lookup` does not have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any `CssUtilityEntry`
+ * array via {@link createCssUtilityRegistryFromEntries} to drive the tool
+ * without touching disk.
+ *
+ * Equivalency engine: `searchByDeclarations` parses a raw CSS declaration
+ * string into a property→value map and scores every entry by Jaccard
+ * (intersection / union) plus a structural-property weighting. The
+ * structural set (`display`, `flex`, `flex-direction`, `align-items`,
+ * `justify-content`, `gap`, `grid-template-columns`) is weighted higher
+ * because matching on those usually means the same layout intent;
+ * matching on padding/margin alone is rarely interesting on its own.
+ */
+import type { LoadCssUtilityManifestsResult } from '../manifest/css-utilities-loader.js';
+import type { CssUtilityEntry } from '../manifest/css-utilities-schema.js';
+/**
+ * One scored candidate produced by the equivalency search.
+ */
+export interface ScoredCssUtilityMatch {
+    readonly entry: CssUtilityEntry;
+    readonly score: number;
+    readonly matchedProperties: readonly string[];
+    readonly extraEntryProperties: readonly string[];
+    readonly missingInputProperties: readonly string[];
+}
+/**
+ * Optional knobs accepted by `searchByDeclarations`. `limit` defaults to 5,
+ * `minScore` defaults to 0.05. Child utilities (entries with a `parent`
+ * slug) are filtered out by default; pass `includeChildren: true` to
+ * include them, or pass an explicit `parent` slug to scope the search to a
+ * specific parent's children.
+ */
+export interface SearchByDeclarationsOptions {
+    readonly limit?: number;
+    readonly minScore?: number;
+    readonly role?: string;
+    readonly parent?: string;
+    readonly includeChildren?: boolean;
+}
+/**
+ * Optional knobs accepted by `findByIntent`. Mirrors the child-filter
+ * semantics of {@link SearchByDeclarationsOptions}.
+ */
+export interface FindByIntentOptions {
+    readonly role?: string;
+    readonly parent?: string;
+    readonly includeChildren?: boolean;
+}
+/**
+ * Domain-friendly read API over a merged css-utility manifest set. All
+ * accessors return readonly arrays sorted by `slug` so tool output stays
+ * deterministic across runs.
+ */
+export interface CssUtilityRegistry {
+    readonly all: readonly CssUtilityEntry[];
+    readonly loadedSources: readonly string[];
+    readonly bySource: ReadonlyMap<string, readonly CssUtilityEntry[]>;
+    readonly byRole: ReadonlyMap<string, readonly CssUtilityEntry[]>;
+    readonly byParent: ReadonlyMap<string, readonly CssUtilityEntry[]>;
+    /**
+     * Returns the first entry whose `selector` or `slug` matches the
+     * supplied name. Accepts both `.dbx-flex-fill-0` and `dbx-flex-fill-0`
+     * — the leading dot is normalised away.
+     */
+    findByName(name: string): CssUtilityEntry | undefined;
+    /**
+     * Returns the children registered under the supplied parent slug,
+     * sorted by slug. Empty when the parent has no children (or does not
+     * exist).
+     */
+    findChildrenOf(parent: string): readonly CssUtilityEntry[];
+    /**
+     * Returns scored candidates whose `intent` field contains the supplied
+     * substring (case-insensitive). Children (entries with a `parent` slug)
+     * are excluded by default; pass `includeChildren: true` to include them,
+     * or pass an explicit `parent` slug to scope to that parent's children.
+     */
+    findByIntent(query: string, options?: FindByIntentOptions): readonly ScoredCssUtilityMatch[];
+    /**
+     * Equivalency search — parses a raw CSS declaration string into a
+     * property→value map, scores every entry, returns the top-N candidates.
+     * Child entries are excluded by default; see {@link SearchByDeclarationsOptions}.
+     */
+    searchByDeclarations(rawCss: string, options?: SearchByDeclarationsOptions): readonly ScoredCssUtilityMatch[];
+}
+/**
+ * Parses a raw CSS declaration string (e.g. `"display: flex; gap: 8px;"`)
+ * into a property→value map. Lowercases properties; trims and collapses
+ * whitespace in values; drops empty pairs.
+ *
+ * @param raw - The declaration string to parse.
+ * @returns The parsed property→value map (lowercased keys)
+ */
+export declare function parseDeclarations(raw: string): ReadonlyMap<string, string>;
+/**
+ * Builds a {@link CssUtilityRegistry} from a loader result. Single sorted-by-
+ * slug copy, plus pre-computed source/role buckets.
+ *
+ * @param loaded - The merged registry returned by `loadCssUtilityManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCssUtilityRegistry(loaded: LoadCssUtilityManifestsResult): CssUtilityRegistry;
+/**
+ * Builds a {@link CssUtilityRegistry} from a raw entry array. Used by tests
+ * and by callers that want to drive the tool without going through the
+ * loader pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list (will be sorted by slug)
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCssUtilityRegistryFromEntries(input: {
+    readonly entries: readonly CssUtilityEntry[];
+    readonly loadedSources: readonly string[];
+}): CssUtilityRegistry;
+/**
+ * Empty registry suitable as a default when the server has no manifest
+ * sources to load. Tools wired against this behave like a registry that
+ * loaded successfully with zero entries.
+ */
+export declare const EMPTY_CSS_UTILITY_REGISTRY: CssUtilityRegistry;

package/src/lib/mcp-scan/registry/dbx-docs-ui-examples-runtime.d.ts

@@ -0,0 +1,58 @@
+/**
+ * dbx-docs-ui-examples runtime registry wrapper.
+ *
+ * Wraps the merged manifest result with domain-friendly accessors so the
+ * `dbx_ui_examples` and `dbx_ui_search` tools can query entries without
+ * walking Maps directly. Mirrors `ui-components-runtime.ts`: registry is
+ * loaded once at server startup and passed into the tool factories.
+ */
+import type { LoadDbxDocsUiExamplesManifestsResult } from '../manifest/dbx-docs-ui-examples-loader.js';
+import type { DbxDocsUiExampleEntry } from '../manifest/dbx-docs-ui-examples-schema.js';
+export interface DbxDocsUiExamplesRegistry {
+    readonly all: readonly DbxDocsUiExampleEntry[];
+    readonly loadedSources: readonly string[];
+    readonly categories: readonly string[];
+    readonly modules: readonly string[];
+    /**
+     * Returns the entry whose slug matches exactly. Slugs are
+     * case-sensitive; collisions across modules are resolved at load time.
+     */
+    findBySlug(slug: string): DbxDocsUiExampleEntry | undefined;
+    /**
+     * Returns every entry whose `category` field matches exactly.
+     */
+    findByCategory(category: string): readonly DbxDocsUiExampleEntry[];
+    /**
+     * Returns every entry whose `relatedSlugs` contains the supplied UI
+     * component slug. Used by `dbx_ui_search` to surface relevant examples
+     * alongside component results.
+     */
+    findRelatedTo(uiComponentSlug: string): readonly DbxDocsUiExampleEntry[];
+}
+/**
+ * Builds a {@link DbxDocsUiExamplesRegistry} from a loader result.
+ *
+ * @param loaded - The merged manifest loader output.
+ * @returns A registry with slug, category, module, and related-slug indices.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createDbxDocsUiExamplesRegistry(loaded: LoadDbxDocsUiExamplesManifestsResult): DbxDocsUiExamplesRegistry;
+/**
+ * Builds a {@link DbxDocsUiExamplesRegistry} from a raw entry array, used by tests and tools that synthesize entries directly.
+ *
+ * @param input - Pre-built entries and source labels.
+ * @param input.entries - The example entries to index.
+ * @param input.loadedSources - Labels of the manifest sources that contributed the entries.
+ * @returns A registry with slug, category, module, and related-slug indices.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createDbxDocsUiExamplesRegistryFromEntries(input: {
+    readonly entries: readonly DbxDocsUiExampleEntry[];
+    readonly loadedSources: readonly string[];
+}): DbxDocsUiExamplesRegistry;
+/**
+ * Empty registry suitable as a default when no example manifests are
+ * configured. Tools wired against this behave like an empty cluster —
+ * "no examples" rather than crashing.
+ */
+export declare const EMPTY_DBX_DOCS_UI_EXAMPLES_REGISTRY: DbxDocsUiExamplesRegistry;

package/src/lib/mcp-scan/registry/downstream-models-runtime.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Runtime cache for downstream `<x>-firebase` model catalogs.
+ *
+ * `dbx_model_search` and `dbx_model_lookup` consult this cache after the
+ * upstream `FIREBASE_MODELS` registry to extend their reach into the
+ * caller's workspace. The first call performs discovery + extraction; the
+ * result is memoised for the server lifetime keyed by
+ * (workspaceRoot, componentDirs).
+ *
+ * No mtime-based invalidation — the agent loop is short enough that a stale
+ * catalog after an in-flight downstream model edit is fixed by reconnecting
+ * the MCP server. That mirrors the upstream registry, which is baked at
+ * build time and never refreshed at runtime.
+ */
+import { type DownstreamFirebasePackage } from '../scan/discover-firebase-packages.js';
+import type { FirebaseModel, FirebaseModelGroup } from './firebase-models.js';
+/**
+ * One per-package extraction failure. Surfaced so a malformed downstream
+ * package doesn't silently drop without a trace.
+ */
+export interface DownstreamCatalogError {
+    /**
+     * Workspace-relative component directory the failure occurred under.
+     */
+    readonly componentDir: string;
+    /**
+     * Workspace-relative source file path when the failure was tied to a
+     * single file; equal to `componentDir` for whole-package failures.
+     */
+    readonly sourceFile: string;
+    /**
+     * Human-readable failure message.
+     */
+    readonly message: string;
+}
+/**
+ * Aggregated downstream catalog for a workspace + componentDirs scope.
+ */
+export interface DownstreamCatalog {
+    /**
+     * Every detected downstream model, sorted root-first then alphabetically.
+     */
+    readonly models: readonly FirebaseModel[];
+    /**
+     * Every detected downstream model-group container.
+     */
+    readonly modelGroups: readonly FirebaseModelGroup[];
+    /**
+     * The packages the catalog was assembled from. Includes packages that
+     * produced zero models (kept so the formatter can report what was
+     * scanned).
+     */
+    readonly packages: readonly DownstreamFirebasePackage[];
+    /**
+     * Per-package extraction failures, if any.
+     */
+    readonly errors: readonly DownstreamCatalogError[];
+    /**
+     * `true` when the catalog was built via auto-discovery (no
+     * `componentDirs` override). The search formatter uses this to render
+     * the "no downstream packages discovered" hint.
+     */
+    readonly discoveryUsed: boolean;
+}
+/**
+ * Input for {@link getDownstreamCatalog}.
+ */
+export interface GetDownstreamCatalogInput {
+    /**
+     * Absolute workspace root the scan should run against.
+     */
+    readonly workspaceRoot: string;
+    /**
+     * Optional explicit component directories (workspace-relative). When
+     * supplied, discovery is skipped and only these directories are scanned.
+     * When omitted, `components/*-firebase` is auto-discovered.
+     */
+    readonly componentDirs?: readonly string[];
+}
+/**
+ * Returns the downstream catalog for the supplied workspace + dirs scope.
+ * Cached for the server lifetime. Concurrent callers get the same in-flight
+ * promise and share the underlying ts-morph parses.
+ *
+ * @param input - The scope to scan.
+ * @returns The assembled downstream catalog.
+ */
+export declare function getDownstreamCatalog(input: GetDownstreamCatalogInput): Promise<DownstreamCatalog>;
+/**
+ * Drops every cached entry. Intended for spec use only — the runtime
+ * never needs to call this because the cache is server-lifetime.
+ */
+export declare function clearDownstreamCatalogCache(): void;

package/src/lib/mcp-scan/registry/filters-runtime.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Filters runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadFilterManifestsResult} produced by the loader with
+ * domain-friendly accessors so the lookup tool and the registry resource
+ * don't have to walk Maps directly.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any entry array via
+ * {@link createFilterRegistryFromEntries} to drive the tool without touching
+ * disk.
+ *
+ * Manifest entries (flat, JSON-friendly shape) are converted into the
+ * `FilterEntryInfo` shape historically exposed by `tools/data/filter-entries.ts`.
+ * The lookup tool keeps consuming that shape so this module is the only seam
+ * that changed when the hand-written entries were deleted.
+ */
+import type { LoadFilterManifestsResult } from '../manifest/filters-loader.js';
+import type { FilterEntry } from '../manifest/filters-schema.js';
+/**
+ * Discriminator between Angular directives (`[dbxFilter*]`) and shape-only
+ * patterns (`ClickableFilterPreset`). Mirrors the legacy `FilterEntryKind`
+ * exposed by `tools/data/filter-entries.ts`.
+ */
+export type FilterKind = 'directive' | 'pattern';
+/**
+ * One documented input on a filter directive — alias, type, description.
+ */
+export interface FilterEntryInputInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+}
+/**
+ * One curated filter entry surfaced through `dbx_filter_lookup`. Mirrors the
+ * legacy hand-written shape so the lookup tool didn't have to be rewritten
+ * when the manifest pipeline replaced the inline data table.
+ */
+export interface FilterEntryInfo {
+    readonly slug: string;
+    readonly kind: FilterKind;
+    readonly className: string;
+    readonly selector: string | undefined;
+    readonly module: string;
+    readonly description: string;
+    readonly inputs: readonly FilterEntryInputInfo[];
+    readonly outputs: readonly FilterEntryInputInfo[];
+    readonly relatedSlugs: readonly string[];
+    readonly skillRefs: readonly string[];
+    readonly example: string;
+}
+/**
+ * Domain-friendly read API over a merged filters manifest set. All accessors
+ * return readonly arrays preserving the order the manifests declared their
+ * entries (manifests are walked in source order).
+ */
+export interface FilterRegistry {
+    readonly all: readonly FilterEntryInfo[];
+    readonly loadedSources: readonly string[];
+    readonly kinds: readonly FilterKind[];
+    /**
+     * Returns the entry whose slug matches `slug` exactly. Slugs are unique
+     * across manifests (collisions emit a loader warning and the second-loaded
+     * entry wins).
+     */
+    findBySlug(slug: string): FilterEntryInfo | undefined;
+    /**
+     * Returns the entry whose TypeScript class name matches `className`
+     * (case-insensitive).
+     */
+    findByClassName(className: string): FilterEntryInfo | undefined;
+    /**
+     * Returns the directive entry whose `selector` matches `selector`. The
+     * lookup tolerates the `[dbxFoo]` attribute form and the bracket-less
+     * `dbxFoo` form so callers can use whichever syntax their host context
+     * renders.
+     */
+    findBySelector(selector: string): FilterEntryInfo | undefined;
+    /**
+     * Returns every entry whose `kind` field matches `kind` exactly, in
+     * registry order.
+     */
+    findByKind(kind: FilterKind): readonly FilterEntryInfo[];
+}
+/**
+ * Stable rendering order for kind buckets in the catalog view.
+ */
+export declare const FILTER_KIND_ORDER: readonly FilterKind[];
+/**
+ * Builds a {@link FilterRegistry} from a loader result.
+ *
+ * @param loaded - The merged registry returned by `loadFilterManifests`
+ * @returns A domain-friendly read API over the merged entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createFilterRegistry(loaded: LoadFilterManifestsResult): FilterRegistry;
+/**
+ * Builds a {@link FilterRegistry} from a raw {@link FilterEntryInfo} array.
+ * Used by tests that need to drive the tool without going through the loader
+ * pipeline.
+ *
+ * @param input - The entries plus the source labels to advertise.
+ * @param input.entries - The full entry list.
+ * @param input.loadedSources - Source labels reported via `registry.loadedSources`
+ * @returns A domain-friendly read API over the supplied entries.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createFilterRegistryFromEntries(input: {
+    readonly entries: readonly FilterEntryInfo[];
+    readonly loadedSources: readonly string[];
+}): FilterRegistry;
+/**
+ * Empty registry suitable as a default when the server has no filters
+ * manifest sources to load. Tools wired against this registry behave like
+ * a registry that loaded successfully with zero entries.
+ */
+export declare const EMPTY_FILTER_REGISTRY: FilterRegistry;
+/**
+ * Converts a manifest entry into the {@link FilterEntryInfo} shape the lookup
+ * tool consumes. Pattern entries (no `@Directive` decorator) carry an
+ * `undefined` selector and empty inputs/outputs.
+ *
+ * @param entry - The manifest entry to convert.
+ * @returns The matching FilterEntryInfo.
+ */
+export declare function toFilterEntryInfo(entry: FilterEntry): FilterEntryInfo;