cajonzero 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toby Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# cajonzero
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Serverless（Cloudflare）的 BOX3 **仅 Play 端**引擎：内置账号系统，房间跑在
+Durable Object 上，地图放在 OSS/CDN。
+
+## 安装
+
+```bash
+npm install cajonzero
+npx cj0 --help
+```
+
+## 本地运行
+
+```bash
+npm install
+npm run build     # 构建大厅/后台
+npm run demo      # http://127.0.0.1:8787
+```
+
+打开页面后注册账号、选一张地图即可进入房间。
+管理后台在 `/admin/login`，演示令牌为 `cajonzero-demo-admin-token`。
+
+## 创建自己的服务
+
+```bash
+cj0 create my-server
+cd my-server
+npm install
+npm run dev       # 本地预览
+```
+
+部署前配置三项：
+
+```bash
+npx wrangler kv namespace create CAJONZERO_KV     # 把返回的 id 填进 wrangler.jsonc
+npx wrangler secret put CAJONZERO_SESSION_SECRET  # 会话签名密钥
+npx wrangler secret put BOX_PLAY_ADMIN_TOKEN   # 管理后台令牌
+npm run deploy
+```
+
+## 配置地图
+
+地图不随 worker 上传。把解包后的 `.boxplay` 目录传到 OSS/S3/CDN，
+再在 `cajonzero/maps.json` 中登记：
+
+```json
+{
+  "version": 1,
+  "maps": [
+    {
+      "slug": "race",
+      "root": "https://<你的 CDN>/box3/race/",
+      "worldId": "<世界 id>",
+      "name": "显示名",
+      "etag": "v1"
+    }
+  ]
+}
+```
+
+地图内容更新时记得提升 `etag`（否则会命中 KV 里的旧缓存）。
+房间参数、地图拉取策略等在 `cajonzero/config.json` 中调整。
+
+## 常用命令
+
+```bash
+cj0 serve [--port <port>] [--host <host>]   # 本地启动
+cj0 create <folder>                         # 生成部署项目
+npm test                                       # 运行测试
+npm run ci:gates                               # 完整检查（类型/测试/构建）
+```
+
+更多细节见 [`docs/`](./docs/) 与 [`demo/`](./demo/README.md)。

package/dist/bin/cj0.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/cj0.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+import { mkdirSync, existsSync, statSync, writeFileSync, readdirSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// src/scaffold/templates.ts
+var SCAFFOLD_ENTRY_PATH = "src/index.ts";
+var SCAFFOLD_COMPATIBILITY_DATE = "2026-09-01";
+var SCAFFOLD_KV_PLACEHOLDER_ID = "PLACEHOLDER_KV_ID";
+var SCAFFOLD_ENTRY_CONTENT = [
+  'import config from "../cajonzero/config.json";',
+  'import maps from "../cajonzero/maps.json";',
+  "",
+  'import { serve } from "cajonzero/serve";',
+  "",
+  "export default serve({ config, maps });",
+  'export { Room } from "cajonzero";',
+  ""
+].join("\n");
+var SCAFFOLD_CONFIG_CONTENT = `${JSON.stringify(
+  {
+    name: "<project-name>",
+    admin: { path: "/admin" },
+    room: { tickRate: 64, emptyGraceMs: 48e4 },
+    maps: {
+      cacheTtlSeconds: 86400,
+      maxDownloadBytes: 33554432,
+      concurrency: 8,
+      requestTimeoutMs: 15e3
+    }
+  },
+  null,
+  2
+)}
+`;
+var SCAFFOLD_MAPS_CONTENT = `${JSON.stringify({ version: 1, maps: [] }, null, 2)}
+`;
+var SHIP_UI_SCRIPT = `node -e "const fs=require('node:fs'),p=require('node:path');fs.cpSync(p.join(p.dirname(require.resolve('cajonzero/package.json')),'dist','ui'),p.join('dist','ui'),{recursive:true,force:true})"`;
+function packageJson(options) {
+  const manifest = {
+    name: options.packageName,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: `${SHIP_UI_SCRIPT} && wrangler dev`,
+      build: `${SHIP_UI_SCRIPT} && wrangler deploy --dry-run`,
+      deploy: `${SHIP_UI_SCRIPT} && wrangler deploy`,
+      // `prepare` also runs after `npm install`, so a plain install leaves a
+      // ready-to-deploy project.
+      prepare: SHIP_UI_SCRIPT
+    },
+    dependencies: {
+      cajonzero: options.cajonzeroRange,
+      unstorage: options.unstorageRange
+    },
+    devDependencies: {
+      wrangler: options.wranglerRange
+    }
+  };
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+function wranglerConfig(options) {
+  return [
+    "{",
+    "  // cajonzero-created project \u2014 Cloudflare Workers config.",
+    "  // `main` is the thin worker entry; wrangler bundles it (and cajonzero) on",
+    "  // the fly, so there is no separate worker build step.",
+    '  "$schema": "./node_modules/wrangler/config-schema.json",',
+    `  "name": ${JSON.stringify(options.packageName)},`,
+    `  "main": ${JSON.stringify(SCAFFOLD_ENTRY_PATH)},`,
+    `  "compatibility_date": ${JSON.stringify(options.compatibilityDate)},`,
+    "  // Deliberately NO `nodejs_compat`: cajonzero's worker path is Node-free.",
+    '  "compatibility_flags": [],',
+    "  // Static UI (play lobby + owner admin console) served by the worker.",
+    "  // cajonzero ships the built assets into this directory.",
+    '  "assets": {',
+    '    "directory": "dist/ui",',
+    "    // History routing: deep links (/play/x, /admin/bans) boot index.html.",
+    '    "not_found_handling": "single-page-application",',
+    '    "run_worker_first": ["/api/*", "/runtime/*"]',
+    "  },",
+    "  // Non-secret deployment label. Secrets are set with `wrangler secret put`:",
+    "  //   CAJONZERO_SESSION_SECRET, BOX_PLAY_ADMIN_TOKEN",
+    '  "vars": {',
+    '    "CAJONZERO_ENV": "development"',
+    "  },",
+    '  "kv_namespaces": [',
+    "    {",
+    "      // Player/account data + map-script KV + resolved map-seed cache.",
+    '      "binding": "CAJONZERO_KV",',
+    "      // Replace with `wrangler kv namespace create CAJONZERO_KV` output.",
+    `      "id": ${JSON.stringify(SCAFFOLD_KV_PLACEHOLDER_ID)}`,
+    "    }",
+    "  ],",
+    '  "durable_objects": {',
+    '    "bindings": [',
+    "      {",
+    "        // Per-room actor namespace. `Room` is re-exported by the entry.",
+    '        "name": "ROOMS",',
+    '        "class_name": "Room"',
+    "      }",
+    "    ]",
+    "  },",
+    '  "migrations": [',
+    "    {",
+    '      "tag": "v1",',
+    '      "new_sqlite_classes": ["Room"]',
+    "    }",
+    "  ]",
+    "}",
+    ""
+  ].join("\n");
+}
+function gitignore() {
+  return ["node_modules", "dist", ".wrangler", ".dev.vars", ""].join("\n");
+}
+function readme(options) {
+  return [
+    `# ${options.packageName}`,
+    "",
+    "A serverless (Cloudflare Workers) BOX3 **play** server, scaffolded by",
+    "[`cajonzero`](https://www.npmjs.com/package/cajonzero).",
+    "",
+    "This project contains **no engine source code** \u2014 configuration plus a short",
+    "worker entry that hands `cajonzero/config.json` and `cajonzero/maps.json` to the",
+    "runtime:",
+    "",
+    "```ts",
+    'import config from "../cajonzero/config.json";',
+    'import maps from "../cajonzero/maps.json";',
+    'import { serve } from "cajonzero/serve";',
+    "",
+    "export default serve({ config, maps });",
+    'export { Room } from "cajonzero";',
+    "```",
+    "",
+    "## Quick start",
+    "",
+    "```bash",
+    "npm install     # also syncs cajonzero's prebuilt lobby/console into dist/ui",
+    "npm run dev     # wrangler dev \u2192 http://localhost:8787",
+    "```",
+    "",
+    "`npm run build` validates the deploy by bundling the worker without",
+    "publishing (`wrangler deploy --dry-run`).",
+    "",
+    "## Required secrets",
+    "",
+    "Set both secrets with Wrangler (never commit them):",
+    "",
+    "```bash",
+    "npx wrangler secret put CAJONZERO_SESSION_SECRET   # signs player session proofs",
+    "npx wrangler secret put BOX_PLAY_ADMIN_TOKEN     # owner token for the admin API",
+    "```",
+    "",
+    "## Maps (object storage)",
+    "",
+    "Maps are **not** uploaded with the worker and are never unpacked at runtime.",
+    "Unpack the `.boxplay` yourself and upload the resulting directory to OSS/S3/CDN",
+    "with the archive layout preserved:",
+    "",
+    "```text",
+    "<root>/bundle.json",
+    "<root>/worlds/<worldId>/manifest.json",
+    "<root>/worlds/<worldId>/data/project-state.json",
+    "<root>/worlds/<worldId>/data/blobs/<cid>",
+    "```",
+    "",
+    "Then add an entry to `cajonzero/maps.json`:",
+    "",
+    "```json",
+    "{",
+    '  "version": 1,',
+    '  "maps": [',
+    "    {",
+    '      "slug": "omega",',
+    '      "root": "https://cdn.example.com/cajonzero/omega/",',
+    '      "worldId": "project-omega",',
+    '      "name": "Omega City Reloaded",',
+    '      "version": "1.0.4",',
+    '      "etag": "v1.0.4"',
+    "    }",
+    "  ]",
+    "}",
+    "```",
+    "",
+    "- `root` must be the unpacked map directory and end with `/`.",
+    "- `etag` (or `version`) is the seed-cache revision: bump it whenever you",
+    "  re-upload the map, otherwise the cached world stays stale.",
+    "- The bucket may be public-read; the server fetches it, so no CORS is needed",
+    "  for gameplay. Enable CORS only if the browser loads assets from it.",
+    "",
+    "## Where things live",
+    "",
+    "- **Play lobby** \u2014 the worker serves the lobby at `/`.",
+    "- **Admin console** \u2014 at `/admin` (sign in with `BOX_PLAY_ADMIN_TOKEN`) for",
+    "  player bans and runtime settings; its JSON API is under `/api/admin/*`.",
+    "- **Map catalog** \u2014 `GET /api/maps` returns the entries from `maps.json`.",
+    "",
+    "## Deploy",
+    "",
+    "```bash",
+    "npm run deploy  # wrangler deploy",
+    "```",
+    ""
+  ].join("\n");
+}
+function buildScaffoldFiles(options) {
+  return [
+    { path: "package.json", content: packageJson(options) },
+    { path: "wrangler.jsonc", content: wranglerConfig(options) },
+    { path: SCAFFOLD_ENTRY_PATH, content: SCAFFOLD_ENTRY_CONTENT },
+    {
+      path: "cajonzero/config.json",
+      content: SCAFFOLD_CONFIG_CONTENT.replace("<project-name>", options.packageName)
+    },
+    { path: "cajonzero/maps.json", content: SCAFFOLD_MAPS_CONTENT },
+    { path: ".gitignore", content: gitignore() },
+    { path: "README.md", content: readme(options) }
+  ];
+}
+var CAJONZERO_RANGE_PREFIX = "^";
+var FALLBACK_WRANGLER_RANGE = "^4.151.1";
+var FALLBACK_UNSTORAGE_RANGE = "^1.17.6";
+var PACKAGE_JSON_URL = new URL("../../package.json", import.meta.url);
+var ScaffoldError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ScaffoldError";
+    this.code = code;
+  }
+};
+function readCajonzeroPackage(manifestPath) {
+  const filePath = fileURLToPath(PACKAGE_JSON_URL);
+  const raw = readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  const version = typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "0.0.0";
+  const wrangler = parsed.devDependencies?.["wrangler"];
+  const wranglerRange = typeof wrangler === "string" && wrangler.length > 0 ? wrangler : FALLBACK_WRANGLER_RANGE;
+  const unstorage = parsed.dependencies?.["unstorage"];
+  const unstorageRange = typeof unstorage === "string" && unstorage.length > 0 ? unstorage : FALLBACK_UNSTORAGE_RANGE;
+  return { version, wranglerRange, unstorageRange };
+}
+function toPackageName(folder) {
+  const base = path.basename(folder);
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-._]+/, "").replace(/[-._]+$/, "");
+  return slug.length > 0 ? slug : "cajonzero-app";
+}
+function isNonEmptyDirectory(dir) {
+  if (!existsSync(dir)) return false;
+  if (!statSync(dir).isDirectory()) return false;
+  return readdirSync(dir).length > 0;
+}
+function createProject(folder, options = {}) {
+  const name = typeof folder === "string" ? folder.trim() : "";
+  if (name.length === 0) {
+    throw new ScaffoldError("INVALID_TARGET", "create requires a target folder");
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const target = path.resolve(cwd, name);
+  if (existsSync(target) && !statSync(target).isDirectory()) {
+    throw new ScaffoldError("INVALID_TARGET", `target exists and is not a directory: ${target}`);
+  }
+  if (isNonEmptyDirectory(target)) {
+    throw new ScaffoldError(
+      "TARGET_NOT_EMPTY",
+      `target directory already exists and is not empty: ${target} (refusing to overwrite)`
+    );
+  }
+  const manifest = options.version !== void 0 ? void 0 : readCajonzeroPackage();
+  const version = options.version ?? manifest?.version ?? "0.0.0";
+  const wranglerRange = options.wranglerRange ?? manifest?.wranglerRange ?? FALLBACK_WRANGLER_RANGE;
+  const unstorageRange = options.unstorageRange ?? manifest?.unstorageRange ?? FALLBACK_UNSTORAGE_RANGE;
+  const files = buildScaffoldFiles({
+    packageName: toPackageName(target),
+    cajonzeroRange: `${CAJONZERO_RANGE_PREFIX}${version}`,
+    unstorageRange,
+    wranglerRange,
+    compatibilityDate: options.compatibilityDate ?? SCAFFOLD_COMPATIBILITY_DATE
+  });
+  mkdirSync(target, { recursive: true });
+  for (const file of files) {
+    const fullPath = path.join(target, file.path);
+    mkdirSync(path.dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, file.content, "utf8");
+  }
+  return { target, files: files.map((file) => file.path) };
+}
+
+// src/bin/cj0.ts
+var USAGE = `cj0 \u2014 serverless (Cloudflare) play-only BOX3 engine
+
+Usage:
+  cj0 <command> [options]
+
+Commands:
+  create <folder>                         Scaffold a deployable project
+  serve [--port <port>] [--host <host>]   Run the cajonzero server locally (workerd)
+
+Serve options:
+  --port <port>    Listener port (default: 8787)
+  --host <host>    Listener host (default: 127.0.0.1)
+  --config <file>  Wrangler config (default: wrangler.jsonc)
+  -h, --help       Show this help
+
+Maps: unpack the .boxplay, upload the directory to OSS/CDN, and list its root
+in cajonzero/maps.json. The CLI does not import map archives.
+`;
+var DEFAULT_SERVE_PORT = 8787;
+var DEFAULT_SERVE_HOST = "127.0.0.1";
+var DEFAULT_CONFIG = "wrangler.jsonc";
+var LOCAL_DEV_SECRETS = ["CAJONZERO_SESSION_SECRET", "BOX_PLAY_ADMIN_TOKEN"];
+function localDevVars() {
+  const vars = {};
+  for (const name of LOCAL_DEV_SECRETS) {
+    const value = process.env[name];
+    if (value !== void 0 && value.length > 0) {
+      vars[name] = value;
+    }
+  }
+  return Object.keys(vars).length > 0 ? vars : void 0;
+}
+function printUsage() {
+  process.stdout.write(USAGE);
+}
+function fail(message) {
+  process.stderr.write(`cajonzero: ${message}
+`);
+  process.exitCode = 1;
+}
+function errorLabel(error) {
+  if (error instanceof ScaffoldError) {
+    return `${error.code}: ${error.message}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function runCreate(args) {
+  const [folder] = args;
+  if (folder === void 0) {
+    fail("create requires: cj0 create <folder>");
+    return;
+  }
+  const result = createProject(folder);
+  process.stdout.write(
+    `created project in ${result.target} (${result.files.length} files)
+  ${result.files.join(", ")}
+  next: cd ${folder} && npm install && npm run dev
+`
+  );
+}
+function readFlagValue(args, index, flag) {
+  const inline = args[index];
+  if (inline !== void 0 && inline.startsWith(`${flag}=`)) {
+    return inline.slice(flag.length + 1);
+  }
+  const value = args[index + 1];
+  if (value === void 0 || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+function parseServeFlags(args) {
+  let port = DEFAULT_SERVE_PORT;
+  let host = DEFAULT_SERVE_HOST;
+  let config = DEFAULT_CONFIG;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === void 0) continue;
+    if (arg === "--port" || arg.startsWith("--port=")) {
+      const raw = readFlagValue(args, i, "--port");
+      const parsed = Number(raw);
+      if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+        throw new Error(`--port must be an integer in [0, 65535] (got "${raw}")`);
+      }
+      port = parsed;
+      if (!arg.includes("=")) i += 1;
+    } else if (arg === "--host" || arg.startsWith("--host=")) {
+      host = readFlagValue(args, i, "--host");
+      if (!arg.includes("=")) i += 1;
+    } else if (arg === "--config" || arg.startsWith("--config=")) {
+      config = readFlagValue(args, i, "--config");
+      if (!arg.includes("=")) i += 1;
+    } else {
+      throw new Error(`unexpected serve option "${arg}"`);
+    }
+  }
+  return { port, host, config };
+}
+async function runServe(args) {
+  const flags = parseServeFlags(args);
+  const { unstable_dev, unstable_readConfig } = await import('wrangler');
+  const config = unstable_readConfig({ config: flags.config });
+  const entry = config.main;
+  if (entry === void 0 || entry.length === 0) {
+    throw new Error(`no worker entry ("main") found in ${flags.config}`);
+  }
+  const assetsDir = config.assets?.directory;
+  if (typeof assetsDir === "string" && assetsDir.length > 0) {
+    const configDir = path.dirname(path.resolve(process.cwd(), flags.config));
+    mkdirSync(path.resolve(configDir, assetsDir), { recursive: true });
+  }
+  const secrets = localDevVars();
+  const worker = await unstable_dev(entry, {
+    config: flags.config,
+    ip: flags.host,
+    port: flags.port,
+    local: true,
+    logLevel: "info",
+    // Inject local-dev secrets (from the environment) on top of the config
+    // `vars` so auth/session work locally without `wrangler secret put`.
+    ...secrets !== void 0 ? { vars: { ...config.vars ?? {}, ...secrets } } : {},
+    experimental: {
+      disableExperimentalWarning: true,
+      disableDevRegistry: true,
+      showInteractiveDevSession: false
+    }
+  });
+  process.stdout.write(
+    `cj0 serve listening on http://${worker.address}:${worker.port}
+  (workerd via wrangler dev \xB7 config ${flags.config} \xB7 DO/KV/assets bound)
+` + (secrets !== void 0 ? `  (local dev secrets injected: ${Object.keys(secrets).join(", ")})
+` : "")
+  );
+  let stopping = false;
+  const shutdown = async (signal) => {
+    if (stopping) return;
+    stopping = true;
+    process.stdout.write(`
+cajonzero: received ${signal}, shutting down
+`);
+    try {
+      await worker.stop();
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", () => {
+    void shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    void shutdown("SIGTERM");
+  });
+  await worker.waitUntilExit();
+}
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h" || command === "help") {
+    printUsage();
+    return;
+  }
+  try {
+    switch (command) {
+      case "serve":
+        await runServe(rest);
+        return;
+      case "create":
+        runCreate(rest);
+        return;
+      default:
+        process.stderr.write(`cajonzero: unknown command "${command}"
+
+`);
+        printUsage();
+        process.exitCode = 1;
+    }
+  } catch (error) {
+    fail(errorLabel(error));
+  }
+}
+main(process.argv.slice(2)).catch((error) => {
+  fail(errorLabel(error));
+});
+//# sourceMappingURL=cj0.js.map
+//# sourceMappingURL=cj0.js.map