replume-cli 0.1.1 → 0.2.0

package/README.md

@@ -13,41 +13,18 @@ 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.
 
@@ -71,7 +48,7 @@ console.log(`ADD=${add(1, 2)}`);
 JS
 ```
 
-Cursor project hooks are installed by `replume init` only when `.cursor/` already exists in the project or `--cursor` is supplied. The global install keeps `replume hook claude` and `replume hook cursor` available to hooks. A one-shot npx does not leave a persistent hook command. If npm returns 404, the package has not been published yet.
+Cursor project hooks are installed by `replume init` only when `.cursor/` already exists in the project or `--cursor` is supplied. Codex project hooks follow the same opt-in rule with `.codex/` or `--codex`. The global install keeps `replume hook claude`, `replume hook cursor`, and `replume hook codex` available to hooks. A one-shot npx does not leave a persistent hook command. If npm returns 404, the package has not been published yet.
 
 To remove Replume's project hooks, run `replume init --remove-cursor-hooks` for Cursor. For Claude Code, edit the project's `.claude/settings.json` and remove only the `replume hook claude` entries, keeping any other hooks. `replume init` does not currently have a Claude hook removal flag.
 
@@ -105,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

@@ -30,3 +30,35 @@ CLAIM, DAMAGES OR OTHER 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.
 ```
+
+## Test cases from hoophq/fence — MIT
+
+Some shell-command test cases in this project's tests (`test/core/shell-safety.test.ts` and `test/core/shell-safety-3.test.ts`, for example the recursive-delete commands and the expected block/allow outcomes) are taken from the test suite of hoophq/fence, https://github.com/hoophq/fence (`internal/analyzer/shell/shell_test.go`, commit 31623d48220f8b4abba67f4f9993884e45cd755c). The device-name pattern of `isBlockDevice` in `src/core/rules.ts` (which names count as raw disks) follows `blockDeviceRe` in fence's `internal/analyzer/shell/shell.go`, and the `$TMPDIR` handling follows the behavior its `TestTmpdirResolution` pins. No other fence code is included. The following is its upstream license and copyright notice:
+
+```text
+MIT License
+
+Copyright (c) 2026 hoop.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.