command-cmd 1.0.2 → 1.0.4

package/docPTBR.md

@@ -1,19 +1,12 @@
 # command-cmd (Documentacao PT-BR)
 
-`command-cmd` e uma biblioteca para detectar e extrair comandos estruturados de texto livre, com foco em respostas de IA.
+`command-cmd` extrai comandos de texto de IA e executa automacoes com cursor via `robotjs`.
 
-Ela e util quando o modelo retorna linguagem natural junto com blocos de comando e voce precisa transformar isso em dados para automacao.
+Funcoes exportadas:
 
-## Para que serve
-
-Use esta biblioteca para:
-
-- Extrair comandos embutidos em respostas de IA.
-- Capturar varios comandos na mesma mensagem.
-- Normalizar saida em um objeto padrao com `type`, `command`, `extra` e `seq`.
-- Interpretar entradas com chaves em ingles e portugues (`type/tipo`, `command/comando`).
-
-Ela **nao executa comandos**. Ela apenas faz parsing.
+- `cmd`
+- `extractFirstCommand`
+- `cursor`
 
 ## Instalacao
 
@@ -21,223 +14,277 @@ Ela **nao executa comandos**. Ela apenas faz parsing.
 npm install command-cmd
 ```
 
-## Uso rapido
+## Importacao (com nomes em PT-BR)
 
 ```js
-import { cmd, extractFirstCommand } from 'command-cmd';
+import {
+  cmd as extrairComandos,
+  extractFirstCommand as extrairPrimeiroComando,
+  cursor as executarCursor
+} from 'command-cmd';
+```
+
+## 1) `cmd(message)`
 
-const textoDaIA = `
-Vamos executar em duas etapas:
-[tipo: shell, comando: npm test, extra: executar na raiz do projeto, seq: 2]
-`;
+Extrai blocos de comando de um texto.
 
-const listaDeComandos = cmd(textoDaIA);
-const primeiroComando = extractFirstCommand(textoDaIA);
+Formato aceito:
 
-console.log(listaDeComandos);
-console.log(primeiroComando);
+```txt
+[tipo: abrir_app, comando: tiktok, botao: barra_pesquisa, seq: 1]
 ```
 
-Saida esperada:
+Para movimento sequencial:
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: 'executar na raiz do projeto',
-    seq: 2
-  }
-]
+```txt
+[mover_sequencia, points: 120x220|420x260|800x300, interval: 300, click: between, doubleClick: true]
+```
 
+Tambem aceita o formato curto que voce pediu:
+
+```txt
+[abrir_app, comando: tiktok, botao: pularADS]
+```
+
+Objeto retornado:
+
+```js
 {
-  type: 'shell',
-  command: 'npm test',
-  extra: 'executar na raiz do projeto',
-  seq: 2
+  type: 'abrir_app',
+  command: 'tiktok',
+  extra: undefined,
+  button: 'pularADS',
+  seq: 1
 }
 ```
 
-## API completa
+## 2) `extractFirstCommand(message)`
 
-### `cmd(message)`
+Retorna apenas o primeiro comando valido.
 
-Extrai **todos** os comandos validos de uma string.
+Saida:
 
-- Entrada: `message` (string).
-- Saida: `Array<{ type: string, command: string, extra?: string, seq?: number }>`
-- Se `message` nao for string: retorna `[]`.
-- Se nenhum comando valido for encontrado: retorna `[]`.
+```js
+{ type, command, extra, button, points, path, interval, clickDelay, click, doubleClick, seq } | null
+```
 
-Um comando so entra no resultado quando tem:
+## 3) `cursor(input, options?)`
 
-- `type` (ou `tipo`)
-- `command` (ou `comando`)
+Executa os comandos com mouse/teclado.
 
-Regras do campo `seq`:
+`input` pode ser:
 
-- E opcional.
-- Aceita apenas numero inteiro maior ou igual a zero.
-- Se o valor for invalido (ex.: `seq: duas_vezes`), o campo fica `undefined`.
+- `string` (a funcao chama `cmd` internamente)
+- objeto unico
+- lista de objetos
 
-### `extractFirstCommand(message)`
+Campos aceitos no objeto:
 
-Retorna apenas o primeiro comando valido.
+- `type` ou `tipo`
+- `command` ou `comando`
+- `button` ou `botao`
+- `points` ou `pontos` (sequencia de coordenadas)
+- `path` ou `caminho` ou `trajeto` (alias de `points`)
+- `interval` ou `intervalo` (ms entre pontos)
+- `clickDelay` ou `delayClique` (ms entre chegada no ponto e clique)
+- `click` ou `clique` (`none`, `between`, `each`, `first`, `last`)
+- `doubleClick` ou `duplo` (true/false)
+- `seq` ou `sequencia`
+- `extra`
 
-- Entrada: `message` (string).
-- Saida: `{ type, command, extra, seq } | null`
-- Se nao houver comando valido: retorna `null`.
+### Nome dos apps e botoes (importante)
 
-## Formato esperado dos comandos
+Voce pode chamar apps e botoes como quiser.
 
-Cada comando deve estar entre colchetes:
+A lib usa o nome apenas para buscar no `map.json`, aplicando normalizacao:
 
-```txt
-[tipo: valor, comando: valor, extra: valor, seq: 3]
-```
+- ignora maiusculas/minusculas;
+- converte espaco/hifen para `_`;
+- remove acentos.
 
-Chaves reconhecidas:
+Exemplos que viram a mesma chave logica:
 
-- `type` ou `tipo`
-- `command` ou `comando`
-- `extra`
-- `seq`
+- `Pular ADS`
+- `pular-ads`
+- `pular_ads`
 
-A comparacao das chaves e case-insensitive.
+O mesmo vale para nome de app:
 
-Exemplos validos:
+- `Tik Tok`
+- `tik-tok`
+- `tik_tok`
 
-```txt
-[TYPE: shell, COMMAND: ls -la, SEQ: 1]
-[tipo: shell, comando: pwd, seq: 2]
+Exemplo com objeto em PT-BR:
+
+```js
+const listaDeComandos = [
+  { tipo: 'abrir_app', comando: 'youtube', botao: 'barra_pesquisa', seq: 1 },
+  { tipo: 'abrir_app', comando: 'youtube', botao: 'pularADS', seq: 1 }
+];
+
+const resumoDeExecucao = await executarCursor(listaDeComandos);
+console.log(resumoDeExecucao);
 ```
 
-## Regras de parsing
+## Estado de app (aberto/fechado)
 
-- A biblioteca procura trechos no formato `[ ... ]`.
-- O conteudo interno e dividido por virgula.
-- Cada parte precisa ter `:` para virar `chave: valor`.
-- Bloco sem `type/tipo` ou `command/comando` e ignorado.
-- `seq` so e aplicado quando for numero inteiro nao negativo.
-- Chaves desconhecidas usam fallback:
-- A primeira chave desconhecida pode virar `type`, e o valor vira `command`.
-- Chaves desconhecidas seguintes podem preencher `extra`, se ainda estiver vazio.
+Para comandos de app (`abrir_app`, `close_app`), a lib usa `map.json`:
 
-## Exemplos com respostas de IA
+1. Le o estado atual do app (`aberto` ou `fechado`).
+2. Se ja estiver `aberto`, nao tenta abrir de novo.
+3. Executa o clique no botao mapeado.
+4. Se o botao tiver `setState`, atualiza o estado no `map.json`.
 
-### Exemplo 1: comando unico
+### Criacao automatica do `map.json`
 
-Texto da IA:
+Se o arquivo `map.json` nao existir, a lib cria automaticamente na raiz do projeto (cwd), por padrao.
 
-```txt
-Para listar arquivos:
-[tipo: shell, comando: ls -la, extra: linux ou mac, seq: 1]
-```
+Esse arquivo inicial ja vem com:
 
-Resultado:
+- `state` em cada app;
+- `buttons` em cada app;
+- botao `fechar` padrao em cada app (`setState: "fechado"`).
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'ls -la',
-    extra: 'linux ou mac',
-    seq: 1
-  }
-]
-```
+Isso permite cenarios como:
 
-### Exemplo 2: varios comandos
+- "clique na barra de pesquisa do TikTok"
+- "clique no botao de pular anuncio do YouTube"
 
-Texto da IA:
+A IA pode converter para:
 
 ```txt
-Passo 1: [tipo: shell, comando: npm install, seq: 1]
-Passo 2: [tipo: shell, comando: npm run dev, extra: porta padrao 3000, seq: 1]
-Passo 3: [tipo: shell, comando: npm test, seq: 3]
+[abrir_app, comando: tiktok, botao: barra_pesquisa]
+[abrir_app, comando: youtube, botao: pularADS]
 ```
 
-Resultado:
+## Comandos de `type` suportados
 
-```js
-[
-  { type: 'shell', command: 'npm install', extra: undefined, seq: 1 },
-  { type: 'shell', command: 'npm run dev', extra: 'porta padrao 3000', seq: 1 },
-  { type: 'shell', command: 'npm test', extra: undefined, seq: 3 }
-]
-```
+- `abrir_app` / `open_app`
+- `fechar_app` / `close_app`
+- `click` / `clicar`
+- `double_click` / `clique_duplo`
+- `scroll` / `rolar`
+- `mover_sequencia` / `move_sequence`
+- `skip_ads` / `pular_ads`
+
+## Movimento sequencial (novo)
 
-### Exemplo 3: `seq` invalido
+Use `mover_sequencia` para mover o mouse por 2 ou mais coordenadas em ordem.
 
-Texto da IA:
+### Formato de coordenadas
+
+Use `points` no formato:
 
 ```txt
-[tipo: shell, comando: npm test, seq: tres]
+100x200|300x260|640x420
 ```
 
-Resultado:
+Tambem funciona com `:`:
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: undefined,
-    seq: undefined
-  }
-]
+```txt
+100:200|300:260|640:420
 ```
 
-## Como construir o system prompt da IA
+### Controle de clique entre pontos
 
-A qualidade da extracao depende de um formato estavel. O ideal e forcar o modelo a sempre emitir blocos validos.
+Campo `click`:
 
-### Modelo 1: estrito (somente blocos)
+- `none`: sem clique
+- `between`: clica em cada ponto antes do ultimo
+- `each`: clica em todos os pontos
+- `first`: clica so no primeiro ponto
+- `last`: clica so no ultimo ponto
 
-```txt
-Voce e um assistente tecnico.
-Sempre que sugerir uma acao executavel, responda usando blocos no formato:
-[tipo: <categoria>, comando: <comando>, extra: <contexto opcional>, seq: <inteiro opcional>]
+Campo `doubleClick`:
 
-Regras obrigatorias:
-1. Use sempre colchetes.
-2. Use as chaves exatamente como: tipo, comando, extra, seq.
-3. seq deve ser inteiro >= 0.
-4. Nao use virgula dentro dos valores.
-5. Um comando por bloco.
+- `true`: usa clique duplo quando houver clique
+- `false`: clique simples
+
+Campo `clickDelay`:
+
+- delay (ms) entre chegada no ponto e clique naquele ponto
+
+### Exemplo em texto da IA
+
+```txt
+[mover_sequencia, points: 140x260|520x280|980x300, interval: 250, click: between, doubleClick: true]
 ```
 
-### Modelo 2: explicacao + blocos
+Com `clickDelay`:
 
 ```txt
-Voce pode explicar em linguagem natural.
-Quando houver comando, inclua um bloco por comando no formato:
-[tipo: <categoria>, comando: <comando>, extra: <contexto opcional>, seq: <inteiro opcional>]
+[mover_sequencia, caminho: 140x260|520x280|980x300, interval: 250, clickDelay: 120, click: between, doubleClick: true]
+```
+
+### Exemplo em objeto JS (mais facil para o dev)
 
-Se nao houver comando, nao invente bloco.
-Se houver repeticao, informe em seq.
+```js
+await executarCursor({
+  tipo: 'mover_sequencia',
+  pontos: [
+    { x: 140, y: 260 },
+    { x: 520, y: 280 },
+    { x: 980, y: 300 }
+  ],
+  intervalo: 250,
+  delayClique: 120,
+  clique: 'between',
+  duplo: true
+});
 ```
 
-### Exemplo de resposta esperada da IA
+## Opcoes de `cursor`
 
-```txt
-Para preparar o ambiente, siga:
-[tipo: shell, comando: npm install, extra: instalar dependencias, seq: 1]
-[tipo: shell, comando: npm test, extra: repetir para validar estabilidade, seq: 3]
+```js
+{
+  mapPath: 'map.json',          // caminho do mapeador
+  createMapIfMissing: true,     // padrao: cria map automaticamente se faltar
+  persistMap: true,             // salva estado no arquivo
+  launchKey: 'command',         // use false para nao disparar tecla de launcher
+  moveSteps: 50,
+  moveDelay: 8,
+  scrollSteps: 10,
+  scrollDelay: 20,
+  typeDelay: 50,
+  sequenceInterval: 250,        // intervalo padrao do mover_sequencia
+  sequenceClick: 'none',        // none|between|each|first|last
+  sequenceDoubleClick: false,   // clique duplo por padrao
+  defaultClosePoint: { x: 1888, y: 16 } // botao "fechar" padrao
+}
 ```
 
-## Limitacoes atuais
+## map.json (doc dedicada)
+
+Voce pediu uma doc dedicada para o mapeador. Ela esta aqui:
 
-- Valores com virgula podem quebrar o parsing porque a divisao interna usa `,`.
-- Colchetes dentro do valor (`[` ou `]`) podem interferir na captura.
-- Apenas um campo `extra` e retornado por bloco.
+- `mapPTBR.md` (PT-BR)
+- `map.md` (English)
 
-## Seguranca
+Esses arquivos explicam:
 
-Esta biblioteca nao executa comandos.
+- como montar `apps`, `buttons` e `state`;
+- como mapear coordenadas;
+- como mapear botoes por app;
+- como usar `setState` para atualizar para `fechado`.
+
+## System prompt recomendado (IA -> comando)
+
+```txt
+Voce e um assistente tecnico.
+Quando sugerir acao executavel, responda apenas com blocos:
+[tipo: <tipo>, comando: <app_ou_valor>, points: <pontos_opcionais>, botao: <botao_opcional>, interval: <ms_opcional>, clickDelay: <ms_ate_click>, click: <modo_opcional>, doubleClick: <boolean_opcional>, extra: <texto_opcional>, seq: <inteiro_opcional>]
+
+Regras:
+1. Use sempre colchetes.
+2. Um comando por bloco.
+3. seq deve ser inteiro >= 0.
+4. Para app, use tipo abrir_app e comando com nome do app.
+5. Quando for clique de elemento de UI, preencha botao com a chave do map.json.
+6. Para movimento sequencial, use tipo mover_sequencia e `points` no formato `xXy|xXy|xXy`.
+```
 
-Se voce for executar o resultado extraido:
+## Observacoes importantes
 
-- Use allowlist de comandos permitidos.
-- Bloqueie padroes perigosos.
-- Exija confirmacao para operacoes destrutivas.
+- `cursor` precisa de ambiente desktop com `robotjs`.
+- Se `map.json` nao existir e `createMapIfMissing` for `false`, comandos de app retornam erro.
+- Evite virgulas dentro dos valores do bloco `[ ... ]`, porque o parser divide por virgula.

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.