Navigate

API reference

@pyric/cli/repro

13 published symbols from @pyric/cli

Generated from the TypeScript declarations shipped at this import path.

Interfaces

ReplayDivergence

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.

Properties

PropertyTypeDescription
actualunknown-
entrynumberIndex of the recorded entry in entries.
expectedunknown-
kind"result" | "event"-
operationReplayOperationThe operation or listener the frame belongs to.
reason"differs" | "missing"-
sessionstring-

ReplayOperation

The recorded operation a divergent frame answers.

Properties

PropertyType
instance?string
method?string
path?string
subId?string

ReplayPlaneDifference

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.

Properties

PropertyType
entrynumber
kind"result" | "event"
nodeunknown
operationReplayOperation
sessionstring
workerunknown

ReplayPlaneReport

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.

Properties

PropertyTypeDescription
checkednumberRecorded results and events compared.
divergencesReplayDivergence[]At most MAX_REPORTED divergences, in recorded order.
firstDivergenceReplayDivergence-
okboolean-
planeReplayPlaneName-

ReplayReproOptions

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.

Properties

PropertyTypeDescription
frameTimeoutMs?numberHow long to wait for one recorded result or event, in milliseconds.
planes?ReplayPlaneName[]Planes to replay on. Defaults to both.

ReproBase

Everything the host held when the recorded log starts.

Properties

PropertyTypeDescription
appOptionsRecord<string, unknown>The Firebase options the first app port sent, when one had.
atnumberWhen the starting state was read, in milliseconds since the epoch.
checkpointCheckpointFirestore, the default RTDB instance, Storage, Auth, rules and clock.
databaseInstancesRecord<string, unknown>Each named RTDB instance’s tree; the default instance is in the checkpoint.
defaultInstancestringThe instance getDatabase(app) selects.
messaging?booleanWhether the host served Messaging operations. Files written before this was recorded leave it out, and replay keeps Messaging off for them.
permissivebooleanWhether instances without rules allow every request (--permissive).
rules{ database: ReproDatabaseRules; firestore: string; storage: string; }-
rules.databaseReproDatabaseRulesKeyed by instance name; defaultInstance names the default one.
rules.firestorestring-
rules.storagestring-
sessionsRecord<string, ReproPortSession>Ports signed in when the log starts, keyed by client session id.
subscriptionsRecord<string, InboundMessage[]>Listener registrations still open when the log starts, by client session id.

ReproFile

Properties

PropertyTypeDescription
baseReproBase-
createdAtstring-
entriesReproEntry[]-
recordedBystringThe @pyric/cli version that recorded it.
schema"pyric.repro.v1"-
truncatedbooleanTrue when older entries were dropped to keep the log bounded.

ReproReplayReport

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.

Properties

PropertyTypeDescription
okboolean-
planeDifferencesReplayPlaneDifference[]Frames where the planes produced different results. Empty with one plane.
planesPartial<Record<ReplayPlaneName, ReplayPlaneReport>>-
warningsstring[]Recorded changes replay cannot reproduce, such as a command that wrote state.

Type Aliases

ReplayPlaneName

type ReplayPlaneName = "node" | "worker";

@pyric/cli/repro: replay a repro file that pyric serve repro capture wrote, so a bug found in a real project becomes a regression test.

import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';

const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));

The Node plane needs Node 22.15 or later, as the Node host does.


ReproEntry

type ReproEntry =
  | {
  at: number;
  frame: InboundMessage;
  kind: "in";
  session: string;
}
  | {
  at: number;
  frame: OutboundMessage;
  kind: "out";
  session: string;
}
  | {
  at: number;
  event: "disconnect" | "interrupted";
  kind: "client";
  session: string;
}
  | {
  at: number;
  dataB64: string;
  kind: "upload";
  offset: number;
  partIndex: number;
  uploadId: string;
}
  | {
  at: number;
  instance?: string;
  kind: "rules";
  service: "firestore" | "database" | "storage";
  source: unknown;
}
  | {
  at: number;
  kind: "external";
  name: string;
  source: "command";
};

One record in the operation log.

Type Declaration

{
  at: number;
  frame: InboundMessage;
  kind: "in";
  session: string;
}
at
at: number;
frame
frame: InboundMessage;
kind
kind: "in";
session
session: string;

A frame a port sent: an operation, a listener registration, an unsubscribe.

{
  at: number;
  frame: OutboundMessage;
  kind: "out";
  session: string;
}
at
at: number;
frame
frame: OutboundMessage;
kind
kind: "out";
session
session: string;

A frame the host sent a port: an operation result or a listener event.

{
  at: number;
  event: "disconnect" | "interrupted";
  kind: "client";
  session: string;
}
at
at: number;
event
event: "disconnect" | "interrupted";
kind
kind: "client";
session
session: string;

A transport disconnect or interruption for a client session.

{
  at: number;
  dataB64: string;
  kind: "upload";
  offset: number;
  partIndex: number;
  uploadId: string;
}
at
at: number;
dataB64
dataB64: string;
kind
kind: "upload";
offset
offset: number;
partIndex
partIndex: number;
uploadId
uploadId: string;

Staged bytes written to a pending Storage upload over the HTTP byte route.

{
  at: number;
  instance?: string;
  kind: "rules";
  service: "firestore" | "database" | "storage";
  source: unknown;
}
at
at: number;
instance?
optional instance: string;
kind
kind: "rules";
service
service: "firestore" | "database" | "storage";
source
source: unknown;

A rules deploy from the project’s rules files.

{
  at: number;
  kind: "external";
  name: string;
  source: "command";
}
at
at: number;
kind
kind: "external";
name
name: string;
source
source: "command";

A command or MCP method call that changed state outside any port. Replay cannot run it.

Variables

REPRO_SCHEMA

const REPRO_SCHEMA: "pyric.repro.v1";

Functions

parseRepro()

function parseRepro(value: unknown): ReproFile;

Read a repro file’s JSON value, refusing one this version cannot replay.

Parameters

ParameterType
valueunknown

Returns

ReproFile


replayRepro()

function replayRepro(repro: unknown, options?: ReplayReproOptions): Promise<ReproReplayReport>;

Replay a repro file on a fresh Node host and a fresh worker host, and report the first divergence from the recording on each and every difference between them. Accepts a parsed file or its JSON value.

Parameters

ParameterType
reprounknown
options?ReplayReproOptions

Returns

Promise<ReproReplayReport>