@gjermundgaraba/clankerbox-sdk 0.16.0 → 0.18.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as HostErrorTag, C as actionsByName, D as Conflict, E as ClankerboxError, F as Unavailable, I as hostErrors, M as Invalid, N as NotFound, O as ConflictKind, P as Precondition, S as Http, T as Capacity, _ as MachineSpec, b as SshEndpoint, c as ActionRecord, d as CheckpointActionName, f as CheckpointActionRecord, g as Machine, h as Limit, i as Interface, j as Internal, k as HostError, l as ActionStatus, m as Host, n as CreateOptions$1, o as client_d_exports, p as CreateRequest, s as ActionName, u as Checkpoint, v as Runtime, w as readTimeout, x as SshLogin, y as Setup } from "./client-DgDb-TR7.mjs";
+import { A as ConflictKind, B as Refused, C as Declared, D as Capacity, E as readTimeout, F as NotFound, G as hostErrors, H as Unavailable, I as NotMade, K as retryable, L as NotOffered, M as Internal, N as Invalid, O as ClankerboxError, P as Missing, R as NotReady, S as stateLabel, T as actionsByName, U as Unsizable, V as ScriptFailed, W as WrongState, _ as Setup, b as Usage, c as ActionRecord, d as CreateRequest, f as Host, g as Runtime, h as Reading, i as Interface, j as HostError, k as Conflict, l as ActionStatus, m as MachineSpec, n as CreateOptions$1, o as client_d_exports, p as Machine, s as ActionName, u as Checkpoint, v as SshEndpoint, w as Http, x as isReady, y as SshLogin, z as PinMismatch } from "./client-8af586hb.mjs";
 import { Effect, FileSystem, Path, PlatformError, Schema, Scope } from "effect";
 //#region src/ids.d.ts
 export declare const HostId: Schema.String;
@@ -46,11 +46,14 @@ interface Built {
 }
 /**
  * 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.
+ * that it deletes however it ends. A prebuild that is there and done is the answer, one that
+ * failed is deleted and built again, and one still running is `Conflict{busy}`, as its capture
+ * holds it. Of two builds of one spec at once, the second's capture is `Conflict`, and neither
+ * touches the other's machine.
  */
-declare const build: (client: Interface, spec: MachineSpec, options?: CreateOptions$1) => Effect.Effect<Built, ClankerboxError>;
+declare const build: (client: Interface, spec: MachineSpec & {
+  readonly setup: Setup;
+}, options?: CreateOptions$1) => Effect.Effect<Built, ClankerboxError>;
 //#endregion
 //#region src/release.d.ts
 /** Also the version of the clankerbox binaries it ships with. */
@@ -120,21 +123,22 @@ export interface SshTarget {
   readonly login: SshLogin;
   readonly hostKey: string;
 }
-/** Only a running machine has an endpoint, and only a prepared one a host key. */
-export declare const sshTarget: (machine: Machine) => SshTarget | {
-  readonly lacks: "SSH endpoint" | "SSH host key on record";
-};
 /**
- * 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.
+ * Only a running machine has an endpoint, and only a prepared one a host key; a machine without
+ * either is `WrongState`, naming what it lacks and why.
+ */
+export declare const sshTarget: (machine: Machine) => Effect.Effect<SshTarget, WrongState>;
+/** A known_hosts line pinning `name` to a host key on record, `<type> <base64>`. */
+export declare const knownHostsLine: (name: string, hostKey: string) => string;
+/**
+ * ssh's arguments to the target's address, pinned to its host key through a known-hosts file that
+ * lasts as long as the scope, which must outlast the ssh. The destination is the address, not the
+ * ID, so no ssh_config block for the ID applies. Ports change on fork, restore, and every boat
+ * start, so read the target 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
-export declare const mibPerGib = 1024;
-/** Exactly, as a size flag takes it: `32G`, `1.5G`, `512M`, `1500M`. */
-export declare const formatMib: (mib: number) => string;
+//#region src/describe.d.ts
 /** On one line: `cpu: missing; ram: not a known field`. `names` renames top-level fields. */
 export declare const describeIssues: (error: Schema.SchemaError, names?: ReadonlyMap<PropertyKey, string>) => string;
 /**
@@ -143,4 +147,11 @@ export declare const describeIssues: (error: Schema.SchemaError, names?: Readonl
  */
 export declare const describeFileError: ({ reason }: PlatformError.PlatformError) => string;
 //#endregion
-export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, CheckpointActionName, CheckpointActionRecord, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, Host, HostError, HostErrorTag, Http, Internal, Invalid, Limit, Machine, MachineSpec, NotFound, prebuild_d_exports as Prebuild, Precondition, Runtime, Setup, SshEndpoint, SshLogin, Unavailable, actionsByName, hostErrors, readTimeout };
+//#region src/sizes.d.ts
+export declare const mibPerGib = 1024;
+/** Exactly, as a size flag takes it: `32G`, `1.5G`, `512M`, `1500M`. */
+export declare const formatMib: (mib: number) => string;
+/** As a size flag takes it: `60G`. */
+export declare const formatGib: (gib: number) => string;
+//#endregion
+export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, Declared, Host, HostError, Http, Internal, Invalid, Machine, MachineSpec, Missing, NotFound, NotMade, NotOffered, NotReady, PinMismatch, prebuild_d_exports as Prebuild, Reading, Refused, Runtime, ScriptFailed, Setup, SshEndpoint, SshLogin, Unavailable, Unsizable, Usage, WrongState, actionsByName, hostErrors, isReady, readTimeout, retryable, stateLabel };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-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 { A as parseId, B as NotFound, C as Usage, D as Id, E as HostId, F as ConflictKind, G as Refused, H as NotOffered, I as HostError, J as Unsizable, K as ScriptFailed, L as Internal, M as Capacity, N as ClankerboxError, O as Name, P as Conflict, R as Invalid, S as SshLogin, T as stateLabel, U as NotReady, V as NotMade, W as PinMismatch, X as hostErrors, Y as WrongState, Z as retryable, _ as Machine, a as release, b as Setup, c as Http, d as ActionName, f as ActionRecord, g as Host, h as CreateRequest, i as describeIssues, j as parseName, k as formatId, l as actionsByName, m as Checkpoint, o as version, p as ActionStatus, q as Unavailable, r as describeFileError, s as versionHeader, t as client_exports, u as readTimeout, v as MachineSpec, w as isReady, x as SshEndpoint, y as Runtime, z as Missing } from "./client-JikMOSHo.mjs";
 import { Effect, FileSystem, Option, Path, Predicate, Record, Schema } from "effect";
-import { Base64 } from "effect/encoding";
+import { Base64, Hex } from "effect/encoding";
 //#region src/prebuild.ts
 var prebuild_exports = /* @__PURE__ */ __exportAll({
 	build: () => build,
@@ -10,12 +10,7 @@ var prebuild_exports = /* @__PURE__ */ __exportAll({
 });
 const prefix = "prebuilt-";
 const digestDigits = 12;
-/**
-* 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("");
 /**
 * 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
@@ -30,8 +25,8 @@ const nameOf = (spec, host) => Effect.promise(() => globalThis.crypto.subtle.dig
 	spec.diskGib,
 	spec.setup?.script ?? null,
 	host.runtimeVersion
-])))).pipe(Effect.map((digest) => `${prefix}${hex(digest).slice(0, digestDigits)}`));
-const lookup = (client, id) => client.checkpoint(id).pipe(Effect.map(Option.some), Effect.catchTag("NotFound", () => Effect.succeedNone));
+])))).pipe(Effect.map((digest) => `${prefix}${Hex.encode(new Uint8Array(digest)).slice(0, digestDigits)}`));
+const lookup = (client, id) => client.getCheckpoint({ id }).pipe(Effect.map(Option.some), Effect.catchTag("NotFound", () => Effect.succeedNone));
 /**
 * `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.
@@ -41,39 +36,53 @@ const create = (client, name, spec, options) => Effect.gen(function* () {
 	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),
+	if (Option.isSome(found) && isReady(found.value)) return {
+		machine: yield* client.restoreMachine({
+			checkpoint: 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 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.
+* that it deletes however it ends. A prebuild that is there and done is the answer, one that
+* failed is deleted and built again, and one still running is `Conflict{busy}`, as its capture
+* holds it. Of two builds of one spec at once, the second's capture is `Conflict`, and neither
+* touches the other's machine.
 */
 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" ? {
+		if (isReady(found.value)) return {
 			checkpoint: found.value,
 			built: false
-		} : yield* new Precondition({ message: `prebuild ${id}'s ${action.name} is ${action.status}; delete it to prebuild again` });
+		};
+		if (action.status === "running") return yield* new Conflict({
+			message: `prebuild ${id} is busy: its ${action.name} is running`,
+			kind: "busy",
+			host: host.id,
+			action: "captureCheckpoint",
+			id
+		});
+		yield* client.deleteCheckpoint({ id });
 	}
-	const builder = `prebuilding-${hex(globalThis.crypto.getRandomValues(new Uint8Array(builderBytes)))}`;
+	const builder = `prebuilding-${Hex.encode(globalThis.crypto.getRandomValues(new Uint8Array(builderBytes)))}`;
 	const builderId = yield* formatId(host.id, builder);
-	const removal = Effect.catchTag(client.delete(builderId), "NotFound", () => Effect.void);
+	const removal = client.deleteMachine({ id: builderId });
 	return {
 		checkpoint: yield* Effect.gen(function* () {
 			yield* client.create(builder, spec, { host: host.id });
-			if (host.captureFrom === "stopped") yield* client.stop(builderId);
-			return yield* client.capture(builderId, name);
+			if (host.captureFrom === "stopped") yield* client.stopMachine({ id: builderId });
+			return yield* client.captureCheckpoint({
+				machine: builderId,
+				name
+			});
 		}).pipe(Effect.onError(() => Effect.ignore(removal))),
 		built: true,
 		leftover: yield* removal.pipe(Effect.as(void 0), Effect.catch(() => Effect.succeed(builderId)))
@@ -81,9 +90,7 @@ const build = (client, spec, options) => Effect.gen(function* () {
 });
 //#endregion
 //#region src/setup.ts
-/** 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";
 const wrap = (base64) => {
 	const lines = [];
@@ -91,14 +98,8 @@ const wrap = (base64) => {
 	return lines.join("\n");
 };
 const quote = (text) => `'${text.replaceAll("'", `'\\''`)}'`;
-/** Under `./`, so a name that starts with `-` is never read as an option. */
 const argument = (entry) => quote(`./${entry}`);
-/** The one bit of a mode a recipe carries, as git does, so a checkout's umask changes nothing. */
 const executable = 73;
-/**
-* 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",
 	"set -eu",
@@ -242,36 +243,35 @@ const specRequest = (what, profile, overrides, names) => Effect.gen(function* ()
 });
 //#endregion
 //#region src/ssh.ts
-/** Only a running machine has an endpoint, and only a prepared one a host key. */
+/**
+* Only a running machine has an endpoint, and only a prepared one a host key; a machine without
+* either is `WrongState`, naming what it lacks and why.
+*/
 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" } : {
+	const { id, ssh: login, hostKey, action } = machine;
+	if (login !== void 0 && hostKey !== void 0) return Effect.succeed({
 		id,
 		login,
 		hostKey
-	};
+	});
+	const lacks = login === void 0 ? "SSH endpoint" : "SSH host key on record";
+	const state = stateLabel(machine);
+	const message = `${id} has no ${lacks} (${state}, ${action.name} ${action.status}): see clankerbox get ${id}`;
+	return Effect.fail(new WrongState({
+		message,
+		machine: id,
+		state
+	}));
 };
-/**
-* ssh looks the key up by `HostKeyAlias`, so the line doesn't depend on the endpoint, which
-* changes.
-*/
-const knownHostsLine = (id, hostKey) => {
+/** A known_hosts line pinning `name` to a host key on record, `<type> <base64>`. */
+const knownHostsLine = (name, hostKey) => {
 	const [type = "", key = ""] = hostKey.trim().split(/\s+/u);
-	return `${id} ${type} ${key}\n`;
+	return `${name} ${type} ${key}\n`;
 };
-/**
-* 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",
 	user,
 	"-o",
-	`HostName=${target.login.host}`,
-	"-o",
 	`Port=${target.login.port}`,
 	"-o",
 	`HostKeyAlias=${target.id}`,
@@ -281,13 +281,14 @@ const sshArguments = (target, user, knownHosts, extra) => [
 	"GlobalKnownHostsFile=/dev/null",
 	"-o",
 	"StrictHostKeyChecking=yes",
-	target.id,
+	target.login.host,
 	...extra
 ];
 /**
-* 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.
+* ssh's arguments to the target's address, pinned to its host key through a known-hosts file that
+* lasts as long as the scope, which must outlast the ssh. The destination is the address, not the
+* ID, so no ssh_config block for the ID applies. 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;
@@ -298,4 +299,11 @@ const pinnedSsh = (target, user, extra) => Effect.gen(function* () {
 	return sshArguments(target, user, knownHosts, extra);
 });
 //#endregion
-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 };
+//#region src/sizes.ts
+const mibPerGib = 1024;
+/** Exactly, as a size flag takes it: `32G`, `1.5G`, `512M`, `1500M`. */
+const formatMib = (mib) => mib >= 1024 && mib % 512 === 0 ? `${mib / mibPerGib}G` : `${mib}M`;
+/** As a size flag takes it: `60G`. */
+const formatGib = (gib) => `${gib}G`;
+//#endregion
+export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, ClankerboxError, client_exports as Client, Conflict, ConflictKind, CreateRequest, Host, HostError, HostId, Http, Id, Internal, Invalid, Machine, MachineSpec, Missing, Name, NotFound, NotMade, NotOffered, NotReady, PinMismatch, prebuild_exports as Prebuild, Profile, Refused, Runtime, ScriptFailed, Setup, SshEndpoint, SshLogin, Unavailable, Unsizable, Usage, WrongState, actionsByName, describeFileError, describeIssues, formatGib, formatId, formatMib, hostErrors, isReady, knownHostsLine, loadProfile, mibPerGib, packRecipe, parseId, parseName, pinnedSsh, readSetup, readTimeout, release, retryable, specRequest, sshTarget, stateLabel, version, versionHeader };

package/dist/node.d.mts

@@ -1,6 +1,10 @@
-import { M as Invalid, a as Options, o as client_d_exports, r as HostEntry, t as Client } from "./client-DgDb-TR7.mjs";
+import { N as Invalid, a as Options, r as HostEntry, t as Client } from "./client-8af586hb.mjs";
 import { Layer } from "effect";
 //#region src/node.d.ts
-/** Over Node's `http`, which sets no timeout of its own: a mutation can run for hours. */
+/**
+ * The client over Node's `http`, which sets no timeout of its own: a mutation can run for hours.
+ * It is in `./node`, apart from `.`, so an app that brings its own `HttpClient` never loads
+ * `@effect/platform-node`.
+ */
 export declare const layer: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Layer.Layer<Client, Invalid>;
 //#endregion

package/dist/node.mjs

@@ -1,12 +1,12 @@
-import { n as layer$1 } from "./client-CLemHDCl.mjs";
+import { n as layer$1 } from "./client-JikMOSHo.mjs";
 import { Layer } from "effect";
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
 //#region src/node.ts
 /**
-* Apart from `.`, so an app that brings its own `HttpClient` never loads
+* The client over Node's `http`, which sets no timeout of its own: a mutation can run for hours.
+* It is in `./node`, apart from `.`, so an app that brings its own `HttpClient` never loads
 * `@effect/platform-node`.
 */
-/** 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.16.0",
+  "version": "0.18.1",
   "description": "clankerbox's API contract and client library, for Effect",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@gjermundgaraba/effect-actions": "0.14.0"
+    "@gjermundgaraba/effect-actions": "0.17.0"
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.4",
@@ -36,8 +36,9 @@
     "@types/node": "26.6.4",
     "effect": "4.0.4",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vite-plus": "1.2.0",
+    "vitest": "5.0.4"
   },
   "peerDependencies": {
     "@effect/platform-node": "~4.0.4",