llar 0.1.1__py3-none-any.whl

llar/__init__.py

@@ -0,0 +1,2 @@
+# ABOUTME: Provides the llar package for managing coding agents' local state.
+# ABOUTME: Keeps package imports free of filesystem access and CLI side effects.

llar/__main__.py

@@ -0,0 +1,7 @@
+# ABOUTME: Runs llar through Python's module entry point.
+# ABOUTME: Delegates command handling to the installed CLI application.
+
+from llar.cli import app
+
+if __name__ == "__main__":
+    app()

llar/cli.py

@@ -0,0 +1,646 @@
+# ABOUTME: Exposes project summaries, conversations, activity and diagnostics.
+# ABOUTME: Applies explicit directory scopes to the appropriate evidence fields.
+
+import json
+import stat
+from importlib.metadata import version
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from llar.core.context import Context
+from llar.core.coverage import Report
+from llar.core.file_copy import CopyResult
+from llar.core.inventory import Project
+from llar.core.scope import Scope
+from llar.core.snapshot import Snapshot, collect
+from llar.core.transfer_plan import TransferPlan, build_plan
+from llar.core.transfers import Endpoint, TransferError
+from llar.harnesses import HARNESSES
+from llar.harnesses.base import Harness
+from llar.harnesses.transfers import execute_application
+
+app = typer.Typer(
+    help="Look after the local state coding agents keep about your projects.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+projects_app = typer.Typer(
+    no_args_is_help=True, help="Inspect known project directories."
+)
+sessions_app = typer.Typer(no_args_is_help=True, help="Inspect logical conversations.")
+activity_app = typer.Typer(no_args_is_help=True, help="Inspect runtime observations.")
+trust_app = typer.Typer(no_args_is_help=True, help="Inspect explicit trust settings.")
+app.add_typer(projects_app, name="projects")
+app.add_typer(sessions_app, name="sessions")
+app.add_typer(activity_app, name="activity")
+projects_app.add_typer(trust_app, name="trust")
+
+Home = Annotated[Path | None, typer.Option(help="Inspect an isolated alternate home.")]
+Json = Annotated[bool, typer.Option("--json", help="Emit machine-readable output.")]
+Selection = Annotated[
+    list[str] | None, typer.Option("--harness", help="Select a harness; repeatable.")
+]
+Directory = Annotated[
+    Path | None, typer.Option("--dir", help="Exact associated directory.")
+]
+Recursive = Annotated[bool, typer.Option(help="Include descendants of --dir.")]
+Unassigned = Annotated[bool, typer.Option(help="Only objects with unknown ownership.")]
+ProjectPath = Annotated[Path, typer.Argument(help="Exact project directory.")]
+
+
+def selected(names: list[str] | None) -> list[Harness]:
+    if names is not None and set(names) - {harness.name for harness in HARNESSES}:
+        raise typer.BadParameter("Unknown harness. Choose claude or codex.")
+    return [harness for harness in HARNESSES if names is None or harness.name in names]
+
+
+def inspect(home: Path | None, names: list[str] | None) -> Snapshot:
+    return collect(Context.create(home), selected(names))
+
+
+def scope(
+    directory: Path | None, recursive: bool = False, unassigned: bool = False
+) -> Scope:
+    try:
+        return Scope(
+            directory.expanduser().resolve() if directory is not None else None,
+            recursive,
+            unassigned,
+        )
+    except ValueError as error:
+        raise typer.BadParameter(str(error)) from None
+
+
+def emit(
+    rows: list[dict[str, object]],
+    json_: bool,
+    report: Report,
+    *,
+    empty: str = "No matching records in inspected sources.",
+) -> None:
+    if json_:
+        typer.echo(
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "items": rows,
+                    "diagnostics": report.diagnostics,
+                    "coverage": report.as_dict(),
+                }
+            )
+        )
+    else:
+        if not rows:
+            typer.echo(
+                empty
+                if report.complete
+                else "Inspection incomplete; no matching records in readable sources."
+            )
+        for row in rows:
+            if "explicit_trust" in row:
+                typer.echo(f"{row['harness']} {json.dumps(row['path'])}")
+                trust = row["explicit_trust"]
+                if trust is None:
+                    trust = (
+                        "unset" if row.get("explicit_trust_inspected") else "unknown"
+                    )
+                typer.echo(f"  explicit_trust={trust}")
+                if "session_count" in row:
+                    typer.echo(
+                        f"  exists={row['exists']}, known={row['known']}, "
+                        f"sessions={row['session_count']}, "
+                        f"transcripts={row['transcript_count']}, "
+                        f"activity_records={row['activity_record_count']}, "
+                        f"live_sessions={row['live_session_count']}"
+                    )
+                    typer.echo("  memory_inventory=not_inspected")
+                    paths = row.get("state_paths", [])
+                    if isinstance(paths, list):
+                        for path in paths:
+                            typer.echo(f"  state: {json.dumps(path)}")
+                typer.echo(f"  config: {json.dumps(row['config_file'])}")
+            elif "ref" in row:
+                typer.echo(
+                    f"{json.dumps(row['ref'])} "
+                    f"started_in={json.dumps(row['started_in'])}"
+                )
+                typer.echo(
+                    f"  activity={row['activity']}, "
+                    f"transcripts={row['transcript_count']}, "
+                    f"activity_records={row['activity_record_count']}"
+                )
+            elif "session_id" in row:
+                typer.echo(
+                    f"{row['harness']} {row['state']} {json.dumps(row['session_id'])} "
+                    f"observed_in={json.dumps(row['observed_in'])}"
+                )
+                typer.echo(f"  Evidence: {row['evidence']}")
+            elif "code" in row:
+                typer.echo(f"{row['harness']} {row['code']} {json.dumps(row['path'])}")
+                typer.echo(f"  Evidence: {row['evidence']}")
+                typer.echo(f"  Next: {row['suggestion']}")
+            else:
+                typer.echo(json.dumps(row, ensure_ascii=True))
+        typer.echo(
+            f"Coverage: {'complete' if report.complete else 'incomplete'} "
+            f"for inspected metadata; {len(report.limitations)} declared limitations."
+        )
+        for limitation in report.limitations:
+            typer.echo(f"  Limit: {limitation['harness']}: {limitation['detail']}")
+        for diagnostic in report.diagnostics:
+            typer.echo(
+                f"{diagnostic['harness']} {diagnostic['code']}: "
+                f"{diagnostic['message']} {json.dumps(diagnostic['path'])}",
+                err=True,
+            )
+    if not report.complete:
+        raise typer.Exit(1)
+
+
+def project_rows(
+    snapshot: Snapshot,
+    context: Context,
+    names: list[str] | None,
+    path: Path,
+) -> list[dict[str, object]]:
+    target = path.expanduser().resolve()
+    result: list[dict[str, object]] = []
+    for harness in selected(names):
+        matches = [
+            project
+            for project in snapshot.projects
+            if project.path == target and project.harness == harness.name
+        ]
+        if not matches:
+            item = Project(target, harness.name, harness.config_file(context))
+            item.explicit_trust_inspected = snapshot.report.inspected(
+                harness.name, "project_config"
+            )
+            try:
+                item.exists = stat.S_ISDIR(target.stat().st_mode)
+            except FileNotFoundError:
+                item.exists = False
+            except OSError:
+                snapshot.report.add(
+                    harness.name,
+                    "unreadable-project",
+                    target,
+                    "Cannot inspect the requested project directory.",
+                )
+            matches = [item]
+        result.extend(project.as_dict() for project in matches)
+    return result
+
+
+def show_version(value: bool) -> None:
+    if value:
+        typer.echo(version("llar"))
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version_: Annotated[
+        bool, typer.Option("--version", callback=show_version, is_eager=True)
+    ] = False,
+) -> None:
+    """Inspect local coding-agent state."""
+
+
+@app.command()
+def harnesses(
+    home: Home = None, json_: Json = False, harness: Selection = None
+) -> None:
+    """Show detected harnesses and supported read capabilities."""
+    context = Context.create(home)
+    report = Report()
+    rows: list[dict[str, object]] = []
+    for item in selected(harness):
+        root = item.state_home(context)
+        config_path = item.config_file(context)
+        home_source = report.source(item.name, "home_discovery", root)
+        config_source = report.source(item.name, "config_discovery", config_path)
+        home_mode = home_source.mode(root, optional=True)
+        config_mode = config_source.mode(config_path, optional=True)
+        if home_mode is not None and not stat.S_ISDIR(home_mode):
+            home_source.problem(
+                "unsupported-home", root, "Harness home is not a directory."
+            )
+        if config_mode is not None and not stat.S_ISREG(config_mode):
+            config_source.problem(
+                "unsupported-config", config_path, "Config is not a regular file."
+            )
+        present = (home_mode is not None and stat.S_ISDIR(home_mode)) or (
+            config_mode is not None and stat.S_ISREG(config_mode)
+        )
+        unknown = home_source.status == "partial" or config_source.status == "partial"
+        rows.append(
+            {
+                "name": item.name,
+                "present": True if present else None if unknown else False,
+                "config_file": str(config_path),
+                "state_locations": [str(root), str(config_path)],
+                "capabilities": [
+                    "projects",
+                    "conversations",
+                    "activity",
+                    "diagnostics",
+                ],
+            }
+        )
+    emit(rows, json_, report)
+
+
+@app.command()
+def status(
+    path: ProjectPath = Path("."),
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+) -> None:
+    """Summarize one exact directory, including discovered storage locations."""
+    snapshot = inspect(home, harness)
+    emit(
+        project_rows(snapshot, Context.create(home), harness, path),
+        json_,
+        snapshot.report,
+    )
+
+
+@projects_app.command("list")
+def list_projects(
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+    directory: Directory = None,
+    recursive: Recursive = False,
+    missing: Annotated[bool, typer.Option(help="Only missing directories.")] = False,
+) -> None:
+    """List all recorded directories, optionally selecting an exact subtree."""
+    selection = scope(directory, recursive)
+    snapshot = inspect(home, harness)
+    emit(
+        [
+            row.as_dict()
+            for row in snapshot.projects
+            if selection.matches(row.path) and (not missing or row.exists is False)
+        ],
+        json_,
+        snapshot.report,
+    )
+
+
+@trust_app.command("show")
+def show_trust(
+    path: ProjectPath = Path("."),
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+) -> None:
+    """Show stored explicit trust, without inferring effective trust."""
+    snapshot = inspect(home, harness)
+    emit(
+        [
+            {
+                key: row[key]
+                for key in (
+                    "path",
+                    "harness",
+                    "explicit_trust",
+                    "explicit_trust_inspected",
+                    "config_file",
+                )
+            }
+            for row in project_rows(snapshot, Context.create(home), harness, path)
+        ],
+        json_,
+        snapshot.report,
+    )
+
+
+@sessions_app.command("list")
+def list_sessions(
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+    directory: Directory = None,
+    recursive: Recursive = False,
+    unassigned: Unassigned = False,
+    live: Annotated[
+        bool, typer.Option(help="Only verified active conversations.")
+    ] = False,
+) -> None:
+    """List conversations by starting directory, never substituting runtime cwd."""
+    selection = scope(directory, recursive, unassigned)
+    snapshot = inspect(home, harness)
+    emit(
+        [
+            row.as_dict()
+            for row in snapshot.conversations
+            if selection.matches(row.started_in)
+            and (not live or row.activity_state == "live")
+        ],
+        json_,
+        snapshot.report,
+    )
+
+
+@sessions_app.command("show")
+def show_session(
+    ref: str, home: Home = None, json_: Json = False, harness: Selection = None
+) -> None:
+    """Show metadata for one harness-qualified or unambiguous native session ID."""
+    snapshot = inspect(home, harness)
+    matches = [
+        row for row in snapshot.conversations if row.ref == ref or row.session_id == ref
+    ]
+    if not matches and not snapshot.report.complete:
+        emit([], json_, snapshot.report)
+    if len(matches) != 1:
+        raise typer.BadParameter(
+            "Session reference is missing or ambiguous; use harness:ID."
+        )
+    emit([matches[0].as_dict()], json_, snapshot.report)
+
+
+@activity_app.command("list")
+def list_activity(
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+    directory: Directory = None,
+    recursive: Recursive = False,
+    unassigned: Unassigned = False,
+    state: Annotated[
+        str | None, typer.Option(help="Filter live, stale or unknown observations.")
+    ] = None,
+) -> None:
+    """List runtime observations by observed directory, including stale records."""
+    selection = scope(directory, recursive, unassigned)
+    if state is not None and state not in ("live", "stale", "unknown"):
+        raise typer.BadParameter("--state must be live, stale or unknown.")
+    snapshot = inspect(home, harness)
+    emit(
+        [
+            row.as_dict()
+            for row in snapshot.activity
+            if selection.matches(row.observed_in)
+            and (state is None or row.state == state)
+        ],
+        json_,
+        snapshot.report,
+    )
+
+
+@app.command()
+def doctor(
+    home: Home = None,
+    json_: Json = False,
+    harness: Selection = None,
+    directory: Directory = None,
+    recursive: Recursive = False,
+    unassigned: Unassigned = False,
+) -> None:
+    """Explain issues in inspected state without repairing anything."""
+    selection = scope(directory, recursive, unassigned)
+    snapshot = inspect(home, harness)
+    findings = snapshot.findings
+    emit(
+        [
+            row.as_dict()
+            for row in findings
+            if selection.matches(
+                None if row.code == "unassigned-state" else Path(row.path)
+            )
+        ],
+        json_,
+        snapshot.report,
+        empty="No issues found in inspected state.",
+    )
+
+
+def emit_transfer(
+    plan: TransferPlan,
+    *,
+    apply: bool,
+    json_: bool,
+    result: CopyResult | None = None,
+) -> None:
+    mode = "apply" if apply else "dry-run"
+    row = {"mode": mode, **plan.as_dict()}
+    if result is not None:
+        row.update(result.as_dict())
+    if json_:
+        typer.echo(
+            json.dumps(
+                {
+                    "schema_version": 1,
+                    "items": [row],
+                    "diagnostics": plan.diagnostics,
+                    "coverage": plan.coverage(),
+                }
+            )
+        )
+    else:
+        typer.echo(f"{plan.operation} {mode}")
+        for label, address, root in (
+            ("Source", plan.source_endpoint, plan.source),
+            ("Destination", plan.destination_endpoint, plan.destination),
+        ):
+            value = str(root) if root is not None else f"{address.host}:{address.path}"
+            if address.host is not None and root is not None:
+                value = f"{address.host}:{root}"
+            typer.echo(f"{label}: {json.dumps(value)}")
+        typer.echo("Components: " + ", ".join(plan.components))
+        typer.echo(f"Proposed changes: {len(plan.changes)}")
+        for change in plan.changes:
+            target = str(change.destination) if change.destination is not None else None
+            typer.echo(
+                f"  {change.effect} {change.harness or 'filesystem'} "
+                f"{change.component}: {json.dumps(str(change.source))} "
+                f"-> {json.dumps(target)}"
+            )
+            if change.source_key or change.destination_key:
+                typer.echo(
+                    f"    selector: {json.dumps(change.source_key)} "
+                    f"-> {json.dumps(change.destination_key)}"
+                )
+            if change.destination_owners:
+                typer.echo(
+                    "    owners: "
+                    + json.dumps([str(owner) for owner in change.destination_owners])
+                )
+            if change.started_in is not None:
+                typer.echo(
+                    f"    started_in (preserved): {json.dumps(str(change.started_in))}"
+                )
+            if change.cleanup == "after_verification":
+                typer.echo("    source cleanup only after verification")
+        for blocker in plan.blockers:
+            location = str(blocker.path) if blocker.path is not None else None
+            typer.echo(
+                f"BLOCKED {blocker.code} ({blocker.endpoint}): "
+                f"{json.dumps(blocker.message)} {json.dumps(location)}"
+            )
+        for diagnostic in plan.diagnostics:
+            if diagnostic.get("incomplete") is True:
+                typer.echo(
+                    f"  {diagnostic['endpoint']} {diagnostic['code']}: "
+                    f"{json.dumps(diagnostic['message'])} "
+                    f"{json.dumps(diagnostic['path'])}"
+                )
+        typer.echo(
+            "Inspection coverage: "
+            + ("complete" if plan.coverage()["complete"] else "incomplete")
+            + " for declared metadata. Transfer support is incomplete."
+        )
+        if result is not None and result.applied:
+            typer.echo("Copy completed and verified. Source retained.")
+        elif result is not None and result.error is not None:
+            typer.echo(f"Apply failed: {result.error}. Source retained.")
+            publication = (
+                "unknown"
+                if row.get("publication_unknown")
+                else result.destination_published
+            )
+            typer.echo(f"Destination published: {publication}")
+        else:
+            typer.echo("No changes made.")
+            if plan.can_apply:
+                typer.echo("Use --apply to perform this copy.")
+        native = row.get("published_native")
+        if isinstance(native, list):
+            for path in native:
+                typer.echo("Published native state: " + json.dumps(path))
+        if result is not None and result.record is not None:
+            host = row.get("operation_host")
+            receipt = f"{host}:{result.record}" if host else str(result.record)
+            typer.echo("Operation record: " + json.dumps(receipt))
+        if result is not None and result.staging is not None:
+            host = row.get("operation_host")
+            stage = f"{host}:{result.staging}" if host else str(result.staging)
+            typer.echo("Staging retained: " + json.dumps(stage))
+    if (
+        plan.blockers
+        or not plan.coverage()["complete"]
+        or result is not None
+        and result.error is not None
+    ):
+        raise typer.Exit(1)
+
+
+@app.command("mv", help="Plan a project move; application is not implemented.")
+@app.command("cp", help="Plan a copy; apply files or supported local native state.")
+def transfer(
+    context: typer.Context,
+    source: Annotated[
+        str, typer.Argument(help="Explicit local or SSH source directory.")
+    ],
+    destination: Annotated[
+        str, typer.Argument(help="Exact resulting local or SSH project directory.")
+    ],
+    home: Home = None,
+    target_home: Annotated[
+        Path | None,
+        typer.Option(
+            "--target-home",
+            help="Isolated destination home; defaults to --home for local transfers.",
+        ),
+    ] = None,
+    ssh_config: Annotated[
+        Path | None,
+        typer.Option(
+            "--ssh-config", help="OpenSSH configuration file for this transfer."
+        ),
+    ] = None,
+    only: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--only",
+            help="Select files, sessions, memory, settings or artifacts; repeatable.",
+        ),
+    ] = None,
+    harness: Selection = None,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Show the transfer plan (default).")
+    ] = False,
+    apply_: Annotated[
+        bool,
+        typer.Option("--apply", help="Apply a supported transfer after preflight."),
+    ] = False,
+    json_: Json = False,
+) -> None:
+    if dry_run and apply_:
+        raise typer.BadParameter("--apply and --dry-run are mutually exclusive.")
+    names = tuple(item.name for item in selected(harness))
+    try:
+        origin = Endpoint.parse(source)
+        target = Endpoint.parse(destination)
+        if target_home is None and origin.host is None and target.host is None:
+            target_home = home
+        if origin.host is not None or target.host is not None:
+            from llar.core.ssh_transfer import execute, plan_transfer
+
+            plan, connection = plan_transfer(
+                "mv" if context.info_name == "mv" else "cp",
+                origin,
+                target,
+                home=home,
+                target_home=target_home,
+                only=set(only) if only is not None else None,
+                harnesses=names,
+                ssh_config=ssh_config,
+            )
+            remote_result = execute(plan, connection, apply=True) if apply_ else None
+            emit_transfer(plan, apply=apply_, json_=json_, result=remote_result)
+            return
+        if ssh_config is not None:
+            raise typer.BadParameter("--ssh-config requires one SSH endpoint.")
+        plan = build_plan(
+            "mv" if context.info_name == "mv" else "cp",
+            origin,
+            target,
+            Context.create(home),
+            Context.create(target_home),
+            only=set(only) if only is not None else None,
+            harnesses=names,
+        )
+    except typer.Exit:
+        raise
+    except TransferError as error:
+        raise typer.BadParameter(str(error)) from None
+    except (OSError, RuntimeError):
+        raise typer.BadParameter(
+            "Cannot resolve the requested filesystem context."
+        ) from None
+    result = (
+        execute_application(
+            plan,
+            Context.create(home),
+            Context.create(target_home),
+            apply=True,
+        )
+        if apply_ and plan.can_apply
+        else None
+    )
+    emit_transfer(plan, apply=apply_, json_=json_, result=result)
+
+
+@app.command("_remote", hidden=True)
+def remote_peer() -> None:
+    from llar.core.ssh import serve
+
+    serve()
+
+
+@app.command(
+    "_rsync",
+    hidden=True,
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def remote_rsync(context: typer.Context) -> None:
+    from llar.core.ssh import serve_rsync
+
+    serve_rsync(context.args)

llar/core/__init__.py

@@ -0,0 +1,2 @@
+# ABOUTME: Holds shared domain primitives for local agent state.
+# ABOUTME: Keeps harness-independent data separate from command rendering.

llar/core/activity.py

@@ -0,0 +1,32 @@
+# ABOUTME: Represents live, stale and unverifiable runtime ownership observations.
+# ABOUTME: Keeps process and writer-lock evidence separate from transcript counts.
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+ActivityState = Literal["live", "stale", "unknown"]
+
+
+@dataclass(frozen=True)
+class Activity:
+    harness: str
+    session_id: str | None
+    observed_in: Path | None
+    source: Path
+    state: ActivityState
+    evidence: str
+    pid: int | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "harness": self.harness,
+            "session_id": self.session_id,
+            "observed_in": str(self.observed_in)
+            if self.observed_in is not None
+            else None,
+            "source": str(self.source),
+            "state": self.state,
+            "evidence": self.evidence,
+            "pid": self.pid,
+        }