@emeryld/rrroutes-export 1.1.1 → 1.1.2

package/README.md

@@ -1,6 +1,120 @@
 # @emeryld/rrroutes-export
 
-Export helpers and CLI for RRRoutes finalized leaves.
+Headless runtime inspection, canonical snapshots, semantic changes, checkpoints,
+storage, and JSON HTTP adapters for RRRoutes. Browser rendering lives in
+`@emeryld/rrroutes-export-ui`.
+
+## Runtime setup
+
+```ts
+import { createRRRoutesExportRuntime } from '@emeryld/rrroutes-export'
+import { createFileSystemInspectionStorage } from '@emeryld/rrroutes-export/storage/filesystem'
+
+export const rrroutesExport = createRRRoutesExportRuntime({
+  endpointClient,
+  allRoutes,
+  allClients: { users: usersClient, projects: projectsClient },
+  sockets: { application: socketClient },
+  server, // optional for client-only and contract-only processes
+  storage: createFileSystemInspectionStorage({ directory: '.rrroutes' }),
+  checkpoints: {
+    scope: process.env.NODE_ENV ?? 'development',
+    retention: {
+      type: 'combined',
+      maximum: 20,
+      maximumAgeMs: 30 * 24 * 60 * 60 * 1000,
+    },
+  },
+  meta: {
+    application: 'example-api',
+    environment: process.env.NODE_ENV,
+    version: process.env.APP_VERSION,
+    commit: process.env.GIT_SHA,
+  },
+})
+```
+
+`METHOD + path` is always the canonical route identity. Optional leaf,
+binding, augment, controller, middleware, and socket IDs improve display and
+diff matching but never replace the route key and are never required.
+
+Snapshots are structural by default. Use `inspect({ includeLive: true })` for
+hosted socket status; live connection IDs, rooms, and listener counts do not
+affect the normal snapshot hash or checkpoint changelog.
+
+## Checkpoints
+
+```ts
+await rrroutesExport.checkpoints.advance({
+  scope: 'production',
+  trigger: {
+    type: 'webhook',
+    externalId: deploymentId,
+    label: `Deployment ${deploymentId}`,
+  },
+})
+```
+
+Advancement is scope-locked and writes the durable change set before replacing
+the active checkpoint. Transition hashes make webhook retries idempotent.
+Checkpoint retention and change-set retention are independent; change sets are
+kept forever by default.
+
+Built-in storage adapters are available at:
+
+- `@emeryld/rrroutes-export/storage/memory`
+- `@emeryld/rrroutes-export/storage/filesystem`
+- `@emeryld/rrroutes-export/storage/sqlite`
+
+The SQLite adapter accepts a database compatible with `node:sqlite`
+`DatabaseSync` or `better-sqlite3`, avoiding a mandatory native dependency.
+
+## Hosted inspector API
+
+```ts
+app.use(
+  '/_rrroutes',
+  rrroutesExport.createExpressRouter({
+    mutations: {
+      enabled: process.env.NODE_ENV !== 'production',
+      authorize: async ({ request, action }) =>
+        authorizeInspector(request, action),
+    },
+  }),
+)
+```
+
+Mutation routes are disabled by default. The handler sets no-store headers,
+limits mutation bodies, supports authorization hooks and idempotency keys, and
+does not expose request data, tokens, query cache contents, environment
+variables, or function source. Mounting is always application-owned; the
+package never exposes the inspector automatically.
+
+Use `createHttpHandler()` for the framework-neutral Web `Request`/`Response`
+adapter. Install `express` only when using the Express adapter.
+
+## CLI
+
+```bash
+rrroutes-export-snapshot --module ./src/inspection-runtime.ts \
+  --export rrroutesExport --out ./rrroutes.snapshot.json
+
+rrroutes-export-changes --module ./src/inspection-runtime.ts \
+  --export rrroutesExport --before ./previous.snapshot.json \
+  --out ./rrroutes.changes.json
+
+rrroutes-checkpoint advance --module ./src/inspection-runtime.ts \
+  --export rrroutesExport --scope production
+
+rrroutes-inspector-serve --module ./src/inspection-runtime.ts \
+  --export rrroutesExport --port 4310
+```
+
+## Legacy finalized-leaf exports
+
+The original finalized-leaf and Git-history entry points remain temporarily as
+thin migration surfaces. They reuse the same schema serializer, source
+extractor, and baked-payload injector used by the canonical implementation.
 
 ## What this package provides
 

package/bin/rrroutes-checkpoint.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCheckpointCli } from '../dist/index.mjs'
+
+runCheckpointCli(process.argv.slice(2))
+  .then((result) => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`))
+  .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })

package/bin/rrroutes-export-changes.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runChangesCli } from '../dist/index.mjs'
+
+runChangesCli(process.argv.slice(2))
+  .then(({ outFile }) => process.stdout.write(`${outFile}\n`))
+  .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })

package/bin/rrroutes-export-snapshot.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runSnapshotCli } from '../dist/index.mjs'
+
+runSnapshotCli(process.argv.slice(2))
+  .then(({ outFile }) => process.stdout.write(`${outFile}\n`))
+  .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })

package/bin/rrroutes-inspector-serve.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runInspectorServeCli } from '../dist/index.mjs'
+
+runInspectorServeCli(process.argv.slice(2))
+  .then(({ port }) => process.stdout.write(`RRRoutes inspector listening on http://localhost:${port}\n`))
+  .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })

package/dist/adapters/express.d.ts

@@ -0,0 +1,6 @@
+import type { Router } from 'express';
+import type { InspectorHttpOptions, InspectorRuntimeLike } from '../http/types';
+export type InspectorExpressOptions = InspectorHttpOptions & {
+    runtime: InspectorRuntimeLike;
+};
+export declare function createExpressRouter(options: InspectorExpressOptions): Router;

package/dist/checkpoint/lock.d.ts

@@ -0,0 +1,4 @@
+export declare class ScopeLock {
+    #private;
+    run<T>(scope: string, action: () => Promise<T>): Promise<T>;
+}

package/dist/checkpoint/retention.d.ts

@@ -0,0 +1,15 @@
+import type { ChangeSetRetention, CheckpointRetention } from './types';
+import type { InspectionStorage } from '../storage/types';
+export declare function applyCheckpointRetention(args: {
+    storage: InspectionStorage;
+    scope: string;
+    activeId: string;
+    retention?: CheckpointRetention;
+    now?: number;
+}): Promise<void>;
+export declare function applyChangeSetRetention(args: {
+    storage: InspectionStorage;
+    scope: string;
+    retention: ChangeSetRetention;
+    now?: number;
+}): Promise<void>;

package/dist/checkpoint/service.d.ts

@@ -0,0 +1,11 @@
+import type { RRRoutesSnapshot } from '../snapshot/types';
+import type { InspectionStorage } from '../storage/types';
+import type { ChangeSetRetention, CheckpointRetention, CheckpointService } from './types';
+export type CreateCheckpointServiceOptions = {
+    inspect: () => Promise<RRRoutesSnapshot>;
+    storage?: InspectionStorage;
+    scope?: string;
+    retention?: CheckpointRetention;
+    changeSetRetention?: ChangeSetRetention;
+};
+export declare function createCheckpointService(options: CreateCheckpointServiceOptions): CheckpointService;

package/dist/checkpoint/types.d.ts

@@ -0,0 +1,65 @@
+import type { CheckpointTrigger, RRRoutesChangeSet } from '../diff/types';
+import type { RRRoutesSnapshot } from '../snapshot/types';
+export interface RRRoutesCheckpoint {
+    id: string;
+    scope: string;
+    createdAt: string;
+    updatedAt: string;
+    snapshotHash: string;
+    snapshot: RRRoutesSnapshot;
+    trigger: CheckpointTrigger;
+    expiresAt?: string;
+}
+export type RRRoutesCheckpointSummary = Omit<RRRoutesCheckpoint, 'snapshot'> & {
+    active: boolean;
+};
+export type RRRoutesChangeSetSummary = Omit<RRRoutesChangeSet, 'changes'>;
+export type CheckpointRetention = {
+    type: 'duration';
+    maximumAgeMs: number;
+} | {
+    type: 'count';
+    maximum: number;
+} | {
+    type: 'combined';
+    maximumAgeMs: number;
+    maximum: number;
+};
+export type ChangeSetRetention = {
+    type: 'forever';
+} | {
+    type: 'duration';
+    maximumAgeMs: number;
+} | {
+    type: 'count';
+    maximum: number;
+};
+export type CheckpointAdvanceInput = {
+    scope?: string;
+    trigger?: CheckpointTrigger;
+};
+export type CheckpointAdvanceResult = {
+    status: 'baseline_created';
+    checkpoint: RRRoutesCheckpoint;
+} | {
+    status: 'no_changes';
+    checkpoint: RRRoutesCheckpoint;
+} | {
+    status: 'idempotent_replay';
+    checkpoint: RRRoutesCheckpoint;
+    changeSet?: RRRoutesChangeSet;
+} | {
+    status: 'advanced';
+    checkpoint: RRRoutesCheckpoint;
+    changeSet: RRRoutesChangeSet;
+};
+export interface CheckpointService {
+    advance(input?: CheckpointAdvanceInput): Promise<CheckpointAdvanceResult>;
+    create(input?: CheckpointAdvanceInput): Promise<RRRoutesCheckpoint>;
+    get(id: string): Promise<RRRoutesCheckpoint | undefined>;
+    getActive(scope?: string): Promise<RRRoutesCheckpoint | undefined>;
+    list(scope?: string): Promise<readonly RRRoutesCheckpointSummary[]>;
+    delete(id: string): Promise<void>;
+    listChangeSets(scope?: string): Promise<readonly RRRoutesChangeSetSummary[]>;
+    getChangeSet(id: string): Promise<RRRoutesChangeSet | undefined>;
+}

package/dist/cli/changes.d.ts

@@ -0,0 +1,4 @@
+export declare function runChangesCli(argv: readonly string[]): Promise<{
+    changeSet: import("..").RRRoutesChangeSet;
+    outFile: string;
+}>;

package/dist/cli/checkpoint.d.ts

@@ -0,0 +1 @@
+export declare function runCheckpointCli(argv: readonly string[]): Promise<import("..").RRRoutesCheckpoint | import("..").CheckpointAdvanceResult>;

package/dist/cli/runtime.d.ts

@@ -0,0 +1,7 @@
+import type { RRRoutesExportRuntime } from '../runtime';
+export declare function parseCliFlags(argv: readonly string[]): Map<string, string>;
+export declare function loadExportRuntime(args: {
+    modulePath: string;
+    exportName?: string;
+}): Promise<RRRoutesExportRuntime>;
+export declare function requiredFlag(flags: Map<string, string>, name: string): string;

package/dist/cli/serve.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from 'node:http';
+import type { Express } from 'express';
+export declare function runInspectorServeCli(argv: readonly string[]): Promise<{
+    app: Express;
+    server: Server;
+    port: number;
+}>;

package/dist/cli/snapshot.d.ts

@@ -0,0 +1,4 @@
+export declare function runSnapshotCli(argv: readonly string[]): Promise<{
+    snapshot: import("..").RRRoutesSnapshot;
+    outFile: string;
+}>;

package/dist/diff/diff-snapshots.d.ts

@@ -0,0 +1,4 @@
+import type { RRRoutesSnapshot } from '../snapshot/types';
+import type { DiffOptions, RRRoutesChangeSet } from './types';
+export declare function diffRRRoutesSnapshots(before: RRRoutesSnapshot, after: RRRoutesSnapshot, options?: DiffOptions): RRRoutesChangeSet;
+export declare const createSnapshotChangeSet: typeof diffRRRoutesSnapshots;

package/dist/diff/types.d.ts

@@ -0,0 +1,58 @@
+import type { RouteKey } from '@emeryld/rrroutes-contract';
+import type { JsonValue } from '../snapshot/types';
+export type RRRoutesChangeLayer = 'contract' | 'client' | 'server' | 'socket';
+export type RRRoutesChangeSeverity = 'breaking' | 'behavioral' | 'non-breaking' | 'informational';
+export type RRRoutesChangeType = 'route_added' | 'route_removed' | 'route_id_changed' | 'schema_changed' | 'cfg_changed' | 'description_changed' | 'files_changed' | 'source_changed' | 'client_resource_added' | 'client_resource_removed' | 'client_binding_added' | 'client_binding_removed' | 'client_binding_target_changed' | 'client_binding_enabled' | 'client_binding_disabled' | 'client_build_options_changed' | 'client_augment_added' | 'client_augment_removed' | 'client_augment_changed' | 'client_augment_reordered' | 'client_socket_connection_added' | 'client_socket_connection_removed' | 'client_socket_connection_changed' | 'server_controller_registered' | 'server_controller_unregistered' | 'server_endpoint_enabled' | 'server_endpoint_disabled' | 'server_controller_changed' | 'server_middleware_added' | 'server_middleware_removed' | 'server_middleware_changed' | 'server_middleware_reordered' | 'server_output_validation_changed' | 'socket_runtime_added' | 'socket_runtime_removed' | 'socket_contract_event_added' | 'socket_contract_event_removed' | 'socket_payload_schema_changed' | 'socket_handler_added' | 'socket_handler_removed' | 'socket_binding_changed' | 'socket_room_strategy_changed' | 'socket_cache_reducer_changed' | 'socket_heartbeat_configuration_changed';
+export interface FieldChange {
+    field: string;
+    before?: JsonValue;
+    after?: JsonValue;
+}
+export interface RRRoutesChange {
+    id: string;
+    layer: RRRoutesChangeLayer;
+    type: RRRoutesChangeType;
+    routeKey?: RouteKey;
+    entityId: string;
+    severity: RRRoutesChangeSeverity;
+    before?: JsonValue;
+    after?: JsonValue;
+    changedFields?: readonly FieldChange[];
+}
+export interface CheckpointTrigger {
+    type: string;
+    id?: string;
+    externalId?: string;
+    label?: string;
+    actor?: string;
+    metadata?: JsonValue;
+}
+export interface SnapshotReference {
+    snapshotHash: string;
+    capturedAt: string;
+    checkpointId?: string;
+}
+export interface RRRoutesChangeSummary {
+    total: number;
+    byLayer: Record<RRRoutesChangeLayer, number>;
+    bySeverity: Record<RRRoutesChangeSeverity, number>;
+    byType: Partial<Record<RRRoutesChangeType, number>>;
+}
+export interface RRRoutesChangeSet {
+    id: string;
+    scope: string;
+    createdAt: string;
+    from: SnapshotReference;
+    to: SnapshotReference;
+    trigger: CheckpointTrigger;
+    summary: RRRoutesChangeSummary;
+    changes: readonly RRRoutesChange[];
+}
+export interface DiffOptions {
+    includeLive?: boolean;
+    scope?: string;
+    trigger?: CheckpointTrigger;
+    createdAt?: string;
+    fromCheckpointId?: string;
+    toCheckpointId?: string;
+}

package/dist/exportFinalizedLeaves.changelog.d.ts

@@ -1,5 +1,6 @@
 import { type ExportFinalizedLeavesOptions, type FinalizedLeavesExport, type WriteFinalizedLeavesExportOptions } from './exportFinalizedLeaves';
 import type { FlatSchemaEntry, FlatSchemaMap } from './flattenSchema';
+import type { RRRoutesChangeSet } from './diff/types';
 declare const CHANGESET_CFG_FIELDS: readonly ["summary", "description", "tags", "deprecated", "stability", "docsGroup", "docsHidden", "feed"];
 declare const SCHEMA_SECTIONS: readonly ["params", "query", "body", "output"];
 type ChangelogSchemaSection = (typeof SCHEMA_SECTIONS)[number];
@@ -112,6 +113,8 @@ export type FinalizedLeavesChangelogExport = {
     byRoute: Record<string, RouteChangeEvent[]>;
     bySourceObject: Record<string, SourceObjectChangeEvent[]>;
     rollups: ChangelogRollups;
+    /** Canonical durable transitions used by checkpoints and direct comparisons. */
+    changeSets?: RRRoutesChangeSet[];
 };
 export type ExportFinalizedLeavesChangelogOptions = {
     modulePath: string;
@@ -160,6 +163,7 @@ declare function loadSnapshotExport(options: {
 declare function diffSnapshots(previous: CommitSnapshot, current: CommitSnapshot): {
     routeEvents: RouteChangeEvent[];
     sourceEvents: SourceObjectChangeEvent[];
+    changeSet: RRRoutesChangeSet;
 };
 export declare function writeFinalizedLeavesChangelogExport(payload: FinalizedLeavesChangelogExport, outFileOrOptions: string | WriteFinalizedLeavesExportOptions): Promise<{
     outFile?: string;

package/dist/files/baked-payload.d.ts

@@ -0,0 +1,21 @@
+import type { RRRoutesChangeSet } from '../diff/types';
+import type { RRRoutesCheckpointSummary } from '../checkpoint/types';
+import type { RRRoutesSnapshot } from '../snapshot/types';
+export declare const RRROUTES_BAKED_PAYLOAD_MARKER = "<!--__RRROUTES_INSPECTOR_BAKED_PAYLOAD__-->";
+export type RRRoutesBakedInspectorPayload = {
+    kind: 'rrroutes-inspector-baked';
+    snapshot: RRRoutesSnapshot;
+    checkpoints: readonly RRRoutesCheckpointSummary[];
+    changeSets: readonly RRRoutesChangeSet[];
+};
+export declare function createBakedInspectorPayload(args: {
+    snapshot: RRRoutesSnapshot;
+    checkpoints?: readonly RRRoutesCheckpointSummary[];
+    changeSets?: readonly RRRoutesChangeSet[];
+}): RRRoutesBakedInspectorPayload;
+export declare function escapeBakedPayload(payload: unknown): string;
+export declare function injectBakedInspectorPayload(html: string, payload: unknown, options?: {
+    marker?: string;
+    globalName?: string;
+    scriptId?: string;
+}): string;

package/dist/files/write.d.ts

@@ -0,0 +1,10 @@
+import type { RRRoutesChangeSet } from '../diff/types';
+import type { RRRoutesSnapshot } from '../snapshot/types';
+export type WriteSnapshotOptions = {
+    outFile: string;
+};
+export type WriteChangeSetOptions = {
+    outFile: string;
+};
+export declare function writeRRRoutesSnapshot(snapshot: RRRoutesSnapshot, options: WriteSnapshotOptions): Promise<void>;
+export declare function writeRRRoutesChangeSet(changeSet: RRRoutesChangeSet, options: WriteChangeSetOptions): Promise<void>;

package/dist/http/handler.d.ts

@@ -0,0 +1,2 @@
+import type { HttpHandler, InspectorHttpOptions, InspectorRuntimeLike } from './types';
+export declare function createInspectorHttpHandler(runtime: InspectorRuntimeLike, options?: InspectorHttpOptions): HttpHandler;

package/dist/http/types.d.ts

@@ -0,0 +1,24 @@
+import type { CheckpointService } from '../checkpoint/types';
+import type { InspectOptions, RRRoutesSnapshot } from '../snapshot/types';
+export type InspectorMutationAction = 'checkpoint.create' | 'checkpoint.advance' | 'checkpoint.delete';
+export type InspectorMutationOptions = false | {
+    enabled: boolean;
+    authorize?: (args: {
+        request: Request;
+        action: InspectorMutationAction;
+    }) => boolean | Promise<boolean>;
+};
+export type InspectorHttpOptions = {
+    mutations?: InspectorMutationOptions;
+    includeLive?: boolean;
+    maxMutationBodyBytes?: number;
+    authorize?: (args: {
+        request: Request;
+        action: 'read';
+    }) => boolean | Promise<boolean>;
+};
+export type InspectorRuntimeLike = {
+    inspect(options?: InspectOptions): Promise<RRRoutesSnapshot>;
+    checkpoints: CheckpointService;
+};
+export type HttpHandler = (request: Request) => Promise<Response>;