Skip to content

Commit e26a833

Browse files
codeaholicguycodeaholicguy
committed
Global setup design
1 parent 4a8597c commit e26a833

5 files changed

Lines changed: 519 additions & 0 deletions

File tree

‎docs/ai/design/feature-global-setup.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
phase: design
3+
title: System Design & Architecture
4+
description: Define the technical architecture, components, and data models
5+
feature: global-setup
6+
---
7+
8+
# System Design & Architecture - Global Setup Feature
9+
10+
## Architecture Overview
11+
**What is the high-level system structure?**
12+
13+
```mermaid
14+
graph TD
15+
CLI[CLI: ai-devkit setup --global] --> Selector[EnvironmentSelector]
16+
Selector -->|Filter by globalCommandPath| GlobalEnvs[Global-capable Environments]
17+
GlobalEnvs --> User[User Selection]
18+
User --> TM[TemplateManager]
19+
TM -->|Copy commands| GlobalFolder[~/.gemini/antigravity/global_workflows/ or ~/.codex/prompts/]
20+
```
21+
22+
**Key components and their responsibilities:**
23+
- **CLI (`src/cli.ts`)**: Adds new `setup` command with `--global` flag
24+
- **EnvironmentSelector (`src/lib/EnvironmentSelector.ts`)**: New method to select only global-capable environments
25+
- **TemplateManager (`src/lib/TemplateManager.ts`)**: New method to copy commands to global folders
26+
- **Environment Definitions (`src/util/env.ts`)**: New `globalCommandPath` property to indicate global support
27+
28+
**Technology stack choices:**
29+
- Use existing `fs-extra` for file operations with `os.homedir()` for home directory resolution
30+
- Use existing `inquirer` for user prompts
31+
32+
## Data Models
33+
**What data do we need to manage?**
34+
35+
### EnvironmentDefinition (Updated)
36+
```typescript
37+
export interface EnvironmentDefinition {
38+
code: string;
39+
name: string;
40+
contextFileName: string;
41+
commandPath: string;
42+
description?: string;
43+
isCustomCommandPath?: boolean;
44+
customCommandExtension?: string;
45+
globalCommandPath?: string; // NEW: Path relative to home dir for global commands
46+
}
47+
```
48+
49+
### Environment Definitions with Global Support
50+
```typescript
51+
antigravity: {
52+
code: 'antigravity',
53+
name: 'Antigravity',
54+
contextFileName: 'AGENTS.md',
55+
commandPath: '.agent/workflows',
56+
globalCommandPath: '.gemini/antigravity/global_workflows', // NEW
57+
},
58+
codex: {
59+
code: 'codex',
60+
name: 'OpenAI Codex',
61+
contextFileName: 'AGENTS.md',
62+
commandPath: '.codex/commands',
63+
globalCommandPath: '.codex/prompts', // NEW
64+
}
65+
```
66+
67+
## API Design
68+
**How do components communicate?**
69+
70+
### New CLI Command
71+
```bash
72+
ai-devkit setup --global
73+
```
74+
75+
### New/Modified Functions
76+
77+
**`src/util/env.ts`:**
78+
```typescript
79+
// Get only environments that support global setup
80+
export function getGlobalCapableEnvironments(): EnvironmentDefinition[];
81+
82+
// Check if an environment supports global setup
83+
export function hasGlobalSupport(envCode: EnvironmentCode): boolean;
84+
```
85+
86+
**`src/lib/EnvironmentSelector.ts`:**
87+
```typescript
88+
// Select from global-capable environments only
89+
async selectGlobalEnvironments(): Promise<EnvironmentCode[]>;
90+
```
91+
92+
**`src/lib/TemplateManager.ts`:**
93+
```typescript
94+
// Copy commands to global folder
95+
async copyCommandsToGlobal(envCode: EnvironmentCode): Promise<string[]>;
96+
97+
// Check if global commands exist
98+
async checkGlobalCommandsExist(envCode: EnvironmentCode): Promise<boolean>;
99+
```
100+
101+
## Component Breakdown
102+
**What are the major building blocks?**
103+
104+
### 1. Types Update (`src/types.ts`)
105+
- Add `globalCommandPath?: string` to `EnvironmentDefinition`
106+
107+
### 2. Environment Definitions Update (`src/util/env.ts`)
108+
- Add `globalCommandPath` to Antigravity and Codex definitions
109+
- Add `getGlobalCapableEnvironments()` function
110+
- Add `hasGlobalSupport()` function
111+
112+
### 3. EnvironmentSelector Update (`src/lib/EnvironmentSelector.ts`)
113+
- Add `selectGlobalEnvironments()` method that filters to global-capable envs
114+
115+
### 4. TemplateManager Update (`src/lib/TemplateManager.ts`)
116+
- Add `copyCommandsToGlobal()` method
117+
- Add `checkGlobalCommandsExist()` method
118+
- Handle home directory resolution with `os.homedir()`
119+
120+
### 5. New Setup Command (`src/commands/setup.ts`)
121+
- Create new command file for `setup --global`
122+
- Handle environment selection, overwrite prompts, and file copying
123+
124+
### 6. CLI Update (`src/cli.ts`)
125+
- Add `setup` command with `--global` flag
126+
127+
## Design Decisions
128+
**Why did we choose this approach?**
129+
130+
1. **Separate `setup` command vs. extending `init`:**
131+
- Chosen: New `setup` command with `--global` flag
132+
- Rationale: Keeps concerns separated; `init` is for project setup, `setup --global` is for global setup
133+
134+
2. **`globalCommandPath` property on EnvironmentDefinition:**
135+
- Chosen: Optional property that indicates global support
136+
- Rationale: Extensible - any environment can add global support by defining this property
137+
- Alternative considered: Separate `GLOBAL_ENVIRONMENTS` constant - less flexible
138+
139+
3. **File extension handling:**
140+
- Chosen: Use `.md` format for both Antigravity and Codex global commands
141+
- Rationale: Antigravity global workflows use `.md` format (same as local `.agent/workflows/`), Codex prompts also use `.md`
142+
- Note: Unlike regular Gemini which uses `.toml`, Antigravity global is different
143+
144+
4. **Overwrite behavior:**
145+
- Chosen: Check for existing files and prompt user
146+
- Rationale: Prevents accidental data loss of customized commands
147+
148+
5. **Cross-platform support:**
149+
- Chosen: Use `os.homedir()` and `path.join()` for path resolution
150+
- Rationale: Works consistently on macOS, Linux, and Windows
151+
152+
## Non-Functional Requirements
153+
**How should the system perform?**
154+
155+
**Reliability:**
156+
- Gracefully handle missing home directory
157+
- Create global folders if they don't exist
158+
- Provide clear error messages if file operations fail
159+
160+
**Usability:**
161+
- Clear prompts for environment selection
162+
- Informative success/error messages
163+
- Consistent with existing `init` command UX

‎docs/ai/implementation/feature-global-setup.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
phase: implementation
3+
title: Implementation Guide
4+
description: Technical implementation notes, patterns, and code guidelines
5+
feature: global-setup
6+
---
7+
8+
# Implementation Guide - Global Setup Feature
9+
10+
## Development Setup
11+
**How do we get started?**
12+
13+
- Prerequisites: Node.js, npm, project already set up
14+
- Run `npm install` to ensure dependencies are installed
15+
- Run `npm run build` to verify TypeScript compilation
16+
17+
## Code Structure
18+
**How is the code organized?**
19+
20+
Files to modify/create:
21+
```
22+
src/
23+
├── types.ts # Add globalCommandPath to EnvironmentDefinition
24+
├── util/
25+
│ └── env.ts # Add global support flags and helper functions
26+
├── lib/
27+
│ ├── EnvironmentSelector.ts # Add selectGlobalEnvironments method
28+
│ └── TemplateManager.ts # Add copyCommandsToGlobal method
29+
├── commands/
30+
│ ├── init.ts # Existing (no changes needed)
31+
│ └── setup.ts # NEW: Global setup command
32+
└── cli.ts # Add setup command
33+
```
34+
35+
## Implementation Notes
36+
**Key technical details to remember:**
37+
38+
### Home Directory Resolution
39+
```typescript
40+
import * as os from 'os';
41+
import * as path from 'path';
42+
43+
const homeDir = os.homedir();
44+
const globalPath = path.join(homeDir, env.globalCommandPath);
45+
```
46+
47+
### EnvironmentDefinition Update
48+
```typescript
49+
export interface EnvironmentDefinition {
50+
// ... existing properties
51+
globalCommandPath?: string; // Path relative to home directory (without ~)
52+
}
53+
```
54+
55+
### Global-capable Environment Filtering
56+
```typescript
57+
export function getGlobalCapableEnvironments(): EnvironmentDefinition[] {
58+
return getAllEnvironments().filter(env => env.globalCommandPath !== undefined);
59+
}
60+
```
61+
62+
### Patterns & Best Practices
63+
- Reuse existing `copyCommands` logic for consistency
64+
- Use `fs-extra` for all file operations (already a dependency)
65+
- Follow existing error handling patterns from `init.ts`
66+
- Use `chalk` for colored output (already imported)
67+
68+
## Integration Points
69+
**How do pieces connect?**
70+
71+
1. CLI parses `setup --global` command
72+
2. `setupCommand()` calls `EnvironmentSelector.selectGlobalEnvironments()`
73+
3. For each selected environment, `TemplateManager.checkGlobalCommandsExist()` checks for existing files
74+
4. If files exist, prompt user for overwrite confirmation
75+
5. `TemplateManager.copyCommandsToGlobal()` copies commands to global folder
76+
6. Display success/error messages
77+
78+
## Error Handling
79+
**How do we handle failures?**
80+
81+
- Wrap file operations in try/catch blocks
82+
- Provide clear error messages with suggested fixes
83+
- Don't exit on first error - try to complete as much as possible
84+
- Log warnings for non-critical issues (e.g., file already skipped)
85+
86+
## Security Notes
87+
**What security measures are in place?**
88+
89+
- Only write to user's home directory (no system directories)
90+
- Prompt before overwriting existing files
91+
- No network requests or external dependencies

‎docs/ai/planning/feature-global-setup.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
phase: planning
3+
title: Project Planning & Task Breakdown
4+
description: Break down work into actionable tasks and estimate timeline
5+
feature: global-setup
6+
---
7+
8+
# Project Planning & Task Breakdown - Global Setup Feature
9+
10+
## Milestones
11+
**What are the major checkpoints?**
12+
13+
- [ ] Milestone 1: Environment definitions updated with global support
14+
- [ ] Milestone 2: Core global setup functionality implemented
15+
- [ ] Milestone 3: CLI command integrated and tested
16+
17+
## Task Breakdown
18+
**What specific work needs to be done?**
19+
20+
### Phase 1: Foundation - Update Types and Environment Definitions
21+
- [ ] Task 1.1: Add `globalCommandPath` property to `EnvironmentDefinition` interface in `src/types.ts`
22+
- [ ] Task 1.2: Add `globalCommandPath` to Antigravity definition in `src/util/env.ts`
23+
- [ ] Task 1.3: Add `globalCommandPath` to Codex definition in `src/util/env.ts`
24+
- [ ] Task 1.4: Add `getGlobalCapableEnvironments()` function in `src/util/env.ts`
25+
- [ ] Task 1.5: Add `hasGlobalSupport()` function in `src/util/env.ts`
26+
27+
### Phase 2: Core Features - Implement Global Setup Logic
28+
- [ ] Task 2.1: Add `selectGlobalEnvironments()` method to `EnvironmentSelector` class
29+
- [ ] Task 2.2: Add `copyCommandsToGlobal()` method to `TemplateManager` class
30+
- [ ] Task 2.3: Add `checkGlobalCommandsExist()` method to `TemplateManager` class
31+
- [ ] Task 2.4: Create new `src/commands/setup.ts` file with global setup logic
32+
33+
### Phase 3: Integration & Polish
34+
- [ ] Task 3.1: Add `setup` command to CLI in `src/cli.ts`
35+
- [ ] Task 3.2: Add user-friendly messages and error handling
36+
- [ ] Task 3.3: Update CHANGELOG.md with new feature
37+
- [ ] Task 3.4: Test end-to-end with Antigravity and Codex
38+
39+
## Dependencies
40+
**What needs to happen in what order?**
41+
42+
```mermaid
43+
graph TD
44+
T1.1[Task 1.1: Update types] --> T1.2[Task 1.2: Antigravity def]
45+
T1.1 --> T1.3[Task 1.3: Codex def]
46+
T1.2 --> T1.4[Task 1.4: getGlobalCapableEnvironments]
47+
T1.3 --> T1.4
48+
T1.4 --> T1.5[Task 1.5: hasGlobalSupport]
49+
T1.5 --> T2.1[Task 2.1: selectGlobalEnvironments]
50+
T1.5 --> T2.2[Task 2.2: copyCommandsToGlobal]
51+
T1.5 --> T2.3[Task 2.3: checkGlobalCommandsExist]
52+
T2.1 --> T2.4[Task 2.4: setup.ts command]
53+
T2.2 --> T2.4
54+
T2.3 --> T2.4
55+
T2.4 --> T3.1[Task 3.1: CLI integration]
56+
T3.1 --> T3.2[Task 3.2: Polish messages]
57+
T3.2 --> T3.3[Task 3.3: CHANGELOG]
58+
T3.3 --> T3.4[Task 3.4: E2E testing]
59+
```
60+
61+
**External dependencies:**
62+
- None - all dependencies are internal
63+
64+
## Timeline & Estimates
65+
**When will things be done?**
66+
67+
| Task | Estimated Effort |
68+
|------|-----------------|
69+
| Phase 1 (Tasks 1.1-1.5) | ~30 minutes |
70+
| Phase 2 (Tasks 2.1-2.4) | ~45 minutes |
71+
| Phase 3 (Tasks 3.1-3.4) | ~30 minutes |
72+
| **Total** | **~1.75 hours** |
73+
74+
## Risks & Mitigation
75+
**What could go wrong?**
76+
77+
| Risk | Likelihood | Impact | Mitigation |
78+
|------|------------|--------|------------|
79+
| Home directory not accessible | Low | High | Add error handling with clear message |
80+
| File permissions issues | Low | Medium | Catch errors and provide helpful guidance |
81+
| Path resolution issues on Windows | Medium | Medium | Use `os.homedir()` and `path.join()` consistently |
82+
83+
## Resources Needed
84+
**What do we need to succeed?**
85+
86+
- Existing codebase familiarity (already explored)
87+
- `fs-extra` and `os` Node.js modules (already available)
88+
- Test environment with Antigravity and/or Codex installed (user to verify)

0 commit comments

Comments
 (0)