command-cmd 1.0.2 → 1.0.5

package/doc.md

@@ -1,19 +1,14 @@
 # command-cmd (English Documentation)
 
-`command-cmd` is a lightweight parser for detecting and extracting structured commands from free-form text, especially AI output.
+`command-cmd` parses AI text commands and runs cursor automation through `robotjs`.
 
-It is useful when a model returns natural language plus command blocks and you need clean structured data for automation.
+Exported functions:
 
-## What it is for
-
-Use this library to:
-
-- Extract commands embedded in AI responses.
-- Capture multiple commands from a single message.
-- Normalize output into a standard object: `type`, `command`, `extra`, and `seq`.
-- Accept both English and Portuguese keys (`type/tipo`, `command/comando`).
-
-It **does not execute commands**. It only parses text.
+- `cmd`
+- `extractFirstCommand`
+- `cursor`
+- `initMap`
+- `initDoc`
 
 ## Installation
 
@@ -21,223 +16,368 @@ It **does not execute commands**. It only parses text.
 npm install command-cmd
 ```
 
-## Quick start
+## Import
 
 ```js
-import { cmd, extractFirstCommand } from 'command-cmd';
+import { cmd, extractFirstCommand, cursor, initMap, initDoc } from 'command-cmd';
+```
+
+## 1) `cmd(message)`
+
+Extracts command blocks from text.
 
-const aiMessage = `
-Run this sequence:
-[type: shell, command: npm test, extra: run from project root, seq: 2]
-`;
+Accepted format:
 
-const commandList = cmd(aiMessage);
-const firstCommand = extractFirstCommand(aiMessage);
+```txt
+[type: open_app, command: tiktok, button: search_bar, seq: 1]
+```
+
+For sequential movement:
 
-console.log(commandList);
-console.log(firstCommand);
+```txt
+[move_sequence, points: 120x220|420x260|800x300, interval: 300, click: between, doubleClick: true]
 ```
 
-Expected output:
+Short format is also supported:
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: 'run from project root',
-    seq: 2
-  }
-]
+```txt
+[open_app, command: tiktok, button: skip_ads]
+```
+
+Returned object:
 
+```js
 {
-  type: 'shell',
-  command: 'npm test',
-  extra: 'run from project root',
-  seq: 2
+  type: 'open_app',
+  command: 'tiktok',
+  extra: undefined,
+  button: 'skip_ads',
+  seq: 1
 }
 ```
 
-## Full API
+## 2) `extractFirstCommand(message)`
 
-### `cmd(message)`
+Returns only the first valid command.
 
-Extracts **all** valid commands from a string.
+Output:
 
-- Input: `message` (string).
-- Output: `Array<{ type: string, command: string, extra?: string, seq?: number }>`
-- If `message` is not a string: returns `[]`.
-- If no valid command is found: returns `[]`.
+```js
+{
+  type,
+  command,
+  extra,
+  button,
+  key,
+  modifiers,
+  text,
+  typeDelay,
+  points,
+  path,
+  interval,
+  clickDelay,
+  click,
+  doubleClick,
+  seq
+} | null
+```
 
-A block is returned only when it contains:
+## 3) `cursor(input, options?)`
 
-- `type` (or `tipo`)
-- `command` (or `comando`)
+Runs mouse/keyboard actions.
 
-`seq` rules:
+`input` can be:
 
-- Optional field.
-- Accepts only integer values greater than or equal to zero.
-- If invalid (for example `seq: many`), it remains `undefined`.
+- string (internally parsed with `cmd`)
+- one command object
+- array of command objects
 
-### `extractFirstCommand(message)`
+Accepted object keys:
 
-Returns only the first valid command.
+- `type` or `tipo`
+- `command` or `comando`
+- `button` or `botao`
+- `key` or `tecla` (for `key_tap`)
+- `modifiers` or `modificadores` (example: `command+shift`)
+- `text` or `texto` (for `type_string_delayed`)
+- `typeDelay` or `typingDelay` (ms per character while typing)
+- `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`
 
-- Input: `message` (string).
-- Output: `{ type, command, extra, seq } | null`
-- If no valid command is found: returns `null`.
+## 4) `initMap(options?)`
 
-## Expected command format
+Creates (or loads/merges) `map.json` explicitly.
 
-Each command must be inside square brackets:
+Example:
 
-```txt
-[type: value, command: value, extra: value, seq: 3]
+```js
+await initMap();
+await initMap({ mapPath: './config/map.json' });
 ```
 
-Recognized keys:
+Optional keys:
 
-- `type` or `tipo`
-- `command` or `comando`
-- `extra`
-- `seq`
+- `mapPath`
+- `createMapIfMissing`
+- `persistMap`
+- `apps`
+- `defaultClosePoint`
+- `skipAdsPoint`
+- `persistMerged` (writes merged defaults even when map already exists)
 
-Key matching is case-insensitive.
+## 5) `initDoc(options?)`
 
-Valid examples:
+Creates documentation files from package templates.
 
-```txt
-[TYPE: shell, COMMAND: ls -la, SEQ: 1]
-[tipo: shell, comando: pwd, seq: 2]
+By default it writes in current working directory:
+
+- `doc.md`
+- `docPTBR.md`
+- `map.md`
+- `mapPTBR.md`
+
+Example:
+
+```js
+await initDoc();
+await initDoc({ outputDir: './docs', overwrite: true, includeMapDocs: false });
 ```
 
-## Parsing rules
+Optional keys:
 
-- The parser searches for `[ ... ]` blocks.
-- Internal content is split by commas.
-- Each segment needs `:` to become `key: value`.
-- Blocks without `type/tipo` or `command/comando` are ignored.
-- `seq` is applied only when it is a non-negative integer.
-- Unknown keys use fallback behavior:
-- The first unknown key may become `type`, and its value becomes `command`.
-- Later unknown keys may fill `extra` if it is still empty.
+- `outputDir` (alias: `dir`, `path`)
+- `overwrite`
+- `includeMapDocs`
+- `files` (e.g. `['doc', 'docPTBR', 'map', 'mapPTBR']`)
 
-## Real AI response examples
+### App and button names (important)
 
-### Example 1: single command
+You can name apps and buttons however you want.
 
-AI text:
+The library uses the name only to resolve keys in `map.json`, with normalization:
 
-```txt
-To list files:
-[type: shell, command: ls -la, extra: linux or mac, seq: 1]
-```
+- case-insensitive;
+- spaces/hyphens converted to `_`;
+- accents removed.
+
+Examples that resolve to the same logical key:
 
-Result:
+- `Skip ADS`
+- `skip-ads`
+- `skip_ads`
+
+Same idea for app names:
+
+- `Tik Tok`
+- `tik-tok`
+- `tik_tok`
+
+Example:
 
 ```js
-[
-  {
-    type: 'shell',
-    command: 'ls -la',
-    extra: 'linux or mac',
-    seq: 1
-  }
-]
+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);
 ```
 
-### Example 2: multiple commands
+## App state flow (open/closed)
 
-AI text:
+For app commands (`open_app`, `close_app`), the library uses `map.json`:
 
-```txt
-Step 1: [type: shell, command: npm install, seq: 1]
-Step 2: [type: shell, command: npm run dev, extra: default port 3000, seq: 1]
-Step 3: [type: shell, command: npm test, seq: 3]
-```
+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`.
 
-Result:
+Note: `open_app/abrir_app` always triggers `robot.keyTap("command")` before app flow.
+
+### Automatic `map.json` creation
+
+If `map.json` does not exist, the library creates it automatically in the project root (cwd) by default.
+
+You can also create it explicitly before any automation:
 
 ```js
-[
-  { type: 'shell', command: 'npm install', extra: undefined, seq: 1 },
-  { type: 'shell', command: 'npm run dev', extra: 'default port 3000', seq: 1 },
-  { type: 'shell', command: 'npm test', extra: undefined, seq: 3 }
-]
+await initMap();
 ```
 
-### Example 3: invalid `seq`
+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:
 
-AI text:
+- "click TikTok search bar"
+- "click YouTube skip ad button"
+
+AI output example:
 
 ```txt
-[type: shell, command: npm test, seq: three]
+[open_app, command: tiktok, button: search_bar]
+[open_app, command: youtube, button: skip_ads]
 ```
 
-Result:
+## Supported `type` values
 
-```js
-[
-  {
-    type: 'shell',
-    command: 'npm test',
-    extra: undefined,
-    seq: undefined
-  }
-]
+- `open_app` / `abrir_app`
+- `close_app` / `fechar_app`
+- `click` / `clicar`
+- `double_click` / `clique_duplo`
+- `scroll` / `rolar`
+- `move_sequence` / `mover_sequencia`
+- `skip_ads` / `pular_ads`
+- `key_tap` / `tecla`
+- `type_string_delayed` / `digitar`
+
+## Keyboard and typing
+
+Single key:
+
+```txt
+[key_tap, key: enter]
 ```
 
-## How to build the AI system prompt
+With modifier:
 
-Extraction quality depends on stable formatting. The best approach is to force the model to emit valid command blocks.
+```txt
+[key_tap, key: v, modifiers: command]
+```
 
-### Template 1: strict mode (blocks only)
+Slow typing:
 
 ```txt
-You are a technical assistant.
-Whenever you suggest an executable action, output blocks in this format:
-[type: <category>, command: <command>, extra: <optional context>, seq: <optional integer>]
+[type_string_delayed, text: Typing slowly..., typeDelay: 100]
+```
 
-Mandatory rules:
-1. Always use square brackets.
-2. Always use keys exactly as: type, command, extra, seq.
-3. seq must be an integer >= 0.
-4. Do not use commas inside values.
-5. One command per block.
+## Sequential movement (new)
+
+Use `move_sequence` to move mouse through 2+ points in order.
+
+### Coordinate format
+
+Use `points` as:
+
+```txt
+100x200|300x260|640x420
 ```
 
-### Template 2: explanation + blocks
+`:` is also accepted:
 
 ```txt
-You can explain in natural language.
-Whenever a command is needed, include one block per command using:
-[type: <category>, command: <command>, extra: <optional context>, seq: <optional integer>]
+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
 
-If no command is needed, do not create a block.
-If a command must be repeated, set seq accordingly.
+`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]
 ```
 
-### Example of expected AI answer
+With `clickDelay`:
 
 ```txt
-To prepare the environment:
-[type: shell, command: npm install, extra: install dependencies, seq: 1]
-[type: shell, command: npm test, extra: repeat for stability check, seq: 3]
+[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
+});
 ```
 
-## Current limitations
+## `cursor` options
 
-- Values containing commas may break parsing because splitting uses `,`.
-- Values containing `[` or `]` may interfere with block matching.
-- Only one `extra` field is returned per block.
+```js
+{
+  mapPath: 'map.json',
+  createMapIfMissing: true,
+  persistMap: true,
+  launchKey: 'command', // used by close_app fallback shortcut (command+w)
+  moveSteps: 50,
+  moveDelay: 8,
+  scrollSteps: 10,
+  scrollDelay: 20,
+  typeDelay: 50,
+  sequenceInterval: 250,
+  sequenceClick: 'none',
+  sequenceDoubleClick: false,
+  defaultClosePoint: { x: 1888, y: 16 }
+}
+```
 
-## Security
+## Dedicated mapper docs
 
-This library does not execute commands.
+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>, key: <optional_key>, modifiers: <optional_modifiers>, text: <optional_text>, typeDelay: <typing_ms>, 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.
+```
 
-If you execute parsed output:
+## Important notes
 
-- Use an allowlist of allowed commands.
-- Block dangerous patterns.
-- Require confirmation for destructive operations.
+- `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.