Codflow Update

CodFlow Update — Agent Runbook

CodFlow self-hosters cloned the repo and completed setup with the codflow-setup skill: their wrangler.toml files, root .env, and .dev.vars files are filled with THEIR resource IDs and secrets and are all gitignored. This runbook brings such an install to the latest upstream code incrementally — no re-running setup, no re-creating resources, no data loss.

This skill ships inside the repo (.agents/skills/codflow-update/), so a plain git pull delivers it. The very first time, the developer can pull once by hand (git pull origin main) and then ask their agent to run this skill; every update after that is fully agent-driven.

Source of truth: updates come from https://github.com/bighadj22/codflow, branch main. Every fetch/merge in this runbook targets that repository and branch — never a fork, never another branch.

Report EVERY step to the user — devs and non-devs alike

The developer running this may be a non-developer ("vibe coder") who set CodFlow up with an agent and never touched git or wrangler themselves. After completing EACH step below, stop and tell the user what just happened, in plain language, before starting the next step:

• Say what you did, what it changed, and why — one short paragraph per step.
• Lead with the plain-language outcome, then the technical detail. Good:

  "✅ Step 2 of 8 done: I downloaded the latest CodFlow code (14 new versions since yours, including a fix for order tracking). Your files — database, images, settings, passwords — were not touched. Next: I'll check if the new version needs new settings added to your config files."

• Never dump raw command output at a non-dev without a one-line explanation of what it means.
• If a step needs a decision or a value only the user has (a password, a domain, a yes/no), ask clearly and wait — do not guess.
• If a step fails, say plainly what broke and what you will do about it before doing anything.

Do not stay silent across multiple steps and summarize at the end — the user must be able to follow the update as it happens.

What an update changes vs. what it must never touch

Before Starting — State This Contract

State this to the developer before running anything:

"This update will fetch the latest CodFlow code and merge it into your checkout, merge any new template settings into your wrangler.toml and .env files while keeping your resource IDs, worker names, and domains, apply any new D1 migrations to your database (existing data is untouched), and redeploy the affected workers. Nothing is re-created from scratch, no secrets are regenerated, and no demo data is re-seeded."

Prerequisites — Gates, In Order

1. This must be an existing install. Verify, from the repo root:

   test -f .env && test -f cod-server/wrangler.toml && test -f cod-client-astro/wrangler.toml && echo OK

   If any is missing, STOP — this is not a completed setup. Run the codflow-setup skill instead.

2. Correct upstream remote.

   git remote get-url origin    # expect .../bighadj22/codflow.git

   If origin points elsewhere (a fork, another copy), ask the developer where they track CodFlow updates. If upstream is not configured:

   git remote add upstream https://github.com/bighadj22/codflow.git

   and use upstream in place of origin throughout this runbook.

3. Cloudflare auth still valid.

   env -u CLOUDFLARE_ACCOUNT_ID npx wrangler whoami

   Same trap as setup: if the shell exports a stale CLOUDFLARE_ACCOUNT_ID the OAuth token cannot access, EVERY wrangler command fails with Authentication error [code: 10000]. Prefix every wrangler invocation with env -u CLOUDFLARE_ACCOUNT_ID (done throughout below).

4. Clean working tree.

   git status --porcelain

   • Gitignored files showing as untracked/modified (wrangler.toml, .env, .dev.vars) are expected and fine — confirm with git check-ignore .env cod-server/wrangler.toml that they are ignored.
   • Modified TRACKED files block the merge. Do not reset --hard on your own. Present the git status list to the developer and offer:
     • git stash push -m "local edits before codflow update" -- <files> (pop after the update, expect conflicts if the same lines changed upstream),
     • committing them to a local branch, or
     • discarding them — only with explicit confirmation.

5. Record the rollback point (mandatory).

   git rev-parse --short HEAD | tee /tmp/codflow-update-old-head
   git describe --tags HEAD 2>/dev/null || echo "(untagged)"

   Keep this for Step 8. Cloudflare also keeps each worker's previous deployment, so workers can be rolled back independently of the database.

Step 1 — Fetch and Assess (changes nothing yet)

git fetch origin main --tags
git rev-list --count HEAD..origin/main        # commits behind
git log --oneline HEAD..origin/main           # what's incoming

If the count is 0, the code is already current — but the install may still be stale (pulled but never migrated/deployed). Do NOT exit yet: run the assessment table below plus migrations list in Step 5; if everything is clean, report "fully up to date" and stop.

Capture the assessment BEFORE merging — after the merge these diff ranges are empty. Fill this in and show the resulting plan to the developer:

If CHANGELOG.md changed, read its new sections and summarize the user-visible changes for the developer before proceeding.

Present the plan ("I will merge N commits, apply migrations X–Y, add var Z to both wrangler.toml files, and redeploy cod-server + dashboard") and get a go-ahead. Migrations and redeploys touch their live store — never surprise them.

Step 2 — Merge the Code

git merge --ff-only origin/main

• --ff-only succeeds when the checkout has no local commits — the normal self-host case. If it refuses, the developer has local commits: git log --oneline origin/main..HEAD shows them. Offer to git rebase origin/main or stop and let the developer decide. Do not force the merge.
• If dependencies changed (Step 1 table), reinstall at the repo root:

  npm ci

  One root lockfile covers all workspaces — never create per-package lockfiles. If a dev server later dies with Missing field 'moduleType', a second Vite major crept in: rm -rf node_modules && npm ci, then npm ls vite must show a single major (the root overrides pin enforces it).

Step 3 — Sync the Gitignored Config with the New Templates

This is the step self-hosters miss. git pull updates wrangler.toml.example and .env.example, but NEVER the user's live gitignored files. When upstream adds a binding, a [vars] key, or a new .env key, the live files must be merged by hand (agent) or the next deploy breaks or the feature silently fails.

Work over these pairs:

1. Back up every live config file first

Into a directory OUTSIDE the repo (survives resets, never hits git):

BK="$HOME/.codflow-backups/$(date +%Y%m%d-%H%M%S)" && mkdir -p "$BK" && \
cp .env cod-client-astro/.env cod-server/wrangler.toml cod-client-astro/wrangler.toml "$BK/" && \
cp cod-server/.dev.vars cod-client-astro/.dev.vars cod-astro/theme01/.dev.vars "$BK/" 2>/dev/null; ls -la "$BK"

Report this path to the developer — it is the config-level rollback.

2. Diff live file against the CURRENT template

diff cod-server/wrangler.toml.example cod-server/wrangler.toml
diff cod-client-astro/wrangler.toml.example cod-client-astro/wrangler.toml
diff .env.example .env

This catches cumulative drift (not just this update) and works even when the developer already pulled the code themselves. Expect the live file to differ in resource IDs, worker names, and real domains — those differences are CORRECT. You are hunting only for things present in the template but MISSING from the live file.

3. Merge rules

• Add to the live file: new [vars] keys, new binding blocks ([[kv_namespaces]], [[r2_buckets]], [[d1_databases]], …), new top-level settings.
• Keep the user's value for: database_id, KV ids, bucket_name, MEDIA_DOMAIN, all URL vars (WORKER_URL, BETTER_AUTH_URL, PUBLIC_APP_URL, PUBLIC_API_URL, PUBLIC_TRUSTED_ORIGINS, COD_SERVER_URL), and every name = worker name. Never reset a worker name to the template default — that deploys onto (or creates) a DIFFERENT worker.
• Adopt upstream's compatibility_date and compatibility_flags changes — they are tied to what the new code expects. Note the change in the summary.
• A binding block copied from the template carries placeholder IDs. A genuinely NEW binding means a new resource — create it in Step 4, then bind the real ID. Never leave a placeholder. After merging, re-run the setup placeholder check and expect zero hits:

  grep -rn "00000000-0000\|00000000000000000000000000000000" \
    cod-server/wrangler.toml cod-client-astro/wrangler.toml

• Keys removed from a template: leave them in the live file, note it in the summary, and only remove after the developer confirms (removals are rare and may be staged rollouts).
• New keys in .env.example → add to .env. Fill values derivable from the install (e.g. a new COD_* key whose value equals an existing binding); otherwise ask the developer. COD_SERVER_URL must stay the real deployed origin — a loopback value blocks the theme01 deploy by design.

4. Confirm the live files are still ignored

git status --short .env cod-server/wrangler.toml cod-client-astro/wrangler.toml
# expected: nothing listed

If anything shows up, STOP — the .gitignore arrangement broke; fix before continuing.

Step 4 — New Resources and Secrets ONLY (conditional)

Skip entirely when Step 1 found no new bindings or secrets.

• New resource bindings (a [[kv_namespaces]]/[[r2_buckets]]/etc. block the live file lacked): create exactly that resource, nothing else, with the install's <project> prefix — env -u CLOUDFLARE_ACCOUNT_ID npx wrangler kv namespace create <name> — following the setup skill's rules: fresh unique names, never reuse a foreign existing resource, capture the real ID, bind it, re-run the placeholder grep.
• New secrets (new fields in cod-server/src/types/env.ts, or secret put mentions in the updated docs/skills): ask the developer for the value, then set with the setup skill's safe pattern — value via a chmod-600 temp file or stdin redirect, never echo/heredoc:

  printf '<value>' | env -u CLOUDFLARE_ACCOUNT_ID npx wrangler secret put <NAME> --name <server-worker-name>

  Also add it to the matching .dev.vars for local dev.
• NEVER regenerate existing secrets. BETTER_AUTH_SECRET and MCP_LOGIN_TICKET_SECRET must remain the SAME values on both workers — regenerating either invalidates every dashboard session and breaks cross-worker auth. An update only ever ADDS secrets.
• Optional features (Sendili email, WhatsApp OTP, Turnstile, …) stay opt-in. An update never configures them silently — mention them in the summary if the changelog announces them.