notoken-core 1.2.0 → 1.3.0

package/README.md

@@ -0,0 +1,47 @@
+# notoken-core
+
+Shared engine for [notoken](https://notoken.sh) — NLP parsing, execution, detection, analysis.
+
+Used by the CLI (`notoken`) and the desktop app (`notoken-installer`).
+
+## Install
+
+```bash
+npm install notoken-core
+```
+
+## Usage
+
+```typescript
+import {
+  parseIntent,
+  executeIntent,
+  detectLocalPlatform,
+  checkForUpdate,
+} from "notoken-core";
+
+// Parse natural language into a structured intent
+const parsed = await parseIntent("restart nginx on prod");
+console.log(parsed.intent.intent);  // "service.restart"
+console.log(parsed.intent.fields);  // { service: "nginx", environment: "prod" }
+
+// Detect platform
+const platform = detectLocalPlatform();
+console.log(platform.distro);       // "Ubuntu 24.04.2 LTS"
+console.log(platform.packageManager); // "apt"
+```
+
+## What's Inside
+
+- **119 config-driven intents** — services, docker, git, files, network, security, databases, and more
+- **NLP pipeline** — rule parser + compromise POS tagging + multi-classifier + keyboard typo correction
+- **LLM fallback** — Claude CLI, OpenAI API, or Ollama (auto-detected)
+- **File parsers** — passwd, shadow, .env, yaml, json, nginx, apache, BIND zone files
+- **Intelligent analysis** — load/disk/memory assessment, project type detection
+- **Conversation persistence** — knowledge tree, coreference resolution
+- **Platform detection** — Linux/macOS/Windows/WSL, adapts commands per OS
+- **Adaptive rules** — learns from failures via LLM
+
+## License
+
+MIT — [Dino Bartolome](https://notoken.sh)

package/dist/handlers/executor.js

@@ -8,6 +8,7 @@ import { detectLocalPlatform, getPackageForCommand, getInstallCommand } from "..
 import { withSpinner } from "../utils/spinner.js";
 import { analyzeOutput } from "../utils/analysis.js";
 import { smartRead, smartSearch } from "../utils/smartFile.js";
+import { pluginRegistry } from "../plugins/registry.js";
 /**
  * Generic command executor.
  *
@@ -19,6 +20,15 @@ export async function executeIntent(intent) {
     if (!def) {
         throw new Error(`No intent definition found for: ${intent.intent}`);
     }
+    // Plugin beforeExecute hooks — can cancel execution
+    const proceed = await pluginRegistry.runBeforeExecute({
+        intent: intent.intent,
+        fields: intent.fields,
+        rawText: intent.rawText,
+    });
+    if (proceed === false) {
+        return "[cancelled by plugin]";
+    }
     // Fuzzy resolve file paths if needed
     const resolved = await resolveFuzzyFields(intent);
     const fields = resolved.fields;
@@ -121,6 +131,8 @@ export async function executeIntent(intent) {
     if (analysis) {
         result += "\n" + analysis;
     }
+    // Plugin afterExecute hooks
+    await pluginRegistry.runAfterExecute({ intent: intent.intent, fields }, result);
     return result;
 }
 async function executeGitIntent(intentName, fields) {

package/dist/index.d.ts

@@ -48,5 +48,7 @@ export { checkForUpdate, checkForUpdateSync, runUpdate, formatUpdateBanner, type
 export { logFailure, loadFailures, clearFailures } from "./utils/logger.js";
 export { logUncertainty, loadUncertaintyLog, getUncertaintySummary } from "./nlp/uncertainty.js";
 export { recordHistory, loadHistory, getRecentHistory, searchHistory } from "./context/history.js";
+export { pluginRegistry } from "./plugins/index.js";
+export type { NotokenPlugin, PluginIntent, PluginPlaybook, PluginHooks, LoadedPlugin } from "./plugins/index.js";
 export type { DynamicIntent, ParsedCommand, IntentDef, FieldDef, EnvironmentName } from "./types/intent.js";
 export type { RulePatch, RulePatchChange, FailureLog, RulesConfig } from "./types/rules.js";

package/dist/index.js

@@ -62,3 +62,5 @@ export { checkForUpdate, checkForUpdateSync, runUpdate, formatUpdateBanner } fro
 export { logFailure, loadFailures, clearFailures } from "./utils/logger.js";
 export { logUncertainty, loadUncertaintyLog, getUncertaintySummary } from "./nlp/uncertainty.js";
 export { recordHistory, loadHistory, getRecentHistory, searchHistory } from "./context/history.js";
+// ── Plugins ──
+export { pluginRegistry } from "./plugins/index.js";

package/dist/plugins/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Plugin system public API.
+ */
+export { pluginRegistry } from "./registry.js";
+export type { NotokenPlugin, PluginIntent, PluginPlaybook, PluginHooks, PluginAliases, PluginFileHints, LoadedPlugin, } from "./types.js";

package/dist/plugins/index.js

@@ -0,0 +1,4 @@
+/**
+ * Plugin system public API.
+ */
+export { pluginRegistry } from "./registry.js";

package/dist/plugins/registry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Plugin registry.
+ *
+ * Discovers, loads, validates, and manages plugins.
+ *
+ * Plugin sources (checked in order):
+ * 1. ~/.notoken/plugins/         — local plugins (JS/TS files or directories)
+ * 2. npm: notoken-plugin-*       — installed globally via npm
+ * 3. Built-in plugins            — shipped with notoken-core
+ *
+ * Usage:
+ *   import { pluginRegistry } from "notoken-core";
+ *   await pluginRegistry.loadAll();
+ *   const intents = pluginRegistry.getAllIntents();
+ *   const playbooks = pluginRegistry.getAllPlaybooks();
+ */
+import type { LoadedPlugin } from "./types.js";
+declare class PluginRegistry {
+    private plugins;
+    private loaded;
+    /**
+     * Load all plugins from all sources.
+     */
+    loadAll(): Promise<void>;
+    /**
+     * Load a single plugin by path or module name.
+     */
+    load(nameOrPath: string, source?: "npm" | "local"): Promise<boolean>;
+    /**
+     * Unload a plugin by name.
+     */
+    unload(name: string): Promise<boolean>;
+    /** Get all intents from all plugins + core. */
+    getAllIntents(): Array<{
+        name: string;
+        [k: string]: unknown;
+    }>;
+    /** Get all playbooks from all plugins. */
+    getAllPlaybooks(): Array<{
+        name: string;
+        description: string;
+        steps: Array<{
+            command: string;
+            label: string;
+        }>;
+        _plugin: string;
+    }>;
+    /** Get all service aliases from plugins. */
+    getAllServiceAliases(): Record<string, string[]>;
+    /** Get all environment aliases from plugins. */
+    getAllEnvironmentAliases(): Record<string, string[]>;
+    /** Run all beforeExecute hooks. Returns false if any hook cancels. */
+    runBeforeExecute(intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+        rawText: string;
+    }): Promise<boolean>;
+    /** Run all afterExecute hooks. */
+    runAfterExecute(intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+    }, result: string): Promise<void>;
+    /** Run all onError hooks. */
+    runOnError(intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+    }, error: Error): Promise<void>;
+    /** Run all onUnknown hooks. Returns first non-null result. */
+    runOnUnknown(rawText: string): Promise<{
+        intent: string;
+        fields: Record<string, unknown>;
+        confidence: number;
+    } | null>;
+    /** List all loaded plugins. */
+    list(): LoadedPlugin[];
+    /** Get a plugin by name. */
+    get(name: string): LoadedPlugin | undefined;
+    /** Get count of loaded plugins. */
+    get count(): number;
+    private loadLocalPlugins;
+    private loadNpmPlugins;
+    private validate;
+}
+/** Singleton plugin registry. */
+export declare const pluginRegistry: PluginRegistry;
+export {};

package/dist/plugins/registry.js

@@ -0,0 +1,280 @@
+/**
+ * Plugin registry.
+ *
+ * Discovers, loads, validates, and manages plugins.
+ *
+ * Plugin sources (checked in order):
+ * 1. ~/.notoken/plugins/         — local plugins (JS/TS files or directories)
+ * 2. npm: notoken-plugin-*       — installed globally via npm
+ * 3. Built-in plugins            — shipped with notoken-core
+ *
+ * Usage:
+ *   import { pluginRegistry } from "notoken-core";
+ *   await pluginRegistry.loadAll();
+ *   const intents = pluginRegistry.getAllIntents();
+ *   const playbooks = pluginRegistry.getAllPlaybooks();
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { USER_HOME } from "../utils/paths.js";
+const require = createRequire(import.meta.url);
+const PLUGIN_DIR = resolve(USER_HOME, "plugins");
+class PluginRegistry {
+    plugins = new Map();
+    loaded = false;
+    /**
+     * Load all plugins from all sources.
+     */
+    async loadAll() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        // 1. Local plugins
+        await this.loadLocalPlugins();
+        // 2. npm global plugins
+        await this.loadNpmPlugins();
+        // Report
+        if (this.plugins.size > 0) {
+            const names = Array.from(this.plugins.keys());
+            console.error(`\x1b[2m[plugins] Loaded ${names.length}: ${names.join(", ")}\x1b[0m`);
+        }
+    }
+    /**
+     * Load a single plugin by path or module name.
+     */
+    async load(nameOrPath, source = "local") {
+        try {
+            let plugin = null;
+            let pluginPath = nameOrPath;
+            // Try CJS require first (works for .js with module.exports), then ESM import
+            try {
+                const mod = require(nameOrPath);
+                plugin = (mod && typeof mod.name === "string") ? mod :
+                    (mod?.default && typeof mod.default.name === "string") ? mod.default : null;
+            }
+            catch {
+                // Fall back to ESM import
+                try {
+                    const mod = await import(nameOrPath);
+                    plugin = (mod.default && typeof mod.default.name === "string" ? mod.default :
+                        typeof mod.name === "string" ? mod :
+                            null);
+                }
+                catch { }
+            }
+            if (!plugin || !plugin.name) {
+                console.error(`[plugins] Invalid plugin (no name): ${nameOrPath}`);
+                return false;
+            }
+            // Validate
+            if (!this.validate(plugin))
+                return false;
+            this.plugins.set(plugin.name, {
+                plugin: plugin,
+                source,
+                path: pluginPath,
+                enabled: true,
+            });
+            // Call onLoad hook
+            if (plugin.hooks?.onLoad) {
+                await plugin.hooks.onLoad();
+            }
+            return true;
+        }
+        catch (err) {
+            console.error(`[plugins] Failed to load ${nameOrPath}: ${err.message}`);
+            return false;
+        }
+    }
+    /**
+     * Unload a plugin by name.
+     */
+    async unload(name) {
+        const loaded = this.plugins.get(name);
+        if (!loaded)
+            return false;
+        if (loaded.plugin.hooks?.onUnload) {
+            await loaded.plugin.hooks.onUnload();
+        }
+        this.plugins.delete(name);
+        return true;
+    }
+    // ── Getters ──
+    /** Get all intents from all plugins + core. */
+    getAllIntents() {
+        const intents = [];
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.intents)
+                continue;
+            for (const intent of plugin.intents) {
+                intents.push({
+                    ...intent,
+                    fields: intent.fields ?? {},
+                    execution: intent.execution ?? "local",
+                    requiresConfirmation: intent.requiresConfirmation ?? false,
+                    riskLevel: intent.riskLevel ?? "low",
+                    examples: intent.examples ?? [],
+                    _plugin: plugin.name,
+                });
+            }
+        }
+        return intents;
+    }
+    /** Get all playbooks from all plugins. */
+    getAllPlaybooks() {
+        const playbooks = [];
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.playbooks)
+                continue;
+            for (const pb of plugin.playbooks) {
+                playbooks.push({ ...pb, _plugin: plugin.name });
+            }
+        }
+        return playbooks;
+    }
+    /** Get all service aliases from plugins. */
+    getAllServiceAliases() {
+        const aliases = {};
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.aliases?.services)
+                continue;
+            for (const [service, aliasList] of Object.entries(plugin.aliases.services)) {
+                aliases[service] = [...(aliases[service] ?? []), ...aliasList];
+            }
+        }
+        return aliases;
+    }
+    /** Get all environment aliases from plugins. */
+    getAllEnvironmentAliases() {
+        const aliases = {};
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.aliases?.environments)
+                continue;
+            for (const [env, aliasList] of Object.entries(plugin.aliases.environments)) {
+                aliases[env] = [...(aliases[env] ?? []), ...aliasList];
+            }
+        }
+        return aliases;
+    }
+    /** Run all beforeExecute hooks. Returns false if any hook cancels. */
+    async runBeforeExecute(intent) {
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.hooks?.beforeExecute)
+                continue;
+            const result = await plugin.hooks.beforeExecute(intent);
+            if (result === false)
+                return false;
+        }
+        return true;
+    }
+    /** Run all afterExecute hooks. */
+    async runAfterExecute(intent, result) {
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.hooks?.afterExecute)
+                continue;
+            try {
+                await plugin.hooks.afterExecute(intent, result);
+            }
+            catch { }
+        }
+    }
+    /** Run all onError hooks. */
+    async runOnError(intent, error) {
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.hooks?.onError)
+                continue;
+            try {
+                await plugin.hooks.onError(intent, error);
+            }
+            catch { }
+        }
+    }
+    /** Run all onUnknown hooks. Returns first non-null result. */
+    async runOnUnknown(rawText) {
+        for (const { plugin, enabled } of this.plugins.values()) {
+            if (!enabled || !plugin.hooks?.onUnknown)
+                continue;
+            try {
+                const result = await plugin.hooks.onUnknown(rawText);
+                if (result)
+                    return result;
+            }
+            catch { }
+        }
+        return null;
+    }
+    /** List all loaded plugins. */
+    list() {
+        return Array.from(this.plugins.values());
+    }
+    /** Get a plugin by name. */
+    get(name) {
+        return this.plugins.get(name);
+    }
+    /** Get count of loaded plugins. */
+    get count() {
+        return this.plugins.size;
+    }
+    // ── Private ──
+    async loadLocalPlugins() {
+        if (!existsSync(PLUGIN_DIR))
+            return;
+        const entries = readdirSync(PLUGIN_DIR, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = resolve(PLUGIN_DIR, entry.name);
+            if (entry.isDirectory()) {
+                // Directory plugin — look for index.js or index.mjs
+                const indexPath = [
+                    join(fullPath, "index.js"),
+                    join(fullPath, "index.mjs"),
+                    join(fullPath, "index.cjs"),
+                ].find((p) => existsSync(p));
+                if (indexPath)
+                    await this.load(indexPath, "local");
+            }
+            else if (entry.name.endsWith(".js") || entry.name.endsWith(".mjs")) {
+                await this.load(fullPath, "local");
+            }
+        }
+    }
+    async loadNpmPlugins() {
+        try {
+            const result = execSync("npm list -g --depth=0 --json 2>/dev/null", {
+                encoding: "utf-8",
+                timeout: 10_000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            const parsed = JSON.parse(result);
+            const deps = Object.keys(parsed.dependencies ?? {});
+            for (const dep of deps) {
+                if (dep.startsWith("notoken-plugin-")) {
+                    await this.load(dep, "npm");
+                }
+            }
+        }
+        catch { }
+    }
+    validate(plugin) {
+        if (!plugin.name || typeof plugin.name !== "string") {
+            console.error("[plugins] Plugin missing name");
+            return false;
+        }
+        if (plugin.name.includes(" ") || plugin.name.includes("/")) {
+            console.error(`[plugins] Invalid plugin name: "${plugin.name}" (no spaces or slashes)`);
+            return false;
+        }
+        if (plugin.intents) {
+            for (const intent of plugin.intents) {
+                if (!intent.name || !intent.command) {
+                    console.error(`[plugins] Plugin "${plugin.name}" has intent missing name or command`);
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+}
+/** Singleton plugin registry. */
+export const pluginRegistry = new PluginRegistry();

package/dist/plugins/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Plugin type definitions.
+ *
+ * A plugin is a plain object that conforms to this interface.
+ * Minimum: { name, intents }
+ * Everything else is optional.
+ */
+export interface PluginIntent {
+    name: string;
+    description: string;
+    synonyms: string[];
+    fields?: Record<string, {
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+    command: string;
+    execution?: "local" | "remote";
+    requiresConfirmation?: boolean;
+    riskLevel?: "low" | "medium" | "high";
+    allowlist?: string[];
+    examples?: string[];
+}
+export interface PluginPlaybook {
+    name: string;
+    description: string;
+    steps: Array<{
+        command: string;
+        label: string;
+    }>;
+}
+export interface PluginHooks {
+    /** Called before any intent executes. Return false to cancel. */
+    beforeExecute?: (intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+        rawText: string;
+    }) => Promise<boolean | void>;
+    /** Called after any intent executes successfully. */
+    afterExecute?: (intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+    }, result: string) => Promise<void>;
+    /** Called when an intent execution fails. */
+    onError?: (intent: {
+        intent: string;
+        fields: Record<string, unknown>;
+    }, error: Error) => Promise<void>;
+    /** Called when no intent matches. Return a result to handle it, or null to pass. */
+    onUnknown?: (rawText: string) => Promise<{
+        intent: string;
+        fields: Record<string, unknown>;
+        confidence: number;
+    } | null>;
+    /** Called on startup. */
+    onLoad?: () => Promise<void>;
+    /** Called on shutdown. */
+    onUnload?: () => Promise<void>;
+}
+export interface PluginAliases {
+    services?: Record<string, string[]>;
+    environments?: Record<string, string[]>;
+}
+export interface PluginFileHints {
+    [category: string]: {
+        aliases: string[];
+        configs?: Array<{
+            path: string;
+            description: string;
+        }>;
+        logs?: Array<{
+            path: string;
+            description: string;
+        }>;
+    };
+}
+export interface NotokenPlugin {
+    /** Unique plugin name (e.g., "aws", "mycompany", "slack") */
+    name: string;
+    /** Plugin version */
+    version?: string;
+    /** Description */
+    description?: string;
+    /** Author */
+    author?: string;
+    /** New intents this plugin adds */
+    intents?: PluginIntent[];
+    /** New playbooks */
+    playbooks?: PluginPlaybook[];
+    /** Lifecycle hooks */
+    hooks?: PluginHooks;
+    /** New service/environment aliases */
+    aliases?: PluginAliases;
+    /** New file hint locations */
+    fileHints?: PluginFileHints;
+    /** Plugin configuration (user can set via notoken config set plugins.<name>.<key>) */
+    config?: Record<string, unknown>;
+}
+export interface LoadedPlugin {
+    plugin: NotokenPlugin;
+    source: "npm" | "local" | "builtin";
+    path: string;
+    enabled: boolean;
+}

package/dist/plugins/types.js

@@ -0,0 +1,8 @@
+/**
+ * Plugin type definitions.
+ *
+ * A plugin is a plain object that conforms to this interface.
+ * Minimum: { name, intents }
+ * Everything else is optional.
+ */
+export {};

package/dist/utils/config.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { RulesConfig } from "../types/rules.js";
 import { IntentsConfig } from "../types/intent.js";
 import { CONFIG_DIR } from "./paths.js";
+import { pluginRegistry } from "../plugins/registry.js";
 let cachedRules = null;
 let cachedIntents = null;
 export function loadRules(forceReload = false) {
@@ -10,6 +11,20 @@ export function loadRules(forceReload = false) {
         return cachedRules;
     const raw = readFileSync(resolve(CONFIG_DIR, "rules.json"), "utf-8");
     cachedRules = RulesConfig.parse(JSON.parse(raw));
+    // Merge plugin aliases into rules
+    const pluginServices = pluginRegistry.getAllServiceAliases();
+    for (const [service, aliases] of Object.entries(pluginServices)) {
+        if (!cachedRules.serviceAliases[service]) {
+            cachedRules.serviceAliases[service] = aliases;
+        }
+        else {
+            for (const alias of aliases) {
+                if (!cachedRules.serviceAliases[service].includes(alias)) {
+                    cachedRules.serviceAliases[service].push(alias);
+                }
+            }
+        }
+    }
     return cachedRules;
 }
 export function loadIntents(forceReload = false) {
@@ -17,6 +32,14 @@ export function loadIntents(forceReload = false) {
         return cachedIntents.intents;
     const raw = readFileSync(resolve(CONFIG_DIR, "intents.json"), "utf-8");
     cachedIntents = IntentsConfig.parse(JSON.parse(raw));
+    // Merge plugin intents
+    const pluginIntents = pluginRegistry.getAllIntents();
+    for (const pi of pluginIntents) {
+        // Don't add duplicates
+        if (!cachedIntents.intents.find((i) => i.name === pi.name)) {
+            cachedIntents.intents.push(pi);
+        }
+    }
     return cachedIntents.intents;
 }
 export function getIntentDef(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notoken-core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Shared engine for notoken — NLP parsing, execution, detection, analysis",
   "type": "module",
   "license": "MIT",