@gjermundgaraba/clankerbox-sdk 0.4.1 → 0.12.0

package/dist/index.mjs

@@ -0,0 +1,106 @@
+import { A as Capacity, B as hostErrors, C as HostId, D as isId, E as formatId, F as Internal, I as Invalid, L as NotFound, M as ConflictKind, N as ErrorTag, O as parseId, P as HostErrorTag, R as Precondition, S as version, T as Name, _ as Profile, a as HostGroup, b as SshEndpoint, c as readTimeout, d as ActionRecord, f as Checkpoint, g as MachineSpec, h as Machine, i as CheckpointGroup, j as Conflict, k as parseName, l as versionHeader, m as Host, n as client_exports, o as Http, p as CreateRequest, s as MachineGroup, u as ActionName, v as Runtime, w as Id, x as release, y as Setup, z as Unavailable } from "./client-jXYWrnuZ.mjs";
+import { Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+//#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}: ${error.message}` })));
+	const profile = yield* decodeProfile(text, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => new Invalid({ message: `profile ${file}: ${error.message}` })));
+	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.
+*/
+const lineLength = 76;
+/** base64 has no `_`, so no line of the payload can end the 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");
+};
+/**
+* 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.
+*/
+const selfExtracting = (archive) => [
+	"#!/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\"",
+	"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.
+*/
+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}: ${error.message}` }))));
+/** 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;
+	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}: ${error.message}` }))));
+//#endregion
+export { ActionName, ActionRecord, Capacity, Checkpoint, CheckpointGroup, client_exports as Client, Conflict, ConflictKind, CreateRequest, ErrorTag, Host, HostErrorTag, HostGroup, HostId, Http, Id, Internal, Invalid, Machine, MachineGroup, MachineSpec, Name, NotFound, Precondition, Profile, Runtime, Setup, SshEndpoint, Unavailable, formatId, hostErrors, isId, loadProfile, packRecipe, parseId, parseName, readSetup, readTimeout, release, version, versionHeader };

package/dist/node.d.mts

@@ -0,0 +1,6 @@
+import { E as Invalid, n as HostEntry, r as Options, t as Client } from "./client-BVzrg2pq.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. */
+export declare const layer: (hosts: ReadonlyArray<HostEntry>, options?: Options) => Layer.Layer<Client, Invalid>;
+//#endregion

package/dist/node.mjs

@@ -0,0 +1,12 @@
+import { r as make, t as Client } from "./client-jXYWrnuZ.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`.
+*/
+/** 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));
+//#endregion
+export { layer };

package/dist/rolldown-runtime-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/package.json

@@ -1,65 +1,54 @@
 {
   "name": "@gjermundgaraba/clankerbox-sdk",
-  "version": "0.4.1",
-  "description": "Generated Protobuf messages and Connect RPC service descriptors for clankerbox",
+  "version": "0.12.0",
+  "description": "clankerbox's API contract and client library, for Effect",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gjermundgaraba/clankerbox.git",
-    "directory": "protocol"
-  },
-  "homepage": "https://github.com/gjermundgaraba/clankerbox/tree/main/protocol#readme",
-  "bugs": "https://github.com/gjermundgaraba/clankerbox/issues",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "directory": "packages/sdk"
   },
+  "files": [
+    "dist"
+  ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
-    "./resources": {
-      "types": "./dist/gen/clankerbox/v1/resources_pb.d.ts",
-      "import": "./dist/gen/clankerbox/v1/resources_pb.js"
+    "./node": {
+      "types": "./dist/node.d.mts",
+      "import": "./dist/node.mjs"
     },
-    "./machine": {
-      "types": "./dist/gen/clankerbox/v1/machine_pb.d.ts",
-      "import": "./dist/gen/clankerbox/v1/machine_pb.js"
-    },
-    "./session": {
-      "types": "./dist/gen/clankerbox/v1/session_pb.d.ts",
-      "import": "./dist/gen/clankerbox/v1/session_pb.js"
-    },
-    "./host": {
-      "types": "./dist/gen/clankerbox/v1/host_pb.d.ts",
-      "import": "./dist/gen/clankerbox/v1/host_pb.js"
-    },
-    "./profile": {
-      "types": "./dist/gen/clankerbox/v1/profile_pb.d.ts",
-      "import": "./dist/gen/clankerbox/v1/profile_pb.js"
-    }
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
   "dependencies": {
-    "@bufbuild/protobuf": "2.15.0"
+    "@gjermundgaraba/effect-actions": "0.9.0"
   },
   "devDependencies": {
-    "@bufbuild/protoc-gen-es": "2.15.0",
+    "@effect/platform-node": "4.0.0",
+    "@types/node": "26.6.4",
+    "effect": "4.0.0",
     "typescript": "7.0.2",
-    "@connectrpc/connect": "2.2.0",
-    "@connectrpc/connect-node": "2.2.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0"
+  },
+  "peerDependencies": {
+    "@effect/platform-node": "^4.0.0",
+    "effect": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@effect/platform-node": {
+      "optional": true
+    }
   },
   "scripts": {
-    "generate": "./scripts/generate.sh",
-    "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.mjs",
-    "test:package": "node scripts/test-package.mjs"
+    "build": "vp pack",
+    "test": "vp test"
   }
 }

package/README.md

@@ -1,100 +0,0 @@
-# @gjermundgaraba/clankerbox-sdk
-
-Generated Protobuf messages, TypeScript types and Connect RPC service descriptors
-for clankerbox. This ESM package includes compiled JavaScript and declarations;
-consumers do not need protoc, a Go toolchain, or a clankerbox source checkout.
-
-```sh
-npm install @gjermundgaraba/clankerbox-sdk @connectrpc/connect @connectrpc/connect-node
-```
-
-```ts
-import { MachineService, SessionService } from "@gjermundgaraba/clankerbox-sdk";
-import { createClient } from "@connectrpc/connect";
-import { createConnectTransport } from "@connectrpc/connect-node";
-```
-
-The package supplies descriptors, not a transport or lifecycle coordinator.
-Node consumers supply Connect 2.x and use
-`createConnectTransport({httpVersion: "2", ...})`; browser fetch cannot carry
-the bidirectional attachment stream. `@bufbuild/protobuf` is included as a
-runtime dependency. All descriptors are exported at the root and through
-`/resources`, `/machine`, `/session` and `/host` subpaths.
-
-SDK **0.4.1** targets clankerbox **0.9.0** and its attachment-owned session
-contract: sessions are created by `Open.create` inside `AttachSession`, and each
-`Input` is sent at the `input_offset` the guest last acknowledged. Use this pair
-together; SDK and controller version numbers are independent. The wire contract
-is unchanged from SDK 0.4.0 and clankerbox 0.8.0. Older installations and guest
-images are not migrated.
-
-## RPC contract
-
-The wire package is `clankerbox.v1`. The Protobuf sources under
-`clankerbox/v1/` generate Go messages in `gen/clankerbox/v1`, Go Connect
-handlers and clients in `gen/clankerbox/v1/clankerboxv1connect`, and TypeScript
-in `src/gen/clankerbox/v1`. Generated code is checked in.
-
-The services:
-
-- `MachineService`: discovery, resource reads, lifecycle mutations, operation
-  inspection and label replacement. Lifecycle mutations carry idempotency keys
-  and return durable Operations; clients poll `GetOperation` and never resubmit
-  a mutation because a wait timed out. `SetLabels` is the exception: it takes
-  no key and returns the updated `Machine` synchronously.
-- `SessionService`: terminal sessions, mounted on controller, host and guest
-  with endpoint-specific authorization.
-- `HostService`: private operation submission and status plus host and machine
-  inspection. Each action is a `oneof` payload.
-
-Public `Profile`, `Host`, `Machine` and `Checkpoint` messages omit image paths,
-private endpoints, engine store paths and credentials. `internal/rpcmodel`
-converts between these messages and the services' persisted records.
-
-Errors combine a Connect status code with a typed `ErrorDetail` reason.
-`retryable` describes the operation, not terminal input: input is addressed by
-offset, so repeating it on the same attachment is safe and carrying it to another
-is not. The streaming semantics of
-`AttachSession` are specified in
-[terminal sessions](https://github.com/gjermundgaraba/clankerbox/blob/main/docs/terminal-sessions.md).
-
-## Generation and packaging
-
-```sh
-cd protocol
-pnpm install --frozen-lockfile
-pnpm generate
-pnpm build
-pnpm check
-pnpm test
-pnpm test:package
-pnpm pack
-```
-
-`generate` requires protoc 36.1 and installs pinned protoc-gen-go,
-protoc-gen-connect-go and protoc-gen-es into `.tools/`. Go dependency versions
-are in the root `go.mod`; JavaScript versions are in `package.json` and the
-lockfile. Regeneration must leave the checked-in output unchanged.
-
-`pnpm pack` clean-builds JavaScript and declarations and copies the repository's
-MIT license into the package. `pnpm test:package` packs and installs the artifact
-in a temporary consumer with lifecycle scripts disabled, then checks runtime
-imports, TypeScript declarations, package contents and license inclusion.
-
-Publishing uses dedicated `sdk-v<VERSION>` tags, not controller release tags.
-See [SDK publishing](https://github.com/gjermundgaraba/clankerbox/blob/main/docs/sdk-publishing.md)
-for first-publish setup and the tokenless GitHub Actions release workflow.
-
-## Tests
-
-```sh
-go test -race ./internal/rpcmodel ./gen/...
-cd protocol && pnpm test
-```
-
-The Go tests cover conversion round trips, private-field redaction, every
-operation action and state, and typed errors over a real connection. The SDK
-tests cover bigint and JSON precision, oneofs and service shapes.
-`test/real-vm.mjs` and `test/public-session.mjs` drive a running machine and are
-not part of the default test glob; see
-[tests](https://github.com/gjermundgaraba/clankerbox/blob/main/tests/README.md).