@briine/create-bot 0.0.1

package/README.md

@@ -0,0 +1,31 @@
+# @briine/create-bot
+
+Scaffold a new Briine bot project.
+
+## Usage
+
+```bash
+npm create @briine/bot@latest my-bot
+```
+
+If you want to skip dependency installation during creation:
+
+```bash
+npm create @briine/bot@latest my-bot -- --no-install
+```
+
+## What it generates
+
+- A minimal TypeScript Briine bot powered by `@briine/sdk`
+- A starter `.env.example` with the values you will copy from Briine
+- A `README.md` with the two next steps: configure credentials and run the bot
+
+## After scaffolding
+
+1. Log in to Briine and create your first agent.
+2. Copy `.env.example` to `.env` and paste in your Briine values.
+3. Run `npm run dev`.
+
+## Requirements
+
+- Node.js 20 or newer

package/bin/create-bot.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+import { copyFile, cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const templateDir = path.resolve(__dirname, '../template');
+
+function printUsage() {
+    console.log('Usage: npm create @briine/bot@latest [project-name]');
+}
+
+function parseArgs(argv) {
+    const flags = new Set(argv.filter(arg => arg.startsWith('-')));
+    const positionals = argv.filter(arg => !arg.startsWith('-'));
+    return {
+        noInstall: flags.has('--no-install'),
+        help: flags.has('--help') || flags.has('-h'),
+        projectName: positionals[0],
+    };
+}
+
+function toClassName(value) {
+    return value
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('') || 'MyBot';
+}
+
+function toAgentEnvPrefix(value) {
+    return value
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toUpperCase() || 'MY_BOT';
+}
+
+function validateProjectName(value) {
+    return /^[a-z0-9][a-z0-9-_]*$/i.test(value);
+}
+
+async function promptForProjectName() {
+    const rl = readline.createInterface({ input, output });
+
+    try {
+        while (true) {
+            const answer = (await rl.question('Project name: ')).trim();
+
+            if (!answer) {
+                continue;
+            }
+
+            if (!validateProjectName(answer)) {
+                console.error('Project name must start with a letter or number and may only include letters, numbers, dashes, or underscores.');
+                continue;
+            }
+
+            return answer;
+        }
+    } finally {
+        rl.close();
+    }
+}
+
+async function targetExists(targetDir) {
+    try {
+        await readdir(targetDir);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function writePackageJson(targetDir, projectName) {
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    const raw = await readFile(packageJsonPath, 'utf8');
+    const packageJson = JSON.parse(raw);
+    packageJson.name = projectName;
+    await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+
+async function writeSourceTemplate(targetDir, className, envPrefix) {
+    const sourcePath = path.join(targetDir, 'src/index.ts');
+    const raw = await readFile(sourcePath, 'utf8');
+    const updated = raw
+        .replaceAll('__BOT_CLASS_NAME__', className)
+        .replaceAll('__BOT_ENV_PREFIX__', envPrefix);
+    await writeFile(sourcePath, updated);
+}
+
+async function writeReadme(targetDir, projectName, envPrefix) {
+    const readmePath = path.join(targetDir, 'README.md');
+    const raw = await readFile(readmePath, 'utf8');
+    const updated = raw
+        .replaceAll('__PROJECT_NAME__', projectName)
+        .replaceAll('__BOT_ENV_PREFIX__', envPrefix);
+    await writeFile(readmePath, updated);
+}
+
+async function writeEnvExample(targetDir, envPrefix) {
+    const envExamplePath = path.join(targetDir, '.env.example');
+    const raw = await readFile(envExamplePath, 'utf8');
+    const updated = raw.replaceAll('__BOT_ENV_PREFIX__', envPrefix);
+    await writeFile(envExamplePath, updated);
+}
+
+async function installDependencies(targetDir) {
+    await new Promise((resolve, reject) => {
+        const child = spawn('npm', ['install'], {
+            cwd: targetDir,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+
+        child.on('exit', code => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+
+            reject(new Error(`npm install exited with code ${code ?? 'unknown'}`));
+        });
+
+        child.on('error', reject);
+    });
+}
+
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+
+    if (args.help) {
+        printUsage();
+        return;
+    }
+
+    const projectName = args.projectName?.trim() ? args.projectName.trim() : await promptForProjectName();
+
+    if (!validateProjectName(projectName)) {
+        console.error('Invalid project name. Use letters, numbers, dashes, or underscores.');
+        process.exitCode = 1;
+        return;
+    }
+
+    const targetDir = path.resolve(process.cwd(), projectName);
+    const className = toClassName(projectName);
+    const envPrefix = toAgentEnvPrefix(projectName);
+
+    if (await targetExists(targetDir)) {
+        console.error(`Target directory already exists: ${targetDir}`);
+        process.exitCode = 1;
+        return;
+    }
+
+    await mkdir(targetDir, { recursive: true });
+    await cp(templateDir, targetDir, { recursive: true });
+    await copyFile(path.join(templateDir, '.gitignore'), path.join(targetDir, '.gitignore'));
+    await copyFile(path.join(templateDir, '.env.example'), path.join(targetDir, '.env.example'));
+
+    await writePackageJson(targetDir, projectName);
+    await writeSourceTemplate(targetDir, className, envPrefix);
+    await writeReadme(targetDir, projectName, envPrefix);
+    await writeEnvExample(targetDir, envPrefix);
+
+    if (!args.noInstall) {
+        try {
+            await installDependencies(targetDir);
+        } catch (error) {
+            console.warn('Project created, but dependency installation failed.');
+            console.warn(error instanceof Error ? error.message : String(error));
+        }
+    }
+
+    console.log('');
+    console.log(`Created ${projectName} at ${targetDir}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log(`  cd ${projectName}`);
+    console.log('  cp .env.example .env');
+    if (args.noInstall) {
+        console.log('  npm install');
+    }
+    console.log('  npm run dev');
+    console.log('');
+    console.log('Create your first Briine agent on briine.com and paste those values into .env before connecting.');
+}
+
+main().catch(error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/bin/create-bot.test.js

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const cliPath = path.resolve(process.cwd(), 'bin/create-bot.js');
+
+test('scaffolds a bot project', async () => {
+    const parentDir = await mkdtemp(path.join(os.tmpdir(), 'briine-create-bot-'));
+
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [cliPath, 'my-first-bot', '--no-install'], {
+                cwd: parentDir,
+                env: { ...process.env, npm_config_user_agent: 'test', PATH: process.env.PATH },
+                stdio: 'ignore',
+            });
+
+            child.on('exit', code => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+
+                reject(new Error(`CLI exited with code ${code ?? 'unknown'}`));
+            });
+
+            child.on('error', reject);
+        });
+
+        const generatedPackage = JSON.parse(await readFile(path.join(parentDir, 'my-first-bot/package.json'), 'utf8'));
+        const generatedSource = await readFile(path.join(parentDir, 'my-first-bot/src/index.ts'), 'utf8');
+        const generatedReadme = await readFile(path.join(parentDir, 'my-first-bot/README.md'), 'utf8');
+        const generatedEnv = await readFile(path.join(parentDir, 'my-first-bot/.env.example'), 'utf8');
+
+        assert.equal(generatedPackage.name, 'my-first-bot');
+        assert.match(generatedSource, /class MyFirstBot extends BriineAgent/);
+        assert.match(generatedSource, /process\.env\.MY_FIRST_BOT_NAME!/);
+        assert.match(generatedReadme, /MY_FIRST_BOT_SECRET/);
+        assert.match(generatedEnv, /MY_FIRST_BOT_VERSION=0\.0\.1/);
+    } finally {
+        await rm(parentDir, { recursive: true, force: true });
+    }
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@briine/create-bot",
+  "version": "0.0.1",
+  "description": "Scaffold a new Briine bot project.",
+  "license": "MIT",
+  "author": "@briine",
+  "repository": "github:briinedev/create-bot",
+  "type": "module",
+  "bin": {
+    "create-briine-bot": "./bin/create-bot.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "briine",
+    "bot",
+    "create",
+    "scaffold",
+    "typescript"
+  ]
+}

package/template/.env.example

@@ -0,0 +1,5 @@
+API_HOST=arena.briine.workers.dev
+USERNAME=your-briine-username
+__BOT_ENV_PREFIX___NAME=your-agent-name
+__BOT_ENV_PREFIX___VERSION=0.0.1
+__BOT_ENV_PREFIX___SECRET=replace-with-agent-secret

package/template/README.md

@@ -0,0 +1,32 @@
+# __PROJECT_NAME__
+
+This project was generated with `npm create @briine/bot`.
+
+## 1. Get your Briine credentials
+
+Log in to Briine, create your first agent, and copy these values into `.env`:
+
+- `USERNAME`
+- `__BOT_ENV_PREFIX___NAME`
+- `__BOT_ENV_PREFIX___VERSION`
+- `__BOT_ENV_PREFIX___SECRET`
+
+If you're running against a different Briine environment, update `API_HOST` as well.
+
+## 2. Start the bot
+
+```bash
+cp .env.example .env
+npm run dev
+```
+
+## Project structure
+
+- `src/index.ts` contains your bot logic and the `Agent.register(...)` call.
+- `.env` stores the credentials used to authenticate and queue.
+
+## Next changes to make
+
+- Replace the starter drafting strategy with your own character priorities.
+- Replace the starter action logic with a real combat policy.
+- Add logging around decisions once you start testing matches.

package/template/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@briine/sdk": "^0.1.0",
+    "dotenv": "^17.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  }
+}

package/template/src/index.ts

@@ -0,0 +1,43 @@
+import 'dotenv/config';
+import BriineAgent, { Action, Character, MatchStatus, Spell } from '@briine/sdk';
+
+class __BOT_CLASS_NAME__ extends BriineAgent {
+    chooseCharacter(available: Character[], _ally: Character[], _enemy: Character[]): Character {
+        return available[0];
+    }
+
+    chooseSpells(available: Spell[], _ally: Character[], _enemy: Character[]): Spell[] {
+        return available;
+    }
+
+    chooseAction(status: MatchStatus): Action {
+        const source = status.sources[0];
+        const target = status.targets[0];
+        const spell = source?.spells.find(candidate => candidate.available);
+
+        if (source && spell && target) {
+            return { source, target, action: spell };
+        }
+
+        if (source && target && source.attacks[0]) {
+            return { source, target, action: source.attacks[0] };
+        }
+
+        return {
+            source,
+            target: source,
+            action: 'defend',
+        };
+    }
+}
+
+BriineAgent.register(
+    new __BOT_CLASS_NAME__(
+        process.env.USERNAME!,
+        process.env.__BOT_ENV_PREFIX___NAME!,
+        process.env.__BOT_ENV_PREFIX___VERSION!,
+        process.env.__BOT_ENV_PREFIX___SECRET!,
+        true,
+    ),
+    process.env.API_HOST!,
+);

package/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}