command-cmd 1.0.4 → 1.0.6

package/cmd.js

@@ -1,8 +1,11 @@
 import fs from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 
-const { readFile, writeFile } = fs.promises;
-const { resolve: resolvePath } = path;
+const { readFile, writeFile, mkdir } = fs.promises;
+const { resolve: resolvePath, dirname: dirnamePath } = path;
+
+const MODULE_DIR = dirnamePath(fileURLToPath(import.meta.url));
 
 const DEFAULT_APPS = Object.freeze({
   spotify: {
@@ -19,6 +22,35 @@ const DEFAULT_APPS = Object.freeze({
   }
 });
 
+const DOC_TEMPLATE_MAP = Object.freeze({
+  doc_en: Object.freeze({
+    key: 'doc_en',
+    source: 'doc.md',
+    target: 'doc.md',
+    isMapDoc: false
+  }),
+  doc_ptbr: Object.freeze({
+    key: 'doc_ptbr',
+    source: 'docPTBR.md',
+    target: 'docPTBR.md',
+    isMapDoc: false
+  }),
+  map_en: Object.freeze({
+    key: 'map_en',
+    source: 'map.md',
+    target: 'map.md',
+    isMapDoc: true
+  }),
+  map_ptbr: Object.freeze({
+    key: 'map_ptbr',
+    source: 'mapPTBR.md',
+    target: 'mapPTBR.md',
+    isMapDoc: true
+  })
+});
+
+const DOC_TEMPLATES = Object.freeze(Object.values(DOC_TEMPLATE_MAP));
+
 const ACTION_ALIASES = Object.freeze({
   skip_ads: 'skip_ads',
   skipads: 'skip_ads',
@@ -45,7 +77,20 @@ const ACTION_ALIASES = Object.freeze({
   close_app: 'close_app',
   closeapp: 'close_app',
   fechar_app: 'close_app',
-  fecharapp: 'close_app'
+  fecharapp: 'close_app',
+  key_tap: 'key_tap',
+  keytap: 'key_tap',
+  tap_key: 'key_tap',
+  tapkey: 'key_tap',
+  press_key: 'key_tap',
+  pressionar_tecla: 'key_tap',
+  tecla: 'key_tap',
+  type_string_delayed: 'type_string_delayed',
+  typestringdelayed: 'type_string_delayed',
+  type_string: 'type_string_delayed',
+  typestring: 'type_string_delayed',
+  digitar: 'type_string_delayed',
+  escrever: 'type_string_delayed'
 });
 
 const BUTTON_ALIASES = Object.freeze({
@@ -84,6 +129,10 @@ const CLICK_MODE = Object.freeze({
 });
 
 let robotCache;
+const MAPER_POLL_INTERVAL = 50;
+let maperInterval = null;
+let maperLastPosition = null;
+let maperPrintedLine = false;
 
 export function cmd(message) {
   if (typeof message !== 'string') {
@@ -103,6 +152,10 @@ export function cmd(message) {
       command: undefined,
       extra: undefined,
       button: undefined,
+      key: undefined,
+      modifiers: undefined,
+      text: undefined,
+      typeDelay: undefined,
       points: undefined,
       path: undefined,
       interval: undefined,
@@ -140,6 +193,42 @@ export function cmd(message) {
         command.extra = value;
       } else if (key === 'button' || key === 'botao' || key === 'botão') {
         command.button = value;
+      } else if (key === 'key' || key === 'tecla' || key === 'hotkey') {
+        command.key = value;
+        if (!command.command) {
+          command.command = value;
+        }
+      } else if (
+        key === 'modifier' ||
+        key === 'modifiers' ||
+        key === 'modificador' ||
+        key === 'modificadores'
+      ) {
+        command.modifiers = value;
+      } else if (
+        key === 'text' ||
+        key === 'texto' ||
+        key === 'string' ||
+        key === 'mensagem'
+      ) {
+        command.text = value;
+        if (!command.command) {
+          command.command = value;
+        }
+      } else if (
+        key === 'typedelay' ||
+        key === 'type_delay' ||
+        key === 'typingdelay' ||
+        key === 'typing_delay' ||
+        key === 'textdelay' ||
+        key === 'delaytexto' ||
+        key === 'delaydigitacao' ||
+        key === 'delaydigitar'
+      ) {
+        const typeDelay = toNonNegativeInteger(value);
+        if (typeDelay !== null) {
+          command.typeDelay = typeDelay;
+        }
       } else if (
         key === 'points' ||
         key === 'pontos' ||
@@ -200,7 +289,7 @@ export function cmd(message) {
       }
     }
 
-    if (command.type && command.command) {
+    if (hasCommandPayload(command)) {
       results.push(command);
     }
   }
@@ -213,6 +302,161 @@ export function extractFirstCommand(message) {
   return first || null;
 }
 
+export async function maper(enabled) {
+  const shouldEnable = parseBooleanValue(enabled);
+  if (shouldEnable === null) {
+    throw new Error('maper_requires_boolean_true_or_false');
+  }
+
+  if (!shouldEnable) {
+    if (maperInterval) {
+      clearInterval(maperInterval);
+      maperInterval = null;
+    }
+
+    maperLastPosition = null;
+
+    if (maperPrintedLine && process.stdout && typeof process.stdout.write === 'function') {
+      process.stdout.write('\n');
+    }
+
+    maperPrintedLine = false;
+    return { active: false, pollInterval: MAPER_POLL_INTERVAL };
+  }
+
+  const robot = await getRobot();
+
+  const printPosition = (position) => {
+    const line = `[maper] x: ${position.x} | y: ${position.y}`;
+
+    if (process.stdout && process.stdout.isTTY && typeof process.stdout.write === 'function') {
+      process.stdout.write(`\r${line}`);
+      maperPrintedLine = true;
+      return;
+    }
+
+    console.log(line);
+  };
+
+  const pollPosition = () => {
+    let position;
+    try {
+      position = robot.getMousePos();
+    } catch (error) {
+      return;
+    }
+
+    if (!position || !Number.isFinite(position.x) || !Number.isFinite(position.y)) {
+      return;
+    }
+
+    if (
+      maperLastPosition &&
+      position.x === maperLastPosition.x &&
+      position.y === maperLastPosition.y
+    ) {
+      return;
+    }
+
+    maperLastPosition = { x: position.x, y: position.y };
+    printPosition(position);
+  };
+
+  if (maperInterval) {
+    return { active: true, pollInterval: MAPER_POLL_INTERVAL };
+  }
+
+  maperLastPosition = null;
+  pollPosition();
+  maperInterval = setInterval(pollPosition, MAPER_POLL_INTERVAL);
+
+  if (typeof maperInterval.unref === 'function') {
+    maperInterval.unref();
+  }
+
+  return { active: true, pollInterval: MAPER_POLL_INTERVAL };
+}
+
+export async function initMap(options = {}) {
+  const config = buildCursorConfig(options);
+  const mapAlreadyExists = await pathExists(config.mapPath);
+  const store = await createMapStore(config);
+
+  const persistMerged =
+    parseBooleanValue(options && options.persistMerged) === true ||
+    parseBooleanValue(options && options.writeMerged) === true;
+
+  if (!mapAlreadyExists && config.persistMap) {
+    // already persisted by createMapStore when file is missing
+  } else if (persistMerged && config.persistMap) {
+    await persistMapStore(store);
+  }
+
+  return {
+    path: store.path,
+    created: !mapAlreadyExists,
+    persisted: (!mapAlreadyExists || persistMerged) && config.persistMap,
+    version: store.map.version,
+    appCount: Object.keys(store.map.apps || {}).length,
+    map: store.map
+  };
+}
+
+export async function initDoc(options = {}) {
+  const raw = options && typeof options === 'object' ? options : {};
+  const outputDir = resolveDocOutputDir(raw);
+  const overwrite = parseBooleanValue(raw.overwrite) === true;
+  const includeMapDocs = shouldIncludeMapDocs(raw.includeMapDocs);
+  const templates = resolveDocTemplates(raw.files, includeMapDocs);
+
+  await mkdir(outputDir, { recursive: true });
+
+  const created = [];
+  const updated = [];
+  const skipped = [];
+
+  for (const template of templates) {
+    const sourcePath = resolvePath(MODULE_DIR, template.source);
+    const targetPath = resolvePath(outputDir, template.target);
+    const targetExists = await pathExists(targetPath);
+
+    if (targetExists && !overwrite) {
+      skipped.push({
+        key: template.key,
+        path: targetPath,
+        reason: 'exists'
+      });
+      continue;
+    }
+
+    let content;
+    try {
+      content = await readFile(sourcePath, 'utf8');
+    } catch (error) {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`doc_template_not_found:${template.source}`);
+      }
+      throw error;
+    }
+
+    await writeFile(targetPath, content, 'utf8');
+
+    if (targetExists) {
+      updated.push({ key: template.key, path: targetPath });
+    } else {
+      created.push({ key: template.key, path: targetPath });
+    }
+  }
+
+  return {
+    outputDir,
+    overwrite,
+    created,
+    updated,
+    skipped
+  };
+}
+
 export async function cursor(input, options = {}) {
   const commands = normalizeCursorInput(input);
   if (commands.length === 0) {
@@ -313,6 +557,10 @@ export async function cursor(input, options = {}) {
           command: command.command,
           extra: command.extra,
           button: command.button,
+          key: command.key,
+          modifiers: command.modifiers,
+          text: command.text,
+          typeDelay: command.typeDelay,
           points: command.points,
           path: command.path,
           interval: command.interval,
@@ -428,6 +676,45 @@ function mergeOptionApps(customApps) {
   return merged;
 }
 
+function toCommandText(value) {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed || '';
+  }
+
+  if (Number.isFinite(value)) {
+    return String(value);
+  }
+
+  return '';
+}
+
+function hasCommandPayload(command) {
+  if (!command || !command.type) {
+    return false;
+  }
+
+  const actionKey = resolveActionKey(command.type);
+
+  if (actionKey === 'key_tap') {
+    return Boolean(toCommandText(command.key) || toCommandText(command.command));
+  }
+
+  if (actionKey === 'type_string_delayed') {
+    return Boolean(
+      toCommandText(command.text) ||
+        toCommandText(command.command) ||
+        toCommandText(command.extra)
+    );
+  }
+
+  if (actionKey === 'move_sequence') {
+    return Boolean(command.points || command.path || toCommandText(command.command));
+  }
+
+  return Boolean(toCommandText(command.command));
+}
+
 function normalizeCommandObject(value) {
   if (!value || typeof value !== 'object') {
     return null;
@@ -435,6 +722,28 @@ function normalizeCommandObject(value) {
 
   const rawType = value.type !== undefined ? value.type : value.tipo;
   const rawCommand = value.command !== undefined ? value.command : value.comando;
+  const rawKey =
+    value.key !== undefined
+      ? value.key
+      : value.tecla !== undefined
+        ? value.tecla
+        : value.hotkey;
+  const rawModifiers =
+    value.modifiers !== undefined
+      ? value.modifiers
+      : value.modifier !== undefined
+        ? value.modifier
+        : value.modificadores !== undefined
+          ? value.modificadores
+          : value.modificador;
+  const rawText =
+    value.text !== undefined
+      ? value.text
+      : value.texto !== undefined
+        ? value.texto
+        : value.string !== undefined
+          ? value.string
+          : value.mensagem;
   const rawButton =
     value.button !== undefined
       ? value.button
@@ -482,37 +791,66 @@ function normalizeCommandObject(value) {
           : value.cliqueDuplo !== undefined
             ? value.cliqueDuplo
             : value.clique_duplo;
+  const rawTypeDelay =
+    value.typeDelay !== undefined
+      ? value.typeDelay
+      : value.type_delay !== undefined
+        ? value.type_delay
+        : value.typingDelay !== undefined
+          ? value.typingDelay
+          : value.typing_delay !== undefined
+            ? value.typing_delay
+            : value.textDelay !== undefined
+              ? value.textDelay
+              : value.delayTexto !== undefined
+                ? value.delayTexto
+                : value.delayDigitacao !== undefined
+                  ? value.delayDigitacao
+                  : value.delayDigitar;
 
   const type =
     typeof rawType === 'string' ? rawType.trim() : String(rawType || '').trim();
+  const actionKey = resolveActionKey(type);
 
   const normalizedPoints = normalizePointsValue(
     rawPoints !== undefined ? rawPoints : rawPath
   );
 
-  let command =
-    typeof rawCommand === 'string'
-      ? rawCommand.trim()
-      : Number.isFinite(rawCommand)
-        ? String(rawCommand)
-        : '';
+  const key = toCommandText(rawKey);
+  const text = toCommandText(rawText);
+
+  let command = toCommandText(rawCommand);
 
   if (!command && normalizedPoints) {
     command = serializePoints(normalizedPoints);
   }
 
-  if (!type || !command) {
-    return null;
+  if (!command && text) {
+    command = text;
+  }
+
+  if (!command && key) {
+    command = key;
+  }
+
+  const extra =
+    value.extra === undefined || value.extra === null
+      ? undefined
+      : toCommandText(value.extra) || String(value.extra);
+
+  if (!command && actionKey === 'type_string_delayed' && extra) {
+    command = extra;
   }
 
   const normalized = {
     type,
     command,
-    extra:
-      value.extra === undefined || value.extra === null
-        ? undefined
-        : String(value.extra),
+    extra,
     button: undefined,
+    key: undefined,
+    modifiers: undefined,
+    text: undefined,
+    typeDelay: undefined,
     points: undefined,
     path: undefined,
     interval: undefined,
@@ -529,6 +867,24 @@ function normalizeCommandObject(value) {
     }
   }
 
+  if (key) {
+    normalized.key = key;
+  }
+
+  const modifiers = parseKeyModifiers(rawModifiers);
+  if (modifiers && modifiers.length > 0) {
+    normalized.modifiers = modifiers;
+  }
+
+  if (text) {
+    normalized.text = text;
+  }
+
+  const typeDelay = toNonNegativeInteger(rawTypeDelay);
+  if (typeDelay !== null) {
+    normalized.typeDelay = typeDelay;
+  }
+
   if (normalizedPoints) {
     normalized.points = normalizedPoints;
     normalized.path = normalizedPoints;
@@ -562,7 +918,7 @@ function normalizeCommandObject(value) {
     normalized.seq = seq;
   }
 
-  return normalized;
+  return hasCommandPayload(normalized) ? normalized : null;
 }
 
 function normalizeCursorInput(input) {
@@ -896,6 +1252,70 @@ function canonicalToken(value) {
     .replace(/[-\s]+/g, '_');
 }
 
+function normalizeKeyTapToken(value) {
+  const token = canonicalToken(value);
+  if (!token) {
+    return undefined;
+  }
+
+  if (
+    token === 'cmd' ||
+    token === 'command' ||
+    token === 'meta' ||
+    token === 'super' ||
+    token === 'win' ||
+    token === 'windows'
+  ) {
+    return 'command';
+  }
+
+  if (token === 'ctrl' || token === 'control' || token === 'ctl') {
+    return 'control';
+  }
+
+  if (token === 'option' || token === 'opt') {
+    return 'alt';
+  }
+
+  if (token === 'spacebar') {
+    return 'space';
+  }
+
+  return token;
+}
+
+function parseKeyModifiers(value) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const list = Array.isArray(value) ? value : [value];
+  const modifiers = [];
+
+  for (const item of list) {
+    if (item === undefined || item === null) {
+      continue;
+    }
+
+    const chunks =
+      typeof item === 'string'
+        ? item.split(/[+|,\s]+/g)
+        : [String(item)];
+
+    for (const chunk of chunks) {
+      const modifier = normalizeKeyTapToken(chunk);
+      if (!modifier) continue;
+      modifiers.push(modifier);
+    }
+  }
+
+  if (modifiers.length === 0) {
+    return undefined;
+  }
+
+  return Array.from(new Set(modifiers));
+}
+
 function resolveActionKey(type) {
   const key = canonicalToken(type);
   return ACTION_ALIASES[key];
@@ -1016,6 +1436,124 @@ function cloneAppMap(app) {
   };
 }
 
+async function pathExists(filePath) {
+  try {
+    await readFile(filePath, 'utf8');
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function shouldIncludeMapDocs(value) {
+  const parsed = parseBooleanValue(value);
+  if (parsed === null) {
+    return value !== false;
+  }
+  return parsed;
+}
+
+function resolveDocTemplateByName(value) {
+  const token = canonicalToken(value);
+  if (!token) {
+    return null;
+  }
+
+  if (
+    token === 'doc' ||
+    token === 'doc_en' ||
+    token === 'docmd' ||
+    token === 'en' ||
+    token === 'english'
+  ) {
+    return DOC_TEMPLATE_MAP.doc_en;
+  }
+
+  if (
+    token === 'doc_ptbr' ||
+    token === 'docptbr' ||
+    token === 'ptbr' ||
+    token === 'pt_br' ||
+    token === 'pt'
+  ) {
+    return DOC_TEMPLATE_MAP.doc_ptbr;
+  }
+
+  if (
+    token === 'map' ||
+    token === 'map_en' ||
+    token === 'mapmd' ||
+    token === 'map_doc' ||
+    token === 'mapdoc'
+  ) {
+    return DOC_TEMPLATE_MAP.map_en;
+  }
+
+  if (
+    token === 'map_ptbr' ||
+    token === 'mapptbr' ||
+    token === 'map_pt' ||
+    token === 'map_ptbr_md'
+  ) {
+    return DOC_TEMPLATE_MAP.map_ptbr;
+  }
+
+  return null;
+}
+
+function resolveDocTemplates(filesOption, includeMapDocs) {
+  const defaultTemplates = includeMapDocs
+    ? DOC_TEMPLATES
+    : DOC_TEMPLATES.filter((template) => !template.isMapDoc);
+
+  if (filesOption === undefined || filesOption === null) {
+    return defaultTemplates;
+  }
+
+  const values = Array.isArray(filesOption) ? filesOption : [filesOption];
+  const selected = [];
+  const invalid = [];
+
+  for (const value of values) {
+    const template = resolveDocTemplateByName(value);
+    if (!template) {
+      invalid.push(String(value));
+      continue;
+    }
+    if (!includeMapDocs && template.isMapDoc) {
+      continue;
+    }
+    if (!selected.find((item) => item.key === template.key)) {
+      selected.push(template);
+    }
+  }
+
+  if (selected.length === 0 && invalid.length > 0) {
+    throw new Error(`invalid_doc_templates:${invalid.join('|')}`);
+  }
+
+  return selected.length > 0 ? selected : defaultTemplates;
+}
+
+function resolveDocOutputDir(options) {
+  const rawOutput =
+    options.outputDir !== undefined
+      ? options.outputDir
+      : options.dir !== undefined
+        ? options.dir
+        : options.path;
+
+  const output = typeof rawOutput === 'string' ? rawOutput.trim() : '';
+  if (!output) {
+    return resolvePath(process.cwd());
+  }
+
+  return resolvePath(output);
+}
+
 function normalizeButtonConfig(rawConfig) {
   if (rawConfig === undefined || rawConfig === null) {
     return null;
@@ -1307,6 +1845,7 @@ async function updateAppState(store, appName, nextState) {
 
 async function persistMapStore(store) {
   if (!store.persistMap) return;
+  await mkdir(dirnamePath(store.path), { recursive: true });
   const serialized = JSON.stringify(store.map, null, 2) + '\n';
   await writeFile(store.path, serialized, 'utf8');
 }
@@ -1420,10 +1959,6 @@ function createActionHandlers(robot, runtime) {
       throw new Error(`missing_launcher:${appName}`);
     }
 
-    if (config.launchKey) {
-      robot.keyTap(config.launchKey);
-    }
-
     if (appConfig.launcher.path) {
       await clickTarget(robot, appConfig.launcher, config);
     } else {
@@ -1499,6 +2034,58 @@ function createActionHandlers(robot, runtime) {
     return config.sequenceDoubleClick;
   }
 
+  async function tapKey(key, modifiers) {
+    if (modifiers && modifiers.length > 0) {
+      robot.keyTap(key, modifiers);
+      return;
+    }
+    robot.keyTap(key);
+  }
+
+  function resolveKeyTapPayload(command) {
+    const key = normalizeKeyTapToken(
+      command.key !== undefined ? command.key : command.command
+    );
+
+    if (!key) {
+      throw new Error('key_tap_requires_key');
+    }
+
+    const modifiers =
+      command.modifiers !== undefined
+        ? parseKeyModifiers(command.modifiers)
+        : parseKeyModifiers(command.extra);
+
+    return {
+      key,
+      modifiers
+    };
+  }
+
+  function resolveTypeStringPayload(command) {
+    const text =
+      command.text !== undefined && command.text !== null
+        ? String(command.text)
+        : command.command !== undefined && command.command !== null
+          ? String(command.command)
+          : command.extra !== undefined && command.extra !== null
+            ? String(command.extra)
+            : '';
+
+    if (!text.trim()) {
+      throw new Error('type_string_delayed_requires_text');
+    }
+
+    const customDelay = toNonNegativeInteger(
+      command.typeDelay !== undefined ? command.typeDelay : command.interval
+    );
+
+    return {
+      text,
+      typeDelay: customDelay !== null ? customDelay : config.typeDelay
+    };
+  }
+
   return {
     async skip_ads(command) {
       let point = config.skipAdsPoint;
@@ -1598,7 +2185,19 @@ function createActionHandlers(robot, runtime) {
       }
     },
 
+    async key_tap(command) {
+      const payload = resolveKeyTapPayload(command);
+      await tapKey(payload.key, payload.modifiers);
+    },
+
+    async type_string_delayed(command) {
+      const payload = resolveTypeStringPayload(command);
+      robot.typeStringDelayed(payload.text, payload.typeDelay);
+    },
+
     async open_app(command) {
+      await tapKey('command');
+
       const mapStore = await getMapStore();
       const appRef = resolveAppInMap(mapStore, command.command);
       if (!appRef.app) {
@@ -1626,7 +2225,12 @@ function createActionHandlers(robot, runtime) {
         if (appRef.app.searchIcon && appRef.app.searchIcon.position) {
           await clickTarget(robot, appRef.app.searchIcon, config);
         }
-        robot.typeStringDelayed(String(command.extra), config.typeDelay);
+
+        const customTypeDelay = toNonNegativeInteger(command.typeDelay);
+        const typeDelay =
+          customTypeDelay !== null ? customTypeDelay : config.typeDelay;
+
+        robot.typeStringDelayed(String(command.extra), typeDelay);
       }
     },
 

package/doc.md

@@ -7,6 +7,9 @@ Exported functions:
 - `cmd`
 - `extractFirstCommand`
 - `cursor`
+- `initMap`
+- `initDoc`
+- `maper`
 
 ## Installation
 
@@ -17,7 +20,7 @@ npm install command-cmd
 ## Import
 
 ```js
-import { cmd, extractFirstCommand, cursor } from 'command-cmd';
+import { cmd, extractFirstCommand, cursor, initMap, initDoc, maper } from 'command-cmd';
 ```
 
 ## 1) `cmd(message)`
@@ -61,7 +64,23 @@ Returns only the first valid command.
 Output:
 
 ```js
-{ type, command, extra, button, points, path, interval, clickDelay, click, doubleClick, seq } | null
+{
+  type,
+  command,
+  extra,
+  button,
+  key,
+  modifiers,
+  text,
+  typeDelay,
+  points,
+  path,
+  interval,
+  clickDelay,
+  click,
+  doubleClick,
+  seq
+} | null
 ```
 
 ## 3) `cursor(input, options?)`
@@ -79,6 +98,10 @@ Accepted object keys:
 - `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)
@@ -88,6 +111,67 @@ Accepted object keys:
 - `seq` or `sequencia`
 - `extra`
 
+## 4) `initMap(options?)`
+
+Creates (or loads/merges) `map.json` explicitly.
+
+Example:
+
+```js
+await initMap();
+await initMap({ mapPath: './config/map.json' });
+```
+
+Optional keys:
+
+- `mapPath`
+- `createMapIfMissing`
+- `persistMap`
+- `apps`
+- `defaultClosePoint`
+- `skipAdsPoint`
+- `persistMerged` (writes merged defaults even when map already exists)
+
+## 5) `initDoc(options?)`
+
+Creates documentation files from package templates.
+
+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 });
+```
+
+Optional keys:
+
+- `outputDir` (alias: `dir`, `path`)
+- `overwrite`
+- `includeMapDocs`
+- `files` (e.g. `['doc', 'docPTBR', 'map', 'mapPTBR']`)
+
+## 6) `maper(enabled)`
+
+Turns terminal mouse position mapping on/off.
+
+- pass `true` to start mapping
+- pass `false` to stop mapping
+- while active, it prints current `x/y` only when mouse position changes
+
+Example:
+
+```js
+await maper(true);  // starts mapper
+await maper(false); // stops mapper
+```
+
 ### App and button names (important)
 
 You can name apps and buttons however you want.
@@ -131,10 +215,18 @@ For app commands (`open_app`, `close_app`), the library uses `map.json`:
 3. Executes mapped button click.
 4. If that button has `setState`, it updates app state in `map.json`.
 
+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
+await initMap();
+```
+
 The generated file includes:
 
 - `state` for each app;
@@ -162,6 +254,28 @@ AI output example:
 - `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]
+```
+
+With modifier:
+
+```txt
+[key_tap, key: v, modifiers: command]
+```
+
+Slow typing:
+
+```txt
+[type_string_delayed, text: Typing slowly..., typeDelay: 100]
+```
 
 ## Sequential movement (new)
 
@@ -236,7 +350,7 @@ await cursor({
   mapPath: 'map.json',
   createMapIfMissing: true,
   persistMap: true,
-  launchKey: 'command', // set false to disable launcher key tap
+  launchKey: 'command', // used by close_app fallback shortcut (command+w)
   moveSteps: 50,
   moveDelay: 8,
   scrollSteps: 10,
@@ -267,7 +381,7 @@ They explain:
 ```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>]
+[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.

package/docPTBR.md

@@ -7,6 +7,9 @@ Funcoes exportadas:
 - `cmd`
 - `extractFirstCommand`
 - `cursor`
+- `initMap`
+- `initDoc`
+- `maper`
 
 ## Instalacao
 
@@ -20,7 +23,10 @@ npm install command-cmd
 import {
   cmd as extrairComandos,
   extractFirstCommand as extrairPrimeiroComando,
-  cursor as executarCursor
+  cursor as executarCursor,
+  initMap as iniciarMap,
+  initDoc as iniciarDoc,
+  maper
 } from 'command-cmd';
 ```
 
@@ -65,7 +71,23 @@ Retorna apenas o primeiro comando valido.
 Saida:
 
 ```js
-{ type, command, extra, button, points, path, interval, clickDelay, click, doubleClick, seq } | null
+{
+  type,
+  command,
+  extra,
+  button,
+  key,
+  modifiers,
+  text,
+  typeDelay,
+  points,
+  path,
+  interval,
+  clickDelay,
+  click,
+  doubleClick,
+  seq
+} | null
 ```
 
 ## 3) `cursor(input, options?)`
@@ -83,6 +105,10 @@ Campos aceitos no objeto:
 - `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)
@@ -92,6 +118,67 @@ Campos aceitos no objeto:
 - `seq` ou `sequencia`
 - `extra`
 
+## 4) `initMap(options?)`
+
+Cria (ou carrega/mescla) o `map.json` de forma explicita.
+
+Exemplo:
+
+```js
+await iniciarMap();
+await iniciarMap({ mapPath: './config/map.json' });
+```
+
+Campos opcionais:
+
+- `mapPath`
+- `createMapIfMissing`
+- `persistMap`
+- `apps`
+- `defaultClosePoint`
+- `skipAdsPoint`
+- `persistMerged` (salva defaults mesclados mesmo se o map ja existir)
+
+## 5) `initDoc(options?)`
+
+Cria os arquivos de documentacao usando os templates do pacote.
+
+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 });
+```
+
+Campos opcionais:
+
+- `outputDir` (alias: `dir`, `path`)
+- `overwrite`
+- `includeMapDocs`
+- `files` (ex.: `['doc', 'docPTBR', 'map', 'mapPTBR']`)
+
+## 6) `maper(enabled)`
+
+Liga/desliga o mapeador de posicao do mouse no terminal.
+
+- passe `true` para ativar
+- passe `false` para desativar
+- enquanto ativo, ele mostra `x/y` apenas quando a posicao muda
+
+Exemplo:
+
+```js
+await maper(true);  // inicia o mapeador
+await maper(false); // encerra o mapeador
+```
+
 ### Nome dos apps e botoes (importante)
 
 Voce pode chamar apps e botoes como quiser.
@@ -135,10 +222,18 @@ Para comandos de app (`abrir_app`, `close_app`), a lib usa `map.json`:
 3. Executa o clique no botao mapeado.
 4. Se o botao tiver `setState`, atualiza o estado no `map.json`.
 
+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
+await iniciarMap();
+```
+
 Esse arquivo inicial ja vem com:
 
 - `state` em cada app;
@@ -166,6 +261,28 @@ A IA pode converter para:
 - `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]
+```
+
+Atalho com modificador:
+
+```txt
+[key_tap, key: v, modifiers: command]
+```
+
+Digitando devagar:
+
+```txt
+[type_string_delayed, text: Digitando devagar..., typeDelay: 100]
+```
 
 ## Movimento sequencial (novo)
 
@@ -240,7 +357,7 @@ await executarCursor({
   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
+  launchKey: 'command',         // usado no fallback de close_app (atalho command+w)
   moveSteps: 50,
   moveDelay: 8,
   scrollSteps: 10,
@@ -272,7 +389,7 @@ Esses arquivos explicam:
 ```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>]
+[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.

package/map.md

@@ -14,6 +14,12 @@ Create `map.json` in your project root (where Node runs).
 
 By default, the library auto-creates this file if it does not exist.
 
+You can also create it explicitly:
+
+```js
+await initMap();
+```
+
 If you need another path:
 
 ```js

package/mapPTBR.md

@@ -14,6 +14,12 @@ 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.
 
+Tambem da para criar explicitamente:
+
+```js
+await initMap();
+```
+
 Se quiser outro caminho, passe em `cursor`:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "command-cmd",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "main": "cmd.js",
   "type": "module",
   "scripts": {