superacli 1.0.0

package/docs/features/adapters.md

@@ -0,0 +1,25 @@
+# Adapters Integration
+
+SUPERCLI acts as a universal frontend proxy that translates semantic commands (e.g., `aws instances list`) into specific backend protocol requests via adapters.
+
+## Key Features
+
+- **HTTP Adapter**: Directly invokes external REST APIs with configured methods, headers, and interpolated path/query parameters.
+- **OpenAPI Adapter**: Given a registered OpenAPI spec URL, maps a SUPERCLI command dynamically to an OpenAPI operation, handling auth and schema resolution on the fly.
+- **MCP Adapter (Model Context Protocol)**: Connects to local or remote MCP servers to trigger their exposed tools. Supports both standard HTTP/SSE connections and spinning up local `stdio` child process execution (like `node server.js`).
+- **Local MCP Registry**: Decouples MCP tool integration from the backend server by maintaining a local `.supercli_cache.json` registry for fast integration.
+
+## Usage
+
+```bash
+# The adapter is chosen when commands are bound. For example MCP management:
+
+# List offline/local MCP servers registered in the config
+supercli mcp list
+
+# Add an offline local MCP stdio server
+supercli mcp add summarize-local --url http://127.0.0.1:8787
+
+# Execute an MCP tool via the bound alias
+supercli ai text summarize --text "Hello world"
+```

package/docs/features/agent-friendly.md

@@ -0,0 +1,28 @@
+# Agent-Friendly Tooling
+
+SUPERCLI is designed from the ground up to be frictionless for AI agents to discover, understand, and interact with infrastructure.
+
+## Key Features
+
+- **Machine-Readable Discovery (`--help-json`)**: Emits the entire capability tree of the CLI in a single nested JSON object, allowing agents to ingest all available namespaces, resources, and actions at once.
+- **Input/Output Schemas (`--schema`)**: Returns JSON schemas for command arguments and expected outputs, giving agents strict contracts.
+- **Token Optimization (`--compact`)**: Compresses verbose JSON payload keys into short aliases (e.g., `namespace` -> `ns`) to save on LLM context windows.
+- **Automatic JSON Envelope (`--json`)**: Wraps all output (success or failure) in a deterministic envelope with metadata like duration and execution command.
+- **Smart Piped Input**: Automatically detects if data is piped via `stdin` and parses JSON into command arguments seamlessly (perfect for chaining workflows).
+- **Separation of Concerns**: Informational logs or human-readable warnings go to `stderr`, while pure data goes to `stdout`, keeping pure JSON piping safe.
+
+## Usage
+
+```bash
+# Get all available commands formatted for agents
+supercli --help-json
+
+# Inspect argument and return schemas for a specific command
+supercli <namespace> <resource> <action> --schema
+
+# Execute a command and get output in compact, token-saving mode
+supercli <namespace> <resource> <action> --compact
+
+# Pipe JSON directly into a command
+echo '{"id": 123}' | supercli <namespace> <resource> <action> --json
+```

package/docs/features/ask.md

@@ -0,0 +1,32 @@
+# Natural Language execution ("ask")
+
+SUPERCLI seamlessly translates natural language intents into execution steps in your infrastructure by mapping user queries directly to your established command capability graph.
+
+## Key Features
+
+- **Decentralized Execution (`SUPERCLI_SERVER` vs Local)**: SUPERCLI can generate natural language execution workflows on the backend server to share API keys across teams, or directly on the individual developer's machine locally using `OPENAI_BASE_URL`.
+- **Automatic Fallback Execution**: The translation produces a DAG workflow JSON. SUPERCLI takes this JSON and runs it sequentially via the standard workflow planner mechanism.
+- **Dynamic Context**: The LLM context is strictly limited to the definitions and JSON schemas of the actual configured commands.
+
+## Setup
+
+Set environment variables on either the local machine (for purely local mode) or the backend server (`server/app.js`):
+
+```bash
+export OPENAI_BASE_URL=https://api.openai.com/v1
+export OPENAI_MODEL=gpt-4
+export OPENAI_API_KEY=sk-...
+```
+
+## Usage
+
+If the feature is enabled (either server-side or locally), it becomes visible in `supercli help`.
+
+```bash
+# Query the system to build and execute a workflow
+supercli ask "list the posts and summarize them"
+
+# Output will stream the execution steps
+# 1. jsonplaceholder posts list 
+# 2. ai text summarize --text="{{step.0.data.summary}}"
+```

package/docs/features/config-sync.md

@@ -0,0 +1,22 @@
+# Configuration Synchronization
+
+SUPERCLI leverages a caching strategy that allows the CLI executable to run blazingly fast while decoupling read operations from needing immediate backend validation.
+
+## Key Features
+
+- **Offline Command Trees**: Upon a synchronization phase, SUPERCLI pulls down the entire state of the backend configuration (commands, actions, MCP servers, OpenAPI specs) into a rapid-access local flat file cache (`.supercli_cache.json`).
+- **Speed Sub-Millisecond Dispatch**: Bypassing HTTP verification checks manually against the server saves precious tokens and network latency. The `help`, `inspect`, and `skills` routing operations become instant.
+- **Independent Execution**: You do not strictly need a running server to perform offline tool execution or registry manipulation (such as adding internal MCP tools natively to the cache).
+
+## Usage
+
+```bash
+# Sync entire backend state locally
+supercli sync
+
+# Inspect local cache statistics (commands stored, cache TTL, mcp servers)
+supercli config show
+
+# Start executing against local registry (network calls defer to MCP providers instead of backend)
+supercli ai text summarize "Offline CLI Mode"
+```

package/docs/features/execution-plans.md

@@ -0,0 +1,25 @@
+# Execution Plans (DAG)
+
+Execution Plans allow SUPERCLI to decouple the intent to execute a command from the actual execution itself. This gives agents (and humans) the ability to dry-run commands, verify correctness, analyze side effects, and explicitly authorize actions.
+
+## Key Features
+
+- **4-Step Directed Acyclic Graph (DAG)**: Computes the precise chain of operations needed to run a command:
+  1. `resolve`: Lookup the command spec and backend adapter configuration.
+  2. `validate`: Run input schema validation.
+  3. `adapter`: Prepare the external request (HTTP, MCP, OpenAPI) based on the input.
+  4. `transform`: Process the raw response into the finalized output format.
+- **Risk Assessment**: Automatically classifies execution intent based on the presence of side-effects (`safe` for reads, `medium` for mutations).
+- **Stateful Short-Lived Plans**: The backend safely stores generated execution plans with unique IDs, locking the execution context so it cannot be tampered with between generation and execution.
+
+## Usage
+
+```bash
+# 1. Generate an execution plan without running the command
+supercli plan <namespace> <resource> <action> --arg1 value
+
+# (Output returns a plan_id and a list of steps)
+
+# 2. Execute the previously created plan
+supercli execute <plan_id>
+```

package/docs/features/observability.md

@@ -0,0 +1,22 @@
+# Observability & Traceability
+
+SUPERCLI maintains a rich audit trail to monitor tool utilization natively, eliminating CLI tooling "blind spots".
+
+## Key Features
+
+- **Job Tracing API (`/api/jobs`)**: Every time the CLI executes a command, it fires an asynchronous job tracking payload via `fetch` to the backend server with its execution parameters (command called, user arguments, duration, risk classification, outcome code).
+- **Historical Analysis**: Administrators can review which endpoints are failing at the network adapter layer, identify slow execution patterns, or audit AI agent behaviors natively.
+- **Dashboard Interface**: The built-in Express `.ejs` UI ships a dedicated `Jobs` dashboard that dynamically visualizes job history and computes basic high-level stats (e.g., success rate).
+
+## Usage
+
+Observability is enabled entirely passively. The CLI client naturally logs its outcome up to the server.
+
+```bash
+# The CLI automatically records this execution trace
+SUPERCLI_SERVER=http://127.0.0.1:3000 supercli github issues list
+
+# The traces can be consumed locally or via REST
+open http://localhost:3000/jobs
+curl http://127.0.0.1:3000/api/jobs/stats
+```

package/docs/features/skills.md

@@ -0,0 +1,25 @@
+# AI Skills Support
+
+SUPERCLI natively integrates a teaching mechanism to empower local LLMs/agents with context about the application's CLI interface.
+
+## Key Features
+
+- **Bootstrapping Skills (`teach`)**: Emits a meta-skill document (in Markdown format compatible with Anthropic/OpenAI instructions) detailing the core architectural design of SUPERCLI and dynamically listing the namespaces and resources available.
+- **Micro-Skills Extraction (`get <cmd>`)**: Automatically pulls a specific SUPERCLI command's capabilities and formats it into a self-contained AI-actionable tool instruction (e.g., Markdown schema).
+- **Embedded DAG Planning**: Optionally injects execution plan information (`--show-dag`) into a skill's document to teach agents how to handle dry-runs for risky operations before execution.
+
+## Usage
+
+```bash
+# List all available capabilities briefly as an index
+supercli skills list --json
+
+# Extract the global knowledge required to teach an agent how SUPERCLI works
+supercli skills teach
+
+# Generate a hyper-specific instruction for an AI agent on how to call a command
+supercli skills get oapi.todos.list
+
+# Same as above, but instruct the AI on execution planning
+supercli skills get oapi.todos.list --show-dag
+```

package/docs/features/storage.md

@@ -0,0 +1,25 @@
+# Pluggable Storage
+
+By default, the backend of SUPERCLI is incredibly lightweight. However, for scaled enterprise deployments, its datastore is fully pluggable.
+
+## Key Features
+
+- **Key-Value Abstraction Layer**: Rather than tying the application to a specific database driver (e.g., MongoDB), SUPERCLI operates strictly against a generic `delete`, `set`, `get`, and `listKeys` interface.
+- **Natural Entity Keys**: Data records internally utilize human-readable string IDs (like `command:namespace.resource.action`) rather than opaque ObjectIDs to improve portability.
+- **Zero-Dependency Native Backend (`FileAdapter`)**: Without MongoDB configured, SUPERCLI defaults to reading and writing `.json` files in a local directory (`./supercli_storage`). This makes local testing completely frictionless and allows backing up configurations natively into Git if desired.
+- **Enterprise Scale (`MongoAdapter`)**: Toggling an environment variable enables MongoDB persistence for shared, concurrent, high-availability deployments.
+
+## Usage
+
+The storage adapter is entirely determined by your environment variables in `.env` or process spawn.
+
+```bash
+# Default behavior (uses FileAdapter producing ./supercli_storage/*.json files)
+npm start
+
+# Enable MongoDB Mode
+export SUPERCLI_USE_MONGO=true
+export MONGO_URL=mongodb://127.0.0.1:27017
+export SUPERCLI_DB=supercli
+npm start
+```

package/docs/features/workflows.md

@@ -0,0 +1,33 @@
+# Multi-Step Workflows
+
+SUPERCLI handles command chaining inherently via Workflow Commands without forcing agents or developers to write complicated shell orchestration.
+
+## Key Features
+
+- **Workflow Adapter Definition**: SUPERCLI represents compound multi-step processes as just another single command in its capability tree (`type: workflow`).
+- **Data Piping (Context Mapping)**: When a workflow command executes, the `stdout` JSON result of step 1 can automatically be injected into the arguments of step 2. This creates clean API mapping layers (e.g., extract an ID from one endpoint, pass it to another).
+- **Atomic Abstraction**: A complex graph of actions is compacted into one deterministic interface that agents discover seamlessly.
+
+## Usage
+
+A workflow is stored as a standard command in the registry, composed of references to other commands:
+
+```json
+{
+  "namespace": "aws",
+  "resource": "instances",
+  "action": "restart_and_log",
+  "type": "workflow",
+  "adapterConfig": {
+    "steps": [
+      { "command": "aws.instances.restart", "args": { "instance_id": "{{args.id}}" } },
+      { "command": "logging.events.publish", "args": { "message": "Instance {{step.0.data.status}} restarted." } }
+    ]
+  }
+}
+```
+
+```bash
+# Executing the workflow command feels completely standard
+supercli aws instances restart_and_log --id i-0123456789
+```