chore: bootstrap housing research platform

src/shanghai_housing/cli.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Optional
+
+from .db import DEFAULT_DB_PATH, connect, init_db, load_sample_data
+from .indicators import compute_area_scores
+from .reporting import format_scores_table, write_monthly_report
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shanghai_housing",
+        description="Shanghai housing market research toolkit.",
+    )
+    parser.add_argument(
+        "--db",
+        type=Path,
+        default=DEFAULT_DB_PATH,
+        help=f"SQLite database path. Default: {DEFAULT_DB_PATH}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("init-db", help="Create or update the SQLite schema.")
+    subparsers.add_parser("load-sample", help="Load demonstration sample data.")
+
+    score_parser = subparsers.add_parser("score", help="Print area scores for a month.")
+    score_parser.add_argument("--month", required=True, help="Month in YYYY-MM format.")
+
+    report_parser = subparsers.add_parser("report", help="Generate a monthly Markdown report.")
+    report_parser.add_argument("--month", required=True, help="Month in YYYY-MM format.")
+    report_parser.add_argument(
+        "--output",
+        type=Path,
+        help="Output Markdown path. Default: reports/monthly-YYYY-MM.md",
+    )
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init-db":
+        path = init_db(args.db)
+        print(f"Initialized database: {path}")
+        return 0
+
+    if args.command == "load-sample":
+        load_sample_data(args.db)
+        print(f"Loaded sample data into: {args.db}")
+        return 0
+
+    if args.command == "score":
+        with connect(args.db) as conn:
+            scores = compute_area_scores(conn, args.month)
+        print(format_scores_table(scores))
+        return 0
+
+    if args.command == "report":
+        output = args.output or Path("reports") / f"monthly-{args.month}.md"
+        with connect(args.db) as conn:
+            path = write_monthly_report(conn, args.month, output)
+        print(f"Generated report: {path}")
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2