dexbot 1.6.8 → 1.6.10

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.
Files changed (70) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/analysis/README.md +1 -1
  3. package/analysis/tradingview/README.md +14 -9
  4. package/claw/modules/chain_queries.ts +9 -4
  5. package/claw/modules/claw_bridge.ts +9 -9
  6. package/claw/package.json +1 -1
  7. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  8. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  9. package/dist/analysis/ama_fitting/optimizer_high_resolution.js +2 -1
  10. package/dist/analysis/bot_fitting/backtest_ama_sweep.js +2 -2
  11. package/dist/analysis/bot_fitting/backtest_bot_fitting.js +4 -4
  12. package/dist/analysis/bot_key_utils.js +14 -4
  13. package/dist/analysis/tradingview/analyze_tradingview.d.ts +0 -3
  14. package/dist/analysis/tradingview/analyze_tradingview.js +3 -14
  15. package/dist/analysis/tradingview/grid_reset_sim.d.ts +11 -1
  16. package/dist/analysis/tradingview/grid_reset_sim.js +22 -9
  17. package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +178 -32
  18. package/dist/analysis/trend_detection/dynamic_weight_chart_generator.js +8 -3
  19. package/dist/dexbot.js +57 -29
  20. package/dist/market_adapter/core/market_adapter_service.d.ts +81 -1
  21. package/dist/market_adapter/core/market_adapter_service.js +225 -18
  22. package/dist/market_adapter/core/signals/hurst_analyzer.d.ts +10 -1
  23. package/dist/market_adapter/core/signals/hurst_analyzer.js +40 -18
  24. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.d.ts +26 -2
  25. package/dist/market_adapter/core/signals/permutation_entropy_analyzer.js +132 -29
  26. package/dist/market_adapter/core/strategies/ama_slope_model.d.ts +2 -2
  27. package/dist/market_adapter/core/strategies/ama_slope_model.js +12 -10
  28. package/dist/market_adapter/core/strategies/dynamic_weight_series.d.ts +41 -14
  29. package/dist/market_adapter/core/strategies/dynamic_weight_series.js +138 -30
  30. package/dist/market_adapter/core/strategies/regime_gate.d.ts +61 -3
  31. package/dist/market_adapter/core/strategies/regime_gate.js +207 -7
  32. package/dist/market_adapter/interval_utils.d.ts +18 -1
  33. package/dist/market_adapter/interval_utils.js +31 -1
  34. package/dist/market_adapter/lp_chart_strategy_loader.js +2 -1
  35. package/dist/market_adapter/market_adapter.d.ts +151 -2
  36. package/dist/market_adapter/market_adapter.js +378 -62
  37. package/dist/market_adapter/test_helpers.d.ts +2 -2
  38. package/dist/market_adapter/test_helpers.js +2 -2
  39. package/dist/market_adapter/utils/chain.d.ts +1 -1
  40. package/dist/market_adapter/utils/chain.js +8 -6
  41. package/dist/market_adapter/utils/file_json_cache.d.ts +29 -0
  42. package/dist/market_adapter/utils/file_json_cache.js +106 -0
  43. package/dist/modules/account_bots.js +5 -4
  44. package/dist/modules/bitshares-native/resolvers.js +5 -0
  45. package/dist/modules/bot_settings.js +13 -1
  46. package/dist/modules/chain_orders.js +2 -1
  47. package/dist/modules/config.d.ts +6 -0
  48. package/dist/modules/config.js +1 -0
  49. package/dist/modules/constants.d.ts +11 -1
  50. package/dist/modules/constants.js +64 -15
  51. package/dist/modules/credential_policy.js +4 -1
  52. package/dist/modules/credit_runtime.js +5 -1
  53. package/dist/modules/order/grid.js +95 -25
  54. package/dist/modules/order/utils/system.js +11 -1
  55. package/dist/modules/utils/asset_symbols.d.ts +59 -0
  56. package/dist/modules/utils/asset_symbols.js +128 -0
  57. package/dist/modules/version_notice.d.ts +166 -20
  58. package/dist/modules/version_notice.js +401 -56
  59. package/dist/pm2.js +9 -2
  60. package/dist/scripts/analyze-credit.js +10 -7
  61. package/dist/scripts/chart_command.js +12 -4
  62. package/dist/scripts/verify-browser-bundle.js +8 -0
  63. package/dist/unlock.js +7 -7
  64. package/docs/DEXBOT_COMPARISON.md +3 -3
  65. package/docs/EVOLUTION.md +14 -12
  66. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  67. package/docs/GRID_RECALCULATION.md +28 -5
  68. package/docs/README.md +2 -2
  69. package/market_adapter/README.md +30 -2
  70. package/package.json +1 -1
@@ -58,6 +58,7 @@ import * as OrderUtils from './order.js';
58
58
  import Logger from '../../order/logger.js';
59
59
  import { runtime } from '../../runtime.js';
60
60
  import { getErrorMessage } from '../../utils/errors.js';
61
+ import { normalizeAssetRef } from '../../utils/asset_symbols.js';
61
62
  import { withTimeout } from './timeout.js';
62
63
  const { ensureDir, readJSON } = storage;
63
64
  const systemLogger = new Logger('System');
@@ -117,6 +118,13 @@ const poolIdCache = new Map();
117
118
  export const lookupAsset = async (BitShares, s) => {
118
119
  if (!BitShares)
119
120
  return null;
121
+ // BitShares symbols are canonical UPPERCASE and object ids ("1.3.x") are
122
+ // passed through; normalizing here means every caller (price derivation,
123
+ // fee cache, pool lookup) hits the chain with the canonical spelling.
124
+ // Only real symbols are rewritten: a blank/non-string ref must keep its
125
+ // original spelling in the CRITICAL error below.
126
+ if (typeof s === 'string' && s.trim())
127
+ s = normalizeAssetRef(s);
120
128
  let cached = null;
121
129
  if (BitShares?.assets) {
122
130
  try {
@@ -161,7 +169,9 @@ export const lookupAsset = async (BitShares, s) => {
161
169
  export const resolveAssetByRef = async (BitShares, ref) => {
162
170
  if (!BitShares?.db)
163
171
  return null;
164
- const cacheKey = String(ref);
172
+ // Same rule as lookupAsset: canonicalize real symbols, leave anything else
173
+ // (object ids pass through, junk keeps its original spelling) untouched.
174
+ const cacheKey = typeof ref === 'string' ? normalizeAssetRef(ref) : String(ref);
165
175
  const method = /^1\.3\.\d+$/.test(cacheKey) ? 'get_assets' : 'lookup_asset_symbols';
166
176
  const camelMethod = method.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
167
177
  try {
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Central asset-symbol / asset-ref normalization.
3
+ *
4
+ * BitShares stores asset symbols canonically UPPERCASE, so the assetA and
5
+ * assetB symbols of a bot pair are always UPPERCASE on chain.
6
+ * Nodes accept a lowercase lookup and answer it without error, so a lowercase
7
+ * symbol never fails — it just travels on as lowercase into everything built
8
+ * from it: the `symbol` field we attach to resolved assets, chart titles,
9
+ * cache-file names, Kibana query terms, and strict in-process comparisons such
10
+ * as the core-asset side check `assetA === 'CORE'`. That is a
11
+ * silent-wrong-answer class of bug, not a loud
12
+ * one, so the conversion is done ONCE here and applied at every boundary that
13
+ * accepts a pair from a human (CLI prompts, `dexbot tv`/`dw` targets) or hands
14
+ * a symbol to the chain (`lookup_asset_symbols`).
15
+ *
16
+ * Rules:
17
+ * - Asset OBJECT IDs ("1.3.x") are not symbols: they are returned verbatim so
18
+ * ref-routing callers (get_assets vs lookup_asset_symbols) keep working.
19
+ * - Everything else is trimmed and uppercased.
20
+ * - Non-strings / empty input normalize to '' (never "undefined"/"null").
21
+ *
22
+ * Browser-safe: no node built-ins.
23
+ */
24
+ /** True when the value is a BitShares asset object id, not a symbol. */
25
+ export declare function isAssetObjectId(value: unknown): boolean;
26
+ /**
27
+ * Canonicalize an asset symbol (or pass an asset object id through untouched).
28
+ * This is the single conversion used before a symbol reaches the blockchain
29
+ * and before it is compared, cached, or rendered.
30
+ */
31
+ export declare function normalizeAssetSymbol(value: unknown): string;
32
+ /**
33
+ * Same as {@link normalizeAssetSymbol}; reads better at call sites that pass a
34
+ * mixed "id or symbol" reference (credit runtime, credential policy, pools).
35
+ */
36
+ export declare function normalizeAssetRef(value: unknown): string;
37
+ /** Case- and whitespace-insensitive asset-symbol equality. */
38
+ export declare function isSameAssetSymbol(a: unknown, b: unknown): boolean;
39
+ /**
40
+ * Split an "assetA/assetB" CLI target into the two normalized symbols.
41
+ * Whitespace around either leg is dropped and both legs are uppercased, so
42
+ * "assetb/asseta" and "ASSETB / ASSETA" produce the same assetA/assetB pair.
43
+ * @returns exactly two symbols, or [] when the target is not a usable pair.
44
+ */
45
+ export declare function splitPairTarget(target: unknown): string[];
46
+ /**
47
+ * Canonicalize the asset symbols of a bot config entry, recursively into
48
+ * `debtPolicy.lending[]`. This is the single definition of WHICH config keys
49
+ * hold symbols, shared by every config reader:
50
+ * - `modules/bot_settings.normalizeBotEntry` (production read funnel)
51
+ * - `analysis/bot_key_utils.loadBotMeta` (analysis/tools read funnel)
52
+ *
53
+ * Returns the SAME reference when there is nothing to canonicalize, so the
54
+ * common already-uppercase case costs one pass and no allocation, and a
55
+ * hand-edited lowercase entry never leaks into a chain call, a comparison or
56
+ * a rendered label. The input is never mutated.
57
+ */
58
+ export declare function canonicalizeBotAssetSymbols<T extends Record<string, any>>(entry: T): T;
59
+ //# sourceMappingURL=asset_symbols.d.ts.map
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Central asset-symbol / asset-ref normalization.
3
+ *
4
+ * BitShares stores asset symbols canonically UPPERCASE, so the assetA and
5
+ * assetB symbols of a bot pair are always UPPERCASE on chain.
6
+ * Nodes accept a lowercase lookup and answer it without error, so a lowercase
7
+ * symbol never fails — it just travels on as lowercase into everything built
8
+ * from it: the `symbol` field we attach to resolved assets, chart titles,
9
+ * cache-file names, Kibana query terms, and strict in-process comparisons such
10
+ * as the core-asset side check `assetA === 'CORE'`. That is a
11
+ * silent-wrong-answer class of bug, not a loud
12
+ * one, so the conversion is done ONCE here and applied at every boundary that
13
+ * accepts a pair from a human (CLI prompts, `dexbot tv`/`dw` targets) or hands
14
+ * a symbol to the chain (`lookup_asset_symbols`).
15
+ *
16
+ * Rules:
17
+ * - Asset OBJECT IDs ("1.3.x") are not symbols: they are returned verbatim so
18
+ * ref-routing callers (get_assets vs lookup_asset_symbols) keep working.
19
+ * - Everything else is trimmed and uppercased.
20
+ * - Non-strings / empty input normalize to '' (never "undefined"/"null").
21
+ *
22
+ * Browser-safe: no node built-ins.
23
+ */
24
+ /** BitShares asset object id, e.g. "1.3.0" (the core asset) or "1.3.529". */
25
+ const ASSET_OBJECT_ID_PATTERN = /^1\.3\.\d+$/;
26
+ /** True when the value is a BitShares asset object id, not a symbol. */
27
+ export function isAssetObjectId(value) {
28
+ return ASSET_OBJECT_ID_PATTERN.test(String(value ?? '').trim());
29
+ }
30
+ /**
31
+ * Canonicalize an asset symbol (or pass an asset object id through untouched).
32
+ * This is the single conversion used before a symbol reaches the blockchain
33
+ * and before it is compared, cached, or rendered.
34
+ */
35
+ export function normalizeAssetSymbol(value) {
36
+ if (value === null || value === undefined)
37
+ return '';
38
+ const text = String(value).trim();
39
+ if (!text)
40
+ return '';
41
+ if (ASSET_OBJECT_ID_PATTERN.test(text))
42
+ return text;
43
+ return text.toUpperCase();
44
+ }
45
+ /**
46
+ * Same as {@link normalizeAssetSymbol}; reads better at call sites that pass a
47
+ * mixed "id or symbol" reference (credit runtime, credential policy, pools).
48
+ */
49
+ export function normalizeAssetRef(value) {
50
+ return normalizeAssetSymbol(value);
51
+ }
52
+ /** Case- and whitespace-insensitive asset-symbol equality. */
53
+ export function isSameAssetSymbol(a, b) {
54
+ const na = normalizeAssetSymbol(a);
55
+ const nb = normalizeAssetSymbol(b);
56
+ return na !== '' && na === nb;
57
+ }
58
+ /**
59
+ * Split an "assetA/assetB" CLI target into the two normalized symbols.
60
+ * Whitespace around either leg is dropped and both legs are uppercased, so
61
+ * "assetb/asseta" and "ASSETB / ASSETA" produce the same assetA/assetB pair.
62
+ * @returns exactly two symbols, or [] when the target is not a usable pair.
63
+ */
64
+ export function splitPairTarget(target) {
65
+ return String(target ?? '')
66
+ .split('/')
67
+ .map((part) => normalizeAssetSymbol(part))
68
+ .filter((part) => part !== '');
69
+ }
70
+ // ── Config-level canonicalization (the one place that knows the key names) ────
71
+ /** bots.json keys holding an asset SYMBOL at the top level of a bot entry. */
72
+ const BOT_ASSET_SYMBOL_KEYS = ['assetA', 'assetB'];
73
+ /** `debtPolicy.lending[]` keys holding an asset SYMBOL. */
74
+ const LENDING_ASSET_SYMBOL_KEYS = ['asset', 'collateralAsset'];
75
+ /**
76
+ * Canonicalize the asset symbols of a bot config entry, recursively into
77
+ * `debtPolicy.lending[]`. This is the single definition of WHICH config keys
78
+ * hold symbols, shared by every config reader:
79
+ * - `modules/bot_settings.normalizeBotEntry` (production read funnel)
80
+ * - `analysis/bot_key_utils.loadBotMeta` (analysis/tools read funnel)
81
+ *
82
+ * Returns the SAME reference when there is nothing to canonicalize, so the
83
+ * common already-uppercase case costs one pass and no allocation, and a
84
+ * hand-edited lowercase entry never leaks into a chain call, a comparison or
85
+ * a rendered label. The input is never mutated.
86
+ */
87
+ export function canonicalizeBotAssetSymbols(entry) {
88
+ if (!entry || typeof entry !== 'object')
89
+ return entry;
90
+ let changed = false;
91
+ const out = { ...entry };
92
+ for (const key of BOT_ASSET_SYMBOL_KEYS) {
93
+ if (typeof out[key] === 'string') {
94
+ const canonical = normalizeAssetSymbol(out[key]);
95
+ if (canonical !== out[key]) {
96
+ out[key] = canonical;
97
+ changed = true;
98
+ }
99
+ }
100
+ }
101
+ if ('debtPolicy' in out) {
102
+ const policy = out.debtPolicy;
103
+ if (policy && typeof policy === 'object' && Array.isArray(policy.lending)) {
104
+ let lendingChanged = false;
105
+ const lending = policy.lending.map((item) => {
106
+ if (!item || typeof item !== 'object')
107
+ return item;
108
+ const canonicalItem = { ...item };
109
+ for (const key of LENDING_ASSET_SYMBOL_KEYS) {
110
+ if (typeof canonicalItem[key] === 'string') {
111
+ const canonical = normalizeAssetSymbol(canonicalItem[key]);
112
+ if (canonical !== canonicalItem[key]) {
113
+ canonicalItem[key] = canonical;
114
+ lendingChanged = true;
115
+ }
116
+ }
117
+ }
118
+ return canonicalItem;
119
+ });
120
+ if (lendingChanged) {
121
+ out.debtPolicy = { ...policy, lending };
122
+ changed = true;
123
+ }
124
+ }
125
+ }
126
+ return (changed ? out : entry);
127
+ }
128
+ //# sourceMappingURL=asset_symbols.js.map
@@ -21,23 +21,40 @@
21
21
  * prompt).
22
22
  * 2. NEVER THROWS. Every failure path — offline, DNS failure, slow registry,
23
23
  * unreadable cache, browser — resolves to `null`.
24
- * 3. NO SUBPROCESSES. The registry is queried with a single HTTPS GET and a
24
+ * 3. NO SUBPROCESSES. Each source is queried with a single HTTPS GET and a
25
25
  * hard timeout. `execSync('npm view ...')` (as used by `dexbot update`)
26
26
  * costs 1-3s of spawn and hard-depends on the npm CLI, neither of which is
27
27
  * acceptable on the launcher critical path.
28
+ * 3b. MULTIPLE SOURCES, FALLBACK NOT FAILURE. One source is a single point of
29
+ * failure: a host that cannot reach registry.npmjs.org (firewall, DNS, a
30
+ * proxy only the npm CLI knows about) reported "unknown" forever even when
31
+ * the release was published on GitHub. Sources are tried in order and the
32
+ * first answer wins, so an unreachable registry degrades to a slower probe
33
+ * instead of a permanent "?". Each source is bounded by an even share of
34
+ * the total budget, so a hanging first source cannot starve the second.
35
+ * 3c. NEVER MYSTERY. Every failure path records WHY (`ENOTFOUND`, `HTTP 403`,
36
+ * `timeout`, `no fetch`, …) and the unknown verdict names it. An operator
37
+ * cannot act on "?" and used to have to guess between DNS, TLS, a proxy and
38
+ * a timeout.
28
39
  * 4. THROTTLED + NOTIFY-ONCE. A check runs at most once per
29
- * `UPDATER.NOTICE_INTERVAL_MS`, and the same version is announced only once
30
- * (`notifiedVersion` in the cache) so an ignored notice does not nag on
31
- * every restart. A new published version resets that latch. The latch is
32
- * committed by `printVersionStatus` only AFTER the notice is displayed, so a
40
+ * `UPDATER.NOTICE_INTERVAL_MS` AFTER A SUCCESS, and once per
41
+ * `UPDATER.NOTICE_RETRY_MS` after a failure (a failure is the observation
42
+ * that decays fastest — see the constant). The same version is announced
43
+ * only once (`notifiedVersion` in the cache) so an ignored notice does not
44
+ * nag on every restart. A new published version resets that latch. The latch
45
+ * is committed by `printVersionStatus` only AFTER the notice is displayed, so a
33
46
  * launcher path that returns without printing cannot silently consume it —
34
47
  * it is re-offered once the throttle window expires. A throttled run still
35
48
  * reports a status (from the cached observation) so `dexbot stat` answers
36
49
  * "am I current?" without spending a request.
50
+ * 4a. DEFERRED, NOT DROPPED. Callers that have other work to do (`dexbot stat`
51
+ * prints a process table) start the probe, do their work, and flush the
52
+ * verdict when it lands. Nothing is printed speculatively and nothing is
53
+ * ever truncated by an early `process.exit()`.
37
54
  * 4b. ONE IMPLEMENTATION. Every consumer (`unlock`, `pm2`, `dexbot stat`) goes
38
- * through `startVersionStatusCheck` → `printVersionStatus`; the colour of the
39
- * status line, the hint wording and the latch all live here, so no caller can
40
- * drift from another.
55
+ * through this module — `startVersionStatusCheck` / `startStagedVersionStatus`
56
+ * → `printVersionStatus`; the colour of the status line, the hint wording
57
+ * and the latch all live here, so no caller can drift from another.
41
58
  * 5. SILENT WHEN DISABLED. `Config.DEXBOT_SKIP_VERSION_NOTICE=1` (tests, CI,
42
59
  * automation) or `UPDATER.NOTICE_ENABLED: false` short-circuits before any
43
60
  * network or filesystem work.
@@ -71,6 +88,17 @@ export interface VersionStatus {
71
88
  latestVersion: string | null;
72
89
  installKind: InstallKind;
73
90
  state: VersionState;
91
+ /** Id of the source that answered (`npm` / `github`). */
92
+ source?: string;
93
+ /** Why the probe could not answer — `ENOTFOUND`, `HTTP 403`, `timeout`…
94
+ * Only set when `state === 'unknown'`; rendered in the verdict so the
95
+ * operator can act instead of guessing. */
96
+ reason?: string;
97
+ /** True when the staged wait gave up: nothing answered at all, so the
98
+ * information is MISSING rather than the check having failed. Rendered
99
+ * differently — "no current version information" must not read as
100
+ * "could not check", and neither may read as "up to date". */
101
+ exhausted?: boolean;
74
102
  /** Cache file backing the throttle. Plumbing; callers should not read it. */
75
103
  cacheFile: string;
76
104
  /** Present only when a NEWER version exists AND it has not been announced
@@ -83,10 +111,16 @@ export interface VersionNoticeOptions {
83
111
  currentVersion?: string;
84
112
  /** Override the cache location (tests). */
85
113
  cacheFile?: string;
86
- /** Override the throttle window in ms; `< 0` forces a check. */
114
+ /** Override the throttle window in ms for a SUCCESSFUL cached observation
115
+ * (tests). 0 disables throttling. */
87
116
  intervalMs?: number;
117
+ /** Override the backoff in ms after a FAILED observation (tests). 0
118
+ * disables throttling, so every run re-probes. */
119
+ retryMs?: number;
88
120
  /** Override the registry URL (tests). Pass '' to model an unconfigured setup. */
89
121
  registryUrl?: string;
122
+ /** Override the GitHub releases URL (tests). '' / 'off' disables it. */
123
+ githubReleaseUrl?: string;
90
124
  /** Override `UPDATER.NOTICE_ENABLED` (tests). */
91
125
  enabled?: boolean;
92
126
  /** Override install-kind detection (tests). */
@@ -114,16 +148,87 @@ export interface VersionNoticeOptions {
114
148
  export declare function compareVersions(a: string, b: string): number;
115
149
  /** Classify the running install without spawning anything. */
116
150
  export declare function detectInstallKind(projectRoot?: string): InstallKind;
151
+ /** One place the published version can be read from. */
152
+ export interface VersionSource {
153
+ id: string;
154
+ url: string;
155
+ /** Pull the version out of the source's JSON shape. Returns null when the
156
+ * document does not carry a usable version (bad payload). */
157
+ extract: (body: any) => string | null;
158
+ }
159
+ /**
160
+ * Derive the GitHub "latest release" endpoint from the configured repository
161
+ * URL, so a fork or a self-hosted mirror is honoured without a second hardcoded
162
+ * owner/repo. Returns null for anything that is not a github.com repository —
163
+ * a non-GitHub host has a different API shape and guessing it would produce a
164
+ * guaranteed-wrong request on every probe.
165
+ */
166
+ export declare function deriveGithubReleaseUrl(repositoryUrl: string | undefined, apiBase: string): string | null;
167
+ /**
168
+ * The probe's sources, in priority order.
169
+ *
170
+ * npm FIRST, GitHub second — measured, and the order is load-bearing:
171
+ *
172
+ * latency a wash. Warm, interleaved: npm p50 21ms / github p50 18ms.
173
+ * Cold process: npm 92-102ms / github 97-99ms. GitHub being
174
+ * ~3ms "faster" is noise, not a reason to reorder.
175
+ * payload npm 8KB vs github 40KB (the release document carries the
176
+ * body, assets and author objects). 5x for the same answer.
177
+ * rate limit the GitHub API is 60 requests/hour per IP unauthenticated
178
+ * and answers 403 when spent; npm has no comparable ceiling.
179
+ * Our own 12h throttle keeps us far below it, but a shared
180
+ * server IP or a retry burst is not ours to control.
181
+ * AUTHORITY the deciding one. The release pipeline creates the GitHub
182
+ * release FIRST and publishes to npm ~4-9 minutes LATER
183
+ * (1.6.8 10:15:14Z vs 10:24:00Z; 1.6.7 09:08:48 vs 09:13:15;
184
+ * 1.6.6 00:49:52 vs 00:54:27). GitHub-first would therefore
185
+ * spend that window telling operators a new version exists
186
+ * while `dexbot update` still installs the old one — a hint
187
+ * that is not merely early but wrong. npm lagging by the same
188
+ * minutes is harmless: it says "up to date" a little longer.
189
+ *
190
+ * The cost of this order is the one case that measurably suffers: on a host
191
+ * that cannot reach the registry at all, the fallback answer arrives after the
192
+ * first source's share of the budget is spent (~1.6s of the 3s), versus ~20ms
193
+ * if GitHub went first. That is the right trade — a slow answer is still an
194
+ * answer, and the alternative is an answer that is wrong for the first minutes
195
+ * of every release.
196
+ */
197
+ export declare function resolveReleaseSources(options?: {
198
+ registryUrl?: string;
199
+ githubReleaseUrl?: string;
200
+ repositoryUrl?: string;
201
+ apiBase?: string;
202
+ }): VersionSource[];
117
203
  /**
118
204
  * The single status line, shared by `dexbot stat` and every launcher start.
119
205
  *
120
- * GREEN when the install matches the registry, ORANGE when a newer release
121
- * exists, GRAY when the probe could not answer (offline / throttled with no
122
- * prior observation) — an unknown answer must never be rendered as "up to
123
- * date". The installed version is always named, so a caller never needs a
124
- * second "DEXBot2 vX.Y.Z" header of its own.
206
+ * GREEN when the install matches the published version, ORANGE when a newer
207
+ * release exists, GRAY when the probe could not answer (offline / throttled
208
+ * with no prior observation) — an unknown answer must never be rendered as
209
+ * "up to date". The installed version is always named, so a caller never needs
210
+ * a second "DEXBot2 vX.Y.Z" header of its own. The unknown verdict carries the
211
+ * probe's reason, because an unnamed "?" tells the operator nothing they can
212
+ * act on.
125
213
  */
126
- export declare function formatVersionStatusLine(status: Pick<VersionStatus, 'currentVersion' | 'latestVersion' | 'state'>): string;
214
+ export declare function formatVersionStatusLine(status: Pick<VersionStatus, 'currentVersion' | 'latestVersion' | 'state'> & {
215
+ reason?: string;
216
+ exhausted?: boolean;
217
+ }): string;
218
+ /** What the whole probe concluded. */
219
+ export interface ProbeResult {
220
+ version: string | null;
221
+ source?: string;
222
+ /** Every source's failure reason, in the order they were tried. */
223
+ reasons: string[];
224
+ }
225
+ /**
226
+ * Try the sources in order and take the first answer. The total budget is split
227
+ * EVENLY rather than spent first-come: a source that hangs until the deadline
228
+ * would otherwise leave the fallback with no time at all, which is precisely
229
+ * the case the fallback exists for.
230
+ */
231
+ export declare function probeReleaseSources(sources: VersionSource[], timeoutMs: number, fetchImpl?: any): Promise<ProbeResult>;
127
232
  /**
128
233
  * Start the check. Resolves with the installed-vs-published status, plus a
129
234
  * `notice` when a NEWER version exists and that version has not been
@@ -141,14 +246,21 @@ export declare function printVersionStatus(status: VersionStatus | null | undefi
141
246
  surround?: boolean;
142
247
  }): void;
143
248
  /**
144
- * Run the check and print the status/notice to stdout. Convenience wrapper
145
- * for call sites with nothing to overlap (e.g. `dexbot status`). Returns the
146
- * status that was printed, or null when the feature is switched off.
249
+ * The entry-point renderer: the status line when there is one, the bare
250
+ * installed-version header when the check is switched off.
251
+ *
252
+ * `printVersionStatus(null)` is a deliberate no-op, which is right for a
253
+ * caller that only wants the line — but every CLI entry point must still name
254
+ * the running build when the notice is disabled
255
+ * (`DEXBOT_SKIP_VERSION_NOTICE=1` / `UPDATER.NOTICE_ENABLED=false`), and
256
+ * re-implementing that fallback per entry point is how they drift: `dexbot
257
+ * stat` had it, `dexbot pm2` did not, so a node with the notice off learned its
258
+ * version from one command and not the other. One helper, one behaviour.
147
259
  */
148
- export declare function maybePrintVersionStatus(options?: VersionNoticeOptions & {
260
+ export declare function printVersionStatusOrHeader(status: VersionStatus | null | undefined, options?: {
149
261
  indent?: string;
150
262
  surround?: boolean;
151
- }): Promise<VersionStatus | null>;
263
+ }): void;
152
264
  /**
153
265
  * Await an already-started check and print its status. The single flush path
154
266
  * for callers (`unlock.ts`, `pm2.ts`) that start the probe early and surface it
@@ -156,10 +268,44 @@ export declare function maybePrintVersionStatus(options?: VersionNoticeOptions &
156
268
  * call site.
157
269
  */
158
270
  export declare function flushVersionStatus(pending: Promise<VersionStatus | null>): Promise<void>;
271
+ /**
272
+ * The flush counterpart of `printVersionStatusOrHeader`, for callers that start
273
+ * the probe early and surface it at a terminal point (`unlock.ts`, `pm2.ts`).
274
+ * A null status is the "check switched off" signal, so the installed version is
275
+ * still named - the same single behaviour the stat path gets.
276
+ */
277
+ export declare function flushVersionStatusOrHeader(pending: Promise<VersionStatus | null>): Promise<void>;
159
278
  /**
160
279
  * Print the status when the probe settles, WITHOUT awaiting it. For launch
161
280
  * paths that must never delay the bot start — the resident process outlives the
162
281
  * probe, so there is no `process.exit()` to truncate it.
282
+ *
283
+ * Uses the header-aware renderer: an entry point must name the running build
284
+ * even when the check is switched off, and this is the non-awaited form of the
285
+ * same contract as `flushVersionStatusOrHeader`.
163
286
  */
164
287
  export declare function printVersionStatusWhenReady(pending: Promise<VersionStatus | null>): void;
288
+ export interface StagedVersionNoticeOptions extends VersionNoticeOptions {
289
+ /** Wait at the top of the command before the caller prints anything else.
290
+ * Default `UPDATER.NOTICE_STAGE_GRACE_MS` (1s). */
291
+ graceMs?: number;
292
+ /** Budget for the final forced re-probe. Default
293
+ * `UPDATER.NOTICE_STATUS_TIMEOUT_MS`. */
294
+ finalMs?: number;
295
+ }
296
+ export interface StagedVersionWait {
297
+ /** The status if it lands within `graceMs`, else null. Await this at the
298
+ * top of a report; the value is only interesting for its TIMING. */
299
+ quick: Promise<VersionStatus | null>;
300
+ /** The status to display at the end. Never "still in flight": it resolves
301
+ * with a definitive answer, or with an exhausted status naming the
302
+ * absence of information. Resolves null only when the feature is off. */
303
+ settled: Promise<VersionStatus | null>;
304
+ }
305
+ /**
306
+ * Start the probe and expose the two moments described above. The first probe
307
+ * is started immediately; `quick` settles within the grace period and `settled`
308
+ * carries the whole escalation.
309
+ */
310
+ export declare function startStagedVersionStatus(options?: StagedVersionNoticeOptions): StagedVersionWait;
165
311
  //# sourceMappingURL=version_notice.d.ts.map