scitex-dev 0.22.0__tar.gz → 0.23.0__tar.gz

{scitex_dev-0.22.0 → scitex_dev-0.23.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-07-01
+
+### Added
+- **`scitex-dev service ensure <name>` — supervised long-running services (#273).**
+  Resolves a `kind="service"` JobSpec from the `scitex_dev.jobs` entry-point
+  federation and guarantees it is installed AND running, picking the backend at
+  runtime: systemd `--user` (writes the `.service` unit, `daemon-reload`,
+  `enable --now`) where a user manager exists, otherwise a respawn keep-alive
+  loop (alive-flag + pidfile, capped exponential backoff, logs under
+  `~/.scitex/<pkg>/runtime/logs/`). `--respawn` forces the fallback; `--json`
+  emits a structured result. The durable auto-relaunch a daemon-owning leaf
+  (e.g. the sac listen server) declares once and consumes — closing the
+  "no supervisor" outage class.
+- **Opt-in systemd watchdog for `kind="service"` JobSpecs.** A new
+  `JobSpec.watchdog_sec` field emits `Type=notify` + `WatchdogSec=<N>s` ONLY
+  when a leaf sets it (i.e. the daemon sends `sd_notify(WATCHDOG=1)`). Unset ⇒
+  the unit stays `Type=simple` and relies on `Restart=` alone — avoiding the
+  restart-storm/activation-hang footguns of emitting a watchdog for a daemon
+  that never pings.
+
 ## [0.22.0] - 2026-07-01
 
 ### Added

{scitex_dev-0.22.0/src/scitex_dev.egg-info → scitex_dev-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.22.0
+Version: 0.23.0
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only

scitex_dev-0.23.0/src/scitex_dev/_cli/_integrations.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Integration-command registration for the scitex-dev CLI.
+
+Extracted from ``_root.py`` to keep that orchestrator under the per-file
+line budget. Registers the cross-cutting integration groups on the main
+click group:
+
+* ``mcp``     — MCP server lifecycle.
+* ``creds``   — credential distribution.
+* ``cron``    — ecosystem-wide managed cron.
+* ``hooks``   — git/agent hook management.
+* ``service`` — keep a declared ``kind='service'`` daemon alive
+                (systemd --user or respawn fallback).
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def register_integration_commands(main: click.Group) -> None:
+    """Register the integration command groups on ``main``."""
+    from ._mcp_cmds import register_mcp_commands
+    from .creds import register_creds_commands
+    from .cron import register_cron_commands
+    from ._hooks_cli import register_hooks_commands
+    from .service import register_service_commands
+
+    register_mcp_commands(main)
+    register_creds_commands(main)
+    register_cron_commands(main)
+    register_hooks_commands(main)
+    register_service_commands(main)
+
+
+__all__ = ["register_integration_commands"]
+
+
+# EOF

scitex_dev-0.23.0/src/scitex_dev/_cli/_list_apis.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""``scitex-dev list-python-apis`` — public API tree lister.
+
+Extracted from ``_root.py`` to keep that orchestrator under the
+per-file line budget. Registers a single ``list-python-apis`` command
+on the main click group.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+
+def register_list_python_apis_command(main: click.Group) -> None:
+    """Register ``scitex-dev list-python-apis`` on ``main``."""
+
+    @main.command("list-python-apis")
+    @click.option(
+        "-v",
+        "--verbose",
+        count=True,
+        help="Verbosity: -v sig+doc1, -vv full doc.",
+    )
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+    def list_python_apis(verbose, as_json):
+        """List Python APIs (scitex-dev public API tree).
+
+        \b
+        Example:
+            $ scitex-dev list-python-apis
+            $ scitex-dev list-python-apis -v --json
+        """
+        import inspect
+
+        import scitex_dev
+
+        items = []
+        for name in sorted(scitex_dev.__all__):
+            obj = getattr(scitex_dev, name, None)
+            if obj is None:
+                continue
+            if inspect.isclass(obj):
+                kind = "C"
+            elif callable(obj):
+                kind = "F"
+            else:
+                kind = "V"
+            doc = inspect.getdoc(obj) or ""
+            items.append({"name": name, "type": kind, "doc": doc})
+
+        if as_json:
+            click.echo(json.dumps(items, indent=2))
+            return
+
+        click.secho(
+            f"scitex-dev public API ({len(items)} items):",
+            fg="cyan",
+            bold=True,
+        )
+        for item in items:
+            t = item["type"]
+            click.echo(f"  [{t}] {item['name']}")
+            if verbose >= 1 and item["doc"]:
+                desc = item["doc"].split("\n")[0][:70]
+                click.echo(f"      {desc}")
+
+
+__all__ = ["register_list_python_apis_command"]
+
+
+# EOF

{scitex_dev-0.22.0 → scitex_dev-0.23.0}/src/scitex_dev/_cli/_root.py

@@ -17,7 +17,10 @@ COMMAND_CATEGORIES = [
     ("CI", ["ci"]),
     ("Development", ["show-config", "rename-symbols"]),
     ("Documentation", ["docs", "search-docs", "skills"]),
-    ("Ecosystem", ["audit-umbrella-pins", "cron", "doctor", "ecosystem", "creds"]),
+    (
+        "Ecosystem",
+        ["audit-umbrella-pins", "cron", "doctor", "ecosystem", "creds", "service"],
+    ),
     ("Interface", ["mcp", "list-python-apis"]),
     ("Shell", ["install-tab-completion"]),
 ]
@@ -439,15 +442,9 @@ def search_docs_deprecated(query, scope, max_results, as_json):
 # Integration commands
 # -------------------------------------------------------------------
 
-from ._mcp_cmds import register_mcp_commands
-from .creds import register_creds_commands
-from .cron import register_cron_commands
-from ._hooks_cli import register_hooks_commands
+from ._integrations import register_integration_commands
 
-register_mcp_commands(main)
-register_creds_commands(main)
-register_cron_commands(main)
-register_hooks_commands(main)
+register_integration_commands(main)
 
 # -------------------------------------------------------------------
 # ci runner — self-hosted GitHub Actions runner lifecycle
@@ -479,47 +476,6 @@ except Exception:
 # list-python-apis
 # -------------------------------------------------------------------
 
-@main.command("list-python-apis")
-@click.option(
-    "-v", "--verbose", count=True, help="Verbosity: -v sig+doc1, -vv full doc."
-)
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
-def list_python_apis(verbose, as_json):
-    """List Python APIs (scitex-dev public API tree).
-
-    \b
-    Example:
-        $ scitex-dev list-python-apis
-        $ scitex-dev list-python-apis -v --json
-    """
-    import inspect
-
-    import scitex_dev
+from ._list_apis import register_list_python_apis_command
 
-    items = []
-    for name in sorted(scitex_dev.__all__):
-        obj = getattr(scitex_dev, name, None)
-        if obj is None:
-            continue
-        if inspect.isclass(obj):
-            kind = "C"
-        elif callable(obj):
-            kind = "F"
-        else:
-            kind = "V"
-        doc = inspect.getdoc(obj) or ""
-        items.append({"name": name, "type": kind, "doc": doc})
-
-    if as_json:
-        click.echo(json.dumps(items, indent=2))
-        return
-
-    click.secho(
-        f"scitex-dev public API ({len(items)} items):", fg="cyan", bold=True
-    )
-    for item in items:
-        t = item["type"]
-        click.echo(f"  [{t}] {item['name']}")
-        if verbose >= 1 and item["doc"]:
-            desc = item["doc"].split("\n")[0][:70]
-            click.echo(f"      {desc}")
+register_list_python_apis_command(main)

scitex_dev-0.23.0/src/scitex_dev/_cli/service/__init__.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""``scitex-dev service …`` — keep a declared daemon alive, fleet-wide.
+
+A leaf declares a long-running daemon as a ``kind="service"`` JobSpec
+(via the ``scitex_dev.jobs`` entry-point federation). scitex-dev owns
+keeping it running so no package hand-rolls its own supervisor — the
+2026-07-01 sac ``listen`` daemon death (no supervisor, hung fleet) is
+exactly what this closes.
+
+Verbs:
+  * ``ensure``  — guarantee the named service is installed AND running,
+                  picking the systemd ``--user`` backend when available
+                  and a respawn keep-alive loop otherwise.
+"""
+
+from __future__ import annotations
+
+from ._cmd import register_service_commands
+
+__all__ = ["register_service_commands"]

scitex_dev-0.23.0/src/scitex_dev/_cli/service/_cmd.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""``scitex-dev service`` Click group + ``ensure`` subcommand."""
+
+from __future__ import annotations
+
+import click
+
+
+def register_service_commands(main_group: click.Group) -> click.Group:
+    """Register ``scitex-dev service`` on the given main group."""
+
+    @main_group.group("service", invoke_without_command=True)
+    @click.pass_context
+    def service(ctx: click.Context) -> None:
+        """Keep a declared ``kind='service'`` daemon alive, fleet-wide.
+
+        \b
+        Leaves declare a long-running daemon as a `kind="service"`
+        JobSpec via the `scitex_dev.jobs` entry-point group; scitex-dev
+        owns keeping it running. Two backends are chosen automatically:
+          * systemd --user   when a user manager is reachable
+          * respawn loop      otherwise (keep-alive under
+                              ~/.scitex/<pkg>/runtime/)
+
+        \b
+        Verbs:
+          ensure  — install + start the named service (idempotent)
+        """
+        if ctx.invoked_subcommand is None:
+            click.echo(ctx.get_help())
+
+    _register_ensure(service)
+    return service
+
+
+def _register_ensure(service: click.Group) -> None:
+    @service.command("ensure")
+    @click.argument("name")
+    @click.option(
+        "--json",
+        "as_json",
+        is_flag=True,
+        default=False,
+        help="Emit the ensure result as structured JSON.",
+    )
+    @click.option(
+        "--respawn",
+        "force_respawn",
+        is_flag=True,
+        default=False,
+        help=(
+            "Force the respawn-loop backend even if systemd --user is "
+            "available (for hosts where the user manager is present but "
+            "unwanted for this daemon)."
+        ),
+    )
+    def ensure(name: str, as_json: bool, force_respawn: bool) -> None:
+        """Ensure the `kind='service'` daemon NAME is installed AND running.
+
+        \b
+        Resolves NAME from the scitex_dev.jobs federation (same lookup
+        as `ecosystem systemd`), then:
+          * systemd --user available  → write the .service unit,
+            daemon-reload, enable --now (idempotent).
+          * otherwise                 → write + launch a respawn
+            keep-alive loop under ~/.scitex/<pkg>/runtime/.
+
+        \b
+        Example:
+          $ scitex-dev service ensure sac.listen
+          $ scitex-dev service ensure sac.listen --respawn
+          $ scitex-dev service ensure sac.listen --json
+        """
+        from ...jobs._ensure import ensure_service
+
+        avail_fn = (lambda: False) if force_respawn else None
+        try:
+            result = ensure_service(name, systemd_available_fn=avail_fn)
+        except KeyError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+        if as_json:
+            import json
+
+            click.echo(
+                json.dumps(
+                    {
+                        "name": result.name,
+                        "backend": result.backend,
+                        "unit_path": (
+                            str(result.unit_path) if result.unit_path else None
+                        ),
+                        "script_path": (
+                            str(result.script_path)
+                            if result.script_path
+                            else None
+                        ),
+                        "already_running": result.already_running,
+                        "messages": list(result.messages),
+                    }
+                )
+            )
+            return
+
+        click.echo(f"service ensure {result.name}: backend={result.backend}")
+        for msg in result.messages:
+            click.echo(f"  {msg}")
+
+
+__all__ = ["register_service_commands"]
+
+
+# EOF

{scitex_dev-0.22.0 → scitex_dev-0.23.0}/src/scitex_dev/jobs/__init__.py

@@ -147,6 +147,23 @@ class JobSpec:
         controls automatic restart on exit/failure. Defaults to
         ``"no"`` (no restart). MUST stay ``"no"`` for ``timer`` and
         ``cron`` kinds.
+    watchdog_sec
+        systemd ``WatchdogSec`` for ``kind="service"`` only — the
+        liveness-ping interval that guards against *hangs* (a crash is
+        already covered by ``Restart=``; a hang is not). Defaults to
+        ``None`` (no watchdog).
+
+        CRITICAL CAVEAT — opt-in on purpose. ``WatchdogSec`` does
+        NOTHING unless the daemon periodically calls
+        ``sd_notify(WATCHDOG=1)`` under ``Type=notify``. A plain
+        ``Type=simple`` daemon that never pings would be *killed and
+        restarted every ``WatchdogSec`` seconds* by systemd — a
+        footgun. So a JobSpec must EXPLICITLY set ``watchdog_sec`` to
+        request it; when set, the unit builder emits ``Type=notify`` +
+        ``WatchdogSec=<N>s`` and the LEAF is responsible for sending
+        the pings. When unset, the unit stays ``Type=simple`` and
+        relies on ``Restart=`` alone (crashes, not hangs). MUST be
+        ``None`` for ``timer`` and ``cron`` kinds.
     """
 
     name: str
@@ -158,6 +175,7 @@ class JobSpec:
     on_unit_active_sec: str | None = None
     timeout_sec: int | None = None
     restart_policy: str = "no"
+    watchdog_sec: int | None = None
 
     def __post_init__(self) -> None:
         # Run the validator at construction time so a malformed leaf
@@ -221,6 +239,15 @@ class JobSpec:
                 f"services use Restart= for keepalive, not a timer). "
                 f"Got: {self.on_unit_active_sec!r}"
             )
+        if self.watchdog_sec is not None and self.watchdog_sec <= 0:
+            # A non-positive interval is meaningless and, worse, would
+            # produce a WatchdogSec=0s that systemd treats as "disabled"
+            # while implying the leaf opted in — a confusing half-state.
+            raise ValueError(
+                f"JobSpec({self.name!r}, kind='service').watchdog_sec "
+                f"must be a positive number of seconds when set. "
+                f"Got: {self.watchdog_sec!r}"
+            )
 
     def _validate_timer(self) -> None:
         # A systemd Timer needs SOMETHING to tell it when to fire.
@@ -239,6 +266,12 @@ class JobSpec:
                 f"must be 'no' (timers fire oneshot services; Restart= "
                 f"doesn't apply). Got: {self.restart_policy!r}"
             )
+        if self.watchdog_sec is not None:
+            raise ValueError(
+                f"JobSpec({self.name!r}, kind='timer').watchdog_sec "
+                f"must be None (WatchdogSec guards long-running services, "
+                f"not oneshot timer bodies). Got: {self.watchdog_sec!r}"
+            )
 
     def _validate_cron(self) -> None:
         # Cron lines are inert text in the user's crontab. The systemd
@@ -275,6 +308,12 @@ class JobSpec:
                 f"must be 'no' (cron has no restart concept). Got: "
                 f"{self.restart_policy!r}"
             )
+        if self.watchdog_sec is not None:
+            raise ValueError(
+                f"JobSpec({self.name!r}, kind='cron').watchdog_sec "
+                f"must be None (systemd-only field). Got: "
+                f"{self.watchdog_sec!r}"
+            )
 
 
 def _iter_entry_points(group: str):