stim 1.21.0 → 1.22.0

package/dist/api.d.mts

@@ -1,23 +1,51 @@
-import { a as DoctorPlatform, c as AndroidFacts, d as IosFacts, i as TailnetMachineIo, l as CcacheActivity, n as BuildMachinesInspection, o as Finding, r as GeneratedTickets, u as CompilationCacheActivity } from "./client-B7QVOlCr.mjs";
-import { i as WorkspaceLaunchPlatform } from "./settings-DkdmlelE.mjs";
-import "./exec-H20xSg2T.mjs";
-import { t as IdleDevice } from "./idle-BVeRGroT.mjs";
-import { readFileSync, writeFileSync } from "node:fs";
-import { StimContext, hostSimulatorArch } from "@stim-cli/core";
-import { ANDROID_EMULATOR_APPS, AgentDeviceUsage, ArchivedWorkspace, MacosBuild, MaintenanceAction, MaintenanceMode, MaintenancePressure, MaintenanceStatus, NdjsonRecord, SettingScope, SettingWriteResult, SettingsPayload, SimRuntimeUsage, StatsReport, SwiftpmCacheUsage, WebBrowserState, WebViewport, machineCapacity } from "@stim-cli/core/state";
+import { _ as IosFacts, a as BuildMachinesInspection, d as DoctorPlatform, f as Finding, g as CompilationCacheActivity, h as CcacheActivity, m as AndroidFacts, n as WebLaunched, o as GeneratedTickets, s as TailnetMachineIo, u as BudgetReport } from "./android-project-DVWyCbWU.mjs";
+import { a as WorkspaceLaunchPlatform } from "./ios-CDvlmUs7.mjs";
+import "./exec-DnYc4HGH.mjs";
+import "./pull-request-eODyIqZF.mjs";
+import { t as IdleDevice } from "./idle-C4cZ757K.mjs";
+import { StimContext } from "@stim-cli/core";
+import { AgentDeviceUsage, ArchivedWorkspace, BuildPlanPayload, MacosBuild, MacosBuildPlanPayload, MaintenanceAction, MaintenanceMode, MaintenancePressure, MaintenanceStatus, NdjsonRecord, SettingScope, SettingWriteResult, SettingsPayload, SimRuntimeUsage, StatsReport, SwiftpmCacheUsage, WebBrowserState } from "@stim-cli/core/state";
+import { statSync } from "fs";
 import { Command } from "commander";
-import "@expo/fingerprint";
-import { loadCacheProvider } from "@stim-cli/cache";
 import { ToolchainEntry } from "@stim-cli/core/toolchain";
-import { ChildProcess } from "node:child_process";
-import { HelloResult } from "@stim-cli/core/protocol";
-//#region src/commands/android/build.d.ts
-interface AndroidBuildOptions {
-  variant?: string;
-  abi?: "arm64-v8a" | "armeabi-v7a" | "x86" | "x86_64" | "all";
-  buildCache?: boolean;
-  remoteBuild?: string;
+import { HelloResult, PlatformBuildOptions, PlatformRunOptions } from "@stim-cli/core/protocol";
+//#region src/engine/device-lease.d.ts
+type LeasePlatform = "ios" | "android";
+interface ReleasedLease {
+  platform: LeasePlatform;
+  id: string;
+  deviceName: string | null;
+  expiresAt: string;
 }
+//#endregion
+//#region src/commands/gc/results.d.ts
+type GcResultKind = "archive" | "device" | "parkedDevice" | "parkedHostedDevice" | "idleDevice" | "deviceRecord" | "workspaceOutputs" | "recording" | "workspaceDirectory" | "project" | "buildLock" | "buildSlot" | "deviceLease" | "easSession" | "worktree" | "cache" | "statusCache" | "tempLeftover" | "watchmanRoot" | "watchman" | "gradleDaemon" | "gradleVersion" | "kotlinDaemon";
+type GcResultStatus = "done" | "kept" | "failed";
+interface GcResult {
+  kind: GcResultKind;
+  status: GcResultStatus;
+  label: string;
+  id: string | null;
+  bytes: number | null;
+  detail: string | null;
+}
+//#endregion
+//#region src/supervisor/start-facts.d.ts
+interface StartFacts {
+  port: number;
+  supervisorPid: number | null;
+  mode: string | null;
+  logsDir: string;
+  agentDevice?: {
+    stateDir: string;
+  };
+  alreadyRunning: boolean;
+}
+//#endregion
+//#region src/commands/android/build.d.ts
+type AndroidBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "android";
+}>, "platform">;
 interface AndroidBuildFacts {
   /** Owned copy, retained with this workspace until explicitly removed. */
   apkPath: string;
@@ -40,9 +68,9 @@ interface AndroidBuildFacts {
 }
 //#endregion
 //#region src/commands/macos-build.d.ts
-interface MacosBuildOptions {
-  remoteBuild?: string;
-}
+type MacosBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "macos";
+}>, "platform">;
 interface MacosBuildFacts {
   product: string;
   /** Owned copy, retained with this workspace until explicitly removed. */
@@ -59,14 +87,9 @@ interface MacosBuildFacts {
 }
 //#endregion
 //#region src/commands/ios/build.d.ts
-interface IosBuildOptions {
-  configuration?: string;
-  scheme?: string;
-  /** Simulator architecture. Defaults to the host for Debug, or all architectures otherwise. */
-  arch?: "arm64" | "x86_64" | "all";
-  buildCache?: boolean;
-  remoteBuild?: string;
-}
+type IosBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "ios";
+}>, "platform">;
 interface IosBuildFacts {
   /** Owned simulator app, retained with this workspace until explicitly removed. */
   appPath: string;
@@ -89,15 +112,6 @@ interface IosBuildFacts {
   };
 }
 //#endregion
-//#region src/engine/device-lease.d.ts
-type LeasePlatform = "ios" | "android";
-interface ReleasedLease {
-  platform: LeasePlatform;
-  id: string;
-  deviceName: string | null;
-  expiresAt: string;
-}
-//#endregion
 //#region src/commands/stop.d.ts
 interface SupervisorOutcome {
   status: string;
@@ -165,9 +179,6 @@ interface TunnelOutcome {
   reason?: string;
 }
 //#endregion
-//#region src/web/launch.d.ts
-type WebLaunched = true | "bundling" | "unverified";
-//#endregion
 //#region src/commands/web.d.ts
 interface WebFacts extends WebBrowserState {
   platform: "web";
@@ -183,42 +194,20 @@ interface WebFacts extends WebBrowserState {
 //#region src/maintenance/status.d.ts
 declare function maintenanceStatus(env?: NodeJS.ProcessEnv): MaintenanceStatus;
 //#endregion
-//#region src/commands/gc/results.d.ts
-type GcResultKind = "archive" | "device" | "parkedDevice" | "parkedHostedDevice" | "idleDevice" | "deviceRecord" | "workspaceOutputs" | "recording" | "workspaceDirectory" | "project" | "buildLock" | "buildSlot" | "deviceLease" | "easSession" | "worktree" | "cache" | "statusCache" | "tempLeftover" | "watchmanRoot" | "watchman" | "gradleDaemon" | "gradleVersion" | "kotlinDaemon";
-type GcResultStatus = "done" | "kept" | "failed";
-interface GcResult {
-  kind: GcResultKind;
-  status: GcResultStatus;
-  label: string;
-  id: string | null;
-  bytes: number | null;
-  detail: string | null;
+//#region src/diagnostics/stim-installations.d.ts
+interface StimInstallation {
+  path: string;
+  realPath: string;
+  version: string | null;
 }
-//#endregion
-//#region src/budget.d.ts
-type ReclaimStepName = "idle-devices" | "idle-dev-servers" | "workspace-outputs" | "stale-cache-entries";
-interface ReclaimedStep {
-  step: ReclaimStepName;
-  targets: string[];
-  failures: number;
-  freedMb?: number;
-}
-interface BudgetReport {
-  budget: {
-    minFreeDiskGb: number;
-    hardFloorDiskGb: number;
-    maxCommittedMemoryGb: number;
-    maxLiveWorkspaces: number;
-  };
-  volumes: {
-    volume: string;
-    freeGb: number;
-  }[];
-  memory: {
-    committedGb: number;
-    liveWorkspaces: number;
-  } | null;
-  plan: ReclaimedStep[];
+interface StimVersionReport {
+  runningVersion: string;
+  runningPath: string | null;
+  resolved: StimInstallation | null;
+  installations: StimInstallation[];
+  versions: string[];
+  highestVersion: string | null;
+  resolvedIsOlder: boolean;
 }
 //#endregion
 //#region src/device-host/machines.d.ts
@@ -246,22 +235,6 @@ declare function inspectDeviceHostMachines({ fix, version, tickets, operation }:
   operation?: StimContext;
 }, io?: TailnetMachineIo, entries?: string[] | null): Promise<Inspection>;
 //#endregion
-//#region src/diagnostics/stim-installations.d.ts
-interface StimInstallation {
-  path: string;
-  realPath: string;
-  version: string | null;
-}
-interface StimVersionReport {
-  runningVersion: string;
-  runningPath: string | null;
-  resolved: StimInstallation | null;
-  installations: StimInstallation[];
-  versions: string[];
-  highestVersion: string | null;
-  resolvedIsOlder: boolean;
-}
-//#endregion
 //#region src/commands/doctor.d.ts
 /**
  * Where the toolchain a process without a login shell, such as stim-server under Stim Desktop, finds each tool,
@@ -847,30 +820,7 @@ interface StimOptions {
    */
   onProgress?: (event: StimProgress) => void;
 }
-interface NativeRunOptions {
-  slot?: string;
-  metroCheck?: boolean;
-  buildCache?: boolean;
-  remoteBuild?: string;
-}
-type StimRunOptions = ((NativeRunOptions & {
-  platform: "ios";
-  configuration?: string;
-  scheme?: string;
-  deviceType?: string;
-  runtime?: string;
-}) | (NativeRunOptions & {
-  platform: "android";
-  variant?: string;
-  systemImage?: string;
-  deviceProfile?: string;
-}) | {
-  platform: "macos";
-  remoteBuild?: string;
-} | {
-  platform: "web";
-  headed?: boolean;
-}) & {
+type StimRunOptions = PlatformRunOptions & {
   signal?: AbortSignal;
 };
 type StimRunResult = {
@@ -887,7 +837,7 @@ type StimRunResult = {
     bundleId: string;
     executable: string;
     pid: number | null;
-    launched: boolean;
+    launched: boolean | "unverified";
     build: MacosBuild;
     logs: {
       dir: string;
@@ -919,8 +869,19 @@ type StimBuildResult = {
 interface StimStopOptions {
   slot?: string;
   signal?: AbortSignal;
+  /** Runs once with the resolved workspace before teardown; throwing refuses the operation. */
+  beforeStop?: (workspace: string) => void;
 }
 type StimStopResult = StopResult;
+interface StimStartOptions {
+  remote?: boolean;
+  resetCache?: boolean;
+  waitSeconds?: number;
+  signal?: AbortSignal;
+  /** Runs once with the resolved app before usage recording or startup; throwing refuses the operation. */
+  beforeStart?: (workspace: string) => void;
+}
+type StimStartResult = StartFacts;
 interface StimReloadOptions {
   platform?: ReloadPlatform;
   signal?: AbortSignal;
@@ -951,16 +912,57 @@ interface StimLogsOptions {
 interface StimReadOptions {
   signal?: AbortSignal;
 }
+type StimPlanOptions = ({
+  platform: "ios" | "android";
+  slot?: string;
+} | {
+  platform: "macos";
+}) & StimReadOptions;
+type StimPlan = BuildPlanPayload | MacosBuildPlanPayload;
 interface StimDoctorOptions extends StimReadOptions {
   platform?: "ios" | "android";
   /** Records completed iOS/Android checks in project state. Defaults to false for report-only reads. */
   record?: boolean;
 }
+interface StimMachineAccessOptions extends StimReadOptions {
+  /** The setup ticket generated by the caller. Omit to reuse or generate tickets for the configured machines. */
+  ticket?: string;
+}
 type StimDoctorReport = DoctorReport;
 type StimGcOptions = GcReadOptions & StimReadOptions;
 type StimGcReport = Exclude<GcPayload, {
   code: string;
 }>;
+type StimGcMutationOptions = StimGcOptions & {
+  delete?: boolean;
+  /** Shuts down owned devices idle for at least this many milliseconds, including without `delete`. */
+  idleMs?: number;
+};
+interface StimGcMutationResult {
+  report: StimGcReport;
+  exitCode: 0 | 1;
+}
+interface StimWorktreeWarmOptions extends StimReadOptions {
+  /** Called for each canonical workspace in the resolved warming scope before effects; throwing refuses warming. */
+  beforeWarm?: (workspace: string) => void;
+}
+interface StimWorktreeWarmResult {
+  exitCode: 0 | 1;
+}
+interface StimWorktreeRemoveOptions extends StimReadOptions {
+  /** Called for each canonical workspace in the resolved cleanup scope before effects; throwing refuses cleanup. */
+  beforeRemove?: (workspace: string) => void;
+  /** Defaults to the client's projectRoot. Relative paths resolve against that directory. */
+  target?: string;
+  /** Allows removal with uncommitted or unpushed work or initialized submodules, as CLI --force does. */
+  force?: boolean;
+}
+interface StimWorktreeRemoveResult {
+  /** True once the linked Git worktree is removed, even if later branch cleanup fails. */
+  removed: boolean;
+  /** Source checkout environment cleanup can succeed without removing the checkout. */
+  exitCode: 0 | 1;
+}
 type StimSettings = SettingsPayload;
 type StimSettingWriteResult = SettingWriteResult;
 interface StimSettingWriteOptions extends StimReadOptions {
@@ -971,12 +973,24 @@ interface StimSettingWriteOptions extends StimReadOptions {
 type StimStats = StatsReport;
 interface StimClient {
   readonly projectRoot: string;
+  /** Starts or reuses the app's dev server; resources remain workspace-owned until stop is called. */
+  start(options?: StimStartOptions): Promise<StimStartResult>;
   /** Returns this home's persistent nonsecret identity, initializing it under the config lock on first use. */
   identity(options?: StimReadOptions): Promise<string>;
   /** Reads findings with a 60 second execution and 35 second cleanup budget. Never repairs; records a completed check only with `record: true`. */
   doctor(options?: StimDoctorOptions): Promise<StimDoctorReport>;
+  /** Requests build/device-host approval with a 120 second execution and 35 second cleanup budget. Never grants access or repairs project state. */
+  requestMachineAccess(options?: StimMachineAccessOptions): Promise<StimDoctorReport>;
+  /** Predicts the configured native build with a 60 second execution and 35 second cleanup budget; never builds or launches. */
+  plan(options: StimPlanOptions): Promise<StimPlan>;
   /** Reads the GC dry-run report with a 60 second execution and 35 second cleanup budget. Never deletes, repairs or shuts down idle resources. */
   gc(options?: StimGcOptions): Promise<StimGcReport>;
+  /** Executes requested GC actions, preserving partial results and waiting for owned cleanup before releasing maintenance admission. */
+  collectGarbage(options?: StimGcMutationOptions): Promise<StimGcMutationResult>;
+  /** Copies missing ignored state from the source checkout into this linked worktree. */
+  warmWorktree(options?: StimWorktreeWarmOptions): Promise<StimWorktreeWarmResult>;
+  /** Removes a linked worktree or reclaims a source checkout's environment using the CLI safety checks. */
+  removeWorktree(options?: StimWorktreeRemoveOptions): Promise<StimWorktreeRemoveResult>;
   /** Builds an artifact without acquiring a device or starting a runtime. */
   build<P extends StimBuildOptions["platform"]>(options: StimBuildOptions & {
     platform: P;
@@ -1030,7 +1044,7 @@ declare class StimError extends Error {
   readonly details: unknown;
   constructor({ code, message, remedy, details }: Omit<StimFailure, "remedy"> & {
     remedy?: string | null;
-  });
+  }, options?: ErrorOptions);
 }
 /**
  * Creates a client without starting processes or changing the caller's cwd, environment, or signal handlers.
@@ -1041,4 +1055,4 @@ declare class StimError extends Error {
  */
 declare function createStim(options: StimOptions): StimClient;
 //#endregion
-export { type StimBuildOptions, type StimBuildResult, type StimClient, type StimDiagnostics, type StimDiagnosticsOptions, type StimDoctorOptions, type StimDoctorReport, StimError, type StimGcOptions, type StimGcReport, type StimLogsOptions, type StimOptions, type StimPlatform, type StimProgress, type StimReadOptions, type StimReloadOptions, type StimReloadResult, type StimRunOptions, type StimRunResult, type StimSettingWriteOptions, type StimSettingWriteResult, type StimSettings, type StimStats, type StimStopOptions, type StimStopResult, createStim };
+export { type StimBuildOptions, type StimBuildResult, type StimClient, type StimDiagnostics, type StimDiagnosticsOptions, type StimDoctorOptions, type StimDoctorReport, StimError, type StimGcMutationOptions, type StimGcMutationResult, type StimGcOptions, type StimGcReport, type StimLogsOptions, type StimMachineAccessOptions, type StimOptions, type StimPlan, type StimPlanOptions, type StimPlatform, type StimProgress, type StimReadOptions, type StimReloadOptions, type StimReloadResult, type StimRunOptions, type StimRunResult, type StimSettingWriteOptions, type StimSettingWriteResult, type StimSettings, type StimStartOptions, type StimStartResult, type StimStats, type StimStopOptions, type StimStopResult, type StimWorktreeRemoveOptions, type StimWorktreeRemoveResult, type StimWorktreeWarmOptions, type StimWorktreeWarmResult, createStim };