superacli 1.0.0

package/docs/initial/architecture.md

@@ -0,0 +1,436 @@
+The main risk of a **cloud-defined CLI** is that as commands grow (hundreds → thousands), the CLI becomes **slow, heavy, and chatty**.
+
+The trick used by large systems (like Kubernetes or Terraform) is **lazy resolution + namespace indexing**.
+
+The CLI **never loads the whole command universe**.
+
+Instead it resolves commands **progressively**.
+
+---
+
+# 1. The Problem at Scale
+
+If the server sends the full config:
+
+```
+10 namespaces
+200 resources
+2000 commands
+```
+
+The CLI cache becomes:
+
+```
+5–10 MB JSON
+```
+
+Problems:
+
+* slow startup
+* slow autocomplete
+* frequent config refreshes
+* unnecessary data
+
+---
+
+# 2. The Solution: Hierarchical Command Index
+
+Instead of returning **all commands**, the API exposes a **tree index**.
+
+Think of commands as a **filesystem**.
+
+Example structure:
+
+```
+/
+ ├ referential
+ │   ├ users
+ │   │   ├ fetch
+ │   │   ├ list
+ │   │   └ create
+ │   └ groups
+ │
+ ├ infra
+ │   └ service
+ │       ├ deploy
+ │       └ logs
+ │
+ └ ai
+     └ summarize
+```
+
+The CLI only loads **what the user navigates**.
+
+---
+
+# 3. Progressive Resolution
+
+Example CLI session:
+
+```
+supercli <TAB>
+```
+
+CLI requests:
+
+```
+GET /api/tree
+```
+
+Response:
+
+```json
+{
+  "namespaces": [
+    "referential",
+    "infra",
+    "ai"
+  ]
+}
+```
+
+---
+
+User continues:
+
+```
+supercli referential <TAB>
+```
+
+CLI calls:
+
+```
+GET /api/tree/referential
+```
+
+Response:
+
+```json
+{
+  "resources": [
+    "users",
+    "groups"
+  ]
+}
+```
+
+---
+
+Next:
+
+```
+supercli referential users <TAB>
+```
+
+Request:
+
+```
+GET /api/tree/referential/users
+```
+
+Response:
+
+```json
+{
+  "actions": [
+    "fetch",
+    "list",
+    "create"
+  ]
+}
+```
+
+---
+
+Finally execution:
+
+```
+supercli referential users fetch
+```
+
+CLI fetches full command:
+
+```
+GET /api/command/referential/users/fetch
+```
+
+---
+
+# 4. CLI Cache Structure
+
+Instead of one big config file:
+
+```
+~/.supercli/
+```
+
+Use segmented cache.
+
+```
+~/.supercli/cache/
+
+namespaces.json
+referential.resources.json
+referential.users.actions.json
+command.referential.users.fetch.json
+```
+
+This keeps each cache file tiny.
+
+---
+
+# 5. CLI Runtime Algorithm
+
+Command parsing:
+
+```
+supercli referential users fetch --id 42
+```
+
+Resolution steps:
+
+1. resolve namespace
+2. resolve resource
+3. resolve action
+4. fetch command spec
+
+Pseudo logic:
+
+```
+resolveNamespace()
+resolveResource()
+resolveAction()
+fetchCommand()
+execute()
+```
+
+Each step is cached.
+
+---
+
+# 6. Why This Scales
+
+With **5000 commands**:
+
+| Strategy     | Data loaded |
+| ------------ | ----------- |
+| Full config  | 5–10 MB     |
+| Tree index   | ~2 KB       |
+| Command spec | ~1 KB       |
+
+CLI startup remains **instant**.
+
+---
+
+# 7. Server-Side Index
+
+Server stores commands normally.
+
+But builds an index:
+
+```
+namespace
+resource
+action
+```
+
+Mongo query:
+
+```
+db.commands.distinct("namespace")
+```
+
+or:
+
+```
+db.commands.distinct("resource",{namespace:"referential"})
+```
+
+Very fast.
+
+---
+
+# 8. Autocomplete Becomes Cheap
+
+Shell autocomplete simply queries the CLI.
+
+Example:
+
+```
+__supercli_complete referential users
+```
+
+CLI resolves locally from cache or calls:
+
+```
+GET /api/tree/referential/users
+```
+
+Latency:
+
+```
+<20ms
+```
+
+---
+
+# 9. Bonus Trick: ETags
+
+Each tree response includes an **etag**.
+
+Example:
+
+```
+ETag: tree-v42
+```
+
+CLI requests:
+
+```
+If-None-Match: tree-v42
+```
+
+Server returns:
+
+```
+304 Not Modified
+```
+
+Meaning:
+
+```
+zero bandwidth
+```
+
+---
+
+# 10. Further Optimization: Namespace Packs
+
+Large organizations may have:
+
+```
+10000 commands
+```
+
+Namespaces can be grouped:
+
+```
+referential
+infra
+billing
+ai
+platform
+```
+
+CLI can preload frequently used namespaces.
+
+Example config:
+
+```
+~/.supercli/profile.json
+```
+
+```
+{
+  "prefetch": ["referential","infra"]
+}
+```
+
+---
+
+# 11. Lazy Adapter Loading
+
+Another important trick.
+
+Adapters are loaded **only when needed**.
+
+Example:
+
+```
+adapters/
+ openapi.js
+ mcp.js
+ http.js
+```
+
+Runtime:
+
+```
+require("./adapters/"+adapter)
+```
+
+So a user running **OpenAPI commands** never loads MCP code.
+
+---
+
+# 12. Execution Shortcut
+
+For frequently used commands, cache the spec:
+
+```
+~/.supercli/cache/command.hash
+```
+
+Next run:
+
+```
+skip server entirely
+```
+
+---
+
+# 13. Resulting Performance
+
+With the above design:
+
+| Metric            | Value        |
+| ----------------- | ------------ |
+| CLI startup       | <10 ms       |
+| Autocomplete      | <20 ms       |
+| Command execution | network only |
+| Cache size        | <200 KB      |
+
+Even with **thousands of commands**.
+
+---
+
+# 14. The Elegant Part
+
+The CLI becomes:
+
+```
+a command resolver
+```
+
+Not:
+
+```
+a command registry
+```
+
+Which is why it scales.
+
+---
+
+# 15. Final Architecture
+
+```
+            Web UI
+              |
+              v
+       Control Plane API
+              |
+        MongoDB commands
+              |
+      Hierarchical index
+              |
+          CLI runtime
+              |
+        Adapter execution
+```
+
+The CLI stays **tiny and fast**, while the **command universe can grow arbitrarily**.
+
+---
+
+If you want, I can also show you **one design tweak that would make SUPERCLI extremely attractive to AI agents and MCP ecosystems**, which could position it as a **universal tool registry for LLMs**.

package/docs/initial/built-in-mcp-server.md

@@ -0,0 +1,64 @@
+Absolutely — that’s a **natural extension** and fits perfectly with the SUPERCLI philosophy. Here’s why it’s interesting and how it would work:
+
+---
+
+## 💡 Built-in MCP Server for SUPERCLI
+
+### What it Enables
+
+1. **Dynamic Agent Integration**
+
+   * Agents can connect over **MCP (Modular Control Protocol)** using SSE/STDIO.
+   * Commands, schemas, and DAGs are automatically exposed in a structured, versioned way.
+   * No need for agents to hardcode knowledge of SUPERCLI commands.
+
+2. **Real-Time Event Streaming**
+
+   * Long-running commands can stream progress, logs, or DAG step completion via SSE.
+   * Agents can monitor execution, abort, or react dynamically without polling.
+
+3. **Single-Call Semantics Preserved**
+
+   * The MCP server is just a transport layer. Execution is still **one-shot** per command.
+   * Optional DAG exposure can be streamed as events or included inline.
+
+4. **Composable in Multi-Agent Systems**
+
+   * Multiple agents can subscribe to the MCP server.
+   * One agent triggers a command; others can observe DAG progress, results, or metadata.
+
+5. **OSS-Friendly**
+
+   * Exposing SUPERCLI over MCP provides a **standardized API** for agentic workflows.
+   * Makes SUPERCLI a drop-in alternative to proprietary agent-driven CLIs like gws but **open source and ecosystem-agnostic**.
+
+---
+
+### Example Flow
+
+```text
+Agent connects → subscribes to SUPERCLI MCP SSE
+Agent sends: fetch users --id 42
+Server computes DAG → executes steps
+Server streams: DAG nodes as events (if requested) + final structured result
+Agent consumes JSON, makes decisions, possibly triggers downstream commands
+```
+
+**Optional DAG**: Could be streamed incrementally, reducing token usage for very large workflows.
+
+---
+
+### Key Benefits
+
+| Benefit                      | Why It Matters                                                 |
+| ---------------------------- | -------------------------------------------------------------- |
+| Real-time visibility         | Agents can reason mid-execution or report status               |
+| Schema introspection via MCP | Agents discover commands dynamically, no prior hardcoding      |
+| Standardized transport       | MCP SSE/STDIO works for both CLI clients and agentic pipelines |
+| OSS extensibility            | Any team can deploy SUPERCLI + MCP server internally or externally |
+
+---
+
+If you want, I can **draft a full architecture diagram and flow** showing **SUPERCLI + built-in MCP server**, including optional DAG streaming, single-shot execution, and agent discovery — essentially how SUPERCLI becomes an **open, AI-first alternative to gws with universal applicability**.
+
+Do you want me to do that next?