@heytherevibin/skillforge 0.2.1

package/lib/packs.js

@@ -0,0 +1,184 @@
+/**
+ * Skill pack installer.
+ *
+ * A "pack" is any git repo containing a skillforge.json manifest at the root:
+ *   {
+ *     "name": "my-pack",
+ *     "version": "1.0.0",
+ *     "skills": ["skill-one", "skill-two"]   // folder names relative to repo root
+ *   }
+ *
+ * Packs are git-cloned to ~/.skillforge/packs/<source-hash>/ and their
+ * declared skill folders are symlinked into ~/.skillforge/skills/.
+ * This means uninstall just removes the symlinks + the cached clone,
+ * and updates are a single `git pull`.
+ */
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.skillforge');
+const PACKS_DIR = path.join(CONFIG_DIR, 'packs');
+const USER_SKILLS_DIR = path.join(CONFIG_DIR, 'skills');
+const PACK_REGISTRY = path.join(CONFIG_DIR, 'packs.json');
+
+function ensureDirs() {
+  fs.mkdirSync(PACKS_DIR, { recursive: true });
+  fs.mkdirSync(USER_SKILLS_DIR, { recursive: true });
+}
+
+function loadRegistry() {
+  if (!fs.existsSync(PACK_REGISTRY)) return {};
+  try { return JSON.parse(fs.readFileSync(PACK_REGISTRY, 'utf8')); }
+  catch { return {}; }
+}
+
+function saveRegistry(reg) {
+  fs.writeFileSync(PACK_REGISTRY, JSON.stringify(reg, null, 2));
+}
+
+function normalizeSource(source) {
+  // Accept "user/repo", "https://github.com/user/repo", "git@github.com:user/repo.git", or a local path
+  if (source.startsWith('http://') || source.startsWith('https://') || source.startsWith('git@')) {
+    return { type: 'git', url: source };
+  }
+  if (source.startsWith('./') || source.startsWith('/') || source.startsWith('~')) {
+    return { type: 'local', path: source.replace(/^~/, os.homedir()) };
+  }
+  // user/repo shorthand → github
+  if (/^[\w.-]+\/[\w.-]+$/.test(source)) {
+    return { type: 'git', url: `https://github.com/${source}` };
+  }
+  throw new Error(`Cannot interpret source: ${source}`);
+}
+
+function sourceKey(src) {
+  return crypto.createHash('sha1').update(JSON.stringify(src)).digest('hex').slice(0, 10);
+}
+
+function readManifest(packDir) {
+  const mf = path.join(packDir, 'skillforge.json');
+  if (!fs.existsSync(mf)) {
+    throw new Error(`No skillforge.json found at ${packDir}. A skill pack must have a manifest at its root.`);
+  }
+  const m = JSON.parse(fs.readFileSync(mf, 'utf8'));
+  if (!m.name || !Array.isArray(m.skills)) {
+    throw new Error('skillforge.json must have "name" (string) and "skills" (array of folder names)');
+  }
+  return m;
+}
+
+function validateSkills(packDir, manifest) {
+  const errors = [];
+  for (const s of manifest.skills) {
+    const skillPath = path.join(packDir, s);
+    if (!fs.existsSync(skillPath)) errors.push(`Listed skill "${s}" not found in pack`);
+    else if (!fs.existsSync(path.join(skillPath, 'SKILL.md'))) errors.push(`"${s}" has no SKILL.md`);
+  }
+  if (errors.length) throw new Error('Pack validation failed:\n  - ' + errors.join('\n  - '));
+}
+
+function linkSkills(packDir, manifest, packKey) {
+  const linked = [];
+  for (const s of manifest.skills) {
+    const target = path.join(USER_SKILLS_DIR, s);
+    if (fs.existsSync(target)) {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) {
+        // Existing pack symlink — overwrite (re-install case)
+        fs.unlinkSync(target);
+      } else {
+        throw new Error(`A skill folder named "${s}" already exists in user skills (not from a pack). Remove it first or rename your pack's skill.`);
+      }
+    }
+    fs.symlinkSync(path.join(packDir, s), target, 'dir');
+    linked.push(s);
+  }
+  return linked;
+}
+
+function unlinkSkills(skills) {
+  const removed = [];
+  for (const s of skills) {
+    const target = path.join(USER_SKILLS_DIR, s);
+    if (fs.existsSync(target)) {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) {
+        fs.unlinkSync(target);
+        removed.push(s);
+      }
+    }
+  }
+  return removed;
+}
+
+function installPack(source) {
+  ensureDirs();
+  const src = normalizeSource(source);
+  const key = sourceKey(src);
+  const packDir = path.join(PACKS_DIR, key);
+
+  if (src.type === 'git') {
+    if (fs.existsSync(packDir)) {
+      // Already cloned — update instead
+      const r = spawnSync('git', ['-C', packDir, 'pull', '--ff-only', '--quiet'], { stdio: 'inherit' });
+      if (r.status !== 0) throw new Error('git pull failed');
+    } else {
+      const r = spawnSync('git', ['clone', '--depth', '1', '--quiet', src.url, packDir], { stdio: 'inherit' });
+      if (r.status !== 0) throw new Error(`git clone failed for ${src.url}`);
+    }
+  } else {
+    // Local path — symlink the pack dir itself
+    if (fs.existsSync(packDir)) fs.rmSync(packDir, { recursive: true, force: true });
+    fs.symlinkSync(src.path, packDir, 'dir');
+  }
+
+  const manifest = readManifest(packDir);
+  validateSkills(packDir, manifest);
+  const linked = linkSkills(packDir, manifest, key);
+
+  const reg = loadRegistry();
+  reg[manifest.name] = {
+    source,
+    key,
+    version: manifest.version || 'unknown',
+    skills: linked,
+    installed_at: new Date().toISOString(),
+  };
+  saveRegistry(reg);
+  return { name: manifest.name, skills: linked, version: manifest.version };
+}
+
+function uninstallPack(name) {
+  ensureDirs();
+  const reg = loadRegistry();
+  const entry = reg[name];
+  if (!entry) throw new Error(`No installed pack named "${name}"`);
+  const removed = unlinkSkills(entry.skills);
+  const packDir = path.join(PACKS_DIR, entry.key);
+  if (fs.existsSync(packDir)) {
+    const stat = fs.lstatSync(packDir);
+    if (stat.isSymbolicLink()) fs.unlinkSync(packDir);
+    else fs.rmSync(packDir, { recursive: true, force: true });
+  }
+  delete reg[name];
+  saveRegistry(reg);
+  return { name, removed };
+}
+
+function listPacks() {
+  ensureDirs();
+  const reg = loadRegistry();
+  return Object.entries(reg).map(([name, e]) => ({ name, ...e }));
+}
+
+function updatePack(name) {
+  const reg = loadRegistry();
+  const entry = reg[name];
+  if (!entry) throw new Error(`No installed pack named "${name}"`);
+  return installPack(entry.source);  // re-runs git pull + relinks
+}
+
+module.exports = { installPack, uninstallPack, listPacks, updatePack };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@heytherevibin/skillforge",
+  "version": "0.2.1",
+  "description": "Skill orchestration for Claude: hybrid embedding and router-based routing, MCP and HTTP servers, per-user learning, and a large bundled SKILL.md catalog.",
+  "keywords": [
+    "claude",
+    "skills",
+    "agent",
+    "orchestrator",
+    "anthropic",
+    "llm",
+    "routing"
+  ],
+  "license": "MIT",
+  "bin": {
+    "skillforge": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "python/",
+    "skills/",
+    "README.md",
+    "CHANGELOG.md",
+    "STRATEGY.md",
+    "LICENSE",
+    "RELEASING.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  }
+}

package/python/app/auth.py

@@ -0,0 +1,63 @@
+"""
+Bearer-token auth and per-user namespacing.
+
+Single-user mode (default): no token required, all state goes to user_id=''.
+Multi-user mode: set SKILLFORGE_AUTH_TOKENS env var to a JSON map of
+{"token-value": "user-id"}. Requests must send Authorization: Bearer <token>.
+The resolved user_id is then used to scope sessions, weights, and events.
+
+This keeps the architecture single-process (one SQLite, one router instance)
+while letting each user have isolated learning state.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from fastapi import HTTPException, Request
+
+
+# ---- Token registry ----
+
+def _load_tokens() -> dict[str, str]:
+    """Read SKILLFORGE_AUTH_TOKENS env (JSON: {token: user_id})."""
+    raw = os.getenv("SKILLFORGE_AUTH_TOKENS", "").strip()
+    if not raw:
+        return {}
+    try:
+        m = json.loads(raw)
+        if not isinstance(m, dict):
+            print("[skillforge] SKILLFORGE_AUTH_TOKENS must be a JSON object")
+            return {}
+        return {str(k): str(v) for k, v in m.items()}
+    except json.JSONDecodeError:
+        print("[skillforge] SKILLFORGE_AUTH_TOKENS is not valid JSON, ignoring")
+        return {}
+
+
+_TOKENS = _load_tokens()
+_AUTH_REQUIRED = bool(_TOKENS)
+
+
+def auth_enabled() -> bool:
+    return _AUTH_REQUIRED
+
+
+def resolve_user(request: Request) -> str:
+    """Get user_id from a request.
+
+    - If auth is not configured (single-user mode): returns ''.
+    - If auth is configured: extracts bearer token, returns mapped user_id,
+      or raises 401.
+    """
+    if not _AUTH_REQUIRED:
+        return ""
+    header = request.headers.get("authorization", "")
+    if not header.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+    token = header[7:].strip()
+    user_id = _TOKENS.get(token)
+    if not user_id:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user_id

package/python/app/cli.py

@@ -0,0 +1,78 @@
+"""Dev harness: terminal client for POST /chat (requires `skillforge start` + API key)."""
+import argparse
+import json
+import sys
+import uuid
+
+import httpx
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--url", default="http://localhost:8000")
+    args = ap.parse_args()
+
+    session_id = str(uuid.uuid4())
+    conversation = []
+    print(f"\nskillforge chat — session {session_id[:8]}")
+    print("Commands: 'exit' to quit, 'reset' for new session\n")
+
+    while True:
+        try:
+            prompt = input("you ▸ ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not prompt:
+            continue
+        if prompt == "exit":
+            break
+        if prompt == "reset":
+            session_id = str(uuid.uuid4())
+            conversation = []
+            print(f"[new session: {session_id[:8]}]\n")
+            continue
+
+        full = []
+        picked = []
+        try:
+            with httpx.stream(
+                "POST",
+                f"{args.url}/chat",
+                json={"prompt": prompt, "session_id": session_id, "conversation": conversation},
+                timeout=120.0,
+            ) as r:
+                if r.status_code != 200:
+                    print(f"[error {r.status_code}] {r.read().decode()}")
+                    continue
+                print("claude ▸ ", end="", flush=True)
+                for line in r.iter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    try:
+                        data = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+                    if "delta" in data:
+                        sys.stdout.write(data["delta"])
+                        sys.stdout.flush()
+                        full.append(data["delta"])
+                    elif "done" in data:
+                        picked = data.get("picked", [])
+                    elif "error" in data:
+                        print(f"\n[stream error] {data['error']}")
+        except httpx.HTTPError as e:
+            print(f"\n[connection error] {e}")
+            print("Is the server running? Try: skillforge start")
+            continue
+
+        print()
+        if picked:
+            print(f"   \033[2m↳ skills used: {', '.join(picked)}\033[0m")
+        print()
+        conversation.append({"role": "user", "content": prompt})
+        conversation.append({"role": "assistant", "content": "".join(full)})
+
+
+if __name__ == "__main__":
+    main()

package/python/app/db_paths.py

@@ -0,0 +1,26 @@
+"""Orchestrator SQLite path resolution (stdlib only — safe for lightweight tests)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def global_db_path() -> Path:
+    return Path(
+        os.getenv("SKILLFORGE_DB_PATH", str(Path.home() / ".skillforge" / "data" / "orchestrator.db"))
+    )
+
+
+def resolve_orchestrator_db(project_root: str | None) -> Path:
+    """SQLite file: ``<project>/.skillforge/orchestrator.db`` when project_root is set, else global path.
+
+    If ``project_root`` is empty, falls back to env ``SKILLFORGE_PROJECT_ROOT``, then global.
+    """
+    pr = (project_root or "").strip()
+    if not pr:
+        pr = os.getenv("SKILLFORGE_PROJECT_ROOT", "").strip()
+    if pr:
+        root = Path(pr).expanduser().resolve()
+        return root / ".skillforge" / "orchestrator.db"
+    return global_db_path()

package/python/app/events_cli.py

@@ -0,0 +1,175 @@
+"""Print routing/events from Skillforge SQLite (terminal observability)."""
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from app.db_paths import resolve_orchestrator_db
+
+
+def _format_route_line(ts: float, sid: str | None, prev: dict, verbose: bool) -> str:
+    tstr = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ts))
+    picked = prev.get("picked")
+    sid12 = (sid or "-")[:12]
+    base = f"{tstr}  route  session={sid12:12}  picked={picked}"
+    ms = prev.get("route_ms")
+    if ms is not None:
+        base += f"  {ms}ms"
+    if prev.get("rerouted"):
+        base += "  reroute"
+    if verbose:
+        prompt = (prev.get("prompt") or "")[:120].replace("\n", " ")
+        reason = (prev.get("reasoning") or "")[:100].replace("\n", " ")
+        if prompt:
+            base += f'\n         prompt: {prompt}{"…" if len(str(prev.get("prompt") or "")) > 120 else ""}'
+        if reason:
+            base += f'\n         why: {reason}'
+    return base
+
+
+def _print_row(ts: float, sid: str | None, et: str | None, payload: str | None, verbose: bool) -> None:
+    prev = json.loads(payload) if payload else {}
+    if et == "route" and isinstance(prev, dict):
+        print(_format_route_line(ts, sid, prev, verbose))
+        return
+    extra = ""
+    if et == "feedback" and isinstance(prev, dict):
+        extra = f" skill={prev.get('skill')} thumbs={prev.get('thumbs')}"
+    tstr = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ts))
+    print(f"{tstr}  {et or '?'}  session={sid or '-':12}{extra}")
+
+
+def _print_snapshot(
+    con: sqlite3.Connection,
+    user_id: str,
+    recent_minutes: float,
+    *,
+    db_path: Path | None = None,
+) -> None:
+    """Usage totals + recently active sessions (routes), for live CLI."""
+    since = time.time() - recent_minutes * 60.0
+    cur = con.execute(
+        "SELECT skill_name, uses, referenced FROM skill_weights WHERE user_id = ? AND uses > 0 "
+        "ORDER BY uses DESC LIMIT 12",
+        (user_id,),
+    )
+    usage = cur.fetchall()
+    cur = con.execute(
+        """
+        SELECT session_id, MAX(ts) AS mt
+        FROM events
+        WHERE ts >= ? AND event_type = 'route' AND user_id = ?
+        GROUP BY session_id
+        ORDER BY mt DESC
+        LIMIT 15
+        """,
+        (since, user_id),
+    )
+    sessions = cur.fetchall()
+    line = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
+    print(f"── [{line}] skillforge live ──")
+    if db_path is not None:
+        print(f"  SQLite: {db_path}")
+    if usage:
+        ubits = [f"{n} uses={u} ref={r}" for n, u, r in usage]
+        print("  Top skills:", "; ".join(ubits))
+    else:
+        print("  Top skills: (no route stats yet for this user_id)")
+    if sessions:
+        short = [f"{(s or '-')[:10]}…" if s and len(s) > 10 else (s or "-") for s, _ in sessions]
+        print(f"  Active sessions (routes in last {int(recent_minutes)}m): {len(sessions)} —", ", ".join(short))
+    else:
+        print(f"  Active sessions: none in last {int(recent_minutes)}m")
+    print("── new events ──")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="Skillforge event log (SQLite). Use --watch for realtime usage + routes."
+    )
+    ap.add_argument("--limit", type=int, default=40)
+    ap.add_argument("--watch", action="store_true", help="Poll for new rows (default interval 2s)")
+    ap.add_argument("--poll", type=float, default=2.0, help="Seconds between polls in --watch mode")
+    ap.add_argument(
+        "--summary-every",
+        type=float,
+        default=15.0,
+        metavar="SEC",
+        help="In --watch mode, re-print usage snapshot every SEC seconds (0 = only at start)",
+    )
+    ap.add_argument(
+        "--recent-minutes",
+        type=float,
+        default=60.0,
+        help="Window for 'active sessions' in snapshots (default 60)",
+    )
+    ap.add_argument(
+        "--user",
+        default="",
+        help="Logical user id for stats/sessions (matches MCP SKILLFORGE_MCP_USER_ID / HTTP user). Default empty.",
+    )
+    ap.add_argument(
+        "--project-root",
+        default="",
+        help="Workspace root — reads <root>/.skillforge/orchestrator.db. Default: env SKILLFORGE_PROJECT_ROOT or global DB.",
+    )
+    ap.add_argument("-v", "--verbose", action="store_true", help="More detail on route lines")
+    args = ap.parse_args()
+
+    pr = (args.project_root or "").strip() or None
+    db_path = resolve_orchestrator_db(pr)
+
+    if not db_path.exists():
+        print("No database yet — run skillforge mcp or skillforge start first (or route once with this project_root).")
+        print(f"  Expected: {db_path}")
+        return
+
+    if args.watch:
+        con = sqlite3.connect(str(db_path))
+        row = con.execute("SELECT COALESCE(MAX(ts), 0) FROM events").fetchone()
+        con.close()
+        last_max = float(row[0]) if row else 0.0
+        summary_every = args.summary_every
+        next_summary = time.monotonic()
+        first = True
+        try:
+            while True:
+                now_m = time.monotonic()
+                if first or (summary_every > 0 and now_m >= next_summary):
+                    con = sqlite3.connect(str(db_path))
+                    _print_snapshot(con, args.user, args.recent_minutes, db_path=db_path)
+                    con.close()
+                    first = False
+                    next_summary = now_m + summary_every
+                con = sqlite3.connect(str(db_path))
+                cur = con.execute(
+                    "SELECT ts, session_id, event_type, payload FROM events WHERE ts > ? ORDER BY ts ASC",
+                    (last_max,),
+                )
+                rows = cur.fetchall()
+                con.close()
+                for ts, sid, et, pay in rows:
+                    _print_row(ts, sid, et, pay, args.verbose)
+                    last_max = max(last_max, float(ts))
+                time.sleep(max(0.5, args.poll))
+        except KeyboardInterrupt:
+            print()
+    else:
+        con = sqlite3.connect(str(db_path))
+        _print_snapshot(con, args.user, args.recent_minutes, db_path=db_path)
+        cur = con.execute(
+            "SELECT ts, session_id, event_type, payload FROM events ORDER BY ts DESC LIMIT ?",
+            (args.limit,),
+        )
+        rows = cur.fetchall()
+        con.close()
+        print("── recent events (newest first) ──")
+        for ts, sid, et, pay in rows:
+            _print_row(ts, sid, et, pay, args.verbose)
+
+
+if __name__ == "__main__":
+    main()