dev-memory-cli 0.18.2

package/lib/dev_memory_context.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from dev_memory_common import (
+    collect_git_facts,
+    ensure_branch_paths_exist,
+    get_setup_completed,
+    list_missing_docs,
+    merged_focus_areas,
+    read_json,
+    sync_progress,
+    write_json,
+)
+
+
+def command_show(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+    payload = {
+        "repo_root": str(repo_root),
+        "repo_key": repo_key,
+        "branch": branch_name,
+        "branch_key": branch_key,
+        "storage_root": str(storage_root),
+        "repo_dir": str(repo_dir),
+        "branch_dir": str(branch_dir),
+        "setup_completed": get_setup_completed(paths["manifest"]),
+        "files": {key: str(value) for key, value in paths.items()},
+        "missing_or_placeholder": list_missing_docs(paths),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def command_sync(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+    if branch_name is None:
+        # no-git mode — no git facts to derive.
+        print(json.dumps({"mode": "no-git", "skipped": True}, ensure_ascii=False))
+        return
+
+    prior_manifest = read_json(paths["manifest"]) or {}
+    facts = collect_git_facts(repo_root, branch_name, storage_root)
+    all_paths = sorted(set(
+        facts["working_tree_files"]
+        + facts["staged_files"]
+        + facts["untracked_files"]
+        + facts["recent_commit_files"]
+    ))
+    facts["focus_areas"] = merged_focus_areas(all_paths, prior_manifest.get("focus_areas") or [])
+    sync_progress(paths, facts)
+
+    manifest = read_json(paths["manifest"])
+    manifest.update(
+        {
+            "repo_root": str(repo_root),
+            "repo_key": repo_key,
+            "branch": branch_name,
+            "branch_key": branch_key,
+            "storage_root": str(storage_root),
+            "updated_at": facts["updated_at"],
+            "last_seen_head": facts["last_seen_head"],
+            "default_base": facts["default_base"],
+            "scope_summary": facts["scope_summary"],
+            "focus_areas": facts["focus_areas"],
+        }
+    )
+    write_json(paths["manifest"], manifest)
+
+    repo_manifest = read_json(paths["repo_manifest"])
+    repo_manifest.update(
+        {
+            "repo_root": str(repo_root),
+            "repo_key": repo_key,
+            "storage_root": str(storage_root),
+            "updated_at": facts["updated_at"],
+            "last_seen_branch": branch_name,
+            "last_seen_head": facts["last_seen_head"],
+            "default_base": facts["default_base"],
+        }
+    )
+    write_json(paths["repo_manifest"], repo_manifest)
+
+    payload = {
+        "repo_root": str(repo_root),
+        "repo_key": repo_key,
+        "branch": branch_name,
+        "storage_root": str(storage_root),
+        "repo_dir": str(repo_dir),
+        "branch_dir": str(branch_dir),
+        "missing_or_placeholder": list_missing_docs(paths),
+        "focus_areas": facts["focus_areas"],
+        "files_considered": len(all_paths),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Read or refresh repo+branch development assets.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    for name in ("show", "sync"):
+        sub = subparsers.add_parser(name)
+        sub.add_argument("--repo", default=".", help="Path inside the target Git repository")
+        sub.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
+        sub.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
+
+    args = parser.parse_args()
+    try:
+        if args.command == "show":
+            command_show(args)
+        else:
+            command_sync(args)
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/lib/dev_memory_graduate.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+dev-memory-graduate: harvest cross-branch reusable knowledge from a branch's
+v2 memory, then archive the branch dir under `branches/_archived/`.
+
+In v2, the harvest source is preferentially `pending-promotion.md` (content
+that capture auto-staged as cross-branch-reusable) plus `decisions.md`. We
+still dump progress/risks/glossary in dry-run so the human can spot anything
+the heuristic missed, but the primary signal is pending-promotion.
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from dev_memory_common import (
+    ARCHIVE_INDEX_NAME,
+    append_archive_index,
+    append_log_event,
+    append_to_section,
+    archive_branch_dir,
+    archive_root_dir,
+    asset_paths,
+    build_archive_summary,
+    detect_no_git_mode,
+    get_branch_paths,
+    git_lines,
+    git_stdout,
+    read_json,
+    split_sections,
+    upsert_markdown_section,
+)
+
+
+def _read_sections(path):
+    if not path.exists():
+        return []
+    content = path.read_text(encoding="utf-8")
+    _, sections = split_sections(content)
+    return [{"title": title, "body": body} for title, body in sections]
+
+
+def _git_status(repo_root, default_base):
+    if default_base is None:
+        return {"ahead": None, "uncommitted": None, "default_base": None}
+    raw = git_stdout(["rev-list", "--count", f"{default_base}..HEAD"], cwd=repo_root, check=False)
+    try:
+        ahead = int(raw)
+    except (TypeError, ValueError):
+        ahead = None
+    uncommitted = bool(git_lines(["status", "--porcelain"], cwd=repo_root, check=False))
+    return {"ahead": ahead, "uncommitted": uncommitted, "default_base": default_base}
+
+
+def command_dry_run(args):
+    if detect_no_git_mode(args.repo):
+        print(json.dumps({"error": "no-git mode: graduate has nothing to archive (no branches exist)"}, ensure_ascii=False))
+        return 1
+
+    repo_root, branch_name, branch_key, _, repo_key, repo_dir, branch_dir = get_branch_paths(args.repo, args.context_dir, args.branch)
+
+    if not branch_dir.exists():
+        print(json.dumps({"error": f"branch memory not initialized: {branch_dir}"}, ensure_ascii=False))
+        return 1
+
+    paths = asset_paths(repo_dir, branch_dir)
+    branch_manifest = read_json(paths["manifest"])
+    repo_manifest = read_json(paths["repo_manifest"])
+    default_base = branch_manifest.get("default_base") or repo_manifest.get("default_base")
+
+    payload = {
+        "repo_root": str(repo_root),
+        "repo_key": repo_key,
+        "branch": branch_name,
+        "branch_key": branch_key,
+        "branch_dir": str(branch_dir),
+        "archive_destination": str(archive_root_dir(repo_dir) / f"{branch_key}__{datetime.now(timezone.utc).strftime('%Y%m%d')}"),
+        "git_status": _git_status(repo_root, default_base),
+        # v2: primary harvest source is pending-promotion.md (capture-staged
+        # cross-branch candidates) plus decisions.md. Progress/risks/glossary
+        # are dumped only for human cross-check.
+        "primary_sources": {
+            "pending-promotion.md": _read_sections(paths["pending_promotion"]),
+            "decisions.md": _read_sections(paths["decisions"]),
+        },
+        "cross_check_sources": {
+            "progress.md": _read_sections(paths["progress"]),
+            "risks.md": _read_sections(paths["risks"]),
+            "glossary.md": _read_sections(paths["glossary"]),
+            "overview.md": _read_sections(paths["overview"]),
+        },
+        "repo_files": {
+            "overview.md": _read_sections(paths["repo_overview"]),
+            "decisions.md": _read_sections(paths["repo_decisions"]),
+            "glossary.md": _read_sections(paths["repo_glossary"]),
+        },
+        "harvest_targets": {
+            "repo_overview": ["长期目标与边界", "仓库级关键约束"],
+            "repo_decisions": ["跨分支通用决策"],
+            "repo_glossary": ["长期有效背景", "共享入口", "共享注意点"],
+        },
+        "instructions": (
+            "优先读 primary_sources 抓取通用知识（剥离业务名词后），按 harvest-schema.md 写出 harvest.json。"
+            "cross_check_sources 只做漏网之鱼检查，不是主源。确认无误后跑 graduate apply。"
+        ),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _apply_entries(target_path, entries):
+    n = 0
+    for entry in entries or []:
+        section = entry.get("section")
+        body = entry.get("body", "")
+        mode = entry.get("mode", "append")
+        if not section:
+            raise ValueError(f"harvest entry missing 'section': {entry}")
+        if mode == "append":
+            append_to_section(target_path, section, body)
+        elif mode == "replace":
+            upsert_markdown_section(target_path, section, body)
+        else:
+            raise ValueError(f"harvest entry has unknown mode '{mode}': {entry}")
+        n += 1
+    return n
+
+
+def command_apply(args):
+    if detect_no_git_mode(args.repo):
+        print(json.dumps({"error": "no-git mode: graduate has nothing to archive"}, ensure_ascii=False))
+        return 1
+
+    repo_root, branch_name, branch_key, _, repo_key, repo_dir, branch_dir = get_branch_paths(args.repo, args.context_dir, args.branch)
+
+    if not branch_dir.exists():
+        print(json.dumps({"error": f"branch memory not initialized: {branch_dir}"}, ensure_ascii=False))
+        return 1
+
+    harvest = read_json(Path(args.harvest_file))
+    if not harvest:
+        print(json.dumps({"error": f"harvest file empty or missing: {args.harvest_file}"}, ensure_ascii=False))
+        return 1
+
+    # Reject unknown top-level keys explicitly. The most common failure mode
+    # is a pre-v2 harvest.json still using repo_context / repo_sources —
+    # without this check those entries would be silently dropped while
+    # archive=true still mv'd the branch away, leaving the shared layer
+    # un-updated with no visible error.
+    known_keys = {"repo_overview", "repo_decisions", "repo_glossary", "notes", "archive"}
+    unknown_keys = sorted(k for k in harvest.keys() if k not in known_keys)
+    if unknown_keys:
+        legacy_hint = ""
+        if any(k in {"repo_context", "repo_sources"} for k in unknown_keys):
+            legacy_hint = (
+                " (v1 schema? repo_context → repo_decisions or repo_glossary; "
+                "repo_sources → repo_glossary; see references/harvest-schema.md)"
+            )
+        print(
+            json.dumps(
+                {"error": f"unknown harvest key(s): {unknown_keys}{legacy_hint}"},
+                ensure_ascii=False,
+            )
+        )
+        return 1
+
+    paths = asset_paths(repo_dir, branch_dir)
+
+    # v2: the harvest target keys match the new repo-shared files.
+    applied = {
+        "repo_overview": _apply_entries(paths["repo_overview"], harvest.get("repo_overview")),
+        "repo_decisions": _apply_entries(paths["repo_decisions"], harvest.get("repo_decisions")),
+        "repo_glossary": _apply_entries(paths["repo_glossary"], harvest.get("repo_glossary")),
+    }
+    total = sum(applied.values())
+
+    branch_manifest = read_json(paths["manifest"])
+    default_base = branch_manifest.get("default_base")
+    git_log = []
+    if default_base:
+        git_log = git_lines(["log", "--oneline", f"{default_base}..HEAD"], cwd=repo_root, check=False)
+
+    summary_md = build_archive_summary(branch_manifest, git_log, harvest_notes=harvest.get("notes"))
+    summary_path = branch_dir / "archive_summary.md"
+    summary_path.write_text(summary_md, encoding="utf-8")
+
+    do_archive = harvest.get("archive", True)
+    archive_dst = None
+    if do_archive:
+        date_tag = datetime.now(timezone.utc).strftime("%Y%m%d")
+        archive_dst = archive_root_dir(repo_dir) / f"{branch_key}__{date_tag}"
+        archive_branch_dir(branch_dir, archive_dst)
+        head = branch_manifest.get("last_seen_head") or "<unknown>"
+        notes_short = (harvest.get("notes") or "").splitlines()[0][:80] if harvest.get("notes") else ""
+        index_line = f"- {date_tag[:4]}-{date_tag[4:6]}-{date_tag[6:8]} {branch_name} (HEAD {head}) → harvested {total} entries: {notes_short}"
+        append_archive_index(archive_root_dir(repo_dir) / ARCHIVE_INDEX_NAME, index_line)
+
+    # Event log: graduate is a repo-layer event (the branch log is gone with
+    # the archive move). One row in repo/log.md captures the harvest + archive
+    # destination so future readers can scan the timeline.
+    log_summary = f"branch={branch_name} harvested={total}"
+    log_details = [
+        ("harvested_total", total),
+        ("repo_overview", applied["repo_overview"]),
+        ("repo_decisions", applied["repo_decisions"]),
+        ("repo_glossary", applied["repo_glossary"]),
+        ("archived_to", archive_dst.name if archive_dst else "no"),
+    ]
+    if harvest.get("notes"):
+        log_details.append(("notes", (harvest["notes"] or "").splitlines()[0][:120]))
+    append_log_event(
+        paths.get("repo_log"),
+        "graduate",
+        kind="apply",
+        summary=log_summary,
+        details=log_details,
+    )
+
+    print(json.dumps({
+        "branch": branch_name,
+        "harvested": applied,
+        "harvested_total": total,
+        "archive_summary": str((archive_dst or branch_dir) / "archive_summary.md"),
+        "archived_to": str(archive_dst) if archive_dst else None,
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+def command_index(args):
+    if detect_no_git_mode(args.repo):
+        print(json.dumps({"error": "no-git mode: no archive index"}, ensure_ascii=False))
+        return 1
+
+    repo_root, _, _, _, _, repo_dir, _ = get_branch_paths(args.repo, args.context_dir, args.branch or "HEAD")
+    index_path = archive_root_dir(repo_dir) / ARCHIVE_INDEX_NAME
+    if not index_path.exists():
+        print(json.dumps({"index_path": str(index_path), "exists": False, "entries": []}, ensure_ascii=False))
+        return 0
+    text = index_path.read_text(encoding="utf-8")
+    entries = [line for line in text.splitlines() if line.startswith("- ")]
+    print(json.dumps({
+        "index_path": str(index_path),
+        "exists": True,
+        "entries": entries,
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+def main():
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--repo", default=".", help="Path inside the target Git repository")
+    common.add_argument("--context-dir", help="User-home storage root override")
+    common.add_argument("--branch", help="Branch name override (defaults to current)")
+
+    parser = argparse.ArgumentParser(description="Graduate a branch's dev-memory: harvest reusable knowledge, then archive.")
+    sub = parser.add_subparsers(dest="command")
+    sub.required = True
+
+    p_dry = sub.add_parser("dry-run", parents=[common], help="Dump branch + repo sections for harvest review")
+    p_dry.set_defaults(func=command_dry_run)
+
+    p_apply = sub.add_parser("apply", parents=[common], help="Apply harvest patch and archive branch dir")
+    p_apply.add_argument("--harvest-file", required=True, help="Path to harvest.json")
+    p_apply.set_defaults(func=command_apply)
+
+    p_idx = sub.add_parser("index", parents=[common], help="List archived branches")
+    p_idx.set_defaults(func=command_index)
+
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except Exception as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/lib/dev_memory_setup.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""
+dev-memory-setup: initialize the skeleton AND merge any unsorted.md content
+into the structured v2 files. In v2, setup is no longer a gate — capture
+lazy-inits files on first write. Setup's job is now:
+
+  1. Ensure skeleton exists (idempotent).
+  2. Scan unsorted.md and present each entry to the user for classification.
+  3. Route user's choices into decisions/progress/risks/glossary/shared-*.
+  4. Mark manifest.setup_completed = true.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from dev_memory_common import (
+    ensure_branch_paths_exist,
+    get_setup_completed,
+    mark_setup_completed,
+    split_sections,
+    upsert_markdown_section,
+)
+
+
+def _extract_unsorted_entries(unsorted_path):
+    """Parse unsorted.md into a list of individual entries. Each entry is a
+    bullet line or a paragraph; we split on top-level bullets to give the
+    user one-at-a-time classification. Returns [] if empty or only
+    placeholder text.
+    """
+    if not unsorted_path.exists():
+        return []
+    content = unsorted_path.read_text(encoding="utf-8")
+    _, sections = split_sections(content)
+    entries = []
+    for _, body in sections:
+        for line in body.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if stripped in ("- 待补充", "- 待刷新"):
+                continue
+            # Only include top-level bullets; nested lines get combined.
+            if stripped.startswith("- "):
+                entries.append(stripped[2:].strip())
+            elif entries:
+                # Continuation of the previous bullet.
+                entries[-1] = entries[-1] + " " + stripped
+    return entries
+
+
+def _report_skeleton(paths, setup_completed):
+    """Build the `files` key for the setup output."""
+    return {
+        "setup_completed": setup_completed,
+        "files": {key: str(value) for key, value in paths.items()},
+    }
+
+
+def command_init(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+    report = _report_skeleton(paths, get_setup_completed(paths["manifest"]))
+
+    unsorted_entries = _extract_unsorted_entries(paths["unsorted"])
+    report.update(
+        {
+            "repo_root": str(repo_root),
+            "repo_key": repo_key,
+            "branch": branch_name,
+            "storage_root": str(storage_root),
+            "repo_dir": str(repo_dir),
+            "branch_dir": str(branch_dir),
+            "unsorted_entries": unsorted_entries,
+            "unsorted_count": len(unsorted_entries),
+            "mode": "init",
+        }
+    )
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+# Merge plan: the caller (agent) receives unsorted entries from `init`,
+# asks the user (or classifies with LLM) which bucket each goes to, then
+# submits the classification as a JSON file to `merge-unsorted`.
+#
+# plan.json format:
+# {
+#   "classifications": [
+#     {"entry": "original bullet text", "kind": "decision|progress|next|risk|glossary|source|shared-*|skip"},
+#     ...
+#   ],
+#   "clear_unsorted_on_done": true
+# }
+#
+# The kind values match dev-memory-capture's KIND_MAP.
+
+_SETUP_KIND_TO_TARGET = {
+    "decision": ("decisions", "关键决策与原因"),
+    "progress": ("progress", "当前进展"),
+    "next": ("progress", "下一步"),
+    "risk": ("risks", "阻塞与注意点"),
+    "glossary": ("glossary", "当前有效上下文"),
+    "source": ("glossary", "分支源资料入口"),
+    "shared-decision": ("repo_decisions", "跨分支通用决策"),
+    "shared-context": ("repo_glossary", "长期有效背景"),
+    "shared-source": ("repo_glossary", "共享入口"),
+}
+
+
+def _apply_classifications(paths, classifications):
+    """Group classifications by target section, then upsert-merge each group
+    into the target file. Returns a per-section tally.
+    """
+    groups = {}  # (file_key, section) -> list of entry strings
+    skipped = 0
+    for item in classifications or []:
+        entry = (item.get("entry") or "").strip()
+        kind = (item.get("kind") or "").strip()
+        if not entry:
+            continue
+        if kind == "skip" or not kind:
+            skipped += 1
+            continue
+        target = _SETUP_KIND_TO_TARGET.get(kind)
+        if not target:
+            skipped += 1
+            continue
+        groups.setdefault(target, []).append(entry)
+
+    tally = {}
+    for (file_key, section), entries in groups.items():
+        # Append to existing section rather than replace — preserves whatever
+        # was already in decisions/progress/etc. before setup merge ran.
+        from dev_memory_common import append_to_section
+        body = "\n".join(f"- {e}" for e in entries)
+        path = paths[file_key]
+        append_to_section(path, section, body)
+        tally[f"{file_key}:{section}"] = len(entries)
+    return {"applied": tally, "skipped": skipped}
+
+
+def _clear_unsorted(unsorted_path):
+    """After merge, reset unsorted.md to its placeholder template."""
+    from dev_memory_common import template_unsorted
+    unsorted_path.write_text(template_unsorted(), encoding="utf-8")
+
+
+def command_merge_unsorted(args):
+    repo_root, branch_name, branch_key, storage_root, repo_key, repo_dir, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+
+    plan = json.loads(Path(args.plan_file).read_text(encoding="utf-8"))
+    classifications = plan.get("classifications") or []
+    clear_on_done = plan.get("clear_unsorted_on_done", True)
+
+    result = _apply_classifications(paths, classifications)
+
+    if clear_on_done and result["applied"]:
+        _clear_unsorted(paths["unsorted"])
+
+    mark_setup_completed(paths["manifest"])
+
+    print(
+        json.dumps(
+            {
+                "repo_root": str(repo_root),
+                "repo_key": repo_key,
+                "branch": branch_name,
+                "branch_dir": str(branch_dir),
+                "mode": "merge-unsorted",
+                "applied": result["applied"],
+                "skipped": result["skipped"],
+                "unsorted_cleared": clear_on_done and bool(result["applied"]),
+                "setup_completed": True,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def command_mark_completed(args):
+    """Just flip setup_completed to true without touching unsorted. Use when
+    there's nothing to merge but the user wants to formally mark setup done
+    so classifier defaults shift from unsorted to progress."""
+    repo_root, branch_name, _, _, _, _, branch_dir, paths = ensure_branch_paths_exist(
+        args.repo, args.context_dir, args.branch
+    )
+    mark_setup_completed(paths["manifest"])
+    print(
+        json.dumps(
+            {
+                "branch": branch_name,
+                "branch_dir": str(branch_dir),
+                "mode": "mark-completed",
+                "setup_completed": True,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def _add_common_args(p):
+    p.add_argument("--repo", default=".", help="Path inside the target Git repository")
+    p.add_argument("--context-dir", help="User-home storage root. Defaults to ~/.dev-memory/repos")
+    p.add_argument("--branch", help="Branch name. Defaults to the current checked-out branch")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Initialize repo+branch dev-memory skeleton, merge unsorted content, and mark setup done.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="Ensure skeleton exists, return paths + unsorted entries for review")
+    _add_common_args(p_init)
+
+    p_merge = sub.add_parser("merge-unsorted", help="Apply a classification plan over unsorted entries")
+    _add_common_args(p_merge)
+    p_merge.add_argument("--plan-file", required=True, help="Path to JSON plan with classifications")
+
+    p_mark = sub.add_parser("mark-completed", help="Flip manifest.setup_completed = true without merging")
+    _add_common_args(p_mark)
+
+    # Backward-compat: old callers ran `init_dev_memory.py --repo X` with no
+    # subcommand. If argv starts with a flag (not a known subcommand or help),
+    # inject `init` so the legacy invocation still works.
+    argv = sys.argv[1:]
+    known_cmds = {"init", "merge-unsorted", "mark-completed"}
+    if argv and argv[0] not in known_cmds and argv[0] not in ("-h", "--help"):
+        argv = ["init"] + argv
+
+    args = parser.parse_args(argv)
+    try:
+        return {
+            "init": command_init,
+            "merge-unsorted": command_merge_unsorted,
+            "mark-completed": command_mark_completed,
+        }[args.command](args)
+    except Exception as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())