@cogcoin/client 0.5.0

package/dist/bitcoind/testing.d.ts

@@ -0,0 +1,9 @@
+export { openManagedBitcoindClientInternal } from "./client.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { normalizeRpcBlock } from "./normalize.js";
+export { BitcoinRpcClient } from "./rpc.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
+export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";
+export { WritingQuoteRotator, loadWritingQuotesForTesting, shuffleIndicesForTesting, } from "./quotes.js";

package/dist/bitcoind/testing.js

@@ -0,0 +1,9 @@
+export { openManagedBitcoindClientInternal } from "./client.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { normalizeRpcBlock } from "./normalize.js";
+export { BitcoinRpcClient } from "./rpc.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, createBootstrapStateForTesting, downloadSnapshotFileForTesting, loadBootstrapStateForTesting, resolveBootstrapPathsForTesting, saveBootstrapStateForTesting, validateSnapshotFileForTesting, waitForHeadersForTesting, } from "./bootstrap.js";
+export { buildBitcoindArgsForTesting, createRpcClient, launchManagedBitcoindNode, resolveDefaultBitcoindDataDirForTesting, validateNodeConfigForTesting, } from "./node.js";
+export { ManagedProgressController, TtyProgressRenderer, advanceFollowSceneStateForTesting, createFollowSceneStateForTesting, createBootstrapProgressForTesting, formatCompactFollowAgeLabelForTesting, loadBannerArtForTesting, loadScrollArtForTesting, loadTrainCarArtForTesting, loadTrainArtForTesting, loadTrainSmokeArtForTesting, formatProgressLineForTesting, formatQuoteLineForTesting, renderArtFrameForTesting, renderCompletionFrameForTesting, renderFollowFrameForTesting, renderIntroFrameForTesting, resolveCompletionMessageForTesting, resolveIntroMessageForTesting, resolveStatusFieldTextForTesting, setFollowBlockTimeForTesting, setFollowBlockTimesForTesting, syncFollowSceneStateForTesting, } from "./progress.js";
+export { WritingQuoteRotator, loadWritingQuotesForTesting, shuffleIndicesForTesting, } from "./quotes.js";

package/dist/bitcoind/types.d.ts

@@ -0,0 +1,396 @@
+import type { BitcoinBlock, Client, ClientOptions, ClientTip } from "../types.js";
+export type BootstrapPhase = "snapshot_download" | "wait_headers_for_snapshot" | "load_snapshot" | "bitcoin_sync" | "cogcoin_sync" | "follow_tip" | "paused" | "error" | "complete";
+export type ProgressOutputMode = "auto" | "tty" | "none";
+export interface SnapshotMetadata {
+    url: string;
+    filename: string;
+    height: number;
+    sha256: string;
+    sizeBytes: number;
+}
+export interface WritingQuote {
+    quote: string;
+    author: string;
+}
+export interface BootstrapProgress {
+    phase: BootstrapPhase;
+    message: string;
+    resumed: boolean;
+    downloadedBytes: number | null;
+    totalBytes: number | null;
+    percent: number | null;
+    bytesPerSecond: number | null;
+    etaSeconds: number | null;
+    headers: number | null;
+    blocks: number | null;
+    targetHeight: number | null;
+    baseHeight: number | null;
+    tipHashHex: string | null;
+    lastError: string | null;
+    updatedAt: number;
+}
+export interface ManagedBitcoindProgressEvent {
+    phase: BootstrapPhase;
+    progress: BootstrapProgress;
+    snapshot: SnapshotMetadata;
+    currentQuote: WritingQuote | null;
+    cogcoinSyncHeight: number | null;
+    cogcoinSyncTargetHeight: number | null;
+}
+export interface BitcoindRpcConfig {
+    url: string;
+    cookieFile: string;
+    port: number;
+}
+export interface BitcoindZmqConfig {
+    endpoint: string;
+    topic: "hashblock";
+    port: number;
+    pollIntervalMs: number;
+}
+export interface ManagedBitcoindRuntimeConfig {
+    chain: "main" | "regtest";
+    rpc: BitcoindRpcConfig;
+    zmqPort: number;
+    p2pPort: number;
+}
+export declare const MANAGED_BITCOIND_SERVICE_API_VERSION = "cogcoin/bitcoind-service/v1";
+export type ManagedBitcoindServiceState = "starting" | "ready" | "stopping" | "failed";
+export interface ManagedBitcoindServiceStatus {
+    serviceApiVersion: typeof MANAGED_BITCOIND_SERVICE_API_VERSION;
+    binaryVersion: string;
+    buildId: string | null;
+    serviceInstanceId: string;
+    state: ManagedBitcoindServiceState;
+    processId: number | null;
+    walletRootId: string;
+    chain: "main" | "regtest";
+    dataDir: string;
+    runtimeRoot: string;
+    startHeight: number;
+    rpc: BitcoindRpcConfig;
+    zmq: BitcoindZmqConfig;
+    p2pPort: number;
+    walletReplica: ManagedCoreWalletReplicaStatus | null;
+    startedAtUnixMs: number;
+    heartbeatAtUnixMs: number;
+    updatedAtUnixMs: number;
+    lastError: string | null;
+}
+export interface ManagedBitcoindObservedStatus extends Omit<ManagedBitcoindServiceStatus, "serviceApiVersion"> {
+    serviceApiVersion: string;
+}
+export type ManagedBitcoindHealth = "ready" | "starting" | "failed" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "replica-missing" | "replica-mismatch" | "unavailable";
+export interface SyncResult {
+    appliedBlocks: number;
+    rewoundBlocks: number;
+    commonAncestorHeight: number | null;
+    startingHeight: number | null;
+    endingHeight: number | null;
+    bestHeight: number;
+    bestHashHex: string;
+}
+export interface ManagedBitcoindStatus {
+    ready: boolean;
+    following: boolean;
+    chain: string;
+    pid: number | null;
+    walletRootId: string | null;
+    rpc: BitcoindRpcConfig;
+    zmq: BitcoindZmqConfig;
+    indexedTip: ClientTip | null;
+    nodeBestHeight: number | null;
+    nodeBestHashHex: string | null;
+    bootstrapPhase: BootstrapPhase;
+    bootstrapProgress: BootstrapProgress;
+    cogcoinSyncHeight: number | null;
+    cogcoinSyncTargetHeight: number | null;
+    currentQuote: WritingQuote | null;
+    snapshot: SnapshotMetadata;
+    serviceRuntimeRoot?: string;
+    serviceUpdatedAtUnixMs?: number | null;
+    walletReplica?: ManagedCoreWalletReplicaStatus | null;
+    serviceStatus?: ManagedBitcoindObservedStatus | null;
+    indexerDaemon?: ManagedIndexerDaemonObservedStatus | null;
+}
+export interface ManagedBitcoindOptions extends ClientOptions {
+    dataDir?: string;
+    databasePath?: string;
+    rpcPort?: number;
+    zmqPort?: number;
+    p2pPort?: number;
+    startupTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    pollIntervalMs?: number;
+    syncDebounceMs?: number;
+    walletRootId?: string;
+    managedWalletPassphrase?: string;
+    onProgress?: (event: ManagedBitcoindProgressEvent) => void;
+    progressOutput?: ProgressOutputMode;
+}
+export interface ManagedBitcoindClient extends Client {
+    syncToTip(): Promise<SyncResult>;
+    startFollowingTip(): Promise<void>;
+    getNodeStatus(): Promise<ManagedBitcoindStatus>;
+    close(): Promise<void>;
+}
+export interface InternalManagedBitcoindOptions extends ManagedBitcoindOptions {
+    chain: "main" | "regtest";
+    startHeight: number;
+}
+export interface ManagedCoreWalletReplicaStatus {
+    walletRootId: string;
+    walletName: string;
+    loaded: boolean;
+    descriptors: boolean;
+    privateKeysEnabled: boolean;
+    created: boolean;
+    proofStatus?: "not-proven" | "ready" | "missing" | "mismatch";
+    descriptorChecksum?: string | null;
+    fundingAddress0?: string | null;
+    fundingScriptPubKeyHex0?: string | null;
+    message?: string | null;
+}
+export declare const INDEXER_DAEMON_SERVICE_API_VERSION = "cogcoin/indexer-ipc/v1";
+export declare const INDEXER_DAEMON_SCHEMA_VERSION = "cogcoin/indexer-db/v1";
+export type ManagedIndexerTruthSource = "lease" | "probe" | "status-file" | "none";
+export type ManagedIndexerDaemonState = "starting" | "catching-up" | "reorging" | "synced" | "stopping" | "failed" | "schema-mismatch" | "service-version-mismatch";
+export interface ManagedIndexerDaemonRuntimeIdentity {
+    serviceApiVersion: typeof INDEXER_DAEMON_SERVICE_API_VERSION;
+    schemaVersion: typeof INDEXER_DAEMON_SCHEMA_VERSION;
+    walletRootId: string;
+    daemonInstanceId: string;
+    processId: number | null;
+    startedAtUnixMs: number;
+}
+export interface ManagedIndexerSnapshotIdentity extends ManagedIndexerDaemonRuntimeIdentity {
+    snapshotSeq: string | null;
+    tipHeight: number | null;
+    tipHash: string | null;
+    openedAtUnixMs: number;
+}
+export interface ManagedIndexerDaemonStatus {
+    serviceApiVersion: typeof INDEXER_DAEMON_SERVICE_API_VERSION;
+    binaryVersion: string;
+    buildId: string | null;
+    updatedAtUnixMs: number;
+    walletRootId: string;
+    daemonInstanceId: string;
+    schemaVersion: typeof INDEXER_DAEMON_SCHEMA_VERSION;
+    state: ManagedIndexerDaemonState;
+    processId: number | null;
+    startedAtUnixMs: number;
+    heartbeatAtUnixMs: number;
+    ipcReady: boolean;
+    rpcReachable: boolean;
+    coreBestHeight: number | null;
+    coreBestHash: string | null;
+    appliedTipHeight: number | null;
+    appliedTipHash: string | null;
+    snapshotSeq: string | null;
+    backlogBlocks: number | null;
+    reorgDepth: number | null;
+    lastAppliedAtUnixMs: number | null;
+    activeSnapshotCount: number;
+    lastError: string | null;
+}
+export interface ManagedIndexerDaemonObservedStatus extends Omit<ManagedIndexerDaemonStatus, "serviceApiVersion" | "schemaVersion"> {
+    serviceApiVersion: string;
+    schemaVersion: string;
+}
+export interface RpcBlockchainInfo {
+    chain: string;
+    blocks: number;
+    headers: number;
+    bestblockhash: string;
+    pruned: boolean;
+    verificationprogress?: number;
+    initialblockdownload?: boolean;
+}
+export interface RpcNetworkInfo {
+    networkactive: boolean;
+    connections: number;
+    connections_in?: number;
+    connections_out?: number;
+}
+export interface RpcZmqNotification {
+    type: string;
+    address: string;
+    hwm: number;
+}
+export interface RpcVout {
+    value: number | string;
+    n: number;
+    scriptPubKey?: {
+        hex?: string;
+        address?: string;
+    };
+}
+export interface RpcPrevout {
+    scriptPubKey?: {
+        hex?: string;
+        address?: string;
+    };
+}
+export interface RpcVin {
+    txid?: string;
+    coinbase?: string;
+    prevout?: RpcPrevout;
+}
+export interface RpcTransaction {
+    txid: string;
+    hash?: string;
+    vin: RpcVin[];
+    vout: RpcVout[];
+}
+export interface RpcMempoolInfo {
+    loaded: boolean;
+    size?: number;
+}
+export interface RpcMempoolEntry {
+    vsize: number;
+    fees: {
+        base: number;
+        ancestor: number;
+        descendant: number;
+    };
+    ancestorsize?: number;
+    descendantsize?: number;
+}
+export interface RpcRawMempoolVerbose {
+    txids: string[];
+    mempool_sequence: string | number;
+}
+export interface RpcWalletTransaction {
+    txid: string;
+    walletconflicts?: string[];
+    confirmations: number;
+    blockhash?: string;
+    blockheight?: number;
+    time?: number;
+    timereceived?: number;
+}
+export interface RpcBlock {
+    hash: string;
+    previousblockhash?: string;
+    height: number;
+    time?: number;
+    tx: RpcTransaction[];
+}
+export interface RpcChainState {
+    blocks?: number;
+    validated?: boolean;
+    snapshot_blockhash?: string;
+    verificationprogress?: number;
+}
+export interface RpcChainStatesResponse {
+    chainstates: RpcChainState[];
+    headers?: number;
+}
+export interface RpcLoadTxOutSetResult {
+    coins_loaded: number;
+    base_height: number;
+    tip_hash: string;
+}
+export interface RpcCreateWalletResult {
+    name: string;
+    warning: string;
+}
+export interface RpcLoadWalletResult {
+    name: string;
+    warning: string;
+}
+export interface RpcWalletInfo {
+    walletname: string;
+    private_keys_enabled: boolean;
+    descriptors: boolean;
+    unlocked_until?: number;
+}
+export interface RpcDescriptorInfo {
+    descriptor: string;
+    checksum: string;
+    isrange: boolean;
+    issolvable: boolean;
+    hasprivatekeys: boolean;
+}
+export interface RpcListDescriptorsEntry {
+    desc: string;
+    active?: boolean;
+    internal?: boolean;
+    next?: number;
+    range?: number | [number, number];
+    timestamp?: number | string;
+}
+export interface RpcListDescriptorsResult {
+    wallet_name?: string;
+    descriptors: RpcListDescriptorsEntry[];
+}
+export interface RpcImportDescriptorRequest {
+    desc: string;
+    timestamp: string | number;
+    active?: boolean;
+    internal?: boolean;
+    next_index?: number;
+    range?: number | [number, number];
+    label?: string;
+}
+export interface RpcImportDescriptorResult {
+    success: boolean;
+    warnings?: string[];
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface RpcWalletProcessPsbtResult {
+    psbt: string;
+    complete: boolean;
+}
+export interface RpcWalletCreateFundedPsbtResult {
+    psbt: string;
+    fee: number;
+    changepos: number;
+}
+export interface RpcLockedUnspent {
+    txid: string;
+    vout: number;
+}
+export interface RpcListUnspentEntry {
+    txid: string;
+    vout: number;
+    address?: string;
+    scriptPubKey: string;
+    amount: number;
+    confirmations: number;
+    spendable?: boolean;
+    solvable?: boolean;
+    safe?: boolean;
+}
+export interface RpcDecodedPsbt {
+    tx: RpcTransaction;
+}
+export interface RpcFinalizePsbtResult {
+    psbt?: string;
+    hex?: string;
+    complete: boolean;
+}
+export interface RpcTestMempoolAcceptResult {
+    txid?: string;
+    wtxid?: string;
+    allowed: boolean;
+    "reject-reason"?: string;
+}
+export interface ManagedBitcoindNodeHandle {
+    rpc: BitcoindRpcConfig;
+    zmq: BitcoindZmqConfig;
+    pid: number | null;
+    expectedChain: "main" | "regtest";
+    startHeight: number;
+    dataDir: string;
+    walletRootId?: string;
+    runtimeRoot?: string;
+    validate(): Promise<void>;
+    refreshServiceStatus?(): Promise<ManagedBitcoindServiceStatus>;
+    stop(): Promise<void>;
+}
+export type { BitcoinBlock };

package/dist/bitcoind/types.js

@@ -0,0 +1,3 @@
+export const MANAGED_BITCOIND_SERVICE_API_VERSION = "cogcoin/bitcoind-service/v1";
+export const INDEXER_DAEMON_SERVICE_API_VERSION = "cogcoin/indexer-ipc/v1";
+export const INDEXER_DAEMON_SCHEMA_VERSION = "cogcoin/indexer-db/v1";

package/dist/bytes.d.ts

@@ -0,0 +1,9 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function cloneBytes(bytes: Uint8Array): Uint8Array;
+export declare function encodeText(value: string): Uint8Array;
+export declare function decodeText(bytes: Uint8Array): string;
+export declare function encodeNullableText(value: string | null): Uint8Array;
+export declare function decodeNullableText(bytes: Uint8Array): string | null;
+export declare function encodeInteger(value: number): Uint8Array;
+export declare function decodeInteger(bytes: Uint8Array): number;

package/dist/bytes.js

@@ -0,0 +1,36 @@
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+export function bytesToHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+export function hexToBytes(hex) {
+    return new Uint8Array(Buffer.from(hex, "hex"));
+}
+export function cloneBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+export function encodeText(value) {
+    return textEncoder.encode(value);
+}
+export function decodeText(bytes) {
+    return textDecoder.decode(bytes);
+}
+export function encodeNullableText(value) {
+    return encodeText(value ?? "");
+}
+export function decodeNullableText(bytes) {
+    if (bytes.length === 0) {
+        return null;
+    }
+    return decodeText(bytes);
+}
+export function encodeInteger(value) {
+    return encodeText(String(value));
+}
+export function decodeInteger(bytes) {
+    const decoded = Number.parseInt(decodeText(bytes), 10);
+    if (!Number.isSafeInteger(decoded)) {
+        throw new Error("sqlite_meta_integer_invalid");
+    }
+    return decoded;
+}

package/dist/cli/commands/follow.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "../types.js";
+export declare function runFollowCommand(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<number>;

package/dist/cli/commands/follow.js

@@ -0,0 +1,43 @@
+import { dirname } from "node:path";
+import { usesTtyProgress, writeLine } from "../io.js";
+import { classifyCliError } from "../output.js";
+import { createStopSignalWatcher } from "../signals.js";
+export async function runFollowCommand(parsed, context) {
+    const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
+    const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
+    await context.ensureDirectory(dirname(dbPath));
+    const store = await context.openSqliteStore({ filename: dbPath });
+    let storeOwned = true;
+    try {
+        const client = await context.openManagedBitcoindClient({
+            store,
+            databasePath: dbPath,
+            dataDir,
+            progressOutput: parsed.progressOutput,
+        });
+        storeOwned = false;
+        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit);
+        try {
+            await client.startFollowingTip();
+            if (!usesTtyProgress(parsed.progressOutput, context.stderr)) {
+                writeLine(context.stdout, "Following managed Cogcoin tip. Press Ctrl-C to stop.");
+            }
+            return await stopWatcher.promise;
+        }
+        catch (error) {
+            writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
+            await client.close().catch(() => undefined);
+            return classifyCliError(error).exitCode;
+        }
+        finally {
+            stopWatcher.cleanup();
+        }
+    }
+    catch (error) {
+        writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
+        if (storeOwned) {
+            await store.close().catch(() => undefined);
+        }
+        return classifyCliError(error).exitCode;
+    }
+}

package/dist/cli/commands/mining-admin.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "../types.js";
+export declare function runMiningAdminCommand(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<number>;

package/dist/cli/commands/mining-admin.js

@@ -0,0 +1,92 @@
+import { buildHooksDisableMiningData, buildHooksEnableMiningData, buildMineSetupData, } from "../mining-json.js";
+import { buildHooksPreviewData } from "../preview-json.js";
+import { writeLine } from "../io.js";
+import { createTerminalPrompter } from "../prompt.js";
+import { createPreviewSuccessEnvelope, createMutationSuccessEnvelope, describeCanonicalCommand, resolvePreviewJsonSchema, resolveStableMiningControlJsonSchema, writeHandledCliError, writeJsonValue, } from "../output.js";
+import { formatNextStepLines, getHooksEnableMiningNextSteps, getMineSetupNextSteps, } from "../workflow-hints.js";
+function createCommandPrompter(parsed, context) {
+    return parsed.outputMode !== "text"
+        ? createTerminalPrompter(context.stdin, context.stderr)
+        : context.createPrompter();
+}
+export async function runMiningAdminCommand(parsed, context) {
+    try {
+        const provider = context.walletSecretProvider;
+        if (parsed.command === "hooks-mining-enable") {
+            const prompter = createCommandPrompter(parsed, context);
+            const view = await context.enableMiningHooks({
+                provider,
+                prompter,
+            });
+            const nextSteps = getHooksEnableMiningNextSteps();
+            if (parsed.outputMode === "preview-json") {
+                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "enabled", buildHooksPreviewData("hooks-enable-mining", view), {
+                    nextSteps,
+                }));
+                return 0;
+            }
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMiningControlJsonSchema(parsed), "cogcoin hooks enable mining", "enabled", buildHooksEnableMiningData(view), {
+                    nextSteps,
+                }));
+                return 0;
+            }
+            writeLine(context.stdout, "Custom mining hook enabled.");
+            for (const line of formatNextStepLines(nextSteps)) {
+                writeLine(context.stdout, line);
+            }
+            return 0;
+        }
+        if (parsed.command === "hooks-mining-disable") {
+            const view = await context.disableMiningHooks({
+                provider,
+            });
+            if (parsed.outputMode === "preview-json") {
+                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "disabled", buildHooksPreviewData("hooks-disable-mining", view)));
+                return 0;
+            }
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMiningControlJsonSchema(parsed), "cogcoin hooks disable mining", "disabled", buildHooksDisableMiningData(view)));
+                return 0;
+            }
+            writeLine(context.stdout, "Mining hooks switched back to builtin mode.");
+            return 0;
+        }
+        if (parsed.command === "mine-setup") {
+            const prompter = createCommandPrompter(parsed, context);
+            const view = await context.setupBuiltInMining({
+                provider,
+                prompter,
+            });
+            const nextSteps = getMineSetupNextSteps();
+            if (parsed.outputMode === "preview-json") {
+                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "configured", buildHooksPreviewData("mine-setup", view), {
+                    nextSteps,
+                }));
+                return 0;
+            }
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMiningControlJsonSchema(parsed), "cogcoin mine setup", "configured", buildMineSetupData(view), {
+                    nextSteps,
+                }));
+                return 0;
+            }
+            writeLine(context.stdout, "Built-in mining provider configured.");
+            writeLine(context.stdout, `Provider: ${view.provider.provider ?? "unknown"}`);
+            for (const line of formatNextStepLines(nextSteps)) {
+                writeLine(context.stdout, line);
+            }
+            return 0;
+        }
+        writeLine(context.stderr, `mining admin command not implemented: ${parsed.command}`);
+        return 1;
+    }
+    catch (error) {
+        return writeHandledCliError({
+            parsed,
+            stdout: context.stdout,
+            stderr: context.stderr,
+            error,
+        });
+    }
+}

package/dist/cli/commands/mining-read.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "../types.js";
+export declare function runMiningReadCommand(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<number>;