incanto 0.1.0

package/bin/incanto-editor.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * incanto-editor — serve the scene-composer page, rendering with the INSTALLED
+ * engine version (the editor bundle ships in this package).
+ *
+ *   npx incanto-editor                       # PROJECT mode: discovers *.scene.json
+ *   npx incanto-editor src/game.scene.json   # SINGLE mode: one fixed file
+ *   npx incanto-editor level.scene.json --output build/level.scene.json --port 5179 --host 0.0.0.0
+ *
+ * API (the page can only address *.scene.json files under the launch directory):
+ *   GET  /api/meta            → { version, mode, root, input?, output? }
+ *   GET  /api/scenes          → [{ rel, abs }]            (project mode)
+ *   POST /api/scenes          → { path } creates a minimal scene (project mode)
+ *   GET  /api/scene[?file=]   → scene JSON  (single mode ignores ?file=)
+ *   PUT  /api/scene[?file=]   → validates the scene shape, writes the file
+ *
+ * Security: on loopback binds, the Host header must be loopback (defeats DNS
+ * rebinding); writes additionally require Origin (when present) to match the
+ * request host. Bodies are capped at 8MB. Addressable paths are root-bounded
+ * and must end in .scene.json.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const EDITOR_DIR = join(PKG_ROOT, 'editor');
+
+// Biome-compatible JSON layout — same algorithm as the editor's
+// src/format-json.ts (inline when the one-line form fits 80 cols).
+function formatSceneJson(value) {
+  const render = (v, depth) => {
+    if (v === null || typeof v !== 'object') return JSON.stringify(v);
+    const inline = inlineForm(v);
+    if (depth * 2 + inline.length <= 80) return inline;
+    const pad = '  '.repeat(depth + 1);
+    const close = '  '.repeat(depth);
+    if (Array.isArray(v)) {
+      if (v.length === 0) return '[]';
+      return `[\n${v.map((x) => pad + render(x, depth + 1)).join(',\n')}\n${close}]`;
+    }
+    const entries = Object.entries(v);
+    if (entries.length === 0) return '{}';
+    const items = entries.map(([k, x]) => `${pad}${JSON.stringify(k)}: ${render(x, depth + 1)}`);
+    return `{\n${items.join(',\n')}\n${close}}`;
+  };
+  const inlineForm = (v) => {
+    if (v === null || typeof v !== 'object') return JSON.stringify(v);
+    if (Array.isArray(v)) return v.length === 0 ? '[]' : `[${v.map(inlineForm).join(', ')}]`;
+    const entries = Object.entries(v);
+    if (entries.length === 0) return '{}';
+    return `{ ${entries.map(([k, x]) => `${JSON.stringify(k)}: ${inlineForm(x)}`).join(', ')} }`;
+  };
+  return `${render(value, 0)}\n`;
+}
+
+function parseArgs(argv) {
+  const args = { input: undefined, output: undefined, port: 5179, host: '127.0.0.1' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--output') args.output = argv[++i];
+    else if (a === '--port') args.port = Number(argv[++i]);
+    else if (a === '--host') args.host = argv[++i];
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (!a.startsWith('-') && !args.input) args.input = a;
+    else {
+      console.error(`unknown argument: ${a}`);
+      args.error = true;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.error || Number.isNaN(args.port) || (args.output && !args.input)) {
+  console.log(`Usage: npx incanto-editor [scene.json] [--output <path>] [--port 5179] [--host 127.0.0.1]
+
+Without a file: PROJECT mode — discovers every *.scene.json under the current
+directory (a picker opens; a single scene auto-opens; new scenes can be created).
+With a file: SINGLE mode — that file only; saving writes to --output (default:
+the input file). --output requires an input file. Use --host 0.0.0.0 inside containers.`);
+  process.exit(args.help && !args.error ? 0 : 1);
+}
+
+const MODE = args.input ? 'single' : 'project';
+const ROOT = resolve('.');
+const INPUT = args.input ? resolve(args.input) : null;
+const OUTPUT = args.input ? resolve(args.output ?? args.input) : null;
+const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
+
+function discoverScenes() {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), depth + 1);
+      } else if (e.name.endsWith('.scene.json')) {
+        const abs = join(dir, e.name);
+        found.push({ rel: relative(ROOT, abs), abs });
+      }
+    }
+  };
+  walk(ROOT, 0);
+  return found.sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+/** Root-bounded, *.scene.json-only — the page can never address anything else. */
+function resolveSceneFile(rel) {
+  if (typeof rel !== 'string' || !rel.endsWith('.scene.json')) return null;
+  const abs = normalize(resolve(ROOT, rel));
+  if (abs !== ROOT && !abs.startsWith(ROOT + sep)) return null;
+  return abs;
+}
+
+function targetFor(url) {
+  if (MODE === 'single') return { input: INPUT, output: OUTPUT };
+  const abs = resolveSceneFile(url.searchParams.get('file'));
+  return abs ? { input: abs, output: abs } : null;
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.wasm': 'application/wasm',
+};
+
+function send(res, status, body, type = 'application/json; charset=utf-8') {
+  res.writeHead(status, { 'content-type': type });
+  res.end(body);
+}
+
+const LOOPBACK_BIND = args.host === '127.0.0.1' || args.host === 'localhost' || args.host === '::1';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+const MAX_BODY = 8 * 1024 * 1024;
+
+function hostAllowed(req) {
+  // Loopback bind: the Host header must be loopback too — a DNS-rebound page
+  // (attacker.com → 127.0.0.1) arrives with Host: attacker.com and is rejected.
+  if (!LOOPBACK_BIND) return true; // non-loopback (containers): host names vary by network
+  const host = (req.headers.host ?? '').replace(/:\d+$/, '');
+  return LOOPBACK_HOSTS.has(host);
+}
+
+function originAllowed(req) {
+  // Same-origin assertion for state-changing requests: when a browser sends an
+  // Origin header it must match the host we were addressed as.
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    return new URL(origin).host === (req.headers.host ?? '');
+  } catch {
+    return false;
+  }
+}
+
+function isSceneShaped(json) {
+  return (
+    json !== null &&
+    typeof json === 'object' &&
+    json.format === 1 &&
+    json.type === 'scene' &&
+    typeof json.name === 'string' &&
+    json.root !== null &&
+    typeof json.root === 'object'
+  );
+}
+
+function readBody(req, res, onJson) {
+  const chunks = [];
+  let received = 0;
+  req.on('data', (c) => {
+    received += c.length;
+    if (received > MAX_BODY) {
+      send(res, 413, JSON.stringify({ error: 'body too large' }));
+      req.destroy();
+      return;
+    }
+    chunks.push(c);
+  });
+  req.on('end', () => {
+    if (res.writableEnded) return;
+    try {
+      const raw = Buffer.concat(chunks).toString('utf-8');
+      onJson(JSON.parse(raw), raw);
+    } catch (error) {
+      send(res, 400, JSON.stringify({ error: String(error.message ?? error) }));
+    }
+  });
+}
+
+const server = createServer((req, res) => {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+
+  if (!hostAllowed(req)) {
+    return send(res, 403, JSON.stringify({ error: 'forbidden host' }));
+  }
+
+  if (url.pathname === '/api/meta') {
+    return send(
+      res,
+      200,
+      JSON.stringify({ version: VERSION, mode: MODE, root: ROOT, input: INPUT, output: OUTPUT }),
+    );
+  }
+
+  if (url.pathname === '/api/scenes') {
+    if (MODE !== 'project') {
+      return send(res, 400, JSON.stringify({ error: 'scene listing is project-mode only' }));
+    }
+    if (req.method === 'GET') {
+      return send(res, 200, JSON.stringify(discoverScenes()));
+    }
+    if (req.method === 'POST') {
+      if (!originAllowed(req)) {
+        return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
+      }
+      readBody(req, res, (body) => {
+        const abs = resolveSceneFile(body?.path);
+        if (!abs) {
+          return send(
+            res,
+            400,
+            JSON.stringify({ error: 'path must be a *.scene.json inside the project' }),
+          );
+        }
+        if (existsSync(abs)) {
+          return send(res, 409, JSON.stringify({ error: `already exists: ${body.path}` }));
+        }
+        const name = basename(abs).replace(/\.scene\.json$/, '') || 'Scene';
+        const scene = {
+          format: 1,
+          type: 'scene',
+          dimension: '2d',
+          name,
+          root: { name, type: 'Node2D' },
+        };
+        try {
+          mkdirSync(dirname(abs), { recursive: true });
+          writeFileSync(abs, formatSceneJson(scene));
+          return send(res, 201, JSON.stringify({ rel: relative(ROOT, abs), abs }));
+        } catch (error) {
+          return send(res, 400, JSON.stringify({ error: String(error.message ?? error) }));
+        }
+      });
+      return;
+    }
+    return send(res, 405, JSON.stringify({ error: 'method not allowed' }));
+  }
+
+  if (url.pathname === '/api/scene') {
+    const target = targetFor(url);
+    if (!target) {
+      return send(
+        res,
+        400,
+        JSON.stringify({ error: '?file= must be a *.scene.json inside the project' }),
+      );
+    }
+    if (req.method === 'GET') {
+      try {
+        const text = readFileSync(target.input, 'utf-8');
+        JSON.parse(text); // must at least be JSON before the page gets it
+        return send(res, 200, text);
+      } catch (error) {
+        return send(res, 422, JSON.stringify({ error: String(error.message ?? error) }));
+      }
+    }
+    if (req.method === 'PUT') {
+      if (!originAllowed(req)) {
+        return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
+      }
+      readBody(req, res, (json, raw) => {
+        if (!isSceneShaped(json)) {
+          return send(
+            res,
+            422,
+            JSON.stringify({
+              error:
+                'not an incanto scene — required: format: 1, type: "scene", name: string, root: object. The file was NOT written.',
+            }),
+          );
+        }
+        try {
+          // Write the client's bytes verbatim — the editor formats scenes
+          // biome-compatibly; re-stringifying here would undo that.
+          writeFileSync(target.output, raw.endsWith('\n') ? raw : `${raw}\n`);
+          return send(res, 200, JSON.stringify({ ok: true, output: target.output }));
+        } catch (error) {
+          return send(res, 400, JSON.stringify({ error: String(error.message ?? error) }));
+        }
+      });
+      return;
+    }
+    return send(res, 405, JSON.stringify({ error: 'method not allowed' }));
+  }
+
+  // static editor assets (path-traversal guarded)
+  const rel = url.pathname === '/' ? '/index.html' : url.pathname;
+  const file = normalize(join(EDITOR_DIR, rel));
+  if (file !== EDITOR_DIR && !file.startsWith(EDITOR_DIR + sep)) {
+    return send(res, 403, JSON.stringify({ error: 'forbidden' }));
+  }
+  try {
+    const body = readFileSync(file);
+    return send(res, 200, body, MIME[extname(file)] ?? 'application/octet-stream');
+  } catch {
+    return send(res, 404, JSON.stringify({ error: `not found: ${rel}` }));
+  }
+});
+
+server.listen(args.port, args.host, () => {
+  console.log(`incanto-editor v${VERSION}`);
+  if (!LOOPBACK_BIND) {
+    console.warn(
+      `  WARNING: bound to ${args.host} — anyone who can reach this port can read/write scene files. Use only on trusted networks (e.g. inside a container).`,
+    );
+  }
+  if (MODE === 'single') {
+    console.log(`  scene:  ${INPUT}${OUTPUT === INPUT ? '' : `\n  output: ${OUTPUT}`}`);
+  } else {
+    const scenes = discoverScenes();
+    console.log(
+      `  project: ${ROOT} (${scenes.length} scene file${scenes.length === 1 ? '' : 's'})`,
+    );
+  }
+  console.log(
+    `  url:    http://${args.host === '0.0.0.0' ? 'localhost' : args.host}:${args.port}/`,
+  );
+});

package/bin/incanto-env.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * incanto-env — deterministic environment generators on the command line.
+ * Emits scene-insertable NodeJson; the same --seed always emits the same
+ * JSON (keep the seed in your scene notes so levels are reproducible).
+ *
+ * Subcommands and flags come straight from the GENERATORS metadata in the
+ * built library, so `--list` and the params can never drift from the code:
+ *
+ *   npx incanto-env --list                                     every generator + params
+ *   npx incanto-env <generator> --seed 42 [--<param> <value> …] [--json]
+ *   npx incanto-env terrain --seed 42 --theme meadow
+ *   … --into src/game.scene.json [--at Root/Level]             insert instead of print
+ *
+ * generateScatter is library-only (`import {generateScatter} from
+ * 'incanto/env'`) — its item templates don't fit CLI flags.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// ---- the catalog (via the BUILT library — exactly what consumers run) ---------------
+const env = await import(pathToFileURL(join(PKG, 'dist', 'env.js')).href);
+
+const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === '--help' || command === '-h' || command === '--list') {
+  const rows = Object.entries(env.GENERATORS).map(([name, meta]) => {
+    const params = Object.entries(meta.params)
+      .map(([param, def]) =>
+        def.type === 'boolean'
+          ? `[--${kebab(param)}]`
+          : `[--${kebab(param)} ${JSON.stringify(def.default)}]`,
+      )
+      .join(' ');
+    return `  ${name.padEnd(12)} ${meta.dimension}  ${meta.description}\n               --seed <n> ${params}`;
+  });
+  console.log(`Usage:
+  incanto-env <generator> --seed <n> [--<param> <value> …] [--json]
+  incanto-env <generator> --seed <n> --into <scene.json> [--at Root/Level]
+  incanto-env --list
+
+--seed is REQUIRED — generators are deterministic, the same seed always emits
+the same JSON. scatter is library-only (needs item templates).
+
+${rows.join('\n')}`);
+  process.exit(command ? 0 : 1);
+}
+
+const meta = env.GENERATORS[command];
+if (!meta) {
+  console.error(
+    `unknown command '${command}'. Available: [${Object.keys(env.GENERATORS).join(', ')}] — the old meadow/forest/island/rocks/clouds generators became themes (e.g. terrain --theme meadow); scatter is library-only (needs item templates).`,
+  );
+  process.exit(1);
+}
+
+// ---- flags (generic, metadata-driven) ------------------------------------------------
+const paramByFlag = new Map();
+const BOOLEAN_FLAGS = new Set(['--json']);
+for (const [param, def] of Object.entries(meta.params)) {
+  const flag = `--${kebab(param)}`;
+  paramByFlag.set(flag, { param, def });
+  if (def.type === 'boolean') BOOLEAN_FLAGS.add(flag);
+}
+
+const flags = new Map();
+for (let i = 0; i < rest.length; i++) {
+  const arg = rest[i];
+  if (!arg.startsWith('--')) {
+    console.error(`unexpected argument '${arg}' — flags look like --seed 42`);
+    process.exit(1);
+  }
+  if (BOOLEAN_FLAGS.has(arg)) {
+    flags.set(arg, true);
+  } else {
+    flags.set(arg, rest[++i]);
+  }
+}
+
+function num(name) {
+  if (!flags.has(name)) return undefined;
+  const value = Number(flags.get(name));
+  if (!Number.isFinite(value)) {
+    console.error(`${name} must be a number, got '${flags.get(name)}'`);
+    process.exit(1);
+  }
+  return value;
+}
+
+const seed = num('--seed');
+if (seed === undefined) {
+  console.error(
+    '--seed is required: generators are deterministic — the same seed always emits the same JSON, ' +
+      'so a level is reproducible from its seed alone. Pick any integer and keep it in your scene notes.',
+  );
+  process.exit(1);
+}
+
+// ---- generate ------------------------------------------------------------------------
+const opts = { seed };
+for (const [flag, value] of flags) {
+  if (flag === '--seed' || flag === '--json' || flag === '--into' || flag === '--at') continue;
+  const known = paramByFlag.get(flag);
+  if (!known) {
+    console.error(
+      `unknown flag '${flag}' for ${command}. Valid: [${[...paramByFlag.keys()].join(', ')}]`,
+    );
+    process.exit(1);
+  }
+  opts[known.param] = known.def.type === 'number' ? num(flag) : value;
+}
+
+let node;
+try {
+  node = env.runGenerator(command, opts);
+} catch (e) {
+  console.error(e?.message ?? String(e));
+  process.exit(1);
+}
+
+const countNodes = (n) => 1 + (n.children ?? []).reduce((sum, c) => sum + countNodes(c), 0);
+
+if (flags.has('--into')) {
+  const file = resolve(flags.get('--into'));
+  const at = flags.get('--at');
+  const scene = JSON.parse(readFileSync(file, 'utf-8'));
+  const out = env.insertIntoScene(scene, node, at);
+  writeFileSync(file, `${JSON.stringify(out, null, 2)}\n`);
+  console.log(
+    `inserted '${node.name}' (${countNodes(node)} node(s)) into ${file}${at ? ` at '${at}'` : ''} — seed ${seed}`,
+  );
+} else {
+  console.log(JSON.stringify(node, null, 2));
+  if (!flags.has('--json')) {
+    console.error(
+      `${command}: ${countNodes(node)} node(s), seed ${seed} — pipe to a file or rerun with --into <scene.json>`,
+    );
+  }
+}