happy-stacks 0.3.0 → 0.5.0

package/scripts/utils/server/mobile_api_url.test.mjs

@@ -0,0 +1,41 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveMobileReachableServerUrl } from './mobile_api_url.mjs';
+
+test('resolveMobileReachableServerUrl rewrites localhost to LAN IP (env override)', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '192.168.0.50' },
+    serverUrl: 'http://localhost:3005',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'http://192.168.0.50:3005');
+});
+
+test('resolveMobileReachableServerUrl rewrites *.localhost to LAN IP (env override)', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '10.0.0.12' },
+    serverUrl: 'http://happy-exp1.localhost:3009/',
+    serverPort: 3009,
+  });
+  assert.equal(out, 'http://10.0.0.12:3009');
+});
+
+test('resolveMobileReachableServerUrl preserves path and query', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '10.0.0.12' },
+    serverUrl: 'http://127.0.0.1:3005/api?x=1',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'http://10.0.0.12:3005/api?x=1');
+});
+
+test('resolveMobileReachableServerUrl does not rewrite non-local URLs', () => {
+  const out = resolveMobileReachableServerUrl({
+    env: { HAPPY_STACKS_LAN_IP: '192.168.0.50' },
+    serverUrl: 'https://my-machine.tailnet.ts.net',
+    serverPort: 3005,
+  });
+  assert.equal(out, 'https://my-machine.tailnet.ts.net');
+});
+

package/scripts/utils/server/prisma_import.mjs

@@ -0,0 +1,37 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { isUnifiedHappyServerLight } from './flavor_scripts.mjs';
+
+function extractPrismaClient(mod) {
+  return mod?.PrismaClient ?? mod?.default?.PrismaClient ?? null;
+}
+
+async function importPrismaClientFromFile(path) {
+  const mod = await import(pathToFileURL(path).href);
+  const PrismaClient = extractPrismaClient(mod);
+  if (!PrismaClient) {
+    throw new Error(`[prisma] PrismaClient export not found in: ${path}`);
+  }
+  return PrismaClient;
+}
+
+export async function importPrismaClientFromNodeModules({ dir }) {
+  const req = createRequire(import.meta.url);
+  const resolved = req.resolve('@prisma/client', { paths: [dir] });
+  return await importPrismaClientFromFile(resolved);
+}
+
+export async function importPrismaClientFromGeneratedSqlite({ dir }) {
+  const path = join(dir, 'generated', 'sqlite-client', 'index.js');
+  return await importPrismaClientFromFile(path);
+}
+
+export async function importPrismaClientForHappyServerLight({ serverDir }) {
+  if (isUnifiedHappyServerLight({ serverDir })) {
+    return await importPrismaClientFromGeneratedSqlite({ dir: serverDir });
+  }
+  return await importPrismaClientFromNodeModules({ dir: serverDir });
+}
+

package/scripts/utils/server/prisma_import.test.mjs

@@ -0,0 +1,70 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  importPrismaClientForHappyServerLight,
+  importPrismaClientFromGeneratedSqlite,
+  importPrismaClientFromNodeModules,
+} from './prisma_import.mjs';
+
+async function writeJson(path, obj) {
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+test('importPrismaClientFromNodeModules imports PrismaClient via node_modules resolution', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-prisma-import-'));
+  try {
+    await mkdir(join(dir, 'node_modules', '@prisma', 'client'), { recursive: true });
+    await writeJson(join(dir, 'node_modules', '@prisma', 'client', 'package.json'), { name: '@prisma/client', type: 'module', main: './index.js' });
+    await writeFile(join(dir, 'node_modules', '@prisma', 'client', 'index.js'), 'export class PrismaClient {}\n', 'utf-8');
+
+    const PrismaClient = await importPrismaClientFromNodeModules({ dir });
+    assert.equal(typeof PrismaClient, 'function');
+    assert.equal(PrismaClient.name, 'PrismaClient');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('importPrismaClientFromGeneratedSqlite imports PrismaClient from generated/sqlite-client', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-prisma-import-'));
+  try {
+    await writeJson(join(dir, 'package.json'), { type: 'module' });
+    await mkdir(join(dir, 'generated', 'sqlite-client'), { recursive: true });
+    await writeFile(join(dir, 'generated', 'sqlite-client', 'index.js'), 'export class PrismaClient {}\n', 'utf-8');
+
+    const PrismaClient = await importPrismaClientFromGeneratedSqlite({ dir });
+    assert.equal(typeof PrismaClient, 'function');
+    assert.equal(PrismaClient.name, 'PrismaClient');
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('importPrismaClientForHappyServerLight prefers generated sqlite client when prisma/sqlite/schema.prisma exists', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-prisma-import-'));
+  try {
+    await writeJson(join(dir, 'package.json'), { type: 'module' });
+    await mkdir(join(dir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(dir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+
+    await mkdir(join(dir, 'generated', 'sqlite-client'), { recursive: true });
+    await writeFile(join(dir, 'generated', 'sqlite-client', 'index.js'), 'export class PrismaClient {}\n', 'utf-8');
+
+    // Also create a node_modules PrismaClient, but unified should prefer generated.
+    await mkdir(join(dir, 'node_modules', '@prisma', 'client'), { recursive: true });
+    await writeJson(join(dir, 'node_modules', '@prisma', 'client', 'package.json'), { name: '@prisma/client', type: 'module', main: './index.js' });
+    await writeFile(join(dir, 'node_modules', '@prisma', 'client', 'index.js'), 'export class PrismaClient { static which = "node_modules"; }\n', 'utf-8');
+
+    const PrismaClient = await importPrismaClientForHappyServerLight({ serverDir: dir });
+    assert.equal(typeof PrismaClient, 'function');
+    assert.equal(PrismaClient.name, 'PrismaClient');
+    // If we imported node_modules we'd have this static property.
+    assert.equal(PrismaClient.which, undefined);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/scripts/utils/server/ui_env.mjs

@@ -0,0 +1,14 @@
+export function resolveServerUiEnv({ serveUi, uiBuildDir, uiPrefix, uiBuildDirExists }) {
+  if (!serveUi) return {};
+  if (!uiBuildDirExists) return {};
+  if (!uiBuildDir) return {};
+
+  // Set both the canonical env vars (new) and legacy keys (for older server builds).
+  return {
+    HAPPY_SERVER_UI_DIR: uiBuildDir,
+    HAPPY_SERVER_UI_PREFIX: uiPrefix,
+    HAPPY_SERVER_LIGHT_UI_DIR: uiBuildDir,
+    HAPPY_SERVER_LIGHT_UI_PREFIX: uiPrefix,
+  };
+}
+

package/scripts/utils/server/ui_env.test.mjs

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { resolveServerUiEnv } from './ui_env.mjs';
+
+test('resolveServerUiEnv returns empty when UI serving is disabled', () => {
+  assert.deepEqual(
+    resolveServerUiEnv({
+      serveUi: false,
+      uiBuildDir: '/tmp/ui',
+      uiPrefix: '/',
+      uiBuildDirExists: true,
+    }),
+    {}
+  );
+});
+
+test('resolveServerUiEnv returns empty when UI build dir is missing', () => {
+  assert.deepEqual(
+    resolveServerUiEnv({
+      serveUi: true,
+      uiBuildDir: '/tmp/ui',
+      uiPrefix: '/',
+      uiBuildDirExists: false,
+    }),
+    {}
+  );
+});
+
+test('resolveServerUiEnv sets both canonical and legacy env keys when enabled', () => {
+  assert.deepEqual(
+    resolveServerUiEnv({
+      serveUi: true,
+      uiBuildDir: '/tmp/ui',
+      uiPrefix: '/ui',
+      uiBuildDirExists: true,
+    }),
+    {
+      HAPPY_SERVER_UI_DIR: '/tmp/ui',
+      HAPPY_SERVER_UI_PREFIX: '/ui',
+      HAPPY_SERVER_LIGHT_UI_DIR: '/tmp/ui',
+      HAPPY_SERVER_LIGHT_UI_PREFIX: '/ui',
+    }
+  );
+});
+

package/scripts/utils/server/urls.mjs

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 
 import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
 import { resolvePublicServerUrl } from '../../tailscale.mjs';
 import { resolveServerPortFromEnv } from './port.mjs';
+import { normalizeUrlNoTrailingSlash } from '../net/url.mjs';
 
 function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
   try {
@@ -31,14 +33,15 @@ function stackEnvExplicitlySetsWebappUrl({ env, stackName }) {
 }
 
 export function getPublicServerUrlEnvOverride({ env = process.env, serverPort, stackName = null } = {}) {
-  const defaultPublicUrl = `http://localhost:${serverPort}`;
   const name =
     (stackName ?? '').toString().trim() ||
     (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
-    getStackName();
+    getStackName(env);
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
 
   let envPublicUrl =
     (env.HAPPY_STACKS_SERVER_URL ?? env.HAPPY_LOCAL_SERVER_URL ?? '').toString().trim() || '';
+  envPublicUrl = normalizeUrlNoTrailingSlash(envPublicUrl);
 
   // Safety: for non-main stacks, ignore a global SERVER_URL unless it was explicitly set in the stack env file.
   if (name !== 'main' && envPublicUrl && !stackEnvExplicitlySetsPublicUrl({ env, stackName: name })) {
@@ -52,7 +55,7 @@ export function getWebappUrlEnvOverride({ env = process.env, stackName = null }
   const name =
     (stackName ?? '').toString().trim() ||
     (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
-    getStackName();
+    getStackName(env);
 
   let envWebappUrl = (env.HAPPY_WEBAPP_URL ?? '').toString().trim() || '';
 
@@ -66,18 +69,25 @@ export function getWebappUrlEnvOverride({ env = process.env, stackName = null }
 
 export async function resolveServerUrls({ env = process.env, serverPort, allowEnable = true } = {}) {
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const stackName =
+    (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
+    getStackName(env);
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env, serverPort });
   const resolved = await resolvePublicServerUrl({
     internalServerUrl,
     defaultPublicUrl,
     envPublicUrl,
     allowEnable,
+    stackName,
   });
+  const publicServerUrl = normalizeUrlNoTrailingSlash(
+    await preferStackLocalhostUrl(resolved.publicServerUrl, { stackName })
+  );
   return {
     internalServerUrl,
     defaultPublicUrl,
     envPublicUrl,
-    publicServerUrl: resolved.publicServerUrl,
+    publicServerUrl,
     publicServerUrlSource: resolved.source,
   };
 }

package/scripts/utils/server/validate.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { getComponentsDir } from '../paths/paths.mjs';
+import { getComponentRepoDir, getComponentsDir, isHappyMonorepoRoot } from '../paths/paths.mjs';
 
 function isInside(path, dir) {
   const p = resolve(path);
@@ -16,8 +16,14 @@ export function detectServerComponentDirMismatch({ rootDir, serverComponentName,
     return null;
   }
 
-  const otherRepo = resolve(componentsDir, other);
-  const otherWts = resolve(componentsDir, '.worktrees', other);
+  const expectedRepo = resolve(getComponentRepoDir(rootDir, serverComponentName));
+  const otherRepo = resolve(getComponentRepoDir(rootDir, other));
+  // Unified server flavors can legitimately share a single repo/dir.
+  if (expectedRepo === otherRepo) {
+    return null;
+  }
+  const otherKey = isHappyMonorepoRoot(otherRepo) ? 'happy' : other;
+  const otherWts = resolve(componentsDir, '.worktrees', otherKey);
 
   if (isInside(serverDir, otherRepo) || isInside(serverDir, otherWts)) {
     return { expected: serverComponentName, actual: other, serverDir };
@@ -32,10 +38,13 @@ export function assertServerComponentDirMatches({ rootDir, serverComponentName,
     return;
   }
 
+  const expectedRepoDir = getComponentRepoDir(rootDir, mismatch.expected);
+  const expectedRepoKey = isHappyMonorepoRoot(expectedRepoDir) ? 'happy' : mismatch.expected;
+
   const hint =
     mismatch.expected === 'happy-server-light'
-      ? 'Fix: either switch flavor (`happys srv use happy-server`) or switch the active checkout for happy-server-light (`happys wt use happy-server-light default` or a worktree under .worktrees/happy-server-light/).'
-      : 'Fix: either switch flavor (`happys srv use happy-server-light`) or switch the active checkout for happy-server (`happys wt use happy-server default` or a worktree under .worktrees/happy-server/).';
+      ? `Fix: either switch flavor (\`happys srv use happy-server\`) or switch the active checkout for happy-server-light (\`happys wt use happy-server-light default\` or a worktree under .worktrees/${expectedRepoKey}/).`
+      : `Fix: either switch flavor (\`happys srv use happy-server-light\`) or switch the active checkout for happy-server (\`happys wt use happy-server default\` or a worktree under .worktrees/${expectedRepoKey}/).`;
 
   throw new Error(
     `[server] server component dir mismatch:\n` +
@@ -55,6 +64,11 @@ function detectPrismaProvider(schemaText) {
 
 export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
   const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
+  const sqliteSchemaPaths = [
+    join(serverDir, 'prisma', 'sqlite', 'schema.prisma'),
+    join(serverDir, 'prisma', 'schema.sqlite.prisma'),
+  ];
+
   let schemaText = '';
   try {
     schemaText = readFileSync(schemaPath, 'utf-8');
@@ -64,17 +78,41 @@ export function assertServerPrismaProviderMatches({ serverComponentName, serverD
   }
 
   const provider = detectPrismaProvider(schemaText);
-  if (!provider) {
-    return;
-  }
+  if (!provider) return;
 
-  if (serverComponentName === 'happy-server-light' && provider !== 'sqlite') {
-    throw new Error(
-      `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
-        `- ${schemaPath}\n` +
-        `This usually means you're pointing happy-server-light at an upstream happy-server checkout/PR (Postgres).\n` +
-        `Fix: either switch server flavor to happy-server, or point happy-server-light at a fork checkout that keeps sqlite support.`
-    );
+  // Unified happy-server flavors:
+  // - full: prisma/schema.prisma (postgresql)
+  // - light: prisma/sqlite/schema.prisma (sqlite) (legacy: prisma/schema.sqlite.prisma)
+  if (serverComponentName === 'happy-server-light') {
+    for (const sqliteSchemaPath of sqliteSchemaPaths) {
+      try {
+        const sqliteSchemaText = readFileSync(sqliteSchemaPath, 'utf-8');
+        const sqliteProvider = detectPrismaProvider(sqliteSchemaText);
+        if (sqliteProvider && sqliteProvider !== 'sqlite') {
+          throw new Error(
+            `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${sqliteProvider}\" in:\n` +
+              `- ${sqliteSchemaPath}\n` +
+              `Fix: point happy-server-light at a checkout that includes sqlite support, or switch server flavor to happy-server.`
+          );
+        }
+        if (sqliteProvider === 'sqlite') {
+          return;
+        }
+        // Exists, but could not parse provider: keep checking other variants and fall through to legacy behavior.
+      } catch {
+        // missing/unreadable: try other variants and then fall through to legacy behavior below
+      }
+    }
+
+    if (provider !== 'sqlite') {
+      throw new Error(
+        `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
+          `- ${schemaPath}\n` +
+          `This usually means you're pointing happy-server-light at a postgres-only happy-server checkout/PR.\n` +
+          `Fix: either switch server flavor to happy-server, or use a checkout that supports the light flavor (e.g. one that contains prisma/sqlite/schema.prisma or prisma/schema.sqlite.prisma).`
+      );
+    }
+    return;
   }
 
   if (serverComponentName === 'happy-server' && provider === 'sqlite') {
@@ -85,4 +123,3 @@ export function assertServerPrismaProviderMatches({ serverComponentName, serverD
     );
   }
 }
-

package/scripts/utils/server/validate.test.mjs

@@ -0,0 +1,89 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { assertServerPrismaProviderMatches, detectServerComponentDirMismatch } from './validate.mjs';
+
+const PG_SCHEMA = `
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+`.trim();
+
+const SQLITE_SCHEMA = `
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+`.trim();
+
+async function writeSchemas({ dir, schemaPrisma, schemaSqlitePrisma }) {
+  const prismaDir = join(dir, 'prisma');
+  await mkdir(prismaDir, { recursive: true });
+  if (schemaPrisma != null) {
+    await writeFile(join(prismaDir, 'schema.prisma'), schemaPrisma + '\n', 'utf-8');
+  }
+  if (schemaSqlitePrisma != null) {
+    await mkdir(join(prismaDir, 'sqlite'), { recursive: true });
+    await writeFile(join(prismaDir, 'sqlite', 'schema.prisma'), schemaSqlitePrisma + '\n', 'utf-8');
+  }
+}
+
+test('assertServerPrismaProviderMatches accepts unified light flavor (prisma/sqlite/schema.prisma)', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-validate-'));
+  try {
+    await writeSchemas({ dir, schemaPrisma: PG_SCHEMA, schemaSqlitePrisma: SQLITE_SCHEMA });
+    assert.doesNotThrow(() => assertServerPrismaProviderMatches({ serverComponentName: 'happy-server-light', serverDir: dir }));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('assertServerPrismaProviderMatches rejects happy-server-light when only postgres schema exists', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-validate-'));
+  try {
+    await writeSchemas({ dir, schemaPrisma: PG_SCHEMA, schemaSqlitePrisma: null });
+    assert.throws(() => assertServerPrismaProviderMatches({ serverComponentName: 'happy-server-light', serverDir: dir }));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('assertServerPrismaProviderMatches rejects happy-server when schema.prisma is sqlite', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'hs-validate-'));
+  try {
+    await writeSchemas({ dir, schemaPrisma: SQLITE_SCHEMA, schemaSqlitePrisma: null });
+    assert.throws(() => assertServerPrismaProviderMatches({ serverComponentName: 'happy-server', serverDir: dir }));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('detectServerComponentDirMismatch allows unified happy-server-light pointing at happy-server dir', async () => {
+  const rootDir = await mkdtemp(join(tmpdir(), 'hs-validate-root-'));
+  const envKeys = ['HAPPY_STACKS_WORKSPACE_DIR', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT'];
+  const old = Object.fromEntries(envKeys.map((k) => [k, process.env[k]]));
+  try {
+    process.env.HAPPY_STACKS_WORKSPACE_DIR = rootDir;
+    const unifiedDir = join(rootDir, 'components', 'happy-server');
+    await mkdir(unifiedDir, { recursive: true });
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = unifiedDir;
+    process.env.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = unifiedDir;
+
+    const mismatch = detectServerComponentDirMismatch({
+      rootDir,
+      serverComponentName: 'happy-server-light',
+      serverDir: unifiedDir,
+    });
+    assert.equal(mismatch, null);
+  } finally {
+    for (const k of envKeys) {
+      if (old[k] == null) delete process.env[k];
+      else process.env[k] = old[k];
+    }
+    await rm(rootDir, { recursive: true, force: true });
+  }
+});

package/scripts/utils/service/autostart_darwin.mjs

@@ -1,15 +1,54 @@
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 
 import { runCapture } from '../proc/proc.mjs';
 import { getDefaultAutostartPaths } from '../paths/paths.mjs';
 import { resolveInstalledCliRoot, resolveInstalledPath } from '../paths/runtime.mjs';
+import { getCanonicalHomeDir } from '../env/config.mjs';
 
 function plistPathForLabel(label) {
   return join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
 }
 
+function splitPath(p) {
+  return String(p ?? '')
+    .split(':')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function buildLaunchdPath({ execPath = process.execPath, basePath = process.env.PATH } = {}) {
+  // launchd starts with a minimal environment; ensure common tool paths exist,
+  // and include the current Node binary directory so shell shims that exec `node`
+  // still work (e.g. nvm-managed installs).
+  const nodeDir = execPath ? dirname(execPath) : '';
+  const defaults = splitPath('/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin');
+  const fromNode = nodeDir ? [nodeDir] : [];
+  const fromEnv = splitPath(basePath);
+
+  const seen = new Set();
+  const out = [];
+  for (const part of [...fromNode, ...fromEnv, ...defaults]) {
+    if (seen.has(part)) continue;
+    seen.add(part);
+    out.push(part);
+  }
+  return out.join(':') || '/usr/bin:/bin:/usr/sbin:/sbin';
+}
+
+export function pickLaunchdProgramArgs({ rootDir, execPath = process.execPath } = {}) {
+  // Prefer the stable shim under the canonical home dir (used by selfhost installs).
+  // This keeps the LaunchAgent pointing at a stable path while allowing runtime updates.
+  const happysShim = join(getCanonicalHomeDir(), 'bin', 'happys');
+  if (existsSync(happysShim)) {
+    return [happysShim, 'start'];
+  }
+  // Fallback: call the Node entry directly (works in repo-only installs).
+  return [execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+}
+
 function xmlEscape(s) {
   return String(s ?? '')
     .replaceAll('&', '&')
@@ -72,11 +111,12 @@ export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
   await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
   await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
 
-  const programArgs = [process.execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+  const programArgs = pickLaunchdProgramArgs({ rootDir, execPath: process.execPath });
   const mergedEnv = {
     ...(env ?? {}),
     // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
-    PATH: (process.env.PATH ?? '').trim() || '/usr/bin:/bin:/usr/sbin:/sbin',
+    // Also ensure Node is on PATH for shell shims that exec `node` (common with nvm installs).
+    PATH: buildLaunchdPath({ execPath: process.execPath, basePath: process.env.PATH }),
   };
 
   const xml = plistXml({

package/scripts/utils/service/autostart_darwin.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { buildLaunchdPath, pickLaunchdProgramArgs } from './autostart_darwin.mjs';
+
+test('buildLaunchdPath includes node dir and common tool paths', () => {
+  const execPath = '/Users/me/.nvm/versions/node/v22.14.0/bin/node';
+  const p = buildLaunchdPath({ execPath, basePath: '' });
+
+  assert.ok(p.includes('/Users/me/.nvm/versions/node/v22.14.0/bin'), 'includes node dir');
+  assert.ok(p.includes('/usr/bin'), 'includes /usr/bin');
+  assert.ok(p.includes('/bin'), 'includes /bin');
+});
+
+test('pickLaunchdProgramArgs uses stable happys shim when present', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-home-'));
+  const shim = join(dir, 'bin', 'happys');
+  await mkdir(join(dir, 'bin'), { recursive: true });
+  await writeFile(shim, '#!/bin/sh\necho ok\n', { encoding: 'utf-8' });
+
+  // Temporarily point canonical home at our temp dir via env var used by getCanonicalHomeDirFromEnv().
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = dir;
+  try {
+    const args = pickLaunchdProgramArgs({ rootDir: '/fake/root' });
+    assert.deepEqual(args, [shim, 'start']);
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+
+test('pickLaunchdProgramArgs falls back to node + happys.mjs when shim missing', () => {
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = '/definitely-not-a-real-path';
+  try {
+    const execPath = '/usr/local/bin/node';
+    const args = pickLaunchdProgramArgs({ rootDir: '/cli/root', execPath });
+    assert.equal(args[0], execPath);
+    assert.ok(String(args[1]).endsWith('/bin/happys.mjs'));
+    assert.equal(args[2], 'start');
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+

package/scripts/utils/stack/context.mjs

@@ -3,12 +3,12 @@ import { getStackRuntimeStatePath } from './runtime_state.mjs';
 
 export function resolveStackContext({ env = process.env, autostart = null } = {}) {
   const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
-  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
   const stackMode = Boolean(explicitStack);
 
   const envPath =
     (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
-    resolveStackEnvPath(stackName).envPath;
+    resolveStackEnvPath(stackName, env).envPath;
 
   const runtimeStatePath =
     (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||

package/scripts/utils/stack/editor_workspace.mjs

@@ -2,7 +2,7 @@ import { join, resolve } from 'node:path';
 import { writeFile } from 'node:fs/promises';
 
 import { expandHome } from '../paths/canonical_home.mjs';
-import { getComponentDir, getWorkspaceDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { coerceHappyMonorepoRootFromPath, getComponentDir, getWorkspaceDir, resolveStackEnvPath } from '../paths/paths.mjs';
 import { ensureDir } from '../fs/ops.mjs';
 import { getEnvValueAny } from '../env/values.mjs';
 import { readEnvObjectFromFile } from '../env/read.mjs';
@@ -13,7 +13,7 @@ import { getCliHomeDirFromEnvOrDefault } from './dirs.mjs';
 function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
   const raw = getEnvValueAny(stackEnv, ['HAPPY_STACKS_WORKSPACE_DIR', 'HAPPY_LOCAL_WORKSPACE_DIR']);
   if (!raw) {
-    return getWorkspaceDir(rootDir);
+    return getWorkspaceDir(rootDir, stackEnv);
   }
   const expanded = expandHome(raw);
   return expanded.startsWith('/') ? expanded : resolve(rootDir, expanded);
@@ -21,7 +21,7 @@ function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
 
 function resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component }) {
   const raw = getEnvValueAny(stackEnv, keys);
-  if (!raw) return getComponentDir(rootDir, component);
+  if (!raw) return getComponentDir(rootDir, component, stackEnv);
   const expanded = expandHome(raw);
   if (expanded.startsWith('/')) return expanded;
   const workspaceDir = resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv });
@@ -108,8 +108,9 @@ export async function writeStackCodeWorkspace({
   }
   for (const component of selectedComponents) {
     const keys = byName.get(component) ?? [];
-    const dir = resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component });
-    folders.push({ name: component, path: dir });
+    const componentDir = resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component });
+    const monoRoot = coerceHappyMonorepoRootFromPath(componentDir);
+    folders.push({ name: component, path: monoRoot || componentDir });
   }
 
   // Deduplicate by path (can happen if multiple components are pointed at the same dir).
@@ -149,4 +150,3 @@ export async function writeStackCodeWorkspace({
     },
   };
 }
-