@saasicat/nest 0.2.0

package/dist/discovery/index.d.cts

@@ -0,0 +1,299 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, CanActivate, DynamicModule, ForwardReference, LogLevel } from '@nestjs/common';
+import { DiscoveredQuotaPolicy, DiscoveryCodeStatus, CapabilityKind, DiscoverySnapshot } from '@saasicat/types';
+export { DiscoveredCapability, DiscoveredFeature, DiscoveredQuota, DiscoverySnapshot } from '@saasicat/types';
+import { D as DiscoveryAppInfo } from '../discovery.scanner-CUYLKlYT.cjs';
+export { a as DISCOVERY_APP_INFO_TOKEN, b as DISCOVERY_SNAPSHOT_PATH_TOKEN, c as DiscoveryScanner, d as computeSnapshotHash } from '../discovery.scanner-CUYLKlYT.cjs';
+import '@nestjs/core';
+
+/**
+ * Options for `@ImplementsCapability(key, options)`. `key` itself comes as a
+ * separate argument; everything else is optional to keep boilerplate low.
+ */
+interface ImplementsCapabilityOptions {
+    /** Human-readable label (for the discovery UI). */
+    label?: string;
+    /**
+     * Aggregation wrapper: the feature key this capability belongs to.
+     * Bundles are planned exclusively in the SuperAdmin UI and are
+     * **deliberately not** part of the code decorator (SPEC_V2 §3.1).
+     */
+    feature?: string;
+    /**
+     * Code status. Default is `active` (visible in discovery, can be
+     * referenced in plans). `deprecated` recommends a replacement;
+     * `experimental` marks WIP capabilities that the SuperAdmin sees with a
+     * warning in the UI; `internal` does not appear in the UI, but does in the
+     * snapshot hash.
+     */
+    status?: DiscoveryCodeStatus;
+    /**
+     * Implementation kind. Not detected by the scanner itself — the user
+     * declares it explicitly (Endpoint, Service, Job, Event).
+     */
+    kind?: CapabilityKind;
+    /** Code-owner tag (e.g. 'accounting', 'membership'). Audit-relevant. */
+    owner?: string;
+    /** Recommended when `status: 'deprecated'`. */
+    replacementKey?: string;
+    /** Recommended when `status: 'deprecated'`. ISO date. */
+    removalPlannedAt?: string;
+    /** Free-text reason for deprecation/internal. */
+    reason?: string;
+    /**
+     * Feature keys that this capability's feature requires at runtime (#35)
+     * — e.g. `TRAINING_PLANNER` ⟹ `RESOURCE_MANAGEMENT`.
+     * The scanner aggregates the union of all capability requires per feature
+     * (minus its own featureKey); the strict-mode check and the configurator
+     * use it to surface unmet dependencies.
+     */
+    requires?: string[];
+    /**
+     * Old feature keys that this capability's feature replaces (#39).
+     * Hard path of replacement: the declaration lives on the NEW feature, the
+     * old code can be deleted in the same commit. (`replacementKey` remains
+     * the soft path on the still-existing, deprecated old code.)
+     */
+    replaces?: string[];
+}
+/** Options for `@RequiresCapability(...keys)` — currently no options, just the key list. */
+type RequiresCapabilityKeys = readonly string[];
+/**
+ * Options for `@DefinesQuota(options)`. `key` is the QuotaKey that
+ * `@EnforceQuota(...)` checks against at runtime.
+ */
+interface DefinesQuotaOptions {
+    key: string;
+    label: string;
+    /** Unit for the UI (e.g. 'invoices', 'GB', 'requests'). */
+    unit: string;
+    policy: DiscoveredQuotaPolicy;
+    /** Aggregation wrapper: which feature the quota is bound to. */
+    feature?: string;
+    /** Old QuotaKeys that this quota replaces (#39, analogous to Capability `replaces`). */
+    replaces?: string[];
+}
+/** Options for `@EnforceQuota(key, options)`. */
+interface EnforceQuotaOptions {
+    /**
+     * Increment step per call (default 1). Negative values allow a decrement
+     * (e.g. reversal of an invoice).
+     */
+    incrementBy?: number;
+    /**
+     * When the quota is checked:
+     * - `before` — before the handler runs (default; prevents the write)
+     * - `after`  — after successful execution (for counters that need the
+     *              result — e.g. actual storage size)
+     */
+    timing?: 'before' | 'after';
+}
+
+/**
+ * Internal metadata shape under which `@ImplementsCapability` stores its data.
+ * The scanner reads it back out.
+ */
+interface ImplementsCapabilityMetadata extends ImplementsCapabilityOptions {
+    capabilityKey: string;
+}
+/**
+ * Marks a method as the implementation of a technical capability.
+ *
+ * The capability is the smallest checkable unit (e.g. `invoice.create`).
+ * Multiple methods may declare the same capability — the
+ * Discovery scanner deduplicates by `capabilityKey`.
+ *
+ * Optional fields:
+ * - `feature` aggregates capabilities into feature wrappers that the
+ *   SuperAdmin can reference in plans.
+ * - `status` controls visibility/lifecycle (default `active`).
+ * - `kind` declares the implementation kind (default `endpoint`).
+ *
+ * **Bundles are deliberately NOT declared in the decorator** (SPEC_V2 §3.1).
+ * They are created exclusively in the SuperAdmin UI (DB table `bundles`),
+ * by the admin grouping features there.
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', {
+ *   label: 'Rechnung erstellen',
+ *   feature: 'INVOICE_MANAGEMENT',
+ *   kind: 'endpoint',
+ *   owner: 'accounting',
+ * })
+ * createInvoice() { … }
+ * ```
+ */
+declare const ImplementsCapability: (capabilityKey: string, options?: ImplementsCapabilityOptions) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Runtime guard: the tenant must have **all** specified capabilities.
+ * Multiple calls (or multiple keys) are evaluated as a logical AND.
+ *
+ * In contrast to `@RequireFeature(...)` (defined in
+ * `billing/require-feature.decorator.ts`, logical OR), the capability guard
+ * checks at the capability level — finer-grained, because a feature has
+ * multiple capabilities.
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', { … })
+ * @RequiresCapability('invoice.create')
+ * createInvoice() { … }
+ * ```
+ */
+declare const RequiresCapability: (...capabilityKeys: string[]) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Marks a class as a QuotaProvider for a QuotaKey. The
+ * Discovery scanner aggregates from it the list of all quotas defined in
+ * code; the SuperAdmin can reference these as limits in plans/bundles.
+ *
+ * A class may have multiple `@DefinesQuota` decorators (e.g. a
+ * provider that holds counters for multiple QuotaKeys).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * @DefinesQuota({
+ *   key: 'invoicesPerMonth',
+ *   label: 'Rechnungen pro Monat',
+ *   unit: 'invoices',
+ *   policy: 'monthlyReset',
+ *   feature: 'INVOICE_MANAGEMENT',
+ * })
+ * class InvoiceQuotaProvider implements QuotaProvider { … }
+ * ```
+ */
+declare const DefinesQuota: (options: DefinesQuotaOptions) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Internal metadata shape under which `@EnforceQuota` stores its data.
+ */
+interface EnforceQuotaMetadata extends EnforceQuotaOptions {
+    quotaKey: string;
+}
+/**
+ * Runtime enforcement: checks + increments a quota counter per call.
+ * The corresponding `@DefinesQuota` provider must be registered in at least
+ * one class (the strict-mode check verifies this).
+ *
+ * Default `incrementBy: 1`, `timing: 'before'`. On quota overrun the
+ * QuotaGuard throws a `LimitExceededError` (see
+ * `entitlement/limit-exceeded-error.ts`).
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', { … })
+ * @EnforceQuota('invoicesPerMonth', { incrementBy: 1 })
+ * createInvoice() { … }
+ * ```
+ */
+declare const EnforceQuota: (quotaKey: string, options?: EnforceQuotaOptions) => _nestjs_common.CustomDecorator<string>;
+
+interface DiscoveryControllerConfig {
+    /**
+     * Class-level guards for `GET /admin/discovery`. MANDATORY — `forRoot()`
+     * throws at boot otherwise. Pass `[]` explicitly if the endpoint should
+     * deliberately be auth-free (e.g. CI/smoke test).
+     */
+    guards: Array<Type<CanActivate>>;
+}
+interface DiscoveryModuleOptions {
+    /** App identity that is adopted into the snapshot (`app.key`/`app.version`). */
+    app: DiscoveryAppInfo;
+    /**
+     * Controller mount for `GET /admin/discovery`. If omitted, the endpoint
+     * is not registered — consumers can then build it themselves (e.g. with
+     * a different path or additional guards) and inject the scanner via
+     * `DISCOVERY_SNAPSHOT_TOKEN`.
+     */
+    controller?: DiscoveryControllerConfig;
+    /**
+     * Modules whose providers must be visible in the DI scope of this
+     * DynamicModule — typically: `AuthModule`, which exports the `JwtAuthGuard`
+     * from `controller.guards`. Without this entry, NestJS fails with an
+     * `UnknownDependenciesException` for the guard if the AuthModule is not
+     * global.
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * Optional: register the module globally — `DISCOVERY_SNAPSHOT_TOKEN` and
+     * `DiscoveryScanner` are then available without another `imports` entry.
+     * Default: `true`.
+     */
+    isGlobal?: boolean;
+    /**
+     * Optional: path into which the DiscoveryScanner writes the snapshot as
+     * JSON on `OnApplicationBootstrap`. Consumers (CI gates, preflight CLIs)
+     * can read the file with `loadDiscoverySnapshotFromFile(path)` without
+     * booting all app modules themselves. If omitted, nothing is written.
+     */
+    snapshotPath?: string | null;
+}
+declare class DiscoveryModule {
+    static forRoot(options: DiscoveryModuleOptions): DynamicModule;
+}
+
+declare class DiscoverySnapshotNotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * Reads a snapshot JSON file persisted by the DiscoveryScanner and returns
+ * it as a `DiscoverySnapshot`. Throws `DiscoverySnapshotNotFoundError`
+ * when the file is missing — that is a hard boot condition for CI gates
+ * (a Preflight without a current snapshot would be worthless).
+ */
+declare function loadDiscoverySnapshotFromFile(path: string): DiscoverySnapshot;
+
+interface HeadlessScanOptions {
+    /** Log level of the boot context. Default `['error', 'warn', 'log']`. */
+    logger?: LogLevel[] | false;
+    /**
+     * Exit function on errors — default `process.exit(4)` (analogous to
+     * Seed-Gate/Preflight). Injectable in tests.
+     */
+    exit?: (code: number) => never;
+}
+/**
+ * Runs the headless scan and returns the snapshot. On boot/scan
+ * errors the error is logged and the process exits with code 4 —
+ * the staged rollout (non-fatal) is controlled by the consumer's
+ * migrate path (`… || echo WARN`), not by this runner.
+ */
+declare function runHeadlessDiscoveryScan(appModule: Type, options?: HeadlessScanOptions): Promise<DiscoverySnapshot>;
+
+/**
+ * Builds a controller class at boot time with the guards configured by the
+ * consumer. Called by DiscoveryModule.forRoot() when the `controller`
+ * option is set.
+ */
+declare function buildDiscoveryController(guards: Array<Type<CanActivate>>): Type;
+
+/** Method level: marks a capability implementation. */
+declare const IMPLEMENTS_CAPABILITY_KEY = "discovery:implements-capability";
+/** Method/class level: runtime guard, tenant must have the capability. */
+declare const REQUIRES_CAPABILITY_KEY = "discovery:requires-capability";
+/** Class level: marks a class as a QuotaProvider for a QuotaKey. */
+declare const DEFINES_QUOTA_KEY = "discovery:defines-quota";
+/** Method level: runtime enforcement (increment/check of a quota counter). */
+declare const ENFORCE_QUOTA_KEY = "discovery:enforce-quota";
+/**
+ * Provider token for the discovery snapshot — provided by the DiscoveryModule
+ * and consumed via `@Inject(DISCOVERY_SNAPSHOT_TOKEN)`
+ * (e.g. AdminController `/admin/discovery`, CatalogModule auto-sync).
+ *
+ * `Symbol.for` (NOT `Symbol`) is mandatory here: this package is built with tsup/
+ * esbuild, which cannot code-split CJS — each entry point
+ * (`./discovery`, `./catalog`, …) therefore inlines its OWN copy of this
+ * file. A plain `Symbol()` would be a different symbol per copy; a consumer
+ * that imports DiscoveryModule from `./discovery` and CatalogModule from `./catalog`
+ * would get two different tokens → the DI match
+ * fails → the snapshot does not reach the CatalogModule (prod incident
+ * 2026-06-09). `Symbol.for` uses the process-wide registry → identical across
+ * all bundle copies. (#25)
+ */
+declare const DISCOVERY_SNAPSHOT_TOKEN: unique symbol;
+
+export { DEFINES_QUOTA_KEY, DISCOVERY_SNAPSHOT_TOKEN, DefinesQuota, type DefinesQuotaOptions, DiscoveryAppInfo, type DiscoveryControllerConfig, DiscoveryModule, type DiscoveryModuleOptions, DiscoverySnapshotNotFoundError, ENFORCE_QUOTA_KEY, EnforceQuota, type EnforceQuotaMetadata, type EnforceQuotaOptions, type HeadlessScanOptions, IMPLEMENTS_CAPABILITY_KEY, ImplementsCapability, type ImplementsCapabilityMetadata, type ImplementsCapabilityOptions, REQUIRES_CAPABILITY_KEY, RequiresCapability, type RequiresCapabilityKeys, buildDiscoveryController, loadDiscoverySnapshotFromFile, runHeadlessDiscoveryScan };

package/dist/discovery/index.d.ts

@@ -0,0 +1,299 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, CanActivate, DynamicModule, ForwardReference, LogLevel } from '@nestjs/common';
+import { DiscoveredQuotaPolicy, DiscoveryCodeStatus, CapabilityKind, DiscoverySnapshot } from '@saasicat/types';
+export { DiscoveredCapability, DiscoveredFeature, DiscoveredQuota, DiscoverySnapshot } from '@saasicat/types';
+import { D as DiscoveryAppInfo } from '../discovery.scanner-CUYLKlYT.js';
+export { a as DISCOVERY_APP_INFO_TOKEN, b as DISCOVERY_SNAPSHOT_PATH_TOKEN, c as DiscoveryScanner, d as computeSnapshotHash } from '../discovery.scanner-CUYLKlYT.js';
+import '@nestjs/core';
+
+/**
+ * Options for `@ImplementsCapability(key, options)`. `key` itself comes as a
+ * separate argument; everything else is optional to keep boilerplate low.
+ */
+interface ImplementsCapabilityOptions {
+    /** Human-readable label (for the discovery UI). */
+    label?: string;
+    /**
+     * Aggregation wrapper: the feature key this capability belongs to.
+     * Bundles are planned exclusively in the SuperAdmin UI and are
+     * **deliberately not** part of the code decorator (SPEC_V2 §3.1).
+     */
+    feature?: string;
+    /**
+     * Code status. Default is `active` (visible in discovery, can be
+     * referenced in plans). `deprecated` recommends a replacement;
+     * `experimental` marks WIP capabilities that the SuperAdmin sees with a
+     * warning in the UI; `internal` does not appear in the UI, but does in the
+     * snapshot hash.
+     */
+    status?: DiscoveryCodeStatus;
+    /**
+     * Implementation kind. Not detected by the scanner itself — the user
+     * declares it explicitly (Endpoint, Service, Job, Event).
+     */
+    kind?: CapabilityKind;
+    /** Code-owner tag (e.g. 'accounting', 'membership'). Audit-relevant. */
+    owner?: string;
+    /** Recommended when `status: 'deprecated'`. */
+    replacementKey?: string;
+    /** Recommended when `status: 'deprecated'`. ISO date. */
+    removalPlannedAt?: string;
+    /** Free-text reason for deprecation/internal. */
+    reason?: string;
+    /**
+     * Feature keys that this capability's feature requires at runtime (#35)
+     * — e.g. `TRAINING_PLANNER` ⟹ `RESOURCE_MANAGEMENT`.
+     * The scanner aggregates the union of all capability requires per feature
+     * (minus its own featureKey); the strict-mode check and the configurator
+     * use it to surface unmet dependencies.
+     */
+    requires?: string[];
+    /**
+     * Old feature keys that this capability's feature replaces (#39).
+     * Hard path of replacement: the declaration lives on the NEW feature, the
+     * old code can be deleted in the same commit. (`replacementKey` remains
+     * the soft path on the still-existing, deprecated old code.)
+     */
+    replaces?: string[];
+}
+/** Options for `@RequiresCapability(...keys)` — currently no options, just the key list. */
+type RequiresCapabilityKeys = readonly string[];
+/**
+ * Options for `@DefinesQuota(options)`. `key` is the QuotaKey that
+ * `@EnforceQuota(...)` checks against at runtime.
+ */
+interface DefinesQuotaOptions {
+    key: string;
+    label: string;
+    /** Unit for the UI (e.g. 'invoices', 'GB', 'requests'). */
+    unit: string;
+    policy: DiscoveredQuotaPolicy;
+    /** Aggregation wrapper: which feature the quota is bound to. */
+    feature?: string;
+    /** Old QuotaKeys that this quota replaces (#39, analogous to Capability `replaces`). */
+    replaces?: string[];
+}
+/** Options for `@EnforceQuota(key, options)`. */
+interface EnforceQuotaOptions {
+    /**
+     * Increment step per call (default 1). Negative values allow a decrement
+     * (e.g. reversal of an invoice).
+     */
+    incrementBy?: number;
+    /**
+     * When the quota is checked:
+     * - `before` — before the handler runs (default; prevents the write)
+     * - `after`  — after successful execution (for counters that need the
+     *              result — e.g. actual storage size)
+     */
+    timing?: 'before' | 'after';
+}
+
+/**
+ * Internal metadata shape under which `@ImplementsCapability` stores its data.
+ * The scanner reads it back out.
+ */
+interface ImplementsCapabilityMetadata extends ImplementsCapabilityOptions {
+    capabilityKey: string;
+}
+/**
+ * Marks a method as the implementation of a technical capability.
+ *
+ * The capability is the smallest checkable unit (e.g. `invoice.create`).
+ * Multiple methods may declare the same capability — the
+ * Discovery scanner deduplicates by `capabilityKey`.
+ *
+ * Optional fields:
+ * - `feature` aggregates capabilities into feature wrappers that the
+ *   SuperAdmin can reference in plans.
+ * - `status` controls visibility/lifecycle (default `active`).
+ * - `kind` declares the implementation kind (default `endpoint`).
+ *
+ * **Bundles are deliberately NOT declared in the decorator** (SPEC_V2 §3.1).
+ * They are created exclusively in the SuperAdmin UI (DB table `bundles`),
+ * by the admin grouping features there.
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', {
+ *   label: 'Rechnung erstellen',
+ *   feature: 'INVOICE_MANAGEMENT',
+ *   kind: 'endpoint',
+ *   owner: 'accounting',
+ * })
+ * createInvoice() { … }
+ * ```
+ */
+declare const ImplementsCapability: (capabilityKey: string, options?: ImplementsCapabilityOptions) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Runtime guard: the tenant must have **all** specified capabilities.
+ * Multiple calls (or multiple keys) are evaluated as a logical AND.
+ *
+ * In contrast to `@RequireFeature(...)` (defined in
+ * `billing/require-feature.decorator.ts`, logical OR), the capability guard
+ * checks at the capability level — finer-grained, because a feature has
+ * multiple capabilities.
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', { … })
+ * @RequiresCapability('invoice.create')
+ * createInvoice() { … }
+ * ```
+ */
+declare const RequiresCapability: (...capabilityKeys: string[]) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Marks a class as a QuotaProvider for a QuotaKey. The
+ * Discovery scanner aggregates from it the list of all quotas defined in
+ * code; the SuperAdmin can reference these as limits in plans/bundles.
+ *
+ * A class may have multiple `@DefinesQuota` decorators (e.g. a
+ * provider that holds counters for multiple QuotaKeys).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * @DefinesQuota({
+ *   key: 'invoicesPerMonth',
+ *   label: 'Rechnungen pro Monat',
+ *   unit: 'invoices',
+ *   policy: 'monthlyReset',
+ *   feature: 'INVOICE_MANAGEMENT',
+ * })
+ * class InvoiceQuotaProvider implements QuotaProvider { … }
+ * ```
+ */
+declare const DefinesQuota: (options: DefinesQuotaOptions) => _nestjs_common.CustomDecorator<string>;
+/**
+ * Internal metadata shape under which `@EnforceQuota` stores its data.
+ */
+interface EnforceQuotaMetadata extends EnforceQuotaOptions {
+    quotaKey: string;
+}
+/**
+ * Runtime enforcement: checks + increments a quota counter per call.
+ * The corresponding `@DefinesQuota` provider must be registered in at least
+ * one class (the strict-mode check verifies this).
+ *
+ * Default `incrementBy: 1`, `timing: 'before'`. On quota overrun the
+ * QuotaGuard throws a `LimitExceededError` (see
+ * `entitlement/limit-exceeded-error.ts`).
+ *
+ * @example
+ * ```ts
+ * @Post()
+ * @ImplementsCapability('invoice.create', { … })
+ * @EnforceQuota('invoicesPerMonth', { incrementBy: 1 })
+ * createInvoice() { … }
+ * ```
+ */
+declare const EnforceQuota: (quotaKey: string, options?: EnforceQuotaOptions) => _nestjs_common.CustomDecorator<string>;
+
+interface DiscoveryControllerConfig {
+    /**
+     * Class-level guards for `GET /admin/discovery`. MANDATORY — `forRoot()`
+     * throws at boot otherwise. Pass `[]` explicitly if the endpoint should
+     * deliberately be auth-free (e.g. CI/smoke test).
+     */
+    guards: Array<Type<CanActivate>>;
+}
+interface DiscoveryModuleOptions {
+    /** App identity that is adopted into the snapshot (`app.key`/`app.version`). */
+    app: DiscoveryAppInfo;
+    /**
+     * Controller mount for `GET /admin/discovery`. If omitted, the endpoint
+     * is not registered — consumers can then build it themselves (e.g. with
+     * a different path or additional guards) and inject the scanner via
+     * `DISCOVERY_SNAPSHOT_TOKEN`.
+     */
+    controller?: DiscoveryControllerConfig;
+    /**
+     * Modules whose providers must be visible in the DI scope of this
+     * DynamicModule — typically: `AuthModule`, which exports the `JwtAuthGuard`
+     * from `controller.guards`. Without this entry, NestJS fails with an
+     * `UnknownDependenciesException` for the guard if the AuthModule is not
+     * global.
+     */
+    imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+    /**
+     * Optional: register the module globally — `DISCOVERY_SNAPSHOT_TOKEN` and
+     * `DiscoveryScanner` are then available without another `imports` entry.
+     * Default: `true`.
+     */
+    isGlobal?: boolean;
+    /**
+     * Optional: path into which the DiscoveryScanner writes the snapshot as
+     * JSON on `OnApplicationBootstrap`. Consumers (CI gates, preflight CLIs)
+     * can read the file with `loadDiscoverySnapshotFromFile(path)` without
+     * booting all app modules themselves. If omitted, nothing is written.
+     */
+    snapshotPath?: string | null;
+}
+declare class DiscoveryModule {
+    static forRoot(options: DiscoveryModuleOptions): DynamicModule;
+}
+
+declare class DiscoverySnapshotNotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/**
+ * Reads a snapshot JSON file persisted by the DiscoveryScanner and returns
+ * it as a `DiscoverySnapshot`. Throws `DiscoverySnapshotNotFoundError`
+ * when the file is missing — that is a hard boot condition for CI gates
+ * (a Preflight without a current snapshot would be worthless).
+ */
+declare function loadDiscoverySnapshotFromFile(path: string): DiscoverySnapshot;
+
+interface HeadlessScanOptions {
+    /** Log level of the boot context. Default `['error', 'warn', 'log']`. */
+    logger?: LogLevel[] | false;
+    /**
+     * Exit function on errors — default `process.exit(4)` (analogous to
+     * Seed-Gate/Preflight). Injectable in tests.
+     */
+    exit?: (code: number) => never;
+}
+/**
+ * Runs the headless scan and returns the snapshot. On boot/scan
+ * errors the error is logged and the process exits with code 4 —
+ * the staged rollout (non-fatal) is controlled by the consumer's
+ * migrate path (`… || echo WARN`), not by this runner.
+ */
+declare function runHeadlessDiscoveryScan(appModule: Type, options?: HeadlessScanOptions): Promise<DiscoverySnapshot>;
+
+/**
+ * Builds a controller class at boot time with the guards configured by the
+ * consumer. Called by DiscoveryModule.forRoot() when the `controller`
+ * option is set.
+ */
+declare function buildDiscoveryController(guards: Array<Type<CanActivate>>): Type;
+
+/** Method level: marks a capability implementation. */
+declare const IMPLEMENTS_CAPABILITY_KEY = "discovery:implements-capability";
+/** Method/class level: runtime guard, tenant must have the capability. */
+declare const REQUIRES_CAPABILITY_KEY = "discovery:requires-capability";
+/** Class level: marks a class as a QuotaProvider for a QuotaKey. */
+declare const DEFINES_QUOTA_KEY = "discovery:defines-quota";
+/** Method level: runtime enforcement (increment/check of a quota counter). */
+declare const ENFORCE_QUOTA_KEY = "discovery:enforce-quota";
+/**
+ * Provider token for the discovery snapshot — provided by the DiscoveryModule
+ * and consumed via `@Inject(DISCOVERY_SNAPSHOT_TOKEN)`
+ * (e.g. AdminController `/admin/discovery`, CatalogModule auto-sync).
+ *
+ * `Symbol.for` (NOT `Symbol`) is mandatory here: this package is built with tsup/
+ * esbuild, which cannot code-split CJS — each entry point
+ * (`./discovery`, `./catalog`, …) therefore inlines its OWN copy of this
+ * file. A plain `Symbol()` would be a different symbol per copy; a consumer
+ * that imports DiscoveryModule from `./discovery` and CatalogModule from `./catalog`
+ * would get two different tokens → the DI match
+ * fails → the snapshot does not reach the CatalogModule (prod incident
+ * 2026-06-09). `Symbol.for` uses the process-wide registry → identical across
+ * all bundle copies. (#25)
+ */
+declare const DISCOVERY_SNAPSHOT_TOKEN: unique symbol;
+
+export { DEFINES_QUOTA_KEY, DISCOVERY_SNAPSHOT_TOKEN, DefinesQuota, type DefinesQuotaOptions, DiscoveryAppInfo, type DiscoveryControllerConfig, DiscoveryModule, type DiscoveryModuleOptions, DiscoverySnapshotNotFoundError, ENFORCE_QUOTA_KEY, EnforceQuota, type EnforceQuotaMetadata, type EnforceQuotaOptions, type HeadlessScanOptions, IMPLEMENTS_CAPABILITY_KEY, ImplementsCapability, type ImplementsCapabilityMetadata, type ImplementsCapabilityOptions, REQUIRES_CAPABILITY_KEY, RequiresCapability, type RequiresCapabilityKeys, buildDiscoveryController, loadDiscoverySnapshotFromFile, runHeadlessDiscoveryScan };

package/dist/discovery/index.js

@@ -0,0 +1,49 @@
+import {
+  DefinesQuota,
+  EnforceQuota,
+  ImplementsCapability,
+  RequiresCapability,
+  runHeadlessDiscoveryScan
+} from "../chunk-HRU3CP57.js";
+import {
+  DiscoverySnapshotNotFoundError,
+  loadDiscoverySnapshotFromFile
+} from "../chunk-ABB2CRAS.js";
+import {
+  DiscoveryModule,
+  buildDiscoveryController
+} from "../chunk-AJ3EPELS.js";
+import {
+  DISCOVERY_APP_INFO_TOKEN,
+  DISCOVERY_SNAPSHOT_PATH_TOKEN,
+  DiscoveryScanner,
+  computeSnapshotHash
+} from "../chunk-M6CZQYPY.js";
+import {
+  DEFINES_QUOTA_KEY,
+  DISCOVERY_SNAPSHOT_TOKEN,
+  ENFORCE_QUOTA_KEY,
+  IMPLEMENTS_CAPABILITY_KEY,
+  REQUIRES_CAPABILITY_KEY
+} from "../chunk-L4SUWH5B.js";
+import "../chunk-SHUYVCID.js";
+export {
+  DEFINES_QUOTA_KEY,
+  DISCOVERY_APP_INFO_TOKEN,
+  DISCOVERY_SNAPSHOT_PATH_TOKEN,
+  DISCOVERY_SNAPSHOT_TOKEN,
+  DefinesQuota,
+  DiscoveryModule,
+  DiscoveryScanner,
+  DiscoverySnapshotNotFoundError,
+  ENFORCE_QUOTA_KEY,
+  EnforceQuota,
+  IMPLEMENTS_CAPABILITY_KEY,
+  ImplementsCapability,
+  REQUIRES_CAPABILITY_KEY,
+  RequiresCapability,
+  buildDiscoveryController,
+  computeSnapshotHash,
+  loadDiscoverySnapshotFromFile,
+  runHeadlessDiscoveryScan
+};