@uge/payo 2.2.1 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -101,7 +101,28 @@ chat for the third time, Payo is for you.
101
101
 
102
102
  ## Quick Start
103
103
 
104
- No install required — run it in any project directory:
104
+ **macOS / Linux** (and Windows via Git Bash or WSL):
105
+
106
+ ```bash
107
+ curl -fsSL https://payo.uttamgelot.com/install.sh | sh
108
+ ```
109
+
110
+ **Windows** (PowerShell):
111
+
112
+ ```powershell
113
+ irm https://payo.uttamgelot.com/install.ps1 | iex
114
+ ```
115
+
116
+ Then run `payo` in any project directory.
117
+
118
+ The installer needs **no Node.js**. If you already have `bun` or Node >= 20.12
119
+ it installs the npm package (a much smaller download you can update with tools
120
+ you already know); otherwise it downloads a standalone binary. Set
121
+ `PAYO_INSTALL_METHOD=binary` to always get the binary. Re-running the installer
122
+ upgrades in place and cleans up the older copy.
123
+
124
+ <details>
125
+ <summary>Already have Node? You can skip the installer</summary>
105
126
 
106
127
  ```bash
107
128
  npx @uge/payo
@@ -109,15 +130,16 @@ npx @uge/payo
109
130
  bunx @uge/payo
110
131
  ```
111
132
 
112
- > The command you run after install is still `payo`. Install globally with
113
- > `npm i -g @uge/payo` (or `bun add -g @uge/payo`), then just run `payo`.
133
+ Or install it globally with `npm i -g @uge/payo` / `bun add -g @uge/payo`.
134
+
135
+ </details>
114
136
 
115
137
  Answer a short questionnaire about your stack, and Payo drops tailored AI
116
138
  guidance files straight into your repo.
117
139
 
118
140
  ## How to use — a walkthrough
119
141
 
120
- 1. **Run Payo from your project root.** `npx @uge/payo` — it writes into the
142
+ 1. **Run Payo from your project root.** `payo` — it writes into the
121
143
  current directory, so `cd` into the repo first.
122
144
  2. **Existing repo? It's auto-detected.** If Payo finds a manifest, it reads your
123
145
  stack and pre-fills the questionnaire, so most stack questions become a quick
@@ -231,7 +253,8 @@ present.
231
253
  Optionally, Payo adds a **change-audit** skill (`.agents/skills/change-audit/SKILL.md`):
232
254
  if you opt in, it asks when to run — before every commit or before pushing — and the
233
255
  agent uses it at that point to check your pending change against the relevant project
234
- skills and flag anything that conflicts.
256
+ skills and flag anything that conflicts. It reads the diff and reports — it never runs
257
+ your tests, linter or formatter, because your git hook already does.
235
258
 
236
259
  ### Guardrails enforced by hooks, not just prose
237
260
 
@@ -239,21 +262,30 @@ Skills are guidance the assistant _should_ follow — but an agent can skip pros
239
262
  when you enable a guardrail, Payo also writes the hook that makes it fire regardless:
240
263
 
241
264
  - **A git hook (mechanical, hard block).** When you turn on the gitleaks scan or the
242
- verify-before-commit/push step, Payo writes a **`lefthook.yml`** (or, if your repo
243
- already uses **husky**, **pre-commit**, or native `.git/hooks`, merges into _that_
244
- runner instead — never clobbering your setup). It runs `gitleaks` and your test
245
- command at the stage you chose and **blocks the commit/push on failure** — for every
246
- tool, and for a human typing `git`. Payo writes the config; you wire it up once with
247
- `lefthook install` (Payo tells you the command; it installs nothing itself).
248
- - **A native tool hook (soft confirm).** For **Claude, Cursor, and Copilot**, Payo
249
- writes a `PreToolUse` hook that pops a **confirm prompt** right when the agent runs
250
- `git commit` / `git push` (to run change-audit or confirm the push) or a destructive
251
- query (DB-safety). It stores no state and runs no model — it just makes the prompt
252
- appear so the guardrail isn't silently skipped. Tools without a soft-confirm hook
253
- (Codex, Antigravity, Windsurf) are covered by the git hook above.
265
+ verify-before-commit/push step, Payo writes a **`lefthook.yml`** running `gitleaks`,
266
+ your test command, your linter and a format check at the stage you chose, and
267
+ **blocking the commit/push on failure** — for every tool, and for a human typing
268
+ `git`. Payo writes the config; you wire it up once with `lefthook install` (Payo
269
+ tells you the command; it installs nothing itself).
270
+
271
+ **If your repo already has hooks** — **lefthook**, **husky**, **pre-commit**,
272
+ **simple-git-hooks** or native `.git/hooks` — Payo reads what each stage already
273
+ runs and, by default, **leaves your setup completely untouched**. Anything it
274
+ already covers is simply never added; for anything missing, Payo asks whether to
275
+ append it or leave the file alone, and leaving it alone is the recommended answer.
276
+ - **A native tool hook.** For **Claude, Cursor, and Copilot**, Payo writes a
277
+ `PreToolUse` hook that fires when the agent runs `git commit` / `git push` or a
278
+ destructive query. Confirm-push and DB-safety raise a **confirm prompt for you**.
279
+ Change-audit instead **denies the command once** with an instruction back to the
280
+ agent — a confirm prompt would just be approved and the audit skipped — and the
281
+ retry for that same change goes through. It stores nothing outside `.git/` and runs
282
+ no model. Tools without a pre-tool hook (Codex, Antigravity, Windsurf) are covered
283
+ by the git hook above.
254
284
 
255
285
  Both are **idempotent** — re-running Payo never duplicates a hook — and are written
256
- only for the guardrails you actually enabled.
286
+ only for the guardrails you actually enabled. Whatever a hook runs, the generated
287
+ skills tell the agent **not** to run it as well, so the same checks never execute
288
+ twice; anything no hook covers stays an explicit instruction to the agent.
257
289
 
258
290
  The question Payo asks — _"Which agent CLI should Payo use to generate content?"_ —
259
291
  picks only **which installed CLI authors the content**. The output above works with
@@ -355,13 +387,38 @@ Have a stack you want supported or an idea to make the flow better?
355
387
 
356
388
  ## Requirements
357
389
 
358
- **To run Payo:** [Node.js](https://nodejs.org) **>= 20.12**. That's it — `npx @uge/payo`
359
- runs the published, Node-targeted binary, so **you do not need Bun to use Payo.**
360
- If you prefer Bun, `bunx @uge/payo` works too.
390
+ **To run Payo:** nothing. The standalone binary from
391
+ [the installer](#quick-start) is self-contained — no Node, no Bun. `git` is used
392
+ if present (to detect your repo) but is not required.
393
+
394
+ **Via npm instead:** [Node.js](https://nodejs.org) **>= 20.12** for
395
+ `npx @uge/payo`. Bun is optional — `bunx @uge/payo` works, but is never
396
+ required to *use* Payo.
397
+
398
+ **Supported by the binary:** macOS (Apple Silicon and Intel), Linux
399
+ (x64 and arm64, glibc) and Windows x64. On Alpine/musl or Windows on ARM the
400
+ installer tells you to use npm instead.
361
401
 
362
402
  **To develop Payo:** [Bun](https://bun.sh) **>= 1.1.0** (the project builds, tests,
363
403
  and runs from source with Bun — see [Run locally](#run-locally)).
364
404
 
405
+ ## Uninstalling
406
+
407
+ Payo writes nothing outside the project you run it in, so removing the CLI is
408
+ all there is to it:
409
+
410
+ ```bash
411
+ rm ~/.local/bin/payo # standalone binary
412
+ npm rm -g @uge/payo # npm install
413
+ bun remove -g @uge/payo # bun install
414
+ ```
415
+
416
+ The installer prints which of the three it used.
417
+
418
+ > **macOS:** binaries fetched by the installer run fine. If you instead
419
+ > download an archive from the Releases page in a browser, macOS quarantines
420
+ > it — clear that with `xattr -d com.apple.quarantine payo`.
421
+
365
422
  ## Run locally
366
423
 
367
424
  Hacking on Payo or running it from source: