@igoruehara/canvas-flow 0.1.4 → 0.1.6

package/README.md

@@ -1,15 +1,54 @@
 # Canvas Flow
 
-Canvas Flow roda frontend e backend juntos a partir de um pacote npm.
+Canvas Flow e uma aplicacao web local para criar, testar e executar fluxos de IA multiagente em formato visual. O pacote npm sobe frontend e backend juntos em um unico comando.
+
+Use quando quiser:
+
+- criar automacoes com agentes de IA;
+- conectar prompts, ferramentas, webhooks e documentos;
+- testar fluxos localmente antes de publicar;
+- usar RAG com documentos;
+- expor fluxos por API ou webhook.
+
+## Inicio Rapido
+
+Com Docker, o Canvas Flow sobe MongoDB local automaticamente e abre o navegador:
+
+```bash
+npx @igoruehara/canvas-flow@latest --with-docker --open
+```
+
+Sem Docker, use quando voce ja tem MongoDB local, MongoDB Atlas ou outro Mongo remoto:
+
+```bash
+npx @igoruehara/canvas-flow@latest --open
+```
+
+Na primeira execucao o CLI cria `~/.canvas-flow/config.json`, gera secrets locais e inicia o app em:
+
+```txt
+http://localhost:3333
+```
 
 ## Requisitos
 
 - Node.js 20+
-- Docker Desktop opcional, apenas para subir Mongo/Milvus localmente
+- MongoDB local, MongoDB remoto ou Docker Desktop
+- Docker Desktop opcional para subir MongoDB, Milvus, MinIO e etcd localmente
+
+## O Que Ele Entrega
 
-## Rodar com Docker
+- editor visual para montar fluxos multiagente;
+- execucao local de frontend e API no mesmo processo Node;
+- configuracao de provedores de IA pela UI ou pelo `config.json`;
+- RAG com Milvus/Zilliz ou Azure AI Search;
+- entrada por API, webhook, web widget e canais configurados no app;
+- chaves de API para consumir fluxos publicados;
+- validacao do ambiente com `doctor`.
 
-Este caminho sobe MongoDB local automaticamente e abre o navegador.
+## Rodar Com Docker
+
+Para ambiente local simples, suba MongoDB junto com o Canvas Flow:
 
 ```bash
 npx @igoruehara/canvas-flow@latest --with-docker --open
@@ -32,7 +71,7 @@ npx @igoruehara/canvas-flow@latest infra down
 
 `infra down` para os containers, mas mantem os volumes Docker.
 
-## Rodar sem Docker
+## Rodar Sem Docker
 
 Use este caminho quando voce ja tem MongoDB local, Atlas ou outro Mongo remoto.
 
@@ -74,6 +113,8 @@ No Windows:
 C:\Users\<usuario>\.canvas-flow\config.json
 ```
 
+Esse arquivo guarda porta, MongoDB, tokens e provedores. Nao publique `config.json`: ele contem secrets gerados e chaves de API.
+
 Abrir a config:
 
 ```bash
@@ -86,38 +127,104 @@ Ver o caminho da config:
 npx @igoruehara/canvas-flow@latest config
 ```
 
-Exemplo com OpenAI:
+Ver a config no terminal:
+
+```bash
+npx @igoruehara/canvas-flow@latest config --show
+```
+
+Tambem da para configurar ao iniciar. Esses parametros valem para aquela execucao:
+
+```bash
+npx @igoruehara/canvas-flow@latest --port 3334 --public-url http://localhost:3334 --open
+npx @igoruehara/canvas-flow@latest --config C:\canvas-flow\config.json --open
+npx @igoruehara/canvas-flow@latest --home C:\canvas-flow-data --open
+```
+
+## Campos Principais Do Config
+
+`server`: controla porta, URL publica, Swagger, CORS e abertura do navegador.
+
+```json
+{
+  "server": {
+    "port": 3333,
+    "publicUrl": "http://localhost:3333",
+    "openBrowser": false
+  }
+}
+```
+
+`database`: obrigatorio. Use Mongo local, Mongo do Docker ou MongoDB Atlas.
+
+```json
+{
+  "database": {
+    "mongoUrl": "mongodb://127.0.0.1:27017/canvas_flow"
+  }
+}
+```
+
+`auth`: gerado automaticamente. Mantenha `apiToken`, `jwtSecret` e `mediaProxySecret` privados. `login` e opcional.
+
+```json
+{
+  "auth": {
+    "login": false,
+    "apiToken": "generated-by-canvas-flow-init",
+    "jwtSecret": "generated-by-canvas-flow-init"
+  }
+}
+```
+
+`providers`: opcional. Preencha somente os provedores que vai usar. Sem chave de LLM, fluxos que chamam IA/LLM nao vao executar geracao.
 
 ```json
 {
   "providers": {
     "openai": {
-      "apiKey": "sk-..."
+      "apiKey": "sk-...",
+      "chatModel": "gpt-4o"
+    },
+    "claude": {
+      "apiKey": "",
+      "chatModel": "claude-sonnet-4-6"
+    },
+    "gemini": {
+      "apiKey": "",
+      "chatModel": "gemini-3.5-flash"
     }
   }
 }
 ```
 
-Exemplo com porta customizada:
+Tambem e possivel configurar provedores pela propria aplicacao depois que ela estiver rodando. Nesse caso, a configuracao fica salva no MongoDB.
+
+`providers.milvus`: opcional para RAG com Milvus/Zilliz. Milvus local via Docker pode rodar sem token. Milvus remoto normalmente precisa de `token` ou `username/password`.
 
 ```json
 {
-  "server": {
-    "port": 3334,
-    "publicUrl": "http://localhost:3334"
+  "providers": {
+    "milvus": {
+      "address": "",
+      "token": "",
+      "collectionName": "canvas_flow_docs"
+    }
   }
 }
 ```
 
-Tambem da para usar outro arquivo:
+`providers.azureSearch` e `providers.azureBlob`: opcionais para RAG/arquivos usando Azure AI Search e Azure Blob.
 
-```bash
-npx @igoruehara/canvas-flow@latest --config C:\canvas-flow\config.json --open
-```
+`files`: opcional. Por padrao usa armazenamento local em `./tmp/canvas-flow-documents`. Configure S3 apenas se quiser arquivos em bucket.
 
-Nao publique `config.json`: ele contem tokens e secrets gerados.
+`sqs`: opcional. Ative apenas se quiser filas AWS SQS para transicoes assincronas.
 
-## Validar
+`rateLimit`, `httpBatch` e `agentOps`: opcionais. Ajustam limites de API, timeouts de chamadas HTTP em lote e historico/trace operacional.
+
+`runtime` e `aws`: opcionais. Ajustam timezone, execucao de cron, limites do runtime e regiao AWS.
+
+## Validar Ambiente
 
 ```bash
 npx @igoruehara/canvas-flow@latest doctor
@@ -129,7 +236,28 @@ Sem checar rede/Mongo:
 npx @igoruehara/canvas-flow@latest doctor --offline
 ```
 
-## Instalar globalmente
+Para tratar avisos como erro:
+
+```bash
+npx @igoruehara/canvas-flow@latest doctor --strict
+```
+
+## Comandos Do CLI
+
+```bash
+npx @igoruehara/canvas-flow@latest init
+npx @igoruehara/canvas-flow@latest config
+npx @igoruehara/canvas-flow@latest config --edit
+npx @igoruehara/canvas-flow@latest config --show
+npx @igoruehara/canvas-flow@latest doctor
+npx @igoruehara/canvas-flow@latest infra up
+npx @igoruehara/canvas-flow@latest infra up --full
+npx @igoruehara/canvas-flow@latest infra status
+npx @igoruehara/canvas-flow@latest infra logs
+npx @igoruehara/canvas-flow@latest infra down
+```
+
+## Instalar Globalmente
 
 Opcional:
 
@@ -137,3 +265,9 @@ Opcional:
 npm i -g @igoruehara/canvas-flow
 canvas-flow --with-docker --open
 ```
+
+## Seguranca
+
+- Nao publique `~/.canvas-flow/config.json`.
+- Nao exponha `auth.apiToken`, `jwtSecret`, `mediaProxySecret` ou chaves de provedores.
+- Para uso publico ou producao, revise login, CORS, Swagger, limites de API, armazenamento de arquivos e provedores antes de expor o app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igoruehara/canvas-flow",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Standalone npm launcher for Canvas Flow multi-agent GenAI workflows.",
   "keywords": [
     "IA",