superacli 1.0.0

package/docs/initial/initial-spec.md

@@ -0,0 +1,731 @@
+HUMAN:
+Write down spec for CLI + WebUI for configuration
+
+Tech stack: NodeJS, MongoDB, EJS, TailwindCDN,DaisyUICDN, Vue3CDN (No deps) (modular) (< 500 LOC per file)
+
+AI:
+## 1. Overview
+
+**SUPERCLI** is a **cloud-defined dynamic CLI** whose commands are generated from a central configuration.
+Configuration is managed through a **Web UI** and stored in **MongoDB**.
+
+The CLI runtime loads command definitions from the cloud, caches them locally, and executes commands through adapters such as:
+
+* OpenAPI
+* MCP servers
+* HTTP
+* Custom integrations
+
+---
+
+# 2. System Architecture
+
+```
+          +-------------------+
+          |     Web UI        |
+          | Vue + EJS + TW    |
+          +---------+---------+
+                    |
+                    |
+            REST / RPC API
+                    |
+                    v
+          +-------------------+
+          |   NodeJS Backend  |
+          | config service    |
+          +---------+---------+
+                    |
+                    v
+               MongoDB
+                    |
+                    |
+           CLI fetches config
+                    |
+                    v
+          +-------------------+
+          |      SUPERCLI         |
+          | local runtime     |
+          +-------------------+
+```
+
+---
+
+# 3. Core Concepts
+
+## Command
+
+A command is defined as:
+
+```
+namespace resource action
+```
+
+Example:
+
+```
+referential users fetch
+```
+
+Execution:
+
+```
+supercli referential users fetch --id 42
+```
+
+---
+
+## Adapters
+
+Execution backends.
+
+Supported adapters:
+
+```
+openapi
+mcp
+http
+shell
+custom
+```
+
+---
+
+## Namespaces
+
+Logical grouping.
+
+Examples:
+
+```
+referential
+infra
+billing
+ai
+```
+
+---
+
+# 4. MongoDB Data Model
+
+## commands
+
+```
+{
+  _id,
+  namespace: "referential",
+  resource: "users",
+  action: "fetch",
+
+  description: "Fetch a user",
+
+  adapter: "openapi",
+
+  adapterConfig: {
+      specId: "referential-api",
+      operationId: "getUser"
+  },
+
+  arguments: [
+      {
+        name: "id",
+        type: "string",
+        required: true
+      }
+  ],
+
+  createdAt,
+  updatedAt
+}
+```
+
+---
+
+## openapi_specs
+
+```
+{
+  _id,
+  name: "referential-api",
+  url: "https://api.company.com/openapi.json",
+  auth: "oauth"
+}
+```
+
+---
+
+## mcp_servers
+
+```
+{
+  _id,
+  name: "ai-tools",
+  url: "https://mcp.company.com"
+}
+```
+
+---
+
+## adapters_custom
+
+```
+{
+  _id,
+  name: "deployLambda",
+  type: "node",
+  file: "integrations/deployLambda.js"
+}
+```
+
+---
+
+## settings
+
+```
+{
+  key: "config_version",
+  value: "abc123"
+}
+```
+
+Used for CLI cache invalidation.
+
+---
+
+# 5. CLI Specification
+
+## Binary
+
+```
+supercli
+```
+
+---
+
+## Command Syntax
+
+```
+supercli <namespace> <resource> <action> [args]
+```
+
+Example:
+
+```
+supercli referential users fetch --id 42
+```
+
+---
+
+## Built-in Commands
+
+### help
+
+```
+supercli help
+```
+
+Lists namespaces.
+
+---
+
+### config refresh
+
+```
+supercli config refresh
+```
+
+Forces cache refresh.
+
+---
+
+### config show
+
+```
+supercli config show
+```
+
+Displays current configuration version.
+
+---
+
+# 6. CLI Config Cache
+
+Location:
+
+```
+~/.supercli/config.json
+```
+
+Example:
+
+```
+{
+  version: "abc123",
+  ttl: 3600,
+  fetched_at: 17000000,
+  commands: []
+}
+```
+
+---
+
+## Cache Algorithm
+
+Startup:
+
+```
+if cache.exists():
+    if ttl expired:
+        fetch new config
+else:
+    fetch config
+```
+
+---
+
+# 7. CLI Config Fetch API
+
+### GET
+
+```
+GET /api/config
+```
+
+Response:
+
+```
+{
+  version: "abc123",
+  ttl: 3600,
+  commands: [...]
+}
+```
+
+---
+
+# 8. CLI Execution Flow
+
+Example command:
+
+```
+supercli referential users fetch --id 42
+```
+
+Flow:
+
+1 parse CLI arguments
+
+2 load config
+
+3 find command
+
+```
+referential.users.fetch
+```
+
+4 select adapter
+
+```
+openapi
+```
+
+5 execute adapter
+
+---
+
+# 9. Adapter Interface
+
+NodeJS module interface:
+
+```
+execute(command, args, context)
+```
+
+Example:
+
+```
+module.exports = async function(command, args, ctx) {
+}
+```
+
+---
+
+# 10. OpenAPI Adapter
+
+Responsibilities:
+
+* load spec
+* map operationId
+* build request
+* execute HTTP call
+
+Example mapping:
+
+```
+operationId: getUser
+```
+
+Request:
+
+```
+GET /users/{id}
+```
+
+---
+
+# 11. MCP Adapter
+
+Execution:
+
+```
+POST MCP server tool call
+```
+
+Config example:
+
+```
+{
+  server: "ai-tools",
+  tool: "summarize"
+}
+```
+
+---
+
+# 12. Backend API Specification
+
+## Config
+
+### GET
+
+```
+/api/config
+```
+
+Returns CLI config.
+
+---
+
+## Commands CRUD
+
+### GET
+
+```
+/api/commands
+```
+
+---
+
+### POST
+
+```
+/api/commands
+```
+
+---
+
+### PUT
+
+```
+/api/commands/:id
+```
+
+---
+
+### DELETE
+
+```
+/api/commands/:id
+```
+
+---
+
+## OpenAPI specs
+
+```
+/api/openapi
+```
+
+---
+
+## MCP servers
+
+```
+/api/mcp
+```
+
+---
+
+# 13. Backend Folder Structure
+
+```
+/server
+
+app.js
+
+/routes
+commands.js
+config.js
+openapi.js
+mcp.js
+
+/services
+configService.js
+adapterRegistry.js
+
+/adapters
+openapi.js
+mcp.js
+http.js
+shell.js
+
+/views
+layout.ejs
+commands.ejs
+command-edit.ejs
+openapi.ejs
+mcp.ejs
+
+/public
+/js
+/css
+```
+
+---
+
+# 14. Web UI Specification
+
+Rendered using:
+
+```
+EJS + Vue3 CDN
+Tailwind CDN
+DaisyUI CDN
+```
+
+---
+
+# 15. Web UI Pages
+
+## Dashboard
+
+Shows:
+
+* number of commands
+* namespaces
+* adapters
+
+---
+
+## Commands
+
+List of commands.
+
+Table:
+
+```
+namespace
+resource
+action
+adapter
+description
+```
+
+Actions:
+
+```
+edit
+delete
+```
+
+---
+
+## Command Editor
+
+Fields:
+
+```
+namespace
+resource
+action
+description
+adapter
+adapter config
+arguments
+```
+
+Arguments editor:
+
+```
+name
+type
+required
+```
+
+---
+
+## OpenAPI Specs
+
+List:
+
+```
+name
+url
+auth
+```
+
+Button:
+
+```
+import spec
+```
+
+---
+
+## MCP Servers
+
+List:
+
+```
+name
+url
+```
+
+---
+
+# 16. Vue UI Structure
+
+Single Vue app:
+
+```
+window.app = Vue.createApp({})
+```
+
+Components:
+
+```
+CommandList
+CommandEditor
+SpecList
+MCPList
+```
+
+All inline modules.
+
+---
+
+# 17. Example WebUI Page
+
+```
+/commands
+```
+
+Table:
+
+```
++------------+----------+--------+----------+
+| namespace  | resource | action | adapter  |
++------------+----------+--------+----------+
+| referential| users    | fetch  | openapi  |
+```
+
+Button:
+
+```
+Create command
+```
+
+---
+
+# 18. Security
+
+Authentication optional for v1.
+
+Possible future:
+
+```
+JWT
+API tokens
+```
+
+---
+
+# 19. Config Versioning
+
+Whenever config changes:
+
+```
+settings.config_version++
+```
+
+CLI detects version mismatch and refreshes.
+
+---
+
+# 20. File Size Constraints
+
+All files:
+
+```
+< 500 LOC
+```
+
+Strategy:
+
+* small service modules
+* simple routes
+* lightweight adapters
+
+---
+
+# 21. Example CLI Usage
+
+```
+supercli help
+```
+
+```
+supercli referential
+```
+
+```
+supercli referential users
+```
+
+```
+supercli referential users fetch --id 42
+```
+
+---
+
+# 22. MVP Scope
+
+Included:
+
+* dynamic CLI commands
+* config cloud sync
+* OpenAPI adapter
+* MCP adapter
+* Web UI config
+
+Excluded:
+
+* RBAC
+* workflow engine
+* plugin marketplace
+
+---
+
+# 23. Future Extensions
+
+Potential additions:
+
+* workflow commands
+* CLI auto-complete
+* role-based commands
+* CLI auth profiles
+* SDK generation
+* command analytics
+
+---
+
+If you want, I can also design the **actual Mongo schema + CLI runtime architecture that fits in ~1500 LOC total**, which would make a very clean OSS project.