Skip to content

Commit 602440b

Browse files
codeaholicguycodeaholicguy
authored
Add install command (#21)
* docs(ai): add phase-1 docs for install command feature * feat(cli): add install command with config/install services * docs(install-command): align docs with current implementation * fix(cli): harden install error handling and state updates
1 parent 62c54d3 commit 602440b

File tree

25 files changed

+1440
-32
lines changed

25 files changed

+1440
-32
lines changed

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Added
11+
12+
- **Install Command** - Added `ai-devkit install` to apply project configuration from `.ai-devkit.json`
13+
- Supports `--config <path>` for custom config file locations
14+
- Supports `--overwrite` for non-interactive full overwrite mode
15+
- Installs environments, phases, and skills in a single run with summary output
16+
817
## [0.14.0] - 2026-02-21
918

1019
### Changed

‎docs/ai/design/feature-install-command.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Define the technical architecture, components, and data models
5+
feature: install-command
6+
---
7+
8+
# System Design & Architecture - Install Command
9+
10+
## Architecture Overview
11+
12+
**What is the high-level system structure?**
13+
14+
```mermaid
15+
graph TD
16+
User[User: ai-devkit install] --> InstallCommand
17+
InstallCommand --> ConfigLoader[Config Service: load .ai-devkit.json]
18+
ConfigLoader --> Validator[Config Util Validator]
19+
Validator --> Reconciler[Install Reconciler]
20+
Reconciler --> Confirmer[Overwrite Confirmation Prompt]
21+
Reconciler --> EnvSetup[TemplateManager.setupMultipleEnvironments]
22+
Reconciler --> PhaseSetup[TemplateManager.copyPhaseTemplate]
23+
Reconciler --> SkillSetup[SkillManager.addSkill]
24+
SkillSetup --> SkillConfigSync[ConfigManager.update skills metadata]
25+
Reconciler --> Reporter[Install Summary Reporter]
26+
```
27+
28+
**Key components and responsibilities:**
29+
30+
- `install` command handler: orchestrates install lifecycle.
31+
- `InstallConfig Validator`: validates environments, phases, and optional skills.
32+
- `Install Reconciler`: computes desired state vs existing files.
33+
- `TemplateManager` integration: applies environment and phase templates.
34+
- `SkillManager` integration: installs skills from config entries.
35+
- `Overwrite Confirmation Prompt`: when destination artifacts already exist, ask user to confirm replacement.
36+
- `SkillConfigSync`: ensures `ai-devkit skill add` writes skill metadata back to `.ai-devkit.json`.
37+
- `Reporter`: emits per-section summary and final exit status.
38+
39+
## Data Models
40+
41+
**What data do we need to manage?**
42+
43+
```typescript
44+
interface DevKitInstallConfig {
45+
version: string;
46+
environments: EnvironmentCode[];
47+
phases: Phase[];
48+
skills?: Array<{
49+
registry: string;
50+
name: string;
51+
}>;
52+
createdAt: string;
53+
updatedAt: string;
54+
}
55+
```
56+
57+
- Existing fields continue unchanged.
58+
- New `skills` field is optional for backward compatibility.
59+
- Duplicate skill entries deduplicated by `registry + name`.
60+
61+
## API Design
62+
63+
**How do components communicate?**
64+
65+
**CLI surface:**
66+
67+
- `ai-devkit install`
68+
- Optional follow-up flags (proposed):
69+
- `--config <path>` (default `.ai-devkit.json`)
70+
- `--overwrite` (overwrite all existing artifacts without additional prompts)
71+
72+
**Internal interfaces (proposed):**
73+
74+
```typescript
75+
async function installCommand(options: InstallOptions): Promise<void>;
76+
async function validateInstallConfig(config: unknown): Promise<ValidatedInstallConfig>;
77+
async function reconcileAndInstall(config: ValidatedInstallConfig, options: InstallOptions): Promise<InstallReport>;
78+
```
79+
80+
**Output contract:**
81+
82+
- Section summaries for environments, phases, and skills.
83+
- Final totals: installed/skipped/failed.
84+
- Exit codes:
85+
- Invalid/missing config: `1`
86+
- Valid config with success: `0`
87+
- Partial skill-install failures: `0` with warning output and failed item details.
88+
89+
## Component Breakdown
90+
91+
**What are the major building blocks?**
92+
93+
1. `packages/cli/src/commands/install.ts` (new): top-level command execution.
94+
2. `packages/cli/src/services/config/config.service.ts` (new): load config file from disk.
95+
3. `packages/cli/src/util/config.ts` (new): schema validation and normalization.
96+
4. `packages/cli/src/services/install/install.service.ts` (new): reconcile and apply installation.
97+
5. `packages/cli/src/lib/Config.ts` (update): persist/read `skills` metadata.
98+
6. `packages/cli/src/lib/SkillManager.ts` (update): on successful `addSkill`, sync skill entry into `.ai-devkit.json`.
99+
7. `packages/cli/src/cli.ts` (update): register `install` command and options.
100+
101+
## Design Decisions
102+
103+
**Why did we choose this approach?**
104+
105+
- Reuse existing managers (`TemplateManager`, `SkillManager`) for consistency and lower risk.
106+
- Add `install` as separate command instead of overloading `init` to keep intent clear:
107+
- `init`: configure project interactively/template-first.
108+
- `install`: apply existing project config deterministically.
109+
- Keep new config field optional to avoid breaking older projects.
110+
- Existing artifacts require explicit user confirmation before overwrite (safe interactive default).
111+
- Partial skill failures do not fail the whole install run; command exits `0` and reports warnings for failed items.
112+
113+
## Non-Functional Requirements
114+
115+
**How should the system perform?**
116+
117+
- Performance: install should scale linearly with configured phases and skills.
118+
- Reliability: each section continues independently and reports failures.
119+
- Security: validate config values before filesystem/network actions.
120+
- Usability: actionable errors that point to field names and file path.

‎docs/ai/implementation/feature-install-command.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Technical implementation notes, patterns, and code guidelines
5+
feature: install-command
6+
---
7+
8+
# Implementation Guide - Install Command
9+
10+
## Development Setup
11+
12+
- Implemented in `packages/cli` using existing command architecture (`commander`).
13+
- Uses `zod` for schema-based config validation.
14+
- Feature reuses existing managers: `ConfigManager`, `TemplateManager`, `SkillManager`.
15+
16+
## Code Structure
17+
18+
- `packages/cli/src/commands/install.ts`
19+
- New CLI handler for `ai-devkit install`.
20+
- Handles config loading, report output, and process exit code.
21+
- `packages/cli/src/services/config/config.service.ts`
22+
- Loads and parses config file JSON from disk.
23+
- `packages/cli/src/util/config.ts`
24+
- Validates and normalizes install config data using Zod.
25+
- Supports skill shape normalization (`name` and legacy `skill` key).
26+
- `packages/cli/src/services/install/install.service.ts`
27+
- Reconciles desired state and applies environment/phase/skill installation.
28+
- Implements overwrite and warning-based partial-failure policy.
29+
- `packages/cli/src/types.ts`
30+
- Adds optional `skills` metadata to `DevKitConfig`.
31+
- `packages/cli/src/lib/Config.ts`
32+
- Adds `addSkill` helper to persist unique `registry + name` entries.
33+
- `packages/cli/src/lib/SkillManager.ts`
34+
- Persists metadata to `.ai-devkit.json` after successful `skill add`.
35+
- `packages/cli/src/cli.ts`
36+
- Registers new `install` command and options.
37+
38+
## Implementation Notes
39+
40+
### CLI Surface
41+
42+
- `ai-devkit install`
43+
- Options:
44+
- `--config <path>`: alternate config file path (default `.ai-devkit.json`)
45+
- `--overwrite`: overwrite all existing artifacts without additional prompts
46+
47+
### Reconcile Behavior
48+
49+
- Environments and phases are installed section-by-section.
50+
- Existing artifacts are skipped unless overwrite mode is confirmed.
51+
- Skill failures are collected as warnings and do not fail run by default.
52+
- Skills are deduplicated by `registry + name` before installation.
53+
54+
### Exit Code Policy
55+
56+
- `1` for invalid/missing config.
57+
- `1` for environment/phase failures.
58+
- `0` for successful run and for skill-only partial failures.
59+
60+
## Error Handling
61+
62+
- Validation errors include field-level context and config file path.
63+
- Orchestrator aggregates per-item warnings and reports all failures at the end.
64+
- Install command prints summary and warnings before setting final exit code.
65+
66+
## Performance Considerations
67+
68+
- Linear processing by environments/phases/skills.
69+
- No additional network calls beyond existing `SkillManager` behavior.
70+
- Config normalization avoids duplicate work for duplicate entries.
71+
72+
## Security Notes
73+
74+
- Input is validated before filesystem/network operations.
75+
- Unsupported environments/phases are rejected early.
76+
- Empty/invalid skill metadata is rejected before installation.

‎docs/ai/planning/feature-install-command.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Break down work into actionable tasks and estimate timeline
5+
feature: install-command
6+
---
7+
8+
# Project Planning & Task Breakdown - Install Command
9+
10+
## Milestones
11+
12+
**What are the major checkpoints?**
13+
14+
- [x] Milestone 1: Requirements/design approved for `ai-devkit install`.
15+
- [x] Milestone 2: Core install flow (config read + env/phase reconcile) implemented.
16+
- [x] Milestone 3: Skill install integration + tests + docs completed.
17+
18+
## Task Breakdown
19+
20+
**What specific work needs to be done?**
21+
22+
### Phase 1: Foundation
23+
24+
- [x] Task 1.1: Add `install` command wiring in `packages/cli/src/cli.ts`.
25+
- [x] Task 1.2: Implement install config validator for `.ai-devkit.json`.
26+
- [x] Task 1.3: Define backward-compatible skills schema (`skills[]` optional).
27+
- [x] Task 1.4: Add install report model (installed/skipped/failed counters).
28+
29+
### Phase 2: Core Features
30+
31+
- [x] Task 2.1: Implement environment setup from `environments` using `TemplateManager`.
32+
- [x] Task 2.2: Implement phase setup from `phases` using `TemplateManager`.
33+
- [x] Task 2.3: Add idempotent handling for existing artifacts.
34+
- [x] Task 2.4: Add `--overwrite` behavior and conflict messaging.
35+
36+
### Phase 3: Skills Integration
37+
38+
- [x] Task 3.1: Implement skills install loop from config skills entries.
39+
- [x] Task 3.2: Deduplicate skill entries by `registry + name`.
40+
- [x] Task 3.3: Add partial-failure handling with warning-only skill failures.
41+
- [x] Task 3.4: Update config types/read-write paths for optional `skills` field.
42+
43+
### Phase 4: Validation & Docs
44+
45+
- [x] Task 4.1: Unit tests for config validation and normalization.
46+
- [x] Task 4.2: Integration tests for full `ai-devkit install` happy path.
47+
- [x] Task 4.3: Integration tests for missing config, invalid config, and partial failures.
48+
- [x] Task 4.4: Update README/CLI help/changelog with usage examples.
49+
50+
## Dependencies
51+
52+
**What needs to happen in what order?**
53+
54+
```mermaid
55+
graph TD
56+
T11[1.1 CLI wiring] --> T12[1.2 validator]
57+
T12 --> T21[2.1 env setup]
58+
T12 --> T22[2.2 phase setup]
59+
T13[1.3 skills schema] --> T31[3.1 skills install]
60+
T31 --> T33[3.3 strict/partial failure]
61+
T21 --> T41[4.1 tests]
62+
T22 --> T42[4.2 integration]
63+
T33 --> T43[4.3 failure tests]
64+
T42 --> T44[4.4 docs]
65+
T43 --> T44
66+
```
67+
68+
## Timeline & Estimates
69+
70+
**When will things be done?**
71+
72+
- Phase 1: completed
73+
- Phase 2: completed
74+
- Phase 3: completed
75+
- Phase 4: completed
76+
- Remaining estimate: 0 day
77+
78+
## Risks & Mitigation
79+
80+
**What could go wrong?**
81+
82+
- Risk: Existing `.ai-devkit.json` files lack `skills`.
83+
- Mitigation: keep field optional and treat as empty array.
84+
- Risk: Skill installs fail because of network/registry issues.
85+
- Mitigation: continue on error and collect warnings with clear per-skill failure details.
86+
- Risk: Overwrite policy causes accidental template replacement.
87+
- Mitigation: default skip existing artifacts unless `--overwrite` is enabled.
88+
89+
## Resources Needed
90+
91+
**What do we need to succeed?**
92+
93+
- Existing CLI command framework (`commander`).
94+
- Existing managers (`ConfigManager`, `TemplateManager`, `SkillManager`).
95+
- Test harness for command-level tests.

0 commit comments

Comments
 (0)