@stim-cli/core 1.14.0 → 1.16.0

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { Server } from "node:net";
 //#region dir-lock.d.ts
 interface DirLockOptions {
   /** @deprecated Occupied locks are never expired. */
@@ -8,6 +9,10 @@ interface DirLockOptions {
 }
 declare function withDirLock<T>(lockPath: string, fn: () => T, { waitMs, pollMs, ensureParent }?: DirLockOptions): T;
 //#endregion
+//#region macos-resources.d.ts
+/** Whether a resource destination is a contained, non-empty path under Contents/Resources. */
+declare function validMacosResourceDestination(value: unknown): value is string;
+//#endregion
 //#region quoted-path.d.ts
 /** Quote a path for a shell command Stim prints for a human to copy and run. */
 declare function quotedPath(path: string): string;
@@ -23,6 +28,39 @@ interface StoreArtifactOptions {
 }
 declare function storeArtifact(dest: string, buildPath: string, { runFile, overwrite, writeMetadata, onRenameError }: StoreArtifactOptions): string | null;
 //#endregion
+//#region compiled-helper.d.ts
+/**
+ * Returns `<dir>/<name>-<hash>`, compiling it with `compile` first when it is missing. The hash covers `version` and
+ * each input's name and bytes, so a changed source or compiler builds a new helper beside the old one. `compile`
+ * writes to a private temporary path that is renamed into place, so concurrent builders never expose a partial file.
+ * Pruning is best effort and keeps this helper, the newest previous build, helpers modified in the last ten minutes and running helpers. It runs after a build and on the first call per process.
+ */
+declare function compiledHelper({ dir, name, inputs, version, compile }: {
+  dir: string;
+  name: string;
+  inputs: readonly string[];
+  version: string;
+  compile: (output: string) => Promise<void>;
+}): Promise<string>;
+//#endregion
+//#region metro-bridge.d.ts
+interface MetroBridge {
+  server: Server;
+  close: () => Promise<void>;
+}
+/** Bind this gateway only to the client's own Tailscale address; `peer` is the pinned worker's literal address. */
+declare function createMetroGateway({ metroPort, peer, secret }: {
+  metroPort: number;
+  peer: string;
+  secret: string;
+}): MetroBridge;
+/** Bind this endpoint only to worker loopback; `peer` comes from the approved client's authenticated connection. */
+declare function createMetroBridge({ gatewayPort, peer, secret }: {
+  gatewayPort: number;
+  peer: string;
+  secret: string;
+}): MetroBridge;
+//#endregion
 //#region index.d.ts
 declare function configDir(): string;
 declare function workspaceSlug(projectRoot: string): string;
@@ -47,12 +85,15 @@ interface BuildRunOptions {
   variant?: string;
   abi?: string;
   allArch?: boolean;
+  arch?: string;
   configuration?: string;
   scheme?: string;
   buildConfiguration?: string;
   isSimulator?: boolean;
   device?: string | boolean | null;
 }
+/** The simulator slice a local build compiles for this machine: `arm64` or `x86_64`. */
+declare function hostSimulatorArch(arch?: string): "arm64" | "x86_64";
 declare function buildCacheKey(platform: string, fingerprintHash: string, options?: unknown): string;
 interface RegisterOptions {
   dir: string;
@@ -80,4 +121,4 @@ declare function readCacheManifest(file: string): CacheManifest;
 declare function updateCacheManifest(file: string, mutate: (caches: Array<Record<string, unknown>>) => Array<Record<string, unknown>>): CacheManifest;
 declare function registerCache({ dir, name, prune, note, entriesDepth, layout, replaces }: RegisterOptions): void;
 //#endregion
-export { BuildRunOptions, CacheManifest, CacheRegistrationMatch, type DirLockOptions, LOG_ROTATE_BYTES, METRO_NAMED_CACHE_LAYOUT, RegisterOptions, STORE_ROOT_TAG, type StoreArtifactOptions, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, rotateLog, rotatedLogPath, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };
+export { BuildRunOptions, CacheManifest, CacheRegistrationMatch, type DirLockOptions, LOG_ROTATE_BYTES, METRO_NAMED_CACHE_LAYOUT, type MetroBridge, RegisterOptions, STORE_ROOT_TAG, type StoreArtifactOptions, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, compiledHelper, configDir, createMetroBridge, createMetroGateway, hostSimulatorArch, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, rotateLog, rotatedLogPath, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, validMacosResourceDestination, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import { S as quotedPath } from "./ownership-claim-O31Y5iIb.mjs";
-import { C as artifactIn, E as withDirLock, S as workspaceStateDir, T as storeArtifact, _ as updateCacheManifest, a as buildCacheRoot, b as workspaceName, c as cachePathSetting, d as readCacheManifest, f as registerCache, g as tagSharedStore, h as sharedStoreRoot, i as buildCacheKey, l as configDir, m as rotatedLogPath, n as METRO_NAMED_CACHE_LAYOUT, o as cacheManifestLockPath, p as rotateLog, r as STORE_ROOT_TAG, s as cacheNameSegment, t as LOG_ROTATE_BYTES, u as metroCacheRoot, v as workspaceId, w as resolveArtifact, x as workspaceSlug, y as workspaceLogDir } from "./core-CmZJEFj_.mjs";
-export { LOG_ROTATE_BYTES, METRO_NAMED_CACHE_LAYOUT, STORE_ROOT_TAG, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, rotateLog, rotatedLogPath, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };
+import { A as validMacosResourceDestination, C as workspaceStateDir, D as artifactIn, E as compiledHelper, O as resolveArtifact, S as workspaceSlug, T as createMetroGateway, _ as tagSharedStore, a as buildCacheRoot, b as workspaceLogDir, c as cachePathSetting, d as metroCacheRoot, f as readCacheManifest, g as sharedStoreRoot, h as rotatedLogPath, i as buildCacheKey, j as withDirLock, k as storeArtifact, l as configDir, m as rotateLog, n as METRO_NAMED_CACHE_LAYOUT, o as cacheManifestLockPath, p as registerCache, r as STORE_ROOT_TAG, s as cacheNameSegment, t as LOG_ROTATE_BYTES, u as hostSimulatorArch, v as updateCacheManifest, w as createMetroBridge, x as workspaceName, y as workspaceId } from "./core-DWOUn9xp.mjs";
+export { LOG_ROTATE_BYTES, METRO_NAMED_CACHE_LAYOUT, STORE_ROOT_TAG, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, compiledHelper, configDir, createMetroBridge, createMetroGateway, hostSimulatorArch, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, rotateLog, rotatedLogPath, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, validMacosResourceDestination, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/dist/oversight.d.mts

@@ -0,0 +1,308 @@
+//#region oversight.d.ts
+/** What a notification is about; each can be switched off on its own. */
+declare const OVERSIGHT_CATEGORIES: readonly ["started", "stuck", "looping", "finished", "machine", "control", "attention"];
+type OversightCategory = (typeof OVERSIGHT_CATEGORIES)[number];
+declare const DEFAULT_STUCK_MINUTES = 15;
+interface Activity {
+  state: string;
+  driver?: {
+    tool: string;
+    since: string | null;
+  };
+  lastActivityAt?: string;
+  recent?: Partial<Record<string, string>>;
+}
+interface Device {
+  name?: string | null;
+  state?: string;
+  physical?: boolean;
+  activity?: Activity;
+}
+interface Build {
+  platform: string;
+  status: string;
+  result?: string;
+  startedAt: string;
+  finishedAt: string | null;
+  errorCode?: string;
+  diagnostics?: {
+    file: string | null;
+    line: number | null;
+  }[];
+}
+/** The part of a `stim status --json` environment the rules read. */
+interface OversightEnvironment {
+  path: string;
+  live: boolean;
+  phase?: string;
+  ios?: Device | null;
+  android?: Device | null;
+  slots?: {
+    slot: string;
+    ios?: Device | null;
+    android?: Device | null;
+  }[];
+  worktree?: {
+    path: string;
+    branch?: string;
+    repository?: string;
+    git?: {
+      mergedInto: string | null;
+    } | null;
+  } | null;
+  build?: {
+    state: string;
+    startedAt: string;
+    platform?: string;
+  } | null;
+  issues?: {
+    code: string;
+    severity: string;
+    message: string;
+    remedy: string;
+    slot?: string;
+  }[];
+  physicalDevices?: {
+    platform: string;
+    slot: string;
+    id: string;
+    name: string | null;
+    model: string | null;
+    lease: {
+      expiresAt: string;
+    };
+  }[];
+  remoteDevices?: {
+    sessionId: string;
+    startedAt: string | null;
+  }[];
+  lastBuilds?: {
+    ios?: Build;
+    android?: Build;
+  };
+  builds?: {
+    ios?: Build[];
+    android?: Build[];
+  };
+  logs?: {
+    errorsSinceMarker: number;
+  } | null;
+  web?: {
+    running: boolean;
+    activity?: Activity;
+  } | null;
+}
+interface OversightStatus {
+  environments: OversightEnvironment[];
+  unprovisionedWorktrees?: {
+    path: string;
+    repository?: string;
+  }[];
+}
+/** A workspace's pull request, from GitHub. */
+interface OversightPullRequest {
+  number: number;
+  state: "open" | "merged" | "closed";
+  draft: boolean;
+  url: string;
+}
+interface OversightInput {
+  machine: string;
+  /** Null when the machine's status is not current, so its workspaces are left as they were. */
+  status: OversightStatus | null;
+  volumes: {
+    freeBytes: number;
+  }[] | null;
+  memoryPressure: string | null;
+  /** The phone's connection to the machine; null where it is not known, as on the machine itself. */
+  link: "open" | "offline" | "refused" | "unpaired" | null;
+  /** Each workspace's pull request by path, null when it has none; a missing path was not looked up. */
+  pullRequests: Record<string, OversightPullRequest | null>;
+  /** `grantedAt` of the device leases stim-server holds for phones, so a person controlling a device is no agent. */
+  ownLeases: readonly string[];
+}
+interface OversightPrefs {
+  categories: readonly OversightCategory[];
+  stuckMinutes: number;
+  /** Whether it is quiet hours now: nothing notifies, and what still holds afterwards notifies then. */
+  quiet: boolean;
+}
+type OversightTarget = {
+  kind: "machine";
+} | {
+  kind: "workspace";
+  path: string;
+} | {
+  kind: "device";
+  path: string;
+  platform: "ios" | "android" | "web" | "macos";
+  slot: string;
+} | {
+  kind: "build";
+  path: string;
+  platform: "ios" | "android";
+} | {
+  kind: "url";
+  path: string;
+  url: string;
+};
+interface OversightNotification {
+  /** Stable for the workspace or machine and category, so a later notification replaces the earlier one. */
+  id: string;
+  category: OversightCategory;
+  title: string;
+  body: string;
+  /** Delivered without sound or banner interruption. */
+  quiet: boolean;
+  /** Groups notifications in the notification list; null leaves them ungrouped. */
+  thread: string | null;
+  target: OversightTarget;
+}
+interface Loop {
+  signature: string;
+  notified: boolean;
+}
+interface WorkspaceEntry {
+  seenAt: number;
+  warmed: boolean;
+  drove: boolean;
+  drivenAt: number | null;
+  driveNotified: boolean;
+  errors: number;
+  errorsAt: number | null;
+  stuckAt: number | null;
+  finished: boolean;
+  /** Ids of the `attention` items already notified, so each notifies once per episode. */
+  attention: string[];
+  loops: {
+    ios?: Loop;
+    android?: Loop;
+  };
+  pr: {
+    number: number;
+    ready: boolean;
+    merged: boolean;
+  } | null | undefined;
+  mergedInto: string | null;
+  mergeNotified: boolean;
+}
+interface Held {
+  since: number;
+  notified: boolean;
+}
+interface OversightState {
+  workspaces: Record<string, WorkspaceEntry>;
+  disk?: Held;
+  memory?: Held;
+  /** Whether memory pressure was ever read, so the first reading records what is true without notifying. */
+  memoryKnown?: boolean;
+  link?: Held & {
+    kind: string;
+  };
+}
+interface OversightResult {
+  state: OversightState;
+  notifications: OversightNotification[];
+  /** When a timed rule may become due while nothing else changes. */
+  wakeAt: number | null;
+}
+/** The name home shows for a workspace: its branch, else its checkout's folder. */
+declare function oversightTitle(env: OversightEnvironment, status: OversightStatus): string;
+type Platform = "ios" | "android" | "web";
+interface SlotDevice {
+  platform: Platform;
+  slot: string;
+  model: string;
+  modelLabel?: "ios-simulator" | "android-device" | "android-emulator" | "chrome";
+  running: boolean;
+  activity: Activity | undefined;
+}
+/**
+ * The notifications a machine owes since `previous`, the state the last call returned. Null `previous` records
+ * what is already true without notifying, so a restart or a new registration stays quiet. Each workspace and
+ * machine problem notifies once per episode, under one id per category, so a later episode replaces it.
+ * `awakeSince` restarts the offline settle time, for a checker that was not running.
+ */
+declare function oversee(previous: OversightState | null, input: OversightInput, prefs: OversightPrefs, now: number, awakeSince?: number): OversightResult;
+/** Whether `minuteOfDay` falls in quiet hours from `start` to `end`, minutes after midnight; they may span midnight. */
+declare function inQuietHours(quietHours: {
+  start: number;
+  end: number;
+} | null, minuteOfDay: number): boolean;
+/** What only a person can act on or decide. */
+interface NeedsAttentionItem {
+  /** Stable while the problem lasts; `stuck`, `looping` and `machine` items use the oversight notification ids. */
+  id: string;
+  /** The oversight notification category that covers the item; `attention` is for the rest. */
+  category: "attention" | "stuck" | "looping" | "machine";
+  severity: "error" | "warning";
+  /** The workspace path; null for the machine. */
+  workspace: string | null;
+  body: string;
+  /** A `stim` command to run from `workspace`, or null when the fix is outside Stim. */
+  remedy: string | null;
+}
+interface NeedsAttentionInput {
+  environments: OversightEnvironment[];
+  /** Each volume Stim uses; null when not measured. */
+  volumes: {
+    freeBytes: number;
+  }[] | null;
+  now: number;
+  stuckMinutes: number;
+  easSessionMinutes: number;
+  /** `grantedAt` of the device leases stim-server holds for phones, so a person controlling a device is no agent. */
+  ownLeases?: readonly string[];
+}
+/** Selected attention facts for rendering a body without repeating the rule that selected the item. */
+type AttentionMessage = {
+  kind: "issue";
+  slot?: string;
+  message: string;
+} | {
+  kind: "signing";
+  platform: string;
+  code: string;
+} | {
+  kind: "diagnostic-loop";
+  platform: string;
+  count: number;
+  file: string;
+  line: number;
+  language: string | undefined;
+} | {
+  kind: "launch-loop";
+  platform: string;
+  count: number;
+} | {
+  kind: "build-loop";
+  platform: string;
+  count: number;
+  errorCode: string | undefined;
+} | {
+  kind: "lease";
+  leased: string;
+} | {
+  kind: "eas";
+  minutes: number;
+} | {
+  kind: "stuck";
+  minutes: number;
+  green: "ios" | "android" | null;
+  model: string;
+  modelLabel: SlotDevice["modelLabel"];
+} | {
+  kind: "disk";
+  freeBytes: number;
+};
+/** Formats only an attention item's body; identity, remedy and ordering stay with the policy. */
+type AttentionFormatter = (message: AttentionMessage) => string;
+/** A failed run older than this on an idle workspace is history, not a problem. */
+declare const STALE_MS: number;
+/**
+ * The items, errors first, then the machine's, then live workspaces' before idle ones', each in status order. Log
+ * errors, a single failed run, and issues an agent's next `stim` command repairs are left out: agents handle them.
+ */
+declare function needsAttention(input: NeedsAttentionInput, format?: AttentionFormatter): NeedsAttentionItem[];
+//#endregion
+export { AttentionFormatter, AttentionMessage, DEFAULT_STUCK_MINUTES, NeedsAttentionInput, NeedsAttentionItem, OVERSIGHT_CATEGORIES, OversightCategory, OversightEnvironment, OversightInput, OversightNotification, OversightPrefs, OversightPullRequest, OversightResult, OversightState, OversightStatus, OversightTarget, STALE_MS, inQuietHours, needsAttention, oversee, oversightTitle };