happy-stacks 0.1.2 → 0.3.0

package/scripts/utils/fs/ops.mjs

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+
+export async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+export async function readTextIfExists(path) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return null;
+    const raw = await readFile(p, 'utf-8');
+    const t = raw.trim();
+    return t ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readTextOrEmpty(path) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return '';
+    return await readFile(p, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+

package/scripts/utils/fs/package_json.mjs

@@ -0,0 +1,8 @@
+import { readJsonIfExists } from './json.mjs';
+
+export async function readPackageJsonVersion(path) {
+  const pkg = await readJsonIfExists(path, { defaultValue: null });
+  const v = String(pkg?.version ?? '').trim();
+  return v || null;
+}
+

package/scripts/utils/fs/tail.mjs

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+
+export async function readLastLines(path, lines = 60) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    const parts = raw.split('\n');
+    return parts.slice(Math.max(0, parts.length - lines)).join('\n');
+  } catch {
+    return null;
+  }
+}
+

package/scripts/utils/git/refs.mjs

@@ -0,0 +1,26 @@
+export function parseGithubPullRequest(input) {
+  const raw = (input ?? '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) {
+    return { number: Number(raw), owner: null, repo: null };
+  }
+  // https://github.com/<owner>/<repo>/pull/<num>
+  const m = raw.match(/github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)\/pull\/(?<num>\d+)/);
+  if (!m?.groups?.num) return null;
+  return {
+    number: Number(m.groups.num),
+    owner: m.groups.owner ?? null,
+    repo: m.groups.repo ?? null,
+  };
+}
+
+export function sanitizeSlugPart(s) {
+  return (s ?? '')
+    .toString()
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._/-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+

package/scripts/utils/{worktrees.mjs → git/worktrees.mjs}

@@ -1,8 +1,8 @@
 import { readdir } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
-import { getComponentsDir } from './paths.mjs';
-import { pathExists } from './fs.mjs';
-import { run, runCapture } from './proc.mjs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { getComponentsDir } from '../paths/paths.mjs';
+import { pathExists } from '../fs/fs.mjs';
+import { run, runCapture } from '../proc/proc.mjs';
 
 export function parseGithubOwner(remoteUrl) {
   const raw = (remoteUrl ?? '').trim();
@@ -23,6 +23,62 @@ export function componentRepoDir(rootDir, component) {
   return join(getComponentsDir(rootDir), component);
 }
 
+export function isComponentWorktreePath({ rootDir, component, dir }) {
+  const raw = String(dir ?? '').trim();
+  if (!raw) return false;
+  const abs = resolve(raw);
+  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  return abs.startsWith(root);
+}
+
+export function worktreeSpecFromDir({ rootDir, component, dir }) {
+  const raw = String(dir ?? '').trim();
+  if (!raw) return null;
+  if (!isComponentWorktreePath({ rootDir, component, dir: raw })) return null;
+  const abs = resolve(raw);
+  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  const rel = abs.slice(root.length).split('/').filter(Boolean);
+  if (rel.length < 2) return null;
+  // rel = [owner, ...branchParts]
+  return rel.join('/');
+}
+
+export async function inferRemoteNameForOwner({ repoDir, owner }) {
+  const want = String(owner ?? '').trim();
+  if (!want) return 'upstream';
+
+  const candidates = ['upstream', 'origin', 'fork'];
+  for (const remoteName of candidates) {
+    try {
+      const url = (await runCapture('git', ['remote', 'get-url', remoteName], { cwd: repoDir })).trim();
+      const o = parseGithubOwner(url);
+      if (o && o === want) {
+        return remoteName;
+      }
+    } catch {
+      // ignore missing remote
+    }
+  }
+  return 'upstream';
+}
+
+export async function createWorktreeFromBaseWorktree({
+  rootDir,
+  component,
+  slug,
+  baseWorktreeSpec,
+  remoteName = 'upstream',
+  depsMode = '',
+}) {
+  const args = ['wt', 'new', component, slug, `--remote=${remoteName}`, `--base-worktree=${baseWorktreeSpec}`];
+  if (depsMode) args.push(`--deps=${depsMode}`);
+  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), ...args], { cwd: rootDir });
+
+  const repoDir = componentRepoDir(rootDir, component);
+  const owner = await getRemoteOwner({ repoDir, remoteName });
+  return join(getWorktreesRoot(rootDir), component, owner, ...slug.split('/'));
+}
+
 export function resolveComponentSpecToDir({ rootDir, component, spec }) {
   const raw = (spec ?? '').trim();
   if (!raw || raw === 'default') {

package/scripts/utils/net/dns.mjs

@@ -0,0 +1,10 @@
+export function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
+  const s = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return s || fallback;
+}
+

package/scripts/utils/{ports.mjs → net/ports.mjs}

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import net from 'node:net';
-import { runCapture } from './proc.mjs';
+import { runCaptureIfCommandExists } from '../proc/commands.mjs';
 
 async function listListenPids(port) {
   if (!Number.isFinite(port) || port <= 0) return [];
@@ -9,10 +9,7 @@ async function listListenPids(port) {
   let raw = '';
   try {
     // `lsof` exits non-zero if no matches; normalize to empty output.
-    raw = await runCapture('sh', [
-      '-lc',
-      `command -v lsof >/dev/null 2>&1 && lsof -nP -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null || true`,
-    ]);
+    raw = await runCaptureIfCommandExists('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
   } catch {
     raw = '';
   }
@@ -102,3 +99,4 @@ export async function pickNextFreeTcpPort(startPort, { reservedPorts = new Set()
   }
   throw new Error(`[local] unable to find a free TCP port starting at ${startPort}`);
 }
+

package/scripts/utils/paths/canonical_home.mjs

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function expandHome(p) {
+  return String(p ?? '').replace(/^~(?=\/)/, homedir());
+}
+
+export function getCanonicalHomeDirFromEnv(env = process.env) {
+  const fromEnv = (
+    (env.HAPPY_STACKS_CANONICAL_HOME_DIR ?? '').trim() ||
+    (env.HAPPY_LOCAL_CANONICAL_HOME_DIR ?? '').trim() ||
+    ''
+  );
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
+}
+
+export function getCanonicalHomeEnvPathFromEnv(env = process.env) {
+  return join(getCanonicalHomeDirFromEnv(env), '.env');
+}
+

package/scripts/utils/paths/localhost_host.mjs

@@ -0,0 +1,9 @@
+import { getStackName } from './paths.mjs';
+import { sanitizeDnsLabel } from '../net/dns.mjs';
+
+export function resolveLocalhostHost({ stackMode, stackName = getStackName() } = {}) {
+  if (!stackMode) return 'localhost';
+  if (!stackName || stackName === 'main') return 'localhost';
+  return `happy-${sanitizeDnsLabel(stackName)}.localhost`;
+}
+

package/scripts/utils/{paths.mjs → paths/paths.mjs}

@@ -3,6 +3,9 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 
+import { expandHome } from './canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
+
 const PRIMARY_APP_SLUG = 'happy-stacks';
 const LEGACY_APP_SLUG = 'happy-local';
 const PRIMARY_LABEL_BASE = 'com.happy.stacks';
@@ -15,10 +18,10 @@ export function getRootDir(importMetaUrl) {
   return dirname(dirname(fileURLToPath(importMetaUrl)));
 }
 
-export function getHappyStacksHomeDir() {
-  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
+export function getHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_HOME_DIR;
 }
@@ -26,7 +29,7 @@ export function getHappyStacksHomeDir() {
 export function getWorkspaceDir(cliRootDir = null) {
   const fromEnv = (process.env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   const homeDir = getHappyStacksHomeDir();
   const defaultWorkspace = join(homeDir, 'workspace');
@@ -52,7 +55,7 @@ function normalizePathForEnv(rootDir, raw) {
   if (!trimmed) {
     return '';
   }
-  const expanded = trimmed.replace(/^~(?=\/)/, homedir());
+  const expanded = expandHome(trimmed);
   // If the path is relative, treat it as relative to the workspace root (default: repo root).
   const workspaceDir = getWorkspaceDir(rootDir);
   return expanded.startsWith('/') ? expanded : resolve(workspaceDir, expanded);
@@ -88,7 +91,7 @@ export function getLegacyStackLabel(stackName = getStackName()) {
 export function getStacksStorageRoot() {
   const fromEnv = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_STORAGE_ROOT;
 }
@@ -101,12 +104,13 @@ export function resolveStackBaseDir(stackName = getStackName()) {
   const preferredRoot = getStacksStorageRoot();
   const newBase = join(preferredRoot, stackName);
   const legacyBase = stackName === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', stackName);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   // Prefer the new layout by default.
   //
   // For non-main stacks, keep legacy layout if the legacy env exists and the new env does not.
   // This avoids breaking existing stacks until `happys stack migrate` is run.
-  if (stackName !== 'main') {
+  if (allowLegacy && stackName !== 'main') {
     const newEnv = join(preferredRoot, stackName, 'env');
     const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
     if (!existsSync(newEnv) && existsSync(legacyEnv)) {
@@ -123,11 +127,12 @@ export function resolveStackEnvPath(stackName = getStackName()) {
   const newEnv = join(getStacksStorageRoot(), stackName, 'env');
   // Legacy layout: ~/.happy/local/stacks/<name>/env
   const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   if (existsSync(newEnv)) {
     return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
   }
-  if (existsSync(legacyEnv)) {
+  if (allowLegacy && existsSync(legacyEnv)) {
     return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
   }
   return { envPath: newEnv, isLegacy, baseDir: activeBase };
@@ -182,3 +187,4 @@ export function getDefaultAutostartPaths() {
     legacyStderrPath,
   };
 }
+

package/scripts/utils/{runtime.mjs → paths/runtime.mjs}

@@ -2,16 +2,16 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { expandHome } from './canonical_home.mjs';
 
 export function getRuntimeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim();
   if (fromEnv) {
     return expandHome(fromEnv);
   }
-  const homeDir = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() ? expandHome(process.env.HAPPY_STACKS_HOME_DIR.trim()) : join(homedir(), '.happy-stacks');
+  const homeDir = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim()
+    ? expandHome(process.env.HAPPY_STACKS_HOME_DIR.trim())
+    : join(homedir(), '.happy-stacks');
   return join(homeDir, 'runtime');
 }
 

package/scripts/utils/proc/commands.mjs

@@ -0,0 +1,34 @@
+import { runCapture } from './proc.mjs';
+
+export async function resolveCommandPath(cmd, { cwd, env, timeoutMs } = {}) {
+  const c = String(cmd ?? '').trim();
+  if (!c) return '';
+
+  try {
+    if (process.platform === 'win32') {
+      const out = (await runCapture('where', [c], { cwd, env, timeoutMs })).trim();
+      const first = out.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || '';
+      return first;
+    }
+    return (
+      await runCapture('sh', ['-lc', `command -v "${c}" 2>/dev/null || true`], { cwd, env, timeoutMs })
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function runCaptureIfCommandExists(cmd, args, { cwd, env, timeoutMs } = {}) {
+  const resolved = await resolveCommandPath(cmd, { cwd, env, timeoutMs });
+  if (!resolved) return '';
+  try {
+    return await runCapture(resolved, args, { cwd, env, timeoutMs });
+  } catch {
+    return '';
+  }
+}
+
+export async function commandExists(cmd, { cwd } = {}) {
+  return Boolean(await resolveCommandPath(cmd, { cwd }));
+}
+

package/scripts/utils/proc/ownership.mjs

@@ -0,0 +1,135 @@
+import { runCapture } from './proc.mjs';
+import { killPid } from '../expo/expo.mjs';
+
+export async function getPsEnvLine(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['eww', '-p', String(n)]);
+    // Output usually includes a header line and then a single process line.
+    const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return lines[1];
+    if (lines.length === 1) return lines[0];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listPidsWithEnvNeedle(needle) {
+  const n = String(needle ?? '').trim();
+  if (!n) return [];
+  if (process.platform === 'win32') return [];
+  try {
+    // Include environment variables (eww) so we can match on HAPPY_STACKS_ENV_FILE=/.../env safely.
+    const out = await runCapture('ps', ['eww', '-ax', '-o', 'pid=,command=']);
+    const pids = [];
+    for (const line of out.split('\n')) {
+      if (!line.includes(n)) continue;
+      const m = line.trim().match(/^(\d+)\s+/);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      if (Number.isFinite(pid) && pid > 1) {
+        pids.push(pid);
+      }
+    }
+    return Array.from(new Set(pids));
+  } catch {
+    return [];
+  }
+}
+
+export async function getProcessGroupId(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['-o', 'pgid=', '-p', String(n)]);
+    const raw = out.trim();
+    const pgid = raw ? Number(raw) : NaN;
+    return Number.isFinite(pgid) && pgid > 1 ? pgid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir } = {}) {
+  const line = await getPsEnvLine(pid);
+  if (!line) return false;
+  const sn = String(stackName ?? '').trim();
+  const ep = String(envPath ?? '').trim();
+  const ch = String(cliHomeDir ?? '').trim();
+
+  // Require at least one stack identifier.
+  const hasStack =
+    (sn && (line.includes(`HAPPY_STACKS_STACK=${sn}`) || line.includes(`HAPPY_LOCAL_STACK=${sn}`))) ||
+    (!sn && (line.includes('HAPPY_STACKS_STACK=') || line.includes('HAPPY_LOCAL_STACK=')));
+  if (!hasStack) return false;
+
+  // Prefer env-file binding (strongest).
+  if (ep) {
+    if (line.includes(`HAPPY_STACKS_ENV_FILE=${ep}`) || line.includes(`HAPPY_LOCAL_ENV_FILE=${ep}`)) {
+      return true;
+    }
+  }
+
+  // Fallback: CLI home dir binding (useful for daemon-related processes).
+  if (ch) {
+    if (line.includes(`HAPPY_HOME_DIR=${ch}`) || line.includes(`HAPPY_STACKS_CLI_HOME_DIR=${ch}`) || line.includes(`HAPPY_LOCAL_CLI_HOME_DIR=${ch}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function killPidOwnedByStack(pid, { stackName, envPath, cliHomeDir, label = 'process', json = false } = {}) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  await killPid(pid);
+  return { killed: true, reason: 'killed' };
+}
+
+export async function killProcessGroupOwnedByStack(
+  pid,
+  { stackName, envPath, cliHomeDir, label = 'process-group', json = false, signal = 'SIGTERM' } = {}
+) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  const pgid = await getProcessGroupId(pid);
+  if (!pgid) {
+    await killPid(pid);
+    return { killed: true, reason: 'killed_pid_only' };
+  }
+  try {
+    process.kill(-pgid, signal);
+  } catch {
+    // ignore
+  }
+  // Escalate if still alive.
+  try {
+    process.kill(pid, 0);
+    try {
+      process.kill(-pgid, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+  } catch {
+    // exited
+  }
+  return { killed: true, reason: 'killed_pgid', pgid };
+}
+

package/scripts/utils/proc/package_scripts.mjs

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { pathExists } from '../fs/fs.mjs';
+import { requirePnpm } from './pm.mjs';
+
+export async function detectPackageManagerCmd(dir) {
+  if (await pathExists(join(dir, 'yarn.lock'))) {
+    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
+  }
+  await requirePnpm();
+  return { name: 'pnpm', cmd: 'pnpm', argsForScript: (script) => ['--silent', script] };
+}
+
+export async function readPackageJsonScripts(dir) {
+  try {
+    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    return scripts;
+  } catch {
+    return null;
+  }
+}
+
+export function pickFirstScript(scripts, candidates) {
+  if (!scripts) return null;
+  const list = Array.isArray(candidates) ? candidates : [];
+  return list.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+}
+

package/scripts/utils/proc/pids.mjs

@@ -0,0 +1,11 @@
+export function isPidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+