rig-cli 1.0.0__py3-none-any.whl

rig/__init__.py

@@ -0,0 +1,6 @@
+"""rig: Zero-dependency local dev environment and process runner."""
+
+from rig.cli import main
+from rig.core.constants import __version__
+
+__all__ = ["__version__", "main"]

rig/__main__.py

@@ -0,0 +1,8 @@
+"""rig CLI entry point when invoked via python -m rig."""
+
+import sys
+
+from rig.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rig/cli.py

@@ -0,0 +1,107 @@
+"""Generic local stack orchestrator and command-line entry point."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Any
+
+from rig.commands.dispatch import _dispatch_command, _handle_exception, _prepare_args
+from rig.core import constants
+from rig.core.errors import RigError
+from rig.parser import build_parser
+
+_SUBMODULES = (
+    "rig.core.constants",
+    "rig.core.errors",
+    "rig.core.identity",
+    "rig.core.locks",
+    "rig.core.state",
+    "rig.core.env",
+    "rig.core.terminal",
+    "rig.net.ports",
+    "rig.net.probe",
+    "rig.net.health",
+    "rig.proc.process",
+    "rig.proc.teardown",
+    "rig.proc.spawn",
+    "rig.proc.record",
+    "rig.compose.client",
+    "rig.compose.context",
+    "rig.compose.docker",
+    "rig.compose.discovery",
+    "rig.compose.supervisor",
+    "rig.compose.starter",
+    "rig.compose.stopper",
+    "rig.manifest.models",
+    "rig.manifest.parser",
+    "rig.manifest.detector",
+    "rig.manifest.inspect",
+    "rig.manifest.loader",
+    "rig.manifest.schema",
+    "rig.commands.common",
+    "rig.commands.dispatch",
+    "rig.commands.up",
+    "rig.commands.up.context",
+    "rig.commands.up.service",
+    "rig.commands.up.runner",
+    "rig.commands.up.rollback",
+    "rig.commands.up.relink",
+    "rig.commands.up.loop",
+    "rig.commands.down",
+    "rig.commands.down.runner",
+    "rig.commands.status",
+    "rig.commands.ps",
+    "rig.commands.prune",
+    "rig.commands.check",
+    "rig.commands.init",
+    "rig.commands.logs",
+    "rig.parser",
+)
+
+for _mod in _SUBMODULES:
+    _m = importlib.import_module(_mod)
+    for _k, _v in _m.__dict__.items():
+        if not _k.startswith("__"):
+            globals()[_k] = _v
+
+
+class _CliModule(ModuleType):
+    def __setattr__(self, name: str, value: Any) -> None:
+        super().__setattr__(name, value)
+        for mod_name, mod in list(sys.modules.items()):
+            if mod_name.startswith("rig.") and mod is not self and name in mod.__dict__:
+                setattr(mod, name, value)
+
+    def __delattr__(self, name: str) -> None:
+        super().__delattr__(name)
+        for mod_name, mod in list(sys.modules.items()):
+            if mod_name.startswith("rig.") and mod is not self and name in mod.__dict__:
+                mod.__dict__.pop(name, None)
+
+
+sys.modules[__name__].__class__ = _CliModule
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    as_json = "--json" in raw_argv
+    if as_json:
+        raw_argv = [a for a in raw_argv if a != "--json"]
+    parser = build_parser(as_json=as_json)
+    try:
+        args = parser.parse_args(raw_argv)
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else constants.EXIT_USAGE
+
+    _prepare_args(args, as_json)
+    try:
+        return _dispatch_command(args.command, args)
+    except (RigError, TimeoutError, KeyboardInterrupt, OSError, RuntimeError, ValueError) as exc:
+        return _handle_exception(exc, args.command, as_json)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rig/commands/__init__.py

@@ -0,0 +1,23 @@
+"""Command handlers for the rig CLI."""
+
+from rig.commands.check import cmd_check
+from rig.commands.down import cmd_down
+from rig.commands.init import cmd_init
+from rig.commands.logs import cmd_logs
+from rig.commands.prune import cmd_prune
+from rig.commands.ps import cmd_ps
+from rig.commands.status import cmd_status
+from rig.commands.up import cmd_up
+from rig.manifest.schema import cmd_schema
+
+__all__ = [
+    "cmd_check",
+    "cmd_down",
+    "cmd_init",
+    "cmd_logs",
+    "cmd_prune",
+    "cmd_ps",
+    "cmd_schema",
+    "cmd_status",
+    "cmd_up",
+]

rig/commands/check.py

@@ -0,0 +1,125 @@
+"""Static project and manifest verification command."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from rig.core.constants import EXIT_OK, EXIT_USAGE
+from rig.core.env import render
+from rig.core.errors import RigError, print_json_envelope
+from rig.core.terminal import get_theme
+from rig.manifest.inspect import _resolve_executable
+from rig.manifest.loader import load_manifest
+
+MANIFEST_EXCEPTIONS = (RigError, OSError, ValueError, KeyError)
+
+
+def _check_binary(
+    spec: str, cwd: Path, ctx: tuple[dict[str, Any], str, list[dict[str, Any]]]
+) -> None:
+    render_vals, tag, issues = ctx
+    bin_str = str(render(spec, render_vals))
+    actual = _resolve_executable(bin_str, cwd)
+    if actual is None:
+        msg = f"executable '{spec}' not found"
+        issues.append({"level": "error", "check": f"{tag}:binary", "message": msg})
+    elif not os.access(actual, os.X_OK):
+        msg = f"file '{spec}' is not executable"
+        issues.append({"level": "error", "check": f"{tag}:binary", "message": msg})
+
+
+def _check_proc_service(
+    svc: Any, info: tuple[Path, Path, str], issues: list[dict[str, Any]]
+) -> None:
+    root, cwd, tag = info
+    if not shutil.which("lsof"):
+        msg = "'lsof' not found on PATH"
+        issues.append({"level": "error", "check": f"{tag}:lsof", "message": msg})
+    vals = {"root": str(root), "cwd": str(cwd), "python": sys.executable}
+    bin_ctx = (vals, tag, issues)
+    if svc.command:
+        _check_binary(svc.command[0], cwd, bin_ctx)
+    elif svc.type == "fd" and svc.python:
+        _check_binary(svc.python, cwd, bin_ctx)
+
+
+def _check_compose_service(svc: Any, info: tuple[Path, str], issues: list[dict[str, Any]]) -> None:
+    root, tag = info
+    if not shutil.which("docker"):
+        msg = "'docker' not found on PATH"
+        issues.append({"level": "error", "check": f"{tag}:docker", "message": msg})
+    if svc.compose_file and not (p := (root / svc.compose_file).resolve()).is_file():
+        msg = f"compose file '{p}' does not exist"
+        issues.append({"level": "error", "check": f"{tag}:compose_file", "message": msg})
+
+
+def _check_service(svc: Any, root: Path, ctx: tuple[str, str, list[dict[str, Any]]]) -> None:
+    sname, mode_tag, issues = ctx
+    cwd = (root / svc.cwd).resolve()
+    tag = f"{mode_tag} service:{sname}".strip()
+    if not cwd.is_dir():
+        msg = f"working directory '{cwd}' does not exist"
+        issues.append({"level": "error", "check": f"{tag}:cwd", "message": msg})
+    if svc.type in ("fd", "port"):
+        _check_proc_service(svc, (root, cwd, tag), issues)
+    elif svc.type == "compose":
+        _check_compose_service(svc, (root, tag), issues)
+
+
+def _check_modes(
+    manifest: Any, modes: list[str | None], ctx: tuple[Path, list[dict[str, Any]]]
+) -> None:
+    root, issues = ctx
+    for m in modes:
+        try:
+            m_manifest = manifest.for_mode(m)
+        except MANIFEST_EXCEPTIONS as exc:
+            issues.append({"level": "error", "check": f"mode:{m}", "message": str(exc)})
+            continue
+        tag = f"[{m}]" if m else ""
+        for sname, svc in m_manifest.services.items():
+            _check_service(svc, root, (sname, tag, issues))
+
+
+def _report_check_results(
+    manifest: Any, issues: list[dict[str, Any]], opts: tuple[int, bool, Path]
+) -> int:
+    mode_count, as_json, manifest_path = opts
+    has_errors = any(i["level"] == "error" for i in issues)
+    if as_json:
+        data = {"ok": not has_errors, "project": manifest.project, "issues": issues}
+        print_json_envelope("check", data)
+        return EXIT_USAGE if has_errors else EXIT_OK
+    th = get_theme()
+    for i in issues:
+        prefix = f"{th.red}✖ FAIL{th.r}" if i["level"] == "error" else f"{th.yellow}▲ WARN{th.r}"
+        print(f"{prefix} {i['check']}: {i['message']}", file=sys.stderr)
+    if not issues:
+        msg = f"manifest '{manifest_path}' is valid for {mode_count} mode(s)."
+        print(f"{th.green}✓ OK{th.r} check passed: {msg}")
+    return EXIT_USAGE if has_errors else EXIT_OK
+
+
+def cmd_check(root: Path, manifest_path: Path, *args: Any, **kwargs: Any) -> int:
+    argv = list(args)
+    mode = kwargs.get("mode") or (argv.pop(0) if argv else None)
+    as_json = bool(kwargs.get("as_json") or (argv.pop(0) if argv else False))
+    issues: list[dict[str, Any]] = []
+    resolved_root = Path(root).resolve()
+    try:
+        manifest = load_manifest(manifest_path)
+    except MANIFEST_EXCEPTIONS as exc:
+        if as_json:
+            issue = {"level": "error", "check": "manifest", "message": str(exc)}
+            print_json_envelope("check", {"ok": False, "issues": [issue]})
+        else:
+            print(f"FAIL manifest: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+    modes = [mode] if mode else (list(manifest.modes.keys()) if manifest.modes else [None])
+    _check_modes(manifest, modes, (resolved_root, issues))
+    return _report_check_results(manifest, issues, (len(modes), as_json, manifest_path))

rig/commands/common.py

@@ -0,0 +1,149 @@
+"""Common command helpers, dependency ordering, and state inspection."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from rig.compose.stopper import compose_stop_record
+from rig.compose.supervisor import compose_record_alive, compose_record_status
+from rig.core.constants import TEARDOWN_TIMEOUT_SECS
+from rig.core.identity import instance_id
+from rig.core.locks import _lock_path, ensure_runtime_dir
+from rig.core.state import _state_path
+from rig.manifest.loader import load_manifest
+from rig.manifest.models import Manifest
+from rig.net.ports import port_is_free
+from rig.proc.process import identity_matches, pid_alive
+from rig.proc.teardown import pgid_alive, terminate_record
+
+_COMPOSE_STATUS_LABELS: dict[str, str] = {"alive": "running", "error": "error"}
+
+
+def record_alive(record: Mapping[str, Any], root: Path) -> bool:
+    if record.get("type") == "compose":
+        return compose_record_alive(record, root)
+    return identity_matches(record)
+
+
+def record_status(record: Mapping[str, Any], root: Path) -> str:
+    """Return 'running', 'stopped' or 'error' for one recorded service."""
+    if record.get("type") != "compose":
+        return "running" if identity_matches(record) else "stopped"
+    return _COMPOSE_STATUS_LABELS.get(compose_record_status(record, root), "stopped")
+
+
+def is_service_verifiable_alive(record: Mapping[str, Any], root: Path) -> bool:
+    if record.get("type") == "compose":
+        return compose_record_alive(record, root)
+    pid = record.get("pid")
+    return isinstance(pid, int) and pid_alive(pid) and identity_matches(record)
+
+
+def is_service_active_in_mode(record: Mapping[str, Any], root: Path) -> bool:
+    if record.get("type") == "compose":
+        return compose_record_status(record, root) != "absent"
+    return (
+        is_service_verifiable_alive(record, root)
+        or (isinstance(record.get("pgid"), int) and pgid_alive(record["pgid"]))
+        or (isinstance(record.get("pid"), int) and pid_alive(record["pid"]))
+    )
+
+
+def _is_dead(rec: Mapping[str, Any], root: Path) -> bool:
+    if rec.get("type") == "compose":
+        return compose_record_status(rec, root) == "absent"
+    pgid_ok = isinstance(rec.get("pgid"), int) and pgid_alive(rec["pgid"])
+    return not identity_matches(rec) and not pgid_ok
+
+
+def prune_state(state: dict[str, Any], root: Path) -> list[str]:
+    dropped = [n for n, r in list(state.get("services", {}).items()) if _is_dead(r, root)]
+    for name in dropped:
+        rec = state["services"].pop(name, None) or {}
+        if (port := rec.get("port")) and not port_is_free(int(port)):
+            warn = f"  warning: {name} port {port} in use (pid {rec.get('pid')} may be orphaned)"
+            print(warn, file=sys.stderr)
+    return dropped
+
+
+def _values_for(state: Mapping[str, Any], root: Path, instance: str) -> dict[str, Any]:
+    values: dict[str, Any] = {
+        "root": str(root),
+        "instance": instance,
+        "data_dir": str(Path(root) / "data"),
+        "python": sys.executable,
+    }
+    for name, record in state.get("services", {}).items():
+        if record.get("port"):
+            values[f"{name}_port"] = record["port"]
+            values[f"{name}_url"] = record.get("url") or f"http://127.0.0.1:{record['port']}"
+    return values
+
+
+def record_depends_on(record: Mapping[str, Any]) -> list[str]:
+    raw = record.get("depends_on")
+    return [i for i in raw if isinstance(i, str)] if isinstance(raw, (list, tuple, set)) else []
+
+
+def _merged_depends_on(
+    name: str, record: Mapping[str, Any], manifest: Manifest | None = None
+) -> set[str]:
+    deps = set(record_depends_on(record))
+    if manifest is not None and name in manifest.services:
+        deps.update(manifest.services[name].depends_on)
+    return deps - {name}
+
+
+def _consumers_of(
+    name: str, services: Mapping[str, Mapping[str, Any]], manifest: Manifest | None = None
+) -> set[str]:
+    consumers = {
+        other for other, rec in services.items() if name in _merged_depends_on(other, rec, manifest)
+    }
+    if manifest is not None:
+        consumers.update(manifest.dependents(name))
+    return consumers - {name}
+
+
+def _drain_ready_deps(deps: set[str], in_degree: dict[str, int]) -> list[str]:
+    in_degree.update({d: in_degree[d] - 1 for d in deps})
+    return [d for d in deps if in_degree[d] == 0]
+
+
+def reverse_dependency_order(services: Mapping[str, Mapping[str, Any]]) -> list[str]:
+    in_degree = {k: 0 for k in services}
+    dep_map = {k: set() for k in services}
+    for name, rec in services.items():
+        for d in {d for d in record_depends_on(rec) if d in services and d != name}:
+            dep_map[name].add(d)
+            in_degree[d] += 1
+    queue = [k for k, deg in in_degree.items() if deg == 0]
+    order = []
+    while queue:
+        curr = queue.pop(0)
+        order.append(curr)
+        queue.extend(_drain_ready_deps(dep_map[curr], in_degree))
+    return order + [k for k in services if k not in order]
+
+
+def _stop_record(record: Mapping[str, Any], root: Path, remove: bool = True) -> str:
+    if record.get("type") == "compose":
+        return compose_stop_record(record, root, remove=remove)
+    return terminate_record(record, TEARDOWN_TIMEOUT_SECS)
+
+
+def _resolve_manifest_context(root: Path, manifest_path: Path):
+    raw_manifest = load_manifest(manifest_path)
+    resolved_root = Path(root).resolve()
+    ensure_runtime_dir(resolved_root)
+    instance = instance_id(raw_manifest.project, resolved_root)
+    return (
+        raw_manifest,
+        resolved_root,
+        instance,
+        _state_path(resolved_root, instance=instance),
+        _lock_path(resolved_root, instance=instance),
+    )

rig/commands/dispatch.py

@@ -0,0 +1,87 @@
+"""Command dispatching and top-level CLI error handling."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from rig import commands
+from rig.core import constants
+from rig.core.errors import RigError, format_human_error, print_json_error
+from rig.core.identity import find_default_manifest, find_project_root
+from rig.core.terminal import get_theme
+
+
+def _dispatch_command(cmd: str, args: argparse.Namespace) -> int:
+    root, mf, j = args.root_dir, args.manifest_file, args.as_json
+    dispatch = {
+        "up": lambda: commands.cmd_up(
+            root, mf, scope=args.scope, mode=args.mode, switch=args.switch, as_json=j
+        ),
+        "down": lambda: commands.cmd_down(
+            root,
+            mf,
+            scope=args.scope,
+            target=args.target,
+            all_instances=args.all_instances,
+            as_json=j,
+        ),
+        "status": lambda: commands.cmd_status(root, mf, as_json=j),
+        "ps": lambda: commands.cmd_ps(
+            health=args.health, as_json=j, wide=getattr(args, "wide", False)
+        ),
+        "ls": lambda: commands.cmd_ps(
+            health=args.health, as_json=j, wide=getattr(args, "wide", False)
+        ),
+        "list": lambda: commands.cmd_ps(
+            health=args.health, as_json=j, wide=getattr(args, "wide", False)
+        ),
+        "prune": lambda: commands.cmd_prune(force=args.force, as_json=j),
+        "check": lambda: commands.cmd_check(root, mf, mode=args.mode, as_json=j),
+        "init": lambda: commands.cmd_init(
+            root, dry_run=args.dry_run, force=args.force, up=args.up, as_json=j
+        ),
+        "schema": lambda: commands.cmd_schema(as_json=j),
+        "logs": lambda: commands.cmd_logs(
+            root, mf, service=args.service, tail=args.tail, mode=args.mode, as_json=j
+        ),
+    }
+    action = dispatch.get(cmd)
+    return action() if action else constants.EXIT_OK
+
+
+def _print_rig_error(exc: RigError) -> None:
+    th = get_theme()
+    print(format_human_error(exc, th), end="", file=sys.stderr)
+
+
+def _handle_exception(exc: Exception, cmd: str, as_json: bool) -> int:
+    if isinstance(exc, RigError):
+        if as_json:
+            print_json_error(exc, command=cmd)
+        else:
+            _print_rig_error(exc)
+        return exc.exit_code
+    if isinstance(exc, TimeoutError):
+        err = RigError(str(exc), code="E_LOCK_TIMEOUT", exit_code=constants.EXIT_MUTEX_CONFLICT)
+        return _handle_exception(err, cmd, as_json)
+    if isinstance(exc, KeyboardInterrupt):
+        err = RigError(
+            "operation cancelled by user",
+            code="E_INTERRUPTED",
+            exit_code=constants.EXIT_INTERRUPTED,
+        )
+        return _handle_exception(err, cmd, as_json)
+    err = RigError(
+        f"unexpected error: {exc}", code="E_INTERNAL", exit_code=constants.EXIT_OP_FAILED
+    )
+    return _handle_exception(err, cmd, as_json)
+
+
+def _prepare_args(args: argparse.Namespace, as_json: bool) -> None:
+    args.as_json = as_json
+    r_arg = getattr(args, "root", None)
+    args.root_dir = Path(r_arg).resolve() if r_arg else find_project_root()
+    m_arg = getattr(args, "manifest", None)
+    args.manifest_file = Path(m_arg).resolve() if m_arg else find_default_manifest(args.root_dir)

rig/commands/down/__init__.py

@@ -0,0 +1,139 @@
+"""Teardown command for stopping individual checkouts or all machine instances."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from rig.commands.common import (
+    _merged_depends_on,
+    _stop_record,
+    reverse_dependency_order,
+)
+from rig.commands.down.runner import down_checkout
+from rig.core.constants import (
+    EXIT_NOT_FOUND,
+    EXIT_OK,
+    EXIT_OP_FAILED,
+    LOCK_FILE_NAME,
+    STATE_FILE_NAME,
+)
+from rig.core.errors import RigError, print_json_envelope
+from rig.core.identity import get_instances_dir
+from rig.core.locks import exclusive_lock
+from rig.core.state import read_state, write_state
+
+
+def _stop_instance_records(
+    services: dict[str, Any], root: Path, state: dict[str, Any]
+) -> tuple[list[str], list[str]]:
+    stopped, failed, failed_svcs = [], [], set()
+    for name in reverse_dependency_order(services):
+        if deps := [d for d in failed_svcs if name in _merged_depends_on(d, services[d])]:
+            failed.append(f"{name}: refused (needed by running dependent {', '.join(deps)})")
+            failed_svcs.add(name)
+            continue
+        outcome = _stop_record(services[name], root)
+        if outcome in ("terminated", "killed", "stale"):
+            state["services"].pop(name, None)
+            stopped.append(name)
+        else:
+            failed_svcs.add(name)
+            failed.append(f"{name}: {outcome}")
+    return stopped, failed
+
+
+def _stop_instance(inst_dir: Path) -> dict[str, Any]:
+    state_file = inst_dir / STATE_FILE_NAME
+    if not state_file.exists():
+        return {"instance": inst_dir.name, "status": "no_state", "stopped": [], "failed": []}
+    with exclusive_lock(inst_dir / LOCK_FILE_NAME):
+        state = read_state(state_file)
+        root = Path(state["root"]).resolve() if state.get("root") else inst_dir
+        stopped, failed = _stop_instance_records(dict(state.get("services", {})), root, state)
+        state["generation"] = int(state.get("generation", 0)) + 1
+        write_state(state_file, state)
+        proj = state.get("project", inst_dir.name)
+        return {"instance": inst_dir.name, "project": proj, "stopped": stopped, "failed": failed}
+
+
+def _down_all_instances(as_json: bool) -> int:
+    instances_dir = get_instances_dir()
+    if not instances_dir.is_dir():
+        if as_json:
+            print_json_envelope("down", {"instances": [], "all": True})
+        else:
+            print("No active rig instances to stop.")
+        return EXIT_OK
+    results = [
+        _stop_instance(d)
+        for d in sorted(instances_dir.iterdir())
+        if d.is_dir() and (d / STATE_FILE_NAME).is_file()
+    ]
+    failed_any = any(r.get("failed") for r in results)
+    if as_json:
+        print_json_envelope("down", {"instances": results, "all": True}, ok=not failed_any)
+    return EXIT_OP_FAILED if failed_any else EXIT_OK
+
+
+def _matches_target(d: Path, target: str) -> bool:
+    if not (d.is_dir() and (d / STATE_FILE_NAME).is_file()):
+        return False
+    proj = read_state(d / STATE_FILE_NAME).get("project") or d.name.rsplit("-", 1)[0]
+    return target.lower() in (d.name.lower(), proj.lower()) or d.name == target
+
+
+def _find_matching_instances(instances_dir: Path, target: str) -> list[Path]:
+    if not instances_dir.is_dir():
+        return []
+    return [d for d in sorted(instances_dir.iterdir()) if _matches_target(d, target)]
+
+
+def _find_target(target: str) -> Path:
+    matched = _find_matching_instances(get_instances_dir(), target)
+    if not matched:
+        msg = f"no instance found matching {target!r}"
+        head = f"No active or recorded instance matches {target!r}"
+        hint = "Check running instances with 'rig ps'"
+        raise RigError(msg, code="E_NOT_FOUND", exit_code=EXIT_NOT_FOUND, headline=head, hint=hint)
+    if len(matched) > 1:
+        names = ", ".join(d.name for d in matched)
+        msg = f"ambiguous target {target!r}; matches: {names}"
+        head = f"Multiple instances match {target!r}"
+        ctx = f"Matching instances:\n{names}"
+        hint = "Specify the full instance identifier (e.g. from 'rig ps')"
+        raise RigError(
+            msg,
+            code="E_AMBIGUOUS",
+            exit_code=EXIT_NOT_FOUND,
+            headline=head,
+            context=ctx,
+            hint=hint,
+        )
+    return matched[0]
+
+
+def cmd_down(
+    root: Path | None = None,
+    manifest_path: Path | None = None,
+    scope: str = "full",
+    *args: Any,
+    **kwargs: Any,
+) -> int:
+    argv = list(args)
+    target = kwargs.get("target") or (argv.pop(0) if argv else None)
+    all_inst = bool(kwargs.get("all_instances") or (argv.pop(0) if argv else False))
+    as_json = bool(kwargs.get("as_json") or (argv.pop(0) if argv else False))
+    if all_inst:
+        return _down_all_instances(as_json)
+    if target:
+        res = _stop_instance(_find_target(target))
+        if as_json:
+            print_json_envelope("down", res, ok=not res.get("failed"))
+        return EXIT_OP_FAILED if res.get("failed") else EXIT_OK
+    if root and manifest_path:
+        return down_checkout(root, manifest_path, scope, as_json=as_json)
+    return EXIT_OK
+
+
+__all__ = ["_down_all_instances", "_find_target", "_stop_instance", "cmd_down", "down_checkout"]