mandrel-platform 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "engines": {

package/templates/runbooks/README.md

@@ -0,0 +1,42 @@
+# Runbook Templates (copyable thin stubs)
+
+These are **copyable thin-stub templates** — one per canonical mandrel-platform
+runbook in [`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks).
+They implement the MP-9 adoption model (§7.7 / F1): *replace each duplicated
+process runbook with a thin local doc that holds project-specific values plus a
+link to the canonical runbook.*
+
+Each stub:
+
+- **Links** to its canonical mandrel-platform runbook (the process source of
+  truth — do not re-author the process here).
+- Carries **placeholders** for project-specific values in `<ANGLE_BRACKET>`
+  form (hosts, env names, dashboards, DB engine, worker names, …).
+
+## How to adopt (downstream repo)
+
+1. Copy the stub(s) you need into your project's `docs/runbooks/`:
+   ```bash
+   cp node_modules/mandrel-platform/templates/runbooks/deploy-promotion.md \
+      docs/runbooks/deploy-promotion.md
+   ```
+2. Replace every `<PLACEHOLDER>` with your project's real values.
+3. Fill in the **Project-Specific Notes** section.
+4. Leave the canonical link intact — when the upstream process changes, you only
+   re-read the link, not rewrite the stub.
+
+## Stubs
+
+| Stub | Canonical runbook |
+|------|-------------------|
+| `deploy-promotion.md` | staging → production promotion |
+| `incident-response.md` | severity, escalation, postmortem |
+| `database-backup-restore.md` | backup, PITR, restore/rollback |
+| `observability.md` | logs, Sentry, uptime, metrics |
+| `post-deploy-smoke.md` | boot-smoke gate + diagnosis |
+| `environments-provisioning.md` | env model + provisioning steps |
+| `dependency-update.md` | Renovate, CVE gate, catalog |
+| `branch-protection-setup.md` | aggregator required-check model |
+
+> Placeholder convention: `<UPPER_SNAKE>` between angle brackets. Search for
+> `<` after copying to find everything that still needs a value.

package/templates/runbooks/branch-protection-setup.md

@@ -0,0 +1,45 @@
+# Branch Protection Setup — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical single-aggregator protection model and the
+> `main-protection.json` contract live in the mandrel-platform repo:
+> [`docs/runbooks/branch-protection-setup.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/branch-protection-setup.md).
+> This file only holds **<PROJECT_NAME>-specific check names and reviewers**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Repo (`owner/repo`) | `<OWNER>/<REPO>` |
+| Protected branch | `<PROTECTED_BRANCH>` (e.g. `main`) |
+| Required aggregator check | `<AGGREGATOR_CHECK>` (e.g. `ci-required`) |
+| Protection contract file | `<MAIN_PROTECTION_JSON>` (e.g. `docs/runbooks/main-protection.json`) |
+| Reviewer group(s) | `<REVIEWER_GROUPS>` |
+| GitHub plan | `<GITHUB_PLAN>` (free / pro / team) |
+
+## Apply & Verify
+
+```bash
+# Preview / apply
+node scripts/apply-branch-protection.mjs --dry-run
+node scripts/apply-branch-protection.mjs --apply
+
+# Verify
+gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \
+  --jq '.required_status_checks.contexts'
+# Expected: ["<AGGREGATOR_CHECK>"]
+```
+
+> **Do not add individual job names as required checks** — only the aggregator.
+
+## Project-Specific Notes
+
+<!-- Ruleset IDs, enforceAdmins rationale, plan-specific constraints. -->
+
+- _TODO: fill in._
+
+---
+
+See also the project's `<MAIN_PROTECTION_JSON>` and the local stubs:
+`dependency-update.md`, `environments-provisioning.md`.

package/templates/runbooks/database-backup-restore.md

@@ -0,0 +1,49 @@
+# Database Backup & Restore — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical backup strategy, PITR procedure, and
+> restore steps live in the mandrel-platform repo:
+> [`docs/runbooks/database-backup-restore.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/database-backup-restore.md).
+> This file only holds **<PROJECT_NAME>-specific database values**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| DB engine | `<DB_ENGINE>` (e.g. Turso/libSQL) |
+| Staging DB name | `<STAGING_DB_NAME>` |
+| Production DB name | `<PRODUCTION_DB_NAME>` |
+| Org / account | `<DB_ORG>` |
+| PITR retention window | `<PITR_WINDOW>` (e.g. 7 days) |
+| Critical tables (integrity check) | `<CRITICAL_TABLE>` |
+| Worker secret for DB URL | `<DATABASE_URL_SECRET>` |
+| Backup verification log | `<BACKUP_VERIFY_LOG_LOCATION>` |
+
+## Restore from Pre-Deploy Snapshot (primary path)
+
+```bash
+SNAPSHOT_BRANCH="<SNAPSHOT_BRANCH>"   # from the deploy workflow run output
+turso db create <PRODUCTION_DB_NAME>-restored \
+  --from-db <PRODUCTION_DB_NAME> --from-branch "$SNAPSHOT_BRANCH"
+turso db shell <PRODUCTION_DB_NAME>-restored "SELECT COUNT(*) FROM <CRITICAL_TABLE>;"
+# Repoint the worker secret and redeploy — see canonical Section 5.
+```
+
+## Manual Backup
+
+```bash
+turso db branch create <PRODUCTION_DB_NAME> backup-$(date +%Y%m%d)
+turso db shell <PRODUCTION_DB_NAME> ".dump" > backup-$(date +%Y%m%d).sql  # store securely
+```
+
+## Project-Specific Notes
+
+<!-- Snapshot cadence, who owns restores, where dumps are archived. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `deploy-promotion.md`,
+`incident-response.md`, and the project's `docs/environments.md`.

package/templates/runbooks/dependency-update.md

@@ -0,0 +1,40 @@
+# Dependency Update — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical Renovate model, CVE gate, catalog, and
+> override conventions live in the mandrel-platform repo:
+> [`docs/runbooks/dependency-update.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/dependency-update.md).
+> This file only holds **<PROJECT_NAME>-specific configuration pointers**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Package manager | `<PACKAGE_MANAGER>` (e.g. pnpm) |
+| Renovate config | `<RENOVATE_CONFIG_PATH>` |
+| CVE allowlist location | `<CVE_ALLOWLIST_PATH>` |
+| Audit command | `<AUDIT_COMMAND>` (e.g. `pnpm run audit:check`) |
+| Renovate Dependency Dashboard | `<DASHBOARD_ISSUE_URL>` |
+| Node version pin | `<NODE_VERSION>` (`.nvmrc`) |
+
+## Common Commands
+
+```bash
+# Run the CVE gate locally (what CI sees)
+<AUDIT_COMMAND>
+
+# Out-of-band update
+<PACKAGE_MANAGER> update <package-name>
+```
+
+## Project-Specific Notes
+
+<!-- Renovate preset overrides, grouped packages, manual-merge policies. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `secret-rotation.md`, `incident-response.md`, and
+the project's `docs/environments.md`.

package/templates/runbooks/deploy-promotion.md

@@ -0,0 +1,47 @@
+# Deploy Promotion — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical, process-level procedure lives in the
+> mandrel-platform repo:
+> [`docs/runbooks/deploy-promotion.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/deploy-promotion.md).
+> This file only holds **<PROJECT_NAME>-specific values**. When the process
+> changes, update the canonical runbook upstream — not this stub.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Staging worker name | `<STAGING_WORKER_NAME>` |
+| Production worker name | `<PRODUCTION_WORKER_NAME>` |
+| Staging deploy workflow | `<STAGING_DEPLOY_WORKFLOW>` (e.g. `deploy-staging.yml`) |
+| Production deploy workflow | `<PRODUCTION_DEPLOY_WORKFLOW>` (e.g. `deploy-production.yml`) |
+| Production health URL | `<PRODUCTION_HEALTH_URL>` |
+| Staging health URL | `<STAGING_HEALTH_URL>` |
+| Promotion approvers | `<APPROVER_HANDLES>` |
+| Deploy-window channel | `<DEPLOY_CHANNEL>` |
+
+## Trigger a Production Promotion
+
+```bash
+gh workflow run <PRODUCTION_DEPLOY_WORKFLOW> --ref main --field confirm=true
+```
+
+## Verify
+
+```bash
+curl -sf <PRODUCTION_HEALTH_URL> && echo OK || echo FAIL
+wrangler deployments list --name <PRODUCTION_WORKER_NAME> | head -3
+```
+
+## Project-Specific Notes
+
+<!-- Record any promotion quirks for this project: extra pre-checks, manual
+     migration steps, stakeholder sign-off requirements, etc. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `post-deploy-smoke.md`,
+`incident-response.md`, and the project's `docs/environments.md`.

package/templates/runbooks/environments-provisioning.md

@@ -0,0 +1,42 @@
+# Environments Provisioning — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical environment model and step-by-step
+> provisioning procedure live in the mandrel-platform repo:
+> [`docs/runbooks/environments-provisioning.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/environments-provisioning.md).
+> This file only holds **<PROJECT_NAME>-specific IDs and names**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Repo (`owner/repo`) | `<OWNER>/<REPO>` |
+| Cloudflare account ID | `<CF_ACCOUNT_ID>` |
+| Zone / domain | `<ZONE>` |
+| Worker base name | `<WORKER_NAME>` |
+| Staging domain | `<STAGING_DOMAIN>` |
+| Production domain | `<PRODUCTION_DOMAIN>` |
+| Secrets manager project | `<SECRETS_PROJECT_ID>` (e.g. Infisical) |
+| Staging DB name | `<STAGING_DB_NAME>` |
+| Production DB name | `<PRODUCTION_DB_NAME>` |
+
+## Environment Map
+
+| Environment | Branch | Deployed by |
+|-------------|--------|-------------|
+| `local` | any | developer (`wrangler dev`) |
+| `staging` | `main` (auto) | CI/CD after CI-green |
+| `production` | `main` (manual) | `workflow_dispatch` |
+
+## Project-Specific Notes
+
+<!-- Custom domains, reviewer requirements, secret-sync specifics. -->
+
+- _TODO: fill in._
+
+---
+
+The authoritative environment inventory (URLs, secret names, DB names) is the
+project's own `docs/environments.md`. See also the local stubs:
+`branch-protection-setup.md`, `secret-rotation.md`, `deploy-promotion.md`.

package/templates/runbooks/incident-response.md

@@ -0,0 +1,52 @@
+# Incident Response — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical severity model, escalation flow, response
+> steps, and postmortem template live in the mandrel-platform repo:
+> [`docs/runbooks/incident-response.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/incident-response.md).
+> This file only holds **<PROJECT_NAME>-specific contacts and links**.
+
+---
+
+## Escalation Contacts
+
+| Role | Who | Channel |
+|------|-----|---------|
+| First responder / on-call | `<ONCALL_HANDLE>` | `<ONCALL_CHANNEL>` |
+| On-call lead (P1/P2) | `<LEAD_HANDLE>` | `<LEAD_CHANNEL>` |
+| Stakeholder notify (P1) | `<STAKEHOLDER_LIST>` | `<STAKEHOLDER_CHANNEL>` |
+
+## Tooling Links
+
+| Tool | URL |
+|------|-----|
+| Error tracking (Sentry) | `<SENTRY_PROJECT_URL>` |
+| Uptime (Better Stack) | `<BETTERSTACK_URL>` |
+| Status page | `<STATUS_PAGE_URL>` |
+| Incident issue label | `incident`, `severity::P1` … |
+
+## Severity SLAs (from canonical — confirm or override)
+
+| Severity | Target response |
+|----------|-----------------|
+| P1 — Critical | < 15 min |
+| P2 — High | < 1 hour |
+| P3 — Medium | < 4 hours |
+| P4 — Low | next business day |
+
+## First Moves
+
+1. Acknowledge the alert in `<BETTERSTACK_URL>` / `<SENTRY_PROJECT_URL>`.
+2. Open an incident issue (`incident` + `severity::*`).
+3. **Recent deploy? Rollback first** — see `rollback.md`.
+4. Follow the full response steps in the canonical runbook.
+
+## Project-Specific Notes
+
+<!-- Paging procedures, escalation timeouts, known fragile subsystems. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `observability.md`,
+`secret-rotation.md`, and the project's `docs/environments.md`.

package/templates/runbooks/observability.md

@@ -0,0 +1,49 @@
+# Observability — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical observability stack, query patterns, and
+> on-call response flow live in the mandrel-platform repo:
+> [`docs/runbooks/observability.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/observability.md).
+> This file only holds **<PROJECT_NAME>-specific endpoints and dataset names**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Worker name(s) | `<WORKER_NAME>` |
+| Cloudflare account ID | `<CF_ACCOUNT_ID>` |
+| Analytics Engine dataset | `<AE_DATASET>` |
+| Sentry dashboard | `<SENTRY_PROJECT_URL>` |
+| Sentry DSN secret | `<SENTRY_DSN_SECRET>` |
+| Better Stack dashboard | `<BETTERSTACK_URL>` |
+| Logpush destination | `<LOGPUSH_DESTINATION>` |
+
+## Quick Commands
+
+```bash
+# Live tail
+wrangler tail --name <WORKER_NAME> --format pretty
+
+# Errors only
+wrangler tail --name <WORKER_NAME> --format json | jq 'select(.outcome != "ok")'
+```
+
+## Alert Thresholds (from canonical — confirm or override)
+
+| Metric | Action threshold |
+|--------|------------------|
+| 5xx rate | > 1% sustained → consider rollback |
+| P99 response time | > 2× baseline → investigate |
+| Uptime probe failing | any failure → page on-call |
+
+## Project-Specific Notes
+
+<!-- Custom dashboards, known noisy alerts, dataset schema notes. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `incident-response.md`, `rollback.md`, `slo.md`,
+and the project's `docs/environments.md`.

package/templates/runbooks/post-deploy-smoke.md

@@ -0,0 +1,39 @@
+# Post-Deploy Smoke — <PROJECT_NAME>
+
+> **Thin local stub.** The canonical smoke contract, failure diagnosis, and
+> auto-rollback behavior live in the mandrel-platform repo:
+> [`docs/runbooks/post-deploy-smoke.md`](https://github.com/dsj1984/mandrel-platform/blob/main/docs/runbooks/post-deploy-smoke.md).
+> This file only holds **<PROJECT_NAME>-specific health URLs and parameters**.
+
+---
+
+## Project Values
+
+| Value | Setting |
+|-------|---------|
+| Staging health URL | `<STAGING_HEALTH_URL>` |
+| Production health URL | `<PRODUCTION_HEALTH_URL>` |
+| Health route | `<HEALTH_ROUTE>` (e.g. `GET /health`) |
+| Smoke script | `<SMOKE_SCRIPT>` (e.g. `./scripts/smoke-deploy.sh`) |
+| Max attempts | `<SMOKE_MAX_ATTEMPTS>` (default 5) |
+| Delay between retries | `<SMOKE_DELAY_SECONDS>` (default 10s) |
+
+## Run the Smoke Manually
+
+```bash
+<SMOKE_SCRIPT> <PRODUCTION_HEALTH_URL> <SMOKE_MAX_ATTEMPTS> <SMOKE_DELAY_SECONDS>
+
+# One-shot check
+curl -sf <PRODUCTION_HEALTH_URL> && echo OK || echo FAIL
+```
+
+## Project-Specific Notes
+
+<!-- Cold-start tuning, non-standard health checks, auth exceptions. -->
+
+- _TODO: fill in._
+
+---
+
+See also the local stubs: `rollback.md`, `deploy-promotion.md`,
+`observability.md`, and the project's `docs/environments.md`.