alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/cli.py

@@ -0,0 +1,517 @@
+"""Command-line entrypoint for alter-runtime.
+
+Subcommands:
+  init      Generate Ed25519 device keypair, install host service unit,
+            verify alter-cli session, ensure XDG directories exist.
+  start     Enable + start the host service unit (systemd/launchd/Windows Service).
+  stop      Stop the host service unit.
+  status    Report current daemon state (running? socket reachable? last event?).
+  daemon    Run the supervisor in the foreground (for systemd Type=exec or debugging).
+  query     Query the current materialised view (attunement, warmth, trust tier).
+  ingest    Manually ingest a signal (for testing).
+
+Matches the shape of the alter-cli (Node/TS) command handler at
+/mnt/personal/Workspaces/alter-cli/src/index.ts:24-79 - simple switch-on-verb,
+no external CLI framework dependency (argparse is stdlib).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from alter_runtime.config import (
+    cache_dir,
+    config_dir,
+    ensure_directories,
+    keypair_path,
+    load_config,
+    load_session,
+    unix_socket_path,
+)
+from alter_runtime.daemon import run_daemon
+from alter_runtime.service_install import current_platform, service_status
+from alter_runtime.service_install import install as install_service
+from alter_runtime.service_install import uninstall as uninstall_service
+
+__all__ = ["build_parser", "main"]
+
+logger = logging.getLogger("alter_runtime.cli")
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="alter-runtime",
+        description=(
+            "~Alter Identity Runtime - L3 local sovereign daemon. "
+            "See packages/alter-runtime/README.md for architectural context."
+        ),
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Logging verbosity (overrides ALTER_RUNTIME_LOG_LEVEL).",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # init
+    p_init = sub.add_parser(
+        "init",
+        help="Bootstrap: generate keypair, ensure dirs, verify session.",
+    )
+    p_init.add_argument(
+        "--force",
+        action="store_true",
+        help="Regenerate the keypair even if one already exists.",
+    )
+    p_init.add_argument(
+        "--install-service",
+        action="store_true",
+        help=(
+            "Also install the host service unit (systemd user unit on Linux, "
+            "launchd LaunchAgent on macOS) without starting it."
+        ),
+    )
+
+    # start
+    p_start = sub.add_parser(
+        "start",
+        help="Install + enable + start the host service unit.",
+    )
+    p_start.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Render the unit file and print the service commands without touching the filesystem.",
+    )
+    p_start.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip the interactive consent prompt (CI / package-manager use).",
+    )
+    p_start.add_argument(
+        "--reinstall",
+        action="store_true",
+        help=(
+            "Reinstall a previously-uninstalled artefact, bypassing the "
+            "deletion-permanence tombstone."
+        ),
+    )
+
+    # stop
+    sub.add_parser("stop", help="Disable + stop the host service unit.")
+
+    # status
+    sub.add_parser("status", help="Report daemon state and local connectivity.")
+
+    # daemon (foreground)
+    sub.add_parser("daemon", help="Run the supervisor in the foreground.")
+
+    # query
+    p_query = sub.add_parser("query", help="Query the current materialised view.")
+    p_query.add_argument(
+        "field",
+        nargs="?",
+        choices=["handle", "attunement", "warmth", "income", "trust_tier", "all"],
+        default="all",
+    )
+
+    # ingest
+    p_ingest = sub.add_parser("ingest", help="Manually ingest a signal (for testing).")
+    p_ingest.add_argument("--kind", required=True, help="Signal kind (e.g. tool_invocation).")
+    p_ingest.add_argument(
+        "--payload",
+        default="{}",
+        help="JSON-encoded payload for the signal.",
+    )
+    p_ingest.add_argument("--producer", default="cli:manual", help="Producer identifier.")
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Bootstrap the daemon environment."""
+    ensure_directories()
+    logger.info("config dir: %s", config_dir())
+    logger.info("cache dir: %s", cache_dir())
+    logger.info("unix socket: %s", unix_socket_path())
+
+    # Keypair
+    kp_path = keypair_path()
+    if kp_path.exists() and not args.force:
+        logger.info("keypair already exists at %s (use --force to regenerate)", kp_path)
+    else:
+        _generate_keypair(kp_path)
+        logger.info("keypair generated at %s", kp_path)
+
+    # Session check
+    session = load_session()
+    if session is None:
+        print(
+            "\nNo alter-cli session found. Run `alter login` to authenticate,\n"
+            "then re-run `alter-runtime init` to complete bootstrap.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"\nReady. handle={session.handle} consent_tier=L{session.consent_tier}")
+
+    if args.install_service:
+        try:
+            result = install_service(enable=False, dry_run=False)
+        except (FileNotFoundError, NotImplementedError) as exc:
+            print(f"service install skipped: {exc}", file=sys.stderr)
+        else:
+            print(f"service unit written to {result.unit_path} (not started)")
+
+    print("Next: `alter-runtime start` to launch the host service.")
+    return 0
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Install + enable + start the host service unit."""
+    import importlib.metadata
+
+    from alter_runtime.consent import (
+        ConsentDeclined,
+        UserDeletedArtefact,
+        enumerate_artefacts,
+        print_consent_screen,
+        prompt_consent,
+        remove_tombstone,
+        write_manifest_entry,
+    )
+
+    platform = current_platform()
+    if platform not in ("linux", "darwin"):
+        print(
+            f"alter-runtime start is not yet supported on platform={platform!r}. "
+            "Run `alter-runtime daemon` in the foreground for debugging.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # C1 - consent gate. Enumerate artefacts, render the consent screen, and
+    # wait for explicit confirmation before touching the filesystem.
+    # Skipped on --dry-run (no writes happen) and bypassed by --yes.
+    if not args.dry_run:
+        artefacts = enumerate_artefacts()
+        print_consent_screen(artefacts, uninstall_cmd="alter-runtime stop")
+        try:
+            prompt_consent(yes=args.yes)
+        except ConsentDeclined:
+            print("Install cancelled.")
+            return 1
+    else:
+        artefacts = enumerate_artefacts()
+
+    try:
+        result = install_service(
+            enable=True,
+            dry_run=args.dry_run,
+            reinstall=getattr(args, "reinstall", False),
+        )
+    except UserDeletedArtefact as exc:
+        print(
+            f"  {exc.args[0]} was previously deleted by the user.\n"
+            "  ALTER will not recreate it automatically.\n"
+            "  To reinstall, run: alter-runtime start --reinstall",
+            file=sys.stderr,
+        )
+        return 1
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.dry_run:
+        print("--- rendered unit ---")
+        print(result.rendered)
+        print("--- service commands ---")
+        for cmd in result.service_commands:
+            print(" ".join(cmd))
+        return 0
+
+    # C2 - post-install manifest. Write a manifest entry for every artefact
+    # that was successfully installed.
+    try:
+        version = importlib.metadata.version("alter-runtime")
+    except importlib.metadata.PackageNotFoundError:
+        version = "unknown"
+
+    for artefact in artefacts:
+        try:
+            write_manifest_entry(artefact, version=version)
+        except OSError as exc:
+            # Manifest write failure is non-fatal - the install succeeded.
+            print(f"  warning: could not write manifest entry: {exc}", file=sys.stderr)
+
+    # C3 - if --reinstall was passed and succeeded, clear the tombstone so
+    # subsequent starts don't need --reinstall again.
+    if getattr(args, "reinstall", False):
+        for artefact in artefacts:
+            try:
+                remove_tombstone(artefact["path"])
+            except OSError:
+                pass
+
+    print(f"installed {result.unit_path}")
+    for cmd, exit_code in result.command_results:
+        tag = "ok" if exit_code == 0 else f"exit={exit_code}"
+        print(f"  {' '.join(cmd)}  [{tag}]")
+    # Non-zero exit for any service command is non-fatal - the unit file
+    # was still written, so re-running `alter-runtime start` or enabling
+    # the unit manually will pick up where we left off.
+    return 0
+
+
+def cmd_stop(_args: argparse.Namespace) -> int:
+    """Disable + stop the host service unit."""
+    from alter_runtime.consent import _sha256_file, write_tombstone
+    from alter_runtime.service_install import (
+        launchd_plist_install_path,
+        systemd_unit_install_path,
+    )
+
+    platform = current_platform()
+    if platform not in ("linux", "darwin"):
+        print(
+            f"alter-runtime stop is not yet supported on platform={platform!r}.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # C3 - tombstone the unit file before uninstalling so that a subsequent
+    # `alter-runtime start` does not silently recreate it.
+    if platform == "linux":
+        unit_path = systemd_unit_install_path()
+    else:
+        unit_path = launchd_plist_install_path()
+
+    if unit_path.exists():
+        sha = _sha256_file(unit_path)
+        try:
+            write_tombstone(unit_path, sha256_at_deletion=sha, source="user_explicit")
+        except OSError as exc:
+            print(f"  warning: could not write tombstone: {exc}", file=sys.stderr)
+
+    try:
+        results = uninstall_service()
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    for cmd, exit_code in results:
+        tag = "ok" if exit_code == 0 else f"exit={exit_code}"
+        print(f"  {' '.join(cmd)}  [{tag}]")
+    print("service unit removed")
+    return 0
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    """Report daemon state - does the socket exist? Is the session valid?"""
+    lines: list[str] = []
+
+    socket = unix_socket_path()
+    lines.append(f"unix socket:     {socket}")
+    if socket.exists():
+        lines.append("  state:         present")
+    else:
+        lines.append("  state:         absent (daemon not running or socket path mismatched)")
+
+    kp = keypair_path()
+    lines.append(f"keypair:         {kp}")
+    lines.append(f"  state:         {'present' if kp.exists() else 'absent'}")
+
+    session = load_session()
+    if session is None:
+        lines.append("session:         none (run `alter login`)")
+    else:
+        lines.append(f"session:         handle={session.handle} tier=L{session.consent_tier}")
+        lines.append(f"  api:           {session.api}")
+        lines.append(f"  expires:       {session.jwt_expires_at}")
+
+    config = load_config()
+    lines.append(f"config:          {config_dir() / 'runtime.yaml'}")
+    lines.append(f"  do_sse:        {config.do_sse_endpoint}")
+    lines.append(f"  mcp_fallback:  {config.mcp_fallback_endpoint}")
+    lines.append(f"  log_level:     {config.log_level}")
+
+    svc = service_status()
+    lines.append(f"service unit:    {svc.unit_path}")
+    lines.append(f"  platform:      {svc.platform}")
+    lines.append(f"  installed:     {svc.installed}")
+    lines.append(f"  active:        {svc.active} ({svc.status_line})")
+
+    print("\n".join(lines))
+    return 0
+
+
+def cmd_daemon(_args: argparse.Namespace) -> int:
+    """Run the supervisor in the foreground."""
+    try:
+        asyncio.run(run_daemon())
+    except KeyboardInterrupt:
+        logger.info("interrupted")
+        return 130
+    return 0
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    """Query the local cache / daemon socket for current field state.
+
+    Wave 1 skeleton: reads only the local cache file that `scripts/alter-identity.sh`
+    already maintains at ~/.cache/alter/identity.json. Wave 2 stream 2b wires a
+    live socket query.
+    """
+    cache_file = cache_dir() / "identity.json"
+    if not cache_file.exists():
+        print("no cached identity state - run `alter-runtime daemon` or `alter-identity.sh`")
+        return 1
+
+    try:
+        data = json.loads(cache_file.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"failed to read cache: {exc}", file=sys.stderr)
+        return 1
+
+    field = args.field
+    if field == "all":
+        print(json.dumps(data, indent=2))
+        return 0
+
+    alias = {
+        "handle": "handle",
+        "attunement": "attunement",
+        "warmth": "level",
+        "income": "income",
+        "trust_tier": "trust_tier",
+    }
+    key = alias.get(field, field)
+    value = data.get(key)
+    if value is None:
+        print(f"field '{field}' not present in local cache")
+        return 1
+    print(value)
+    return 0
+
+
+def cmd_ingest(args: argparse.Namespace) -> int:
+    """Manually ingest a signal.
+
+    Wave 1 skeleton: validates the payload shape and prints what would be
+    sent. Wave 2 stream 2b wires the actual socket send + DO ingest path.
+    """
+    try:
+        payload = json.loads(args.payload)
+    except json.JSONDecodeError as exc:
+        print(f"invalid --payload JSON: {exc}", file=sys.stderr)
+        return 1
+
+    session = load_session()
+    if session is None:
+        print("no session - run `alter login`", file=sys.stderr)
+        return 1
+
+    envelope = {
+        "v": "alter1",
+        "handle": session.handle,
+        "kind": args.kind,
+        "payload": payload,
+        "producer": args.producer,
+        "consent_tier": session.consent_tier,
+    }
+
+    print("Would ingest:")
+    print(json.dumps(envelope, indent=2))
+    print("\n(Wave 2 wires the actual send path via unix socket → daemon → DO.)")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Main dispatcher
+# ---------------------------------------------------------------------------
+
+
+COMMANDS: dict[str, object] = {
+    "init": cmd_init,
+    "start": cmd_start,
+    "stop": cmd_stop,
+    "status": cmd_status,
+    "daemon": cmd_daemon,
+    "query": cmd_query,
+    "ingest": cmd_ingest,
+}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=args.log_level.upper(),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S%z",
+    )
+
+    handler = COMMANDS.get(args.command)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return 2
+    return handler(args)  # type: ignore[operator]
+
+
+# ---------------------------------------------------------------------------
+# Keypair generation (stub - Wave 1 writes a placeholder; Wave 2 wires real
+# Ed25519 generation via `cryptography` package)
+# ---------------------------------------------------------------------------
+
+
+def _generate_keypair(path: Path) -> None:
+    """Generate a placeholder keypair file.
+
+    Wave 1 skeleton: writes a JSON scaffold without actually generating an
+    Ed25519 key. Wave 2 stream 2c will use `cryptography` to generate a
+    real keypair and bind it to the sovereign passkey root (per
+    Invisible Infrastructure P2).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    placeholder = {
+        "version": 1,
+        "algorithm": "ed25519",
+        "generated_at": None,
+        "public_key_b64": None,
+        "private_key_b64": None,
+        "_notice": (
+            "Wave 1 scaffold - real keypair generation lands in Wave 2 stream 2c "
+            "with the cryptography package and sovereign passkey binding."
+        ),
+    }
+    path.write_text(json.dumps(placeholder, indent=2))
+    try:
+        path.chmod(0o600)
+    except (OSError, NotImplementedError):
+        pass
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())