cloak-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{cloak_cli-0.2.0 → cloak_cli-0.3.0}/.github/workflows/ci.yml

@@ -6,6 +6,11 @@ on:
   pull_request:
     branches: [main]
 
+env:
+  # Opt into Node 24 runtime for actions; silences deprecation warnings ahead of
+  # the June 2026 default cutover.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -14,10 +19,10 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip

{cloak_cli-0.2.0 → cloak_cli-0.3.0}/.github/workflows/release.yml

@@ -24,14 +24,17 @@ on:
     tags:
       - "v*"
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
 
@@ -43,7 +46,7 @@ jobs:
       - name: Build sdist + wheel
         run: python -m build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: dist
           path: dist/
@@ -59,7 +62,7 @@ jobs:
     permissions:
       id-token: write   # required for Trusted Publisher (OIDC)
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v5
         with:
           name: dist
           path: dist/

cloak_cli-0.3.0/.pre-commit-hooks.yaml

@@ -0,0 +1,35 @@
+# pre-commit hook definitions for CLOAK.
+#
+# Add to your .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/newtophilly/cloak
+#       rev: v0.2.0
+#       hooks:
+#         - id: cloak-scan
+#
+# See https://pre-commit.com for general pre-commit setup.
+
+- id: cloak-scan
+  name: cloak scan
+  description: >-
+    Find secrets and proprietary markers in code before commit. Wraps detect-secrets and
+    layers in policy.secret_rules from .cloakpolicy. Exits 1 on findings (blocks commit).
+  entry: cloak scan
+  language: python
+  pass_filenames: false
+  args: ["."]
+  always_run: true
+  stages: [pre-commit]
+
+- id: cloak-context-preview
+  name: cloak context (preview only)
+  description: >-
+    Render a redacted markdown view of the repo. Useful as a manual check that the redaction
+    output looks right. Does not block commits — `stages: [manual]` means run only when you
+    invoke it explicitly: `pre-commit run cloak-context-preview --hook-stage manual`.
+  entry: cloak context
+  language: python
+  pass_filenames: false
+  args: [".", "--json"]
+  stages: [manual]

cloak_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+Notable changes by release. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-05-08
+
+- Added `cloak diff-context` — preview what `cloak context` would redact, with per-file counts of function bodies, proprietary tables, docstrings stripped (under `--strict`), and byte reduction. No files written; pure dry-run for trust. JSON output supported.
+- README softened the pre-release framing — version numbers (0.x) already signal early-stage; "alpha software" copy was overcorrecting.
+
+## [0.2.1] — 2026-05-08
+
+- Added `.pre-commit-hooks.yaml` so teams can drop `cloak-scan` into their `.pre-commit-config.yaml` and have it gate commits.
+- Added `examples/python-pricing-engine/` (with a real pytest suite, so `--verify "pytest"` actually runs) and `examples/js-api-client/`. Each ships with its own `.cloakpolicy`.
+- README now points at the examples and shows the pre-commit setup.
+
+## [0.2.0] — 2026-05-08
+
+Feature matrix complete: every command now works for both Python and JS/TS.
+
+- Added JS/TS support to `cloak obfuscate`. Per-file rename of module-level `_names` (functions, classes, generator functions, simple `const`/`let`/`var` bindings) using tree-sitter. Skips dunder-like names, all-underscore names, and anything in `policy.public_api`. Property access, shorthand object properties, and destructuring patterns are deliberately not renamed in v1 — they'd silently change object shapes.
+- A mixed Python+JS repo now obfuscates in one pass with one manifest and one verify command.
+
+## [0.1.2] — 2026-05-08
+
+- Added `cloak policy init` — interactive wizard that detects project layout (Python / Node / TypeScript / common src directories) and scaffolds a sensible `.cloakpolicy`. Supports `--yes` (non-interactive), `--force` (overwrite), `--out` (custom path).
+- New `cloak policy ...` subcommand group; more policy commands will go here.
+
+## [0.1.1] — 2026-05-08
+
+- Added JS/TS support to `cloak context` via tree-sitter. Supported extensions: `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`. Function/method/arrow bodies and module-level `UPPER_SNAKE_CASE` object/array constants get redacted; type definitions and signatures are preserved. Output is byte-spliced into the original source so formatting and surrounding comments survive.
+
+## [0.1.0] — 2026-05-08
+
+First tagged alpha. All three headline commands are functional for Python.
+
+- `cloak scan`: wraps `detect-secrets` and layers in `policy.secret_rules`. Returns severity / file / line / rule_id / redacted preview / suggested action. Raw secrets never appear in output. Exit 1 on findings, 0 clean.
+- `cloak context` (Python): AST-based redactor. Function bodies → `...`, module-level `UPPER_SNAKE` dict/list/set/tuple constants → `...`. Imports, class shapes, signatures, docstrings preserved. `--strict` aliases enum values and strips docstrings (justified by the Phase 0 adversarial probe). `--out`, `--copy`, `--json` all supported.
+- `cloak obfuscate` (Python): renames module-private `_names` skipping `policy.public_api` and dunders; optional docstring stripping per policy. Writes `cloak-manifest.json` (sha256s, rename map, full policy snapshot, verify result). `--verify "<cmd>"` gates success on the user's test suite — exit 1 if tests fail. Refuses to overwrite a non-empty output directory.
+- GitHub Actions CI (ruff format/check + mypy --strict + pytest matrix on 3.11/3.12/3.13) and a tag-triggered release workflow that publishes to PyPI via Trusted Publisher (OIDC, no stored tokens).
+- `pyproject.toml` reads version dynamically from `src/cloak/__init__.py` (single source of truth).
+- Phase 0 validation experiment documented in `docs/research/`.

{cloak_cli-0.2.0 → cloak_cli-0.3.0}/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to CLOAK
 
-Thanks for considering a contribution. CLOAK is an alpha-stage open-source project; the easiest ways to help are issues, small focused PRs, and feedback on the build plan.
+Thanks for considering a contribution. CLOAK is an early-stage open-source project (pre-1.0); the easiest ways to help are issues, small focused PRs, and feedback on the build plan.
 
 ## Development setup
 
@@ -25,7 +25,9 @@ CI will run all three. Please keep them green before opening a PR.
 
 ## What to work on
 
-Open issues are labeled by area (`scan`, `context`, `obfuscate`, `policy`, `cli`) and difficulty. New contributors should look for `good-first-issue`. The roadmap lives in [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) — read that first to understand how a piece of work fits.
+Open issues are the obvious starting point if there are any. Beyond that: [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) lists the things that work today, the known v1 limitations, and what's not started — anything in those last two buckets is fair game for a PR.
+
+If you're not sure whether a change is in scope, open an issue describing what you're thinking before sinking time into it. I'd rather discuss the shape of a PR up front than ask for a rewrite after the fact.
 
 ## Honest positioning
 
@@ -33,7 +35,7 @@ CLOAK markets itself as a **governance + friction** tool, not unbreakable protec
 
 ## Reporting security issues
 
-Please do **not** file public issues for security vulnerabilities. Open a private security advisory at https://github.com/newtophilly/cloak/security/advisories/new with details, and we'll respond as quickly as we can.
+Please don't file public GitHub issues for security vulnerabilities. Open a private security advisory at https://github.com/newtophilly/cloak/security/advisories/new — full details in [SECURITY.md](SECURITY.md).
 
 ## Releasing (maintainers)
 

{cloak_cli-0.2.0 → cloak_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloak-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Local CLI for safer LLM workflows: redact code before pasting, generate verified obfuscated copies, enforce policy from your repo.
 Project-URL: Homepage, https://github.com/newtophilly/cloak
 Project-URL: Repository, https://github.com/newtophilly/cloak
@@ -248,8 +248,10 @@ Description-Content-Type: text/markdown
 
 > Local CLI for safer LLM workflows. Redact code before pasting into ChatGPT or Claude. Generate verified obfuscated copies for sharing. Enforce policy from your repo.
 
-> [!IMPORTANT]
-> CLOAK is **alpha software** in active development. APIs and policy format may change before 1.0. The three headline commands (`scan`, `context`, `obfuscate`) are functional for Python; JS/TS support arrives in Phases 3.5 and 5. See [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md) for the roadmap.
+![demo](docs/demo.gif)
+
+> [!NOTE]
+> CLOAK is at **v0.3** — the three headline commands (`scan`, `context`, `obfuscate`) work for both Python and JS/TS, plus `diff-context` for previewing redactions. The `.cloakpolicy` format and CLI flags may still change before 1.0. See [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md) for what's shipped, the known v1 limitations, and what's not started.
 
 ## What CLOAK is
 
@@ -263,10 +265,12 @@ cloak context ./repo --out safe-context.md --copy
 cloak obfuscate ./repo --out ./repo.cloaked --verify "pytest"
 ```
 
-- **`cloak scan`** — Find secrets and proprietary markers in code (wraps `detect-secrets` / `gitleaks` and layers your policy on top).
+- **`cloak scan`** — Find secrets and proprietary markers in code (wraps `detect-secrets` and layers your policy's custom regex rules on top).
 - **`cloak context`** — Generate a redacted markdown view of a repo (function bodies hidden, signatures + docstrings kept) safe to paste into an LLM for architectural feedback. Use `--strict` to also alias enums and paraphrase docstrings.
 - **`cloak obfuscate`** — Produce a transformed copy of your code that **still passes your test suite**, for sharing with contractors or third parties. The `--verify` flag is the differentiator: if your tests don't pass against the transformed copy, the operation fails.
 
+There's also `cloak diff-context` — a dry-run that previews exactly what `cloak context` would redact (function bodies, proprietary tables, docstrings under `--strict`) and the byte reduction, without writing anything. Run it before you trust the transformation.
+
 ## Why this exists
 
 The "Shadow AI" problem is real: leadership says "don't paste code into ChatGPT" and developers do it anyway because they have deadlines. Existing solutions are either enterprise-grade network DLP (expensive, blunt, requires IT) or policy documents nobody reads.
@@ -279,7 +283,7 @@ Honest positioning matters in security tooling.
 
 - **Not unbreakable.** A motivated reader (human or LLM) given an obfuscated copy of your code can still extract logic. CLOAK reduces leak surface and creates friction; it does not provide cryptographic protection. Real protection comes from blocking, redacting, encrypting, compiling, or simply never sending the source.
 - **Not a replacement for enterprise DLP.** Network-layer enforcement (Lasso, Polymer, Cyberhaven, Prisma AIRS, etc.) operates at a different layer and is complementary. CLOAK lives in the developer's workflow, not the network egress.
-- **Not a secret scanner from scratch.** `cloak scan` wraps existing battle-tested OSS scanners (`detect-secrets`, `gitleaks`) and layers policy-aware rules on top. The reuse is intentional and disclosed.
+- **Not a secret scanner from scratch.** `cloak scan` wraps `detect-secrets` (Yelp's open-source scanner — years of regex/entropy tuning come for free) and layers your policy's `secret_rules` on top. The reuse is intentional and disclosed.
 - **Not magic for content the LLM has already seen.** Once code is sent, it's sent. CLOAK helps before paste, not after.
 
 ## Quickstart
@@ -324,6 +328,33 @@ $ cloak obfuscate src/payments --out /tmp/payments.cloaked --verify "pytest test
 $ cloak scan . --json   # exits 1 if any secrets, JSON for parsing.
 ```
 
+### Try it on the included examples
+
+The repo ships [`examples/`](examples/) with one Python and one JS project, each with its own `.cloakpolicy`. Clone, install, and run end-to-end against either in 30 seconds:
+
+```bash
+cd examples/python-pricing-engine
+cloak scan .
+cloak context . --copy
+cloak obfuscate . --out /tmp/pricing.cloaked --verify "pytest"
+```
+
+See [examples/README.md](examples/README.md) for the full walkthrough.
+
+### Use as a pre-commit hook
+
+Drop `cloak scan` into `.pre-commit-config.yaml` to block commits that introduce secrets:
+
+```yaml
+repos:
+  - repo: https://github.com/newtophilly/cloak
+    rev: v0.2.1
+    hooks:
+      - id: cloak-scan
+```
+
+Then `pre-commit install` and you're done. See [pre-commit.com](https://pre-commit.com) for general setup.
+
 ## How `.cloakpolicy` works
 
 The policy lives in a `.cloakpolicy` YAML file at the repo root. It's checked into git, versioned with your code, and reviewed via the same PR process as everything else. Authority = whoever has merge access.
@@ -365,8 +396,8 @@ A full annotated example is at [`.cloakpolicy.example`](.cloakpolicy.example).
 
 ## Documentation
 
-- [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) — how this is being built, in the open
-- [`docs/research/`](docs/research/) — Phase 0 validation experiment + competitive landscape research
+- [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) — current state, what's shipped, known v1 limits, what's not yet built
+- [`docs/research/`](docs/research/) — the Phase 0 validation experiment that informed CLOAK's redaction strategy (a fake industrial-automation pricing engine + the LLM responses + our PASS/CONDITIONAL-PASS evaluations)
 
 ## Integrations
 
@@ -377,16 +408,11 @@ CLOAK is designed to be called as a subprocess from other developer tools and AI
 
 ## Status
 
-| Phase | What | Status |
-|-------|------|--------|
-| 0 | Validation experiment | ✅ Done — strategy validated, two-tier redaction discovered |
-| 1 | CLI scaffold + `.cloakpolicy` loader | ✅ Done |
-| 2 | `cloak scan` (wraps detect-secrets) | ✅ Done |
-| 3 | `cloak context` for Python | ✅ Done |
-| 3.5 | `cloak context` JS/TS via tree-sitter | ✅ Done |
-| 4 | `cloak obfuscate` Python with `--verify` | ✅ Done (v1) |
-| 5 | `cloak obfuscate` JS/TS via tree-sitter | ✅ Done (v1) |
-| 6 | `cloak eval` (LLM-prompt-based regression harness) | ⏳ |
+What works today: `cloak scan`, `cloak context`, `cloak obfuscate` for both Python and JS/TS, plus `cloak policy init` for first-time setup and pre-commit-hook integration.
+
+What's known to not yet work / has documented v1 limits: cross-file rename in `obfuscate` (per-file only — `--verify` catches breakage), JS/TS shorthand-property and destructuring rename (deliberately skipped to avoid silently changing object shapes), `cloak eval` regression harness (not started).
+
+The full breakdown — what's shipped, the v1 gaps named honestly, and what's not started — lives in [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md).
 
 ## Contributing
 

{cloak_cli-0.2.0 → cloak_cli-0.3.0}/README.md

@@ -7,8 +7,10 @@
 
 > Local CLI for safer LLM workflows. Redact code before pasting into ChatGPT or Claude. Generate verified obfuscated copies for sharing. Enforce policy from your repo.
 
-> [!IMPORTANT]
-> CLOAK is **alpha software** in active development. APIs and policy format may change before 1.0. The three headline commands (`scan`, `context`, `obfuscate`) are functional for Python; JS/TS support arrives in Phases 3.5 and 5. See [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md) for the roadmap.
+![demo](docs/demo.gif)
+
+> [!NOTE]
+> CLOAK is at **v0.3** — the three headline commands (`scan`, `context`, `obfuscate`) work for both Python and JS/TS, plus `diff-context` for previewing redactions. The `.cloakpolicy` format and CLI flags may still change before 1.0. See [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md) for what's shipped, the known v1 limitations, and what's not started.
 
 ## What CLOAK is
 
@@ -22,10 +24,12 @@ cloak context ./repo --out safe-context.md --copy
 cloak obfuscate ./repo --out ./repo.cloaked --verify "pytest"
 ```
 
-- **`cloak scan`** — Find secrets and proprietary markers in code (wraps `detect-secrets` / `gitleaks` and layers your policy on top).
+- **`cloak scan`** — Find secrets and proprietary markers in code (wraps `detect-secrets` and layers your policy's custom regex rules on top).
 - **`cloak context`** — Generate a redacted markdown view of a repo (function bodies hidden, signatures + docstrings kept) safe to paste into an LLM for architectural feedback. Use `--strict` to also alias enums and paraphrase docstrings.
 - **`cloak obfuscate`** — Produce a transformed copy of your code that **still passes your test suite**, for sharing with contractors or third parties. The `--verify` flag is the differentiator: if your tests don't pass against the transformed copy, the operation fails.
 
+There's also `cloak diff-context` — a dry-run that previews exactly what `cloak context` would redact (function bodies, proprietary tables, docstrings under `--strict`) and the byte reduction, without writing anything. Run it before you trust the transformation.
+
 ## Why this exists
 
 The "Shadow AI" problem is real: leadership says "don't paste code into ChatGPT" and developers do it anyway because they have deadlines. Existing solutions are either enterprise-grade network DLP (expensive, blunt, requires IT) or policy documents nobody reads.
@@ -38,7 +42,7 @@ Honest positioning matters in security tooling.
 
 - **Not unbreakable.** A motivated reader (human or LLM) given an obfuscated copy of your code can still extract logic. CLOAK reduces leak surface and creates friction; it does not provide cryptographic protection. Real protection comes from blocking, redacting, encrypting, compiling, or simply never sending the source.
 - **Not a replacement for enterprise DLP.** Network-layer enforcement (Lasso, Polymer, Cyberhaven, Prisma AIRS, etc.) operates at a different layer and is complementary. CLOAK lives in the developer's workflow, not the network egress.
-- **Not a secret scanner from scratch.** `cloak scan` wraps existing battle-tested OSS scanners (`detect-secrets`, `gitleaks`) and layers policy-aware rules on top. The reuse is intentional and disclosed.
+- **Not a secret scanner from scratch.** `cloak scan` wraps `detect-secrets` (Yelp's open-source scanner — years of regex/entropy tuning come for free) and layers your policy's `secret_rules` on top. The reuse is intentional and disclosed.
 - **Not magic for content the LLM has already seen.** Once code is sent, it's sent. CLOAK helps before paste, not after.
 
 ## Quickstart
@@ -83,6 +87,33 @@ $ cloak obfuscate src/payments --out /tmp/payments.cloaked --verify "pytest test
 $ cloak scan . --json   # exits 1 if any secrets, JSON for parsing.
 ```
 
+### Try it on the included examples
+
+The repo ships [`examples/`](examples/) with one Python and one JS project, each with its own `.cloakpolicy`. Clone, install, and run end-to-end against either in 30 seconds:
+
+```bash
+cd examples/python-pricing-engine
+cloak scan .
+cloak context . --copy
+cloak obfuscate . --out /tmp/pricing.cloaked --verify "pytest"
+```
+
+See [examples/README.md](examples/README.md) for the full walkthrough.
+
+### Use as a pre-commit hook
+
+Drop `cloak scan` into `.pre-commit-config.yaml` to block commits that introduce secrets:
+
+```yaml
+repos:
+  - repo: https://github.com/newtophilly/cloak
+    rev: v0.2.1
+    hooks:
+      - id: cloak-scan
+```
+
+Then `pre-commit install` and you're done. See [pre-commit.com](https://pre-commit.com) for general setup.
+
 ## How `.cloakpolicy` works
 
 The policy lives in a `.cloakpolicy` YAML file at the repo root. It's checked into git, versioned with your code, and reviewed via the same PR process as everything else. Authority = whoever has merge access.
@@ -124,8 +155,8 @@ A full annotated example is at [`.cloakpolicy.example`](.cloakpolicy.example).
 
 ## Documentation
 
-- [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) — how this is being built, in the open
-- [`docs/research/`](docs/research/) — Phase 0 validation experiment + competitive landscape research
+- [`docs/BUILD_PLAN.md`](docs/BUILD_PLAN.md) — current state, what's shipped, known v1 limits, what's not yet built
+- [`docs/research/`](docs/research/) — the Phase 0 validation experiment that informed CLOAK's redaction strategy (a fake industrial-automation pricing engine + the LLM responses + our PASS/CONDITIONAL-PASS evaluations)
 
 ## Integrations
 
@@ -136,16 +167,11 @@ CLOAK is designed to be called as a subprocess from other developer tools and AI
 
 ## Status
 
-| Phase | What | Status |
-|-------|------|--------|
-| 0 | Validation experiment | ✅ Done — strategy validated, two-tier redaction discovered |
-| 1 | CLI scaffold + `.cloakpolicy` loader | ✅ Done |
-| 2 | `cloak scan` (wraps detect-secrets) | ✅ Done |
-| 3 | `cloak context` for Python | ✅ Done |
-| 3.5 | `cloak context` JS/TS via tree-sitter | ✅ Done |
-| 4 | `cloak obfuscate` Python with `--verify` | ✅ Done (v1) |
-| 5 | `cloak obfuscate` JS/TS via tree-sitter | ✅ Done (v1) |
-| 6 | `cloak eval` (LLM-prompt-based regression harness) | ⏳ |
+What works today: `cloak scan`, `cloak context`, `cloak obfuscate` for both Python and JS/TS, plus `cloak policy init` for first-time setup and pre-commit-hook integration.
+
+What's known to not yet work / has documented v1 limits: cross-file rename in `obfuscate` (per-file only — `--verify` catches breakage), JS/TS shorthand-property and destructuring rename (deliberately skipped to avoid silently changing object shapes), `cloak eval` regression harness (not started).
+
+The full breakdown — what's shipped, the v1 gaps named honestly, and what's not started — lives in [docs/BUILD_PLAN.md](docs/BUILD_PLAN.md).
 
 ## Contributing
 

cloak_cli-0.3.0/SECURITY.md

@@ -0,0 +1,32 @@
+# Security policy
+
+CLOAK is early-stage software (pre-1.0), maintained by a single person. The latest release on PyPI (`cloak-cli`) is the one that gets security attention; older releases will not get backports.
+
+## Reporting a vulnerability
+
+**Please don't file public GitHub issues for security vulnerabilities.** Open a private security advisory at https://github.com/newtophilly/cloak/security/advisories/new and include:
+
+- What the vulnerability is and what it lets an attacker do.
+- Reproduction steps or a minimal proof-of-concept.
+- Which version(s) you found it in.
+- Any mitigation you'd suggest.
+
+I'll respond as soon as I can. Realistic expectation: a few days for an acknowledgement, longer for a fix depending on severity and how busy I am. If I'm slow, that's solo-maintainer life — feel free to nudge me on the advisory thread.
+
+## What counts as a vulnerability
+
+In scope (these are real bugs and I want to know about them):
+
+- CLOAK leaks code that the policy was supposed to redact — secrets that `cloak scan` should have caught, function bodies that escape `cloak context` redaction, identifiers that should have been renamed by `cloak obfuscate`.
+- The CLI does something it shouldn't — runs unintended code, writes outside the user-supplied output directory, etc.
+- The published distribution (PyPI artifact, GitHub release, `cloak-manifest.json`) is tampered with or has been compromised.
+
+Not in scope (CLOAK doesn't claim to prevent these):
+
+- An LLM successfully reasoning about a redacted view. CLOAK is friction tooling, not unbreakable protection. See "What CLOAK is NOT" in the README.
+- An obfuscated copy still being human-readable enough for a motivated reader. Same caveat.
+- Vulnerabilities in upstream packages (`detect-secrets`, `tree-sitter`, `typer`, etc.). Report those upstream — but if the upstream bug means CLOAK leaks something, that's in scope here too.
+
+## Coordinated disclosure
+
+Default: I'd like to fix it privately, ship a release, then publicly disclose. If we agree a public disclosure date, I'll keep to it. If a fix is taking longer than expected, I'll talk to you about extending the embargo rather than letting it slip silently.

cloak_cli-0.3.0/docs/AGENT_INTEGRATION.md

@@ -0,0 +1,224 @@
+# Integrating CLOAK from another tool
+
+> Audience: AI agents (Codex, Claude, custom assistants) and developer tools that call CLOAK as a subprocess. If you're a human user, the [README](../README.md) is what you want.
+
+CLOAK is a local CLI. It runs cleanly headless: stable JSON output (`--json`), predictable exit codes, no interactive prompts in non-TTY mode. That makes it easy to invoke from other tools without surprises.
+
+## What CLOAK does, in one paragraph
+
+A `.cloakpolicy` (YAML) sits at the user's repo root. CLOAK has three commands: `scan` finds secrets and proprietary markers; `context` produces a redacted markdown view of the source that's safe to paste into an LLM; `obfuscate` produces a transformed copy of the code that — if `--verify "<cmd>"` was passed — only succeeds if the user's tests pass against the transformed output. CLOAK is friction tooling, not unbreakable protection — surface that honestly when relevant.
+
+## When you should call CLOAK
+
+- The user is preparing to send code to an LLM (paste into chat, build a context packet, share with an assistant).
+- A `.cloakpolicy` file exists at any ancestor directory of the target path. CLOAK finds it automatically; you don't need to.
+- The user explicitly asked for a "safe paste", "redacted version", "AI-safe context", or "obfuscated copy".
+- The user is preparing source for a contractor or third party (use `cloak obfuscate --verify`).
+
+## When you should NOT call CLOAK
+
+- For files outside the user's working repo or otherwise not under their control.
+- The repo has no `.cloakpolicy` AND the user did not explicitly ask for redaction. Don't surprise users with silent redaction.
+- For pure config files, build artifacts, or non-source assets.
+- When the user asked for an explicit `--no-cloak` or equivalent escape hatch in your tool. Honor it.
+
+## Detecting CLOAK and installing it
+
+```bash
+cloak --version
+# Prints "cloak X.Y.Z" on stdout, exit 0. If the command isn't found, install it.
+```
+
+```bash
+# Recommended:
+pip install cloak-cli
+# (The PyPI package name is cloak-cli; the binary on $PATH is `cloak`.)
+
+# From source:
+git clone https://github.com/newtophilly/cloak.git && cd cloak && pip install .
+```
+
+If installation fails, don't silently skip CLOAK in a workflow that explicitly asked for it — surface the error to the user.
+
+## Commands and their JSON contracts
+
+Always pass `--json` when invoking from another tool. The text output is for humans and uses Rich panels, tables, and ANSI codes that don't parse cleanly.
+
+### `cloak scan`
+
+Find secrets and proprietary markers.
+
+```bash
+cloak scan <path> [--policy <file>] [--json]
+```
+
+JSON output:
+
+```json
+{
+  "command": "scan",
+  "status": "ok",
+  "files_scanned": 12,
+  "policy_loaded_from": "/abs/path/to/.cloakpolicy",
+  "policy_version": 1,
+  "findings": [
+    {
+      "severity": "high",
+      "file": "src/foo.py",
+      "line": 42,
+      "rule_id": "detect-secrets/AWS Access Key",
+      "redacted_preview": "AKIA****************",
+      "suggested_action": "Rotate this credential and remove it from source."
+    }
+  ]
+}
+```
+
+`status` is `"ok"` when there are no findings, `"findings"` when there are. `policy_loaded_from` is `null` if no `.cloakpolicy` was found and defaults are being used. **Raw secrets are never printed — `redacted_preview` is the only secret-derived value that appears in output.**
+
+### `cloak context`
+
+Generate a redacted markdown view safe to paste into an LLM.
+
+```bash
+cloak context <path> [--out <file>] [--copy] [--strict] [--policy <file>] [--json]
+```
+
+- `--out <file>`: write the markdown to a file (default: stdout).
+- `--copy`: also put the result on the system clipboard (uses `pbcopy` / `xclip` / `wl-copy` / `clip.exe` if available).
+- `--strict`: aggressive mode — enum values aliased to opaque names, docstrings stripped. Use this when sharing code with parties you don't trust.
+- `--json`: emit a status JSON instead of generating context. Useful as a probe to check whether CLOAK is available and what policy applies; doesn't actually produce the redacted output.
+
+The default markdown output structure:
+- A stable HTML-comment header with version, policy source, and `strict: true|false` for downstream tooling.
+- A `## Files` section listing all input files.
+- Per-file sections with imports, class shapes, function/method signatures, docstrings (per policy).
+- Function/method bodies replaced with `...` for Python, `/* [REDACTED BY CLOAK] */` for JS/TS.
+- Module-level UPPER_SNAKE_CASE constants holding dict/list/object/array literals replaced with `...` (Python) or `/* [REDACTED BY CLOAK] */ null` (JS/TS).
+
+`--json` status output:
+
+```json
+{
+  "command": "context",
+  "status": "ok",
+  "files_discovered": 12,
+  "policy_loaded_from": "/abs/path/to/.cloakpolicy",
+  "policy_version": 1,
+  "strict": false,
+  "implementation_status": "Python supported; JS/TS supported via tree-sitter."
+}
+```
+
+### `cloak obfuscate`
+
+Produce a transformed copy of a repo, optionally gated on a test command passing.
+
+```bash
+cloak obfuscate <path> --out <out_dir> [--verify "<test_cmd>"] [--profile standard|aggressive] [--policy <file>] [--json]
+```
+
+- `--out`: required. Output directory; must not exist or must be empty.
+- `--verify "<test_cmd>"`: shell command run inside the output dir. The operation FAILS (exit 1) if the command exits non-zero. This is the differentiating feature — only succeeds if the user's tests pass against the obfuscated copy.
+- `--profile`: currently `standard` is the only supported value. `aggressive` is reserved.
+
+JSON output:
+
+```json
+{
+  "command": "obfuscate",
+  "status": "ok",
+  "output_dir": "/abs/path/to/out",
+  "manifest_path": "/abs/path/to/out/cloak-manifest.json",
+  "files_copied": 1,
+  "files_transformed": 2,
+  "rename_count": 4,
+  "policy_loaded_from": "/abs/path/to/.cloakpolicy",
+  "verify_command": "pytest",
+  "verify_passed": true
+}
+```
+
+`status` is `"ok"` on success, `"verify_failed"` when `--verify` was passed and the test command exited non-zero, `"error"` when the operation couldn't proceed (e.g., output directory not empty). The output is still written when `verify_failed` so users can inspect what went wrong.
+
+The output directory always contains `cloak-manifest.json` — the audit-trail artifact with: cloak version, generated-at timestamp, sha256 of every source file and every output file, the rename map keyed `path:original`, the policy hash + full policy snapshot, and (if applicable) the verify command + its result. The schema is in [`src/cloak/obfuscate/manifest.py`](../src/cloak/obfuscate/manifest.py).
+
+## Exit codes
+
+- `0` — success.
+- `1` — operation completed with findings or verify failure that the caller should look at (e.g., `cloak scan` found secrets, `cloak obfuscate --verify` failed).
+- `2` — usage / validation error (bad arguments, output directory not empty, etc.).
+
+When in doubt, parse the JSON `status` field rather than relying only on the exit code.
+
+## Policy file (`.cloakpolicy`)
+
+YAML at the repo root. CLOAK auto-discovers it by walking up from the target path. If no policy is found, sensible defaults apply.
+
+A short example:
+
+```yaml
+version: 1
+sensitive_paths: ["src/pricing/**"]
+public_api: ["QuoteEngine.calculate_quote"]
+context_defaults:
+  keep_docstrings: true
+  redact_function_bodies: true
+  alias_enums: false
+obfuscate_defaults:
+  profile: standard
+  strip_docstrings: false
+```
+
+A full annotated example is at [`.cloakpolicy.example`](../.cloakpolicy.example) at the repo root.
+
+**Don't modify a project's `.cloakpolicy` without explicit user consent.** Treat it like a CODEOWNERS file or a CI config — it's governance, not configuration you can adjust on the user's behalf.
+
+## Common patterns
+
+### Building a redacted context packet for an LLM
+
+```bash
+# Probe: is CLOAK installed and is there a policy in this repo?
+cloak scan /path/to/repo --json
+
+# If a policy was loaded OR the user explicitly asked for redaction:
+cloak context /path/to/repo --out /tmp/safe.md
+# Use /tmp/safe.md as the source-code section of the packet.
+```
+
+### Pre-paste workflow (user is about to ask an LLM for help)
+
+```bash
+cloak context /path/to/repo/src/foo.py --copy
+# Tell the user: "Redacted view is on your clipboard; paste away."
+```
+
+### Preparing source for a contractor
+
+```bash
+cloak obfuscate /path/to/repo --out /tmp/repo.cloaked --verify "pytest"
+# If exit 0, the obfuscated copy passes the user's tests — safe to ship.
+# If exit 1, look at the JSON output's verify-related fields and tell the user.
+# Either way, /tmp/repo.cloaked/cloak-manifest.json is the audit artifact.
+```
+
+## Honesty constraints when describing CLOAK to users
+
+If your tool surfaces CLOAK output to a human, please match CLOAK's positioning:
+
+- DO: "CLOAK redacted the proprietary parts before sending."
+- DO: "CLOAK created a transformed copy that still passes your tests."
+- DON'T: "Your code is now safe from AI."
+- DON'T: "This is unreadable to LLMs."
+- DON'T: "This is encrypted."
+
+Obfuscation is friction, not cryptographic protection. The "What CLOAK is NOT" section in the [README](../README.md) is the canonical list of caveats — surface that wording verbatim if a user asks about CLOAK's guarantees.
+
+## Reporting integration issues
+
+Open an issue at https://github.com/newtophilly/cloak/issues with:
+- The exact CLOAK version (`cloak --version`).
+- Which tool was integrating with CLOAK (yours, fob, your own client, etc.).
+- The command invoked and the full output.
+- What you expected vs. what happened.