oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/cli/main.py

@@ -1,19 +1,23 @@
-"""Oscura Core CLI Framework implementing CLI-001.
+"""Oscura Core CLI Framework implementing CLI-001 (Enhanced Edition).
 
 Provides the main entry point for the oscura command-line interface with
-support for multiple output formats and verbose logging.
+comprehensive subcommands, interactive mode, batch processing, configuration
+management, and shell completion support.
 
 
 Example:
     $ oscura --help
-    $ oscura characterize signal.wfm --output json
-    $ oscura decode uart.wfm -vv
+    $ oscura analyze signal.wfm --output json
+    $ oscura decode uart capture.wfm --baud-rate 115200
     $ oscura shell   # Interactive REPL
+    $ oscura config --show  # View configuration
+    $ oscura plugins list  # Manage plugins
 """
 
 import json
 import logging
 import sys
+from pathlib import Path
 from typing import Any
 
 import click
@@ -126,37 +130,98 @@ def format_output(data: dict[str, Any], format_type: str) -> str:
     return formatter(data)
 
 
-@click.group()  # type: ignore[misc]
-@click.option(  # type: ignore[misc]
+def load_config_file(config_path: Path | None = None) -> dict[str, Any]:
+    """Load configuration from YAML file.
+
+    Args:
+        config_path: Path to config file. If None, searches for config in:
+            1. .oscura.yaml in current directory
+            2. ~/.config/oscura/config.yaml
+
+    Returns:
+        Configuration dictionary.
+    """
+    import yaml
+
+    if config_path is None:
+        # Search for config files
+        candidates = [
+            Path(".oscura.yaml"),
+            Path.home() / ".config" / "oscura" / "config.yaml",
+        ]
+        for candidate in candidates:
+            if candidate.exists():
+                config_path = candidate
+                break
+
+    if config_path is None or not config_path.exists():
+        return {}
+
+    with open(config_path) as f:
+        return yaml.safe_load(f) or {}
+
+
+@click.group()
+@click.option(
     "-v",
     "--verbose",
     count=True,
     help="Increase verbosity (-v for INFO, -vv for DEBUG).",
 )
-@click.version_option(version="0.1.0", prog_name="oscura")  # type: ignore[misc]
-@click.pass_context  # type: ignore[misc]
-def cli(ctx: click.Context, verbose: int) -> None:
-    """Oscura - Signal Analysis Framework for Oscilloscope Data.
-
-    Command-line tools for characterizing buffers, decoding protocols,
-    analyzing spectra, and comparing signals.
+@click.option(
+    "--config",
+    type=click.Path(exists=True),
+    default=None,
+    help="Path to configuration file (YAML).",
+)
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    help="Quiet mode (suppress non-error output).",
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="JSON output mode for scripting.",
+)
+@click.version_option(prog_name="oscura")  # Version auto-detected from package metadata
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    verbose: int,
+    config: str | None,
+    quiet: bool,
+    json_output: bool,
+) -> None:
+    """Oscura - Hardware Reverse Engineering Framework.
+
+    Unified framework for extracting all information from hardware systems through
+    signals and data. Features unknown protocol discovery, state machine extraction,
+    CRC recovery, and security analysis.
 
     Args:
         ctx: Click context object.
         verbose: Verbosity level (0=WARNING, 1=INFO, 2+=DEBUG).
+        config: Path to configuration file.
+        quiet: Quiet mode flag.
+        json_output: JSON output mode flag.
 
     Examples:
-        oscura characterize signal.wfm
+        oscura analyze signal.wfm
         oscura decode uart.wfm --protocol auto
         oscura batch '*.wfm' --analysis characterize
-        oscura compare before.wfm after.wfm
+        oscura visualize trace.wfm
         oscura shell  # Interactive REPL
     """
     # Ensure ctx.obj exists
     ctx.ensure_object(dict)
 
     # Set logging level based on verbosity
-    if verbose == 0:
+    if quiet:
+        logger.setLevel(logging.ERROR)
+    elif verbose == 0:
         logger.setLevel(logging.WARNING)
     elif verbose == 1:
         logger.setLevel(logging.INFO)
@@ -166,9 +231,28 @@ def cli(ctx: click.Context, verbose: int) -> None:
         logger.debug("Debug mode enabled")
 
     ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+    ctx.obj["json_output"] = json_output
+
+    # Load configuration
+    config_path = Path(config) if config else None
+    ctx.obj["config"] = load_config_file(config_path)
 
 
-@click.command()  # type: ignore[misc]
+# Enhanced subcommands - imported below
+from oscura.cli.analyze import analyze
+from oscura.cli.batch import batch
+from oscura.cli.benchmark import benchmark
+from oscura.cli.characterize import characterize
+from oscura.cli.compare import compare
+from oscura.cli.config_cmd import config as config_cmd
+from oscura.cli.decode import decode
+from oscura.cli.export import export
+from oscura.cli.validate_cmd import validate
+from oscura.cli.visualize import visualize
+
+
+@click.command()
 def shell() -> None:
     """Start an interactive Oscura shell.
 
@@ -177,7 +261,7 @@ def shell() -> None:
 
     Example:
         $ oscura shell
-        Oscura Shell v0.1.0
+        Oscura Shell v0.6.0
         >>> trace = load("signal.wfm")
         >>> rise_time(trace)
     """
@@ -186,9 +270,9 @@ def shell() -> None:
     start_shell()
 
 
-@click.command()  # type: ignore[misc]
-@click.argument("tutorial_id", required=False, default=None)  # type: ignore[misc]
-@click.option("--list", "list_tutorials", is_flag=True, help="List available tutorials")  # type: ignore[misc]
+@click.command()
+@click.argument("tutorial_id", required=False, default=None)
+@click.option("--list", "list_tutorials", is_flag=True, help="List available tutorials")
 def tutorial(tutorial_id: str | None, list_tutorials: bool) -> None:
     """Run an interactive tutorial.
 
@@ -202,8 +286,8 @@ def tutorial(tutorial_id: str | None, list_tutorials: bool) -> None:
         oscura tutorial --list           # List available tutorials
         oscura tutorial getting_started  # Run the getting started tutorial
     """
-    from oscura.onboarding import list_tutorials as list_tut
-    from oscura.onboarding import run_tutorial
+    from oscura.cli.onboarding import list_tutorials as list_tut
+    from oscura.cli.onboarding import run_tutorial
 
     if list_tutorials or tutorial_id is None:
         tutorials = list_tut()
@@ -217,15 +301,15 @@ def tutorial(tutorial_id: str | None, list_tutorials: bool) -> None:
     run_tutorial(tutorial_id, interactive=True)
 
 
-# Import subcommands
-from oscura.cli.batch import batch  # noqa: E402
-from oscura.cli.characterize import characterize  # noqa: E402
-from oscura.cli.compare import compare  # noqa: E402
-from oscura.cli.decode import decode  # noqa: E402
-
-# Register subcommands
-cli.add_command(characterize)  # type: ignore[has-type]
+# Register all subcommands
+cli.add_command(analyze)  # type: ignore[has-type]
 cli.add_command(decode)  # type: ignore[has-type]
+cli.add_command(export)
+cli.add_command(visualize)
+cli.add_command(benchmark)
+cli.add_command(validate)
+cli.add_command(config_cmd, name="config")
+cli.add_command(characterize)  # type: ignore[has-type]
 cli.add_command(batch)  # type: ignore[has-type]
 cli.add_command(compare)  # type: ignore[has-type]
 cli.add_command(shell)

oscura/{onboarding → cli/onboarding}/__init__.py

@@ -4,20 +4,20 @@ This package provides interactive tutorials, context-sensitive help,
 and guided analysis features for new users.
 """
 
-from oscura.onboarding.help import (
+from oscura.cli.onboarding.help import (
     explain_result,
     get_example,
     get_help,
     suggest_commands,
 )
-from oscura.onboarding.tutorials import (
+from oscura.cli.onboarding.tutorials import (
     Tutorial,
     TutorialStep,
     get_tutorial,
     list_tutorials,
     run_tutorial,
 )
-from oscura.onboarding.wizard import (
+from oscura.cli.onboarding.wizard import (
     AnalysisWizard,
     WizardStep,
     run_wizard,

oscura/{onboarding → cli/onboarding}/help.py

@@ -5,7 +5,7 @@ context, and result explanations for non-expert users.
 
 
 Example:
-    >>> from oscura.onboarding import get_help, suggest_commands
+    >>> from oscura.cli.onboarding import get_help, suggest_commands
     >>> get_help("rise_time")
     >>> suggest_commands(trace)
 """
@@ -252,22 +252,7 @@ def suggest_commands(trace: Any = None, context: str | None = None) -> list[dict
     suggestions = []
 
     if trace is None:
-        # No trace loaded - suggest loading
-        suggestions.append(
-            {
-                "command": "trace = load('file.csv')",
-                "description": "Load a trace file to get started",
-                "reason": "No trace loaded yet",
-            }
-        )
-        suggestions.append(
-            {
-                "command": "formats = get_supported_formats()",
-                "description": "See what file formats are supported",
-                "reason": "Helpful for knowing what files you can load",
-            }
-        )
-        return suggestions
+        return _suggest_loading_commands()
 
     # Trace is loaded - suggest measurements
     suggestions.append(
@@ -278,7 +263,48 @@ def suggest_commands(trace: Any = None, context: str | None = None) -> list[dict
         }
     )
 
-    # Check if it looks like digital signal
+    # Add signal type-specific suggestions
+    _add_signal_type_suggestions(suggestions, trace)
+
+    # Always suggest filtering for noisy signals
+    suggestions.append(
+        {
+            "command": "filtered = low_pass(trace, cutoff_hz)",
+            "description": "Apply low-pass filter to remove noise",
+            "reason": "Clean up high-frequency noise",
+        }
+    )
+
+    # Add context-specific suggestions
+    if context:
+        _add_context_suggestions(suggestions, context)
+
+    return suggestions
+
+
+def _suggest_loading_commands() -> list[dict[str, str]]:
+    """Get suggestions when no trace is loaded."""
+    return [
+        {
+            "command": "trace = load('file.csv')",
+            "description": "Load a trace file to get started",
+            "reason": "No trace loaded yet",
+        },
+        {
+            "command": "formats = get_supported_formats()",
+            "description": "See what file formats are supported",
+            "reason": "Helpful for knowing what files you can load",
+        },
+    ]
+
+
+def _add_signal_type_suggestions(suggestions: list[dict[str, str]], trace: Any) -> None:
+    """Add signal type-specific suggestions.
+
+    Args:
+        suggestions: List to append suggestions to.
+        trace: Trace object to analyze.
+    """
     if hasattr(trace, "data"):
         import numpy as np
 
@@ -318,47 +344,43 @@ def suggest_commands(trace: Any = None, context: str | None = None) -> list[dict
                 }
             )
 
-    # Always suggest filtering for noisy signals
-    suggestions.append(
-        {
-            "command": "filtered = low_pass(trace, cutoff_hz)",
-            "description": "Apply low-pass filter to remove noise",
-            "reason": "Clean up high-frequency noise",
-        }
-    )
 
-    # Context-specific suggestions
-    if context:
-        context_lower = context.lower()
-        if "uart" in context_lower or "serial" in context_lower:
-            suggestions.insert(
-                0,
-                {
-                    "command": "packets = decode_uart(trace)",
-                    "description": "Decode UART serial data",
-                    "reason": "You mentioned UART/serial",
-                },
-            )
-        elif "spi" in context_lower:
-            suggestions.insert(
-                0,
-                {
-                    "command": "packets = decode_spi(clk_trace, data_trace)",
-                    "description": "Decode SPI bus",
-                    "reason": "You mentioned SPI",
-                },
-            )
-        elif "i2c" in context_lower:
-            suggestions.insert(
-                0,
-                {
-                    "command": "packets = decode_i2c(scl_trace, sda_trace)",
-                    "description": "Decode I2C bus",
-                    "reason": "You mentioned I2C",
-                },
-            )
+def _add_context_suggestions(suggestions: list[dict[str, str]], context: str) -> None:
+    """Add context-specific suggestions based on user intent.
 
-    return suggestions
+    Args:
+        suggestions: List to prepend suggestions to.
+        context: User context string.
+    """
+    context_lower = context.lower()
+
+    if "uart" in context_lower or "serial" in context_lower:
+        suggestions.insert(
+            0,
+            {
+                "command": "packets = decode_uart(trace)",
+                "description": "Decode UART serial data",
+                "reason": "You mentioned UART/serial",
+            },
+        )
+    elif "spi" in context_lower:
+        suggestions.insert(
+            0,
+            {
+                "command": "packets = decode_spi(clk_trace, data_trace)",
+                "description": "Decode SPI bus",
+                "reason": "You mentioned SPI",
+            },
+        )
+    elif "i2c" in context_lower:
+        suggestions.insert(
+            0,
+            {
+                "command": "packets = decode_i2c(scl_trace, sda_trace)",
+                "description": "Decode I2C bus",
+                "reason": "You mentioned I2C",
+            },
+        )
 
 
 def explain_result(
@@ -389,7 +411,7 @@ def explain_result(
     }
 
     if measurement.lower() in explanations:
-        return explanations[measurement.lower()](value)  # type: ignore[no-untyped-call]
+        return explanations[measurement.lower()](value)
 
     # Generic explanation
     return f"{measurement}: {value}"

oscura/{onboarding → cli/onboarding}/tutorials.py

@@ -9,7 +9,7 @@ covering common analysis workflows.
   - Progress tracking
 
 Example:
-    >>> from oscura.onboarding import run_tutorial
+    >>> from oscura.cli.onboarding import run_tutorial
     >>> run_tutorial("getting_started")
     Welcome to Oscura!
     Step 1/5: Loading a trace file
@@ -71,16 +71,47 @@ TUTORIALS: dict[str, Tutorial] = {}
 def _register_getting_started() -> None:
     """Register the getting started tutorial."""
     steps = [
-        TutorialStep(
-            title="Loading a Trace File",
-            description="""
+        _create_loading_step(),
+        _create_measurements_step(),
+        _create_spectral_step(),
+        _create_protocol_step(),
+        _create_discovery_step(),
+    ]
+
+    tutorial = Tutorial(
+        id="getting_started",
+        title="Getting Started with Oscura",
+        description="""
+Welcome to Oscura! This tutorial will teach you the basics of
+signal analysis in 5 easy steps:
+
+1. Loading trace files
+2. Making basic measurements
+3. Spectral analysis
+4. Protocol decoding
+5. Auto-discovery
+
+No prior signal analysis experience required!
+""",
+        steps=steps,
+        difficulty="beginner",
+    )
+
+    TUTORIALS[tutorial.id] = tutorial
+
+
+def _create_loading_step() -> TutorialStep:
+    """Create loading trace file tutorial step."""
+    return TutorialStep(
+        title="Loading a Trace File",
+        description="""
 Oscura can load waveform data from many file formats.
 The simplest way is to use the load() function, which auto-detects the format.
 
 Think of a trace like a recording of an electrical signal over time -
 similar to how an audio file stores sound waves.
 """,
-            code="""
+        code="""
 import oscura as osc
 
 # Load a waveform file (replace with your file path)
@@ -90,15 +121,19 @@ trace = osc.load("signal.csv")
 print(f"Loaded {len(trace.data)} samples")
 print(f"Sample rate: {trace.metadata.sample_rate} Hz")
 """,
-            expected_output="Loaded 10000 samples\nSample rate: 1000000.0 Hz",
-            hints=[
-                "Try loading a CSV file with two columns: time and voltage",
-                "Supported formats: .csv, .wfm, .npz, .hdf5, and more",
-            ],
-        ),
-        TutorialStep(
-            title="Making Basic Measurements",
-            description="""
+        expected_output="Loaded 10000 samples\nSample rate: 1000000.0 Hz",
+        hints=[
+            "Try loading a CSV file with two columns: time and voltage",
+            "Supported formats: .csv, .wfm, .npz, .hdf5, and more",
+        ],
+    )
+
+
+def _create_measurements_step() -> TutorialStep:
+    """Create measurements tutorial step."""
+    return TutorialStep(
+        title="Making Basic Measurements",
+        description="""
 Once you have a trace, you can measure things like:
 - Rise time: How fast a signal goes from low to high
 - Frequency: How many times per second the signal repeats
@@ -106,7 +141,7 @@ Once you have a trace, you can measure things like:
 
 These are the same measurements an oscilloscope would show you!
 """,
-            code="""
+        code="""
 import oscura as osc
 
 trace = osc.load("signal.csv")
@@ -124,15 +159,19 @@ results = osc.measure(trace)
 for name, value in results.items():
     print(f"{name}: {value}")
 """,
-            expected_output="Rise time: 2.50 nanoseconds\nFrequency: 10.00 MHz",
-            hints=[
-                "rise_time() measures 10%-90% transition by default",
-                "Use measure() to get all measurements in one call",
-            ],
-        ),
-        TutorialStep(
-            title="Spectral Analysis (Frequency Domain)",
-            description="""
+        expected_output="Rise time: 2.50 nanoseconds\nFrequency: 10.00 MHz",
+        hints=[
+            "rise_time() measures 10%-90% transition by default",
+            "Use measure() to get all measurements in one call",
+        ],
+    )
+
+
+def _create_spectral_step() -> TutorialStep:
+    """Create spectral analysis tutorial step."""
+    return TutorialStep(
+        title="Spectral Analysis (Frequency Domain)",
+        description="""
 Spectral analysis shows you what frequencies are present in your signal.
 This is useful for:
 - Finding the main frequency of a clock signal
@@ -141,7 +180,7 @@ This is useful for:
 
 It's like looking at a music equalizer that shows bass, mid, and treble!
 """,
-            code="""
+        code="""
 import oscura as osc
 
 trace = osc.load("signal.csv")
@@ -160,21 +199,25 @@ snr_value = osc.snr(trace)
 print(f"THD: {thd_value:.1f} dB")
 print(f"SNR: {snr_value:.1f} dB")
 """,
-            expected_output="Dominant frequency: 10.00 MHz\nTHD: -45.2 dB\nSNR: 52.3 dB",
-            hints=[
-                "THD (Total Harmonic Distortion) should be negative in dB - more negative is better",
-                "SNR (Signal-to-Noise Ratio) should be positive - higher is better",
-            ],
-        ),
-        TutorialStep(
-            title="Protocol Decoding",
-            description="""
+        expected_output="Dominant frequency: 10.00 MHz\nTHD: -45.2 dB\nSNR: 52.3 dB",
+        hints=[
+            "THD (Total Harmonic Distortion) should be negative in dB - more negative is better",
+            "SNR (Signal-to-Noise Ratio) should be positive - higher is better",
+        ],
+    )
+
+
+def _create_protocol_step() -> TutorialStep:
+    """Create protocol decoding tutorial step."""
+    return TutorialStep(
+        title="Protocol Decoding",
+        description="""
 If your signal is a digital communication protocol like UART, SPI, or I2C,
 Oscura can decode it to show you the actual data being transmitted.
 
 Think of it like translating Morse code back into text!
 """,
-            code="""
+        code="""
 import oscura as osc
 
 # Load a UART signal
@@ -188,15 +231,19 @@ packets = decode_uart(trace)
 for pkt in packets[:5]:  # First 5 packets
     print(f"Time: {pkt.timestamp:.6f}s, Data: 0x{pkt.data:02X} ('{chr(pkt.data)}')")
 """,
-            expected_output="Time: 0.000001s, Data: 0x48 ('H')\nTime: 0.000086s, Data: 0x65 ('e')",
-            hints=[
-                "UART baud rate is auto-detected by default",
-                "Supported protocols: UART, SPI, I2C, CAN, and many more",
-            ],
-        ),
-        TutorialStep(
-            title="Auto-Discovery for Beginners",
-            description="""
+        expected_output="Time: 0.000001s, Data: 0x48 ('H')\nTime: 0.000086s, Data: 0x65 ('e')",
+        hints=[
+            "UART baud rate is auto-detected by default",
+            "Supported protocols: UART, SPI, I2C, CAN, and many more",
+        ],
+    )
+
+
+def _create_discovery_step() -> TutorialStep:
+    """Create auto-discovery tutorial step."""
+    return TutorialStep(
+        title="Auto-Discovery for Beginners",
+        description="""
 Not sure what your signal is? Oscura can analyze it automatically!
 
 The characterize_signal() function examines your trace and tells you:
@@ -206,7 +253,7 @@ The characterize_signal() function examines your trace and tells you:
 
 It's like having an expert look at your signal and give you hints!
 """,
-            code="""
+        code="""
 import oscura as osc
 from oscura.discovery import characterize_signal
 
@@ -226,35 +273,13 @@ else:
     for alt in result.alternatives:
         print(f"  - {alt.signal_type}: {alt.confidence:.1%}")
 """,
-            expected_output="Signal type: digital\nConfidence: 94.0%",
-            hints=[
-                "Confidence >= 80% means high confidence in the detection",
-                "Low confidence? Check the alternatives for other possibilities",
-            ],
-        ),
-    ]
-
-    tutorial = Tutorial(
-        id="getting_started",
-        title="Getting Started with Oscura",
-        description="""
-Welcome to Oscura! This tutorial will teach you the basics of
-signal analysis in 5 easy steps:
-
-1. Loading trace files
-2. Making basic measurements
-3. Spectral analysis
-4. Protocol decoding
-5. Auto-discovery
-
-No prior signal analysis experience required!
-""",
-        steps=steps,
-        difficulty="beginner",
+        expected_output="Signal type: digital\nConfidence: 94.0%",
+        hints=[
+            "Confidence >= 80% means high confidence in the detection",
+            "Low confidence? Check the alternatives for other possibilities",
+        ],
     )
 
-    TUTORIALS[tutorial.id] = tutorial
-
 
 def _register_spectral_analysis() -> None:
     """Register the spectral analysis tutorial."""