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

{cloak_cli-0.1.2 → cloak_cli-0.2.0}/CHANGELOG.md

@@ -6,6 +6,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-08
+
+Feature matrix complete: all three headline commands now work for both Python and JS/TS.
+
+### Added
+- Phase 5: `cloak obfuscate` now handles JavaScript and TypeScript files, dispatched by extension. Per-file rename of module-level identifiers starting with `_` (function declarations, class declarations, generator functions, `const`/`let`/`var` simple bindings) using tree-sitter for parsing and byte-splice for output. Skips dunder-like names (`__version`), all-underscore names, and anything matching `policy.public_api` (with trailing-`*` wildcard support). Property access (`obj._foo`), shorthand object properties, and destructuring patterns are deliberately not renamed in v1 — they would silently change object shapes and risk runtime breakage. Limitations are caught by `--verify` (cross-file imports, local-variable shadowing of module-level `_names`).
+- `cloak obfuscate` against a mixed Python+JS repo now transforms both languages in one pass with one manifest, one rename map, and one verify command.
+
 ## [0.1.2] - 2026-05-08
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloak-cli
-Version: 0.1.2
+Version: 0.2.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
@@ -385,7 +385,7 @@ CLOAK is designed to be called as a subprocess from other developer tools and AI
 | 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 (javascript-obfuscator) | ⏳ |
+| 5 | `cloak obfuscate` JS/TS via tree-sitter | ✅ Done (v1) |
 | 6 | `cloak eval` (LLM-prompt-based regression harness) | ⏳ |
 
 ## Contributing

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

@@ -144,7 +144,7 @@ CLOAK is designed to be called as a subprocess from other developer tools and AI
 | 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 (javascript-obfuscator) | ⏳ |
+| 5 | `cloak obfuscate` JS/TS via tree-sitter | ✅ Done (v1) |
 | 6 | `cloak eval` (LLM-prompt-based regression harness) | ⏳ |
 
 ## Contributing

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

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

{cloak_cli-0.1.2 → cloak_cli-0.2.0}/src/cloak/cli.py

@@ -247,7 +247,7 @@ def _emit_obfuscate_terminal(policy: Policy, result: ObfuscateResult) -> None:
         "[bold green]✓ Obfuscated[/bold green]",
         f"output:        {result.output_dir}",
         f"manifest:      {result.manifest_path}",
-        f"transformed:   {result.files_transformed} python files",
+        f"transformed:   {result.files_transformed} source files",
         f"copied:        {result.files_copied} other files",
         f"renames:       {len(result.rename_map)} module-private identifiers",
     ]

cloak_cli-0.2.0/src/cloak/obfuscate/js_transformer.py

@@ -0,0 +1,175 @@
+"""Phase 5 — JS/TS obfuscation transformer.
+
+Per-file rename of module-level identifiers that start with `_` (and aren't dunder-like or
+all underscores). Same shape as the Python obfuscator: collect candidate names, build a
+deterministic rename map (`_a000`, `_a001`, ...), then byte-splice every reference of those
+names in the file with their new identifier.
+
+Tree-sitter is used as a parser only — we don't unparse. Edits happen at the byte level so
+all formatting and comments outside renamed identifiers survive.
+
+v1 limitations (deferred — caught by `--verify`):
+  - Cross-file rename. If `import { _helper } from './lib'`, the import keeps `_helper` but
+    the target file renames it; tests will fail and the user knows immediately.
+  - Local-variable shadowing. If a function body defines `const _helper = ...` shadowing a
+    module-level `_helper`, both get renamed; tests will catch logic bugs that arise.
+  - Shorthand property in object literals (`{ _helper }`) and destructuring patterns
+    (`const { _helper } = ...`) are NOT renamed (would change object shape silently). This
+    means a module-level `_helper` referenced via shorthand goes un-renamed there.
+  - Class methods are NOT renamed (could be public API).
+"""
+
+from dataclasses import dataclass, field
+
+from tree_sitter import Node, Parser
+
+from cloak.context.js_redactor import JsLikeKind, _get_language
+from cloak.policy import Policy
+
+_RENAMEABLE_IDENTIFIER_TYPES = {"identifier", "type_identifier"}
+
+_DEFINITION_NODE_TYPES = {
+    "function_declaration",
+    "generator_function_declaration",
+    "class_declaration",
+    "lexical_declaration",
+    "variable_declaration",
+}
+
+
+@dataclass
+class JsTransformResult:
+    """Result of transforming a single JS/TS file."""
+
+    source_text: str
+    output_text: str
+    rename_map: dict[str, str] = field(default_factory=dict)
+
+
+def transform_js_like_source(
+    source: str,
+    kind: JsLikeKind,
+    policy: Policy,
+) -> JsTransformResult:
+    """Apply v1 obfuscation to a JS/TS source string. Returns transformed text + rename map."""
+    src_bytes = source.encode("utf-8")
+    parser = Parser(_get_language(kind))
+    tree = parser.parse(src_bytes)
+
+    names = _collect_top_level_private_names(tree.root_node, src_bytes, policy)
+    rename_map = _build_rename_map(names)
+
+    if not rename_map:
+        return JsTransformResult(source_text=source, output_text=source)
+
+    edits: list[tuple[int, int, bytes]] = []
+    _collect_rename_edits(tree.root_node, src_bytes, rename_map, edits)
+
+    if not edits:
+        return JsTransformResult(source_text=source, output_text=source, rename_map=rename_map)
+
+    edits.sort(key=lambda e: e[0], reverse=True)
+    out = bytearray(src_bytes)
+    for start, end, replacement in edits:
+        out[start:end] = replacement
+    return JsTransformResult(
+        source_text=source,
+        output_text=out.decode("utf-8", errors="replace"),
+        rename_map=rename_map,
+    )
+
+
+def _collect_top_level_private_names(root_node: Node, src: bytes, policy: Policy) -> list[str]:
+    """Find top-level definitions whose name starts with `_`. Skips dunders, all-underscore."""
+    names: list[str] = []
+    seen: set[str] = set()
+    public_api = set(policy.public_api)
+
+    for child in root_node.children:
+        # `export ...` wraps a real declaration — peek through one level.
+        target = child
+        if child.type == "export_statement":
+            for inner in child.children:
+                if inner.type in _DEFINITION_NODE_TYPES:
+                    target = inner
+                    break
+
+        for name in _extract_definition_names(target, src):
+            if _should_rename(name, public_api) and name not in seen:
+                seen.add(name)
+                names.append(name)
+
+    return names
+
+
+def _extract_definition_names(node: Node, src: bytes) -> list[str]:
+    """Return the symbol names this top-level definition introduces."""
+    if node.type in {
+        "function_declaration",
+        "generator_function_declaration",
+        "class_declaration",
+    }:
+        name_node = node.child_by_field_name("name")
+        if name_node is not None:
+            return [_text(name_node, src)]
+        return []
+
+    if node.type in {"lexical_declaration", "variable_declaration"}:
+        result: list[str] = []
+        for declarator in node.children:
+            if declarator.type != "variable_declarator":
+                continue
+            name_node = declarator.child_by_field_name("name")
+            # Only handle the simple `const _foo = ...` case. Destructuring patterns
+            # (object_pattern, array_pattern) are skipped — too risky to rename in v1.
+            if name_node is not None and name_node.type == "identifier":
+                result.append(_text(name_node, src))
+        return result
+
+    return []
+
+
+def _should_rename(name: str, public_api: set[str]) -> bool:
+    if not name.startswith("_"):
+        return False
+    if name.startswith("__"):
+        # Dunder-like; conservative skip (e.g. `__dirname` in CommonJS).
+        return False
+    if all(c == "_" for c in name):
+        return False
+    if name in public_api:
+        return False
+    for pattern in public_api:
+        if pattern.endswith("*") and name.startswith(pattern.rstrip("*")):
+            return False
+    return True
+
+
+def _build_rename_map(names: list[str]) -> dict[str, str]:
+    return {name: f"_a{i:03d}" for i, name in enumerate(names)}
+
+
+def _collect_rename_edits(
+    node: Node,
+    src: bytes,
+    rename_map: dict[str, str],
+    edits: list[tuple[int, int, bytes]],
+) -> None:
+    """Walk the tree; replace `identifier`/`type_identifier` nodes whose text is in the map.
+
+    Critically: we do NOT touch `property_identifier` (member access — `.foo` is a different
+    scope), `shorthand_property_identifier` (would silently change object shape), or
+    destructuring identifiers — see v1 limitations in module docstring.
+    """
+    if node.type in _RENAMEABLE_IDENTIFIER_TYPES:
+        text = _text(node, src)
+        if text in rename_map:
+            edits.append((node.start_byte, node.end_byte, rename_map[text].encode("utf-8")))
+        return  # leaf
+
+    for child in node.children:
+        _collect_rename_edits(child, src, rename_map, edits)
+
+
+def _text(node: Node, src: bytes) -> str:
+    return src[node.start_byte : node.end_byte].decode("utf-8", errors="replace")

{cloak_cli-0.1.2 → cloak_cli-0.2.0}/src/cloak/obfuscate/runner.py

@@ -17,7 +17,9 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 from cloak import __version__
+from cloak.context.js_redactor import language_for_extension
 from cloak.filesystem import walk_repo
+from cloak.obfuscate.js_transformer import transform_js_like_source
 from cloak.obfuscate.manifest import Manifest
 from cloak.obfuscate.transformer import transform_python_source
 from cloak.policy import Policy
@@ -81,6 +83,8 @@ def run_obfuscate(
 
         source_hashes[str(rel)] = _sha256_file(src_file)
 
+        js_like_kind = language_for_extension(src_file.suffix)
+
         if src_file.suffix == ".py":
             try:
                 source_text = src_file.read_text(encoding="utf-8")
@@ -91,7 +95,7 @@ def run_obfuscate(
                 continue
 
             try:
-                result = transform_python_source(source_text, policy, file_label=str(rel))
+                py_result = transform_python_source(source_text, policy, file_label=str(rel))
             except SyntaxError:
                 # Don't break on un-parseable files. Copy them through unchanged.
                 shutil.copy2(src_file, out_file)
@@ -99,9 +103,24 @@ def run_obfuscate(
                 files_copied += 1
                 continue
 
-            out_file.write_text(result.output_text, encoding="utf-8")
+            out_file.write_text(py_result.output_text, encoding="utf-8")
+            output_hashes[str(rel)] = _sha256_file(out_file)
+            for orig, new in py_result.rename_map.items():
+                rename_map_global[f"{rel}:{orig}"] = new
+            files_transformed += 1
+        elif js_like_kind is not None:
+            try:
+                source_text = src_file.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError):
+                shutil.copy2(src_file, out_file)
+                output_hashes[str(rel)] = _sha256_file(out_file)
+                files_copied += 1
+                continue
+
+            js_result = transform_js_like_source(source_text, js_like_kind, policy)
+            out_file.write_text(js_result.output_text, encoding="utf-8")
             output_hashes[str(rel)] = _sha256_file(out_file)
-            for orig, new in result.rename_map.items():
+            for orig, new in js_result.rename_map.items():
                 rename_map_global[f"{rel}:{orig}"] = new
             files_transformed += 1
         else:

cloak_cli-0.2.0/tests/test_obfuscate_js.py

@@ -0,0 +1,201 @@
+"""Tests for `cloak obfuscate` JS/TS support (Phase 5)."""
+
+import json
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from cloak.cli import app
+from cloak.obfuscate.js_transformer import transform_js_like_source
+from cloak.obfuscate.runner import run_obfuscate
+from cloak.policy import Policy
+
+runner = CliRunner()
+
+
+# ---------- transformer unit tests ----------
+
+
+def test_renames_module_level_function() -> None:
+    src = (
+        "function _helper(x) {\n"
+        "  return x + 1;\n"
+        "}\n"
+        "\n"
+        "export function publicFn(x) {\n"
+        "  return _helper(x);\n"
+        "}\n"
+    )
+    result = transform_js_like_source(src, "javascript", Policy())
+    assert "_helper" not in result.output_text
+    assert "_a000" in result.output_text
+    # Public name preserved
+    assert "publicFn" in result.output_text
+    # Reference inside publicFn correctly rewritten
+    assert "_a000(x)" in result.output_text
+    assert result.rename_map == {"_helper": "_a000"}
+
+
+def test_renames_module_level_const() -> None:
+    src = "const _internal = 42;\nexport const value = _internal * 2;\n"
+    result = transform_js_like_source(src, "javascript", Policy())
+    assert "_internal" not in result.output_text
+    assert "_a000" in result.output_text
+    assert "value = _a000 * 2" in result.output_text
+
+
+def test_renames_module_level_class() -> None:
+    src = (
+        "class _Internal {\n"
+        "  constructor() { this.x = 1; }\n"
+        "}\n"
+        "\n"
+        "export function make() {\n"
+        "  return new _Internal();\n"
+        "}\n"
+    )
+    result = transform_js_like_source(src, "javascript", Policy())
+    assert "_Internal" not in result.output_text
+    assert "_a000" in result.output_text
+    assert "new _a000()" in result.output_text
+
+
+def test_does_not_rename_dunder_like_names() -> None:
+    src = "const __version = '1.0';\nconst _foo = 1;\n"
+    result = transform_js_like_source(src, "javascript", Policy())
+    assert "__version" in result.output_text  # preserved
+    assert "_foo" not in result.output_text  # renamed
+    assert "_a000" in result.output_text
+
+
+def test_respects_public_api_in_policy() -> None:
+    src = "export function _publicHelper(x) { return x; }\n"
+    policy = Policy(public_api=["_publicHelper"])
+    result = transform_js_like_source(src, "javascript", policy)
+    assert "_publicHelper" in result.output_text
+    assert not result.rename_map
+
+
+def test_handles_export_statement_with_lexical_declaration() -> None:
+    src = "export const _privateUtil = (x) => x * 2;\n"
+    result = transform_js_like_source(src, "javascript", Policy())
+    # The name should still be renamed even though it's wrapped in `export`.
+    assert "_privateUtil" not in result.output_text
+    assert "_a000" in result.output_text
+
+
+def test_preserves_property_access_with_same_name() -> None:
+    """obj._helper is a member access — different scope; we don't rename it."""
+    src = (
+        "function _helper(x) { return x * 2; }\n"
+        "const obj = { _helper: 'something else' };\n"
+        "export function go() {\n"
+        "  return _helper(obj._helper);\n"
+        "}\n"
+    )
+    result = transform_js_like_source(src, "javascript", Policy())
+    # The bare `_helper` reference (function call) should be renamed.
+    # The property access `obj._helper` should NOT be renamed (different scope).
+    assert "obj._helper" in result.output_text
+    # The standalone calls should be renamed.
+    assert "_a000(obj._helper)" in result.output_text
+
+
+def test_typescript_renames_top_level_types() -> None:
+    """TypeScript: rename top-level _-prefixed type identifiers as well."""
+    src = (
+        "type _Internal = { x: number };\nexport function make(): _Internal { return { x: 1 }; }\n"
+    )
+    result = transform_js_like_source(src, "typescript", Policy())
+    # type_alias_declaration: tree-sitter-typescript should expose this; for v1, our
+    # _DEFINITION_NODE_TYPES doesn't include it, so the rename won't happen. This is
+    # documented as a limitation. The point of this test: confirm we don't crash.
+    assert result.output_text  # non-empty
+    # The visible behavior may or may not rename; either is acceptable for v1.
+
+
+def test_returns_unchanged_when_no_private_names() -> None:
+    src = "export function pub(x) { return x; }\n"
+    result = transform_js_like_source(src, "javascript", Policy())
+    assert result.output_text == src
+    assert not result.rename_map
+
+
+def test_handles_invalid_source_gracefully() -> None:
+    src = "function broken( {{{"
+    # Should not raise.
+    transform_js_like_source(src, "javascript", Policy())
+
+
+# ---------- pipeline integration ----------
+
+
+def _make_js_repo(tmp_path: Path) -> Path:
+    """Sample JS repo: lib + matching test that imports the public function."""
+    repo = tmp_path / "src_repo"
+    repo.mkdir()
+    (repo / "lib.js").write_text(
+        "function _double(x) {\n"
+        "  return x * 2;\n"
+        "}\n"
+        "\n"
+        "export function publicFn(x) {\n"
+        "  return _double(x);\n"
+        "}\n"
+    )
+    (repo / "package.json").write_text('{"type":"module"}\n')
+    return repo
+
+
+def test_runner_handles_mixed_python_and_js(tmp_path: Path) -> None:
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "lib.py").write_text(
+        "def _helper(x):\n    return x + 1\n\ndef pub(x):\n    return _helper(x)\n"
+    )
+    (repo / "lib.js").write_text(
+        "function _helper(x) { return x + 1; }\nexport function pub(x) { return _helper(x); }\n"
+    )
+    out = tmp_path / "obfuscated"
+
+    result = run_obfuscate(repo, out, Policy())
+    assert result.files_transformed == 2  # both py and js were transformed
+    py_text = (out / "lib.py").read_text()
+    js_text = (out / "lib.js").read_text()
+    assert "_helper" not in py_text
+    assert "_helper" not in js_text
+    assert "_a000" in py_text
+    assert "_a000" in js_text
+
+
+def test_runner_writes_manifest_with_js_renames(tmp_path: Path) -> None:
+    repo = _make_js_repo(tmp_path)
+    out = tmp_path / "obfuscated"
+    run_obfuscate(repo, out, Policy())
+
+    manifest = json.loads((out / "cloak-manifest.json").read_text())
+    assert "lib.js:_double" in manifest["rename_map"]
+    assert manifest["rename_map"]["lib.js:_double"] == "_a000"
+
+
+# ---------- CLI integration ----------
+
+
+def test_cli_obfuscate_against_js_repo(tmp_path: Path) -> None:
+    repo = _make_js_repo(tmp_path)
+    out = tmp_path / "obf"
+    result = runner.invoke(app, ["obfuscate", str(repo), "--out", str(out)])
+    assert result.exit_code == 0, result.stdout
+    obfuscated = (out / "lib.js").read_text()
+    assert "_double" not in obfuscated
+    assert "_a000" in obfuscated
+    assert "publicFn" in obfuscated  # public preserved
+
+
+def test_cli_obfuscate_panel_shows_renames(tmp_path: Path) -> None:
+    repo = _make_js_repo(tmp_path)
+    out = tmp_path / "obf"
+    result = runner.invoke(app, ["obfuscate", str(repo), "--out", str(out)])
+    assert result.exit_code == 0
+    assert "Obfuscated" in result.stdout
+    assert "1 module-private" in result.stdout or "renames:" in result.stdout