@rashidee/co2 1.3.10 → 1.3.12

package/plugin/skills/util-gencicdscript/references/cicd-app-template.md

@@ -1,689 +1,798 @@
-# CI/CD App Template
-
-`cicd/app/server.js` — generic; reads `cicd.config.json`. Copy verbatim.
-
-```js
-// Generated by util-gencicdscript — zero-dependency CI/CD build/run/deploy app.
-// Env (set by Compound Context Studio at spawn): PORT, CO2_STUDIO_URL, CO2_PROJECT_ID,
-// CO2_GUARD_TOKEN. Bare page — designed to be embedded in the studio as an iframe.
-// One nav tab per application; the tab body streams that application's log live over a
-// hand-rolled WebSocket (server→client push only). Memory safety: logs live on disk, the
-// server retains nothing per subscriber beyond the socket itself (bounded initial tail,
-// slow clients are dropped on backpressure), and the client trims its DOM log buffer.
-const http = require('node:http')
-const net = require('node:net')
-const { spawn, execFileSync } = require('node:child_process')
-const { createHash } = require('node:crypto')
-const { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, openSync, readSync, closeSync, createWriteStream } = require('node:fs')
-const { join, resolve } = require('node:path')
-
-const APP_DIR = __dirname
-const PROJECT_DIR = resolve(APP_DIR, '..', '..')
-const LOG_DIR = join(PROJECT_DIR, 'cicd', 'logs')
-const STATE_FILE = join(PROJECT_DIR, 'cicd', 'state.json')
-const CONFIG_PATH = join(APP_DIR, 'cicd.config.json')
-// Config is re-read on demand (mtime-cached), so a regenerated plan — corrected build/start
-// commands, renamed artifacts, added apps or changed infra — is picked up WITHOUT restarting
-// this app. Only the listen PORT is bound once at boot (a port change still needs a respawn).
-let configCache = { mtimeMs: -1, data: { port: 4100, apps: [], infra: [] } }
-function loadConfig() {
-  try {
-    const mtimeMs = statSync(CONFIG_PATH).mtimeMs
-    if (mtimeMs !== configCache.mtimeMs) {
-      configCache = { mtimeMs, data: JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) }
-    }
-  } catch {
-    /* unreadable or mid-write — keep the last good config */
-  }
-  return configCache.data
-}
-const PORT = Number(process.env.PORT || loadConfig().port || 4100)
-const STUDIO = process.env.CO2_STUDIO_URL || 'http://127.0.0.1:3001'
-const PROJECT_ID = process.env.CO2_PROJECT_ID || ''
-const TOKEN = process.env.CO2_GUARD_TOKEN || ''
-
-mkdirSync(LOG_DIR, { recursive: true })
-const running = new Map() // app name -> ChildProcess (only processes THIS app spawned)
-const activity = new Map() // app name -> 'building' | 'deploying' (transient, exclusive)
-const failed = new Map() // app name -> true after a nonzero run exit
-const stopping = new Set() // app names whose exit was requested — not a failure
-const lastError = new Map() // app name -> string
-
-function saveState() {
-  const s = {}
-  for (const a of loadConfig().apps) s[a.name] = running.has(a.name) ? 'running' : 'stopped'
-  try { writeFileSync(STATE_FILE, JSON.stringify(s)) } catch {}
-}
-
-function currentBranch() {
-  try {
-    return execFileSync('git', ['branch', '--show-current'], { cwd: PROJECT_DIR }).toString().trim()
-  } catch { return null }
-}
-
-// ---- Develop gate (Compound Context Studio) --------------------------------------------
-// An application that never completed a conductor-develop run has nothing to build or run —
-// its tab controls are disabled. Refreshed every 30 s; the last known answer is kept when the
-// studio is briefly unreachable, and `null` (never fetched) disables controls with a hint.
-let guardApps = null // Map lower(name|folder) -> developedOnce
-async function refreshGuard() {
-  if (!PROJECT_ID) return
-  try {
-    const r = await fetch(`${STUDIO}/api/cicd-guard/${PROJECT_ID}?token=${TOKEN}`, { signal: AbortSignal.timeout(3000) })
-    if (!r.ok) return
-    const g = await r.json()
-    if (Array.isArray(g.applications)) {
-      guardApps = new Map()
-      for (const a of g.applications) guardApps.set(String(a.name).toLowerCase(), !!a.developedOnce)
-    }
-  } catch {}
-}
-function developedOnce(app) {
-  if (!guardApps) return null // unknown — controls stay disabled until the studio answers
-  const byName = guardApps.get(app.name.toLowerCase())
-  if (byName !== undefined) return byName
-  const byFolder = guardApps.get(String(app.folder || '').toLowerCase())
-  return byFolder === undefined ? null : byFolder
-}
-refreshGuard()
-setInterval(refreshGuard, 30_000).unref?.()
-
-// ---- Log streaming ---------------------------------------------------------------------
-// One log file per application (build + run + deploy share it — the tab is one stream).
-// Subscribers get a bounded tail on connect, then live appends; nothing is buffered
-// server-side, and a subscriber that cannot keep up is dropped instead of queuing forever.
-const subscribers = new Map() // app name -> Set<net.Socket>
-const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
-
-function wsFrame(data) {
-  const payload = Buffer.from(data)
-  const len = payload.length
-  let header
-  if (len < 126) header = Buffer.from([0x81, len])
-  else if (len < 65_536) { header = Buffer.alloc(4); header[0] = 0x81; header[1] = 126; header.writeUInt16BE(len, 2) }
-  else { header = Buffer.alloc(10); header[0] = 0x81; header[1] = 127; header.writeBigUInt64BE(BigInt(len), 2) }
-  return Buffer.concat([header, payload])
-}
-
-function broadcast(name, chunk) {
-  const subs = subscribers.get(name)
-  if (!subs || subs.size === 0) return
-  const frame = wsFrame(chunk)
-  for (const s of subs) {
-    if (s.writableLength > 1_000_000) { subs.delete(s); try { s.destroy() } catch {} ; continue }
-    s.write(frame)
-  }
-}
-
-function logPath(name) { return join(LOG_DIR, `${name}.log`) }
-
-function logTail(name, bytes = 16_384) {
-  try {
-    const p = logPath(name)
-    const size = statSync(p).size
-    const start = Math.max(0, size - bytes)
-    const buf = Buffer.alloc(size - start)
-    const fd = openSync(p, 'r')
-    readSync(fd, buf, 0, buf.length, start)
-    closeSync(fd)
-    return buf.toString('utf8')
-  } catch { return '' }
-}
-
-function logLine(app, text) {
-  const line = `\n--- ${new Date().toISOString()} ${text}\n`
-  try { createWriteStream(logPath(app.name), { flags: 'a' }).end(line) } catch {}
-  broadcast(app.name, line)
-}
-
-function runLogged(app, command, onExit) {
-  const log = createWriteStream(logPath(app.name), { flags: 'a' })
-  log.write(`\n--- ${new Date().toISOString()} $ ${command}\n`)
-  broadcast(app.name, `\n--- ${new Date().toISOString()} $ ${command}\n`)
-  const child = spawn(command, { cwd: join(PROJECT_DIR, app.folder), shell: true, env: process.env })
-  const tap = (d) => { log.write(d); broadcast(app.name, d) }
-  child.stdout.on('data', tap)
-  child.stderr.on('data', tap)
-  child.on('exit', (code) => { log.end(); onExit(code) })
-  return child
-}
-
-// ---- Application config (runtime .env etc.) --------------------------------------------
-// Each app declares the config files its start command reads (inferred by util-plancicd from
-// ENVIRONMENT.md or an existing .env/.env-* file). A `managed` file carries the plan's resolved
-// content and is materialized into the application folder before Build/Start when it is missing —
-// so an application always starts with COMPLETE configuration. The Config modal shows every file's
-// live on-disk content for troubleshooting. Paths are relative to the application folder.
-const MAX_CONFIG_BYTES = 200_000
-function configAbsPath(app, cfg) { return join(PROJECT_DIR, app.folder, cfg.path) }
-function ensureConfigs(app) {
-  for (const cfg of app.configs || []) {
-    if (!cfg.managed || cfg.content == null) continue // env-file configs are used as-is on disk
-    const abs = configAbsPath(app, cfg)
-    if (existsSync(abs)) continue // never overwrite a config already on disk
-    try {
-      mkdirSync(join(abs, '..'), { recursive: true })
-      writeFileSync(abs, cfg.content)
-      logLine(app, `config: wrote ${cfg.path} from the plan (was missing)`)
-    } catch (e) {
-      logLine(app, `config: FAILED to write ${cfg.path} — ${e.message}`)
-    }
-  }
-}
-function readConfig(app, cfg) {
-  const abs = configAbsPath(app, cfg)
-  let exists = false, content = ''
-  try {
-    if (existsSync(abs)) {
-      exists = true
-      const buf = readFileSync(abs)
-      content = buf.length > MAX_CONFIG_BYTES
-        ? buf.slice(0, MAX_CONFIG_BYTES).toString('utf8') + '\n… (truncated)'
-        : buf.toString('utf8')
-    } else if (cfg.managed && cfg.content != null) {
-      content = cfg.content // planned content — not yet written to disk
-    }
-  } catch (e) { content = `(unreadable: ${e.message})` }
-  return {
-    path: cfg.path, label: cfg.label || cfg.path, source: cfg.source || 'env-file',
-    managed: !!cfg.managed, keys: cfg.keys || [], note: cfg.note || '', exists, content,
-  }
-}
-
-// ---- App lifecycle ---------------------------------------------------------------------
-// Candidate loopback hosts to check for liveness: IPv4 (127.0.0.1) AND IPv6 (::1) loopback
-// always, plus whatever host the plan's health URL names. Frameworks bind different families —
-// Spring Boot listens on 127.0.0.1, but Vite/Next preview dev servers bind IPv6 ::1 only — so
-// probing a single family misses half of them. `localhost` in a health URL is included as-is
-// and resolved by the OS.
-function probeHosts(app) {
-  const hosts = new Set(['127.0.0.1', '::1'])
-  try { if (app.health) hosts.add(new URL(app.health).hostname) } catch {}
-  return [...hosts]
-}
-// Liveness = a raw TCP connect to the app's listen port on ANY candidate host, NOT an HTTP
-// fetch of a health URL. A listening port means the app is up regardless of auth (Spring
-// Security 401s), path (actuator disabled), or protocol — and it is reliable where Node's fetch
-// is not (undici can stall on localhost keep-alive and time out against a server curl reaches
-// in 20 ms). This also detects apps started outside this CI/CD app, so their state shows right.
-async function probe(app) {
-  const results = await Promise.all(probeHosts(app).map((h) => tcpProbe(h, app.port, 800)))
-  return results.some(Boolean)
-}
-
-// Infrastructure reachability — a raw TCP connect, so it works for non-HTTP services
-// (PostgreSQL, Redis) as well as web consoles. Status-only: infra is never controlled here.
-function tcpProbe(host, port, timeout = 1000) {
-  return new Promise((resolve) => {
-    const socket = new net.Socket()
-    let done = false
-    const finish = (ok) => { if (done) return; done = true; try { socket.destroy() } catch {} ; resolve(ok) }
-    socket.setTimeout(timeout)
-    socket.once('connect', () => finish(true))
-    socket.once('timeout', () => finish(false))
-    socket.once('error', () => finish(false))
-    try { socket.connect(Number(port), host || '127.0.0.1') } catch { finish(false) }
-  })
-}
-
-function buildApp(app) {
-  if (activity.has(app.name)) return
-  activity.set(app.name, 'building'); lastError.delete(app.name)
-  ensureConfigs(app)
-  runLogged(app, app.build, (code) => {
-    activity.delete(app.name)
-    if (code !== 0) lastError.set(app.name, `build exited ${code} — see log`)
-    else logLine(app, 'build OK')
-  })
-}
-
-function deployApp(app) {
-  if (activity.has(app.name) || !app.deploy) return
-  activity.set(app.name, 'deploying'); lastError.delete(app.name)
-  runLogged(app, app.deploy, (code) => {
-    activity.delete(app.name)
-    if (code !== 0) lastError.set(app.name, `deploy exited ${code} — see log`)
-    else logLine(app, `deploy OK (${app.deployMethod})`)
-  })
-}
-
-function startApp(app) {
-  if (running.get(app.name) || activity.has(app.name)) return
-  failed.delete(app.name); lastError.delete(app.name)
-  ensureConfigs(app)
-  if (app.method === 'container') {
-    runLogged(app, app.start, () => {})
-    saveState(); return
-  }
-  const child = runLogged(app, app.start, (code) => {
-    running.delete(app.name)
-    // A user-requested Stop exits nonzero (killed) — that is not a failure.
-    if (code !== 0 && !stopping.delete(app.name)) {
-      failed.set(app.name, true)
-      lastError.set(app.name, `process exited ${code} — see log`)
-    } else stopping.delete(app.name)
-    saveState()
-  })
-  running.set(app.name, child)
-  saveState()
-}
-
-// shell:true spawns a shell whose grandchildren survive child.kill() on Windows — kill the
-// whole tree there (taskkill /T); plain kill elsewhere.
-function killTree(child) {
-  if (process.platform === 'win32' && child.pid) {
-    try { execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }) } catch {}
-  } else {
-    try { child.kill() } catch {}
-  }
-}
-
-// Stop an app we DON'T hold a child handle for (started outside this app, or before this app
-// last restarted) by killing whatever process tree is listening on its port — so Stop works
-// for any running app, not only ones this CI/CD app spawned. Returns true if a PID was killed.
-function killByPort(port) {
-  try {
-    if (process.platform === 'win32') {
-      const out = execFileSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' })
-      const pids = new Set()
-      for (const line of out.split(/\r?\n/)) {
-        const m = line.match(/:(\d+)\s+\S+\s+LISTENING\s+(\d+)/)
-        if (m && Number(m[1]) === Number(port)) pids.add(m[2])
-      }
-      for (const pid of pids) {
-        try { execFileSync('taskkill', ['/pid', pid, '/T', '/F'], { stdio: 'ignore' }) } catch {}
-      }
-      return pids.size > 0
-    }
-    const out = execFileSync('sh', ['-c', `lsof -ti tcp:${port} || true`], { encoding: 'utf8' })
-    const pids = out.split(/\s+/).filter(Boolean)
-    for (const pid of pids) { try { process.kill(Number(pid)) } catch {} }
-    return pids.length > 0
-  } catch { return false }
-}
-
-function stopApp(app) {
-  if (app.method === 'container' && app.stop && app.stop !== 'process-kill') {
-    try { execFileSync(app.stop.split(' ')[0], app.stop.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
-  } else {
-    const child = running.get(app.name)
-    if (child) {
-      stopping.add(app.name)
-      killTree(child)
-    } else {
-      // No child handle — kill by port so an externally/previously started app still stops.
-      lastError.delete(app.name)
-      if (!killByPort(app.port)) {
-        lastError.set(app.name, `could not stop — nothing found listening on port ${app.port}`)
-      }
-    }
-  }
-  running.delete(app.name)
-  saveState()
-}
-
-function json(res, code, body) {
-  res.writeHead(code, { 'content-type': 'application/json' })
-  res.end(JSON.stringify(body))
-}
-
-// ---- Page ------------------------------------------------------------------------------
-const PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>CI/CD</title><style>
-body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;display:flex;flex-direction:column;height:100vh}
-.top{display:flex;gap:8px;align-items:center;padding:10px 12px 6px;font-size:13px}
-.meta{font-size:11px;color:#5b6572}
-.tabs{display:flex;gap:2px;padding:0 12px;border-bottom:1px solid #d9dee5;flex-wrap:wrap}
-.tab{border:1px solid #d9dee5;border-bottom:none;border-radius:8px 8px 0 0;background:#eef1f5;padding:6px 14px;font-size:13px;cursor:pointer;display:flex;gap:6px;align-items:center}
-.tab.active{background:#fff;font-weight:600}
-.tab .dot{width:8px;height:8px;border-radius:99px;background:#8a94a0}
-.dot.running{background:#1c8a4a}.dot.failed{background:#c23b3b}.dot.building,.dot.deploying{background:#c9922a}
-.bar{display:flex;gap:8px;align-items:center;padding:10px 12px;background:#fff;border-bottom:1px solid #e1e5ea;flex-wrap:wrap}
-.badge{font-size:10px;text-transform:uppercase;border-radius:99px;padding:2px 8px;color:#fff;background:#8a94a0}
-.badge.running{background:#1c8a4a}.badge.failed{background:#c23b3b}.badge.building,.badge.deploying{background:#c9922a}
-.url{font-size:12px;color:#1a66d0;text-decoration:underline;word-break:break-all}
-button{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:4px 12px;font-size:12px;cursor:pointer}
-button:hover:enabled{background:#eef1f5}
-button:disabled{opacity:.4;cursor:default}
-.notice{padding:4px 12px;font-size:11px;color:#8a5a00;background:#fff7e6;display:none}
-.err{padding:4px 12px;font-size:11px;color:#c23b3b;display:none;white-space:pre-wrap}
-#log{flex:1;margin:0;padding:10px 12px;background:#0f1216;color:#d7dde4;font-size:11px;line-height:1.5;overflow:auto;white-space:pre-wrap}
-.muted{color:#5b6572;font-size:12px}
-.modal{position:fixed;inset:0;background:rgba(0,0,0,.45);display:none;align-items:center;justify-content:center;padding:24px;z-index:20}
-.modal.open{display:flex}
-.modal-panel{background:#fff;border-radius:10px;max-width:920px;width:100%;max-height:85vh;display:flex;flex-direction:column;overflow:hidden;box-shadow:0 10px 40px rgba(0,0,0,.3)}
-.modal-head{display:flex;align-items:center;gap:8px;padding:10px 14px;border-bottom:1px solid #e1e5ea;font-size:13px}
-.modal-body{padding:12px 14px;overflow:auto}
-.cfg{margin-bottom:16px}
-.cfg h3{font-size:13px;margin:0 0 4px;display:flex;gap:8px;align-items:center}
-.cfg .src{font-size:10px;text-transform:uppercase;border-radius:99px;padding:2px 8px;background:#eef1f5;color:#5b6572}
-.cfg .miss{color:#c23b3b;font-weight:600}
-.cfg .ok{color:#1c8a4a;font-weight:600}
-.cfg .keys{font-size:11px;color:#5b6572;margin:2px 0}
-.cfg pre{background:#0f1216;color:#d7dde4;font-size:11px;padding:8px 10px;border-radius:6px;overflow:auto;max-height:320px;white-space:pre-wrap;margin:4px 0 0}
-</style></head><body>
-<div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span><span style="flex:1"></span><a id="infralink" class="url" href="/infra" target="_blank" rel="noreferrer" style="display:none">Infrastructure ↗</a></div>
-<div class="tabs" id="tabs"></div>
-<div class="bar" id="bar"></div>
-<div class="notice" id="notice"></div>
-<div class="err" id="err"></div>
-<pre id="log"></pre>
-<div class="modal" id="cfgModal" onclick="if(event.target===this)closeConfig()">
-  <div class="modal-panel">
-    <div class="modal-head"><strong id="cfgTitle">Configuration</strong><span style="flex:1"></span><button onclick="closeConfig()">Close</button></div>
-    <div class="modal-body" id="cfgBody"></div>
-  </div>
-</div>
-<script>
-function esc(s){ return String(s==null?'':s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])) }
-let state = { apps: [] }
-let active = null
-let ws = null, wsTimer = null
-
-function appOf(name){ return state.apps.find(a => a.name === name) }
-
-function renderTabs(){
-  document.getElementById('tabs').innerHTML = state.apps.map(a => \`
-    <div class="tab \${a.name===active?'active':''}" onclick="setActive('\${a.name}')">
-      <span class="dot \${a.phase}"></span>\${a.name}\${a.developedOnce===false?' 🔒':''}</div>\`).join('')
-}
-
-function renderBar(){
-  const a = appOf(active)
-  if (!a) return
-  const url = 'http://'+location.hostname+':'+a.port+'/'
-  const gate = a.developedOnce === true
-  const busy = a.phase==='building'||a.phase==='deploying'
-  document.getElementById('bar').innerHTML = \`
-    <span class="badge \${a.phase}">\${a.phase}\${a.external?' (external)':''}</span>
-    <span class="meta">\${a.method} · port \${a.port}</span>
-    <a class="url" href="\${url}" target="_blank" rel="noreferrer">\${url}</a>
-    <span style="flex:1"></span>
-    <button onclick="openConfig()" title="Show this application's runtime configuration files">Config</button>
-    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''}>Build</button>
-    <button onclick="act('start')" \${!gate||busy||a.phase==='running'?'disabled':''}>Start</button>
-    <button onclick="act('stop')" \${a.phase!=='running'?'disabled':''}>Stop</button>
-    \${a.deploy?\`<button onclick="act('deploy')" \${!gate||busy?'disabled':''}>Deploy (\${a.deployMethod})</button>\`:''}\`
-  const notice = document.getElementById('notice')
-  if (a.developedOnce === false) {
-    notice.textContent = 'This application has not been developed through the workflow yet — run conductor-feature-develop first.'
-    notice.style.display = 'block'
-  } else if (a.developedOnce === null) {
-    notice.textContent = 'Develop status not verified yet (studio unreachable) — controls stay disabled.'
-    notice.style.display = 'block'
-  } else notice.style.display = 'none'
-  const err = document.getElementById('err')
-  if (a.error) { err.textContent = a.error; err.style.display = 'block' } else err.style.display = 'none'
-}
-
-function setActive(name){
-  if (active === name) return
-  active = name
-  closeWs()
-  document.getElementById('log').textContent = ''
-  openWs(name)
-  renderTabs(); renderBar()
-}
-
-// Live log stream. One socket at a time (closed on tab switch); auto-reconnect while the tab
-// stays active; the DOM buffer is trimmed so long sessions never grow the page unbounded.
-function openWs(name){
-  ws = new WebSocket('ws://'+location.host+'/ws?app='+encodeURIComponent(name))
-  ws.onmessage = e => appendLog(e.data)
-  ws.onclose = () => { ws = null; if (active === name) wsTimer = setTimeout(() => openWs(name), 2000) }
-}
-function closeWs(){
-  if (wsTimer) { clearTimeout(wsTimer); wsTimer = null }
-  if (ws) { ws.onclose = null; try { ws.close() } catch {} ws = null }
-}
-function appendLog(text){
-  const el = document.getElementById('log')
-  const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 40
-  el.textContent += text
-  if (el.textContent.length > 400000) el.textContent = el.textContent.slice(-250000)
-  if (atBottom) el.scrollTop = el.scrollHeight
-}
-
-// Config modal — the runtime config files this application needs to start (from the plan). Shows
-// each file's live on-disk content (or the planned content when a managed file is not yet written),
-// its source (environment / env-file / derived), required keys and present/MISSING status — so the
-// user can troubleshoot a start-up that is failing for want of complete configuration.
-async function openConfig(){
-  if (!active) return
-  const modal = document.getElementById('cfgModal')
-  document.getElementById('cfgTitle').textContent = 'Configuration — '+active
-  document.getElementById('cfgBody').innerHTML = '<div class="muted">Loading…</div>'
-  modal.classList.add('open')
-  const s = await fetch('/api/apps/'+encodeURIComponent(active)+'/config').then(r=>r.json()).catch(()=>null)
-  const configs = (s && s.configs) || []
-  document.getElementById('cfgBody').innerHTML = configs.length ? configs.map(c => \`
-    <div class="cfg">
-      <h3>\${esc(c.label)} <span class="src">\${esc(c.source)}</span>
-        \${c.exists ? '<span class="ok">present</span>' : '<span class="miss">MISSING'+(c.managed&&c.content?' — created on Build/Start':'')+'</span>'}</h3>
-      \${c.keys&&c.keys.length ? '<div class="keys">Required keys: '+c.keys.map(esc).join(', ')+'</div>' : ''}
-      \${c.note ? '<div class="keys">'+esc(c.note)+'</div>' : ''}
-      <pre>\${esc(c.content) || '(empty)'}</pre>
-    </div>\`).join('') : '<div class="muted">No runtime configuration declared for this application.</div>'
-}
-function closeConfig(){ document.getElementById('cfgModal').classList.remove('open') }
-document.addEventListener('keydown', e => { if (e.key === 'Escape') closeConfig() })
-
-async function refresh(){
-  const s = await fetch('/api/state').then(r => r.json()).catch(() => null)
-  if (!s) return
-  state = s
-  document.getElementById('branch').textContent = s.currentBranch ? 'branch: '+s.currentBranch : ''
-  document.getElementById('infralink').style.display = s.hasInfra ? 'inline' : 'none'
-  if (!active && s.apps.length) setActive(s.apps[0].name)
-  renderTabs(); renderBar()
-}
-async function act(op){
-  await fetch('/api/apps/'+encodeURIComponent(active)+'/'+op, { method: 'POST' })
-  refresh()
-}
-// Rescan immediately when the user returns to this page (tab focus / regained visibility), so
-// coming back from another screen reflects the true app + infra state without waiting the poll.
-document.addEventListener('visibilitychange', () => { if (!document.hidden) refresh() })
-window.addEventListener('focus', refresh)
-refresh(); setInterval(refresh, 3000)
-</script></body></html>`
-
-// ---- Infrastructure page ---------------------------------------------------------------
-// Standalone status-only page (opened in a new tab from the main page's Infrastructure link).
-// Lists every supporting 3rd-party service with a live TCP-reachability dot and a console link
-// when the service exposes a web UI. No lifecycle controls — infra is externally managed.
-const INFRA_PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>Infrastructure</title><style>
-body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;padding:16px}
-h1{font-size:16px;margin:0 0 12px}
-table{border-collapse:collapse;width:100%;max-width:820px;font-size:13px}
-th,td{text-align:left;padding:8px 10px;border-bottom:1px solid #e1e5ea}
-th{font-size:11px;text-transform:uppercase;color:#5b6572}
-.dot{display:inline-block;width:9px;height:9px;border-radius:99px;background:#8a94a0;margin-right:6px;vertical-align:middle}
-.dot.up{background:#1c8a4a}.dot.down{background:#c23b3b}
-.url{color:#1a66d0;text-decoration:underline}
-.muted{color:#5b6572;font-size:12px}
-.legend{margin-top:12px;font-size:11px;color:#5b6572}
-</style></head><body>
-<h1>Infrastructure</h1>
-<table><thead><tr><th>Status</th><th>Service</th><th>Endpoint</th><th>Console</th></tr></thead>
-<tbody id="rows"><tr><td colspan="4" class="muted">Loading…</td></tr></tbody></table>
-<div class="legend">● up ○ down — TCP reachability, polled every 3s</div>
-<script>
-function esc(s){ return String(s==null?'':s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])) }
-async function refresh(){
-  const s = await fetch('/api/infra').then(r=>r.json()).catch(()=>null)
-  if(!s) return
-  const rows = (s.infra||[]).map(i => \`
-    <tr>
-      <td><span class="dot \${i.up?'up':'down'}"></span>\${i.up?'up':'down'}</td>
-      <td>\${esc(i.name)}\${i.description?' <span class="muted">— '+esc(i.description)+'</span>':''}</td>
-      <td class="muted">\${esc(i.host)}:\${esc(i.port)}</td>
-      <td>\${i.url?'<a class="url" href="'+esc(i.url)+'" target="_blank" rel="noreferrer">open ↗</a>':'—'}</td>
-    </tr>\`).join('')
-  document.getElementById('rows').innerHTML = rows || '<tr><td colspan="4" class="muted">No infrastructure declared.</td></tr>'
-}
-// Rescan immediately when the user returns to this page (tab focus / regained visibility), so
-// coming back from another screen reflects the true app + infra state without waiting the poll.
-document.addEventListener('visibilitychange', () => { if (!document.hidden) refresh() })
-window.addEventListener('focus', refresh)
-refresh(); setInterval(refresh, 3000)
-</script></body></html>`
-
-// ---- HTTP ------------------------------------------------------------------------------
-const server = http.createServer(async (req, res) => {
-  if (req.method === 'GET' && req.url === '/') {
-    res.writeHead(200, { 'content-type': 'text/html' })
-    return res.end(PAGE)
-  }
-  if (req.method === 'GET' && req.url === '/infra') {
-    res.writeHead(200, { 'content-type': 'text/html' })
-    return res.end(INFRA_PAGE)
-  }
-  if (req.method === 'GET' && req.url === '/api/infra') {
-    const infra = await Promise.all((loadConfig().infra || []).map(async (i) => ({
-      id: i.id, name: i.name, host: i.host || '127.0.0.1', port: i.port,
-      url: i.url || null, description: i.description || '',
-      up: await tcpProbe(i.host || '127.0.0.1', i.port),
-    })))
-    return json(res, 200, { infra })
-  }
-  if (req.method === 'GET' && req.url === '/api/state') {
-    const apps = await Promise.all(loadConfig().apps.map(async (a) => {
-      const healthy = await probe(a)
-      const phase = activity.get(a.name) || (healthy ? 'running' : failed.has(a.name) ? 'failed' : 'stopped')
-      return {
-        name: a.name, method: a.method, port: a.port, phase,
-        deploy: !!a.deploy, deployMethod: a.deployMethod || 'none',
-        external: healthy && !running.has(a.name),
-        developedOnce: developedOnce(a),
-        error: lastError.get(a.name) || null,
-      }
-    }))
-    return json(res, 200, { currentBranch: currentBranch(), hasInfra: (loadConfig().infra || []).length > 0, apps })
-  }
-  const cfgm = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/config$/)
-  if (cfgm && req.method === 'GET') {
-    const app = loadConfig().apps.find((a) => a.name === decodeURIComponent(cfgm[1]))
-    if (!app) return json(res, 404, { error: 'unknown app' })
-    return json(res, 200, { configs: (app.configs || []).map((c) => readConfig(app, c)) })
-  }
-  const m = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
-  if (m && req.method === 'POST') {
-    const app = loadConfig().apps.find((a) => a.name === decodeURIComponent(m[1]))
-    if (!app) return json(res, 404, { error: 'unknown app' })
-    if (m[2] !== 'stop' && developedOnce(app) === false) {
-      return json(res, 409, { error: 'application has not completed a develop workflow run' })
-    }
-    if (m[2] === 'build') buildApp(app)
-    else if (m[2] === 'start') startApp(app)
-    else if (m[2] === 'deploy') deployApp(app)
-    else stopApp(app)
-    return json(res, 200, { ok: true })
-  }
-  json(res, 404, { error: 'not found' })
-})
-
-// WebSocket endpoint /ws?app=<name> — push-only log stream (see "Log streaming" above).
-server.on('upgrade', (req, socket) => {
-  let name = ''
-  let isWsPath = false
-  try {
-    const url = new URL(req.url, 'http://x')
-    isWsPath = url.pathname === '/ws'
-    name = url.searchParams.get('app') || ''
-  } catch {}
-  const key = req.headers['sec-websocket-key']
-  const app = loadConfig().apps.find((a) => a.name === name)
-  if (!app || !key || !isWsPath) { socket.destroy(); return }
-  const accept = createHash('sha1').update(key + WS_GUID).digest('base64')
-  socket.write(
-    'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
-    `Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
-  )
-  let subs = subscribers.get(name)
-  if (!subs) { subs = new Set(); subscribers.set(name, subs) }
-  subs.add(socket)
-  const cleanup = () => { subs.delete(socket); try { socket.destroy() } catch {} }
-  socket.on('close', cleanup)
-  socket.on('error', cleanup)
-  // Client frames are only ever close (0x8) — anything else is ignored, never buffered.
-  socket.on('data', (buf) => { if ((buf[0] & 0x0f) === 0x8) cleanup() })
-  socket.write(wsFrame(logTail(name)))
-})
-
-server.listen(PORT, () => console.log(`cicd app on :${PORT}`))
-```
-
-`cicd/app/cicd.config.json` shape — one `apps` entry per application from the plan's Deployment
-Decisions table, one `infra` entry per row of the plan's `## Infrastructure` table.
-`deployMethod`/`deploy` come from the plan's Deploy columns (`deploy` is `null` when the method
-is `none`). `infra[].url` is `null` for a headless service (Console URL cell `-`); emit
-`"infra": []` when the plan declares no supporting services.
-
-Each app also carries a `configs` array — the runtime config files the application reads at start,
-from the plan's `## Application Configs` section (one entry per file). Fields:
-`path` (relative to the application folder), `label`, `source` (`environment` | `env-file` |
-`derived`), `managed` (when `true` the server writes `content` to `path` before Build/Start if the
-file is missing, so start-up always has complete config), `keys` (the required keys the app needs
-to boot), `note`, and `content` (the plan's resolved file body when `managed`; `null`/omitted for an
-`env-file` used as-is on disk). Emit `"configs": []` when an application needs no runtime config
-file. NEVER omit a `managed.content` that the plan resolved — that body is what guarantees the app
-starts configured. Per the dev-environment plaintext rule, `content` may include credentials
-verbatim (this is a local dev CI/CD app).
-
-```json
-{
-  "port": 4100,
-  "apps": [
-    {
-      "name": "my-app",
-      "folder": "my-app",
-      "method": "process",
-      "port": 3000,
-      "build": "pnpm install && pnpm build",
-      "start": "node dist/index.js",
-      "stop": "process-kill",
-      "deployMethod": "kubernetes",
-      "deploy": "kubectl apply -f my-app/k8s/",
-      "health": "http://127.0.0.1:3000/",
-      "configs": [
-        {
-          "path": ".env",
-          "label": ".env (runtime)",
-          "source": "environment",
-          "managed": true,
-          "keys": ["DATABASE_URL", "REDIS_HOST", "PORT"],
-          "note": "Resolved from ENVIRONMENT.md → my-app section",
-          "content": "DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb\nREDIS_HOST=127.0.0.1\nPORT=3000\n"
-        },
-        {
-          "path": ".env-uat",
-          "label": ".env-uat (existing)",
-          "source": "env-file",
-          "managed": false,
-          "keys": ["DATABASE_URL", "REDIS_HOST"],
-          "note": "Existing env file in the app folder — used as-is",
-          "content": null
-        }
-      ]
-    }
-  ],
-  "infra": [
-    {
-      "id": "postgres-main",
-      "name": "PostgreSQL (app db)",
-      "host": "127.0.0.1",
-      "port": 5432,
-      "url": null,
-      "description": "Shared application database"
-    },
-    {
-      "id": "keycloak",
-      "name": "Keycloak",
-      "host": "127.0.0.1",
-      "port": 8180,
-      "url": "http://127.0.0.1:8180",
-      "description": "Single sign-on"
-    }
-  ]
-}
-```
+# CI/CD App Template
+
+`cicd/app/server.js` — generic; reads `cicd.config.json`. Copy verbatim.
+
+```js
+// Generated by util-gencicdscript — zero-dependency CI/CD build/run/deploy app.
+// Env (set by Compound Context Studio at spawn): PORT, CO2_STUDIO_URL, CO2_PROJECT_ID,
+// CO2_GUARD_TOKEN. Bare page — designed to be embedded in the studio as an iframe.
+// One nav tab per application; the tab body streams that application's log live over a
+// hand-rolled WebSocket (server→client push only). Memory safety: logs live on disk, the
+// server retains nothing per subscriber beyond the socket itself (bounded initial tail,
+// slow clients are dropped on backpressure), and the client trims its DOM log buffer.
+const http = require('node:http')
+const net = require('node:net')
+const { spawn, execFileSync } = require('node:child_process')
+const { createHash } = require('node:crypto')
+const { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, openSync, readSync, closeSync, createWriteStream } = require('node:fs')
+const { join, resolve } = require('node:path')
+
+const APP_DIR = __dirname
+const PROJECT_DIR = resolve(APP_DIR, '..', '..')
+const LOG_DIR = join(PROJECT_DIR, 'cicd', 'logs')
+const STATE_FILE = join(PROJECT_DIR, 'cicd', 'state.json')
+const CONFIG_PATH = join(APP_DIR, 'cicd.config.json')
+// Config is re-read on demand (mtime-cached), so a regenerated plan — corrected build/start
+// commands, renamed artifacts, added apps or changed infra — is picked up WITHOUT restarting
+// this app. Only the listen PORT is bound once at boot (a port change still needs a respawn).
+let configCache = { mtimeMs: -1, data: { port: 5000, apps: [], infra: [] } }
+function loadConfig() {
+  try {
+    const mtimeMs = statSync(CONFIG_PATH).mtimeMs
+    if (mtimeMs !== configCache.mtimeMs) {
+      configCache = { mtimeMs, data: JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) }
+    }
+  } catch {
+    /* unreadable or mid-write — keep the last good config */
+  }
+  return configCache.data
+}
+const PORT = Number(process.env.PORT || loadConfig().port || 5000)
+const STUDIO = process.env.CO2_STUDIO_URL || 'http://127.0.0.1:3001'
+const PROJECT_ID = process.env.CO2_PROJECT_ID || ''
+const TOKEN = process.env.CO2_GUARD_TOKEN || ''
+
+mkdirSync(LOG_DIR, { recursive: true })
+const running = new Map() // app name -> ChildProcess (only processes THIS app spawned)
+const activity = new Map() // app name -> 'building' | 'deploying' (transient, exclusive)
+const failed = new Map() // app name -> true after a nonzero run exit
+const stopping = new Set() // app names whose exit was requested — not a failure
+const lastError = new Map() // app name -> string
+
+function saveState() {
+  const s = {}
+  for (const a of loadConfig().apps) s[a.name] = running.has(a.name) ? 'running' : 'stopped'
+  try { writeFileSync(STATE_FILE, JSON.stringify(s)) } catch {}
+}
+
+function currentBranch() {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], { cwd: PROJECT_DIR }).toString().trim()
+  } catch { return null }
+}
+
+// ---- Develop gate (Compound Context Studio) --------------------------------------------
+// An application that never completed a conductor-develop run has nothing to build or run —
+// its tab controls are disabled. Refreshed every 30 s; the last known answer is kept when the
+// studio is briefly unreachable, and `null` (never fetched) disables controls with a hint.
+let guardApps = null // Map lower(name|folder) -> developedOnce
+let guardVersions = [] // project versions (semver strings, studio order — latest first)
+async function refreshGuard() {
+  if (!PROJECT_ID) return
+  try {
+    const r = await fetch(`${STUDIO}/api/cicd-guard/${PROJECT_ID}?token=${TOKEN}`, { signal: AbortSignal.timeout(3000) })
+    if (!r.ok) return
+    const g = await r.json()
+    if (Array.isArray(g.applications)) {
+      guardApps = new Map()
+      for (const a of g.applications) guardApps.set(String(a.name).toLowerCase(), !!a.developedOnce)
+    }
+    // The topbar version selector's choices — the {VERSION} tag substituted into commands.
+    if (Array.isArray(g.versions)) guardVersions = g.versions.map((v) => String(v.semver)).filter(Boolean)
+  } catch {}
+}
+function developedOnce(app) {
+  if (!guardApps) return null // unknown — controls stay disabled until the studio answers
+  const byName = guardApps.get(app.name.toLowerCase())
+  if (byName !== undefined) return byName
+  const byFolder = guardApps.get(String(app.folder || '').toLowerCase())
+  return byFolder === undefined ? null : byFolder
+}
+refreshGuard()
+setInterval(refreshGuard, 30_000).unref?.()
+
+// ---- Log streaming ---------------------------------------------------------------------
+// One log file per application (build + run + deploy share it — the tab is one stream).
+// Subscribers get a bounded tail on connect, then live appends; nothing is buffered
+// server-side, and a subscriber that cannot keep up is dropped instead of queuing forever.
+const subscribers = new Map() // app name -> Set<net.Socket>
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+function wsFrame(data) {
+  const payload = Buffer.from(data)
+  const len = payload.length
+  let header
+  if (len < 126) header = Buffer.from([0x81, len])
+  else if (len < 65_536) { header = Buffer.alloc(4); header[0] = 0x81; header[1] = 126; header.writeUInt16BE(len, 2) }
+  else { header = Buffer.alloc(10); header[0] = 0x81; header[1] = 127; header.writeBigUInt64BE(BigInt(len), 2) }
+  return Buffer.concat([header, payload])
+}
+
+function broadcast(name, chunk) {
+  const subs = subscribers.get(name)
+  if (!subs || subs.size === 0) return
+  const frame = wsFrame(chunk)
+  for (const s of subs) {
+    if (s.writableLength > 1_000_000) { subs.delete(s); try { s.destroy() } catch {} ; continue }
+    s.write(frame)
+  }
+}
+
+function logPath(name) { return join(LOG_DIR, `${name}.log`) }
+
+function logTail(name, bytes = 16_384) {
+  try {
+    const p = logPath(name)
+    const size = statSync(p).size
+    const start = Math.max(0, size - bytes)
+    const buf = Buffer.alloc(size - start)
+    const fd = openSync(p, 'r')
+    readSync(fd, buf, 0, buf.length, start)
+    closeSync(fd)
+    return buf.toString('utf8')
+  } catch { return '' }
+}
+
+function logLine(app, text) {
+  const line = `\n--- ${new Date().toISOString()} ${text}\n`
+  try { createWriteStream(logPath(app.name), { flags: 'a' }).end(line) } catch {}
+  broadcast(app.name, line)
+}
+
+function runLogged(app, command, onExit) {
+  const log = createWriteStream(logPath(app.name), { flags: 'a' })
+  log.write(`\n--- ${new Date().toISOString()} $ ${command}\n`)
+  broadcast(app.name, `\n--- ${new Date().toISOString()} $ ${command}\n`)
+  const child = spawn(command, { cwd: join(PROJECT_DIR, app.folder), shell: true, env: process.env })
+  const tap = (d) => { log.write(d); broadcast(app.name, d) }
+  child.stdout.on('data', tap)
+  child.stderr.on('data', tap)
+  child.on('exit', (code) => { log.end(); onExit(code) })
+  return child
+}
+
+// ---- Application config (runtime .env etc.) --------------------------------------------
+// Each app declares the config files its start command reads (inferred by util-plancicd from
+// ENVIRONMENT.md or an existing .env/.env-* file). A `managed` file carries the plan's resolved
+// content and is materialized into the application folder before Build/Start when it is missing —
+// so an application always starts with COMPLETE configuration. The Config modal shows every file's
+// live on-disk content for troubleshooting. Paths are relative to the application folder.
+const MAX_CONFIG_BYTES = 200_000
+function configAbsPath(app, cfg) { return join(PROJECT_DIR, app.folder, cfg.path) }
+function ensureConfigs(app) {
+  for (const cfg of app.configs || []) {
+    if (!cfg.managed || cfg.content == null) continue // env-file configs are used as-is on disk
+    const abs = configAbsPath(app, cfg)
+    if (existsSync(abs)) continue // never overwrite a config already on disk
+    try {
+      mkdirSync(join(abs, '..'), { recursive: true })
+      writeFileSync(abs, cfg.content)
+      logLine(app, `config: wrote ${cfg.path} from the plan (was missing)`)
+    } catch (e) {
+      logLine(app, `config: FAILED to write ${cfg.path} — ${e.message}`)
+    }
+  }
+}
+function readConfig(app, cfg) {
+  const abs = configAbsPath(app, cfg)
+  let exists = false, content = ''
+  try {
+    if (existsSync(abs)) {
+      exists = true
+      const buf = readFileSync(abs)
+      content = buf.length > MAX_CONFIG_BYTES
+        ? buf.slice(0, MAX_CONFIG_BYTES).toString('utf8') + '\n… (truncated)'
+        : buf.toString('utf8')
+    } else if (cfg.managed && cfg.content != null) {
+      content = cfg.content // planned content — not yet written to disk
+    }
+  } catch (e) { content = `(unreadable: ${e.message})` }
+  return {
+    path: cfg.path, label: cfg.label || cfg.path, source: cfg.source || 'env-file',
+    managed: !!cfg.managed, keys: cfg.keys || [], note: cfg.note || '', exists, content,
+  }
+}
+
+// ---- App lifecycle ---------------------------------------------------------------------
+// Candidate loopback hosts to check for liveness: IPv4 (127.0.0.1) AND IPv6 (::1) loopback
+// always, plus whatever host the plan's health URL names. Frameworks bind different families —
+// Spring Boot listens on 127.0.0.1, but Vite/Next preview dev servers bind IPv6 ::1 only — so
+// probing a single family misses half of them. `localhost` in a health URL is included as-is
+// and resolved by the OS.
+function probeHosts(app) {
+  const hosts = new Set(['127.0.0.1', '::1'])
+  try { if (app.health) hosts.add(new URL(app.health).hostname) } catch {}
+  return [...hosts]
+}
+// Liveness = a raw TCP connect to the app's listen port on ANY candidate host, NOT an HTTP
+// fetch of a health URL. A listening port means the app is up regardless of auth (Spring
+// Security 401s), path (actuator disabled), or protocol — and it is reliable where Node's fetch
+// is not (undici can stall on localhost keep-alive and time out against a server curl reaches
+// in 20 ms). This also detects apps started outside this CI/CD app, so their state shows right.
+async function probe(app) {
+  const results = await Promise.all(probeHosts(app).map((h) => tcpProbe(h, app.port, 800)))
+  return results.some(Boolean)
+}
+
+// Infrastructure reachability — a raw TCP connect, so it works for non-HTTP services
+// (PostgreSQL, Redis) as well as web consoles. Status-only: infra is never controlled here.
+function tcpProbe(host, port, timeout = 1000) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket()
+    let done = false
+    const finish = (ok) => { if (done) return; done = true; try { socket.destroy() } catch {} ; resolve(ok) }
+    socket.setTimeout(timeout)
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+    try { socket.connect(Number(port), host || '127.0.0.1') } catch { finish(false) }
+  })
+}
+
+// {VERSION} token substitution — the version comes from the page's topbar selector (the
+// studio guard's versions, latest preselected). Tag-only: never checks out code. The `v`
+// prefix is stripped so docker tags read `1.2.0`, not `v1.2.0`.
+function subst(cmd, version) {
+  return String(cmd || '').replaceAll('{VERSION}', String(version || 'latest').replace(/^v/, ''))
+}
+
+// Managed Dockerfile from the plan's ## Dockerfiles — written before Build only when the
+// application folder has none (an existing Dockerfile is never overwritten).
+function ensureDockerfile(app) {
+  const d = app.dockerfile
+  if (!d || d.content == null) return
+  const abs = join(PROJECT_DIR, app.folder, d.path || 'Dockerfile')
+  if (existsSync(abs)) return
+  try {
+    writeFileSync(abs, d.content)
+    logLine(app, `dockerfile: wrote ${d.path || 'Dockerfile'} from the plan (was missing)`)
+  } catch (e) { logLine(app, `dockerfile: FAILED to write — ${e.message}`) }
+}
+
+function buildApp(app, version, onDone) {
+  if (activity.has(app.name)) { onDone && onDone(); return }
+  activity.set(app.name, 'building'); lastError.delete(app.name)
+  ensureConfigs(app)
+  ensureDockerfile(app)
+  runLogged(app, subst(app.build, version), (code) => {
+    activity.delete(app.name)
+    if (code !== 0) lastError.set(app.name, `build exited ${code} — see log`)
+    else logLine(app, 'build OK')
+    onDone && onDone()
+  })
+}
+
+function deployApp(app, version) {
+  if (activity.has(app.name) || !app.deploy) return
+  activity.set(app.name, 'deploying'); lastError.delete(app.name)
+  runLogged(app, subst(app.deploy, version), (code) => {
+    activity.delete(app.name)
+    if (code !== 0) lastError.set(app.name, `deploy exited ${code} — see log`)
+    else logLine(app, `deploy OK (${app.deployMethod})`)
+  })
+}
+
+function startApp(app, version) {
+  if (running.get(app.name) || activity.has(app.name)) return
+  failed.delete(app.name); lastError.delete(app.name)
+  ensureConfigs(app)
+  if (app.method === 'container') {
+    runLogged(app, subst(app.start, version), () => {})
+    saveState(); return
+  }
+  const child = runLogged(app, subst(app.start, version), (code) => {
+    running.delete(app.name)
+    // A user-requested Stop exits nonzero (killed) — that is not a failure.
+    if (code !== 0 && !stopping.delete(app.name)) {
+      failed.set(app.name, true)
+      lastError.set(app.name, `process exited ${code} — see log`)
+    } else stopping.delete(app.name)
+    saveState()
+  })
+  running.set(app.name, child)
+  saveState()
+}
+
+// shell:true spawns a shell whose grandchildren survive child.kill() on Windows — kill the
+// whole tree there (taskkill /T); plain kill elsewhere.
+function killTree(child) {
+  if (process.platform === 'win32' && child.pid) {
+    try { execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }) } catch {}
+  } else {
+    try { child.kill() } catch {}
+  }
+}
+
+// Stop an app we DON'T hold a child handle for (started outside this app, or before this app
+// last restarted) by killing whatever process tree is listening on its port — so Stop works
+// for any running app, not only ones this CI/CD app spawned. Returns true if a PID was killed.
+function killByPort(port) {
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' })
+      const pids = new Set()
+      for (const line of out.split(/\r?\n/)) {
+        const m = line.match(/:(\d+)\s+\S+\s+LISTENING\s+(\d+)/)
+        if (m && Number(m[1]) === Number(port)) pids.add(m[2])
+      }
+      for (const pid of pids) {
+        try { execFileSync('taskkill', ['/pid', pid, '/T', '/F'], { stdio: 'ignore' }) } catch {}
+      }
+      return pids.size > 0
+    }
+    const out = execFileSync('sh', ['-c', `lsof -ti tcp:${port} || true`], { encoding: 'utf8' })
+    const pids = out.split(/\s+/).filter(Boolean)
+    for (const pid of pids) { try { process.kill(Number(pid)) } catch {} }
+    return pids.length > 0
+  } catch { return false }
+}
+
+function stopApp(app, version) {
+  if (app.method === 'container' && app.stop && app.stop !== 'process-kill') {
+    const stopCmd = subst(app.stop, version)
+    try { execFileSync(stopCmd.split(' ')[0], stopCmd.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
+  } else {
+    const child = running.get(app.name)
+    if (child) {
+      stopping.add(app.name)
+      killTree(child)
+    } else {
+      // No child handle — kill by port so an externally/previously started app still stops.
+      lastError.delete(app.name)
+      if (!killByPort(app.port)) {
+        lastError.set(app.name, `could not stop — nothing found listening on port ${app.port}`)
+      }
+    }
+  }
+  running.delete(app.name)
+  saveState()
+}
+
+function json(res, code, body) {
+  res.writeHead(code, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+
+// ---- Page ------------------------------------------------------------------------------
+const PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>CI/CD</title><style>
+body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;display:flex;flex-direction:column;height:100vh}
+.top{display:flex;gap:8px;align-items:center;padding:10px 12px 6px;font-size:13px}
+.meta{font-size:11px;color:#5b6572}
+.tabs{display:flex;gap:2px;padding:0 12px;border-bottom:1px solid #d9dee5;flex-wrap:wrap}
+.tab{border:1px solid #d9dee5;border-bottom:none;border-radius:8px 8px 0 0;background:#eef1f5;padding:6px 14px;font-size:13px;cursor:pointer;display:flex;gap:6px;align-items:center}
+.tab.active{background:#fff;font-weight:600}
+.tab .dot{width:8px;height:8px;border-radius:99px;background:#8a94a0}
+.dot.running{background:#1c8a4a}.dot.failed{background:#c23b3b}.dot.building,.dot.deploying{background:#c9922a}
+.bar{display:flex;gap:8px;align-items:center;padding:10px 12px;background:#fff;border-bottom:1px solid #e1e5ea;flex-wrap:wrap}
+.badge{font-size:10px;text-transform:uppercase;border-radius:99px;padding:2px 8px;color:#fff;background:#8a94a0}
+.badge.running{background:#1c8a4a}.badge.failed{background:#c23b3b}.badge.building,.badge.deploying{background:#c9922a}
+.url{font-size:12px;color:#1a66d0;text-decoration:underline;word-break:break-all}
+button{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:4px 12px;font-size:12px;cursor:pointer}
+select{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:3px 6px;font-size:12px}
+button:hover:enabled{background:#eef1f5}
+button:disabled{opacity:.4;cursor:default}
+.notice{padding:4px 12px;font-size:11px;color:#8a5a00;background:#fff7e6;display:none}
+.err{padding:4px 12px;font-size:11px;color:#c23b3b;display:none;white-space:pre-wrap}
+#log{flex:1;margin:0;padding:10px 12px;background:#0f1216;color:#d7dde4;font-size:11px;line-height:1.5;overflow:auto;white-space:pre-wrap}
+.muted{color:#5b6572;font-size:12px}
+.modal{position:fixed;inset:0;background:rgba(0,0,0,.45);display:none;align-items:center;justify-content:center;padding:24px;z-index:20}
+.modal.open{display:flex}
+.modal-panel{background:#fff;border-radius:10px;max-width:920px;width:100%;max-height:85vh;display:flex;flex-direction:column;overflow:hidden;box-shadow:0 10px 40px rgba(0,0,0,.3)}
+.modal-head{display:flex;align-items:center;gap:8px;padding:10px 14px;border-bottom:1px solid #e1e5ea;font-size:13px}
+.modal-body{padding:12px 14px;overflow:auto}
+.cfg{margin-bottom:16px}
+.cfg h3{font-size:13px;margin:0 0 4px;display:flex;gap:8px;align-items:center}
+.cfg .src{font-size:10px;text-transform:uppercase;border-radius:99px;padding:2px 8px;background:#eef1f5;color:#5b6572}
+.cfg .miss{color:#c23b3b;font-weight:600}
+.cfg .ok{color:#1c8a4a;font-weight:600}
+.cfg .keys{font-size:11px;color:#5b6572;margin:2px 0}
+.cfg pre{background:#0f1216;color:#d7dde4;font-size:11px;padding:8px 10px;border-radius:6px;overflow:auto;max-height:320px;white-space:pre-wrap;margin:4px 0 0}
+</style></head><body>
+<div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span>
+<span class="meta">version</span><select id="ver" title="Tag substituted into {VERSION} in commands (docker image tag)"><option value="">latest</option></select>
+<button onclick="actAll('build')" title="Build every eligible application, one at a time">Build All</button>
+<button onclick="actAll('start')" title="Start every eligible stopped application">Start All</button>
+<button onclick="actAll('stop')" title="Stop every running application">Stop All</button>
+<span style="flex:1"></span><a id="infralink" class="url" href="infra" target="_blank" rel="noreferrer" style="display:none">Infrastructure ↗</a></div>
+<div class="tabs" id="tabs"></div>
+<div class="bar" id="bar"></div>
+<div class="notice" id="notice"></div>
+<div class="err" id="err"></div>
+<pre id="log"></pre>
+<div class="modal" id="cfgModal" onclick="if(event.target===this)closeConfig()">
+  <div class="modal-panel">
+    <div class="modal-head"><strong id="cfgTitle">Configuration</strong><span style="flex:1"></span><button onclick="closeConfig()">Close</button></div>
+    <div class="modal-body" id="cfgBody"></div>
+  </div>
+</div>
+<script>
+function esc(s){ return String(s==null?'':s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])) }
+let state = { apps: [] }
+let active = null
+let ws = null, wsTimer = null
+
+function appOf(name){ return state.apps.find(a => a.name === name) }
+
+function renderTabs(){
+  document.getElementById('tabs').innerHTML = state.apps.map(a => \`
+    <div class="tab \${a.name===active?'active':''}" onclick="setActive('\${a.name}')">
+      <span class="dot \${a.phase}"></span>\${a.name}\${a.developedOnce===false?' 🔒':''}</div>\`).join('')
+}
+
+function renderBar(){
+  const a = appOf(active)
+  if (!a) return
+  const url = 'http://'+location.hostname+':'+a.port+'/'
+  const gate = a.developedOnce === true
+  const busy = a.phase==='building'||a.phase==='deploying'
+  document.getElementById('bar').innerHTML = \`
+    <span class="badge \${a.phase}">\${a.phase}\${a.external?' (external)':''}</span>
+    <span class="meta">\${a.method} · port \${a.port}</span>
+    <a class="url" href="\${url}" target="_blank" rel="noreferrer">\${url}</a>
+    <span style="flex:1"></span>
+    <button onclick="openConfig()" title="Show this application's runtime configuration files">Config</button>
+    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''} title="\${a.image?'Builds the app AND the docker image '+a.image+':<version>':'Runs the plan build command'}">Build</button>
+    <button onclick="act('start')" \${!gate||busy||a.phase==='running'?'disabled':''}>Start</button>
+    <button onclick="act('stop')" \${a.phase!=='running'?'disabled':''}>Stop</button>
+    \${a.deploy?\`<button onclick="act('deploy')" \${!gate||busy?'disabled':''}>Deploy (\${a.deployMethod})</button>\`:''}\`
+  const notice = document.getElementById('notice')
+  if (a.developedOnce === false) {
+    notice.textContent = 'This application has not been developed through the workflow yet — run conductor-feature-develop first.'
+    notice.style.display = 'block'
+  } else if (a.developedOnce === null) {
+    notice.textContent = 'Develop status not verified yet (studio unreachable) — controls stay disabled.'
+    notice.style.display = 'block'
+  } else notice.style.display = 'none'
+  const err = document.getElementById('err')
+  if (a.error) { err.textContent = a.error; err.style.display = 'block' } else err.style.display = 'none'
+}
+
+function setActive(name){
+  if (active === name) return
+  active = name
+  closeWs()
+  document.getElementById('log').textContent = ''
+  openWs(name)
+  renderTabs(); renderBar()
+}
+
+// Live log stream. One socket at a time (closed on tab switch); auto-reconnect while the tab
+// stays active; the DOM buffer is trimmed so long sessions never grow the page unbounded.
+function openWs(name){
+  // Path-relative + scheme-aware so the stream works direct (:5000/) AND behind the studio's
+  // /api/cicd/<id>/app-proxy/ prefix (which tunnels the upgrade), also under HTTPS.
+  ws = new WebSocket((location.protocol==='https:'?'wss://':'ws://')+location.host+location.pathname.replace(/\/$/,'')+'/ws?app='+encodeURIComponent(name))
+  ws.onmessage = e => appendLog(e.data)
+  ws.onclose = () => { ws = null; if (active === name) wsTimer = setTimeout(() => openWs(name), 2000) }
+}
+function closeWs(){
+  if (wsTimer) { clearTimeout(wsTimer); wsTimer = null }
+  if (ws) { ws.onclose = null; try { ws.close() } catch {} ws = null }
+}
+function appendLog(text){
+  const el = document.getElementById('log')
+  const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 40
+  el.textContent += text
+  if (el.textContent.length > 400000) el.textContent = el.textContent.slice(-250000)
+  if (atBottom) el.scrollTop = el.scrollHeight
+}
+
+// Config modal — the runtime config files this application needs to start (from the plan). Shows
+// each file's live on-disk content (or the planned content when a managed file is not yet written),
+// its source (environment / env-file / derived), required keys and present/MISSING status — so the
+// user can troubleshoot a start-up that is failing for want of complete configuration.
+async function openConfig(){
+  if (!active) return
+  const modal = document.getElementById('cfgModal')
+  document.getElementById('cfgTitle').textContent = 'Configuration — '+active
+  document.getElementById('cfgBody').innerHTML = '<div class="muted">Loading…</div>'
+  modal.classList.add('open')
+  const s = await fetch('api/apps/'+encodeURIComponent(active)+'/config').then(r=>r.json()).catch(()=>null)
+  const configs = (s && s.configs) || []
+  document.getElementById('cfgBody').innerHTML = configs.length ? configs.map(c => \`
+    <div class="cfg">
+      <h3>\${esc(c.label)} <span class="src">\${esc(c.source)}</span>
+        \${c.exists ? '<span class="ok">present</span>' : '<span class="miss">MISSING'+(c.managed&&c.content?' — created on Build/Start':'')+'</span>'}</h3>
+      \${c.keys&&c.keys.length ? '<div class="keys">Required keys: '+c.keys.map(esc).join(', ')+'</div>' : ''}
+      \${c.note ? '<div class="keys">'+esc(c.note)+'</div>' : ''}
+      <pre>\${esc(c.content) || '(empty)'}</pre>
+    </div>\`).join('') : '<div class="muted">No runtime configuration declared for this application.</div>'
+}
+function closeConfig(){ document.getElementById('cfgModal').classList.remove('open') }
+document.addEventListener('keydown', e => { if (e.key === 'Escape') closeConfig() })
+
+// Topbar version selector — the studio guard's project versions (latest first). Repopulated
+// only when the list changes so the user's selection survives the 3 s poll.
+let verChoices = ''
+function renderVersions(versions){
+  const sel = document.getElementById('ver')
+  const list = (versions && versions.length ? versions : []).join('|')
+  if (list === verChoices) return
+  verChoices = list
+  sel.innerHTML = (versions && versions.length ? versions : ['latest'])
+    .map((v, i) => '<option value="'+esc(v)+'"'+(i===0?' selected':'')+'>'+esc(v)+'</option>').join('')
+}
+function selectedVersion(){ return document.getElementById('ver').value || '' }
+
+async function refresh(){
+  const s = await fetch('api/state').then(r => r.json()).catch(() => null)
+  if (!s) return
+  state = s
+  document.getElementById('branch').textContent = s.currentBranch ? 'branch: '+s.currentBranch : ''
+  document.getElementById('infralink').style.display = s.hasInfra ? 'inline' : 'none'
+  renderVersions(s.versions)
+  if (!active && s.apps.length) setActive(s.apps[0].name)
+  renderTabs(); renderBar()
+}
+async function act(op){
+  await fetch('api/apps/'+encodeURIComponent(active)+'/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
+  refresh()
+}
+async function actAll(op){
+  await fetch('api/all/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
+  refresh()
+}
+// Rescan immediately when the user returns to this page (tab focus / regained visibility), so
+// coming back from another screen reflects the true app + infra state without waiting the poll.
+document.addEventListener('visibilitychange', () => { if (!document.hidden) refresh() })
+window.addEventListener('focus', refresh)
+refresh(); setInterval(refresh, 3000)
+</script></body></html>`
+
+// ---- Infrastructure page ---------------------------------------------------------------
+// Standalone status-only page (opened in a new tab from the main page's Infrastructure link).
+// Lists every supporting 3rd-party service with a live TCP-reachability dot and a console link
+// when the service exposes a web UI. No lifecycle controls — infra is externally managed.
+const INFRA_PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>Infrastructure</title><style>
+body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;padding:16px}
+h1{font-size:16px;margin:0 0 12px}
+table{border-collapse:collapse;width:100%;max-width:820px;font-size:13px}
+th,td{text-align:left;padding:8px 10px;border-bottom:1px solid #e1e5ea}
+th{font-size:11px;text-transform:uppercase;color:#5b6572}
+.dot{display:inline-block;width:9px;height:9px;border-radius:99px;background:#8a94a0;margin-right:6px;vertical-align:middle}
+.dot.up{background:#1c8a4a}.dot.down{background:#c23b3b}
+.url{color:#1a66d0;text-decoration:underline}
+.muted{color:#5b6572;font-size:12px}
+.legend{margin-top:12px;font-size:11px;color:#5b6572}
+</style></head><body>
+<h1>Infrastructure</h1>
+<table><thead><tr><th>Status</th><th>Service</th><th>Endpoint</th><th>Console</th></tr></thead>
+<tbody id="rows"><tr><td colspan="4" class="muted">Loading…</td></tr></tbody></table>
+<div class="legend">● up ○ down — TCP reachability, polled every 3s</div>
+<script>
+function esc(s){ return String(s==null?'':s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])) }
+async function refresh(){
+  const s = await fetch('api/infra').then(r=>r.json()).catch(()=>null)
+  if(!s) return
+  const rows = (s.infra||[]).map(i => \`
+    <tr>
+      <td><span class="dot \${i.up?'up':'down'}"></span>\${i.up?'up':'down'}</td>
+      <td>\${esc(i.name)}\${i.description?' <span class="muted">— '+esc(i.description)+'</span>':''}</td>
+      <td class="muted">\${esc(i.host)}:\${esc(i.port)}</td>
+      <td>\${i.url?'<a class="url" href="'+esc(i.url)+'" target="_blank" rel="noreferrer">open ↗</a>':'—'}</td>
+    </tr>\`).join('')
+  document.getElementById('rows').innerHTML = rows || '<tr><td colspan="4" class="muted">No infrastructure declared.</td></tr>'
+}
+// Rescan immediately when the user returns to this page (tab focus / regained visibility), so
+// coming back from another screen reflects the true app + infra state without waiting the poll.
+document.addEventListener('visibilitychange', () => { if (!document.hidden) refresh() })
+window.addEventListener('focus', refresh)
+refresh(); setInterval(refresh, 3000)
+</script></body></html>`
+
+// ---- HTTP ------------------------------------------------------------------------------
+const server = http.createServer(async (req, res) => {
+  if (req.method === 'GET' && req.url === '/') {
+    res.writeHead(200, { 'content-type': 'text/html' })
+    return res.end(PAGE)
+  }
+  if (req.method === 'GET' && req.url === '/infra') {
+    res.writeHead(200, { 'content-type': 'text/html' })
+    return res.end(INFRA_PAGE)
+  }
+  if (req.method === 'GET' && req.url === '/api/infra') {
+    const infra = await Promise.all((loadConfig().infra || []).map(async (i) => ({
+      id: i.id, name: i.name, host: i.host || '127.0.0.1', port: i.port,
+      url: i.url || null, description: i.description || '',
+      up: await tcpProbe(i.host || '127.0.0.1', i.port),
+    })))
+    return json(res, 200, { infra })
+  }
+  if (req.method === 'GET' && req.url === '/api/state') {
+    const apps = await Promise.all(loadConfig().apps.map(async (a) => {
+      const healthy = await probe(a)
+      const phase = activity.get(a.name) || (healthy ? 'running' : failed.has(a.name) ? 'failed' : 'stopped')
+      return {
+        name: a.name, method: a.method, port: a.port, phase,
+        deploy: !!a.deploy, deployMethod: a.deployMethod || 'none',
+        image: a.image || null,
+        external: healthy && !running.has(a.name),
+        developedOnce: developedOnce(a),
+        error: lastError.get(a.name) || null,
+      }
+    }))
+    return json(res, 200, {
+      currentBranch: currentBranch(),
+      hasInfra: (loadConfig().infra || []).length > 0,
+      versions: guardVersions,
+      apps,
+    })
+  }
+  const cfgm = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/config$/)
+  if (cfgm && req.method === 'GET') {
+    const app = loadConfig().apps.find((a) => a.name === decodeURIComponent(cfgm[1]))
+    if (!app) return json(res, 404, { error: 'unknown app' })
+    return json(res, 200, { configs: (app.configs || []).map((c) => readConfig(app, c)) })
+  }
+  // ?version=<semver> on every action — the topbar selection, substituted into {VERSION}.
+  const reqVersion = (() => {
+    try { return new URL(req.url, 'http://x').searchParams.get('version') || '' } catch { return '' }
+  })()
+  const path = (req.url || '').split('?')[0]
+  const m = path.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
+  if (m && req.method === 'POST') {
+    const app = loadConfig().apps.find((a) => a.name === decodeURIComponent(m[1]))
+    if (!app) return json(res, 404, { error: 'unknown app' })
+    if (m[2] !== 'stop' && developedOnce(app) === false) {
+      return json(res, 409, { error: 'application has not completed a develop workflow run' })
+    }
+    if (m[2] === 'build') buildApp(app, reqVersion)
+    else if (m[2] === 'start') startApp(app, reqVersion)
+    else if (m[2] === 'deploy') deployApp(app, reqVersion)
+    else stopApp(app, reqVersion)
+    return json(res, 200, { ok: true })
+  }
+  // All-apps controls. Eligible = develop gate not failed and not mid-build/deploy; build and
+  // start additionally skip apps already running. Builds run SEQUENTIALLY (honest logs, no
+  // CPU storm); start/stop fire together. Ineligible apps are skipped silently.
+  const all = path.match(/^\/api\/all\/(build|start|stop)$/)
+  if (all && req.method === 'POST') {
+    const op = all[1]
+    const apps = loadConfig().apps
+    if (op === 'stop') {
+      for (const a of apps) {
+        if (running.has(a.name)) stopApp(a, reqVersion)
+        else probe(a).then((up) => { if (up) stopApp(a, reqVersion) })
+      }
+      return json(res, 200, { ok: true })
+    }
+    const eligible = []
+    for (const a of apps) {
+      if (developedOnce(a) === false || activity.has(a.name)) continue
+      if (await probe(a)) continue // already running — skip for build AND start
+      eligible.push(a)
+    }
+    if (op === 'start') {
+      for (const a of eligible) startApp(a, reqVersion)
+      return json(res, 200, { ok: true, count: eligible.length })
+    }
+    // op === 'build' — sequential chain: each build starts when the previous one exits.
+    const queue = [...eligible]
+    const next = () => { const a = queue.shift(); if (a) buildApp(a, reqVersion, next) }
+    next()
+    return json(res, 200, { ok: true, count: eligible.length })
+  }
+  json(res, 404, { error: 'not found' })
+})
+
+// WebSocket endpoint /ws?app=<name> — push-only log stream (see "Log streaming" above).
+server.on('upgrade', (req, socket) => {
+  let name = ''
+  let isWsPath = false
+  try {
+    const url = new URL(req.url, 'http://x')
+    isWsPath = url.pathname === '/ws'
+    name = url.searchParams.get('app') || ''
+  } catch {}
+  const key = req.headers['sec-websocket-key']
+  const app = loadConfig().apps.find((a) => a.name === name)
+  if (!app || !key || !isWsPath) { socket.destroy(); return }
+  const accept = createHash('sha1').update(key + WS_GUID).digest('base64')
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+    `Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
+  )
+  let subs = subscribers.get(name)
+  if (!subs) { subs = new Set(); subscribers.set(name, subs) }
+  subs.add(socket)
+  const cleanup = () => { subs.delete(socket); try { socket.destroy() } catch {} }
+  socket.on('close', cleanup)
+  socket.on('error', cleanup)
+  // Client frames are only ever close (0x8) — anything else is ignored, never buffered.
+  socket.on('data', (buf) => { if ((buf[0] & 0x0f) === 0x8) cleanup() })
+  socket.write(wsFrame(logTail(name)))
+})
+
+server.listen(PORT, () => console.log(`cicd app on :${PORT}`))
+```
+
+`cicd/app/cicd.config.json` shape — one `apps` entry per application from the plan's Deployment
+Decisions table, one `infra` entry per row of the plan's `## Infrastructure` table.
+`deployMethod`/`deploy` come from the plan's Deploy columns (`deploy` is `null` when the method
+is `none`). `infra[].url` is `null` for a headless service (Console URL cell `-`); emit
+`"infra": []` when the plan declares no supporting services.
+
+Docker fields (from the plan's `## Docker` / `## Dockerfiles` sections): top-level
+`"docker": { "registry": "<repo>" }` or `null` when the plan is not dockerized. Per app,
+`"image"` is the Docker table's Image value (`null` for a non-dockerized app) and
+`"dockerfile"` is `{ "path": "Dockerfile", "content": "<managed body>" }` for a `managed`
+Dockerfile (materialized before Build when missing — never overwriting), or
+`{ "path": "Dockerfile", "content": null }` for an `existing` one (`null` entirely when the
+app has no image). Commands may carry the literal `{VERSION}` token — copied verbatim; the
+server substitutes the topbar-selected version (semver sans `v`, fallback `latest`) at
+execution time.
+
+Each app also carries a `configs` array — the runtime config files the application reads at start,
+from the plan's `## Application Configs` section (one entry per file). Fields:
+`path` (relative to the application folder), `label`, `source` (`environment` | `env-file` |
+`derived`), `managed` (when `true` the server writes `content` to `path` before Build/Start if the
+file is missing, so start-up always has complete config), `keys` (the required keys the app needs
+to boot), `note`, and `content` (the plan's resolved file body when `managed`; `null`/omitted for an
+`env-file` used as-is on disk). Emit `"configs": []` when an application needs no runtime config
+file. NEVER omit a `managed.content` that the plan resolved — that body is what guarantees the app
+starts configured. Per the dev-environment plaintext rule, `content` may include credentials
+verbatim (this is a local dev CI/CD app).
+
+```json
+{
+  "port": 5000,
+  "docker": { "registry": "registry.example.com/team" },
+  "apps": [
+    {
+      "name": "my-app",
+      "folder": "my-app",
+      "method": "process",
+      "port": 3000,
+      "build": "pnpm install && pnpm build && docker build -t registry.example.com/team/my-app:{VERSION} .",
+      "start": "node dist/index.js",
+      "stop": "process-kill",
+      "deployMethod": "kubernetes",
+      "deploy": "kubectl apply -f my-app/k8s/",
+      "health": "http://127.0.0.1:3000/",
+      "image": "registry.example.com/team/my-app",
+      "dockerfile": {
+        "path": "Dockerfile",
+        "content": "FROM node:22-slim\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --omit=dev\nCOPY . .\nEXPOSE 3000\nCMD [\"node\", \"dist/index.js\"]\n"
+      },
+      "configs": [
+        {
+          "path": ".env",
+          "label": ".env (runtime)",
+          "source": "environment",
+          "managed": true,
+          "keys": ["DATABASE_URL", "REDIS_HOST", "PORT"],
+          "note": "Resolved from ENVIRONMENT.md → my-app section",
+          "content": "DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb\nREDIS_HOST=127.0.0.1\nPORT=3000\n"
+        },
+        {
+          "path": ".env-uat",
+          "label": ".env-uat (existing)",
+          "source": "env-file",
+          "managed": false,
+          "keys": ["DATABASE_URL", "REDIS_HOST"],
+          "note": "Existing env file in the app folder — used as-is",
+          "content": null
+        }
+      ]
+    }
+  ],
+  "infra": [
+    {
+      "id": "postgres-main",
+      "name": "PostgreSQL (app db)",
+      "host": "127.0.0.1",
+      "port": 5432,
+      "url": null,
+      "description": "Shared application database"
+    },
+    {
+      "id": "keycloak",
+      "name": "Keycloak",
+      "host": "127.0.0.1",
+      "port": 8180,
+      "url": "http://127.0.0.1:8180",
+      "description": "Single sign-on"
+    }
+  ]
+}
+```