@codepassion/skills 1.1.1 → 1.4.0

package/skills/c9n-deliverables/scripts/data-dictionary.cjs

@@ -0,0 +1,49 @@
+// Generate a data dictionary (Markdown) from a live MySQL/MariaDB INFORMATION_SCHEMA.
+// Schema only — no row data. Requires `mysql2` resolvable (run from a project that has it).
+//
+// Usage:  node data-dictionary.cjs <output.md>
+// Env (or a .env loaded via dotenv): SQL_HOST SQL_PORT SQL_USERNAME SQL_PASSWORD SQL_DATABASE_1
+//   Adjust the env var names below to match the target project's config.
+const mysql = require('mysql2/promise')
+const fs = require('fs')
+
+const OUT = process.argv[2]
+if (!OUT) { console.error('usage: node data-dictionary.cjs <output.md>'); process.exit(2) }
+try { require('dotenv').config({ path: process.env.ENV_FILE || '.env' }) } catch {}
+
+const cfg = {
+  host: process.env.SQL_HOST || process.env.DB_HOST,
+  port: +(process.env.SQL_PORT || process.env.DB_PORT || 3306),
+  user: process.env.SQL_USERNAME || process.env.DB_USER,
+  password: process.env.SQL_PASSWORD || process.env.DB_PASSWORD,
+  database: process.env.SQL_DATABASE_1 || process.env.DB_NAME,
+}
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+
+;(async () => {
+  const c = await mysql.createConnection({ ...cfg, connectTimeout: 10000 })
+  const [tables] = await c.query(
+    `SELECT TABLE_NAME, TABLE_COMMENT,
+            (SELECT COUNT(*) FROM information_schema.columns col WHERE col.table_schema=t.table_schema AND col.table_name=t.table_name) COLS
+     FROM information_schema.tables t WHERE t.table_schema=? AND t.table_type='BASE TABLE' ORDER BY t.table_name`, [cfg.database])
+  const [cols] = await c.query(
+    `SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT
+     FROM information_schema.columns WHERE table_schema=? ORDER BY TABLE_NAME, ORDINAL_POSITION`, [cfg.database])
+  const byTable = {}
+  for (const col of cols) (byTable[col.TABLE_NAME] ||= []).push(col)
+
+  let md = `# Data Dictionary\n\nGenerated from the live database schema (\`INFORMATION_SCHEMA\`). **${tables.length} tables.**\n\n## Tables\n\n`
+  for (const t of tables) md += `- [${t.TABLE_NAME}](#${t.TABLE_NAME.toLowerCase()}) (${t.COLS} columns)\n`
+  md += `\n---\n\n`
+  for (const t of tables) {
+    md += `### ${t.TABLE_NAME}\n\n`
+    if (t.TABLE_COMMENT) md += `${esc(t.TABLE_COMMENT)}\n\n`
+    md += `| Column | Type | Null | Key | Default | Extra | Comment |\n|--------|------|------|-----|---------|-------|--------|\n`
+    for (const col of byTable[t.TABLE_NAME] || [])
+      md += `| ${esc(col.COLUMN_NAME)} | \`${esc(col.COLUMN_TYPE)}\` | ${col.IS_NULLABLE} | ${esc(col.COLUMN_KEY)} | ${col.COLUMN_DEFAULT === null ? '' : esc(col.COLUMN_DEFAULT)} | ${esc(col.EXTRA)} | ${esc(col.COLUMN_COMMENT)} |\n`
+    md += `\n`
+  }
+  fs.writeFileSync(OUT, md)
+  console.log(`wrote ${OUT} — ${tables.length} tables, ${cols.length} columns`)
+  await c.end()
+})().catch((e) => { console.error('FAILED:', e.code || e.message); process.exit(1) })

package/skills/c9n-deliverables/scripts/export-openapi.cjs

@@ -0,0 +1,35 @@
+// Export the OpenAPI/Swagger spec from a NestJS app WITHOUT starting the HTTP server.
+// This is a TEMPLATE — adapt the DocumentBuilder block to match the project's main.ts.
+//
+// Usage:  node export-openapi.cjs <output.json>
+//
+// IMPORTANT notes learned the hard way:
+//  - Run against the COMPILED build (`nest build` -> dist), not ts-node. ts-node
+//    transpile-only mis-emits decorator metadata and TypeORM entity validation fails.
+//  - App bootstrap may require real resources (DB reachable, credential files present).
+//    Booting connects to the DB; use a dev DB, never production.
+//  - Match enableVersioning() and the DocumentBuilder config to the project's main.ts.
+const { NestFactory } = require('@nestjs/core')
+const { SwaggerModule, DocumentBuilder } = require('@nestjs/swagger')
+const { VersioningType } = require('@nestjs/common')
+const fs = require('fs')
+const path = require('path')
+require('reflect-metadata')
+try { require('dotenv').config({ path: process.env.ENV_FILE || '.env' }) } catch {}
+
+const OUT = process.argv[2] || 'openapi.json'
+// ADAPT: path to the compiled AppModule
+const { AppModule } = require(path.resolve(process.cwd(), 'dist/src/app.module'))
+
+;(async () => {
+  const app = await NestFactory.create(AppModule, { logger: ['error', 'warn'] })
+  // ADAPT: copy enableVersioning() from the project's main.ts if it uses versioning
+  app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1', prefix: 'api/v' })
+  // ADAPT: mirror the project's DocumentBuilder (title, version, auth schemes)
+  const config = new DocumentBuilder().setTitle('API').setVersion('1.0').build()
+  const document = SwaggerModule.createDocument(app, config)
+  fs.writeFileSync(path.resolve(process.cwd(), OUT), JSON.stringify(document, null, 2))
+  console.log(`wrote ${OUT} — ${Object.keys(document.paths || {}).length} paths`)
+  await app.close()
+  process.exit(0)
+})().catch((e) => { console.error('FAILED:', e?.message || e); process.exit(1) })

package/skills/c9n-deliverables/scripts/md-to-pdf.mjs

@@ -0,0 +1,73 @@
+// Render a Markdown file to PDF via a headless Chromium browser.
+// Handles Mermaid code fences (```mermaid) by rendering them to SVG client-side.
+//
+// Usage:  node md-to-pdf.mjs <input.md> <output.pdf>
+//
+// No install required if a Chromium-family browser is present (Brave/Chrome/Edge/Chromium).
+// Mermaid + marked load from CDN, so the machine needs internet for diagram rendering.
+//
+// SECURITY: input is expected to be FIRST-PARTY documentation you generated for the
+// delivery (the project's own docs), not untrusted third-party Markdown. Mermaid runs with
+// securityLevel:'strict' (no click handlers / inline HTML in diagrams). Markdown is still
+// rendered with raw HTML allowed — do not feed this untrusted Markdown.
+//
+// NOTE: For very WIDE diagrams (many nodes in one row), prefer `flowchart TB` / vertical
+// ER layouts in the source — wide diagrams scale down to an illegible strip at page width.
+import { readFileSync, writeFileSync, mkdtempSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, basename } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const [src, out] = process.argv.slice(2)
+if (!src || !out) { console.error('usage: node md-to-pdf.mjs <input.md> <output.pdf>'); process.exit(2) }
+
+const BROWSERS = [
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+]
+const browser = BROWSERS.find(existsSync)
+if (!browser) { console.error('No Chromium-family browser found. Install Chrome/Brave/Chromium.'); process.exit(1) }
+
+const md = readFileSync(src, 'utf8')
+const html = `<!doctype html><html><head><meta charset="utf-8">
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+<style>
+  @page { margin: 18mm 16mm; }
+  body { font: 14px/1.6 -apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif; color:#1a1a1a; max-width:820px; margin:0 auto; }
+  h1 { font-size:26px; border-bottom:2px solid #222; padding-bottom:6px; }
+  h2 { font-size:20px; margin-top:28px; border-bottom:1px solid #ddd; padding-bottom:4px; }
+  h3 { font-size:16px; margin-top:20px; }
+  table { border-collapse:collapse; width:100%; margin:12px 0; font-size:13px; }
+  th,td { border:1px solid #ccc; padding:6px 10px; text-align:left; vertical-align:top; }
+  th { background:#f4f4f4; }
+  code { background:#f0f0f0; padding:1px 5px; border-radius:3px; font-size:12px; }
+  pre { background:#f6f8fa; padding:12px; border-radius:6px; overflow:auto; }
+  pre code { background:none; padding:0; }
+  .mermaid { text-align:center; margin:16px 0; }
+  blockquote { border-left:4px solid #ccc; margin:12px 0; padding:4px 14px; color:#555; }
+</style></head><body>
+<div id="out"></div>
+<script type="text/markdown" id="src">${md.replace(/<\/script>/g, '<\\/script>')}</script>
+<script>
+  document.getElementById('out').innerHTML = marked.parse(document.getElementById('src').textContent);
+  document.querySelectorAll('code.language-mermaid').forEach(c => {
+    const d = document.createElement('div'); d.className='mermaid'; d.textContent=c.textContent;
+    c.closest('pre').replaceWith(d);
+  });
+  mermaid.initialize({ startOnLoad:false, securityLevel:'strict' });
+  mermaid.run();
+</script></body></html>`
+
+const tmp = mkdtempSync(join(tmpdir(), 'md2pdf-'))
+const htmlPath = join(tmp, basename(src) + '.html')
+writeFileSync(htmlPath, html)
+execFileSync(browser, [
+  '--headless', '--disable-gpu', '--no-pdf-header-footer',
+  '--run-all-compositor-stages-before-draw', '--virtual-time-budget=20000',
+  `--print-to-pdf=${out}`, `file://${htmlPath}`,
+], { stdio: 'inherit' })
+console.log('wrote', out)

package/skills/c9n-deliverables/scripts/openapi-to-pdf.mjs

@@ -0,0 +1,78 @@
+// Render an OpenAPI 3 spec to a print-friendly PDF (no lazy loading — full content,
+// unlike Redoc/Swagger UI which lazy-render and truncate when printed).
+//
+// Usage:  node openapi-to-pdf.mjs <openapi.json> <output.pdf> [guide.md]
+//   guide.md (optional) is prepended as an intro section before the endpoint reference.
+//
+// SECURITY: the spec and guide.md are expected to be FIRST-PARTY artifacts you generated
+// for the delivery, not untrusted input. The guide Markdown is rendered with raw HTML
+// allowed — do not pass an untrusted guide file.
+import { readFileSync, writeFileSync, mkdtempSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const [specPath, out, guidePath] = process.argv.slice(2)
+if (!specPath || !out) { console.error('usage: node openapi-to-pdf.mjs <openapi.json> <output.pdf> [guide.md]'); process.exit(2) }
+
+const BROWSERS = [
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+]
+const browser = BROWSERS.find(existsSync)
+if (!browser) { console.error('No Chromium-family browser found.'); process.exit(1) }
+
+const spec = JSON.parse(readFileSync(specPath, 'utf8'))
+const guideMd = guidePath && existsSync(guidePath) ? readFileSync(guidePath, 'utf8').replace(/^# .*\r?\n/, '') : ''
+const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]))
+const refName = (r) => (r?.$ref ? r.$ref.split('/').pop() : null)
+const schemaType = (s) => !s ? '' : s.$ref ? refName(s) : s.type === 'array' ? `${schemaType(s.items)}[]` : s.enum ? `enum(${s.enum.map(esc).join(', ')})` : s.format ? `${s.type}<${s.format}>` : (s.type || 'object')
+
+const methods = ['get', 'post', 'put', 'patch', 'delete']
+const groups = {}
+for (const [p, item] of Object.entries(spec.paths || {}))
+  for (const m of methods) { const op = item[m]; if (!op) continue; const tag = (op.tags && op.tags[0]) || 'default'; (groups[tag] ||= []).push({ m, p, op }) }
+
+const pTable = (ps = []) => !ps.length ? '' : `<table class="p"><thead><tr><th>Name</th><th>In</th><th>Req</th><th>Type</th></tr></thead><tbody>${ps.map((pa) => `<tr><td><code>${esc(pa.name)}</code></td><td>${esc(pa.in)}</td><td>${pa.required ? 'yes' : 'no'}</td><td>${esc(schemaType(pa.schema))}</td></tr>`).join('')}</tbody></table>`
+const bBlock = (rb) => { if (!rb) return ''; const j = rb.content && (rb.content['application/json'] || Object.values(rb.content)[0]); return `<div class="body"><span class="lbl">Request body${rb.required ? ' (required)' : ''}:</span> <code>${esc(j ? schemaType(j.schema) : 'object')}</code></div>` }
+const rBlock = (r = {}) => { const rows = Object.entries(r).map(([c, v]) => `<tr><td><code>${esc(c)}</code></td><td>${esc(v.description || '')}</td></tr>`).join(''); return rows ? `<table class="p"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table>` : '' }
+
+let body = ''
+for (const tag of Object.keys(groups).sort()) {
+  body += `<h2>${esc(tag)}</h2>`
+  for (const { m, p, op } of groups[tag])
+    body += `<div class="op"><div class="line"><span class="m ${m}">${m.toUpperCase()}</span><code class="path">${esc(p)}</code></div>${op.summary ? `<div class="sum">${esc(op.summary)}</div>` : ''}${op.description ? `<div class="desc">${esc(op.description)}</div>` : ''}${pTable(op.parameters)}${bBlock(op.requestBody)}${rBlock(op.responses)}</div>`
+}
+const opCount = Object.values(spec.paths || {}).reduce((n, it) => n + methods.filter((m) => it[m]).length, 0)
+
+const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+@page { margin: 16mm 14mm; }
+body { font: 12px/1.5 -apple-system,Segoe UI,Roboto,Arial,sans-serif; color:#1a1a1a; max-width:860px; margin:0 auto; }
+h1 { font-size:24px; border-bottom:2px solid #222; padding-bottom:6px; }
+h2 { font-size:18px; margin:26px 0 10px; border-bottom:1px solid #ddd; padding-bottom:4px; break-after:avoid; }
+.op { border:1px solid #e3e3e3; border-radius:6px; padding:10px 12px; margin:10px 0; break-inside:avoid; }
+.line { display:flex; align-items:center; gap:8px; }
+.m { color:#fff; font-weight:700; font-size:11px; padding:2px 8px; border-radius:4px; }
+.m.get{background:#2e8b57}.m.post{background:#1f6feb}.m.put{background:#b8860b}.m.patch{background:#8250df}.m.delete{background:#cf222e}
+.sum { font-weight:600; margin:6px 0 2px; } .desc { color:#555; margin:2px 0; }
+table.p { border-collapse:collapse; width:100%; margin:8px 0; font-size:11px; }
+table.p th, table.p td { border:1px solid #ddd; padding:4px 8px; text-align:left; } table.p th { background:#f5f5f5; }
+.body { margin:6px 0; } .lbl { color:#555; } code { background:#f0f0f0; padding:1px 4px; border-radius:3px; }
+.meta { color:#555; margin-bottom:18px; } .section-break { break-before:page; }
+.guide table { border-collapse:collapse; width:100%; margin:8px 0; font-size:12px; }
+.guide th, .guide td { border:1px solid #ccc; padding:5px 9px; text-align:left; } .guide th { background:#f4f4f4; }
+.guide blockquote { border-left:4px solid #ccc; margin:10px 0; padding:4px 14px; color:#555; }
+</style>${guideMd ? '<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>' : ''}</head><body>
+<h1>${esc(spec.info?.title || 'API')} — API Documentation</h1>
+<div class="meta">Version ${esc(spec.info?.version || '')} · OpenAPI ${esc(spec.openapi || '')} · ${Object.keys(spec.paths || {}).length} paths · ${opCount} operations</div>
+${guideMd ? `<div class="guide" id="guide"></div><script type="text/markdown" id="g">${guideMd.replace(/<\/script>/g, '<\\/script>')}</script><script>document.getElementById('guide').innerHTML=marked.parse(document.getElementById('g').textContent)</script><h1 class="section-break">Endpoint Reference</h1>` : ''}
+${body}
+</body></html>`
+
+const tmp = mkdtempSync(join(tmpdir(), 'oa2pdf-'))
+const htmlPath = join(tmp, 'api.html')
+writeFileSync(htmlPath, html)
+execFileSync(browser, ['--headless', '--disable-gpu', '--no-pdf-header-footer', '--run-all-compositor-stages-before-draw', '--virtual-time-budget=15000', `--print-to-pdf=${out}`, `file://${htmlPath}`], { stdio: 'inherit' })
+console.log('wrote', out)

package/skills/c9n-deliverables/scripts/snapshot-source.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Produce a clean source-code snapshot using git archive.
+# git archive only includes tracked files — node_modules, .env, dist, secrets are
+# excluded automatically (assuming they are gitignored / untracked).
+#
+# Usage:  snapshot-source.sh <repo-root> <output.zip>
+set -euo pipefail
+
+REPO_ROOT="${1:-$PWD}"
+OUT="${2:?usage: snapshot-source.sh <repo-root> <output.zip>}"
+
+# Resolve a relative <output.zip> against the caller's cwd, then use `git -C` so we
+# never change the caller's working directory. (A bare relative --output under
+# `git -C`/`cd` would surprisingly land inside the repo root.)
+case "$OUT" in /*) ;; *) OUT="$PWD/$OUT" ;; esac
+
+if [ ! -d "$REPO_ROOT/.git" ]; then
+  echo "Error: $REPO_ROOT is not a git repository." >&2
+  exit 1
+fi
+
+git -C "$REPO_ROOT" archive --format=zip --output "$OUT" HEAD
+echo "Source snapshot written to: $OUT"

package/skills/c9n-pipeline/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: c9n-pipeline
+description: Bootstrap the C9N CI/CD pipeline INTO a Turborepo/Bun monorepo — generates the per-repo GitHub Actions (CI + tag-driven Deployment that call the org codepassion-team/cicd reusable workflows), per-app Dockerfiles (Elysia→bun-compile, Next.js standalone+runtime-env, generic service), and .dockerignore; then walks the developer through the out-of-repo ops (GitHub Environments, Coolify resources, ghcr pull, the PORT=3000 web footgun) and verifies the live deploy. Use when setting up CI/CD on a new C9N project, "add github actions", "set up deployment", "wire up Coolify", or porting the Smiley pipeline to another repo. Complements c9n-semver-deployment (owns the tag->env mapping) and c9n-spec (scaffolds docs, not pipelines).
+---
+
+Bootstraps the Code Passion (C9N) CI/CD pipeline into a target repo so a new project deploys the
+same way as the reference implementation (Smiley): **one image per app, built once at the Alpha
+tag, redeployed to Beta/Production by base tag**, env injected at runtime by Coolify. The heavy
+lifting lives in the org reusable workflows `codepassion-team/cicd/.github/workflows/{build,deploy}.yml`
+— the per-repo files this skill generates just call them. The skill's real value is **Phase 3**:
+the interactive ops checklist that encodes every footgun the Smiley setup hit.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project. The Next.js wiring is an **edit** of files the dev
+already owns, not a file drop (see Phase 2).
+
+## What gets generated
+
+| Path | Template | When |
+|------|----------|------|
+| `<app>/Dockerfile` | `Dockerfile.api` | app has `elysia` |
+| `<app>/Dockerfile` | `Dockerfile.web` | app has `next` |
+| `<app>/Dockerfile` | `Dockerfile.service` | any other deployable app (worker, plain Bun) |
+| `.dockerignore` | `dockerignore` | always (repo root) |
+| `.github/workflows/ci.yml` | `workflows/ci.yml` (+ `_migration-check.partial` if DB) | always |
+| `.github/workflows/deployment.yml` | `workflows/deployment.yml` (+ `_build-job`/`_deploy-job` partials) | always |
+| `<web>/next.config.js` | **edit, not copy** | per web app |
+| `<web>/app/layout.tsx` | **edit, not copy** | per web app |
+
+## Workflow
+
+Run in order; this is a table of contents — rules are below.
+
+1. **Detect (Phase 1).** Scan `apps/*/package.json`. Classify each: `next`→web, `elysia`→api, else
+   →service. Detect DB by **real artifacts** — a migration-generate script in some `package.json`
+   AND a migrations dir on disk — capture their actual names; never assume `drizzle:generate` /
+   `packages/supabase/migrations`. Read root `package.json` for the Bun version / lockfile name.
+   Ask which environments exist (Alpha / Beta / Production). **Print the detected plan and confirm
+   before writing anything.**
+2. **Generate (Phase 2).** Copy templates with tokens substituted. **Diff/confirm per file** — if a
+   target exists, show the diff and ask overwrite/skip/merge; never blind-clobber; leave unrelated
+   files (a hand-kept `staging.yaml`) alone. Then do the **web edits** (below). Run the web build
+   once to prove nothing is baked.
+3. **Checklist (Phase 3).** Walk the dev interactively through the out-of-repo ops (below). This is
+   the deliverable.
+4. **Verify (Phase 4).** After the dev confirms the ops are done, push a tag (or reuse one), watch
+   the Actions run, then `curl` each deployed URL per environment and report pass/fail per app.
+
+## Token substitution
+
+| Token | Source |
+|-------|--------|
+| `{{PACKAGE_NAME}}` | `<project>-<appkey>`, e.g. `smiley-web`. Lowercase. This is the ghcr image name and the `package_name` workflow input. |
+| `{{APP_DIR}}` | The app's path, e.g. `apps/web`. |
+| `{{APP_KEY}}` | Short lowercase id unique per app: `api`, `web`, `worker`. Used in job names. |
+| `{{APP_PORT}}` | `3001` api · `3000` web · service's listen port (drop `EXPOSE` for a portless worker). |
+| `{{BUN_VERSION}}` | Pin from root toolchain, e.g. `1.3.10`. Same across all Dockerfiles. |
+| `{{WORKSPACE_MANIFEST_COPIES}}` | **web template only:** one `COPY <app>/package.json ./<app>/package.json` line **per app** — the `deps` stage runs `bun install` before `COPY . .`, so it needs every workspace manifest to resolve the graph. The api/service compile templates copy only the built app's manifest (matches Smiley's api Dockerfile; avoids pulling a sibling app's postinstall without its src). |
+| `{{MIGRATION_CHECK}}` | `_migration-check.partial.yml` with `{{MIGRATION_SCRIPT}}`/`{{MIGRATIONS_DIR}}` filled, **or empty string** if no DB. |
+| `{{ORG_REF}}` | The org reusable-workflow ref — currently `turborepo`. One place; bump here if the org repo retags. |
+| `{{BUILD_JOBS}}` / `{{DEPLOY_JOBS}}` | Stamp `_build-job.partial` once per app (Alpha only) and `_deploy-job.partial` once per app per environment, pruning unused envs. |
+| `{{DEPLOY_NAME}}` | The org `deploy.yml` `name` input → uppercased to `<NAME>_UUID`. **Only `API` and `WEB` are wired** in the org deploy.yml (see Gotchas). |
+
+## Web edits (surgical — not a file drop)
+
+For each **web** app, edit the files the dev owns; fail loudly if they can't be parsed rather than
+overwrite:
+
+- `next.config.js` — add `output: "standalone"`, `outputFileTracingRoot` (monorepo root), and
+  `transpilePackages` for the workspace packages the app imports.
+- `app/layout.tsx` — add `<head><PublicEnvScript /></head>` (`import { PublicEnvScript } from
+  "next-runtime-env"`). Client code reads public config with `env("NEXT_PUBLIC_X")`, **not**
+  `process.env` (which bakes at build → undefined at runtime).
+- Flag `next-runtime-env` as a dependency to add — **do not run `bun add` yourself**; tell the dev.
+- **Caveat:** runtime values only reach the browser on non-statically-prerendered pages. A page that
+  reads runtime public env must opt out of static caching (`export const dynamic = "force-dynamic"`)
+  or rely on `<PublicEnvScript>` keeping the document dynamic. Note this so future feature work
+  doesn't silently bake a static page.
+
+## Phase 3 — interactive ops checklist (the deliverable)
+
+Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
+
+**Repo prerequisites**
+- A **`develop` branch must exist** — `build.yml` commits the version bump and does
+  `git pull --rebase origin develop` / `push HEAD:develop`. No develop branch → build fails.
+- Tags drive deploys; the exact tag→env mapping is **c9n-semver-deployment** (don't restate it).
+
+**Per environment** — create a GitHub **Environment** named exactly `Alpha` / `Beta` / `Production`:
+- Variables: `COOLIFY_RESOURCE_API_UUID`, `COOLIFY_RESOURCE_WEB_UUID` (the Coolify app UUIDs;
+  `deploy.yml` resolves `${NAME}_UUID`), and `TURBO_TEAM`.
+- Secrets: `COOLIFY_TOKEN` (Coolify API bearer) and `TURBO_TOKEN`. `GITHUB_TOKEN` is automatic
+  (ghcr push uses it; the build job already declares `packages: write`).
+
+**Coolify** (one resource per app per env): source = Docker image
+`ghcr.io/codepassion-team/{{PACKAGE_NAME}}:<base_tag>`; copy each resource's UUID into the matching
+env variable above. Caddy `reverse_proxy <app>:<port>` (api `:3001`, web `:3000`).
+
+**ghcr** — packages are **private**: give Coolify a registry pull credential (or set package
+visibility), or the image pull silently fails.
+
+**Web runtime env in Coolify** (the scars):
+- `PORT=3000` — Next standalone obeys `PORT`; Coolify defaults it to `80`, which 502s behind a
+  Caddy `:3000` proxy. This is the single most common web-deploy failure.
+- `HOSTNAME=0.0.0.0`.
+- The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+
+## Phase 4 — verify
+
+Push a `v*.*.*` tag (or reuse one), watch the run (`gh run watch`), then for each app per env
+`curl -so /dev/null -w "%{http_code}"` the deployed URL (e.g. `https://api.<proj>.alpha.c9n.co`,
+`https://<proj>.alpha.c9n.co`) and confirm `200`. Report a clean pass/fail table. Don't call it done
+on a green Actions run alone — the 502 class only shows at the live URL.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body. Install via `install.sh claude` (or `project`/`codex`) so the
+  templates come along — same limitation as `c9n-spec`/`c9n-deliverables`.
+- **Org deploy.yml wires only `API_UUID` + `WEB_UUID`.** A third app type (worker) needs a PR to
+  `codepassion-team/cicd` adding `COOLIFY_RESOURCE_<NAME>_UUID` to deploy.yml's `env:` block. Flag
+  this; don't generate a deploy job that silently can't resolve its UUID.
+- **Build once, deploy by base tag.** build.yml strips `-alpha`/`-rc.*`; deploy.yml also strips
+  `-beta.*`. So `v1.2.3` (Alpha) and a later `v1.2.3-beta.1` release both resolve base tag `v1.2.3`
+  and redeploy the same image. Beta/Prod must have an Alpha build of that base version in ghcr first.
+- **`.dockerignore` matters.** Without it, the host's `node_modules` (wrong platform) leaks into the
+  build context and clobbers the linux deps → "failed to load next.config". The template ships it.
+- **Don't touch `.env*`.** Generate `.dockerignore` to exclude them; never read or write env files.

package/skills/c9n-pipeline/templates/Dockerfile.api

@@ -0,0 +1,49 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (Elysia BFF) — compiled to a single Bun binary, run on
+# debian slim. Generated by c9n-pipeline; tune freely after.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS build
+
+WORKDIR /app
+
+# Root manifests + lockfile
+COPY package.json bun.lock ./
+
+# This app's manifest + shared packages (compile needs only this member's graph)
+COPY {{APP_DIR}}/package.json ./{{APP_DIR}}/package.json
+COPY packages/ ./packages/
+
+# Source needed to compile (copied before install so workspace links resolve)
+COPY {{APP_DIR}}/src ./{{APP_DIR}}/src
+
+RUN bun install
+
+ENV NODE_ENV=production
+
+# Compile the API to a standalone binary from the repo root
+RUN bun build \
+    --compile \
+    --minify-whitespace \
+    --minify-syntax \
+    --target=bun \
+    --outfile /app/server \
+    ./{{APP_DIR}}/src/index.ts
+
+# Runtime image — debian slim for compiled-Bun-binary compatibility
+FROM debian:bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/server ./server
+RUN chmod +x ./server
+
+ENV NODE_ENV=production
+
+EXPOSE {{APP_PORT}}
+
+CMD ["./server"]

package/skills/c9n-pipeline/templates/Dockerfile.service

@@ -0,0 +1,45 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (generic Bun service / worker) — compiled to a single Bun
+# binary, run on debian slim. Generated by c9n-pipeline.
+# A worker with no HTTP port: drop the EXPOSE line and skip its Coolify domain.
+# NOTE: the org deploy.yml only wires API_UUID + WEB_UUID — a third app type
+# needs a PR to codepassion-team/cicd to add its COOLIFY_RESOURCE_<NAME>_UUID.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS build
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+COPY {{APP_DIR}}/package.json ./{{APP_DIR}}/package.json
+COPY packages/ ./packages/
+COPY {{APP_DIR}}/src ./{{APP_DIR}}/src
+
+RUN bun install
+
+ENV NODE_ENV=production
+
+RUN bun build \
+    --compile \
+    --minify-whitespace \
+    --minify-syntax \
+    --target=bun \
+    --outfile /app/server \
+    ./{{APP_DIR}}/src/index.ts
+
+FROM debian:bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/server ./server
+RUN chmod +x ./server
+
+ENV NODE_ENV=production
+
+EXPOSE {{APP_PORT}}
+
+CMD ["./server"]

package/skills/c9n-pipeline/templates/Dockerfile.web

@@ -0,0 +1,50 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (Next.js app) — Bun multi-stage build.
+# Public env is read at RUNTIME via next-runtime-env (<PublicEnvScript>), so this
+# image bakes no NEXT_PUBLIC_* — Coolify injects them at run, like the API image.
+# Generated by c9n-pipeline; see the ADR this skill points you to.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS base
+WORKDIR /app
+
+# Install dependencies with bun
+FROM base AS deps
+COPY package.json bun.lock ./
+{{WORKSPACE_MANIFEST_COPIES}}
+COPY packages/ ./packages/
+RUN bun install
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Next.js expects {{APP_DIR}}/.env to exist; intentionally empty — no public env
+# is baked at build (it is injected at runtime via next-runtime-env).
+RUN touch {{APP_DIR}}/.env
+
+RUN cd {{APP_DIR}} && bun run build
+
+# Production image — serve the Next.js standalone output
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    PORT={{APP_PORT}} \
+    HOSTNAME="0.0.0.0"
+
+RUN groupadd --system --gid 1001 nodejs && \
+    useradd --system --uid 1001 nextjs
+
+# Leverage Next.js output file tracing to keep the image small
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/.next/static ./{{APP_DIR}}/.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/public ./{{APP_DIR}}/public
+
+USER nextjs
+
+EXPOSE {{APP_PORT}}
+
+CMD ["bun", "{{APP_DIR}}/server.js"]

package/skills/c9n-pipeline/templates/dockerignore

@@ -0,0 +1,18 @@
+.next
+node_modules
+**/node_modules
+**/.next
+**/dist
+.git
+.turbo
+**/.turbo
+npm-debug.log
+yarn-error.log
+bun-debug.log
+.env
+**/.env
+.env.*
+**/.env.*
+
+# Next.js telemetry
+.next/telemetry

package/skills/c9n-pipeline/templates/workflows/_build-job.partial.yml

@@ -0,0 +1,13 @@
+# One BUILD job per app. Alpha only — the image is built once at the tag push
+# and redeployed to Beta/Production by base tag (no rebuild). {{APP_KEY}} is a
+# lowercase id unique per app (e.g. api, web). {{ORG_REF}} is the org workflow
+# ref (e.g. turborepo) — keep it identical across every job in this file.
+  build-{{APP_KEY}}-alpha:
+    name: Build
+    if: github.event_name != 'release' && startsWith(github.ref, 'refs/tags/v')
+    uses: codepassion-team/cicd/.github/workflows/build.yml@{{ORG_REF}}
+    with:
+      environment: Alpha
+      build_path: ./{{APP_DIR}}
+      package_name: {{PACKAGE_NAME}}
+    secrets: inherit

package/skills/c9n-pipeline/templates/workflows/_deploy-job.partial.yml

@@ -0,0 +1,17 @@
+# One DEPLOY job per app per environment. {{DEPLOY_NAME}} is the org deploy.yml
+# name input that resolves the Coolify UUID var: it is uppercased to
+# ${{DEPLOY_NAME_UPPER}}_UUID, so it MUST be a key the org deploy.yml wires
+# (currently only API and WEB). Stamp the right {{IF_CONDITION}} per environment
+# from c9n-semver-deployment:
+#   Alpha       -> needs: build-{{APP_KEY}}-alpha ; if: github.event_name != 'release' && startsWith(github.ref, 'refs/tags/v')
+#   Beta        -> (no needs) ; if: github.event_name == 'release' && github.event.release.prerelease == true && startsWith(github.event.release.tag_name, 'v')
+#   Production  -> (no needs) ; if: github.event_name == 'release' && github.event.release.prerelease == false && startsWith(github.event.release.tag_name, 'v')
+  deploy-{{APP_KEY}}-{{ENV_KEY}}:
+    name: Deploy
+    if: {{IF_CONDITION}}
+    {{NEEDS_LINE}}
+    uses: codepassion-team/cicd/.github/workflows/deploy.yml@{{ORG_REF}}
+    with:
+      name: {{DEPLOY_NAME}}
+      environment: {{ENVIRONMENT}}
+    secrets: inherit

package/skills/c9n-pipeline/templates/workflows/_migration-check.partial.yml

@@ -0,0 +1,16 @@
+# Inject in place of {{MIGRATION_CHECK}} in ci.yml ONLY when a DB is detected
+# (a migration-generate script exists in some package.json AND a migrations dir
+# exists). Substitute {{MIGRATION_SCRIPT}} and {{MIGRATIONS_DIR}} with the real
+# detected names — do not assume drizzle:generate / packages/supabase/migrations.
+# If no DB, {{MIGRATION_CHECK}} is the empty string and ci.yml ends at Build.
+      - name: Verify migrations are up to date
+        run: bun run {{MIGRATION_SCRIPT}} -- --name check
+      - name: Check for uncommitted migration changes
+        run: |
+          if git diff --name-only --exit-code {{MIGRATIONS_DIR}}; then
+            echo "Migrations are up to date"
+          else
+            echo "Detected uncommitted migration changes. Run 'bun run {{MIGRATION_SCRIPT}}' locally and commit the result."
+            git diff {{MIGRATIONS_DIR}}
+            exit 1
+          fi

package/skills/c9n-pipeline/templates/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+on:
+  push:
+    branches: ['main', 'develop']
+  pull_request:
+    types: [opened, synchronize]
+jobs:
+  build:
+    name: Check
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Cache turbo build setup
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: ${{ runner.os }}-turbo-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-turbo-
+      - uses: oven-sh/setup-bun@v2
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Install dependencies
+        run: bun install
+      - name: Check types
+        run: bun run check-types
+      - name: Build
+        run: bun run build
+{{MIGRATION_CHECK}}