@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/manifest/ui-components-schema.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Arktype schemas for the ui-components manifest format.
+ *
+ * Manifests are JSON files that catalog UI components, directives, pipes, and
+ * services from one source — either a `@dereekb/*` package bundled with this
+ * MCP, or a downstream-app manifest discovered via `dbx-mcp.config.json`.
+ * Each manifest contributes its entries to a merged registry that the
+ * `lookup-ui` and `search-ui` MCP tools query.
+ *
+ * The schemas in this module are the *contract* — once a downstream app
+ * commits a manifest file, breaking changes here mean every downstream
+ * regenerates. Optional fields can be added in v1; structural breaks must
+ * bump the manifest `version` and update the loader's accepted versions.
+ */
+/**
+ * High-level category bucket for a UI entry — the primary search index.
+ */
+export declare const UI_COMPONENT_CATEGORIES: readonly ["layout", "list", "button", "card", "feedback", "overlay", "navigation", "text", "screen", "action", "router", "misc"];
+/**
+ * Static type for the closed category vocabulary.
+ */
+export type UiComponentCategoryValue = (typeof UI_COMPONENT_CATEGORIES)[number];
+/**
+ * Angular construct kind. Drives output formatting in tools (components have
+ * content projection, directives advertise selectors, pipes have transform
+ * signatures, services expose injection tokens).
+ */
+export declare const UI_COMPONENT_KINDS: readonly ["component", "directive", "pipe", "service"];
+/**
+ * Static type for the closed kind vocabulary.
+ */
+export type UiComponentKindValue = (typeof UI_COMPONENT_KINDS)[number];
+/**
+ * One input (signal `input()` or `@Input()`-decorated property) on a UI entry.
+ */
+export declare const UiComponentInputEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    default?: string | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link UiComponentInputEntry}.
+ */
+export type UiComponentInputEntry = typeof UiComponentInputEntry.infer;
+/**
+ * One output (signal `output()` or `@Output()` `EventEmitter`) on a UI entry.
+ */
+export declare const UiComponentOutputEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    emits: string;
+    description: string;
+}, {}>;
+/**
+ * Static type inferred from {@link UiComponentOutputEntry}.
+ */
+export type UiComponentOutputEntry = typeof UiComponentOutputEntry.infer;
+/**
+ * One UI entry inside a manifest. Each entry describes a single exported
+ * Angular construct — its selector, where it lives, what category it indexes
+ * under, and the inputs/outputs callers wire to.
+ *
+ * Required fields are the minimum needed for `lookup-ui` to render a useful
+ * answer. Every other field is optional so the auto-generator can populate
+ * them progressively.
+ */
+export declare const UiComponentEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    slug: string;
+    category: "action" | "list" | "screen" | "text" | "layout" | "button" | "card" | "feedback" | "overlay" | "navigation" | "router" | "misc";
+    kind: "pipe" | "component" | "directive" | "service";
+    selector: string;
+    className: string;
+    module: string;
+    description: string;
+    inputs: {
+        name: string;
+        type: string;
+        description: string;
+        required: boolean;
+        default?: string | undefined;
+    }[];
+    outputs: {
+        name: string;
+        emits: string;
+        description: string;
+    }[];
+    contentProjection?: string | undefined;
+    relatedSlugs?: string[] | undefined;
+    skillRefs?: string[] | undefined;
+    example?: string | undefined;
+    minimalExample?: string | undefined;
+    deprecated?: string | boolean | undefined;
+    since?: string | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link UiComponentEntry}. Co-named with the const
+ * so callers can write `import { UiComponentEntry }` and use it in both value
+ * and type positions.
+ */
+export type UiComponentEntry = typeof UiComponentEntry.infer;
+/**
+ * Top-level manifest envelope. One file per source. The `source` field is the
+ * workspace-unique label used to detect collisions; `module` carries the npm
+ * package the entries ship in.
+ *
+ * `version` is the schema version. The loader currently accepts only
+ * `version: 1`; manifests with any other value are rejected (strict
+ * sources) or warned-and-skipped (non-strict sources).
+ */
+export declare const UiComponentManifest: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    source: string;
+    module: string;
+    generatedAt: string;
+    generator: string;
+    entries: {
+        slug: string;
+        category: "action" | "list" | "screen" | "text" | "layout" | "button" | "card" | "feedback" | "overlay" | "navigation" | "router" | "misc";
+        kind: "pipe" | "component" | "directive" | "service";
+        selector: string;
+        className: string;
+        module: string;
+        description: string;
+        inputs: {
+            name: string;
+            type: string;
+            description: string;
+            required: boolean;
+            default?: string | undefined;
+        }[];
+        outputs: {
+            name: string;
+            emits: string;
+            description: string;
+        }[];
+        contentProjection?: string | undefined;
+        relatedSlugs?: string[] | undefined;
+        skillRefs?: string[] | undefined;
+        example?: string | undefined;
+        minimalExample?: string | undefined;
+        deprecated?: string | boolean | undefined;
+        since?: string | undefined;
+    }[];
+}, {}>;
+/**
+ * Static type inferred from {@link UiComponentManifest}.
+ */
+export type UiComponentManifest = typeof UiComponentManifest.infer;

package/src/lib/mcp-scan/manifest/utils-loader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Loader for utils manifests.
+ *
+ * Reads one or more manifest files (bundled `@dereekb/*` registries plus any
+ * downstream-app manifests discovered via `dbx-mcp.config.json`), validates
+ * them against {@link UtilManifest}, and merges them into a single
+ * lookup-ready registry.
+ *
+ * Failure handling mirrors the pipes loader: bundled sources are strict by
+ * default, external sources are not. If no source loads successfully the
+ * loader throws.
+ */
+import { type UtilEntry } from './utils-schema.js';
+import { type ManifestLoaderWarning, type ManifestReadFile, type ManifestSource } from './manifest-loader-base.js';
+/**
+ * One manifest the loader is asked to ingest. `path` must be absolute.
+ */
+export type UtilManifestSource = ManifestSource;
+/**
+ * Function shape used by the loader to read manifest contents.
+ */
+export type UtilManifestReadFile = ManifestReadFile;
+/**
+ * Discriminated union of all non-fatal events the loader emits.
+ */
+export type UtilLoaderWarning = ManifestLoaderWarning;
+/**
+ * Input to {@link loadUtilManifests}.
+ */
+export interface LoadUtilManifestsInput {
+    readonly sources: readonly UtilManifestSource[];
+    readonly readFile?: UtilManifestReadFile;
+}
+/**
+ * Result of {@link loadUtilManifests}. `entries` is the merged lookup map
+ * keyed by `${module}::${slug}`; `categoryIndex` is the inverted index
+ * from category value to entry keys (sorted alphabetically for
+ * deterministic output).
+ */
+export interface LoadUtilManifestsResult {
+    readonly entries: ReadonlyMap<string, UtilEntry>;
+    readonly categoryIndex: ReadonlyMap<string, readonly string[]>;
+    readonly warnings: readonly UtilLoaderWarning[];
+    readonly loadedSources: readonly string[];
+}
+/**
+ * Loads, validates, and merges the supplied manifest sources into a single
+ * registry suitable for the `dbx_util_lookup` / `dbx_util_search` MCP tools.
+ *
+ * @param input - Manifest sources plus an optional injected `readFile`
+ * @returns Merged entries, category index, deterministic warnings, and the list of source labels that loaded.
+ * @throws {Error} When a strict source fails or when zero manifests load successfully.
+ */
+export declare function loadUtilManifests(input: LoadUtilManifestsInput): Promise<LoadUtilManifestsResult>;

package/src/lib/mcp-scan/manifest/utils-schema.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Arktype schemas for the utils manifest format.
+ *
+ * Manifests are JSON files that catalog utilities (functions, classes,
+ * constants, factory factories) opted in via the `@dbxUtil` JSDoc marker.
+ * One manifest per source — bundled `@dereekb/*` packages plus any
+ * downstream-app manifests discovered via `dbx-mcp.config.json` — feeds
+ * the merged registry that powers the `dbx_util_lookup` and
+ * `dbx_util_search` MCP tools.
+ *
+ * The schemas in this module are the *contract* — once a downstream app
+ * commits a manifest file, breaking changes here mean every downstream
+ * regenerates. Optional fields can be added in v1; structural breaks must
+ * bump the manifest `version` and update the loader's accepted versions.
+ */
+/**
+ * Closed vocabulary describing the kind of TypeScript export the utility
+ * is. The extractor auto-detects from the source declaration (function vs.
+ * class vs. const), and authors can override via `@dbxUtilKind`. `factory`
+ * is reserved for functions whose return type is itself a function — used
+ * by the configurable factory pattern.
+ */
+export declare const UTIL_KINDS: readonly ["function", "class", "const", "factory"];
+/**
+ * Static type for the closed kind vocabulary.
+ */
+export type UtilKindValue = (typeof UTIL_KINDS)[number];
+/**
+ * One documented parameter of a function/factory utility, or one
+ * constructor parameter for a class utility.
+ */
+export declare const UtilParamEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    type: string;
+    description: string;
+    optional: boolean;
+}, {}>;
+/**
+ * Static type inferred from {@link UtilParamEntry}.
+ */
+export type UtilParamEntry = typeof UtilParamEntry.infer;
+/**
+ * One utility entry inside a manifest. Each entry describes a single
+ * exported symbol — its slug, kind, category, signature, and the
+ * documented parameters/return.
+ *
+ * Required fields are the minimum needed for `dbx_util_lookup` to render
+ * a useful answer; every other field is optional so the auto-generator
+ * can populate them progressively.
+ */
+export declare const UtilEntry: import("arktype/internal/variants/object.ts").ObjectType<{
+    slug: string;
+    name: string;
+    kind: "function" | "class" | "const" | "factory";
+    category: string;
+    module: string;
+    subpath: string;
+    signature: string;
+    description: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+        optional: boolean;
+    }[];
+    returns: string;
+    tags: string[];
+    example?: string | undefined;
+    relatedSlugs?: string[] | undefined;
+    skillRefs?: string[] | undefined;
+    deprecated?: string | boolean | undefined;
+    since?: string | undefined;
+}, {}>;
+/**
+ * Static type inferred from {@link UtilEntry}.
+ */
+export type UtilEntry = typeof UtilEntry.infer;
+/**
+ * Top-level manifest envelope. One file per source. The `source` field is
+ * the workspace-unique label used to detect collisions; `module` carries
+ * the npm package the entries ship in.
+ *
+ * `version` is the schema version. The loader currently accepts only
+ * `version: 1`; manifests with any other value are rejected (strict
+ * sources) or warned-and-skipped (non-strict sources).
+ */
+export declare const UtilManifest: import("arktype/internal/variants/object.ts").ObjectType<{
+    version: 1;
+    source: string;
+    module: string;
+    generatedAt: string;
+    generator: string;
+    entries: {
+        slug: string;
+        name: string;
+        kind: "function" | "class" | "const" | "factory";
+        category: string;
+        module: string;
+        subpath: string;
+        signature: string;
+        description: string;
+        params: {
+            name: string;
+            type: string;
+            description: string;
+            optional: boolean;
+        }[];
+        returns: string;
+        tags: string[];
+        example?: string | undefined;
+        relatedSlugs?: string[] | undefined;
+        skillRefs?: string[] | undefined;
+        deprecated?: string | boolean | undefined;
+        since?: string | undefined;
+    }[];
+}, {}>;
+/**
+ * Static type inferred from {@link UtilManifest}.
+ */
+export type UtilManifest = typeof UtilManifest.infer;

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

@@ -0,0 +1,173 @@
+/**
+ * Actions runtime registry wrapper.
+ *
+ * Wraps the raw {@link LoadActionManifestsResult} produced by the loader
+ * with domain-friendly accessors so the lookup tool and the registry
+ * resource don't have to walk Maps directly.
+ *
+ * Manifest entries (flat, JSON-friendly shape) are converted into the
+ * `ActionEntryInfo` discriminated union historically exposed by
+ * `registry/actions.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 { LoadActionManifestsResult } from '../manifest/actions-loader.js';
+import type { ActionEntry, DbxActionStateValue } from '../manifest/actions-schema.js';
+/**
+ * Three roles share a slug index but differ in payload.
+ */
+export type ActionEntryRole = 'directive' | 'store' | 'state';
+/**
+ * Stable rendering order for role buckets in the catalog view.
+ */
+export declare const ACTION_ROLE_ORDER: readonly ActionEntryRole[];
+/**
+ * Common base fields shared across all three entry shapes.
+ */
+export interface ActionEntryBase {
+    readonly slug: string;
+    readonly role: ActionEntryRole;
+    readonly description: string;
+    readonly skillRefs: readonly string[];
+    readonly example: string;
+}
+/**
+ * One input on a directive.
+ */
+export interface ActionInputInfo {
+    readonly alias: string;
+    readonly propertyName: string;
+    readonly type: string;
+    readonly required: boolean;
+    readonly defaultValue?: string;
+    readonly description: string;
+}
+/**
+ * One output / event emitter on a directive.
+ */
+export interface ActionOutputInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+}
+/**
+ * Method exposed by a store entry.
+ */
+export interface ActionMethodInfo {
+    readonly name: string;
+    readonly signature: string;
+    readonly description: string;
+}
+/**
+ * Observable exposed by a store entry.
+ */
+export interface ActionObservableInfo {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+}
+/**
+ * Directive entry. Captures selector + class + DI behavior + the action
+ * states the directive interacts with.
+ */
+export interface ActionDirectiveInfo extends ActionEntryBase {
+    readonly role: 'directive';
+    readonly selector: string;
+    readonly className: string;
+    readonly module: string;
+    readonly inputs: readonly ActionInputInfo[];
+    readonly outputs: readonly ActionOutputInfo[];
+    readonly producesContext: boolean;
+    readonly consumesContext: boolean;
+    readonly stateInteraction: readonly DbxActionStateValue[];
+}
+/**
+ * Store entry. There is exactly one in the registry today
+ * (`ActionContextStore`), but the shape allows derivative stores to join.
+ */
+export interface ActionStoreInfo extends ActionEntryBase {
+    readonly role: 'store';
+    readonly className: string;
+    readonly module: string;
+    readonly methods: readonly ActionMethodInfo[];
+    readonly observables: readonly ActionObservableInfo[];
+    readonly disabledKeyDefaults: readonly string[];
+}
+/**
+ * State entry — one per member of the `DbxActionState` enum.
+ */
+export interface ActionStateInfo extends ActionEntryBase {
+    readonly role: 'state';
+    readonly enumName: 'DbxActionState';
+    readonly stateValue: DbxActionStateValue;
+    readonly literal: string;
+    readonly module: string;
+    readonly transitionsFrom: readonly DbxActionStateValue[];
+    readonly transitionsTo: readonly DbxActionStateValue[];
+}
+/**
+ * Discriminated union exposed to the lookup tool.
+ */
+export type ActionEntryInfo = ActionDirectiveInfo | ActionStoreInfo | ActionStateInfo;
+/**
+ * Domain-friendly read API over a merged actions manifest set.
+ */
+export interface ActionRegistry {
+    readonly all: readonly ActionEntryInfo[];
+    readonly loadedSources: readonly string[];
+    readonly roles: readonly ActionEntryRole[];
+    /**
+     * Returns the entry whose slug matches `slug` exactly.
+     */
+    findBySlug(slug: string): ActionEntryInfo | undefined;
+    /**
+     * Returns the directive entry whose selector matches `selector` exactly.
+     */
+    findDirectiveBySelector(selector: string): ActionDirectiveInfo | undefined;
+    /**
+     * Returns the entry whose TypeScript class name matches `className`
+     * (case-insensitive).
+     */
+    findByClassName(className: string): ActionEntryInfo | undefined;
+    /**
+     * Returns the state entry whose `stateValue` matches.
+     */
+    findStateByValue(stateValue: DbxActionStateValue): ActionStateInfo | undefined;
+    /**
+     * Returns every entry in the supplied role, in registry order.
+     */
+    findByRole(role: ActionEntryRole): readonly ActionEntryInfo[];
+}
+/**
+ * Builds an {@link ActionRegistry} from a loader result.
+ *
+ * @param loaded - The result of loading action manifests.
+ * @returns A fully-indexed {@link ActionRegistry}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createActionRegistry(loaded: LoadActionManifestsResult): ActionRegistry;
+/**
+ * Builds an {@link ActionRegistry} from a raw {@link ActionEntryInfo} array.
+ *
+ * @param input - Pre-built entries and source labels.
+ * @param input.entries - Action entries already converted to runtime form.
+ * @param input.loadedSources - Labels of the manifest sources that contributed the entries.
+ * @returns A fully-indexed {@link ActionRegistry}.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createActionRegistryFromEntries(input: {
+    readonly entries: readonly ActionEntryInfo[];
+    readonly loadedSources: readonly string[];
+}): ActionRegistry;
+/**
+ * Empty registry for default-no-source scenarios.
+ */
+export declare const EMPTY_ACTION_REGISTRY: ActionRegistry;
+/**
+ * Converts a manifest entry into the {@link ActionEntryInfo} shape the
+ * lookup tool consumes.
+ *
+ * @param entry - The action manifest entry (directive, store, or state).
+ * @returns The runtime-shaped {@link ActionEntryInfo} for the entry.
+ */
+export declare function toActionEntryInfo(entry: ActionEntry): ActionEntryInfo;