pi-smart-router 0.1.0

package/config/routing-clusters.yaml.example

@@ -0,0 +1,41 @@
+# Example routing cluster catalog — copy to config/routing-clusters.yaml and customize.
+# Reference prompts are embedded at load time; centroids are the mean embedding per cluster.
+# Reason codes use stable prefixes: cluster_${id} (e.g. cluster_low_stakes_general).
+# See specs/001-build-smart-router/data-model.md and GitHub issue #55.
+
+clusters:
+  - id: low_stakes_general
+    tier_bias: zero-tier
+    reference_prompts:
+      - "what is 2+2"
+      - "define polymorphism in one sentence"
+      - "explain what a closure is"
+    min_similarity: 0.82
+    min_margin: 0.05
+
+  - id: mechanical_edit
+    tier_bias: zero-tier
+    reference_prompts:
+      - "format this file with prettier"
+      - "fix lint errors"
+      - "add semicolons to this file"
+    min_similarity: 0.80
+    min_margin: 0.05
+
+  - id: deep_debug
+    tier_bias: frontier-cloud
+    reference_prompts:
+      - "race condition in async handler"
+      - "memory leak in production service"
+      - "debug intermittent test failure"
+    min_similarity: 0.78
+    min_margin: 0.04
+
+  - id: architecture
+    tier_bias: frontier-cloud
+    reference_prompts:
+      - "design a microservices migration"
+      - "system design for a distributed cache"
+      - "architect an event sourcing layer"
+    min_similarity: 0.78
+    min_margin: 0.04

package/data/contrib/example.json

@@ -0,0 +1,25 @@
+[
+  {
+    "version": 1,
+    "timestamp": "2026-07-07T12:00:00.000Z",
+    "session_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "turn_type": "main_loop",
+    "stage": "hydra_match",
+    "reason_code": "hydra_embedding_match",
+    "selected_model_id": "gpt-4o-mini",
+    "tier": "economical-cloud",
+    "routing_latency_ms": 12,
+    "estimated_cost_usd": 0.001,
+    "estimated_input_tokens": 60,
+    "has_tool_context": false,
+    "compaction_flag": false,
+    "triage_verdict": "ambiguous",
+    "triage_reason_code": "mixed_signals",
+    "triage_cyclomatic_score": 1,
+    "requirement_reasoning": 0.5,
+    "requirement_code_gen": 0.4,
+    "requirement_tool_use": 0.2,
+    "success_label": true,
+    "outcome_signals": ["feedback_good"]
+  }
+]

package/dist/api/explain/router-explain.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Explain endpoint handler — T041.
+ *
+ * Returns routing rationale (tier, stage, reason_code, candidates) without
+ * dispatching upstream inference. Runs the same pipeline as the live path
+ * to guarantee bit-for-bit decision equivalence.
+ *
+ * Contract: specs/001-build-smart-router/contracts/explain-endpoint.md v1.0.0
+ *
+ * Invariants:
+ *   - MUST NOT call upstream LLM providers
+ *   - MUST produce a decision identical to the live pipeline for the same input
+ *   - MUST emit no RoutingTelemetry with upstream cost (routing_latency_ms only)
+ */
+import type { ModelProfile, RoutingDecision } from '../../domain/types/index.js';
+import { RouterPipeline } from '../../domain/pipeline/router-pipeline.js';
+import type { ClusterMatcher } from '../../domain/matching/cluster-matcher.js';
+export interface ExplainValidationError {
+    readonly error: 'validation_failed';
+    readonly details: readonly string[];
+}
+export interface ExplainSuccess {
+    readonly status: 200;
+    readonly body: RoutingDecision;
+}
+export interface ExplainBadRequest {
+    readonly status: 400;
+    readonly body: ExplainValidationError;
+}
+export interface ExplainUnavailable {
+    readonly status: 503;
+    readonly body: RoutingDecision;
+}
+export type ExplainResult = ExplainSuccess | ExplainBadRequest | ExplainUnavailable;
+export interface ExplainHandlerDeps {
+    readonly fleet: readonly ModelProfile[];
+    readonly pipeline: RouterPipeline;
+    readonly clusterMatcher?: ClusterMatcher;
+}
+/**
+ * Create an explain handler bound to a shared pipeline instance.
+ *
+ * Reuses the same RouterPipeline as the live dispatch path so
+ * session pin state and stage ordering are identical.
+ */
+export declare function createExplainHandler(deps: ExplainHandlerDeps): (rawBody: unknown) => Promise<ExplainResult>;
+//# sourceMappingURL=router-explain.d.ts.map

package/dist/api/explain/router-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-explain.d.ts","sourceRoot":"","sources":["../../../src/api/explain/router-explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAA2B,MAAM,6BAA6B,CAAC;AAE1G,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAK/E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAIpF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,IAG7B,SAAS,OAAO,KAAG,OAAO,CAAC,aAAa,CAAC,CA+CxE"}

package/dist/api/explain/router-explain.js

@@ -0,0 +1,101 @@
+/**
+ * Explain endpoint handler — T041.
+ *
+ * Returns routing rationale (tier, stage, reason_code, candidates) without
+ * dispatching upstream inference. Runs the same pipeline as the live path
+ * to guarantee bit-for-bit decision equivalence.
+ *
+ * Contract: specs/001-build-smart-router/contracts/explain-endpoint.md v1.0.0
+ *
+ * Invariants:
+ *   - MUST NOT call upstream LLM providers
+ *   - MUST produce a decision identical to the live pipeline for the same input
+ *   - MUST emit no RoutingTelemetry with upstream cost (routing_latency_ms only)
+ */
+import { RoutingRequestSchema } from '../../domain/types/schemas.js';
+import { safeCloudDefault } from '../../domain/pipeline/safe-default.js';
+import { enrichRoutingDecisionForExplain } from '../../infrastructure/telemetry/routing-telemetry.js';
+// ─── Handler factory ──────────────────────────────────────────────────────────
+/**
+ * Create an explain handler bound to a shared pipeline instance.
+ *
+ * Reuses the same RouterPipeline as the live dispatch path so
+ * session pin state and stage ordering are identical.
+ */
+export function createExplainHandler(deps) {
+    const { fleet, pipeline, clusterMatcher } = deps;
+    return async function explain(rawBody) {
+        const parsed = RoutingRequestSchema.safeParse(rawBody);
+        if (!parsed.success) {
+            return {
+                status: 400,
+                body: {
+                    error: 'validation_failed',
+                    details: parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+                },
+            };
+        }
+        const request = toRoutingRequest(parsed.data);
+        const start = performance.now();
+        try {
+            const decision = await pipeline.route(request);
+            return {
+                status: 200,
+                body: await enrichRoutingDecisionForExplain(request, decision, {
+                    fleet,
+                    ...(clusterMatcher !== undefined ? { clusterMatcher } : {}),
+                }),
+            };
+        }
+        catch {
+            const fallbackModel = safeCloudDefault(fleet);
+            const decision = {
+                request_id: request.request_id,
+                selected_model_id: fallbackModel?.id ?? 'unknown',
+                tier: fallbackModel?.tier ?? 'economical-cloud',
+                stage: 'fallback',
+                reason_code: 'safe_default',
+                routing_latency_ms: performance.now() - start,
+                pin_reason: null,
+            };
+            return {
+                status: 503,
+                body: await enrichRoutingDecisionForExplain(request, decision, {
+                    fleet,
+                    ...(clusterMatcher !== undefined ? { clusterMatcher } : {}),
+                }),
+            };
+        }
+    };
+}
+/**
+ * Map Zod-validated data to the domain RoutingRequest entity, bridging
+ * schema field names (tool_call_id/tool_calls) to entity shape (tool_blocks)
+ * and satisfying exactOptionalPropertyTypes constraints.
+ */
+function toRoutingRequest(data) {
+    // Build with known required fields, then add optional fields only when present
+    // to satisfy exactOptionalPropertyTypes (no explicit undefined values).
+    const result = {
+        request_id: data.request_id,
+        session_id: data.session_id,
+        prompt_text: data.prompt_text,
+    };
+    if (data.messages !== undefined) {
+        result['messages'] = data.messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+            ...(m.tool_calls !== undefined ? { tool_blocks: m.tool_calls } : {}),
+        }));
+    }
+    if (data.turn_type !== undefined)
+        result['turn_type'] = data.turn_type;
+    if (data.compaction_flag !== undefined)
+        result['compaction_flag'] = data.compaction_flag;
+    if (data.force_model_id !== undefined)
+        result['force_model_id'] = data.force_model_id;
+    if (data.estimated_input_tokens !== undefined)
+        result['estimated_input_tokens'] = data.estimated_input_tokens;
+    return result;
+}
+//# sourceMappingURL=router-explain.js.map

package/dist/api/explain/router-explain.js.map

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

package/dist/api/middleware/pi-router-middleware.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pi lifecycle hook integration — T021, T021b, SP-055.
+ *
+ * Registers compaction and model-override hooks on pi extension events.
+ * Lifecycle flags are consumed when building the next routing request
+ * (extension `buildRoutingRequest` or embedder `dispatch.dispatch`).
+ *
+ * Routing and stream delegation live in `.pi/extensions/smart-router/` for
+ * pi users, or in embedder code that calls `GatewayDispatch.dispatch()`.
+ * This module does not register routing or no-op context hooks.
+ *
+ * Contract: specs/001-build-smart-router/contracts/pi-middleware.md v1.0.0
+ */
+export interface PiSessionManager {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+}
+export interface PiExtensionContext {
+    readonly cwd: string;
+    readonly sessionManager: PiSessionManager;
+}
+export interface PiMessage {
+    readonly role: string;
+    readonly content: string;
+    readonly tool_call_id?: string;
+    readonly tool_calls?: readonly unknown[];
+}
+export interface PiContextEvent {
+    readonly messages: readonly PiMessage[];
+}
+export interface PiModelSelectEvent {
+    readonly source: string;
+    readonly model: {
+        readonly provider: string;
+        readonly id: string;
+    };
+}
+/** Legacy embedder event shape; routing is handled in the pi extension stream path. */
+export interface PiProviderRequestEvent {
+    readonly provider: string;
+    readonly model: string;
+    readonly messages?: readonly PiMessage[];
+    [key: string]: unknown;
+}
+export interface PiExtensionHooks {
+    on(event: 'before_provider_request', handler: (event: PiProviderRequestEvent, ctx: PiExtensionContext) => PiProviderRequestEvent | Promise<PiProviderRequestEvent>): void;
+    on(event: 'context', handler: (event: PiContextEvent, ctx: PiExtensionContext) => void): void;
+    on(event: 'session_compact', handler: (event: unknown, ctx: PiExtensionContext) => void): void;
+    on(event: 'session_before_compact', handler: (event: unknown, ctx: PiExtensionContext) => void): void;
+    on(event: 'model_select', handler: (event: PiModelSelectEvent, ctx: PiExtensionContext) => void): void;
+}
+export interface LifecycleFlags {
+    readonly compaction_flag?: boolean;
+    readonly force_model_id?: string;
+}
+/**
+ * Per-session lifecycle flags set by pi compaction and model_select hooks.
+ * Shared across router rebuilds so hook state survives fleet refresh.
+ */
+export declare class LifecycleHookState {
+    private readonly sessions;
+    private getOrCreate;
+    markCompaction(sessionId: string): void;
+    setForceModel(sessionId: string, modelId: string): void;
+    /**
+     * Consume lifecycle flags for the next routing request.
+     * Compaction is one-shot; force_model_id is one-shot per consume.
+     */
+    consume(sessionId: string): LifecycleFlags;
+}
+export interface PiRouterMiddlewareOptions {
+    readonly lifecycleHookState?: LifecycleHookState;
+}
+export interface PiRouterMiddleware {
+    readonly register: (hooks: PiExtensionHooks) => void;
+    readonly lifecycleHookState: LifecycleHookState;
+}
+/**
+ * Create pi lifecycle hook handlers for session compaction and model overrides.
+ *
+ * Library embedders: call `router.register(hooks)` on the returned `RouterHandle`
+ * and route via `router.dispatch.dispatch()`. For pi, use the project extension at
+ * `.pi/extensions/smart-router/` — it owns stream delegation and routing telemetry.
+ */
+export declare function createPiRouterMiddleware(options?: PiRouterMiddlewareOptions): PiRouterMiddleware;
+//# sourceMappingURL=pi-router-middleware.d.ts.map

package/dist/api/middleware/pi-router-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-router-middleware.d.ts","sourceRoot":"","sources":["../../../src/api/middleware/pi-router-middleware.ts"],"names":[],"mappings":"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"}

package/dist/api/middleware/pi-router-middleware.js

@@ -0,0 +1,83 @@
+/**
+ * Pi lifecycle hook integration — T021, T021b, SP-055.
+ *
+ * Registers compaction and model-override hooks on pi extension events.
+ * Lifecycle flags are consumed when building the next routing request
+ * (extension `buildRoutingRequest` or embedder `dispatch.dispatch`).
+ *
+ * Routing and stream delegation live in `.pi/extensions/smart-router/` for
+ * pi users, or in embedder code that calls `GatewayDispatch.dispatch()`.
+ * This module does not register routing or no-op context hooks.
+ *
+ * Contract: specs/001-build-smart-router/contracts/pi-middleware.md v1.0.0
+ */
+/**
+ * Per-session lifecycle flags set by pi compaction and model_select hooks.
+ * Shared across router rebuilds so hook state survives fleet refresh.
+ */
+export class LifecycleHookState {
+    sessions = new Map();
+    getOrCreate(sessionId) {
+        let state = this.sessions.get(sessionId);
+        if (!state) {
+            state = { compactionPending: false };
+            this.sessions.set(sessionId, state);
+        }
+        return state;
+    }
+    markCompaction(sessionId) {
+        this.getOrCreate(sessionId).compactionPending = true;
+    }
+    setForceModel(sessionId, modelId) {
+        const state = this.getOrCreate(sessionId);
+        state.forceModelId = modelId;
+    }
+    /**
+     * Consume lifecycle flags for the next routing request.
+     * Compaction is one-shot; force_model_id is one-shot per consume.
+     */
+    consume(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state) {
+            return {};
+        }
+        const flags = {
+            ...(state.compactionPending ? { compaction_flag: true } : {}),
+            ...(state.forceModelId !== undefined ? { force_model_id: state.forceModelId } : {}),
+        };
+        state.compactionPending = false;
+        delete state.forceModelId;
+        if (!state.compactionPending && state.forceModelId === undefined) {
+            this.sessions.delete(sessionId);
+        }
+        return flags;
+    }
+}
+function resolveHookSessionId(ctx) {
+    return ctx.sessionManager.getSessionId();
+}
+/**
+ * Create pi lifecycle hook handlers for session compaction and model overrides.
+ *
+ * Library embedders: call `router.register(hooks)` on the returned `RouterHandle`
+ * and route via `router.dispatch.dispatch()`. For pi, use the project extension at
+ * `.pi/extensions/smart-router/` — it owns stream delegation and routing telemetry.
+ */
+export function createPiRouterMiddleware(options) {
+    const lifecycleHookState = options?.lifecycleHookState ?? new LifecycleHookState();
+    function register(hooks) {
+        hooks.on('session_compact', (_event, ctx) => {
+            lifecycleHookState.markCompaction(resolveHookSessionId(ctx));
+        });
+        hooks.on('session_before_compact', (_event, ctx) => {
+            lifecycleHookState.markCompaction(resolveHookSessionId(ctx));
+        });
+        hooks.on('model_select', (event, ctx) => {
+            if (event.source === 'set') {
+                lifecycleHookState.setForceModel(resolveHookSessionId(ctx), event.model.id);
+            }
+        });
+    }
+    return { register, lifecycleHookState };
+}
+//# sourceMappingURL=pi-router-middleware.js.map

package/dist/api/middleware/pi-router-middleware.js.map

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

package/dist/cli/smart-router-cli.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Smart Router CLI subcommands — library-facing command handlers.
+ *
+ * Extension wiring lives in `.pi/extensions/smart-router/commands.ts`;
+ * this module holds reusable subcommand logic for dogfooding and tests.
+ */
+import { SessionPinner } from '../domain/pinning/session-pinner.js';
+import type { RoutingDatasetRecord, RoutingOutcomeRecord } from '../domain/types/index.js';
+import type { StorePort } from '../domain/types/store-port.js';
+export declare const UNPIN_SUBCOMMAND: "unpin";
+export declare const EXPORT_TELEMETRY_CONTRIB_COMMAND: "export telemetry-contrib";
+export declare const TELEMETRY_CONTRIB_VERSION: 1;
+export declare const TELEMETRY_CONTRIB_SCHEMA_PATH = "specs/001-build-smart-router/contracts/telemetry-contrib.schema.json";
+export declare const DEFAULT_TELEMETRY_CONTRIB_EXPORT_DIR = ".pi-smart-router/exports";
+export declare const DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT = 10000;
+/** Keys stripped from contrib export (install-local identifiers and prompt-adjacent fields). */
+export declare const TELEMETRY_CONTRIB_STRIP_KEYS: readonly ["request_id", "session_id", "prompt_text", "messages", "prompt", "prompt_fingerprint", "pepper", "install_pepper", "dataset_pepper", "dataset_key", "pepper_key", "install_key", "candidates_json", "context_fit_rejected_json"];
+/** Mirrors SP-116 `CALIBRATION_CONTRIB_REJECT_KEYS` for ingest-safe export. */
+export declare const TELEMETRY_CONTRIB_REJECT_KEYS: readonly ["session_id", "prompt_text", "messages", "prompt", "prompt_fingerprint"];
+/** Mirrors SP-116 tainted key pattern for ingest-safe export. */
+export declare const TELEMETRY_CONTRIB_TAINTED_KEY_PATTERN: RegExp;
+export declare class TelemetryContribValidationError extends Error {
+    readonly name = "TelemetryContribValidationError";
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Fail closed when a contrib row contains forbidden or tainted keys (SP-116 parity). */
+export declare function assertTelemetryContribRecordSafe(record: unknown, context?: string): asserts record is Record<string, unknown>;
+/** Strip install-local pepper fields from a validated contrib row (SP-116 parity). */
+export declare function sanitizeTelemetryContribRecord(record: Record<string, unknown>): Record<string, unknown>;
+export type UnpinOutcome = 'cleared' | 'noop' | 'unavailable';
+export interface UnpinCommandResult {
+    readonly outcome: UnpinOutcome;
+    readonly message: string;
+    readonly level: 'info' | 'error';
+    readonly previousModelId?: string;
+}
+export interface UnpinCommandContext {
+    readonly sessionId: string;
+    readonly sessionPinner: SessionPinner | undefined;
+}
+export interface ExportTelemetryContribOptions {
+    readonly limit?: number;
+    readonly cwd?: string;
+    readonly writeFile?: boolean;
+}
+export interface ExportTelemetryContribResult {
+    readonly path: string | null;
+    readonly recordCount: number;
+    readonly json: string;
+}
+export interface TelemetryContribExportContext {
+    readonly store: StorePort;
+    readonly cwd: string;
+    readonly limit: number;
+}
+/** Returns true when args invoke `/smart-router unpin`. */
+export declare function isUnpinInvocation(args: string): boolean;
+/** Returns true when args invoke `export telemetry-contrib`. */
+export declare function isExportTelemetryContribInvocation(args: string): boolean;
+export declare function parseExportTelemetryContribArgs(args: string): {
+    readonly limit: number;
+};
+/**
+ * Clear the current session pin via SessionPinner.breakPin().
+ * Does not modify SessionPinner break rules — operator-initiated unpin only.
+ */
+export declare function executeUnpinCommand(ctx: UnpinCommandContext): UnpinCommandResult;
+export declare function hashSessionIdForContribExport(sessionId: string): string;
+/** Map a dataset row plus linked outcomes to a privacy-safe telemetry contrib record. */
+export declare function toTelemetryContribRecord(record: RoutingDatasetRecord, outcomes?: readonly RoutingOutcomeRecord[]): Record<string, unknown>;
+export declare function formatTelemetryContribJson(records: readonly Record<string, unknown>[]): string;
+export declare function formatTelemetryContribJsonl(records: readonly Record<string, unknown>[]): string;
+export declare function formatTelemetryContribExportTimestamp(date?: Date): string;
+export declare function getTelemetryContribExportPath(cwd: string, timestamp: string): string;
+/** Defense-in-depth validation using SP-116 contrib safety checks. */
+export declare function validateTelemetryContribRecord(record: unknown, context?: string): Record<string, unknown>;
+export declare function buildTelemetryContribRecords(datasetRecords: readonly RoutingDatasetRecord[], outcomeRecords?: readonly RoutingOutcomeRecord[]): Record<string, unknown>[];
+export declare function exportTelemetryContrib(ctx: TelemetryContribExportContext, options?: Pick<ExportTelemetryContribOptions, 'writeFile'>): Promise<ExportTelemetryContribResult>;
+/** Join dataset export shape with outcome labels, then strip to contrib-safe fields. */
+export declare function datasetExportRowToTelemetryContrib(exportRecord: Record<string, unknown>, outcomes: readonly RoutingOutcomeRecord[]): Record<string, unknown>;
+export declare const smartRouterCliSubcommands: {
+    readonly unpin: typeof executeUnpinCommand;
+    readonly exportTelemetryContrib: typeof exportTelemetryContrib;
+};
+//# sourceMappingURL=smart-router-cli.d.ts.map

package/dist/cli/smart-router-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-router-cli.d.ts","sourceRoot":"","sources":["../../src/cli/smart-router-cli.ts"],"names":[],"mappings":"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"}