@caracal-lynx/sluice 0.1.0

package/dist/plugins/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+export { RuleRegistry, TransformRegistry } from './registry.js';
+export { loadPlugins, loadNpmPlugins } from './loader.js';
+//# sourceMappingURL=index.js.map

package/dist/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugins/loader.d.ts

@@ -0,0 +1,22 @@
+import type { MergeStrategyRegistry } from '../merge/index.js';
+import type { RuleRegistry, TransformRegistry } from './registry.js';
+/**
+ * Scan `pluginDir` for `*.rule.{ts,js}` and `*.transform.{ts,js}` files,
+ * import each one, and register the exported `rule` / `transform` with the
+ * supplied registries.
+ *
+ * Silently returns if `pluginDir` does not exist.
+ * Throws `ConfigError` if a file is found but does not export a valid plugin.
+ */
+export declare function loadPlugins(pluginDir: string, rules: RuleRegistry, transforms: TransformRegistry, mergeStrategies?: typeof MergeStrategyRegistry): Promise<void>;
+/**
+ * Read `sluice.config.yaml` at `configPath`, parse it with
+ * `ToolkitConfigSchema`, then import each declared npm package and call its
+ * `plugin.register()` function.
+ *
+ * Silently returns if `configPath` does not exist.
+ * Throws `ConfigError` for unreadable config files, packages that fail to
+ * import, or packages that do not export `plugin.register`.
+ */
+export declare function loadNpmPlugins(configPath: string, rules: RuleRegistry, transforms: TransformRegistry, mergeStrategies?: typeof MergeStrategyRegistry): Promise<void>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/plugins/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAK/D,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AA0BrE;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,iBAAiB,EAC7B,eAAe,CAAC,EAAE,OAAO,qBAAqB,GAC7C,OAAO,CAAC,IAAI,CAAC,CAmEf;AAID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,iBAAiB,EAC7B,eAAe,CAAC,EAAE,OAAO,qBAAqB,GAC7C,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dist/plugins/loader.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+/**
+ * Sluice — plugin loader
+ * @caracal-lynx/sluice
+ *
+ * Tier 2: discovers *.rule.{ts,js} and *.transform.{ts,js} files from a
+ * plugins directory and registers them with the provided registries.
+ *
+ * Tier 3: reads sluice.config.yaml, imports declared npm packages, and
+ * calls each package's register() function.
+ *
+ * Neither function throws if the directory / config file does not exist —
+ * both are optional for any given project.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { load as yamlLoad } from 'js-yaml';
+import { ToolkitConfigSchema } from '../config/schema.js';
+import { ConfigError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+// ── Internal helpers ──────────────────────────────────────────────────────────
+async function dirExists(p) {
+    try {
+        const stat = await fs.stat(p);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively list all files under `dir` whose name ends with one of the
+ * given `suffixes`, returning absolute paths.
+ */
+async function findFiles(dir, suffixes) {
+    const entries = await fs.readdir(dir, { recursive: true });
+    return entries
+        .filter(e => suffixes.some(s => e.endsWith(s)))
+        .map(e => path.resolve(path.join(dir, e)));
+}
+// ── Tier 2: file-based plugins ────────────────────────────────────────────────
+/**
+ * Scan `pluginDir` for `*.rule.{ts,js}` and `*.transform.{ts,js}` files,
+ * import each one, and register the exported `rule` / `transform` with the
+ * supplied registries.
+ *
+ * Silently returns if `pluginDir` does not exist.
+ * Throws `ConfigError` if a file is found but does not export a valid plugin.
+ */
+export async function loadPlugins(pluginDir, rules, transforms, mergeStrategies) {
+    if (!(await dirExists(pluginDir)))
+        return;
+    const ruleFiles = await findFiles(pluginDir, ['.rule.ts', '.rule.js']);
+    for (const file of ruleFiles) {
+        try {
+            const mod = (await import(pathToFileURL(file).href));
+            const plugin = mod['rule'];
+            if (typeof plugin?.id !== 'string' || typeof plugin.validate !== 'function') {
+                throw new Error('Plugin file must export: export const rule: RulePlugin with id and validate()');
+            }
+            rules.register(plugin);
+            logger.debug({ pluginId: plugin.id, file }, 'Registered rule plugin');
+        }
+        catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
+            throw new ConfigError(`Failed to load rule plugin "${path.basename(file)}": ${String(err)}`, err);
+        }
+    }
+    const transformFiles = await findFiles(pluginDir, ['.transform.ts', '.transform.js']);
+    for (const file of transformFiles) {
+        try {
+            const mod = (await import(pathToFileURL(file).href));
+            const plugin = mod['transform'];
+            if (typeof plugin?.id !== 'string' || typeof plugin.apply !== 'function') {
+                throw new Error('Plugin file must export: export const transform: TransformPlugin with id and apply()');
+            }
+            transforms.register(plugin);
+            logger.debug({ pluginId: plugin.id, file }, 'Registered transform plugin');
+        }
+        catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
+            throw new ConfigError(`Failed to load transform plugin "${path.basename(file)}": ${String(err)}`, err);
+        }
+    }
+    if (!mergeStrategies)
+        return;
+    const mergeFiles = await findFiles(pluginDir, ['.merge.ts', '.merge.js']);
+    for (const file of mergeFiles) {
+        try {
+            const mod = (await import(pathToFileURL(file).href));
+            const plugin = mod['mergeStrategy'];
+            if (typeof plugin?.id !== 'string' || typeof plugin.merge !== 'function') {
+                throw new Error('Plugin file must export: export const mergeStrategy: MergeStrategyPlugin with id and merge()');
+            }
+            mergeStrategies.register(plugin);
+            logger.debug({ pluginId: plugin.id, file }, 'Registered merge strategy plugin');
+        }
+        catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
+            throw new ConfigError(`Failed to load merge strategy plugin "${path.basename(file)}": ${String(err)}`, err);
+        }
+    }
+}
+// ── Tier 3: npm package plugins ───────────────────────────────────────────────
+/**
+ * Read `sluice.config.yaml` at `configPath`, parse it with
+ * `ToolkitConfigSchema`, then import each declared npm package and call its
+ * `plugin.register()` function.
+ *
+ * Silently returns if `configPath` does not exist.
+ * Throws `ConfigError` for unreadable config files, packages that fail to
+ * import, or packages that do not export `plugin.register`.
+ */
+export async function loadNpmPlugins(configPath, rules, transforms, mergeStrategies) {
+    try {
+        await fs.access(configPath);
+    }
+    catch {
+        return;
+    }
+    let raw;
+    try {
+        raw = yamlLoad(await fs.readFile(configPath, 'utf-8'));
+    }
+    catch (err) {
+        throw new ConfigError(`Failed to read toolkit config "${configPath}": ${String(err)}`, err);
+    }
+    const config = ToolkitConfigSchema.parse(raw);
+    for (const entry of config.plugins) {
+        try {
+            const pkg = (await import(entry.package));
+            const exported = (pkg['plugin'] ?? pkg['default']);
+            if (typeof exported?.register !== 'function') {
+                throw new Error(`Package "${entry.package}" must export plugin.register()`);
+            }
+            exported.register(rules, transforms, entry.options, mergeStrategies);
+            logger.info({ package: entry.package }, 'Loaded npm plugin package');
+        }
+        catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
+            throw new ConfigError(`Failed to load plugin package "${entry.package}": ${String(err)}`, err);
+        }
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/plugins/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAI5C,iFAAiF;AAEjF,KAAK,UAAU,SAAS,CAAC,CAAS;IAChC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,QAA2B;IAC/D,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAQ,OAAoB;SACzB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;SAC9C,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,iFAAiF;AAEjF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAiB,EACjB,KAAmB,EACnB,UAA6B,EAC7B,eAA8C;IAE9C,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;QAAE,OAAO;IAE1C,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IACvE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;YAChF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAA2B,CAAC;YACrD,IAAI,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAC5E,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACvB,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,wBAAwB,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW;gBAAE,MAAM,GAAG,CAAC;YAC1C,MAAM,IAAI,WAAW,CACnB,+BAA+B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,EACrE,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC;IACtF,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;YAChF,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAgC,CAAC;YAC/D,IAAI,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzE,MAAM,IAAI,KAAK,CACb,sFAAsF,CACvF,CAAC;YACJ,CAAC;YACD,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,6BAA6B,CAAC,CAAC;QAC7E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW;gBAAE,MAAM,GAAG,CAAC;YAC1C,MAAM,IAAI,WAAW,CACnB,oCAAoC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,EAC1E,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC,eAAe;QAAE,OAAO;IAE7B,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;YAChF,MAAM,MAAM,GAAG,GAAG,CAAC,eAAe,CAAoC,CAAC;YACvE,IAAI,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzE,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;YACJ,CAAC;YACD,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,kCAAkC,CAAC,CAAC;QAClF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW;gBAAE,MAAM,GAAG,CAAC;YAC1C,MAAM,IAAI,WAAW,CACnB,yCAAyC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,EAC/E,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,UAAkB,EAClB,KAAmB,EACnB,UAA6B,EAC7B,eAA8C;IAE9C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,kCAAkC,UAAU,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,EAC/D,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE9C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAA4B,CAAC;YACrE,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CASpC,CAAC;YACd,IAAI,OAAO,QAAQ,EAAE,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAC7C,MAAM,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;YAC9E,CAAC;YACD,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;YACrE,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,2BAA2B,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW;gBAAE,MAAM,GAAG,CAAC;YAC1C,MAAM,IAAI,WAAW,CACnB,kCAAkC,KAAK,CAAC,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,EAClE,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/plugins/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sluice — plugin registries
+ * @caracal-lynx/sluice
+ *
+ * RuleRegistry and TransformRegistry hold custom plugins loaded from
+ * file plugins (Tier 2) and npm packages (Tier 3). Built-in rules and
+ * transform types are NOT stored here — the DQ and transform engines
+ * consult built-ins first, then fall through to the registry.
+ */
+import type { RulePlugin, TransformPlugin } from './types.js';
+export declare class RuleRegistry {
+    private readonly plugins;
+    register(plugin: RulePlugin): void;
+    get(id: string): RulePlugin | undefined;
+    has(id: string): boolean;
+    list(): string[];
+}
+export declare class TransformRegistry {
+    private readonly plugins;
+    register(plugin: TransformPlugin): void;
+    get(id: string): TransformPlugin | undefined;
+    has(id: string): boolean;
+    list(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/plugins/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/plugins/registry.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9D,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAUlC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIvC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,IAAI,MAAM,EAAE;CAGjB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAUvC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI5C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/plugins/registry.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+import { ConfigError } from '../utils/errors.js';
+export class RuleRegistry {
+    plugins = new Map();
+    register(plugin) {
+        if (this.plugins.has(plugin.id)) {
+            throw new ConfigError(`Duplicate rule plugin id "${plugin.id}". ` +
+                `Check plugins/ folder and npm plugin packages for conflicts.`);
+        }
+        this.plugins.set(plugin.id, plugin);
+    }
+    get(id) {
+        return this.plugins.get(id);
+    }
+    has(id) {
+        return this.plugins.has(id);
+    }
+    list() {
+        return [...this.plugins.keys()];
+    }
+}
+export class TransformRegistry {
+    plugins = new Map();
+    register(plugin) {
+        if (this.plugins.has(plugin.id)) {
+            throw new ConfigError(`Duplicate transform plugin id "${plugin.id}". ` +
+                `Check plugins/ folder and npm plugin packages for conflicts.`);
+        }
+        this.plugins.set(plugin.id, plugin);
+    }
+    get(id) {
+        return this.plugins.get(id);
+    }
+    has(id) {
+        return this.plugins.has(id);
+    }
+    list() {
+        return [...this.plugins.keys()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/plugins/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/plugins/registry.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAavC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,OAAO,YAAY;IACN,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEzD,QAAQ,CAAC,MAAkB;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,WAAW,CACnB,6BAA6B,MAAM,CAAC,EAAE,KAAK;gBAC3C,8DAA8D,CAC/D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE9D,QAAQ,CAAC,MAAuB;QAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,WAAW,CACnB,kCAAkC,MAAM,CAAC,EAAE,KAAK;gBAChD,8DAA8D,CAC/D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/plugins/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Sluice — plugin interfaces
+ * @caracal-lynx/sluice
+ *
+ * Interfaces for Tier 2 (file plugins) and Tier 3 (npm package plugins).
+ * Plugins must be pure — no I/O, no side effects, no async.
+ */
+import type { CheckConfig } from '../config/types.js';
+import type { MergeStrategyRegistry } from '../merge/index.js';
+import type { RuleRegistry, TransformRegistry } from './registry.js';
+export interface RulePlugin {
+    /** Must match the 'type' key used in pipeline YAML checks. */
+    readonly id: string;
+    /** Optional human-readable description for error messages and profiling. */
+    readonly description?: string;
+    /**
+     * Validate a single cell value.
+     * Return null if valid; RuleViolation if not.
+     * Must be pure — no side effects, no I/O.
+     */
+    validate(value: unknown, config: CheckConfig, rowIndex: number, field: string): RuleViolation | null;
+}
+export interface RuleViolation {
+    field: string;
+    rowIndex: number;
+    value: unknown;
+    rule: string;
+    severity: 'critical' | 'warning' | 'info';
+    message: string;
+}
+export interface TransformPlugin {
+    /**
+     * Must match the 'customOp' key used in pipeline YAML field mappings.
+     * Used with: type: custom, customOp: <id>
+     */
+    readonly id: string;
+    readonly description?: string;
+    /**
+     * Transform a single source value.
+     * Receives the raw value and the full source row for cross-field operations.
+     * Return the transformed value. Return null to emit a null in the output.
+     * Throw TransformError for unrecoverable errors.
+     * Must be pure — no side effects, no I/O.
+     * Must not mutate the row object.
+     */
+    apply(value: unknown, row: Record<string, unknown>, config: CustomFieldMapping): unknown;
+}
+export interface CustomFieldMapping {
+    from?: string | string[];
+    to: string;
+    type: 'custom';
+    customOp: string;
+    /** Arbitrary per-plugin config from YAML, passed through verbatim. */
+    options?: Record<string, unknown>;
+    default?: unknown;
+    optional?: boolean;
+}
+export interface PluginPackage {
+    register(rules: RuleRegistry, transforms: TransformRegistry, options?: Record<string, unknown>, mergeStrategies?: typeof MergeStrategyRegistry): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIrE,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CACN,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,aAAa,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAK,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAK,OAAO,CAAC;IAClB,IAAI,EAAM,MAAM,CAAC;IACjB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC1C,OAAO,EAAG,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;OAOG;IACH,KAAK,CACH,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAK,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,EAAE,EAAQ,MAAM,CAAC;IACjB,IAAI,EAAM,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAID,MAAM,WAAW,aAAa;IAC5B,QAAQ,CACN,KAAK,EAAO,YAAY,EACxB,UAAU,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,eAAe,CAAC,EAAE,OAAO,qBAAqB,GAC7C,IAAI,CAAC;CACT"}

package/dist/plugins/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/plugins/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC"}

package/dist/runner.d.ts

@@ -0,0 +1,97 @@
+import type { ColumnMeta } from './staging/index.js';
+import { type ExtractResult } from './adapters/source/index.js';
+import { type LoadResult } from './adapters/target/index.js';
+import type { Pipeline } from './config/types.js';
+import { DQEngine, type DQSummary } from './dq/index.js';
+import type { EnrichPhaseFactory, EnrichSummary } from './enrich/types.js';
+import { StagingStore } from './staging/index.js';
+import { TransformEngine, type TransformResult } from './transform/index.js';
+import { RuleRegistry, TransformRegistry } from './plugins/registry.js';
+import { ProgressReporter } from './utils/progress.js';
+export declare function registerEnrichPhase(factory: EnrichPhaseFactory): void;
+/** Test-only helper. Not exported from `src/index.ts`. */
+export declare function _resetEnrichPhaseForTesting(): void;
+/** Test-only helper. Not exported from `src/index.ts`. */
+export declare function _isEnrichPhaseRegistered(): boolean;
+export interface RunResult {
+    pipeline: string;
+    mode: Pipeline['run']['mode'];
+    extract: ExtractResult;
+    dq: DQSummary;
+    transform: TransformResult | null;
+    load: LoadResult | null;
+    merge?: {
+        rowsMerged: number;
+        conflicts: number;
+        unmatched: number;
+    };
+    /** Phase 4a — populated when an `enrich:` block ran. */
+    enrichSummary?: EnrichSummary;
+    /** Path to the state JSON written at the end of a successful run. */
+    stateFilePath?: string;
+    /** Set by `sluice profile`; absent for other commands. */
+    profilePath?: string;
+}
+/** CLI-level overrides applied to the loaded Pipeline config. */
+export interface RunOverrides {
+    outputDir?: string;
+    dryRun?: boolean;
+    mode?: Pipeline['run']['mode'];
+    pluginDirs?: string[];
+    /** Set by `sluice run --no-enrich` to skip the Phase 4a enrich phase. */
+    skipEnrich?: boolean;
+    /**
+     * Optional progress reporter. CLI callers pass a live reporter; library
+     * callers (and tests) can omit it to get a silent no-op.
+     */
+    progress?: ProgressReporter;
+}
+export declare class PipelineRunner {
+    protected readonly ruleRegistry: RuleRegistry;
+    protected readonly transformRegistry: TransformRegistry;
+    protected readonly dqEngine: DQEngine;
+    protected readonly transformEngine: TransformEngine;
+    protected progress: ProgressReporter;
+    private pluginsLoaded;
+    private incrementalSinceUsed;
+    constructor(ruleRegistry?: RuleRegistry, transformRegistry?: TransformRegistry);
+    /**
+     * Load plugins from the file system and npm packages.
+     * Called once per runner instance at the start of the first pipeline run.
+     *
+     * - Tier 2: Scans `{cwd}/plugins/` for `*.rule.{ts,js}` and `*.transform.{ts,js}`.
+     * - Tier 3: Reads `{cwd}/sluice.config.yaml` for npm plugin declarations.
+     */
+    protected loadAllPlugins(cwd: string, pluginDirs?: string[]): Promise<void>;
+    run(yamlPath: string, overrides?: RunOverrides): Promise<RunResult>;
+    protected runExtract(config: Pipeline, store: StagingStore, tableName?: string, phaseLabel?: string): Promise<ExtractResult>;
+    protected runDQ(config: Pipeline, store: StagingStore, tableName?: string, _sourceId?: string, // Reserved for per-source filtering in MultiSourcePipelineRunner.
+    phaseLabel?: string): Promise<DQSummary>;
+    /**
+     * Phase 4a enrich phase. No-ops (returns `undefined`) when:
+     *   - the pipeline has no `enrich:` block;
+     *   - `--no-enrich` was set (`overrides.skipEnrich`);
+     *   - the run is `validate-only` or `dryRun`;
+     *   - `@caracal-lynx/sluice-enrich` is not installed (no factory registered).
+     *
+     * The "not installed" case logs a WARN so an operator who configured an
+     * `enrich:` block expecting it to run notices the misconfiguration.
+     */
+    protected runEnrich(config: Pipeline, store: StagingStore, pluginDir: string, overrides: RunOverrides): Promise<EnrichSummary | undefined>;
+    protected runTransform(config: Pipeline, store: StagingStore, sourceTable?: string, targetTable?: string): Promise<TransformResult>;
+    protected runLoad(config: Pipeline, store: StagingStore): Promise<LoadResult>;
+    protected writeStateFile(config: Pipeline, extract: ExtractResult, dq: DQSummary, load: LoadResult, enrichSummary?: EnrichSummary): Promise<string>;
+    /**
+     * `sluice profile` entry point — extract only, then emit per-column stats.
+     * Never writes an output CSV, never runs DQ or transforms.
+     */
+    profile(yamlPath: string, overrides?: RunOverrides): Promise<RunResult>;
+    private buildProfile;
+    protected applyOverrides(config: Pipeline, overrides: RunOverrides): Pipeline;
+    protected resolveStagingDb(config: Pipeline): string;
+    protected resolveIncrementalSince(config: Pipeline): Promise<string>;
+    protected applyIncrementalFilter(store: StagingStore, tableName: string, incrementalField: string, incrementalSince: string): Promise<void>;
+    protected materializeAcceptedRows(store: StagingStore, tableName: string, columns: ColumnMeta[], rejectedRowIndices: number[]): Promise<string>;
+    protected buildRunResult(config: Pipeline, extract: ExtractResult, dq: DQSummary, transform: TransformResult | null, load: LoadResult | null, enrichSummary?: EnrichSummary): RunResult;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}