v8scli 0.2.2 → 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/bin/v8s.js

@@ -9,14 +9,22 @@ import { deps } from '../src/commands/deps.js';
 import { pull } from '../src/commands/pull.js';
 import { search } from '../src/commands/search.js';
 import { add, remove, update } from '../src/commands/add.js';
+import { create, edit, icon, cover, submit, release, whoami } from '../src/commands/mod.js';
 
 const [, , command, ...args] = process.argv;
 
-const commands = { init, build, login, upload, status, deps, pull, search, add, remove, update };
+const commands = { init, build, login, upload, status, deps, pull, search, add, remove, update,
+  create, edit, icon, cover, submit, release, whoami };
 
 const usage = `v8scli <command>
 
   init <slug> [--local]  scaffold a new mod in ./<slug> (--local: SDK/CLI from checkouts)
+  create [--library]  register the mod from ./mod.json on the portal
+  edit <flags>  change name/description/visibility (--name, --description, --full <file>, --visibility)
+  icon <file>   upload the square icon      cover <file>  upload the 16:9 cover
+  submit        send the latest uploaded version to dev review
+  release "notes"  publish the latest version to prod (admin approves)
+  whoami        show whose token is in use
   build         bundle the mod locally (self-check, dist/<slug>.js)
   login         save portal URL and API token (~/.config/v8s/config.json)
   upload        pack sources and upload a new version to the portal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v8scli",
-  "version": "0.2.2",
+  "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/mod.js

@@ -0,0 +1,168 @@
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { api, readConfig, readManifest } from '../common.js';
+
+/**
+ * Жизненный цикл мода из CLI: создать, описать, дать картинки, отправить.
+ *
+ * До этого создание и оформление жили только в веб-панели, и написать мод
+ * целиком из редактора было нельзя — приходилось прерываться на браузер.
+ * Все команды работают по API-токену.
+ */
+
+/** modId по slug из mod.json; вызывающему нужен и сам манифест */
+async function resolveMod(config, manifest) {
+  const { mods } = await api(config, '/api/mods/my');
+  const mod = mods.find((m) => m.slug === manifest.slug);
+  if (!mod) throw new Error(`mod "${manifest.slug}" not found on the portal — run \`v8scli create\` first`);
+  return mod;
+}
+
+/** Последняя версия мода — с ней работают submit и release */
+async function latestVersion(config, modId) {
+  const { versions } = await api(config, `/api/mods/${modId}`);
+  if (!versions?.length) throw new Error('no versions uploaded yet — run `v8scli upload` first');
+  return versions[0];
+}
+
+const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+
+async function uploadImage(config, modId, path, kind) {
+  const body = await readFile(path);
+  const type = MIME[extname(path).toLowerCase()];
+  if (!type) throw new Error(`unsupported image type: ${extname(path)} (png, jpg, webp)`);
+
+  const form = new FormData();
+  form.append('file', new Blob([body], { type }), basename(path));
+
+  const { mod } = await api(config, `/api/mods/${modId}/${kind}`, { method: 'POST', body: form });
+  console.log(`${kind}: ${kind === 'icon' ? mod.iconUrl : mod.coverUrl}`);
+}
+
+/** v8scli create — заводит мод на портале по mod.json текущей папки */
+export async function create(args) {
+  const config = await readConfig();
+  const manifest = await readManifest();
+
+  const isLibrary = args.includes('--library') || Boolean(manifest.library);
+
+  const { mod } = await api(config, '/api/mods/create', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      slug: manifest.slug,
+      name: typeof manifest.name === 'string' ? manifest.name : manifest.slug,
+      description: typeof manifest.description === 'string' ? manifest.description : '',
+      isLibrary,
+    }),
+  });
+
+  console.log(`created: ${mod.slug} (#${mod.id})${isLibrary ? ' [library]' : ''}`);
+  console.log('next: v8scli upload');
+}
+
+/** v8scli edit --name … --description … --full FILE --visibility … */
+export async function edit(args) {
+  const config = await readConfig();
+  const manifest = await readManifest();
+  const mod = await resolveMod(config, manifest);
+
+  const value = (flag) => {
+    const at = args.indexOf(flag);
+    return at >= 0 ? args[at + 1] : undefined;
+  };
+
+  const body = {};
+  if (value('--name')) body.name = value('--name');
+  if (value('--description')) body.description = value('--description');
+  if (value('--visibility')) body.visibility = value('--visibility');
+  if (value('--full')) body.descriptionFull = await readFile(value('--full'), 'utf-8');
+
+  if (!Object.keys(body).length)
+    throw new Error('nothing to change: --name, --description, --full <file>, --visibility <public|whitelist|private>');
+
+  const { mod: updated } = await api(config, `/api/mods/${mod.id}/update`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  console.log(`updated: ${updated.slug} — ${Object.keys(body).join(', ')}`);
+}
+
+/** v8scli icon <file> / v8scli cover <file> */
+export async function icon(args) {
+  const config = await readConfig();
+  const mod = await resolveMod(config, await readManifest());
+  if (!args[0]) throw new Error('usage: v8scli icon <file.png>');
+  await uploadImage(config, mod.id, args[0], 'icon');
+}
+
+export async function cover(args) {
+  const config = await readConfig();
+  const mod = await resolveMod(config, await readManifest());
+  if (!args[0]) throw new Error('usage: v8scli cover <file.png>');
+  await uploadImage(config, mod.id, args[0], 'cover');
+}
+
+/** v8scli submit — последнюю загруженную версию на дев-проверку */
+export async function submit() {
+  const config = await readConfig();
+  const mod = await resolveMod(config, await readManifest());
+  const version = await latestVersion(config, mod.id);
+
+  // У разработчиков команды загрузка сразу даёт dev_ready — отправлять нечего,
+  // и это нормальный исход, а не ошибка: сценарий «залил и тестирую» не ломается
+  if (version.status === 'dev_ready') {
+    console.log(`${version.version}: already dev_ready — ready to test in your lobby`);
+    return;
+  }
+
+  if (version.status !== 'draft')
+    throw new Error(`version ${version.version} is ${version.status}, nothing to submit`);
+
+  const { version: moved } = await api(config, `/api/mods/${mod.id}/versions/${version.id}/action`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'submit_dev' }),
+  });
+
+  // У разработчиков команды дев-ревью пропускается, и версия сразу dev_ready
+  console.log(`${moved.version}: ${moved.status}`);
+  console.log(moved.status === 'dev_ready'
+    ? 'ready to test in your lobby'
+    : 'sent to review');
+}
+
+/** v8scli release "заметки к релизу" — публикация версии в прод */
+export async function release(args) {
+  const config = await readConfig();
+  const mod = await resolveMod(config, await readManifest());
+  const version = await latestVersion(config, mod.id);
+
+  const notes = args.join(' ').trim();
+  if (notes.length < 10)
+    throw new Error('release notes are required (10 characters or more): v8scli release "what changed"');
+
+  if (version.status === 'draft')
+    throw new Error(`version ${version.version} is still a draft — run \`v8scli submit\` first`);
+
+  const { version: moved } = await api(config, `/api/mods/${mod.id}/versions/${version.id}/action`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'submit_release', changelog: notes }),
+  });
+
+  console.log(`${moved.version}: ${moved.status} — waiting for an admin to publish it`);
+}
+
+/** v8scli whoami — чей это токен и можно ли им работать */
+export async function whoami() {
+  const config = await readConfig();
+  const { developer } = await api(config, '/api/developers/me');
+
+  if (!developer) throw new Error('token is valid but the account is not a developer yet');
+
+  console.log(`${developer.nickname} (${developer.accountId}) — ${developer.status}`);
+  console.log(`portal: ${config.portalUrl.replace(/\/\/[^@]*@/, '//')}`);
+}

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,11 +42,15 @@ 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);
   if (!mod)
-    throw new Error(`mod "${manifest.slug}" not found on the portal — create it in the web UI first`);
+    throw new Error(`mod "${manifest.slug}" not found on the portal — run \`v8scli create\` first`);
 
   for (let attempt = 0; attempt < 2; attempt++) {
     const archive = await packSources(manifest);
@@ -59,7 +64,7 @@ export async function upload() {
         body: form,
       });
       console.log(`uploaded: ${manifest.slug}@${version.version} status=${version.status}`);
-      console.log('next: submit it for review from the web UI or wait for CLI action support');
+      console.log('next: v8scli submit');
       return;
     } catch (error) {
       const match = String(error?.message ?? '').match(/version_not_incremented: last is (\d+\.\d+\.\d+)/);

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"
   }
 }