docs(plan): implementation plan for under-construction placeholder

Four-task plan: tests → page+assets → workflow → README. TDD via src/placeholder.test.ts (vitest only discovers src/**/*.test.ts). Atomic commits per task; the plan is wired off the spec at commit 9b0c36b. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-25 18:03:27 +02:00
parent 9b0c36b5e0
commit c3511a4c1b
1 changed files with 518 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-25-under-construction-placeholder.md
+++ b/docs/superpowers/plans/2026-04-25-under-construction-placeholder.md
@@ -0,0 +1,518 @@
+# Under-construction placeholder Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a branded "back shortly" page for cameleer.io plus a manual-trigger Gitea workflow that swaps it onto the live origin on demand, recoverable by re-running the existing `deploy.yml`.
+
+**Architecture:** Standalone HTML in a top-level `placeholder/` directory, plus two PNG asset copies. A new `.gitea/workflows/deploy-placeholder.yml` rsyncs that directory to the same Hetzner docroot used by `deploy.yml` (`--delete` enabled, `deploy-production` concurrency group shared so the two workflows queue rather than race). No Astro build dependency, so the placeholder still ships when the main build is broken — which is the worst case where one is needed.
+
+**Tech Stack:** Plain HTML5 + inlined CSS, Google Fonts (DM Sans, JetBrains Mono), bash + rsync over SSH:222, Vitest 1 for static-content assertions.
+
+**Spec:** `docs/superpowers/specs/2026-04-25-under-construction-placeholder-design.md` (commit `9b0c36b`).
+
+---
+
+## File Structure
+
+| File | Status | Responsibility |
+|---|---|---|
+| `placeholder/index.html` | Create | Static under-construction page. Single self-contained file, references the two sibling PNGs by relative path. Contains `__SALES_EMAIL__` substitution token (used twice — `mailto:` href and link text). |
+| `placeholder/cameleer-logo.png` | Create (copy) | Hero logo. Copy of `public/icons/cameleer-192.png` (~36 KB). |
+| `placeholder/favicon.png` | Create (copy) | Browser tab icon. Copy of `public/icons/cameleer-32.png` (~2.4 KB). |
+| `src/placeholder.test.ts` | Create | Static assertions that the placeholder HTML has the contract the deploy workflow depends on (sentinel string, token, references, no JS, etc.). Lives in `src/` because `vitest.config.ts` only discovers `src/**/*.test.ts`. |
+| `.gitea/workflows/deploy-placeholder.yml` | Create | Manual-dispatch workflow: substitute sales email → rsync `placeholder/` to docroot → smoke-test the live origin. |
+| `README.md` | Modify | Append a "Placeholder mode" subsection under "Deployment". |
+
+---
+
+## Task 1: Add tests for the placeholder HTML
+
+**Why first:** Establishes the contract the workflow depends on — sentinel string, substitution token, asset references — before any markup is written, so we can't accidentally drop one of them later.
+
+**Files:**
+- Create: `src/placeholder.test.ts`
+
+- [ ] **Step 1: Write the failing test file**
+
+Create `src/placeholder.test.ts` with this exact content:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const placeholderDir = join(process.cwd(), 'placeholder');
+const indexPath = join(placeholderDir, 'index.html');
+
+describe('placeholder/index.html', () => {
+  const html = readFileSync(indexPath, 'utf8');
+
+  it('starts with the HTML5 doctype', () => {
+    expect(html.toLowerCase().trimStart()).toMatch(/^<!doctype html>/);
+  });
+
+  it('has the back-shortly title', () => {
+    expect(html).toContain('<title>Cameleer — Back shortly</title>');
+  });
+
+  it('is not indexable by search engines', () => {
+    expect(html).toContain('<meta name="robots" content="noindex">');
+  });
+
+  it('declares the dark color-scheme matching the live site', () => {
+    expect(html).toContain('<meta name="color-scheme" content="dark">');
+    expect(html).toContain('<meta name="theme-color" content="#060a13">');
+  });
+
+  it('contains the sentinel string the deploy workflow greps for', () => {
+    // The workflow's post-deploy smoke test fails if this string is missing.
+    expect(html).toContain('Routes are remapping');
+  });
+
+  it('uses the live hero subhead verbatim', () => {
+    expect(html).toContain(
+      'Cameleer is the hosted runtime and observability platform for Apache Camel — auto-traced, replay-ready, cross-service correlated. The 3 AM page becomes a 30-second answer.'
+    );
+  });
+
+  it('contains __SALES_EMAIL__ tokens at both the mailto href and the link text', () => {
+    const matches = html.match(/__SALES_EMAIL__/g) ?? [];
+    expect(matches.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('contains no other __TOKEN__ style placeholders', () => {
+    // Guard against a forgotten token that would survive the sed substitution.
+    const allTokens = html.match(/__[A-Z][A-Z0-9_]+__/g) ?? [];
+    const nonSales = allTokens.filter((t) => t !== '__SALES_EMAIL__');
+    expect(nonSales).toEqual([]);
+  });
+
+  it('references the sibling cameleer-logo.png by relative path', () => {
+    expect(html).toContain('src="./cameleer-logo.png"');
+  });
+
+  it('references the sibling favicon.png by relative path', () => {
+    expect(html).toContain('href="./favicon.png"');
+  });
+
+  it('has no <script> tags (placeholder must work without JS)', () => {
+    expect(html).not.toMatch(/<script[\s>]/i);
+  });
+});
+
+describe('placeholder/ asset siblings', () => {
+  it('cameleer-logo.png exists on disk', () => {
+    expect(existsSync(join(placeholderDir, 'cameleer-logo.png'))).toBe(true);
+  });
+
+  it('favicon.png exists on disk', () => {
+    expect(existsSync(join(placeholderDir, 'favicon.png'))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test suite to verify the new tests fail**
+
+Run: `npm test`
+
+Expected: vitest fails when loading `src/placeholder.test.ts` because `readFileSync` throws `ENOENT` on the missing `placeholder/index.html`. The pre-existing `src/middleware.test.ts` suite must still pass.
+
+- [ ] **Step 3: Commit the failing tests**
+
+```bash
+git add src/placeholder.test.ts
+git commit -m "test(placeholder): add static-content tests for under-construction page"
+```
+
+Note: this commit is intentionally a red bar. Task 2 turns it green in a single follow-up commit. If you prefer a green-only history, fold this commit into Task 2's commit at the end.
+
+---
+
+## Task 2: Create the placeholder page and copy assets
+
+**Files:**
+- Create: `placeholder/index.html`
+- Create: `placeholder/cameleer-logo.png` (copy of `public/icons/cameleer-192.png`)
+- Create: `placeholder/favicon.png` (copy of `public/icons/cameleer-32.png`)
+
+- [ ] **Step 1: Copy the PNG assets into `placeholder/`**
+
+The repo's full-resolution `public/cameleer-logo.svg` is 1.5 MB (embedded raster data) and is not used here. The 192 px PNG is the correct size and weight for the placeholder hero.
+
+```bash
+mkdir -p placeholder
+cp public/icons/cameleer-192.png placeholder/cameleer-logo.png
+cp public/icons/cameleer-32.png  placeholder/favicon.png
+ls -la placeholder/
+```
+
+Expected: both files present. `cameleer-logo.png` ~36 KB; `favicon.png` ~2.4 KB.
+
+- [ ] **Step 2: Write `placeholder/index.html`**
+
+Create `placeholder/index.html` with this exact content. Note both occurrences of `__SALES_EMAIL__` — the deploy workflow substitutes them via `sed ... -g`.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="dark">
+    <meta name="theme-color" content="#060a13">
+    <meta name="robots" content="noindex">
+    <meta name="description" content="Cameleer is briefly offline. We'll be back on the trail in a moment.">
+
+    <title>Cameleer — Back shortly</title>
+
+    <link rel="icon" type="image/png" sizes="32x32" href="./favicon.png">
+
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet"
+          href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,400;0,700;1,400&family=JetBrains+Mono&display=swap">
+
+    <style>
+      :root {
+        --bg:         #060a13;
+        --accent:     #f0b429;
+        --text:       #e8eaed;
+        --text-muted: #9aa3b2;
+        --text-faint: #828b9b;
+      }
+      *, *::before, *::after { box-sizing: border-box; }
+      html, body { margin: 0; padding: 0; }
+      body {
+        background-color: var(--bg);
+        background-image: radial-gradient(60% 60% at 50% 50%, rgba(240, 180, 41, 0.10), transparent 70%);
+        color: var(--text);
+        font-family: 'DM Sans', system-ui, -apple-system, sans-serif;
+        -webkit-font-smoothing: antialiased;
+        min-height: 100vh;
+      }
+      main {
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding: 2.5rem 1.5rem;
+        text-align: center;
+      }
+      .logo {
+        width: 96px;
+        height: 96px;
+        margin: 0 0 1.75rem;
+      }
+      .eyebrow {
+        display: inline-block;
+        margin: 0 0 1.5rem;
+        font-size: 14px;
+        font-style: italic;
+        color: var(--accent);
+      }
+      h1 {
+        margin: 0 0 1.5rem;
+        font-weight: 700;
+        font-size: clamp(2.25rem, 4.5vw, 4rem);
+        line-height: 1.05;
+        letter-spacing: -0.02em;
+        max-width: 18ch;
+      }
+      .subhead {
+        margin: 0 0 2rem;
+        max-width: 42rem;
+        font-size: 1.125rem;
+        line-height: 1.55;
+        color: var(--text-muted);
+      }
+      .micro {
+        margin: 0;
+        font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace;
+        font-size: 12px;
+        color: var(--text-faint);
+      }
+      .micro a { color: inherit; text-decoration: none; }
+      .micro a:hover, .micro a:focus { text-decoration: underline; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <img class="logo" src="./cameleer-logo.png" alt="Cameleer" width="96" height="96">
+      <p class="eyebrow">✦ Routes are remapping.</p>
+      <h1>We're back on the trail<br>in a moment.</h1>
+      <p class="subhead">Cameleer is the hosted runtime and observability platform for Apache Camel — auto-traced, replay-ready, cross-service correlated. The 3 AM page becomes a 30-second answer.</p>
+      <p class="micro">cameleer.io · <a href="mailto:__SALES_EMAIL__">__SALES_EMAIL__</a></p>
+    </main>
+  </body>
+</html>
+```
+
+- [ ] **Step 3: Run the placeholder tests to verify they pass**
+
+Run: `npm test -- placeholder`
+
+Expected: all tests in `src/placeholder.test.ts` pass. (`-- placeholder` is a vitest test-name filter that runs only the new file's `describe` blocks for fast feedback.)
+
+- [ ] **Step 4: Run the full test suite to verify no regressions**
+
+Run: `npm test`
+
+Expected: every existing test still passes (the middleware/CSP suite is the only other one).
+
+- [ ] **Step 5: Visual verification in a browser**
+
+The `__SALES_EMAIL__` token will be visible in the rendered page — that is expected; it's substituted at deploy time. Confirm visual treatment.
+
+```bash
+npx serve placeholder -l 4322
+# then open http://localhost:4322 in a browser
+```
+
+Confirm by eye:
+1. Centered single-column layout, logo on top.
+2. Dark background (#060a13) with a faint amber radial glow centered.
+3. Italic amber eyebrow `✦ Routes are remapping.`.
+4. Bold display heading wraps onto two lines on desktop ("We're back on the trail" / "in a moment.").
+5. Subhead reads as muted body text below.
+6. Mono microcopy at the bottom shows `cameleer.io · __SALES_EMAIL__` in faint grey, with the token rendered as a `mailto:` link.
+7. Resize the window to ~360 px wide — layout stays centered, heading scales down via `clamp()`, no horizontal scroll.
+
+Stop the server with Ctrl-C when done.
+
+- [ ] **Step 6: Commit the placeholder page and assets**
+
+```bash
+git add placeholder/index.html placeholder/cameleer-logo.png placeholder/favicon.png
+git commit -m "feat(placeholder): add under-construction page with branded teaser
+
+Standalone HTML + two sibling PNGs, no Astro build dependency.
+Carries __SALES_EMAIL__ substitution tokens that the new deploy
+workflow replaces at deploy time."
+```
+
+---
+
+## Task 3: Add the deploy-placeholder workflow
+
+**Files:**
+- Create: `.gitea/workflows/deploy-placeholder.yml`
+
+- [ ] **Step 1: Write `.gitea/workflows/deploy-placeholder.yml`**
+
+Create with this exact content. Mirrors `deploy.yml`'s SSH/rsync pattern but skips `npm ci`/`astro build`/Lighthouse — the placeholder is hand-authored static and must be deployable when the main build is broken.
+
+```yaml
+# -----------------------------------------------------------------------------
+# cameleer-website — Deploy under-construction placeholder
+#
+# MANUAL TRIGGER ONLY. Replaces the live cameleer.io docroot with a static
+# "back shortly" page. Recovery: trigger Actions → deploy → Run workflow on
+# the desired main commit.
+#
+# Shares the deploy-production concurrency group with deploy.yml so the two
+# workflows queue rather than race on the same docroot.
+#
+# This workflow does NOT run npm/astro. The placeholder is hand-authored
+# static HTML in placeholder/, deliberately decoupled from the main build so
+# it can ship even when the main build is broken (which is the worst case in
+# which a placeholder is needed).
+#
+# Required secrets (repo settings → Actions → Secrets):
+#   SFTP_HOST, SFTP_USER, SFTP_PATH, SFTP_KEY, SFTP_KNOWN_HOSTS
+#   PUBLIC_SALES_EMAIL
+# -----------------------------------------------------------------------------
+
+name: deploy-placeholder
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Substitute sales email into placeholder
+        env:
+          PUBLIC_SALES_EMAIL: ${{ secrets.PUBLIC_SALES_EMAIL }}
+        run: |
+          set -e
+          : "${PUBLIC_SALES_EMAIL:?PUBLIC_SALES_EMAIL secret must be set}"
+          sed -i "s|__SALES_EMAIL__|${PUBLIC_SALES_EMAIL}|g" placeholder/index.html
+          if grep -q '__SALES_EMAIL__' placeholder/index.html; then
+            echo "Token __SALES_EMAIL__ still present after substitution — refusing to ship."
+            exit 1
+          fi
+
+      - name: Configure SSH
+        env:
+          SFTP_KEY: ${{ secrets.SFTP_KEY }}
+          SFTP_KNOWN_HOSTS: ${{ secrets.SFTP_KNOWN_HOSTS }}
+        run: |
+          set -e
+          : "${SFTP_KEY:?SFTP_KEY secret must be set}"
+          : "${SFTP_KNOWN_HOSTS:?SFTP_KNOWN_HOSTS secret must be set}"
+          mkdir -p ~/.ssh
+          printf '%s\n' "$SFTP_KEY" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          printf '%s\n' "$SFTP_KNOWN_HOSTS" > ~/.ssh/known_hosts
+          chmod 644 ~/.ssh/known_hosts
+          if ! command -v rsync >/dev/null 2>&1 || ! command -v ssh >/dev/null 2>&1; then
+            if command -v sudo >/dev/null 2>&1; then SUDO=sudo; else SUDO=; fi
+            $SUDO apt-get update -qq
+            $SUDO apt-get install -y --no-install-recommends rsync openssh-client
+          fi
+
+      - name: Deploy via rsync
+        env:
+          SFTP_USER: ${{ secrets.SFTP_USER }}
+          SFTP_HOST: ${{ secrets.SFTP_HOST }}
+          SFTP_PATH: ${{ secrets.SFTP_PATH }}
+        run: |
+          : "${SFTP_USER:?SFTP_USER secret must be set}"
+          : "${SFTP_HOST:?SFTP_HOST secret must be set}"
+          : "${SFTP_PATH:?SFTP_PATH secret must be set}"
+          # Hetzner Webhosting splits SSH into two ports:
+          #   port 22  — SFTP only, no remote command exec
+          #   port 222 — full SSH with shell exec (rsync needs this)
+          # `--rsync-path=/usr/bin/rsync` tells the local rsync where to find
+          # the remote binary on Hetzner's locked-down PATH.
+          # `BatchMode=yes` disables interactive prompts.
+          rsync -avz --delete --rsync-path=/usr/bin/rsync \
+            -e "ssh -p 222 -i $HOME/.ssh/id_ed25519 -o BatchMode=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=$HOME/.ssh/known_hosts" \
+            placeholder/ "$SFTP_USER@$SFTP_HOST:$SFTP_PATH/"
+
+      - name: Post-deploy smoke test
+        run: |
+          set -e
+          echo "Confirming the placeholder is live on www.cameleer.io..."
+          BODY=$(curl -sf https://www.cameleer.io/)
+          echo "$BODY" | grep -qF 'Routes are remapping' \
+            || { echo "Sentinel string missing — placeholder did not land."; exit 1; }
+          echo "$BODY" | grep -qF 'mailto:' \
+            || { echo "mailto: link missing — sales email substitution may have failed."; exit 1; }
+          curl -sfI https://www.cameleer.io/cameleer-logo.png > /dev/null \
+            || { echo "cameleer-logo.png not reachable on the live origin."; exit 1; }
+          echo "Placeholder is live."
+```
+
+- [ ] **Step 2: Verify the YAML parses**
+
+Run a quick Node-based parse check (no extra dep needed; Node ships with no YAML parser, so use a one-off `npx`):
+
+```bash
+npx --yes js-yaml .gitea/workflows/deploy-placeholder.yml > /dev/null && echo "YAML OK"
+```
+
+Expected: `YAML OK`. If `js-yaml` errors, re-read the file for stray tabs or unbalanced quoting.
+
+- [ ] **Step 3: Verify the existing deploy.yml is unchanged**
+
+Run: `git diff .gitea/workflows/deploy.yml`
+
+Expected: empty output (the new workflow is additive only).
+
+- [ ] **Step 4: Commit the workflow**
+
+```bash
+git add .gitea/workflows/deploy-placeholder.yml
+git commit -m "ci(deploy): add deploy-placeholder workflow
+
+Manual-trigger workflow that substitutes PUBLIC_SALES_EMAIL into
+placeholder/index.html, rsyncs placeholder/ to the Hetzner docroot
+over SSH:222, then smoke-tests the live origin for the sentinel
+string, mailto link, and logo URL.
+
+Shares the deploy-production concurrency group with deploy.yml so
+the two workflows can never race on the same docroot. Recovery is
+the regular deploy.yml — no separate un-placeholder workflow."
+```
+
+---
+
+## Task 4: Document the placeholder mode in the README
+
+**Files:**
+- Modify: `README.md` (append a subsection under "## Deployment", after the existing "Rollback" paragraph and before "**Security headers**")
+
+- [ ] **Step 1: Read the current README to locate the insertion point**
+
+Run: `cat README.md`
+
+Locate the line `Rollback: trigger the deploy workflow on the previous \`main\` commit (Actions UI lets you pick a ref).`. The new subsection goes immediately after it, separated by a blank line, before the `**Security headers**` paragraph.
+
+- [ ] **Step 2: Insert the placeholder-mode subsection**
+
+Use the `Edit` tool with these exact arguments. `old_string` is the existing two-paragraph boundary; `new_string` reproduces it with the new `### Placeholder mode` subsection wedged in between.
+
+`file_path`: `README.md`
+
+`old_string`:
+````
+Rollback: trigger the deploy workflow on the previous `main` commit (Actions UI lets you pick a ref).
+
+**Security headers** (HSTS, CSP, X-Frame-Options, etc.) are owned by **Cloudflare Transform Rules**, not by anything in this repo.
+````
+
+`new_string`:
+````
+Rollback: trigger the deploy workflow on the previous `main` commit (Actions UI lets you pick a ref).
+
+### Placeholder mode
+
+To put the site into "back shortly" mode, trigger Gitea → **Actions → deploy-placeholder → Run workflow**. To bring the real site back, trigger **Actions → deploy → Run workflow** on the desired `main` commit. Both workflows share the `deploy-production` concurrency group, so they can never run simultaneously.
+
+The placeholder is hand-authored static HTML in `placeholder/` and does NOT depend on `npm`/`astro build` — it is deliberately decoupled from the main build so it can ship even when that build is broken.
+
+**Security headers** (HSTS, CSP, X-Frame-Options, etc.) are owned by **Cloudflare Transform Rules**, not by anything in this repo.
+````
+
+- [ ] **Step 3: Verify the README still renders cleanly**
+
+Run: `cat README.md | head -60`
+
+Confirm by eye that the new subsection appears under "Deployment", the surrounding paragraphs are intact, and there is exactly one blank line between adjacent blocks.
+
+- [ ] **Step 4: Commit the README update**
+
+```bash
+git add README.md
+git commit -m "docs(readme): add placeholder mode section
+
+Documents the deploy-placeholder workflow trigger and the recovery
+path back to the real site via deploy.yml."
+```
+
+---
+
+## Final verification
+
+- [ ] **Run the full test suite one more time**
+
+Run: `npm test`
+
+Expected: all tests pass — both `src/middleware.test.ts` and `src/placeholder.test.ts`.
+
+- [ ] **Confirm the four commits are in place**
+
+Run: `git log --oneline -5`
+
+Expected (top-down): README docs commit, deploy-placeholder.yml commit, placeholder feat commit, placeholder test commit, then the spec commit (`9b0c36b docs(spec): ...`).
+
+- [ ] **Sanity-check the placeholder directory ships only what it should**
+
+Run: `ls -la placeholder/`
+
+Expected: exactly three files — `index.html`, `cameleer-logo.png`, `favicon.png`. No stray `.test.ts`, `.DS_Store`, etc. (If anything else appears, remove it before merging — `rsync --delete` would otherwise push it to the live origin.)
+
+- [ ] **Push and trigger the first real run** (operator step, not part of the implementation)
+
+Push the branch, merge to `main` once reviewed, then in Gitea: **Actions → deploy-placeholder → Run workflow** on `main`. Verify by visiting `https://www.cameleer.io/` that the placeholder renders, then trigger **Actions → deploy → Run workflow** to restore the real site.