@homeflare/alchemy 0.14.0 → 0.19.0

package/src/linux/fake-linux-host.ts

@@ -0,0 +1,197 @@
+/**
+ * An in-memory Linux host for the tests beside it: a filesystem in a Map, the four directory
+ * programs, and a systemd that behaves the way systemctl.ts measured the real one behaving.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file, it is not on the barrel, and it never touches the
+ *   real filesystem or runs a real program — which is the only way the lifecycle tests can prove
+ *   "an adopted unit is not restarted" without stopping something on a live host.
+ * ★ IT MODELS THE BEHAVIOURS THE PROVIDERS DEPEND ON: `show` of an unknown unit EXITS 0 with
+ *   `LoadState=not-found`; `enable` fails for a unit file with no `[Install]`; `NeedDaemonReload`
+ *   turns on when a unit file changes under systemd and off at `daemon-reload`; every call is
+ *   recorded in order, so a test can assert that a restart did NOT happen.
+ */
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type UnitState, fakeSystemd } from './fake-systemd.ts';
+import type {
+  ExecResult,
+  FileStat,
+  HostRunner,
+  HostUser,
+  WriteOptions,
+} from '../launchd/runner.ts';
+
+type Entry = { bytes: Uint8Array; mode: number; uid: number; gid: number; kind: FileStat['kind'] };
+
+export type FakeLinuxOptions = {
+  euid?: number;
+  privileged?: boolean;
+  /** Directories that exist, and their owner uid. Every level above one of these exists as root. */
+  dirs?: Record<string, number>;
+  users?: Record<string, HostUser>;
+  groups?: Record<string, number>;
+  /** ⛔ Make every `systemctl show` fail, to prove a failed READ refuses instead of writing. */
+  failShow?: boolean;
+};
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+const errno = (code: string, path: string) =>
+  Object.assign(new Error(`${code}: ${path}`), { code });
+const parent = (path: string) => path.slice(0, path.lastIndexOf('/')) || '/';
+const decode = (bytes: Uint8Array | undefined) =>
+  bytes === undefined ? undefined : new TextDecoder().decode(bytes);
+
+export const fakeLinuxHost = (options: FakeLinuxOptions = {}) => {
+  const euid = options.euid ?? 0;
+  const privileged = options.privileged ?? false;
+  const root = privileged || euid === 0;
+  const dirs = new Map(Object.entries(options.dirs ?? {}));
+  const files = new Map<string, Entry>();
+  const calls: string[][] = [];
+  const units = new Map<string, UnitState>();
+  const above = new Set<string>(['/']);
+  for (const dir of dirs.keys()) {
+    const parts = dir.split('/').slice(1, -1);
+    for (const index of parts.keys()) above.add(`/${parts.slice(0, index + 1).join('/')}`);
+  }
+  for (const dir of dirs.keys()) above.delete(dir);
+  const implied = (path: string) => above.has(path);
+  /** Unit name → the path its file was last written at, so `show` can find it again. */
+  const unitPaths = new Map<string, string>();
+  /** Declared directories keep their own mode and owner; implied ones are root's 0755. */
+  const modes = new Map<string, { mode: number; uid: number; gid: number }>();
+  for (const [dir, owner] of dirs) modes.set(dir, { gid: 0, mode: 0o755, uid: owner });
+
+  const digest = (text: string) => sha256Hex(new TextEncoder().encode(text));
+
+  /** ★ The default unit directory needs no registration, exactly as it needs none on a real host. */
+  const pathOf = (name: string) => unitPaths.get(name) ?? `/etc/systemd/system/${name}`;
+  const fileFor = (name: string) => decode(files.get(pathOf(name))?.bytes);
+
+  const systemctl = fakeSystemd({
+    digest,
+    failShow: options.failShow === true,
+    fileAt: (path) => decode(files.get(path)?.bytes),
+    fileFor,
+    files,
+    pathOf,
+    units,
+  });
+
+  const directoryProgram = (argv: readonly string[]): ExecResult => {
+    const [program, ...rest] = argv;
+    const path = rest.at(-1) ?? '';
+    if (program === 'mkdir') {
+      const mode = rest[0] === '-m' ? Number.parseInt(rest[1] ?? '755', 8) : 0o755;
+      if (!dirs.has(parent(path)) && !implied(parent(path))) {
+        return fail(1, `mkdir: cannot create directory '${path}': No such file or directory`);
+      }
+      if (dirs.has(path) || implied(path)) return fail(1, `mkdir: '${path}': File exists`);
+      dirs.set(path, euid);
+      modes.set(path, { gid: 0, mode, uid: euid });
+      return ok();
+    }
+    if (program === 'chmod' || program === 'chown') {
+      const live = modes.get(path);
+      if (!dirs.has(path) || live === undefined) return fail(1, `${String(program)}: ${path}`);
+      if (program === 'chmod') live.mode = Number.parseInt(rest[0] ?? '755', 8);
+      else {
+        if (!root) return fail(1, `chown: ${path}: Operation not permitted`);
+        const [uid, gid] = (rest[0] ?? '').split(':');
+        if (uid !== undefined && uid !== '') live.uid = Number(uid);
+        if (gid !== undefined && gid !== '') live.gid = Number(gid);
+      }
+      return ok();
+    }
+    if (program === 'rmdir') {
+      if (!dirs.has(path)) return fail(1, `rmdir: '${path}': No such file or directory`);
+      if ([...files.keys()].some((file) => parent(file) === path)) {
+        return fail(1, `rmdir: failed to remove '${path}': Directory not empty`);
+      }
+      dirs.delete(path);
+      modes.delete(path);
+      return ok();
+    }
+    return fail(127, `fake: no program ${String(program)}`);
+  };
+
+  const runner: HostRunner = {
+    effectiveUid: () => euid,
+    exec: async (argv) => {
+      calls.push([...argv]);
+      if (argv[0] === 'systemctl') return systemctl(argv.slice(1).filter((arg) => arg !== '--'));
+      if (argv[0] === 'getent') return fail(2, 'getent: not modelled');
+      return directoryProgram(argv.filter((arg) => arg !== '--'));
+    },
+    lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
+    lookupUser: async (nameOrId) =>
+      options.users?.[nameOrId] ??
+      Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    privileged,
+    readFile: async (path) => files.get(path)?.bytes,
+    removeFile: async (path) => {
+      if (files.has(path) && (dirs.get(parent(path)) ?? 0) !== euid && !root) {
+        throw errno('EACCES', path);
+      }
+      files.delete(path);
+    },
+    sleep: async () => undefined,
+    stat: async (path) => {
+      const entry = files.get(path);
+      if (entry !== undefined) {
+        return {
+          gid: entry.gid,
+          kind: entry.kind,
+          mode: entry.mode,
+          size: entry.bytes.length,
+          uid: entry.uid,
+        };
+      }
+      const live = modes.get(path);
+      if (live !== undefined) return { ...live, kind: 'directory', size: 0 };
+      if (implied(path)) return { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: 0 };
+      return undefined;
+    },
+    writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
+      calls.push(['write', path]);
+      const owner = modes.get(parent(path))?.uid ?? (implied(parent(path)) ? 0 : undefined);
+      if (owner === undefined) throw errno('ENOENT', parent(path));
+      if (owner !== euid && !root) throw errno('EACCES', path);
+      if (write.uid !== undefined && write.uid !== euid && !root) throw errno('EPERM', path);
+      files.set(path, {
+        bytes,
+        gid: write.gid ?? 0,
+        kind: 'file',
+        mode: write.mode,
+        uid: write.uid ?? euid,
+      });
+    },
+  };
+
+  /** Put a unit on the host the way a package or a person would, outside any declaration. */
+  const placeUnit = (path: string, text: string, state: Partial<UnitState> = {}) => {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    files.set(path, {
+      bytes: new TextEncoder().encode(text),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    unitPaths.set(name, path);
+    modes.set(path.slice(0, path.lastIndexOf('/')) || '/', { gid: 0, mode: 0o755, uid: 0 });
+    units.set(name, {
+      active: state.active ?? false,
+      enabled: state.enabled ?? false,
+      loadedSha: state.loadedSha === undefined ? digest(text) : state.loadedSha,
+      ...(state.masked === undefined ? {} : { masked: state.masked }),
+    });
+  };
+
+  /** Tell the fake systemd which file a unit name belongs to, before that file exists. */
+  const expectUnit = (path: string) => {
+    unitPaths.set(path.slice(path.lastIndexOf('/') + 1), path);
+  };
+
+  return { calls, dirs, expectUnit, files, modes, placeUnit, runner, units };
+};

package/src/linux/fake-systemd.ts

@@ -0,0 +1,103 @@
+/**
+ * The systemd half of the fake Linux host: a `systemctl` that behaves the way systemctl.ts measured
+ * the real one behaving. ⛔ TEST-ONLY, and not on the barrel.
+ *
+ * ★ THE ONE BEHAVIOUR EVERYTHING ELSE RESTS ON: `show` of a unit that does not exist EXITS 0 and
+ *   answers `LoadState=not-found`. A fake that returned an error there would let a provider bug
+ *   through that reads the exit code instead of the load state — which is the bug the real host's
+ *   measurement exists to prevent.
+ */
+import type { ExecResult } from '../launchd/runner.ts';
+
+export type UnitState = {
+  /** What systemd has loaded; `undefined` once it has been unloaded. */
+  loadedSha: string | undefined;
+  active: boolean;
+  enabled: boolean;
+  masked?: boolean;
+};
+
+export type FakeSystemdDeps = {
+  readonly units: Map<string, UnitState>;
+  /** Every unit-file path the host holds, so a reload can notice a new one. */
+  readonly files: { keys: () => Iterable<string> };
+  /** The text of a unit's file, or `undefined` when it has none. */
+  readonly fileFor: (name: string) => string | undefined;
+  /** The text at one path, for the reload sweep. */
+  readonly fileAt: (path: string) => string | undefined;
+  readonly pathOf: (name: string) => string;
+  readonly digest: (text: string) => string;
+  /** ⛔ Make every `show` fail, to prove a failed READ refuses instead of writing. */
+  readonly failShow: boolean;
+};
+
+const ok = (stdout = ''): ExecResult => ({ exitCode: 0, stderr: '', stdout });
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+export const fakeSystemd = (deps: FakeSystemdDeps) => {
+  return (args: readonly string[]): ExecResult => {
+    const verb = args[0];
+    const name = args.at(-1) ?? '';
+    const state = deps.units.get(name);
+    const onDisk = deps.fileFor(name);
+    if (verb === 'show') {
+      // ⛔ MEASURED: exit 0 even for a unit that does not exist.
+      if (deps.failShow) return fail(1, 'Failed to connect to bus: No such file');
+      const known = state !== undefined || onDisk !== undefined;
+      const loaded = state?.loadedSha !== undefined;
+      return ok(
+        [
+          `Id=${name}`,
+          `LoadState=${state?.masked === true ? 'masked' : known && loaded ? 'loaded' : 'not-found'}`,
+          `ActiveState=${state?.active === true ? 'active' : 'inactive'}`,
+          `SubState=${state?.active === true ? 'running' : 'dead'}`,
+          `UnitFileState=${state?.masked === true ? 'masked' : onDisk === undefined ? '' : state?.enabled === true ? 'enabled' : 'disabled'}`,
+          `FragmentPath=${onDisk === undefined ? '' : deps.pathOf(name)}`,
+          `NeedDaemonReload=${onDisk !== undefined && state?.loadedSha !== deps.digest(onDisk) && loaded ? 'yes' : 'no'}`,
+        ].join('\n'),
+      );
+    }
+    if (verb === 'daemon-reload') {
+      for (const [unit, current] of deps.units) {
+        const text = deps.fileFor(unit);
+        if (text !== undefined) current.loadedSha = deps.digest(text);
+        // ★ A unit whose file is gone and that is not running stops being a unit systemd knows.
+        else if (!current.active) deps.units.delete(unit);
+      }
+      // ★ A unit file that appeared since the last reload becomes a unit systemd knows about.
+      for (const path of deps.files.keys()) {
+        const unit = path.slice(path.lastIndexOf('/') + 1);
+        const text = deps.fileAt(path);
+        if (text !== undefined && deps.pathOf(unit) === path && !deps.units.has(unit)) {
+          deps.units.set(unit, { active: false, enabled: false, loadedSha: deps.digest(text) });
+        }
+      }
+      return ok();
+    }
+    const current = deps.units.get(name);
+    if (current === undefined || onDisk === undefined) {
+      return fail(5, `Failed to ${String(verb)} ${name}: Unit ${name} not found.`);
+    }
+    if (current.masked === true) return fail(1, `Unit ${name} is masked.`);
+    if (verb === 'enable') {
+      if (!onDisk.includes('[Install]')) {
+        return fail(1, `The unit files have no installation config (WantedBy=, ...).`);
+      }
+      current.enabled = true;
+      return ok();
+    }
+    if (verb === 'disable') {
+      current.enabled = false;
+      return ok();
+    }
+    if (verb === 'start' || verb === 'restart') {
+      current.active = true;
+      return ok();
+    }
+    if (verb === 'stop') {
+      current.active = false;
+      return ok();
+    }
+    return fail(64, `fake systemctl: unsupported ${args.join(' ')}`);
+  };
+};

package/src/linux/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Linux host providers for Alchemy — a host's directories, its files (whole, or one managed block
+ * inside somebody else's file) and its systemd units, over the SAME HostRunner seam the launchd
+ * subpath drives a Mac through.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle
+ *   files, the systemctl parsers and the fake host are internals; an `export *` would publish them
+ *   as API and make the next refactor a breaking change.
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS: a unit is restarted only when its own file changed, or a digest
+ *   the declaration listed changed. See docs/linux-host.md.
+ * ★ THE SEAM IS SHARED, NOT COPIED. `HostRunner` is re-exported here so a Linux stack never has to
+ *   import from the launchd subpath to type its own runner.
+ */
+export type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+export { HostDirectory, HostDirectoryProvider } from './directory.ts';
+export { linuxProviders } from './providers.ts';
+export type { RegionSpec } from './region.ts';
+export type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+export { RemoteFile, RemoteFileProvider } from './remote-file.ts';
+export type { SshRunnerOptions } from './ssh-runner.ts';
+export { sshRunner } from './ssh-runner.ts';
+export type {
+  ExecResult,
+  FileStat,
+  HostRunner,
+  HostUser,
+  WriteOptions,
+} from '../launchd/runner.ts';
+export { HostRunnerService, canActAsRoot, hostRunnerLayer } from '../launchd/runner.ts';
+export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
+export { DEFAULT_UNIT_DIRECTORY, renderUnit } from './unit-form.ts';
+export { SystemdTimer, SystemdTimerProvider, SystemdUnit, SystemdUnitProvider } from './unit.ts';

package/src/linux/providers.ts

@@ -0,0 +1,26 @@
+/**
+ * Every provider in this subpath with ONE HostRunner, as a single layer for a host stack.
+ *
+ *     const runner = await sshRunner({ host: 'the-host' });
+ *     Layer.mergeAll(linuxProviders(runner), …the stack's other providers)
+ *
+ * ★ ONE RUNNER FOR ALL OF THEM, so a directory, the config file inside it and the unit that reads
+ *   that file are written by the same identity on the same host — a stack cannot create the
+ *   directory on one host and start the unit on another by accident.
+ * ⛔ THERE IS NO DEFAULT. launchdProviders() defaults to localRunner() because a Mac stack runs on
+ *   the Mac it declares; a Linux host is somewhere else, and a silent default to "this machine"
+ *   would write the estate's `/etc/systemd/system` onto the laptop running the deploy.
+ */
+import * as Layer from 'effect/Layer';
+import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { HostDirectoryProvider } from './directory.ts';
+import { RemoteFileProvider } from './remote-file.ts';
+import { SystemdTimerProvider, SystemdUnitProvider } from './unit.ts';
+
+export const linuxProviders = (runner: HostRunner) =>
+  Layer.mergeAll(
+    HostDirectoryProvider(),
+    RemoteFileProvider(),
+    SystemdTimerProvider(),
+    SystemdUnitProvider(),
+  ).pipe(Layer.provide(hostRunnerLayer(runner)));

package/src/linux/region.test.ts

@@ -0,0 +1,89 @@
+/**
+ * The managed region, byte for byte. ⛔ The load-bearing assertion in this file is that everything
+ *   outside the markers is IDENTICAL — not similar, not re-terminated. Every consumer of this mode
+ *   owns four lines inside a file that belongs to a vendor, a package or a person.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readRegion, regionProblems, removeRegion, spliceRegion } from './region.ts';
+
+const spec = { name: 'homeflare-example' };
+const HOST_FILE = [
+  '# Loopback, from the OS vendor',
+  '127.0.0.1\tlocalhost',
+  '::1\t\tlocalhost ip6-localhost',
+  '',
+  '10.0.0.1\tsomething.invalid',
+  '',
+].join('\n');
+
+describe('splice', () => {
+  test('appends the block and leaves every other byte identical', () => {
+    const next = spliceRegion(HOST_FILE, spec, '10.0.0.2\tdeclared.invalid\n');
+    expect(next.startsWith(HOST_FILE)).toBe(true);
+    expect(next.slice(HOST_FILE.length)).toBe(
+      '# BEGIN homeflare-example\n10.0.0.2\tdeclared.invalid\n# END homeflare-example\n',
+    );
+  });
+
+  test('replaces the block in place, and the surroundings survive a rewrite', () => {
+    const once = spliceRegion(HOST_FILE, spec, 'one\n');
+    const twice = spliceRegion(once, spec, 'two\nthree\n');
+    expect(readRegion(twice, spec)).toBe('two\nthree\n');
+    expect(removeRegion(twice, spec)).toBe(HOST_FILE);
+    // ★ The block stayed where it was: nothing after it moved above it.
+    expect(twice.indexOf('# BEGIN')).toBe(once.indexOf('# BEGIN'));
+  });
+
+  test('a file with no final newline gets exactly one, and nothing else', () => {
+    const next = spliceRegion('alpha', spec, 'body\n');
+    expect(next).toBe('alpha\n# BEGIN homeflare-example\nbody\n# END homeflare-example\n');
+  });
+
+  test('an empty body is still a block, so the markers hold the place', () => {
+    const next = spliceRegion('', spec, '');
+    expect(next).toBe('# BEGIN homeflare-example\n# END homeflare-example\n');
+    expect(readRegion(next, spec)).toBe('');
+  });
+
+  test('the comment token is the host file’s own', () => {
+    const next = spliceRegion('// vendor\n', { comment: '//', name: 'block' }, 'x\n');
+    expect(next).toBe('// vendor\n// BEGIN block\nx\n// END block\n');
+  });
+
+  test('two blocks in one file do not see each other', () => {
+    const first = spliceRegion(HOST_FILE, { name: 'a' }, 'alpha\n');
+    const both = spliceRegion(first, { name: 'b' }, 'beta\n');
+    expect(readRegion(both, { name: 'a' })).toBe('alpha\n');
+    expect(readRegion(both, { name: 'b' })).toBe('beta\n');
+    expect(removeRegion(removeRegion(both, { name: 'b' }), { name: 'a' })).toBe(HOST_FILE);
+  });
+});
+
+describe('refusals', () => {
+  const half = '# BEGIN homeflare-example\nbody\n';
+  test('a BEGIN with no END is a refusal, not a guess', () => {
+    expect(() => readRegion(half, spec)).toThrow(/BEGIN marker and no match/);
+  });
+
+  test('an END before its BEGIN is a refusal', () => {
+    const broken = '# END homeflare-example\nbody\n# BEGIN homeflare-example\n';
+    expect(() => readRegion(broken, spec)).toThrow(/END marker before its BEGIN/);
+  });
+
+  test('two BEGIN markers name the lines rather than picking one', () => {
+    const doubled = `${half}# END homeflare-example\n${half}# END homeflare-example\n`;
+    expect(() => spliceRegion(doubled, spec, 'x\n')).toThrow(/two BEGIN markers .*lines 1, 4/);
+  });
+
+  test('a name or comment that could not be found verbatim is refused up front', () => {
+    expect(regionProblems({ name: 'has\nnewline' })).toHaveLength(1);
+    expect(regionProblems({ comment: '# ', name: 'ok' })).toHaveLength(1);
+    expect(regionProblems({ comment: ';', name: 'ok-1' })).toEqual([]);
+  });
+});
+
+describe('remove', () => {
+  test('is a no-op when the block is not there', () => {
+    expect(removeRegion(HOST_FILE, spec)).toBe(HOST_FILE);
+  });
+});

package/src/linux/region.ts

@@ -0,0 +1,118 @@
+/**
+ * A MANAGED REGION: a block a resource owns inside a file it does not own.
+ *
+ * ★ WHY THIS EXISTS. Four files on this estate are owned by something else and still need one
+ *   declared block: a packet-filter anchor line inside the OS vendor's own ruleset, a host table,
+ *   a generated Nix module, and an operator's ssh config. Declaring the WHOLE file would mean
+ *   taking it from its owner — which puts it back, or refuses its next activation. So the resource
+ *   owns the lines between two markers and promises that every other byte is untouched.
+ * ⛔ THE REST OF THE FILE IS BYTE-IDENTICAL. Not "semantically the same", not re-indented, not
+ *   re-terminated: the bytes before the BEGIN line and after the END line are copied through. That
+ *   is the property region.test.ts asserts, because it is the whole reason the other owner tolerates
+ *   this.
+ * ⛔ AMBIGUITY IS A REFUSAL, NEVER A GUESS. Two BEGIN markers with the same name, an END before its
+ *   BEGIN, or a BEGIN with no END all mean someone edited inside the block. Picking one would
+ *   silently delete their edit, so each is an Error naming the line.
+ * ★ THE MARKER IS A COMMENT IN THE HOST FILE'S OWN LANGUAGE, which is why the comment token is a
+ *   prop: `#` covers the four consumers above, and a file whose comments are `//` or `;` says so.
+ */
+
+export type RegionSpec = {
+  /** Distinguishes this block from any other managed block in the same file. */
+  readonly name: string;
+  /** The file's comment token. @default '#' */
+  readonly comment?: string;
+};
+
+export const DEFAULT_COMMENT = '#';
+
+const tokens = (spec: RegionSpec) => {
+  const comment = spec.comment ?? DEFAULT_COMMENT;
+  return {
+    begin: `${comment} BEGIN ${spec.name}`,
+    end: `${comment} END ${spec.name}`,
+  };
+};
+
+export const regionProblems = (spec: RegionSpec): string[] => {
+  const found: string[] = [];
+  const comment = spec.comment ?? DEFAULT_COMMENT;
+  if (!/^\S{1,4}$/.test(comment) || comment.includes('\u0000')) {
+    found.push('region comment must be 1–4 non-space characters');
+  }
+  // ⛔ A marker must be one line and must be findable verbatim; a name with a newline would split
+  //   it, and leading or trailing space would not match what we later search for.
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._:@/-]{0,79}$/.test(spec.name)) {
+    found.push('region name must be 1–80 printable characters and start alphanumeric');
+  }
+  return found;
+};
+
+const refuse = (message: string): Error => new Error(`managed region: ${message}`);
+
+const duplicate = (what: string, at: readonly number[], line: string): Error =>
+  refuse(
+    `${what} for ${JSON.stringify(line)} (lines ${at.map((index) => index + 1).join(', ')}). ` +
+      'Remove the duplicate; this resource will not choose between them.',
+  );
+
+/** Where the block sits: the line indices of its markers, or `undefined` when it is not there. */
+const locate = (lines: readonly string[], spec: RegionSpec) => {
+  const { begin, end } = tokens(spec);
+  const begins = lines.flatMap((line, index) => (line === begin ? [index] : []));
+  const ends = lines.flatMap((line, index) => (line === end ? [index] : []));
+  if (begins.length > 1) throw duplicate('two BEGIN markers', begins, begin);
+  if (ends.length > 1) throw duplicate('two END markers', ends, end);
+  const [from] = begins;
+  const [to] = ends;
+  if (from === undefined && to === undefined) return undefined;
+  if (from === undefined || to === undefined) {
+    throw refuse(
+      `${JSON.stringify(spec.name)} has a ${from === undefined ? 'END' : 'BEGIN'} marker and no ` +
+        'match. Repair the file by hand — a half-marked block means an edit inside it.',
+    );
+  }
+  if (to < from) throw refuse(`${JSON.stringify(spec.name)} has its END marker before its BEGIN`);
+  return { from, to };
+};
+
+/**
+ * The file's bytes with the block set to `body`, appended at the end when it is not there yet.
+ * ⚠️ A file that does not end in a newline gets one before the block is appended — the ONLY byte
+ *   this function adds outside its own block, and without it the last existing line and the BEGIN
+ *   marker would become one line.
+ */
+export const spliceRegion = (file: string, spec: RegionSpec, body: string): string => {
+  const { begin, end } = tokens(spec);
+  // ★ A body is stored as whole lines: exactly one newline after the last one, none doubled.
+  const block = [begin, ...(body === '' ? [] : body.replace(/\n$/, '').split('\n')), end];
+  const lines = file.split('\n');
+  const found = locate(lines, spec);
+  if (found !== undefined) {
+    return [...lines.slice(0, found.from), ...block, ...lines.slice(found.to + 1)].join('\n');
+  }
+  const prefix = file === '' || file.endsWith('\n') ? file : `${file}\n`;
+  return `${prefix}${block.join('\n')}\n`;
+};
+
+/** The block's body, or `undefined` when the file has no such block. */
+export const readRegion = (file: string, spec: RegionSpec): string | undefined => {
+  const lines = file.split('\n');
+  const found = locate(lines, spec);
+  if (found === undefined) return undefined;
+  const body = lines.slice(found.from + 1, found.to);
+  return body.length === 0 ? '' : `${body.join('\n')}\n`;
+};
+
+/**
+ * The file with the block and both markers removed — what a delete leaves behind.
+ * ★ Byte-for-byte the file as it was before the block was appended, with one exception already
+ *   named on `spliceRegion`: a file that had no final newline when the block was added keeps the
+ *   newline that adding it required. Nothing else is added or dropped.
+ */
+export const removeRegion = (file: string, spec: RegionSpec): string => {
+  const lines = file.split('\n');
+  const found = locate(lines, spec);
+  if (found === undefined) return file;
+  return [...lines.slice(0, found.from), ...lines.slice(found.to + 1)].join('\n');
+};

package/src/linux/remote-file-form.ts

@@ -0,0 +1,96 @@
+/**
+ * RemoteFile's props, attributes and validation — the pure half of the provider.
+ *
+ * ⛔ `content` IS NEVER A SECRET, for the same reason it is not on HostFile: Alchemy stores props
+ *   unencrypted, so every byte here sits in the state store and in every plan diff. A secret file
+ *   stays rendered at run time by a secret renderer; a stack declares at most the PATH it writes to.
+ *   secret-tripwire.ts refuses the obvious case and catches nothing subtle.
+ * ★ TWO MODES, ONE RESOURCE. Without `region` this owns the whole file, exactly as HostFile does on
+ *   a Mac. With `region` it owns only the lines between two markers and promises every other byte
+ *   is untouched (region.ts) — which is the only way to declare a block inside a file another tool,
+ *   a vendor package or a person owns.
+ */
+import { pathProblems } from '../launchd/host-file-form.ts';
+import { fileSecretProblems } from '../launchd/secret-tripwire.ts';
+import { type RegionSpec, regionProblems } from './region.ts';
+
+export interface RemoteFileProps {
+  /** Absolute path on the host. ⚠️ The parent directory must exist — declare a HostDirectory. */
+  path: string;
+  /** UTF-8 text: the whole file, or the region's body. ⛔ Never a secret — see the file header. */
+  content: string;
+  /**
+   * Own a block inside a file this resource does not own, instead of the whole file.
+   * ⛔ In region mode `mode`, `owner` and `group` apply ONLY to a file this resource creates: an
+   *   existing file keeps the mode and ownership its owner gave it, because changing them would be
+   *   a second, undeclared claim on a file we only borrowed four lines of.
+   */
+  region?: RegionSpec;
+  /**
+   * Create the file when it is absent. Region mode only; whole-file mode always creates.
+   * ⛔ Default `false`: a region declared against a path that does not exist is far more often a
+   *   typo (a wrong `/etc` path) than an intention, and creating it would hide the typo.
+   */
+  create?: boolean;
+  /** Permission bits. @default 0o644 */
+  mode?: number;
+  /** User name or numeric uid. Omitted: whoever the runner writes as. */
+  owner?: string | number;
+  /** Group name or numeric gid. Omitted: the directory's default group. */
+  group?: string | number;
+}
+
+export interface RemoteFileAttributes {
+  path: string;
+  /** SHA-256 of the WHOLE file on disk, in both modes. */
+  sha256: string;
+  /** SHA-256 of the part this resource owns — in region mode, of the region's body alone. */
+  contentSha256: string;
+  /**
+   * The block this resource owns, when it owns only a block.
+   * ⛔ IT IS IN THE ATTRIBUTES ON PURPOSE. Alchemy's `delete` handler is given the attributes and
+   *   nothing else, and without the marker name a delete could not find the block — it could only
+   *   delete the whole file, which belongs to someone else.
+   */
+  region?: RegionSpec;
+  mode: number;
+  uid: number;
+  gid: number;
+  size: number;
+}
+
+export const DEFAULT_MODE = 0o644;
+
+const identityProblems = (name: string, value: string | number | undefined): string[] => {
+  if (value === undefined) return [];
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value >= 0
+      ? []
+      : [`${name} must be a non-negative integer id`];
+  }
+  return /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(value) || /^\d+$/.test(value)
+    ? []
+    : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
+};
+
+export const fileProblems = (props: RemoteFileProps): string[] => {
+  const found = pathProblems(props.path);
+  const mode = props.mode ?? DEFAULT_MODE;
+  if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
+  found.push(...identityProblems('owner', props.owner));
+  found.push(...identityProblems('group', props.group));
+  found.push(...fileSecretProblems(props.content));
+  if (props.region !== undefined) {
+    found.push(...regionProblems(props.region));
+    // ⛔ Say it at plan time rather than let a deploy silently ignore the prop: in region mode
+    //   these describe a file we do not own, and they are honoured only for a `create`.
+    if (props.create !== true && (props.mode !== undefined || props.owner !== undefined)) {
+      found.push(
+        'mode and owner apply only to a file this resource creates; drop them, or set create: true',
+      );
+    }
+  } else if (props.create === true) {
+    found.push('create is for region mode only; a whole-file declaration always creates the file');
+  }
+  return found;
+};