@profoundry-us/highball 0.3.0 → 0.3.2

package/ONBOARDING.md

@@ -14,7 +14,7 @@ yourself.
 
 ## 0. Preconditions
 
-`npx highball --help` must work (Node >= 18, package installed as a dev
+`npx @profoundry-us/highball --help` must work (Node >= 18, package installed as a dev
 dependency). If it doesn't, ask your human whether to install from the npm
 registry (`npm install --save-dev @profoundry-us/highball`) or from a
 local tarball path they provide. In a repo with no `package.json`, create
@@ -36,19 +36,57 @@ Answer these by reading, not assuming:
   repo *already trust* — look at `package.json` scripts, a `justfile` or
   `Makefile`, CI workflows, README instructions. Wire what exists; invent
   no new tooling in the first pass.
-- **Host or container?** If the toolchain runs in Docker (compose files, a
-  devcontainer), find the dev service's name, then verify the repo mount
-  and working directory by running `pwd` and `ls` through
-  `docker compose exec -T <service>`. Rules will run there; you need to
-  know what paths they see.
+- **Host or container?** Settle this before writing a single rule — see the
+  callout immediately below. Getting it wrong makes every rule fail for the
+  same uninteresting reason, and it is the most common way this setup
+  stalls.
 - **What's fast?** Time candidate commands. Only sub-~2s commands belong
   on the per-edit path; test suites belong at turn end; anything needing a
   live server or long setup should not gate turns at all (leave it to the
   repo's existing workflow, or declare it `todo`).
 
+### If the repo's toolchain lives in Docker
+
+Plenty of repos run *everything* through containers — the host may have no
+Ruby, no Python, no database at all. Highball handles this, but only if you
+declare it. **The runner itself always stays on the host** (that's where the
+hooks fire and where the journal lives); only the rule commands move.
+
+Find the dev service and confirm what it actually sees, rather than assuming
+the layout:
+
+```bash
+docker compose ps --services
+docker compose exec -T <service> sh -c 'pwd && ls'
+```
+
+Then declare the wrapper once, and every rule runs through it:
+
+```yaml
+exec:
+  via: docker compose exec -T --workdir /app app
+```
+
+Four traps, each of which has bitten a real onboarding:
+
+1. **`-T` is mandatory.** Hook shells have no TTY; without it commands hang
+   or die with "the input device is not a TTY".
+2. **Set `--workdir`** to wherever the repo is mounted (verify with `pwd`
+   above). Containers frequently start somewhere other than the mount root.
+3. **Self-orchestrating commands must opt out with `exec: host`.** A
+   `just test` / `make test` target that runs its *own* `docker compose
+   exec` would otherwise be double-wrapped into nonsense.
+4. **Host-only tools opt out too.** If a linter or parser exists on the host
+   but not in the image (`node --check` against a JS bundle, say), mark that
+   rule `exec: host`.
+
+A stopped container makes every wrapped rule fail. That's correct behavior —
+unverifiable is not passing — but say so plainly to your human rather than
+quietly dropping the rules.
+
 ## 2. Scaffold
 
-Run `npx highball init`. It never overwrites: an existing
+Run `npx @profoundry-us/highball init`. It never overwrites: an existing
 `.highball/checks.yml` is kept, and if `.claude/settings.json` already
 exists it prints the hook snippet for you to merge by hand — merge it
 without disturbing existing hooks. Otherwise it creates both files.
@@ -110,7 +148,7 @@ Decision rules:
 You must never see, type, or store a token value. Ask your human to:
 
 1. Create this project (and a token for it) in their Highball app.
-2. Run `npx highball login` themselves — interactively, or piping the
+2. Run `npx @profoundry-us/highball login` themselves — interactively, or piping the
    token via `--token-stdin` to keep it out of shell history.
 
 This stores the token in `~/.highball/credentials.json` (machine-local,
@@ -119,8 +157,8 @@ vars instead. The repo tree never contains a secret.
 
 ## 5. Verify — all four proofs, not just the happy path
 
-1. **Fast path:** `npx highball run --fast` exits 0, every rule passed.
-2. **Full path:** `npx highball run` exits 0 (or fails honestly on real
+1. **Fast path:** `npx @profoundry-us/highball run --fast` exits 0, every rule passed.
+2. **Full path:** `npx @profoundry-us/highball run` exits 0 (or fails honestly on real
    pre-existing issues — surface those to your human rather than papering
    over them).
 3. **The guardrail:** prove exit 2 works. Create an obviously-temporary

package/README.md

@@ -13,11 +13,10 @@ block, they just aren't recorded.
 
 Published releases: `npm install --save-dev @profoundry-us/highball`.
 
-Install before running anything: with the package in `node_modules`, the
-short `npx highball …` form resolves to this runner's binary. Without it,
-bare `npx highball` would fetch the unrelated unscoped `highball` package
-from the registry — for uninstalled one-offs, always use the scoped form
-(`npx @profoundry-us/highball <command>`).
+**Always use the scoped name.** The unscoped npm name `highball` belongs to
+an unrelated package, so a bare `npx highball` — in a committed hook, a
+README, or a one-off — is a single uninstalled checkout away from fetching
+a stranger's code and running it.
 
 From a local tarball (pre-release):
 
@@ -31,7 +30,7 @@ npm install --save-dev ../highball-runner/profoundry-us-highball-<v>.tgz
 Highball is installed *by the AI agent that will be checked by it*. After
 installing the package, tell the repo's Claude Code agent:
 
-> Run `npx highball onboard` and follow the instructions.
+> Run `npx @profoundry-us/highball onboard` and follow the instructions.
 
 [ONBOARDING.md](ONBOARDING.md) (which that command prints) walks the agent
 through surveying the repo's real toolchain, scaffolding, writing rules that
@@ -41,8 +40,8 @@ human, and verifying all four proofs — including that exit 2 actually blocks.
 The pieces, for reference or manual setup:
 
 ```bash
-npx highball init    # scaffolds .highball/checks.yml + Claude Code hooks
-npx highball login   # stores this machine's project token (once per machine)
+npx @profoundry-us/highball init    # scaffolds checks.yml + Claude Code hooks
+npx @profoundry-us/highball login   # stores a project token (once per machine)
 ```
 
 `init` never overwrites an existing `checks.yml` and never edits an existing
@@ -95,9 +94,17 @@ in hosts that render Apps (Claude Desktop and friends), asking about your
 checks produces an interactive inline dashboard — click a run for per-rule
 detail with expandable command output, re-run fast or full checks from a
 button. In hosts without Apps support the same tools answer in plain text,
-per the extension's graceful-degradation rule. Register it as
-`command: npx`, `args: ["highball", "mcp"]` (or absolute paths for hosts
-that spawn outside your shell PATH).
+per the extension's graceful-degradation rule. Register it with the scoped
+name — hosts spawn the server from an arbitrary directory, so it resolves
+from the registry rather than a local install:
+
+```json
+"highball": { "command": "npx", "args": ["-y", "@profoundry-us/highball", "mcp"] }
+```
+
+The journal it reads is machine-global (`~/.highball/runs/`), so one
+registration covers every repo on that machine — there is no per-repo MCP
+setup.
 
 The split is capability-driven, not guesswork: the server reads the
 client's initialize capabilities (`io.modelcontextprotocol/ui`) — hosts
@@ -112,8 +119,8 @@ Desktop restart.
 
 Every run also appends to a local journal (`~/.highball/runs/<project>.jsonl`,
 pruned to the last 200) — unconditionally, whether or not reporting is
-configured. `npx highball runs` lists recent runs; `npx highball runs 3`
-shows one run's detail with failure output, and `--logs` prints every
+configured. `npx @profoundry-us/highball runs` lists recent runs; adding a
+number shows one run's detail with failure output, and `--logs` prints every
 rule's captured output, GitHub-Actions-style — the journal keeps the last
 10KB per rule, pass or fail, while the dashboard receives failure tails
 only. So the runner is self-sufficient out of the box: the hosted

package/lib/init.js

@@ -36,17 +36,20 @@ checks:
   #   fast: true
 `;
 
+// Always the SCOPED command. The unscoped npm name belongs to an unrelated
+// package, so a bare `npx highball` in a committed hook is one uninstalled
+// checkout away from fetching a stranger's code and running it on every edit.
 const HOOKS_JSON = {
   hooks: {
     PostToolUse: [
       {
         matcher: "Write|Edit",
-        hooks: [{ type: "command", command: "npx highball run --fast" }]
+        hooks: [{ type: "command", command: "npx @profoundry-us/highball run --fast" }]
       }
     ],
     Stop: [
       {
-        hooks: [{ type: "command", command: "npx highball run", timeout: 900 }]
+        hooks: [{ type: "command", command: "npx @profoundry-us/highball run", timeout: 900 }]
       }
     ]
   }

package/lib/run.js

@@ -137,11 +137,25 @@ export async function run(args) {
 // friends); that id groups this run with the rest of the agent's session
 // on the dashboard. A TTY means a human at a terminal — don't block on
 // read.
+//
+// The deadline matters: a non-TTY stdin that nobody writes to and nobody
+// closes (a pipeline, a task runner, a CI step) would otherwise hang the
+// runner forever waiting for EOF. Hooks write their payload immediately,
+// so a short wait costs nothing and turns an indefinite hang into a run
+// with no session context.
+const HOOK_STDIN_DEADLINE_MS = 400;
+
 async function readHookPayload() {
   if (process.stdin.isTTY) return {};
   try {
-    let text = "";
-    for await (const chunk of process.stdin) text += chunk;
+    const text = await Promise.race([
+      (async () => {
+        let buffered = "";
+        for await (const chunk of process.stdin) buffered += chunk;
+        return buffered;
+      })(),
+      new Promise((resolve) => setTimeout(() => resolve(""), HOOK_STDIN_DEADLINE_MS))
+    ]);
     return JSON.parse(text);
   } catch {
     return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and reports runs to a Highball dashboard.",
   "keywords": [
     "ai",