command-cmd 1.0.2 → 1.0.5

package/docPTBR.md

@@ -1,19 +1,14 @@
 # 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`
+- `initMap`
+- `initDoc`
 
 ## Instalacao
 
@@ -21,223 +16,375 @@ 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,
+  initMap as iniciarMap,
+  initDoc as iniciarDoc
+} from 'command-cmd';
+```
+
+## 1) `cmd(message)`
+
+Extrai blocos de comando de um texto.
 
-const textoDaIA = `
-Vamos executar em duas etapas:
-[tipo: shell, comando: npm test, extra: executar na raiz do projeto, seq: 2]
-`;
+Formato aceito:
 
-const listaDeComandos = cmd(textoDaIA);
-const primeiroComando = extractFirstCommand(textoDaIA);
+```txt
+[tipo: abrir_app, comando: tiktok, botao: barra_pesquisa, seq: 1]
+```
+
+Para movimento sequencial:
 
-console.log(listaDeComandos);
-console.log(primeiroComando);
+```txt
+[mover_sequencia, points: 120x220|420x260|800x300, interval: 300, click: between, doubleClick: true]
 ```
 
-Saida esperada:
+Tambem aceita o formato curto que voce pediu:
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: 'executar na raiz do projeto',
-    seq: 2
-  }
-]
+```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,
+  key,
+  modifiers,
+  text,
+  typeDelay,
+  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`
+- `key` ou `tecla` (para `key_tap`)
+- `modifiers` ou `modificadores` (ex.: `command+shift`)
+- `text` ou `texto` (para `type_string_delayed`)
+- `typeDelay` ou `typingDelay` (ms por caractere na digitacao)
+- `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`.
+## 4) `initMap(options?)`
 
-## Formato esperado dos comandos
+Cria (ou carrega/mescla) o `map.json` de forma explicita.
 
-Cada comando deve estar entre colchetes:
+Exemplo:
 
-```txt
-[tipo: valor, comando: valor, extra: valor, seq: 3]
+```js
+await iniciarMap();
+await iniciarMap({ mapPath: './config/map.json' });
 ```
 
-Chaves reconhecidas:
+Campos opcionais:
 
-- `type` ou `tipo`
-- `command` ou `comando`
-- `extra`
-- `seq`
+- `mapPath`
+- `createMapIfMissing`
+- `persistMap`
+- `apps`
+- `defaultClosePoint`
+- `skipAdsPoint`
+- `persistMerged` (salva defaults mesclados mesmo se o map ja existir)
 
-A comparacao das chaves e case-insensitive.
+## 5) `initDoc(options?)`
 
-Exemplos validos:
+Cria os arquivos de documentacao usando os templates do pacote.
 
-```txt
-[TYPE: shell, COMMAND: ls -la, SEQ: 1]
-[tipo: shell, comando: pwd, seq: 2]
+Por padrao, escreve no diretório atual:
+
+- `doc.md`
+- `docPTBR.md`
+- `map.md`
+- `mapPTBR.md`
+
+Exemplo:
+
+```js
+await iniciarDoc();
+await iniciarDoc({ outputDir: './docs', overwrite: true, includeMapDocs: false });
 ```
 
-## Regras de parsing
+Campos opcionais:
 
-- 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.
+- `outputDir` (alias: `dir`, `path`)
+- `overwrite`
+- `includeMapDocs`
+- `files` (ex.: `['doc', 'docPTBR', 'map', 'mapPTBR']`)
 
-## Exemplos com respostas de IA
+### Nome dos apps e botoes (importante)
 
-### Exemplo 1: comando unico
+Voce pode chamar apps e botoes como quiser.
 
-Texto da IA:
+A lib usa o nome apenas para buscar no `map.json`, aplicando normalizacao:
 
-```txt
-Para listar arquivos:
-[tipo: shell, comando: ls -la, extra: linux ou mac, seq: 1]
-```
+- ignora maiusculas/minusculas;
+- converte espaco/hifen para `_`;
+- remove acentos.
+
+Exemplos que viram a mesma chave logica:
 
-Resultado:
+- `Pular ADS`
+- `pular-ads`
+- `pular_ads`
+
+O mesmo vale para nome de app:
+
+- `Tik Tok`
+- `tik-tok`
+- `tik_tok`
+
+Exemplo com objeto em PT-BR:
 
 ```js
-[
-  {
-    type: 'shell',
-    command: 'ls -la',
-    extra: 'linux ou mac',
-    seq: 1
-  }
-]
+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);
 ```
 
-### Exemplo 2: varios comandos
+## Estado de app (aberto/fechado)
 
-Texto da IA:
+Para comandos de app (`abrir_app`, `close_app`), a lib usa `map.json`:
 
-```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]
-```
+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`.
 
-Resultado:
+Obs.: `abrir_app/open_app` sempre dispara `robot.keyTap("command")` antes do fluxo do app.
+
+### Criacao automatica do `map.json`
+
+Se o arquivo `map.json` nao existir, a lib cria automaticamente na raiz do projeto (cwd), por padrao.
+
+Tambem da para criar explicitamente antes das automacoes:
 
 ```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 }
-]
+await iniciarMap();
 ```
 
-### Exemplo 3: `seq` invalido
+Esse arquivo inicial ja vem com:
+
+- `state` em cada app;
+- `buttons` em cada app;
+- botao `fechar` padrao em cada app (`setState: "fechado"`).
+
+Isso permite cenarios como:
 
-Texto da IA:
+- "clique na barra de pesquisa do TikTok"
+- "clique no botao de pular anuncio do YouTube"
+
+A IA pode converter para:
 
 ```txt
-[tipo: shell, comando: npm test, seq: tres]
+[abrir_app, comando: tiktok, botao: barra_pesquisa]
+[abrir_app, comando: youtube, botao: pularADS]
 ```
 
-Resultado:
+## Comandos de `type` suportados
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: undefined,
-    seq: undefined
-  }
-]
+- `abrir_app` / `open_app`
+- `fechar_app` / `close_app`
+- `click` / `clicar`
+- `double_click` / `clique_duplo`
+- `scroll` / `rolar`
+- `mover_sequencia` / `move_sequence`
+- `skip_ads` / `pular_ads`
+- `key_tap` / `tecla`
+- `type_string_delayed` / `digitar`
+
+## Teclado e digitacao
+
+Atalho simples:
+
+```txt
+[key_tap, key: enter]
 ```
 
-## Como construir o system prompt da IA
+Atalho com modificador:
 
-A qualidade da extracao depende de um formato estavel. O ideal e forcar o modelo a sempre emitir blocos validos.
+```txt
+[key_tap, key: v, modifiers: command]
+```
 
-### Modelo 1: estrito (somente blocos)
+Digitando devagar:
 
 ```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>]
+[type_string_delayed, text: Digitando devagar..., typeDelay: 100]
+```
 
-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.
+## Movimento sequencial (novo)
+
+Use `mover_sequencia` para mover o mouse por 2 ou mais coordenadas em ordem.
+
+### Formato de coordenadas
+
+Use `points` no formato:
+
+```txt
+100x200|300x260|640x420
 ```
 
-### Modelo 2: explicacao + blocos
+Tambem funciona com `:`:
 
 ```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>]
+100:200|300:260|640:420
+```
+
+### Controle de clique entre pontos
+
+Campo `click`:
+
+- `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
+
+Campo `doubleClick`:
+
+- `true`: usa clique duplo quando houver clique
+- `false`: clique simples
 
-Se nao houver comando, nao invente bloco.
-Se houver repeticao, informe em seq.
+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]
 ```
 
-### Exemplo de resposta esperada da IA
+Com `clickDelay`:
 
 ```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]
+[mover_sequencia, caminho: 140x260|520x280|980x300, interval: 250, clickDelay: 120, click: between, doubleClick: true]
+```
+
+### Exemplo em objeto JS (mais facil para o dev)
+
+```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
+});
 ```
 
-## Limitacoes atuais
+## Opcoes de `cursor`
 
-- 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.
+```js
+{
+  mapPath: 'map.json',          // caminho do mapeador
+  createMapIfMissing: true,     // padrao: cria map automaticamente se faltar
+  persistMap: true,             // salva estado no arquivo
+  launchKey: 'command',         // usado no fallback de close_app (atalho command+w)
+  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
+}
+```
 
-## Seguranca
+## map.json (doc dedicada)
 
-Esta biblioteca nao executa comandos.
+Voce pediu uma doc dedicada para o mapeador. Ela esta aqui:
+
+- `mapPTBR.md` (PT-BR)
+- `map.md` (English)
+
+Esses arquivos explicam:
+
+- 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>, key: <tecla_opcional>, modifiers: <mods_opcional>, text: <texto_opcional>, typeDelay: <ms_digitacao>, 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.