geniejars 0.2.7

package/src/pool.mjs

@@ -0,0 +1,158 @@
+import fs from 'fs/promises'
+import { createWriteStream } from 'fs'
+import path from 'path'
+
+const LOCK_RETRIES = 20
+const LOCK_DELAY_BASE_MS = 50
+
+// Load geniejars.config.json. Resolution order:
+//   1. explicit configPath argument
+//   2. $GENIEJARS_HOME/geniejars.config.json
+//   3. ./geniejars.config.json (cwd — works when running from project dir, including via sudo)
+//   4. error
+export async function loadConfig(configPath) {
+  let p
+  if (configPath) {
+    p = path.resolve(configPath)
+  } else if (process.env.GENIEJARS_HOME) {
+    p = path.join(process.env.GENIEJARS_HOME, 'geniejars.config.json')
+  } else {
+    const cwd = path.join(process.cwd(), 'geniejars.config.json')
+    try { await fs.access(cwd); p = cwd } catch {
+      throw new Error(
+        'No config found. Set GENIEJARS_HOME to your project directory, or run from the project root.'
+      )
+    }
+  }
+  const text = await fs.readFile(p, 'utf8')
+  const config = JSON.parse(text)
+  if (!config.nodePath) config.nodePath = process.execPath
+  return config
+}
+
+// Derive canonical geniejars name. n is 1-indexed.
+export function poolName(config, n) {
+  return config.poolPrefix + String(n).padStart(config.poolPadding, '0')
+}
+
+// All names in the pool, in order.
+export function allNames(config) {
+  const names = []
+  for (let i = 1; i <= config.poolSize; i++) {
+    names.push(poolName(config, i))
+  }
+  return names
+}
+
+// Home directory for a geniejars.
+export function homeDir(config, name) {
+  return path.join(config.homeBase, name)
+}
+
+// Build a fresh state with all geniejars and ports free.
+export function initialState(config) {
+  const pool = {}
+  for (const name of allNames(config)) {
+    pool[name] = { status: 'free', allocatedAt: null, allocatedBy: null, tag: null, ports: null, prepared: null }
+  }
+  const ports = {}
+  for (let i = 0; i < config.portCount; i++) {
+    ports[config.portBase + i] = 'free'
+  }
+  return { version: 1, updated: new Date().toISOString(), pool, ports }
+}
+
+// Read state file. Returns initialState if the file does not yet exist.
+// Migrates missing ports section if state predates port support.
+export async function readState(config) {
+  try {
+    const text = await fs.readFile(config.stateFile, 'utf8')
+    const state = JSON.parse(text)
+    if (!state.ports) {
+      const fresh = initialState(config)
+      state.ports = fresh.ports
+    }
+    return state
+  } catch (err) {
+    if (err.code === 'ENOENT') return initialState(config)
+    throw err
+  }
+}
+
+// Write state file atomically via a tmp-then-rename.
+// Caller must hold the lock.
+export async function writeState(config, state) {
+  state.updated = new Date().toISOString()
+  const tmp = config.stateFile + '.tmp'
+  const dir = path.dirname(config.stateFile)
+  await fs.mkdir(dir, { recursive: true })
+  await fs.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8')
+  await fs.rename(tmp, config.stateFile)
+}
+
+// Acquire the lock file. Returns an async release function.
+// Detects stale locks by checking if the recorded PID is still alive.
+export async function acquireLock(config) {
+  const lockFile = config.lockFile
+  const dir = path.dirname(lockFile)
+  await fs.mkdir(dir, { recursive: true })
+
+  for (let attempt = 0; attempt < LOCK_RETRIES; attempt++) {
+    try {
+      // O_EXCL: fail if exists — atomic create-exclusive
+      const fh = await fs.open(lockFile, 'wx')
+      await fh.writeFile(String(process.pid), 'utf8')
+      await fh.close()
+      return async () => {
+        try { await fs.unlink(lockFile) } catch {}
+      }
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+      // Check if the lock holder is still alive
+      try {
+        const pid = parseInt(await fs.readFile(lockFile, 'utf8'), 10)
+        if (!isNaN(pid) && pid !== process.pid) {
+          try {
+            process.kill(pid, 0)
+          } catch (killErr) {
+            if (killErr.code === 'ESRCH') {
+              // Stale lock — remove and retry immediately
+              await fs.unlink(lockFile).catch(() => {})
+              continue
+            }
+          }
+        }
+      } catch {}
+      // Wait with exponential backoff then retry
+      await sleep(LOCK_DELAY_BASE_MS * Math.pow(1.5, attempt))
+    }
+  }
+  throw new Error(`Could not acquire lock at ${lockFile} after ${LOCK_RETRIES} attempts`)
+}
+
+// Resolve a geniejars name or alias to a canonical pool name.
+// Accepts: 'sub001', 'helloworld_1'
+export function resolveName(state, nameOrAlias) {
+  if (nameOrAlias in state.pool) return nameOrAlias
+  const found = Object.entries(state.pool).find(([, e]) => e.alias === nameOrAlias)
+  if (found) return found[0]
+  throw new Error(`Unknown geniejars or alias: ${nameOrAlias}`)
+}
+
+// Free geniejars names.
+export function freeNames(state) {
+  return Object.entries(state.pool)
+    .filter(([, v]) => v.status === 'free')
+    .map(([k]) => k)
+}
+
+// Occupied geniejars names.
+export function occupiedNames(state) {
+  return Object.entries(state.pool)
+    .filter(([, v]) => v.status === 'occupied')
+    .map(([k]) => k)
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}

package/src/prepare.mjs

@@ -0,0 +1,219 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { homeDir, acquireLock, readState, writeState } from './pool.mjs'
+import { runShellAs } from './run.mjs'
+
+// Replace ${PORT(n)} and ${COMMON} placeholders in text.
+function substitute(text, ports, commonDir) {
+  text = text.replace(/\$\{PORT\((\d+)\)\}/g, (match, n) => {
+    const idx = parseInt(n, 10) - 1
+    if (idx < 0 || idx >= ports.length) {
+      throw new Error(`${match}: port index out of range (geniejars has ${ports.length} port(s))`)
+    }
+    return String(ports[idx])
+  })
+  if (commonDir != null) {
+    text = text.replace(/\$\{COMMON\}/g, commonDir)
+  }
+  return text
+}
+
+// Generate the next available alias for a tag across the pool.
+function nextAlias(state, tag, currentName) {
+  const used = Object.entries(state.pool)
+    .filter(([n, e]) => e.tag === tag && n !== currentName)
+    .map(([, e]) => e.alias)
+    .filter(Boolean)
+    .map(a => parseInt(a.split('_').pop(), 10))
+    .filter(n => !isNaN(n))
+  const num = used.length > 0 ? Math.max(...used) + 1 : 1
+  return `${tag}_${num}`
+}
+
+// Parse JFile text. Returns array of directive objects.
+// Supported directives: TAG, ENV, WORKDIR, COPY, RUN, CMD, DEPEND, ADDPATH, IMPORT
+export function parseJFile(text) {
+  const directives = []
+  const lines = text.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim()
+    const lineNum = i + 1
+
+    if (!line || line.startsWith('#')) continue
+
+    const spaceIdx = line.search(/\s/)
+    const directive = spaceIdx === -1 ? line.toUpperCase() : line.slice(0, spaceIdx).toUpperCase()
+    const rest = spaceIdx === -1 ? '' : line.slice(spaceIdx + 1).trimStart()
+
+    if (directive === 'TAG') {
+      if (!rest || /\s/.test(rest)) throw new Error(`JFile line ${lineNum}: TAG requires a single word`)
+      directives.push({ type: 'TAG', tag: rest, line: lineNum })
+
+    } else if (directive === 'COPY') {
+      const match = rest.match(/^(\S+)\s+(\S+)$/)
+      if (!match) throw new Error(`JFile line ${lineNum}: COPY requires exactly two arguments: COPY <src> <dest>`)
+      directives.push({ type: 'COPY', src: match[1], dest: match[2], line: lineNum })
+
+    } else if (directive === 'RUN') {
+      if (!rest) throw new Error(`JFile line ${lineNum}: RUN requires a command`)
+      directives.push({ type: 'RUN', command: rest, line: lineNum })
+
+    } else if (directive === 'ENV') {
+      const eqIdx = rest.indexOf('=')
+      if (eqIdx === -1) throw new Error(`JFile line ${lineNum}: ENV requires KEY=VALUE format`)
+      const key = rest.slice(0, eqIdx)
+      const value = rest.slice(eqIdx + 1)
+      if (!key) throw new Error(`JFile line ${lineNum}: ENV key cannot be empty`)
+      directives.push({ type: 'ENV', key, value, line: lineNum })
+
+    } else if (directive === 'WORKDIR') {
+      if (!rest) throw new Error(`JFile line ${lineNum}: WORKDIR requires a path`)
+      directives.push({ type: 'WORKDIR', path: rest, line: lineNum })
+
+    } else if (directive === 'DEPEND') {
+      if (!rest) throw new Error(`JFile line ${lineNum}: DEPEND requires a path`)
+      directives.push({ type: 'DEPEND', path: rest, line: lineNum })
+
+    } else if (directive === 'ADDPATH') {
+      if (!rest) throw new Error(`JFile line ${lineNum}: ADDPATH requires a path`)
+      directives.push({ type: 'ADDPATH', path: rest, line: lineNum })
+
+    } else if (directive === 'IMPORT') {
+      if (!rest || /\s/.test(rest)) throw new Error(`JFile line ${lineNum}: IMPORT requires a single env var name`)
+      directives.push({ type: 'IMPORT', key: rest, line: lineNum })
+
+    } else if (directive === 'CMD') {
+      if (!rest) throw new Error(`JFile line ${lineNum}: CMD requires a command`)
+      let cmd
+      if (rest.startsWith('[')) {
+        try { cmd = JSON.parse(rest) } catch {
+          throw new Error(`JFile line ${lineNum}: CMD JSON array is invalid`)
+        }
+      } else {
+        cmd = ['sh', '-c', rest]
+      }
+      directives.push({ type: 'CMD', cmd, line: lineNum })
+
+    } else {
+      throw new Error(`JFile line ${lineNum}: Unknown directive: ${directive}`)
+    }
+  }
+
+  return directives
+}
+
+// Read and parse a JFile from disk.
+export async function readJFile(filePath) {
+  const text = await fs.readFile(filePath, 'utf8')
+  return parseJFile(text)
+}
+
+// Apply parsed directives to a geniejars.
+// contextDir: base directory for resolving relative COPY src paths.
+// Options:
+//   env: object - extra env vars merged before JFile ENVs
+// Returns { tag, cmd, workdir, env }
+export async function applyJFile(config, name, directives, contextDir, options = {}) {
+  const home = homeDir(config, name)
+  const accEnv = { ...(options.env ?? {}) }
+  const addedPaths = []
+  let currentWorkdir = home
+  let cmd = null
+  let tag = null
+
+  for (const d of directives) {
+    if (d.type === 'TAG') {
+      tag = d.tag
+
+    } else if (d.type === 'ENV') {
+      accEnv[d.key] = d.value
+
+    } else if (d.type === 'WORKDIR') {
+      currentWorkdir = path.isAbsolute(d.path) ? d.path : path.join(home, d.path)
+      await fs.mkdir(currentWorkdir, { recursive: true })
+
+    } else if (d.type === 'COPY') {
+      const src = path.isAbsolute(d.src) ? d.src : path.resolve(contextDir, d.src)
+      const dest = path.isAbsolute(d.dest) ? d.dest : path.join(currentWorkdir, d.dest)
+      await fs.mkdir(path.dirname(dest), { recursive: true })
+      await fs.cp(src, dest, { recursive: true })
+
+    } else if (d.type === 'RUN') {
+      const result = await runShellAs(config, name, d.command, {
+        cwd: currentWorkdir,
+        env: Object.keys(accEnv).length > 0 ? accEnv : undefined,
+        capture: false,
+      })
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `JFile line ${d.line}: RUN failed (exit ${result.exitCode}): ${d.command}`
+        )
+      }
+
+    } else if (d.type === 'DEPEND') {
+      try {
+        await fs.access(d.path)
+      } catch {
+        throw new Error(`dependency not found: ${d.path}`)
+      }
+
+    } else if (d.type === 'IMPORT') {
+      if (!(d.key in process.env)) {
+        throw new Error(`IMPORT ${d.key}: variable not set in manager environment`)
+      }
+      accEnv[d.key] = process.env[d.key]
+
+    } else if (d.type === 'ADDPATH') {
+      addedPaths.push(d.path)
+
+    } else if (d.type === 'CMD') {
+      cmd = d.cmd
+    }
+  }
+
+  return { tag, cmd, workdir: currentWorkdir, env: accEnv, addedPaths }
+}
+
+// Convenience: read file, apply, and save prepared config to state.
+export async function prepare(config, name, geniejarsFilePath, options = {}) {
+  const absPath = path.resolve(geniejarsFilePath)
+  const contextDir = path.dirname(absPath)
+
+  // Read state to get assigned ports for substitution
+  const state = await readState(config)
+  const entry = state.pool[name]
+  if (!entry || entry.status !== 'occupied') {
+    throw new Error(`Geniejars ${name} is not allocated — run allocate first`)
+  }
+  const ports = entry.ports ?? []
+
+  // Substitute ${PORT(n)} and ${COMMON} before parsing
+  let text = await fs.readFile(absPath, 'utf8')
+  text = substitute(text, ports, config.commonDir ?? null)
+
+  const directives = parseJFile(text)
+  const prepared = await applyJFile(config, name, directives, contextDir, options)
+
+  // Save prepared config, tag, and alias into state
+  const release = await acquireLock(config)
+  try {
+    const st = await readState(config)
+    const e = st.pool[name]
+    if (e) {
+      const { tag } = prepared
+      // Keep existing alias if tag unchanged, otherwise generate a new one
+      const alias = (tag && e.tag === tag && e.alias)
+        ? e.alias
+        : (tag ? nextAlias(st, tag, name) : null)
+      e.tag = tag ?? e.tag
+      e.alias = alias
+      e.prepared = prepared
+    }
+    await writeState(config, st)
+  } finally {
+    await release()
+  }
+
+  return prepared
+}

package/src/run.mjs

@@ -0,0 +1,162 @@
+import net from 'net'
+import fs from 'fs'
+import path from 'path'
+import { homeDir } from './pool.mjs'
+
+function socketPath(config, name) {
+  return path.join(config.socketDir, `${name}.sock`)
+}
+
+// Send a request to the agent and handle the streaming response.
+// Resolves when the connection closes or a terminal message is received.
+function request(config, name, req, options = {}) {
+  const { capture = false, onMessage, logStream } = options
+
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath(config, name))
+    let buf = ''
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+
+    function settle(fn, value) {
+      if (settled) return
+      settled = true
+      fn(value)
+    }
+
+    client.on('connect', () => { client.write(JSON.stringify(req) + '\n') })
+
+    client.on('data', chunk => {
+      buf += chunk.toString()
+      let nl
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl).trim()
+        buf = buf.slice(nl + 1)
+        if (!line) continue
+        let msg
+        try { msg = JSON.parse(line) } catch { continue }
+
+        if (onMessage) onMessage(msg)
+
+        switch (msg.type) {
+          case 'stdout':
+            if (logStream) logStream.write(msg.data)
+            else if (capture) stdout += msg.data
+            else process.stdout.write(msg.data)
+            break
+          case 'stderr':
+            if (logStream) logStream.write(msg.data)
+            else if (capture) stderr += msg.data
+            else process.stderr.write(msg.data)
+            break
+          case 'exit':
+            settle(resolve, { exitCode: msg.code, stdout, stderr })
+            break
+          case 'started':
+            if (options.detach) {
+              settle(resolve, { pid: msg.pid, detached: true })
+              client.destroy()
+            }
+            break
+          case 'stopped':
+            settle(resolve, { stopped: true })
+            break
+          case 'status':
+            settle(resolve, { running: msg.running, pid: msg.pid })
+            break
+          case 'error':
+            settle(reject, new Error(msg.message))
+            client.destroy()
+            break
+        }
+      }
+    })
+
+    client.on('error', err =>
+      settle(reject, new Error(`Agent connection failed (${name}): ${err.message}`))
+    )
+    client.on('close', () => {
+      if (!settled) settle(resolve, { exitCode: null, stdout, stderr })
+    })
+  })
+}
+
+// Run a short-lived command as the geniejars via the agent.
+export async function runAs(config, name, cmd, args = [], options = {}) {
+  const { cwd, env, capture = false } = options
+  return request(config, name, { type: 'run', cmd, args, cwd, env }, { capture })
+}
+
+// Convenience: run `sh -c shellCommand` as the geniejars.
+export async function runShellAs(config, name, shellCommand, options = {}) {
+  return runAs(config, name, 'sh', ['-c', shellCommand], options)
+}
+
+// Derive the log file path for a geniejars from config.
+export function logFilePath(config, name) {
+  if (!config.logDir) return null
+  return path.join(config.logDir, `${name}.log`)
+}
+
+// Start the long-running main process.
+// wait: true (default) — awaits process exit, streams output to terminal
+// wait: false          — returns after started confirmation (fire and forget)
+// logFile: path        — write stdout/stderr to file instead of terminal
+//                        auto-derived from config.logDir when wait: false
+export async function startAs(config, name, cmd, args = [], options = {}) {
+  const { cwd, env, onStarted, wait = true, logFile } = options
+
+  const resolvedLogFile = logFile
+    ?? (!wait && config.logDir ? logFilePath(config, name) : null)
+
+  let logStream = null
+  if (resolvedLogFile) {
+    await fs.promises.mkdir(path.dirname(resolvedLogFile), { recursive: true })
+    logStream = fs.createWriteStream(resolvedLogFile, { flags: 'a' })
+  }
+
+  try {
+    return await request(config, name, { type: 'start', cmd, args, cwd, env }, {
+      detach: !wait,
+      logStream,
+      onMessage: msg => { if (msg.type === 'started' && onStarted) onStarted(msg.pid) },
+    })
+  } finally {
+    if (logStream) logStream.end()
+  }
+}
+
+// Stop the main process.
+export async function stopProcess(config, name) {
+  return request(config, name, { type: 'stop' })
+}
+
+// Get agent status.
+export async function agentStatus(config, name) {
+  return request(config, name, { type: 'status' })
+}
+
+// Ensure a geniejars agent is up via the shell server.
+// Requires the shell server to be running (geniejars sys up).
+export function ensureAgent(config, name) {
+  const serverSock = path.join(config.socketDir, 'server.sock')
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(serverSock)
+    let buf = ''
+    client.on('connect', () => client.write(JSON.stringify({ type: 'ensure', name }) + '\n'))
+    client.on('data', chunk => {
+      buf += chunk.toString()
+      if (buf.includes('\n')) {
+        try {
+          const msg = JSON.parse(buf.split('\n')[0].trim())
+          client.destroy()
+          if (msg.type === 'error') reject(new Error(msg.message))
+          else resolve()
+        } catch {}
+      }
+    })
+    client.on('error', err => reject(new Error(`Shell server not running: ${err.message}\nRun: geniejars sys up`)))
+    client.on('close', () => reject(new Error('No response from shell server')))
+  })
+}