@blucca/n8n-check 0.0.0-stage → 0.1.6

package/examples/agregado-enrichment/prepare.mjs

@@ -0,0 +1,39 @@
+import {mkdir, writeFile} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+// Download immutable Agregado exports; generate synthetic contracts beside them.
+// Source: ffrt-labs/agregado (README declares MIT). See README for attribution.
+const root=resolve(process.argv[2] ?? 'temp/agregado-enrichment');
+await mkdir(root,{recursive:true});
+const sources={
+ original:{repo:'ffrt-labs/agregado',commit:'0cbbac9c7c6e19f2b9f82bab57cf75a171279eac',sha256:'49c2fce7e72ed0b773f9236a9ca29d3146714bd46a001cb0f3ddc7ece1acff1d'},
+ fixed:{repo:'blucca/agregado',commit:'b4e4332b57341f1afdb7a3be7a9069540b8a15f4',sha256:'e0104cd7c58bfeb7c5a4e77ce3bc01832bd209ca8aa824ae77ce804781ea18c0'},
+};
+for(const [name,source] of Object.entries(sources)){
+ const url=`https://raw.githubusercontent.com/${source.repo}/${source.commit}/n8n/workflows/article-enrichment.json`;
+ const bytes=execFileSync('curl',['--fail','--silent','--show-error','--location','--max-time','60',url],{maxBuffer:2*1024*1024});
+ const hash=createHash('sha256').update(bytes).digest('hex');
+ if(hash!==source.sha256)throw new Error(`${name}: source SHA256 mismatch`);
+ JSON.parse(bytes.toString('utf8'));
+ await writeFile(`${root}/${name}.json`,bytes);
+}
+
+const ordinary=id=>({entry:{id,url:`https://example.test/article-${id}`,title:`Article ${id}`}});
+const bridge=id=>({entry:{id,url:`https://bridge.example.test/p/00000000-0000-4000-8000-${String(id).padStart(12,'0')}`,title:`Article ${id}`}});
+const body=item=>({entry_id:item.entry.id,canonical_url:item.entry.url,title:item.entry.title,...(item.entry.url.includes('/p/')?{bridge_content:`<p>Content for ${item.entry.id}</p>`}:{})});
+const groups={ordinary:[ordinary(101),ordinary(102)],mixed:[ordinary(101),bridge(102),ordinary(103),bridge(104)],retry:[ordinary(101),ordinary(102)]};
+for(const [name,items] of Object.entries(groups)){
+ const bridged=items.filter(i=>i.entry.url.includes('/p/'));
+ const expected=items.map(body);
+ if(name==='retry')expected.push(body(items.at(-1)));
+ const spec={version:1,name:`Agregado ${name}: preserve every Article`,input:{node:'Parse entries',items},timeoutMs:90000,mocks:[
+  {node:'Call enrich API',url:'/api/private/articles/enrich',routes:[{method:'POST',path:'/api/private/articles/enrich',responses:name==='retry'?[{status:200,json:{ok:true}},{status:503,json:{message:'temporary unavailable'}},{status:200,json:{ok:true}}]:[{status:200,json:{ok:true}}],expect:{count:expected.length,bodies:expected}}]},
+  {node:'Lookup bridge content',url:'/d1/content',routes:[{method:'POST',path:'/d1/content',responses:bridged.length?bridged.map(i=>({status:200,json:{result:[{results:[{readable_content:`<p>Content for ${i.entry.id}</p>`}]}]}})):[{status:200,json:{result:[{results:[]}]}}],expect:{count:bridged.length}}]},
+  {node:'Claim alert',url:'/d1/claim',routes:[{method:'POST',path:'/d1/claim',responses:[{status:200,json:{result:[{meta:{changes:1}}]}}],expect:{count:0}}]},
+  {node:'Notify',url:'/alert',routes:[{method:'POST',path:'/alert',responses:[{status:200,json:{ok:true}}],expect:{count:0}}]},
+ ],assertions:[{node:'Build enrich request',equals:items.map(i=>({entry:i.entry,body:body(i)}))}]};
+ await writeFile(`${root}/${name}.case.json`,JSON.stringify(spec,null,2)+'\n');
+}
+await writeFile(`${root}/sources.json`,JSON.stringify(sources,null,2)+'\n');
+console.log(`Prepared two pinned workflows and three synthetic cases in ${root}`);

package/examples/identity-projection/README.md

@@ -0,0 +1,39 @@
+# Keep row identities stable as metadata changes
+
+A three-row fixture contains two eligible records and one distractor. The Code node filters by score and adds a fresh `processedAt` timestamp. The contract checks two ordered IDs; timestamps can change between runs.
+
+```json
+{ "node": "Select rows", "count": 2, "pluck": "json.id", "equals": ["row-A", "row-B"] }
+```
+
+**Available in v0.1.6+.** The [local case builder](https://blucca.github.io/n8n-check/) offers **Selected field + item count**: choose `json.id`, review the expected IDs, and download the case and CI file.
+
+## Run
+
+From a current source checkout, build the isolated runtime:
+
+```sh
+docker build -t n8n-check .
+docker run --rm --network none -v "$PWD:/work" n8n-check \
+  examples/identity-projection/workflow.json examples/identity-projection/case.json \
+  --out /work/results/identity-fixed
+# Exit 0: two items, both expected IDs.
+
+docker run --rm --network none -v "$PWD:/work" n8n-check \
+  examples/identity-projection/wrong-id.json examples/identity-projection/case.json \
+  --out /work/results/identity-wrong
+# Exit 1: two items, wrong IDs; the n8n execution still succeeds.
+```
+
+## Recorded comparison
+
+Real n8n 2.41.7, loopback-only network, synthetic data:
+
+| Workflow | Engine | Count | Ordered identities | Contract |
+|---|---|---|---|---|
+| `workflow.json` | Success | 2: pass | row-A, row-B: pass | 5/5, exit 0 |
+| `wrong-id.json` | Success | 2: pass | wrong-row, wrong-row: fail | 4/5, exit 1 |
+
+[Observed checks and source hashes](observed-results.json) record the comparison. The negative control preserves the item count and changes both IDs. This catches a same-size replacement while allowing timestamp metadata to vary.
+
+Projection uses an own-property dotted path from each n8n item. Missing fields produce failure diagnostics. Order and duplicates remain significant. Select full-object `equals` when every output field belongs in the acceptance contract.

package/examples/identity-projection/case.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "name": "Preserve row identities while metadata changes",
+  "input": {
+    "node": "Rows",
+    "items": [
+      {
+        "id": "row-A",
+        "score": 0.9
+      },
+      {
+        "id": "row-B",
+        "score": 0.8
+      },
+      {
+        "id": "distractor",
+        "score": 0.2
+      }
+    ]
+  },
+  "mocks": [],
+  "assertions": [
+    {
+      "node": "Select rows",
+      "count": 2,
+      "pluck": "json.id",
+      "equals": [
+        "row-A",
+        "row-B"
+      ]
+    }
+  ]
+}

package/examples/identity-projection/observed-results.json

@@ -0,0 +1,117 @@
+{
+  "scope": "Synthetic identity projection comparison; main source with count/pluck, following v0.1.5",
+  "featureCommit": "1c58962",
+  "files": {
+    "workflow.json": "52268bee2c061ddfde870b8775dc8f0da0f08745286962eaff5f1736cf8ece31",
+    "wrong-id.json": "cf05d59ee7ca254481ecf5db43b006da79379528c2c80d704baa78a817e5d0bf",
+    "case.json": "a6237f7bae2fb8713cd4dd2265a195d5185302709a8eab2707d467c30a498429"
+  },
+  "runs": {
+    "fixed": {
+      "startedAt": "2026-10-06T22:55:14.503Z",
+      "n8nVersion": "2.41.7",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "passed",
+      "exitCode": 0,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "Select rows",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "Select rows: output 0 count",
+          "passed": true,
+          "expected": 2,
+          "actual": 2
+        },
+        {
+          "name": "Select rows: output 0 pluck json.id",
+          "passed": true,
+          "expected": [
+            "row-A",
+            "row-B"
+          ],
+          "actual": [
+            "row-A",
+            "row-B"
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        }
+      ],
+      "requests": []
+    },
+    "wrong-id": {
+      "startedAt": "2026-10-06T22:55:57.808Z",
+      "n8nVersion": "2.41.7",
+      "network": {
+        "mode": "loopback-only",
+        "enforced": true,
+        "interfaces": [
+          "lo"
+        ]
+      },
+      "status": "failed",
+      "exitCode": 1,
+      "checks": [
+        {
+          "name": "n8n execution succeeds",
+          "passed": true,
+          "actual": {
+            "cliExitCode": 0,
+            "lastNode": "Select rows",
+            "executionFound": true
+          }
+        },
+        {
+          "name": "Select rows: output 0 count",
+          "passed": true,
+          "expected": 2,
+          "actual": 2
+        },
+        {
+          "name": "Select rows: output 0 pluck json.id",
+          "passed": false,
+          "expected": [
+            "row-A",
+            "row-B"
+          ],
+          "actual": [
+            "wrong-row",
+            "wrong-row"
+          ]
+        },
+        {
+          "name": "mock: all requests match routes",
+          "passed": true,
+          "actual": []
+        },
+        {
+          "name": "mock: request limits and server",
+          "passed": true,
+          "actual": []
+        }
+      ],
+      "requests": []
+    }
+  }
+}

package/examples/identity-projection/workflow.json

@@ -0,0 +1,71 @@
+{
+  "name": "Stable row identities",
+  "nodes": [
+    {
+      "id": "start",
+      "name": "Start",
+      "type": "n8n-nodes-base.manualTrigger",
+      "typeVersion": 1,
+      "position": [
+        -400,
+        0
+      ],
+      "parameters": {}
+    },
+    {
+      "id": "rows",
+      "name": "Rows",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        -200,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "return $input.all();"
+      }
+    },
+    {
+      "id": "select",
+      "name": "Select rows",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "return $input.all().filter(item => item.json.score >= 0.7).map(item => ({ json: { ...item.json, processedAt: new Date().toISOString() } }));"
+      }
+    }
+  ],
+  "connections": {
+    "Start": {
+      "main": [
+        [
+          {
+            "node": "Rows",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Rows": {
+      "main": [
+        [
+          {
+            "node": "Select rows",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  }
+}

package/examples/identity-projection/wrong-id.json

@@ -0,0 +1,71 @@
+{
+  "name": "Stable row identities",
+  "nodes": [
+    {
+      "id": "start",
+      "name": "Start",
+      "type": "n8n-nodes-base.manualTrigger",
+      "typeVersion": 1,
+      "position": [
+        -400,
+        0
+      ],
+      "parameters": {}
+    },
+    {
+      "id": "rows",
+      "name": "Rows",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        -200,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "return $input.all();"
+      }
+    },
+    {
+      "id": "select",
+      "name": "Select rows",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        0,
+        0
+      ],
+      "parameters": {
+        "mode": "runOnceForAllItems",
+        "jsCode": "return $input.all().filter(item => item.json.score >= 0.7).map(item => ({ json: { ...item.json, id: \"wrong-row\", processedAt: new Date().toISOString() } }));"
+      }
+    }
+  ],
+  "connections": {
+    "Start": {
+      "main": [
+        [
+          {
+            "node": "Rows",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Rows": {
+      "main": [
+        [
+          {
+            "node": "Select rows",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  }
+}

package/examples/morsof-invoice-history/README.md

@@ -0,0 +1,77 @@
+# Morsof invoice-history regression contract
+
+Executable coverage for the seven batch-history cases in [Morsof issue #7](https://github.com/Morsoflab/n8n-automation-templates/issues/7), using the workflow from [PR #8](https://github.com/Morsoflab/n8n-automation-templates/pull/8), real n8n Code/If/Data Table nodes, and isolated SQLite storage.
+
+## Source and results
+
+- Current workflow: `3d8c61ee5b0e37e7e0052f53e7839db011b9c0de`.
+- Historical first version: `adb2d3c3aa7534bcce53d955938e24c9f061b315`.
+- `prepare.mjs` downloads those exports and verifies their SHA-256 hashes.
+- Runtime: n8n **2.41.7**, n8n-check **0.1.3**, Node **26.10.0** in the recorded run; Linux loopback-only networking.
+
+| Case | Current result | Persisted history rows |
+|---|---|---:|
+| Two eligible invoices | 9/9 | 2 |
+| Eligible + paid | 9/9 | 1 |
+| Existing + new | 9/9 | 2 |
+| Duplicate input | 9/9; one stored ID shared by both outputs | 1 |
+| Reordered existing + new | 9/9 | 2 |
+| Empty history, three eligible | 9/9 | 3 |
+| Multiple existing rows | 9/9; newest matching row selected | 4 |
+| Unchanged second execution | 9/9; both already prepared; zero writes | 2 |
+
+The historical export fails with `Multiple matches` in **Check Reminder History**, produces zero writes, and exits 1 under the same two-invoice contract. Its first error occurs before the reported global-limit data-loss path. The current export passes all seven cases.
+
+For same-batch duplicates, **Ready for Review** physically emits both items: the first has `outputPath=ready_for_review`; the second has `outputPath=already_prepared` and `actionReason=duplicate_in_execution`. Both reference the one stored row. The separate **Already Prepared** node receives matches from history loaded before this execution. A downstream approval consumer can select `outputPath === "ready_for_review"` to process fresh drafts.
+
+The replay check executes the same imported workflow twice against the same isolated database. It checks the original stored IDs, complete unchanged database rows, and original preparation timestamps.
+
+## Run
+
+Requirements: Node 24+, the n8n 2.41.7 CLI on `PATH`, an n8n-check v0.1.3 checkout, Linux `unshare` and `ip`.
+
+```sh
+# Network access is used for the two pinned source downloads.
+node prepare.mjs
+
+# Supply the directory containing n8n-check's bin/ and src/.
+# Example: export PATH=/path/to/n8n-runtime/node_modules/.bin:$PATH
+unshare --user --map-root-user --net sh -c \
+  'ip link set lo up && ./run.sh /path/to/n8n-check ./results'
+```
+
+A single case:
+
+```sh
+unshare --user --map-root-user --net sh -c \
+  'ip link set lo up && node /path/to/n8n-check/bin/n8n-check.mjs \
+   fixed.workflow.json two-eligible.case.json \
+   --n8n "$PWD/n8n-datatable.cjs" --out results/two-eligible'
+```
+
+Each case writes JSON + JUnit and retains its actual execution output and isolated SQLite database. `run.sh` expects the historical regression to exit 1 and finishes with the persistent replay check.
+
+## Fixture adaptations
+
+The prepared exports preserve the upstream business-processing nodes, expressions, table schema, and connections. Four explicit fixture changes make the upstream manual test plan repeatable:
+
+1. Set the documented `EVALUATION_DATE` test override to `2030-06-20`.
+2. Replace **Load Fictional Invoice Samples** with the case's synthetic invoice array.
+3. Add a fixture-only seed branch between table creation and the original history load. This inserts requested history fixtures through the real Data Table node, including duplicate historical keys.
+4. Append read-only terminal projections that check invoice/customer/recipient identity, classification, stage, routing, draft linkage, stored row IDs, and writes. The full original outputs remain in `execution.json`.
+
+The adapters use fictional `.example` recipients. Every execution stays inactive and contains the upstream preparation workflow, its local fixtures, and its observation nodes.
+
+## Data Table CLI adapter
+
+n8n 2.41.7's server startup initializes the Data Table module. Its standalone `execute` command omits that initialization and reports `Attempted to use Data table node but the module is disabled` for this workflow.
+
+`n8n-datatable.cjs` is pinned to **2.41.7**. It runs the ordinary CLI with the upstream `DataTableModule.init()` and context registration added after `Execute.init()`. All Data Table node code, proxy validation, and database writes remain the upstream implementation. Its small internal initialization bridge should be reviewed when changing runtime versions. The source workflow and n8n-check runner files stay unchanged.
+
+`replay.mjs` uses n8n-check 0.1.3's execution helpers for the second invocation and Node's `node:sqlite` to compare actual rows. The seven ordinary cases use the published CLI case format directly.
+
+## Coverage boundary
+
+The contract covers batch correlation, existing-history matching, duplicate inputs, output linkage, and persistent replay. The upstream README's broader contact/date-validation matrix and insertion-failure simulation are separate cases. The historical `Multiple matches` failure and current batch success are the measured comparison.
+
+Upstream workflow source is MIT, attributed in `UPSTREAM-LICENSE`.

package/examples/morsof-invoice-history/UPSTREAM-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MORSOF
+
+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/examples/morsof-invoice-history/n8n-datatable.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+const path = require('node:path');
+const fs = require('node:fs');
+const cli = (process.env.PATH ?? '').split(path.delimiter).map(dir => path.join(dir, 'n8n')).find(file => fs.existsSync(file));
+if (!cli) throw new Error('Put the n8n 2.41.7 binary on PATH.');
+const root = path.dirname(path.dirname(fs.realpathSync(cli)));
+const {createRequire} = require('node:module');
+const req = createRequire(path.join(root,'package.json'));
+if (req('./package.json').version !== '2.41.7') throw new Error('This Data Table CLI adapter is pinned to n8n 2.41.7.');
+if (process.argv[2] === 'execute') {
+  process.env.NODE_CONFIG_DIR = path.join(root,'bin/config');
+  req('reflect-metadata');
+  req('./dist/config');
+  const {Execute} = req('./dist/commands/execute');
+  const {Container} = req('@n8n/di');
+  const {DataTableModule} = req('./dist/modules/data-table/data-table.module');
+  const originalInit = Execute.prototype.init;
+  // The server start command performs this module setup; the execute command omits it.
+  // Keep the real Data Table storage, proxies, validation, and node implementation.
+  Execute.prototype.init = async function() {
+    await originalInit.call(this);
+    const module = Container.get(DataTableModule);
+    await module.init();
+    this.moduleRegistry.context.set('data-table', await module.context());
+    this.moduleRegistry.activeModules.push('data-table');
+  };
+}
+req('./bin/n8n');

package/examples/morsof-invoice-history/observed-results.json

@@ -0,0 +1,113 @@
+{
+  "recordedAt": "2026-10-06T18:48:00Z",
+  "runtime": {
+    "n8n": "2.41.7",
+    "n8nCheck": "0.1.3",
+    "node": "26.10.0",
+    "network": "Linux loopback-only",
+    "dataTableAdapter": "Real upstream module initialized for CLI execute"
+  },
+  "sources": {
+    "fixed": [
+      "3d8c61ee5b0e37e7e0052f53e7839db011b9c0de",
+      "b29612d4206a557129f0f97b7ca6619419033bff7940bc2366370fd20838e180"
+    ],
+    "broken": [
+      "adb2d3c3aa7534bcce53d955938e24c9f061b315",
+      "43bb3d16f4e1bf10a01cbb75b257e7bdb8e536d2aaedb94f1d05464137dda23a"
+    ]
+  },
+  "cases": [
+    {
+      "name": "two-eligible",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 2
+    },
+    {
+      "name": "eligible-paid",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 1
+    },
+    {
+      "name": "existing-new",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 2
+    },
+    {
+      "name": "duplicate",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 1
+    },
+    {
+      "name": "reordered",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 2
+    },
+    {
+      "name": "empty-history",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 3
+    },
+    {
+      "name": "multiple-existing",
+      "status": "passed",
+      "checksPassed": 9,
+      "checksTotal": 9,
+      "exitCode": 0,
+      "persistedRowCount": 4
+    },
+    {
+      "name": "broken",
+      "status": "failed",
+      "checksPassed": 6,
+      "checksTotal": 9,
+      "exitCode": 1,
+      "persistedRowCount": 0
+    }
+  ],
+  "historicalFailure": {
+    "node": "Check Reminder History",
+    "message": "Multiple matches",
+    "writes": 0
+  },
+  "duplicateSemantics": {
+    "physicalNode": "Ready for Review",
+    "outputPaths": [
+      "ready_for_review",
+      "already_prepared"
+    ],
+    "secondReason": "duplicate_in_execution",
+    "sharedHistoryRecordId": 1
+  },
+  "persistentReplay": {
+    "checksPassed": 9,
+    "checksTotal": 9,
+    "status": "passed",
+    "persistedRowCount": 2,
+    "secondExecutionWrites": 0,
+    "originalRowIds": [
+      1,
+      2
+    ],
+    "completeRowsUnchanged": true,
+    "preparationTimestampsPreserved": true
+  }
+}