@cogcoin/client 0.5.2 → 0.5.4

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.2` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@0.5.4` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -32,6 +32,8 @@ npx cogcoin sync
 
 Verify the installed genesis artifacts before using the client in a production implementation.
 The installed package provides the `cogcoin` command for local wallet setup, sync, reads, writes, and mining workflows.
+Provider-backed local wallets unlock on demand by default; `cogcoin wallet lock` suppresses that behavior until `cogcoin unlock` is run again.
+Passphrase-wrapped wallet-state flows still require explicit passphrase-based access.
 
 ## Dependency Surface
 
@@ -72,13 +74,19 @@ Managed node subpath:
 
 The installed `cogcoin` command covers the first-party local wallet and node workflow:
 
-- wallet lifecycle commands such as `init`, `unlock`, `lock`, `repair`, `export`, and `import`
-- sync and service commands such as `status`, `sync`, and `follow`
+- wallet lifecycle commands such as `init`, `restore`, `unlock`, `lock`, `repair`, `export`, and `import`
+- sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
 - mining and hook commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, and `hooks status`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+Ordinary `sync`, `follow`, and wallet-aware read/status flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
+Use the explicit `bitcoin ...` and `indexer ...` commands when you want direct service inspection or start/stop control.
+For provider-backed local wallets, normal reads, mutations, export, and mining setup flows auto-materialize a local unlock session when the wallet is not explicitly locked.
+`cogcoin restore` and `cogcoin wallet restore` rebuild a fresh local wallet from a 24-word English BIP39 mnemonic and recreate the managed Core wallet replica.
+Run `cogcoin sync` afterward to bootstrap the managed Bitcoin/indexer state.
+`cogcoin wallet import <path>` remains the richer encrypted-archive restore path that preserves more local continuity metadata than mnemonic-only restore.
 
 ## SQLite Store
 
@@ -119,6 +127,9 @@ The managed `bitcoind` client also exposes:
 - `onProgress(event)` for structured bootstrap/sync progress updates
 - `progressOutput: "auto" | "tty" | "none"` for the built-in scroll-train terminal progress UI
 
+At the CLI layer, managed services are persistent until explicitly stopped.
+`cogcoin bitcoin start` starts managed `bitcoind`, `cogcoin bitcoin stop` stops managed `bitcoind` and the paired indexer, `cogcoin indexer start` starts the managed indexer and auto-starts `bitcoind` first when needed, and `cogcoin indexer stop` stops only the indexer.
+
 The default TTY progress renderer ships with the package and uses the bundled scroll, train, and quote assets from `dist/art/*` and `dist/writing_quotes.json`.
 
 ## Published Contents

package/dist/app-paths.d.ts

@@ -18,6 +18,7 @@ export interface CogcoinResolvedPaths {
     walletStatePath: string;
     walletStateBackupPath: string;
     walletUnlockSessionPath: string;
+    walletExplicitLockPath: string;
     walletControlLockPath: string;
     bitcoindLockPath: string;
     bitcoindStatusPath: string;

package/dist/app-paths.js

@@ -64,6 +64,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
     const walletStateBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc.bak");
     const walletUnlockSessionPath = joinForPlatform(platform, runtimeRoot, "wallet-unlock-session.enc");
+    const walletExplicitLockPath = joinForPlatform(platform, runtimeRoot, "wallet-explicit-lock.json");
     const walletControlLockPath = joinForPlatform(platform, runtimeRoot, "wallet-control.lock");
     const bitcoindLockPath = joinForPlatform(platform, runtimeRoot, "bitcoind.lock");
     const bitcoindStatusPath = joinForPlatform(platform, runtimeRoot, "bitcoind-status.json");
@@ -91,6 +92,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStatePath,
         walletStateBackupPath,
         walletUnlockSessionPath,
+        walletExplicitLockPath,
         walletControlLockPath,
         bitcoindLockPath,
         bitcoindStatusPath,

package/dist/art/wallet.txt

@@ -0,0 +1,10 @@
+                     ⛭ Write this down. Keep it secret, keep it safe. ⛭         
+▐▀▀▀▀▀▀▚    ╔──────────────────────────────────────────────────────────────────╗
+▛▞▀▀▀▀▀▀▚   │                                                                  │
+▌▝▀▀▀▀▀▀▀▌  │  1.achieved   6.achieved  11.achieved  16.achieved  21.achieved  │
+▌  ▗▙▙   ▌  │  2.achieved   7.achieved  12.achieved  17.achieved  22.achieved  │
+▌  ▐  ▌  ▌  │  3.achieved   8.achieved  13.achieved  18.achieved  23.achieved  │
+▌  ▐▀▀▚  ▌  │  4.achieved   9.achieved  14.achieved  19.achieved  24.achieved  │
+▌  ▐▄▄▞  ▌  │  5.achieved  10.achieved  15.achieved  20.achieved               │
+▌   ▘▘   ▌  │                                                                  │
+▝▀▀▀▀▀▀▀▀▘  ╚──────────────────────────────────────────────────────────────────╝

package/dist/bitcoind/indexer-daemon.d.ts

@@ -73,6 +73,10 @@ export interface IndexerDaemonProbeResult {
     client: IndexerDaemonClient | null;
     error: string | null;
 }
+export interface IndexerDaemonStopResult {
+    status: "stopped" | "not-running";
+    walletRootId: string;
+}
 export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
@@ -92,6 +96,11 @@ export declare function attachOrStartIndexerDaemon(options: {
     walletRootId?: string;
     startupTimeoutMs?: number;
 }): Promise<IndexerDaemonClient>;
+export declare function stopIndexerDaemonService(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<IndexerDaemonStopResult>;
 export declare function shutdownIndexerDaemonForTesting(options: {
     dataDir: string;
     walletRootId?: string;

package/dist/bitcoind/indexer-daemon.js

@@ -39,6 +39,20 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+async function waitForProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await sleep(50);
+    }
+    throw new Error(errorCode);
+}
+async function clearIndexerDaemonRuntimeArtifacts(paths) {
+    await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+}
 function createIndexerDaemonClient(socketPath) {
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
@@ -357,26 +371,49 @@ export async function attachOrStartIndexerDaemon(options) {
         throw error;
     }
 }
-export async function shutdownIndexerDaemonForTesting(options) {
+export async function stopIndexerDaemonService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.indexerDaemonStatusPath);
-    if (status?.processId !== null && status?.processId !== undefined) {
+    const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
+        purpose: "indexer-daemon-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
+    try {
+        const status = await readJsonFile(paths.indexerDaemonStatusPath);
+        const processId = status?.processId ?? null;
+        if (status === null || processId === null || !await isProcessAlive(processId)) {
+            await clearIndexerDaemonRuntimeArtifacts(paths);
+            return {
+                status: "not-running",
+                walletRootId,
+            };
+        }
         try {
-            process.kill(status.processId, "SIGTERM");
-            const deadline = Date.now() + 5_000;
-            while (Date.now() < deadline) {
-                if (!await isProcessAlive(status.processId)) {
-                    break;
-                }
-                await sleep(50);
-            }
+            process.kill(processId, "SIGTERM");
         }
-        catch {
-            // ignore stale pid cleanup failures
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
         }
+        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            status: "stopped",
+            walletRootId,
+        };
     }
-    await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    finally {
+        await lock.release();
+    }
+}
+export async function shutdownIndexerDaemonForTesting(options) {
+    await stopIndexerDaemonService(options).catch(async () => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    });
 }
 export async function readIndexerDaemonStatusForTesting(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;

package/dist/bitcoind/service.d.ts

@@ -25,11 +25,20 @@ export interface ManagedBitcoindServiceProbeResult {
     status: ManagedBitcoindObservedStatus | null;
     error: string | null;
 }
+export interface ManagedBitcoindServiceStopResult {
+    status: "stopped" | "not-running";
+    walletRootId: string;
+}
 export declare function createManagedWalletReplica(rpc: ManagedWalletReplicaRpc, walletRootId: string, options?: {
     managedWalletPassphrase?: string;
 }): Promise<ManagedCoreWalletReplicaStatus>;
 export declare function probeManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindServiceProbeResult>;
 export declare function attachOrStartManagedBitcoindService(options: ManagedBitcoindServiceOptions): Promise<ManagedBitcoindNodeHandle>;
+export declare function stopManagedBitcoindService(options: {
+    dataDir: string;
+    walletRootId?: string;
+    shutdownTimeoutMs?: number;
+}): Promise<ManagedBitcoindServiceStopResult>;
 export declare function readManagedBitcoindServiceStatusForTesting(dataDir: string, walletRootId?: string): Promise<ManagedBitcoindObservedStatus | null>;
 export declare function shutdownManagedBitcoindServiceForTesting(options: {
     dataDir: string;

package/dist/bitcoind/service.js

@@ -21,6 +21,16 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
+async function waitForProcessExit(pid, timeoutMs, errorCode) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await sleep(250);
+    }
+    throw new Error(errorCode);
+}
 function getWalletReplicaName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
@@ -488,6 +498,12 @@ async function writeBitcoindStatus(paths, status) {
         p2pPort: status.p2pPort,
     });
 }
+async function clearManagedBitcoindRuntimeArtifacts(paths) {
+    await rm(paths.bitcoindStatusPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindPidPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+    await rm(paths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
+}
 async function refreshManagedBitcoindStatus(status, paths, options) {
     const nowUnixMs = Date.now();
     const rpc = createRpcClient(status.rpc);
@@ -699,37 +715,62 @@ export async function attachOrStartManagedBitcoindService(options) {
         throw error;
     }
 }
-export async function readManagedBitcoindServiceStatusForTesting(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
-    const paths = resolveManagedServicePaths(dataDir, walletRootId);
-    return readJsonFile(paths.bitcoindStatusPath);
-}
-export async function shutdownManagedBitcoindServiceForTesting(options) {
+export async function stopManagedBitcoindService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.bitcoindStatusPath);
-    if (status === null) {
-        return;
-    }
-    const rpc = createRpcClient(status.rpc);
+    const lock = await acquireFileLock(paths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-stop",
+        walletRootId,
+        dataDir: options.dataDir,
+    });
     try {
-        await rpc.stop();
-    }
-    catch {
-        if (status.processId !== null) {
+        const status = await readJsonFile(paths.bitcoindStatusPath);
+        const processId = status?.processId ?? null;
+        if (status === null || processId === null || !await isProcessAlive(processId)) {
+            await clearManagedBitcoindRuntimeArtifacts(paths);
+            return {
+                status: "not-running",
+                walletRootId,
+            };
+        }
+        const rpc = createRpcClient(status.rpc);
+        try {
+            await rpc.stop();
+        }
+        catch {
             try {
-                process.kill(status.processId, "SIGTERM");
+                process.kill(processId, "SIGTERM");
             }
-            catch {
-                // ignore
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                    throw error;
+                }
             }
         }
+        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, "managed_bitcoind_service_stop_timeout");
+        await clearManagedBitcoindRuntimeArtifacts(paths);
+        return {
+            status: "stopped",
+            walletRootId,
+        };
     }
-    const deadline = Date.now() + (options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS);
-    while (Date.now() < deadline) {
-        if (!await isProcessAlive(status.processId)) {
-            break;
-        }
-        await sleep(250);
+    finally {
+        await lock.release();
     }
-    await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+}
+export async function readManagedBitcoindServiceStatusForTesting(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
+    const paths = resolveManagedServicePaths(dataDir, walletRootId);
+    return readJsonFile(paths.bitcoindStatusPath);
+}
+export async function shutdownManagedBitcoindServiceForTesting(options) {
+    await stopManagedBitcoindService({
+        dataDir: options.dataDir,
+        walletRootId: options.walletRootId,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+    }).catch(async (error) => {
+        const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+        const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
+        await rm(paths.bitcoindReadyPath, { force: true }).catch(() => undefined);
+        throw error;
+    });
 }

package/dist/bitcoind/testing.d.ts

@@ -1,8 +1,8 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
-export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, 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";

package/dist/bitcoind/testing.js

@@ -1,8 +1,8 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
-export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
+export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";
-export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, shutdownManagedBitcoindServiceForTesting, } from "./service.js";
+export { attachOrStartManagedBitcoindService, readManagedBitcoindServiceStatusForTesting, stopManagedBitcoindService, 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";

package/dist/cli/commands/service-runtime.d.ts

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