@cogcoin/client 0.5.0

package/dist/bitcoind/progress/assets.js

@@ -0,0 +1,90 @@
+import { readFileSync } from "node:fs";
+import { ART_HEIGHT, ART_WIDTH, FOLLOW_CAR_HEIGHT, FOLLOW_CAR_WIDTH, TRAIN_SPRITE_HEIGHT, TRAIN_SPRITE_WIDTH, } from "./constants.js";
+const ART_TEMPLATE_CACHE = {};
+const SPRITE_CACHE = {};
+let FOLLOW_CAR_TEMPLATE_CACHE = null;
+function normalizeArtTemplate(raw, name) {
+    const lines = raw.replaceAll("\r\n", "\n").split("\n");
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    if (lines.length !== ART_HEIGHT) {
+        throw new Error(`art_template_height_invalid_${name}_${lines.length}`);
+    }
+    for (const line of lines) {
+        if (line.length !== ART_WIDTH) {
+            throw new Error(`art_template_width_invalid_${name}_${line.length}`);
+        }
+    }
+    return lines;
+}
+export function loadArtTemplate(name) {
+    const cached = ART_TEMPLATE_CACHE[name];
+    if (cached !== undefined) {
+        return cached;
+    }
+    const lines = normalizeArtTemplate(readFileSync(new URL(`../../art/${name}.txt`, import.meta.url), "utf8"), name);
+    ART_TEMPLATE_CACHE[name] = lines;
+    return lines;
+}
+function normalizeSprite(raw, name) {
+    const lines = raw.replaceAll("\r\n", "\n").split("\n");
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    if (lines.length !== TRAIN_SPRITE_HEIGHT) {
+        throw new Error(`sprite_height_invalid_${name}_${lines.length}`);
+    }
+    return lines.map((line) => {
+        if (line.length > TRAIN_SPRITE_WIDTH) {
+            throw new Error(`sprite_width_invalid_${name}_${line.length}`);
+        }
+        return line.padEnd(TRAIN_SPRITE_WIDTH, " ");
+    });
+}
+export function loadSprite(name) {
+    const cached = SPRITE_CACHE[name];
+    if (cached !== undefined) {
+        return cached;
+    }
+    const lines = normalizeSprite(readFileSync(new URL(`../../art/${name}.txt`, import.meta.url), "utf8"), name);
+    SPRITE_CACHE[name] = lines;
+    return lines;
+}
+function normalizeFollowCarTemplate(raw) {
+    const lines = raw.replaceAll("\r\n", "\n").split("\n");
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    if (lines.length !== FOLLOW_CAR_HEIGHT) {
+        throw new Error(`sprite_height_invalid_train-car_${lines.length}`);
+    }
+    return lines.map((line) => {
+        if (line.length > FOLLOW_CAR_WIDTH) {
+            throw new Error(`sprite_width_invalid_train-car_${line.length}`);
+        }
+        return line.padEnd(FOLLOW_CAR_WIDTH, " ");
+    });
+}
+export function loadFollowCarTemplate() {
+    if (FOLLOW_CAR_TEMPLATE_CACHE !== null) {
+        return FOLLOW_CAR_TEMPLATE_CACHE;
+    }
+    FOLLOW_CAR_TEMPLATE_CACHE = normalizeFollowCarTemplate(readFileSync(new URL("../../art/train-car.txt", import.meta.url), "utf8"));
+    return FOLLOW_CAR_TEMPLATE_CACHE;
+}
+export function loadBannerArtForTesting() {
+    return [...loadArtTemplate("banner")];
+}
+export function loadScrollArtForTesting() {
+    return [...loadArtTemplate("scroll")];
+}
+export function loadTrainSmokeArtForTesting() {
+    return [...loadSprite("train-smoke")];
+}
+export function loadTrainArtForTesting() {
+    return [...loadSprite("train")];
+}
+export function loadTrainCarArtForTesting() {
+    return [...loadFollowCarTemplate()];
+}

package/dist/bitcoind/progress/constants.d.ts

@@ -0,0 +1,48 @@
+export declare const PROGRESS_TICK_MS = 250;
+export declare const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
+export declare const ART_WIDTH = 80;
+export declare const ART_HEIGHT = 13;
+export declare const INTRO_ENTRY_MS = 5000;
+export declare const INTRO_PAUSE_MS = 5000;
+export declare const INTRO_EXIT_MS = 5000;
+export declare const INTRO_TOTAL_MS: number;
+export declare const STATUS_ELLIPSIS_WIDTH = 3;
+export declare const STATUS_ELLIPSIS_TICK_MS = 500;
+export declare const NEUTRAL_MESSAGE_TITLE = "\u26ED  C O G C O I N  \u26ED";
+export declare const MESSAGE_FIELD_ROW = 1;
+export declare const STATUS_FIELD_ROW = 12;
+export declare const FIELD_LEFT = 8;
+export declare const FIELD_WIDTH = 64;
+export declare const SCROLL_WINDOW_LEFT = 7;
+export declare const SCROLL_WINDOW_TOP = 3;
+export declare const SCROLL_WINDOW_WIDTH = 65;
+export declare const SCROLL_WINDOW_HEIGHT = 8;
+export declare const TRAIN_CLIP_MIN_COLUMN = -1;
+export declare const TRAIN_CLIP_MAX_COLUMN = 65;
+export declare const MAX_QUOTE_LINES = 6;
+export declare const TRAIN_SPRITE_WIDTH = 64;
+export declare const TRAIN_SPRITE_HEIGHT = 6;
+export declare const TRAIN_SPRITE_TOP: number;
+export declare const TRAIN_CENTER_X: number;
+export declare const TRAIN_OFFSCREEN_LEFT_X: number;
+export declare const TRAIN_OFFSCREEN_RIGHT_X: number;
+export declare const FOLLOW_CAR_WIDTH = 9;
+export declare const FOLLOW_CAR_PITCH = 8;
+export declare const FOLLOW_CAR_HEIGHT = 6;
+export declare const FOLLOW_WINDOW_LEFT: number;
+export declare const FOLLOW_WINDOW_WIDTH: number;
+export declare const FOLLOW_CAR_TOP: number;
+export declare const FOLLOW_AGE_ROW: number;
+export declare const FOLLOW_CENTER_SLOT_X: number;
+export declare const FOLLOW_CONNECTION_SLOT_X: number;
+export declare const FOLLOW_PENDING_SLOT_X = 0;
+export declare const FOLLOW_PENDING_OFFSCREEN_LEFT_X: number;
+export declare const FOLLOW_CLIP_MIN_COLUMN = 0;
+export declare const FOLLOW_CLIP_MAX_COLUMN: number;
+export declare const FOLLOW_RIGHT_SLOT_XS: readonly [number, number, number, number];
+export declare const FOLLOW_PENDING_LABEL = "~10 min";
+export declare const FOLLOW_PENDING_ENTER_MS = 1000;
+export declare const FOLLOW_APPROACH_MS = 3000;
+export declare const FOLLOW_FAST_APPROACH_MS = 1000;
+export declare const FOLLOW_SHIFT_MS = 1000;
+export declare const FOLLOW_FAST_SHIFT_MS = 1000;

package/dist/bitcoind/progress/constants.js

@@ -0,0 +1,53 @@
+export const PROGRESS_TICK_MS = 250;
+export const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
+export const ART_WIDTH = 80;
+export const ART_HEIGHT = 13;
+export const INTRO_ENTRY_MS = 5_000;
+export const INTRO_PAUSE_MS = 5_000;
+export const INTRO_EXIT_MS = 5_000;
+export const INTRO_TOTAL_MS = INTRO_ENTRY_MS + INTRO_PAUSE_MS + INTRO_EXIT_MS;
+export const STATUS_ELLIPSIS_WIDTH = 3;
+export const STATUS_ELLIPSIS_TICK_MS = 500;
+export const NEUTRAL_MESSAGE_TITLE = "⛭  C O G C O I N  ⛭";
+export const MESSAGE_FIELD_ROW = 1;
+export const STATUS_FIELD_ROW = 12;
+export const FIELD_LEFT = 8;
+export const FIELD_WIDTH = 64;
+export const SCROLL_WINDOW_LEFT = 7;
+export const SCROLL_WINDOW_TOP = 3;
+export const SCROLL_WINDOW_WIDTH = 65;
+export const SCROLL_WINDOW_HEIGHT = 8;
+export const TRAIN_CLIP_MIN_COLUMN = -1;
+export const TRAIN_CLIP_MAX_COLUMN = SCROLL_WINDOW_WIDTH;
+export const MAX_QUOTE_LINES = 6;
+export const TRAIN_SPRITE_WIDTH = 64;
+export const TRAIN_SPRITE_HEIGHT = 6;
+export const TRAIN_SPRITE_TOP = SCROLL_WINDOW_TOP + Math.floor((SCROLL_WINDOW_HEIGHT - TRAIN_SPRITE_HEIGHT) / 2);
+export const TRAIN_CENTER_X = Math.round((SCROLL_WINDOW_WIDTH - TRAIN_SPRITE_WIDTH) / 2);
+export const TRAIN_OFFSCREEN_LEFT_X = -TRAIN_SPRITE_WIDTH - 1;
+export const TRAIN_OFFSCREEN_RIGHT_X = SCROLL_WINDOW_WIDTH + 1;
+export const FOLLOW_CAR_WIDTH = 9;
+export const FOLLOW_CAR_PITCH = 8;
+export const FOLLOW_CAR_HEIGHT = 6;
+export const FOLLOW_WINDOW_LEFT = SCROLL_WINDOW_LEFT - 1;
+export const FOLLOW_WINDOW_WIDTH = SCROLL_WINDOW_WIDTH + 3;
+export const FOLLOW_CAR_TOP = SCROLL_WINDOW_TOP + Math.floor((SCROLL_WINDOW_HEIGHT - FOLLOW_CAR_HEIGHT) / 2) - 2;
+export const FOLLOW_AGE_ROW = FOLLOW_CAR_TOP + FOLLOW_CAR_HEIGHT;
+export const FOLLOW_CENTER_SLOT_X = Math.floor((FOLLOW_WINDOW_WIDTH - FOLLOW_CAR_WIDTH) / 2);
+export const FOLLOW_CONNECTION_SLOT_X = FOLLOW_CENTER_SLOT_X - FOLLOW_CAR_PITCH;
+export const FOLLOW_PENDING_SLOT_X = 0;
+export const FOLLOW_PENDING_OFFSCREEN_LEFT_X = -FOLLOW_CAR_WIDTH;
+export const FOLLOW_CLIP_MIN_COLUMN = 0;
+export const FOLLOW_CLIP_MAX_COLUMN = FOLLOW_WINDOW_WIDTH - 1;
+export const FOLLOW_RIGHT_SLOT_XS = [
+    FOLLOW_CENTER_SLOT_X + FOLLOW_CAR_PITCH,
+    FOLLOW_CENTER_SLOT_X + (FOLLOW_CAR_PITCH * 2),
+    FOLLOW_CENTER_SLOT_X + (FOLLOW_CAR_PITCH * 3),
+    FOLLOW_CENTER_SLOT_X + (FOLLOW_CAR_PITCH * 4),
+];
+export const FOLLOW_PENDING_LABEL = "~10 min";
+export const FOLLOW_PENDING_ENTER_MS = 1_000;
+export const FOLLOW_APPROACH_MS = 3_000;
+export const FOLLOW_FAST_APPROACH_MS = 1_000;
+export const FOLLOW_SHIFT_MS = 1_000;
+export const FOLLOW_FAST_SHIFT_MS = 1_000;

package/dist/bitcoind/progress/controller.d.ts

@@ -0,0 +1,28 @@
+import type { BootstrapPhase, BootstrapProgress, ManagedBitcoindProgressEvent, ProgressOutputMode, SnapshotMetadata, WritingQuote } from "../types.js";
+interface ProgressControllerOptions {
+    onProgress?: (event: ManagedBitcoindProgressEvent) => void;
+    progressOutput?: ProgressOutputMode;
+    quoteStatePath: string;
+    snapshot: SnapshotMetadata;
+}
+export declare class ManagedProgressController {
+    #private;
+    constructor(options: ProgressControllerOptions);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    enableFollowVisualMode(indexedHeight?: number | null, blockTimesByHeight?: Record<number, number>): Promise<void>;
+    setFollowBlockTime(height: number, blockTime: number): void;
+    replaceFollowBlockTimes(blockTimesByHeight: Record<number, number>): void;
+    playCompletionScene(): Promise<void>;
+    setPhase(phase: BootstrapPhase, patch?: Partial<Omit<BootstrapProgress, "phase" | "updatedAt">>): Promise<void>;
+    setCogcoinSync(height: number | null, targetHeight: number | null, etaSeconds?: number | null): Promise<void>;
+    getStatusSnapshot(): {
+        bootstrapPhase: BootstrapPhase;
+        bootstrapProgress: BootstrapProgress;
+        cogcoinSyncHeight: number | null;
+        cogcoinSyncTargetHeight: number | null;
+        currentQuote: WritingQuote | null;
+        snapshot: SnapshotMetadata;
+    };
+}
+export {};

package/dist/bitcoind/progress/controller.js

@@ -0,0 +1,188 @@
+import { WritingQuoteRotator as QuoteRotator } from "../quotes.js";
+import { INTRO_TOTAL_MS, PROGRESS_TICK_MS } from "./constants.js";
+import { advanceFollowSceneState, createFollowSceneState, replaceFollowBlockTimes, setFollowBlockTime, syncFollowSceneState, } from "./follow-scene.js";
+import { createBootstrapProgress, createDefaultMessage, resolveStatusFieldText, } from "./formatting.js";
+import { TtyProgressRenderer } from "./tty-renderer.js";
+export class ManagedProgressController {
+    #options;
+    #snapshot;
+    #outputMode;
+    #quoteRotator = null;
+    #renderer = null;
+    #ticker = null;
+    #currentQuote = null;
+    #currentDisplayPhase = "banner";
+    #currentDisplayStartedAt = 0;
+    #cogcoinSyncHeight = null;
+    #cogcoinSyncTargetHeight = null;
+    #progress;
+    #started = false;
+    #followVisualMode = false;
+    #followScene = createFollowSceneState();
+    constructor(options) {
+        this.#options = options;
+        this.#snapshot = options.snapshot;
+        this.#outputMode = options.progressOutput ?? "auto";
+        this.#progress = createBootstrapProgress("paused", options.snapshot);
+    }
+    async start() {
+        if (this.#started) {
+            return;
+        }
+        this.#started = true;
+        this.#quoteRotator = await QuoteRotator.create(this.#options.quoteStatePath);
+        if (this.#shouldRenderToTty()) {
+            this.#renderer = new TtyProgressRenderer();
+        }
+        await this.#refresh();
+        this.#ticker = setInterval(() => {
+            void this.#refresh();
+        }, PROGRESS_TICK_MS);
+    }
+    async close() {
+        if (this.#ticker !== null) {
+            clearInterval(this.#ticker);
+            this.#ticker = null;
+        }
+        this.#renderer?.close();
+        this.#renderer = null;
+        this.#started = false;
+    }
+    async enableFollowVisualMode(indexedHeight = null, blockTimesByHeight = {}) {
+        this.#followVisualMode = true;
+        this.#followScene = createFollowSceneState(indexedHeight, blockTimesByHeight);
+        this.#currentQuote = null;
+        if (this.#started) {
+            await this.#refresh();
+        }
+    }
+    setFollowBlockTime(height, blockTime) {
+        if (!this.#followVisualMode) {
+            return;
+        }
+        setFollowBlockTime(this.#followScene, height, blockTime);
+    }
+    replaceFollowBlockTimes(blockTimesByHeight) {
+        if (!this.#followVisualMode) {
+            return;
+        }
+        replaceFollowBlockTimes(this.#followScene, blockTimesByHeight);
+    }
+    async playCompletionScene() {
+        if (!this.#started || this.#renderer === null) {
+            return;
+        }
+        if (this.#ticker !== null) {
+            clearInterval(this.#ticker);
+            this.#ticker = null;
+        }
+        const startedAt = Date.now();
+        while (true) {
+            const elapsedMs = Math.min(INTRO_TOTAL_MS, Date.now() - startedAt);
+            this.#renderer.renderTrainScene("completion", this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, elapsedMs);
+            if (elapsedMs >= INTRO_TOTAL_MS) {
+                break;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, PROGRESS_TICK_MS);
+            });
+        }
+    }
+    async setPhase(phase, patch = {}) {
+        this.#progress = {
+            ...this.#progress,
+            ...patch,
+            phase,
+            message: patch.message ?? createDefaultMessage(phase),
+            updatedAt: Date.now(),
+        };
+        if (phase !== "cogcoin_sync" && phase !== "follow_tip") {
+            this.#cogcoinSyncHeight = null;
+            this.#cogcoinSyncTargetHeight = null;
+        }
+        if (this.#followVisualMode) {
+            syncFollowSceneState(this.#followScene, {
+                indexedHeight: phase === "follow_tip" ? this.#cogcoinSyncHeight : undefined,
+                nodeHeight: this.#progress.blocks,
+                liveActivated: phase === "follow_tip" || this.#followScene.liveActivated,
+            });
+        }
+        await this.#refresh();
+    }
+    async setCogcoinSync(height, targetHeight, etaSeconds = null) {
+        this.#cogcoinSyncHeight = height;
+        this.#cogcoinSyncTargetHeight = targetHeight;
+        this.#progress = {
+            ...this.#progress,
+            phase: "cogcoin_sync",
+            message: createDefaultMessage("cogcoin_sync"),
+            etaSeconds,
+            updatedAt: Date.now(),
+        };
+        if (this.#followVisualMode) {
+            syncFollowSceneState(this.#followScene, {
+                indexedHeight: height,
+                nodeHeight: targetHeight,
+                liveActivated: this.#followScene.liveActivated,
+            });
+        }
+        await this.#refresh();
+    }
+    getStatusSnapshot() {
+        return {
+            bootstrapPhase: this.#progress.phase,
+            bootstrapProgress: { ...this.#progress },
+            cogcoinSyncHeight: this.#cogcoinSyncHeight,
+            cogcoinSyncTargetHeight: this.#cogcoinSyncTargetHeight,
+            currentQuote: this.#currentQuote,
+            snapshot: this.#snapshot,
+        };
+    }
+    async #refresh() {
+        if (!this.#started || this.#quoteRotator === null) {
+            return;
+        }
+        const now = Date.now();
+        if (this.#followVisualMode) {
+            advanceFollowSceneState(this.#followScene, now);
+            this.#currentQuote = null;
+        }
+        else {
+            const snapshot = await this.#quoteRotator.current(now);
+            this.#currentDisplayPhase = snapshot.displayPhase;
+            this.#currentDisplayStartedAt = snapshot.displayStartedAt;
+            this.#currentQuote = snapshot.displayPhase === "scroll"
+                ? snapshot.currentQuote
+                : null;
+        }
+        const event = {
+            phase: this.#progress.phase,
+            progress: { ...this.#progress },
+            snapshot: this.#snapshot,
+            currentQuote: this.#currentQuote,
+            cogcoinSyncHeight: this.#cogcoinSyncHeight,
+            cogcoinSyncTargetHeight: this.#cogcoinSyncTargetHeight,
+        };
+        try {
+            this.#options.onProgress?.(event);
+        }
+        catch {
+            // User progress callbacks should never break managed sync.
+        }
+        const statusFieldText = resolveStatusFieldText(this.#progress, this.#snapshot.height, now);
+        if (this.#followVisualMode) {
+            this.#renderer?.renderFollowScene(this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, this.#followScene, statusFieldText);
+            return;
+        }
+        this.#renderer?.render(this.#currentDisplayPhase, this.#currentQuote, this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, Math.max(0, now - this.#currentDisplayStartedAt), statusFieldText);
+    }
+    #shouldRenderToTty() {
+        if (this.#outputMode === "none") {
+            return false;
+        }
+        if (this.#outputMode === "tty") {
+            return true;
+        }
+        return process.stderr.isTTY === true;
+    }
+}

package/dist/bitcoind/progress/follow-scene.d.ts

@@ -0,0 +1,40 @@
+export type FollowAnimationKind = "placeholder_enter" | "tip_approach" | "convoy_shift";
+export interface FollowAnimation {
+    kind: FollowAnimationKind;
+    startedAt: number;
+    height: number | null;
+    durationMs: number;
+}
+export interface FollowSceneStateForTesting {
+    liveActivated: boolean;
+    indexedHeight: number | null;
+    displayedCenterHeight: number | null;
+    observedNodeHeight: number | null;
+    blockTimesByHeight: Record<number, number>;
+    queuedHeights: number[];
+    pendingLabel: string | null;
+    pendingStaticX: number | null;
+    animation: FollowAnimation | null;
+}
+export declare function createFollowSceneState(indexedHeight?: number | null, blockTimesByHeight?: Record<number, number>): FollowSceneStateForTesting;
+export declare function setFollowBlockTime(state: FollowSceneStateForTesting, height: number, blockTime: number): void;
+export declare function replaceFollowBlockTimes(state: FollowSceneStateForTesting, blockTimesByHeight: Record<number, number>): void;
+export declare function formatCompactFollowAgeLabel(blockTime: number, now: number): string;
+export declare const formatCompactFollowAgeLabelForTesting: typeof formatCompactFollowAgeLabel;
+export declare function syncFollowSceneState(state: FollowSceneStateForTesting, { indexedHeight, nodeHeight, liveActivated, }: {
+    indexedHeight?: number | null;
+    nodeHeight?: number | null;
+    liveActivated?: boolean;
+}): void;
+export declare function advanceFollowSceneState(state: FollowSceneStateForTesting, now: number): void;
+export declare function renderFollowFrame(state: FollowSceneStateForTesting, statusFieldText: string, now: number): string[];
+export declare function createFollowSceneStateForTesting(indexedHeight?: number | null, blockTimesByHeight?: Record<number, number>): FollowSceneStateForTesting;
+export declare function setFollowBlockTimesForTesting(state: FollowSceneStateForTesting, blockTimesByHeight: Record<number, number>): FollowSceneStateForTesting;
+export declare function setFollowBlockTimeForTesting(state: FollowSceneStateForTesting, height: number, blockTime: number): FollowSceneStateForTesting;
+export declare function syncFollowSceneStateForTesting(state: FollowSceneStateForTesting, options: {
+    indexedHeight?: number | null;
+    nodeHeight?: number | null;
+    liveActivated?: boolean;
+}): FollowSceneStateForTesting;
+export declare function advanceFollowSceneStateForTesting(state: FollowSceneStateForTesting, now: number): FollowSceneStateForTesting;
+export declare function renderFollowFrameForTesting(state: FollowSceneStateForTesting, statusFieldText?: string, now?: number): string[];