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

package/dist/cli/src/new.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATES = void 0;
+exports.newProject = newProject;
+const fs = require("node:fs");
+const path = require("node:path");
+const kit_1 = require("./kit");
+/** What `new` can start from: the platform's starters, and the kit's own templates. */
+exports.TEMPLATES = {
+    mod: { dir: ['starters', 'grid-mod'], sdk: 'ckx-sdk', about: "a mod: a player's code on a grid they own" },
+    client: { dir: ['templates', 'client'], sdk: 'crowdy-client-sdk', about: "a mod's CLIENT half, run in visitors' browsers" },
+    hub: { dir: ['templates', 'hub'], sdk: 'ckx-sdk', about: 'a hub: state and one handler at a time' },
+    spoke: { dir: ['templates', 'spoke'], sdk: 'ckx-sdk', about: 'a spoke: stateless, scaled out' },
+    'world-tick': { dir: ['starters', 'world-tick'], sdk: 'ckx-sdk', about: "the starter pack's root hub: clock, weather, resources, events" },
+    matchmaker: { dir: ['starters', 'matchmaker'], sdk: 'ckx-sdk', about: 'a rating queue that reserves sessions' },
+    session: { dir: ['starters', 'session'], sdk: 'ckx-sdk', about: 'one game from lobby to result' },
+    'npc-mobs': { dir: ['starters', 'npc-mobs'], sdk: 'ckx-sdk', about: "an area's mobs and NPCs" },
+};
+const CRATE_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+function copyTree(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        if (entry.name === 'target')
+            continue;
+        const src = path.join(from, entry.name);
+        const dst = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyTree(src, dst);
+        else
+            fs.copyFileSync(src, dst);
+    }
+}
+/** The manifest with `[package] name` set and the SDK's line naming this kit's version. */
+function personalise(manifest, name, sdk) {
+    let section = '';
+    let renamed = false;
+    return manifest
+        .split('\n')
+        .map((line) => {
+        const header = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+        if (header) {
+            section = header[1].trim();
+            return line;
+        }
+        if (section === 'package' && !renamed && /^\s*name\s*=/.test(line)) {
+            renamed = true;
+            return `name = "${name}"`;
+        }
+        if (section === 'dependencies' && new RegExp(`^\\s*${sdk}\\s*=`).test(line)) {
+            return `${sdk} = "${(0, kit_1.sdkRequirement)(sdk)}"`;
+        }
+        return line;
+    })
+        .join('\n');
+}
+function newProject(template, name, into) {
+    const spec = exports.TEMPLATES[template];
+    if (!spec)
+        throw new Error(`no template '${template}'; one of: ${Object.keys(exports.TEMPLATES).join(', ')}`);
+    if (!CRATE_NAME.test(name)) {
+        throw new Error(`crate name '${name}' must be lowercase letters, digits, '-' or '_', starting with a letter`);
+    }
+    if (template === 'mod' && name.length > 48)
+        throw new Error("a mod's name is at most 48 characters");
+    const dir = path.resolve(into ?? name);
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0)
+        throw new Error(`${dir} exists and is not empty`);
+    copyTree((0, kit_1.kitPath)(...spec.dir), dir);
+    const manifest = path.join(dir, 'Cargo.toml');
+    fs.writeFileSync(manifest, personalise(fs.readFileSync(manifest, 'utf8'), name, spec.sdk));
+    fs.copyFileSync((0, kit_1.kitPath)('rust-toolchain.toml'), path.join(dir, 'rust-toolchain.toml'));
+    fs.writeFileSync(path.join(dir, '.gitignore'), 'target/\n');
+    return dir;
+}

package/dist/cli/src/tools.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.which = which;
+exports.run = run;
+exports.cargo = cargo;
+exports.cacheDir = cacheDir;
+exports.instrumentBin = instrumentBin;
+exports.wasmOpt = wasmOpt;
+exports.sha256 = sha256;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const kit_1 = require("./kit");
+/** A program on PATH, resolved; null when it is not installed. */
+function which(cmd) {
+    for (const dir of (process.env.PATH ?? '').split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, cmd);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // not in this directory
+        }
+    }
+    return null;
+}
+/**
+ * Runs a step. Its output goes to stderr, so `--json` keeps stdout for the report; a step that
+ * fails throws with the step's name.
+ */
+function run(label, cmd, args, options = {}) {
+    const result = (0, node_child_process_1.spawnSync)(cmd, args, { stdio: ['ignore', process.stderr, process.stderr], ...options });
+    if (result.error) {
+        throw new Error(`${label}: ${result.error.code === 'ENOENT' ? `${cmd} is not installed` : result.error.message}`);
+    }
+    if (result.status !== 0)
+        throw new Error(`${label} failed (exit ${result.status ?? result.signal})`);
+}
+function cargo() {
+    const bin = which('cargo');
+    if (!bin)
+        throw new Error('cargo is not installed: install Rust with rustup (https://rustup.rs)');
+    return bin;
+}
+function cacheDir() {
+    return (process.env.CKX_KIT_CACHE ??
+        path.join(process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache'), 'ckx-kit'));
+}
+function copyTree(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        if (entry.name === 'target')
+            continue;
+        const src = path.join(from, entry.name);
+        const dst = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyTree(src, dst);
+        else
+            fs.copyFileSync(src, dst);
+    }
+}
+function treeHash(dir, h = (0, node_crypto_1.createHash)('sha256'), rel = '') {
+    for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name === 'target')
+            continue;
+        const child = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            treeHash(dir, h, child);
+        else
+            h.update(child).update('\0').update(fs.readFileSync(path.join(dir, child))).update('\0');
+    }
+    return h;
+}
+/**
+ * The platform's `instrument`, which meters a CLIENT half: built from the kit's copy with the
+ * pinned Rust and its lock on first use, and cached by the copy's contents.
+ */
+function instrumentBin() {
+    const source = (0, kit_1.kitPath)('tools', 'instrument');
+    const key = treeHash(source).update(fs.readFileSync((0, kit_1.kitPath)('rust-toolchain.toml'))).digest('hex').slice(0, 16);
+    const dir = path.join(cacheDir(), `instrument-${key}`);
+    const bin = path.join(dir, 'target', 'release', process.platform === 'win32' ? 'instrument.exe' : 'instrument');
+    if (fs.existsSync(bin))
+        return bin;
+    copyTree(source, dir);
+    fs.copyFileSync((0, kit_1.kitPath)('rust-toolchain.toml'), path.join(dir, 'rust-toolchain.toml'));
+    process.stderr.write('== instrument (first use: building the platform\'s metering tool)\n');
+    run('cargo build (instrument)', cargo(), ['build', '--release', '--locked'], { cwd: dir });
+    if (!fs.existsSync(bin))
+        throw new Error(`instrument did not build at ${bin}`);
+    return bin;
+}
+function wasmOpt() {
+    const bin = which('wasm-opt');
+    if (!bin)
+        throw new Error('wasm-opt is not installed: install binaryen (apt install binaryen, brew install binaryen)');
+    return bin;
+}
+function sha256(bytes) {
+    return (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}

package/kit.pin

@@ -0,0 +1,9 @@
+# The platform toolchain release this kit was copied from (sync-kit.sh in the platform's
+# repository). The paths in `copied` are byte-identical to it: change them there, never here.
+toolchain_version=v1.9.0
+toolchain_commit=8b4ef8929c4fd1bb7ccf604032ad75b970aca1a2
+sdk_commit=b4194c7a13e2f3b74279cb4f715c4bcdaba70023
+ckx_sdk_version=0.8.0
+crowdy_client_sdk_version=0.1.0
+rust_version=1.97.1
+copied=crates/ckx-sdk/src crates/crowdy-client-sdk/src tools/instrument/Cargo.toml tools/instrument/Cargo.lock tools/instrument/src checks/src/build/exec-source.ts checks/src/build/exec-source.spec.ts checks/src/build/rust-source-guard.ts checks/src/build/rust-source-guard.spec.ts checks/src/build/wasm-inspect.ts checks/src/build/wasm-inspect.spec.ts checks/src/build/client-capabilities.ts checks/src/build/client-capabilities.spec.ts checks/src/test-support/wasm-module.ts checks/compute-toolchain/host-catalog.json starters rust-toolchain.toml vendor.lock

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@crowdedkingdoms/ckx-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1-dev.1",
+  "description": "Build, check and test Crowded Kingdoms ck-exec mods, hubs and spokes on your machine, as the platform builds them",
+  "license": "MIT OR Apache-2.0",
+  "homepage": "https://docs.crowdedkingdoms.com/exec/intro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CrowdedKingdoms/ckx-kit.git"
+  },
+  "bugs": "https://github.com/CrowdedKingdoms/ckx-kit/issues",
+  "keywords": [
+    "crowded-kingdoms",
+    "ck-exec",
+    "wasm",
+    "gamedev",
+    "rust"
+  ],
+  "bin": {
+    "ckx-kit": "dist/cli/src/main.js"
+  },
+  "files": [
+    "dist/cli/src",
+    "dist/checks/src/build",
+    "crates/*/Cargo.toml",
+    "crates/*/README.md",
+    "crates/*/LICENSE-MIT",
+    "crates/*/LICENSE-APACHE",
+    "crates/*/src/**",
+    "tools/instrument/Cargo.toml",
+    "tools/instrument/Cargo.lock",
+    "tools/instrument/src",
+    "starters/ckx.json",
+    "starters/*/Cargo.toml",
+    "starters/*/src/**",
+    "templates/*/Cargo.toml",
+    "templates/*/src/**",
+    "checks/compute-toolchain/host-catalog.json",
+    "rust-toolchain.toml",
+    "vendor.lock",
+    "kit.pin",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli/src/main.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest",
+    "test:cli": "node --test cli/test/cli.test.mjs",
+    "policy": "node scripts/ci/check-content-policy.mjs"
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "@types/node": "22.15.2",
+    "jest": "29.7.0",
+    "ts-jest": "29.3.2",
+    "typescript": "5.8.3"
+  },
+  "jest": {
+    "rootDir": "checks/src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "transform": {
+      "^.+\\.(t|j)s$": [
+        "ts-jest",
+        {
+          "tsconfig": "<rootDir>/../../tsconfig.json"
+        }
+      ]
+    },
+    "testEnvironment": "node"
+  }
+}

package/rust-toolchain.toml

@@ -0,0 +1,6 @@
+[toolchain]
+# Platform pin for compute-module builds. Bump deliberately: the artifact
+# cache keys include this version, so a bump recompiles every module.
+channel = "1.97.1"
+targets = ["wasm32-wasip1", "wasm32-unknown-unknown"]
+profile = "minimal"

package/starters/ckx.json

@@ -0,0 +1,9 @@
+{
+  "root": "world",
+  "types": {
+    "world": { "kind": "hub", "crate": "world-tick", "wasm": "world_tick.wasm", "client": true, "persist_every_ms": 10000 },
+    "matchmaker": { "kind": "hub", "parent": "world", "crate": "matchmaker", "wasm": "matchmaker.wasm", "client": true, "calls": ["session"] },
+    "session": { "kind": "hub", "parent": "matchmaker", "crate": "session", "wasm": "session.wasm", "client": true },
+    "npcs": { "kind": "hub", "parent": "world", "crate": "npc-mobs", "wasm": "npc_mobs.wasm", "client": true, "calls": ["world"], "scopes": ["world.read"] }
+  }
+}

package/starters/grid-mod/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "grid-mod"
+description = "Starter mod: a player's code on a grid they own; greets visitors and follows what happens in the grid"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+ckx-sdk = "0.8.0"
+serde = { version = "1", features = ["derive"] }

package/starters/grid-mod/src/lib.rs

@@ -0,0 +1,82 @@
+//! A mod: a player's code on a grid they own, deployed with `execModDeploy` rather than in the
+//! app's manifest. One instance runs per grid, keyed by the grid id, in its owner's own
+//! sandbox; its node API calls reach only that grid, and only while the owner still owns it.
+//! It calls no other node, and only players call it.
+//!
+//! Endpoints: `visit` (players), `state` (anyone) and `probe`, which tries to call the app's
+//! root hub and returns the refusal. What happens in the grid arrives at `on_world`.
+
+use ckx_sdk::prelude::*;
+
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq)]
+pub struct GridMod {
+    pub grid: u64,
+    pub visits: u64,
+    pub last_visitor: Option<u64>,
+    /// World events heard, by kind, and the chunk of the last one.
+    pub actors: u64,
+    pub voxels: u64,
+    pub last_chunk: Option<[i64; 3]>,
+}
+
+impl GridMod {
+    fn heard(&mut self, events: &[WorldEvent]) {
+        for e in events {
+            match e.kind.as_str() {
+                WorldEvent::ACTORS => self.actors += 1,
+                WorldEvent::VOXELS => self.voxels += 1,
+                _ => continue,
+            }
+            self.last_chunk = Some(e.chunk);
+        }
+    }
+}
+
+impl Hub for GridMod {
+    fn spawn(ctx: &Ctx, _seed: &[u8]) -> Result<Self> {
+        let grid = ctx.key.parse().map_err(|_| Error::new("a mod's key is its grid id"))?;
+        Ok(Self { grid, ..Self::default() })
+    }
+
+    fn load(_ctx: &Ctx, snapshot: &[u8], _from_version: u64) -> Result<Self> {
+        decode(snapshot)
+    }
+
+    fn persist(&mut self, _ctx: &Ctx) -> Result<Vec<u8>> {
+        encode(self)
+    }
+
+    fn handle(&mut self, ctx: &Ctx, call: Call<'_>) -> Result<Vec<u8>> {
+        match call.method {
+            "visit" => {
+                self.last_visitor = Some(call.player()?);
+                self.visits += 1;
+                encode(&format!("welcome to grid {}, visitor {}", self.grid, self.visits))
+            }
+            "state" => encode(&*self),
+            "probe" => encode(&ctx.call("world", "", "state", &encode(&())?).err().map(|e| e.to_string())),
+            m => Err(Error(format!("no endpoint `{m}`"))),
+        }
+    }
+
+    fn on_world(&mut self, ctx: &Ctx, events: &[WorldEvent]) -> Result<()> {
+        self.heard(events);
+        ctx.persist_now();
+        Ok(())
+    }
+}
+
+ckx_sdk::export_hub!(GridMod);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn world_events_are_counted_by_kind() {
+        let mut m = GridMod { grid: 7, ..GridMod::default() };
+        let e = |kind: &str, x| WorldEvent { grid: 7, kind: kind.into(), chunk: [x, 0, 0] };
+        m.heard(&[e(WorldEvent::ACTORS, 1), e(WorldEvent::VOXELS, 2), e("weather", 3)]);
+        assert_eq!((m.actors, m.voxels, m.last_chunk), (1, 1, Some([2, 0, 0])));
+    }
+}

package/starters/matchmaker/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "matchmaker"
+description = "Starter: a rating queue with widening windows and accept-gated matches that reserve a session"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+ckx-sdk = "0.8.0"
+serde = { version = "1", features = ["derive"] }