@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/service/autostart_darwin.mjs

@@ -0,0 +1,198 @@
+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 hstackShim = join(getCanonicalHomeDir(), 'bin', 'hstack');
+  if (existsSync(hstackShim)) {
+    return [hstackShim, 'start'];
+  }
+  // Fallback: call the Node entry directly (works in repo-only installs).
+  return [execPath, resolveInstalledPath(rootDir, 'bin/hstack.mjs'), 'start'];
+}
+
+function xmlEscape(s) {
+  return String(s ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function plistXml({ label, programArgs, env = {}, stdoutPath, stderrPath, workingDirectory }) {
+  const envEntries = Object.entries(env ?? {}).filter(([k, v]) => String(k).trim() && String(v ?? '').trim());
+  const programArgsXml = programArgs.map((a) => `      <string>${xmlEscape(a)}</string>`).join('\n');
+  const envXml = envEntries
+    .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  const workingDirXml = workingDirectory
+    ? `\n    <key>WorkingDirectory</key>\n    <string>${xmlEscape(workingDirectory)}</string>\n`
+    : '\n';
+
+  // IMPORTANT:
+  // We want launchd to restart the stack if it crashes, but not to spin in a tight loop when
+  // `hstack start` exits cleanly (e.g. it detects "already running").
+  //
+  // `KeepAlive` with `SuccessfulExit=false` means:
+  // - exit 0 => do not restart (success)
+  // - exit non-zero => restart (crash)
+  const keepAliveXml =
+    `\n    <key>KeepAlive</key>\n` +
+    `    <dict>\n` +
+    `      <key>SuccessfulExit</key>\n` +
+    `      <false/>\n` +
+    `    </dict>\n`;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(label)}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgsXml}
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+${keepAliveXml}
+${workingDirXml}    <key>StandardOutPath</key>
+    <string>${xmlEscape(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(stderrPath)}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+
+export function buildLaunchdPlistXml({ label, programArgs, env = {}, stdoutPath, stderrPath, workingDirectory }) {
+  return plistXml({ label, programArgs, env, stdoutPath, stderrPath, workingDirectory });
+}
+
+export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
+  if (process.platform !== 'darwin') {
+    throw new Error('[local] macOS autostart is only supported on Darwin');
+  }
+  const l = String(label ?? '').trim();
+  if (!l) throw new Error('[local] missing launchd label');
+
+  const plistPath = plistPathForLabel(l);
+  const { stdoutPath, stderrPath } = getDefaultAutostartPaths();
+  await mkdir(dirname(plistPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
+
+  const programArgs = pickLaunchdProgramArgs({ rootDir, execPath: process.execPath });
+  const mergedEnv = {
+    ...(env ?? {}),
+    // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
+    // 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 = buildLaunchdPlistXml({
+    label: l,
+    programArgs,
+    env: mergedEnv,
+    stdoutPath,
+    stderrPath,
+    workingDirectory: resolveInstalledCliRoot(rootDir),
+  });
+
+  const tmp = join(dirname(plistPath), `.tmp.${l}.${Date.now()}.plist`);
+  await writeFile(tmp, xml, 'utf-8');
+  await rename(tmp, plistPath);
+
+  // Best-effort load/enable; `scripts/service.mjs` has a more robust bootstrap fallback.
+  try {
+    await runCapture('launchctl', ['load', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+}
+
+export async function ensureMacAutostartDisabled({ label }) {
+  if (process.platform !== 'darwin') {
+    return;
+  }
+  const l = String(label ?? '').trim();
+  if (!l) return;
+  const plistPath = plistPathForLabel(l);
+
+  const uidRaw = Number(process.env.UID);
+  const uid = Number.isFinite(uidRaw) ? uidRaw : null;
+
+  try {
+    await runCapture('launchctl', ['unload', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+  try {
+    await runCapture('launchctl', ['unload', plistPath]);
+  } catch {
+    // ignore
+  }
+  if (uid != null) {
+    try {
+      await runCapture('launchctl', ['disable', `gui/${uid}/${l}`]);
+    } catch {
+      // ignore
+    }
+    try {
+      await runCapture('launchctl', ['bootout', `gui/${uid}`, plistPath]);
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    await runCapture('launchctl', ['remove', l]);
+  } catch {
+    // ignore
+  }
+}

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

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { buildLaunchdPath, pickLaunchdProgramArgs } from './autostart_darwin.mjs';
+
+function setEnvKey(t, key, value) {
+  const previous = process.env[key];
+  if (value == null) delete process.env[key];
+  else process.env[key] = value;
+  t.after(() => {
+    if (previous == null) delete process.env[key];
+    else process.env[key] = previous;
+  });
+}
+
+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 hstack shim when present', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-home-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  const shim = join(dir, 'bin', 'hstack');
+  await mkdir(join(dir, 'bin'), { recursive: true });
+  await writeFile(shim, '#!/bin/sh\necho ok\n', { encoding: 'utf-8' });
+
+  setEnvKey(t, 'HAPPIER_STACK_CANONICAL_HOME_DIR', dir);
+  const args = pickLaunchdProgramArgs({ rootDir: '/fake/root' });
+  assert.deepEqual(args, [shim, 'start']);
+});
+
+test('pickLaunchdProgramArgs falls back to node + hstack.mjs when shim missing', (t) => {
+  setEnvKey(t, 'HAPPIER_STACK_CANONICAL_HOME_DIR', '/definitely-not-a-real-path');
+  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/hstack.mjs'));
+  assert.equal(args[2], 'start');
+});

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

@@ -0,0 +1,19 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildLaunchdPlistXml } from './autostart_darwin.mjs';
+
+test('buildLaunchdPlistXml uses KeepAlive SuccessfulExit=false (avoid launchd restart loops on clean exits)', () => {
+  const xml = buildLaunchdPlistXml({
+    label: 'dev.happier.stack',
+    programArgs: ['/bin/echo', 'start'],
+    env: { HAPPIER_STACK_ENV_FILE: '/tmp/env' },
+    stdoutPath: '/tmp/out.log',
+    stderrPath: '/tmp/err.log',
+    workingDirectory: '/tmp',
+  });
+
+  assert.match(xml, /<key>KeepAlive<\/key>\s*<dict>/m);
+  assert.match(xml, /<key>SuccessfulExit<\/key>\s*<false\/>/m);
+});
+

package/scripts/utils/stack/cli_identities.mjs

@@ -0,0 +1,29 @@
+import { dirname, join } from 'node:path';
+
+const IDENTITY_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+
+export function parseCliIdentityOrThrow(raw) {
+  const v = (raw ?? '').toString().trim();
+  if (!v || v === 'default') return 'default';
+  if (!IDENTITY_RE.test(v)) {
+    throw new Error(
+      `[stack] invalid --identity=${JSON.stringify(v)}. ` +
+        `Expected: "default" or a short name matching ${IDENTITY_RE} (max 64 chars).`
+    );
+  }
+  return v;
+}
+
+export function resolveCliHomeDirForIdentity({ cliHomeDir, identity }) {
+  const id = parseCliIdentityOrThrow(identity);
+  if (id === 'default') return cliHomeDir;
+
+  // Keep identities adjacent to the stack's default cli home dir:
+  //   <...>/<stack>/cli              (default)
+  //   <...>/<stack>/cli-identities/<id>
+  //
+  // If the stack overrides cliHomeDir to a custom path, we keep the same layout
+  // relative to that path's parent directory.
+  const baseDir = dirname(cliHomeDir);
+  return join(baseDir, 'cli-identities', id);
+}

package/scripts/utils/stack/context.mjs

@@ -0,0 +1,19 @@
+import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getStackRuntimeStatePath } from './runtime_state.mjs';
+
+export function resolveStackContext({ env = process.env, autostart = null } = {}) {
+  const explicitStack = (env.HAPPIER_STACK_STACK ?? '').toString().trim();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPIER_STACK_ENV_FILE ?? '').toString().trim() || resolveStackEnvPath(stackName, env).envPath;
+
+  const runtimeStatePath =
+    (env.HAPPIER_STACK_RUNTIME_STATE_PATH ?? '').toString().trim() || getStackRuntimeStatePath(stackName);
+
+  const explicitEphemeral = (env.HAPPIER_STACK_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+  const ephemeral = explicitEphemeral || (stackMode && stackName !== 'main');
+
+  return { stackMode, stackName, envPath, runtimeStatePath, ephemeral };
+}

package/scripts/utils/stack/dirs.mjs

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+
+export function getCliHomeDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPIER_STACK_CLI_HOME_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'cli');
+}
+
+export function getServerLightDataDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPIER_SERVER_LIGHT_DATA_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'server-light');
+}
+
+export function resolveCliHomeDir(env = process.env) {
+  const fromExplicit = (env.HAPPIER_HOME_DIR ?? '').trim();
+  if (fromExplicit) {
+    return expandHome(fromExplicit);
+  }
+  const fromStacks = (env.HAPPIER_STACK_CLI_HOME_DIR ?? '').trim();
+  if (fromStacks) {
+    return expandHome(fromStacks);
+  }
+  return join(getDefaultAutostartPaths().baseDir, 'cli');
+}

package/scripts/utils/stack/editor_workspace.mjs

@@ -0,0 +1,126 @@
+import { join, resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getComponentDir, getRepoDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { ensureDir } from '../fs/ops.mjs';
+import { getEnvValueAny } from '../env/values.mjs';
+import { readEnvObjectFromFile } from '../env/read.mjs';
+import { resolveCommandPath } from '../proc/commands.mjs';
+import { run, runCapture } from '../proc/proc.mjs';
+import { getCliHomeDirFromEnvOrDefault } from './dirs.mjs';
+
+export async function isCursorInstalled({ cwd, env } = {}) {
+  if (await resolveCommandPath('cursor', { cwd, env })) return true;
+  if (process.platform !== 'darwin') return false;
+  try {
+    await runCapture('open', ['-Ra', 'Cursor'], { cwd, env });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function openWorkspaceInEditor({ rootDir, editor, workspacePath }) {
+  if (editor === 'code') {
+    const codePath = await resolveCommandPath('code', { cwd: rootDir, env: process.env });
+    if (!codePath) {
+      throw new Error(
+        "[stack] VS Code CLI 'code' not found on PATH. In VS Code: Cmd+Shift+P → 'Shell Command: Install code command in PATH'."
+      );
+    }
+    await run(codePath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  const cursorPath = await resolveCommandPath('cursor', { cwd: rootDir, env: process.env });
+  if (cursorPath) {
+    try {
+      await run(cursorPath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    } catch {
+      await run(cursorPath, [workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    }
+    return;
+  }
+
+  if (process.platform === 'darwin') {
+    // Cursor installed but CLI missing is common on macOS.
+    await run('open', ['-na', 'Cursor', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  throw new Error("[stack] Cursor CLI 'cursor' not found on PATH (and non-macOS fallback is unavailable).");
+}
+
+export async function writeStackCodeWorkspace({
+  rootDir,
+  stackName,
+  includeStackDir,
+  includeAllComponents,
+  includeCliHome,
+}) {
+  const { baseDir, envPath } = resolveStackEnvPath(stackName);
+  const stackEnv = await readEnvObjectFromFile(envPath);
+
+  const serverComponent =
+    getEnvValueAny(stackEnv, ['HAPPIER_STACK_SERVER_COMPONENT']) || 'happier-server-light';
+
+  const folders = [];
+  if (includeStackDir) {
+    folders.push({ name: `stack:${stackName}`, path: baseDir });
+  }
+  if (includeCliHome) {
+    const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir: baseDir, env: stackEnv });
+    folders.push({ name: `cli:${stackName}`, path: expandHome(cliHomeDir) });
+  }
+  // Repo-only model: stacks pin a single monorepo checkout/worktree via HAPPIER_STACK_REPO_DIR.
+  const repoRoot = getRepoDir(rootDir, stackEnv);
+  folders.push({ name: 'repo', path: repoRoot });
+
+  // Optional convenience: include service subfolders for easier IDE scoping.
+  if (includeAllComponents) {
+    const uiDir = getComponentDir(rootDir, 'happier-ui', stackEnv);
+    const cliDir = getComponentDir(rootDir, 'happier-cli', stackEnv);
+    const serverDir = getComponentDir(rootDir, serverComponent, stackEnv);
+    folders.push({ name: 'ui', path: uiDir });
+    folders.push({ name: 'cli', path: cliDir });
+    folders.push({ name: 'server', path: serverDir });
+  }
+
+  // Deduplicate by path (can happen if multiple components are pointed at the same dir).
+  const uniqFolders = folders.filter((f, i, arr) => arr.findIndex((x) => x.path === f.path) === i);
+
+  await ensureDir(baseDir);
+  const workspacePath = join(baseDir, `stack.${stackName}.code-workspace`);
+  const payload = {
+    folders: uniqFolders,
+    settings: {
+      'search.exclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+      'files.watcherExclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+    },
+  };
+  await writeFile(workspacePath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+
+  return {
+    workspacePath,
+    baseDir,
+    envPath,
+    serverComponent,
+    folders: uniqFolders,
+    flags: {
+      includeStackDir: Boolean(includeStackDir),
+      includeCliHome: Boolean(includeCliHome),
+      includeAllComponents: Boolean(includeAllComponents),
+    },
+  };
+}