@patchgg/cli 0.1.3 → 0.3.0

package/README.md

@@ -23,8 +23,7 @@ pch agent install              # gives your coding agent Patch's tools
 pch search "grappling hook"    # something to start from: then pch remix or pch clone it, and change it
 pch new your-name/my-game      # a repo with a patch.json; or pch init in a folder you have
 pch validate
-pch publish                    # a browser game or mod stops here as a private draft
-pch test start your-name/my-game@0.1.0    # played on your PC in Patch Desktop, which it takes to go live
+pch publish                    # upload, test on your PC, your review of the footage, then live
 pch media add your-name/my-game cover.png --kind cover
 pch project update your-name/my-game --summary "One line about it"
 ```
@@ -337,37 +336,28 @@ It's advice. Nothing reads its result, nothing stops you publishing, and it does
 
 ### From upload to live
 
-A release stays a private draft until you say it's ready. `pch publish` uploads it as a private draft, and a browser game or a mod Patch installs (a recipe's `mode` of `browser`, `installed` or `standalone`) stops there until it has passed a test on your PC. Patch Desktop plays it as players get it and records it, then someone looks at the footage, and you decide when it goes out:
+`pch publish` takes a release from upload to live, saying where it is in one line: **Uploading**, **Testing on your PC**, **In review**, **Live**. Running it is your yes. A browser game or a mod Patch installs (a recipe's `mode` of `browser`, `installed` or `standalone`) is played on your PC by Patch Desktop and recorded, and the flow stops once for its review: look at the footage it saved, then send the review it prints, which sends it on to Patch's review and follows it until it's live.
 
 ```sh
-pch publish                                     # a private draft, and says what's next
-pch test start patch/lantern@0.1.0              # waits for you to press Start in Patch Desktop
-pch test view patch/lantern@0.1.0 --wait        # follows it until it's been played
-pch test footage patch/lantern@0.1.0            # saves its pictures, and prints where
-pch test review patch/lantern@0.1.0 --verdict pass --plays yes --harmful no \
-  --summary "It starts and plays" \
-  --moment "1 00:04 the title screen draws" --moment "1 00:10 a round of play"
-pch release submit patch/lantern@0.1.0          # your yes: Patch reviews it, and it goes live
+pch publish                                     # upload, test on your PC, save the footage
+pch publish patch/lantern@0.1.0 --review pass --summary "It starts and plays" --moment "1 00:04 the title screen draws" --moment "1 00:10 a round of play"
 ```
 
-- Patch's review after `pch release submit` can take several minutes, and nothing tells you when it's over: `pch status` says, and `--wait 50` holds its answer until something changes, for up to that many seconds.
-- Only your team can find a release published on the `private` channel, and they play it signed in. It isn't locked: anyone who has a browser game's or a block demo's game address could load it, so don't put anything secret in it. The same goes for one in a private repo, though its source stays private. A mod's files aren't on the game host. Once a project that isn't private has a public release, only a public release changes what's played, so a newer private one can't be played yet. `pch status` and `pch project view` say which it is, and where. `pch release promote` puts it out for everyone.
-- A passed test shows it starts and runs, not that it plays well. So before a game's first public release, `pch test review`, `pch test view` and `pch status` ask you to play it yourself, as `ask` with `--json`, in words for an agent to pass on. `pch guide` says how. Asking is all they do: nothing checks you played, and a later public release, a private one or a block's demo isn't asked.
-- Nothing starts a test but `pch test start`, and nothing publishes but `pch release submit`. Each command says what comes next, as `next` with `--json`, and `pch status` does too.
-- Patch Desktop has to be open and signed in on your PC. A test started from pch waits there until you press Start or Not now: only one asked for from a chat in Patch Desktop starts by itself. If it isn't open, the test says so, as `ask` with `--json`, in words for an agent to pass on.
-- `--wait` with no number follows it to the end for someone at a terminal, and for 100 seconds with nobody there, since an agent's shell commands get about 2 minutes. If it isn't over by then, it says so and exits 0: run the next command to keep following.
-- With a test open, `pch test start` follows that one, since starting another would cancel it. `pch test cancel` first to start over.
-- A review needs a verdict, whether it plays, whether it does anything harmful, a summary, and at least two moments you saw, with at least one from each run: `"<run> <mm:ss> <what you saw>"`, with the time on a frame.
-- A second `pch publish` of a version that's past draft submits nothing: a release never changes, so it says how to finish that one, or to move the version on.
-- A mod players install some other way (`workshop` or `manual`) has no test, so `pch publish` submits it from its draft. A staff key publishes directly.
-
-| Exit code | `pch test`                                                                                              |
-| --------- | ------------------------------------------------------------------------------------------------------- |
-| 0         | Passed, still going, or waiting for its review: `state` says which, and `next` what to run              |
-| 1         | Couldn't run, or was cancelled: `outcome` says why, and it needs starting again                         |
-| 3         | Failed, on a check on the PC or in its review. A version that failed can't be tested or published again |
-
-`pch publish` and `pch release promote` exit 0 when they leave a private draft that needs its test, since that's the usual first stop: with `--json`, `release.status` is `draft` and `next` says what to run. So a 0 from them doesn't mean published, as a release in review doesn't either. `pch release submit` exits 5 with `test_first` or `test_not_passed` until it has passed, and `pch publish` with `test_not_passed` for a draft whose test hasn't. Both exit 3 with `files_failed` when the file checks stop it, as `pch test start` does. Each error has what to run in `details.next`.
+- A review needs `pass` or `fail`, a summary, and at least two moments you saw, with at least one from each run: `"<run> <mm:ss> <what you saw>"`, with the time on a frame. Add `--harmful` if it does anything harmful, which fails it.
+- Patch Desktop has to be open and signed in on your PC. A test started from pch asks you to press Start wherever you are in Patch Desktop, unless you've turned on "Start my agents' tests by themselves"; only one asked for from a chat in Patch Desktop starts by itself either way. What only you can do is printed as it comes up, as `needs_person` with `--json`.
+- At a terminal it follows the release until it stops; with nobody there, for 100 seconds, since an agent's shell commands get about 2 minutes. If it isn't over by then, it says so and exits 0: run `pch publish <owner/slug@version>`, as it prints, to keep following.
+- After a test that couldn't run, `pch publish <owner/slug@version> --test-again` starts another.
+- `pch test start` tries a build on your PC without publishing it, and `pch test view`, `pch test footage` and `pch test review` look at it. `pch publish <owner/slug@version>` carries it on from there once you want it out.
+- Who can see a release is said once a project, the first time it comes up, and always in `--json` as `who_can_see`. Only your team can find a release on the `private` channel, and they play it signed in. It isn't locked: anyone who has a browser game's or a block demo's game address could load it, so don't put anything secret in it.
+- A passed test shows it starts and runs, not that it plays well, so play a game yourself before its first public release. `pch guide` says how.
+- A second `pch publish` of a version that's past draft uploads nothing: a release never changes, so it says how to finish that one, or to move the version on.
+- A mod players install some other way (`workshop` or `manual`) has no test, so it goes straight to Patch's review. A staff key publishes directly.
+
+| Exit code | `pch publish`                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------- |
+| 0         | Live, waiting for your review of the footage, ready for a press in a chat, or still going: `stage` says which |
+| 1         | Its test couldn't run, or its repo is private: `code` and the message say what to do                          |
+| 3         | It failed its test or its checks. A version that failed can't be tested or published again                    |
 
 ### Blocks
 
@@ -528,7 +518,7 @@ CI runs both on Windows, macOS and Linux. pch knows it's the executable through
 
 ### Releasing
 
-**Release with the button:** [Actions, Release pch](https://github.com/patch-gg/pch/actions/workflows/release.yml), **Run workflow** on `main`, then pick `patch` (fixes), `minor` (new things) or `major` (breaking). It tags `main` with the next version and releases it to npm and the one-line installers together. Patch-gg/patch's `product/design/cli.md`, Releasing pch, says what each step does and what to do when one fails.
+**Release with the button:** [Actions, Release pch](https://github.com/patch-gg/pch/actions/workflows/release.yml), **Run workflow** on `main`, then pick `patch` (fixes), `minor` (new things) or `major` (breaking). It tags `main` with the next version and releases it to npm and the one-line installers together, then opens Patch Desktop's PR to ship it. Patch-gg/patch's `product/design/cli.md`, Releasing pch, says what each step does and what to do when one fails.
 
 `package.json` stays `"private": true`, so npm and pnpm refuse to publish pch from a checkout, and a test keeps it that way. [`publish.yml`](.github/workflows/publish.yml) is the only way out. It runs on a `v<version>` tag on `main`, which is the version, and stops unless production has repos. It publishes with npm's trusted publishing, so no npm key is kept anywhere: npm takes `@patchgg/cli` only from this repo's `publish.yml`, as the package's settings on npmjs.com say. One build per version: its `pack` job runs every check, builds once, takes `private` out of its own copy, packs, tries the tarball installed, and keeps it as the run's artifact `npm-package`. Every other way of installing pch is made from that tarball's `dist/`, never rebuilt from source. Then, in order:
 - `executable` makes the six executables, each on its own runner (Linux, macOS and Windows, x64 and arm64), and runs the smoke test against each, and on Linux the tests too.
@@ -537,6 +527,7 @@ CI runs both on Windows, macOS and Linux. pch knows it's the executable through
 - `try-installers` installs it from staging.patch.gg on a clean Debian container, Linux on Arm, both kinds of Mac and both kinds of Windows, and checks it runs, says its version, and on Windows, its signature.
 - `publish` sends the tarball to npm, with provenance once this repo is public.
 - `production` puts the same files on cdn.patch.gg and moves production's `latest.json`.
+- `desktop` opens the PR in patch-gg/patch that ships the version in Patch Desktop (`feat(desktop): ship pch <version> from npm` for a minor or major, `fix(desktop)` for a patch, as Desktop's version comes from its PR titles). It signs in as the `patch-gg-releases` GitHub App, so patch's CI runs on the PR. The app is installed on patch-gg/patch alone, and its client ID and key are in the `production` environment. A patch or minor release merges itself once that CI passes, which publishes a staging build of Patch Desktop. A major waits for a person to merge it. The release is out before this job starts, so if it fails, re-run it alone.
 
 Nothing reaches npm or production unless every platform got through. A version's files never change: a version that's on the CDN already with other files stops the release. `latest.json` only moves forward, and it's the one version check: the installers read it, and so do `pch update` and the notice. The `staging` and `production` environments take `v*` tags only, and hold R2 keys for their own public bucket alone (`infra/scripts/create-pch-release-keys.mjs` in patch-gg/patch makes them).
 To release what's on `main`: