Repository navigation
Add the Edge CLI, on Node-safe extractions from the GUI - #6082
Draft
paullinator wants to merge 12 commits into
Draft
paullinator wants to merge 12 commits into
paullinator wants to merge 12 commits into
Conversation
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
All alerts resolved. Learn more about Socket for GitHub. This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored. |
paullinator
force-pushed
the
paul/cli
branch
11 times, most recently
from
August 8, 2026 07:06
67406a5 to
35eeb43
Compare
paullinator
force-pushed
the
paul/cli
branch
10 times, most recently
from
September 3, 2026 05:13
a8819b9 to
60adf1e
Compare
paullinator
force-pushed
the
paul/cli
branch
2 times, most recently
from
September 5, 2026 00:08
7d3a2ba to
c0c5f13
Compare
paullinator
force-pushed
the
paul/cli
branch
3 times, most recently
from
September 24, 2026 20:49
0574066 to
4bb295e
Compare
paullinator
force-pushed
the
paul/cli
branch
from
September 30, 2026 06:40
4bb295e to
70e9045
Compare
paullinator
changed the title
paullinator
force-pushed
the
paul/cli
branch
8 times, most recently
from
October 10, 2026 07:06
ef2f489 to
2324b31
Compare
`typechain` emits `export * as factories from './factories'`, and the React Native preset does not transform namespace re-exports. The plugin was declared but never enabled, so `TransactionListTop` failed to parse the moment `src/plugins/contracts` existed — which it does after any `npm install`, since `prepare` generates it. Metro needs that transform as much as jest does, so it belongs in the shared config.
src/util/hmacAuth.ts imports hashjs and src/util/utils.ts imports uuid, but both packages were only ever resolved transitively. Declare them so a clean install and the Node CLI bundle both get them.
paullinator
force-pushed
the
paul/cli
branch
7 times, most recently
from
October 10, 2026 17:16
f569518 to
ebea9ed
Compare
`network.ts`, `utils.ts` and the locale boot each pulled React Native in through their module load paths, so nothing outside the app could fetch from the info server, format an amount, or pick a language table. Fiat constants and helpers move to `fiatConstants.ts`, and `getOsVersion` to `rnUtils.ts` alongside the other React Native-only helpers, with `keysStore.ts` following it there. `getCurrencyCodeWithAccount` moves to `txDisplay/currencyCodes.ts`, which `utils.ts` can reach and `CurrencyInfoHelpers.ts` re-exports, so its fifty-odd call sites are untouched and there is still only one body deciding what an asset is called. `network.ts` takes its server lists and device fields through `configureNetwork` and `initInfoServer(params)` rather than reading `appConfig` and `react-native-device-info` at module scope. Reporting splits with them. These modules recovered from a failure by writing to `console`, which is a terminal in the app and, in a detached daemon, a file its own shutdown deletes. `reportWarning.ts` is one module-level sink they call instead: `console.warn` by default, so the GUI is unchanged, and redirected by whoever owns the process. It is a sink rather than an injected logger because these are free functions on both import graphs, and threading one through `getCurrencyCodeWithAccount` and its callers would put a logger in the signature of every display helper. Locale boot splits the same way: `bootLocale.ts` applies a language table and number format with no React Native imports, and `initLocale.ts` stays GUI-only, feeding it what `react-native-localize` reports. Capturing those device fields is separate from starting the poll: `configureInfoServer` records them synchronously, so `fetchPublicRollup` works for whoever calls it first, while `initInfoServer` owns the polling and the decision to skip the unsigned launch fetch. `fetchWaterfall` refuses an empty server list, because `asyncWaterfall([])` resolves `undefined` and every caller would then fail on `response.ok` with an error naming nothing. `asyncWaterfall` is event-driven: each server is running or settled, a failure hands over to the next at once, and the last failure is rethrown only when nothing is running and nothing is left to try. The array version tracked servers by position, so a primary that was slow and then failed took a still-running fallback's promise with it and threw while healthy servers were answering. Refreshing the info rollup or the coinrank list joins a fetch already in flight, so a flapping connection cannot start several and let whichever answers last decide. It adds `edge/no-module-scope-lstrings`, a lint rule that stops a module reading `lstrings` while it loads, following the binding however it was imported or aliased. Its rule tests run in a child Node process, because jest's transform does not load `.mjs`. It is not switched on here: `Extract Node-safe transaction tagging` adds the config block that enables it for the trees the CLI loads. Two helpers come with them. `errorMessage` renders whatever was thrown in one place, so these modules' reports need no engine import to get it. `withDeadline` is `raceTimeout` with a rejection instead of a sentinel, and both unref their pending timer, because a deadline should never be the reason a Node process stays alive.
Exchange rates could not be fetched outside the app: the module read its server list and its error reporter at load time, both of which come from React Native. The query logic now takes what it needs through `configureExchangeRates`, and `exchangeRatesGui` supplies the GUI's Airship reporter at app start. A Node caller supplies its own, so the same rate lookup answers the same way in both places. Two answers that were one. `0` means "the server could not price this date", which is a fact about the asset and is cached as one; a request that failed, a chain whose budget expired and a queue that was stopped learned nothing, and settling those at `0` as well made a wrong number indistinguishable from a real one. They settle at `RATE_UNAVAILABLE` instead — `NaN`, so a caller that does not check degrades to the old behaviour rather than to something plausible — and `isRateUnavailable` is the test. The one caller that must not write a wrong number is an accounting export. The budget is the caller's. `RATE_QUERY_TIMEOUT_MS` bounds one upstream request and the chain bounds the whole fill, and a fill is one pass per 99 keys — so the ceiling that matters belongs to whoever is waiting, and it is passed in rather than read from a module constant they cannot reach.
`initLocale` reaches for `react-native-localize`, so nothing outside the app could ask which locale to use. The decision itself is pure: read a tag from argv, config or the environment, normalize it, and pick a language table. `nodeLocale.ts` holds that decision with no React Native imports, and feeds the same `applyLocale` that the GUI's device lookup already calls, so the GUI and any Node caller resolve a locale the same way rather than approximately the same way. Precedence is explicit and tested: an explicit tag, then config, then `EDGE_CLI_LOCALE`, then `LC_ALL` / `LC_MESSAGES` / `LANG`, then `Intl`, then `en-US`. `es_MX.UTF-8@euro` and `C` both resolve, which is what the POSIX forms actually look like. `env` is typed as the variables it reads rather than `NodeJS.ProcessEnv`, which in this repo demands `NODE_ENV` and would make every caller invent one.
`CategoriesActions.ts` held five hundred lines deciding what a transaction should be called: the category, the payee, the direction, and the label for each action type. All of it is a pure function of the transaction, the wallet and the account, but it sat behind Redux imports, so nothing outside the app could ask the same question and get the same answer. `src/util/txDisplay/` holds that logic now — `displayInfo` for the derivation, `category` for the category strings, `txActionLabels` for the action names, and `currencyCodes` for the ticker lookups. The call sites move with the helpers: `CategoryModal`, `TransactionDetailsScene`, `TransactionListRow` and `TransactionsExportScene` import `splitCategory`, `joinCategory`, `getTxActionDisplayInfo` and `Category` from `util/txDisplay` instead of from `CategoriesActions`, and those moves are import paths only. `cleanFiatCurrencyCode` moves to `fiatCode.ts` for the same reason, and `memoUtils`' labels are read when they are shown rather than captured while the module loads. One behaviour does change, in `splitCategory`'s fallback for a category it does not recognise. It stripped `/^[^:]:/`, which removes only a one-character prefix — `X:Food` came back as `Food` — and returned the probe with its appended colon, so a bare `Shopping` became `Shopping:`. `TransactionDetailsScene` round-trips the pair, so opening and saving such a transaction wrote the change back. It now keeps the stored text exactly. The point is that two callers cannot drift. A transaction rendered in a list, exported to CSV, or printed by a script now describes itself identically, because it is the same code deciding. `CategoriesActions.ts` keeps what is the app's: the account's subcategories file and the Redux state around it. Reads and writes go through `serializeByKey`, one at a time per account, so a second tap in `CategoryModal` cannot drop the first one's entry and a slow mount read cannot overwrite a list that was just added to. The file is cleaned: JSON that is not a categories object is not read as the defaults. The modal shows the defaults instead, and the first add keeps the unreadable file as `Categories.json.unreadable-<ms>` before starting the list again, so nothing is lost and the feature is not left dead on every device. Category names are read when they are shown, never captured while the module loads, because `applyLocale` replaces the strings in place. `txActionConstants.ts` goes: its table is `txDisplay/txActionLabels` now.
Three small pieces of GUI state that any caller reading transactions needs, and none of which had a reason to be Redux-only. `exchangeDenom` picks the denomination a currency or token reports amounts in. `DenominationSelectors` keeps its selector shape and calls it, so the two cannot disagree about what a multiplier is. `spamThreshold` decides which incoming transactions are dust worth hiding. The GUI applies it to every list; a caller that reads the same wallet and does not apply it sees a different set of transactions, which is the sort of difference that looks like a bug in whichever one you did not write. `localAccountSettings` reads the device-local settings file that holds the spam filter toggle, and `LocalSettingsActions` reads through it rather than duplicating the format. The threshold needs a rate, and asks for it at the current hour rather than the current millisecond, so repeated listings share one cache entry instead of missing on every call. It is a different source from the GUI's, which reads live rates from Redux, and a lookup that fails yields no filtering — stated in the module, because the two can legitimately disagree. A settings file that is *there* and cannot be read is not the same as one that was never written, and both readers say which they got. `readLocalAccountSettingsOrDefaults` answers `trusted: false` for the first, because its defaults have the spam filter *on*: substituting them silently applies a floor to an account that turned the filter off, and a caller that caches them must not then mark itself authoritative, or a later write persists them over the real file. So the threshold declines to filter on an untrusted read — no floor is the safe direction, the same one a non-finite rate takes — and reports it. A write never starts from those defaults. Every local writer goes through `updateLocalAccountSettings(account, update)`, which applies the caller's change to a base it establishes itself: the cache when it is trusted, and otherwise `readLocalAccountSettingsForWrite`, which reads the file strictly, twice. When both reads fail on the content, the file is recovered rather than refused for ever: text that does not parse is kept as `Settings.json.unreadable-<ms>`, and a box that will not decrypt leaves nothing to keep and is deleted; either way the answer says which. A failure that says nothing about the content — a permission error, a descriptor limit — is rethrown and the file stays. Writes are serialized per account, as `change-local-settings` does. The synced `Settings.json` has one write door too, `updateSyncedSettings(account, update)`, which applies the change to a strict read made for that write, so a stale or defaults-based object can never be written over the real file. Collections are changed inside the updater — the most-recent wallets list, the security-check map — so a caller's old copy cannot replace the file's. An unreadable file stops the write with a translated message, and there is no recovery door: this file is on the synced repo, where a sync may still bring a good copy. The login-time denomination migration goes through the same door, so one failed read no longer writes the whole file out as defaults. `syncedSettingsAreTrusted` reports only the login read, which is what fills Redux, so the export can tell whether the units and fiat it holds are the account's own. `syncedSettingsFile` holds the one definition of the synced `Settings.json` that Node-safe code reads. The GUI's own cleaner sits behind an Airship import and cannot be loaded here, so this is a two-field view of the same file with the same defaults, and a test asserts those defaults still match the GUI's.
`TransactionExportActions.tsx` was a five-hundred-line thunk that did four separable jobs: fill in historical fiat values, render CSV, render QBO, and render the Bitwave format. Only the last step needed React Native, and only for writing the file. `fillTxsFiat` asks the rates server what each transaction was worth on the day it happened, which is the part that makes an export more than a dump of native amounts. `txExport/format` renders the three formats. `exportTxInfo` holds the Bitwave account mapping the exporter needs. The thunk keeps the file-writing and the share sheet, and calls the same renderers. `TransactionsExportScene` follows it. A test now covers `fillTxsFiat` against a partial wallet, which is all it reads. The formats matter here: an export that a person reconciles against their books has to be byte-identical whichever tool produced it, and the only way to be sure of that is for one renderer to produce both. Which is not only the renderers but the *dispatch* over them, so `buildExportFiles` is here too. The three formats want different denominations — CSV and QBO carry the amount beside a unit, in the user's display units, while Bitwave has no unit field at all and its `amount` has to be the exchange denomination or a row reads `50000 BTC` for 0.0005 BTC — and deciding that per caller is how the two came to disagree. One exhaustive `switch` with a `never` default decides it once, so a fourth format cannot be half-wired, and `TX_EXPORT_FORMAT_INFO` holds each format's file suffix and media type beside the format set rather than in three non-exhaustive copies. `fillTxsFiat` reports what it could not price instead of writing a zero for it, so a caller can tell a priced export from a short one. `planTxExport` makes the decisions that come before rendering — which formats, with which Bitwave account id, and what the user must be told — where a test can reach them. A Bitwave format with no account id is dropped and reported, settings that could not be read stop the export, and rates the queue gave up on still produce the files, with the count of unpriced rows shown, because refusing made a full-history export unobtainable.
`SendScene2` saved a sent transaction and then attached its metadata, its category, its notes and any swap details in a sequence that had to happen in a particular order and had grown inline in the scene. A second caller that saved a transaction and got the order wrong would produce a transaction that looks right until someone exports it. `txTagging/apply` holds that sequence. `SendScene2` calls it and loses two dozen lines. The scene was the only definition of what a correctly tagged transaction is, and now it is not the only caller that can produce one. It re-applies only the fields the caller actually supplied. Under `EdgeMetadataChange` an empty string is a value rather than "leave unchanged", so passing all three through would let a caller who set one field erase the other two that core derived. The trigger is any non-empty name, notes or category, which is wider than the scene's old `payeeName != null` check and preserves a category that would otherwise be lost; callers pass the metadata they were given, never computed display metadata. It also switches on `edge/no-module-scope-lstrings`, added with `Make network and utils Node-safe`, as an error for `src/cli`, `src/locales` and `src/util`, which lint clean of module-scope `lstrings` reads at this point, so from here a regression fails lint. The config block's comment speaks of the CLI and its `bootNodeLocale`, which the next commit adds; these trees are the ones it loads without the app's boot.
A long-lived engine daemon owns the `EdgeContext` and answers a JSON
REST API over a Unix socket; the `edge-cli` binary is a thin one-shot
client that spawns the engine on demand and keeps a session id in
`session.json` so commands chain. `docs/EDGE_CLI.md` describes that
architecture and deliberately documents no endpoints — the reference is
generated.
The point of this commit is the declaration format, so it carries one
group of each shape rather than the whole surface. Each is one
`route({…})`: the core call it fronts, the HTTP method and path, how it
appears on the command line, cleaners for the query, body and response,
and its error codes. The prose lives inside the declaration, beside the
field it describes, and the JSDoc above carries what belongs to the call
as a whole.
Nothing is written twice. The command line, the help text, the OpenAPI
document and the HTML reference are all derived from these declarations,
and the derived artifacts are committed so a fresh clone needs no build
step. Four gates run in the pre-commit hook and reject the ways they
could drift apart: a route with no command, a handler reading a field
its cleaner would strip, a request parameter the core call does not
have, and a generated file that is stale. The fifth asks whether a
command is exercised by a test, so it arrives with the suites that drive
the whole surface, in the commit that completes it.
The shapes worth reviewing are all here:
- no arguments, engine-local — `engine-status`, `engine-config`
- no arguments, reaching core — `local-users`, `fetch-login-messages`
- one named argument — `username-available`
- a body, and the session it establishes — `create-account`,
`login-with-password`, `logout`
- a positional path parameter — `object-get`, `object-delete`
- a held-open stream — `subscribe`
Path parameters are base58 identifiers and nothing else, because base64
wallet ids and free-text usernames contain `/` and cannot survive a URL
unescaped. Everything else is a named argument. A positional is declared
once as an ordinary field and the path is derived from it, so the two
cannot disagree.
`--fake` serves an in-process `makeFakeEdgeWorld`, which is what lets
the CLI tests run in a hook with no network, no server and no API key.
Core values with methods on them cannot cross JSON, so the engine keeps
them and hands back a handle: a staged transaction, a pending login, a
swap quote, a lobby. A handle carries its own TTL and is released when
the caller finishes with it, and a call that consumes one — approving a
swap — marks it in flight first, so a client that retries after its own
socket timeout is refused with `OBJECT_IN_USE` rather than spending
twice. A call that keeps its handle holds it the same way, so a
broadcast that outlives the TTL still returns its txid instead of
expiring between the send and the reply. Reading a handle returns a
projection, never the live object: serializing an `EdgeAccount` would
walk its `otpKey` and `recoveryKey` getters, and a swap quote reaches
both wallets and every token they know.
`cli:plugins:check` is a gate on the packages the engine registers
rather than on this repository: every relative `require` in a bundled
plugin's `lib` has to resolve, and every plugin family's `*Tools.js` has
to load. Five do not today, in `edge-currency-accountbased`, which is
why `docs/EDGE_CLI.md` carries a table of which asset families a Node
CLI can actually carry. The gate fails on a new breakage *and* on one of
the five being fixed, so the list is cleaned up when that dependency
releases instead of becoming permanent.
Responses are validated against the same cleaners that document them.
`checkResponse` runs each one and discards the cleaned value, since a
cleaner strips unknown keys and returning it would delete fields the
engine means to send; `EDGE_CLI_CHECK_RESPONSES` decides whether a
mismatch warns, fails the request, or is skipped. Drift shows up in the
log rather than reaching a caller unnoticed.
What is fatal is decided here, and it is narrow. An `uncaughtException`
unwound a stack and left state nothing can reason about, so the engine
logs it, shuts down and exits non-zero — and keeps its startup log, the
one file that then says why. An unhandled rejection is *not* fatal,
which is not Node's default: a rejection nobody awaited means only that
whatever was going to read that value has none, and this process hosts
third-party plugins, one of which rejects on a timer. Treating it as
fatal cost every session, every live stream and every handle in the
daemon. It is reported with the whole rejected value — `inspect`, not
`String`, since a plugin rejects with a plain object and `String`
renders that as `[object Object]` — and the engine stays up.
Everything else that recovers reports to one place. The engine points
`reportWarning`'s sink and `configureExchangeRates`' hooks at its own
logger at boot, so a rates server that fails, an unreadable settings
file and an asset whose token the plugin dropped all reach
`engine-<profile>.log` rather than a terminal nobody is watching.
`apiCredentials` decides what every request is signed with: an explicit
`-k` overrides the key and drops the `keys.json` secret that does not
belong to it, a key from the config file is only where the key came from
and keeps both, and `EDGE_CLI_FORCE_KEYS_JSON` or `-k` skips the native
signer. Which signer is chosen decides which `appKeys` layer the info
server serves, so it is a pure function with a table rather than four
decisions inline behind an I/O call.
One engine serves one profile, and it claims the profile by creating its
run file exclusively before opening the data directory, so two cold
invocations cannot hold two `EdgeContext`s on one set of repos or unlink
each other's socket. The idle timer counts in-flight requests as well as
sessions and subscribers, so a cold login cannot be shut down underneath
itself. Everything the engine reads from disk — its run file, the
client's session file, the account's synced settings — goes through a
cleaner, and the bearer tokens in an OTP challenge are masked on their
way to a terminal while staying in the REST body the commands read them
from.
Account and session management, credentials, 2FA and vouchers, the data
store, keys and wallets, tokens, URIs, transactions and their export,
the staged spend path, swaps, exchange rates, and the `$internalStuff`
admin calls — the rest of the surface, each call its own `route({…})`
declaration carrying its own cleaners, error list and prose.
With the surface complete, the suites that drive all of it arrive too:
`testCliFake` and `testCliSubscribe` spawn a real engine daemon on a
Unix socket under a temporary data directory and walk every command
against the in-process fake world, needing no network and no API key —
and the fifth documentation gate, the one that asks whether a command's
handler is ever reached, counts them. `docs/api/README.md` is the
contributor's guide to the declaration format and to all five gates.
They hold across every route: the surface matches, each response field
carries prose, each call either matches its `edge-core-js` signature or
records why it differs, and every command either reaches its handler
offline or is listed with the suite that drives it instead. `npm run
docs:api:gates` reports the counts; they are not repeated here, because
a number in a commit message goes stale the first time a route is added.
Some handlers no offline suite can reach past a refusal: a spend needs
funds, a swap a live partner, a voucher a pending login. The coverage
gate lists each with what does reach it, either a handler suite such as
`spendHandlers.test.ts` or `ratesRoutes.test.ts`, which it checks
exists, or the reason nothing can. No command is excused as reachable
only over the network.
Where the API departs from `edge-core-js` it is recorded in `coreExtra`
with the reason — a wallet object that cannot cross HTTP as anything but
an id, the `to`/`amount` shorthand that expands into `spendTargets`,
engine-side paging and export on `get-transactions`. Anything not listed
there fails the build.
A caller's mistake is a refusal, not a success. Core's own surface is
tolerant in ways an API cannot be — `changeEnabledTokenIds` filters out
an id it does not know and answers 200, so a mistyped contract address
was indistinguishable from a no-op; a voucher id the login server has
never seen is forwarded and reported as approved, while the server
approves the real login on a timer; a `--token-id` the wallet tracks
nothing for answered an empty list and exit 0. Each of those is now a
`404` or a `400` naming the field, raised before anything is written,
and the declared error list says so. The same stance covers a pair of
fields that contradict each other: a `spendInfo` beside a `tokenId`, a
saved export preference with no format to save.
Where a value cannot be derived safely the call refuses rather than
guesses. `rates-usd-to-native` requires its `multiplier`, because this
route has no logged-in account to read a denomination from and an
assumed one returns a `nativeAmount` wrong by orders of magnitude.
`sign-bytes` rejects malformed base64 instead of signing whatever
decoded. Handles record the resolved `wallet.id`, so a wallet id and a
unique prefix of it name the same wallet on every step of a staged
spend.
The CLI is built from this repository but is not this repository: rollup inlines every module it reaches under `src/`, so a published package is the two bundles, the CLI document as its README and `LICENSE`. Nothing about it needs the CLI to move to a workspace or a submodule, and the app's own `package.json` stays `private: true` — what is published is a separate manifest assembled in a temporary directory, so the app itself cannot reach npm by accident. `src/cli/npmMeta.ts` holds the decisions: the scoped name, the bin name, the licence — `BSD-3-Clause`, the CLI's own, not the app's `SEE LICENSE IN LICENSE`, which names a file a published package does not carry. There are no per-platform native packages. The version is not among them. The CLI ships in lockstep with the app, so the manifest takes it from the app's `package.json`: there is no second number to bump, and a published CLI says which app release it corresponds to. Lockstep costs one thing worth knowing before a release — npm will not replace an existing version, so a CLI-only fix goes out on the next app version bump rather than on its own. The dependency list is derived, not written down. `rollup.config.cli.mjs` externalises every key of the app's `dependencies` — its whole runtime set — so the bundles leave all of them as bare `require`s while needing fifteen, and anything the app does not declare is inlined instead. `buildCliManifest.ts` walks the module graph from both entry points, keeps the bare specifiers the app declares as dependencies, drops builtins and type-only imports, and treats the rest as bundled. Checked against the bundles' own `require` calls: fifteen declared and none missing, which is the direction that decides whether an install can run — three of the fifteen (`date-fns`, `edge-info-server`, `uuid`) rollup inlines rather than externalises, so the tarball declares a little more than it strictly needs. Hand-maintaining that list fails as an `npm install` that succeeds and a CLI that cannot resolve a module on first run, so `cli:manifest:check` gates it in `verify` and the pre-commit hook. `npm run prepare` regenerates it as it does the documentation artifacts, so in CI, as for those, `docs:api:committed` is what catches a stale one. `publishCli.ts` builds, stages and publishes, and by default the tarball carries no HMAC addon. The addon's shards rebuild the same `apiSecret` the mobile release builds sign with, from a pad that is a constant in this public repository, so shipping it would hand that secret to anyone with `npm pack` and `strings`. An unsigned CLI needs an `edgeApiKey` of its own, and the staged README says so. `--with-signer --signer-secret-is-cli-only` is the opt-in for a key pair issued to the CLI; `--with-signer` alone is refused. Each way a publish could go wrong is refused before it happens, because npm will not replace a version: - a working tree that is dirty, or that git cannot describe; - a HEAD that cannot be read, or that no long-lived branch (`develop`, `master`, `staging`) or tag contains after a fetch, since the README's links into this repository are pinned to it and a feature branch's next force-push would drop the commit; - a plugin family the bundled packages are known to break (`scripts/util/knownPluginBreakage.js`, which `cli:plugins:check` holds the installed packages to), unless `--allow-broken-plugins`; - a signer addon whose name is missing from the manifest's `files`, the allowlist npm packs from; - a flag whose value is missing or is itself a flag — `--out` with the path left off used to fall through to `npm publish --access public`. `--dry-run` packs without publishing and `--out` stages for inspection. CI moves from Node 18 to 22 for every build of this repository, because `cli:plugins:check` enters `.travis.yml` here and loads every plugin's tools: the Solana family reaches `rpc-websockets`, which `require`s the ESM-only `uuid@14`, and Node can `require()` ESM only from 20.19 and 22.12. The same floor is the package's `engines` — below it an install succeeds and Solana alone fails to load. Today the plugin refusal stops every publish: the EVM chains need an `edge-currency-accountbased` release that ships `lib/ethereum/abi/`. One thing the exercise surfaced, not fixed here: installing the package costs 2.3 GB across 69,756 files, of which about 1.3 GB is React Native mobile binaries — iOS simulator slices and Android libraries for the privacy coins — reached through `edge-currency-accountbased`, which also brings `react-native` itself. A Node CLI can load none of it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds the Edge CLI —
edge-cliand theedge-enginedaemon behind it — andthe work that had to come first: nine commits that move display metadata,
denominations, spam-threshold resolution, local and synced settings, the
transaction export pipeline, transaction tagging, locale selection, exchange
rates and the network helpers out of GUI-only modules so they load under
plain Node, with no behaviour change to the app.
The engine is a long-lived process owning an
EdgeContext, serving JSON overa Unix socket (with an optional token-authenticated loopback TCP listener).
The client is thin: it spawns the engine on demand, forwards one request and
prints the answer. 117 routes, each its own
route({…})declaration carryingits cleaners, its error list and its prose; the command table, the help text
and the OpenAPI reference are generated from those declarations and
committed.
Five documentation gates hold over the surface — the generated artifacts are
current, the surface matches, every response field carries prose, each call
matches its
edge-core-jssignature or records why it differs, and everycommand either reaches its handler offline against the fake world or is
listed with the suite that drives it.
npm run docs:api:gatesruns them;cli:manifest:checkanddocs:api:committedrun beside them.The twelve commits are meant to be read in order, and each one stands on its
own:
npm test,npm run docs:api:gates,npm run test:cli:node-safeandnpm run test:cli:offlinepass on every tree, with the npm scripts, theCHANGELOG entries and the CI steps landing in the commit that adds the file
each one names.
Not included, and waiting on a decision: the published package carries no
native HMAC signer. Its shards reconstruct the same
apiSecretthe iOS andAndroid release builds sign with, so shipping it in a public tarball would
hand that secret to
npm packplusstrings.publish:cli --with-signerexists and refuses unless
--signer-secret-is-cli-onlysays the secret isthe CLI's own — which needs an
apiKey/apiSecretpair issued for@edgeapp/cli. Until then a published CLI needs anedgeApiKeyof its ownin
keys.jsonor-k, and says so when it has neither.Documentation:
docs/EDGE_CLI.mdis theguide and the published README;
docs/api/README.mdis the declaration format.
CHANGELOG
Does this branch warrant an entry to the CHANGELOG?
Dependencies
none
Requirements
If you have made any visual changes to the GUI. Make sure you have:
Test plan
npm test— the jest suites, including 50-odd new ones undersrc/__tests__/cliandsrc/__tests__/utilfor the engine's handlers,the client, the rate queue, the locale boot and the export pipeline.
npm run docs:api:gates— the five documentation gates.npm run test:cli:node-safe— both CLI entry points loaded under plainNode with a
react-nativeimport poisoned, so a module-scope leak intothe shared code fails here.
npm run test:cli:offline—testCliFakeandtestCliSubscribedrive areal engine daemon on a Unix socket under a temporary data directory,
against the in-process fake world. No network, no API key.
npm run test:cli:offline:built— the same suites against the rollupbundle, which is what a published CLI runs.
npm run test:cli:network— the one-shot, CAPTCHA and edge-login suitesagainst the tester fleet. Needs the network and an Edge API key.
CLI session on the tester servers
Run on 2026-10-10 against
9beff6d7d:paul/cli(da1b8fe8, rebased on its master) packed in throughpack-dependencies, thennpm run build:cli:all.test:cli:networkagainst the tester fleet passed: one-shot 13/13, CAPTCHA, edge-login.test:cli:offlineagainst the built bundle passed: 242 fake-world checks plus the subscribe suite.Then the session below, run with the built CLI as
clitester, sending funds to and fromsharetestand swapping LTC to BTC. Every command is shown as typed, with its full output and exit code. Passwords went throughEDGE_CLI_PASSWORDand show as<redacted>; session ids are shortened. The full log, byte arrays included, is at https://balls.edge.app/pr-artifacts/edge-react-gui/cliTesterSession/202610101758-cli-session.log.Every command below was run with the built CLI (
lib/edgeCli.js, shown asedge-cli), from edge-react-guipaul/cliat5bda66390with edge-currency-accountbasedpaul/cliatda1b8fe8packed in (https://balls.edge.app/20261010174309-edge-currency-accountbased-4.102.0.tgz).-tpoints the client and engine at the tester servers: login-tester, info-tester, sync-tester.EDGE_CLI_PASSWORDand appear as<redacted>. PINs never appear, and live session ids are shortened tosess_….clitester(funded) andsharetest(the receiver), each with its own data directory.engine-configlogin-with-password(both accounts, password fromEDGE_CLI_PASSWORD)get-addressesltc1qmcs05z9stqwxlm48f3ja66qnu9w9edpvc6c456; clitester LTCltc1qfkvdvrcr8g82mr72q7u67p8yzpg7yl3n3nm9nw, BTCbc1q5kjamtm0424shsjp4dng3z85xxrqhgdzm7j7crencode-urilitecoin:ltc1qmcs…?amount=0.005&label=sharetestspend --dry-runspendclitester → sharetest, 0.005 LTC9ca11b2d32db160c39434b4b989ef737a08debc346411d792097ff5c21cd7c83; seen by sharetestspendsharetest → clitester, 0.002 LTCb9acbae3efc486c7e0bc423a64b0ca6131d7049b06ae4a64c2e09fd8a01a98f2fetch-swap-quotesandapprove-swap-quote, 0.05 LTC → BTC (THORChain)0f0a34872761fb57db762bb82660ea5142fc6fd894324ca1238a217f91236262; 2738 sats paid out, txid9ef7af518502d91bfd6513c624c08ca7ccf94122d3c6bd0d3e4a101c02d40d88approve-swap-quoteafter the exchange's 60 s410 QUOTE_EXPIRED, exit 4, nothing signedlogoutBalances: clitester LTC 2 went from 0.45255611 to 0.39912806, its BTC from 0.00109035 to 0.00111773, and sharetest LTC from 0 to 0.00264937.
The session: 31 commands and their output
2026-10-10 17:50:15 (clitester)
exit 0, 4.1s
2026-10-10 17:50:36 (clitester)
exit 0, 16.9s
2026-10-10 17:50:36 (clitester)
exit 0, 0.3s
2026-10-10 17:50:42 (clitester)
exit 0, 0.3s
2026-10-10 17:50:47 (clitester)
exit 0, 0.2s
2026-10-10 17:50:47 (clitester)
exit 0, 0.1s
2026-10-10 17:50:48 (clitester)
exit 0, 0.1s
2026-10-10 17:51:06 (sharetest)
exit 0, 7.9s
2026-10-10 17:51:06 (sharetest)
exit 0, 0.1s
2026-10-10 17:51:06 (sharetest)
exit 0, 0.1s
2026-10-10 17:51:06 (sharetest)
exit 0, 0.1s
2026-10-10 17:51:13 (clitester)
exit 0, 0.1s
2026-10-10 17:51:13 (clitester)
exit 0, 0.1s
2026-10-10 17:51:13 (clitester)
exit 0, 0.2s
2026-10-10 17:51:18 (clitester)
exit 0, 0.1s
2026-10-10 17:51:24 (clitester)
exit 0, 0.5s
2026-10-10 17:51:37 (clitester)
exit 0, 1.3s
2026-10-10 17:51:59 (sharetest)
exit 0, 1.6s
2026-10-10 17:51:59 (sharetest)
exit 0, 0.1s
2026-10-10 17:52:07 (sharetest)
exit 0, 0.2s
2026-10-10 17:52:19 (clitester)
exit 0, 5.3s
2026-10-10 17:52:28 (clitester)
exit 0, 0.2s
2026-10-10 17:52:40 (clitester)
exit 0, 3.1s
2026-10-10 17:53:43 (clitester)
exit 4, 0.1s
2026-10-10 17:53:50 (clitester)
exit 0, 0.2s
2026-10-10 17:57:25 (clitester)
exit 0, 1.5s
2026-10-10 17:57:25 (clitester)
exit 0, 0.1s
2026-10-10 17:57:25 (clitester)
exit 0, 0.1s
2026-10-10 17:57:25 (sharetest)
exit 0, 0.1s
2026-10-10 17:57:26 (sharetest)
exit 0, 0.1s
2026-10-10 17:57:26 (clitester)
exit 0, 0.1s