gentle-shell-bridge 0.0.0-stage → 0.3.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 (112) hide show
  1. package/.codegraph/.gitignore +5 -0
  2. package/PRD.md +144 -0
  3. package/README.md +745 -2
  4. package/docs/architecture.md +981 -0
  5. package/docs/contract.md +1266 -0
  6. package/docs/state.md +251 -0
  7. package/examples/bash-card.ts +1694 -0
  8. package/gentle-shell-bridge-0.3.0.tgz +0 -0
  9. package/odd/tasks/palette-sections.md +30 -0
  10. package/odd/tasks/plugin-keymap.md +32 -0
  11. package/odd/tasks/plugin-surface-contract.md +55 -0
  12. package/package.json +35 -4
  13. package/src/api.ts +492 -0
  14. package/src/arm.ts +83 -0
  15. package/src/bus.ts +558 -0
  16. package/src/capture.ts +886 -0
  17. package/src/card-style-line.ts +112 -0
  18. package/src/card-style-rows.ts +390 -0
  19. package/src/card-style-transform.ts +862 -0
  20. package/src/card-style-wiring.ts +472 -0
  21. package/src/card-styles.ts +159 -0
  22. package/src/config.ts +71 -0
  23. package/src/extension.ts +271 -0
  24. package/src/hook.ts +310 -0
  25. package/src/index.ts +71 -0
  26. package/src/notices.ts +137 -0
  27. package/src/plugin-lines.ts +865 -0
  28. package/src/plugin-surface.ts +218 -0
  29. package/src/presence.ts +259 -0
  30. package/src/repaint.ts +351 -0
  31. package/src/row-labels.ts +146 -0
  32. package/src/row-names.ts +273 -0
  33. package/src/row-origin.ts +144 -0
  34. package/src/rows.ts +248 -0
  35. package/src/section-panel.ts +378 -0
  36. package/src/section-pointer.ts +164 -0
  37. package/src/sections-rows.ts +128 -0
  38. package/src/sidebar-render.ts +535 -0
  39. package/src/sidebar.ts +919 -0
  40. package/src/status.ts +1161 -0
  41. package/src/store.ts +279 -0
  42. package/src/tool-design-adoption.ts +263 -0
  43. package/src/tool-design-rows.ts +246 -0
  44. package/src/tool-design-wiring.ts +428 -0
  45. package/src/tool-designs.ts +402 -0
  46. package/src/transform-pipeline.ts +351 -0
  47. package/src/types.ts +442 -0
  48. package/src/visibility.ts +154 -0
  49. package/test/api.test.ts +395 -0
  50. package/test/apply-on-move.test.ts +477 -0
  51. package/test/arm.test.ts +220 -0
  52. package/test/bridge-ready.test.ts +309 -0
  53. package/test/bus.test.ts +165 -0
  54. package/test/button-rows.test.ts +409 -0
  55. package/test/capture.test.ts +356 -0
  56. package/test/card-style-rows.test.ts +510 -0
  57. package/test/card-style-transform.test.ts +379 -0
  58. package/test/card-style-wiring.test.ts +258 -0
  59. package/test/card-styles-e2e.test.ts +491 -0
  60. package/test/card-styles.test.ts +324 -0
  61. package/test/card-transcript-path.test.ts +178 -0
  62. package/test/config.test.ts +93 -0
  63. package/test/e2e.test.ts +443 -0
  64. package/test/example-bash-identity.test.ts +372 -0
  65. package/test/example-bash-matrix.test.ts +856 -0
  66. package/test/example-designs.test.ts +734 -0
  67. package/test/example-neon-transform.test.ts +283 -0
  68. package/test/example-plain-style.test.ts +1268 -0
  69. package/test/extension.test.ts +160 -0
  70. package/test/fake-events.ts +58 -0
  71. package/test/fake-host.ts +211 -0
  72. package/test/fake-sidebar.ts +516 -0
  73. package/test/fake-transcript.ts +486 -0
  74. package/test/frame-telemetry.test.ts +417 -0
  75. package/test/hook.test.ts +196 -0
  76. package/test/manifest.test.ts +105 -0
  77. package/test/new-category.test.ts +979 -0
  78. package/test/notices.test.ts +328 -0
  79. package/test/plugin-integration-lines.test.ts +979 -0
  80. package/test/plugin-surface.test.ts +152 -0
  81. package/test/presence.test.ts +459 -0
  82. package/test/rail-surfaces.test.ts +457 -0
  83. package/test/rail-width.test.ts +423 -0
  84. package/test/regression.test.ts +483 -0
  85. package/test/repaint-api.test.ts +200 -0
  86. package/test/reserved-categories.test.ts +361 -0
  87. package/test/row-labels.test.ts +284 -0
  88. package/test/row-names.test.ts +473 -0
  89. package/test/row-origin.test.ts +395 -0
  90. package/test/section-interaction.test.ts +364 -0
  91. package/test/section-panel.test.ts +403 -0
  92. package/test/sections-rows.test.ts +291 -0
  93. package/test/sidebar-backend.test.ts +471 -0
  94. package/test/sidebar-e2e.test.ts +331 -0
  95. package/test/sidebar-hover.test.ts +276 -0
  96. package/test/sidebar-independent.test.ts +349 -0
  97. package/test/sidebar-render.test.ts +281 -0
  98. package/test/sidebar-sections.test.ts +245 -0
  99. package/test/status-card-styles.test.ts +201 -0
  100. package/test/status-section-frame.test.ts +181 -0
  101. package/test/status-sections.test.ts +243 -0
  102. package/test/status.test.ts +209 -0
  103. package/test/store.test.ts +192 -0
  104. package/test/surface-repaint-cost.test.ts +520 -0
  105. package/test/tool-design-chain.test.ts +483 -0
  106. package/test/tool-design-cost.test.ts +473 -0
  107. package/test/tool-design-rows.test.ts +359 -0
  108. package/test/tool-designs.test.ts +745 -0
  109. package/test/transform-pipeline.test.ts +465 -0
  110. package/test/transforms-bus.test.ts +233 -0
  111. package/test/verifier-width-regressions.test.ts +164 -0
  112. package/tsconfig.json +18 -0
@@ -0,0 +1,395 @@
1
+ /**
2
+ * The runtime handshake (S1, S5 "zero extra steps"): the published API object, its shape gate and
3
+ * the `bridgeApi()` helper a plugin calls from its own `session_start` handler.
4
+ *
5
+ * A plugin and the bridge are two independent projects. Pi gives them one sanctioned channel that
6
+ * needs no path: `globalThis`. These tests pin that channel only — the symbol, the frozen object,
7
+ * the gate and the absent-means-absent rule — because a path or an environment variable is exactly
8
+ * what the rejected design offered and what this design replaces.
9
+ */
10
+
11
+ import assert from "node:assert/strict";
12
+ import { mkdtempSync, rmSync } from "node:fs";
13
+ import { tmpdir } from "node:os";
14
+ import { join } from "node:path";
15
+ import test from "node:test";
16
+
17
+ import {
18
+ API_SCHEMA,
19
+ API_VERSION,
20
+ BRIDGE_API_KEY,
21
+ VERSION,
22
+ bridgeApi,
23
+ isBridgeApi,
24
+ publishBridgeApi,
25
+ resetBridgeApiForTests,
26
+ } from "../src/api.ts";
27
+ import {
28
+ resetBusForTests,
29
+ resetSectionsForTests,
30
+ snapshotProviders,
31
+ snapshotSections,
32
+ } from "../src/bus.ts";
33
+ import { disableCaptureBackend, getCaptureDiagnostics, resetCaptureStateForTests } from "../src/capture.ts";
34
+ import gentleShellBridge, {
35
+ type BridgeExtensionApi,
36
+ type BridgeSessionHandler,
37
+ } from "../src/extension.ts";
38
+ import { resetHookStateForTests } from "../src/hook.ts";
39
+ import { resetNoticesForTests, snapshotNotices } from "../src/notices.ts";
40
+ import { resetRowBuildStateForTests } from "../src/rows.ts";
41
+ import {
42
+ disableSidebarBackend,
43
+ resetSidebarStateForTests,
44
+ } from "../src/sidebar.ts";
45
+ import { resetSectionFailuresForTests } from "../src/sidebar-render.ts";
46
+ import { resetStoreStateForTests } from "../src/store.ts";
47
+ import type { RowProvider, SidebarSection } from "../src/types.ts";
48
+ import { createFakeHost, type FakeHost, type FakeUiTarget } from "./fake-host.ts";
49
+ import {
50
+ cardBody,
51
+ cardTitles,
52
+ fakeTui,
53
+ registerNativeFooter,
54
+ resetSidebar,
55
+ } from "./fake-sidebar.ts";
56
+
57
+ const hostSlot = (): Record<symbol, unknown> => globalThis as unknown as Record<symbol, unknown>;
58
+
59
+ const provider = (id: string): RowProvider => ({ id, category: "Cards", rows: () => [] });
60
+ const section = (id: string, title = "MUSIC"): SidebarSection => ({
61
+ id,
62
+ title,
63
+ meta: () => "1 playing",
64
+ lines: () => ["track one"],
65
+ });
66
+
67
+ /** Every terminal write the process would show; the bridge must produce none. */
68
+ const captureConsole = (): { writes: string[]; restore: () => void } => {
69
+ const writes: string[] = [];
70
+ const sink = (globalThis as unknown as { console: { log: unknown; warn: unknown; error: unknown } })
71
+ .console;
72
+ const original = { log: sink.log, warn: sink.warn, error: sink.error };
73
+ const record =
74
+ (method: string) =>
75
+ (...args: unknown[]): void => {
76
+ writes.push(`${method}: ${args.map((arg) => String(arg)).join(" ")}`);
77
+ };
78
+ sink.log = record("log");
79
+ sink.warn = record("warn");
80
+ sink.error = record("error");
81
+ return {
82
+ writes,
83
+ restore: () => {
84
+ sink.log = original.log;
85
+ sink.warn = original.warn;
86
+ sink.error = original.error;
87
+ },
88
+ };
89
+ };
90
+
91
+ let configHome: string;
92
+ let previousConfigHome: string | undefined;
93
+
94
+ test.before(() => {
95
+ configHome = mkdtempSync(join(tmpdir(), "gsb-api-"));
96
+ previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
97
+ process.env.GENTLE_PI_CONFIG_HOME = configHome;
98
+ });
99
+
100
+ test.after(() => {
101
+ if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
102
+ else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
103
+ rmSync(configHome, { recursive: true, force: true });
104
+ });
105
+
106
+ test.beforeEach(() => {
107
+ rmSync(join(configHome, "gentle-shell-bridge"), { recursive: true, force: true });
108
+ resetBridgeApiForTests();
109
+ resetNoticesForTests();
110
+ resetBusForTests();
111
+ resetSectionsForTests();
112
+ resetSidebar();
113
+ resetSidebarStateForTests();
114
+ resetSectionFailuresForTests();
115
+ resetStoreStateForTests();
116
+ resetCaptureStateForTests();
117
+ resetHookStateForTests();
118
+ resetRowBuildStateForTests();
119
+ disableCaptureBackend();
120
+ disableSidebarBackend();
121
+ });
122
+
123
+ test.afterEach(() => {
124
+ disableCaptureBackend();
125
+ disableSidebarBackend();
126
+ });
127
+
128
+ // ---------------------------------------------------------------------------------------------
129
+ // The published object
130
+ // ---------------------------------------------------------------------------------------------
131
+
132
+ test("publishing stores one frozen, versioned API object at the stable symbol", () => {
133
+ const api = publishBridgeApi();
134
+
135
+ assert.equal(hostSlot()[BRIDGE_API_KEY], api, "the slot holds exactly the object published");
136
+ assert.ok(Object.isFrozen(api), "the published contract is frozen: nobody may extend it in place");
137
+ assert.deepEqual(Object.keys(api).sort(), [
138
+ "VERSION",
139
+ "createStore",
140
+ "registerCardStyle",
141
+ "registerCommands",
142
+ "registerKeymap",
143
+ "registerRows",
144
+ "registerSection",
145
+ "registerToolDesign",
146
+ "registerTransform",
147
+ "requestRepaint",
148
+ "resolveKeymap",
149
+ "schema",
150
+ "version",
151
+ ]);
152
+ assert.equal(api.schema, "gentle-shell-bridge/api");
153
+ assert.equal(api.version, 1);
154
+ assert.equal(api.VERSION, VERSION);
155
+ assert.equal(api.schema, API_SCHEMA);
156
+ assert.equal(api.version, API_VERSION);
157
+ assert.equal(isBridgeApi(api), true);
158
+ });
159
+
160
+ test("the published functions are the working ones, not a stale copy", () => {
161
+ const api = publishBridgeApi();
162
+
163
+ const disposeRows = api.registerRows(provider("loon.banner-source"));
164
+ const disposeSection = api.registerSection(section("loon.music"));
165
+
166
+ assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["loon.banner-source"]);
167
+ assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
168
+
169
+ disposeSection();
170
+ disposeRows();
171
+ assert.deepEqual(snapshotProviders(), []);
172
+ assert.deepEqual(snapshotSections(), []);
173
+ });
174
+
175
+ test("the shape gate accepts only the v1 surface it advertises", () => {
176
+ const valid = {
177
+ schema: API_SCHEMA,
178
+ version: API_VERSION,
179
+ registerRows: () => () => {},
180
+ registerSection: () => () => {},
181
+ createStore: () => ({}),
182
+ };
183
+
184
+ assert.equal(isBridgeApi(valid), true);
185
+
186
+ // Every mismatch is "absent", so the caller sees `undefined` instead of an error path.
187
+ for (const rejected of [
188
+ undefined,
189
+ null,
190
+ "gentle-shell-bridge",
191
+ 42,
192
+ {},
193
+ { ...valid, schema: "gentle-shell-bridge/api/v2" },
194
+ { ...valid, version: 2 },
195
+ { ...valid, version: "1" },
196
+ { schema: API_SCHEMA, version: API_VERSION },
197
+ { ...valid, registerRows: undefined },
198
+ { ...valid, registerSection: "nope" },
199
+ { ...valid, createStore: {} },
200
+ ]) {
201
+ assert.equal(isBridgeApi(rejected), false, `must reject ${JSON.stringify(rejected)}`);
202
+ }
203
+ });
204
+
205
+ test("a second publish keeps the first object: first wins", () => {
206
+ const first = publishBridgeApi();
207
+ const second = publishBridgeApi();
208
+
209
+ assert.equal(second, first);
210
+ assert.equal(hostSlot()[BRIDGE_API_KEY], first);
211
+ });
212
+
213
+ test("two loaded copies of the module publish one object and both work through it", async () => {
214
+ const first = publishBridgeApi();
215
+
216
+ // Pi loads every extension with `moduleCache: false`, so this package genuinely exists twice in
217
+ // one process. A second copy is a second module instance, not a second global slot.
218
+ const copyPath = new URL("../src/api.ts?second-copy", import.meta.url).href;
219
+ const second = (await import(copyPath)) as typeof import("../src/api.ts");
220
+
221
+ assert.equal(hostSlot()[BRIDGE_API_KEY], first, "the second copy never overwrote the slot");
222
+ const secondApi = second.publishBridgeApi();
223
+ assert.equal(secondApi, first, "and publishing again hands the same object back");
224
+ assert.equal(second.isBridgeApi(hostSlot()[BRIDGE_API_KEY]), true);
225
+
226
+ // Both copies register into the same process-global bus, which is what makes them interchangeable.
227
+ first.registerRows(provider("shared"));
228
+ secondApi.registerRows(provider("shared"));
229
+ assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["shared"]);
230
+ secondApi.registerSection(section("shared.section"));
231
+ assert.deepEqual(snapshotSections().map((registered) => registered.id), ["shared.section"]);
232
+ });
233
+
234
+ // ---------------------------------------------------------------------------------------------
235
+ // bridgeApi(): the object or undefined, never a wait
236
+ // ---------------------------------------------------------------------------------------------
237
+
238
+ test("bridgeApi returns undefined when nothing is published, and the object once it is", () => {
239
+ assert.equal(bridgeApi(), undefined, "no publication is absent, full stop");
240
+
241
+ const api = publishBridgeApi();
242
+ assert.equal(bridgeApi(), api, "and the published object is handed back immediately");
243
+ });
244
+
245
+ test("an object that fails the gate is absent: bridgeApi returns undefined, one notice, no throw", () => {
246
+ for (const incompatible of [
247
+ { ...usableSurface(), schema: "someone-else/api" },
248
+ { ...usableSurface(), version: 2 },
249
+ { schema: API_SCHEMA, version: API_VERSION },
250
+ ]) {
251
+ resetBridgeApiForTests();
252
+ resetNoticesForTests();
253
+ hostSlot()[BRIDGE_API_KEY] = incompatible;
254
+ const captured = captureConsole();
255
+ let seen: unknown;
256
+ try {
257
+ assert.doesNotThrow(() => {
258
+ seen = bridgeApi();
259
+ });
260
+ } finally {
261
+ captured.restore();
262
+ }
263
+
264
+ assert.equal(seen, undefined, "a mismatched object is never handed to a plugin");
265
+ assert.equal(hostSlot()[BRIDGE_API_KEY], incompatible, "the slot is left exactly as it was");
266
+ assert.deepEqual(captured.writes, [], "the skew is never written to the terminal");
267
+ const notices = snapshotNotices().entries;
268
+ assert.equal(notices.length, 1, "and it is recorded once, not per call");
269
+ assert.match(notices[0].message, /incompatible|unsupported|version|not the/u);
270
+ assert.match(notices[0].message, /absent|ABSENT/u);
271
+ assert.match(notices[0].message, /left/u);
272
+ assert.doesNotMatch(notices[0].message, /queue/u, "the notice never mentions a removed queue");
273
+ }
274
+ });
275
+
276
+ const usableSurface = (): Record<string, unknown> => ({
277
+ schema: API_SCHEMA,
278
+ version: API_VERSION,
279
+ registerRows: () => () => {},
280
+ registerSection: () => () => {},
281
+ createStore: () => ({ get: () => undefined, set: () => {} }),
282
+ });
283
+
284
+ test("an incompatible slot is never reset, and publishing still yields a working API", () => {
285
+ const incompatible = { ...usableSurface(), version: 2 };
286
+ hostSlot()[BRIDGE_API_KEY] = incompatible;
287
+ const captured = captureConsole();
288
+ let published: ReturnType<typeof publishBridgeApi> | undefined;
289
+ try {
290
+ published = publishBridgeApi();
291
+ } finally {
292
+ captured.restore();
293
+ }
294
+
295
+ assert.deepEqual(captured.writes, []);
296
+ assert.equal(hostSlot()[BRIDGE_API_KEY], incompatible, "the slot is left exactly as it was");
297
+ assert.equal(isBridgeApi(hostSlot()[BRIDGE_API_KEY]), false);
298
+ assert.equal(bridgeApi(), undefined, "and consumers still see it as absent");
299
+ assert.ok(published !== undefined, "this copy still has an object to register through");
300
+ assert.equal(isBridgeApi(published), true);
301
+ published.registerSection(section("loon.music"));
302
+ assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
303
+ });
304
+
305
+ // ---------------------------------------------------------------------------------------------
306
+ // Through the entry: a plugin registers from its own session_start handler
307
+ // ---------------------------------------------------------------------------------------------
308
+
309
+ type UiWithWidget = FakeUiTarget & {
310
+ setWidget?: (key: string, factory: (tui: unknown, theme: unknown) => unknown) => void;
311
+ };
312
+
313
+ const installWidgetSurface = (host: FakeHost): void => {
314
+ const ui = host.ui as UiWithWidget;
315
+ ui.setWidget = (_key, factory) => {
316
+ factory(fakeTui(), { name: "fake-theme" });
317
+ };
318
+ };
319
+
320
+ const armThroughEntry = (host: FakeHost): void => {
321
+ const handlers: BridgeSessionHandler[] = [];
322
+ const pi: BridgeExtensionApi = {
323
+ // `gentle-pi` is present, so `session_start` arms (S9/T12).
324
+ getCommands: () => [{ name: "gentle:customize" }],
325
+ on(event, handler) {
326
+ if (event === "session_start") handlers.push(handler);
327
+ },
328
+ registerCommand() {},
329
+ };
330
+ gentleShellBridge(pi);
331
+ assert.equal(handlers.length, 1);
332
+ handlers[0]({}, { hasUI: true, ui: host.ui });
333
+ };
334
+
335
+ test("a plugin that registers from session_start renders its section and its Sections toggle", () => {
336
+ const host = createFakeHost();
337
+ installWidgetSurface(host);
338
+ registerNativeFooter(); // the host's own rail
339
+
340
+ publishBridgeApi(); // the bridge loaded, as it always does before any session_start
341
+
342
+ const api = bridgeApi();
343
+ assert.ok(api !== undefined, "the API is present in the handler: no waiting, no queue");
344
+ api.registerRows({
345
+ id: "loon.banner-source",
346
+ category: "Cards",
347
+ rows: () => [
348
+ {
349
+ category: "Cards",
350
+ label: "Loon banner source",
351
+ choice: { setting: "Loon banner source", value: "on", current: () => true },
352
+ action: () => {},
353
+ },
354
+ ],
355
+ });
356
+ api.registerSection(section("loon.music"));
357
+ assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["loon.banner-source"]);
358
+ assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
359
+
360
+ armThroughEntry(host); // session_start
361
+ host.buildMenu();
362
+
363
+ assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"], "the registered section reached the rail");
364
+ assert.deepEqual(cardBody("MUSIC"), ["track one"]);
365
+ const toggle = host.toggleLines().find((line) => line.startsWith("music "));
366
+ assert.ok(toggle !== undefined, "and its toggle reached Sections");
367
+ assert.ok(toggle.includes("● shown") && toggle.includes("○ hidden"));
368
+ assert.ok(
369
+ host.toggleLines().some((line) => line.startsWith("Loon banner source")),
370
+ "the provider's rows reached the menu too",
371
+ );
372
+ });
373
+
374
+ test("PRESERVE: a session_start without a UI still arms nothing", () => {
375
+ const handlers: BridgeSessionHandler[] = [];
376
+ const pi: BridgeExtensionApi = {
377
+ getCommands: () => [{ name: "gentle:customize" }],
378
+ on(_event, handler) {
379
+ handlers.push(handler);
380
+ },
381
+ registerCommand() {},
382
+ };
383
+ gentleShellBridge(pi);
384
+ publishBridgeApi();
385
+ bridgeApi()?.registerRows(provider("queued.rows"));
386
+
387
+ handlers[0]({}, { hasUI: false });
388
+
389
+ assert.equal(getCaptureDiagnostics().armedTargets, 0, "no UI still means no arming");
390
+ assert.deepEqual(
391
+ snapshotProviders().map((registered) => registered.id),
392
+ ["queued.rows"],
393
+ "registration from a plugin handler is independent of the bridge arming",
394
+ );
395
+ });