diff --git a/apps/api/src/lib/asset-storage.ts b/apps/api/src/lib/asset-storage.ts index 77bacd4..defa5c7 100644 --- a/apps/api/src/lib/asset-storage.ts +++ b/apps/api/src/lib/asset-storage.ts @@ -1,8 +1,9 @@ import { execFile } from 'node:child_process'; import { createHash, randomUUID } from 'node:crypto'; +import { existsSync } from 'node:fs'; import { mkdtemp, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; -import { extname, join } from 'node:path'; +import { dirname, extname, join } from 'node:path'; import { promisify } from 'node:util'; import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'; @@ -148,19 +149,94 @@ const getS3Client = () => { return s3Client; }; +const findWorkspaceBinary = (binaryName: string) => { + let currentDir = process.cwd(); + + while (true) { + const candidate = join(currentDir, 'node_modules', '.bin', binaryName); + if (existsSync(candidate)) { + return candidate; + } + + const parentDir = dirname(currentDir); + if (parentDir === currentDir) { + break; + } + + currentDir = parentDir; + } + + return binaryName; +}; + +const getWranglerExecutable = () => { + const configured = process.env.WRANGLER_BIN?.trim(); + if (configured) { + return configured; + } + + return findWorkspaceBinary('wrangler'); +}; + +const toTrimmedOutput = (value: unknown) => { + if (typeof value !== 'string') { + return undefined; + } + + const normalized = value.trim(); + if (!normalized) { + return undefined; + } + + return normalized.slice(0, 400); +}; + +const runWrangler = async (args: string[]) => { + const env = getEnv(); + const executable = getWranglerExecutable(); + + try { + return await execFileAsync(executable, args, { + env: { + ...process.env, + CLOUDFLARE_ACCOUNT_ID: env.r2AccountId, + }, + }); + } catch (error) { + if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') { + throw serviceUnavailable('Wrangler CLI is not available for R2 uploads', { + hint: 'set WRANGLER_BIN or expose node_modules/.bin on PATH', + executable, + }); + } + + const details: Record = { + hint: 'check the mounted Wrangler profile, CLI login state, and bucket permissions', + executable, + reason: error instanceof Error ? error.message : String(error), + }; + const stderr = typeof error === 'object' && error !== null && 'stderr' in error ? toTrimmedOutput(error.stderr) : undefined; + const stdout = typeof error === 'object' && error !== null && 'stdout' in error ? toTrimmedOutput(error.stdout) : undefined; + if (stderr) { + details.stderr = stderr; + } + if (stdout) { + details.stdout = stdout; + } + + throw serviceUnavailable('Wrangler CLI failed while accessing R2', { + ...details, + }); + } +}; + const getWranglerPublicBaseUrl = async (bucket: string) => { const cached = wranglerDevUrlCache.get(bucket); if (cached) { return cached; } - const env = getEnv(); - const result = await execFileAsync('wrangler', ['r2', 'bucket', 'dev-url', 'get', bucket], { - env: { - ...process.env, - CLOUDFLARE_ACCOUNT_ID: env.r2AccountId, - }, - }); + const result = await runWrangler(['r2', 'bucket', 'dev-url', 'get', bucket]); const output = `${result.stdout}\n${result.stderr}`; const match = output.match(/https:\/\/[^\s]+/); @@ -212,16 +288,7 @@ const uploadWithWrangler = async (objectKey: string, body: Buffer, mimeType: str try { await writeFile(tempFile, body); - await execFileAsync( - 'wrangler', - ['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType], - { - env: { - ...process.env, - CLOUDFLARE_ACCOUNT_ID: env.r2AccountId, - }, - }, - ); + await runWrangler(['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType]); } finally { await rm(tempDir, { recursive: true, force: true }); } diff --git a/skills/rebase-api-rollout/SKILL.md b/skills/rebase-api-rollout/SKILL.md new file mode 100644 index 0000000..3cdaa18 --- /dev/null +++ b/skills/rebase-api-rollout/SKILL.md @@ -0,0 +1,51 @@ +--- +name: rebase-api-rollout +description: Deploy and operate the Rebase backend server stack on `rebase@101.33.75.240`. Use when releasing or debugging `apps/api`, PostgreSQL, `cloudflared`, server env files, Docker Compose rollout, readiness checks, admin bootstrap, database backups, or the end-to-end server side of the Rebase production release. +--- + +# Rebase API Rollout + +## Overview + +Use this skill for the server-managed half of the Rebase production stack. It centers on `ops/manage.sh`, the Docker Compose topology in `infra/production/docker-compose.yml`, and the production config registry in `docs/production-config.md`. + +## Standard Rollout + +1. Keep the code on `dev` until it is validated. +2. Validate release readiness locally when needed: + - `pnpm deploy:server:config` + - any targeted API checks for the touched area +3. Use `./ops/manage.sh check` before a remote rollout. +4. Use `./ops/manage.sh deploy api` for API-only changes. +5. Use `./ops/manage.sh deploy stack` when API, Postgres, or `cloudflared` changes require the full stack. +6. Verify with: + - `./ops/manage.sh ps` + - `./ops/manage.sh health` + - `./ops/manage.sh ready` + - `./ops/manage.sh logs api 200` +7. Run targeted DB or bootstrap commands only when the task requires them. + +## Current Production Topology + +- host: `rebase@101.33.75.240` +- repo dir: `/home/rebase/rebase.network` +- compose file: `infra/production/docker-compose.yml` +- env file: `infra/production/server.env` +- API service: `api` +- DB service: `postgres` +- tunnel service: `cloudflared` +- public API hostname: `https://api.rebase.network` + +Use `references/runbook.md` for the exact command set and `references/troubleshooting.md` for the known failure modes. + +## When To Read References + +- Read `references/runbook.md` before performing a routine rollout, restart, log inspection, DB query, backup, or bootstrap action. +- Read `references/troubleshooting.md` when health checks fail, compose services do not come up, the tunnel is broken, the env file is missing, or the DB needs verification. + +## Guardrails + +- Prefer `ops/manage.sh` over ad-hoc SSH commands. +- Keep PostgreSQL private to the server and compose network; do not expose it publicly. +- Update `docs/deployment.md` and `docs/production-config.md` when server topology or ownership changes. +- If the task also includes public/admin Workers, pair this skill with `rebase-cloudflare-release`. diff --git a/skills/rebase-api-rollout/agents/openai.yaml b/skills/rebase-api-rollout/agents/openai.yaml new file mode 100644 index 0000000..f99512c --- /dev/null +++ b/skills/rebase-api-rollout/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Rebase API Rollout" + short_description: "Deploy and operate the Rebase API stack" + default_prompt: "Use $rebase-api-rollout to deploy, verify, or debug the Rebase API server stack." diff --git a/skills/rebase-api-rollout/references/runbook.md b/skills/rebase-api-rollout/references/runbook.md new file mode 100644 index 0000000..5672dae --- /dev/null +++ b/skills/rebase-api-rollout/references/runbook.md @@ -0,0 +1,56 @@ +# API Rollout Runbook + +## Primary Commands + +```bash +./ops/manage.sh check +./ops/manage.sh sync +./ops/manage.sh deploy api +./ops/manage.sh deploy stack +./ops/manage.sh ps +./ops/manage.sh logs api 200 +./ops/manage.sh health +./ops/manage.sh ready +./ops/manage.sh db query "select count(*) from geekdaily_episodes;" +./ops/manage.sh db backup +./ops/manage.sh bootstrap-admin +``` + +## Choose The Right Deploy Target + +- `deploy api`: API code or API container changes only +- `deploy stack`: API + Postgres + `cloudflared`, or infra/env changes that affect multiple services + +## First Release Or Recovery Tasks + +Use only when the task explicitly requires them: + +- bootstrap first admin account +- seed baseline content +- DB backup before risky migrations or cleanup + +## What `check` Should Confirm + +`./ops/manage.sh check` should validate: + +- SSH access works +- Docker and Compose exist remotely +- remote repo dir exists +- compose file exists +- remote env file exists +- compose `ps` can run + +## Health Endpoints + +- `health`: quick API liveness +- `ready`: API + dependency readiness + +Both should succeed before treating the rollout as healthy. + +## Important Repo Files + +- `ops/manage.sh` +- `infra/production/docker-compose.yml` +- `infra/production/server.env.example` +- `docs/deployment.md` +- `docs/production-config.md` diff --git a/skills/rebase-api-rollout/references/troubleshooting.md b/skills/rebase-api-rollout/references/troubleshooting.md new file mode 100644 index 0000000..6827a59 --- /dev/null +++ b/skills/rebase-api-rollout/references/troubleshooting.md @@ -0,0 +1,65 @@ +# API Troubleshooting + +## `ops/manage.sh check` Fails + +Inspect these in order: + +1. SSH access to `rebase@101.33.75.240` +2. remote repo dir exists: `/home/rebase/rebase.network` +3. remote `infra/production/server.env` exists +4. Docker Engine and Docker Compose plugin are installed remotely +5. compose file path still matches `infra/production/docker-compose.yml` + +## API Health Or Ready Fails + +Run: + +```bash +./ops/manage.sh ps +./ops/manage.sh logs api 200 +./ops/manage.sh logs cloudflared 200 +``` + +Then check: + +- API container started +- env values such as `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are present +- DB is reachable from API +- migrations or schema expectations are not blocking startup + +## Tunnel Or Public API Hostname Fails + +Remember the production routing model: + +- browser -> Cloudflare -> `api.rebase.network` -> `cloudflared` -> `api:8788` + +If `https://api.rebase.network` fails but local health is good, inspect: + +- `cloudflared` container logs +- tunnel token in `infra/production/server.env` +- Cloudflare Zero Trust hostname mapping + +## Database Checks + +Use: + +```bash +./ops/manage.sh db query "select now();" +./ops/manage.sh db query "select count(*) from geekdaily_episodes;" +./ops/manage.sh db backup +``` + +Do not expose Postgres publicly just to debug. + +## Release Policy Reminder + +The normal release policy is still: + +- work on `dev` +- validate locally +- push `origin/dev` +- create PR to `main` +- merge through GitHub +- deploy release-ready backend code from reviewed state + +Do not bypass this just because the server is self-managed. diff --git a/skills/rebase-cloudflare-release/SKILL.md b/skills/rebase-cloudflare-release/SKILL.md new file mode 100644 index 0000000..8bc64b1 --- /dev/null +++ b/skills/rebase-cloudflare-release/SKILL.md @@ -0,0 +1,46 @@ +--- +name: rebase-cloudflare-release +description: Deploy and troubleshoot the Rebase Cloudflare Workers frontend stack. Use when working on `apps/web` or `apps/admin`, configuring Cloudflare Workers Builds, fixing build or deploy failures, checking custom domains, KV bindings, or compatibility date issues, or performing the Rebase `dev to main to Cloudflare` release flow. +--- + +# Rebase Cloudflare Release + +## Overview + +Use this skill for the Rebase public and admin Workers release path. Keep the release flow anchored to the repo's `dev -> PR -> main -> Cloudflare Builds` policy and use the runbooks in `references/` before changing dashboard settings or patching build configuration. + +## Release Workflow + +1. Work on `dev`, not `main`. +2. Validate locally before pushing: + - `pnpm install --frozen-lockfile` + - `pnpm --filter @rebase/web check` + - `pnpm build:web:prod` + - `pnpm build:admin:prod` +3. Push to `origin/dev`. +4. Create a pull request from `dev` to `main`. +5. Merge only through GitHub; do not merge `main` locally as the normal release path. +6. Let Cloudflare Workers Builds publish from `main`. +7. Verify production domains after the build finishes. + +## Current Production Split + +- Public Worker: `rebase-web` +- Public domains: `rebase.network`, `rebase.community` +- Admin Worker: `rebase-admin` +- Admin domain: `admin.rebase.network` +- Public API origin used by Workers: `https://api.rebase.network` + +Use `references/build-settings.md` when you need the exact dashboard settings, commands, bindings, and watch-path rules. + +## When To Read References + +- Read `references/build-settings.md` before editing Cloudflare dashboard settings, worker build commands, bindings, or domains. +- Read `references/troubleshooting.md` when Cloudflare logs show install failures, compatibility date errors, duplicate KV provisioning, `hello world` on the production domain, or mismatched branch output. + +## Guardrails + +- Treat Cloudflare dashboard configuration as part of production state; update `docs/deployment.md` and `docs/production-config.md` when it changes. +- Prefer `pnpm deploy:web:dry-run` and `pnpm deploy:admin:dry-run` for local verification. +- Do not use local manual production deploys as the default path. +- If the task also includes backend rollout, pair this skill with `rebase-api-rollout`. diff --git a/skills/rebase-cloudflare-release/agents/openai.yaml b/skills/rebase-cloudflare-release/agents/openai.yaml new file mode 100644 index 0000000..7ef3567 --- /dev/null +++ b/skills/rebase-cloudflare-release/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Rebase Cloudflare Release" + short_description: "Deploy and debug Rebase Cloudflare Workers" + default_prompt: "Use $rebase-cloudflare-release to release or debug the Rebase Cloudflare Workers stack." diff --git a/skills/rebase-cloudflare-release/references/build-settings.md b/skills/rebase-cloudflare-release/references/build-settings.md new file mode 100644 index 0000000..203c816 --- /dev/null +++ b/skills/rebase-cloudflare-release/references/build-settings.md @@ -0,0 +1,70 @@ +# Cloudflare Worker Build Settings + +## Build Targets + +### `rebase-web` + +- production branch: `main` +- non-production branch builds: enabled +- root directory: `/` +- build command: `pnpm build:web:prod` +- deploy command: `pnpm exec wrangler deploy --config apps/web/dist/server/wrangler.production.json` +- non-production deploy command: `pnpm exec wrangler versions upload --config apps/web/dist/server/wrangler.production.json` +- config source in repo: `apps/web/wrangler.template.jsonc` +- Astro adapter config source: `apps/web/astro.config.mjs` + +Required Workers Builds env: + +- `SESSION_KV_NAMESPACE_ID` +- `SESSION_KV_NAMESPACE_PREVIEW_ID` (usually same as production id) + +Runtime vars: + +- `SITE_URL=https://rebase.network` +- `API_BASE_URL=https://api.rebase.network` + +### `rebase-admin` + +- production branch: `main` +- non-production branch builds: enabled +- root directory: `/` +- build command: `pnpm build:admin:prod` +- deploy command: `pnpm exec wrangler deploy --config apps/admin/wrangler.production.jsonc` +- non-production deploy command: `pnpm exec wrangler versions upload --config apps/admin/wrangler.production.jsonc` + +Build-time targets: + +- `VITE_API_BASE_URL=https://api.rebase.network` +- `VITE_PUBLIC_SITE_BASE_URL=https://rebase.network` + +## Why Root Directory Must Stay `/` + +Keep `/` as the Workers Builds root because: + +- root `package.json` contains the workspace release scripts +- `pnpm-lock.yaml` and `pnpm-workspace.yaml` live at repo root +- the public Worker build writes `apps/web/dist/server/wrangler.production.json` + +## Release Validation Commands + +Run these locally before handing the build to Cloudflare: + +```bash +pnpm install --frozen-lockfile +pnpm --filter @rebase/web check +pnpm build:web:prod +pnpm build:admin:prod +pnpm deploy:web:dry-run +pnpm deploy:admin:dry-run +``` + +## Production Verification + +After a successful Cloudflare build, verify: + +- `https://rebase.network` +- `https://rebase.community` +- `https://admin.rebase.network` +- public site content is not stale +- admin login still works +- Worker routes no longer return placeholder output such as `hello world` diff --git a/skills/rebase-cloudflare-release/references/troubleshooting.md b/skills/rebase-cloudflare-release/references/troubleshooting.md new file mode 100644 index 0000000..6572fbf --- /dev/null +++ b/skills/rebase-cloudflare-release/references/troubleshooting.md @@ -0,0 +1,68 @@ +# Cloudflare Troubleshooting + +## `ERR_PNPM_OUTDATED_LOCKFILE` + +Symptom: + +- Cloudflare fails during `pnpm install --frozen-lockfile` +- log mentions `package.json` specifiers not matching `pnpm-lock.yaml` + +Fix: + +1. Keep the intended dependencies in `package.json`. +2. Run `pnpm install` locally. +3. Commit the updated `pnpm-lock.yaml` together with the manifest changes. +4. Re-run `pnpm install --frozen-lockfile` locally before pushing. + +## Compatibility Date Error + +Symptom: + +- `This Worker requires compatibility date "2026-04-09", but the newest date supported by this server binary is "2026-04-08"` + +Rebase-specific fix: + +- make `apps/web/astro.config.mjs` pass `configPath: './wrangler.template.jsonc'` into the Cloudflare adapter +- keep `apps/web/wrangler.template.jsonc` as the explicit source of truth for `compatibility_date` + +This prevents Astro/Cloudflare build tooling from drifting to an implicit future date during build. + +## Duplicate KV Namespace Provisioning + +Symptom: + +- Wrangler tries to create `rebase-web-session` +- Cloudflare returns `a namespace with this account ID and title already exists` + +Fix: + +- set `SESSION_KV_NAMESPACE_ID` in Workers Builds +- set `SESSION_KV_NAMESPACE_PREVIEW_ID` too +- keep `scripts/deploy/prepare-web-assets.mjs` in the release path so the generated deploy config binds the existing namespace instead of provisioning a new one + +## Production Domain Returns `hello world` + +Check these in order: + +1. the correct Worker is attached to the custom domain +2. the Cloudflare build used `main` +3. the production deploy command points at the generated config file +4. the latest merge actually contains the expected app code + +## Local Build Works Poorly but Cloudflare Should Still Build + +There are two separate classes of problems: + +- lockfile or manifest mismatch: must be fixed in git +- local Miniflare/runtime mismatch: often only affects local builds and should be verified against the repo's explicit wrangler config + +Do not assume they are the same issue. + +## Repo Files To Check Before Patching + +- `apps/web/astro.config.mjs` +- `apps/web/wrangler.template.jsonc` +- `apps/admin/wrangler.production.jsonc` +- `scripts/deploy/prepare-web-assets.mjs` +- `docs/deployment.md` +- `docs/production-config.md`