happy-stacks 0.0.0 → 0.1.2

package/scripts/init.mjs

@@ -1,14 +1,25 @@
+import { existsSync } from 'node:fs';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { ensureHomeEnvUpdated } from './utils/config.mjs';
+import { ensureCanonicalHomeEnvUpdated, ensureHomeEnvUpdated } from './utils/config.mjs';
+import { parseDotenv } from './utils/dotenv.mjs';
 
 function expandHome(p) {
   return p.replace(/^~(?=\/)/, homedir());
 }
 
+async function readJsonIfExists(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
@@ -22,6 +33,47 @@ function parseArgValue(argv, key) {
   return null;
 }
 
+function firstNonEmpty(...values) {
+  for (const v of values) {
+    const s = (v ?? '').trim();
+    if (s) return s;
+  }
+  return '';
+}
+
+async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
+  try {
+    const contents = await readFile(path, 'utf-8');
+    const parsed = parseDotenv(contents);
+    for (const [k, v] of parsed.entries()) {
+      const allowOverride = override && (!overridePrefix || k.startsWith(overridePrefix));
+      if (allowOverride || process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v;
+      }
+    }
+  } catch {
+    // ignore missing/invalid env file
+  }
+}
+
+function isWorkspaceBootstrapped(workspaceDir) {
+  // Heuristic: if the expected component repos exist in the workspace, we consider bootstrap "already done"
+  // and avoid re-running the interactive bootstrap wizard from `happys init`.
+  //
+  // Users can always re-run bootstrap explicitly:
+  //   happys bootstrap --interactive
+  try {
+    const componentsDir = join(workspaceDir, 'components');
+    const ui = join(componentsDir, 'happy', 'package.json');
+    const cli = join(componentsDir, 'happy-cli', 'package.json');
+    const serverLight = join(componentsDir, 'happy-server-light', 'package.json');
+    const serverFull = join(componentsDir, 'happy-server', 'package.json');
+    return existsSync(ui) && existsSync(cli) && (existsSync(serverLight) || existsSync(serverFull));
+  } catch {
+    return false;
+  }
+}
+
 async function writeExecutable(path, contents) {
   await writeFile(path, contents, { mode: 0o755 });
 }
@@ -87,31 +139,108 @@ async function main() {
   if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
     console.log([
       '[init] usage:',
-      '  happys init [--home-dir=/path] [--workspace-dir=/path] [--runtime-dir=/path] [--install-path] [--no-runtime] [--no-bootstrap] [--] [bootstrap args...]',
+      '  happys init [--home-dir=/path] [--workspace-dir=/path] [--runtime-dir=/path] [--storage-dir=/path] [--cli-root-dir=/path] [--tailscale-bin=/path] [--tailscale-cmd-timeout-ms=MS] [--tailscale-enable-timeout-ms=MS] [--tailscale-enable-timeout-ms-auto=MS] [--tailscale-reset-timeout-ms=MS] [--install-path] [--no-runtime] [--force-runtime] [--no-bootstrap] [--] [bootstrap args...]',
       '',
       'notes:',
       '  - writes ~/.happy-stacks/.env (stable pointer file)',
       '  - default workspace: ~/.happy-stacks/workspace',
       '  - default runtime: ~/.happy-stacks/runtime (recommended for services/SwiftBar)',
+      '  - runtime install is skipped if the same version is already installed (use --force-runtime to reinstall)',
+      '  - set HAPPY_STACKS_INIT_NO_RUNTIME=1 to persist skipping runtime installs on this machine',
       '  - optional: --install-path adds ~/.happy-stacks/bin to your shell PATH (idempotent)',
-      '  - by default, runs `happys bootstrap --interactive` at the end (TTY only)',
+      '  - by default, runs `happys bootstrap --interactive` at the end (TTY only) IF components are not already present',
     ].join('\n'));
     return;
   }
 
   const cliRootDir = getCliRootDir();
 
+  // Important: `happys init` must be idempotent and must not "forget" custom dirs from a prior install.
+  //
+  // Other scripts load this pointer via `scripts/utils/env.mjs`, but `init.mjs` is often run before
+  // anything else (or directly from a repo checkout). So we load it here too.
+  const canonicalEnvPath = join(homedir(), '.happy-stacks', '.env');
+  if (existsSync(canonicalEnvPath)) {
+    await loadEnvFile(canonicalEnvPath, { override: false });
+    await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_STACKS_' });
+    await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_LOCAL_' });
+  }
+
   const homeDirRaw = parseArgValue(argv, 'home-dir');
-  const homeDir = expandHome((homeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() || join(homedir(), '.happy-stacks'));
+  const homeDir = expandHome(firstNonEmpty(
+    homeDirRaw,
+    process.env.HAPPY_STACKS_HOME_DIR,
+    process.env.HAPPY_LOCAL_HOME_DIR,
+    join(homedir(), '.happy-stacks'),
+  ));
   process.env.HAPPY_STACKS_HOME_DIR = homeDir;
+  process.env.HAPPY_LOCAL_HOME_DIR = process.env.HAPPY_LOCAL_HOME_DIR ?? homeDir;
 
   const workspaceDirRaw = parseArgValue(argv, 'workspace-dir');
-  const workspaceDir = expandHome((workspaceDirRaw ?? '').trim() || join(homeDir, 'workspace'));
-  process.env.HAPPY_STACKS_WORKSPACE_DIR = process.env.HAPPY_STACKS_WORKSPACE_DIR ?? workspaceDir;
+  const workspaceDir = expandHome(firstNonEmpty(
+    workspaceDirRaw,
+    process.env.HAPPY_STACKS_WORKSPACE_DIR,
+    process.env.HAPPY_LOCAL_WORKSPACE_DIR,
+    join(homeDir, 'workspace'),
+  ));
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = workspaceDir;
+  process.env.HAPPY_LOCAL_WORKSPACE_DIR = process.env.HAPPY_LOCAL_WORKSPACE_DIR ?? workspaceDir;
 
   const runtimeDirRaw = parseArgValue(argv, 'runtime-dir');
-  const runtimeDir = expandHome((runtimeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim() || join(homeDir, 'runtime'));
-  process.env.HAPPY_STACKS_RUNTIME_DIR = process.env.HAPPY_STACKS_RUNTIME_DIR ?? runtimeDir;
+  const runtimeDir = expandHome(firstNonEmpty(
+    runtimeDirRaw,
+    process.env.HAPPY_STACKS_RUNTIME_DIR,
+    process.env.HAPPY_LOCAL_RUNTIME_DIR,
+    join(homeDir, 'runtime'),
+  ));
+  process.env.HAPPY_STACKS_RUNTIME_DIR = runtimeDir;
+  process.env.HAPPY_LOCAL_RUNTIME_DIR = process.env.HAPPY_LOCAL_RUNTIME_DIR ?? runtimeDir;
+
+  const storageDirRaw = parseArgValue(argv, 'storage-dir');
+  const storageDirOverride = expandHome((storageDirRaw ?? '').trim());
+  if (storageDirOverride) {
+    process.env.HAPPY_STACKS_STORAGE_DIR = process.env.HAPPY_STACKS_STORAGE_DIR ?? storageDirOverride;
+  }
+
+  const cliRootDirRaw = parseArgValue(argv, 'cli-root-dir');
+  const cliRootDirOverride = expandHome((cliRootDirRaw ?? '').trim());
+  if (cliRootDirOverride) {
+    process.env.HAPPY_STACKS_CLI_ROOT_DIR = process.env.HAPPY_STACKS_CLI_ROOT_DIR ?? cliRootDirOverride;
+  }
+
+  const tailscaleBinRaw = parseArgValue(argv, 'tailscale-bin');
+  const tailscaleBinOverride = expandHome((tailscaleBinRaw ?? '').trim());
+  if (tailscaleBinOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_BIN = process.env.HAPPY_STACKS_TAILSCALE_BIN ?? tailscaleBinOverride;
+  }
+
+  const tailscaleCmdTimeoutMsRaw = parseArgValue(argv, 'tailscale-cmd-timeout-ms');
+  const tailscaleCmdTimeoutMsOverride = (tailscaleCmdTimeoutMsRaw ?? '').trim();
+  if (tailscaleCmdTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_CMD_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_CMD_TIMEOUT_MS ?? tailscaleCmdTimeoutMsOverride;
+  }
+
+  const tailscaleEnableTimeoutMsRaw = parseArgValue(argv, 'tailscale-enable-timeout-ms');
+  const tailscaleEnableTimeoutMsOverride = (tailscaleEnableTimeoutMsRaw ?? '').trim();
+  if (tailscaleEnableTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS ?? tailscaleEnableTimeoutMsOverride;
+  }
+
+  const tailscaleEnableTimeoutMsAutoRaw = parseArgValue(argv, 'tailscale-enable-timeout-ms-auto');
+  const tailscaleEnableTimeoutMsAutoOverride = (tailscaleEnableTimeoutMsAutoRaw ?? '').trim();
+  if (tailscaleEnableTimeoutMsAutoOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS_AUTO =
+      process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS_AUTO ?? tailscaleEnableTimeoutMsAutoOverride;
+  }
+
+  const tailscaleResetTimeoutMsRaw = parseArgValue(argv, 'tailscale-reset-timeout-ms');
+  const tailscaleResetTimeoutMsOverride = (tailscaleResetTimeoutMsRaw ?? '').trim();
+  if (tailscaleResetTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_RESET_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_RESET_TIMEOUT_MS ?? tailscaleResetTimeoutMsOverride;
+  }
 
   const nodePath = process.execPath;
 
@@ -121,30 +250,53 @@ async function main() {
   await mkdir(runtimeDir, { recursive: true });
   await mkdir(join(homeDir, 'bin'), { recursive: true });
 
-  await ensureHomeEnvUpdated({
-    updates: [
-      { key: 'HAPPY_STACKS_HOME_DIR', value: homeDir },
-      { key: 'HAPPY_STACKS_WORKSPACE_DIR', value: workspaceDir },
-      { key: 'HAPPY_STACKS_RUNTIME_DIR', value: runtimeDir },
-      { key: 'HAPPY_STACKS_NODE', value: nodePath },
-    ],
-  });
+  const pointerUpdates = [
+    { key: 'HAPPY_STACKS_HOME_DIR', value: homeDir },
+    { key: 'HAPPY_STACKS_WORKSPACE_DIR', value: workspaceDir },
+    { key: 'HAPPY_STACKS_RUNTIME_DIR', value: runtimeDir },
+    { key: 'HAPPY_STACKS_NODE', value: nodePath },
+  ];
+  if (storageDirOverride) {
+    pointerUpdates.push({ key: 'HAPPY_STACKS_STORAGE_DIR', value: storageDirOverride });
+  }
+  if (cliRootDirOverride) {
+    pointerUpdates.push({ key: 'HAPPY_STACKS_CLI_ROOT_DIR', value: cliRootDirOverride });
+  }
 
-  const installRuntime = !argv.includes('--no-runtime');
+  // Write the "real" home env (used by runtime + scripts), AND a stable pointer at ~/.happy-stacks/.env.
+  // The pointer file allows launchd/SwiftBar/minimal shells to discover the actual install location
+  // even when no env vars are exported.
+  await ensureHomeEnvUpdated({ updates: pointerUpdates });
+  await ensureCanonicalHomeEnvUpdated({ updates: pointerUpdates });
+
+  const initNoRuntimeRaw = (process.env.HAPPY_STACKS_INIT_NO_RUNTIME ?? process.env.HAPPY_LOCAL_INIT_NO_RUNTIME ?? '').trim();
+  const initNoRuntime = initNoRuntimeRaw === '1' || initNoRuntimeRaw.toLowerCase() === 'true' || initNoRuntimeRaw.toLowerCase() === 'yes';
+  const forceRuntime = argv.includes('--force-runtime');
+  const skipRuntime = argv.includes('--no-runtime') || (initNoRuntime && !forceRuntime);
+  const installRuntime = !skipRuntime;
   if (installRuntime) {
-    const pkg = JSON.parse(await readFile(join(cliRootDir, 'package.json'), 'utf-8'));
-    const version = String(pkg.version ?? '').trim() || 'latest';
-    const spec = version === '0.0.0' ? 'happy-stacks@latest' : `happy-stacks@${version}`;
+    const cliPkg = await readJsonIfExists(join(cliRootDir, 'package.json'));
+    const cliVersion = String(cliPkg?.version ?? '').trim() || 'latest';
+    const spec = cliVersion === '0.0.0' ? 'happy-stacks@latest' : `happy-stacks@${cliVersion}`;
 
-    console.log(`[init] installing runtime into ${runtimeDir} (${spec})...`);
-    let res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, spec], { stdio: 'inherit' });
-    if (res.status !== 0) {
-      // Pre-publish developer experience: if the package isn't on npm yet (E404),
-      // fall back to installing the local checkout into the runtime prefix.
-      console.log(`[init] runtime install failed; attempting local install from ${cliRootDir}...`);
-      res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, cliRootDir], { stdio: 'inherit' });
+    const runtimePkgPath = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
+    const runtimePkg = await readJsonIfExists(runtimePkgPath);
+    const runtimeVersion = String(runtimePkg?.version ?? '').trim();
+    const sameVersionInstalled = Boolean(cliVersion && cliVersion !== '0.0.0' && runtimeVersion && runtimeVersion === cliVersion);
+
+    if (!forceRuntime && sameVersionInstalled) {
+      console.log(`[init] runtime already installed in ${runtimeDir} (happy-stacks@${runtimeVersion})`);
+    } else {
+      console.log(`[init] installing runtime into ${runtimeDir} (${spec})...`);
+      let res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, spec], { stdio: 'inherit' });
       if (res.status !== 0) {
-        process.exit(res.status ?? 1);
+        // Pre-publish developer experience: if the package isn't on npm yet (E404),
+        // fall back to installing the local checkout into the runtime prefix.
+        console.log(`[init] runtime install failed; attempting local install from ${cliRootDir}...`);
+        res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, cliRootDir], { stdio: 'inherit' });
+        if (res.status !== 0) {
+          process.exit(res.status ?? 1);
+        }
       }
     }
   }
@@ -154,15 +306,58 @@ async function main() {
   const shim = [
     '#!/bin/bash',
     'set -euo pipefail',
+    'CANONICAL_ENV="$HOME/.happy-stacks/.env"',
+    '',
+    '# Best-effort: if env vars are not exported (common under launchd/SwiftBar),',
+    '# read the stable pointer file at ~/.happy-stacks/.env to discover the real dirs.',
+    'if [[ -f "$CANONICAL_ENV" ]]; then',
+    '  if [[ -z "${HAPPY_STACKS_HOME_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_HOME_DIR="$(grep -E \'^HAPPY_STACKS_HOME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_HOME_DIR=//\')" || true',
+    '    export HAPPY_STACKS_HOME_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_WORKSPACE_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_WORKSPACE_DIR="$(grep -E \'^HAPPY_STACKS_WORKSPACE_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_WORKSPACE_DIR=//\')" || true',
+    '    export HAPPY_STACKS_WORKSPACE_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_RUNTIME_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_RUNTIME_DIR="$(grep -E \'^HAPPY_STACKS_RUNTIME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_RUNTIME_DIR=//\')" || true',
+    '    export HAPPY_STACKS_RUNTIME_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_NODE:-}" ]]; then',
+    '    HAPPY_STACKS_NODE="$(grep -E \'^HAPPY_STACKS_NODE=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_NODE=//\')" || true',
+    '    export HAPPY_STACKS_NODE',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_CLI_ROOT_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_CLI_ROOT_DIR="$(grep -E \'^HAPPY_STACKS_CLI_ROOT_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_CLI_ROOT_DIR=//\')" || true',
+    '    export HAPPY_STACKS_CLI_ROOT_DIR',
+    '  fi',
+    'fi',
+    '',
     'HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"',
     'ENV_FILE="$HOME_DIR/.env"',
-    'NODE_BIN=""',
-    'if [[ -f "$ENV_FILE" ]]; then',
+    'WORKDIR="${HAPPY_STACKS_WORKSPACE_DIR:-$HOME_DIR/workspace}"',
+    'if [[ -d "$WORKDIR" ]]; then',
+    '  cd "$WORKDIR"',
+    'else',
+    '  cd "$HOME"',
+    'fi',
+    'NODE_BIN="${HAPPY_STACKS_NODE:-}"',
+    'if [[ -z "$NODE_BIN" && -f "$ENV_FILE" ]]; then',
     '  NODE_BIN="$(grep -E \'^HAPPY_STACKS_NODE=\' "$ENV_FILE" | head -n 1 | sed \'s/^HAPPY_STACKS_NODE=//\')"',
     'fi',
     'if [[ -z "$NODE_BIN" ]]; then',
     '  NODE_BIN="$(command -v node 2>/dev/null || true)"',
     'fi',
+    'CLI_ROOT_DIR="${HAPPY_STACKS_CLI_ROOT_DIR:-}"',
+    'if [[ -z "$CLI_ROOT_DIR" && -f "$ENV_FILE" ]]; then',
+    '  CLI_ROOT_DIR="$(grep -E \'^HAPPY_STACKS_CLI_ROOT_DIR=\' "$ENV_FILE" | head -n 1 | sed \'s/^HAPPY_STACKS_CLI_ROOT_DIR=//\')" || true',
+    'fi',
+    'if [[ -n "$CLI_ROOT_DIR" ]]; then',
+    '  CLI_ENTRY="$CLI_ROOT_DIR/bin/happys.mjs"',
+    '  if [[ -f "$CLI_ENTRY" ]]; then',
+    '    exec "$NODE_BIN" "$CLI_ENTRY" "$@"',
+    '  fi',
+    'fi',
     'RUNTIME_DIR="${HAPPY_STACKS_RUNTIME_DIR:-$HOME_DIR/runtime}"',
     'ENTRY="$RUNTIME_DIR/node_modules/happy-stacks/bin/happys.mjs"',
     'if [[ -f "$ENTRY" ]]; then',
@@ -202,11 +397,15 @@ async function main() {
 
   const wantBootstrap = !argv.includes('--no-bootstrap');
   const isTty = process.stdout.isTTY && process.stdin.isTTY;
-  const shouldBootstrap = wantBootstrap;
+  const alreadyBootstrapped = isWorkspaceBootstrapped(workspaceDir);
+  const bootstrapExplicit = bootstrapArgs.length > 0;
+  const shouldBootstrap = wantBootstrap && (bootstrapExplicit || !alreadyBootstrapped);
 
   if (shouldBootstrap) {
     const nextArgs = [...bootstrapArgs];
-    if (isTty && !nextArgs.includes('--interactive') && !nextArgs.includes('-i')) {
+    // Only auto-enable the interactive wizard when init is driving bootstrap with no explicit args.
+    // If users pass args after `--`, we assume they know what they want and avoid injecting prompts.
+    if (!bootstrapExplicit && isTty && !nextArgs.includes('--interactive') && !nextArgs.includes('-i')) {
       nextArgs.unshift('--interactive');
     }
     console.log('[init] running bootstrap...');
@@ -221,6 +420,12 @@ async function main() {
     return;
   }
 
+  if (wantBootstrap && alreadyBootstrapped && !bootstrapExplicit) {
+    console.log('[init] bootstrap: already set up; skipping');
+    console.log('[init] tip: to re-run setup: happys bootstrap --interactive');
+    console.log('');
+  }
+
   console.log('[init] next steps:');
   console.log(`  export PATH=\"${homeDir}/bin:$PATH\"`);
   console.log('  happys bootstrap --interactive');
@@ -230,3 +435,4 @@ main().catch((err) => {
   console.error('[init] failed:', err);
   process.exit(1);
 });
+

package/scripts/migrate.mjs

@@ -0,0 +1,292 @@
+import './utils/env.mjs';
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+import { parseArgs } from './utils/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { parseDotenv } from './utils/dotenv.mjs';
+import { ensureEnvFileUpdated } from './utils/env_file.mjs';
+import { resolveStackEnvPath } from './utils/paths.mjs';
+import { ensureDepsInstalled } from './utils/pm.mjs';
+import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/happy_server_infra.mjs';
+import { runCapture } from './utils/proc.mjs';
+
+function usage() {
+  return [
+    '[migrate] usage:',
+    '  happys migrate light-to-server --from-stack=<name> --to-stack=<name> [--include-files] [--force] [--json]',
+    '',
+    'Notes:',
+    '- This migrates chat data from happy-server-light (SQLite) to happy-server (Postgres).',
+    '- It preserves IDs, so existing session URLs keep working on the new server.',
+    '- If --include-files is set, it mirrors server-light local files into Minio (S3) in the target stack.',
+  ].join('\n');
+}
+
+async function readEnvObject(envPath) {
+  try {
+    const raw = await readFile(envPath, 'utf-8');
+    return Object.fromEntries(parseDotenv(raw).entries());
+  } catch {
+    return {};
+  }
+}
+
+function getEnvValue(env, key) {
+  return (env?.[key] ?? '').toString().trim();
+}
+
+function parseFileDatabaseUrl(url) {
+  const raw = String(url ?? '').trim();
+  if (!raw) return null;
+  if (raw.startsWith('file:')) {
+    const path = raw.slice('file:'.length);
+    return { url: raw, path };
+  }
+  return null;
+}
+
+async function ensureTargetSecretMatchesSource({ sourceSecretPath, targetSecretPath }) {
+  try {
+    const src = (await readFile(sourceSecretPath, 'utf-8')).trim();
+    if (!src) return null;
+    await mkdir(join(targetSecretPath, '..'), { recursive: true }).catch(() => {});
+    const { rename, writeFile } = await import('node:fs/promises');
+    // Write with a trailing newline, via atomic replace.
+    const tmp = join(join(targetSecretPath, '..'), `.handy-master-secret.${Date.now()}.tmp`);
+    await writeFile(tmp, src + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await rename(tmp, targetSecretPath);
+    return src;
+  } catch {
+    return null;
+  }
+}
+
+async function importPrismaClientFrom(dir) {
+  const req = createRequire(import.meta.url);
+  const resolved = req.resolve('@prisma/client', { paths: [dir] });
+  // eslint-disable-next-line import/no-dynamic-require
+  const mod = req(resolved);
+  return mod.PrismaClient;
+}
+
+async function migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json }) {
+  const from = resolveStackEnvPath(fromStack);
+  const to = resolveStackEnvPath(toStack);
+
+  const fromEnv = await readEnvObject(from.envPath);
+  const toEnv = await readEnvObject(to.envPath);
+
+  const fromFlavor = getEnvValue(fromEnv, 'HAPPY_STACKS_SERVER_COMPONENT') || getEnvValue(fromEnv, 'HAPPY_LOCAL_SERVER_COMPONENT') || 'happy-server-light';
+  const toFlavor = getEnvValue(toEnv, 'HAPPY_STACKS_SERVER_COMPONENT') || getEnvValue(toEnv, 'HAPPY_LOCAL_SERVER_COMPONENT') || 'happy-server-light';
+
+  if (fromFlavor !== 'happy-server-light') {
+    throw new Error(`[migrate] from-stack must use happy-server-light (got: ${fromFlavor})`);
+  }
+  if (toFlavor !== 'happy-server') {
+    throw new Error(`[migrate] to-stack must use happy-server (got: ${toFlavor})`);
+  }
+
+  const fromDataDir = getEnvValue(fromEnv, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(from.baseDir, 'server-light');
+  const fromFilesDir = getEnvValue(fromEnv, 'HAPPY_SERVER_LIGHT_FILES_DIR') || join(fromDataDir, 'files');
+  const fromDbUrl = getEnvValue(fromEnv, 'DATABASE_URL') || `file:${join(fromDataDir, 'happy-server-light.sqlite')}`;
+  const fromParsed = parseFileDatabaseUrl(fromDbUrl);
+  if (!fromParsed?.path) {
+    throw new Error(`[migrate] from-stack DATABASE_URL must be file:... (got: ${fromDbUrl})`);
+  }
+
+  const toPortRaw = getEnvValue(toEnv, 'HAPPY_STACKS_SERVER_PORT') || getEnvValue(toEnv, 'HAPPY_LOCAL_SERVER_PORT');
+  const toPort = toPortRaw ? Number(toPortRaw) : NaN;
+  if (!Number.isFinite(toPort) || toPort <= 0) {
+    throw new Error(`[migrate] to-stack is missing a valid server port (HAPPY_STACKS_SERVER_PORT)`);
+  }
+
+  // Ensure target secret is the same as source so auth tokens remain valid after migration.
+  const sourceSecretPath = join(fromDataDir, 'handy-master-secret.txt');
+  const targetSecretPath = getEnvValue(toEnv, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE') || join(to.baseDir, 'happy-server', 'handy-master-secret.txt');
+  await ensureTargetSecretMatchesSource({ sourceSecretPath, targetSecretPath });
+  await ensureEnvFileUpdated({
+    envPath: to.envPath,
+    updates: [{ key: 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE', value: targetSecretPath }],
+  });
+
+  // Bring up infra and ensure env vars are present.
+  const infra = await ensureHappyServerManagedInfra({
+    stackName: toStack,
+    baseDir: to.baseDir,
+    serverPort: toPort,
+    publicServerUrl: `http://127.0.0.1:${toPort}`,
+    envPath: to.envPath,
+    env: process.env,
+  });
+  await applyHappyServerMigrations({ serverDir: fullDir, env: { ...process.env, ...infra.env } });
+
+  // Resolve component dirs (prefer stack-pinned dirs).
+  const lightDir = getEnvValue(fromEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT') || getEnvValue(fromEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT');
+  const fullDir = getEnvValue(toEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER') || getEnvValue(toEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER');
+  if (!lightDir || !fullDir) {
+    throw new Error('[migrate] missing component dirs in stack env (expected HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT and HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER)');
+  }
+
+  await ensureDepsInstalled(lightDir, 'happy-server-light');
+  await ensureDepsInstalled(fullDir, 'happy-server');
+
+  // Copy sqlite DB to a snapshot so migration is consistent even if the source server is running.
+  const snapshotDir = join(to.baseDir, 'migrations');
+  await mkdir(snapshotDir, { recursive: true });
+  const snapshotPath = join(snapshotDir, `happy-server-light.${basename(fromParsed.path)}.${Date.now()}.sqlite`);
+  await copyFile(fromParsed.path, snapshotPath);
+  const snapshotDbUrl = `file:${snapshotPath}`;
+
+  const SourcePrismaClient = await importPrismaClientFrom(lightDir);
+  const TargetPrismaClient = await importPrismaClientFrom(fullDir);
+
+  const sourceDb = new SourcePrismaClient({ datasources: { db: { url: snapshotDbUrl } } });
+  const targetDb = new TargetPrismaClient({ datasources: { db: { url: infra.env.DATABASE_URL } } });
+
+  try {
+    // Fail-fast unless target is empty (keeps this safe).
+    const existingSessions = await targetDb.session.count();
+    const existingMessages = await targetDb.sessionMessage.count();
+    if (!force && (existingSessions > 0 || existingMessages > 0)) {
+      throw new Error(
+        `[migrate] target database is not empty (sessions=${existingSessions}, messages=${existingMessages}).\n` +
+          `Pass --force to attempt a merge (skipDuplicates), or migrate into a fresh stack.`
+      );
+    }
+
+    // Core entities
+    const accounts = await sourceDb.account.findMany();
+    if (accounts.length) {
+      await targetDb.account.createMany({ data: accounts, skipDuplicates: true });
+    }
+
+    const machines = await sourceDb.machine.findMany();
+    if (machines.length) {
+      await targetDb.machine.createMany({ data: machines, skipDuplicates: true });
+    }
+
+    const accessKeys = await sourceDb.accessKey.findMany();
+    if (accessKeys.length) {
+      await targetDb.accessKey.createMany({ data: accessKeys, skipDuplicates: true });
+    }
+
+    const sessions = await sourceDb.session.findMany();
+    if (sessions.length) {
+      await targetDb.session.createMany({ data: sessions, skipDuplicates: true });
+    }
+
+    // Messages: stream in batches to avoid high memory.
+    let migrated = 0;
+    const batchSize = 1000;
+    let cursor = null;
+    while (true) {
+      // eslint-disable-next-line no-await-in-loop
+      const page = await sourceDb.sessionMessage.findMany({
+        ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+        orderBy: { id: 'asc' },
+        take: batchSize,
+      });
+      if (!page.length) break;
+      cursor = page[page.length - 1].id;
+      // eslint-disable-next-line no-await-in-loop
+      await targetDb.sessionMessage.createMany({ data: page, skipDuplicates: true });
+      migrated += page.length;
+      // eslint-disable-next-line no-console
+      if (!json && migrated % (batchSize * 20) === 0) console.log(`[migrate] migrated ${migrated} messages...`);
+    }
+
+    // Pending queue (small)
+    const pending = await sourceDb.sessionPendingMessage.findMany();
+    if (pending.length) {
+      await targetDb.sessionPendingMessage.createMany({ data: pending, skipDuplicates: true });
+    }
+
+    if (includeFiles) {
+      // Mirror server-light local files (public/*) into Minio bucket root.
+      // This assumes server-light stored public files under HAPPY_SERVER_LIGHT_FILES_DIR/public/...
+      // (Matches happy-server Minio object keys).
+      const { composePath, projectName } = infra;
+      await runCapture('docker', [
+        'compose',
+        '-f',
+        composePath,
+        '-p',
+        projectName,
+        'run',
+        '--rm',
+        '-T',
+        '-v',
+        `${fromFilesDir}:/src:ro`,
+        'minio-init',
+        'sh',
+        '-lc',
+        [
+          `mc alias set local http://minio:9000 ${infra.env.S3_ACCESS_KEY} ${infra.env.S3_SECRET_KEY}`,
+          `mc mirror --overwrite /src local/${infra.env.S3_BUCKET}`,
+        ].join(' && '),
+      ]);
+    }
+
+    printResult({
+      json,
+      data: {
+        ok: true,
+        fromStack,
+        toStack,
+        snapshotPath,
+        migrated: { accounts: accounts.length, sessions: sessions.length, messages: migrated, machines: machines.length, accessKeys: accessKeys.length },
+        filesMirrored: Boolean(includeFiles),
+      },
+      text: [
+        `[migrate] ok`,
+        `[migrate] from: ${fromStack} (${fromFlavor})`,
+        `[migrate] to:   ${toStack} (${toFlavor})`,
+        `[migrate] sqlite snapshot: ${snapshotPath}`,
+        `[migrate] messages: ${migrated}`,
+        includeFiles ? `[migrate] files: mirrored from ${fromFilesDir} -> minio bucket ${infra.env.S3_BUCKET}` : `[migrate] files: skipped`,
+      ].join('\n'),
+    });
+  } finally {
+    await sourceDb.$disconnect().catch(() => {});
+    await targetDb.$disconnect().catch(() => {});
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({ json, data: { ok: true }, text: usage() });
+    return;
+  }
+
+  const cmd = argv.find((a) => !a.startsWith('--')) ?? '';
+  if (!cmd) {
+    throw new Error(usage());
+  }
+
+  if (cmd !== 'light-to-server') {
+    throw new Error(`[migrate] unknown subcommand: ${cmd}\n\n${usage()}`);
+  }
+
+  const fromStack = (kv.get('--from-stack') ?? 'main').trim();
+  const toStack = (kv.get('--to-stack') ?? '').trim();
+  const includeFiles = flags.has('--include-files') || (kv.get('--include-files') ?? '').trim() === '1';
+  const force = flags.has('--force');
+  if (!toStack) {
+    throw new Error('[migrate] --to-stack is required');
+  }
+
+  const rootDir = (await import('./utils/paths.mjs')).getRootDir(import.meta.url);
+  await migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json });
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});
+