code-data-ark 2.0.3__tar.gz → 2.0.4__tar.gz

{code_data_ark-2.0.3 → code_data_ark-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-data-ark
-Version: 2.0.3
+Version: 2.0.4
 Summary: Code Data Ark — local observability and intelligence platform for VS Code + Copilot Chat sessions
 Project-URL: Homepage, https://github.com/goCosmix/cda
 Project-URL: Repository, https://github.com/goCosmix/cda.git

{code_data_ark-2.0.3 → code_data_ark-2.0.4}/cda/kernel/pmf_kernel.py

@@ -1,9 +1,13 @@
 import json
 import os
+import shutil
 import signal
+import socket
 import subprocess
 import sys
+import threading
 import time
+import webbrowser
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional
@@ -17,6 +21,132 @@ from cda.kernel.paths import (
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 10001
 
+# ── launchd integration ──────────────────────────────────────────────────────
+
+PLIST_LABEL = "com.gocosmix.cda"
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{PLIST_LABEL}.plist"
+
+
+def generate_plist(cda_bin: str, cda_home: Path) -> str:
+    log = cda_home / "logs" / "launchd.log"
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{cda_bin}</string>
+        <string>pmf</string>
+        <string>up</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <false/>
+    <key>StandardOutPath</key>
+    <string>{log}</string>
+    <key>StandardErrorPath</key>
+    <string>{log}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>CDA_HOME</key>
+        <string>{cda_home}</string>
+        <key>PATH</key>
+        <string>{os.path.dirname(cda_bin)}:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>
+"""
+
+
+def install_launchd(cda_home: Path) -> Path:
+    """Write the LaunchAgent plist and load it with launchctl."""
+    cda_bin = shutil.which("cda")
+    if not cda_bin:
+        raise PMFKernelError("cda binary not found on PATH — cannot generate plist")
+
+    target = plist_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(generate_plist(cda_bin, cda_home))
+
+    # Unload any stale registration first
+    subprocess.run(["launchctl", "unload", str(target)], capture_output=True)
+
+    result = subprocess.run(
+        ["launchctl", "load", str(target)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise PMFKernelError(f"launchctl load failed: {result.stderr.strip()}")
+
+    return target
+
+
+def uninstall_launchd() -> None:
+    """Unload and remove the LaunchAgent plist."""
+    target = plist_path()
+    if target.exists():
+        subprocess.run(["launchctl", "unload", str(target)], capture_output=True)
+        target.unlink(missing_ok=True)
+
+
+def open_browser_when_ready(
+    url: str,
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    timeout: float = 12.0,
+) -> threading.Thread:
+    """
+    Spawn a daemon thread that polls host:port and opens a browser when ready.
+    For foreground (serve) use: the thread outlives the caller because serve blocks.
+    For background (pmf up / ui start): call wait_for_port() instead so we poll
+    synchronously before the process exits.
+    """
+    def _wait_and_open():
+        elapsed = 0.0
+        while elapsed < timeout:
+            try:
+                with socket.create_connection((host, port), timeout=0.5):
+                    webbrowser.open(url)
+                    return
+            except OSError:
+                time.sleep(0.25)
+                elapsed += 0.25
+
+    t = threading.Thread(target=_wait_and_open, daemon=True)
+    t.start()
+    return t
+
+
+def wait_for_port_and_open_browser(
+    url: str,
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    timeout: float = 8.0,
+) -> bool:
+    """
+    Block until host:port accepts connections (or timeout), then open browser.
+    Use this when the caller process will exit after starting a background service.
+    Returns True if port came up, False on timeout.
+    """
+    elapsed = 0.0
+    while elapsed < timeout:
+        try:
+            with socket.create_connection((host, port), timeout=0.5):
+                webbrowser.open(url)
+                return True
+        except OSError:
+            time.sleep(0.25)
+            elapsed += 0.25
+    return False
+
+
 ensure_dirs()
 
 

{code_data_ark-2.0.3 → code_data_ark-2.0.4}/cda/ui/cli.py

@@ -24,6 +24,9 @@ Commands:
   cda pmf stop <service>     Stop a service
   cda pmf restart <service>  Restart a service
   cda pmf logs <service>     Tail service logs
+  cda pmf up                 Start watcher + web UI (opens browser when ready)
+  cda pmf install            Register as macOS LaunchAgent (auto-start on login)
+  cda pmf uninstall          Remove the LaunchAgent registration
   cda check                  Run a full self-diagnostic. The system checks itself.
   cda init                   First-run setup — create ~/.cda/ and validate environment
   cda serve                  Start the local web UI on port 10001
@@ -62,7 +65,11 @@ import textwrap
 import datetime
 from pathlib import Path
 from cda.pipeline.reconstruct import decompress_vfs
-from cda.kernel.pmf_kernel import PMFKernel, PMFKernelError
+from cda.kernel.pmf_kernel import (
+    PMFKernel, PMFKernelError,
+    install_launchd, uninstall_launchd, plist_path,
+    open_browser_when_ready, wait_for_port_and_open_browser,
+)
 from cda.kernel.paths import (
     DB_PATH, PID_FILE, UI_PID_FILE, UI_LOG_FILE,
     QUEUE_DIR, POLICY_FILE, ensure_dirs,
@@ -361,10 +368,11 @@ def status():
 @cli.command("serve")
 @click.option("--host", default="127.0.0.1", show_default=True, help="Local host to bind the web UI")
 @click.option("--port", default=10001, show_default=True, help="Local port for the web UI")
-def serve(host, port):
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser automatically")
+def serve(host, port, no_browser):
     """Start the local web UI for Code Data Ark in the foreground."""
-    click.echo(yellow(f"  Starting local web UI at http://{host}:{port}"))
-    click.echo(yellow("  Use `cda ui start` to launch it as a background service."))
+    url = f"http://{host}:{port}"
+    click.echo(yellow(f"  Starting local web UI at {url}"))
     try:
         import importlib
         import cda.ui.web as web
@@ -373,6 +381,8 @@ def serve(host, port):
         click.echo(red("  Failed to start web UI. Ensure the package is installed and importable."))
         click.echo(red(f"  Details: {exc}"))
         return
+    if not no_browser:
+        open_browser_when_ready(url, host, port)
     web.start_server(host=host, port=port)
 
 
@@ -396,12 +406,17 @@ def _ui_is_running():
 @ui.command("start")
 @click.option("--host", default="127.0.0.1", show_default=True, help="Local host to bind the web UI")
 @click.option("--port", default=10001, show_default=True, help="Local port for the web UI")
-def ui_start(host, port):
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser automatically")
+def ui_start(host, port, no_browser):
     """Start the web UI as a background service."""
     try:
         result = kernel.start_service("ui", options={"host": host, "port": port})
-        click.echo(green(f"  Web UI started in background at http://{host}:{port} pid={result['pid']}"))
+        url = f"http://{host}:{port}"
+        click.echo(green(f"  Web UI started in background at {url} pid={result['pid']}"))
         click.echo(yellow(f"  Logs: {UI_LOG_FILE}"))
+        if not no_browser:
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
     except PMFKernelError as exc:
         click.echo(red(f"  Failed to start UI: {exc}"))
 
@@ -485,12 +500,17 @@ def pmf_status(service_id):
 @click.argument("service_id")
 @click.option("--host", default="127.0.0.1", help="Host override for UI service")
 @click.option("--port", default=10001, help="Port override for UI service")
-def pmf_start(service_id, host, port):
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser (UI service only)")
+def pmf_start(service_id, host, port, no_browser):
     """Start a PMF-managed Ark service."""
     options = {"host": host, "port": port} if service_id == "ui" else None
     try:
         result = kernel.start_service(service_id, options=options)
         click.echo(green(f"  Started {result['label']} pid={result['pid']}"))
+        if service_id == "ui" and not no_browser:
+            url = f"http://{host}:{port}"
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
     except PMFKernelError as exc:
         click.echo(red(f"  {exc}"))
 
@@ -529,6 +549,69 @@ def pmf_logs(service_id, tail):
         click.echo(red(f"  {exc}"))
 
 
+@pmf.command("up")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Host for web UI")
+@click.option("--port", default=10001, show_default=True, help="Port for web UI")
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser when UI is ready")
+def pmf_up(host, port, no_browser):
+    """Start all CDA services (watcher + web UI). Called automatically by launchd on login."""
+    url = f"http://{host}:{port}"
+
+    click.echo(bold("  Code Data Ark — starting services"))
+    click.echo(hr())
+
+    try:
+        result = kernel.start_service("watcher")
+        click.echo(green(f"  Watcher      started  pid={result['pid']}"))
+    except PMFKernelError as exc:
+        click.echo(yellow(f"  Watcher      {exc}"))
+
+    try:
+        result = kernel.start_service("ui", options={"host": host, "port": port})
+        click.echo(green(f"  Web UI       started  pid={result['pid']}  →  {url}"))
+        if not no_browser:
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
+    except PMFKernelError as exc:
+        click.echo(yellow(f"  Web UI       {exc}"))
+
+    click.echo()
+
+
+@pmf.command("install")
+def pmf_install():
+    """Install CDA as a macOS launchd LaunchAgent (auto-start on login)."""
+    from cda.kernel.paths import CDA_HOME as _cda_home
+    click.echo()
+    click.echo(bold("  Installing CDA LaunchAgent"))
+    click.echo(hr())
+    try:
+        target = install_launchd(_cda_home)
+        click.echo(green(f"  Plist:   {target}"))
+        click.echo(green("  Label:   com.gocosmix.cda"))
+        click.echo(green("  Loaded:  yes — CDA will start automatically on next login"))
+        click.echo()
+        click.echo(dim("  To start services now without logging out:"))
+        click.echo(dim("    cda pmf up"))
+        click.echo()
+    except PMFKernelError as exc:
+        click.echo(red(f"  {exc}"))
+        click.echo(yellow("  Make sure `cda` is on PATH: export PATH=\"$HOME/Library/Python/3.9/bin:$PATH\""))
+        click.echo()
+
+
+@pmf.command("uninstall")
+def pmf_uninstall():
+    """Remove the CDA launchd LaunchAgent."""
+    target = plist_path()
+    if not target.exists():
+        click.echo(yellow("  No LaunchAgent plist found — nothing to uninstall."))
+        return
+    uninstall_launchd()
+    click.echo(green(f"  Removed: {target}"))
+    click.echo(green("  CDA will no longer start automatically on login."))
+
+
 @cli.group()
 def embed():
     """Build and inspect semantic intelligence."""
@@ -2606,9 +2689,10 @@ def init():
     click.echo(bold("  CDA_HOME: ") + str(CDA_HOME))
     click.echo()
     click.echo(dim("  Next steps:"))
+    click.echo(dim("    cda pmf install  — register as a macOS LaunchAgent (auto-start on login)"))
     click.echo(dim("    cda sync         — ingest all VS Code session data"))
-    click.echo(dim("    cda watch start  — start the live watcher daemon"))
-    click.echo(dim("    cda serve        — open the web dashboard on :10001"))
+    click.echo(dim("    cda pmf up       — start watcher + web UI now (opens browser)"))
+    click.echo(dim("    cda serve        — run web UI in foreground (opens browser)"))
     click.echo()
 
 

{code_data_ark-2.0.3 → code_data_ark-2.0.4}/changelog.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.4] - 2026-05-11
+
+### Added
+- **`cda pmf install`** — generates and loads a macOS `~/Library/LaunchAgents/com.gocosmix.cda.plist`; CDA starts automatically on login
+- **`cda pmf uninstall`** — unloads and removes the LaunchAgent plist
+- **`cda pmf up`** — starts watcher + web UI in one command; opens browser when the server is ready; called by launchd on login
+- **Browser auto-open**: `cda serve`, `cda ui start`, and `cda pmf start ui` now open a browser tab when the server is ready (`--no-browser` to disable)
+- `cda.kernel.pmf_kernel`: `install_launchd()`, `uninstall_launchd()`, `generate_plist()`, `plist_path()`, `open_browser_when_ready()`, `wait_for_port_and_open_browser()`
+
 ## [2.0.3] - 2026-05-11
 
 ### Fixed

{code_data_ark-2.0.3 → code_data_ark-2.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-data-ark"
-version = "2.0.3"
+version = "2.0.4"
 description = "Code Data Ark — local observability and intelligence platform for VS Code + Copilot Chat sessions"
 readme = "readme.md"
 license = "MIT"

code_data_ark-2.0.4/version

@@ -0,0 +1 @@
+2.0.4

code_data_ark-2.0.3/version

@@ -1 +0,0 @@
-2.0.3