@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/utils/cli/cliDistIntegrity.mjs

@@ -1,6 +1,13 @@
+import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
+import { DEFAULT_CLI_RUNTIME_IMPORT_TIMEOUT_MS } from '@happier-dev/cli-common/runtimeImportProbePolicy';
+
+export const CLI_DIST_INTEGRITY_PROBE_ENV = 'HAPPIER_CLI_DIST_INTEGRITY_PROBE';
+export const CLI_DIST_BUILD_MANIFEST = '.build-manifest.json';
+export const DEFAULT_CLI_DIST_RUNTIME_IMPORT_TIMEOUT_MS = DEFAULT_CLI_RUNTIME_IMPORT_TIMEOUT_MS;
+
 export function isCliScriptEntrypoint(pathLike) {
   const value = String(pathLike ?? '').trim().toLowerCase();
   return value.endsWith('.mjs') || value.endsWith('.js') || value.endsWith('.cjs');
@@ -18,69 +25,139 @@ export function resolveCliDistEntrypointFromBin(cliBin) {
   if (!isCliScriptEntrypoint(bin)) return null;
   try {
     const binDir = dirname(bin);
-    return join(binDir, '..', 'dist', 'index.mjs');
+    const fallbackBuildEntrypoint = join(binDir, '..', 'dist', 'index.mjs');
+    const candidates = [
+      fallbackBuildEntrypoint,
+      join(binDir, '..', 'package-dist', 'index.mjs'),
+    ];
+    let firstExistingCandidate = null;
+    for (const candidate of candidates) {
+      if (!existsSync(candidate)) continue;
+      firstExistingCandidate ??= candidate;
+      if (readCliDistIntegrity(candidate).ok) return candidate;
+    }
+    return firstExistingCandidate ?? fallbackBuildEntrypoint;
   } catch {
     return null;
   }
 }
 
-function extractRelativeMjsImportSpecifiers(source) {
-  const specs = new Set();
-  const patterns = [
-    /(?:^|[^\w$])import\s+(?:[^'"]*?\s+from\s*)?['"]([^'"]+)['"]/gm,
-    /(?:^|[^\w$])export\s+[^'"]*?\s+from\s*['"]([^'"]+)['"]/gm,
-    /import\s*\(\s*['"]([^'"]+)['"]\s*\)/gm,
-  ];
-  for (const re of patterns) {
-    for (const match of source.matchAll(re)) {
-      const spec = String(match?.[1] ?? '').trim();
-      if (!spec || !spec.startsWith('.')) continue;
-      if (!spec.endsWith('.mjs')) continue;
-      specs.add(spec);
-    }
-  }
-  return [...specs];
+export function readCliDistIntegrity(entrypoint) {
+  return readCliDistBuildManifest(entrypoint);
 }
 
-export function findMissingCliDistModules(entrypoint, maxFiles = 400) {
-  const missing = [];
-  const seen = new Set();
-  const queue = [entrypoint];
-  while (queue.length > 0 && seen.size < maxFiles) {
-    const filePath = queue.shift();
-    if (!filePath || seen.has(filePath)) continue;
-    seen.add(filePath);
-
-    let source = '';
-    try {
-      source = readFileSync(filePath, 'utf-8');
-    } catch {
-      missing.push(filePath);
-      continue;
-    }
-
-    const imports = extractRelativeMjsImportSpecifiers(source);
-    for (const spec of imports) {
-      const target = join(dirname(filePath), spec);
-      if (!existsSync(target)) {
-        missing.push(target);
-        continue;
-      }
-      if (!seen.has(target)) {
-        queue.push(target);
-      }
+export function readCliDistBuildManifest(entrypoint) {
+  if (!entrypoint || !existsSync(entrypoint)) {
+    return {
+      ok: false,
+      reason: 'missing_entrypoint',
+      fingerprint: null,
+      fileCount: 0,
+      manifestPath: null,
+    };
+  }
+  const manifestPath = join(dirname(String(entrypoint)), CLI_DIST_BUILD_MANIFEST);
+  if (!existsSync(manifestPath)) {
+    return {
+      ok: false,
+      reason: 'missing_build_manifest',
+      fingerprint: null,
+      fileCount: 0,
+      manifestPath,
+    };
+  }
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const fingerprint = String(manifest?.fingerprint ?? '').trim();
+    if (!/^[a-f0-9]{16}$/i.test(fingerprint)) {
+      return {
+        ok: false,
+        reason: 'invalid_build_manifest_fingerprint',
+        fingerprint: null,
+        fileCount: 0,
+        manifestPath,
+      };
     }
+    const fileCount = Number(manifest?.fileCount);
+    return {
+      ok: true,
+      reason: 'manifest',
+      fingerprint: fingerprint.toLowerCase(),
+      fileCount: Number.isFinite(fileCount) && fileCount >= 0 ? Math.trunc(fileCount) : 0,
+      manifestPath,
+      manifest,
+    };
+  } catch {
+    return {
+      ok: false,
+      reason: 'invalid_build_manifest',
+      fingerprint: null,
+      fileCount: 0,
+      manifestPath,
+    };
   }
-  return missing;
 }
 
-export function readCliDistIntegrity(entrypoint) {
-  if (!entrypoint || !existsSync(entrypoint)) {
-    return { ok: false, reason: 'missing_entrypoint' };
+export async function probeCliDistRuntimeImport(entrypoint, options = {}) {
+  const entry = String(entrypoint ?? '').trim();
+  if (!entry) {
+    throw new Error('[cli-dist] runtime import probe missing entrypoint');
   }
-  const missing = findMissingCliDistModules(entrypoint);
-  if (missing.length === 0) {
-    return { ok: true, reason: 'exists' };
-  }
-  return { ok: false, reason: `incomplete:${missing[0]}` };
+  const nodeExecutable = options.nodeExecutable ?? process.execPath;
+  const timeoutMsRaw = Number(options.timeoutMs ?? DEFAULT_CLI_DIST_RUNTIME_IMPORT_TIMEOUT_MS);
+  const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0
+    ? Math.trunc(timeoutMsRaw)
+    : DEFAULT_CLI_DIST_RUNTIME_IMPORT_TIMEOUT_MS;
+  const env = {
+    ...process.env,
+    ...(options.env ?? {}),
+    // Run the real daemon command loader rather than suppressing CLI dispatch.
+    // This reaches command-owned lazy imports while --help keeps the probe side-effect free.
+    [CLI_DIST_INTEGRITY_PROBE_ENV]: 'daemon-command',
+    HAPPIER_CLI_RUNTIME_DISABLE: '1',
+    HAPPIER_CLI_UPDATE_CHECK: '0',
+  };
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(nodeExecutable, [entry, 'daemon', '--help'], {
+      cwd: options.cwd,
+      env,
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+    let spawnError = null;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+    timeout.unref?.();
+    child.stderr?.on('data', (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on('error', (error) => {
+      spawnError = error;
+    });
+    child.on('close', (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (timedOut) {
+        reject(new Error(`[cli-dist] runtime import probe timed out after ${timeoutMs}ms for ${entry}`));
+        return;
+      }
+      if (spawnError) {
+        reject(spawnError);
+        return;
+      }
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const suffix = stderr.trim() ? `\n${stderr.trim().split('\n').slice(-8).join('\n')}` : '';
+      reject(new Error(`[cli-dist] runtime import probe failed for ${entry} (code=${code}, signal=${signal ?? 'none'}).${suffix}`));
+    });
+  });
 }

package/scripts/utils/cli/cliDistIntegrity.test.mjs

@@ -0,0 +1,157 @@
+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 {
+  DEFAULT_CLI_DIST_RUNTIME_IMPORT_TIMEOUT_MS,
+  probeCliDistRuntimeImport,
+  readCliDistBuildManifest,
+  readCliDistIntegrity,
+} from './cliDistIntegrity.mjs';
+
+test('runtime import probe default budget covers source daemon startup verification', () => {
+  assert.equal(DEFAULT_CLI_DIST_RUNTIME_IMPORT_TIMEOUT_MS, 120_000);
+});
+
+test('readCliDistIntegrity requires a build manifest next to the entrypoint', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-integrity-'));
+  try {
+    const distDir = join(tmp, 'dist');
+    const entrypoint = join(distDir, 'index.mjs');
+    await mkdir(distDir, { recursive: true });
+    await writeFile(entrypoint, 'export const ready = true;\n', 'utf-8');
+
+    assert.deepEqual(readCliDistIntegrity(entrypoint), {
+      ok: false,
+      reason: 'missing_build_manifest',
+      fingerprint: null,
+      fileCount: 0,
+      manifestPath: join(distDir, '.build-manifest.json'),
+    });
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('readCliDistBuildManifest reads the manifest fingerprint without rehashing dist files', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-fingerprint-'));
+  try {
+    const distDir = join(tmp, 'dist');
+    const entrypoint = join(distDir, 'index.mjs');
+    await mkdir(distDir, { recursive: true });
+    await writeFile(entrypoint, "import './missing.mjs';\n", 'utf-8');
+    await writeFile(
+      join(distDir, '.build-manifest.json'),
+      JSON.stringify({
+        fingerprint: 'abcdef1234567890',
+        builtAt: '2026-07-09T00:00:00.000Z',
+        fileCount: 7,
+        toolVersion: '1',
+      }) + '\n',
+      'utf-8',
+    );
+
+    const manifest = readCliDistBuildManifest(entrypoint);
+    assert.equal(manifest.ok, true);
+    assert.equal(manifest.fingerprint, 'abcdef1234567890');
+    assert.equal(manifest.fileCount, 7);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('probeCliDistRuntimeImport resolves a valid ESM entrypoint', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-runtime-probe-ok-'));
+  try {
+    const entrypoint = join(tmp, 'index.mjs');
+    await writeFile(entrypoint, 'export const ready = true;\n', 'utf-8');
+
+    await probeCliDistRuntimeImport(entrypoint);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('probeCliDistRuntimeImport rejects ESM link failures', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-runtime-probe-fail-'));
+  try {
+    const entrypoint = join(tmp, 'index.mjs');
+    await writeFile(entrypoint, "import { A } from './chunk.mjs'; export const value = A;\n", 'utf-8');
+    await writeFile(join(tmp, 'chunk.mjs'), 'export const B = true;\n', 'utf-8');
+
+    await assert.rejects(
+      () => probeCliDistRuntimeImport(entrypoint),
+      /does not provide an export named|runtime import probe failed/
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('probeCliDistRuntimeImport validates the daemon command lazy import closure', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-daemon-probe-fail-'));
+  try {
+    const entrypoint = join(tmp, 'index.mjs');
+    await writeFile(
+      entrypoint,
+      "if (process.argv.includes('daemon')) await import('./daemon.mjs');\n",
+      'utf-8',
+    );
+    await writeFile(join(tmp, 'daemon.mjs'), "import './missing-daemon-dependency.mjs';\n", 'utf-8');
+
+    await assert.rejects(
+      () => probeCliDistRuntimeImport(entrypoint),
+      /missing-daemon-dependency|runtime import probe failed/,
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('probeCliDistRuntimeImport rejects when the import process stays alive past the timeout', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-cli-dist-runtime-probe-timeout-'));
+  try {
+    const entrypoint = join(tmp, 'index.mjs');
+    const pidPath = join(tmp, 'probe.pid');
+    const pipeHolderPidPath = join(tmp, 'pipe-holder.pid');
+    await writeFile(
+      entrypoint,
+      [
+        `import { spawn } from 'node:child_process';`,
+        `import { writeFileSync } from 'node:fs';`,
+        `writeFileSync(${JSON.stringify(pidPath)}, String(process.pid));`,
+        `const pipeHolder = spawn(process.execPath, ['--eval', 'setTimeout(() => {}, 350)'], { stdio: ['ignore', 'ignore', 'inherit'] });`,
+        `writeFileSync(${JSON.stringify(pipeHolderPidPath)}, String(pipeHolder.pid));`,
+        `setInterval(() => {}, 1000);`,
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const result = await Promise.race([
+      probeCliDistRuntimeImport(entrypoint, { timeoutMs: 150 }).then(
+        () => 'resolved',
+        (error) => error,
+      ),
+      new Promise((resolve) => setTimeout(() => resolve('timed-out'), 1000)),
+    ]);
+
+    assert.match(result instanceof Error ? result.message : String(result), /timed out/i);
+    const probePid = Number(await readFile(pidPath, 'utf-8'));
+    assert.throws(
+      () => process.kill(probePid, 0),
+      (error) => error?.code === 'ESRCH',
+      'expected the timed-out import probe process to be reaped before rejection',
+    );
+    const pipeHolderPid = Number(await readFile(pipeHolderPidPath, 'utf-8'));
+    assert.throws(
+      () => process.kill(pipeHolderPid, 0),
+      (error) => error?.code === 'ESRCH',
+      'expected the timed-out import probe stderr pipe to be closed before rejection',
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/utils/cli/cli_registry.mjs

@@ -1,3 +1,10 @@
+const GLOBAL_FLAG_CONTRACTS = [
+  {
+    usage: '--sandbox-dir PATH',
+    description: 'Run fully isolated under PATH (no writes to your real ~/.happier-stack or ~/.happier/stacks)',
+  },
+];
+
 export function gethstackRegistry() {
   /**
    * Command definition shape:
@@ -112,6 +119,13 @@ export function gethstackRegistry() {
       rootUsage: 'hstack dev [-- ...]',
       description: 'Start local stack (dev)',
     },
+    {
+      name: 'dev-targets',
+      kind: 'node',
+      scriptRelPath: 'scripts/dev_targets.mjs',
+      rootUsage: 'hstack dev-targets add|remove|list|show|doctor|path [--stack=NAME]',
+      description: 'Configure Mutagen-backed remote development daemons',
+    },
     {
       name: 'stop',
       kind: 'node',
@@ -186,6 +200,16 @@ export function gethstackRegistry() {
       rootUsage: 'hstack migrate light-to-server --from-stack=<name> --to-stack=<name> [--include-files] [--force] [--json]',
       description: 'Migrate data between server flavors (experimental)',
     },
+    {
+      name: 'sqlite-snapshot',
+      kind: 'node',
+      scriptRelPath: 'scripts/sqlite_snapshot.mjs',
+      rootUsage: [
+        'hstack sqlite-snapshot snapshot --source PATH --output PATH --disposable-root PATH [--json]',
+        'hstack sqlite-snapshot restore --snapshot PATH --output PATH --disposable-root PATH [--json]',
+      ],
+      description: 'Create or restore-verify an explicit disposable SQLite snapshot',
+    },
     {
       name: 'monorepo',
       kind: 'node',
@@ -213,8 +237,8 @@ export function gethstackRegistry() {
       aliases: ['dev-client', 'devclient'],
       kind: 'node',
       scriptRelPath: 'scripts/mobile_dev_client.mjs',
-      rootUsage: 'hstack mobile-dev-client --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
-      description: 'Install the shared hstack dev-client app (iOS)',
+      rootUsage: 'hstack mobile-dev-client --install [--profile=internaldev|publicdev] [--platform=ios|android] [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
+      description: 'Install the shared hstack dev-client app',
     },
     {
       name: 'eas',
@@ -259,8 +283,8 @@ export function gethstackRegistry() {
       rootUsage:
         [
           'hstack remote daemon setup --ssh <user@host> [--preview|--dev|--stable] [--channel <stable|preview|dev>] [--service <user|none>] [--ssh-config-file=<path>] [--server-url=<url>] [--webapp-url=<url>] [--public-server-url=<url>] [--json]',
-          'hstack remote server setup --ssh <user@host> [--preview|--dev|--stable] [--channel <stable|preview|dev>] [--mode <user|system>] [--self-host-server-binary <path>] [--env KEY=VALUE]... [--json]',
-          'hstack remote relay setup --ssh <user@host> [--preview|--dev|--stable] [--channel <stable|preview|dev>] [--mode <user|system>] [--self-host-server-binary <path>] [--env KEY=VALUE]... [--json]',
+          'hstack remote server setup --ssh <user@host> [--preview|--dev|--stable] [--channel <stable|preview|dev>] [--mode <user|system>] [--server-binary <path>] [--env KEY=VALUE]... [--json]',
+          'hstack remote relay setup --ssh <user@host> [--preview|--dev|--stable] [--channel <stable|preview|dev>] [--mode <user|system>] [--server-binary <path>] [--env KEY=VALUE]... [--json]',
         ],
       description: 'Remote setup helpers (SSH verified bootstrap + daemon/server setup)',
     },
@@ -394,6 +418,13 @@ export function gethstackRegistry() {
       argsFromRest: (rest) => ['--run-ios', '--no-metro', '--configuration=Release', ...rest],
       hidden: true,
     },
+    {
+      name: 'mobile:ios:profile',
+      kind: 'node',
+      scriptRelPath: 'scripts/mobile.mjs',
+      argsFromRest: (rest) => ['--prebuild', '--run-ios', '--no-metro', '--configuration=Release', '--profiling-runtime', ...rest],
+      hidden: true,
+    },
     {
       name: 'mobile:install',
       kind: 'node',
@@ -412,6 +443,67 @@ export function gethstackRegistry() {
   return { commands };
 }
 
+function collecthstackRootUsageLines() {
+  const { commands } = gethstackRegistry();
+  const usageLines = [];
+  for (const command of commands) {
+    if (!command.rootUsage) continue;
+    if (Array.isArray(command.rootUsage)) usageLines.push(...command.rootUsage);
+    else usageLines.push(command.rootUsage);
+  }
+  return usageLines;
+}
+
+function normalizeUsageToken(token) {
+  return String(token ?? '')
+    .replace(/^[[(]+/, '')
+    .replace(/[\])]+$/g, '')
+    .replace(/\.{3}$/g, '');
+}
+
+function isLongFlagToken(token) {
+  return /^--[a-z0-9][a-z0-9-]*$/i.test(normalizeUsageToken(token));
+}
+
+function isSpaceSeparatedValuePlaceholder(token) {
+  const normalized = normalizeUsageToken(token);
+  if (!normalized) return false;
+  if (normalized.startsWith('<') && normalized.endsWith('>')) return true;
+  if (/^[A-Z][A-Z0-9_-]*$/i.test(normalized)) return true;
+  if (/^[A-Z][A-Z0-9_-]*=.+$/i.test(normalized)) return true;
+  return false;
+}
+
+function splitFlagUsage(usage) {
+  const tokens = String(usage ?? '').split(/\s+/).filter(Boolean);
+  const [flagToken, valueToken] = tokens;
+  return {
+    flag: normalizeUsageToken(flagToken),
+    value: normalizeUsageToken(valueToken),
+  };
+}
+
+export function gethstackSpaceSeparatedValueFlags() {
+  const valueFlags = new Set();
+  const usageLines = [
+    ...GLOBAL_FLAG_CONTRACTS.map((entry) => entry.usage),
+    ...collecthstackRootUsageLines(),
+  ];
+
+  for (const usageLine of usageLines) {
+    const tokens = String(usageLine ?? '').split(/\s+/).filter(Boolean);
+    for (let index = 0; index < tokens.length - 1; index += 1) {
+      const current = tokens[index];
+      const next = tokens[index + 1];
+      if (!isLongFlagToken(current)) continue;
+      if (!isSpaceSeparatedValuePlaceholder(next)) continue;
+      valueFlags.add(normalizeUsageToken(current));
+    }
+  }
+
+  return valueFlags;
+}
+
 export function resolvehstackCommand(cmd) {
   const registry = gethstackRegistry();
   const map = new Map();
@@ -436,12 +528,11 @@ export function renderhstackRootHelp() {
   const { commands } = gethstackRegistry();
   const visible = commands.filter((c) => !c.hidden);
 
-  const usageLines = [];
-  for (const c of visible) {
-    if (!c.rootUsage) continue;
-    if (Array.isArray(c.rootUsage)) usageLines.push(...c.rootUsage);
-    else usageLines.push(c.rootUsage);
-  }
+  const usageLines = collecthstackRootUsageLines().filter((line) => {
+    const [commandName] = String(line ?? '').trim().split(/\s+/).slice(1);
+    if (!commandName) return false;
+    return visible.some((command) => command.name === commandName);
+  });
 
   const rows = visible
     .filter((c) => c.description)
@@ -459,7 +550,12 @@ export function renderhstackRootHelp() {
     ansiEnabled() ? bold(`${cyan('hstack')} — hstack (Happier Stack) CLI`) : 'hstack - hstack (Happier Stack) CLI',
     '',
     ansiEnabled() ? bold('global flags:') : 'global flags:',
-    `  ${ansiEnabled() ? cyan('--sandbox-dir') : '--sandbox-dir'} PATH   ${ansiEnabled() ? dim('Run fully isolated under PATH (no writes to your real ~/.happier-stack or ~/.happier/stacks)') : 'Run fully isolated under PATH (no writes to your real ~/.happier-stack or ~/.happier/stacks)'}`,
+    ...GLOBAL_FLAG_CONTRACTS.map((entry) => {
+      const { flag, value } = splitFlagUsage(entry.usage);
+      const flagText = `${ansiEnabled() ? cyan(flag) : flag} ${value}`;
+      const description = ansiEnabled() ? dim(entry.description) : entry.description;
+      return `  ${flagText}   ${description}`;
+    }),
     '',
     ansiEnabled() ? bold('usage:') : 'usage:',
     ...usageLines.map((l) => `  ${l}`),

package/scripts/utils/cli/prereqs.test.mjs

@@ -13,7 +13,7 @@ test('assertCliPrereqs({yarn:true}) accepts yarn', async () => {
     const yarnBin = join(root, 'yarn');
     await writeFile(yarnBin, '#!/bin/sh\nexit 0\n', 'utf-8');
     await chmod(yarnBin, 0o755);
-    process.env.PATH = `/bin:${root}`;
+    process.env.PATH = root;
 
     await assertCliPrereqs({ yarn: true });
   } finally {
@@ -25,7 +25,7 @@ test('assertCliPrereqs({yarn:true}) accepts yarn', async () => {
 test('assertCliPrereqs({yarn:true}) throws when yarn is unavailable', async () => {
   const oldPath = process.env.PATH;
   try {
-    process.env.PATH = '/bin';
+    process.env.PATH = '';
     await assert.rejects(() => assertCliPrereqs({ yarn: true }), /yarn/i);
   } finally {
     process.env.PATH = oldPath;