v8scli 0.2.0

package/README.md

@@ -0,0 +1,39 @@
+# v8scli
+
+CLI (`v8s`) for building and publishing V8 `point_script` mods.
+Companion of the `v8_scripting` SDK.
+
+The first call runs through the package name — `npx v8s` would look for a
+package called `v8s`, which does not exist. Inside the scaffolded project the
+CLI is a devDependency, so plain `npx v8s` works from there on:
+
+```bash
+npx v8scli init my_mod             # scaffold (inside a project plain `npx v8s` works)
+cd my_mod && npm i
+npx v8s build         # bundle + dist/my_mod.vjs_c для теста на своём сервере
+npx v8s login         # portal url + api token (dpt_...)
+npx v8s upload        # pack sources, create a version on the portal
+npx v8s status        # versions + review status
+npx v8s deps          # download typings of library dependencies
+```
+
+Rules enforced at build time (same as on the portal):
+only your files and the `v8_scripting` SDK can be imported;
+`cs_script/point_script` is provided by the runtime.
+
+Before the npm release the packages are installed from checkouts —
+`init --local` writes the SDK and the CLI into the project as `file:` deps,
+so `npm install` never touches the registry:
+
+```bash
+cd dev_portal/cli && npm install
+cd ~/mods && node /path/to/dev_portal/cli/bin/v8s.js init my_mod --local
+cd my_mod && npm install && npx v8s build
+```
+
+The SDK is looked up next to the CLI checkout (`dev_portal/sdk`);
+override with `V8S_LOCAL_SDK=/path/to/sdk`.
+
+Dev portals behind basic auth: pass credentials inside the url on login,
+e.g. `https://user:pass@developer.example.com` — the API token then goes
+in the `X-Api-Token` header automatically.

package/bin/v8s.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// v8s — CLI разработчика модов. Команды: init, build, login, upload, status, deps.
+import { init } from '../src/commands/init.js';
+import { build } from '../src/commands/build.js';
+import { login } from '../src/commands/login.js';
+import { upload } from '../src/commands/upload.js';
+import { status } from '../src/commands/status.js';
+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';
+
+const [, , command, ...args] = process.argv;
+
+const commands = { init, build, login, upload, status, deps, pull, search, add, remove, update };
+
+const usage = `v8s <command>
+
+  init <slug> [--local]  scaffold a new mod in ./<slug> (--local: SDK/CLI from checkouts)
+  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
+  status        show versions and review status of the current mod
+  deps          download typings of library dependencies (./.v8s_types)
+  pull <slug>   fetch the latest uploaded sources of your mod from the portal
+  search [q]    browse published libraries on the portal
+  add <slug>[@ver]  pin a library release as a dependency (+ typings)
+  remove <slug> drop a library from dependencies (+ its typings)
+  update [slug] bump pinned library releases to the latest published
+`;
+
+if (!command || !commands[command]) {
+  console.log(usage);
+  process.exit(command ? 1 : 0);
+}
+
+try {
+  await commands[command](args);
+} catch (error) {
+  console.error(`error: ${error?.message ?? error}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "v8scli",
+  "version": "0.2.0",
+  "description": "CLI for building and publishing V8 point_script mods (companion of v8_scripting)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "v8s": "bin/v8s.js",
+    "v8scli": "bin/v8s.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.9",
+    "tar": "^7.4.3"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,114 @@
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { api, readConfig, readManifest } from '../common.js';
+import { deps } from './deps.js';
+
+/**
+ * v8s add <slug>[@version] — подключить библиотеку точным пином релиза.
+ * Без версии берётся последний published; typings скачиваются сразу.
+ *
+ * v8s update [slug] — поднять пин(ы) до последнего published-релиза.
+ */
+
+async function resolveLibrary(config, slug) {
+  const { libraries } = await api(
+    config, `/api/registry/libraries?query=${encodeURIComponent(slug)}`);
+  const library = libraries.find((lib) => lib.slug === slug);
+  if (!library) throw new Error(`library "${slug}" not found on the portal`);
+  return library;
+}
+
+async function writeDependency(slug, version) {
+  const raw = JSON.parse(await readFile('mod.json', 'utf-8'));
+  const dependencies = raw.dependencies || [];
+
+  const next = `${slug}@${version}`;
+  const index = dependencies.findIndex((dep) => dep.split('@')[0] === slug);
+  const previous = index >= 0 ? dependencies[index] : null;
+
+  if (index >= 0) dependencies[index] = next;
+  else dependencies.push(next);
+
+  raw.dependencies = dependencies;
+  await writeFile('mod.json', `${JSON.stringify(raw, null, 2)}\n`);
+
+  return previous;
+}
+
+export async function add(args) {
+  const spec = args[0];
+  if (!spec) throw new Error('usage: v8s add <slug>[@version]');
+
+  const [slug, requested] = spec.split('@');
+  if (!/^[a-z][a-z0-9_]{2,31}$/.test(slug)) throw new Error(`invalid slug "${slug}"`);
+
+  const config = await readConfig();
+  const manifest = await readManifest();
+  if (manifest.slug === slug) throw new Error('a mod cannot depend on itself');
+
+  const library = await resolveLibrary(config, slug);
+
+  const version = requested || library.latest;
+  if (!library.versions.includes(version))
+    throw new Error(
+      `library "${slug}" has no release ${version} (available: ${library.versions.join(', ')})`);
+
+  const previous = await writeDependency(slug, version);
+  console.log(previous
+    ? `updated: ${previous} -> ${slug}@${version}`
+    : `added: ${slug}@${version}`);
+
+  await deps();
+}
+
+export async function remove(args) {
+  const slug = args[0];
+  if (!slug) throw new Error('usage: v8s remove <slug>');
+
+  const raw = JSON.parse(await readFile('mod.json', 'utf-8'));
+  const dependencies = raw.dependencies || [];
+  const index = dependencies.findIndex((dep) => dep.split('@')[0] === slug);
+  if (index < 0) throw new Error(`"${slug}" is not in mod.json dependencies`);
+
+  const removed = dependencies.splice(index, 1)[0];
+  raw.dependencies = dependencies;
+  await writeFile('mod.json', `${JSON.stringify(raw, null, 2)}\n`);
+
+  // тайпинги больше не нужны
+  await rm(join('.v8s_types', `${slug}.d.ts`), { force: true });
+
+  console.log(`removed: ${removed}`);
+}
+
+export async function update(args) {
+  const only = args[0] || null;
+
+  const config = await readConfig();
+  const manifest = await readManifest();
+  const dependencies = manifest.dependencies || [];
+
+  if (!dependencies.length) {
+    console.log('no dependencies in mod.json');
+    return;
+  }
+
+  let changed = 0;
+
+  for (const dep of dependencies) {
+    const slug = dep.split('@')[0];
+    if (only && slug !== only) continue;
+
+    const library = await resolveLibrary(config, slug);
+    const previous = await writeDependency(slug, library.latest);
+
+    if (previous !== `${slug}@${library.latest}`) {
+      console.log(`updated: ${previous} -> ${slug}@${library.latest}`);
+      changed += 1;
+    } else {
+      console.log(`up to date: ${slug}@${library.latest}`);
+    }
+  }
+
+  if (changed) await deps();
+}

package/src/commands/build.js

@@ -0,0 +1,53 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readManifest } from '../common.js';
+
+// Локальная самопроверка: тот же контракт, что на портале —
+// только файлы мода + SDK, cs_script/point_script остаётся external.
+export async function build() {
+  const esbuild = await import('esbuild');
+  const manifest = await readManifest();
+  const disallowed = new Set();
+
+  const result = await esbuild.build({
+    entryPoints: [manifest.entry],
+    bundle: true,
+    write: false,
+    format: 'esm',
+    target: 'es2020',
+    platform: 'neutral',
+    logLevel: 'warning',
+    plugins: [{
+      name: 'import-guard',
+      setup(build) {
+        build.onResolve({ filter: /.*/ }, (args) => {
+          if (args.path === 'cs_script/point_script') return { path: args.path, external: true };
+          if (args.path.startsWith('.') || args.path.startsWith('/')) return null;
+          if (args.path === 'v8_scripting' || args.path.startsWith('v8_scripting/')) return null; // SDK из node_modules
+          disallowed.add(args.path);
+          return { path: args.path, external: true };
+        });
+      },
+    }],
+  });
+
+  if (disallowed.size)
+    throw new Error(`disallowed imports: ${[...disallowed].join(', ')} — only mod files and the v8_scripting SDK are allowed`);
+
+  await mkdir('dist', { recursive: true });
+
+  const bundle = Buffer.from(result.outputFiles[0].contents);
+  const jsOut = join('dist', `${manifest.slug}.js`);
+  await writeFile(jsOut, bundle);
+
+  // .vjs_c рядом с бандлом: его можно сразу положить на свой сервер в
+  // addons/scripts_dev и проверить мод, не дожидаясь сборки на портале
+  const { buildVjsC } = await import('../vjs.js');
+  const resource = buildVjsC(bundle);
+  const resourceOut = join('dist', `${manifest.slug}.vjs_c`);
+  await writeFile(resourceOut, resource);
+
+  console.log(`ok: ${jsOut} (${bundle.length} bytes)`);
+  console.log(`ok: ${resourceOut} (${resource.length} bytes) — для локального теста: положить в game/csgo/addons/scripts_dev/`);
+  console.log('релизный артефакт портал собирает сам из исходников');
+}

package/src/commands/deps.js

@@ -0,0 +1,26 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api, readConfig, readManifest } from '../common.js';
+
+// Скачивает typings модов-библиотек из dependencies в ./.v8s_types/<slug>.d.ts.
+// Рантайм-объект библиотеки берётся через Instance.GetInterface("<slug>") —
+// typings дают только типы для import type.
+export async function deps() {
+  const config = await readConfig();
+  const manifest = await readManifest();
+  const dependencies = manifest.dependencies ?? [];
+  if (!dependencies.length) {
+    console.log('no dependencies in mod.json');
+    return;
+  }
+
+  await mkdir('.v8s_types', { recursive: true });
+  for (const dep of dependencies) {
+    const [slug] = dep.split('@');
+    const text = await api(config, `/api/registry/typings/${slug}/latest`);
+    const content = typeof text === 'string' ? text : text.raw;
+    await writeFile(join('.v8s_types', `${slug}.d.ts`), content);
+    console.log(`.v8s_types/${slug}.d.ts`);
+  }
+  console.log('add ".v8s_types" to tsconfig "include" (template already has it)');
+}

package/src/commands/init.js

@@ -0,0 +1,61 @@
+import { cp, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const TEMPLATES = join(CLI_ROOT, 'templates');
+
+/**
+ * Пути до локальных чекаутов SDK и CLI для режима --local (пакеты ещё не в npm).
+ * SDK ищем в V8S_LOCAL_SDK, иначе рядом с CLI (dev_portal/sdk).
+ */
+async function resolveLocalPackages() {
+  const sdk = process.env.V8S_LOCAL_SDK ?? join(CLI_ROOT, '..', 'sdk');
+  if (!existsSync(join(sdk, 'package.json')))
+    throw new Error(
+      `--local: SDK not found at ${sdk} — pass the checkout path via V8S_LOCAL_SDK=/path/to/dev_portal/sdk`,
+    );
+  return { sdk: await realpath(sdk), cli: await realpath(CLI_ROOT) };
+}
+
+export async function init(args) {
+  const isLocal = args.includes('--local');
+  const slug = args.find((arg) => !arg.startsWith('-'));
+  if (!slug || !/^[a-z][a-z0-9_]{2,31}$/.test(slug))
+    throw new Error('usage: v8s init <slug> [--local]  (slug: [a-z][a-z0-9_]{2,31})');
+
+  const local = isLocal ? await resolveLocalPackages() : null;
+
+  const dir = join(process.cwd(), slug);
+  if (existsSync(dir)) throw new Error(`directory ${slug} already exists`);
+
+  await mkdir(dir, { recursive: true });
+  await cp(TEMPLATES, dir, { recursive: true });
+
+  // подстановка slug в шаблоны
+  for (const file of ['mod.json', 'package.json']) {
+    const path = join(dir, file);
+    await writeFile(path, (await readFile(path, 'utf-8')).replaceAll('__SLUG__', slug));
+  }
+
+  // локальный режим: SDK и CLI ставятся из чекаутов (file:), реестр не нужен
+  if (local) {
+    const path = join(dir, 'package.json');
+    const manifest = JSON.parse(await readFile(path, 'utf-8'));
+    manifest.devDependencies = {
+      ...manifest.devDependencies,
+      v8_scripting: `file:${local.sdk}`,
+      v8scli: `file:${local.cli}`,
+    };
+    await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+
+  console.log(`created ./${slug}${local ? ' (local SDK/CLI from checkouts)' : ''}
+next steps:
+  cd ${slug}
+  npm install
+  npx v8s build      # self-check bundle
+  npx v8s login      # portal url + api token
+  npx v8s upload     # create a version on the portal`);
+}

package/src/commands/login.js

@@ -0,0 +1,28 @@
+import { createInterface } from 'node:readline/promises';
+import { api, readConfig, writeConfig, CONFIG_PATH } from '../common.js';
+
+// v8s login [portalUrl] [token] — с аргументами работает без интерактива (CI-friendly).
+export async function login(args = []) {
+  const config = await readConfig();
+  let [portalUrl, token] = args;
+
+  if (!portalUrl || !token) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      portalUrl =
+        portalUrl ||
+        (await rl.question(`portal url [${config.portalUrl ?? 'https://developer.xplay.gg'}]: `)).trim() ||
+        config.portalUrl || 'https://developer.xplay.gg';
+      token = token || (await rl.question('api token (portal -> API Tokens): ')).trim();
+    } finally {
+      rl.close();
+    }
+  }
+
+  if (!token?.startsWith('dpt_')) throw new Error('token must start with dpt_');
+
+  const next = { portalUrl, token };
+  await api(next, '/api/registry/health'); // живость портала (и basic auth из url)
+  await writeConfig(next);
+  console.log(`saved to ${CONFIG_PATH}`);
+}

package/src/commands/pull.js

@@ -0,0 +1,67 @@
+import { mkdir, readFile, writeFile, cp } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { api, apiBinary, readConfig } from '../common.js';
+
+const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'templates');
+
+/**
+ * v8s pull <slug> — скачивает исходники последней версии мода с портала.
+ *
+ * В папке существующего мода (mod.json с тем же slug) обновляет исходники
+ * на месте; иначе создаёт ./<slug> с полной обвязкой проекта (package.json,
+ * tsconfig из шаблона) — «git clone» для мода одной командой.
+ */
+export async function pull(args) {
+  const slug = args[0];
+  if (!slug || !/^[a-z][a-z0-9_]{2,31}$/.test(slug))
+    throw new Error('usage: v8s pull <slug>');
+
+  const config = await readConfig();
+
+  const { mods } = await api(config, '/api/mods/my');
+  const mod = mods.find((m) => m.slug === slug);
+  if (!mod) throw new Error(`mod "${slug}" not found among your mods on the portal`);
+
+  const { versions } = await api(config, `/api/mods/${mod.id}`);
+  if (!versions.length) throw new Error(`mod "${slug}" has no uploaded versions yet`);
+  const latest = versions[0];
+
+  const archive = await apiBinary(
+    config, `/api/mods/${mod.id}/versions/${latest.id}/sources`);
+
+  // куда разворачивать: текущая папка, если это уже этот мод, иначе ./<slug>
+  let target = process.cwd();
+  let created = false;
+
+  const localManifest = join(target, 'mod.json');
+  const isSameMod = existsSync(localManifest)
+    && JSON.parse(await readFile(localManifest, 'utf-8')).slug === slug;
+
+  if (!isSameMod) {
+    target = join(process.cwd(), slug);
+    if (existsSync(target)) throw new Error(`directory ${slug} already exists`);
+    await mkdir(target, { recursive: true });
+    await cp(TEMPLATES, target, { recursive: true });
+
+    const pkgPath = join(target, 'package.json');
+    await writeFile(pkgPath,
+      (await readFile(pkgPath, 'utf-8')).replaceAll('__SLUG__', slug));
+    created = true;
+  }
+
+  const tar = await import('tar');
+  await new Promise((resolve, reject) => {
+    const stream = tar.extract({ cwd: target, gzip: true });
+    stream.on('error', reject);
+    stream.on('finish', resolve);
+    stream.end(archive);
+  });
+
+  console.log(`pulled ${slug}@${latest.version} -> ${created ? `./${slug}` : '.'}`);
+  if (created) console.log(`next: cd ${slug} && npm install`);
+  if ((JSON.parse(await readFile(join(target, 'mod.json'), 'utf-8')).dependencies || []).length)
+    console.log('dependencies present — run `npx v8s deps` to fetch typings');
+}

package/src/commands/search.js

@@ -0,0 +1,20 @@
+import { api, readConfig } from '../common.js';
+
+/** v8s search [query] — публичный каталог библиотек портала */
+export async function search(args) {
+  const config = await readConfig();
+  const query = encodeURIComponent(args.join(' ').trim());
+
+  const { libraries } = await api(config, `/api/registry/libraries?query=${query}`);
+
+  if (!libraries.length) {
+    console.log('no libraries found');
+    return;
+  }
+
+  for (const lib of libraries) {
+    console.log(`${lib.slug}@${lib.latest}  ${lib.name} — ${lib.description || 'no description'}`);
+    console.log(`  by ${lib.ownerNickname || 'unknown'} | versions: ${lib.versions.join(', ')}`);
+    console.log(`  add: npx v8s add ${lib.slug}`);
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,17 @@
+import { api, readConfig, readManifest } from '../common.js';
+
+export async function status() {
+  const config = await readConfig();
+  const manifest = await readManifest();
+
+  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`);
+
+  const { versions } = await api(config, `/api/mods/${mod.id}`);
+  console.log(`${mod.slug} (#${mod.id}) — ${mod.status}${mod.isLibrary ? ', library' : ''}`);
+  for (const v of versions) {
+    const comment = v.reviewComment ? `  # ${v.reviewComment}` : '';
+    console.log(`  ${v.version.padEnd(10)} ${v.status}${comment}`);
+  }
+}

package/src/commands/upload.js

@@ -0,0 +1,70 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { api, readConfig, readManifest } from '../common.js';
+
+// Пакует исходники (mod.json + src/ + typings) и создаёт версию на портале.
+// Финальный артефакт собирает сам портал — загружаются только исходники.
+async function packSources(manifest) {
+  const tar = await import('tar');
+
+  const files = ['mod.json', 'src'];
+  if (manifest.typings) files.push(manifest.typings);
+
+  const chunks = [];
+  await new Promise((resolve, reject) => {
+    tar.create({ gzip: true, cwd: process.cwd(), portable: true }, files)
+      .on('data', (chunk) => chunks.push(chunk))
+      .on('end', resolve)
+      .on('error', reject);
+  });
+
+  const archive = Buffer.concat(chunks);
+  console.log(`packed ${files.join(', ')} -> ${archive.length} bytes`);
+
+  return archive;
+}
+
+// Портал требует версию строго выше последней загруженной. Если локальная не выше
+// (забыли поднять после прошлой загрузки) — поднимаем patch сами и пишем в mod.json.
+async function bumpVersion(manifest, lastVersion) {
+  const [major, minor, patch] = lastVersion.split('.').map((part) => parseInt(part, 10));
+  const next = `${major}.${minor}.${patch + 1}`;
+
+  const raw = JSON.parse(await readFile('mod.json', 'utf-8'));
+  raw.version = next;
+  await writeFile('mod.json', `${JSON.stringify(raw, null, 2)}\n`);
+  manifest.version = next;
+
+  console.log(`version ${lastVersion} is already on the portal — bumped mod.json to ${next}`);
+}
+
+export async function upload() {
+  const config = await readConfig();
+  const manifest = await readManifest();
+
+  // 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`);
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const archive = await packSources(manifest);
+
+    const form = new FormData();
+    form.append('file', new Blob([archive], { type: 'application/gzip' }), `${manifest.slug}.tar.gz`);
+
+    try {
+      const { version } = await api(config, `/api/mods/${mod.id}/versions/upload`, {
+        method: 'POST',
+        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');
+      return;
+    } catch (error) {
+      const match = String(error?.message ?? '').match(/version_not_incremented: last is (\d+\.\d+\.\d+)/);
+      if (!match || attempt > 0) throw error;
+      await bumpVersion(manifest, match[1]);
+    }
+  }
+}

package/src/common.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const CONFIG_DIR = join(homedir(), '.config', 'v8s');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+export async function readConfig() {
+  try {
+    return JSON.parse(await readFile(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export async function readManifest(dir = process.cwd()) {
+  let raw;
+  try {
+    raw = await readFile(join(dir, 'mod.json'), 'utf-8');
+  } catch {
+    throw new Error('mod.json not found — run from the mod root (or v8s init first)');
+  }
+  const manifest = JSON.parse(raw);
+  if (!manifest.slug || !manifest.entry) throw new Error('mod.json must contain slug and entry');
+  return manifest;
+}
+
+/**
+ * Авторизованный запрос к порталу.
+ * API-токен уходит в X-Api-Token: заголовок Authorization может быть занят
+ * basic auth стенда (дев за traefik) — его CLI берёт из user:pass в portalUrl.
+ */
+/** Как api(), но возвращает Buffer — для скачивания архивов исходников */
+export async function apiBinary(config, path) {
+  if (!config.portalUrl) throw new Error('not logged in — run `v8s login` first');
+  const url = new URL(config.portalUrl);
+  const headers = {};
+  if (config.token) headers['X-Api-Token'] = config.token;
+  if (url.username) {
+    headers.Authorization =
+      'Basic ' + Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString('base64');
+    url.username = '';
+    url.password = '';
+  }
+  const res = await fetch(new URL(path, url), { headers });
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+export async function api(config, path, options = {}) {
+  if (!config.portalUrl) throw new Error('not logged in — run `v8s login` first');
+  const url = new URL(config.portalUrl);
+  const headers = { ...(options.headers ?? {}) };
+  if (config.token) headers['X-Api-Token'] = config.token;
+  if (url.username) {
+    headers.Authorization =
+      'Basic ' + Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString('base64');
+    url.username = '';
+    url.password = '';
+  }
+  const target = new URL(path, url);
+  const res = await fetch(target, { ...options, headers });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { raw: text };
+  }
+  if (!res.ok) throw new Error(body?.message ?? `${res.status} ${res.statusText}`);
+  return body;
+}

package/src/vjs.js

@@ -0,0 +1,80 @@
+// Упаковка JS в ресурс .vjs_c — копия портального src/versions/vjs.ts (единственное
+// место знания о формате). Нужна для локальных тестов на своём сервере: релизный
+// артефакт всё равно собирает портал из исходников.
+const RED2_HEX ='0533564b7c161274e9069846aff2e63eb59037e7010000000000004071020000' +
+  '010000000000000027000000070007008f0300008e0200000000000000000000' +
+  '000000000000000078020000cd01000017010000c10000000300000000000000' +
+  '330000000000000024000000070000000700000009000000f02a6d5f496e7075' +
+  '74446570656e64656e63696573006d5f52656c617469766546696c656e616d65' +
+  '00736372697074732f6b616b6173686b612e6a2700f01a536561726368506174' +
+  '68006373676f5f6164646f6e732f62686f705f656d657661656c7833006d5f6e' +
+  '4800f000435243006d5f624f7074696f6e616c0c00001700604578697374730e' +
+  '0051497347616d73000e6f001176700042416464693e000fb500017c41726775' +
+  '6d656e1700a0506172616d657465724ec900b25f5f5f4f766572726964654400' +
+  '686174615f5f5f2800f203547970650042696e617279426c6f62417267c3009b' +
+  '6e6765727072696e740f007044656661756c7410016b70656369616c8100c153' +
+  '7472696e67004a61766153d800f40520436f6d70696c65722056657273696f6e' +
+  '006d5f1300b34964656e7469666965720013000638000078004055736572b400' +
+  'f0070050616e6f72616d612050726570726f636573736f720d006673656e6365' +
+  '2f5a0006350101d601206564620110737300f00068696c645265736f75726365' +
+  '4c69736000b55765616b5265666572656e140002e6014561626c657d00294973' +
+  '3d0000250075756261737365743d001673150000220121696e85009073000000' +
+  '0020000000530a00000006040017040400930100000002010200000c00000a00' +
+  '13031c0080050000004b0120b6340053070000000824001b092400082000220a' +
+  '000100f31e0b0000000c0000000d0000000e0000000f00000010000000110000' +
+  '0012000000130000001400000015000000161c0000500013171c001b181c0000' +
+  '180013195c00131a0800131b0800d01c0000001d0000001e0000001fa000f000' +
+  '180906060c0e0d0e06060f0d0e0e080f00210f0f1500100f0a00b0080808090f' +
+  '010100ddeeff';
+
+const RED2_BUFFER = Buffer.from(RED2_HEX, 'hex');
+const HEADER_VERSION = 12;
+const RESOURCE_VERSION = 4;
+
+export function buildVjsC(jsBuffer) {
+  const blocks = [
+    { type: 'RED2', data: RED2_BUFFER },
+    { type: 'DATA', data: jsBuffer },
+  ];
+
+  const headerSize = 4 + 2 + 2 + 4 + 4;
+  const blockMetaSize = 12 * blocks.length;
+  const totalHeaderSize = headerSize + blockMetaSize;
+
+  const header = Buffer.alloc(totalHeaderSize);
+  header.writeUInt32LE(0, 0); // fileSize, патчится в конце
+  header.writeUInt16LE(HEADER_VERSION, 4);
+  header.writeUInt16LE(RESOURCE_VERSION, 6);
+  header.writeUInt32LE(8, 8);
+  header.writeUInt32LE(blocks.length, 12);
+
+  for (let i = 0; i < blocks.length; i++) {
+    const pos = headerSize + i * 12;
+    header.write(blocks[i].type, pos, 4, 'ascii');
+    header.writeUInt32LE(0xdeadbeef, pos + 4);
+    header.writeUInt32LE(0xdeadbeef, pos + 8);
+  }
+
+  const blocksStart = headerSize + 4;
+  let currentPos = totalHeaderSize;
+  const chunks = [];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const blockData = blocks[i].data;
+    const pad = (16 - (currentPos % 16)) % 16; // выравнивание как в Resource.Serialize
+    if (pad > 0) {
+      chunks.push(Buffer.alloc(pad, 0));
+      currentPos += pad;
+    }
+    const blockOffset = currentPos;
+    chunks.push(blockData);
+    currentPos += blockData.length;
+
+    const blockMetaOffset = blocksStart + i * 12;
+    header.writeUInt32LE(blockOffset - blockMetaOffset, blockMetaOffset);
+    header.writeUInt32LE(blockData.length, blockMetaOffset + 4);
+  }
+
+  header.writeUInt32LE(currentPos, 0);
+  return Buffer.concat([header, ...chunks], currentPos);
+}

package/templates/mod.json

@@ -0,0 +1,14 @@
+{
+  "slug": "__SLUG__",
+  "name": "__SLUG__",
+  "description": "",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "entry": "src/index.ts",
+  "environments": ["lobby"],
+  "sessionTypes": [],
+  "settings": [],
+  "dependencies": [],
+  "conflicts": [],
+  "capabilities": []
+}

package/templates/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mod-__SLUG__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "v8s build",
+    "upload": "v8s upload"
+  },
+  "devDependencies": {
+    "v8_scripting": "^0.2.1",
+    "v8scli": "^0.2.0",
+    "typescript": "^5.9.2"
+  }
+}

package/templates/src/index.ts

@@ -0,0 +1,26 @@
+import { Instance } from "cs_script/point_script";
+import { runScheduler, setInterval } from "v8_scripting/scheduler";
+
+// Конфиг мода: настройки из лобби (ключи из mod.json settings[]).
+// До запуска через платформу GetModConfig может отсутствовать — работаем на дефолтах.
+const config = Instance.GetModConfig?.();
+Instance.Msg(`mod started, environment: ${config?.environment ?? "dev"}`);
+
+// В рантайме нет своего цикла событий: таймеры и отложенные вызовы двигаются
+// отсюда. Без этой строки setInterval/setTimeout/nextFrame молча не сработают.
+Instance.OnGameFrame(() => runScheduler());
+
+// У ботов (и в момент подключения до создания контроллера) player приходит
+// undefined, хотя движковые типы обещают его всегда — проверяйте перед доступом,
+// иначе колбэк упадёт на каждом заходе бота.
+Instance.OnPlayerConnect(({ player }) => {
+  if (!player) {
+    return;
+  }
+
+  Instance.PrintToChat(player.GetPlayerSlot(), "Welcome!");
+});
+
+setInterval(() => {
+  Instance.Msg("heartbeat");
+}, 60_000);

package/templates/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": ["v8_scripting"]
+  },
+  "include": ["src", ".v8s_types"]
+}