assertion-cli 0.1.0__py3-none-any.whl

main.py

@@ -0,0 +1,499 @@
+import base64
+import importlib.resources
+import json
+import re
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+from api import AssertionClient
+from bundle import build_bundle
+from git import (
+    exit_with_error,
+    find_git_root,
+    get_head_branch,
+    get_head_sha,
+    get_uncommitted_diff,
+)
+from link import load_link, save_link
+from models import CheckpointResponse, SessionContext, SessionStatus, render_stack_list
+from session import (
+    ASSERTION_DIR_NAME,
+    METADATA_FILE_NAME,
+    PROMPTS_FILE_NAME,
+    append_checkpoint_entry,
+    continue_session,
+    load_existing_session,
+    start_new_session,
+    update_metadata_head,
+)
+
+app = typer.Typer(help="Assertion CLI")
+
+STATUS_POLL_INTERVAL_SECONDS = 2.0
+
+
+def render_checkpoint_response(resp: CheckpointResponse) -> str:
+    lines = [
+        f"checkpoint_id: {resp.checkpoint_id}",
+        f"outcome: {resp.outcome}",
+    ]
+    for review in resp.reviews:
+        lines.append("")
+        lines.append(f"model: {review.model}")
+        lines.append(f"approved: {str(review.approved).lower()}")
+        lines.append(review.feedback)
+
+    lines.append("")
+    lines.append(resp.reasoning)
+    return "\n".join(lines)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Assertion command group."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
+@app.command("stacks")
+def stacks() -> None:
+    """List available verification stacks."""
+    client = AssertionClient()
+    stack_list = client.stacks()
+    typer.echo(render_stack_list(stack_list))
+
+
+ASSERTION_MARKER_BEGIN = "<!-- assertion-cli:begin -->"
+ASSERTION_MARKER_END = "<!-- assertion-cli:end -->"
+
+
+def _load_template(name: str) -> str:
+    return (
+        importlib.resources.files("assertion_cli_templates")
+        .joinpath(name)
+        .read_text(encoding="utf-8")
+    )
+
+
+def _write_full_file(path: Path, content: str, repo_root: Path) -> None:
+    """Idempotently overwrite a file. Creates parent dirs as needed.
+
+    Silent on no-op; echoes only when a write actually happens.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and path.read_text(encoding="utf-8") == content:
+        return
+    path.write_text(content, encoding="utf-8")
+    typer.echo(f"Wrote {path.relative_to(repo_root)}")
+
+
+def _apply_marked_block(path: Path, body: str, repo_root: Path) -> None:
+    """Idempotently insert/update an assertion-marked block in a markdown file.
+
+    Existing content outside the markers is preserved exactly.
+    Silent on no-op; echoes only when a write actually happens.
+    """
+    marked_block = f"{ASSERTION_MARKER_BEGIN}\n{body}\n{ASSERTION_MARKER_END}\n"
+    pattern = re.compile(
+        re.escape(ASSERTION_MARKER_BEGIN)
+        + r".*?"
+        + re.escape(ASSERTION_MARKER_END)
+        + r"\n?",
+        re.DOTALL,
+    )
+
+    if path.exists():
+        current = path.read_text(encoding="utf-8")
+        if pattern.search(current):
+            new_content = pattern.sub(marked_block, current)
+        else:
+            sep = (
+                ""
+                if current.endswith("\n\n")
+                else ("\n" if current.endswith("\n") else "\n\n")
+            )
+            new_content = current + sep + marked_block
+        if new_content != current:
+            path.write_text(new_content, encoding="utf-8")
+            typer.echo(f"Updated {path.relative_to(repo_root)}")
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(marked_block, encoding="utf-8")
+        typer.echo(f"Wrote {path.relative_to(repo_root)}")
+
+
+def _refresh_skill_files(repo_root: Path) -> None:
+    """Write/refresh the assertion-owned skill files for each coding agent.
+
+    Safe to call on every checkpoint — these files are entirely ours; updating
+    them to match the installed CLI version cannot clobber customer content.
+
+    `.claude/skills/`  — Claude Code
+    `.agents/skills/`  — Codex + Cursor (Cursor also accepts .cursor/skills/)
+    """
+    skill_body = _load_template("SKILL.md")
+    _write_full_file(
+        repo_root / ".claude" / "skills" / "assertion-cli" / "SKILL.md",
+        skill_body,
+        repo_root,
+    )
+    _write_full_file(
+        repo_root / ".agents" / "skills" / "assertion-cli" / "SKILL.md",
+        skill_body,
+        repo_root,
+    )
+
+
+_GITIGNORE_ASSERTION_ENTRY = ".assertion/"
+
+
+def _ensure_gitignore_excludes_assertion(repo_root: Path) -> None:
+    """Append `.assertion/` to the repo's .gitignore if not already excluded.
+
+    `.assertion/` holds per-session state (prompts, checkpoint message,
+    metadata, screenshots) — purely local working data. Without this entry it
+    surfaces as untracked changes that `asrt checkpoint`'s diff collector
+    would otherwise bundle and send to the reviewers.
+    """
+    gitignore = repo_root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    if any(
+        line.strip() in {".assertion", ".assertion/"} for line in existing.splitlines()
+    ):
+        return
+    prefix = "" if not existing or existing.endswith("\n") else "\n"
+    gitignore.write_text(
+        existing + prefix + _GITIGNORE_ASSERTION_ENTRY + "\n", encoding="utf-8"
+    )
+    typer.echo(
+        f"Updated {gitignore.relative_to(repo_root)} (added {_GITIGNORE_ASSERTION_ENTRY})"
+    )
+
+
+def _apply_activation_blocks(repo_root: Path) -> None:
+    """Insert/update the marked activation block in customer-owned CLAUDE.md / AGENTS.md.
+
+    Only called by `asrt init`. We deliberately do NOT call this on every checkpoint —
+    these files may be tracked in the customer's git, and silently dirtying them on
+    every checkpoint is hostile. The block is a stable pointer to the skill file, so
+    re-running on every CLI upgrade isn't necessary.
+    """
+    activation_body = _load_template("ACTIVATION.md").strip()
+    _apply_marked_block(repo_root / "CLAUDE.md", activation_body, repo_root)
+    _apply_marked_block(repo_root / "AGENTS.md", activation_body, repo_root)
+
+
+def _clear_session_state(ctx: SessionContext) -> None:
+    """Remove per-session files so the next prompt/checkpoint starts cleanly.
+
+    Leaves the `.assertion/` directory itself (and `link`, `screenshots/`) in
+    place so the customer can still retrieve the just-completed session's URL.
+    """
+    for path in (ctx.prompts_path, ctx.checkpoint_path, ctx.metadata_path):
+        path.unlink(missing_ok=True)
+
+
+@app.command("init")
+def init() -> None:
+    """One-time bootstrap: install the assertion-cli skill files into this repo.
+
+    Writes `.claude/skills/assertion-cli/SKILL.md`, `.agents/skills/assertion-cli/SKILL.md`,
+    and the marked activation block in `CLAUDE.md` and `AGENTS.md`. Run this once after
+    `uv tool install assertion-cli` so the coding agent (Claude Code, Codex, Cursor) loads
+    the skill and knows to call `asrt`. `asrt checkpoint` refreshes the skill files on each
+    run so they stay aligned with the installed CLI; `CLAUDE.md` / `AGENTS.md` are only
+    touched here, never by checkpoint, so they're safe to track in git.
+    """
+    repo_root = find_git_root(Path.cwd())
+    _refresh_skill_files(repo_root)
+    _apply_activation_blocks(repo_root)
+    _ensure_gitignore_excludes_assertion(repo_root)
+    typer.echo("")
+    typer.echo("The coding agent will now follow the Assertion workflow:")
+    typer.echo('  - asrt prompt "<msg>" on every customer turn')
+    typer.echo("  - asrt checkpoint at trajectory-feedback moments")
+    typer.echo("  - asrt verify at completion, then PR")
+
+
+@app.command("prompt")
+def prompt_cmd(
+    text: str = typer.Argument(..., help="Customer prompt text to record."),
+) -> None:
+    """Append a customer prompt to the session prompt history."""
+    normalized = text.strip()
+    if not normalized:
+        exit_with_error("Prompt text must not be empty.")
+
+    repo_root = find_git_root(Path.cwd())
+    assertion_dir = repo_root / ASSERTION_DIR_NAME
+    assertion_dir.mkdir(exist_ok=True)
+    prompts_path = assertion_dir / PROMPTS_FILE_NAME
+
+    entry = {
+        "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "text": normalized,
+    }
+    with prompts_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+@app.command("checkpoint")
+def checkpoint(
+    message: str = typer.Argument(..., help="Checkpoint progress message."),
+    stack: str | None = typer.Option(
+        None,
+        "--stack",
+        help="Force a new session against this stack ID. Overwrites any existing session.",
+    ),
+    continue_session_flag: bool = typer.Option(
+        False,
+        "--continue",
+        help="Require an existing session to continue (fail if none exists).",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Print the checkpoint response as a single JSON line."
+    ),
+) -> None:
+    """Record a checkpoint.
+
+    With no flag, the CLI auto-continues the existing session if one is present,
+    otherwise starts a new session against the stack attached to this repo's
+    GitHub origin. Use `--continue` to fail fast when no session exists, or
+    `--stack <id>` to force a brand-new session (destructive — replaces any
+    in-flight session).
+    """
+    if stack and continue_session_flag:
+        typer.echo("ERROR: --stack and --continue are mutually exclusive.", err=True)
+        raise typer.Exit(code=1)
+
+    repo_root = find_git_root(Path.cwd())
+
+    # Refresh the assertion-owned skill files so the agent always loads the
+    # version that ships with the installed CLI. We deliberately do NOT touch
+    # CLAUDE.md / AGENTS.md here — those are customer-owned and only updated
+    # by `asrt init`.
+    _refresh_skill_files(repo_root)
+
+    existing_metadata_path = repo_root / ASSERTION_DIR_NAME / METADATA_FILE_NAME
+
+    if continue_session_flag or (stack is None and existing_metadata_path.exists()):
+        # Either the caller asked to continue explicitly, OR they passed no
+        # flag and a session already exists (2nd+ checkpoint of the same
+        # session). In both cases continue rather than starting fresh — the
+        # alternative would silently destroy an in-flight session. To force a
+        # new session, pass --stack <id> or clear .assertion/ first (the
+        # post-verify prompt offers to do this).
+        ctx, metadata = continue_session(start_path=Path.cwd())
+    else:
+        from session import resolve_stack_id_for_repo
+
+        resolved_stack = stack or resolve_stack_id_for_repo(repo_root)
+        ctx, metadata = start_new_session(
+            start_path=Path.cwd(), stack_id=resolved_stack
+        )
+
+    stack_id = metadata.stack_id
+    assert stack_id is not None
+
+    append_checkpoint_entry(ctx.checkpoint_path, message)
+    head_sha = get_head_sha(ctx.repo_root)
+    head_branch = get_head_branch(ctx.repo_root)
+    diff_text = get_uncommitted_diff(ctx.repo_root)
+    metadata = update_metadata_head(
+        ctx.metadata_path, metadata, head_sha, head_branch=head_branch
+    )
+
+    bundle_bytes = build_bundle(
+        metadata=metadata,
+        diff_text=diff_text,
+        prompts_text=ctx.prompts_path.read_text(encoding="utf-8"),
+        checkpoint_text=message,
+    )
+
+    client = AssertionClient()
+    resp = client.checkpoint(
+        stack_id=stack_id,
+        session_id=metadata.session_id,
+        bundle_bytes=bundle_bytes,
+    )
+    if json_output:
+        typer.echo(resp.model_dump_json())
+    else:
+        typer.echo(render_checkpoint_response(resp))
+    if str(resp.outcome).endswith("failed"):
+        raise typer.Exit(code=1)
+
+
+@app.command("verify")
+def verify(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the terminal verification status as a single JSON line.",
+    ),
+    no_wait: bool = typer.Option(
+        False,
+        "--no-wait",
+        help="Submit and return immediately without polling. Useful for harnesses.",
+    ),
+) -> None:
+    """Submit final verification and wait for the result."""
+    ctx, metadata = load_existing_session(Path.cwd())
+    stack_id = metadata.stack_id
+    assert stack_id is not None
+    head_sha = get_head_sha(ctx.repo_root)
+    head_branch = get_head_branch(ctx.repo_root)
+    diff_text = get_uncommitted_diff(ctx.repo_root)
+    metadata = update_metadata_head(
+        ctx.metadata_path, metadata, head_sha, head_branch=head_branch
+    )
+
+    bundle_bytes = build_bundle(
+        metadata=metadata,
+        diff_text=diff_text,
+        prompts_text=ctx.prompts_path.read_text(encoding="utf-8"),
+        checkpoint_text=ctx.checkpoint_path.read_text(encoding="utf-8"),
+    )
+
+    client = AssertionClient()
+    resp = client.verify(
+        stack_id=stack_id,
+        session_id=metadata.session_id,
+        bundle_bytes=bundle_bytes,
+    )
+
+    session_id = resp.session_id
+    session_url = resp.url
+    save_link(ctx.assertion_dir, session_url)
+
+    if no_wait:
+        if json_output:
+            typer.echo(
+                json.dumps(
+                    {
+                        "session_id": session_id,
+                        "url": session_url,
+                        "status": "submitted",
+                    }
+                )
+            )
+        else:
+            typer.echo(f"Verification submitted ({session_id}). URL: {session_url}")
+        return
+
+    if not json_output:
+        typer.echo(f"Verification submitted ({session_id}). Waiting for result...")
+
+    poll_count = 0
+    while True:
+        payload = client.status(session_id=session_id)
+
+        if payload.status in {SessionStatus.CREATED, SessionStatus.RUNNING}:
+            poll_count += 1
+            if not json_output:
+                sys.stderr.write(".")
+                sys.stderr.flush()
+            time.sleep(STATUS_POLL_INTERVAL_SECONDS)
+            continue
+
+        if poll_count > 0 and not json_output:
+            sys.stderr.write("\n")
+            sys.stderr.flush()
+
+        if payload.url:
+            session_url = payload.url
+        save_link(ctx.assertion_dir, session_url)
+
+        if payload.screenshots:
+            screenshot_dir = Path(".assertion") / "screenshots" / session_id
+            screenshot_dir.mkdir(parents=True, exist_ok=True)
+            for idx, uri in enumerate(payload.screenshots):
+                _, b64data = uri.split(",", 1)
+                ext = "jpeg" if "jpeg" in uri.split(",")[0] else "png"
+                path = screenshot_dir / f"screenshot_{idx:03d}.{ext}"
+                path.write_bytes(base64.b64decode(b64data))
+
+        if json_output:
+            typer.echo(
+                json.dumps(
+                    {
+                        "session_id": session_id,
+                        "url": session_url,
+                        "status": str(payload.status),
+                        "message": payload.message,
+                        "summary": payload.summary,
+                        "screenshot_count": len(payload.screenshots),
+                    }
+                )
+            )
+            if payload.status == SessionStatus.FAILED:
+                raise typer.Exit(code=1)
+            return
+
+        if payload.message is None:
+            typer.echo(
+                "Invalid API response: terminal status must include a message.",
+                err=True,
+            )
+            raise typer.Exit(code=1)
+
+        typer.echo(payload.message)
+        if payload.summary:
+            typer.echo(f"\nSummary:\n{payload.summary}")
+        if payload.screenshots:
+            typer.echo(
+                f"\nScreenshots ({len(payload.screenshots)}) saved to "
+                f".assertion/screenshots/{session_id}/"
+            )
+        typer.echo(f"\nSession: {session_url}")
+        if payload.status == SessionStatus.FAILED:
+            raise typer.Exit(code=1)
+
+        # On a clean verify in an interactive shell, offer to clear session
+        # state so the next `asrt prompt` / `asrt checkpoint` starts fresh.
+        if sys.stdin.isatty() and typer.confirm(
+            "\nStart a new session? This clears .assertion/ (prompts, metadata, checkpoint).",
+            default=False,
+        ):
+            _clear_session_state(ctx)
+            typer.echo("Cleared. Next `asrt prompt` starts a new session.")
+        return
+
+
+@app.command("get-link")
+def get_link() -> None:
+    """Print the session link for the current verification session."""
+    ctx, metadata = load_existing_session(Path.cwd())
+    url = load_link(ctx.assertion_dir)
+    typer.echo(url)
+
+
+@app.command("decision")
+def decision(
+    checkpoint_id: str = typer.Argument(..., help="Checkpoint ID."),
+    yes: bool = typer.Option(
+        False, "--yes", help="Agree with the checkpoint feedback."
+    ),
+    no: bool = typer.Option(
+        False, "--no", help="Disagree with the checkpoint feedback."
+    ),
+) -> None:
+    """Record an agree/disagree sentiment for a failed checkpoint."""
+    if yes == no:
+        typer.echo("ERROR: Pass exactly one of --yes or --no.", err=True)
+        raise typer.Exit(code=1)
+
+    client = AssertionClient()
+    client.decision(
+        checkpoint_id=checkpoint_id,
+        decision="yes" if yes else "no",
+    )
+
+
+if __name__ == "__main__":
+    app()

models.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Sequence
+
+from pydantic import BaseModel, ConfigDict
+
+
+class VerificationStack(BaseModel):
+    id: str
+    name: str
+    description: str
+    repo: str
+
+
+class InitResponse(BaseModel):
+    session_id: str
+    stacks: list[VerificationStack]
+
+
+class VerifyResponse(BaseModel):
+    session_id: str
+    url: str
+
+
+class ReviewDetail(BaseModel):
+    model: str
+    approved: bool
+    feedback: str
+
+
+class CheckpointResponse(BaseModel):
+    checkpoint_id: str
+    outcome: str
+    reasoning: str
+    reviews: list[ReviewDetail]
+    created_at: str
+    updated_at: str
+
+
+class DecisionResponse(BaseModel):
+    ok: bool = True
+
+
+class SessionStatus(StrEnum):
+    CREATED = "created"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class StatusResponse(BaseModel):
+    status: SessionStatus
+    message: str | None = None
+    summary: str | None = None
+    screenshots: list[str] = []
+    url: str | None = None
+
+
+class ErrorResponse(BaseModel):
+    error: str
+
+
+class MetadataPayload(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    session_id: str
+    stack_id: str | None = None
+    head_sha: str | None = None
+    head_branch: str | None = None
+
+
+def render_stack_list(stacks: Sequence["VerificationStack"]) -> str:
+    lines: list[str] = []
+    for s in stacks:
+        lines.append(f"- {s.id}: {s.name} [repo: {s.repo}] — {s.description}")
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class SessionContext:
+    repo_root: Path
+    assertion_dir: Path
+    prompts_path: Path
+    checkpoint_path: Path
+    metadata_path: Path