import { INTERNAL_COMMANDS, PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog'; import type { DaemonInstallSource } from '@agent-device/kernel/contracts'; import type { CliFlags } from '@agent-device/contracts/command'; import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema'; import { LEASE_DEVICE_SPEC_FLAGS } from '@agent-device/command-registry/flag-groups'; import { AppError } from '@agent-device/kernel/errors'; import { parseGitHubActionsArtifactInstallSourceSpec } from '@agent-device/provision-kit/install-source-config'; import { booleanField, jsonSchemaField, leaseDeviceSpecFields, looseObjectSchema, requiredField, integerField, stringField, } from '../command-input.ts'; import { commonInputFromFlags, direct, leaseDeviceSpecInputFromFlags, request, requiredDaemonString, requiredString, } from '../cli-grammar/common.ts'; import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts'; import { defineCommandFacet } from '../family/types.ts'; import { defineFieldCommandMetadata } from '../field-command-contract.ts'; const installCommandMetadata = defineFieldCommandMetadata( 'install', 'Install an app binary from a local path. Provide an app identifier with the path when the target needs explicit app selection; use reinstall to replace an already installed app. Local Android and iOS install steps time out after 120s; the command allows 480s including device startup.', { app: stringField('Optional app identifier hint.'), appPath: requiredField(stringField('Path to app binary.')), ...leaseDeviceSpecFields(), }, ); const reinstallCommandMetadata = defineFieldCommandMetadata( 'reinstall', 'Replace an installed app with a binary from a local path. Use this when preserving the same app identity while installing a new build on the selected device. Local Android and iOS install steps time out after 120s; the command allows 480s including device startup and uninstall.', { app: requiredField(stringField()), appPath: requiredField(stringField('Path to app binary.')), ...leaseDeviceSpecFields(), }, ); const uninstallCommandMetadata = defineFieldCommandMetadata( 'uninstall', 'Remove an installed app from the selected device. A package name or bundle id that is not installed succeeds with wasInstalled: false. The command allows 480s including device startup.', { app: requiredField(stringField('Package name, bundle id, or installed app name.')), ...leaseDeviceSpecFields(), }, ); const installFromSourceCommandMetadata = defineFieldCommandMetadata( 'install-from-source', 'Install app builds from URLs, remote source specs, or CI artifacts resolved by a remote daemon. The command allows 600s, including up to 120s for the download; local Android and iOS install steps time out after 120s.', { source: requiredField( jsonSchemaField(looseObjectSchema('Install source object.')), ), retainPaths: booleanField(), retentionMs: integerField(), }, ); const installCliSchema = { usageOverride: 'install | install ', listUsageOverride: 'install ', positionalArgs: ['appOrPath', 'path?'], allowedFlags: LEASE_DEVICE_SPEC_FLAGS, } as const satisfies CommandSchemaOverride; const reinstallCliSchema = { positionalArgs: ['app', 'path'], allowedFlags: LEASE_DEVICE_SPEC_FLAGS, } as const satisfies CommandSchemaOverride; const uninstallCliSchema = { positionalArgs: ['app'], allowedFlags: LEASE_DEVICE_SPEC_FLAGS, } as const satisfies CommandSchemaOverride; const installFromSourceCliSchema = { usageOverride: 'install-from-source | install-from-source --github-actions-artifact ', usageFlags: [], listUsageOverride: 'install-from-source', positionalArgs: ['url?'], allowedFlags: ['header', 'githubActionsArtifact', 'installSource', 'retainPaths', 'retentionMs'], } as const satisfies CommandSchemaOverride; const installCliReader: CliReader = (positionals, flags) => installInputFromCli(positionals, flags); const reinstallCliReader: CliReader = (positionals, flags) => reinstallInputFromCli(positionals, flags); const uninstallCliReader: CliReader = (positionals, flags) => ({ ...commonInputFromFlags(flags), app: requiredString(positionals[0], 'uninstall requires app'), ...leaseDeviceSpecInputFromFlags(flags), }); const installFromSourceCliReader: CliReader = (positionals, flags) => ({ ...commonInputFromFlags(flags), source: resolveInstallSource(positionals, flags), retainPaths: flags.retainPaths, retentionMs: flags.retentionMs, }); const installDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.install, (input) => installPositionals(input.app, input.appPath), ); const reinstallDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.reinstall, (input) => requiredPair(input.app, input.appPath), ); const uninstallDaemonWriter: DaemonWriter = direct(PUBLIC_COMMANDS.uninstall, (input) => [ requiredDaemonString(input.app, 'missing app'), ]); const installFromSourceDaemonWriter: DaemonWriter = (input) => request(INTERNAL_COMMANDS.installSource, [], { ...input, installSource: input.source, retainMaterializedPaths: input.retainPaths, materializedPathRetentionMs: input.retentionMs, }); const installCommandFacet = defineCommandFacet({ name: 'install', text: { summary: 'Install an app binary from a path', }, metadata: installCommandMetadata, run: (client, input) => client.apps.install(input), cliSchema: installCliSchema, cliReader: installCliReader, daemonWriter: installDaemonWriter, }); const reinstallCommandFacet = defineCommandFacet({ name: 'reinstall', text: { summary: 'Replace an installed app with a new build', }, metadata: reinstallCommandMetadata, run: (client, input) => client.apps.reinstall(input), cliSchema: reinstallCliSchema, cliReader: reinstallCliReader, daemonWriter: reinstallDaemonWriter, }); const uninstallCommandFacet = defineCommandFacet({ name: 'uninstall', text: { summary: 'Remove an installed app', }, metadata: uninstallCommandMetadata, run: (client, input) => client.apps.uninstall(input), cliSchema: uninstallCliSchema, cliReader: uninstallCliReader, daemonWriter: uninstallDaemonWriter, }); const installFromSourceCommandFacet = defineCommandFacet({ name: 'install-from-source', text: { summary: 'Install app builds from URLs or CI artifacts', }, metadata: installFromSourceCommandMetadata, run: (client, input) => client.apps.installFromSource(input), cliSchema: installFromSourceCliSchema, cliReader: installFromSourceCliReader, daemonWriter: installFromSourceDaemonWriter, }); export const installManagementCommandFacets = [ installCommandFacet, reinstallCommandFacet, uninstallCommandFacet, installFromSourceCommandFacet, ] as const; function installInputFromCli(positionals: string[], flags: CliFlags): Record { const [first, second] = positionals; const hasExplicitApp = second !== undefined; return { ...commonInputFromFlags(flags), ...(hasExplicitApp ? { app: requiredString(first, 'install requires app') } : {}), appPath: requiredString(hasExplicitApp ? second : first, 'install requires path'), ...leaseDeviceSpecInputFromFlags(flags), }; } function reinstallInputFromCli(positionals: string[], flags: CliFlags): Record { return { ...commonInputFromFlags(flags), app: requiredString(positionals[0], 'reinstall requires app'), appPath: requiredString(positionals[1], 'reinstall requires path'), ...leaseDeviceSpecInputFromFlags(flags), }; } function installPositionals(app: unknown, appPath: unknown): string[] { const path = requiredDaemonString(appPath, 'missing app path'); return typeof app === 'string' && app.length > 0 ? [app, path] : [path]; } function requiredPair(first: unknown, second: unknown): string[] { return [ requiredDaemonString(first, 'missing first positional'), requiredDaemonString(second, 'missing second positional'), ]; } // fallow-ignore-next-line complexity function resolveInstallSource(positionals: string[], flags: CliFlags) { const url = positionals[0]?.trim(); if (positionals.length > 1) { throw new AppError( 'INVALID_ARGS', 'install-from-source accepts either one positional or --github-actions-artifact', ); } const githubArtifactSource = flags.githubActionsArtifact ? parseGitHubActionsArtifactInstallSourceSpec(flags.githubActionsArtifact) : undefined; const configuredSource = flags.installSource; const sourceCount = (url ? 1 : 0) + (githubArtifactSource ? 1 : 0) + (configuredSource ? 1 : 0); if (sourceCount !== 1) { throw new AppError( 'INVALID_ARGS', 'install-from-source requires exactly one source: , --github-actions-artifact, or config installSource', ); } if (!url && flags.header && flags.header.length > 0) { throw new AppError( 'INVALID_ARGS', 'install-from-source --header is only supported for URL sources', ); } if (githubArtifactSource) return githubArtifactSource; if (configuredSource) return configuredSource; if (!isHttpUrl(url!)) { throw new AppError('INVALID_ARGS', `install-from-source must be an http(s) URL: ${url}`, { hint: 'Install a local build with install .', }); } return { kind: 'url' as const, url: url!, headers: parseInstallSourceHeaders(flags.header), }; } function isHttpUrl(value: string): boolean { const protocol = URL.parse(value)?.protocol; return protocol === 'http:' || protocol === 'https:'; } function parseInstallSourceHeaders( headerFlags: CliFlags['header'], ): Record | undefined { if (!headerFlags || headerFlags.length === 0) return undefined; const headers: Record = {}; for (const rawHeader of headerFlags) { const separator = rawHeader.indexOf(':'); if (separator <= 0) { throw new AppError( 'INVALID_ARGS', `Invalid --header value "${rawHeader}". Expected "name:value".`, ); } const name = rawHeader.slice(0, separator).trim(); const value = rawHeader.slice(separator + 1).trim(); if (!name) { throw new AppError( 'INVALID_ARGS', `Invalid --header value "${rawHeader}". Header name cannot be empty.`, ); } headers[name] = value; } return headers; }