ai-docs-toolkit 0.1.0__py3-none-any.whl

ai_docs_toolkit/cli/__init__.py

@@ -0,0 +1,1153 @@
+from ai_docs_toolkit import __version__
+from ai_docs_toolkit.context import (
+    context_project,
+    format_context_json,
+    format_context_markdown,
+)
+from ai_docs_toolkit.graph import GraphFilters, format_graph_json, graph_project
+from ai_docs_toolkit.impact import (
+    format_impact_human,
+    format_impact_json,
+    impact_changed_project,
+    impact_project,
+)
+from ai_docs_toolkit.mcp.setup import (
+    format_jetbrains_mcp_config_json,
+    format_mcp_status_human,
+    jetbrains_mcp_config,
+    mcp_setup_status,
+)
+from ai_docs_toolkit.core import (
+    InitResult,
+    AzureDevOpsConfig,
+    AzureDevOpsPushResult,
+    doctor_project,
+    azure_devops_config_from_env,
+    format_azure_devops_push_json,
+    format_doctor_json,
+    format_doctor_human,
+    format_file_lookup_human,
+    format_file_lookup_json,
+    format_planning_operation_human,
+    format_planning_operation_json,
+    format_planning_layout_migration_dry_run,
+    format_planning_scaffold_result,
+    format_stage_review_human,
+    format_stage_review_json,
+    format_task_export_json,
+    format_task_export_markdown,
+    init_project,
+    lookup_document_file,
+    lookup_plan_file,
+    lookup_request_file,
+    lookup_stage_file,
+    lookup_task_file,
+    planning_layout_migration_dry_run,
+    scaffold_planning_record,
+    start_stage,
+    start_task,
+    close_stage,
+    close_task,
+    add_stage,
+    add_task,
+    review_stage,
+    export_tasks,
+    push_azure_devops_tasks,
+    autofix_planning,
+    fix_sections,
+    add_requirement,
+)
+from ai_docs_toolkit.validation import (
+    format_human_validation_result,
+    format_json_validation_result,
+    validate_project_human,
+)
+
+
+def _help_text() -> str:
+    return "\n".join(
+        [
+            f"ai-docs {__version__}",
+            "",
+            "Usage:",
+            "  ai-docs --help",
+            "  ai-docs --version",
+            "  ai-docs init [--profile minimal|agent] [--force] [--dry-run|--check]",
+            "  ai-docs doctor [--format json|--json]",
+            "  ai-docs file (--id ID | --task TASK | --request REQUEST | --plan PLAN [--stage STAGE]) [--absolute] [--format json|--json]",
+            "  ai-docs validate",
+            "  ai-docs validate --json",
+            "  ai-docs validate --fix-planning [--dry-run] [--format json|--json]",
+            "  ai-docs fix-sections [--dry-run] [--format json|--json]",
+            "  ai-docs add-requirement TARGET-ID \"requirement\" [--dry-run] [--format json|--json]",
+            "  ai-docs plan start-stage --stage STAGE-ID [--dry-run] [--format json|--json]",
+            "  ai-docs plan start-task --task TASK-ID [--dry-run] [--format json|--json]",
+            "  ai-docs plan close-task --task TASK-ID [--dry-run] [--format json|--json]",
+            "  ai-docs plan close-stage --stage STAGE-ID [--dry-run] [--format json|--json]",
+            "  ai-docs plan add-stage --plan PLAN-ID --stage SLUG [--dry-run] [--format json|--json]",
+            "  ai-docs plan add-task --stage STAGE-ID --task SLUG [--dry-run] [--format json|--json]",
+            "  ai-docs plan review-stage --stage STAGE-ID [--format json|--json]",
+            "  ai-docs tasks export (--task TASK-ID | --stage STAGE-ID | --plan PLAN-ID) [--include-planned] [--include-backlog] [--format json|markdown] [--output PATH]",
+            "  ai-docs tasks push --provider azure-devops (--task TASK-ID | --stage STAGE-ID | --plan PLAN-ID) --organization ORG --project PROJECT [--dry-run] [--write-back] [--format json]",
+            "  ai-docs graph --format json [--type TYPE] [--module MODULE] [--id ID]",
+            "  ai-docs impact (--id ID | --changed [--base REF]) [--format json]",
+            "  ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json] [--history exclude|include|legacy] [--body-budget-bytes N] [--depth N]",
+            "  ai-docs mcp status [--project-root PATH] [--config FILE]",
+            "  ai-docs mcp configure --client jetbrains --print-json [--project-root PATH] [--config FILE]",
+            "  ai-docs planning scaffold --plan SLUG --stage SLUG --task SLUG --task-id TASK-NNNNNN [--date YYYY-MM-DD]",
+            "  ai-docs planning migrate-layout --dry-run",
+        ]
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv) if argv is not None else None
+
+    if args is None:
+        import sys
+
+        args = sys.argv[1:]
+
+    if not args or "--help" in args or "-h" in args:
+        print(_help_text())
+        return 0
+
+    if "--version" in args or "-V" in args:
+        print(__version__)
+        return 0
+
+    init_args = _parse_init_args(args)
+    if init_args is not None:
+        profile, force, dry_run, check = init_args
+        result = init_project(
+            ".",
+            profile=profile,
+            force=force,
+            dry_run=dry_run,
+            check=check,
+        )
+        print(_format_init_result(result))
+        return result.exit_code
+
+    doctor_format = _parse_doctor_args(args)
+    if doctor_format is not None:
+        result = doctor_project(".")
+        print(
+            format_doctor_json(result)
+            if doctor_format == "json"
+            else format_doctor_human(result)
+        )
+        return result.exit_code
+
+    file_args = _parse_file_args(args)
+    if file_args is not None:
+        selector, value, stage_value, absolute, output_format = file_args
+        if selector == "id":
+            result = lookup_document_file(value, ".")
+        elif selector == "task":
+            result = lookup_task_file(value, ".")
+        elif selector == "request":
+            result = lookup_request_file(value, ".")
+        elif selector == "plan" and stage_value is not None:
+            result = lookup_stage_file(value, stage_value, ".")
+        else:
+            result = lookup_plan_file(value, ".")
+        print(
+            format_file_lookup_json(result)
+            if output_format == "json"
+            else format_file_lookup_human(result, absolute=absolute)
+        )
+        return result.exit_code
+
+    if args == ["validate"]:
+        result = validate_project_human(".")
+        print(format_human_validation_result(result))
+        return result.exit_code
+
+    if args == ["validate", "--json"] or args == ["--json", "validate"]:
+        result = validate_project_human(".")
+        print(format_json_validation_result(result))
+        return result.exit_code
+
+    validate_fix_args = _parse_validate_fix_args(args)
+    if validate_fix_args is not None:
+        dry_run, output_format = validate_fix_args
+        fix_result = autofix_planning(".", dry_run=dry_run)
+        if output_format == "json":
+            print(format_planning_operation_json(fix_result))
+        else:
+            print(format_planning_operation_human(fix_result))
+        if fix_result.exit_code != 0:
+            return fix_result.exit_code
+        if dry_run:
+            return 0
+        validation_result = validate_project_human(".")
+        print(format_human_validation_result(validation_result))
+        return validation_result.exit_code
+
+    fix_sections_args = _parse_simple_mutation_args(args, "fix-sections")
+    if fix_sections_args is not None:
+        dry_run, output_format = fix_sections_args
+        result = fix_sections(".", dry_run=dry_run)
+        print(
+            format_planning_operation_json(result)
+            if output_format == "json"
+            else format_planning_operation_human(result)
+        )
+        return result.exit_code
+
+    add_requirement_args = _parse_add_requirement_args(args)
+    if add_requirement_args is not None:
+        target_id, requirement, dry_run, output_format = add_requirement_args
+        result = add_requirement(
+            ".",
+            target_id=target_id,
+            requirement=requirement,
+            dry_run=dry_run,
+        )
+        print(
+            format_planning_operation_json(result)
+            if output_format == "json"
+            else format_planning_operation_human(result)
+        )
+        return result.exit_code
+
+    plan_args = _parse_plan_args(args)
+    if plan_args is not None:
+        command, target, slug, dry_run, output_format = plan_args
+        if command == "start-stage":
+            result = start_stage(".", stage_id=target, dry_run=dry_run)
+        elif command == "start-task":
+            result = start_task(".", task_id=target, dry_run=dry_run)
+        elif command == "close-task":
+            result = close_task(".", task_id=target, dry_run=dry_run)
+        elif command == "close-stage":
+            result = close_stage(".", stage_id=target, dry_run=dry_run)
+        elif command == "add-stage":
+            result = add_stage(".", plan_id=target, stage_slug=slug or "", dry_run=dry_run)
+        elif command == "add-task":
+            result = add_task(".", stage_id=target, task_slug=slug or "", dry_run=dry_run)
+        else:
+            review = review_stage(".", stage_id=target)
+            print(
+                format_stage_review_json(review)
+                if output_format == "json"
+                else format_stage_review_human(review)
+            )
+            return review.exit_code
+        print(
+            format_planning_operation_json(result)
+            if output_format == "json"
+            else format_planning_operation_human(result)
+        )
+        return result.exit_code
+
+    graph_filters = _parse_graph_args(args)
+    if graph_filters is not None:
+        result = graph_project(".", filters=graph_filters)
+        print(format_graph_json(result))
+        return result.exit_code
+
+    impact_args = _parse_impact_args(args)
+    if impact_args is not None:
+        impact_mode, impact_source_ids, impact_format, impact_base = impact_args
+        result = (
+            impact_changed_project(".", base_ref=impact_base)
+            if impact_mode == "changed"
+            else impact_project(impact_source_ids, ".")
+        )
+        print(
+            format_impact_json(result)
+            if impact_format == "json"
+            else format_impact_human(result)
+        )
+        return result.exit_code
+
+    context_args = _parse_context_args(args)
+    if context_args is not None:
+        context_mode, context_value, context_format, history, budget, depth = context_args
+        result = context_project(mode=context_mode, value=context_value, project_root=".", history=history, body_budget_bytes=budget, max_depth=depth)
+        print(
+            format_context_json(result)
+            if context_format == "json"
+            else format_context_markdown(result)
+        )
+        return result.exit_code
+
+    tasks_export_args = _parse_tasks_export_args(args)
+    if tasks_export_args is not None:
+        selector, value, include_planned, include_backlog, output_format, output_path = (
+            tasks_export_args
+        )
+        result = export_tasks(
+            ".",
+            task_id=value if selector == "task" else None,
+            stage_id=value if selector == "stage" else None,
+            plan_id=value if selector == "plan" else None,
+            include_planned=include_planned,
+            include_backlog=include_backlog,
+        )
+        output = (
+            format_task_export_markdown(result)
+            if output_format == "markdown"
+            else format_task_export_json(result)
+        )
+        if output_path is not None:
+            from pathlib import Path
+
+            Path(output_path).write_text(output, encoding="utf-8")
+        else:
+            print(output, end="")
+        return result.exit_code
+
+    tasks_push_args = _parse_tasks_push_args(args)
+    if tasks_push_args is not None:
+        (
+            selector,
+            value,
+            provider,
+            organization,
+            project,
+            work_item_type,
+            include_planned,
+            include_backlog,
+            dry_run,
+            write_back,
+        ) = tasks_push_args
+        if provider != "azure-devops":
+            import sys
+
+            print("Unsupported task provider. Supported providers: azure-devops", file=sys.stderr)
+            return 3
+        config_result = azure_devops_config_from_env(
+            organization=organization,
+            project=project,
+            work_item_type=work_item_type,
+        )
+        if not isinstance(config_result, AzureDevOpsConfig):
+            result = AzureDevOpsPushResult(exit_code=1, issues=(config_result,))
+        else:
+            result = push_azure_devops_tasks(
+                ".",
+                config=config_result,
+                task_id=value if selector == "task" else None,
+                stage_id=value if selector == "stage" else None,
+                plan_id=value if selector == "plan" else None,
+                include_planned=include_planned,
+                include_backlog=include_backlog,
+                dry_run=dry_run,
+                write_back=write_back,
+            )
+        print(format_azure_devops_push_json(result), end="")
+        return result.exit_code
+
+    mcp_args = _parse_mcp_args(args)
+    if mcp_args is not None:
+        mode, project_root, config_file = mcp_args
+        if mode == "status":
+            result = mcp_setup_status(project_root=project_root, config_file=config_file)
+            print(format_mcp_status_human(result))
+            return 0 if result["ok"] else 1
+
+        if mode == "jetbrains-json":
+            print(
+                format_jetbrains_mcp_config_json(
+                    jetbrains_mcp_config(
+                        project_root=project_root,
+                        config_file=config_file,
+                    )
+                )
+            )
+            return 0
+
+    planning_args = _parse_planning_args(args)
+    if planning_args is not None:
+        if planning_args == ("migrate-layout",):
+            result = planning_layout_migration_dry_run(".")
+            print(format_planning_layout_migration_dry_run(result))
+            return 0
+
+        plan_slug, stage_slug, task_slug, task_id, plan_date = planning_args
+        result = scaffold_planning_record(
+            ".",
+            plan_slug=plan_slug,
+            stage_slug=stage_slug,
+            task_slug=task_slug,
+            task_id=task_id,
+            plan_date=plan_date,
+        )
+        print(format_planning_scaffold_result(result))
+        return result.exit_code
+
+    if args and args[0] == "graph":
+        import sys
+
+        print("Usage: ai-docs graph --format json", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "impact":
+        import sys
+
+        print(
+            "Usage: ai-docs impact (--id ID | --changed [--base REF]) [--format json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "context":
+        import sys
+
+        print(
+            "Usage: ai-docs context (--id ID | --module MODULE | --feature FEATURE | --changed) [--format json] [--history exclude|include|legacy] [--body-budget-bytes N] [--depth N]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "tasks":
+        import sys
+
+        print(
+            "Usage: ai-docs tasks export (--task TASK-ID | --stage STAGE-ID | --plan PLAN-ID) "
+            "[--include-planned] [--include-backlog] [--format json|markdown] [--output PATH]\n"
+            "   or: ai-docs tasks push --provider azure-devops (--task TASK-ID | --stage STAGE-ID | --plan PLAN-ID) "
+            "--organization ORG --project PROJECT [--dry-run] [--write-back] [--format json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "init":
+        import sys
+
+        print(
+            "Usage: ai-docs init [--profile minimal|agent] [--force] [--dry-run|--check]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "doctor":
+        import sys
+
+        print("Usage: ai-docs doctor [--format json|--json]", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "fix-sections":
+        import sys
+
+        print("Usage: ai-docs fix-sections [--dry-run] [--format json|--json]", file=sys.stderr)
+        return 3
+
+    if args and args[0] == "add-requirement":
+        import sys
+
+        print(
+            "Usage: ai-docs add-requirement TARGET-ID \"requirement\" [--dry-run] [--format json|--json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "file":
+        import sys
+
+        print(
+            "Usage: ai-docs file (--id ID | --task TASK | --request REQUEST | --plan PLAN [--stage STAGE]) [--absolute] [--format json|--json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "plan":
+        import sys
+
+        print(
+            "Usage: ai-docs plan (start-stage|close-stage) --stage STAGE-ID [--dry-run] [--format json|--json]\n"
+            "   or: ai-docs plan (start-task|close-task) --task TASK-ID [--dry-run] [--format json|--json]\n"
+            "   or: ai-docs plan add-stage --plan PLAN-ID --stage SLUG [--dry-run] [--format json|--json]\n"
+            "   or: ai-docs plan add-task --stage STAGE-ID --task SLUG [--dry-run] [--format json|--json]\n"
+            "   or: ai-docs plan review-stage --stage STAGE-ID [--format json|--json]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "mcp":
+        import sys
+
+        print(
+            "Usage: ai-docs mcp status [--project-root PATH] [--config FILE]\n"
+            "   or: ai-docs mcp configure --client jetbrains --print-json [--project-root PATH] [--config FILE]",
+            file=sys.stderr,
+        )
+        return 3
+
+    if args and args[0] == "planning":
+        import sys
+
+        print(
+            "Usage: ai-docs planning scaffold --plan SLUG --stage SLUG --task SLUG --task-id TASK-NNNNNN [--date YYYY-MM-DD]\n"
+            "   or: ai-docs planning migrate-layout --dry-run",
+            file=sys.stderr,
+        )
+        return 3
+
+    import sys
+
+    print(f"Unknown command or option: {' '.join(args)}", file=sys.stderr)
+    print("Run `ai-docs --help` for usage.", file=sys.stderr)
+    return 3
+
+
+def _parse_init_args(args: list[str]) -> tuple[str, bool, bool, bool] | None:
+    if not args or args[0] != "init":
+        return None
+
+    values = args[1:]
+    profile = "agent"
+    force = False
+    dry_run = False
+    check = False
+    index = 0
+    while index < len(values):
+        option = values[index]
+        if option == "--force":
+            force = True
+            index += 1
+            continue
+
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+
+        if option == "--check":
+            check = True
+            index += 1
+            continue
+
+        if option == "--profile":
+            if index + 1 >= len(values):
+                return None
+            profile = values[index + 1]
+            if profile not in {"minimal", "agent"}:
+                return None
+            index += 2
+            continue
+
+        return None
+
+    if dry_run and check:
+        return None
+
+    return profile, force, dry_run, check
+
+
+def _parse_doctor_args(args: list[str]) -> str | None:
+    if args == ["doctor"]:
+        return "human"
+    if args in (["doctor", "--json"], ["--json", "doctor"]):
+        return "json"
+    if args == ["doctor", "--format", "json"]:
+        return "json"
+    return None
+
+
+def _format_init_result(result: InitResult) -> str:
+    lines = [
+        f"ai-docs init ({result.mode})",
+        f"profile: {result.profile}",
+        "created:",
+        *_format_path_list(result.created),
+        "skipped:",
+        *_format_path_list(result.skipped),
+    ]
+
+    if result.overwritten:
+        lines.extend(["overwritten:", *_format_path_list(result.overwritten)])
+
+    for label, paths in (
+        ("missing", result.missing),
+        ("stale-known", result.stale_known),
+        ("locally-modified", result.locally_modified),
+        ("provenance-missing", result.provenance_missing),
+    ):
+        if paths:
+            lines.extend([f"{label}:", *_format_path_list(paths)])
+
+    if result.unresolved:
+        lines.extend(
+            [
+                "unresolved (review and rerun with --force to overwrite):",
+                *_format_path_list(result.unresolved),
+            ]
+        )
+
+    if result.obsolete:
+        lines.extend(["obsolete:", *_format_path_list(result.obsolete)])
+
+    if result.errors:
+        lines.extend(["errors:", *_format_path_list(result.errors)])
+
+    return "\n".join(lines)
+
+
+def _format_path_list(paths: tuple[str, ...]) -> list[str]:
+    if not paths:
+        return ["- none"]
+    return [f"- {path}" for path in paths]
+
+
+def _parse_file_args(args: list[str]) -> tuple[str, str, str | None, bool, str] | None:
+    if not args or args[0] != "file":
+        return None
+
+    values = args[1:]
+    selector: str | None = None
+    selector_value: str | None = None
+    stage_value: str | None = None
+    absolute = False
+    output_format = "human"
+    index = 0
+    while index < len(values):
+        option = values[index]
+        if option == "--absolute":
+            absolute = True
+            index += 1
+            continue
+
+        if option == "--json":
+            output_format = "json"
+            index += 1
+            continue
+
+        if option == "--format":
+            if index + 1 >= len(values) or values[index + 1] != "json":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+
+        if option in {"--id", "--task", "--request", "--plan"}:
+            if index + 1 >= len(values) or selector is not None:
+                return None
+            selector = option.removeprefix("--")
+            selector_value = values[index + 1]
+            index += 2
+            continue
+
+        if option == "--stage":
+            if index + 1 >= len(values) or stage_value is not None:
+                return None
+            stage_value = values[index + 1]
+            index += 2
+            continue
+
+        return None
+
+    if selector is None or selector_value is None:
+        return None
+
+    if stage_value is not None and selector != "plan":
+        return None
+
+    return selector, selector_value, stage_value, absolute, output_format
+
+
+def _parse_validate_fix_args(args: list[str]) -> tuple[bool, str] | None:
+    if not args or args[0] != "validate" or "--fix-planning" not in args:
+        return None
+
+    dry_run = False
+    output_format = "human"
+    index = 1
+    while index < len(args):
+        option = args[index]
+        if option == "--fix-planning":
+            index += 1
+            continue
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+        if option == "--json":
+            output_format = "json"
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] != "json":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+        return None
+    return dry_run, output_format
+
+
+def _parse_simple_mutation_args(args: list[str], command: str) -> tuple[bool, str] | None:
+    if not args or args[0] != command:
+        return None
+
+    dry_run = False
+    output_format = "human"
+    index = 1
+    while index < len(args):
+        option = args[index]
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+        if option == "--json":
+            output_format = "json"
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] != "json":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+        return None
+    return dry_run, output_format
+
+
+def _parse_add_requirement_args(args: list[str]) -> tuple[str, str, bool, str] | None:
+    if not args or args[0] != "add-requirement":
+        return None
+
+    positional: list[str] = []
+    dry_run = False
+    output_format = "human"
+    index = 1
+    while index < len(args):
+        option = args[index]
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+        if option == "--json":
+            output_format = "json"
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] != "json":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+        if option.startswith("--"):
+            return None
+        positional.append(option)
+        index += 1
+
+    if len(positional) != 2:
+        return None
+    return positional[0], positional[1], dry_run, output_format
+
+
+def _parse_plan_args(args: list[str]) -> tuple[str, str, str | None, bool, str] | None:
+    if len(args) < 2 or args[0] != "plan":
+        return None
+
+    command = args[1]
+    if command not in {
+        "start-stage",
+        "start-task",
+        "close-task",
+        "close-stage",
+        "add-stage",
+        "add-task",
+        "review-stage",
+    }:
+        return None
+
+    dry_run = False
+    output_format = "human"
+    target: str | None = None
+    slug: str | None = None
+    index = 2
+    while index < len(args):
+        option = args[index]
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+        if option == "--json":
+            output_format = "json"
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] != "json":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+        if option in {"--task", "--stage", "--plan"}:
+            if index + 1 >= len(args):
+                return None
+            value = args[index + 1]
+            if command in {"start-task", "close-task"} and option == "--task":
+                target = value
+            elif command in {"start-stage", "close-stage", "review-stage"} and option == "--stage":
+                target = value
+            elif command == "add-stage" and option == "--plan":
+                target = value
+            elif command == "add-task" and option == "--stage":
+                target = value
+            elif command == "add-stage" and option == "--stage":
+                slug = value
+            elif command == "add-task" and option == "--task":
+                slug = value
+            else:
+                return None
+            index += 2
+            continue
+        return None
+
+    if target is None:
+        return None
+    if command in {"add-stage", "add-task"} and slug is None:
+        return None
+    if dry_run and command == "review-stage":
+        return None
+    return command, target, slug, dry_run, output_format
+
+
+def _parse_graph_args(args: list[str]) -> GraphFilters | None:
+    if not args or args[0] != "graph":
+        return None
+
+    values = args[1:]
+    if len(values) < 2 or values[:2] != ["--format", "json"]:
+        return None
+
+    document_type: str | None = None
+    module: str | None = None
+    document_id: str | None = None
+    index = 2
+    while index < len(values):
+        option = values[index]
+        if index + 1 >= len(values):
+            return None
+
+        value = values[index + 1]
+        if option == "--type":
+            document_type = value
+        elif option == "--module":
+            module = value
+        elif option == "--id":
+            document_id = value
+        else:
+            return None
+        index += 2
+
+    return GraphFilters(
+        document_type=document_type,
+        module=module,
+        document_id=document_id,
+    )
+
+
+def _parse_impact_args(
+    args: list[str],
+) -> tuple[str, tuple[str, ...], str, str | None] | None:
+    if not args or args[0] != "impact":
+        return None
+
+    values = args[1:]
+    mode: str | None = None
+    source_ids: tuple[str, ...] = ()
+    output_format = "human"
+    base_ref: str | None = None
+    index = 0
+    while index < len(values):
+        value = values[index]
+        if value == "--changed" and mode is None:
+            mode = "changed"
+            index += 1
+            continue
+        if value == "--id" and mode is None and index + 1 < len(values):
+            mode = "id"
+            source_ids = (values[index + 1],)
+            index += 2
+            continue
+        if value == "--format" and index + 1 < len(values):
+            if values[index + 1] != "json" or output_format != "human":
+                return None
+            output_format = "json"
+            index += 2
+            continue
+        if value == "--base" and index + 1 < len(values) and base_ref is None:
+            base_ref = values[index + 1]
+            index += 2
+            continue
+        return None
+
+    if mode is None or (mode == "id" and base_ref is not None):
+        return None
+    return (mode, source_ids, output_format, base_ref)
+
+
+def _parse_context_args(args: list[str]) -> tuple[str, str, str, str | None, int | None, int | None] | None:
+    if not args or args[0] != "context":
+        return None
+    options = {}
+    index = 1
+    allowed = {"--id", "--module", "--feature", "--changed", "--format", "--history", "--body-budget-bytes", "--depth"}
+    while index < len(args):
+        option = args[index]
+        if option not in allowed or option in options:
+            return None
+        if option == "--changed":
+            options[option] = ""
+            index += 1
+            continue
+        if index + 1 >= len(args) or not args[index + 1] or args[index + 1].startswith("--"):
+            return None
+        options[option] = args[index + 1]
+        index += 2
+    sources = [key for key in options if key in {"--id", "--module", "--feature", "--changed"}]
+    if len(sources) != 1 or ("--format" in options and options["--format"] != "json"):
+        return None
+    history = options.get("--history")
+    if history is not None and history not in {"exclude", "include", "legacy"}:
+        return None
+    numeric = {}
+    for key in ("--body-budget-bytes", "--depth"):
+        value = options.get(key)
+        if value is not None:
+            if not value.isascii() or not value.isdigit():
+                return None
+            try:
+                numeric[key] = int(value)
+            except ValueError:
+                return None
+    source = sources[0]
+    return (source[2:], options[source], options.get("--format", "markdown"), history,
+            numeric.get("--body-budget-bytes"), numeric.get("--depth"))
+
+
+def _parse_tasks_export_args(
+    args: list[str],
+) -> tuple[str, str, bool, bool, str, str | None] | None:
+    if len(args) < 3 or args[:2] != ["tasks", "export"]:
+        return None
+
+    selector: str | None = None
+    value: str | None = None
+    include_planned = False
+    include_backlog = False
+    output_format = "json"
+    output_path: str | None = None
+    index = 2
+    while index < len(args):
+        option = args[index]
+        if option == "--include-planned":
+            include_planned = True
+            index += 1
+            continue
+        if option == "--include-backlog":
+            include_backlog = True
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] not in {"json", "markdown"}:
+                return None
+            output_format = args[index + 1]
+            index += 2
+            continue
+        if option == "--output":
+            if index + 1 >= len(args) or output_path is not None:
+                return None
+            output_path = args[index + 1]
+            index += 2
+            continue
+        if option in {"--task", "--stage", "--plan"}:
+            if index + 1 >= len(args) or selector is not None:
+                return None
+            selector = option.removeprefix("--")
+            value = args[index + 1]
+            index += 2
+            continue
+        return None
+
+    if selector is None or value is None:
+        return None
+
+    return selector, value, include_planned, include_backlog, output_format, output_path
+
+
+def _parse_tasks_push_args(
+    args: list[str],
+) -> tuple[str, str, str, str | None, str | None, str, bool, bool, bool, bool] | None:
+    if len(args) < 4 or args[:2] != ["tasks", "push"]:
+        return None
+
+    selector: str | None = None
+    value: str | None = None
+    provider: str | None = None
+    organization: str | None = None
+    project: str | None = None
+    work_item_type = "Task"
+    include_planned = False
+    include_backlog = False
+    dry_run = False
+    write_back = False
+    output_format = "json"
+    index = 2
+    while index < len(args):
+        option = args[index]
+        if option == "--include-planned":
+            include_planned = True
+            index += 1
+            continue
+        if option == "--include-backlog":
+            include_backlog = True
+            index += 1
+            continue
+        if option == "--dry-run":
+            dry_run = True
+            index += 1
+            continue
+        if option == "--write-back":
+            write_back = True
+            index += 1
+            continue
+        if option == "--format":
+            if index + 1 >= len(args) or args[index + 1] != "json":
+                return None
+            output_format = args[index + 1]
+            index += 2
+            continue
+        if option in {"--task", "--stage", "--plan"}:
+            if index + 1 >= len(args) or selector is not None:
+                return None
+            selector = option.removeprefix("--")
+            value = args[index + 1]
+            index += 2
+            continue
+        if option in {"--provider", "--organization", "--project", "--work-item-type"}:
+            if index + 1 >= len(args):
+                return None
+            option_value = args[index + 1]
+            if option == "--provider":
+                provider = option_value
+            elif option == "--organization":
+                organization = option_value
+            elif option == "--project":
+                project = option_value
+            else:
+                work_item_type = option_value
+            index += 2
+            continue
+        return None
+
+    if selector is None or value is None or provider is None or output_format != "json":
+        return None
+
+    return (
+        selector,
+        value,
+        provider,
+        organization,
+        project,
+        work_item_type,
+        include_planned,
+        include_backlog,
+        dry_run,
+        write_back,
+    )
+
+
+def _context_mode(option: str) -> str | None:
+    if option == "--id":
+        return "id"
+    if option == "--module":
+        return "module"
+    if option == "--feature":
+        return "feature"
+    return None
+
+
+def _parse_mcp_args(args: list[str]) -> tuple[str, str, str] | None:
+    if not args or args[0] != "mcp":
+        return None
+
+    values = args[1:]
+    if not values:
+        return None
+
+    if values[0] == "status":
+        options = _parse_project_options(values[1:])
+        if options is None:
+            return None
+        project_root, config_file = options
+        return ("status", project_root, config_file)
+
+    if values[:4] == ["configure", "--client", "jetbrains", "--print-json"]:
+        options = _parse_project_options(values[4:])
+        if options is None:
+            return None
+        project_root, config_file = options
+        return ("jetbrains-json", project_root, config_file)
+
+    return None
+
+
+def _parse_project_options(values: list[str]) -> tuple[str, str] | None:
+    project_root = "."
+    config_file = "ai-docs.config.yaml"
+    index = 0
+    while index < len(values):
+        option = values[index]
+        if index + 1 >= len(values):
+            return None
+        value = values[index + 1]
+        if option == "--project-root":
+            project_root = value
+        elif option == "--config":
+            config_file = value
+        else:
+            return None
+        index += 2
+    return project_root, config_file
+
+
+def _parse_planning_args(args: list[str]):
+    if not args or args[0] != "planning":
+        return None
+
+    if args[1:] == ["migrate-layout", "--dry-run"]:
+        return ("migrate-layout",)
+
+    if args[:2] != ["planning", "scaffold"]:
+        return None
+
+    from datetime import date
+
+    values = args[2:]
+    parsed: dict[str, str] = {}
+    index = 0
+    while index < len(values):
+        option = values[index]
+        if index + 1 >= len(values):
+            return None
+        value = values[index + 1]
+        if option not in {"--plan", "--stage", "--task", "--task-id", "--date"}:
+            return None
+        parsed[option] = value
+        index += 2
+
+    required = {"--plan", "--stage", "--task", "--task-id"}
+    if not required.issubset(parsed):
+        return None
+
+    plan_date = None
+    if "--date" in parsed:
+        try:
+            plan_date = date.fromisoformat(parsed["--date"])
+        except ValueError:
+            return None
+
+    return (
+        parsed["--plan"],
+        parsed["--stage"],
+        parsed["--task"],
+        parsed["--task-id"],
+        plan_date,
+    )