7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
docs+scripts: add contributor bootstrap scripts for bash and PowerShell (#661)
nicyoong591c80d73b21
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 4acd0452..e2110477 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -12,6 +12,18 @@ npm test # server vitest; also runs client tests if presentnpm run build # compile server and dashboard```+For a repeatable local setup, run the bootstrap script for your shell. It only+installs dependencies when `package-lock.json` has changed and creates `.env`+when it is absent:++```powershell+.\scripts\dev-bootstrap.ps1+```++```bash+./scripts/dev-bootstrap.sh+```+Every PR should:- Include a test, and keep the existing suite green (`npm test`).diff --git a/README.md b/README.mdindex 3eb0cb58..3322d15c 100644--- a/README.md+++ b/README.md@@ -330,7 +330,7 @@ Contributors very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev lo- **Dashboard polish** — charts on the Analytics page, key rotation UX, batch import of keys from `.env`.- **Docs** — more examples, client library snippets for Go/Rust/etc., a deployment recipe for Docker or Fly.-`npm install && npm run dev` gets you the server on :3001 and the dashboard on :5173, both with HMR. PRs should include a test, keep the existing suite green (`npm test`), and match the `.editorconfig` / tsconfig defaults already in the repo. Database migration workflow and the full contributor loop are in [CONTRIBUTING.md](./CONTRIBUTING.md).+`npm install && npm run dev` gets you the server on :3001 and the dashboard on :5173, both with HMR. For a repeatable setup, use `./scripts/dev-bootstrap.sh` on Bash or `.\scripts\dev-bootstrap.ps1` on PowerShell; each preserves an existing `.env`. PRs should include a test, keep the existing suite green (`npm test`), and match the `.editorconfig` / tsconfig defaults already in the repo. Database migration workflow and the full contributor loop are in [CONTRIBUTING.md](./CONTRIBUTING.md).### Contributorsdiff --git a/package.json b/package.jsonindex c631546c..3b6ce45f 100644--- a/package.json+++ b/package.json@@ -10,7 +10,8 @@"scripts": {"dev": "concurrently --kill-others-on-fail --names server,client \"npm run dev -w server\" \"npm run dev -w client\"","dev:lan": "concurrently --kill-others-on-fail --names server,client \"npm run dev -w server\" \"npm run dev -w client -- --host\"",- "test": "npm run test -w server && npm run test -w cli && npm run test -w client --if-present",+ "test": "npm run test:bootstrap && npm run test -w server && npm run test -w cli && npm run test -w client --if-present",+ "test:bootstrap": "node --test scripts/dev-bootstrap.test.mjs","build": "npm run build -w server && npm run build -w cli && npm run build -w client","build:server": "npm run build -w server","test:migrations": "npm run test:migrations -w server",diff --git a/scripts/dev-bootstrap.ps1 b/scripts/dev-bootstrap.ps1new file mode 100644index 00000000..0dbfac43--- /dev/null+++ b/scripts/dev-bootstrap.ps1@@ -0,0 +1,89 @@+[CmdletBinding()]+param(+ [string]$ProjectRoot = (Split-Path -Parent $PSScriptRoot)+)++$ErrorActionPreference = 'Stop'++function Get-CommandVersion {+ param(+ [string]$Command,+ [string]$Argument+ )++ $version = (& $Command $Argument).Trim().TrimStart('v')+ if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($version)) {+ throw "Unable to determine $Command version."+ }++ return [Version]$version+}++function Get-LockHash {+ param([string]$Path)++ return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()+}++$ProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path+$packageJson = Join-Path $ProjectRoot 'package.json'+$lockfile = Join-Path $ProjectRoot 'package-lock.json'+$nodeModules = Join-Path $ProjectRoot 'node_modules'+$lockStamp = Join-Path $nodeModules '.freellmapi-bootstrap-lock'+$envFile = Join-Path $ProjectRoot '.env'++if (-not (Test-Path -LiteralPath $packageJson) -or -not (Test-Path -LiteralPath $lockfile)) {+ throw "Project root must contain package.json and package-lock.json: $ProjectRoot"+}++$nodeVersion = Get-CommandVersion -Command 'node' -Argument '--version'+if ($nodeVersion -lt [Version]'20.18.0' -or $nodeVersion -ge [Version]'25.0.0') {+ throw "Node.js >=20.18.0 and <25.0.0 is required; found $nodeVersion."+}++$npmVersion = Get-CommandVersion -Command 'npm' -Argument '--version'+if ($npmVersion -lt [Version]'10.0.0') {+ throw "npm >=10.0.0 is required; found $npmVersion."+}++$lockHash = Get-LockHash -Path $lockfile+$installedLockHash = if (Test-Path -LiteralPath $lockStamp) {+ (Get-Content -LiteralPath $lockStamp -Raw).Trim().ToLowerInvariant()+} else {+ ''+}++Push-Location $ProjectRoot+try {+ if (-not (Test-Path -LiteralPath $nodeModules) -or $installedLockHash -ne $lockHash) {+ Write-Host 'Installing dependencies...'+ & npm install+ if ($LASTEXITCODE -ne 0) {+ throw "npm install failed with exit code $LASTEXITCODE."+ }++ $lockHash = Get-LockHash -Path $lockfile+ Set-Content -LiteralPath $lockStamp -Value $lockHash -NoNewline -Encoding ascii+ } else {+ Write-Host 'Dependencies already match package-lock.json.'+ }++ if (-not (Test-Path -LiteralPath $envFile)) {+ $encryptionKey = (& node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))").Trim()+ if ($LASTEXITCODE -ne 0 -or $encryptionKey -notmatch '^[0-9a-f]{64}$') {+ throw 'Unable to generate ENCRYPTION_KEY.'+ }++ @(+ "ENCRYPTION_KEY=$encryptionKey"+ 'PORT=3001'+ ) | Set-Content -LiteralPath $envFile -Encoding ascii+ Write-Host 'Created .env with a new ENCRYPTION_KEY.'+ } else {+ Write-Host '.env already exists; leaving it unchanged.'+ }+} finally {+ Pop-Location+}++Write-Host 'Bootstrap complete. Start development with: npm run dev'diff --git a/scripts/dev-bootstrap.sh b/scripts/dev-bootstrap.shnew file mode 100755index 00000000..33c3e58f--- /dev/null+++ b/scripts/dev-bootstrap.sh@@ -0,0 +1,79 @@+#!/usr/bin/env bash++set -euo pipefail++project_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"++if [[ "${1:-}" == "--project-root" ]]; then+ project_root="${2:?--project-root requires a path}"+ shift 2+fi++if [[ $# -gt 0 ]]; then+ echo "Usage: $0 [--project-root PATH]" >&2+ exit 1+fi++if [[ ! -f "$project_root/package.json" || ! -f "$project_root/package-lock.json" ]]; then+ echo "Project root must contain package.json and package-lock.json: $project_root" >&2+ exit 1+fi++node_version="$(node --version | sed 's/^v//')"+npm_version="$(npm --version)"++version_is_supported="$(node - "$node_version" "$npm_version" <<'NODE'+const [nodeVersion, npmVersion] = process.argv.slice(2).map((value) => value.split('.').map(Number));+const compare = (left, right) => {+ for (let index = 0; index < Math.max(left.length, right.length); index += 1) {+ const difference = (left[index] ?? 0) - (right[index] ?? 0);+ if (difference !== 0) return difference;+ }+ return 0;+};+const nodeOk = compare(nodeVersion, [20, 18, 0]) >= 0 && nodeVersion[0] < 25;+const npmOk = compare(npmVersion, [10, 0, 0]) >= 0;+process.stdout.write(nodeOk && npmOk ? 'yes' : 'no');+NODE+)"++if [[ "$version_is_supported" != "yes" ]]; then+ echo "Node.js >=20.18.0 and <25.0.0 plus npm >=10.0.0 are required; found Node.js $node_version and npm $npm_version." >&2+ exit 1+fi++lock_hash_for() {+ node -e "const fs = require('node:fs'); const crypto = require('node:crypto'); process.stdout.write(crypto.createHash('sha256').update(fs.readFileSync(process.argv[1])).digest('hex'))" "$1"+}++lockfile="$project_root/package-lock.json"+node_modules="$project_root/node_modules"+lock_stamp="$node_modules/.freellmapi-bootstrap-lock"+lock_hash="$(lock_hash_for "$lockfile")"+installed_lock_hash=""++if [[ -f "$lock_stamp" ]]; then+ installed_lock_hash="$(tr -d '[:space:]' < "$lock_stamp")"+fi++cd "$project_root"++if [[ ! -d "$node_modules" || "$installed_lock_hash" != "$lock_hash" ]]; then+ echo 'Installing dependencies...'+ npm install+ lock_hash="$(lock_hash_for "$lockfile")"+ printf '%s' "$lock_hash" > "$lock_stamp"+else+ echo 'Dependencies already match package-lock.json.'+fi++if [[ ! -e .env ]]; then+ encryption_key="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))")"+ umask 077+ printf 'ENCRYPTION_KEY=%s\nPORT=3001\n' "$encryption_key" > .env+ echo 'Created .env with a new ENCRYPTION_KEY.'+else+ echo '.env already exists; leaving it unchanged.'+fi++echo 'Bootstrap complete. Start development with: npm run dev'diff --git a/scripts/dev-bootstrap.test.mjs b/scripts/dev-bootstrap.test.mjsnew file mode 100644index 00000000..c9874a30--- /dev/null+++ b/scripts/dev-bootstrap.test.mjs@@ -0,0 +1,90 @@+import { createHash } from 'node:crypto';+import { execFile as execFileCallback } from 'node:child_process';+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { promisify } from 'node:util';+import test from 'node:test';+import assert from 'node:assert/strict';++const execFile = promisify(execFileCallback);+const projectRoot = resolve(import.meta.dirname, '..');+const powershell = process.platform === 'win32' ? 'powershell.exe' : null;++async function makeFixture(t) {+ const fixture = await mkdtemp(join(tmpdir(), 'freellmapi-bootstrap-'));+ const lockfile = join(fixture, 'package-lock.json');+ const lockContents = '{"name":"bootstrap-fixture","lockfileVersion":3}\n';+ const lockHash = createHash('sha256').update(lockContents).digest('hex');++ await writeFile(join(fixture, 'package.json'), '{"name":"bootstrap-fixture"}\n');+ await writeFile(lockfile, lockContents);+ await mkdir(join(fixture, 'node_modules'));+ await writeFile(join(fixture, 'node_modules', '.freellmapi-bootstrap-lock'), lockHash);+ t.after(() => rm(fixture, { force: true, recursive: true }));+ return { fixture, lockfile };+}++async function assertEnvIsCreatedAndPreserved(runBootstrap, t) {+ const { fixture } = await makeFixture(t);++ await runBootstrap(fixture);+ const generatedEnv = await readFile(join(fixture, '.env'), 'utf8');+ assert.match(generatedEnv, /^ENCRYPTION_KEY=[0-9a-f]{64}\r?\nPORT=3001\r?\n$/);++ const existingEnv = 'ENCRYPTION_KEY=keep-this-value\nPORT=4444\n';+ await writeFile(join(fixture, '.env'), existingEnv);+ await runBootstrap(fixture);+ assert.equal(await readFile(join(fixture, '.env'), 'utf8'), existingEnv);+}++async function assertMissingStampInstalls(runBootstrap, t) {+ const { fixture, lockfile } = await makeFixture(t);+ await rm(join(fixture, 'node_modules', '.freellmapi-bootstrap-lock'));++ await runBootstrap(fixture);++ const lockHash = createHash('sha256').update(await readFile(lockfile)).digest('hex');+ assert.equal(+ (await readFile(join(fixture, 'node_modules', '.freellmapi-bootstrap-lock'), 'utf8')).trim(),+ lockHash,+ );+}++test('PowerShell bootstrap creates and preserves .env', { skip: powershell === null }, async (t) => {+ await assertEnvIsCreatedAndPreserved(+ (fixture) => execFile(powershell, [+ '-NoProfile',+ '-ExecutionPolicy', 'Bypass',+ '-File', join(projectRoot, 'scripts', 'dev-bootstrap.ps1'),+ '-ProjectRoot', fixture,+ ]),+ t,+ );+});++test('Bash bootstrap creates and preserves .env', { skip: process.platform === 'win32' }, async (t) => {+ await assertEnvIsCreatedAndPreserved(+ (fixture) => execFile('bash', [join(projectRoot, 'scripts', 'dev-bootstrap.sh'), '--project-root', fixture]),+ t,+ );+});++test('PowerShell bootstrap installs when the lockfile stamp is missing', { skip: powershell === null }, async (t) => {+ await assertMissingStampInstalls(+ (fixture) => execFile(powershell, [+ '-NoProfile',+ '-ExecutionPolicy', 'Bypass',+ '-File', join(projectRoot, 'scripts', 'dev-bootstrap.ps1'),+ '-ProjectRoot', fixture,+ ]),+ t,+ );+});++test('Bash bootstrap installs when the lockfile stamp is missing', { skip: process.platform === 'win32' }, async (t) => {+ await assertMissingStampInstalls(+ (fixture) => execFile('bash', [join(projectRoot, 'scripts', 'dev-bootstrap.sh'), '--project-root', fixture]),+ t,+ );+});