@blockrun/franklin 3.28.1 → 3.28.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -56,6 +56,8 @@ Built by the [BlockRun](https://blockrun.ai) team. Apache-2.0. TypeScript. Ships
56
56
 
57
57
  ## Quick start
58
58
 
59
+ > **Requires Node.js 20.19+ (Node 22 LTS recommended).** Check with `node -v`. Older Node crashes at startup with `ERR_REQUIRE_ESM`.
60
+
59
61
  ```bash
60
62
  # 1. Install
61
63
  npm install -g @blockrun/franklin
@@ -70,6 +72,32 @@ franklin balance # show address + USDC balance
70
72
 
71
73
  That's it. Zero signup, zero credit card, zero phone verification. Send **$5 of USDC** to the wallet and you've unlocked every frontier model and every paid tool in the BlockRun gateway.
72
74
 
75
+ **No global install? Just run it directly** — no permissions, no `-g`:
76
+
77
+ ```bash
78
+ npx @blockrun/franklin
79
+ ```
80
+
81
+ ### Install troubleshooting
82
+
83
+ | Symptom | Cause | Fix |
84
+ | ------- | ----- | --- |
85
+ | `npm error EACCES … mkdir '/usr/local/lib/node_modules'` | Your global npm folder is owned by root (common when Node was installed from the macOS `.pkg`). | Don't use `sudo`. Either run `npx @blockrun/franklin` (no global install needed), or switch to a user-owned Node via a version manager — see below. |
86
+ | `Error [ERR_REQUIRE_ESM] … rpc-websockets … require() of ES Module … uuid` | Node is older than 20.19. Franklin's Solana deps need the `require(esm)` support added in Node 20.19.0. | Upgrade to Node 20.19+ or 22 LTS (see below). This is the #1 cause of a crash on first run. |
87
+ | `npm warn EBADENGINE … required: { node: '>=20.x' }` | Node is older than 20.19. | Upgrade to Node 20.19+ or 22 LTS. The warning alone is harmless, but on old Node the run will also crash — upgrade. |
88
+
89
+ The clean, permanent fix for both is a **user-owned Node** so global installs never touch root-owned system folders:
90
+
91
+ ```bash
92
+ # nvm (https://github.com/nvm-sh/nvm)
93
+ nvm install 22 && nvm use 22
94
+ npm install -g @blockrun/franklin
95
+
96
+ # or fnm (https://github.com/Schniz/fnm)
97
+ fnm install 22 && fnm use 22
98
+ npm install -g @blockrun/franklin
99
+ ```
100
+
73
101
  ### Prefer a GUI? Try Franklin for VS Code
74
102
 
75
103
  [![Franklin for VS Code — Beta is here](assets/franklin-vscode-banner.png)](https://marketplace.visualstudio.com/items?itemName=blockrun.franklin-vscode)
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  #!/usr/bin/env node
2
- export {};
2
+ import './preflight.js';
package/dist/index.js CHANGED
@@ -1,4 +1,6 @@
1
1
  #!/usr/bin/env node
2
+ // Node version guard — MUST be first so it runs before the Solana stack loads on old Node.
3
+ import './preflight.js';
2
4
  // Global error handlers — catch unhandled rejections/exceptions before they crash silently
3
5
  process.on('unhandledRejection', (reason) => {
4
6
  console.error(`\x1b[31mUnhandled error: ${reason instanceof Error ? reason.message : String(reason)}\x1b[0m`);
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,27 @@
1
+ // Preflight: verify the Node.js runtime BEFORE any heavy dependency loads.
2
+ //
3
+ // Must be the very first import in index.ts and must stay dependency-free.
4
+ // ESM evaluates imported modules depth-first in source order, so importing this
5
+ // first lets it exit cleanly before the Solana stack is evaluated. Several
6
+ // transitive deps (rpc-websockets require()-ing ESM-only uuid, @noble/*) need
7
+ // the require(esm) capability that only exists on Node >= 20.19.0; on older Node
8
+ // they throw ERR_REQUIRE_ESM at load time, which would otherwise surface as an
9
+ // opaque stack trace pointing at node_modules instead of a clear instruction.
10
+ const MIN = [20, 19, 0];
11
+ const current = process.versions.node.split('.').map((part) => parseInt(part, 10));
12
+ const [curMajor = 0, curMinor = 0, curPatch = 0] = current;
13
+ const [minMajor, minMinor, minPatch] = MIN;
14
+ const tooOld = curMajor < minMajor ||
15
+ (curMajor === minMajor &&
16
+ (curMinor < minMinor || (curMinor === minMinor && curPatch < minPatch)));
17
+ if (tooOld) {
18
+ const red = (s) => `\x1b[31m${s}\x1b[0m`;
19
+ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
20
+ console.error(red(`\nFranklin requires Node.js ${MIN.join('.')} or newer — you have ${process.versions.node}.`));
21
+ console.error('\nUpgrade Node, then re-run franklin:');
22
+ console.error(dim(' nvm install 22 && nvm use 22 # https://github.com/nvm-sh/nvm'));
23
+ console.error(dim(' # or: fnm install 22 && fnm use 22 # https://github.com/Schniz/fnm'));
24
+ console.error('');
25
+ process.exit(1);
26
+ }
27
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blockrun/franklin",
3
- "version": "3.28.1",
3
+ "version": "3.28.3",
4
4
  "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -63,7 +63,7 @@
63
63
  },
64
64
  "homepage": "https://Franklin.run",
65
65
  "engines": {
66
- "node": ">=20"
66
+ "node": ">=20.19.0"
67
67
  },
68
68
  "dependencies": {
69
69
  "@blockrun/llm": "^2.0.0",