create-vimp-game 0.1.0

package/bin/create-vimp-game.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { main, reportError } from '../src/cli.js';
+
+// Точка входа `npm create vimp-game <dir>`: разбор argv и печать ошибок
+// живут в src/cli.js, здесь остаётся только контракт процесса.
+
+main(process.argv.slice(2)).then(
+  code => {
+    process.exitCode = code;
+  },
+  error => {
+    reportError(error);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "create-vimp-game",
+  "version": "0.1.0",
+  "description": "Scaffolder for VIMP game plugins",
+  "keywords": [
+    "vimp",
+    "scaffold",
+    "game",
+    "template"
+  ],
+  "homepage": "https://github.com/lgick/vimp#readme",
+  "bugs": {
+    "url": "https://github.com/lgick/vimp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/lgick/vimp.git",
+    "directory": "packages/create-vimp-game"
+  },
+  "author": "lgick",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "bin": {
+    "create-vimp-game": "./bin/create-vimp-game.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "prepack": "node ./scripts/write-versions.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,227 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { generate, GenerateError } from './generator.js';
+import { askAnswers } from './prompts.js';
+import { checkTools, initGit } from './preflight.js';
+import {
+  buildTokens,
+  defaultPackageName,
+  defaultTitle,
+  toGameId,
+  TokenError,
+} from './tokens.js';
+import { resolveVersions, toPins } from './versions.js';
+import { color, log, nextSteps, warn } from './ui.js';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(moduleDir, '..');
+
+export class UsageError extends Error {}
+
+export const USAGE = `Usage: create-vimp-game <directory> [options]
+
+  --id <id>          game id, kebab-case (default: directory name)
+  --title <title>    human-readable title
+  --package <name>   npm package name (default: @vimp-games/<id>)
+  --author <name>
+  --yes, -y          accept all defaults, no prompts
+  --force            allow a non-empty target directory
+  --no-git           skip \`git init\`
+  --engine-path <p>  dev only: link a local engine checkout
+  --core-path <p>    dev only: [patch.crates-io] for vimp-engine-core
+  --help, --version
+`;
+
+const VALUE_OPTIONS = new Map([
+  ['--id', 'id'],
+  ['--title', 'title'],
+  ['--package', 'packageName'],
+  ['--author', 'author'],
+  ['--engine-path', 'enginePath'],
+  ['--core-path', 'corePath'],
+]);
+
+export function parseArgs(argv) {
+  const args = { git: true };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (VALUE_OPTIONS.has(arg)) {
+      i += 1;
+
+      // значение, начинающееся с '--', — почти всегда забытый аргумент:
+      // без проверки следующий флаг тихо стал бы названием игры
+      if (argv[i] === undefined || argv[i].startsWith('--')) {
+        throw new UsageError(`option '${arg}' needs a value\n\n${USAGE}`);
+      }
+
+      args[VALUE_OPTIONS.get(arg)] = argv[i];
+      continue;
+    }
+
+    switch (arg) {
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+
+      case '--version':
+      case '-v':
+        args.version = true;
+        break;
+
+      case '--yes':
+      case '-y':
+        args.yes = true;
+        break;
+
+      case '--force':
+        args.force = true;
+        break;
+
+      case '--no-git':
+        args.git = false;
+        break;
+
+      default:
+        if (arg.startsWith('-')) {
+          throw new UsageError(`unknown option '${arg}'\n\n${USAGE}`);
+        }
+
+        if (args.directory !== undefined) {
+          throw new UsageError(`unexpected argument '${arg}'\n\n${USAGE}`);
+        }
+
+        args.directory = arg;
+    }
+  }
+
+  return args;
+}
+
+// дефолты для интерактива и для --yes считаются одинаково: ответы человека
+// лишь перекрывают их
+export function buildDefaults(args) {
+  const directory = args.directory ?? 'my-game';
+  const id = args.id ?? toGameId(path.basename(path.resolve(directory)));
+
+  return {
+    directory,
+    id,
+    title: args.title ?? defaultTitle(id),
+    packageName: args.packageName ?? defaultPackageName(id),
+    author: args.author ?? '',
+  };
+}
+
+// пересчёт дефолтов по ходу интерактива: каталог, названный вручную,
+// обязан тянуть за собой id, а тот — заголовок и имя пакета. Флаги из argv
+// остаются сильнее всего, что выводится из ответов
+export function buildDerivers(args) {
+  return {
+    id: directory =>
+      args.id ?? toGameId(path.basename(path.resolve(directory))),
+    title: id => args.title ?? defaultTitle(id),
+    packageName: id => args.packageName ?? defaultPackageName(id),
+  };
+}
+
+async function ensurePathExists(option, value) {
+  if (value === undefined) {
+    return;
+  }
+
+  try {
+    await stat(path.resolve(value));
+  } catch {
+    throw new UsageError(`option '${option}': no such path '${value}'`);
+  }
+}
+
+async function ownVersion() {
+  const manifest = JSON.parse(
+    await readFile(path.join(packageRoot, 'package.json'), 'utf8'),
+  );
+
+  return manifest.version;
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  if (args.version) {
+    process.stdout.write(`${await ownVersion()}\n`);
+    return 0;
+  }
+
+  // интерактив имеет смысл только у живого терминала: в CI и под пайпом
+  // вопросы повисли бы без ответа
+  const interactive = args.yes !== true && process.stdin.isTTY === true;
+
+  if (args.directory === undefined && !interactive) {
+    throw new UsageError(`missing <directory>\n\n${USAGE}`);
+  }
+
+  // опечатку в dev-путях иначе видно только на `npm install`, невнятной
+  // ошибкой npm — и уже поверх сгенерированного проекта
+  await Promise.all([
+    ensurePathExists('--engine-path', args.enginePath),
+    ensurePathExists('--core-path', args.corePath),
+  ]);
+
+  const answers = await askAnswers(buildDefaults(args), {
+    interactive,
+    derive: buildDerivers(args),
+  });
+  const pins = toPins(await resolveVersions());
+
+  const tokens = buildTokens({
+    id: answers.id,
+    title: answers.title,
+    packageName: answers.packageName,
+    author: answers.author,
+    ...pins,
+  });
+
+  const targetDir = path.resolve(answers.directory);
+
+  await generate({
+    templateDir: path.join(packageRoot, 'templates', 'default'),
+    targetDir,
+    tokens,
+    force: args.force === true,
+    enginePath: args.enginePath,
+    corePath: args.corePath,
+  });
+
+  if (args.git) {
+    await initGit(targetDir);
+  }
+
+  for (const tool of await checkTools()) {
+    warn(`${color.bold(tool.command)} not found — ${tool.hint}`);
+  }
+
+  log(nextSteps({ directory: answers.directory, tokens }));
+
+  return 0;
+}
+
+export function reportError(error) {
+  const known =
+    error instanceof UsageError ||
+    error instanceof GenerateError ||
+    error instanceof TokenError;
+
+  process.stderr.write(
+    known ? `${error.message}\n` : `${error.stack ?? error.message}\n`,
+  );
+}

package/src/generator.js

@@ -0,0 +1,196 @@
+import {
+  readdir,
+  mkdir,
+  readFile,
+  writeFile,
+  copyFile,
+  stat,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+// Разворачивание templates/default в каталог игры: обход дерева, подстановка
+// {{ТОКЕНОВ}}, переименования служебных имён.
+
+export class GenerateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GenerateError';
+  }
+}
+
+// подстановка идёт только в текстовых файлах: ассеты (webm/mp3) копируются
+// побайтово, иначе кодировка их портит
+const TEXT_EXTENSIONS = new Set([
+  '.js',
+  '.json',
+  '.rs',
+  '.toml',
+  '.md',
+  '.html',
+  '.css',
+  '.txt',
+  '.gitignore',
+]);
+
+const TOKEN_RE = /\{\{([A-Z0-9_]+)\}\}/g;
+
+// внутри репозитория движка файлы шаблона не должны выглядеть настоящими:
+// package.json.tpl не подхватят workspaces, _gitignore — git
+export function targetName(name) {
+  const withoutTpl = name.endsWith('.tpl') ? name.slice(0, -4) : name;
+
+  return withoutTpl.startsWith('_') ? `.${withoutTpl.slice(1)}` : withoutTpl;
+}
+
+export function isTextFile(sourceName) {
+  if (sourceName.endsWith('.tpl')) {
+    return true;
+  }
+
+  const name = targetName(sourceName);
+
+  return TEXT_EXTENSIONS.has(path.extname(name) || name);
+}
+
+export function renderTokens(content, tokens, file) {
+  const rendered = content.replace(TOKEN_RE, (match, key) => {
+    if (!(key in tokens)) {
+      throw new GenerateError(`unknown token ${match} in ${file}`);
+    }
+
+    return tokens[key];
+  });
+
+  // токен неизвестного вида ({{ foo }}, {{Bar}}) TOKEN_RE не ловит: такой
+  // мусор уехал бы в файлы игры молча.
+  //
+  // Цена стража: любая пара `{{…}}` в шаблоне запрещена, включая
+  // экранирование фигурной скобки в Rust (`format!("{{")`). Такой код в
+  // шаблоне пишется через промежуточную переменную или обходом форматтера
+  const leftover = rendered.match(/\{\{[^}]*\}\}/);
+
+  if (leftover !== null) {
+    throw new GenerateError(`unsubstituted token ${leftover[0]} in ${file}`);
+  }
+
+  return rendered;
+}
+
+// каталог должен отсутствовать или быть пустым: генератор пишет поверх и
+// без проверки затёр бы чужую работу
+export async function ensureTargetDir(dir, { force = false } = {}) {
+  let entries;
+
+  try {
+    entries = await readdir(dir);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      await mkdir(dir, { recursive: true });
+      return;
+    }
+
+    throw error;
+  }
+
+  if (entries.length > 0 && !force) {
+    throw new GenerateError(
+      `target directory is not empty: ${dir} (use --force to write into it)`,
+    );
+  }
+}
+
+// rootDir отдельно от targetDir: список созданных файлов собирается путями
+// от корня игры, а рекурсия спускается по подкаталогам
+async function copyTree(sourceDir, targetDir, tokens, created, rootDir) {
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const source = path.join(sourceDir, entry.name);
+    const target = path.join(targetDir, targetName(entry.name));
+
+    if (entry.isDirectory()) {
+      await mkdir(target, { recursive: true });
+      await copyTree(source, target, tokens, created, rootDir);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    if (isTextFile(entry.name)) {
+      const content = await readFile(source, 'utf8');
+
+      await writeFile(target, renderTokens(content, tokens, source), 'utf8');
+    } else {
+      await copyFile(source, target);
+    }
+
+    created.push(path.relative(rootDir, target));
+  }
+}
+
+// dev-режимы этапа 6: игра собирается против несобранного релиза движка —
+// пакет берётся из локального чекаута, крейт подменяется patch.crates-io
+async function applyEnginePath(targetDir, enginePath) {
+  const file = path.join(targetDir, 'package.json');
+  const manifest = JSON.parse(await readFile(file, 'utf8'));
+
+  manifest.devDependencies = {
+    ...manifest.devDependencies,
+    'vimp-engine': `file:${path.resolve(enginePath)}`,
+  };
+
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+
+async function applyCorePath(targetDir, corePath) {
+  const file = path.join(targetDir, 'Cargo.toml');
+  const patch =
+    '\n[patch.crates-io]\n' +
+    `vimp-engine-core = { path = "${path.resolve(corePath)}" }\n`;
+
+  const content = await readFile(file, 'utf8');
+
+  await writeFile(file, `${content.trimEnd()}\n${patch}`, 'utf8');
+}
+
+async function exists(file) {
+  try {
+    await stat(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function generate({
+  templateDir,
+  targetDir,
+  tokens,
+  force = false,
+  enginePath,
+  corePath,
+}) {
+  await ensureTargetDir(targetDir, { force });
+
+  const created = [];
+
+  await copyTree(templateDir, targetDir, tokens, created, targetDir);
+
+  if (
+    enginePath !== undefined &&
+    (await exists(path.join(targetDir, 'package.json')))
+  ) {
+    await applyEnginePath(targetDir, enginePath);
+  }
+
+  if (
+    corePath !== undefined &&
+    (await exists(path.join(targetDir, 'Cargo.toml')))
+  ) {
+    await applyCorePath(targetDir, corePath);
+  }
+
+  return created.sort();
+}

package/src/preflight.js

@@ -0,0 +1,48 @@
+import { spawn } from 'node:child_process';
+
+// Проверка окружения и git init. Отсутствие cargo/wasm-pack генерацию не
+// блокирует: файлы игры создаются, ошибка всплывёт на npm run core:build —
+// к тому моменту у автора уже есть проект и подсказка по установке.
+
+const TOOLS = [
+  {
+    command: 'cargo',
+    hint: 'install Rust: https://rustup.rs',
+  },
+  {
+    command: 'wasm-pack',
+    hint: 'install wasm-pack: cargo install wasm-pack',
+  },
+];
+
+function run(command, args, options = {}) {
+  return new Promise(resolve => {
+    // timeout: зависший `cargo --version` (сеть, битый тулчейн) иначе
+    // держал бы скаффолдер бесконечно — проверка окружения не стоит того
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: 'ignore',
+      shell: false,
+      timeout: 5000,
+    });
+
+    child.on('error', () => resolve(null));
+    child.on('close', code => resolve(code));
+  });
+}
+
+export async function checkTools() {
+  const codes = await Promise.all(
+    TOOLS.map(tool => run(tool.command, ['--version'])),
+  );
+
+  return TOOLS.filter((tool, index) => codes[index] !== 0);
+}
+
+// первый коммит остаётся за автором игры: скаффолдер только заводит
+// репозиторий, чтобы `git diff` работал с первой правки
+export async function initGit(dir) {
+  const code = await run('git', ['init', '--quiet'], { cwd: dir });
+
+  return code === 0;
+}

package/src/prompts.js

@@ -0,0 +1,79 @@
+import { createInterface } from 'node:readline/promises';
+
+import { isValidGameId, isValidPackageName } from './tokens.js';
+
+// Интерактив на node:readline/promises — у пакета нулевые рантайм-зависимости:
+// он ставится через `npm create`, и каждая зависимость здесь превращается в
+// секунду ожидания пользователя.
+
+let rl = null;
+
+function reader() {
+  if (rl === null) {
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+  }
+
+  return rl;
+}
+
+export function closePrompts() {
+  rl?.close();
+  rl = null;
+}
+
+export async function ask(question, fallback = '') {
+  const suffix = fallback === '' ? '' : ` (${fallback})`;
+  const answer = await reader().question(`${question}${suffix}: `);
+
+  return answer.trim() === '' ? fallback : answer.trim();
+}
+
+// переспрос на месте: без него невалидный id всплывал бы TokenError-ом уже
+// после всех пяти вопросов, и вводить пришлось бы заново
+export async function askValid(question, fallback, isValid, hint) {
+  for (;;) {
+    const answer = await ask(question, fallback);
+
+    if (isValid(answer)) {
+      return answer;
+    }
+
+    process.stdout.write(`  ${hint}\n`);
+  }
+}
+
+// один проход вопросов; --yes и не-TTY (CI, пайп) отвечают дефолтами.
+//
+// Дефолты пересчитываются по ходу: человек, назвавший каталог
+// `space-arena`, ждёт «Space Arena» и `@vimp-games/space-arena`, а не
+// значения, выведенные из аргументов до вопросов
+export async function askAnswers(defaults, { interactive = true, derive } = {}) {
+  if (!interactive) {
+    return { ...defaults };
+  }
+
+  try {
+    const directory = await ask('Directory', defaults.directory);
+    const id = await askValid(
+      'Game id',
+      derive.id(directory),
+      isValidGameId,
+      "expected kebab-case, e.g. 'space-arena'",
+    );
+
+    return {
+      directory,
+      id,
+      title: await ask('Title', derive.title(id)),
+      packageName: await askValid(
+        'Package name',
+        derive.packageName(id),
+        isValidPackageName,
+        'expected an npm package name, e.g. @vimp-games/space-arena',
+      ),
+      author: await ask('Author', defaults.author),
+    };
+  } finally {
+    closePrompts();
+  }
+}

package/src/tokens.js

@@ -0,0 +1,99 @@
+// Подстановки шаблона: из ответов CLI выводится полный набор токенов
+// {{…}}, которые generator.js подставляет в файлы templates/default.
+
+// id игры — kebab-case: он же сегмент URL (/games/<id>/), ключ каталога и
+// HostPlugin.id, поэтому пробелы и заглавные в нём недопустимы
+const GAME_ID_RE = /^[a-z][a-z0-9-]*$/;
+
+// имя npm-пакета: правила реестра (опциональная область видимости,
+// нижний регистр, без пробелов)
+const PACKAGE_NAME_RE =
+  /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+export class TokenError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'TokenError';
+  }
+}
+
+export function isValidGameId(id) {
+  return typeof id === 'string' && GAME_ID_RE.test(id) && !id.endsWith('-');
+}
+
+export function isValidPackageName(name) {
+  return (
+    typeof name === 'string' &&
+    name.length > 0 &&
+    name.length <= 214 &&
+    PACKAGE_NAME_RE.test(name)
+  );
+}
+
+// имя каталога встречается любое («My Game 2», «game_v2»); приводим к
+// допустимому id, чтобы --yes не падал на первом же запуске
+export function toGameId(value) {
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/^([0-9])/, 'game-$1');
+}
+
+export function defaultTitle(id) {
+  return id
+    .split('-')
+    .filter(part => part !== '')
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+export function defaultPackageName(id) {
+  return `@vimp-games/${id}`;
+}
+
+export function toCrateName(id) {
+  return `${id}-core`;
+}
+
+// wasm-bindgen выдаёт файлы по имени крейта в snake_case: pkg-web/<crate>_bg.wasm
+export function toCrateSnake(crateName) {
+  return crateName.replace(/-/g, '_');
+}
+
+export function buildTokens({
+  id,
+  title,
+  packageName,
+  author,
+  engineVersion,
+  coreVersion,
+  year = new Date().getFullYear(),
+}) {
+  if (!isValidGameId(id)) {
+    throw new TokenError(
+      `invalid game id '${id}': expected kebab-case, e.g. 'space-arena'`,
+    );
+  }
+
+  const resolvedPackage = packageName ?? defaultPackageName(id);
+
+  if (!isValidPackageName(resolvedPackage)) {
+    throw new TokenError(`invalid npm package name '${resolvedPackage}'`);
+  }
+
+  const crateName = toCrateName(id);
+
+  return {
+    GAME_ID: id,
+    GAME_TITLE: title ?? defaultTitle(id),
+    PACKAGE_NAME: resolvedPackage,
+    CRATE_NAME: crateName,
+    CRATE_SNAKE: toCrateSnake(crateName),
+    ENGINE_VERSION: engineVersion,
+    CORE_VERSION: coreVersion,
+    AUTHOR: author ?? '',
+    YEAR: String(year),
+  };
+}