@happier-dev/stack 0.1.0-preview.74.1

package/scripts/build.mjs

@@ -0,0 +1,266 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/proc/pm.mjs';
+import { resolveServerPortFromEnv } from './utils/server/urls.mjs';
+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 { 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';
+
+/**
+ * Build a lightweight static web UI bundle (no Expo dev server).
+ *
+ * Output directory default: ~/.happier/stacks/main/ui (legacy: ~/.happier/local/ui)
+ * Server will serve it at / when HAPPIER_SERVER_UI_DIR is set.
+ * (Legacy /ui paths are redirected to /.)
+ */
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--tauri', '--no-tauri', '--no-ui'], json: true },
+      text: [
+        '[build] usage:',
+        '  hstack build [--tauri] [--json]',
+        '  node scripts/build.mjs [--tauri|--no-tauri] [--no-ui] [--json]',
+        '',
+        'note:',
+        '  If run from inside the Happier UI checkout/worktree, the build uses that checkout.',
+      ].join('\n'),
+    });
+    return;
+  }
+  const rootDir = getRootDir(import.meta.url);
+
+  // If invoked from inside the Happier UI checkout/worktree, prefer that directory without requiring `hstack wt use ...`.
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: getInvokedCwd(process.env),
+    components: ['happier-ui', 'happy'],
+  });
+  if (inferred?.component === 'happier-ui' || inferred?.component === 'happy') {
+    if (!(process.env.HAPPIER_STACK_REPO_DIR ?? '').toString().trim()) {
+      process.env.HAPPIER_STACK_REPO_DIR = inferred.repoDir;
+    }
+  }
+
+  // Optional: skip building the web UI bundle.
+  //
+  // This is useful for evidence capture flows that validate non-UI components (e.g. `happy-cli`)
+  // but still require a "build" step.
+  const skipUi = flags.has('--no-ui');
+
+  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
+
+  // For Tauri builds we embed an explicit API base URL (tauri:// origins cannot use window.location.origin).
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+
+  const outDir = process.env.HAPPIER_STACK_UI_BUILD_DIR?.trim()
+    ? process.env.HAPPIER_STACK_UI_BUILD_DIR.trim()
+    : join(getDefaultAutostartPaths().baseDir, 'ui');
+
+  // UI is served at root; /ui redirects to /.
+
+  if (skipUi) {
+    // Ensure the output dir exists so server-light doesn't crash if used, but do not run Expo export.
+    await rm(outDir, { recursive: true, force: true });
+    await mkdir(outDir, { recursive: true });
+    await writeFile(join(outDir, '.hstack-build-skipped'), 'no-ui\n', 'utf-8');
+    if (json) {
+      printResult({ json, data: { ok: true, outDir, skippedUi: true, tauriBuilt: false } });
+    } else {
+      console.log(`[local] skipping UI export (--no-ui); created empty UI dir at ${outDir}`);
+    }
+    return;
+  }
+
+  const uiDir = getComponentDir(rootDir, 'happier-ui');
+  await requireDir('happier-ui', uiDir);
+
+  await ensureDepsInstalled(uiDir, 'happier-ui');
+
+  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: '',
+  };
+
+  // Expo CLI is available via node_modules/.bin once dependencies are installed.
+  await buildIntoTempThenReplace(outDir, async (tmpOutDir) => {
+    // Ensure the output dir exists (Expo writes into it).
+    await rm(tmpOutDir, { recursive: true, force: true });
+    await mkdir(tmpOutDir, { recursive: true });
+
+    const paths = getExpoStatePaths({
+      baseDir: getDefaultAutostartPaths().baseDir,
+      kind: 'ui-export',
+      projectDir: uiDir,
+      stateFileName: 'ui.export.state.json',
+    });
+    await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+    const args = ['export', '--platform', 'web', '--output-dir', tmpOutDir, ...(wantsExpoClearCache({ env }) ? ['-c'] : [])];
+    await expoExec({ dir: uiDir, args, env, ensureDepsLabel: 'happier-ui' });
+
+    const indexPath = join(tmpOutDir, 'index.html');
+    if (!(await pathExists(indexPath))) {
+      throw new Error(
+        `[local] UI export incomplete: missing ${indexPath}\nFix: re-run hstack build (or run hstack dev for dev mode)`,
+      );
+    }
+  });
+
+  if (json) {
+    printResult({ json, data: { ok: true, outDir, tauriBuilt: false } });
+  } else {
+    console.log('[local] UI build complete');
+  }
+
+  //
+  // Tauri build (optional)
+  //
+  // Default: do NOT build Tauri (it's slow and requires extra toolchain).
+  // Enable explicitly with:
+  // - `hstack build -- --tauri`, or
+  // - `HAPPIER_STACK_BUILD_TAURI=1`
+  const envBuildTauri = (process.env.HAPPIER_STACK_BUILD_TAURI ?? '').trim();
+  const buildTauriFromEnv = envBuildTauri !== '' ? envBuildTauri !== '0' : false;
+  const buildTauri = !flags.has('--no-tauri') && (flags.has('--tauri') || buildTauriFromEnv);
+  if (!buildTauri) {
+    return;
+  }
+
+  // Default to debug builds for local development so devtools are available.
+  const tauriDebug = (process.env.HAPPIER_STACK_TAURI_DEBUG ?? '1') === '1';
+
+  // Choose the API endpoint the Tauri app should use.
+  //
+  // Priority:
+  // 1) HAPPIER_STACK_TAURI_SERVER_URL (explicit override)
+  // 2) If available, a Tailscale Serve https://*.ts.net URL (portable across machines on the same tailnet)
+  // 3) Fallback to internal loopback (same-machine)
+  const tauriServerUrlOverride = process.env.HAPPIER_STACK_TAURI_SERVER_URL?.trim()
+    ? process.env.HAPPIER_STACK_TAURI_SERVER_URL.trim()
+    : '';
+  const preferTailscale = (process.env.HAPPIER_STACK_TAURI_PREFER_TAILSCALE ?? '1') !== '0';
+  const tailscaleUrl = preferTailscale ? await tailscaleServeHttpsUrl() : null;
+  const tauriServerUrl = tauriServerUrlOverride || tailscaleUrl || internalServerUrl;
+
+  const tauriDistDir = process.env.HAPPIER_STACK_TAURI_UI_DIR?.trim()
+    ? process.env.HAPPIER_STACK_TAURI_UI_DIR.trim()
+    : join(uiDir, 'dist');
+
+  await rm(tauriDistDir, { recursive: true, force: true });
+  await mkdir(tauriDistDir, { recursive: true });
+
+  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
+  };
+  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 });
+  }
+
+  await expoExec({
+    dir: uiDir,
+    args: [
+      'export',
+      '--platform',
+      'web',
+      '--output-dir',
+      tauriDistDir,
+      // Important: clear bundler cache so EXPO_PUBLIC_* inlining doesn't reuse
+      // the previous (web) export's transform results.
+      '-c',
+    ],
+    env: tauriEnv,
+    ensureDepsLabel: 'happy',
+  });
+
+  // Build the Tauri app using a generated config that skips upstream beforeBuildCommand (which uses yarn).
+  const tauriConfigPath = join(uiDir, 'src-tauri', 'tauri.conf.json');
+  const tauriConfigRaw = await readFile(tauriConfigPath, 'utf-8');
+  const tauriConfig = JSON.parse(tauriConfigRaw);
+  tauriConfig.build = tauriConfig.build ?? {};
+  // Prefer the upstream relative dist dir when possible (less surprising for Tauri tooling).
+  tauriConfig.build.frontendDist = tauriDistDir === join(uiDir, 'dist') ? '../dist' : tauriDistDir;
+  tauriConfig.build.beforeBuildCommand = null;
+  tauriConfig.build.beforeDevCommand = null;
+
+  // Build a separate "local" app so it doesn't reuse previous storage (server URL, auth, etc).
+  // This avoids needing any changes in the Happy source code to override a previously saved server.
+  applyStackTauriOverrides({ tauriConfig, env: process.env });
+
+  if (tauriDebug) {
+    // Enable devtools in debug builds (useful for troubleshooting connectivity).
+    tauriConfig.app = tauriConfig.app ?? {};
+    tauriConfig.app.windows = Array.isArray(tauriConfig.app.windows) ? tauriConfig.app.windows : [];
+    if (tauriConfig.app.windows.length > 0) {
+      tauriConfig.app.windows = tauriConfig.app.windows.map((w) => ({ ...w, devtools: true }));
+    }
+  }
+
+  const generatedConfigPath = join(getDefaultAutostartPaths().baseDir, 'tauri.conf.happier-stack.json');
+  await mkdir(dirname(generatedConfigPath), { recursive: true });
+  await writeFile(generatedConfigPath, JSON.stringify(tauriConfig, null, 2), 'utf-8');
+
+  console.log('[local] building Tauri app...');
+  const cargoTargetDir = join(getDefaultAutostartPaths().baseDir, 'tauri-target');
+  await mkdir(cargoTargetDir, { recursive: true });
+
+  const tauriBuildEnv = {
+    ...process.env,
+    // Fixes builds after moving the repo by isolating cargo outputs from old absolute paths.
+    CARGO_TARGET_DIR: cargoTargetDir,
+    // Newer Tauri CLI parses CI as a boolean; many environments set CI=1 which fails.
+    CI: 'false',
+  };
+
+  const tauriArgs = ['build', '--config', generatedConfigPath];
+  if (tauriDebug) {
+    tauriArgs.push('--debug');
+  }
+  await pmExecBin({ dir: uiDir, bin: 'tauri', args: tauriArgs, env: tauriBuildEnv });
+  if (json) {
+    printResult({ json, data: { ok: true, outDir, tauriBuilt: true, tauriServerUrl } });
+  } else {
+  console.log('[local] Tauri build complete');
+  }
+}
+
+main().catch((err) => {
+  console.error('[local] build failed:', err);
+  process.exit(1);
+});

package/scripts/bundleWorkspaceDeps.mjs

@@ -0,0 +1,38 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { bundleWorkspacePackages, findRepoRoot } from '@happier-dev/cli-common/workspaces';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export function bundleWorkspaceDeps(opts = {}) {
+  const repoRoot = opts.repoRoot ?? findRepoRoot(__dirname);
+  const stackDir = opts.stackDir ?? resolve(repoRoot, 'apps', 'stack');
+
+  const bundles = [
+    {
+      packageName: '@happier-dev/cli-common',
+      srcDir: resolve(repoRoot, 'packages', 'cli-common'),
+      destDir: resolve(stackDir, 'node_modules', '@happier-dev', 'cli-common'),
+    },
+  ];
+
+  bundleWorkspacePackages({ bundles });
+}
+
+const invokedAsMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  return resolve(argv1) === fileURLToPath(import.meta.url);
+})();
+
+if (invokedAsMain) {
+  try {
+    bundleWorkspaceDeps();
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+

package/scripts/bundleWorkspaceDeps.test.mjs

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { bundleWorkspaceDeps } from './bundleWorkspaceDeps.mjs';
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function createBundleFixture(prefix = 'happy-stack-bundle-workspace-deps-') {
+  const repoRoot = mkdtempSync(join(tmpdir(), prefix));
+  const stackDir = resolve(repoRoot, 'apps', 'stack');
+  const cliCommonDir = resolve(repoRoot, 'packages', 'cli-common');
+  writeJson(resolve(repoRoot, 'package.json'), { name: 'repo', private: true });
+  writeFileSync(resolve(repoRoot, 'yarn.lock'), '# lock\n', 'utf8');
+  mkdirSync(resolve(cliCommonDir, 'dist'), { recursive: true });
+  mkdirSync(stackDir, { recursive: true });
+  return { repoRoot, stackDir, cliCommonDir };
+}
+
+test('bundleWorkspaceDeps copies dist + writes a sanitized package.json without install scripts', () => {
+  const { repoRoot, stackDir, cliCommonDir } = createBundleFixture();
+  try {
+    writeJson(resolve(cliCommonDir, 'package.json'), {
+      name: '@happier-dev/cli-common',
+      version: '0.0.0',
+      type: 'module',
+      main: './dist/index.js',
+      types: './dist/index.d.ts',
+      exports: { '.': { default: './dist/index.js', types: './dist/index.d.ts' } },
+      scripts: { postinstall: 'echo should-not-run' },
+    });
+    writeFileSync(resolve(cliCommonDir, 'dist', 'index.js'), 'export const z = 3;\n', 'utf8');
+
+    bundleWorkspaceDeps({ repoRoot, stackDir });
+
+    const bundledPkgJson = JSON.parse(
+      readFileSync(resolve(stackDir, 'node_modules', '@happier-dev', 'cli-common', 'package.json'), 'utf8'),
+    );
+    assert.equal(bundledPkgJson.scripts, undefined);
+    assert.equal(bundledPkgJson.name, '@happier-dev/cli-common');
+    assert.equal(bundledPkgJson.private, true);
+
+    const bundledDistPath = resolve(stackDir, 'node_modules', '@happier-dev', 'cli-common', 'dist', 'index.js');
+    assert.ok(existsSync(bundledDistPath), 'dist/index.js should be copied to bundled location');
+  } finally {
+    rmSync(repoRoot, { recursive: true, force: true });
+  }
+});
+
+test('bundleWorkspaceDeps throws when cli-common dist/ is missing', () => {
+  const { repoRoot, stackDir, cliCommonDir } = createBundleFixture('happy-stack-bundle-workspace-deps-no-dist-');
+  try {
+    rmSync(resolve(cliCommonDir, 'dist'), { recursive: true, force: true });
+    writeJson(resolve(cliCommonDir, 'package.json'), {
+      name: '@happier-dev/cli-common',
+      version: '0.0.0',
+      main: './dist/index.js',
+    });
+    assert.throws(() => bundleWorkspaceDeps({ repoRoot, stackDir }), /Missing dist\/ for @happier-dev\/cli-common/);
+  } finally {
+    rmSync(repoRoot, { recursive: true, force: true });
+  }
+});
+
+test('bundleWorkspaceDeps throws when cli-common package.json is malformed', () => {
+  const { repoRoot, stackDir, cliCommonDir } = createBundleFixture('happy-stack-bundle-workspace-deps-bad-json-');
+  try {
+    writeFileSync(resolve(cliCommonDir, 'package.json'), '{"name":"@happier-dev/cli-common"', 'utf8');
+    assert.throws(() => bundleWorkspaceDeps({ repoRoot, stackDir }), SyntaxError);
+  } finally {
+    rmSync(repoRoot, { recursive: true, force: true });
+  }
+});

package/scripts/ci.mjs

@@ -0,0 +1,135 @@
+import './utils/env/env.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getInvokedCwd } from './utils/cli/cwd_scope.mjs';
+import { run } from './utils/proc/proc.mjs';
+
+function getRootDir() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function findHappyMonorepoRoot(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 12; i++) {
+    const pkg = join(dir, 'package.json');
+    const lock = join(dir, 'yarn.lock');
+    const packagesDir = join(dir, 'packages');
+    if (existsSync(pkg) && existsSync(lock) && existsSync(packagesDir)) {
+      try {
+        // lightweight name check (don’t parse unless needed)
+        const text = readFileSync(pkg, 'utf8');
+        if (text.includes('"name": "monorepo"')) return dir;
+      } catch {
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function resolveDockerHostEnv() {
+  // Prefer Docker Desktop’s user socket on macOS.
+  const desktopSock = resolve(process.env.HOME ?? '', '.docker', 'run', 'docker.sock');
+  if (existsSync(desktopSock)) {
+    return `unix://${desktopSock}`;
+  }
+  // Fallback to the classic location (often present on Linux).
+  const defaultSock = '/var/run/docker.sock';
+  if (existsSync(defaultSock)) {
+    return `unix://${defaultSock}`;
+  }
+  return '';
+}
+
+async function cmdAct({ argv }) {
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  const rootDir = getRootDir();
+  const invokedCwd = getInvokedCwd(process.env);
+  const happyRoot = findHappyMonorepoRoot(invokedCwd);
+  if (!happyRoot) {
+    throw new Error('[ci] could not find Happier monorepo root from cwd; run from inside the happier worktree (monorepo root)');
+  }
+
+  const runner = join(happyRoot, 'scripts', 'ci', 'run-act-tests.sh');
+  if (!existsSync(runner)) {
+    throw new Error(`[ci] missing act runner script: ${runner}`);
+  }
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const jobArgs = positionals.slice(1); // after "act"
+
+  const dockerHost = resolveDockerHostEnv();
+  const env = {
+    ...process.env,
+    ...(dockerHost ? { ACT_DOCKER_SOCKET: dockerHost } : {}),
+  };
+
+  if (!json) {
+    // eslint-disable-next-line no-console
+    console.log(`[ci] act: ${runner}`);
+    if (dockerHost) {
+      // eslint-disable-next-line no-console
+      console.log(`[ci] ACT_DOCKER_SOCKET=${dockerHost}`);
+    }
+    if (jobArgs.length > 0) {
+      // eslint-disable-next-line no-console
+      console.log(`[ci] jobs: ${jobArgs.join(' ')}`);
+    }
+  }
+
+  await run('bash', [runner, ...jobArgs], { cwd: happyRoot, env });
+  printResult({
+    json,
+    data: { ok: true, runner, happyRoot, dockerHost: dockerHost || null },
+    text: '[ci] ✅ act ok',
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { commands: ['act'], flags: ['--json'] },
+      text: ['[ci] usage:', '  hstack ci act [job...] [--json]'].join('\n'),
+    });
+    return;
+  }
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const sub = positionals[0];
+  if (!sub) {
+    throw new Error('[ci] missing subcommand (expected: act)');
+  }
+  if (sub === 'act') {
+    await cmdAct({ argv });
+    return;
+  }
+  throw new Error(`[ci] unknown subcommand: ${sub} (expected: act)`);
+}
+
+const invokedAsMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  return resolve(argv1) === fileURLToPath(import.meta.url);
+})();
+
+if (invokedAsMain) {
+  main().catch((error) => {
+    const msg = error instanceof Error ? error.message : String(error);
+    // eslint-disable-next-line no-console
+    console.error(msg);
+    process.exit(1);
+  });
+}

package/scripts/ci.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, realpath, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { resolveDockerHostEnv } from './ci.mjs';
+
+test('resolveDockerHostEnv prefers Docker Desktop user socket when present', async () => {
+  const prevHome = process.env.HOME;
+  const home = await mkdtemp(join(tmpdir(), 'ci-test-home-'));
+  try {
+    process.env.HOME = home;
+    const sockPath = join(home, '.docker', 'run', 'docker.sock');
+    await mkdir(join(home, '.docker', 'run'), { recursive: true });
+    await writeFile(sockPath, '');
+
+    const host = resolveDockerHostEnv();
+    const hostPath = host.replace(/^unix:\/\//, '');
+    const expected = await realpath(sockPath);
+    const actual = await realpath(hostPath);
+    assert.equal(actual, expected);
+  } finally {
+    process.env.HOME = prevHome;
+    await rm(home, { recursive: true, force: true });
+  }
+});
+
+test('resolveDockerHostEnv still resolves user socket when HOME is unset', async () => {
+  const prevHome = process.env.HOME;
+  const prevCwd = process.cwd();
+  const cwd = await mkdtemp(join(tmpdir(), 'ci-test-cwd-'));
+  try {
+    delete process.env.HOME;
+    process.chdir(cwd);
+    const sockPath = join(cwd, '.docker', 'run', 'docker.sock');
+    await mkdir(join(cwd, '.docker', 'run'), { recursive: true });
+    await writeFile(sockPath, '');
+
+    const host = resolveDockerHostEnv();
+    const hostPath = host.replace(/^unix:\/\//, '');
+    const expected = await realpath(sockPath);
+    const actual = await realpath(hostPath);
+    assert.equal(actual, expected);
+  } finally {
+    process.chdir(prevCwd);
+    if (typeof prevHome === 'undefined') delete process.env.HOME;
+    else process.env.HOME = prevHome;
+    await rm(cwd, { recursive: true, force: true });
+  }
+});

package/scripts/cli-link.mjs

@@ -0,0 +1,57 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureCliBuilt, ensureHappyCliLocalNpmLinked } from './utils/proc/pm.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+
+/**
+ * Link the local Happier CLI wrapper into your PATH.
+ *
+ * This is intentionally extracted so you can re-run linking without doing a full `hstack bootstrap`.
+ *
+ * What it does:
+ * - optionally builds the monorepo CLI package (apps/cli or packages/cli) (controlled by env/flags)
+ * - installs `happier`/`hstack` shims under `<homeDir>/bin` (default: `~/.happier-stack/bin`) (recommended over `npm link`)
+ *
+ * Env:
+ * - HAPPIER_STACK_CLI_BUILD=0 to skip building happier-cli
+ * - HAPPIER_STACK_NPM_LINK=0 to skip shim installation
+ *
+ * Flags:
+ * - --no-build: skip building happier-cli
+ * - --no-link: skip shim installation
+ */
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--no-build', '--no-link'], json: true },
+      text: [
+        '[cli-link] usage:',
+        '  hstack cli:link [--no-build] [--no-link] [--json]',
+        '  node scripts/cli-link.mjs [--no-build] [--no-link] [--json]',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const cliDir = getComponentDir(rootDir, 'happier-cli');
+
+  const buildCli = !flags.has('--no-build') && (process.env.HAPPIER_STACK_CLI_BUILD ?? '1') !== '0';
+  const npmLinkCli = !flags.has('--no-link') && (process.env.HAPPIER_STACK_NPM_LINK ?? '1') !== '0';
+
+  await ensureCliBuilt(cliDir, { buildCli });
+  await ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli });
+
+  printResult({ json, data: { ok: true, buildCli, npmLinkCli }, text: '[local] cli link complete' });
+}
+
+main().catch((err) => {
+  console.error('[local] cli link failed:', err);
+  process.exit(1);
+});