dsh-ssh-hub 0.0.0-stage → 0.2.0

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 (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
@@ -0,0 +1,333 @@
1
+ /**
2
+ * Metric sampling and tiered retention.
3
+ *
4
+ * A fleet operator needs two different things from history, and they pull in
5
+ * opposite directions:
6
+ *
7
+ * - **"What happened at 03:12?"** wants fine resolution, recently.
8
+ * - **"Is this box slowly filling up over months?"** wants a long window,
9
+ * and does not care about per-second detail.
10
+ *
11
+ * Keeping every raw sample forever answers both and costs unbounded disk on
12
+ * the operator's own workstation. Keeping only hourly averages answers the
13
+ * second and makes the first unanswerable. So this keeps three tiers and
14
+ * lets the coarse tiers outlive the fine ones:
15
+ *
16
+ * raw one sample per round, pruned after RAW_WINDOW
17
+ * 1m one sample per minute, pruned after MINUTE_WINDOW
18
+ * 15m one sample per 15 min, pruned after QUARTER_WINDOW
19
+ * 1h one sample per hour, never pruned
20
+ *
21
+ * Each tier is derived from the tier below it by averaging, so a tier never
22
+ * invents a sample that no measurement supports — a bucket with no raw
23
+ * samples produces no aggregated sample at all. That distinction matters:
24
+ * a gap in the graph means "we did not measure", not "the value was zero".
25
+ *
26
+ * Storage is one JSON Lines file per host and tier. JSONL because a partial
27
+ * write loses one line, not the file, and because an operator can read it
28
+ * with `tail` without a tool.
29
+ */
30
+
31
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
32
+ import { join } from 'node:path'
33
+ import { dshHome } from '../dsh-home.ts'
34
+ import type { CheckResult } from '../inspect/checks.ts'
35
+
36
+ /** One metric sample. */
37
+ export interface MetricSample {
38
+ /** Epoch milliseconds. */
39
+ at: number
40
+ /** The metric id (equal to the check id that produced it). */
41
+ metric: string
42
+ /** The value; null when the probe could not read it. */
43
+ value: number | null
44
+ }
45
+
46
+ /** One aggregated bucket. */
47
+ export interface MetricBucket {
48
+ /** Bucket start, epoch milliseconds. */
49
+ at: number
50
+ metric: string
51
+ /** Mean of the raw samples in the bucket; null when every sample was blind. */
52
+ value: number | null
53
+ /** How many raw samples fed this bucket. */
54
+ samples: number
55
+ }
56
+
57
+ /** A retention tier. */
58
+ export interface Tier {
59
+ /** Tier name, also its directory name. */
60
+ name: 'raw' | '1m' | '15m' | '1h'
61
+ /** Bucket width in milliseconds (0 for raw, which keeps the sample's own `at`). */
62
+ widthMs: number
63
+ /** How long a bucket survives, in milliseconds; 0 means forever. */
64
+ keepMs: number
65
+ }
66
+
67
+ /**
68
+ * The tiers, coarse to fine windows.
69
+ *
70
+ * The raw window is deliberately short (24h): raw samples are the bulky tier,
71
+ * and anything older is answerable from the 1m tier for a month.
72
+ */
73
+ export const TIERS: readonly Tier[] = [
74
+ { name: 'raw', widthMs: 0, keepMs: 24 * 60 * 60 * 1000 },
75
+ { name: '1m', widthMs: 60 * 1000, keepMs: 30 * 24 * 60 * 60 * 1000 },
76
+ { name: '15m', widthMs: 15 * 60 * 1000, keepMs: 90 * 24 * 60 * 60 * 1000 },
77
+ { name: '1h', widthMs: 60 * 60 * 1000, keepMs: 0 },
78
+ ]
79
+
80
+ /** The metrics store root. */
81
+ export function metricsRoot(): string {
82
+ return join(dshHome(), 'dsh-ssh-hub', 'metrics')
83
+ }
84
+
85
+ /**
86
+ * Sanitise an alias into a directory-safe file stem.
87
+ *
88
+ * Whitelist rather than blacklist: an alias comes from operator input, and a
89
+ * blacklist that forgets one character (`.` — so `..` survives and the path
90
+ * escapes the store root) is a path-traversal bug. Keeping only
91
+ * `[A-Za-z0-9_-]` cannot encode a separator or a parent reference.
92
+ */
93
+ function aliasStem(alias: string): string {
94
+ const stem = alias.replace(/[^A-Za-z0-9_-]/g, '_')
95
+ // A stem of only dots or empty would still be unsafe; fall back to a fixed
96
+ // name so the store always has a writable directory.
97
+ return /^[._-]*$/.test(stem) || stem === '' ? '_alias' : stem
98
+ }
99
+
100
+ /**
101
+ * The file a (host, tier) pair lives in.
102
+ *
103
+ * @param alias - the host alias.
104
+ * @param tier - the tier name.
105
+ * @param root - store root override (tests).
106
+ * @returns the absolute path.
107
+ */
108
+ export function tierPath(alias: string, tier: Tier['name'], root = metricsRoot()): string {
109
+ return join(root, aliasStem(alias), `${tier}.jsonl`)
110
+ }
111
+
112
+ /** Parse JSON Lines, skipping torn lines. */
113
+ function parseLines(text: string): unknown[] {
114
+ const out: unknown[] = []
115
+ for (const line of text.split('\n')) {
116
+ const trimmed = line.trim()
117
+ if (trimmed === '') continue
118
+ try {
119
+ out.push(JSON.parse(trimmed) as unknown)
120
+ } catch {
121
+ // A torn tail line (a crash mid-write) is expected; skip it rather
122
+ // than losing the whole history.
123
+ }
124
+ }
125
+ return out
126
+ }
127
+
128
+ /**
129
+ * The metric store: append raw samples, derive coarser tiers, prune.
130
+ *
131
+ * One instance per plugin apply. Every method is synchronous: samples are
132
+ * small and arrive once per inspection round, so a write is microseconds,
133
+ * and making it async would only add a window in which an in-flight round's
134
+ * samples could interleave with a prune.
135
+ */
136
+ export class MetricStore {
137
+ private readonly root: string
138
+
139
+ constructor(root?: string) {
140
+ this.root = root ?? metricsRoot()
141
+ }
142
+
143
+ /**
144
+ * Append one round's samples and roll the tiers up.
145
+ *
146
+ * @param alias - the host alias.
147
+ * @param samples - the samples from this round.
148
+ */
149
+ record(alias: string, samples: readonly MetricSample[]): void {
150
+ if (samples.length === 0) return
151
+ this.appendTier(alias, 'raw', samples.map(sample => ({
152
+ at: sample.at,
153
+ metric: sample.metric,
154
+ value: sample.value,
155
+ })))
156
+ this.rollUp(alias)
157
+ }
158
+
159
+ /** Append entries to one tier file. */
160
+ private appendTier(alias: string, tier: Tier['name'], entries: readonly Record<string, unknown>[]): void {
161
+ if (entries.length === 0) return
162
+ const path = tierPath(alias, tier, this.root)
163
+ mkdirSync(join(path, '..'), { recursive: true })
164
+ appendFileSync(path, entries.map(entry => JSON.stringify(entry)).join('\n') + '\n', 'utf8')
165
+ }
166
+
167
+ /**
168
+ * Delete every stored series for one alias.
169
+ *
170
+ * Called when a host is removed from the store: its metric history is keyed
171
+ * only by alias, so leaving it behind means a later host that happens to
172
+ * reuse the name inherits a stranger's numbers. That is worse than losing
173
+ * history, because the numbers look plausible.
174
+ *
175
+ * @param alias - the host alias.
176
+ * @returns true when something was removed.
177
+ */
178
+ forget(alias: string): boolean {
179
+ const dir = join(this.root, aliasStem(alias))
180
+ if (!existsSync(dir)) return false
181
+ // One directory per alias; removing it takes every tier file with it.
182
+ rmSync(dir, { recursive: true, force: true })
183
+ return true
184
+ }
185
+
186
+ /** Read one tier. */
187
+ readTier(alias: string, tier: Tier | Tier['name']): Array<Record<string, unknown>> {
188
+ const name = typeof tier === 'string' ? tier : tier.name
189
+ const path = tierPath(alias, name, this.root)
190
+ if (!existsSync(path)) return []
191
+ return parseLines(readFileSync(path, 'utf8')) as Array<Record<string, unknown>>
192
+ }
193
+
194
+ /**
195
+ * Derive every coarse tier from the tier below and prune expired buckets.
196
+ *
197
+ * Idempotent: a bucket that already exists is replaced, not duplicated, so
198
+ * running this after every round converges instead of accumulating.
199
+ */
200
+ rollUp(alias: string): void {
201
+ for (let index = 1; index < TIERS.length; index += 1) {
202
+ const source = TIERS[index - 1]
203
+ const target = TIERS[index]
204
+ if (source === undefined || target === undefined) continue
205
+ this.aggregate(alias, source, target)
206
+ }
207
+ for (const tier of TIERS) this.prune(alias, tier)
208
+ }
209
+
210
+ /**
211
+ * Aggregate a finer tier into a coarser one.
212
+ *
213
+ * Buckets are aligned to the width, so a bucket always covers the same
214
+ * wall-clock window regardless of when the round happened.
215
+ */
216
+ private aggregate(alias: string, source: Tier, target: Tier): void {
217
+ const rows = this.readTier(alias, source).filter((row): row is { at: number; metric: string; value: number | null } =>
218
+ typeof row['at'] === 'number' && typeof row['metric'] === 'string'
219
+ && (row['value'] === null || typeof row['value'] === 'number'))
220
+ if (rows.length === 0) return
221
+
222
+ // Group by (metric, bucket start).
223
+ const buckets = new Map<string, { at: number; metric: string; sum: number; count: number; samples: number }>()
224
+ for (const row of rows) {
225
+ const at = Math.floor(row.at / target.widthMs) * target.widthMs
226
+ const key = `${row.metric}|${at}`
227
+ let bucket = buckets.get(key)
228
+ if (bucket === undefined) {
229
+ bucket = { at, metric: row.metric, sum: 0, count: 0, samples: 0 }
230
+ buckets.set(key, bucket)
231
+ }
232
+ bucket.samples += 1
233
+ // A blind sample counts as "we measured, but saw nothing" and is
234
+ // excluded from the mean rather than counted as zero.
235
+ if (row.value !== null) {
236
+ bucket.sum += row.value
237
+ bucket.count += 1
238
+ }
239
+ }
240
+
241
+ // Rewrite the whole target tier: bounded by the retention window, and
242
+ // rewriting avoids duplicate rows when a bucket is re-derived.
243
+ const existing = this.readTier(alias, target)
244
+ .filter((row): row is { at: number; metric: string; value: number | null; samples: number } =>
245
+ typeof row['at'] === 'number' && typeof row['metric'] === 'string')
246
+ const merged = new Map<string, MetricBucket>()
247
+ for (const row of existing) {
248
+ merged.set(`${row.metric}|${row.at}`, { at: row.at, metric: row.metric, value: row.value, samples: row.samples })
249
+ }
250
+ for (const [, bucket] of buckets) {
251
+ merged.set(`${bucket.metric}|${bucket.at}`, {
252
+ at: bucket.at,
253
+ metric: bucket.metric,
254
+ value: bucket.count > 0 ? bucket.sum / bucket.count : null,
255
+ samples: bucket.samples,
256
+ })
257
+ }
258
+ const sorted = [...merged.values()].sort((left, right) => left.at - right.at)
259
+ const path = tierPath(alias, target.name, this.root)
260
+ mkdirSync(join(path, '..'), { recursive: true })
261
+ writeFileSync(path, sorted.map(row => JSON.stringify(row)).join('\n') + (sorted.length > 0 ? '\n' : ''), 'utf8')
262
+ }
263
+
264
+ /** Drop buckets older than the tier's retention window. */
265
+ private prune(alias: string, tier: Tier): void {
266
+ if (tier.keepMs === 0) return
267
+ const rows = this.readTier(alias, tier)
268
+ const cutoff = Date.now() - tier.keepMs
269
+ const kept = rows.filter(row => typeof row['at'] === 'number' && row['at'] >= cutoff)
270
+ if (kept.length === rows.length) return
271
+ const path = tierPath(alias, tier.name, this.root)
272
+ writeFileSync(path, kept.map(row => JSON.stringify(row)).join('\n') + (kept.length > 0 ? '\n' : ''), 'utf8')
273
+ }
274
+
275
+ /**
276
+ * Read a series for display.
277
+ *
278
+ * @param alias - the host.
279
+ * @param tier - which tier to read.
280
+ * @param metric - optional metric filter.
281
+ * @param limit - most recent N buckets (default 120).
282
+ * @returns the series, oldest first.
283
+ */
284
+ series(alias: string, tier: Tier['name'], metric?: string, limit = 120): MetricBucket[] {
285
+ const rows = this.readTier(alias, tier)
286
+ const out: MetricBucket[] = []
287
+ for (const row of rows) {
288
+ if (typeof row['at'] !== 'number' || typeof row['metric'] !== 'string') continue
289
+ if (metric !== undefined && row['metric'] !== metric) continue
290
+ const value = row['value']
291
+ if (value !== null && typeof value !== 'number') continue
292
+ out.push({
293
+ at: row['at'],
294
+ metric: row['metric'],
295
+ value,
296
+ samples: typeof row['samples'] === 'number' ? row['samples'] : 1,
297
+ })
298
+ }
299
+ out.sort((left, right) => left.at - right.at)
300
+ return out.length > limit ? out.slice(out.length - limit) : out
301
+ }
302
+ }
303
+
304
+ /**
305
+ * Extract numeric samples from one inspection round for one host.
306
+ *
307
+ * Only checks with a numeric kind become metrics: a boolean check ("sshd is
308
+ * running") has no meaningful average, and a text check has no series at all.
309
+ * The timestamp comes from the round, because a CheckResult carries no time
310
+ * of its own — every result in a round shares the round's start.
311
+ *
312
+ * @param at - the round's start, epoch milliseconds.
313
+ * @param results - the round's results for that host.
314
+ * @param kindOf - resolves a check id to its kind.
315
+ * @returns the numeric samples.
316
+ */
317
+ export function samplesFromRound(
318
+ at: number,
319
+ results: readonly CheckResult[],
320
+ kindOf: (checkId: string) => string | undefined,
321
+ ): MetricSample[] {
322
+ const samples: MetricSample[] = []
323
+ for (const item of results) {
324
+ const kind = kindOf(item.checkId)
325
+ if (kind !== 'percent' && kind !== 'gauge') continue
326
+ samples.push({
327
+ at,
328
+ metric: item.checkId,
329
+ value: typeof item.value === 'number' ? item.value : null,
330
+ })
331
+ }
332
+ return samples
333
+ }
@@ -0,0 +1,142 @@
1
+ // Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
2
+ /**
3
+ * Host single-instance guard shared by the plugin family. The family bundle
4
+ * (dsh-web-all / dsh-skins) namespaces every child row id (web-ui-*), so
5
+ * the loader accepts a standalone install of the same package side by side;
6
+ * without this guard the second instance would still re-register the same
7
+ * webserver routes, tools, settings namespaces, and system-prompt sections
8
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
9
+ * no-op for as long as the first instance lives (the browser half is already
10
+ * deduped by package name in the client module host).
11
+ *
12
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
13
+ * long after the refused mount ran its course: the Host reloads a profile by
14
+ * creating the new loader entries before the old ones are torn down (a
15
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
16
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
17
+ * previous entry still owns the name. Dropping that refused mount lost the
18
+ * plugin for good - the previous entry then disposed its own mount, releasing
19
+ * the name with nobody left to take it, and the family row stayed listed as
20
+ * active while its host routes 404ed (the task-board panel showed
21
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
22
+ * restart recovered it).
23
+ *
24
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
25
+ * the holder releases the name - if the waiting fiber is still alive then. The
26
+ * single-instance guarantee is unchanged: exactly one mount is live per
27
+ * package name, and the replay re-enters the guard so a later mount still
28
+ * dedupes against it.
29
+ *
30
+ * The registry rides a global symbol so two module instances of the same
31
+ * package (npm copy vs repository link) still share one verdict. That symbol
32
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
33
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
34
+ * dsh-community-plugins) are separate repositories carrying their own copy of
35
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
36
+ * must keep the shape every published copy reads (a `Set` of package names
37
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
38
+ * under their own additive key, and the registry reads back a `Set` even when
39
+ * some other build left a different value there. Changing `MOUNTED`'s shape
40
+ * in place broke that contract once: a satellite's legacy copy created a
41
+ * `Set`, the family's new copy read it as a `Map`, and every family row
42
+ * mounted after it failed with "claims.get is not a function".
43
+ *
44
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
45
+ * return value as the fiber disposer, so the unmarker is returned, not run.
46
+ */
47
+
48
+ /** Published cross-repository contract: package names currently mounted. */
49
+ const MOUNTED = Symbol.for('dsh-web.mounted-plugins')
50
+
51
+ /** Additive key this guard owns: refused mounts waiting for the name. */
52
+ const WAITERS = Symbol.for('dsh-web.mounted-plugins.waiters')
53
+
54
+ /** The slice of a cordis context this guard touches. */
55
+ interface MountContext {
56
+ effect?: (effect: () => unknown) => unknown
57
+ }
58
+
59
+ /** One mount that was refused while another fiber owned the package name. */
60
+ interface PendingMount {
61
+ /** Replay the refused mount; a no-op once its own fiber has been disposed. */
62
+ run(): void
63
+ }
64
+
65
+ interface MountRegistry {
66
+ [MOUNTED]?: unknown
67
+ [WAITERS]?: Map<string, PendingMount[]>
68
+ }
69
+
70
+ /**
71
+ * The shared name registry, always a `Set` whatever another build stored here:
72
+ * a foreign value (an interim shape, a hand-written global) must not take every
73
+ * family plugin down with it.
74
+ * @returns the process-wide set of mounted package names.
75
+ */
76
+ function mountedSet(): Set<string> {
77
+ const registry = globalThis as MountRegistry
78
+ const existing = registry[MOUNTED]
79
+ if (existing instanceof Set) return existing as Set<string>
80
+ const created = new Set<string>()
81
+ registry[MOUNTED] = created
82
+ return created
83
+ }
84
+
85
+ /** Queue per package name for mounts refused while a holder was alive. */
86
+ function mountWaiters(): Map<string, PendingMount[]> {
87
+ const registry = globalThis as MountRegistry
88
+ return (registry[WAITERS] ??= new Map())
89
+ }
90
+
91
+ /**
92
+ * Wrap a cordis plugin apply so the package runs at most once per process.
93
+ * The first mount registers normally and releases the name when its fiber
94
+ * disposes; a mount refused while that name is held waits for the release and
95
+ * then runs, unless its own fiber disposes first.
96
+ * @param packageName - npm package identity shared by every install source.
97
+ * @param fn - the original plugin apply.
98
+ * @returns an apply of the same shape.
99
+ */
100
+ export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
101
+ const mount = (...args: unknown[]): unknown => {
102
+ const mounted = mountedSet()
103
+ const ctx = args[0] as MountContext | undefined
104
+ if (mounted.has(packageName)) {
105
+ // Another fiber (the aggregate row, a standalone install, or a copy built
106
+ // from an older revision of this guard) owns the name. Queue instead of
107
+ // dropping: dropping lost the plugin for the rest of the process when the
108
+ // holder was disposed by a reload.
109
+ const waiters = mountWaiters()
110
+ const queue = waiters.get(packageName) ?? []
111
+ let alive = true
112
+ const pending: PendingMount = {
113
+ run: () => {
114
+ if (alive) mount(...args)
115
+ },
116
+ }
117
+ // A fiber that dies while it waits must not be replayed afterwards: its
118
+ // context is disposed and registering effects on it would throw.
119
+ ctx?.effect?.(() => () => {
120
+ alive = false
121
+ const index = queue.indexOf(pending)
122
+ if (index >= 0) queue.splice(index, 1)
123
+ })
124
+ queue.push(pending)
125
+ waiters.set(packageName, queue)
126
+ return
127
+ }
128
+ mounted.add(packageName)
129
+ ctx?.effect?.(() => () => {
130
+ mounted.delete(packageName)
131
+ const waiters = mountWaiters()
132
+ const queue = waiters.get(packageName)
133
+ if (queue === undefined) return
134
+ waiters.delete(packageName)
135
+ // Defer the handover one microtask so the disposing mount's own effects
136
+ // (routes, ledger, timers) are torn down before the next one registers.
137
+ for (const waiter of queue.splice(0)) queueMicrotask(() => { waiter.run() })
138
+ })
139
+ return fn(...args)
140
+ }
141
+ return mount as T
142
+ }