jame 1.0.dev2__tar.gz → 1.0.dev3__tar.gz

{jame-1.0.dev2 → jame-1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jame
-Version: 1.0.dev2
+Version: 1.0.dev3
 Summary: Just Another Method of Exploitation
 Author: JAMe Contributors
 License: MIT
@@ -20,6 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: c2e
+Requires-Dist: mapres
 Requires-Dist: PyYAML>=6.0
 Dynamic: license-file
 
@@ -41,31 +42,36 @@ JAMe is a lightweight forensic and triage toolkit for scanning files, extracting
 
 ## Installation
 
-JAMe requires Python 3.10 or newer. From the repository root, this one-line
-installer creates the virtual environment, installs JAMe, links the command
-into the absolute path `$HOME/.local/bin`, and adds that directory to the
-current shell and future Bash login/interactive shells:
+JAMe requires Python 3.10 or newer. Install the latest published package and
+register `jame` on your user PATH with:
 
 ```bash
-python3 -m venv .venv && .venv/bin/pip install jame && mkdir -p "$HOME/.local/bin" && if [[ -e "$HOME/.local/bin/jame" && ! "$HOME/.local/bin/jame" -ef "$(pwd -P)/.venv/bin/jame" ]]; then printf '%s\n' 'Refusing to replace existing command at ~/.local/bin/jame' >&2; exit 1; fi && ln -sfn "$(pwd -P)/.venv/bin/jame" "$HOME/.local/bin/jame" && for rc in "$HOME/.profile" "$HOME/.bashrc"; do grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc" 2>/dev/null || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc"; done && export PATH="$HOME/.local/bin:$PATH" && jame --help
+curl -fsSL https://raw.githubusercontent.com/HungerNet/JAMe/main/install.sh | bash
 ```
 
+The installer creates a dedicated environment under `$HOME/.local/share/jame`,
+installs the MapRes pre-release API, `jame`, and C2E, and links the command to
+`$HOME/.local/bin/jame`. It adds that directory to Bash or Zsh startup files;
+open a new shell if it was not already on your current PATH.
+
+Set `JAME_PYTHON` to select a specific Python 3.10+ executable. Set
+`JAME_INSTALL_DIR` or `JAME_BIN_DIR` to change the absolute install or bin path.
+
 ## CLI
 
-From a checkout, the Bash launcher can also be run directly; it uses the active
-virtual environment, the checkout's `.venv`, or `python3.10`, in that order:
+After installation, run the `jame` command from any directory:
 
 ```bash
-./jame.sh --help
-./jame.sh tests/files/solution.txt
+jame --help
+jame tests/files/solution.txt
 ```
 
-The default command finds a flag and extracts supported archives. The original
-path-only form remains supported:
+The default command finds a flag and extracts supported archives. The explicit
+`solve` form is also available:
 
 ```bash
-./jame.sh tests/files/solution.txt
-./jame.sh solve tests/files/solution.txt --format 'flag{*}'
+jame tests/files/solution.txt
+jame solve tests/files/solution.txt --format 'flag{*}'
 ```
 
 Use `*` for any-length text and `*N` for exactly `N` characters. Repeating
@@ -75,23 +81,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./jame.sh update
-./jame.sh update --pre
-./jame.sh find-flag tests/files/challenge.txt --format 'hcr{*4}'
-./jame.sh scan tests/files/scan.txt
-./jame.sh crypto tests/files/strings.txt --verbose
-./jame.sh binary tests/files/strings.txt
-./jame.sh stego tests/files/strings.txt
-./jame.sh forensics tests/files/strings.txt
-./jame.sh archive path/to/archive.zip --max-depth 2
-./jame.sh file-type tests/files/strings.txt
-./jame.sh strings tests/files/strings.txt
-./jame.sh binwalk path/to/file.bin
-./jame.sh caesar 'Khoor' --shift 3
+jame update
+jame update --pre
+jame find-flag tests/files/challenge.txt --format 'hcr{*4}'
+jame scan tests/files/scan.txt
+jame crypto tests/files/strings.txt --verbose
+jame binary tests/files/strings.txt
+jame stego tests/files/strings.txt
+jame forensics tests/files/strings.txt
+jame archive path/to/archive.zip --max-depth 2
+jame file-type tests/files/strings.txt
+jame strings tests/files/strings.txt
+jame binwalk path/to/file.bin
+jame caesar 'Khoor'
+jame caesar 'Khoor' --verbose
+jame caesar 'Khoor' --shift 3
 ```
 
 `--verbose` prints the structured result, including analyzer details and raw
-output where available. `binwalk` requires the external `binwalk` utility.
+output where available. Caesar brute force prints only its highest-ranked
+decoded candidate by default; `--verbose` shows the ranked candidates.
+`jame update` upgrades JAMe and C2E; `jame update --pre` also upgrades MapRes
+using prerelease versions. `binwalk` requires the external `binwalk` utility.
 
 ## Quickstart
 

{jame-1.0.dev2 → jame-1.0.dev3}/README.md

@@ -16,31 +16,36 @@ JAMe is a lightweight forensic and triage toolkit for scanning files, extracting
 
 ## Installation
 
-JAMe requires Python 3.10 or newer. From the repository root, this one-line
-installer creates the virtual environment, installs JAMe, links the command
-into the absolute path `$HOME/.local/bin`, and adds that directory to the
-current shell and future Bash login/interactive shells:
+JAMe requires Python 3.10 or newer. Install the latest published package and
+register `jame` on your user PATH with:
 
 ```bash
-python3 -m venv .venv && .venv/bin/pip install jame && mkdir -p "$HOME/.local/bin" && if [[ -e "$HOME/.local/bin/jame" && ! "$HOME/.local/bin/jame" -ef "$(pwd -P)/.venv/bin/jame" ]]; then printf '%s\n' 'Refusing to replace existing command at ~/.local/bin/jame' >&2; exit 1; fi && ln -sfn "$(pwd -P)/.venv/bin/jame" "$HOME/.local/bin/jame" && for rc in "$HOME/.profile" "$HOME/.bashrc"; do grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc" 2>/dev/null || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc"; done && export PATH="$HOME/.local/bin:$PATH" && jame --help
+curl -fsSL https://raw.githubusercontent.com/HungerNet/JAMe/main/install.sh | bash
 ```
 
+The installer creates a dedicated environment under `$HOME/.local/share/jame`,
+installs the MapRes pre-release API, `jame`, and C2E, and links the command to
+`$HOME/.local/bin/jame`. It adds that directory to Bash or Zsh startup files;
+open a new shell if it was not already on your current PATH.
+
+Set `JAME_PYTHON` to select a specific Python 3.10+ executable. Set
+`JAME_INSTALL_DIR` or `JAME_BIN_DIR` to change the absolute install or bin path.
+
 ## CLI
 
-From a checkout, the Bash launcher can also be run directly; it uses the active
-virtual environment, the checkout's `.venv`, or `python3.10`, in that order:
+After installation, run the `jame` command from any directory:
 
 ```bash
-./jame.sh --help
-./jame.sh tests/files/solution.txt
+jame --help
+jame tests/files/solution.txt
 ```
 
-The default command finds a flag and extracts supported archives. The original
-path-only form remains supported:
+The default command finds a flag and extracts supported archives. The explicit
+`solve` form is also available:
 
 ```bash
-./jame.sh tests/files/solution.txt
-./jame.sh solve tests/files/solution.txt --format 'flag{*}'
+jame tests/files/solution.txt
+jame solve tests/files/solution.txt --format 'flag{*}'
 ```
 
 Use `*` for any-length text and `*N` for exactly `N` characters. Repeating
@@ -50,23 +55,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./jame.sh update
-./jame.sh update --pre
-./jame.sh find-flag tests/files/challenge.txt --format 'hcr{*4}'
-./jame.sh scan tests/files/scan.txt
-./jame.sh crypto tests/files/strings.txt --verbose
-./jame.sh binary tests/files/strings.txt
-./jame.sh stego tests/files/strings.txt
-./jame.sh forensics tests/files/strings.txt
-./jame.sh archive path/to/archive.zip --max-depth 2
-./jame.sh file-type tests/files/strings.txt
-./jame.sh strings tests/files/strings.txt
-./jame.sh binwalk path/to/file.bin
-./jame.sh caesar 'Khoor' --shift 3
+jame update
+jame update --pre
+jame find-flag tests/files/challenge.txt --format 'hcr{*4}'
+jame scan tests/files/scan.txt
+jame crypto tests/files/strings.txt --verbose
+jame binary tests/files/strings.txt
+jame stego tests/files/strings.txt
+jame forensics tests/files/strings.txt
+jame archive path/to/archive.zip --max-depth 2
+jame file-type tests/files/strings.txt
+jame strings tests/files/strings.txt
+jame binwalk path/to/file.bin
+jame caesar 'Khoor'
+jame caesar 'Khoor' --verbose
+jame caesar 'Khoor' --shift 3
 ```
 
 `--verbose` prints the structured result, including analyzer details and raw
-output where available. `binwalk` requires the external `binwalk` utility.
+output where available. Caesar brute force prints only its highest-ranked
+decoded candidate by default; `--verbose` shows the ranked candidates.
+`jame update` upgrades JAMe and C2E; `jame update --pre` also upgrades MapRes
+using prerelease versions. `binwalk` requires the external `binwalk` utility.
 
 ## Quickstart
 

{jame-1.0.dev2 → jame-1.0.dev3}/jame/cli/jame_cli.py

@@ -1,13 +1,27 @@
 '''Command-line entry point for JAMe.'''
 
 import json
+import os
 import subprocess
 import sys
 
 from c2e import LiveCLI, command
+from mapres import ascii_colors, rprint, res, setGlobalMaps
 
 from jame import Jame
 
+setGlobalMaps(ascii_colors)
+_COLOR_ENABLED = sys.stdout.isatty() and 'NO_COLOR' not in os.environ
+
+
+def _paint(text: object, color: str, *, bold: bool = False) -> str:
+    if not _COLOR_ENABLED:
+        return str(text)
+    style = res(f'<{color}>')
+    if bold:
+        style = res('<bold>') + style
+    return f'{style}{text}{res("<reset>")}'
+
 
 def _print_result(cli: LiveCLI, result: object, detailed: bool = False) -> None:
     if detailed:
@@ -15,15 +29,22 @@ def _print_result(cli: LiveCLI, result: object, detailed: bool = False) -> None:
         output = to_dict() if callable(to_dict) else result
         cli.safePrint(json.dumps(output, indent=2, default=str))
     elif hasattr(result, 'summary'):
-        cli.safePrint(result.summary)
+        if hasattr(result, 'flag'):
+            color = 'green' if result.flag else 'yellow'
+        else:
+            color = 'green' if getattr(result, 'confidence', 0.0) >= 0.7 else 'aqua'
+        cli.safePrint(_paint(result.summary, color))
+        if getattr(result, 'flag', None):
+            cli.safePrint(_paint(result.flag, 'green', bold=True))
     elif result is None:
-        cli.safePrint('No flag found.')
+        cli.safePrint(_paint('No flag found.', 'yellow'))
     elif isinstance(result, list):
-        cli.safePrint('\n'.join(str(item) for item in result) if result else 'No results.')
+        output = '\n'.join(str(item) for item in result) if result else 'No results.'
+        cli.safePrint(_paint(output, 'blue'))
     elif isinstance(result, (dict, tuple)):
-        cli.safePrint(json.dumps(result, indent=2, default=str))
+        cli.safePrint(_paint(json.dumps(result, indent=2, default=str), 'blue'))
     else:
-        cli.safePrint(result)
+        cli.safePrint(_paint(result, 'aqua'))
 
 
 @command('solve')
@@ -131,7 +152,16 @@ def caesar(cli: LiveCLI, text: str) -> None:
             cli.safePrint("Error: --shift must be an integer or 'brute'")
             raise SystemExit(2) from None
     result = Jame().decodeCaesar(text, shift_value)
-    _print_result(cli, result, verbose())
+    if verbose():
+        _print_result(cli, result, detailed=True)
+    elif shift_value == 'brute':
+        best = result.get('best')
+        if best:
+            cli.safePrint(_paint(best['decoded'], 'green', bold=True))
+        else:
+            cli.safePrint(_paint('No Caesar candidate found.', 'yellow'))
+    else:
+        cli.safePrint(_paint(result.get('decoded', result.get('error', '')), 'green'))
 
 
 @caesar.param('shift', type=str, default='brute')
@@ -148,12 +178,14 @@ def _caesar_verbose(value):
 
 @command('update')
 def update(cli: LiveCLI) -> None:
-    '''Upgrade JAMe and its C2E CLI dependency.'''
-    cli.safePrint('Updating JAMe...')
+    '''Upgrade JAMe and C2E, optionally including the MapRes prerelease.'''
+    rprint(_paint('Updating JAMe...', 'aqua'))
     command = [sys.executable, '-m', 'pip', 'install', '--upgrade']
     if pre():
         command.append('--pre')
     command.extend(['c2e', 'jame'])
+    if pre():
+        command.append('mapres')
     result = subprocess.run(command, check=False)
     if result.returncode:
         raise SystemExit(result.returncode)

{jame-1.0.dev2 → jame-1.0.dev3}/jame.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jame
-Version: 1.0.dev2
+Version: 1.0.dev3
 Summary: Just Another Method of Exploitation
 Author: JAMe Contributors
 License: MIT
@@ -20,6 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: c2e
+Requires-Dist: mapres
 Requires-Dist: PyYAML>=6.0
 Dynamic: license-file
 
@@ -41,31 +42,36 @@ JAMe is a lightweight forensic and triage toolkit for scanning files, extracting
 
 ## Installation
 
-JAMe requires Python 3.10 or newer. From the repository root, this one-line
-installer creates the virtual environment, installs JAMe, links the command
-into the absolute path `$HOME/.local/bin`, and adds that directory to the
-current shell and future Bash login/interactive shells:
+JAMe requires Python 3.10 or newer. Install the latest published package and
+register `jame` on your user PATH with:
 
 ```bash
-python3 -m venv .venv && .venv/bin/pip install jame && mkdir -p "$HOME/.local/bin" && if [[ -e "$HOME/.local/bin/jame" && ! "$HOME/.local/bin/jame" -ef "$(pwd -P)/.venv/bin/jame" ]]; then printf '%s\n' 'Refusing to replace existing command at ~/.local/bin/jame' >&2; exit 1; fi && ln -sfn "$(pwd -P)/.venv/bin/jame" "$HOME/.local/bin/jame" && for rc in "$HOME/.profile" "$HOME/.bashrc"; do grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$rc" 2>/dev/null || printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$rc"; done && export PATH="$HOME/.local/bin:$PATH" && jame --help
+curl -fsSL https://raw.githubusercontent.com/HungerNet/JAMe/main/install.sh | bash
 ```
 
+The installer creates a dedicated environment under `$HOME/.local/share/jame`,
+installs the MapRes pre-release API, `jame`, and C2E, and links the command to
+`$HOME/.local/bin/jame`. It adds that directory to Bash or Zsh startup files;
+open a new shell if it was not already on your current PATH.
+
+Set `JAME_PYTHON` to select a specific Python 3.10+ executable. Set
+`JAME_INSTALL_DIR` or `JAME_BIN_DIR` to change the absolute install or bin path.
+
 ## CLI
 
-From a checkout, the Bash launcher can also be run directly; it uses the active
-virtual environment, the checkout's `.venv`, or `python3.10`, in that order:
+After installation, run the `jame` command from any directory:
 
 ```bash
-./jame.sh --help
-./jame.sh tests/files/solution.txt
+jame --help
+jame tests/files/solution.txt
 ```
 
-The default command finds a flag and extracts supported archives. The original
-path-only form remains supported:
+The default command finds a flag and extracts supported archives. The explicit
+`solve` form is also available:
 
 ```bash
-./jame.sh tests/files/solution.txt
-./jame.sh solve tests/files/solution.txt --format 'flag{*}'
+jame tests/files/solution.txt
+jame solve tests/files/solution.txt --format 'flag{*}'
 ```
 
 Use `*` for any-length text and `*N` for exactly `N` characters. Repeating
@@ -75,23 +81,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./jame.sh update
-./jame.sh update --pre
-./jame.sh find-flag tests/files/challenge.txt --format 'hcr{*4}'
-./jame.sh scan tests/files/scan.txt
-./jame.sh crypto tests/files/strings.txt --verbose
-./jame.sh binary tests/files/strings.txt
-./jame.sh stego tests/files/strings.txt
-./jame.sh forensics tests/files/strings.txt
-./jame.sh archive path/to/archive.zip --max-depth 2
-./jame.sh file-type tests/files/strings.txt
-./jame.sh strings tests/files/strings.txt
-./jame.sh binwalk path/to/file.bin
-./jame.sh caesar 'Khoor' --shift 3
+jame update
+jame update --pre
+jame find-flag tests/files/challenge.txt --format 'hcr{*4}'
+jame scan tests/files/scan.txt
+jame crypto tests/files/strings.txt --verbose
+jame binary tests/files/strings.txt
+jame stego tests/files/strings.txt
+jame forensics tests/files/strings.txt
+jame archive path/to/archive.zip --max-depth 2
+jame file-type tests/files/strings.txt
+jame strings tests/files/strings.txt
+jame binwalk path/to/file.bin
+jame caesar 'Khoor'
+jame caesar 'Khoor' --verbose
+jame caesar 'Khoor' --shift 3
 ```
 
 `--verbose` prints the structured result, including analyzer details and raw
-output where available. `binwalk` requires the external `binwalk` utility.
+output where available. Caesar brute force prints only its highest-ranked
+decoded candidate by default; `--verbose` shows the ranked candidates.
+`jame update` upgrades JAMe and C2E; `jame update --pre` also upgrades MapRes
+using prerelease versions. `binwalk` requires the external `binwalk` utility.
 
 ## Quickstart
 

{jame-1.0.dev2 → jame-1.0.dev3}/jame.egg-info/requires.txt

@@ -1,2 +1,3 @@
 c2e
+mapres
 PyYAML>=6.0

{jame-1.0.dev2 → jame-1.0.dev3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jame"
-version = "1.0-dev.2"
+version = "1.0-dev.3"
 description = "Just Another Method of Exploitation"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,7 @@ keywords = [
 ]
 dependencies = [
     "c2e",
+    "mapres",
     "PyYAML>=6.0",
 ]
 classifiers = [

{jame-1.0.dev2 → jame-1.0.dev3}/tests/test_cli.py

@@ -4,16 +4,26 @@ import json
 import sys
 from types import SimpleNamespace
 
+from mapres import ascii_colors
+
 from jame.cli import jame_cli
 from jame.cli.jame_cli import main
 
 
 def run_cli(monkeypatch, capsys, *arguments: str) -> str:
     monkeypatch.setattr(sys, 'argv', ['jame', *arguments])
+    monkeypatch.setattr(jame_cli, '_COLOR_ENABLED', False)
     main()
     return capsys.readouterr().out
 
 
+def test_cli_uses_mapres_color_tokens(monkeypatch):
+    '''Render color tokens from MapRes's registered ASCII map.'''
+    monkeypatch.setattr(jame_cli, '_COLOR_ENABLED', True)
+
+    assert jame_cli._paint('candidate', 'orange') == f'{ascii_colors.orange}candidate{ascii_colors.reset}'
+
+
 def test_cli_uses_numbered_wildcard_for_exact_length(monkeypatch, capsys):
     '''Treat numbered wildcard length as exact and unnumbered stars as open-ended.'''
     unbounded = run_cli(
@@ -52,11 +62,26 @@ def test_cli_verbose_prints_structured_analyzer_details(monkeypatch, capsys):
 
 
 def test_cli_supports_caesar_method(monkeypatch, capsys):
-    '''Expose the Caesar decoder as a CLI command.'''
-    output = run_cli(monkeypatch, capsys, 'caesar', 'Khoor', '--shift', '3')
+    '''Return only the best Caesar decode by default.'''
+    output = run_cli(monkeypatch, capsys, 'caesar', 'Khoor')
+
+    assert output.strip() == 'Hello'
+
+
+def test_cli_caesar_verbose_shows_ranked_candidates(monkeypatch, capsys):
+    '''Expose ranked Caesar candidates through verbose output.'''
+    output = run_cli(monkeypatch, capsys, 'caesar', 'Khoor', '--verbose')
 
     result = json.loads(output)
-    assert result == {'shift': 3, 'decoded': 'Hello'}
+    assert result['best']['decoded'] == 'Hello'
+    assert len(result['results']) == 25
+
+
+def test_cli_caesar_explicit_shift(monkeypatch, capsys):
+    '''Decode one Caesar shift without verbose metadata.'''
+    output = run_cli(monkeypatch, capsys, 'caesar', 'Khoor', '--shift', '3')
+
+    assert output.strip() == 'Hello'
 
 
 def test_cli_update_pre_requests_prereleases(monkeypatch, capsys):
@@ -71,5 +96,21 @@ def test_cli_update_pre_requests_prereleases(monkeypatch, capsys):
     run_cli(monkeypatch, capsys, 'update', '--pre')
 
     arguments, check = calls[0]
-    assert arguments[-4:] == ['--upgrade', '--pre', 'c2e', 'jame']
-    assert check is False
+    assert arguments[-5:] == ['--upgrade', '--pre', 'c2e', 'jame', 'mapres']
+    assert check is False
+
+
+def test_cli_stable_update_leaves_mapres_prerelease_installed(monkeypatch, capsys):
+    '''Avoid downgrading the required MapRes API during a stable update.'''
+    calls = []
+
+    def fake_run(arguments, check):
+        calls.append(arguments)
+        return SimpleNamespace(returncode=0)
+
+    monkeypatch.setattr(jame_cli.subprocess, 'run', fake_run)
+    run_cli(monkeypatch, capsys, 'update')
+
+    assert calls[0][-2:] == ['c2e', 'jame']
+    assert '--pre' not in calls[0]
+    assert 'mapres' not in calls[0]