geniejars 0.2.7

package/script/geniejars.mjs

@@ -0,0 +1,667 @@
+#!/usr/bin/env node
+// Usage: geniejars <command> [subcommand] [options]
+//
+// Commands:
+//   preconfig                          create geniejars.config.json in current directory
+//   example install                    install hello world webserver example
+//   setup                              one-time system setup (run as root)
+//   uninstall                          remove all geniejars and system config (run as root)
+//   sys up                             start shell server
+//   sys down                           stop shell server and all agents
+//   sys status                         show running agents
+//   alloc [-s|--select] [--backup] [--no-clear] [--tag <tag>]
+//   free [name]                        uses selected if no name
+//   build [name] [folder|JFile]        uses selected if no name
+//   app up [-n|--nowait] [name]        start CMD, uses selected if no name
+//   app down [name]                    stop CMD, uses selected if no name
+//   exec [name] <cmd> [args...]        run one-off command, uses selected if no name
+//   normalize [name]                   fix file permissions, uses selected if no name
+//   status [--json]                    show pool status
+//   mount [-C] [name] <path>           symlink geniejars home, uses selected if no name
+//   mount -C <path>                    symlink commonDir
+//   unmount <path>                     remove symlink
+//   select <name>                      select geniejars for subsequent commands
+//   unselect                           clear selection
+
+import net from 'net'
+import { spawn, execFile } from 'child_process'
+import { promisify } from 'util'
+import fs from 'fs/promises'
+import fsSync from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+import { loadConfig, readState, allNames, homeDir, resolveName } from '../src/pool.mjs'
+import { allocate, deallocate } from '../src/allocate.mjs'
+import { prepare } from '../src/prepare.mjs'
+import { runAs, startAs, stopProcess, agentStatus, ensureAgent } from '../src/run.mjs'
+import { normalize } from '../src/normalize.mjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const serverScript = path.resolve(__dirname, '../src/server.mjs')
+const setupScript = path.resolve(__dirname, 'setup-geniejars.mjs')
+const uninstallScript = path.resolve(__dirname, 'uninstall-geniejars.mjs')
+
+// --- Selection ---
+
+const SELECTED_FILE = path.resolve('.geniejars-selected')
+
+function getSelected() {
+  if (process.env.GENIEJARS) return process.env.GENIEJARS.trim()
+  try { return fsSync.readFileSync(SELECTED_FILE, 'utf8').trim() || null } catch { return null }
+}
+
+async function setSelected(name) {
+  await fs.writeFile(SELECTED_FILE, name + '\n')
+}
+
+async function clearSelected() {
+  await fs.unlink(SELECTED_FILE).catch(() => {})
+}
+
+// --- Helpers ---
+
+function die(msg) {
+  console.error('Error:', msg)
+  process.exit(1)
+}
+
+function requireName(arg, state) {
+  const raw = arg ?? getSelected()
+  if (!raw) die('no geniejars specified and none selected (use: geniejars select <name>)')
+  return resolveName(state, raw)
+}
+
+// --- Server helpers ---
+
+function serverSockPath(config) {
+  return path.join(config.socketDir, 'server.sock')
+}
+
+function serverPidPath(config) {
+  return path.join(config.socketDir, 'server.pid')
+}
+
+function isRunning(pid) {
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+// Send one request to the shell server, return response
+function serverRequest(config, req) {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(serverSockPath(config))
+    let buf = ''
+    client.on('connect', () => { client.write(JSON.stringify(req) + '\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(msg)
+        } 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')))
+  })
+}
+
+// --- Command dispatch ---
+
+const argv = process.argv.slice(2)
+const [cmd, ...args] = argv
+
+function showHelp() {
+  console.log(`Usage: geniejars <command> [options]
+
+Commands:
+  preconfig                          create geniejars.config.json in current directory
+  example install                    install hello world webserver example
+  setup                              one-time system setup (run as root)
+  uninstall                          remove all geniejars and system config (run as root)
+  sys up                             start shell server
+  sys down                           stop shell server and all agents
+  sys status                         show running agents
+  alloc [-s|--select] [--backup] [--no-clear] [--tag <tag>]
+  free [name]                        uses selected if no name
+  build [name] [folder|JFile]        uses selected if no name
+  app up [-n|--nowait] [name]        start CMD, uses selected if no name
+  app down [name]                    stop CMD, uses selected if no name
+  exec [name] <cmd> [args...]        run one-off command, uses selected if no name
+  normalize [name]                   fix file permissions, uses selected if no name
+  status [--json]                    show pool status
+  mount [name] <path>                symlink geniejars home, uses selected if no name
+  mount -C <path>                    symlink commonDir
+  unmount <path>                     remove symlink
+  select <name>                      select geniejars for subsequent commands
+  unselect                           clear selection
+  readme                             show the README
+  common-issues                      show common issues and solutions`)
+}
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  showHelp()
+  process.exit(0)
+}
+
+if (cmd === 'example') {
+  const [subcmd] = args
+  if (subcmd !== 'install') die('Usage: geniejars example install')
+  const dir = path.resolve('geniejars-example')
+  try {
+    await fs.access(dir)
+    console.error('geniejars-example/ already exists — remove it first if you want to reinstall')
+    process.exit(1)
+  } catch {}
+  await fs.mkdir(dir)
+  await fs.mkdir(path.join(dir, 'helloworld'))
+
+  // --- helloworld/server.mjs ---
+  await fs.writeFile(path.join(dir, 'helloworld', 'server.mjs'), `\
+import http from 'http'
+import os from 'os'
+
+const port = parseInt(process.env.PORT_1 || '3000')
+const user = process.env.USER || 'unknown'
+const started = new Date().toISOString()
+
+function log(msg) { console.log(\`[\${new Date().toISOString()}] \${msg}\`) }
+
+log(\`starting — user: \${user}  host: \${os.hostname()}  port: \${port}\`)
+
+const heartbeat = setInterval(() => log(\`heartbeat — uptime \${process.uptime().toFixed(1)}s\`), 3000)
+heartbeat.unref()
+
+const html = \`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>geniejars example</title>
+  <style>
+    body { font-family: monospace; max-width: 600px; margin: 80px auto; padding: 0 20px; color: #1a1a1a; }
+    h1 { font-size: 1.4rem; margin-bottom: 0.2em; }
+    .tag { display: inline-block; background: #e8f5e9; color: #2e7d32; padding: 2px 8px; border-radius: 3px; font-size: 0.85rem; }
+    table { margin-top: 2em; border-collapse: collapse; width: 100%; }
+    td { padding: 6px 12px; border-bottom: 1px solid #eee; }
+    td:first-child { color: #888; width: 120px; }
+    footer { margin-top: 3em; font-size: 0.8rem; color: #aaa; }
+  </style>
+</head>
+<body>
+  <h1>geniejars example server</h1>
+  <span class="tag">running</span>
+  <table>
+    <tr><td>user</td><td>\${user}</td></tr>
+    <tr><td>port</td><td>\${port}</td></tr>
+    <tr><td>host</td><td>\${os.hostname()}</td></tr>
+    <tr><td>started</td><td>\${started}</td></tr>
+    <tr><td>uptime</td><td>\${process.uptime().toFixed(0)}s</td></tr>
+  </table>
+  <footer>This process is isolated inside its own Linux user account.<br>Powered by <strong>geniejars</strong>.</footer>
+</body>
+</html>\`
+
+const server = http.createServer((req, res) => {
+  log(\`\${req.method} \${req.url} from \${req.socket.remoteAddress}\`)
+  res.writeHead(200, { 'Content-Type': 'text/html' })
+  res.end(html)
+})
+
+server.listen(port, () => log(\`listening on http://localhost:\${port}\`))
+
+process.on('SIGTERM', () => {
+  log('received SIGTERM — shutting down')
+  clearInterval(heartbeat)
+  server.close()
+})
+`)
+
+  // --- helloworld/JFile ---
+  await fs.writeFile(path.join(dir, 'helloworld', 'JFile'), `\
+TAG helloworld
+COPY server.mjs server.mjs
+CMD node server.mjs
+`)
+
+  // --- libcall.mjs ---
+  await fs.writeFile(path.join(dir, 'libcall.mjs'), `\
+#!/usr/bin/env node
+// geniejars libcall example
+//
+// Allocates a geniejars, builds and runs the helloworld webserver for 15 seconds,
+// then stops it and prints the captured log.
+//
+// Run from your project directory:
+//   node geniejars-example/libcall.mjs
+
+import fs from 'fs/promises'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import * as geniejars from 'geniejars'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const subFile = path.join(__dirname, 'helloworld', 'JFile')
+
+const config = await geniejars.loadConfig()
+
+console.log('=== geniejars libcall example ===')
+console.log()
+
+let name
+try {
+  process.stdout.write('Allocating geniejars...  ')
+  name = await geniejars.allocate(config, { tag: 'libcall' })
+  console.log(name)
+
+  process.stdout.write('Building helloworld... ')
+  const prepared = await geniejars.prepare(config, name, subFile)
+  console.log('done')
+
+  process.stdout.write('Starting agent...      ')
+  await geniejars.ensureAgent(config, name)
+  console.log('ready')
+
+  // Build port env from allocated ports
+  const state = await geniejars.readState(config)
+  const ports = state.pool[name]?.ports ?? []
+  const portEnv = Object.fromEntries(ports.map((p, i) => [\`PORT_\${i + 1}\`, String(p)]))
+
+  const logFile = path.join(config.logDir ?? '/tmp', \`libcall-\${name}.log\`)
+  await fs.rm(logFile, { force: true })
+
+  const [cmd, ...args] = prepared.cmd
+  console.log(\`Starting app...        (log: \${logFile})\`)
+  if (ports.length > 0) console.log(\`  curl http://localhost:\${ports[0]}\`)
+  console.log()
+
+  const stopTimer = setTimeout(() => geniejars.stopProcess(config, name).catch(() => {}), 15000)
+
+  await geniejars.startAs(config, name, cmd, args, {
+    cwd: prepared.workdir,
+    env: { ...prepared.env, ...portEnv },
+    wait: true,
+    logFile,
+    onStarted: pid => console.log(\`  [pid \${pid}] started — running for 15 seconds...\`),
+  })
+
+  clearTimeout(stopTimer)
+  console.log()
+  console.log(\`--- captured log (\${logFile}) ---\`)
+  const log = await fs.readFile(logFile, 'utf8').catch(() => '(no log captured)')
+  console.log(log.trimEnd())
+  console.log('--- end of log ---')
+  console.log()
+
+} finally {
+  if (name) {
+    process.stdout.write('Deallocating...        ')
+    await geniejars.deallocate(config, name).catch(() => {})
+    console.log('done')
+  }
+}
+`)
+
+  console.log('Examples installed in ./geniejars-example/')
+  console.log()
+  console.log('helloworld — simple isolated webserver:')
+  console.log('  geniejars alloc -s')
+  console.log('  geniejars build ./geniejars-example/helloworld')
+  console.log('  geniejars app up')
+  console.log()
+  console.log('libcall — library usage demo:')
+  console.log('  node geniejars-example/libcall.mjs')
+  process.exit(0)
+}
+
+if (cmd === 'preconfig') {
+  const dest = path.resolve('geniejars.config.json')
+  const src = path.resolve(__dirname, '../geniejars.config.example.json')
+  try {
+    await fs.access(dest)
+    console.error('geniejars.config.json already exists — remove it first if you want to reset')
+    process.exit(1)
+  } catch {}
+  await fs.copyFile(src, dest)
+  console.log(`geniejars.config.json created in ${process.cwd()}`)
+  console.log('Edit it to match your system, then run: sudo geniejars setup')
+  process.exit(0)
+}
+
+process.on('uncaughtException', err => {
+  console.error('Error:', err.message)
+  process.exit(1)
+})
+
+process.on('unhandledRejection', err => {
+  console.error('Error:', err?.message ?? err)
+  process.exit(1)
+})
+
+const config = await loadConfig()
+
+// setup
+if (cmd === 'setup') {
+  const child = spawn(config.nodePath ?? process.execPath, [setupScript], { stdio: 'inherit' })
+  child.on('exit', code => process.exit(code ?? 0))
+
+// uninstall
+} else if (cmd === 'uninstall') {
+  const child = spawn(config.nodePath ?? process.execPath, [uninstallScript], { stdio: 'inherit' })
+  child.on('exit', code => process.exit(code ?? 0))
+
+// sys
+} else if (cmd === 'sys') {
+  const [subcmd] = args
+  if (!subcmd || !['up', 'down', 'status'].includes(subcmd)) {
+    die('Usage: geniejars sys <up|down|status>')
+  }
+  await fs.mkdir(config.socketDir, { recursive: true })
+
+  if (subcmd === 'up') {
+    // Check that all required groups are active in this session
+    const execFileAsync = promisify(execFile)
+    const activeGids = new Set(process.getgroups())
+    const requiredGroups = [config.managerGroup, ...allNames(config)]
+    const missingGroups = []
+    for (const group of requiredGroups) {
+      try {
+        const { stdout } = await execFileAsync('getent', ['group', group])
+        const gid = parseInt(stdout.split(':')[2], 10)
+        if (!activeGids.has(gid)) missingGroups.push(group)
+      } catch {
+        missingGroups.push(group)
+      }
+    }
+    if (missingGroups.length > 0) {
+      console.error(`Error: missing active group membership for: ${missingGroups.join(', ')}`)
+      console.error(`Group membership changes require a new login session.`)
+      console.error(`Run: su ${config.managerUser}  (or log out and back in)`)
+      process.exit(1)
+    }
+
+    const pidPath = serverPidPath(config)
+    try {
+      const existing = parseInt(await fs.readFile(pidPath, 'utf8'), 10)
+      if (existing && isRunning(existing)) {
+        console.log(`Server already running (pid ${existing})`)
+        process.exit(0)
+      }
+    } catch {}
+    const child = spawn(config.nodePath ?? process.execPath, [serverScript], {
+      detached: true,
+      stdio: ['ignore', 'ignore', 'ignore'],
+    })
+    child.unref()
+    await fs.writeFile(pidPath, String(child.pid))
+    console.log(`Server started (pid ${child.pid})`)
+
+  } else if (subcmd === 'down') {
+    try {
+      await serverRequest(config, { type: 'shutdown' })
+      await fs.unlink(serverPidPath(config)).catch(() => {})
+      console.log('Server shutting down')
+    } catch (err) { die(err.message) }
+
+  } else if (subcmd === 'status') {
+    try {
+      const resp = await serverRequest(config, { type: 'status' })
+      if (resp.agents.length === 0) {
+        console.log('No agents running')
+      } else {
+        for (const { name, pid } of resp.agents) console.log(`${name}: running (pid ${pid})`)
+      }
+    } catch (err) { die(err.message) }
+  }
+
+// alloc
+} else if (cmd === 'alloc') {
+  const backup = args.includes('--backup')
+  const clear = !args.includes('--no-clear')
+  const select = args.includes('--select') || args.includes('-s')
+  let tag = null
+  const tagIdx = args.indexOf('--tag')
+  if (tagIdx !== -1) {
+    tag = args[tagIdx + 1]
+    if (!tag) die('--tag requires a value')
+  }
+  try {
+    const name = await allocate(config, { backup, clear, tag })
+    if (select) await setSelected(name)
+    console.log(name)
+  } catch (err) { die(err.message) }
+
+// free
+} else if (cmd === 'free') {
+  const state = await readState(config)
+  const name = requireName(args[0], state)
+  try {
+    await deallocate(config, name)
+    if (getSelected() === name) await clearSelected()
+    console.log(`Released: ${name}`)
+  } catch (err) { die(err.message) }
+
+// build
+} else if (cmd === 'build') {
+  const selected = getSelected()
+  let name, subFile
+  if (selected) {
+    name = resolveName(await readState(config), selected)
+    const arg = args[0] ?? 'JFile'
+    const argStat = await fs.stat(path.resolve(arg)).catch(() => null)
+    subFile = argStat?.isDirectory() ? path.join(arg, 'JFile') : arg
+  } else {
+    if (!args[0]) die('Usage: geniejars build <name> [folder|JFile]')
+    const state = await readState(config)
+    name = resolveName(state, args[0])
+    const arg = args[1] ?? 'JFile'
+    const argStat = await fs.stat(path.resolve(arg)).catch(() => null)
+    subFile = argStat?.isDirectory() ? path.join(arg, 'JFile') : arg
+  }
+  try {
+    await prepare(config, name, subFile)
+    const fresh = await readState(config)
+    const alias = fresh.pool[name]?.alias
+    console.log(`Built: ${name}${alias ? ` (${alias})` : ''}`)
+  } catch (err) { die(err.message) }
+
+// app
+} else if (cmd === 'app') {
+  const flags = args.filter(a => a.startsWith('-'))
+  const positional = args.filter(a => !a.startsWith('-'))
+  const [subcmd, nameOrAlias] = positional
+
+  if (!subcmd || !['up', 'down'].includes(subcmd)) die('Usage: geniejars app <up|down> [name]')
+
+  const state = await readState(config)
+  const name = requireName(nameOrAlias, state)
+  const entry = state.pool[name]
+
+  if (subcmd === 'up') {
+    if (!entry.prepared?.cmd) die('No CMD found — run: geniejars build first')
+    const [appCmd, ...cmdArgs] = entry.prepared.cmd
+    const cwd = entry.prepared.workdir ?? homeDir(config, name)
+    const portEnv = {}
+    if (entry.ports) entry.ports.forEach((port, i) => { portEnv[`PORT_${i + 1}`] = String(port) })
+    const addedPaths = entry.prepared.addedPaths ?? []
+    const basePath = process.env.PATH || '/usr/local/bin:/usr/bin:/bin'
+    const pathEnv = addedPaths.length > 0 ? { PATH: addedPaths.join(':') + ':' + basePath } : {}
+    const env = { ...portEnv, ...pathEnv, ...(entry.prepared.env ?? {}) }
+    const wait = !flags.includes('--nowait') && !flags.includes('-n')
+
+    await ensureAgent(config, name)
+
+    if (wait) {
+      process.on('SIGINT', async () => { await stopProcess(config, name).catch(() => {}); process.exit(0) })
+    }
+    try {
+      const result = await startAs(config, name, appCmd, cmdArgs, {
+        cwd, env, wait,
+        onStarted: pid => console.error(`[geniejars] ${name} started (pid ${pid})`),
+      })
+      if (!wait) console.log(name)
+      else process.exit(result.exitCode ?? 0)
+    } catch (err) { die(err.message) }
+
+  } else if (subcmd === 'down') {
+    try {
+      await stopProcess(config, name)
+      console.log(`Stopped: ${name}`)
+    } catch (err) { die(err.message) }
+  }
+
+// exec
+} else if (cmd === 'exec') {
+  const selected = getSelected()
+  let name, execCmd, execArgs
+  if (selected) {
+    const state = await readState(config)
+    name = resolveName(state, selected)
+    ;[execCmd, ...execArgs] = args
+  } else {
+    const [nameOrAlias, c, ...rest] = args
+    if (!nameOrAlias || !c) die('Usage: geniejars exec [name] <cmd> [args...]')
+    const state = await readState(config)
+    name = resolveName(state, nameOrAlias)
+    execCmd = c
+    execArgs = rest
+  }
+  if (!execCmd) die('No command specified')
+  // Single argument with no sub-args — run through shell so redirects, pipes, etc. work
+  if (execArgs.length === 0) { execArgs = ['-c', execCmd]; execCmd = 'sh' }
+  await ensureAgent(config, name)
+  try {
+    const result = await runAs(config, name, execCmd, execArgs)
+    process.exit(result.exitCode ?? 0)
+  } catch (err) { die(err.message) }
+
+// normalize
+} else if (cmd === 'normalize') {
+  const state = await readState(config)
+  const name = requireName(args[0], state)
+  try {
+    await normalize(config, name)
+    console.log(`Normalized: ${name}`)
+  } catch (err) { die(err.message) }
+
+// status
+} else if (cmd === 'status') {
+  const jsonMode = args.includes('--json')
+  const state = await readState(config)
+  if (jsonMode) { console.log(JSON.stringify(state, null, 2)); process.exit(0) }
+  const names = allNames(config)
+  const agentResults = await Promise.all(
+    names.map(async name => {
+      const entry = state.pool[name]
+      if (entry?.status !== 'occupied') return { name, running: false, pid: null }
+      try {
+        const s = await agentStatus(config, name)
+        return { name, running: s.running, pid: s.pid }
+      } catch { return { name, running: false, pid: null } }
+    })
+  )
+  const agentMap = Object.fromEntries(agentResults.map(r => [r.name, r]))
+  const rows = names.map(name => {
+    const entry = state.pool[name] ?? { status: 'unknown', allocatedAt: null, alias: null }
+    const agent = agentMap[name]
+    return {
+      name,
+      alias: entry.alias ?? '-',
+      status: entry.status,
+      process: entry.status === 'occupied'
+        ? (agent.running ? `running (pid ${agent.pid})` : 'stopped')
+        : '-',
+      allocatedAt: entry.allocatedAt ?? '-',
+    }
+  })
+  const cols = {
+    name:        Math.max(4,  ...rows.map(r => r.name.length)),
+    alias:       Math.max(5,  ...rows.map(r => r.alias.length)),
+    status:      Math.max(6,  ...rows.map(r => r.status.length)),
+    process:     Math.max(7,  ...rows.map(r => r.process.length)),
+    allocatedAt: Math.max(12, ...rows.map(r => r.allocatedAt.length)),
+  }
+  const fmt = r =>
+    r.name.padEnd(cols.name) + '  ' + r.alias.padEnd(cols.alias) + '  ' +
+    r.status.padEnd(cols.status) + '  ' + r.process.padEnd(cols.process) + '  ' + r.allocatedAt
+  console.log(
+    'NAME'.padEnd(cols.name) + '  ' + 'ALIAS'.padEnd(cols.alias) + '  ' +
+    'STATUS'.padEnd(cols.status) + '  ' + 'PROCESS'.padEnd(cols.process) + '  ' + 'ALLOCATED AT'
+  )
+  console.log('-'.repeat(cols.name + cols.alias + cols.status + cols.process + cols.allocatedAt + 8))
+  for (const row of rows) console.log(fmt(row))
+  const selected = getSelected()
+  console.log()
+  console.log(selected ? `Selected: ${selected}` : 'Selected: (none)')
+
+// mount
+} else if (cmd === 'mount') {
+  const isCommon = args[0] === '-C'
+  let target, linkPath
+  if (isCommon) {
+    linkPath = args[1]
+    if (!linkPath) die('Usage: geniejars mount -C <linkpath>')
+    if (!config.commonDir) die('commonDir not set in config')
+    target = config.commonDir
+  } else {
+    const selected = getSelected()
+    let nameOrAlias, lp
+    if (selected && args.length === 1) {
+      nameOrAlias = selected
+      lp = args[0]
+    } else {
+      ;[nameOrAlias, lp] = args
+    }
+    if (!nameOrAlias || !lp) die('Usage: geniejars mount [name] <linkpath>')
+    const state = await readState(config)
+    const name = resolveName(state, nameOrAlias)
+    target = homeDir(config, name)
+    linkPath = lp
+  }
+  const link = path.resolve(linkPath)
+  try {
+    await fs.symlink(target, link)
+    console.log(`Mounted: ${link} -> ${target}`)
+  } catch (err) { die(err.message) }
+
+// unmount
+} else if (cmd === 'unmount') {
+  const [linkPath] = args
+  if (!linkPath) die('Usage: geniejars unmount <linkpath>')
+  const link = path.resolve(linkPath)
+  try {
+    const stat = await fs.lstat(link)
+    if (!stat.isSymbolicLink()) die(`${link} is not a symlink`)
+    await fs.unlink(link)
+    console.log(`Unmounted: ${link}`)
+  } catch (err) { die(err.message) }
+
+// select
+} else if (cmd === 'select') {
+  const [nameOrAlias] = args
+  if (!nameOrAlias) die('Usage: geniejars select <name|alias>')
+  const state = await readState(config)
+  const name = resolveName(state, nameOrAlias)
+  if (state.pool[name]?.status !== 'occupied') die(`${name} is not allocated`)
+  await setSelected(name)
+  console.log(`Selected: ${name}`)
+
+// unselect
+} else if (cmd === 'unselect') {
+  await clearSelected()
+  console.log('Selection cleared')
+
+} else if (cmd === 'readme') {
+  const readmePath = path.resolve(__dirname, '../README.md')
+  const child = spawn('more', [readmePath], { stdio: 'inherit' })
+  child.on('exit', code => process.exit(code ?? 0))
+
+} else if (cmd === 'common-issues') {
+  const issuePath = path.resolve(__dirname, '../COMMON-ISSUES.md')
+  const child = spawn('more', [issuePath], { stdio: 'inherit' })
+  child.on('exit', code => process.exit(code ?? 0))
+
+} else {
+  die(`Unknown command: ${cmd}. Run: geniejars help`)
+}