@cogcoin/client 0.5.0

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

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

package/dist/cli/commands/wallet-read.js

@@ -0,0 +1,265 @@
+import { dirname } from "node:path";
+import { formatBalanceReport, formatDetailedWalletStatusReport, formatDomainReport, formatDomainsReport, formatFieldReport, formatFieldsReport, formatFundingAddressReport, formatIdentityListReport, formatLocksReport, } from "../wallet-format.js";
+import { writeLine } from "../io.js";
+import { findWalletDomain, listDomainFields } from "../../wallet/read/index.js";
+import { filterWalletDomains } from "../../wallet/read/index.js";
+import { createErrorEnvelope, createSuccessEnvelope, describeCanonicalCommand, normalizeListPage, writeJsonValue, } from "../output.js";
+import { buildAddressJson, buildBalanceJson, buildDomainsJson, buildFieldJson, buildFieldsJson, buildIdsJson, buildLocksJson, buildShowJson, buildWalletStatusJson, listFieldsForJson, listLocksForJson, } from "../read-json.js";
+import { formatNextStepLines, getAddressNextSteps, getFundingQuickstartGuidance, getIdsNextSteps, getLocksNextSteps, } from "../workflow-hints.js";
+function createUnknownPage(parsed, defaultLimit) {
+    return {
+        limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+        returned: 0,
+        truncated: false,
+        moreAvailable: null,
+        totalKnown: null,
+    };
+}
+function activeDomainFilters(parsed) {
+    const filters = [];
+    if (parsed.domainsAnchoredOnly) {
+        filters.push("--anchored");
+    }
+    if (parsed.domainsListedOnly) {
+        filters.push("--listed");
+    }
+    if (parsed.domainsMineableOnly) {
+        filters.push("--mineable");
+    }
+    return filters;
+}
+function emitJson(context, parsed, schema, result) {
+    writeJsonValue(context.stdout, createSuccessEnvelope(schema, describeCanonicalCommand(parsed), result.data, {
+        warnings: result.warnings,
+        explanations: result.explanations,
+        nextSteps: result.nextSteps,
+    }));
+    return 0;
+}
+export async function runWalletReadCommand(parsed, context) {
+    const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
+    const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
+    await context.ensureDirectory(dirname(dbPath));
+    const readContext = await context.openWalletReadContext({
+        dataDir,
+        databasePath: dbPath,
+        secretProvider: context.walletSecretProvider,
+    });
+    try {
+        switch (parsed.command) {
+            case "wallet-status":
+                if (parsed.outputMode === "json") {
+                    return emitJson(context, parsed, "cogcoin/wallet-status/v1", buildWalletStatusJson(readContext));
+                }
+                writeLine(context.stdout, formatDetailedWalletStatusReport(readContext));
+                return 0;
+            case "wallet-address":
+            case "address":
+                if (parsed.outputMode === "json") {
+                    return emitJson(context, parsed, "cogcoin/address/v1", buildAddressJson(readContext));
+                }
+                writeLine(context.stdout, formatFundingAddressReport(readContext));
+                if (readContext.model?.fundingIdentity?.address !== null && readContext.model?.fundingIdentity?.address !== undefined) {
+                    writeLine(context.stdout, `Quickstart: ${getFundingQuickstartGuidance()}`);
+                }
+                for (const line of formatNextStepLines(getAddressNextSteps(readContext, readContext.model?.fundingIdentity?.address ?? null))) {
+                    writeLine(context.stdout, line);
+                }
+                return 0;
+            case "wallet-ids":
+            case "ids": {
+                const defaultLimit = 100;
+                if (parsed.outputMode === "json") {
+                    if (readContext.model === null) {
+                        return emitJson(context, parsed, "cogcoin/ids/v1", buildIdsJson(readContext, createUnknownPage(parsed, defaultLimit), []));
+                    }
+                    const { items, page } = normalizeListPage(readContext.model.identities, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    return emitJson(context, parsed, "cogcoin/ids/v1", buildIdsJson(readContext, page, items));
+                }
+                writeLine(context.stdout, formatIdentityListReport(readContext, {
+                    limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+                    all: parsed.listAll,
+                }));
+                if (readContext.model !== null) {
+                    const { items } = normalizeListPage(readContext.model.identities, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    for (const line of formatNextStepLines(getIdsNextSteps(items))) {
+                        writeLine(context.stdout, line);
+                    }
+                }
+                return 0;
+            }
+            case "balance":
+            case "cog-balance":
+                if (parsed.outputMode === "json") {
+                    return emitJson(context, parsed, "cogcoin/balance/v1", buildBalanceJson(readContext));
+                }
+                writeLine(context.stdout, formatBalanceReport(readContext));
+                return 0;
+            case "locks":
+            case "cog-locks": {
+                const defaultLimit = 100;
+                if (parsed.outputMode === "json") {
+                    const locks = listLocksForJson(readContext, {
+                        claimableOnly: parsed.locksClaimableOnly,
+                        reclaimableOnly: parsed.locksReclaimableOnly,
+                    });
+                    if (locks === null) {
+                        return emitJson(context, parsed, "cogcoin/locks/v1", buildLocksJson(readContext, null, createUnknownPage(parsed, defaultLimit)));
+                    }
+                    const { items, page } = normalizeListPage(locks, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    return emitJson(context, parsed, "cogcoin/locks/v1", buildLocksJson(readContext, items, page));
+                }
+                writeLine(context.stdout, formatLocksReport(readContext, {
+                    claimableOnly: parsed.locksClaimableOnly,
+                    reclaimableOnly: parsed.locksReclaimableOnly,
+                    limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+                    all: parsed.listAll,
+                }));
+                const locks = listLocksForJson(readContext, {
+                    claimableOnly: parsed.locksClaimableOnly,
+                    reclaimableOnly: parsed.locksReclaimableOnly,
+                });
+                if (locks !== null) {
+                    const { items } = normalizeListPage(locks, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    for (const line of formatNextStepLines(getLocksNextSteps(items))) {
+                        writeLine(context.stdout, line);
+                    }
+                }
+                return 0;
+            }
+            case "domain-list":
+            case "domains": {
+                const defaultLimit = 100;
+                const filters = activeDomainFilters(parsed);
+                const domains = filterWalletDomains(readContext, {
+                    anchoredOnly: parsed.domainsAnchoredOnly,
+                    listedOnly: parsed.domainsListedOnly,
+                    mineableOnly: parsed.domainsMineableOnly,
+                });
+                if (parsed.outputMode === "json") {
+                    if (domains === null) {
+                        return emitJson(context, parsed, "cogcoin/domains/v1", buildDomainsJson(readContext, null, createUnknownPage(parsed, defaultLimit)));
+                    }
+                    const { items, page } = normalizeListPage(domains, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    return emitJson(context, parsed, "cogcoin/domains/v1", buildDomainsJson(readContext, items, page));
+                }
+                writeLine(context.stdout, formatDomainsReport(readContext, {
+                    limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+                    all: parsed.listAll,
+                    domains,
+                    activeFilters: filters,
+                }));
+                return 0;
+            }
+            case "domain-show":
+            case "show": {
+                const domainName = parsed.args[0];
+                const domain = findWalletDomain(readContext, domainName);
+                if (readContext.snapshot !== null && domain === null) {
+                    if (parsed.outputMode === "json") {
+                        writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/show/v1", describeCanonicalCommand(parsed), "not_found", "Domain not found."));
+                    }
+                    else {
+                        writeLine(context.stdout, formatDomainReport(readContext, domainName));
+                    }
+                    return 3;
+                }
+                if (parsed.outputMode === "json") {
+                    return emitJson(context, parsed, "cogcoin/show/v1", buildShowJson(readContext, domainName));
+                }
+                writeLine(context.stdout, formatDomainReport(readContext, parsed.args[0]));
+                return 0;
+            }
+            case "fields":
+            case "field-list": {
+                const defaultLimit = 100;
+                const domainName = parsed.args[0];
+                const fields = listFieldsForJson(readContext, domainName);
+                if (readContext.snapshot !== null && fields === null) {
+                    if (parsed.outputMode === "json") {
+                        writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/fields/v1", describeCanonicalCommand(parsed), "not_found", "Domain not found."));
+                    }
+                    else {
+                        writeLine(context.stdout, formatFieldsReport(readContext, domainName, {
+                            limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+                            all: parsed.listAll,
+                        }));
+                    }
+                    return 3;
+                }
+                if (parsed.outputMode === "json") {
+                    if (fields === null) {
+                        return emitJson(context, parsed, "cogcoin/fields/v1", buildFieldsJson(readContext, domainName, null, createUnknownPage(parsed, defaultLimit)));
+                    }
+                    const { items, page } = normalizeListPage(fields, {
+                        limit: parsed.listLimit,
+                        all: parsed.listAll,
+                        defaultLimit,
+                    });
+                    return emitJson(context, parsed, "cogcoin/fields/v1", buildFieldsJson(readContext, domainName, items, page));
+                }
+                writeLine(context.stdout, formatFieldsReport(readContext, domainName, {
+                    limit: parsed.listAll ? null : (parsed.listLimit ?? defaultLimit),
+                    all: parsed.listAll,
+                }));
+                return 0;
+            }
+            case "field":
+            case "field-show": {
+                const domainName = parsed.args[0];
+                const fieldName = parsed.args[1];
+                const domainFields = listDomainFields(readContext, domainName);
+                const field = domainFields?.find((entry) => entry.name === fieldName) ?? null;
+                if (readContext.snapshot !== null && domainFields === null) {
+                    if (parsed.outputMode === "json") {
+                        writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/field/v1", describeCanonicalCommand(parsed), "not_found", "Domain not found."));
+                    }
+                    else {
+                        writeLine(context.stdout, formatFieldReport(readContext, domainName, fieldName));
+                    }
+                    return 3;
+                }
+                if (readContext.snapshot !== null && domainFields !== null && field === null) {
+                    if (parsed.outputMode === "json") {
+                        writeJsonValue(context.stdout, createErrorEnvelope("cogcoin/field/v1", describeCanonicalCommand(parsed), "not_found", "Field not found."));
+                    }
+                    else {
+                        writeLine(context.stdout, formatFieldReport(readContext, domainName, fieldName));
+                    }
+                    return 3;
+                }
+                if (parsed.outputMode === "json") {
+                    return emitJson(context, parsed, "cogcoin/field/v1", buildFieldJson(readContext, domainName, fieldName));
+                }
+                writeLine(context.stdout, formatFieldReport(readContext, parsed.args[0], parsed.args[1]));
+                return 0;
+            }
+            default:
+                writeLine(context.stderr, `wallet read command not implemented: ${parsed.command}`);
+                return 5;
+        }
+    }
+    finally {
+        await readContext.close();
+    }
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,3 @@
+import type { CliRunnerContext, RequiredCliRunnerContext } from "./types.js";
+export declare function readPackageVersionFromDisk(): Promise<string>;
+export declare function createDefaultContext(overrides?: CliRunnerContext): RequiredCliRunnerContext;

package/dist/cli/context.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, } from "../app-paths.js";
+import { openManagedBitcoindClient } from "../bitcoind/index.js";
+import { inspectPassiveClientStatus } from "../passive-status.js";
+import { openSqliteStore } from "../sqlite/index.js";
+import { exportWallet, importWallet, initializeWallet, lockWallet, repairWallet, unlockWallet, } from "../wallet/lifecycle.js";
+import { openWalletReadContext } from "../wallet/read/index.js";
+import { disableMiningHooks, enableMiningHooks, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, } from "../wallet/mining/index.js";
+import { createLazyDefaultWalletSecretProvider } from "../wallet/state/provider.js";
+import { 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";
+import { createTerminalPrompter } from "./prompt.js";
+export async function readPackageVersionFromDisk() {
+    const raw = await readFile(new URL("../../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? "0.0.0";
+}
+export function createDefaultContext(overrides = {}) {
+    return {
+        stdout: overrides.stdout ?? process.stdout,
+        stderr: overrides.stderr ?? process.stderr,
+        stdin: overrides.stdin ?? process.stdin,
+        signalSource: overrides.signalSource ?? process,
+        forceExit: overrides.forceExit ?? ((code) => {
+            process.exit(code);
+        }),
+        openSqliteStore: overrides.openSqliteStore ?? openSqliteStore,
+        openManagedBitcoindClient: overrides.openManagedBitcoindClient ?? openManagedBitcoindClient,
+        inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,
+        openWalletReadContext: overrides.openWalletReadContext ?? openWalletReadContext,
+        initializeWallet: overrides.initializeWallet ?? initializeWallet,
+        exportWallet: overrides.exportWallet ?? exportWallet,
+        importWallet: overrides.importWallet ?? importWallet,
+        unlockWallet: overrides.unlockWallet ?? unlockWallet,
+        lockWallet: overrides.lockWallet ?? lockWallet,
+        registerDomain: overrides.registerDomain ?? registerDomain,
+        anchorDomain: overrides.anchorDomain ?? anchorDomain,
+        transferDomain: overrides.transferDomain ?? transferDomain,
+        sellDomain: overrides.sellDomain ?? sellDomain,
+        buyDomain: overrides.buyDomain ?? buyDomain,
+        sendCog: overrides.sendCog ?? sendCog,
+        claimCogLock: overrides.claimCogLock ?? claimCogLock,
+        reclaimCogLock: overrides.reclaimCogLock ?? reclaimCogLock,
+        lockCogToDomain: overrides.lockCogToDomain ?? lockCogToDomain,
+        setDomainEndpoint: overrides.setDomainEndpoint ?? setDomainEndpoint,
+        clearDomainEndpoint: overrides.clearDomainEndpoint ?? clearDomainEndpoint,
+        setDomainDelegate: overrides.setDomainDelegate ?? setDomainDelegate,
+        clearDomainDelegate: overrides.clearDomainDelegate ?? clearDomainDelegate,
+        setDomainMiner: overrides.setDomainMiner ?? setDomainMiner,
+        clearDomainMiner: overrides.clearDomainMiner ?? clearDomainMiner,
+        setDomainCanonical: overrides.setDomainCanonical ?? setDomainCanonical,
+        createField: overrides.createField ?? createField,
+        setField: overrides.setField ?? setField,
+        clearField: overrides.clearField ?? clearField,
+        giveReputation: overrides.giveReputation ?? giveReputation,
+        revokeReputation: overrides.revokeReputation ?? revokeReputation,
+        enableMiningHooks: overrides.enableMiningHooks ?? enableMiningHooks,
+        disableMiningHooks: overrides.disableMiningHooks ?? disableMiningHooks,
+        inspectMiningControlPlane: overrides.inspectMiningControlPlane ?? inspectMiningControlPlane,
+        runForegroundMining: overrides.runForegroundMining ?? runForegroundMining,
+        startBackgroundMining: overrides.startBackgroundMining ?? startBackgroundMining,
+        stopBackgroundMining: overrides.stopBackgroundMining ?? stopBackgroundMining,
+        setupBuiltInMining: overrides.setupBuiltInMining ?? setupBuiltInMining,
+        readMiningLog: overrides.readMiningLog ?? readMiningLog,
+        followMiningLog: overrides.followMiningLog ?? followMiningLog,
+        repairWallet: overrides.repairWallet ?? repairWallet,
+        walletSecretProvider: overrides.walletSecretProvider ?? createLazyDefaultWalletSecretProvider(),
+        createPrompter: overrides.createPrompter ?? (() => createTerminalPrompter(overrides.stdin ?? process.stdin, overrides.stdout ?? process.stdout)),
+        ensureDirectory: overrides.ensureDirectory ?? (async (path) => {
+            await mkdir(path, { recursive: true });
+        }),
+        readPackageVersion: overrides.readPackageVersion ?? readPackageVersionFromDisk,
+        resolveDefaultBitcoindDataDir: overrides.resolveDefaultBitcoindDataDir ?? resolveDefaultBitcoindDataDirForTesting,
+        resolveDefaultClientDatabasePath: overrides.resolveDefaultClientDatabasePath ?? resolveDefaultClientDatabasePathForTesting,
+    };
+}

package/dist/cli/io.d.ts

@@ -0,0 +1,3 @@
+import type { ProgressOutput, WritableLike } from "./types.js";
+export declare function writeLine(stream: WritableLike, line: string): void;
+export declare function usesTtyProgress(progressOutput: ProgressOutput, stream: WritableLike): boolean;

package/dist/cli/io.js

@@ -0,0 +1,12 @@
+export function writeLine(stream, line) {
+    stream.write(`${line}\n`);
+}
+export function usesTtyProgress(progressOutput, stream) {
+    if (progressOutput === "none") {
+        return false;
+    }
+    if (progressOutput === "tty") {
+        return true;
+    }
+    return stream.isTTY === true;
+}

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

@@ -0,0 +1,5 @@
+import type { MiningControlPlaneView, MiningEventRecord } from "../wallet/mining/index.js";
+export declare function formatMiningSummaryLine(mining: MiningControlPlaneView): string;
+export declare function formatHooksStatusReport(mining: MiningControlPlaneView): string;
+export declare function formatMineStatusReport(mining: MiningControlPlaneView): string;
+export declare function formatMiningEventRecord(event: MiningEventRecord): string;

package/dist/cli/mining-format.js

@@ -0,0 +1,156 @@
+function formatMaybeIso(unixMs) {
+    return unixMs === null ? "none" : new Date(unixMs).toISOString();
+}
+function formatIndexerTruthSource(source) {
+    switch (source) {
+        case "lease":
+            return "coherent snapshot lease";
+        case "probe":
+            return "live daemon probe";
+        case "status-file":
+            return "advisory status file";
+        default:
+            return "none";
+    }
+}
+export function formatMiningSummaryLine(mining) {
+    const hookMode = mining.hook.mode === "unavailable" ? "unavailable" : mining.hook.mode;
+    const provider = mining.provider.configured
+        ? `${mining.provider.provider} configured`
+        : mining.provider.status === "error"
+            ? "config unavailable"
+            : "not configured";
+    const suffix = mining.runtime.miningState === "repair-required"
+        ? "  next repair"
+        : mining.runtime.miningState === "paused-stale"
+            ? "  next wait-or-rerun"
+            : mining.runtime.miningState === "paused" && mining.runtime.liveMiningFamilyInMempool
+                ? "  next wait-or-rerun"
+                : mining.runtime.pauseReason === "zero-reward"
+                    ? "  zero-reward"
+                    : "";
+    return `${mining.runtime.runMode} / ${mining.runtime.miningState} / ${mining.runtime.currentPhase}  hooks ${hookMode} (${mining.hook.operatorValidationState})  provider ${provider}${suffix}`;
+}
+export function formatHooksStatusReport(mining) {
+    const lines = ["Mining Hook Status"];
+    lines.push(`Mode: ${mining.hook.mode}`);
+    lines.push(`Entrypoint: ${mining.hook.entrypointPath}`);
+    lines.push(`Entrypoint present: ${mining.hook.entrypointExists ? "yes" : "no"}`);
+    lines.push(`Package: ${mining.hook.packageStatus}`);
+    if (mining.hook.packageMessage !== null) {
+        lines.push(`Package note: ${mining.hook.packageMessage}`);
+    }
+    lines.push(`Trust: ${mining.hook.trustStatus}`);
+    if (mining.hook.trustMessage !== null) {
+        lines.push(`Trust note: ${mining.hook.trustMessage}`);
+    }
+    lines.push(`Validation: ${mining.hook.operatorValidationState}`);
+    if (mining.hook.validationError !== null) {
+        lines.push(`Validation note: ${mining.hook.validationError}`);
+    }
+    lines.push(`Validated at: ${formatMaybeIso(mining.hook.validatedAtUnixMs)}`);
+    lines.push(`Launch fingerprint: ${mining.hook.currentLaunchFingerprint ?? "unavailable"}`);
+    lines.push(`Validated launch fingerprint: ${mining.hook.validatedLaunchFingerprint ?? "none"}`);
+    lines.push(`Full fingerprint: ${mining.hook.currentFullFingerprint ?? (mining.hook.verifyUsed ? "unavailable" : "not requested")}`);
+    lines.push(`Validated full fingerprint: ${mining.hook.validatedFullFingerprint ?? "none"}`);
+    lines.push(`Cooldown until: ${formatMaybeIso(mining.hook.cooldownUntilUnixMs)}`);
+    lines.push(`Cooldown active: ${mining.hook.cooldownActive ? "yes" : "no"}`);
+    lines.push(`Consecutive failures: ${mining.hook.consecutiveFailureCount}`);
+    return lines.join("\n");
+}
+export function formatMineStatusReport(mining) {
+    const lines = ["Mining Status"];
+    lines.push(`Run mode: ${mining.runtime.runMode}`);
+    lines.push(`Mining state: ${mining.runtime.miningState}`);
+    lines.push(`Current phase: ${mining.runtime.currentPhase}`);
+    if (mining.runtime.pauseReason !== null) {
+        lines.push(`Pause reason: ${mining.runtime.pauseReason}`);
+    }
+    if (mining.runtime.lastSuspendDetectedAtUnixMs !== null) {
+        lines.push(`Last suspend detected: ${formatMaybeIso(mining.runtime.lastSuspendDetectedAtUnixMs)}`);
+    }
+    lines.push(`Hook mode: ${mining.runtime.hookMode}`);
+    lines.push(`Hook validation: ${mining.hook.operatorValidationState}`);
+    lines.push(`Provider: ${mining.provider.configured ? `${mining.provider.provider} configured` : mining.provider.status}`);
+    if (mining.provider.message !== null) {
+        lines.push(`Provider note: ${mining.provider.message}`);
+    }
+    lines.push(`Provider runtime: ${mining.runtime.providerState ?? "unknown"}`);
+    lines.push(`Hook cooldown: ${mining.hook.cooldownActive ? "active" : "inactive"}`);
+    lines.push(`Managed bitcoind: ${mining.runtime.bitcoindHealth}`);
+    if (mining.runtime.bitcoindReplicaStatus !== null) {
+        lines.push(`Managed Core wallet: ${mining.runtime.bitcoindReplicaStatus}`);
+    }
+    lines.push(`Bitcoin service: ${mining.runtime.nodeHealth}`);
+    lines.push(`Indexer service: ${mining.runtime.indexerHealth}`);
+    lines.push(`Indexer truth source: ${formatIndexerTruthSource(mining.runtime.indexerTruthSource)}`);
+    if (mining.runtime.indexerDaemonInstanceId !== null) {
+        lines.push(`Indexer daemon instance: ${mining.runtime.indexerDaemonInstanceId}`);
+    }
+    if (mining.runtime.indexerSnapshotSeq !== null) {
+        lines.push(`Indexer snapshot sequence: ${mining.runtime.indexerSnapshotSeq}`);
+    }
+    if (mining.runtime.indexerReorgDepth !== null) {
+        lines.push(`Indexer reorg depth: ${mining.runtime.indexerReorgDepth}`);
+    }
+    lines.push(`Tip alignment: ${mining.runtime.tipsAligned === null ? "unknown" : mining.runtime.tipsAligned ? "aligned" : "misaligned"}`);
+    lines.push(`Core publishability: ${mining.runtime.corePublishState ?? "unknown"}`);
+    if (mining.runtime.backgroundWorkerPid !== null) {
+        lines.push(`Background worker: pid ${mining.runtime.backgroundWorkerPid} (${mining.runtime.backgroundWorkerHealth ?? "unknown"})`);
+    }
+    if (mining.runtime.currentDomainName !== null) {
+        lines.push(`Current domain: ${mining.runtime.currentDomainName}`);
+    }
+    if (mining.runtime.currentTxid !== null) {
+        lines.push(`Current txid: ${mining.runtime.currentTxid}`);
+    }
+    lines.push(`Publish state: ${mining.runtime.currentPublishState}`);
+    if (mining.runtime.currentPublishDecision !== null) {
+        lines.push(`Publish decision: ${mining.runtime.currentPublishDecision}`);
+    }
+    if (mining.runtime.sameDomainCompetitorSuppressed === true) {
+        lines.push("Competitiveness gate: suppressed by same-domain mempool incumbent");
+    }
+    else if (mining.runtime.competitivenessGateIndeterminate === true) {
+        lines.push("Competitiveness gate: indeterminate, so this tick was skipped safely");
+    }
+    else if (mining.runtime.higherRankedCompetitorDomainCount !== null) {
+        lines.push(`Higher-ranked competitor domains: ${mining.runtime.higherRankedCompetitorDomainCount}`);
+    }
+    if (mining.runtime.dedupedCompetitorDomainCount !== null) {
+        lines.push(`Deduped competitor domains: ${mining.runtime.dedupedCompetitorDomainCount}`);
+    }
+    if (mining.runtime.lastMempoolSequence !== null) {
+        lines.push(`Last mempool sequence: ${mining.runtime.lastMempoolSequence}`);
+    }
+    if (mining.runtime.mempoolSequenceCacheStatus !== null) {
+        lines.push(`Gate cache: ${mining.runtime.mempoolSequenceCacheStatus}`);
+    }
+    lines.push(`Last validation: ${formatMaybeIso(mining.runtime.lastValidationAtUnixMs)}`);
+    lines.push(`Last event: ${formatMaybeIso(mining.runtime.lastEventAtUnixMs)}`);
+    if (mining.runtime.lastError !== null) {
+        lines.push(`Last error: ${mining.runtime.lastError}`);
+    }
+    if (mining.runtime.note !== null) {
+        lines.push(`Note: ${mining.runtime.note}`);
+    }
+    if (mining.runtime.miningState === "repair-required") {
+        lines.push("Next: run `cogcoin repair` before mining again.");
+    }
+    else if (mining.runtime.pauseReason === "zero-reward") {
+        lines.push("Next: wait for the next positive-reward target height; mining resumes automatically.");
+    }
+    else if (mining.runtime.currentPhase === "resuming") {
+        lines.push("Next: wait for mining to finish rechecking health after the local runtime resumed.");
+    }
+    else if (mining.runtime.miningState === "paused-stale") {
+        lines.push("Next: wait for the live mempool family to confirm, or rerun mining after the tip settles.");
+    }
+    else if (mining.runtime.miningState === "paused" && mining.runtime.liveMiningFamilyInMempool) {
+        lines.push("Next: wait for the live mempool family to confirm, or rerun mining when you want replacements to resume.");
+    }
+    return lines.join("\n");
+}
+export function formatMiningEventRecord(event) {
+    return `${new Date(event.timestampUnixMs).toISOString()}  ${event.level.toUpperCase()}  ${event.kind}  ${event.message}`;
+}

package/dist/cli/mining-json.d.ts

@@ -0,0 +1,49 @@
+import type { MiningControlPlaneView, MiningRuntimeStatusV1 } from "../wallet/mining/index.js";
+export declare function buildHooksDisableMiningData(view: MiningControlPlaneView): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};
+export declare function buildHooksEnableMiningData(view: MiningControlPlaneView): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};
+export declare function buildMineSetupData(view: MiningControlPlaneView): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};
+export declare function buildMineStartData(result: {
+    started: boolean;
+    snapshot: MiningRuntimeStatusV1 | null;
+}): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};
+export declare function buildMineStopData(snapshot: MiningRuntimeStatusV1 | null): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};

package/dist/cli/mining-json.js

@@ -0,0 +1,89 @@
+import { buildStateChangeData } from "./mutation-json.js";
+function summarizeRuntime(snapshot) {
+    if (snapshot === null) {
+        return null;
+    }
+    return {
+        runMode: snapshot.runMode,
+        miningState: snapshot.miningState,
+        currentPhase: snapshot.currentPhase,
+        backgroundWorkerPid: snapshot.backgroundWorkerPid,
+        backgroundWorkerRunId: snapshot.backgroundWorkerRunId,
+        note: snapshot.note,
+    };
+}
+export function buildHooksDisableMiningData(view) {
+    return buildHooksStateChangeData("hooks-disable-mining", view);
+}
+export function buildHooksEnableMiningData(view) {
+    return buildHooksStateChangeData("hooks-enable-mining", view);
+}
+export function buildMineSetupData(view) {
+    const after = {
+        hook: {
+            mode: view.hook.mode,
+            validationState: view.hook.validationState,
+            operatorValidationState: view.hook.operatorValidationState,
+            validationError: view.hook.validationError,
+            cooldownActive: view.hook.cooldownActive,
+        },
+        provider: {
+            configured: view.provider.configured,
+            provider: view.provider.provider,
+            status: view.provider.status,
+            modelOverride: view.provider.modelOverride,
+            extraPromptConfigured: view.provider.extraPromptConfigured,
+        },
+        runtime: summarizeRuntime(view.runtime),
+    };
+    return buildStateChangeData({
+        kind: "mine-setup",
+        state: after,
+        after,
+    });
+}
+function buildHooksStateChangeData(kind, view) {
+    const after = {
+        hook: {
+            mode: view.hook.mode,
+            validationState: view.hook.validationState,
+            operatorValidationState: view.hook.operatorValidationState,
+            validationError: view.hook.validationError,
+            cooldownActive: view.hook.cooldownActive,
+        },
+        provider: {
+            configured: view.provider.configured,
+            provider: view.provider.provider,
+            status: view.provider.status,
+        },
+        runtime: summarizeRuntime(view.runtime),
+    };
+    return buildStateChangeData({
+        kind,
+        state: after,
+        after,
+    });
+}
+export function buildMineStartData(result) {
+    const after = {
+        started: result.started,
+        runtime: summarizeRuntime(result.snapshot),
+    };
+    return buildStateChangeData({
+        kind: "mine-start",
+        state: after,
+        after,
+    });
+}
+export function buildMineStopData(snapshot) {
+    const after = {
+        stopped: snapshot !== null,
+        runtime: summarizeRuntime(snapshot),
+        note: snapshot?.note ?? "Background mining was not active.",
+    };
+    return buildStateChangeData({
+        kind: "mine-stop",
+        state: after,
+        after,
+    });
+}