superacli 1.0.0

package/docs/initial/initial-spec-details.md

@@ -0,0 +1,726 @@
+Below is a **minimal architecture that fits ~1500 LOC total** while keeping **every file <500 LOC**, modular, and aligned with:
+
+* NodeJS
+* MongoDB (native driver)
+* EJS
+* Vue3 CDN
+* Tailwind CDN
+* DaisyUI CDN
+* zero build tools
+
+The system has **two binaries**:
+
+```
+/server   -> config control plane
+/cli      -> runtime CLI
+```
+
+---
+
+# 1. Project Structure
+
+```
+supercli/
+
+server/
+  app.js
+  db.js
+
+  routes/
+    commands.js
+    config.js
+    specs.js
+    mcp.js
+
+  services/
+    configService.js
+
+  views/
+    layout.ejs
+    commands.ejs
+    command-edit.ejs
+    specs.ejs
+    mcp.ejs
+
+  public/
+    app.js
+
+cli/
+  supercli.js
+  config.js
+  executor.js
+
+  adapters/
+    openapi.js
+    mcp.js
+    http.js
+```
+
+Approx LOC:
+
+```
+server
+app.js                150
+db.js                 30
+routes/*              350
+services/*            200
+views                 200
+public/app.js         150
+
+cli
+supercli.js               150
+config.js             120
+executor.js           120
+adapters/*            200
+```
+
+Total ≈ **1500 LOC**
+
+---
+
+# 2. MongoDB Schema
+
+No ODM.
+
+Collections:
+
+```
+commands
+specs
+mcp
+settings
+```
+
+---
+
+## commands
+
+```
+{
+  _id: ObjectId,
+
+  namespace: "referential",
+  resource: "users",
+  action: "fetch",
+
+  description: "Fetch user",
+
+  adapter: "openapi",
+
+  adapterConfig: {
+    spec: "referential-api",
+    operationId: "getUser"
+  },
+
+  args: [
+    {
+      name: "id",
+      type: "string",
+      required: true
+    }
+  ],
+
+  createdAt: ISODate(),
+  updatedAt: ISODate()
+}
+```
+
+---
+
+## specs
+
+```
+{
+  _id: ObjectId,
+  name: "referential-api",
+  url: "https://api.company.com/openapi.json",
+  auth: "none"
+}
+```
+
+---
+
+## mcp
+
+```
+{
+  _id: ObjectId,
+  name: "ai-tools",
+  url: "https://mcp.company.com"
+}
+```
+
+---
+
+## settings
+
+```
+{
+  key: "config_version",
+  value: "1"
+}
+```
+
+---
+
+# 3. Server Runtime
+
+## server/app.js
+
+Responsibilities:
+
+```
+express server
+view engine
+static assets
+mount routes
+```
+
+Example skeleton:
+
+```javascript
+const express = require("express")
+const path = require("path")
+
+const commands = require("./routes/commands")
+const config = require("./routes/config")
+const specs = require("./routes/specs")
+const mcp = require("./routes/mcp")
+
+const app = express()
+
+app.use(express.json())
+app.use(express.urlencoded({ extended:true }))
+
+app.set("view engine","ejs")
+app.set("views",path.join(__dirname,"views"))
+
+app.use("/static",express.static("public"))
+
+app.use("/api/config",config)
+app.use("/api/commands",commands)
+app.use("/api/specs",specs)
+app.use("/api/mcp",mcp)
+
+app.get("/",(req,res)=>res.redirect("/commands"))
+
+app.listen(3000)
+```
+
+---
+
+# 4. Config Service
+
+Central piece.
+
+## services/configService.js
+
+Responsibilities:
+
+```
+aggregate commands
+attach specs
+return CLI config
+```
+
+Example response:
+
+```
+{
+  version: "12",
+  ttl: 3600,
+  commands: [...]
+}
+```
+
+Pseudo:
+
+```javascript
+async function getCLIConfig(db){
+
+  const commands = await db.collection("commands").find().toArray()
+
+  const version = await db.collection("settings")
+    .findOne({key:"config_version"})
+
+  return {
+    version: version.value,
+    ttl: 3600,
+    commands
+  }
+
+}
+```
+
+---
+
+# 5. CLI Config Endpoint
+
+## GET
+
+```
+/api/config
+```
+
+Response:
+
+```
+{
+  version: "12",
+  ttl: 3600,
+  commands: [...]
+}
+```
+
+---
+
+# 6. CLI Runtime
+
+Binary:
+
+```
+cli/supercli.js
+```
+
+Usage:
+
+```
+supercli <namespace> <resource> <action> [args]
+```
+
+Example:
+
+```
+supercli referential users fetch --id 42
+```
+
+---
+
+# 7. CLI Cache
+
+Location:
+
+```
+~/.supercli/config.json
+```
+
+Structure:
+
+```
+{
+  version: "12",
+  fetchedAt: 1700000,
+  ttl: 3600,
+  commands: [...]
+}
+```
+
+---
+
+## cli/config.js
+
+Responsibilities:
+
+```
+load cache
+check ttl
+fetch remote config
+```
+
+Pseudo:
+
+```javascript
+async function loadConfig(){
+
+  if(cacheExists()){
+    if(ttlValid()){
+      return readCache()
+    }
+  }
+
+  const res = await fetch(SERVER+"/api/config")
+  const cfg = await res.json()
+
+  writeCache(cfg)
+
+  return cfg
+}
+```
+
+---
+
+# 8. CLI Command Parsing
+
+Example input:
+
+```
+supercli referential users fetch --id 42
+```
+
+Parse:
+
+```
+namespace = referential
+resource = users
+action = fetch
+args = { id:42 }
+```
+
+Minimal parser:
+
+```
+process.argv
+```
+
+---
+
+# 9. Command Resolution
+
+Inside CLI:
+
+```
+cmd = config.commands.find(
+ c.namespace==ns &&
+ c.resource==res &&
+ c.action==act
+)
+```
+
+---
+
+# 10. Executor
+
+## cli/executor.js
+
+Responsibilities:
+
+```
+select adapter
+execute command
+```
+
+Example:
+
+```
+switch(adapter)
+```
+
+```
+openapi
+mcp
+http
+```
+
+---
+
+Example:
+
+```javascript
+async function execute(cmd,args){
+
+ if(cmd.adapter==="openapi"){
+   return openapi.execute(cmd,args)
+ }
+
+ if(cmd.adapter==="mcp"){
+   return mcp.execute(cmd,args)
+ }
+
+}
+```
+
+---
+
+# 11. OpenAPI Adapter
+
+## adapters/openapi.js
+
+Responsibilities:
+
+```
+fetch spec
+resolve operation
+build request
+execute
+```
+
+Pseudo:
+
+```
+load spec
+find operationId
+resolve path
+replace params
+call API
+```
+
+Example:
+
+```javascript
+async function execute(cmd,args){
+
+ const spec = await fetchSpec(cmd.adapterConfig.spec)
+
+ const op = findOperation(spec,cmd.adapterConfig.operationId)
+
+ const url = buildUrl(op,args)
+
+ const res = await fetch(url)
+
+ return res.json()
+
+}
+```
+
+---
+
+# 12. MCP Adapter
+
+## adapters/mcp.js
+
+Example request:
+
+```
+POST /tool
+```
+
+Body:
+
+```
+{
+  tool:"summarize",
+  input:{...}
+}
+```
+
+---
+
+# 13. Web UI
+
+Server-rendered using **EJS + Vue CDN**.
+
+Pages:
+
+```
+/commands
+/commands/new
+/specs
+/mcp
+```
+
+---
+
+# 14. layout.ejs
+
+Includes:
+
+```
+tailwind CDN
+daisyUI CDN
+vue CDN
+```
+
+Example:
+
+```
+https://cdn.tailwindcss.com
+https://cdn.jsdelivr.net/npm/daisyui
+https://unpkg.com/vue@3
+```
+
+---
+
+# 15. Commands Page
+
+Table view:
+
+```
+namespace
+resource
+action
+adapter
+```
+
+Example row:
+
+```
+referential users fetch openapi
+```
+
+Buttons:
+
+```
+edit
+delete
+```
+
+---
+
+# 16. Command Editor
+
+Fields:
+
+```
+namespace
+resource
+action
+adapter
+description
+adapterConfig
+args
+```
+
+Args UI:
+
+```
++ add arg
+name
+type
+required
+```
+
+Handled by Vue.
+
+---
+
+# 17. Vue App
+
+Single file:
+
+```
+public/app.js
+```
+
+Example:
+
+```javascript
+const app = Vue.createApp({
+
+  data(){
+    return {
+      commands:[],
+      loading:true
+    }
+  },
+
+  async mounted(){
+    const r = await fetch("/api/commands")
+    this.commands = await r.json()
+    this.loading=false
+  }
+
+})
+
+app.mount("#app")
+```
+
+---
+
+# 18. Config Version Bump
+
+Whenever command/spec/mcp changes:
+
+```
+db.settings.updateOne(
+ {key:"config_version"},
+ {$inc:{value:1}}
+)
+```
+
+This forces CLI refresh.
+
+---
+
+# 19. Example CLI Session
+
+```
+supercli help
+```
+
+Output:
+
+```
+namespaces:
+referential
+ai
+infra
+```
+
+---
+
+```
+supercli referential
+```
+
+```
+resources:
+users
+groups
+```
+
+---
+
+```
+supercli referential users
+```
+
+```
+actions:
+fetch
+list
+create
+```
+
+---
+
+```
+supercli referential users fetch --id 42
+```
+
+Result:
+
+```
+{
+ id:42,
+ name:"Alice"
+}
+```
+
+---
+
+# 20. Key Design Principle
+
+The CLI **knows nothing about commands**.
+
+It only understands:
+
+```
+namespace resource action
+```
+
+Everything else is **data-driven**.
+
+---
+
+# 21. Why This Architecture Works
+
+It creates a **platform primitive**:
+
+```
+cloud defined CLI
+```
+
+Which can orchestrate:
+
+```
+APIs
+AI tools
+infra
+automation
+```
+
+Through a single runtime.
+
+---
+
+If you'd like, I can also show you the **3 killer features that would make this project explode on GitHub (and differentiate it from existing CLIs)**.