Skip to content

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.md
index 4acd0452..e2110477 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,6 +12,18 @@ npm test # server vitest; also runs client tests if present
npm 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.md
index 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).
### Contributors
diff --git a/package.json b/package.json
index 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.ps1
new file mode 100644
index 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.sh
new file mode 100755
index 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.mjs
new file mode 100644
index 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,
+ );
+});