cognitivesystems 0.0.2__py3-none-any.whl

cognitivesystems/__init__.py

@@ -0,0 +1,8 @@
+"""CognitiveSystems — catalog-driven Docker homeserver deployer."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cognitivesystems")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

cognitivesystems/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m cognitivesystems`` entry point."""
+import sys
+
+from cognitivesystems.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cognitivesystems/bootstrap.py

@@ -0,0 +1,10 @@
+"""Bootstrap paths — default state file location (``--state`` override only)."""
+
+from __future__ import annotations
+
+import pathlib
+
+
+def default_state_path() -> pathlib.Path:
+    """Return the default ``state.json`` path under the user's home directory."""
+    return pathlib.Path.home() / "cognitivesystems" / "state" / "state.json"

cognitivesystems/catalog.py

@@ -0,0 +1,65 @@
+"""Catalog access — thin wrapper over the renderer's loader.
+
+Keeps one source of truth (``render.load_catalog``) while giving the CLI/TUI a
+small, import-friendly surface that resolves the packaged-or-repo catalog dir.
+"""
+from __future__ import annotations
+
+import pathlib
+
+from . import render
+
+
+def load(services_dir: pathlib.Path | None = None, *, overlay: bool = True) -> dict:
+    """Load the service catalog (shipped services plus the optional user overlay).
+
+    Parameters
+    ----------
+    services_dir : pathlib.Path or None, optional
+        Directory holding the per-service ``service.yml`` files. ``None`` resolves the
+        packaged-or-repo default via :func:`render.default_services_dir`.
+    overlay : bool, default: True
+        When ``True``, merge the user-catalog overlay (custom/community apps) over the
+        shipped services.
+
+    Returns
+    -------
+    dict
+        The merged catalog, shaped ``{"install_order": [...], "services": {...}}``.
+    """
+    return render.load_catalog(
+        services_dir or render.default_services_dir(),
+        render.default_overlay_dir() if overlay else None)   # include custom/community apps
+
+
+def meta(services_dir: pathlib.Path | None = None) -> dict:
+    """Return the compact catalog summary consumed by the deploy/CLI/TUI layers.
+
+    Parameters
+    ----------
+    services_dir : pathlib.Path or None, optional
+        Catalog directory; ``None`` uses the packaged-or-repo default.
+
+    Returns
+    -------
+    dict
+        The catalog meta (display names, subdomains, host ports, auth, …) as produced
+        by :func:`render._meta`.
+    """
+    return render._meta(load(services_dir))
+
+
+def service_names(services_dir: pathlib.Path | None = None) -> list[str]:
+    """List the catalog's service keys, sorted.
+
+    Parameters
+    ----------
+    services_dir : pathlib.Path or None, optional
+        Catalog directory; ``None`` uses the packaged-or-repo default.
+
+    Returns
+    -------
+    list of str
+        Sorted service keys.
+    """
+    return sorted(load(services_dir)["services"].keys())

cognitivesystems/cli.py

@@ -0,0 +1,540 @@
+"""CognitiveSystems CLI.
+
+Cross-platform commands (``list`` / ``meta`` / ``render`` / ``init`` / ``configure``)
+plus the Linux-only deploy commands (``install`` / ``update`` / ``uninstall`` / ``system``).
+Running ``cognitivesystems`` with no subcommand launches the web dashboard, falling back
+to the Textual TUI when the ``[web]`` extra is absent or the dashboard is disabled.
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import pathlib
+import sys
+
+from . import __version__, bootstrap, catalog, config, credentials, render, state
+
+
+def _split(items: list[str] | None) -> list[str]:
+    """Flatten repeated and comma-separated CLI values into a flat list.
+
+    Parameters
+    ----------
+    items : list of str or None
+        Raw argument values (each may itself be comma-separated).
+
+    Returns
+    -------
+    list of str
+        The non-empty, comma-split items.
+    """
+    return [s for grp in (items or []) for s in str(grp).split(",") if s]
+
+
+# ─── cross-platform ──────────────────────────────────────────────────────────
+def _cmd_list(args: argparse.Namespace) -> int:
+    """``list`` — print catalog services, marking installed ones with ``*``.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (uses ``args.state``).
+
+    Returns
+    -------
+    int
+        Process exit code.
+    """
+    m = catalog.meta()
+    inst = (state.load(args.state).get("installed") or {}) if pathlib.Path(args.state).is_file() else {}
+    for name in sorted(m["services"]):
+        d = m["services"][name]
+        mark = "*" if name in inst else " "
+        print(f"{mark} {name:20} {d.get('display_name', name)}")
+    return 0
+
+
+def _cmd_meta(args: argparse.Namespace) -> int:
+    """``meta`` — print the catalog metadata as JSON.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (unused).
+
+    Returns
+    -------
+    int
+        Process exit code.
+    """
+    print(json.dumps(catalog.meta(), indent=2))
+    return 0
+
+
+def _cmd_render(args: argparse.Namespace) -> int:
+    """``render`` — render one service's compose + ``.env`` to a directory.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (service, ``--out``, ``--services-dir``, ``--no-sidecars``, state).
+
+    Returns
+    -------
+    int
+        Process exit code from the renderer.
+    """
+    argv = [args.service, "--state", args.state, "--out-root", args.out]
+    if args.services_dir:
+        argv += ["--services-dir", args.services_dir]
+    if args.no_sidecars:
+        argv += ["--no-sidecars"]
+    return render.main(argv)
+
+
+def _cmd_tui(args: argparse.Namespace) -> int:
+    """``tui`` — launch the Textual terminal UI.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (uses ``args.state``).
+
+    Returns
+    -------
+    int
+        Process exit code (``1`` if Textual is unavailable).
+    """
+    try:
+        from . import tui
+    except ImportError as e:  # textual missing
+        print(f"TUI unavailable ({e}). Reinstall: pip install cognitivesystems", file=sys.stderr)
+        return 1
+    return tui.run(args.state)
+
+
+def _cmd_web(args: argparse.Namespace) -> int:
+    """``web`` — launch the FastAPI web dashboard.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (``--host``, ``--port``, ``--no-open``, state).
+
+    Returns
+    -------
+    int
+        Process exit code (``1`` if the ``[web]`` extra is not installed).
+    """
+    try:
+        from .web import server
+    except ImportError as e:  # [web] extra not installed
+        print(f"web dashboard unavailable ({e}). Install: pip install cognitivesystems[web]",
+              file=sys.stderr)
+        return 1
+    return server.serve(state_path=args.state, host=args.host, port=args.port,
+                        open_browser=not getattr(args, "no_open", False))
+
+
+def _web_disabled(state_path: str) -> bool:
+    """Report whether the auto-launching dashboard has been explicitly disabled.
+
+    Parameters
+    ----------
+    state_path : str
+        Path to ``state.json``.
+
+    Returns
+    -------
+    bool
+        ``True`` if ``state.dashboard.enabled`` is ``False``.
+    """
+    p = pathlib.Path(state_path)
+    data = state.load(p) if p.is_file() else {}
+    return (data.get("dashboard") or {}).get("enabled") is False
+
+
+def _web_available() -> bool:
+    """Report whether the web dashboard dependencies are importable.
+
+    Returns
+    -------
+    bool
+        ``True`` if both ``fastapi`` and ``uvicorn`` can be found.
+    """
+    return all(importlib.util.find_spec(m) is not None for m in ("fastapi", "uvicorn"))
+
+
+def _cmd_default(args: argparse.Namespace) -> int:
+    """No subcommand: launch the web dashboard, falling back to the TUI.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments.
+
+    Returns
+    -------
+    int
+        Process exit code from whichever interface is launched.
+    """
+    if not _web_disabled(args.state) and _web_available():
+        return _cmd_web(args)
+    return _cmd_tui(args)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    """``init`` — create ``state.json`` from an install profile.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (``--profile``, state).
+
+    Returns
+    -------
+    int
+        Process exit code (``1`` if the profile is not found).
+    """
+    data_path = pathlib.Path(args.state)
+    try:
+        state.init(data_path, args.profile)
+    except FileNotFoundError as e:
+        print(f"cognitivesystems init: {e}", file=sys.stderr)
+        return 1
+    print(f"init: wrote {data_path} (profile: {args.profile})")
+    return 0
+
+
+def _cmd_configure(args: argparse.Namespace) -> int:
+    """``configure`` — interactively set credentials/secrets into ``state.json``.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (``--profile``, ``--service``, ``--registries``, state).
+
+    Returns
+    -------
+    int
+        Process exit code.
+    """
+    data_path = pathlib.Path(args.state)
+    data = state.load(data_path) or state.default_state()
+    if not data.get("site"):
+        try:
+            state.load_profile(data, args.profile)
+            data.setdefault("site", {})["profile"] = args.profile
+        except FileNotFoundError:
+            pass
+    credentials.configure(data, catalog.meta(),
+                          services=_split(args.service) or None,
+                          registries=args.registries)
+    state.save(data_path, data)
+    print(f"configure: saved {data_path}")
+    return 0
+
+
+# ─── deploy (Linux) ──────────────────────────────────────────────────────────
+def _load_for_deploy(args: argparse.Namespace):
+    """Load state + meta and run preflight for a deploy command.
+
+    Seeds the default profile when state has no ``.site`` yet, then runs
+    :func:`deploy.preflight` (which creates the profile's data root).
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (uses ``args.state``).
+
+    Returns
+    -------
+    tuple
+        ``(deploy_module, data_path, meta, data)``.
+    """
+    from . import deploy
+    data_path = pathlib.Path(args.state)
+    meta = catalog.meta()
+    data = state.load(data_path) or state.default_state()
+    if not data.get("site"):  # seed the default profile when state has no .site yet
+        try:
+            state.load_profile(data, "homeserver")
+            data.setdefault("site", {})["profile"] = "homeserver"
+        except FileNotFoundError:
+            pass
+    deploy.preflight(data)  # after state load: preflight creates the profile's data root
+    return deploy, data_path, meta, data
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    """``install`` — install services (Linux + Docker).
+
+    Applies CLI overrides, requires the needed secrets non-interactively, resolves install
+    order, checks port conflicts, then installs each service (one failure does not abort the
+    batch; failures are summarized).
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (services, ``--mode``/``--domain``/``--wildcard``/…, state).
+
+    Returns
+    -------
+    int
+        ``0`` if all succeeded, ``1`` if any service or a precheck failed.
+    """
+    from .deploy import DeployError
+    try:
+        deploy, data_path, meta, data = _load_for_deploy(args)
+        state.apply_cli_overrides(
+            data, puid=args.puid, pgid=args.pgid, mode=args.mode, domain=args.domain,
+            wildcard=(True if args.wildcard else None), cf_dns_token=args.cf_token,
+        )
+        # non-interactive: required secrets must already be in env/state (the TUI
+        # spawns install as a subprocess with no stdin, so it cannot prompt)
+        credentials.require_globals(data, interactive=False)
+        state.save(data_path, data)
+        deploy.registry_login(data)
+        ordered = deploy.resolve_deps(_split(args.services), meta)
+        # fail closed before touching anything if two services would fight over a
+        # host port (e.g. MariaDB + MySQL on 3306) — clearer than a mid-deploy abort
+        deploy.check_port_conflicts(ordered, meta, data)
+        failed: list[str] = []
+        for svc in ordered:
+            # one failing service must not abort the batch: log it, keep going
+            # (dependents of a failed dependency simply fail too and get reported),
+            # then summarize at the end and exit nonzero if anything failed
+            try:
+                if state.is_installed(data, svc):
+                    if args.force:
+                        deploy.uninstall_one(svc, data, meta, data_path, purge=args.purge)
+                    else:
+                        print(f"{svc} already installed; skipping (use --force to reinstall)")
+                        continue
+                deploy.install_one(svc, data, meta, data_path, auto_update=args.auto_update)
+            except DeployError as e:
+                failed.append(svc)
+                print(f"cognitivesystems install: {svc} failed: {e}", file=sys.stderr)
+        if failed:
+            print(f"cognitivesystems install: {len(failed)}/{len(ordered)} services failed: "
+                  f"{', '.join(failed)} — fix the cause and re-run the same install "
+                  "(succeeded services are skipped)", file=sys.stderr)
+            return 1
+    except (DeployError, credentials.CredentialError) as e:
+        print(f"cognitivesystems install: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    """``update`` — update the given services, or all installed when none are named.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (optional services, state).
+
+    Returns
+    -------
+    int
+        ``0`` on success, ``1`` if nothing is installed or an update fails.
+    """
+    from .deploy import DeployError
+    try:
+        deploy, data_path, meta, data = _load_for_deploy(args)
+        svcs = _split(args.services) or list((data.get("installed") or {}).keys())
+        if not svcs:
+            print("nothing installed to update.", file=sys.stderr)
+            return 1
+        for svc in svcs:
+            deploy.update_one(svc, data, meta, data_path)
+    except DeployError as e:
+        print(f"cognitivesystems update: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_uninstall(args: argparse.Namespace) -> int:
+    """``uninstall`` — remove the given services (optionally purging their data).
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (services, ``--purge``, state).
+
+    Returns
+    -------
+    int
+        ``0`` on success, ``1`` if an uninstall fails.
+    """
+    from .deploy import DeployError
+    try:
+        deploy, data_path, meta, data = _load_for_deploy(args)
+        for svc in _split(args.services):
+            deploy.uninstall_one(svc, data, meta, data_path, purge=args.purge)
+    except DeployError as e:
+        print(f"cognitivesystems uninstall: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_system(args: argparse.Namespace) -> int:
+    """``system`` — run a host-admin action (ssh-keygen / change-password / media-user).
+
+    Resolves the active profile's data root from state (ssh-keygen publishes under it).
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments (``action``, passthrough ``args``, state).
+
+    Returns
+    -------
+    int
+        The action's exit code (``1`` on a deploy error).
+    """
+    from . import system
+    from .deploy import DeployError
+    try:
+        # ssh-keygen publishes under the active profile's data root; resolve it from state
+        data = state.load(pathlib.Path(args.state)) or state.default_state()
+        if not data.get("site"):  # seed the default profile so data_root resolves
+            try:
+                state.load_profile(data, "homeserver")
+                data.setdefault("site", {})["profile"] = "homeserver"
+            except FileNotFoundError:
+                pass
+        return system.run(args.action, args.args, data_root=config.data_root_for(data))
+    except (DeployError, config.ConfigError) as e:
+        print(f"cognitivesystems system: {e}", file=sys.stderr)
+        return 1
+
+
+# ─── parser ──────────────────────────────────────────────────────────────────
+def _add_state_arg(sp: argparse.ArgumentParser) -> None:
+    """Add the shared ``--state`` argument to a subparser.
+
+    Parameters
+    ----------
+    sp : argparse.ArgumentParser
+        The subparser to extend.
+    """
+    sp.add_argument("--state", default=str(bootstrap.default_state_path()),
+                    help="path to state.json (default: %(default)s)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser with all subcommands.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        The configured parser.
+    """
+    p = argparse.ArgumentParser(
+        prog="cognitivesystems",
+        description="CognitiveSystems - catalog-driven Docker homeserver deployer.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    sp = sub.add_parser("list", help="list catalog services (* = installed)")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_list)
+
+    sp = sub.add_parser("meta", help="print catalog metadata as JSON")
+    sp.set_defaults(func=_cmd_meta)
+
+    sp = sub.add_parser("tui", help="launch the terminal UI")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_tui)
+
+    sp = sub.add_parser("web", help="launch the web dashboard (host control plane; auto with no command)")
+    sp.add_argument("--host", default="127.0.0.1",
+                    help="bind address (default loopback; off-loopback exposes full host/docker)")
+    sp.add_argument("--port", type=int, default=8800)
+    sp.add_argument("--no-open", dest="no_open", action="store_true", help="don't open a browser")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_web)
+
+    sp = sub.add_parser("render", help="render a service's compose + .env")
+    sp.add_argument("service")
+    sp.add_argument("--out", default="./render-out")
+    sp.add_argument("--services-dir", default=None)
+    sp.add_argument("--no-sidecars", action="store_true")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_render)
+
+    sp = sub.add_parser("init", help="create state.json from a profile")
+    sp.add_argument("--profile", default="homeserver")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_init)
+
+    sp = sub.add_parser("configure",
+                        help="set credentials/secrets (prompt; Enter = generate) → state.json")
+    sp.add_argument("--profile", default="homeserver")
+    sp.add_argument("--service", action="append",
+                    help="limit per-service password prompts (repeatable)")
+    sp.add_argument("--registries", action="store_true",
+                    help="also add/edit private registry logins")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_configure)
+
+    sp = sub.add_parser("install", help="install services (Linux + Docker)")
+    sp.add_argument("services", nargs="+", help="service names (comma or space separated)")
+    sp.add_argument("--mode", choices=["public", "private", "local"], default=None)
+    sp.add_argument("--domain", default=None)
+    sp.add_argument("--puid", default=None)
+    sp.add_argument("--pgid", default=None)
+    sp.add_argument("--wildcard", action="store_true")
+    sp.add_argument("--cf-token", dest="cf_token", default=None,
+                    help="scoped Cloudflare DNS API token (wildcard DNS-01)")
+    sp.add_argument("--force", action="store_true", help="reinstall if already installed")
+    sp.add_argument("--purge", action="store_true", help="also drop data dir (with --force)")
+    g = sp.add_mutually_exclusive_group()
+    g.add_argument("--auto-update", dest="auto_update", action="store_true", default=None)
+    g.add_argument("--no-auto-update", dest="auto_update", action="store_false")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_install)
+
+    sp = sub.add_parser("update", help="update services (default: all installed)")
+    sp.add_argument("services", nargs="*")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_update)
+
+    sp = sub.add_parser("uninstall", help="uninstall services")
+    sp.add_argument("services", nargs="+")
+    sp.add_argument("--purge", action="store_true", help="also drop data dir")
+    _add_state_arg(sp)
+    sp.set_defaults(func=_cmd_uninstall)
+
+    sp = sub.add_parser("system", help="host admin (Linux): ssh-keygen | change-password | media-user")
+    sp.add_argument("action", choices=["ssh-keygen", "change-password", "media-user"])
+    _add_state_arg(sp)   # ssh-keygen resolves the profile's data_root from state; pass --state BEFORE the action
+    sp.add_argument("args", nargs=argparse.REMAINDER, help="arguments passed through to the action")
+    sp.set_defaults(func=_cmd_system)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point: parse arguments and dispatch to the selected command.
+
+    Parameters
+    ----------
+    argv : list of str or None, optional
+        Argument vector; ``None`` uses ``sys.argv``.
+
+    Returns
+    -------
+    int
+        The selected command's exit code.
+    """
+    args = build_parser().parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:  # no subcommand → web dashboard (auto), else the TUI
+        ns = argparse.Namespace(state=str(bootstrap.default_state_path()), host="127.0.0.1",
+                                port=8800, no_open=False)
+        return _cmd_default(ns)
+    return func(args)