cpflow 6.0.0.rc.0 → 6.0.1

data/CONTRIBUTING.md

@@ -40,7 +40,7 @@ overcommit --install
 Every repository-based external `uses:` entry under `.github/workflows/` or `.github/actions/` must use an immutable,
 lowercase 40-character commit SHA followed by the exact release tag in a same-line comment. Do not use moving
 major-version tags or branch names. New action repositories also require explicit review before they are added to
-`trusted_actions` in `.agents/agent-workflow.yml`. Docker actions must use an exact `sha256:` image digest; manually
+`trusted_actions` in `.agents/trusted-actions.yml`. Docker actions must use an exact `sha256:` image digest; manually
 review the registry, image, and digest because Docker references are outside the repository allowlist.
 Generated downstream calls to Control Plane Flow's cross-repository reusable workflows are the deliberate exception:
 they use an exact `vX.Y.Z` release tag so the workflow source stays aligned with the released `cpflow` gem.
@@ -150,10 +150,10 @@ cpflow test
 
 ## Developing the GitHub flow generator
 
-`cpflow generate-github-actions` copies workflow templates in `lib/github_flow_templates/` and canonical composite actions in `.github/actions/cpflow-*` into a target repo's `.github/` directory. To work on this feature:
+`cpflow generate-github-actions` copies workflow templates in `lib/github_flow_templates/` into a target repo's `.github/` directory. The composite actions those workflows call stay in this repository's `.github/actions/cpflow-*`; workflows load them from the pinned `.cpflow` checkout as `./.cpflow/.github/actions/cpflow-*`. To work on this feature:
 
-- **Edit each canonical source in place.** The generator does no string-mangling beyond a small set of substitutions handled in `lib/command/generate_github_actions.rb`; what you put in `lib/github_flow_templates/.github/` is (almost) exactly what ships into a generated repo. Edit composite actions in the root `.github/actions/cpflow-*` directories. Make changes in those canonical sources, not in a generated copy.
-- **Surface area to keep consistent.** A change to a PR command (e.g. `+review-app-deploy`) usually touches three places: the trigger workflow (`lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml`), the PR-open quick reference (`cpflow-review-app-help.yml`), and the long-form help (`lib/github_flow_templates/.github/cpflow-help.md`). The AI flow prompt (`lib/command/ai_github_flow_prompt.rb`) also names commands and should be kept in sync.
+- **Edit each canonical source in place.** The generator does no string-mangling beyond a small set of substitutions handled in `lib/command/generate_github_actions.rb`; what you put in `lib/github_flow_templates/.github/` is (almost) exactly what ships into a generated repo. Edit composite actions in the root `.github/actions/cpflow-*` directories; they are not copied downstream. Make changes in those canonical sources, not in a generated copy.
+- **Surface area to keep consistent.** A change to a PR command (e.g. `+review-app-deploy`) usually touches three places: the trigger workflow (`lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml`), the PR-open quick reference (`cpflow-review-app-help.yml`), and the long-form help (`lib/github_flow_templates/.github/cpflow-help.md`). The AI flow prompt (`lib/command/ai_github_flow_prompt.txt`, mirrored in `docs/ai-github-flow-prompt.md`) also names commands and should be kept in sync.
 - **Run the generator spec on every change:**
 
   ```sh

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (6.0.0.rc.0)
+    cpflow (6.0.1)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

data/README.md

@@ -29,7 +29,7 @@ _If you need a free demo account for Control Plane (no CC required), you can con
 To bootstrap a new project, run three commands from the repo root:
 
 1. **`cpflow github-flow-readiness`** — gate for common rollout blockers (missing Rails runtime scaffold, legacy Ruby or Bundler toolchains, unpublished exact-pinned gems or npm packages, missing production Dockerfiles). Exits non-zero on any blocker.
-2. **`cpflow generate`** — creates `.controlplane/` scaffolding. Infers the app prefix from the repo directory, the base Ruby version from `.ruby-version`/`.tool-versions`/`Gemfile`, the JS package manager from `package.json`, repo-defined frontend precompile hooks (Shakapacker `precompile_hook`, React on Rails auto bundle generation), and switches to persistent `db` + `storage` volume templates when `config/database.yml` shows SQLite in production.
+2. **`cpflow generate`** — creates `.controlplane/` scaffolding and a safe root `.dockerignore` when one is missing. It infers the app prefix from the repo directory, the base Ruby version from `.ruby-version`/`.tool-versions`/`Gemfile`, the JS package manager from `package.json`, repo-defined frontend precompile hooks (Shakapacker `precompile_hook`, React on Rails auto bundle generation), and switches to persistent SQLite data + Active Storage volume templates when `config/database.yml` shows SQLite in production.
 3. **`cpflow generate-github-actions`** — adds the reusable GitHub Actions pipeline for review apps, staging deploys, and manual production promotion.
 
 The generated scaffold is a starting point. After generation, adapt `.controlplane/` for app-specific workloads (Sidekiq, Node renderer), wire any private-dependency Docker build settings (SSH key, optional known-host overrides), and verify that the production Docker build succeeds.
@@ -398,7 +398,7 @@ cpflow generate-github-actions
 bin/test-cpflow-github-flow
 ```
 
-`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate-github-actions` checks in the local `.github/actions/cpflow-*` implementations alongside the workflows, and also writes `bin/test-cpflow-github-flow` for local validation and `bin/pin-cpflow-github-ref` for temporarily pinning downstream wrappers to an upstream commit SHA during pre-release testing. `cpflow generate` already switches to persistent `db` and `storage` volumes when `config/database.yml` shows SQLite in production and preserves detected frontend precompile hooks, but you should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, give it the [AI rollout prompt](./docs/ai-github-flow-prompt.md) rather than a vague "set up CI" request.
+`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate-github-actions` writes the workflows, which load cpflow's composite actions from the pinned upstream ref, and also writes `bin/test-cpflow-github-flow` for local validation and `bin/pin-cpflow-github-ref` for temporarily pinning downstream wrappers to an upstream commit SHA during pre-release testing. `cpflow generate` already switches to persistent `/app/data` and `/app/storage` volumes when `config/database.yml` shows SQLite in production, redirects every detected production SQLite database into persistent storage, keeps migrations visible under `/app/db`, and preserves detected frontend precompile hooks. You should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, give it the [AI rollout prompt](./docs/ai-github-flow-prompt.md) rather than a vague "set up CI" request.
 
 For a live example, see the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md) repository.
 
@@ -545,6 +545,9 @@ If you want to run PostgreSQL on Control Plane instead of keeping a Heroku add-o
 persistent storage and optional scheduled backups. Additionally, we provide a default `postgres` template in this
 repository optimized for Control Plane and suitable for development purposes.
 
+For disposable review apps, see [PostgreSQL for review apps](./docs/postgres-review-apps.md)
+for helper ownership, automatic cleanup, and recovery after interrupted deletion.
+
 ## In-memory Databases
 
 E.g., Redis, Memcached.

data/docs/ai-github-flow-prompt.md

@@ -8,13 +8,109 @@ first.
 ## Recommended Prompt
 
 ```text
-Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
-
-If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in workflows and local actions move together. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
-
-Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
-
-Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML validation, and any CI-equivalent build steps. Push the branch and check the GitHub Actions results. Only stop early for a real external blocker or a product decision that changes scope.
+Set up Control Plane GitHub Flow for this repo.
+
+Before generating anything:
+- First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if
+  present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither
+  is possible, stop and report that blocker.
+- Use the same `cpflow` invocation for the rest of the rollout.
+- Start with `cpflow github-flow-readiness` and stop on any reported blockers.
+- The repo must be deployable from a clean clone: published package versions, complete runtime
+  scaffold, and a production Dockerfile that can build the app.
+- If any package version is unpublished, inaccessible from CI, or requires credentials that are not
+  already modeled in the repo or GitHub settings, stop and report the blocker instead of generating
+  workflow files.
+- If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not
+  even have a production Dockerfile yet, or if it is a monorepo without an already-decided single
+  app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
+
+Generate the flow:
+- If `.controlplane/` is missing, run `cpflow generate`.
+- Treat the generated app names as the repo-name default and rename them only if the
+  project needs a different prefix.
+- Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch
+  BRANCH` when staging should deploy from a branch other than `main`/`master`).
+- Keep review apps opt-in via `+review-app-deploy`.
+- Make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging
+  workflow's `on.push.branches` filter.
+- List the GitHub secrets and variables that must be configured.
+
+Keep the Control Plane Flow source pins together:
+- Do not hand-edit duplicated upstream refs into the generated wrappers.
+- Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each
+  reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its
+  `control_plane_flow_ref` setup input.
+- By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem
+  version; temporary explicit ref overrides are for unreleased testing and must keep all three
+  values synchronized.
+- Do not add `.github/actions/cpflow-*` copies; the workflows load cpflow's composite actions and
+  runtime source from the pinned `.cpflow` checkout.
+
+When bumping the `cpflow` gem in a downstream repo:
+- `cpflow update-github-actions` refreshes helpers while preserving all top-level workflows,
+  including their refs and triggers.
+- It reports `.github/actions/cpflow-*` copies left by cpflow 6.0.0; delete them once no workflow is
+  pinned to 6.0.0 or names one.
+- Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for
+  replacement, then review the diff and reapply downstream customizations.
+- A differing existing validator blocks all writes: preserve its downstream checks in executable
+  `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before
+  retrying.
+- The generated validator invokes that preserved extension and propagates its failures.
+- Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the
+  updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or
+  `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler).
+
+Review apps and workload sizing:
+- Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING`
+  when the generated review app config can be inferred.
+- For public demos, starter staging apps, and long-lived review apps, keep the app workload `type:
+  standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI:
+  true` so Control Plane can right-size CPU and memory allocation at that fixed replica count.
+- Shared Postgres and other stateful workloads are the usual exceptions and should stay manually
+  sized; Capacity AI is for supported stateless app/service workloads.
+- If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before
+  first deploy or plan a delete/recreate migration because Control Plane will not change an existing
+  `standard` workload to `serverless` in place.
+- For shared review-app resources such as one staging database, use `shared_secret_grants` and
+  `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this
+  keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost.
+
+Staging and production:
+- Document the one-time Control Plane bootstrap command for persistent staging and production apps
+  with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates,
+  document `cpflow apply-template` and the need for the app identity to have `reveal` on the app
+  secret policy.
+- Do not imply the staging deploy or promotion workflows create those persistent GVCs.
+- For production promotion, document a protected `production` GitHub Environment with required
+  reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not
+  as a repository or organization secret.
+
+Docker image and runtime:
+- Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn,
+  `pnpm`, or npm after the main install layer.
+- Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby
+  requirement.
+- Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a
+  `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the
+  generated Dockerfile runs that codegen step before `rails assets:precompile`.
+- If `config/database.yml` shows SQLite in production, confirm that the generated scaffold redirects
+  every production database file into persistent `/app/data` (or keeps it under persistent
+  `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage
+  under `/app/storage`, and runs `rails db:prepare`; otherwise keep the default Postgres workload.
+- If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated
+  workflows.
+- Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN
+  --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set
+  `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to
+  newline-delimited single tokens such as `--build-arg=FOO=bar`.
+
+Validate and finish:
+- Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML
+  validation, and any CI-equivalent build steps.
+- Push the branch and check the GitHub Actions results.
+- Only stop early for a real external blocker or a product decision that changes scope.
 ```
 
 ## Local Shortcut
@@ -46,7 +142,7 @@ Stop and report the blocker instead of generating `cpflow-*` workflow files when
 The rollout is done when all of the following are true:
 
 - `.controlplane/` exists and matches the actual app shape
-- `.github/cpflow-help.md`, `.github/workflows/cpflow-*`, and `.github/actions/cpflow-*` are in place
+- `.github/cpflow-help.md` and `.github/workflows/cpflow-*` are in place, with no `.github/actions/cpflow-*` copies
 - review apps are opt-in, staging auto-deploys from one branch, and production promotion is manual
 - required GitHub secrets and variables are documented for the repo
 - the production image build path is validated for the real app