xtrm-tools 0.7.0 → 0.7.2

package/skills/documenting/scripts/validate_metadata.py

@@ -1,242 +0,0 @@
-#!/usr/bin/env python3
-"""
-Validate SSOT memory metadata compliance.
-
-Checks if a memory file has all required frontmatter fields and follows
-the naming conventions defined in the SSOT guidelines.
-"""
-
-import sys
-import re
-from pathlib import Path
-import yaml
-
-
-def extract_headings(content: str) -> list:
-    """Extract (heading, first_sentence) for every ## section (not ###)."""
-    results = []
-    lines = content.splitlines()
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-        if line.startswith("## ") and not line.startswith("### "):
-            heading = line[3:].strip()
-            summary = ""
-            j = i + 1
-            in_code = False
-            while j < len(lines):
-                l = lines[j].strip()
-                if l.startswith("```"):
-                    in_code = not in_code
-                    j += 1
-                    continue
-                if not in_code and l and not l.startswith("#") and not l.startswith("|") and not l.startswith("-"):
-                    # Take up to first period, strip trailing period
-                    sentence = l.split(".")[0].strip()
-                    summary = sentence[:120]
-                    break
-                j += 1
-            results.append((heading, summary))
-        i += 1
-    return results
-
-
-def generate_index_table(headings: list) -> str:
-    """Generate a full markdown table string from headings list."""
-    rows = ["| Section | Summary |", "|---|---|"]
-    for heading, summary in headings:
-        anchor = heading.lower()
-        for ch in "/()":
-            anchor = anchor.replace(ch, "")
-        anchor = re.sub(r"[\s_]+", "-", anchor)
-        anchor = re.sub(r"-+", "-", anchor)
-        anchor = anchor.strip("-")
-        rows.append(f"| [{heading}](#{anchor}) | {summary or '_no summary_'} |")
-    return "\n".join(rows) + "\n"
-
-
-def inject_index(content: str, table: str) -> str:
-    """Replace existing INDEX block or insert one after frontmatter closing ---."""
-    header = "<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->\n"
-    footer = "<!-- END INDEX -->"
-    block = f"{header}{table}{footer}"
-
-    # Replace existing block
-    existing = re.search(r"<!-- INDEX:.*?-->.*?<!-- END INDEX -->", content, re.DOTALL)
-    if existing:
-        return content[:existing.start()] + block + content[existing.end():]
-
-    # Insert after second --- (end of frontmatter)
-    fm_match = re.match(r"^(---\n.*?\n---\n)(.*)", content, re.DOTALL)
-    if fm_match:
-        return fm_match.group(1) + "\n" + block + "\n" + fm_match.group(2)
-
-    return block + "\n" + content
-
-
-REQUIRED_FIELDS = {
-    "ssot": ["title", "version", "updated", "scope", "category", "subcategory", "domain"],
-    "pattern": ["title", "version", "updated", "scope", "category", "domain"],
-    "plan": ["title", "version", "updated", "scope", "category"],
-    "reference": ["title", "scope", "category"],
-    "archive": ["title", "version", "updated", "scope", "category", "archived_date"],
-}
-
-CATEGORY_SUFFIXES = ["ssot", "pattern", "plan", "reference", "archive", "troubleshoot", "commit_log"]
-
-
-def extract_frontmatter(content):
-    """Extract YAML frontmatter from markdown content."""
-    match = re.match(r'^---\n(.*?)\n---\n', content, re.DOTALL)
-    if not match:
-        return None
-    try:
-        return yaml.safe_load(match.group(1))
-    except yaml.YAMLError as e:
-        print(f"ERROR: Invalid YAML frontmatter: {e}")
-        return None
-
-
-def validate_naming(filename):
-    """Validate filename follows naming conventions."""
-    errors = []
-
-    # Check if ends with .md
-    if not filename.endswith('.md'):
-        errors.append("Filename should end with .md")
-        return errors
-
-    stem = filename[:-3]  # Remove .md
-    
-    # Check if ends with known category suffix
-    has_suffix = any(stem.endswith(f"_{suffix}") for suffix in CATEGORY_SUFFIXES)
-    if not has_suffix:
-        errors.append(f"Filename should end with one of: {', '.join(['_' + s + '.md' for s in CATEGORY_SUFFIXES])}")
-
-    return errors
-
-
-def validate_version(version):
-    """Validate semantic version format (x.y.z)."""
-    if not version:
-        return False
-    pattern = r'^\d+\.\d+\.\d+$'
-    return bool(re.match(pattern, str(version)))
-
-
-def validate_metadata(filepath):
-    """Validate memory metadata."""
-    path = Path(filepath)
-
-    if not path.exists():
-        print(f"ERROR: File not found: {filepath}")
-        return False
-
-    print(f"Validating: {path.name}")
-    print("=" * 60)
-
-    errors = []
-    warnings = []
-
-    # Check naming convention
-    naming_errors = validate_naming(path.name)
-    errors.extend(naming_errors)
-
-    # Read content
-    content = path.read_text(encoding='utf-8')
-
-    # Extract frontmatter
-    metadata = extract_frontmatter(content)
-    if metadata is None:
-        errors.append("Missing or invalid YAML frontmatter (should be between --- markers)")
-        print_results(errors, warnings)
-        return False
-
-    # Determine category from filename suffix
-    category = None
-    stem = path.name[:-3]
-    for suffix in CATEGORY_SUFFIXES:
-        if stem.endswith(f"_{suffix}"):
-            category = suffix
-            break
-
-    # Check required fields based on category
-    # If category is troubleshoot or commit_log, they might not have strict requirements yet
-    if category in REQUIRED_FIELDS:
-        required = REQUIRED_FIELDS[category]
-        missing_fields = [field for field in required if field not in metadata]
-        if missing_fields:
-            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
-    else:
-        # Default to ssot requirements if unknown but has suffix
-        required = REQUIRED_FIELDS["ssot"]
-        missing_fields = [field for field in required if field not in metadata]
-        if missing_fields:
-            errors.append(f"Missing required fields: {', '.join(missing_fields)}")
-
-    # Validate version format (if present)
-    if "version" in metadata:
-        if not validate_version(metadata["version"]):
-            errors.append(f"Invalid version format: {metadata['version']} (should be x.y.z)")
-
-    # Validate updated timestamp (if present)
-    if "updated" in metadata:
-        updated = str(metadata["updated"])
-        # Check for ISO8601-ish format (basic validation)
-        if not re.match(r'^\d{4}-\d{2}-\d{2}', updated):
-            warnings.append(f"Updated timestamp should be ISO8601 format: {updated}")
-
-    # Check for domain field (should be array)
-    if "domain" in metadata:
-        if not isinstance(metadata["domain"], list):
-            errors.append("Domain field should be an array/list")
-
-    # Check for changelog in SSOT files
-    if category == "ssot" and "changelog" not in metadata:
-        warnings.append("SSOT files should include a changelog section in frontmatter")
-
-    print_results(errors, warnings)
-
-    # Regenerate INDEX block unconditionally (navigation aid, independent of schema validity)
-    headings = extract_headings(content)
-    if headings:
-        table = generate_index_table(headings)
-        new_content = inject_index(content, table)
-        if new_content != content:
-            path.write_text(new_content, encoding="utf-8")
-            print("  ✏️  INDEX regenerated.")
-
-    return len(errors) == 0
-
-
-def print_results(errors, warnings):
-    """Print validation results."""
-    if errors:
-        print("\n❌ ERRORS:")
-        for error in errors:
-            print(f"  - {error}")
-
-    if warnings:
-        print("\n⚠️  WARNINGS:")
-        for warning in warnings:
-            print(f"  - {warning}")
-
-    if not errors and not warnings:
-        print("\n✅ VALID: All checks passed!")
-
-    print("=" * 60)
-
-
-def main():
-    if len(sys.argv) < 2:
-        print("Usage: validate_metadata.py <memory-file.md>")
-        print("Example: validate_metadata.py analytics_volatility_ssot.md")
-        sys.exit(1)
-
-    filepath = sys.argv[1]
-    success = validate_metadata(filepath)
-    sys.exit(0 if success else 1)
-
-
-if __name__ == "__main__":
-    main()

package/skills/documenting/templates/CHANGELOG.md.template

@@ -1,13 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [{initial_version}] - {release_date}
-
-### Added
-- Initial release

package/skills/find-skills/SKILL.md

@@ -1,133 +0,0 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```

package/skills/gitnexus-exploring/SKILL.md

@@ -1,75 +0,0 @@
----
-name: gitnexus-exploring
-description: Navigate unfamiliar code using GitNexus knowledge graph
----
-
-# Exploring Codebases with GitNexus
-
-## When to Use
-- "How does authentication work?"
-- "What's the project structure?"
-- "Show me the main components"
-- "Where is the database logic?"
-- Understanding code you haven't seen before
-
-## Workflow
-
-```
-1. READ gitnexus://repos                          → Discover indexed repos
-2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
-4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
-5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
-```
-
-> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
-
-## Checklist
-
-```
-- [ ] READ gitnexus://repo/{name}/context
-- [ ] gitnexus_query for the concept you want to understand
-- [ ] Review returned processes (execution flows)
-- [ ] gitnexus_context on key symbols for callers/callees
-- [ ] READ process resource for full execution traces
-- [ ] Read source files for implementation details
-```
-
-## Resources
-
-| Resource | What you get |
-|----------|-------------|
-| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
-| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
-| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
-| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
-
-## Tools
-
-**gitnexus_query** — find execution flows related to a concept:
-```
-gitnexus_query({query: "payment processing"})
-→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
-→ Symbols grouped by flow with file locations
-```
-
-**gitnexus_context** — 360-degree view of a symbol:
-```
-gitnexus_context({name: "validateUser"})
-→ Incoming calls: loginHandler, apiMiddleware
-→ Outgoing calls: checkToken, getUserById
-→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
-```
-
-## Example: "How does payment processing work?"
-
-```
-1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. gitnexus_query({query: "payment processing"})
-   → CheckoutFlow: processPayment → validateCard → chargeStripe
-   → RefundFlow: initiateRefund → calculateRefund → processRefund
-3. gitnexus_context({name: "processPayment"})
-   → Incoming: checkoutHandler, webhookHandler
-   → Outgoing: validateCard, chargeStripe, saveTransaction
-4. Read src/payments/processor.ts for implementation details
-```

package/skills/gitnexus-impact-analysis/SKILL.md

@@ -1,94 +0,0 @@
----
-name: gitnexus-impact-analysis
-description: Analyze blast radius before making code changes
----
-
-# Impact Analysis with GitNexus
-
-## When to Use
-- "Is it safe to change this function?"
-- "What will break if I modify X?"
-- "Show me the blast radius"
-- "Who uses this code?"
-- Before making non-trivial code changes
-- Before committing — to understand what your changes affect
-
-## Workflow
-
-```
-1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
-2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
-3. gitnexus_detect_changes()                               → Map current git changes to affected flows
-4. Assess risk and report to user
-```
-
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
-
-## Checklist
-
-```
-- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
-- [ ] Review d=1 items first (these WILL BREAK)
-- [ ] Check high-confidence (>0.8) dependencies
-- [ ] READ processes to check affected execution flows
-- [ ] gitnexus_detect_changes() for pre-commit check
-- [ ] Assess risk level and report to user
-```
-
-## Understanding Output
-
-| Depth | Risk Level | Meaning |
-|-------|-----------|---------|
-| d=1 | **WILL BREAK** | Direct callers/importers |
-| d=2 | LIKELY AFFECTED | Indirect dependencies |
-| d=3 | MAY NEED TESTING | Transitive effects |
-
-## Risk Assessment
-
-| Affected | Risk |
-|----------|------|
-| <5 symbols, few processes | LOW |
-| 5-15 symbols, 2-5 processes | MEDIUM |
-| >15 symbols or many processes | HIGH |
-| Critical path (auth, payments) | CRITICAL |
-
-## Tools
-
-**gitnexus_impact** — the primary tool for symbol blast radius:
-```
-gitnexus_impact({
-  target: "validateUser",
-  direction: "upstream",
-  minConfidence: 0.8,
-  maxDepth: 3
-})
-
-→ d=1 (WILL BREAK):
-  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
-  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
-
-→ d=2 (LIKELY AFFECTED):
-  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
-```
-
-**gitnexus_detect_changes** — git-diff based impact analysis:
-```
-gitnexus_detect_changes({scope: "staged"})
-
-→ Changed: 5 symbols in 3 files
-→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
-→ Risk: MEDIUM
-```
-
-## Example: "What breaks if I change validateUser?"
-
-```
-1. gitnexus_impact({target: "validateUser", direction: "upstream"})
-   → d=1: loginHandler, apiMiddleware (WILL BREAK)
-   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
-
-2. READ gitnexus://repo/my-app/processes
-   → LoginFlow and TokenRefresh touch validateUser
-
-3. Risk: 2 direct callers, 2 processes = MEDIUM
-```

package/skills/gitnexus-refactoring/SKILL.md

@@ -1,113 +0,0 @@
----
-name: gitnexus-refactoring
-description: Plan safe refactors using blast radius and dependency mapping
----
-
-# Refactoring with GitNexus
-
-## When to Use
-- "Rename this function safely"
-- "Extract this into a module"
-- "Split this service"
-- "Move this to a new file"
-- Any task involving renaming, extracting, splitting, or restructuring code
-
-## Workflow
-
-```
-1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
-2. gitnexus_query({query: "X"})                            → Find execution flows involving X
-3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
-4. Plan update order: interfaces → implementations → callers → tests
-```
-
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
-
-## Checklists
-
-### Rename Symbol
-```
-- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
-- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
-- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
-- [ ] gitnexus_detect_changes() — verify only expected files changed
-- [ ] Run tests for affected processes
-```
-
-### Extract Module
-```
-- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
-- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
-- [ ] Define new module interface
-- [ ] Extract code, update imports
-- [ ] gitnexus_detect_changes() — verify affected scope
-- [ ] Run tests for affected processes
-```
-
-### Split Function/Service
-```
-- [ ] gitnexus_context({name: target}) — understand all callees
-- [ ] Group callees by responsibility
-- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
-- [ ] Create new functions/services
-- [ ] Update callers
-- [ ] gitnexus_detect_changes() — verify affected scope
-- [ ] Run tests for affected processes
-```
-
-## Tools
-
-**gitnexus_rename** — automated multi-file rename:
-```
-gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
-→ 12 edits across 8 files
-→ 10 graph edits (high confidence), 2 ast_search edits (review)
-→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
-```
-
-**gitnexus_impact** — map all dependents first:
-```
-gitnexus_impact({target: "validateUser", direction: "upstream"})
-→ d=1: loginHandler, apiMiddleware, testUtils
-→ Affected Processes: LoginFlow, TokenRefresh
-```
-
-**gitnexus_detect_changes** — verify your changes after refactoring:
-```
-gitnexus_detect_changes({scope: "all"})
-→ Changed: 8 files, 12 symbols
-→ Affected processes: LoginFlow, TokenRefresh
-→ Risk: MEDIUM
-```
-
-**gitnexus_cypher** — custom reference queries:
-```cypher
-MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
-RETURN caller.name, caller.filePath ORDER BY caller.filePath
-```
-
-## Risk Rules
-
-| Risk Factor | Mitigation |
-|-------------|------------|
-| Many callers (>5) | Use gitnexus_rename for automated updates |
-| Cross-area refs | Use detect_changes after to verify scope |
-| String/dynamic refs | gitnexus_query to find them |
-| External/public API | Version and deprecate properly |
-
-## Example: Rename `validateUser` to `authenticateUser`
-
-```
-1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
-   → 12 edits: 10 graph (safe), 2 ast_search (review)
-   → Files: validator.ts, login.ts, middleware.ts, config.json...
-
-2. Review ast_search edits (config.json: dynamic reference!)
-
-3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
-   → Applied 12 edits across 8 files
-
-4. gitnexus_detect_changes({scope: "all"})
-   → Affected: LoginFlow, TokenRefresh
-   → Risk: MEDIUM — run tests for these flows
-```