@toon-protocol/hub 0.34.3

package/dist/chunk-MNVIN5XK.js

@@ -0,0 +1,125 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+
+// src/constants.ts
+var CONTAINER_PREFIX = "townhouse-";
+var NODE_BTP_PORT = 3e3;
+var DEFAULT_CONNECTOR_IMAGE = (
+  // v3.10.4 — connector#137 (non-EVM inbound claim validator: Solana Ed25519 /
+  // Mina verification wired to the BTP server) + connector#136 (dynamic-HS-peer
+  // settlement: peerIdToChainMap populated via registerPeerChain), closing
+  // toon#213 and unblocking Solana + Mina pay-to-write for dynamic HS apexes.
+  // Validated live: bumping a running apex 3.10.3→3.10.4 made dynamic-HS Solana
+  // and Mina on-chain settlement work end-to-end. Builds on:
+  // v3.10.3 — connector#133 Mina claimFromChannel balance-conservation fix
+  // (#134 + #135 test follow-up). For an inbound unidirectional Mina claim the
+  // provider built the co-signed claim with balanceB=0, but the on-chain
+  // PaymentChannel.claimFromChannel circuit asserts balanceA + balanceB ==
+  // depositTotal and verifies both signatures over Poseidon([balanceA,balanceB,
+  // salt]); balanceB=0 violated conservation → PROOF_GENERATION_FAILED before any
+  // tx. 3.10.2 derives balanceB = depositTotal − balanceA from the public
+  // on-chain depositTotal (3.10.3 hardens the integration tests). This is the
+  // connector half of the LAST Mina publish-settle blocker (#158): with it +
+  // the client conserved-balanceB signing fix, a Mina-settled publish drives
+  // claimFromChannel to an on-chain landing (nonceField 0→1, proven live).
+  // Patch bump — no SDK/admin contract change vs 3.10.1; bumped because townhouse
+  // needs the conservation-correct settle behavior (CONNECTOR_RELEASE_CONTRACT.md
+  // patch-bump exception).
+  // v3.10.1 — connector#132 settlement claim-chain routing fix. The
+  // settlement-executor was routing Solana/Mina settle by a stale EVM channel
+  // instead of by the claim's own chain, so non-EVM publish-settle mis-routed
+  // to the EVM path. 3.10.1 selects the settlement chain from the inbound
+  // claim's `blockchain` (claim-driven) with guards. This is the connector half
+  // of #159 (Solana publish-settle proven on-chain; unblocks the Mina #158 /
+  // mill #157 town-side fixes for end-to-end validation). Patch bump — no
+  // SDK/admin contract change vs 3.10.0; bumped because townhouse needs the
+  // fixed (non-EVM-misrouting) settlement behavior per
+  // CONNECTOR_RELEASE_CONTRACT.md's patch-bump exception.
+  // v3.10.0 — Story 34.4 fund-custody zkApp bundle (#130/#131, closes #134). The
+  // connector now bundles the Story 34.4 `PaymentChannel` zkApp (FUND CUSTODY on
+  // deposit + FUND DISTRIBUTION on settle: the zkApp account escrows the deposit
+  // and `settle()` drains balanceB→participantB / balanceA→participantA). Its
+  // compiled verification key is byte-identical to the zkApp our harness deploys
+  // (VK hash 21482326729342759163995140331524541410906862862696135294081643945442581537217),
+  // so connector-driven `claimFromChannel`/`settle` proofs verify against the
+  // deployed contract. Minor bump; SDK/admin contract unchanged within 3.x.
+  // v3.9.13 — #128 openChannel deploy/initialize split. The zkApp openChannel
+  // path was combining contract deploy + initialize into one tx; 3.9.13 splits
+  // them so the on-chain channel opens cleanly.
+  // v3.9.12 — #126 zkApp tx fee + balance conservation. The apex's
+  // `claimFromChannel` settlement tx was broadcast with NO fee (failed at
+  // `Insufficient fee`); 3.9.12 sets the zkApp tx fee AND guards balance
+  // conservation (rejects a claim whose transferred amount would violate
+  // deposit-total conservation). Together with 3.9.13 the on-chain Mina
+  // claimFromChannel tx broadcasts and LANDS (zkApp nonce/balanceCommitment
+  // advance) — completing the non-EVM pay-to-write settle loop.
+  // v3.9.11 — #123 apex co-signs signatureB. `claimFromChannel` previously
+  // reused the client's signatureA as signatureB, so the on-chain dual-party
+  // verification reverted at `participant B signature verification failed`. With
+  // 3.9.11 the connector co-signs signatureB with the apex Mina key, so both
+  // signature checks pass and the on-chain Mina claimFromChannel tx lands
+  // (zkApp nonce/balanceCommitment advance). This was the LAST Mina blocker.
+  // v3.9.10 — #121 claimFromChannel signatureA wrapper. `claimFromChannel` now
+  // accepts the `signBalanceProof` wrapper ({commitment,signature:{r,s},...}) as
+  // `signatureA` (was: INVALID_PARAMETERS "Invalid signatureA" — wrapper vs bare
+  // {r,s} mismatch threw before any tx). This is the LAST Mina settle blocker:
+  // with it the connector submits the on-chain Mina claimFromChannel tx and the
+  // zkApp nonce/balanceCommitment advance.
+  // v3.9.9 — #118 advancing-claims acceptance in verifyBalanceProof. Resolves the
+  // nonce tension that blocked the Mina settle leg: the claim nonce was required to
+  // EQUAL the on-chain nonce, but `claimFromChannel` needs the claim to ADVANCE the
+  // channel (nonce > on-chain). 3.9.9 makes verifyBalanceProof accept advancing
+  // claims, so the connector can auto-drive `claimFromChannel` on a Mina publish.
+  // v3.9.8 — #117 Mina settlement-trigger fix. `CLAIM_RECEIVED` now emits the real
+  // `transferredAmount` (was hardcoded `BigInt(0)`), so the settlement-threshold
+  // check actually fires for Mina, triggering claimFromChannel().
+  // Together 3.9.8 + 3.9.9 complete the connector-driven on-chain Mina settle.
+  // v3.9.7 — #114 inbound Mina claimFromChannel + #84 dual-party. Enables the
+  // on-chain `claimFromChannel` for externally-opened (inbound) channels, fixing
+  // the `_participantCache` miss (ACCOUNT_NOT_FOUND) + off-chain/on-chain
+  // proof-message mismatch that blocked the Mina settle leg in 3.9.6; also closes
+  // #98/#84 (dual-party). This completes the full non-EVM on-chain settle
+  // (CLAIM_FROM_CHANNEL + SETTLE_CHANNEL) for BOTH Solana and Mina.
+  // Builds on the 3.9.6 chain:
+  //   #94 (3.9.4) — Solana Ed25519 precompile / on-chain message reconstruction.
+  //   #95 (3.9.4) — Mina getChannelState missing setActiveInstance.
+  //   #98 (3.9.5) — Mina balance-proof commitment was compared against the zkApp
+  //                 address; fixed to compare the on-chain `balanceCommitment`.
+  //   #99 (3.9.5) — Solana CLAIM_FROM_CHANNEL fee-payer decoupled from the claiming
+  //                 participant so the connector can unilaterally redeem a
+  //                 peer-signed inbound claim.
+  //   3.9.6 — connector-CI fix only (no runtime change vs 3.9.5).
+  //   #114 (3.9.7) — on-chain claimFromChannel enabled for inbound channels.
+  // Builds on 3.9.3's Solana settle-executor channel-lookup fix (#92), 3.9.2's Mina
+  // settlement-side proof-encoding fix (#90), 3.9.1's #88 fix (SettlementExecutor
+  // resolves the settlement chain for dynamic anonymous HS peers), and 3.9.1's
+  // blockchain-typed inbound claim validation (validateClaimMessage switches on
+  // claim.blockchain → validateEVMClaim / validateSolanaClaim / validateMinaClaim).
+  // validateSolanaClaim accepts { blockchain:'solana', programId, channelAccount
+  // (base58), nonce, transferredAmount, signature, signerPublicKey (base58),
+  // cluster? }. No breaking changes to the SDK/admin contract within 3.x (verified
+  // >=3.3.2 through 3.10.3 — see packages/sdk/CONNECTOR_MIGRATION.md). Digest
+  // resolved via `docker buildx imagetools inspect` for tag 3.10.3 (manifest-index
+  // digest). To bump: see CONNECTOR_RELEASE_CONTRACT.md.
+  "ghcr.io/toon-protocol/connector@sha256:48d2160e4479aae068ebd8b735a0a063995f1f2f17308c847f3a9b6cc57b1de4"
+);
+var ACCOUNT_INDEX_TOWN = 0;
+var ACCOUNT_INDEX_MILL = 1;
+var ACCOUNT_INDEX_DVM = 2;
+var ACCOUNT_INDEX_APEX = 3;
+var TOWN_HEALTH_PORT = 3100;
+var MILL_HEALTH_PORT = 3200;
+var DVM_HEALTH_PORT = 3400;
+
+export {
+  CONTAINER_PREFIX,
+  NODE_BTP_PORT,
+  DEFAULT_CONNECTOR_IMAGE,
+  ACCOUNT_INDEX_TOWN,
+  ACCOUNT_INDEX_MILL,
+  ACCOUNT_INDEX_DVM,
+  ACCOUNT_INDEX_APEX,
+  TOWN_HEALTH_PORT,
+  MILL_HEALTH_PORT,
+  DVM_HEALTH_PORT
+};
+//# sourceMappingURL=chunk-MNVIN5XK.js.map

package/dist/chunk-MNVIN5XK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Shared constants for Townhouse package.\n *\n * Single source of truth for values used across multiple modules\n * (orchestrator, config-generator, CLI).\n */\n\n/** Container name prefix for all Townhouse-managed Docker containers */\nexport const CONTAINER_PREFIX = 'townhouse-';\n\n/** Internal BTP port exposed by node containers (Docker-internal only) */\nexport const NODE_BTP_PORT = 3000;\n\n/**\n * Default connector Docker image — digest-pinned per CONNECTOR_RELEASE_CONTRACT.md.\n *\n * To bump: capture a new digest by running the Story 45.1 publish workflow\n * against the desired connector tag, copy the resulting image-manifest.json\n * connector entry's digest, and update this constant + the contract canary\n * fixture. See packages/sdk/CONNECTOR_RELEASE_CONTRACT.md for the full bump\n * checklist + breaking-changes history.\n *\n * To read the human-readable tag for log output, consult dist/image-manifest.json:\n *   manifest.images.connector.tag\n */\nexport const DEFAULT_CONNECTOR_IMAGE =\n  // v3.10.4 — connector#137 (non-EVM inbound claim validator: Solana Ed25519 /\n  // Mina verification wired to the BTP server) + connector#136 (dynamic-HS-peer\n  // settlement: peerIdToChainMap populated via registerPeerChain), closing\n  // toon#213 and unblocking Solana + Mina pay-to-write for dynamic HS apexes.\n  // Validated live: bumping a running apex 3.10.3→3.10.4 made dynamic-HS Solana\n  // and Mina on-chain settlement work end-to-end. Builds on:\n  // v3.10.3 — connector#133 Mina claimFromChannel balance-conservation fix\n  // (#134 + #135 test follow-up). For an inbound unidirectional Mina claim the\n  // provider built the co-signed claim with balanceB=0, but the on-chain\n  // PaymentChannel.claimFromChannel circuit asserts balanceA + balanceB ==\n  // depositTotal and verifies both signatures over Poseidon([balanceA,balanceB,\n  // salt]); balanceB=0 violated conservation → PROOF_GENERATION_FAILED before any\n  // tx. 3.10.2 derives balanceB = depositTotal − balanceA from the public\n  // on-chain depositTotal (3.10.3 hardens the integration tests). This is the\n  // connector half of the LAST Mina publish-settle blocker (#158): with it +\n  // the client conserved-balanceB signing fix, a Mina-settled publish drives\n  // claimFromChannel to an on-chain landing (nonceField 0→1, proven live).\n  // Patch bump — no SDK/admin contract change vs 3.10.1; bumped because townhouse\n  // needs the conservation-correct settle behavior (CONNECTOR_RELEASE_CONTRACT.md\n  // patch-bump exception).\n  // v3.10.1 — connector#132 settlement claim-chain routing fix. The\n  // settlement-executor was routing Solana/Mina settle by a stale EVM channel\n  // instead of by the claim's own chain, so non-EVM publish-settle mis-routed\n  // to the EVM path. 3.10.1 selects the settlement chain from the inbound\n  // claim's `blockchain` (claim-driven) with guards. This is the connector half\n  // of #159 (Solana publish-settle proven on-chain; unblocks the Mina #158 /\n  // mill #157 town-side fixes for end-to-end validation). Patch bump — no\n  // SDK/admin contract change vs 3.10.0; bumped because townhouse needs the\n  // fixed (non-EVM-misrouting) settlement behavior per\n  // CONNECTOR_RELEASE_CONTRACT.md's patch-bump exception.\n  // v3.10.0 — Story 34.4 fund-custody zkApp bundle (#130/#131, closes #134). The\n  // connector now bundles the Story 34.4 `PaymentChannel` zkApp (FUND CUSTODY on\n  // deposit + FUND DISTRIBUTION on settle: the zkApp account escrows the deposit\n  // and `settle()` drains balanceB→participantB / balanceA→participantA). Its\n  // compiled verification key is byte-identical to the zkApp our harness deploys\n  // (VK hash 21482326729342759163995140331524541410906862862696135294081643945442581537217),\n  // so connector-driven `claimFromChannel`/`settle` proofs verify against the\n  // deployed contract. Minor bump; SDK/admin contract unchanged within 3.x.\n  // v3.9.13 — #128 openChannel deploy/initialize split. The zkApp openChannel\n  // path was combining contract deploy + initialize into one tx; 3.9.13 splits\n  // them so the on-chain channel opens cleanly.\n  // v3.9.12 — #126 zkApp tx fee + balance conservation. The apex's\n  // `claimFromChannel` settlement tx was broadcast with NO fee (failed at\n  // `Insufficient fee`); 3.9.12 sets the zkApp tx fee AND guards balance\n  // conservation (rejects a claim whose transferred amount would violate\n  // deposit-total conservation). Together with 3.9.13 the on-chain Mina\n  // claimFromChannel tx broadcasts and LANDS (zkApp nonce/balanceCommitment\n  // advance) — completing the non-EVM pay-to-write settle loop.\n  // v3.9.11 — #123 apex co-signs signatureB. `claimFromChannel` previously\n  // reused the client's signatureA as signatureB, so the on-chain dual-party\n  // verification reverted at `participant B signature verification failed`. With\n  // 3.9.11 the connector co-signs signatureB with the apex Mina key, so both\n  // signature checks pass and the on-chain Mina claimFromChannel tx lands\n  // (zkApp nonce/balanceCommitment advance). This was the LAST Mina blocker.\n  // v3.9.10 — #121 claimFromChannel signatureA wrapper. `claimFromChannel` now\n  // accepts the `signBalanceProof` wrapper ({commitment,signature:{r,s},...}) as\n  // `signatureA` (was: INVALID_PARAMETERS \"Invalid signatureA\" — wrapper vs bare\n  // {r,s} mismatch threw before any tx). This is the LAST Mina settle blocker:\n  // with it the connector submits the on-chain Mina claimFromChannel tx and the\n  // zkApp nonce/balanceCommitment advance.\n  // v3.9.9 — #118 advancing-claims acceptance in verifyBalanceProof. Resolves the\n  // nonce tension that blocked the Mina settle leg: the claim nonce was required to\n  // EQUAL the on-chain nonce, but `claimFromChannel` needs the claim to ADVANCE the\n  // channel (nonce > on-chain). 3.9.9 makes verifyBalanceProof accept advancing\n  // claims, so the connector can auto-drive `claimFromChannel` on a Mina publish.\n  // v3.9.8 — #117 Mina settlement-trigger fix. `CLAIM_RECEIVED` now emits the real\n  // `transferredAmount` (was hardcoded `BigInt(0)`), so the settlement-threshold\n  // check actually fires for Mina, triggering claimFromChannel().\n  // Together 3.9.8 + 3.9.9 complete the connector-driven on-chain Mina settle.\n  // v3.9.7 — #114 inbound Mina claimFromChannel + #84 dual-party. Enables the\n  // on-chain `claimFromChannel` for externally-opened (inbound) channels, fixing\n  // the `_participantCache` miss (ACCOUNT_NOT_FOUND) + off-chain/on-chain\n  // proof-message mismatch that blocked the Mina settle leg in 3.9.6; also closes\n  // #98/#84 (dual-party). This completes the full non-EVM on-chain settle\n  // (CLAIM_FROM_CHANNEL + SETTLE_CHANNEL) for BOTH Solana and Mina.\n  // Builds on the 3.9.6 chain:\n  //   #94 (3.9.4) — Solana Ed25519 precompile / on-chain message reconstruction.\n  //   #95 (3.9.4) — Mina getChannelState missing setActiveInstance.\n  //   #98 (3.9.5) — Mina balance-proof commitment was compared against the zkApp\n  //                 address; fixed to compare the on-chain `balanceCommitment`.\n  //   #99 (3.9.5) — Solana CLAIM_FROM_CHANNEL fee-payer decoupled from the claiming\n  //                 participant so the connector can unilaterally redeem a\n  //                 peer-signed inbound claim.\n  //   3.9.6 — connector-CI fix only (no runtime change vs 3.9.5).\n  //   #114 (3.9.7) — on-chain claimFromChannel enabled for inbound channels.\n  // Builds on 3.9.3's Solana settle-executor channel-lookup fix (#92), 3.9.2's Mina\n  // settlement-side proof-encoding fix (#90), 3.9.1's #88 fix (SettlementExecutor\n  // resolves the settlement chain for dynamic anonymous HS peers), and 3.9.1's\n  // blockchain-typed inbound claim validation (validateClaimMessage switches on\n  // claim.blockchain → validateEVMClaim / validateSolanaClaim / validateMinaClaim).\n  // validateSolanaClaim accepts { blockchain:'solana', programId, channelAccount\n  // (base58), nonce, transferredAmount, signature, signerPublicKey (base58),\n  // cluster? }. No breaking changes to the SDK/admin contract within 3.x (verified\n  // >=3.3.2 through 3.10.3 — see packages/sdk/CONNECTOR_MIGRATION.md). Digest\n  // resolved via `docker buildx imagetools inspect` for tag 3.10.3 (manifest-index\n  // digest). To bump: see CONNECTOR_RELEASE_CONTRACT.md.\n  'ghcr.io/toon-protocol/connector@sha256:48d2160e4479aae068ebd8b735a0a063995f1f2f17308c847f3a9b6cc57b1de4';\n\n/**\n * Human-readable connector tag for the digest pinned in DEFAULT_CONNECTOR_IMAGE.\n *\n * This is the machine-readable counterpart to the `@sha256:` digest above. It\n * MUST stay in lockstep with BOTH:\n *   1. the `@sha256:<digest>` in DEFAULT_CONNECTOR_IMAGE (above), and\n *   2. `env.CONNECTOR_VERSION_DEFAULT` in\n *      `.github/workflows/publish-townhouse-images.yml`.\n *\n * The `connector-version-alignment.test.ts` source-level guard asserts (1) the\n * workflow env equals this tag and (2) DEFAULT_CONNECTOR_IMAGE is well-formed,\n * so a human bumping one but not the other fails CI at PR time — BEFORE a\n * release. (PR #165 drifted constants.ts to 3.10.3 while leaving the workflow\n * env at 3.10.0, hard-failing preflight and silently breaking the v0.17.4 and\n * v0.17.5 publishes.) The live tag↔digest resolution stays in the workflow's\n * preflight job (`docker buildx imagetools inspect`); this constant only guards\n * the SOURCE-level human drift. When bumping the connector: update the digest\n * above, this tag, AND the workflow env together.\n */\nexport const DEFAULT_CONNECTOR_TAG = '3.10.4';\n\n/**\n * HD wallet account indices per node type (Story 21.4, D21-008).\n * BIP-44 paths: m/44'/{coin}'/ACCOUNT'/0/0\n */\nexport const ACCOUNT_INDEX_TOWN = 0;\nexport const ACCOUNT_INDEX_MILL = 1;\nexport const ACCOUNT_INDEX_DVM = 2;\n/**\n * Apex (connector) settlement account. The apex is the parent connector\n * (`g.townhouse`) that signs settlement claims; its key is derived from the\n * operator mnemonic at this index so the operator never has to supply a raw\n * settlement key. Index 3 continues the town/mill/dvm sequence (and matches the\n * dev convention where the apex is Anvil account[3], 0x90F79bf6…).\n */\nexport const ACCOUNT_INDEX_APEX = 3;\n\n/** BLS health port exposed by each node container type (internal Docker port). */\nexport const TOWN_HEALTH_PORT = 3100;\nexport const MILL_HEALTH_PORT = 3200;\nexport const DVM_HEALTH_PORT = 3400;\n"],"mappings":";;;AAQO,IAAM,mBAAmB;AAGzB,IAAM,gBAAgB;AActB,IAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiGX;AAAA;AA2BK,IAAM,qBAAqB;AAC3B,IAAM,qBAAqB;AAC3B,IAAM,oBAAoB;AAQ1B,IAAM,qBAAqB;AAG3B,IAAM,mBAAmB;AACzB,IAAM,mBAAmB;AACzB,IAAM,kBAAkB;","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import Docker from 'dockerode';
+import { W as WalletManager, D as DockerOrchestrator, T as TownhouseConfig, C as ComposeLoaderOptions, N as NodeType } from './orchestrator-dGq7CeaO.js';
+import 'node:events';
+import '@toon-protocol/core';
+
+/**
+ * Boot rebinder — recreate provisioned child node containers from nodes.yaml on
+ * `townhouse hs up`.
+ *
+ * `hs down` runs `docker compose down` (removing child containers) and `hs up`'s
+ * `orchestrator.up([])` only boots the apex (connector + townhouse-api). Without
+ * this, a restart leaves previously-added town/mill/dvm children stopped, and
+ * the BootReconciler would re-register peers pointing at containers that no
+ * longer exist. This module rebuilds each child's full env from the wallet +
+ * config and (re)starts it via `startNodeViaCompose`, which is idempotent:
+ *   - container already running with identical env → docker compose no-ops;
+ *   - config changed since last start (e.g. mill relays edited) → recreated.
+ * That second case is the "auto-rebind from config" behaviour: edit config.yaml,
+ * `hs up`, and the children pick up the change.
+ *
+ * Run this BEFORE the BootReconciler so containers exist when peers re-register.
+ * Every step is non-fatal — a failure to rebind one node is logged and the rest
+ * proceed; apex boot is never blocked.
+ */
+
+/** Minimal wallet surface the rebinder needs (keeps it test-stubbable). */
+type RebindWallet = Pick<WalletManager, 'deriveNodeKey' | 'getMnemonic' | 'getNodeKeys'>;
+/** Minimal orchestrator surface the rebinder needs. */
+type RebindOrchestrator = Pick<DockerOrchestrator, 'startNodeViaCompose'>;
+interface RebindDeps {
+    nodesYamlPath: string;
+    wallet: RebindWallet;
+    orchestrator: RebindOrchestrator;
+    config: TownhouseConfig;
+    /**
+     * Apex public BTP URL injected into the town's env so its kind:10032
+     * advertises a reachable endpoint (resolved by the caller from
+     * config/host.json — see resolvePublicBtpUrl). Omit for non-town or when the
+     * hostname isn't resolved yet (town falls back to its default).
+     */
+    publicBtpUrl?: string;
+    /**
+     * Public Nostr relay read URL injected into the town's env so its
+     * kind:10032 advertises where clients subscribe (resolved by the caller from
+     * config/host.json — see resolveRelayUrl). Omit for non-town / unexposed.
+     */
+    relayUrl?: string;
+    /** Optional progress sink (defaults to no-op). */
+    log?: (line: string) => void;
+}
+interface RebindSummary {
+    /** Node ids whose `startNodeViaCompose` was invoked successfully. */
+    started: string[];
+    /** Node ids deliberately not started, with the reason. */
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    /** Node ids whose rebind threw, with the error message. */
+    failed: {
+        id: string;
+        err: string;
+    }[];
+}
+
+/**
+ * Cross-platform browser opener for the wizard CLI command.
+ * Uses platform-native launchers; errors are non-fatal.
+ */
+interface BrowserOpener {
+    open(url: string): Promise<void>;
+}
+
+/**
+ * Port-collision preflight for `townhouse hs up` (Epic 49 Followup B).
+ *
+ * Detects host-port conflicts BEFORE handing off to Docker, so operators get
+ * an actionable error message instead of a cryptic mid-boot EADDRINUSE.
+ *
+ * Detection strategy (defense in depth):
+ *   1. Bind a transient TCP socket to 127.0.0.1:<port> and immediately close.
+ *      If bind throws EADDRINUSE, the port is occupied. Pure Node, no deps,
+ *      works on Linux/Mac/WSL — this is the source of truth.
+ *   2. If (1) flags a collision, ask Docker for the offending container's
+ *      name + compose project so the message can name a culprit. Best-effort
+ *      enrichment — Docker may be unreachable, in which case we still report
+ *      the port and suggest `lsof` for non-Docker processes.
+ */
+
+interface PortCollision {
+    /** The host port that is already bound. */
+    port: number;
+    /** Name of the Docker container holding the port (when known). */
+    containerName?: string;
+    /** Compose project the container belongs to (when known). */
+    composeProject?: string;
+    /** Container status string e.g. "Up 5 hours" (when known). */
+    status?: string;
+}
+
+/**
+ * CLI entrypoint for `@toon-protocol/hub` (Story 21.1).
+ *
+ * Subcommands: init, up, down, status, --help
+ *
+ * Usage:
+ *   townhouse init [--force]
+ *   townhouse up
+ *   townhouse down
+ *   townhouse status
+ */
+
+/**
+ * Error thrown when `main()` is invoked with `--help`. Callers (tests) can
+ * distinguish this from genuine failures; the top-level entrypoint catches
+ * it and exits 0.
+ */
+declare class CliHelpRequested extends Error {
+    constructor();
+}
+/**
+ * This package's version, read from its own package.json at runtime. Used by
+ * `townhouse --version` so tooling that shells out (e.g. @toon-protocol/
+ * townhouse-mcp's version-skew probe) has a real version to compare against.
+ * Resolves `../package.json` relative to the module — package root from
+ * `dist/cli.js`, and `packages/townhouse/package.json` under vitest/src.
+ */
+declare function readCliVersion(): string;
+/**
+ * Dependency-injection overrides for the `hs up` / `hs down` CLI path.
+ * Used by unit tests to stub out Docker, file I/O, and admin client.
+ */
+interface CliHsOverrides {
+    /** Override materializeComposeTemplate (avoids disk writes in tests). */
+    materializeComposeTemplate?: (profile: string, opts?: ComposeLoaderOptions) => {
+        composePath: string;
+        manifestPath: string;
+    };
+    /** Override the DockerOrchestrator constructor (avoids real Docker in tests). */
+    createOrchestrator?: (docker: Docker, config: TownhouseConfig, walletManager: WalletManager | undefined, options: {
+        profile: 'hs' | 'direct';
+        composePath: string;
+    }) => {
+        up: (profiles: NodeType[]) => Promise<void>;
+        down: () => Promise<void>;
+        on: (event: string, handler: (...args: unknown[]) => void) => unknown;
+        /**
+         * Pre-pull a single image ref (Epic 49 Followup D).
+         * Optional on the stub interface — when omitted on a real orchestrator,
+         * the cold-pull narration phase is skipped (silent degrade).
+         */
+        pullImage?: (image: string) => Promise<void>;
+        /**
+         * Start/recreate a child node container with the given env overlay. Used by
+         * the boot rebinder; optional on the stub so existing tests that don't
+         * provision children need not implement it.
+         */
+        startNodeViaCompose?: (type: NodeType, env: Record<string, string>) => Promise<void>;
+        /** Relay hidden-service sidecar lifecycle (HS-mode public relay reads). */
+        ensureRelaySidecar?: () => Promise<void>;
+        getRelayHsHostname?: (timeoutMs?: number) => Promise<string | null>;
+    };
+    /**
+     * Override the boot rebinder (auto-rebind of child containers on `hs up`).
+     * Tests inject a spy to assert wiring without touching Docker/the wallet.
+     * When omitted, the default calls the real `rebindChildContainers`.
+     */
+    rebindChildren?: (deps: RebindDeps) => Promise<RebindSummary>;
+    /** Override ConnectorAdminClient construction (avoids real HTTP in tests). */
+    createAdminClient?: (baseUrl: string, timeoutMs: number) => {
+        getHsHostname: () => Promise<{
+            hostname: string | null;
+            publishedAt: string | null;
+        }>;
+    };
+    /** Override `docker compose down -v` spawn for --rotate-keys (avoids real Docker). */
+    runComposeDown?: (composePath: string, withVolumes: boolean) => Promise<void>;
+    /**
+     * Override BootReconciler construction (Story 46.1). Tests inject a stub
+     * with a spied-on `reconcile()` to assert wiring without touching disk
+     * or the connector. When omitted, the default constructs a real
+     * `BootReconciler` against `~/.townhouse/{nodes.yaml,reconciler.log}`.
+     */
+    createReconciler?: (nodesYamlPath: string, reconcilerLogPath: string) => {
+        reconcile: () => Promise<void>;
+    };
+    /**
+     * Override the port-collision preflight check (Epic 49 Followup B).
+     * Default invokes `checkHsPortCollisions(docker)` from
+     * `./cli/preflight-ports.js`. Tests inject a stub that returns either
+     * `[]` (happy path) or a fabricated PortCollision[] (collision path) so
+     * the production socket-bind + Docker enrichment is not exercised in
+     * unit tests.
+     */
+    checkPortCollisions?: (docker: Docker) => Promise<PortCollision[]>;
+}
+/**
+ * Dependency-injection overrides for the `node add` / `node remove` / `node list` CLI path.
+ * Used by unit tests to stub `fetch` and the interactive confirmation prompt.
+ */
+interface CliNodeCommandOverrides {
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+    confirm?: (question: string) => Promise<boolean>;
+    apiUrl?: string;
+}
+declare function main(argv: string[], dockerInstance?: Docker, browserOpener?: BrowserOpener, hsOverrides?: CliHsOverrides, nodeCommandOverrides?: CliNodeCommandOverrides): Promise<void>;
+
+export { CliHelpRequested, type CliHsOverrides, type CliNodeCommandOverrides, main, readCliVersion };