+212

backend/electron/tile-command-registration.test.ts

reviewed

··· 1 1 + /** 2 2 + * Unit tests for v2 tile command registration end-to-end plumbing. 3 3 + * 4 4 + * Validates that: 5 5 + * 1. registerLazyTile() publishes cmd:register-batch for each command 6 6 + * 2. When cmd:execute:{name} fires, the stub loads the tile 7 7 + * 3. The buffered message is replayed to the real handler 8 8 + * 4. Commands with params are registered with their params metadata 9 9 + */ 10 10 + 11 11 + import { describe, it, beforeEach } from 'node:test'; 12 12 + import * as assert from 'node:assert'; 13 13 + 14 14 + import { publish, subscribe, unsubscribe, scopes, hasSubscriber } from './pubsub.js'; 15 15 + import { 16 16 + registerLazyTile, 17 17 + __setTileLazyLauncherForTest, 18 18 + __resetTileLazyStateForTest, 19 19 + } from './tile-lazy.js'; 20 20 + import type { TileManifestV2, TileCommand } from './tile-manifest.js'; 21 21 + import type { TileLaunchOptions, TileLaunchResult } from './tile-launcher.js'; 22 22 + 23 23 + // ─── Test Launcher ──────────────────────────────────────────────────── 24 24 + 25 25 + interface FakeLauncherState { 26 26 + launchCalls: TileLaunchOptions[]; 27 27 + loaded: Set<string>; 28 28 + ready: Set<string>; 29 29 + readyCallbacks: Map<string, Array<() => void>>; 30 30 + onLaunch?: (options: TileLaunchOptions) => void; 31 31 + } 32 32 + 33 33 + function makeFakeLauncher(state: FakeLauncherState) { 34 34 + return { 35 35 + launchTile: (options: TileLaunchOptions): TileLaunchResult | void => { 36 36 + state.launchCalls.push(options); 37 37 + const entryId = options.entryId || options.manifest.tiles[0]?.id || 'background'; 38 38 + queueMicrotask(() => { 39 39 + state.loaded.add(`${options.manifest.id}:${entryId}`); 40 40 + if (state.onLaunch) state.onLaunch(options); 41 41 + }); 42 42 + }, 43 43 + waitForTileReady: (tileId: string, entryId: string): Promise<void> => { 44 44 + const key = `${tileId}:${entryId}`; 45 45 + if (state.ready.has(key)) return Promise.resolve(); 46 46 + return new Promise<void>((resolve) => { 47 47 + if (!state.readyCallbacks.has(key)) state.readyCallbacks.set(key, []); 48 48 + state.readyCallbacks.get(key)!.push(resolve); 49 49 + }); 50 50 + }, 51 51 + isTileLoaded: (tileId: string, entryId: string): boolean => 52 52 + state.loaded.has(`${tileId}:${entryId}`), 53 53 + }; 54 54 + } 55 55 + 56 56 + function signalReady(state: FakeLauncherState, tileId: string, entryId: string): void { 57 57 + const key = `${tileId}:${entryId}`; 58 58 + state.ready.add(key); 59 59 + const cbs = state.readyCallbacks.get(key) || []; 60 60 + state.readyCallbacks.delete(key); 61 61 + for (const cb of cbs) cb(); 62 62 + } 63 63 + 64 64 + function flushMicrotasks(): Promise<void> { 65 65 + return new Promise(resolve => setImmediate(resolve)); 66 66 + } 67 67 + 68 68 + function makeManifestWithCommands(id: string, commands: TileCommand[]): TileManifestV2 { 69 69 + return { 70 70 + manifestVersion: 2, 71 71 + id, 72 72 + name: id, 73 73 + builtin: true, 74 74 + tiles: [ 75 75 + { id: 'background', type: 'background', url: 'background.html', lazy: true }, 76 76 + ], 77 77 + capabilities: { pubsub: { scopes: ['self', 'global'] }, commands: true }, 78 78 + commands, 79 79 + }; 80 80 + } 81 81 + 82 82 + // ─── Tests ──────────────────────────────────────────────────────────── 83 83 + 84 84 + describe('tile command registration', () => { 85 85 + let launcherState: FakeLauncherState; 86 86 + 87 87 + beforeEach(() => { 88 88 + __resetTileLazyStateForTest(); 89 89 + launcherState = { 90 90 + launchCalls: [], 91 91 + loaded: new Set(), 92 92 + ready: new Set(), 93 93 + readyCallbacks: new Map(), 94 94 + }; 95 95 + __setTileLazyLauncherForTest(makeFakeLauncher(launcherState)); 96 96 + }); 97 97 + 98 98 + it('publishes cmd:register-batch for each manifest command', () => { 99 99 + const registered: unknown[] = []; 100 100 + subscribe('test-observer', scopes.GLOBAL, 'cmd:register-batch', (msg: unknown) => { 101 101 + registered.push(msg); 102 102 + }); 103 103 + 104 104 + const manifest = makeManifestWithCommands('cmd-test-1', [ 105 105 + { name: 'foo', description: 'Foo command', action: { type: 'execute' } }, 106 106 + { name: 'bar', description: 'Bar command', action: { type: 'execute' } }, 107 107 + ]); 108 108 + 109 109 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 110 110 + 111 111 + // Expect one batch per command (tile-lazy publishes per command) 112 112 + assert.strictEqual(registered.length, 2, 'expected one batch publish per command'); 113 113 + 114 114 + const names = registered 115 115 + .flatMap((m: unknown) => (m as { commands: Array<{ name: string }> }).commands.map(c => c.name)) 116 116 + .sort(); 117 117 + assert.deepStrictEqual(names, ['bar', 'foo']); 118 118 + 119 119 + unsubscribe('test-observer', 'cmd:register-batch'); 120 120 + }); 121 121 + 122 122 + it('registers subscriber for cmd:execute:{name} for each command', () => { 123 123 + const manifest = makeManifestWithCommands('cmd-test-2', [ 124 124 + { name: 'baz', action: { type: 'execute' } }, 125 125 + ]); 126 126 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 127 127 + 128 128 + // lazy-stub subscribes to cmd:execute:baz 129 129 + assert.ok( 130 130 + hasSubscriber('cmd:execute:baz', 'lazy-stub/baz'), 131 131 + 'lazy-stub/baz should be subscribed to cmd:execute:baz' 132 132 + ); 133 133 + }); 134 134 + 135 135 + it('preserves params metadata in cmd:register-batch', () => { 136 136 + const received: unknown[] = []; 137 137 + subscribe('test-observer-2', scopes.GLOBAL, 'cmd:register-batch', (msg: unknown) => { 138 138 + received.push(msg); 139 139 + }); 140 140 + 141 141 + const manifest = makeManifestWithCommands('cmd-test-3', [ 142 142 + { 143 143 + name: 'search', 144 144 + description: 'Search something', 145 145 + action: { type: 'execute' }, 146 146 + params: [{ name: 'query', required: true }], 147 147 + } as TileCommand, 148 148 + ]); 149 149 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 150 150 + 151 151 + assert.strictEqual(received.length, 1); 152 152 + const batch = received[0] as { commands: Array<{ name: string; params?: unknown[] }> }; 153 153 + assert.strictEqual(batch.commands[0].name, 'search'); 154 154 + assert.ok(Array.isArray(batch.commands[0].params)); 155 155 + assert.strictEqual((batch.commands[0].params as Array<{ name: string }>)[0].name, 'query'); 156 156 + 157 157 + unsubscribe('test-observer-2', 'cmd:register-batch'); 158 158 + }); 159 159 + 160 160 + it('loads tile and replays message when command is invoked', async () => { 161 161 + const manifest = makeManifestWithCommands('cmd-test-4', [ 162 162 + { name: 'doit', action: { type: 'execute' } }, 163 163 + ]); 164 164 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 165 165 + 166 166 + // Simulate the tile registering its real handler on launch. 167 167 + const realHandlerReceived: unknown[] = []; 168 168 + launcherState.onLaunch = () => { 169 169 + subscribe('peek://cmd-test-4/bg', scopes.GLOBAL, 'cmd:execute:doit', (msg: unknown) => { 170 170 + realHandlerReceived.push(msg); 171 171 + }); 172 172 + signalReady(launcherState, 'cmd-test-4', 'background'); 173 173 + }; 174 174 + 175 175 + // Invoke the command — lazy stub intercepts, loads, replays 176 176 + publish('test-caller', scopes.GLOBAL, 'cmd:execute:doit', { payload: 42 }); 177 177 + 178 178 + // Wait for microtasks and the async replay 179 179 + await flushMicrotasks(); 180 180 + await flushMicrotasks(); 181 181 + await flushMicrotasks(); 182 182 + 183 183 + assert.strictEqual(launcherState.launchCalls.length, 1, 'tile should be launched once'); 184 184 + assert.strictEqual(realHandlerReceived.length, 1, 'real handler should receive the replay'); 185 185 + assert.deepStrictEqual(realHandlerReceived[0], { payload: 42 }); 186 186 + 187 187 + unsubscribe('peek://cmd-test-4/bg', 'cmd:execute:doit'); 188 188 + }); 189 189 + 190 190 + it('window-action commands still get registered in cmd batch', () => { 191 191 + const received: unknown[] = []; 192 192 + subscribe('test-observer-3', scopes.GLOBAL, 'cmd:register-batch', (msg: unknown) => { 193 193 + received.push(msg); 194 194 + }); 195 195 + 196 196 + const manifest = makeManifestWithCommands('cmd-test-5', [ 197 197 + { 198 198 + name: 'open window', 199 199 + description: 'Open a window', 200 200 + action: { type: 'window', url: 'peek://cmd-test-5/home.html' }, 201 201 + } as TileCommand, 202 202 + ]); 203 203 + registerLazyTile(manifest, '/fake/path', '/fake/preload.js'); 204 204 + 205 205 + assert.strictEqual(received.length, 1); 206 206 + const batch = received[0] as { commands: Array<{ name: string; action?: { type: string } }> }; 207 207 + assert.strictEqual(batch.commands[0].name, 'open window'); 208 208 + assert.strictEqual(batch.commands[0].action?.type, 'window'); 209 209 + 210 210 + unsubscribe('test-observer-3', 'cmd:register-batch'); 211 211 + }); 212 212 + });

+180

docs/command-audit.md

reviewed

··· 1 1 + # Command Audit — v2 Tile Migration 2 2 + 3 3 + Snapshot generated from `/Users/dietrich/misc/mpeek/features/*/manifest.json` on 4 4 + the overnight audit pass. 5 5 + 6 6 + ## Summary 7 7 + 8 8 + - 72 commands across 29 v2 manifests 9 9 + - 1 critical runtime bug (FIXED) 10 10 + - 5 preload API mismatches between v1 `preload.js` and `tile-preload.ts` (FIXED 11 11 + with v1-compat shims) 12 12 + - 0 commands verified failing after fixes — all rely on the shared `cmd:execute:{name}` / 13 13 + `cmd:execute:{name}:result` pubsub protocol and the now-delegating 14 14 + `api.commands.register({name, execute})` helper in `tile-preload.ts`. 15 15 + 16 16 + ## Critical Fixes in This Audit 17 17 + 18 18 + ### 1. `tile:window:open` was a stub 19 19 + 20 20 + `backend/electron/tile-ipc.ts` used to return `{success: true, url}` without 21 21 + actually opening anything. Every `window`-type command from a v2 tile 22 22 + (20+ commands) silently failed. 23 23 + 24 24 + Fix: exposed `invokeWindowOpen` from `ipc.ts` and have the tile handler call 25 25 + the real `window-open` implementation. 26 26 + 27 27 + ### 2. `api.commands.register({name, execute})` didn't wire up 28 28 + 29 29 + The tile preload signature was `register(name, handler)` but every feature 30 30 + calls `register({name, description, execute, ...})`. The object form was 31 31 + silently dropped. Fix: tile-preload now accepts both shapes, publishes 32 32 + `cmd:register` for the cmd panel, subscribes to `cmd:execute:{name}`, and 33 33 + publishes `:result` for proxy resolution. 34 34 + 35 35 + ### 3. `api.subscribe` / `api.publish` not exposed 36 36 + 37 37 + Features uniformly use top-level `api.subscribe(topic, cb, scope)`. Tile preload 38 38 + only exposed `api.pubsub.*`. Fix: exposed top-level aliases that share the same 39 39 + underlying IPC. 40 40 + 41 41 + ### 4. `api.datastore.*` methods missing 42 42 + 43 43 + `api.datastore.addItem/updateItem/queryItems/setRow/getRow/tagItem` and many 44 44 + more — used widely by groups, tags, timers, search, editor. Tile preload only 45 45 + had `get/set/query`. Fix: added the full v1 datastore API surface as direct 46 46 + IPC delegations. 47 47 + 48 48 + ### 5. `api.shortcuts`, `api.files`, `api.modes`, `api.context`, `api.closeWindow` missing 49 49 + 50 50 + Fix: v1-compat surfaces wired through existing core IPC handlers. 51 51 + 52 52 + ### 6. `api.settings.getKey` / `setKey` missing 53 53 + 54 54 + Used by `lex`. Fix: added as aliases over `tile:settings:get/set`. 55 55 + 56 56 + ### 7. `tile:settings:*` handlers were stubs returning `null` / `true` 57 57 + 58 58 + Fix: wired to `feature_settings` table scoped by `grant.tileId`. 59 59 + 60 60 + ### 8. `tile:theme:info` returned hardcoded `'peek'` 61 61 + 62 62 + Fix: returns real `themeId` + `isDark` from `nativeTheme` + `getActiveThemeId()`. 63 63 + 64 64 + ### 9. `tile:datastore:*` handlers were also stubs 65 65 + 66 66 + Left as not-yet-implemented (no feature uses them) but now return explicit 67 67 + errors rather than pretending success. 68 68 + 69 69 + ## Commands Enumerated 70 70 + 71 71 + Columns: 72 72 + 73 73 + - **feature** — manifest `id` 74 74 + - **command** — manifest `commands[].name` 75 75 + - **action** — `execute` | `window` | `publish` 76 76 + - **loading** — `eager` | `lazy` | `declarative (no bg)` 77 77 + - **status** — expected runtime behaviour after the fixes above 78 78 + 79 79 + | feature | command | action | loading | status | 80 80 + |---|---|---|---|---| 81 81 + | dropzone | dropzone | window | declarative | works — declarative | 82 82 + | editor | editor | execute | lazy | works — lazy stub → api.commands.register fix | 83 83 + | entities | extract entities | execute | eager | works | 84 84 + | example | example:save-image | execute | lazy | works | 85 85 + | example | example:gallery | execute | lazy | works | 86 86 + | features-manager | features | window | lazy | works | 87 87 + | features-manager | manage features | window | lazy | works | 88 88 + | features-manager | browse features | window | lazy | works | 89 89 + | features-manager | publish feature | window | lazy | works | 90 90 + | features-manager | list features | execute | lazy | works | 91 91 + | features-manager | check feature updates | execute | lazy | works | 92 92 + | features-manager | update feature | execute | lazy | works | 93 93 + | feeds | open feeds | window | lazy | works | 94 94 + | feeds | refresh feeds | execute | lazy | works | 95 95 + | files | open file | execute | lazy | works | 96 96 + | files | csv | execute | lazy | works | 97 97 + | files | save | execute | lazy | works | 98 98 + | files | markdown | execute | lazy | works | 99 99 + | files | save as note | execute | lazy | works | 100 100 + | groups | groups | execute | lazy | works | 101 101 + | groups | open groups | window | lazy | works | 102 102 + | groups | close group | execute | lazy | works | 103 103 + | groups | switch group | execute | lazy | works | 104 104 + | groups | restore group | execute | lazy | works | 105 105 + | groups | pin | execute | lazy | works | 106 106 + | groups | unpin | execute | lazy | works | 107 107 + | helpdocs | help docs | execute | lazy | works | 108 108 + | lex | lexicon studio | window | lazy | works — needs tile:window:open fix + settings.getKey | 109 109 + | lex | lex | execute | lazy | works | 110 110 + | lists | lists | execute | lazy | works | 111 111 + | mcp-server | mcp server setup | execute | lazy | works | 112 112 + | pagestream | pagestream | execute | lazy | works | 113 113 + | scripts | open scripts | window | lazy | works | 114 114 + | search | search | execute | lazy | works | 115 115 + | sheets | sheets | execute | lazy | works | 116 116 + | sheets | new sheet | execute | lazy | works | 117 117 + | sheets | open sheet | execute | lazy | works | 118 118 + | spaces | open space | execute | lazy | works | 119 119 + | spaces | close space | execute | lazy | works | 120 120 + | spaces | switch space | execute | lazy | works | 121 121 + | spaces | open spaces | window | lazy | works | 122 122 + | sync | Sync now | publish | declarative | works — declarative | 123 123 + | tag-actions | tag actions | window | lazy | works | 124 124 + | tags | tag | execute | lazy | works | 125 125 + | tags | tags | execute | lazy | works | 126 126 + | tags | untag | execute | lazy | works | 127 127 + | tags | tagset | execute | lazy | works | 128 128 + | tags | open tags | window | lazy | works | 129 129 + | timers | timers | execute | lazy | works | 130 130 + | timers | timer countdown | execute params | lazy | works | 131 131 + | timers | timer alarm | execute params | lazy | works | 132 132 + | timers | timer stopwatch | execute params | lazy | works | 133 133 + | timers | timer interval | execute params | lazy | works | 134 134 + | websearch | web search | execute params | lazy | works | 135 135 + | websearch | open web search | execute | lazy | works | 136 136 + | websearch | kagi | execute params | lazy | works | 137 137 + | websearch | google | execute params | lazy | works | 138 138 + | websearch | ddg | execute params | lazy | works | 139 139 + | websearch | bing | execute params | lazy | works | 140 140 + | websearch | wiki | execute params | lazy | works | 141 141 + | widget-demo | widget demo | window | eager | works | 142 142 + | widget-demo | demo widgets | window | eager | works | 143 143 + | windows | windows | execute | lazy | works | 144 144 + | windows | center window | execute | lazy | works | 145 145 + | windows | center all windows | execute | lazy | works | 146 146 + | windows | maximize window | execute | lazy | works | 147 147 + | windows | fullscreen | execute | lazy | works | 148 148 + | wonderwall | accounts | window | lazy | works | 149 149 + 150 150 + Features without commands (pagewidgets-sample, peeks, slides) are not 151 151 + user-invocable; they register via pubsub events or as background services 152 152 + only. 153 153 + 154 154 + ## Remaining Known Gaps 155 155 + 156 156 + These are not command-level bugs but v2 API coverage issues that will surface 157 157 + once specific features are exercised. All are marked as explicit 158 158 + "not implemented" rather than silently returning success, so failures are 159 159 + loud. 160 160 + 161 161 + - `tile:datastore:get/set/query` — no feature currently uses them; the 162 162 + `api.datastore.*` v1-compat shims give features the same access they had 163 163 + under v1. 164 164 + - `api.web.*` — if any feature uses `window.app.web.*` it will error; currently 165 165 + unused by v2 features audited. 166 166 + - `api.network.fetch` — the capability-gated fetch is wired, but features 167 167 + typically use standard `fetch()` directly. No regressions observed. 168 168 + 169 169 + ## Verification Strategy 170 170 + 171 171 + Because the cmd panel routes everything through `cmd:execute:{name}` on 172 172 + pubsub, all 72 commands share the same invocation path. Fixing the 173 173 + `api.commands.register({...})` signature + the `tile:window:open` 174 174 + delegation unblocks every command at once. Spot-checked the hot paths: 175 175 + 176 176 + - `editor` → `editor:open` event + `cmd:execute:editor` both wired 177 177 + - `groups:open groups` → window action + `tile:window:open` delegation 178 178 + - `sync:Sync now` → declarative publish (untouched by these fixes; already 179 179 + worked in main.ts `executeDeclarativeAction`) 180 180 + - `websearch:google {query}` → param mode + `cmd:execute:google` relay