@invariant.guru/cli 0.6.4 → 0.6.7

package/README.md

@@ -166,15 +166,20 @@ invariant plan:complete <session-id> --summary "Booking command + tests"
 Composes a *review session*: a second session whose job is to review the branch
 and write the result into `doc/review/<branch>.xml`.
 
-A review is a verdict **on** something, so it always names the session whose
-work is under review — `--session` is required. Without it the command refuses
-and lists the sessions it could have reviewed.
+A review says what it is about, and one of the two forms is required. Without
+either the command refuses and lists the sessions it could have reviewed —
+which is what stops a review ending up attached to nothing by accident.
 
 ```bash
 invariant review --session <session-id>   # review the work that session produced
-invariant review --session <id> --base origin/develop   # diff against something else
+invariant review --standalone             # review this branch on its own
+invariant review --standalone --base origin/develop     # diff against something else
 ```
 
+`--standalone` is for work no session of yours covers: pull a colleague's
+branch, review it, and get the same triage flow with nothing of your own behind
+it.
+
 Paste its execute line into a **new** agent conversation. That is the point: a
 fresh one has not seen the plan, so it reads the diff as evidence rather than as
 confirmation. It reviews exactly `git diff --cached $(git merge-base <base> HEAD)`
@@ -191,10 +196,23 @@ writes the comments you accepted into that same session's `## Plan` and moves it
 to `planned`. Executing it implements them. Nothing is ever committed or pushed —
 you stage and commit when you are happy.
 
+Or send them to the people who will read the merge request instead:
+
+```bash
+invariant review publish <branch> --dry-run   # what would go where
+invariant review publish <branch>
+```
+
+Each accepted comment becomes a **draft (pending)** comment on the branch's
+GitLab merge request, anchored on its file and line. Nothing is submitted for
+you and nobody is notified — you read the drafts in GitLab and press *Submit
+review*. The token is per project: see [docs/spec-review.md](docs/spec-review.md) §9.
+
 ### 7. `invariant ui` — see and manage your sessions
 
-Opens a local dashboard for this project's sessions: a board grouped by status,
-rendered markdown, a rich editor, review triage, and a command palette.
+Opens a local dashboard for this project: a session board grouped by status,
+rendered markdown, a rich editor, review triage, package management, and a
+command palette.
 
 ```bash
 invariant ui              # start on 4200 (or the next free port) and open a browser
@@ -399,6 +417,8 @@ invariant inspect nest-clean-architecture
 |--------|-------------|
 | `-d, --details` | Show all items including inactive ones |
 
+The **Packages** page in `invariant ui` is this same tree, with checkboxes.
+
 ### `invariant list`
 
 List installed or available packages.
@@ -453,11 +473,14 @@ waits for you to rule on every comment, and then implements the ones you
 accepted — one file, one conversation.
 
 ```bash
-invariant review --session <session-id>        # the session whose work is reviewed (required)
+invariant review --session <session-id>        # the session whose work is reviewed
+invariant review --standalone                  # a branch tied to no session
 invariant review --session <id> --base origin/develop   # diff against another ref
 invariant review list                          # every review document
 invariant review show <branch> --open          # what still needs a decision
 invariant review plan-changes <branch>         # accepted comments → the session's Plan
+invariant review publish <branch> --dry-run    # what would go where on the merge request
+invariant review publish <branch>              # accepted comments → draft MR comments
 ```
 
 | Subcommand | Description |
@@ -466,10 +489,12 @@ invariant review plan-changes <branch>         # accepted comments → the sessi
 | `list` | Every review document in the project (`--json`) |
 | `show <review>` | Print a review's comments (`--staged`, `--open`, `--json`) |
 | `plan-changes <review>` | Write the accepted comments into the session's `## Plan` |
+| `publish <review>` | Create draft GitLab merge-request comments (`--dry-run`, `--mr <iid>`) |
 
 | Option | Description |
 |--------|-------------|
-| `-s, --session <session>` | The plan session whose work is under review (**required**) |
+| `-s, --session <session>` | The plan session whose work is under review |
+| `--standalone` | Review this branch on its own, tied to no session |
 | `-b, --base <ref>` | Ref to diff against (default: `origin/main`, then `origin/master`, `main`, `master`) |
 
 Reviews land in `doc/review/<branch>.xml`, one file per branch, appended to on
@@ -478,6 +503,11 @@ partial triage silently drops the comments nobody looked at, so it is not
 allowed. Nothing here touches the index or a remote: the git commands this tool
 may run are allowlisted to read-only ones.
 
+`publish` has the same gate, and one of its own: it writes **draft notes and
+nothing else**. There is no call in this tool that submits a review, so the
+comments stay pending until a human presses *Submit review* in GitLab. Only
+staged comments are sent; a discarded one never leaves your machine.
+
 Configure it under `review` in `invariant.json`:
 
 ```jsonc
@@ -521,6 +551,28 @@ In the UI: `⌘K` opens the command palette, `⇧⌘V` toggles rendered preview
 editing, `N` starts a session, `?` lists every shortcut. On a review session,
 `j`/`k` move between comments and `s` / `d` / `e` stage, discard, or edit one.
 
+#### The Packages page
+
+The **Packages** section of the UI is a view over the package commands — it runs
+the same `invariant install`, `add`, `remove`, `uninstall` and `sync` you would
+type, in the directory the UI was started in, and shows you the command before it
+runs. It never writes `invariant.json` itself.
+
+- **The tree is `invariant inspect`.** Selecting a package lists everything it
+  ships, grouped by type, with the active items ticked.
+- **Toggling stages, it does not fire.** Tick and untick as many items as you
+  like; the bar at the bottom shows what will run, and **Apply** issues one
+  `remove` and one `add` for the whole batch. Optionally a `sync` after.
+- **Install** takes a GitHub repository (the default — `owner/repo`, or a pasted
+  URL, plus an optional ref) or a registry name, and previews the exact
+  `invariant install …` line including `--no-add` and `--sync`.
+- **Sync** runs from the top bar, with a **Check only** dry run that reports
+  drift the way CI does.
+- **A package the config declares but this checkout never installed** shows as
+  *not installed*, with a button that fetches it from its recorded source.
+
+A change made in a terminal shows up in an open page within a couple of seconds.
+
 To work on the UI itself: start a daemon (`invariant ui --no-open`), then run
 `yarn dev:ui` for Vite with hot reload against it — `INVARIANT_UI_PORT=<port>`
 when the daemon landed on something other than 4200.