@ssheleg/sheleg-dev 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+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).
+
+## [0.4.0] — 2026-08-12
+
+### Changed
+
+- **Five of the six skills now open with `Use when …` and carry paired Russian
+  triggers** — `ad-tracking`, `crypto-payments`, `frontend-performance`, `google-auth`,
+  `google-signin`. `stripe-billing` already did, which is how the gap stayed invisible:
+  the pack looked migrated because the one skill anybody checked was. The other five
+  were unreachable from a request written in Russian.
+
+  v0.3.0 brought three of these descriptions inside the 970 headroom by dropping
+  duplicate triggers; this release rebuilds all five to the house shape — capability,
+  coverage, English and Russian triggers, exclusion — and every one lands between 821
+  and 884 chars.
+
+## [0.3.1] — 2026-08-11
+
+### Changed
+
+- **Thirteen references over 100 lines now open with a `## Contents` list**,
+  generated from each file's own `##` headings. A partial read is what an agent
+  does with a long reference, and without the list it gets an arbitrary slice.
+
+## [0.3.0] — 2026-08-11
+
+### Changed
+
+- **`ad-tracking`'s body went from 891 lines / 9160 tokens to 429 / 4747** —
+  both caps are 500 lines and 5000 tokens, so it had been running at nearly
+  double each. Measured with `cl100k`, not estimated.
+
+  Nothing was deleted. Consent, event naming, e-commerce, CSP, Next.js and
+  verification were duplicating `consent-mode.md`, `event-tracking.md`,
+  `gtag-api.md` and `performance-security.md` — which cover the same ground in
+  more depth — so the body keeps a load trigger and the trap, and the depth
+  stays where it already was. The GA4 command table and the recommended-event
+  table were verbatim subsets of two references.
+
+  What had **no** reference to go to was moved into a new one:
+  `references/meta-linkedin.md` (parameter objects per standard event, the
+  firing wrapper, advanced matching, CAPI deduplication).
+
+  The traps stay in the body on purpose — an agent cannot know to open a file
+  about a trap it does not know exists. The consent ordering, the
+  `NEXT_PUBLIC_*` build-time inlining, purchase deduplication and the
+  double-counted SPA page view are all still inline.
+
+- **Three descriptions brought inside the 5% headroom** the canon asks for
+  (≤970 of 1024): `google-signin` 1021 → 968, `crypto-payments` 993 → 966,
+  `ad-tracking` 988 → 959. Only duplicate trigger phrases were dropped —
+  "crypto invoice" beside "crypto checkout", "ad pixel" beside "pixel". A
+  description at 99% of the cap has nowhere to put the "NOT for …" clause a
+  near-miss neighbour will eventually force.
+
+## [0.2.0] — 2026-08-11
+
+A sixth skill, and the one the pack was missing: cards. `crypto-payments`
+covered the gateway that calls you back; nothing covered the gateway that holds
+the money and the subscription state.
+
+### Added
+
+- **`stripe-billing`** — the seam between Stripe and your own database, which is
+  where subscription integrations actually fail. Stripe's agent toolchain first
+  (CLI, `stripe agent setup`, `stripe sandbox create` for keys without an
+  account, the MCP server's implementation planner, `.md` docs), then the
+  invariants: a lazily-built client with a pinned API version and
+  `maxNetworkRetries` rather than a hand-rolled loop that buys two subscriptions
+  for one intent; product-to-price resolution with pinned ids and both modes'
+  ids in every allowlist; the get-or-create customer race as a conditional
+  update with orphan cleanup; metadata written to the session **and**
+  `subscription_data`, because renewal events never see the session;
+  claim-first webhook idempotency with a release on failure, and the response
+  codes that decide whether Stripe retries; the verify endpoint as a safety net,
+  with the ownership check that stops one user claiming another's purchase;
+  `billing_reason` as the difference between a renewal and a $0.40 proration
+  invoice; proration with `error_if_incomplete` and a compensating Stripe revert
+  when the local write fails; cumulative `amount_refunded` handled as a
+  compare-and-swap; a sequential reconciliation job that leaves non-Stripe rows
+  alone; and price drift, which fails no request and reaches only customers.
+
+  Five references: `stripe-agent-toolchain.md`, `webhook-events.md`,
+  `subscription-lifecycle.md`, `price-integrity.md`,
+  `testing-and-local-dev.md`.
+
+  Stripe-side decisions — Checkout vs PaymentIntents, Connect, Tax, Metronome
+  for new usage-based billing — are deferred by name to Stripe's own
+  `stripe-best-practices` skill, which wins any disagreement. The rules taken
+  from Stripe's documentation (no `payment_method_types` on subscription
+  Checkout Sessions, one Product per plan a customer can choose, restricted keys
+  over secret keys, a secrets vault over environment variables) were read from
+  `docs.stripe.com` on 2026-08-11 against Stripe CLI 1.45.2 and the official
+  plugin 0.5.1.
+
+### Changed
+
+- CI installs and asserts six skills, not five, and requires a `stripe-billing`
+  reference to land with them.
+
+## [0.1.0] — 2026-08-06
+
+First release. Five skills, ported out of a Cursor-only skills directory where
+they had no version, no validator and no way to reach any other agent. Every
+external claim with a shelf life was re-checked against its source on
+2026-08-06 before shipping; what changed is listed under *Corrected on the way
+in*.
+
+### Added
+
+- **`crypto-payments`** — accepting crypto without losing money to the three
+  things that make it unlike cards: a payer who sends the wrong amount, a
+  webhook that arrives more than once, and a rate that moves between quote and
+  transfer. Status mapping with an explicit terminal set, signature verification
+  with constant-time compare and the JSON-escaping trap, idempotency as a
+  compare-and-swap rather than read-then-write, proxy-aware IP allowlisting,
+  CSRF exemption scoped to one exact path, the conversion buffer, the
+  reconciliation fields that make "what did we receive" answerable, the credit
+  waterfall, refunds and AML holds, tunnelled local development with signed mock
+  callbacks, a ten-case test matrix and a security checklist.
+  `references/heleket-provider.md` carries one gateway's concrete wire format.
+- **`ad-tracking`** — GA4, Google Ads, Meta Pixel and LinkedIn Insight under
+  Consent Mode v2, with unified consent updates, cross-platform event mapping,
+  e-commerce and deduplication, CSP per platform, and Next.js patterns. Four
+  deep references on the Google tag itself: consent mode, the gtag API, event
+  design, and performance/security.
+- **`google-signin`** — the GIS ID-token flow as a security problem: the
+  three-way account-linking branch with the pre-hijacking guard, login-CSRF
+  defence covering **both** delivery flows, nonce and replay protection, GCP
+  setup, and a checklist where each item maps to a real attack.
+- **`google-auth`** — the server side: OAuth 2.0 web-server flow, Application
+  Default Credentials, service accounts and JWT, Workload and Workforce Identity
+  Federation, impersonation and downscoping — Node and Python throughout.
+- **`frontend-performance`** — Core Web Vitals with an audit workflow, font
+  loading, GPU-composited animation and the gradient-animation alternatives,
+  bundle and cache work, CSP, and the accessibility rules that actually move a
+  Lighthouse score. References for CSS, Next.js and accessibility.
+
+### Corrected on the way in
+
+- **FedCM is mandatory, not upcoming.** The source described the migration as
+  having happened; it did not say the opt-out is gone. FedCM has been required
+  for One Tap and Sign-In button implementations since **August 2025**, so
+  `use_fedcm` and the traffic exemption no longer exist, and code branching on
+  the old `isNotDisplayed()` moment callbacks needs revisiting. Corrected in
+  both `google-auth` and `google-signin`.
+- **Consent Mode v2 now expects a certified CMP.** Required since March 2024 for
+  EEA/UK traffic; by 2026 Google additionally expects a CMP from its
+  certification programme, so a correct hand-rolled banner is no longer
+  sufficient on its own. Noted in `references/consent-mode.md`.
+- **`crypto-payments` is provider-neutral by design.** The source was written
+  around a single gateway. The reusable engineering — signature verification,
+  idempotency, the buffer, reconciliation — is provider-shaped, and pinning it
+  to one processor made the skill narrower and tied it to that processor's
+  standing. The gateway's own wire format moved to a reference, which states the
+  compliance position on record for it and says plainly that choosing a
+  processor is not a technical decision.
+
+### Infrastructure
+
+- Structural validator (`test/validate.py`): one version across four files,
+  Agent Skills front-matter limits, and `SKILL.md` ↔ `references/` agreement in
+  **both** directions — no dangling link, no file nobody loads.
+- Installer CLI and `install.sh`, both installing all five skills, both
+  exercised by running them rather than syntax-checking them.
+- CI with negative self-tests: every guard is planted against and required to
+  fail before it is trusted.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssheleg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# sheleg-dev
+
+The integration layer a product reaches once it has users: **money in, tracking,
+sign-in, and speed.**
+
+Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
+
+---
+
+## The six skills
+
+| Skill | Answers |
+|---|---|
+| **`stripe-billing`** | how does a Stripe payment become an entitlement in my database, exactly once |
+| **`crypto-payments`** | how do I take crypto without losing money to under-payment, duplicate webhooks or rate drift |
+| **`ad-tracking`** | how do GA4, Google Ads, Meta and LinkedIn fire correctly under Consent Mode v2 |
+| **`google-signin`** | how do I let people sign in with Google without handing someone their account |
+| **`google-auth`** | how does my *server* authenticate to Google — OAuth, ADC, service accounts, federation |
+| **`frontend-performance`** | why is the Lighthouse score bad and which fix actually moves it |
+
+Each carries its own references and loads them only when the work reaches them.
+
+**`stripe-billing`** — Stripe's own agent toolchain first (CLI, `stripe agent
+setup`, a sandbox without an account, the MCP implementation planner), then the
+seam it cannot help with: a pinned API version and SDK retries instead of a loop
+that buys two subscriptions for one intent; metadata written twice, because
+renewal events never see the checkout session; claim-first webhook idempotency
+with a release on failure; `billing_reason` as the difference between a renewal
+and a $0.40 proration invoice; proration with a compensating revert when the
+local write fails; `amount_refunded` as a cumulative total, not an increment; a
+reconciliation job that leaves non-Stripe rows alone; and price drift, which
+fails no request and reaches only customers. Which Stripe primitive to use is
+deferred to Stripe's own `stripe-best-practices` skill.
+
+**`crypto-payments`** — status mapping with an explicit terminal set;
+signature verification in constant time, with the forward-slash escaping trap
+that makes signatures valid for some payloads and not others; idempotency as a
+compare-and-swap (`updateMany` with a non-final status guard) instead of the
+read-then-write race; proxy-aware IP allowlisting that counts hops from the
+right; CSRF exemption scoped to exactly one path; the conversion buffer; the
+reconciliation fields that make "what did we actually receive" answerable six
+months later; refunds and AML holds as states, not events.
+
+**`ad-tracking`** — one unified consent update across four platforms, standard
+event mapping, e-commerce with deduplication, per-platform CSP, Next.js
+patterns. Four deep references on the Google tag: consent mode, the gtag API,
+event schema design, and performance/security.
+
+**`google-signin`** — the ID-token flow treated as a security problem: the
+three-way account-linking branch with the **pre-hijacking guard**, login-CSRF
+covering both delivery flows, nonce and replay protection, and a checklist where
+every item maps to a named attack.
+
+**`google-auth`** — OAuth 2.0 web-server flow, Application Default Credentials
+and its search order, service-account JWT including domain-wide delegation,
+Workload and Workforce Identity Federation, impersonation, downscoping. Node and
+Python side by side throughout.
+
+**`frontend-performance`** — Core Web Vitals with an audit workflow and a budget
+template; font loading; GPU-composited animation and what to do instead of
+animating `background-position`; code splitting, cache headers, CSP; and the
+accessibility rules — contrast, heading order, alt text, target size — that move
+a Lighthouse score.
+
+---
+
+## Install
+
+**Claude Code plugin** (recommended):
+
+```bash
+/plugin marketplace add ssheleg/sheleg-dev
+/plugin install sheleg-dev@sheleg-dev
+```
+
+**npm installer** — copies all six skills into `~/.claude/skills/`:
+
+```bash
+npx @ssheleg/sheleg-dev
+```
+
+**Any of 70+ agents:**
+
+```bash
+npx skills add ssheleg/sheleg-dev
+```
+
+**Whole family at once:**
+
+```bash
+npx --yes sshlg-skills@latest update
+```
+
+Restart your agent afterwards — skills load at session start.
+
+---
+
+## A note on `crypto-payments`
+
+The skill is provider-neutral on purpose. The reusable engineering — signature
+verification, idempotency, the buffer, reconciliation — is provider-shaped, and
+the invariants hold across Coinbase Commerce, NOWPayments, BTCPay and others.
+One gateway's concrete wire format lives in a reference, together with the
+compliance position on record for it.
+
+**Choosing a payment processor is a business and compliance decision, not a
+technical one.** Processors differ in licensing, AML programme and sanctions
+exposure, and that standing changes. This pack tells you how to integrate one
+correctly. It does not tell you which one to trust.
+
+---
+
+## Verify
+
+```bash
+python3 test/validate.py
+```
+
+One version across `package.json`, `plugin.json`, `marketplace.json` and the top
+`CHANGELOG` entry; front matter inside the Agent Skills limits (over-long front
+matter does not error — hosts truncate it silently, which is worse); and
+`SKILL.md` ↔ `references/` agreement in **both** directions, so neither a
+dangling link nor a file nobody loads can ship.
+
+CI plants a defect against every one of those guards and requires the validator
+to fail. A green from a check nobody has watched fail is not evidence.
+
+---
+
+## License
+
+MIT © ssheleg

package/SECURITY.md

@@ -0,0 +1,63 @@
+# Security
+
+## What this skill actually does on your machine
+
+`sheleg-dev` is documentation plus one small Python script. Installed, it is:
+
+| Component | Runtime behavior |
+|---|---|
+| `SKILL.md` + `references/*.md` | Text. Read by the agent, executes nothing. |
+| `scripts/page_audit.py` | Runs only when you or the agent invokes it. Python **standard library only** — no dependencies, no install step. |
+| `commands/`, `cursor/rules/` | Text read by the host agent. |
+| `bin/sheleg-dev.js` (npm installer) | Copies the skill directory and the slash command into `~/.claude/`. No network, no post-install script. |
+
+There is no telemetry, no analytics, no phone-home, and nothing writes outside
+the paths above.
+
+## Network behavior of `page_audit.py`
+
+- Plain `GET` requests, **http and https only** — any other scheme (`file://`,
+  `ftp://`, `gopher://`, …) is refused before a request is made, and a redirect
+  that leaves http(s) is refused too.
+- Only to URLs **you** pass via `--url` / `--url-list`. In `--file` mode it makes
+  no requests at all, which is how the test suite runs.
+- No cookies, no credentials, no auth headers; a plain User-Agent that identifies
+  the tool.
+- Bounded: `--timeout` (default 20s) and `--max-bytes` (default 5 MB). A declared
+  content type that is not HTML/XHTML/XML is refused rather than parsed.
+- Read-only: results go to stdout. The script never writes a file. The only files
+  it ever **reads** are the two you name yourself (`--file`, `--url-list`).
+
+## What the skill will not tell an agent to do
+
+The audit procedure is explicitly **defensive**. Manipulative tactics —
+cloaking, fabricated consensus networks, review manipulation, click-signal
+spoofing, takedown abuse — appear only in `references/threats-and-defense.md`,
+written as *detect and withstand*, and the skill's non-negotiables forbid
+recommending them.
+
+The procedure is also read-only by default: it will not submit forms, request
+indexing, disavow links or change a live property without explicit approval in
+the session.
+
+## Reporting a problem
+
+Open an issue at <https://github.com/ssheleg/sheleg-dev/issues>. If it is
+sensitive, say so in the issue without the details and a private channel will be
+arranged.
+
+## Verifying for yourself
+
+```bash
+git clone https://github.com/ssheleg/sheleg-dev && cd sheleg-dev
+python3 test/validate.py         # structure, version sync, references, links, anchors
+python3 test/test_page_audit.py  # auditor behavior, offline fixtures + scheme guard
+grep -rnE "urlopen|build_opener|opener\.open|socket|subprocess|os\.system|\beval\(|\bexec\(|\bopen\(" \
+  plugins/sheleg-dev/skills/sheleg-dev/scripts/page_audit.py
+```
+
+The last command prints the auditor's entire I/O surface — six lines: the
+`urllib.request` import, one comment, the opener that carries the scheme guard,
+the one `opener.open(...)` call, and the two `open()` calls that read the file
+paths you pass on the command line. No `subprocess`, no `os.system`, no `eval`,
+no `exec`, no raw sockets. Everything else in `plugins/` is markdown.

package/bin/sheleg-dev.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/*
+ * sheleg-dev installer CLI.
+ *
+ * Installs every sheleg-dev skill into ~/.claude/skills/<name>
+ * (same layout as install.sh). Idempotent: an existing install is skipped unless
+ * --force. Zero dependencies.
+ *
+ * For other agents (Cursor, Codex, 70+) use: npx skills add ssheleg/sheleg-dev
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const REPO = 'ssheleg/sheleg-dev';
+
+function usage() {
+  console.log(`sheleg-dev installer
+
+Usage:
+  npx @ssheleg/sheleg-dev [--force]   install all sheleg-dev skills
+                                       into ~/.claude (skip existing unless --force)
+  npx @ssheleg/sheleg-dev --help
+
+Other install paths:
+  Claude Code plugin:  /plugin marketplace add ${REPO}
+                       /plugin install sheleg-dev@sheleg-dev
+  Any agent (70+):     npx skills add ${REPO}`);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function installOne(label, src, dest, isDir, force) {
+  if (fs.existsSync(dest) && !force) {
+    console.log(`skip: ${label} already installed at ${dest} (rerun with --force to overwrite)`);
+    return;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (isDir) copyDir(src, dest);
+  else fs.copyFileSync(src, dest);
+  console.log(`Installed ${label} -> ${dest}`);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    usage();
+    return 0;
+  }
+  const force = args.includes('--force');
+  const unknown = args.filter((a) => a !== '--force');
+  if (unknown.length) {
+    console.error(`unknown argument(s): ${unknown.join(' ')}`);
+    usage();
+    return 2;
+  }
+
+  const skillsRoot = path.join(ROOT, 'plugins/sheleg-dev/skills');
+  if (!fs.existsSync(skillsRoot)) {
+    console.error(`error: skill sources missing at ${skillsRoot} — corrupted package?`);
+    return 1;
+  }
+
+  const names = fs
+    .readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  if (!names.length) {
+    console.error(`error: no skills found under ${skillsRoot} — corrupted package?`);
+    return 1;
+  }
+
+  const home = os.homedir();
+  for (const name of names) {
+    installOne(
+      `${name} skill`,
+      path.join(skillsRoot, name),
+      path.join(home, '.claude', 'skills', name),
+      true,
+      force
+    );
+  }
+  return 0;
+}
+
+process.exit(main(process.argv));

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ssheleg/sheleg-dev",
+  "version": "0.4.0",
+  "description": "Six integration skills for the layer a product reaches once it has users: Stripe subscription billing, crypto payments, ad and conversion tracking under Consent Mode v2, Google sign-in and the wider Google auth surface, and Core Web Vitals. This package is the installer CLI.",
+  "bin": {
+    "sheleg-dev": "bin/sheleg-dev.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "plugins",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "repository": "github:ssheleg/sheleg-dev",
+  "homepage": "https://github.com/ssheleg/sheleg-dev",
+  "license": "MIT",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "subscriptions",
+    "stripe-billing",
+    "stripe",
+    "crypto-payments",
+    "webhooks",
+    "google-analytics",
+    "consent-mode",
+    "meta-pixel",
+    "google-auth",
+    "oauth2",
+    "core-web-vitals",
+    "claude-code",
+    "cursor",
+    "skill"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "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.",
+  "version": "0.4.0",
+  "author": {
+    "name": "ssheleg",
+    "url": "https://x.com/sshlg93"
+  },
+  "homepage": "https://github.com/ssheleg/sheleg-dev",
+  "repository": "https://github.com/ssheleg/sheleg-dev",
+  "license": "MIT",
+  "keywords": [
+    "stripe",
+    "subscriptions",
+    "stripe-billing",
+    "crypto-payments",
+    "webhooks",
+    "google-analytics",
+    "consent-mode",
+    "meta-pixel",
+    "google-auth",
+    "oauth2",
+    "core-web-vitals",
+    "claude-code",
+    "cursor"
+  ]
+}