procd 1.0.0__tar.gz

procd-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

procd-1.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: procd
+Version: 1.0.0
+Summary: The Native Stack Runner. Orchestration Without Containers.
+Keywords: 
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Dist: cryptography>=46.0.7
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pyshortcuts>=1.9.7
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: rich>=15.0.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Procd
+The Native Stack Runner. Orchestration Without Containers.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)

procd-1.0.0/README_PYPI.md

@@ -0,0 +1,4 @@
+# Procd
+The Native Stack Runner. Orchestration Without Containers.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)

procd-1.0.0/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "procd"
+version = "1.0.0"
+description = "The Native Stack Runner. Orchestration Without Containers."
+readme = "README_PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "alpine" },
+]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=46.0.7",
+    "inquirerpy>=0.3.4",
+    "psutil>=7.2.2",
+    "pyshortcuts>=1.9.7",
+    "python-dotenv>=1.2.2",
+    "rich>=15.0.0",
+]
+
+
+[project.scripts]
+procd = "procd.cli:main"
+
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]
+
+
+[tool.uv]
+package = true
+
+
+[tool.ruff]
+# https://docs.astral.sh/ruff/configuration/
+src = ["src"]
+
+[tool.ruff.lint]
+# https://docs.astral.sh/ruff/rules/
+select = [
+    # pycodestyle (E, W)
+    "E2",
+    "E4",
+    "E7",
+    "E9",
+    "W",
+
+    # Pyflakes (F)
+    "F",
+
+    # flake8-no-pep420 (INP)
+    "INP",
+
+    # pep8-naming (N)
+    #"N",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"docker/*.py" = ["INP"]
+"scripts/*.py" = ["INP"]
+"tests/*.py" = ["INP"]
+"var/*.py" = ["INP"]
+
+
+[tool.pytest.ini_options]
+cache_dir = "var/.pytest_cache"
+
+
+[tool.coverage.run]
+source = ["src"]
+data_file = "var/.coverage"
+omit = [
+    "tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

procd-1.0.0/src/procd/__init__.py

@@ -0,0 +1,3 @@
+from .supervisor import Supervisor
+
+__all__ = ["Supervisor"]

procd-1.0.0/src/procd/_expand.py

@@ -0,0 +1,20 @@
+"""@{VAR} / @{VAR:-default} 展開の共通実装。"""
+from __future__ import annotations
+
+import re
+
+_AT_BRACE_RE = re.compile(r"@\{([^}]+)\}")
+
+
+def resolve_var(key: str, mapping: dict[str, str]) -> str:
+    """@{VAR} または @{VAR:-default} を mapping で解決する。"""
+    if ":-" in key:
+        var, default = key.split(":-", 1)
+        val = mapping.get(var)
+        return val if val is not None and val != "" else default
+    return mapping.get(key, f"@{{{key}}}")
+
+
+def expand(s: str, mapping: dict[str, str]) -> str:
+    """mapping で @{VAR} / @{VAR:-default} を展開する。未定義キーはそのまま残す。"""
+    return _AT_BRACE_RE.sub(lambda m: resolve_var(m.group(1), mapping), s)

procd-1.0.0/src/procd/_logger.py

@@ -0,0 +1,41 @@
+"""
+サービスの stdout をリアルタイムで JSONL に書き出すラッパープロセス。
+
+使い方（procd 内部から呼ばれる）:
+    <service> | python -m procd._logger <tag> <jsonl_path>
+
+サービスが終了すると stdin が閉じ、このプロセスも自然に終了する。
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import sys
+
+
+def run(tag: str, output_file: str) -> None:
+    with open(output_file, mode="a", encoding="utf-8", buffering=1) as f:
+        for line in sys.stdin:
+            clean_line = line.rstrip("\n\r")
+            if not clean_line:
+                continue
+            entry = {
+                "t": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="milliseconds"),
+                "s": tag,
+                "m": clean_line,
+            }
+            try:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+                f.flush()
+            except Exception as e:
+                print(f"[procd._logger] {e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: <command> | python -m procd._logger <tag> <jsonl_path>", file=sys.stderr)
+        sys.exit(1)
+    try:
+        run(sys.argv[1], sys.argv[2])
+    except KeyboardInterrupt:
+        pass

procd-1.0.0/src/procd/builtin.py

@@ -0,0 +1,415 @@
+"""
+Zeus 組み込みコマンド (@mkdir, @remove, @copy, @move, @extract, @get, @run, @read, @echo, @select, @set, @enc, @dec)
+
+steps の行が @ で始まる場合にこのモジュールが処理する。
+Python 標準ライブラリのみ使用するためクロスプラットフォームで動作する。
+ただし @enc / @dec は cryptography パッケージを使用する（OpenSSL AES-256-CBC 互換、改ざん検知なし）。
+"""
+from __future__ import annotations
+
+import shlex
+import shutil
+import tarfile
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Console
+
+from . import download as dl_mod
+
+_console = Console()
+_err_console = Console(stderr=True)
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class Cancelled(SystemExit):
+    """ユーザーが対話入力をキャンセルしたときに送出する。終了コード 130（Ctrl+C 相当）。"""
+    def __init__(self) -> None:
+        super().__init__(130)
+
+
+def run(cmd: str, conf: "Config | None" = None, runtime_env: "dict[str, str] | None" = None, extra_env: "dict[str, str] | None" = None, step_runner: "Any | None" = None) -> None:
+    """@ 始まりのコマンド文字列を実行する。"""
+    parts = shlex.split(cmd[1:])  # 先頭の @ を除いて分割
+    if not parts:
+        raise ValueError("Empty built-in command")
+
+    name, args = parts[0], parts[1:]
+
+    if name == "echo":
+        # "off" / "on" control step-echo mode via runtime_env
+        if len(args) == 1 and args[0].lower() in ("off", "on"):
+            if runtime_env is not None:
+                runtime_env["__echo__"] = args[0].lower()
+            return
+        # Extract raw text preserving internal whitespace
+        raw_parts = cmd[1:].split(None, 1)
+        print(raw_parts[1] if len(raw_parts) > 1 else "")
+
+    elif name == "mkdir":
+        for p in args:
+            Path(p).mkdir(parents=True, exist_ok=True)
+            _console.print(f"[dim]mkdir {p}[/dim]")
+
+    elif name == "remove":
+        for p in args:
+            path = Path(p)
+            if path.is_dir():
+                shutil.rmtree(path)
+            elif path.exists():
+                path.unlink()
+            _console.print(f"[dim]remove {p}[/dim]")
+
+    elif name == "copy":
+        if len(args) != 2:
+            raise ValueError("@copy <src> <dst>")
+        shutil.copy2(args[0], args[1])
+        _console.print(f"[dim]copy {args[0]} -> {args[1]}[/dim]")
+
+    elif name in ("move", "mv"):
+        if len(args) < 2:
+            raise ValueError("@move <src> [src ...] <dst>")
+        import glob as glob_mod
+        _GLOB_CHARS = frozenset("*?[")
+        *src_patterns, dst_str = args
+        dst = Path(dst_str)
+        dst_is_dir = dst_str.endswith("/") or dst_str.endswith("\\")
+        if dst_is_dir and not dst.exists():
+            dst.mkdir(parents=True, exist_ok=True)
+        srcs: list[Path] = []
+        for pat in src_patterns:
+            if _GLOB_CHARS.intersection(pat):
+                matched = sorted(glob_mod.glob(pat, recursive=True))
+                srcs.extend(Path(m) for m in matched)
+            else:
+                srcs.append(Path(pat))
+        if len(srcs) > 1 and not dst.is_dir():
+            raise ValueError(f"@move: destination must be a directory when moving multiple files: {dst_str}")
+        for src in srcs:
+            shutil.move(str(src), str(dst))
+            _console.print(f"[dim]move {src} -> {dst_str}[/dim]")
+
+    elif name == "extract":
+        if len(args) != 2:
+            raise ValueError("@extract <file> <dest>")
+        src, dest_str = args[0], args[1]
+        dest = Path(dest_str)
+        dest.mkdir(parents=True, exist_ok=True)
+        src_lower = src.lower()
+        from rich.progress import Progress, SpinnerColumn, TextColumn
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=_console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task(f"extracting {Path(src).name} ...")
+            if src_lower.endswith(".zip"):
+                with zipfile.ZipFile(src) as zf:
+                    for member in zf.infolist():
+                        progress.update(task, description=f"extracting {member.filename}")
+                        zf.extract(member, dest)
+            elif any(src_lower.endswith(ext) for ext in (".tar.gz", ".tgz", ".tar.bz2", ".tar.xz")):
+                with tarfile.open(src) as tf:
+                    for member in tf.getmembers():
+                        progress.update(task, description=f"extracting {member.name}")
+                        tf.extract(member, dest)
+            else:
+                raise ValueError(f"@extract: unsupported format: {src}")
+        _console.print(f"[dim]extract {src} -> {dest_str}[/dim]")
+
+    elif name == "read":
+        if len(args) < 1:
+            raise ValueError("@read <VAR> [prompt...]")
+        if runtime_env is None:
+            raise RuntimeError("@read requires a runtime context")
+        var = args[0]
+        # shlex.split strips trailing spaces, so extract the prompt from the raw string.
+        # cmd[1:] strips the leading '@', then split(None, 2) gives ["read", "VAR", "raw prompt"].
+        raw_parts = cmd[1:].split(None, 2)
+        prompt = raw_parts[2] if len(raw_parts) > 2 else ""
+        value = input(prompt)
+        runtime_env[var] = value
+
+    elif name == "get":
+        if len(args) < 1:
+            raise ValueError("@get <name> [name ...]")
+        if conf is None:
+            raise RuntimeError("@get requires config")
+        if len(args) == 1:
+            _do_get(args[0], conf)
+        else:
+            dl_mod.do_get_parallel(list(args), conf)
+
+    elif name == "run":
+        if len(args) != 1:
+            raise ValueError("@run <name>")
+        if conf is None:
+            raise RuntimeError("@run requires config")
+        _do_run(args[0], conf, runtime_env, parent_env=extra_env, step_runner=step_runner)
+
+    elif name == "up":
+        if len(args) < 1:
+            raise ValueError("@up <name> [name ...]")
+        if conf is None:
+            raise RuntimeError("@up requires config")
+        for svc_name in args:
+            _do_up(svc_name, conf)
+
+    elif name == "down":
+        if len(args) < 1:
+            raise ValueError("@down <name> [name ...]")
+        if conf is None:
+            raise RuntimeError("@down requires config")
+        for svc_name in args:
+            _do_down(svc_name, conf)
+
+    elif name == "select":
+        if len(args) < 2:
+            raise ValueError("@select <VAR> <token>...")
+        if runtime_env is None:
+            raise RuntimeError("@select requires a runtime context")
+        runtime_env[args[0]] = _do_select(args[0], args[1:], project_dir=conf.project_dir if conf else None)
+
+    elif name == "set":
+        # @set <VAR> <value> [s/<pattern>/<replacement>/[flags]]
+        if len(args) < 2 or len(args) > 3:
+            raise ValueError("@set <VAR> <value> [s/<pattern>/<replacement>/[flags]]")
+        if runtime_env is None:
+            raise RuntimeError("@set requires a runtime context")
+        value = args[1]
+        if len(args) == 3:
+            value = _apply_substitution(value, args[2])
+        runtime_env[args[0]] = value
+
+    elif name == "enc":
+        # @enc <passfile> <src> <dest>
+        if len(args) != 3:
+            raise ValueError("@enc <passfile> <src> <dest>")
+        _do_enc(pass_file=args[0], src=args[1], dest=args[2])
+
+    elif name == "dec":
+        # @dec <passfile> <src> <dest>
+        if len(args) != 3:
+            raise ValueError("@dec <passfile> <src> <dest>")
+        _do_dec(pass_file=args[0], src=args[1], dest=args[2])
+
+    else:
+        raise ValueError(f"Unknown built-in command: @{name}")
+
+
+# ---------------------------------------------------------------------------
+# set  (変数代入・正規表現置換)
+# ---------------------------------------------------------------------------
+
+def _apply_substitution(value: str, expr: str) -> str:
+    """s/<pattern>/<replacement>/[flags] 形式の正規表現置換を value に適用する。
+    flags: i = 大小文字無視, g = 全置換（省略時は最初の1箇所のみ）。
+    パターン・置換文字列内の \\/ は / のエスケープとして扱う。
+    """
+    import re
+    if not expr.startswith("s/"):
+        raise ValueError(f"@set: 置換式は s/<pattern>/<replacement>/[flags] の形式にしてください: {expr!r}")
+
+    # \/ をエスケープとして扱いながら / で最大2分割するパーサー
+    inner = expr[2:]
+    parts: list[str] = []
+    current: list[str] = []
+    i = 0
+    while i < len(inner):
+        if inner[i] == "\\" and i + 1 < len(inner) and inner[i + 1] == "/":
+            current.append("\\/")
+            i += 2
+        elif inner[i] == "/":
+            parts.append("".join(current))
+            current = []
+            i += 1
+            if len(parts) == 2:
+                parts.append(inner[i:])  # 残りはすべて flags
+                break
+        else:
+            current.append(inner[i])
+            i += 1
+    if len(parts) < 2:
+        parts.append("".join(current))
+    while len(parts) < 3:
+        parts.append("")
+
+    pattern, replacement, flags_str = parts[0], parts[1], parts[2]
+    re_flags, count = 0, 1
+    for f in flags_str:
+        if f == "i":
+            re_flags |= re.IGNORECASE
+        elif f == "g":
+            count = 0  # 0 = すべて置換
+    return re.sub(pattern, replacement, value, count=count, flags=re_flags)
+
+
+# ---------------------------------------------------------------------------
+# enc / dec  (OpenSSL AES-256-CBC 互換、改ざん検知なし)
+# ---------------------------------------------------------------------------
+
+_OPENSSL_MAGIC = b"Salted__"
+
+
+def _evp_bytes_to_key(password: bytes, salt: bytes) -> tuple[bytes, bytes]:
+    """EVP_BytesToKey (SHA-256, 1 iteration) → (key: 32 bytes, iv: 16 bytes)."""
+    import hashlib
+    d, d_i = b"", b""
+    while len(d) < 48:  # 32 (AES-256 key) + 16 (IV)
+        d_i = hashlib.sha256(d_i + password + salt).digest()
+        d += d_i
+    return d[:32], d[32:48]
+
+
+def _do_enc(pass_file: str, src: str, dest: str) -> None:
+    """AES-256-CBC で暗号化。OpenSSL `Salted__` フォーマット互換。"""
+    import os
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    from cryptography.hazmat.primitives import padding
+
+    password = Path(pass_file).read_bytes().splitlines()[0]  # 1行目のみ（openssl互換）
+    salt = os.urandom(8)
+    key, iv = _evp_bytes_to_key(password, salt)
+
+    padder = padding.PKCS7(128).padder()
+    plaintext = padder.update(Path(src).read_bytes()) + padder.finalize()
+
+    encryptor = Cipher(algorithms.AES(key), modes.CBC(iv)).encryptor()
+    ciphertext = encryptor.update(plaintext) + encryptor.finalize()
+
+    Path(dest).write_bytes(_OPENSSL_MAGIC + salt + ciphertext)
+    _console.print(f"[dim]enc {src} -> {dest}[/dim]")
+
+
+def _do_dec(pass_file: str, src: str, dest: str) -> None:
+    """AES-256-CBC で復号。OpenSSL `Salted__` フォーマット互換。"""
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    from cryptography.hazmat.primitives import padding
+
+    raw = Path(src).read_bytes()
+    if not raw.startswith(_OPENSSL_MAGIC):
+        raise ValueError(f"@dec: OpenSSL Salted__ ヘッダが見つかりません: {src}")
+
+    salt = raw[8:16]
+    ciphertext = raw[16:]
+    password = Path(pass_file).read_bytes().splitlines()[0]
+    key, iv = _evp_bytes_to_key(password, salt)
+
+    decryptor = Cipher(algorithms.AES(key), modes.CBC(iv)).decryptor()
+    padded = decryptor.update(ciphertext) + decryptor.finalize()
+
+    unpadder = padding.PKCS7(128).unpadder()
+    data = unpadder.update(padded) + unpadder.finalize()
+
+    Path(dest).write_bytes(data)
+    _console.print(f"[dim]dec {src} -> {dest}[/dim]")
+
+
+# ---------------------------------------------------------------------------
+
+def _do_get(name: str, conf: "Config", force: bool = False) -> None:
+    dl_mod.do_get(name, conf, force=force)
+
+
+def _do_run(name: str, conf: "Config", runtime_env: "dict[str, str] | None" = None, parent_env: "dict[str, str] | None" = None, step_runner: "Any | None" = None) -> None:
+    """@run の実装。別コマンドの steps を再帰実行する。"""
+    if name not in conf.commands:
+        raise ValueError(f"@run: unknown command: {name}")
+    cmd = conf.commands[name]
+    label = f"[dim]{name}[/dim]" + (f"[dim]  {cmd.description}[/dim]" if cmd.description else "")
+    _console.rule(label, style="dim")
+    # 環境変数マージ: 親の env を下敷きにして、子の cmd.env で上書き
+    merged_env: dict[str, str] = {**(parent_env or {}), **(cmd.env or {})}
+    # @set / @select の変数スコープは子コマンド内で独立させる
+    child_runtime_env: dict[str, str] = {}
+    total = len(cmd.steps)
+    for i, step in enumerate(cmd.steps):
+        prefix = f"  [cyan][{i + 1}/{total}][/cyan] "
+        if step_runner is not None:
+            code = step_runner(
+                step, conf,
+                extra_env=merged_env if merged_env else None,
+                shell=cmd.shell,
+                prefix=prefix,
+                interactive=cmd.interactive,
+                runtime_env=child_runtime_env,
+            )
+            if code != 0:
+                raise RuntimeError(f"Step failed (exit code {code}): {step}")
+        else:
+            # フォールバック: step_runner なしでの直接実行（@run が cli 外から呼ばれた場合）
+            if step.startswith("@"):
+                run(step, conf, child_runtime_env, extra_env=merged_env if merged_env else None)
+            else:
+                import subprocess as _sp
+                result = _sp.run(shlex.split(step))
+                if result.returncode != 0:
+                    raise RuntimeError(f"Step failed (exit code {result.returncode}): {step}")
+
+
+def _do_up(name: str, conf: "Config") -> None:
+    """@up の実装。サービスをバックグラウンドで起動し ready まで待機する。"""
+    from . import process
+
+    if name not in conf.services:
+        raise ValueError(f"@up: unknown service: {name}")
+    if process.is_running(name):
+        _console.print(f"[dim][{name}] already running[/dim]")
+        return
+    svc = conf.services[name]
+    _console.print(f"[dim]starting {name}...[/dim]")
+    process.start(name, svc, detach=True, project_dir=conf.project_dir)
+    result = process.wait_ready(name, svc, project_dir=conf.project_dir)
+    if result is None:
+        raise RuntimeError(f"@up: {name} exited immediately")
+    if not result:
+        raise RuntimeError(f"@up: {name} timed out waiting for ready")
+    _console.print(f"[dim][{name}] ready (pid {process.read_pid(name)})[/dim]")
+
+
+def _do_down(name: str, conf: "Config") -> None:
+    """@down の実装。サービスを停止する。"""
+    from . import process
+
+    if name not in conf.services:
+        raise ValueError(f"@down: unknown service: {name}")
+    if process.stop(name):
+        _console.print(f"[dim]stopped {name}[/dim]")
+    else:
+        _console.print(f"[dim][{name}] was not running[/dim]")
+
+
+def _do_select(var: str, tokens: list[str], project_dir: "Path | None" = None) -> str:
+    """@select の実装。tokens を glob 展開またはリテラルとして候補を収集し InquirerPy fuzzy で選択させる。"""
+    import glob as glob_mod
+
+    from InquirerPy import inquirer
+
+    _GLOB_CHARS = frozenset("*?[")
+
+    candidates: list[str] = []
+    for token in tokens:
+        if _GLOB_CHARS.intersection(token):
+            matches = sorted(glob_mod.glob(token, root_dir=project_dir, recursive=True))
+            candidates.extend(Path(m).as_posix() for m in matches)
+        else:
+            candidates.append(token)
+
+    if not candidates:
+        _err_console.print(f"[bold red]Error:[/bold red] @select: no candidates for {tokens!r}")
+        raise SystemExit(1)
+
+    result = inquirer.fuzzy(
+        message=f"Select {var}:",
+        choices=candidates,
+        max_height="40%",
+    ).execute()
+
+    if result is None:
+        raise Cancelled()
+
+    return result