replume-cli 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+Replume Beta License
+
+Copyright (c) 2026 Replume Inc. All rights reserved.
+
+1. Grant. Replume Inc. ("Licensor") grants you a limited, non-exclusive, non-transferable, revocable license to install and use this software ("Software") for your own internal development work, free of charge, during the beta period.
+
+2. Restrictions. You may not: (a) copy, modify, or create derivative works of the Software, except as needed to run it; (b) sell, sublicense, rent, host, or otherwise distribute the Software or any part of it; (c) reverse engineer, decompile, or extract source code from the Software, except where applicable law forbids this restriction; (d) use the Software to build or operate a product or service that competes with the Software or with Replume; (e) remove or alter any copyright, license, or trademark notice.
+
+3. Ownership. The Software and all rights in it remain with the Licensor. No trademark rights are granted: "Replume", its logos, and its mascots remain the property of the Licensor.
+
+4. Your data. The Software runs on your machine. The Licensor does not receive your code or data through the Software unless you explicitly enable a feature that says so.
+
+5. Beta; changes. The Software is a beta release and may change or be withdrawn at any time. The Licensor may change these terms for future versions and may end this license by written notice or by withdrawing the Software.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. Replume checks and reports on the work of AI coding agents; it does not guarantee that any change is correct or safe. You remain responsible for reviewing your code.
+
+7. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR FOR LOSS OF DATA, PROFITS, OR BUSINESS, ARISING FROM USE OF THE SOFTWARE.
+
+8. Third-party components. The Software includes third-party open-source components under their own licenses, listed in the package.
+
+Contact: hello@replume.dev

package/README.md

@@ -1,3 +1,96 @@
-# replume-cli
+# Replume
 
-Reserved for Replume (https://replume.dev). Coming soon.
+Replume helps you inspect what a coding agent changed against the task you gave it. It proposes a task scope, records supported agent actions when hooks run, checks the committed change in an isolated environment, and reports what passed, what went beyond scope, and what remains unknown.
+
+Replume is free during beta under the proprietary Replume Beta License. See [LICENSE](LICENSE). Questions: hello@replume.dev.
+
+## Install and first run
+
+Requires Node 20 or newer and Git. Supported platforms: macOS and Linux. Windows is not supported yet. Docker is optional: with a running daemon and the local `node:20-bookworm-slim` image, scenarios run in a container without network access. Otherwise they run in an isolated working copy on your machine, so use a repository you trust. Install globally so the agent hooks can find `replume` later:
+
+```sh
+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.
+
+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.
+
+```sh
+mkdir replume-first-run && cd replume-first-run && git init
+printf '{"name":"replume-first-run","version":"1.0.0","type":"module"}\n' > package.json
+mkdir src && printf 'export const add = (a, b) => a - b;\n' > src/add.js
+replume init
+cat > .replume/scenarios/add.yaml <<'YAML'
+v: 1
+id: add
+description: add returns the sum
+declared_covers: ["src/add.js"]
+run: "node .replume/scenarios/add.mjs"
+timeout_sec: 10
+expect:
+  exit_code: 0
+  stdout_contains: ["ADD=3"]
+YAML
+cat > .replume/scenarios/add.mjs <<'JS'
+import { add } from '../../src/add.js';
+console.log(`ADD=${add(1, 2)}`);
+JS
+git add package.json src .replume/scenarios && 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`. `must_check` names required scenarios; check that it contains `add`. A scenario is a command and an expected result. Its `declared_covers` is a declaration, not measured coverage. 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 initial scenario should fail because the function subtracts.
+
+```sh
+replume confirm
+git add .replume/contract.yaml .replume/.gitignore && git commit -m 'Confirm Replume task'
+printf 'export const add = (a, b) => a + b;\n' > src/add.js
+git add src/add.js && git commit -m 'Make add return the sum'
+replume verify
+```
+
+Expected: the final report starts with `Verdict: PASS`, the scenario shows `DONE`, and the last line states the actual isolation mode. This sample uses a manual edit, so the report warns that agent actions were not observed. With an agent, give it the same task between `confirm` and `verify`, then review and commit its change. A passing scenario establishes only the stated `ADD=3` behavior.
+
+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.
+
+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.
+
+## Reading the report
+
+The first lines give `PASS`, `FAIL`, or `INCOMPLETE` and the reason. `DONE` means a scenario ran and met its stated expectations. `FAILED` means a run or required check failed. `EXTRA` names a changed path outside the allowed scope. `TAMPERING` names a suspicious test or configuration change. `NOT CHECKED` means no scenario declares coverage of the changed path. A green scenario does not prove the entire task correct.
+
+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.
+
+## 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.
+
+| Choice | Destination | Data sent |
+| --- | --- | --- |
+| 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 |
+| `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 |
+
+Text sent to OpenAI, GitHub comments and the HTTP judge receives best-effort pattern-based secret redaction first. It cannot guarantee removal of every secret; review the diff, task and agent messages before opting in. `replume install` writes a CI workflow with explicit `--legacy-judge --post-github-comment` flags; review that file before pushing it.
+
+## Agent evidence and isolation
+
+| Agent | Observe | Block | Steer |
+| --- | --- | --- | --- |
+| Cursor | CLI hook events observed; IDE not tested | protected Write blocked in 2 CLI runs; out-of-scope warn did not block | steering unverified |
+
+Cursor CLI: protected-file Write blocked in 2 CLI runs; out-of-scope Write warned but was not blocked in 2 CLI runs, and the agent did not quote the warning; IDE and live steering message delivery not tested.
+
+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`.
+
+### Local task metrics (first slice)
+
+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

@@ -0,0 +1,32 @@
+# Third-party notices
+
+This package uses the following production dependency. `commander` is installed as a separate npm dependency; `dist/cli.js` imports it rather than bundling its source.
+
+## commander 12.1.0 — MIT
+
+The following is its upstream license and copyright notice:
+
+```text
+(The MIT License)
+
+Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+
+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.
+```