@caracal-lynx/sluice 0.1.0

package/dist/transform/engine.js

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+/**
+ * TransformEngine — reads rows from `sourceTable`, applies field mappings
+ * (cleanse ops, type coercion, lookups, expressions, constants, concat, custom
+ * plugins), and writes to `targetTable`. Both tables default to
+ * `stg_raw` / `stg_transformed` so callers can reuse the engine for both the
+ * single-source path and the post-merge multi-source path.
+ *
+ * Every output column is stored as VARCHAR in the staging store. Target
+ * adapters re-emit as needed; DuckDB serialises values losslessly through
+ * the string representation.
+ */
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat.js';
+import { TransformRegistry } from '../plugins/registry.js';
+import { quoteIdent } from '../staging/index.js';
+import { TransformError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { applyCleanse } from './cleanse.js';
+import { ExpressionEvaluator } from './expression.js';
+import { LookupResolver } from './lookup.js';
+dayjs.extend(customParseFormat);
+export class TransformEngine {
+    transforms;
+    constructor(transforms = new TransformRegistry()) {
+        this.transforms = transforms;
+    }
+    async run(config, store, sourceTable = 'stg_raw', targetTable = 'stg_transformed', onProgress) {
+        const lookups = new LookupResolver();
+        await lookups.loadAll(config, config.run);
+        const expressionEval = new ExpressionEvaluator();
+        const outputColumns = config.transform.fields.map((f) => ({
+            name: f.to,
+            duckDbType: 'VARCHAR',
+        }));
+        await store.dropTable(targetTable);
+        await store.createTable(targetTable, outputColumns);
+        const rows = await store.query(`SELECT * FROM ${quoteIdent(sourceTable)}`);
+        const outputBatch = [];
+        const outputDateFormat = config.target.dateFormat;
+        let rowsFailed = 0;
+        for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            try {
+                const outRow = {};
+                for (const field of config.transform.fields) {
+                    outRow[field.to] = applyFieldMapping(field, row, lookups, expressionEval, this.transforms, outputDateFormat);
+                }
+                outputBatch.push(outRow);
+                if (outputBatch.length >= config.run.batchSize) {
+                    await store.insertBatch(targetTable, outputBatch);
+                    outputBatch.length = 0;
+                    if (onProgress)
+                        onProgress(i + 1);
+                }
+            }
+            catch (err) {
+                rowsFailed++;
+                if (config.run.onError === 'stop') {
+                    throw err instanceof TransformError
+                        ? err
+                        : new TransformError(`transform failed at row ${i}: ${String(err)}`, err);
+                }
+                logger.warn({ rowIndex: i, err: err instanceof Error ? err.message : String(err) }, 'transform: row failed (onError: continue)');
+            }
+        }
+        if (outputBatch.length > 0) {
+            await store.insertBatch(targetTable, outputBatch);
+        }
+        if (onProgress)
+            onProgress(rows.length);
+        const rowsOut = await store.rowCount(targetTable);
+        return { rowsIn: rows.length, rowsOut, rowsFailed };
+    }
+}
+function applyFieldMapping(field, row, lookups, expr, transforms, outputDateFormat) {
+    // ── Types that do not read `from` directly ──────────────────────────────
+    if (field.type === 'constant') {
+        return field.value ?? null;
+    }
+    if (field.type === 'expression') {
+        if (typeof field.value !== 'string') {
+            throw new TransformError(`expression field "${field.to}" requires string 'value'`);
+        }
+        return expr.evaluate(field.value, row);
+    }
+    if (field.type === 'custom') {
+        if (!field.customOp) {
+            throw new TransformError(`custom field "${field.to}" requires 'customOp'`);
+        }
+        const plugin = transforms.get(field.customOp);
+        if (!plugin) {
+            throw new TransformError(`No custom transform plugin registered for "${field.customOp}"`);
+        }
+        const value = typeof field.from === 'string' ? row[field.from] : undefined;
+        // Apply default/optional logic before calling plugin
+        if (value === null || value === undefined || value === '') {
+            if (field.default !== undefined && field.default !== null) {
+                return field.default;
+            }
+            else if (field.optional) {
+                return null;
+            }
+        }
+        // FieldMapping is schema-validated but not modeled as a discriminated union,
+        // so we narrow to the custom mapping shape at this call site.
+        const result = plugin.apply(value, row, field);
+        // Apply default/optional logic after plugin returns
+        if (result === null || result === undefined) {
+            if (field.default !== undefined && field.default !== null) {
+                return field.default;
+            }
+            else if (field.optional) {
+                return null;
+            }
+        }
+        return result;
+    }
+    // ── concat: join from[] with separator, then cleanse ────────────────────
+    if (field.type === 'concat') {
+        if (!Array.isArray(field.from)) {
+            throw new TransformError(`concat field "${field.to}" requires array 'from'`);
+        }
+        const sep = field.separator ?? ' ';
+        const parts = field.from.map((f) => {
+            const v = row[f];
+            return v === null || v === undefined ? '' : String(v);
+        });
+        let value = parts.join(sep);
+        if (field.cleanse)
+            value = applyCleanse(value, field.cleanse);
+        if (value === null || value === undefined || value === '') {
+            return applyDefaultOrOptional(field, value);
+        }
+        return String(value);
+    }
+    // ── lookup: resolve via LookupResolver ──────────────────────────────────
+    if (field.type === 'lookup') {
+        if (typeof field.from !== 'string') {
+            throw new TransformError(`lookup field "${field.to}" requires string 'from'`);
+        }
+        if (!field.lookup) {
+            throw new TransformError(`lookup field "${field.to}" requires 'lookup'`);
+        }
+        const sourceValue = row[field.from];
+        const resolved = lookups.resolve(field.lookup, sourceValue);
+        if (resolved !== undefined)
+            return resolved;
+        if (field.default !== undefined && field.default !== null)
+            return field.default;
+        if (field.optional)
+            return null;
+        throw new TransformError(`lookup "${field.lookup}" missed value "${String(sourceValue)}" for field "${field.to}"`);
+    }
+    // ── Scalar types: string, number, decimal, boolean, date ─────────────────
+    if (typeof field.from !== 'string') {
+        throw new TransformError(`field "${field.to}" of type ${field.type} requires string 'from'`);
+    }
+    let value = row[field.from];
+    // Default + optional: null/empty handling
+    if (value === null || value === undefined || value === '') {
+        if (field.default !== undefined && field.default !== null) {
+            value = field.default;
+        }
+        else if (field.optional) {
+            return null;
+        }
+        else if (field.type === 'string') {
+            // Empty strings pass through as-is for strings unless optional/default
+            value = value === null || value === undefined ? null : '';
+        }
+    }
+    if (field.cleanse && value !== null && value !== undefined) {
+        value = applyCleanse(value, field.cleanse);
+    }
+    if (value === null || value === undefined)
+        return null;
+    switch (field.type) {
+        case 'string': {
+            let s = String(value);
+            if (typeof field.max === 'number')
+                s = s.slice(0, field.max);
+            return s;
+        }
+        case 'number': {
+            const n = Number(value);
+            if (!Number.isFinite(n)) {
+                throw new TransformError(`field "${field.to}" value "${String(value)}" is not a number`);
+            }
+            return Math.round(n);
+        }
+        case 'decimal': {
+            const n = parseFloat(String(value));
+            if (!Number.isFinite(n)) {
+                throw new TransformError(`field "${field.to}" value "${String(value)}" is not a decimal`);
+            }
+            return n.toFixed(field.precision ?? 2);
+        }
+        case 'boolean': {
+            return ['1', 'true', 'yes', 'y', 't'].includes(String(value).toLowerCase())
+                ? 'true'
+                : 'false';
+        }
+        case 'date': {
+            const parsed = field.format
+                ? dayjs(String(value), field.format, true)
+                : dayjs(String(value));
+            if (!parsed.isValid()) {
+                throw new TransformError(`field "${field.to}" value "${String(value)}" is not a valid date (format: ${field.format ?? 'ISO'})`);
+            }
+            return outputDateFormat ? parsed.format(outputDateFormat) : parsed.toISOString();
+        }
+    }
+    // Unreachable — all cases covered above
+    return value;
+}
+function applyDefaultOrOptional(field, value) {
+    if (field.default !== undefined && field.default !== null)
+        return field.default;
+    if (field.optional)
+        return null;
+    return value;
+}
+//# sourceMappingURL=engine.js.map

package/dist/transform/engine.js.map

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

package/dist/transform/expression.d.ts

@@ -0,0 +1,5 @@
+export declare class ExpressionEvaluator {
+    private readonly warnedExpressions;
+    evaluate(expression: string, row: Record<string, unknown>): unknown;
+}
+//# sourceMappingURL=expression.d.ts.map

package/dist/transform/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../src/transform/expression.ts"],"names":[],"mappings":"AAsBA,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IAEvD,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;CAwCpE"}

package/dist/transform/expression.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+/**
+ * Expression evaluator.
+ *
+ * Two dispatch paths per CLAUDE.md:
+ *   - No `js:` prefix → expr-eval Parser (safe, limited to arithmetic + member access).
+ *   - `js:` prefix → vm.runInNewContext with a restricted global set.
+ *
+ * Neither path uses `eval()` or `new Function()`.
+ */
+import { runInNewContext } from 'node:vm';
+import { Parser } from 'expr-eval';
+import { ExpressionError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+const parser = new Parser();
+export class ExpressionEvaluator {
+    warnedExpressions = new Set();
+    evaluate(expression, row) {
+        if (expression.startsWith('js:')) {
+            const code = expression.slice(3).trim();
+            if (!this.warnedExpressions.has(code)) {
+                this.warnedExpressions.add(code);
+                logger.warn({ expression: code }, 'expression: using js: path (vm.runInNewContext)');
+            }
+            try {
+                return runInNewContext(code, {
+                    row,
+                    Date,
+                    Math,
+                    JSON,
+                    String,
+                    Number,
+                    Boolean,
+                }, { timeout: 1000 });
+            }
+            catch (err) {
+                throw new ExpressionError(`js expression failed: ${err instanceof Error ? err.message : String(err)}`, err);
+            }
+        }
+        try {
+            // expr-eval's Value type is narrower than Record<string, unknown>, but
+            // at runtime it only traverses property access — non-primitive leaves
+            // are fine as long as the expression doesn't operate on them.
+            return parser.parse(expression).evaluate({ row });
+        }
+        catch (err) {
+            throw new ExpressionError(`expr-eval expression failed: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+    }
+}
+//# sourceMappingURL=expression.js.map

package/dist/transform/expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.js","sourceRoot":"","sources":["../../src/transform/expression.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,EAAE,MAAM,EAAc,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;AAE5B,MAAM,OAAO,mBAAmB;IACb,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvD,QAAQ,CAAC,UAAkB,EAAE,GAA4B;QACvD,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACjC,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,iDAAiD,CAAC,CAAC;YACvF,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,eAAe,CACpB,IAAI,EACJ;oBACE,GAAG;oBACH,IAAI;oBACJ,IAAI;oBACJ,IAAI;oBACJ,MAAM;oBACN,MAAM;oBACN,OAAO;iBACR,EACD,EAAE,OAAO,EAAE,IAAI,EAAE,CAClB,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,eAAe,CACvB,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC3E,GAAG,CACJ,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,uEAAuE;YACvE,sEAAsE;YACtE,8DAA8D;YAC9D,OAAO,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAsB,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,eAAe,CACvB,gCAAgC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAClF,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/transform/index.d.ts

@@ -0,0 +1,6 @@
+export { applyCleanse } from './cleanse.js';
+export { TransformEngine } from './engine.js';
+export { ExpressionEvaluator } from './expression.js';
+export { LookupResolver } from './lookup.js';
+export type { TransformResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transform/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/transform/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+export { applyCleanse } from './cleanse.js';
+export { TransformEngine } from './engine.js';
+export { ExpressionEvaluator } from './expression.js';
+export { LookupResolver } from './lookup.js';
+//# sourceMappingURL=index.js.map

package/dist/transform/index.js.map

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

package/dist/transform/lookup.d.ts

@@ -0,0 +1,10 @@
+import type { Pipeline, RunConfig } from '../config/types.js';
+export declare class LookupResolver {
+    private readonly tables;
+    loadAll(config: Pipeline, runConfig: RunConfig): Promise<void>;
+    /** Returns the resolved value, or undefined on miss. */
+    resolve(lookupName: string, key: unknown): string | undefined;
+    /** Primarily for tests. */
+    getTable(name: string): ReadonlyMap<string, string> | undefined;
+}
+//# sourceMappingURL=lookup.d.ts.map

package/dist/transform/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/transform/lookup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK9D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAE3D,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCpE,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAS7D,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;CAGhE"}

package/dist/transform/lookup.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+/**
+ * LookupResolver — preloads every `transform.lookups[]` entry into an
+ * in-memory Map<string, string> keyed by name. Values stringified.
+ *
+ * Each lookup entry has its own `source` config (any source adapter works),
+ * so this resolver re-uses the global SourceAdapterRegistry to extract the
+ * lookup table into a temporary `:memory:` staging store, then copies the
+ * key/value pairs into the cache.
+ */
+import { SourceAdapterRegistry } from '../adapters/source/index.js';
+import { StagingStore, quoteIdent } from '../staging/index.js';
+import { TransformError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+export class LookupResolver {
+    tables = new Map();
+    async loadAll(config, runConfig) {
+        for (const lookup of config.transform.lookups) {
+            if (this.tables.has(lookup.name)) {
+                throw new TransformError(`Duplicate lookup name: "${lookup.name}"`);
+            }
+            const adapter = SourceAdapterRegistry.get(lookup.source.adapter);
+            const tempStore = new StagingStore(':memory:');
+            await tempStore.open();
+            try {
+                await adapter.connect(lookup.source);
+                try {
+                    await adapter.extract(lookup.source, tempStore, runConfig, () => { }, 'stg_lookup');
+                }
+                finally {
+                    await adapter.disconnect();
+                }
+                const rows = await tempStore.query(`SELECT ${quoteIdent(lookup.key)} AS k, ${quoteIdent(lookup.value)} AS v FROM stg_lookup`);
+                const map = new Map();
+                for (const row of rows) {
+                    const k = row['k'];
+                    const v = row['v'];
+                    if (k === null || k === undefined)
+                        continue;
+                    map.set(String(k), v === null || v === undefined ? '' : String(v));
+                }
+                this.tables.set(lookup.name, map);
+                logger.debug({ lookup: lookup.name, entries: map.size }, 'lookup: loaded');
+            }
+            finally {
+                await tempStore.close();
+            }
+        }
+    }
+    /** Returns the resolved value, or undefined on miss. */
+    resolve(lookupName, key) {
+        const table = this.tables.get(lookupName);
+        if (!table) {
+            throw new TransformError(`Unknown lookup: "${lookupName}"`);
+        }
+        if (key === null || key === undefined || key === '')
+            return undefined;
+        return table.get(String(key));
+    }
+    /** Primarily for tests. */
+    getTable(name) {
+        return this.tables.get(name);
+    }
+}
+//# sourceMappingURL=lookup.js.map

package/dist/transform/lookup.js.map

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

package/dist/transform/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Transform engine result. Phase 4 runner emits a trivial pass-through count;
+ * Phase 6 introduces the full engine with cleanse/expression/lookup.
+ */
+export interface TransformResult {
+    rowsIn: number;
+    rowsOut: number;
+    rowsFailed: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transform/types.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/transform/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/transform/types.js.map

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

package/dist/utils/env.d.ts

@@ -0,0 +1,3 @@
+export declare function loadEnv(envFile?: string): void;
+export declare function requireEnv(name: string): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/utils/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAQA,wBAAgB,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ9C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ/C"}

package/dist/utils/env.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+import { config as dotenvConfig } from 'dotenv';
+import { ConfigError } from './errors.js';
+let envLoaded = false;
+export function loadEnv(envFile) {
+    if (envLoaded)
+        return;
+    if (envFile !== undefined) {
+        dotenvConfig({ path: envFile });
+    }
+    else {
+        dotenvConfig();
+    }
+    envLoaded = true;
+}
+export function requireEnv(name) {
+    // Treat an explicitly-set empty string as set. "Not set" means the
+    // variable is absent from the environment, not that it is empty.
+    const value = process.env[name];
+    if (value === undefined) {
+        throw new ConfigError(`Required environment variable not set: ${name}`);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/utils/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,MAAM,UAAU,OAAO,CAAC,OAAgB;IACtC,IAAI,SAAS;QAAE,OAAO;IACtB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,YAAY,EAAE,CAAC;IACjB,CAAC;IACD,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,mEAAmE;IACnE,iEAAiE;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,0CAA0C,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class PipelineError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class ConfigError extends PipelineError {
+}
+export declare class SourceError extends PipelineError {
+}
+export declare class StagingError extends PipelineError {
+}
+export declare class DQError extends PipelineError {
+}
+export declare class PipelineDQError extends DQError {
+    readonly criticalCount: number;
+    readonly reportPath: string;
+    constructor(criticalCount: number, reportPath: string);
+}
+export declare class TransformError extends PipelineError {
+}
+export declare class ExpressionError extends TransformError {
+}
+export declare class LoadError extends PipelineError {
+}
+export declare class EnrichError extends PipelineError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,aAAc,SAAQ,KAAK;aACO,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAO7D;AACD,qBAAa,WAAY,SAAQ,aAAa;CAAG;AACjD,qBAAa,WAAY,SAAQ,aAAa;CAAG;AACjD,qBAAa,YAAa,SAAQ,aAAa;CAAG;AAClD,qBAAa,OAAQ,SAAQ,aAAa;CAAG;AAC7C,qBAAa,eAAgB,SAAQ,OAAO;aAExB,aAAa,EAAE,MAAM;aACrB,UAAU,EAAE,MAAM;gBADlB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM;CAIrC;AACD,qBAAa,cAAe,SAAQ,aAAa;CAAG;AACpD,qBAAa,eAAgB,SAAQ,cAAc;CAAG;AACtD,qBAAa,SAAU,SAAQ,aAAa;CAAG;AAC/C,qBAAa,WAAY,SAAQ,aAAa;CAAG"}

package/dist/utils/errors.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+export class PipelineError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = this.constructor.name;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+export class ConfigError extends PipelineError {
+}
+export class SourceError extends PipelineError {
+}
+export class StagingError extends PipelineError {
+}
+export class DQError extends PipelineError {
+}
+export class PipelineDQError extends DQError {
+    criticalCount;
+    reportPath;
+    constructor(criticalCount, reportPath) {
+        super(`Pipeline halted: ${criticalCount} critical DQ violations. See ${reportPath}`);
+        this.criticalCount = criticalCount;
+        this.reportPath = reportPath;
+    }
+}
+export class TransformError extends PipelineError {
+}
+export class ExpressionError extends TransformError {
+}
+export class LoadError extends PipelineError {
+}
+export class EnrichError extends PipelineError {
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC,MAAM,OAAO,aAAc,SAAQ,KAAK;IACO;IAA7C,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;CACF;AACD,MAAM,OAAO,WAAY,SAAQ,aAAa;CAAG;AACjD,MAAM,OAAO,WAAY,SAAQ,aAAa;CAAG;AACjD,MAAM,OAAO,YAAa,SAAQ,aAAa;CAAG;AAClD,MAAM,OAAO,OAAQ,SAAQ,aAAa;CAAG;AAC7C,MAAM,OAAO,eAAgB,SAAQ,OAAO;IAExB;IACA;IAFlB,YACkB,aAAqB,EACrB,UAAkB;QAElC,KAAK,CAAC,oBAAoB,aAAa,gCAAgC,UAAU,EAAE,CAAC,CAAC;QAHrE,kBAAa,GAAb,aAAa,CAAQ;QACrB,eAAU,GAAV,UAAU,CAAQ;IAGpC,CAAC;CACF;AACD,MAAM,OAAO,cAAe,SAAQ,aAAa;CAAG;AACpD,MAAM,OAAO,eAAgB,SAAQ,cAAc;CAAG;AACtD,MAAM,OAAO,SAAU,SAAQ,aAAa;CAAG;AAC/C,MAAM,OAAO,WAAY,SAAQ,aAAa;CAAG"}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { logger } from './logger.js';
+export { loadEnv, requireEnv } from './env.js';
+export { ProgressReporter, createSilentProgress, type PhaseKind, type PhaseEndState, type ProgressLogLevel, type ProgressReporterOptions, type StartPhaseOpts, type EndPhaseOpts, type SummaryOpts, } from './progress.js';
+export { PipelineError, ConfigError, SourceError, StagingError, DQError, PipelineDQError, TransformError, ExpressionError, LoadError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,OAAO,EACP,eAAe,EACf,cAAc,EACd,eAAe,EACf,SAAS,GACV,MAAM,aAAa,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+export { logger } from './logger.js';
+export { loadEnv, requireEnv } from './env.js';
+export { ProgressReporter, createSilentProgress, } from './progress.js';
+export { PipelineError, ConfigError, SourceError, StagingError, DQError, PipelineDQError, TransformError, ExpressionError, LoadError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GAQrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,OAAO,EACP,eAAe,EACf,cAAc,EACd,eAAe,EACf,SAAS,GACV,MAAM,aAAa,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,14 @@
+import pino from 'pino';
+/**
+ * Route all pino output to stderr so stdout stays dedicated to the progress
+ * bar rendered by `ProgressReporter`. This matches how tools like git, cargo,
+ * and npm separate streams:
+ *
+ *   stdout  → progress feedback and final summary (from ProgressReporter)
+ *   stderr  → all structured log records (info, warn, error, fatal)
+ *
+ * Operators who want just the logs in a file can use `2>run.log`; the bar
+ * stays visible on the terminal.
+ */
+export declare const logger: pino.Logger<never, boolean>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAGA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,6BAGlB,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright (c) 2026 Caracal Lynx Ltd.
+import pino from 'pino';
+/**
+ * Route all pino output to stderr so stdout stays dedicated to the progress
+ * bar rendered by `ProgressReporter`. This matches how tools like git, cargo,
+ * and npm separate streams:
+ *
+ *   stdout  → progress feedback and final summary (from ProgressReporter)
+ *   stderr  → all structured log records (info, warn, error, fatal)
+ *
+ * Operators who want just the logs in a file can use `2>run.log`; the bar
+ * stays visible on the terminal.
+ */
+export const logger = pino({ level: process.env['LOG_LEVEL'] ?? 'info' }, pino.destination({ fd: 2, sync: false }));
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uCAAuC;AAEvC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CACxB,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,MAAM,EAAE,EAC7C,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CACzC,CAAC"}