@crowdedkingdoms/ckx-kit 0.0.0-stage → 0.1.0-dev.1

package/dist/checks/src/build/wasm-inspect.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * Readers for the few WASM sections the build pipeline checks without instantiating a module:
+ * exported function signatures and the declared memory maximum, and the CLIENT ABI check
+ * CLIENT builds pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_MAX_MEMORY_MB = exports.CLIENT_ARTIFACT_MAX_BYTES = exports.CLIENT_ABI_IMPORTS = exports.WASM_OPT_ARGS = void 0;
+exports.readU32Leb = readU32Leb;
+exports.readWasmName = readWasmName;
+exports.readFunctionExportTypes = readFunctionExportTypes;
+exports.readDefinedMemoryMaximum = readDefinedMemoryMaximum;
+exports.validateClientArtifact = validateClientArtifact;
+function readU32Leb(bytes, offset, end) {
+    let value = 0;
+    let shift = 0;
+    for (let i = 0; i < 5 && offset < end; i++, offset++) {
+        const byte = bytes[offset];
+        value += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0) {
+            return { value, next: offset + 1 };
+        }
+        shift += 7;
+    }
+    throw new Error('malformed WASM u32 LEB');
+}
+function readWasmName(bytes, offset, end) {
+    const length = readU32Leb(bytes, offset, end);
+    const next = length.next + length.value;
+    if (next > end)
+        throw new Error('truncated WASM name');
+    return {
+        value: new TextDecoder().decode(bytes.subarray(length.next, next)),
+        next,
+    };
+}
+/** Resolve exported function names to their declared core-WASM signatures. */
+function readFunctionExportTypes(bytes) {
+    const types = [];
+    const functionTypeIndices = [];
+    const exportedFunctions = new Map();
+    let offset = 8;
+    while (offset < bytes.length) {
+        const sectionId = bytes[offset++];
+        const sectionSize = readU32Leb(bytes, offset, bytes.length);
+        offset = sectionSize.next;
+        const sectionEnd = offset + sectionSize.value;
+        if (sectionEnd > bytes.length)
+            throw new Error('truncated WASM section');
+        if (sectionId === 1) {
+            const count = readU32Leb(bytes, offset, sectionEnd);
+            offset = count.next;
+            for (let i = 0; i < count.value; i++) {
+                if (bytes[offset++] !== 0x60) {
+                    throw new Error('unsupported WASM function type');
+                }
+                const paramCount = readU32Leb(bytes, offset, sectionEnd);
+                offset = paramCount.next;
+                const params = Array.from(bytes.subarray(offset, offset + paramCount.value));
+                offset += paramCount.value;
+                const resultCount = readU32Leb(bytes, offset, sectionEnd);
+                offset = resultCount.next;
+                const results = Array.from(bytes.subarray(offset, offset + resultCount.value));
+                offset += resultCount.value;
+                if (offset > sectionEnd)
+                    throw new Error('truncated WASM function type');
+                types.push({ params, results });
+            }
+        }
+        else if (sectionId === 2) {
+            const count = readU32Leb(bytes, offset, sectionEnd);
+            offset = count.next;
+            for (let i = 0; i < count.value; i++) {
+                offset = readWasmName(bytes, offset, sectionEnd).next;
+                offset = readWasmName(bytes, offset, sectionEnd).next;
+                const kind = bytes[offset++];
+                if (kind !== 0) {
+                    throw new Error('client ABI parser encountered a non-function import');
+                }
+                const typeIndex = readU32Leb(bytes, offset, sectionEnd);
+                offset = typeIndex.next;
+                functionTypeIndices.push(typeIndex.value);
+            }
+        }
+        else if (sectionId === 3) {
+            const count = readU32Leb(bytes, offset, sectionEnd);
+            offset = count.next;
+            for (let i = 0; i < count.value; i++) {
+                const typeIndex = readU32Leb(bytes, offset, sectionEnd);
+                offset = typeIndex.next;
+                functionTypeIndices.push(typeIndex.value);
+            }
+        }
+        else if (sectionId === 7) {
+            const count = readU32Leb(bytes, offset, sectionEnd);
+            offset = count.next;
+            for (let i = 0; i < count.value; i++) {
+                const name = readWasmName(bytes, offset, sectionEnd);
+                offset = name.next;
+                const kind = bytes[offset++];
+                const index = readU32Leb(bytes, offset, sectionEnd);
+                offset = index.next;
+                if (kind === 0)
+                    exportedFunctions.set(name.value, index.value);
+            }
+        }
+        offset = sectionEnd;
+    }
+    const result = new Map();
+    for (const [name, functionIndex] of exportedFunctions) {
+        const typeIndex = functionTypeIndices[functionIndex];
+        const type = types[typeIndex];
+        if (!type)
+            throw new Error(`missing WASM type for export '${name}'`);
+        result.set(name, type);
+    }
+    return result;
+}
+/** Read the sole defined wasm32 memory maximum; imported/multiple memories fail closed. */
+function readDefinedMemoryMaximum(bytes) {
+    if (bytes.length < 8 ||
+        bytes[0] !== 0x00 ||
+        bytes[1] !== 0x61 ||
+        bytes[2] !== 0x73 ||
+        bytes[3] !== 0x6d) {
+        throw new Error('malformed WASM header');
+    }
+    let offset = 8;
+    while (offset < bytes.length) {
+        const sectionId = bytes[offset++];
+        const sectionSize = readU32Leb(bytes, offset, bytes.length);
+        offset = sectionSize.next;
+        const sectionEnd = offset + sectionSize.value;
+        if (sectionEnd > bytes.length)
+            throw new Error('truncated WASM section');
+        if (sectionId !== 5) {
+            offset = sectionEnd;
+            continue;
+        }
+        const count = readU32Leb(bytes, offset, sectionEnd);
+        offset = count.next;
+        if (count.value !== 1) {
+            throw new Error(`artifact must define exactly one memory (got ${count.value})`);
+        }
+        const flags = readU32Leb(bytes, offset, sectionEnd);
+        offset = flags.next;
+        // Only wasm32, unshared memory with an explicit maximum is accepted.
+        if (flags.value !== 1)
+            return null;
+        const minimum = readU32Leb(bytes, offset, sectionEnd);
+        offset = minimum.next;
+        const maximum = readU32Leb(bytes, offset, sectionEnd);
+        offset = maximum.next;
+        if (minimum.value > maximum.value || offset !== sectionEnd) {
+            throw new Error('malformed WASM memory limits');
+        }
+        return maximum.value;
+    }
+    return null;
+}
+/** wasm-opt feature flags rustc-emitted modules need (Phase 0 finding). */
+exports.WASM_OPT_ARGS = [
+    '-O3',
+    '--enable-bulk-memory',
+    '--enable-sign-ext',
+    '--enable-mutable-globals',
+    '--enable-nontrapping-float-to-int',
+];
+const WASM_PAGE_BYTES = 64 * 1024;
+const I32 = 0x7f;
+const I64 = 0x7e;
+/**
+ * What a CLIENT half may import: the `ck` module the CrowdyJS browser glue implements, and
+ * `random_get`, the one WASI call it answers for real (crowdy-client-sdk's `random_bytes`).
+ */
+exports.CLIENT_ABI_IMPORTS = {
+    ck: new Set(['log', 'now_ms', 'state_get', 'state_set', 'host_call']),
+    wasi_snapshot_preview1: new Set(['random_get']),
+};
+/** The functions every CLIENT half exports, with their core-WASM signatures. */
+const CLIENT_ABI_FUNCTIONS = {
+    init: { params: [], results: [] },
+    tick: { params: [I32], results: [] },
+    ck_alloc: { params: [I32], results: [I32] },
+    ck_free: { params: [I32, I32], results: [] },
+    handle_invoke: { params: [I32, I32], results: [I64] },
+};
+const CLIENT_ABI_OPTIONAL = {
+    on_event: { params: [I32, I32], results: [] },
+};
+/** The largest CLIENT half this API builds and serves. */
+exports.CLIENT_ARTIFACT_MAX_BYTES = 512 * 1024;
+/** The linear memory `instrument` clamps a CLIENT half to. */
+exports.CLIENT_MAX_MEMORY_MB = 32;
+/**
+ * A built CLIENT half fit for the browser glue: at most 512 KiB, compiles, imports only the
+ * client ABI, exports `memory`, the `ck_fuel` global `instrument` injects and the entry
+ * points with their signatures, and declares a memory maximum within the clamp. Compiling
+ * does not run the module.
+ */
+async function validateClientArtifact(bytes, maxMemoryMb = exports.CLIENT_MAX_MEMORY_MB) {
+    if (bytes.length > exports.CLIENT_ARTIFACT_MAX_BYTES) {
+        throw new Error(`module is ${bytes.length} bytes; a CLIENT half is at most ${exports.CLIENT_ARTIFACT_MAX_BYTES}`);
+    }
+    let module;
+    try {
+        module = await WebAssembly.compile(bytes);
+    }
+    catch (err) {
+        throw new Error(`malformed WASM module: ${err.message}`);
+    }
+    for (const imp of WebAssembly.Module.imports(module)) {
+        if (imp.kind !== 'function' ||
+            !exports.CLIENT_ABI_IMPORTS[imp.module]?.has(imp.name)) {
+            throw new Error(`module import ${imp.module}::${imp.name} (${imp.kind}) is not part of the CLIENT ABI`);
+        }
+    }
+    const exported = new Map(WebAssembly.Module.exports(module).map((e) => [e.name, e.kind]));
+    if (exported.get('memory') !== 'memory') {
+        throw new Error("module does not export memory 'memory'");
+    }
+    if (exported.get('ck_fuel') !== 'global') {
+        throw new Error("module does not export the global 'ck_fuel'; it was not instrumented");
+    }
+    const expected = {
+        ...CLIENT_ABI_FUNCTIONS,
+    };
+    for (const [name, type] of Object.entries(CLIENT_ABI_OPTIONAL)) {
+        if (exported.has(name))
+            expected[name] = type;
+    }
+    const types = readFunctionExportTypes(bytes);
+    for (const [name, want] of Object.entries(expected)) {
+        if (exported.get(name) !== 'function') {
+            throw new Error(`module does not export function '${name}'; build it with crowdy-client-sdk's register_module!`);
+        }
+        const got = types.get(name);
+        if (!got ||
+            got.params.join(',') !== want.params.join(',') ||
+            got.results.join(',') !== want.results.join(',')) {
+            throw new Error(`module export '${name}' has the wrong signature`);
+        }
+    }
+    const maxPages = readDefinedMemoryMaximum(bytes);
+    const clampPages = Math.floor((maxMemoryMb * 1024 * 1024) / WASM_PAGE_BYTES);
+    if (maxPages === null || maxPages > clampPages) {
+        throw new Error(`module memory maximum ${maxPages ?? 'missing'} exceeds the clamp of ${clampPages} pages`);
+    }
+}

package/dist/cli/src/build.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOD_ARTIFACT_MAX_BYTES = void 0;
+exports.check = check;
+exports.build = build;
+const fs = require("node:fs");
+const path = require("node:path");
+const client_capabilities_1 = require("../../checks/src/build/client-capabilities");
+const exec_source_1 = require("../../checks/src/build/exec-source");
+const wasm_inspect_1 = require("../../checks/src/build/wasm-inspect");
+const kit_1 = require("./kit");
+const tools_1 = require("./tools");
+const TARGET = 'wasm32-unknown-unknown';
+/** The largest module a mod may deploy, the platform's mod limit (4 MiB). */
+exports.MOD_ARTIFACT_MAX_BYTES = 4 * 1024 * 1024;
+/** The platform's source checks, on the files it would receive. Throws its refusal. */
+function check(crate) {
+    (0, exec_source_1.validateExecCrates)([crate.source], crate.kind);
+}
+/** `execBuild`'s steps for one crate, without the platform's sandbox. */
+async function build(crate, options = {}) {
+    check(crate);
+    const sdk = exec_source_1.BUILD_SDK[crate.kind];
+    const work = path.join(crate.dir, 'target', 'ckx-kit', crate.kind);
+    const src = path.join(work, 'crate');
+    fs.rmSync(src, { recursive: true, force: true });
+    for (const [rel, content] of Object.entries(crate.source.files)) {
+        const file = path.join(src, rel);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, rel === 'Cargo.toml' ? (0, exec_source_1.rewriteExecManifest)(content, (0, kit_1.kitPath)('crates', sdk), crate.kind) : content);
+    }
+    fs.copyFileSync((0, kit_1.kitPath)('rust-toolchain.toml'), path.join(src, 'rust-toolchain.toml'));
+    // The registry crates' versions the platform vendors; cargo adds this crate's own entries.
+    fs.copyFileSync((0, kit_1.kitPath)('vendor.lock'), path.join(src, 'Cargo.lock'));
+    // One target directory can serve many crates (CKX_KIT_TARGET_DIR), so their shared
+    // dependencies compile once.
+    const targetDir = process.env.CKX_KIT_TARGET_DIR
+        ? path.resolve(process.env.CKX_KIT_TARGET_DIR)
+        : path.join(work, 'target');
+    (0, tools_1.run)(`cargo build --release --target ${TARGET}`, (0, tools_1.cargo)(), ['build', '--release', '--target', TARGET], {
+        cwd: src,
+        env: { ...process.env, CARGO_TARGET_DIR: targetDir },
+    });
+    const raw = path.join(targetDir, TARGET, 'release', `${crate.libName}.wasm`);
+    if (!fs.existsSync(raw)) {
+        throw new Error(`${crate.name}: no .wasm produced; [lib] crate-type must be ["cdylib"]`);
+    }
+    let bytes;
+    let summary;
+    if (crate.kind === 'client') {
+        const step = path.join(work, 'client');
+        fs.rmSync(step, { recursive: true, force: true });
+        fs.mkdirSync(step, { recursive: true });
+        fs.copyFileSync(raw, path.join(step, 'raw.wasm'));
+        (0, tools_1.run)(`instrument --max-memory-mb ${wasm_inspect_1.CLIENT_MAX_MEMORY_MB}`, (0, tools_1.instrumentBin)(), [
+            'raw.wasm',
+            'metered.wasm',
+            '--max-memory-mb',
+            String(wasm_inspect_1.CLIENT_MAX_MEMORY_MB),
+        ], { cwd: step });
+        (0, tools_1.run)(`wasm-opt ${wasm_inspect_1.WASM_OPT_ARGS.join(' ')}`, (0, tools_1.wasmOpt)(), [...wasm_inspect_1.WASM_OPT_ARGS, 'metered.wasm', '-o', 'final.wasm'], { cwd: step });
+        bytes = fs.readFileSync(path.join(step, 'final.wasm'));
+        await (0, wasm_inspect_1.validateClientArtifact)(bytes);
+        summary = (0, client_capabilities_1.deriveClientCapabilities)(bytes, await (0, client_capabilities_1.readHostCatalog)((0, kit_1.kitPath)('checks', 'compute-toolchain', 'host-catalog.json')));
+    }
+    else {
+        bytes = fs.readFileSync(raw);
+        await (0, exec_source_1.validateExecArtifact)(bytes);
+        if (options.mod && bytes.length > exports.MOD_ARTIFACT_MAX_BYTES) {
+            throw new Error(`module is ${bytes.length} bytes; a mod's module is at most ${exports.MOD_ARTIFACT_MAX_BYTES}`);
+        }
+    }
+    const out = path.resolve(options.out ?? path.join(crate.dir, 'target', 'ckx-kit', `${crate.name}.wasm`));
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, bytes);
+    const pin = (0, kit_1.readPin)();
+    const report = {
+        crate: crate.name,
+        kind: crate.kind,
+        mod: Boolean(options.mod),
+        wasm: out,
+        sizeBytes: bytes.length,
+        sha256: (0, tools_1.sha256)(bytes),
+        notSent: crate.notSent,
+        kit: {
+            version: (0, kit_1.kitVersion)(),
+            toolchain: pin.toolchain_version ?? 'unknown',
+            sdk,
+            sdkVersion: (0, kit_1.sdkVersion)(sdk),
+            rust: pin.rust_version ?? 'unknown',
+        },
+    };
+    if (summary) {
+        report.capabilitySummary = JSON.parse((0, client_capabilities_1.canonicalJson)(summary));
+        report.capabilityHash = (0, client_capabilities_1.capabilityHash)(summary);
+        report.tickIntervalMs = (0, exec_source_1.clientTickIntervalMs)(crate.source.files['Cargo.toml']);
+    }
+    return report;
+}

package/dist/cli/src/crate.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCrate = readCrate;
+const fs = require("node:fs");
+const path = require("node:path");
+const kit_1 = require("./kit");
+const SKIP_DIRS = new Set(['target', '.git', 'node_modules']);
+function walk(dir, rel, out) {
+    for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+        const child = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walk(dir, child, out);
+        }
+        else if (entry.isFile()) {
+            out.push(child);
+        }
+    }
+}
+function sent(rel) {
+    return rel === 'Cargo.toml' || rel === 'README.md' || (rel.startsWith('src/') && rel.endsWith('.rs'));
+}
+/** A CLIENT half is the crate that depends on `crowdy-client-sdk`. */
+function detectKind(manifest) {
+    let section = '';
+    for (const raw of manifest.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        const header = line.match(/^\[([^\]]+)\]$/);
+        if (header)
+            section = header[1].trim();
+        else if (section === 'dependencies' && /^crowdy-client-sdk\s*=/.test(line))
+            return 'client';
+    }
+    return 'exec';
+}
+function readCrate(dir, kind) {
+    const root = path.resolve(dir);
+    const manifestPath = path.join(root, 'Cargo.toml');
+    if (!fs.existsSync(manifestPath))
+        throw new Error(`${root} has no Cargo.toml`);
+    const all = [];
+    walk(root, '', all);
+    const files = {};
+    const notSent = [];
+    for (const rel of all.sort()) {
+        if (sent(rel))
+            files[rel] = fs.readFileSync(path.join(root, rel), 'utf8');
+        else
+            notSent.push(rel);
+    }
+    const manifest = files['Cargo.toml'];
+    const name = (0, kit_1.manifestValue)(manifest, 'package', 'name');
+    if (!name)
+        throw new Error('Cargo.toml has no [package] name');
+    const libName = (0, kit_1.manifestValue)(manifest, 'lib', 'name') ?? name.replace(/-/g, '_');
+    return {
+        dir: root,
+        name,
+        libName,
+        kind: kind ?? detectKind(manifest),
+        source: { name, files },
+        notSent,
+    };
+}

package/dist/cli/src/doctor.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctor = doctor;
+const node_child_process_1 = require("node:child_process");
+const kit_1 = require("./kit");
+const tools_1 = require("./tools");
+function output(cmd, args) {
+    const r = (0, node_child_process_1.spawnSync)(cmd, args, { encoding: 'utf8' });
+    return r.status === 0 ? r.stdout.trim() : null;
+}
+/** What a build on this machine needs, and which platform toolchain this kit matches. */
+function doctor() {
+    const pin = (0, kit_1.readPin)();
+    const rust = pin.rust_version ?? '';
+    const findings = [];
+    const node = Number(process.versions.node.split('.')[0]);
+    findings.push({ ok: node >= 20, what: 'node', detail: `${process.versions.node} (20 or later)` });
+    const cargo = (0, tools_1.which)('cargo') ? output('cargo', ['--version']) : null;
+    findings.push({ ok: Boolean(cargo), what: 'cargo', detail: cargo ?? 'not installed: https://rustup.rs' });
+    if ((0, tools_1.which)('rustup')) {
+        const toolchains = output('rustup', ['toolchain', 'list']) ?? '';
+        const installed = toolchains.split('\n').some((l) => l.startsWith(`${rust}-`) || l.startsWith(`${rust} `));
+        findings.push({
+            ok: installed,
+            what: `Rust ${rust}`,
+            detail: installed ? 'installed' : `missing: rustup toolchain install ${rust} --target wasm32-unknown-unknown`,
+        });
+        const targets = installed ? (output('rustup', ['target', 'list', '--installed', '--toolchain', rust]) ?? '') : '';
+        const wasm = targets.split('\n').includes('wasm32-unknown-unknown');
+        findings.push({
+            ok: wasm,
+            what: 'wasm32-unknown-unknown',
+            detail: wasm ? 'installed' : `missing: rustup target add --toolchain ${rust} wasm32-unknown-unknown`,
+        });
+    }
+    else {
+        findings.push({ ok: false, what: 'rustup', detail: 'not installed: the kit pins the Rust release the platform builds with' });
+    }
+    const opt = (0, tools_1.which)('wasm-opt') ? output('wasm-opt', ['--version']) : null;
+    findings.push({
+        ok: Boolean(opt),
+        what: 'wasm-opt',
+        detail: opt ?? 'not installed (needed for CLIENT halves): apt install binaryen, brew install binaryen',
+    });
+    findings.push({
+        ok: true,
+        what: 'kit',
+        detail: `ckx-kit ${(0, kit_1.kitVersion)()}: platform toolchain ${pin.toolchain_version ?? 'unknown'}, ckx-sdk ${(0, kit_1.sdkVersion)('ckx-sdk')}, crowdy-client-sdk ${(0, kit_1.sdkVersion)('crowdy-client-sdk')}, Rust ${rust}`,
+    });
+    return { findings, ok: findings.every((f) => f.ok) };
+}

package/dist/cli/src/kit.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KIT_ROOT = void 0;
+exports.kitPath = kitPath;
+exports.readPin = readPin;
+exports.kitVersion = kitVersion;
+exports.manifestValue = manifestValue;
+exports.sdkVersion = sdkVersion;
+exports.sdkRequirement = sdkRequirement;
+const fs = require("node:fs");
+const path = require("node:path");
+/** The package root: this file runs from `dist/cli/src/`. */
+exports.KIT_ROOT = path.resolve(__dirname, '..', '..', '..');
+function kitPath(...parts) {
+    return path.join(exports.KIT_ROOT, ...parts);
+}
+/** `kit.pin`: the platform toolchain release this kit was copied from. */
+function readPin() {
+    const pin = {};
+    const file = kitPath('kit.pin');
+    if (!fs.existsSync(file))
+        return pin;
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+        const m = line.match(/^([a-z_]+)=(.*)$/);
+        if (m)
+            pin[m[1]] = m[2];
+    }
+    return pin;
+}
+function kitVersion() {
+    return JSON.parse(fs.readFileSync(kitPath('package.json'), 'utf8')).version;
+}
+/** `[section] key = "value"` from a Cargo manifest; one-line values only, as the platform takes. */
+function manifestValue(manifest, section, key) {
+    let current = '';
+    for (const raw of manifest.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        const header = line.match(/^\[([^\]]+)\]$/);
+        if (header) {
+            current = header[1].trim();
+            continue;
+        }
+        if (current !== section)
+            continue;
+        const kv = line.match(/^([A-Za-z0-9_-]+)\s*=\s*"([^"]*)"$/);
+        if (kv && kv[1] === key)
+            return kv[2];
+    }
+    return null;
+}
+/**
+ * The version of an SDK this kit carries. A release stamps the version published for its tier
+ * (`0.8.0-dev.1`, `0.8.0-test.1`, `0.8.0`); a checkout of the kit carries the bare one.
+ */
+function sdkVersion(sdk) {
+    const manifest = fs.readFileSync(kitPath('crates', sdk, 'Cargo.toml'), 'utf8');
+    const version = manifestValue(manifest, 'package', 'version');
+    if (!version)
+        throw new Error(`crates/${sdk}/Cargo.toml has no version`);
+    return version;
+}
+/** How a crate names this kit's SDK: a prerelease is chosen only by naming it exactly. */
+function sdkRequirement(sdk) {
+    const version = sdkVersion(sdk);
+    return version.includes('-') ? `=${version}` : version;
+}

package/dist/cli/src/main.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = require("node:path");
+const node_util_1 = require("node:util");
+const build_1 = require("./build");
+const crate_1 = require("./crate");
+const doctor_1 = require("./doctor");
+const kit_1 = require("./kit");
+const new_1 = require("./new");
+const USAGE = `ckx-kit: build, check and test ck-exec code as the Crowded Kingdoms platform builds it.
+
+  ckx-kit new <template> <name> [--dir <path>]
+      Start a crate. Templates: ${Object.keys(new_1.TEMPLATES).join(', ')}.
+  ckx-kit check [dir] [--client | --exec]
+      The platform's source checks, on exactly the files it takes (Cargo.toml, README.md,
+      and .rs files under src/).
+  ckx-kit build [dir] [--mod | --client | --exec] [--out <file>] [--json]
+      What execBuild does: the checks, the pinned Rust for wasm32-unknown-unknown with the
+      platform's release profile, then the module check. --mod adds the mod limits; a CLIENT
+      half (a crowdy-client-sdk crate) is metered and optimized, and its capability summary
+      printed.
+  ckx-kit doctor
+      What a build here needs, and the platform toolchain this kit matches.
+
+The platform still builds what you deploy from its source: execModBuild, execModClientBuild,
+execBuild or Crowdy Studio. Docs: https://docs.crowdedkingdoms.com/exec/intro`;
+function kindOf(values) {
+    if (values.client && (values.exec || values.mod))
+        throw new Error('--client is a CLIENT half; it cannot be --exec or --mod');
+    if (values.client)
+        return 'client';
+    if (values.exec || values.mod)
+        return 'exec';
+    return undefined;
+}
+async function main(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            mod: { type: 'boolean' },
+            client: { type: 'boolean' },
+            exec: { type: 'boolean' },
+            out: { type: 'string' },
+            dir: { type: 'string' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    const [command, ...rest] = positionals;
+    if (values.version) {
+        console.log((0, kit_1.kitVersion)());
+        return 0;
+    }
+    if (values.help || !command) {
+        console.log(USAGE);
+        return command || values.help ? 0 : 2;
+    }
+    switch (command) {
+        case 'new': {
+            const [template, name] = rest;
+            if (!template || !name)
+                throw new Error('usage: ckx-kit new <template> <name> [--dir <path>]');
+            const dir = (0, new_1.newProject)(template, name, values.dir);
+            const rel = path.relative(process.cwd(), dir) || '.';
+            const flag = template === 'mod' ? ' --mod' : '';
+            console.log(`created ${rel} (${new_1.TEMPLATES[template].about})\n\n  cd ${rel}\n  cargo test\n  npx ckx-kit build${flag}`);
+            return 0;
+        }
+        case 'check': {
+            const crate = (0, crate_1.readCrate)(rest[0] ?? '.', kindOf(values));
+            (0, build_1.check)(crate);
+            console.log(`${crate.name}: passes the platform's checks (${crate.kind === 'client' ? 'a CLIENT half' : 'a ck-exec crate'})`);
+            if (crate.notSent.length)
+                console.log(`not sent to the platform: ${crate.notSent.join(', ')}`);
+            return 0;
+        }
+        case 'build': {
+            const crate = (0, crate_1.readCrate)(rest[0] ?? '.', kindOf(values));
+            const report = await (0, build_1.build)(crate, { mod: values.mod, out: values.out });
+            if (values.json) {
+                console.log(JSON.stringify(report, null, 2));
+                return 0;
+            }
+            console.log(`${report.crate}: ${report.sizeBytes} bytes, sha256 ${report.sha256}\n  ${report.wasm}`);
+            if (report.capabilitySummary) {
+                console.log(`  capabilities ${report.capabilityHash}; host calls: ${report.capabilitySummary.hostFunctions.join(', ') || 'none'}; ticks every ${report.tickIntervalMs} ms`);
+            }
+            if (report.notSent.length)
+                console.log(`  not sent to the platform: ${report.notSent.join(', ')}`);
+            console.log(`  built as platform toolchain ${report.kit.toolchain} builds it (${report.kit.sdk} ${report.kit.sdkVersion}, Rust ${report.kit.rust})`);
+            return 0;
+        }
+        case 'doctor': {
+            const { findings, ok } = (0, doctor_1.doctor)();
+            for (const f of findings)
+                console.log(`${f.ok ? 'ok  ' : 'FAIL'} ${f.what}: ${f.detail}`);
+            return ok ? 0 : 1;
+        }
+        default:
+            throw new Error(`unknown command '${command}'\n\n${USAGE}`);
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});