@limrun/api 0.39.3 → 0.39.5

package/src/folder-sync.ts

@@ -47,6 +47,12 @@ export type FolderSyncOptions = {
    * ignoreFn: (path) => !(path.startsWith('src/') || path.endsWith('.json'))
    */
   ignoreFn: IgnoreFn;
+  /**
+   * Sync symlinks as symlinks (relative, in-root targets only). Off by
+   * default: only the limbuild workspace sync understands link entries;
+   * the limulator app-install sync keeps the historical skip behavior.
+   */
+  syncSymlinks?: boolean;
   /**
    * Extra files to sync into limbuild. These are included
    * in every sync pass but are not watched directly.
@@ -77,6 +83,12 @@ type FileEntry = {
   sha256: string;
   absPath: string;
   mode: number;
+  /**
+   * Symlink target (literal readlink output, forward slashes). Non-empty
+   * marks a symlink entry: the target string is the content (sha256/size
+   * describe it) and the entry never carries a payload.
+   */
+  linkTarget?: string;
 };
 
 type FolderSyncHttpPayload = {
@@ -94,7 +106,7 @@ type FolderSyncHttpMeta = {
   rootName: string;
   install?: boolean;
   launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
-  files: { path: string; size: number; sha256: string; mode: number }[];
+  files: { path: string; size: number; sha256: string; mode?: number; link?: string }[];
   payloads: FolderSyncHttpPayload[];
 };
 type FolderSyncHttpResponse = {
@@ -109,6 +121,10 @@ type FolderSyncHttpResponse = {
   error?: string;
 };
 
+/** Full uploads at or above this size get an info-level notice so "sync is
+ * stuck" turns into "a GB-scale file is being uploaded". */
+const LARGE_UPLOAD_NOTICE_BYTES = 64 * 1024 * 1024;
+
 const noopLogger = (_level: 'debug' | 'info' | 'warn' | 'error', _msg: string) => {
   // Intentionally empty: callers (e.g. ios-client.ts) should provide their own logger
   // to control verbosity and integrate with the SDK's logging setup.
@@ -269,7 +285,35 @@ async function sha256FileHex(filePath: string): Promise<string> {
   });
 }
 
-async function walkFiles(root: string, ignoreFn: IgnoreFn): Promise<FileEntry[]> {
+/**
+ * Validates a symlink's readlink target at sync time: it must be relative,
+ * backslash-free, and lexically resolve inside the sync root when joined
+ * with the link's directory (the daemon enforces the same policy on apply,
+ * so failing here is the same failure with a better message).
+ */
+function validateSymlinkTarget(rel: string, target: string): void {
+  if (target.includes('\\')) {
+    throw new Error(
+      `symlink ${rel} -> ${target} target contains a backslash, which the daemon rejects; ` +
+        'remove the link or pass --ignore to skip it',
+    );
+  }
+  const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(rel), target));
+  if (resolved === '.' || resolved === '..' || resolved.startsWith('../')) {
+    throw new Error(
+      `symlink ${rel} -> ${target} points outside the sync root; ` +
+        'run the sync from the repo root that contains the target, remove the link, ' +
+        'or pass --ignore to skip it',
+    );
+  }
+}
+
+async function walkFiles(
+  root: string,
+  ignoreFn: IgnoreFn,
+  syncSymlinks: boolean,
+  log?: FolderSyncOptions['log'],
+): Promise<FileEntry[]> {
   const rootResolved = path.resolve(root);
   const rootStat = await fs.promises.stat(rootResolved);
   if (rootStat.isFile()) {
@@ -305,6 +349,36 @@ async function walkFiles(root: string, ignoreFn: IgnoreFn): Promise<FileEntry[]>
         stack.push(abs);
         continue;
       }
+      if (ent.isSymbolicLink()) {
+        if (!syncSymlinks) continue;
+        // Symlinks ship as link entries with the literal target: a
+        // symlinked directory arrives here too and is sent as a link, not
+        // traversed (git semantics). The target string is the content.
+        // Probe both forms: a symlink named e.g. `Pods` or `build` may point
+        // at a directory, so directory-only excludes (`Pods/`, `build/`)
+        // must match it and skip before validation rejects an out-of-root
+        // target.
+        if (ignoreFn(rel) || ignoreFn(rel + '/')) continue;
+        const target = (await fs.promises.readlink(abs)).split(path.sep).join('/');
+        // An absolute target can never resolve remotely and no sync root
+        // can contain it; skip it like pre-symlink clients did (with a
+        // warning) instead of failing a previously working sync.
+        if (path.posix.isAbsolute(target) || path.win32.isAbsolute(target)) {
+          log?.('warn', `skipping symlink ${rel} -> ${target}: absolute targets cannot resolve remotely`);
+          continue;
+        }
+        validateSymlinkTarget(rel, target);
+        const sha256 = crypto.createHash('sha256').update(target).digest('hex');
+        out.push({
+          path: rel,
+          size: Buffer.byteLength(target),
+          sha256,
+          absPath: abs,
+          mode: 0,
+          linkTarget: target,
+        });
+        continue;
+      }
       if (!ent.isFile()) continue;
 
       // Check custom ignores for files
@@ -329,7 +403,9 @@ async function collectAdditionalFiles(
   }
   const out: FileEntry[] = [];
   for (const additionalFile of additionalFiles) {
-    const remotePath = additionalFile.remotePath;
+    // Canonicalize user-supplied remote paths ("./netrc" -> "netrc") so the
+    // manifest key matches what the daemon applies and echoes in needFull.
+    const remotePath = path.posix.normalize(additionalFile.remotePath);
     const absPath = path.resolve(additionalFile.localPath);
     const st = await fs.promises.stat(absPath);
     if (!st.isFile()) {
@@ -449,9 +525,48 @@ export async function encodeXdelta3Patch(
   return bytesWritten;
 }
 
-async function cachePut(cacheRoot: string, relPath: string, srcFile: string): Promise<void> {
-  const dst = path.join(cacheRoot, relPath.split('/').join(path.sep));
+async function cachePut(
+  cacheRoot: string,
+  relPath: string,
+  srcFile: string,
+  linkTarget?: string,
+  checkedDirs?: Set<string>,
+): Promise<void> {
+  const segments = relPath.split('/');
+  const dst = path.join(cacheRoot, segments.join(path.sep));
+  // Remove any ancestor that is not a real directory before mkdir/write: a
+  // path that previously synced as a symlink (or a regular file that became
+  // a directory) leaves a stale cache inode, and writing children through a
+  // symlink would corrupt the link target's cached entries while mkdir over
+  // a file throws after the server already applied. Only relevant when
+  // symlink sync is on; the caller passes checkedDirs (which also memoizes
+  // ancestors already confirmed real, so the sorted walk skips shared
+  // prefixes) then and omits it otherwise to skip the sweep entirely.
+  if (checkedDirs) {
+    let ancestor = cacheRoot;
+    for (let i = 0; i < segments.length - 1; i++) {
+      ancestor = path.join(ancestor, segments[i]!);
+      if (checkedDirs.has(ancestor)) continue;
+      const ast = await fs.promises.lstat(ancestor).catch(() => null);
+      if (ast && !ast.isDirectory()) {
+        await fs.promises.rm(ancestor, { recursive: true, force: true });
+      } else if (ast) {
+        checkedDirs.add(ancestor);
+      }
+    }
+  }
   await fs.promises.mkdir(path.dirname(dst), { recursive: true });
+  // Replace the destination inode when its type doesn't match what we're
+  // writing: a stale symlink (copyFile would follow it) or a stale directory
+  // (copyFile onto a dir throws EISDIR) left by a since-changed path.
+  const st = await fs.promises.lstat(dst).catch(() => null);
+  if (st && (st.isSymbolicLink() || st.isDirectory() || linkTarget !== undefined)) {
+    await fs.promises.rm(dst, { recursive: true, force: true });
+  }
+  if (linkTarget !== undefined) {
+    await fs.promises.symlink(linkTarget, dst);
+    return;
+  }
   await fs.promises.copyFile(srcFile, dst);
 }
 
@@ -567,7 +682,7 @@ async function syncFolderOnce(
   const log = opts.log ?? noopLogger;
   const slog = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => log(level, `syncFolder: ${msg}`);
 
-  const files = await walkFiles(localFolderPath, opts.ignoreFn);
+  const files = await walkFiles(localFolderPath, opts.ignoreFn, opts.syncSymlinks ?? false, slog);
   const additionalFiles = await collectAdditionalFiles(opts.additionalFiles);
   const allFiles = [...files, ...additionalFiles].sort((a, b) => a.path.localeCompare(b.path));
   const fileMap = new Map(allFiles.map((f) => [f.path, f]));
@@ -587,11 +702,30 @@ async function syncFolderOnce(
   type EncodedPayload = { payload: FolderSyncHttpPayload; filePath: string; cleanupDir?: string };
 
   // Build payload list by comparing against local basis cache (single-flight/watch assumes server matches cache).
+  // lstat, never stat/existsSync: those follow symlinks and misreport a
+  // basis symlink (dangling or pointing at another cached file) as the
+  // file itself.
   const encodeLimit = concurrencyLimit();
   const changed: FileEntry[] = [];
   for (const f of allFiles) {
     const basisPath = cacheGet(opts.basisCacheDir, f.path);
-    if (!fs.existsSync(basisPath)) {
+    const basisStat = await fs.promises.lstat(basisPath).catch(() => null);
+    if (!basisStat) {
+      changed.push(f);
+      continue;
+    }
+    if (f.linkTarget !== undefined) {
+      if (!basisStat.isSymbolicLink()) {
+        changed.push(f);
+        continue;
+      }
+      const basisTarget = (await fs.promises.readlink(basisPath)).split(path.sep).join('/');
+      if (basisTarget !== f.linkTarget) {
+        changed.push(f);
+      }
+      continue;
+    }
+    if (!basisStat.isFile()) {
       changed.push(f);
       continue;
     }
@@ -601,9 +735,17 @@ async function syncFolderOnce(
     }
   }
 
-  const encodedPayloads = await mapLimit(changed, encodeLimit, async (f): Promise<EncodedPayload> => {
+  // Symlink entries travel in the manifest only, with no payloads.
+  const changedFiles = changed.filter((f) => f.linkTarget === undefined);
+  // Grows in the needFull retry below; sized here so the summary counts
+  // every path that actually shipped this sync.
+  const changedPaths = new Set(changed.map((f) => f.path));
+
+  const encodedPayloads = await mapLimit(changedFiles, encodeLimit, async (f): Promise<EncodedPayload> => {
     const basisPath = cacheGet(opts.basisCacheDir, f.path);
-    if (f.size >= MIN_XDELTA_TARGET_BYTES && fs.existsSync(basisPath)) {
+    const basisStat =
+      f.size >= MIN_XDELTA_TARGET_BYTES ? await fs.promises.lstat(basisPath).catch(() => null) : null;
+    if (basisStat?.isFile()) {
       const basisSha = await sha256FileHex(basisPath);
       const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'limulator-xdelta3-'));
       const patchPath = path.join(tmpDir, 'patch.xdelta3');
@@ -642,6 +784,9 @@ async function syncFolderOnce(
       }
     }
     slog('debug', `full(file): ${f.path} size=${f.size}`);
+    if (f.size >= LARGE_UPLOAD_NOTICE_BYTES) {
+      slog('info', `uploading large file ${f.path} (${fmtBytes(f.size)})`);
+    }
     bytesSentFull += f.size;
     return {
       payload: {
@@ -663,7 +808,8 @@ async function syncFolderOnce(
       path: f.path,
       size: f.size,
       sha256: f.sha256.toLowerCase(),
-      mode: f.mode,
+      // Symlink entries carry the target; regular files carry the mode bits.
+      ...(f.linkTarget !== undefined ? { link: f.linkTarget } : { mode: f.mode }),
     })),
     payloads: encodedPayloads.map((p) => p.payload),
   };
@@ -696,10 +842,29 @@ async function syncFolderOnce(
   // Retry once if server needs full for some paths (basis mismatch).
   if (!resp.ok && resp.needFull && resp.needFull.length > 0) {
     const need = new Set(resp.needFull);
+    // A daemon that predates symlink support json-drops the `link` field and
+    // asks for these entries as full files. Streaming absPath would FOLLOW
+    // the link and silently materialize target content remotely, so fail loud
+    // instead. (New daemons never put symlink entries in needFull.)
+    const needFullLinks = [...need].filter((p) => fileMap.get(p)?.linkTarget !== undefined);
+    if (needFullLinks.length > 0) {
+      throw new Error(
+        "this instance's build daemon does not support symlinks yet (needs an updated limbuild); " +
+          `recreate the instance or retry later. Paths: ${needFullLinks.join(', ')}`,
+      );
+    }
     const retryPayloads: EncodedPayload[] = [];
     for (const p of need) {
       const entry = fileMap.get(p);
       if (!entry) continue;
+      // The retry uploads real bytes: count them (and surface large files)
+      // exactly like first-pass fulls, or a fresh-daemon resync of a warm
+      // cache reports "sent=0B" while gigabytes upload.
+      if (entry.size >= LARGE_UPLOAD_NOTICE_BYTES) {
+        slog('info', `uploading large file ${entry.path} (${fmtBytes(entry.size)})`);
+      }
+      bytesSentFull += entry.size;
+      changedPaths.add(entry.path);
       retryPayloads.push({
         payload: {
           kind: 'full',
@@ -709,10 +874,12 @@ async function syncFolderOnce(
         },
         filePath: entry.absPath,
       });
-      bytesSentFull += entry.size;
     }
     if (retryPayloads.length > 0) {
-      slog('debug', `server requested full for ${retryPayloads.length} files; retrying once`);
+      slog(
+        'info',
+        `daemon requested a full upload for ${retryPayloads.length} files (no matching basis); retrying once`,
+      );
       const retryMeta: FolderSyncHttpMeta = {
         ...meta,
         id: genId('sync'),
@@ -749,11 +916,12 @@ async function syncFolderOnce(
   const tookMs = nowMs() - totalStart;
   const totalBytes = bytesSentFull + bytesSentDelta;
   slog(
-    'debug',
-    `sync finished files=${allFiles.length} sent=${fmtBytes(totalBytes)} syncWork=${fmtMs(
-      syncWorkMs,
-    )} total=${fmtMs(tookMs)}`,
+    'info',
+    `sync complete: files=${allFiles.length} changed=${changedPaths.size} sent=${fmtBytes(
+      totalBytes,
+    )} in ${fmtMs(tookMs)}`,
   );
+  slog('debug', `sync timing syncWork=${fmtMs(syncWorkMs)} total=${fmtMs(tookMs)}`);
   const out: SyncFolderResult = { bytesSent: totalBytes };
   if (resp.installedAppPath) {
     out.installedAppPath = resp.installedAppPath;
@@ -762,8 +930,12 @@ async function syncFolderOnce(
     out.installedBundleId = resp.bundleId;
   }
   // Update local cache optimistically: after a successful sync, cache reflects current local tree.
+  // The stale-symlink-ancestor sweep only matters when symlink sync is on
+  // (otherwise the cache never holds a symlink); checkedDirs memoizes ancestors
+  // across the sorted walk.
+  const checkedDirs = opts.syncSymlinks ? new Set<string>() : undefined;
   for (const f of allFiles) {
-    await cachePut(opts.basisCacheDir, f.path, f.absPath);
+    await cachePut(opts.basisCacheDir, f.path, f.absPath, f.linkTarget, checkedDirs);
   }
   return out;
 }

package/src/ios-client.ts

@@ -270,17 +270,17 @@ export type DetoxLaunchRuntime = {
 
 export type LaunchAppRuntime = DetoxLaunchRuntime;
 
-export type LaunchAppShutdownCallback = (exitCode: number, logs: string[]) => Promise<void>;
+export type LaunchAppExitCallback = (logs: string[]) => Promise<void>;
 
-type LaunchAppShutdownOptions = {
+type LaunchAppExitOptions = {
   /**
    * Called when the launched app exits. The logs array contains one entry per
    * stdout/stderr line produced by that execution, as reported by limulator.
    */
-  onShutdown?: LaunchAppShutdownCallback;
+  onExit?: LaunchAppExitCallback;
 };
 
-type StandardLaunchAppOptions = LaunchAppShutdownOptions & {
+type StandardLaunchAppOptions = LaunchAppExitOptions & {
   /**
    * Launch behavior when the app may already be running.
    * Defaults to `ForegroundIfRunning` server-side.
@@ -289,7 +289,7 @@ type StandardLaunchAppOptions = LaunchAppShutdownOptions & {
   runtime?: undefined;
 };
 
-type RuntimeLaunchAppOptions = LaunchAppShutdownOptions & {
+type RuntimeLaunchAppOptions = LaunchAppExitOptions & {
   /** Runtime launches must relaunch so runtime injection is applied. */
   mode?: Extract<LaunchAppMode, 'RelaunchIfRunning'>;
   /** Optional app runtime to attach during launch. */
@@ -970,7 +970,7 @@ type ServerResponse = {
   exitCode?: number;
   // Log tail fields
   logs?: string;
-  // App shutdown fields
+  // App exit fields
   execId?: string;
   logLineCount?: number;
   // App log streaming fields
@@ -1546,33 +1546,31 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return logs.split(/\r?\n/);
     };
 
-    const handleAppShutdown = (message: ServerResponse): boolean => {
-      if (message.type !== 'appShutdown') {
+    const handleAppExit = (message: ServerResponse): boolean => {
+      if (message.type !== 'appExit') {
         return false;
       }
 
-      const { execId, bundleId, exitCode, logLineCount } = message;
+      const { execId, bundleId, logLineCount } = message;
       if (
         typeof execId !== 'string' ||
         typeof bundleId !== 'string' ||
-        typeof exitCode !== 'number' ||
-        !Number.isInteger(exitCode) ||
         typeof logLineCount !== 'number' ||
         !Number.isInteger(logLineCount) ||
         logLineCount < 0
       ) {
-        logger.warn('Received malformed appShutdown message:', message);
+        logger.warn('Received malformed appExit message:', message);
         return true;
       }
 
-      const notification = takeServerNotification('appShutdown', execId);
+      const notification = takeServerNotification('appExit', execId);
       if (!notification) {
-        logger.debug(`Received appShutdown for unknown or already handled execId: ${execId}`);
+        logger.debug(`Received appExit for unknown or already handled execId: ${execId}`);
         return true;
       }
 
       void notification(message).catch((error) => {
-        logger.error(`Error processing appShutdown notification for execId ${execId}:`, error);
+        logger.error(`Error processing appExit notification for execId ${execId}:`, error);
       });
 
       return true;
@@ -1652,7 +1650,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
           return;
         }
 
-        if (handleAppShutdown(message)) {
+        if (handleAppExit(message)) {
           return;
         }
 
@@ -1912,20 +1910,18 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         );
       }
       const mode = launchOptions.runtime ? 'RelaunchIfRunning' : launchOptions.mode;
-      const onShutdown = launchOptions.onShutdown;
-      const execId = onShutdown ? generateId() : undefined;
-      if (execId && onShutdown) {
-        registerServerNotification('appShutdown', execId, async (message) => {
-          const { bundleId, exitCode, logLineCount } = message;
+      const onExit = launchOptions.onExit;
+      const execId = onExit ? generateId() : undefined;
+      if (execId && onExit) {
+        registerServerNotification('appExit', execId, async (message) => {
+          const { bundleId, logLineCount } = message;
           if (
             typeof bundleId !== 'string' ||
-            typeof exitCode !== 'number' ||
-            !Number.isInteger(exitCode) ||
             typeof logLineCount !== 'number' ||
             !Number.isInteger(logLineCount) ||
             logLineCount < 0
           ) {
-            logger.warn(`Received malformed appShutdown payload for execId ${execId}:`, message);
+            logger.warn(`Received malformed appExit payload for execId ${execId}:`, message);
             return;
           }
 
@@ -1935,13 +1931,13 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
               await sendRequest<string>('appLogTail', { bundleId, lines: logLineCount }),
             );
           } catch (error) {
-            logger.error(`Failed to fetch app logs for shutdown execId ${execId}:`, error);
+            logger.error(`Failed to fetch app logs for exit execId ${execId}:`, error);
           }
 
           try {
-            await onShutdown(exitCode, logs);
+            await onExit(logs);
           } catch (error) {
-            logger.error(`Error in onShutdown callback for execId ${execId}:`, error);
+            logger.error(`Error in onExit callback for execId ${execId}:`, error);
           }
         });
       }
@@ -1952,7 +1948,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         execId,
       }).catch((error) => {
         if (execId) {
-          deleteServerNotification('appShutdown', execId);
+          deleteServerNotification('appExit', execId);
         }
         throw error;
       });

package/src/resources/xcode-instances-helpers.ts

@@ -45,6 +45,12 @@ export type SyncOptions = {
    * Return true to ignore, false to keep.
    */
   ignore?: (relativePath: string) => boolean;
+  /**
+   * Optional predicate for force-including paths that would otherwise be
+   * dropped (gitignored generated sources, default Xcode excludes). Same
+   * calling convention as `ignore`; return true to force-sync the path.
+   */
+  include?: (relativePath: string) => boolean;
   /**
    * Extra files to sync on every sync pass.
    */
@@ -596,40 +602,18 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           ignoreFn: await createIgnoreFn(localCodePath, {
             basisCacheDir,
             log,
-            additional: (relativePath: string) => {
-              if (
-                relativePath.startsWith('build/') ||
-                relativePath.startsWith('.build/') ||
-                relativePath.startsWith('DerivedData/') ||
-                relativePath.startsWith('Index.noindex/') ||
-                relativePath.startsWith('ModuleCache.noindex/') ||
-                relativePath.startsWith('.index-build/')
-              ) {
-                return true;
-              }
-              if (
-                relativePath.startsWith('.swiftpm/') ||
-                relativePath.startsWith('Pods/') ||
-                relativePath.startsWith('Carthage/Build/')
-              ) {
-                return true;
-              }
-              if (relativePath.includes('/xcuserdata/')) {
-                return true;
-              }
-              if (relativePath.includes('.dSYM/')) {
-                return true;
-              }
-              if (opts?.ignore?.(relativePath)) {
-                return true;
-              }
-              return false;
-            },
+            xcodeDefaults: true,
+            ...(opts?.include ? { include: opts.include } : {}),
+            ...(opts?.ignore ? { additional: opts.ignore } : {}),
           }),
           basisCacheDir,
           watch: opts?.watch ?? true,
           launchMode: 'ForegroundIfRunning',
           log,
+          // The limbuild workspace sync understands symlink entries; the
+          // limulator app-install sync (ios-client.ts) does not and keeps
+          // the default skip behavior.
+          syncSymlinks: true,
           ...(additionalFiles ? { additionalFiles } : {}),
         };
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.39.3'; // x-release-please-version
+export const VERSION = '0.39.5'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.39.3";
+export declare const VERSION = "0.39.5";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.39.3";
+export declare const VERSION = "0.39.5";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.39.3'; // x-release-please-version
+exports.VERSION = '0.39.5'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.39.3'; // x-release-please-version
+export const VERSION = '0.39.5'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map