@xeplr/actions 1.4.3 → 1.4.4

package/README.md

@@ -123,8 +123,8 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `emailRead` | `email-read` | List messages, newest first, with `unread_only`, `limit` (1–1000, default 50), `since`, `from_equals`, `from_contains`, `subject_contains`, `body: 'full' \| 'text' \| 'none'`, optional NDJSON spooling. |
 | `emailMove` | `email-move` | Move a message (`messageId`, `folder`) to `toFolder`. |
 | `emailDelete` | `email-delete` | Flag `\Deleted` **and expunge** — permanent, not a move to Trash. |
-| `emailDownloadEmail` | `email-download-email` | Stream the raw message to an `.eml` file. `{ count, saved[], path }`. |
-| `emailDownloadAttachments` | `email-download-attachments` | Save attachments, optionally filtered by `extension` / `filenameContains`. `{ count, saved[], path, skipped }`. |
+| `emailDownloadEmail` | `email-download-email` | Stream the raw message to an `.eml` file, named by `fileName`. `{ count, saved[], path, existing[] }`. |
+| `emailDownloadAttachments` | `email-download-attachments` | Save attachments, optionally filtered by `extension` / `filenameContains`, named by `fileName` (see [Saving files](#saving-files-names-and-a-name-already-taken)). `{ count, saved[], path, skipped, existing[] }`. |
 | `httpRequest`, `spawnProgram`, `dbQuery`, `fileMove` | — | **Placeholders.** Empty modules with no `name` or `execute`; `register()` rejects them. |
 
 ### Connections
@@ -231,9 +231,42 @@ should not take the other eight hundred and ninety-nine with it.
 **No aggregation.** `group by status, count` changes what a row *is*; that is
 a different shape and, when it is wanted, a different step.
 
+## Saving files: names, and a name already taken
+
+Every action that saves a file follows one rule (`lib/fileNames.js`): `email-download-attachments`, `email-download-email` and `export-table`.
+
+**`fileName`** (the email steps) or **`outputPath`** (`export-table`) is a template with two kinds of placeholder:
+
+| | filled in by | examples |
+|---|---|---|
+| `{…}` | the workflow, before the step runs | `{trigger.window.from\|date:YYYY-MM}`, `{item.from}` |
+| `[…]` | the action, from the file itself | attachments: `[original]` `[name]` `[ext]` `[n]` `[id]`; a whole email: `[subject]` `[id]` `[ext]` |
+
+```
+Bank-{trigger.window.from|date:YYYY-MM:Asia/Kolkata}-[original]   →  Bank-2026-09-statement.csv
+```
+
+- **Why two kinds:** the engine fills every `{…}` first, so a file's own placeholders in `{…}` would be blanked before the action saw them.
+- **A placeholder the file does not have** is refused, listing the ones it has. A name that comes out empty is refused.
+- **A name never leaves its folder:** `/ \ : * ? " < > |` become `_`, and `.` or `..` is refused. Spaces are kept.
+- **No `fileName`:** a random prefix and the original name, as before.
+
+**`ifExists`**, when the name is already taken:
+
+| | |
+|---|---|
+| `fail` (default) | The step fails with `FILE_EXISTS`, naming the file, and **nothing is written**. A second run for the same period is caught, not repeated. |
+| `skip` | Not written; listed in `existing[]` (`export-table`: `skipped: true`), so the next step can branch on "already downloaded". |
+| `overwrite` | Replaced. Two files of one step with one name still get a suffix, so neither is lost. |
+| `addSuffix` | `Bank-2026-09 (2).csv`, the next free number. |
+
+Decided for the whole step before anything is written, so `fail` never leaves half a batch.
+
 ## Export
 
-`export-table` writes rows that arrive **already presented**: which columns, in what order, under what heading, and for each cell its raw value and the text a reader saw. The action knows nothing of reports or pivots; the caller decides all that (in xeplr-bi, `report-engine`'s `presentTable` does). Each format takes what it needs:
+**From a workflow:** `rows` can be plain records, as a fetch or the data step gives them (`{ ref: 'A1', amount: 500 }`). Columns pick them by `key` (default: the header). With no columns, every field of the first row, in order. `outputPath` follows [Saving files](#saving-files-names-and-a-name-already-taken).
+
+`export-table` also writes rows that arrive **already presented**: which columns, in what order, under what heading, and for each cell its raw value and the text a reader saw. The action knows nothing of reports or pivots; the caller decides all that (in xeplr-bi, `report-engine`'s `presentTable` does). Each format takes what it needs:
 
 | format | writes | from |
 |---|---|---|
@@ -484,20 +517,26 @@ await driver.query(pool, userSql, params)          // reads only
 
 ## Tests
 
-There is no `npm test` script. The tests use `node:test`; run a file directly:
-
 ```sh
+npm test                                   # every folder of test/, one file at a time
+PG_HOST=localhost PG_USER=$USER npm test   # the same, with the Postgres suites running
 node --test test/uploader/reconcile.test.js
 ```
 
-| needs nothing | needs a database |
-|---|---|
-| `test/import-modes.test.js` (DuckDB in memory; its Postgres cases run when `PG_HOST`/`PG_PORT`/`PG_USER`/`PG_PASSWORD`/`PG_DATABASE` are set, its MySQL cases when `MYSQL_HOST`/`MYSQL_PORT`/`MYSQL_USER`/`MYSQL_PASSWORD` are), `test/formats/pasted-rows.test.js` (its last case loads into Postgres when `PG_HOST`/`PG_PORT`/`PG_USER`/`PG_PASSWORD`/`PG_DATABASE` are set, else skipped), `test/procedure-call.test.js`, `test/streaming/spool.test.js`, `test/uploader/reconcile.test.js`, `test/write-progress.test.js`, `test/stop-movement.test.js`, `test/formats/csv-gnarly.test.js`, `test/drivers/mysql.test.js`, `test/drivers/mssql.test.js`, `test/drivers/query-columns.test.js`, `test/builtins/email.test.js` (loads the package root, which needs `@xeplr/db`: a peer dependency, installed for development) | Postgres at `localhost:5435` (`PG_PASSWORD`, default `postgres`; database `xeplr_actions_test`): `test/drivers/postgres.test.js`, `test/builtins/db-push.test.js`, `test/builtins/file-upload.test.js` (also honours `PG_HOST`/`PG_PORT`/`PG_USER`), `test/uploader/upload.test.js`; plus `@xeplr/db` for `test/uploader/meta-store-knex.test.js` |
-| `test/list-columns-length.test.js` (`XEPLR_TEST_PG_URL`, `MYSQL_TEST_URL`, `MSSQL_TEST_URL`; each skipped when unset), `test/drivers/duckdb.test.js`, `test/drivers/duckdb-values.test.js`, `test/duckdb-index-guard.test.js`, `test/staged-load.test.js` (needs `@duckdb/node-api`) | MySQL `localhost:3306` (`MYSQL_HOST/PORT/USER/PASSWORD`): `test/drivers/mysql-integration.test.js` |
-| | SQL Server `localhost:1433` (`MSSQL_HOST/PORT/USER/PASSWORD`): `test/drivers/mssql-integration.test.js` |
-| | Postgres + MySQL + SQL Server (`PG_*`, `MYSQL_*`, `MSSQL_*`): `test/builtins/db-replication.test.js` |
+**Databases come from the environment, never from code** (`test/helpers/databases.js`):
+
+| database | settings | default port |
+|---|---|---|
+| Postgres | `PG_HOST` `PG_PORT` `PG_USER` `PG_PASSWORD` | 5432 |
+| MySQL | `MYSQL_HOST` `MYSQL_PORT` `MYSQL_USER` `MYSQL_PASSWORD` | 3306 |
+| SQL Server | `MSSQL_HOST` `MSSQL_PORT` `MSSQL_USER` `MSSQL_PASSWORD` | 1433 |
+
+- **No `*_HOST`:** that database's tests are **skipped**, and each says which settings run it.
+- **`*_HOST` set:** they run, and a login the database refuses **fails** them. A configured run never passes by not connecting.
+- **One file at a time** (`--test-concurrency=1`): the database suites share the `xeplr_actions_test` database and race to create it when run side by side.
+- **Why:** these files used to carry a fixed host, port and password each (Postgres on `:5435`). On any other machine they all failed, so the pre-commit gate and CI ran only `test/*.test.js` and never this package's sub-folders. That is how `data-operation` shipped returning no rows (fixed in 1.4.2).
 
-`test/db-move.live.js` runs against a developer's own `.env` path and is not a portable test. CI (`.github/workflows/ci.yml`) skips tests when there is no `test` script.
+Other tests read their own settings: `test/list-columns-length.test.js` (`XEPLR_TEST_PG_URL`, `MYSQL_TEST_URL`, `MSSQL_TEST_URL`), `test/readonly-connections.test.js` (`PGHOST` …), and `test/dates-across-zones.test.js` skips a database it cannot reach. `test/db-move.live.js` runs against a developer's own `.env` path and is not part of `npm test`.
 
 ## License
 

package/lib/builtins/email/download-attachments.js

@@ -13,11 +13,12 @@
 
 var emailDrivers = require('../../drivers/email');
 var emailConfig = require('../../drivers/email/config');
+var fileNames = require('../../fileNames');
 
 module.exports = {
   name: 'email-download-attachments',
   description: 'Save a message\'s attachments to disk, optionally filtered by extension or ' +
-               'filename substring. Returns { count, saved[], path, skipped }.',
+               'filename substring, named as you say. Returns { count, saved[], path, skipped, existing[] }.',
   requires: [],
 
   // Which mailbox first — it is the only answer that changes what the rest of
@@ -39,7 +40,7 @@ module.exports = {
       description: 'Only attachments with this extension, e.g. "pdf" or ".pdf".' },
     { name: 'filenameContains', type: 'string', order: 7, group: 'Filters',
       description: 'Only attachments whose filename contains this substring.' }
-  ],
+  ].concat(fileNames.nameInputs(8, '[original], [name], [ext], [n] (1, 2, … per attachment), [id] (the message)')),
 
   execute: async function(ctx) {
     var input = ctx.input || {};

package/lib/builtins/email/download-email.js

@@ -11,6 +11,7 @@
 
 var emailDrivers = require('../../drivers/email');
 var emailConfig = require('../../drivers/email/config');
+var fileNames = require('../../fileNames');
 
 module.exports = {
   name: 'email-download-email',
@@ -32,7 +33,7 @@ module.exports = {
       description: 'Folder the message is currently in — where its id is valid.' },
     { name: 'outDir',     type: 'string', order: 5,
       description: 'Directory to write into. Defaults to XEPLR_ACTIONS_TMP_DIR.' }
-  ],
+  ].concat(fileNames.nameInputs(6, '[subject], [id] (the message), [ext] (eml)')),
 
   execute: async function(ctx) {
     var input = ctx.input || {};

package/lib/builtins/export/table.js

@@ -22,6 +22,7 @@ var path = require('path');
 var readline = require('readline');
 var writers = require('../../formats/writers');
 var { checkFormatRequires } = require('../../formats');
+var fileNames = require('../../fileNames');
 
 function tmpDir() {
   var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
@@ -35,10 +36,28 @@ function fileNameFor(title, extension) {
   return base + '.' + extension;
 }
 
-async function* rowsFrom(input) {
-  if (Array.isArray(input.rows)) { for (var i = 0; i < input.rows.length; i++) yield input.rows[i]; return; }
+/**
+ * A ROW AS THE WRITERS TAKE IT: { values: [...] }. A plain record — what a
+ * fetch or the data step gives, { ref: 'A1', amount: 500 } — is laid out by
+ * the columns' `key` (or header), so a workflow can hand its rows straight
+ * over instead of reshaping them first.
+ */
+function asRow(row, columns) {
+  if (row && Array.isArray(row.values)) return row;
+  var r = row || {};
+  return { values: columns.map(function(c) { var k = c.key || c.header; return r[k] === undefined ? null : r[k]; }) };
+}
+
+async function* rowsFrom(input, columns) {
+  if (Array.isArray(input.rows)) { for (var i = 0; i < input.rows.length; i++) yield asRow(input.rows[i], columns); return; }
   var lines = readline.createInterface({ input: fs.createReadStream(input.rowsFile), crlfDelay: Infinity });
-  for await (var line of lines) if (line.trim()) yield JSON.parse(line);
+  for await (var line of lines) if (line.trim()) yield asRow(JSON.parse(line), columns);
+}
+
+/** Columns for plain records when none are given: every key of the first one, as it is. */
+function columnsOf(rows) {
+  var first = (rows || []).find(function(r) { return r && typeof r === 'object' && !Array.isArray(r.values); });
+  return first ? Object.keys(first).map(function(k) { return { header: k, key: k }; }) : [];
 }
 
 module.exports = {
@@ -50,22 +69,29 @@ module.exports = {
   inputSchema: [
     { name: 'format', type: 'string', required: true, order: 1, enum: writers.SUPPORTED,
       description: 'csv, xlsx or pdf.' },
-    { name: 'document', type: 'object', required: true, order: 2,
-      description: '{ title?, subtitle?, footer?, columns: [{ header, kind?: number|date|text, numFmt?, align?, width? }] }. ' +
-                   'numFmt is an Excel number format ("#,##0.00", "0.0%", "mmm yyyy").' },
+    { name: 'document', type: 'object', order: 2,
+      description: '{ title?, subtitle?, footer?, columns: [{ header, key?, kind?: number|date|text, numFmt?, align?, width? }] }. ' +
+                   'numFmt is an Excel number format ("#,##0.00", "0.0%", "mmm yyyy"). key: which field of a plain record ' +
+                   'goes in the column (default: the header). No columns with plain records: every field of the first row.' },
     { name: 'rows', type: 'array', order: 3,
-      description: 'Rows: { values: [], display?: [], kind?: detail|subtotal|total }. Or give rowsFile.' },
+      description: 'Plain records, as a fetch or the data step gives them ({ ref, amount }), or { values: [], display?: [], ' +
+                   'kind?: detail|subtotal|total }. Or give rowsFile.' },
     { name: 'rowsFile', type: 'string', order: 4,
       description: 'An NDJSON file with one row per line, instead of rows.' },
     { name: 'outputPath', type: 'string', order: 5,
-      description: 'Where to write. Default: a new file in XEPLR_ACTIONS_TMP_DIR named after the title.' },
+      description: 'Where to write, e.g. /data/recon/Recon-{trigger.window.from|date:YYYY-MM}.xlsx. ' +
+                   'Default: a new file in XEPLR_ACTIONS_TMP_DIR named after the title.' },
+    { name: 'ifExists', type: 'string', order: 7, default: 'fail', options: fileNames.IF_EXISTS,
+      description: 'When outputPath is already there. fail: the step fails and nothing is written. skip: left alone ' +
+                   '(skipped: true). overwrite: replaced. addSuffix: "name (2).xlsx".' },
     { name: 'maxRows', type: 'number', order: 6,
       description: 'PDF only: rows to draw before stopping with a note (default 5,000).' }
   ],
   outputSchema: [
     { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
     { name: 'contentType', type: 'string' }, { name: 'bytes', type: 'number' },
-    { name: 'rows', type: 'number' }, { name: 'truncated', type: 'boolean' }
+    { name: 'rows', type: 'number' }, { name: 'truncated', type: 'boolean' },
+    { name: 'skipped', type: 'boolean' }
   ],
 
   execute: async function(ctx) {
@@ -74,6 +100,7 @@ module.exports = {
     var writer = writers.getWriter(format);
     checkFormatRequires('export-table', format, writer);
     var doc = Object.assign({}, input.document || {});
+    if ((!Array.isArray(doc.columns) || !doc.columns.length) && Array.isArray(input.rows)) doc.columns = columnsOf(input.rows);
     if (!Array.isArray(doc.columns) || !doc.columns.length) {
       var bad = new Error('document.columns must list at least one column');
       bad.status = 400;
@@ -89,10 +116,22 @@ module.exports = {
     var info = writers.INFO[format];
     var fileName = fileNameFor(doc.title, info.extension);
     var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(tmpDir(), 'export-')), fileName);
+    if (input.outputPath) {
+      // The same rule as every action that saves a file (lib/fileNames.js):
+      // a name already taken is never silently replaced.
+      var dir = path.dirname(filePath);
+      fs.mkdirSync(dir, { recursive: true });
+      var place = fileNames.plan(dir, [path.basename(filePath)], input.ifExists)[0];
+      if (!place.write) {
+        return { filePath: place.path, fileName: place.name, contentType: info.contentType,
+          bytes: fs.statSync(place.path).size, rows: 0, truncated: false, skipped: true };
+      }
+      filePath = place.path;
+    }
     var open = writer.open(filePath, doc);
     var signal = ctx.signal;
     try {
-      for await (var row of rowsFrom(input)) {
+      for await (var row of rowsFrom(input, doc.columns)) {
         if (signal && signal.aborted) throw new Error('Stopped by request');
         var more = await open.writeRow(row);
         // Excel's own limit: the rest are only counted. A PDF keeps counting
@@ -106,7 +145,8 @@ module.exports = {
         contentType: info.contentType,
         bytes: fs.statSync(filePath).size,
         rows: done.rows,
-        truncated: done.truncated
+        truncated: done.truncated,
+        skipped: false
       };
     } catch (err) {
       try { fs.rmSync(filePath, { force: true }); } catch (e) { /* nothing to clean */ }

package/lib/drivers/email/files.js

@@ -12,6 +12,7 @@ var path   = require('path');
 var fs     = require('fs');
 var fsp    = require('fs/promises');
 var os     = require('os');
+var fileNames = require('../../fileNames');
 
 // Short random prefix. Attachment names collide constantly in mail —
 // "invoice.pdf" from fifty senders — and a download that silently overwrites
@@ -65,7 +66,74 @@ function emlFilename(subject, uid) {
   return shortId() + '_' + base + '.eml';
 }
 
+/**
+ * Where each attachment goes. Named (input.fileName): every name decided
+ * before any file is written (fileNames.plan, with ifExists). Unnamed: a
+ * random prefix, as always — attachment names collide.
+ * @returns [{ name, path, write }] in the order of `attachments`
+ */
+function attachmentPlaces(dir, attachments, uid, input) {
+  if (!input.fileName) {
+    return attachments.map(function(a) {
+      var n = shortId() + '_' + sanitizeFilename(a.filename);
+      return { name: n, path: path.join(dir, n), write: true };
+    });
+  }
+  return fileNames.plan(dir, attachments.map(function(a, i) {
+    var p = fileNames.partsOf(a.filename);
+    return fileNames.nameFrom(input.fileName, { original: p.original, name: p.name, ext: p.ext, n: i + 1, id: uid });
+  }), input.ifExists);
+}
+
+/** Where a whole message's .eml goes: named by input.fileName, else the subject. */
+function emlPlace(dir, subject, uid, input) {
+  if (!input.fileName) {
+    var n = emlFilename(subject, uid);
+    return { name: n, path: path.join(dir, n), write: true };
+  }
+  var named = fileNames.nameFrom(input.fileName, { subject: fileNames.safeName(subject) || 'message', id: uid, ext: 'eml' });
+  return fileNames.plan(dir, [named], input.ifExists)[0];
+}
+
+/**
+ * Save a parsed message's attachments that pass the filters, named as asked.
+ * @returns { count, saved[], existing[], path, skipped }
+ *   saved[] entries are { filename, path, size, contentType } — nodemailer's
+ *   attachment shape, so email-send can forward them as they are.
+ */
+function saveAttachments(dir, all, uid, input) {
+  var wanted = all.filter(function(a) { return attachmentMatches(a.filename, input.extension, input.filenameContains); });
+  var places = attachmentPlaces(dir, wanted, uid, input);
+  var saved = [];
+  var existing = [];
+  wanted.forEach(function(a, i) {
+    var place = places[i];
+    if (!place.write) { existing.push({ filename: place.name, path: place.path }); return; }
+    fs.writeFileSync(place.path, a.content);
+    saved.push({
+      filename: input.fileName ? place.name : (a.filename || place.name),
+      path: place.path,
+      size: a.size || (a.content && a.content.length) || null,
+      contentType: a.contentType || null
+    });
+  });
+  return {
+    count: saved.length,
+    saved: saved,
+    // Already there and left alone (ifExists: skip), so the next step can
+    // tell "nothing new" from "nothing attached".
+    existing: existing,
+    path: saved.length ? saved[0].path : null,
+    // Reported rather than silent: "0 attachments" and "6 attachments, none
+    // matched your filter" are different problems with the same count.
+    skipped: all.length - wanted.length
+  };
+}
+
 module.exports = {
+  saveAttachments: saveAttachments,
+  attachmentPlaces: attachmentPlaces,
+  emlPlace: emlPlace,
   shortId: shortId,
   sanitizeFilename: sanitizeFilename,
   resolveOutDir: resolveOutDir,

package/lib/drivers/email/imap.js

@@ -317,12 +317,17 @@ async function downloadEmail(connection, input) {
       subject = (meta && meta.envelope && meta.envelope.subject) || null;
     } catch (_) { /* filename falls back to the uid — never fatal */ }
 
-    var dl = await client.download(uid, undefined, { uid: true });
-
     var dir = await files.resolveOutDir(input.outDir);
-    var filename = files.emlFilename(subject, uid);
-    var filepath = files.path.join(dir, filename);
+    // Decided before the download: a name already taken under `fail` costs
+    // nothing, and under `skip` nothing is fetched at all.
+    var where = files.emlPlace(dir, subject, uid, input);
+    if (!where.write) {
+      return { count: 0, saved: [], path: null, existing: [{ filename: where.name, path: where.path }], subject: subject, messageId: uid };
+    }
+    var filename = where.name;
+    var filepath = where.path;
 
+    var dl = await client.download(uid, undefined, { uid: true });
     await pipeline(dl.content, files.fs.createWriteStream(filepath));
 
     var size = files.fs.statSync(filepath).size;
@@ -332,6 +337,7 @@ async function downloadEmail(connection, input) {
       // `path` / `saved[]` identically whichever produced the file.
       saved: [{ filename: filename, path: filepath, size: size, contentType: 'message/rfc822' }],
       path: filepath,
+      existing: [],
       subject: subject,
       messageId: uid
     };
@@ -353,35 +359,11 @@ async function downloadAttachments(connection, input) {
   return withMailbox('email-download-attachments', connection, input.folder || 'INBOX', async function(client) {
     var dl = await client.download(uid, undefined, { uid: true });
     var parsed = await simpleParser(dl.content);
-    var all = parsed.attachments || [];
 
     var dir = await files.resolveOutDir(input.outDir);
-    var saved = [];
-    var skipped = 0;
-
-    for (var i = 0; i < all.length; i++) {
-      var a = all[i];
-      if (!files.attachmentMatches(a.filename, input.extension, input.filenameContains)) { skipped++; continue; }
-      var filename = files.shortId() + '_' + files.sanitizeFilename(a.filename);
-      var filepath = files.path.join(dir, filename);
-      files.fs.writeFileSync(filepath, a.content);
-      saved.push({
-        filename: a.filename || filename,
-        path: filepath,
-        size: a.size || (a.content && a.content.length) || null,
-        contentType: a.contentType || null
-      });
-    }
-
-    return {
-      count: saved.length,
-      saved: saved,
-      path: saved.length ? saved[0].path : null,
-      // Reported rather than silent: "0 attachments" and "6 attachments, none
-      // matched your filter" are different problems with the same count.
-      skipped: skipped,
-      messageId: uid
-    };
+    var out = files.saveAttachments(dir, parsed.attachments || [], uid, input);
+    out.messageId = uid;
+    return out;
   });
 }
 

package/lib/fileNames.js

@@ -0,0 +1,136 @@
+// WHAT A SAVED FILE IS CALLED, AND WHAT HAPPENS WHEN ONE IS ALREADY THERE.
+//
+// One rule for every action that writes a file, so a workflow can say
+// "Bank-2026-09.csv" instead of getting "3f9a1c02e4_statement.csv".
+//
+// A name is a template with two kinds of placeholder:
+//   {…}  from the WORKFLOW, filled in by the engine before the step runs:
+//        Bank-{trigger.window.from|date:YYYY-MM}
+//   […]  from the FILE ITSELF, filled in here: [original] [name] [ext] [n]
+//        and whatever the action adds (an email's [subject], [id]).
+// Square brackets because the engine fills every {…} first, and would blank
+// a file's own placeholders before the action ever saw them.
+//
+// ifExists, when the name is already taken:
+//   fail       (default) the step fails, naming the file: nothing is written,
+//              so a second run for the same period is caught, not repeated
+//   skip       nothing is written for it, and it is listed in `existing`, so
+//              the next step can branch on "already downloaded"
+//   overwrite  replaced
+//   addSuffix  "Bank-2026-09 (2).csv"
+// Decided for the whole step before anything is written, so `fail` never
+// leaves half a batch behind.
+
+var fs = require('fs');
+var path = require('path');
+
+var IF_EXISTS = ['fail', 'skip', 'overwrite', 'addSuffix'];
+
+function nameError(message, code) {
+  var err = new Error(message);
+  err.code = code || 'FILE_NAME_INVALID';
+  err.status = 400;
+  return err;
+}
+
+/**
+ * A name that is safe to join to a directory: no separators, no characters
+ * a filesystem refuses, not "." or "..". Spaces are kept — "Bank Sep 2026.csv"
+ * is a name a person wants.
+ */
+function safeName(name) {
+  var out = String(name == null ? '' : name)
+    .replace(/[\/\\:*?"<>|\u0000-\u001f]+/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 200);
+  if (!out || /^\.+$/.test(out)) return '';
+  return out;
+}
+
+/** The parts of an original file name: [original], [name], [ext]. */
+function partsOf(original) {
+  var o = safeName(original) || 'file';
+  var dot = o.lastIndexOf('.');
+  var hasExt = dot > 0 && dot < o.length - 1;
+  return { original: o, name: hasExt ? o.slice(0, dot) : o, ext: hasExt ? o.slice(dot + 1) : '' };
+}
+
+/**
+ * The name from `template` and the file's own `tokens`. A placeholder the
+ * file does not have is refused, listing the ones it does — a typo must not
+ * quietly drop part of a name.
+ */
+function nameFrom(template, tokens) {
+  var unknown = [];
+  var out = String(template).replace(/\[([A-Za-z]+)\]/g, function(whole, key) {
+    if (!Object.prototype.hasOwnProperty.call(tokens, key)) { unknown.push(key); return whole; }
+    var v = tokens[key];
+    return v === null || v === undefined ? '' : String(v);
+  });
+  if (unknown.length) {
+    throw nameError('The file name "' + template + '" uses [' + unknown.join('], [') + '], which this file does not have. ' +
+      'It has: [' + Object.keys(tokens).join('], [') + '].');
+  }
+  var safe = safeName(out);
+  if (!safe) throw nameError('The file name "' + template + '" comes out empty. Check the values it is made from.');
+  return safe;
+}
+
+function withSuffix(name, k) {
+  var dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(0, dot) + ' (' + k + ')' + name.slice(dot) : name + ' (' + k + ')';
+}
+
+/**
+ * Where each file goes, decided for the whole step before anything is
+ * written. `names` in order; returns [{ name, path, write }] where `write`
+ * is false for one skipped. Throws FILE_EXISTS for `fail`.
+ */
+function plan(dir, names, ifExists) {
+  var mode = ifExists || 'fail';
+  if (IF_EXISTS.indexOf(mode) === -1) {
+    throw nameError('ifExists is one of ' + IF_EXISTS.join(', ') + ', not "' + mode + '".');
+  }
+  var taken = {};
+  var exists = function(n) { return taken[n] || fs.existsSync(path.join(dir, n)); };
+  return names.map(function(name) {
+    var out = name;
+    if (exists(out)) {
+      if (mode === 'fail') {
+        throw nameError('"' + out + '" is already in ' + dir + '. Nothing was saved. ' +
+          'Set ifExists to skip, overwrite or addSuffix to save anyway.', 'FILE_EXISTS');
+      }
+      if (mode === 'skip') return { name: out, path: path.join(dir, out), write: false };
+      if (mode === 'addSuffix') {
+        var k = 2;
+        while (exists(withSuffix(name, k))) k++;
+        out = withSuffix(name, k);
+      }
+      // overwrite: the same name, written again. Two files of THIS step with
+      // one name still get a suffix: overwriting its own first file would lose it.
+      if (mode === 'overwrite' && taken[out]) {
+        var j = 2;
+        while (taken[withSuffix(name, j)]) j++;
+        out = withSuffix(name, j);
+      }
+    }
+    taken[out] = true;
+    return { name: out, path: path.join(dir, out), write: true };
+  });
+}
+
+/** The inputs every file-writing action takes, to spread into its inputSchema. */
+function nameInputs(order, tokensHelp) {
+  return [
+    { name: 'fileName', type: 'string', order: order, group: 'Saving',
+      description: 'What to call the file. {…} comes from the workflow, e.g. Bank-{trigger.window.from|date:YYYY-MM}; ' +
+        '[…] from the file: ' + tokensHelp + '. Empty: a random prefix and the original name.' },
+    { name: 'ifExists', type: 'string', order: order + 1, group: 'Saving', default: 'fail',
+      options: IF_EXISTS,
+      description: 'When the name is taken. fail: the step fails and nothing is saved. skip: listed in `existing`, not saved. ' +
+        'overwrite: replaced. addSuffix: "name (2).ext". Only with a file name.' }
+  ];
+}
+
+module.exports = { safeName: safeName, partsOf: partsOf, nameFrom: nameFrom, plan: plan, nameInputs: nameInputs, IF_EXISTS: IF_EXISTS };

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
+  "scripts": {
+    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\""
+  },
   "files": [
     "index.js",
     "lib/"