@happier-dev/stack 0.1.0-preview.74.1

package/scripts/lint.mjs

@@ -0,0 +1,177 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
+
+const VALID_TARGETS = ['ui', 'cli', 'server'];
+
+function targetFromComponent(component) {
+  const c = String(component ?? '').trim();
+  if (c === 'happier-ui' || c === 'happy') return 'ui';
+  if (c === 'happier-cli' || c === 'happy-cli') return 'cli';
+  if (c === 'happier-server' || c === 'happier-server-light' || c === 'happy-server' || c === 'happy-server-light') return 'server';
+  return null;
+}
+
+function componentFromTarget(target) {
+  const t = String(target ?? '').trim();
+  if (t === 'ui') return 'happier-ui';
+  if (t === 'cli') return 'happier-cli';
+  if (t === 'server') return 'happier-server';
+  return null;
+}
+
+function normalizeTargetsOrThrow(rawTargets) {
+  const requested = Array.isArray(rawTargets) ? rawTargets.map((t) => String(t ?? '').trim()).filter(Boolean) : [];
+  if (!requested.length) return ['all'];
+
+  const mapped = requested
+    .map((t) => {
+      const lower = t.toLowerCase();
+      if (lower === 'all') return 'all';
+      if (VALID_TARGETS.includes(lower)) return lower;
+      return targetFromComponent(lower) ?? null;
+    })
+    .filter(Boolean);
+
+  if (!mapped.length) return ['all'];
+  return mapped;
+}
+
+function pickLintScript(scripts) {
+  const candidates = [
+    'lint',
+    'lint:ci',
+    'check',
+    'check:lint',
+    'eslint',
+    'eslint:check',
+  ];
+  return pickFirstScript(scripts, candidates);
+}
+
+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: { targets: [...VALID_TARGETS, 'all'], flags: ['--json'] },
+      text: [
+        '[lint] usage:',
+        '  hstack lint [ui|cli|server|all] [--json]',
+        '',
+        'targets:',
+        `  ${[...VALID_TARGETS, 'all'].join(' | ')}`,
+        '',
+        'examples:',
+        '  hstack lint',
+        '  hstack lint ui',
+        '  hstack lint ui cli',
+        '',
+        'note:',
+        '  If run from inside a repo checkout/worktree and no targets are provided, defaults to the inferred app (ui/cli/server).',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const inferredComponent =
+    positionals.length === 0
+      ? inferComponentFromCwd({
+          rootDir,
+          invokedCwd: getInvokedCwd(process.env),
+          components: ['happier-ui', 'happier-cli', 'happier-server', 'happier-server-light', 'happy', 'happy-cli', 'happy-server', 'happy-server-light'],
+        })
+      : null;
+  if (inferredComponent) {
+    if (!(process.env.HAPPIER_STACK_REPO_DIR ?? '').toString().trim()) {
+      process.env.HAPPIER_STACK_REPO_DIR = inferredComponent.repoDir;
+    }
+  }
+
+  const inferredTarget = inferredComponent ? targetFromComponent(inferredComponent.component) : null;
+  const requested = normalizeTargetsOrThrow(positionals.length ? positionals : inferredTarget ? [inferredTarget] : ['all']);
+  const wantAll = requested.includes('all');
+  const targets = wantAll ? VALID_TARGETS : requested;
+
+  const results = [];
+  for (const target of targets) {
+    if (!VALID_TARGETS.includes(target)) {
+      results.push({ target, ok: false, skipped: false, error: `unknown target (expected one of: ${[...VALID_TARGETS, 'all'].join(', ')})` });
+      continue;
+    }
+
+    const component = componentFromTarget(target);
+    const dir = getComponentDir(rootDir, component);
+    if (!(await pathExists(dir))) {
+      results.push({ target, ok: false, skipped: false, dir, error: `missing target dir: ${dir}` });
+      continue;
+    }
+
+    const scripts = await readPackageJsonScripts(dir);
+    if (!scripts) {
+      results.push({ target, ok: true, skipped: true, dir, reason: 'no package.json' });
+      continue;
+    }
+
+    const script = pickLintScript(scripts);
+    if (!script) {
+      results.push({ target, ok: true, skipped: true, dir, reason: 'no lint script found in package.json' });
+      continue;
+    }
+
+    await ensureDepsInstalled(dir, target);
+    const pm = await detectPackageManagerCmd(dir);
+
+    try {
+      // eslint-disable-next-line no-console
+      console.log(`[lint] ${target}: running ${pm.name} ${script}`);
+      await run(pm.cmd, pm.argsForScript(script), { cwd: dir, env: process.env });
+      results.push({ target, ok: true, skipped: false, dir, pm: pm.name, script });
+    } catch (e) {
+      results.push({ target, ok: false, skipped: false, dir, pm: pm.name, script, error: String(e?.message ?? e) });
+    }
+  }
+
+  const ok = results.every((r) => r.ok);
+  if (json) {
+    printResult({ json, data: { ok, results } });
+    return;
+  }
+
+  const lines = ['[lint] results:'];
+  for (const r of results) {
+    if (r.ok && r.skipped) {
+      lines.push(`- ↪ ${r.target}: skipped (${r.reason})`);
+    } else if (r.ok) {
+      lines.push(`- ✅ ${r.target}: ok (${r.pm} ${r.script})`);
+    } else {
+      lines.push(`- ❌ ${r.target}: failed (${r.pm ?? 'unknown'} ${r.script ?? ''})`);
+      if (r.error) lines.push(`  - ${r.error}`);
+    }
+  }
+  if (!ok) {
+    lines.push('');
+    lines.push('[lint] failed');
+  }
+  printResult({ json: false, text: lines.join('\n') });
+  if (!ok) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('[lint] failed:', err);
+  process.exit(1);
+});

package/scripts/menubar.mjs

@@ -0,0 +1,202 @@
+import './utils/env/env.mjs';
+import { cp, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { normalizeProfile } from './utils/cli/normalize.mjs';
+import { banner, kv, sectionTitle } from './utils/ui/layout.mjs';
+import { cyan, dim, green } from './utils/ui/ansi.mjs';
+import { detectSwiftbarPluginInstalled, removeSwiftbarPlugins } from './utils/menubar/swiftbar.mjs';
+
+async function ensureSwiftbarAssets({ cliRootDir }) {
+  const homeDir = getHappyStacksHomeDir();
+  const destDir = join(homeDir, 'extras', 'swiftbar');
+  const srcDir = join(cliRootDir, 'extras', 'swiftbar');
+
+  if (!existsSync(srcDir)) {
+    throw new Error(`[menubar] missing assets at: ${srcDir}`);
+  }
+
+  await mkdir(destDir, { recursive: true });
+  await cp(srcDir, destDir, {
+    recursive: true,
+    force: true,
+    filter: (p) => !p.includes('.DS_Store'),
+  });
+
+  return { homeDir, destDir };
+}
+
+function openSwiftbarPluginsDir() {
+  const s = 'DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; if [[ -z "$DIR" ]]; then DIR="$HOME/Library/Application Support/SwiftBar/Plugins"; fi; open "$DIR"';
+  const res = spawnSync('bash', ['-lc', s], { stdio: 'inherit' });
+  if (res.status !== 0) {
+    process.exit(res.status ?? 1);
+  }
+}
+
+function sandboxPluginBasename() {
+  const sandboxDir = (process.env.HAPPIER_STACK_SANDBOX_DIR ?? '').trim();
+  if (!sandboxDir) return '';
+  const hash = createHash('sha256').update(sandboxDir).digest('hex').slice(0, 10);
+  return `hstack.sandbox-${hash}`;
+}
+
+async function main() {
+  const rawArgv = process.argv.slice(2);
+  const argv = rawArgv[0] === 'menubar' ? rawArgv.slice(1) : rawArgv;
+  const helpSepIdx = argv.indexOf('--');
+  const helpScopeArgv = helpSepIdx === -1 ? argv : argv.slice(0, helpSepIdx);
+  const { flags } = parseArgs(helpScopeArgv);
+  const json = wantsJson(helpScopeArgv, { flags });
+
+  const cmd = helpScopeArgv.find((a) => a && a !== '--' && !a.startsWith('-')) || 'help';
+  const wantsHelpFlag = wantsHelp(helpScopeArgv, { flags });
+  const usageByCmd = new Map([
+    ['install', 'hstack menubar install [--json]'],
+    ['uninstall', 'hstack menubar uninstall [--json]'],
+    ['open', 'hstack menubar open [--json]'],
+    ['mode', 'hstack menubar mode <selfhost|dev> [--json]'],
+    ['status', 'hstack menubar status [--json]'],
+  ]);
+
+  if (wantsHelpFlag && cmd !== 'help') {
+    const usage = usageByCmd.get(cmd);
+    if (usage) {
+      printResult({
+        json,
+        data: { ok: true, cmd, usage },
+        text: [`[menubar ${cmd}] usage:`, `  ${usage}`, '', 'see also:', '  hstack menubar --help'].join('\n'),
+      });
+      return;
+    }
+  }
+
+  if (wantsHelpFlag || cmd === 'help') {
+    printResult({
+      json,
+      data: { commands: ['install', 'uninstall', 'open', 'mode', 'status'] },
+      text: [
+        banner('menubar', { subtitle: 'SwiftBar menu bar plugin (macOS).' }),
+        '',
+        sectionTitle('usage:'),
+        `  ${cyan('hstack menubar')} install [--json]`,
+        `  ${cyan('hstack menubar')} uninstall [--json]`,
+        `  ${cyan('hstack menubar')} open [--json]`,
+        `  ${cyan('hstack menubar')} mode <selfhost|dev> [--json]`,
+        `  ${cyan('hstack menubar')} status [--json]`,
+        '',
+        sectionTitle('notes:'),
+        `- ${dim('Installs the SwiftBar plugin into the active SwiftBar plugin folder')}`,
+        `- ${dim('Keeps plugin source under <homeDir>/extras/swiftbar for stability')}`,
+        `- ${dim('Sandbox mode: install/uninstall are disabled by default (set HAPPIER_STACK_SANDBOX_ALLOW_GLOBAL=1 to override)')}`,
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const cliRootDir = getRootDir(import.meta.url);
+
+  if (cmd === 'menubar:open' || cmd === 'open') {
+    if (json) {
+      printResult({ json, data: { ok: true } });
+      return;
+    }
+    openSwiftbarPluginsDir();
+    return;
+  }
+
+  if (cmd === 'menubar:uninstall' || cmd === 'uninstall') {
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      printResult({ json, data: { ok: true, skipped: 'sandbox' }, text: '[menubar] uninstall skipped (sandbox mode)' });
+      return;
+    }
+    const patterns = isSandboxed()
+      ? [`${sandboxPluginBasename()}.*.sh`]
+      : ['hstack.*.sh'];
+    const res = await removeSwiftbarPlugins({ patterns });
+    const dir = res.pluginsDir;
+    printResult({
+      json,
+      data: { ok: res.ok, pluginsDir: dir, removed: res.removed },
+      text: dir
+        ? (res.ok ? `[menubar] removed plugins from ${dir}` : `[menubar] failed to remove plugins from ${dir}`)
+        : '[menubar] no plugins dir found',
+    });
+    return;
+  }
+
+  if (cmd === 'status') {
+    const mode = (process.env.HAPPIER_STACK_MENUBAR_MODE ?? 'dev').trim() || 'dev';
+    const swift = await detectSwiftbarPluginInstalled();
+    printResult({
+      json,
+      data: { ok: true, mode, pluginsDir: swift.pluginsDir, installed: swift.installed },
+      text: [
+        sectionTitle('Menubar'),
+        `- ${kv('mode:', cyan(mode))}`,
+        `- ${kv('swiftbar plugin:', swift.installed ? green('installed') : dim('not installed'))}`,
+        swift.pluginsDir ? `- ${kv('plugins dir:', swift.pluginsDir)}` : null,
+      ].filter(Boolean).join('\n'),
+    });
+    return;
+  }
+
+  if (cmd === 'mode') {
+    const positionals = argv.filter((a) => !a.startsWith('--'));
+    const raw = positionals[1] ?? '';
+    const mode = normalizeProfile(raw);
+    if (!mode) {
+      throw new Error('[menubar] usage: hstack menubar mode <selfhost|dev> [--json]');
+    }
+    await ensureEnvLocalUpdated({
+      rootDir: cliRootDir,
+      updates: [
+        { key: 'HAPPIER_STACK_MENUBAR_MODE', value: mode },
+      ],
+    });
+    printResult({ json, data: { ok: true, mode }, text: `[menubar] mode set: ${mode}` });
+    return;
+  }
+
+  if (cmd === 'menubar:install' || cmd === 'install') {
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      throw new Error(
+        '[menubar] install is disabled in sandbox mode.\n' +
+          'Reason: SwiftBar plugin installation writes to a global user folder.\n' +
+          'If you really want this, set: HAPPIER_STACK_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const { destDir } = await ensureSwiftbarAssets({ cliRootDir });
+    const installer = join(destDir, 'install.sh');
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_HOME_DIR: getHappyStacksHomeDir(),
+      ...(isSandboxed()
+        ? {
+            HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME: sandboxPluginBasename(),
+            HAPPIER_STACK_SWIFTBAR_PLUGIN_WRAPPER: '1',
+          }
+        : {}),
+    };
+    const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env });
+    if (res.status !== 0) {
+      process.exit(res.status ?? 1);
+    }
+    printResult({ json, data: { ok: true }, text: '[menubar] installed' });
+    return;
+  }
+
+  throw new Error(`[menubar] unknown command: ${cmd}`);
+}
+
+main().catch((err) => {
+  console.error('[menubar] failed:', err);
+  process.exit(1);
+});

package/scripts/migrate.mjs

@@ -0,0 +1,318 @@
+import './utils/env/env.mjs';
+import { cp, mkdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { readEnvObjectFromFile } from './utils/env/read.mjs';
+import { getComponentDir, getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/server/infra/happy_server_infra.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
+import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import { getEnvValue } from './utils/env/values.mjs';
+import { importPrismaClientFromNodeModules } from './utils/server/prisma_import.mjs';
+
+function usage() {
+  return [
+    '[migrate] usage:',
+    '  hstack migrate light-to-server --from-stack=<name> --to-stack=<name> [--include-files] [--force] [--json]',
+    '',
+    'Notes:',
+    '- This migrates chat data from happier-server-light (PG_Light via embedded PGlite) to happier-server (Docker 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');
+}
+
+const readEnvObject = readEnvObjectFromFile;
+
+function normalizePgliteServerConnToDatabaseUrl(rawConn) {
+  const raw = String(rawConn ?? '').trim();
+  if (!raw) throw new Error('[migrate] invalid PGlite server connection string (empty)');
+  const url = (() => {
+    try {
+      return new URL(raw);
+    } catch {
+      // pglite-socket can return "127.0.0.1:NNNN" (host:port). Convert to a postgres URL.
+      return new URL(`postgresql://postgres@${raw}/postgres?sslmode=disable`);
+    }
+  })();
+  url.searchParams.set('connection_limit', '1');
+  return url.toString();
+}
+
+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 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, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
+  const toFlavor = getEnvValue(toEnv, 'HAPPIER_STACK_SERVER_COMPONENT') || 'happier-server-light';
+
+  if (fromFlavor !== 'happier-server-light') {
+    throw new Error(`[migrate] from-stack must use happier-server-light (got: ${fromFlavor})`);
+  }
+  if (toFlavor !== 'happier-server') {
+    throw new Error(`[migrate] to-stack must use happier-server (got: ${toFlavor})`);
+  }
+
+  const fromDataDir = getEnvValue(fromEnv, 'HAPPIER_SERVER_LIGHT_DATA_DIR') || join(from.baseDir, 'server-light');
+  const fromFilesDir = getEnvValue(fromEnv, 'HAPPIER_SERVER_LIGHT_FILES_DIR') || join(fromDataDir, 'files');
+  const fromDbDir = getEnvValue(fromEnv, 'HAPPIER_SERVER_LIGHT_DB_DIR') || join(fromDataDir, 'pglite');
+
+  const toPortRaw = getEnvValue(toEnv, 'HAPPIER_STACK_SERVER_PORT');
+  let toPort = toPortRaw ? Number(toPortRaw) : NaN;
+  const toEphemeral = !toPortRaw;
+  if (!Number.isFinite(toPort) || toPort <= 0) {
+    // Ephemeral-port stacks don't pin ports in env. Pick a free port for this one-off migration run.
+    toPort = await pickNextFreeTcpPort(3005);
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[migrate] to-stack has no pinned port; using ephemeral port ${toPort} for this migration run`);
+    }
+  }
+
+  // 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, 'HAPPIER_STACK_HANDY_MASTER_SECRET_FILE') || join(to.baseDir, 'happier-server', 'handy-master-secret.txt');
+  await ensureTargetSecretMatchesSource({ sourceSecretPath, targetSecretPath });
+  await ensureEnvFileUpdated({
+    envPath: to.envPath,
+    updates: [{ key: 'HAPPIER_STACK_HANDY_MASTER_SECRET_FILE', value: targetSecretPath }],
+  });
+
+  // Resolve component dirs (prefer stack-pinned dirs).
+  const lightDir = getComponentDir(rootDir, 'happier-server-light', fromEnv);
+  const fullDir = getComponentDir(rootDir, 'happier-server', toEnv);
+
+  await ensureDepsInstalled(lightDir, 'happier-server-light');
+  await ensureDepsInstalled(fullDir, 'happier-server');
+
+  // 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,
+      ...(toEphemeral ? { HAPPIER_STACK_EPHEMERAL_PORTS: '1' } : {}),
+    },
+  });
+  await applyHappyServerMigrations({ serverDir: fullDir, env: { ...process.env, ...infra.env } });
+
+  // Snapshot the embedded DB dir so migration is consistent even if the source server is running.
+  const snapshotDir = join(to.baseDir, 'migrations');
+  await mkdir(snapshotDir, { recursive: true });
+  const snapshotDbDir = join(snapshotDir, `pglite.${basename(fromDbDir)}.${Date.now()}`);
+  await cp(fromDbDir, snapshotDbDir, { recursive: true, force: true });
+
+  // Ensure schema is applied on the snapshot DB (idempotent).
+  await runCapture('yarn', ['-s', 'migrate:light:deploy'], {
+    cwd: lightDir,
+    env: {
+      ...process.env,
+      HAPPIER_SERVER_LIGHT_DATA_DIR: fromDataDir,
+      HAPPIER_SERVER_LIGHT_FILES_DIR: fromFilesDir,
+      HAPPIER_SERVER_LIGHT_DB_DIR: snapshotDbDir,
+    },
+  });
+
+  // Read from the snapshot via a temporary pglite socket and the standard Prisma client.
+  const { PGlite } = await import('@electric-sql/pglite');
+  const { PGLiteSocketServer } = await import('@electric-sql/pglite-socket');
+  const pglite = new PGlite(snapshotDbDir);
+  await pglite.waitReady;
+  const pgliteServer = new PGLiteSocketServer({ db: pglite, host: '127.0.0.1', port: 0 });
+  await pgliteServer.start();
+  const snapshotDbUrl = normalizePgliteServerConnToDatabaseUrl(pgliteServer.getServerConn());
+
+  const SourcePrismaClient = await importPrismaClientFromNodeModules({ dir: lightDir });
+  const TargetPrismaClient = await importPrismaClientFromNodeModules({ dir: 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 HAPPIER_SERVER_LIGHT_FILES_DIR/public/...
+      // (Matches happier-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,
+        snapshotDbDir,
+        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] pglite snapshot dir: ${snapshotDbDir}`,
+        `[migrate] messages: ${migrated}`,
+        includeFiles ? `[migrate] files: mirrored from ${fromFilesDir} -> minio bucket ${infra.env.S3_BUCKET}` : `[migrate] files: skipped`,
+      ].join('\n'),
+    });
+  } finally {
+    try {
+      await sourceDb.$disconnect();
+    } catch {
+      // ignore
+    }
+    try {
+      await targetDb.$disconnect();
+    } catch {
+      // ignore
+    }
+    try {
+      await pgliteServer.stop();
+    } catch {
+      // ignore
+    }
+    try {
+      await pglite.close();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+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 = 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);
+});