jame 1.0.dev0__tar.gz → 1.0.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jame
-Version: 1.0.dev0
+Version: 1.0.dev3
 Summary: Just Another Method of Exploitation
 Author: JAMe Contributors
 License: MIT
@@ -19,6 +19,8 @@ Classifier: Development Status :: 4 - Beta
 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
 
@@ -40,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
@@ -74,21 +81,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./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.dev0 → 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,21 +55,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./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.dev3/jame/cli/jame_cli.py

@@ -0,0 +1,210 @@
+'''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:
+        to_dict = getattr(result, 'to_dict', None)
+        output = to_dict() if callable(to_dict) else result
+        cli.safePrint(json.dumps(output, indent=2, default=str))
+    elif hasattr(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(_paint('No flag found.', 'yellow'))
+    elif isinstance(result, list):
+        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(_paint(json.dumps(result, indent=2, default=str), 'blue'))
+    else:
+        cli.safePrint(_paint(result, 'aqua'))
+
+
+@command('solve')
+def solve(cli: LiveCLI, path: str) -> None:
+    '''Find a flag and extract supported archives.'''
+    engine = Jame(flag_patterns=[format()], max_depth=max_depth(), verbose=verbose())
+    result = engine.autoSolve(
+        path,
+        format=format(),
+        maxDepth=max_depth(),
+        verbose=verbose(),
+    )
+    _print_result(cli, result, verbose())
+
+
+@solve.param('format', type=str, default='flag{*}')
+def _solve_format(value):
+    '''Flag pattern; '*' matches any length and '*N' matches exactly N characters.'''
+    return value
+
+
+@solve.param('max-depth', type=int, default=3)
+def _solve_max_depth(value):
+    '''Maximum recursive archive extraction depth.'''
+    return value
+
+
+@solve.flag('verbose')
+def _solve_verbose(value):
+    '''Print structured result details.'''
+    return value
+
+
+@command('find-flag')
+def find_flag(cli: LiveCLI, path: str) -> None:
+    '''Find a flag matching a wildcard pattern.'''
+    result = Jame().findFlag(path, format())
+    _print_result(cli, result, verbose())
+
+
+@find_flag.param('format', type=str, default='flag{*}')
+def _find_flag_format(value):
+    '''Flag pattern; '*' matches any length and '*N' matches exactly N characters.'''
+    return value
+
+
+@find_flag.flag('verbose')
+def _find_flag_verbose(value):
+    '''Print structured result details.'''
+    return value
+
+
+def _register_path_command(name: str, method_name: str, description: str) -> None:
+    @command(name)
+    def handler(cli: LiveCLI, path: str) -> None:
+        result = getattr(Jame(), method_name)(path)
+        _print_result(cli, result, verbose())
+
+    handler.func.__doc__ = description
+    handler.desc = description
+    def verbose_flag(value):
+        '''Print structured result details.'''
+        return value
+
+    handler.flag('verbose')(verbose_flag)
+
+
+_register_path_command('scan', 'scanFile', 'Run all available analyzers.')
+_register_path_command('crypto', 'cryptoAnalyze', 'Analyze crypto indicators.')
+_register_path_command('binary', 'binaryAnalyze', 'Analyze binary indicators.')
+_register_path_command('stego', 'stegoAnalyze', 'Check for steganography indicators.')
+_register_path_command('forensics', 'forensicsAnalyze', 'Run forensic checks.')
+_register_path_command('file-type', 'getFileType', 'Detect the file type.')
+_register_path_command('strings', 'runStrings', 'Extract printable strings.')
+_register_path_command('binwalk', 'runBinwalk', 'Run binwalk when installed.')
+
+
+@command('archive')
+def archive(cli: LiveCLI, path: str) -> None:
+    '''Extract supported archives.'''
+    engine = Jame(max_depth=max_depth(), verbose=verbose())
+    _print_result(cli, engine.archiveExtract(path), verbose())
+
+
+@archive.param('max-depth', type=int, default=3)
+def _archive_max_depth(value):
+    '''Maximum recursive archive extraction depth.'''
+    return value
+
+
+@archive.flag('verbose')
+def _archive_verbose(value):
+    '''Print structured result details.'''
+    return value
+
+
+@command('caesar')
+def caesar(cli: LiveCLI, text: str) -> None:
+    '''Decode Caesar-shifted text.'''
+    shift_value = shift()
+    if shift_value != 'brute':
+        try:
+            shift_value = int(shift_value)
+        except ValueError:
+            cli.safePrint("Error: --shift must be an integer or 'brute'")
+            raise SystemExit(2) from None
+    result = Jame().decodeCaesar(text, shift_value)
+    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')
+def _caesar_shift(value):
+    '''Integer shift or 'brute' to check every Caesar shift.'''
+    return value
+
+
+@caesar.flag('verbose')
+def _caesar_verbose(value):
+    '''Print structured result details.'''
+    return value
+
+
+@command('update')
+def update(cli: LiveCLI) -> None:
+    '''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)
+
+
+@update.flag('pre')
+def _update_pre(value):
+    '''Include pre-release versions when upgrading.'''
+    return value
+
+
+def main() -> None:
+    '''Parse command-line options and dispatch them through C2E.'''
+    LiveCLI().run_argv(
+        prog='jame',
+        description='Just Another Method of Exploitation',
+        default_command='solve',
+    )
+
+
+if __name__ == '__main__':
+    main()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jame
-Version: 1.0.dev0
+Version: 1.0.dev3
 Summary: Just Another Method of Exploitation
 Author: JAMe Contributors
 License: MIT
@@ -19,6 +19,8 @@ Classifier: Development Status :: 4 - Beta
 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
 
@@ -40,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
@@ -74,21 +81,28 @@ to require five characters, not `hcr{*****}`.
 Other available methods:
 
 ```bash
-./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.dev0 → jame-1.0.dev3}/jame.egg-info/requires.txt

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

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

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

jame-1.0.dev3/tests/test_cli.py

@@ -0,0 +1,116 @@
+'''Integration tests for the JAMe command-line interface.'''
+
+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(
+        monkeypatch,
+        capsys,
+        'tests/files/challenge.txt',
+        '--format',
+        'hcr{*****}',
+    )
+    assert 'hcr{abcd}' in unbounded
+
+    exact = run_cli(
+        monkeypatch,
+        capsys,
+        'tests/files/challenge.txt',
+        '--format',
+        'hcr{*5}',
+    )
+    assert 'No flag extracted.' in exact
+    assert 'hcr{abcd}' not in exact
+
+
+def test_cli_verbose_prints_structured_analyzer_details(monkeypatch, capsys):
+    '''Expose structured result details with the verbose flag.'''
+    output = run_cli(
+        monkeypatch,
+        capsys,
+        'crypto',
+        'tests/files/strings.txt',
+        '--verbose',
+    )
+
+    result = json.loads(output)
+    assert result['file_path'] == 'tests/files/strings.txt'
+    assert 'findings' in result
+
+
+def test_cli_supports_caesar_method(monkeypatch, capsys):
+    '''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['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):
+    '''Pass --pre through to pip when updating JAMe and C2E.'''
+    calls = []
+
+    def fake_run(arguments, check):
+        calls.append((arguments, check))
+        return SimpleNamespace(returncode=0)
+
+    monkeypatch.setattr(jame_cli.subprocess, 'run', fake_run)
+    run_cli(monkeypatch, capsys, 'update', '--pre')
+
+    arguments, check = calls[0]
+    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]

jame-1.0.dev0/jame/cli/jame_cli.py

@@ -1,151 +0,0 @@
-'''Command-line entry point for JAMe.'''
-
-import argparse
-import json
-import sys
-
-from jame import Jame
-
-
-_COMMANDS = {
-    'archive',
-    'binary',
-    'binwalk',
-    'caesar',
-    'crypto',
-    'file-type',
-    'find-flag',
-    'forensics',
-    'scan',
-    'solve',
-    'stego',
-    'strings',
-}
-
-
-def _add_path_arguments(command: argparse.ArgumentParser) -> None:
-    command.add_argument('path', help='Path to the file to analyze')
-    command.add_argument('--verbose', action='store_true', help='Print structured result details')
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog='jame',
-        description='Just Another Method of Exploitation',
-    )
-    subparsers = parser.add_subparsers(dest='command', required=True)
-
-    solve = subparsers.add_parser('solve', help='Find a flag and extract supported archives')
-    _add_path_arguments(solve)
-    solve.add_argument(
-        '--format',
-        default='flag{*}',
-        help="Flag pattern; '*' matches any length and '*N' matches exactly N characters",
-    )
-    solve.add_argument('--max-depth', type=int, default=3, help='Archive extraction depth')
-
-    find_flag = subparsers.add_parser('find-flag', help='Find a flag matching a pattern')
-    _add_path_arguments(find_flag)
-    find_flag.add_argument(
-        '--format',
-        default='flag{*}',
-        help="Flag pattern; '*' matches any length and '*N' matches exactly N characters",
-    )
-
-    for name, description in (
-        ('scan', 'Run all available analyzers'),
-        ('crypto', 'Analyze crypto indicators'),
-        ('binary', 'Analyze binary indicators'),
-        ('stego', 'Check for steganography indicators'),
-        ('forensics', 'Run forensic checks'),
-        ('file-type', 'Detect the file type'),
-        ('strings', 'Extract printable strings'),
-        ('binwalk', 'Run binwalk when installed'),
-    ):
-        command = subparsers.add_parser(name, help=description)
-        _add_path_arguments(command)
-
-    archive = subparsers.add_parser('archive', help='Extract supported archives')
-    _add_path_arguments(archive)
-    archive.add_argument('--max-depth', type=int, default=3, help='Archive extraction depth')
-
-    caesar = subparsers.add_parser('caesar', help='Decode Caesar-shifted text')
-    caesar.add_argument('text', help='Text to decode')
-    caesar.add_argument('--shift', default='brute', help="Integer shift or 'brute'")
-    caesar.add_argument('--verbose', action='store_true', help='Print structured result details')
-
-    return parser
-
-
-def _print_result(result: object, verbose: bool) -> None:
-    if verbose:
-        to_dict = getattr(result, 'to_dict', None)
-        output = to_dict() if callable(to_dict) else result
-        print(json.dumps(output, indent=2, default=str))
-    elif hasattr(result, 'summary'):
-        print(result.summary)
-    elif result is None:
-        print('No flag found.')
-    elif isinstance(result, list):
-        print('\n'.join(str(item) for item in result) if result else 'No results.')
-    elif isinstance(result, (dict, tuple)):
-        print(json.dumps(result, indent=2, default=str))
-    else:
-        print(result)
-
-
-def main() -> None:
-    '''Parse command-line options and run the requested JAMe method.'''
-    argv = sys.argv[1:]
-    if argv and argv[0] not in _COMMANDS and argv[0] not in {'-h', '--help'}:
-        argv.insert(0, 'solve')
-
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    max_depth = getattr(args, 'max_depth', 3)
-    engine = Jame(
-        flag_patterns=[getattr(args, 'format', 'flag{*}')],
-        max_depth=max_depth,
-        verbose=args.verbose,
-    )
-
-    if args.command == 'solve':
-        result = engine.autoSolve(
-            args.path,
-            format=args.format,
-            maxDepth=args.max_depth,
-            verbose=args.verbose,
-        )
-    elif args.command == 'find-flag':
-        result = engine.findFlag(args.path, args.format)
-    elif args.command == 'scan':
-        result = engine.scanFile(args.path)
-    elif args.command == 'crypto':
-        result = engine.cryptoAnalyze(args.path)
-    elif args.command == 'binary':
-        result = engine.binaryAnalyze(args.path)
-    elif args.command == 'stego':
-        result = engine.stegoAnalyze(args.path)
-    elif args.command == 'forensics':
-        result = engine.forensicsAnalyze(args.path)
-    elif args.command == 'archive':
-        engine.setMaxDepth(args.max_depth)
-        result = engine.archiveExtract(args.path)
-    elif args.command == 'file-type':
-        result = engine.getFileType(args.path)
-    elif args.command == 'strings':
-        result = engine.runStrings(args.path)
-    elif args.command == 'binwalk':
-        result = engine.runBinwalk(args.path)
-    else:
-        try:
-            shift = 'brute' if args.shift == 'brute' else int(args.shift)
-        except ValueError:
-            parser.error("--shift must be an integer or 'brute'")
-        result = engine.decodeCaesar(args.text, shift)
-
-    _print_result(result, args.verbose)
-
-
-if __name__ == '__main__':
-    main()

jame-1.0.dev0/tests/test_cli.py

@@ -1,57 +0,0 @@
-'''Integration tests for the JAMe command-line interface.'''
-
-import json
-import sys
-
-from jame.cli.jame_cli import main
-
-
-def run_cli(monkeypatch, capsys, *arguments: str) -> str:
-    monkeypatch.setattr(sys, 'argv', ['jame', *arguments])
-    main()
-    return capsys.readouterr().out
-
-
-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(
-        monkeypatch,
-        capsys,
-        'tests/files/challenge.txt',
-        '--format',
-        'hcr{*****}',
-    )
-    assert 'hcr{abcd}' in unbounded
-
-    exact = run_cli(
-        monkeypatch,
-        capsys,
-        'tests/files/challenge.txt',
-        '--format',
-        'hcr{*5}',
-    )
-    assert 'No flag extracted.' in exact
-    assert 'hcr{abcd}' not in exact
-
-
-def test_cli_verbose_prints_structured_analyzer_details(monkeypatch, capsys):
-    '''Expose structured result details with the verbose flag.'''
-    output = run_cli(
-        monkeypatch,
-        capsys,
-        'crypto',
-        'tests/files/strings.txt',
-        '--verbose',
-    )
-
-    result = json.loads(output)
-    assert result['file_path'] == 'tests/files/strings.txt'
-    assert 'findings' in result
-
-
-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')
-
-    result = json.loads(output)
-    assert result == {'shift': 3, 'decoded': 'Hello'}