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

cloak_cli-0.2.1/.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.2.0 → cloak_cli-0.2.1}/CHANGELOG.md

@@ -6,6 +6,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-08
+
+### Added
+- `.pre-commit-hooks.yaml` at repo root. Users can add `cloak-scan` to their `.pre-commit-config.yaml` and `cloak scan` runs as a pre-commit gate (exits 1 on findings, blocks the commit). A second `cloak-context-preview` hook is provided at `stages: [manual]` for opt-in invocation.
+- `examples/` directory with two end-to-end demos: `python-pricing-engine/` (with pytest coverage so `--verify "pytest"` works) and `js-api-client/`. Each has its own `.cloakpolicy`. New users can `cd examples/python-pricing-engine && cloak scan .` and see CLOAK in action in 30 seconds. See `examples/README.md` for the walkthrough.
+- README "Try it on the included examples" + "Use as a pre-commit hook" sections.
+
 ## [0.2.0] - 2026-05-08
 
 Feature matrix complete: all three headline commands now work for both Python and JS/TS.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloak-cli
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -324,6 +324,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.0
+    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.

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

@@ -83,6 +83,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.0
+    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.

cloak_cli-0.2.1/examples/README.md

@@ -0,0 +1,61 @@
+# CLOAK examples
+
+Two tiny projects to demonstrate `cloak scan`, `cloak context`, and `cloak obfuscate` end to end.
+
+Both have their own `.cloakpolicy` so you can run CLOAK against them right away.
+
+## `python-pricing-engine/`
+
+A simplified pricing engine: a public `calculate_total` plus private `_apply_tier` and `_apply_region` helpers, with `_TIER_DISCOUNTS` and `_REGIONAL_MARKUPS` proprietary tables. Includes pytest coverage so `--verify` has something real to check.
+
+```bash
+cd examples/python-pricing-engine
+
+# 1. Scan for secrets / proprietary markers
+cloak scan .
+
+# 2. Generate redacted markdown safe to paste into ChatGPT/Claude
+cloak context . --copy
+# Bodies replaced with `...`. Tables (_TIER_DISCOUNTS, _REGIONAL_MARKUPS) replaced
+# with `...`. Public API + signatures preserved.
+
+# 3. Obfuscate, gated on the pytest suite passing
+cloak obfuscate . --out /tmp/pricing.cloaked --verify "pytest"
+# Private helpers renamed (_apply_tier → _a000, _apply_region → _a001).
+# Public `calculate_total` preserved (it's in .cloakpolicy public_api).
+# Tests pass against the obfuscated copy.
+ls /tmp/pricing.cloaked/cloak-manifest.json   # audit trail with hashes + rename map
+```
+
+## `js-api-client/`
+
+A small API client with a public `fetchJson` plus private `_buildHeaders` and `_normalizePath` helpers, and `_BASE_HEADERS` / `_TIMEOUT_MS` proprietary constants.
+
+```bash
+cd examples/js-api-client
+
+cloak scan .
+cloak context . --copy
+cloak obfuscate . --out /tmp/client.cloaked
+# Note: no --verify here because the example doesn't ship a Node test runner setup.
+# In your real project, you'd pass --verify "npm test" or similar.
+```
+
+## What you should observe
+
+- `cloak scan` exits 0 (no secrets in these examples) and prints a green "Clean" panel.
+- `cloak context` produces markdown where signatures and class shapes survive, but bodies and proprietary tables are replaced with `...` (Python) or `/* [REDACTED BY CLOAK] */` (JS/TS).
+- `cloak obfuscate` produces a transformed copy in the output dir with `_a000`/`_a001`/...  identifiers replacing the original `_names`. Public-API names listed in `.cloakpolicy` are preserved.
+- The `cloak-manifest.json` in the output dir records: cloak version, source/output sha256s, the rename map, the policy snapshot, and (if `--verify` was passed) the verify command + result.
+
+## Want to try `--verify` failing?
+
+Edit `pricing.py` to break the math (e.g., return `subtotal` instead of the discounted total) and rerun:
+
+```bash
+cloak obfuscate . --out /tmp/pricing.cloaked --verify "pytest"
+# Exit code 1, panel shows the failing pytest output.
+# Output is still written for inspection but the operation is reported as failed.
+```
+
+This is the differentiator: `cloak obfuscate` only succeeds if your tests pass against the transformed copy.

cloak_cli-0.2.1/examples/js-api-client/.cloakpolicy

@@ -0,0 +1,25 @@
+# Example policy for the JS API client.
+version: 1
+
+sensitive_paths:
+  - "*.js"
+  - "*.ts"
+
+# `fetchJson` is the public API — never let obfuscate rename it.
+public_api:
+  - "fetchJson"
+
+secret_rules: []
+allow_strings: []
+
+context_defaults:
+  keep_docstrings: true
+  redact_function_bodies: true
+  alias_enums: false
+
+obfuscate_defaults:
+  rename_private: true
+  rename_public_api: false
+  encode_strings: false
+  strip_docstrings: false
+  profile: standard

cloak_cli-0.2.1/examples/js-api-client/client.js

@@ -0,0 +1,34 @@
+// Tiny example API client — public function plus underscore-private helpers.
+//
+// Demonstrates how `cloak context` and `cloak obfuscate` treat JS files.
+
+const _BASE_HEADERS = {
+  "User-Agent": "example-client/1.0",
+  "Accept": "application/json",
+};
+
+const _TIMEOUT_MS = 5000;
+
+function _buildHeaders(token) {
+  return {
+    ..._BASE_HEADERS,
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+function _normalizePath(path) {
+  if (!path.startsWith("/")) return `/${path}`;
+  return path;
+}
+
+export async function fetchJson(baseUrl, path, token) {
+  const url = baseUrl + _normalizePath(path);
+  const response = await fetch(url, {
+    headers: _buildHeaders(token),
+    signal: AbortSignal.timeout(_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return response.json();
+}

cloak_cli-0.2.1/examples/python-pricing-engine/.cloakpolicy

@@ -0,0 +1,24 @@
+# Example policy for the Python pricing engine.
+version: 1
+
+sensitive_paths:
+  - "*.py"
+
+# `calculate_total` is the public entry point — never let obfuscate rename it.
+public_api:
+  - "calculate_total"
+
+secret_rules: []
+allow_strings: []
+
+context_defaults:
+  keep_docstrings: true
+  redact_function_bodies: true
+  alias_enums: false
+
+obfuscate_defaults:
+  rename_private: true
+  rename_public_api: false
+  encode_strings: false
+  strip_docstrings: false
+  profile: standard

cloak_cli-0.2.1/examples/python-pricing-engine/pricing.py

@@ -0,0 +1,43 @@
+"""Tiny example pricing engine — public API + private helpers + 'proprietary tables'.
+
+This file exists to demonstrate how `cloak context` and `cloak obfuscate` treat each kind
+of definition. It is intentionally small and self-contained.
+"""
+
+from dataclasses import dataclass
+
+
+_TIER_DISCOUNTS = {
+    "basic": 0.00,
+    "pro": 0.10,
+    "enterprise": 0.20,
+}
+
+_REGIONAL_MARKUPS = {
+    "domestic": 1.00,
+    "international": 1.15,
+}
+
+
+@dataclass
+class Customer:
+    customer_id: str
+    tier: str
+    region: str
+
+
+def calculate_total(customer: Customer, subtotal: float) -> float:
+    """Public API: produce a final price for a customer + subtotal."""
+    discount = _apply_tier(customer.tier)
+    markup = _apply_region(customer.region)
+    return subtotal * (1 - discount) * markup
+
+
+def _apply_tier(tier: str) -> float:
+    """Return the discount fraction for a tier."""
+    return _TIER_DISCOUNTS.get(tier, 0.0)
+
+
+def _apply_region(region: str) -> float:
+    """Return the price multiplier for a region."""
+    return _REGIONAL_MARKUPS.get(region, 1.0)

cloak_cli-0.2.1/examples/python-pricing-engine/test_pricing.py

@@ -0,0 +1,19 @@
+"""Tests for the example pricing engine — used by `cloak obfuscate --verify`."""
+
+from pricing import Customer, calculate_total
+
+
+def test_basic_domestic() -> None:
+    c = Customer(customer_id="C1", tier="basic", region="domestic")
+    assert calculate_total(c, 100.0) == 100.0
+
+
+def test_pro_domestic_gets_10_percent() -> None:
+    c = Customer(customer_id="C2", tier="pro", region="domestic")
+    assert calculate_total(c, 100.0) == 90.0
+
+
+def test_enterprise_international() -> None:
+    c = Customer(customer_id="C3", tier="enterprise", region="international")
+    # 100 * 0.80 * 1.15 = 92.0
+    assert calculate_total(c, 100.0) == 92.0

{cloak_cli-0.2.0 → cloak_cli-0.2.1}/pyproject.toml

@@ -65,7 +65,7 @@ packages = ["src/cloak"]
 [tool.ruff]
 line-length = 100
 target-version = "py311"
-extend-exclude = ["docs", ".venv"]
+extend-exclude = ["docs", ".venv", "examples"]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]

{cloak_cli-0.2.0 → cloak_cli-0.2.1}/src/cloak/__init__.py

@@ -1,3 +1,3 @@
 """CLOAK — local CLI for safer LLM workflows."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"