feat: lazy command loading for faster CLI startup

cloudbuild_pr.yaml

@@ -23,6 +23,9 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-39 && cd /tmp/build-39
       pip install --upgrade pip setuptools wheel build -q
+      # Create a local-only tag so setuptools-scm generates a real version
+      # instead of 0.0.0.dev0. This tag is never pushed.
+      git tag 99.0.0.dev39 2>/dev/null || true
       python -m build -q
       ls -lh dist/
 
@@ -33,6 +36,27 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+
+      print(f'importlib.metadata: {meta_ver}')
+      print(f'limacharlie.__version__: {attr_ver}')
+
+      assert meta_ver == attr_ver, (
+          f'Version mismatch: importlib.metadata={meta_ver!r} vs '
+          f'__version__={attr_ver!r}'
+      )
+      assert attr_ver != '0.0.0.dev0', (
+          f'__version__ is the fallback 0.0.0.dev0 - _version.py import failed'
+      )
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson (expect 3.10.x on Python 3.9) ---"
       python -c "
       import orjson
@@ -61,6 +85,7 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-310 && cd /tmp/build-310
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev310 2>/dev/null || true
       python -m build -q
 
       echo "--- Installing wheel ---"
@@ -70,6 +95,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson ---"
       python -c "
       from limacharlie.json_compat import backend_name, HAS_ORJSON
@@ -94,6 +130,7 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-311 && cd /tmp/build-311
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev311 2>/dev/null || true
       python -m build -q
 
       echo "--- Installing wheel ---"
@@ -103,6 +140,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson ---"
       python -c "
       from limacharlie.json_compat import backend_name, HAS_ORJSON
@@ -127,6 +175,7 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-312 && cd /tmp/build-312
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev312 2>/dev/null || true
       python -m build -q
 
       echo "--- Installing wheel ---"
@@ -136,6 +185,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson ---"
       python -c "
       from limacharlie.json_compat import backend_name, HAS_ORJSON
@@ -160,6 +220,7 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-313 && cd /tmp/build-313
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev313 2>/dev/null || true
       python -m build -q
 
       echo "--- Installing wheel ---"
@@ -169,6 +230,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson ---"
       python -c "
       from limacharlie.json_compat import backend_name, HAS_ORJSON
@@ -193,6 +265,7 @@ steps:
       echo "--- Building wheel ---"
       cp -r /workspace /tmp/build-314 && cd /tmp/build-314
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev314 2>/dev/null || true
       python -m build -q
 
       echo "--- Installing wheel ---"
@@ -202,6 +275,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- Verifying orjson ---"
       python -c "
       from limacharlie.json_compat import backend_name, HAS_ORJSON
@@ -226,6 +310,7 @@ steps:
       echo "--- Building sdist ---"
       cp -r /workspace /tmp/build-sdist && cd /tmp/build-sdist
       pip install --upgrade pip setuptools wheel build -q
+      git tag 99.0.0.dev999 2>/dev/null || true
       python -m build --sdist -q
       ls -lh dist/
 
@@ -236,6 +321,17 @@ steps:
       pip show limacharlie
       limacharlie --version
 
+      echo "--- Verifying version consistency ---"
+      python -c "
+      from importlib.metadata import version as pkg_version
+      import limacharlie
+      meta_ver = pkg_version('limacharlie')
+      attr_ver = limacharlie.__version__
+      assert meta_ver == attr_ver, f'Version mismatch: metadata={meta_ver!r} vs __version__={attr_ver!r}'
+      assert attr_ver != '0.0.0.dev0', '__version__ is fallback 0.0.0.dev0'
+      print(f'Version consistency: OK ({meta_ver})')
+      "
+
       echo "--- sdist check passed ---"
   waitFor: ["-"]
 
@@ -370,6 +466,69 @@ steps:
       echo "--- Unit tests passed ---"
   waitFor: ["-"]
 
+# ---------------------------------------------------------------------------
+# Sanity check: latest stable release from PyPI.
+# Installs the currently published version (not the PR branch) and verifies
+# it works. Catches PyPI packaging issues, broken uploads, and dependency
+# regressions in the published package.
+# ---------------------------------------------------------------------------
+
+- id: "PyPI Stable Sanity Check"
+  name: 'python:3.11'
+  entrypoint: "bash"
+  args:
+    - '-c'
+    - |
+      set -e
+      echo "=========================================="
+      echo "  PyPI Stable Sanity Check"
+      echo "=========================================="
+
+      echo "--- Installing latest stable from PyPI ---"
+      pip install --upgrade pip -q
+      pip install limacharlie -q
+      INSTALLED_VERSION=$(python -c "from importlib.metadata import version; print(version('limacharlie'))")
+      echo "Installed version: $${INSTALLED_VERSION}"
+
+      echo "--- Verifying package metadata ---"
+      pip show limacharlie
+
+      echo "--- Verifying version is valid semver ---"
+      python -c "
+      import re
+      from importlib.metadata import version
+      v = version('limacharlie')
+      assert v, 'version is empty'
+      assert re.match(r'^\d+\.\d+\.\d+', v), f'version {v!r} does not look like semver'
+      print(f'Package version: {v} (OK)')
+      "
+
+      echo "--- Verifying CLI entry point ---"
+      limacharlie --version
+
+      echo "--- Verifying CLI --help ---"
+      limacharlie --help | head -20
+
+      echo "--- Verifying SDK core imports ---"
+      python -c "
+      from limacharlie.client import Client
+      from limacharlie.config import resolve_credentials, load_config
+      print('SDK core imports OK')
+      "
+
+      echo "--- Verifying CLI command groups load ---"
+      for cmd in auth sensor org dr search tag hive event; do
+        echo -n "  $${cmd} --help: "
+        limacharlie $${cmd} --help > /dev/null 2>&1 && echo 'OK' || echo 'FAILED'
+      done
+
+      echo "--- Verifying completion generation ---"
+      limacharlie completion bash > /dev/null
+      echo "Bash completion: OK"
+
+      echo "--- PyPI sanity check passed (version $${INSTALLED_VERSION}) ---"
+  waitFor: ["-"]
+
 # ---------------------------------------------------------------------------
 # Integration tests and benchmarks (Python 3.14 only - tests API behavior,
 # not Python version compat).

limacharlie/__init__.py

@@ -1,6 +1,9 @@
 """limacharlie SDK for limacharlie.io"""
 
-from .client import __version__
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"
 
 __author__ = "Refraction Point, Inc"
 __author_email__ = "info@refractionpoint.com"

limacharlie/ai_help.py

@@ -122,8 +122,11 @@ def _top_level_help(cli: click.Group) -> str:
     lines.append("## All Command Groups")
     lines.append("")
 
-    for name in sorted(cli.commands):
-        sub = cli.commands[name]
+    ctx = click.Context(cli)
+    for name in cli.list_commands(ctx):
+        sub = cli.get_command(ctx, name)
+        if sub is None:
+            continue
         short = (sub.get_short_help_str(limit=300) or "").strip()
         lines.append(f"- **{name}** — {short}")