@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/service.mjs

@@ -2,7 +2,7 @@ import './utils/env/env.mjs';
 import { run, runCapture } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir, getSystemdUnitInfo, resolveStackEnvPath } from './utils/paths/paths.mjs';
 import { getInternalServerUrl, getPublicServerUrlEnvOverride } from './utils/server/urls.mjs';
-import { ensureMacAutostartDisabled, ensureMacAutostartEnabled } from './utils/service/autostart_darwin.mjs';
+import { resolveServerUrls } from './utils/server/urls.mjs';
 import { installService as installManagedService, uninstallService as uninstallManagedService } from './utils/service/service_manager.mjs';
 import { getCanonicalHomeDir } from './utils/env/config.mjs';
 import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
@@ -24,6 +24,13 @@ import {
   resolvePreferredStackDaemonStatePaths,
   resolveStackCredentialPaths,
 } from './utils/auth/credentials_paths.mjs';
+import {
+  resolveAutostartEnvFilePath,
+  resolveAutostartLogPaths,
+  resolveAutostartWorkingDirectory,
+} from './utils/service/stack_autostart_resolution.mjs';
+import { buildServiceAuthGuidance } from './utils/service/auth_guidance.mjs';
+import { recordStackRuntimeStopRequest } from './utils/stack/runtime_state.mjs';
 
 /**
  * Manage the autostart service installed by `hstack bootstrap -- --autostart`.
@@ -47,7 +54,7 @@ function getUid() {
   return Number.isFinite(n) ? n : null;
 }
 
-function getAutostartEnv({ rootDir, mode }) {
+function getAutostartEnv({ mode, systemUserHomeDir } = {}) {
   // IMPORTANT:
   // LaunchAgents should NOT bake the entire config into the plist, because that would require
   // reinstalling the service for any config change (server flavor, worktrees, ports, etc).
@@ -60,18 +67,20 @@ function getAutostartEnv({ rootDir, mode }) {
   // Main installs:
   // - default to the main stack env (outside the repo): ~/.happier/stacks/main/env
 
-  const stacksEnvFile = process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '';
-  const envFileRaw = stacksEnvFile || resolveStackEnvPath('main').envPath;
-
-  // For system services, prefer a dynamic %h-based default when no explicit env file is set.
-  // This avoids accidentally pinning root's stack env when the service will run as another user.
-  const envFile =
-    mode === 'system' && !stacksEnvFile
-      ? '%h/.happier/stacks/main/env'
-      : envFileRaw;
+  const explicitEnvFilePath = process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '';
+  const defaultMainEnvFilePath = resolveStackEnvPath('main').envPath;
+  const envFile = resolveAutostartEnvFilePath({
+    mode,
+    explicitEnvFilePath,
+    defaultMainEnvFilePath,
+    systemUserHomeDir,
+  });
 
   return {
     HAPPIER_STACK_ENV_FILE: envFile,
+    // Service-mode behavior: keep server/UI up and start the daemon only once auth exists.
+    HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH: '1',
+    HAPPIER_STACK_SERVICE_MODE: '1',
   };
 }
 
@@ -111,7 +120,7 @@ function ensureLinuxSystemModeSupported({ mode }) {
   }
 }
 
-async function resolveStackAutostartProgramArgs({ rootDir, mode, systemUser }) {
+export async function resolveStackAutostartProgramArgs({ rootDir, mode, systemUser }) {
   const base = getCanonicalHomeDir();
   const candidates =
     process.platform === 'win32'
@@ -134,8 +143,8 @@ async function resolveStackAutostartProgramArgs({ rootDir, mode, systemUser }) {
     }
   }
 
-  if (shimPath) return [shimPath, 'start'];
-  return [process.execPath, resolveInstalledPath(rootDir, 'bin/hstack.mjs'), 'start'];
+  if (shimPath) return [shimPath, 'start', '--restart'];
+  return [process.execPath, resolveInstalledPath(rootDir, 'bin/hstack.mjs'), 'start', '--restart'];
 }
 
 export async function installService({ mode = 'user', systemUser = null } = {}) {
@@ -148,8 +157,19 @@ export async function installService({ mode = 'user', systemUser = null } = {})
   }
   ensureLinuxSystemModeSupported({ mode });
   const rootDir = getRootDir(import.meta.url);
-  const { label, stdoutPath, stderrPath, baseDir } = getDefaultAutostartPaths();
-  const env = getAutostartEnv({ rootDir, mode });
+  const systemUserHomeDir = mode === 'system' && systemUser ? await resolveHomeDirForUser(systemUser) : '';
+  const defaults = getDefaultAutostartPaths();
+  const env = getAutostartEnv({ mode, systemUserHomeDir });
+  const { baseDir, stdoutPath, stderrPath } = resolveAutostartLogPaths({
+    mode,
+    hasStorageDirOverride: Boolean((process.env.HAPPIER_STACK_STORAGE_DIR ?? '').trim()),
+    systemUserHomeDir,
+    stackName: defaults.stackName,
+    defaultBaseDir: defaults.baseDir,
+    defaultStdoutPath: defaults.stdoutPath,
+    defaultStderrPath: defaults.stderrPath,
+  });
+  const { label } = defaults;
   // Ensure the env file exists so the service never points at a missing path.
   try {
     const envFile = env.HAPPIER_STACK_ENV_FILE;
@@ -164,12 +184,14 @@ export async function installService({ mode = 'user', systemUser = null } = {})
     // ignore
   }
   const programArgs = await resolveStackAutostartProgramArgs({ rootDir, mode, systemUser });
-  const workingDirectory =
-    process.platform === 'linux'
-      ? '%h'
-      : process.platform === 'darwin'
-        ? resolveInstalledCliRoot(rootDir)
-        : baseDir;
+  const workingDirectory = resolveAutostartWorkingDirectory({
+    platform: process.platform,
+    mode,
+    defaultHomeDir: homedir(),
+    systemUserHomeDir,
+    baseDir,
+    installedCliRoot: resolveInstalledCliRoot(rootDir),
+  });
 
   await installManagedService({
     platform: process.platform,
@@ -252,109 +274,6 @@ function systemdUnitName() {
   return `${label}.service`;
 }
 
-function systemdUnitPath() {
-  return join(homedir(), '.config', 'systemd', 'user', systemdUnitName());
-}
-
-function systemdEnvLines(env) {
-  return Object.entries(env)
-    .map(([k, v]) => `Environment=${k}=${String(v)}`)
-    .join('\n');
-}
-
-async function ensureSystemdUserServiceEnabled({ rootDir, label, env }) {
-  const unitPath = systemdUnitPath();
-  await mkdir(dirname(unitPath), { recursive: true });
-  const hstackShim = join(getCanonicalHomeDir(), 'bin', 'hstack');
-  const entry = existsSync(hstackShim) ? hstackShim : join(rootDir, 'bin', 'hstack.mjs');
-  const exec = existsSync(hstackShim) ? entry : `${process.execPath} ${entry}`;
-
-  const unit = `[Unit]
-Description=Happier Stack (${label})
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=%h
-${systemdEnvLines(env)}
-ExecStart=${exec} start
-Restart=always
-RestartSec=2
-
-[Install]
-WantedBy=default.target
-`;
-
-  await writeFile(unitPath, unit, 'utf-8');
-  await runCapture('systemctl', ['--user', 'daemon-reload']).catch(() => {});
-  await run('systemctl', ['--user', 'enable', '--now', systemdUnitName()]);
-}
-
-async function ensureSystemdSystemServiceEnabled({ rootDir, label, env, systemUser }) {
-  const { unitName, unitPath } = getSystemdUnitInfo({ mode: 'system' });
-  let userLine = '';
-  let hstackShim = join(getCanonicalHomeDir(), 'bin', 'hstack');
-  if (systemUser) {
-    const home = await resolveHomeDirForUser(systemUser);
-    if (home) {
-      hstackShim = join(home, '.happier-stack', 'bin', 'hstack');
-    }
-    userLine = `User=${systemUser}\n`;
-  }
-
-  const entry = existsSync(hstackShim) ? hstackShim : join(rootDir, 'bin', 'hstack.mjs');
-  const exec = existsSync(hstackShim) ? entry : `${process.execPath} ${entry}`;
-
-  const unit = `[Unit]
-Description=Happier Stack (${label})
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-${userLine}WorkingDirectory=%h
-${systemdEnvLines(env)}
-ExecStart=${exec} start
-Restart=always
-RestartSec=2
-
-[Install]
-WantedBy=multi-user.target
-`;
-
-  try {
-    await writeFile(unitPath, unit, 'utf-8');
-  } catch (e) {
-    const code = e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
-    if (code === 'EACCES' || code === 'EPERM') {
-      throw new Error(`[local] --mode=system requires root (run with sudo).`);
-    }
-    throw e;
-  }
-  await runCapture('systemctl', ['daemon-reload']).catch(() => {});
-  await run('systemctl', ['enable', '--now', unitName]);
-}
-
-async function ensureSystemdUserServiceDisabled({ remove } = {}) {
-  await runCapture('systemctl', ['--user', 'disable', '--now', systemdUnitName()]).catch(() => {});
-  await runCapture('systemctl', ['--user', 'stop', systemdUnitName()]).catch(() => {});
-  if (remove) {
-    await rm(systemdUnitPath(), { force: true }).catch(() => {});
-    await runCapture('systemctl', ['--user', 'daemon-reload']).catch(() => {});
-  }
-}
-
-async function ensureSystemdSystemServiceDisabled({ remove } = {}) {
-  const { unitName, unitPath } = getSystemdUnitInfo({ mode: 'system' });
-  await runCapture('systemctl', ['disable', '--now', unitName]).catch(() => {});
-  await runCapture('systemctl', ['stop', unitName]).catch(() => {});
-  if (remove) {
-    await rm(unitPath, { force: true }).catch(() => {});
-    await runCapture('systemctl', ['daemon-reload']).catch(() => {});
-  }
-}
-
 async function systemdStatus() {
   await run('systemctl', ['--user', 'status', systemdUnitName(), '--no-pager']);
 }
@@ -454,7 +373,12 @@ async function postStartDiagnostics() {
   } catch {
     port = 3005;
   }
-  const { publicServerUrl: publicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port });
+  const resolvedUrls = await resolveServerUrls({ env: process.env, serverPort: port, allowEnable: false }).catch(() => null);
+  const publicUrl =
+    resolvedUrls?.publicServerUrl
+      ? String(resolvedUrls.publicServerUrl)
+      : getPublicServerUrlEnvOverride({ env: process.env, serverPort: port }).publicServerUrl;
+  const publicServerUrlSource = String(resolvedUrls?.publicServerUrlSource ?? '').trim();
 
   const cliDir = getComponentDir(rootDir, 'happier-cli');
   const cliBin = join(cliDir, 'bin', 'happier.mjs');
@@ -542,7 +466,12 @@ async function postStartDiagnostics() {
   console.log(banner('service', { subtitle: `Post-start diagnostics (${stackName})` }));
   console.log('');
 
-  const authCmd = stackName === 'main' ? 'hstack auth login' : `hstack stack auth ${stackName} login`;
+  const authGuidance = buildServiceAuthGuidance({
+    stackName,
+    publicServerUrl: publicUrl,
+    tailscaleServeEnabled: (process.env.HAPPIER_STACK_TAILSCALE_SERVE ?? '0') === '1',
+    publicServerUrlSource,
+  });
 
   if (res.ok && res.kind === 'running') {
     console.log(sectionTitle('Daemon'));
@@ -556,13 +485,37 @@ async function postStartDiagnostics() {
   } else if (!existingCredentialPath) {
     console.log(bullets([`${yellow('!')} auth required ${dim(`(missing ${accessKey})`)}`]));
     console.log('');
+    if (authGuidance.warnings.length > 0) {
+      console.log(sectionTitle('Warning'));
+      for (const w of authGuidance.warnings) {
+        console.log(w);
+        console.log('');
+      }
+    }
     console.log(sectionTitle('Authenticate'));
-    console.log(bullets([`${dim('run:')} ${cmdFmt(authCmd)}`]));
+    console.log(
+      bullets([
+        `${dim('headless (recommended):')} ${cmdFmt(authGuidance.headlessCmd)}`,
+        `${dim('laptop (web):')} ${cmdFmt(authGuidance.laptopCmd)}`,
+      ])
+    );
   } else if (res.kind === 'auth_required') {
     console.log(bullets([`${yellow('!')} waiting for auth ${dim(`(pid=${res.pid ?? 'unknown'})`)}`]));
     console.log('');
+    if (authGuidance.warnings.length > 0) {
+      console.log(sectionTitle('Warning'));
+      for (const w of authGuidance.warnings) {
+        console.log(w);
+        console.log('');
+      }
+    }
     console.log(sectionTitle('Authenticate'));
-    console.log(bullets([`${dim('run:')} ${cmdFmt(authCmd)}`]));
+    console.log(
+      bullets([
+        `${dim('headless (recommended):')} ${cmdFmt(authGuidance.headlessCmd)}`,
+        `${dim('laptop (web):')} ${cmdFmt(authGuidance.laptopCmd)}`,
+      ])
+    );
   } else {
     console.log(bullets([`${yellow('!')} not running`]));
   }
@@ -584,13 +537,26 @@ async function postStartDiagnostics() {
   }
 }
 
-async function stopLaunchAgent({ persistent }) {
+async function stopLaunchAgent({ persistent, requestedBy = 'service stop', reason = '' }) {
   const { plistPath } = getDefaultAutostartPaths();
   if (!existsSync(plistPath)) {
     // Service isn't installed for this stack (common for ad-hoc stacks). Treat as a no-op.
     return;
   }
 
+  const envFile = resolveAutostartEnvFilePath({
+    mode: 'user',
+    explicitEnvFilePath: process.env.HAPPIER_STACK_ENV_FILE?.trim() ? process.env.HAPPIER_STACK_ENV_FILE.trim() : '',
+    defaultMainEnvFilePath: resolveStackEnvPath('main').envPath,
+    systemUserHomeDir: null,
+  });
+  const runtimeStatePath = join(dirname(envFile), 'stack.runtime.json');
+  await recordStackRuntimeStopRequest(runtimeStatePath, {
+    signal: 'SIGTERM',
+    requestedBy,
+    reason,
+  }).catch(() => {});
+
   const { label } = getDefaultAutostartPaths();
 
   // Old-style
@@ -696,13 +662,18 @@ async function main() {
   const argv = process.argv.slice(2);
   const helpSepIdx = argv.indexOf('--');
   const helpScopeArgv = helpSepIdx === -1 ? argv : argv.slice(0, helpSepIdx);
+  const passthrough = helpSepIdx === -1 ? [] : argv.slice(helpSepIdx + 1);
   const mode = resolveServiceMode(helpScopeArgv);
   const systemUser = resolveSystemUser(helpScopeArgv);
   ensureLinuxSystemModeSupported({ mode });
+  const authNow =
+    helpScopeArgv.includes('--auth-now') ||
+    helpScopeArgv.includes('--auth');
 
   if (process.platform !== 'darwin' && process.platform !== 'linux' && process.platform !== 'win32') {
     throw new Error('[local] service commands are only supported on macOS (launchd), Linux (systemd), and Windows (schtasks).');
   }
+  const rootDir = getRootDir(import.meta.url);
   const positionals = helpScopeArgv.filter((a) => a && a !== '--' && !a.startsWith('-'));
   const cmd = positionals[0] ?? 'help';
   const json = wantsJson(helpScopeArgv);
@@ -712,10 +683,10 @@ async function main() {
     ['install', 'hstack service install [--json]'],
     ['uninstall', 'hstack service uninstall [--json]'],
     ['status', 'hstack service status [--json]'],
-    ['start', 'hstack service start [--json]'],
+    ['start', 'hstack service start [--auth-now] [-- <auth login args...>] [--json]'],
     ['stop', 'hstack service stop [--json]'],
-    ['restart', 'hstack service restart [--json]'],
-    ['enable', 'hstack service enable [--json]'],
+    ['restart', 'hstack service restart [--auth-now] [-- <auth login args...>] [--json]'],
+    ['enable', 'hstack service enable [--auth-now] [-- <auth login args...>] [--json]'],
     ['disable', 'hstack service disable [--json]'],
     ['logs', 'hstack service logs [--json]'],
     ['tail', 'hstack service tail'],
@@ -743,8 +714,8 @@ async function main() {
         sectionTitle('usage:'),
         `  ${cyan('hstack service')} install|uninstall [--mode=system|user] [--system-user=<name>] [--json]`,
         `  ${cyan('hstack service')} status [--mode=system|user] [--json]`,
-        `  ${cyan('hstack service')} start|stop|restart [--mode=system|user] [--json]`,
-        `  ${cyan('hstack service')} enable|disable [--mode=system|user] [--json]`,
+        `  ${cyan('hstack service')} start|stop|restart [--mode=system|user] [--auth-now] [-- <auth login args...>] [--json]`,
+        `  ${cyan('hstack service')} enable|disable [--mode=system|user] [--auth-now] [-- <auth login args...>] [--json]`,
         `  ${cyan('hstack service')} logs [--mode=system|user] [--json]`,
         `  ${cyan('hstack service')} tail`,
         '',
@@ -849,6 +820,12 @@ async function main() {
         }
       }
       await postStartDiagnostics();
+      if (authNow) {
+        await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), 'login', ...passthrough], {
+          cwd: rootDir,
+          env: process.env,
+        });
+      }
       if (json) printResult({ json, data: { ok: true, action: 'start' } });
       return;
     case 'stop':
@@ -859,7 +836,7 @@ async function main() {
         return;
       }
       if (process.platform === 'darwin') {
-        await stopLaunchAgent({ persistent: false });
+        await stopLaunchAgent({ persistent: false, requestedBy: 'service stop', reason: 'explicit service stop' });
       } else {
         if (mode === 'system') {
           const { unitName } = getSystemdUnitInfo({ mode });
@@ -881,7 +858,7 @@ async function main() {
       }
       if (process.platform === 'darwin') {
         if (!(await restartLaunchAgentBestEffort())) {
-          await stopLaunchAgent({ persistent: false });
+          await stopLaunchAgent({ persistent: false, requestedBy: 'service restart', reason: 'explicit service restart' });
           await waitForLaunchAgentStopped();
           await startLaunchAgent({ persistent: false });
         }
@@ -894,6 +871,12 @@ async function main() {
         }
       }
       await postStartDiagnostics();
+      if (authNow) {
+        await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), 'login', ...passthrough], {
+          cwd: rootDir,
+          env: process.env,
+        });
+      }
       if (json) printResult({ json, data: { ok: true, action: 'restart' } });
       return;
     case 'enable':
@@ -916,6 +899,12 @@ async function main() {
         }
       }
       await postStartDiagnostics();
+      if (authNow) {
+        await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), 'login', ...passthrough], {
+          cwd: rootDir,
+          env: process.env,
+        });
+      }
       if (json) printResult({ json, data: { ok: true, action: 'enable' } });
       return;
     case 'disable':
@@ -927,7 +916,7 @@ async function main() {
         return;
       }
       if (process.platform === 'darwin') {
-        await stopLaunchAgent({ persistent: true });
+        await stopLaunchAgent({ persistent: true, requestedBy: 'service disable', reason: 'explicit service disable' });
       } else {
         if (mode === 'system') {
           const { unitName } = getSystemdUnitInfo({ mode });

package/scripts/service_autostart_program_args.test.mjs

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+import * as serviceModule from './service.mjs';
+
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+const rootDir = scriptsDir;
+
+test('resolveStackAutostartProgramArgs uses the stable hstack shim with --restart', async (t) => {
+  assert.equal(typeof serviceModule.resolveStackAutostartProgramArgs, 'function');
+
+  const tmp = await mkdtemp(join(tmpdir(), 'stack-service-program-args-'));
+  const canonicalHomeDir = join(tmp, 'canonical-home');
+  const shimPath = join(canonicalHomeDir, 'bin', 'hstack');
+  await mkdir(join(canonicalHomeDir, 'bin'), { recursive: true });
+  await writeFile(shimPath, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+
+  const previousCanonicalHome = process.env.HAPPIER_STACK_CANONICAL_HOME_DIR;
+  process.env.HAPPIER_STACK_CANONICAL_HOME_DIR = canonicalHomeDir;
+  t.after(async () => {
+    if (previousCanonicalHome == null) delete process.env.HAPPIER_STACK_CANONICAL_HOME_DIR;
+    else process.env.HAPPIER_STACK_CANONICAL_HOME_DIR = previousCanonicalHome;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const programArgs = await serviceModule.resolveStackAutostartProgramArgs({ rootDir, mode: 'user', systemUser: null });
+  assert.deepEqual(programArgs, [shimPath, 'start', '--restart']);
+});

package/scripts/service_mode_help.test.mjs

@@ -11,6 +11,7 @@ test('hstack service --help documents systemd mode flag', async () => {
   const res = await runNode([join(rootDir, 'scripts', 'service.mjs'), '--help'], { cwd: rootDir, env: process.env });
   assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
   assert.match(res.stdout, /--mode=system\|user/);
+  assert.match(res.stdout, /--auth-now\b/, `expected help to mention --auth-now\nstdout:\n${res.stdout}`);
 });
 
 test('hstack service --help tolerates invalid mode values', async () => {

package/scripts/setup.mjs

@@ -142,7 +142,7 @@ async function maybeConfigureForkRemoteForDevProfile({ rootDir, interactive, env
     // eslint-disable-next-line no-console
     console.log(
       `${yellow('!')} Dev setup: origin points to upstream (${upstream.owner}/${upstream.repo}), but you don't have push access.\n` +
-        `${dim('Fix:')} re-run ${cyan('hstack setup --profile=dev')} in a TTY to configure a fork, or set ${cyan('HAPPIER_STACK_FORK_URL')} to your fork repo URL.`
+        `${dim('Fix:')} re-run ${cyan('hstack setup-from-source --profile=dev')} in a TTY to configure a fork, or set ${cyan('HAPPIER_STACK_FORK_URL')} to your fork repo URL.`
     );
     return;
   }
@@ -300,11 +300,17 @@ async function ensureLocalRepoStack({ rootDir, repoDir, serverComponent, env, st
   return stackName;
 }
 
-async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, tailscaleWanted, menubarMode, happierRepoUrl }) {
+async function ensureSetupConfigPersisted({ rootDir, profile, serverComponent, tailscaleWanted, menubarMode, happierRepoUrl, stableBranch }) {
   // Repo source here describes where we clone the Happier monorepo from (apps/ui + apps/cli + apps/server).
   const repoSourceForProfile = profile === 'selfhost' ? 'upstream' : null;
   const monoRepo = String(happierRepoUrl ?? '').trim();
+  const stable = String(stableBranch ?? '').trim();
   const updates = [
+    ...(stable
+      ? [
+          { key: 'HAPPIER_STACK_STABLE_BRANCH', value: stable },
+        ]
+      : []),
     { key: 'HAPPIER_STACK_SERVER_COMPONENT', value: serverComponent },
     // Default for selfhost:
     // - monorepo: upstream (Happier)
@@ -639,12 +645,14 @@ async function cmdSetup({ rootDir, argv }) {
 	      data: {
 	        profiles: ['selfhost', 'dev', 'local-repo'],
 	        flags: [
-	          '--profile=selfhost|dev',
+	          '--profile=selfhost|dev|local-repo',
 	          '--server=happier-server-light|happier-server',
 	          '--server-flavor=light|full',
             '--non-interactive',
             '--repo-dir=/abs/path/to/happier   # local-repo profile only',
             '--stack=<name>                   # local-repo profile only (default: local)',
+            '--stable-branch=<name>           # git branch for the stable (workspace/main) checkout',
+            '--branch=<name>                  # alias for --stable-branch',
 	          '--happier-repo=<owner/repo|url>     # override the monorepo clone source',
 	          '--workspace-dir=/absolute/path   # dev profile only',
             '--no-ui-deps                  # bootstrap: skip UI deps',
@@ -663,15 +671,18 @@ async function cmdSetup({ rootDir, argv }) {
       },
 	      text: [
 	        '[setup] usage:',
-	        '  hstack setup',
-	        '  hstack setup --profile=selfhost',
-	        '  hstack setup --profile=dev',
-	        '  hstack setup --profile=dev --workspace-dir=~/Development/happier',
-          '  hstack setup --profile=local-repo --repo-dir=~/Development/happier',
-	        '  hstack setup --happier-repo=happier-dev/happier',
+	        '  hstack setup-from-source',
+	        '  hstack setup-from-source --profile=selfhost',
+	        '  hstack setup-from-source --profile=dev',
+	        '  hstack setup-from-source --profile=dev --workspace-dir=~/Development/happier',
+          '  hstack setup-from-source --profile=local-repo --repo-dir=~/Development/happier',
+	        '  hstack setup-from-source --happier-repo=happier-dev/happier',
 	        '  hstack tools setup-pr --repo=<pr-url|number>',
-	        '  hstack setup --auth',
-	        '  hstack setup --no-auth',
+	        '  hstack setup-from-source --auth',
+	        '  hstack setup-from-source --no-auth',
+          '',
+          'deprecated:',
+          '  hstack setup   # use setup-from-source instead',
 	        '',
 	        'notes:',
 	        '  - selfhost profile is a guided installer for running Happier locally (optionally with Tailscale + autostart).',
@@ -911,6 +922,22 @@ async function cmdSetup({ rootDir, argv }) {
     console.log(`${dim('Repo:')} ${cyan(localRepoDir)}`);
   }
 
+  const stableBranchFlagRaw = (kv.get('--stable-branch') ?? '').toString().trim();
+  const stableBranchAliasRaw = (kv.get('--branch') ?? '').toString().trim();
+  if (stableBranchFlagRaw && stableBranchAliasRaw && stableBranchFlagRaw !== stableBranchAliasRaw) {
+    throw new Error('[setup] conflicting stable branch args: pass only one of --stable-branch=... or --branch=...');
+  }
+  const stableBranchWanted = stableBranchFlagRaw || stableBranchAliasRaw;
+  if (stableBranchWanted) {
+    if (/\s/.test(stableBranchWanted)) {
+      throw new Error('[setup] --stable-branch must not contain whitespace');
+    }
+    if (stableBranchWanted.startsWith('-')) {
+      throw new Error('[setup] --stable-branch must not start with "-"');
+    }
+    process.env.HAPPIER_STACK_STABLE_BRANCH = stableBranchWanted;
+  }
+
   const setupChildEnv = buildSetupChildEnv({
     baseEnv: process.env,
     workspaceDirWanted,
@@ -1209,6 +1236,7 @@ async function cmdSetup({ rootDir, argv }) {
     tailscaleWanted,
     menubarMode,
     happierRepoUrl,
+    stableBranch: stableBranchWanted,
   });
 
   // Apply repo override to this process too (so the immediately-following install step sees it),

package/scripts/setup_deprecation_warning.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runNodeCapture as runNode } from './testkit/stack_script_command_testkit.mjs';
+
+function resolveRootDir() {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  return dirname(scriptsDir);
+}
+
+test('hstack setup prints a deprecation warning (non-JSON)', async () => {
+  const rootDir = resolveRootDir();
+  const res = await runNode([join(rootDir, 'bin', 'hstack.mjs'), 'setup', '--help'], { cwd: rootDir });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr, /deprecated/i);
+  assert.match(res.stderr, /setup-from-source/);
+});
+
+test('hstack setup-from-source does not print the deprecation warning', async () => {
+  const rootDir = resolveRootDir();
+  const res = await runNode([join(rootDir, 'bin', 'hstack.mjs'), 'setup-from-source', '--help'], { cwd: rootDir });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.doesNotMatch(res.stderr, /deprecated/i);
+});
+
+test('hstack setup does not print the warning in --json mode', async () => {
+  const rootDir = resolveRootDir();
+  const res = await runNode(
+    [
+      join(rootDir, 'bin', 'hstack.mjs'),
+      'setup',
+      '--json',
+      '--profile=selfhost',
+      '--server=happier-server-light',
+      '--no-auth',
+      '--no-tailscale',
+      '--no-autostart',
+      '--no-menubar',
+      '--no-start-now',
+    ],
+    { cwd: rootDir, env: { ...process.env, HAPPIER_STACK_TEST_TTY: '0' } }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.doesNotMatch(res.stderr, /deprecated/i);
+});
+