@gjermundgaraba/clankerbox-sdk 0.15.2 → 0.15.4

package/dist/{client-SX6jTU1R.d.mts → client-Cn1bj4It.d.mts}

@@ -297,6 +297,11 @@ interface Interface {
   readonly capacity: Effect.Effect<Gathered<Limit>>;
   readonly machine: (id: string) => Effect.Effect<Machine, ClankerboxError>;
   readonly checkpoint: (id: string) => Effect.Effect<Checkpoint, ClankerboxError>;
+  /**
+   * The host a create of `base` goes to: the options' host, or else the first host in the list
+   * that offers the base. It is read either way, so a caller knows its runtime before it creates.
+   */
+  readonly place: (base: string, options?: CreateOptions) => Effect.Effect<Host, ClankerboxError>;
   /**
    * Creates a machine named `name` on the options' host, or else on the first host in the
    * list that offers the spec's base.
@@ -320,4 +325,4 @@ declare class Client extends Client_base {}
  */
 declare const make: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Effect.Effect<Interface, Invalid, HttpClient.HttpClient>;
 //#endregion
-export { Precondition as A, ConflictKind as C, Internal as D, HostErrorTag as E, hostErrors as M, Invalid as O, Conflict as S, HostError as T, SshLogin as _, ActionName as a, Capacity as b, CreateRequest as c, Machine as d, MachineSpec as f, SshEndpoint as g, Setup as h, client_d_exports as i, Unavailable as j, NotFound as k, Host as l, Runtime as m, HostEntry as n, ActionRecord as o, Profile as p, Options as r, Checkpoint as s, Client as t, Limit as u, release as v, ErrorTag as w, ClankerboxError as x, version as y };
+export { Invalid as A, ClankerboxError as C, HostError as D, ErrorTag as E, Precondition as M, Unavailable as N, HostErrorTag as O, hostErrors as P, Capacity as S, ConflictKind as T, Setup as _, Options as a, release as b, ActionRecord as c, Host as d, Limit as f, Runtime as g, Profile as h, Interface as i, NotFound as j, Internal as k, Checkpoint as l, MachineSpec as m, CreateOptions as n, client_d_exports as o, Machine as p, HostEntry as r, ActionName as s, Client as t, CreateRequest as u, SshEndpoint as v, Conflict as w, version as x, SshLogin as y };

package/dist/{client-cFk3r2_1.mjs → client-pUFgD6Xz.mjs}

@@ -129,7 +129,7 @@ const formatId = (host, name) => {
 };
 //#endregion
 //#region package.json
-var version$1 = "0.15.2";
+var version$1 = "0.15.4";
 //#endregion
 //#region src/resources.ts
 /** The resources a host reports: machines, checkpoints and the host itself. */
@@ -598,7 +598,7 @@ const make = (hosts, options) => Effect.gen(function* () {
 	* silent host after it delays nothing. With no winner the create is `Unavailable` only if
 	* a host gave no reply; otherwise asking again changes nothing, and it is `Precondition`.
 	*/
-	const place = (base) => Effect.gen(function* () {
+	const offering = (base) => Effect.gen(function* () {
 		const asked = yield* Effect.forEach(routed, (route) => Effect.map(Effect.forkScoped(Effect.result(readHost(route))), (fiber) => ({
 			host: route.entry.id,
 			fiber
@@ -611,7 +611,7 @@ const make = (hosts, options) => Effect.gen(function* () {
 			if (Result.isFailure(result)) {
 				noReply ||= Predicate.isTagged(result.failure, "Unavailable");
 				misses.push(`${host} failed: ${result.failure.message}`);
-			} else if (result.success.bases.includes(base)) return host;
+			} else if (result.success.bases.includes(base)) return result.success;
 			else {
 				const { bases } = result.success;
 				misses.push(`${host} offers ${bases.length > 0 ? bases.join(", ") : "no bases"}`);
@@ -626,8 +626,9 @@ const make = (hosts, options) => Effect.gen(function* () {
 	const create = (name, spec, options) => Effect.gen(function* () {
 		yield* parseName(name);
 		if (options?.host !== void 0) return yield* createOn(options.host, name, spec);
-		return yield* createOn(yield* place(spec.base), name, spec);
+		return yield* createOn((yield* offering(spec.base)).id, name, spec);
 	});
+	const place = (base, options) => options?.host === void 0 ? offering(base) : Effect.flatMap(route(options.host), readHost);
 	/** The ID a call that makes a resource on `source`'s host gives it. */
 	const sibling = (source, name) => Effect.flatMap(parseId(source), ({ host }) => formatId(host, name));
 	return {
@@ -637,6 +638,7 @@ const make = (hosts, options) => Effect.gen(function* () {
 		capacity: gather((route) => ask(route, actions.getCapacity, "get capacity", (api) => api.getCapacity())),
 		machine: (id) => byId(id, actions.getMachine, `get ${id}`, (api) => api.getMachine({ id })),
 		checkpoint: (id) => byId(id, actions.getCheckpoint, `get ${id}`, (api) => api.getCheckpoint({ id })),
+		place,
 		create,
 		start: (id) => byId(id, actions.startMachine, `start ${id}`, (api) => api.startMachine({ id })),
 		stop: (id) => byId(id, actions.stopMachine, `stop ${id}`, (api) => api.stopMachine({ id })),

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { A as Precondition, C as ConflictKind, D as Internal, E as HostErrorTag, M as hostErrors, O as Invalid, S as Conflict, T as HostError, _ as SshLogin, a as ActionName, b as Capacity, c as CreateRequest, d as Machine, f as MachineSpec, g as SshEndpoint, h as Setup, i as client_d_exports, j as Unavailable, k as NotFound, l as Host, m as Runtime, o as ActionRecord, p as Profile, s as Checkpoint, u as Limit, v as release, w as ErrorTag, x as ClankerboxError, y as version } from "./client-SX6jTU1R.mjs";
+import { A as Invalid, C as ClankerboxError, D as HostError, E as ErrorTag, M as Precondition, N as Unavailable, O as HostErrorTag, P as hostErrors, S as Capacity, T as ConflictKind, _ as Setup, b as release, c as ActionRecord, d as Host, f as Limit, g as Runtime, h as Profile, i as Interface, j as NotFound, k as Internal, l as Checkpoint, m as MachineSpec, n as CreateOptions, o as client_d_exports, p as Machine, s as ActionName, u as CreateRequest, v as SshEndpoint, w as Conflict, x as version, y as SshLogin } from "./client-Cn1bj4It.mjs";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { Duration, Effect, FileSystem, Path, PlatformError, Schema } from "effect";
-import { ChildProcessSpawner } from "effect/process";
+import { Duration, Effect, FileSystem, Path, PlatformError, Schema, Scope } from "effect";
 //#region src/api.d.ts
 /**
  * How long a client waits for a read's reply from one host, unless it sets its own. A host
@@ -307,6 +306,54 @@ export declare const parseId: (id: string) => Effect.Effect<IdParts, Invalid>;
 export declare const parseName: (name: string) => Effect.Effect<string, Invalid>;
 /** Joins a host ID and a name into the resource's ID, checking both parts and the whole. */
 export declare const formatId: (host: string, name: string) => Effect.Effect<string, Invalid>;
+declare namespace prebuild_d_exports {
+  export { Built, Created, build, create, nameOf };
+}
+/**
+ * The name of the spec's prebuild on a host: a digest of the spec's label, base and sizes, the
+ * setup script as sent, and the host's runtime version. A `ram` checkpoint restores only under
+ * the release that saved it, so after a runtime bump a create misses the old prebuild instead
+ * of failing to restore it. The setup's timeout is no part of it, and neither is the base's
+ * image: a host only names it. The script holds whatever secrets a recipe carries, and the name
+ * 12 hex characters of a digest of it.
+ */
+declare const nameOf: (spec: MachineSpec, host: Pick<Host, "runtimeVersion">) => Effect.Effect<string>;
+interface Created {
+  readonly machine: Machine;
+  /** The prebuild the machine was restored from; without one, its setup ran. */
+  readonly prebuild?: Checkpoint | undefined;
+}
+/**
+ * Creates a machine named `name` as `client.create` does, but restores it from the spec's
+ * prebuild when the host it lands on has one whose capture is done. A spec without a setup has
+ * none. Placement is the create's own, and a prebuild stays on the host that made it, so a spec
+ * placed on another host runs its setup. A failed restore is the reply.
+ */
+declare const create: (client: Interface, name: string, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Created, ClankerboxError>;
+interface Built {
+  readonly checkpoint: Checkpoint;
+  /** Whether this call built it; false when it was already there. */
+  readonly built: boolean;
+  /**
+   * The ID of the machine that built it, when its delete failed: it may still run, holding its
+   * RAM, until it is deleted.
+   */
+  readonly leftover?: string | undefined;
+}
+/**
+ * Builds the spec's prebuild on the host a create of it lands on: a machine of its own runs the
+ * setup, is captured under the prebuild's name, and is deleted. smolvm captures a running
+ * machine, RAM included, and boat a running one too; Tart only a stopped one, so its machine is
+ * stopped first. A prebuild whose capture is done is the answer as it is; one that failed or is
+ * still captured is refused.
+ *
+ * Each build's machine has a random name of its own, and the host takes a checkpoint name once,
+ * so of two builds of one spec at once both run the setup and the second's capture is
+ * `Conflict`: neither touches the other's machine or prebuild. A build deletes its machine
+ * however it ends. If that fails after a failure, the first failure is the reply; after a
+ * capture, the prebuild is made, and the machine is the reply's `leftover`.
+ */
+declare const build: (client: Interface, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Built, ClankerboxError>;
 //#endregion
 //#region src/profile.d.ts
 /** A profile file as read: its fields, with `setup.path` resolved, and its name as `label`. */
@@ -322,13 +369,39 @@ export declare const loadProfile: (file: string) => Effect.Effect<LoadedProfile,
 //#endregion
 //#region src/setup.d.ts
 /**
- * Packs a recipe directory into one self-extracting script: a base64 tar that unpacks into a
- * temporary directory, then runs `setup.sh` from there. `COPYFILE_DISABLE=1` and
- * `--no-xattrs` keep macOS `tar` from adding `._*` files and provenance headers.
+ * Packs a recipe directory into one self-extracting script, which makes each of its entries
+ * with plain shell: a directory with `mkdir`, a symlink with `ln -s` as it is, and a file from
+ * base64, made executable when any of its execute bits is set. A symlink is never walked into,
+ * so nothing outside the recipe is packed, and in the guest nothing is written through one.
+ * Of a mode only the execute bit is kept, as git keeps it, so a checkout's umask changes
+ * nothing. Entries go in sorted order and nothing records a time or an owner, so the same
+ * files pack into the same script: a prebuild is named after it.
  */
-export declare const packRecipe: (directory: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner>;
+export declare const packRecipe: (directory: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
 /** Reads a setup: a script file's text, or a recipe directory packed into one script. */
-export declare const readSetup: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner>;
+export declare const readSetup: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
+//#endregion
+//#region src/ssh.d.ts
+/** What ssh needs of a machine: where it is reached, as whom, and the host key to pin. */
+export interface SshTarget {
+  readonly id: string;
+  readonly login: SshLogin;
+  readonly hostKey: string;
+}
+/**
+ * The machine's SSH target, or what it lacks: an endpoint, which only a running machine has, or
+ * a host key, which preparation records.
+ */
+export declare const sshTarget: (machine: Machine) => SshTarget | {
+  readonly lacks: "SSH endpoint" | "SSH host key on record";
+};
+/**
+ * Writes a one-line known-hosts file pinning the target's host key, and returns the arguments
+ * that run ssh against it with strict host key checking, as `user`. The file lasts as long as
+ * the scope, which must outlast the ssh it is for. Ports change on fork and restore, and on
+ * boat at every start, so a target is read anew for each ssh.
+ */
+export declare const pinnedSsh: (target: SshTarget, user: string, extra: ReadonlyArray<string>) => Effect.Effect<Array<string>, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
 //#endregion
 //#region src/text.d.ts
 /**
@@ -347,4 +420,4 @@ export declare const describeIssues: (error: Schema.SchemaError, names?: Readonl
  */
 export declare const describeFileError: ({ reason }: PlatformError.PlatformError) => string;
 //#endregion
-export { ActionName, ActionRecord, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostError, HostErrorTag, Internal, Invalid, Limit, Machine, MachineSpec, NotFound, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, hostErrors, release, version };
+export { ActionName, ActionRecord, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostError, HostErrorTag, Internal, Invalid, Limit, Machine, MachineSpec, NotFound, prebuild_d_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, hostErrors, release, version };

package/dist/index.mjs

@@ -1,6 +1,105 @@
-import { A as parseName, B as Unavailable, C as release, D as Name, E as Id, F as HostErrorTag, I as Internal, L as Invalid, M as Conflict, N as ConflictKind, O as formatId, P as ErrorTag, R as NotFound, S as SshLogin, T as HostId, V as hostErrors, _ as MachineSpec, a as describeIssues, b as Setup, c as readTimeout, d as ActionRecord, f as Checkpoint, g as Machine, h as Limit, i as describeFileError, j as Capacity, k as parseId, l as versionHeader, m as Host, n as client_exports, o as formatMib, p as CreateRequest, s as Http, u as ActionName, v as Profile, w as version, x as SshEndpoint, y as Runtime, z as Precondition } from "./client-cFk3r2_1.mjs";
-import { Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/process";
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { A as parseName, B as Unavailable, C as release, D as Name, E as Id, F as HostErrorTag, I as Internal, L as Invalid, M as Conflict, N as ConflictKind, O as formatId, P as ErrorTag, R as NotFound, S as SshLogin, T as HostId, V as hostErrors, _ as MachineSpec, a as describeIssues, b as Setup, c as readTimeout, d as ActionRecord, f as Checkpoint, g as Machine, h as Limit, i as describeFileError, j as Capacity, k as parseId, l as versionHeader, m as Host, n as client_exports, o as formatMib, p as CreateRequest, s as Http, u as ActionName, v as Profile, w as version, x as SshEndpoint, y as Runtime, z as Precondition } from "./client-pUFgD6Xz.mjs";
+import { Effect, FileSystem, Option, Path, Predicate, Schema } from "effect";
+//#region src/prebuild.ts
+/**
+* Prebuilds: a checkpoint of a machine whose setup has run, which a create of the same spec
+* restores instead of running the setup again. They are the client's alone. A prebuild is an
+* ordinary checkpoint under a name derived from what it is of, so a host stores no profile and
+* knows nothing of them, and a create finds its prebuild with one read by ID. A prebuild never
+* changes and nothing here deletes one: building anew is a `checkpoint delete` first.
+*/
+var prebuild_exports = /* @__PURE__ */ __exportAll({
+	build: () => build,
+	create: () => create,
+	nameOf: () => nameOf
+});
+const prefix = "prebuilt-";
+/** How much of the digest a prebuild's name carries. */
+const digestDigits = 12;
+/**
+* How many random bytes a builder's name carries: 64 bits, so no two builds draw one name. With
+* `prebuilding-`, it is 28 characters, inside the 29 a 32-character host ID and its `_` leave of
+* an ID's 62.
+*/
+const builderBytes = 8;
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+* The name of the spec's prebuild on a host: a digest of the spec's label, base and sizes, the
+* setup script as sent, and the host's runtime version. A `ram` checkpoint restores only under
+* the release that saved it, so after a runtime bump a create misses the old prebuild instead
+* of failing to restore it. The setup's timeout is no part of it, and neither is the base's
+* image: a host only names it. The script holds whatever secrets a recipe carries, and the name
+* 12 hex characters of a digest of it.
+*/
+const nameOf = (spec, host) => Effect.promise(() => globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([
+	spec.profile ?? null,
+	spec.base,
+	spec.cpu,
+	spec.ramMib,
+	spec.diskGib,
+	spec.setup?.script ?? null,
+	host.runtimeVersion
+])))).pipe(Effect.map((digest) => `${prefix}${hex(digest).slice(0, digestDigits)}`));
+/** The checkpoint `id`, if the host has it. */
+const lookup = (client, id) => client.checkpoint(id).pipe(Effect.map(Option.some), Effect.catchTag("NotFound", () => Effect.succeedNone));
+/**
+* Creates a machine named `name` as `client.create` does, but restores it from the spec's
+* prebuild when the host it lands on has one whose capture is done. A spec without a setup has
+* none. Placement is the create's own, and a prebuild stays on the host that made it, so a spec
+* placed on another host runs its setup. A failed restore is the reply.
+*/
+const create = (client, name, spec, options) => Effect.gen(function* () {
+	if (spec.setup === void 0) return { machine: yield* client.create(name, spec, options) };
+	const host = yield* client.place(spec.base, options);
+	const id = yield* formatId(host.id, yield* nameOf(spec, host));
+	const found = yield* lookup(client, id);
+	if (Option.isSome(found) && found.value.action.status === "done") return {
+		machine: yield* client.restore(id, name),
+		prebuild: found.value
+	};
+	return { machine: yield* client.create(name, spec, { host: host.id }) };
+});
+/**
+* Builds the spec's prebuild on the host a create of it lands on: a machine of its own runs the
+* setup, is captured under the prebuild's name, and is deleted. smolvm captures a running
+* machine, RAM included, and boat a running one too; Tart only a stopped one, so its machine is
+* stopped first. A prebuild whose capture is done is the answer as it is; one that failed or is
+* still captured is refused.
+*
+* Each build's machine has a random name of its own, and the host takes a checkpoint name once,
+* so of two builds of one spec at once both run the setup and the second's capture is
+* `Conflict`: neither touches the other's machine or prebuild. A build deletes its machine
+* however it ends. If that fails after a failure, the first failure is the reply; after a
+* capture, the prebuild is made, and the machine is the reply's `leftover`.
+*/
+const build = (client, spec, options) => Effect.gen(function* () {
+	if (spec.setup === void 0) return yield* new Invalid({ message: "a prebuild needs a setup" });
+	const host = yield* client.place(spec.base, options);
+	const name = yield* nameOf(spec, host);
+	const id = yield* formatId(host.id, name);
+	const found = yield* lookup(client, id);
+	if (Option.isSome(found)) {
+		const { action } = found.value;
+		return action.status === "done" ? {
+			checkpoint: found.value,
+			built: false
+		} : yield* new Precondition({ message: `prebuild ${id}'s ${action.name} is ${action.status}; delete it to prebuild again` });
+	}
+	const builder = `prebuilding-${hex(globalThis.crypto.getRandomValues(new Uint8Array(builderBytes)))}`;
+	const builderId = yield* formatId(host.id, builder);
+	const removal = Effect.catchTag(client.delete(builderId), "NotFound", () => Effect.void);
+	return {
+		checkpoint: yield* Effect.gen(function* () {
+			yield* client.create(builder, spec, { host: host.id });
+			if (host.runtime === "tart") yield* client.stop(builderId);
+			return yield* client.capture(builderId, name);
+		}).pipe(Effect.onError(() => Effect.ignore(removal))),
+		built: true,
+		leftover: yield* removal.pipe(Effect.as(void 0), Effect.catch(() => Effect.succeed(builderId)))
+	};
+});
+//#endregion
 //#region src/profile.ts
 /** Reads a profile file for `create`. Hosts never see a profile. */
 /** Profile files are JSON, decoded with closed input like every call: unknown keys are refused. */
@@ -39,66 +138,79 @@ const loadProfile = (file) => Effect.gen(function* () {
 * script. Nothing here logs a script or a packed recipe: a recipe can carry secrets.
 */
 const lineLength = 76;
-/** base64 has no `_`, so no line of the payload can end the here-document early. */
+/** base64 has no `_`, so no line of a file's payload can end its here-document early. */
 const terminator = "CLANKERBOX_RECIPE";
 const wrap = (base64) => {
 	const lines = [];
 	for (let at = 0; at < base64.length; at += lineLength) lines.push(base64.slice(at, at + lineLength));
 	return lines.join("\n");
 };
+/** A string as one single-quoted shell word, whatever it holds. */
+const quote = (text) => `'${text.replaceAll("'", `'\\''`)}'`;
+/**
+* An entry's path as a command's argument: under `./`, so a name that starts with `-` is never
+* read as an option.
+*/
+const argument = (entry) => quote(`./${entry}`);
+/** Any execute bit, which is the one bit of a mode a recipe carries, as git does. */
+const executable = 73;
 /**
-* Pipes the archive into `tar -x` in a fresh directory, so no file of the recipe's can
-* collide with the archive, then runs `./setup.sh` from there: its `#!` line picks the
-* interpreter, as for a single-file setup, and the unpacker marks it executable whatever mode
-* it was packed with. The directory is under `/var/tmp`, as a single-file setup is, which
-* nothing mounts `noexec`, and is removed however setup ends. Setup runs as a child
-* rather than through `exec`, so the cleanup trap still runs after it. `--no-same-owner`
-* keeps the packer's uid off the files when root unpacks them in the guest.
+* Makes the recipe's files in a fresh directory, then runs `./setup.sh` from there: its `#!`
+* line picks the interpreter, as for a single-file setup, and the unpacker marks it executable
+* whatever mode it was packed with. The directory is under `/var/tmp`, as a single-file setup
+* is, which nothing mounts `noexec`, and is removed however setup ends. Setup runs as a child
+* rather than through `exec`, so the cleanup trap still runs after it.
 */
-const selfExtracting = (archive) => [
+const selfExtracting = (steps) => [
 	"#!/bin/sh",
 	"set -eu",
 	"recipe=$(mktemp -d /var/tmp/clankerbox-recipe.XXXXXX)",
 	`trap 'rm -rf "$recipe"' EXIT`,
 	"trap 'exit 1' HUP INT TERM",
-	`base64 -d <<'${terminator}' | tar -x -f - --no-same-owner -C "$recipe"`,
-	wrap(archive),
-	terminator,
 	"cd \"$recipe\"",
+	...steps,
 	"chmod +x setup.sh",
 	"./setup.sh",
 	""
 ].join("\n");
 /**
-* Packs a recipe directory into one self-extracting script: a base64 tar that unpacks into a
-* temporary directory, then runs `setup.sh` from there. `COPYFILE_DISABLE=1` and
-* `--no-xattrs` keep macOS `tar` from adding `._*` files and provenance headers.
+* Packs a recipe directory into one self-extracting script, which makes each of its entries
+* with plain shell: a directory with `mkdir`, a symlink with `ln -s` as it is, and a file from
+* base64, made executable when any of its execute bits is set. A symlink is never walked into,
+* so nothing outside the recipe is packed, and in the guest nothing is written through one.
+* Of a mode only the execute bit is kept, as git keeps it, so a checkout's umask changes
+* nothing. Entries go in sorted order and nothing records a time or an owner, so the same
+* files pack into the same script: a prebuild is named after it.
 */
 const packRecipe = (directory) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const noSetup = new Invalid({ message: `recipe ${directory} has no setup.sh` });
 	if ((yield* fs.stat(`${directory}/setup.sh`).pipe(Effect.mapError((error) => Predicate.isTagged(error.reason, "NotFound") ? noSetup : error))).type !== "File") return yield* noSetup;
-	const tar = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(ChildProcess.make("tar", [
-		"--no-xattrs",
-		"-c",
-		"-f",
-		"-",
-		"-C",
-		directory,
-		"."
-	], {
-		env: { COPYFILE_DISABLE: "1" },
-		extendEnv: true,
-		stdin: "ignore"
-	}));
-	const [archive, errors, code] = yield* Effect.all([
-		Stream.mkUint8Array(tar.stdout),
-		Stream.mkString(Stream.decodeText(tar.stderr)),
-		tar.exitCode
-	], { concurrency: "unbounded" });
-	if (code !== 0) return yield* new Invalid({ message: `tar couldn't pack recipe ${directory} (exit ${code}): ${errors.trim()}` });
-	return selfExtracting(Buffer.from(archive.buffer, archive.byteOffset, archive.byteLength).toString("base64"));
-}).pipe(Effect.scoped, Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't pack recipe ${directory}: ${describeFileError(error)}` }))));
+	const steps = [];
+	/** Packs the entries of the recipe's directory `under`, `""` being the recipe itself. */
+	const walk = (under) => Effect.gen(function* () {
+		const names = yield* fs.readDirectory(under === "" ? directory : `${directory}/${under}`);
+		for (const name of names.toSorted()) {
+			const entry = under === "" ? name : `${under}/${name}`;
+			const path = `${directory}/${entry}`;
+			const link = yield* Effect.option(fs.readLink(path));
+			if (Option.isSome(link)) {
+				steps.push(`ln -s -- ${quote(link.value)} ${argument(entry)}`);
+				continue;
+			}
+			const info = yield* fs.stat(path);
+			if (info.type === "Directory") {
+				steps.push(`mkdir ${argument(entry)}`);
+				yield* walk(entry);
+			} else if (info.type === "File") {
+				steps.push(`base64 -d >${argument(entry)} <<'${terminator}'`, wrap(Buffer.from(yield* fs.readFile(path)).toString("base64")), terminator);
+				if ((info.mode & executable) !== 0) steps.push(`chmod +x ${argument(entry)}`);
+			} else return yield* new Invalid({ message: `recipe ${directory} holds ${entry}, a ${info.type}: a recipe packs only files, directories and symlinks` });
+		}
+	});
+	yield* walk("");
+	return selfExtracting(steps);
+}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't pack recipe ${directory}: ${describeFileError(error)}` }))));
 /** Reads a setup: a script file's text, or a recipe directory packed into one script. */
 const readSetup = (path) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -106,4 +218,71 @@ const readSetup = (path) => Effect.gen(function* () {
 	return yield* fs.readFileString(path);
 }).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't read setup ${path}: ${describeFileError(error)}` }))));
 //#endregion
-export { ActionName, ActionRecord, Capacity, Checkpoint, client_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostErrorTag, HostId, Http, Id, Internal, Invalid, Limit, Machine, MachineSpec, Name, NotFound, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, describeFileError, describeIssues, formatId, formatMib, hostErrors, loadProfile, packRecipe, parseId, parseName, readSetup, readTimeout, release, version, versionHeader };
+//#region src/ssh.ts
+/**
+* The system `ssh`'s arguments for a machine, pinned to its host key: what `clankerbox ssh` runs,
+* and what anything else that reaches a guest through port 22 does, such as a port forward.
+*/
+/**
+* The machine's SSH target, or what it lacks: an endpoint, which only a running machine has, or
+* a host key, which preparation records.
+*/
+const sshTarget = (machine) => {
+	const { id, ssh: login, hostKey } = machine;
+	if (login === void 0) return { lacks: "SSH endpoint" };
+	return hostKey === void 0 ? { lacks: "SSH host key on record" } : {
+		id,
+		login,
+		hostKey
+	};
+};
+/**
+* The known-hosts line pinning the machine's host key under its ID: ssh looks the key up by
+* `HostKeyAlias`, so the line doesn't depend on the endpoint, which changes.
+*/
+const knownHostsLine = (id, hostKey) => {
+	const [type = "", key = ""] = hostKey.trim().split(/\s+/u);
+	return `${id} ${type} ${key}\n`;
+};
+/**
+* ssh's arguments. OpenSSH keeps the first user it is given, so the leading `-l` decides it:
+* one in the caller's arguments or in an ssh config doesn't apply. The destination is the
+* machine's ID, so a `Host <pattern>` block in the user's ssh config can set keys and options
+* per machine; the endpoint and the pinned host key come from command-line options, which no
+* config overrides. The caller's arguments go after the destination, where OpenSSH still reads
+* options (`-L …`) before a remote command.
+*/
+const sshArguments = (target, user, knownHosts, extra) => [
+	"-l",
+	user,
+	"-o",
+	`HostName=${target.login.host}`,
+	"-o",
+	`Port=${target.login.port}`,
+	"-o",
+	`HostKeyAlias=${target.id}`,
+	"-o",
+	`UserKnownHostsFile=${knownHosts}`,
+	"-o",
+	"GlobalKnownHostsFile=/dev/null",
+	"-o",
+	"StrictHostKeyChecking=yes",
+	target.id,
+	...extra
+];
+/**
+* Writes a one-line known-hosts file pinning the target's host key, and returns the arguments
+* that run ssh against it with strict host key checking, as `user`. The file lasts as long as
+* the scope, which must outlast the ssh it is for. Ports change on fork and restore, and on
+* boat at every start, so a target is read anew for each ssh.
+*/
+const pinnedSsh = (target, user, extra) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const directory = yield* fs.makeTempDirectoryScoped({ prefix: "clankerbox-ssh-" });
+	const knownHosts = path.join(directory, "known_hosts");
+	yield* fs.writeFileString(knownHosts, knownHostsLine(target.id, target.hostKey));
+	return sshArguments(target, user, knownHosts, extra);
+});
+//#endregion
+export { ActionName, ActionRecord, Capacity, Checkpoint, client_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostErrorTag, HostId, Http, Id, Internal, Invalid, Limit, Machine, MachineSpec, Name, NotFound, prebuild_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, describeFileError, describeIssues, formatId, formatMib, hostErrors, loadProfile, packRecipe, parseId, parseName, pinnedSsh, readSetup, readTimeout, release, sshTarget, version, versionHeader };

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { O as Invalid, n as HostEntry, r as Options, t as Client } from "./client-SX6jTU1R.mjs";
+import { A as Invalid, a as Options, r as HostEntry, t as Client } from "./client-Cn1bj4It.mjs";
 import { Layer } from "effect";
 //#region src/node.d.ts
 /** Node's `http` module sets no timeout of its own: a mutation can run for hours. */

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { r as make, t as Client } from "./client-cFk3r2_1.mjs";
+import { r as make, t as Client } from "./client-pUFgD6Xz.mjs";
 import { Layer } from "effect";
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
 //#region src/node.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerbox-sdk",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "clankerbox's API contract and client library, for Effect",
   "license": "MIT",
   "repository": {