@rashidee/co2 1.3.4 → 1.3.6

package/drizzle/0017_git_remote_url.sql

@@ -0,0 +1,3 @@
+-- v2.2.0: Per-project git remote URL (push destination). Nullable; auto-seeded from an
+-- imported repo's origin, editable in project detail. Contains no embedded credentials.
+ALTER TABLE `projects` ADD `git_remote_url` text;

package/drizzle/0018_default_branch.sql

@@ -0,0 +1,3 @@
+-- v2.3.0: Per-project default (trunk) branch — the branch release branches merge back into on a
+-- version cut (runVersionCutGit). Defaults to `main`; existing rows backfill to `main`.
+ALTER TABLE `projects` ADD `default_branch` text DEFAULT 'main' NOT NULL;

package/drizzle/0019_git_provider.sql

@@ -0,0 +1,3 @@
+-- v2.3.0: Per-project git hosting provider — drives the PAT auth-username convention (GitHub
+-- `x-access-token` vs GitLab `oauth2`). Defaults to `github`; existing rows backfill to `github`.
+ALTER TABLE `projects` ADD `git_provider` text DEFAULT 'github' NOT NULL;

package/drizzle/meta/_journal.json

@@ -120,6 +120,27 @@
       "when": 1784700000000,
       "tag": "0016_cicd_v2100",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1784800000000,
+      "tag": "0017_git_remote_url",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "6",
+      "when": 1784900000000,
+      "tag": "0018_default_branch",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "6",
+      "when": 1785000000000,
+      "tag": "0019_git_provider",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rashidee/co2",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
   "type": "module",
   "license": "MIT",

package/plugin/skills/util-gencicdscript/SKILL.md

@@ -8,10 +8,15 @@ description: >
   `**Approved**:` line (stamped by Compound Context Studio's Approve button). Produces
   cicd/app/ — a zero-npm-dependency node:http app (server.js + cicd.config.json) rendering a
   bare light-themed page (no header/sidebar/footer, iframe-embeddable) with one nav tab per
-  application: a controls bar (status badge, clickable app URL opening a new tab, Build /
-  Start / Stop / Deploy buttons) above that application's log streamed live over a built-in
-  zero-dependency WebSocket (bounded tail + backpressure drop server-side, trimmed DOM buffer
-  client-side — no leaks/OOM). Build and Deploy commands come from the approved plan (inferred
+  application: a controls bar (status badge, clickable app URL opening a new tab, a Config
+  button, and Build / Start / Stop / Deploy buttons) above that application's log streamed live
+  over a built-in zero-dependency WebSocket (bounded tail + backpressure drop server-side, trimmed
+  DOM buffer client-side — no leaks/OOM). The Config button opens a modal listing the application's
+  runtime config files (from the plan's `## Application Configs`) — each with its source
+  (ENVIRONMENT.md-derived vs an existing .env/.env-* file), present/MISSING status, required keys
+  and full live content — for troubleshooting; and before Build/Start the app materializes any
+  missing plan-managed config file into the application folder so it always starts with complete
+  configuration. Build and Deploy commands come from the approved plan (inferred
   from ENVIRONMENT.md/DEVTOOL.md — e.g. Spring Boot jar vs Docker image; deploy via web-server
   copy, docker run or kubectl apply, or none). Controls are disabled for any application that
   has never completed a conductor-develop workflow run (checked against the studio's
@@ -58,12 +63,22 @@ Read `references/cicd-app-template.md` for the complete file templates. Produce:
 
 1. `cicd/app/cicd.config.json` — from the plan's tables:
    `{ "port": <CI/CD app port>, "apps": [{ "name", "folder", "method", "port", "build",
-   "start", "stop", "deployMethod", "deploy", "health" }], "infra": [{ "id", "name", "host",
-   "port", "url", "description" }] }` — `deployMethod` is the plan's Deploy Method column
+   "start", "stop", "deployMethod", "deploy", "health", "configs" }], "infra": [{ "id", "name",
+   "host", "port", "url", "description" }] }` — `deployMethod` is the plan's Deploy Method column
    (`none|web-server|docker|kubernetes`) and `deploy` its command (`null` when the method is
    `none`). The `infra` array comes from the plan's `## Infrastructure` table (one entry per
    row); `url` is `null` when the Console URL cell is `-`. Emit `"infra": []` when the plan's
    Infrastructure table is empty — never invent services the plan does not list.
+   - `configs` — the runtime config files each application reads at start, from the plan's
+     `## Application Configs` section (one entry per file):
+     `{ "path", "label", "source", "managed", "keys", "note", "content" }`. `source` is
+     `environment` | `env-file` | `derived`; `path` is relative to the application folder. When
+     `managed` is `true`, `content` is the plan's resolved file body (verbatim, credentials
+     included per the dev-plaintext rule) — the generated app writes it into the application folder
+     before Build/Start if the file is missing, so the app always starts with COMPLETE config. For
+     an `env-file` used as-is on disk, set `managed:false` and `content:null`. Copy the plan's
+     resolved `content` blocks verbatim — NEVER drop a managed file's content (that body is what
+     guarantees the app boots). Emit `"configs": []` for an app the plan lists no config files for.
 2. `cicd/app/server.js` — the template verbatim (it is generic; all project specifics live in
    cicd.config.json). Zero npm dependencies.
 3. Ensure `cicd/logs/` and `cicd/state.json` are ignored: append `cicd/logs/` and
@@ -78,6 +93,10 @@ port, application count) and STOP — the studio starts/embeds the app.
 
 - Zero npm dependencies — plain node:http only (the WebSocket log stream is hand-rolled in the
   template); no install step may be required.
+- Live config: the generated server re-reads `cicd.config.json` on demand (mtime-cached), so a
+  regenerated plan — corrected build/start commands, a renamed build artifact, added apps or
+  changed infra — is applied WITHOUT restarting the running app (only the listen port is bound
+  once at boot). Never cache the parsed config in a top-level `const`.
 - The page is bare: no header, sidebar or footer (it is iframed by the studio). Light theme,
   one nav tab per application; the tab body is that application's live log.
 - Infrastructure page: when `infra` is non-empty the main page shows an "Infrastructure" link
@@ -93,9 +112,22 @@ port, application count) and STOP — the studio starts/embeds the app.
 - Develop gate: controls stay disabled for an application that never completed a
   conductor-develop run — checked via `${CO2_STUDIO_URL}/api/cicd-guard/${CO2_PROJECT_ID}`
   with the CO2_GUARD_TOKEN from the spawn env (refreshed every 30 s, last answer cached).
+- Application config (troubleshooting + completeness): every application tab has a **Config**
+  button opening a modal that lists the app's runtime config files (from `configs`) — each with its
+  source badge (`environment`/`env-file`/`derived`), present/MISSING status, required keys and full
+  live on-disk content. The Config button is ALWAYS enabled (independent of the develop gate) so a
+  failed start-up can always be inspected. Before Build and before Start the server materializes any
+  `managed` config file whose `content` is set into the application folder when it is missing (never
+  overwriting a file already on disk), so an application never fails to come up for want of config.
 - Log streaming must stay bounded: per-app log file on disk, bounded tail on connect, live
   append broadcast only, slow subscribers dropped on backpressure, client DOM buffer trimmed.
-- Already-running detection: `/api/state` probes each application's health URL (falling back
-  to its port) so an app started outside this page still shows as running; a Stop on an
-  externally started process is refused with a hint instead of killed.
+- Already-running detection: `/api/state` decides "is it running?" by a raw TCP connect to the
+  application's `port` on BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the host named
+  in its `health` URL — up if any connects. This is family-agnostic (Spring binds `127.0.0.1`,
+  Vite/Next preview bind IPv6 `::1` only) and reliable where an HTTP fetch is not, so an app
+  started outside this page still shows as running. Carry `health` and `port` from the plan
+  verbatim into `cicd.config.json`.
+- Stop works for any running app: if the app was started outside this CI/CD app (no child
+  handle), Stop kills whatever process tree is listening on its `port` (kill-by-port), so the
+  Stop control is enabled/usable whenever an app is detected running.
 - Never touch PRD.md/CLAUDE.md; never run builds or deploys yourself during generation.

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

@@ -21,8 +21,23 @@ 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 = JSON.parse(readFileSync(join(APP_DIR, 'cicd.config.json'), 'utf8'))
-const PORT = Number(process.env.PORT || CONFIG.port || 4100)
+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 || ''
@@ -36,7 +51,7 @@ const lastError = new Map() // app name -> string
 
 function saveState() {
   const s = {}
-  for (const a of CONFIG.apps) s[a.name] = running.has(a.name) ? 'running' : 'stopped'
+  for (const a of loadConfig().apps) s[a.name] = running.has(a.name) ? 'running' : 'stopped'
   try { writeFileSync(STATE_FILE, JSON.stringify(s)) } catch {}
 }
 
@@ -133,13 +148,67 @@ function runLogged(app, command, onExit) {
   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 url = app.health || `http://127.0.0.1:${app.port}/`
-  try {
-    await fetch(url, { signal: AbortSignal.timeout(800) })
-    return true
-  } catch { return false }
+  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
@@ -160,6 +229,7 @@ function tcpProbe(host, port, timeout = 1000) {
 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`)
@@ -180,6 +250,7 @@ function deployApp(app) {
 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
@@ -207,17 +278,45 @@ function killTree(child) {
   }
 }
 
+// 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) {
-      lastError.set(app.name, 'running outside this CI/CD app — stop it from where it was started')
-      return
+    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}`)
+      }
     }
-    stopping.add(app.name)
-    killTree(child)
   }
   running.delete(app.name)
   saveState()
@@ -248,6 +347,19 @@ 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>
@@ -255,7 +367,14 @@ button:disabled{opacity:.4;cursor:default}
 <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
@@ -279,9 +398,10 @@ function renderBar(){
     <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'||(a.external&&a.method!=='container')?'disabled':''}>Stop</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) {
@@ -323,6 +443,30 @@ function appendLog(text){
   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
@@ -336,6 +480,10 @@ 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>`
 
@@ -373,6 +521,10 @@ async function refresh(){
     </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>`
 
@@ -387,7 +539,7 @@ const server = http.createServer(async (req, res) => {
     return res.end(INFRA_PAGE)
   }
   if (req.method === 'GET' && req.url === '/api/infra') {
-    const infra = await Promise.all((CONFIG.infra || []).map(async (i) => ({
+    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),
@@ -395,7 +547,7 @@ const server = http.createServer(async (req, res) => {
     return json(res, 200, { infra })
   }
   if (req.method === 'GET' && req.url === '/api/state') {
-    const apps = await Promise.all(CONFIG.apps.map(async (a) => {
+    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 {
@@ -406,11 +558,17 @@ const server = http.createServer(async (req, res) => {
         error: lastError.get(a.name) || null,
       }
     }))
-    return json(res, 200, { currentBranch: currentBranch(), hasInfra: (CONFIG.infra || []).length > 0, apps })
+    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 = CONFIG.apps.find((a) => a.name === decodeURIComponent(m[1]))
+    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' })
@@ -434,7 +592,7 @@ server.on('upgrade', (req, socket) => {
     name = url.searchParams.get('app') || ''
   } catch {}
   const key = req.headers['sec-websocket-key']
-  const app = CONFIG.apps.find((a) => a.name === name)
+  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(
@@ -459,7 +617,18 @@ server.listen(PORT, () => console.log(`cicd app on :${PORT}`))
 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:
+`"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
 {
@@ -475,7 +644,27 @@ is `none`). `infra[].url` is `null` for a headless service (Console URL cell `-`
       "stop": "process-kill",
       "deployMethod": "kubernetes",
       "deploy": "kubectl apply -f my-app/k8s/",
-      "health": "http://127.0.0.1:3000/"
+      "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": [

package/plugin/skills/util-plancicd/SKILL.md

@@ -10,7 +10,12 @@ description: >
   method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
   start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
   kubectl apply — only when the environment calls for one), port and health-check URL, plus a
-  port for the generated CI/CD app itself. It also enumerates the project's supporting
+  port for the generated CI/CD app itself. It also infers each application's RUNTIME CONFIG — the
+  config files its start command reads (e.g. `.env`), deciding per file whether the values come
+  from ENVIRONMENT.md or from an existing `.env` / `.env-*` file already in the app folder, listing
+  the required keys and, for ENVIRONMENT.md-sourced files, the resolved content — so the generated
+  CI/CD app can complete the config before start (guaranteeing the app comes up) and show it in a
+  per-application Config modal for troubleshooting. It also enumerates the project's supporting
   infrastructure (3rd-party services from CLAUDE.md's `# Supporting 3rd Party Applications` and
   ENVIRONMENT.md — host, port and optional console URL) into an `## Infrastructure` section so
   the generated CI/CD app can surface a status-only Infrastructure page. The plan carries a
@@ -47,6 +52,7 @@ If the argument is missing or the file does not exist, STOP and tell the user to
 | Dev tools | `DEVTOOL.md` (project root) |
 | Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
 | App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
+| App config files | `<app_folder>/.env`, `<app_folder>/.env-*` (and stack-conventional config files) |
 | Infrastructure | `CLAUDE.md` `# Supporting 3rd Party Applications` + `ENVIRONMENT.md` |
 | Output plan | `cicd/CICD_PLAN.md` |
 
@@ -61,6 +67,13 @@ If the argument is missing or the file does not exist, STOP and tell the user to
 4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
    infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
    `composer.json` → laravel).
+4a. For each application, discover its RUNTIME CONFIG files: list any existing `.env` / `.env-*`
+   in the application folder AND the stack-conventional config the start command reads (node/
+   laravel → `.env`; Spring Boot → `application.properties` / `application-<profile>.yml` or a
+   `.env` when the app loads one). Read the content of each existing file (values may be reused).
+   Cross-reference ENVIRONMENT.md for the per-application config values (DB/cache/broker hosts and
+   ports, external-service URLs, credentials, secrets, the app's own PORT) and the Infrastructure
+   list from step 5 for the hosts/ports the app must point at.
 5. Build the **infrastructure list**: one entry per supporting 3rd-party service the project
    declares. For each, resolve `host` (default `127.0.0.1`), `port` and — when it exposes a web
    console/UI — a `url`, cross-referencing ENVIRONMENT.md for the actual host/port/endpoint. A
@@ -96,9 +109,47 @@ If the argument is missing or the file does not exist, STOP and tell the user to
   needs no deploy step beyond Start; never invent a target the config does not name.
 - **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
   collisions with the studio (3001) and the CI/CD app port.
-- **Health**: `http://127.0.0.1:<port>/` or a documented health endpoint from the spec.
+- **Health / running-detection**: the endpoint the generated CI/CD app uses to tell whether the
+  application is already running. Detection is a **raw TCP connect to the app's port on loopback**
+  — the generated app probes BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback, plus the host
+  named in this Health value — so it does not matter which family the framework binds. This
+  matters because dev servers differ: Spring Boot binds `127.0.0.1`, but **Vite / Next preview
+  servers bind IPv6 `::1` (localhost) only** and are invisible to an IPv4-only probe. Therefore
+  set the Health host to **`localhost`** (not `127.0.0.1`) for any Node/Vite/Next dev-server app
+  so the detection host set includes the interface it actually binds; use `127.0.0.1` for JVM
+  apps. Value form: `http://localhost:<port>/` or a documented health path from the spec (the
+  path is informational — detection keys on the port, not the path).
 - **CI/CD app port**: 4100 unless taken in `# Port Allocation`; record it in the plan.
 
+### Application config (per application)
+
+Decide the runtime config the application needs so it STARTS SUCCESSFULLY, and where each value
+comes from. For every config file the start command reads (`path`, relative to the application
+folder):
+
+- **source** — classify each file:
+  - `env-file` — an existing `.env` / `.env-*` in the app folder already holds the runtime values;
+    use it as-is on disk (do NOT re-materialize it). Set `managed: no`, no resolved content.
+  - `environment` — there is no complete runtime file; resolve the required values from
+    ENVIRONMENT.md (and the Infrastructure hosts/ports) and record the fully-resolved file content.
+    Set `managed: yes` so the CI/CD app writes it before Build/Start when missing.
+  - `derived` — the runtime file is chosen/combined from existing material (e.g. copy the target
+    env's `.env-<env>` to the canonical `.env` the start command reads, or merge an existing
+    `.env-*` with ENVIRONMENT.md values). Set `managed: yes` and record the resolved content.
+- **required keys** — enumerate every key the app must have to boot: its own PORT, datastore/cache/
+  broker connection strings, external-service URLs, credentials/secrets. Cross-check them against
+  ENVIRONMENT.md and the Infrastructure list.
+- **completeness (the point of this)** — every required key MUST be satisfiable from ENVIRONMENT.md
+  or an existing env file. If a required key cannot be resolved, still emit the config entry but
+  call out the unresolved key in that application's Rationale as a GAP (so the human fixes
+  ENVIRONMENT.md before approving) — never silently drop it.
+- **managed content** — for a `managed: yes` file, write the resolved body verbatim into the plan
+  as a fenced block (`path=<file>`). Values (including credentials) are emitted verbatim under the
+  dev-environment plaintext rule; they must never appear in the Rationale narrative.
+
+Only list files the app actually reads at runtime — do not invent config files. An app that needs
+no config file gets an empty config list.
+
 ### Infrastructure (status-only)
 
 Supporting 3rd-party services are **not** built/started/deployed by the CI/CD app — they are
@@ -116,9 +167,10 @@ Never emit credentials into the infrastructure entries — status and links only
 
 ## Phase 3 — Write the plan
 
-Create `cicd/` if missing and write `cicd/CICD_PLAN.md`:
+Create `cicd/` if missing and write `cicd/CICD_PLAN.md` (shown here in a 4-backtick fence so the
+inner ```env config block renders — the plan file itself uses a normal 3-backtick env fence):
 
-```markdown
+````markdown
 # CI/CD Deployment Plan — <Project Name>
 
 **Generated**: <ISO date>
@@ -135,6 +187,37 @@ Create `cicd/` if missing and write `cicd/CICD_PLAN.md`:
 |---|---|---|---|---|---|---|---|---|---|
 | <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
 
+> **Running-detection**: the generated CI/CD app determines "is it running?" by a TCP connect to
+> each application's **Port** on both IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the
+> **Health** host — so an app is detected whichever family it binds. Use a `localhost` Health host
+> for Node/Vite/Next apps (they bind IPv6 `::1`) and `127.0.0.1` for JVM apps.
+
+## Application Configs
+
+The runtime config each application needs to START SUCCESSFULLY. The generated CI/CD app writes any
+`managed=yes` file into the application folder before Build/Start when it is missing, and shows
+every file (source, status, required keys, live content) in the per-application Config modal for
+troubleshooting. One table per application; `Path` is relative to the application folder.
+
+### <App Name> (<folder>)
+
+| Path | Source | Managed | Required Keys |
+|---|---|---|---|
+| .env | environment | yes | DATABASE_URL, REDIS_HOST, PORT |
+| .env-uat | env-file | no | DATABASE_URL, REDIS_HOST |
+
+For each `Managed=yes` row, follow it with the resolved file body (verbatim — credentials allowed
+under the dev-plaintext rule):
+
+```env path=.env
+DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb
+REDIS_HOST=127.0.0.1
+PORT=3000
+```
+
+Omit the fenced block for `env-file` rows (the file is used as-is on disk). If an application needs
+no config file, write `_No runtime config files._` under its heading.
+
 ## Infrastructure
 
 Supporting 3rd-party services shown status-only (TCP reachability) on the CI/CD app's
@@ -147,7 +230,7 @@ Infrastructure page. Leave the table body empty when the project declares no sup
 ## Rationale
 
 - <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
-```
+````
 
 Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
 only on COMPLETED.