command-cmd 1.0.1 → 1.0.4

package/doc.md

@@ -0,0 +1,285 @@
+# command-cmd (English Documentation)
+
+`command-cmd` parses AI text commands and runs cursor automation through `robotjs`.
+
+Exported functions:
+
+- `cmd`
+- `extractFirstCommand`
+- `cursor`
+
+## Installation
+
+```bash
+npm install command-cmd
+```
+
+## Import
+
+```js
+import { cmd, extractFirstCommand, cursor } from 'command-cmd';
+```
+
+## 1) `cmd(message)`
+
+Extracts command blocks from text.
+
+Accepted format:
+
+```txt
+[type: open_app, command: tiktok, button: search_bar, seq: 1]
+```
+
+For sequential movement:
+
+```txt
+[move_sequence, points: 120x220|420x260|800x300, interval: 300, click: between, doubleClick: true]
+```
+
+Short format is also supported:
+
+```txt
+[open_app, command: tiktok, button: skip_ads]
+```
+
+Returned object:
+
+```js
+{
+  type: 'open_app',
+  command: 'tiktok',
+  extra: undefined,
+  button: 'skip_ads',
+  seq: 1
+}
+```
+
+## 2) `extractFirstCommand(message)`
+
+Returns only the first valid command.
+
+Output:
+
+```js
+{ type, command, extra, button, points, path, interval, clickDelay, click, doubleClick, seq } | null
+```
+
+## 3) `cursor(input, options?)`
+
+Runs mouse/keyboard actions.
+
+`input` can be:
+
+- string (internally parsed with `cmd`)
+- one command object
+- array of command objects
+
+Accepted object keys:
+
+- `type` or `tipo`
+- `command` or `comando`
+- `button` or `botao`
+- `points` or `pontos` (coordinate sequence)
+- `path` or `caminho` or `trajeto` (alias of `points`)
+- `interval` or `intervalo` (ms between points)
+- `clickDelay` or `delayClique` (ms between arriving and click)
+- `click` or `clique` (`none`, `between`, `each`, `first`, `last`)
+- `doubleClick` or `duplo` (true/false)
+- `seq` or `sequencia`
+- `extra`
+
+### App and button names (important)
+
+You can name apps and buttons however you want.
+
+The library uses the name only to resolve keys in `map.json`, with normalization:
+
+- case-insensitive;
+- spaces/hyphens converted to `_`;
+- accents removed.
+
+Examples that resolve to the same logical key:
+
+- `Skip ADS`
+- `skip-ads`
+- `skip_ads`
+
+Same idea for app names:
+
+- `Tik Tok`
+- `tik-tok`
+- `tik_tok`
+
+Example:
+
+```js
+const commands = [
+  { type: 'open_app', command: 'youtube', button: 'search_bar', seq: 1 },
+  { type: 'open_app', command: 'youtube', button: 'skip_ads', seq: 1 }
+];
+
+const runSummary = await cursor(commands);
+console.log(runSummary);
+```
+
+## App state flow (open/closed)
+
+For app commands (`open_app`, `close_app`), the library uses `map.json`:
+
+1. Reads app state (`open` or `closed` / `aberto` or `fechado`).
+2. If already open, it does not open the app again.
+3. Executes mapped button click.
+4. If that button has `setState`, it updates app state in `map.json`.
+
+### Automatic `map.json` creation
+
+If `map.json` does not exist, the library creates it automatically in the project root (cwd) by default.
+
+The generated file includes:
+
+- `state` for each app;
+- `buttons` for each app;
+- a default `fechar/close` button for each app (`setState: "fechado"`).
+
+This supports flows such as:
+
+- "click TikTok search bar"
+- "click YouTube skip ad button"
+
+AI output example:
+
+```txt
+[open_app, command: tiktok, button: search_bar]
+[open_app, command: youtube, button: skip_ads]
+```
+
+## Supported `type` values
+
+- `open_app` / `abrir_app`
+- `close_app` / `fechar_app`
+- `click` / `clicar`
+- `double_click` / `clique_duplo`
+- `scroll` / `rolar`
+- `move_sequence` / `mover_sequencia`
+- `skip_ads` / `pular_ads`
+
+## Sequential movement (new)
+
+Use `move_sequence` to move mouse through 2+ points in order.
+
+### Coordinate format
+
+Use `points` as:
+
+```txt
+100x200|300x260|640x420
+```
+
+`:` is also accepted:
+
+```txt
+100:200|300:260|640:420
+```
+
+### Click behavior between points
+
+`click` field:
+
+- `none`: no click
+- `between`: click every point except the last
+- `each`: click every point
+- `first`: click only the first point
+- `last`: click only the last point
+
+`doubleClick` field:
+
+- `true`: use double click when click is triggered
+- `false`: single click
+
+`clickDelay` field:
+
+- delay (ms) between arriving at a point and clicking that point
+
+### AI text example
+
+```txt
+[move_sequence, points: 140x260|520x280|980x300, interval: 250, click: between, doubleClick: true]
+```
+
+With `clickDelay`:
+
+```txt
+[move_sequence, path: 140x260|520x280|980x300, interval: 250, clickDelay: 120, click: between, doubleClick: true]
+```
+
+### JS object example (recommended for devs)
+
+```js
+await cursor({
+  type: 'move_sequence',
+  points: [
+    { x: 140, y: 260 },
+    { x: 520, y: 280 },
+    { x: 980, y: 300 }
+  ],
+  interval: 250,
+  clickDelay: 120,
+  click: 'between',
+  doubleClick: true
+});
+```
+
+## `cursor` options
+
+```js
+{
+  mapPath: 'map.json',
+  createMapIfMissing: true,
+  persistMap: true,
+  launchKey: 'command', // set false to disable launcher key tap
+  moveSteps: 50,
+  moveDelay: 8,
+  scrollSteps: 10,
+  scrollDelay: 20,
+  typeDelay: 50,
+  sequenceInterval: 250,
+  sequenceClick: 'none',
+  sequenceDoubleClick: false,
+  defaultClosePoint: { x: 1888, y: 16 }
+}
+```
+
+## Dedicated mapper docs
+
+Dedicated docs for creating and calibrating `map.json`:
+
+- `mapPTBR.md` (PT-BR)
+- `map.md` (English)
+
+They explain:
+
+- app mapping and coordinates;
+- per-app button mapping;
+- state management with `setState`.
+
+## Recommended system prompt (AI -> command)
+
+```txt
+You are a technical assistant.
+When you suggest executable actions, output only blocks:
+[type: <type>, command: <app_or_value>, points: <optional_points>, button: <optional_button>, interval: <optional_ms>, clickDelay: <optional_ms_before_click>, click: <optional_mode>, doubleClick: <optional_boolean>, extra: <optional_text>, seq: <optional_integer>]
+
+Rules:
+1. Always use square brackets.
+2. One command per block.
+3. seq must be an integer >= 0.
+4. For app interaction, use type open_app and command with app name.
+5. For UI clicks, fill button using a key that exists in map.json.
+6. For sequential movement, use type move_sequence and points in `xXy|xXy|xXy` format.
+```
+
+## Important notes
+
+- `cursor` requires a desktop environment where `robotjs` works.
+- If `map.json` does not exist and `createMapIfMissing` is `false`, app commands fail.
+- Avoid commas inside `[ ... ]` values because parser splitting uses commas.

package/docPTBR.md

@@ -0,0 +1,290 @@
+# command-cmd (Documentacao PT-BR)
+
+`command-cmd` extrai comandos de texto de IA e executa automacoes com cursor via `robotjs`.
+
+Funcoes exportadas:
+
+- `cmd`
+- `extractFirstCommand`
+- `cursor`
+
+## Instalacao
+
+```bash
+npm install command-cmd
+```
+
+## Importacao (com nomes em PT-BR)
+
+```js
+import {
+  cmd as extrairComandos,
+  extractFirstCommand as extrairPrimeiroComando,
+  cursor as executarCursor
+} from 'command-cmd';
+```
+
+## 1) `cmd(message)`
+
+Extrai blocos de comando de um texto.
+
+Formato aceito:
+
+```txt
+[tipo: abrir_app, comando: tiktok, botao: barra_pesquisa, seq: 1]
+```
+
+Para movimento sequencial:
+
+```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: 'abrir_app',
+  command: 'tiktok',
+  extra: undefined,
+  button: 'pularADS',
+  seq: 1
+}
+```
+
+## 2) `extractFirstCommand(message)`
+
+Retorna apenas o primeiro comando valido.
+
+Saida:
+
+```js
+{ type, command, extra, button, points, path, interval, clickDelay, click, doubleClick, seq } | null
+```
+
+## 3) `cursor(input, options?)`
+
+Executa os comandos com mouse/teclado.
+
+`input` pode ser:
+
+- `string` (a funcao chama `cmd` internamente)
+- objeto unico
+- lista de objetos
+
+Campos aceitos no objeto:
+
+- `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`
+
+### Nome dos apps e botoes (importante)
+
+Voce pode chamar apps e botoes como quiser.
+
+A lib usa o nome apenas para buscar no `map.json`, aplicando normalizacao:
+
+- ignora maiusculas/minusculas;
+- converte espaco/hifen para `_`;
+- remove acentos.
+
+Exemplos que viram a mesma chave logica:
+
+- `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
+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);
+```
+
+## Estado de app (aberto/fechado)
+
+Para comandos de app (`abrir_app`, `close_app`), a lib usa `map.json`:
+
+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`.
+
+### Criacao automatica do `map.json`
+
+Se o arquivo `map.json` nao existir, a lib cria automaticamente na raiz do projeto (cwd), por padrao.
+
+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:
+
+- "clique na barra de pesquisa do TikTok"
+- "clique no botao de pular anuncio do YouTube"
+
+A IA pode converter para:
+
+```txt
+[abrir_app, comando: tiktok, botao: barra_pesquisa]
+[abrir_app, comando: youtube, botao: pularADS]
+```
+
+## Comandos de `type` suportados
+
+- `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)
+
+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
+```
+
+Tambem funciona com `:`:
+
+```txt
+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
+
+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]
+```
+
+Com `clickDelay`:
+
+```txt
+[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
+});
+```
+
+## Opcoes de `cursor`
+
+```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
+}
+```
+
+## map.json (doc dedicada)
+
+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>, 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`.
+```
+
+## Observacoes importantes
+
+- `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.