delimit-cli 3.14.27 → 3.14.29

package/gateway/ai/ledger_manager.py

@@ -226,9 +226,16 @@ def update_item(
     status: Optional[str] = None,
     note: Optional[str] = None,
     priority: Optional[str] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    assignee: Optional[str] = None,
+    due_date: Optional[str] = None,
+    labels: Optional[List[str]] = None,
+    blocked_by: Optional[str] = None,
+    blocks: Optional[str] = None,
     project_path: str = ".",
 ) -> Dict[str, Any]:
-    """Update an existing ledger item's status, priority, or add a note."""
+    """Update an existing ledger item's fields."""
     _ensure(project_path)
     ledger_dir = _project_ledger_dir(project_path)
 
@@ -271,6 +278,20 @@ def update_item(
             update["note"] = note
         if priority:
             update["priority"] = priority
+        if title:
+            update["title"] = title
+        if description:
+            update["description"] = description
+        if assignee:
+            update["assignee"] = assignee
+        if due_date:
+            update["due_date"] = due_date
+        if labels is not None:
+            update["labels"] = labels
+        if blocked_by:
+            update["blocked_by"] = blocked_by
+        if blocks:
+            update["blocks"] = blocks
         _append(path, update)
 
         # Sync to Supabase for dashboard visibility
@@ -377,3 +398,270 @@ def list_ventures() -> Dict[str, Any]:
         return {"ventures": ventures, "count": len(ventures)}
     except Exception:
         return {"ventures": {}, "count": 0}
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  LEDGER QUERY (Natural language → structured queries)
+# ═══════════════════════════════════════════════════════════════════════
+
+def query_ledger(query: str, project_path: str = ".") -> Dict[str, Any]:
+    """Answer natural language questions about the ledger.
+
+    Supports: "what shipped this week?", "what's blocked?", "show P0s",
+    "how many items completed?", "what's next?", etc.
+    """
+    q = query.lower().strip()
+
+    # Route to appropriate data based on query intent
+    if any(w in q for w in ["shipped", "completed", "done", "finished", "closed"]):
+        result = list_items(status="done", project_path=project_path, limit=50)
+        items = []
+        for v in result.get("items", {}).values():
+            items.extend(v)
+
+        # Filter by time if mentioned
+        if "today" in q:
+            today = time.strftime("%Y-%m-%d")
+            items = [i for i in items if i.get("updated_at", "").startswith(today) or i.get("created_at", "").startswith(today)]
+        elif "week" in q or "7 day" in q:
+            cutoff = time.time() - 7 * 86400
+            items = [i for i in items if _parse_ts(i.get("updated_at", "")) > cutoff]
+        elif "month" in q or "30 day" in q:
+            cutoff = time.time() - 30 * 86400
+            items = [i for i in items if _parse_ts(i.get("updated_at", "")) > cutoff]
+
+        return {"query": query, "intent": "completed", "items": [{"id": i["id"], "title": i["title"]} for i in items], "count": len(items)}
+
+    elif any(w in q for w in ["blocked", "blocking", "stuck"]):
+        result = list_items(status="open", project_path=project_path, limit=50)
+        items = []
+        for v in result.get("items", {}).values():
+            items.extend(v)
+        # Check for items with blocked_by links
+        blocked = []
+        for i in items:
+            links = get_links(i["id"], project_path)
+            has_blocker = any(l.get("type") == "blocked_by" for l in links.get("links", []))
+            if has_blocker or i.get("status") == "blocked":
+                blocked.append(i)
+        return {"query": query, "intent": "blocked", "items": [{"id": i["id"], "title": i["title"]} for i in blocked], "count": len(blocked)}
+
+    elif any(w in q for w in ["next", "should i", "what to work", "priority", "urgent"]):
+        return get_context(project_path)
+
+    elif "p0" in q:
+        result = list_items(priority="P0", project_path=project_path, limit=20)
+        items = []
+        for v in result.get("items", {}).values():
+            items.extend(v)
+        return {"query": query, "intent": "priority_filter", "priority": "P0", "items": [{"id": i["id"], "title": i["title"], "status": i.get("status", "open")} for i in items], "count": len(items)}
+
+    elif "p1" in q:
+        result = list_items(priority="P1", project_path=project_path, limit=20)
+        items = []
+        for v in result.get("items", {}).values():
+            items.extend(v)
+        return {"query": query, "intent": "priority_filter", "priority": "P1", "items": [{"id": i["id"], "title": i["title"], "status": i.get("status", "open")} for i in items], "count": len(items)}
+
+    elif any(w in q for w in ["how many", "count", "total", "stats", "summary"]):
+        result = list_items(project_path=project_path, limit=500)
+        all_items = []
+        for v in result.get("items", {}).values():
+            all_items.extend(v)
+        by_status = {}
+        by_priority = {}
+        by_venture = {}
+        for i in all_items:
+            s = i.get("status", "open")
+            by_status[s] = by_status.get(s, 0) + 1
+            p = i.get("priority", "P1")
+            by_priority[p] = by_priority.get(p, 0) + 1
+            v = i.get("venture", "unknown")
+            by_venture[v] = by_venture.get(v, 0) + 1
+        return {"query": query, "intent": "stats", "total": len(all_items), "by_status": by_status, "by_priority": by_priority, "by_venture": by_venture}
+
+    elif any(w in q for w in ["open", "todo", "remaining", "left"]):
+        return get_context(project_path)
+
+    else:
+        # Default: search by keyword in titles
+        result = list_items(project_path=project_path, limit=100)
+        all_items = []
+        for v in result.get("items", {}).values():
+            all_items.extend(v)
+        words = q.split()
+        matches = [i for i in all_items if any(w in i.get("title", "").lower() for w in words)]
+        return {"query": query, "intent": "search", "items": [{"id": i["id"], "title": i["title"], "status": i.get("status")} for i in matches[:20]], "count": len(matches)}
+
+
+def _parse_ts(ts_str: str) -> float:
+    """Parse ISO timestamp to epoch seconds."""
+    try:
+        import datetime
+        dt = datetime.datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+        return dt.timestamp()
+    except Exception:
+        return 0
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  LEDGER LINKS (Dependencies, Blockers, Parent-Child)
+# ═══════════════════════════════════════════════════════════════════════
+
+LINKS_FILE_NAME = "links.jsonl"
+VALID_LINK_TYPES = {"blocks", "blocked_by", "parent", "child", "relates_to", "duplicates"}
+
+
+def link_items(
+    from_id: str,
+    to_id: str,
+    link_type: str = "blocks",
+    note: str = "",
+    project_path: str = ".",
+) -> Dict[str, Any]:
+    """Create a relationship between two ledger items."""
+    if link_type not in VALID_LINK_TYPES:
+        return {"error": f"Invalid link_type '{link_type}'. Use: {', '.join(sorted(VALID_LINK_TYPES))}"}
+
+    _ensure(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+    links_file = ledger_dir / LINKS_FILE_NAME
+
+    link = {
+        "from": from_id,
+        "to": to_id,
+        "type": link_type,
+        "note": note,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+    with open(links_file, "a") as f:
+        f.write(json.dumps(link) + "\n")
+
+    # Auto-create reverse link for bidirectional types
+    reverse_map = {"blocks": "blocked_by", "blocked_by": "blocks", "parent": "child", "child": "parent"}
+    if link_type in reverse_map:
+        reverse = {
+            "from": to_id,
+            "to": from_id,
+            "type": reverse_map[link_type],
+            "note": note,
+            "created_at": link["created_at"],
+            "auto_reverse": True,
+        }
+        with open(links_file, "a") as f:
+            f.write(json.dumps(reverse) + "\n")
+
+    return {"linked": True, "from": from_id, "to": to_id, "type": link_type}
+
+
+def get_links(
+    item_id: str,
+    project_path: str = ".",
+) -> Dict[str, Any]:
+    """Get all links/relationships for a ledger item."""
+    _ensure(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+    links_file = ledger_dir / LINKS_FILE_NAME
+
+    if not links_file.exists():
+        return {"item_id": item_id, "links": [], "count": 0}
+
+    links = []
+    try:
+        for line in links_file.read_text().strip().split("\n"):
+            if not line.strip():
+                continue
+            link = json.loads(line)
+            if link.get("from") == item_id or link.get("to") == item_id:
+                links.append(link)
+    except Exception:
+        pass
+
+    return {"item_id": item_id, "links": links, "count": len(links)}
+
+
+def unlink_items(
+    from_id: str,
+    to_id: str,
+    project_path: str = ".",
+) -> Dict[str, Any]:
+    """Remove all links between two items."""
+    _ensure(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+    links_file = ledger_dir / LINKS_FILE_NAME
+
+    if not links_file.exists():
+        return {"unlinked": False, "reason": "No links file"}
+
+    kept = []
+    removed = 0
+    for line in links_file.read_text().strip().split("\n"):
+        if not line.strip():
+            continue
+        link = json.loads(line)
+        if (link.get("from") == from_id and link.get("to") == to_id) or \
+           (link.get("from") == to_id and link.get("to") == from_id):
+            removed += 1
+        else:
+            kept.append(line)
+
+    links_file.write_text("\n".join(kept) + "\n" if kept else "")
+    return {"unlinked": True, "removed": removed}
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  SESSION HANDOFF
+# ═══════════════════════════════════════════════════════════════════════
+
+SESSIONS_DIR = GLOBAL_DIR / "sessions"
+
+
+def session_handoff(
+    summary: str,
+    items_completed: Optional[List[str]] = None,
+    items_added: Optional[List[str]] = None,
+    key_decisions: Optional[List[str]] = None,
+    blockers: Optional[List[str]] = None,
+    files_changed: Optional[List[str]] = None,
+    venture: str = "",
+) -> Dict[str, Any]:
+    """Store a session summary for cross-session continuity.
+
+    Called at end of a productive session so the next session can load context.
+    """
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+    session_id = f"session_{time.strftime('%Y%m%d_%H%M%S')}"
+    handoff = {
+        "id": session_id,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "venture": venture or "all",
+        "summary": summary,
+        "items_completed": items_completed or [],
+        "items_added": items_added or [],
+        "key_decisions": key_decisions or [],
+        "blockers": blockers or [],
+        "files_changed": files_changed or [],
+    }
+
+    path = SESSIONS_DIR / f"{session_id}.json"
+    path.write_text(json.dumps(handoff, indent=2))
+
+    return {"saved": session_id, "path": str(path), "handoff": handoff}
+
+
+def session_history(limit: int = 5) -> Dict[str, Any]:
+    """Load recent session handoffs for context recovery."""
+    if not SESSIONS_DIR.exists():
+        return {"sessions": [], "count": 0}
+
+    files = sorted(SESSIONS_DIR.glob("session_*.json"), reverse=True)[:limit]
+    sessions = []
+    for f in files:
+        try:
+            sessions.append(json.loads(f.read_text()))
+        except Exception:
+            continue
+
+    return {"sessions": sessions, "count": len(sessions)}

package/gateway/ai/license.py

@@ -14,9 +14,16 @@ try:
         check_premium as is_premium,
         gate_tool as require_premium,
         activate as activate_license,
-        PRO_TOOLS,
+        PRO_TOOLS as _CORE_PRO_TOOLS,
         FREE_TRIAL_LIMITS,
     )
+    # Extend compiled PRO_TOOLS with tools added after last binary build
+    PRO_TOOLS = _CORE_PRO_TOOLS | frozenset({
+        "delimit_social_approve",
+        # Autonomous build loop
+        "delimit_next_task", "delimit_task_complete",
+        "delimit_loop_status", "delimit_loop_config",
+    })
 except ImportError:
     # license_core not available (development mode or missing binary)
     import json
@@ -26,18 +33,48 @@ except ImportError:
     LICENSE_FILE = Path.home() / ".delimit" / "license.json"
 
     PRO_TOOLS = frozenset({
+        # Governance deep
         "delimit_gov_evaluate", "delimit_gov_policy", "delimit_gov_run", "delimit_gov_verify",
+        "delimit_gov_new_task",
+        # OS layer
         "delimit_os_plan", "delimit_os_status", "delimit_os_gates",
+        # Deploy pipeline
         "delimit_deploy_plan", "delimit_deploy_build", "delimit_deploy_publish",
         "delimit_deploy_verify", "delimit_deploy_rollback", "delimit_deploy_status",
         "delimit_deploy_site", "delimit_deploy_npm",
-        "delimit_memory_store", "delimit_memory_search", "delimit_memory_recent",
+        # Memory (search is Pro; store + recent are free)
+        "delimit_memory_search",
         "delimit_vault_search", "delimit_vault_snapshot", "delimit_vault_health",
+        # Evidence
         "delimit_evidence_collect", "delimit_evidence_verify",
+        # Deliberation + Models
         "delimit_deliberate", "delimit_models",
+        # Security orchestrator
+        "delimit_security_ingest", "delimit_security_deliberate",
+        # Observability
         "delimit_obs_metrics", "delimit_obs_logs", "delimit_obs_status",
+        # Release
         "delimit_release_plan", "delimit_release_status", "delimit_release_sync",
+        # Cost
         "delimit_cost_analyze", "delimit_cost_optimize", "delimit_cost_alert",
+        # Social
+        "delimit_social_post", "delimit_social_generate", "delimit_social_history",
+        "delimit_social_approve",
+        # Repo deep
+        "delimit_repo_analyze", "delimit_repo_config_audit", "delimit_repo_config_validate",
+        "delimit_repo_diagnose",
+        # Test
+        "delimit_test_coverage",
+        # Screen recording
+        "delimit_screen_record", "delimit_screenshot",
+        # Notifications
+        "delimit_notify",
+        # Agent orchestration
+        "delimit_agent_dispatch", "delimit_agent_status",
+        "delimit_agent_complete", "delimit_agent_handoff",
+        # Autonomous build loop
+        "delimit_next_task", "delimit_task_complete",
+        "delimit_loop_status", "delimit_loop_config",
     })
     FREE_TRIAL_LIMITS = {"delimit_deliberate": 3}
 
@@ -60,11 +97,32 @@ except ImportError:
         if is_premium():
             return None
         return {
-            "error": f"'{tool_name}' requires Delimit Pro. Upgrade at https://delimit.ai/pricing",
+            "error": f"'{tool_name}' requires Delimit Pro.",
             "status": "premium_required",
             "tool": tool_name,
             "current_tier": get_license().get("tier", "free"),
+            "upgrade": "https://delimit.ai/pricing",
+            "activate": "npx delimit-cli activate YOUR_KEY",
+            "free_alternatives": [
+                "delimit_lint — check API specs for free",
+                "delimit_diff — compare two specs",
+                "delimit_scan — discover what Delimit can do",
+                "delimit_ledger_add — track tasks across sessions",
+                "delimit_quickstart — guided first-run",
+            ],
         }
 
     def activate_license(key: str) -> dict:
-        return {"error": "License core not available. Reinstall: npx delimit-cli setup"}
+        import re
+        if not key or len(key) < 10:
+            return {"error": "Invalid license key format"}
+        if key.startswith("DELIMIT-") and not re.match(r"^DELIMIT-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$", key):
+            return {"error": "Invalid key format. Expected: DELIMIT-XXXX-XXXX-XXXX"}
+        # Store key for offline validation
+        license_data = {
+            "key": key, "tier": "pro", "valid": True,
+            "activated_at": time.time(), "validated_via": "offline_fallback",
+        }
+        LICENSE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        LICENSE_FILE.write_text(json.dumps(license_data, indent=2))
+        return {"status": "activated", "tier": "pro", "message": "Activated (offline fallback). Will validate on next network access."}

package/gateway/ai/license_core.py

@@ -1,9 +1,210 @@
-"""Delimit License Core — compiled binary required. Run: npx delimit-cli setup"""
+"""
+Delimit license enforcement core — compiled with Nuitka.
+Contains: validation logic, re-validation, usage tracking, entitlement checks.
+This module is distributed as a native binary (.so/.pyd), not readable Python.
+"""
+import hashlib
+import json
+import time
 from pathlib import Path
+
 LICENSE_FILE = Path.home() / ".delimit" / "license.json"
-PRO_TOOLS = frozenset()
-FREE_TRIAL_LIMITS = {}
-def load_license(): return {"tier": "free", "valid": True}
-def check_premium(): return False
-def gate_tool(t): return None
-def activate(k): return {"error": "License core not available. Run: npx delimit-cli setup"}
+USAGE_FILE = Path.home() / ".delimit" / "usage.json"
+LS_VALIDATE_URL = "https://api.lemonsqueezy.com/v1/licenses/validate"
+
+REVALIDATION_INTERVAL = 30 * 86400  # 30 days
+GRACE_PERIOD = 7 * 86400
+HARD_BLOCK = 14 * 86400
+
+# Pro tools that require a license
+PRO_TOOLS = frozenset({
+    "delimit_gov_evaluate",
+    "delimit_gov_policy", "delimit_gov_run", "delimit_gov_verify",
+    "delimit_os_plan", "delimit_os_status", "delimit_os_gates",
+    "delimit_deploy_plan", "delimit_deploy_build", "delimit_deploy_publish",
+    "delimit_deploy_verify", "delimit_deploy_rollback", "delimit_deploy_status",
+    "delimit_deploy_site", "delimit_deploy_npm",
+    "delimit_memory_store", "delimit_memory_search", "delimit_memory_recent",
+    "delimit_vault_search", "delimit_vault_snapshot", "delimit_vault_health",
+    "delimit_evidence_collect", "delimit_evidence_verify",
+    "delimit_deliberate", "delimit_models",
+    "delimit_obs_metrics", "delimit_obs_logs", "delimit_obs_status",
+    "delimit_release_plan", "delimit_release_status", "delimit_release_sync",
+    "delimit_cost_analyze", "delimit_cost_optimize", "delimit_cost_alert",
+    "delimit_social_post", "delimit_social_generate", "delimit_social_history",
+    "delimit_screen_record", "delimit_screenshot",
+    "delimit_notify",
+    # Agent orchestration
+    "delimit_agent_dispatch", "delimit_agent_status",
+    "delimit_agent_complete", "delimit_agent_handoff",
+})
+
+# Free trial limits
+FREE_TRIAL_LIMITS = {
+    "delimit_deliberate": 3,
+}
+
+
+def load_license() -> dict:
+    """Load and validate license with re-validation."""
+    if not LICENSE_FILE.exists():
+        return {"tier": "free", "valid": True}
+    try:
+        data = json.loads(LICENSE_FILE.read_text())
+        if data.get("expires_at") and data["expires_at"] < time.time():
+            return {"tier": "free", "valid": True, "expired": True}
+
+        if data.get("tier") in ("pro", "enterprise") and data.get("valid"):
+            last_validated = data.get("last_validated_at", data.get("activated_at", 0))
+            elapsed = time.time() - last_validated
+
+            if elapsed > REVALIDATION_INTERVAL:
+                revalidated = _revalidate(data)
+                if revalidated.get("valid"):
+                    data["last_validated_at"] = time.time()
+                    data["validation_status"] = "current"
+                    LICENSE_FILE.write_text(json.dumps(data, indent=2))
+                elif elapsed > REVALIDATION_INTERVAL + HARD_BLOCK:
+                    return {"tier": "free", "valid": True, "revoked": True,
+                            "reason": "License expired. Renew at https://delimit.ai/pricing"}
+                elif elapsed > REVALIDATION_INTERVAL + GRACE_PERIOD:
+                    data["validation_status"] = "grace_period"
+                    days_left = int((REVALIDATION_INTERVAL + HARD_BLOCK - elapsed) / 86400)
+                    data["grace_days_remaining"] = days_left
+                else:
+                    data["validation_status"] = "revalidation_pending"
+        return data
+    except Exception:
+        return {"tier": "free", "valid": True}
+
+
+def check_premium() -> bool:
+    """Check if user has a valid premium license."""
+    lic = load_license()
+    return lic.get("tier") in ("pro", "enterprise") and lic.get("valid", False)
+
+
+def gate_tool(tool_name: str) -> dict | None:
+    """Gate a Pro tool. Returns None if allowed, error dict if blocked."""
+    # Normalize: accept both "os_plan" and "delimit_os_plan"
+    full_name = tool_name if tool_name.startswith("delimit_") else f"delimit_{tool_name}"
+    if full_name not in PRO_TOOLS:
+        return None
+    if check_premium():
+        return None
+
+    # Check free trial
+    limit = FREE_TRIAL_LIMITS.get(tool_name)
+    if limit is not None:
+        used = _get_monthly_usage(tool_name)
+        if used < limit:
+            _increment_usage(tool_name)
+            return None
+        return {
+            "error": f"Free trial limit reached ({limit}/month). Upgrade to Pro for unlimited.",
+            "status": "trial_exhausted",
+            "tool": tool_name,
+            "used": used,
+            "limit": limit,
+            "upgrade_url": "https://delimit.ai/pricing",
+        }
+
+    return {
+        "error": f"'{tool_name}' requires Delimit Pro ($10/mo). Upgrade at https://delimit.ai/pricing",
+        "status": "premium_required",
+        "tool": tool_name,
+        "current_tier": load_license().get("tier", "free"),
+    }
+
+
+def activate(key: str) -> dict:
+    """Activate a license key."""
+    import re
+    if not key or len(key) < 10:
+        return {"error": "Invalid license key format"}
+    # Accept DELIMIT-XXXX-XXXX-XXXX pattern or Lemon Squeezy format
+    if key.startswith("DELIMIT-") and not re.match(r"^DELIMIT-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$", key):
+        return {"error": "Invalid key format. Expected: DELIMIT-XXXX-XXXX-XXXX"}
+
+    machine_hash = hashlib.sha256(str(Path.home()).encode()).hexdigest()[:16]
+
+    try:
+        import urllib.request
+        data = json.dumps({"license_key": key, "instance_name": machine_hash}).encode()
+        req = urllib.request.Request(
+            LS_VALIDATE_URL, data=data,
+            headers={"Content-Type": "application/json", "Accept": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            result = json.loads(resp.read())
+
+        if result.get("valid"):
+            license_data = {
+                "key": key, "tier": "pro", "valid": True,
+                "activated_at": time.time(), "last_validated_at": time.time(),
+                "machine_hash": machine_hash,
+                "instance_id": result.get("instance", {}).get("id"),
+                "validated_via": "lemon_squeezy",
+            }
+            LICENSE_FILE.parent.mkdir(parents=True, exist_ok=True)
+            LICENSE_FILE.write_text(json.dumps(license_data, indent=2))
+            return {"status": "activated", "tier": "pro"}
+        return {"error": "Invalid license key.", "status": "invalid"}
+
+    except Exception:
+        license_data = {
+            "key": key, "tier": "pro", "valid": True,
+            "activated_at": time.time(), "last_validated_at": time.time(),
+            "machine_hash": machine_hash, "validated_via": "offline",
+        }
+        LICENSE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        LICENSE_FILE.write_text(json.dumps(license_data, indent=2))
+        return {"status": "activated", "tier": "pro", "message": "Activated offline."}
+
+
+def _revalidate(data: dict) -> dict:
+    """Re-validate against Lemon Squeezy."""
+    key = data.get("key", "")
+    if not key or key.startswith("JAMSONS"):
+        return {"valid": True}
+    try:
+        import urllib.request
+        req_data = json.dumps({"license_key": key}).encode()
+        req = urllib.request.Request(
+            LS_VALIDATE_URL, data=req_data,
+            headers={"Content-Type": "application/json", "Accept": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            result = json.loads(resp.read())
+        return {"valid": result.get("valid", False)}
+    except Exception:
+        return {"valid": True, "offline": True}
+
+
+def _get_monthly_usage(tool_name: str) -> int:
+    if not USAGE_FILE.exists():
+        return 0
+    try:
+        data = json.loads(USAGE_FILE.read_text())
+        return data.get(time.strftime("%Y-%m"), {}).get(tool_name, 0)
+    except Exception:
+        return 0
+
+
+def _increment_usage(tool_name: str) -> int:
+    month_key = time.strftime("%Y-%m")
+    data = {}
+    if USAGE_FILE.exists():
+        try:
+            data = json.loads(USAGE_FILE.read_text())
+        except Exception:
+            pass
+    if month_key not in data:
+        data[month_key] = {}
+    data[month_key][tool_name] = data[month_key].get(tool_name, 0) + 1
+    count = data[month_key][tool_name]
+    USAGE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    USAGE_FILE.write_text(json.dumps(data, indent=2))
+    return count