happy-stacks 0.4.0 → 0.5.0

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/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/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';
@@ -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({
     },
   };
 }
-

package/scripts/utils/stack/interactive_stack_config.mjs

@@ -0,0 +1,185 @@
+import { join, resolve } from 'node:path';
+
+import { prompt, promptWorktreeSource } from '../cli/wizard.mjs';
+import { coerceHappyMonorepoRootFromPath, getComponentsDir } from '../paths/paths.mjs';
+import { resolveComponentSpecToDir } from '../git/worktrees.mjs';
+
+function wantsNo(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  return v === 'n' || v === 'no' || v === '0' || v === 'false';
+}
+
+function resolveHappySpecDir({ rootDir, spec }) {
+  if (!spec) return '';
+  if (spec === 'default' || spec === 'main') {
+    return join(getComponentsDir(rootDir), 'happy');
+  }
+  if (typeof spec === 'string') {
+    const dir = resolveComponentSpecToDir({ rootDir, component: 'happy', spec });
+    return dir ? resolve(rootDir, dir) : '';
+  }
+  return '';
+}
+
+export async function interactiveNew({ rootDir, rl, defaults, deps = {} }) {
+  const promptFn = deps.prompt ?? prompt;
+  const promptWorktreeSourceFn = deps.promptWorktreeSource ?? promptWorktreeSource;
+
+  const out = { ...defaults };
+
+  if (!out.stackName) {
+    out.stackName = (await rl.question('Stack name: ')).trim();
+  }
+  if (!out.stackName) {
+    throw new Error('[stack] stack name is required');
+  }
+  if (out.stackName === 'main') {
+    throw new Error('[stack] stack name "main" is reserved (use the default stack without creating it)');
+  }
+
+  if (!out.serverComponent) {
+    const server = (await rl.question('Server component [happy-server-light|happy-server] (default: happy-server-light): ')).trim();
+    out.serverComponent = server || 'happy-server-light';
+  }
+
+  if (!out.port) {
+    const want = (await rl.question('Port (empty = ephemeral): ')).trim();
+    out.port = want ? Number(want) : null;
+  }
+
+  if (!out.createRemote) {
+    out.createRemote = await promptFn(rl, 'Git remote for creating new worktrees (default: upstream): ', { defaultValue: 'upstream' });
+  }
+
+  if (out.components.happy == null) {
+    out.components.happy = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: 'happy',
+      stackName: out.stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  const happyIsCreate = Boolean(out.components.happy && typeof out.components.happy === 'object' && out.components.happy.create);
+  const happyMonoRoot = coerceHappyMonorepoRootFromPath(resolveHappySpecDir({ rootDir, spec: out.components.happy }));
+  const canDeriveMonorepoGroup = Boolean(happyMonoRoot) || happyIsCreate;
+  let deriveMonorepoGroup = false;
+
+  if (canDeriveMonorepoGroup) {
+    const ans = await promptFn(rl, 'Detected happy monorepo checkout. Derive happy-cli + happy-server from it? [Y/n]: ', {
+      defaultValue: 'y',
+    });
+    deriveMonorepoGroup = !wantsNo(ans);
+  }
+
+  if (deriveMonorepoGroup) {
+    out.components['happy-cli'] = null;
+    out.components['happy-server'] = null;
+    // In monorepo mode, happy-server-light is derived when supported by the monorepo server checkout.
+    // If not supported, the stack env will keep the default separate happy-server-light checkout.
+    out.components['happy-server-light'] = null;
+  } else if (out.components['happy-cli'] == null) {
+    out.components['happy-cli'] = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: 'happy-cli',
+      stackName: out.stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
+  if (serverComponent === 'happy-server-light' && deriveMonorepoGroup) {
+    out.components['happy-server-light'] = null;
+    return out;
+  }
+  if (serverComponent === 'happy-server' && deriveMonorepoGroup) {
+    out.components['happy-server'] = null;
+  } else if (out.components[serverComponent] == null) {
+    out.components[serverComponent] = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: serverComponent,
+      stackName: out.stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  return out;
+}
+
+export async function interactiveEdit({ rootDir, rl, stackName, existingEnv, defaults, deps = {} }) {
+  const promptFn = deps.prompt ?? prompt;
+  const promptWorktreeSourceFn = deps.promptWorktreeSource ?? promptWorktreeSource;
+
+  const out = { ...defaults, stackName };
+
+  const currentServer = existingEnv.HAPPY_STACKS_SERVER_COMPONENT ?? existingEnv.HAPPY_LOCAL_SERVER_COMPONENT ?? '';
+  const server = await promptFn(rl, `Server component [happy-server-light|happy-server] (default: ${currentServer || 'happy-server-light'}): `, {
+    defaultValue: currentServer || 'happy-server-light',
+  });
+  out.serverComponent = server || 'happy-server-light';
+
+  const currentPort = existingEnv.HAPPY_STACKS_SERVER_PORT ?? existingEnv.HAPPY_LOCAL_SERVER_PORT ?? '';
+  const wantPort = await promptFn(rl, `Port (empty = keep ${currentPort || 'ephemeral'}; type 'ephemeral' to unpin): `, { defaultValue: '' });
+  const wantTrimmed = wantPort.trim().toLowerCase();
+  out.port = wantTrimmed === 'ephemeral' ? null : wantPort ? Number(wantPort) : currentPort ? Number(currentPort) : null;
+
+  const currentRemote = existingEnv.HAPPY_STACKS_STACK_REMOTE ?? existingEnv.HAPPY_LOCAL_STACK_REMOTE ?? '';
+  out.createRemote = await promptFn(rl, `Git remote for creating new worktrees (default: ${currentRemote || 'upstream'}): `, {
+    defaultValue: currentRemote || 'upstream',
+  });
+
+  out.components.happy = await promptWorktreeSourceFn({
+    rl,
+    rootDir,
+    component: 'happy',
+    stackName,
+    createRemote: out.createRemote,
+  });
+
+  const happyIsCreate = Boolean(out.components.happy && typeof out.components.happy === 'object' && out.components.happy.create);
+  const happyMonoRoot = coerceHappyMonorepoRootFromPath(resolveHappySpecDir({ rootDir, spec: out.components.happy }));
+  const canDeriveMonorepoGroup = Boolean(happyMonoRoot) || happyIsCreate;
+  let deriveMonorepoGroup = false;
+  if (canDeriveMonorepoGroup) {
+    const ans = await promptFn(rl, 'Detected happy monorepo checkout. Derive happy-cli + happy-server from it? [Y/n]: ', {
+      defaultValue: 'y',
+    });
+    deriveMonorepoGroup = !wantsNo(ans);
+  }
+
+  if (deriveMonorepoGroup) {
+    out.components['happy-cli'] = null;
+    out.components['happy-server'] = null;
+    out.components['happy-server-light'] = null;
+  } else if (out.components['happy-cli'] == null) {
+    out.components['happy-cli'] = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: 'happy-cli',
+      stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
+  if (serverComponent === 'happy-server-light' && deriveMonorepoGroup) {
+    out.components['happy-server-light'] = null;
+    return out;
+  }
+  if (serverComponent === 'happy-server' && deriveMonorepoGroup) {
+    out.components['happy-server'] = null;
+  } else {
+    out.components[serverComponent] = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: serverComponent,
+      stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  return out;
+}