cg-code-graph 0.23.12__tar.gz → 0.23.14__tar.gz

{cg_code_graph-0.23.12/cg_code_graph.egg-info → cg_code_graph-0.23.14}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cg-code-graph
-Version: 0.23.12
-Summary: cg: a code graph of routes, calls, data access and platform boundaries for agents and humans (CLI + MCP server)
+Version: 0.23.14
+Summary: Python package on PyPI (not a Rust crate): a code graph of routes, calls, data access and platform boundaries. pip install cg-code-graph
 Author: cyberchronos00
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/cyberchronos00/code-graph
@@ -31,6 +31,8 @@ Dynamic: license-file
 
 **See everything a change affects before you make it: a local, deterministic dependency graph of routes, calls, tables and config, with `file:line` evidence for every hop.**
 
+cg is a Python package on PyPI: `pip install cg-code-graph` (or `pipx install cg-code-graph`, or `uv tool install cg-code-graph`). It is not a Rust crate. `cargo install cg-code-graph` does not apply.
+
 For you and your AI agent (CLI + MCP). No LLM in the graph.
 
 <!-- mcp-name: io.github.cyberchronos00/cg-code-graph -->
@@ -46,13 +48,13 @@ For you and your AI agent (CLI + MCP). No LLM in the graph.
 ## Quick start
 
 ```bash
-pipx install cg-code-graph          # or: uv tool install cg-code-graph
+pipx install cg-code-graph          # Python package. Not a Rust crate (cargo install does not apply).
 cg index . --db out/graph.db        # prints starter queries for your repo
-cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server and a "use cg first" agent rule
+cg install --yes --project          # non-interactive MCP register; --host cursor|claude|codex|vscode|…
 cg reaches table:orders --db out/graph.db   # any table, connection or config key
 ```
 
-Try it on a bundled sample, link a frontend to a backend, or connect an agent over MCP: [Quick start guide](https://code-graph.cyberchronos00.workers.dev/docs/quickstart). Other install options (install.sh, Windows, exact-mode toolchains): [Install](https://code-graph.cyberchronos00.workers.dev/docs/install).
+Try it on a bundled sample, link a frontend to a backend, or connect an agent over MCP: [Quick start guide](https://code-graph.cyberchronos00.workers.dev/docs/quickstart). Other install options (install.sh, Windows, exact-mode toolchains): [Install](https://code-graph.cyberchronos00.workers.dev/docs/install). A clean cloud or CI image: [Cloud agent bootstrap](https://code-graph.cyberchronos00.workers.dev/docs/cloud-agents).
 
 `cg reaches table:store_books` on the bundled Django sample:
 

{cg_code_graph-0.23.12 → cg_code_graph-0.23.14}/README.md

@@ -4,6 +4,8 @@
 
 **See everything a change affects before you make it: a local, deterministic dependency graph of routes, calls, tables and config, with `file:line` evidence for every hop.**
 
+cg is a Python package on PyPI: `pip install cg-code-graph` (or `pipx install cg-code-graph`, or `uv tool install cg-code-graph`). It is not a Rust crate. `cargo install cg-code-graph` does not apply.
+
 For you and your AI agent (CLI + MCP). No LLM in the graph.
 
 <!-- mcp-name: io.github.cyberchronos00/cg-code-graph -->
@@ -19,13 +21,13 @@ For you and your AI agent (CLI + MCP). No LLM in the graph.
 ## Quick start
 
 ```bash
-pipx install cg-code-graph          # or: uv tool install cg-code-graph
+pipx install cg-code-graph          # Python package. Not a Rust crate (cargo install does not apply).
 cg index . --db out/graph.db        # prints starter queries for your repo
-cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server and a "use cg first" agent rule
+cg install --yes --project          # non-interactive MCP register; --host cursor|claude|codex|vscode|…
 cg reaches table:orders --db out/graph.db   # any table, connection or config key
 ```
 
-Try it on a bundled sample, link a frontend to a backend, or connect an agent over MCP: [Quick start guide](https://code-graph.cyberchronos00.workers.dev/docs/quickstart). Other install options (install.sh, Windows, exact-mode toolchains): [Install](https://code-graph.cyberchronos00.workers.dev/docs/install).
+Try it on a bundled sample, link a frontend to a backend, or connect an agent over MCP: [Quick start guide](https://code-graph.cyberchronos00.workers.dev/docs/quickstart). Other install options (install.sh, Windows, exact-mode toolchains): [Install](https://code-graph.cyberchronos00.workers.dev/docs/install). A clean cloud or CI image: [Cloud agent bootstrap](https://code-graph.cyberchronos00.workers.dev/docs/cloud-agents).
 
 `cg reaches table:store_books` on the bundled Django sample:
 

{cg_code_graph-0.23.12 → cg_code_graph-0.23.14}/cg_code_graph/__init__.py

@@ -1,2 +1,2 @@
 """code-graph: deterministic code knowledge graph (beta)."""
-__version__ = "0.23.12"
+__version__ = "0.23.14"

{cg_code_graph-0.23.12 → cg_code_graph-0.23.14}/cg_code_graph/apps.py

@@ -56,7 +56,8 @@ def index_apps(root: str | Path, db: str | Path, cfg: dict, scip=None, python_ro
                            include_generated=include_generated)
         out["apps"].append({"name": a["name"], "root": a["root"] or ".", "role": a["role"], "db": str(per_app[a["name"]]),
                             "nodes": st.get("nodes"), "edges": st.get("edges"), "index_seconds": st.get("index_seconds"),
-                            "frameworks": sorted(((st.get("presets") or {}).get("frameworks") or {}))})
+                            "frameworks": sorted(((st.get("presets") or {}).get("frameworks") or {})),
+                            **({"incomplete": st["incomplete"]} if st.get("incomplete") else {})})
     if len(apps) == 1:
         shutil.copyfile(per_app[apps[0]["name"]], db)
         out["db_is"] = f"graph of app {apps[0]['name']}"

{cg_code_graph-0.23.12 → cg_code_graph-0.23.14}/cg_code_graph/cli.py

@@ -12,7 +12,7 @@
   python -m cg_code_graph.cli api-calls <all|unmatched|substring|glob*> --db out/combined.db
   python -m cg_code_graph.cli plan list|load|validate|check|baseline [<name>] --db out/combined.db [--verify] [--summary] [--json]
   python -m cg_code_graph.cli routes --db ... [--writes [TABLE]] [--reaches SPEC...] [--missing NAME] [--unguarded]
-  python -m cg_code_graph.cli search <name> --db ... [--kind route]
+  python -m cg_code_graph.cli search <name> --db ... [--kind route] [--compact]
   python -m cg_code_graph.cli channels [PATTERN] --db ...   (who can join, which events publish, which client code listens)
   python -m cg_code_graph.cli tests <spec> --db ...          (tests covering a symbol / route / table: direct + transitive)
   python -m cg_code_graph.cli bridges [PATTERN] --db ... [--protocol capacitor] [--unmatched]   (web / native bridge calls)
@@ -35,6 +35,16 @@ import sys
 from .core.store import GraphStore
 from . import query as Q
 from .bridges import PROTOCOLS as BRIDGE_PROTOCOLS
+from .cli_errors import explain_parse_error
+
+_COMPACT_SEARCH_LIMIT = 8
+_COMPACT_SNIPPET_LINES = 40
+_COMPACT_CALLERS = 8
+_COMPACT_ENTRIES = 5
+_COMPACT_HELP = ("short agent summary (also CG_OUTPUT=compact): fewer rows, short paths, and how to expand. "
+                 "Search shows 8 nodes unless --limit is set; snippet shows 40 lines unless --max-lines is set; "
+                 "impact omits evidence paths. The default output is unchanged. "
+                 "For a token cap, use cg explore --budget")
 
 
 def _parse_repo(spec: str) -> tuple[str, str, str]:
@@ -58,7 +68,8 @@ def _add_install_parser(sub, uninstall: bool):
     from .mcp_install import HOSTS
     name = "uninstall" if uninstall else "install"
     help_ = ("remove the cg MCP server entry from a host config" if uninstall else
-             "register the cg MCP server (key cg) in a host config; previews and asks first")
+             "register the cg MCP server (key cg) in a host config; previews and asks first "
+             "(--yes writes without asking; with no host detected it writes the Cursor project config)")
     p = sub.add_parser(name, help=help_)
     p.add_argument("--host", action="append", choices=[*HOSTS, "all"],
                    help="MCP host (repeatable). Default: hosts already present for this scope")
@@ -86,6 +97,68 @@ def _add_install_parser(sub, uninstall: bool):
         p.add_argument("--graphs", help="registry file for --migrate (default: ~/.config/cg/graphs.toml)")
 
 
+class _CgParser(argparse.ArgumentParser):
+    """Parent parser whose rejected flags and unknown commands stay on one screen."""
+
+    def parse_args(self, args=None, namespace=None):
+        argv = sys.argv[1:] if args is None else list(args)
+        self._cg_argv = argv
+        self._cg_root = self
+        for action in self._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                for sub in action.choices.values():
+                    sub._cg_argv = argv
+                    sub._cg_root = self
+        return super().parse_args(args, namespace)
+
+    def error(self, message):
+        text = explain_parse_error(self, message, getattr(self, "_cg_argv", None))
+        if text:
+            self.exit(2, text if text.endswith("\n") else text + "\n")
+        super().error(message)
+
+
+def _opt_given(args, flag: str) -> bool:
+    return any(arg == flag or arg.startswith(flag + "=") for arg in args)
+
+
+def _compact_output(parsed, args) -> bool:
+    """Text-only compact profile. `--json` keeps the document shape."""
+    if getattr(parsed, "json", False):
+        return False
+    if getattr(parsed, "compact", False):
+        return True
+    return os.environ.get("CG_OUTPUT", "").strip().lower() == "compact"
+
+
+def _print_impact_compact(st, parsed, res) -> None:
+    """First callers and entry points, no evidence paths, and how to expand."""
+    callers, entries = res["callers"], res["entry_points"]
+    shown_c = callers[:_COMPACT_CALLERS]
+    print(f"callers (transitive): {len(callers)}  showing {len(shown_c)}")
+    labels = _impact_labels(shown_c, lambda c: c.get("fqn") or c["id"], lambda c: c.get("module") or c.get("kind"))
+    for caller, label in zip(shown_c, labels):
+        loc = f"  @ {Q.short_path(caller.get('file'))}:{caller.get('line')}" if caller.get("file") else ""
+        print(f"  d={caller['depth']} [{caller['module'] or caller['kind']}] {label}{loc}{Q.caller_label(caller)}")
+    if len(callers) > len(shown_c):
+        print(f"{len(callers) - len(shown_c)} more callers, drop --compact for the full list")
+    shown_e = entries[:_COMPACT_ENTRIES]
+    print(f"entry points: {len(entries)}  showing {len(shown_e)}")
+    for entry in shown_e:
+        loc = f"  @ {Q.short_path(entry.get('file'))}:{entry.get('line')}" if entry.get("file") else ""
+        print(f"  {entry['entry_kind']:16} {entry.get('fqn') or entry['name']}{loc}  conf={entry['path_confidence']}")
+    if len(entries) > len(shown_e):
+        print(f"{len(entries) - len(shown_e)} more entry points, drop --compact for the full list")
+    if any(row.get("candidate") for row in shown_c + shown_e):
+        print(Q.CANDIDATE_NOTE)
+    if parsed.plans_dir:
+        from . import plans as P
+        hits = P.snapshot_clients(st, [e["id"] for e in entries if e["id"].startswith("route:")], parsed.plans_dir)
+        print(f"external clients (snapshot, not indexed): {len(hits)}")
+    print("expand: drop --compact or unset CG_OUTPUT. token cap: cg explore --budget")
+    _note(_completeness(st, list(res["targets"]) + [c["id"] for c in callers]), False)
+
+
 def _impact_labels(rows: list[dict], name_of, group_of) -> list[str]:
     """Display names for one impact listing. Same-name rows in one group gain a file suffix."""
     from collections import defaultdict
@@ -113,14 +186,14 @@ def _version_text(version: str) -> str:
 
 def main(argv=None):
     from . import __version__
-    ap = argparse.ArgumentParser(prog="cg")
+    ap = _CgParser(prog="cg")
     args_in = sys.argv[1:] if argv is None else list(argv)
     if args_in[:1] == ["--version"]:
         print(_version_text(__version__))   # printed here: argparse's version action re-wraps a second line
         return 0
     ap.add_argument("--version", action="version", version=f"cg {__version__}")
     sub = ap.add_subparsers(dest="cmd", required=True)
-    p = sub.add_parser("index", help="detect languages / frameworks under ROOT and build the graph DB (stats JSON on stdout, coverage on stderr)"); p.add_argument("root"); p.add_argument("--db", required=True); p.add_argument("--name"); p.add_argument("--scip", action="append"); p.add_argument("--gates", help="gate scenarios JSON (e.g. examples/bookstore.gates.json)")
+    p = sub.add_parser("index", help="detect languages / frameworks under ROOT and build the graph DB (stats JSON on stdout, coverage on stderr)"); p.add_argument("root"); p.add_argument("--db", required=True); p.add_argument("--name"); p.add_argument("--scip", action="append"); p.add_argument("--gates", help="gate scenarios JSON (e.g. examples/bookstore.gates.json)"); p.add_argument("--allow-incomplete", action="store_true", help="exit 0 even when most supported source files could not be indexed (missing PHP / Node / Dart toolchain); the WARNING / ERROR lines still print")
     p.add_argument("--python-root", action="append", metavar="DIR",
                    help="Python source root, relative to ROOT (repeatable); replaces detection and python.source_roots in .cg.yaml")
     p.add_argument("--no-apps", action="store_true",
@@ -221,6 +294,7 @@ def main(argv=None):
     p = sub.add_parser("search", help="nodes by name / FQN substring, plus route middleware / guard / auth names")
     p.add_argument("name"); p.add_argument("--db", required=True); p.add_argument("--kind"); p.add_argument("--limit", type=int, default=30)
     p.add_argument("--json", action="store_true"); p.add_argument("--platform", help="only code built for this target (windows, linux, macos, ios, android, web; see docs/platforms.md)")
+    p.add_argument("--compact", action="store_true", help=_COMPACT_HELP)
     p = sub.add_parser("channels", help="broadcast channels: who can join (auth callback + checks), which events publish on it, which client code / pages listen")
     p.add_argument("pattern", nargs="?", help="channel pattern or concrete name (orders.{id}, orders.42, orders.*); omit to list all")
     p.add_argument("--db", required=True); p.add_argument("--json", action="store_true"); p.add_argument("--no-source", action="store_true")
@@ -328,10 +402,13 @@ def main(argv=None):
     p.add_argument("--context", type=int, default=0, help="extra lines of context around the symbol (default 0)")
     p.add_argument("--max-lines", type=int, default=200, help="cap the printed body (default 200); extra lines are noted")
     p.add_argument("--json", action="store_true")
+    p.add_argument("--compact", action="store_true", help=_COMPACT_HELP)
     p = sub.add_parser("explore", help="question or spec → source, entry points, call paths and blast radius")
     p.add_argument("query", help="a free-text question, a source file, or a symbol spec")
     p.add_argument("--db", required=True)
-    p.add_argument("--budget", type=int, default=3000, help="token budget (clamped to 500..20000, default 3000)")
+    p.add_argument("--budget", type=int, default=3000,
+                   help="token budget (clamped to 500..20000, default 3000). "
+                        "search, snippet and impact name this flag from --help and from --compact")
     p.add_argument("--max-symbols", type=int, default=4, help="how many symbols to expand (default 4)")
     p.add_argument("--json", action="store_true")
     p = sub.add_parser("agents", help="opt-in: add cg usage guidance (and the cg MCP entry) to AGENTS.md / CLAUDE.md / Cursor rules; previews and asks first")
@@ -394,6 +471,7 @@ def main(argv=None):
             p.add_argument("--platform", help="only code built for this target (windows, linux, macos, ios, android, web; see docs/platforms.md)")
         if name == "impact":
             p.add_argument("--plans-dir", help="also list external clients from the snapshot files in this directory (e.g. examples/plans)")
+            p.add_argument("--compact", action="store_true", help=_COMPACT_HELP)
     a = ap.parse_args(argv)
 
     if a.cmd == "index":
@@ -413,7 +491,13 @@ def main(argv=None):
                                      include_generated=a.include_generated)
                 print(json.dumps({k: v for k, v in summary.items()}, indent=2, default=str))
                 print(render_apps(summary), file=sys.stderr)
-                return
+                from .coverage import incomplete_lines
+                fatal = False
+                for app in summary.get("apps") or ():
+                    for ln in incomplete_lines(app.get("incomplete"), allow=a.allow_incomplete, where=f"app {app['name']}"):
+                        print(ln, file=sys.stderr)
+                    fatal = fatal or bool((app.get("incomplete") or {}).get("fatal"))
+                return 3 if fatal and not a.allow_incomplete else None
             st = index_project(a.root, a.db, a.name, a.scip, gates=a.gates, python_roots=a.python_root,
                                include_generated=a.include_generated)
         except ConfigError as ex:
@@ -422,7 +506,12 @@ def main(argv=None):
         print(json.dumps(st, indent=2, default=str))
         from .coverage import render_summary
         print(render_summary({"": st.get("coverage")}, db=a.db), file=sys.stderr)  # stdout stays pure JSON
-        return
+        from .coverage import incomplete_lines
+        inc = st.get("incomplete")
+        for ln in incomplete_lines(inc, allow=a.allow_incomplete):
+            print(ln, file=sys.stderr)
+        # a mostly-unindexed project is an error, so `rc == 0 && nodes > 0` checks do not accept it (#239)
+        return 3 if inc and inc.get("fatal") and not a.allow_incomplete else None
     if a.cmd == "doctor":
         from .doctor import render, report
         r = report(a.root, scip=a.scip)
@@ -523,8 +612,17 @@ def main(argv=None):
         print(json.dumps(rows, indent=1) if a.json else render_starters(rows))
         return
     if a.cmd == "snippet":
-        res = Q.snippet(GraphStore(a.db), a.spec, context=a.context, max_lines=a.max_lines)
-        print(json.dumps(res, indent=1, default=str) if a.json else Q.render_snippet(res))
+        context, max_lines = a.context, a.max_lines
+        compact = _compact_output(a, args_in)
+        if compact and not _opt_given(args_in, "--max-lines"):
+            max_lines = min(max_lines, _COMPACT_SNIPPET_LINES)
+        res = Q.snippet(GraphStore(a.db), a.spec, context=context, max_lines=max_lines)
+        if a.json:
+            print(json.dumps(res, indent=1, default=str))
+        elif compact:
+            print(Q.render_snippet_compact(res))
+        else:
+            print(Q.render_snippet(res))
         return 0 if res.get("status") == "ok" else 1
     if a.cmd == "explore":
         from . import explore as EX
@@ -697,8 +795,25 @@ def main(argv=None):
             _note(_completeness(st, res.get("targets")), False)
         return
     if a.cmd == "search":
-        res = Q.search(st, a.name, kind=a.kind, limit=a.limit, platform=a.platform)
-        print(json.dumps(res, indent=1, default=str) if a.json else Q.render_search(res))
+        limit = a.limit
+        compact = _compact_output(a, args_in)
+        if compact and not _opt_given(args_in, "--limit"):
+            limit = min(limit, _COMPACT_SEARCH_LIMIT)
+        res = Q.search(st, a.name, kind=a.kind, limit=limit, platform=a.platform)
+        if a.json:
+            print(json.dumps(res, indent=1, default=str))
+        elif compact:
+            more, note = 0, None
+            if a.platform:
+                if len(res["nodes"]) == limit:
+                    probe = Q.search(st, a.name, kind=a.kind, limit=limit + 1, platform=a.platform)
+                    if len(probe["nodes"]) > limit:
+                        note = "1+ more, raise --limit"
+            else:
+                more = max(0, Q.search_node_total(st, a.name, a.kind) - len(res["nodes"]))
+            print(Q.render_search_compact(res, more=more, more_note=note))
+        else:
+            print(Q.render_search(res))
         return
     if a.cmd == "reaches":
         for spec in a.specs:
@@ -738,6 +853,9 @@ def main(argv=None):
             print(Q.connections_line(res["connections"]))
         if not res["callers"] and not res["entry_points"]:
             print(Q.explain_no_callers(st, a.spec, res["targets"], a.min_confidence)); return
+        if _compact_output(a, args_in):
+            _print_impact_compact(st, a, res)
+            return
         nc = res.get("callers_candidate") or 0
         print(f"callers (transitive): {len(res['callers']) - nc}" + (f" (+{nc} candidate)" if nc else ""))
         caller_names = _impact_labels(res["callers"], lambda c: c.get("fqn") or c["id"], lambda c: c.get("module") or c.get("kind"))

cg_code_graph-0.23.14/cg_code_graph/cli_errors.py

@@ -0,0 +1,171 @@
+"""Short errors for rejected flags and unknown subcommands.
+
+Grep- and git-style flags are not accepted: the reply names the long option
+that already exists on this command, or the commands that do have it.
+Unknown subcommands name the closest real commands instead of the full list.
+"""
+from __future__ import annotations
+
+import argparse
+import difflib
+import re
+
+# Rejected spellings -> long options that already exist somewhere on the CLI.
+FLAG_HINTS: dict[str, tuple[str, ...]] = {
+    "-k": ("--kind",),
+    "-A": ("--context", "--max-lines"),
+    "-C": ("--context",),
+    "--depth": ("--max-depth",),
+    "--name": ("--db",),
+}
+
+# Guesses that spelling distance does not connect to the real command.
+COMMAND_HINTS: dict[str, tuple[str, ...]] = {
+    "callers": ("impact", "node", "readers"),
+    "caller": ("impact", "node", "readers"),
+    "called-by": ("impact", "node", "readers"),
+    "whocalls": ("impact", "node", "readers"),
+    "who-calls": ("impact", "node", "readers"),
+    "callees": ("downstream", "node"),
+    "callee": ("downstream", "node"),
+    "find": ("search",),
+    "grep": ("search",),
+    "cat": ("snippet", "node"),
+    "source": ("snippet", "node"),
+}
+
+
+def explain_parse_error(parser: argparse.ArgumentParser, message: str, argv: list[str] | None) -> str | None:
+    """A one-screen stderr body, or None to keep argparse's own error."""
+    root = getattr(parser, "_cg_root", parser)
+    args = list(argv or getattr(parser, "_cg_argv", []) or [])
+    if message.startswith("unrecognized arguments:"):
+        return _unknown_args(root, message, args)
+    if message.startswith("argument cmd: invalid choice:"):
+        return _unknown_command(root, message)
+    return None
+
+
+def _subparsers(parser: argparse.ArgumentParser):
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _option_strings(parser: argparse.ArgumentParser) -> set[str]:
+    out: set[str] = set()
+    for action in parser._actions:
+        out.update(action.option_strings)
+    return out
+
+
+def _owners(root: argparse.ArgumentParser, option: str) -> list[str]:
+    action = _subparsers(root)
+    if action is None:
+        return []
+    return sorted(name for name, sub in action.choices.items() if option in _option_strings(sub))
+
+
+def _command(argv: list[str], names: set[str]) -> str | None:
+    for arg in argv:
+        if arg == "--":
+            return None
+        if arg in names:
+            return arg
+        if arg.startswith("-"):
+            continue
+        return None
+    return None
+
+
+def _normalize_flag(token: str) -> str:
+    if token.startswith("--") and "=" in token:
+        return token.split("=", 1)[0]
+    if re.fullmatch(r"-[A-Za-z]\d+", token):
+        return token[:2]
+    return token
+
+
+def _flag_hint(root: argparse.ArgumentParser, command: str | None, flag: str) -> str | None:
+    options = FLAG_HINTS.get(flag)
+    if not options:
+        return None
+    parts: list[str] = []
+    for opt in options:
+        owners = _owners(root, opt)
+        if not owners:
+            continue
+        if command and command in owners:
+            parts.append(opt)
+        else:
+            parts.append(f"{opt} (on {', '.join(owners)})")
+    if not parts:
+        return None
+    text = f"unknown {flag}; did you mean {' or '.join(parts)}?"
+    if flag == "--name":
+        named = _owners(root, "--name")
+        if named:
+            text += f" (--name sets the project name on {', '.join(named)})"
+    return text
+
+
+def _unknown_args(root: argparse.ArgumentParser, message: str, argv: list[str]) -> str:
+    action = _subparsers(root)
+    names = set(action.choices) if action is not None else set()
+    command = _command(argv, names)
+    tokens = message.split(":", 1)[1].strip().split()
+    hints: list[str] = []
+    leftover: list[str] = []
+    i = 0
+    while i < len(tokens):
+        token = tokens[i]
+        if token.startswith("-") and token != "-":
+            flag = _normalize_flag(token)
+            hint = _flag_hint(root, command, flag)
+            i += 1
+            values: list[str] = []
+            while i < len(tokens) and not (tokens[i].startswith("-") and tokens[i] != "-"):
+                values.append(tokens[i])
+                i += 1
+            if hint:
+                hints.append(hint)
+            else:
+                leftover.append(token)
+                leftover.extend(values)
+            continue
+        leftover.append(token)
+        i += 1
+    body: list[str] = list(hints)
+    if leftover:
+        body.append("unrecognized arguments: " + " ".join(leftover))
+    if not body:
+        body.append(message)
+    if leftover:
+        body.append(f"see `cg {command} --help`" if command else "see `cg --help`")
+    text = "cg: error: " + body[0]
+    if len(body) > 1:
+        text += "\n" + "\n".join(body[1:])
+    return text
+
+
+def _fmt_try(names: list[str]) -> str:
+    shown = [f"cg {name}" for name in names]
+    if len(shown) == 1:
+        return shown[0]
+    if len(shown) == 2:
+        return f"{shown[0]} or {shown[1]}"
+    return ", ".join(shown[:-1]) + ", or " + shown[-1]
+
+
+def _unknown_command(root: argparse.ArgumentParser, message: str) -> str:
+    action = _subparsers(root)
+    choices = list(action.choices) if action is not None else []
+    match = re.search(r"invalid choice: '([^']*)'", message)
+    name = match.group(1) if match else ""
+    picks = [cmd for cmd in COMMAND_HINTS.get(name, ()) if cmd in choices]
+    if not picks and name:
+        picks = difflib.get_close_matches(name, choices, n=3, cutoff=0.6)
+    if picks:
+        return f"cg: error: unknown command {name!r}; try: {_fmt_try(picks)}"
+    return f"cg: error: unknown command {name!r}; run `cg --help` for commands"