@wringer/core 0.0.0 → 0.1.1

package/src/pick-merge-base-steps.ts

@@ -0,0 +1,37 @@
+import type { GitRequest } from './run-git.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface MergeBaseStepInput {
+  readonly root: string;
+  readonly base: string;
+
+  // The text of `git rev-list --max-count=1 --all`: empty when the repo has no commit.
+  readonly newestCommit: string;
+}
+
+export interface MergeBaseSteps {
+  readonly verifyBase: GitRequest;
+  readonly mergeBase: GitRequest;
+
+  readonly noSharedCommit: WringerError;
+}
+
+// `merge-base` names no cause when HEAD is unborn or the base is missing, so a repo with no commit
+// fails before it, and a missing base fails `verifyBase` with git's own message.
+export function pickMergeBaseSteps(input: MergeBaseStepInput): MergeBaseSteps | WringerError {
+  if (input.newestCommit.trim() === '') {
+    return new WringerError('environment', {
+      message: 'The repo has no commit yet, so its change has no fingerprint.',
+      hint: 'Commit once, then run the command again.',
+    });
+  }
+
+  return {
+    verifyBase: { cwd: input.root, args: ['rev-parse', '--verify', `${input.base}^{commit}`] },
+    mergeBase: { cwd: input.root, args: ['merge-base', 'HEAD', input.base] },
+    noSharedCommit: new WringerError('environment', {
+      message: `HEAD and ${input.base} share no commit in this clone, so the change has no fingerprint.`,
+      hint: 'In a shallow clone, fetch more history, such as with `git fetch --unshallow`.',
+    }),
+  };
+}

package/src/pick-pending-cleanups.ts

@@ -0,0 +1,23 @@
+export interface CleanupFacts {
+  readonly launched: boolean;
+  readonly serviceKeys: readonly string[];
+
+  // Each part whose stop has already started.
+  readonly stopping: ReadonlySet<string>;
+}
+
+export interface PendingCleanups {
+  readonly app: readonly string[];
+  readonly services: readonly string[];
+}
+
+const appCleanupKey = 'app';
+
+// Each part that is up and not yet stopping. The app stops before the services, so a service that
+// records its log, such as a stream recorder, sees its last lines.
+export function pickPendingCleanups(facts: CleanupFacts): PendingCleanups {
+  return {
+    app: facts.launched && !facts.stopping.has(appCleanupKey) ? [appCleanupKey] : [],
+    services: facts.serviceKeys.filter((key) => !facts.stopping.has(key)),
+  };
+}

package/src/pick-submodule-refusal.ts

@@ -0,0 +1,46 @@
+import { WringerError } from './wringer-error.ts';
+
+// `status --porcelain=v2` gives each submodule a field `S<c><m><u>`: `m` is `M` when its tracked
+// files changed and `u` is `U` when it holds untracked files. A moved commit alone reaches the
+// fingerprint through the gitlink, but work inside a submodule never does.
+export function pickSubmoduleRefusal(statusEntries: Uint8Array): WringerError | null {
+  const dirty = collectDirtySubmodules(Buffer.from(statusEntries).toString('utf8'));
+
+  if (dirty.length === 0) {
+    return null;
+  }
+
+  return new WringerError('environment', {
+    message: `The submodule ${dirty.join(', ')} holds work that is not committed in it, so the change has no fingerprint.`,
+    hint: 'Commit or stash the work inside the submodule, then run the command again.',
+  });
+}
+
+// A changed entry is `1`, a renamed one `2` and an unmerged one `u`, each with this many fields
+// before its path; with `-z`, a renamed entry's old path follows as an entry of its own.
+const fieldsBeforePath: ReadonlyMap<string, number> = new Map([
+  ['1', 8],
+  ['2', 9],
+  ['u', 10],
+]);
+
+function collectDirtySubmodules(status: string): string[] {
+  const entries = status.split('\0');
+  const dirty: string[] = [];
+  let index = 0;
+
+  while (index < entries.length) {
+    const fields = (entries[index] ?? '').split(' ');
+    const [kind = '', , submodule = ''] = fields;
+    const pathIndex = fieldsBeforePath.get(kind);
+    const isDirty = submodule[2] === 'M' || submodule[3] === 'U';
+
+    if (pathIndex !== undefined && submodule.startsWith('S') && isDirty) {
+      dirty.push(fields.slice(pathIndex).join(' '));
+    }
+
+    index += kind === '2' ? 2 : 1;
+  }
+
+  return dirty;
+}

package/src/pick-supervisor-operation.ts

@@ -0,0 +1,52 @@
+import { findOwnValue } from './find-own-value.ts';
+import { supervisorServiceName } from './supervisor-protocol.ts';
+import type { SupervisorRequest } from './supervisor-protocol.ts';
+import type { ServiceInstance } from './types.ts';
+import { WringerError } from './wringer-error.ts';
+
+export type SupervisorOperation =
+  | { readonly kind: 'stop' }
+  | { readonly kind: 'status' }
+  | {
+      readonly kind: 'call';
+
+      // Empty for a request with no deadline; otherwise the one delay after which the call aborts.
+      readonly cancelAfterMs: readonly number[];
+      readonly call: (signal: AbortSignal) => Promise<unknown>;
+    }
+  | { readonly kind: 'refuse'; readonly error: WringerError };
+
+// A service method's signal aborts this long before the caller's deadline, so the method has time
+// to stop its work, such as a browser closing its page, before the caller reports a timeout.
+const serviceCancelReserveMs = 1000;
+
+export function pickSupervisorOperation(
+  request: SupervisorRequest,
+  services: ReadonlyMap<string, Pick<ServiceInstance, 'methods'>>,
+  nowMs: number,
+): SupervisorOperation {
+  if (request.service === supervisorServiceName) {
+    return request.method === 'stop' ? { kind: 'stop' } : { kind: 'status' };
+  }
+
+  const methods = services.get(request.service)?.methods ?? {};
+  const method = findOwnValue(methods, request.method);
+
+  if (method === undefined) {
+    return {
+      kind: 'refuse',
+      error: new WringerError('usage', {
+        message: `The run has no service call ${request.service} ${request.method}.`,
+      }),
+    };
+  }
+
+  return {
+    kind: 'call',
+    cancelAfterMs:
+      request.deadlineAt === undefined
+        ? []
+        : [Math.max(0, request.deadlineAt - serviceCancelReserveMs - nowMs)],
+    call: (signal) => method(request.args, signal),
+  };
+}

package/src/prepare-args.ts

@@ -0,0 +1,22 @@
+import type { z } from 'zod';
+import type { ArgsResult } from './types.ts';
+
+// Parses raw arguments with a command's own schema and hands the typed result to `build`, so the
+// typed arguments never leave the closure that knows their type.
+export function prepareArgs<Args, Prepared>(
+  schema: z.ZodType<Args>,
+  raw: unknown,
+  build: (args: Args) => Prepared,
+): ArgsResult<Prepared> {
+  const parsed = schema.safeParse(raw ?? {});
+
+  if (!parsed.success) {
+    const problems = parsed.error.issues.map((issue) =>
+      issue.path.length === 0 ? issue.message : `${issue.path.join('.')}: ${issue.message}`,
+    );
+
+    return { ok: false, message: `The arguments are not valid: ${problems.join('; ')}` };
+  }
+
+  return { ok: true, prepared: build(parsed.data) };
+}

package/src/probe-process.ts

@@ -0,0 +1,16 @@
+import { isErrorCode } from './is-error-code.ts';
+
+// Signal 0 checks that the process exists and sends nothing. EPERM means it runs as another user.
+export function probeProcess(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (error) {
+    return isErrorCode(error, 'EPERM');
+  }
+}

package/src/quote-shell-word.ts

@@ -0,0 +1,9 @@
+const plainWord = /^[\w%+,./:=@-]+$/u;
+
+export function quoteShellWord(word: string): string {
+  if (plainWord.test(word)) {
+    return word;
+  }
+
+  return `'${word.replaceAll("'", `'\\''`)}'`;
+}

package/src/race-deadline.ts

@@ -0,0 +1,23 @@
+import { WringerError } from './wringer-error.ts';
+
+// The work's own promise may never settle once its deadline passes, so the deadline settles the
+// race with a timeout, including a deadline that passed before the race began.
+export async function raceDeadline<T>(work: Promise<T>, deadline: AbortSignal): Promise<T> {
+  const aborted = Promise.withResolvers<T>();
+
+  const onAbort = (): void => {
+    aborted.reject(new WringerError('timeout'));
+  };
+
+  deadline.addEventListener('abort', onAbort, { once: true });
+
+  if (deadline.aborted) {
+    onAbort();
+  }
+
+  try {
+    return await Promise.race([work, aborted.promise]);
+  } finally {
+    deadline.removeEventListener('abort', onAbort);
+  }
+}

package/src/read-changed-paths.ts

@@ -0,0 +1,39 @@
+import type { FingerprintHost } from './read-fingerprint.ts';
+
+export interface ChangedPathsRequest {
+  readonly cwd: string;
+  readonly base: string;
+  readonly exclude: readonly string[];
+}
+
+// The paths the branch changes against its merge base: committed, staged and unstaged edits, and
+// untracked files that git does not ignore.
+export async function readChangedPaths(
+  host: Pick<FingerprintHost, 'runGit'>,
+  request: ChangedPathsRequest,
+): Promise<readonly string[]> {
+  const mergeBaseResult = await host.runGit({
+    cwd: request.cwd,
+    args: ['merge-base', 'HEAD', request.base],
+  });
+
+  const mergeBase = mergeBaseResult.stdout.trim();
+  const excludes = request.exclude.map((path) => `:(exclude)${path}`);
+
+  // `-z` gives each path as it is: without it, git quotes a path with a tab, a newline or a
+  // non-ASCII letter, and the quoted form matches no feature's glob.
+  const [tracked, untracked] = await Promise.all([
+    host.runGit({
+      cwd: request.cwd,
+      args: ['diff', '--name-only', '-z', '--no-renames', mergeBase, '--', '.', ...excludes],
+    }),
+    host.runGit({
+      cwd: request.cwd,
+      args: ['ls-files', '-z', '--others', '--exclude-standard', '--', '.', ...excludes],
+    }),
+  ]);
+
+  const paths = `${tracked.stdout}\0${untracked.stdout}`.split('\0').filter((path) => path !== '');
+
+  return [...new Set(paths)].toSorted();
+}

package/src/read-default-base.ts

@@ -0,0 +1,21 @@
+import type { FingerprintHost } from './read-fingerprint.ts';
+
+// The base a branch merges into: the remote's default branch when the clone knows it, else `main`.
+// git exits non-zero when the clone has no remote default branch, which is a normal answer here.
+export async function readDefaultBase(
+  host: Pick<FingerprintHost, 'runGit'>,
+  root: string,
+): Promise<string> {
+  try {
+    const result = await host.runGit({
+      cwd: root,
+      args: ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'],
+    });
+
+    const base = result.stdout.trim();
+
+    return base === '' ? 'main' : base;
+  } catch {
+    return 'main';
+  }
+}

package/src/read-fingerprint.ts

@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { buildPromisedObjectReads } from './build-promised-object-reads.ts';
+import { buildSkipWorktreeMarks } from './build-skip-worktree-marks.ts';
+import { buildSubmoduleAdds } from './build-submodule-adds.ts';
+import { parsePatchID } from './parse-patch-id.ts';
+import { pickMergeBaseFailure } from './pick-merge-base-failure.ts';
+import { pickMergeBaseSteps } from './pick-merge-base-steps.ts';
+import { pickSubmoduleRefusal } from './pick-submodule-refusal.ts';
+import type { GitRequest } from './run-git.ts';
+import type { ProcessResult } from './run-process.ts';
+import { WringerError } from './wringer-error.ts';
+
+export interface FingerprintHost {
+  readonly runGit: (request: GitRequest) => Promise<ProcessResult>;
+  readonly runGitBytes: (request: GitRequest) => Promise<Uint8Array>;
+  readonly removeDirectory: (path: string) => Promise<void>;
+}
+
+export interface FingerprintRequest {
+  readonly cwd: string;
+  readonly base: string;
+  readonly exclude: readonly string[];
+}
+
+const pinnedDiffOptions = [
+  '--unified=3',
+  '--inter-hunk-context=0',
+  '--no-renames',
+  '--diff-algorithm=myers',
+  '--indent-heuristic',
+  '--src-prefix=a/',
+  '--dst-prefix=b/',
+  '--ignore-submodules=none',
+  '--submodule=short',
+];
+
+// The index is built and diffed in a git folder of its own, so only the repo's tracked files and
+// git's defaults shape the change: no config, attributes or ignore rules of the clone, the user or
+// the system reach it, and the same change gets the same fingerprint in any clone.
+export async function readFingerprint(
+  host: FingerprintHost,
+  request: FingerprintRequest,
+): Promise<string> {
+  const root = await readRepoRoot(host, request.cwd);
+  const mergeBase = await readMergeBase(host, root, request.base);
+
+  await readPromisedObjects(host, root, mergeBase);
+  await readSubmoduleWork(host, root);
+
+  const gitDir = await readGitPath(host, root, `wringer-${randomUUID()}`);
+
+  try {
+    const env = await createIsolatedGitDir(host, root, gitDir);
+
+    // The index starts as a copy of the repo's own, so a file staged past an ignore rule counts as
+    // a commit would count it. `--index-info` takes the lines `ls-files --stage` prints.
+    const staged = await host.runGitBytes({ cwd: root, args: ['ls-files', '--stage', '-z'] });
+
+    await host.runGit({
+      cwd: root,
+      args: ['update-index', '-z', '--index-info'],
+      stdin: staged,
+      env,
+    });
+
+    await copySkipWorktreeFlags(host, root, env);
+
+    // With sparse checkout on, git 2.37 and later clears the skip-worktree mark of each file on disk
+    // as it reads the index, so an edit to a marked file counts and only an absent one stays out.
+    await host.runGit({
+      cwd: root,
+      args: ['-c', 'core.sparseCheckout=true', 'add', '--all'],
+      env,
+    });
+
+    await addSubmodules(host, root, env);
+
+    // The exclusions apply to the diff, not to `add`: `add` refuses an ignored path in a pathspec,
+    // and a committed change to an excluded path reaches the index from the repo's own anyway.
+    const diff = await host.runGitBytes({
+      cwd: root,
+      args: [
+        'diff',
+        '--cached',
+        '--binary',
+        '--no-color',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--no-relative',
+        ...pinnedDiffOptions,
+        mergeBase,
+        '--',
+        ':(top)',
+        ...request.exclude.map((path) => `:(top,exclude)${path}`),
+      ],
+      env,
+    });
+
+    const patchID = await host.runGit({
+      cwd: root,
+
+      // `--verbatim` hashes with the stable algorithm and keeps whitespace, so `"a b"` and `"ab"`
+      // differ; `--stable` alone drops it, and git refuses the two flags together.
+      args: ['patch-id', '--verbatim'],
+      stdin: diff,
+      env,
+    });
+
+    return parsePatchID(patchID.stdout);
+  } finally {
+    await host.removeDirectory(gitDir);
+  }
+}
+
+// From a subfolder, `ls-files` lists only that folder, with paths relative to it, so every index
+// step runs from the root.
+async function readRepoRoot(host: FingerprintHost, cwd: string): Promise<string> {
+  const result = await host.runGit({ cwd, args: ['rev-parse', '--show-toplevel'] });
+
+  // A folder name may end in a space, so only the line end git adds comes off.
+  return resolve(cwd, result.stdout.replace(/\n$/u, ''));
+}
+
+async function readMergeBase(host: FingerprintHost, root: string, base: string): Promise<string> {
+  const commits = await host.runGit({ cwd: root, args: ['rev-list', '--max-count=1', '--all'] });
+
+  const steps = pickMergeBaseSteps({ root, base, newestCommit: commits.stdout });
+
+  if (steps instanceof WringerError) {
+    throw steps;
+  }
+
+  await host.runGit(steps.verifyBase);
+
+  try {
+    const result = await host.runGit(steps.mergeBase);
+
+    return result.stdout.trim();
+  } catch (error) {
+    throw pickMergeBaseFailure(error, steps.noSharedCommit);
+  }
+}
+
+async function readPromisedObjects(
+  host: FingerprintHost,
+  root: string,
+  mergeBase: string,
+): Promise<void> {
+  const config = await host.runGit({ cwd: root, args: ['config', '--list', '-z'] });
+
+  for (const request of buildPromisedObjectReads({ root, mergeBase, configList: config.stdout })) {
+    await host.runGit(request);
+  }
+}
+
+// `--no-optional-locks` keeps status from writing the repo's own index, and `-uno` skips the
+// repo's own untracked files, which `add --all` counts anyway.
+async function readSubmoduleWork(host: FingerprintHost, root: string): Promise<void> {
+  const status = await host.runGitBytes({
+    cwd: root,
+    args: [
+      '--no-optional-locks',
+      'status',
+      '--porcelain=v2',
+      '-z',
+      '--ignore-submodules=none',
+      '--untracked-files=no',
+    ],
+  });
+
+  const refusal = pickSubmoduleRefusal(status);
+
+  if (refusal !== null) {
+    throw refusal;
+  }
+}
+
+// git prints a path inside the git folder relative to the folder it runs in; the path leaves here
+// absolute.
+async function readGitPath(host: FingerprintHost, root: string, name: string): Promise<string> {
+  const result = await host.runGit({ cwd: root, args: ['rev-parse', '--git-path', name] });
+
+  return resolve(root, result.stdout.replace(/\n$/u, ''));
+}
+
+// Only git's defaults apply: no system or global config, and no `-c` from a calling git. The two
+// keys turn off the attributes and ignore files git reads from the user's config folder by default.
+const isolatedConfigEnv = {
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_CONFIG_PARAMETERS: '',
+  GIT_CONFIG_COUNT: '2',
+  GIT_CONFIG_KEY_0: 'core.attributesFile',
+  GIT_CONFIG_VALUE_0: '/dev/null',
+  GIT_CONFIG_KEY_1: 'core.excludesFile',
+  GIT_CONFIG_VALUE_1: '/dev/null',
+  GIT_ATTR_NOSYSTEM: '1',
+};
+
+// The folder reads the repo's objects as alternates and writes its own, so the repo gains no
+// object. A bare folder made with no template has no `info/attributes` and no `info/exclude`.
+async function createIsolatedGitDir(
+  host: FingerprintHost,
+  root: string,
+  gitDir: string,
+): Promise<Readonly<Record<string, string>>> {
+  const objects = await readGitPath(host, root, 'objects');
+  const format = await host.runGit({ cwd: root, args: ['rev-parse', '--show-object-format'] });
+
+  await host.runGit({
+    cwd: root,
+    args: ['init', '--quiet', '--bare', '--template=', `--object-format=${format.stdout.trim()}`],
+    env: { ...isolatedConfigEnv, GIT_DIR: gitDir, GIT_COMMON_DIR: gitDir },
+  });
+
+  return buildIsolatedEnv(gitDir, root, objects);
+}
+
+// Each variable a calling git, such as a hook's, may set is overwritten, so the steps cannot reach
+// the repo's own index, objects or git folder. git lets GIT_DIFF_OPTS override `--unified`, and
+// the pathspec variables change what `:(top)` and each exclusion match.
+function buildIsolatedEnv(
+  gitDir: string,
+  root: string,
+  objects: string,
+): Readonly<Record<string, string>> {
+  return {
+    ...isolatedConfigEnv,
+    GIT_DIR: gitDir,
+    GIT_COMMON_DIR: gitDir,
+    GIT_WORK_TREE: root,
+    GIT_INDEX_FILE: join(gitDir, 'index'),
+    GIT_OBJECT_DIRECTORY: join(gitDir, 'objects'),
+    GIT_ALTERNATE_OBJECT_DIRECTORIES: toQuotedGitPath(objects),
+    GIT_DIFF_OPTS: '--unified=3',
+    GIT_LITERAL_PATHSPECS: '0',
+    GIT_GLOB_PATHSPECS: '0',
+    GIT_NOGLOB_PATHSPECS: '0',
+    GIT_ICASE_PATHSPECS: '0',
+  };
+}
+
+// git splits the alternates list at `:`, unless an entry is quoted the way C quotes a string.
+function toQuotedGitPath(path: string): string {
+  return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"`;
+}
+
+async function copySkipWorktreeFlags(
+  host: FingerprintHost,
+  root: string,
+  env: Readonly<Record<string, string>>,
+): Promise<void> {
+  const tagged = await host.runGitBytes({ cwd: root, args: ['ls-files', '-t', '-z'] });
+
+  for (const request of buildSkipWorktreeMarks({ root, env, taggedEntries: tagged })) {
+    await host.runGit(request);
+  }
+}
+
+async function addSubmodules(
+  host: FingerprintHost,
+  root: string,
+  env: Readonly<Record<string, string>>,
+): Promise<void> {
+  const staged = await host.runGitBytes({ cwd: root, args: ['ls-files', '--stage', '-z'], env });
+
+  for (const request of buildSubmoduleAdds({ root, env, stagedEntries: staged })) {
+    await host.runGit(request);
+  }
+}

package/src/read-head-sha.ts

@@ -0,0 +1,23 @@
+import type { FingerprintHost } from './read-fingerprint.ts';
+import { WringerError } from './wringer-error.ts';
+
+// The SHA only labels an envelope, so a git that fails or cannot start leaves it null and the
+// command's own result stands.
+export async function readHeadSHA(
+  host: Pick<FingerprintHost, 'runGit'>,
+  root: string,
+): Promise<string | null> {
+  const result = await host
+    .runGit({ cwd: root, args: ['rev-parse', '--short', 'HEAD'] })
+    .catch((error: unknown) => {
+      if (error instanceof WringerError) {
+        return null;
+      }
+
+      throw error;
+    });
+
+  const sha = result?.stdout.trim() ?? '';
+
+  return sha === '' ? null : sha;
+}

package/src/read-launch-host.ts

@@ -0,0 +1,64 @@
+import { appendFile } from 'node:fs/promises';
+import { buildLaunchGuard } from './build-launch-guard.ts';
+import { createDirectory } from './create-directory.ts';
+import { createSocketFolder } from './create-socket-folder.ts';
+import { killProcessGroup } from './kill-process-group.ts';
+import { listenSupervisorSocket } from './listen-supervisor-socket.ts';
+import type { SupervisorSocket, SupervisorSocketOptions } from './listen-supervisor-socket.ts';
+import { removeDirectory } from './remove-directory.ts';
+import { runProcess } from './run-process.ts';
+import type { ProcessRequest, ProcessResult } from './run-process.ts';
+
+export interface AppSpawnOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+export interface AppProcess {
+  readonly pid: number;
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly stderr: ReadableStream<Uint8Array>;
+  readonly exited: Promise<number>;
+}
+
+// Everything the launch reads from or does to this machine.
+export interface LaunchHost {
+  readonly guard: readonly string[];
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly spawnApp: (argv: readonly string[], options: AppSpawnOptions) => AppProcess;
+  readonly appendLog: (path: string, text: string) => Promise<void>;
+  readonly createDirectory: (path: string) => Promise<void>;
+
+  // Returns the socket's path, in the temp folder when the preferred path is too long for a socket.
+  readonly createSocketFolder: (preferredSocket: string) => Promise<string>;
+  readonly removeDirectory: (path: string) => Promise<void>;
+  readonly listenSupervisorSocket: (options: SupervisorSocketOptions) => Promise<SupervisorSocket>;
+  readonly killProcessGroup: (pid: number, signal?: NodeJS.Signals) => void;
+  readonly runProcess: (request: ProcessRequest) => Promise<ProcessResult>;
+}
+
+// The app gets a process group of its own, so a stop can signal every process it started.
+export function readLaunchHost(): LaunchHost {
+  return {
+    guard: buildLaunchGuard(Bun.which('setpriv')),
+    cwd: process.cwd(),
+    env: { ...process.env },
+    spawnApp: (argv, options) =>
+      Bun.spawn([...argv], {
+        cwd: options.cwd,
+        env: { ...options.env },
+        stdin: 'ignore',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        detached: true,
+      }),
+    appendLog: appendFile,
+    createDirectory,
+    createSocketFolder,
+    removeDirectory,
+    listenSupervisorSocket,
+    killProcessGroup,
+    runProcess,
+  };
+}

package/src/read-pid-namespace.ts

@@ -0,0 +1,18 @@
+import { readlinkSync } from 'node:fs';
+import { isErrorCode } from './is-error-code.ts';
+
+const namespacePattern = /\[(?<id>\d+)\]/v;
+
+// A PID names a process only inside its PID namespace, so two containers that share a folder can
+// both run a process 4100. A host with no `/proc`, such as macOS, has the one namespace `host`.
+export function readPIDNamespace(): string {
+  try {
+    return namespacePattern.exec(readlinkSync('/proc/self/ns/pid'))?.groups?.['id'] ?? 'host';
+  } catch (error) {
+    if (isErrorCode(error, 'ENOENT') || isErrorCode(error, 'EACCES')) {
+      return 'host';
+    }
+
+    throw error;
+  }
+}