@iflow-mcp/jkheadley-instar 0.26.2

package/scripts/generate-builtin-manifest.cjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+/**
+ * generate-builtin-manifest.js
+ *
+ * Scans the Instar source tree to enumerate all built-in capabilities and
+ * produces src/data/builtin-manifest.json with content hashes.
+ *
+ * Run at build time: node scripts/generate-builtin-manifest.js
+ * CI validation: npm test includes a test that verifies the manifest is up-to-date.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// Guard: warn if working tree is dirty (manifest won't match committed source in CI)
+try {
+  const status = execSync('git status --porcelain -- src/', { cwd: ROOT, encoding: 'utf-8' }).trim();
+  if (status) {
+    console.warn('\n⚠️  WARNING: Working tree has uncommitted changes in src/.');
+    console.warn('   The generated manifest may not match committed source.');
+    console.warn('   CI test "is up-to-date with current source" will fail if you commit this.');
+    console.warn('   Stash WIP first: git stash push -u\n');
+  }
+} catch { /* not a git repo or git not available — skip check */ }
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function sha256File(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return sha256(content);
+}
+
+function fileExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Scan hooks from PostUpdateMigrator's migrateHooks method.
+ * These are the 14 hook files Instar writes to .instar/hooks/instar/.
+ */
+function scanHooks() {
+  const entries = [];
+
+  // The canonical list of built-in hooks, matching PostUpdateMigrator.migrateHookLayout's builtinHooks
+  const builtinHooks = [
+    { file: 'session-start.sh', domain: 'identity' },
+    { file: 'dangerous-command-guard.sh', domain: 'safety' },
+    { file: 'grounding-before-messaging.sh', domain: 'safety' },
+    { file: 'compaction-recovery.sh', domain: 'identity' },
+    { file: 'external-operation-gate.js', domain: 'safety' },
+    { file: 'deferral-detector.js', domain: 'safety' },
+    { file: 'post-action-reflection.js', domain: 'evolution' },
+    { file: 'external-communication-guard.js', domain: 'safety' },
+    { file: 'scope-coherence-collector.js', domain: 'coherence' },
+    { file: 'scope-coherence-checkpoint.js', domain: 'coherence' },
+    { file: 'free-text-guard.sh', domain: 'safety' },
+    { file: 'claim-intercept.js', domain: 'coherence' },
+    { file: 'claim-intercept-response.js', domain: 'coherence' },
+    { file: 'auto-approve-permissions.js', domain: 'safety' },
+  ];
+
+  for (const hook of builtinHooks) {
+    // Hooks are generated by PostUpdateMigrator at runtime, not from static files.
+    // We hash the source method that generates them (PostUpdateMigrator.ts) keyed by hook name.
+    // This means the manifest hash changes when the generator code changes.
+    const sourceFile = path.join(ROOT, 'src/core/PostUpdateMigrator.ts');
+    const sourceHash = fileExists(sourceFile) ? sha256File(sourceFile) : 'generated-at-runtime';
+
+    entries.push({
+      id: `hook:${hook.file.replace(/\.(sh|js)$/, '')}`,
+      type: 'hook',
+      domain: hook.domain,
+      sourcePath: `src/core/PostUpdateMigrator.ts`,
+      installedPath: `.instar/hooks/instar/${hook.file}`,
+      contentHash: sourceHash,
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Scan default jobs from getDefaultJobs() in init.ts.
+ * We extract job slugs by parsing the source.
+ */
+function scanDefaultJobs() {
+  const entries = [];
+  const initPath = path.join(ROOT, 'src/commands/init.ts');
+
+  if (!fileExists(initPath)) return entries;
+
+  const content = fs.readFileSync(initPath, 'utf-8');
+
+  // Extract job slugs from the getDefaultJobs function
+  const slugRegex = /slug:\s*'([^']+)'/g;
+  const functionStart = content.indexOf('function getDefaultJobs');
+  if (functionStart === -1) return entries;
+
+  // Find the closing of the function (next function or end)
+  const functionSection = content.slice(functionStart);
+  let match;
+  const slugs = [];
+  while ((match = slugRegex.exec(functionSection)) !== null) {
+    slugs.push(match[1]);
+  }
+
+  // Hash the getDefaultJobs function section for drift detection
+  const functionEnd = functionSection.indexOf('\n}\n');
+  const functionBody = functionSection.slice(0, functionEnd > 0 ? functionEnd + 3 : undefined);
+  const functionHash = sha256(functionBody);
+
+  const jobDomainMap = {
+    'health-check': 'monitoring',
+    'reflection-trigger': 'evolution',
+    'relationship-maintenance': 'relationships',
+    'update-check': 'updates',
+    'feedback-retry': 'feedback',
+    'dispatch-check': 'dispatches',
+    'self-diagnosis': 'monitoring',
+    'evolution-review': 'evolution',
+    'insight-harvest': 'evolution',
+    'commitment-check': 'commitments',
+    'project-map-refresh': 'mapping',
+    'coherence-audit': 'coherence',
+    'degradation-digest': 'monitoring',
+    'state-integrity-check': 'monitoring',
+    'memory-hygiene': 'memory',
+    'guardian-pulse': 'monitoring',
+    'session-continuity-check': 'sessions',
+    'memory-export': 'memory',
+    'git-sync': 'coordination',
+  };
+
+  for (const slug of slugs) {
+    entries.push({
+      id: `job:${slug}`,
+      type: 'job',
+      domain: jobDomainMap[slug] || 'general',
+      sourcePath: 'src/commands/init.ts',
+      contentHash: functionHash,
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Scan shipped skills from .claude/skills/.
+ */
+function scanSkills() {
+  const entries = [];
+  const skillsDir = path.join(ROOT, '.claude/skills');
+
+  if (!fs.existsSync(skillsDir)) return entries;
+
+  const skillFolders = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory());
+
+  for (const folder of skillFolders) {
+    const skillPath = path.join(skillsDir, folder.name, 'skill.md');
+    const altPath = path.join(skillsDir, folder.name, 'SKILL.md');
+    const actualPath = fileExists(skillPath) ? skillPath : (fileExists(altPath) ? altPath : null);
+
+    if (!actualPath) continue;
+
+    entries.push({
+      id: `skill:${folder.name}`,
+      type: 'skill',
+      domain: 'skills',
+      sourcePath: path.relative(ROOT, actualPath),
+      contentHash: sha256File(actualPath),
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Scan API route groups from routes.ts.
+ * We enumerate top-level route domains, not individual endpoints.
+ */
+function scanRouteGroups() {
+  const entries = [];
+  const routesPath = path.join(ROOT, 'src/server/routes.ts');
+  const machineRoutesPath = path.join(ROOT, 'src/server/machineRoutes.ts');
+
+  // Known route domains — we enumerate these statically because route registration
+  // is done via method calls, not a declarative config we can parse reliably.
+  const routeDomains = [
+    { name: 'health', domain: 'monitoring' },
+    { name: 'agents', domain: 'sessions' },
+    { name: 'backups', domain: 'operations' },
+    { name: 'git', domain: 'coordination' },
+    { name: 'memory', domain: 'memory' },
+    { name: 'semantic', domain: 'memory' },
+    { name: 'status', domain: 'monitoring' },
+    { name: 'capabilities', domain: 'mapping' },
+    { name: 'project-map', domain: 'mapping' },
+    { name: 'coherence', domain: 'coherence' },
+    { name: 'topic-bindings', domain: 'sessions' },
+    { name: 'context', domain: 'context' },
+    { name: 'scope-coherence', domain: 'coherence' },
+    { name: 'canonical-state', domain: 'state' },
+    { name: 'ci', domain: 'monitoring' },
+    { name: 'sessions', domain: 'sessions' },
+    { name: 'jobs', domain: 'scheduling' },
+    { name: 'skip-ledger', domain: 'scheduling' },
+    { name: 'telegram', domain: 'communication' },
+    { name: 'attention', domain: 'communication' },
+    { name: 'relationships', domain: 'relationships' },
+    { name: 'feedback', domain: 'feedback' },
+    { name: 'updates', domain: 'updates' },
+    { name: 'dispatches', domain: 'dispatches' },
+    { name: 'quota', domain: 'monitoring' },
+    { name: 'publishing', domain: 'publishing' },
+    { name: 'private-views', domain: 'publishing' },
+    { name: 'tunnel', domain: 'networking' },
+    { name: 'events', domain: 'networking' },
+    { name: 'evolution', domain: 'evolution' },
+    { name: 'watchdog', domain: 'monitoring' },
+    { name: 'topic-memory', domain: 'memory' },
+    { name: 'state-sync', domain: 'coordination' },
+    { name: 'intent', domain: 'intent' },
+    { name: 'triage', domain: 'safety' },
+    { name: 'operations', domain: 'safety' },
+    { name: 'sentinel', domain: 'safety' },
+    { name: 'trust', domain: 'safety' },
+    { name: 'monitoring', domain: 'monitoring' },
+    { name: 'commitments', domain: 'commitments' },
+    { name: 'episodes', domain: 'memory' },
+    { name: 'messages', domain: 'coordination' },
+    { name: 'system-reviews', domain: 'monitoring' },
+    { name: 'machine-mesh', domain: 'coordination' },
+    { name: 'secret-drop', domain: 'security' },
+  ];
+
+  // Hash the routes source for drift detection
+  const routesHash = fileExists(routesPath) ? sha256File(routesPath) : 'unknown';
+  const machineHash = fileExists(machineRoutesPath) ? sha256File(machineRoutesPath) : 'unknown';
+
+  for (const route of routeDomains) {
+    entries.push({
+      id: `route-group:${route.name}`,
+      type: 'route-group',
+      domain: route.domain,
+      sourcePath: route.name === 'machine-mesh' ? 'src/server/machineRoutes.ts' : 'src/server/routes.ts',
+      contentHash: route.name === 'machine-mesh' ? machineHash : routesHash,
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Scan CLI commands from cli.ts.
+ */
+function scanCliCommands() {
+  const entries = [];
+  const cliPath = path.join(ROOT, 'src/cli.ts');
+
+  if (!fileExists(cliPath)) return entries;
+
+  const cliHash = sha256File(cliPath);
+
+  // Top-level CLI commands
+  const commands = [
+    { name: 'init', domain: 'setup' },
+    { name: 'setup', domain: 'setup' },
+    { name: 'add', domain: 'setup' },
+    { name: 'backup', domain: 'operations' },
+    { name: 'git', domain: 'coordination' },
+    { name: 'memory', domain: 'memory' },
+    { name: 'knowledge', domain: 'memory' },
+    { name: 'semantic', domain: 'memory' },
+    { name: 'intent', domain: 'intent' },
+    { name: 'feedback', domain: 'feedback' },
+    { name: 'server', domain: 'server' },
+    { name: 'status', domain: 'monitoring' },
+    { name: 'user', domain: 'users' },
+    { name: 'relationship', domain: 'relationships' },
+    { name: 'job', domain: 'scheduling' },
+    { name: 'lifeline', domain: 'communication' },
+    { name: 'list', domain: 'monitoring' },
+    { name: 'autostart', domain: 'operations' },
+    { name: 'migrate', domain: 'updates' },
+    { name: 'machines', domain: 'coordination' },
+    { name: 'whoami', domain: 'identity' },
+    { name: 'pair', domain: 'coordination' },
+    { name: 'join', domain: 'coordination' },
+    { name: 'wakeup', domain: 'coordination' },
+    { name: 'leave', domain: 'coordination' },
+    { name: 'doctor', domain: 'monitoring' },
+    { name: 'review', domain: 'monitoring' },
+    { name: 'nuke', domain: 'operations' },
+    { name: 'playbook', domain: 'context' },
+  ];
+
+  for (const cmd of commands) {
+    entries.push({
+      id: `cli:${cmd.name}`,
+      type: 'cli-command',
+      domain: cmd.domain,
+      sourcePath: 'src/cli.ts',
+      contentHash: cliHash,
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Scan shipped template files.
+ */
+function scanTemplates() {
+  const entries = [];
+  const templateDirs = [
+    { dir: 'src/templates/hooks', type: 'template', domain: 'safety' },
+    { dir: 'src/templates/scripts', type: 'template', domain: 'operations' },
+    { dir: 'playbook-scripts', type: 'playbook-script', domain: 'context' },
+  ];
+
+  for (const { dir, type, domain } of templateDirs) {
+    const fullDir = path.join(ROOT, dir);
+    if (!fs.existsSync(fullDir)) continue;
+
+    const files = fs.readdirSync(fullDir, { withFileTypes: true })
+      .filter(f => f.isFile());
+
+    for (const file of files) {
+      const filePath = path.join(fullDir, file.name);
+      entries.push({
+        id: `${type}:${file.name}`,
+        type,
+        domain,
+        sourcePath: path.join(dir, file.name),
+        contentHash: sha256File(filePath),
+        since: '2025-01-01',
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Scan core subsystems (detected by the presence of key source files).
+ */
+function scanSubsystems() {
+  const subsystems = [
+    { name: 'server', domain: 'server', sourceFile: 'src/server/AgentServer.ts' },
+    { name: 'session-manager', domain: 'sessions', sourceFile: 'src/core/SessionManager.ts' },
+    { name: 'auto-updater', domain: 'updates', sourceFile: 'src/core/AutoUpdater.ts' },
+    { name: 'auto-dispatcher', domain: 'dispatches', sourceFile: 'src/core/AutoDispatcher.ts' },
+    { name: 'post-update-migrator', domain: 'updates', sourceFile: 'src/core/PostUpdateMigrator.ts' },
+    { name: 'scheduler', domain: 'scheduling', sourceFile: 'src/scheduler/JobScheduler.ts' },
+    { name: 'project-mapper', domain: 'mapping', sourceFile: 'src/core/ProjectMapper.ts' },
+    { name: 'degradation-reporter', domain: 'monitoring', sourceFile: 'src/monitoring/DegradationReporter.ts' },
+    { name: 'telegram-lifeline', domain: 'communication', sourceFile: 'src/lifeline/TelegramLifeline.ts' },
+    { name: 'orphan-process-reaper', domain: 'monitoring', sourceFile: 'src/monitoring/OrphanProcessReaper.ts' },
+    { name: 'semantic-memory', domain: 'memory', sourceFile: 'src/memory/SemanticMemory.ts' },
+    { name: 'multi-machine-coordinator', domain: 'coordination', sourceFile: 'src/core/MultiMachineCoordinator.ts' },
+    { name: 'backup-manager', domain: 'operations', sourceFile: 'src/core/BackupManager.ts' },
+    { name: 'evolution-manager', domain: 'evolution', sourceFile: 'src/core/EvolutionManager.ts' },
+  ];
+
+  const entries = [];
+
+  for (const sub of subsystems) {
+    const fullPath = path.join(ROOT, sub.sourceFile);
+    if (!fileExists(fullPath)) continue;
+
+    entries.push({
+      id: `subsystem:${sub.name}`,
+      type: 'subsystem',
+      domain: sub.domain,
+      sourcePath: sub.sourceFile,
+      contentHash: sha256File(fullPath),
+      since: '2025-01-01',
+    });
+  }
+
+  return entries;
+}
+
+// --- Main ---
+
+function main() {
+  const allEntries = [
+    ...scanHooks(),
+    ...scanDefaultJobs(),
+    ...scanSkills(),
+    ...scanRouteGroups(),
+    ...scanCliCommands(),
+    ...scanTemplates(),
+    ...scanSubsystems(),
+  ];
+
+  // Build the manifest
+  const manifest = {
+    $schema: './builtin-manifest.schema.json',
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    instarVersion: require(path.join(ROOT, 'package.json')).version,
+    entryCount: allEntries.length,
+    entries: {},
+  };
+
+  for (const entry of allEntries) {
+    manifest.entries[entry.id] = entry;
+  }
+
+  // Write to src/data/
+  const outputPath = path.join(ROOT, 'src/data/builtin-manifest.json');
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2) + '\n');
+
+  // Summary
+  const byType = {};
+  for (const entry of allEntries) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+  }
+
+  console.log(`Generated builtin-manifest.json: ${allEntries.length} entries`);
+  for (const [type, count] of Object.entries(byType).sort()) {
+    console.log(`  ${type}: ${count}`);
+  }
+}
+
+main();

package/scripts/pre-push-gate.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Fast pre-push gate — runs BEFORE the test suite to catch common issues early.
+ *
+ * Checks:
+ *   1. NEXT.md exists and has required sections (saves ~4min if missing)
+ *   2. package.json version was incremented from the latest published guide
+ *
+ * This is intentionally lightweight — no imports from src/, no TypeScript,
+ * no test framework. Just reads files and exits.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const upgradesDir = path.join(ROOT, 'upgrades');
+const nextPath = path.join(ROOT, 'upgrades', 'NEXT.md');
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+const version = pkg.version;
+
+const REQUIRED_SECTIONS = [
+  '## What Changed',
+  '## What to Tell Your User',
+  '## Summary of New Capabilities',
+];
+
+const MIN_LENGTH = 200;
+
+let errors = [];
+let warnings = [];
+
+// ── 1. NEXT.md validation ─────────────────────────────────────────────
+
+const versionedGuidePath = path.join(upgradesDir, `${version}.md`);
+const versionedGuideExists = fs.existsSync(versionedGuidePath);
+const nextExists = fs.existsSync(nextPath);
+
+if (versionedGuideExists) {
+  // Already finalized — validate the versioned guide instead
+  const content = fs.readFileSync(versionedGuidePath, 'utf-8');
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      errors.push(`${version}.md missing "${section}" section`);
+    }
+  }
+  if (content.length < MIN_LENGTH) {
+    errors.push(`${version}.md is too short (${content.length} chars, need ${MIN_LENGTH}+)`);
+  }
+} else if (nextExists) {
+  const content = fs.readFileSync(nextPath, 'utf-8');
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      errors.push(`NEXT.md missing "${section}" section`);
+    }
+  }
+
+  if (content.length < MIN_LENGTH) {
+    errors.push(`NEXT.md is too short (${content.length} chars, need ${MIN_LENGTH}+)`);
+  }
+
+  // Check for unfilled template placeholders
+  if (content.includes('<!-- Describe what changed')) {
+    errors.push(`NEXT.md "What Changed" still has template placeholder`);
+  }
+  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
+    errors.push(`NEXT.md "What to Tell Your User" still has template placeholder`);
+  }
+  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
+    errors.push(`NEXT.md "Summary of New Capabilities" still has template placeholder`);
+  }
+} else {
+  errors.push(
+    `No upgrade guide found. Create upgrades/NEXT.md with sections: ${REQUIRED_SECTIONS.join(', ')}`
+  );
+}
+
+// ── 2. Version increment check ────────────────────────────────────────
+
+// Find the latest published version from existing upgrade guides
+const publishedVersions = fs.existsSync(upgradesDir)
+  ? fs.readdirSync(upgradesDir)
+      .map(f => /^(\d+)\.(\d+)\.(\d+)\.md$/.exec(f))
+      .filter(Boolean)
+      .map(m => ({
+        str: `${m[1]}.${m[2]}.${m[3]}`,
+        parts: [+m[1], +m[2], +m[3]],
+      }))
+      .sort((a, b) => {
+        for (let i = 0; i < 3; i++) {
+          if (a.parts[i] !== b.parts[i]) return a.parts[i] - b.parts[i];
+        }
+        return 0;
+      })
+  : [];
+
+const latestPublished = publishedVersions.length > 0
+  ? publishedVersions[publishedVersions.length - 1]
+  : null;
+
+if (latestPublished) {
+  const [curMaj, curMin, curPatch] = version.split('.').map(Number);
+  const [pubMaj, pubMin, pubPatch] = latestPublished.parts;
+
+  if (curMaj === pubMaj && curMin === pubMin && curPatch === pubPatch) {
+    warnings.push(
+      `package.json version (${version}) matches the latest published guide (${latestPublished.str}). ` +
+      `Did you forget to bump the version? Run: npm version patch|minor|major`
+    );
+  } else if (
+    curMaj < pubMaj ||
+    (curMaj === pubMaj && curMin < pubMin) ||
+    (curMaj === pubMaj && curMin === pubMin && curPatch < pubPatch)
+  ) {
+    errors.push(
+      `package.json version (${version}) is LOWER than the latest published guide (${latestPublished.str}). ` +
+      `Version must be incremented, not decremented.`
+    );
+  }
+}
+
+// ── 3. Test file change check ─────────────────────────────────────────
+// If source files changed, at least one test file should also change.
+// This prevents shipping code changes without regression tests.
+
+try {
+  const { execSync } = await import('node:child_process');
+  // Get files changed since the remote tracking branch
+  const remoteBranch = execSync('git rev-parse --abbrev-ref @{u} 2>/dev/null || echo origin/main', { encoding: 'utf-8' }).trim();
+  const changedFiles = execSync(`git diff --name-only ${remoteBranch}...HEAD 2>/dev/null || git diff --name-only HEAD~1`, { encoding: 'utf-8' })
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+
+  const srcChanges = changedFiles.filter(f => f.startsWith('src/') && f.endsWith('.ts'));
+  const testChanges = changedFiles.filter(f => f.includes('tests/') && f.endsWith('.test.ts'));
+
+  if (srcChanges.length > 0 && testChanges.length === 0) {
+    warnings.push(
+      `${srcChanges.length} source file(s) changed but no test files were added or modified. ` +
+      `Every code change should include regression tests. Files changed:\n` +
+      srcChanges.slice(0, 5).map(f => `      • ${f}`).join('\n') +
+      (srcChanges.length > 5 ? `\n      • ...and ${srcChanges.length - 5} more` : '')
+    );
+  }
+} catch {
+  // Git commands may fail in CI or detached HEAD — skip gracefully
+}
+
+// ── Report ────────────────────────────────────────────────────────────
+
+if (errors.length > 0 || warnings.length > 0) {
+  console.log('\n  Pre-Push Gate');
+  console.log(`  ${'─'.repeat(40)}`);
+}
+
+if (errors.length > 0) {
+  console.log('');
+  for (const e of errors) {
+    console.log(`  ❌ ${e}`);
+  }
+  console.log('\n  Fix these before pushing. This saves ~4 minutes vs. discovering them in the test suite.\n');
+  process.exit(1);
+}
+
+if (warnings.length > 0) {
+  console.log('');
+  for (const w of warnings) {
+    console.log(`  ⚠️  ${w}`);
+  }
+  console.log('');
+}
+
+// If we get here, gate passed — print nothing (let the test suite output take over)

package/scripts/relay-entrypoint.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Minimal relay entrypoint for Docker/Fly.io deployment.
+ * Bypasses the CLI which checks for tmux and other local prerequisites.
+ */
+
+import { startRelay } from '../dist/commands/relay.js';
+
+const port = parseInt(process.env.RELAY_PORT ?? '8787', 10);
+const host = process.env.RELAY_HOST ?? '0.0.0.0';
+const adminPort = parseInt(process.env.RELAY_ADMIN_PORT ?? '9091', 10);
+const adminKey = process.env.RELAY_ADMIN_KEY ?? '';
+const dataDir = process.env.RELAY_DATA_DIR ?? './data';
+
+const authRate = process.env.RELAY_AUTH_RATE ?? 'not set';
+console.log(`  RELAY_AUTH_RATE: ${authRate}`);
+console.log(`  RELAY_DATA_DIR: ${dataDir}`);
+startRelay({ port, host, adminPort, adminKey, dataDir, foreground: true });