@devries-cameron20 / composio-1 / commits / 304e2fda3
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): add composio version --check for machine-readable update status

The startup upgrade banner is TTY-gated, so scripts and agent-driven (piped) CLI usage never learn a newer stable exists. `composio version --check` prints a JSON status to stdout — {current, latestStable, updateAvailable, lastChecked} — reusing the update notice's self-throttled release cache (fresh <24h: no network; stale: synchronous fetch, 10s timeout, failures degrade to the cached/absent state). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Kshitij Jhunjhunwala committed Jul 24, 2026 at 14:22 UTC 304e2fda3ca1f213d0551e74655406ed2c1765b2
3 files changed +155 -4
ts/packages/cli/src/commands/version.cmd.ts
+28 -3
@@ -1,7 +1,17 @@
1 -import { Command } from '@effect/cli';
1 +import { Command, Options } from '@effect/cli';
2 import { Effect } from 'effect';
3 import { getVersion } from 'src/effects/version';
4 +import { getUpdateStatus } from 'src/services/update-check';
5 import { TerminalUI } from 'src/services/terminal-ui';
6 +import { bold, cyanBright } from 'src/ui/colors';
7 +
8 +const check = Options.boolean('check').pipe(
9 + Options.withDescription(
10 + 'Check for a newer stable release and print a machine-readable JSON status ' +
11 + '({current, latestStable, updateAvailable, lastChecked}). ' +
12 + 'Refreshes the release cache when it is older than 24 hours.'
13 + )
14 +);
15
16 /**
17 * CLI command to display the version of the Composio CLI.
@@ -9,13 +19,28 @@ import { TerminalUI } from 'src/services/terminal-ui';
19 * @example
20 * ```bash
21 * composio version
22 + * composio version --check
23 * ```
24 */
14 -export const versionCmd = Command.make('version', {}).pipe(
25 +export const versionCmd = Command.make('version', { check }).pipe(
26 Command.withDescription('Display the current Composio CLI version.'),
16 - Command.withHandler(() =>
27 + Command.withHandler(({ check }) =>
28 Effect.gen(function* () {
29 const ui = yield* TerminalUI;
30 +
31 + if (check) {
32 + const status = yield* getUpdateStatus;
33 + if (status.updateAvailable && status.latestStable) {
34 + yield* ui.log.info(
35 + `Update available: ${status.current} → ${bold(cyanBright(status.latestStable))} — run ${cyanBright('composio upgrade')}`
36 + );
37 + } else {
38 + yield* ui.log.info(`${status.current} is up to date.`);
39 + }
40 + yield* ui.output(JSON.stringify(status));
41 + return;
42 + }
43 +
44 const version = yield* getVersion;
45 yield* ui.log.info(version);
46 yield* ui.output(version);
ts/packages/cli/src/services/update-check.ts
+52 -1
@@ -33,6 +33,18 @@ export interface UpdateCheckState {
33 latestVersion: string; // e.g. "0.3.0"
34 }
35
36 +/** Machine-readable update status for `composio version --check`. */
37 +export interface UpdateStatus {
38 + /** Installed CLI version (release-tag.txt next to the binary, or APP_VERSION). */
39 + current: string;
40 + /** Latest known stable release with a binary for this platform, if known. */
41 + latestStable: string | null;
42 + /** True when a strictly newer stable release than `current` is available. */
43 + updateAvailable: boolean;
44 + /** When the release list was last fetched (ISO-8601), if ever. */
45 + lastChecked: string | null;
46 +}
47 +
48 const UpdateCheckStateSchema = Schema.parseJson(
49 Schema.Struct({
50 lastChecked: Schema.String,
@@ -232,7 +244,36 @@ export function createUpdateChecker(config: UpdateCheckConfig) {
244 );
245 });
246
235 - return { showUpdateNotice, checkForUpdate };
247 + /**
248 + * Refresh the release cache (self-throttled to the check interval) and
249 + * report a machine-readable status. Unlike the notice, this ignores the
250 + * TTY gate — callers asked for the data explicitly.
251 + */
252 + const getUpdateStatus: Effect.Effect<UpdateStatus, never, FileSystem.FileSystem | Path.Path> =
253 + Effect.gen(function* () {
254 + yield* checkForUpdate;
255 + const state = yield* Effect.option(readState);
256 +
257 + const cachedLatest = Option.getOrUndefined(Option.map(state, s => s.latestVersion));
258 + // The cache falls back to the current version when no release was found,
259 + // so a prerelease can leak into latestVersion — never report that as stable.
260 + const latestStable =
261 + cachedLatest && semver.valid(cachedLatest) && semver.prerelease(cachedLatest) === null
262 + ? cachedLatest
263 + : null;
264 +
265 + return {
266 + current: config.currentVersion,
267 + latestStable,
268 + updateAvailable: latestStable !== null && semver.gt(latestStable, config.currentVersion),
269 + lastChecked: Option.getOrElse(
270 + Option.map(state, s => s.lastChecked),
271 + () => null as string | null
272 + ),
273 + } satisfies UpdateStatus;
274 + }).pipe(Effect.orDie);
275 +
276 + return { showUpdateNotice, checkForUpdate, getUpdateStatus };
277 }
278
279 // ── Public API (production defaults, fire-and-forget) ───────────────────
@@ -247,6 +288,16 @@ export const showUpdateNotice = Effect.gen(function* () {
288 yield* createUpdateChecker(config).showUpdateNotice(terminal);
289 }).pipe(Effect.provide(DefaultConfigLayers));
290
291 +/**
292 + * Refresh the release cache if stale and return a machine-readable status.
293 + * Powers `composio version --check`.
294 + */
295 +export const getUpdateStatus: Effect.Effect<UpdateStatus> = Effect.gen(function* () {
296 + const stateFile = yield* defaultStateFile;
297 + const config = yield* defaultConfig(stateFile);
298 + return yield* createUpdateChecker(config).getUpdateStatus;
299 +}).pipe(Effect.provide(DefaultConfigLayers));
300 +
301 /** Fire-and-forget background fetch to GitHub. */
302 export function checkForUpdateInBackground(): void {
303 // Runs from cli-main before the runtime boots; runPromiseExit never throws back
ts/packages/cli/test/src/services/update-check.test.ts
+75
@@ -244,6 +244,81 @@ describe('showUpdateNotice', () => {
244 );
245 });
246
247 +// ── getUpdateStatus ─────────────────────────────────────────────────────
248 +
249 +describe('getUpdateStatus', () => {
250 + it.effect('reports an available update for a stale stable install', () =>
251 + Effect.gen(function* () {
252 + const config = makeConfig({
253 + currentVersion: '0.2.0',
254 + fetchFn: vi.fn().mockResolvedValue({
255 + ok: true,
256 + json: () => Promise.resolve(makeReleasesPayload(['0.3.0'])),
257 + }) as unknown as typeof fetch,
258 + });
259 + const { getUpdateStatus } = createUpdateChecker(config);
260 +
261 + const status = yield* getUpdateStatus;
262 +
263 + expect(status).toEqual({
264 + current: '0.2.0',
265 + latestStable: '0.3.0',
266 + updateAvailable: true,
267 + lastChecked: expect.any(String),
268 + });
269 + }).pipe(Effect.provide(PlatformLayers))
270 + );
271 +
272 + it.effect('reports no update when the fetch fails and no cache exists', () =>
273 + Effect.gen(function* () {
274 + const config = makeConfig({
275 + currentVersion: '0.2.0',
276 + fetchFn: vi.fn().mockRejectedValue(new Error('offline')) as unknown as typeof fetch,
277 + });
278 + const { getUpdateStatus } = createUpdateChecker(config);
279 +
280 + const status = yield* getUpdateStatus;
281 +
282 + expect(status.updateAvailable).toBe(false);
283 + expect(status.lastChecked).toEqual(expect.any(String));
284 + }).pipe(Effect.provide(PlatformLayers))
285 + );
286 +
287 + it.effect('does not report a cached prerelease as latestStable', () =>
288 + Effect.gen(function* () {
289 + const config = makeConfig({ currentVersion: '0.2.32-beta.289' });
290 + writeState(config, {
291 + lastChecked: new Date().toISOString(),
292 + latestVersion: '0.2.32-beta.289',
293 + });
294 + const { getUpdateStatus } = createUpdateChecker(config);
295 +
296 + const status = yield* getUpdateStatus;
297 +
298 + expect(status.latestStable).toBeNull();
299 + expect(status.updateAvailable).toBe(false);
300 + }).pipe(Effect.provide(PlatformLayers))
301 + );
302 +
303 + it.effect('uses the fresh cache without fetching', () =>
304 + Effect.gen(function* () {
305 + const fetchFn = vi.fn();
306 + const config = makeConfig({
307 + currentVersion: '0.2.0',
308 + fetchFn: fetchFn as unknown as typeof fetch,
309 + });
310 + writeState(config, { lastChecked: new Date().toISOString(), latestVersion: '0.2.1' });
311 + const { getUpdateStatus } = createUpdateChecker(config);
312 +
313 + const status = yield* getUpdateStatus;
314 +
315 + expect(fetchFn).not.toHaveBeenCalled();
316 + expect(status.latestStable).toBe('0.2.1');
317 + expect(status.updateAvailable).toBe(true);
318 + }).pipe(Effect.provide(PlatformLayers))
319 + );
320 +});
321 +
322 // ── checkForUpdate ──────────────────────────────────────────────────────
323
324 describe('checkForUpdate', () => {