@gjermundgaraba/clankerbox-sdk 0.15.6 → 0.16.0

package/dist/index.mjs

@@ -1,36 +1,26 @@
 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-BkZhmYJx.mjs";
-import { Effect, FileSystem, Option, Path, Predicate, Schema } from "effect";
+import { A as Name, B as Invalid, C as MachineSpec, D as SshLogin, E as SshEndpoint, F as ClankerboxError, H as Precondition, I as Conflict, L as ConflictKind, M as parseId, N as parseName, O as HostId, P as Capacity, R as HostErrorTag, S as Machine, T as Setup, U as Unavailable, V as NotFound, W as hostErrors, _ as CheckpointActionName, a as formatMib, b as Host, c as version, d as actionsByName, f as readTimeout, g as Checkpoint, h as ActionStatus, i as describeIssues, j as formatId, k as Id, l as versionHeader, m as ActionRecord, o as mibPerGib, p as ActionName, r as describeFileError, s as release, t as client_exports, u as Http, v as CheckpointActionRecord, w as Runtime, x as Limit, y as CreateRequest, z as Internal } from "./client-CLemHDCl.mjs";
+import { Effect, FileSystem, Option, Path, Predicate, Record, Schema } from "effect";
+import { Base64 } from "effect/encoding";
 //#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.
+* 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.
+* A digest of the spec's label, base, sizes, 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 and
+* the base's image are no part of it.
 */
 const nameOf = (spec, host) => Effect.promise(() => globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([
 	spec.profile ?? null,
@@ -41,16 +31,13 @@ const nameOf = (spec, host) => Effect.promise(() => globalThis.crypto.subtle.dig
 	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.
+* `client.create`, restoring the spec's prebuild when the host it is placed on has one whose
+* capture is done, unless `fresh`. 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) };
+	if (spec.setup === void 0 || options?.fresh === true) return { machine: yield* client.create(name, spec, { host: options?.host }) };
 	const host = yield* client.place(spec.base, options);
 	const id = yield* formatId(host.id, yield* nameOf(spec, host));
 	const found = yield* lookup(client, id);
@@ -61,17 +48,10 @@ const create = (client, name, spec, options) => Effect.gen(function* () {
 	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`.
+* Builds the spec's prebuild on the host a create of it is placed on, with a machine of its own
+* that it deletes however it ends. A prebuild that is there and done is the answer; one that
+* failed or is still being captured is refused. Of two builds of one spec at once, the second's
+* capture is `Conflict`, and neither touches the other's machine or prebuild.
 */
 const build = (client, spec, options) => Effect.gen(function* () {
 	if (spec.setup === void 0) return yield* new Invalid({ message: "a prebuild needs a setup" });
@@ -92,7 +72,7 @@ const build = (client, spec, options) => Effect.gen(function* () {
 	return {
 		checkpoint: yield* Effect.gen(function* () {
 			yield* client.create(builder, spec, { host: host.id });
-			if (host.runtime === "tart") yield* client.stop(builderId);
+			if (host.captureFrom === "stopped") yield* client.stop(builderId);
 			return yield* client.capture(builderId, name);
 		}).pipe(Effect.onError(() => Effect.ignore(removal))),
 		built: true,
@@ -100,43 +80,8 @@ const build = (client, spec, options) => Effect.gen(function* () {
 	};
 });
 //#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. */
-const decodeProfile = Schema.decodeUnknownEffect(Schema.fromJsonString(Profile));
-/**
-* Reads the profile file at `file`. Its name, the file name without `.json`, is the machine's
-* `profile` label, and its `setup.path` is resolved against the file's directory. The setup
-* itself is read by whoever sends it, with `readSetup`.
-*/
-const loadProfile = (file) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const text = yield* fs.readFileString(file).pipe(Effect.mapError((error) => new Invalid({ message: `couldn't read profile ${file}: ${describeFileError(error)}` })));
-	const profile = yield* decodeProfile(text, {
-		onExcessProperty: "error",
-		errors: "all"
-	}).pipe(Effect.mapError((error) => new Invalid({ message: `profile ${file}: ${describeIssues(error)}` })));
-	const label = path.basename(file, ".json");
-	return profile.setup === void 0 ? {
-		...profile,
-		label
-	} : {
-		...profile,
-		setup: {
-			...profile.setup,
-			path: path.resolve(path.dirname(file), profile.setup.path)
-		},
-		label
-	};
-});
-//#endregion
 //#region src/setup.ts
-/**
-* Setup scripts for create. A host receives one script: a file is sent as its text, and a
-* recipe directory (a `setup.sh` and the files it needs) is packed into one self-extracting
-* script. Nothing here logs a script or a packed recipe: a recipe can carry secrets.
-*/
+/** Nothing here logs a script or a packed recipe: a recipe can carry secrets. */
 const lineLength = 76;
 /** base64 has no `_`, so no line of a file's payload can end its here-document early. */
 const terminator = "CLANKERBOX_RECIPE";
@@ -145,21 +90,14 @@ const wrap = (base64) => {
 	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.
-*/
+/** 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. */
+/** The one bit of a mode a recipe carries, as git does, so a checkout's umask changes nothing. */
 const executable = 73;
 /**
-* 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.
+* Under `/var/tmp`, which nothing mounts `noexec`. Setup runs as a child rather than through
+* `exec`, so the cleanup trap still runs after it.
 */
 const selfExtracting = (steps) => [
 	"#!/bin/sh",
@@ -174,20 +112,18 @@ const selfExtracting = (steps) => [
 	""
 ].join("\n");
 /**
-* 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.
+* Packs a recipe directory, a `setup.sh` and the files it needs, into one self-extracting script.
+* Symlinks are recreated as they are and never walked into. The same files always pack into the
+* same script, as 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` });
+	const noSetup = new Invalid({
+		message: `recipe ${directory} has no setup.sh`,
+		file: directory
+	});
 	if ((yield* fs.stat(`${directory}/setup.sh`).pipe(Effect.mapError((error) => Predicate.isTagged(error.reason, "NotFound") ? noSetup : error))).type !== "File") return yield* noSetup;
 	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()) {
@@ -203,30 +139,110 @@ const packRecipe = (directory) => Effect.gen(function* () {
 				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);
+				steps.push(`base64 -d >${argument(entry)} <<'${terminator}'`, wrap(Base64.encode(yield* fs.readFile(path))), 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` });
+			} else return yield* new Invalid({
+				message: `recipe ${directory} holds ${entry}, a ${info.type}: a recipe packs only files, directories and symlinks`,
+				file: path
+			});
 		}
 	});
 	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. */
+}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({
+	message: `couldn't pack recipe ${directory}: ${describeFileError(error)}`,
+	file: directory
+}))));
+/** A script file's text, or a recipe directory packed into one script. */
 const readSetup = (path) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	if ((yield* fs.stat(path)).type === "Directory") return yield* packRecipe(path);
 	return yield* fs.readFileString(path);
-}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({ message: `couldn't read setup ${path}: ${describeFileError(error)}` }))));
+}).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new Invalid({
+	message: `couldn't read setup ${path}: ${describeFileError(error)}`,
+	file: path
+}))));
 //#endregion
-//#region src/ssh.ts
+//#region src/profile.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.
+* A client-side file that fills in a create's spec; hosts never see it. `setup.path` is a script
+* file or a recipe directory, relative to the profile file.
 */
+const Profile = Schema.Struct({
+	base: MachineSpec.fields.base,
+	cpu: MachineSpec.fields.cpu,
+	ramMib: MachineSpec.fields.ramMib,
+	diskGib: MachineSpec.fields.diskGib,
+	setup: Schema.optionalKey(Schema.Struct({
+		path: Schema.String,
+		timeoutSeconds: Setup.fields.timeoutSeconds
+	})),
+	host: Schema.optionalKey(HostId)
+});
+const decodeProfile = Schema.decodeUnknownEffect(Schema.fromJsonString(Profile));
 /**
-* The machine's SSH target, or what it lacks: an endpoint, which only a running machine has, or
-* a host key, which preparation records.
+* Its file name without `.json` is the machine's `profile` label. Unknown keys are refused. The
+* setup itself is read by whoever sends it, with `readSetup`.
 */
+const loadProfile = (file) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const text = yield* fs.readFileString(file).pipe(Effect.mapError((error) => new Invalid({
+		message: `couldn't read profile ${file}: ${describeFileError(error)}`,
+		file
+	})));
+	const profile = yield* decodeProfile(text, {
+		onExcessProperty: "error",
+		errors: "all"
+	}).pipe(Effect.mapError((error) => new Invalid({
+		message: `profile ${file}: ${describeIssues(error)}`,
+		file
+	})));
+	const label = path.basename(file, ".json");
+	return profile.setup === void 0 ? {
+		...profile,
+		label
+	} : {
+		...profile,
+		setup: {
+			...profile.setup,
+			path: path.resolve(path.dirname(file), profile.setup.path)
+		},
+		label
+	};
+});
+const decodeSpec = Schema.decodeUnknownEffect(MachineSpec);
+/**
+* The spec and host a create of `profile` asks for, with the overrides applied and the setup
+* read. Each refusal names `what`, and each field as `names` calls it.
+*/
+const specRequest = (what, profile, overrides, names) => Effect.gen(function* () {
+	const file = overrides.setup ?? profile?.setup?.path;
+	const timeoutSeconds = overrides.setupTimeoutSeconds ?? profile?.setup?.timeoutSeconds;
+	if (file === void 0 && overrides.setupTimeoutSeconds !== void 0) return yield* new Invalid({ message: `${what}: ${names?.get("setupTimeoutSeconds") ?? "the setup timeout"} needs a setup to time` });
+	const script = file === void 0 ? void 0 : yield* readSetup(file);
+	const fields = {
+		base: overrides.base ?? profile?.base,
+		cpu: overrides.cpu ?? profile?.cpu,
+		ramMib: overrides.ramMib ?? profile?.ramMib,
+		diskGib: overrides.diskGib ?? profile?.diskGib,
+		setup: script === void 0 ? void 0 : Record.filter({
+			script,
+			timeoutSeconds
+		}, Predicate.isNotUndefined),
+		profile: profile?.label
+	};
+	return {
+		spec: yield* decodeSpec(Record.filter(fields, Predicate.isNotUndefined), {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((error) => new Invalid({ message: `${what}: ${describeIssues(error, names)}` }))),
+		host: overrides.host ?? profile?.host
+	};
+});
+//#endregion
+//#region src/ssh.ts
+/** Only a running machine has an endpoint, and only a prepared one a host key. */
 const sshTarget = (machine) => {
 	const { id, ssh: login, hostKey } = machine;
 	if (login === void 0) return { lacks: "SSH endpoint" };
@@ -237,20 +253,18 @@ const sshTarget = (machine) => {
 	};
 };
 /**
-* 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.
+* 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.
+* OpenSSH keeps the first user it is given, so the leading `-l` decides it. The destination is
+* the machine's ID, so a `Host <pattern>` block in the user's ssh config can match it, while the
+* endpoint and the pinned key come from options 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",
@@ -271,10 +285,9 @@ const sshArguments = (target, user, knownHosts, extra) => [
 	...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.
+* ssh's arguments, pinned to the target's host key through a known-hosts file that lasts as long
+* as the scope, which must outlast the ssh. Ports change on fork, restore, and every boat start,
+* so read the target anew for each ssh.
 */
 const pinnedSsh = (target, user, extra) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -285,4 +298,4 @@ const pinnedSsh = (target, user, extra) => Effect.gen(function* () {
 	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 };
+export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, CheckpointActionName, CheckpointActionRecord, ClankerboxError, client_exports as Client, Conflict, ConflictKind, CreateRequest, Host, HostErrorTag, HostId, Http, Id, Internal, Invalid, Limit, Machine, MachineSpec, Name, NotFound, prebuild_exports as Prebuild, Precondition, Profile, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, actionsByName, describeFileError, describeIssues, formatId, formatMib, hostErrors, loadProfile, mibPerGib, packRecipe, parseId, parseName, pinnedSsh, readSetup, readTimeout, release, specRequest, sshTarget, version, versionHeader };

package/dist/node.d.mts

@@ -1,6 +1,6 @@
-import { A as Invalid, a as Options, r as HostEntry, t as Client } from "./client-Cn1bj4It.mjs";
+import { M as Invalid, a as Options, o as client_d_exports, r as HostEntry, t as Client } from "./client-DgDb-TR7.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. */
+/** Over Node's `http`, which sets no timeout of its own: a mutation can run for hours. */
 export declare const layer: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Layer.Layer<Client, Invalid>;
 //#endregion

package/dist/node.mjs

@@ -1,12 +1,12 @@
-import { r as make, t as Client } from "./client-BkZhmYJx.mjs";
+import { n as layer$1 } from "./client-CLemHDCl.mjs";
 import { Layer } from "effect";
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
 //#region src/node.ts
 /**
-* The client over Node's `http` module, the SDK's `/node` entry. It stands apart so that an
-* app that brings its own `HttpClient` to `Client.make` never loads `@effect/platform-node`.
+* Apart from `.`, so an app that brings its own `HttpClient` never loads
+* `@effect/platform-node`.
 */
-/** Node's `http` module sets no timeout of its own: a mutation can run for hours. */
-const layer = (hosts, options) => Layer.effect(Client, make(hosts, options)).pipe(Layer.provide(NodeHttpClient.layerNodeHttp));
+/** Over Node's `http`, which sets no timeout of its own: a mutation can run for hours. */
+const layer = (hosts, options) => layer$1(hosts, options).pipe(Layer.provide(NodeHttpClient.layerNodeHttp));
 //#endregion
 export { layer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerbox-sdk",
-  "version": "0.15.6",
+  "version": "0.16.0",
   "description": "clankerbox's API contract and client library, for Effect",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.4",
+    "@effect/vitest": "4.0.4",
     "@types/node": "26.6.4",
     "effect": "4.0.4",
     "typescript": "7.0.2",