aisquare-cli 0.1.0__py3-none-any.whl

aisquare/__init__.py

@@ -0,0 +1,10 @@
+"""aisquare — a portable memory layer for coding agents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("aisquare-cli")
+except PackageNotFoundError:  # pragma: no cover - only when running from a raw checkout
+    __version__ = "0.0.0+uninstalled"
+
+__all__ = ["__version__"]

aisquare/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m aisquare``."""
+
+from aisquare.cli.app import main
+
+if __name__ == "__main__":
+    main()

aisquare/cli/__init__.py

@@ -0,0 +1 @@
+"""Thin Typer layer — parses arguments and delegates to the service layer."""

aisquare/cli/agents.py

@@ -0,0 +1,60 @@
+"""``aisquare agents`` — detect and connect coding agents."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from aisquare.cli.common import emit_agents, emit_connected, emit_disconnected, fail
+from aisquare.services import agents as agents_service
+
+app = typer.Typer(help="Detect and connect coding agents.", no_args_is_help=True)
+
+AgentName = Annotated[str, typer.Argument(help="Agent name, e.g. 'claude-code'.")]
+
+
+@app.command("list")
+def list_() -> None:
+    """List supported agents and whether they are connected."""
+    emit_agents(agents_service.list_agents())
+
+
+@app.command("scan")
+def scan() -> None:
+    """Scan this machine for installed agents."""
+    emit_agents(agents_service.scan())
+
+
+@app.command("status")
+def status(
+    name: Annotated[str | None, typer.Argument(help="Agent to inspect (default: all).")] = None,
+) -> None:
+    """Show integration health for one agent, or all of them."""
+    try:
+        agents = agents_service.status(name)
+    except KeyError:
+        fail(f"unknown agent: {name}", error="unknown_agent", ref=name)
+    emit_agents(agents)
+
+
+@app.command("connect")
+def connect(name: AgentName) -> None:
+    """Connect an agent: install aisquare's hooks and ingest its existing context."""
+    try:
+        connection = agents_service.connect(name)
+    except KeyError:
+        fail(f"unknown agent: {name}", error="unknown_agent", ref=name)
+    except ValueError as exc:
+        fail(str(exc), error="not_installed", ref=name)
+    emit_connected(connection)
+
+
+@app.command("disconnect")
+def disconnect(name: AgentName) -> None:
+    """Disconnect an agent (its already-imported context is kept)."""
+    try:
+        agents_service.disconnect(name)
+    except KeyError:
+        fail(f"unknown agent: {name}", error="unknown_agent", ref=name)
+    emit_disconnected(name)

aisquare/cli/app.py

@@ -0,0 +1,101 @@
+"""Root Typer application: global flags, version, and command registration."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from aisquare import __version__
+from aisquare.cli import (
+    agents,
+    auth,
+    capture,
+    connectors,
+    context,
+    enforce,
+    hook,
+    policy,
+    project,
+    root,
+)
+from aisquare.cli import config as config_cli
+from aisquare.core.state import RuntimeState, set_state
+
+app = typer.Typer(
+    help="Portable memory layer for coding agents.",
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    pretty_exceptions_show_locals=False,
+)
+
+
+def _print_version(value: bool) -> None:
+    """Eager callback for ``--version``."""
+    if value:
+        typer.echo(f"aisquare {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show the version and exit.",
+            callback=_print_version,
+            is_eager=True,
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Enable verbose output.")
+    ] = False,
+    quiet: Annotated[
+        bool, typer.Option("--quiet", "-q", help="Suppress non-essential output.")
+    ] = False,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Emit machine-readable JSON on stdout.")
+    ] = False,
+    profile: Annotated[
+        str, typer.Option("--profile", help="Configuration profile to use.", metavar="NAME")
+    ] = "default",
+    no_color: Annotated[bool, typer.Option("--no-color", help="Disable coloured output.")] = False,
+) -> None:
+    """Portable memory layer for coding agents.
+
+    Keeps user preferences and per-project conventions persistent across
+    agent sessions.
+    """
+    state = RuntimeState(
+        verbose=verbose,
+        quiet=quiet,
+        json_output=json_output,
+        profile=profile,
+        no_color=no_color,
+    )
+    set_state(state)
+    ctx.obj = state
+
+
+root.register(app)
+
+app.add_typer(auth.app, name="auth")
+app.add_typer(agents.app, name="agents")
+app.add_typer(connectors.app, name="connectors")
+app.add_typer(context.app, name="context")
+app.add_typer(context.app, name="ctx", hidden=True, help="Alias of 'context'.")
+app.add_typer(project.app, name="project")
+app.add_typer(project.app, name="workspace", hidden=True, help="Alias of 'project'.")
+app.add_typer(capture.app, name="capture")
+app.add_typer(config_cli.app, name="config")
+app.add_typer(policy.app, name="policy")
+app.add_typer(enforce.app, name="enforce")
+app.add_typer(hook.app, name="hook", hidden=True)
+
+
+def main() -> None:
+    """Console-script entry point for both ``aisquare`` and ``asq``."""
+    app()

aisquare/cli/auth.py

@@ -0,0 +1,27 @@
+"""``aisquare auth`` — inspect and manage credentials."""
+
+from __future__ import annotations
+
+import typer
+
+from aisquare.services import auth as auth_service
+
+app = typer.Typer(help="Inspect and manage credentials.", no_args_is_help=True)
+
+
+@app.command("status")
+def status() -> None:
+    """Show whether this machine is authenticated, and as whom."""
+    auth_service.status()
+
+
+@app.command("rotate")
+def rotate() -> None:
+    """Rotate the stored API token."""
+    auth_service.rotate()
+
+
+@app.command("token")
+def token() -> None:
+    """Print the active API token (for scripting)."""
+    auth_service.token()

aisquare/cli/capture.py

@@ -0,0 +1,39 @@
+"""``aisquare capture`` — the background capture pipeline."""
+
+from __future__ import annotations
+
+import typer
+
+from aisquare.services import capture as capture_service
+
+app = typer.Typer(help="Control background capture of agent activity.", no_args_is_help=True)
+
+
+@app.command("status")
+def status() -> None:
+    """Show whether capture is running."""
+    capture_service.status()
+
+
+@app.command("pause")
+def pause() -> None:
+    """Pause capture without removing hooks."""
+    capture_service.pause()
+
+
+@app.command("resume")
+def resume() -> None:
+    """Resume paused capture."""
+    capture_service.resume()
+
+
+@app.command("start")
+def start() -> None:
+    """Start the capture pipeline."""
+    capture_service.start()
+
+
+@app.command("stop")
+def stop() -> None:
+    """Stop the capture pipeline."""
+    capture_service.stop()

aisquare/cli/common.py

@@ -0,0 +1,350 @@
+"""Shared CLI parsing and rendering helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import NoReturn
+
+import tomli_w
+import typer
+from rich.table import Table
+
+from aisquare.core.config import AppConfig
+from aisquare.core.console import stderr_console, stdout_console
+from aisquare.core.state import get_state
+from aisquare.models import (
+    AgentConnection,
+    AgentInfo,
+    CheckStatus,
+    ContextEntry,
+    DoctorCheck,
+    InjectionRecord,
+    OnboardReport,
+    Pool,
+    ProjectInfo,
+    PromptRecord,
+    SetupReport,
+    StatusReport,
+)
+
+_DEFAULT_EMPTY = 'No context entries yet. Add one with: aisquare remember "…"'
+
+
+def resolve_pool(user: bool, project: bool) -> Pool | None:
+    """Map the ``--user``/``--project`` flag pair onto a pool name.
+
+    Returns ``None`` when neither flag is given, letting the service apply
+    the configured default pool.
+    """
+    if user and project:
+        raise typer.BadParameter("--user and --project are mutually exclusive.")
+    if user:
+        return "user"
+    if project:
+        return "project"
+    return None
+
+
+def emit_entry(entry: ContextEntry, *, verb: str) -> None:
+    """Render a single entry — JSON under ``--json``, a confirmation otherwise."""
+    if get_state().json_output:
+        typer.echo(entry.model_dump_json())
+    else:
+        stdout_console().print(f"✓ {verb} ({entry.pool}): {entry.text}")
+
+
+def emit_entries(entries: list[ContextEntry], *, empty_message: str = _DEFAULT_EMPTY) -> None:
+    """Render a list of entries — a JSON array under ``--json``, a table otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps([entry.model_dump(mode="json") for entry in entries]))
+        return
+    if not entries:
+        stdout_console().print(empty_message)
+        return
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("ID", no_wrap=True)
+    table.add_column("POOL", no_wrap=True)
+    table.add_column("TAGS")
+    table.add_column("TEXT")
+    for entry in entries:
+        table.add_row(entry.id, entry.pool, ", ".join(entry.tags), entry.text)
+    stdout_console().print(table)
+
+
+def emit_removed(ref: str) -> None:
+    """Confirm a deletion — JSON under ``--json``, a confirmation otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps({"removed": ref}, separators=(",", ":")))
+    else:
+        stdout_console().print(f"✓ removed {ref}")
+
+
+def emit_imported(count: int) -> None:
+    """Confirm an import — JSON under ``--json``, a confirmation otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps({"imported": count}, separators=(",", ":")))
+    else:
+        noun = "entry" if count == 1 else "entries"
+        stdout_console().print(f"✓ imported {count} {noun}")
+
+
+def emit_exported(file: Path) -> None:
+    """Confirm an export to a file — JSON under ``--json``, a confirmation otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps({"exported": str(file)}, separators=(",", ":")))
+    else:
+        stdout_console().print(f"✓ exported to {file}")
+
+
+def emit_entry_detail(entry: ContextEntry) -> None:
+    """Render one entry in full — JSON under ``--json``, a key/value view otherwise."""
+    if get_state().json_output:
+        typer.echo(entry.model_dump_json())
+        return
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column()
+    grid.add_row("id", entry.id)
+    grid.add_row("pool", entry.pool)
+    if entry.project_id:
+        grid.add_row("project", entry.project_id)
+    if entry.tags:
+        grid.add_row("tags", ", ".join(entry.tags))
+    grid.add_row("created", entry.created_at.isoformat())
+    grid.add_row("updated", entry.updated_at.isoformat())
+    console = stdout_console()
+    console.print(grid)
+    console.print()
+    console.print(entry.text)
+
+
+def emit_block(block: str) -> None:
+    """Emit an assembled context block — wrapped under ``--json``, verbatim otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps({"block": block}))
+    else:
+        typer.echo(block, nl=False)
+
+
+def emit_injection_record(record: InjectionRecord | None) -> None:
+    """Render the last-injection record for ``why``."""
+    if get_state().json_output:
+        typer.echo("null" if record is None else record.model_dump_json())
+        return
+    console = stdout_console()
+    if record is None:
+        console.print("No context has been injected yet. Run: aisquare inject")
+        return
+    total = record.user_count + record.project_count
+    console.print(f"Last injection: {record.injected_at.isoformat()}")
+    console.print(
+        f"  {total} entries — {record.user_count} from your user pool, "
+        f"{record.project_count} from this project"
+    )
+
+
+def emit_project_detail(project: ProjectInfo) -> None:
+    """Render one project — JSON under ``--json``, a key/value view otherwise."""
+    if get_state().json_output:
+        typer.echo(project.model_dump_json())
+        return
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column()
+    grid.add_row("name", project.root.name or project.id)
+    grid.add_row("id", project.id)
+    grid.add_row("root", str(project.root))
+    if project.linked_repos:
+        grid.add_row("repos", ", ".join(project.linked_repos))
+    stdout_console().print(grid)
+
+
+def emit_projects(projects: list[ProjectInfo], *, active_id: str | None) -> None:
+    """Render the project list — a JSON array under ``--json``, a table otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps([project.model_dump(mode="json") for project in projects]))
+        return
+    if not projects:
+        stdout_console().print("No projects registered yet. Run: aisquare init")
+        return
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("", no_wrap=True)
+    table.add_column("NAME")
+    table.add_column("ID", no_wrap=True)
+    table.add_column("ROOT")
+    for project in projects:
+        marker = "*" if project.id == active_id else ""
+        table.add_row(marker, project.root.name or "—", project.id, str(project.root))
+    stdout_console().print(table)
+
+
+def emit_project_action(message: str, project: ProjectInfo) -> None:
+    """Confirm a project action — the project as JSON under ``--json``, a message otherwise."""
+    if get_state().json_output:
+        typer.echo(project.model_dump_json())
+    else:
+        stdout_console().print(message)
+
+
+def emit_setup(report: SetupReport) -> None:
+    """Render the outcome of ``init``."""
+    if get_state().json_output:
+        typer.echo(report.model_dump_json())
+        return
+    console = stdout_console()
+    verb = "already initialized" if report.already_initialized else "initialized"
+    console.print(f"✓ aisquare {verb} at {report.home}")
+    console.print(
+        f"  project: {report.project.root.name or report.project.id} ({report.project.id})"
+    )
+    if report.onboarded:
+        console.print(f"  onboarded {report.onboarded} context entries")
+    for note in report.notes:
+        console.print(f"  note: {note}")
+
+
+def emit_config(config: AppConfig) -> None:
+    """Render the full config — JSON under ``--json``, TOML otherwise."""
+    if get_state().json_output:
+        typer.echo(config.model_dump_json())
+    else:
+        typer.echo(tomli_w.dumps(config.model_dump(mode="json")), nl=False)
+
+
+def emit_config_value(key: str, value: str) -> None:
+    """Render one config value — ``{key: value}`` under ``--json``, ``key = value`` otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps({key: value}))
+    else:
+        stdout_console().print(f"{key} = {value}")
+
+
+def emit_agents(agents: list[AgentInfo]) -> None:
+    """Render detected agents — a JSON array under ``--json``, a table otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps([agent.model_dump(mode="json") for agent in agents]))
+        return
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("AGENT")
+    table.add_column("DETECTED")
+    table.add_column("CONNECTED")
+    table.add_column("CONTEXT")
+    for agent in agents:
+        context = ", ".join(str(path) for path in agent.config_paths) or "—"
+        table.add_row(
+            agent.name,
+            "yes" if agent.detected else "no",
+            "yes" if agent.connected else "no",
+            context,
+        )
+    stdout_console().print(table)
+
+
+def emit_connected(connection: AgentConnection) -> None:
+    """Confirm an agent connection: hook install + context ingested."""
+    if get_state().json_output:
+        typer.echo(connection.model_dump_json())
+        return
+    hooks = "hooks installed" if connection.hooks_installed else "no hooks for this agent"
+    noun = "entry" if connection.imported == 1 else "entries"
+    stdout_console().print(
+        f"✓ connected {connection.name} — {hooks}; imported {connection.imported} {noun}"
+    )
+
+
+def emit_onboard(report: OnboardReport) -> None:
+    """Render the outcome of ``project onboard`` — snapshot summary + seeded facts."""
+    if get_state().json_output:
+        typer.echo(report.model_dump_json())
+        return
+    console = stdout_console()
+    snapshot = report.snapshot
+    if snapshot is not None and snapshot.status == "ready":
+        line = f"✓ snapshot: {snapshot.file_count} files, {snapshot.token_count} tokens"
+        if snapshot.skeleton_token_count:
+            line += f" (skeleton {snapshot.skeleton_token_count} tokens)"
+        console.print(line)
+    elif snapshot is not None and snapshot.status == "too_large":
+        console.print("snapshot: codebase too large to pack within the token budget")
+    else:
+        console.print("snapshot: skipped (repomix/Node not available)")
+    if report.seeded:
+        console.print(f"seeded {len(report.seeded)} project fact(s):")
+        for entry in report.seeded:
+            console.print(f"  - {entry.text}")
+
+
+def emit_prompts(prompts: list[PromptRecord]) -> None:
+    """Render captured prompt history — a JSON array under ``--json``, a table otherwise."""
+    if get_state().json_output:
+        typer.echo(json.dumps([prompt.model_dump(mode="json") for prompt in prompts]))
+        return
+    if not prompts:
+        stdout_console().print(
+            "No prompts captured yet. Connect Claude Code: aisquare agents connect claude-code"
+        )
+        return
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("WHEN", no_wrap=True)
+    table.add_column("PROMPT")
+    for prompt in prompts:
+        table.add_row(prompt.created_at.strftime("%Y-%m-%d %H:%M"), prompt.text)
+    stdout_console().print(table)
+
+
+def emit_disconnected(name: str) -> None:
+    """Confirm an agent disconnection."""
+    if get_state().json_output:
+        typer.echo(json.dumps({"disconnected": name}, separators=(",", ":")))
+    else:
+        stdout_console().print(f"✓ disconnected {name}")
+
+
+def emit_status(report: StatusReport) -> None:
+    """Render the status summary."""
+    if get_state().json_output:
+        typer.echo(report.model_dump_json())
+        return
+    console = stdout_console()
+    project = report.active_project
+    console.print(f"aisquare: {'initialized' if report.initialized else 'not initialized'}")
+    console.print(f"home:     {report.home}")
+    console.print(f"project:  {project.root.name or project.id} ({project.id})")
+    console.print(
+        f"context:  {report.user_entries} user, {report.project_entries} in this project; "
+        f"{report.project_count} project(s) registered"
+    )
+    console.print(f"detected: {', '.join(report.agents_detected) or 'none'}")
+    console.print(f"connected: {', '.join(report.agents_connected) or 'none'}")
+
+
+_CHECK_SYMBOL = {CheckStatus.ok: "✓", CheckStatus.warn: "⚠", CheckStatus.fail: "✗"}
+
+
+def emit_doctor(checks: list[DoctorCheck]) -> None:
+    """Render diagnostic check results, with a fix hint for anything not OK."""
+    if get_state().json_output:
+        typer.echo(json.dumps([check.model_dump(mode="json") for check in checks]))
+        return
+    console = stdout_console()
+    for check in checks:
+        console.print(f"{_CHECK_SYMBOL[check.status]} {check.name}: {check.detail}")
+        if check.fix and check.status is not CheckStatus.ok:
+            console.print(f"    → {check.fix}")
+
+
+def fail(message: str, *, error: str, ref: str | None = None, exit_code: int = 1) -> NoReturn:
+    """Report a runtime error and exit.
+
+    Mirrors the stub contract: a machine-readable object on stdout under
+    ``--json``, a human message on stderr otherwise.
+    """
+    if get_state().json_output:
+        payload = {"error": error}
+        if ref is not None:
+            payload["ref"] = ref
+        typer.echo(json.dumps(payload, separators=(",", ":")))
+    else:
+        stderr_console().print(f"✗ {message}")
+    raise typer.Exit(exit_code)

aisquare/cli/config.py

@@ -0,0 +1,54 @@
+"""``aisquare config`` — read and write configuration."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from aisquare.cli.common import emit_config, emit_config_value, fail
+from aisquare.models import RedactionLevel
+from aisquare.services import settings as settings_service
+
+app = typer.Typer(help="Read and write aisquare configuration.", no_args_is_help=True)
+
+
+@app.command("list")
+def list_() -> None:
+    """Print the fully-resolved configuration."""
+    emit_config(settings_service.list_values())
+
+
+@app.command("get")
+def get(
+    key: Annotated[str, typer.Argument(help="Dotted key, e.g. 'redaction.level'.")],
+) -> None:
+    """Print a single configuration value."""
+    try:
+        value = settings_service.get_value(key)
+    except KeyError:
+        fail(f"unknown config key: {key}", error="unknown_key", ref=key)
+    emit_config_value(key, value)
+
+
+@app.command("set")
+def set_(
+    key: Annotated[str, typer.Argument(help="Dotted key, e.g. 'capture.enabled'.")],
+    value: Annotated[str, typer.Argument(help="New value.")],
+) -> None:
+    """Set a configuration value and save it."""
+    try:
+        stored = settings_service.set_value(key, value)
+    except KeyError:
+        fail(f"unknown config key: {key}", error="unknown_key", ref=key)
+    except ValueError as exc:
+        fail(str(exc), error="invalid_value", ref=key)
+    emit_config_value(key, stored)
+
+
+@app.command("redaction")
+def redaction(
+    level: Annotated[RedactionLevel, typer.Argument(help="Redaction level.")],
+) -> None:
+    """Set how aggressively captured data is scrubbed."""
+    emit_config_value("redaction.level", settings_service.set_redaction(level))

aisquare/cli/connectors.py

@@ -0,0 +1,37 @@
+"""``aisquare connectors`` — external sources feeding the context pools."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from aisquare.services import connectors as connectors_service
+
+app = typer.Typer(help="Manage connectors to external sources.", no_args_is_help=True)
+
+ConnectorName = Annotated[str, typer.Argument(help="Connector name, e.g. 'notion'.")]
+
+
+@app.command("list")
+def list_() -> None:
+    """List available and configured connectors."""
+    connectors_service.list_connectors()
+
+
+@app.command("add")
+def add(name: ConnectorName) -> None:
+    """Add and configure a connector."""
+    connectors_service.add(name)
+
+
+@app.command("remove")
+def remove(name: ConnectorName) -> None:
+    """Remove a configured connector."""
+    connectors_service.remove(name)
+
+
+@app.command("status")
+def status() -> None:
+    """Show connector health and last sync times."""
+    connectors_service.status()