replume-cli 0.1.2 → 0.2.1

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.
 
@@ -82,6 +58,8 @@ The first lines give `PASS`, `FAIL`, or `INCOMPLETE` and the reason. `DONE` mean
 
 Evidence labels distinguish what this verify run computed (`Verified in this environment`), what came from editable local files (`Observed`), optional model judgment (`Assumed`), and what was not checked (`Unknown`). The local event ledger records only actions that reached installed hooks. A manual commit can pass its checks while agent steps were not observed; the report calls that out. Use `replume demo` for a built-in recorded replay of rule decisions; it does not show live steering.
 
+In a second terminal inside the project, run `replume watch` while the agent works. It prints one line per recorded step, including blocks and their reasons, Stop retries, test results, and the final saved-report verdict. Use `replume watch --once` to read the ledger and exit. Colors appear in a terminal unless `NO_COLOR` is set; no events means the project hooks may not have run.
+
 ## What stays on your machine / what can leave it
 
 The default Replume flow (`init`, `draft`, `confirm`, hooks, `verify`) makes no Replume-managed outbound request. Contract, events, report and scenario results stay local. Commands in your own repository, including test/scenario commands, can use the network themselves; inspect them before running. Docker scenario mode disables container networking; the isolated working copy does not.
@@ -91,6 +69,7 @@ The default Replume flow (`init`, `draft`, `confirm`, hooks, `verify`) makes no
 | Default flow | None from Replume | Nothing sent by Replume |
 | `verify --legacy-judge` | OpenAI, `api.openai.com` | Full Git diff, task text and agent action summary; also a GitHub check-run with commit SHA and verdict to `api.github.com` |
 | `verify --legacy-judge --post-github-comment` | GitHub PR, `api.github.com` | Task text and model reasoning in a PR comment; it can be public if the repository is public |
+| `github comment --repo OWNER/REPO --pr N` | GitHub PR via logged-in `gh` or `api.github.com` with `GITHUB_TOKEN` | Previewed, redacted, allow-listed sections from one saved session report (or a saved verify JSON supplied with `--report`); task text and changed paths may be included |
 | `REPLUME_JUDGE=shadow` or `on`, `REPLUME_JUDGE_PROVIDER=http`, `REPLUME_JUDGE_URL=https://…` | The configured HTTPS host | Task text, recent agent action summaries and proposed action or final message; `REPLUME_JUDGE_ALLOW_INSECURE_HTTP=1` separately permits HTTP |
 | `verify --check-registry` | `registry.npmjs.org` or `pypi.org` | Package names added in dependency changes; no source file contents from this lookup |
 
@@ -106,10 +85,20 @@ 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 share`, `replume github`, `replume memory`, `replume usage`, `replume demo`, `replume judge-eval`, `replume install`, `replume hook`.
 
 ### Local task metrics (first slice)
 
+`replume share [report]` uploads one session report to replume.dev and prints an unlisted link (`replume.dev/r/<id>`). It never runs on its own. It first prints exactly what will be sent: the verdict, what was asked and done, what changed, where Replume steered, tests, time and tokens, and the runtime and not-checked notes. Secrets are redacted, absolute paths become `<path>`, and the full verify output, assumptions, model-judge evidence and your code are not sent; `--no-diff` also drops diff hunks and per-file line counts. It asks before uploading (`--yes` skips the question, `--dry-run` only previews). The delete token stays in `.replume/shares.jsonl` (git-ignored); `replume share --delete <id>` removes the report.
+
+`replume github comment --repo OWNER/REPO --pr N --dry-run` previews a PR comment made from the latest saved session report, using the same redacted sections as `share`. Run it without `--dry-run` to confirm interactively, or add `--yes` in CI. `--report PATH` selects a report; a saved verify JSON produces a shorter comment labeled “from saved file, not re-verified.” Nothing is posted during `verify` by default.
+
 Replume reads Claude Code token counters from its local transcript at Stop and SessionEnd. To add counters from a local Codex rollout or Cursor CLI success JSON, run `replume usage import-codex --rollout <path> --task-id <id> --session-id <id>` or `replume usage import-cursor --result <path> --task-id <id> --session-id <id>`. These commands store only counts and task/session IDs in `.replume/usage.jsonl`; they make no API call. Uncaptured usage remains Unknown. Active agent time and human waiting time remain Unknown.
 
 After `replume verify` passes, run `replume accept` to explicitly accept the current commit. It runs verification again and records the acceptance locally. Run `replume verify` afterward to refresh the saved report's accepted-change metrics. Any dollar figure is labelled **estimated API-equivalent** for captured tokens using a dated price table; it is not a bill or a savings claim. Before acceptance, it remains Unknown.

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.