@codepassion/skills 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
   "license": "MIT",
   "type": "module",

package/skills/c9n/SKILL.md

@@ -271,12 +271,20 @@ already owns, not a file drop (see Phase 2).
 
 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.**
+1. **Detect (Phase 1).** First decide the repo shape:
+   - **Monorepo** — `apps/` and/or `turbo.json` exist. Scan `apps/*/package.json`, classify each:
+     `next`→web, `elysia`→api, else→service. `{{APP_DIR}}` = `apps/<name>`.
+   - **Single-app** — no `apps/`, no `turbo.json`; the deployable app is the repo root. Classify the
+     root `package.json` (`next`→web, etc.). `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = the repo name
+     (no `-web` suffix needed), and the **single-app template variants** apply (see "Single-app repos"
+     below) — drop the workspace-manifest copies, `outputFileTracingRoot`, `transpilePackages`, and
+     the `apps/web/` path segments. The generated `ci.yml` also drops Turbo (see that template's note).
+
+   Then 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 the app's `package.json` for the Bun version / lockfile name
+   (but **pin ≥ 1.3.10** — see `{{BUN_VERSION}}`). 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
@@ -291,11 +299,11 @@ Run in order; this is a table of contents — rules are below.
 | 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_DIR}}` | The app's path, e.g. `apps/web`. **Single-app repo: `.`** (the app is the repo root — this leaves valid `./.next/...` paths in the template). |
 | `{{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). |
+| `{{BUN_VERSION}}` | **Pin ≥ 1.3.10** (same across all Dockerfiles). Do **not** copy the host's `bun --version` — 1.2.x breaks `next build` on Linux with `TypeError: Expected CommonJS module to have a function wrapper` (edge/jest-worker; only shows on Linux, not macOS). |
+| `{{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). **Single-app repo: empty string** (root `package.json` + `bun.lock` are already copied; there is no `packages/` — also delete the `COPY packages/ ./packages/` line). |
 | `{{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. |
@@ -306,17 +314,46 @@ Run in order; this is a table of contents — rules are below.
 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.
+- `next.config.js` — add `output: "standalone"`. **Monorepo only:** also add `outputFileTracingRoot`
+  (monorepo root) and `transpilePackages` for the workspace packages the app imports. **Single-app:
+  omit both** (root app traces natively; no workspace packages).
 - `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).
+  "next-runtime-env"`).
+- **Convert EVERY `process.env.NEXT_PUBLIC_*` read to `env("NEXT_PUBLIC_X")`** — not just client
+  components. Next **inlines every `process.env.NEXT_PUBLIC_*` literal at build time in SERVER code and
+  middleware too**, so any read left as `process.env` bakes the build value (or a build-time
+  placeholder) into the server/middleware bundle and runtime injection can't override it. This is the
+  #1 time-sink: a stray `process.env.NEXT_PUBLIC_SUPABASE_URL` in `middleware.ts` bakes the placeholder
+  → `supabase.auth.getUser()` fails → **auth redirect loop** that only shows in the container, not
+  locally. Convert: client components, **server components, route handlers (`app/api/**`), middleware,
+  and any t3-env `runtimeEnv` mapping**. Non-public server vars (`DATABASE_URL`, `*_SERVICE_KEY`) stay
+  on `process.env` — they aren't inlined and are present at runtime.
+- **Phase-2 gate — must pass before you call the web edits done:**
+  `grep -rn 'process.env.NEXT_PUBLIC' {{APP_DIR}}` (the app dir — `.` for single-app, `apps/web` for a
+  monorepo app; not every repo has a `src/`) returns **nothing**. Any hit is a latent runtime bug.
 - 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.
 
+## Single-app repos (no `apps/`, no `turbo.json`)
+
+The templates are monorepo-shaped; one set of token substitutions makes them serve a root-level single
+app. Apply these deltas (verified on `ddg-jewelry-admin`):
+
+- **Tokens:** `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = repo name (no `-web` suffix),
+  `{{WORKSPACE_MANIFEST_COPIES}}` = empty.
+- **`Dockerfile.web`:** delete the `COPY packages/ ./packages/` line (no `packages/`). The runner
+  `COPY` lines collapse to `.next/standalone ./`, `.next/static ./.next/static`, `public ./public`
+  (the `{{APP_DIR}}=.` substitution yields valid `./.next/...` — fine to simplify).
+- **`next.config`:** `output: "standalone"` only — no `outputFileTracingRoot`, no `transpilePackages`.
+- **`ci.yml`:** drop the Turbo `env:`, the `.turbo` cache step, and swap `bun run check-types` for
+  `bunx tsc --noEmit` if the repo has no `check-types` script (single apps usually don't).
+- **Runner (optional but recommended):** a single Next app deploys cleanly on a Node runner
+  (`node:22-alpine` or `gcr.io/distroless/nodejs22-debian12`, `CMD ["server.js"]`). Distroless cuts the
+  image ~4× and drops the runner CVEs (seen on `ddg-jewelry-admin`).
+
 ## Phase 3 — interactive ops checklist (the deliverable)
 
 Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
@@ -342,8 +379,14 @@ 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`.
+- **Coolify `Ports Exposes` (General page) is a SEPARATE setting from the `PORT` env** — it defaults
+  to `80` and must be set to the app port (`3000`). With `PORT=3000` but Ports Exposes still `80`, the
+  deploy log warns `PORT (3000) does not match configured ports_exposes: 80` and the proxy 502s. Fix
+  both.
+- `HOSTNAME=0.0.0.0` — the Dockerfile already bakes this; only set it if something overrides it.
 - The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+- **Set ALL env values UNQUOTED** (public and server alike) — Coolify passes values literally, so a
+  quoted `DATABASE_URL="…"` keeps the quotes and breaks `new URL()` (`ERR_INVALID_URL`).
 
 ## Phase 4 — verify
 

package/skills/c9n-pipeline/SKILL.md

@@ -31,12 +31,20 @@ already owns, not a file drop (see Phase 2).
 
 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.**
+1. **Detect (Phase 1).** First decide the repo shape:
+   - **Monorepo** — `apps/` and/or `turbo.json` exist. Scan `apps/*/package.json`, classify each:
+     `next`→web, `elysia`→api, else→service. `{{APP_DIR}}` = `apps/<name>`.
+   - **Single-app** — no `apps/`, no `turbo.json`; the deployable app is the repo root. Classify the
+     root `package.json` (`next`→web, etc.). `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = the repo name
+     (no `-web` suffix needed), and the **single-app template variants** apply (see "Single-app repos"
+     below) — drop the workspace-manifest copies, `outputFileTracingRoot`, `transpilePackages`, and
+     the `apps/web/` path segments. The generated `ci.yml` also drops Turbo (see that template's note).
+
+   Then 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 the app's `package.json` for the Bun version / lockfile name
+   (but **pin ≥ 1.3.10** — see `{{BUN_VERSION}}`). 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
@@ -51,11 +59,11 @@ Run in order; this is a table of contents — rules are below.
 | 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_DIR}}` | The app's path, e.g. `apps/web`. **Single-app repo: `.`** (the app is the repo root — this leaves valid `./.next/...` paths in the template). |
 | `{{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). |
+| `{{BUN_VERSION}}` | **Pin ≥ 1.3.10** (same across all Dockerfiles). Do **not** copy the host's `bun --version` — 1.2.x breaks `next build` on Linux with `TypeError: Expected CommonJS module to have a function wrapper` (edge/jest-worker; only shows on Linux, not macOS). |
+| `{{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). **Single-app repo: empty string** (root `package.json` + `bun.lock` are already copied; there is no `packages/` — also delete the `COPY packages/ ./packages/` line). |
 | `{{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. |
@@ -66,17 +74,46 @@ Run in order; this is a table of contents — rules are below.
 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.
+- `next.config.js` — add `output: "standalone"`. **Monorepo only:** also add `outputFileTracingRoot`
+  (monorepo root) and `transpilePackages` for the workspace packages the app imports. **Single-app:
+  omit both** (root app traces natively; no workspace packages).
 - `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).
+  "next-runtime-env"`).
+- **Convert EVERY `process.env.NEXT_PUBLIC_*` read to `env("NEXT_PUBLIC_X")`** — not just client
+  components. Next **inlines every `process.env.NEXT_PUBLIC_*` literal at build time in SERVER code and
+  middleware too**, so any read left as `process.env` bakes the build value (or a build-time
+  placeholder) into the server/middleware bundle and runtime injection can't override it. This is the
+  #1 time-sink: a stray `process.env.NEXT_PUBLIC_SUPABASE_URL` in `middleware.ts` bakes the placeholder
+  → `supabase.auth.getUser()` fails → **auth redirect loop** that only shows in the container, not
+  locally. Convert: client components, **server components, route handlers (`app/api/**`), middleware,
+  and any t3-env `runtimeEnv` mapping**. Non-public server vars (`DATABASE_URL`, `*_SERVICE_KEY`) stay
+  on `process.env` — they aren't inlined and are present at runtime.
+- **Phase-2 gate — must pass before you call the web edits done:**
+  `grep -rn 'process.env.NEXT_PUBLIC' {{APP_DIR}}` (the app dir — `.` for single-app, `apps/web` for a
+  monorepo app; not every repo has a `src/`) returns **nothing**. Any hit is a latent runtime bug.
 - 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.
 
+## Single-app repos (no `apps/`, no `turbo.json`)
+
+The templates are monorepo-shaped; one set of token substitutions makes them serve a root-level single
+app. Apply these deltas (verified on `ddg-jewelry-admin`):
+
+- **Tokens:** `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = repo name (no `-web` suffix),
+  `{{WORKSPACE_MANIFEST_COPIES}}` = empty.
+- **`Dockerfile.web`:** delete the `COPY packages/ ./packages/` line (no `packages/`). The runner
+  `COPY` lines collapse to `.next/standalone ./`, `.next/static ./.next/static`, `public ./public`
+  (the `{{APP_DIR}}=.` substitution yields valid `./.next/...` — fine to simplify).
+- **`next.config`:** `output: "standalone"` only — no `outputFileTracingRoot`, no `transpilePackages`.
+- **`ci.yml`:** drop the Turbo `env:`, the `.turbo` cache step, and swap `bun run check-types` for
+  `bunx tsc --noEmit` if the repo has no `check-types` script (single apps usually don't).
+- **Runner (optional but recommended):** a single Next app deploys cleanly on a Node runner
+  (`node:22-alpine` or `gcr.io/distroless/nodejs22-debian12`, `CMD ["server.js"]`). Distroless cuts the
+  image ~4× and drops the runner CVEs (seen on `ddg-jewelry-admin`).
+
 ## Phase 3 — interactive ops checklist (the deliverable)
 
 Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
@@ -102,8 +139,14 @@ 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`.
+- **Coolify `Ports Exposes` (General page) is a SEPARATE setting from the `PORT` env** — it defaults
+  to `80` and must be set to the app port (`3000`). With `PORT=3000` but Ports Exposes still `80`, the
+  deploy log warns `PORT (3000) does not match configured ports_exposes: 80` and the proxy 502s. Fix
+  both.
+- `HOSTNAME=0.0.0.0` — the Dockerfile already bakes this; only set it if something overrides it.
 - The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+- **Set ALL env values UNQUOTED** (public and server alike) — Coolify passes values literally, so a
+  quoted `DATABASE_URL="…"` keeps the quotes and breaks `new URL()` (`ERR_INVALID_URL`).
 
 ## Phase 4 — verify
 

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

@@ -3,6 +3,11 @@
 # 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.
+#
+# {{BUN_VERSION}} must be >= 1.3.10 — 1.2.x breaks `next build` on Linux.
+# Single-app repo: {{APP_DIR}}=. and {{WORKSPACE_MANIFEST_COPIES}}= empty; also
+# delete the `COPY packages/ ./packages/` line below (no packages/ dir). See the
+# "Single-app repos" section in SKILL.md.
 # -----------------------------------------------------------------------------
 
 FROM oven/bun:{{BUN_VERSION}} AS base

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

@@ -34,5 +34,17 @@ jobs:
       - name: Check types
         run: bun run check-types
       - name: Build
-        run: bun run build
+        # Placeholder NEXT_PUBLIC_* values satisfy module-init that reads them at import
+        # time (e.g. Supabase clients) — CI has no .env files, so without these
+        # `next build` throws "Error: supabaseUrl is required" collecting page
+        # data. Real values are injected at runtime via next-runtime-env, never
+        # baked. Mirrors the Dockerfile build stage. Add one line per public var
+        # the app constructs a client from at import.
+        run: SKIP_ENV_VALIDATION=1 bun run build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: http://placeholder.invalid
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: placeholder
 {{MIGRATION_CHECK}}
+# Single-app repos (no turbo.json): remove the TURBO_TOKEN/TURBO_TEAM `env:` and
+# the `.turbo` cache step above, and swap `bun run check-types` for
+# `bunx tsc --noEmit` if the repo has no check-types script.