notoken-core 1.6.0 → 1.8.0

package/dist/utils/browser.js

@@ -0,0 +1,364 @@
+/**
+ * Browser Manager.
+ *
+ * Detects, installs, and launches browser automation engines.
+ *
+ * Priority:
+ *   1. Patchright (patched Playwright — anti-detection)
+ *   2. Playwright
+ *   3. Docker (browserless/chromium container)
+ *   4. System browser (xdg-open / open / start)
+ *
+ * Usage:
+ *   notoken browse <url>
+ *   notoken browse install
+ *   notoken browse status
+ *   "open google.com"
+ *   "take screenshot of example.com"
+ *   "browse to localhost:3000"
+ */
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { USER_HOME } from "./paths.js";
+import { platform } from "node:os";
+const SCREENSHOTS_DIR = resolve(USER_HOME, "screenshots");
+const c = {
+    reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+    green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m", cyan: "\x1b[36m",
+};
+// ─── Detection ─────────────────────────────────────────────────────────────
+function tryExec(cmd, timeout = 5000) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasNpmPackage(name) {
+    // Fast check: try to resolve the module directly
+    const resolved = tryExec(`node -e "try{require.resolve('${name}');console.log('ok')}catch{}" 2>/dev/null`, 3000);
+    if (resolved === "ok")
+        return true;
+    // Check global bin
+    if (tryExec(`which ${name} 2>/dev/null`, 2000))
+        return true;
+    return false;
+}
+export function detectBrowserEngines() {
+    const engines = [];
+    // 1. Patchright
+    const patchrightInstalled = hasNpmPackage("patchright");
+    engines.push({
+        engine: "patchright",
+        available: patchrightInstalled,
+        version: patchrightInstalled ? (tryExec("npx patchright --version 2>/dev/null", 3000) ?? "installed") : undefined,
+        browsersInstalled: patchrightInstalled ? checkBrowserBinaries("patchright") : false,
+    });
+    // 2. Playwright
+    const playwrightInstalled = hasNpmPackage("playwright");
+    engines.push({
+        engine: "playwright",
+        available: playwrightInstalled,
+        version: playwrightInstalled ? (tryExec("npx playwright --version 2>/dev/null", 3000) ?? "installed") : undefined,
+        browsersInstalled: playwrightInstalled ? checkBrowserBinaries("playwright") : false,
+    });
+    // 3. Docker (browserless)
+    const dockerAvailable = !!tryExec("docker --version");
+    let dockerImage;
+    if (dockerAvailable) {
+        const images = tryExec("docker images --format '{{.Repository}}:{{.Tag}}' 2>/dev/null");
+        if (images) {
+            const browserless = images.split("\n").find(i => i.includes("browserless") || i.includes("chromium") || i.includes("chrome"));
+            dockerImage = browserless;
+        }
+    }
+    engines.push({
+        engine: "docker",
+        available: dockerAvailable,
+        version: dockerAvailable ? tryExec("docker --version")?.replace("Docker version ", "") ?? undefined : undefined,
+        dockerImage,
+    });
+    // 4. System browser (always available)
+    engines.push({
+        engine: "system",
+        available: true,
+        version: getSystemBrowserName(),
+    });
+    return engines;
+}
+function checkBrowserBinaries(engine) {
+    // Check if chromium is installed for the engine
+    const check = tryExec(`npx ${engine} install --dry-run chromium 2>&1`);
+    if (check?.includes("already installed") || check?.includes("is already"))
+        return true;
+    // Fallback: try to find the browser cache
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    const cacheDir = engine === "patchright"
+        ? resolve(home, ".cache", "patchright")
+        : resolve(home, ".cache", "ms-playwright");
+    return existsSync(cacheDir);
+}
+function getSystemBrowserName() {
+    const os = platform();
+    if (os === "darwin")
+        return "macOS default (open)";
+    if (os === "win32")
+        return "Windows default (start)";
+    // Check for common Linux browsers
+    for (const browser of ["google-chrome-stable", "google-chrome", "chromium-browser", "chromium", "firefox"]) {
+        if (tryExec(`which ${browser}`))
+            return browser;
+    }
+    return "xdg-open";
+}
+/**
+ * Get the best available engine.
+ */
+export function getBestEngine() {
+    const engines = detectBrowserEngines();
+    // Prefer patchright > playwright > docker (only with image) > system
+    const patchright = engines.find(e => e.engine === "patchright" && e.available && e.browsersInstalled);
+    if (patchright)
+        return patchright;
+    const playwright = engines.find(e => e.engine === "playwright" && e.available && e.browsersInstalled);
+    if (playwright)
+        return playwright;
+    // Patchright/playwright installed but no browsers — still usable (will auto-download)
+    const patchrightNoBrowser = engines.find(e => e.engine === "patchright" && e.available);
+    if (patchrightNoBrowser)
+        return patchrightNoBrowser;
+    const playwrightNoBrowser = engines.find(e => e.engine === "playwright" && e.available);
+    if (playwrightNoBrowser)
+        return playwrightNoBrowser;
+    const docker = engines.find(e => e.engine === "docker" && e.available && e.dockerImage);
+    if (docker)
+        return docker;
+    return engines.find(e => e.engine === "system") ?? null;
+}
+export async function installBrowserEngine(engine) {
+    const target = engine ?? "patchright";
+    if (target === "patchright" || target === "playwright") {
+        try {
+            console.log(`${c.dim}Installing ${target}...${c.reset}`);
+            execSync(`npm install -g ${target}`, { stdio: "inherit", timeout: 120000 });
+            console.log(`${c.dim}Installing ${target} browsers (chromium)...${c.reset}`);
+            execSync(`npx ${target} install chromium`, { stdio: "inherit", timeout: 300000 });
+            return { success: true, engine: target, message: `${target} + chromium installed successfully` };
+        }
+        catch (err) {
+            return { success: false, engine: target, message: `Failed to install ${target}: ${err instanceof Error ? err.message : err}` };
+        }
+    }
+    if (target === "docker") {
+        const dockerAvailable = !!tryExec("docker --version");
+        if (!dockerAvailable) {
+            return { success: false, engine: "docker", message: "Docker is not installed. Install Docker first." };
+        }
+        try {
+            console.log(`${c.dim}Pulling browserless/chromium image...${c.reset}`);
+            execSync("docker pull ghcr.io/browserless/chromium", { stdio: "inherit", timeout: 300000 });
+            return { success: true, engine: "docker", message: "browserless/chromium image pulled" };
+        }
+        catch (err) {
+            return { success: false, engine: "docker", message: `Failed to pull image: ${err instanceof Error ? err.message : err}` };
+        }
+    }
+    return { success: true, engine: "system", message: "System browser is always available" };
+}
+// ─── Browse ────────────────────────────────────────────────────────────────
+/**
+ * Open a URL using the best available engine.
+ */
+export async function browse(opts) {
+    const url = normalizeUrl(opts.url);
+    const engine = getBestEngine();
+    if (!engine) {
+        return { engine: "system", url, error: "No browser engine available" };
+    }
+    // For system browser or non-headless without screenshot, just open
+    if (engine.engine === "system" && !opts.screenshot) {
+        return openSystemBrowser(url);
+    }
+    // For automation engines
+    if (engine.engine === "patchright" || engine.engine === "playwright") {
+        return browseWithPlaywright(engine.engine, url, opts);
+    }
+    if (engine.engine === "docker") {
+        return browseWithDocker(url, opts);
+    }
+    return openSystemBrowser(url);
+}
+export function normalizeUrl(url) {
+    // Add https:// if no protocol
+    if (!/^https?:\/\//i.test(url) && !url.startsWith("file://")) {
+        // If it looks like localhost, use http
+        if (url.startsWith("localhost") || url.startsWith("127.0.0.1") || url.startsWith("0.0.0.0")) {
+            return `http://${url}`;
+        }
+        return `https://${url}`;
+    }
+    return url;
+}
+function openSystemBrowser(url) {
+    try {
+        const os = platform();
+        if (os === "darwin") {
+            execSync(`open "${url}"`, { stdio: "ignore" });
+        }
+        else if (os === "win32") {
+            execSync(`start "" "${url}"`, { stdio: "ignore", shell: "cmd.exe" });
+        }
+        else {
+            // WSL check
+            const isWSL = tryExec("grep -qi microsoft /proc/version && echo wsl");
+            if (isWSL) {
+                execSync(`cmd.exe /c start "" "${url}"`, { stdio: "ignore" });
+            }
+            else {
+                execSync(`xdg-open "${url}"`, { stdio: "ignore" });
+            }
+        }
+        return { engine: "system", url, title: "Opened in system browser" };
+    }
+    catch (err) {
+        return { engine: "system", url, error: `Failed to open: ${err instanceof Error ? err.message : err}` };
+    }
+}
+async function browseWithPlaywright(engine, url, opts) {
+    // Generate a script and run it via node
+    const headless = opts.headless ?? !opts.screenshot;
+    const viewport = opts.viewport ?? { width: 1280, height: 720 };
+    const waitFor = opts.waitFor ?? 2000;
+    mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+    const screenshotPath = opts.screenshotPath ?? opts.screenshot
+        ? resolve(SCREENSHOTS_DIR, `screenshot-${Date.now()}.png`)
+        : undefined;
+    const script = `
+const { chromium } = require("${engine}");
+(async () => {
+  const browser = await chromium.launch({ headless: ${headless} });
+  const context = await browser.newContext({
+    viewport: { width: ${viewport.width}, height: ${viewport.height} },
+    ${opts.userAgent ? `userAgent: "${opts.userAgent}",` : ""}
+  });
+  const page = await context.newPage();
+  await page.goto("${url}", { waitUntil: "domcontentloaded", timeout: 30000 });
+  await page.waitForTimeout(${waitFor});
+  const title = await page.title();
+  ${screenshotPath ? `await page.screenshot({ path: "${screenshotPath}", fullPage: true });` : ""}
+  ${!headless && !opts.screenshot ? `
+  // Keep browser open for interactive use
+  console.log(JSON.stringify({ title, status: "open" }));
+  // Wait for user to close
+  await new Promise(() => {});
+  ` : `
+  console.log(JSON.stringify({ title, status: "done" }));
+  await browser.close();
+  `}
+})().catch(err => {
+  console.error(JSON.stringify({ error: err.message }));
+  process.exit(1);
+});
+`;
+    const tmpScript = resolve(USER_HOME, ".browse-script.cjs");
+    writeFileSync(tmpScript, script);
+    return new Promise((res) => {
+        const child = spawn("node", [tmpScript], {
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: opts.screenshot ? 60000 : 0,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => { stdout += d.toString(); });
+        child.stderr?.on("data", (d) => { stderr += d.toString(); });
+        // For interactive (non-headless, no screenshot), resolve immediately
+        if (!headless && !opts.screenshot) {
+            setTimeout(() => {
+                res({ engine, url, title: "Browser opened interactively", screenshotPath: undefined });
+            }, 3000);
+            return;
+        }
+        child.on("close", () => {
+            try {
+                const result = JSON.parse(stdout.trim().split("\n").pop() ?? "{}");
+                if (result.error) {
+                    res({ engine, url, error: result.error });
+                }
+                else {
+                    res({ engine, url, title: result.title, screenshotPath });
+                }
+            }
+            catch {
+                res({ engine, url, error: stderr || "Unknown error" });
+            }
+        });
+    });
+}
+async function browseWithDocker(url, opts) {
+    const screenshotPath = opts.screenshot
+        ? resolve(SCREENSHOTS_DIR, `screenshot-${Date.now()}.png`)
+        : undefined;
+    try {
+        // Start browserless container if not running
+        const running = tryExec("docker ps --format '{{.Image}}' 2>/dev/null");
+        if (!running?.includes("browserless")) {
+            console.log(`${c.dim}Starting browserless container...${c.reset}`);
+            execSync("docker run -d --rm -p 3100:3000 --name notoken-browser ghcr.io/browserless/chromium", {
+                stdio: "ignore",
+                timeout: 30000,
+            });
+            // Wait for it to be ready
+            execSync("sleep 2");
+        }
+        if (opts.screenshot && screenshotPath) {
+            mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+            // Use browserless screenshot API
+            execSync(`curl -sf -o "${screenshotPath}" "http://localhost:3100/screenshot?url=${encodeURIComponent(url)}"`, {
+                timeout: 30000,
+            });
+            return { engine: "docker", url, title: "Screenshot via Docker", screenshotPath };
+        }
+        // Just open — use browserless content API to get title
+        const content = tryExec(`curl -sf "http://localhost:3100/content?url=${encodeURIComponent(url)}" 2>/dev/null`);
+        const titleMatch = content?.match(/<title>([^<]+)<\/title>/i);
+        return { engine: "docker", url, title: titleMatch?.[1] ?? "Page loaded via Docker" };
+    }
+    catch (err) {
+        return { engine: "docker", url, error: `Docker browse failed: ${err instanceof Error ? err.message : err}` };
+    }
+}
+// ─── Formatting ────────────────────────────────────────────────────────────
+export function formatBrowserStatus(engines) {
+    const lines = [];
+    lines.push(`${c.bold}Browser Engines${c.reset}\n`);
+    for (const e of engines) {
+        const icon = e.available
+            ? (e.engine === "system" ? `${c.green}⬤${c.reset}` :
+                e.browsersInstalled !== false ? `${c.green}⬤${c.reset}` : `${c.yellow}⬤${c.reset}`)
+            : `${c.dim}○${c.reset}`;
+        const status = e.available
+            ? (e.browsersInstalled === false ? `${c.yellow}installed (no browsers)${c.reset}` : `${c.green}ready${c.reset}`)
+            : `${c.dim}not installed${c.reset}`;
+        const ver = e.version ? ` ${c.dim}${e.version}${c.reset}` : "";
+        const docker = e.dockerImage ? ` ${c.dim}image: ${e.dockerImage}${c.reset}` : "";
+        const pref = e === getBestEngine() ? ` ${c.cyan}← active${c.reset}` : "";
+        lines.push(`  ${icon} ${c.bold}${e.engine}${c.reset} — ${status}${ver}${docker}${pref}`);
+    }
+    const best = getBestEngine();
+    lines.push("");
+    lines.push(`  ${c.dim}Active engine: ${best?.engine ?? "none"}${c.reset}`);
+    lines.push(`  ${c.dim}Screenshots: ${SCREENSHOTS_DIR}${c.reset}`);
+    return lines.join("\n");
+}
+// ─── Stop Docker browser ───────────────────────────────────────────────────
+export function stopDockerBrowser() {
+    try {
+        execSync("docker stop notoken-browser 2>/dev/null", { stdio: "ignore", timeout: 10000 });
+        return `${c.green}✓${c.reset} Docker browser stopped.`;
+    }
+    catch {
+        return `${c.dim}No Docker browser running.${c.reset}`;
+    }
+}

package/dist/utils/commandHistory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Command History — persistent history with search.
+ *
+ * Stores every command typed in interactive mode.
+ * Supports:
+ *   - History file (~/.notoken/command-history.txt)
+ *   - Search (Ctrl+R style fuzzy search)
+ *   - Recent commands for suggestions
+ *   - Dedup consecutive duplicates
+ */
+/** Load history from disk. */
+export declare function loadHistory(): string[];
+/** Add a command to history (dedup consecutive). */
+export declare function addToHistory(command: string): void;
+/** Search history with fuzzy matching. */
+export declare function searchHistory(query: string, limit?: number): string[];
+/** Get the N most recent unique commands. */
+export declare function getRecentCommands(limit?: number): string[];
+/** Get history for readline (returns copy of array for rl.history). */
+export declare function getReadlineHistory(): string[];

package/dist/utils/commandHistory.js

@@ -0,0 +1,108 @@
+/**
+ * Command History — persistent history with search.
+ *
+ * Stores every command typed in interactive mode.
+ * Supports:
+ *   - History file (~/.notoken/command-history.txt)
+ *   - Search (Ctrl+R style fuzzy search)
+ *   - Recent commands for suggestions
+ *   - Dedup consecutive duplicates
+ */
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+const HISTORY_DIR = resolve(homedir(), ".notoken");
+const HISTORY_FILE = resolve(HISTORY_DIR, "command-history.txt");
+const MAX_HISTORY = 2000;
+let _history = null;
+/** Load history from disk. */
+export function loadHistory() {
+    if (_history)
+        return _history;
+    if (!existsSync(HISTORY_DIR))
+        mkdirSync(HISTORY_DIR, { recursive: true });
+    if (existsSync(HISTORY_FILE)) {
+        _history = readFileSync(HISTORY_FILE, "utf-8")
+            .split("\n")
+            .filter(l => l.trim())
+            .slice(-MAX_HISTORY);
+    }
+    else {
+        _history = [];
+    }
+    return _history;
+}
+/** Add a command to history (dedup consecutive). */
+export function addToHistory(command) {
+    const history = loadHistory();
+    const trimmed = command.trim();
+    if (!trimmed)
+        return;
+    // Don't add if it's the same as the last command
+    if (history.length > 0 && history[history.length - 1] === trimmed)
+        return;
+    // Don't add meta commands
+    if (trimmed.startsWith(":") || trimmed.startsWith("/"))
+        return;
+    history.push(trimmed);
+    // Append to file
+    try {
+        appendFileSync(HISTORY_FILE, trimmed + "\n");
+    }
+    catch { }
+    // Trim in memory if too long
+    if (history.length > MAX_HISTORY) {
+        _history = history.slice(-MAX_HISTORY);
+    }
+}
+/** Search history with fuzzy matching. */
+export function searchHistory(query, limit = 10) {
+    const history = loadHistory();
+    const lower = query.toLowerCase();
+    const matches = [];
+    for (let i = history.length - 1; i >= 0; i--) {
+        const cmd = history[i];
+        const cmdLower = cmd.toLowerCase();
+        if (cmdLower.includes(lower)) {
+            // Exact substring match — higher score for more recent
+            const recency = (i / history.length) * 0.3; // 0-0.3
+            const relevance = lower.length / cmdLower.length; // longer match = better
+            matches.push({ cmd, score: 0.5 + recency + relevance * 0.2 });
+        }
+        else {
+            // Check word overlap
+            const queryWords = lower.split(/\s+/);
+            const cmdWords = new Set(cmdLower.split(/\s+/));
+            const overlap = queryWords.filter(w => cmdWords.has(w)).length;
+            if (overlap > 0) {
+                const score = (overlap / queryWords.length) * 0.4 + (i / history.length) * 0.2;
+                matches.push({ cmd, score });
+            }
+        }
+    }
+    // Dedup and sort by score
+    const seen = new Set();
+    return matches
+        .sort((a, b) => b.score - a.score)
+        .filter(m => { if (seen.has(m.cmd))
+        return false; seen.add(m.cmd); return true; })
+        .slice(0, limit)
+        .map(m => m.cmd);
+}
+/** Get the N most recent unique commands. */
+export function getRecentCommands(limit = 10) {
+    const history = loadHistory();
+    const seen = new Set();
+    const recent = [];
+    for (let i = history.length - 1; i >= 0 && recent.length < limit; i--) {
+        if (!seen.has(history[i])) {
+            seen.add(history[i]);
+            recent.push(history[i]);
+        }
+    }
+    return recent;
+}
+/** Get history for readline (returns copy of array for rl.history). */
+export function getReadlineHistory() {
+    return [...loadHistory()].reverse();
+}

package/dist/utils/completer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tab-completion for notoken interactive mode.
+ *
+ * Builds a flat list of completable phrases from intents, meta commands,
+ * service aliases, common verbs, and recent history.  Cached and rebuilt
+ * every 60 seconds.
+ */
+/**
+ * Build (or rebuild) the flat list of completable strings.
+ */
+export declare function buildCompletions(): string[];
+/**
+ * Readline-compatible completer function.
+ *
+ * Signature: (line: string) => [matches: string[], line: string]
+ */
+export declare function completeInput(line: string): [string[], string];

package/dist/utils/completer.js

@@ -0,0 +1,79 @@
+/**
+ * Tab-completion for notoken interactive mode.
+ *
+ * Builds a flat list of completable phrases from intents, meta commands,
+ * service aliases, common verbs, and recent history.  Cached and rebuilt
+ * every 60 seconds.
+ */
+import { loadIntents } from "./config.js";
+import { loadRules } from "./config.js";
+import { getRecentHistory } from "../context/history.js";
+// ── Cache ───────────────────────────────────────────────────────────────────
+let cached = [];
+let lastBuilt = 0;
+const CACHE_TTL = 60_000; // 60 s
+const META_COMMANDS = [
+    "/jobs", "/help", "/quit", "/output", "/kill",
+    "/aliases", "/history",
+];
+const COMMON_VERBS = [
+    "restart", "check", "show", "list", "install",
+    "diagnose", "monitor",
+];
+/**
+ * Build (or rebuild) the flat list of completable strings.
+ */
+export function buildCompletions() {
+    const set = new Set();
+    // Meta commands
+    for (const cmd of META_COMMANDS)
+        set.add(cmd);
+    // Common verbs
+    for (const v of COMMON_VERBS)
+        set.add(v);
+    // Intent synonyms
+    try {
+        const intents = loadIntents();
+        for (const intent of intents) {
+            for (const syn of intent.synonyms ?? []) {
+                set.add(syn.toLowerCase());
+            }
+        }
+    }
+    catch { /* config may not be loaded yet */ }
+    // Service alias names
+    try {
+        const rules = loadRules();
+        for (const [service, aliases] of Object.entries(rules.serviceAliases)) {
+            set.add(service);
+            for (const a of aliases)
+                set.add(a.toLowerCase());
+        }
+    }
+    catch { /* rules may not be loaded yet */ }
+    // Recent commands from history
+    try {
+        const recent = getRecentHistory(20);
+        for (const entry of recent) {
+            if (entry.rawText)
+                set.add(entry.rawText);
+        }
+    }
+    catch { /* history may be empty */ }
+    cached = [...set].sort();
+    lastBuilt = Date.now();
+    return cached;
+}
+/**
+ * Readline-compatible completer function.
+ *
+ * Signature: (line: string) => [matches: string[], line: string]
+ */
+export function completeInput(line) {
+    if (Date.now() - lastBuilt > CACHE_TTL || cached.length === 0) {
+        buildCompletions();
+    }
+    const lower = line.toLowerCase();
+    const hits = cached.filter((c) => c.toLowerCase().startsWith(lower));
+    return [hits.length > 0 ? hits : cached, line];
+}

package/dist/utils/config.js

@@ -1,8 +1,8 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { RulesConfig } from "../types/rules.js";
 import { IntentsConfig } from "../types/intent.js";
-import { CONFIG_DIR } from "./paths.js";
+import { CONFIG_DIR, USER_HOME } from "./paths.js";
 import { pluginRegistry } from "../plugins/registry.js";
 let cachedRules = null;
 let cachedIntents = null;
@@ -40,6 +40,36 @@ export function loadIntents(forceReload = false) {
             cachedIntents.intents.push(pi);
         }
     }
+    // Merge user custom intents from ~/.notoken/custom-intents.json
+    const customFile = resolve(USER_HOME, "custom-intents.json");
+    if (existsSync(customFile)) {
+        try {
+            const customRaw = readFileSync(customFile, "utf-8");
+            const customData = JSON.parse(customRaw);
+            const customIntents = customData.intents ?? [];
+            for (const ci of customIntents) {
+                const entry = ci;
+                // Build a full IntentDef with sensible defaults for user-defined intents
+                const def = {
+                    name: entry.name,
+                    description: entry.description ?? "",
+                    synonyms: entry.synonyms ?? [],
+                    fields: entry.fields ?? {},
+                    command: entry.command ?? "",
+                    execution: entry.execution ?? "local",
+                    requiresConfirmation: entry.requiresConfirmation ?? true,
+                    riskLevel: entry.riskLevel ?? "medium",
+                    examples: entry.examples ?? entry.synonyms ?? [],
+                };
+                if (!cachedIntents.intents.find((i) => i.name === def.name)) {
+                    cachedIntents.intents.push(def);
+                }
+            }
+        }
+        catch {
+            // Silently ignore malformed custom intents file
+        }
+    }
     return cachedIntents.intents;
 }
 export function getIntentDef(name) {

package/dist/utils/dbQuery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Natural language → SQL query builder.
+ *
+ * Translates phrases like:
+ *   "look at items and find sally"        → SELECT * FROM items WHERE ... LIKE '%sally%'
+ *   "show me all users"                   → SELECT * FROM users
+ *   "count orders"                        → SELECT COUNT(*) FROM orders
+ *   "show tables"                         → \dt (postgres) or SHOW TABLES (mysql)
+ *   "describe users table"                → \d users or DESCRIBE users
+ *   "find orders where total > 100"       → SELECT * FROM orders WHERE total > 100
+ */
+export type DbType = "postgres" | "mysql";
+export interface DbQueryResult {
+    query: string;
+    command: string;
+    explanation: string;
+}
+/**
+ * Build a SQL query from natural language.
+ */
+export declare function buildQuery(rawText: string, fields: Record<string, unknown>, dbType?: DbType): DbQueryResult;
+/**
+ * Format query result for display — show the SQL, explain it, then run.
+ */
+export declare function formatQueryPlan(result: DbQueryResult): string;