@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/rust-testing/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: rust-testing
+description: Writing and organising tests for Rust crates with cargo test, covering #[cfg(test)] unit modules, integration tests under tests/, doc tests, trait-based fakes and mockall, property tests with proptest, #[tokio::test] for async code, and the cargo test flags for filtering and output. Use when adding or fixing Rust tests, deciding where a test belongs in a crate, testing async or I/O-bound Rust code, or getting a flaky cargo test run under control.
+license: MIT
+compatibility: Any Agent Skills host. Needs a Rust toolchain with cargo. proptest, mockall and tokio are used only if the project already depends on them or the user agrees to add them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "cargo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Rust testing
+
+Put each test where it can see exactly what it needs, keep it deterministic, and prove it with a `cargo test` run.
+
+## 0. Before you write a test
+
+1. Read `Cargo.toml` `[dev-dependencies]`: which of `proptest`, `mockall`, `tokio` (with which features), `tempfile`, `insta`, `rstest` are already there. Use those. **Ask the user** before adding a new dev-dependency.
+2. Check how CI runs tests (`.github/workflows/`, `Makefile`, `justfile`): plain `cargo test`, `cargo nextest run`, feature flags, `--workspace`. Use the same command.
+3. Run the existing suite once and record the result. If it already fails, **stop and tell the user** which tests fail before you change anything.
+
+## 1. Choose where the test goes
+
+| Testing | Put it in | Can see |
+|---|---|---|
+| One function or private helper | `#[cfg(test)] mod tests` at the bottom of the same file | Private items via `use super::*;` |
+| The crate's public API, as a user would call it | `tests/<feature>.rs` (each file is its own crate) | Only `pub` items |
+| A usage example in the docs | A fenced code block in the item's `///` doc comment | Only `pub` items |
+| A binary's behaviour end to end | `tests/cli.rs`, running the binary (for example with `assert_cmd` if present) | Process output |
+
+- Binary crates: integration tests can't import `main.rs`. Move logic into `src/lib.rs` and keep `main.rs` thin.
+- Shared integration helpers go in `tests/common/mod.rs` (not `tests/common.rs`, which cargo would run as its own test crate), pulled in with `mod common;`.
+
+## 2. Unit tests
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_port_from_host_string() {
+        assert_eq!(parse_port("localhost:8080"), Ok(8080));
+    }
+
+    #[test]
+    fn rejects_missing_port() {
+        let err = parse_port("localhost").unwrap_err();
+        assert!(matches!(err, ParseError::MissingPort));
+    }
+
+    #[test]
+    fn reads_port_from_config_text() -> Result<(), Box<dyn std::error::Error>> {
+        let config: Config = "port = 8080".parse()?;
+        assert_eq!(config.port, 8080);
+        Ok(())
+    }
+
+    #[test]
+    #[should_panic(expected = "capacity must be non-zero")]
+    fn zero_capacity_panics() {
+        RingBuffer::<u8>::new(0);
+    }
+}
+```
+
+- Name tests after the behaviour (`rejects_missing_port`), not `test1`.
+- Assert on the specific error variant with `matches!` instead of comparing `Debug` strings.
+- Use `#[should_panic(expected = "...")]` only for documented panics; give the expected text so an unrelated panic doesn't pass.
+- Tests may return `Result<(), E>` to use `?`; in tests, `unwrap()` and `expect()` are fine.
+
+## 3. Doc tests
+
+- Every public function with a non-obvious use gets an example. Doc tests compile and run with `cargo test` (`cargo test --doc` for only these).
+- Use `?` in examples by ending with `# Ok::<(), Box<dyn std::error::Error>>(())`; lines starting with `# ` are hidden from the rendered docs.
+- Mark examples `no_run` when they need network or files, `compile_fail` to prove misuse doesn't compile, `ignore` only with a written reason.
+- Doc tests run only for library targets. `cargo nextest` does not run doc tests, so CI that uses nextest needs a separate `cargo test --doc` step.
+
+## 4. Fakes and mocks via traits
+
+Rust has no runtime monkey-patching. Make the boundary a trait and inject it.
+
+1. Define a small trait for the external dependency (clock, HTTP client, repository).
+2. Make the code under test generic over it (`struct Service<R: Repo>`) or take `&dyn Repo` / `Arc<dyn Repo>`.
+3. In tests, prefer a hand-written fake (an in-memory `HashMap` store) for state; use `mockall` (`#[cfg_attr(test, mockall::automock)]` on the trait) when you must assert on calls.
+4. Never mock the type under test, and never mock pure functions you could just call.
+
+Examples for fakes, mockall expectations and time control: `references/fakes-proptest-async.md`.
+
+## 5. Property tests with proptest
+
+Use them for parsers, encoders, data structures and anything with an invariant ("decode(encode(x)) == x", "sorted output is a permutation of input").
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn round_trips(s in "\\PC*") {
+        prop_assert_eq!(decode(&encode(&s)).unwrap(), s);
+    }
+}
+```
+
+- Use `prop_assert!` / `prop_assert_eq!` inside `proptest!` so failures shrink.
+- Commit the `proptest-regressions/` files it writes; they replay past failures.
+
+## 6. Async tests
+
+- `#[tokio::test]` runs on a current-thread runtime. Use `#[tokio::test(flavor = "multi_thread", worker_threads = 2)]` only when the code needs real parallelism (for example it calls `block_in_place`).
+- `#[tokio::test]` needs tokio's `macros` and `rt` features for the test target (`[dev-dependencies] tokio = { ..., features = ["macros", "rt"] }`); the `multi_thread` flavor also needs `rt-multi-thread`.
+- Don't sleep for real. With the `test-util` feature, `#[tokio::test(start_paused = true)]` and `tokio::time::advance` make timers instant and deterministic.
+- Wrap anything that could hang in `tokio::time::timeout` so a bug fails the test instead of stalling CI.
+
+## 7. Running tests
+
+| Goal | Command |
+|---|---|
+| Everything in a workspace | `cargo test --workspace --all-features` |
+| Tests whose name contains a string | `cargo test parse_port` |
+| One integration test file | `cargo test --test cli` |
+| Only unit tests in the library | `cargo test --lib` |
+| Only doc tests | `cargo test --doc` |
+| Exact name match (full module path) | `cargo test -- --exact parser::tests::parses_port_from_host_string` |
+| Show `println!` output | `cargo test -- --nocapture` |
+| Run serially (shared global state) | `cargo test -- --test-threads=1` |
+| Run ignored (slow) tests | `cargo test -- --ignored` or `-- --include-ignored` |
+| Keep going after a failing test crate | `cargo test --no-fail-fast` |
+
+Flags before `--` go to cargo; flags after `--` go to the test binary.
+
+## 8. Flaky tests
+
+1. Run the test alone and in a loop to reproduce: `for i in $(seq 50); do cargo test name -- --exact || break; done`.
+2. Common causes: tests sharing a file path, port, env var or global (run in parallel threads); real time; `HashMap` iteration order; unseeded randomness.
+3. Fix the cause: `tempfile::tempdir()` per test, bind port `0`, pass config instead of reading env vars, sort before asserting. `--test-threads=1` is a diagnostic, not a fix.
+
+## Never
+
+- Never delete, `#[ignore]` or weaken an existing test to make the suite pass without the user's agreement.
+- Never let tests touch the real network, the user's home directory or shared databases.
+- Never assert on `format!("{:?}", ...)` output when a structured comparison is possible.
+
+## Report back
+
+End with: tests added or changed (names and files), the exact command you ran, pass/fail counts, and anything not covered.

package/skills/rust-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add unit tests for the tokenizer module in my Rust crate",
+    "How do I mock the HTTP client trait in Rust so my service tests don't hit the network?",
+    "My #[tokio::test] hangs forever when the retry backoff sleeps, how do I test it without waiting?",
+    "Where should integration tests go in a Rust library and how do I share helpers between them?",
+    "Write a proptest that checks my Rust serializer round-trips arbitrary input"
+  ],
+  "should_not_trigger": [
+    "Refactor this Rust module to return thiserror errors instead of String",
+    "My Rust tests don't compile anymore after bumping tokio, error E0277 future is not Send",
+    "Review my Rust diff for blocking calls inside async functions",
+    "Write pytest fixtures for the Django user model",
+    "Set up Playwright end-to-end tests for the checkout flow"
+  ]
+}

package/skills/rust-testing/references/fakes-proptest-async.md

@@ -0,0 +1,113 @@
+# Fakes, mockall, proptest strategies and async time
+
+Read this when a test needs a test double, a custom proptest strategy, or control over time.
+
+## Hand-written fake
+
+```rust
+pub trait Repo {
+    fn get(&self, id: u64) -> Result<Option<User>, RepoError>;
+    fn save(&self, user: &User) -> Result<(), RepoError>;
+}
+
+#[cfg(test)]
+#[derive(Default)]
+struct FakeRepo {
+    users: std::sync::Mutex<std::collections::HashMap<u64, User>>,
+}
+
+#[cfg(test)]
+impl Repo for FakeRepo {
+    fn get(&self, id: u64) -> Result<Option<User>, RepoError> {
+        Ok(self.users.lock().unwrap().get(&id).cloned())
+    }
+    fn save(&self, user: &User) -> Result<(), RepoError> {
+        self.users.lock().unwrap().insert(user.id, user.clone());
+        Ok(())
+    }
+}
+```
+
+A fake keeps real behaviour (what you save, you can read back), so tests check outcomes instead of call sequences. Prefer it over a mock whenever state is involved.
+
+## mockall
+
+```rust
+#[cfg_attr(test, mockall::automock)]
+pub trait Mailer {
+    fn send(&self, to: &str, body: &str) -> Result<(), MailError>;
+}
+
+#[test]
+fn sends_welcome_mail_once() {
+    let mut mailer = MockMailer::new();
+    mailer
+        .expect_send()
+        .withf(|to, _| to == "ama@example.com")
+        .times(1)
+        .returning(|_, _| Ok(()));
+
+    signup(&mailer, "ama@example.com").unwrap();
+}
+```
+
+- Expectations are checked when the mock is dropped; an unmet `times(1)` fails the test.
+- Keep `mockall` in `[dev-dependencies]` and gate `automock` with `cfg_attr(test, ...)` so it never reaches release builds.
+- If a mock needs more than three expectations, the unit is probably doing too much; consider a fake or a smaller seam.
+
+## Injecting time
+
+```rust
+pub trait Clock { fn now(&self) -> std::time::SystemTime; }
+
+struct FixedClock(std::time::SystemTime);
+impl Clock for FixedClock { fn now(&self) -> std::time::SystemTime { self.0 } }
+```
+
+Pass the clock into the code under test rather than calling `SystemTime::now()` inside it.
+
+## proptest strategies
+
+```rust
+use proptest::prelude::*;
+
+fn order() -> impl Strategy<Value = Order> {
+    (1u32..1000, prop::collection::vec("[a-z]{1,8}", 0..10))
+        .prop_map(|(qty, tags)| Order { qty, tags })
+}
+
+proptest! {
+    #![proptest_config(ProptestConfig::with_cases(512))]
+
+    #[test]
+    fn order_round_trips_through_text(o in order()) {
+        prop_assert_eq!(o.to_string().parse::<Order>().unwrap(), o);
+    }
+}
+```
+
+- Derive strategies for your own types with `prop_map` or, if the project uses it, `#[derive(Arbitrary)]` from `proptest-derive`.
+- Use `prop_assume!` sparingly; filtering too many cases makes proptest give up.
+
+## Async time control (tokio `test-util` feature)
+
+```rust
+#[tokio::test(start_paused = true)]
+async fn retries_after_backoff() {
+    let handle = tokio::spawn(fetch_with_retry());
+    tokio::time::advance(std::time::Duration::from_secs(5)).await;
+    assert!(handle.await.unwrap().is_ok());
+}
+```
+
+With time paused, the runtime auto-advances to the next timer when every task is idle, so `sleep`-based code completes instantly and deterministically.
+
+## Temporary files
+
+```rust
+let dir = tempfile::tempdir()?;           // removed when `dir` is dropped
+let path = dir.path().join("config.toml");
+std::fs::write(&path, "port = 8080")?;
+```
+
+Never write test files into the repository tree or a fixed path in `/tmp`.

package/skills/search-first/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: search-first
+description: Reuse-before-build check that runs before writing any new helper, utility, component or integration. Searches the current codebase for an existing function or pattern, then the project's installed dependencies and the standard library, then the package ecosystem, and weighs reuse, extend or build on fit, maintenance, licence, size and security before any code is written. Use when about to add a new function, module, wrapper or dependency, when the user asks "do we already have something for this" or "is there a library for X", or when a task smells like a solved problem (parsing, retries, dates, validation, caching).
+license: MIT
+compatibility: Any Agent Skills host. Ecosystem search needs network access and the project's package manager.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Search first
+
+The cheapest code is code that already exists and is already tested. Spend a few minutes searching before writing anything new. Go outward in rings, and stop at the first ring that has a good fit.
+
+## Ring 1: this codebase
+
+1. Name the capability in a few ways: the verb and the noun ("retry", "backoff", "withRetry", "attempts"), domain words, and likely file names (`utils`, `helpers`, `lib`, `common`, `shared`).
+2. Search the code for each term, and for call sites of similar behaviour (for example search for `setTimeout` near `catch` when looking for retries).
+3. Check shared packages in a monorepo (`packages/`, `libs/`) and internal SDKs.
+4. Look at how neighbouring features solved the same problem. A local convention beats a better-in-theory approach.
+
+If you find something close: use it as is, or extend it in place (add a parameter, generalise carefully, add a test). Don't fork a near-copy.
+
+## Ring 2: what's already installed
+
+1. Read the dependency manifest (`package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`, `*.csproj`, `pubspec.yaml`).
+2. Check whether an installed library already does this (lodash, date libraries, validation libraries, HTTP clients with retry support, framework helpers).
+3. Check the language's standard library and the platform: many "helpers" are one built-in call (`structuredClone`, `Intl.DateTimeFormat`, `AbortSignal.timeout`, Python `itertools` and `functools`, Go `slices` and `maps`).
+
+## Ring 3: the ecosystem
+
+Only when rings 1 and 2 have nothing:
+
+1. Search the package registry for the language and the official docs of the framework in use.
+2. Shortlist at most three candidates and check each against the table below. Use the registry page and the repository, not memory.
+
+| Check | Look at | Red flag |
+|---|---|---|
+| Fit | README, API docs | Needs heavy wrapping to do your one job |
+| Maintenance | Last release, open issues, response to issues | No release in years with open bugs, archived repo |
+| Adoption | Download counts, dependents | Tiny usage for a critical path |
+| Licence | Licence file | Incompatible with the project (ask if unsure) |
+| Size and deps | Install size, transitive dependencies | Large tree for a small job |
+| Security | Advisories (`npm audit`, `pip-audit`, `cargo audit`, GitHub advisories) | Unpatched advisories, typo-squat names |
+
+## Decide
+
+Pick one, and say why in one or two lines:
+
+- **Reuse**: an existing internal or installed option fits. Best default.
+- **Extend**: an internal one almost fits. Change it in place, with a test.
+- **Adopt**: a new dependency is clearly worth it. **Ask the user before adding any dependency**, and respect project rules (some repos forbid new dependencies in some folders).
+- **Build**: nothing fits, or the job is a few lines and a dependency would cost more than it saves. Write the minimum, following local conventions, with a test.
+
+## Report
+
+Before writing code, state:
+
+```
+Need: <capability>
+Searched: <terms and places>, installed deps, stdlib, <registry if used>
+Found: <path or package, or "nothing suitable">
+Decision: reuse | extend | adopt | build, because <reason>
+```
+
+## Never
+
+- Never add a dependency without the user's approval.
+- Never copy-paste a near-duplicate of an existing helper.
+- Never pick a package by name or popularity alone without checking its repository.
+- Never let the search turn into a research project: for a few-line helper, a couple of minutes is enough.

package/skills/search-first/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "I need a retry-with-backoff helper for our API client, do we already have something like that?",
+    "Before you write a new slugify function, check the repo and our dependencies for one",
+    "Is there an existing library for parsing ISO 8601 durations or should we write our own?",
+    "Add CSV export to the reports page but reuse whatever we already have instead of writing from scratch"
+  ],
+  "should_not_trigger": [
+    "Audit our dependencies for known vulnerabilities and outdated packages",
+    "Research and compare three managed message brokers for our architecture decision, with citations",
+    "Refactor the duplicated validation code in the checkout module without changing behaviour",
+    "Find where the session timeout is configured in this app"
+  ]
+}

package/skills/security-review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: security-review
+description: Security review of a code change or module covering secrets, injection, authentication and authorization, input validation, data exposure, dependencies and unsafe configuration, with findings ranked by severity and concrete fixes. Use when the user asks for a security review, audit or vulnerability check, or before shipping code that handles auth, payments, user input, files or personal data.
+license: MIT
+compatibility: Any Agent Skills host. The secret scanner needs Node 18+ and git.
+metadata:
+  kete-loom/version: "0.1.2"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/requires: "git, node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Security review
+
+Find real, exploitable problems in the code in front of you and explain how to fix them. This skill is **read-only**: report findings, and change code only if the user asks.
+
+## 1. Set the scope
+
+- Default scope is the current change: `git diff <base>...HEAD` plus uncommitted work. If the user names files or a module, review that instead.
+- Identify the trust boundaries the code touches: HTTP handlers, CLI args, file uploads, webhooks, queues, database, third-party APIs, LLM prompts.
+
+## 2. Scan for secrets first
+
+Run the scanner from the root of the repo being reviewed, pointing at this skill's folder (`<skill-dir>` is the folder holding this SKILL.md):
+
+```
+node <skill-dir>/scripts/scan-secrets.js            # changed files vs. HEAD and staged work
+node <skill-dir>/scripts/scan-secrets.js --all      # every tracked file
+```
+
+Treat any hit as **critical** until shown to be a test fixture or placeholder. If a real secret was committed, tell the user it must be **rotated**: removing it from the code is not enough, because it stays in git history.
+
+## 3. Walk the checklist
+
+Read `references/checklist.md` and apply each section that matches the code in scope. The essentials:
+
+1. **Injection**: SQL/NoSQL built with string concatenation, shell commands with user input, template injection, path traversal (`../`), SSRF in URL fetchers, prompt injection where user text reaches an LLM with tool access.
+2. **AuthN / AuthZ**: every sensitive route checks the session *and* that this user may act on this specific resource (no IDOR). Password hashing uses bcrypt/scrypt/argon2. Tokens expire.
+3. **Input validation**: validated at the boundary with a schema; size limits on bodies and uploads; file type checked by content, not just extension.
+4. **Data exposure**: no secrets, tokens, PII or stack traces in logs, errors or API responses; least-privilege queries (no `SELECT *` sent to clients).
+5. **Web**: CSRF protection on cookie-authenticated mutations, output encoding (XSS), strict CORS, security headers, secure cookie flags.
+6. **Payments and webhooks**: signatures verified on the raw body, amounts computed server-side, idempotency on retries.
+7. **Dependencies**: run the ecosystem's audit (`npm audit`, `pip-audit`, `govulncheck`, `cargo audit`) if available; flag new dependencies that are unmaintained or unpinned.
+8. **Config**: debug mode off in production, no default credentials, secrets read from the environment or a secret manager.
+
+Trace each suspicious input from where it enters to where it is used before calling it a finding. No path from untrusted input means no finding.
+
+## 4. Report
+
+Order findings by severity: **Critical** (exploitable now, data or money at risk), **High**, **Medium**, **Low**. For each finding give:
+
+- **Where:** `file:line`
+- **What:** one sentence on the flaw.
+- **Exploit:** how an attacker would trigger it.
+- **Fix:** a concrete code change.
+
+Finish with what you checked and found clean, and anything you couldn't assess (for example infrastructure you can't see). Don't pad the report with generic advice; if the change is clean, say so.

package/skills/security-review/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Review my last commit for security vulnerabilities",
+    "Audit the login and password reset handlers before we go live",
+    "Did I accidentally commit any API keys or secrets in this branch?",
+    "Check this file upload endpoint for injection or path traversal issues"
+  ],
+  "should_not_trigger": [
+    "Run all the checks on my branch before I open a pull request",
+    "Explain the difference between authentication and authorization",
+    "Speed up this slow database query",
+    "Add a password strength meter to the signup form UI"
+  ]
+}

package/skills/security-review/references/checklist.md

@@ -0,0 +1,54 @@
+# Security review checklist
+
+Apply the sections that match the code in scope. Each item is a question; a "no" is a candidate finding to trace and confirm.
+
+## Secrets
+- Are all keys, tokens and passwords read from the environment or a secret manager?
+- Are `.env` files and key files listed in `.gitignore`?
+- Do test fixtures use obviously fake values?
+
+## Injection
+- Are all database queries parameterised (placeholders or ORM query builders, no string concatenation)?
+- Is user input ever passed to a shell? If so, is it passed as an argument array, never through a shell string?
+- Are file paths built from user input normalised and checked to stay inside an allowed directory?
+- Do server-side URL fetches restrict scheme and host (SSRF), and block private and metadata IP ranges?
+- Do templates auto-escape? Is any `dangerouslySetInnerHTML`, `v-html`, `|safe` or `innerHTML` fed user data?
+- Can user-supplied text reach an LLM that can call tools or read private data? Is the tool scope limited?
+
+## Authentication
+- Are passwords hashed with argon2, scrypt or bcrypt (never plain SHA/MD5)?
+- Do sessions and tokens expire, and are they invalidated on logout and password change?
+- Is login rate-limited? Do responses avoid revealing whether an account exists?
+- Are JWTs verified with a fixed algorithm (no `alg: none`, no algorithm taken from the token)?
+
+## Authorization
+- Does every handler that reads or changes a resource check that *this* user may access *this* resource (not only that they are logged in)?
+- Are admin routes protected server-side, not just hidden in the UI?
+- Are mass-assignment risks handled (only allowed fields copied from the request)?
+
+## Input validation
+- Is every external input validated against a schema at the boundary?
+- Are there limits on body size, upload size, array length and pagination size?
+- Are uploaded files checked by content type and stored outside the web root with generated names?
+
+## Data exposure
+- Do logs exclude passwords, tokens, card data and personal data?
+- Do error responses hide stack traces and internal details in production?
+- Do API responses return only the fields the client needs?
+
+## Web
+- Are cookie-authenticated state changes protected against CSRF?
+- Are cookies `HttpOnly`, `Secure` and `SameSite`?
+- Is CORS restricted to known origins (no `*` with credentials)?
+- Are security headers set (CSP, HSTS, X-Content-Type-Options, frame-ancestors)?
+
+## Payments and webhooks
+- Is every webhook signature verified against the raw request body with a constant-time comparison?
+- Are amounts and prices computed on the server, never trusted from the client?
+- Is payment status confirmed with the provider's verify API before value is given?
+- Are webhook handlers idempotent (the same event processed twice has no extra effect)?
+
+## Dependencies and config
+- Does the dependency audit pass, or are remaining issues justified?
+- Are new dependencies maintained and pinned in a lockfile?
+- Is debug mode off and are default credentials removed in production config?

package/skills/security-review/scripts/scan-secrets.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+// Lightweight secret scanner. Read-only.
+//   node scan-secrets.js         changed + staged + untracked files (vs HEAD)
+//   node scan-secrets.js --all   every tracked file
+//   node scan-secrets.js <file>  specific files
+// Exit code 1 if anything is found. Values are masked in the output.
+
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const RULES = [
+  ['AWS access key', /\b(AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ['GitHub token', /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{60,}\b/],
+  ['Anthropic API key', /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
+  ['OpenAI API key', /\bsk-(proj-)?[A-Za-z0-9_-]{32,}\b/],
+  ['Paystack secret key', /\bsk_(live|test)_[a-f0-9]{40}\b/],
+  ['Stripe live key', /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/],
+  ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['Private key block', /-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ['JWT', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/],
+  ['Connection string with password', /\b(postgres(ql)?|mysql|mongodb(\+srv)?|redis|amqp):\/\/[^\s:@/]+:[^\s@/]{3,}@/i],
+  ['Hard-coded secret assignment', /\b(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\b["']?\s*[:=]\s*["'][^"'\s]{8,}["']/i],
+];
+
+const PLACEHOLDER = /(example|placeholder|changeme|your[_-]|xxxx|dummy|fake|<[^>]+>|\$\{|process\.env|os\.environ)/i;
+const SKIP_FILE = /(\.lock$|lock\.json$|\.min\.js$|\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf)$)/i;
+
+function git(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return '';
+  }
+}
+
+function files(argv) {
+  const explicit = argv.filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit;
+  if (argv.includes('--all')) return git(['ls-files']).split('\n').filter(Boolean);
+  const changed = [
+    // --relative: diff paths are repo-root based by default; ls-files is cwd based
+    ...git(['diff', '--name-only', '--relative', 'HEAD']).split('\n'),
+    ...git(['diff', '--name-only', '--relative', '--cached']).split('\n'),
+    ...git(['ls-files', '--others', '--exclude-standard']).split('\n'),
+  ];
+  return [...new Set(changed.filter(Boolean))];
+}
+
+function mask(s) {
+  return s.length <= 8 ? '****' : `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`;
+}
+
+const hits = [];
+for (const file of files(process.argv.slice(2))) {
+  if (SKIP_FILE.test(file) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) continue;
+  if (fs.statSync(file).size > 1_000_000) continue;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  lines.forEach((line, i) => {
+    const seen = new Set();
+    for (const [label, re] of RULES) {
+      const m = re.exec(line);
+      // Check the match, not the line: `process.env.KEY || "sk_live_..."` is still a leak.
+      if (!m || PLACEHOLDER.test(m[0]) || seen.has(m[0])) continue;
+      seen.add(m[0]); // most specific rule wins (rules are ordered specific-first)
+      hits.push({ file, line: i + 1, rule: label, match: mask(m[0]) });
+    }
+  });
+}
+
+if (!hits.length) {
+  console.log('No likely secrets found.');
+} else {
+  for (const h of hits) console.log(`${h.file}:${h.line}  ${h.rule}  ${h.match}`);
+  console.log(`\n${hits.length} possible secret(s). Confirm each; rotate any real secret that was committed.`);
+  process.exitCode = 1;
+}