feat: scaffold us-cpa skill

skills/us-cpa/src/us_cpa/cli.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+COMMANDS = (
+    "question",
+    "prepare",
+    "review",
+    "fetch-year",
+    "extract-docs",
+    "render-forms",
+    "export-efile-ready",
+)
+
+
+def _add_common_arguments(
+    parser: argparse.ArgumentParser, *, include_tax_year: bool = True
+) -> None:
+    if include_tax_year:
+        parser.add_argument("--tax-year", type=int, default=None)
+    parser.add_argument("--case-dir", default=None)
+    parser.add_argument("--format", choices=("json", "markdown"), default="json")
+
+
+def _emit(payload: dict[str, Any], output_format: str) -> int:
+    if output_format == "markdown":
+        lines = [f"# {payload['command']}"]
+        for key, value in payload.items():
+            if key == "command":
+                continue
+            lines.append(f"- **{key}**: {value}")
+        print("\n".join(lines))
+    else:
+        print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _require_case_dir(args: argparse.Namespace) -> Path:
+    if not args.case_dir:
+        raise SystemExit("A case directory is required for this command.")
+    return Path(args.case_dir).expanduser().resolve()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="us-cpa",
+        description="US federal individual tax workflow CLI.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    question = subparsers.add_parser("question", help="Answer a tax question.")
+    _add_common_arguments(question)
+    question.add_argument("--question", required=True)
+
+    prepare = subparsers.add_parser("prepare", help="Prepare a return case.")
+    _add_common_arguments(prepare)
+
+    review = subparsers.add_parser("review", help="Review a return case.")
+    _add_common_arguments(review)
+
+    fetch_year = subparsers.add_parser(
+        "fetch-year", help="Fetch tax-year forms and instructions."
+    )
+    _add_common_arguments(fetch_year, include_tax_year=False)
+    fetch_year.add_argument("--tax-year", type=int, required=True)
+
+    extract_docs = subparsers.add_parser(
+        "extract-docs", help="Extract facts from case documents."
+    )
+    _add_common_arguments(extract_docs)
+
+    render_forms = subparsers.add_parser(
+        "render-forms", help="Render compiled IRS forms."
+    )
+    _add_common_arguments(render_forms)
+
+    export_efile = subparsers.add_parser(
+        "export-efile-ready", help="Export an e-file-ready payload."
+    )
+    _add_common_arguments(export_efile)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "question":
+        payload = {
+            "command": "question",
+            "format": args.format,
+            "taxYear": args.tax_year,
+            "caseDir": args.case_dir,
+            "question": args.question,
+            "status": "not_implemented",
+        }
+        return _emit(payload, args.format)
+
+    if args.command in {"prepare", "review", "extract-docs", "render-forms", "export-efile-ready"}:
+        case_dir = _require_case_dir(args)
+        payload = {
+            "command": args.command,
+            "format": args.format,
+            "taxYear": args.tax_year,
+            "caseDir": str(case_dir),
+            "status": "not_implemented",
+        }
+        return _emit(payload, args.format)
+
+    if args.command == "fetch-year":
+        payload = {
+            "command": "fetch-year",
+            "format": args.format,
+            "taxYear": args.tax_year,
+            "status": "not_implemented",
+        }
+        return _emit(payload, args.format)
+
+    parser.error(f"Unsupported command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())