superacli 1.0.0

package/docs/initial/core-features.md

@@ -0,0 +1,366 @@
+These are **three features that would make SUPERCLI genuinely stand out** and likely gain traction if open-sourced. They all build on the **cloud-defined command graph** concept you already designed.
+
+---
+
+# 1. Command Graph (Composable CLI)
+
+Most CLIs execute **single commands**.
+SUPERCLI can execute **graphs of commands** defined in config.
+
+This turns the CLI into a **light orchestration engine**.
+
+## Concept
+
+Commands can call other commands.
+
+Example command:
+
+```
+infra deploy service
+```
+
+Internally defined as:
+
+```
+infra.build
+infra.push
+infra.deploy
+infra.verify
+```
+
+---
+
+## Mongo Model
+
+Add:
+
+```
+type: "command" | "workflow"
+```
+
+Example:
+
+```
+{
+  namespace: "infra",
+  resource: "service",
+  action: "deploy",
+
+  type: "workflow",
+
+  steps: [
+    "infra service build",
+    "infra service push",
+    "infra service deploy",
+    "infra service verify"
+  ]
+}
+```
+
+---
+
+## CLI Execution
+
+```
+supercli infra service deploy
+```
+
+Executor:
+
+```
+for step in workflow.steps:
+   run(step)
+```
+
+---
+
+## Benefits
+
+This makes the CLI capable of:
+
+```
+deployments
+infra automation
+data pipelines
+AI pipelines
+```
+
+without needing another orchestrator.
+
+---
+
+# 2. Natural Language CLI (AI Command Router)
+
+Add an optional **LLM router** that maps natural language to commands.
+
+Example:
+
+```
+supercli ask "fetch user 42 and summarize activity"
+```
+
+The system resolves:
+
+```
+referential users fetch --id 42
+ai summarize --user 42
+```
+
+---
+
+## Architecture
+
+```
+User input
+     |
+LLM router
+     |
+command graph
+     |
+CLI executor
+```
+
+---
+
+## Prompt Context
+
+Provide the model with:
+
+```
+available commands
+arguments
+descriptions
+```
+
+Example context:
+
+```
+referential users fetch --id
+ai summarize --text
+```
+
+---
+
+## Model Output
+
+Structured:
+
+```
+[
+ {
+  command:"referential users fetch",
+  args:{id:42}
+ },
+ {
+  command:"ai summarize",
+  args:{text:"$prev.output"}
+ }
+]
+```
+
+---
+
+## CLI Execution
+
+```
+execute step 1
+pipe result
+execute step 2
+```
+
+---
+
+## Why This Is Powerful
+
+It turns the CLI into:
+
+```
+natural language operational interface
+```
+
+Useful for:
+
+```
+SRE
+platform teams
+AI operators
+```
+
+---
+
+# 3. Dynamic CLI Autocomplete
+
+This is a **killer UX feature**.
+
+Autocomplete comes from **cloud config**, not static definitions.
+
+Example:
+
+```
+supercli <TAB>
+```
+
+Shows:
+
+```
+referential
+infra
+ai
+billing
+```
+
+---
+
+```
+supercli referential <TAB>
+```
+
+Shows:
+
+```
+users
+groups
+devices
+```
+
+---
+
+```
+supercli referential users <TAB>
+```
+
+Shows:
+
+```
+fetch
+list
+create
+delete
+```
+
+---
+
+## Implementation
+
+CLI exposes:
+
+```
+supercli completion
+```
+
+Shell integration:
+
+```
+eval "$(supercli completion bash)"
+```
+
+---
+
+## Completion Script Logic
+
+Autocomplete calls:
+
+```
+supercli __complete referential users
+```
+
+CLI returns:
+
+```
+fetch
+list
+create
+```
+
+Using cached config.
+
+---
+
+# 4. Bonus Feature (Very GitHub-Friendly)
+
+## OpenAPI → CLI Auto Generation
+
+Add a button in the UI:
+
+```
+Import OpenAPI
+```
+
+The system:
+
+1 downloads spec
+2 scans operations
+3 generates commands automatically
+
+Example mapping:
+
+```
+GET /users -> referential users list
+GET /users/{id} -> referential users fetch
+POST /users -> referential users create
+```
+
+This instantly produces a **full CLI for any API**.
+
+---
+
+# 5. Hidden Strategic Value
+
+The project becomes a **control plane for developer operations**.
+
+It unifies:
+
+```
+API CLI
+AI tools
+infra commands
+workflows
+```
+
+Into one system.
+
+This makes SUPERCLI essentially a:
+
+```
+Universal DevOps + AI CLI runtime
+```
+
+---
+
+# 6. If Open-Sourced
+
+These 3 features would likely attract users:
+
+1️⃣ **Cloud-defined CLI**
+2️⃣ **Command workflows**
+3️⃣ **Natural language CLI**
+
+This combination is currently **rare in developer tooling**.
+
+---
+
+# 7. What Would Make It Go Viral
+
+One simple demo:
+
+```
+supercli import-openapi stripe.json
+```
+
+Then immediately:
+
+```
+supercli stripe customers list
+```
+
+Or:
+
+```
+supercli ask "create a stripe customer"
+```
+
+That would instantly demonstrate the power.
+
+---
+
+If you want, I can also show you a **much more radical idea** that would make SUPERCLI a **new category of tool (not just a CLI)** — something closer to a **"Kubernetes for commands"**.

package/docs/initial/dag.md

@@ -0,0 +1,20 @@
+SUPERCLI (Dynamic CLI) is a config-driven, AI-friendly CLI that dynamically generates commands from cloud configuration and service specifications (OpenAPI, MCP, custom integrations). It is designed for both humans and agents, providing discoverable, introspectable, plannable, and executable commands in a single invocation.
+
+Discoverable — Commands and namespaces can be listed automatically. Agents can query what capabilities exist without prior knowledge.
+
+Introspectable — Every command exposes its inputs, outputs, adapters, and side-effects, allowing agents to understand usage and risk before execution.
+
+Plannable — Execution steps (validation, API calls, transformations, dependencies) are internally computed as a DAG (Directed Acyclic Graph) to ensure correct order and safe handling of dependencies.
+
+Executable — Commands run in one shot; the agent receives deterministic, structured output directly, without requiring a separate execute step.
+
+
+SUPERCLI (Dynamic CLI) is a config-driven, AI-friendly CLI that dynamically generates commands from cloud configuration and service specifications (OpenAPI, MCP, custom integrations). It is designed for both humans and agents, providing discoverable, introspectable, plannable, and executable commands in a single invocation.
+
+Discoverable — Commands and namespaces can be listed automatically. Agents can query what capabilities exist without prior knowledge.
+
+Introspectable — Every command exposes its inputs, outputs, adapters, and side-effects, allowing agents to understand usage and risk before execution.
+
+Plannable — Execution steps (validation, API calls, transformations, dependencies) are internally computed as a DAG (Directed Acyclic Graph) to ensure correct order and safe handling of dependencies.
+
+Executable — Commands run in one shot; the agent receives deterministic, structured output directly, without requiring a separate execute step.

package/docs/initial/description.txt

@@ -0,0 +1,9 @@
+SUPERCLI (Dynamic CLI) is a config-driven, AI-friendly CLI that dynamically generates commands from cloud configuration and service specifications (OpenAPI, MCP, custom integrations). It is designed for both humans and agents, providing discoverable, introspectable, plannable, and executable commands in a single invocation.
+
+Discoverable — Commands and namespaces can be listed automatically. Agents can query what capabilities exist without prior knowledge.
+
+Introspectable — Every command exposes its inputs, outputs, adapters, and side-effects, allowing agents to understand usage and risk before execution.
+
+Plannable — Execution steps (validation, API calls, transformations, dependencies) are internally computed as a DAG (Directed Acyclic Graph) to ensure correct order and safe handling of dependencies.
+
+Executable — Commands run in one shot; the agent receives deterministic, structured output directly, without requiring a separate execute step.