command-cmd 1.0.2 → 1.0.4

package/mapPTBR.md

@@ -0,0 +1,238 @@
+# map.json (Guia do Mapeador PT-BR)
+
+Este arquivo explica como criar o `map.json` para a lib saber:
+
+- onde clicar para abrir cada app;
+- onde ficam botoes internos de cada app;
+- qual o estado atual do app (`aberto` ou `fechado`).
+
+Obs.: o comando `mover_sequencia` nao depende do `map.json`. Ele usa coordenadas enviadas no proprio comando.
+
+## Onde criar o arquivo
+
+Crie `map.json` na raiz do seu projeto (mesma pasta onde voce roda o Node).
+
+Por padrao, a lib cria esse arquivo automaticamente se ele nao existir.
+
+Se quiser outro caminho, passe em `cursor`:
+
+```js
+await cursor(comandos, { mapPath: './config/map.json' });
+```
+
+## Estrutura minima
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "youtube": {
+      "state": "fechado",
+      "launcher": { "x": 20, "y": 225 },
+      "buttons": {}
+    }
+  }
+}
+```
+
+Mesmo no arquivo minimo, o gerador padrao sempre inclui:
+
+- `state`;
+- `buttons`;
+- botao `fechar` por app (com `setState: "fechado"`).
+
+## Estrutura recomendada (com botoes)
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "tiktok": {
+      "state": "fechado",
+      "launcher": {
+        "position": { "x": 28, "y": 260 },
+        "caminho": {
+          "points": ["60x740", "140x740", "220x740", "28x260"],
+          "click": "between",
+          "interval": 180,
+          "clickDelay": 120
+        }
+      },
+      "searchIcon": { "x": 612, "y": 138 },
+      "buttons": {
+        "barra_pesquisa": { "x": 612, "y": 138 }
+      }
+    },
+    "youtube": {
+      "state": "aberto",
+      "launcher": { "x": 20, "y": 225 },
+      "searchIcon": { "x": 575, "y": 144 },
+      "buttons": {
+        "pular_ads": { "x": 808, "y": 569 },
+        "fechar": {
+          "position": { "x": 1888, "y": 16 },
+          "setState": "fechado"
+        }
+      }
+    }
+  }
+}
+```
+
+## Campos do app
+
+- `state`: `aberto` ou `fechado`
+- `launcher`: ponto para clicar e abrir/focar app
+- `searchIcon`: ponto da lupa/barra de busca (opcional)
+- `buttons`: mapa de botoes do app
+- `caminho` dentro de `launcher` (opcional): rota de pontos antes do clique final no app
+
+## Campos de botao
+
+Formato simples:
+
+```json
+"pular_ads": { "x": 808, "y": 569 }
+```
+
+Formato completo:
+
+```json
+"fechar": {
+  "position": { "x": 1888, "y": 16 },
+  "setState": "fechado"
+}
+```
+
+Com caminho:
+
+```json
+"barra_pesquisa": {
+  "position": { "x": 612, "y": 138 },
+  "caminho": {
+    "points": ["500x140", "560x140", "612x138"],
+    "click": "between",
+    "interval": 150,
+    "clickDelay": 100,
+    "doubleClick": false
+  }
+}
+```
+
+Quando `setState` existe, a lib atualiza o estado do app apos clicar no botao.
+
+## Nome de apps e botoes
+
+Voce pode definir o nome como quiser no `map.json`.
+
+O mesmo vale para nome de app dentro de `apps`.
+
+Exemplo:
+
+```json
+"buttons": {
+  "meu_botao_custom": { "x": 500, "y": 300 }
+}
+```
+
+Depois, a IA ou seu codigo pode chamar:
+
+```txt
+[abrir_app, comando: tiktok, botao: meu_botao_custom]
+```
+
+A busca aplica normalizacao (case-insensitive, troca espaco/hifen por `_`, remove acento).
+
+## Campo `caminho` (opcional)
+
+`caminho` pode ser usado em:
+
+- `apps.<nome>.launcher`
+- `apps.<nome>.searchIcon`
+- `apps.<nome>.buttons.<nomeBotao>`
+
+Formato:
+
+```json
+"caminho": {
+  "points": ["100x200", "300x260", "640x420"],
+  "click": "between",
+  "interval": 200,
+  "clickDelay": 120,
+  "doubleClick": false
+}
+```
+
+Campos:
+
+- `points`: sequencia de coordenadas
+- `click`: `none`, `between`, `each`, `first`, `last`
+- `interval`: delay entre pontos (ms)
+- `clickDelay`: delay entre chegada no ponto e clique (ms)
+- `doubleClick`: se o clique do caminho e duplo
+
+Observacao:
+
+- ao final do caminho, a lib ainda executa o clique final no destino (`position`).
+
+## Como a lib usa o estado
+
+No comando:
+
+```txt
+[abrir_app, comando: youtube, botao: pularADS]
+```
+
+Fluxo:
+
+1. Le `apps.youtube.state`.
+2. Se estiver `aberto`, nao tenta abrir novamente.
+3. Busca `buttons.pular_ads` no mapeador e clica.
+4. Se esse botao tiver `setState`, atualiza o estado no arquivo.
+
+## Exemplo de comandos da IA
+
+```txt
+[abrir_app, comando: tiktok, botao: barra_pesquisa]
+[abrir_app, comando: youtube, botao: pularADS]
+[fechar_app, comando: youtube, botao: fechar]
+```
+
+## Alias aceitos
+
+App:
+
+- `google` -> `chrome`
+
+Botao:
+
+- `pularADS` -> `pular_ads`
+- `search`, `search_bar`, `barra_pesquisa` -> mesma chave logica
+- `close`, `fechar` -> `fechar`
+
+## Calibrando coordenadas (rapido)
+
+Use este script para ler a posicao atual do mouse:
+
+```js
+import robot from 'robotjs';
+
+setInterval(() => {
+  const p = robot.getMousePos();
+  console.log(`x=${p.x}, y=${p.y}`);
+}, 300);
+```
+
+Passe o mouse sobre launcher/botoes e copie os valores para o `map.json`.
+
+## Erros comuns
+
+- `unknown_app:<nome>`: app nao existe em `map.json`.
+- `unknown_button:<app>:<botao>`: botao nao existe em `apps.<app>.buttons`.
+- `missing_launcher:<app>`: faltou `launcher`.
+- `map_not_found:<caminho>`: faltou criar `map.json`.
+
+## Dica de manutencao
+
+- Mantenha nomes de botoes curtos e estaveis (`barra_pesquisa`, `pular_ads`, `fechar`).
+- Se a UI mudar de lugar, atualize apenas o `map.json`, sem mexer no codigo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "command-cmd",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "cmd.js",
   "type": "module",
   "scripts": {
@@ -9,5 +9,8 @@
   "keywords": [],
   "author": "cmstudio",
   "license": "ISC",
-  "description": "Extraia comandos, ótimo para usar com agentes de IA"
+  "description": "Extraia comandos, ótimo para usar com agentes de IA",
+  "dependencies": {
+    "robotjs": "^0.6.0"
+  }
 }