aether-mkt 0.1.0__py3-none-any.whl

aether/__init__.py

@@ -0,0 +1,12 @@
+"""aether · 内容分发 v0.1.
+
+PyPI package: ``aether-mkt``   (the hyphenated form is reserved on PyPI)
+CLI command:  ``aether``       (cleaner to type)
+
+Internal modules live under the ``aether`` Python package (Python
+identifiers can't have hyphens), so ``import aether.cli`` works after
+``pip install aether-mkt``.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

aether/cli.py

@@ -0,0 +1,525 @@
+"""aether CLI · 驱动 macOS / Linux 上的 aether 服务生命周期。
+
+发布版本（v0.1）走**本机 PostgreSQL + launchd**，不依赖 Docker：
+
+  - Postgres 通过 brew services / systemctl / 系统服务管理器运行
+  - aether web 服务通过 launchd plist 在 macOS 后台跑（开机自起、崩溃重启）
+  - 首次 `aether init` 自动跑 schema.sql 建表
+
+设计上：
+  - idempotent + fail-fast（任何步骤失败立即退出，不留半成品）
+  - 数据 / 配置持久化到 XDG-style 目录（macOS: ~/Library/Application Support/aether）
+  - 7 个子命令：init / serve / stop / update / status / logs / uninstall
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+# Note: pyproject.toml [project.scripts] exposes ``aether = "aether.cli:main"``
+# so this file is the entry point installed by `pip install aether-mkt`.
+
+APP_NAME = "aether"
+VERSION = "0.1.0"
+LAUNCHD_LABEL = "com.aether.web"
+LAUNCHD_PLIST_NAME = f"{LAUNCHD_LABEL}.plist"
+
+# Default DATABASE_URL points at a local Postgres reachable via unix socket
+# (peer auth on macOS — no password needed when the macOS user owns the DB).
+DEFAULT_DATABASE_URL = "postgresql:///aether"
+DEFAULT_LLM_BASE_URL = "https://api.anthropic.com"
+DEFAULT_LLM_MODEL = "claude-sonnet-4-6"
+
+ENV_TEMPLATE = """\
+# aether v0.1 · env config (also editable at runtime via /settings UI)
+
+# DB — local Postgres (peer auth on macOS when DB owner = macOS user).
+DATABASE_URL={default_db}
+
+# LLM three-piece (overridable at runtime via /settings).
+LLM_BASE_URL={default_llm_base}
+LLM_MODEL={default_llm_model}
+LLM_API_KEY=sk-ant-REPLACE_ME
+
+# Fetcher
+USER_AGENT=AetherBot/0.1
+REQUEST_TIMEOUT=30
+DEFAULT_TOP_N=3
+"""
+
+# Keys from .env that get injected into the launchd plist's EnvironmentVariables.
+INJECTED_ENV_KEYS = (
+    "DATABASE_URL",
+    "LLM_BASE_URL",
+    "LLM_MODEL",
+    "LLM_API_KEY",
+    "USER_AGENT",
+    "REQUEST_TIMEOUT",
+    "DEFAULT_TOP_N",
+)
+
+
+# --------------------------------------------------------------------------- #
+# Paths
+# --------------------------------------------------------------------------- #
+
+def data_dir() -> Path:
+    """XDG-style per-user data directory.
+
+    - macOS:   ~/Library/Application Support/aether
+    - Linux:   $XDG_DATA_HOME/aether  or  ~/.local/share/aether
+    - Windows: %APPDATA%\\aether  (dev only)
+    """
+    system = platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / APP_NAME
+    if system == "Linux":
+        xdg = os.environ.get("XDG_DATA_HOME")
+        return Path(xdg) / APP_NAME if xdg else Path.home() / ".local" / "share" / APP_NAME
+    appdata = os.environ.get("APPDATA")
+    return Path(appdata) / APP_NAME if appdata else Path.home() / f".{APP_NAME}"
+
+
+def runtime_dir() -> Path:
+    """log / launchd staging directory."""
+    return data_dir() / "runtime"
+
+
+def launchd_agents_dir() -> Path:
+    """~/Library/LaunchAgents (macOS only)."""
+    return Path.home() / "Library" / "LaunchAgents"
+
+
+def launchd_plist_path() -> Path:
+    return launchd_agents_dir() / LAUNCHD_PLIST_NAME
+
+
+def deploy_dir() -> Path:
+    """Bundled deploy assets shipped inside the wheel."""
+    return Path(__file__).parent / "deploy"
+
+
+def env_file_path() -> Path:
+    return data_dir() / ".env"
+
+
+# --------------------------------------------------------------------------- #
+# Subprocess helpers
+# --------------------------------------------------------------------------- #
+
+def _run(cmd: Sequence[str], **kw) -> subprocess.CompletedProcess:
+    """subprocess.run with check=True; bubble stderr on failure."""
+    try:
+        return subprocess.run(cmd, check=True, **kw)
+    except subprocess.CalledProcessError as e:
+        sys.stderr.write(f"command failed (rc={e.returncode}): {' '.join(e.cmd)}\n")
+        if e.stderr:
+            sys.stderr.write(e.stderr.decode("utf-8", errors="replace") + "\n")
+        raise
+
+
+def _open_in_editor(path: Path) -> None:
+    editor = os.environ.get("EDITOR")
+    if editor:
+        subprocess.run([editor, str(path)])
+        return
+    system = platform.system()
+    if system == "Darwin":
+        subprocess.run(["open", str(path)])
+    elif system == "Linux" and shutil.which("xdg-open"):
+        subprocess.run(["xdg-open", str(path)])
+    # Windows / no editor: no-op; user edits via /settings later.
+
+
+# --------------------------------------------------------------------------- #
+# Postgres connectivity + schema bootstrap
+# --------------------------------------------------------------------------- #
+
+def _check_postgres() -> None:
+    """fail-fast if Postgres unreachable."""
+    try:
+        from src.db import get_conn
+        with get_conn(connect_timeout=3) as conn, conn.cursor() as cur:
+            cur.execute("SELECT 1")
+            cur.fetchone()
+    except Exception as e:
+        sys.stderr.write(
+            f"ERROR: cannot connect to Postgres ({e.__class__.__name__}).\n"
+            "\n"
+            "macOS quick fix:\n"
+            "  brew install postgresql@16\n"
+            "  brew services start postgresql@16\n"
+            f"  createdb {APP_NAME}\n"
+            "  aether init    # retry\n"
+            "\n"
+            "Linux quick fix:\n"
+            "  sudo apt install postgresql\n"
+            "  sudo systemctl start postgresql\n"
+            f"  sudo -u postgres createdb {APP_NAME}\n"
+            "  aether init    # retry\n"
+        )
+        sys.exit(1)
+
+
+def _schema_exists() -> bool:
+    """True if the `sources` table is present (proxy for 'bootstrap done')."""
+    try:
+        from src.db import get_conn
+        with get_conn(connect_timeout=3) as conn, conn.cursor() as cur:
+            cur.execute(
+                "SELECT 1 FROM information_schema.tables "
+                "WHERE table_schema = 'public' AND table_name = 'sources'"
+            )
+            return cur.fetchone() is not None
+    except Exception:
+        return False
+
+
+def _bootstrap_schema() -> None:
+    """Run db/schema.sql. Idempotent: uses CREATE TABLE IF NOT EXISTS etc."""
+    schema_path = deploy_dir() / "db" / "schema.sql"
+    if not schema_path.exists():
+        sys.stderr.write(f"ERROR: schema.sql missing in wheel: {schema_path}\n")
+        sys.exit(1)
+    sql = schema_path.read_text(encoding="utf-8")
+    print("[init] applying schema.sql (first boot)...")
+    try:
+        from src.db import get_conn
+        with get_conn(connect_timeout=10) as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql)
+            conn.commit()
+    except Exception as e:
+        sys.stderr.write(f"ERROR: schema bootstrap failed: {e}\n")
+        sys.exit(1)
+    print("[init] schema applied.")
+
+
+# --------------------------------------------------------------------------- #
+# launchd plist rendering
+# --------------------------------------------------------------------------- #
+
+def _read_env_file(path: Path) -> dict[str, str]:
+    """Minimal .env parser: KEY=VALUE lines, # comments, no expansion."""
+    out: dict[str, str] = {}
+    if not path.exists():
+        return out
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def _render_plist() -> str:
+    """Substitute placeholders in com.aether.web.plist template."""
+    template = (deploy_dir() / LAUNCHD_PLIST_NAME).read_text(encoding="utf-8")
+    python_exe = sys.executable
+    work_dir = str(data_dir())
+    log_dir = str(runtime_dir())
+    # PATH must include the venv site-packages bin so uvicorn resolves;
+    # otherwise launchd inherits a stripped PATH.
+    path_env = os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin")
+
+    # Inject user-provided env (DATABASE_URL / LLM_* / etc.) into plist dict.
+    user_env = _read_env_file(env_file_path())
+    injected_xml_lines = []
+    for key in INJECTED_ENV_KEYS:
+        if key in user_env and user_env[key]:
+            from xml.sax.saxutils import escape
+            injected_xml_lines.append(
+                f"        <key>{escape(key)}</key>\n"
+                f"        <string>{escape(user_env[key])}</string>"
+            )
+    injected = "\n".join(injected_xml_lines) if injected_xml_lines else ""
+
+    rendered = (
+        template
+        .replace("__PYTHON__", python_exe)
+        .replace("__WORKDIR__", work_dir)
+        .replace("__PATH__", path_env)
+        .replace("__LOG_DIR__", log_dir)
+        .replace("__INJECTED_ENV__", injected)
+    )
+    return rendered
+
+
+def _install_launchd_plist() -> Path:
+    """Render + write plist to ~/Library/LaunchAgents/. Idempotent."""
+    if platform.system() != "Darwin":
+        sys.stderr.write(
+            "ERROR: launchd integration is macOS-only.\n"
+            "On Linux, manage the web process manually (systemd / nohup).\n"
+        )
+        sys.exit(1)
+    launchd_agents_dir().mkdir(parents=True, exist_ok=True)
+    target = launchd_plist_path()
+    target.write_text(_render_plist(), encoding="utf-8")
+    return target
+
+
+def _launchctl(*args: str) -> None:
+    """Run launchctl and let exceptions bubble."""
+    _run(["launchctl"] + list(args))
+
+
+def _launchd_uid_target() -> str:
+    """gui/<uid>/<label> — the per-user launchd domain.
+
+    On macOS uses os.getuid(); on Windows / dev we use a stable placeholder
+    so tests work. cmd_serve / cmd_stop gate on macOS upstream, so this
+    fallback only matters for unit-test execution paths.
+    """
+    uid = os.getuid() if hasattr(os, "getuid") else 1000
+    return f"gui/{uid}/{LAUNCHD_LABEL}"
+
+
+# --------------------------------------------------------------------------- #
+# Sub-commands
+# --------------------------------------------------------------------------- #
+
+def cmd_init(args: argparse.Namespace) -> None:
+    """First-time setup: ensure Postgres reachable, write .env, bootstrap schema."""
+    print(f"[init] aether {VERSION}")
+    print(f"[init] data dir: {data_dir()}")
+    data_dir().mkdir(parents=True, exist_ok=True)
+    runtime_dir().mkdir(parents=True, exist_ok=True)
+
+    _check_postgres()
+    print("[init] postgres OK")
+
+    env_file = env_file_path()
+    if env_file.exists() and not args.force:
+        print(f"[init] .env already exists at {env_file} (use --force to overwrite)")
+    else:
+        env_file.write_text(
+            ENV_TEMPLATE.format(
+                default_db=DEFAULT_DATABASE_URL,
+                default_llm_base=DEFAULT_LLM_BASE_URL,
+                default_llm_model=DEFAULT_LLM_MODEL,
+            ),
+            encoding="utf-8",
+        )
+        print(f"[init] wrote {env_file}")
+
+    # Schema bootstrap — idempotent.
+    if _schema_exists():
+        print("[init] schema already present, skipping bootstrap")
+    else:
+        _bootstrap_schema()
+
+    print()
+    print("=" * 60)
+    print("NEXT: edit .env and fill LLM_API_KEY (required), then run:")
+    print("  aether serve")
+    print("=" * 60)
+    if not args.no_prompt:
+        try:
+            input("Press Enter to open .env in your default editor (Ctrl-D to skip)...")
+        except EOFError:
+            print()
+        _open_in_editor(env_file)
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    """Install launchd plist + launchctl load (background, auto-restart)."""
+    _check_postgres()
+    if not env_file_path().exists():
+        sys.stderr.write(f"ERROR: {env_file_path()} not found. Run `aether init` first.\n")
+        sys.exit(1)
+    if not _schema_exists():
+        sys.stderr.write("ERROR: schema not bootstrapped. Run `aether init` first.\n")
+        sys.exit(1)
+
+    plist = _install_launchd_plist()
+    print(f"[serve] wrote {plist}")
+
+    uid_target = _launchd_uid_target()
+    # If already loaded, bootout first so a fresh load picks up new plist content.
+    list_result = subprocess.run(
+        ["launchctl", "list", LAUNCHD_LABEL],
+        capture_output=True, text=True,
+    )
+    if list_result.returncode == 0:
+        print(f"[serve] unloading previous instance...")
+        with contextlib.suppress(subprocess.CalledProcessError):
+            _launchctl("bootout", uid_target)
+
+    print(f"[serve] launchctl load -w {plist.name} ...")
+    _launchctl("load", "-w", str(plist))
+    print(f"[serve] launchctl kickstart -k {uid_target} ...")
+    _launchctl("kickstart", "-k", uid_target)
+    print()
+    print("[serve] aether is running.")
+    print("        web:   http://localhost:8000/articles")
+    print("        logs:  aether logs")
+    print("        stop:  aether stop")
+
+
+def cmd_stop(args: argparse.Namespace) -> None:
+    """launchctl bootout (graceful stop; plist kept on disk)."""
+    uid_target = _launchd_uid_target()
+    try:
+        _launchctl("bootout", uid_target)
+        print("[stop] aether stopped")
+    except subprocess.CalledProcessError:
+        print("[stop] aether was not running")
+
+
+def cmd_update(args: argparse.Namespace) -> None:
+    """pip install --upgrade + restart."""
+    print("[update] pip install --upgrade aether-mkt ...")
+    _run([sys.executable, "-m", "pip", "install", "--upgrade", "aether-mkt"])
+    cmd_stop(argparse.Namespace())
+    cmd_serve(argparse.Namespace())
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    """Show launchd status + DB connectivity + data dir."""
+    print(f"aether {VERSION}")
+    print(f"data dir: {data_dir()}")
+    print()
+    # launchd status
+    try:
+        _run(["launchctl", "print", _launchd_uid_target()])
+    except subprocess.CalledProcessError:
+        print("not running. run `aether serve`.")
+    # DB ping
+    print()
+    try:
+        from src.db import get_conn
+        with get_conn(connect_timeout=3) as conn, conn.cursor() as cur:
+            cur.execute("SELECT version()")
+            v = cur.fetchone()[0]
+        print(f"postgres: OK ({v[:60]})")
+    except Exception as e:
+        print(f"postgres: DOWN ({e.__class__.__name__}: {e})")
+
+
+def cmd_logs(args: argparse.Namespace) -> None:
+    """tail the web log (out + err interleaved)."""
+    log_dir = runtime_dir()
+    if not log_dir.exists():
+        print("no log dir. run `aether serve` first.")
+        return
+    out_log = log_dir / "web.out.log"
+    err_log = log_dir / "web.err.log"
+    files = [str(p) for p in (out_log, err_log) if p.exists()]
+    if not files:
+        print(f"no log files in {log_dir}. run `aether serve` first.")
+        return
+    try:
+        _run(["tail", "-f"] + files)
+    except KeyboardInterrupt:
+        print()
+
+
+def cmd_uninstall(args: argparse.Namespace) -> None:
+    """Stop service + remove launchd plist + (optional) remove data dir."""
+    print("[uninstall] this will:")
+    print("  - stop aether (launchctl bootout)")
+    print("  - remove ~/Library/LaunchAgents/com.aether.web.plist")
+    if args.keep_data:
+        print("  - KEEP data dir (--keep-data)")
+    else:
+        print("  - remove data dir")
+    if not args.yes:
+        try:
+            confirm = input("continue? [y/N] ")
+        except EOFError:
+            confirm = "n"
+        if confirm.lower() != "y":
+            print("cancelled")
+            return
+    # Stop + remove plist
+    with contextlib.suppress(subprocess.CalledProcessError):
+        _launchctl("bootout", _launchd_uid_target())
+    plist = launchd_plist_path()
+    if plist.exists():
+        plist.unlink()
+        print(f"[uninstall] removed {plist}")
+    if not args.keep_data and data_dir().exists():
+        shutil.rmtree(data_dir())
+        print(f"[uninstall] removed {data_dir()}")
+    print("[uninstall] done.")
+    print("  to remove the package itself: pip uninstall aether-mkt")
+
+
+# --------------------------------------------------------------------------- #
+# Entry point
+# --------------------------------------------------------------------------- #
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="aether",
+        description="aether 内容分发 v0.1 · CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+examples:
+  aether init        first-time setup (check postgres, write .env, bootstrap schema)
+  aether serve       start web (background, auto-restart via launchd)
+  aether status      show launchd status + DB connectivity
+  aether logs        tail web logs (Ctrl-C to exit)
+  aether stop        stop web
+  aether update      upgrade package + restart
+  aether uninstall   remove plist + (optionally) data dir
+""",
+    )
+    parser.add_argument("--version", action="version", version=f"aether {VERSION}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="first-time setup")
+    p.add_argument("--force", action="store_true", help="overwrite existing .env")
+    p.add_argument("--no-prompt", action="store_true", help="don't open editor")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("serve", help="start web (background via launchd)")
+    p.set_defaults(func=cmd_serve)
+
+    p = sub.add_parser("stop", help="stop web (launchctl bootout)")
+    p.set_defaults(func=cmd_stop)
+
+    p = sub.add_parser("update", help="upgrade package + restart")
+    p.set_defaults(func=cmd_update)
+
+    p = sub.add_parser("status", help="show launchd status + DB ping")
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("logs", help="tail web logs (Ctrl-C to exit)")
+    p.set_defaults(func=cmd_logs)
+
+    p = sub.add_parser("uninstall", help="stop + remove plist + (optionally) data dir")
+    p.add_argument("--keep-data", action="store_true", help="preserve data dir")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation")
+    p.set_defaults(func=cmd_uninstall)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print("\ninterrupted", file=sys.stderr)
+        return 130
+    except subprocess.CalledProcessError as e:
+        return e.returncode or 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aether/deploy/com.aether.web.plist

@@ -0,0 +1,81 @@
+<?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>
+    <!-- ===== Identity ===== -->
+    <key>Label</key>
+    <string>com.aether.web</string>
+    <key>ProcessType</key>
+    <string>Background</string>
+
+    <!-- ===== What to run =====
+         Placeholders are substituted by aether serve at install time:
+           __PYTHON__    absolute path to the Python interpreter
+                         running the CLI (sys.executable)
+           __WORKDIR__   aether data dir (XDG-style)
+         The CLI passes --app-dir so web.app can read settings.json
+         from the right location regardless of cwd. -->
+    <key>ProgramArguments</key>
+    <array>
+        <string>__PYTHON__</string>
+        <string>-m</string>
+        <string>uvicorn</string>
+        <string>web.app:app</string>
+        <string>--host</string>
+        <string>127.0.0.1</string>
+        <string>--port</string>
+        <string>8000</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>__WORKDIR__</string>
+
+    <!-- ===== Environment =====
+         Database URL + LLM keys + runtime config, all sourced from the
+         user's ~/Library/Application Support/aether/.env at install time.
+         PATH includes the venv site-packages bin so uvicorn is found. -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>__PATH__</string>
+        <key>AETHER_DATA_DIR</key>
+        <string>__WORKDIR__</string>
+        <!-- The actual DATABASE_URL / LLM_* / USER_AGENT / REQUEST_TIMEOUT /
+             DEFAULT_TOP_N entries are injected by `aether serve` from .env. -->
+        __INJECTED_ENV__
+    </dict>
+
+    <!-- ===== Lifecycle ===== -->
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <!-- Restart on crash, but not on clean exit (so `aether stop` works). -->
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <!-- ===== Logs =====
+         Captured to runtime/ so `aether logs` can tail them. -->
+    <key>StandardOutPath</key>
+    <string>__LOG_DIR__/web.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>__LOG_DIR__/web.err.log</string>
+
+    <!-- ===== Resource limits ===== -->
+    <key>SoftResourceLimits</key>
+    <dict>
+        <key>NumberOfFiles</key>
+        <integer>65536</integer>
+    </dict>
+    <key>HardResourceLimits</key>
+    <dict>
+        <key>NumberOfFiles</key>
+        <integer>65536</integer>
+    </dict>
+</dict>
+</plist>