pi-microsandbox 0.2.0 → 0.3.0

package/extensions/pi-msb/labels.ts

@@ -5,317 +5,132 @@ import {
   type ManagedSandboxRecord,
   type PersistedSandboxState,
   type SandboxLabelInput,
-  type StorageMode,
   type ValidatedManagedSandbox,
-  type VolumeLabelInput,
-  type VolumeRecord,
 } from "./types.ts";
 
-const STORAGE_MODES: readonly StorageMode[] = ["git", "direct", "none"];
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-
-function isStorageMode(value: unknown): value is StorageMode {
-  return typeof value === "string" && STORAGE_MODES.includes(value as StorageMode);
-}
-
 function nonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.length > 0;
 }
-
 function finiteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
 
-/**
- * SDK versions have returned labels both as maps and as entry/tuple arrays.
- * Keep that tolerance in this module so callers never need to know the SDK shape.
- */
+/** SDK versions have returned labels both as maps and as entry/tuple arrays. */
 function normalizeLabels(value: unknown): Record<string, string> | null {
   const labels: Record<string, string> = {};
-
   if (isRecord(value)) {
-    for (const [key, labelValue] of Object.entries(value)) {
-      if (!key || labelValue === null || labelValue === undefined) continue;
-      if (
-        typeof labelValue === "string" ||
-        typeof labelValue === "number" ||
-        typeof labelValue === "boolean"
-      ) {
-        labels[key] = String(labelValue);
+    for (const [key, item] of Object.entries(value)) {
+      if (key && (typeof item === "string" || typeof item === "number" || typeof item === "boolean")) {
+        labels[key] = String(item);
       }
     }
     return labels;
   }
-
   if (Array.isArray(value)) {
     for (const entry of value) {
-      let key: unknown;
-      let labelValue: unknown;
-
-      if (Array.isArray(entry)) {
-        [key, labelValue] = entry;
-      } else if (isRecord(entry)) {
-        key = entry.key ?? entry.name;
-        labelValue = entry.value;
+      const key = Array.isArray(entry) ? entry[0] : isRecord(entry) ? entry.key ?? entry.name : undefined;
+      const item = Array.isArray(entry) ? entry[1] : isRecord(entry) ? entry.value : undefined;
+      if (typeof key === "string" && key && (typeof item === "string" || typeof item === "number" || typeof item === "boolean")) {
+        labels[key] = String(item);
       }
-
-      if (
-        typeof key !== "string" ||
-        key.length === 0 ||
-        (typeof labelValue !== "string" &&
-          typeof labelValue !== "number" &&
-          typeof labelValue !== "boolean")
-      ) {
-        // A bad label entry must not make otherwise useful SDK output unusable.
-        continue;
-      }
-      labels[key] = String(labelValue);
     }
     return labels;
   }
-
   return null;
 }
 
 function rawRecord(value: unknown): Record<string, unknown> | null {
   if (isRecord(value)) return value;
-
-  // Some CLI/SDK adapters expose a record as [name, labels]. Accept this only
-  // at the normalization boundary; all public functions return object records.
-  if (
-    Array.isArray(value) &&
-    value.length >= 2 &&
-    typeof value[0] === "string"
-  ) {
+  if (Array.isArray(value) && value.length >= 2 && typeof value[0] === "string") {
     return { name: value[0], labels: value[1] };
   }
-
   return null;
 }
 
 function labelsFromRaw(raw: Record<string, unknown>): Record<string, string> | null {
-  const direct = raw.labels;
-  if (direct !== undefined) return normalizeLabels(direct);
-
-  const metadata = raw.metadata;
-  if (isRecord(metadata) && metadata.labels !== undefined) {
-    return normalizeLabels(metadata.labels);
-  }
-
-  return null;
-}
-
-function optionalString(
-  target: Record<string, unknown>,
-  key: string,
-  value: unknown,
-): void {
-  if (typeof value === "string") target[key] = value;
-  else delete target[key];
-}
-
-function optionalNumber(
-  target: Record<string, unknown>,
-  key: string,
-  value: unknown,
-): void {
-  if (finiteNumber(value)) target[key] = value;
-  else delete target[key];
+  if (raw.labels !== undefined) return normalizeLabels(raw.labels);
+  return isRecord(raw.metadata) ? normalizeLabels(raw.metadata.labels) : null;
 }
 
 export function buildSandboxLabels(input: SandboxLabelInput): Record<string, string> {
-  const labels: Record<string, string> = {
+  return {
     [LABEL_KEYS.managed]: "true",
     [LABEL_KEYS.schema]: String(STATE_SCHEMA_VERSION),
     [LABEL_KEYS.session]: input.sessionId,
-    [LABEL_KEYS.mode]: input.mode,
     [LABEL_KEYS.cwd]: input.cwd,
+    [LABEL_KEYS.root]: input.root,
+    [LABEL_KEYS.guestRoot]: input.guestRoot,
     [LABEL_KEYS.pid]: String(input.pid),
     [LABEL_KEYS.image]: input.image,
     [LABEL_KEYS.keep]: "true",
   };
-
-  if (input.mode === "git") {
-    if (!nonEmptyString(input.volumeName)) {
-      throw new Error("git sandbox labels require a volume name");
-    }
-    labels[LABEL_KEYS.volume] = input.volumeName;
-    if (input.seedBranch !== undefined && input.seedBranch !== null) {
-      labels[LABEL_KEYS.seedBranch] = input.seedBranch;
-    }
-    if (input.seedSha !== undefined && input.seedSha !== null) {
-      labels[LABEL_KEYS.seedSha] = input.seedSha;
-    }
-  }
-
-  return labels;
-}
-
-export function buildVolumeLabels(input: VolumeLabelInput): Record<string, string> {
-  const labels: Record<string, string> = {
-    [LABEL_KEYS.managed]: "true",
-    [LABEL_KEYS.schema]: String(STATE_SCHEMA_VERSION),
-    [LABEL_KEYS.session]: input.sessionId,
-    [LABEL_KEYS.cwd]: input.cwd,
-    [LABEL_KEYS.keep]: "true",
-  };
-
-  if (input.seedBranch !== undefined && input.seedBranch !== null) {
-    labels[LABEL_KEYS.seedBranch] = input.seedBranch;
-  }
-  if (input.seedSha !== undefined && input.seedSha !== null) {
-    labels[LABEL_KEYS.seedSha] = input.seedSha;
-  }
-
-  return labels;
 }
 
 export function normalizeSandboxRecord(value: unknown): ManagedSandboxRecord | null {
   const raw = rawRecord(value);
   if (!raw) return null;
-
   const labels = labelsFromRaw(raw);
   const name = raw.name ?? raw.id ?? raw.sandboxName;
   if (!labels || !nonEmptyString(name)) return null;
-
-  const normalized: Record<string, unknown> = { ...raw, name, labels };
-  optionalString(normalized, "status", raw.status ?? raw.state);
-  optionalNumber(normalized, "createdAt", raw.createdAt ?? raw.created_at);
-  return normalized as unknown as ManagedSandboxRecord;
-}
-
-export function normalizeVolumeRecord(value: unknown): VolumeRecord | null {
-  const raw = rawRecord(value);
-  if (!raw) return null;
-
-  const labels = labelsFromRaw(raw);
-  const name = raw.name ?? raw.id ?? raw.volumeName;
-  const hostPath = raw.hostPath ?? raw.path ?? raw.host_path;
-  if (!labels || !nonEmptyString(name) || !nonEmptyString(hostPath)) return null;
-
-  const normalized: Record<string, unknown> = { ...raw, name, hostPath, labels };
-  optionalString(normalized, "kind", raw.kind ?? raw.type);
-  optionalNumber(normalized, "usedBytes", raw.usedBytes ?? raw.used_bytes);
-  optionalNumber(normalized, "createdAt", raw.createdAt ?? raw.created_at);
-  return normalized as unknown as VolumeRecord;
+  const status = raw.status ?? raw.state;
+  const createdAt = raw.createdAt ?? raw.created_at;
+  return {
+    name,
+    labels,
+    ...(typeof status === "string" ? { status } : {}),
+    ...(finiteNumber(createdAt) ? { createdAt } : {}),
+  };
 }
 
 export function parseCliSandboxList(json: string): ManagedSandboxRecord[] {
   let parsed: unknown;
-  try {
-    parsed = JSON.parse(json);
-  } catch (error) {
+  try { parsed = JSON.parse(json); } catch (error) {
     throw new Error("invalid sandbox list JSON", { cause: error });
   }
-
-  let rows: unknown[];
-  if (Array.isArray(parsed)) {
-    rows = parsed;
-  } else if (isRecord(parsed) && Array.isArray(parsed.sandboxes)) {
-    rows = parsed.sandboxes;
-  } else {
-    throw new Error("invalid sandbox list shape: expected an array or {sandboxes: []}");
-  }
-
-  return rows
-    .map((row) => normalizeSandboxRecord(row))
-    .filter((row): row is ManagedSandboxRecord => row !== null);
+  const rows = Array.isArray(parsed)
+    ? parsed
+    : isRecord(parsed) && Array.isArray(parsed.sandboxes)
+      ? parsed.sandboxes
+      : null;
+  if (!rows) throw new Error("invalid sandbox list shape: expected an array or {sandboxes: []}");
+  return rows.map(normalizeSandboxRecord).filter((row): row is ManagedSandboxRecord => row !== null);
 }
 
-export function validateManagedSandbox(
-  record: ManagedSandboxRecord,
-): ValidatedManagedSandbox | null {
+export function validateManagedSandbox(record: ManagedSandboxRecord): ValidatedManagedSandbox | null {
   if (!isRecord(record) || !nonEmptyString(record.name)) return null;
-
   const labels = normalizeLabels(record.labels);
   if (!labels) return null;
-
   const sessionId = labels[LABEL_KEYS.session];
-  const mode = labels[LABEL_KEYS.mode];
   const cwd = labels[LABEL_KEYS.cwd];
-  const image = labels[LABEL_KEYS.image];
-  const pidText = labels[LABEL_KEYS.pid];
-  const volumeName = labels[LABEL_KEYS.volume];
-
+  const root = labels[LABEL_KEYS.root];
+  const guestRoot = labels[LABEL_KEYS.guestRoot];
+  const pid = labels[LABEL_KEYS.pid];
   if (
     labels[LABEL_KEYS.managed] !== "true" ||
     labels[LABEL_KEYS.schema] !== String(STATE_SCHEMA_VERSION) ||
     labels[LABEL_KEYS.keep] !== "true" ||
-    !nonEmptyString(sessionId) ||
-    !isStorageMode(mode) ||
-    !nonEmptyString(cwd) ||
-    !nonEmptyString(image) ||
-    !pidText ||
-    !/^\d+$/.test(pidText) ||
-    !Number.isSafeInteger(Number(pidText))
-  ) {
-    return null;
-  }
-
-  if (mode === "git" && !nonEmptyString(volumeName)) return null;
-  if (mode !== "git" && volumeName !== undefined) return null;
-
-  const normalized: Record<string, unknown> = {
-    ...record,
-    labels,
-    name: record.name,
-    sessionId,
-    mode,
-    cwd,
-  };
-  if (volumeName !== undefined && volumeName.length > 0) {
-    normalized.volumeName = volumeName;
-  } else {
-    delete normalized.volumeName;
-  }
-  return normalized as unknown as ValidatedManagedSandbox;
-}
-
-function validOptionalString(value: unknown): boolean {
-  return value === undefined || typeof value === "string";
-}
-
-function validOptionalNullableString(value: unknown): boolean {
-  return value === undefined || value === null || typeof value === "string";
+    !nonEmptyString(sessionId) || !nonEmptyString(cwd) || !nonEmptyString(root) ||
+    !nonEmptyString(guestRoot) || !nonEmptyString(labels[LABEL_KEYS.image]) || !pid || !/^\d+$/.test(pid) ||
+    !Number.isSafeInteger(Number(pid))
+  ) return null;
+  return { ...record, labels, sessionId, cwd, root, guestRoot };
 }
 
 function validPersistedState(value: Record<string, unknown>): boolean {
-  return (
-    value.version === STATE_SCHEMA_VERSION &&
-    nonEmptyString(value.sessionId) &&
-    nonEmptyString(value.sandboxName) &&
-    isStorageMode(value.mode) &&
-    nonEmptyString(value.cwd) &&
-    nonEmptyString(value.image) &&
-    typeof value.enabled === "boolean" &&
-    finiteNumber(value.createdAt) &&
-    validOptionalString(value.volumeName) &&
-    validOptionalString(value.volumeHostPath) &&
-    validOptionalNullableString(value.seedBranch) &&
-    validOptionalNullableString(value.seedSha)
-  );
+  return value.version === STATE_SCHEMA_VERSION &&
+    nonEmptyString(value.sessionId) && nonEmptyString(value.sandboxName) &&
+    nonEmptyString(value.cwd) && nonEmptyString(value.root) && nonEmptyString(value.guestRoot) &&
+    nonEmptyString(value.image) && typeof value.enabled === "boolean" && finiteNumber(value.createdAt);
 }
 
-export function encodeSessionState(
-  state: PersistedSandboxState,
-): PersistedSandboxState {
-  // Do not mutate a caller-owned object. Encoding always stamps the current
-  // schema so a state written by this module can never be mistaken for an old
-  // version after a future schema change.
+export function encodeSessionState(state: PersistedSandboxState): PersistedSandboxState {
   return { ...state, version: STATE_SCHEMA_VERSION };
 }
 
-export function decodeSessionState(
-  value: unknown,
-  currentSessionId: string,
-): PersistedSandboxState | null {
-  if (!isRecord(value) || value.sessionId !== currentSessionId) return null;
-  if (!validPersistedState(value)) return null;
-
-  // Preserve forward-compatible, unknown JSON fields while replacing the
-  // validated known fields with their exact runtime values.
+export function decodeSessionState(value: unknown, currentSessionId: string): PersistedSandboxState | null {
+  if (!isRecord(value) || value.sessionId !== currentSessionId || !validPersistedState(value)) return null;
   return { ...value, version: STATE_SCHEMA_VERSION } as PersistedSandboxState;
 }

package/extensions/pi-msb/locks.ts

@@ -47,18 +47,17 @@ async function lockOperations(opts: LocksOptions): Promise<LockOperations> {
 function normalizeLockInfo(value: unknown): LockInfo | null {
   if (typeof value !== "object" || value === null) return null;
   const candidate = value as Partial<LockInfo>;
-  const { version, sessionId, sandboxName, volumeName, mode, cwd, pid, createdAt } = candidate;
+  const { version, sessionId, sandboxName, cwd, root, pid, createdAt } = candidate;
   if (version !== LOCKFILE_VERSION
     || typeof sessionId !== "string" || sessionId.length === 0
     || typeof sandboxName !== "string" || sandboxName.length === 0
-    || (volumeName !== undefined && (typeof volumeName !== "string" || volumeName.length === 0))
-    || (mode !== "git" && mode !== "direct" && mode !== "none")
     || typeof cwd !== "string" || !isAbsolute(cwd)
+    || typeof root !== "string" || !isAbsolute(root)
     || typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0
     || typeof createdAt !== "number" || !Number.isFinite(createdAt)) {
     return null;
   }
-  return { version, sessionId, sandboxName, volumeName, mode, cwd, pid, createdAt };
+  return { version, sessionId, sandboxName, cwd, root, pid, createdAt };
 }
 
 function validLockInfo(value: unknown): value is LockInfo {
@@ -72,12 +71,11 @@ function lockInfoJson(info: LockInfo): string {
     version: LOCKFILE_VERSION,
     sessionId: info.sessionId,
     sandboxName: info.sandboxName,
-    mode: info.mode,
     cwd: info.cwd,
+    root: info.root,
     pid: info.pid,
     createdAt: info.createdAt,
   };
-  if (info.volumeName !== undefined) value.volumeName = info.volumeName;
   return `${JSON.stringify(value)}\n`;
 }
 

package/extensions/pi-msb/prune.ts

@@ -26,12 +26,13 @@ const MANAGED_LABELS: Readonly<Record<string, string>> = Object.freeze({
   [LABEL_KEYS.managed]: "true",
 });
 
-const REQUIRED_LABELS = [
+const CURRENT_REQUIRED_LABELS = [
   LABEL_KEYS.managed,
   LABEL_KEYS.schema,
   LABEL_KEYS.session,
-  LABEL_KEYS.mode,
   LABEL_KEYS.cwd,
+  LABEL_KEYS.root,
+  LABEL_KEYS.guestRoot,
   LABEL_KEYS.pid,
   LABEL_KEYS.image,
   LABEL_KEYS.keep,
@@ -62,17 +63,20 @@ function validateRecord(value: unknown): ManagedSandboxRecord | null {
     labels[key] = label;
   }
 
-  for (const key of REQUIRED_LABELS) {
-    if (typeof labels[key] !== "string" || labels[key].length === 0) return null;
-  }
   if (labels[LABEL_KEYS.managed] !== "true") return null;
-  if (labels[LABEL_KEYS.schema] !== String(STATE_SCHEMA_VERSION)) return null;
-  if (!/^\d+$/.test(labels[LABEL_KEYS.pid])) return null;
-  if (!Number.isSafeInteger(Number(labels[LABEL_KEYS.pid]))) return null;
-  if (labels[LABEL_KEYS.keep] !== "true") return null;
-  if (!["git", "direct", "none"].includes(labels[LABEL_KEYS.mode])) return null;
-  if (labels[LABEL_KEYS.mode] === "git" && !labels[LABEL_KEYS.volume]) return null;
-  if (labels[LABEL_KEYS.mode] !== "git" && labels[LABEL_KEYS.volume] !== undefined) return null;
+  if (!labels[LABEL_KEYS.session] || !/^\d+$/.test(labels[LABEL_KEYS.schema] ?? "")) return null;
+  if (Number(labels[LABEL_KEYS.schema]) > STATE_SCHEMA_VERSION) return null;
+
+  // Old managed schemas are removable after their session owner lock is
+  // acquired. Their storage labels are deliberately ignored: prune has no
+  // volume capability and legacy volumes must remain untouched.
+  if (labels[LABEL_KEYS.schema] === String(STATE_SCHEMA_VERSION)) {
+    for (const key of CURRENT_REQUIRED_LABELS) {
+      if (typeof labels[key] !== "string" || labels[key].length === 0) return null;
+    }
+    if (!/^\d+$/.test(labels[LABEL_KEYS.pid]) || !Number.isSafeInteger(Number(labels[LABEL_KEYS.pid]))) return null;
+    if (labels[LABEL_KEYS.keep] !== "true") return null;
+  }
 
   return {
     name: value.name,