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
+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.