@rehearsal-db/core 0.1.0-beta.6 → 0.1.0-beta.8

package/CHANGELOG.md

@@ -5,6 +5,38 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.8] - 2026-10-02
+
+### Fixed
+
+- Lifecycle commands now preserve an explicit `--config=<path>` through runtime
+  selection and execution. A command cannot silently operate on the default config's
+  baseline, runtime identity, ports, or cleanup target instead.
+
+## [0.1.0-beta.7] - 2026-10-02
+
+### Added
+
+- A concise roadmap prioritizes real-project acceptance, easier baseline onboarding,
+  and another ordinary PostgreSQL project before further database expansion.
+- A preview-first cleanup command for old baseline generations, the current project's
+  disposable runtime, and explicitly selected older unused Supabase images. Applying a
+  cleanup requires the exact digest from its preview.
+- First-run setup now generates a fully populated, commented configuration that explains
+  safe defaults, project-specific checks, and optional local-only settings in place.
+
+### Changed
+
+- Rehearsal now respects user-owned Colima CPU, memory, and disk settings. Projects may
+  configure Colima auto-start and baseline retention in `rehearsal.config.mjs`.
+
+### Fixed
+
+- Beta publishing now updates both npm's `beta` and `latest` tags after registry
+  verification, keeping the package page and default install on the newest reviewed
+  beta. A protected manual repair path fixes existing tag drift without storing an npm
+  token or choosing an arbitrary version.
+
 ## [0.1.0-beta.6] - 2026-10-02
 
 ### Changed
@@ -170,7 +202,9 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.6...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.8...HEAD
+[0.1.0-beta.8]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.7...v0.1.0-beta.8
+[0.1.0-beta.7]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.6...v0.1.0-beta.7
 [0.1.0-beta.6]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.5...v0.1.0-beta.6
 [0.1.0-beta.5]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.4...v0.1.0-beta.5
 [0.1.0-beta.4]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.3...v0.1.0-beta.4

package/README.md

@@ -31,9 +31,11 @@ npm install --save-dev @rehearsal-db/core@beta
 npx rehearsal
 ```
 
-The guide shows your progress and offers the next safe action. On first use, choose
-**Set the stage**, select Supabase or PostgreSQL, review the preview, and confirm the files
-it will create. Existing files are never overwritten.
+The first run detects your project and offers to create a commented
+`rehearsal.config.mjs` with the project name, migration paths, commands, ports, and safe
+defaults already filled in. Choose **Set the stage**, select Supabase or PostgreSQL,
+review the preview, and confirm the files it will create. Existing files are never
+overwritten.
 
 For PostgreSQL, download the reviewed local image once before running the guide:
 
@@ -61,6 +63,10 @@ Start with synthetic data. Rehearsal does not copy or sanitize production data f
 5. Run the rehearsal and your application proof.
 6. Test the local application, then verify, reset, stop, or discard the runtime.
 
+When local disk space gets tight, choose **Clean up disk space** in the guide. Rehearsal
+previews old baseline generations first and keeps runtime or shared-image removal
+explicit.
+
 Press `Ctrl+Z` at any guided prompt to exit the whole session. Choose **Get help**, or run
 `npx rehearsal support`, to create a privacy-safe diagnostic report.
 
@@ -98,6 +104,7 @@ Start here:
 - [Getting started](docs/getting-started.md) — set up your own project
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
+- [Next steps](docs/roadmap.md) — see the current product sequence
 
 Reference:
 

package/docs/commands.md

@@ -59,11 +59,36 @@ and process exit code, not parse human-facing text.
 | `npx rehearsal reset`                                 | Discard runtime edits and restore the baseline.                     |
 | `npx rehearsal stop`                                  | Stop the runtime but keep its local state.                          |
 | `npx rehearsal discard`                               | Remove this project's disposable runtime and volume.                |
+| `npx rehearsal cleanup`                               | Preview conservative cleanup without removing anything.             |
 
 In a terminal, the guide displays candidate filenames and asks for confirmation. In a
 script, copy the digest from `candidates` into `--confirm-candidates`. Adding, removing,
 reordering, or editing a migration changes that digest.
 
+## Clean up disk space
+
+Start with a preview:
+
+```bash
+npx rehearsal cleanup
+```
+
+By default, cleanup selects only old baseline generations beyond the retention setting
+in `rehearsal.config.mjs`. Add options to broaden the preview:
+
+| Command option      | Additional resources considered                                        |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--include-runtime` | This project's disposable runtime and its database volumes.            |
+| `--include-images`  | Older unused Supabase images; the newest image for each service stays. |
+| `--write`           | Apply the exact freshly verified preview.                              |
+| `--confirm-cleanup` | Full cleanup digest printed by the preview; required with `--write`.   |
+
+Image cleanup never removes an image used by any running or stopped container and never
+runs a global Docker prune. Images may be shared by projects and can be downloaded again,
+so they remain excluded unless you explicitly add `--include-images`. Database volumes
+belonging to other projects are never included. This follows
+[Docker's conservative pruning guidance](https://docs.docker.com/engine/manage-resources/pruning/).
+
 ## Common options
 
 | Option                          | Meaning                                                          |
@@ -72,7 +97,16 @@ reordering, or editing a migration changes that digest.
 | `--verbose`                     | Show more safe detail.                                           |
 | `--debug`                       | Show the most diagnostic detail; still review it before sharing. |
 | `--plain`                       | Disable decorative interactive prompts.                          |
-| `--config=<path>`               | Use a specific config file inside the project.                   |
+| `--config=<path>`               | Use only this config for planning and every runtime action.      |
 | `--target=supabase\|postgresql` | Choose the setup target.                                         |
+| `--include-runtime`             | Include this project's runtime in a cleanup preview.             |
+| `--include-images`              | Include older unused Supabase images in a cleanup preview.       |
+| `--confirm-cleanup=<digest>`    | Confirm the exact cleanup set printed by the preview.            |
+| `--write`                       | Apply a setup, policy, or cleanup preview.                       |
 
 Run `npx rehearsal --help` to print the command list available in your installed version.
+
+When a project has more than one config, pass `--config=<path>` on every command for the
+non-default one. Rehearsal keeps that exact config selected through status, run, reset,
+start, migrate, verify, stop, discard, and cleanup; it will not fall back to
+`rehearsal.config.mjs` during a runtime action.

package/docs/configuration.md

@@ -6,29 +6,55 @@ Most users should let the guide create this file:
 npx rehearsal
 ```
 
-Use this page when reviewing or changing the generated `rehearsal.config.mjs`. The schema
-is strict: misspelled fields, unknown fields, and unsupported versions are errors. The
-`.mjs` extension works in both CommonJS and ESM projects.
+The first run uses your chosen database type and detects the project name, migration
+folder, package-manager commands, and free local ports. After you approve the setup
+preview, it creates a commented `rehearsal.config.mjs` with those values filled in.
+Installation itself does not use a `postinstall` script or silently modify the project.
+
+Review lines marked `CHECK`, especially the application proof command. Optional settings
+are present as commented examples, and secrets never belong in this file. Rehearsal will
+not overwrite an existing config.
+
+Use this page when changing the generated file. The schema is strict: misspelled fields,
+unknown fields, and unsupported versions are errors. The `.mjs` extension works in both
+CommonJS and ESM projects.
 
 ```ts
+// @ts-check
 import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
+  // Configuration format. Rehearsal will explain if an upgrade is ever needed.
   schemaVersion: 1,
+  // Stable local name used in Rehearsal labels and reports.
   project: { name: "example-app" },
+
+  // Project files Rehearsal reads. Every path stays inside this repository.
   supabase: {
     workdir: ".",
     migrationDirectory: "supabase/migrations",
     rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
     runtimeWorkdir: ".rehearsal/runtime",
+
+    // Optional; configure both keys together.
+    // serviceEnvironmentFile: ".env.rehearsal-service.local",
+    // serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
   },
   baseline: {
     artifactDirectory: ".rehearsal",
     sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
   },
+  containerRuntime: {
+    autoStartColima: true,
+  },
+  cleanup: {
+    retainBaselineGenerations: 2,
+  },
   application: {
+    // CHECK: replace these when the detected package scripts are not correct.
     startCommand: "npm run dev:rehearsal",
     proofCommand: "npm run test:rehearsal",
+    environmentFile: ".rehearsal/runtime.env",
   },
   runtime: {
     target: "supabase",
@@ -38,7 +64,16 @@ export default defineRehearsalConfig({
     databasePort: 58322,
     studioPort: 58323,
   },
-  safety: { hostedAccess: "disabled", outboundNetwork: "deny" },
+  safety: {
+    allowedHosts: ["127.0.0.1", "::1", "localhost"],
+    blockedEnvironmentVariables: [
+      "SUPABASE_ACCESS_TOKEN",
+      "SUPABASE_DB_PASSWORD",
+      "SUPABASE_PROJECT_ID",
+    ],
+    hostedAccess: "disabled",
+    outboundNetwork: "deny",
+  },
 });
 ```
 
@@ -51,6 +86,26 @@ All paths resolve inside the consuming project. The artifact directory must be n
 Rehearsal never overwrites this config. To start over, move the existing file somewhere
 safe, run setup again, and compare the two files before deleting either one.
 
+## Container runtime and cleanup
+
+```ts
+containerRuntime: {
+  autoStartColima: true,
+},
+cleanup: {
+  retainBaselineGenerations: 2,
+},
+```
+
+Rehearsal uses whichever Docker-compatible engine already answers `docker info`. If none
+is running and `autoStartColima` is `true`, Rehearsal may run `colima start`. It respects
+the user's Colima CPU, memory, and disk settings and never changes them. Set the field to
+`false` when you prefer to start Docker or Colima yourself.
+
+`retainBaselineGenerations` controls how many immutable baseline generations survive
+`rehearsal cleanup`; it must be at least 1. Runtime deletion and shared-image inspection
+are command choices, not automatic retention settings. See [CLI commands](commands.md).
+
 ## Supabase service environment
 
 Some local identity providers need a client ID and secret. Configure both fields or
@@ -67,9 +122,12 @@ terminate at local Auth. They do not grant hosted database access.
 
 ## Safety fields
 
-Version 1 accepts loopback hosts only. `hostedAccess` can only be `disabled`, and
-`outboundNetwork` can only be `deny`. Ambient hosted Supabase variables are quarantined
-from child processes. There is no force flag to weaken these rules.
+Version 1 accepts loopback runtime URLs only. `hostedAccess` can only be `disabled`, and
+`outboundNetwork` can only be `deny`. Common hosted Supabase and PostgreSQL credentials
+are quarantined from child processes. These fields are fail-closed configuration rules,
+not a host firewall: trusted project proof commands and runtime adapters remain ordinary
+local code and must be reviewed. There is no force flag to weaken the configuration
+rules.
 
 ## Ports and project identity
 

package/docs/releasing.md

@@ -52,7 +52,16 @@ publication must change and prove the workflow before narrowing that permission.
     protected integration branches and rerun their complete verification.
 
 The workflow publishes prereleases under the `beta` dist-tag and refuses a stable
-version. A stable tag requires a later contract, compatibility, and release decision.
+version. While Rehearsal has no stable release, the workflow also moves `latest` to the
+same reviewed beta. This keeps the npm package page and the ordinary
+`npm install @rehearsal-db/core` command current. When Rehearsal gains a stable release,
+`latest` must switch to the stable line while `beta` continues to identify prereleases.
+
+The trusted publisher allows `npm dist-tag` only so this workflow can maintain those two
+tags without a stored npm token. A manual workflow run from `main` can repair the tags
+for the exact prerelease version currently recorded in `package.json`; it cannot publish
+a package or select a different version. The protected `npm` environment still supplies
+the human approval gate.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,
 or creating a tag does not authorize npm publication. Publication requires explicit

package/docs/roadmap.md

@@ -0,0 +1,39 @@
+# Next steps
+
+The current Rehearsal beta supports guided Supabase and ordinary PostgreSQL rehearsals.
+The next work should be driven by real project use before adding more database targets.
+
+## 1. Complete the first real-project acceptance run
+
+Update an existing Supabase application to `@rehearsal-db/core@beta` on its own clean
+branch, then prove:
+
+- `doctor` reports `READY`;
+- the intended candidate migrations are the only candidates;
+- a complete rehearsal and the application proof pass;
+- verify, reset, stop, and restart behave as expected.
+
+Record any confusing instruction or unnecessary manual step. Those findings should guide
+the next usability changes.
+
+## 2. Simplify baseline onboarding
+
+Make safe records, migration evidence, and sanitization-policy review easier for a new
+developer. Reduce manual file preparation without weakening review, checksum, or
+local-only safety rules.
+
+## 3. Validate another ordinary PostgreSQL project
+
+Use a non-Supabase application with real migration history and a synthetic baseline.
+Fix general PostgreSQL problems before adding provider-specific behavior.
+
+## 4. Consider PostgreSQL service compatibility
+
+Only after the ordinary PostgreSQL workflow is reliable, evaluate compatibility needs
+for individual PostgreSQL services. Keep rehearsals disposable and local; hosted database
+execution remains outside the current safety model.
+
+## Later
+
+MySQL, MongoDB, and unrelated database families require different migration and restore
+behavior. They remain out of scope until the PostgreSQL experience is proven and stable.

package/docs/troubleshooting.md

@@ -39,6 +39,29 @@ writes setup files.
 Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
 Restarting the computer is rarely necessary.
 
+## Docker or Colima is out of disk space
+
+Preview what Rehearsal can safely remove:
+
+```bash
+npx rehearsal cleanup --include-images
+```
+
+Review the list, then add `--write` and the printed `--confirm-cleanup` digest. Rehearsal
+keeps the newest Supabase image for each service, refuses images used by any running or
+stopped container, and never runs a global Docker or volume prune. Add
+`--include-runtime` only when this project's disposable database may also be removed.
+
+For example, copy the full digest from your preview:
+
+```bash
+npx rehearsal cleanup --include-images --write --confirm-cleanup=PASTE_FULL_DIGEST_HERE
+```
+
+For Colima, disk capacity belongs to the user rather than the project. Increase it with
+`colima stop` followed by a larger `colima start --disk <GiB>` value. Rehearsal respects
+that configuration and does not choose a disk size.
+
 ## The guide does not show styled menus
 
 Rehearsal uses numbered menus when terminal styling is unavailable, `NO_COLOR` is set, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "private": false,
   "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
   "repository": {

package/scripts/lib/environment/local_supabase.mjs

@@ -62,14 +62,13 @@ export const localCommandSucceeds = (
     stdio: "ignore",
   }).status === 0;
 
-export const ensureLocalContainerRuntime = ({ cwd = process.cwd() } = {}) => {
+export const ensureLocalContainerRuntime = ({
+  cwd = process.cwd(),
+  autoStartColima = true,
+} = {}) => {
   if (localCommandSucceeds("docker", ["info"], { cwd })) return;
-  if (localCommandSucceeds("colima", ["version"], { cwd })) {
-    runLocalCommand(
-      "colima",
-      ["start", "--cpu", "4", "--memory", "4", "--disk", "40"],
-      { cwd },
-    );
+  if (autoStartColima && localCommandSucceeds("colima", ["version"], { cwd })) {
+    runLocalCommand("colima", ["start"], { cwd });
   }
   if (!localCommandSucceeds("docker", ["info"], { cwd })) {
     throw new Error(
@@ -118,8 +117,9 @@ export const startLocalSupabase = ({
   exclude = [],
   environment = {},
   applyMigrations = true,
+  autoStartColima = true,
 } = {}) => {
-  ensureLocalContainerRuntime({ cwd });
+  ensureLocalContainerRuntime({ cwd, autoStartColima });
   const startArguments = withWorkdir(
     ["start", ...(exclude.length ? ["--exclude", exclude.join(",")] : [])],
     workdir,

package/scripts/lib/rehearsal/baseline_artifact.mjs

@@ -478,7 +478,7 @@ export const listIncompleteBaselineBuilds = async ({ artifactRoot }) => {
   }
 };
 
-export const pruneBaselineGenerations = async ({
+export const planBaselineGenerationPrune = async ({
   artifactRoot,
   retain = 2,
 }) => {
@@ -516,7 +516,36 @@ export const pruneBaselineGenerations = async ({
   const removed = entries
     .map((entry) => entry.name)
     .filter((name) => !retained.has(name));
-  for (const name of removed) {
+  return { retained: [...retained], removed };
+};
+
+export const pruneBaselineGenerations = async ({
+  artifactRoot,
+  retain = 2,
+  expectedRemoved,
+}) => {
+  const root = assertArtifactRoot(artifactRoot);
+  const plan = await planBaselineGenerationPrune({
+    artifactRoot: root,
+    retain,
+  });
+  const generationsRoot = join(root, generationsDirectoryName);
+  if (
+    expectedRemoved &&
+    (expectedRemoved.length !== plan.removed.length ||
+      expectedRemoved.some((name, index) => name !== plan.removed[index]))
+  ) {
+    throw new Error(
+      "Rehearsal baseline generations changed after the cleanup preview.",
+    );
+  }
+  for (const name of plan.removed) {
+    const active = await resolveActiveBaselinePaths({ artifactRoot: root });
+    if (basename(active.generationDirectory) === name) {
+      throw new Error(
+        "Refusing to prune the active Rehearsal baseline generation.",
+      );
+    }
     const target = assertInsideRoot(
       generationsRoot,
       join(generationsRoot, name),
@@ -525,7 +554,7 @@ export const pruneBaselineGenerations = async ({
     await makeArtifactTreeWritable(target);
     await rm(target, { recursive: true, force: true });
   }
-  return { retained: [...retained], removed };
+  return plan;
 };
 
 export const removeBaselineArtifactRoot = async ({ artifactRoot }) => {