@xeplr/actions 1.1.1

package/LICENSE

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

package/index.js

@@ -0,0 +1,51 @@
+var registry  = require('./lib/registry');
+var runner    = require('./lib/runner');
+var errors    = require('./lib/errors');
+var builtins  = require('./lib/builtins');
+var uploader  = require('./lib/uploader');
+var streaming = require('./lib/streaming');
+var dbDrivers = require('./lib/drivers/db');
+var fileDrivers = require('./lib/drivers/file');
+var formats   = require('./lib/formats');
+var configDb  = require('./lib/uploader/attach');
+
+module.exports = {
+  // Registry
+  register:      registry.register,
+  get:           registry.get,
+  has:           registry.has,
+  list:          registry.list,
+  clear:         registry.clear,
+
+  // Safe invocation — two forms:
+  //   runAction({ name, input, system?, timeoutMs? })
+  //   runAction(nameOrAction, input, opts?)
+  runAction:     runner.runAction,
+
+  // Errors
+  ActionNotRegisteredError:     errors.ActionNotRegisteredError,
+  ActionMissingDependencyError: errors.ActionMissingDependencyError,
+  TransientError:               errors.TransientError,
+
+  // Built-in actions
+  //   var { register, builtins } = require('@xeplr/actions');
+  //   register(builtins.sendEmail);                    ← simple
+  //   register(builtins.fileUpload({ metaKnex }));     ← factory-shaped when config is needed
+  builtins:      builtins,
+
+  // Primitives (used internally by actions and exposed for consumers writing
+  // their own — e.g. a UI wizard showing inferred columns from a CSV sample
+  // before actually committing to an import).
+  uploader:      uploader,
+  inferColumns:  uploader.inferColumns,
+  streaming:     streaming,
+  drivers:       { db: dbDrivers, file: fileDrivers },
+  formats:       formats,
+
+  // xeplr_configs — shared control-plane DB (import/movement metadata).
+  // One call per app: attachConfig({ service }); await xcfg.ready(). See
+  // lib/uploader/attach.js. configRequiredEnv spreads into the app's own
+  // env.required.js, same convention as @xeplr/auth's requiredEnv.
+  attachConfig:      configDb.attachConfig,
+  configRequiredEnv: configDb.requiredEnv
+};

package/lib/builtins/db/fetch.js

@@ -0,0 +1,142 @@
+// db-fetch action — routes to getDriver(input.dbType), then streams rows out
+// of the source via driver.fetchStream (a server-side cursor / native stream,
+// never buffering the whole result set).
+//
+// STREAMING BY DEFAULT. Unlike the older builtins convention (streaming_mode
+// defaults false), db-fetch defaults streaming_mode=TRUE: rows are spooled to
+// an NDJSON temp file and the action returns { filePath, format, bytes, rows }.
+// That output plugs straight into db-push's `filePath` input for cross-engine
+// replication with a bounded memory footprint at both ends.
+//
+// Set streaming_mode:false ONLY for known-small reads — it buffers the full
+// result set into output.rows (still read via the streaming cursor internally).
+//
+//   modes:
+//     'table'  → SELECT * FROM <table>            (input.table required)
+//     'query'  → raw input.sql (+ input.params)   (input.sql required)
+//   Temp file: XEPLR_ACTIONS_TMP_DIR (default os.tmpdir()/xeplr-actions),
+//   named <occurrenceId>_db-fetch_<seq>.jsonl. Cleanup: none in-action — rely
+//   on the sweep-temp-files action (or db-push after it consumes the file).
+
+var dbDrivers  = require('../../drivers/db');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+var os = require('os');
+var path = require('path');
+var fs = require('fs');
+var fsp = require('fs/promises');
+
+module.exports = {
+  name: 'db-fetch',
+  description: 'Stream rows out of a source DB table or query. Streaming by default: ' +
+               'spools to an NDJSON file (output.filePath) consumable by db-push. ' +
+               'Routes to the driver named by input.dbType.',
+  requires: [],   // per-driver requires checked at runtime once dbType is known
+
+  inputSchema: [
+    { name: 'dbType',         type: 'string',  required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql' },
+    { name: 'connection',     type: 'object',  required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'mode',           type: 'string',  default: 'table', order: 3,
+      description: '"table" (SELECT * FROM input.table) or "query" (raw input.sql)' },
+    { name: 'table',          type: 'string',  order: 4,
+      description: 'Source table name (mode="table").' },
+    { name: 'sql',            type: 'string',  order: 5,
+      description: 'Raw SQL to stream (mode="query").' },
+    { name: 'params',         type: 'array',   order: 6,
+      description: 'Bind params for mode="query".' },
+    { name: 'streaming_mode', type: 'boolean', default: true, order: 7,
+      description: 'Default TRUE → spool to NDJSON file. false → inline output.rows (small reads only).' },
+    { name: 'batchSize',      type: 'number',  default: 1000, order: 8,
+      description: 'Rows pulled per cursor round-trip / stream highWaterMark.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-fetch', input.dbType, driver);
+    if (typeof driver.fetchStream !== 'function') {
+      throw new Error('db-fetch: driver "' + input.dbType + '" does not implement fetchStream yet');
+    }
+
+    var built = buildFetchSql(driver, input);
+    var streaming = input.streaming_mode !== false;   // default TRUE
+    var pool = await driver.connect(input.connection);
+
+    try {
+      var rowStream = driver.fetchStream(pool, {
+        sql: built.sql, params: built.params, batchSize: input.batchSize || 1000
+      });
+
+      if (!streaming) {
+        var rows = [];
+        for await (var row of rowStream) rows.push(row);
+        return { rows: rows, rowCount: rows.length, streaming: false };
+      }
+
+      var filePath = await resolveOutputPath(system);
+      var stats = await writeNDJSON(filePath, rowStream);
+      return {
+        filePath:  filePath,
+        format:    'jsonl',
+        bytes:     stats.bytes,
+        rows:      stats.rows,
+        streaming: true
+      };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function buildFetchSql(driver, input) {
+  var mode = input.mode || (input.table ? 'table' : 'query');
+  if (mode === 'table') {
+    if (!input.table) throw new Error('db-fetch: mode "table" requires input.table');
+    return { sql: 'SELECT * FROM ' + driver.quoteIdent(input.table), params: [] };
+  }
+  if (mode === 'query') {
+    if (!input.sql) throw new Error('db-fetch: mode "query" requires input.sql');
+    return { sql: input.sql, params: input.params || [] };
+  }
+  throw new Error('db-fetch: unsupported mode "' + mode + '" (use "table" or "query")');
+}
+
+
+async function resolveOutputPath(system) {
+  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  await fsp.mkdir(dir, { recursive: true });
+  var base = (system.occurrenceId || generateId()) + '_db-fetch_' + generateId() + '.jsonl';
+  return path.join(dir, base);
+}
+// Write an async iterable of rows to an NDJSON file, honoring write
+// backpressure (await 'drain' when the OS buffer is full). One JSON object
+// per line — the exact shape db-push's filePath reader expects.
+async function writeNDJSON(filePath, rowIterable) {
+  var ws = fs.createWriteStream(filePath, { encoding: 'utf8' });
+  var rows = 0;
+  var bytes = 0;
+  try {
+    for await (var row of rowIterable) {
+      var line = JSON.stringify(row) + '\n';
+      bytes += Buffer.byteLength(line);
+      rows++;
+      if (!ws.write(line)) {
+        await new Promise(function(resolve, reject) {
+          ws.once('drain', resolve);
+          ws.once('error', reject);
+        });
+      }
+    }
+  } finally {
+    await new Promise(function(resolve, reject) {
+      ws.end(resolve);
+      ws.once('error', reject);
+    });
+  }
+  return { rows: rows, bytes: bytes };
+}

package/lib/builtins/db/list-columns.js

@@ -0,0 +1,39 @@
+// db-list-columns action — wraps each driver's existing getTableSchema
+// (already used internally by uploader.reconcile) as a standalone action:
+// column name + data type for one named table.
+
+var dbDrivers = require('../../drivers/db');
+
+module.exports = {
+  name: 'db-list-columns',
+  description: 'List a table\'s columns (name + data type). Routes to the driver named by input.dbType.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'dbType',     type: 'string', required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'table',      type: 'string', required: true, order: 3,
+      description: 'Table name to introspect' },
+    { name: 'schema',     type: 'string', order: 4,
+      description: 'Schema the table lives in (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-list-columns', input.dbType, driver);
+    if (typeof driver.getTableSchema !== 'function') {
+      throw new Error('db-list-columns: driver "' + input.dbType + '" does not implement getTableSchema yet');
+    }
+
+    var pool = await driver.connect(input.connection);
+    try {
+      var columns = await driver.getTableSchema(pool, input.table, input.schema);
+      return { columns: columns };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/db/list-procedures.js

@@ -0,0 +1,36 @@
+// db-list-procedures action — same shape as db-list-tables, lists stored
+// procedures instead (excludes functions — see each driver's listProcedures).
+
+var dbDrivers = require('../../drivers/db');
+
+module.exports = {
+  name: 'db-list-procedures',
+  description: 'List stored procedure names in a schema/database. Routes to the driver named by input.dbType.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'dbType',     type: 'string', required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'schema',     type: 'string', order: 3,
+      description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-list-procedures', input.dbType, driver);
+    if (typeof driver.listProcedures !== 'function') {
+      throw new Error('db-list-procedures: driver "' + input.dbType + '" does not implement listProcedures yet');
+    }
+
+    var pool = await driver.connect(input.connection);
+    try {
+      var procedures = await driver.listProcedures(pool, input.schema);
+      return { procedures: procedures };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/db/list-tables.js

@@ -0,0 +1,38 @@
+// db-list-tables action — routes to getDriver(input.dbType) and lists base
+// tables (never views) visible to the given schema/database. Small metadata
+// read, no streaming — parity with db-fetch/db-push on connection lifecycle
+// only (connect, use, close).
+
+var dbDrivers = require('../../drivers/db');
+
+module.exports = {
+  name: 'db-list-tables',
+  description: 'List base table names in a schema/database. Routes to the driver named by input.dbType.',
+  requires: [],   // per-driver requires checked at runtime once dbType is known
+
+  inputSchema: [
+    { name: 'dbType',     type: 'string', required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'schema',     type: 'string', order: 3,
+      description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-list-tables', input.dbType, driver);
+    if (typeof driver.listTables !== 'function') {
+      throw new Error('db-list-tables: driver "' + input.dbType + '" does not implement listTables yet');
+    }
+
+    var pool = await driver.connect(input.connection);
+    try {
+      var tables = await driver.listTables(pool, input.schema);
+      return { tables: tables };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/db/list-views.js

@@ -0,0 +1,35 @@
+// db-list-views action — same shape as db-list-tables, lists views instead.
+
+var dbDrivers = require('../../drivers/db');
+
+module.exports = {
+  name: 'db-list-views',
+  description: 'List view names in a schema/database. Routes to the driver named by input.dbType.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'dbType',     type: 'string', required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'schema',     type: 'string', order: 3,
+      description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-list-views', input.dbType, driver);
+    if (typeof driver.listViews !== 'function') {
+      throw new Error('db-list-views: driver "' + input.dbType + '" does not implement listViews yet');
+    }
+
+    var pool = await driver.connect(input.connection);
+    try {
+      var views = await driver.listViews(pool, input.schema);
+      return { views: views };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/db/push.js

@@ -0,0 +1,107 @@
+// db-push action — pushes rows into a target DB table.
+//
+// Composes: drivers.db.<type> + uploader.upload + SqlQueue
+//
+// Inputs accept EITHER `rows` (inline) OR `filePath` (NDJSON, one row per line
+// — matches spool()'s output shape). The action creates its own SqlQueue per
+// call and tears it down when done; movement lifecycle is fully self-contained.
+
+var { upload } = require('../../uploader');
+var dbDrivers  = require('../../drivers/db');
+var { SqlQueue } = require('@xeplr/utils/lib/queue');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+var fs = require('fs');
+var readline = require('readline');
+
+module.exports = {
+  name: 'db-push',
+  description: 'Push rows into a target DB table. Supports UPSERT via primaryKeys, ' +
+               'NDJSON streaming via filePath, movement-scoped rollback, and error-table ' +
+               'routing on failure. Routes to the driver named by input.dbType.',
+  requires: [],   // per-driver requires checked at runtime once dbType is known
+
+  inputSchema: [
+    { name: 'dbType',      type: 'string',  required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql | mongo' },
+    { name: 'connection',  type: 'object',  required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database }' },
+    { name: 'targetTable', type: 'string',  required: true, order: 3 },
+    { name: 'primaryKeys', type: 'array',   order: 4,
+      description: 'Column names for UPSERT. Empty/omitted = plain INSERT.' },
+    { name: 'rows',        type: 'array',   order: 5,
+      description: 'Inline rows (mutually exclusive with filePath).' },
+    { name: 'filePath',    type: 'string',  order: 6,
+      description: 'Path to an NDJSON file (one row per line). Use for large uploads.' },
+    { name: 'movementId',  type: 'string',  order: 7,
+      description: 'Correlation key for rollback. Defaults to system.occurrenceId or a fresh id.' },
+    { name: 'batchSize',   type: 'number',  default: 5000, order: 8 },
+    { name: 'concurrency', type: 'number',  default: 4,    order: 9 }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-push', input.dbType, driver);
+
+    var movementId = input.movementId || system.occurrenceId || ('mv_' + generateId());
+    var source = resolveSource(input);
+
+    var pool = await driver.connect(input.connection);
+    var connectionName = input.targetTable;
+    var connections = {};
+    connections[connectionName] = pool;
+
+    var queue = new SqlQueue({
+      connections: connections,
+      // Route through driver.query, not conn.query directly: each driver
+      // normalizes the result shape AND binds params dialect-correctly
+      // (pg/mysql take a positional array; mssql needs request.input @p0..@pN).
+      executor: async function(item, conn) { await driver.query(conn, item.sql, item.params || []); },
+      concurrency: input.concurrency || 4,
+      maxAttempts: 3
+    });
+
+    try {
+      return await upload({
+        source:              source,
+        driver:              driver,
+        connection:          pool,
+        targetTable:         input.targetTable,
+        primaryKeys:         (input.primaryKeys && input.primaryKeys.length) ? input.primaryKeys : null,
+        movementId:          movementId,
+        queue:               queue,
+        connectionName:      connectionName,
+        dbType:              input.dbType,       // recorded in import_meta
+        // Movement metadata persists to xeplr_config when the framework supplies
+        // a meta store (meta-store-knex bound to xeplr_config); else no-op.
+        metaStore:           ctx.metaStore,
+        batchSize:           input.batchSize
+      });
+    } finally {
+      queue.stop();
+      await driver.close(pool);
+    }
+  }
+};
+
+// Return an async iterable for whichever input shape the caller supplied.
+function resolveSource(input) {
+  if (Array.isArray(input.rows) && input.rows.length > 0) return asyncFromArray(input.rows);
+  if (input.filePath)                                     return asyncFromNDJSONFile(input.filePath);
+  throw new Error('db-push: either input.rows (non-empty) or input.filePath is required');
+}
+
+async function* asyncFromArray(rows) {
+  for (var i = 0; i < rows.length; i++) yield rows[i];
+}
+
+async function* asyncFromNDJSONFile(filePath) {
+  var stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+  var rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  for await (var line of rl) {
+    if (line.trim().length === 0) continue;
+    yield JSON.parse(line);
+  }
+}

package/lib/builtins/db/query.js

@@ -0,0 +1,5 @@
+// db-query action — routes to getDriver(input.dbType) and runs a raw
+// query or procedure. Streaming semantics identical to db-fetch:
+// streaming_mode=true → output.filePath instead of output.rows.
+//
+// Implementation pending user spec.

package/lib/builtins/file/move.js

@@ -0,0 +1,8 @@
+// file-move action — copies/moves files or entire directories from one
+// location to another. Source + target can each be local/sharepoint/google
+// (i.e. it uses getSource(sourceType) on both ends).
+//
+// Streaming: always streamed when files are large. Input flag:
+//   { operation: 'copy' | 'move', overwrite: boolean }
+//
+// Implementation pending user spec.

package/lib/builtins/file/upload.js

@@ -0,0 +1,123 @@
+// file-upload action — read from a file source (local / sftp / sharepoint /
+// google), parse via a format (csv / excel / txt / json), push to a target DB.
+//
+// The full pipe: [source stream] → [format parser] → [rows async iterable]
+//                → [uploader.upload → SqlQueue → DB]
+//
+// Composed from primitives that are all separately usable — a consumer that
+// just wants "give me rows from this CSV without touching a DB" can call
+// getFormat('csv').parseStream(fs.createReadStream(path)) directly.
+
+var { upload } = require('../../uploader');
+var fileSources = require('../../drivers/file');
+var formats     = require('../../formats');
+var dbDrivers   = require('../../drivers/db');
+var { SqlQueue } = require('@xeplr/utils/lib/queue');
+var { generateId } = require('@xeplr/utils/lib/helpers');
+
+module.exports = {
+  name: 'file-upload',
+  description: 'Read a file (CSV / Excel / JSON / TXT) from a source ' +
+               '(local / sftp / sharepoint / google) and push rows into a target DB table. ' +
+               'Types + columns are inferred from the first N rows.',
+  requires: [],   // per-source/format/driver checks happen at runtime
+
+  inputSchema: [
+    // SOURCE
+    { name: 'sourceType',    type: 'string',  required: true, default: 'local', order: 1,
+      description: 'local | sftp | sharepoint | google' },
+    { name: 'sourcePath',    type: 'string',  required: true, order: 2,
+      description: 'File path (local) or key/id (remote sources)' },
+    { name: 'sourceConfig',  type: 'object',  default: {}, order: 3,
+      description: 'Source-specific config (SFTP creds, SharePoint site, etc.)' },
+
+    // FORMAT
+    { name: 'format',        type: 'string',  required: true, default: 'csv', order: 4,
+      description: 'csv | excel | txt | json' },
+    { name: 'formatConfig',  type: 'object',  default: {}, order: 5,
+      description: 'Format-specific options (delimiter, sheet name, etc.)' },
+
+    // TARGET
+    { name: 'dbType',        type: 'string',  required: true, default: 'postgres', order: 10 },
+    { name: 'dbConnection',  type: 'object',  required: true, order: 11 },
+    { name: 'targetTable',   type: 'string',  required: true, order: 12 },
+    { name: 'primaryKeys',   type: 'array',   order: 13 },
+
+    // CONTROL
+    { name: 'movementId',    type: 'string',  order: 20 },
+    { name: 'batchSize',     type: 'number',  default: 5000, order: 21 },
+    { name: 'concurrency',   type: 'number',  default: 4,    order: 22 }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+
+    // Resolve source + format + target driver up front so any missing peer
+    // dep throws with a clear message before we start touching resources.
+    var source = fileSources.getSource(input.sourceType);
+    fileSources.checkSourceRequires('file-upload', input.sourceType, source);
+
+    var format = formats.getFormat(input.format);
+    formats.checkFormatRequires('file-upload', input.format, format);
+
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('file-upload', input.dbType, driver);
+
+    // Some formats need a stream (csv, json, txt — pure pipe semantics);
+    // some need a file path (xlsx — the zip central directory is at the file
+    // tail so unzipper must seek). The format declares which via `inputMode`;
+    // sources implement whichever their transport can serve.
+    var sourceCfg = Object.assign({}, input.sourceConfig, { path: input.sourcePath });
+    var rowsIterable;
+    if (format.inputMode === 'path') {
+      if (typeof source.openPath !== 'function') {
+        throw new Error("file-upload: format '" + input.format + "' requires a file path but source '" +
+                        input.sourceType + "' does not implement openPath(). Add openPath() to the source " +
+                        "(local sources should return config.path; remote sources should download to a tmp path).");
+      }
+      var filePath = await source.openPath(sourceCfg);
+      rowsIterable = format.parsePath(filePath, input.formatConfig || {});
+    } else {
+      var stream = await source.openStream(sourceCfg);
+      rowsIterable = format.parseStream(stream, input.formatConfig || {});
+    }
+
+    // Set up target
+    var movementId = input.movementId || system.occurrenceId || ('mv_' + generateId());
+    var pool = await driver.connect(input.dbConnection);
+    var connections = {};
+    connections[input.targetTable] = pool;
+
+    var queue = new SqlQueue({
+      connections: connections,
+      executor: async function(item, conn) { await conn.query(item.sql, item.params || []); },
+      concurrency: input.concurrency || 4,
+      maxAttempts: 3
+    });
+
+    try {
+      return await upload({
+        source:         rowsIterable,
+        driver:         driver,
+        connection:     pool,
+        targetTable:    input.targetTable,
+        primaryKeys:    (input.primaryKeys && input.primaryKeys.length) ? input.primaryKeys : null,
+        movementId:     movementId,
+        queue:          queue,
+        connectionName: input.targetTable,
+        dbType:         input.dbType,   // recorded in import_meta
+        batchSize:      input.batchSize,
+        // Movement metadata persists to xeplr_configs when the caller supplies
+        // a meta store (meta-store-knex); else no-op. mtId1-4/details are
+        // opaque tenant/app context — see runner.js's ctx.system passthrough.
+        metaStore:      ctx.metaStore,
+        mtId1: system.mtId1, mtId2: system.mtId2, mtId3: system.mtId3, mtId4: system.mtId4,
+        details:        system.details
+      });
+    } finally {
+      queue.stop();
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/http-request.js

@@ -0,0 +1,3 @@
+// http-request action — generic HTTP client with optional auth pre-call.
+// Uses Node's built-in fetch (Node 18+). No peer deps.
+// Implementation pending user spec.

package/lib/builtins/index.js

@@ -0,0 +1,40 @@
+// Built-in actions bundled with @xeplr/actions.
+// Each entry is a module — registerAction(mod) picks up the name from mod.name.
+// Placeholders throw at register/run time until specced.
+//
+// Streaming convention (uniform across db/ and file/ actions):
+//   - Inputs may include `streaming_mode: boolean` (default false).
+//   - When true, reads write to a temp file (rotating NDJSON for db rows,
+//     raw for files) and return { filePath | dirPath, format, bytes, ... }
+//     in the output.
+//   - When false, data stays inline in output.rows / output.content.
+//   - Writes may accept EITHER `rows: []` OR a spooled `filePath`/`dirPath`.
+//   - Temp dir: XEPLR_ACTIONS_TMP_DIR env var, default os.tmpdir() + '/xeplr-actions/'.
+//
+// Uploader primitive (lib/uploader/) handles DDL, type inference, TZ, batch
+// bisection, and error-table routing. The DB actions here compose it with
+// the appropriate driver.
+
+module.exports = {
+  // Generic actions (no runtime-config dependency)
+  httpRequest:  require('./http-request'),
+  spawnProgram: require('./spawn-program'),
+  sendEmail:    require('./send-email'),
+
+  // DB actions — factory-shaped (call fileUpload({ metaKnex }) to get a
+  // registerable module) so the Knex handle for the meta store binds at
+  // configuration time, not runtime.
+  dbFetch:      require('./db/fetch'),
+  dbPush:       require('./db/push'),
+  dbQuery:      require('./db/query'),
+
+  // DB introspection — list tables/views/procedures, or one table's columns.
+  dbListTables:     require('./db/list-tables'),
+  dbListViews:      require('./db/list-views'),
+  dbListProcedures: require('./db/list-procedures'),
+  dbListColumns:    require('./db/list-columns'),
+
+  // File actions — factory-shaped for the same reason (meta store binding).
+  fileUpload:   require('./file/upload'),
+  fileMove:     require('./file/move')
+};