argus-code 0.2.0__py3-none-any.whl

argus/adapters/claude_code/ingest_file.py

@@ -0,0 +1,137 @@
+"""Parse one Claude Code JSONL file from a byte offset, return new offset."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from ...schema.types import RawSessionHeader
+from ..base import AdapterIngestResult, ParseError
+from .extract_tool_calls import extract_tool_calls
+from .extract_transcript import extract_transcript_segments
+from .extract_turns import extract_turns
+from .schemas import AssistantLine, UserLine
+
+# Per-tick read cap to avoid OOM on a corrupt multi-GB JSONL.
+MAX_TICK_BYTES = 64 * 1024 * 1024  # 64 MiB
+
+
+def _empty_result(file_path: Path) -> AdapterIngestResult:
+    return AdapterIngestResult(
+        header=RawSessionHeader(
+            native_session_id=file_path.stem,
+            agent="claude_code",
+            agent_version=None,
+            project_path="",
+            started_at="",
+            ended_at=None,
+            agent_reported_cost_usd=None,
+            metadata={},
+        ),
+        turns=[],
+        tool_calls=[],
+        segments=[],
+        parse_errors=[],
+    )
+
+
+def ingest_claude_code_file(
+    file_path: Path, from_offset: int = 0
+) -> tuple[AdapterIngestResult, int]:
+    """Read new bytes after ``from_offset``, parse, return (result, new_offset).
+
+    Partial trailing lines are held back until the next call. Malformed
+    lines are recorded as ParseErrors and skipped — surrounding lines
+    still ingest successfully.
+    """
+    with open(file_path, "rb") as fh:
+        fh.seek(0, 2)  # end
+        size = fh.tell()
+        if size <= from_offset:
+            return _empty_result(file_path), from_offset
+        read_len = min(size - from_offset, MAX_TICK_BYTES)
+        fh.seek(from_offset)
+        raw = fh.read(read_len)
+
+    text = raw.decode("utf-8", errors="replace")
+    last_nl = text.rfind("\n")
+    consumable = text[: last_nl + 1] if last_nl != -1 else ""
+    consumed_bytes = len(consumable.encode("utf-8"))
+    new_offset = from_offset + consumed_bytes
+
+    assistant_lines: list[AssistantLine] = []
+    user_lines: list[UserLine] = []
+    parse_errors: list[ParseError] = []
+    line_offset = from_offset
+
+    for line in consumable.split("\n"):
+        if not line:
+            line_offset += 1
+            continue
+        line_bytes = len(line.encode("utf-8"))
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError as e:
+            parse_errors.append(
+                ParseError(
+                    file=str(file_path),
+                    byte_offset=line_offset,
+                    reason=str(e),
+                    raw_line_truncated=line[:200],
+                )
+            )
+            line_offset += line_bytes + 1
+            continue
+
+        otype = obj.get("type") if isinstance(obj, dict) else None
+        try:
+            if otype == "assistant":
+                assistant_lines.append(AssistantLine.model_validate(obj))
+            elif otype == "user":
+                # User-line schema failure is non-fatal (loose schema) — skip
+                # without recording, otherwise parse_errors would flood.
+                try:
+                    user_lines.append(UserLine.model_validate(obj))
+                except ValidationError:
+                    pass
+        except ValidationError as e:
+            parse_errors.append(
+                ParseError(
+                    file=str(file_path),
+                    byte_offset=line_offset,
+                    reason=str(e),
+                    raw_line_truncated=line[:200],
+                )
+            )
+        line_offset += line_bytes + 1
+
+    turns = extract_turns(assistant_lines)
+    tool_calls = extract_tool_calls(assistant_lines, user_lines)
+    segments = extract_transcript_segments(assistant_lines, user_lines)
+
+    session_id = file_path.stem
+    cwd = assistant_lines[0].cwd if assistant_lines else ""
+    version = assistant_lines[-1].version if assistant_lines else None
+    started_at = (
+        assistant_lines[0].timestamp if assistant_lines else "1970-01-01T00:00:00.000Z"
+    )
+    ended_at = assistant_lines[-1].timestamp if assistant_lines else None
+
+    result = AdapterIngestResult(
+        header=RawSessionHeader(
+            native_session_id=session_id,
+            agent="claude_code",
+            agent_version=version,
+            project_path=cwd,
+            started_at=started_at,
+            ended_at=ended_at,
+            agent_reported_cost_usd=None,
+            metadata={},
+        ),
+        turns=turns,
+        tool_calls=tool_calls,
+        segments=segments,
+        parse_errors=parse_errors,
+    )
+    return result, new_offset

argus/adapters/claude_code/model.py

@@ -0,0 +1,11 @@
+"""Claude Code model-name canonicalization."""
+from __future__ import annotations
+
+import re
+
+_DATED_SUFFIX_RE = re.compile(r"-(\d{8})$")
+
+
+def canonicalize_claude_model(raw: str) -> str:
+    """Strip a YYYYMMDD date suffix if present; leave aliases alone."""
+    return _DATED_SUFFIX_RE.sub("", raw)

argus/adapters/claude_code/schemas.py

@@ -0,0 +1,77 @@
+"""pydantic schemas for one line of a Claude Code JSONL session log.
+
+Equivalents of the zod schemas in src/adapters/claude_code/schemas.ts.
+``model_config = ConfigDict(extra='allow')`` mirrors zod's ``.passthrough()``
+so unknown fields like ``attribution_agent`` survive parsing.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Passthrough(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class CacheCreation(_Passthrough):
+    ephemeral_5m_input_tokens: int = 0
+    ephemeral_1h_input_tokens: int = 0
+
+
+class Usage(_Passthrough):
+    input_tokens: int = Field(ge=0)
+    output_tokens: int = Field(ge=0)
+    cache_read_input_tokens: int = Field(default=0, ge=0)
+    cache_creation_input_tokens: int = Field(default=0, ge=0)
+    cache_creation: CacheCreation | None = None
+    service_tier: str | None = None
+
+
+class AssistantMessage(_Passthrough):
+    id: str
+    model: str
+    role: Literal["assistant"]
+    content: list[dict[str, Any]] = Field(default_factory=list)
+    stop_reason: str | None = None
+    usage: Usage
+
+
+class UserMessage(_Passthrough):
+    role: Literal["user"]
+    # Either a plain string ("hello") or a list of content blocks
+    # ([{type: 'tool_result', ...}, ...]).
+    content: str | list[Any]
+
+
+class AssistantLine(_Passthrough):
+    type: Literal["assistant"]
+    sessionId: str
+    uuid: str
+    timestamp: str
+    cwd: str
+    version: str | None = None
+    userType: str | None = None
+    entrypoint: str | None = None
+    gitBranch: str | None = None
+    isSidechain: bool | None = None
+    agentId: str | None = None
+    requestId: str | None = None
+    attribution_agent: str | None = None
+    message: AssistantMessage
+
+
+class UserLine(_Passthrough):
+    type: Literal["user"]
+    sessionId: str
+    uuid: str
+    timestamp: str
+    cwd: str
+    version: str | None = None
+    userType: str | None = None
+    entrypoint: str | None = None
+    gitBranch: str | None = None
+    isSidechain: bool | None = None
+    agentId: str | None = None
+    message: UserMessage

argus/adapters/registry.py

@@ -0,0 +1,30 @@
+"""Adapter registry.
+
+Each Adapter class self-registers at import time via ``@register``.
+"""
+from __future__ import annotations
+
+from .base import Adapter
+
+_REGISTRY: dict[str, type[Adapter]] = {}
+
+
+def register(cls: type[Adapter]) -> type[Adapter]:
+    """Class decorator — adds ``cls`` to the registry by ``cls.agent``."""
+    _REGISTRY[cls.agent] = cls
+    return cls
+
+
+def available_adapters() -> list[Adapter]:
+    """Instantiate every registered adapter whose ``is_present()`` is True."""
+    out: list[Adapter] = []
+    for cls in _REGISTRY.values():
+        a = cls()
+        if a.is_present():
+            out.append(a)
+    return out
+
+
+def registered_adapter_names() -> list[str]:
+    """Names of every adapter the registry knows about (present or not)."""
+    return list(_REGISTRY.keys())

argus/cli.py

@@ -0,0 +1,384 @@
+"""``argus`` CLI — typer subcommand tree."""
+from __future__ import annotations
+
+import logging
+import shutil
+import sys
+import webbrowser
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+import argus.detectors  # noqa: F401  — triggers @register side-effects
+
+from .adapters.registry import available_adapters
+from .collector.first_run import run_first_pass_ingest
+from .collector.scheduler import start_scheduler
+from .collector.watcher import start_watcher
+from .detectors.registry import available_detectors
+from .pricing.load import load_pricing_table
+from .pricing.refresh import diff_pricing, fetch_litellm_table
+from .scaffold.scaffolder import scaffold_project
+from .scaffold.snapshot import snapshot_candidates, snapshot_template
+from .scaffold.storage import RESERVED_TEMPLATE_NAMES, list_templates, resolve_template
+from .server.app import ServerOpts, build_app, serve_blocking
+from .store.db import open_db
+from .store.repository import Repository
+
+logger = logging.getLogger("argus")
+app = typer.Typer(help="Local-first dashboard for coding-agent costs", no_args_is_help=True)
+pricing_app = typer.Typer(help="Pricing-table operations")
+search_app = typer.Typer(help="Manage transcript-search indexing")
+app.add_typer(pricing_app, name="pricing")
+app.add_typer(search_app, name="search")
+claude_app = typer.Typer(help="Scaffold and manage .claude/ project setups")
+template_app = typer.Typer(help="Manage scaffolding templates")
+claude_app.add_typer(template_app, name="template")
+app.add_typer(claude_app, name="claude")
+
+
+def _setup_logging(quiet: bool = False, verbose: bool = False) -> None:
+    level = logging.WARNING if quiet else (logging.DEBUG if verbose else logging.INFO)
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def _dashboard_dir() -> Path:
+    """Path of the bundled dashboard-dist (wheel) or repo-root one (dev)."""
+    try:
+        traversable = resources.files("argus") / "dashboard-dist"
+        candidate = Path(str(traversable))
+        if candidate.exists():
+            return candidate
+    except (ModuleNotFoundError, FileNotFoundError):
+        pass
+    return Path(__file__).resolve().parents[2] / "dashboard-dist"
+
+
+def _default_data_dir() -> Path:
+    return Path.home() / ".argus"
+
+
+@app.command()
+def start(
+    port: int = typer.Option(4242, "-p", "--port"),
+    host: str = typer.Option(
+        "127.0.0.1",
+        "--host",
+        help=(
+            "Bind host. Default 127.0.0.1 (loopback only). Pass 0.0.0.0 to "
+            "expose on LAN — see SECURITY.md."
+        ),
+    ),
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+    quiet: bool = typer.Option(False, "--quiet"),
+    verbose: bool = typer.Option(False, "--verbose"),
+) -> None:
+    """Start the watcher, ingester, and dashboard server."""
+    _setup_logging(quiet=quiet, verbose=verbose)
+
+    db = open_db(data_dir / "argus.db")
+    repo = Repository(db)
+
+    adapters = available_adapters()
+    if not adapters:
+        typer.echo(
+            "No adapter data found. Argus expects ~/.claude/ (Claude Code) "
+            "to be present at minimum.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    names = ", ".join(a.agent for a in adapters)
+    logger.info("Detected adapters: %s", names)
+
+    table = load_pricing_table()
+    logger.info("Argus: ingesting recent sessions...")
+    handle = run_first_pass_ingest(adapters, repo, table, recent_days=30)
+    handle.wait_foreground()
+    s = handle.status()
+    logger.info(
+        "Argus: foreground ingest complete (%d/%d files), starting watcher...",
+        s.processed,
+        s.total,
+    )
+
+    watcher = start_watcher(adapters, repo, table)
+
+    detectors = available_detectors()
+    logger.info("Loaded %d detectors: %s", len(detectors), [d.name for d in detectors])
+    scheduler = start_scheduler(detectors, repo)
+
+    dash_dir = _dashboard_dir()
+    server_app = build_app(
+        repo,
+        ServerOpts(
+            pricing_table_version=table.version,
+            ingest_status=handle.status,
+            dashboard_dir=dash_dir,
+            port=port,
+            host=host,
+            adapters=adapters,
+            pricing_table=table,
+        ),
+    )
+    display_host = "localhost" if host in ("0.0.0.0", "::") else host
+    url = f"http://{display_host}:{port}"
+    logger.info("Argus running at %s", url)
+    if host in ("0.0.0.0", "::"):
+        logger.warning(
+            "⚠ WARNING: bound to all network interfaces. Anyone on your LAN "
+            "can read your prompt history, transcripts, and project paths."
+        )
+    try:
+        webbrowser.open(url)
+    except Exception:  # noqa: BLE001
+        pass
+
+    try:
+        serve_blocking(server_app, host=host, port=port)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        scheduler.stop()
+        watcher.stop()
+        db.close()
+        logger.info("Argus stopped.")
+
+
+@pricing_app.command("refresh")
+def pricing_refresh() -> None:
+    """Fetch the latest LiteLLM pricing and (after confirm) overwrite the bundled table."""
+    _setup_logging()
+    current = load_pricing_table()
+    typer.echo("Fetching latest pricing from LiteLLM...")
+    fresh = fetch_litellm_table()
+    diff = diff_pricing(current, fresh)
+    typer.echo(
+        f"Added: {len(diff.added)}, Removed: {len(diff.removed)}, "
+        f"Changed: {len(diff.changed)}, Unchanged: {len(diff.unchanged)}"
+    )
+    for k in diff.changed:
+        typer.echo(f"  ~ {k}: {current.models[k].model_dump()} -> {fresh.models[k].model_dump()}")
+    for k in diff.added:
+        typer.echo(f"  + {k}: {fresh.models[k].model_dump()}")
+    for k in diff.removed:
+        typer.echo(f"  - {k}")
+    if not (diff.added or diff.changed or diff.removed):
+        typer.echo("Nothing to update.")
+        return
+    if not typer.confirm("Apply?"):
+        typer.echo("Cancelled.")
+        return
+    # Write into the repo's pricing/ dir if we're in dev; otherwise into the
+    # wheel's bundled dir (which is read-only for installed packages — print
+    # a hint).
+    try:
+        traversable = resources.files("argus") / "pricing"
+        out_dir = Path(str(traversable))
+        if not out_dir.is_dir():
+            raise FileNotFoundError(out_dir)
+    except (ModuleNotFoundError, FileNotFoundError):
+        out_dir = Path(__file__).resolve().parents[2] / "pricing"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_file = out_dir / f"{fresh.version}.json"
+    out_file.write_text(fresh.model_dump_json(indent=2), encoding="utf-8")
+    typer.echo(f"Wrote {out_file}")
+
+
+@search_app.command("status")
+def search_status(data_dir: Path = typer.Option(_default_data_dir(), "--data-dir")) -> None:
+    db = open_db(data_dir / "argus.db")
+    repo = Repository(db)
+    enabled = repo.is_search_indexing_enabled()
+    segs = repo.segment_stats()
+    typer.echo(f"Status:   {'ENABLED' if enabled else 'disabled'}")
+    typer.echo(f"Indexed:  {segs['total']:,} segments across {segs['sessions']} sessions")
+    if not enabled and segs["total"] > 0:
+        typer.echo("Note:     existing segments stay on disk but are hidden from search")
+        typer.echo("          until you re-enable. Use 'argus search clear' to wipe them.")
+
+
+@search_app.command("enable")
+def search_enable(data_dir: Path = typer.Option(_default_data_dir(), "--data-dir")) -> None:
+    db = open_db(data_dir / "argus.db")
+    repo = Repository(db)
+    if repo.is_search_indexing_enabled():
+        typer.echo("Already enabled.")
+        segs = repo.segment_stats()
+        typer.echo(f"Indexed: {segs['total']:,} segments across {segs['sessions']} sessions")
+        return
+    repo.set_search_indexing_enabled(True)
+    typer.echo("Enabled. Run `argus start` to backfill — historical sessions will")
+    typer.echo("index in the background. New sessions are indexed automatically.")
+
+
+@search_app.command("disable")
+def search_disable(data_dir: Path = typer.Option(_default_data_dir(), "--data-dir")) -> None:
+    db = open_db(data_dir / "argus.db")
+    repo = Repository(db)
+    repo.set_search_indexing_enabled(False)
+    segs = repo.segment_stats()
+    typer.echo("Disabled.")
+    if segs["total"] > 0:
+        typer.echo(f"{segs['total']:,} existing segments are still on disk but hidden")
+        typer.echo("from search. Run `argus search clear` to wipe them.")
+
+
+@search_app.command("clear")
+def search_clear(
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+    yes: bool = typer.Option(False, "-y", "--yes"),
+) -> None:
+    db = open_db(data_dir / "argus.db")
+    repo = Repository(db)
+    segs = repo.segment_stats()
+    if segs["total"] == 0:
+        typer.echo("Nothing to clear (0 indexed segments).")
+        repo.set_search_indexing_enabled(False)
+        return
+    if not yes and not typer.confirm(f"Delete {segs['total']:,} indexed segments?"):
+        typer.echo("Cancelled.")
+        return
+    before_bytes = repo.db_size_bytes()
+    repo.clear_all_segments()
+    repo.set_search_indexing_enabled(False)
+    repo.vacuum()
+    after_bytes = repo.db_size_bytes()
+    freed = max(0, before_bytes - after_bytes)
+
+    def fmt(n: int) -> str:
+        if n >= 1024 * 1024:
+            return f"{n / 1024 / 1024:.1f} MB"
+        if n >= 1024:
+            return f"{n / 1024:.1f} KB"
+        return f"{n} B"
+
+    typer.echo(f"Deleted {segs['total']:,} segments.")
+    typer.echo(f"Freed {fmt(freed)} on disk (DB now {fmt(after_bytes)}).")
+
+
+def _render_tree(paths: list[Path], root: Path) -> str:
+    rels = sorted(p.relative_to(root).as_posix() for p in paths)
+    seen: set[str] = set()
+    lines: list[str] = []
+    for r in rels:
+        parts = r.split("/")
+        for depth, part in enumerate(parts):
+            prefix = "/".join(parts[: depth + 1])
+            if prefix in seen:
+                continue
+            seen.add(prefix)
+            is_dir = depth < len(parts) - 1
+            lines.append("  " * depth + part + ("/" if is_dir else ""))
+    return "\n".join(lines)
+
+
+@claude_app.command("init")
+def claude_init(
+    path: Path = typer.Argument(Path("."), help="Target project directory"),
+    template: str = typer.Option("default", "--template", help="Template name"),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite existing files (never CLAUDE.md)"
+    ),
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+) -> None:
+    """Scaffold a .claude/ setup (and CLAUDE.md) into a project."""
+    try:
+        template_dir = resolve_template(template, data_dir)
+    except KeyError:
+        avail = ", ".join(list_templates(data_dir)) or "(none)"
+        typer.echo(f"Unknown template '{template}'. Available: {avail}", err=True)
+        raise typer.Exit(code=1)
+
+    dest = path.resolve()
+    dest.mkdir(parents=True, exist_ok=True)
+    result = scaffold_project(template_dir, dest, force=force)
+
+    for p in result.created:
+        typer.echo(f"  + {p.relative_to(dest).as_posix()}")
+    for p, reason in result.skipped:
+        typer.echo(f"  - {p.relative_to(dest).as_posix()}  ({reason})")
+
+    touched = result.created + [p for p, _ in result.skipped]
+    if touched:
+        typer.echo("\nResulting layout:")
+        typer.echo(_render_tree(touched, dest))
+    typer.echo(f"\nScaffolded '{template}' into {dest}")
+    typer.echo(f"{len(result.created)} created, {len(result.skipped)} skipped.")
+
+
+@template_app.command("list")
+def template_list(
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+) -> None:
+    """List available template names (user templates shadow bundled)."""
+    names = list_templates(data_dir)
+    if not names:
+        typer.echo("No templates found.")
+        return
+    for n in names:
+        typer.echo(n)
+
+
+@template_app.command("create")
+def template_create(
+    name: str = typer.Argument(..., help="Template name to create"),
+    path: Path = typer.Option(Path("."), "--path", help="Project dir to snapshot"),
+    all_subdirs: bool = typer.Option(
+        False, "--all", help="Include every subfolder without prompting"
+    ),
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+) -> None:
+    """Snapshot the current project's .claude/ into a reusable user template."""
+    if name in RESERVED_TEMPLATE_NAMES:
+        typer.echo(f"'{name}' is reserved, pick another name", err=True)
+        raise typer.Exit(code=1)
+
+    project = path.resolve()
+    if not (project / ".claude").is_dir():
+        typer.echo(f"No .claude/ directory found in {project}", err=True)
+        raise typer.Exit(code=1)
+
+    candidates = snapshot_candidates(project)
+    if all_subdirs:
+        included = candidates
+    else:
+        included = [
+            d for d in candidates if typer.confirm(f"Include {d}/?", default=True)
+        ]
+
+    try:
+        target = snapshot_template(
+            project, name, data_dir, include_subdirs=included
+        )
+    except ValueError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+    typer.echo(f"Created template '{name}' at {target}")
+
+
+@app.command()
+def wipe(
+    data_dir: Path = typer.Option(_default_data_dir(), "--data-dir"),
+    yes: bool = typer.Option(False, "-y", "--yes"),
+) -> None:
+    """Delete all local Argus data."""
+    if not yes and not typer.confirm(f"Delete {data_dir}?"):
+        typer.echo("Cancelled.")
+        return
+    if data_dir.exists():
+        shutil.rmtree(data_dir)
+    typer.echo(f"Deleted {data_dir}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()