@celilo/cli 0.11.0 → 0.12.1

package/src/services/web-route-cleanup.ts

@@ -0,0 +1,144 @@
+/**
+ * Route cleanup on module removal — the consumer half of ISS-0035.
+ *
+ * `register_route` / `unregister_routes` emit `public_web.routes_changed`, and
+ * the provider's `reconcile_routes` subscription re-renders its config from
+ * `web_routes`. But `unregister_routes` is only reachable from a module's own
+ * `on_uninstall` teardown script, and most consumers don't define one —
+ * celilo-website, celilo-registry, celilo-apt-repo and celilo-mgmt all publish
+ * a site and have no teardown. For those, `module remove` deleted the route
+ * rows through the FK cascade on `modules.id` and emitted NOTHING, so the
+ * provider never learned the route was gone: the rendered Caddyfile kept a site
+ * block for a module that no longer exists, and `/srv/www/<slug>` was orphaned.
+ *
+ * The fix lives here rather than in each module's teardown script for the usual
+ * reason: one call site in `performModuleRemove` covers every consumer and
+ * can't be forgotten by the next one. Modules that DO define an `on_uninstall`
+ * calling `unregister_routes` still win — their hook runs first and this
+ * becomes a no-op (zero owned routes).
+ *
+ * Everything here is best-effort. A failed asset `rm` or an undelivered
+ * reconcile is reported as a warning, never a thrown error: a stuck provider is
+ * no reason to strand a module in a half-removed state.
+ */
+
+import { execRunner, runAppCommand, shellEscape } from '@celilo/capabilities';
+import type { Runner } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, webRoutes } from '../db/schema';
+import { loadHookConfigMap } from '../hooks/load-hook-config';
+import { emitWebRoutesChangedAndWait } from './celilo-events';
+
+export interface WebRouteCleanupResult {
+  routesRemoved: number;
+  /** Asset roots actually deleted from the provider host. */
+  assetDirsRemoved: string[];
+  /** Non-fatal problems, for the caller to log. Never thrown. */
+  warnings: string[];
+}
+
+export interface WebRouteCleanupDeps {
+  moduleId: string;
+  db: DbClient;
+  /** Injectable remote runner — tests pass a mock. */
+  run?: Runner;
+  /** Injectable event emit + wait — tests pass a stub. */
+  emitAndWait?: typeof emitWebRoutesChangedAndWait;
+}
+
+/**
+ * The provider host that owns `/srv/www` — the same `config.target_ip` the
+ * public_web capability uses for its asset uploads.
+ */
+async function resolvePublicWebHostIp(db: DbClient): Promise<string | undefined> {
+  const providers = db
+    .select()
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, 'public_web'))
+    .all();
+  const provider = providers[0];
+  if (!provider) return undefined;
+
+  const config = await loadHookConfigMap(provider.moduleId, db);
+  // target_ip may carry a CIDR suffix; the capability strips it the same way.
+  return String(config.target_ip ?? '').split('/')[0] || undefined;
+}
+
+/**
+ * Delete a module's web routes, reclaim its static asset roots, and tell the
+ * provider to reconcile. Returns counts + warnings; never throws.
+ */
+export async function cleanupWebRoutesForModule(
+  deps: WebRouteCleanupDeps,
+): Promise<WebRouteCleanupResult> {
+  const { moduleId, db, run = execRunner, emitAndWait = emitWebRoutesChangedAndWait } = deps;
+
+  const owned = db.select().from(webRoutes).where(eq(webRoutes.moduleId, moduleId)).all();
+  if (owned.length === 0) {
+    // Either the module never registered a route, or its own on_uninstall
+    // already called unregister_routes (which emitted and reconciled). Nothing
+    // to do — and importantly, no event, so we don't trigger a redundant
+    // reconcile on every module removal.
+    return { routesRemoved: 0, assetDirsRemoved: [], warnings: [] };
+  }
+
+  const warnings: string[] = [];
+  const assetDirsRemoved: string[] = [];
+
+  const staticSlugs = owned.filter((r) => r.type === 'static').map((r) => r.slug);
+  if (staticSlugs.length > 0) {
+    const providerIp = await resolvePublicWebHostIp(db);
+    if (!providerIp) {
+      warnings.push(
+        `No public_web provider host found — left ${staticSlugs.length} asset dir(s) in /srv/www on disk`,
+      );
+    } else {
+      for (const slug of staticSlugs) {
+        const dir = `/srv/www/${slug}`;
+        // escape-hatch: reclaiming a consumer's static web root on the provider
+        // host. No capability owns asset-root teardown, and it is neither
+        // desired-state nor a service action.
+        const result = runAppCommand(
+          { ipv4_address: providerIp },
+          `rm -rf ${shellEscape(dir)}`,
+          run,
+          { timeoutMs: 30_000 },
+        );
+        if (result.ok) {
+          assetDirsRemoved.push(dir);
+        } else {
+          warnings.push(
+            `Failed to remove ${dir} on ${providerIp} (continuing): ${result.stderr || result.stdout || 'unknown'}`,
+          );
+        }
+      }
+    }
+  }
+
+  db.delete(webRoutes).where(eq(webRoutes.moduleId, moduleId)).run();
+
+  // Same signal a consumer's own unregister_routes emits. Unlike the deploy
+  // path (ISS-0081), an undelivered reconcile here is a warning, not a
+  // failure — removal must complete regardless.
+  const reconcile = await emitAndWait(moduleId);
+  if (reconcile.noDispatcher) {
+    warnings.push(
+      `Routes for ${moduleId} were deleted but no event dispatcher is running, so the public_web provider has not reconciled — it is still serving the removed route(s) until its next reconcile.`,
+    );
+  } else if (reconcile.timedOut) {
+    warnings.push(
+      `public_web provider did not confirm the route removal within the deadline (${reconcile.succeeded} ok, ${reconcile.failed} failed of ${reconcile.events} event(s)).`,
+    );
+  } else if (reconcile.failed > 0) {
+    warnings.push(
+      `public_web provider failed to apply the route removal (${reconcile.failed} delivery failure(s)) — it may still be serving the removed route(s).`,
+    );
+  } else if (reconcile.events > 0 && reconcile.succeeded === 0) {
+    warnings.push(
+      `Routes for ${moduleId} were deleted but NO provider reconciled — the provider has no reconcile_routes subscription, so the removed route(s) may still be served.`,
+    );
+  }
+
+  return { routesRemoved: owned.length, assetDirsRemoved, warnings };
+}

package/src/templates/generator.ts

@@ -158,7 +158,7 @@ export function getOutputFilename(templateFilename: string): string {
  *     a no-op and a real change an in-place UPDATE — never the destructive
  *     REPLACE the terraform-safety guard (create-only, see terraform-safety.ts)
  *     rejects. terraform = birth DNS, the `dns-client-config` aspect = ongoing
- *     DNS. The per-type lists are in the callback. See v2/LXC_INTERNAL_DNS.md.
+ *     DNS. The per-type lists are in the callback. See openspec/specs/lxc-dns-at-birth/spec.md.
  *
  * Anchored on the resource's opening line — it never brace-matches the nested
  * disk/network/features blocks, so it's robust to attribute order/formatting.
@@ -736,7 +736,7 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
 
   // Dedicated DNS-ingress IP (ISS-0156). A dns_internal provider now deploys into
   // a PROTECTED zone (dmz) so it can see protected-zone query sources for
-  // split-horizon views (v2/INTERNAL_DNS_ZONE_VIEWS.md). `internal` devices have
+  // split-horizon views (openspec/specs/internal-dns-zone-views/spec.md). `internal` devices have
   // no route into the 10-net, so they reach the resolver through a firewall DNAT
   // on a dedicated `internal`-subnet address. A module opts in by declaring a
   // `dns_ingress_ip` infrastructure variable; we allocate a free IP from the

package/src/types/infrastructure.ts

@@ -96,7 +96,7 @@ export interface Machine {
   /**
    * Appliance / API-only machines (e.g., greenwave) where celilo has
    * no shell access. Base-module aspects skip these — see
-   * v2/CELILO_BASE.md D8. Optional on the type because most call
+   * openspec/specs/base-module-aspects/spec.md D8. Optional on the type because most call
    * sites don't care; the DB column defaults to false so the
    * effective value is well-defined regardless.
    */

package/src/variables/computed/computed-integration.test.ts

@@ -159,7 +159,7 @@ describe('computed capability fields — DB integration', () => {
     if (!result.success) expect(result.error).toMatch(/could not be resolved|Failed to evaluate/);
   });
 
-  // Gap B (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md step 3): buildResolutionContext
+  // Gap B (openspec/specs/internal-dns-split-horizon/spec.md step 3): buildResolutionContext
   // must EAGERLY evaluate computed markers into the capabilities map, so the
   // `variables.imports` path (which reads context.capabilities directly, not via
   // resolveVariable) sees the real array.

package/src/variables/computed/evaluate.ts

@@ -8,7 +8,7 @@
  * integration (a later step) decide how refs map onto live data.
  *
  * The function allow-list is the v1 set from
- * v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md (D1.1):
+ * openspec/specs/internal-dns-split-horizon/spec.md (D1.1):
  *   keys, values, map, concat, unique, format
  *
  * Secret-projection rule: `values(secret.*)` is rejected — it would leak

package/src/variables/computed/parse.ts

@@ -1,7 +1,7 @@
 /**
  * Parser for the computed-variable DSL.
  *
- * Computed variables (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md, D1) are
+ * Computed variables (openspec/specs/internal-dns-split-horizon/spec.md, D1) are
  * declared in a manifest with `type: computed` and a `value:` expression
  * derived on access from other values, e.g.:
  *

package/src/variables/context.test.ts

@@ -21,7 +21,7 @@ const TEST_DB_PATH = './test-context.db';
 /**
  * Select a proxmox container_service for a module + give it a hostname, so the
  * deployed-system recording in buildResolutionContext fires (IPAM allocates and
- * records into module_systems). v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * records into module_systems). openspec/specs/module-systems-addressing/spec.md.
  */
 function setupProxmoxInfra(db: DbClient, moduleId: string, zone: string): void {
   const serviceId = `svc-${moduleId}`;

package/src/variables/context.ts

@@ -148,7 +148,7 @@ function autoDeriveInventoryVariables(
  * its deployed systems. `$self:` supports the optional `[N]` array-index suffix
  * (e.g. `$self:domains[0]`). `$infra:` references a provider's deployed system
  * by name (the replacement for the old `$self:target_ip` — see
- * v2/MODULE_SYSTEMS_ADDRESSING.md). Non-string values and strings that don't
+ * openspec/specs/module-systems-addressing/spec.md). Non-string values and strings that don't
  * start with one of those prefixes are returned unchanged.
  */
 function resolveSelfRefsInObject(
@@ -323,7 +323,7 @@ export async function buildResolutionContext(
     }
   }
 
-  // Deployed-system recording (v2/MODULE_SYSTEMS_ADDRESSING.md).
+  // Deployed-system recording (openspec/specs/module-systems-addressing/spec.md).
   // Record this module's system(s) into module_systems at generate time, so
   // `$infra:<name>.…` resolves in templates. The address comes from:
   //   - machine pool      → the machine's own IP; no vmid (no container).
@@ -468,7 +468,7 @@ export async function buildResolutionContext(
       providerSystems,
     );
 
-    // Evaluate computed-field markers (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md
+    // Evaluate computed-field markers (openspec/specs/internal-dns-split-horizon/spec.md
     // D1) in the PROVIDER's context, so consumers — both `$capability:` template
     // refs AND `variables.imports` — see the real value (e.g. domain_list as an
     // array) rather than the raw marker. Only build the provider lookup when a
@@ -498,7 +498,7 @@ export async function buildResolutionContext(
     systemConfigMap[row.key] = row.value;
   }
 
-  // LXC nameserver list (v2/LXC_INTERNAL_DNS.md). Proxmox's `nameserver` is a
+  // LXC nameserver list (openspec/specs/lxc-dns-at-birth/spec.md). Proxmox's `nameserver` is a
   // space-separated primary/secondary list. Compose it so every celilo-built
   // LXC boots with a working resolver — before Ansible's apt update, and
   // independent of which Proxmox node it lands on (the nodes' DNS defaults
@@ -566,7 +566,7 @@ export async function buildResolutionContext(
   // Build the `$infra:<name>.<field>` lookup from the systems recorded above
   // (proxmox/machine at generate; DigitalOcean gets refreshed at deploy from
   // terraform outputs). This is what lets `$infra:` resolve in templates.
-  // v2/MODULE_SYSTEMS_ADDRESSING.md.
+  // openspec/specs/module-systems-addressing/spec.md.
   let infraSystemsMap: Record<string, import('./types').InfraSystemFields> = {};
   if (module?.manifestData) {
     const { buildInfraSystemsMap } = await import('../services/deployed-systems');

package/src/variables/lxc-nameserver.test.ts

@@ -9,7 +9,7 @@ const TEST_DB_PATH = './test-lxc-nameserver.db';
 
 /**
  * Coverage for the generate-time `lxc_nameserver` composition
- * (v2/LXC_INTERNAL_DNS.md): proxmox_lxc templates read `$self:lxc_nameserver`,
+ * (openspec/specs/lxc-dns-at-birth/spec.md): proxmox_lxc templates read `$self:lxc_nameserver`,
  * a space-separated primary/secondary list = internal dns_internal resolver
  * first (CIDR stripped), then the public dns.primary/dns.fallback resolvers;
  * public-only when no dns_internal provider is registered (bootstrap).

package/src/variables/resolver.ts

@@ -75,7 +75,7 @@ export async function resolveVariable(
 
     case 'infra': {
       // Format: $infra:<system-name>.<field> — references a deployed system by
-      // its stable handle (requires.systems[].name). v2/MODULE_SYSTEMS_ADDRESSING.md.
+      // its stable handle (requires.systems[].name). openspec/specs/module-systems-addressing/spec.md.
       const dot = variable.path.indexOf('.');
       if (dot === -1) {
         return {
@@ -208,7 +208,7 @@ export async function resolveVariable(
         };
       }
 
-      // Computed field (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D1):
+      // Computed field (openspec/specs/internal-dns-split-horizon/spec.md D1):
       // evaluate the DSL expression in the PROVIDER's context. Like the
       // lazy $self: block below, we look up the provider module, but here
       // we build a typed lookup over its config/secrets/system data.

package/src/variables/types.ts

@@ -24,7 +24,7 @@ export interface ResolutionContext {
   capabilities: Record<string, Record<string, unknown>>;
   /**
    * The module's deployed systems, keyed by name, for `$infra:<name>.<field>`
-   * resolution at generate time (v2/MODULE_SYSTEMS_ADDRESSING.md). Each value
+   * resolution at generate time (openspec/specs/module-systems-addressing/spec.md). Each value
    * exposes the snake_cased fields a template can reference: `ipv4_address`,
    * `hostname`, `zone`, `vmid`, `cidr`. Optional only so the many test-stub
    * `ResolutionContext` literals need no churn — production (buildResolutionContext)

package/src/api/protocol.ts

@@ -1,159 +0,0 @@
-/**
- * Remote API wire protocol (Slice 1).
- *
- * A versioned, Zod-validated tagged union carried as NDJSON. This is the
- * transport-neutral message layer for driving the CLI over the wire — see
- * `v2/API_COMMUNICATION.md`. Slice 1 covers non-interactive command execution
- * + streamed output; `interview` / `answer` / `cancel` arrive in Slice 3.
- *
- * The command crosses the wire as a *structured, validated* `argv` array —
- * never a shell string handed to `exec`.
- */
-
-import { z } from 'zod';
-
-export const API_PROTOCOL_VERSION = 1;
-
-// ── client → server ──────────────────────────────────────────────────────
-
-export const CommandMessageSchema = z.object({
-  type: z.literal('command'),
-  /** Structured argv (e.g. ["module", "list"]) — dispatched into runCli. */
-  argv: z.array(z.string()).min(1),
-});
-export type CommandMessage = z.infer<typeof CommandMessageSchema>;
-
-/** Client's answer to a server `interview` message, correlated by `id`. */
-export const AnswerMessageSchema = z.object({
-  type: z.literal('answer'),
-  id: z.string(),
-  value: z.unknown(),
-});
-export type AnswerMessage = z.infer<typeof AnswerMessageSchema>;
-
-export const ClientMessageSchema = z.discriminatedUnion('type', [
-  CommandMessageSchema,
-  AnswerMessageSchema,
-  // Slice 3+: CancelMessageSchema
-]);
-export type ClientMessage = z.infer<typeof ClientMessageSchema>;
-
-// ── server → client ──────────────────────────────────────────────────────
-
-/** Handshake: server announces itself + the protocol version it speaks. */
-export const ReadyMessageSchema = z.object({
-  type: z.literal('ready'),
-  protocolVersion: z.literal(API_PROTOCOL_VERSION),
-});
-export type ReadyMessage = z.infer<typeof ReadyMessageSchema>;
-
-/**
- * A forwarded `ProgressDisplay` protocol-mode marker. Mirrors the markers
- * emitted by `packages/cli-display` in protocol mode (start/push/done/fail/sub
- * and the legacy instant `[progress]`).
- */
-export const ProgressMessageSchema = z.object({
-  type: z.literal('progress'),
-  kind: z.enum(['start', 'push', 'done', 'fail', 'sub', 'message']),
-  doing: z.string().optional(),
-  done: z.string().optional(),
-  message: z.string().optional(),
-});
-export type ProgressMessage = z.infer<typeof ProgressMessageSchema>;
-
-/** A plain output line from the command that isn't a progress marker. */
-export const LogMessageSchema = z.object({
-  type: z.literal('log'),
-  message: z.string(),
-});
-export type LogMessage = z.infer<typeof LogMessageSchema>;
-
-/** Terminal message for a command run. */
-export const ResultMessageSchema = z.object({
-  type: z.literal('result'),
-  success: z.boolean(),
-  exitCode: z.number(),
-});
-export type ResultMessage = z.infer<typeof ResultMessageSchema>;
-
-/** Protocol-level error (malformed message, etc.) — distinct from a failed command. */
-export const ErrorMessageSchema = z.object({
-  type: z.literal('error'),
-  error: z.string(),
-});
-export type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
-
-/**
- * A mid-run interview question forwarded from the server's event bus. The client
- * renders it, then replies with an `answer` carrying the same `id`. Mirrors the
- * generic `interview.required.*` payload (see bus-interview.ts).
- */
-export const InterviewMessageSchema = z.object({
-  type: z.literal('interview'),
-  id: z.string(),
-  kind: z.enum(['text', 'confirm', 'select', 'multiselect']),
-  message: z.string(),
-  description: z.string().optional(),
-  defaultValue: z.string().optional(),
-  placeholder: z.string().optional(),
-  options: z
-    .array(z.object({ value: z.string(), label: z.string(), hint: z.string().optional() }))
-    .optional(),
-  required: z.boolean().optional(),
-});
-export type InterviewMessage = z.infer<typeof InterviewMessageSchema>;
-
-export const ServerMessageSchema = z.discriminatedUnion('type', [
-  ReadyMessageSchema,
-  ProgressMessageSchema,
-  LogMessageSchema,
-  ResultMessageSchema,
-  ErrorMessageSchema,
-  InterviewMessageSchema,
-]);
-export type ServerMessage = z.infer<typeof ServerMessageSchema>;
-
-// ── translation ───────────────────────────────────────────────────────────
-
-/**
- * Translate one line of the command's stdout into a server message. Progress
- * markers become structured `progress` messages; everything else is a `log`.
- *
- * ponytail: the marker grammar is duplicated from packages/cli-display's
- * ProgressDisplay (which *emits* it). If a third consumer appears, extract a
- * shared parser into @celilo/cli-display and have both sides import it.
- */
-export function translateOutputLine(line: string): ProgressMessage | LogMessage {
-  const startPush = line.match(/^\[progress:(start|push)\] (.*?) \| (.*)$/);
-  if (startPush) {
-    return {
-      type: 'progress',
-      kind: startPush[1] as 'start' | 'push',
-      doing: startPush[2],
-      done: startPush[3],
-    };
-  }
-
-  const done = line.match(/^\[progress:done\](.*)$/);
-  if (done) {
-    const msg = done[1].trim();
-    return { type: 'progress', kind: 'done', message: msg || undefined };
-  }
-
-  const fail = line.match(/^\[progress:fail\] (.*)$/);
-  if (fail) {
-    return { type: 'progress', kind: 'fail', message: fail[1] };
-  }
-
-  const sub = line.match(/^\[progress:sub\] (.*)$/);
-  if (sub) {
-    return { type: 'progress', kind: 'sub', message: sub[1] };
-  }
-
-  const legacy = line.match(/^\[progress\] (.*)$/);
-  if (legacy) {
-    return { type: 'progress', kind: 'message', message: legacy[1] };
-  }
-
-  return { type: 'log', message: line };
-}

package/src/api/remote-client.ts

@@ -1,218 +0,0 @@
-/**
- * Remote API client — `celilo --remote <dest> <command...>` (Slice 2c).
- *
- * SSHes to <dest> (whose sshd forced command runs `api-serve --principal=…`),
- * ships the command as a structured argv over the NDJSON protocol, renders the
- * streamed `progress`/`log` through the local ProgressDisplay, and exits with
- * the command's exit code. Reuses the system `ssh` client, so keys, known_hosts,
- * agent, and ~/.ssh/config all apply — execution is remote, presentation local.
- */
-
-import { type DisplayWriter, ProgressDisplay } from '@celilo/cli-display';
-import * as clack from '@clack/prompts';
-import { type InterviewMessage, type ServerMessage, ServerMessageSchema } from './protocol';
-
-const REMOTE_FLAG = '--remote';
-
-/** Render a forwarded interview via clack, returning the operator's answer. */
-async function defaultRenderInterview(iv: InterviewMessage): Promise<unknown> {
-  const options = (iv.options ?? []).map((o) => ({ value: o.value, label: o.label, hint: o.hint }));
-  let result: unknown;
-  switch (iv.kind) {
-    case 'confirm':
-      result = await clack.confirm({
-        message: iv.message,
-        initialValue: iv.defaultValue === 'true',
-      });
-      break;
-    case 'select':
-      result = await clack.select({ message: iv.message, options });
-      break;
-    case 'multiselect':
-      result = await clack.multiselect({
-        message: iv.message,
-        options,
-        required: iv.required ?? false,
-      });
-      break;
-    default:
-      result = await clack.text({
-        message: iv.message,
-        defaultValue: iv.defaultValue,
-        placeholder: iv.placeholder,
-      });
-  }
-  if (clack.isCancel(result)) {
-    clack.cancel('Cancelled.');
-    process.exit(130);
-  }
-  return result;
-}
-
-/** Minimal transport surface — satisfied by a `Bun.spawn` of `ssh`. */
-export interface RemoteTransport {
-  stdin: { write(chunk: string): void; flush?(): number | Promise<number> };
-  stdout: ReadableStream<Uint8Array>;
-  kill(): void;
-  exited: Promise<number>;
-}
-
-/**
- * Resolve the remote target from a leading `--remote <dest>` / `--remote=<dest>`
- * or the `CELILO_REMOTE` env. Returns null for a local invocation.
- */
-export function resolveRemote(
-  argv: string[],
-  remoteEnv: string | undefined = process.env.CELILO_REMOTE,
-): { dest: string; commandArgv: string[] } | null {
-  const rest = argv.slice(2);
-
-  if (rest[0] === REMOTE_FLAG && rest[1]) {
-    return { dest: rest[1], commandArgv: rest.slice(2) };
-  }
-  if (rest[0]?.startsWith(`${REMOTE_FLAG}=`)) {
-    return { dest: rest[0].slice(REMOTE_FLAG.length + 1), commandArgv: rest.slice(1) };
-  }
-  if (remoteEnv) {
-    return { dest: remoteEnv, commandArgv: rest };
-  }
-  return null;
-}
-
-function openSshTransport(dest: string): RemoteTransport {
-  // -T: no pseudo-tty — we want a raw NDJSON pipe. stderr inherits so ssh's own
-  // diagnostics (host-key prompts, connection failures) reach the operator.
-  const proc = Bun.spawn(['ssh', '-T', dest], {
-    stdin: 'pipe',
-    stdout: 'pipe',
-    stderr: 'inherit',
-  });
-  return {
-    stdin: proc.stdin,
-    stdout: proc.stdout,
-    kill: () => proc.kill(),
-    exited: proc.exited,
-  };
-}
-
-/** Apply one server message to the local display; returns an exit code if terminal. */
-function applyMessage(
-  msg: ServerMessage,
-  display: ProgressDisplay,
-  out: DisplayWriter,
-): number | null {
-  switch (msg.type) {
-    case 'ready':
-      return null;
-    case 'progress':
-      switch (msg.kind) {
-        case 'start':
-          display.startStep(msg.doing ?? '', msg.done ?? '');
-          break;
-        case 'push':
-          display.pushStep(msg.doing ?? '', msg.done ?? '');
-          break;
-        case 'done':
-          display.doneStep(msg.message);
-          break;
-        case 'fail':
-          display.failStep(msg.message ?? '');
-          break;
-        case 'sub':
-          display.subEvent(msg.message ?? '');
-          break;
-        case 'message':
-          display.instantEvent(msg.message ?? '');
-          break;
-      }
-      return null;
-    case 'log':
-      // Nest under the active step so the footer isn't corrupted; otherwise print.
-      if (display.hasPending) {
-        display.subEvent(msg.message);
-      } else {
-        out.write(`${msg.message}\n`);
-      }
-      return null;
-    case 'error':
-      process.stderr.write(`${msg.error}\n`);
-      return null;
-    case 'interview':
-      // Handled by the caller (needs the transport to reply) — never reached here.
-      return null;
-    case 'result':
-      return msg.exitCode;
-  }
-}
-
-export async function runRemoteClient(
-  dest: string,
-  argv: string[],
-  opts: {
-    openTransport?: (dest: string) => RemoteTransport;
-    out?: DisplayWriter;
-    renderInterview?: (interview: InterviewMessage) => Promise<unknown>;
-  } = {},
-): Promise<number> {
-  if (argv.length === 0) {
-    process.stderr.write(
-      'celilo --remote <dest> requires a command (e.g. celilo --remote host module list)\n',
-    );
-    return 2;
-  }
-
-  const openTransport = opts.openTransport ?? openSshTransport;
-  const out = opts.out ?? process.stdout;
-  const renderInterview = opts.renderInterview ?? defaultRenderInterview;
-  const display = new ProgressDisplay({ out });
-
-  const transport = openTransport(dest);
-  transport.stdin.write(`${JSON.stringify({ type: 'command', argv })}\n`);
-  await transport.stdin.flush?.();
-
-  let resultExit: number | null = null;
-  const decoder = new TextDecoder();
-  let buffer = '';
-
-  outer: for await (const chunk of transport.stdout) {
-    buffer += decoder.decode(chunk, { stream: true });
-    let nl = buffer.indexOf('\n');
-    while (nl >= 0) {
-      const line = buffer.slice(0, nl);
-      buffer = buffer.slice(nl + 1);
-      nl = buffer.indexOf('\n');
-      if (!line.trim()) continue;
-
-      let msg: ServerMessage;
-      try {
-        msg = ServerMessageSchema.parse(JSON.parse(line));
-      } catch {
-        // Non-protocol line (e.g. an ssh notice) — pass through.
-        out.write(`${line}\n`);
-        continue;
-      }
-
-      if (msg.type === 'interview') {
-        const value = await renderInterview(msg);
-        transport.stdin.write(`${JSON.stringify({ type: 'answer', id: msg.id, value })}\n`);
-        await transport.stdin.flush?.();
-        continue;
-      }
-
-      const exit = applyMessage(msg, display, out);
-      if (exit !== null) {
-        resultExit = exit;
-        break outer;
-      }
-    }
-  }
-
-  if (resultExit !== null) {
-    // Server is still looping awaiting more input — tear it down.
-    transport.kill();
-    return resultExit;
-  }
-
-  // Stream ended without a result — surface the transport's exit (ssh failure).
-  return transport.exited;
-}