@ssheleg/sheleg-dev 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## v0.10.5 — the installers refuse the shadow they used to write
+
+Both install channels — `npx @ssheleg/sheleg-dev` and `install.sh` — now consult the
+target home's `~/.claude/plugins/installed_plugins.json` before writing anything under
+`~/.claude/skills/`. If the sheleg-dev **plugin** is installed there, the install is
+**refused with exit 3**: a plain copy beside a plugin shadows the plugin's skill of the
+same name and serves the frozen version forever, and until this release neither channel
+looked at all. Reproduced live in the family on 2026-08-29: a bare
+`npx @ssheleg/telegram-dev` shipped three shadows while the plugin was enabled.
+
+- `installed_plugins.json` is the signal, because it is the record of what is actually
+  installed. A check keyed on the `plugins/marketplaces/<name>` directory alone — the
+  shape other family members carried — is the fail-open class: a marketplace added from
+  a local `directory` source has no dir there, and plugin names differ from marketplace
+  names. The directory is kept only as a fallback signal.
+- The refusal names its remedy with the **real spec read from the JSON**
+  (`claude plugin marketplace update sheleg-dev`, `claude plugin update <spec>`), plus
+  the family launcher line, and offers `--force` as the explicit override for running
+  two channels deliberately.
+- An absent or corrupt `installed_plugins.json` reads as "no plugin": the check fails
+  open and never crashes an install — the fresh HOME is the common case.
+- New suite `test/installer_test.js` (11 cases, both channels, throwaway HOMEs), wired
+  into `npm test` and CI. **Watched failing first**: run against the pre-refusal
+  installers it went red on 7 of 11 cases, each showing the shadow landing at exit 0.
+- Both success paths now end by saying how the next version arrives — the update line —
+  and `install.sh` gained `--force`/usage parsing (unknown argument exits 2) to carry
+  the same contract as the npm channel.
+- `.claude-plugin/marketplace.json` still said "Six integration skills" while seven
+  ship (the validator counts 7; README and SECURITY say seven). It now says seven and
+  names error tracking — the second hand-written count this repository has caught after
+  the fact, which is why the new suite derives the roster from the tree.
+- `SECURITY.md`'s installer contract moved with the behaviour: the read surface now
+  includes the two read-only looks at the target home, and the I/O-surface grep line
+  count was re-measured (twelve, and it was already twelve before this change — the
+  "eleven" had rotted when a comment naming `rm -rf` arrived).
+
 ## v0.10.4 — the channel that sends the installs, on npm too
 
 - The `skills.sh` badge and the canonical `homepage` reached GitHub in the previous cycle and stopped

package/README.md

@@ -118,6 +118,12 @@ a Lighthouse score.
 npx @ssheleg/sheleg-dev
 ```
 
+If the sheleg-dev **plugin** is already installed in that home, the npm installer
+and `install.sh` refuse with exit 3 instead of writing plain copies — a plain
+copy shadows the plugin's skill of the same name and serves the frozen version
+forever. The refusal prints the plugin-channel update commands; `--force`
+overrides it, deliberately.
+
 **Any of 70+ agents:**
 
 ```bash

package/SECURITY.md

@@ -33,7 +33,7 @@ no socket; the greps below prove all three.
 | `plugins/sheleg-dev/hooks/money-gate.js` | 1 | Runs on a tool call, when the plugin is enabled. Requires `path` and its own decision module — nothing else. Reads stdin, writes one JSON line, exits 0 on every path. |
 | `plugins/sheleg-dev/hooks/lib/moneygate.js` | 1 | Pure. Payload and environment in, verdict out. No `require` at all, no filesystem, no clock. |
 | `bin/sheleg-dev.js` — the npm installer | 1 | Runs only when you invoke it. Node built-ins only: `fs`, `path`, `os`. |
-| `install.sh` — the shell installer | 1 | **Not in the tarball** — `files` ships `bin/` and `plugins/`, so this one reaches you only through a clone. Runs when you invoke it. Coreutils only: `cd`, `pwd`, `dirname`, `basename`, `mkdir`, `rm`, `cp`, `echo`. It is the destructive channel: `rm -rf` per skill, then `cp -R`. |
+| `install.sh` — the shell installer | 1 | **Not in the tarball** — `files` ships `bin/` and `plugins/`, so this one reaches you only through a clone. Runs when you invoke it. Shell tools only: `cd`, `pwd`, `dirname`, `basename`, `mkdir`, `rm`, `cp`, `echo`, plus `sed` and `head` to read the plugin registry it refuses to shadow. It is the destructive channel: `rm -rf` per skill, then `cp -R`. |
 | `plugins/sheleg-dev/skills/*/fixtures/*.json` — webhook payloads | 16 | Data. Placeholder ids only; no key, token, signing secret or real customer id. |
 | `plugins/sheleg-dev/skills/*/fixtures/*.mjs` — the assertion packs and their reference implementations | 4 | Runs only when you invoke it. Reads the JSON beside it with `readFileSync` and nothing else: no `child_process`, no `fetch`, no write, no `process.env`. |
 | `plugins/sheleg-dev/skills/*/fixtures/manifest.json` and its `README.md` | 4 | Text. The invariant-to-fixture-to-document map, which `test/validate.py` reads. |
@@ -61,24 +61,32 @@ nothing but the CLI you typed.
 ## What the installers read and write
 
 Both do one thing: copy the seven skill directories out of the package into
-`~/.claude/skills/<name>`.
-
-- **Read:** only files inside the package.
+`~/.claude/skills/<name>` — unless the sheleg-dev **plugin** is already installed
+in that home, in which case both refuse with exit 3 rather than write plain
+copies that would shadow the plugin's skills and serve this frozen version
+forever. `--force` overrides the refusal, deliberately.
+
+- **Read:** files inside the package, plus two read-only looks at the target
+  home to decide the refusal above: `~/.claude/plugins/installed_plugins.json`
+  (the record of installed plugins; a missing or unparsable file reads as "no
+  plugin", so the check fails open and never crashes an install) and whether
+  `~/.claude/plugins/marketplaces/sheleg-dev` exists, kept only as a fallback
+  signal.
 - **Write:** only `~/.claude/skills/` — seven directories, named for the seven skills.
   Nothing else on the filesystem, nothing outside `$HOME`.
 - **Network: none.** Neither file opens a socket or resolves a hostname.
   `bin/sheleg-dev.js` requires `fs`, `path` and `os` and nothing else — no
   `child_process`, no `fetch`, no `http` — so it spawns no process at all;
-  `install.sh` runs only the coreutils named above. The grep below prints the
-  whole surface of both files in eleven lines.
+  `install.sh` runs only the shell tools named above. The grep below prints the
+  whole surface of both files in twelve lines.
 - **No telemetry, no analytics, no phone-home.** Nothing here has anywhere to
   send anything.
 
 **One destructive difference between the two installers.** `bin/sheleg-dev.js`
 skips a skill that is already installed and says so, unless you pass `--force`
-(`bin/sheleg-dev.js:45-46`). `install.sh` does not ask: for each of the seven names
+(`bin/sheleg-dev.js:89-90`). `install.sh` does not ask: for each of the seven names
 it runs `rm -rf` on the destination and re-copies, every time
-(`install.sh:21-22`). If you have hand-edited an installed skill, the shell
+(`install.sh:62-63`). If you have hand-edited an installed skill, the shell
 installer deletes your edits and the node installer does not.
 
 ## Credentials
@@ -193,14 +201,22 @@ node test/moneygate_test.js
 # The command prints its own count.
 node test/fixtures_test.js
 
+# Both installers against throwaway HOMEs: fresh install, rerun, --force, and the
+# plugin-present refusal — exit 3, the remedy naming the real plugin spec, nothing
+# written; a corrupt ~/.claude/plugins/installed_plugins.json fails open. The command
+# prints its own count.
+node test/installer_test.js
+
 # What the assertion packs cannot reach: NO OUTPUT, and grep exits 1 because it
 # matched nothing. `readFileSync` of the fixtures beside them is their whole I/O.
 grep -rnE "child_process|\bfetch\(|require\('(http|https|net|dns|tls)'\)|spawn\(|execFile|writeFileSync|appendFileSync|unlinkSync|process\.env\." \
   plugins/sheleg-dev/skills/*/fixtures/*.mjs
 
-# The entire I/O surface of the only two executable files: eleven lines. Three
-# built-in requires, the copy/mkdir/remove calls, homedir, and install.sh's
-# rm -rf + cp -R. No process, no socket, no network.
+# The entire I/O surface of the only two executable files: twelve lines. Three
+# built-in requires, the copy/mkdir/remove calls, homedir, install.sh's
+# rm -rf + cp -R, and one comment naming rm -rf. No process, no socket, no
+# network — the plugin-registry read that decides the shadow refusal is
+# readFileSync in the node file and sed in the shell one.
 grep -nE "require|child_process|exec|spawn|fetch|socket|rm -rf|cp -R|copyFileSync|mkdirSync|rmSync|homedir" bin/sheleg-dev.js install.sh
 
 # Live-key shapes across the skill payload: one line, and it is a placeholder.

package/bin/sheleg-dev.js

@@ -17,6 +17,44 @@ const os = require('os');
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'ssheleg/sheleg-dev';
 
+// Exit codes are the contract: 0 installed or skipped, 1 corrupted package,
+// 2 usage error, 3 refused — the plugin channel owns this agent (--force overrides).
+const EXIT_PLUGIN_PRESENT = 3;
+
+/**
+ * The plugin spec (`<name>@<marketplace>`) installed for `name` in this home,
+ * or null.
+ *
+ * `installed_plugins.json` is the record of what is actually installed. The
+ * `plugins/marketplaces/<name>` directory — the check other members of this
+ * family keyed on until 2026-08-29 — under-reports: a marketplace added from a
+ * local `directory` source has no dir there at all, and plugin names differ
+ * from marketplace names, so a check keyed on it stays green while the shadow
+ * lands. Absence and corruption both read as "no plugin": the fresh HOME is
+ * the common case, and an installer that crashes on a parse error refuses the
+ * machines that need it most.
+ */
+function installedPluginSpec(home, name) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const plugins =
+      parsed && typeof parsed === 'object' &&
+      parsed.plugins && typeof parsed.plugins === 'object'
+        ? parsed.plugins
+        : parsed;
+    if (!plugins || typeof plugins !== 'object') return null;
+    for (const spec of Object.keys(plugins)) {
+      if (spec === name) return `${name}@${name}`;
+      if (spec.startsWith(name + '@')) return spec;
+    }
+  } catch {
+    // missing or corrupt = no plugin — fail open on absence, never crash
+  }
+  return null;
+}
+
 function usage() {
   console.log(`sheleg-dev installer
 
@@ -25,6 +63,12 @@ Usage:
                                        into ~/.claude (skip existing unless --force)
   npx @ssheleg/sheleg-dev --help
 
+Exit codes:
+  0 installed or skipped   2 usage error
+  1 corrupted package      3 refused: the sheleg-dev PLUGIN is installed in
+                             this home — plain copies would shadow its skills
+                             (pass --force to write them anyway)
+
 Other install paths:
   Claude Code plugin:  /plugin marketplace add ${REPO}
                        /plugin install sheleg-dev@sheleg-dev
@@ -84,6 +128,39 @@ function main(argv) {
   }
 
   const home = os.homedir();
+
+  // One channel per agent. Plain copies under ~/.claude/skills/ beside the
+  // installed sheleg-dev plugin are a second listing of the same skills, and
+  // the stale copies win — the exact shadow this family's canon forbids.
+  // Refuse rather than create them, and refuse LOUDLY: a marketplaces/-dir
+  // check alone is the fail-open class (a directory-sourced marketplace has no
+  // dir there, plugin names differ from marketplace names), and a refusal that
+  // exits 0 reads as success to every script above it. Reproduced live
+  // 2026-08-29: a bare `npx @ssheleg/telegram-dev` shipped three shadows past
+  // exactly that hole while the plugin was enabled.
+  const spec = installedPluginSpec(home, 'sheleg-dev');
+  const marketplace = path.join(home, '.claude', 'plugins', 'marketplaces', 'sheleg-dev');
+  const viaMarketplaceDir = !spec && fs.existsSync(marketplace);
+  if ((spec || viaMarketplaceDir) && !force) {
+    const found = spec
+      ? `installed as the Claude Code plugin ${spec}\n` +
+        '         (declared in ~/.claude/plugins/installed_plugins.json)'
+      : `registered as a Claude Code marketplace\n         (${marketplace})`;
+    console.error(
+      `refused: sheleg-dev is already ${found}.\n` +
+      `         Plain copies in ~/.claude/skills/ would shadow the plugin's\n` +
+      `         ${names.length} skills and serve this frozen version forever. Update the\n` +
+      '         plugin channel instead:\n' +
+      '           claude plugin marketplace update sheleg-dev\n' +
+      `           claude plugin update ${spec || 'sheleg-dev@sheleg-dev'}\n` +
+      '         Family launcher (updates every member, prunes shadow copies):\n' +
+      '           npx --yes sshlg-skills@latest update\n' +
+      '         Pass --force to write the plain copies anyway — a deliberate choice\n' +
+      '         to run two channels, where the stale one wins.'
+    );
+    return EXIT_PLUGIN_PRESENT;
+  }
+
   for (const name of names) {
     installOne(
       `${name} skill`,
@@ -111,6 +188,15 @@ function main(argv) {
     console.log('skills copy. To get it here, register it yourself — README.md, section');
     console.log('"The manual gate", has the settings snippet. Nothing enforces this step.');
   }
+  // The last line says how the next version arrives — "Installed" is not a
+  // complete sentence. Auto-update is off on purpose: this member composes
+  // with its family, and per-marketplace autoUpdate moves each member on its
+  // own clock, into combinations nobody tested together.
+  console.log(
+    '\nUpdates: rerun `npx @ssheleg/sheleg-dev@latest --force`, or refresh the\n' +
+    'whole family with `npx --yes sshlg-skills@latest update` (every channel,\n' +
+    'and it prunes plain copies that would shadow a plugin).'
+  );
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/sheleg-dev",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Seven integration skills for the layer a product reaches once it has users: Stripe subscription billing and cancellation retention, crypto payments, ad and conversion tracking under Consent Mode v2, Google sign-in and the wider Google auth surface, error tracking, and Core Web Vitals. This package is the installer CLI.",
   "bin": {
     "sheleg-dev": "bin/sheleg-dev.js"
@@ -43,8 +43,8 @@
     "skill"
   ],
   "scripts": {
-    "test": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js",
+    "test": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js",
     "test:negatives": "python3 test/negatives.py",
-    "test:all": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && python3 test/negatives.py"
+    "test:all": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js && python3 test/negatives.py"
   }
 }

package/plugins/sheleg-dev/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "sheleg-dev",
   "displayName": "Sheleg Dev",
   "description": "The integration layer a product needs once it has users: Stripe subscription billing reconciled into your own database, crypto payments that survive over-payment and duplicate webhooks, ad and conversion tracking under Consent Mode v2, Google sign-in with the account-linking guards, the wider Google auth surface, and Core Web Vitals work that moves the score, and Sentry error tracking wired so it does not forward your own credentials to a third party and so a stack trace names the commit that caused it.",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"