fix: default apps listing to user-installed (#541)

Author: thymikee

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.15.0
 
+- Breaking: `apps` discovery and public app-list helpers now default to user-installed apps. Use `--all` or `filter: 'all'` to include system/OEM apps.
 - Breaking: removed the `agent-device/android-apps` public subpath. Use the Android app helpers from `agent-device/android-adb`.
 - Breaking: removed the `agent-device/daemon` public subpath. Use `agent-device/contracts` for daemon request/response types.
 - Breaking: removed public local ADB bypass/selection helpers such as `spawnAndroidAdbBySerial` and `resolveAndroidAdbProvider`; use `createLocalAndroidAdbProvider(device)` or pass providers directly to the helpers from `agent-device/android-adb`.

README.md

@@ -114,6 +114,7 @@ Try the loop.
 ```bash
 # Find the app.
 agent-device apps --platform ios
+agent-device apps --platform android
 
 # Start a session.
 agent-device open SampleApp --platform ios

src/__tests__/cli-client-commands.test.ts

@@ -508,6 +508,39 @@ test('open forwards macOS surface to the client apps API', async () => {
   assert.equal(observed?.surface, 'menubar');
 });
 
+test('apps command defaults to user-installed and prints discovery hint', async () => {
+  let observedAppsFilter: string | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    listApps: async (options) => {
+      observedAppsFilter = options?.appsFilter;
+      return ['Demo (com.example.demo)'];
+    },
+  });
+
+  const output = await captureOutput(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'apps',
+      positionals: [],
+      flags: {
+        json: false,
+        help: false,
+        version: false,
+        platform: 'android',
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+
+  assert.equal(observedAppsFilter, 'user-installed');
+  assert.equal(output.stdout, 'Demo (com.example.demo)\n');
+  assert.match(output.stderr, /user-installed apps/i);
+  assert.match(output.stderr, /--all/);
+});
+
 test('screenshot reports annotated ref count in non-json mode', async () => {
   const client = createStubClient({
     installFromSource: async () => {
@@ -834,8 +867,35 @@ async function captureStdout(run: () => Promise<void>): Promise<string> {
   return stdout;
 }
 
+async function captureOutput(
+  run: () => Promise<void>,
+): Promise<{ stdout: string; stderr: string }> {
+  let stdout = '';
+  let stderr = '';
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  try {
+    await run();
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { stdout, stderr };
+}
+
 function createStubClient(params: {
   installFromSource: AgentDeviceClient['apps']['installFromSource'];
+  listApps?: AgentDeviceClient['apps']['list'];
   prepareMetro?: AgentDeviceClient['metro']['prepare'];
   reloadMetro?: AgentDeviceClient['metro']['reload'];
   open?: AgentDeviceClient['apps']['open'];
@@ -884,7 +944,7 @@ function createStubClient(params: {
         identifiers: { appId: 'com.example.demo' },
       }),
       installFromSource: params.installFromSource,
-      list: async () => [],
+      list: params.listApps ?? (async () => []),
       open:
         params.open ??
         (async () => ({

src/__tests__/runtime-apps.test.ts

@@ -33,7 +33,7 @@ test('runtime app commands call typed backend lifecycle primitives', async () =>
   const closed = await device.apps.close({ app: 'com.example.app' });
   assert.equal(closed.kind, 'appClosed');
 
-  const listed = await device.apps.list({ filter: 'user-installed' });
+  const listed = await device.apps.list();
   assert.deepEqual(listed.apps, [
     {
       id: 'com.example.app',

src/backend.ts

@@ -1,4 +1,5 @@
 import type { AndroidSnapshotBackendMetadata } from './platforms/android/snapshot-types.ts';
+import type { AppsFilter } from './client-types.ts';
 import type {
   Point,
   ScreenshotOverlayRef,
@@ -198,7 +199,7 @@ export type BackendOpenOptions = {
   relaunch?: boolean;
 };
 
-export type BackendAppListFilter = 'all' | 'user-installed';
+export type BackendAppListFilter = AppsFilter;
 
 export type BackendAppInfo = {
   id: string;
@@ -527,7 +528,7 @@ export type AgentDeviceBackend = {
   closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
   listApps?(
     context: BackendCommandContext,
-    filter?: BackendAppListFilter,
+    filter: BackendAppListFilter,
   ): Promise<readonly BackendAppInfo[]>;
   getAppState?(context: BackendCommandContext, app: string): Promise<BackendAppState>;
   pushFile?(

src/cli/commands/apps.ts

@@ -1,12 +1,24 @@
 import { buildSelectionOptions, writeCommandOutput } from './shared.ts';
+import { DEFAULT_APPS_FILTER } from '../../client-types.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 
 export const appsCommand: ClientCommandHandler = async ({ flags, client }) => {
+  const appsFilter = flags.appsFilter ?? DEFAULT_APPS_FILTER;
   const apps = await client.apps.list({
     ...buildSelectionOptions(flags),
-    appsFilter: flags.appsFilter,
+    appsFilter,
   });
   const data = { apps };
-  writeCommandOutput(flags, data, () => apps.join('\n'));
+  writeCommandOutput(flags, data, () => {
+    if (!flags.json) {
+      process.stderr.write(
+        appsFilter === 'all'
+          ? 'Showing all apps, including system apps.\n'
+          : 'Showing user-installed apps. Use --all to include system apps.\n',
+      );
+    }
+    if (apps.length > 0) return apps.join('\n');
+    return appsFilter === 'all' ? 'No apps found.' : 'No user-installed apps found.';
+  });
   return true;
 };

src/client-types.ts

@@ -21,6 +21,9 @@ import type { MetroBridgeScope } from './client-companion-tunnel-contract.ts';
 export type { FindLocator } from './utils/finders.ts';
 export type { CompanionTunnelScope, MetroBridgeScope } from './client-companion-tunnel-contract.ts';
 
+export type AppsFilter = 'user-installed' | 'all';
+export const DEFAULT_APPS_FILTER: AppsFilter = 'user-installed';
+
 type DaemonTransportMode = 'auto' | 'socket' | 'http';
 type DaemonServerMode = 'socket' | 'http' | 'dual';
 type SessionIsolationMode = 'none' | 'tenant';
@@ -232,7 +235,7 @@ export type AppInstallFromSourceResult = {
 
 export type AppListOptions = AgentDeviceRequestOverrides &
   AgentDeviceSelectionOptions & {
-    appsFilter?: 'all' | 'user-installed';
+    appsFilter?: AppsFilter;
   };
 
 export type MaterializationReleaseOptions = AgentDeviceRequestOverrides & {
@@ -800,7 +803,7 @@ export type InternalRequestOptions = AgentDeviceClientConfig &
     metroPort?: number;
     bundleUrl?: string;
     launchUrl?: string;
-    appsFilter?: 'all' | 'user-installed';
+    appsFilter?: AppsFilter;
     installSource?: DaemonInstallSource;
     retainMaterializedPaths?: boolean;
     materializedPathRetentionMs?: number;

src/commands/apps.ts

@@ -9,6 +9,7 @@ import type {
 } from '../backend.ts';
 import type { FileInputRef } from '../io.ts';
 import type { AgentDeviceRuntime, CommandContext } from '../runtime-contract.ts';
+import { DEFAULT_APPS_FILTER } from '../client-types.ts';
 import { AppError } from '../utils/errors.ts';
 import { successText } from '../utils/success-text.ts';
 import { resolveCommandInput } from './io-policy.ts';
@@ -151,7 +152,7 @@ export const listAppsCommand: RuntimeCommand<
 
   const apps = await runtime.backend.listApps(
     toAppBackendContext(runtime, options),
-    options.filter ?? 'all',
+    options.filter ?? DEFAULT_APPS_FILTER,
   );
   return {
     kind: 'appsList',

src/commands/session-lifecycle/definition.ts

@@ -1,5 +1,6 @@
 import { PUBLIC_COMMANDS } from '../../command-catalog.ts';
 import type { CommandCapability } from '../../core/capabilities.ts';
+import { DEFAULT_APPS_FILTER } from '../../client-types.ts';
 import { commandCapabilityMap, commandSchemaMap, defineCommand } from '../command-definition.ts';
 
 const APP_RUNTIME_CAPABILITY = {
@@ -89,11 +90,11 @@ const installFromSourceCommandDefinition = defineCommand({
 const appsCommandDefinition = defineCommand({
   name: PUBLIC_COMMANDS.apps,
   schema: {
-    helpDescription: 'List installed apps (includes default/system apps by default)',
+    helpDescription: 'List user-installed apps; use --all to include system/OEM apps',
     summary: 'List installed apps',
     positionalArgs: [],
     allowedFlags: ['appsFilter'],
-    defaults: { appsFilter: 'all' },
+    defaults: { appsFilter: DEFAULT_APPS_FILTER },
   },
   capability: APP_INVENTORY_CAPABILITY,
 });

src/daemon/handlers/__tests__/session.test.ts

@@ -1390,7 +1390,7 @@ test('apps on macOS uses Apple app listing path', async () => {
 
   mockListIosApps.mockImplementation(async (device, filter) => {
     expect(device.platform).toBe('macos');
-    expect(filter).toBe('all');
+    expect(filter).toBe('user-installed');
     return [{ bundleId: 'com.apple.systempreferences', name: 'System Settings' }];
   });
   const response = await handleSessionCommands({