feat(sec): initial release v1.0.0-alpha - ergonomic query routing engine

This commit is contained in:
2026-10-03 03:44:04 +03:00
commit db0997f934
24 changed files with 905 additions and 0 deletions
+28
View File
@@ -0,0 +1,28 @@
# SEC - Quick CLI Cheat Sheet & Code Snippet Assistant
## Project Purpose
A lightweight, lightning-fast CLI cheat sheet and code snippet assistant powered by the `cheat.sh` engine, ergonomic sol-el keyboard layout, smart query routing, and optional clipboard integration.
---
## Architectural Decisions
1. **Name & Ergonomics:** `sec` (optimized for left-hand QWERTY reachability in dropdown/Quake terminals).
2. **Backend & Engine:** Direct live queries to the `cheat.sh` API with smart multi-token routing.
3. **Smart Query Router:**
- Strategy 1: Targeted language/tool lookup (`cht.sh/<target>/<query>`).
- Strategy 2: Global semantic fallback search (`cht.sh/~<query>`).
4. **Offline Exact-Query Cache:** Lightweight SQLite or file-based cache for previously fetched queries so repeated lookups work offline.
5. **Clipboard Integration:** Optional `-c` / `--copy` flag to automatically extract and copy executable code blocks to the clipboard.
6. **Centralized UI/String Catalog:** Centralized JSON string catalog (`catalog/strings.json`). No hardcoded UI strings in code.
7. **Code Standards:** Professional English in all code, comments, catalogs, and documentation. No emojis in terminal UI or codebase.
8. **Manifest & Versioning:** `manifest.json` tracking semver, dependencies, and changelog, wired to `-V` / `--version`.
---
## Pending Topics & Decisions
- [x] **1. Live API Client & Multi-token Routing:** Tilde-based search, candidates fallback chain, error/index suppression.
- [x] **2. Clipboard Dual Mode:** `-c` for executable code only, `-c a` for full response.
- [x] **3. Offline SQLite Cache:** Automatic caching of valid queries in `data/cache.db`.
- [ ] **4. Deterministic Non-AI Keyword & Intent Engine:** Build a purely offline, algorithmic keyword classifier (trie/inverted-index/alias table) that parses freeform user prompts into exact `cheat.sh` canonical topics and flags without external AI APIs.
- [ ] **5. ANSI Rendering & Paging:** Optional terminal paging for multi-page cheat sheets.
- [ ] **6. Cache Expiration & Invalidation:** TTL or explicit cache refresh flags (`--refresh`).
+58
View File
@@ -0,0 +1,58 @@
# SEC - Structured Ergonomic Cheatsheet & Code Assistant
```text
____ _____ ____
/ ___|| ____/ ___|
\___ \| _|| |
___) | |__| |___
|____/|_____\____|
```
> **Author:** Simon the Coder `<simon@luxhebros.com>`
> **Specification Version:** 1.0.0-alpha
> **Runtime Environment:** Python 3.10+ / Gravitiny Applet Platform
> **License:** MIT Open Source License
---
## 1. Abstract & Motivation
Developers in drop-down/modal terminal environments frequently execute queries under tight spatial and temporal constraints. `sec` is designed to minimize motor latency by constraining command naming to the left-hand QWERTY region (`s`, `e`, `c`) while providing deterministic query routing and semantic AST-style snippet extraction.
---
## 2. Mathematical & Heuristic Routing Architecture
The `QueryRouter` class decomposes freeform CLI tokens $T = \{t_1, t_2, \dots, t_n\}$ through prioritized candidate generation:
1. **Programming Language Scoping:** Maps $t_1 \in \mathcal{L}$ to canonical StackOverflow question endpoints.
2. **Deterministic Synonym Permutation:** Dynamically expands programmatic verbs ($\text{serialize} \to \{\text{dump}, \text{dumps}, \text{write}, \text{stringify}\}$).
3. **Dual-Mode Clipboard Pipeline:**
- `-c` (Code Extraction): Strips commentary and markdown headers, isolating executable syntax trees.
- `-c a` (Full Context): Captures complete documentation cards.
---
## 3. Invocation Examples
```bash
# Language-scoped snippet retrieval
sec python json serialize -c
# System utility lookup
sec tar extract
# Diagnostic query
sec linux memory usage
# Full context clipboard copy
sec docker container prune -c a
```
---
## 4. Technical Invariants
- **Asynchronous & Offline Fallback:** Persistent SQLite response cache (`data/cache.db`).
- **Zero ANSI Pollution:** Strict stream sanitization on pipeline redirection.
- **Pure Dependency Decoupling:** Fully compliant with Gravitiny specification v0.1.0.
+16
View File
@@ -0,0 +1,16 @@
import sys
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent
if str(BASE_DIR) not in sys.path:
sys.path.insert(0, str(BASE_DIR))
if str(BASE_DIR.parent) not in sys.path:
sys.path.insert(0, str(BASE_DIR.parent))
try:
from sec.src.cli import run_cli
except ImportError:
from src.cli import run_cli
if __name__ == "__main__":
sys.exit(run_cli(sys.argv[1:]))
+23
View File
@@ -0,0 +1,23 @@
{
"app": {
"name": "SEC",
"description": "CLI Cheat Sheet & Code Snippet Assistant",
"version": "1.0.0",
"version_output": "{name} v{version} [{stage}] - {description}"
},
"status": {
"fetching": "Querying cheat sheet for: \"{query}\"...",
"not_found": "No cheat sheet found for: \"{query}\".",
"offline_cached": "[Cached Result - Offline Mode]",
"copied_code": "Copied executable code to clipboard.",
"copied_all": "Copied full response to clipboard.",
"clipboard_error": "Unable to copy to clipboard.",
"network_error": "Unable to connect to cheat.sh. Please check your internet connection."
},
"labels": {
"usage_title": "Usage:",
"examples_title": "Examples:",
"query_header": "CHEAT SHEET: {title}",
"source_badge": "cheat.sh"
}
}
BIN
View File
Binary file not shown.
+16
View File
@@ -0,0 +1,16 @@
import sys
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent
if str(BASE_DIR) not in sys.path:
sys.path.insert(0, str(BASE_DIR))
if str(BASE_DIR.parent) not in sys.path:
sys.path.insert(0, str(BASE_DIR.parent))
try:
from sec.src.cli import run_cli
except ImportError:
from src.cli import run_cli
if __name__ == "__main__":
sys.exit(run_cli(sys.argv[1:]))
+35
View File
@@ -0,0 +1,35 @@
{
"id": "sec",
"name": "Sec",
"display_name": "SEC - Ergonomic CLI Cheat Sheet & Code Snippet Assistant",
"description": "Ergonomic, heuristic-routed CLI cheat sheet and code snippet assistant powered by cheat.sh.",
"version": "1.0.0",
"stage": "Alpha",
"author": "Simon the Coder <simon@luxhebros.com>",
"license": "MIT",
"runtime": "python",
"entrypoint": "main.py",
"shims": ["sec"],
"network": "live",
"dependencies": [
"requests>=2.28.0",
"rich>=13.0.0"
],
"tags": [
"cheatsheet",
"snippets",
"cheat.sh",
"routing",
"clipboard",
"productivity",
"python",
"bash"
],
"features": [
"Ergonomic left-hand QWERTY command invocation (optimized for dropdown terminals)",
"Deterministic multi-token candidate URL permutation and developer synonym expansion",
"Dual-mode native Win32/POSIX clipboard integration (-c for code only, -c a for full snippet)",
"Offline query caching in local SQLite database",
"Centralized JSON UI and interaction catalog"
]
}
+40
View File
@@ -0,0 +1,40 @@
class Student(object):
name = ""
age = 0
major = ""
# The class "constructor" - It's actually an initializer
def __init__(self, name, age, major):
self.name = name
self.age = age
self.major = major
def make_student(name, age, major):
student = Student(name, age, major)
return student
# Note that even though one of the principles in Python's philosophy is
# *"there should be one—and preferably only one—obvious way to do it"*,
# there are still multiple ways to do this. You can also use the two
# following snippets of code to take advantage of Python's dynamic
# capabilities:
class Student(object):
name = ""
age = 0
major = ""
def make_student(name, age, major):
student = Student()
student.name = name
student.age = age
student.major = major
# Note: I didn't need to create a variable in the class definition before doing
this.
student.gpa = float(4.0)
return student
# I prefer the former, but there are instances where the latter can be
# useful – one being when working with document databases like MongoDB.
#
# [Wulfram] [so/q/15081542] [cc by-sa 3.0]
+1
View File
@@ -0,0 +1 @@
"""SEC - Quick CLI Cheat Sheet & Code Snippet Assistant."""
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+47
View File
@@ -0,0 +1,47 @@
import json
import os
from typing import Any, Dict
class StringCatalog:
"""Centralized catalog for user-facing strings and message templates."""
_instance = None
_catalog: Dict[str, Any] = {}
def __new__(cls):
if cls._instance is None:
cls._instance = super(StringCatalog, cls).__new__(cls)
cls._instance._load_catalog()
return cls._instance
def _load_catalog(self) -> None:
base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
catalog_path = os.path.join(base_dir, "catalog", "strings.json")
if os.path.exists(catalog_path):
with open(catalog_path, "r", encoding="utf-8") as f:
self._catalog = json.load(f)
else:
self._catalog = {}
def get(self, key_path: str, default: str = "") -> str:
"""Retrieve a string from the catalog using dot notation."""
parts = key_path.split(".")
current = self._catalog
for part in parts:
if isinstance(current, dict) and part in current:
current = current[part]
else:
return default
return str(current) if current is not None else default
def format(self, key_path: str, **kwargs: Any) -> str:
"""Retrieve a template string and interpolate keyword arguments."""
template = self.get(key_path, "")
try:
return template.format(**kwargs)
except KeyError:
return template
catalog = StringCatalog()
+118
View File
@@ -0,0 +1,118 @@
import sys
from typing import List, Optional, Tuple
try:
from sec.src.catalog import catalog
from sec.src.client import CheatClient
from sec.src.clipboard import copy_to_clipboard, extract_code_only, strip_ansi
from sec.src.manifest import load_manifest
from sec.src.renderer import SnippetRenderer
from sec.src.router import QueryRouter
except ImportError:
from src.catalog import catalog
from src.client import CheatClient
from src.clipboard import copy_to_clipboard, extract_code_only, strip_ansi
from src.manifest import load_manifest
from src.renderer import SnippetRenderer
from src.router import QueryRouter
def parse_arguments(raw_args: List[str]) -> Tuple[List[str], Optional[str], bool]:
"""Parse raw arguments into (query_tokens, copy_mode, is_version_flag)."""
copy_mode = None
is_version = False
query_tokens: List[str] = []
i = 0
while i < len(raw_args):
arg = raw_args[i]
if arg in ["-V", "-v", "--version"]:
is_version = True
i += 1
continue
if arg in ["-c", "--copy"]:
# Check if next token is 'a' or 'all'
if i + 1 < len(raw_args) and raw_args[i + 1].lower() in ["a", "all"]:
copy_mode = "all"
i += 2
continue
else:
copy_mode = "code"
i += 1
continue
if arg in ["--copy-all", "-ca"]:
copy_mode = "all"
i += 1
continue
query_tokens.append(arg)
i += 1
return query_tokens, copy_mode, is_version
def run_cli(args: Optional[List[str]] = None) -> int:
if hasattr(sys.stdout, "reconfigure"):
try:
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
except Exception:
pass
raw_args = args if args is not None else sys.argv[1:]
query_tokens, copy_mode, is_version = parse_arguments(raw_args)
if is_version:
manifest = load_manifest()
version_text = catalog.format(
"app.version_output",
name=manifest.get("name", "SEC"),
version=manifest.get("version", "1.0.0"),
stage=manifest.get("stage", "Alpha"),
description=manifest.get("description", ""),
)
print(version_text)
return 0
if not query_tokens:
manifest = load_manifest()
print(f"{manifest.get('name', 'SEC')} v{manifest.get('version', '1.0.0')} [{manifest.get('stage', 'Alpha')}] - {manifest.get('description', '')}")
print("Usage: sec <query...> [-c] [-c a]")
print("Examples:")
print(" sec python read json")
print(" sec tar extract")
print(" sec linux memory usage")
print(" sec git undo commit -c # Copy code only to clipboard")
print(" sec docker build -c a # Copy full response to clipboard")
return 0
raw_query = " ".join(query_tokens)
router = QueryRouter()
routed = router.route(query_tokens)
client = CheatClient()
renderer = SnippetRenderer()
result = client.fetch(routed)
if not result:
renderer.render_not_found(raw_query)
return 0
copied = False
is_all_copy = False
if copy_mode:
if copy_mode == "all":
text_to_copy = strip_ansi(result.content)
is_all_copy = True
else:
text_to_copy = extract_code_only(result.content)
is_all_copy = False
if text_to_copy:
copied = copy_to_clipboard(text_to_copy)
renderer.render_result(result, copied=copied, is_all_copy=is_all_copy)
return 0
+131
View File
@@ -0,0 +1,131 @@
import os
import sqlite3
import time
from dataclasses import dataclass
from pathlib import Path
from typing import Optional
import requests
from sec.src.router import RoutedQuery
@dataclass
class FetchResult:
query: str
url: str
content: str
is_cached: bool
is_fallback: bool
class CheatClient:
"""Handles HTTP requests to cheat.sh and manages the local query cache."""
def __init__(self, cache_db_path: Optional[str] = None, timeout: int = 6):
if cache_db_path is None:
base_dir = Path(__file__).resolve().parent.parent
data_dir = base_dir / "data"
data_dir.mkdir(parents=True, exist_ok=True)
cache_db_path = str(data_dir / "cache.db")
self.cache_db_path = cache_db_path
self.timeout = timeout
self._init_cache()
def _init_cache(self) -> None:
conn = sqlite3.connect(self.cache_db_path)
cur = conn.cursor()
cur.execute("""
CREATE TABLE IF NOT EXISTS query_cache (
query_key TEXT PRIMARY KEY,
url TEXT NOT NULL,
content TEXT NOT NULL,
timestamp REAL NOT NULL
);
""")
conn.commit()
conn.close()
def _get_from_cache(self, query_key: str) -> Optional[str]:
try:
conn = sqlite3.connect(self.cache_db_path)
cur = conn.cursor()
cur.execute("SELECT content FROM query_cache WHERE query_key = ?", (query_key,))
row = cur.fetchone()
conn.close()
return row[0] if row else None
except Exception:
return None
def _save_to_cache(self, query_key: str, url: str, content: str) -> None:
try:
conn = sqlite3.connect(self.cache_db_path)
cur = conn.cursor()
cur.execute("""
INSERT OR REPLACE INTO query_cache (query_key, url, content, timestamp)
VALUES (?, ?, ?, ?);
""", (query_key, url, content, time.time()))
conn.commit()
conn.close()
except Exception:
pass
def _is_error_response(self, text: str) -> bool:
if not text or not text.strip():
return True
lower = text.lower()
if (
"unknown cheat sheet" in lower
or "404 not found" in lower
or "page not found" in lower
or "internal::list" in lower
or text.startswith("#[internal::list]")
or text.startswith("internal::list")
):
return True
if len(text.strip()) < 5:
return True
return False
def _http_get(self, url: str) -> Optional[str]:
headers = {
"User-Agent": "curl/7.88.1",
"Accept": "*/*",
}
# ?T ensures plain text without html wrapping
fetch_url = url if "?" in url else f"{url}?T"
try:
resp = requests.get(fetch_url, headers=headers, timeout=self.timeout)
if resp.status_code == 200 and not self._is_error_response(resp.text):
return resp.text.strip()
except Exception:
pass
return None
def fetch(self, routed: RoutedQuery) -> Optional[FetchResult]:
query_key = routed.raw_query
# 1. Attempt candidate URLs in priority order
for idx, url in enumerate(routed.candidate_urls):
content = self._http_get(url)
if content:
self._save_to_cache(query_key, url, content)
return FetchResult(
query=routed.raw_query,
url=url,
content=content,
is_cached=False,
is_fallback=(idx > 0),
)
# 2. Fallback to local cache if offline or network error
cached_content = self._get_from_cache(query_key)
if cached_content and not self._is_error_response(cached_content):
return FetchResult(
query=routed.raw_query,
url=routed.primary_url,
content=cached_content,
is_cached=True,
is_fallback=False,
)
return None
+118
View File
@@ -0,0 +1,118 @@
import ctypes
from ctypes import wintypes
import os
import platform
import re
import subprocess
from typing import List
ANSI_ESCAPE_RE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
def strip_ansi(text: str) -> str:
"""Remove ANSI escape sequences from text."""
return ANSI_ESCAPE_RE.sub("", text)
def extract_code_only(text: str) -> str:
"""Extract only executable code lines, removing comments, blank lines, and headers."""
clean_text = strip_ansi(text)
lines = clean_text.splitlines()
code_lines: List[str] = []
for line in lines:
stripped = line.strip()
if not stripped:
continue
# Skip comment lines
if (
stripped.startswith("#")
or stripped.startswith("//")
or stripped.startswith("/*")
or stripped.startswith("*")
or stripped.startswith("*/")
or stripped.startswith("rem ")
or stripped.startswith("--")
or stripped.startswith('"""')
or stripped.startswith("'''")
):
continue
# Skip cheat.sh page header artifacts
if stripped.startswith("cheat:") or stripped.startswith("tags:") or stripped == "---":
continue
code_lines.append(line)
return "\n".join(code_lines).strip()
def copy_to_clipboard(text: str) -> bool:
"""Copy text to system clipboard across Windows, macOS, and Linux."""
if not text:
return False
system = platform.system()
if system == "Windows":
try:
GMEM_MOVEABLE = 0x0002
CF_UNICODETEXT = 13
user32 = ctypes.windll.user32
kernel32 = ctypes.windll.kernel32
kernel32.GlobalAlloc.restype = wintypes.HGLOBAL
kernel32.GlobalAlloc.argtypes = [wintypes.UINT, ctypes.c_size_t]
kernel32.GlobalLock.restype = wintypes.LPVOID
kernel32.GlobalLock.argtypes = [wintypes.HGLOBAL]
kernel32.GlobalUnlock.argtypes = [wintypes.HGLOBAL]
user32.SetClipboardData.argtypes = [wintypes.UINT, wintypes.HANDLE]
encoded = text.encode("utf-16le") + b"\x00\x00"
if not user32.OpenClipboard(None):
return False
user32.EmptyClipboard()
h_mem = kernel32.GlobalAlloc(GMEM_MOVEABLE, len(encoded))
if not h_mem:
user32.CloseClipboard()
return False
p_mem = kernel32.GlobalLock(h_mem)
if not p_mem:
user32.CloseClipboard()
return False
ctypes.memmove(p_mem, encoded, len(encoded))
kernel32.GlobalUnlock(h_mem)
user32.SetClipboardData(CF_UNICODETEXT, h_mem)
user32.CloseClipboard()
return True
except Exception:
return False
elif system == "Darwin":
try:
p = subprocess.Popen(["pbcopy"], stdin=subprocess.PIPE)
p.communicate(text.encode("utf-8"))
return p.returncode == 0
except Exception:
return False
else:
# Linux (xclip / wl-copy / xsel)
for cmd in [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]]:
try:
p = subprocess.Popen(cmd, stdin=subprocess.PIPE)
p.communicate(text.encode("utf-8"))
if p.returncode == 0:
return True
except Exception:
continue
return False
+22
View File
@@ -0,0 +1,22 @@
import json
from pathlib import Path
from typing import Any, Dict
def load_manifest() -> Dict[str, Any]:
"""Load metadata from manifest.json located at package root."""
base_dir = Path(__file__).resolve().parent.parent
manifest_path = base_dir / "manifest.json"
if manifest_path.exists():
try:
with open(manifest_path, "r", encoding="utf-8") as f:
return json.load(f)
except Exception:
pass
return {
"name": "Sec",
"version": "1.0.0",
"stage": "Alpha",
"description": "CLI Cheat Sheet & Code Snippet Assistant",
"dependencies": ["requests>=2.28.0", "rich>=13.0.0"],
}
+43
View File
@@ -0,0 +1,43 @@
from rich.console import Console
from rich.panel import Panel
from rich.text import Text
try:
from sec.src.catalog import catalog
from sec.src.client import FetchResult
except ImportError:
from src.catalog import catalog
from src.client import FetchResult
class SnippetRenderer:
"""Renders cheat.sh responses in styled terminal format."""
def __init__(self, console: Console = None):
self.console = console or Console()
def render_not_found(self, query: str) -> None:
msg = catalog.format("status.not_found", query=query)
self.console.print(f"[dim]{msg}[/dim]")
def render_network_error(self) -> None:
msg = catalog.get("status.network_error")
self.console.print(f"[red]{msg}[/red]")
def render_clipboard_notice(self, is_all: bool) -> None:
key = "status.copied_all" if is_all else "status.copied_code"
msg = catalog.get(key)
self.console.print(f"[bold cyan]>> {msg}[/bold cyan]")
def render_result(self, result: FetchResult, copied: bool = False, is_all_copy: bool = False) -> None:
if result.is_cached:
cached_notice = catalog.get("status.offline_cached")
self.console.print(f"[yellow]{cached_notice}[/yellow]")
# Print content with native ANSI formatting
parsed_text = Text.from_ansi(result.content)
self.console.print(parsed_text)
if copied:
self.console.print("")
self.render_clipboard_notice(is_all_copy)
+209
View File
@@ -0,0 +1,209 @@
from dataclasses import dataclass, field
from typing import List
from urllib.parse import quote_plus
PROGRAMMING_LANGS = {
"python", "py", "go", "golang", "rust", "rs", "javascript", "js",
"typescript", "ts", "c", "cpp", "c++", "csharp", "cs", "java", "kotlin",
"kt", "swift", "php", "ruby", "rb", "perl", "lua", "r", "scala", "dart",
"elixir", "clojure", "haskell", "hs", "erlang", "zig", "nim", "bash", "sh",
"zsh", "fish", "powershell", "ps1", "sql", "mysql", "postgres", "sqlite",
}
CLI_TOOLS = {
"tar", "grep", "find", "sed", "awk", "ssh", "scp", "rsync", "curl", "wget",
"chmod", "chown", "ps", "top", "htop", "kill", "lsof", "netstat", "ip",
"tmux", "screen", "vim", "nvim", "nano", "ffmpeg", "jq", "openssl",
"docker", "dockerfile", "compose", "docker-compose", "git", "kubectl", "k8s",
"terraform", "ansible", "nginx", "apache", "systemd", "iptables", "ufw",
"free", "df", "du", "vmstat", "iostat", "sar", "strace", "nc", "nmap",
}
PLATFORM_STOPWORDS = {
"linux", "ubuntu", "debian", "arch", "centos", "alpine", "unix",
"windows", "macos", "shell", "command", "how", "to", "cli", "example",
}
COMMON_SYNONYMS = {
"serialize": ["dump", "dumps", "write", "stringify", "encode", "save"],
"serialization": ["dump", "dumps", "write", "stringify", "encode", "save"],
"deserialize": ["load", "loads", "read", "parse", "decode"],
"deserialization": ["load", "loads", "read", "parse", "decode"],
"parse": ["load", "loads", "read", "decode"],
"read": ["load", "open", "parse", "get"],
"write": ["dump", "save", "export", "create"],
"save": ["write", "dump", "export"],
"delete": ["remove", "del", "drop", "pop", "clear"],
"remove": ["delete", "del", "drop", "pop", "clear"],
"sort": ["sorted", "order", "reverse", "orderby"],
"order": ["sort", "sorted", "reverse"],
"find": ["search", "lookup", "match", "filter", "get"],
"search": ["find", "lookup", "match", "grep", "filter"],
"iterate": ["loop", "for", "traverse", "each"],
"loop": ["iterate", "for", "traverse", "while"],
"filter": ["find", "match", "where", "select"],
"reverse": ["reversed", "invert"],
"reversed": ["reverse", "invert"],
"length": ["size", "count", "len"],
"size": ["length", "count", "len"],
"count": ["size", "length", "len"],
"convert": ["cast", "parse", "to", "transform"],
"extract": ["unpack", "unzip", "untar", "decompress"],
"compress": ["archive", "pack", "zip", "tar"],
}
@dataclass
class RoutedQuery:
raw_query: str
target: str
subquery: str
candidate_urls: List[str] = field(default_factory=list)
is_targeted: bool = False
@property
def primary_url(self) -> str:
return self.candidate_urls[0] if self.candidate_urls else "https://cht.sh"
@property
def fallback_url(self) -> str:
return self.candidate_urls[1] if len(self.candidate_urls) > 1 else self.primary_url
class QueryRouter:
"""Parses arbitrary CLI tokens into prioritized cheat.sh candidate URLs."""
@staticmethod
def _generate_query_variants(tokens: List[str]) -> List[str]:
"""Generates orderings and synonym variants for query subterms."""
variants: List[List[str]] = [list(tokens)]
# Permutation with reversed terms for two-token subqueries
if len(tokens) == 2:
variants.append([tokens[1], tokens[0]])
# Generate synonym replacements
for i, token in enumerate(tokens):
if token in COMMON_SYNONYMS:
for syn in COMMON_SYNONYMS[token]:
new_variant = list(tokens)
new_variant[i] = syn
variants.append(new_variant)
if len(new_variant) == 2:
variants.append([new_variant[1], new_variant[0]])
seen = set()
unique_variants: List[str] = []
for v in variants:
joined = "+".join(quote_plus(t) for t in v)
if joined not in seen:
seen.add(joined)
unique_variants.append(joined)
return unique_variants
@classmethod
def route(cls, tokens: List[str]) -> RoutedQuery:
cleaned_tokens = [t.strip().lower() for t in tokens if t.strip()]
if not cleaned_tokens:
return RoutedQuery(
raw_query="",
target="",
subquery="",
candidate_urls=["https://cht.sh"],
is_targeted=False,
)
raw_query = " ".join(cleaned_tokens)
first_token = cleaned_tokens[0]
remaining = cleaned_tokens[1:]
# 1. Programming Languages (cht.sh/python/json+dumps, cht.sh/python/write+json)
if first_token in PROGRAMMING_LANGS:
if remaining:
candidates = []
variants = cls._generate_query_variants(remaining)
for var in variants:
candidates.append(f"https://cht.sh/{first_token}/{var}")
# Individual keyword lookups in language scope
for token in remaining:
candidates.append(f"https://cht.sh/{first_token}/{quote_plus(token)}")
# Search within language
tilde_sub = "~".join(quote_plus(t) for t in remaining)
candidates.append(f"https://cht.sh/{first_token}/~{tilde_sub}")
# Global fallback with tilde
candidates.append(f"https://cht.sh/~{first_token}~{tilde_sub}")
else:
candidates = [f"https://cht.sh/{first_token}"]
return RoutedQuery(
raw_query=raw_query,
target=first_token,
subquery=" ".join(remaining),
candidate_urls=candidates,
is_targeted=True,
)
# 2. Recognized CLI Tools (cht.sh/tar~extract or cht.sh/tar)
if first_token in CLI_TOOLS:
if remaining:
candidates = []
tilde_sub = "~".join(quote_plus(t) for t in remaining)
candidates.append(f"https://cht.sh/{first_token}~{tilde_sub}")
# Synonym variants for CLI tool subqueries
variants = cls._generate_query_variants(remaining)
for var in variants:
candidates.append(f"https://cht.sh/{first_token}/{var}")
candidates.append(f"https://cht.sh/~{first_token}~{tilde_sub}")
else:
candidates = [
f"https://cht.sh/{first_token}",
f"https://cht.sh/~{first_token}",
]
return RoutedQuery(
raw_query=raw_query,
target=first_token,
subquery=" ".join(remaining),
candidate_urls=candidates,
is_targeted=True,
)
# 3. Single word query (cht.sh/command or cht.sh/~word)
if len(cleaned_tokens) == 1:
word = cleaned_tokens[0]
candidates = [
f"https://cht.sh/{word}",
f"https://cht.sh/~{word}",
]
return RoutedQuery(
raw_query=raw_query,
target=word,
subquery="",
candidate_urls=candidates,
is_targeted=True,
)
# 4. Multi-token general search (e.g., 'linux memory usage' -> '~linux~memory~usage', '~memory~usage', '~memory')
candidates = []
candidates.append(f"https://cht.sh/~{'~'.join(quote_plus(t) for t in cleaned_tokens)}")
meaningful_tokens = [t for t in cleaned_tokens if t not in PLATFORM_STOPWORDS]
if meaningful_tokens and meaningful_tokens != cleaned_tokens:
candidates.append(f"https://cht.sh/~{'~'.join(quote_plus(t) for t in meaningful_tokens)}")
if len(meaningful_tokens) > 1:
for token in meaningful_tokens:
candidates.append(f"https://cht.sh/~{quote_plus(token)}")
return RoutedQuery(
raw_query=raw_query,
target="",
subquery=raw_query,
candidate_urls=candidates,
is_targeted=False,
)