interlocking 0.1.0__tar.gz → 0.2.1__tar.gz

interlocking-0.2.1/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: interlocking
+Version: 0.2.1
+Summary: A lightweight task dispatcher with explicit control.
+Keywords: task-runner,batch,exclusive-lock,cli,mutex,distributed-lock
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Utilities
+Requires-Dist: boto3>1.40.0,<2 ; extra == 'aws'
+Requires-Python: >=3.11
+Provides-Extra: aws
+Description-Content-Type: text/markdown
+
+# Interlocking
+
+> One track, one train.  
+> Easy to run. Explicit to control.
+
+Interlocking is a framework for managing background task execution in distributed environments.
+The name comes from the railway interlocking system, which prevents two trains from entering the same track at the same time. Exclusive control is at the core of the library.
+Using a railway metaphor, it manages the lifecycle of batch tasks (exclusive control, run records, and CLI integration) in a single, consistent way.
+
+## Features
+
+- **Exclusive control**: The same task never runs concurrently.
+- **Run records**: Stores the result of the most recent run and hands it over to the next one (`Coupler`).
+- **CLI integration**: Builds a command line from type hints and reports the result through the exit code.
+- **Pluggable**: Extend behavior with a `Station` (storage backend) or `TrainMiddleware`.
+
+## Installation
+
+```bash
+pip install interlocking
+```
+
+To use S3 as the storage backend:
+
+```bash
+pip install "interlocking[aws]"
+```
+
+Requires Python 3.11 or later.
+
+## Quick start
+
+```python
+# tasks.py
+from typing import Annotated
+from interlocking import Line, Coupler
+
+line = Line()
+
+@line.track(name="daily", help="Daily job")
+def daily_task(c: Coupler, target_date: Annotated[str, "Target date (YYYY-MM-DD)"]) -> dict:
+    last_id = c.last_data.get("last_id", 0)
+    # ... do the work ...
+    return {"last_id": 9999}
+```
+
+```python
+# main.py
+import sys
+
+from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
+
+dispatcher = TrainDispatcher(
+    station=LocalStation(base_path=".interlocking"),
+    lines={"batch": "tasks:line"},
+)
+
+cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="Batch tasks")
+sys.exit(cli.execute(cli.parse_args()))  # report the result via exit code
+```
+
+```bash
+# `start` makes the intent to run explicit: without it, nothing runs
+python main.py start batch daily --target-date 2026-04-01
+
+# Release a stuck lock (a separate management operation)
+python main.py abort batch daily
+```
+
+## License
+
+MIT

interlocking-0.2.1/README.md

@@ -0,0 +1,72 @@
+# Interlocking
+
+> One track, one train.  
+> Easy to run. Explicit to control.
+
+Interlocking is a framework for managing background task execution in distributed environments.
+The name comes from the railway interlocking system, which prevents two trains from entering the same track at the same time. Exclusive control is at the core of the library.
+Using a railway metaphor, it manages the lifecycle of batch tasks (exclusive control, run records, and CLI integration) in a single, consistent way.
+
+## Features
+
+- **Exclusive control**: The same task never runs concurrently.
+- **Run records**: Stores the result of the most recent run and hands it over to the next one (`Coupler`).
+- **CLI integration**: Builds a command line from type hints and reports the result through the exit code.
+- **Pluggable**: Extend behavior with a `Station` (storage backend) or `TrainMiddleware`.
+
+## Installation
+
+```bash
+pip install interlocking
+```
+
+To use S3 as the storage backend:
+
+```bash
+pip install "interlocking[aws]"
+```
+
+Requires Python 3.11 or later.
+
+## Quick start
+
+```python
+# tasks.py
+from typing import Annotated
+from interlocking import Line, Coupler
+
+line = Line()
+
+@line.track(name="daily", help="Daily job")
+def daily_task(c: Coupler, target_date: Annotated[str, "Target date (YYYY-MM-DD)"]) -> dict:
+    last_id = c.last_data.get("last_id", 0)
+    # ... do the work ...
+    return {"last_id": 9999}
+```
+
+```python
+# main.py
+import sys
+
+from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
+
+dispatcher = TrainDispatcher(
+    station=LocalStation(base_path=".interlocking"),
+    lines={"batch": "tasks:line"},
+)
+
+cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="Batch tasks")
+sys.exit(cli.execute(cli.parse_args()))  # report the result via exit code
+```
+
+```bash
+# `start` makes the intent to run explicit: without it, nothing runs
+python main.py start batch daily --target-date 2026-04-01
+
+# Release a stuck lock (a separate management operation)
+python main.py abort batch daily
+```
+
+## License
+
+MIT

{interlocking-0.1.0 → interlocking-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "interlocking"
-version = "0.1.0"
+version = "0.2.1"
 description = "A lightweight task dispatcher with explicit control."
 readme = "README.md"
 requires-python = ">=3.11"

{interlocking-0.1.0 → interlocking-0.2.1}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "interlocking"
-version = "0.1.0"
+version = "0.2.1"
 description = "A lightweight task dispatcher with explicit control."
 readme = "README.md"
 requires-python = ">=3.11"

{interlocking-0.1.0 → interlocking-0.2.1}/src/interlocking/__init__.py

@@ -12,7 +12,7 @@ Easy to run. Explicit to control.
     from interlocking import Line, Coupler
     from interlocking import InterlockingCLI, TrainDispatcher, LocalStation
 """
-from .cli import ExitCode, InterlockingCLI
+from .cli import CliRequest, ExitCode, InterlockingCLI
 from .dispatcher import Train, TrainDispatcher, TrainMiddleware
 from .line import Line
 from .models import (
@@ -20,6 +20,7 @@ from .models import (
     SignalBlockedError,
     SignalStatus,
     StaleLockError,
+    TrainPlan,
     TrainRecord,
     TrainResult,
 )
@@ -28,6 +29,7 @@ from .station import LocalStation, S3Station, Station
 __all__ = [
     # CLI ビルダー
     "InterlockingCLI",
+    "CliRequest",
     "ExitCode",
     # 路線定義（Router）
     "Line",
@@ -35,6 +37,7 @@ __all__ = [
     "Coupler",
     "TrainRecord",
     "TrainResult",
+    "TrainPlan",
     # ディスパッチャー
     "Train",
     "TrainDispatcher",

interlocking-0.2.1/src/interlocking/cli.py

@@ -0,0 +1,426 @@
+"""
+interlocking.cli
+===========
+interlocking を使った CLI の共通ビルダー。
+
+動詞を先頭に置く（ADR-0007）。``start`` は実行を明示するガード、``abort`` は別の管理操作::
+
+    main.py start batch daily --target-date 2026-04-01 --force
+    main.py abort batch daily
+
+argparse の2ステップインターフェースに準拠する::
+
+    cli = InterlockingCLI(
+        dispatcher=dispatcher,
+        prog="sails-task2",
+        description="SAILSタスク実行コマンド",
+    )
+    request = cli.parse_args()           # パーサー構築 + 引数解析（CliRequest を返す）
+    context.setup_logging(...)           # 起動時処理は、ここに書く
+    sys.exit(cli.execute(request))       # タスク実行。結果を終了コード（ExitCode）で返す
+"""
+from __future__ import annotations
+
+import argparse
+import inspect
+import json
+import sys
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Literal,
+    Optional,
+    Tuple,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .dispatcher import TrainDispatcher, _check_reserved_params
+from .models import Coupler, TrainPlan, TrainResult
+
+DEFAULT_STALE_AFTER = 600
+OUTPUT_FORMATS = ("text", "json")
+
+
+class ExitCode(IntEnum):
+    """CLI の終了コード。cron など上位のオーケストレーターが結果を判別するための規約。"""
+
+    SUCCESS = 0
+    FAILED = 1   # タスクが失敗した（--dry-run では、判定できなかった）
+    USAGE = 2    # argparse の引数エラー（argparse が返す。interlocking はこの値を他の用途に使わない）
+    BLOCKED = 3  # 赤信号（他の列車が運行中）で実行されなかった
+    STALE = 4    # 前回ロックの残骸（stale）で実行されなかった。復旧が必要
+    SKIPPED = 5  # Middleware が実行を見送った
+
+
+def _exit_code(result: TrainResult) -> ExitCode:
+    """depart() の結果を終了コードに変換する。判断できないときは失敗扱いにする。"""
+    if result.status == "success":
+        return ExitCode.SUCCESS
+    if result.status == "blocked":
+        return ExitCode.STALE if result.is_stale else ExitCode.BLOCKED
+    if result.status == "skipped":
+        return ExitCode.SKIPPED
+    return ExitCode.FAILED
+
+
+def _plan_exit_code(plan: TrainPlan) -> ExitCode:
+    """plan() の予測を、本番を実行したときと同じ終了コードに変換する。判定できないときは失敗扱い（ADR-0008）。"""
+    return {
+        "ready": ExitCode.SUCCESS,
+        "blocked": ExitCode.BLOCKED,
+        "stale": ExitCode.STALE,
+    }.get(plan.outcome, ExitCode.FAILED)
+
+
+def _format_plan_text(plan: TrainPlan) -> str:
+    """TrainPlan を人が読む形に整形する。"""
+    last = plan.last_stop
+    lines = [
+        f"[DRY-RUN] {plan.track_id} （実行しません）",
+        f"outcome         : {plan.outcome}",
+        f"signal          : {plan.signal.value if plan.signal else '(未確認)'}",
+        f"first_departure : {plan.first_departure}",
+    ]
+    if not plan.first_departure:
+        lines.append(f"last stop       : {last.status}  run_id={last.run_id}  run_by={last.run_by}")
+        lines.append(f"last_data       : {json.dumps(last.data, ensure_ascii=False)}")
+    lines.append(f"params          : {json.dumps(plan.params, ensure_ascii=False)}")
+    lines.append(
+        f"options         : force={plan.force}  allow_stale_takeover={plan.allow_stale_takeover}"
+        f"  stale_after={plan.stale_after}  run_by={plan.run_by}"
+    )
+    lines.extend(f"note            : {note}" for note in plan.notes)
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class CliRequest:
+    """parse_args() の結果。execute() が受け取る、型のある入れ物。
+
+    ``command="start"`` は depart() の呼び出し内容、``command="abort"`` は abort() の呼び出し内容を表す。
+    利用者は parse_args() と execute() の間で、``dataclasses.replace()`` で加工できる。
+    組み合わせは構築時に検査する（abort では実行用の属性を指定できない）。
+
+    Attributes:
+        command:  ``"start"``（実行）または ``"abort"``（実行中フラグの強制解除）。
+        track_id: タスク識別子（"line_name:track_name" 形式）。
+        params:   タスク関数に渡す引数（start のみ）。
+        force:    True のとき信号確認をスキップする（start のみ）。
+        allow_stale_takeover: True のとき、stale なロックだけを引き継いで実行する（start のみ）。
+        stale_after: stale とみなす秒数（start のみ）。
+        run_id:   実行ID。None のとき自動生成する（start のみ。dry_run とは併用できない）。
+        run_by:   実行（操作）ユーザー名。None のとき OS ユーザー。
+        dry_run:  True のとき、タスクを呼ばずに実行の予測を標準出力に出す（start のみ）。
+        output:   dry_run の出力形式 ``"text"`` / ``"json"``。None のとき text（dry_run のみ）。
+    """
+
+    command: Literal["start", "abort"]
+    track_id: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    force: bool = False
+    allow_stale_takeover: bool = False
+    stale_after: int = DEFAULT_STALE_AFTER
+    run_id: Optional[str] = None
+    run_by: Optional[str] = None
+    dry_run: bool = False
+    output: Optional[Literal["text", "json"]] = None
+
+    def __post_init__(self) -> None:
+        if self.command not in ("start", "abort"):
+            raise ValueError(f"command は 'start' か 'abort' を指定してください: {self.command!r}")
+        if self.output is not None and self.output not in OUTPUT_FORMATS:
+            raise ValueError(f"output は {list(OUTPUT_FORMATS)} のいずれかを指定してください: {self.output!r}")
+        if self.command == "abort":
+            start_only = {
+                "params": bool(self.params),
+                "force": self.force,
+                "allow_stale_takeover": self.allow_stale_takeover,
+                "stale_after": self.stale_after != DEFAULT_STALE_AFTER,
+                "run_id": self.run_id is not None,
+                "dry_run": self.dry_run,
+                "output": self.output is not None,
+            }
+            invalid = sorted(name for name, specified in start_only.items() if specified)
+            if invalid:
+                raise ValueError(f"abort では {invalid} を指定できません（start のみの属性です）")
+        elif self.dry_run:
+            if self.run_id is not None:
+                raise ValueError("dry_run では run_id を指定できません（実行しないため）")
+        elif self.output is not None:
+            raise ValueError("output は dry_run のときだけ指定できます")
+
+
+# params の抄出時に除外する、InterlockingCLI 内部の dest とオプション名
+_CONTROL_KEYS: frozenset = frozenset({
+    "force", "allow_stale_takeover", "stale_after", "run_id", "run_by", "dry_run", "output",
+})
+# サブコマンドの dest。タスクの引数名と衝突しないよう、先頭に "_" を付ける
+_COMMAND, _LINE, _TRACK, _TRACK_ID = "_command", "_line", "_track", "_track_id"
+
+
+def _setup_argparsers(registry: Dict[str, Tuple[Callable, str]], parsers: Any, line_name: Optional[str] = None) -> None:
+    """路線 registry から argparse サブパーサーを構築する。
+
+    関数の型ヒント (Annotated[Type, "help"]) から引数定義を自動生成する。
+    Annotated でない引数（Coupler 以外）はエラーとなる。
+
+    Args:
+        registry:  TrainDispatcher.registry（line_name でフィルタ済みを推奨）。
+        parsers:   argparse の add_subparsers() の戻り値。
+        line_name: 指定時は "line_name:track_name" の track_name 部分をサブコマンド名にする。
+    """
+    for track_id, (func, help_text) in registry.items():
+        # InterlockingCLI 経由の場合は track_name 部分のみをサブコマンド名にする
+        display_name = track_id.split(":", 1)[1] if line_name and ":" in track_id else track_id
+        parser = parsers.add_parser(display_name, help=help_text)
+        parser.set_defaults(**{_TRACK_ID: track_id})
+
+        try:
+            type_hints = get_type_hints(func, include_extras=True)
+        except Exception:
+            type_hints = {}
+
+        sig = inspect.signature(func)
+        _check_reserved_params(track_id, sig.parameters)
+
+        for param_name, param in sig.parameters.items():
+            hint = param.annotation if param.annotation is not inspect.Parameter.empty else None
+            type_hint = type_hints.get(param_name)
+            if type_hint is not None:
+                hint = type_hint
+            if hint is None:
+                continue
+
+            is_coupler = False
+            try:
+                if hint is Coupler:
+                    is_coupler = True
+                elif hasattr(hint, '__name__') and hint.__name__ == 'Coupler':
+                    is_coupler = True
+                elif isinstance(hint, str) and hint == 'Coupler':
+                    is_coupler = True
+            except Exception:
+                pass
+            if is_coupler:
+                continue
+
+            origin = get_origin(hint)
+            has_metadata = hasattr(hint, '__metadata__')
+            import typing
+            is_annotated = (
+                has_metadata or
+                (origin is not None and (
+                    origin is getattr(typing, 'Annotated', None) or
+                    str(origin) == 'typing.Annotated'
+                ))
+            )
+            if not is_annotated:
+                raise TypeError(
+                    f"タスク '{track_id}' の引数 '{param_name}' には "
+                    f"Annotated[Type, 'ヘルプメッセージ'] が必要です。"
+                )
+
+            args = get_args(hint)
+            actual_type = args[0]
+            help_msg = hint.__metadata__[0] if hint.__metadata__ else ""
+            arg_required = param.default is inspect.Parameter.empty
+            arg_default = None if arg_required else param.default
+            # CLI フラグはケバブケース（--target-date）、params のキーは引数名（target_date）のまま
+            flag = f"--{param_name.replace('_', '-')}"
+            if actual_type is bool:
+                parser.add_argument(flag, dest=param_name, action="store_true", help=help_msg)
+            else:
+                # 必須の引数（デフォルトなし）が抜けたら、実行前に引数エラーにする
+                parser.add_argument(
+                    flag, dest=param_name, type=actual_type, default=arg_default,
+                    required=arg_required, help=help_msg,
+                )
+
+        parser.add_argument("--force", action="store_true", help="信号を無視して実行する（安全装置をすべて解除する）")
+        parser.add_argument(
+            "--allow-stale-takeover", dest="allow_stale_takeover", action="store_true",
+            help="stale（前回ロックの残骸）なロックだけを引き継いで実行する",
+        )
+        parser.add_argument(
+            "--stale-after", dest="stale_after", type=int, default=DEFAULT_STALE_AFTER,
+            help=f"この秒数が経過したロックを stale（前回ロックの残骸）とみなす (default={DEFAULT_STALE_AFTER})",
+        )
+        parser.add_argument("--run-by", dest="run_by", default=None, help="実行ユーザー名 (記録用)")
+        parser.add_argument("--run-id", dest="run_id", default=None, help="実行ID (記録用)")
+        parser.add_argument(
+            "--dry-run", dest="dry_run", action="store_true",
+            help="タスクを実行せず、実行したらどうなるか（信号・前回の状態・引数）を標準出力に出す",
+        )
+        parser.add_argument(
+            "--output", dest="output", choices=OUTPUT_FORMATS, default=None,
+            help="--dry-run の出力形式 (default=text)",
+        )
+
+
+class InterlockingCLI:
+    """interlocking CLI のビルダー。
+
+    動詞を先頭に置く（``start`` / ``abort``）。``start`` は実行を明示するガードで、動詞がなければ
+    何も実行されない（引数エラー）。``abort`` は別の管理操作で、実行用のオプションは持たない。
+
+    argparse の2ステップに準拠した設計:
+      parse_args() でパーサーを構築して引数を解析し（CliRequest を返す）、
+      execute() でタスクを実行する。
+
+    3フェーズでパーサーを構築する:
+      Phase 1 (Discovery): dispatcher.lines のキーだけでトップレベルパーサーを構成。
+      Phase 2 (Loading):   ``start`` で指定された路線のモジュールを import し line 属性を取得。
+                           line.register_to(dispatcher) でタスクを登録する。
+                           ``abort`` は路線を読み込まない（路線のモジュールが壊れていても復旧できる）。
+      Phase 3 (Mapping):   登録済みタスクから詳細パーサーを構築する。
+
+    Args:
+        dispatcher:      構築済みの TrainDispatcher。
+        prog:            CLI プログラム名（argparse の prog）。
+        description:     CLI の説明文。
+        version:         アプリの版。渡したときだけ ``--version`` が付き、``<prog> <version>`` を出す（ADR-0009）。
+    """
+
+    def __init__(
+        self,
+        dispatcher: TrainDispatcher,
+        prog: str = "interlocking",
+        description: str = "",
+        version: Optional[str] = None,
+    ) -> None:
+        self.dispatcher = dispatcher
+        self.prog = prog
+        self.description = description
+        self.version = version
+
+    def parse_args(self, argv: Optional[list] = None) -> CliRequest:
+        """パーサーを構築して引数を解析する。
+
+        argparse の parse_args() に相当するステップ。
+        戻り値の CliRequest を execute() に渡すことでタスクを実行する。
+        起動時処理（ログ設定など）や ``dataclasses.replace()`` による加工は、この間に行える。
+
+        Args:
+            argv: パース対象の引数リスト。None のとき sys.argv[1:] を使用。
+
+        Returns:
+            解析済みの CliRequest。引数エラーは argparse の標準動作で終了する（終了コード 2）。
+        """
+        _argv = list(argv) if argv is not None else sys.argv[1:]
+        lines = list(self.dispatcher.lines)
+
+        root = argparse.ArgumentParser(prog=self.prog, description=self.description)
+        if self.version is not None:
+            # argparse は version を % 書式で展開するので、利用者の文字列の % はエスケープする
+            escaped = self.version.replace("%", "%%")
+            root.add_argument("--version", action="version", version=f"%(prog)s {escaped}")
+        commands = root.add_subparsers(dest=_COMMAND, required=True, metavar="{start,abort}")
+
+        # Phase 1: 路線名だけでパーサーを構成（import なし）
+        start = commands.add_parser("start", help="タスクを実行する（実行を明示するガード）")
+        line_subparsers = start.add_subparsers(dest=_LINE, required=True, metavar="line", help="line name")
+        line_parsers: Dict[str, argparse.ArgumentParser] = {
+            line: line_subparsers.add_parser(line) for line in lines
+        }
+
+        # Phase 2: start で指定された路線だけをロードし登録
+        if len(_argv) >= 2 and _argv[0] == "start" and _argv[1] in line_parsers:
+            self.dispatcher.load_line(_argv[1])
+
+        # Phase 3: 登録済みタスクから詳細パーサーを構築。路線別にフィルタして track_name だけをサブコマンド名にする。
+        for line, lp in line_parsers.items():
+            track_subparsers = lp.add_subparsers(dest=_TRACK, required=True, metavar="track", help="タスク名")
+            line_registry = {
+                track_id: entry
+                for track_id, entry in self.dispatcher.registry.items()
+                if track_id.startswith(f"{line}:")
+            }
+            _setup_argparsers(line_registry, track_subparsers, line)
+
+        # abort は実行とは別の管理操作。路線は lines のキーで検証し、Track は文字列のまま受け取る。
+        abort = commands.add_parser("abort", help="実行中フラグを強制解除する（管理操作）")
+        abort.add_argument(_LINE, metavar="line", choices=lines, help="line name")
+        abort.add_argument(_TRACK, metavar="track", help="タスク名")
+        abort.add_argument("--run-by", dest="run_by", default=None, help="操作ユーザー名 (記録用)")
+
+        try:
+            return self._to_request(root.parse_args(_argv))
+        except ValueError as e:  # CliRequest の組み合わせ検査（例: --output だけの指定）
+            root.error(str(e))
+
+    @staticmethod
+    def _to_request(ns: argparse.Namespace) -> CliRequest:
+        """argparse の Namespace を CliRequest に変換する。"""
+        values = vars(ns)
+        if values[_COMMAND] == "abort":
+            return CliRequest(
+                command="abort",
+                track_id=f"{values[_LINE]}:{values[_TRACK]}",
+                run_by=values.get("run_by"),
+            )
+        params = {k: v for k, v in values.items() if not k.startswith("_") and k not in _CONTROL_KEYS}
+        return CliRequest(
+            command="start",
+            track_id=values[_TRACK_ID],
+            params=params,
+            force=values["force"],
+            allow_stale_takeover=values["allow_stale_takeover"],
+            stale_after=values["stale_after"],
+            run_id=values.get("run_id"),
+            run_by=values.get("run_by"),
+            dry_run=values["dry_run"],
+            output=values.get("output"),
+        )
+
+    def execute(self, request: CliRequest) -> int:
+        """parse_args() の結果を受け取ってタスクを実行し、結果を終了コードで返す。
+
+        sys.exit() は呼ばない（Python コードから呼ぶライブラリ利用を妨げない）。
+        スクリプトでは ``sys.exit(cli.execute(request))`` として終了コードを伝える。
+        組み合わせの検証は CliRequest の構築時に済んでいる。
+
+        ``dry_run=True`` のときは、タスクを呼ばず、``dispatcher.plan()`` の結果を標準出力に出し、
+        本番を同じオプションで実行したときと同じ終了コードを返す（実行できる 0 / 赤信号 3 / stale 4 /
+        判定できない 1）。TrainMiddleware は通らない（ADR-0008）。
+
+        Args:
+            request: parse_args() が返した CliRequest（``dataclasses.replace()`` で加工してよい）。
+
+        Returns:
+            :class:`ExitCode`（int）。成功 0 / 失敗 1 / 赤信号 3 / stale 4 / 見送り 5。
+            引数エラー（2）は parse_args() が argparse の標準動作で終了する。
+        """
+        if request.command == "abort":
+            self.dispatcher.abort(request.track_id, run_by=request.run_by)
+            return ExitCode.SUCCESS
+
+        if request.dry_run:
+            plan = self.dispatcher.plan(
+                request.track_id,
+                request.params,
+                force=request.force,
+                allow_stale_takeover=request.allow_stale_takeover,
+                stale_after=request.stale_after,
+                run_by=request.run_by,
+            )
+            if request.output == "json":
+                print(json.dumps(plan.to_dict(), ensure_ascii=False, indent=2, default=str))
+            else:
+                print(_format_plan_text(plan))
+            return _plan_exit_code(plan)
+
+        result = self.dispatcher.depart(
+            request.track_id,
+            request.params,
+            force=request.force,
+            allow_stale_takeover=request.allow_stale_takeover,
+            stale_after=request.stale_after,
+            run_id=request.run_id,
+            run_by=request.run_by,
+        )
+        return _exit_code(result)

{interlocking-0.1.0 → interlocking-0.2.1}/src/interlocking/dispatcher.py

@@ -28,6 +28,7 @@ from .models import (
     SignalBlockedError,
     SignalStatus,
     StaleLockError,
+    TrainPlan,
     TrainRecord,
     TrainResult,
 )
@@ -35,6 +36,20 @@ from .station import Station
 
 logger = logging.getLogger(__name__)
 
+# フレームワークの CLI オプション（--dry-run / --output）と衝突するため、タスクの引数には使えない（ADR-0008）。
+# 利用者が自分で実装する場合は、track_dry_run のように接頭辞を付ける。
+RESERVED_PARAM_NAMES = frozenset({"dry_run", "output"})
+
+
+def _check_reserved_params(track_id: str, names: Any) -> None:
+    """タスクの引数に予約名が使われていたら TypeError にする。"""
+    reserved = sorted(RESERVED_PARAM_NAMES & set(names))
+    if reserved:
+        raise TypeError(
+            f"タスク '{track_id}' の引数 {reserved} はフレームワークの予約名です。"
+            f"別の名前にしてください（例: track_{reserved[0]}）。"
+        )
+
 
 def _default_run_by() -> str:
     """実行ユーザー名の既定値。Lambda など passwd に UID がない環境では "unknown"。"""
@@ -341,12 +356,17 @@ class TrainDispatcher:
         """
         self.master.abort(track_id)
         record = self.master.load_record(track_id)
+        _run_by = run_by or _default_run_by()
         record.status = "aborted"
         record.error_type = None
         record.error_message = None
         record.aborted_at = time.time()
-        record.aborted_by = run_by or _default_run_by()
+        record.aborted_by = _run_by
         self.master.save_record(track_id, record)
+        # abort は TrainMiddleware を通らないので、操作の事実をここで記録する（run_id は実行ではないため None）
+        logging.LoggerAdapter(
+            logger, {"track_id": track_id, "run_id": None, "run_by": _run_by}
+        ).info("Aborted: %s by=%s", track_id, _run_by)
 
     def load_line(self, line_name: str) -> None:
         """指定路線を lazy import して registry に登録する。
@@ -366,7 +386,12 @@ class TrainDispatcher:
         self.load_line(track_id.split(":")[0])
 
     def register(self, track_id: str, func: Callable, help: str) -> None:
-        """タスクを registry に登録する。通常は Line.register_to() から呼ばれる。"""
+        """タスクを registry に登録する。通常は Line.register_to() から呼ばれる。
+
+        Raises:
+            TypeError: タスクの引数に予約名（dry_run / output）が使われている場合。
+        """
+        _check_reserved_params(track_id, _task_signature(func)[1])
         self.registry[track_id] = (func, help)
 
     def task_params(self, track_id: str) -> Tuple[Set[str], Set[str]]:
@@ -379,6 +404,85 @@ class TrainDispatcher:
         _, names, required = _task_signature(self.registry[track_id][0])
         return set(names), required
 
+    def plan(
+        self,
+        track_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        force: bool = False,
+        allow_stale_takeover: bool = False,
+        stale_after: int = 600,
+        run_by: Optional[str] = None,
+    ) -> TrainPlan:
+        """同じオプションで depart() したらどうなるかを、副作用なしで予測する（--dry-run 用）。
+
+        タスク関数は呼ばず、ロックも取らず、記録も保存しない。TrainMiddleware も通さない。
+        結果は確認した時点のスナップショットで、depart() は実行時にあらためて信号を確認する。
+
+        Args:
+            track_id:  タスク識別子（"line_name:track_name" 形式）。
+            params:    タスク関数に渡す引数の dict。depart() と同じ検証を行う。
+            force / allow_stale_takeover / stale_after: depart() と同じ意味。
+            run_by:    実行ユーザー名。省略時は getpass.getuser()。
+
+        Raises:
+            ValueError: params に未知のキーがある、または必須の引数が不足している場合。
+        """
+        _params = dict(params or {})
+        self._ensure_line_for(track_id)
+        _, arg_names, required = _task_signature(self.registry[track_id][0])
+
+        if unknown := _params.keys() - set(arg_names):
+            raise ValueError(
+                f"{track_id} に存在しない引数です: {sorted(unknown)} (使用可能: {sorted(arg_names)})"
+            )
+        if missing := required - _params.keys():
+            raise ValueError(f"{track_id} に必須の引数が不足しています: {sorted(missing)}")
+
+        notes: list = []
+        signal: Optional[SignalStatus] = None
+        if force:
+            outcome = "ready"
+            notes.append("--force のため、信号を確認せずに実行します。")
+        else:
+            try:
+                signal = self.master.peek_signal(track_id, stale_after)
+            except NotImplementedError as e:
+                outcome = "unknown"
+                notes.append(f"信号の状態を判定できません: {e}")
+            else:
+                if signal is SignalStatus.CLEAR:
+                    outcome = "ready"
+                elif signal is SignalStatus.STALE:
+                    if allow_stale_takeover:
+                        outcome = "ready"
+                        notes.append("前回ロックの残骸（stale）を引き継いで実行します。")
+                    else:
+                        outcome = "stale"
+                        notes.append(
+                            "前回ロックの残骸（stale）があります。abort か --allow-stale-takeover で復旧してください。"
+                        )
+                else:
+                    outcome = "blocked"
+                    notes.append("他の列車が運行中です。")
+        notes.append("確認した時点のスナップショットです。実行時にあらためて信号を確認します。")
+        notes.append("TrainMiddleware は動作しないため、Middleware による見送りは予測に含まれません。")
+
+        last_stop = self.master.load_record(track_id)
+        return TrainPlan(
+            track_id=track_id,
+            outcome=outcome,
+            signal=signal,
+            first_departure=last_stop.run_id is None,
+            last_stop=last_stop,
+            params=_params,
+            force=force,
+            allow_stale_takeover=allow_stale_takeover,
+            stale_after=stale_after,
+            run_by=run_by or _default_run_by(),
+            notes=notes,
+        )
+
     def depart(
         self,
         track_id: str,

{interlocking-0.1.0 → interlocking-0.2.1}/src/interlocking/models.py

@@ -129,6 +129,57 @@ class TrainResult:
         }
 
 
+@dataclass
+class TrainPlan:
+    """TrainDispatcher.plan() の結果。実行したらどうなるかの予測（スナップショット）。
+
+    タスク関数は呼ばず、ロックも取らず、記録も保存しない。確認した時点の状態にすぎず、
+    実行時の結果を保証しない。TrainMiddleware は通さないので、Middleware の見送り判断は含まれない。
+
+    Attributes:
+        track_id:  タスク識別子。
+        outcome:   同じオプションで実行したときの予測。
+                   ready（実行できる）/ blocked（赤信号）/ stale（前回ロックの残骸）/
+                   unknown（Station が確認に対応していない、など判定できない）。
+        signal:    確認した信号の状態。確認していない（force）・判定できないときは None。
+        first_departure: 始発（初回実行）かどうか。
+        last_stop: 前回の到着記録。始発時は run_id=None の空の記録。
+        params:    タスク関数に渡る引数。
+        force / allow_stale_takeover / stale_after / run_by: 実行の制御オプション。
+        notes:     判定の根拠や注意。人にも AI にも、出力だけで読み取れるようにする。
+    """
+    track_id: str
+    outcome: str
+    signal: Optional[SignalStatus]
+    first_departure: bool
+    last_stop: TrainRecord
+    params: Dict[str, Any] = field(default_factory=dict)
+    force: bool = False
+    allow_stale_takeover: bool = False
+    stale_after: int = 600
+    run_by: Optional[str] = None
+    notes: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        """JSON シリアライズ可能な dict を返す。"""
+        return {
+            "track_id": self.track_id,
+            "outcome": self.outcome,
+            "signal": None if self.signal is None else self.signal.value,
+            "first_departure": self.first_departure,
+            "last_stop": self.last_stop.to_dict(),
+            "last_data": self.last_stop.data,
+            "params": self.params,
+            "options": {
+                "force": self.force,
+                "allow_stale_takeover": self.allow_stale_takeover,
+                "stale_after": self.stale_after,
+                "run_by": self.run_by,
+            },
+            "notes": list(self.notes),
+        }
+
+
 class SignalBlockedError(Exception):
     """多重起動が検出されたとき raise される。Train.prepare() から発生する。
 

{interlocking-0.1.0 → interlocking-0.2.1}/src/interlocking/station.py

@@ -70,6 +70,25 @@ class Station(ABC):
     def clear_signal(self, track_id: str) -> None:
         """信号を解放する（Unlock）。"""
 
+    def peek_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """信号の状態を、ロックを取らずに確認する（--dry-run 用）。
+
+        check_signal() と違い、ロックの取得・作成・削除などの副作用を持たない。
+        結果は、確認した時点のスナップショットにすぎない。
+
+        抽象メソッドではない（既存のカスタム Station を壊さない）。未対応の Station は
+        NotImplementedError を送出し、呼び出し側は「判定できない」と報告する。
+
+        Returns:
+            CLEAR:   今は、ロックが取れる状態。
+            BLOCKED: 他の列車が運行中。
+            STALE:   前回ロックの残骸。
+
+        Raises:
+            NotImplementedError: この Station は、ロックを取らない確認に対応していない。
+        """
+        raise NotImplementedError(f"{type(self).__name__} は peek_signal() に対応していません")
+
     @abstractmethod
     def abort(self, track_id: str) -> None:
         """信号を強制解除する。
@@ -196,6 +215,17 @@ class LocalStation(Station):
             return SignalStatus.BLOCKED
         return SignalStatus.BLOCKED  # 確定できないときは止める側に倒す
 
+    def peek_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """シグナルファイルを作らず、ロックも保持せずに、信号の状態を確認する。"""
+        sig_path, _ = self._get_paths(track_id)
+        for _ in range(_MAX_ATTEMPTS):
+            if not sig_path.exists():
+                return SignalStatus.CLEAR
+            status = self._probe_existing(sig_path)
+            if status is not None:
+                return status
+        return SignalStatus.BLOCKED  # 確定できないときは止める側に倒す
+
     def takeover_signal(self, track_id: str, stale_after: int = 600) -> bool:
         """プロセスが消失して残ったシグナルファイルのロックを取得する。
 
@@ -363,6 +393,18 @@ class S3Station(Station):
             return SignalStatus.STALE if elapsed >= stale_after else SignalStatus.BLOCKED
         return SignalStatus.BLOCKED  # 確定できないときは止める側に倒す
 
+    def peek_signal(self, track_id: str, stale_after: int = 600) -> SignalStatus:
+        """head_object だけで信号の状態を確認する。PUT も DELETE もしない。"""
+        from botocore.exceptions import ClientError
+        try:
+            response = self._s3.head_object(Bucket=self.bucket, Key=self._signal_key(track_id))
+        except ClientError as e:
+            if e.response["Error"]["Code"] in ("NoSuchKey", "404"):
+                return SignalStatus.CLEAR
+            raise
+        elapsed = time.time() - response["LastModified"].timestamp()
+        return SignalStatus.STALE if elapsed >= stale_after else SignalStatus.BLOCKED
+
     def takeover_signal(self, track_id: str, stale_after: int = 600) -> bool:
         """stale なシグナルオブジェクトを、ETag を条件に上書きして引き継ぐ。
 

interlocking-0.1.0/PKG-INFO

@@ -1,79 +0,0 @@
-Metadata-Version: 2.4
-Name: interlocking
-Version: 0.1.0
-Summary: A lightweight task dispatcher with explicit control.
-Keywords: task-runner,batch,exclusive-lock,cli,mutex,distributed-lock
-Author: alpine
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: System :: Distributed Computing
-Classifier: Topic :: Utilities
-Requires-Dist: boto3>1.40.0,<2 ; extra == 'aws'
-Requires-Python: >=3.11
-Provides-Extra: aws
-Description-Content-Type: text/markdown
-
-# Interlocking
-
-> One track, one train.  
-> Easy to run. Explicit to control.
-
-interlocking は、分散環境におけるバックグラウンドタスクの実行管理フレームワークです。
-名前は鉄道の連動装置（同じ軌道に同時に列車を入れないよう進路を制御する仕組み）に由来し、排他制御を核に据えています。
-鉄道メタファーにより、バッチタスクのライフサイクル（排他制御・実行記録・CLI 統合）を統一された方法で管理します。
-
-## 特長
-
-- **排他制御**: 同じタスクを同時に走らせない。
-- **実行記録**: 直近の実行結果を記録し、次回実行に引き継ぐ（`Coupler`）。
-- **CLI 統合**: 型ヒントからコマンドラインを組み立て、結果を終了コードで返す。
-- **差し込み**: `Station`（ストレージ）や `TrainMiddleware` で、振る舞いを拡張できる。
-
-## 最小構成
-
-```python
-# tasks.py
-from typing import Annotated
-from interlocking import Line, Coupler
-
-line = Line()
-
-@line.track(name="daily", help="日次処理")
-def daily_task(c: Coupler, target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"]) -> dict:
-    last_id = c.last_data.get("last_id", 0)
-    # ... 処理 ...
-    return {"last_id": 9999}
-```
-
-```python
-# main.py
-import sys
-
-from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
-
-dispatcher = TrainDispatcher(
-    station=LocalStation(base_path=".interlocking"),
-    lines={"batch": "tasks:line"},
-)
-
-cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="バッチタスク")
-sys.exit(cli.execute(cli.parse_args()))  # 結果を終了コードで伝える
-```
-
-```bash
-python main.py batch daily start --target-date 2026-04-01
-```
-
-## 開発
-
-```bash
-uv sync
-uv run pytest
-```
-
-## ライセンス
-
-MIT

interlocking-0.1.0/README.md

@@ -1,61 +0,0 @@
-# Interlocking
-
-> One track, one train.  
-> Easy to run. Explicit to control.
-
-interlocking は、分散環境におけるバックグラウンドタスクの実行管理フレームワークです。
-名前は鉄道の連動装置（同じ軌道に同時に列車を入れないよう進路を制御する仕組み）に由来し、排他制御を核に据えています。
-鉄道メタファーにより、バッチタスクのライフサイクル（排他制御・実行記録・CLI 統合）を統一された方法で管理します。
-
-## 特長
-
-- **排他制御**: 同じタスクを同時に走らせない。
-- **実行記録**: 直近の実行結果を記録し、次回実行に引き継ぐ（`Coupler`）。
-- **CLI 統合**: 型ヒントからコマンドラインを組み立て、結果を終了コードで返す。
-- **差し込み**: `Station`（ストレージ）や `TrainMiddleware` で、振る舞いを拡張できる。
-
-## 最小構成
-
-```python
-# tasks.py
-from typing import Annotated
-from interlocking import Line, Coupler
-
-line = Line()
-
-@line.track(name="daily", help="日次処理")
-def daily_task(c: Coupler, target_date: Annotated[str, "対象日付 (YYYY-MM-DD)"]) -> dict:
-    last_id = c.last_data.get("last_id", 0)
-    # ... 処理 ...
-    return {"last_id": 9999}
-```
-
-```python
-# main.py
-import sys
-
-from interlocking import TrainDispatcher, LocalStation, InterlockingCLI
-
-dispatcher = TrainDispatcher(
-    station=LocalStation(base_path=".interlocking"),
-    lines={"batch": "tasks:line"},
-)
-
-cli = InterlockingCLI(dispatcher=dispatcher, prog="my-task", description="バッチタスク")
-sys.exit(cli.execute(cli.parse_args()))  # 結果を終了コードで伝える
-```
-
-```bash
-python main.py batch daily start --target-date 2026-04-01
-```
-
-## 開発
-
-```bash
-uv sync
-uv run pytest
-```
-
-## ライセンス
-
-MIT

interlocking-0.1.0/src/interlocking/cli.py

@@ -1,264 +0,0 @@
-"""
-interlocking.cli
-===========
-interlocking を使った CLI の共通ビルダー。
-
-argparse の2ステップインターフェースに準拠する::
-
-    cli = InterlockingCLI(
-        dispatcher=dispatcher,
-        prog="sails-task2",
-        description="SAILSタスク実行コマンド",
-    )
-    args = cli.parse_args()          # パーサー構築 + 引数解析
-    context.setup_logging(args.log_config)
-    sys.exit(cli.execute(args))      # タスク実行。結果を終了コード（ExitCode）で返す
-"""
-from __future__ import annotations
-
-import argparse
-import inspect
-import sys
-from enum import IntEnum
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    Optional,
-    Tuple,
-    get_args,
-    get_origin,
-    get_type_hints,
-)
-
-from .dispatcher import TrainDispatcher
-from .models import Coupler, TrainResult
-
-
-class ExitCode(IntEnum):
-    """CLI の終了コード。cron など上位のオーケストレーターが結果を判別するための規約。"""
-
-    SUCCESS = 0
-    FAILED = 1   # タスクが失敗した
-    USAGE = 2    # argparse の引数エラー（argparse が返す。interlocking はこの値を他の用途に使わない）
-    BLOCKED = 3  # 赤信号（他の列車が運行中）で実行されなかった
-    STALE = 4    # 前回ロックの残骸（stale）で実行されなかった。復旧が必要
-    SKIPPED = 5  # Middleware が実行を見送った
-
-
-def _exit_code(result: TrainResult) -> ExitCode:
-    """depart() の結果を終了コードに変換する。判断できないときは失敗扱いにする。"""
-    if result.status == "success":
-        return ExitCode.SUCCESS
-    if result.status == "blocked":
-        return ExitCode.STALE if result.is_stale else ExitCode.BLOCKED
-    if result.status == "skipped":
-        return ExitCode.SKIPPED
-    return ExitCode.FAILED
-
-# InterlockingCLI 内部で使用する共通キー（params の抄出時に除外）
-_INTERLOCKING_PARAM_KEYS: frozenset = frozenset({
-    "command", "track_id", "line", "force", "allow_stale_takeover", "stale_after", "run_id", "run_by", "parser",
-})
-
-
-def _setup_argparsers(registry: Dict[str, Tuple[Callable, str]], parsers: Any, line_name: Optional[str] = None) -> None:
-    """路線 registry から argparse サブパーサーを構築する。
-
-    関数の型ヒント (Annotated[Type, "help"]) から引数定義を自動生成する。
-    Annotated でない引数（Coupler 以外）はエラーとなる。
-
-    Args:
-        registry:  TrainDispatcher.registry（line_name でフィルタ済みを推奨）。
-        parsers:   argparse の add_subparsers() の戻り値。
-        line_name: 指定時は "line_name:track_name" の track_name 部分をサブコマンド名にする。
-    """
-    for track_id, (func, help_text) in registry.items():
-        # InterlockingCLI 経由の場合は track_name 部分のみをサブコマンド名にする
-        display_name = track_id.split(":", 1)[1] if line_name and ":" in track_id else track_id
-        parser = parsers.add_parser(display_name, help=help_text)
-        parser.set_defaults(track_id=track_id)
-        parser.add_argument("command", choices=["start", "abort"])
-
-        try:
-            type_hints = get_type_hints(func, include_extras=True)
-        except Exception:
-            type_hints = {}
-
-        sig = inspect.signature(func)
-
-        for param_name, param in sig.parameters.items():
-            hint = param.annotation if param.annotation is not inspect.Parameter.empty else None
-            type_hint = type_hints.get(param_name)
-            if type_hint is not None:
-                hint = type_hint
-            if hint is None:
-                continue
-
-            is_coupler = False
-            try:
-                if hint is Coupler:
-                    is_coupler = True
-                elif hasattr(hint, '__name__') and hint.__name__ == 'Coupler':
-                    is_coupler = True
-                elif isinstance(hint, str) and hint == 'Coupler':
-                    is_coupler = True
-            except Exception:
-                pass
-            if is_coupler:
-                continue
-
-            origin = get_origin(hint)
-            has_metadata = hasattr(hint, '__metadata__')
-            import typing
-            is_annotated = (
-                has_metadata or
-                (origin is not None and (
-                    origin is getattr(typing, 'Annotated', None) or
-                    str(origin) == 'typing.Annotated'
-                ))
-            )
-            if not is_annotated:
-                raise TypeError(
-                    f"タスク '{track_id}' の引数 '{param_name}' には "
-                    f"Annotated[Type, 'ヘルプメッセージ'] が必要です。"
-                )
-
-            args = get_args(hint)
-            actual_type = args[0]
-            help_msg = hint.__metadata__[0] if hint.__metadata__ else ""
-            arg_default = (
-                param.default if param.default is not inspect.Parameter.empty else None
-            )
-            if actual_type is bool:
-                parser.add_argument(f"--{param_name}", action="store_true", help=help_msg)
-            else:
-                parser.add_argument(f"--{param_name}", type=actual_type, default=arg_default, help=help_msg)
-
-        parser.add_argument("--force", action="store_true", help="信号を無視して実行する（安全装置をすべて解除する）")
-        parser.add_argument(
-            "--allow-stale-takeover", dest="allow_stale_takeover", action="store_true",
-            help="stale（前回ロックの残骸）なロックだけを引き継いで実行する",
-        )
-        parser.add_argument(
-            "--stale-after", dest="stale_after", type=int, default=600,
-            help="この秒数が経過したロックを stale（前回ロックの残骸）とみなす (default=600)",
-        )
-        parser.add_argument("--run-by", dest="run_by", default=None, help="実行ユーザー名 (記録用)")
-        parser.add_argument("--run-id", dest="run_id", default=None, help="実行ID (記録用)")
-
-
-class InterlockingCLI:
-    """interlocking CLI のビルダー。
-
-    argparse の2ステップに準拠した設計:
-      parse_args() でパーサーを構築して引数を解析し、
-      execute() でタスクを実行する。
-
-    3フェーズでパーサーを構築する:
-      Phase 1 (Discovery): dispatcher.lines のキーだけでトップレベルパーサーを構成。
-      Phase 2 (Loading):   指定路線のモジュールを import し line 属性を取得。
-                           line.register_to(dispatcher) でタスクを登録する。
-      Phase 3 (Mapping):   登録済みタスクから詳細パーサーを構築する。
-
-    Args:
-        dispatcher:      構築済みの TrainDispatcher。
-        prog:            CLI プログラム名（argparse の prog）。
-        description:     CLI の説明文。
-        extra_arguments: ルートパーサーに追加する引数を設定するコールバック。
-    """
-
-    def __init__(
-        self,
-        dispatcher: TrainDispatcher,
-        prog: str = "interlocking",
-        description: str = "",
-        extra_arguments: Optional[Callable[[argparse.ArgumentParser], None]] = None,
-    ) -> None:
-        self.dispatcher = dispatcher
-        self.prog = prog
-        self.description = description
-        self.extra_arguments = extra_arguments
-
-    def parse_args(self, argv: Optional[list] = None) -> argparse.Namespace:
-        """パーサーを構築して引数を解析する。
-
-        argparse の parse_args() に相当するステップ。
-        戻り値の Namespace を execute() に渡すことでタスクを実行する。
-
-        Args:
-            argv: パース対象の引数リスト。None のとき sys.argv[1:] を使用。
-
-        Returns:
-            解析済みの argparse.Namespace。
-        """
-        _argv = argv if argv is not None else sys.argv[1:]
-
-        root = argparse.ArgumentParser(prog=self.prog, description=self.description)
-        root.set_defaults(parser=root, track_id=None)
-
-        if self.extra_arguments:
-            self.extra_arguments(root)
-
-        line_subparsers = root.add_subparsers(dest="line", help="line name")
-
-        # Phase 1: 路線名だけでパーサーを構成（import なし）
-        line_parsers: Dict[str, argparse.ArgumentParser] = {}
-        for line in self.dispatcher.lines:
-            lp = line_subparsers.add_parser(line)
-            lp.set_defaults(parser=lp, track_id=None)
-            line_parsers[line] = lp
-
-        # Phase 2: 指定路線をロードし登録
-        temp_parser = argparse.ArgumentParser(add_help=False)
-        if self.extra_arguments:
-            self.extra_arguments(temp_parser)
-        temp_parser.add_argument('line', nargs='?', choices=list(self.dispatcher.lines))
-        temp_args, _ = temp_parser.parse_known_args(_argv)
-        if temp_args.line:
-            self.dispatcher.load_line(temp_args.line)
-
-        # Phase 3: 登録済みタスクから詳細パーサーを構築。路線別にフィルタして track_name だけをサブコマンド名にする。
-        for line, lp in line_parsers.items():
-            track_subparsers = lp.add_subparsers(dest="track_id", help="タスク名")
-            line_registry = {
-                track_id: entry
-                for track_id, entry in self.dispatcher.registry.items()
-                if track_id.startswith(f"{line}:")
-            }
-            _setup_argparsers(line_registry, track_subparsers, line)
-
-        return root.parse_args(_argv)
-
-    def execute(self, args: argparse.Namespace) -> int:
-        """parse_args() の結果を受け取ってタスクを実行し、結果を終了コードで返す。
-
-        sys.exit() は呼ばない（Python コードから呼ぶライブラリ利用を妨げない）。
-        スクリプトでは ``sys.exit(cli.execute(args))`` として終了コードを伝える。
-
-        Args:
-            args: parse_args() が返した Namespace。
-
-        Returns:
-            :class:`ExitCode`（int）。成功 0 / 失敗 1 / 赤信号 3 / stale 4 / 見送り 5。
-            引数エラー（2）は parse_args() が argparse の標準動作で終了する。
-        """
-        if args.track_id is None:
-            args.parser.print_help()
-            return ExitCode.SUCCESS
-
-        if args.command == "abort":
-            self.dispatcher.abort(args.track_id, run_by=getattr(args, "run_by", None))
-            return ExitCode.SUCCESS
-
-        params = {k: v for k, v in vars(args).items() if k not in _INTERLOCKING_PARAM_KEYS}
-        result = self.dispatcher.depart(
-            args.track_id,
-            params,
-            force=args.force,
-            allow_stale_takeover=args.allow_stale_takeover,
-            stale_after=args.stale_after,
-            run_id=getattr(args, "run_id", None),
-            run_by=getattr(args, "run_by", None),
-        )
-        return _exit_code(result)