cartograph-cli 0.2.2__tar.gz → 0.3.0__tar.gz

{cartograph_cli-0.2.2 → cartograph_cli-0.3.0}/CLAUDE.md

@@ -63,10 +63,19 @@ update. Wrap or extend in your own code instead.
 
     cartograph cloud publish [widget_id] [path]
         [--lib]                          publish from library by ID
-        [--visibility public|private]    defaults to public
+        [--visibility public|private]    defaults to public (or cartograph.toml)
+        [--governance open|protected]    contribution governance model
+    cartograph cloud update <@handle/widget_id>
+        [--governance open|protected]    update governance model
     cartograph cloud unpublish <widget_id> [--confirm]
     cartograph cloud sync                reconcile local with cloud
     cartograph cloud rate <widget_id> <score 1-5> [--comment "..."]
+    cartograph cloud propose <@owner/widget_id> [path]
+        --reason "what changed and why"  REQUIRED
+    cartograph cloud proposals list            list my proposals
+    cartograph cloud proposals view <@owner/widget_id> [proposal_id]
+    cartograph cloud proposals accept <@owner/widget_id> <proposal_id>
+    cartograph cloud proposals reject <@owner/widget_id> <proposal_id> [--reason "..."]
 
 **Library and account**
 

{cartograph_cli-0.2.2 → cartograph_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartograph-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: Widget library manager for AI agents — CLI
 License-Expression: MIT
 License-File: LICENSE

{cartograph_cli-0.2.2/src/cartograph/_vendor → cartograph_cli-0.3.0/cg/infra_agent_cli_python/src}/agent_cli.py

@@ -95,6 +95,9 @@ class AgentCLI:
             )
 
         sub = parser.add_subparsers(dest="command", metavar="<command>")
+        # Maps a tuple of parent parts to (parser, subparsers) for nested commands.
+        # e.g. ("cloud",) -> (cloud_parser, cloud_subparsers)
+        #      ("cloud", "proposals") -> (proposals_parser, proposals_subparsers)
         self._nested_parsers = {}
 
         for _group_name, commands in self._groups:
@@ -103,16 +106,23 @@ class AgentCLI:
                 parts = name.split()
                 handler = cmd.get("handler")
 
-                if len(parts) == 2:
-                    parent, child = parts
-                    if parent not in self._nested_parsers:
-                        parent_parser = sub.add_parser(parent, help=f"{parent} operations")
-                        parent_sub = parent_parser.add_subparsers(dest=f"{parent}_command")
-                        self._nested_parsers[parent] = (parent_parser, parent_sub)
-                    _, parent_sub = self._nested_parsers[parent]
-                    p = parent_sub.add_parser(child, help=cmd.get("help", ""))
-                else:
+                if len(parts) == 1:
                     p = sub.add_parser(name, help=cmd.get("help", ""))
+                else:
+                    # Walk the parent chain, creating subparsers at each level
+                    current_sub = sub
+                    for depth in range(len(parts) - 1):
+                        key = tuple(parts[: depth + 1])
+                        if key not in self._nested_parsers:
+                            parent_name = parts[depth]
+                            dest = "_".join(key) + "_command"
+                            parent_parser = current_sub.add_parser(
+                                parent_name, help=f"{parent_name} operations",
+                            )
+                            parent_sub = parent_parser.add_subparsers(dest=dest)
+                            self._nested_parsers[key] = (parent_parser, parent_sub)
+                        _, current_sub = self._nested_parsers[key]
+                    p = current_sub.add_parser(parts[-1], help=cmd.get("help", ""))
 
                 for arg_spec in cmd.get("args", []):
                     self._add_arg(p, arg_spec)
@@ -120,7 +130,7 @@ class AgentCLI:
                 if handler:
                     p.set_defaults(func=handler)
 
-        for parent, (parent_parser, _) in self._nested_parsers.items():
+        for key, (parent_parser, _) in self._nested_parsers.items():
             parent_parser.set_defaults(func=lambda args, pp=parent_parser: pp.print_help())
 
         return parser

{cartograph_cli-0.2.2 → cartograph_cli-0.3.0}/cg/infra_agent_cli_python/tests/test_agent_cli.py

@@ -248,6 +248,74 @@ class TestRun:
         assert "Basic:" in captured.out
 
 
+class TestDeepNesting:
+    def test_three_level_nesting(self):
+        def cmd_leaf(args):
+            return {"id": args.id}
+
+        cli = AgentCLI(prog="t", version="0.1.0")
+        cli.add_commands("Cloud", [
+            {
+                "name": "cloud proposals list",
+                "help": "List proposals",
+                "handler": lambda a: {"items": []},
+                "args": [],
+            },
+            {
+                "name": "cloud proposals view",
+                "help": "View a proposal",
+                "handler": cmd_leaf,
+                "args": [{"name": "id"}],
+            },
+            {
+                "name": "cloud push",
+                "help": "Push to cloud",
+                "handler": lambda a: {"pushed": True},
+                "args": [],
+            },
+        ])
+        parser = cli.build_parser()
+
+        # Three-level command works
+        args = parser.parse_args(["cloud", "proposals", "view", "42"])
+        assert args.id == "42"
+        assert hasattr(args, "func")
+
+        # Two-level sibling still works
+        args2 = parser.parse_args(["cloud", "push"])
+        assert hasattr(args2, "func")
+
+    def test_four_level_nesting(self):
+        cli = AgentCLI(prog="t", version="0.1.0")
+        cli.add_commands("Deep", [
+            {
+                "name": "a b c d",
+                "help": "Four levels deep",
+                "handler": lambda a: {"deep": True},
+                "args": [{"name": "val"}],
+            },
+        ])
+        parser = cli.build_parser()
+        args = parser.parse_args(["a", "b", "c", "d", "hello"])
+        assert args.val == "hello"
+
+    def test_parent_shows_help(self, capsys):
+        cli = AgentCLI(prog="t", version="0.1.0")
+        cli.add_commands("Cloud", [
+            {
+                "name": "cloud proposals list",
+                "help": "List proposals",
+                "handler": lambda a: {},
+                "args": [],
+            },
+        ])
+        parser = cli.build_parser()
+        # "cloud proposals" with no subcommand should print help
+        args = parser.parse_args(["cloud", "proposals"])
+        func = getattr(args, "func", None)
+        assert func is not None  # should have the help-printing default
+
+
 class TestMultipleGroups:
     def test_three_groups(self):
         cli = AgentCLI(prog="t", version="0.1.0")

cartograph_cli-0.3.0/cg/infra_file_stamp_python/.validation_stamp.json

@@ -0,0 +1 @@
+{"language": "python", "fingerprint": "ff91956c7b94d2841373d49cd69337069be2201e580839049311d6cc52d28a8c", "validated_at": "2026-03-30T01:26:48.772591+00:00", "cartograph_version": "0.2.0", "test_results": {}}

cartograph_cli-0.3.0/cg/infra_file_stamp_python/examples/example_usage.py

@@ -0,0 +1,56 @@
+"""
+Example usage of File Stamp.
+
+Demonstrates fingerprinting a directory and using stamps to detect changes.
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from src.file_stamp import (
+    collect_files,
+    fingerprint,
+    write_stamp,
+    read_stamp,
+    is_stamp_valid,
+)
+
+# Create a temporary project to stamp
+with tempfile.TemporaryDirectory() as project:
+    src = os.path.join(project, "src")
+    os.makedirs(src)
+
+    with open(os.path.join(src, "main.py"), "w") as f:
+        f.write("def run(): pass\n")
+    with open(os.path.join(src, "util.py"), "w") as f:
+        f.write("helpers = True\n")
+
+    # 1. Collect files
+    files = collect_files(project)
+    sys.stdout.write(f"Found {len(files)} files\n")
+
+    # 2. Compute fingerprint
+    fp = fingerprint(project)
+    sys.stdout.write(f"Fingerprint: {fp[:16]}...\n")
+
+    # 3. Write a stamp with metadata
+    stamp = write_stamp(project, metadata={"language": "python", "tool": "example"})
+    sys.stdout.write(f"Stamp written at {stamp['stamped_at']}\n")
+
+    # 4. Check validity - should be valid (nothing changed)
+    valid = is_stamp_valid(project, metadata_match={"language": "python"})
+    sys.stdout.write(f"Valid (no changes): {valid}\n")
+
+    # 5. Modify a file
+    with open(os.path.join(src, "main.py"), "w") as f:
+        f.write("def run(): return 42\n")
+
+    # 6. Check again - should be invalid (file changed)
+    valid = is_stamp_valid(project, metadata_match={"language": "python"})
+    sys.stdout.write(f"Valid (after edit): {valid}\n")
+
+    # 7. Re-stamp
+    write_stamp(project, metadata={"language": "python", "tool": "example"})
+    valid = is_stamp_valid(project, metadata_match={"language": "python"})
+    sys.stdout.write(f"Valid (after re-stamp): {valid}\n")

cartograph_cli-0.3.0/cg/infra_file_stamp_python/src/__init__.py

@@ -0,0 +1 @@
+# Package marker - add explicit exports here once the public API is stable.

cartograph_cli-0.3.0/cg/infra_file_stamp_python/src/file_stamp.py

@@ -0,0 +1,156 @@
+"""
+File Stamp - fingerprint-based change detection for file sets.
+
+Computes a SHA-256 digest over a set of files (paths + contents) and
+stores it as a JSON stamp. On subsequent runs, recomputes and compares
+to detect whether any watched file has changed.
+
+Use cases: build cache invalidation, validation short-circuiting,
+incremental processing pipelines.
+"""
+
+import glob as _glob
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+
+
+STAMP_FILE = ".file_stamp.json"
+
+_SKIP_EXTENSIONS = frozenset({".pyc", ".pyo", ".o", ".so", ".dylib"})
+_SKIP_DIRS = frozenset({"__pycache__", ".pytest_cache", ".git", "node_modules"})
+
+
+def collect_files(root, patterns=None, skip_dirs=None, skip_extensions=None):
+    """Return sorted absolute paths matching glob patterns under root.
+
+    Args:
+        root: Base directory to search from.
+        patterns: Glob patterns relative to root. Defaults to common source
+                  patterns (src/, tests/, examples/, plus root config files).
+        skip_dirs: Directory names to exclude. Defaults to __pycache__,
+                   .pytest_cache, .git, node_modules.
+        skip_extensions: File extensions to exclude. Defaults to .pyc, .pyo,
+                         .o, .so, .dylib.
+
+    Returns:
+        Sorted list of absolute file paths.
+    """
+    if skip_dirs is None:
+        skip_dirs = _SKIP_DIRS
+    if skip_extensions is None:
+        skip_extensions = _SKIP_EXTENSIONS
+    if patterns is None:
+        patterns = [
+            os.path.join(root, "src", "**", "*"),
+            os.path.join(root, "tests", "**", "*"),
+            os.path.join(root, "examples", "**", "*"),
+            os.path.join(root, "*.json"),
+            os.path.join(root, "*.toml"),
+            os.path.join(root, "*.yaml"),
+            os.path.join(root, "*.yml"),
+        ]
+
+    files = set()
+    for pattern in patterns:
+        for f in _glob.glob(pattern, recursive=True):
+            if not os.path.isfile(f):
+                continue
+            rel_parts = os.path.relpath(f, root).split(os.sep)
+            if any(part in skip_dirs for part in rel_parts):
+                continue
+            if os.path.splitext(f)[1] in skip_extensions:
+                continue
+            files.add(os.path.abspath(f))
+    return sorted(files)
+
+
+def fingerprint(root, files=None, **collect_kwargs):
+    """Compute a SHA-256 hex digest over (relative-path, content) pairs.
+
+    Args:
+        root: Base directory (used for relative path computation).
+        files: Explicit list of absolute paths. If None, calls
+               collect_files(root, **collect_kwargs).
+
+    Returns:
+        Hex digest string.
+    """
+    if files is None:
+        files = collect_files(root, **collect_kwargs)
+
+    h = hashlib.sha256()
+    for fpath in files:
+        rel = os.path.relpath(fpath, root)
+        h.update(rel.encode())
+        try:
+            with open(fpath, "rb") as f:
+                h.update(f.read())
+        except OSError:
+            pass
+    return h.hexdigest()
+
+
+def write_stamp(root, metadata=None, stamp_name=STAMP_FILE, **collect_kwargs):
+    """Write a stamp file after computing the current fingerprint.
+
+    Args:
+        root: Directory to fingerprint and write the stamp into.
+        metadata: Optional dict of extra fields to include in the stamp
+                  (e.g. {"language": "python", "tool_version": "1.0"}).
+        stamp_name: Filename for the stamp. Defaults to .file_stamp.json.
+        **collect_kwargs: Passed to collect_files (patterns, skip_dirs, etc).
+
+    Returns:
+        The stamp dict that was written.
+    """
+    stamp = {
+        "fingerprint": fingerprint(root, **collect_kwargs),
+        "stamped_at": datetime.now(timezone.utc).isoformat(),
+    }
+    if metadata:
+        stamp.update(metadata)
+
+    stamp_path = os.path.join(root, stamp_name)
+    with open(stamp_path, "w") as f:
+        json.dump(stamp, f)
+    return stamp
+
+
+def read_stamp(root, stamp_name=STAMP_FILE):
+    """Read an existing stamp file. Returns the stamp dict or None."""
+    stamp_path = os.path.join(root, stamp_name)
+    try:
+        with open(stamp_path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def is_stamp_valid(root, metadata_match=None, stamp_name=STAMP_FILE,
+                   **collect_kwargs):
+    """Check if the stamp is still valid (no files changed).
+
+    Args:
+        root: Directory to check.
+        metadata_match: Optional dict of metadata keys that must match.
+                        e.g. {"language": "python"} ensures the stamp was
+                        written for the same language.
+        stamp_name: Filename for the stamp.
+        **collect_kwargs: Passed to collect_files for recomputing fingerprint.
+
+    Returns:
+        True if stamp exists, metadata matches, and fingerprint is current.
+    """
+    stamp = read_stamp(root, stamp_name)
+    if stamp is None:
+        return False
+
+    if metadata_match:
+        for key, value in metadata_match.items():
+            if stamp.get(key) != value:
+                return False
+
+    current = fingerprint(root, **collect_kwargs)
+    return stamp.get("fingerprint") == current

cartograph_cli-0.3.0/cg/infra_file_stamp_python/tests/test_file_stamp.py

@@ -0,0 +1,144 @@
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from src.file_stamp import (
+    collect_files,
+    fingerprint,
+    write_stamp,
+    read_stamp,
+    is_stamp_valid,
+    STAMP_FILE,
+)
+
+
+def _make_tree(tmp_path):
+    """Create a small file tree for testing."""
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "main.py").write_text("print('hello')")
+    (src / "util.py").write_text("x = 1")
+    tests = tmp_path / "tests"
+    tests.mkdir()
+    (tests / "test_main.py").write_text("assert True")
+    (tmp_path / "widget.json").write_text('{"name": "test"}')
+    return tmp_path
+
+
+def test_collect_files_defaults(tmp_path):
+    root = _make_tree(tmp_path)
+    files = collect_files(str(root))
+    names = [os.path.basename(f) for f in files]
+    assert "main.py" in names
+    assert "util.py" in names
+    assert "test_main.py" in names
+    assert "widget.json" in names
+
+
+def test_collect_files_skips_pycache(tmp_path):
+    root = _make_tree(tmp_path)
+    cache = tmp_path / "src" / "__pycache__"
+    cache.mkdir()
+    (cache / "main.cpython-312.pyc").write_bytes(b"\x00")
+    files = collect_files(str(root))
+    for f in files:
+        assert "__pycache__" not in f
+
+
+def test_collect_files_custom_patterns(tmp_path):
+    root = _make_tree(tmp_path)
+    patterns = [os.path.join(str(root), "src", "*.py")]
+    files = collect_files(str(root), patterns=patterns)
+    names = [os.path.basename(f) for f in files]
+    assert "main.py" in names
+    assert "test_main.py" not in names
+
+
+def test_fingerprint_deterministic(tmp_path):
+    root = _make_tree(tmp_path)
+    fp1 = fingerprint(str(root))
+    fp2 = fingerprint(str(root))
+    assert fp1 == fp2
+    assert len(fp1) == 64  # SHA-256 hex
+
+
+def test_fingerprint_changes_on_edit(tmp_path):
+    root = _make_tree(tmp_path)
+    fp1 = fingerprint(str(root))
+    (tmp_path / "src" / "main.py").write_text("print('changed')")
+    fp2 = fingerprint(str(root))
+    assert fp1 != fp2
+
+
+def test_fingerprint_changes_on_new_file(tmp_path):
+    root = _make_tree(tmp_path)
+    fp1 = fingerprint(str(root))
+    (tmp_path / "src" / "new.py").write_text("y = 2")
+    fp2 = fingerprint(str(root))
+    assert fp1 != fp2
+
+
+def test_fingerprint_explicit_files(tmp_path):
+    root = _make_tree(tmp_path)
+    only = [str(tmp_path / "src" / "main.py")]
+    fp = fingerprint(str(root), files=only)
+    assert len(fp) == 64
+
+
+def test_write_and_read_stamp(tmp_path):
+    root = _make_tree(tmp_path)
+    stamp = write_stamp(str(root))
+    assert "fingerprint" in stamp
+    assert "stamped_at" in stamp
+
+    loaded = read_stamp(str(root))
+    assert loaded is not None
+    assert loaded["fingerprint"] == stamp["fingerprint"]
+
+
+def test_write_stamp_with_metadata(tmp_path):
+    root = _make_tree(tmp_path)
+    stamp = write_stamp(str(root), metadata={"language": "python", "version": "1.0"})
+    assert stamp["language"] == "python"
+    assert stamp["version"] == "1.0"
+
+    loaded = read_stamp(str(root))
+    assert loaded["language"] == "python"
+
+
+def test_read_stamp_missing(tmp_path):
+    assert read_stamp(str(tmp_path)) is None
+
+
+def test_is_stamp_valid_fresh(tmp_path):
+    root = _make_tree(tmp_path)
+    write_stamp(str(root))
+    assert is_stamp_valid(str(root)) is True
+
+
+def test_is_stamp_valid_after_change(tmp_path):
+    root = _make_tree(tmp_path)
+    write_stamp(str(root))
+    (tmp_path / "src" / "main.py").write_text("print('changed')")
+    assert is_stamp_valid(str(root)) is False
+
+
+def test_is_stamp_valid_metadata_match(tmp_path):
+    root = _make_tree(tmp_path)
+    write_stamp(str(root), metadata={"language": "python"})
+    assert is_stamp_valid(str(root), metadata_match={"language": "python"}) is True
+    assert is_stamp_valid(str(root), metadata_match={"language": "nim"}) is False
+
+
+def test_is_stamp_valid_no_stamp(tmp_path):
+    root = _make_tree(tmp_path)
+    assert is_stamp_valid(str(root)) is False
+
+
+def test_custom_stamp_name(tmp_path):
+    root = _make_tree(tmp_path)
+    write_stamp(str(root), stamp_name=".my_stamp.json")
+    assert os.path.exists(str(tmp_path / ".my_stamp.json"))
+    assert is_stamp_valid(str(root), stamp_name=".my_stamp.json") is True
+    assert is_stamp_valid(str(root)) is False  # default name doesn't exist

cartograph_cli-0.3.0/cg/infra_file_stamp_python/widget.json

@@ -0,0 +1,24 @@
+{
+  "meta": {
+    "id": "infra-file-stamp-python",
+    "name": "File Stamp",
+    "version": "1.0.0",
+    "domain": "infra",
+    "tags": [
+      "fingerprint",
+      "cache-invalidation",
+      "file-hash",
+      "change-detection",
+      "build-tools"
+    ]
+  },
+  "description": "Fingerprint-based change detection for file sets. Computes SHA-256 over watched files, writes a JSON stamp, and checks validity on subsequent runs. Useful for build cache invalidation, validation short-circuiting, and incremental processing pipelines.",
+  "tech_stack": {
+    "language": "python",
+    "dependencies": []
+  },
+  "library_notes": {
+    "general": "Single responsibility - one widget does one thing. No global state. No project-specific code, hardcoded paths, credentials, or environment-specific values. Expose variation points as constructor parameters or function arguments - no hardcoded thresholds, colors, sizes, or behavior flags. All dependencies must be declared in widget.json tech_stack.dependencies. Widgets cannot depend on other widgets - they must be fully self-contained. If you need logic from another widget, copy it into src/ directly. Examples must run and exit cleanly with no user input, no network calls, and no external services or API keys - use fake/hardcoded data. The widget's own declared dependencies are fine and will be installed by the validator before the example runs. Do not modify library_notes - it is managed by Cartograph and will be restored on checkin.",
+    "language": "Use pytest for all tests - no unittest. Type hints required on all public functions. No __init__.py in tests/. No if __name__ == '__main__' blocks in src/ files. Imports ordered: stdlib, third-party, local."
+  }
+}

{cartograph_cli-0.2.2 → cartograph_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cartograph-cli"
-version = "0.2.2"
+version = "0.3.0"
 description = "Widget library manager for AI agents — CLI"
 readme = "README.md"
 license = "MIT"
@@ -18,7 +18,7 @@ dependencies = [
 cartograph = "cartograph.cli:main"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/cartograph"]
+packages = ["src/cartograph", "cg"]
 
 
 [tool.pytest.ini_options]