assay-kit 0.1.0__py3-none-any.whl

assay/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("assay-kit")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"

assay/cli/main.py

@@ -0,0 +1,406 @@
+"""Assay CLI entrypoint."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional, cast
+
+import typer
+
+from assay import __version__
+from assay.config import AssayConfig, ConfigError, load_config
+from assay.formatter.formatter import format_packet
+from assay.formatter.writer import write_packet
+from assay.keys.store import KeyStoreError, create_key, list_keys, revoke_key
+from assay.runner import artifacts as _artifacts
+from assay.runner import runner as _runner
+from assay.schedule.cron import InvalidCronError, validate_cron
+from assay.schedule.store import ScheduleStoreError, add_schedule, list_schedules, remove_schedule
+
+app = typer.Typer(
+    help="Assay — independent verification layer for software projects.",
+    invoke_without_command=True,
+)
+schedule_app = typer.Typer(help="Manage scheduled test runs.")
+key_app = typer.Typer(help="Manage API keys for the ingest endpoint.")
+
+app.add_typer(schedule_app, name="schedule")
+app.add_typer(key_app, name="key")
+
+_NOT_IMPLEMENTED = "not implemented"
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(  # noqa: UP007
+        None,
+        "--version",
+        help="Print version and exit.",
+    ),
+    config: Optional[str] = typer.Option(  # noqa: UP007
+        None,
+        "--config",
+        help="Override config file path.",
+        envvar="ASSAY_CONFIG",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", help="Enable verbose output."),
+) -> None:
+    try:
+        ctx.obj = load_config(config)
+    except ConfigError as exc:
+        typer.echo(f"config error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    if version:
+        typer.echo(f"assay {__version__}")
+        raise typer.Exit(0)
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def run(
+    ctx: typer.Context,
+    target: Optional[str] = typer.Option(None, "--target", help="URL or target to test."),  # noqa: UP007
+    suite: str = typer.Option("default", "--suite", help="Test suite name."),
+    output: Optional[str] = typer.Option(None, "--output", help="Output directory."),  # noqa: UP007
+    task_id: Optional[str] = typer.Option(None, "--task-id", help="Grain task ID to tag this run."),  # noqa: UP007
+    submit: bool = typer.Option(False, "--submit", help="Submit packet to Grain output path after run."),
+) -> None:
+    """Execute a test run using the Playwright + Docker runner."""
+    from assay.grain.detect import detect_task_id
+
+    if target is None:
+        typer.echo("error: --target is required", err=True)
+        raise typer.Exit(2)
+
+    config: AssayConfig = ctx.obj
+    output_dir = output or config.output.directory
+    image = config.runner.docker_image
+
+    # Resolve task_id: explicit flag > Grain auto-detect
+    effective_task_id = task_id or detect_task_id(config.grain.project_root or None)
+    if effective_task_id:
+        typer.echo(f"task_id: {effective_task_id}")
+
+    runner_result = _runner.run(target, suite=suite, output_dir=output_dir, image=image)
+
+    try:
+        bundle = _artifacts.collect_artifacts(runner_result.output_dir, runner_result)
+    except _artifacts.ArtifactError as exc:
+        typer.echo(f"error reading artifacts: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+    typer.echo(f"outcome: {bundle.outcome}")
+    if bundle.error:
+        typer.echo(f"error: {bundle.error}", err=True)
+
+    try:
+        packet = format_packet(bundle, task_id=effective_task_id)
+        # Copy screenshot to a stable verification_id-based name in the output dir
+        verification_id = str(packet["verification_id"])
+        if bundle.screenshot_path:
+            src = Path(bundle.screenshot_path)
+            if src.exists():
+                dest = Path(output_dir) / f"{verification_id}.png"
+                shutil.copy2(src, dest)
+                packet["artifact_refs"] = [str(dest)]
+        packet_path = write_packet(packet, output_dir)
+        typer.echo(f"packet: {packet_path}")
+    except Exception as exc:
+        typer.echo(f"error writing packet: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+    if submit:
+        _do_submit(str(packet_path), config)
+
+    if bundle.outcome == "pass":
+        raise typer.Exit(0)
+    elif bundle.outcome == "fail":
+        raise typer.Exit(3)
+    else:
+        raise typer.Exit(1)
+
+
+def _do_submit(packet_path: str, config: AssayConfig) -> None:
+    """Copy a packet to the configured Grain output path."""
+    import json as _json
+
+    grain_output = config.grain.output_path
+    if not grain_output:
+        typer.echo("error: [grain] output_path not configured", err=True)
+        raise typer.Exit(1)
+
+    try:
+        data = _json.loads(Path(packet_path).read_text())
+    except Exception as exc:
+        typer.echo(f"error reading packet: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+    import jsonschema  # type: ignore[import-untyped]
+
+    from assay.schemas import ASSAY_PAYLOAD
+    try:
+        jsonschema.validate(instance=data, schema=ASSAY_PAYLOAD)
+    except jsonschema.ValidationError as exc:
+        typer.echo(f"error: packet schema invalid: {exc.message}", err=True)
+        raise typer.Exit(1) from exc
+
+    dest_dir = Path(grain_output)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / Path(packet_path).name
+    shutil.copy2(packet_path, dest)
+    typer.echo(f"submitted: {dest}")
+
+
+# ---------------------------------------------------------------------------
+# submit
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def submit(
+    ctx: typer.Context,
+    packet: str = typer.Option(..., "--packet", help="Path to the packet JSON file to submit."),
+) -> None:
+    """Validate and submit a packet to the configured Grain output path."""
+    config: AssayConfig = ctx.obj
+    _do_submit(packet, config)
+
+
+# ---------------------------------------------------------------------------
+# serve
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def serve(
+    ctx: typer.Context,
+    host: str = typer.Option("127.0.0.1", "--host", help="Host to bind."),
+    port: int = typer.Option(8000, "--port", help="Port to bind."),
+) -> None:
+    """Start the FastAPI ingest server."""
+    import uvicorn
+
+    from assay.ingest.app import app as ingest_app
+
+    config: AssayConfig = ctx.obj
+    ingest_app.state.key_store = config.keys.store
+    ingest_app.state.output_dir = config.output.directory
+
+    uvicorn.run(ingest_app, host=host, port=port)
+
+
+# ---------------------------------------------------------------------------
+# report
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def report(
+    output: str = typer.Option("./assay-output", "--output", help="Directory to read packets from."),
+    format: str = typer.Option("text", "--format", help="Output format: text or json."),
+    filter: Optional[str] = typer.Option(None, "--filter", help="Filter packets, e.g. outcome=fail."),  # noqa: UP007
+) -> None:
+    """Display task packet summaries from the output directory."""
+    import json as _json
+    from pathlib import Path as _Path
+
+    out = _Path(output)
+    if not out.is_dir():
+        typer.echo(f"error: output directory not found: {output}", err=True)
+        raise typer.Exit(1)
+
+    packets = []
+    for path in sorted(out.glob("assay-*.json")):
+        try:
+            data: dict[str, object] = _json.loads(path.read_text())
+        except Exception:
+            continue
+        packets.append(data)
+
+    # Apply --filter key=value
+    if filter:
+        if "=" not in filter:
+            typer.echo("error: --filter must be in key=value form", err=True)
+            raise typer.Exit(2)
+        fkey, fval = filter.split("=", 1)
+        packets = [p for p in packets if str(p.get(fkey, "")) == fval]
+
+    if format == "json":
+        typer.echo(_json.dumps(packets, indent=2))
+        raise typer.Exit(0)
+
+    if not packets:
+        typer.echo("no packets found")
+        raise typer.Exit(0)
+
+    # Text table
+    col = "{:<36}  {:<13}  {:<8}  {:<10}  {:<10}  {}"
+    typer.echo(col.format("verification_id", "outcome", "severity", "screenshot", "verified_at", "summary"))
+    typer.echo("-" * 120)
+    for p in packets:
+        vid = str(p.get("verification_id", ""))[:36]
+        outcome = str(p.get("outcome", ""))
+        severity = str(p.get("severity", ""))
+        refs = cast(list[object], p.get("artifact_refs", []))
+        has_screenshot = "yes" if any(str(r).endswith(".png") for r in refs) else "no"
+        verified_at = str(p.get("verified_at", ""))[:10]
+        summary = str(p.get("summary", ""))
+        typer.echo(col.format(vid, outcome, severity, has_screenshot, verified_at, summary))
+
+
+# ---------------------------------------------------------------------------
+# schedule subcommands
+# ---------------------------------------------------------------------------
+
+
+@schedule_app.command("add")
+def schedule_add(
+    ctx: typer.Context,
+    cron: str = typer.Option(..., "--cron", help="Cron expression (5-field)."),
+    suite: str = typer.Option("default", "--suite", help="Test suite name."),
+    target: Optional[str] = typer.Option(None, "--target", help="URL override (uses config default if omitted)."),  # noqa: UP007
+) -> None:
+    """Register a new scheduled run."""
+    try:
+        validate_cron(cron)
+    except InvalidCronError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+    config: AssayConfig = ctx.obj
+    try:
+        sid = add_schedule(config.schedule.store, cron, suite=suite, target=target)
+    except ScheduleStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"schedule added: {sid}")
+
+
+@schedule_app.command("list")
+def schedule_list(ctx: typer.Context) -> None:
+    """List all active schedules."""
+    config: AssayConfig = ctx.obj
+    try:
+        schedules = list_schedules(config.schedule.store)
+    except ScheduleStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    if not schedules:
+        typer.echo("no schedules")
+        return
+    for s in schedules:
+        target = s["target"] or "(config default)"
+        last = s["last_run"] or "never"
+        typer.echo(f"{s['id']}  {s['cron']}  suite={s['suite']}  target={target}  last_run={last}")
+
+
+@schedule_app.command("run")
+def schedule_run(ctx: typer.Context) -> None:
+    """Start the scheduler loop (foreground; Ctrl+C to stop)."""
+    from assay.schedule.loop import run_scheduler
+
+    config: AssayConfig = ctx.obj
+    run_scheduler(config)
+
+
+@schedule_app.command("remove")
+def schedule_remove(
+    ctx: typer.Context,
+    schedule_id: str = typer.Argument(..., help="Schedule ID to remove."),
+) -> None:
+    """Remove a schedule by ID."""
+    config: AssayConfig = ctx.obj
+    try:
+        remove_schedule(config.schedule.store, schedule_id)
+    except ScheduleStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"removed: {schedule_id}")
+
+
+@schedule_app.command("start")
+def schedule_start(ctx: typer.Context) -> None:
+    """Start the scheduler as a background daemon."""
+    from assay.schedule.daemon import start
+
+    start(config_path=None)
+
+
+@schedule_app.command("stop")
+def schedule_stop() -> None:
+    """Stop the running background scheduler daemon."""
+    from assay.schedule.daemon import stop
+
+    stop()
+
+
+@schedule_app.command("status")
+def schedule_status() -> None:
+    """Show whether the background scheduler daemon is running."""
+    from assay.schedule.daemon import status
+
+    info = status()
+    if info["running"]:
+        typer.echo(f"running (pid {info['pid']})")
+    else:
+        typer.echo("stopped")
+    typer.echo(f"log: {info['log_file']}")
+
+
+# ---------------------------------------------------------------------------
+# key subcommands
+# ---------------------------------------------------------------------------
+
+
+@key_app.command("create")
+def key_create(
+    ctx: typer.Context,
+    name: Optional[str] = typer.Option(None, "--name", help="Label for the key."),  # noqa: UP007
+) -> None:
+    """Generate a new API key."""
+    config: AssayConfig = ctx.obj
+    try:
+        raw = create_key(config.keys.store, label=name)
+    except KeyStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"key: {raw}")
+    typer.echo("Save this key — it will not be shown again.")
+
+
+@key_app.command("list")
+def key_list(ctx: typer.Context) -> None:
+    """List all API keys (IDs and labels only)."""
+    config: AssayConfig = ctx.obj
+    try:
+        keys = list_keys(config.keys.store)
+    except KeyStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    if not keys:
+        typer.echo("no keys")
+        return
+    for k in keys:
+        status = "revoked" if k["revoked"] else "active"
+        typer.echo(f"{k['id']}  {k['label']}  {status}  {k['created_at']}")
+
+
+@key_app.command("revoke")
+def key_revoke(
+    ctx: typer.Context,
+    key_id: str = typer.Argument(..., help="Key ID to revoke."),
+) -> None:
+    """Revoke an API key by ID."""
+    config: AssayConfig = ctx.obj
+    try:
+        revoke_key(config.keys.store, key_id)
+    except KeyStoreError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"revoked: {key_id}")

assay/config.py

@@ -0,0 +1,149 @@
+"""Assay configuration loader.
+
+Reads assay.toml from (in priority order):
+  1. explicit path passed to load_config()
+  2. ./assay.toml  (project-local)
+  3. ~/.assay/config.toml  (global user)
+  4. built-in defaults (all fields optional)
+
+Exit code 2 is expected when ConfigError propagates to the CLI layer.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_KNOWN_SECTIONS = {"project", "runner", "output", "serve", "keys", "schedule", "grain"}
+
+
+class ConfigError(Exception):
+    """Raised on config parse or validation failure."""
+
+
+@dataclass
+class ProjectConfig:
+    name: str = "assay"
+
+
+@dataclass
+class RunnerConfig:
+    docker_image: str = "assay-playwright:latest"
+    timeout_seconds: int = 300
+
+
+@dataclass
+class OutputConfig:
+    directory: str = "./assay-output"
+
+
+@dataclass
+class ServeConfig:
+    host: str = "127.0.0.1"
+    port: int = 8000
+
+
+@dataclass
+class KeysConfig:
+    store: str = "~/.assay/keys.json"
+
+
+@dataclass
+class ScheduleConfig:
+    store: str = "~/.assay/schedules.json"
+
+
+@dataclass
+class GrainConfig:
+    project_root: str = ""
+    output_path: str = ""
+
+
+@dataclass
+class AssayConfig:
+    project: ProjectConfig = field(default_factory=ProjectConfig)
+    runner: RunnerConfig = field(default_factory=RunnerConfig)
+    output: OutputConfig = field(default_factory=OutputConfig)
+    serve: ServeConfig = field(default_factory=ServeConfig)
+    keys: KeysConfig = field(default_factory=KeysConfig)
+    schedule: ScheduleConfig = field(default_factory=ScheduleConfig)
+    grain: GrainConfig = field(default_factory=GrainConfig)
+
+
+def _resolve_path(override: str | None) -> Path | None:
+    if override is not None:
+        p = Path(override)
+        if not p.exists():
+            raise ConfigError(f"config file not found: {override}")
+        return p
+    local = Path("assay.toml")
+    if local.exists():
+        return local
+    global_ = Path.home() / ".assay" / "config.toml"
+    if global_.exists():
+        return global_
+    return None
+
+
+def _parse(raw: dict[str, object]) -> AssayConfig:
+    unknown = set(raw.keys()) - _KNOWN_SECTIONS
+    if unknown:
+        raise ConfigError(f"unknown config section(s): {', '.join(sorted(unknown))}")
+
+    def _section(key: str) -> dict[str, object]:
+        val = raw.get(key, {})
+        if not isinstance(val, dict):
+            raise ConfigError(f"config section [{key}] must be a table")
+        return val
+
+    proj = _section("project")
+    runner = _section("runner")
+    output = _section("output")
+    serve = _section("serve")
+    keys = _section("keys")
+    schedule = _section("schedule")
+    grain = _section("grain")
+
+    raw_timeout = runner.get("timeout_seconds", 300)
+    raw_port = serve.get("port", 8000)
+    if not isinstance(raw_timeout, int):
+        raise ConfigError(f"runner.timeout_seconds must be an integer, got {raw_timeout!r}")
+    if not isinstance(raw_port, int):
+        raise ConfigError(f"serve.port must be an integer, got {raw_port!r}")
+
+    return AssayConfig(
+        project=ProjectConfig(name=str(proj.get("name", "assay"))),
+        runner=RunnerConfig(
+            docker_image=str(runner.get("docker_image", "assay-playwright:latest")),
+            timeout_seconds=raw_timeout,
+        ),
+        output=OutputConfig(directory=str(output.get("directory", "./assay-output"))),
+        serve=ServeConfig(
+            host=str(serve.get("host", "127.0.0.1")),
+            port=raw_port,
+        ),
+        keys=KeysConfig(store=str(keys.get("store", "~/.assay/keys.json"))),
+        schedule=ScheduleConfig(store=str(schedule.get("store", "~/.assay/schedules.json"))),
+        grain=GrainConfig(
+            project_root=str(grain.get("project_root", "")),
+            output_path=str(grain.get("output_path", "")),
+        ),
+    )
+
+
+def load_config(path: str | None = None) -> AssayConfig:
+    """Load and return AssayConfig from the resolved config file path.
+
+    Returns all-defaults AssayConfig if no config file is found.
+    Raises ConfigError on file-not-found (when explicit path given), parse error,
+    or unknown section.
+    """
+    resolved = _resolve_path(path)
+    if resolved is None:
+        return AssayConfig()
+    try:
+        raw = tomllib.loads(resolved.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"invalid TOML in {resolved}: {exc}") from exc
+    return _parse(raw)

assay/formatter/__init__.py

@@ -0,0 +1 @@
+"""Assay formatter package — converts runner artifacts to Grain Sentinel payloads."""

assay/formatter/formatter.py

@@ -0,0 +1,93 @@
+"""Formatter — converts ArtifactBundle or SDK IngestPayload to a Grain Sentinel payload dict."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from assay.runner.artifacts import ArtifactBundle
+
+if TYPE_CHECKING:
+    from assay.ingest.app import IngestPayload
+
+_ISSUE_TYPE_MAP = {
+    "pass": "test_failure",
+    "fail": "test_failure",
+    "inconclusive": "test_failure",
+}
+
+_SEVERITY_MAP = {
+    "pass": "info",
+    "fail": "error",
+    "inconclusive": "warning",
+}
+
+
+def _summary(bundle: ArtifactBundle) -> str:
+    """Build a human-readable one-line summary."""
+    if bundle.outcome == "pass":
+        return f"pass: {bundle.url}"
+    if bundle.error:
+        return f"{bundle.outcome}: {bundle.error}"
+    return f"{bundle.outcome}: {bundle.url or 'unknown url'}"
+
+
+def _verified_at(bundle: ArtifactBundle) -> str:
+    """Return bundle timestamp or current UTC time in ISO 8601."""
+    if bundle.timestamp:
+        return bundle.timestamp
+    return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def format_packet(
+    bundle: ArtifactBundle,
+    task_id: Optional[str] = None,  # noqa: UP007
+) -> dict[str, object]:
+    """Convert an ArtifactBundle into a Grain Sentinel payload dict.
+
+    Args:
+        bundle: Populated ArtifactBundle from collect_artifacts().
+        task_id: Grain TASK-#### ID being verified; None for standalone runs.
+
+    Returns:
+        Dict conforming to data_contracts.md §1 Grain Sentinel payload schema.
+    """
+    artifact_refs: list[str] = [bundle.screenshot_path] if bundle.screenshot_path else []
+
+    return {
+        "verification_id": str(uuid.uuid4()),
+        "task_id": task_id,
+        "issue_type": _ISSUE_TYPE_MAP.get(bundle.outcome, "test_failure"),
+        "severity": _SEVERITY_MAP.get(bundle.outcome, "warning"),
+        "outcome": bundle.outcome,
+        "summary": _summary(bundle),
+        "artifact_refs": artifact_refs,
+        "followup_candidates": [],
+        "verified_at": _verified_at(bundle),
+    }
+
+
+def format_sdk_packet(payload: "IngestPayload") -> dict[str, object]:
+    """Convert a browser SDK IngestPayload into a Grain Sentinel payload dict.
+
+    Args:
+        payload: Validated IngestPayload from the POST /ingest handler.
+
+    Returns:
+        Dict conforming to data_contracts.md §1 schema.
+    """
+    comment = payload.user_comment or ""
+    summary = f"SDK capture: {payload.url}" + (f" — {comment}" if comment else "")
+
+    return {
+        "verification_id": str(uuid.uuid4()),
+        "task_id": None,
+        "issue_type": "screenshot_evidence",
+        "severity": "info",
+        "outcome": "inconclusive",
+        "summary": summary,
+        "artifact_refs": [],
+        "followup_candidates": [],
+        "verified_at": payload.captured_at,
+    }

assay/formatter/writer.py

@@ -0,0 +1,34 @@
+"""Packet file writer — serialises a Grain Sentinel payload dict to disk."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def write_packet(packet: dict[str, object], output_dir: str) -> Path:
+    """Write a Grain Sentinel payload dict to a JSON file in output_dir.
+
+    The filename is derived from the packet's verified_at and verification_id
+    fields so it is both human-sortable and globally unique.
+
+    Args:
+        packet: Grain Sentinel payload dict from format_packet().
+        output_dir: Directory to write into. Created if it does not exist.
+
+    Returns:
+        Path of the written file.
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    verified_at = str(packet.get("verified_at", ""))
+    verification_id = str(packet.get("verification_id", ""))
+
+    # Make verified_at filename-safe: drop colons and dots
+    ts_safe = verified_at.replace(":", "").replace(".", "").replace("-", "")
+
+    filename = f"assay-{ts_safe}-{verification_id}.json"
+    path = out / filename
+    path.write_text(json.dumps(packet))
+    return path