"""`okstra worktree-status` 의 진입점. 핸들러는 [worktree_cli.status] 에 있다."""
from __future__ import annotations

import argparse

from .worktree_cli import status

_CLI_EPILOG = r"""Usage:
  okstra worktree-status [--path <dir>] [--check-clean]

okstra provisions `.okstra` plus the configured sync entries (`.project-docs`,
`.claude`, …) into every task worktree, and an `implementation` stage worktree
sits inside its task worktree. A bare `git status --porcelain` therefore never
comes back empty there, so a plan step asserting a clean tree with one fails on
okstra's scaffolding rather than on the stage's own work. This command asks the
same question against source paths only — the exact gate okstra's own handoff
and stage-integration steps use.

Use it as the assertion in a plan step:
  okstra worktree-status --check-clean

Do not chain a `git tag stage-<N>-exit` onto it. Stage completion records the
commit in the consumer ledger without creating or moving git tags.

Output: JSON { ok, path, clean, entries, excluded }. `entries` holds the
`git status --short` rows that made it dirty; `excluded` lists the paths left
out of the question.
"""


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        prog="okstra worktree-status",
        description="Clean-worktree check that ignores okstra's own scaffolding.",
        epilog=_CLI_EPILOG,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "--path", default=".",
        help="directory to inspect (default: the current directory). There is "
             "no --project-root: point --path at the stage or task worktree "
             "you mean, or run it from inside one.",
    )
    parser.add_argument(
        "--check-clean", action="store_true",
        help="exit 1 when the tree is dirty (default: always exit 0)",
    )
    return status(parser.parse_args(argv))


if __name__ == "__main__":
    raise SystemExit(main())