feat: add shutdown command (#718)

* feat: add shutdown command

* fix: address shutdown review feedback

* fix: reject active session shutdown targets

* fix: preserve shutdown failure details

* fix: satisfy shutdown fallow audit

* fix: simplify shutdown session handling

Author: thymikee

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

@@ -994,6 +994,7 @@ function createStubClient(params: {
     devices: {
       list: async () => [],
       boot: unexpectedCommandCall,
+      shutdown: unexpectedCommandCall,
     },
     sessions: {
       list: async () => [],

src/__tests__/runtime-admin-router.test.ts

@@ -39,6 +39,9 @@ test('admin runtime commands call typed backend primitives', async () => {
   const boot = await device.admin.boot({ target: { id: 'SIM-1' } });
   assert.equal(boot.kind, 'deviceBooted');
 
+  const shutdown = await device.admin.shutdown({ target: { id: 'SIM-1' } });
+  assert.equal(shutdown.kind, 'deviceShutdown');
+
   const installed = await device.admin.install({
     app: 'com.example.app',
     source: { kind: 'path', path: '/tmp/Example.app' },
@@ -60,6 +63,7 @@ test('admin runtime commands call typed backend primitives', async () => {
   assert.deepEqual(calls, [
     'listDevices',
     'bootDevice',
+    'shutdownDevice',
     'installApp',
     'reinstallApp',
     'installApp',
@@ -244,6 +248,9 @@ function createAdminBackend(
     bootDevice: async () => {
       calls.push('bootDevice');
     },
+    shutdownDevice: async () => {
+      calls.push('shutdownDevice');
+    },
     installApp: async (_context, target) => {
       calls.push('installApp');
       onInstallSource?.(target.source);

src/backend.ts

@@ -531,6 +531,10 @@ export type AgentDeviceBackend = {
     context: BackendCommandContext,
     target?: BackendDeviceTarget,
   ): Promise<BackendActionResult>;
+  shutdownDevice?(
+    context: BackendCommandContext,
+    target?: BackendDeviceTarget,
+  ): Promise<BackendActionResult>;
   resolveInstallSource?(
     context: BackendCommandContext,
     source: BackendInstallSource,

src/client-types.ts

@@ -561,6 +561,8 @@ export type DeviceBootOptions = ClientCommandBaseOptions & {
   headless?: boolean;
 };
 
+export type DeviceShutdownOptions = ClientCommandBaseOptions;
+
 export type AppPushOptions = ClientCommandBaseOptions & {
   app: string;
   payload: string | Record<string, unknown>;
@@ -908,6 +910,7 @@ export type AgentDeviceClient = {
       options?: AgentDeviceRequestOverrides & AgentDeviceSelectionOptions,
     ) => Promise<AgentDeviceDevice[]>;
     boot: (options?: DeviceBootOptions) => Promise<CommandRequestResult>;
+    shutdown: (options?: DeviceShutdownOptions) => Promise<CommandRequestResult>;
   };
   sessions: {
     list: (options?: AgentDeviceRequestOverrides) => Promise<AgentDeviceSession[]>;

src/client.ts

@@ -105,6 +105,7 @@ export function createAgentDeviceClient(
         return devices.map(normalizeDevice);
       },
       boot: async (options = {}) => await executeCommand('boot', options),
+      shutdown: async (options = {}) => await executeCommand('shutdown', options),
     },
     sessions: {
       list: async (options = {}) => await listSessions(options),

src/command-catalog.ts

@@ -37,6 +37,7 @@ export const PUBLIC_COMMANDS = {
   scroll: 'scroll',
   screenshot: 'screenshot',
   settings: 'settings',
+  shutdown: 'shutdown',
   snapshot: 'snapshot',
   swipe: 'swipe',
   test: 'test',
@@ -82,6 +83,7 @@ export type ClientBackedCliCommandName =
 export const BATCH_COMMAND_NAMES = [
   PUBLIC_COMMANDS.devices,
   PUBLIC_COMMANDS.boot,
+  PUBLIC_COMMANDS.shutdown,
   PUBLIC_COMMANDS.apps,
   PUBLIC_COMMANDS.open,
   PUBLIC_COMMANDS.close,

src/commands/admin.ts

@@ -36,6 +36,17 @@ export type AdminBootCommandResult = {
   target?: BackendDeviceTarget;
 } & BackendResultEnvelope;
 
+export type AdminShutdownCommandOptions = CommandContext & {
+  target?: BackendDeviceTarget;
+};
+
+export type AdminShutdownCommandResult = {
+  kind: 'deviceShutdown';
+  target?: BackendDeviceTarget;
+  backendResult?: Record<string, unknown>;
+  message?: string;
+};
+
 export type AdminInstallCommandOptions = CommandContext & {
   app: string;
   source: BackendInstallSource;
@@ -95,6 +106,27 @@ export const bootCommand: RuntimeCommand<
   };
 };
 
+export const shutdownCommand: RuntimeCommand<
+  AdminShutdownCommandOptions | undefined,
+  AdminShutdownCommandResult
+> = async (runtime, options = {}): Promise<AdminShutdownCommandResult> => {
+  if (!runtime.backend.shutdownDevice) {
+    throw new AppError('UNSUPPORTED_OPERATION', 'admin.shutdown is not supported by this backend');
+  }
+  const target = normalizeDeviceTarget(options.target);
+  const backendResult = await runtime.backend.shutdownDevice(
+    toBackendContext(runtime, options),
+    target,
+  );
+  const formattedBackendResult = toBackendResult(backendResult);
+  return {
+    kind: 'deviceShutdown',
+    ...(target ? { target } : {}),
+    ...(formattedBackendResult ? { backendResult: formattedBackendResult } : {}),
+    ...successText('Shutdown device'),
+  };
+};
+
 export const installCommand: RuntimeCommand<
   AdminInstallCommandOptions,
   AdminInstallCommandResult

src/commands/cli-grammar/apps.ts

@@ -29,6 +29,7 @@ export const appCliReaders = {
     ...commonInputFromFlags(flags),
     headless: flags.headless,
   }),
+  shutdown: (_positionals, flags) => commonInputFromFlags(flags),
   prepare: (positionals, flags) => ({
     ...commonInputFromFlags(flags),
     action: requiredString(positionals[0], 'prepare requires subcommand'),
@@ -77,6 +78,7 @@ export const appCliReaders = {
 export const appDaemonWriters = {
   devices: direct(PUBLIC_COMMANDS.devices),
   boot: direct(PUBLIC_COMMANDS.boot),
+  shutdown: direct(PUBLIC_COMMANDS.shutdown),
   prepare: direct(PUBLIC_COMMANDS.prepare, (input) => [
     requiredDaemonString(input.action, 'prepare requires subcommand'),
   ]),

src/commands/cli-output.ts

@@ -19,6 +19,7 @@ import {
   openCliOutput,
   recordCliOutput,
   sessionCliOutput,
+  shutdownCliOutput,
   snapshotCliOutput,
   tapCliOutput,
 } from './client-output.ts';
@@ -42,6 +43,7 @@ const messageOutput = resultOutput(messageCliOutput);
 
 const cliOutputFormatters: Partial<Record<CommandName, CliOutputFormatter>> = {
   boot: resultOutput(bootCliOutput),
+  shutdown: resultOutput(shutdownCliOutput),
   click: resultOutput(tapCliOutput),
   press: resultOutput(tapCliOutput),
   batch: resultOutput(batchCliOutput),

src/commands/client-command-contracts.ts

@@ -22,6 +22,7 @@ type MetroInput = { action: 'prepare' | 'reload' } & MetroPrepareOptions & Metro
 export const clientCommandDefinitions = [
   defineExecutableCommand(metadata('devices'), (client, input) => client.devices.list(input)),
   defineExecutableCommand(metadata('boot'), (client, input) => client.devices.boot(input)),
+  defineExecutableCommand(metadata('shutdown'), (client, input) => client.devices.shutdown(input)),
   defineExecutableCommand(metadata('apps'), (client, input) => client.apps.list(input)),
   defineExecutableCommand(metadata('session'), async (client, { action: _action, ...input }) => ({
     sessions: await client.sessions.list(input),