v8scli 0.3.0 → 0.4.0

package/README.md

@@ -23,6 +23,24 @@ npx v8scli update          # bump pinned releases to the latest
 npx v8scli deps            # (re)download typings of dependencies
 ```
 
+## Privileges and commands (`apiVersion: 2`)
+
+For a manifest with `"apiVersion": 2`, `build` and `upload` write `xplay.generated.ts` next to the
+entry: typed keys from `mod.json` (`PermissionKey`, `PlayerValues`, `SessionSettings`, `CommandKey`,
+`CommandArgs`) and ready `access` / `commands` objects from `v8_scripting/access`. Then the project
+is typechecked (`tsc --noEmit`) — a mistyped key or a player key read as a server setting fails the
+build, not the game. The file is part of the sources: commit it, `upload` packs it.
+
+```ts
+import { access, commands } from './xplay.generated';
+import { playerRef } from 'v8_scripting/access';
+
+const ref = playerRef(controller);
+if (access.permission('use').can(ref)) { /* ... */ }
+const limit = access.value('knives_limit').get(ref) ?? 3;
+commands.on('refill', (ctx, args) => `refilled ${args.target}`);
+```
+
 ## Local SDK/CLI development
 
 `--local` wires the SDK and CLI as `file:` dependencies from your checkouts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v8scli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI for building and publishing V8 point_script mods (companion of v8_scripting)",
   "license": "MIT",
   "type": "module",

package/src/commands/build.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readManifest } from '../common.js';
+import { ensureGenerated, typecheck } from '../typegen.js';
 
 // Локальная самопроверка: тот же контракт, что на портале —
 // только файлы мода + SDK, cs_script/point_script остаётся external.
@@ -9,6 +10,10 @@ export async function build() {
   const manifest = await readManifest();
   const disallowed = new Set();
 
+  // apiVersion 2: ключи мода — типами из mod.json, и сборка без проверки типов не идёт
+  if (await ensureGenerated(manifest))
+    typecheck();
+
   const result = await esbuild.build({
     entryPoints: [manifest.entry],
     bundle: true,

package/src/commands/upload.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { api, readConfig, readManifest } from '../common.js';
+import { ensureGenerated, typecheck } from '../typegen.js';
 
 // Пакует исходники (mod.json + src/ + typings) и создаёт версию на портале.
 // Финальный артефакт собирает сам портал — загружаются только исходники.
@@ -41,6 +42,10 @@ export async function upload() {
   const config = await readConfig();
   const manifest = await readManifest();
 
+  // Сгенерированные типы — часть исходников: портал собирает мод с тем же модулем, что и build
+  if (await ensureGenerated(manifest))
+    typecheck();
+
   // modId по slug
   const { mods } = await api(config, '/api/mods/my');
   const mod = mods.find((m) => m.slug === manifest.slug);

package/src/typegen.js

@@ -0,0 +1,170 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+// Типы ключей мода из mod.json — API apiVersion 2 (v8_scripting/access).
+//
+// Мод спрашивает у платформы разрешения, персональные значения и настройки сервера по ключам из
+// манифеста. Чтобы опечатка в ключе или чтение player-ключа как настройки сервера ловились при сборке,
+// а не в игре, CLI пишет рядом с entry модуль с типами и готовыми access / commands. Файл —
+// часть исходников: его пакует upload, и портал собирает мод с ним же.
+
+export const GENERATED_FILE = 'xplay.generated.ts';
+
+const header = `// Сгенерировано v8scli из mod.json — не править руками: build и upload перепишут.
+`;
+
+function literal(value) {
+  return JSON.stringify(value);
+}
+
+function union(values, fallback) {
+  const items = (values ?? []).filter((value) => typeof value === 'string');
+  return items.length ? items.map(literal).join(' | ') : fallback;
+}
+
+/** Тип значения настройки манифеста в TypeScript */
+function valueType(setting) {
+  switch (setting.type) {
+    case 'bool':
+      return 'boolean';
+    case 'int':
+    case 'float':
+    case 'player':
+    case 'team':
+      return 'number';
+    case 'enum':
+      return union(setting.variants, 'string');
+    case 'set':
+      return `Array<${union(setting.variants, 'string')}>`;
+    case 'players':
+      return 'number[]';
+    case 'audience':
+      return 'AudienceValue';
+    case 'string':
+    case 'color':
+    default:
+      return 'string';
+  }
+}
+
+/** Все настройки, включая зависимые (dependents), в порядке манифеста */
+function flattenSettings(settings, out = []) {
+  for (const setting of settings ?? []) {
+    if (!setting || typeof setting.key !== 'string')
+      continue;
+    out.push(setting);
+    if (Array.isArray(setting.dependents))
+      flattenSettings(setting.dependents, out);
+  }
+  return out;
+}
+
+function fields(settings) {
+  return settings.length
+    ? settings.map((setting) => `  ${literal(setting.key)}: ${valueType(setting)};`).join('\n')
+    : '';
+}
+
+export function generateAccessModule(manifest) {
+  const settings = flattenSettings(manifest.settings);
+  const playerSettings = settings.filter((setting) => setting.scope === 'player');
+  const sessionSettings = settings.filter((setting) => setting.scope !== 'player');
+  const permissions = (manifest.permissions ?? []).filter((item) => item && typeof item.key === 'string');
+  const commands = (manifest.commands ?? []).filter((item) => item && typeof item.key === 'string');
+
+  const permissionDefaults = permissions.map((item) => `    ${literal(item.key)}: ${item.default === true},`).join('\n');
+
+  const commandArgs = commands.map((command) => {
+    const args = (command.args ?? [])
+      .filter((arg) => arg && typeof arg.name === 'string')
+      .map((arg) => {
+        const type = arg.type === 'int' || arg.type === 'duration' || arg.type === 'player'
+          ? 'number'
+          : arg.type === 'enum' ? union(arg.variants, 'string') : 'string';
+        return `${literal(arg.name)}${arg.required ? '' : '?'}: ${type}`;
+      });
+    return `  ${literal(command.key)}: { ${args.join('; ')}${args.length ? ';' : ''} };`;
+  }).join('\n');
+
+  return `${header}import { createAccess, createCommands } from 'v8_scripting/access';
+import type { AudienceValue, CommandContext, CommandResult } from 'v8_scripting/access';
+
+/** Разрешения мода (permissions[]) */
+export type PermissionKey = ${union(permissions.map((item) => item.key), 'never')};
+
+/** Персональные настройки (scope: "player"): у групп и игроков могут быть свои значения */
+export interface PlayerValues {
+${fields(playerSettings)}
+}
+
+/** Настройки мода на сервер (scope: "session") — одно значение на всех */
+export interface SessionSettings {
+${fields(sessionSettings)}
+}
+
+/** Команды мода (commands[]) */
+export type CommandKey = ${union(commands.map((item) => item.key), 'never')};
+
+/** Аргументы команд — уже разобранные платформой: player — AccountID, duration — секунды */
+export interface CommandArgs {
+${commandArgs}
+}
+
+export const access = createAccess<PermissionKey, PlayerValues, SessionSettings>({
+  permissionDefaults: {
+${permissionDefaults}
+  },
+});
+
+const commandsRaw = createCommands<CommandKey>();
+
+/** Обработчик команды с типизированными аргументами */
+export const commands = {
+  on<K extends CommandKey>(key: K, handler: (context: CommandContext, args: CommandArgs[K]) => CommandResult): () => void {
+    return commandsRaw.on(key, handler as (context: CommandContext, args: Record<string, string | number>) => CommandResult);
+  },
+};
+`;
+}
+
+/** Путь сгенерированного модуля — рядом с entry */
+export function generatedPath(manifest, dir = process.cwd()) {
+  return join(dir, dirname(manifest.entry), GENERATED_FILE);
+}
+
+/**
+ * Написать модуль типов для мода apiVersion 2. Переписывает только при изменении — иначе
+ * вотчеры сборки крутились бы по кругу. false — мод apiVersion 1, типов нет
+ */
+export async function ensureGenerated(manifest, dir = process.cwd()) {
+  if (!(Number(manifest.apiVersion) >= 2))
+    return false;
+
+  const path = generatedPath(manifest, dir);
+  const source = generateAccessModule(manifest);
+  const current = existsSync(path) ? await readFile(path, 'utf-8') : '';
+  if (current !== source) {
+    await writeFile(path, source);
+    console.log(`ok: ${path} — типы ключей из mod.json`);
+  }
+  return true;
+}
+
+/**
+ * Проверка типов проекта. Для модов apiVersion 2 обязательна: ради неё и генерируются ключи.
+ * Нужен typescript в проекте (он есть в шаблоне init)
+ */
+export function typecheck(dir = process.cwd()) {
+  const tsc = join(dir, 'node_modules', '.bin', process.platform === 'win32' ? 'tsc.cmd' : 'tsc');
+  if (!existsSync(tsc))
+    throw new Error('typescript is not installed in the mod — run `npm i -D typescript` (apiVersion 2 mods are typechecked on build)');
+  if (!existsSync(join(dir, 'tsconfig.json')))
+    throw new Error('tsconfig.json not found — apiVersion 2 mods are typechecked on build (see the init template)');
+
+  const result = spawnSync(tsc, ['--noEmit', '-p', 'tsconfig.json'], { cwd: dir, stdio: 'inherit', shell: process.platform === 'win32' });
+  if (result.status !== 0)
+    throw new Error('typecheck failed — fix the errors above (keys come from mod.json, see src/' + GENERATED_FILE + ')');
+  console.log('ok: typecheck');
+}

package/templates/package.json

@@ -7,8 +7,8 @@
     "upload": "v8scli upload"
   },
   "devDependencies": {
-    "v8_scripting": "^0.3.0",
-    "v8scli": "^0.2.0",
+    "v8_scripting": "^0.27.0",
+    "v8scli": "^0.4.0",
     "typescript": "^5.9.2"
   }
 }