command-cmd 1.0.1 → 1.0.4

package/map.md

@@ -0,0 +1,238 @@
+# map.json (Mapper Guide - English)
+
+This guide explains how to create `map.json` so the library knows:
+
+- where to click to open each app;
+- where app-specific buttons are;
+- current app state (`open` / `closed` or `aberto` / `fechado`).
+
+Note: `move_sequence` does not depend on `map.json`; it uses coordinates from the command payload.
+
+## File location
+
+Create `map.json` in your project root (where Node runs).
+
+By default, the library auto-creates this file if it does not exist.
+
+If you need another path:
+
+```js
+await cursor(commands, { mapPath: './config/map.json' });
+```
+
+## Minimal structure
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "youtube": {
+      "state": "closed",
+      "launcher": { "x": 20, "y": 225 },
+      "buttons": {}
+    }
+  }
+}
+```
+
+Even with minimal setup, the generated default map includes:
+
+- `state`;
+- `buttons`;
+- a default `close/fechar` button per app (`setState: "fechado"`).
+
+## Recommended structure (with buttons)
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "tiktok": {
+      "state": "closed",
+      "launcher": {
+        "position": { "x": 28, "y": 260 },
+        "path": {
+          "points": ["60x740", "140x740", "220x740", "28x260"],
+          "click": "between",
+          "interval": 180,
+          "clickDelay": 120
+        }
+      },
+      "searchIcon": { "x": 612, "y": 138 },
+      "buttons": {
+        "search_bar": { "x": 612, "y": 138 }
+      }
+    },
+    "youtube": {
+      "state": "open",
+      "launcher": { "x": 20, "y": 225 },
+      "searchIcon": { "x": 575, "y": 144 },
+      "buttons": {
+        "skip_ads": { "x": 808, "y": 569 },
+        "close": {
+          "position": { "x": 1888, "y": 16 },
+          "setState": "closed"
+        }
+      }
+    }
+  }
+}
+```
+
+## App fields
+
+- `state`: `open`, `closed`, `aberto`, or `fechado`
+- `launcher`: click point used to open/focus app
+- `searchIcon`: search icon point (optional)
+- `buttons`: per-app button map
+- optional `path/caminho` inside `launcher`: movement route before final click
+
+## Button fields
+
+Simple format:
+
+```json
+"skip_ads": { "x": 808, "y": 569 }
+```
+
+Full format:
+
+```json
+"close": {
+  "position": { "x": 1888, "y": 16 },
+  "setState": "closed"
+}
+```
+
+With path:
+
+```json
+"search_bar": {
+  "position": { "x": 612, "y": 138 },
+  "path": {
+    "points": ["500x140", "560x140", "612x138"],
+    "click": "between",
+    "interval": 150,
+    "clickDelay": 100,
+    "doubleClick": false
+  }
+}
+```
+
+When `setState` is present, the library updates app state in `map.json` after click.
+
+## App and button names
+
+You can name buttons freely in `map.json`.
+
+Same for app names inside `apps`.
+
+Example:
+
+```json
+"buttons": {
+  "my_custom_button": { "x": 500, "y": 300 }
+}
+```
+
+Then call it using:
+
+```txt
+[open_app, command: tiktok, button: my_custom_button]
+```
+
+Lookup uses normalization (case-insensitive, spaces/hyphens to `_`, accent-insensitive).
+
+## Optional `path/caminho` field
+
+You can use `path/caminho` in:
+
+- `apps.<name>.launcher`
+- `apps.<name>.searchIcon`
+- `apps.<name>.buttons.<buttonName>`
+
+Format:
+
+```json
+"path": {
+  "points": ["100x200", "300x260", "640x420"],
+  "click": "between",
+  "interval": 200,
+  "clickDelay": 120,
+  "doubleClick": false
+}
+```
+
+Fields:
+
+- `points`: coordinate sequence
+- `click`: `none`, `between`, `each`, `first`, `last`
+- `interval`: delay between points (ms)
+- `clickDelay`: delay between arriving and clicking at that point (ms)
+- `doubleClick`: whether path clicks are double clicks
+
+Note:
+
+- after the path, the library still performs the final click on `position`.
+
+## How app state is used
+
+Command:
+
+```txt
+[open_app, command: youtube, button: skipADS]
+```
+
+Flow:
+
+1. Reads `apps.youtube.state`.
+2. If already open, it does not open again.
+3. Resolves `buttons.skip_ads` and clicks.
+4. If that button has `setState`, it writes the new state to file.
+
+## AI command examples
+
+```txt
+[open_app, command: tiktok, button: search_bar]
+[open_app, command: youtube, button: skipADS]
+[close_app, command: youtube, button: close]
+```
+
+## Accepted aliases
+
+App:
+
+- `google` -> `chrome`
+
+Button:
+
+- `skipADS` -> `skip_ads`
+- `search`, `search_bar`, `barra_pesquisa` -> same logical key
+- `close`, `fechar` -> `close`/`fechar` mapping
+
+## Quick coordinate calibration
+
+Use this script to read current mouse coordinates:
+
+```js
+import robot from 'robotjs';
+
+setInterval(() => {
+  const p = robot.getMousePos();
+  console.log(`x=${p.x}, y=${p.y}`);
+}, 300);
+```
+
+Move mouse over launcher/buttons and copy values into `map.json`.
+
+## Common errors
+
+- `unknown_app:<name>`: app not found in `map.json`
+- `unknown_button:<app>:<button>`: missing button under `apps.<app>.buttons`
+- `missing_launcher:<app>`: app has no `launcher`
+- `map_not_found:<path>`: map file not found
+
+## Maintenance tip
+
+Keep stable button keys (`search_bar`, `skip_ads`, `close`).  
+If UI changes, update only `map.json`, not your code.

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.1",
+  "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"
+  }
 }