@cogcoin/client 0.5.0

package/dist/cli/runner.js

@@ -0,0 +1,129 @@
+import { createDefaultContext } from "./context.js";
+import { writeLine } from "./io.js";
+import { classifyCliError, createCommandJsonErrorEnvelope, createErrorEnvelope, formatCliTextError, inferOutputMode, isStructuredOutputMode, writeJsonValue, } from "./output.js";
+import { HELP_TEXT, parseCliArgs } from "./parse.js";
+import { runFollowCommand } from "./commands/follow.js";
+import { runMiningAdminCommand } from "./commands/mining-admin.js";
+import { runMiningReadCommand } from "./commands/mining-read.js";
+import { runMiningRuntimeCommand } from "./commands/mining-runtime.js";
+import { runStatusCommand } from "./commands/status.js";
+import { runSyncCommand } from "./commands/sync.js";
+import { runWalletAdminCommand } from "./commands/wallet-admin.js";
+import { runWalletMutationCommand } from "./commands/wallet-mutation.js";
+import { runWalletReadCommand } from "./commands/wallet-read.js";
+export async function runCli(argv, contextOverrides = {}) {
+    const context = createDefaultContext(contextOverrides);
+    let parsed;
+    try {
+        parsed = parseCliArgs(argv);
+    }
+    catch (error) {
+        const classified = classifyCliError(error);
+        if (isStructuredOutputMode(inferOutputMode(argv))) {
+            writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/cli/v1", `cogcoin ${argv.join(" ")}`.trim(), classified.errorCode, classified.message));
+            return classified.exitCode;
+        }
+        writeLine(context.stderr, classified.message);
+        writeLine(context.stderr, HELP_TEXT.trimEnd());
+        return classified.exitCode;
+    }
+    if (parsed.version) {
+        writeLine(context.stdout, await context.readPackageVersion());
+        return 0;
+    }
+    if (parsed.help || parsed.command === null) {
+        if (parsed.command === null && isStructuredOutputMode(parsed.outputMode)) {
+            writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/cli/v1", "cogcoin", "cli_missing_command", "cli_missing_command"));
+            return 2;
+        }
+        writeLine(context.stdout, HELP_TEXT.trimEnd());
+        return parsed.help ? 0 : 2;
+    }
+    try {
+        if (parsed.command === "sync") {
+            return runSyncCommand(parsed, context);
+        }
+        if (parsed.command === "follow") {
+            return runFollowCommand(parsed, context);
+        }
+        if (parsed.command === "status") {
+            return runStatusCommand(parsed, context);
+        }
+        if (parsed.command === "mine"
+            || parsed.command === "mine-start"
+            || parsed.command === "mine-stop") {
+            return runMiningRuntimeCommand(parsed, context);
+        }
+        if (parsed.command === "hooks-mining-enable"
+            || parsed.command === "hooks-mining-disable"
+            || parsed.command === "mine-setup") {
+            return runMiningAdminCommand(parsed, context);
+        }
+        if (parsed.command === "init"
+            || parsed.command === "repair"
+            || parsed.command === "unlock"
+            || parsed.command === "wallet-export"
+            || parsed.command === "wallet-import"
+            || parsed.command === "wallet-init"
+            || parsed.command === "wallet-unlock"
+            || parsed.command === "wallet-lock") {
+            return runWalletAdminCommand(parsed, context);
+        }
+        if (parsed.command === "anchor"
+            || parsed.command === "domain-anchor"
+            || parsed.command === "register"
+            || parsed.command === "domain-register"
+            || parsed.command === "transfer"
+            || parsed.command === "domain-transfer"
+            || parsed.command === "sell"
+            || parsed.command === "domain-sell"
+            || parsed.command === "unsell"
+            || parsed.command === "domain-unsell"
+            || parsed.command === "buy"
+            || parsed.command === "domain-buy"
+            || parsed.command === "domain-endpoint-set"
+            || parsed.command === "domain-endpoint-clear"
+            || parsed.command === "domain-delegate-set"
+            || parsed.command === "domain-delegate-clear"
+            || parsed.command === "domain-miner-set"
+            || parsed.command === "domain-miner-clear"
+            || parsed.command === "domain-canonical"
+            || parsed.command === "field-create"
+            || parsed.command === "field-set"
+            || parsed.command === "field-clear"
+            || parsed.command === "send"
+            || parsed.command === "claim"
+            || parsed.command === "reclaim"
+            || parsed.command === "cog-send"
+            || parsed.command === "cog-claim"
+            || parsed.command === "cog-reclaim"
+            || parsed.command === "cog-lock"
+            || parsed.command === "rep-give"
+            || parsed.command === "rep-revoke") {
+            return runWalletMutationCommand(parsed, context);
+        }
+        if (parsed.command === "hooks-mining-status"
+            || parsed.command === "mine-status"
+            || parsed.command === "mine-log") {
+            return runMiningReadCommand(parsed, context);
+        }
+        return runWalletReadCommand(parsed, context);
+    }
+    catch (error) {
+        const classified = classifyCliError(error);
+        if (isStructuredOutputMode(parsed.outputMode)) {
+            writeJsonValue(context.stdout, createCommandJsonErrorEnvelope(parsed, error));
+            return classified.exitCode;
+        }
+        const formatted = formatCliTextError(error);
+        if (formatted !== null) {
+            for (const line of formatted) {
+                writeLine(context.stderr, line);
+            }
+        }
+        else {
+            writeLine(context.stderr, classified.message);
+        }
+        return classified.exitCode;
+    }
+}

package/dist/cli/signals.d.ts

@@ -0,0 +1,3 @@
+import type { InterruptibleOutcome, ManagedClientLike, SignalSource, StopSignalWatcher, WritableLike } from "./types.js";
+export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void): StopSignalWatcher;
+export declare function waitForCompletionOrStop<T>(promise: Promise<T>, stopWatcher: StopSignalWatcher): Promise<InterruptibleOutcome<T>>;

package/dist/cli/signals.js

@@ -0,0 +1,63 @@
+import { writeLine } from "./io.js";
+export function createStopSignalWatcher(signalSource, stderr, client, forceExit) {
+    let closing = false;
+    let resolved = false;
+    let onSignal = () => { };
+    const cleanup = () => {
+        signalSource.off("SIGINT", onSignal);
+        signalSource.off("SIGTERM", onSignal);
+    };
+    const promise = new Promise((resolve) => {
+        const settle = (code) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            cleanup();
+            resolve(code);
+        };
+        const onFirstSignal = () => {
+            closing = true;
+            writeLine(stderr, "Stopping managed Cogcoin client...");
+            void client.close().then(() => {
+                settle(0);
+            }, () => {
+                settle(1);
+            });
+        };
+        onSignal = () => {
+            if (!closing) {
+                onFirstSignal();
+                return;
+            }
+            settle(130);
+            forceExit(130);
+        };
+    });
+    signalSource.on("SIGINT", onSignal);
+    signalSource.on("SIGTERM", onSignal);
+    return {
+        cleanup,
+        isStopping: () => closing,
+        promise,
+    };
+}
+export async function waitForCompletionOrStop(promise, stopWatcher) {
+    const outcome = await Promise.race([
+        promise.then((value) => ({ kind: "completed", value }), (error) => ({ kind: "error", error })),
+        stopWatcher.promise.then((code) => ({ kind: "stopped", code })),
+    ]);
+    if (outcome.kind === "stopped") {
+        return outcome;
+    }
+    if (outcome.kind === "error") {
+        if (stopWatcher.isStopping()) {
+            return {
+                kind: "stopped",
+                code: await stopWatcher.promise,
+            };
+        }
+        throw outcome.error;
+    }
+    return outcome;
+}

package/dist/cli/status-format.d.ts

@@ -0,0 +1,2 @@
+import type { inspectPassiveClientStatus } from "../passive-status.js";
+export declare function formatStatusReport(status: Awaited<ReturnType<typeof inspectPassiveClientStatus>>): string;

package/dist/cli/status-format.js

@@ -0,0 +1,48 @@
+function formatBootstrapPercent(current, total) {
+    if (total <= 0) {
+        return "0.00";
+    }
+    return ((current / total) * 100).toFixed(2);
+}
+export function formatStatusReport(status) {
+    const lines = [
+        "Cogcoin Client Status",
+        `DB path: ${status.dbPath}`,
+        `Bitcoin datadir: ${status.bitcoinDataDir}`,
+        `Store exists: ${status.storeExists ? "yes" : "no"}`,
+        `Store initialized: ${status.storeInitialized ? "yes" : "no"}`,
+    ];
+    if (status.storeError !== null) {
+        lines.push(`Store error: ${status.storeError}`);
+    }
+    if (status.indexedTip === null) {
+        lines.push("Indexed tip: none");
+    }
+    else {
+        lines.push(`Indexed tip height: ${status.indexedTip.height}`);
+        lines.push(`Indexed tip hash: ${status.indexedTip.blockHashHex}`);
+        lines.push(`Indexed tip state hash: ${status.indexedTip.stateHashHex ?? "none"}`);
+    }
+    if (status.latestCheckpoint === null) {
+        lines.push("Latest checkpoint: none");
+    }
+    else {
+        lines.push(`Latest checkpoint height: ${status.latestCheckpoint.height}`);
+        lines.push(`Latest checkpoint hash: ${status.latestCheckpoint.blockHashHex}`);
+    }
+    if (status.bootstrap === null) {
+        lines.push("Bootstrap state: none");
+    }
+    else {
+        lines.push(`Bootstrap phase: ${status.bootstrap.phase}`);
+        lines.push(`Bootstrap download: ${status.bootstrap.downloadedBytes} / ${status.bootstrap.totalBytes} bytes (${formatBootstrapPercent(status.bootstrap.downloadedBytes, status.bootstrap.totalBytes)}%)`);
+        lines.push(`Bootstrap validated: ${status.bootstrap.validated ? "yes" : "no"}`);
+        lines.push(`Bootstrap loaded: ${status.bootstrap.loadTxOutSetComplete ? "yes" : "no"}`);
+        lines.push(`Bootstrap base height: ${status.bootstrap.baseHeight ?? "none"}`);
+        lines.push(`Bootstrap tip hash: ${status.bootstrap.tipHashHex ?? "none"}`);
+        lines.push(`Bootstrap snapshot height: ${status.bootstrap.snapshotHeight ?? "none"}`);
+        lines.push(`Bootstrap last error: ${status.bootstrap.lastError ?? "none"}`);
+    }
+    lines.push("Live node: not checked (passive status)");
+    return lines.join("\n");
+}

package/dist/cli/types.d.ts

@@ -0,0 +1,148 @@
+import type { inspectPassiveClientStatus } from "../passive-status.js";
+import { openSqliteStore } from "../sqlite/index.js";
+import type { ClientStoreAdapter } from "../types.js";
+import type { exportWallet, WalletPrompter, importWallet, initializeWallet, lockWallet, repairWallet, unlockWallet } from "../wallet/lifecycle.js";
+import type { openWalletReadContext } from "../wallet/read/index.js";
+import type { WalletSecretProvider } from "../wallet/state/provider.js";
+import type { disableMiningHooks, enableMiningHooks, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining } from "../wallet/mining/index.js";
+import type { anchorDomain, buyDomain, claimCogLock, clearDomainDelegate, clearDomainEndpoint, clearDomainMiner, clearField, createField, giveReputation, lockCogToDomain, registerDomain, reclaimCogLock, revokeReputation, sendCog, setField, setDomainCanonical, setDomainDelegate, setDomainEndpoint, setDomainMiner, sellDomain, transferDomain } from "../wallet/tx/index.js";
+export type ProgressOutput = "auto" | "tty" | "none";
+export type OutputMode = "text" | "json" | "preview-json";
+export type CommandName = "init" | "repair" | "sync" | "status" | "follow" | "unlock" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "hooks-mining-enable" | "hooks-mining-disable" | "hooks-mining-status" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-status" | "mine-log" | "wallet-export" | "wallet-import" | "wallet-init" | "wallet-lock" | "wallet-unlock" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
+export interface WritableLike {
+    isTTY?: boolean;
+    write(chunk: string): void;
+}
+export interface ReadableLike {
+    isTTY?: boolean;
+}
+export interface SignalSource {
+    on(event: "SIGINT" | "SIGTERM", listener: () => void): void;
+    off(event: "SIGINT" | "SIGTERM", listener: () => void): void;
+}
+export interface ParsedCliArgs {
+    command: CommandName | null;
+    args: string[];
+    help: boolean;
+    version: boolean;
+    outputMode: OutputMode;
+    dbPath: string | null;
+    dataDir: string | null;
+    progressOutput: ProgressOutput;
+    unlockFor: string | null;
+    assumeYes: boolean;
+    forceRace: boolean;
+    anchorMessage: string | null;
+    transferTarget: string | null;
+    endpointText: string | null;
+    endpointJson: string | null;
+    endpointBytes: string | null;
+    fieldPermanent: boolean;
+    fieldFormat: string | null;
+    fieldValue: string | null;
+    fromIdentity: string | null;
+    lockRecipientDomain: string | null;
+    conditionHex: string | null;
+    untilHeight: string | null;
+    preimageHex: string | null;
+    reviewText: string | null;
+    locksClaimableOnly: boolean;
+    locksReclaimableOnly: boolean;
+    domainsAnchoredOnly: boolean;
+    domainsListedOnly: boolean;
+    domainsMineableOnly: boolean;
+    listLimit: number | null;
+    listAll: boolean;
+    verify: boolean;
+    follow: boolean;
+}
+export interface ManagedClientLike {
+    syncToTip(): Promise<{
+        appliedBlocks: number;
+        rewoundBlocks: number;
+        endingHeight: number | null;
+        bestHeight: number;
+    }>;
+    playSyncCompletionScene?(): Promise<void>;
+    startFollowingTip(): Promise<void>;
+    getNodeStatus(): Promise<{
+        indexedTip: {
+            height: number;
+            blockHashHex: string;
+            stateHashHex: string | null;
+        } | null;
+        nodeBestHeight: number | null;
+    }>;
+    close(): Promise<void>;
+}
+export interface CliRunnerContext {
+    stdout?: WritableLike;
+    stderr?: WritableLike;
+    stdin?: ReadableLike;
+    signalSource?: SignalSource;
+    forceExit?: (code: number) => never | void;
+    openSqliteStore?: typeof openSqliteStore;
+    openManagedBitcoindClient?: (options: {
+        store: ClientStoreAdapter;
+        databasePath?: string;
+        dataDir?: string;
+        progressOutput?: ProgressOutput;
+    }) => Promise<ManagedClientLike>;
+    inspectPassiveClientStatus?: typeof inspectPassiveClientStatus;
+    openWalletReadContext?: typeof openWalletReadContext;
+    initializeWallet?: typeof initializeWallet;
+    exportWallet?: typeof exportWallet;
+    importWallet?: typeof importWallet;
+    unlockWallet?: typeof unlockWallet;
+    lockWallet?: typeof lockWallet;
+    registerDomain?: typeof registerDomain;
+    anchorDomain?: typeof anchorDomain;
+    transferDomain?: typeof transferDomain;
+    sellDomain?: typeof sellDomain;
+    buyDomain?: typeof buyDomain;
+    sendCog?: typeof sendCog;
+    claimCogLock?: typeof claimCogLock;
+    reclaimCogLock?: typeof reclaimCogLock;
+    lockCogToDomain?: typeof lockCogToDomain;
+    setDomainEndpoint?: typeof setDomainEndpoint;
+    clearDomainEndpoint?: typeof clearDomainEndpoint;
+    setDomainDelegate?: typeof setDomainDelegate;
+    clearDomainDelegate?: typeof clearDomainDelegate;
+    setDomainMiner?: typeof setDomainMiner;
+    clearDomainMiner?: typeof clearDomainMiner;
+    setDomainCanonical?: typeof setDomainCanonical;
+    createField?: typeof createField;
+    setField?: typeof setField;
+    clearField?: typeof clearField;
+    giveReputation?: typeof giveReputation;
+    revokeReputation?: typeof revokeReputation;
+    enableMiningHooks?: typeof enableMiningHooks;
+    disableMiningHooks?: typeof disableMiningHooks;
+    inspectMiningControlPlane?: typeof inspectMiningControlPlane;
+    runForegroundMining?: typeof runForegroundMining;
+    startBackgroundMining?: typeof startBackgroundMining;
+    stopBackgroundMining?: typeof stopBackgroundMining;
+    setupBuiltInMining?: typeof setupBuiltInMining;
+    readMiningLog?: typeof readMiningLog;
+    followMiningLog?: typeof followMiningLog;
+    repairWallet?: typeof repairWallet;
+    walletSecretProvider?: WalletSecretProvider;
+    createPrompter?: () => WalletPrompter;
+    ensureDirectory?: (path: string) => Promise<void>;
+    readPackageVersion?: () => Promise<string>;
+    resolveDefaultBitcoindDataDir?: () => string;
+    resolveDefaultClientDatabasePath?: () => string;
+}
+export interface StopSignalWatcher {
+    cleanup(): void;
+    isStopping(): boolean;
+    promise: Promise<number>;
+}
+export type InterruptibleOutcome<T> = {
+    kind: "completed";
+    value: T;
+} | {
+    kind: "stopped";
+    code: number;
+};
+export type RequiredCliRunnerContext = Required<CliRunnerContext>;

package/dist/cli/types.js

@@ -0,0 +1,2 @@
+import { openManagedBitcoindClient } from "../bitcoind/index.js";
+import { openSqliteStore } from "../sqlite/index.js";

package/dist/cli/wallet-format.d.ts

@@ -0,0 +1,29 @@
+import type { WalletDomainView, WalletReadContext } from "../wallet/read/index.js";
+export declare function getRepairRecommendation(context: WalletReadContext): string | null;
+export declare function getMutationRecommendation(context: WalletReadContext): string | null;
+export declare function formatWalletOverviewReport(context: WalletReadContext): string;
+export declare function formatDetailedWalletStatusReport(context: WalletReadContext): string;
+export declare function formatFundingAddressReport(context: WalletReadContext): string;
+export declare function formatIdentityListReport(context: WalletReadContext, options?: {
+    limit?: number | null;
+    all?: boolean;
+}): string;
+export declare function formatBalanceReport(context: WalletReadContext): string;
+export declare function formatLocksReport(context: WalletReadContext, options?: {
+    claimableOnly?: boolean;
+    reclaimableOnly?: boolean;
+    limit?: number | null;
+    all?: boolean;
+}): string;
+export declare function formatDomainsReport(context: WalletReadContext, options?: {
+    limit?: number | null;
+    all?: boolean;
+    domains?: WalletDomainView[] | null;
+    activeFilters?: string[];
+}): string;
+export declare function formatDomainReport(context: WalletReadContext, domainName: string): string;
+export declare function formatFieldsReport(context: WalletReadContext, domainName: string, options?: {
+    limit?: number | null;
+    all?: boolean;
+}): string;
+export declare function formatFieldReport(context: WalletReadContext, domainName: string, fieldName: string): string;