fix(cli): harden install error handling and state updates

Author: codeaholicguy

docs/ai/testing/feature-install-command.md

@@ -40,9 +40,19 @@ feature: install-command
 - [x] `ConfigManager.addSkill` skips duplicates.
 - [x] `SkillManager.addSkill` persists skill metadata (`registry`, `name`) to config.
 
+### Install Orchestration (`services/install/install.service.ts`)
+
+- [x] Installs environments/phases/skills in happy path.
+- [x] Prompts once and skips conflicting artifacts when overwrite is declined.
+- [x] Overwrites conflicting artifacts when prompted confirmation is accepted.
+- [x] Auto-overwrites without prompt when `--overwrite` is set.
+- [x] Skill failures are collected as warnings and do not change exit code.
+- [x] Exit code is non-zero when environment/phase failures occur.
+
 ## Integration Tests
 
 - [x] Command-level flow covered via `install` command tests with mocked orchestrator.
+- [x] Service-level integration flow covered with mocked dependencies for overwrite and partial-failure branches.
 - [ ] Real filesystem integration test for `ai-devkit install` happy path.
 - [ ] Real filesystem integration test for `--overwrite` confirmation flow.
 - [ ] Real skill install partial-failure integration with network errors.
@@ -53,6 +63,7 @@ Executed on February 23, 2026:
 
 ```bash
 npm run test -- --runInBand \
+  src/__tests__/services/install/install.service.test.ts \
   src/__tests__/util/config.test.ts \
   src/__tests__/commands/install.test.ts \
   src/__tests__/services/config/config.service.test.ts \
@@ -62,6 +73,17 @@ npm run test -- --runInBand \
 ```
 
 Result: targeted suites pass locally (command/config/config-service/config-manager/init/skill-manager coverage).
+Additional focused run:
+
+```bash
+npm run test -- --runInBand \
+  src/__tests__/services/install/install.service.test.ts \
+  src/__tests__/commands/install.test.ts \
+  src/__tests__/util/config.test.ts \
+  src/__tests__/services/config/config.service.test.ts
+```
+
+Result: `4 passed, 4 total` suites and `16 passed, 16 total` tests.
 
 ## Manual Testing
 

packages/cli/src/__tests__/commands/init.test.ts

@@ -111,6 +111,10 @@ describe('init command template mode', () => {
     mockLoadInitTemplate.mockResolvedValue({});
   });
 
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
   it('uses template values and installs multiple skills from same registry without prompts', async () => {
     mockLoadInitTemplate.mockResolvedValue({
       environments: ['codex'],

packages/cli/src/__tests__/commands/install.test.ts

@@ -47,6 +47,10 @@ describe('install command', () => {
     });
   });
 
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
   it('fails with non-zero exit code when config loading fails', async () => {
     mockLoadConfigFile.mockRejectedValue(new Error('Config file not found: /tmp/.ai-devkit.json'));
 
@@ -99,4 +103,22 @@ describe('install command', () => {
     expect(mockUi.summary).toHaveBeenCalled();
     expect(process.exitCode).toBe(0);
   });
+
+  it('fails with non-zero exit code when reconcile step throws', async () => {
+    mockLoadConfigFile.mockResolvedValue({
+      configPath: '/tmp/.ai-devkit.json',
+      data: {}
+    });
+    mockLoadAndValidateInstallConfig.mockReturnValue({
+      environments: ['codex'],
+      phases: ['requirements'],
+      skills: []
+    });
+    mockReconcileAndInstall.mockRejectedValue(new Error('install failed'));
+
+    await installCommand({});
+
+    expect(mockUi.error).toHaveBeenCalledWith('install failed');
+    expect(process.exitCode).toBe(1);
+  });
 });

packages/cli/src/__tests__/services/install/install.service.test.ts

@@ -0,0 +1,167 @@
+import { jest } from '@jest/globals';
+
+const mockPrompt: any = jest.fn();
+
+const mockConfigManager: any = {
+  read: jest.fn(),
+  create: jest.fn(),
+  update: jest.fn(),
+  addPhase: jest.fn()
+};
+
+const mockTemplateManager: any = {
+  checkEnvironmentExists: jest.fn(),
+  fileExists: jest.fn(),
+  setupMultipleEnvironments: jest.fn(),
+  copyPhaseTemplate: jest.fn()
+};
+
+const mockSkillManager: any = {
+  addSkill: jest.fn()
+};
+
+jest.mock('inquirer', () => ({
+  __esModule: true,
+  default: {
+    prompt: (...args: unknown[]) => mockPrompt(...args)
+  }
+}));
+
+jest.mock('../../../lib/Config', () => ({
+  ConfigManager: jest.fn(() => mockConfigManager)
+}));
+
+jest.mock('../../../lib/TemplateManager', () => ({
+  TemplateManager: jest.fn(() => mockTemplateManager)
+}));
+
+jest.mock('../../../lib/EnvironmentSelector', () => ({
+  EnvironmentSelector: jest.fn()
+}));
+
+jest.mock('../../../lib/SkillManager', () => ({
+  SkillManager: jest.fn(() => mockSkillManager)
+}));
+
+import { getInstallExitCode, reconcileAndInstall } from '../../../services/install/install.service';
+
+describe('install service', () => {
+  const installConfig = {
+    environments: ['codex' as const],
+    phases: ['requirements' as const],
+    skills: [{ registry: 'codeaholicguy/ai-devkit', name: 'debug' }]
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mockConfigManager.read.mockResolvedValue({
+      environments: [],
+      phases: []
+    });
+    mockConfigManager.create.mockResolvedValue({
+      environments: [],
+      phases: []
+    });
+    mockConfigManager.update.mockResolvedValue({});
+    mockConfigManager.addPhase.mockResolvedValue({});
+
+    mockTemplateManager.checkEnvironmentExists.mockResolvedValue(false);
+    mockTemplateManager.fileExists.mockResolvedValue(false);
+    mockTemplateManager.setupMultipleEnvironments.mockResolvedValue([]);
+    mockTemplateManager.copyPhaseTemplate.mockResolvedValue('docs/ai/requirements/README.md');
+
+    mockSkillManager.addSkill.mockResolvedValue(undefined);
+    mockPrompt.mockResolvedValue({ overwrite: false });
+  });
+
+  it('installs all sections on happy path', async () => {
+    const report = await reconcileAndInstall(installConfig, {});
+
+    expect(mockConfigManager.update).toHaveBeenCalledWith({
+      environments: ['codex'],
+      phases: ['requirements'],
+      skills: [{ registry: 'codeaholicguy/ai-devkit', name: 'debug' }]
+    });
+    expect(report.environments.installed).toBe(1);
+    expect(report.phases.installed).toBe(1);
+    expect(report.skills.installed).toBe(1);
+    expect(report.warnings).toEqual([]);
+  });
+
+  it('prompts and skips conflicting artifacts when overwrite is not confirmed', async () => {
+    mockTemplateManager.checkEnvironmentExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+    mockTemplateManager.fileExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+    mockPrompt.mockResolvedValue({ overwrite: false });
+
+    const report = await reconcileAndInstall(installConfig, {});
+
+    expect(mockPrompt).toHaveBeenCalledTimes(1);
+    expect(report.environments.skipped).toBe(1);
+    expect(report.phases.skipped).toBe(1);
+    expect(report.skills.installed).toBe(1);
+    expect(mockConfigManager.update).toHaveBeenCalledWith({
+      environments: [],
+      phases: [],
+      skills: [{ registry: 'codeaholicguy/ai-devkit', name: 'debug' }]
+    });
+  });
+
+  it('overwrites conflicting artifacts when overwrite is confirmed via prompt', async () => {
+    mockTemplateManager.checkEnvironmentExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+    mockTemplateManager.fileExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+    mockPrompt.mockResolvedValue({ overwrite: true });
+
+    const report = await reconcileAndInstall(installConfig, {});
+
+    expect(mockPrompt).toHaveBeenCalledTimes(1);
+    expect(report.environments.installed).toBe(1);
+    expect(report.phases.installed).toBe(1);
+  });
+
+  it('auto-overwrites and does not prompt when --overwrite is set', async () => {
+    mockTemplateManager.checkEnvironmentExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+    mockTemplateManager.fileExists
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce(true);
+
+    const report = await reconcileAndInstall(installConfig, { overwrite: true });
+
+    expect(mockPrompt).not.toHaveBeenCalled();
+    expect(report.environments.installed).toBe(1);
+    expect(report.phases.installed).toBe(1);
+  });
+
+  it('reports skill failures as warnings and continues', async () => {
+    mockSkillManager.addSkill.mockRejectedValue(new Error('network down'));
+
+    const report = await reconcileAndInstall(installConfig, {});
+
+    expect(report.skills.failed).toBe(1);
+    expect(report.warnings).toEqual([
+      'Skill codeaholicguy/ai-devkit/debug failed: network down'
+    ]);
+    expect(getInstallExitCode(report)).toBe(0);
+  });
+
+  it('returns non-zero exit code when environment or phase failures occur', () => {
+    const report = {
+      environments: { installed: 0, skipped: 0, failed: 1 },
+      phases: { installed: 0, skipped: 0, failed: 0 },
+      skills: { installed: 0, skipped: 0, failed: 0 },
+      warnings: []
+    };
+
+    expect(getInstallExitCode(report)).toBe(1);
+  });
+});

packages/cli/src/commands/install.ts

@@ -43,9 +43,16 @@ export async function installCommand(options: InstallCommandOptions): Promise<vo
     return;
   }
 
-  const report = await reconcileAndInstall(validatedConfig, {
-    overwrite: options.overwrite
-  });
+  let report;
+  try {
+    report = await reconcileAndInstall(validatedConfig, {
+      overwrite: options.overwrite
+    });
+  } catch (error) {
+    ui.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+    return;
+  }
 
   ui.summary({
     title: 'Install Summary',

packages/cli/src/services/install/install.service.ts

@@ -50,11 +50,9 @@ export async function reconcileAndInstall(
     throw new Error('Failed to initialize project config for install command.');
   }
 
-  await configManager.update({
-    environments: config.environments,
-    phases: config.phases,
-    skills: config.skills
-  });
+  const successfulEnvironments: typeof config.environments = [];
+  const successfulPhases: typeof config.phases = [];
+  const successfulSkills: typeof config.skills = [];
 
   for (const envCode of config.environments) {
     try {
@@ -66,6 +64,7 @@ export async function reconcileAndInstall(
 
       await templateManager.setupMultipleEnvironments([envCode]);
       report.environments.installed += 1;
+      successfulEnvironments.push(envCode);
     } catch (error) {
       report.environments.failed += 1;
       report.warnings.push(
@@ -85,6 +84,7 @@ export async function reconcileAndInstall(
       await templateManager.copyPhaseTemplate(phase);
       await configManager.addPhase(phase);
       report.phases.installed += 1;
+      successfulPhases.push(phase);
     } catch (error) {
       report.phases.failed += 1;
       report.warnings.push(
@@ -97,6 +97,7 @@ export async function reconcileAndInstall(
     try {
       await skillManager.addSkill(skill.registry, skill.name);
       report.skills.installed += 1;
+      successfulSkills.push(skill);
     } catch (error) {
       report.skills.failed += 1;
       report.warnings.push(
@@ -105,6 +106,12 @@ export async function reconcileAndInstall(
     }
   }
 
+  await configManager.update({
+    environments: successfulEnvironments,
+    phases: successfulPhases,
+    skills: successfulSkills
+  });
+
   return report;
 }