@mycadet/cli 0.12.6-dev.202610091338.ee7f3e3 → 0.12.7

package/src/lib/assistant-config.ts

@@ -93,10 +93,10 @@ export interface ContainerInfo {
  * validation boundary — the same toolchain writes and reads them — so they are
  * modeled as plain types here rather than re-validated.
  *
- * `runtimeUrl` is required (`readAssistants` only returns entries that have one)
+ * `runtimeUrl` is required (`loadAllAssistants` only returns entries that have one)
  * and `resources` is the richer host shape. `cloud` is inherited from
  * `LockfileAssistant` (always present; normalized at the read seam — see
- * `readAssistants`). The index signature preserves unknown on-disk fields so a
+ * `loadAllAssistants`). The index signature preserves unknown on-disk fields so a
  * read→write round-trip never drops a newer writer's data.
  */
 export type AssistantEntry = Omit<
@@ -330,7 +330,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
   return mutated;
 }
 
-function readAssistants(): AssistantEntry[] {
+export function loadAllAssistants(): AssistantEntry[] {
   const data = readLockfile();
   const entries = data.assistants;
   if (!Array.isArray(entries)) {
@@ -384,7 +384,7 @@ function writeAssistants(entries: AssistantEntry[]): void {
 }
 
 export function loadLatestAssistant(): AssistantEntry | null {
-  const entries = readAssistants();
+  const entries = loadAllAssistants();
   if (entries.length === 0) {
     return null;
   }
@@ -397,7 +397,7 @@ export function loadLatestAssistant(): AssistantEntry | null {
 }
 
 export function findAssistantByName(name: string): AssistantEntry | null {
-  return readAssistants().find((entry) => entry.assistantId === name) ?? null;
+  return loadAllAssistants().find((entry) => entry.assistantId === name) ?? null;
 }
 
 export function getAssistantDisplayName(entry: AssistantEntry): string {
@@ -430,7 +430,7 @@ function getAssistantDisplayNameCandidates(entry: AssistantEntry): string[] {
 export function lookupAssistantByIdentifier(
   identifier: string,
 ): AssistantLookupResult {
-  const entries = readAssistants();
+  const entries = loadAllAssistants();
   const exactId = entries.find((entry) => entry.assistantId === identifier);
   if (exactId) {
     return { status: "found", entry: exactId };
@@ -483,10 +483,6 @@ export function removeAssistantEntry(assistantId: string): void {
   });
 }
 
-export function loadAllAssistants(): AssistantEntry[] {
-  return readAssistants();
-}
-
 /**
  * Read the first existing lockfile for an explicitly-provided environment,
  * without applying legacy migrations. This is the cross-env read path used by
@@ -585,7 +581,7 @@ export function resolveAssistant(nameArg?: string): AssistantEntry | null {
     // Active assistant no longer exists in lockfile — fall through
   }
 
-  const all = readAssistants();
+  const all = loadAllAssistants();
   if (all.length === 1) return all[0];
 
   return null;
@@ -617,7 +613,7 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
       // Active assistant no longer exists in lockfile — fall through.
     }
 
-    const all = readAssistants();
+    const all = loadAllAssistants();
     if (all.length === 1) return all[0];
 
     if (all.length === 0) {
@@ -648,7 +644,7 @@ export function extractHostFromUrl(url: string): string {
 
 export function saveAssistantEntry(entry: AssistantEntry): void {
   withCliLockfileLock(() => {
-    const entries = readAssistants().filter(
+    const entries = loadAllAssistants().filter(
       (e) => e.assistantId !== entry.assistantId,
     );
     entries.unshift(entry);

package/src/lib/backup-ops.ts

@@ -7,7 +7,6 @@ import {
   unlinkSync,
   writeFileSync,
 } from "fs";
-import { homedir } from "os";
 import { dirname, join } from "path";
 
 import {
@@ -17,12 +16,12 @@ import {
 } from "./bundle-staging.js";
 import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { getStateDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 
 /** Default backup directory following XDG convention */
 export function getBackupsDir(): string {
-  const dataHome =
-    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
-  return join(dataHome, "cadet", "backups");
+  return join(getStateDir(getCurrentEnvironment()), "backups");
 }
 
 /** Human-readable file size */

package/src/lib/client-identity.ts

@@ -1,25 +1,24 @@
 /**
  * Stable per-install client identity for the CLI.
  *
- * Generates a UUID on first use and persists it to
- * `~/.config/cadet/client-id` so the daemon's event hub can
+ * Generates a UUID on first use and persists it to the environment's
+ * config dir (`client-id`) so the daemon's event hub can
  * track this terminal across SSE reconnects and CLI restarts.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { randomUUID } from "crypto";
-import { homedir } from "os";
 import { join } from "path";
 
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
 export const CLI_INTERFACE_ID = "cli";
 export const WEB_INTERFACE_ID = "web";
 
 let cached: string | null = null;
 
-function getConfigDir(): string {
-  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(configHome, "cadet");
-}
+
 
 /**
  * Returns a stable UUID identifying this CLI installation.
@@ -28,8 +27,7 @@ function getConfigDir(): string {
 export function getClientId(): string {
   if (cached) return cached;
 
-  const configDir = getConfigDir();
-  const idFile = join(configDir, "client-id");
+  const idFile = join(getConfigDir(getCurrentEnvironment()), "client-id");
 
   try {
     if (existsSync(idFile)) {
@@ -45,7 +43,7 @@ export function getClientId(): string {
 
   const id = randomUUID();
   try {
-    mkdirSync(configDir, { recursive: true });
+    mkdirSync(getConfigDir(getCurrentEnvironment()), { recursive: true });
     writeFileSync(idFile, id, "utf-8");
   } catch {
     /* best-effort persist — transient id still works for this session */

package/src/lib/guardian-token.ts

@@ -28,6 +28,39 @@ import {
 import { getConfigDir, getConfigDirs } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { z } from "zod";
+
+/**
+ * The guardian token fields as they arrive untrusted (gateway refresh/init
+ * responses, persisted token files). Every field is independently optional
+ * and independently caught: one malformed field must not invalidate the
+ * others — callers fall back per field.
+ */
+const GuardianTokenFieldsSchema = z
+  .object({
+    guardianPrincipalId: z.string().optional().catch(undefined),
+    accessToken: z.string().optional().catch(undefined),
+    accessTokenExpiresAt: z
+      .union([z.string(), z.number()])
+      .optional()
+      .catch(undefined),
+    refreshToken: z.string().optional().catch(undefined),
+    refreshTokenExpiresAt: z
+      .union([z.string(), z.number()])
+      .optional()
+      .catch(undefined),
+    refreshAfter: z.string().optional().catch(undefined),
+    isNew: z.boolean().optional().catch(undefined),
+    deviceId: z.string().optional().catch(undefined),
+  })
+  .catch({});
+
+/** Narrow untrusted JSON to the token fields whose values have the right
+ * shape; fields absent or malformed come back undefined for callers to
+ * fall back on or reject. */
+function parseGuardianTokenFields(value: unknown): Partial<GuardianTokenData> {
+  return GuardianTokenFieldsSchema.parse(value);
+}
 
 const DEVICE_ID_SALT = "mycadet-host-id";
 
@@ -470,19 +503,24 @@ export async function refreshGuardianTokenResult(
       return classifyRefreshHttpStatus(response.status);
     }
 
-    const json = (await response.json()) as Record<string, unknown>;
+    const parsed = parseGuardianTokenFields(await response.json());
+    if (parsed.accessToken == null) {
+      return {
+        ok: false,
+        status: 502,
+        error: "Assistant gateway returned a malformed token refresh response",
+      };
+    }
     const refreshed: GuardianTokenData = {
       guardianPrincipalId:
-        (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
-      accessToken: json.accessToken as string,
+        parsed.guardianPrincipalId ?? tokenData.guardianPrincipalId,
+      accessToken: parsed.accessToken,
       accessTokenExpiresAt:
-        (json.accessTokenExpiresAt as string | number) ??
-        tokenData.accessTokenExpiresAt,
-      refreshToken: (json.refreshToken as string) ?? tokenData.refreshToken,
+        parsed.accessTokenExpiresAt ?? tokenData.accessTokenExpiresAt,
+      refreshToken: parsed.refreshToken ?? tokenData.refreshToken,
       refreshTokenExpiresAt:
-        (json.refreshTokenExpiresAt as string | number) ??
-        tokenData.refreshTokenExpiresAt,
-      refreshAfter: (json.refreshAfter as string) ?? tokenData.refreshAfter,
+        parsed.refreshTokenExpiresAt ?? tokenData.refreshTokenExpiresAt,
+      refreshAfter: parsed.refreshAfter ?? tokenData.refreshAfter,
       isNew: false,
       deviceId: tokenData.deviceId,
       leasedAt: new Date().toISOString(),
@@ -583,15 +621,28 @@ export async function leaseGuardianToken(
     throw new Error(`guardian/init failed (${response.status}): ${body}`);
   }
 
-  const json = (await response.json()) as Record<string, unknown>;
+  const parsed = parseGuardianTokenFields(await response.json());
+  if (
+    parsed.guardianPrincipalId == null ||
+    parsed.accessToken == null ||
+    parsed.accessTokenExpiresAt == null ||
+    parsed.refreshToken == null ||
+    parsed.refreshTokenExpiresAt == null ||
+    parsed.refreshAfter == null ||
+    parsed.isNew == null
+  ) {
+    throw new Error(
+      `guardian/init returned a malformed token response (${response.status})`,
+    );
+  }
   const tokenData: GuardianTokenData = {
-    guardianPrincipalId: json.guardianPrincipalId as string,
-    accessToken: json.accessToken as string,
-    accessTokenExpiresAt: json.accessTokenExpiresAt as string | number,
-    refreshToken: json.refreshToken as string,
-    refreshTokenExpiresAt: json.refreshTokenExpiresAt as string | number,
-    refreshAfter: json.refreshAfter as string,
-    isNew: json.isNew as boolean,
+    guardianPrincipalId: parsed.guardianPrincipalId,
+    accessToken: parsed.accessToken,
+    accessTokenExpiresAt: parsed.accessTokenExpiresAt,
+    refreshToken: parsed.refreshToken,
+    refreshTokenExpiresAt: parsed.refreshTokenExpiresAt,
+    refreshAfter: parsed.refreshAfter,
+    isNew: parsed.isNew,
     deviceId,
     leasedAt: new Date().toISOString(),
   };
@@ -675,7 +726,10 @@ export function seedGuardianTokenFromSiblingEnv(assistantId: string): boolean {
   for (const { path: sibling } of candidates) {
     try {
       const raw = readFileSync(sibling);
-      const parsed = JSON.parse(raw.toString("utf-8")) as GuardianTokenData;
+      const parsed = parseGuardianTokenFields(
+        JSON.parse(raw.toString("utf-8")),
+      );
+      if (parsed.refreshTokenExpiresAt == null) continue;
       const refreshExpiry = new Date(parsed.refreshTokenExpiresAt).getTime();
       if (!Number.isFinite(refreshExpiry) || refreshExpiry <= now) continue;
       const dir = dirname(destPath);

package/src/lib/health-check.ts

@@ -1,12 +1,13 @@
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { z } from "zod";
 
-export const HEALTH_CHECK_TIMEOUT_MS = 1500;
+const HealthResponseSchema = z.object({
+  status: z.string().optional(),
+  message: z.string().optional(),
+  version: z.string().optional(),
+});
 
-interface HealthResponse {
-  status: string;
-  message?: string;
-  version?: string;
-}
+export const HEALTH_CHECK_TIMEOUT_MS = 1500;
 
 export interface HealthCheckResult {
   status: string;
@@ -57,7 +58,9 @@ export async function checkManagedHealth(
       return { status: `error (${response.status})`, detail: null };
     }
 
-    const data = (await response.json()) as HealthResponse;
+    const data = HealthResponseSchema
+      .catch({})
+      .parse(await response.json());
     const status = data.status || "unknown";
     return {
       status,
@@ -168,12 +171,12 @@ export async function fetchManagedPs(
   }
 }
 
-interface LegacyConnectionStatus {
-  state: string;
-  is_awake: boolean;
-  pod_status: string | null;
-  detail: string | null;
-}
+const LegacyConnectionStatusSchema = z.object({
+  state: z.string(),
+  is_awake: z.boolean(),
+  pod_status: z.string().nullable(),
+  detail: z.string().nullable(),
+});
 
 async function fetchLegacyConnectionStatus(
   runtimeUrl: string,
@@ -194,7 +197,11 @@ async function fetchLegacyConnectionStatus(
     clearTimeout(timeoutId);
     if (!response.ok) return null;
 
-    const data = (await response.json()) as LegacyConnectionStatus;
+    const parsed = LegacyConnectionStatusSchema.safeParse(
+      await response.json(),
+    );
+    if (!parsed.success) return null;
+    const data = parsed.data;
 
     // Translate legacy shape into the ps process tree
     const status: ManagedProcessEntry["status"] = data.is_awake
@@ -240,7 +247,9 @@ export async function checkHealth(
       return { status: `error (${response.status})`, detail: null };
     }
 
-    const data = (await response.json()) as HealthResponse;
+    const data = HealthResponseSchema
+      .catch({})
+      .parse(await response.json());
     const status = data.status || "unknown";
     return {
       status,

package/src/lib/local-hatch-lock.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "child_process";
 import { createHash, randomUUID } from "crypto";
+import { z } from "zod";
 import {
   closeSync,
   mkdirSync,
@@ -57,7 +58,7 @@ function processIsAlive(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "EPERM";
+    return errnoCode(error) === "EPERM";
   }
 }
 
@@ -87,30 +88,21 @@ function processStartedAt(pid: number): string | undefined {
   }
 }
 
+function errnoCode(error: unknown): string | undefined {
+  if (!(error instanceof Error)) return undefined;
+  if (!("code" in error) || typeof error.code !== "string") return undefined;
+  return error.code;
+}
+
+const LockOwnerFileSchema = z.object({
+  pid: z.number().int().positive(),
+  processStartedAt: z.string().min(1).optional().catch(undefined),
+  token: z.string().min(1),
+});
+
 function parseOwner(raw: string): LockOwner | undefined {
   try {
-    const parsed = JSON.parse(raw) as {
-      pid?: unknown;
-      processStartedAt?: unknown;
-      token?: unknown;
-    };
-    if (
-      typeof parsed.pid === "number" &&
-      Number.isInteger(parsed.pid) &&
-      parsed.pid > 0 &&
-      typeof parsed.token === "string" &&
-      parsed.token.length > 0
-    ) {
-      return {
-        pid: parsed.pid,
-        processStartedAt:
-          typeof parsed.processStartedAt === "string" &&
-          parsed.processStartedAt.length > 0
-            ? parsed.processStartedAt
-            : undefined,
-        token: parsed.token,
-      };
-    }
+    return LockOwnerFileSchema.parse(JSON.parse(raw));
   } catch {}
   return undefined;
 }
@@ -195,7 +187,7 @@ function acquireRecoveryClaim(
       writeOwnerFile(claimPath, owner);
       return () => releaseLock(claimPath, owner.token);
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      if (errnoCode(error) !== "EEXIST") {
         throw error;
       }
       if (
@@ -248,7 +240,7 @@ function removeStaleLock(
       unlinkSync(lockPath);
       return true;
     } catch (error) {
-      return (error as NodeJS.ErrnoException).code === "ENOENT";
+      return errnoCode(error) === "ENOENT";
     }
   } finally {
     releaseRecoveryClaim();
@@ -262,7 +254,7 @@ function releaseLock(lockPath: string, token: string): void {
   try {
     unlinkSync(lockPath);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+    if (errnoCode(error) !== "ENOENT") {
       throw error;
     }
   }
@@ -306,7 +298,7 @@ export async function withLocalHatchLock<T>(
     try {
       writeOwnerFile(lockPath, owner);
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      if (errnoCode(error) !== "EEXIST") {
         throw error;
       }
       if (removeStaleLock(lockPath, owner, liveOwnerRecoveryGraceMs)) {

package/src/lib/local-runtime-client.ts

@@ -11,6 +11,9 @@ import {
   resolveRuntimeUrl,
 } from "./runtime-url.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { z } from "zod";
+
+const RuntimeIdentitySchema = z.object({ version: z.string().min(1) });
 
 /**
  * Thrown when the local runtime returns 409 for an export/import request
@@ -66,15 +69,23 @@ async function migrationRequestHeaders(
   return bearerHeaders(token);
 }
 
-interface Raw409Body {
-  detail?: string;
+const Raw409BodySchema = z.object({
+  detail: z.string().optional(),
   // The runtime's current 409 contract nests the payload under `error`:
   //   { error: { code: "export_in_progress" | "import_in_progress", job_id } }
   // We also tolerate a legacy flat shape ({ code, job_id }) for resilience.
-  error?: string | { code?: string; job_id?: string };
-  code?: string;
-  job_id?: string;
-}
+  error: z
+    .union([
+      z.string(),
+      z.object({
+        code: z.string().optional(),
+        job_id: z.string().optional(),
+      }),
+    ])
+    .optional(),
+  code: z.string().optional(),
+  job_id: z.string().optional(),
+});
 
 /** Common 409 → MigrationInProgressError parsing used by the two POST helpers. */
 async function throwIfInProgress(
@@ -82,11 +93,11 @@ async function throwIfInProgress(
   defaultKind: "export_in_progress" | "import_in_progress",
 ): Promise<void> {
   if (response.status !== 409) return;
-  const body = (await response.json().catch(() => ({}))) as Raw409Body;
-  const nested =
-    typeof body.error === "object" && body.error !== null
-      ? body.error
-      : undefined;
+  const parsed = Raw409BodySchema.safeParse(
+    await response.json().catch(() => ({})),
+  );
+  const body = parsed.success ? parsed.data : {};
+  const nested = typeof body.error === "object" ? body.error : undefined;
   const jobId = nested?.job_id ?? body.job_id ?? "";
   const rawKind =
     nested?.code ??
@@ -355,9 +366,9 @@ export async function localRuntimeIdentity(
       `Failed to fetch runtime identity: ${response.status} ${response.statusText}`,
     );
   }
-  const body = (await response.json()) as { version?: unknown };
-  if (typeof body.version !== "string" || !body.version) {
+  const parsed = RuntimeIdentitySchema.safeParse(await response.json());
+  if (!parsed.success) {
     throw new Error("Runtime identity response missing version");
   }
-  return { version: body.version };
+  return { version: parsed.data.version };
 }

package/src/lib/ngrok.ts

@@ -11,21 +11,36 @@ import {
   saveIngressUrl,
   saveNgrokDomain,
 } from "./ingress-config.js";
-import { isJsonObject } from "./json";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { z } from "zod";
 
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
 const NGROK_POLL_TIMEOUT_MS = 15_000;
 
-interface NgrokTunnel {
-  public_url: string;
-  config?: { addr?: string };
-}
+const NgrokTunnelSchema = z.object({
+  public_url: z.string(),
+  config: z
+    .object({
+      addr: z.string().optional(),
+    })
+    .optional(),
+});
 
-interface NgrokTunnelsResponse {
-  tunnels: NgrokTunnel[];
-}
+type NgrokTunnel = z.infer<typeof NgrokTunnelSchema>;
+
+const NgrokTunnelsResponseSchema = z.object({
+  tunnels: z.array(NgrokTunnelSchema).optional(),
+});
+
+/**
+ * The ingress block of the workspace config, as read by the tunnel edge:
+ * explicitly enabled with a saved public URL.
+ */
+export const IngressConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  publicBaseUrl: z.string().optional(),
+});
 
 /**
  * Check whether ngrok is installed and accessible on the PATH.
@@ -55,8 +70,8 @@ async function queryNgrokTunnels(): Promise<NgrokTunnel[] | null> {
       signal: AbortSignal.timeout(2_000),
     });
     if (!res.ok) return null;
-    const data = (await res.json()) as NgrokTunnelsResponse;
-    return data.tunnels ?? [];
+    const parsed = NgrokTunnelsResponseSchema.safeParse(await res.json());
+    return parsed.success ? (parsed.data.tunnels ?? []) : null;
   } catch {
     return null;
   }
@@ -195,13 +210,27 @@ export async function waitForNgrokUrl(
  * Check whether an already-loaded workspace config has webhook-based
  * integrations (e.g. Telegram, Twilio) that require a public ingress URL.
  */
+const TelegramIntegrationSchema = z.object({
+  botUsername: z.unknown().optional(),
+});
+
+const TwilioIntegrationSchema = z.object({
+  accountSid: z.unknown().optional(),
+  phoneNumber: z.unknown().optional(),
+});
+
 export function hasWebhookIntegrations(
   config: Record<string, unknown>,
 ): boolean {
-  const telegram = isJsonObject(config.telegram) ? config.telegram : undefined;
-  if (telegram?.botUsername) return true;
-  const twilio = isJsonObject(config.twilio) ? config.twilio : undefined;
-  if (twilio?.accountSid || twilio?.phoneNumber) return true;
+  const telegram = TelegramIntegrationSchema.safeParse(config.telegram);
+  if (telegram.success && telegram.data.botUsername) return true;
+  const twilio = TwilioIntegrationSchema.safeParse(config.twilio);
+  if (
+    twilio.success &&
+    (twilio.data.accountSid || twilio.data.phoneNumber)
+  ) {
+    return true;
+  }
   return false;
 }
 
@@ -227,9 +256,11 @@ export function hasWebhookIntegrationsConfigured(
 function hasNonNgrokIngressUrl(workspaceDir: string): boolean {
   try {
     const config = loadRawConfig(workspaceDir);
-    const ingress = isJsonObject(config.ingress) ? config.ingress : undefined;
-    const publicBaseUrl = ingress?.publicBaseUrl;
-    if (!publicBaseUrl || typeof publicBaseUrl !== "string") return false;
+    const parsed = IngressConfigSchema.safeParse(config.ingress);
+    const publicBaseUrl = parsed.success
+      ? parsed.data.publicBaseUrl
+      : undefined;
+    if (!publicBaseUrl) return false;
     return !publicBaseUrl.includes("ngrok");
   } catch {
     return false;