epi-recorder 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

epi_cli/keys.py

@@ -234,7 +234,7 @@ def generate_default_keypair_if_missing(console_output: bool = True) -> bool:
     private_path, public_path = key_manager.generate_keypair("default")
     
     if console_output:
-        console.print("\n[bold green]🔐 Welcome to EPI![/bold green]")
+        console.print("\n[bold green]Welcome to EPI![/bold green]")
         console.print("\n[dim]Generated default Ed25519 key pair for signing:[/dim]")
         console.print(f"  [cyan]Private:[/cyan] {private_path}")
         console.print(f"  [cyan]Public:[/cyan]  {public_path}")
@@ -260,8 +260,8 @@ def print_keys_table(keys: list[dict[str, str]]) -> None:
     table.add_column("Public Key", style="blue")
     
     for key in keys:
-        private_status = "✅" if key["has_private"] else "❌"
-        public_status = "✅" if key["has_public"] else "❌"
+        private_status = "[Y]" if key["has_private"] else "[N]"
+        public_status = "[Y]" if key["has_public"] else "[N]"
         
         table.add_row(
             key["name"],

epi_cli/ls.py

@@ -0,0 +1,160 @@
+"""
+EPI CLI Ls - List recordings in ./epi-recordings/ directory.
+
+Usage:
+  epi ls
+"""
+
+import json
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from epi_core.container import EPIContainer
+
+console = Console()
+
+app = typer.Typer(name="ls", help="List local recordings (./epi-recordings/)")
+
+DEFAULT_DIR = Path("epi-recordings")
+
+
+def _format_metrics(metrics: Dict[str, Any]) -> str:
+    """Format metrics dictionary as a compact string."""
+    if not metrics:
+        return ""
+    
+    formatted = []
+    for key, value in metrics.items():
+        if isinstance(value, float):
+            # Format floats to 2 decimal places
+            formatted.append(f"{key}={value:.2f}")
+        else:
+            formatted.append(f"{key}={value}")
+    
+    return ", ".join(formatted)
+
+
+def _get_recording_info(epi_file: Path) -> dict:
+    """
+    Extract basic info from a recording.
+    
+    Returns:
+        Dictionary with recording metadata
+    """
+    try:
+        # Read manifest
+        manifest = EPIContainer.read_manifest(epi_file)
+        
+        # Get file stats
+        stats = epi_file.stat()
+        size_mb = stats.st_size / (1024 * 1024)
+        modified = datetime.fromtimestamp(stats.st_mtime)
+        
+        # Extract CLI command if available
+        cli_command = getattr(manifest, 'cli_command', None)
+        
+        # Extract originating script from cli_command
+        script = "Unknown"
+        if cli_command:
+            parts = cli_command.split()
+            for i, part in enumerate(parts):
+                if part.endswith('.py'):
+                    script = Path(part).name
+                    break
+        
+        # Check signature
+        signed = "Yes" if manifest.signature else "No"
+        
+        # Quick integrity check
+        integrity_ok, _ = EPIContainer.verify_integrity(epi_file)
+        status = "[OK]" if integrity_ok else "[FAIL]"
+        
+        # Extract new metadata fields
+        goal = getattr(manifest, 'goal', None)
+        metrics = getattr(manifest, 'metrics', None)
+        tags = getattr(manifest, 'tags', None)
+        
+        return {
+            "name": epi_file.name,
+            "script": script,
+            "size_mb": f"{size_mb:.2f}",
+            "modified": modified.strftime("%Y-%m-%d %H:%M:%S"),
+            "signed": signed,
+            "status": status,
+            "goal": goal or "",
+            "metrics_summary": _format_metrics(metrics) if metrics else "",
+            "tags_summary": ", ".join(tags) if tags else ""
+        }
+    except Exception as e:
+        return {
+            "name": epi_file.name,
+            "script": "Error",
+            "size_mb": "?",
+            "modified": "?",
+            "signed": "?",
+            "status": f"[ERR] {str(e)[:20]}",
+            "goal": "",
+            "metrics_summary": "",
+            "tags_summary": ""
+        }
+
+
+@app.callback(invoke_without_command=True)
+def ls(
+    all_dirs: bool = typer.Option(False, "--all", "-a", help="Search current directory too"),
+):
+    """
+    List local recordings in ./epi-recordings/ directory.
+    
+    Shows created/verified status and originating script if available.
+    """
+    # Find recordings
+    recordings = []
+    
+    # Check default directory
+    if DEFAULT_DIR.exists():
+        recordings.extend(DEFAULT_DIR.glob("*.epi"))
+    
+    # Optionally check current directory
+    if all_dirs:
+        recordings.extend(Path(".").glob("*.epi"))
+    
+    # Remove duplicates
+    recordings = list(set(recordings))
+    recordings.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    
+    if not recordings:
+        console.print("[yellow]No recordings found[/yellow]")
+        if not DEFAULT_DIR.exists():
+            console.print(f"[dim]Directory {DEFAULT_DIR} does not exist yet[/dim]")
+        console.print("[dim]Tip: Run 'epi run script.py' to create your first recording[/dim]")
+        return
+    
+    # Build table
+    table = Table(title=f"EPI Recordings ({len(recordings)} found)")
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Modified", style="dim")
+    table.add_column("Goal", style="blue", no_wrap=False)
+    table.add_column("Metrics", style="purple", no_wrap=False)
+    table.add_column("Tags", style="green", no_wrap=False)
+    
+    for recording in recordings:
+        info = _get_recording_info(recording)
+        table.add_row(
+            info["name"],
+            info["modified"],
+            info["goal"][:50] + "..." if len(info["goal"]) > 50 else info["goal"],
+            info["metrics_summary"],
+            info["tags_summary"]
+        )
+    
+    console.print()
+    console.print(table)
+    console.print()
+    console.print(f"[dim]Tip: View a recording with 'epi view <name>'[/dim]")

epi_cli/main.py

@@ -12,7 +12,31 @@ from epi_cli.keys import generate_default_keypair_if_missing
 # Create Typer app
 app = typer.Typer(
     name="epi",
-    help="EPI - Evidence Packaged Infrastructure for AI workflows",
+    help="""EPI - Evidence Packaged Infrastructure for AI workflows
+
+Commands:
+  run    <script.py>        Record, auto-verify and open viewer. (Zero-config)
+  record --out <file.epi> -- <cmd...>
+                           Advanced: record any command, exact output file.
+  verify <file.epi>         Verify a recording's integrity.
+  view   <file.epi|name>    Open recording in browser (name resolves ./epi-recordings/).
+  ls                        List local recordings (./epi-recordings/).
+  keys                      Manage keys (list/generate/export) - advanced.
+  help                      Show this quickstart.
+
+Quickstart (first 30s):
+  1) Install: pip install epi-recorder
+  2) Record (simplest): epi run my_script.py
+     -> Saved: ./epi-recordings/my_script_20251121_231501.epi
+     -> Verified: OK
+     -> Viewer: opened in browser
+  3) See recordings: epi ls
+  4) Open a recording: epi view my_script_20251121_231501
+
+Tips:
+  - Want explicit name? Use the advanced command: epi record --out experiment.epi -- python my_script.py
+  - For scripts using the API, use @record decorator or with record(): no filenames needed.
+""",
     add_completion=False,
     no_args_is_help=True,
     rich_markup_mode="rich"
@@ -40,20 +64,61 @@ def version():
     console.print("[dim]The PDF for AI workflows[/dim]")
 
 
+@app.command(name="help")
+def show_help():
+    """Show extended quickstart help."""
+    help_text = """[bold cyan]EPI Recorder - Quickstart Guide[/bold cyan]
+
+[bold]Usage:[/bold] epi <command> [options]
+
+[bold]Commands:[/bold]
+  [cyan]run[/cyan]    <script.py>        Record, auto-verify and open viewer. (Zero-config)
+  [cyan]record[/cyan] --out <file.epi> -- <cmd...>
+                           Advanced: record any command, exact output file.
+  [cyan]verify[/cyan] <file.epi>         Verify a recording's integrity.
+  [cyan]view[/cyan]   <file.epi|name>    Open recording in browser (name resolves ./epi-recordings/).
+  [cyan]ls[/cyan]                        List local recordings (./epi-recordings/).
+  [cyan]keys[/cyan]                      Manage keys (list/generate/export) - advanced.
+  [cyan]help[/cyan]                      Show this quickstart.
+
+[bold]Quickstart (first 30s):[/bold]
+  1) Install: pip install epi-recorder
+  2) Record (simplest): [green]epi run my_script.py[/green]
+     -> Saved: ./epi-recordings/my_script_20251121_231501.epi
+     -> Verified: OK
+     -> Viewer: opened in browser
+  3) See recordings: [green]epi ls[/green]
+  4) Open a recording: [green]epi view my_script_20251121_231501[/green]
+
+[bold]Tips:[/bold]
+  - Want explicit name? Use the advanced command: epi record --out experiment.epi -- python my_script.py
+  - For scripts using the API, use @record decorator or with record(): no filenames needed.
+"""
+    console.print(help_text)
+
+
 # Import and register subcommands
 # These will be added as they're implemented
 
+# NEW: run command (zero-config) - direct import
+from epi_cli.run import run as run_command
+app.command(name="run", help="Record, auto-verify and open viewer. (Zero-config)")(run_command)
+
 # Phase 1: verify command
 from epi_cli.verify import verify_app
 app.add_typer(verify_app, name="verify", help="Verify .epi file integrity and authenticity")
 
-# Phase 2: record command
+# Phase 2: record command (legacy/advanced)
 from epi_cli.record import app as record_app
-app.add_typer(record_app, name="record", help="Record a workflow into a .epi file")
+app.add_typer(record_app, name="record", help="Advanced: record any command, exact output file.")
 
 # Phase 3: view command
 from epi_cli.view import app as view_app
-app.add_typer(view_app, name="view", help="View .epi file in browser")
+app.add_typer(view_app, name="view", help="Open recording in browser (name resolves ./epi-recordings/)")
+
+# NEW: ls command
+from epi_cli.ls import ls as ls_command
+app.command(name="ls", help="List local recordings (./epi-recordings/)")(ls_command)
 
 # Phase 1: keys command (for manual key management)
 @app.command()
@@ -70,11 +135,11 @@ def keys(
     if action == "generate":
         try:
             private_path, public_path = key_manager.generate_keypair(name, overwrite=overwrite)
-            console.print(f"\n[bold green]✅ Generated key pair:[/bold green] {name}")
+            console.print(f"\n[bold green][OK] Generated key pair:[/bold green] {name}")
             console.print(f"  [cyan]Private:[/cyan] {private_path}")
             console.print(f"  [cyan]Public:[/cyan]  {public_path}\n")
         except FileExistsError as e:
-            console.print(f"[red]❌ Error:[/red] {e}")
+            console.print(f"[red][FAIL] Error:[/red] {e}")
             raise typer.Exit(1)
     
     elif action == "list":
@@ -87,11 +152,11 @@ def keys(
             console.print(f"\n[bold]Public key for '{name}':[/bold]")
             console.print(f"[cyan]{public_key_b64}[/cyan]\n")
         except FileNotFoundError as e:
-            console.print(f"[red]❌ Error:[/red] {e}")
+            console.print(f"[red][FAIL] Error:[/red] {e}")
             raise typer.Exit(1)
     
     else:
-        console.print(f"[red]❌ Unknown action:[/red] {action}")
+        console.print(f"[red][FAIL] Unknown action:[/red] {action}")
         console.print("[dim]Valid actions: generate, list, export[/dim]")
         raise typer.Exit(1)
 

epi_cli/record.py

@@ -94,10 +94,17 @@ def record(
 ):
     """
     Record a command and package the run into a .epi file.
+    
+    [NOTICE] For simpler usage, try: epi run script.py
+    This command (epi record --out) is for advanced/CI use cases.
     """
     if not command:
-        console.print("[red]❌ No command provided[/red]")
+        console.print("[red][FAIL] No command provided[/red]")
         raise typer.Exit(1)
+    
+    # Show deprecation notice
+    console.print("[dim][NOTICE] For simpler usage, try: epi run script.py[/dim]")
+    console.print("[dim]This advanced command is for CI/exact-control use cases.[/dim]\n")
 
     # Normalize command
     cmd = _ensure_python_command(command)
@@ -171,11 +178,11 @@ def record(
             temp_zip.replace(out)
             signed = True
         except Exception as e:
-            console.print(f"[yellow]⚠️  Signing failed:[/yellow] {e}")
+            console.print(f"[yellow][WARN]  Signing failed:[/yellow] {e}")
 
     # Final output panel
     size_mb = out.stat().st_size / (1024 * 1024)
-    title = "✅ Recording complete" if rc == 0 else "⚠️ Recording finished with errors"
+    title = "[OK] Recording complete" if rc == 0 else "[WARN] Recording finished with errors"
     panel = Panel(
         f"[bold]File:[/bold] {out}\n"
         f"[bold]Size:[/bold] {size_mb:.1f} MB\n"

epi_cli/run.py

@@ -0,0 +1,318 @@
+"""
+EPI CLI Run - Zero-config recording command.
+
+Usage:
+  epi run script.py
+
+This command:
+- Auto-generates output filename in ./epi-recordings/
+- Records the script execution
+- Verifies the recording
+- Opens the viewer automatically
+"""
+
+import os
+import shlex
+import sys
+import tempfile
+import time
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from epi_core.container import EPIContainer
+from epi_core.schemas import ManifestModel
+from epi_core.trust import verify_signature, get_signer_name, create_verification_report
+from epi_cli.keys import KeyManager
+from epi_recorder.environment import save_environment_snapshot
+
+console = Console()
+
+app = typer.Typer(name="run", help="Zero-config recording: epi run my_script.py")
+
+DEFAULT_DIR = Path("epi-recordings")
+
+
+def _gen_auto_name(script_path: Path) -> Path:
+    """
+    Generate automatic output filename in ./epi-recordings/ directory.
+    
+    Args:
+        script_path: Path to the script being recorded
+        
+    Returns:
+        Path to the .epi file
+    """
+    base = script_path.stem if script_path.name != "-" else "recording"
+    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+    DEFAULT_DIR.mkdir(parents=True, exist_ok=True)
+    return DEFAULT_DIR / f"{base}_{timestamp}.epi"
+
+
+def _ensure_python_command(cmd: List[str]) -> List[str]:
+    """
+    Ensure the command is run with Python if it looks like a Python script.
+    """
+    if not cmd:
+        return cmd
+    first = cmd[0]
+    if first.lower().endswith('.py'):
+        return [sys.executable] + cmd
+    return cmd
+
+
+def _build_env_for_child(steps_dir: Path, enable_redaction: bool) -> dict:
+    """
+    Build environment variables for child process to enable recording via sitecustomize.
+    """
+    env = os.environ.copy()
+
+    # Indicate recording mode and where to write steps
+    env["EPI_RECORD"] = "1"
+    env["EPI_STEPS_DIR"] = str(steps_dir)
+    env["EPI_REDACT"] = "1" if enable_redaction else "0"
+
+    # Create a temporary bootstrap dir with sitecustomize.py
+    bootstrap_dir = Path(tempfile.mkdtemp(prefix="epi_bootstrap_"))
+    sitecustomize = bootstrap_dir / "sitecustomize.py"
+    sitecustomize.write_text(
+        "from epi_recorder.bootstrap import initialize_recording\n",
+        encoding="utf-8",
+    )
+
+    # Prepend bootstrap dir and project root to PYTHONPATH
+    project_root = Path(__file__).resolve().parent.parent
+    existing = env.get("PYTHONPATH", "")
+    sep = os.pathsep
+    env["PYTHONPATH"] = f"{bootstrap_dir}{sep}{project_root}{(sep + existing) if existing else ''}"
+
+    return env
+
+
+def _verify_recording(epi_file: Path) -> tuple[bool, str]:
+    """
+    Verify the recording and return status.
+    
+    Returns:
+        (success, message) tuple
+    """
+    try:
+        manifest = EPIContainer.read_manifest(epi_file)
+        integrity_ok, mismatches = EPIContainer.verify_integrity(epi_file)
+        
+        if not integrity_ok:
+            return False, f"Integrity check failed ({len(mismatches)} mismatches)"
+        
+        # Check signature
+        if manifest.signature:
+            signer_name = get_signer_name(manifest.signature)
+            key_manager = KeyManager()
+            
+            try:
+                public_key = key_manager.load_public_key(signer_name or "default")
+                signature_valid, msg = verify_signature(manifest, public_key)
+                
+                if signature_valid:
+                    return True, "OK (signed & verified)"
+                else:
+                    return False, f"Signature invalid: {msg}"
+            except FileNotFoundError:
+                return True, "OK (unsigned - no public key)"
+        else:
+            return True, "OK (unsigned)"
+            
+    except Exception as e:
+        return False, f"Verification failed: {e}"
+
+
+def _open_viewer(epi_file: Path) -> bool:
+    """
+    Open the viewer for the recording.
+    
+    Returns:
+        True if opened successfully
+    """
+    try:
+        import webbrowser
+        
+        # Extract viewer to temp location
+        temp_dir = Path(tempfile.mkdtemp(prefix="epi_view_"))
+        viewer_path = temp_dir / "viewer.html"
+        
+        with zipfile.ZipFile(epi_file, "r") as zf:
+            if "viewer.html" in zf.namelist():
+                zf.extract("viewer.html", temp_dir)
+                file_url = viewer_path.as_uri()
+                return webbrowser.open(file_url)
+        
+        return False
+    except Exception:
+        return False
+
+
+@app.command()
+def run(
+    script: Path = typer.Argument(..., help="Python script to record"),
+    no_verify: bool = typer.Option(False, "--no-verify", help="Skip verification"),
+    no_open: bool = typer.Option(False, "--no-open", help="Don't open viewer automatically"),
+    # New metadata options
+    goal: Optional[str] = typer.Option(None, "--goal", help="Goal or objective of this workflow"),
+    notes: Optional[str] = typer.Option(None, "--notes", help="Additional notes about this workflow"),
+    metric: Optional[List[str]] = typer.Option(None, "--metric", help="Key=value metrics (can be used multiple times)"),
+    approved_by: Optional[str] = typer.Option(None, "--approved-by", help="Person who approved this workflow"),
+    tag: Optional[List[str]] = typer.Option(None, "--tag", help="Tags for categorizing this workflow (can be used multiple times)"),
+):
+    """
+    Zero-config recording: record + verify + view.
+    
+    Example:
+        epi run my_script.py
+        epi run script.py --goal "improve accuracy" --notes "test run" --metric accuracy=0.92 --metric latency=210 --approved-by "bob" --tag test --tag v1
+    """
+    # Validate script exists
+    if not script.exists():
+        console.print(f"[red][FAIL] Error:[/red] Script not found: {script}")
+        raise typer.Exit(1)
+    
+    # Parse metrics if provided
+    metrics_dict = None
+    if metric:
+        metrics_dict = {}
+        for m in metric:
+            if "=" in m:
+                key, value = m.split("=", 1)
+                # Try to convert to float if possible, otherwise keep as string
+                try:
+                    metrics_dict[key] = float(value)
+                except ValueError:
+                    metrics_dict[key] = value
+            else:
+                console.print(f"[yellow]Warning:[/yellow] Invalid metric format: {m} (expected key=value)")
+    
+    # Auto-generate output filename
+    out = _gen_auto_name(script)
+    
+    # Normalize command
+    cmd = _ensure_python_command([str(script)])
+    
+    # Prepare workspace
+    temp_workspace = Path(tempfile.mkdtemp(prefix="epi_record_"))
+    steps_dir = temp_workspace
+    env_json = temp_workspace / "env.json"
+    
+    # Capture environment snapshot
+    save_environment_snapshot(env_json, include_all_env_vars=False, redact_env_vars=True)
+    
+    # Build child environment and run
+    child_env = _build_env_for_child(steps_dir, enable_redaction=True)
+    
+    # Create stdout/stderr logs
+    stdout_log = temp_workspace / "stdout.log"
+    stderr_log = temp_workspace / "stderr.log"
+    
+    console.print(f"[dim]Recording:[/dim] {script.name}")
+    
+    import subprocess
+    
+    start = time.time()
+    with open(stdout_log, "wb") as out_f, open(stderr_log, "wb") as err_f:
+        proc = subprocess.Popen(cmd, env=child_env, stdout=out_f, stderr=err_f)
+        rc = proc.wait()
+    duration = round(time.time() - start, 3)
+    
+    # Build manifest with metadata
+    manifest = ManifestModel(
+        cli_command=" ".join(shlex.quote(c) for c in cmd),
+        goal=goal,
+        notes=notes,
+        metrics=metrics_dict,
+        approved_by=approved_by,
+        tags=tag
+    )
+    
+    # Package into .epi
+    EPIContainer.pack(temp_workspace, manifest, out)
+    
+    # Auto-sign
+    signed = False
+    try:
+        km = KeyManager()
+        priv = km.load_private_key("default")
+        
+        # Read manifest from ZIP
+        import json as _json
+        with zipfile.ZipFile(out, "r") as zf:
+            raw = zf.read("manifest.json").decode("utf-8")
+            data = _json.loads(raw)
+        
+        # Sign manifest
+        from epi_core.schemas import ManifestModel as _MM
+        from epi_core.trust import sign_manifest as _sign
+        m = _MM(**data)
+        sm = _sign(m, priv, "default")
+        signed_json = sm.model_dump_json(indent=2)
+        
+        # Replace manifest in ZIP
+        temp_zip = out.with_suffix(".epi.tmp")
+        with zipfile.ZipFile(out, "r") as zf_in:
+            with zipfile.ZipFile(temp_zip, "w", zipfile.ZIP_DEFLATED) as zf_out:
+                for item in zf_in.namelist():
+                    if item != "manifest.json":
+                        zf_out.writestr(item, zf_in.read(item))
+                zf_out.writestr("manifest.json", signed_json)
+        
+        temp_zip.replace(out)
+        signed = True
+    except Exception:
+        pass  # Non-fatal
+    
+    # Verify
+    verified = False
+    verify_msg = "Skipped"
+    if not no_verify:
+        verified, verify_msg = _verify_recording(out)
+    
+    # Open viewer
+    viewer_opened = False
+    if not no_open and rc == 0 and verified:
+        viewer_opened = _open_viewer(out)
+    
+    # Print results
+    size_mb = out.stat().st_size / (1024 * 1024)
+    
+    lines = []
+    lines.append(f"[bold]Saved:[/bold] {out}")
+    lines.append(f"[bold]Size:[/bold] {size_mb:.2f} MB")
+    lines.append(f"[bold]Duration:[/bold] {duration}s")
+    
+    if not no_verify:
+        if verified:
+            lines.append(f"[bold]Verified:[/bold] [green]{verify_msg}[/green]")
+        else:
+            lines.append(f"[bold]Verified:[/bold] [red]{verify_msg}[/red]")
+    
+    if viewer_opened:
+        lines.append(f"[bold]Viewer:[/bold] [green]Opened in browser[/green]")
+    elif not no_open:
+        lines.append(f"[bold]Viewer:[/bold] [yellow]Could not open automatically[/yellow]")
+        lines.append(f"[dim]Open with:[/dim] epi view {out.name}")
+    
+    title = "[OK] Recording complete" if rc == 0 else "[WARN] Recording finished with errors"
+    panel = Panel(
+        "\n".join(lines),
+        title=title,
+        border_style="green" if rc == 0 else "yellow",
+    )
+    console.print(panel)
+    
+    # Exit with appropriate code
+    if rc != 0:
+        raise typer.Exit(rc)
+    if not verified and not no_verify:
+        raise typer.Exit(1)
+    raise typer.Exit(0)