happy-stacks 0.3.0 → 0.5.0

package/scripts/utils/review/slices.mjs

@@ -0,0 +1,140 @@
+function normalizePath(p) {
+  return String(p ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function commonPrefixParts(partsList) {
+  if (!partsList.length) return [];
+  const first = partsList[0];
+  let n = first.length;
+  for (const parts of partsList.slice(1)) {
+    n = Math.min(n, parts.length, n);
+    for (let i = 0; i < n; i += 1) {
+      if (parts[i] !== first[i]) {
+        n = i;
+        break;
+      }
+    }
+  }
+  return first.slice(0, n);
+}
+
+function pathPrefixLabel(parts, { maxDepth = 4 } = {}) {
+  const depth = Math.min(parts.length, Math.max(1, maxDepth));
+  return parts.slice(0, depth).join('/');
+}
+
+function groupByPrefix(paths, depth) {
+  const groups = new Map();
+  for (const p of paths) {
+    const parts = normalizePath(p).split('/').filter(Boolean);
+    const key = parts.slice(0, Math.max(1, Math.min(depth, parts.length))).join('/');
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(p);
+  }
+  return groups;
+}
+
+/**
+ * Plan review slices that:
+ * - cover every changed path exactly once
+ * - keep each slice at <= maxFiles where possible
+ * - prefer directory-prefix grouping (better reviewer context) over raw batching
+ *
+ * The output is intended for "HEAD-sliced" review: the reviewer gets a focused diff
+ * while still having access to the full repo code at HEAD.
+ */
+export function planPathSlices({ changedPaths, maxFiles = 300, maxPrefixDepth = 6 } = {}) {
+  const unique = Array.from(new Set((Array.isArray(changedPaths) ? changedPaths : []).map(normalizePath))).filter(Boolean);
+  unique.sort();
+  if (!unique.length) return [];
+
+  const limit = Number.isFinite(maxFiles) && maxFiles > 0 ? Math.floor(maxFiles) : 300;
+  if (unique.length <= limit) {
+    const parts = unique.map((p) => p.split('/').filter(Boolean));
+    const prefix = commonPrefixParts(parts);
+    return [
+      {
+        label: prefix.length ? `${pathPrefixLabel(prefix, { maxDepth: 3 })}/` : 'repo/',
+        paths: unique,
+      },
+    ];
+  }
+
+  // First pass: top-level directories (plus root files).
+  const topGroups = groupByPrefix(unique, 1);
+
+  const slices = [];
+  const pushSlice = (label, paths) => {
+    const normalized = Array.from(new Set(paths.map(normalizePath))).filter(Boolean).sort();
+    if (!normalized.length) return;
+    slices.push({ label, paths: normalized });
+  };
+
+  for (const [top, paths] of topGroups.entries()) {
+    if (paths.length <= limit) {
+      pushSlice(top.includes('/') ? top : `${top}/`, paths);
+      continue;
+    }
+
+    // Iteratively refine prefix depth within this group until all chunks are <= limit.
+    let pending = [{ label: top, paths }];
+    for (let depth = 2; depth <= maxPrefixDepth && pending.some((x) => x.paths.length > limit); depth += 1) {
+      const next = [];
+      for (const item of pending) {
+        if (item.paths.length <= limit) {
+          next.push(item);
+          continue;
+        }
+        const groups = groupByPrefix(item.paths, depth);
+        if (groups.size <= 1) {
+          next.push(item);
+          continue;
+        }
+        for (const [k, v] of groups.entries()) {
+          next.push({ label: k, paths: v });
+        }
+      }
+      pending = next;
+    }
+
+    // Final pass: pack refined groups into <=limit windows (greedy, stable order).
+    pending.sort((a, b) => a.label.localeCompare(b.label));
+    let bucket = [];
+    let bucketCount = 0;
+    let bucketLabelParts = [];
+    const flush = () => {
+      if (!bucket.length) return;
+      const parts = commonPrefixParts(bucketLabelParts);
+      const label = parts.length ? `${pathPrefixLabel(parts, { maxDepth: 4 })}/` : `${top}/`;
+      pushSlice(label, bucket);
+      bucket = [];
+      bucketCount = 0;
+      bucketLabelParts = [];
+    };
+
+    for (const g of pending) {
+      const n = g.paths.length;
+      if (n > limit) {
+        // Fall back to raw batching for truly massive groups (rare).
+        flush();
+        for (let i = 0; i < g.paths.length; i += limit) {
+          const batch = g.paths.slice(i, i + limit);
+          pushSlice(`${g.label}/`, batch);
+        }
+        continue;
+      }
+      if (bucketCount + n > limit) {
+        flush();
+      }
+      bucket.push(...g.paths);
+      bucketCount += n;
+      bucketLabelParts.push(g.label.split('/').filter(Boolean));
+    }
+    flush();
+  }
+
+  // Stable ordering helps humans follow progress.
+  slices.sort((a, b) => a.label.localeCompare(b.label));
+  return slices;
+}
+

package/scripts/utils/review/slices.test.mjs

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { planPathSlices } from './slices.mjs';
+
+test('planPathSlices returns empty for no paths', () => {
+  assert.deepEqual(planPathSlices({ changedPaths: [], maxFiles: 3 }), []);
+});
+
+test('planPathSlices creates a single slice when under maxFiles', () => {
+  const slices = planPathSlices({
+    changedPaths: ['expo-app/a.txt', 'cli/b.txt', 'server/c.txt'],
+    maxFiles: 10,
+  });
+  assert.equal(slices.length, 1);
+  assert.deepEqual(slices[0].paths, ['cli/b.txt', 'expo-app/a.txt', 'server/c.txt']);
+});
+
+test('planPathSlices splits large groups by prefix depth and respects maxFiles', () => {
+  const changedPaths = [
+    ...Array.from({ length: 6 }, (_, i) => `expo-app/sources/a${i}.ts`),
+    ...Array.from({ length: 6 }, (_, i) => `expo-app/sources/b${i}.ts`),
+    ...Array.from({ length: 2 }, (_, i) => `cli/src/x${i}.ts`),
+  ];
+  const slices = planPathSlices({ changedPaths, maxFiles: 5, maxPrefixDepth: 4 });
+  assert.ok(slices.length > 1);
+  for (const s of slices) {
+    assert.ok(s.paths.length <= 5, `slice ${s.label} exceeded maxFiles`);
+  }
+  const all = slices.flatMap((s) => s.paths).sort();
+  assert.deepEqual(all, Array.from(new Set(changedPaths)).sort());
+});
+

package/scripts/utils/review/targets.mjs

@@ -0,0 +1,24 @@
+import { getComponentsDir, getComponentDir } from '../paths/paths.mjs';
+import { join } from 'node:path';
+
+export function isStackMode(env = process.env) {
+  const stack = String(env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').trim();
+  const envFile = String(env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').trim();
+  return Boolean(stack && envFile);
+}
+
+export function defaultComponentCheckoutDir(rootDir, component) {
+  return join(getComponentsDir(rootDir), component);
+}
+
+export function resolveDefaultStackReviewComponents({ rootDir, components }) {
+  const list = Array.isArray(components) ? components : [];
+  const out = [];
+  for (const c of list) {
+    const effective = getComponentDir(rootDir, c);
+    const def = defaultComponentCheckoutDir(rootDir, c);
+    if (effective !== def) out.push(c);
+  }
+  return out;
+}
+

package/scripts/utils/review/targets.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveDefaultStackReviewComponents } from './targets.mjs';
+
+test('resolveDefaultStackReviewComponents returns only non-default pinned components', () => {
+  const rootDir = '/tmp/hs-root';
+  const keys = [
+    'HAPPY_STACKS_WORKSPACE_DIR',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI',
+    'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER',
+  ];
+  const old = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+  try {
+    process.env.HAPPY_STACKS_WORKSPACE_DIR = '/tmp/hs-root';
+    // Default checkouts
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY = '';
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = '';
+    // Pinned overrides
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = '/tmp/custom/happy-cli';
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = '/tmp/custom/happy-server';
+
+    const comps = resolveDefaultStackReviewComponents({
+      rootDir,
+      components: ['happy', 'happy-cli', 'happy-server-light', 'happy-server'],
+    });
+    assert.deepEqual(comps.sort(), ['happy-cli', 'happy-server'].sort());
+  } finally {
+    for (const k of keys) {
+      if (old[k] == null) delete process.env[k];
+      else process.env[k] = old[k];
+    }
+  }
+});
+

package/scripts/utils/sandbox/review_pr_sandbox.mjs

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+
+export const REVIEW_PR_MARKER_FILENAME = '.happy-stacks-sandbox-marker';
+export const REVIEW_PR_META_FILENAME = '.happy-stacks-review-pr.json';
+
+export function reviewPrSandboxPrefixBase(baseStackName) {
+  const base = String(baseStackName ?? '').trim() || 'pr';
+  // Keep prefix stable for listing/reuse; mkdtemp adds a random suffix.
+  return `happy-stacks-review-pr-${base}-`;
+}
+
+export function reviewPrSandboxPrefixPath(baseStackName) {
+  return join(tmpdir(), reviewPrSandboxPrefixBase(baseStackName));
+}
+
+async function readJsonBestEffort(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function listReviewPrSandboxes({ baseStackName }) {
+  const prefixBase = reviewPrSandboxPrefixBase(baseStackName);
+  const root = tmpdir();
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!e.name.startsWith(prefixBase)) continue;
+    const dir = resolve(join(root, e.name));
+    const markerPath = join(dir, REVIEW_PR_MARKER_FILENAME);
+    if (!existsSync(markerPath)) continue;
+
+    let markerOk = false;
+    try {
+      const marker = await readFile(markerPath, 'utf-8');
+      markerOk = marker.trim().startsWith('review-pr');
+    } catch {
+      markerOk = false;
+    }
+    if (!markerOk) continue;
+
+    const metaPath = join(dir, REVIEW_PR_META_FILENAME);
+    const meta = await readJsonBestEffort(metaPath);
+
+    let mtimeMs = 0;
+    try {
+      mtimeMs = (await stat(dir)).mtimeMs;
+    } catch {
+      mtimeMs = 0;
+    }
+
+    out.push({
+      dir,
+      name: basename(dir),
+      markerPath,
+      metaPath,
+      baseStackName: String(meta?.baseStackName ?? '').trim() || String(baseStackName ?? '').trim() || null,
+      stackName: String(meta?.stackName ?? '').trim() || null,
+      createdAtMs: typeof meta?.createdAtMs === 'number' ? meta.createdAtMs : null,
+      lastTouchedAtMs: Number.isFinite(mtimeMs) ? mtimeMs : null,
+    });
+  }
+
+  out.sort((a, b) => (b.lastTouchedAtMs ?? 0) - (a.lastTouchedAtMs ?? 0));
+  return out;
+}
+
+export async function writeReviewPrSandboxMeta({ sandboxDir, baseStackName, stackName, argv }) {
+  const dir = resolve(String(sandboxDir ?? '').trim());
+  const markerPath = join(dir, REVIEW_PR_MARKER_FILENAME);
+  const metaPath = join(dir, REVIEW_PR_META_FILENAME);
+
+  // Marker (for safe deletion) + meta (for reuse menu).
+  await writeFile(markerPath, 'review-pr\n', 'utf-8');
+  await writeFile(
+    metaPath,
+    JSON.stringify(
+      {
+        kind: 'review-pr',
+        createdAtMs: Date.now(),
+        baseStackName: String(baseStackName ?? '').trim() || null,
+        stackName: String(stackName ?? '').trim() || null,
+        argv: Array.isArray(argv) ? argv : null,
+      },
+      null,
+      2
+    ) + '\n',
+    'utf-8'
+  );
+
+  return { markerPath, metaPath };
+}
+

package/scripts/utils/server/flavor_scripts.mjs

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+function readScripts(serverDir) {
+  try {
+    const pkgPath = join(serverDir, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    return scripts;
+  } catch {
+    return {};
+  }
+}
+
+function hasScript(scripts, name) {
+  return typeof scripts?.[name] === 'string' && scripts[name].trim().length > 0;
+}
+
+export function isUnifiedHappyServerLight({ serverDir }) {
+  return (
+    existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma')) ||
+    existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma'))
+  );
+}
+
+export function resolveServerLightPrismaSchemaArgs({ serverDir }) {
+  if (existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))) {
+    return ['--schema', 'prisma/sqlite/schema.prisma'];
+  }
+  if (existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma'))) {
+    return ['--schema', 'prisma/schema.sqlite.prisma'];
+  }
+  return [];
+}
+
+export function resolveServerLightPrismaMigrateDeployArgs({ serverDir }) {
+  return ['migrate', 'deploy', ...resolveServerLightPrismaSchemaArgs({ serverDir })];
+}
+
+export function resolveServerLightPrismaClientImport({ serverDir }) {
+  if (!isUnifiedHappyServerLight({ serverDir })) {
+    return '@prisma/client';
+  }
+  const clientPath = join(serverDir, 'generated', 'sqlite-client', 'index.js');
+  return pathToFileURL(clientPath).href;
+}
+
+export function resolvePrismaClientImportForServerComponent({ serverComponentName, serverComponent, serverDir }) {
+  const name = serverComponentName ?? serverComponent;
+  if (name === 'happy-server-light') {
+    return resolveServerLightPrismaClientImport({ serverDir });
+  }
+  return '@prisma/client';
+}
+
+export function resolveServerDevScript({ serverComponentName, serverDir, prismaPush }) {
+  const scripts = readScripts(serverDir);
+
+  if (serverComponentName === 'happy-server') {
+    return 'start';
+  }
+
+  if (serverComponentName === 'happy-server-light') {
+    const unified = isUnifiedHappyServerLight({ serverDir });
+    if (unified) {
+      // Server-light now relies on deterministic migrations (not db push).
+      // Prefer the dedicated dev script that runs migrate deploy before starting.
+      if (hasScript(scripts, 'dev:light')) {
+        return 'dev:light';
+      }
+      // Fallback: no dev script, run the light start script.
+      return hasScript(scripts, 'start:light') ? 'start:light' : 'start';
+    }
+
+    // Legacy behavior: prefer `dev` for older happy-server-light checkouts.
+    if (prismaPush) {
+      return hasScript(scripts, 'dev') ? 'dev' : 'start';
+    }
+    return hasScript(scripts, 'start') ? 'start' : 'dev';
+  }
+
+  // Unknown: be conservative.
+  return 'start';
+}
+
+export function resolveServerStartScript({ serverComponentName, serverDir }) {
+  const scripts = readScripts(serverDir);
+
+  if (serverComponentName === 'happy-server-light') {
+    const unified = isUnifiedHappyServerLight({ serverDir });
+    if (unified && hasScript(scripts, 'start:light')) {
+      return 'start:light';
+    }
+  }
+
+  return 'start';
+}

package/scripts/utils/server/flavor_scripts.test.mjs

@@ -0,0 +1,146 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  resolvePrismaClientImportForServerComponent,
+  resolveServerDevScript,
+  resolveServerLightPrismaClientImport,
+  resolveServerLightPrismaMigrateDeployArgs,
+  resolveServerStartScript,
+} from './flavor_scripts.mjs';
+
+async function writeJson(path, obj) {
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+test('resolveServer*Script uses light scripts when unified light flavor is detected', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+    await writeJson(join(dir, 'package.json'), { scripts: { 'start:light': 'node x', 'dev:light': 'node y' } });
+
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server-light', serverDir: dir, prismaPush: true }), 'dev:light');
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server-light', serverDir: dir, prismaPush: false }), 'dev:light');
+    assert.equal(resolveServerStartScript({ serverComponentName: 'happy-server-light', serverDir: dir }), 'start:light');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServer*Script falls back to legacy scripts for non-unified happy-server-light', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await writeJson(join(dir, 'package.json'), { scripts: { start: 'node start', dev: 'node dev' } });
+
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server-light', serverDir: dir, prismaPush: true }), 'dev');
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server-light', serverDir: dir, prismaPush: false }), 'start');
+    assert.equal(resolveServerStartScript({ serverComponentName: 'happy-server-light', serverDir: dir }), 'start');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServer*Script returns start for happy-server', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await writeJson(join(dir, 'package.json'), { scripts: { start: 'node start', dev: 'node dev' } });
+
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server', serverDir: dir, prismaPush: true }), 'start');
+    assert.equal(resolveServerDevScript({ serverComponentName: 'happy-server', serverDir: dir, prismaPush: false }), 'start');
+    assert.equal(resolveServerStartScript({ serverComponentName: 'happy-server', serverDir: dir }), 'start');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerLightPrismaMigrateDeployArgs adds --schema when unified light flavor is detected', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    assert.deepEqual(resolveServerLightPrismaMigrateDeployArgs({ serverDir: dir }), ['migrate', 'deploy', '--schema', 'prisma/sqlite/schema.prisma']);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerLightPrismaMigrateDeployArgs supports legacy schema.sqlite.prisma', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'schema.sqlite.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    assert.deepEqual(resolveServerLightPrismaMigrateDeployArgs({ serverDir: dir }), ['migrate', 'deploy', '--schema', 'prisma/schema.sqlite.prisma']);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerLightPrismaClientImport returns file URL when unified light flavor is detected', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    const spec = resolveServerLightPrismaClientImport({ serverDir: dir });
+    assert.equal(typeof spec, 'string');
+    assert.ok(spec.startsWith('file:'), `expected file: URL import spec, got: ${spec}`);
+    assert.ok(spec.endsWith('/generated/sqlite-client/index.js'), `unexpected import spec: ${spec}`);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerLightPrismaClientImport returns @prisma/client for legacy happy-server-light', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    assert.equal(resolveServerLightPrismaClientImport({ serverDir: dir }), '@prisma/client');
+    assert.deepEqual(resolveServerLightPrismaMigrateDeployArgs({ serverDir: dir }), ['migrate', 'deploy']);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolvePrismaClientImportForServerComponent returns sqlite client file URL for unified server-light', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    const spec = resolvePrismaClientImportForServerComponent({ serverComponentName: 'happy-server-light', serverDir: dir });
+    assert.equal(typeof spec, 'string');
+    assert.ok(spec.startsWith('file:'), `expected file: URL import spec, got: ${spec}`);
+    assert.ok(spec.endsWith('/generated/sqlite-client/index.js'), `unexpected import spec: ${spec}`);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolvePrismaClientImportForServerComponent accepts serverComponent alias (back-compat)', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    const spec = resolvePrismaClientImportForServerComponent({ serverComponent: 'happy-server-light', serverDir: dir });
+    assert.equal(typeof spec, 'string');
+    assert.ok(spec.startsWith('file:'), `expected file: URL import spec, got: ${spec}`);
+    assert.ok(spec.endsWith('/generated/sqlite-client/index.js'), `unexpected import spec: ${spec}`);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolvePrismaClientImportForServerComponent returns @prisma/client for happy-server', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-flavor-scripts-'));
+  try {
+    assert.equal(resolvePrismaClientImportForServerComponent({ serverComponentName: 'happy-server', serverDir: dir }), '@prisma/client');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/scripts/utils/server/mobile_api_url.mjs

@@ -0,0 +1,61 @@
+import { pickLanIpv4 } from '../net/lan_ip.mjs';
+import { normalizeUrlNoTrailingSlash } from '../net/url.mjs';
+
+function resolveLanIp({ env = process.env } = {}) {
+  const raw = (env.HAPPY_STACKS_LAN_IP ?? env.HAPPY_LOCAL_LAN_IP ?? '').toString().trim();
+  return raw || pickLanIpv4() || '';
+}
+
+function isLocalHostName(hostname) {
+  const h = String(hostname ?? '').trim().toLowerCase();
+  if (!h) return false;
+  if (h === 'localhost' || h === '127.0.0.1' || h === '0.0.0.0') return true;
+  if (h.endsWith('.localhost')) return true;
+  return false;
+}
+
+/**
+ * For mobile devices, `localhost` and `*.localhost` are not reachable.
+ *
+ * This helper rewrites any local server URL to a LAN-reachable URL using the machine's LAN IPv4.
+ * It preserves protocol, port, and path/query.
+ *
+ * Notes:
+ * - If the URL is already non-local (e.g. Tailscale HTTPS), it is returned unchanged.
+ * - If LAN IP cannot be determined, it returns the original URL unchanged.
+ */
+export function resolveMobileReachableServerUrl({
+  env = process.env,
+  serverUrl,
+  serverPort,
+} = {}) {
+  const raw = String(serverUrl ?? '').trim();
+  const fallbackPort = Number(serverPort);
+  const fallback = Number.isFinite(fallbackPort) && fallbackPort > 0 ? `http://localhost:${fallbackPort}` : '';
+  const base = raw || fallback;
+  if (!base) return '';
+
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return base;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return base;
+  }
+
+  if (!isLocalHostName(parsed.hostname)) {
+    return normalizeUrlNoTrailingSlash(parsed.toString());
+  }
+
+  const lanIp = resolveLanIp({ env });
+  if (!lanIp) {
+    return normalizeUrlNoTrailingSlash(parsed.toString());
+  }
+
+  parsed.hostname = lanIp;
+  return normalizeUrlNoTrailingSlash(parsed.toString());
+}
+