@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/menubar/swiftbar.test.mjs

@@ -0,0 +1,85 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { lstat, mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  detectSwiftbarPluginInstalled,
+  removeSwiftbarPlugins,
+  resolveSwiftbarPluginsDir,
+} from './swiftbar.mjs';
+
+test('detectSwiftbarPluginInstalled treats matching symlinks as installed', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-swiftbar-'));
+  try {
+    const pluginsDir = join(tmp, 'plugins');
+    await mkdir(pluginsDir, { recursive: true });
+
+    const target = join(tmp, 'target.sh');
+    const link = join(pluginsDir, 'hstack.5m.sh');
+    await writeFile(target, '#!/bin/sh\necho ok\n', 'utf-8');
+    await symlink(target, link);
+
+    const detected = await detectSwiftbarPluginInstalled({
+      pluginsDir,
+      patterns: ['hstack.*.sh'],
+      env: process.env,
+    });
+    assert.equal(detected.installed, true);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('removeSwiftbarPlugins removes matching symlink plugins', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-swiftbar-'));
+  try {
+    const pluginsDir = join(tmp, 'plugins');
+    await mkdir(pluginsDir, { recursive: true });
+
+    const target = join(tmp, 'target.sh');
+    const link = join(pluginsDir, 'hstack.5m.sh');
+    await writeFile(target, '#!/bin/sh\necho ok\n', 'utf-8');
+    await symlink(target, link);
+
+    const res = await removeSwiftbarPlugins({
+      pluginsDir,
+      patterns: ['hstack.*.sh'],
+      env: process.env,
+    });
+    assert.equal(res.ok, true);
+    assert.equal(res.removed, true);
+    await assert.rejects(() => lstat(link), /ENOENT/i);
+    const detected = await detectSwiftbarPluginInstalled({
+      pluginsDir,
+      patterns: ['hstack.*.sh'],
+      env: process.env,
+    });
+    assert.equal(detected.installed, false);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('resolveSwiftbarPluginsDir ignores override on non-darwin unless explicitly enabled', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-swiftbar-'));
+  try {
+    const pluginsDir = join(tmp, 'plugins');
+    await mkdir(pluginsDir, { recursive: true });
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_SWIFTBAR_PLUGINS_DIR: pluginsDir,
+    };
+
+    const resolved = await resolveSwiftbarPluginsDir({ env });
+    if (process.platform === 'darwin') {
+      assert.equal(resolved, pluginsDir);
+    } else {
+      assert.equal(resolved, null);
+    }
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/mobile/config.mjs

@@ -0,0 +1,35 @@
+import { sanitizeBundleIdSegment, sanitizeUrlScheme } from './identifiers.mjs';
+
+export function resolveMobileExpoConfig({ env = process.env } = {}) {
+  const user = sanitizeBundleIdSegment(env.USER ?? env.USERNAME ?? 'user');
+  const defaultLocalBundleId = `com.happier.local.${user}.dev`;
+
+  const appEnv = env.APP_ENV ?? env.HAPPIER_STACK_APP_ENV ?? 'development';
+  // Prefer stack-scoped config, but also support generic Expo build env vars so users can
+  // drive mobile identity purely via stack env files without learning hstack-specific keys.
+  const iosAppName = (env.HAPPIER_STACK_IOS_APP_NAME ?? env.EXPO_APP_NAME ?? '').toString();
+  const iosBundleId = (
+    env.HAPPIER_STACK_IOS_BUNDLE_ID ??
+    env.EXPO_APP_BUNDLE_ID ??
+    defaultLocalBundleId
+  ).toString();
+  // hstack convention:
+  // - dev-client QR should open a dedicated "hstack Dev" app (not a per-stack release build)
+  // - so default to a stable happy-stacks-specific scheme unless explicitly overridden.
+  const scheme = sanitizeUrlScheme(
+    (env.HAPPIER_STACK_MOBILE_SCHEME ??
+      env.HAPPIER_STACK_DEV_CLIENT_SCHEME ??
+      env.EXPO_APP_SCHEME ??
+      'hstack-dev')
+      .toString()
+  );
+  const host = (env.HAPPIER_STACK_MOBILE_HOST ?? 'lan').toString();
+
+  return {
+    appEnv,
+    iosAppName,
+    iosBundleId,
+    scheme,
+    host,
+  };
+}

package/scripts/utils/mobile/dev_client_links.mjs

@@ -0,0 +1,59 @@
+import { getEnvValueAny } from '../env/values.mjs';
+import { pickLanIpv4 } from '../net/lan_ip.mjs';
+import { resolveMobileExpoConfig } from './config.mjs';
+
+function normalizeHostMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'localhost' || v === 'local') return 'localhost';
+  if (v === 'lan' || v === 'ip') return 'lan';
+  if (v === 'tunnel') return 'tunnel';
+  return v || 'lan';
+}
+
+export function resolveMobileHostMode(env = process.env) {
+  // Prefer explicit host vars (so TUI/setup-pr match the same knobs Expo uses).
+  const raw =
+    getEnvValueAny(env, ['HAPPIER_STACK_MOBILE_HOST']) ||
+    resolveMobileExpoConfig({ env }).host ||
+    'lan';
+  return normalizeHostMode(raw);
+}
+
+export function resolveMobileScheme(env = process.env) {
+  return String(resolveMobileExpoConfig({ env }).scheme || '').trim();
+}
+
+export function resolveMetroUrlForMobile({ env = process.env, port }) {
+  const p = Number(port);
+  if (!Number.isFinite(p) || p <= 0) return '';
+
+  const mode = resolveMobileHostMode(env);
+  if (mode === 'localhost') {
+    return `http://localhost:${p}`;
+  }
+  if (mode === 'lan') {
+    const ip = pickLanIpv4();
+    return `http://${ip || 'localhost'}:${p}`;
+  }
+  // Tunnel URLs are controlled by Expo; we can't reliably derive them locally.
+  // Fall back to localhost so the URL is at least correct for the host machine.
+  return `http://localhost:${p}`;
+}
+
+export function resolveDevClientDeepLink({ scheme, metroUrl }) {
+  const s = String(scheme ?? '').trim();
+  const url = String(metroUrl ?? '').trim();
+  if (!url) return '';
+  if (!s) return url;
+  return `${s}://expo-development-client/?url=${encodeURIComponent(url)}`;
+}
+
+export function resolveMobileQrPayload({ env = process.env, port }) {
+  const metroUrl = resolveMetroUrlForMobile({ env, port });
+  const scheme = resolveMobileScheme(env);
+  const deepLink = resolveDevClientDeepLink({ scheme, metroUrl });
+  // Match Expo CLI / @expo/cli UrlCreator: QR encodes the dev-client deep link.
+  // Note: iOS Camera will still offer to open custom schemes when the app is installed.
+  const payload = deepLink || metroUrl;
+  return { scheme, metroUrl, deepLink, payload };
+}

package/scripts/utils/mobile/identifiers.mjs

@@ -0,0 +1,46 @@
+function sanitizeToken(raw, { allowDots = false } = {}) {
+  const s = (raw ?? '').toString().trim().toLowerCase();
+  const re = allowDots ? /[^a-z0-9.-]+/g : /[^a-z0-9-]+/g;
+  const out = s.replace(re, '-').replace(/^-+|-+$/g, '').replace(/-+/g, '-');
+  return out;
+}
+
+export function sanitizeBundleIdSegment(s) {
+  const seg = sanitizeToken(s, { allowDots: false });
+  if (!seg) return 'app';
+  // Bundle id segments should not start with a digit; prefix if needed.
+  return /^[a-z]/.test(seg) ? seg : `s${seg}`;
+}
+
+export function sanitizeUrlScheme(s) {
+  // iOS URL schemes must start with a letter and may contain letters/digits/+.-.
+  const raw = (s ?? '').toString().trim().toLowerCase();
+  const cleaned = raw.replace(/[^a-z0-9+.-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+  if (!cleaned) return 'happier-dev';
+  return /^[a-z]/.test(cleaned) ? cleaned : `h${cleaned}`;
+}
+
+export function stackSlugForMobileIds(stackName) {
+  const raw = (stackName ?? '').toString().trim();
+  return sanitizeBundleIdSegment(raw || 'stack');
+}
+
+export function defaultDevClientIdentity({ user = null } = {}) {
+  const u = sanitizeBundleIdSegment(user ?? 'user');
+  return {
+    iosAppName: 'Happier Dev',
+    iosBundleId: `dev.happier.stack.dev.${u}`,
+    scheme: 'happier-dev',
+  };
+}
+
+export function defaultStackReleaseIdentity({ stackName, user = null, appName = null } = {}) {
+  const slug = stackSlugForMobileIds(stackName);
+  const u = sanitizeBundleIdSegment(user ?? 'user');
+  const label = (appName ?? '').toString().trim();
+  return {
+    iosAppName: label || `Happier (${stackName})`,
+    iosBundleId: `dev.happier.stack.stack.${u}.${slug}`,
+    scheme: sanitizeUrlScheme(`happier-${slug}`),
+  };
+}

package/scripts/utils/mobile/identifiers.test.mjs

@@ -0,0 +1,41 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  defaultDevClientIdentity,
+  defaultStackReleaseIdentity,
+  sanitizeBundleIdSegment,
+  sanitizeUrlScheme,
+  stackSlugForMobileIds,
+} from './identifiers.mjs';
+
+test('sanitizeBundleIdSegment produces a safe segment', () => {
+  assert.equal(sanitizeBundleIdSegment('  PR272-107  '), 'pr272-107');
+  assert.equal(sanitizeBundleIdSegment('---'), 'app');
+  assert.equal(sanitizeBundleIdSegment('123'), 's123');
+});
+
+test('sanitizeUrlScheme produces a safe scheme', () => {
+  assert.equal(sanitizeUrlScheme('Happier-Dev'), 'happier-dev');
+  assert.equal(sanitizeUrlScheme('123bad'), 'h123bad');
+  assert.equal(sanitizeUrlScheme(''), 'happier-dev');
+});
+
+test('stackSlugForMobileIds derives a stable slug', () => {
+  assert.equal(stackSlugForMobileIds('pr272-107-fixes-2026-01-15'), 'pr272-107-fixes-2026-01-15');
+  assert.equal(stackSlugForMobileIds('  Weird Name  '), 'weird-name');
+});
+
+test('defaultDevClientIdentity is stable and safe', () => {
+  const id = defaultDevClientIdentity({ user: 'Leeroy' });
+  assert.equal(id.iosAppName, 'Happier Dev');
+  assert.equal(id.scheme, 'happier-dev');
+  assert.equal(id.iosBundleId, 'dev.happier.stack.dev.leeroy');
+});
+
+test('defaultStackReleaseIdentity is per-stack', () => {
+  const id = defaultStackReleaseIdentity({ stackName: 'pr272-107', user: 'Leeroy' });
+  assert.equal(id.iosBundleId, 'dev.happier.stack.stack.leeroy.pr272-107');
+  assert.equal(id.scheme, 'happier-pr272-107');
+  assert.equal(id.iosAppName, 'Happier (pr272-107)');
+});

package/scripts/utils/mobile/ios_xcodeproj_patch.mjs

@@ -0,0 +1,128 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { pathExists } from '../fs/fs.mjs';
+
+function sanitizeXcodeProductName(name) {
+  const raw = (name ?? '').toString().trim();
+  const out = raw
+    .replace(/[^A-Za-z0-9_-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-_]+|[-_]+$/g, '');
+  return out || 'Happy';
+}
+
+async function listIosAppXcodeprojNames({ iosDir }) {
+  let entries = [];
+  try {
+    entries = await readdir(iosDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const names = entries
+    .filter((e) => e.isDirectory() && e.name.endsWith('.xcodeproj') && e.name.startsWith('Happy'))
+    .map((e) => e.name);
+
+  // Prefer the common names first to keep behavior stable if multiple projects exist.
+  const score = (name) => {
+    if (name === 'Happydev.xcodeproj') return 0;
+    if (name === 'Happy.xcodeproj') return 1;
+    return 2;
+  };
+  names.sort((a, b) => score(a) - score(b) || a.localeCompare(b));
+  return names;
+}
+
+export async function resolveIosAppXcodeProjects({ uiDir }) {
+  const iosDir = join(uiDir, 'ios');
+  const projectNames = await listIosAppXcodeprojNames({ iosDir });
+
+  const projects = [];
+  for (const projectName of projectNames) {
+    const pbxprojPath = join(iosDir, projectName, 'project.pbxproj');
+    if (!(await pathExists(pbxprojPath))) {
+      continue;
+    }
+
+    const appDirName = projectName.replace(/\.xcodeproj$/, '');
+    const infoPlistPath = join(iosDir, appDirName, 'Info.plist');
+
+    projects.push({
+      name: appDirName,
+      pbxprojPath,
+      infoPlistPath: (await pathExists(infoPlistPath)) ? infoPlistPath : null,
+    });
+  }
+
+  return projects;
+}
+
+export async function patchIosXcodeProjectsForSigningAndIdentity({
+  uiDir,
+  iosBundleId,
+  iosAppName = '',
+} = {}) {
+  const bundleId = (iosBundleId ?? '').toString().trim();
+  const appName = (iosAppName ?? '').toString().trim();
+  const productName = sanitizeXcodeProductName(appName);
+
+  if (!uiDir || !bundleId) {
+    return;
+  }
+
+  const projects = await resolveIosAppXcodeProjects({ uiDir });
+  if (projects.length === 0) {
+    return;
+  }
+
+  for (const project of projects) {
+    // Patch pbxproj: clear pinned signing fields so Expo can reconfigure and include provisioning update flags,
+    // and force a per-stack bundle id + optional PRODUCT_NAME.
+    try {
+      const raw = await readFile(project.pbxprojPath, 'utf-8');
+      let next = raw;
+
+      // Clear team identifiers (both TargetAttributes and build settings variants).
+      next = next.replaceAll(/^\s*DevelopmentTeam\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*DEVELOPMENT_TEAM\s*=\s*[^;]+;\s*$/gm, '');
+      // Clear any pinned provisioning profiles/specifiers (manual signing).
+      next = next.replaceAll(/^\s*PROVISIONING_PROFILE\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*PROVISIONING_PROFILE_SPECIFIER\s*=\s*[^;]+;\s*$/gm, '');
+      // Some projects pin code signing identity; remove to let Xcode resolve based on the selected team.
+      next = next.replaceAll(/^\s*CODE_SIGN_IDENTITY\s*=\s*[^;]+;\s*$/gm, '');
+      next = next.replaceAll(/^\s*"CODE_SIGN_IDENTITY\\[sdk=iphoneos\\*\\]"\s*=\s*[^;]+;\s*$/gm, '');
+
+      next = next.replaceAll(/PRODUCT_BUNDLE_IDENTIFIER = [^;]+;/g, `PRODUCT_BUNDLE_IDENTIFIER = ${bundleId};`);
+
+      if (appName) {
+        // Expo CLI appears to treat some escaped build paths as literal (e.g. "Happy\\ (stack).app"),
+        // so keep PRODUCT_NAME free of spaces to avoid breaking post-build Info.plist parsing.
+        next = next.replaceAll(/PRODUCT_NAME = [^;]+;/g, `PRODUCT_NAME = ${productName};`);
+      }
+
+      if (next !== raw) {
+        await writeFile(project.pbxprojPath, next, 'utf-8');
+      }
+    } catch {
+      // ignore project patch errors; Expo will surface actionable failures if needed
+    }
+
+    // Patch Info.plist display name when possible (home screen label).
+    if (appName && project.infoPlistPath) {
+      try {
+        const plistRaw = await readFile(project.infoPlistPath, 'utf-8');
+        const escaped = appName.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+        const replaced = plistRaw.replace(
+          /(<key>CFBundleDisplayName<\/key>\s*<string>)([\s\S]*?)(<\/string>)/m,
+          `$1${escaped}$3`
+        );
+        if (replaced !== plistRaw) {
+          await writeFile(project.infoPlistPath, replaced, 'utf-8');
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

package/scripts/utils/mobile/ios_xcodeproj_patch.test.mjs

@@ -0,0 +1,131 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { patchIosXcodeProjectsForSigningAndIdentity } from './ios_xcodeproj_patch.mjs';
+
+async function withTempUiDir(t) {
+  const uiDir = await mkdtemp(join(tmpdir(), 'hstack-mobile-'));
+  t.after(async () => {
+    await rm(uiDir, { recursive: true, force: true });
+  });
+  return uiDir;
+}
+
+test('patchIosXcodeProjectsForSigningAndIdentity patches legacy ios/Happy.xcodeproj + ios/Happy/Info.plist', async (t) => {
+  const uiDir = await withTempUiDir(t);
+  const iosDir = join(uiDir, 'ios');
+  await mkdir(join(iosDir, 'Happy.xcodeproj'), { recursive: true });
+  await mkdir(join(iosDir, 'Happy'), { recursive: true });
+
+  const pbxprojPath = join(iosDir, 'Happy.xcodeproj', 'project.pbxproj');
+  await writeFile(
+    pbxprojPath,
+    [
+      'ProvisioningStyle = Automatic;',
+      'DEVELOPMENT_TEAM = 3RSYVV66F6;',
+      'CODE_SIGN_IDENTITY = "Apple Development";',
+      '"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";',
+      'PROVISIONING_PROFILE_SPECIFIER = some-profile;',
+      'PRODUCT_BUNDLE_IDENTIFIER = dev.happier.app;',
+      'PRODUCT_NAME = Happy;',
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const infoPlistPath = join(iosDir, 'Happy', 'Info.plist');
+  await writeFile(
+    infoPlistPath,
+    [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<plist version="1.0"><dict>',
+      '<key>CFBundleDisplayName</key><string>Happy</string>',
+      '</dict></plist>',
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  await patchIosXcodeProjectsForSigningAndIdentity({
+    uiDir,
+    iosBundleId: 'dev.happier.stack.stack.user.pre-pr272',
+    iosAppName: 'HAPPY LEGACY',
+  });
+
+  const pbxproj = await readFile(pbxprojPath, 'utf-8');
+  assert.match(pbxproj, /PRODUCT_BUNDLE_IDENTIFIER = dev\.happier\.stack\.stack\.user\.pre-pr272;/);
+  assert.doesNotMatch(pbxproj, /DEVELOPMENT_TEAM\s*=/);
+  assert.doesNotMatch(pbxproj, /PROVISIONING_PROFILE_SPECIFIER\s*=/);
+  assert.doesNotMatch(pbxproj, /CODE_SIGN_IDENTITY\s*=/);
+  assert.match(pbxproj, /PRODUCT_NAME = HAPPY-LEGACY;/);
+
+  const plist = await readFile(infoPlistPath, 'utf-8');
+  assert.match(plist, /<key>CFBundleDisplayName<\/key><string>HAPPY LEGACY<\/string>/);
+});
+
+test('patchIosXcodeProjectsForSigningAndIdentity patches both Happydev + Happy projects when present', async (t) => {
+  const uiDir = await withTempUiDir(t);
+  const iosDir = join(uiDir, 'ios');
+
+  await mkdir(join(iosDir, 'Happy.xcodeproj'), { recursive: true });
+  await mkdir(join(iosDir, 'Happy'), { recursive: true });
+  await writeFile(join(iosDir, 'Happy.xcodeproj', 'project.pbxproj'), 'PRODUCT_BUNDLE_IDENTIFIER = dev.happier.app;\n', 'utf-8');
+  await writeFile(join(iosDir, 'Happy', 'Info.plist'), '<key>CFBundleDisplayName</key><string>Happy</string>\n', 'utf-8');
+
+  await mkdir(join(iosDir, 'Happydev.xcodeproj'), { recursive: true });
+  await mkdir(join(iosDir, 'Happydev'), { recursive: true });
+  await writeFile(join(iosDir, 'Happydev.xcodeproj', 'project.pbxproj'), 'PRODUCT_BUNDLE_IDENTIFIER = dev.happier.app.dev;\n', 'utf-8');
+  await writeFile(join(iosDir, 'Happydev', 'Info.plist'), '<key>CFBundleDisplayName</key><string>Happy (dev)</string>\n', 'utf-8');
+
+  await patchIosXcodeProjectsForSigningAndIdentity({
+    uiDir,
+    iosBundleId: 'dev.happier.stack.stack.user.pre-pr272',
+    iosAppName: 'HAPPY LEGACY',
+  });
+
+  const pbxprojRelease = await readFile(join(iosDir, 'Happy.xcodeproj', 'project.pbxproj'), 'utf-8');
+  assert.match(pbxprojRelease, /PRODUCT_BUNDLE_IDENTIFIER = dev\.happier\.stack\.stack\.user\.pre-pr272;/);
+
+  const pbxprojDev = await readFile(join(iosDir, 'Happydev.xcodeproj', 'project.pbxproj'), 'utf-8');
+  assert.match(pbxprojDev, /PRODUCT_BUNDLE_IDENTIFIER = dev\.happier\.stack\.stack\.user\.pre-pr272;/);
+});
+
+test('patchIosXcodeProjectsForSigningAndIdentity tolerates missing Info.plist and leaves pre-patched pbxproj unchanged', async (t) => {
+  const uiDir = await withTempUiDir(t);
+  const iosDir = join(uiDir, 'ios');
+  await mkdir(join(iosDir, 'Happy.xcodeproj'), { recursive: true });
+  const pbxprojPath = join(iosDir, 'Happy.xcodeproj', 'project.pbxproj');
+  const prepatched = [
+    'PRODUCT_BUNDLE_IDENTIFIER = dev.happier.stack.already.patched;',
+    'PRODUCT_NAME = HAPPY-LEGACY;',
+    '',
+  ].join('\n');
+  await writeFile(pbxprojPath, prepatched, 'utf-8');
+
+  await patchIosXcodeProjectsForSigningAndIdentity({
+    uiDir,
+    iosBundleId: 'dev.happier.stack.already.patched',
+    iosAppName: 'HAPPY LEGACY',
+  });
+
+  const next = await readFile(pbxprojPath, 'utf-8');
+  assert.equal(next, prepatched);
+});
+
+test('patchIosXcodeProjectsForSigningAndIdentity is a no-op when no Happy*.xcodeproj exists', async (t) => {
+  const uiDir = await withTempUiDir(t);
+  await mkdir(join(uiDir, 'ios', 'Other.xcodeproj'), { recursive: true });
+  await writeFile(join(uiDir, 'ios', 'Other.xcodeproj', 'project.pbxproj'), 'PRODUCT_BUNDLE_IDENTIFIER = keep.me;\n', 'utf-8');
+
+  await patchIosXcodeProjectsForSigningAndIdentity({
+    uiDir,
+    iosBundleId: 'dev.happier.stack.noop',
+    iosAppName: 'NOOP',
+  });
+
+  const next = await readFile(join(uiDir, 'ios', 'Other.xcodeproj', 'project.pbxproj'), 'utf-8');
+  assert.equal(next, 'PRODUCT_BUNDLE_IDENTIFIER = keep.me;\n');
+});

package/scripts/utils/net/bind_mode.mjs

@@ -0,0 +1,39 @@
+export function normalizeBindMode(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (v === 'loopback' || v === 'lan') return v;
+  return null;
+}
+
+export function resolveBindModeFromArgs({ flags, kv }) {
+  if (flags?.has?.('--loopback')) return 'loopback';
+  if (flags?.has?.('--lan')) return 'lan';
+  const raw = kv?.get?.('--bind');
+  return normalizeBindMode(raw);
+}
+
+/**
+ * Apply a bind mode override to an env object.
+ *
+ * Semantics:
+ * - loopback: prefer localhost-only origins/advertising (best for port-forwarded / isolated environments)
+ * - lan: prefer LAN origins/advertising (best for phones on the same network)
+ *
+ * This currently controls Expo's `--host` via HAPPIER_STACK_EXPO_HOST.
+ * Other services may optionally honor HOST=127.0.0.1 when loopback is selected.
+ */
+export function applyBindModeToEnv(env, mode) {
+  const m = normalizeBindMode(mode);
+  if (!m) return env;
+
+  env.HAPPIER_STACK_BIND_MODE = m;
+
+  if (m === 'loopback') {
+    env.HAPPIER_STACK_EXPO_HOST = 'localhost';
+    // Best-effort: some servers honor HOST.
+    env.HOST = '127.0.0.1';
+  } else if (m === 'lan') {
+    env.HAPPIER_STACK_EXPO_HOST = 'lan';
+  }
+
+  return env;
+}

package/scripts/utils/net/dns.mjs

@@ -0,0 +1,10 @@
+export function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
+  const s = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return s || fallback;
+}
+

package/scripts/utils/net/lan_ip.mjs

@@ -0,0 +1,24 @@
+import { networkInterfaces } from 'node:os';
+
+export function pickLanIpv4() {
+  try {
+    const ifaces = networkInterfaces();
+    // Prefer en0 (typical Wi-Fi on macOS), then any non-internal IPv4.
+    const preferred = ['en0', 'en1', 'eth0', 'wlan0'];
+    for (const name of preferred) {
+      const list = ifaces[name] ?? [];
+      for (const i of list) {
+        if (i && i.family === 'IPv4' && !i.internal && i.address) return i.address;
+      }
+    }
+    for (const list of Object.values(ifaces)) {
+      for (const i of list ?? []) {
+        if (i && i.family === 'IPv4' && !i.internal && i.address) return i.address;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return '';
+}
+