@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/src/lib/host-image-loader.ts

@@ -0,0 +1,138 @@
+/**
+ * Client for the host-side image-loader endpoint. Used to acquire image refs
+ * that aren't pullable from any external registry.
+ *
+ * The endpoint URL is a well-known convention — port 5500 on 127.0.0.1.
+ * The CLI calls in whenever it sees a ref that starts with `cadet-local/`,
+ * which are image refs that only exist in a local docker daemon and can't be
+ * `docker pull`'d from any external registry.
+ *
+ * The endpoint contract is intentionally minimal — POST a ref as JSON, get
+ * back a 200 once the image is in the host docker daemon, or a non-2xx
+ * with a descriptive error message. The client doesn't know (or care) what
+ * transport the server uses to put the image there.
+ */
+
+/**
+ * Well-known URL of the host-side image-loader server.
+ */
+export const HOST_IMAGE_LOADER_URL = "http://127.0.0.1:5500/v1/images/load";
+
+/**
+ * Prefix for image refs that only exist in a local docker daemon.
+ * These cannot be `docker pull`'d from any external registry; the CLI must
+ * route them through the host image-loader instead.
+ */
+const LOCAL_BUILD_REF_PREFIX = "cadet-local/";
+
+/** Whether `ref` points at a local-build image that requires the host loader. */
+export function isLocalBuildRef(ref: string): boolean {
+  return ref.startsWith(LOCAL_BUILD_REF_PREFIX);
+}
+
+/** Default timeout for image-load requests. Large `docker save | docker load`
+ * pipelines for full assistant images can run for a minute or two on cold
+ * caches, so we give plenty of headroom. */
+const LOAD_TIMEOUT_MS = 120_000;
+
+export interface HostImageLoaderResponse {
+  loaded?: boolean;
+  ref?: string;
+  error?: string;
+}
+
+export class HostImageLoaderError extends Error {
+  readonly url: string;
+  readonly ref: string;
+  readonly status?: number;
+
+  constructor(message: string, url: string, ref: string, status?: number) {
+    super(message);
+    this.name = "HostImageLoaderError";
+    this.url = url;
+    this.ref = ref;
+    this.status = status;
+  }
+}
+
+function isConnectionRefused(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { cause?: { code?: string }; code?: string };
+  return e.cause?.code === "ECONNREFUSED" || e.code === "ECONNREFUSED";
+}
+
+/**
+ * Ask the host-side loader to acquire `ref` into the host docker daemon.
+ *
+ * Resolves when the server returns 200; throws a {@link HostImageLoaderError}
+ * with a user-actionable message on any failure (network, timeout, non-2xx).
+ *
+ * The `log` callback receives one-line status updates; pass the same logger
+ * the surrounding command uses.
+ */
+/** Minimal fetch signature accepted for test injection. */
+export type FetchLike = (
+  input: string | URL,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<Response>;
+
+export async function loadImageViaHost(
+  url: string,
+  ref: string,
+  log: (msg: string) => void,
+  options: { timeoutMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? LOAD_TIMEOUT_MS;
+  const fetchImpl: FetchLike =
+    options.fetchImpl ?? (fetch as unknown as FetchLike);
+
+  log(`   ↪ ${ref}`);
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ref }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    if (isConnectionRefused(err)) {
+      throw new HostImageLoaderError(
+        `Could not reach image-loader at ${url}. The ref \`${ref}\` is a ` +
+          `local-build image that requires the loader. Is the loader running? ` +
+          `Start it, or set CADET_ASSISTANT_IMAGE / CADET_GATEWAY_IMAGE / ` +
+          `CADET_CREDENTIAL_EXECUTOR_IMAGE to bypass image resolution.`,
+        url,
+        ref,
+      );
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new HostImageLoaderError(
+      `Image-loader request for ${ref} failed: ${message}`,
+      url,
+      ref,
+    );
+  }
+
+  if (!response.ok) {
+    let body: HostImageLoaderResponse | null = null;
+    try {
+      body = (await response.json()) as HostImageLoaderResponse;
+    } catch {
+      // Server returned non-JSON; fall through with status-only error.
+    }
+    const detail = body?.error ? `: ${body.error}` : "";
+    throw new HostImageLoaderError(
+      `Image-loader returned HTTP ${response.status} for ${ref}${detail}`,
+      url,
+      ref,
+      response.status,
+    );
+  }
+}

package/src/lib/http-client.ts

@@ -0,0 +1,143 @@
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
+export type HttpProbeEndpoint = "healthz" | "readyz";
+
+/**
+ * Build the base URL for the daemon HTTP server.
+ */
+export function buildDaemonUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+async function httpProbe(
+  port: number,
+  endpoint: HttpProbeEndpoint,
+  timeoutMs: number,
+): Promise<boolean> {
+  try {
+    const url = `${buildDaemonUrl(port)}/${endpoint}`;
+    const response = await loopbackSafeFetch(url, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Perform an HTTP health check against the daemon's `/healthz` endpoint.
+ * Returns true if the daemon responds with HTTP 200, false otherwise.
+ */
+export async function httpHealthCheck(
+  port: number,
+  timeoutMs = 1500,
+): Promise<boolean> {
+  return httpProbe(port, "healthz", timeoutMs);
+}
+
+/**
+ * Poll a daemon probe endpoint until it responds with 200 or the timeout is
+ * reached.
+ *
+ * Returns true if the daemon became ready within the timeout, false otherwise.
+ */
+export async function waitForDaemonReady(
+  port: number,
+  timeoutMs = 60000,
+  endpoint: HttpProbeEndpoint = "healthz",
+): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await httpProbe(port, endpoint, 1500)) {
+      return true;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return false;
+}
+
+/**
+ * Migration-aware daemon readiness, derived from the `/readyz` BODY rather
+ * than its status code. The status code is the k8s contract — 200 while
+ * migrations run so the pod stays in service, 503 only on migration failure —
+ * so `response.ok` alone cannot distinguish "ready" from "still migrating".
+ */
+export type DaemonReadiness = "ready" | "migrating" | "failed" | "unreachable";
+
+/**
+ * Classify a `/readyz` response (daemon-direct or proxied through the
+ * gateway, which forwards the assistant's readiness body). Shared by the
+ * local daemon probe and the docker upgrade/hatch readiness waits so there is
+ * exactly one reader of the readiness wire shape.
+ *
+ * Any HTTP-answered response proves the daemon is alive, so a non-ready
+ * answer without a failed-migrations body classifies as "migrating" — this
+ * covers legacy daemons whose strict `/readyz` returns 503 with a `notReady`
+ * body throughout startup. "unreachable" is reserved for the no-answer case
+ * (the caller's fetch threw).
+ */
+export function classifyReadyzResponse(
+  ok: boolean,
+  body: unknown,
+): Exclude<DaemonReadiness, "unreachable"> {
+  const readiness = body as {
+    ready?: boolean;
+    dbMigrations?: { state?: string };
+  } | null;
+  if (readiness?.dbMigrations?.state === "failed") return "failed";
+  // A 200 with no explicit `ready: false` counts as ready — this also
+  // covers daemons that predate the migration-state body.
+  if (ok && readiness?.ready !== false) return "ready";
+  return "migrating";
+}
+
+/** Single `/readyz` probe, classified from the response body. */
+export async function probeDaemonReadiness(
+  port: number,
+  timeoutMs = 1500,
+): Promise<DaemonReadiness> {
+  try {
+    const response = await loopbackSafeFetch(`${buildDaemonUrl(port)}/readyz`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const body = (await response.json().catch(() => null)) as unknown;
+    return classifyReadyzResponse(response.ok, body);
+  } catch {
+    return "unreachable";
+  }
+}
+
+/**
+ * `probeDaemonReadiness` with one retry on a transient timeout: a single
+ * probe's 1.5s budget can elapse while a synchronous migration step blocks
+ * the daemon's event loop, misreporting a live daemon as unreachable.
+ */
+export async function probeDaemonReadinessWithRetry(
+  port: number,
+): Promise<DaemonReadiness> {
+  const first = await probeDaemonReadiness(port);
+  if (first !== "unreachable") {
+    return first;
+  }
+  return probeDaemonReadiness(port);
+}
+
+/**
+ * Poll `/readyz` until the daemon is ready, its migrations have terminally
+ * FAILED (returned immediately — failed never recovers without a restart, so
+ * waiting out the deadline would be pure delay), or `deadlineMs` passes.
+ * Returns the last observed readiness.
+ */
+export async function waitForDaemonMigrationsReady(
+  port: number,
+  deadlineMs: number,
+): Promise<DaemonReadiness> {
+  let last: DaemonReadiness = "unreachable";
+  for (;;) {
+    last = await probeDaemonReadiness(port);
+    if (last === "ready" || last === "failed") return last;
+    if (Date.now() >= deadlineMs) return last;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}

package/src/lib/ingress-config.ts

@@ -0,0 +1,226 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  INGRESS_ASSISTANT_ID_KEY,
+  INGRESS_LAST_TUNNEL_KEY,
+  INGRESS_PAIRING_TUNNEL_KEY,
+  type TunnelProviderName,
+  type TunnelRecord,
+} from "@mycadet/service-contracts/ingress";
+
+import {
+  lookupAssistantByIdentifier,
+  saveAssistantEntry,
+  type AssistantEntry,
+} from "./assistant-config.js";
+
+/**
+ * Shared workspace-config helpers for tunnel providers (ngrok, cloudflare,
+ * tailscale) and the nginx ingress proxy. Each provider fronts the local edge
+ * and records the resulting public URL under `ingress.publicBaseUrl` so webhook
+ * integrations can reach the assistant. The workspace config is the
+ * gateway-facing contract; when an `assistantId` is supplied, the URL is also
+ * mirrored onto the lockfile entry (`ingressUrl`) — the CLI-owned contract
+ * that CLI features (e.g. remote-web pairing defaults) read, per the
+ * no-`.cadet/`-reads boundary in cli/AGENTS.md.
+ */
+
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string" || !url.trim()) return undefined;
+  try {
+    const port = Number(new URL(url).port);
+    return Number.isInteger(port) && port > 0 && port <= 65535
+      ? port
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Container topologies whose gateway runs on this machine without host `resources`. */
+export function isLocalContainerEntry(entry: AssistantEntry): boolean {
+  return entry.cloud === "docker" || entry.cloud === "apple-container";
+}
+
+/**
+ * Derive the gateway port from an entry's recorded URLs, preferring the
+ * loopback `localUrl` over `runtimeUrl`. Undefined when neither carries an
+ * explicit port (e.g. a platform-hosted https runtime URL).
+ */
+export function parseGatewayPortFromEntryUrls(
+  entry: AssistantEntry | undefined,
+): number | undefined {
+  return (
+    parsePortFromUrl(entry?.localUrl) ?? parsePortFromUrl(entry?.runtimeUrl)
+  );
+}
+
+/** Default workspace dir: `$CADET_WORKSPACE_DIR` or `~/.cadet/workspace`. */
+export function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.CADET_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".cadet", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
+}
+
+/** Read the workspace `config.json`, or an empty object when it is absent. */
+export function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+/** Write the workspace `config.json`, creating parent directories as needed. */
+export function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+/** The ingress URL mirrored onto the lockfile entry, or null when it has none. */
+export function readLockfileIngressUrl(assistantId: string): string | null {
+  const result = lookupAssistantByIdentifier(assistantId);
+  return result.status === "found" ? (result.entry.ingressUrl ?? null) : null;
+}
+
+/**
+ * Mirror the ingress URL onto the lockfile entry; null removes it. Exported on
+ * its own for tunnels that publish an address to pair against while leaving the
+ * workspace `ingress` record (the webhook callback base) alone.
+ */
+export function stampLockfileIngressUrl(
+  assistantId: string,
+  publicUrl: string | null,
+): void {
+  const result = lookupAssistantByIdentifier(assistantId);
+  if (result.status !== "found") {
+    return;
+  }
+  const entry = result.entry;
+  if (publicUrl) {
+    entry.ingressUrl = publicUrl;
+  } else {
+    delete entry.ingressUrl;
+  }
+  saveAssistantEntry(entry);
+}
+
+/**
+ * Persist a public ingress URL to the workspace config and enable ingress.
+ * `provider`/`assistantId` also land under `ingress.lastTunnel` and
+ * `ingress.assistantId`: workspace-only records the daemon reads to report
+ * tunnel health, deliberately not mirrored onto the lockfile.
+ */
+export function saveIngressUrl(
+  workspaceDir: string,
+  publicUrl: string,
+  assistantId?: string,
+  provider?: TunnelProviderName,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  if (provider) {
+    ingress[INGRESS_LAST_TUNNEL_KEY] = {
+      provider,
+      publicBaseUrl: publicUrl,
+    } satisfies TunnelRecord;
+  }
+  // The daemon can't derive this: it uses 'self' internally.
+  if (assistantId) {
+    ingress[INGRESS_ASSISTANT_ID_KEY] = assistantId;
+  }
+  // This URL is the address to reach the assistant at, pairing included, so a
+  // pairing-only record left by an earlier run no longer names one to prefer.
+  delete ingress[INGRESS_PAIRING_TUNNEL_KEY];
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+  if (assistantId) {
+    stampLockfileIngressUrl(assistantId, publicUrl);
+  }
+}
+
+/**
+ * Persist the tunnel devices pair against under `ingress.pairingTunnel`, plus
+ * the assistant it fronts; null drops the record.
+ *
+ * A tunnel that cannot carry webhook callbacks leaves `ingress.publicBaseUrl`
+ * alone, so the lockfile mirror alone would leave it invisible to the daemon,
+ * which reads only the workspace config. `ingress.assistantId` rides along
+ * because the daemon's probe needs it to tell this assistant's edge from
+ * someone else's, and it names the same assistant either record fronts.
+ */
+export function savePairingTunnel(
+  workspaceDir: string,
+  record: TunnelRecord | null,
+  assistantId?: string,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  if (record) {
+    ingress[INGRESS_PAIRING_TUNNEL_KEY] = record;
+    if (assistantId) {
+      ingress[INGRESS_ASSISTANT_ID_KEY] = assistantId;
+    }
+  } else {
+    delete ingress[INGRESS_PAIRING_TUNNEL_KEY];
+  }
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+/** Persist a reserved ngrok domain under `ingress.ngrok.domain`; null clears it. */
+export function saveNgrokDomain(
+  workspaceDir: string,
+  domain: string | null,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  if (domain) {
+    ingress.ngrok = { domain };
+  } else {
+    delete ingress.ngrok;
+  }
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+/** Read the reserved ngrok domain from the workspace config, if saved. */
+export function loadNgrokDomain(workspaceDir: string): string | null {
+  const ingress = loadRawConfig(workspaceDir).ingress as
+    | Record<string, unknown>
+    | undefined;
+  const ngrok = ingress?.ngrok as Record<string, unknown> | undefined;
+  const domain = ngrok?.domain;
+  return typeof domain === "string" && domain.trim() ? domain : null;
+}
+
+/** Clear the ingress public base URL from the workspace config. */
+export function clearIngressUrl(
+  workspaceDir: string,
+  assistantId?: string,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  // `lastTunnel`/`assistantId` survive teardown on purpose: readers name the
+  // tunnel to restart once it is gone.
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+  if (assistantId) {
+    stampLockfileIngressUrl(assistantId, null);
+  }
+}

package/src/lib/input-history.ts

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+
+import { getInputHistoryPath } from "./environments/paths.js";
+
+const MAX_ENTRIES = 1000;
+
+export function loadHistory(): string[] {
+  try {
+    const path = getInputHistoryPath();
+    if (!existsSync(path)) return [];
+    const content = readFileSync(path, "utf-8");
+    return content
+      .split("\n")
+      .filter((line) => line.length > 0)
+      .slice(-MAX_ENTRIES);
+  } catch {
+    return [];
+  }
+}
+
+export function appendHistory(entry: string): void {
+  const trimmed = entry.trim();
+  if (!trimmed || trimmed.startsWith("/")) return;
+  try {
+    const path = getInputHistoryPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const existing = loadHistory();
+    // Deduplicate: remove previous occurrence of the same entry
+    const deduped = existing.filter((e) => e !== trimmed);
+    deduped.push(trimmed);
+    // Keep only the last MAX_ENTRIES
+    const trimmedList = deduped.slice(-MAX_ENTRIES);
+    writeFileSync(path, trimmedList.join("\n") + "\n", { mode: 0o600 });
+  } catch {
+    // Best-effort persistence — don't crash on write failure
+  }
+}