botql 1.0.0

package/Connectors.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * ConnectorRegistry — resolve o nome de uma plataforma (ex: "TELEGRAM")
+ * para o módulo que sabe falar a API real dessa plataforma.
+ *
+ * O registry NÃO tenta cobrir todas as plataformas existentes — só regista
+ * as que o próprio projeto usa, tal como o xlang-modules.json faz para
+ * bibliotecas. Uma plataforma sem entrada dá erro claro, não falha
+ * silenciosa.
+ *
+ * O mapeamento plataforma -> ficheiro vive em Connectors.json (JSON puro,
+ * sem lógica), esta classe é que sabe carregar e instanciar esses ficheiros.
+ */
+class ConnectorRegistry {
+    constructor(registryPathOrObject = path.join(__dirname, 'Connectors.json')) {
+        if (typeof registryPathOrObject === 'string') {
+            this.baseDir = path.dirname(path.resolve(registryPathOrObject));
+            this.registry = { ...require(path.resolve(registryPathOrObject)) };
+        } else {
+            this.baseDir = __dirname;
+            this.registry = { ...registryPathOrObject };
+        }
+        this.cache = new Map();
+    }
+
+    // Regista/substitui uma plataforma em runtime. Aceita:
+    //  - uma função factory: (credential) => connector
+    //  - o caminho (string) para um módulo que exporta essa factory
+    register(platform, moduleOrFactory) {
+        this.registry[platform] = typeof moduleOrFactory === 'function'
+            ? { factory: moduleOrFactory }
+            : moduleOrFactory;
+    }
+
+    resolve(platform, credential) {
+        const entry = this.registry[platform];
+        if (!entry) {
+            throw new Error(
+                `BotQL: nenhum connector registado para a plataforma "${platform}". ` +
+                `Regista-a em Connectors.json ou via registry.register("${platform}", adapter).`
+            );
+        }
+
+        const cacheKey = `${platform}:${credential}`;
+        if (this.cache.has(cacheKey)) return this.cache.get(cacheKey);
+
+        // entry pode ser: string (caminho de módulo), ou { factory } vindo de register().
+        const factory = typeof entry === 'string'
+            ? require(path.resolve(this.baseDir, entry))
+            : entry.factory || require(path.resolve(this.baseDir, entry.module));
+
+        const connector = factory(credential);
+        this.cache.set(cacheKey, connector);
+        return connector;
+    }
+}
+
+/**
+ * Liga um BotQLInterpreter já carregado a esta registry: para cada
+ * CONNECT registado no bot, resolve o connector real e passa a usá-lo
+ * como destino de REPLY / FORWARD TO / SEND TO para essa plataforma.
+ *
+ * Chamadas manuais a onReply/onForward/onSend passadas nas opções do
+ * interpreter continuam a ter prioridade — isto só preenche o que não
+ * foi definido à mão (onReply/onForward/onSend ficam `null` no
+ * interpreter enquanto não forem definidos, ver botql.js).
+ */
+function attachConnectors(interpreter, registry) {
+    const byService = new Map();
+    for (const conn of interpreter.connections) {
+        byService.set(conn.service, registry.resolve(conn.service, conn.credential));
+    }
+
+    const platformConnector = interpreter.platform ? byService.get(interpreter.platform) : null;
+
+    if (!interpreter.onReply) {
+        interpreter.onReply = async ({ target, text, client }) => {
+            const connector = platformConnector || byService.get('ADMIN');
+            if (!connector) return;
+            await connector.send(target || client, text);
+        };
+    }
+
+    if (!interpreter.onForward) {
+        interpreter.onForward = async ({ target, client }) => {
+            if (!platformConnector) return;
+            await platformConnector.send(target, `Encaminhado de ${client}`);
+        };
+    }
+
+    if (!interpreter.onSend) {
+        interpreter.onSend = async ({ target, signal }) => {
+            const connector = byService.get(target);
+            if (!connector) return;
+            await connector.send(target, JSON.stringify(signal));
+        };
+    }
+
+    return interpreter;
+}
+
+module.exports = { ConnectorRegistry, attachConnectors };

package/Database.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+* Database.js — Camada de banco de dados do BotQL
+*
+* Qualquer adapter aqui implementa a mesma interface, usada pelo botql.js:
+*   createTable(name, columns, preventDefault)
+*   insert(table, columnNames, values) -> id
+*   update(table, column, value, whereColumn, whereValue)
+*   getRows(table) -> array de linhas
+*
+* MemoryDatabase: guarda tudo em memória, sem persistência — bom para
+* testes e para o exemplo do botql.js.
+*
+* SQLiteDatabase: persiste num ficheiro .sqlite real, usando o módulo
+* nativo `node:sqlite` (Node 22+), sem dependências externas.
+*/
+
+const CONTEXT_SCHEMA = [
+{ name: 'id', columnType: 'INT', constraints: ['PRIMARY', 'KEY', 'AUTO_INCREMENT'] },
+{ name: 'client', columnType: 'TEXT', constraints: [] },
+{ name: 'message', columnType: 'TEXT', constraints: [] },
+{ name: 'reply', columnType: 'TEXT', constraints: [] },
+{ name: 'created_at', columnType: 'DATETIME', constraints: [] }
+];
+
+// ===== MemoryDatabase =====
+
+class MemoryDatabase {
+constructor() {
+this.tables = new Map();
+this.autoIncrement = new Map();
+}
+
+createTable(name, columns, preventDefault) {
+const resolvedColumns = (name === 'Context' && columns.length === 0)
+? CONTEXT_SCHEMA
+: columns;
+
+if (this.tables.has(name)) {
+if (preventDefault) return;
+throw new Error(`runtime error: table "${name}" already exists`);
+}
+
+this.tables.set(name, { columns: resolvedColumns, rows: [] });
+this.autoIncrement.set(name, 0);
+}
+
+insert(table, columnNames, values) {
+const t = this.tables.get(table);
+if (!t) throw new Error(`runtime error: table "${table}" does not exist`);
+
+const nextId = this.autoIncrement.get(table) + 1;
+this.autoIncrement.set(table, nextId);
+
+const row = { id: nextId };
+columnNames.forEach((col, i) => { row[col] = values[i]; });
+t.rows.push(row);
+
+return nextId;
+}
+
+update(table, column, value, whereColumn, whereValue) {
+const t = this.tables.get(table);
+if (!t) throw new Error(`runtime error: table "${table}" does not exist`);
+
+const row = whereColumn
+? t.rows.find((r) => r[whereColumn] === whereValue)
+: t.rows[t.rows.length - 1];
+
+if (row) row[column] = value;
+return row || null;
+}
+
+getRows(table) {
+const t = this.tables.get(table);
+return t ? t.rows.slice() : [];
+}
+}
+
+// ===== SQLiteDatabase =====
+
+function mapColumnType(columnType) {
+const type = (columnType || '').toUpperCase();
+if (type === 'INT' || type === 'INTEGER') return 'INTEGER';
+if (type === 'DATETIME' || type === 'DATE') return 'TEXT';
+return 'TEXT';
+}
+
+function buildColumnDef(col) {
+const type = mapColumnType(col.columnType);
+const isPrimary = col.constraints.includes('PRIMARY') && col.constraints.includes('KEY');
+const isAutoIncrement = col.constraints.includes('AUTO_INCREMENT');
+
+let def = `${col.name} ${type}`;
+if (isPrimary) def += ' PRIMARY KEY';
+if (isPrimary && isAutoIncrement) def += ' AUTOINCREMENT';
+return def;
+}
+
+class SQLiteDatabase {
+/**
+* @param {string} filePath Caminho do ficheiro .sqlite, ou ":memory:" para um banco temporário.
+*/
+constructor(filePath = ':memory:') {
+const { DatabaseSync } = require('node:sqlite');
+this.driver = new DatabaseSync(filePath);
+}
+
+createTable(name, columns, preventDefault) {
+const resolvedColumns = (name === 'Context' && columns.length === 0)
+? CONTEXT_SCHEMA
+: columns;
+
+const columnDefs = resolvedColumns.map(buildColumnDef).join(', ');
+const ifNotExists = preventDefault ? 'IF NOT EXISTS ' : '';
+this.driver.exec(`CREATE TABLE ${ifNotExists}${name} (${columnDefs})`);
+}
+
+insert(table, columnNames, values) {
+const placeholders = columnNames.map(() => '?').join(', ');
+const sql = `INSERT INTO ${table} (${columnNames.join(', ')}) VALUES (${placeholders})`;
+const info = this.driver.prepare(sql).run(...values);
+return Number(info.lastInsertRowid);
+}
+
+update(table, column, value, whereColumn, whereValue) {
+if (whereColumn) {
+const sql = `UPDATE ${table} SET ${column} = ? WHERE ${whereColumn} = ?`;
+this.driver.prepare(sql).run(value, whereValue);
+} else {
+const sql = `UPDATE ${table} SET ${column} = ? WHERE id = (SELECT MAX(id) FROM ${table})`;
+this.driver.prepare(sql).run(value);
+}
+}
+
+getRows(table) {
+return this.driver.prepare(`SELECT * FROM ${table}`).all();
+}
+
+close() {
+this.driver.close();
+}
+}
+
+module.exports = { MemoryDatabase, SQLiteDatabase };

package/FileSystem.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * FileSystem.js — Acesso a ficheiros isomorfico (Node ou browser)
+ *
+ * botql.js precisa de ler ficheiros para resolver IMPORT. Em Node isso e
+ * fs.readFileSync + path real. No browser (ou em qualquer ambiente sem
+ * fs), nao ha disco: os "ficheiros" sao apenas texto que o utilizador
+ * forneceu antecipadamente (ex: nos campos de import do editor).
+ *
+ * Qualquer adapter aqui implementa o mesmo contrato, usado por botql.js:
+ *   exists(path) -> boolean
+ *   readFile(path) -> string
+ *   resolve(basePath, relativePath) -> string (caminho absoluto/canonico)
+ *   dirname(path) -> string
+ *
+ * NodeFileSystem: usa fs/path reais do Node. E o omissao quando o codigo
+ * corre em Node (Bootstrap.js, CLI, testes).
+ *
+ * MemoryFileSystem: guarda ficheiros num Map (caminho -> conteudo) em
+ * memoria. Usado no browser: o Index.html regista ai o conteudo de cada
+ * ficheiro importado antes de correr o bot. Os caminhos sao tratados como
+ * chaves de texto simples, normalizadas (sem "./", sem duplicar "/").
+ */
+
+class MemoryFileSystem {
+    constructor(files = {}) {
+        // files: { "caminho/ficheiro.sql": "conteudo..." }
+        this.files = new Map(
+            Object.entries(files).map(([k, v]) => [this._normalize(k), v])
+        );
+    }
+
+    _normalize(p) {
+        // Remove "./" do inicio e barras duplicadas, mantem caminho relativo simples.
+        return String(p).replace(/^\.\//, '').replace(/\/+/g, '/').trim();
+    }
+
+    setFile(path, content) {
+        this.files.set(this._normalize(path), content);
+    }
+
+    exists(path) {
+        return this.files.has(this._normalize(path));
+    }
+
+    readFile(path) {
+        const key = this._normalize(path);
+        if (!this.files.has(key)) {
+            throw new Error(`BotQL: ficheiro não encontrado: "${path}"`);
+        }
+        return this.files.get(key);
+    }
+
+    // basePath e' ignorado de proposito: no browser nao ha nocao real de
+    // diretorio corrente, os ficheiros importados sao identificados pelo
+    // nome/caminho tal como o utilizador os registou.
+    resolve(basePath, relativePath) {
+        return this._normalize(relativePath);
+    }
+
+    dirname(filePath) {
+        const norm = this._normalize(filePath);
+        const idx = norm.lastIndexOf('/');
+        return idx === -1 ? '' : norm.slice(0, idx);
+    }
+}
+
+class NodeFileSystem {
+    constructor() {
+        this._fs = require('fs');
+        this._path = require('path');
+    }
+
+    exists(path) {
+        return this._fs.existsSync(path);
+    }
+
+    readFile(path) {
+        return this._fs.readFileSync(path, 'utf8');
+    }
+
+    resolve(basePath, relativePath) {
+        return this._path.resolve(basePath, relativePath);
+    }
+
+    dirname(filePath) {
+        return this._path.dirname(filePath);
+    }
+}
+
+// Deteta o ambiente uma unica vez. `require` e `module` so existem em Node/CommonJS.
+const isNode = typeof process !== 'undefined'
+    && process.versions
+    && !!process.versions.node;
+
+function createDefaultFileSystem() {
+    return isNode ? new NodeFileSystem() : new MemoryFileSystem();
+}
+
+const api = { MemoryFileSystem, NodeFileSystem, createDefaultFileSystem };
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = api;
+} else {
+    // Browser sem bundler/CommonJS: expõe global.
+    this.BotQLFileSystem = api;
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adilson C. Rafael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.