runspec-logops 0.1.0__tar.gz

runspec_logops-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_logops-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# runspec-logops Changelog
+
+## [0.1.0] — 2026-06-18
+
+Initial release.
+
+Three runnables that let an agent triage application issues from a log file
+cheaply — the runnables do the heavy lifting on the host where the log lives and
+return small structured JSON, so the agent reads condensed conclusions, not raw
+data:
+
+- **`summarize-log`** (autonomous) — streams a log file and clusters repeated
+  errors by signature, returning the top-N distinct issues with counts,
+  first/last timestamp and one bounded sample each. Output size is bounded
+  regardless of input size. Supports a severity floor (`--level`) and a time
+  window (`--since`/`--until`).
+- **`map-trace`** (autonomous) — resolves a stack trace, or a `summarize-log`
+  signature, to the few relevant source snippets in a checkout (`--repo`).
+- **`bundle-digest`** (confirm) — summarises a log, optionally maps a trace to
+  code, and packs digest + snippets + manifest into one small zip for transfer.
+
+Thin wrappers over `runspec-logops-core`. To wrap the logic privately (bake in
+corporate paths/defaults, surface only your own runnables), depend on
+`runspec-logops-core` directly rather than installing this package.

runspec_logops-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-logops
+Version: 0.1.0
+Summary: Log-condensing + code-mapping runnables for runspec — cheap application-support triage from a log file
+Requires-Python: >=3.10
+Requires-Dist: runspec-logops-core>=0.1.0
+Requires-Dist: runspec>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

runspec_logops-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-logops"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Log-condensing + code-mapping runnables for runspec — cheap application-support triage from a log file"
+dependencies = [
+    "runspec>=0.27.0",
+    "runspec-logops-core>=0.1.0",
+]
+
+[project.scripts]
+summarize-log = "runspec_logops.digest:main_summarize_log"
+map-trace     = "runspec_logops.codemap:main_map_trace"
+bundle-digest = "runspec_logops.bundle:main_bundle_digest"
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_logops-0.1.0/runspec_logops/__init__.py

@@ -0,0 +1,21 @@
+"""runspec-logops — log-condensing + code-mapping runnables.
+
+The pure logic lives in the dependency-free ``runspec-logops-core`` package; the
+modules here wrap each helper in a runspec runnable. The helper functions are
+re-exported for convenience and back-compat (e.g. ``from runspec_logops import
+summarize_log``). To import the helpers *without* surfacing any runnables in a
+venv — the corporate-wrapping path — depend on ``runspec-logops-core`` directly
+instead.
+"""
+
+from runspec_logops_core import (
+    build_bundle,
+    map_trace_to_sources,
+    summarize_log,
+)
+
+__all__ = [
+    "summarize_log",
+    "map_trace_to_sources",
+    "build_bundle",
+]

runspec_logops-0.1.0/runspec_logops/bundle.py

@@ -0,0 +1,30 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_logops_core import build_bundle, map_trace_to_sources, summarize_log
+from runspec_logops_core.errors import SourceNotFoundError
+
+
+def main_bundle_digest() -> None:
+    spec = rs.parse("bundle-digest")
+    file_path = str(spec.file)
+    # Unset optionals resolve to an Arg wrapping value None; read .value so the
+    # absent case is a real None rather than the string "None".
+    repo = str(spec.repo) if spec.repo.value is not None else None
+    trace = str(spec.trace) if spec.trace.value is not None else None
+    destination = str(spec.destination)
+    top = int(spec.top)
+    try:
+        digest = summarize_log(file_path, top=top)
+        code_map = None
+        if trace and repo:
+            code_map = map_trace_to_sources(repo, trace)
+        result = build_bundle(digest, code_map, dest_dir=destination, metadata={"trace": trace})
+        print(json.dumps(result))
+    except SourceNotFoundError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
+    except OSError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)

runspec_logops-0.1.0/runspec_logops/codemap.py

@@ -0,0 +1,23 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_logops_core import map_trace_to_sources
+from runspec_logops_core.errors import SourceNotFoundError
+
+
+def main_map_trace() -> None:
+    spec = rs.parse("map-trace")
+    repo = str(spec.repo)
+    trace = str(spec.trace)
+    context = int(spec.context)
+    max_files = int(spec.max_files)
+    try:
+        result = map_trace_to_sources(repo, trace, context=context, max_files=max_files)
+        print(json.dumps(result))
+    except SourceNotFoundError as e:
+        print(json.dumps({"error": str(e), "repo": repo}))
+        sys.exit(1)
+    except OSError as e:
+        print(json.dumps({"error": str(e), "repo": repo}))
+        sys.exit(1)

runspec_logops-0.1.0/runspec_logops/digest.py

@@ -0,0 +1,34 @@
+import json
+import sys
+
+import runspec as rs
+from runspec_logops_core import summarize_log
+from runspec_logops_core.errors import SourceNotFoundError
+
+
+def main_summarize_log() -> None:
+    spec = rs.parse("summarize-log")
+    file_path = str(spec.file)
+    level = str(spec.level)
+    # Unset optionals resolve to an Arg wrapping value None; read .value so the
+    # absent case is a real None rather than the string "None".
+    since = spec.since.value
+    until = spec.until.value
+    top = int(spec.top)
+    max_sample_lines = int(spec.max_sample_lines)
+    try:
+        digest = summarize_log(
+            file_path,
+            level=level,
+            since=since,
+            until=until,
+            top=top,
+            max_sample_lines=max_sample_lines,
+        )
+        print(json.dumps(digest))
+    except SourceNotFoundError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)
+    except OSError as e:
+        print(json.dumps({"error": str(e), "file": file_path}))
+        sys.exit(1)

runspec_logops-0.1.0/runspec_logops/runspec.toml

@@ -0,0 +1,111 @@
+[config]
+autonomy-default = "autonomous"
+
+[config.logging]
+# Per-invocation log files: one {runnable}.{utc-ts}.{run_id}.log per run.
+# Multi-writer safe for shared venvs (use `runspec logs` to view/compact/prune).
+store = "per-run"
+
+# ── Log condensing ─────────────────────────────────────────────────────────────
+
+[summarize-log]
+serve       = ["local"]
+description = "Condense a log file into a small digest: cluster repeated errors by signature and return the top-N distinct issues with counts, first/last timestamp and one sample each. The digest size is bounded regardless of how big the log is, so read this instead of the raw log."
+autonomy    = "autonomous"
+output      = "json"
+
+[summarize-log.args.file]
+type        = "path"
+short       = "-f"
+description = "Path to the log file to summarise"
+
+[summarize-log.args.level]
+type        = "choice"
+options     = ["all", "warning", "error", "critical"]
+default     = "all"
+description = "Only include events at or above this severity"
+
+[summarize-log.args.since]
+type        = "str"
+required    = false
+description = "Window start: ISO timestamp, 'now', or '<n> <unit> ago' (e.g. '2 hours ago')"
+
+[summarize-log.args.until]
+type        = "str"
+required    = false
+description = "Window end: ISO timestamp, 'now', or '<n> <unit> ago'"
+
+[summarize-log.args.top]
+type        = "int"
+short       = "-n"
+default     = 10
+description = "Number of distinct signatures to return (most frequent first)"
+
+[summarize-log.args.max-sample-lines]
+type        = "int"
+default     = 20
+description = "Max lines of the sample kept per signature"
+
+# ── Trace → code ────────────────────────────────────────────────────────────────
+
+[map-trace]
+serve       = ["local"]
+description = "Map a stack trace (or a summarize-log signature like 'NullPointerException@com.acme.OrderSvc.price') to the few relevant source snippets in a checkout. Returns only the lines around each frame, never the whole repo."
+autonomy    = "autonomous"
+output      = "json"
+
+[map-trace.args.repo]
+type        = "path"
+short       = "-r"
+description = "Path to the source checkout to search"
+
+[map-trace.args.trace]
+type        = "str"
+short       = "-t"
+description = "The stack trace text, or a signature emitted by summarize-log"
+
+[map-trace.args.context]
+type        = "int"
+default     = 8
+description = "Lines of context to include around each resolved frame"
+
+[map-trace.args.max-files]
+type        = "int"
+default     = 5
+description = "Maximum number of frames/files to resolve"
+
+# ── Bundle for transfer ─────────────────────────────────────────────────────────
+
+[bundle-digest]
+serve       = ["local"]
+description = "Summarise a log and (optionally) map a trace to code, then pack the digest + snippets + manifest into one small zip ready for transfer to the local machine. Writes a file."
+autonomy    = "confirm"
+output      = "json"
+
+[bundle-digest.args.file]
+type        = "path"
+short       = "-f"
+description = "Path to the log file"
+
+[bundle-digest.args.repo]
+type        = "path"
+short       = "-r"
+required    = false
+description = "Path to the source checkout for the optional code map (omit for a digest-only bundle)"
+
+[bundle-digest.args.trace]
+type        = "str"
+required    = false
+description = "Optional trace/signature to map to code; omit for a digest-only bundle"
+
+[bundle-digest.args.destination]
+type        = "path"
+short       = "-d"
+default     = "/tmp"
+description = "Directory to write the zip into"
+
+[bundle-digest.args.top]
+type        = "int"
+short       = "-n"
+default     = 10
+description = "Number of distinct signatures to include in the digest"

runspec_logops-0.1.0/tests/test_runnables.py

@@ -0,0 +1,56 @@
+"""Smoke tests: each runnable parses args, calls its core helper, prints JSON.
+
+The runnables are exercised end-to-end via their installed console scripts (the
+same path `runspec serve` invokes), so this also proves the runspec.toml ships in
+the package and resolves.
+"""
+
+import json
+import shutil
+import subprocess
+
+import pytest
+
+
+def _run(script: str, *args: str) -> dict:
+    exe = shutil.which(script)
+    if not exe:
+        pytest.skip(f"{script} console script not installed")
+    proc = subprocess.run([exe, *args], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stderr
+    return json.loads(proc.stdout)
+
+
+def test_helpers_reexported() -> None:
+    from runspec_logops_core import summarize_log as core_summarize
+
+    from runspec_logops import build_bundle, map_trace_to_sources, summarize_log
+
+    assert summarize_log is core_summarize
+    assert callable(map_trace_to_sources) and callable(build_bundle)
+
+
+def test_summarize_log_runnable(tmp_path) -> None:
+    log = tmp_path / "app.log"
+    log.write_text("\n".join(["2026-06-18T08:00:00Z ERROR NullPointerException: boom\n\tat com.acme.Svc.go(Svc.java:9)"] * 5 + ["2026-06-18T08:01:00Z INFO ok"]) + "\n")
+    out = _run("summarize-log", "--file", str(log), "-n", "5")
+    assert out["file"] == str(log)
+    assert out["top"][0]["count"] == 5
+    assert out["top"][0]["signature"].startswith("NullPointerException@")
+
+
+def test_map_trace_runnable(tmp_path) -> None:
+    (tmp_path / "app.py").write_text("\n".join(f"line {i}" for i in range(1, 30)) + "\n")
+    trace = 'File "app.py", line 10, in handler'
+    out = _run("map-trace", "--repo", str(tmp_path), "--trace", trace, "--context", "2")
+    assert out["files_matched"] == 1
+    assert out["frames"][0]["file"] == "app.py"
+
+
+def test_bundle_digest_runnable(tmp_path) -> None:
+    log = tmp_path / "app.log"
+    log.write_text("2026-06-18T08:00:00Z ERROR ValueError: bad\n")
+    dest = tmp_path / "out"
+    out = _run("bundle-digest", "--file", str(log), "--destination", str(dest))
+    assert out["destination"].endswith(".zip")
+    assert "digest.json" in out["contents"]