nodmix 2026.5.25

package/skills/model-usage/scripts/model_usage.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+"""
+Summarize CodexBar local cost usage by model.
+
+Defaults to current model (most recent daily entry), or list all models.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+
+def positive_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be >= 1")
+    return parsed
+
+
+def eprint(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def run_codexbar_cost(provider: str) -> List[Dict[str, Any]]:
+    cmd = ["codexbar", "cost", "--format", "json", "--provider", provider]
+    try:
+        output = subprocess.check_output(cmd, text=True)
+    except FileNotFoundError:
+        raise RuntimeError("codexbar not found on PATH. Install CodexBar CLI first.")
+    except subprocess.CalledProcessError as exc:
+        raise RuntimeError(f"codexbar cost failed (exit {exc.returncode}).")
+    try:
+        payload = json.loads(output)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Failed to parse codexbar JSON output: {exc}")
+    if not isinstance(payload, list):
+        raise RuntimeError("Expected codexbar cost JSON array.")
+    return payload
+
+
+def load_payload(input_path: Optional[str], provider: str) -> Dict[str, Any]:
+    if input_path:
+        if input_path == "-":
+            raw = sys.stdin.read()
+        else:
+            with open(input_path, "r", encoding="utf-8") as handle:
+                raw = handle.read()
+        data = json.loads(raw)
+    else:
+        data = run_codexbar_cost(provider)
+
+    if isinstance(data, dict):
+        return data
+
+    if isinstance(data, list):
+        for entry in data:
+            if isinstance(entry, dict) and entry.get("provider") == provider:
+                return entry
+        raise RuntimeError(f"Provider '{provider}' not found in codexbar payload.")
+
+    raise RuntimeError("Unsupported JSON input format.")
+
+
+@dataclass
+class ModelCost:
+    model: str
+    cost: float
+
+
+def parse_daily_entries(payload: Dict[str, Any]) -> List[Dict[str, Any]]:
+    daily = payload.get("daily")
+    if not daily:
+        return []
+    if not isinstance(daily, list):
+        return []
+    return [entry for entry in daily if isinstance(entry, dict)]
+
+
+def parse_date(value: str) -> Optional[date]:
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except Exception:
+        return None
+
+
+def filter_by_days(entries: List[Dict[str, Any]], days: Optional[int]) -> List[Dict[str, Any]]:
+    if not days:
+        return entries
+    cutoff = date.today() - timedelta(days=days - 1)
+    filtered: List[Dict[str, Any]] = []
+    for entry in entries:
+        day = entry.get("date")
+        if not isinstance(day, str):
+            continue
+        parsed = parse_date(day)
+        if parsed and parsed >= cutoff:
+            filtered.append(entry)
+    return filtered
+
+
+def aggregate_costs(entries: Iterable[Dict[str, Any]]) -> Dict[str, float]:
+    totals: Dict[str, float] = {}
+    for entry in entries:
+        breakdowns = entry.get("modelBreakdowns")
+        if not breakdowns:
+            continue
+        if not isinstance(breakdowns, list):
+            continue
+        for item in breakdowns:
+            if not isinstance(item, dict):
+                continue
+            model = item.get("modelName")
+            cost = item.get("cost")
+            if not isinstance(model, str):
+                continue
+            if not isinstance(cost, (int, float)):
+                continue
+            totals[model] = totals.get(model, 0.0) + float(cost)
+    return totals
+
+
+def pick_current_model(entries: List[Dict[str, Any]]) -> Tuple[Optional[str], Optional[str]]:
+    if not entries:
+        return None, None
+    sorted_entries = sorted(
+        entries,
+        key=lambda entry: entry.get("date") or "",
+    )
+    for entry in reversed(sorted_entries):
+        breakdowns = entry.get("modelBreakdowns")
+        if isinstance(breakdowns, list) and breakdowns:
+            scored: List[ModelCost] = []
+            for item in breakdowns:
+                if not isinstance(item, dict):
+                    continue
+                model = item.get("modelName")
+                cost = item.get("cost")
+                if isinstance(model, str) and isinstance(cost, (int, float)):
+                    scored.append(ModelCost(model=model, cost=float(cost)))
+            if scored:
+                scored.sort(key=lambda item: item.cost, reverse=True)
+                return scored[0].model, entry.get("date") if isinstance(entry.get("date"), str) else None
+        models_used = entry.get("modelsUsed")
+        if isinstance(models_used, list) and models_used:
+            last = models_used[-1]
+            if isinstance(last, str):
+                return last, entry.get("date") if isinstance(entry.get("date"), str) else None
+    return None, None
+
+
+def usd(value: Optional[float]) -> str:
+    if value is None:
+        return "—"
+    return f"${value:,.2f}"
+
+
+def latest_day_cost(entries: List[Dict[str, Any]], model: str) -> Tuple[Optional[str], Optional[float]]:
+    if not entries:
+        return None, None
+    sorted_entries = sorted(
+        entries,
+        key=lambda entry: entry.get("date") or "",
+    )
+    for entry in reversed(sorted_entries):
+        breakdowns = entry.get("modelBreakdowns")
+        if not isinstance(breakdowns, list):
+            continue
+        for item in breakdowns:
+            if not isinstance(item, dict):
+                continue
+            if item.get("modelName") == model:
+                cost = item.get("cost") if isinstance(item.get("cost"), (int, float)) else None
+                day = entry.get("date") if isinstance(entry.get("date"), str) else None
+                return day, float(cost) if cost is not None else None
+    return None, None
+
+
+def render_text_current(
+    provider: str,
+    model: str,
+    latest_date: Optional[str],
+    total_cost: Optional[float],
+    latest_cost: Optional[float],
+    latest_cost_date: Optional[str],
+    entry_count: int,
+) -> str:
+    lines = [f"Provider: {provider}", f"Current model: {model}"]
+    if latest_date:
+        lines.append(f"Latest model date: {latest_date}")
+    lines.append(f"Total cost (rows): {usd(total_cost)}")
+    if latest_cost_date:
+        lines.append(f"Latest day cost: {usd(latest_cost)} ({latest_cost_date})")
+    lines.append(f"Daily rows: {entry_count}")
+    return "\n".join(lines)
+
+
+def render_text_all(provider: str, totals: Dict[str, float]) -> str:
+    lines = [f"Provider: {provider}", "Models:"]
+    for model, cost in sorted(totals.items(), key=lambda item: item[1], reverse=True):
+        lines.append(f"- {model}: {usd(cost)}")
+    return "\n".join(lines)
+
+
+def build_json_current(
+    provider: str,
+    model: str,
+    latest_date: Optional[str],
+    total_cost: Optional[float],
+    latest_cost: Optional[float],
+    latest_cost_date: Optional[str],
+    entry_count: int,
+) -> Dict[str, Any]:
+    return {
+        "provider": provider,
+        "mode": "current",
+        "model": model,
+        "latestModelDate": latest_date,
+        "totalCostUSD": total_cost,
+        "latestDayCostUSD": latest_cost,
+        "latestDayCostDate": latest_cost_date,
+        "dailyRowCount": entry_count,
+    }
+
+
+def build_json_all(provider: str, totals: Dict[str, float]) -> Dict[str, Any]:
+    return {
+        "provider": provider,
+        "mode": "all",
+        "models": [
+            {"model": model, "totalCostUSD": cost}
+            for model, cost in sorted(totals.items(), key=lambda item: item[1], reverse=True)
+        ],
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Summarize CodexBar model usage from local cost logs.")
+    parser.add_argument("--provider", choices=["codex", "claude"], default="codex")
+    parser.add_argument("--mode", choices=["current", "all"], default="current")
+    parser.add_argument("--model", help="Explicit model name to report instead of auto-current.")
+    parser.add_argument("--input", help="Path to codexbar cost JSON (or '-' for stdin).")
+    parser.add_argument("--days", type=positive_int, help="Limit to last N days (based on daily rows).")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output.")
+
+    args = parser.parse_args()
+
+    try:
+        payload = load_payload(args.input, args.provider)
+    except Exception as exc:
+        eprint(str(exc))
+        return 1
+
+    entries = parse_daily_entries(payload)
+    entries = filter_by_days(entries, args.days)
+
+    if args.mode == "current":
+        model = args.model
+        latest_date = None
+        if not model:
+            model, latest_date = pick_current_model(entries)
+        if not model:
+            eprint("No model data found in codexbar cost payload.")
+            return 2
+        totals = aggregate_costs(entries)
+        total_cost = totals.get(model)
+        latest_cost_date, latest_cost = latest_day_cost(entries, model)
+
+        if args.format == "json":
+            payload_out = build_json_current(
+                provider=args.provider,
+                model=model,
+                latest_date=latest_date,
+                total_cost=total_cost,
+                latest_cost=latest_cost,
+                latest_cost_date=latest_cost_date,
+                entry_count=len(entries),
+            )
+            indent = 2 if args.pretty else None
+            print(json.dumps(payload_out, indent=indent, sort_keys=args.pretty))
+        else:
+            print(
+                render_text_current(
+                    provider=args.provider,
+                    model=model,
+                    latest_date=latest_date,
+                    total_cost=total_cost,
+                    latest_cost=latest_cost,
+                    latest_cost_date=latest_cost_date,
+                    entry_count=len(entries),
+                )
+            )
+        return 0
+
+    totals = aggregate_costs(entries)
+    if not totals:
+        eprint("No model breakdowns found in codexbar cost payload.")
+        return 2
+
+    if args.format == "json":
+        payload_out = build_json_all(provider=args.provider, totals=totals)
+        indent = 2 if args.pretty else None
+        print(json.dumps(payload_out, indent=indent, sort_keys=args.pretty))
+    else:
+        print(render_text_all(provider=args.provider, totals=totals))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/model-usage/scripts/test_model_usage.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+Tests for model_usage helpers.
+"""
+
+import argparse
+from datetime import date, timedelta
+from unittest import TestCase, main
+
+from model_usage import filter_by_days, positive_int
+
+
+class TestModelUsage(TestCase):
+    def test_positive_int_accepts_valid_numbers(self):
+        self.assertEqual(positive_int("1"), 1)
+        self.assertEqual(positive_int("7"), 7)
+
+    def test_positive_int_rejects_zero_and_negative(self):
+        with self.assertRaises(argparse.ArgumentTypeError):
+            positive_int("0")
+        with self.assertRaises(argparse.ArgumentTypeError):
+            positive_int("-3")
+
+    def test_filter_by_days_keeps_recent_entries(self):
+        today = date.today()
+        entries = [
+            {"date": (today - timedelta(days=5)).strftime("%Y-%m-%d"), "modelBreakdowns": []},
+            {"date": (today - timedelta(days=1)).strftime("%Y-%m-%d"), "modelBreakdowns": []},
+            {"date": today.strftime("%Y-%m-%d"), "modelBreakdowns": []},
+        ]
+
+        filtered = filter_by_days(entries, 2)
+
+        self.assertEqual(len(filtered), 2)
+        self.assertEqual(filtered[0]["date"], (today - timedelta(days=1)).strftime("%Y-%m-%d"))
+        self.assertEqual(filtered[1]["date"], today.strftime("%Y-%m-%d"))
+
+
+if __name__ == "__main__":
+    main()

package/skills/nano-pdf/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nano-pdf
+description: "Edit PDFs with natural-language instructions using the nano-pdf CLI."
+homepage: https://pypi.org/project/nano-pdf/
+metadata:
+  {
+    "nodmix":
+      {
+        "emoji": "📄",
+        "requires": { "bins": ["nano-pdf"] },
+        "install":
+          [
+            {
+              "id": "uv",
+              "kind": "uv",
+              "package": "nano-pdf",
+              "bins": ["nano-pdf"],
+              "label": "Install nano-pdf (uv)",
+            },
+          ],
+      },
+  }
+---
+
+# nano-pdf
+
+Use `nano-pdf` to apply edits to a specific page in a PDF using a natural-language instruction.
+
+## Quick start
+
+```bash
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+```
+
+Notes:
+
+- Page numbers are 0-based or 1-based depending on the tool's version/config; if the result looks off by one, retry with the other.
+- Always sanity-check the output PDF before sending it out.

package/skills/node-connect/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: node-connect
+description: "Diagnose Nodmix Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures."
+---
+
+# Node Connect
+
+Goal: find the one real route from node -> gateway, verify Nodmix is advertising that route, then fix pairing/auth.
+
+## Topology first
+
+Decide which case you are in before proposing fixes:
+
+- same machine / emulator / USB tunnel
+- same LAN / local Wi-Fi
+- same Tailscale tailnet
+- public URL / reverse proxy
+
+Do not mix them.
+
+- Local Wi-Fi problem: do not switch to Tailscale unless remote access is actually needed.
+- VPS / remote gateway problem: do not keep debugging `localhost` or LAN IPs.
+
+## If ambiguous, ask first
+
+If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
+
+Ask for:
+
+- which route they intend: same machine, same LAN, Tailscale tailnet, or public URL
+- whether they used QR/setup code or manual host/port
+- the exact app text/status/error, quoted exactly if possible
+- whether `nodmix devices list` shows a pending pairing request
+
+Do not guess from `can't connect`.
+
+## Canonical checks
+
+Prefer `nodmix qr --json`. It uses the same setup-code payload Android scans.
+
+```bash
+nodmix config get gateway.mode
+nodmix config get gateway.bind
+nodmix config get gateway.tailscale.mode
+nodmix config get gateway.remote.url
+nodmix config get gateway.auth.mode
+nodmix config get gateway.auth.allowTailscale
+nodmix config get plugins.entries.device-pair.config.publicUrl
+nodmix qr --json
+nodmix devices list
+nodmix nodes status
+```
+
+If this Nodmix instance is pointed at a remote gateway, also run:
+
+```bash
+nodmix qr --remote --json
+```
+
+If Tailscale is part of the story:
+
+```bash
+tailscale status --json
+```
+
+## Read the result, not guesses
+
+`nodmix qr --json` success means:
+
+- `gatewayUrl`: this is the actual endpoint the app should use.
+- `urlSource`: this tells you which config path won.
+
+Common good sources:
+
+- `gateway.bind=lan`: same Wi-Fi / LAN only
+- `gateway.bind=tailnet`: direct tailnet access
+- `gateway.tailscale.mode=serve` or `gateway.tailscale.mode=funnel`: Tailscale route
+- `plugins.entries.device-pair.config.publicUrl`: explicit public/reverse-proxy route
+- `gateway.remote.url`: remote gateway route
+
+## Root-cause map
+
+If `nodmix qr --json` says `Gateway is only bound to loopback`:
+
+- remote node cannot connect yet
+- fix the route, then generate a fresh setup code
+- `gateway.bind=auto` is not enough if the effective QR route is still loopback
+- same LAN: use `gateway.bind=lan`
+- same tailnet: prefer `gateway.tailscale.mode=serve` or use `gateway.bind=tailnet`
+- public internet: set a real `plugins.entries.device-pair.config.publicUrl` or `gateway.remote.url`
+
+If `gateway.bind=tailnet set, but no tailnet IP was found`:
+
+- gateway host is not actually on Tailscale
+
+If `qr --remote requires gateway.remote.url`:
+
+- remote-mode config is incomplete
+
+If the app says `pairing required`:
+
+- network route and auth worked
+- approve the pending device
+
+```bash
+nodmix devices list
+nodmix devices approve --latest
+```
+
+If the app says `bootstrap token invalid or expired`:
+
+- old setup code
+- generate a fresh one and rescan
+- do this after any URL/auth fix too
+
+If the app says `unauthorized`:
+
+- wrong token/password, or wrong Tailscale expectation
+- for Tailscale Serve, `gateway.auth.allowTailscale` must match the intended flow
+- otherwise use explicit token/password
+
+## Fast heuristics
+
+- Same Wi-Fi setup + gateway advertises `127.0.0.1`, `localhost`, or loopback-only config: wrong.
+- Remote setup + setup/manual uses private LAN IP: wrong.
+- Tailnet setup + gateway advertises LAN IP instead of MagicDNS / tailnet route: wrong.
+- Public URL set but QR still advertises something else: inspect `urlSource`; config is not what you think.
+- `nodmix devices list` shows pending requests: stop changing network config and approve first.
+
+## Fix style
+
+Reply with one concrete diagnosis and one route.
+
+If there is not enough signal yet, ask for setup + exact app text instead of guessing.
+
+Good:
+
+- `The gateway is still loopback-only, so a node on another network can never reach it. Enable Tailscale Serve, restart the gateway, run nodmix qr again, rescan, then approve the pending device pairing.`
+
+Bad:
+
+- `Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.`

package/skills/node-inspect-debugger/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: node-inspect-debugger
+description: Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.
+metadata: { "nodmix": { "emoji": "🪲", "requires": { "bins": ["node"] } } }
+---
+
+# Node Inspect Debugger
+
+Use for Node.js debugging that needs inspector access: hidden locals, async hangs, flaky tests, child processes, startup races, memory growth, or CPU hot paths.
+
+Default to `node inspect` first. Use Chrome DevTools Protocol only when you need scripted breakpoints, automated state capture, heap snapshots, or CPU profiles.
+
+Quick start
+
+- Pause on entry: `node inspect path/to/script.js`
+- TypeScript: `node --inspect-brk --import tsx path/to/script.ts`
+- Existing PID: `kill -SIGUSR1 <pid>` then `node inspect -p <pid>`
+- Inspect target list: `curl -s http://127.0.0.1:9229/json/list | jq`
+- Nodmix CLI path: `node --inspect-brk nodmix.mjs ...`
+- Nodmix test path: `NODMIX_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>`
+
+Debugger REPL
+
+- Continue/step: `cont`, `next`, `step`, `out`, `pause`
+- Breakpoints: `sb('file.js', 42)`, `sb(42)`, `sb('functionName')`, `breakpoints`, `cb('file.js', 42)`
+- Inspect: `bt`, `list(8)`, `watch('expr')`, `exec expr`
+- Current scope: `repl`, then evaluate locals directly; `Ctrl+C` exits repl mode.
+- Exit safely: `cont` before quitting if the process should continue; otherwise `kill`.
+
+Nodmix tips
+
+- Prefer `127.0.0.1` inspector binds. Do not expose `--inspect=0.0.0.0` unless the network is isolated.
+- For Vitest, debug one file with one worker. Avoid worker pools while stepping.
+- For TS source breakpoints, use `--enable-source-maps` when useful; `node inspect` can still show emitted paths.
+- For child processes, `NODE_OPTIONS=--inspect-brk` can propagate the inspector, but each child needs its own port.
+- For long-lived gateway or dev processes, attach by PID after confirming the target with `/json/list`.
+
+Programmatic CDP
+
+Install tooling outside the repo unless the project already depends on it:
+
+```bash
+mkdir -p /tmp/cdp-tools
+npm --prefix /tmp/cdp-tools i chrome-remote-interface
+NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs
+```
+
+Minimal driver:
+
+```js
+const CDP = require("chrome-remote-interface");
+
+(async () => {
+  const client = await CDP({ port: 9229 });
+  const { Debugger, Runtime } = client;
+
+  Debugger.paused(async ({ callFrames, reason }) => {
+    const top = callFrames[0];
+    console.log("paused", reason, top.url, top.location.lineNumber + 1);
+    const { result } = await Debugger.evaluateOnCallFrame({
+      callFrameId: top.callFrameId,
+      expression: "JSON.stringify({ pid: process.pid })",
+    });
+    console.log(result.value ?? result.description);
+    await Debugger.resume();
+  });
+
+  await Runtime.enable();
+  await Debugger.enable();
+  await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 });
+  await Runtime.runIfWaitingForDebugger();
+})();
+```
+
+Profiles
+
+- CPU: enable `Profiler`, `start`, wait, `stop`, write `/tmp/profile.cpuprofile`, open in Chrome DevTools.
+- Heap: enable `HeapProfiler`, collect `addHeapSnapshotChunk`, call `takeHeapSnapshot`, write `/tmp/heap.heapsnapshot`.
+
+Pitfalls
+
+- `--inspect` does not pause; use `--inspect-brk` when setup must happen before code runs.
+- Default port is `9229`; use `--inspect=0` or a unique port for parallel targets.
+- If a breakpoint misses, confirm file path, source map behavior, and whether execution already passed the line.
+- If the process appears frozen after detaching, it may still be paused in the debugger.