command-cmd 1.0.1 → 1.0.2

package/cmd.js

@@ -11,7 +11,12 @@ export function cmd(message) {
     const inside = match[1].trim();
     if (!inside) continue;
 
-    const obj = { type: undefined, command: undefined, extra: undefined };
+    const obj = {
+      type: undefined,
+      command: undefined,
+      extra: undefined,
+      seq: undefined
+    };
 
     const parts = inside.split(',');
 
@@ -32,6 +37,11 @@ export function cmd(message) {
         obj.command = value;
       } else if (key === 'extra') {
         obj.extra = value;
+      } else if (key === 'seq') {
+        const seq = Number(value);
+        if (Number.isInteger(seq) && seq >= 0) {
+          obj.seq = seq;
+        }
       } else if (!obj.type) {
         obj.type = rawKey.trim();
         obj.command = value;
@@ -54,4 +64,3 @@ export function extractFirstCommand(message) {
   const [first] = cmd(message);
   return first || null;
 }
-

package/doc.md

@@ -0,0 +1,243 @@
+# command-cmd (English Documentation)
+
+`command-cmd` is a lightweight parser for detecting and extracting structured commands from free-form text, especially AI output.
+
+It is useful when a model returns natural language plus command blocks and you need clean structured data for automation.
+
+## 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.
+
+## Installation
+
+```bash
+npm install command-cmd
+```
+
+## Quick start
+
+```js
+import { cmd, extractFirstCommand } from 'command-cmd';
+
+const aiMessage = `
+Run this sequence:
+[type: shell, command: npm test, extra: run from project root, seq: 2]
+`;
+
+const commandList = cmd(aiMessage);
+const firstCommand = extractFirstCommand(aiMessage);
+
+console.log(commandList);
+console.log(firstCommand);
+```
+
+Expected output:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'npm test',
+    extra: 'run from project root',
+    seq: 2
+  }
+]
+
+{
+  type: 'shell',
+  command: 'npm test',
+  extra: 'run from project root',
+  seq: 2
+}
+```
+
+## Full API
+
+### `cmd(message)`
+
+Extracts **all** valid commands from a string.
+
+- 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 `[]`.
+
+A block is returned only when it contains:
+
+- `type` (or `tipo`)
+- `command` (or `comando`)
+
+`seq` rules:
+
+- Optional field.
+- Accepts only integer values greater than or equal to zero.
+- If invalid (for example `seq: many`), it remains `undefined`.
+
+### `extractFirstCommand(message)`
+
+Returns only the first valid command.
+
+- Input: `message` (string).
+- Output: `{ type, command, extra, seq } | null`
+- If no valid command is found: returns `null`.
+
+## Expected command format
+
+Each command must be inside square brackets:
+
+```txt
+[type: value, command: value, extra: value, seq: 3]
+```
+
+Recognized keys:
+
+- `type` or `tipo`
+- `command` or `comando`
+- `extra`
+- `seq`
+
+Key matching is case-insensitive.
+
+Valid examples:
+
+```txt
+[TYPE: shell, COMMAND: ls -la, SEQ: 1]
+[tipo: shell, comando: pwd, seq: 2]
+```
+
+## Parsing rules
+
+- 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.
+
+## Real AI response examples
+
+### Example 1: single command
+
+AI text:
+
+```txt
+To list files:
+[type: shell, command: ls -la, extra: linux or mac, seq: 1]
+```
+
+Result:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'ls -la',
+    extra: 'linux or mac',
+    seq: 1
+  }
+]
+```
+
+### Example 2: multiple commands
+
+AI text:
+
+```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]
+```
+
+Result:
+
+```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 }
+]
+```
+
+### Example 3: invalid `seq`
+
+AI text:
+
+```txt
+[type: shell, command: npm test, seq: three]
+```
+
+Result:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'npm test',
+    extra: undefined,
+    seq: undefined
+  }
+]
+```
+
+## How to build the AI system prompt
+
+Extraction quality depends on stable formatting. The best approach is to force the model to emit valid command blocks.
+
+### Template 1: strict mode (blocks only)
+
+```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>]
+
+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.
+```
+
+### Template 2: explanation + blocks
+
+```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>]
+
+If no command is needed, do not create a block.
+If a command must be repeated, set seq accordingly.
+```
+
+### Example of expected AI answer
+
+```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]
+```
+
+## Current limitations
+
+- 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.
+
+## Security
+
+This library does not execute commands.
+
+If you execute parsed output:
+
+- Use an allowlist of allowed commands.
+- Block dangerous patterns.
+- Require confirmation for destructive operations.

package/docPTBR.md

@@ -0,0 +1,243 @@
+# 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.
+
+Ela e util quando o modelo retorna linguagem natural junto com blocos de comando e voce precisa transformar isso em dados para automacao.
+
+## 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.
+
+## Instalacao
+
+```bash
+npm install command-cmd
+```
+
+## Uso rapido
+
+```js
+import { cmd, extractFirstCommand } from 'command-cmd';
+
+const textoDaIA = `
+Vamos executar em duas etapas:
+[tipo: shell, comando: npm test, extra: executar na raiz do projeto, seq: 2]
+`;
+
+const listaDeComandos = cmd(textoDaIA);
+const primeiroComando = extractFirstCommand(textoDaIA);
+
+console.log(listaDeComandos);
+console.log(primeiroComando);
+```
+
+Saida esperada:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'npm test',
+    extra: 'executar na raiz do projeto',
+    seq: 2
+  }
+]
+
+{
+  type: 'shell',
+  command: 'npm test',
+  extra: 'executar na raiz do projeto',
+  seq: 2
+}
+```
+
+## API completa
+
+### `cmd(message)`
+
+Extrai **todos** os comandos validos de uma string.
+
+- 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 `[]`.
+
+Um comando so entra no resultado quando tem:
+
+- `type` (ou `tipo`)
+- `command` (ou `comando`)
+
+Regras do campo `seq`:
+
+- E opcional.
+- Aceita apenas numero inteiro maior ou igual a zero.
+- Se o valor for invalido (ex.: `seq: duas_vezes`), o campo fica `undefined`.
+
+### `extractFirstCommand(message)`
+
+Retorna apenas o primeiro comando valido.
+
+- Entrada: `message` (string).
+- Saida: `{ type, command, extra, seq } | null`
+- Se nao houver comando valido: retorna `null`.
+
+## Formato esperado dos comandos
+
+Cada comando deve estar entre colchetes:
+
+```txt
+[tipo: valor, comando: valor, extra: valor, seq: 3]
+```
+
+Chaves reconhecidas:
+
+- `type` ou `tipo`
+- `command` ou `comando`
+- `extra`
+- `seq`
+
+A comparacao das chaves e case-insensitive.
+
+Exemplos validos:
+
+```txt
+[TYPE: shell, COMMAND: ls -la, SEQ: 1]
+[tipo: shell, comando: pwd, seq: 2]
+```
+
+## Regras de parsing
+
+- 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.
+
+## Exemplos com respostas de IA
+
+### Exemplo 1: comando unico
+
+Texto da IA:
+
+```txt
+Para listar arquivos:
+[tipo: shell, comando: ls -la, extra: linux ou mac, seq: 1]
+```
+
+Resultado:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'ls -la',
+    extra: 'linux ou mac',
+    seq: 1
+  }
+]
+```
+
+### Exemplo 2: varios comandos
+
+Texto da IA:
+
+```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]
+```
+
+Resultado:
+
+```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 }
+]
+```
+
+### Exemplo 3: `seq` invalido
+
+Texto da IA:
+
+```txt
+[tipo: shell, comando: npm test, seq: tres]
+```
+
+Resultado:
+
+```js
+[
+  {
+    type: 'shell',
+    command: 'npm test',
+    extra: undefined,
+    seq: undefined
+  }
+]
+```
+
+## Como construir o system prompt da IA
+
+A qualidade da extracao depende de um formato estavel. O ideal e forcar o modelo a sempre emitir blocos validos.
+
+### Modelo 1: estrito (somente blocos)
+
+```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>]
+
+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.
+```
+
+### Modelo 2: explicacao + blocos
+
+```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>]
+
+Se nao houver comando, nao invente bloco.
+Se houver repeticao, informe em seq.
+```
+
+### Exemplo de resposta esperada da IA
+
+```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]
+```
+
+## Limitacoes atuais
+
+- 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.
+
+## Seguranca
+
+Esta biblioteca nao executa comandos.
+
+Se voce for executar o resultado extraido:
+
+- Use allowlist de comandos permitidos.
+- Bloqueie padroes perigosos.
+- Exija confirmacao para operacoes destrutivas.

package/package.json

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