@rehearsal-db/core 0.1.0-rc.9 → 1.0.1

package/dist/src/shared/terminal_input.mjs

@@ -0,0 +1,129 @@
+/** Own terminal control bytes without suspending the invoking shell's npm job. */
+const leases = new WeakMap();
+export const hasTerminalInputLease = (input) => !!input && leases.has(input);
+/** Prompt libraries may restore cooked mode; resume only a still-owned lease. */
+export const reassertTerminalInputLease = (input) => {
+    if (!input || !leases.get(input)?.interactive)
+        return;
+    if (input.isRaw !== true)
+        input.setRawMode?.(true);
+    input.resume?.();
+};
+const restoreInput = (input, lease) => {
+    if (!lease.interactive)
+        return;
+    const errors = [];
+    try {
+        if (lease.changedRaw)
+            input.setRawMode?.(lease.wasRaw);
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    try {
+        // A previously untouched (null) stream must return to non-consuming mode,
+        // just like a previously paused stream; do not leave stdin keeping Node alive.
+        if (lease.wasFlowing)
+            input.resume?.();
+        else
+            input.pause?.();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, "Terminal input restoration failed.");
+};
+/**
+ * Raw input turns Ctrl+C/Ctrl+Z into bytes instead of kernel signals to the
+ * entire foreground npm/shell job. Signal handlers remain responsible for
+ * externally delivered signals. The final overlapping lease restores only the
+ * mode/flow state this owner acquired; a pre-existing raw terminal stays raw.
+ */
+export const acquireTerminalInput = (input, onInterrupt) => {
+    if (!input)
+        return Object.assign(() => undefined, { isCurrentOwner: () => true });
+    const owner = { interrupt: onInterrupt };
+    let lease = leases.get(input);
+    const first = !lease;
+    if (!lease) {
+        const owners = [];
+        lease = {
+            owners,
+            interactive: input.isTTY === true,
+            wasRaw: input.isRaw === true,
+            wasFlowing: input.readableFlowing === true,
+            changedRaw: input.isTTY === true &&
+                input.isRaw !== true &&
+                typeof input.setRawMode === "function",
+            dispatch: (chunk) => {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const signal = bytes.includes(0x03)
+                    ? "SIGINT"
+                    : bytes.includes(0x1a)
+                        ? "SIGTSTP"
+                        : null;
+                // Capture one owner before dispatch: synchronous release must not deliver
+                // the same byte again to an outer operation.
+                const current = owners.at(-1);
+                if (signal)
+                    current?.interrupt(signal);
+            },
+        };
+        leases.set(input, lease);
+    }
+    lease.owners.push(owner);
+    try {
+        if (first && lease.changedRaw)
+            input.setRawMode(true);
+        if (first && lease.interactive)
+            input.prependListener("data", lease.dispatch);
+        if (lease.interactive)
+            input.resume?.();
+    }
+    catch (error) {
+        const errors = [error];
+        lease.owners.splice(lease.owners.indexOf(owner), 1);
+        try {
+            if (first && lease.interactive)
+                input.removeListener("data", lease.dispatch);
+        }
+        catch (cleanupError) {
+            errors.push(cleanupError);
+        }
+        if (first) {
+            leases.delete(input);
+            try {
+                restoreInput(input, lease);
+            }
+            catch (cleanupError) {
+                errors.push(cleanupError);
+            }
+        }
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Terminal input could not be acquired or restored.");
+        throw error;
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        lease.owners.splice(lease.owners.indexOf(owner), 1);
+        if (lease.owners.length === 0) {
+            leases.delete(input);
+            try {
+                if (lease.interactive)
+                    input.removeListener("data", lease.dispatch);
+            }
+            finally {
+                restoreInput(input, lease);
+            }
+        }
+    };
+    return Object.assign(release, {
+        isCurrentOwner: () => !released && lease.owners.at(-1) === owner,
+    });
+};

package/docs/commands.md

@@ -324,7 +324,8 @@ Clients should disable conflicting actions unless the state is `idle`.
 
 ### Cancelling a mutation
 
-`run`, `reset`, `migrate`, and confirmed `refresh` support package-owned cancellation.
+`run`, `reset`, `migrate`, confirmed `refresh`, and direct or guided `open` preparation support
+package-owned cancellation.
 Send `SIGINT`, `SIGTERM`, `SIGHUP`, or `SIGTSTP` to the Rehearsal CLI process. Rehearsal
 handles repeated delivery as one request, forwards it only to the detached process group
 it launched, waits for package rollback and child cleanup, releases the project lock, and
@@ -343,6 +344,14 @@ The CLI does not stop Docker itself, signal unrelated processes, prune shared re
 or delete unrelated volumes. `SIGTSTP` is treated as cancellation and becomes `SIGTERM`
 for the owned child group instead of suspending it mid-cleanup. Windows uses direct child
 signalling; the detached process-group guarantee is supported on macOS and Linux.
+During an interactive cancellable operation, Rehearsal temporarily owns terminal control
+input so `Ctrl+C` and `Ctrl+Z` request cleanup without suspending an invoking npm job.
+It restores the terminal's previous raw mode and consuming/non-consuming input state
+after cleanup. Piped input is not consumed by this shortcut.
+For direct or guided `open`, cancellation before the ready attached session returns this same
+exit `130` contract, including interruption during runtime preparation or application
+readiness. A cancellation during the ready application's handoff stops that owned
+application before returning; cleanup failure is not reported as clean cancellation.
 
 `SIGKILL`, host shutdown, and a force-quit cannot produce a result or run cleanup. After
 one of those events, clients must not guess: run `activity --json`. A `stale` or `invalid`
@@ -384,6 +393,13 @@ default `keep-until-stop` leaves databases running; `stop-on-application-exit` s
 with database and Storage changes preserved. Likewise, `lifecycle.run` can remain
 `keep-until-stop` or use `stop-after-run` for bounded automation. JSON results include
 the selected mode, final runtime state, and preserved-data guarantee.
+While the ready application or copied-account sign-in session is attached, terminal
+`Ctrl+C` and `Ctrl+Z` are handled as control bytes rather than suspending npm wrappers.
+Rehearsal restores the prior terminal mode after retiring its owned application; it
+never resumes or signals an invoking shell, npm ancestor, or unrelated job.
+Once the ready application is attached, its handled `Ctrl+C`, `Ctrl+Z`, `SIGINT`, or
+`SIGTSTP` closes the session with exit `0` as before; it does not also cancel an outer
+preparation owner. Nested input ownership dispatches a control byte only once.
 
 ## Clean up disk space
 

package/docs/getting-started.md

@@ -5,6 +5,54 @@ your computer. Normal setup and rehearsal commands never connect to a hosted dat
 
 Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
+## OS-specific setup files (optional)
+
+Separate setup folders are available for
+[Windows / WSL 2](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/windows),
+[macOS](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/macos) and
+[Linux](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/linux).
+They are readable helpers, not native executables or bundled Node/Docker installers.
+Existing Node.js 24 or 26 is required. The default only checks an existing project;
+installation needs an explicit option and does not start a database. Review the
+[shared behavior and release availability](https://github.com/Ddupasquier/rehearsal-db/blob/main/installers/README.md)
+before choosing an install option. An exact core 1.0.1 install requires that version to
+be published; a checked-in helper is not proof of publication.
+
+### Windows: use a WSL 2 Linux workspace
+
+The Windows compatibility route is Linux execution inside **WSL 2**, not a native
+PowerShell/Command Prompt database runtime. Core 1.0.1 and extension 0.1.21 make that
+boundary explicit; native Windows version/help/discovery do not authorize runtime work.
+
+1. Follow Microsoft's [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install)
+   to prepare a WSL 2 Linux distribution, such as Ubuntu 24.04. Do not use WSL 1.
+2. Clone or open the project inside the distribution's Linux home directory, such as
+   `/home/your-name/projects/app`. Do not keep the runtime project under `/mnt/c`, a
+   Windows share or a Windows-mounted drive. Rehearsal does not relocate your files.
+3. Install a supported **Linux** Node/npm and a Docker-compatible Linux engine in that
+   environment. Docker Engine in WSL or an already configured Docker Desktop WSL
+   integration are user-controlled setup choices; Rehearsal does not install or license
+   Docker Desktop for you. In the Linux terminal, check:
+
+   ```bash
+   node -p "process.platform"
+   pwd
+   docker info --format '{{.OSType}}'
+   ```
+
+   Both platform results must be `linux`, and `pwd` must be in the Linux filesystem.
+
+4. For editor use, install Microsoft's **WSL** extension, then run `code .` from that
+   Linux project directory. Confirm the VS Code window says **WSL** in its remote
+   indicator, and install Rehearsal into **WSL**, not only the Windows-side extension host.
+5. Continue below from that Linux terminal. Keep the existing baseline, approval and
+   local-only checks; do not substitute a hosted database to make setup pass.
+
+WSL is a compatibility preview. A real WSL PostgreSQL fixture and a native Remote-WSL
+editor walkthrough are different evidence; do not infer the latter from Linux unit
+tests. Supabase/Auth/Storage in WSL and other remote hosts remain unclaimed until their
+own checks pass. See the [complete platform boundary](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md#operating-systems-and-execution-location).
+
 ## 1. Check the required tools
 
 You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24

package/docs/index.md

@@ -12,6 +12,11 @@ Rehearsal catches those problems before deployment. It restores a reviewed, sani
 baseline into a disposable local PostgreSQL or Supabase environment, applies only the
 exact migrations you approve, and runs your application's own proof.
 
+The [CLI is free and MIT-licensed](https://www.npmjs.com/package/@rehearsal-db/core).
+Prefer clicks to commands? [Install the free VS Code Starter preview](vscode.md).
+All features included in its Starter-licensed releases are free indefinitely, with no
+account, payment card, or trial period.
+
 | Empty-database tests miss…                        | Rehearsal exercises…                                      |
 | ------------------------------------------------- | --------------------------------------------------------- |
 | old rows and edge cases                           | a reviewed, production-shaped baseline                    |
@@ -23,15 +28,16 @@ exact migrations you approve, and runs your application's own proof.
 You do not need to read everything before your first rehearsal. Start with the outcome
 you want, then follow the links when a term or safety check is new.
 
-| I want to…                              | Go here                                                           |
-| --------------------------------------- | ----------------------------------------------------------------- |
-| Set up my own project                   | [Getting started](getting-started.md)                             |
-| Try Rehearsal without touching my app   | [Hands-on tutorial](tutorial.md)                                  |
-| Understand what makes a copy safe       | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
-| Look up a command or setting            | [CLI commands](commands.md) and [Configuration](configuration.md) |
-| Reduce Docker and Supabase resource use | [Container runtime lifecycle](runtime-lifecycle.md)               |
-| Add editor and compiler type checks     | [TypeScript](typescript.md)                                       |
-| Fix something that did not work         | [Troubleshooting](troubleshooting.md)                             |
+| I want to…                               | Go here                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| Set up my own project                    | [Getting started](getting-started.md)                             |
+| Use the free visual workbench in VS Code | [Install VS Code Starter](vscode.md)                              |
+| Try Rehearsal without touching my app    | [Hands-on tutorial](tutorial.md)                                  |
+| Understand what makes a copy safe        | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
+| Look up a command or setting             | [CLI commands](commands.md) and [Configuration](configuration.md) |
+| Reduce Docker and Supabase resource use  | [Container runtime lifecycle](runtime-lifecycle.md)               |
+| Add editor and compiler type checks      | [TypeScript](typescript.md)                                       |
+| Fix something that did not work          | [Troubleshooting](troubleshooting.md)                             |
 
 ## The short version
 

package/docs/releasing.md

@@ -95,23 +95,27 @@ than seven days or in the future. Public fields and timestamps must still match
 bypass metadata is hidden; an explicitly malformed or nonempty bypass list always
 refuses publication.
 
-The prepare job prints an exact approval comment in its summary. Independently check
-the live no-bypass settings and accepted artifact checksum, then paste the comment into
-**Review deployments → npm** and approve manually. Before publishing or repairing
-tags, the workflow reads GitHub's actual approval history and requires the configured
-owner's authenticated review for that npm environment. The comment binds the operation,
-run ID, run attempt, source commit, artifact SHA-256 and settings-record SHA-256.
-GitHub may store the form's line breaks as CRLF instead of LF. The checker treats
-those two encodings as equivalent; it does not trim whitespace or change any field.
-An approval copied from another artifact, run or attempt is refused. Rerun the whole
-workflow after failure so preparation prints a new attempt-bound comment; do not reuse
-an earlier comment when rerunning only the mutation job.
-
-The record alone is never authorization. This mechanism relies on the owner's fresh
-settings review and GitHub's reported timestamps; timestamps are not cryptographic
-proof of every hidden setting change. No settings check eliminates a subsequent
-administrator change or check-to-use race. Keep the npm environment's no-bypass human
-gate enforced. See [GitHub's ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
+The prepare job displays the exact package version, SHA-256, source commit and run
+in its summary. Review the candidate and passed checks, then choose **Review
+deployments → npm → Approve and deploy**. That ordinary GitHub approval is the
+publication authorization: no separate chat approval, secret phrase or pasted block
+is required. Comments are optional.
+
+GitHub's enforced, no-bypass `npm` environment admits the publishing job only after
+its protection rules pass. The workflow also reads this run's actual review history
+to corroborate the configured human owner's approval for the exact npm environment.
+That history does not identify an approval's run attempt or verify artifact bytes;
+the workflow independently checks the prepared tarball's hashes before publication,
+and freshly downloads/checks registry bytes before tag repair. Reruns keep the same
+source/ref and remain subject to GitHub's environment controls; old review text is
+never presented as proof of new bytes or a fresh attempt.
+
+The unsigned settings record remains a bounded drift check, not authorization or
+cryptographic proof of current hidden bypass settings. Refresh its owner observation
+when stale or changed; never advance its timestamp without reading the settings.
+No settings check eliminates a later administrator change or check-to-use race.
+See [GitHub's deployment review](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments),
+[ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
 and [workflow approval history](https://docs.github.com/en/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run).
 
 Keep customer evidence, credentials, runtime data and the internal tracker out of public
@@ -137,11 +141,12 @@ release-source migration.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.
-7. Obtain explicit publication authorization for that exact version and artifact.
-8. Merge the approved release commit through protected `main` and create the exact
+7. Review the release change and its exact artifact evidence.
+8. Merge the reviewed release commit through protected `main` and create the exact
    `v<package-version>` tag and GitHub release.
-9. Review and approve the protected `npm` deployment only after its prepare job matches
-   the approved version and checksum, using its exact approval comment.
+9. Authorize publication once, in the protected `npm` deployment review, after its
+   prepare job matches the tested version and checksum. No comment or chat approval
+   is required.
 10. Verify public visibility, ownership, provenance, registry SHA-1, README rendering,
     exact-version clean installation, CLI execution, signatures, and the unrelated
     installed Docker fixture. Allow up to six minutes for a first package to propagate
@@ -154,6 +159,28 @@ The independent Rehearsal Test Lab is the primary pre-release consumer environme
 Real product integrations provide additional compatibility evidence; they do not
 replace the package-owned release gate or Test Lab.
 
+### Optional remote verification
+
+When local resource guards refuse a heavy run, the existing full release check can
+run on an isolated GitHub-hosted runner instead:
+
+```bash
+gh workflow run verify.yml --ref YOUR_REVIEWED_RELEASE_BRANCH -f exact_release=true
+```
+
+This manual-only option runs `npm run release:verify` and the production dependency
+audit. It adds no required branch check and has no publishing permission or npm
+environment. It does not bypass a local resource guard or start local services.
+The other existing verification jobs still run normally.
+
+Download the run's `exact-release-<commit>-<attempt>` artifact within seven days.
+It contains only the frozen tarball and release reports. Require a successful job
+and all nine passed stages in `acceptance.json`, match the reviewed source commit
+and tarball SHA-256, then use those exact bytes for consumer checks and publication
+authorization. Reports retained after failure are failure evidence, not approval.
+This is an execution option for the same release requirements, not a substitute for
+consumer acceptance, supported-platform observations or human publication approval.
+
 The workflow publishes beta and release-candidate versions under the `beta` dist-tag.
 While Rehearsal has no stable release, it also moves `latest` to the same reviewed
 prerelease. This keeps the npm package page and the ordinary
@@ -177,6 +204,5 @@ package or select a different version. The `npm` environment must supply the ver
 human approval gate; a workflow reference to that environment is not sufficient.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,
-or creating a tag does not authorize npm publication. Publication requires explicit
-authorization for the exact packed artifact, and the protected GitHub environment
-supplies the final human gate.
+or creating a tag does not authorize npm publication. The protected GitHub deployment
+review supplies the single human authorization for the exact displayed artifact.

package/docs/roadmap.md

@@ -1,8 +1,13 @@
 # Next steps
 
-Rehearsal supports guided Supabase and ordinary PostgreSQL migration rehearsals. The
-current development track removes the need for consumer-owned Rehearsal engines while
-keeping application meaning and privacy decisions project-owned.
+Rehearsal core **1.0.0 is available on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core)** for guided Supabase and
+ordinary PostgreSQL migration rehearsals. The [free VS Code Starter preview](vscode.md)
+adds a visual workbench. Neither requires a purchase or account.
+
+The standalone workflow keeps the rehearsal engine in the package while application
+meaning and privacy decisions remain project-owned. The sequence below explains its
+dependencies, not a list of features withheld from the published release.
 
 ## Standalone workflow
 

package/docs/stability.md

@@ -1,11 +1,14 @@
 # Stability and the first stable release
 
-Rehearsal leaves beta when the workflow it already promises is dependable. Stable
-`0.1.0` does not require every planned database, desktop interface, or paid feature.
+Rehearsal core **1.0.0 is published** on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines its
+compatibility promise and the verification policy for releases; it is not an
+unfinished launch checklist. Stable core does not require every planned database,
+editor interface, or paid feature.
 
 ## What becomes a compatibility promise
 
-Starting with `0.1.0`, Rehearsal treats these documented surfaces as public:
+Starting with `1.0.0`, Rehearsal treats these documented surfaces as public:
 
 - CLI command names, flags, JSON result fields, and exit categories in
   [CLI commands](commands.md);
@@ -45,21 +48,30 @@ release.
 
 ## Promotion sequence
 
-The sequence below records the initial beta-to-stable policy, not current release
-progress. Historical version names explain that policy; they do not claim a candidate
-is ready or restart an observation window by themselves.
-
-1. Ship beta.18 with only stability, release-safety, upgrade, and documentation work.
-2. Freeze broad feature development on the release branch.
-3. Publish a release candidate from protected `main` through the reviewed npm environment.
-4. Run the complete Rehearsal Test Lab gate twice from clean isolated workspaces.
-5. Perform one final package-only upgrade in a real consumer. The consumer must use the
-   published package rather than duplicate Rehearsal machinery.
-6. Keep the current candidate available for at least seven calendar days. Restart the
-   window if a blocking package change is required. The container-lifecycle correction
-   in `0.1.0-rc.2` restarts this observation window.
-7. Publish `0.1.0` only when no blocking issue remains and the accepted registry artifact
-   matches the tested artifact exactly.
+Promotion is evidence-based, not a calendar countdown. The initial seven-day RC
+wait was replaced after owner review; passing time alone cannot make a candidate
+ready. The sequence below is policy, not a claim that its checks have passed.
+
+1. Freeze broad feature development on the release branch.
+2. Select one immutable candidate from the reviewed release branch. A release candidate
+   may be published from protected `main` through the reviewed npm environment; another
+   prerelease is not required solely to verify the final stable tarball.
+3. Run the complete Rehearsal Test Lab gate twice from clean isolated workspaces.
+4. Perform one final package-only check in a real consumer using the exact frozen
+   stable tarball, not duplicate Rehearsal machinery. Preserve its reviewed settings
+   and persistent data; a package check does not require resetting its databases.
+5. Review reports and existing scheduled Test Lab results for unresolved blockers.
+   A blocking correction needs its affected acceptance repeated against the exact
+   corrected candidate. Reuse sufficient unchanged evidence with its original scope;
+   do not relabel old or unavailable manual checks as new results. No minimum number
+   of calendar days replaces these checks.
+6. Publish `1.0.0` only when no blocking issue remains and the exact tarball has passed
+   the required release checks and consumer acceptance. The protected GitHub npm
+   review is the single human authorization for its displayed exact version and
+   checksum; no separate chat approval or pasted phrase is required.
+7. Independently verify registry bytes, provenance, signatures and channels, then
+   confirm the published package in the real consumer. Promotion is complete only
+   when the published artifact matches the tested tarball and these checks pass.
 
 Test Lab is the primary verification system. A real consumer is the final compatibility
 check, not a replacement for package-owned coverage. Real Google or GitHub consent does
@@ -69,6 +81,23 @@ not need to run on every build unless authentication behavior changes.
 
 Beta and release-candidate versions publish under the `beta` tag. Before a stable
 release exists, `latest` follows that reviewed prerelease so the ordinary install command
-remains useful. Once stable `0.1.0` exists, `latest` stays on the stable line and `beta`
+remains useful. Once stable `1.0.0` exists, `latest` stays on the stable line and `beta`
 continues to identify the newest prerelease. Stable publication never rewrites the
 `beta` tag.
+
+## Upgrading from a 0.1 release candidate
+
+The first stable release preserves rc.10's database runtime and schema formats and
+corrects invalid-command diagnostics. A package upgrade
+does not require resetting a sandbox or replacing its reviewed configuration, key or
+baseline. Automatic compatible updates do not cross the 0.x-to-1.x version boundary;
+review the changelog and deliberately select the stable version:
+
+```bash
+npm install --save-dev --save-exact @rehearsal-db/core@1.0.0
+npx --no-install rehearsal --version
+npx --no-install rehearsal doctor
+```
+
+Use the project's existing package manager and dependency location. Review its lockfile
+and readiness output before the next sandbox operation; do not reset data just to update.

package/docs/tutorial.md

@@ -117,6 +117,6 @@ npm run test:fixture
 The PostgreSQL equivalent is `npm run test:fixture:postgresql`.
 
 The release workflow also runs `npm run test:fixture:onboarding` from the packed package.
-That check creates fresh Supabase and PostgreSQL consumers, verifies beta configuration
+That check creates fresh Supabase and PostgreSQL consumers, verifies reviewed configuration
 preservation, and exercises safe refusal and recovery for partial setup, occupied ports,
 malformed configuration, and missing credentials.