@stim-cli/core 1.9.0 → 1.10.0

package/dist/state.d.mts

@@ -0,0 +1,507 @@
+//#region state/config-types.d.ts
+type SettingsObject = Record<string, unknown>;
+interface SupervisorRecord {
+  processToken?: string;
+  pid?: number;
+  port?: number;
+  startedAt?: string;
+  serverPid?: number;
+  mode?: string;
+  [key: string]: unknown;
+}
+interface IosDeviceRecord {
+  deviceUdid?: string;
+  deviceName?: string | null;
+  owned?: boolean;
+  serial?: string;
+  simslimManaged?: boolean;
+  [key: string]: unknown;
+}
+interface AndroidDeviceRecord {
+  avdName?: string;
+  consolePort?: number;
+  serial?: string;
+  kind?: string;
+  deviceName?: string | null;
+  owned?: boolean;
+  setupIncomplete?: boolean;
+  [key: string]: unknown;
+}
+type DeviceRecord = IosDeviceRecord | AndroidDeviceRecord;
+interface PlatformRecords {
+  ios?: IosDeviceRecord;
+  android?: AndroidDeviceRecord;
+  [platform: string]: DeviceRecord | undefined;
+}
+interface ProjectRecord {
+  ports?: Record<string, number>;
+  metroPort?: number | null;
+  platforms?: PlatformRecords;
+  deviceSlots?: Record<string, PlatformRecords>;
+  supervisor?: SupervisorRecord;
+  settings?: SettingsObject;
+  worktreeRoot?: boolean;
+  worktreeBranch?: string;
+  worktreeBranchOwned?: boolean;
+  worktreeMainRoot?: string;
+  worktreeRemovalComplete?: boolean;
+  worktreePendingBranchSha?: string;
+  label?: string;
+  bundleId?: string;
+  androidPackage?: string;
+  isExpo?: boolean;
+  lastBuild?: Record<string, unknown>;
+  doctorRuns?: Partial<Record<"ios" | "android", DoctorRunRecord>>;
+  [key: string]: unknown;
+}
+interface DoctorRunRecord {
+  at: string;
+  version: string;
+}
+interface RepoRecord {
+  settings?: SettingsObject;
+  [key: string]: unknown;
+}
+interface ConcurrencyLimits {
+  maxBuilds: number;
+  maxDevices: number;
+}
+interface StimConfig {
+  version?: number;
+  projects: Record<string, ProjectRecord>;
+  repos: Record<string, RepoRecord>;
+  tempDir?: unknown;
+  iosSimulatorApp?: unknown;
+  optimizations?: unknown;
+  concurrency?: {
+    maxBuilds?: unknown;
+    maxDevices?: unknown;
+  };
+  pool?: {
+    iosParkedMax?: unknown;
+    androidParkedMax?: unknown;
+  };
+  parked?: {
+    ios?: unknown;
+    android?: unknown;
+  };
+  caches?: {
+    buildCache?: unknown;
+    metroCache?: unknown;
+  };
+  [key: string]: unknown;
+}
+type Config = StimConfig;
+//#endregion
+//#region state/config.d.ts
+declare function withConfigLock<T>(fn: () => T): T;
+declare function configCorruptRepair(path?: string): string;
+declare function loadConfig(): Config | null;
+declare function getProject(projectPath: string): ProjectRecord | null;
+declare function getConcurrencyLimits({ env }?: {
+  env?: NodeJS.ProcessEnv;
+}): ConcurrencyLimits;
+declare function getProjectSettings(projectPath: string): Record<string, unknown>;
+declare function getProjectSetting(projectPath: string, dottedKey: string): unknown;
+declare function getRepoSettings(gitCommonDir: string): Record<string, unknown>;
+declare function isPathPrefix(prefix: string, path: string): boolean;
+declare function findEnclosingWorktreeRoot(projectPath: string): string | null;
+declare function allMetroPorts(): number[];
+declare function findProjectByMetroPort(port: number): string | null;
+//#endregion
+//#region state/json-file.d.ts
+declare function readJsonFile(path: string): unknown;
+declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+declare function readJsonObject(path: string): Record<string, unknown> | null;
+//#endregion
+//#region state/ledgers.d.ts
+type CreatedDevicePlatform = "ios" | "android";
+interface CreatedDevices {
+  ios: ReadonlySet<string>;
+  android: ReadonlySet<string>;
+}
+declare function readCreatedDevices(): CreatedDevices;
+interface EasSessionClaim {
+  sessionId: string;
+  name: string;
+  platform: "ios" | "android";
+  workspaceRoot: string;
+  workspaceHome: string;
+  stateFile: string;
+}
+interface EasSessionLedgerRead {
+  claims: Map<string, EasSessionClaim>;
+  notice: string | null;
+  safe: boolean;
+}
+/** Returns the claim normalized to canonical paths, or null when it is not a valid claim for `id`. */
+declare function validEasSessionClaim(id: string, value: unknown): EasSessionClaim | null;
+declare function readEasSessionLedger(root?: string): EasSessionLedgerRead;
+//#endregion
+//#region state/ndjson.d.ts
+interface NdjsonRecord {
+  ts?: number;
+  src?: string;
+  level?: string;
+  msg?: string;
+  [key: string]: unknown;
+}
+declare const LEVELS: string[];
+declare const SOURCES: string[];
+declare function levelRank(level?: string): number;
+declare function parseNdjsonLine(line: unknown): NdjsonRecord | null;
+declare function parseNdjsonText(text: unknown): NdjsonRecord[];
+declare function readNdjsonGenerations(file: string): NdjsonRecord[];
+//#endregion
+//#region state/logs-query.d.ts
+interface SinceResult {
+  ms?: number;
+  error?: string;
+}
+interface GrepResult {
+  re?: RegExp;
+  error?: string;
+}
+interface MarkerWindow {
+  launchTs: number | null;
+  bundleTs: number | null;
+}
+interface QueryCriteria {
+  slot?: string;
+  includeNativeCrashes?: boolean;
+  sources?: string[];
+  minLevel?: string;
+  grep?: RegExp;
+  sinceTs?: number;
+  errorsOnly?: boolean;
+  markerTs?: number;
+  bundleMarkerTs?: number;
+}
+interface TailState {
+  offset: number;
+  partial: string;
+}
+declare function parseSince(text: unknown): SinceResult;
+declare function compileGrep(pattern: unknown): GrepResult;
+declare const ERROR_SOURCES: string[];
+declare function markerWindow(records: NdjsonRecord[]): MarkerWindow;
+declare function recordMatches(record: NdjsonRecord | null | undefined, criteria?: QueryCriteria): boolean;
+declare function buildCriteria({ slot, sources, minLevel, since, grep, errorsOnly, markerTs, bundleMarkerTs, now }?: {
+  slot?: string;
+  sources?: string[];
+  minLevel?: string;
+  since?: string | null;
+  grep?: string | RegExp | null;
+  errorsOnly?: boolean;
+  markerTs?: number;
+  bundleMarkerTs?: number;
+  now?: number;
+}): QueryCriteria;
+declare function logFiles(dir: string): string[];
+declare function fileSizes(dir: string): Record<string, number>;
+declare function readLogRecords(dir: string, include?: (name: string) => boolean): NdjsonRecord[];
+declare function attachExpoErrorContext(all: NdjsonRecord[], matched: NdjsonRecord[]): NdjsonRecord[];
+declare function queryLogs({ slot, dir, records, sources, minLevel, since, grep, tail, errorsOnly, errorContext, now }?: {
+  slot?: string;
+  dir?: string;
+  records?: NdjsonRecord[];
+  sources?: string[];
+  minLevel?: string;
+  since?: string;
+  grep?: string | RegExp;
+  tail?: number;
+  errorsOnly?: boolean;
+  errorContext?: boolean;
+  now?: number;
+}): NdjsonRecord[];
+declare function tailRead(prev: TailState | null | undefined, size: number): {
+  start: number;
+  prev: TailState;
+};
+declare function advanceTail(prev: TailState | null | undefined, chunk: string | null | undefined, size: number): {
+  state: TailState;
+  records: NdjsonRecord[];
+};
+declare function followLogs({ dir, onRecord, criteria, intervalMs, offsets }: {
+  dir: string;
+  onRecord: (record: NdjsonRecord) => void;
+  criteria?: QueryCriteria;
+  intervalMs?: number;
+  offsets?: Record<string, number> | null;
+}): () => void;
+declare function sortByTs(records: NdjsonRecord[]): NdjsonRecord[];
+//#endregion
+//#region state/paths.d.ts
+declare function getConfigPath(): string;
+declare function configLockPath(): string;
+declare function workspaceMetadataFile(projectRoot: string): string;
+declare function workspaceLogsDir(projectRoot: string): string;
+declare function workspaceLogErrorIndex(projectRoot: string): string;
+declare function workspaceDerivedData(projectRoot: string): string;
+declare function workspaceGradleBuild(projectRoot: string): string;
+declare function supervisorPidFile(projectRoot: string): string;
+declare function workspaceStateFile(projectRoot: string): string;
+declare function workspaceStateLock(projectRoot: string): string;
+declare function supervisorLogFile(projectRoot: string): string;
+declare function emulatorLogFile(projectRoot: string): string;
+declare function sharedCompilationCache(): string;
+declare function sharedCcache(): string;
+declare function sharedGradle(): string;
+declare function sharedPods(): string;
+declare function createdDevicesFile(): string;
+declare function createdDevicesLock(): string;
+/** The EAS session ledger lives under the real home directory, never under STIM_HOME. */
+declare function easMachineStateRoot(): string;
+declare function easSessionLedgerFile(root?: string): string;
+declare function easSessionLedgerLock(root?: string): string;
+//#endregion
+//#region state/settings-registry.d.ts
+declare const ANDROID_COMPILER_CACHE_CHOICES: readonly ["auto", "ccache", "cas", "none"];
+declare const ANDROID_PCH_CHOICES: readonly ["auto", "on", "off"];
+type TunnelMode = "auto" | "off" | "expo" | "cloudflared" | "ngrok";
+declare const TUNNEL_MODES: readonly TunnelMode[];
+type RemoteDeviceBackend = "proxy" | "eas";
+type SettingScope = "machine" | "workspace" | "repo" | "committed";
+declare const SETTING_SCOPES: readonly SettingScope[];
+type SettingType = {
+  kind: "string";
+  pattern?: string;
+  patternHelp?: string;
+} | {
+  kind: "path";
+  absolute?: boolean;
+  relative?: boolean;
+} | {
+  kind: "strings";
+} | {
+  kind: "number";
+  integer?: boolean;
+  minimum?: number;
+  maximum?: number;
+} | {
+  kind: "boolean";
+} | {
+  kind: "choice";
+  choices: readonly string[];
+} | {
+  kind: "object";
+} | {
+  kind: "bundle-url";
+};
+/**
+ * One setting Stim reads. `scopes` are the layers the setting may be written to;
+ * `committedAt: 'repository'` reads the committed layer from the repository root's
+ * `.stim.json` instead of the app's. A `sensitive` value is never printed and is
+ * written to `.stim.json` only as an `env:` or `file:` reference. `scopedHomeValue`
+ * replaces every layer and the default while STIM_HOME is set and `env` is not.
+ */
+interface SettingDefinition {
+  key: string;
+  type: SettingType;
+  scopes: readonly SettingScope[];
+  description: string;
+  default?: string | number | boolean;
+  env?: string;
+  sensitive?: boolean;
+  committedAt?: "repository";
+  scopedHomeValue?: number;
+}
+interface SettingEntry {
+  key: string;
+  value: unknown;
+  origin: SettingScope | "env" | "default" | null;
+  layers: Partial<Record<SettingScope, unknown>>;
+  env?: {
+    name: string;
+    value: string;
+  };
+  sensitive?: true;
+}
+/** The payload `stim settings --json` prints. */
+interface SettingsPayload {
+  project: string | null;
+  files: Partial<Record<SettingScope, string>>;
+  settings: SettingEntry[];
+  unknown: Array<{
+    key: string;
+    scope: SettingScope;
+    file: string;
+    value: unknown;
+  }>;
+}
+declare const REMOTE_DEVICE_BACKENDS: readonly RemoteDeviceBackend[];
+declare const IOS_SIMULATOR_APPS: readonly ["xcode", "siniulator", "stim-desktop"];
+declare const SETTINGS: readonly SettingDefinition[];
+declare function settingDefinition(key: string): SettingDefinition | null;
+declare function isLayeredSetting(setting: SettingDefinition): boolean;
+declare const SETTING_GROUPS: readonly string[];
+declare function expectedShape(type: SettingType): string;
+declare function acceptsShape(setting: SettingDefinition, value: unknown): boolean;
+declare function settingValueError(setting: SettingDefinition, value: unknown): string | null;
+declare function isSensitiveReference(value: unknown): boolean;
+/**
+ * Coerces raw text (a CLI argument or an environment variable) through a setting's
+ * registry type, the same way for both sources. Types whose values are not written
+ * as bare text (boolean, number, strings, object) are read as JSON; a value that
+ * fails to parse is left as the original string so `settingValueError` reports it.
+ */
+declare function coerceSettingText(setting: SettingDefinition, raw: string): unknown;
+//#endregion
+//#region state/settings-schema.d.ts
+declare const SETTINGS_SCHEMA_FILE = "settings.schema.json";
+declare const SETTINGS_SCHEMA_URL: string;
+type JsonSchema = Record<string, unknown>;
+/**
+ * The published settings schema. The root describes a committed `.stim.json`;
+ * `$defs.machine` describes the settings keys of `$STIM_HOME/config.json`.
+ * Every leaf carries `x-stim` with its dotted key, kind, writable scopes,
+ * environment override, and sensitivity.
+ */
+declare function settingsJsonSchema(): JsonSchema;
+//#endregion
+//#region state/workspace-state.d.ts
+interface WorkspaceState {
+  supervisor?: Record<string, unknown>;
+  collectors?: Record<string, unknown>;
+  lastBuild?: Record<string, unknown>;
+  launches?: Record<string, unknown>;
+  remoteDevice?: Record<string, unknown>;
+  metroTunnel?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+declare const IDLE_STOP_KEY = "devServerStop";
+/** Why the supervisor last stopped the dev server on its own: `metro.idleStopMinutes` with no use. */
+interface IdleStopRecord {
+  reason: "idle";
+  at: string;
+  idleMinutes: number;
+}
+declare function readIdleStop(state: WorkspaceState | null | undefined): IdleStopRecord | null;
+declare function readWorkspaceState(root: string): WorkspaceState | null;
+declare function lastUseFrom(state: WorkspaceState | null, logMtimes: readonly number[]): number;
+declare function workspaceLastUsed(root: string): number;
+//#endregion
+//#region state/status.d.ts
+type StatsPlatform = "ios" | "android";
+type RunOutcomeKind = "hit" | "cold";
+declare const BUILD_PHASES: readonly ["prepare", "cache-lookup", "wait", "prebuild", "pods", "compile", "install", "launch"];
+type BuildPhase = (typeof BUILD_PHASES)[number];
+type ActiveBuildState = "running" | "stale" | "unknown";
+interface BuildReport {
+  platform: StatsPlatform;
+  slot: string;
+  state: ActiveBuildState;
+  phase: BuildPhase;
+  startedAt: string;
+  phaseStartedAt: string;
+  outcome: RunOutcomeKind | null;
+  expectedMs: number | null;
+  expectedPhaseMs: number | null;
+  basis: number;
+}
+type ActivityState = "driven" | "active" | "idle" | "unknown";
+interface ActivityDriver {
+  tool: string;
+  pid: number | null;
+  since: string | null;
+}
+interface DeviceActivity {
+  state: ActivityState;
+  driver?: ActivityDriver;
+  lastActivityAt?: string;
+  basis: string[];
+}
+interface WorktreeFacts {
+  path: string;
+  branch?: string;
+  repository?: string;
+}
+interface AndroidRuntimeFacts {
+  serial: string | null;
+  state: "detected" | "not-detected" | "missing" | "unknown";
+  error?: string;
+}
+interface RemoteDeviceState {
+  platform: "ios" | "android" | null;
+  backend: "eas";
+  sessionId: string;
+  state: "claimed" | "unclaimed" | "unknown";
+  startedAt: string | null;
+  webPreviewUrl: string | null;
+}
+interface EnvironmentState {
+  slots?: {
+    slot: string;
+    ios: EnvironmentState["ios"];
+    android: EnvironmentState["android"];
+  }[];
+  path: string;
+  live: boolean;
+  memoryMb: number;
+  warnings: string[];
+  ios?: {
+    name: string | null;
+    udid: string;
+    owned: boolean;
+    state: string;
+    activity?: DeviceActivity;
+  } | null;
+  android?: {
+    name: string | undefined;
+    owned: boolean;
+    physical: boolean;
+    serial?: string | null;
+    state?: AndroidRuntimeFacts["state"];
+    activity?: DeviceActivity;
+  } | null;
+  metro?: {
+    port: number;
+    running: boolean;
+    pid: number | null;
+    idleStop?: IdleStopRecord;
+  } | null;
+  supervisor?: {
+    pid: number | null;
+    mode: string | null;
+    startedAt: string | null;
+    healthy: boolean;
+  } | null;
+  logs?: {
+    dir: string;
+    errorsSinceMarker: number;
+  } | null;
+  worktree?: WorktreeFacts | null;
+  remoteDevices?: RemoteDeviceState[];
+  build?: BuildReport | null;
+}
+interface StatusCapacity {
+  liveCount: number;
+  committedMb: number;
+  totalMemoryMb: number;
+  overCapacity: boolean;
+}
+interface DeviceLeaseState {
+  slot?: string;
+  path: string;
+  platform: string;
+  id: string | null;
+  deviceName: string | null;
+  holder: string | null;
+  grantedAt: string | null;
+  expiresAt: string | null;
+  mine: boolean;
+  expired: boolean;
+  parsed: boolean;
+}
+/** The payload `stim status --json` prints, and `status --watch --json` prints on each change. */
+interface StatusPayload {
+  environments: (EnvironmentState & {
+    labelOnly?: true;
+  })[];
+  capacity: StatusCapacity;
+  deviceLeases: DeviceLeaseState[];
+  unprovisionedWorktrees: WorktreeFacts[];
+  simctlAvailable: boolean;
+}
+//#endregion
+export { ANDROID_COMPILER_CACHE_CHOICES, ANDROID_PCH_CHOICES, ActiveBuildState, ActivityDriver, AndroidRuntimeFacts, BUILD_PHASES, BuildPhase, BuildReport, ConcurrencyLimits, Config, CreatedDevicePlatform, CreatedDevices, DeviceActivity, DeviceLeaseState, DeviceRecord, DoctorRunRecord, ERROR_SOURCES, EasSessionClaim, EasSessionLedgerRead, EnvironmentState, IDLE_STOP_KEY, IOS_SIMULATOR_APPS, IdleStopRecord, LEVELS, NdjsonRecord, PlatformRecords, ProjectRecord, QueryCriteria, REMOTE_DEVICE_BACKENDS, RemoteDeviceBackend, RemoteDeviceState, RepoRecord, RunOutcomeKind, SETTINGS, SETTINGS_SCHEMA_FILE, SETTINGS_SCHEMA_URL, SETTING_GROUPS, SETTING_SCOPES, SOURCES, SettingDefinition, SettingEntry, SettingScope, SettingType, SettingsObject, SettingsPayload, StatsPlatform, StatusCapacity, StatusPayload, StimConfig, SupervisorRecord, TUNNEL_MODES, TunnelMode, WorkspaceState, WorktreeFacts, acceptsShape, advanceTail, allMetroPorts, attachExpoErrorContext, buildCriteria, coerceSettingText, compileGrep, configCorruptRepair, configLockPath, createdDevicesFile, createdDevicesLock, easMachineStateRoot, easSessionLedgerFile, easSessionLedgerLock, emulatorLogFile, expectedShape, fileSizes, findEnclosingWorktreeRoot, findProjectByMetroPort, followLogs, getConcurrencyLimits, getConfigPath, getProject, getProjectSetting, getProjectSettings, getRepoSettings, isJsonObject, isLayeredSetting, isPathPrefix, isSensitiveReference, lastUseFrom, levelRank, loadConfig, logFiles, markerWindow, parseNdjsonLine, parseNdjsonText, parseSince, queryLogs, readCreatedDevices, readEasSessionLedger, readIdleStop, readJsonFile, readJsonObject, readLogRecords, readNdjsonGenerations, readWorkspaceState, recordMatches, settingDefinition, settingValueError, settingsJsonSchema, sharedCcache, sharedCompilationCache, sharedGradle, sharedPods, sortByTs, supervisorLogFile, supervisorPidFile, tailRead, validEasSessionClaim, withConfigLock, workspaceDerivedData, workspaceGradleBuild, workspaceLastUsed, workspaceLogErrorIndex, workspaceLogsDir, workspaceMetadataFile, workspaceStateFile, workspaceStateLock };