8
import { Writable } from 'node:stream';
9
import { HOST_CONFIG } from 'src/config';
10
import { APP_VERSION } from 'src/constants';
11
+import {
12
+ CommandLifecycleTelemetry,
13
+ type PluginHintShown,
14
+} from 'src/services/command-lifecycle-telemetry';
15
import { defaultNodeOs, NodeOs } from 'src/services/node-os';
16
import { NodeProcess } from 'src/services/node-process';
17
import { detectPluginHost } from 'src/services/agent-host-env';
18
import {
19
createPluginHint,
16
- findRootCommandName,
20
PluginHint,
21
resolvePluginHintConfig,
22
type PluginHintConfig,
23
} from 'src/services/plugin-hint';
24
import { makeTerminalUI, TerminalUI } from 'src/services/terminal-ui';
25
+import { commandIdentity } from 'test/__utils__/command-identity';
26
import { terminalUITestImpl } from 'test/__utils__/services/terminal-ui-test';
27
import { trackedEvents } from 'test/__utils__/tracked-events';
28
37
const DAY_MS = 24 * 60 * 60 * 1000;
38
39
let tempDir: string;
40
+/** What the hint reported through `telemetry` in the current test. */
41
+let shownEvents: PluginHintShown[];
42
+const telemetry = {
43
+ pluginHintShown: (shown: PluginHintShown) => Effect.sync(() => shownEvents.push(shown)),
44
+};
45
beforeEach(() => {
46
tempDir = mkdtempSync(join(tmpdir(), 'plugin-hint-test-'));
47
+ shownEvents = [];
48
});
49
afterEach(() => {
50
vi.useRealTimers();
66
stateDirectory: join(tempDir, '.composio', 'plugin-hints'),
67
host: 'claude',
68
invocationOrigin: undefined,
59
- commandName: 'version',
69
+ commandPath: 'version',
70
claudeInstalledPluginsFile: join(tempDir, '.claude', 'plugins', 'installed_plugins.json'),
71
codexConfigFile: join(tempDir, '.codex', 'config.toml'),
72
hintIntervalMs: DAY_MS,
127
vi.stubEnv('CLAUDECODE', '1');
128
129
return Effect.gen(function* () {
120
- const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
130
+ const config = yield* resolvePluginHintConfig('version');
131
132
expect(config.stateDirectory).toBe(join(cacheDir, 'plugin-hints'));
133
expect(config.host).toBe('claude');
124
- expect(config.commandName).toBe('version');
134
+ expect(config.commandPath).toBe('version');
135
}).pipe(
136
Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
137
Effect.provide(hintLayers())
143
vi.stubEnv('CODEX_HOME', ' ');
144
145
return Effect.gen(function* () {
136
- const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
146
+ const config = yield* resolvePluginHintConfig('version');
147
148
expect(config.claudeInstalledPluginsFile).toBe(
149
join(tempDir, '.claude', 'plugins', 'installed_plugins.json')
162
vi.stubEnv('CODEX_HOME', codexHome);
163
164
return Effect.gen(function* () {
155
- const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
165
+ const config = yield* resolvePluginHintConfig('version');
166
167
expect(config.claudeInstalledPluginsFile).toBe(
168
join(claudeConfigDir, 'plugins', 'installed_plugins.json')
179
vi.stubEnv('CODEX_HOME', 'codex-relative');
180
181
return Effect.gen(function* () {
172
- const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
182
+ const config = yield* resolvePluginHintConfig('version');
183
184
expect(config.claudeInstalledPluginsFile).toBe(
185
join(tempDir, 'claude-relative', 'plugins', 'installed_plugins.json')
192
});
193
});
194
185
-describe('findRootCommandName', () => {
186
- it('skips root log-level flags before the subcommand', () => {
187
- expect(findRootCommandName(['/bin/bun', '/cli/bin.ts', 'setup'])).toBe('setup');
188
- expect(findRootCommandName(['/bin/bun', '/cli/bin.ts', '--log-level', 'debug', 'setup'])).toBe(
189
- 'setup'
190
- );
191
- expect(findRootCommandName(['/bin/bun', '/cli/bin.ts', '--log-level=debug', 'setup'])).toBe(
192
- 'setup'
193
- );
194
- });
195
-});
196
-
195
describe('showPluginHint', () => {
196
let output: string[];
197
203
Effect.gen(function* () {
204
const claudeConfig = makeConfig();
205
writeClaudePlugins(claudeConfig, { 'other@marketplace': [{ scope: 'user' }] });
208
- yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
206
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry);
207
208
const codexConfig = makeConfig({ host: 'codex' });
209
writeFileAt(codexConfig.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
212
- yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
210
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry);
211
212
expect(output).toEqual([
213
"Tip: running under Claude Code without the Composio plugin — 'composio setup --yes' installs it.",
220
Effect.gen(function* () {
221
const config = makeConfig();
222
225
- yield* createPluginHint(config).showPluginHint({
226
- error: () => Effect.die(new Error('EPIPE')),
227
- });
223
+ yield* createPluginHint(config).showPluginHint(
224
+ { error: () => Effect.die(new Error('EPIPE')) },
225
+ telemetry
226
+ );
227
expect(existsSync(join(config.stateDirectory, 'claude.stamp'))).toBe(false);
228
230
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
229
+ yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry);
230
expect(output).toHaveLength(1);
231
}).pipe(Effect.provide(hintLayers()))
232
);
233
235
- it.effect('tracks CLI_PLUGIN_HINT_SHOWN once per printed hint', () =>
234
+ it.effect('reports the hint to the telemetry service once per printed hint', () =>
235
Effect.gen(function* () {
237
- const config = makeConfig({ invocationOrigin: 'installer', commandName: 'whoami' });
236
+ const config = makeConfig({ invocationOrigin: 'installer', commandPath: 'whoami' });
237
239
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
240
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
238
+ yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry);
239
+ yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry);
240
241
expect(output).toHaveLength(1);
243
- expect(trackedEvents).toEqual([
244
- {
245
- name: 'CLI_PLUGIN_HINT_SHOWN',
246
- properties: expect.objectContaining({
247
- source: 'cli',
248
- invocation_origin: 'installer',
249
- cli_version: APP_VERSION,
250
- command_path: 'whoami',
251
- agent_host: 'claude',
252
- }),
253
- },
242
+ expect(shownEvents).toEqual([
243
+ { invocationOrigin: 'installer', commandPath: 'whoami', agentHost: 'claude' },
244
]);
245
+ // The hint tracks nothing itself.
246
+ expect(trackedEvents).toEqual([]);
247
}).pipe(Effect.provide(hintLayers()))
248
);
249
251
Effect.gen(function* () {
252
const claudeConfig = makeConfig();
253
writeClaudePlugins(claudeConfig, { 'composio@composio': [{ scope: 'user' }] });
262
- yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
254
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry);
255
256
const codexConfig = makeConfig({ host: 'codex' });
257
writeFileAt(codexConfig.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n');
266
- yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
258
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry);
259
260
expect(output).toEqual([]);
261
expect(existsSync(claudeConfig.stateDirectory)).toBe(false);
267
const config = makeConfig();
268
writeFileAt(config.claudeInstalledPluginsFile, 'not json{');
269
278
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
270
+ yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry);
271
272
expect(output).toEqual([]);
273
}).pipe(Effect.provide(hintLayers()))
274
);
275
284
- it.effect('stays silent outside a host, in run children, and for setup', () =>
276
+ // `composio setup` turns the hint off in its `CommandMeta`; see
277
+ // `test/src/invocation/invocation-hooks.test.ts`.
278
+ it.effect('stays silent outside a host and in run children', () =>
279
Effect.gen(function* () {
286
- const configs = [
287
- makeConfig({ host: undefined }),
288
- makeConfig({ invocationOrigin: 'run' }),
289
- makeConfig({ commandName: 'setup' }),
290
- ];
280
+ const configs = [makeConfig({ host: undefined }), makeConfig({ invocationOrigin: 'run' })];
281
282
yield* Effect.forEach(configs, config =>
293
- createPluginHint(config).showPluginHint(makeTerminal(output))
283
+ createPluginHint(config).showPluginHint(makeTerminal(output), telemetry)
284
);
285
286
expect(output).toEqual([]);
297
- expect(trackedEvents).toEqual([]);
298
- expect(existsSync(configs[2]!.stateDirectory)).toBe(false);
287
+ expect(shownEvents).toEqual([]);
288
+ expect(existsSync(configs[1]!.stateDirectory)).toBe(false);
289
}).pipe(Effect.provide(hintLayers()))
290
);
291
295
296
yield* Effect.all(
297
Array.from({ length: 20 }, () =>
308
- createPluginHint(config).showPluginHint(makeTerminal(output))
298
+ createPluginHint(config).showPluginHint(makeTerminal(output), telemetry)
299
),
300
{ concurrency: 'unbounded' }
301
);
310
const claudeConfig = makeConfig({ host: 'claude' });
311
const codexConfig = makeConfig({ host: 'codex' });
312
323
- yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
324
- yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
325
- yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
326
- yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
313
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry);
314
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry);
315
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry);
316
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry);
317
318
expect(output).toHaveLength(2);
319
}).pipe(Effect.provide(hintLayers()))
329
const stale = new Date('2026-07-27T00:00:00.000Z');
330
utimesSync(stamp, stale, stale);
331
342
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
332
+ yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry);
333
334
expect(output).toHaveLength(1);
335
}).pipe(Effect.provide(hintLayers()))
351
stderr: Object.assign(capture, { isTTY: false }),
352
});
353
364
- yield* createPluginHint(config).showPluginHint(terminal);
354
+ yield* createPluginHint(config).showPluginHint(terminal, telemetry);
355
356
expect(chunks.join('')).toContain('composio setup');
357
}).pipe(Effect.provide(hintLayers()))
359
});
360
361
describe('PluginHint', () => {
372
- /** `PluginHint.Default` with every path under `tempDir` and a recording stderr. */
373
- const pluginHintLayer = (output: string[]) =>
374
- Layer.provide(
362
+ /**
363
+ * `PluginHint.Default` over the real `CommandLifecycleTelemetry` (its dispatcher mocked above),
364
+ * with every path under `tempDir` and a recording stderr.
365
+ */
366
+ const pluginHintLayer = (output: string[]) => {
367
+ const services = Layer.mergeAll(
368
+ BunServices.layer,
369
+ Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })),
370
+ Layer.succeed(TerminalUI, TerminalUI.of({ ...terminalUITestImpl, ...makeTerminal(output) }))
371
+ );
372
+ return Layer.provide(
373
PluginHint.Default,
376
- Layer.mergeAll(
377
- BunServices.layer,
378
- Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })),
379
- Layer.succeed(TerminalUI, TerminalUI.of({ ...terminalUITestImpl, ...makeTerminal(output) }))
380
- )
374
+ Layer.merge(services, Layer.provide(CommandLifecycleTelemetry.Default, services))
375
);
376
+ };
377
378
/** Runs under Claude Code, which has no Composio plugin installed. */
379
const underClaudeCode = Effect.provideService(
382
);
383
384
it.effect(
390
- '[Given] Claude Code without the plugin [Then] prints and tracks the hint once per interval',
385
+ '[Given] Claude Code without the plugin [Then] prints the hint once per interval and tracks it through the telemetry service',
386
() => {
387
const output: string[] = [];
388
+ const identity = commandIdentity(['dev', 'triggers', 'list']);
389
return Effect.gen(function* () {
390
const hint = yield* PluginHint;
395
- yield* hint.run({ argv: ['/bin/bun', '/cli/bin.ts', 'whoami'] });
396
- yield* hint.run({ argv: ['/bin/bun', '/cli/bin.ts', 'whoami'] });
391
+ yield* hint.run({ identity });
392
+ yield* hint.run({ identity });
393
394
expect(output).toEqual([
395
"Tip: running under Claude Code without the Composio plugin — 'composio setup --yes' installs it.",
397
expect(trackedEvents).toEqual([
398
{
399
name: 'CLI_PLUGIN_HINT_SHOWN',
404
- properties: expect.objectContaining({ command_path: 'whoami', agent_host: 'claude' }),
400
+ properties: expect.objectContaining({
401
+ source: 'cli',
402
+ invocation_origin: 'cli',
403
+ cli_version: APP_VERSION,
404
+ command_path: 'dev triggers list',
405
+ agent_host: 'claude',
406
+ }),
407
},
408
]);
409
}).pipe(underClaudeCode, Effect.provide(pluginHintLayer(output)));
410
}
411
);
410
-
411
- it.effect('[Given] `composio setup` [Then] prints and tracks nothing', () => {
412
- const output: string[] = [];
413
- return Effect.gen(function* () {
414
- const hint = yield* PluginHint;
415
- yield* hint.run({ argv: ['/bin/bun', '/cli/bin.ts', 'setup'] });
416
-
417
- expect(output).toEqual([]);
418
- expect(trackedEvents).toEqual([]);
419
- }).pipe(underClaudeCode, Effect.provide(pluginHintLayer(output)));
420
- });
412
});