@happier-dev/stack 0.1.0-preview.96.1 → 0.2.0-preview.1775370152.55749

package/scripts/build/runtime_retention.mjs

@@ -0,0 +1,170 @@
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readArtifactManifest, validateArtifactManifest } from '../runtime/shared/artifact_manifest.mjs';
+import { readRuntimeManifest, readRuntimePointer, validateRuntimeManifest } from '../runtime/shared/runtime_manifest.mjs';
+import { resolveStackArtifactsDir, resolveStackRuntimePaths } from '../runtime/shared/runtime_paths.mjs';
+
+const DEFAULT_RETENTION_COUNT = 2;
+
+function resolveKeepCount(rawValue, defaultValue) {
+  const raw = String(rawValue ?? '').trim();
+  if (!raw) return defaultValue;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return defaultValue;
+  return Math.max(1, Math.floor(parsed));
+}
+
+function sortNewestFirst(a, b) {
+  if (a.createdAt !== b.createdAt) {
+    return a.createdAt < b.createdAt ? 1 : -1;
+  }
+  return a.id < b.id ? 1 : -1;
+}
+
+function normalizeReferencedSnapshotIds(manifest) {
+  if (!Array.isArray(manifest?.reusedSnapshotIds)) return [];
+  return [...new Set(
+    manifest.reusedSnapshotIds
+      .map((value) => String(value ?? '').trim())
+      .filter(Boolean),
+  )];
+}
+
+function preserveSnapshotWithReferences(snapshotId, snapshotById, keep, seen = new Set()) {
+  const normalizedSnapshotId = String(snapshotId ?? '').trim();
+  if (!normalizedSnapshotId || seen.has(normalizedSnapshotId)) return;
+  seen.add(normalizedSnapshotId);
+  keep.add(normalizedSnapshotId);
+  const snapshot = snapshotById.get(normalizedSnapshotId);
+  for (const referencedSnapshotId of snapshot?.referencedSnapshotIds ?? []) {
+    preserveSnapshotWithReferences(referencedSnapshotId, snapshotById, keep, seen);
+  }
+}
+
+async function listChildDirectories(parentDir) {
+  try {
+    const entries = await readdir(parentDir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function resolveCreatedAtOrMtime(targetPath, rawCreatedAt) {
+  const createdAt = String(rawCreatedAt ?? '').trim();
+  if (createdAt) return createdAt;
+  const entryStat = await stat(targetPath);
+  return entryStat.mtime.toISOString();
+}
+
+export function resolveRuntimeRetentionPolicy({ env = process.env } = {}) {
+  return {
+    runtimeSnapshotKeepCount: resolveKeepCount(env.HAPPIER_STACK_RUNTIME_SNAPSHOT_KEEP_COUNT, DEFAULT_RETENTION_COUNT),
+    artifactKeepCount: resolveKeepCount(env.HAPPIER_STACK_RUNTIME_ARTIFACT_KEEP_COUNT, DEFAULT_RETENTION_COUNT),
+  };
+}
+
+export async function pruneRuntimeSnapshots({
+  stackBaseDir,
+  keepCount,
+  preserveSnapshotIds = [],
+}) {
+  const runtimePaths = resolveStackRuntimePaths({ stackBaseDir });
+  const snapshotIds = await listChildDirectories(runtimePaths.buildsDir);
+  const keep = new Set((preserveSnapshotIds ?? []).map((value) => String(value ?? '').trim()).filter(Boolean));
+  const activePointer = await readRuntimePointer({ currentPath: runtimePaths.currentPath });
+  const activeSnapshotId = String(activePointer?.snapshotId ?? '').trim();
+  const validSnapshots = [];
+  const removedEntries = [];
+
+  for (const snapshotId of snapshotIds) {
+    const snapshotDir = join(runtimePaths.buildsDir, snapshotId);
+    const manifest = await readRuntimeManifest({ manifestPath: join(snapshotDir, 'manifest.json') });
+    const validation = validateRuntimeManifest(manifest);
+    if (!validation.ok) {
+      await rm(snapshotDir, { recursive: true, force: true });
+      removedEntries.push(snapshotId);
+      continue;
+    }
+    validSnapshots.push({
+      id: snapshotId,
+      dir: snapshotDir,
+      createdAt: await resolveCreatedAtOrMtime(snapshotDir, manifest?.createdAt),
+      referencedSnapshotIds: normalizeReferencedSnapshotIds(manifest),
+    });
+  }
+
+  const snapshotById = new Map(validSnapshots.map((snapshot) => [snapshot.id, snapshot]));
+  for (const snapshotId of [...keep]) {
+    preserveSnapshotWithReferences(snapshotId, snapshotById, keep);
+  }
+  if (activeSnapshotId) {
+    preserveSnapshotWithReferences(activeSnapshotId, snapshotById, keep);
+  }
+
+  validSnapshots.sort(sortNewestFirst);
+  const desiredKeepCount = Math.max(1, keepCount);
+  for (const snapshot of validSnapshots) {
+    if (keep.size >= desiredKeepCount) break;
+    preserveSnapshotWithReferences(snapshot.id, snapshotById, keep);
+  }
+
+  for (const snapshot of validSnapshots) {
+    if (keep.has(snapshot.id)) continue;
+    await rm(snapshot.dir, { recursive: true, force: true });
+    removedEntries.push(snapshot.id);
+  }
+
+  return {
+    keptSnapshotIds: validSnapshots.filter((snapshot) => keep.has(snapshot.id)).map((snapshot) => snapshot.id),
+    removedEntries,
+  };
+}
+
+export async function pruneComponentArtifacts({
+  stackBaseDir,
+  component,
+  keepCount,
+}) {
+  const componentDir = join(resolveStackArtifactsDir({ stackBaseDir }), String(component ?? '').trim());
+  const artifactIds = await listChildDirectories(componentDir);
+  const keep = new Set();
+  const validArtifacts = [];
+  const removedEntries = [];
+
+  for (const artifactId of artifactIds) {
+    const artifactDir = join(componentDir, artifactId);
+    const manifest = await readArtifactManifest({ artifactDir });
+    const validation = validateArtifactManifest(manifest);
+    if (!validation.ok) {
+      await rm(artifactDir, { recursive: true, force: true });
+      removedEntries.push(artifactId);
+      continue;
+    }
+    validArtifacts.push({
+      id: artifactId,
+      dir: artifactDir,
+      createdAt: await resolveCreatedAtOrMtime(artifactDir, manifest?.createdAt),
+    });
+  }
+
+  validArtifacts.sort(sortNewestFirst);
+  for (const artifact of validArtifacts.slice(0, Math.max(1, keepCount))) {
+    keep.add(artifact.id);
+  }
+
+  for (const artifact of validArtifacts) {
+    if (keep.has(artifact.id)) continue;
+    await rm(artifact.dir, { recursive: true, force: true });
+    removedEntries.push(artifact.id);
+  }
+
+  return {
+    keptFingerprints: validArtifacts.filter((artifact) => keep.has(artifact.id)).map((artifact) => artifact.id),
+    removedEntries,
+  };
+}

package/scripts/build/runtime_retention.test.mjs

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { writeArtifactManifest } from '../runtime/shared/artifact_manifest.mjs';
+import { writeRuntimeManifest, writeRuntimePointer } from '../runtime/shared/runtime_manifest.mjs';
+import { pruneComponentArtifacts, pruneRuntimeSnapshots, resolveRuntimeRetentionPolicy } from './runtime_retention.mjs';
+
+async function writeRuntimeSnapshot(stackBaseDir, snapshotId, createdAt) {
+  const snapshotDir = join(stackBaseDir, 'runtime', 'builds', snapshotId);
+  await mkdir(join(snapshotDir, 'ui'), { recursive: true });
+  await mkdir(join(snapshotDir, 'server'), { recursive: true });
+  await mkdir(join(snapshotDir, 'cli'), { recursive: true });
+  await writeFile(join(snapshotDir, 'ui', 'index.html'), `<html>${snapshotId}</html>`);
+  await writeFile(join(snapshotDir, 'server', 'happier-server'), `server ${snapshotId}\n`);
+  await writeFile(join(snapshotDir, 'cli', 'happier'), `daemon ${snapshotId}\n`);
+  await writeRuntimeManifest({
+    manifestPath: join(snapshotDir, 'manifest.json'),
+    manifest: {
+      version: 1,
+      snapshotId,
+      sourceFingerprint: `source-${snapshotId}`,
+      createdAt,
+      components: {
+        web: { artifactFingerprint: `web-${snapshotId}`, entrypoint: 'ui/index.html' },
+        server: { artifactFingerprint: `server-${snapshotId}`, entrypoint: 'server/happier-server' },
+        daemon: { artifactFingerprint: `daemon-${snapshotId}`, entrypoint: 'cli/happier' },
+      },
+    },
+  });
+  return snapshotDir;
+}
+
+async function writeArtifact(stackBaseDir, component, fingerprint, createdAt) {
+  const artifactDir = join(stackBaseDir, 'artifacts', component, fingerprint);
+  const payloadDir = join(artifactDir, 'payload');
+  await mkdir(payloadDir, { recursive: true });
+  const entrypoint =
+    component === 'web'
+      ? 'index.html'
+      : component === 'server'
+        ? 'happier-server'
+        : 'happier';
+  await writeFile(join(payloadDir, entrypoint), `${component}:${fingerprint}\n`);
+  await writeArtifactManifest({
+    artifactDir,
+    manifest: {
+      version: 1,
+      component,
+      artifactFingerprint: fingerprint,
+      sourceFingerprint: `source-${fingerprint}`,
+      createdAt,
+      payloadDir: 'payload',
+      entrypoint,
+    },
+  });
+  return artifactDir;
+}
+
+test('resolveRuntimeRetentionPolicy defaults to keeping current plus previous runtime and artifacts', () => {
+  assert.deepEqual(resolveRuntimeRetentionPolicy({ env: {} }), {
+    runtimeSnapshotKeepCount: 2,
+    artifactKeepCount: 2,
+  });
+});
+
+test('pruneRuntimeSnapshots keeps the active snapshot plus the newest previous snapshot and removes invalid directories', async () => {
+  const stackBaseDir = await mkdtemp(join(tmpdir(), 'runtime-retention-runtime-'));
+
+  try {
+    const oldest = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-1', '2026-03-07T10:00:00.000Z');
+    const previous = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-2', '2026-03-07T11:00:00.000Z');
+    const current = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-3', '2026-03-07T12:00:00.000Z');
+    const invalid = join(stackBaseDir, 'runtime', 'builds', 'snapshot-broken');
+    await mkdir(invalid, { recursive: true });
+    await writeFile(join(invalid, 'README.txt'), 'broken\n');
+    await writeRuntimePointer({
+      currentPath: join(stackBaseDir, 'runtime', 'current.json'),
+      pointer: {
+        version: 1,
+        snapshotId: 'snapshot-3',
+        snapshotPath: current,
+        sourceFingerprint: 'source-snapshot-3',
+        updatedAt: '2026-03-07T12:00:00.000Z',
+      },
+    });
+
+    const result = await pruneRuntimeSnapshots({ stackBaseDir, keepCount: 2, preserveSnapshotIds: ['snapshot-3'] });
+
+    assert.deepEqual(result.keptSnapshotIds.sort(), ['snapshot-2', 'snapshot-3']);
+    assert.deepEqual(result.removedEntries.sort(), ['snapshot-1', 'snapshot-broken']);
+    await assert.rejects(() => readFile(join(oldest, 'manifest.json'), 'utf8'), /ENOENT/);
+    assert.equal(await readFile(join(previous, 'manifest.json'), 'utf8').then(Boolean), true);
+    assert.equal(await readFile(join(current, 'manifest.json'), 'utf8').then(Boolean), true);
+  } finally {
+    await rm(stackBaseDir, { recursive: true, force: true });
+  }
+});
+
+test('pruneRuntimeSnapshots preserves the snapshot referenced by current.json by default', async () => {
+  const stackBaseDir = await mkdtemp(join(tmpdir(), 'runtime-retention-current-pointer-'));
+
+  try {
+    const active = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-active', '2026-03-07T10:00:00.000Z');
+    const newer = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-newer', '2026-03-07T11:00:00.000Z');
+    await writeRuntimePointer({
+      currentPath: join(stackBaseDir, 'runtime', 'current.json'),
+      pointer: {
+        version: 1,
+        snapshotId: 'snapshot-active',
+        snapshotPath: active,
+        sourceFingerprint: 'source-snapshot-active',
+        updatedAt: '2026-03-07T11:30:00.000Z',
+      },
+    });
+
+    const result = await pruneRuntimeSnapshots({ stackBaseDir, keepCount: 1 });
+
+    assert.deepEqual(result.keptSnapshotIds.sort(), ['snapshot-active']);
+    assert.deepEqual(result.removedEntries.sort(), ['snapshot-newer']);
+    assert.equal(await readFile(join(active, 'manifest.json'), 'utf8').then(Boolean), true);
+    await assert.rejects(() => readFile(join(newer, 'manifest.json'), 'utf8'), /ENOENT/);
+  } finally {
+    await rm(stackBaseDir, { recursive: true, force: true });
+  }
+});
+
+test('pruneRuntimeSnapshots preserves transitive snapshot references declared by the active manifest', async () => {
+  const stackBaseDir = await mkdtemp(join(tmpdir(), 'runtime-retention-reused-snapshot-'));
+
+  try {
+    const reused = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-reused', '2026-03-07T10:00:00.000Z');
+    const active = await writeRuntimeSnapshot(stackBaseDir, 'snapshot-active', '2026-03-07T11:00:00.000Z');
+    const activeManifestPath = join(active, 'manifest.json');
+    const activeManifest = JSON.parse(await readFile(activeManifestPath, 'utf8'));
+    activeManifest.reusedSnapshotIds = ['snapshot-reused'];
+    await writeFile(activeManifestPath, JSON.stringify(activeManifest, null, 2) + '\n', 'utf8');
+    await writeRuntimePointer({
+      currentPath: join(stackBaseDir, 'runtime', 'current.json'),
+      pointer: {
+        version: 1,
+        snapshotId: 'snapshot-active',
+        snapshotPath: active,
+        sourceFingerprint: 'source-snapshot-active',
+        updatedAt: '2026-03-07T11:30:00.000Z',
+      },
+    });
+
+    const result = await pruneRuntimeSnapshots({ stackBaseDir, keepCount: 1 });
+
+    assert.deepEqual(result.keptSnapshotIds.sort(), ['snapshot-active', 'snapshot-reused']);
+    assert.deepEqual(result.removedEntries, []);
+    assert.equal(await readFile(join(active, 'manifest.json'), 'utf8').then(Boolean), true);
+    assert.equal(await readFile(join(reused, 'manifest.json'), 'utf8').then(Boolean), true);
+  } finally {
+    await rm(stackBaseDir, { recursive: true, force: true });
+  }
+});
+
+test('pruneComponentArtifacts keeps the newest artifacts for a component and removes invalid directories', async () => {
+  const stackBaseDir = await mkdtemp(join(tmpdir(), 'runtime-retention-artifacts-'));
+
+  try {
+    const oldest = await writeArtifact(stackBaseDir, 'web', 'web-1', '2026-03-07T10:00:00.000Z');
+    const previous = await writeArtifact(stackBaseDir, 'web', 'web-2', '2026-03-07T11:00:00.000Z');
+    const current = await writeArtifact(stackBaseDir, 'web', 'web-3', '2026-03-07T12:00:00.000Z');
+    const invalid = join(stackBaseDir, 'artifacts', 'web', 'web-broken');
+    await mkdir(invalid, { recursive: true });
+    await writeFile(join(invalid, 'README.txt'), 'broken\n');
+
+    const result = await pruneComponentArtifacts({ stackBaseDir, component: 'web', keepCount: 2 });
+
+    assert.deepEqual(result.keptFingerprints.sort(), ['web-2', 'web-3']);
+    assert.deepEqual(result.removedEntries.sort(), ['web-1', 'web-broken']);
+    await assert.rejects(() => readFile(join(oldest, 'manifest.json'), 'utf8'), /ENOENT/);
+    assert.equal(await readFile(join(previous, 'manifest.json'), 'utf8').then(Boolean), true);
+    assert.equal(await readFile(join(current, 'manifest.json'), 'utf8').then(Boolean), true);
+  } finally {
+    await rm(stackBaseDir, { recursive: true, force: true });
+  }
+});

package/scripts/build/workspace_build_sandbox.mjs

@@ -0,0 +1,49 @@
+import { cp, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { pathExists } from '../utils/fs/fs.mjs';
+
+export async function findWorkspaceMonorepoRoot(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 12; i += 1) {
+    if ((await pathExists(join(dir, 'package.json'))) && (await pathExists(join(dir, 'yarn.lock')))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`[build] failed to locate monorepo root from ${startDir}`);
+}
+
+async function copyIntoSandbox({ sourceRoot, sandboxRoot, relativePath }) {
+  const sourcePath = join(sourceRoot, relativePath);
+  const destPath = join(sandboxRoot, relativePath);
+  await cp(sourcePath, destPath, { recursive: true });
+}
+
+export async function createWorkspaceBuildSandbox({ packageDir, extraRelativePaths = [] }) {
+  const monorepoRoot = await findWorkspaceMonorepoRoot(packageDir);
+  const packageRelativeDir = relative(monorepoRoot, resolve(packageDir));
+  const sandboxRoot = await mkdtemp(join(tmpdir(), 'hstack-build-sandbox-'));
+
+  await copyIntoSandbox({ sourceRoot: monorepoRoot, sandboxRoot, relativePath: 'package.json' });
+  await copyIntoSandbox({ sourceRoot: monorepoRoot, sandboxRoot, relativePath: 'yarn.lock' });
+  await copyIntoSandbox({ sourceRoot: monorepoRoot, sandboxRoot, relativePath: packageRelativeDir });
+  for (const extraRelativePath of extraRelativePaths) {
+    await copyIntoSandbox({ sourceRoot: monorepoRoot, sandboxRoot, relativePath: extraRelativePath });
+  }
+  if (await pathExists(join(monorepoRoot, 'node_modules'))) {
+    await symlink(join(monorepoRoot, 'node_modules'), join(sandboxRoot, 'node_modules'), 'junction');
+  }
+
+  return {
+    monorepoRoot,
+    sandboxRoot,
+    sandboxPackageDir: join(sandboxRoot, packageRelativeDir),
+    async cleanup() {
+      await rm(sandboxRoot, { recursive: true, force: true });
+    },
+  };
+}

package/scripts/build/workspace_build_sandbox.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtemp, mkdir, readlink, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { createWorkspaceBuildSandbox } from './workspace_build_sandbox.mjs';
+
+test('createWorkspaceBuildSandbox exposes the source node_modules to staged workspaces', async () => {
+  const repoRoot = await mkdtemp(join(tmpdir(), 'workspace-build-sandbox-test-'));
+  const packageDir = join(repoRoot, 'apps', 'server');
+  const agentsDir = join(repoRoot, 'packages', 'agents');
+  const nodeModulesDir = join(repoRoot, 'node_modules');
+
+  await mkdir(packageDir, { recursive: true });
+  await mkdir(agentsDir, { recursive: true });
+  await mkdir(nodeModulesDir, { recursive: true });
+  await writeFile(join(repoRoot, 'package.json'), '{}');
+  await writeFile(join(repoRoot, 'yarn.lock'), '');
+  await writeFile(join(packageDir, 'package.json'), '{}');
+  await writeFile(join(agentsDir, 'package.json'), '{}');
+  await writeFile(join(nodeModulesDir, 'sentinel.txt'), 'reachable');
+
+  const sandbox = await createWorkspaceBuildSandbox({
+    packageDir,
+    extraRelativePaths: ['packages/agents'],
+  });
+
+  try {
+    const sandboxNodeModulesLink = join(sandbox.sandboxRoot, 'node_modules');
+    const target = await readlink(sandboxNodeModulesLink);
+    assert.equal(target, nodeModulesDir);
+  } finally {
+    await sandbox.cleanup();
+    await rm(repoRoot, { recursive: true, force: true });
+  }
+});

package/scripts/build.mjs

@@ -7,12 +7,16 @@ import { dirname, join } from 'node:path';
 import { readFile, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tailscaleServeHttpsUrl } from './tailscale.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, wantsExpoClearCache } from './utils/expo/expo.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, resolveExpoTmpDir, wantsExpoClearCache } from './utils/expo/expo.mjs';
 import { expoExec } from './utils/expo/command.mjs';
 import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
 import { applyStackTauriOverrides } from './utils/tauri/stack_overrides.mjs';
 import { buildIntoTempThenReplace } from './utils/fs/atomic_dir_swap.mjs';
 import { pathExists } from './utils/fs/fs.mjs';
+import { buildStackTauriExportEnv, buildStackWebExportEnv } from './utils/ui/ui_export_env.mjs';
+import { parseBuildSelection } from './build/build_targets.mjs';
+import { shouldBuildStackArtifacts } from './build/build_mode.mjs';
+import { buildStackArtifacts } from './build/build_stack_artifacts.mjs';
 
 /**
  * Build a lightweight static web UI bundle (no Expo dev server).
@@ -29,14 +33,18 @@ async function main() {
   if (wantsHelp(argv, { flags })) {
     printResult({
       json,
-      data: { flags: ['--tauri', '--no-tauri', '--no-ui'], json: true },
+      data: { flags: ['--web', '--server', '--daemon', '--all', '--activate-runtime', '--force-rebuild', '--tauri', '--no-tauri', '--no-ui'], json: true },
       text: [
         '[build] usage:',
         '  hstack build [--tauri] [--json]',
-        '  node scripts/build.mjs [--tauri|--no-tauri] [--no-ui] [--json]',
+        '  hstack stack build <name> [--web|--server|--daemon|--all] [--activate-runtime] [--force-rebuild] [--json]',
+        '  node scripts/build.mjs [--web|--server|--daemon|--all] [--activate-runtime] [--tauri|--no-tauri] [--no-ui] [--json]',
         '',
         'note:',
         '  If run from inside the Happier UI checkout/worktree, the build uses that checkout.',
+        '  Explicit component flags build stack-local artifacts for named stacks in v1.',
+        '  Building artifacts alone does not switch the active runtime; use `hstack stack runtime <name> activate ...` or `--activate-runtime`.',
+        '  --tauri remains a legacy local UI/Tauri build flag and cannot be mixed with stack-local artifact/runtime flags in v1.',
       ].join('\n'),
     });
     return;
@@ -55,6 +63,24 @@ async function main() {
     }
   }
 
+  const selection = parseBuildSelection({ argv });
+  const wantsArtifactBuild = shouldBuildStackArtifacts({ selection, argv, env: process.env });
+  if (wantsArtifactBuild) {
+    const result = await buildStackArtifacts({ rootDir, argv, env: process.env });
+    if (json) {
+      printResult({ json, data: result });
+    } else {
+      console.log(`[build] stack artifacts ready for ${result.stackName}`);
+      for (const [component, artifact] of Object.entries(result.artifacts ?? {})) {
+        console.log(`[build] ${component}: ${artifact.artifactDir}`);
+      }
+      if (result.runtime?.snapshotPath) {
+        console.log(`[build] runtime snapshot activated: ${result.runtime.snapshotPath}`);
+      }
+    }
+    return;
+  }
+
   // Optional: skip building the web UI bundle.
   //
   // This is useful for evidence capture flows that validate non-UI components (e.g. `happy-cli`)
@@ -93,14 +119,7 @@ async function main() {
   console.log(`[local] exporting web UI to ${outDir}...`);
 
   // Build for root hosting (the server redirects /ui -> /).
-  const env = {
-    ...process.env,
-    NODE_ENV: 'production',
-    EXPO_PUBLIC_DEBUG: '0',
-    // Leave empty for web export so the app uses window.location.origin at runtime.
-    // (Important for Tailscale: a phone loading `http://100.x.y.z:3005` must not call `http://localhost:3005`.)
-    EXPO_PUBLIC_HAPPY_SERVER_URL: '',
-  };
+  const env = buildStackWebExportEnv({ baseEnv: process.env });
 
   // Expo CLI is available via node_modules/.bin once dependencies are installed.
   await buildIntoTempThenReplace(outDir, async (tmpOutDir) => {
@@ -114,7 +133,8 @@ async function main() {
       projectDir: uiDir,
       stateFileName: 'ui.export.state.json',
     });
-    await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+    const tmpDir = resolveExpoTmpDir({ env, defaultTmpDir: paths.tmpDir, kind: 'ui-export', projectDir: uiDir });
+    await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir });
     const args = ['export', '--platform', 'web', '--output-dir', tmpOutDir, ...(wantsExpoClearCache({ env }) ? ['-c'] : [])];
     await expoExec({ dir: uiDir, args, env, ensureDepsLabel: 'happier-ui' });
 
@@ -171,27 +191,19 @@ async function main() {
 
   console.log(`[local] exporting web UI for Tauri to ${tauriDistDir}...`);
 
-  const tauriEnv = {
-    ...process.env,
-    NODE_ENV: 'production',
-    EXPO_PUBLIC_DEBUG: '0',
-    // In Tauri, window.location.origin is a tauri:// origin, so we must hardcode the API base.
-    EXPO_PUBLIC_HAPPY_SERVER_URL: tauriServerUrl,
-    // Some parts of the app use EXPO_PUBLIC_SERVER_URL; keep them aligned.
-    EXPO_PUBLIC_SERVER_URL: tauriServerUrl,
-    // For the Tauri bundle we want root-relative assets (no /ui baseUrl), so do not set EXPO_PUBLIC_WEB_BASE_URL
-  };
+  const tauriEnv = buildStackTauriExportEnv({ baseEnv: process.env, tauriServerUrl });
   delete tauriEnv.EXPO_PUBLIC_WEB_BASE_URL;
 
   {
-    const paths = getExpoStatePaths({
-      baseDir: getDefaultAutostartPaths().baseDir,
-      kind: 'ui-export-tauri',
-      projectDir: uiDir,
-      stateFileName: 'ui.export.tauri.state.json',
-    });
-    await ensureExpoIsolationEnv({ env: tauriEnv, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
-  }
+      const paths = getExpoStatePaths({
+        baseDir: getDefaultAutostartPaths().baseDir,
+        kind: 'ui-export-tauri',
+        projectDir: uiDir,
+        stateFileName: 'ui.export.tauri.state.json',
+      });
+      const tmpDir = resolveExpoTmpDir({ env: tauriEnv, defaultTmpDir: paths.tmpDir, kind: 'ui-export-tauri', projectDir: uiDir });
+      await ensureExpoIsolationEnv({ env: tauriEnv, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir });
+    }
 
   await expoExec({
     dir: uiDir,