Initial commit
This commit is contained in:
Zhongwei Li
358
commands/specweave-ado-import-areas.md
Normal file
358
commands/specweave-ado-import-areas.md
Normal file
@@ -0,0 +1,358 @@
|
||||
---
|
||||
name: specweave-ado:import-areas
|
||||
description: Import Azure DevOps area paths from a project and map them to SpecWeave projects. Creates 2-level directory structure with area path-based organization.
|
||||
---
|
||||
|
||||
# Import ADO Area Paths Command
|
||||
|
||||
You are an Azure DevOps integration expert. Help the user import area paths from an ADO project and map them to SpecWeave projects.
|
||||
|
||||
## Command Usage
|
||||
|
||||
```bash
|
||||
/specweave-ado:import-areas # Interactive mode (prompts for project)
|
||||
/specweave-ado:import-areas --project MyProduct # Specific ADO project
|
||||
/specweave-ado:import-areas --dry-run # Preview without creating directories
|
||||
/specweave-ado:import-areas --include-children # Include child area paths
|
||||
```
|
||||
|
||||
## Your Task
|
||||
|
||||
When the user runs this command:
|
||||
|
||||
### Step 1: Validate Prerequisites
|
||||
|
||||
1. **Check ADO credentials** exist in `.env`:
|
||||
- `AZURE_DEVOPS_PAT`
|
||||
- `AZURE_DEVOPS_ORG`
|
||||
- `AZURE_DEVOPS_PROJECT`
|
||||
|
||||
2. **Check config.json** for existing area path mapping:
|
||||
- If `sync.profiles.*.config.areaPathMapping` exists, warn user
|
||||
|
||||
### Step 2: Get Project Name
|
||||
|
||||
**If `--project` flag provided:**
|
||||
- Use the provided project name
|
||||
|
||||
**If no flag (interactive mode):**
|
||||
```
|
||||
🔷 Azure DevOps Area Path Import
|
||||
|
||||
Enter the ADO project name to import area paths from:
|
||||
> MyProduct
|
||||
|
||||
Fetching area paths from project MyProduct...
|
||||
```
|
||||
|
||||
### Step 3: Fetch and Display Area Paths
|
||||
|
||||
```typescript
|
||||
import { fetchAreaPathsForProject } from '../lib/ado-board-resolver';
|
||||
|
||||
const areaPaths = await fetchAreaPathsForProject(
|
||||
process.env.AZURE_DEVOPS_ORG,
|
||||
'MyProduct',
|
||||
process.env.AZURE_DEVOPS_PAT
|
||||
);
|
||||
```
|
||||
|
||||
**Display area paths:**
|
||||
```
|
||||
Found 6 area paths in project MyProduct:
|
||||
|
||||
1. ☑ MyProduct\Frontend (45 active items)
|
||||
2. ☑ MyProduct\Backend (78 active items)
|
||||
3. ☑ MyProduct\Mobile (23 active items)
|
||||
4. ☑ MyProduct\DevOps (12 active items)
|
||||
5. ☐ MyProduct\Archive (0 items) [deselected - archive]
|
||||
6. ☐ MyProduct (root) [deselected - root level]
|
||||
|
||||
Select area paths to import (Space to toggle, Enter to confirm)
|
||||
```
|
||||
|
||||
### Step 4: Map Area Paths to SpecWeave Projects
|
||||
|
||||
For each selected area path, prompt for SpecWeave project ID:
|
||||
|
||||
```
|
||||
🏷️ Mapping area paths to SpecWeave projects:
|
||||
|
||||
Area path "MyProduct\Frontend" → SpecWeave project ID: [fe]
|
||||
→ Include child area paths? [Y/n]: y
|
||||
→ Keywords for auto-classification (optional): frontend, ui, angular, css
|
||||
|
||||
Area path "MyProduct\Backend" → SpecWeave project ID: [be]
|
||||
→ Include child area paths? [Y/n]: y
|
||||
→ Keywords for auto-classification (optional): api, server, database, c#
|
||||
|
||||
Area path "MyProduct\Mobile" → SpecWeave project ID: [mobile]
|
||||
→ Include child area paths? [Y/n]: y
|
||||
→ Keywords for auto-classification (optional): ios, android, xamarin
|
||||
|
||||
Area path "MyProduct\DevOps" → SpecWeave project ID: [devops]
|
||||
→ Include child area paths? [Y/n]: y
|
||||
→ Keywords for auto-classification (optional): infrastructure, ci, cd, terraform
|
||||
```
|
||||
|
||||
**Project ID validation:**
|
||||
- Must be lowercase, alphanumeric with hyphens
|
||||
- Must not collide with existing project IDs
|
||||
- If collision detected, suggest prefixed version: `myproduct-fe` instead of `fe`
|
||||
|
||||
### Step 5: Create Directory Structure
|
||||
|
||||
Create 2-level directory structure:
|
||||
|
||||
```
|
||||
.specweave/docs/internal/specs/
|
||||
└── ADO-myproduct/ ← Level 1: ADO project
|
||||
├── fe/ ← Level 2: SpecWeave project
|
||||
│ └── .gitkeep
|
||||
├── be/
|
||||
│ └── .gitkeep
|
||||
├── mobile/
|
||||
│ └── .gitkeep
|
||||
└── devops/
|
||||
└── .gitkeep
|
||||
```
|
||||
|
||||
### Step 6: Update config.json
|
||||
|
||||
Add area path mapping to config:
|
||||
|
||||
```json
|
||||
{
|
||||
"sync": {
|
||||
"profiles": {
|
||||
"ado-default": {
|
||||
"provider": "ado",
|
||||
"config": {
|
||||
"organization": "myorg",
|
||||
"areaPathMapping": {
|
||||
"project": "MyProduct",
|
||||
"mappings": [
|
||||
{
|
||||
"areaPath": "MyProduct\\Frontend",
|
||||
"specweaveProject": "fe",
|
||||
"includeChildren": true,
|
||||
"keywords": ["frontend", "ui", "angular", "css"]
|
||||
},
|
||||
{
|
||||
"areaPath": "MyProduct\\Backend",
|
||||
"specweaveProject": "be",
|
||||
"includeChildren": true,
|
||||
"keywords": ["api", "server", "database", "c#"]
|
||||
},
|
||||
{
|
||||
"areaPath": "MyProduct\\Mobile",
|
||||
"specweaveProject": "mobile",
|
||||
"includeChildren": true,
|
||||
"keywords": ["ios", "android", "xamarin"]
|
||||
},
|
||||
{
|
||||
"areaPath": "MyProduct\\DevOps",
|
||||
"specweaveProject": "devops",
|
||||
"includeChildren": true,
|
||||
"keywords": ["infrastructure", "ci", "cd", "terraform"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"multiProject": {
|
||||
"enabled": true,
|
||||
"activeProject": "fe",
|
||||
"projects": {
|
||||
"fe": {
|
||||
"name": "Frontend",
|
||||
"externalTools": {
|
||||
"ado": {
|
||||
"areaPath": "MyProduct\\Frontend",
|
||||
"project": "MyProduct"
|
||||
}
|
||||
}
|
||||
},
|
||||
"be": {
|
||||
"name": "Backend",
|
||||
"externalTools": {
|
||||
"ado": {
|
||||
"areaPath": "MyProduct\\Backend",
|
||||
"project": "MyProduct"
|
||||
}
|
||||
}
|
||||
},
|
||||
"mobile": {
|
||||
"name": "Mobile",
|
||||
"externalTools": {
|
||||
"ado": {
|
||||
"areaPath": "MyProduct\\Mobile",
|
||||
"project": "MyProduct"
|
||||
}
|
||||
}
|
||||
},
|
||||
"devops": {
|
||||
"name": "DevOps",
|
||||
"externalTools": {
|
||||
"ado": {
|
||||
"areaPath": "MyProduct\\DevOps",
|
||||
"project": "MyProduct"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 7: Display Summary
|
||||
|
||||
```
|
||||
✅ Azure DevOps Area Paths Import Complete!
|
||||
|
||||
🔷 ADO Project: MyProduct
|
||||
📁 Created: .specweave/docs/internal/specs/ADO-myproduct/
|
||||
|
||||
Area paths imported:
|
||||
✓ MyProduct\Frontend → fe (includes children)
|
||||
Keywords: frontend, ui, angular, css
|
||||
✓ MyProduct\Backend → be (includes children)
|
||||
Keywords: api, server, database, c#
|
||||
✓ MyProduct\Mobile → mobile (includes children)
|
||||
Keywords: ios, android, xamarin
|
||||
✓ MyProduct\DevOps → devops (includes children)
|
||||
Keywords: infrastructure, ci, cd, terraform
|
||||
|
||||
💡 Next steps:
|
||||
1. Use /specweave:switch-project fe to switch active project
|
||||
2. Create increment: /specweave:increment "feature name"
|
||||
3. User stories will auto-sync to the correct area path based on keywords
|
||||
|
||||
📖 Documentation: .specweave/docs/internal/architecture/adr/0143-jira-ado-multi-level-project-mapping.md
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Interactive Import
|
||||
```
|
||||
User: /specweave-ado:import-areas
|
||||
|
||||
You:
|
||||
🔷 Azure DevOps Area Path Import
|
||||
|
||||
Enter the ADO project name: MyProduct
|
||||
Fetching area paths...
|
||||
|
||||
Found 4 area paths:
|
||||
☑ MyProduct\Frontend
|
||||
☑ MyProduct\Backend
|
||||
☑ MyProduct\Mobile
|
||||
☐ MyProduct (root) [deselected]
|
||||
|
||||
Mapping to SpecWeave projects:
|
||||
MyProduct\Frontend → fe
|
||||
MyProduct\Backend → be
|
||||
MyProduct\Mobile → mobile
|
||||
|
||||
✅ Import complete! 3 area paths mapped.
|
||||
```
|
||||
|
||||
### Example 2: Dry Run
|
||||
```
|
||||
User: /specweave-ado:import-areas --project MyProduct --dry-run
|
||||
|
||||
You:
|
||||
🔷 Azure DevOps Area Path Import (DRY RUN)
|
||||
|
||||
Would import from project: MyProduct
|
||||
|
||||
Would create:
|
||||
.specweave/docs/internal/specs/ADO-myproduct/
|
||||
.specweave/docs/internal/specs/ADO-myproduct/fe/
|
||||
.specweave/docs/internal/specs/ADO-myproduct/be/
|
||||
.specweave/docs/internal/specs/ADO-myproduct/mobile/
|
||||
|
||||
Would update config.json with area path mapping.
|
||||
|
||||
No changes made (dry run).
|
||||
```
|
||||
|
||||
### Example 3: Already Configured
|
||||
```
|
||||
User: /specweave-ado:import-areas
|
||||
|
||||
You:
|
||||
⚠️ Area path mapping already exists for project MyProduct
|
||||
|
||||
Current mappings:
|
||||
MyProduct\Frontend → fe
|
||||
MyProduct\Backend → be
|
||||
|
||||
Do you want to:
|
||||
1. Add more area paths
|
||||
2. Replace existing mapping
|
||||
3. Cancel
|
||||
|
||||
> 1
|
||||
|
||||
Fetching additional area paths...
|
||||
☐ MyProduct\Frontend (already mapped)
|
||||
☐ MyProduct\Backend (already mapped)
|
||||
☑ MyProduct\Mobile (new)
|
||||
☑ MyProduct\DevOps (new)
|
||||
|
||||
Added:
|
||||
MyProduct\Mobile → mobile
|
||||
MyProduct\DevOps → devops
|
||||
|
||||
✅ Updated! Now 4 area paths mapped.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Missing credentials:**
|
||||
```
|
||||
❌ Azure DevOps credentials not found
|
||||
|
||||
Please add to .env:
|
||||
AZURE_DEVOPS_PAT=your_personal_access_token
|
||||
AZURE_DEVOPS_ORG=your_organization
|
||||
AZURE_DEVOPS_PROJECT=your_project
|
||||
|
||||
Or run: specweave init . (to configure Azure DevOps)
|
||||
```
|
||||
|
||||
**Project not found:**
|
||||
```
|
||||
❌ ADO project "INVALID" not found in organization "myorg"
|
||||
|
||||
Available projects you have access to:
|
||||
- MyProduct (My Product Development)
|
||||
- Infrastructure (DevOps & Infrastructure)
|
||||
- Legacy (Legacy Systems)
|
||||
|
||||
Tip: Use /specweave-ado:import-areas --project MyProduct
|
||||
```
|
||||
|
||||
**No area paths found:**
|
||||
```
|
||||
⚠️ No child area paths found in project MyProduct
|
||||
|
||||
The project only has the root area path. This means:
|
||||
1. Teams aren't using area paths for organization
|
||||
2. You can create area paths in ADO Project Settings
|
||||
|
||||
Suggestions:
|
||||
- Use single-project mode (no area path mapping)
|
||||
- Create area paths in ADO: Project Settings → Work → Areas
|
||||
- Run this command again after creating area paths
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/specweave-ado:import-projects` - Import multiple ADO projects
|
||||
- `/specweave-ado:sync` - Sync increments with ADO
|
||||
- `/specweave:switch-project` - Switch active SpecWeave project
|
||||
- `/specweave:init-multiproject` - Initialize multi-project mode
|
||||
Reference in New Issue
Block a user