@mycadet/cli 0.0.1 → 0.12.6-dev.202610080043.b727a33

package/node_modules/@mycadet/local-mode/src/lockfile-contract.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  KNOWN_CLOUDS,
+  pairedHostLabel,
+  parseLockfile,
+  resolveCloud,
+  SENSITIVE_KEYS,
+  type Lockfile,
+} from "./lockfile-contract";
+
+describe("parseLockfile", () => {
+  test("passes through a fully-populated lockfile", () => {
+    const raw = {
+      activeAssistant: "asst_1",
+      assistants: [
+        {
+          assistantId: "asst_1",
+          name: "Alice",
+          cloud: "cadet",
+          runtimeUrl: "http://127.0.0.1:7777",
+          hatchedAt: "2026-01-01T00:00:00.000Z",
+          organizationId: "org_1",
+          platformAssistantId: "platform-assistant-1",
+          platformBaseUrl: "https://platform.example.com",
+          platformOrganizationId: "org_1",
+          ingressUrl: "https://tunnel.example.ts.net",
+          resources: { gatewayPort: 7777, daemonPort: 7778 },
+        },
+      ],
+    };
+
+    expect(parseLockfile(raw)).toEqual(raw as Lockfile);
+  });
+
+  test("keeps entries missing only optional fields", () => {
+    const raw = {
+      activeAssistant: null,
+      assistants: [
+        { assistantId: "asst_1", cloud: "cadet", runtimeUrl: "https://x" },
+      ],
+    };
+
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toHaveLength(1);
+    expect(parsed.assistants[0]).toEqual({
+      assistantId: "asst_1",
+      cloud: "cadet",
+      runtimeUrl: "https://x",
+    });
+  });
+
+  test("salvages a legacy entry that has only an assistantId", () => {
+    // The oldest persisted entries carry just the identity; the CLI fills the
+    // rest in lazily. assistantId is the only required field, so the entry must
+    // survive — normalized to the default `local` cloud.
+    const parsed = parseLockfile({
+      activeAssistant: "asst_1",
+      assistants: [{ assistantId: "asst_1" }],
+    });
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local" },
+    ]);
+  });
+
+  test("salvages an entry whose cloud and runtimeUrl are absent", () => {
+    // Older CLI builds predate the `cloud` field and persisted the runtime URL
+    // under a different key (`localUrl`), so a real on-disk entry can lack both
+    // modeled fields. It must still be returned, normalized to `local`.
+    const parsed = parseLockfile({
+      activeAssistant: null,
+      assistants: [
+        { assistantId: "asst_1", localUrl: "http://127.0.0.1:7777" },
+      ],
+    });
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local" },
+    ]);
+  });
+
+  test("drops malformed entries but salvages valid siblings", () => {
+    const raw = {
+      activeAssistant: "asst_ok",
+      assistants: [
+        { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+        { cloud: "local", runtimeUrl: "http://b" }, // missing assistantId
+        { assistantId: 42, cloud: "local", runtimeUrl: "http://c" }, // wrong type
+        "not-an-object",
+      ],
+    };
+
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_ok", cloud: "local", runtimeUrl: "http://a" },
+    ]);
+    expect(parsed.activeAssistant).toBe("asst_ok");
+  });
+
+  test("accepts (does not reject) entries with unknown fields from a newer writer", () => {
+    const raw = {
+      activeAssistant: "asst_1",
+      schemaVersion: 99, // unknown top-level field from a newer writer
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          futureField: { nested: true }, // unknown entry field
+        },
+      ],
+    };
+
+    // A newer writer's extra fields must never make an older reader reject the
+    // entry. The entry survives with its modeled fields; the wire value is the
+    // validated shape (extra fields are stripped from it — the on-disk file
+    // keeps them, see lockfile.test.ts).
+    const parsed = parseLockfile(raw);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local", runtimeUrl: "http://a" },
+    ]);
+    expect(parsed.activeAssistant).toBe("asst_1");
+  });
+
+  test("defaults missing or non-array assistants to an empty list", () => {
+    expect(parseLockfile({}).assistants).toEqual([]);
+    expect(parseLockfile({ assistants: "nope" }).assistants).toEqual([]);
+  });
+
+  test("coerces a non-string activeAssistant to null", () => {
+    expect(
+      parseLockfile({ assistants: [], activeAssistant: 7 }).activeAssistant,
+    ).toBeNull();
+    expect(parseLockfile({ assistants: [] }).activeAssistant).toBeNull();
+  });
+
+  test("returns the empty lockfile for non-object input", () => {
+    const empty: Lockfile = { assistants: [], activeAssistant: null };
+    expect(parseLockfile(null)).toEqual(empty);
+    expect(parseLockfile(undefined)).toEqual(empty);
+    expect(parseLockfile("[]")).toEqual(empty);
+    expect(parseLockfile(123)).toEqual(empty);
+  });
+
+  test("drops a mistyped optional field but keeps the entry", () => {
+    // assistantId is the only required field. A mistyped optional field is
+    // dropped from the result, but the entry survives on the strength of its
+    // identity. (A mistyped `cloud` is dropped, then re-normalized to `local`.)
+    const raw = {
+      assistants: [
+        { assistantId: "asst_1", cloud: 7, runtimeUrl: "http://a" }, // cloud not a string
+        { assistantId: "asst_2", cloud: "local", runtimeUrl: 7 }, // runtimeUrl not a string
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local", runtimeUrl: "http://a" },
+      { assistantId: "asst_2", cloud: "local" },
+    ]);
+  });
+
+  test("drops an entry only when its assistantId is missing or mistyped", () => {
+    const raw = {
+      assistants: [
+        { cloud: "local", runtimeUrl: "http://a" }, // no assistantId
+        { assistantId: 42, cloud: "local" }, // assistantId not a string
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([]);
+  });
+
+  test("keeps organizationId on platform entries and drops it when mistyped", () => {
+    // Platform assistants carry their owning org so the host proxy can scope
+    // requests without guessing; local entries simply omit it.
+    const raw = {
+      assistants: [
+        { assistantId: "asst_1", cloud: "cadet", organizationId: "org_1" },
+        { assistantId: "asst_2", cloud: "cadet", organizationId: 7 }, // mistyped
+        { assistantId: "asst_3", cloud: "local" }, // local, no org
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "asst_1", cloud: "cadet", organizationId: "org_1" },
+      { assistantId: "asst_2", cloud: "cadet" },
+      { assistantId: "asst_3", cloud: "local" },
+    ]);
+  });
+
+  test("keeps a well-typed ingressUrl and drops it when mistyped", () => {
+    // The tunnel-recorded public URL rides the entry so remote-web pairing
+    // surfaces can prefill it; a mistyped value is dropped, entry preserved.
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          ingressUrl: "https://tunnel.example.ts.net",
+        },
+        { assistantId: "asst_2", cloud: "local", ingressUrl: 7 }, // mistyped
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      {
+        assistantId: "asst_1",
+        cloud: "local",
+        ingressUrl: "https://tunnel.example.ts.net",
+      },
+      { assistantId: "asst_2", cloud: "local" },
+    ]);
+  });
+
+  test("drops a resources object missing its numeric ports", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          resources: { gatewayPort: "7777", daemonPort: 7778 },
+        },
+      ],
+      activeAssistant: null,
+    };
+    const [assistant] = parseLockfile(raw).assistants;
+    expect(assistant).toEqual({
+      assistantId: "asst_1",
+      cloud: "local",
+      runtimeUrl: "http://a",
+    });
+    expect(assistant?.resources).toBeUndefined();
+  });
+
+  test("keeps local runtime resource fields when well-typed", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          resources: {
+            gatewayPort: 7777,
+            daemonPort: 7778,
+            runtimeVersion: "v0.8.13",
+            runtimeInstallDir: "/tmp/cadet/runtime/0.8.13",
+          },
+        },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants[0]?.resources).toEqual({
+      gatewayPort: 7777,
+      daemonPort: 7778,
+      runtimeVersion: "v0.8.13",
+      runtimeInstallDir: "/tmp/cadet/runtime/0.8.13",
+    });
+  });
+
+  test("strips sensitive and host-only fields from resources", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          resources: {
+            instanceDir: "/data",
+            gatewayPort: 7777,
+            daemonPort: 7778,
+            runtimeVersion: "v0.8.13",
+            runtimeInstallDir: "/tmp/cadet/runtime/0.8.13",
+            qdrantPort: 7779,
+            cesPort: 7780,
+            signingKey: "hunter2",
+          },
+        },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants[0]?.resources).toEqual({
+      instanceDir: "/data",
+      gatewayPort: 7777,
+      daemonPort: 7778,
+      runtimeVersion: "v0.8.13",
+      runtimeInstallDir: "/tmp/cadet/runtime/0.8.13",
+    });
+  });
+
+  test("resolves cloud from legacy remote markers when the field is absent", () => {
+    // Pre-`cloud` remote entries encode topology in `project` (gcp) / `sshUser`
+    // (custom). The parser resolves these so a cloudless remote entry is never
+    // mistaken for a local one; a cloudless entry with no markers normalizes to
+    // `local`. The raw markers are not carried through.
+    const raw = {
+      assistants: [
+        { assistantId: "gcp_1", project: "my-proj", runtimeUrl: "https://a" },
+        { assistantId: "ssh_1", sshUser: "deploy", runtimeUrl: "https://b" },
+        { assistantId: "local_1", runtimeUrl: "http://localhost:7830" },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "gcp_1", cloud: "gcp", runtimeUrl: "https://a" },
+      { assistantId: "ssh_1", cloud: "custom", runtimeUrl: "https://b" },
+      {
+        assistantId: "local_1",
+        cloud: "local",
+        runtimeUrl: "http://localhost:7830",
+      },
+    ]);
+  });
+
+  test("prefers an explicit cloud over legacy remote markers", () => {
+    const raw = {
+      assistants: [
+        { assistantId: "a", cloud: "cadet", project: "stale-proj" },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "a", cloud: "cadet" },
+    ]);
+  });
+});
+
+describe("resolveCloud", () => {
+  test("prefers an explicit cloud", () => {
+    expect(resolveCloud({ cloud: "cadet", project: "p", sshUser: "u" })).toBe(
+      "cadet",
+    );
+  });
+
+  test("falls back to legacy markers, then local", () => {
+    expect(resolveCloud({ project: "p" })).toBe("gcp");
+    expect(resolveCloud({ sshUser: "u" })).toBe("custom");
+    expect(resolveCloud({})).toBe("local");
+    expect(resolveCloud({ cloud: "" })).toBe("local");
+  });
+});
+
+describe("pairedHostLabel", () => {
+  test("names the remote host from a parseable runtimeUrl", () => {
+    expect(pairedHostLabel("https://tunnel.example.com")).toBe(
+      "Paired · tunnel.example.com",
+    );
+    expect(pairedHostLabel("https://remote-host.example:8443")).toBe(
+      "Paired · remote-host.example",
+    );
+  });
+
+  test("falls back to plain Paired for a missing or unparseable runtimeUrl", () => {
+    expect(pairedHostLabel(undefined)).toBe("Paired");
+    expect(pairedHostLabel("")).toBe("Paired");
+    expect(pairedHostLabel("not a url")).toBe("Paired");
+  });
+});
+
+describe("taxonomy", () => {
+  test("KNOWN_CLOUDS covers the documented topologies", () => {
+    expect(KNOWN_CLOUDS).toEqual([
+      "local",
+      "docker",
+      "apple-container",
+      "cloud",
+      "cadet",
+      "gcp",
+      "aws",
+      "custom",
+      "paired",
+    ]);
+  });
+
+  test("SENSITIVE_KEYS lists the redacted secrets", () => {
+    expect(SENSITIVE_KEYS).toEqual([
+      "signingKey",
+      "bearerToken",
+      "guardianBootstrapSecret",
+    ]);
+  });
+});

package/node_modules/@mycadet/local-mode/src/lockfile-contract.ts

@@ -0,0 +1,283 @@
+/**
+ * The lockfile wire contract — one Zod schema that is the single source of truth
+ * for an assistant entry's shape, its validation, the `cloud` taxonomy, the
+ * normalization, and the redaction policy.
+ *
+ * Kept in its own module, exported from the package as `./contract`, so
+ * consumers import the contract without pulling in the host I/O graph
+ * (`node:fs`, the CLI resolver). The CLI, the host I/O layer, the Electron and
+ * dev-server bridges, and the renderer all depend on this one definition. It
+ * references no node built-ins — the renderer bundles it directly — and `zod`
+ * is its only third-party import.
+ *
+ * The lockfile is written by the Cadet CLI and read across the macOS↔CLI
+ * boundary, which do not release in lockstep, so the parser is permissive: it
+ * validates the modeled fields, salvages an entry on the strength of its
+ * `assistantId` alone (dropping individual malformed optional fields rather
+ * than the whole entry), and ignores unknown fields so a newer writer never
+ * breaks an older reader. Unknown fields are preserved on disk by the write
+ * path (see `lockfile.ts`); the validated value carries only the modeled,
+ * renderer-safe shape.
+ */
+import { z } from "zod";
+
+/**
+ * Known deployment topologies. `cloud` is stored as a free string on disk for
+ * forward-compatibility — an older reader must tolerate a newer writer's value
+ * — but the known set is enumerated here so callers switch on it exhaustively
+ * instead of matching string literals scattered across the codebase:
+ *  - `local` — on-machine daemon
+ *  - `docker` — local container
+ *  - `apple-container` — macOS-app-managed container
+ *  - `cloud` — platform-managed (uses the X-Session-Token auth path);
+ *    canonical since the Cadet rebrand
+ *  - `cadet` — legacy alias of `cloud`, still read from existing lockfiles
+ *  - `gcp` / `aws` / `custom` — remote, SSH-managed
+ *  - `paired` — a remote assistant paired from another machine
+ */
+export const KNOWN_CLOUDS = [
+  "local",
+  "docker",
+  "apple-container",
+  "cloud",
+  "cadet",
+  "gcp",
+  "aws",
+  "custom",
+  "paired",
+] as const;
+export type KnownCloud = (typeof KNOWN_CLOUDS)[number];
+export type Cloud = KnownCloud | (string & {});
+
+/**
+ * Keys that must never cross the host→renderer boundary. Stripped from raw
+ * lockfile JSON before it leaves a host (see `stripSensitiveFields`) and absent
+ * from the renderer-facing schema below; the CLI's extended type is the only
+ * place they are modeled.
+ */
+export const SENSITIVE_KEYS = [
+  "signingKey",
+  "bearerToken",
+  "guardianBootstrapSecret",
+] as const;
+
+/**
+ * Resolve an entry's deployment topology from its raw on-disk fields. Prefers
+ * an explicit `cloud`, then the legacy markers that predate the field
+ * (`project` ⇒ gcp, `sshUser` ⇒ custom), and defaults to "local". This is the
+ * one definition every reader shares, so a cloudless entry is classified
+ * identically by the CLI, the host I/O layer, and the renderer.
+ */
+export function resolveCloud(raw: {
+  cloud?: unknown;
+  project?: unknown;
+  sshUser?: unknown;
+}): Cloud {
+  if (typeof raw.cloud === "string" && raw.cloud) return raw.cloud;
+  if (typeof raw.project === "string" && raw.project) return "gcp";
+  if (typeof raw.sshUser === "string" && raw.sshUser) return "custom";
+  return "local";
+}
+
+/**
+ * Whether a cloud value denotes the platform-managed topology. `cloud` is
+ * canonical; `cadet` is the legacy spelling kept for entries written before
+ * the rebrand. Every reader that used to compare `=== "cadet"` switches on
+ * this instead so both spellings dispatch identically.
+ */
+export function isManagedCloud(cloud: unknown): boolean {
+  return cloud === "cloud" || cloud === "cadet";
+}
+
+/**
+ * Whether an entry's `runtimeUrl` is one a serving host can forward to: an
+ * absolute http(s) URL. Shared by the renderer's paired-gateway URL derivation
+ * and the host-side paired allowlist reader so the two can't drift.
+ */
+export function isUsableRuntimeUrl(url: unknown): boolean {
+  if (typeof url !== "string" || url === "") {
+    return false;
+  }
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * User-facing hosting label for a paired entry: "Paired · <hostname>" when
+ * `runtimeUrl` names the remote host, plain "Paired" otherwise. Shared by the
+ * macOS tray switcher and the web chooser so their renderings cannot drift.
+ */
+export function pairedHostLabel(runtimeUrl: string | undefined): string {
+  if (runtimeUrl) {
+    try {
+      return `Paired · ${new URL(runtimeUrl).hostname}`;
+    } catch {
+      // Unparseable runtimeUrl: plain "Paired".
+    }
+  }
+  return "Paired";
+}
+
+/**
+ * Clouds whose gateway listens on a loopback port of this machine: the
+ * on-machine daemon ("local") and local Docker instances ("docker").
+ */
+export const LOOPBACK_GATEWAY_CLOUDS: readonly Cloud[] = ["local", "docker"];
+
+export function isLoopbackGatewayCloud(cloud: Cloud): boolean {
+  return LOOPBACK_GATEWAY_CLOUDS.includes(cloud);
+}
+
+/**
+ * The loopback gateway port recorded for an assistant entry:
+ * `resources.gatewayPort` when present, else the port of a loopback
+ * `runtimeUrl` (how docker hatch records its published gateway). A
+ * non-loopback `runtimeUrl` yields nothing.
+ */
+export function getLoopbackGatewayPort(entry: {
+  resources?: { gatewayPort?: number };
+  runtimeUrl?: string;
+}): number | undefined {
+  const recorded = entry.resources?.gatewayPort;
+  if (recorded != null) {
+    return recorded;
+  }
+  if (!entry.runtimeUrl) {
+    return undefined;
+  }
+  try {
+    const url = new URL(entry.runtimeUrl);
+    if (url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+      return undefined;
+    }
+    const port = Number(url.port);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Per-instance resources for a local assistant: the renderer-facing subset of
+ * ports, the instance directory, and the local runtime install metadata.
+ * Richer host-only fields (other ports, the signing key) live on the CLI's
+ * type and are stripped from this shape.
+ */
+export const LocalAssistantResourcesSchema = z.object({
+  instanceDir: z.string().optional(),
+  gatewayPort: z.number(),
+  daemonPort: z.number(),
+  runtimeVersion: z.string().optional(),
+  runtimeInstallDir: z.string().optional(),
+});
+export type LocalAssistantResources = z.infer<
+  typeof LocalAssistantResourcesSchema
+>;
+
+/**
+ * The renderer-safe shape of one assistant entry. `assistantId` is the only
+ * required field — the identity every reader looks entries up by — and every
+ * other field is salvaged by {@link parseLockfile}. The CLI extends this with
+ * its host-only and sensitive fields; this base carries only what is safe to
+ * surface in the renderer.
+ */
+export const LockfileAssistantSchema = z.object({
+  assistantId: z.string(),
+  name: z.string().optional(),
+  cloud: z.string().optional(),
+  runtimeUrl: z.string().optional(),
+  hatchedAt: z.string().optional(),
+  /**
+   * When this assistant finished first-run onboarding. Absent for entries that
+   * predate the record, which fall back to hatch age (see the web client's
+   * `onboarded-assistant.ts`).
+   */
+  onboardedAt: z.string().optional(),
+  /** Owning org for platform assistants; absent for local ones. */
+  organizationId: z.string().optional(),
+  /** Platform assistant UUID for a self-hosted local assistant registration. */
+  platformAssistantId: z.string().optional(),
+  /** Platform base URL used for a self-hosted local assistant registration. */
+  platformBaseUrl: z.string().optional(),
+  /** Platform organization UUID used for a self-hosted local assistant registration. */
+  platformOrganizationId: z.string().optional(),
+  /**
+   * Public https URL a `cadet tunnel` provider recorded for this assistant
+   * (mirrored from the workspace ingress config). A public address, so it is
+   * renderer-safe: remote-web pairing surfaces (the `cadet pair` flow, the web
+   * "Pair a device" card) default to it instead of asking the user to retype it.
+   */
+  ingressUrl: z.string().optional(),
+  resources: LocalAssistantResourcesSchema.optional(),
+});
+
+/**
+ * A validated, normalized assistant entry. Identical to the schema's inferred
+ * shape except `cloud` is always present — {@link parseLockfile} resolves it for
+ * every entry (defaulting to "local"), so readers never special-case its
+ * absence.
+ */
+export type LockfileAssistant = Omit<
+  z.infer<typeof LockfileAssistantSchema>,
+  "cloud"
+> & { cloud: Cloud };
+
+export interface Lockfile {
+  assistants: LockfileAssistant[];
+  activeAssistant: string | null;
+}
+
+/**
+ * Renderer-facing result of a lockfile write, returned across the host bridge.
+ * Carries no HTTP-style status — hosts map that away because the renderer
+ * surfaces failures by message alone.
+ */
+export type LockfileWriteResult =
+  | { ok: true; lockfile: Lockfile }
+  | { ok: false; error: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate and normalize a single entry. Returns null only when `assistantId`
+ * is missing or not a string; any other entry is salvaged — each modeled field
+ * is copied only when present and well-typed (a malformed optional field is
+ * dropped without discarding the entry), unknown fields are ignored, and
+ * `cloud` is resolved from the raw markers so a cloudless remote entry is never
+ * mistaken for a local one and a markerless entry defaults to "local".
+ */
+function parseAssistant(raw: unknown): LockfileAssistant | null {
+  if (!isRecord(raw) || typeof raw.assistantId !== "string") return null;
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(LockfileAssistantSchema.shape)) {
+    const result = (field as z.ZodType).safeParse(raw[key]);
+    if (result.success && result.data !== undefined) out[key] = result.data;
+  }
+  out.cloud = resolveCloud(raw);
+  return out as LockfileAssistant;
+}
+
+/**
+ * Coerce parsed JSON into a validated {@link Lockfile}. Total and non-throwing:
+ * entries that fail validation are dropped (one malformed entry can't discard
+ * the file), a missing or non-array `assistants` becomes `[]`, and a non-string
+ * `activeAssistant` becomes null.
+ */
+export function parseLockfile(raw: unknown): Lockfile {
+  const root = isRecord(raw) ? raw : {};
+  const rawAssistants = Array.isArray(root.assistants) ? root.assistants : [];
+  const assistants: LockfileAssistant[] = [];
+  for (const entry of rawAssistants) {
+    const parsed = parseAssistant(entry);
+    if (parsed) assistants.push(parsed);
+  }
+  const activeAssistant =
+    typeof root.activeAssistant === "string" ? root.activeAssistant : null;
+  return { assistants, activeAssistant };
+}