fengming 0.3.7 → 0.3.9

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

@@ -1,319 +0,0 @@
-#!/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

@@ -1,40 +0,0 @@
-#!/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

@@ -1,38 +0,0 @@
----
-name: nano-pdf
-description: "Edit PDFs with natural-language instructions using the nano-pdf CLI."
-homepage: https://pypi.org/project/nano-pdf/
-metadata:
-  {
-    "fengming":
-      {
-        "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

@@ -1,143 +0,0 @@
----
-name: node-connect
-description: "Diagnose FengMing 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 FengMing 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 `fengming devices list` shows a pending pairing request
-
-Do not guess from `can't connect`.
-
-## Canonical checks
-
-Prefer `fengming qr --json`. It uses the same setup-code payload Android scans.
-
-```bash
-fengming config get gateway.mode
-fengming config get gateway.bind
-fengming config get gateway.tailscale.mode
-fengming config get gateway.remote.url
-fengming config get gateway.auth.mode
-fengming config get gateway.auth.allowTailscale
-fengming config get plugins.entries.device-pair.config.publicUrl
-fengming qr --json
-fengming devices list
-fengming nodes status
-```
-
-If this FengMing instance is pointed at a remote gateway, also run:
-
-```bash
-fengming qr --remote --json
-```
-
-If Tailscale is part of the story:
-
-```bash
-tailscale status --json
-```
-
-## Read the result, not guesses
-
-`fengming 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 `fengming 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
-fengming devices list
-fengming devices approve --latest   # preview only; copy the requestId from output
-fengming devices approve <requestId>
-```
-
-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.
-- `fengming 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 fengming 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

@@ -1,85 +0,0 @@
----
-name: node-inspect-debugger
-description: Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.
-metadata: { "fengming": { "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`
-- FengMing CLI path: `node --inspect-brk fengming.mjs ...`
-- FengMing test path: `FENGMING_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`.
-
-FengMing 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.

package/skills/openai-whisper/SKILL.md

@@ -1,38 +0,0 @@
----
-name: openai-whisper
-description: "Local speech-to-text with the Whisper CLI (no API key)."
-homepage: https://openai.com/research/whisper
-metadata:
-  {
-    "fengming":
-      {
-        "emoji": "🎤",
-        "requires": { "bins": ["whisper"] },
-        "install":
-          [
-            {
-              "id": "brew",
-              "kind": "brew",
-              "formula": "openai-whisper",
-              "bins": ["whisper"],
-              "label": "Install OpenAI Whisper (brew)",
-            },
-          ],
-      },
-  }
----
-
-# Whisper (CLI)
-
-Use `whisper` to transcribe audio locally.
-
-Quick start
-
-- `whisper /path/audio.mp3 --model medium --output_format txt --output_dir .`
-- `whisper /path/audio.m4a --task translate --output_format srt`
-
-Notes
-
-- Models download to `~/.cache/whisper` on first run.
-- `--model` defaults to `turbo` on this install.
-- Use smaller models for speed, larger for accuracy.