xtrm-tools 0.7.7 → 0.7.9

package/.xtrm/skills/default/gitnexus-cli/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus status
+```
+
+Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus clean
+```
+
+Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

package/.xtrm/skills/default/gitnexus-exploring/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# 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/.xtrm/skills/default/gitnexus-guide/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

package/.xtrm/skills/default/init-session/SKILL.md

@@ -1,3 +1,6 @@
+---
+description: "Bootstrap context for a new session — load latest report, relevant memories, and orient to current project state."
+---
 # Session Start
 
 Bootstrap context for a new session. Read the latest session report, load relevant memories, and orient to current project state.

package/.xtrm/skills/default/last30days/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: last30days
-version: "2.9.6"
 description: "Deep research engine covering the last 30 days across 10+ sources - Reddit, X/Twitter, YouTube, TikTok, Instagram, Hacker News, Polymarket, and the web. AI synthesizes findings into grounded, cited reports."
 argument-hint: 'last30 AI video tools, last30 best project management tools'
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebSearch
@@ -8,6 +7,7 @@ homepage: https://github.com/mvanhorn/last30days-skill
 repository: https://github.com/mvanhorn/last30days-skill
 author: mvanhorn
 license: MIT
+version: "2.9.7"
 user-invocable: true
 metadata:
   openclaw:

package/.xtrm/skills/default/last30days/scripts/lib/youtube_yt.py

@@ -260,6 +260,34 @@ def _clean_vtt(vtt_text: str) -> str:
 _YT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
 
 
+def _build_caption_track_candidates(caption_tracks: List[Dict[str, Any]]) -> List[str]:
+    """Return candidate caption track URLs in preferred fetch order."""
+    if not caption_tracks:
+        return []
+
+    en_exact = [track for track in caption_tracks if track.get("languageCode", "") == "en"]
+    en_variant = [
+        track for track in caption_tracks
+        if track.get("languageCode", "").startswith("en") and track not in en_exact
+    ]
+    original_lang = [
+        track for track in caption_tracks
+        if not track.get("languageCode", "").startswith("en")
+    ]
+
+    ordered_tracks = en_exact + en_variant + original_lang
+    seen: Set[str] = set()
+    candidate_urls: List[str] = []
+    for track in ordered_tracks:
+        base_url = track.get("baseUrl")
+        if not base_url or base_url in seen:
+            continue
+        seen.add(base_url)
+        candidate_urls.append(base_url)
+
+    return candidate_urls
+
+
 def _fetch_transcript_direct(video_id: str, timeout: int = 30) -> Optional[str]:
     """Fetch YouTube transcript via direct HTTP without yt-dlp.
 
@@ -319,41 +347,34 @@ def _fetch_transcript_direct(video_id: str, timeout: int = 30) -> Optional[str]:
         _log(f"Direct transcript: no caption tracks for {video_id}")
         return None
 
-    # Find English track (prefer exact 'en', then any en variant, then first track)
-    base_url = None
-    for track in caption_tracks:
-        lang = track.get("languageCode", "")
-        if lang == "en":
-            base_url = track.get("baseUrl")
-            break
-    if not base_url:
-        for track in caption_tracks:
-            lang = track.get("languageCode", "")
-            if lang.startswith("en"):
-                base_url = track.get("baseUrl")
-                break
-    if not base_url:
-        # Fall back to first available track
-        base_url = caption_tracks[0].get("baseUrl")
-    if not base_url:
+    candidate_urls = _build_caption_track_candidates(caption_tracks)
+    if not candidate_urls:
         _log(f"Direct transcript: no baseUrl in caption tracks for {video_id}")
         return None
 
-    # Step 3: Fetch the VTT subtitle file
-    sep = "&" if "?" in base_url else "?"
-    vtt_url = f"{base_url}{sep}fmt=vtt"
-    vtt_req = urllib.request.Request(vtt_url, headers=headers)
-    try:
-        with urllib.request.urlopen(vtt_req, timeout=timeout) as resp:
-            vtt_text = resp.read().decode("utf-8", errors="replace")
-    except (urllib.error.URLError, urllib.error.HTTPError, OSError, TimeoutError) as exc:
-        _log(f"Direct transcript: failed to fetch VTT for {video_id}: {exc}")
-        return None
+    subtitle_headers = {
+        **headers,
+        "Referer": watch_url,
+        "Origin": "https://www.youtube.com",
+        "Accept": "text/vtt,text/plain,*/*",
+    }
 
-    if not vtt_text or not vtt_text.strip():
-        return None
+    # Step 3: Fetch VTT subtitle file, trying preferred track order
+    for base_url in candidate_urls:
+        sep = "&" if "?" in base_url else "?"
+        vtt_url = f"{base_url}{sep}fmt=vtt"
+        vtt_req = urllib.request.Request(vtt_url, headers=subtitle_headers)
+        try:
+            with urllib.request.urlopen(vtt_req, timeout=timeout) as resp:
+                vtt_text = resp.read().decode("utf-8", errors="replace")
+        except (urllib.error.URLError, urllib.error.HTTPError, OSError, TimeoutError):
+            continue
+
+        if vtt_text and vtt_text.strip():
+            return vtt_text
 
-    return vtt_text
+    _log(f"Direct transcript: all caption track fetch attempts returned empty for {video_id}")
+    return None
 
 
 def _fetch_transcript_ytdlp(video_id: str, temp_dir: str) -> Optional[str]:
@@ -371,7 +392,7 @@ def _fetch_transcript_ytdlp(video_id: str, temp_dir: str) -> Optional[str]:
         "--ignore-config",
         "--no-cookies-from-browser",
         "--write-auto-subs",
-        "--sub-lang", "en",
+        "--sub-lang", "all",
         "--sub-format", "vtt",
         "--skip-download",
         "--no-warnings",
@@ -401,15 +422,13 @@ def _fetch_transcript_ytdlp(video_id: str, temp_dir: str) -> Optional[str]:
     except FileNotFoundError:
         return None
 
-    # yt-dlp may save as .en.vtt or .en-orig.vtt
-    vtt_path = Path(temp_dir) / f"{video_id}.en.vtt"
-    if not vtt_path.exists():
-        # Try alternate naming
-        for p in Path(temp_dir).glob(f"{video_id}*.vtt"):
-            vtt_path = p
-            break
-        else:
-            return None
+    # yt-dlp naming varies by language (e.g. .en.vtt, .it.vtt, .en-orig.vtt)
+    vtt_path = None
+    for p in Path(temp_dir).glob(f"{video_id}*.vtt"):
+        vtt_path = p
+        break
+    if not vtt_path:
+        return None
 
     try:
         return vtt_path.read_text(encoding="utf-8", errors="replace")

package/.xtrm/skills/default/sync-docs/references/doc-structure.md

@@ -20,7 +20,7 @@ This reference defines what belongs in each focused docs/ file vs README.md.
 | Quick start, one-liner install | `README.md` | Always |
 | Feature overview table | `README.md` | Always, < 20 lines |
 | Hook events, scripts, behavior | `docs/hooks.md` | When hooks/ dir exists |
-| Pi/Copilot extension catalog | `docs/pi-extensions.md` | When config/pi/extensions/ exists |
+| Pi/Copilot extension catalog | `docs/pi-extensions.md` | When packages/pi-extensions/extensions/ exists |
 | System architecture, components | `docs/architecture.md` | When > 2 major subsystems |
 | Policy rules and enforcement | `docs/policies.md` | When policies/ dir exists |
 | MCP server config and usage | `docs/mcp-servers.md` | When .mcp.json or mcp servers exist |

package/.xtrm/skills/default/sync-docs/references/schema.md

@@ -49,7 +49,7 @@ A list of glob patterns (fnmatch syntax) pointing to the source files this doc d
 source_of_truth_for:
   - "hooks/**/*.mjs"
   - "policies/*.json"
-  - "config/pi/extensions/**/*.ts"
+  - "packages/pi-extensions/extensions/**/*.ts"
 ```
 
 ### domain

package/.xtrm/skills/default/sync-docs/scripts/doc_structure_analyzer.py

@@ -45,8 +45,8 @@ SECTION_DOCS_MAP = [
 SUBSYSTEM_SIGNALS: list[tuple[str, str, str, str, str, str, list[str]]] = [
     ("hooks/", "hooks.md", "hooks/ directory exists",
      "Hooks Reference", "hooks", "reference", ["hooks/**/*.mjs", "policies/*.json"]),
-    ("config/pi/extensions/", "pi-extensions.md", "Pi extensions directory exists",
-     "Pi Extensions Reference", "pi-extensions", "reference", ["config/pi/extensions/**/*.ts"]),
+    ("packages/pi-extensions/extensions/", "pi-extensions.md", "Pi extensions directory exists",
+     "Pi Extensions Reference", "pi-extensions", "reference", ["packages/pi-extensions/extensions/**/*.ts"]),
     (".mcp.json", "mcp-servers.md", ".mcp.json present",
      "MCP Servers Configuration", "mcp-servers", "reference", [".mcp.json"]),
     ("policies/", "policies.md", "policies/ directory exists",