slopgate-cli - npm Package Compare versions

Comparing version 0.2.2 to 0.4.2

package.json

 {
   "name": "slopgate-cli",
-  "version": "0.2.2",
+  "version": "0.4.2",
   "description": "Install-gate hook that blocks slopsquatted / hallucinated npm packages before an AI coding agent installs them.",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -39,10 +39,41 @@ # slopgate
 
-Wire it into Claude Code (`settings.json`; the same binary serves the other agents via their own hook command names):
+## Wire it into your agent
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/adamsjack711-ux/slopgate/main/demo/init.gif" alt="slopgate init wiring the hook, then blocking a hallucinated npm install" width="820">
+</p>
+
+One command. `slopgate init` finds its **own** absolute path and merges the hook
+into the agent's settings file — no hand-pasted path to go stale, every other
+key in the file preserved, the original backed up to `*.slopgate.bak`:
+
+```bash
+slopgate init                 # Claude Code  (~/.claude/settings.json)
+slopgate init --agent codex   # OpenAI Codex (~/.codex/hooks.json)
+slopgate init --agent all     # every supported agent at once
+slopgate init --print         # print the snippet + target path, write nothing
+```
+
+Re-running is safe: it updates the path in place instead of duplicating, and
+says `unchanged` when nothing needs to move. Supported: `claude`, `codex`,
+`cursor`, `droid`, `cascade`.
+
+<details><summary>Prefer to wire it by hand?</summary>
+
+Claude Code, `~/.claude/settings.json` (the same binary serves the other agents
+via their own hook command names — see the [Agents](#agents) table):
+
 ```json
 "PreToolUse": [{ "matcher": "Bash",
   "hooks": [{ "type": "command",
-    "command": "/abs/path/to/slopgate claude-pre-tool-use" }] }]
+    "command": "/abs/path/to/slopgate claude-pre-tool-use # slopgate-managed" }] }]
 ```
 
+The trailing `# slopgate-managed` is a shell comment (inert when the hook runs).
+It's how a later `slopgate init` recognizes and updates this entry in place —
+regardless of where the binary ends up — instead of adding a duplicate. Wiring
+by hand is optional; `slopgate init` adds it for you.
+
+</details>
+
 ---
@@ -52,3 +83,3 @@
 
-For each npm package a command would fetch, three checks run cheapest-first,
+For each npm package a command would fetch, the checks run cheapest-first,
 short-circuiting where they can:
@@ -61,3 +92,7 @@
    downloads < `minWeeklyDownloads`. Eligible on its own → at least `review`.
-3. **pkgxray guard** — `pkgxray guard npm:<name>@<version> --format json`, parsed
+3. **Typosquat** — the (existing) name is a near-miss of a popular package
+   (`lodahs`→`lodash`, `reactt`→`react`), by edit distance against an embedded
+   corpus of the top npm packages. Established/popular packages are exempt.
+   Eligible on its own → at least `review`. (Offline; no extra network.)
+4. **pkgxray guard** — `pkgxray guard npm:<name>@<version> --format json`, parsed
    for its `decision` and cited `report.findings`.
@@ -104,2 +139,3 @@
 ```bash
+slopgate init --print           # show the wiring snippet without touching any file
 slopgate preflight              # is pkgxray resolvable?
@@ -126,2 +162,3 @@ slopgate check express          # evaluate a name or command, print JSON evidence
 | `skipPkgxray` | `false` | run existence + freshness only; skip the pkgxray subprocess (and its preflight) |
+| `typosquatCheck` | `true` | flag names that are near-misses of popular packages; set `false` to disable |
 
@@ -186,2 +223,15 @@ `skipPkgxray: true` turns slopgate into a pure existence/freshness pre-check —
 
+### Typosquatting is name-distance, guarded against false positives
+
+A typosquat is the inverse of a hallucination: the package *does* exist, but its
+name is a near-miss of a popular one (`lodahs` for `lodash`) registered to catch
+a fat-fingered or mis-recalled install. slopgate measures optimal-string-
+alignment (edit) distance — including adjacent transpositions, a classic slip —
+against an **embedded, rank-ordered corpus of the top npm packages**, so it works
+offline. Three guards keep it precise: a package that *is* itself popular is
+never flagged; one with real download traffic is treated as established, not a
+squat; and short names are skipped (too many distance-1 collisions). It's
+review-tier, not an auto-block, because edit distance is a heuristic — the human
+gets the final call.
+
 ### It shells out to pkgxray — it never reimplements it
@@ -224,6 +274,5 @@
 
-v1 is the **hallucination gate** for **npm/npx only**. Deliberately out of scope
-(clean extension seams left where natural): PyPI/pip, pnpm/yarn/bun clients,
-cross-registry confusion checks, fuzzy typosquat name-similarity, and any review
-of agent-written code.
+The gate covers **npm/npx only**. Deliberately out of scope (clean extension
+seams left where natural): PyPI/pip, pnpm/yarn/bun clients, cross-registry
+confusion checks, and any review of agent-written code.
 
@@ -230,0 +279,0 @@ ## License

No alert changes

Improved metrics

Total package byte prevSize

26095695

1.72%

Number of lines in readme file

275

21.68%

No dependency changes