@oimdb/cli 0.0.0-stage → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,168 @@
+import { WebSocket } from 'ws';
+
+type TOIMDevBridgeOptions = {
+    wsPort: number;
+    host: string;
+    allowedOrigins: ReadonlySet<string>;
+    /** Opens every line this bridge writes to stderr. */
+    logPrefix: string;
+    /** The command the operator would re-run with a different port. */
+    portInUseHint: string;
+    requestTimeoutMessage: string;
+};
+
+type TOIMDevConnectedBrowser = {
+    ws: WebSocket;
+    url: string;
+    title: string;
+};
+
+declare class OIMDevBridge {
+    private readonly bridgeOptions;
+    private readonly messageReader;
+    private readonly pending;
+    private webSocketServer;
+    private devConnectedBrowser;
+    constructor(bridgeOptions: TOIMDevBridgeOptions);
+    get connectedBrowser(): TOIMDevConnectedBrowser | null;
+    /**
+     * May a page use this bridge?
+     *
+     * From this machine, or named by whoever started the server. An ABSENT
+     * origin is a non-browser client — a CLI, a test — and is allowed; the
+     * literal `'null'` is not, because a sandboxed iframe on any site can send
+     * exactly that.
+     */
+    isOriginAllowed(origin: string | undefined): boolean;
+    request(action: string): Promise<unknown>;
+    start(): void;
+    private readFrame;
+    /**
+     * Newest tab wins — a reload is the ordinary reason for a second `hello` —
+     * but the tab it displaces is CLOSED and the swap is printed. Overwriting the
+     * field in place leaves the displaced socket open for ever and lets a second
+     * connection take the bridge over in silence.
+     */
+    private adoptBrowser;
+    private write;
+}
+
+type TOIMDevUIServerOptions = {
+    wsPort?: number;
+    uiPort?: number;
+    uiDir: string;
+    open?: boolean;
+    /**
+     * The interface both ports bind to. LOOPBACK BY DEFAULT: a tool that hands
+     * out the application's entire data model has no business being reachable
+     * from the café Wi-Fi, and `listen` without a host binds every interface.
+     *
+     * Set it — `'0.0.0.0'` — when the browser genuinely runs somewhere else: a
+     * container, a VM, a phone. That is an opt-in to everyone who can route
+     * there reading the model.
+     */
+    host?: string;
+    /**
+     * Page origins allowed onto the bridge and allowed to read `/api/inspect`,
+     * on top of the loopback origins allowed by default.
+     *
+     * Exact origins (`'http://app.test:3000'`). Never `'*'`: with that on every
+     * response, any page in any tab the developer has open can read every entity
+     * of every registered collection.
+     */
+    allowedOrigins?: readonly string[];
+};
+
+declare class OIMDevUIServer {
+    private readonly uiPort;
+    private readonly shouldOpen;
+    private readonly host;
+    private readonly allowedOrigins;
+    private readonly devUIAssetCatalog;
+    private readonly bridge;
+    constructor(options: TOIMDevUIServerOptions);
+    /**
+     * While bound to loopback, answer only what was addressed to a loopback
+     * name.
+     *
+     * Without this, a page on any site can point a hostname it controls at
+     * 127.0.0.1 and become same-origin with this server. The `Host` header is
+     * the part of that a browser cannot forge. Binding elsewhere is an explicit
+     * decision, so the check stands down there.
+     */
+    private isRequestAddressedHere;
+    private requestBrowser;
+    private setupHTTP;
+    private openURL;
+    start(): void;
+}
+
+interface IOIMDevStateSource {
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+}
+
+declare class OIMDevStateReader {
+    private readonly devStateSource;
+    constructor(devStateSource: IOIMDevStateSource);
+    readInspectText(): Promise<string>;
+    readDumpText(): Promise<string>;
+    readCollectionText(name: string): Promise<string>;
+    readComputedText(name: string): Promise<string>;
+    private namesOf;
+}
+
+interface IOIMDevRegistry {
+    inspect(): unknown;
+    dumpString(): string;
+}
+
+declare class OIMDevRegistryStateSource implements IOIMDevStateSource {
+    private readonly devRegistry;
+    constructor(devRegistry: IOIMDevRegistry);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+}
+
+declare class OIMDevModuleStateSource implements IOIMDevStateSource {
+    private readonly modelModulePath;
+    private devRegistry;
+    constructor(modelModulePath: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    loadDevRegistry(): Promise<IOIMDevRegistry>;
+    private importDevRegistry;
+}
+
+declare class OIMDevBridgeStateSource implements IOIMDevStateSource {
+    private readonly devBridge;
+    private readonly wsPort;
+    constructor(devBridge: OIMDevBridge, wsPort: number);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private requestBrowser;
+}
+
+declare class OIMDevHttpStateSource implements IOIMDevStateSource {
+    private readonly serverUrl;
+    constructor(serverUrl: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private readConnected;
+}
+
+declare class OIMDevCdpStateSource implements IOIMDevStateSource {
+    private readonly cdpUrl;
+    constructor(cdpUrl: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private evaluate;
+    private evaluateOnTab;
+}
+
+type TOIMDevInspectSnapshot = {
+    collections: Record<string, unknown>;
+    computeds: Record<string, unknown>;
+};
+
+export { type IOIMDevRegistry, type IOIMDevStateSource, OIMDevBridge, OIMDevBridgeStateSource, OIMDevCdpStateSource, OIMDevHttpStateSource, OIMDevModuleStateSource, OIMDevRegistryStateSource, OIMDevStateReader, OIMDevUIServer, type TOIMDevBridgeOptions, type TOIMDevInspectSnapshot, type TOIMDevUIServerOptions };

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { WebSocket } from 'ws';
+
+type TOIMDevBridgeOptions = {
+    wsPort: number;
+    host: string;
+    allowedOrigins: ReadonlySet<string>;
+    /** Opens every line this bridge writes to stderr. */
+    logPrefix: string;
+    /** The command the operator would re-run with a different port. */
+    portInUseHint: string;
+    requestTimeoutMessage: string;
+};
+
+type TOIMDevConnectedBrowser = {
+    ws: WebSocket;
+    url: string;
+    title: string;
+};
+
+declare class OIMDevBridge {
+    private readonly bridgeOptions;
+    private readonly messageReader;
+    private readonly pending;
+    private webSocketServer;
+    private devConnectedBrowser;
+    constructor(bridgeOptions: TOIMDevBridgeOptions);
+    get connectedBrowser(): TOIMDevConnectedBrowser | null;
+    /**
+     * May a page use this bridge?
+     *
+     * From this machine, or named by whoever started the server. An ABSENT
+     * origin is a non-browser client — a CLI, a test — and is allowed; the
+     * literal `'null'` is not, because a sandboxed iframe on any site can send
+     * exactly that.
+     */
+    isOriginAllowed(origin: string | undefined): boolean;
+    request(action: string): Promise<unknown>;
+    start(): void;
+    private readFrame;
+    /**
+     * Newest tab wins — a reload is the ordinary reason for a second `hello` —
+     * but the tab it displaces is CLOSED and the swap is printed. Overwriting the
+     * field in place leaves the displaced socket open for ever and lets a second
+     * connection take the bridge over in silence.
+     */
+    private adoptBrowser;
+    private write;
+}
+
+type TOIMDevUIServerOptions = {
+    wsPort?: number;
+    uiPort?: number;
+    uiDir: string;
+    open?: boolean;
+    /**
+     * The interface both ports bind to. LOOPBACK BY DEFAULT: a tool that hands
+     * out the application's entire data model has no business being reachable
+     * from the café Wi-Fi, and `listen` without a host binds every interface.
+     *
+     * Set it — `'0.0.0.0'` — when the browser genuinely runs somewhere else: a
+     * container, a VM, a phone. That is an opt-in to everyone who can route
+     * there reading the model.
+     */
+    host?: string;
+    /**
+     * Page origins allowed onto the bridge and allowed to read `/api/inspect`,
+     * on top of the loopback origins allowed by default.
+     *
+     * Exact origins (`'http://app.test:3000'`). Never `'*'`: with that on every
+     * response, any page in any tab the developer has open can read every entity
+     * of every registered collection.
+     */
+    allowedOrigins?: readonly string[];
+};
+
+declare class OIMDevUIServer {
+    private readonly uiPort;
+    private readonly shouldOpen;
+    private readonly host;
+    private readonly allowedOrigins;
+    private readonly devUIAssetCatalog;
+    private readonly bridge;
+    constructor(options: TOIMDevUIServerOptions);
+    /**
+     * While bound to loopback, answer only what was addressed to a loopback
+     * name.
+     *
+     * Without this, a page on any site can point a hostname it controls at
+     * 127.0.0.1 and become same-origin with this server. The `Host` header is
+     * the part of that a browser cannot forge. Binding elsewhere is an explicit
+     * decision, so the check stands down there.
+     */
+    private isRequestAddressedHere;
+    private requestBrowser;
+    private setupHTTP;
+    private openURL;
+    start(): void;
+}
+
+interface IOIMDevStateSource {
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+}
+
+declare class OIMDevStateReader {
+    private readonly devStateSource;
+    constructor(devStateSource: IOIMDevStateSource);
+    readInspectText(): Promise<string>;
+    readDumpText(): Promise<string>;
+    readCollectionText(name: string): Promise<string>;
+    readComputedText(name: string): Promise<string>;
+    private namesOf;
+}
+
+interface IOIMDevRegistry {
+    inspect(): unknown;
+    dumpString(): string;
+}
+
+declare class OIMDevRegistryStateSource implements IOIMDevStateSource {
+    private readonly devRegistry;
+    constructor(devRegistry: IOIMDevRegistry);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+}
+
+declare class OIMDevModuleStateSource implements IOIMDevStateSource {
+    private readonly modelModulePath;
+    private devRegistry;
+    constructor(modelModulePath: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    loadDevRegistry(): Promise<IOIMDevRegistry>;
+    private importDevRegistry;
+}
+
+declare class OIMDevBridgeStateSource implements IOIMDevStateSource {
+    private readonly devBridge;
+    private readonly wsPort;
+    constructor(devBridge: OIMDevBridge, wsPort: number);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private requestBrowser;
+}
+
+declare class OIMDevHttpStateSource implements IOIMDevStateSource {
+    private readonly serverUrl;
+    constructor(serverUrl: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private readConnected;
+}
+
+declare class OIMDevCdpStateSource implements IOIMDevStateSource {
+    private readonly cdpUrl;
+    constructor(cdpUrl: string);
+    readInspect(): Promise<unknown>;
+    readDump(): Promise<string>;
+    private evaluate;
+    private evaluateOnTab;
+}
+
+type TOIMDevInspectSnapshot = {
+    collections: Record<string, unknown>;
+    computeds: Record<string, unknown>;
+};
+
+export { type IOIMDevRegistry, type IOIMDevStateSource, OIMDevBridge, OIMDevBridgeStateSource, OIMDevCdpStateSource, OIMDevHttpStateSource, OIMDevModuleStateSource, OIMDevRegistryStateSource, OIMDevStateReader, OIMDevUIServer, type TOIMDevBridgeOptions, type TOIMDevInspectSnapshot, type TOIMDevUIServerOptions };