feat(cli): add predownload command to pre-pull container images

Adds `awf predownload` subcommand that pulls Docker images ahead of time
for offline use or faster startup. Supports --image-registry, --image-tag,
--agent-image, and --enable-api-proxy flags. After predownloading, users
can use --skip-pull to avoid pulling at runtime.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Mossaka

src/cli.ts

@@ -1482,6 +1482,32 @@ export function validateFormat(format: string, validFormats: string[]): void {
   }
 }
 
+// Predownload subcommand - pre-pull container images
+program
+  .command('predownload')
+  .description('Pre-download Docker images for offline use or faster startup')
+  .option(
+    '--image-registry <registry>',
+    'Container image registry',
+    'ghcr.io/github/gh-aw-firewall'
+  )
+  .option('--image-tag <tag>', 'Container image tag', 'latest')
+  .option(
+    '--agent-image <value>',
+    'Agent image preset (default, act) or custom image',
+    'default'
+  )
+  .option('--enable-api-proxy', 'Also download the API proxy image', false)
+  .action(async (options) => {
+    const { predownloadCommand } = await import('./commands/predownload');
+    await predownloadCommand({
+      imageRegistry: options.imageRegistry,
+      imageTag: options.imageTag,
+      agentImage: options.agentImage,
+      enableApiProxy: options.enableApiProxy,
+    });
+  });
+
 // Logs subcommand - view Squid proxy logs
 const logsCmd = program
   .command('logs')

src/commands/predownload.test.ts

@@ -0,0 +1,57 @@
+import { resolveImages, PredownloadOptions } from './predownload';
+
+describe('predownload', () => {
+  describe('resolveImages', () => {
+    const defaults: PredownloadOptions = {
+      imageRegistry: 'ghcr.io/github/gh-aw-firewall',
+      imageTag: 'latest',
+      agentImage: 'default',
+      enableApiProxy: false,
+    };
+
+    it('should resolve squid and default agent images', () => {
+      const images = resolveImages(defaults);
+      expect(images).toEqual([
+        'ghcr.io/github/gh-aw-firewall/squid:latest',
+        'ghcr.io/github/gh-aw-firewall/agent:latest',
+      ]);
+    });
+
+    it('should resolve agent-act image for act preset', () => {
+      const images = resolveImages({ ...defaults, agentImage: 'act' });
+      expect(images).toEqual([
+        'ghcr.io/github/gh-aw-firewall/squid:latest',
+        'ghcr.io/github/gh-aw-firewall/agent-act:latest',
+      ]);
+    });
+
+    it('should include api-proxy when enabled', () => {
+      const images = resolveImages({ ...defaults, enableApiProxy: true });
+      expect(images).toEqual([
+        'ghcr.io/github/gh-aw-firewall/squid:latest',
+        'ghcr.io/github/gh-aw-firewall/agent:latest',
+        'ghcr.io/github/gh-aw-firewall/api-proxy:latest',
+      ]);
+    });
+
+    it('should use custom registry and tag', () => {
+      const images = resolveImages({
+        ...defaults,
+        imageRegistry: 'my-registry.io/awf',
+        imageTag: 'v1.0.0',
+      });
+      expect(images).toEqual([
+        'my-registry.io/awf/squid:v1.0.0',
+        'my-registry.io/awf/agent:v1.0.0',
+      ]);
+    });
+
+    it('should use custom agent image as-is', () => {
+      const images = resolveImages({ ...defaults, agentImage: 'ubuntu:22.04' });
+      expect(images).toEqual([
+        'ghcr.io/github/gh-aw-firewall/squid:latest',
+        'ubuntu:22.04',
+      ]);
+    });
+  });
+});

src/commands/predownload.ts

@@ -0,0 +1,66 @@
+import execa from 'execa';
+import { logger } from '../logger';
+
+export interface PredownloadOptions {
+  imageRegistry: string;
+  imageTag: string;
+  agentImage: string;
+  enableApiProxy: boolean;
+}
+
+/**
+ * Resolves the list of image references to pull based on the given options.
+ */
+export function resolveImages(options: PredownloadOptions): string[] {
+  const { imageRegistry, imageTag, agentImage, enableApiProxy } = options;
+  const images: string[] = [];
+
+  // Always pull squid
+  images.push(`${imageRegistry}/squid:${imageTag}`);
+
+  // Pull agent image based on preset
+  const isPreset = agentImage === 'default' || agentImage === 'act';
+  if (isPreset) {
+    const imageName = agentImage === 'act' ? 'agent-act' : 'agent';
+    images.push(`${imageRegistry}/${imageName}:${imageTag}`);
+  } else {
+    // Custom image - pull as-is
+    images.push(agentImage);
+  }
+
+  // Optionally pull api-proxy
+  if (enableApiProxy) {
+    images.push(`${imageRegistry}/api-proxy:${imageTag}`);
+  }
+
+  return images;
+}
+
+/**
+ * Pre-download Docker images for offline use or faster startup.
+ */
+export async function predownloadCommand(options: PredownloadOptions): Promise<void> {
+  const images = resolveImages(options);
+
+  logger.info(`Pre-downloading ${images.length} image(s)...`);
+
+  let failed = 0;
+  for (const image of images) {
+    logger.info(`Pulling ${image}...`);
+    try {
+      await execa('docker', ['pull', image], { stdio: 'inherit' });
+      logger.info(`Successfully pulled ${image}`);
+    } catch (error) {
+      logger.error(`Failed to pull ${image}: ${error instanceof Error ? error.message : error}`);
+      failed++;
+    }
+  }
+
+  if (failed > 0) {
+    logger.error(`${failed} of ${images.length} image(s) failed to pull`);
+    process.exit(1);
+  }
+
+  logger.info(`All ${images.length} image(s) pre-downloaded successfully`);
+  logger.info('You can now use --skip-pull to skip pulling images at runtime');
+}