cdd-cli 3.1.9 → 3.2.2

package/test/containerActions.test.js

@@ -3,14 +3,13 @@ import { jest } from '@jest/globals';
 describe('containerActions service functions (mocked ESM imports)', () => {
   afterEach(() => jest.resetModules());
 
-  test('createContainer returns id when image exists', async () => {
-    // mock imageUtils and dockerService before importing the module under test
+  test('createContainer returns { id, ports } when image exists', async () => {
     const imageUtilsMock = {
       imageExists: jest.fn().mockResolvedValue(true),
       pullImage: jest.fn()
     };
 
-    const inspectMock = jest.fn().mockResolvedValue({ Config: { ExposedPorts: {} } });
+    const inspectMock = jest.fn().mockResolvedValue({ Config: { ExposedPorts: { '3306/tcp': {} } } });
     const dockerMock = {
       createContainer: jest.fn().mockResolvedValue({ id: 'cid-123' }),
       getImage: jest.fn().mockReturnValue({ inspect: inspectMock }),
@@ -27,16 +26,107 @@ describe('containerActions service functions (mocked ESM imports)', () => {
 
     const mod = await import('../src/helpers/dockerService/serviceComponents/containerActions.js');
 
-    const id = await mod.createContainer('nginx:latest', { Name: 'test' });
-    expect(id).toBe('cid-123');
-    const imageUtils = await import('../src/helpers/dockerService/serviceComponents/imageUtils.js');
-    expect(imageUtils.imageExists).toHaveBeenCalledWith('nginx:latest');
-    const ds = await import('../src/helpers/dockerService/dockerService.js');
-    expect(ds.docker.createContainer).toHaveBeenCalled();
-    expect(ds.docker.getImage).toHaveBeenCalledWith('nginx:latest');
+    const result = await mod.createContainer('mysql:8', { Name: 'test' });
+    expect(result).toHaveProperty('id', 'cid-123');
+    expect(result).toHaveProperty('ports');
+    expect(Array.isArray(result.ports)).toBe(true);
+  });
+
+  test('createContainer ports contain containerPort, hostPort, protocol, source fields', async () => {
+    const imageUtilsMock = {
+      imageExists: jest.fn().mockResolvedValue(true),
+      pullImage: jest.fn()
+    };
+
+    const inspectMock = jest.fn().mockResolvedValue({ Config: { ExposedPorts: { '80/tcp': {} } } });
+    const dockerMock = {
+      createContainer: jest.fn().mockResolvedValue({ id: 'cid-ports' }),
+      getImage: jest.fn().mockReturnValue({ inspect: inspectMock }),
+      listContainers: jest.fn().mockResolvedValue([])
+    };
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/serviceComponents/imageUtils.js', () => ({
+      ...imageUtilsMock
+    }));
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/dockerService.js', () => ({
+      docker: dockerMock
+    }));
+
+    const mod = await import('../src/helpers/dockerService/serviceComponents/containerActions.js');
+    const result = await mod.createContainer('nginx:latest', {});
+    expect(result.ports.length).toBeGreaterThan(0);
+    const port = result.ports[0];
+    expect(port).toHaveProperty('containerPort');
+    expect(port).toHaveProperty('hostPort');
+    expect(port).toHaveProperty('protocol');
+    expect(port).toHaveProperty('source');
+  });
+
+  test('createContainer uses IMAGE_PROFILES defaultPort as fallback when ExposedPorts empty', async () => {
+    const imageUtilsMock = {
+      imageExists: jest.fn().mockResolvedValue(true),
+      pullImage: jest.fn()
+    };
+
+    // inspect returns empty ExposedPorts
+    const inspectMock = jest.fn().mockResolvedValue({ Config: { ExposedPorts: {} } });
+    const dockerMock = {
+      createContainer: jest.fn().mockResolvedValue({ id: 'cid-fallback' }),
+      getImage: jest.fn().mockReturnValue({ inspect: inspectMock }),
+      listContainers: jest.fn().mockResolvedValue([])
+    };
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/serviceComponents/imageUtils.js', () => ({
+      ...imageUtilsMock
+    }));
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/dockerService.js', () => ({
+      docker: dockerMock
+    }));
+
+    const { IMAGE_PROFILES } = await import('../src/helpers/constants.js');
+    const mod = await import('../src/helpers/dockerService/serviceComponents/containerActions.js');
+    const result = await mod.createContainer('mysql:8', {}, IMAGE_PROFILES);
+
+    expect(result.id).toBe('cid-fallback');
+    // Should have auto port from defaultPort fallback
+    const mysqlDefault = IMAGE_PROFILES.mysql.defaultPort;
+    const portEntry = result.ports.find(p => p.containerPort === mysqlDefault);
+    expect(portEntry).toBeDefined();
+    expect(portEntry.source).toBe('auto');
+  });
+
+  test('createContainer returns { id, ports: [] } when no ports and image not in profiles', async () => {
+    const imageUtilsMock = {
+      imageExists: jest.fn().mockResolvedValue(true),
+      pullImage: jest.fn()
+    };
+
+    const inspectMock = jest.fn().mockResolvedValue({ Config: { ExposedPorts: {} } });
+    const dockerMock = {
+      createContainer: jest.fn().mockResolvedValue({ id: 'cid-noport' }),
+      getImage: jest.fn().mockReturnValue({ inspect: inspectMock }),
+      listContainers: jest.fn().mockResolvedValue([])
+    };
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/serviceComponents/imageUtils.js', () => ({
+      ...imageUtilsMock
+    }));
+
+    await jest.unstable_mockModule('../src/helpers/dockerService/dockerService.js', () => ({
+      docker: dockerMock
+    }));
+
+    const { IMAGE_PROFILES } = await import('../src/helpers/constants.js');
+    const mod = await import('../src/helpers/dockerService/serviceComponents/containerActions.js');
+    const result = await mod.createContainer('unknownimage:latest', {}, IMAGE_PROFILES);
+
+    expect(result.id).toBe('cid-noport');
+    expect(result.ports).toEqual([]);
   });
 
-  test('createContainer pulls image when not present and returns Id', async () => {
+  test('createContainer pulls image when not present and returns { id, ports }', async () => {
     const imageUtilsMock = {
       imageExists: jest.fn().mockResolvedValue(false),
       pullImage: jest.fn().mockResolvedValue(true)
@@ -58,8 +148,9 @@ describe('containerActions service functions (mocked ESM imports)', () => {
     }));
 
     const mod = await import('../src/helpers/dockerService/serviceComponents/containerActions.js');
-    const id = await mod.createContainer('busybox:1.0');
-    expect(id).toBe('CID-456');
+    const result = await mod.createContainer('busybox:1.0');
+    expect(result.id).toBe('CID-456');
+    expect(result).toHaveProperty('ports');
     const imageUtils = await import('../src/helpers/dockerService/serviceComponents/imageUtils.js');
     expect(imageUtils.pullImage).toHaveBeenCalledWith('busybox:1.0');
   });

package/test/containerOptionsBuilder.test.js

@@ -0,0 +1,36 @@
+let buildContainerOptions;
+
+beforeAll(async () => {
+  const mod = await import('../src/helpers/containerOptionsBuilder.js');
+  buildContainerOptions = mod.buildContainerOptions;
+});
+
+describe('buildContainerOptions', () => {
+  test('basic image only sets Tty', () => {
+    const opts = buildContainerOptions({ imageName: 'nginx' });
+    expect(opts.Tty).toBe(true);
+    expect(opts.Env).toBeUndefined();
+  });
+
+  test('env var with value containing = is preserved intact', () => {
+    const opts = buildContainerOptions({ imageName: 'nginx', envInput: 'TOKEN=a=b' });
+    expect(opts.Env).toEqual(['TOKEN=a=b']);
+  });
+
+  test('multiple env vars with = in values are all preserved', () => {
+    const opts = buildContainerOptions({ imageName: 'nginx', envInput: 'TOKEN=a=b,DSN=user:pass@host/db?opt=1' });
+    expect(opts.Env).toContain('TOKEN=a=b');
+    expect(opts.Env).toContain('DSN=user:pass@host/db?opt=1');
+  });
+
+  test('port input builds ExposedPorts and PortBindings', () => {
+    const opts = buildContainerOptions({ imageName: 'nginx', portInput: '8080:80' });
+    expect(opts.ExposedPorts).toEqual({ '80/tcp': {} });
+    expect(opts.HostConfig.PortBindings['80/tcp']).toEqual([{ HostPort: '8080' }]);
+  });
+
+  test('container name is included when provided', () => {
+    const opts = buildContainerOptions({ imageName: 'nginx', containerName: 'my-nginx' });
+    expect(opts.name).toBe('my-nginx');
+  });
+});

package/test/useContainerCreation.dom.test.js

@@ -4,9 +4,10 @@
 import React, { useEffect } from 'react';
 import { render, act } from '@testing-library/react';
 import { useContainerCreation } from '../src/hooks/creation/useContainerCreation.js';
+import { IMAGE_PROFILES } from '../src/helpers/constants.js';
 
-function HookTester({ onCreate, onCancel, dbImages, expose }) {
-  const hook = useContainerCreation({ onCreate, onCancel, dbImages });
+function HookTester({ onCreate, onCancel, dbImages, imageProfiles, expose }) {
+  const hook = useContainerCreation({ onCreate, onCancel, dbImages, imageProfiles });
   // keep exposing the latest hook values on every render
   useEffect(() => {
     if (expose) expose.current = hook;
@@ -97,4 +98,167 @@ describe('useContainerCreation (DOM render)', () => {
       expect(created.length).toBe(1);
       expect(created[0]).toEqual({ imageName: 'redis', containerName: '', portInput: '', envInput: 'FOO=bar' });
   });
+
+  test('step 3 with mysql image: missing MYSQL_ROOT_PASSWORD blocks creation', () => {
+    const created = [];
+    const expose = { current: null };
+
+    render(<HookTester onCreate={(d) => created.push(d)} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    // advance to step 3 (env) with mysql image
+    act(() => { expose.current.setImageName('mysql:8'); });
+    act(() => { expose.current.nextStep(); }); // step 0 → 1
+    act(() => { expose.current.nextStep(); }); // step 1 → 2
+    act(() => { expose.current.nextStep(); }); // step 2 → 3
+
+    expect(expose.current.step).toBe(3);
+
+    // try to advance without required env var
+    act(() => { expose.current.nextStep(); });
+
+    expect(expose.current.step).toBe(3); // still blocked
+    expect(expose.current.message).toMatch(/MYSQL_ROOT_PASSWORD/i);
+    expect(created.length).toBe(0);
+  });
+
+  test('step 3 with mysql image: valid env advances and calls onCreate', () => {
+    const created = [];
+    const expose = { current: null };
+
+    render(<HookTester onCreate={(d) => created.push(d)} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.setImageName('mysql:8'); });
+    act(() => { expose.current.nextStep(); });
+    act(() => { expose.current.nextStep(); });
+    act(() => { expose.current.nextStep(); }); // at step 3
+
+    act(() => { expose.current.setEnvInput('MYSQL_ROOT_PASSWORD=secret'); });
+    act(() => { expose.current.nextStep(); }); // should call onCreate
+
+    expect(created.length).toBe(1);
+    expect(created[0].imageName).toBe('mysql:8');
+  });
+});
+
+describe('useContainerCreation — suggestions & updateImageInput()', () => {
+  test('hook exposes suggestions, selectedSuggestionIndex, visibleOffset', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+    expect(Array.isArray(expose.current.suggestions)).toBe(true);
+    expect(typeof expose.current.selectedSuggestionIndex).toBe('number');
+    expect(typeof expose.current.visibleOffset).toBe('number');
+  });
+
+  test('updateImageInput() with "ng" filters IMAGE_PROFILES keys containing "ng"', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+
+    expect(expose.current.imageName).toBe('ng');
+    expect(expose.current.suggestions).toContain('nginx');
+  });
+
+  test('updateImageInput() with empty string clears suggestions', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+    act(() => { expose.current.updateImageInput(''); });
+
+    expect(expose.current.suggestions).toHaveLength(0);
+  });
+
+  test('updateImageInput() resets selectedSuggestionIndex to -1', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+
+    expect(expose.current.selectedSuggestionIndex).toBe(-1);
+  });
+
+  test('step-3 message includes suggestedEnv hints when profile has them', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.setImageName('postgres'); });
+    act(() => { expose.current.nextStep(); }); // → step 1
+    act(() => { expose.current.nextStep(); }); // → step 2
+    act(() => { expose.current.nextStep(); }); // → step 3
+
+    expect(expose.current.message).toMatch(/POSTGRES_PASSWORD/i);
+    expect(expose.current.message).toMatch(/POSTGRES_USER/i);
+  });
+});
+
+describe('useContainerCreation — moveSuggestionSelection() & applyFocusedSuggestion()', () => {
+  test('moveSuggestionSelection(1) increases selectedSuggestionIndex', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('m'); });
+    // There should be several suggestions with "m"
+    act(() => { expose.current.moveSuggestionSelection(1); });
+
+    expect(expose.current.selectedSuggestionIndex).toBe(0);
+  });
+
+  test('moveSuggestionSelection() clamps at last item', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('m'); });
+    const count = expose.current.suggestions.length;
+
+    // Move past end
+    for (let i = 0; i <= count + 2; i++) {
+      act(() => { expose.current.moveSuggestionSelection(1); });
+    }
+
+    expect(expose.current.selectedSuggestionIndex).toBe(count - 1);
+  });
+
+  test('moveSuggestionSelection(-1) clamps at -1 (no selection)', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('m'); });
+    act(() => { expose.current.moveSuggestionSelection(-1); });
+
+    expect(expose.current.selectedSuggestionIndex).toBe(-1);
+  });
+
+  test('applyFocusedSuggestion() fills imageName with focused suggestion', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+    act(() => { expose.current.moveSuggestionSelection(1); }); // select first
+    act(() => { expose.current.applyFocusedSuggestion(); });
+
+    expect(expose.current.imageName).toBe('nginx');
+  });
+
+  test('applyFocusedSuggestion() does NOT advance step', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+    act(() => { expose.current.moveSuggestionSelection(1); });
+    act(() => { expose.current.applyFocusedSuggestion(); });
+
+    expect(expose.current.step).toBe(0);
+  });
+
+  test('applyFocusedSuggestion() clears suggestions after applying', () => {
+    const expose = { current: null };
+    render(<HookTester onCreate={() => {}} onCancel={() => {}} dbImages={[]} imageProfiles={IMAGE_PROFILES} expose={expose} />);
+
+    act(() => { expose.current.updateImageInput('ng'); });
+    act(() => { expose.current.moveSuggestionSelection(1); });
+    act(() => { expose.current.applyFocusedSuggestion(); });
+
+    expect(expose.current.suggestions).toHaveLength(0);
+  });
 });

package/test/useControls.dom.test.js

@@ -0,0 +1,313 @@
+/**
+ * @jest-environment jsdom
+ */
+import React, { useEffect } from 'react';
+import { render, act } from '@testing-library/react';
+import { jest } from '@jest/globals';
+
+// Mock ink — capture the useInput handler so tests can simulate keypresses.
+let _inputHandler = null;
+const triggerInput = (input, key = {}) => {
+  if (_inputHandler) _inputHandler(input, key);
+};
+await jest.unstable_mockModule('ink', () => ({
+  Box: ({ children, ...props }) => React.createElement('div', props, children),
+  Text: ({ children }) => React.createElement('span', null, children),
+  useInput: (fn) => { _inputHandler = fn; },
+  useApp: () => ({ exit: () => {} }),
+}));
+
+// Mock containerActions — expose all named exports so dependents don't break
+const mockSvcCreateContainer = jest.fn();
+await jest.unstable_mockModule(
+  '../src/helpers/dockerService/serviceComponents/containerActions.js',
+  () => ({
+    createContainer: mockSvcCreateContainer,
+    removeContainer: jest.fn().mockResolvedValue(undefined),
+    startContainer: jest.fn().mockResolvedValue(undefined),
+    stopContainer: jest.fn().mockResolvedValue(undefined),
+    restartContainer: jest.fn().mockResolvedValue(undefined),
+  })
+);
+
+// Mock getLogsStream to avoid side effects
+await jest.unstable_mockModule(
+  '../src/helpers/dockerService/serviceComponents/containerLogs.js',
+  () => ({ getLogsStream: () => {} })
+);
+
+const { useControls } = await import('../src/hooks/useControls.js');
+
+function HookTester({ containers, expose }) {
+  const hook = useControls(containers);
+  useEffect(() => {
+    if (expose) expose.current = hook;
+  });
+  return null;
+}
+
+// Helper: advance creation wizard to the final step and trigger onCreate
+async function completeCreationWizard(expose, imageName = 'nginx') {
+  act(() => { expose.current.creation.setImageName(imageName); });
+  act(() => { expose.current.creation.nextStep(); }); // step 0 → 1
+  act(() => { expose.current.creation.nextStep(); }); // step 1 → 2
+  act(() => { expose.current.creation.nextStep(); }); // step 2 → 3
+  // step 3: call nextStep to trigger onCreate (async)
+  await act(async () => { expose.current.creation.nextStep(); });
+}
+
+describe('useControls (FR6 — port mapping in success message)', () => {
+  beforeEach(() => {
+    mockSvcCreateContainer.mockReset();
+  });
+
+  test('success message includes port mapping after container creation', async () => {
+    const ports = [
+      { containerPort: '3306', hostPort: '3306', protocol: 'tcp', source: 'auto' },
+    ];
+    mockSvcCreateContainer.mockResolvedValue({ id: 'cid-abc', ports });
+
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    await completeCreationWizard(expose, 'nginx');
+
+    expect(expose.current.actions.message).toBe(
+      'Created container cid-abc | Ports: 3306→3306/tcp'
+    );
+    expect(expose.current.actions.messageColor).toBe('green');
+  });
+
+  test('success message has no port section when ports array is empty', async () => {
+    mockSvcCreateContainer.mockResolvedValue({ id: 'cid-xyz', ports: [] });
+
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    await completeCreationWizard(expose, 'alpine');
+
+    expect(expose.current.actions.message).toBe('Created container cid-xyz');
+    expect(expose.current.actions.messageColor).toBe('green');
+  });
+
+  test('success message includes multiple port mappings', async () => {
+    const ports = [
+      { containerPort: '80', hostPort: '8080', protocol: 'tcp', source: 'user' },
+      { containerPort: '443', hostPort: '8443', protocol: 'tcp', source: 'user' },
+    ];
+    mockSvcCreateContainer.mockResolvedValue({ id: 'cid-multi', ports });
+
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    await completeCreationWizard(expose, 'nginx');
+
+    expect(expose.current.actions.message).toBe(
+      'Created container cid-multi | Ports: 8080→80/tcp, 8443→443/tcp'
+    );
+  });
+
+  test('error message is shown when svcCreateContainer rejects', async () => {
+    mockSvcCreateContainer.mockRejectedValue(new Error('pull access denied'));
+
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    await completeCreationWizard(expose, 'badimage');
+
+    expect(expose.current.actions.message).toBe(
+      'Error creating container: pull access denied'
+    );
+    expect(expose.current.actions.messageColor).toBe('red');
+  });
+});
+
+describe('useControls — step 0 keyboard routing integration', () => {
+  beforeEach(() => {
+    mockSvcCreateContainer.mockReset();
+  });
+
+  test('creation.updateImageInput() filters suggestions (routing readiness check)', () => {
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    // updateImageInput should be exposed through creation hook
+    expect(typeof expose.current.creation.updateImageInput).toBe('function');
+
+    act(() => { expose.current.creation.updateImageInput('ng'); });
+
+    expect(expose.current.creation.suggestions).toContain('nginx');
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(-1);
+  });
+
+  test('moveSuggestionSelection(1) then applyFocusedSuggestion() fills imageName', () => {
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    act(() => { expose.current.creation.updateImageInput('ng'); });
+    act(() => { expose.current.creation.moveSuggestionSelection(1); });
+    act(() => { expose.current.creation.applyFocusedSuggestion(); });
+
+    expect(expose.current.creation.imageName).toBe('nginx');
+    expect(expose.current.creation.step).toBe(0);
+    expect(expose.current.creation.suggestions).toHaveLength(0);
+  });
+
+  test('applyFocusedSuggestion() does not advance step (Enter with focus uses suggestion not nextStep)', () => {
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    act(() => { expose.current.creation.updateImageInput('ng'); });
+    act(() => { expose.current.creation.moveSuggestionSelection(1); });
+    act(() => { expose.current.creation.applyFocusedSuggestion(); });
+
+    // Step must remain 0 — autocomplete applied, wizard did not advance
+    expect(expose.current.creation.step).toBe(0);
+  });
+
+  test('nextStep() with imageName set advances to step 1 (normal flow without suggestions)', () => {
+    const expose = { current: null };
+    render(<HookTester containers={[]} expose={expose} />);
+
+    act(() => { expose.current.creation.setImageName('nginx'); });
+    act(() => { expose.current.creation.nextStep(); });
+
+    expect(expose.current.creation.step).toBe(1);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FR4 / FR5 / FR6 — Real keyboard routing via processCreationInput
+// These tests simulate actual keypresses through the useInput callback.
+// ─────────────────────────────────────────────────────────────────────────────
+describe('useControls — FR4/FR5/FR6 keyboard routing via processCreationInput', () => {
+  beforeEach(() => {
+    _inputHandler = null;
+    mockSvcCreateContainer.mockReset();
+  });
+
+  /** Helper: render hook and enter creation mode by simulating 'c' keypress. */
+  function renderAndStartCreation(containers = []) {
+    const expose = { current: null };
+    render(<HookTester containers={containers} expose={expose} />);
+    // Trigger creation mode ('c' command in handleDockerCommands)
+    act(() => { triggerInput('c', {}); });
+    return expose;
+  }
+
+  // ── FR4: ↑/↓ only intercepted on step 0 with suggestions ────────────────
+
+  test('FR4 — ↓ arrow on step 0 with suggestions moves selection down', () => {
+    const expose = renderAndStartCreation();
+
+    // Type 'n' to get suggestions (nginx, node, etc.)
+    act(() => { triggerInput('n', {}); });
+    const suggestionsAfterType = expose.current.creation.suggestions;
+    expect(suggestionsAfterType.length).toBeGreaterThan(0);
+
+    act(() => { triggerInput('', { downArrow: true }); });
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(0);
+  });
+
+  test('FR4 — ↑ arrow on step 0 with suggestions moves selection up', () => {
+    const expose = renderAndStartCreation();
+
+    act(() => { triggerInput('n', {}); });
+    // Move down twice, then up once → index should be 0
+    act(() => { triggerInput('', { downArrow: true }); });
+    act(() => { triggerInput('', { downArrow: true }); });
+    act(() => { triggerInput('', { upArrow: true }); });
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(0);
+  });
+
+  test('FR4 — ↑/↓ are ignored on step 0 when suggestions list is empty', () => {
+    const expose = renderAndStartCreation();
+
+    // Type something unlikely to match → no suggestions
+    act(() => { triggerInput('x', {}); });
+    act(() => { triggerInput('x', {}); });
+    act(() => { triggerInput('x', {}); });
+    expect(expose.current.creation.suggestions).toHaveLength(0);
+
+    act(() => { triggerInput('', { downArrow: true }); });
+    // selectedSuggestionIndex stays at -1 (ignored)
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(-1);
+  });
+
+  test('FR4 — ↑/↓ are ignored when step > 0 (no suggestions navigation on other steps)', () => {
+    const expose = renderAndStartCreation();
+
+    // Advance to step 1 by typing an image name and pressing Enter
+    act(() => { triggerInput('n', {}); }); // type → imageName='n'
+    act(() => { triggerInput('g', {}); }); // type → imageName='ng', suggestions appear
+    // Clear suggestions by pressing Escape then re-enter (shortcut: directly set step)
+    // Instead, clear imageName and press Enter with no suggestions
+    // Set imageName via direct API, advance step
+    act(() => { expose.current.creation.setImageName('nginx'); });
+    // Simulate Enter (\r) with no focused suggestion → should advance step
+    act(() => { triggerInput('\r', {}); });
+    expect(expose.current.creation.step).toBe(1);
+
+    const prevSelection = expose.current.creation.selectedSuggestionIndex;
+    act(() => { triggerInput('', { downArrow: true }); });
+    // selection is unchanged — arrow ignored on step 1
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(prevSelection);
+  });
+
+  // ── FR5: Enter with focused suggestion → apply, NOT nextStep ─────────────
+
+  test('FR5 — Enter with selectedSuggestionIndex >= 0 applies suggestion and stays on step 0', () => {
+    const expose = renderAndStartCreation();
+
+    act(() => { triggerInput('n', {}); }); // type to get suggestions
+    expect(expose.current.creation.suggestions.length).toBeGreaterThan(0);
+
+    act(() => { triggerInput('', { downArrow: true }); }); // select first suggestion
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(0);
+
+    // Press Enter → should apply suggestion, NOT advance step
+    act(() => { triggerInput('\r', {}); });
+
+    expect(expose.current.creation.step).toBe(0);
+    expect(expose.current.creation.imageName).not.toBe('');
+    expect(expose.current.creation.imageName).not.toBe('n');
+  });
+
+  test('FR5 — Enter with focused suggestion does NOT call nextStep (step stays 0)', () => {
+    const expose = renderAndStartCreation();
+
+    act(() => { triggerInput('n', {}); });
+    act(() => { triggerInput('', { downArrow: true }); }); // focus first
+
+    act(() => { triggerInput('\r', {}); }); // Enter with focus
+
+    // FR5: step must be 0 (nextStep was NOT called)
+    expect(expose.current.creation.step).toBe(0);
+  });
+
+  // ── FR6: Enter without focused suggestion → nextStep ─────────────────────
+
+  test('FR6 — Enter with selectedSuggestionIndex === -1 advances step', () => {
+    const expose = renderAndStartCreation();
+
+    act(() => { expose.current.creation.setImageName('nginx'); });
+    // No suggestion focused (index -1)
+    expect(expose.current.creation.selectedSuggestionIndex).toBe(-1);
+
+    act(() => { triggerInput('\r', {}); }); // Enter without focus
+    expect(expose.current.creation.step).toBe(1);
+  });
+
+  test('FR6 — Enter without focus does NOT apply suggestion (imageName unchanged)', () => {
+    const expose = renderAndStartCreation();
+
+    act(() => { expose.current.creation.setImageName('nginx'); });
+    const nameBefore = expose.current.creation.imageName;
+
+    act(() => { triggerInput('\r', {}); }); // advance to step 1
+
+    // imageName should be unchanged — applyFocusedSuggestion was NOT called
+    expect(expose.current.creation.imageName).toBe(nameBefore);
+    expect(expose.current.creation.step).toBe(1);
+  });
+});