@pushary/agent-hooks 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+## 0.61.0
+
+The largest release since the CLI shipped. Setup no longer asks you to paste an
+API key, the key is checked against the server before anything is written to your
+machine, and commands exit with codes that mean something.
+
+### Read this first: exit codes changed
+
+Commands that used to print a failure and exit `0` now exit non-zero. If you run
+any of these in CI or chained behind `&&`, this is the part that affects you.
+
+| Command | Was | Now |
+| --- | --- | --- |
+| any unknown command or `pushary` typo | `0`, printed help | `2` |
+| `doctor` with a failing check | `0` | `5` |
+| `setup` with a revoked key | `0` | `4` |
+| `setup` with an expired or locked plan | `0` | `5` |
+| `mode`, `wait` with a rejected key | `0` | non-zero |
+| `status` with no key configured | did not exist | `3` |
+
+The full ladder: `0` ok, `1` failed, `2` usage, `3` not configured,
+`4` unauthenticated, `5` problems found, `6` no device, `7` input required,
+`8` unreachable, `130` interrupted.
+
+`pushary doctor && deploy` used to succeed against a machine doctor had just
+declared broken. That is the change worth knowing about.
+
+### Sign in instead of pasting a key
+
+`pushary setup` opens a browser, shows you a code, and receives the key sealed to
+a keypair generated on your machine. The key is never pasted, never shown in a
+terminal, and never transits in a form the server could read.
+
+- `pushary login` and `pushary logout` as standalone commands
+- Pasting a key still works, as a fallback and via `--key`
+- `--key-stdin` reads the key from stdin, so it stays out of your shell history
+  and out of the process list
+
+### New commands
+
+- `pushary status` reports what this machine is connected to, with `--json`
+- `pushary login`, `pushary logout`, `pushary connect`
+
+### Setup
+
+- The key is verified against the server before a single file is written. A
+  revoked key or a locked plan stops the run instead of producing a config that
+  looks finished and never delivers.
+- `--yes` runs setup with no prompts, for CI and images
+- `--agents claude_code,codex,...` picks agents without asking
+- `--dry-run` prints what it would do and touches nothing
+- Agent detection is real, so an agent you do not have is reported as skipped
+  rather than counted as configured
+- Ctrl-C in a trailing prompt no longer reports the whole run as failed
+- A stale `PUSHARY_API_KEY` export in your shell profile is now replaced rather
+  than skipped. It used to win forever over a newly rotated key.
+
+### Delivery is proved to your phone, not just to the workspace
+
+Setup and doctor now check that an approval reaches **you**, not merely that
+somebody in the workspace has a device. On a shared site where the only reachable
+channel cannot be attributed to you, that is said plainly rather than reported as
+success.
+
+### Diagnostics
+
+- `pushary doctor --json` for one machine-readable envelope
+- `pushary doctor --roundtrip` sends a real approval and waits for the tap. It
+  works without a TTY, where the old confirm prompt could not run at all.
+- `pushary doctor --no-push` for a check that stays silent
+- doctor reads the same key the hooks will actually use, honoring
+  `PUSHARY_CONFIG_FILE`, and reports a Claude or Cursor config holding a
+  different key
+
+### Correctness
+
+- `--help` and `--version` print and exit instead of running the command.
+  `pushary daemon --help` used to start a daemon; `pushary hook --help` used to
+  block forever on stdin.
+- Unknown flags are rejected on the commands that parse them, instead of being
+  coerced into a plausible wrong value. `--connect` with an unrecognized mode used
+  to silently mean `web`.
+- Every file this CLI writes is written atomically, so an interrupted setup can
+  no longer truncate a large `~/.claude.json`
+- An unparseable agent config is left alone instead of being overwritten
+- Files holding your key are created `0600`
+- `CODEX_HOME` is honored when locating `config.toml`
+- Hermes setup works on Windows
+- The Cursor plugin is staged and verified before the old one is replaced
+- `installGlobally` pins the exact running version instead of drifting to latest
+- `pushary clean` removes only the export line it wrote, not every line in your
+  shell profile that mentions the key variable
+- Requests honor `HTTP_PROXY` and `HTTPS_PROXY`
+- Color honors `NO_COLOR` and `FORCE_COLOR`, and turns itself off when output is
+  not a terminal
+- `--json` output is machine-readable on stdout, with human text on stderr, so a
+  pipe never receives a spinner
+
+### Pairing
+
+The pairing QR now points at a real web page, so scanning it on a phone without
+the app installed lands on install instructions for that platform instead of a
+dead custom-scheme link.
+
+### Known gaps
+
+- `status`, `clean`, `mode`, `wait`, `stats`, `suggestions` and `upgrade` still
+  ignore an unknown flag rather than exiting `2`. Unchanged from 0.60.0.
+- `pushary upgrade` reapplies Claude settings only. Other agents need `setup`.
+- Codex hook trust still uses a fixed version ceiling, so a newer Codex is sent
+  to the manual `/hooks` step.

package/README.md

@@ -58,17 +58,59 @@ Any other MCP client can use notify and ask by pointing at the Pushary MCP endpo
 
 ## Commands
 
+<!-- Managed: every command below is declared in src/cli/commands.ts, and a test
+     asserts this list matches it. Do not edit one without the other. -->
+
 ```
-setup    Configure Claude Code, Codex, Gemini CLI, Hermes, or Cursor with Pushary
-doctor   Verify your Pushary installation is working
-clean    Remove all Pushary configuration
-mode     Switch approval mode (push_only, push_first, terminal_only, notify_only)
-wait     Show or set the "wait for your phone" ladder (pushary wait 45)
-stats    Show the approval moments your agents hit while not connected
-upgrade  Update the globally installed hooks to the latest version
-hook     Run as a PreToolUse hook (reads stdin, writes stdout)
+setup        Configure Claude Code, Codex, Gemini CLI, Hermes, or Cursor with Pushary
+claude       Run Claude Code through Pushary, reachable from your phone even when idle
+daemon       Keep this machine reachable so your phone can START a new session
+status       One screen: which key is in force, whether the server accepts it, what can receive an approval
+login        Sign in from this terminal, no key to copy (--with-token to pipe one in)
+logout       Remove the key this machine stores, and say what it does not remove
+connect      Connect a phone without re-running setup (--app for the Pushary app)
+doctor       Verify your Pushary installation is working
+clean        Remove all Pushary configuration (--yes for non-interactive)
+mode         Switch approval mode (push_only, push_first, terminal_only)
+wait         Show or set the "wait for your phone" ladder (pushary wait 45)
+stats        Show the approval moments your agents hit while not connected
+suggestions  List rules mined from your own approvals
+upgrade      Update the globally installed hooks to the latest version
+hook         Run as a PreToolUse hook (reads stdin, writes stdout)
 ```
 
+Run `pushary <command> --help` for one command's options.
+
+### Non-interactive setup
+
+`setup` asks which agents you use, so a run with no terminal on stdin needs to be
+told instead. `--agents` or `--yes` does that; without either, setup takes the
+defaults rather than waiting for a keypress that can never arrive.
+
+```bash
+# Everything detected on this machine, no prompts
+npx @pushary/agent-hooks@latest setup --key-stdin --yes --skip-phone < key.txt
+
+# Named agents only
+npx @pushary/agent-hooks@latest setup --agents claude_code,codex --yes --skip-phone
+
+# Store the key and configure nothing
+npx @pushary/agent-hooks@latest setup --agents none --yes
+
+# Show what would be written, change nothing
+npx @pushary/agent-hooks@latest setup --agents auto --dry-run
+
+# One machine-readable object on stdout; every human line goes to stderr
+npx @pushary/agent-hooks@latest setup --agents auto --yes --json
+```
+
+Prefer `--key-stdin` over `--key` in CI: `--key` puts the secret in argv, where
+any other user on the box can read it out of `ps`.
+
+Exit codes: `0` done, `2` bad usage, `3` no key resolvable, `4` the server
+rejected the key, `5` finished with problems (an inactive plan, or an installer
+that failed), `130` cancelled with Ctrl-C.
+
 Examples:
 
 ```bash
@@ -106,7 +148,8 @@ If a policy cannot be fetched or a hook errors, the decision falls back to the a
 - Website: [pushary.com](https://pushary.com/?from=npm)
 - Docs: [pushary.com/docs](https://pushary.com/docs?from=npm)
 - Sign up: [pushary.com/sign-up](https://pushary.com/sign-up?from=npm)
-- Issues: [github.com/pushary/pushary/issues](https://github.com/pushary/pushary/issues)
+- Troubleshooting: [pushary.com/docs/agents/reference/troubleshooting](https://pushary.com/docs/agents/reference/troubleshooting?from=npm)
+- Support and bug reports: [Discord](https://discord.gg/9v3VvUByrr) or [business@pushary.com](mailto:business@pushary.com)
 
 ## License
 

package/dist/bin/pushary-claude.js

@@ -17,18 +17,18 @@ import {
   reportEvent,
   resolvePolicy,
   waitForAnswer
-} from "../chunk-WNRYRN2R.js";
+} from "../chunk-VFBYRR2N.js";
 import {
   getMachineId
 } from "../chunk-RN3NOEJF.js";
-import "../chunk-DWED7BS3.js";
+import "../chunk-HNTKTK5B.js";
 import {
   redactSecrets
 } from "../chunk-DQAN3JQP.js";
 import {
   getApiKey,
   getBaseUrl
-} from "../chunk-NKXSILEW.js";
+} from "../chunk-2UMNXADU.js";
 
 // src/wrapper/claudeBinary.ts
 import { statSync } from "fs";

package/dist/bin/pushary-clean.js

@@ -1,28 +1,33 @@
 #!/usr/bin/env node
 import {
-  removeClaudeAlias
-} from "../chunk-BC3VCZ3E.js";
+  removeClaudeMcpServers,
+  removePusharySettings
+} from "../chunk-CAJZAFVS.js";
 import {
   removeCodexHooks,
   removeGeminiSettings,
   removeInstructionBlock
-} from "../chunk-BQLCELYC.js";
+} from "../chunk-S4TFBJ5O.js";
+import {
+  removeClaudeAlias
+} from "../chunk-BC3VCZ3E.js";
 import {
   execNpm
-} from "../chunk-J7JWI3KU.js";
+} from "../chunk-MUEW424A.js";
 import {
-  removeClaudeMcpServers,
-  removePusharySettings
-} from "../chunk-CAJZAFVS.js";
+  exitOnHelpFlag
+} from "../chunk-HUJQSP4F.js";
+import "../chunk-SML23YOT.js";
 import "../chunk-DQAN3JQP.js";
 
 // bin/pushary-clean.ts
-import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, copyFileSync, rmSync, readdirSync } from "fs";
 import { join } from "path";
 import { homedir, tmpdir } from "os";
 import { execSync } from "child_process";
 import { confirm } from "@inquirer/prompts";
 import { parse as parseTOML, stringify as stringifyTOML } from "smol-toml";
+exitOnHelpFlag("clean");
 var dim = (s) => `\x1B[2m${s}\x1B[0m`;
 var bold = (s) => `\x1B[1m${s}\x1B[0m`;
 var green = (s) => `\x1B[32m${s}\x1B[0m`;
@@ -236,9 +241,19 @@ var main = async () => {
     try {
       const content = readFileSync(shellFile, "utf-8");
       if (content.includes("PUSHARY_API_KEY")) {
-        const cleaned = content.split("\n").filter((l) => !l.includes("PUSHARY_API_KEY")).join("\n");
-        writeFileSync(shellFile, cleaned, "utf-8");
-        console.log(`  ${check} ${shellFile.split("/").pop()} ${dim("(removed API key)")}`);
+        const isOurExport = (line) => /^\s*export\s+PUSHARY_API_KEY=['"]?pk_[A-Za-z0-9]+\.[A-Za-z0-9]+['"]?\s*$/.test(line);
+        const lines = content.split("\n");
+        const declined = lines.filter((l) => l.includes("PUSHARY_API_KEY") && !isOurExport(l));
+        const cleaned = lines.filter((l) => !isOurExport(l)).join("\n");
+        if (cleaned !== content) {
+          const backup = `${shellFile}.pushary-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
+          copyFileSync(shellFile, backup);
+          writeFileSync(shellFile, cleaned, "utf-8");
+          console.log(`  ${check} ${shellFile.split("/").pop()} ${dim(`(removed the export, backup at ${backup})`)}`);
+        }
+        for (const line of declined) {
+          console.log(`  ${skip} ${shellFile.split("/").pop()} ${dim(`left a line referencing PUSHARY_API_KEY: ${line.trim()}`)}`);
+        }
       }
     } catch {
     }

package/dist/bin/pushary-codex-hook.js

@@ -31,7 +31,7 @@ import {
   toCodexWire,
   toPolicyLookup,
   waitForAnswer
-} from "../chunk-WNRYRN2R.js";
+} from "../chunk-VFBYRR2N.js";
 import {
   getMachineId
 } from "../chunk-RN3NOEJF.js";
@@ -39,7 +39,7 @@ import {
   isGatingMoment,
   recordKeylessMoment
 } from "../chunk-WLGEY4UX.js";
-import "../chunk-DWED7BS3.js";
+import "../chunk-HNTKTK5B.js";
 import {
   DECISION_LINE_MAX,
   effectiveWaitSeconds,
@@ -48,7 +48,7 @@ import {
 } from "../chunk-DQAN3JQP.js";
 import {
   getApiKey
-} from "../chunk-NKXSILEW.js";
+} from "../chunk-2UMNXADU.js";
 
 // bin/pushary-codex-hook.ts
 import { basename, join } from "path";

package/dist/bin/pushary-codex.js

@@ -3,15 +3,15 @@ import {
   askUser,
   reportEvent,
   waitForAnswer
-} from "../chunk-WNRYRN2R.js";
+} from "../chunk-VFBYRR2N.js";
 import {
   getMachineId
 } from "../chunk-RN3NOEJF.js";
-import "../chunk-DWED7BS3.js";
+import "../chunk-HNTKTK5B.js";
 import "../chunk-DQAN3JQP.js";
 import {
   getApiKey
-} from "../chunk-NKXSILEW.js";
+} from "../chunk-2UMNXADU.js";
 
 // bin/pushary-codex.ts
 import { basename } from "path";

package/dist/bin/pushary-connect.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/pushary-connect.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import {
+  printKeyCheck
+} from "../chunk-R6C4USIV.js";
+import {
+  confirmAppConnection,
+  connectDevice,
+  printConnectInstructions
+} from "../chunk-GX64YGU3.js";
+import "../chunk-3EGEA4KH.js";
+import {
+  parseFlags
+} from "../chunk-N4DA4CJB.js";
+import {
+  readKeySource
+} from "../chunk-B26DNXCA.js";
+import {
+  checkApiKey
+} from "../chunk-UKNAAVEE.js";
+import {
+  createIo
+} from "../chunk-TX7KBKT7.js";
+import {
+  UsageError
+} from "../chunk-7QLSKOSU.js";
+import "../chunk-BC3VCZ3E.js";
+import {
+  exitOnHelpFlag
+} from "../chunk-HUJQSP4F.js";
+import {
+  EXIT
+} from "../chunk-SML23YOT.js";
+import "../chunk-HNTKTK5B.js";
+import "../chunk-DQAN3JQP.js";
+import "../chunk-2UMNXADU.js";
+
+// bin/pushary-connect.ts
+exitOnHelpFlag("connect");
+var parseConnectOptions = (argv) => {
+  const flags = parseFlags(argv, { bools: ["app", "browser", "help", "h"], values: [] });
+  if (flags.command !== void 0 && flags.command !== "connect") {
+    throw new UsageError(`connect takes no positional arguments (got ${flags.command})`);
+  }
+  if (flags.bools.has("app") && flags.bools.has("browser")) {
+    throw new UsageError("pass either --app or --browser, not both");
+  }
+  return { mode: flags.bools.has("app") ? "app" : "browser" };
+};
+var options;
+try {
+  options = parseConnectOptions(process.argv.slice(2));
+} catch (err) {
+  process.stderr.write(`  ! ${err instanceof Error ? err.message : String(err)}
+`);
+  process.stderr.write("  Run `pushary connect --help` for the full list.\n");
+  process.exit(EXIT.USAGE);
+}
+var { bold, dim, cyan, yellow } = createIo();
+var main = async () => {
+  const source = readKeySource();
+  if (!source.key) {
+    console.log();
+    console.log(`  ${yellow("!")} No API key on this machine, so there is no site to connect a phone to.`);
+    console.log(`  ${dim("Run")} ${cyan("pushary setup")} ${dim("first.")}`);
+    console.log();
+    process.exit(EXIT.NOT_CONFIGURED);
+  }
+  console.log();
+  console.log(`  ${bold("Pushary")} ${dim("connect a phone")}`);
+  console.log();
+  const keyCheck = await checkApiKey(source.key);
+  if (keyCheck.kind !== "ok") {
+    const report = printKeyCheck(keyCheck);
+    if (keyCheck.kind !== "unreachable") process.exit(report.exitCode);
+    console.log();
+  }
+  const result = options.mode === "app" ? await confirmAppConnection(source.key) : process.stdout.isTTY ? await connectDevice(source.key, { showCapabilities: true }) : await printConnectInstructions(source.key);
+  console.log();
+  if (result.reachesYou) {
+    console.log(`  ${dim("Your phone can receive approvals. Try")} ${cyan("pushary doctor --roundtrip")} ${dim("to answer one.")}`);
+    console.log();
+    process.exit(EXIT.OK);
+  }
+  console.log(`  ${dim("No device of yours can answer yet. Run")} ${cyan("pushary connect")} ${dim("again when you are ready.")}`);
+  console.log();
+  process.exit(EXIT.NO_DEVICE);
+};
+main().catch((err) => {
+  process.stderr.write(`  ! connect failed: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(EXIT.FAILED);
+});

package/dist/bin/pushary-daemon.js

@@ -4,14 +4,18 @@ import {
 } from "../chunk-XHKBHWLX.js";
 import {
   resolveGlobalBinary
-} from "../chunk-J7JWI3KU.js";
+} from "../chunk-MUEW424A.js";
+import {
+  exitOnHelpFlag
+} from "../chunk-HUJQSP4F.js";
+import "../chunk-SML23YOT.js";
 import {
   getMachineId
 } from "../chunk-RN3NOEJF.js";
 import {
   getApiKey,
   getBaseUrl
-} from "../chunk-NKXSILEW.js";
+} from "../chunk-2UMNXADU.js";
 
 // src/spawn-daemon.ts
 import { spawn } from "child_process";
@@ -153,6 +157,7 @@ var runSpawnDaemon = async () => {
 };
 
 // bin/pushary-daemon.ts
+exitOnHelpFlag("daemon");
 runSpawnDaemon().then((code) => process.exit(code)).catch((err) => {
   process.stderr.write(
     `[pushary] daemon error: ${err instanceof Error ? err.message : String(err)}