Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
13.4 KB
Raw Blame
/**
 * Run one ISOLATED dev instance of the Evenfire desktop app.
 *
 * Purpose: three PRs (and three minikube targets) have to run the desktop app at
 * the same time on one machine. A normal launch cannot do that because three
 * pieces of state are machine-wide: the `evenfire:`/`clerum:` OS protocol
 * handler, the application name `Evenfire`, and the user-data directory holding
 * the Chromium profile and the stored runtime-config profiles.
 *
 * This launcher therefore gives each run:
 *
 *   - its own per-run directory under the platform application-support
 *     directory (never inside the repository, so profile material cannot end up
 *     in the worktree, in commits or in notes);
 *   - a `--user-data-dir` inside that directory, plus
 *     `CLERUM_DESKTOP_CONFIG_PATH` pointing at a file inside it, so the runtime
 *     config layer cannot read the developer's shared `runtime-configs`
 *     directory even before Electron is ready;
 *   - explicit loopback REST/RPC endpoints taken from the command line;
 *   - a unique visible identity (`PR660 · Minikube30488`) that the app applies to
 *     the process name, the application name and the window title.
 *
 * The app then refuses to register OS protocol handlers and refuses to process
 * deep links, and it verifies the effective runtime (real userData, app path,
 * endpoints, config storage path) against this declaration before initializing
 * any service. A divergence aborts the launch instead of falling back to the
 * shared profile.
 *
 * Safety properties of this script:
 *   - it never copies or reads a session, a keychain entry, a `.env` file or any
 *     private config; it only creates a fresh directory and inspects the
 *     Electron binary and the existing build;
 *   - it never kills, reuses or adopts another instance, and it refuses
 *     `--force-*` passthrough flags;
 *   - the default action is to PRINT THE PLAN. It only spawns Electron with an
 *     explicit `--launch`, which is what keeps this launcher dormant until the
 *     main coordinator wires it up with #654/#651.
 *
 * Usage:
 *   node scripts/start-isolated-app.mjs --target <profile-label> --pr <number> \
 *     --rest-url <rest-origin> --rpc-url <rpc-origin>
 *   node scripts/start-isolated-app.mjs ... --launch
 *
 * Options:
 *   --target <slug>    required, e.g. minikube-30488 (safe slug, 1-64 chars)
 *   --rest-url <url>   required, loopback http(s) URL with an explicit port
 *   --rpc-url <url>    required, loopback http(s) URL with an explicit port
 *   --pr <number>      optional, digits only; makes the label `PR<n> · …`
 *   --base-dir <path>  optional, absolute parent for the per-run directory
 *                      (default: platform application-support directory)
 *   --launch           spawn Electron (default: print the plan only)
 *   --json             print the plan as JSON instead of one log line
 *   --help             print usage
 *   -- <args...>       extra Electron arguments (no `--force-*`, no
 *                      `--user-data-dir`: this script owns both)
 */
import { spawn } from 'node:child_process'
import fs from 'node:fs'
import { createRequire } from 'node:module'
import os from 'node:os'
import path from 'node:path'
import { fileURLToPath } from 'node:url'

const require = createRequire(import.meta.url)
const projectDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
const repoRoot = path.resolve(projectDirectory, '..')

function fail(message) {
  console.error(`[dev-isolation] ${message}`)
  process.exitCode = 1
  return null
}

/**
 * The contract lives in `src/devIsolation.ts`; the launcher consumes the
 * existing compiled build so the two can never disagree about paths, identity
 * or validation.
 */
function loadContract() {
  const compiled = path.join(projectDirectory, 'dist', 'devIsolation.js')
  if (!fs.existsSync(compiled)) {
    fail(
      `missing ${compiled}. Build the main process first: ` +
        `(cd ${path.relative(repoRoot, projectDirectory)} && npm run build:main)`
    )
    return null
  }
  try {
    return require(compiled)
  } catch (error) {
    fail(`could not load ${compiled}: ${error instanceof Error ? error.message : error}`)
    return null
  }
}

function parseArgs(argv) {
  const options = { launch: false, json: false, passthrough: [] }
  for (let index = 0; index < argv.length; index += 1) {
    const argument = argv[index]
    if (argument === '--') {
      options.passthrough = argv.slice(index + 1)
      break
    }
    if (argument === '--launch') {
      options.launch = true
      continue
    }
    if (argument === '--json') {
      options.json = true
      continue
    }
    if (argument === '--help' || argument === '-h') {
      options.help = true
      continue
    }
    const next = argv[index + 1]
    const readValue = name => {
      if (typeof next !== 'string' || next.startsWith('--')) {
        fail(`${name} requires a value`)
        return null
      }
      index += 1
      return next
    }
    if (argument === '--target') options.target = readValue('--target')
    else if (argument === '--pr') options.pr = readValue('--pr')
    else if (argument === '--rest-url') options.restUrl = readValue('--rest-url')
    else if (argument === '--rpc-url') options.rpcUrl = readValue('--rpc-url')
    else if (argument === '--base-dir') options.baseDir = readValue('--base-dir')
    else {
      fail(`unknown argument ${argument}`)
      return null
    }
    if (options.target === null || options.pr === null) return null
    if (options.restUrl === null || options.rpcUrl === null || options.baseDir === null) return null
  }
  return options
}

function assertPassthroughAllowed(passthrough) {
  for (const argument of passthrough) {
    if (argument.startsWith('--force-')) {
      return fail(`refusing passthrough flag ${argument}: forced flags are not allowed`)
    }
    if (argument === '--user-data-dir' || argument.startsWith('--user-data-dir=')) {
      return fail('refusing passthrough --user-data-dir: the launcher owns the isolated profile')
    }
  }
  return true
}

function resolveElectronBinary() {
  let binary
  try {
    binary = require('electron')
  } catch {
    return fail('Electron is not installed. Run: (cd desktop-app && npm run verify:electron)')
  }
  if (typeof binary !== 'string' || !binary) {
    return fail(
      'Electron runtime path is unavailable. Run: (cd desktop-app && npm run verify:electron)'
    )
  }
  try {
    fs.accessSync(binary, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK)
  } catch {
    return fail(`Electron runtime is not executable at ${binary}. Run: npm run verify:electron`)
  }
  return binary
}

function createRunDirectory(contract, options) {
  const baseDirResult = contract.admitIsolationBaseDir({
    requested: options.baseDir,
    repoRoot,
    platform: process.platform,
    homedir: os.homedir(),
    env: process.env,
  })
  if (!baseDirResult.ok) {
    return fail(`${baseDirResult.code}: ${baseDirResult.message}`)
  }
  const prefix = ['evenfire', options.pr ? `pr${options.pr}` : '', options.target, '']
    .filter(Boolean)
    .join('-')
  fs.mkdirSync(baseDirResult.baseDir, { recursive: true, mode: 0o700 })
  const realBase = fs.realpathSync.native(baseDirResult.baseDir)
  const realAdmission = contract.admitIsolationBaseDir({
    requested: realBase,
    repoRoot: fs.realpathSync.native(repoRoot),
    platform: process.platform,
    homedir: os.homedir(),
    env: process.env,
  })
  if (!realAdmission.ok) return fail(realAdmission.code)
  const runDir = fs.mkdtempSync(path.join(realBase, `${prefix}-`))
  const runPaths = contract.devIsolationPaths(runDir)
  fs.mkdirSync(runPaths.userDataDir, { recursive: true, mode: 0o700 })
  return runPaths
}

/**
 * Electron needs a process identity (PATH, HOME, locale). It must not inherit
 * the operator's session tokens, cloud keys, or SSH agent.
 */
const CHILD_ENV_ALLOWLIST = [
  'PATH',
  'HOME',
  'USER',
  'LOGNAME',
  'SHELL',
  'TMPDIR',
  'TMP',
  'TEMP',
  'LANG',
  'LC_ALL',
  'LC_CTYPE',
  'LC_MESSAGES',
  'TZ',
  'TERM',
  'DISPLAY',
  'WAYLAND_DISPLAY',
  'XAUTHORITY',
  'XDG_RUNTIME_DIR',
  'XDG_SESSION_TYPE',
  'XDG_CURRENT_DESKTOP',
  'XDG_DATA_DIRS',
  '__CF_USER_TEXT_ENCODING',
]

function allowedParentEnvironment() {
  const env = {}
  for (const key of CHILD_ENV_ALLOWLIST) {
    const value = process.env[key]
    if (typeof value === 'string' && value !== '') env[key] = value
  }
  return env
}

function childEnvironment(contract, runPaths, options, appPath) {
  return {
    ...allowedParentEnvironment(),
    [contract.DEV_ISOLATION_ENABLE_ENV]: '1',
    [contract.DEV_ISOLATION_ENV.runDir]: runPaths.runDir,
    [contract.DEV_ISOLATION_ENV.restUrl]: options.restUrl,
    [contract.DEV_ISOLATION_ENV.rpcUrl]: options.rpcUrl,
    [contract.DEV_ISOLATION_ENV.target]: options.target,
    ...(options.pr ? { [contract.DEV_ISOLATION_ENV.pr]: options.pr } : {}),
    [contract.DEV_ISOLATION_ENV.appPath]: appPath,
    EXTERNAL_REST_API_BASE_URL: options.restUrl,
    RPC_PROXY_BASE_URL: options.rpcUrl,
    EVENFIRE_RENDERER_URL: '',
    // Second isolation layer: the runtime-config layer reads this file instead
    // of the shared `runtime-configs` directory, including before Electron ready.
    CLERUM_DESKTOP_CONFIG_PATH: runPaths.configPath,
  }
}

function planRecord(plan, runPaths, electronBinary, entrypoint, launch) {
  return {
    kind: 'evenfire-dev-isolation-plan',
    mode: launch ? 'launch' : 'plan-only',
    target: plan.identity.target,
    label: plan.label,
    appName: plan.appName,
    runDir: runPaths.runDir,
    userDataDir: runPaths.userDataDir,
    configPath: runPaths.configPath,
    restUrl: plan.restUrl,
    rpcUrl: plan.rpcUrl,
    appPath: plan.appPath ?? '',
    electron: electronBinary ?? '',
    entrypoint,
  }
}

function printRecord(contract, record, json) {
  if (json) {
    console.log(JSON.stringify(record, null, 2))
    return
  }
  console.log(contract.formatDevIsolationLogLine(record))
}

function writeRunMetadata(runPaths, record, pid) {
  const metadata = { ...record, pid }
  const temporary = `${runPaths.recordPath}.tmp`
  fs.writeFileSync(temporary, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 })
  fs.renameSync(temporary, runPaths.recordPath)
  fs.writeFileSync(runPaths.pidPath, `${pid}\n`, { mode: 0o600 })
}

function launch(contract, plan, runPaths, options, electronBinary, entrypoint, record) {
  const env = childEnvironment(contract, runPaths, options, path.dirname(entrypoint))
  // Self-check with the same contract the app applies: a declaration this
  // launcher cannot itself validate must never reach Electron.
  const decision = contract.resolveDevIsolation(env, [
    contract.DEV_ISOLATION_FLAG,
    '--user-data-dir',
    runPaths.userDataDir,
  ])
  if (decision.mode !== 'isolated') {
    const detail =
      decision.mode === 'refused' ? `${decision.code}: ${decision.message}` : decision.mode
    return fail(`the launcher's own declaration does not validate: ${detail}`)
  }

  const child = spawn(
    electronBinary,
    [`--user-data-dir=${runPaths.userDataDir}`, contract.DEV_ISOLATION_FLAG, entrypoint],
    { env, cwd: projectDirectory, stdio: 'inherit' }
  )
  if (typeof child.pid !== 'number') {
    return fail('Electron did not start')
  }
  writeRunMetadata(runPaths, record, child.pid)
  console.log(`[dev-isolation] launched pid=${child.pid} entrypoint=${entrypoint}`)
  console.log(`[dev-isolation] metadata=${runPaths.recordPath}`)

  for (const signal of ['SIGINT', 'SIGTERM']) {
    process.once(signal, () => child.kill(signal))
  }
  child.once('error', error => {
    console.error(`[dev-isolation] Electron failed to start: ${error.message}`)
    process.exitCode = 1
  })
  child.once('exit', (code, signal) => {
    process.exitCode = signal ? 1 : (code ?? 0)
  })
  return true
}

function main() {
  const options = parseArgs(process.argv.slice(2))
  if (!options) return
  if (options.help) {
    console.log('See the header of scripts/start-isolated-app.mjs for usage.')
    return
  }
  if (!options.target || !options.restUrl || !options.rpcUrl) {
    fail('--target, --rest-url and --rpc-url are required')
    return
  }
  if (!assertPassthroughAllowed(options.passthrough)) return

  const contract = loadContract()
  if (!contract) return

  const entrypoint = path.join(projectDirectory, 'dist', 'main.js')
  if (!fs.existsSync(entrypoint)) {
    fail(`missing ${entrypoint}. Build first: (cd desktop-app && npm run build:main)`)
    return
  }
  const electronBinary = resolveElectronBinary()
  if (!electronBinary) return

  const runPaths = createRunDirectory(contract, options)
  if (!runPaths) return

  const env = childEnvironment(contract, runPaths, options, path.dirname(entrypoint))
  const decision = contract.resolveDevIsolation(env, [
    contract.DEV_ISOLATION_FLAG,
    '--user-data-dir',
    runPaths.userDataDir,
  ])
  if (decision.mode !== 'isolated') {
    const detail =
      decision.mode === 'refused' ? `${decision.code}: ${decision.message}` : decision.mode
    fail(`the launcher's declaration does not validate: ${detail}`)
    return
  }
  const plan = decision.plan
  const record = planRecord(plan, runPaths, electronBinary, entrypoint, options.launch)
  printRecord(contract, record, options.json)

  if (!options.launch) {
    console.log(
      '[dev-isolation] plan only: nothing was launched. ' +
        'Re-run with --launch once the coordinator enables the isolated lane.'
    )
    return
  }
  launch(contract, plan, runPaths, options, electronBinary, entrypoint, record)
}

main()