@homeflare/alchemy 0.15.0 → 0.19.0

package/src/linux/ssh-command.test.ts

@@ -0,0 +1,140 @@
+/**
+ * The ssh wire format, with no connection: quoting, framing, and the fail-closed rule that a
+ * result without the framing marker is never read as data.
+ */
+import { describe, expect, test } from 'bun:test';
+import { ABSENT, frameScript, parseFramed, quoteArgv, shellQuote, sshArgv } from './ssh-command.ts';
+import { parseStat, statScript, writeScript } from './ssh-scripts.ts';
+
+const NONCE = 'a1b2c3d4';
+
+describe('quoting', () => {
+  test('shell metacharacters survive as data', () => {
+    for (const arg of ['a b', '$HOME', '`id`', 'x;rm -rf /', "it's", 'new\nline', '*']) {
+      expect(shellQuote(arg)).toMatch(/^'.*'$/s);
+    }
+    expect(shellQuote("it's")).toBe(`'it'\\''s'`);
+  });
+
+  test('NUL is refused rather than truncated by the shell', () => {
+    expect(() => shellQuote('a\u0000b')).toThrow(/NUL/);
+  });
+
+  test('an argv becomes one command line', () => {
+    expect(quoteArgv(['systemctl', 'show', 'a b.service'])).toBe(
+      `'systemctl' 'show' 'a b.service'`,
+    );
+  });
+});
+
+describe('framing', () => {
+  test('the remote status comes back behind the nonce, and its stderr is clean', () => {
+    const stderr = `boom\n\n__HF_RC_${NONCE}=3\n`;
+    // ★ The command's own trailing newline is the command's; only the marker line is removed.
+    expect(parseFramed(stderr, NONCE)).toEqual({ exitCode: 3, stderr: 'boom\n' });
+  });
+
+  test('a result with no marker is not an answer', () => {
+    // ⛔ This is the whole point: ssh exit 255 with empty output must not read as "not found".
+    expect(parseFramed('', NONCE)).toBeUndefined();
+    expect(
+      parseFramed('ssh: connect to host port 22: Connection refused\n', NONCE),
+    ).toBeUndefined();
+  });
+
+  test('a marker under another nonce cannot speak for this runner', () => {
+    expect(parseFramed(`\n__HF_RC_deadbeef=0\n`, NONCE)).toBeUndefined();
+  });
+
+  test('a program that prints the marker text itself does not win — the last one is ours', () => {
+    const stderr = `pretend: __HF_RC_${NONCE}=0\n\n__HF_RC_${NONCE}=7\n`;
+    expect(parseFramed(stderr, NONCE)?.exitCode).toBe(7);
+  });
+
+  test('the frame ends by echoing the status and exiting with it', () => {
+    const framed = frameScript('true', NONCE);
+    expect(framed).toContain('__hf=$?');
+    expect(framed).toContain(`__HF_RC_${NONCE}=%s`);
+    expect(framed.endsWith('exit "$__hf"')).toBe(true);
+  });
+
+  test('a script that exits still reports — the subshell is load-bearing', async () => {
+    /**
+     * 🔴 MEASURED 2026-09-22 against a live host: without the subshell, `statScript`'s
+     *   `else exit 66` left the shell before the marker printed, and a missing file came back as
+     *   a transport failure. This runs the real framing through a real /bin/sh.
+     */
+    const script = frameScript(statScript('/definitely-not-here-hf'), NONCE);
+    const shell = Bun.spawn(['/bin/sh', '-c', script], { stderr: 'pipe', stdout: 'pipe' });
+    const stderr = await new Response(shell.stderr).text();
+    expect(parseFramed(stderr, NONCE)?.exitCode).toBe(ABSENT);
+  });
+});
+
+describe('the ssh invocation', () => {
+  const argv = sshArgv('somewhere', 'true', { connectTimeoutSec: 10 });
+
+  test('never prompts and never weakens host verification', () => {
+    expect(argv).toContain('BatchMode=yes');
+    expect(argv.join(' ')).not.toContain('StrictHostKeyChecking');
+    expect(argv.join(' ')).not.toContain('UserKnownHostsFile');
+  });
+
+  test('names a POSIX shell rather than trusting the login shell', () => {
+    expect(argv.at(-1)?.startsWith("/bin/sh -c '")).toBe(true);
+  });
+
+  test('a destination that could be read as an option is refused', () => {
+    expect(() => sshArgv('-oProxyCommand=evil', 'true', { connectTimeoutSec: 10 })).toThrow();
+  });
+});
+
+describe('the file scripts', () => {
+  test('stat asks about the link, not its target, and says so for a dangling one', () => {
+    const script = statScript('/etc/thing');
+    expect(script).toContain("[ -e '/etc/thing' ] || [ -L '/etc/thing' ]");
+    expect(script).not.toContain('stat -L');
+  });
+
+  test('the write stages, chowns, chmods, then renames — and cleans up on every failure', () => {
+    const script = writeScript('/etc/a.conf', '/etc/.a.conf.tmp', { gid: 0, mode: 0o640, uid: 0 });
+    const steps = script.split('\n');
+    expect(steps[0]).toBe('set -C');
+    expect(steps[1]).toBe('umask 077');
+    expect(script.indexOf('chown')).toBeLessThan(script.indexOf('chmod'));
+    expect(script).toContain("chmod 640 -- '/etc/.a.conf.tmp'");
+    expect(script).toContain("mv -f -- '/etc/.a.conf.tmp' '/etc/a.conf'");
+    expect(script.match(/rm -f --/g)).toHaveLength(4);
+  });
+
+  test('a declared owner with no group never becomes the user’s login group', () => {
+    expect(writeScript('/a', '/t', { mode: 0o644, uid: 42 })).toContain("chown 42 -- '/t'");
+    expect(writeScript('/a', '/t', { gid: 7, mode: 0o644 })).toContain("chown :7 -- '/t'");
+    expect(writeScript('/a', '/t', { mode: 0o644 })).not.toContain('chown');
+  });
+});
+
+describe('stat output', () => {
+  test('the measured shape parses, file type from the raw mode', () => {
+    // MEASURED 2026-09-22 on Debian 13: `/etc/hostname` → `81a4 644 0 0 4`.
+    expect(parseStat('81a4 644 0 0 4\n')).toEqual({
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      size: 4,
+      uid: 0,
+    });
+    expect(parseStat('41ed 755 0 0 4096')?.kind).toBe('directory');
+    expect(parseStat('a1ff 777 0 0 11')?.kind).toBe('symlink');
+    expect(parseStat('c000 666 0 0 0')?.kind).toBe('other');
+  });
+
+  test('setuid bits come from the permission field, not the raw mode', () => {
+    expect(parseStat('89ed 4755 0 0 1')?.mode).toBe(0o4755);
+  });
+
+  test('anything else is undefined, so the runner can refuse instead of guessing', () => {
+    expect(parseStat('stat: cannot statx')).toBeUndefined();
+    expect(parseStat('')).toBeUndefined();
+  });
+});

package/src/linux/ssh-command.ts

@@ -0,0 +1,99 @@
+/**
+ * The wire format the ssh runner speaks: how an argv becomes one remote `sh` script, and how that
+ * script's real exit code comes back. Pure functions, so every quoting and framing rule is tested
+ * without opening a connection.
+ *
+ * ⛔ `ssh host <words>` IS NOT AN EXECVE. ssh joins its trailing arguments with spaces and the
+ *   REMOTE LOGIN SHELL parses the result, so an unquoted path with a space, a `$`, a backtick or a
+ *   `;` is re-parsed as shell syntax on the other side. Everything therefore goes through
+ *   `shellQuote`, and the remote command is always `/bin/sh -c '<script>'` — a POSIX shell named
+ *   explicitly, so a csh or fish login shell only ever execs it.
+ * ⛔ AN EXIT CODE FROM ssh IS AMBIGUOUS. ssh exits 255 for its own failures (connection refused,
+ *   host key changed, auth) and otherwise passes the remote exit code through — and a remote
+ *   command may itself exit 255. A runner that read the code alone would report "the file is not
+ *   there" for a dropped connection, which is the exact "never infer success from an empty result"
+ *   failure. So every script ends by printing its own status on stderr behind a PER-RUNNER NONCE,
+ *   and a result without that line is a transport failure, never data.
+ * ⚠️ THE NONCE IS NOT DECORATION. Without it a remote program that happens to print the marker on
+ *   stderr could claim any exit code it liked; with a fresh random nonce per runner, the only thing
+ *   that can produce the line is the script we sent.
+ */
+
+/** A script whose work found nothing at the path. ★ Chosen from the 64–113 range sh leaves free. */
+export const ABSENT = 66;
+
+/**
+ * One argument, safe for a POSIX shell. ⛔ Single quotes, because they quote EVERYTHING; the
+ *   `'\''` dance is how a literal quote gets through.
+ */
+export const shellQuote = (arg: string): string => {
+  if (arg.includes('\x00')) throw new Error('ssh: an argument contains NUL');
+  return `'${arg.replaceAll("'", `'\\''`)}'`;
+};
+
+/** An argv as one shell command line. */
+export const quoteArgv = (argv: readonly string[]): string => argv.map(shellQuote).join(' ');
+
+const marker = (nonce: string) => `__HF_RC_${nonce}=`;
+
+/**
+ * Wrap a script so its status comes back unambiguously.
+ *
+ * ⛔ THE SCRIPT RUNS IN A SUBSHELL, AND THAT IS NOT COSMETIC. Several of the scripts end a branch
+ *   with `exit <code>` to say "nothing was there"; at the top level that exit leaves the shell
+ *   immediately and the marker line NEVER PRINTS — so the caller sees a framed result missing its
+ *   frame and, correctly, calls it a transport failure. 🔴 MEASURED 2026-09-22 against a live
+ *   Debian 13 host: `stat` of a missing path came back as "the remote command did not report a
+ *   status (ssh exit 66)" instead of "nothing is at this path". Inside `( … )` the exit leaves only
+ *   the subshell, `$?` carries the code out, and the frame always runs.
+ * ⚠️ The leading `\n` matters too: a program whose last stderr line has no newline would otherwise
+ *   glue itself to the marker and the marker would not be found.
+ */
+export const frameScript = (script: string, nonce: string): string =>
+  `(\n${script}\n)\n__hf=$?\nprintf '\\n${marker(nonce)}%s\\n' "$__hf" >&2\nexit "$__hf"`;
+
+export type Framed = { readonly exitCode: number; readonly stderr: string };
+
+/**
+ * The remote exit code and the stderr that belongs to the command, or `undefined` when the marker
+ * is absent — which means the script never ran to its end: ssh failed, the connection dropped, or
+ * the remote shell could not parse what we sent. ⛔ The caller must treat `undefined` as an error,
+ * never as an answer.
+ */
+export const parseFramed = (stderr: string, nonce: string): Framed | undefined => {
+  const at = stderr.lastIndexOf(`\n${marker(nonce)}`);
+  if (at < 0) return undefined;
+  const digits = /^(\d+)\s*$/.exec(stderr.slice(at + marker(nonce).length + 1));
+  if (digits?.[1] === undefined) return undefined;
+  return { exitCode: Number(digits[1]), stderr: stderr.slice(0, at) };
+};
+
+/**
+ * The fixed ssh options, in front of anything a caller adds.
+ * ⛔ `BatchMode=yes` — a deploy that stops to ask for a passphrase is the failure "no password
+ *   prompts" names, and with BatchMode ssh fails at once instead.
+ * ⛔ NOTHING HERE WEAKENS HOST VERIFICATION. No `StrictHostKeyChecking`, no `UserKnownHostsFile`:
+ *   the operator's own ssh config and known_hosts decide who the host is, and a changed key stays
+ *   a refusal. A runner that turned that off would make a man-in-the-middle a deploy target.
+ * ★ `-T`: no pseudo-terminal, so the remote shell's stdout stays the bytes the program wrote.
+ */
+export const sshArgv = (
+  host: string,
+  script: string,
+  options: { readonly connectTimeoutSec: number; readonly sshArgs?: readonly string[] },
+): readonly string[] => {
+  if (host === '' || host.startsWith('-')) {
+    throw new Error(`ssh: ${JSON.stringify(host)} is not a usable destination`);
+  }
+  return [
+    'ssh',
+    '-T',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    `ConnectTimeout=${String(options.connectTimeoutSec)}`,
+    ...(options.sshArgs ?? []),
+    host,
+    `/bin/sh -c ${shellQuote(script)}`,
+  ];
+};

package/src/linux/ssh-runner.ts

@@ -0,0 +1,188 @@
+/**
+ * `sshRunner()` — the estate's Linux hosts behind the SAME HostRunner seam the launchd family
+ * already drives a Mac through (launchd/runner.ts). Every provider in this directory reaches its
+ * host only through it, so the whole Linux lifecycle runs against a fake in tests.
+ *
+ * ★ WHY THE SAME SEAM AND NOT A SECOND ONE. HostRunner is nine promise-returning methods with no
+ *   macOS in them; what was Mac-specific was launchctl and the plist, not the seam. Reusing it
+ *   means HostFile, the ownership rules and `checkWrite` already work on Linux, and a stack can
+ *   hand the same runner to a file, a directory and a unit.
+ * ⛔ NO PASSWORDS AND NO SILENT SUDO. Every connection is `BatchMode=yes` (ssh-command.ts), and
+ *   `privileged` is false: this runner never calls sudo. A root-owned path therefore needs a
+ *   destination whose ssh user IS root — which is how the estate already reaches its hypervisors —
+ *   or a privileged runner of the caller's own. See docs/linux-host.md; the Linux twin of
+ *   sudoRunner is deliberately a later, separate change with its own allowlist.
+ * ⛔ FAIL CLOSED. A connection that drops, a host key that changed, a shell that cannot parse the
+ *   script: none of them produces a "not found". Without the framing marker the result is an
+ *   Error, never data (ssh-command.ts parseFramed).
+ * ★ EXERCISED READ-ONLY AGAINST A LIVE HOST, 2026-09-22 (Debian 13, systemd 257, ssh user uid
+ *   1001): `stat` of a file, of a missing path and of a symlink (reported `symlink`, so the lstat
+ *   contract holds over the wire); `readFile` of a file and of a missing path; `getent` user and
+ *   group; a failing `exec`; and an argument of `a b '$HOME` + backtick + ` ;rm` arriving verbatim,
+ *   which is the quoting proven rather than argued. Nothing was written.
+ * ⚠️ ONE CONNECTION PER CALL. No multiplexing is configured here: a deploy over a slow link pays a
+ *   handshake per read. Pass `sshArgs: ['-o', 'ControlMaster=auto', …]` to opt into your own
+ *   ControlPersist socket — the kit does not create one behind your back, because a stale socket
+ *   outliving the deploy is a surprise nobody declared.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { groupQuery, parseGroup, parseUser, userQuery } from '../launchd/host-lookup.ts';
+import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+import { ABSENT, frameScript, parseFramed, sshArgv } from './ssh-command.ts';
+import {
+  execScript,
+  parseStat,
+  readScript,
+  removeScript,
+  statScript,
+  writeScript,
+} from './ssh-scripts.ts';
+
+export type SshRunnerOptions = {
+  /** The destination exactly as the operator's own ssh config names it (`Host` block or user@host). */
+  readonly host: string;
+  /** Extra ssh options, after the fixed safety set and before the destination. */
+  readonly sshArgs?: readonly string[];
+  /** Kill a connection after this long. @default 120_000 */
+  readonly execTimeoutMs?: number;
+  /** ssh's own `ConnectTimeout`. @default 10 */
+  readonly connectTimeoutSec?: number;
+};
+
+type Raw = { exitCode: number; stdout: string; stderr: string; signal: string | null };
+
+const spawnSsh = (argv: readonly string[], timeoutMs: number, stdin?: Uint8Array): Promise<Raw> =>
+  new Promise((resolve, reject) => {
+    const [program, ...args] = argv as [string, ...string[]];
+    const child = spawn(program, args, {
+      shell: false,
+      stdio: [stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout?.on('data', (chunk: Buffer) => out.push(chunk));
+    child.stderr?.on('data', (chunk: Buffer) => err.push(chunk));
+    child.on('error', (cause) => {
+      reject(new Error(`ssh: ${cause.message}`));
+    });
+    if (stdin !== undefined && child.stdin !== null) {
+      // ⚠️ EPIPE is normal here: the remote `cat` can die before we finish writing, and the real
+      //   failure is the exit code we are about to read — not a crash in this process.
+      child.stdin.on('error', () => undefined);
+      child.stdin.end(stdin);
+    }
+    child.on('close', (exitCode, signal) => {
+      resolve({
+        exitCode: exitCode ?? -1,
+        signal,
+        stderr: Buffer.concat(err).toString('utf8'),
+        stdout: Buffer.concat(out).toString('utf8'),
+      });
+    });
+  });
+
+/** What the process on the far end did — or an Error, when we cannot say that it ran at all. */
+export const runRemote = async (
+  options: Required<Pick<SshRunnerOptions, 'host' | 'connectTimeoutSec' | 'execTimeoutMs'>> &
+    Pick<SshRunnerOptions, 'sshArgs'>,
+  nonce: string,
+  script: string,
+  stdin?: Uint8Array,
+): Promise<ExecResult> => {
+  const argv = sshArgv(options.host, frameScript(script, nonce), {
+    connectTimeoutSec: options.connectTimeoutSec,
+    ...(options.sshArgs === undefined ? {} : { sshArgs: options.sshArgs }),
+  });
+  const raw = await spawnSsh(argv, options.execTimeoutMs, stdin);
+  const framed = parseFramed(raw.stderr, nonce);
+  if (framed === undefined) {
+    // ⛔ The command may or may not have run. Saying "absent" here is how a dropped link becomes a
+    //   deleted config, so it is an error with ssh's own words (truncated, never the stdout).
+    throw new Error(
+      `ssh ${options.host}: the remote command did not report a status (ssh exit ` +
+        `${String(raw.exitCode)}${raw.signal === null ? '' : `, killed by ${raw.signal}`}): ` +
+        `${raw.stderr.trim().slice(0, 300)}`,
+    );
+  }
+  return { exitCode: framed.exitCode, stderr: framed.stderr, stdout: raw.stdout };
+};
+
+const decodeBase64 = (text: string): Uint8Array =>
+  new Uint8Array(Buffer.from(text.replaceAll('\n', ''), 'base64'));
+
+const failed = (host: string, what: string, result: ExecResult): Error =>
+  new Error(
+    `ssh ${host}: ${what} -> ${String(result.exitCode)}: ${result.stderr.trim().slice(0, 300)}`,
+  );
+
+/**
+ * Connect once to learn who we are, then hand back the runner.
+ * ⛔ THE PROBE IS THE FAIL-CLOSED GATE. `effectiveUid()` is synchronous on HostRunner, so the uid
+ *   must be known before the first provider call; and `uname -s` refuses a host whose `stat -c`,
+ *   `base64` and `mv -f` are not the Linux spellings this runner sends. A host that cannot answer
+ *   both is a thrown Error at construction, not a stack that half-deploys.
+ */
+export const sshRunner = async (options: SshRunnerOptions): Promise<HostRunner> => {
+  const settings = {
+    connectTimeoutSec: options.connectTimeoutSec ?? 10,
+    execTimeoutMs: options.execTimeoutMs ?? 120_000,
+    host: options.host,
+    ...(options.sshArgs === undefined ? {} : { sshArgs: options.sshArgs }),
+  };
+  const nonce = randomBytes(8).toString('hex');
+  const run = (script: string, stdin?: Uint8Array) => runRemote(settings, nonce, script, stdin);
+  const probe = await run('uname -s; id -u');
+  if (probe.exitCode !== 0) throw failed(options.host, 'uname -s; id -u', probe);
+  const [system, uid] = probe.stdout.trim().split('\n');
+  if (system !== 'Linux' || uid === undefined || !/^\d+$/.test(uid)) {
+    throw new Error(
+      `ssh ${options.host}: expected a Linux host, got ${JSON.stringify(probe.stdout.trim())}. ` +
+        'sshRunner() sends GNU/BusyBox argv (stat -c, base64, mv -f); for a Mac use localRunner().',
+    );
+  }
+  const euid = Number(uid);
+  return {
+    effectiveUid: () => euid,
+    exec: (argv) => run(execScript(argv)),
+    lookupGroup: async (nameOrId) => {
+      const result = await run(execScript(groupQuery('linux', nameOrId)));
+      return result.exitCode === 0 ? parseGroup('linux', result.stdout) : undefined;
+    },
+    lookupUser: async (nameOrId) => {
+      const result = await run(execScript(userQuery('linux', nameOrId)));
+      return result.exitCode === 0 ? parseUser('linux', result.stdout) : undefined;
+    },
+    privileged: false,
+    readFile: async (path) => {
+      const result = await run(readScript(path));
+      if (result.exitCode === ABSENT) return undefined;
+      if (result.exitCode !== 0) throw failed(options.host, `read ${path}`, result);
+      return decodeBase64(result.stdout);
+    },
+    removeFile: async (path) => {
+      const result = await run(removeScript(path));
+      if (result.exitCode !== 0) throw failed(options.host, `remove ${path}`, result);
+    },
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stat: async (path) => {
+      const result = await run(statScript(path));
+      if (result.exitCode === ABSENT) return undefined;
+      if (result.exitCode !== 0) throw failed(options.host, `stat ${path}`, result);
+      const parsed = parseStat(result.stdout);
+      // ⛔ Unparseable is an error, not "nothing there": a `stat` that printed something we do not
+      //   understand is a host this runner does not know, and guessing would write over a file.
+      if (parsed === undefined) {
+        throw new Error(`ssh ${options.host}: stat ${path} printed an unexpected shape`);
+      }
+      return parsed;
+    },
+    writeFileAtomic: async (path, bytes, write) => {
+      const at = path.lastIndexOf('/');
+      const temp = `${path.slice(0, at)}/.${path.slice(at + 1)}.${randomBytes(6).toString('hex')}.tmp`;
+      const result = await run(writeScript(path, temp, write), bytes);
+      if (result.exitCode !== 0) throw failed(options.host, `write ${path}`, result);
+    },
+  };
+};

package/src/linux/ssh-scripts.ts

@@ -0,0 +1,105 @@
+/**
+ * The four remote scripts a HostRunner needs, and the parser for the one that returns data.
+ * Pure: every shape here is asserted in ssh-scripts.test.ts without a connection.
+ *
+ * ★ MEASURED 2026-09-22 on Debian 13 (systemd 257, kernel 7.0.14-pve), read-only over ssh:
+ *     $ stat -c '%f %a %u %g %s' /etc/hostname   →  81a4 644 0 0 4          (exit 0)
+ *     $ stat -c '%f %a %u %g %s' /nonexistent    →  "cannot statx"          (exit 1)
+ *   `%f` is the RAW mode in hex, so the file type is in it (0x8000 regular, 0x4000 directory,
+ *   0xa000 symlink) and `%a` is the permission bits alone. ⛔ GNU `stat` does NOT follow symlinks
+ *   without `-L`, which is what makes this an lstat — the FileStat contract (runner.ts) requires it,
+ *   because writing through a symlink changes a file the resource never named.
+ * ⚠️ COREUTILS, NOT POSIX. `stat -c`, `base64` and `mv -f` are GNU/BusyBox spellings, not POSIX
+ *   ones; this runner is for Linux hosts and refuses anything else at the probe (ssh-runner.ts).
+ */
+import { ABSENT, quoteArgv, shellQuote } from './ssh-command.ts';
+import type { FileStat, WriteOptions } from '../launchd/runner.ts';
+
+/** ★ `-e` is false for a dangling symlink and `-L` is true for it, so both tests together mean
+ *    "something is at this path" — the question stat(2) answers and `-e` alone does not. */
+const IF_PRESENT = (path: string) => `if [ -e ${path} ] || [ -L ${path} ]; then`;
+
+export const statScript = (path: string): string => {
+  const quoted = shellQuote(path);
+  return `${IF_PRESENT(quoted)} stat -c '%f %a %u %g %s' -- ${quoted}; else exit ${String(ABSENT)}; fi`;
+};
+
+/** ★ base64 on the wire: stdout then carries no byte that a shell, a pty or a locale can alter. */
+export const readScript = (path: string): string => {
+  const quoted = shellQuote(path);
+  return `${IF_PRESENT(quoted)} base64 -- ${quoted}; else exit ${String(ABSENT)}; fi`;
+};
+
+/** ⛔ `rm -f` is idempotent for an absent path and still FAILS for a directory, which is what keeps
+ *    HostRunner.removeFile from quietly removing something that is not a file. */
+export const removeScript = (path: string): string => `rm -f -- ${shellQuote(path)}`;
+
+export const execScript = (argv: readonly string[]): string => quoteArgv(argv);
+
+/**
+ * Write bytes (fed on stdin) so `path` holds the old file or the new one and never a torn mix.
+ *
+ * ⛔ NOT `install`. GNU coreutils `install` opens the destination and writes THROUGH it — unlike
+ *   macOS's, which stages and renames — so a deploy interrupted mid-write would leave a truncated
+ *   config where a whole one used to be. Staging beside the target and `mv` (rename(2), same
+ *   directory so never EXDEV) is the only atomic spelling available over a shell.
+ * ⛔ `set -C` and `umask 077`: the staged file is created O_EXCL, so a symlink or a file planted at
+ *   the temp name is a refusal rather than a write through it, and it is unreadable by anyone else
+ *   in the moment before its mode is set.
+ * ⚠️ chown BEFORE chmod: chown by root clears setuid/setgid, so the other order silently drops a
+ *   declared 4755 — the same ordering localRunner keeps for the same reason.
+ * ⚠️ Each step removes the staged file before it fails, so a failed write leaves no litter beside
+ *   a file someone else owns.
+ */
+export const writeScript = (path: string, temp: string, options: WriteOptions): string => {
+  const target = shellQuote(path);
+  const staged = shellQuote(temp);
+  const bail = `{ rm -f -- ${staged}; exit`;
+  /**
+   * ⛔ NEVER `chown <uid>:` — GNU chown reads a trailing colon as "and that user's LOGIN GROUP",
+   *   which is a gid nobody declared. Each half is spelled only when it was asked for.
+   */
+  const owner =
+    options.uid === undefined
+      ? options.gid === undefined
+        ? undefined
+        : `:${String(options.gid)}`
+      : options.gid === undefined
+        ? String(options.uid)
+        : `${String(options.uid)}:${String(options.gid)}`;
+  const chown = owner === undefined ? [] : [`chown ${owner} -- ${staged} || ${bail} 72; }`];
+  return [
+    'set -C',
+    'umask 077',
+    `cat > ${staged} || ${bail} 71; }`,
+    ...chown,
+    `chmod ${options.mode.toString(8).padStart(3, '0')} -- ${staged} || ${bail} 73; }`,
+    `mv -f -- ${staged} ${target} || ${bail} 74; }`,
+  ].join('\n');
+};
+
+const TYPE_BITS = 0xf000;
+const KINDS = new Map<number, FileStat['kind']>([
+  [0x8000, 'file'],
+  [0x4000, 'directory'],
+  [0xa000, 'symlink'],
+]);
+
+/** `stat -c '%f %a %u %g %s'` output → a FileStat, or `undefined` when it is not that shape. */
+export const parseStat = (stdout: string): FileStat | undefined => {
+  const fields = stdout.trim().split(/\s+/);
+  if (fields.length !== 5) return undefined;
+  const [rawMode, perms, uid, gid, size] = fields as [string, string, string, string, string];
+  const raw = Number.parseInt(rawMode, 16);
+  const mode = Number.parseInt(perms, 8);
+  const numbers = [raw, mode, Number(uid), Number(gid), Number(size)];
+  if (numbers.some((value) => !Number.isSafeInteger(value) || value < 0)) return undefined;
+  return {
+    gid: Number(gid),
+    kind: KINDS.get(raw & TYPE_BITS) ?? 'other',
+    // ⚠️ `%a` alone, never `%f & 0o7777`: they agree, and the permission field is the documented one.
+    mode,
+    size: Number(size),
+    uid: Number(uid),
+  };
+};