superacli 1.0.0

package/docs/initial/core-features-2.md

@@ -0,0 +1,428 @@
+The idea that really changes the nature of the project is to treat **commands as a control plane resource**, similar to how Kubernetes treats pods, services, and deployments.
+
+Instead of “a CLI that runs commands”, you get:
+
+**A distributed command runtime where the CLI is just one client.**
+
+That turns SUPERCLI into something closer to a **“Kubernetes for commands / tools / APIs / AI”**.
+
+---
+
+# 1. Core Shift: Commands Become Resources
+
+Instead of thinking:
+
+```
+CLI command
+```
+
+Think:
+
+```
+Command Resource
+```
+
+Similar to:
+
+* Deployment
+* Service
+* Job
+
+Example resource:
+
+```
+Command
+```
+
+Example definition:
+
+```yaml
+kind: Command
+metadata:
+  name: users.fetch
+spec:
+  namespace: referential
+  resource: users
+  action: fetch
+
+  adapter: openapi
+
+  adapterConfig:
+    spec: referential-api
+    operationId: getUser
+```
+
+The CLI just **invokes resources**.
+
+---
+
+# 2. Introduce “Command Jobs”
+
+Every execution becomes a **job**.
+
+Example:
+
+```
+supercli referential users fetch --id 42
+```
+
+Creates:
+
+```
+CommandJob
+```
+
+Example record:
+
+```json
+{
+  "id": "job_9821",
+  "command": "referential.users.fetch",
+  "args": { "id": 42 },
+  "status": "running",
+  "createdAt": "...",
+  "result": null
+}
+```
+
+Stored in Mongo.
+
+This allows:
+
+* retries
+* observability
+* async execution
+* distributed runners
+
+---
+
+# 3. Introduce Runners
+
+Instead of executing commands **inside the CLI**, you can have **runners**.
+
+Architecture:
+
+```
+CLI
+   |
+API
+   |
+Job Queue
+   |
+Runners
+```
+
+Runners execute commands.
+
+Example runner types:
+
+```
+http-runner
+mcp-runner
+infra-runner
+ai-runner
+```
+
+This enables:
+
+```
+distributed command execution
+```
+
+---
+
+# 4. Command Events
+
+Each command produces events.
+
+Example:
+
+```
+CommandStarted
+CommandFinished
+CommandFailed
+```
+
+These can be streamed.
+
+Architecture:
+
+```
+CLI
+  |
+API
+  |
+Event Bus
+  |
+Subscribers
+```
+
+Use cases:
+
+* dashboards
+* audit logs
+* automation
+
+---
+
+# 5. Command Pipelines
+
+Commands can subscribe to events.
+
+Example:
+
+```
+user.created
+```
+
+Triggers:
+
+```
+billing.createCustomer
+email.sendWelcome
+```
+
+This turns the system into a **light automation platform**.
+
+---
+
+# 6. Multi-Client Interface
+
+Once commands are resources, multiple interfaces become possible.
+
+Clients:
+
+```
+CLI
+Web UI
+API
+Agents
+```
+
+AI agents could call commands like tools.
+
+Example agent toolset:
+
+```
+referential.users.fetch
+infra.service.deploy
+billing.invoice.create
+```
+
+This makes SUPERCLI a **tool registry for agents**.
+
+---
+
+# 7. Command Permissions
+
+Once commands are resources, you can add RBAC.
+
+Example:
+
+```
+role: dev
+allowed:
+ - referential.users.*
+ - infra.service.deploy
+```
+
+---
+
+# 8. Command Versioning
+
+Commands can evolve.
+
+Example:
+
+```
+referential.users.fetch:v1
+referential.users.fetch:v2
+```
+
+This solves a classic CLI problem:
+
+```
+breaking changes
+```
+
+---
+
+# 9. Observability
+
+Because commands become jobs, you can track:
+
+```
+execution time
+failure rate
+usage
+```
+
+Example dashboard:
+
+```
+Top commands
+Failed commands
+Slow commands
+```
+
+This is something traditional CLIs lack.
+
+---
+
+# 10. Command Graph Visualization
+
+The Web UI could show command relationships.
+
+Example:
+
+```
+infra.service.deploy
+ ├ build
+ ├ push
+ ├ deploy
+ └ verify
+```
+
+This helps teams understand automation.
+
+---
+
+# 11. AI Agents as Runners
+
+An interesting extension:
+
+```
+runner: ai-agent
+```
+
+Example command:
+
+```
+analysis.repository.audit
+```
+
+Runner:
+
+```
+LLM agent
+```
+
+This integrates AI tasks into the same execution plane.
+
+---
+
+# 12. Real Architecture
+
+System becomes:
+
+```
+                +------------------+
+                |      Web UI      |
+                +---------+--------+
+                          |
+                          v
+                    Control Plane
+                     (NodeJS)
+                          |
+           +--------------+-------------+
+           |                            |
+           v                            v
+      Command DB                  Command Jobs
+        MongoDB                      MongoDB
+           |                            |
+           +-------------+--------------+
+                         |
+                    Event Stream
+                         |
+                +--------+--------+
+                |                 |
+                v                 v
+             Runners           CLI
+```
+
+---
+
+# 13. Why This Is a New Category
+
+Most tools only solve one layer:
+
+| Tool           | Capability   |
+| -------------- | ------------ |
+| Terraform      | infra        |
+| Postman        | APIs         |
+| LangChain      | AI tools     |
+| GitHub Actions | CI pipelines |
+
+SUPERCLI could unify:
+
+```
+APIs
+AI tools
+infra
+automation
+```
+
+Under one runtime.
+
+---
+
+# 14. The Simplest Killer Demo
+
+A single project could show the power.
+
+```
+supercli import-openapi stripe.json
+```
+
+Now the CLI instantly supports:
+
+```
+supercli stripe customers list
+supercli stripe charges create
+```
+
+Then:
+
+```
+supercli workflow create-customer
+```
+
+Pipeline:
+
+```
+stripe.customer.create
+email.send
+crm.contact.create
+```
+
+Then:
+
+```
+supercli ask "create a customer for john@example.com"
+```
+
+And the system routes to commands.
+
+That demo alone would communicate the idea extremely well.
+
+---
+
+# 15. Strategic Insight
+
+The real value isn't the CLI.
+
+The value is:
+
+```
+a control plane for tools
+```
+
+Which could eventually become:
+
+```
+a universal execution layer for humans and agents
+```
+
+---
+
+If you're interested, the next thing worth designing is the **single architectural trick that would let this scale to thousands of commands without the CLI becoming slow or bloated**.