@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/expo/metro_ports.mjs

@@ -0,0 +1,101 @@
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
+
+function hashStringToInt(s) {
+  let h = 0;
+  const str = String(s ?? '');
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 31 + str.charCodeAt(i)) >>> 0;
+  }
+  return h >>> 0;
+}
+
+function coercePositiveInt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function resolveStablePortStart({
+  env = process.env,
+  stackName,
+  baseKey,
+  rangeKey,
+  defaultBase,
+  defaultRange,
+}) {
+  const baseRaw = (env[baseKey] ?? '').toString().trim();
+  const rangeRaw = (env[rangeKey] ?? '').toString().trim();
+  const base = coercePositiveInt(baseRaw) ?? defaultBase;
+  const range = coercePositiveInt(rangeRaw) ?? defaultRange;
+  return base + (hashStringToInt(stackName) % range);
+}
+
+export async function pickMetroPort({
+  startPort,
+  forcedPort,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forced = coercePositiveInt(forcedPort);
+  if (forced && !reservedPorts.has(forced)) {
+    const ok = await isTcpPortFree(forced, { host });
+    if (ok) return forced;
+  }
+  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+}
+
+export function wantsStablePortStrategy({ env = process.env, strategyKey, legacyStrategyKey } = {}) {
+  void legacyStrategyKey;
+  const raw = (env[strategyKey] ?? 'ephemeral').toString().trim() || 'ephemeral';
+  return raw === 'stable';
+}
+
+export async function pickUiDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: UI dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickMobileDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: mobile dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickExpoDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forcedPort = (env.HAPPIER_STACK_EXPO_DEV_PORT ?? '').toString().trim() || '';
+
+  const stable =
+    stackMode &&
+    wantsStablePortStrategy({
+      env,
+      strategyKey: 'HAPPIER_STACK_EXPO_DEV_PORT_STRATEGY',
+    });
+  const startPort = stable
+    ? resolveStablePortStart({
+        env,
+        stackName,
+        baseKey: 'HAPPIER_STACK_EXPO_DEV_PORT_BASE',
+        rangeKey: 'HAPPIER_STACK_EXPO_DEV_PORT_RANGE',
+        defaultBase: 8081,
+        defaultRange: 1000,
+      })
+    : 8081;
+
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
+}

package/scripts/utils/expo/metro_ports.test.mjs

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+
+import { pickMetroPort } from './metro_ports.mjs';
+
+function listenEphemeralPort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (!addr || typeof addr === 'string') {
+        srv.close(() => reject(new Error('failed to allocate port')));
+        return;
+      }
+      const port = Number(addr.port);
+      srv.close((err) => {
+        if (err) reject(err);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+test('pickMetroPort does not reuse forced port when it is reserved', async () => {
+  const forced = await listenEphemeralPort();
+  const picked = await pickMetroPort({
+    startPort: forced,
+    forcedPort: String(forced),
+    reservedPorts: new Set([forced]),
+    host: '127.0.0.1',
+  });
+  assert.notEqual(picked, forced);
+});

package/scripts/utils/fs/atomic_dir_swap.mjs

@@ -0,0 +1,55 @@
+import { mkdir, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+function rand() {
+  return Math.random().toString(16).slice(2);
+}
+
+export async function buildIntoTempThenReplace(targetDir, buildFn) {
+  const outDir = String(targetDir ?? '').trim();
+  if (!outDir) throw new Error('[fs] buildIntoTempThenReplace: missing targetDir');
+  if (typeof buildFn !== 'function') throw new Error('[fs] buildIntoTempThenReplace: buildFn must be a function');
+
+  const parent = dirname(outDir);
+  const tmpDir = join(parent, `.tmp.${Date.now()}.${process.pid}.${rand()}`);
+
+  await rm(tmpDir, { recursive: true, force: true });
+  await mkdir(tmpDir, { recursive: true });
+
+  let ok = false;
+  try {
+    await buildFn(tmpDir);
+    ok = true;
+  } finally {
+    if (!ok) {
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  // Swap only after a successful build.
+  const backupDir = join(parent, `.backup.${Date.now()}.${process.pid}.${rand()}`);
+  let hadExisting = false;
+  try {
+    await rename(outDir, backupDir);
+    hadExisting = true;
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+
+  try {
+    await rename(tmpDir, outDir);
+  } catch (err) {
+    if (hadExisting) {
+      await rename(backupDir, outDir).catch((restoreErr) => {
+        if (err && typeof err === 'object') {
+          err.restoreError = restoreErr;
+        }
+      });
+    }
+    throw err;
+  }
+
+  if (hadExisting) {
+    await rm(backupDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/scripts/utils/fs/atomic_dir_swap.test.mjs

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { buildIntoTempThenReplace } from './atomic_dir_swap.mjs';
+
+async function withTempRoot(t) {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-atomic-dir-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+  return root;
+}
+
+test('buildIntoTempThenReplace preserves existing dir when build fails', async (t) => {
+  const root = await withTempRoot(t);
+  const outDir = join(root, 'ui');
+  await mkdir(outDir, { recursive: true });
+  await writeFile(join(outDir, 'marker.txt'), 'old\n', 'utf-8');
+
+  await assert.rejects(
+    async () => {
+      await buildIntoTempThenReplace(outDir, async (tmp) => {
+        await writeFile(join(tmp, 'marker.txt'), 'new\n', 'utf-8');
+        throw new Error('boom');
+      });
+    },
+    /boom/
+  );
+
+  const after = await readFile(join(outDir, 'marker.txt'), 'utf-8');
+  assert.equal(after, 'old\n');
+});
+
+test('buildIntoTempThenReplace replaces dir on success', async (t) => {
+  const root = await withTempRoot(t);
+  const outDir = join(root, 'ui');
+  await mkdir(outDir, { recursive: true });
+  await writeFile(join(outDir, 'marker.txt'), 'old\n', 'utf-8');
+
+  await buildIntoTempThenReplace(outDir, async (tmp) => {
+    await writeFile(join(tmp, 'marker.txt'), 'new\n', 'utf-8');
+  });
+
+  const after = await readFile(join(outDir, 'marker.txt'), 'utf-8');
+  assert.equal(after, 'new\n');
+});
+
+test('buildIntoTempThenReplace validates required arguments', async () => {
+  await assert.rejects(async () => buildIntoTempThenReplace('', async () => {}), /missing targetDir/i);
+  await assert.rejects(async () => buildIntoTempThenReplace('/tmp/out', null), /buildFn must be a function/i);
+});

package/scripts/utils/fs/file_has_content.mjs

@@ -0,0 +1,10 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+export function fileHasContent(path) {
+  try {
+    if (!existsSync(path)) return false;
+    return readFileSync(path, 'utf-8').trim().length > 0;
+  } catch {
+    return false;
+  }
+}

package/scripts/utils/fs/fs.mjs

@@ -0,0 +1,11 @@
+import { access } from 'node:fs/promises';
+
+export async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+

package/scripts/utils/fs/json.mjs

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+
+export async function readJsonIfExists(path, { defaultValue = null } = {}) {
+  try {
+    const p = String(path ?? '').trim();
+    if (!p || !existsSync(p)) return defaultValue;
+    const raw = await readFile(p, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return defaultValue;
+  }
+}
+
+export async function writeJsonAtomic(path, value) {
+  const p = String(path ?? '').trim();
+  if (!p) throw new Error('writeJsonAtomic: path is required');
+  const dir = dirname(p);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}.json`);
+  await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+  await rename(tmp, p);
+}
+

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/dev_checkout.mjs

@@ -0,0 +1,127 @@
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getDevRepoDir, getRepoDir } from '../paths/paths.mjs';
+import { runCapture } from '../proc/proc.mjs';
+
+async function gitHasRemote({ repoDir, remote }) {
+  try {
+    const r = String(remote ?? '').trim();
+    if (!r) return false;
+    await runCapture('git', ['remote', 'get-url', r], { cwd: repoDir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveDevBranchName(env = process.env) {
+  return String(env.HAPPIER_STACK_DEV_BRANCH ?? '').trim() || 'dev';
+}
+
+async function getRemoteUrl({ repoDir, remoteName }) {
+  const r = String(remoteName ?? '').trim();
+  if (!r) return '';
+  try {
+    return (await runCapture('git', ['remote', 'get-url', r], { cwd: repoDir })).trim();
+  } catch {
+    return '';
+  }
+}
+
+// Remote used to *read* the canonical dev branch from (sync/reset defaults).
+export async function resolveDevSyncRemote({ repoDir, env = process.env, preferred = '' } = {}) {
+  const want = String(preferred ?? '').trim();
+  if (want) return want;
+
+  // Default preference: upstream (if configured), else origin.
+  if (await gitHasRemote({ repoDir, remote: 'upstream' })) return 'upstream';
+  if (await gitHasRemote({ repoDir, remote: 'origin' })) return 'origin';
+  return '';
+}
+
+// Remote used to *push* feature branches to (extract defaults).
+// Conventional git behavior: push to origin (fork), PR against upstream.
+export async function resolveDevPushRemote({ repoDir, env = process.env, preferred = '' } = {}) {
+  const want = String(preferred ?? '').trim();
+  if (want) return want;
+
+  if (await gitHasRemote({ repoDir, remote: 'origin' })) return 'origin';
+  if (await gitHasRemote({ repoDir, remote: 'upstream' })) return 'upstream';
+  return '';
+}
+
+export async function ensureDevCheckout({ rootDir, env = process.env, remote = '' } = {}) {
+  const mainDir = getRepoDir(rootDir, { ...env, HAPPIER_STACK_REPO_DIR: '' });
+  const devDir = getDevRepoDir(rootDir, env);
+  const devBranch = resolveDevBranchName(env);
+
+  if (!existsSync(mainDir) || !existsSync(join(mainDir, '.git'))) {
+    throw new Error(`[dev] missing main checkout at ${mainDir}\nFix: run \`hstack bootstrap --clone\` (or \`hstack setup\`).`);
+  }
+
+  const syncRemote = await resolveDevSyncRemote({ repoDir: mainDir, env, preferred: remote });
+  if (!syncRemote) {
+    throw new Error(`[dev] missing git remotes in ${mainDir}\nFix: ensure at least one of {upstream, origin} exists.`);
+  }
+
+  const preferred = String(remote ?? '').trim();
+  const hasUpstream = await gitHasRemote({ repoDir: mainDir, remote: 'upstream' });
+  const hasOrigin = await gitHasRemote({ repoDir: mainDir, remote: 'origin' });
+  let trackingRemote = preferred;
+  if (!trackingRemote) {
+    // Maintainership UX:
+    // Contributor UX:
+    // - if origin differs from upstream, assume origin is a fork and track origin/dev (pushable).
+    // - otherwise, track upstream/dev (canonical).
+    if (hasUpstream && hasOrigin) {
+      const upstreamUrl = await getRemoteUrl({ repoDir: mainDir, remoteName: 'upstream' });
+      const originUrl = await getRemoteUrl({ repoDir: mainDir, remoteName: 'origin' });
+      trackingRemote = upstreamUrl && originUrl && upstreamUrl !== originUrl ? 'origin' : 'upstream';
+    } else if (hasOrigin) {
+      trackingRemote = 'origin';
+    } else if (hasUpstream) {
+      trackingRemote = 'upstream';
+    } else {
+      trackingRemote = syncRemote;
+    }
+  }
+
+  // Already exists: treat as ok, but report the actual tracking remote best-effort.
+  if (existsSync(devDir) && existsSync(join(devDir, '.git'))) {
+    let inferred = '';
+    try {
+      const upstreamRef = (await runCapture('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], { cwd: devDir })).trim();
+      inferred = upstreamRef.split('/')[0] ?? '';
+    } catch {
+      inferred = '';
+    }
+    return { ok: true, created: false, mainDir, devDir, devBranch, syncRemote, trackingRemote: inferred || trackingRemote };
+  }
+
+  await mkdir(devDir, { recursive: true }).catch(() => {});
+
+  // Create/overwrite a local branch "dev" from <remote>/<devBranch>, then add the worktree.
+  // NOTE: `-B` resets the local branch name to the requested start-point (safe for a fresh workspace).
+  const startPoint = `${trackingRemote}/${devBranch}`;
+  try {
+    await runCapture('git', ['fetch', trackingRemote, devBranch], { cwd: mainDir });
+  } catch (e) {
+    // Common contributor case: origin points to a fresh fork that doesn't have dev yet.
+    // Best-effort: seed origin/dev from upstream/dev (or the chosen sync remote).
+    if (trackingRemote === 'origin' && syncRemote && syncRemote !== 'origin') {
+      await runCapture('git', ['fetch', syncRemote, devBranch], { cwd: mainDir });
+      await runCapture('git', ['push', 'origin', `refs/remotes/${syncRemote}/${devBranch}:refs/heads/${devBranch}`], { cwd: mainDir });
+      await runCapture('git', ['fetch', 'origin', devBranch], { cwd: mainDir });
+    } else {
+      throw e;
+    }
+  }
+
+  await runCapture('git', ['worktree', 'add', '-B', devBranch, devDir, startPoint], { cwd: mainDir });
+  // Ensure the branch explicitly tracks the chosen remote for clarity (git status shows upstream correctly).
+  await runCapture('git', ['-C', devDir, 'branch', '--set-upstream-to', startPoint, devBranch], { cwd: mainDir }).catch(() => {});
+
+  return { ok: true, created: true, mainDir, devDir, devBranch, syncRemote, trackingRemote };
+}

package/scripts/utils/git/dev_checkout.test.mjs

@@ -0,0 +1,115 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ensureDevCheckout } from './dev_checkout.mjs';
+
+function runCapture(cmd, args, { cwd, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code) => {
+      if (code === 0) return resolve({ stdout, stderr });
+      const e = new Error(`${cmd} failed (code=${code})`);
+      e.stdout = stdout;
+      e.stderr = stderr;
+      reject(e);
+    });
+  });
+}
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'hstack-dev-checkout-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+async function initBareRepo(dir) {
+  await mkdir(dir, { recursive: true });
+  await runCapture('git', ['init', '--bare'], { cwd: dir });
+}
+
+async function seedRepoWithBranches({ seedDir, upstreamBareDir, originBareDir }) {
+  await mkdir(seedDir, { recursive: true });
+  await runCapture('git', ['init'], { cwd: seedDir });
+  await runCapture('git', ['config', 'user.email', 'test@example.com'], { cwd: seedDir });
+  await runCapture('git', ['config', 'user.name', 'Test'], { cwd: seedDir });
+
+  await writeFile(join(seedDir, 'README.md'), 'seed\n', 'utf-8');
+  await runCapture('git', ['add', '.'], { cwd: seedDir });
+  await runCapture('git', ['commit', '-m', 'seed'], { cwd: seedDir });
+
+  await runCapture('git', ['branch', '-M', 'main'], { cwd: seedDir });
+  await runCapture('git', ['checkout', '-b', 'dev'], { cwd: seedDir });
+
+  await runCapture('git', ['remote', 'add', 'upstream', upstreamBareDir], { cwd: seedDir });
+  await runCapture('git', ['remote', 'add', 'origin', originBareDir], { cwd: seedDir });
+  await runCapture('git', ['push', 'upstream', 'main:main', 'dev:dev'], { cwd: seedDir });
+  await runCapture('git', ['push', 'origin', 'main:main', 'dev:dev'], { cwd: seedDir });
+}
+
+async function cloneIntoWorkspaceMain({ workspaceDir, upstreamBareDir, originBareDir }) {
+  const mainDir = join(workspaceDir, 'main');
+  await mkdir(workspaceDir, { recursive: true });
+  await runCapture('git', ['clone', upstreamBareDir, mainDir], { cwd: workspaceDir });
+
+  // Simulate the common contributor layout:
+  // - upstream = canonical repo
+  // - origin = fork
+  await runCapture('git', ['remote', 'set-url', 'origin', originBareDir], { cwd: mainDir });
+  await runCapture('git', ['remote', 'add', 'upstream', upstreamBareDir], { cwd: mainDir });
+  await runCapture('git', ['fetch', '--all'], { cwd: mainDir });
+}
+
+async function createDevCheckoutFixture(t, { forkWorkflow }) {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const stackRootDir = dirname(dirname(dirname(scriptsDir)));
+  const tempRoot = await withTempRoot(t);
+  const workspaceDir = join(tempRoot, 'workspace');
+  const upstreamBareDir = join(tempRoot, 'upstream.git');
+  const originBareDir = forkWorkflow ? join(tempRoot, 'origin.git') : upstreamBareDir;
+  const seedDir = join(tempRoot, 'seed');
+
+  await initBareRepo(upstreamBareDir);
+  if (forkWorkflow) {
+    await initBareRepo(originBareDir);
+  }
+  await seedRepoWithBranches({ seedDir, upstreamBareDir, originBareDir });
+  await cloneIntoWorkspaceMain({ workspaceDir, upstreamBareDir, originBareDir });
+
+  return {
+    stackRootDir,
+    workspaceDir,
+    originBareDir,
+  };
+}
+
+test('ensureDevCheckout prefers upstream/dev when upstream is pushable', async (t) => {
+  const fixture = await createDevCheckoutFixture(t, { forkWorkflow: false });
+  const env = { ...process.env, HAPPIER_STACK_WORKSPACE_DIR: fixture.workspaceDir };
+  const res = await ensureDevCheckout({ rootDir: fixture.stackRootDir, env });
+  assert.equal(res.ok, true);
+  assert.equal(res.trackingRemote, 'upstream');
+});
+
+test('ensureDevCheckout uses origin/dev when upstream is not pushable (fork workflow)', async (t) => {
+  const fixture = await createDevCheckoutFixture(t, { forkWorkflow: true });
+  const env = { ...process.env, HAPPIER_STACK_WORKSPACE_DIR: fixture.workspaceDir };
+  const res = await ensureDevCheckout({ rootDir: fixture.stackRootDir, env });
+  assert.equal(res.ok, true);
+  assert.equal(res.trackingRemote, 'origin');
+
+  const devDir = join(fixture.workspaceDir, 'dev');
+  const { stdout } = await runCapture('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], { cwd: devDir });
+  assert.equal(stdout.trim(), 'origin/dev');
+});

package/scripts/utils/git/git.mjs

@@ -0,0 +1,67 @@
+import { runCapture } from '../proc/proc.mjs';
+
+export async function gitCapture({ cwd, args }) {
+  return String(await runCapture('git', args, { cwd }));
+}
+
+export async function gitOk({ cwd, args }) {
+  try {
+    await runCapture('git', args, { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function normalizeRemoteName({ cwd, remote }) {
+  const want = String(remote ?? '').trim();
+  if (!want) return want;
+
+  if (await gitOk({ cwd, args: ['remote', 'get-url', want] })) return want;
+
+  // Treat origin/fork as interchangeable if one exists.
+  if (want === 'origin' && (await gitOk({ cwd, args: ['remote', 'get-url', 'fork'] }))) return 'fork';
+  if (want === 'fork' && (await gitOk({ cwd, args: ['remote', 'get-url', 'origin'] }))) return 'origin';
+
+  return want;
+}
+
+export async function resolveRemoteDefaultBranch({ cwd, remote }) {
+  const r = String(remote ?? '').trim();
+  if (!r) return 'main';
+
+  // Prefer refs/remotes/<remote>/HEAD when available.
+  try {
+    const headRef = (await gitCapture({ cwd, args: ['symbolic-ref', '-q', '--short', `refs/remotes/${r}/HEAD`] })).trim();
+    if (headRef.startsWith(`${r}/`)) {
+      return headRef.slice(r.length + 1);
+    }
+  } catch {
+    // ignore
+  }
+
+  // Fallback: parse `git remote show` output.
+  try {
+    const out = await gitCapture({ cwd, args: ['remote', 'show', r] });
+    for (const line of out.split('\n')) {
+      const m = line.match(/^\s*HEAD branch:\s*(.+)\s*$/);
+      if (m?.[1]) return m[1].trim();
+    }
+  } catch {
+    // ignore
+  }
+
+  return 'main';
+}
+
+export async function ensureRemoteRefAvailable({ cwd, remote, branch }) {
+  const r = String(remote ?? '').trim();
+  const b = String(branch ?? '').trim();
+  if (!r || !b) return false;
+  const ref = `refs/remotes/${r}/${b}`;
+  if (await gitOk({ cwd, args: ['show-ref', '--verify', '--quiet', ref] })) return true;
+  // Best-effort fetch of the default branch.
+  await gitCapture({ cwd, args: ['fetch', '--quiet', r, b] }).catch(() => '');
+  return await gitOk({ cwd, args: ['show-ref', '--verify', '--quiet', ref] });
+}
+

package/scripts/utils/git/parse_name_status_z.mjs

@@ -0,0 +1,21 @@
+export function parseNameStatusZ(buf) {
+  const raw = String(buf ?? '');
+  if (!raw) return [];
+  const parts = raw.split('\0').filter((x) => x.length);
+  const entries = [];
+  let i = 0;
+  while (i < parts.length) {
+    const status = parts[i++];
+    const code = status[0] ?? '';
+    if (!code) break;
+    if (code === 'R' || code === 'C') {
+      const from = parts[i++] ?? '';
+      const to = parts[i++] ?? '';
+      entries.push({ code, status, from, to });
+      continue;
+    }
+    const path = parts[i++] ?? '';
+    entries.push({ code, status, path });
+  }
+  return entries;
+}