howzo 0.1.0__py3-none-any.whl

howzo/__init__.py

@@ -0,0 +1,7 @@
+"""howzo - knows your machine.
+
+Ask "how do I X" in English and get the tool that is actually installed on
+this machine, plus a usage hint. Stdlib only, zero models, fully local.
+"""
+
+__version__ = "0.1.0"

howzo/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m howzo` entry point."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

howzo/cli.py

@@ -0,0 +1,48 @@
+"""howzo command-line entry point."""
+import sys
+
+from . import commands
+from .config import db_path
+from .mcp import cmd_mcp
+
+USAGE = """howzo - knows your machine. Ask "how do I X" in English; get the installed tool + command.
+
+Commands:
+  howzo <query>          just type your question (same as ask)
+  howzo scan [--deep]    rebuild inventory (brew/npm/pipx/uv/scripts/system). --deep also captures --help
+  howzo ask "query"
+  howzo whatis <tool>
+  howzo deep <tool>      capture --help for one tool
+  howzo add <name> "desc"  register a tool the scanner can't see (internal CLIs, npx aliases)
+  howzo list [--source S]
+  howzo mcp              run as a stdio MCP server (exposes howzo_ask / howzo_whatis / howzo_list)
+  howzo db               show database path
+
+Stdlib only, zero models, fully local. Works on macOS, Linux, and Windows."""
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print(USAGE)
+        return 1
+    cmd, rest = args[0], args[1:]
+    if cmd == "scan":
+        return commands.cmd_scan(rest)
+    if cmd == "ask":
+        return commands.cmd_ask(rest)
+    if cmd == "whatis":
+        return commands.cmd_whatis(rest)
+    if cmd == "deep":
+        return commands.cmd_deep(rest)
+    if cmd == "add":
+        return commands.cmd_add(rest)
+    if cmd == "list" and (not rest or rest[0].startswith("-")):
+        return commands.cmd_list(rest)
+    if cmd == "mcp":
+        return cmd_mcp(rest)
+    if cmd == "db":
+        print(db_path())
+        return 0
+    # implicit ask: howzo <query> == howzo ask <query>
+    return commands.cmd_ask(args)

howzo/commands.py

@@ -0,0 +1,180 @@
+"""CLI command handlers (scan / ask / whatis / deep / add / list)."""
+import os
+import sqlite3
+import time
+
+from . import config
+from .db import db, upsert
+from .helptext import capture_help
+from .match import coverage, fts_query, find_by_name, has_word, query_tokens, rank_rows
+from .render import render_tool
+from .scan import scanners
+
+
+def cmd_scan(args):
+    c = db()
+    try:
+        # preserve on-demand captured help + enrichments across rescans
+        keep = {r["name"]: (r["help_excerpt"], r["help_captured_at"], r["when_to_use"])
+                for r in c.execute("SELECT name, help_excerpt, help_captured_at, when_to_use FROM tools")}
+        custom_rows = {r["name"]: (r["source"], r["version"], r["path"], r["oneliner"],
+                                   r["when_to_use"], r["help_excerpt"], r["help_captured_at"])
+                       for r in c.execute("SELECT * FROM tools WHERE source IN ('custom','npx')")}
+        c.execute("DELETE FROM tools")
+    except sqlite3.DatabaseError:
+        print("  warning: db corrupted, rebuilding")
+        d = config.db_dir()
+        for f in os.listdir(d):
+            if f.startswith("howzo.db"):
+                os.remove(os.path.join(d, f))
+        c = db()
+        keep, custom_rows = {}, {}
+    deep = "--deep" in args
+    t0 = time.time()
+    for fn in scanners():
+        fn(c)
+    # custom tools added via 'howzo add' must survive rescans
+    for name, (src, ver, path, one, w, h, h_at) in custom_rows.items():
+        c.execute("INSERT INTO tools(name, source, version, path, oneliner, when_to_use, help_excerpt, "
+                  "help_captured_at, scanned_at) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(name) DO NOTHING",
+                  (name, src, ver, path, one, w, h, h_at, time.strftime("%Y-%m-%d")))
+    for name, (h, h_at, w) in keep.items():
+        c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=?, when_to_use=? WHERE name=?",
+                  (h, h_at, w, name))
+    c.commit()
+    total = c.execute("SELECT COUNT(*) FROM tools").fetchone()[0]
+    print(f"  inventory: {total} tools in {time.time()-t0:.0f}s")
+    if deep:
+        print("  capturing --help (can take a few minutes)...")
+        rows = c.execute("SELECT id, name, path FROM tools").fetchall()
+        done = 0
+        for tid, name, path in rows:
+            h = capture_help(name, path)
+            if h:
+                c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=? WHERE id=?",
+                          (h, time.strftime("%Y-%m-%d"), tid))
+                done += 1
+        c.commit()
+        print(f"  help captured for {done}/{len(rows)} tools")
+    else:
+        print("  (tip: 'howzo scan --deep' also captures --help for richer answers;")
+        print("   'howzo deep <tool>' captures help for one tool on demand)")
+    return 0
+
+
+def cmd_ask(args):
+    q = " ".join(args).strip()
+    if not q:
+        print('usage: howzo ask "how do I ..."')
+        return 1
+    c = db()
+    row = find_by_name(c, q)
+    if row:
+        print(render_tool(row, q))
+        return 0
+    ftsq = fts_query(q)
+    toks = query_tokens(q)
+    rows = []
+    if ftsq:
+        try:
+            rows = c.execute(
+                "SELECT t.*, bm25(tools_fts) AS score FROM tools_fts f JOIN tools t ON t.id=f.rowid "
+                "WHERE tools_fts MATCH ? ORDER BY score LIMIT 12", (ftsq,)).fetchall()
+        except sqlite3.OperationalError:
+            rows = []
+    if not rows and toks:
+        # fallback: broad LIKE candidates per token, then word-boundary filter
+        cand = {}
+        for t in toks:
+            like = f"%{t}%"
+            for r in c.execute("SELECT * FROM tools WHERE lower(name) LIKE ? OR lower(oneliner) LIKE ? "
+                               "OR lower(when_to_use) LIKE ? OR lower(help_excerpt) LIKE ? LIMIT 60",
+                               (like, like, like, like)):
+                hay = " ".join(filter(None, [r["name"], r["oneliner"], r["when_to_use"], r["help_excerpt"]]))
+                if has_word(hay, t):
+                    cand[r["id"]] = r
+        rows = list(cand.values())
+    rows = rank_rows(rows, toks)
+    if not rows:
+        print(f"no match for: {q}\n  (try 'howzo scan --deep' to index --help text)")
+        return 1
+    for r in rows[:3]:
+        print(render_tool(r, q))
+        print()
+    best_cov = max(coverage(r, toks) for r in rows[:3])
+    if best_cov < len(toks):
+        print("  (partial match - no tool advertises all terms)")
+    return 0
+
+
+def cmd_whatis(args):
+    c = db()
+    for name in args:
+        row = find_by_name(c, name)
+        if not row:
+            print(f"unknown tool: {name}")
+            continue
+        t = {k: row[k] for k in row.keys()}
+        print(render_tool(t, " ".join(args)))
+        if t.get("help_excerpt"):
+            print("  help:")
+            for l in t["help_excerpt"].splitlines()[:12]:
+                print("   ", l)
+        print()
+    return 0
+
+
+def cmd_add(args):
+    if len(args) < 2:
+        print('usage: howzo add <name> "what it does"   (e.g. howzo add my-internal-tool \'syncs staging DB\')')
+        return 1
+    name = args[0]
+    desc = " ".join(args[1:])
+    c = db()
+    upsert(c, name, "custom", "", "", desc)
+    c.commit()
+    print(f"added: {name} (source=custom, survives rescans)")
+    return 0
+
+
+def cmd_deep(args):
+    if not args:
+        print("usage: howzo deep <tool>")
+        return 1
+    name = args[0]
+    c = db()
+    row = c.execute("SELECT * FROM tools WHERE lower(name)=?", (name.lower(),)).fetchone()
+    if not row:
+        print(f"not in inventory: {name} (run 'howzo scan')")
+        return 1
+    t = {k: row[k] for k in row.keys()}
+    print(f"capturing help for {name}...")
+    h = capture_help(name, t.get("path"))
+    if not h:
+        print("  no help captured (binary not found or silent --help)")
+        return 1
+    c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=? WHERE id=?",
+              (h, time.strftime("%Y-%m-%d"), t["id"]))
+    c.commit()
+    print(f"  ok ({len(h)} chars)")
+    return 0
+
+
+def cmd_list(args):
+    c = db()
+    src = None
+    if "--source" in args:
+        src = args[args.index("--source") + 1]
+    q = "SELECT * FROM tools"
+    params = ()
+    if src:
+        q += " WHERE source=?"
+        params = (src,)
+    q += " ORDER BY source, name"
+    rows = c.execute(q, params).fetchall()
+    print(f"{'TOOL':<28} {'SRC':<8} {'VER':<14} WHAT")
+    for r in rows:
+        t = {k: r[k] for k in r.keys()}
+        print(f"{t['name']:<28} {t['source']:<8} {str(t.get('version') or '')[:13]:<14} {t.get('oneliner','')[:70]}")
+    print(f"\n{len(rows)} tools")
+    return 0

howzo/config.py

@@ -0,0 +1,25 @@
+"""Platform constants and paths.
+
+The database location can be overridden with the HOWZO_DB environment
+variable (the test suite uses this to run against temp directories).
+"""
+import os
+
+IS_WINDOWS = os.name == "nt"
+HOME = os.path.expanduser("~")
+
+# Directories scanned for user scripts (see scan/scripts.py)
+SCAN_DIRS = [os.path.join(HOME, "bin"), os.path.join(HOME, ".local", "bin")]
+
+
+def db_dir():
+    override = os.environ.get("HOWZO_DB")
+    if override:
+        return override
+    if IS_WINDOWS:
+        return os.path.join(os.environ.get("LOCALAPPDATA") or HOME, "howzo")
+    return os.path.join(HOME, ".local", "share", "howzo")
+
+
+def db_path():
+    return os.path.join(db_dir(), "howzo.db")

howzo/db.py

@@ -0,0 +1,74 @@
+"""SQLite + FTS5 inventory store."""
+import os
+import sqlite3
+import time
+
+from . import config
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS tools (
+  id INTEGER PRIMARY KEY,
+  name TEXT UNIQUE NOT NULL,
+  source TEXT,
+  version TEXT,
+  path TEXT,
+  oneliner TEXT DEFAULT '',
+  when_to_use TEXT DEFAULT '',
+  help_excerpt TEXT DEFAULT '',
+  help_captured_at TEXT,
+  scanned_at TEXT
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS tools_fts USING fts5(
+  name, oneliner, when_to_use, help_excerpt, content='tools', content_rowid='id',
+  tokenize='porter unicode61'
+);
+CREATE TRIGGER IF NOT EXISTS tools_ai AFTER INSERT ON tools BEGIN
+  INSERT INTO tools_fts(rowid, name, oneliner, when_to_use, help_excerpt)
+  VALUES (new.id, new.name, new.oneliner, new.when_to_use, new.help_excerpt);
+END;
+CREATE TRIGGER IF NOT EXISTS tools_ad AFTER DELETE ON tools BEGIN
+  INSERT INTO tools_fts(tools_fts, rowid, name, oneliner, when_to_use, help_excerpt)
+  VALUES ('delete', old.id, old.name, old.oneliner, old.when_to_use, old.help_excerpt);
+END;
+CREATE TRIGGER IF NOT EXISTS tools_au AFTER UPDATE ON tools BEGIN
+  INSERT INTO tools_fts(tools_fts, rowid, name, oneliner, when_to_use, help_excerpt)
+  VALUES ('delete', old.id, old.name, old.oneliner, old.when_to_use, old.help_excerpt);
+  INSERT INTO tools_fts(rowid, name, oneliner, when_to_use, help_excerpt)
+  VALUES (new.id, new.name, new.oneliner, new.when_to_use, new.help_excerpt);
+END;
+"""
+
+
+def db(path=None):
+    """Open (creating if needed) the inventory DB at path (default: config.db_path())."""
+    p = path or config.db_path()
+    d = os.path.dirname(p) or "."
+    os.makedirs(d, exist_ok=True)
+    try:
+        c = sqlite3.connect(p)
+        c.row_factory = sqlite3.Row
+        c.executescript(SCHEMA)
+        c.execute("SELECT count(*) FROM tools")  # probe
+        return c
+    except sqlite3.DatabaseError:
+        # corrupted db (e.g. after a schema change) -> wipe and rebuild from a scan
+        print(f"  warning: db corrupted, rebuilding ({p})")
+        for f in os.listdir(d):
+            if f.startswith("howzo.db"):
+                os.remove(os.path.join(d, f))
+        c = sqlite3.connect(p)
+        c.row_factory = sqlite3.Row
+        c.executescript(SCHEMA)
+        return c
+
+
+def upsert(c, name, source, version, path, oneliner):
+    """Insert a tool row, or update version/path on conflict.
+
+    An empty new oneliner never clobbers an existing description.
+    """
+    c.execute("INSERT INTO tools(name, source, version, path, oneliner, scanned_at) VALUES(?,?,?,?,?,?) "
+              "ON CONFLICT(name) DO UPDATE SET source=excluded.source, version=excluded.version, "
+              "path=excluded.path, oneliner=CASE WHEN excluded.oneliner != '' THEN excluded.oneliner ELSE tools.oneliner END, "
+              "scanned_at=excluded.scanned_at",
+              (name, source, version, path, oneliner, time.strftime("%Y-%m-%d")))

howzo/helptext.py

@@ -0,0 +1,53 @@
+"""Human-readable text extraction: man pages and --help output."""
+import os
+import shutil
+import subprocess
+
+MAN_AVAILABLE = shutil.which("man") is not None
+
+
+def _parse_man(out):
+    """Pull (oneliner, excerpt) out of raw man-page text."""
+    if not out.strip():
+        return "", ""
+    lines = out.splitlines()
+    oneliner, excerpt = "", "\n".join(lines[:60])[:3500]
+    try:  # NAME section first line: "name - description"
+        i = next(j for j, l in enumerate(lines) if l.strip() == "NAME")
+        for l in lines[i+1:i+6]:
+            if l.strip() and "-" in l:
+                oneliner = l.split("-", 1)[1].strip()
+                break
+    except StopIteration:
+        pass
+    return oneliner, excerpt
+
+
+def man_oneliner(name):
+    """(oneliner, excerpt) from `man name`; ('', '') if man is missing/empty."""
+    if not MAN_AVAILABLE:
+        return "", ""
+    try:
+        p = subprocess.run(["man", name], capture_output=True, text=True,
+                           encoding="utf-8", errors="replace", timeout=8)
+        out = p.stdout or ""
+    except Exception:
+        return "", ""
+    return _parse_man(out)
+
+
+def capture_help(name, path=""):
+    """Run `tool --help` (then -h) and return the first 4000 chars, or None."""
+    p = path or shutil.which(name)
+    if not p or not os.path.exists(p):
+        return None
+    for flag in ("--help", "-h"):
+        try:
+            r = subprocess.run([p, flag], capture_output=True, text=True,
+                               encoding="utf-8", errors="replace", timeout=5)
+            out = (r.stdout or r.stderr).strip()
+            if len(out) > 60:
+                return out[:4000]
+        except Exception:
+            continue
+    return None

howzo/match.py

@@ -0,0 +1,59 @@
+"""Query tokenization and ranking.
+
+Match = FTS5 BM25 + a word-boundary token-coverage re-rank in Python,
+so 'kill' never matches 'skill' and 'port' never matches 'report'.
+"""
+import re
+
+STOP = {"a", "an", "and", "are", "as", "at", "can", "do", "does", "for", "from",
+        "get", "how", "i", "in", "into", "is", "it", "me", "my", "on", "of", "or", "that",
+        "the", "to", "up", "what", "whats", "which", "with", "you", "your", "show", "shows",
+        "showing", "across", "by", "per", "use", "using"}
+
+
+def query_tokens(q):
+    """Lowercase word tokens, stop words removed, de-duped, capped at 10."""
+    return list(dict.fromkeys(t for t in re.findall(r"[a-z0-9]+", q.lower())
+                              if len(t) > 1 and t not in STOP))[:10]
+
+
+def fts_query(q):
+    """FTS5 match expression (quoted OR of tokens), or None if nothing to search."""
+    toks = query_tokens(q)
+    if not toks:
+        return None
+    return " OR ".join('"%s"' % t for t in toks)
+
+
+def coverage(row, toks):
+    """How many distinct query tokens appear in this row (word-boundary match)."""
+    hay = " ".join(filter(None, [row["name"], row["oneliner"], row["when_to_use"],
+                                row["help_excerpt"]])).lower()
+    return sum(1 for t in toks if re.search(r"(?<![a-z0-9])" + re.escape(t), hay))
+
+
+def has_word(hay, tok):
+    return bool(re.search(r"(?<![a-z0-9])" + re.escape(tok), hay.lower()))
+
+
+def find_by_name(c, q):
+    """Exact (case-insensitive) or prefix name lookup."""
+    q = q.strip().lower()
+    if not q:
+        return None
+    row = c.execute("SELECT * FROM tools WHERE lower(name)=?", (q,)).fetchone()
+    if row:
+        return row
+    return c.execute("SELECT * FROM tools WHERE lower(name) LIKE ?", (q + "%",)).fetchone()
+
+
+def rank_rows(rows, toks):
+    """Re-rank candidates: BM25 + token-coverage bonus (docs matching more
+    distinct query terms win). Rows without a bm25 score still rank by coverage."""
+    def rank_key(r):
+        try:
+            s = r["score"]
+        except (IndexError, KeyError):
+            s = 0.0
+        return (-(2 * coverage(r, toks) + 0.01 * max(0, -s)), r["name"])
+    return sorted(rows, key=rank_key)

howzo/mcp.py

@@ -0,0 +1,79 @@
+"""MCP stdio server (newline-delimited JSON-RPC 2.0).
+
+Run `howzo mcp` to expose howzo_ask / howzo_whatis / howzo_list to MCP clients.
+"""
+import contextlib
+import io
+import json
+import sys
+
+from . import __version__
+from .commands import cmd_ask, cmd_list, cmd_whatis
+
+MCP_TOOLS = [
+    {"name": "howzo_ask",
+     "description": "Ask in English what you want to do (e.g. 'how do I rotate a pdf'). Returns the best-matching installed tool with usage hints.",
+     "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}},
+    {"name": "howzo_whatis",
+     "description": "Look up an installed tool by name and show what it does plus help.",
+     "inputSchema": {"type": "object", "properties": {"tool": {"type": "string"}}, "required": ["tool"]}},
+    {"name": "howzo_list",
+     "description": "List installed tools (name, source, one-liner), optionally filtered by source.",
+     "inputSchema": {"type": "object", "properties": {"source": {"type": "string"}}}},
+]
+
+
+def mcp_handle(msg):
+    m, params = msg.get("method"), msg.get("params", {}) or {}
+    mid = msg.get("id")
+
+    def reply(result):
+        return {"jsonrpc": "2.0", "id": mid, "result": result} if mid is not None else None
+
+    def error(code, message):
+        if mid is None:
+            return None
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+    if m == "initialize":
+        return reply({"protocolVersion": params.get("protocolVersion", "2024-11-05"),
+                      "capabilities": {"tools": {}},
+                      "serverInfo": {"name": "howzo", "version": __version__}})
+    if m == "notifications/initialized":
+        return None
+    if m == "ping":
+        return reply({})
+    if m == "tools/list":
+        return reply({"tools": MCP_TOOLS})
+    if m == "tools/call":
+        name, args = params.get("name"), params.get("arguments", {}) or {}
+        buf = io.StringIO()
+        try:
+            with contextlib.redirect_stdout(buf):
+                if name == "howzo_ask":
+                    cmd_ask([args.get("query", "")])
+                elif name == "howzo_whatis":
+                    cmd_whatis([args.get("tool", "")])
+                elif name == "howzo_list":
+                    cmd_list(["--source", args["source"]] if args.get("source") else [])
+                else:
+                    return reply({"content": [{"type": "text", "text": f"unknown tool {name}"}], "isError": True})
+        except Exception as e:
+            return reply({"content": [{"type": "text", "text": f"error: {e}"}], "isError": True})
+        return reply({"content": [{"type": "text", "text": buf.getvalue()}]})
+    return error(-32601, f"method not found: {m}")
+
+
+def cmd_mcp(args):
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except Exception:
+            continue
+        resp = mcp_handle(msg)
+        if resp:
+            print(json.dumps(resp), flush=True)
+    return 0

howzo/proc.py

@@ -0,0 +1,23 @@
+"""Subprocess helpers (cross-platform, failure-tolerant)."""
+import shutil
+import subprocess
+
+
+def which_cmd(name):
+    """Resolve a command to an executable path.
+
+    Needed so Windows .cmd/.bat shims (npm, pipx, ...) resolve correctly;
+    falls back to the bare name so a missing command fails softly in run().
+    """
+    return shutil.which(name) or name
+
+
+def run(cmd, timeout=30):
+    """Run cmd and return stdout. Never raises; returns '' on any failure."""
+    try:
+        r = subprocess.run([which_cmd(cmd[0])] + list(cmd[1:]),
+                           capture_output=True, text=True,
+                           encoding="utf-8", errors="replace", timeout=timeout)
+        return r.stdout or ""
+    except Exception:
+        return ""

howzo/render.py

@@ -0,0 +1,32 @@
+"""Formatting for terminal and MCP output."""
+import re
+import sqlite3
+
+
+def best_help_lines(help_text, q, n=3):
+    """The n help lines most relevant to query q (original order preserved)."""
+    toks = [t for t in re.findall(r"[a-z0-9]+", q.lower()) if len(t) > 2]
+    if not toks:
+        return []
+    lines = [l.strip() for l in help_text.splitlines() if l.strip()]
+    scored = []
+    for l in lines:
+        s = sum(l.lower().count(t) for t in toks[:5])
+        if s:
+            scored.append((s, l))
+    scored.sort(key=lambda x: -x[0])
+    top = [l for _, l in scored[:n * 2]][:n]
+    return top
+
+
+def render_tool(row, q=""):
+    t = {k: row[k] for k in row.keys()} if isinstance(row, sqlite3.Row) else dict(row)
+    out = [f"{t['name']}  ({t['source']}" + (f", {t['version']}" if t.get("version") else "") + ")"]
+    if t.get("oneliner"):
+        out.append(f"  {t['oneliner']}")
+    if t.get("when_to_use"):
+        out.append(f"  when: {t['when_to_use']}")
+    if t.get("help_excerpt") and q:
+        for l in best_help_lines(t["help_excerpt"], q):
+            out.append(f"  | {l[:110]}")
+    return "\n".join(out)

howzo/scan/__init__.py

@@ -0,0 +1,19 @@
+"""Inventory scanners: one module per tool source.
+
+`scanners()` returns the scanner callables appropriate for this platform,
+in the order they should run.
+"""
+from .. import config
+from .brew import scan_brew
+from .npm import scan_npm
+from .pipx import scan_pipx
+from .uv import scan_uv
+from .scripts import scan_scripts
+from .system import scan_system
+from .path import scan_path
+from .npx import scan_npx_history
+
+
+def scanners():
+    return [scan_brew, scan_npm, scan_pipx, scan_uv, scan_scripts,
+            scan_path if config.IS_WINDOWS else scan_system, scan_npx_history]

howzo/scan/brew.py

@@ -0,0 +1,37 @@
+"""Homebrew formulae (macOS and Linuxbrew)."""
+import json
+import shutil
+
+from ..db import upsert
+from ..proc import run
+
+
+def scan_brew(c):
+    if not shutil.which("brew"):
+        return
+    out = run(["brew", "list", "--versions"], timeout=60)
+    names = []
+    for line in out.splitlines():
+        parts = line.split()
+        if parts and parts[0] and not parts[0].startswith("("):
+            names.append(parts[0])
+    print(f"  brew: {len(names)} formulae, fetching descriptions...")
+
+    def ingest(out):
+        try:
+            data = json.loads(out)
+        except Exception:
+            return False
+        for f in data.get("formulae", []):
+            ver = (f.get("versions") or {}).get("version") or (f.get("versions") or {}).get("stable", "")
+            upsert(c, f["name"], "brew", str(ver), f.get("homepage", ""), f.get("description", ""))
+        return True
+
+    for i in range(0, len(names), 40):
+        chunk = names[i:i+40]
+        if not ingest(run(["brew", "info", "--json=v2", *chunk], timeout=120)):
+            # chunk poisoned (e.g. untrusted tap) -> per-name, tolerate failures
+            for n in chunk:
+                if "/" in n:
+                    continue
+                ingest(run(["brew", "info", "--json=v2", n], timeout=30))

howzo/scan/common.py

@@ -0,0 +1,48 @@
+"""Helpers shared by the scanners."""
+import json
+import os
+import re
+import urllib.request
+
+from .. import config
+from ..proc import run
+
+
+def npm_prefix():
+    return run(["npm", "prefix", "-g"]).strip() or os.path.join(config.HOME, ".npm-global")
+
+
+def pypi_oneliner(name):
+    """Short description of a PyPI package ('' on any failure)."""
+    try:
+        with urllib.request.urlopen(f"https://pypi.org/pypi/{name}/json", timeout=8) as r:
+            info = json.loads(r.read().decode())
+            return (info.get("info", {}).get("summary") or "").strip()
+    except Exception:
+        return ""
+
+
+def header_oneliner(path):
+    """First meaningful comment line of a script (a natural one-liner)."""
+    try:
+        with open(path, "r", errors="ignore") as fh:
+            for i, line in enumerate(fh):
+                if i > 30:
+                    break
+                s = line.strip()
+                if s.startswith("#!") or s in ("#", ""):
+                    continue
+                m = re.match(r"^#\s*(.{12,160})$", s)
+                if m:
+                    return m.group(1)
+    except Exception:
+        pass
+    return ""
+
+
+def is_text_file(path):
+    try:
+        with open(path, "rb") as fh:
+            return fh.read(2) == b"#!"
+    except Exception:
+        return False

howzo/scan/npm.py

@@ -0,0 +1,29 @@
+"""Global npm packages (plus the binaries they install)."""
+import json
+import os
+import shutil
+
+from ..db import upsert
+from ..proc import run
+from .common import npm_prefix
+
+
+def scan_npm(c):
+    if not shutil.which("npm"):
+        return
+    out = run(["npm", "ls", "-g", "--depth=0", "--json"], timeout=60)
+    try:
+        deps = json.loads(out).get("dependencies", {})
+    except Exception:
+        return
+    print(f"  npm: {len(deps)} global packages")
+    for name, info in deps.items():
+        desc = run(["npm", "view", name, "description"], timeout=15).strip()
+        upsert(c, name, "npm", info.get("version", ""), "", desc)
+    # binaries npm installs (link name != package name, e.g. pi)
+    bindir = os.path.join(npm_prefix(), "bin")
+    if os.path.isdir(bindir):
+        for entry in os.listdir(bindir):
+            if entry in deps:
+                continue
+            upsert(c, entry, "npm", "", os.path.join(bindir, entry), "(npm global binary)")

howzo/scan/npx.py

@@ -0,0 +1,44 @@
+"""On-demand npx/bunx/dlx packages mined from shell history."""
+import os
+import re
+
+from .. import config
+from ..db import upsert
+from ..proc import run
+
+NPX_RE = re.compile(r"\b(npx|bunx|pnpm dlx)\s+(@?[a-z0-9][a-z0-9-]*(?:/@[a-z0-9-]+)?)(?:@[a-z0-9.]+)?")
+
+
+def history_files():
+    cands = [os.path.join(config.HOME, ".zsh_history"),
+             os.path.join(config.HOME, ".bash_history")]
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        cands.append(os.path.join(appdata, "Microsoft", "Windows", "PowerShell",
+                                  "PSReadLine", "ConsoleHost_history.txt"))
+    return [h for h in cands if os.path.exists(h)]
+
+
+def scan_npx_history(c):
+    """Index npx/bunx/dlx packages actually used (from shell history)."""
+    hist = next(iter(history_files()), None)
+    if not hist:
+        return
+    pkgs = set()
+    try:
+        with open(hist, errors="ignore") as fh:
+            for line in fh:
+                for m in NPX_RE.finditer(line):
+                    pkgs.add(m.group(2))
+    except Exception:
+        return
+    known = {r["name"] for r in c.execute("SELECT name FROM tools")}
+    n = 0
+    for pkg in sorted(pkgs):
+        base = pkg.split("/")[-1]
+        if base in known:
+            continue  # already covered by a real install
+        desc = run(["npm", "view", pkg, "description"], timeout=15).strip()
+        upsert(c, base, "npx", "", f"npx {pkg}", desc or f"(npx {pkg} - used from shell history)")
+        n += 1
+    print(f"  npx history: {n} on-demand packages (from {os.path.basename(hist)})")

howzo/scan/path.py

@@ -0,0 +1,28 @@
+"""Windows: executables found on PATH (System32, Program Files, node, cargo, ...)."""
+import os
+
+from ..db import upsert
+
+WINDOWS_EXTS = (".exe", ".cmd", ".bat", ".ps1")
+
+
+def scan_path(c):
+    path_env = os.environ.get("Path") or os.environ.get("PATH") or ""
+    names, seen = [], set()
+    for d in path_env.split(os.pathsep):
+        if not d:
+            continue
+        # npm's global bin dir is already covered with versions/descriptions by scan_npm
+        if os.path.basename(d.rstrip("\\/")).lower() == "npm":
+            continue
+        try:
+            entries = os.listdir(d)
+        except OSError:
+            continue
+        for e in entries:
+            if e.lower().endswith(WINDOWS_EXTS) and e not in seen:
+                seen.add(e)
+                names.append((e, os.path.join(d, e)))
+    print(f"  path: {len(names)} executables")
+    for name, p in names:
+        upsert(c, name, "path", "", p, "")

howzo/scan/pipx.py

@@ -0,0 +1,31 @@
+"""Tools installed via pipx (plus the binaries they provide)."""
+import json
+import os
+import shutil
+
+from ..db import upsert
+from ..proc import run
+from .common import pypi_oneliner
+
+
+def scan_pipx(c):
+    if not shutil.which("pipx"):
+        return
+    out = run(["pipx", "list", "--json"], timeout=30)
+    try:
+        data = json.loads(out)
+    except Exception:
+        return
+    n = 0
+    for venv, v in (data.get("venvs") or {}).items():
+        main = (v.get("metadata") or {}).get("main_package") or {}
+        name = main.get("package") or venv
+        ver = main.get("package_version", "")
+        upsert(c, name, "pipx", ver, "", pypi_oneliner(name) or f"(pipx) {name}")
+        # also index the binaries this package provides (crwl -> crawl4ai)
+        for ap in main.get("app_paths") or []:
+            base = os.path.basename(ap.get("__Path__", "")) if isinstance(ap, dict) else os.path.basename(str(ap))
+            if base and base != name:
+                upsert(c, base, "pipx", ver, ap.get("__Path__", ""), f"(binary of pipx {name})")
+        n += 1
+    print(f"  pipx: {n} packages")

howzo/scan/scripts.py

@@ -0,0 +1,41 @@
+"""User scripts in ~/bin and ~/.local/bin."""
+import os
+
+from .. import config
+from ..db import upsert
+from .common import header_oneliner, is_text_file, npm_prefix
+
+
+def scan_scripts(c):
+    npm_root = npm_prefix()
+    pipx_root = os.path.join(config.HOME, ".local", "pipx", "venvs")
+    n = 0
+    seen = set()
+    for d in config.SCAN_DIRS:
+        if not os.path.isdir(d):
+            continue
+        for entry in sorted(os.listdir(d)):
+            p = os.path.join(d, entry)
+            if entry.endswith((".bak",)) or ".bak-" in entry:
+                continue
+            if os.path.islink(p):
+                tgt = os.path.realpath(p)
+                # skip links whose target is already covered by another source
+                if tgt.startswith(pipx_root) or tgt.startswith(npm_root):
+                    continue
+                src = "local"
+                oneliner = header_oneliner(tgt) if is_text_file(tgt) else ""
+                path = tgt
+            elif os.path.isfile(p) and os.access(p, os.X_OK):
+                if is_text_file(p):
+                    src, oneliner, path = "script", header_oneliner(p), p
+                else:
+                    src, oneliner, path = "local", "", p
+            else:
+                continue
+            if path in seen:
+                continue
+            seen.add(path)
+            upsert(c, entry, src, "", path, oneliner)
+            n += 1
+    print(f"  scripts/local: {n} from {', '.join(os.path.basename(x) for x in config.SCAN_DIRS)}")

howzo/scan/system.py

@@ -0,0 +1,30 @@
+"""System binaries on Unix (/usr/bin, /usr/sbin, /usr/local/bin) via man pages."""
+import os
+import time
+
+from ..db import upsert
+from ..helptext import man_oneliner
+
+SYSTEM_DIRS = ("/usr/bin", "/usr/sbin", "/usr/local/bin")
+
+
+def scan_system(c):
+    names, seen = [], set()
+    for d in SYSTEM_DIRS:
+        if not os.path.isdir(d):
+            continue
+        for n in os.listdir(d):
+            if n not in seen:
+                seen.add(n)
+                names.append(n)
+    print(f"  system: {len(names)} binaries, fetching man pages (slow part)...")
+    n = 0
+    for name in names:
+        oneliner, excerpt = man_oneliner(name)
+        if oneliner or excerpt:
+            upsert(c, name, "system", "", f"/usr/bin/{name}", oneliner)
+            if excerpt:
+                c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=? WHERE name=? AND (help_excerpt='' OR source='system')",
+                          (excerpt, time.strftime("%Y-%m-%d"), name))
+            n += 1
+    print(f"  system: {n} indexed with man text")

howzo/scan/uv.py

@@ -0,0 +1,21 @@
+"""Tools installed via `uv tool`."""
+import re
+import shutil
+
+from ..db import upsert
+from ..proc import run
+from .common import pypi_oneliner
+
+
+def scan_uv(c):
+    if not shutil.which("uv"):
+        return
+    out = run(["uv", "tool", "list"], timeout=30)
+    n = 0
+    for line in out.splitlines():
+        m = re.match(r"^(\S+) v?(\S+)\s*$", line.strip())
+        if m and not line.strip().startswith("-"):
+            name = m.group(1)
+            upsert(c, name, "uv", m.group(2), "", pypi_oneliner(name) or f"(uv) {name}")
+            n += 1
+    print(f"  uv: {n} tools")

howzo-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: howzo
+Version: 0.1.0
+Summary: Knows your machine: ask 'how do I X' in English, get the installed tool + a runnable command.
+Author: Sohail
+License: MIT
+Project-URL: Homepage, https://github.com/sohailchd/howzo
+Project-URL: Repository, https://github.com/sohailchd/howzo
+Keywords: cli,shell,commands,developer-tools,discovery,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# howzo
+
+**Knows your machine.** Ask "how do I X" in English → get the tool that is actually installed on *this* machine, plus a runnable command.
+
+howzo is a free, local, **zero-model** command router. It indexes the tools that are actually installed on your box — brew, npm, pipx, uv, system binaries, your own scripts — and answers plain-English questions by matching against that inventory. No accounts, no API keys, no telemetry, and no network access when answering.
+
+## Why
+
+Generic command helpers (ShellGPT, mang.sh, Atuin) index a static corpus of popular commands. howzo indexes *your machine* instead — the exact tools, versions, and help text you actually have. If it's installed, howzo knows it; if it isn't, howzo doesn't waste your time suggesting it.
+
+## Install
+
+Requires Python 3.9+. Runtime dependencies: **none** (stdlib only).
+
+### macOS / Linux
+
+```sh
+pipx install howzo        # or: uv tool install howzo
+```
+
+macOS also has a Homebrew formula (tap required):
+
+```sh
+brew tap sohailchd/howzo && brew install howzo
+```
+
+### Windows
+
+```powershell
+py -m pipx install howzo  # or: uv tool install howzo
+```
+
+### From source
+
+```sh
+git clone https://github.com/sohailchd/howzo.git
+pipx install --editable howzo    # or: uv tool install --editable howzo
+```
+
+### First run
+
+```sh
+howzo scan     # one-time: build your machine's inventory (~2-3 min)
+```
+
+Rescans are safe: captured help text, `when_to_use` notes, custom entries, and mined npx packages are preserved.
+
+## Usage
+
+```console
+$ howzo "how do I rotate a pdf"
+pdfq  (pipx, 1.0)
+  rotate and convert pdf files
+
+$ howzo whatis crwl
+crwl  (pipx, 0.3.1)
+  (binary of pipx crawl4ai)
+
+$ howzo kill a process on port 8080
+lsof  (brew, 9.9)
+  list open files and network connections
+```
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `howzo <query>` | Ask in plain English (implicit `ask`) |
+| `howzo scan [--deep]` | Rebuild inventory; `--deep` also captures `--help` text for every tool |
+| `howzo ask "query"` | Same as `<query>` |
+| `howzo whatis <tool>` | Reverse lookup: what is this tool for? |
+| `howzo deep <tool>` | Capture `--help`/man for one tool on demand |
+| `howzo add <name> "desc"` | Register a tool the scanner can't see (internal CLIs, aliases) |
+| `howzo list [--source S]` | Browse the inventory |
+| `howzo mcp` | Run as a stdio MCP server |
+| `howzo db` | Show the database path |
+
+## What it indexes
+
+| Source | What's indexed |
+|---|---|
+| brew | formulae + versions + descriptions (`brew info`) |
+| npm | global packages + their installed binaries |
+| pipx | packages + the binaries they provide (e.g. `crwl` → crawl4ai) |
+| uv | `uv tool` installs |
+| scripts | executables in `~/bin` and `~/.local/bin` (one-liner from the script header) |
+| system (Unix) | `/usr/bin` + `/usr/sbin` + `/usr/local/bin` binaries, described via man pages |
+| path (Windows) | executables found on `PATH` (System32, Program Files, …) |
+| npx | `npx`/`bunx`/`pnpm dlx` packages mined from your shell history (zsh, bash, PowerShell) |
+| custom | anything you add with `howzo add` |
+
+A typical machine indexes ~1,200 tools.
+
+## How it works
+
+- **SQLite + FTS5** at `~/.local/share/howzo/howzo.db` (Windows: `%LOCALAPPDATA%\howzo`), one row per tool: name, source, version, oneliner, when-to-use, help excerpt.
+- **Match = BM25 + word-boundary token-coverage re-rank** in Python. No models, no embeddings — `kill` never matches `skill`, `port` never matches `report`.
+- **~20–30 MB RAM**, and answering is fully offline. The network is only touched while scanning, to fetch package descriptions from npm/PyPI.
+- Set `HOWZO_DB=/some/dir` to relocate the database (also how the test suite isolates itself).
+
+## MCP
+
+howzo runs as a stdio MCP server exposing `howzo_ask`, `howzo_whatis`, and `howzo_list`:
+
+```json
+{
+  "mcpServers": {
+    "howzo": { "command": "howzo", "args": ["mcp"] }
+  }
+}
+```
+
+## Development
+
+```sh
+git clone https://github.com/sohailchd/howzo.git && cd howzo
+uv venv .venv
+VIRTUAL_ENV=$PWD/.venv uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"
+pytest
+```
+
+Layout:
+
+```
+src/howzo/
+├── cli.py        # entry point + dispatch
+├── commands.py   # scan / ask / whatis / deep / add / list
+├── config.py     # platform constants, DB path (HOWZO_DB override)
+├── proc.py       # subprocess helpers (cross-platform)
+├── db.py         # SQLite + FTS5 schema, upsert
+├── match.py      # tokenization, FTS query, BM25 + coverage re-rank
+├── render.py     # output formatting
+├── helptext.py   # man pages, --help capture
+├── mcp.py        # MCP stdio server
+└── scan/         # one module per source: brew, npm, pipx, uv, scripts, system, path, npx
+tests/            # pytest suite (runs against temp DBs, no network)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

howzo-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+howzo/__init__.py,sha256=wbsofBIcJjnWA8K6sYTyBLG59qWkqkpoam5mhzrd7Xc,206
+howzo/__main__.py,sha256=PsemdtR6zysUlFr8MlCP9JGUQM2KmNrAevv_w8KqVc8,125
+howzo/cli.py,sha256=1Fh8iPDf5oDY2ddjy7dx2VWfFyXjQ9rPl_1NETvyP8s,1623
+howzo/commands.py,sha256=1Ni008S3A4ELMKratG2aVmZ_moHUV1D_4TfLkPJL4Zk,6633
+howzo/config.py,sha256=_x7fjnP1zAJhH2GCpM7eiKjp1qfm3szfaHuNotn54Po,703
+howzo/db.py,sha256=H_M2UfoxJRSbzg8k6BmRU4JefcRFmr_ZyH3a-xkQemw,2883
+howzo/helptext.py,sha256=CAj3g5aff3IOvv0crQ7T5KG9zol3m1AZXVYDjlg8wcE,1716
+howzo/match.py,sha256=ZVetkTRxdIeJvbJfjH9Sil1aRgsB9s5CgPnB28ZAQdA,2181
+howzo/mcp.py,sha256=jW9yIwuwEFsUURGIEO-U1-aj3EGbw08VEHg3JQizbYA,3062
+howzo/proc.py,sha256=TGlbwVybanndabwp6CinngBo9C6YFzaCWRj6KTqYoaM,749
+howzo/render.py,sha256=jl9RXnI527So8DL3ZbUI0QexE3wH6gwHjradqDgzrqE,1129
+howzo/scan/__init__.py,sha256=cUn0A2COGbxx00I0_1UMXlhGHgyHtZa4BwOcvwSILYY,580
+howzo/scan/brew.py,sha256=DXJXiHWbQ0Hznq_2qEKtNKmJth6nyiB77pNEK2CqfcU,1275
+howzo/scan/common.py,sha256=dFHw1t_I92y_Jd1UWlHN6ceCfZIS6x5gDxe0jT6d__k,1301
+howzo/scan/npm.py,sha256=AKOZwpc5J3nWFb-aFqpAgWZ07q11O7bn8mEIGDQWVOg,970
+howzo/scan/npx.py,sha256=XadO1t0zxjSzwjk6QNP_AYS1Bse3xnnyVpZQlN3HMUY,1565
+howzo/scan/path.py,sha256=S6ssJbzaigVC3XhaYUQ84TII_x02xOnq20aZwbrzfuI,926
+howzo/scan/pipx.py,sha256=yoFKgkL78hkGo44_6fNR61uEV3SUmgKBU4Z6-MKZe44,1106
+howzo/scan/scripts.py,sha256=25FjfFCm7sXYAqS-e6vEAx8dMUNwMFlsj3K5RrqE1dQ,1506
+howzo/scan/system.py,sha256=FK-KAB6X3DknNPdUjDC87Rz4LGvPaD50uD9G1nFUfHY,1040
+howzo/scan/uv.py,sha256=3q2sAnS4IpdOwYFTRlgSQAjHon0B2amUojJC99ozTTI,578
+howzo-0.1.0.dist-info/licenses/LICENSE,sha256=Id6vY80adeWmZFCXGn0ev8-BqTe-1TEKXB7fZcE83uM,1063
+howzo-0.1.0.dist-info/METADATA,sha256=_sui4wRbdftkvss-jl5TJyb0b7oQ-3pyu-R91_NueCs,5717
+howzo-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+howzo-0.1.0.dist-info/entry_points.txt,sha256=bEfbcSm5jzqqufz0Uzv9Z7RUSzyJzv5nU6DbyXjD4sE,41
+howzo-0.1.0.dist-info/top_level.txt,sha256=3JxTqIhWpy1U8TyDoKn03VN5HtqSY1W7SOCeRNal8aw,6
+howzo-0.1.0.dist-info/RECORD,,

howzo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

howzo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+howzo = howzo.cli:main

howzo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

howzo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+howzo