@pushrec/skills 0.2.0 → 0.3.4

package/bundled-skills/pushrec-skills/references/prerequisites.yaml

@@ -0,0 +1,412 @@
+# pushREC Skills Prerequisites
+# version: 1.1.0
+#
+# Skills NOT listed here require NO API keys or credentials (Level 0).
+# 80+ skills work immediately after install with zero configuration.
+#
+# Level definitions:
+#   L1: Google OAuth2 - one-time browser consent flow (~15 min total)
+#   L2: API keys - individual service signups (~2-5 min each)
+#   L3: Service accounts - KYC verification or usage-based billing (~10 min each)
+#   L4: Applications - requires desktop app (Obsidian) installed
+
+# ============================================================================
+# LEVEL 1: Google OAuth2
+# One-time setup: Create a Google Cloud project, enable APIs, create OAuth
+# credentials. All Google skills share the same GCP project.
+# ============================================================================
+
+gmail:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (one-time for all Google services)"
+      credentials_path: "~/.claude/.credentials/gmail-oauth.keys.json"
+      notes: "OAuth2 browser consent flow. Tokens stored at ~/.gmail-mcp/credentials.json"
+
+google-sheets:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/sheets-client-secret.json"
+      notes: "OAuth2 preferred. Service Account fallback supported."
+
+google-docs:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/docs-client-secret.json"
+      notes: "OAuth2 preferred. Service Account fallback supported."
+
+google-calendar:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/calendar-oauth.keys.json"
+      notes: "OAuth2 browser consent flow."
+
+google-drive:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/drive-oauth.keys.json"
+      notes: "OAuth2 browser consent flow."
+
+google-contacts:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/contacts-oauth.keys.json"
+      notes: "Read-only. Shares GCP project with Gmail."
+
+google-slides:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      credentials_path: "~/.claude/.credentials/slides-token.json"
+      notes: "OAuth2 or Service Account (GOOGLE_SERVICE_ACCOUNT_JSON)."
+
+finance-manager:
+  level: 1
+  requires:
+    - env: GOOGLE_OAUTH_CREDENTIALS
+      type: oauth2
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "15 minutes (shared with other Google services)"
+      notes: "Composes gmail + google-sheets + google-docs + ocr-processor. Set up Google OAuth first."
+
+# ============================================================================
+# LEVEL 2: API Keys
+# Individual service signups. Each key takes 2-5 minutes to obtain.
+# ============================================================================
+
+fal-ai:
+  level: 2
+  requires:
+    - env: FAL_KEY
+      type: api_key
+      service: FAL.ai
+      setup_url: https://fal.ai/dashboard/keys
+      setup_time: "2 minutes"
+      notes: "Set in ~/.claude/.env as FAL_KEY=your-key"
+
+ultimate-infographics:
+  level: 2
+  requires:
+    - env: FAL_KEY
+      type: api_key
+      service: FAL.ai
+      setup_url: https://fal.ai/dashboard/keys
+      setup_time: "2 minutes (shared with fal-ai)"
+      notes: "Uses fal-ai for Seedream 4.5 image generation."
+
+elevenlabs:
+  level: 2
+  requires:
+    - env: ELEVENLABS_API_KEY
+      type: api_key
+      service: ElevenLabs
+      setup_url: https://elevenlabs.io/app/settings/api-keys
+      setup_time: "2 minutes"
+      notes: "Set in ~/.claude/.env as ELEVENLABS_API_KEY=sk_xxx"
+
+gemini-vision:
+  level: 2
+  requires:
+    - env: GOOGLE_API_KEY
+      type: api_key
+      service: Google AI Studio
+      setup_url: https://aistudio.google.com/apikey
+      setup_time: "2 minutes"
+      notes: "Shared with ocr-processor. Set in ~/.claude/.env as GOOGLE_API_KEY=AIza..."
+
+ocr-processor:
+  level: 2
+  requires:
+    - env: GOOGLE_API_KEY
+      type: api_key
+      service: Google AI Studio
+      setup_url: https://aistudio.google.com/apikey
+      setup_time: "2 minutes (shared with gemini-vision)"
+      notes: "Primary provider: Gemini."
+    - env: MISTRAL_API_KEY
+      type: api_key
+      service: Mistral AI
+      setup_url: https://console.mistral.ai/api-keys
+      setup_time: "2 minutes"
+      notes: "Alternative provider for OCR. Set in ~/.claude/.env as MISTRAL_API_KEY=xxx"
+
+airtable:
+  level: 2
+  requires:
+    - env: AIRTABLE_API_KEY
+      type: api_key
+      service: Airtable
+      setup_url: https://airtable.com/create/tokens
+      setup_time: "3 minutes"
+      notes: "Personal Access Token (pat prefix). Set as AIRTABLE_API_KEY=patXXX"
+
+crm:
+  level: 2
+  requires:
+    - env: AIRTABLE_API_KEY
+      type: api_key
+      service: Airtable
+      setup_url: https://airtable.com/create/tokens
+      setup_time: "3 minutes (shared with airtable)"
+      notes: "CRM orchestration layer built on Airtable. Same API key."
+
+deploy-vercel:
+  level: 2
+  requires:
+    - env: VERCEL_TOKEN
+      type: api_key
+      service: Vercel
+      setup_url: https://vercel.com/account/tokens
+      setup_time: "2 minutes"
+      notes: "Personal access token. Set in ~/.claude/.env as VERCEL_TOKEN=xxx"
+
+retell-ai:
+  level: 2
+  requires:
+    - env: RETELL_API_KEY
+      type: api_key
+      service: Retell AI
+      setup_url: https://www.retellai.com/dashboard
+      setup_time: "3 minutes"
+      notes: "Set in ~/.claude/.env as RETELL_API_KEY=key_xxx"
+
+exa:
+  level: 2
+  requires:
+    - env: EXA_API_KEY
+      type: api_key
+      service: Exa.ai
+      setup_url: https://dashboard.exa.ai/api-keys
+      setup_time: "2 minutes"
+      notes: "AI-native search API. Set in ~/.claude/.env as EXA_API_KEY=xxx"
+
+gumroad:
+  level: 2
+  requires:
+    - env: GUMROAD_ACCESS_TOKEN
+      type: api_key
+      service: Gumroad
+      setup_url: https://app.gumroad.com/settings/advanced#application-form
+      setup_time: "3 minutes"
+      notes: "OAuth access token. Also supports ~/.gumroad/credentials file."
+
+convex:
+  level: 2
+  requires:
+    - env: CONVEX_DEPLOY_KEY
+      type: api_key
+      service: Convex
+      setup_url: https://dashboard.convex.dev
+      setup_time: "3 minutes"
+      notes: "Deploy key for Convex projects. Set in ~/.claude/.env as CONVEX_DEPLOY_KEY=xxx"
+
+youtube-api:
+  level: 2
+  requires:
+    - env: YOUTUBE_API_KEY
+      type: api_key
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "3 minutes (shared with GCP project)"
+      notes: "YouTube Data API v3. Optional - many operations work without key via yt-dlp."
+
+skool-api:
+  level: 2
+  requires:
+    - env: SKOOL_COOKIES
+      type: cookie_auth
+      service: Skool.com
+      setup_url: https://www.skool.com
+      setup_time: "5 minutes (browser login)"
+      notes: "Cookie-based auth persisted at ~/.skool/cookies.json. No API key - uses browser login."
+
+# ============================================================================
+# LEVEL 2 (continued): General-purpose API keys
+# Used by multiple skills or for advanced integrations.
+# ============================================================================
+
+deep-research:
+  level: 2
+  requires:
+    - env: OPENAI_API_KEY
+      type: api_key
+      service: OpenAI
+      setup_url: https://platform.openai.com/api-keys
+      setup_time: "2 minutes"
+      notes: "Used by deep-research and other skills that support OpenAI models."
+    - env: ANTHROPIC_API_KEY
+      type: api_key
+      service: Anthropic
+      setup_url: https://console.anthropic.com/settings/keys
+      setup_time: "2 minutes"
+      notes: "Used for API-routed sub-agents and headless operations."
+
+browser-automation:
+  level: 2
+  requires:
+    - env: RAPIDAPI_KEY
+      type: api_key
+      service: RapidAPI
+      setup_url: https://rapidapi.com/developer/dashboard
+      setup_time: "3 minutes"
+      notes: "Used by browser-automation and data enrichment integrations."
+
+# ============================================================================
+# LEVEL 3: Service Accounts
+# Require KYC verification, usage-based billing, or special configuration.
+# ============================================================================
+
+twilio:
+  level: 3
+  requires:
+    - env: TWILIO_ACCOUNT_SID
+      type: service_account
+      service: Twilio
+      setup_url: https://console.twilio.com
+      setup_time: "10 minutes"
+    - env: TWILIO_AUTH_TOKEN
+      type: service_account
+      service: Twilio
+      setup_url: https://console.twilio.com
+      setup_time: "included above"
+    - env: TWILIO_PHONE_NUMBER
+      type: service_account
+      service: Twilio
+      setup_url: https://console.twilio.com
+      setup_time: "included above"
+      notes: "Three env vars required. KYC may be needed for full access."
+
+bright-data:
+  level: 3
+  requires:
+    - env: API_TOKEN
+      type: service_account
+      service: Bright Data
+      setup_url: https://brightdata.com/cp/setting
+      setup_time: "10 minutes"
+      notes: "Usage-based billing. Set in ~/.claude/.env as API_TOKEN=xxx"
+
+google-maps:
+  level: 3
+  requires:
+    - env: GOOGLE_MAPS_API_KEY
+      type: api_key
+      service: Google Cloud Console
+      setup_url: https://console.cloud.google.com/apis/credentials
+      setup_time: "5 minutes"
+      notes: "Requires billing enabled on GCP project. Set as GOOGLE_MAPS_API_KEY=AIza..."
+
+weather:
+  level: 3
+  requires:
+    - env: OPENWEATHERMAP_API_KEY
+      type: api_key
+      service: OpenWeatherMap
+      setup_url: https://home.openweathermap.org/api_keys
+      setup_time: "3 minutes"
+      notes: "Free tier available. One Call 3.0 requires paid subscription."
+
+flight-tracker:
+  level: 3
+  requires:
+    - env: AVIATIONSTACK_API_KEY
+      type: api_key
+      service: AviationStack
+      setup_url: https://aviationstack.com/signup/free
+      setup_time: "3 minutes"
+      notes: "Free tier available with limited requests."
+
+claude-gateway:
+  level: 3
+  requires:
+    - env: DISCORD_BOT_TOKEN
+      type: api_key
+      service: Discord
+      setup_url: https://discord.com/developers/applications
+      setup_time: "10 minutes"
+    - env: DISCORD_CHANNEL_ID
+      type: config
+      service: Discord
+      setup_time: "included above"
+    - env: DISCORD_GUILD_ID
+      type: config
+      service: Discord
+      setup_time: "included above"
+      notes: "Three env vars required. Create Discord bot application and invite to server."
+
+voice-agent-v2:
+  level: 3
+  requires:
+    - env: LIVEKIT_API_KEY
+      type: api_key
+      service: LiveKit
+      setup_url: https://cloud.livekit.io
+      setup_time: "5 minutes"
+    - env: LIVEKIT_API_SECRET
+      type: api_key
+      service: LiveKit
+      setup_time: "included above"
+    - env: LIVEKIT_URL
+      type: config
+      service: LiveKit
+      setup_time: "included above"
+      notes: "Three env vars required. LiveKit Cloud or self-hosted."
+
+# ============================================================================
+# LEVEL 4: Applications
+# Requires desktop software installed on the user's machine.
+# ============================================================================
+
+vault-manager:
+  level: 4
+  requires:
+    - env: OBSIDIAN_INSTALLED
+      type: application
+      service: Obsidian
+      setup_url: https://obsidian.md
+      setup_time: "30 minutes (install + vault setup)"
+      notes: "Free app. Requires an Obsidian vault configured with PARA structure."
+
+life-os:
+  level: 4
+  requires:
+    - env: OBSIDIAN_INSTALLED
+      type: application
+      service: Obsidian
+      setup_url: https://obsidian.md
+      setup_time: "30 minutes (install + vault setup)"
+      notes: "Requires vault-manager configured first. Life Operating System orchestrator."

package/bundled-skills/pushrec-skills/scripts/diagnostic.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""pushREC Skills diagnostic: checks system readiness for Claude Code skills.
+
+Standalone Python 3.8+, zero external dependencies.
+Output: JSON to stdout (parseable by Claude Code).
+Exit codes: 0 = all good, 1 = missing critical prereqs, 2 = warnings only.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+VERSION = "1.1.0"
+SKILLS_DIR = Path.home() / ".claude" / "skills"
+CONFIG_PATH = Path.home() / ".pushrec" / "config.json"
+ENV_PATH = Path.home() / ".claude" / ".env"
+PREREQUISITES_PATH = Path(__file__).resolve().parent.parent / "references" / "prerequisites.yaml"
+
+# Fallback list used when prerequisites.yaml cannot be read
+_FALLBACK_KEY_PREFIXES = [
+    "ELEVENLABS_API_KEY",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "FAL_KEY",
+    "GOOGLE_API_KEY",
+    "GOOGLE_MAPS_API_KEY",
+    "YOUTUBE_API_KEY",
+    "RAPIDAPI_KEY",
+    "TWILIO_ACCOUNT_SID",
+    "TWILIO_AUTH_TOKEN",
+    "RETELL_API_KEY",
+    "API_TOKEN",
+    "AIRTABLE_API_KEY",
+    "VERCEL_TOKEN",
+    "OPENWEATHERMAP_API_KEY",
+    "AVIATIONSTACK_API_KEY",
+    "DISCORD_BOT_TOKEN",
+    "MISTRAL_API_KEY",
+]
+
+
+def load_key_prefixes():
+    """Load API key env var names from prerequisites.yaml, falling back to hardcoded list."""
+    try:
+        with open(PREREQUISITES_PATH, "r") as f:
+            content = f.read()
+        # Simple YAML parsing: extract all `env: VALUE` lines (no PyYAML dependency)
+        prefixes = set()
+        for line in content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("- env:") or stripped.startswith("env:"):
+                value = stripped.split(":", 1)[1].strip()
+                if value:
+                    prefixes.add(value)
+        if prefixes:
+            return sorted(prefixes)
+    except (OSError, ValueError):
+        pass
+    return _FALLBACK_KEY_PREFIXES
+
+
+KNOWN_KEY_PREFIXES = load_key_prefixes()
+
+
+def run_command(args):
+    """Run a shell command and return (success, stdout_stripped)."""
+    try:
+        result = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.returncode == 0, result.stdout.strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return False, ""
+
+
+def parse_version(version_string):
+    """Extract numeric version tuple from a version string like 'v22.1.0' or '2.1.45'."""
+    cleaned = version_string.lstrip("v").strip()
+    parts = []
+    for segment in cleaned.split("."):
+        digits = ""
+        for char in segment:
+            if char.isdigit():
+                digits += char
+            else:
+                break
+        if digits:
+            parts.append(int(digits))
+    return tuple(parts) if parts else (0,)
+
+
+def version_gte(current, minimum):
+    """Check if current version >= minimum version."""
+    current_tuple = parse_version(current)
+    minimum_tuple = parse_version(minimum)
+    return current_tuple >= minimum_tuple
+
+
+def check_claude_code():
+    """Check Claude Code installation and version."""
+    success, output = run_command(["claude", "--version"])
+    if not success:
+        return {"status": "fail", "version": None, "minimum": "2.1.0"}
+    version = output.strip()
+    if version_gte(version, "2.1.0"):
+        return {"status": "pass", "version": version, "minimum": "2.1.0"}
+    return {"status": "fail", "version": version, "minimum": "2.1.0"}
+
+
+def check_node():
+    """Check Node.js installation and version."""
+    success, output = run_command(["node", "--version"])
+    if not success:
+        return {"status": "fail", "version": None, "minimum": "20.0.0"}
+    version = output.strip()
+    if version_gte(version, "20.0.0"):
+        return {"status": "pass", "version": version, "minimum": "20.0.0"}
+    return {"status": "fail", "version": version, "minimum": "20.0.0"}
+
+
+def check_npm():
+    """Check npm installation."""
+    success, output = run_command(["npm", "--version"])
+    if not success:
+        return {"status": "fail", "version": None}
+    return {"status": "pass", "version": output.strip()}
+
+
+def check_skills_installed():
+    """Count installed skills by looking for SKILL.md files."""
+    if not SKILLS_DIR.is_dir():
+        return {"status": "fail", "count": 0}
+    count = 0
+    for child in SKILLS_DIR.iterdir():
+        if child.is_dir() and (child / "SKILL.md").is_file():
+            count += 1
+    if count == 0:
+        return {"status": "fail", "count": 0}
+    return {"status": "pass", "count": count}
+
+
+def check_license():
+    """Check pushREC license status via config.json."""
+    if not CONFIG_PATH.is_file():
+        return {"status": "fail", "installed_skills": 0}
+    try:
+        with open(CONFIG_PATH, "r") as f:
+            config = json.load(f)
+        installed = config.get("installedSkills", {})
+        count = len(installed) if isinstance(installed, dict) else 0
+        if count > 0:
+            return {"status": "pass", "installed_skills": count}
+        return {"status": "fail", "installed_skills": 0}
+    except (json.JSONDecodeError, OSError):
+        return {"status": "fail", "installed_skills": 0}
+
+
+def check_api_keys():
+    """Detect configured API keys from ~/.claude/.env."""
+    detected = []
+    if not ENV_PATH.is_file():
+        return {"status": "info", "detected": 0, "keys": []}
+    try:
+        with open(ENV_PATH, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                for prefix in KNOWN_KEY_PREFIXES:
+                    if line.startswith(prefix + "="):
+                        value = line.split("=", 1)[1].strip().strip('"').strip("'")
+                        if value:
+                            detected.append(prefix)
+                        break
+    except OSError:
+        pass
+    return {"status": "info", "detected": len(detected), "keys": detected}
+
+
+def check_obsidian():
+    """Check if Obsidian is installed (platform-specific)."""
+    system = platform.system()
+    if system == "Darwin":
+        installed = Path("/Applications/Obsidian.app").exists()
+    elif system == "Linux":
+        success, _ = run_command(["which", "obsidian"])
+        installed = success
+    elif system == "Windows":
+        success, _ = run_command(["where", "obsidian"])
+        installed = success
+    else:
+        installed = False
+    return {"status": "info", "installed": installed}
+
+
+def main():
+    # Exit silently in headless mode — hooks must never block headless sessions
+    # (e.g. CI pipelines, sub-agents) with interactive diagnostics or stdout noise.
+    if os.environ.get("CLAUDE_HEADLESS"):
+        sys.exit(0)
+
+    checks = {
+        "claude_code": check_claude_code(),
+        "node": check_node(),
+        "npm": check_npm(),
+        "skills_installed": check_skills_installed(),
+        "license": check_license(),
+        "api_keys": check_api_keys(),
+        "obsidian": check_obsidian(),
+    }
+
+    critical_failures = []
+    warnings = []
+
+    if checks["claude_code"]["status"] == "fail":
+        critical_failures.append("Claude Code")
+    if checks["node"]["status"] == "fail":
+        critical_failures.append("Node.js v20+")
+    if checks["npm"]["status"] == "fail":
+        critical_failures.append("npm")
+    if checks["skills_installed"]["status"] == "fail":
+        warnings.append("No skills installed")
+    if checks["license"]["status"] == "fail":
+        warnings.append("No active license")
+
+    if critical_failures:
+        exit_code = 1
+        summary = f"Missing critical prerequisites: {', '.join(critical_failures)}."
+    elif warnings:
+        exit_code = 2
+        summary = f"Warnings: {', '.join(warnings)}."
+    else:
+        skills_count = checks["skills_installed"].get("count", 0)
+        api_count = checks["api_keys"].get("detected", 0)
+        summary = f"All systems ready. {skills_count} skills installed, {api_count} API keys detected."
+        exit_code = 0
+
+    report = {
+        "version": VERSION,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "platform": platform.system().lower(),
+        "npm_version": checks["npm"].get("version"),
+        "skills_count": checks["skills_installed"].get("count", 0),
+        "checks": checks,
+        "exit_code": exit_code,
+        "summary": summary,
+    }
+
+    print(json.dumps(report, indent=2))
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()