replume-cli 0.1.2 → 0.2.0

package/README.md

@@ -15,40 +15,16 @@ npm install -g replume-cli
 Cursor hooks are installed by `replume init --cursor`, or automatically when the project already has a `.cursor/` directory and you run `replume init`; otherwise Cursor agent steps will not be recorded in the ledger.
 Codex hooks are installed by `replume init --codex`, or automatically when the project already has a `.codex/` directory and you run `replume init`; finding `codex` on PATH alone does not install them. Otherwise Codex agent steps will not be recorded in the ledger. After installation, review and trust the hook definition with `/hooks` in Codex.
 
-Create a disposable project in a scratch directory. If Git asks for an identity when you commit, set `git config user.name "Your Name"` and `git config user.email "you@example.com"` in this disposable repository.
+Create a disposable project in a scratch directory, then:
 
 ```sh
-mkdir replume-first-run && cd replume-first-run && git init
-printf '{"name":"replume-first-run","version":"1.0.0","type":"module","scripts":{"test":"node --test"}}\n' > package.json
-mkdir src test && printf 'export const add = (a, b) => a - b;\n' > src/add.js
-cat > test/add.test.js <<'JS'
-import test from 'node:test';
-import assert from 'node:assert';
-import { add } from '../src/add.js';
-test('add returns the sum', () => assert.equal(add(1, 2), 3));
-JS
+npm install -g replume-cli
 replume init
-git add -A && git commit -m 'Set up first run'
-replume draft --task "Change src/add.js so add returns a+b instead of a-b"
-cat .replume/contract.yaml
-```
-
-The draft is a proposal, not policy. `allow` lists files the agent may change; check that it contains `src/add.js`. `test_command` should be `npm test`; it must run at least one test. `protect` lists the existing test file, so the agent may not weaken it. If `allow` is empty, use a task that names `src/add.js` or add it to the contract; `replume confirm` refuses an empty list unless you explicitly accept broad scope. Confirmation records a local task-start baseline. Commit the confirmed contract and generated `.replume/.gitignore` before asking the agent to work. The test fails at first because the function subtracts.
-
-```sh
-replume confirm
-git add .replume/contract.yaml .replume/.gitignore && git commit -m 'Confirm Replume task'
 ```
 
-Now give the agent the task in this folder, for example `claude -p "Change src/add.js so add returns a+b instead of a-b"` with Claude Code, and let it edit with the hooks installed by `replume init`. Review and commit its change, then verify and accept:
+Start your agent in that folder. That is the whole setup. `replume init` installs the hooks and writes `.replume/config` with `mode: auto`. The first thing you ask the agent is the task. You do not write a contract, confirm it, or make a setup commit.
 
-```sh
-git add src/add.js && git commit -m 'Make add return the sum'
-replume verify
-replume accept
-```
-
-Expected: the report starts with `Verdict: PASS`, `test_command` shows as DONE, and an `OBSERVED` line lists `src/add.js` as "checked by test_command and observed steps; no scenario". The last line states the actual isolation mode. `replume accept` then records the accepted change. A passing test establishes only what that test checks.
+`replume init --approve` writes `mode: approve` and keeps the older path: `replume draft --task`, review, `replume confirm`, then `replume accept` after verify.
 
 Scenarios are optional. Without one, verify can PASS when all of these hold: the contract's `test_command` runs at least one test and passes; nothing is FAILED, EXTRA or TAMPERING; and the ledger has an agent session for the task with an event naming each changed file. Otherwise the file is `NOT CHECKED` and the verdict is `INCOMPLETE`, with the reason: "agent steps not observed" (no session for this task in the ledger) or "change not seen by hooks" (no event names the file). A manual edit made without hooks therefore gives `INCOMPLETE`. Scenarios listed in `must_check` are required.
 
@@ -106,7 +82,13 @@ Cursor CLI: protected-file Write blocked in 2 CLI runs; out-of-scope Write warne
 
 Docker mode: when a local Docker daemon is running and the image (default `node:20-bookworm-slim`) is present, `replume verify` runs scenarios in a container with no network and a read-only copy of the commit; otherwise it uses the isolated working copy, which is not a security boundary. The container's no-network setting, read-only mount and timeout cleanup were tested in a real container on one Mac, not in CI. The isolated working copy runs commands with your machine access; use only trusted repositories.
 
-Commands: `replume init`, `replume task`, `replume draft`, `replume confirm`, `replume watch`, `replume verify`, `replume accept`, `replume report`, `replume usage`, `replume demo`, `replume install`, `replume hook`.
+### Optional RUNTIME check
+
+`replume verify --runtime` tries the committed program as a user would, then runs the same probe at the base commit. It detects a `package.json` binary or `start`/`dev` script, a Python entry point, a static `index.html`, or a Dockerfile `CMD`/`EXPOSE`. CLI projects get `--help` and an explicit literal command from the task when one is present. Servers get localhost requests to `/` and literal GET routes found in source; mutating and parameterized routes are not guessed. Web apps additionally need Playwright Chromium in the local runtime image: the browser opens `/`, records console errors and failed requests, and writes a screenshot under `.replume/evidence/`. Runtime findings appear in a separate `RUNTIME (like a user)` report section. A new failure relative to the base is FAIL. Missing tools or an inconclusive base are NOT CHECKED; a failure already present at the base remains visible and prevents a runtime PASS.
+
+This stage **only** runs in Docker, even if scenario verification used the worktree fallback. For a detected web app, Replume uses the [official Playwright image](https://playwright.dev/docs/docker) pinned to `v1.64.0-noble`. On first use it announces the roughly 3.5 GB local image download and builds a local image with `playwright@1.64.0`, because the official image contains browsers but [not the npm package](https://playwright.dev/docs/docker). Image preparation contacts the image/npm registries; the app and browser run together over localhost in a fresh container with `--network none`, a read-only repo mount, and no host Docker socket. CLI and HTTP probes do not pull Playwright. Use `--runtime-image <local-image>` to supply another image; Replume never pulls a custom image. A Dockerfile `CMD` is run against the selected image and clean commit, without a Dockerfile build. If anything cannot run, the report says NOT CHECKED. An automatic end-of-task integration can call `runRuntimeAtTaskEnd` from `src/sandbox/index.ts`; its `enabled: false` option and CLI `--no-runtime` disable the stage. Existing projects should add `evidence/` to `.replume/.gitignore` before running this option; new `replume init` projects include it. Docker is useful isolation, not a perfect security boundary.
+
+Commands: `replume init`, `replume task`, `replume draft`, `replume confirm`, `replume watch`, `replume verify`, `replume accept`, `replume report`, `replume usage`, `replume demo`, `replume judge-eval`, `replume install`, `replume hook`.
 
 ### Local task metrics (first slice)
 

package/THIRD-PARTY-NOTICES.md

@@ -58,3 +58,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## Optional web runtime: Microsoft Playwright — Apache-2.0
+
+When a web app is detected for the optional runtime check, Replume can pull the official `mcr.microsoft.com/playwright:v1.64.0-noble` image and install the matching `playwright@1.64.0` npm package into a local derived Docker image. Playwright is developed by Microsoft and licensed Apache-2.0 ([source and license](https://github.com/microsoft/playwright/blob/main/LICENSE)). Neither image nor package is bundled in the Replume npm archive. The image also contains Chromium and Ubuntu components with their own notices and licenses inside the upstream image.