@akterjs/cli 0.0.0-stage → 0.1.1

package/dist/archive/tar.pure.mjs

@@ -0,0 +1,291 @@
+import { L as reduce, T as join, _ as getSomes, c as every, h as fromIterable, j as map, l as filter, u as findFirst } from "../Array-B4kuTQeW.mjs";
+import { S as none, b as map$1, f as getOrElse, h as isNone, u as fromNullishOr, w as some } from "../Option-DkxSnBhp.mjs";
+import { D as mapAccum, T as make, r as concat$1, y as fromIterable$1 } from "../Stream-bK9QIETN.mjs";
+import { d as replace, m as split, p as slice, u as padStart } from "../String-q5dcsVe4.mjs";
+// src/archive/tar.pure.ts
+/**
+* The tar subset `.akter` archives use (POSIX ustar with pax `path` and `size` records), read and written as streams so
+* an actor database of any size never sits in memory. GNU tar and bsdtar read what it writes.
+*/
+const blockBytes = 512;
+const endBlocks = 2;
+const nameBytes = 100;
+const sizeDigits = 11;
+const octalBase = 8;
+const decimalBase = 10;
+const nothing = 0;
+const terminator = 1;
+/** The largest size the ustar size field holds; a larger entry carries a pax `size` record. */
+const largestUstarSize = octalBase ** sizeDigits - terminator;
+const fileMode = 420;
+const checksumDigits = 6;
+const space = 32;
+const field = {
+	checksum: {
+		at: 148,
+		width: 8
+	},
+	gid: {
+		at: 116,
+		width: 8
+	},
+	magic: {
+		at: 257,
+		width: 8
+	},
+	mode: {
+		at: 100,
+		width: 8
+	},
+	mtime: {
+		at: 136,
+		width: 12
+	},
+	name: {
+		at: 0,
+		width: nameBytes
+	},
+	size: {
+		at: 124,
+		width: 12
+	},
+	type: {
+		at: 156,
+		width: 1
+	},
+	uid: {
+		at: 108,
+		width: 8
+	}
+};
+const encoder = new globalThis.TextEncoder();
+const decoder = new globalThis.TextDecoder();
+const paddingOf = (size) => (blockBytes - size % blockBytes) % blockBytes;
+const octal = (value, width) => `${padStart(width - terminator, "0")(value.toString(octalBase))}\0`;
+const isChecksumByte = (index) => index >= field.checksum.at && index < field.checksum.at + field.checksum.width;
+const checksumOf = (block) => reduce(fromIterable(block), nothing, (total, byte, index) => {
+	if (isChecksumByte(index)) return total + space;
+	return total + byte;
+});
+const fieldsOf = (name, size, typeFlag) => [
+	[field.name.at, name],
+	[field.mode.at, octal(fileMode, field.mode.width)],
+	[field.uid.at, octal(nothing, field.uid.width)],
+	[field.gid.at, octal(nothing, field.gid.width)],
+	[field.size.at, octal(Math.min(size, largestUstarSize), field.size.width)],
+	[field.mtime.at, octal(nothing, field.mtime.width)],
+	[field.type.at, typeFlag],
+	[field.magic.at, "ustar\x0000"]
+];
+const header = (name, size, typeFlag) => {
+	const block = new Uint8Array(blockBytes);
+	for (const [at, text] of fieldsOf(name, size, typeFlag)) block.set(encoder.encode(text), at);
+	const checksum = `${padStart(checksumDigits, "0")(checksumOf(block).toString(octalBase))}\0 `;
+	block.set(encoder.encode(checksum), field.checksum.at);
+	return block;
+};
+/** One pax record, `<length> <key>=<value>\n`, where the length counts its own digits. */
+const paxRecord = (key, value) => {
+	const body = ` ${key}=${value}\n`;
+	const bodyBytes = encoder.encode(body).length;
+	const guess = bodyBytes + String(bodyBytes).length;
+	const length = bodyBytes + String(guess).length;
+	return `${String(length)}${body}`;
+};
+const paxRecords = ({ path, size }) => {
+	const records = [...filter([paxRecord("path", path)], () => encoder.encode(path).length > nameBytes), ...filter([paxRecord("size", String(size))], () => size > largestUstarSize)];
+	return join(records, "");
+};
+const headersFor = (entry) => {
+	const records = encoder.encode(paxRecords(entry));
+	const file = header(slice(nothing, nameBytes)(entry.path), entry.size, "0");
+	if (records.length === nothing) return [file];
+	return [
+		header("PaxHeader", records.length, "x"),
+		records,
+		new Uint8Array(paddingOf(records.length)),
+		file
+	];
+};
+const paddingStream = (size) => make(new Uint8Array(paddingOf(size)));
+/** The bytes of one entry: its headers, its content, and the padding that ends it on a block boundary. */
+const tarEntry = ({ content, path, size }) => concat$1(fromIterable$1(headersFor({
+	path,
+	size
+})), concat$1(content, paddingStream(size)));
+/** The two zero blocks that end an archive. */
+const tarEnd = make(new Uint8Array(blockBytes * endBlocks));
+const initial = {
+	buffered: /* @__PURE__ */ new Uint8Array(),
+	collecting: none(),
+	done: false,
+	pax: none(),
+	remaining: nothing,
+	skip: nothing
+};
+const textAt = (block, { at, width }) => replace(/\0.*$/su, "")(decoder.decode(block.subarray(at, at + width)));
+const paxLine = /^\d+ (?<key>[^=]+)=(?<value>.*)$/su;
+const pairOf = (line) => {
+	const groups = fromNullishOr(paxLine.exec(line)?.groups);
+	return map$1(groups, (found) => [found.key ?? "", found.value ?? ""]);
+};
+const parsePax = (records) => {
+	const lines = split("\n")(decoder.decode(records));
+	const pairs = getSomes(map(lines, pairOf));
+	const valueOf = (key) => map$1(findFirst(pairs, ([name]) => name === key), ([, value]) => value);
+	return {
+		path: valueOf("path"),
+		size: map$1(valueOf("size"), (text) => Number.parseInt(text, decimalBase))
+	};
+};
+const concat = (left, right) => {
+	const joined = new Uint8Array(left.length + right.length);
+	joined.set(left);
+	joined.set(right, left.length);
+	return joined;
+};
+const isZero = (block) => every(fromIterable(block), (byte) => byte === nothing);
+/** A file header: the entry it starts, with any pax path and size before it applied. */
+const fileHeader = (state, block, ustarSize) => {
+	const pax = getOrElse(state.pax, () => ({
+		path: none(),
+		size: none()
+	}));
+	const path = getOrElse(pax.path, () => textAt(block, field.name));
+	const size = getOrElse(pax.size, () => ustarSize);
+	const type = textAt(block, field.type);
+	const next = {
+		...state,
+		pax: none(),
+		remaining: size,
+		skip: paddingOf(size)
+	};
+	if (type !== "0" && type !== "") return [next, []];
+	return [next, [{
+		kind: "entry",
+		path,
+		size
+	}]];
+};
+/** Reads one header block; a zero block ends the archive and a corrupt one stops it. */
+const readHeader = (state, block) => {
+	if (isZero(block)) return [{
+		...state,
+		done: true
+	}, [{ kind: "end" }]];
+	if (Number.parseInt(textAt(block, field.checksum), octalBase) !== checksumOf(block)) return [{
+		...state,
+		done: true
+	}, [{
+		kind: "invalid",
+		reason: "a header failed its checksum"
+	}]];
+	const size = Number.parseInt(textAt(block, field.size), octalBase);
+	if (textAt(block, field.type) === "x") return [{
+		...state,
+		collecting: some(/* @__PURE__ */ new Uint8Array()),
+		remaining: size,
+		skip: paddingOf(size)
+	}, []];
+	return fileHeader(state, block, size);
+};
+const readContent = (state, bytes) => {
+	const taken = bytes.subarray(nothing, state.remaining);
+	const rest = bytes.subarray(taken.length);
+	const remaining = state.remaining - taken.length;
+	if (isNone(state.collecting)) return [
+		{
+			...state,
+			remaining
+		},
+		rest,
+		[{
+			bytes: taken,
+			kind: "data"
+		}]
+	];
+	const collected = concat(state.collecting.value, taken);
+	if (remaining > nothing) return [
+		{
+			...state,
+			collecting: some(collected),
+			remaining
+		},
+		rest,
+		[]
+	];
+	return [
+		{
+			...state,
+			collecting: none(),
+			pax: some(parsePax(collected)),
+			remaining
+		},
+		rest,
+		[]
+	];
+};
+const readBlock = (state, bytes) => {
+	const pending = concat(state.buffered, bytes);
+	if (pending.length < blockBytes) return [
+		{
+			...state,
+			buffered: pending
+		},
+		/* @__PURE__ */ new Uint8Array(),
+		[]
+	];
+	const [next, events] = readHeader({
+		...state,
+		buffered: /* @__PURE__ */ new Uint8Array()
+	}, pending.subarray(nothing, blockBytes));
+	return [
+		next,
+		pending.subarray(blockBytes),
+		events
+	];
+};
+/** Consumes what it can of `bytes` in the current state: entry content, padding, or a header block. */
+const advance = (state, bytes) => {
+	if (state.remaining > nothing) return readContent(state, bytes);
+	if (state.skip > nothing) {
+		const skipped = Math.min(state.skip, bytes.length);
+		return [
+			{
+				...state,
+				skip: state.skip - skipped
+			},
+			bytes.subarray(skipped),
+			[]
+		];
+	}
+	return readBlock(state, bytes);
+};
+const hasWork = (state, rest) => {
+	if (state.done) return false;
+	const atHeader = state.remaining === nothing && state.skip === nothing;
+	return rest.length > nothing || atHeader && state.buffered.length >= blockBytes;
+};
+const parseChunk = (state, chunk) => {
+	const events = [];
+	let current = state;
+	let rest = chunk;
+	while (hasWork(current, rest)) {
+		const [next, left, emitted] = advance(current, rest);
+		current = next;
+		rest = left;
+		events.push(...emitted);
+	}
+	return [current, events];
+};
+const halted = (state) => {
+	if (state.done) return [];
+	return [{ kind: "truncated" }];
+};
+/**
+* Parses a tar stream into entry, data and end events. An archive that stops before its end blocks ends with a
+* `truncated` event, and a corrupt header with an `invalid` one, so a reader never mistakes a cut archive for a
+* complete one.
+*/
+const untar = (bytes) => mapAccum(bytes, () => initial, parseChunk, { onHalt: halted });
+export { tarEnd, tarEntry, untar };

package/dist/archive/zstd.adapter.mjs

@@ -0,0 +1,46 @@
+import { Jn as succeed, M as fail, X as forkScoped, aa as Service, en as sync, et as gen, gn as void_, o as andThen, p as callback, rn as tapError, tt as ignore } from "../Effect-CKFpqbmw.mjs";
+import { Xt as isError } from "../Option-DkxSnBhp.mjs";
+import { W as runForEach, g as fromAsyncIterable, nt as unwrap } from "../Stream-bK9QIETN.mjs";
+import { ArchiveInvalidError } from "./archive-invalid.errors.mjs";
+import { createZstdCompress, createZstdDecompress } from "node:zlib";
+// src/archive/zstd.adapter.ts
+const failedTo = (doing) => (cause) => ArchiveInvalidError.make({ message: `zstd could not ${doing} the archive: ${String(cause)}` });
+const settle = (failed) => (resume) => (error) => {
+	if (isError(error)) {
+		resume(fail(failed(error)));
+		return;
+	}
+	resume(void_);
+};
+/**
+* Pipes bytes through a `node:zlib` zstd stream with backpressure: a fiber writes each chunk and waits for zlib to take
+* it before the next, and the output is read as the stream's async iterable. A failed input destroys the codec, which
+* fails the output.
+*/
+const through = (make, doing) => (bytes) => unwrap(gen(function* zstdStream() {
+	const codec = make();
+	const failed = failedTo(doing);
+	const done = settle(failed);
+	const write = (chunk) => callback((resume) => {
+		codec.write(chunk, done(resume));
+	});
+	const end = callback((resume) => {
+		codec.end(() => {
+			done(resume)();
+		});
+	});
+	const fed = andThen(runForEach(bytes, write), end);
+	const destroyed = ignore(tapError(fed, (cause) => sync(() => {
+		codec.destroy(new Error(cause.message));
+	})));
+	yield* forkScoped(destroyed);
+	return fromAsyncIterable(codec, failed);
+}));
+/** Zstandard through `node:zlib`, which Node 24 and Bun both provide. */
+var Zstd = class extends Service()("@akterjs/cli/archive/zstd.adapter/Zstd") {
+	static layer = succeed(this, {
+		compress: through(createZstdCompress, "compress"),
+		decompress: through(createZstdDecompress, "decompress")
+	});
+};
+export { Zstd };

package/dist/bench/bench-report.pure.mjs

@@ -0,0 +1,120 @@
+import { L as reduce, T as join, j as map, v as groupBy, z as sort } from "../Array-B4kuTQeW.mjs";
+import { n as max } from "../Number-BvkRkfc-.mjs";
+import { a as String$1, f as mapInput, i as Number, n as Boolean, o as combine } from "../Order-C1JC991I.mjs";
+import { F as String$2, I as Struct, U as Tuple, g as Finite, hr as toEntries, n as ArraySchema, v as Int } from "../Schema-MiKt5K1v.mjs";
+import { h as startsWith, l as padEnd, y as trimEnd } from "../String-q5dcsVe4.mjs";
+// src/bench/bench-report.pure.ts
+const Sample = Tuple([String$2, Finite]);
+const Hardware = Struct({
+	arch: String$2,
+	cores: Int,
+	cpu: String$2,
+	memoryGiB: Finite,
+	os: String$2
+});
+const BenchSamples = Struct({
+	elapsedMillis: Finite,
+	hardware: Hardware,
+	name: String$2,
+	runtime: String$2,
+	samples: ArraySchema(Sample)
+});
+const failedPrefix = "failed: ";
+const millisPerSecond = 1e3;
+const percent = 100;
+const first = 0;
+const step = 1;
+const median = 50;
+const tail = 90;
+const farTail = 99;
+const decimals = 2;
+const notices = {
+	cloud: {
+		cost: "cost per row: unmeasured. akter bench doesn't read the app's usage yet.",
+		notice: "AKTER CLOUD RUN: steps ran from the machine below to the app over the network, so every latency includes that path. They describe Akter Cloud only when this generator ran off the machine under load; a published number links this command and states the workload's caveats."
+	},
+	comparison: {
+		cost: "cost per row: unmeasured. akter bench doesn't read another system's bill.",
+		notice: "COMPARISON RUN: another system, not Akter, driven by the same runner. Steps ran from the machine below to it over the network, so every latency includes that path. A published comparison links this command and the workload's script, and states the caveats of each system's setup."
+	},
+	local: {
+		cost: "cost per row: unmeasured. It needs an Akter Cloud run; a local run has no cost to report.",
+		notice: "LOCAL RUN: akter dev on this machine. These numbers describe this machine and this checkout, not Akter Cloud, and aren't published results."
+	}
+};
+const rank = (sorted, quantile) => sorted[Math.max(first, Math.ceil(quantile / percent * sorted.length) - step)] ?? first;
+const latencyOf = (latencies) => {
+	const sorted = sort(latencies, Number);
+	return {
+		max: rank(sorted, percent),
+		p50: rank(sorted, median),
+		p90: rank(sorted, tail),
+		p99: rank(sorted, farTail)
+	};
+};
+const rowOf = (outcome, latencies, elapsedMillis) => ({
+	costPerRow: "unmeasured",
+	failed: startsWith(failedPrefix)(outcome),
+	latencyMillis: latencyOf(latencies),
+	outcome,
+	perSecond: latencies.length / (elapsedMillis / millisPerSecond),
+	steps: latencies.length
+});
+const byFailedThenName = combine(mapInput(Boolean, (row) => row.failed), mapInput(String$1, (row) => row.outcome));
+const benchReport = ({ environment, run, settings }) => {
+	const { elapsedMillis, hardware, name, runtime, samples } = run;
+	const groups = groupBy(samples, ([outcome]) => outcome);
+	const rows = map(toEntries(groups), ([outcome, group]) => rowOf(outcome, map(group, ([, latency]) => latency), elapsedMillis));
+	const total = rowOf("total", map(samples, ([, latency]) => latency), elapsedMillis);
+	return {
+		...environment,
+		...settings,
+		costNote: notices[settings.kind].cost,
+		elapsedMillis,
+		hardware,
+		local: settings.kind === "local",
+		notice: notices[settings.kind].notice,
+		rows: sort(rows, byFailedThenName),
+		runtime,
+		total,
+		workload: name
+	};
+};
+const fixed = (value) => value.toFixed(decimals);
+const tableOf = (rows) => {
+	const cells = map(rows, (row) => [
+		row.outcome,
+		String(row.steps),
+		fixed(row.perSecond),
+		fixed(row.latencyMillis.p50),
+		fixed(row.latencyMillis.p90),
+		fixed(row.latencyMillis.p99),
+		fixed(row.latencyMillis.max),
+		row.costPerRow
+	]);
+	const header = [
+		"outcome",
+		"steps",
+		"per second",
+		"p50 ms",
+		"p90 ms",
+		"p99 ms",
+		"max ms",
+		"cost per row"
+	];
+	const widths = map(header, (title, column) => reduce(cells, title.length, (width, cell) => max(width, cell[column]?.length ?? first)));
+	return map([header, ...cells], (cell) => trimEnd(join(map(cell, (text, column) => padEnd(widths[column] ?? first)(text)), "  ")));
+};
+const reportLines = (report) => [
+	report.notice,
+	`workload ${report.workload}, ${fixed(report.durationMillis / millisPerSecond)} s at concurrency ${report.concurrency}, against ${report.target}; ${report.total.steps} steps in ${fixed(report.elapsedMillis / millisPerSecond)} s`,
+	"",
+	...tableOf([...report.rows, report.total]),
+	"",
+	`hardware: ${report.hardware.cpu}, ${report.hardware.cores} cores, ${fixed(report.hardware.memoryGiB)} GiB, ${report.hardware.os} ${report.hardware.arch}`,
+	`runtime: ${report.runtime}`,
+	`versions: ${join(map(toEntries(report.versions), ([name, version]) => `${name} ${version}`), ", ")}`,
+	`pins: commit ${report.pins.commit} (${report.pins.worktree}), ${report.pins.lockfile} sha256 ${report.pins.lockfileSha256}`,
+	report.costNote
+];
+export { BenchSamples, benchReport, reportLines };

package/dist/bench/bench-runner.pure.mjs

@@ -0,0 +1,89 @@
+import { T as join } from "../Array-B4kuTQeW.mjs";
+import { typeScriptImports } from "../app-entry.pure.mjs";
+// src/bench/bench-runner.pure.ts
+const benchRunner = join([
+	"import { writeFileSync } from \"node:fs\";",
+	"import { arch, cpus, platform, release, totalmem } from \"node:os\";",
+	"import { createInterface } from \"node:readline\";",
+	"import { Cause, Effect, Exit, Layer, Option } from \"effect\";",
+	...typeScriptImports,
+	"",
+	"const config = JSON.parse(process.argv[2]);",
+	"const module = await import(config.workload);",
+	"",
+	"if (typeof module.workload !== \"function\") {",
+	"  console.error(\"akter bench: \" + config.workload + \" has no workload export. Export it as: export const workload = ({ id }) => ({ name, open, step });\");",
+	"  process.exit(1);",
+	"}",
+	"",
+	"// stdin: one JSON line with the URL and, on Akter Cloud, the bearer header; then each refreshed header.",
+	"const lines = createInterface({ input: process.stdin })[Symbol.asyncIterator]();",
+	"const connection = JSON.parse((await lines.next()).value);",
+	"let authorization = connection.authorization;",
+	"void (async () => {",
+	"  for await (const line of lines) authorization = JSON.parse(line).authorization;",
+	"})();",
+	"const headers = () => (authorization === undefined ? {} : { authorization });",
+	"",
+	"// kind is local (akter dev), cloud or comparison, so a workload sends a development identity only to akter dev.",
+	"const workload = module.workload({ id: config.id, kind: connection.kind, url: connection.url });",
+	"const samples = [];",
+	"const failureOf = (cause) => {",
+	"  const error = Cause.squash(cause);",
+	"  return \"failed: \" + (error?._tag ?? error?.name ?? \"defect\");",
+	"};",
+	"// A step with no answer within --step-timeout counts as failed, so one stuck step can't hold the run open.",
+	"const timedOut = \"failed: no answer within \" + config.stepTimeoutMillis + \" ms\";",
+	"const outcomeOf = (exit) => {",
+	"  if (Exit.isFailure(exit)) return failureOf(exit.cause);",
+	"  return Option.isSome(exit.value) ? String(exit.value.value) : timedOut;",
+	"};",
+	"const worker = (session, deadline) =>",
+	"  Effect.gen(function* () {",
+	"    while (performance.now() < deadline) {",
+	"      const started = performance.now();",
+	"      const exit = yield* Effect.exit(Effect.timeoutOption(workload.step(session), config.stepTimeoutMillis));",
+	"      samples.push([outcomeOf(exit), performance.now() - started]);",
+	"    }",
+	"  });",
+	"const opened = Effect.flatMap(Effect.timeoutOption(workload.open, config.stepTimeoutMillis), (session) =>",
+	"  Option.isSome(session) ? Effect.succeed(session.value) : Effect.fail(new Error(\"open got no answer within \" + config.stepTimeoutMillis + \" ms\")),",
+	");",
+	"const run = Effect.gen(function* () {",
+	"  const session = yield* opened;",
+	"  const started = performance.now();",
+	"  const workers = Array.from({ length: config.concurrency }, () => worker(session, started + config.durationMillis));",
+	"  yield* Effect.all(workers, { concurrency: \"unbounded\", discard: true });",
+	"  return performance.now() - started;",
+	"});",
+	"// A comparison workload reaches its own system; an Akter workload gets the Akter client.",
+	"const client = connection.kind === \"comparison\"",
+	"  ? Layer.empty",
+	"  : (await import(\"@akterjs/client/effect\")).akterClient({ headers, url: connection.url });",
+	"const exit = await Effect.runPromiseExit(Effect.scoped(run).pipe(Effect.provide(client)));",
+	"",
+	"if (Exit.isFailure(exit)) {",
+	"  console.error(\"akter bench: \" + workload.name + \" failed before its steps ran.\");",
+	"  console.error(Cause.pretty(exit.cause));",
+	"  // An RPC or HTTP failure keeps its reason, such as an unresolved host, in its reason and cause chain.",
+	"  const next = (error) => error?.reason ?? error?.cause;",
+	"  for (let reason = next(Cause.squash(exit.cause)); reason !== undefined; reason = next(reason)) {",
+	"    console.error(\"caused by: \" + (reason?.message || reason?._tag || String(reason)));",
+	"  }",
+	"  process.exit(1);",
+	"}",
+	"",
+	"const processors = cpus();",
+	"const hardware = {",
+	"  arch: arch(),",
+	"  cores: processors.length,",
+	"  cpu: processors[0]?.model ?? \"unknown\",",
+	"  memoryGiB: totalmem() / 1073741824,",
+	"  os: platform() + \" \" + release(),",
+	"};",
+	"const runtime = process.versions.bun === undefined ? \"node \" + process.versions.node : \"bun \" + process.versions.bun;",
+	"writeFileSync(config.out, JSON.stringify({ elapsedMillis: exit.value, hardware, name: workload.name, runtime, samples }));",
+	"process.exit(0);",
+	""
+], "\n");
+export { benchRunner };