@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/stack/interactive_stack_config.mjs

@@ -0,0 +1,266 @@
+import { prompt, promptSelect, promptWorktreeSource } from '../cli/wizard.mjs';
+import { gitCapture, gitOk } from '../git/git.mjs';
+import { parseGithubOwnerRepo } from '../git/worktrees.mjs';
+import { getRepoDir } from '../paths/paths.mjs';
+import { cyan, dim, green } from '../ui/ansi.mjs';
+import { sectionTitle, warn } from '../ui/layout.mjs';
+import { normalizeStackNameOrNull } from './names.mjs';
+
+function wantsNo(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  return v === 'n' || v === 'no' || v === '0' || v === 'false';
+}
+
+async function promptStackName({ rl } = {}) {
+  while (true) {
+    // eslint-disable-next-line no-await-in-loop
+    const raw = (await rl.question(`${dim('Stack name')}: `)).trim();
+    const normalized = normalizeStackNameOrNull(raw);
+    if (!normalized) {
+      // eslint-disable-next-line no-console
+      console.log(warn('Invalid stack name. Use lowercase letters/numbers/hyphens (example: my-stack).'));
+      continue;
+    }
+    if (normalized === 'main') {
+      // eslint-disable-next-line no-console
+      console.log(warn('Stack name "main" is reserved. Use the default stack without creating it.'));
+      continue;
+    }
+
+    const trimmedLower = raw.trim().toLowerCase();
+    if (normalized !== trimmedLower) {
+      // eslint-disable-next-line no-console
+      console.log(warn(`Normalized stack name to ${cyan(normalized)}.`));
+    }
+    return normalized;
+  }
+}
+
+function parsePortOrNull(raw) {
+  const trimmed = String(raw ?? '').trim();
+  if (!trimmed) return { ok: true, kind: 'empty', port: null };
+  const token = trimmed.toLowerCase();
+  if (token === 'ephemeral') return { ok: true, kind: 'ephemeral', port: null };
+  if (!/^\d+$/.test(token)) return { ok: false, kind: 'invalid', port: null };
+  const n = Number(token);
+  if (!Number.isFinite(n) || n <= 0 || n > 65535) return { ok: false, kind: 'invalid', port: null };
+  return { ok: true, kind: 'port', port: n };
+}
+
+async function promptPort({ rl, promptFn, label, defaultValue = '' } = {}) {
+  while (true) {
+    // eslint-disable-next-line no-await-in-loop
+    const raw = await promptFn(rl, label, { defaultValue });
+    const parsed = parsePortOrNull(raw);
+    if (parsed.ok) return { raw, parsed };
+    // eslint-disable-next-line no-console
+    console.log(warn(`Invalid port: "${String(raw ?? '').trim()}". Enter a number (1-65535), or leave empty.`));
+  }
+}
+
+function normalizeRemoteNameOrNull(raw) {
+  const v = String(raw ?? '').trim();
+  if (!v) return null;
+  // Remote names should be safe identifiers and should not be interpreted as flags by `git remote ...`.
+  // Allow namespaced remotes (e.g. "team/upstream") while avoiding ambiguous path-like forms.
+  if (!/^(?!.*\/\/)(?!.*\/$)[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(v)) return null;
+  return v;
+}
+
+async function promptRemoteName({ rl, promptFn, label, defaultValue = '' } = {}) {
+  while (true) {
+    // eslint-disable-next-line no-await-in-loop
+    const raw = await promptFn(rl, label, { defaultValue });
+    const trimmed = String(raw ?? '').trim();
+    const fallback = String(defaultValue ?? '').trim();
+    const normalized = normalizeRemoteNameOrNull(trimmed === '' && fallback !== '' ? fallback : trimmed);
+    if (normalized) return normalized;
+    // eslint-disable-next-line no-console
+    console.log(
+      warn(
+        `Invalid git remote name: "${String(raw ?? '').trim()}". Use letters/numbers/dot/underscore/hyphen/slash (example: upstream or team/upstream).`
+      )
+    );
+  }
+}
+
+async function describeGitRemote({ repoDir, remote }) {
+  const r = String(remote ?? '').trim();
+  if (!repoDir || !r) return '';
+  try {
+    const url = (await gitCapture({ cwd: repoDir, args: ['remote', 'get-url', r] })).trim();
+    if (!url) return '';
+    const parsed = parseGithubOwnerRepo(url);
+    return parsed ? `${parsed.owner}/${parsed.repo}` : url;
+  } catch {
+    return '';
+  }
+}
+
+async function resolveDefaultCreateRemote({ repoDir }) {
+  // Prefer upstream when present (clean PR history), else fall back to origin.
+  if (await gitOk({ cwd: repoDir, args: ['remote', 'get-url', 'upstream'] })) return 'upstream';
+  if (await gitOk({ cwd: repoDir, args: ['remote', 'get-url', 'origin'] })) return 'origin';
+  return 'upstream';
+}
+
+export async function interactiveNew({ rootDir, rl, defaults, deps = {} }) {
+  const promptFn = deps.prompt ?? prompt;
+  const promptSelectFn = deps.promptSelect ?? promptSelect;
+  const promptWorktreeSourceFn = deps.promptWorktreeSource ?? promptWorktreeSource;
+
+  const out = { ...defaults };
+
+  if (!out.stackName) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(sectionTitle('Create a stack'));
+    // eslint-disable-next-line no-console
+    console.log(dim('Stacks are isolated local environments (ports + dirs + DB + CLI home).'));
+    out.stackName = await promptStackName({ rl });
+  }
+  if (!out.stackName) {
+    throw new Error('[stack] stack name is required');
+  }
+  {
+    const normalized = normalizeStackNameOrNull(out.stackName);
+    if (!normalized) {
+      throw new Error('[stack] stack name is invalid');
+    }
+    if (normalized === 'main') {
+      throw new Error('[stack] stack name "main" is reserved');
+    }
+    out.stackName = normalized;
+  }
+
+  if (!out.serverComponent) {
+    out.serverComponent = await promptSelectFn(rl, {
+      title: `${sectionTitle('Server flavor')}\n${dim('Pick the backend this stack should run. You can switch later with `stack srv`.')}`,
+      options: [
+        { label: `happier-server-light (${green('recommended')}) — simplest local install (PG_Light via embedded PGlite)`, value: 'happier-server-light' },
+        { label: `happier-server — full server (Postgres/Redis/Minio via Docker)`, value: 'happier-server' },
+      ],
+      defaultIndex: 0,
+    });
+  }
+
+  if (!out.port) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(sectionTitle('Ports'));
+    // eslint-disable-next-line no-console
+    console.log(dim('Tip: leaving this empty uses an ephemeral port (recommended for non-main stacks).'));
+    // Accept "ephemeral" explicitly, and reprompt on invalid input.
+    const { parsed } = await promptPort({
+      rl,
+      promptFn,
+      label: `${dim('Port')} (empty = ephemeral; type 'ephemeral' to unpin): `,
+      defaultValue: '',
+    });
+    out.port = parsed.port;
+  }
+
+  if (!out.createRemote) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(sectionTitle('Worktrees'));
+    const mainDir = getRepoDir(rootDir, { ...process.env, HAPPIER_STACK_REPO_DIR: '' });
+    const upstreamRepo = await describeGitRemote({ repoDir: mainDir, remote: 'upstream' });
+    const originRepo = await describeGitRemote({ repoDir: mainDir, remote: 'origin' });
+    const defaultRemote = await resolveDefaultCreateRemote({ repoDir: mainDir });
+
+    // eslint-disable-next-line no-console
+    console.log(
+      dim(`New worktrees are typically based on ${cyan('upstream')}${upstreamRepo ? ` (${upstreamRepo})` : ''} (clean PR history).`)
+    );
+    if (upstreamRepo || originRepo) {
+      // eslint-disable-next-line no-console
+      console.log(dim(`Remotes: ${upstreamRepo ? `upstream=${upstreamRepo}` : 'upstream=(missing)'}, ${originRepo ? `origin=${originRepo}` : 'origin=(missing)'}`));
+    }
+
+    out.createRemote = await promptRemoteName({
+      rl,
+      promptFn,
+      label: `${dim('Git remote for new worktrees')} (default: ${defaultRemote}): `,
+      defaultValue: defaultRemote,
+    });
+  }
+
+  if (out.repo == null) {
+    // NOTE: promptWorktreeSource is still component-named internally; for hstack, this is the monorepo checkout.
+    out.repo = await promptWorktreeSourceFn({
+      rl,
+      rootDir,
+      component: 'happier-ui',
+      stackName: out.stackName,
+      createRemote: out.createRemote,
+    });
+  }
+
+  return out;
+}
+
+export async function interactiveEdit({ rootDir, rl, stackName, existingEnv, defaults, deps = {} }) {
+  const promptFn = deps.prompt ?? prompt;
+  const promptSelectFn = deps.promptSelect ?? promptSelect;
+  const promptWorktreeSourceFn = deps.promptWorktreeSource ?? promptWorktreeSource;
+
+  const out = { ...defaults, stackName };
+
+  const currentServer = existingEnv.HAPPIER_STACK_SERVER_COMPONENT ?? '';
+  out.serverComponent = await promptSelectFn(rl, {
+    title: `${sectionTitle('Server flavor')}\n${dim('Pick the backend this stack should run. You can switch again later.')}`,
+    options: [
+      { label: `happier-server-light (${green('recommended')}) — simplest local install (PG_Light via embedded PGlite)`, value: 'happier-server-light' },
+      { label: `happier-server — full server (Postgres/Redis/Minio via Docker)`, value: 'happier-server' },
+    ],
+    defaultIndex: (currentServer || 'happier-server-light') === 'happier-server' ? 1 : 0,
+  });
+
+  const currentPort = existingEnv.HAPPIER_STACK_SERVER_PORT ?? '';
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(sectionTitle('Ports'));
+  const { parsed } = await promptPort({
+    rl,
+    promptFn,
+    label: `${dim(`Port`)} (empty = keep ${currentPort || 'ephemeral'}; type 'ephemeral' to unpin): `,
+    defaultValue: '',
+  });
+  const existingPort = currentPort ? Number(currentPort) : null;
+  out.port = parsed.kind === 'empty' ? (Number.isFinite(existingPort) ? existingPort : null) : parsed.port;
+
+  const currentRemote = existingEnv.HAPPIER_STACK_STACK_REMOTE ?? '';
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(sectionTitle('Worktrees'));
+  const mainDir = getRepoDir(rootDir, { ...process.env, HAPPIER_STACK_REPO_DIR: '' });
+  const upstreamRepo = await describeGitRemote({ repoDir: mainDir, remote: 'upstream' });
+  const originRepo = await describeGitRemote({ repoDir: mainDir, remote: 'origin' });
+  if (upstreamRepo || originRepo) {
+    // eslint-disable-next-line no-console
+    console.log(dim(`Remotes: ${upstreamRepo ? `upstream=${upstreamRepo}` : 'upstream=(missing)'}, ${originRepo ? `origin=${originRepo}` : 'origin=(missing)'}`));
+  }
+  const defaultRemote = (currentRemote || (await resolveDefaultCreateRemote({ repoDir: mainDir })) || 'upstream').trim();
+  out.createRemote = await promptRemoteName({
+    rl,
+    promptFn,
+    label: `${dim('Git remote for new worktrees')} (default: ${defaultRemote}): `,
+    defaultValue: defaultRemote,
+  });
+
+  out.repo = await promptWorktreeSourceFn({
+    rl,
+    rootDir,
+    component: 'happier-ui',
+    stackName,
+    createRemote: out.createRemote,
+  });
+
+  return out;
+}

package/scripts/utils/stack/interactive_stack_config.port_validation.test.mjs

@@ -0,0 +1,93 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { interactiveEdit, interactiveNew } from './interactive_stack_config.mjs';
+import { createInteractiveStackConfigDeps, mkRl } from './interactive_stack_config_testkit.mjs';
+
+test('interactiveNew reprompts when port input is invalid', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const rootDir = '/tmp/hstack-root';
+  const rl = mkRl(['not-a-number', '4242']);
+
+  const out = await interactiveNew({
+    rootDir,
+    rl,
+    defaults: {
+      stackName: 'exp-port-validate',
+      port: null,
+      serverComponent: 'happier-server-light',
+      createRemote: 'upstream',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps(),
+  });
+
+  assert.equal(out.port, 4242);
+});
+
+test('interactiveEdit reprompts when port input is invalid and allows empty to keep current port', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const rootDir = '/tmp/hstack-root';
+  const rl = mkRl([]);
+
+  const prompted = [];
+  const out = await interactiveEdit({
+    rootDir,
+    rl,
+    stackName: 'exp-edit-port-validate',
+    existingEnv: {
+      HAPPIER_STACK_SERVER_COMPONENT: 'happier-server-light',
+      HAPPIER_STACK_SERVER_PORT: '4101',
+      HAPPIER_STACK_STACK_REMOTE: 'upstream',
+    },
+    defaults: {},
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        prompted.push(String(question));
+        if (String(question).includes('Port')) {
+          const idx = prompted.filter((q) => q.includes('Port')).length;
+          return idx === 1 ? 'abc' : '';
+        }
+        return defaultValue ?? '';
+      },
+    }),
+  });
+
+  assert.equal(out.port, 4101);
+});
+
+test('interactiveNew accepts explicit "ephemeral" token for unpinned port', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl(['ephemeral']),
+    defaults: {
+      stackName: 'exp-port-ephemeral',
+      port: null,
+      serverComponent: 'happier-server-light',
+      createRemote: 'upstream',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps(),
+  });
+  assert.equal(out.port, null);
+});
+
+test('interactiveEdit treats malformed existing port as ephemeral when input is empty', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveEdit({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl([]),
+    stackName: 'exp-edit-port-malformed',
+    existingEnv: {
+      HAPPIER_STACK_SERVER_COMPONENT: 'happier-server-light',
+      HAPPIER_STACK_SERVER_PORT: 'not-a-port',
+      HAPPIER_STACK_STACK_REMOTE: 'upstream',
+    },
+    defaults: {},
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, _question, { defaultValue } = {}) => defaultValue ?? '',
+    }),
+  });
+  assert.equal(out.port, null);
+});

package/scripts/utils/stack/interactive_stack_config.remote_validation.test.mjs

@@ -0,0 +1,122 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { interactiveEdit, interactiveNew } from './interactive_stack_config.mjs';
+import { createInteractiveStackConfigDeps, mkRl } from './interactive_stack_config_testkit.mjs';
+
+test('interactiveNew reprompts when createRemote input is invalid', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const asked = [];
+  let remoteAnswers = 0;
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl([]),
+    defaults: {
+      stackName: 'exp-remote-validate',
+      port: 4101,
+      serverComponent: 'happier-server-light',
+      createRemote: '',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        asked.push(String(question));
+        if (String(question).includes('Git remote for new worktrees')) {
+          remoteAnswers += 1;
+          return remoteAnswers === 1 ? 'bad remote' : 'upstream';
+        }
+        return defaultValue ?? '';
+      },
+    }),
+  });
+
+  assert.ok(asked.some((q) => q.includes('Git remote for new worktrees')));
+  assert.equal(out.createRemote, 'upstream');
+});
+
+test('interactiveEdit reprompts when createRemote input is invalid', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  let remoteAnswers = 0;
+  const out = await interactiveEdit({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl([]),
+    stackName: 'exp-edit-remote-validate',
+    existingEnv: {
+      HAPPIER_STACK_SERVER_COMPONENT: 'happier-server-light',
+      HAPPIER_STACK_SERVER_PORT: '4101',
+      HAPPIER_STACK_STACK_REMOTE: 'origin',
+    },
+    defaults: {},
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        if (String(question).includes('Git remote for new worktrees')) {
+          remoteAnswers += 1;
+          return remoteAnswers === 1 ? 'bad remote' : 'upstream';
+        }
+        if (String(question).includes('Port')) {
+          return '';
+        }
+        return defaultValue ?? '';
+      },
+    }),
+  });
+
+  assert.equal(out.createRemote, 'upstream');
+});
+
+test('interactiveEdit keeps current remote when prompt answer is empty', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveEdit({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl([]),
+    stackName: 'exp-edit-remote-default',
+    existingEnv: {
+      HAPPIER_STACK_SERVER_COMPONENT: 'happier-server-light',
+      HAPPIER_STACK_SERVER_PORT: '4101',
+      HAPPIER_STACK_STACK_REMOTE: 'origin',
+    },
+    defaults: {},
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        if (String(question).includes('Git remote for new worktrees')) {
+          return '';
+        }
+        if (String(question).includes('Port')) {
+          return '';
+        }
+        return defaultValue ?? '';
+      },
+    }),
+  });
+
+  assert.equal(out.createRemote, 'origin');
+});
+
+test('interactiveNew accepts slash in createRemote input', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  let remoteAnswers = 0;
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl([]),
+    defaults: {
+      stackName: 'exp-remote-slash',
+      port: 4101,
+      serverComponent: 'happier-server-light',
+      createRemote: '',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps({
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        if (String(question).includes('Git remote for new worktrees')) {
+          remoteAnswers += 1;
+          if (remoteAnswers > 1) throw new Error('unexpected remote reprompt');
+          return 'team/upstream';
+        }
+        return defaultValue ?? '';
+      },
+    }),
+  });
+
+  assert.equal(remoteAnswers, 1);
+  assert.equal(out.createRemote, 'team/upstream');
+});

package/scripts/utils/stack/interactive_stack_config.stack_name_validation.test.mjs

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { interactiveNew } from './interactive_stack_config.mjs';
+import { createInteractiveStackConfigDeps, mkRl } from './interactive_stack_config_testkit.mjs';
+
+test('interactiveNew normalizes stackName to a DNS-safe label', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl(['My Stack']),
+    defaults: {
+      stackName: '',
+      port: 4101,
+      serverComponent: 'happier-server-light',
+      createRemote: 'upstream',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps(),
+  });
+  assert.equal(out.stackName, 'my-stack');
+});
+
+test('interactiveNew reprompts when stackName is reserved or sanitizes to empty', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl(['main', '----', 'ok-stack']),
+    defaults: {
+      stackName: '',
+      port: 4101,
+      serverComponent: 'happier-server-light',
+      createRemote: 'upstream',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps(),
+  });
+  assert.equal(out.stackName, 'ok-stack');
+});
+
+test('interactiveNew rejects prefilled reserved stackName', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  await assert.rejects(
+    () =>
+      interactiveNew({
+        rootDir: '/tmp/hstack-root',
+        rl: mkRl([]),
+        defaults: {
+          stackName: 'main',
+          port: 4101,
+          serverComponent: 'happier-server-light',
+          createRemote: 'upstream',
+          repo: 'default',
+        },
+        deps: createInteractiveStackConfigDeps(),
+      }),
+    /reserved/i
+  );
+});
+
+test('interactiveNew reprompts when stackName exceeds max length', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const out = await interactiveNew({
+    rootDir: '/tmp/hstack-root',
+    rl: mkRl(['a'.repeat(64), 'max-len-ok']),
+    defaults: {
+      stackName: '',
+      port: 4101,
+      serverComponent: 'happier-server-light',
+      createRemote: 'upstream',
+      repo: 'default',
+    },
+    deps: createInteractiveStackConfigDeps(),
+  });
+  assert.equal(out.stackName, 'max-len-ok');
+});

package/scripts/utils/stack/interactive_stack_config_testkit.mjs

@@ -0,0 +1,18 @@
+export function mkRl(answers = []) {
+  let index = 0;
+  return {
+    question: async () => {
+      const value = answers[index] ?? '';
+      index += 1;
+      return String(value);
+    },
+  };
+}
+
+export function createInteractiveStackConfigDeps(overrides = {}) {
+  return {
+    promptSelect: async (_rl, { options, defaultIndex = 0 }) => options?.[defaultIndex]?.value,
+    promptWorktreeSource: async () => 'default',
+    ...overrides,
+  };
+}

package/scripts/utils/stack/names.mjs

@@ -0,0 +1,27 @@
+export function sanitizeStackName(raw, { fallback = 'stack', maxLen = 64 } = {}) {
+  const s = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  const out = s || String(fallback ?? 'stack');
+  return Number.isFinite(maxLen) && maxLen > 0 ? out.slice(0, maxLen) : out;
+}
+
+export function normalizeStackNameOrNull(raw, { maxLen = 63 } = {}) {
+  const trimmed = String(raw ?? '').trim();
+  if (!trimmed) return null;
+
+  const normalized = String(trimmed)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+
+  if (!normalized) return null;
+  if (Number.isFinite(maxLen) && maxLen > 0 && normalized.length > maxLen) return null;
+  return normalized;
+}

package/scripts/utils/stack/names.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { normalizeStackNameOrNull } from './names.mjs';
+
+test('normalizeStackNameOrNull normalizes to a DNS-safe label', () => {
+  assert.equal(normalizeStackNameOrNull('My Stack'), 'my-stack');
+});
+
+test('normalizeStackNameOrNull returns null when the name sanitizes to empty', () => {
+  assert.equal(normalizeStackNameOrNull('----'), null);
+});
+
+test('normalizeStackNameOrNull returns null when the name exceeds maxLen', () => {
+  const long = 'a'.repeat(64);
+  assert.equal(normalizeStackNameOrNull(long), null);
+});
+
+test('normalizeStackNameOrNull accepts a 63-character DNS-safe label', () => {
+  const max = 'a'.repeat(63);
+  assert.equal(normalizeStackNameOrNull(max), max);
+});
+
+test('normalizeStackNameOrNull collapses punctuation runs into single separators', () => {
+  assert.equal(normalizeStackNameOrNull('My__Stack...Name'), 'my-stack-name');
+});

package/scripts/utils/stack/pr_stack_name.mjs

@@ -0,0 +1,16 @@
+import { parseGithubPullRequest } from '../git/refs.mjs';
+import { sanitizeStackName } from './names.mjs';
+
+export function inferPrStackBaseName({ happy, happyCli, server, serverLight, fallback = 'pr' }) {
+  const parts = [];
+  const hn = parseGithubPullRequest(happy)?.number ?? null;
+  const cn = parseGithubPullRequest(happyCli)?.number ?? null;
+  const sn = parseGithubPullRequest(server)?.number ?? null;
+  const sln = parseGithubPullRequest(serverLight)?.number ?? null;
+  if (hn) parts.push(`happy${hn}`);
+  if (cn) parts.push(`cli${cn}`);
+  if (sn) parts.push(`server${sn}`);
+  if (sln) parts.push(`light${sln}`);
+  return sanitizeStackName(parts.length ? `pr-${parts.join('-')}` : fallback, { fallback, maxLen: 64 });
+}
+