@limrun/api 0.39.4 → 0.39.6

package/src/folder-sync-ignore.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import ignorePkg from 'ignore';
+import ignorePkg, { type Ignore } from 'ignore';
 
 const execFileAsync = promisify(execFile);
 
@@ -11,7 +11,26 @@ export type IgnoreFn = (relativePath: string) => boolean;
 export type IgnoreLogger = (level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void;
 
 export type IgnoreFnOptions = {
+  /** User-supplied extra excludes (the CLI's --ignore). Consulted after every built-in layer. */
   additional?: IgnoreFn;
+  /**
+   * User-supplied force-includes (the CLI's --include): matches sync even when
+   * gitignored or covered by the default Xcode excludes. Only `.git`,
+   * `.DS_Store`, and the basis cache stay excluded. Note: the walk prunes
+   * gitignore-excluded directories, so to rescue files under a wholly-ignored
+   * parent the predicate must also match the parent directory paths (probed
+   * with a trailing slash), e.g. `^ios/` reaches `ios/GeneratedKit/...` but
+   * `GeneratedKit/` alone does not.
+   */
+  include?: IgnoreFn;
+  /**
+   * "Xcode project sync mode." Enables the default Xcode/dependency excludes
+   * (build/, Pods/, xcuserdata/, …) and nested-.gitignore honoring. When
+   * unset (e.g. the app-bundle install sync) only the root .gitignore is
+   * read, so a build artifact isn't reshaped by gitignore files embedded
+   * in it.
+   */
+  xcodeDefaults?: boolean;
   basisCacheDir: string;
   log?: IgnoreLogger;
 };
@@ -52,21 +71,98 @@ async function getGitTrackedSets(rootDir: string): Promise<GitTrackedSets | null
   }
 }
 
+// Root-anchored (top-level only) default excludes; nested build junk is the
+// project's own nested .gitignore's job. xcuserdata/.dSYM below are any-depth.
+const XCODE_DEFAULT_EXCLUDE_PREFIXES = [
+  'build/',
+  '.build/',
+  'DerivedData/',
+  'Index.noindex/',
+  'ModuleCache.noindex/',
+  '.index-build/',
+  '.swiftpm/',
+  'Pods/',
+  'Carthage/Build/',
+];
+
+/**
+ * Builds the layered sync ignore predicate. First decisive answer wins:
+ *
+ *  1. `.git`, `.DS_Store`, the basis cache: excluded, never overridable.
+ *  2. User include (--include): explicit intent beats the default excludes.
+ *  3. Default Xcode/dependency excludes (when xcodeDefaults is set).
+ *  4. Built-in force-include: `*.xcconfig` (gitignored xcconfigs are still
+ *     required to reproduce the build remotely). Gitignored projects are NOT
+ *     force-included: limbuild regenerates them from project.yml, and
+ *     exact-version holdouts force-sync theirs with `--include`.
+ *  5. `.gitignore` chain: the root file, plus nested ones with git semantics
+ *     when xcodeDefaults is set (rules bind relative to their containing
+ *     directory, deeper files override shallower ones). Only a decisive
+ *     *exclude* short-circuits; a negation re-include defers to layer 6.
+ *     Directory pruning in the walk means only layers 2 and 4 can reach a
+ *     file whose parent directory is gitignore-excluded, and only when the
+ *     predicate matches the pruned parent directory paths too.
+ *  6. User ignore (--ignore).
+ */
 export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions): Promise<IgnoreFn> {
   const rootResolved = path.resolve(rootDir);
+
+  // Per-directory .gitignore instances, lazily loaded; key is the dir path
+  // relative to the root ('' = root), value null when the dir has none.
   // ignorecase: false matches git's default semantics. The package defaults to true,
   // which silently drops e.g. `Vendor/` when .gitignore says `vendor/` (Ruby convention).
   // allowRelativePaths: true so a `../`-style path doesn't throw mid-sync — treat it as
   // "not ignored" and let it through, since the cost of dropping a needed file is higher
   // than including an unexpected one.
-  const ig = ignorePkg({ ignorecase: false, allowRelativePaths: true });
-  const gitignorePath = path.join(rootResolved, '.gitignore');
-  try {
-    const content = await fs.promises.readFile(gitignorePath, 'utf-8');
-    ig.add(content);
-  } catch {
-    // No .gitignore file, return empty ignore instance
-  }
+  const dirIgnores = new Map<string, Ignore | null>();
+  const gitignoreFor = (dirRel: string): Ignore | null => {
+    let ig = dirIgnores.get(dirRel);
+    if (ig !== undefined) return ig;
+    try {
+      const content = fs.readFileSync(
+        path.join(rootResolved, dirRel.split('/').join(path.sep), '.gitignore'),
+        'utf-8',
+      );
+      ig = ignorePkg({ ignorecase: false, allowRelativePaths: true }).add(content);
+    } catch {
+      ig = null;
+    }
+    dirIgnores.set(dirRel, ig);
+    return ig;
+  };
+
+  // xcodeDefaults selects "Xcode project sync mode": besides the default junk
+  // excludes it also enables nested-.gitignore honoring and the project-file
+  // force-includes below. Callers that don't set it (e.g. the app-bundle
+  // install sync) keep the legacy behavior: root-only .gitignore and no
+  // project force-includes, so a build artifact isn't reshaped by gitignore
+  // files or Xcode-specific rules that happen to sit inside it.
+  const nestedGitignore = !!options.xcodeDefaults;
+
+  // Evaluates the .gitignore chain for a path (trailing slash preserved so
+  // dir-only rules like `build/` match the directory itself). Files are
+  // consulted root-to-deepest; the last decisive match wins, so deeper
+  // files naturally override shallower ones. When nestedGitignore is off,
+  // only the root .gitignore is consulted.
+  const gitignoreDecision = (testPath: string): { ignored: boolean; rule?: string } | undefined => {
+    const withoutTrailingSlash = testPath.replace(/\/+$/, '');
+    const trailingSlash = testPath.endsWith('/') ? '/' : '';
+    const parts = withoutTrailingSlash.split('/');
+    let decision: { ignored: boolean; rule?: string } | undefined;
+    const depth = nestedGitignore ? parts.length : 1;
+    for (let i = 0; i < depth; i++) {
+      const ig = gitignoreFor(parts.slice(0, i).join('/'));
+      if (!ig) continue;
+      const result = ig.test(parts.slice(i).join('/') + trailingSlash);
+      if (result.ignored || result.unignored) {
+        decision = { ignored: result.ignored };
+        const rule = (result as { rule?: { pattern?: string } }).rule?.pattern;
+        if (rule !== undefined) decision.rule = rule;
+      }
+    }
+    return decision;
+  };
+
   const basisCacheRelative = normalizeRelativePath(
     path.relative(rootResolved, options.basisCacheDir),
   ).replace(/\/+$/, '');
@@ -86,6 +182,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     if (!normalized) return false;
     const withoutTrailingSlash = normalized.replace(/\/+$/, '');
 
+    // 1. Never overridable.
     if (
       withoutTrailingSlash === '.git' ||
       withoutTrailingSlash.startsWith('.git/') ||
@@ -103,16 +200,34 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
     ) {
       return true;
     }
+    // 2. User include.
+    if (options.include?.(normalized)) return false;
+    // 3. Default Xcode/dependency excludes.
+    if (options.xcodeDefaults) {
+      for (const prefix of XCODE_DEFAULT_EXCLUDE_PREFIXES) {
+        if (normalized.startsWith(prefix)) return true;
+      }
+      if (normalized.includes('/xcuserdata/') || normalized.includes('.dSYM/')) return true;
+    }
+    // 4. Built-in force-include: gitignored xcconfigs are still required to
+    // reproduce the build remotely. Gitignored .xcodeproj bundles are NOT
+    // force-included: limbuild regenerates them from project.yml, and
+    // exact-version holdouts force-sync theirs with --include.
     if (withoutTrailingSlash.endsWith('.xcconfig')) return false;
-    if (ig.ignores(normalized)) {
+    // 5. The .gitignore chain. Only a decisive *exclude* short-circuits; a
+    // negation re-include (decision.ignored === false) still falls through to
+    // the user --ignore layer, matching the pre-restructure precedence where
+    // gitignore never overrode --ignore for a re-included path.
+    const decision = gitignoreDecision(normalized);
+    if (decision?.ignored) {
       if (
         trackedSets &&
         (trackedSets.tracked.has(withoutTrailingSlash) || trackedSets.prefixes.has(withoutTrailingSlash))
       ) {
-        const rule = ig.test(normalized).rule?.pattern ?? '<unknown>';
+        const rule = decision.rule ?? '<unknown>';
         if (!warnedRules.has(rule)) {
           warnedRules.add(rule);
-          const msg = `.gitignore rule '${rule}' is dropping '${withoutTrailingSlash}', which is tracked in git. The remote build will not see this path. Remove or scope the rule if you need it synced.`;
+          const msg = `.gitignore rule '${rule}' is dropping '${withoutTrailingSlash}', which is tracked in git. The remote build will not see this path. Remove or scope the rule, or pass --include, if you need it synced.`;
           if (log) {
             log('warn', msg);
           } else {
@@ -122,6 +237,7 @@ export async function createIgnoreFn(rootDir: string, options: IgnoreFnOptions):
       }
       return true;
     }
+    // 6. User ignore.
     if (options.additional?.(normalized)) return true;
     return false;
   };

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/instance-client.ts

@@ -96,6 +96,7 @@ async function bootstrapAndroidBasisCache(
   apiUrl: string,
   token: string,
   log: FolderSyncOptions['log'],
+  onBasisDownload?: (sizeBytes?: number) => void,
 ): Promise<void> {
   const remotePath = path.basename(apkPath);
   const basisPath = path.join(basisCacheDir, remotePath);
@@ -130,6 +131,7 @@ async function bootstrapAndroidBasisCache(
   if (!seed) {
     return;
   }
+  onBasisDownload?.(seed.size);
   await downloadFileToLocalPath(buildSyncSeedUrl(apiUrl, seed.sha256), token, basisPath);
   log('debug', `seeded Android basis cache from instance seed: ${seed.sha256}`);
 }
@@ -237,6 +239,7 @@ export type InstanceClient = {
       watch?: boolean;
       launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning';
       basisCacheDir?: string;
+      onBasisDownload?: (sizeBytes?: number) => void;
     },
   ) => Promise<SyncFolderResult>;
 
@@ -1294,7 +1297,14 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         }
       };
       await fs.promises.mkdir(basisCacheDir, { recursive: true });
-      await bootstrapAndroidBasisCache(resolvedPath, basisCacheDir, options.apiUrl, options.token, syncLog);
+      await bootstrapAndroidBasisCache(
+        resolvedPath,
+        basisCacheDir,
+        options.apiUrl,
+        options.token,
+        syncLog,
+        syncOpts?.onBasisDownload,
+      );
       return await syncFolder(resolvedPath, {
         apiUrl: options.apiUrl,
         token: options.token,

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.4'; // x-release-please-version
+export const VERSION = '0.39.6'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.39.4";
+export declare const VERSION = "0.39.6";
 //# 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.4'; // x-release-please-version
+exports.VERSION = '0.39.6'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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