@toon-protocol/townhouse 0.1.0-rc5 → 0.1.1

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import Docker from 'dockerode';
+import { C as ComposeLoaderOptions, T as TownhouseConfig, W as WalletManager, N as NodeType } from './manager-SsneW_Mj.js';
 
 /**
  * Cross-platform browser opener for the wizard CLI command.
@@ -9,6 +10,33 @@ 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/townhouse` (Story 21.1).
  *
@@ -29,10 +57,74 @@ interface BrowserOpener {
 declare class CliHelpRequested extends Error {
     constructor();
 }
+/**
+ * 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';
+        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>;
+    };
+    /** 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;
+}
 /**
  * Main CLI entry — exported for testability (same pattern as Mill CLI).
  * Accepts optional dockerode instance for dependency injection in tests.
+ * The optional `hsOverrides` bag is used by unit tests to stub out Docker,
+ * file I/O, and admin-client calls in the `hs up` / `hs down` path.
  */
-declare function main(argv: string[], dockerInstance?: Docker, browserOpener?: BrowserOpener): Promise<void>;
+declare function main(argv: string[], dockerInstance?: Docker, browserOpener?: BrowserOpener, hsOverrides?: CliHsOverrides, nodeCommandOverrides?: CliNodeCommandOverrides): Promise<void>;
 
-export { CliHelpRequested, main };
+export { CliHelpRequested, type CliHsOverrides, type CliNodeCommandOverrides, main };