specweave 0.28.59 → 0.28.62

package/plugins/specweave-ado/commands/specweave-ado-clone-repos.md

@@ -0,0 +1,379 @@
+---
+name: specweave-ado:clone-repos
+description: Clone Azure DevOps repositories to local workspace. Use after init if cloning was skipped, or to add repos later.
+---
+
+# Clone Azure DevOps Repositories Command
+
+You are an Azure DevOps repository cloning expert. Help users clone repositories from ADO projects to their local workspace.
+
+## Purpose
+
+This command clones Azure DevOps repositories **after** initial SpecWeave setup (`specweave init`). Use when:
+- User skipped cloning during init
+- Adding repositories from additional projects
+- Re-cloning after cleanup
+- Selective cloning with pattern filtering
+
+## Command Syntax
+
+```bash
+# Interactive mode (prompts for everything)
+/specweave-ado:clone-repos
+
+# With pattern filter
+/specweave-ado:clone-repos --pattern "sw-*"
+
+# Regex pattern
+/specweave-ado:clone-repos --pattern "regex:^api-.*$"
+
+# Specific project only
+/specweave-ado:clone-repos --project "MyProject"
+
+# Dry-run (preview only)
+/specweave-ado:clone-repos --dry-run
+```
+
+## Your Task
+
+When the user runs this command:
+
+### Step 1: Check Prerequisites
+
+```typescript
+import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';
+import chalk from 'chalk';
+
+const projectPath = process.cwd();
+const envContent = readEnvFile(projectPath);
+
+if (!envContent) {
+  console.log(chalk.red('❌ No .env file found. Run `specweave init` first.'));
+  return;
+}
+
+const parsed = parseEnvFile(envContent);
+
+if (!parsed.AZURE_DEVOPS_PAT || !parsed.AZURE_DEVOPS_ORG) {
+  console.log(chalk.red('❌ Missing Azure DevOps credentials.'));
+  console.log(chalk.gray('   Run `specweave init` with Azure DevOps provider.'));
+  return;
+}
+
+const org = parsed.AZURE_DEVOPS_ORG;
+const pat = parsed.AZURE_DEVOPS_PAT;
+
+console.log(chalk.blue('\n📦 ADO Repository Cloning\n'));
+console.log(chalk.gray(`   Organization: ${org}`));
+```
+
+### Step 2: Get Project Selection
+
+```typescript
+import { AzureDevOpsProvider } from '../../../src/core/repo-structure/providers/azure-devops-provider.js';
+
+const provider = new AzureDevOpsProvider();
+
+// If project specified via CLI, use it
+let selectedProjects: string[] = [];
+
+if (args.project) {
+  selectedProjects = [args.project];
+  console.log(chalk.gray(`   Project: ${args.project} (from CLI)`));
+} else {
+  // Fetch available projects
+  console.log(chalk.gray('\n   Fetching projects...'));
+
+  const response = await fetch(
+    `https://dev.azure.com/${org}/_apis/projects?api-version=7.0`,
+    {
+      headers: {
+        'Authorization': `Basic ${Buffer.from(':' + pat).toString('base64')}`,
+        'Accept': 'application/json'
+      }
+    }
+  );
+
+  if (!response.ok) {
+    console.log(chalk.red(`❌ Failed to fetch projects: ${response.status}`));
+    return;
+  }
+
+  const data = await response.json();
+  const projects = data.value || [];
+
+  if (projects.length === 0) {
+    console.log(chalk.yellow('⚠️  No projects found in organization.'));
+    return;
+  }
+
+  // Prompt for project selection
+  const { checkbox } = await import('@inquirer/prompts');
+
+  selectedProjects = await checkbox({
+    message: 'Select project(s) to clone repositories from:',
+    choices: projects.map(p => ({ name: p.name, value: p.name })),
+    required: true
+  });
+
+  console.log(chalk.green(`   ✓ ${selectedProjects.length} project(s) selected`));
+}
+```
+
+### Step 3: Fetch Repositories
+
+```typescript
+const allRepos = [];
+
+for (const project of selectedProjects) {
+  console.log(chalk.gray(`\n   Fetching repos from ${project}...`));
+
+  try {
+    const repos = await provider.listRepositories(org, project, pat);
+    const reposWithProject = repos.map(r => ({ ...r, project }));
+    allRepos.push(...reposWithProject);
+    console.log(chalk.green(`   ✓ Found ${repos.length} repositories`));
+  } catch (error) {
+    console.log(chalk.yellow(`   ⚠️ Failed: ${error.message}`));
+  }
+}
+
+if (allRepos.length === 0) {
+  console.log(chalk.yellow('\n⚠️  No repositories found.'));
+  return;
+}
+
+console.log(chalk.blue(`\n📋 Total: ${allRepos.length} repositories available\n`));
+```
+
+### Step 4: Apply Pattern Filter
+
+```typescript
+import { filterRepositoriesByPattern } from '../../../src/cli/helpers/selection-strategy.js';
+
+let filteredRepos = allRepos;
+let patternDescription = 'all';
+
+if (args.pattern) {
+  // Determine pattern type
+  const isRegex = args.pattern.startsWith('regex:');
+  const pattern = isRegex ? args.pattern.slice(6) : args.pattern;
+
+  const clonePattern = {
+    strategy: isRegex ? 'pattern-regex' : 'pattern-glob',
+    pattern: pattern,
+    isRegex
+  };
+
+  filteredRepos = filterRepositoriesByPattern(allRepos, clonePattern);
+  patternDescription = `matching "${pattern}"`;
+
+  console.log(chalk.gray(`   Pattern: ${args.pattern}`));
+  console.log(chalk.gray(`   Matched: ${filteredRepos.length} of ${allRepos.length} repos\n`));
+} else {
+  // Prompt for pattern selection
+  const { select, input } = await import('@inquirer/prompts');
+
+  const strategy = await select({
+    message: 'How do you want to select repositories?',
+    choices: [
+      { name: 'All - Clone all repositories', value: 'all' },
+      { name: 'Pattern (glob) - e.g., "sw-*", "*-backend"', value: 'pattern-glob' },
+      { name: 'Pattern (regex) - e.g., "^api-.*$"', value: 'pattern-regex' }
+    ]
+  });
+
+  if (strategy !== 'all') {
+    const pattern = await input({
+      message: 'Enter pattern:',
+      validate: v => v.trim() ? true : 'Pattern required'
+    });
+
+    const clonePattern = {
+      strategy,
+      pattern: pattern.trim(),
+      isRegex: strategy === 'pattern-regex'
+    };
+
+    filteredRepos = filterRepositoriesByPattern(allRepos, clonePattern);
+    patternDescription = `matching "${pattern.trim()}"`;
+  }
+}
+
+if (filteredRepos.length === 0) {
+  console.log(chalk.yellow(`⚠️  No repositories ${patternDescription}.`));
+  return;
+}
+```
+
+### Step 5: Preview and Confirm
+
+```typescript
+console.log(chalk.blue(`\n📦 Repositories to clone (${filteredRepos.length}):\n`));
+
+// Show preview (max 20)
+filteredRepos.slice(0, 20).forEach(repo => {
+  console.log(chalk.gray(`   • ${repo.name} (${repo.project})`));
+});
+
+if (filteredRepos.length > 20) {
+  console.log(chalk.gray(`   ... and ${filteredRepos.length - 20} more\n`));
+}
+
+if (args.dryRun) {
+  console.log(chalk.cyan('\n🔎 DRY RUN: No repositories will be cloned.\n'));
+  return;
+}
+
+const { confirm } = await import('@inquirer/prompts');
+
+const confirmed = await confirm({
+  message: `Clone ${filteredRepos.length} repositories to ./repos/?`,
+  default: true
+});
+
+if (!confirmed) {
+  console.log(chalk.gray('\n⏭️  Cloning cancelled.\n'));
+  return;
+}
+```
+
+### Step 6: Start Background Cloning
+
+```typescript
+import { triggerAdoRepoCloning } from '../../../src/cli/helpers/init/ado-repo-cloning.js';
+
+// Build adoProjectSelection
+const adoProjectSelection = {
+  org,
+  pat,
+  projects: selectedProjects
+};
+
+// Build clonePattern
+const clonePatternResult = args.pattern
+  ? {
+      strategy: args.pattern.startsWith('regex:') ? 'pattern-regex' : 'pattern-glob',
+      pattern: args.pattern.startsWith('regex:') ? args.pattern.slice(6) : args.pattern
+    }
+  : { strategy: 'all' };
+
+// Trigger background cloning
+await triggerAdoRepoCloning(projectPath, adoProjectSelection, clonePatternResult);
+```
+
+## Examples
+
+### Example 1: Interactive Clone
+**User**: `/specweave-ado:clone-repos`
+
+**Output**:
+```
+📦 ADO Repository Cloning
+
+   Organization: mycompany
+
+   Fetching projects...
+   ✓ 3 projects found
+
+Select project(s) to clone repositories from:
+> [x] Platform
+  [x] Shared
+  [ ] Legacy
+
+   ✓ 2 project(s) selected
+
+   Fetching repos from Platform...
+   ✓ Found 12 repositories
+   Fetching repos from Shared...
+   ✓ Found 4 repositories
+
+📋 Total: 16 repositories available
+
+How do you want to select repositories?
+> All - Clone all repositories
+
+📦 Repositories to clone (16):
+
+   • sw-frontend (Platform)
+   • sw-backend (Platform)
+   • sw-shared-lib (Shared)
+   ... and 13 more
+
+Clone 16 repositories to ./repos/? (Y/n)
+
+📦 Fetching ADO Repositories
+
+   Fetching from mycompany/Platform...
+   ✓ Found 12 repositories in Platform
+   Fetching from mycompany/Shared...
+   ✓ Found 4 repositories in Shared
+
+🔄 Cloning 16 repositories in background...
+
+   Repositories will be cloned to: ./repos/
+   Job ID: abc12345
+
+   Check progress: /specweave:jobs
+   Resume if interrupted: /specweave:jobs --resume abc12345
+```
+
+### Example 2: Pattern Filter
+**User**: `/specweave-ado:clone-repos --pattern "sw-*"`
+
+**Output**:
+```
+📦 ADO Repository Cloning
+
+   Organization: mycompany
+   Pattern: sw-*
+   Matched: 8 of 16 repos
+
+📦 Repositories to clone (8):
+
+   • sw-frontend (Platform)
+   • sw-backend (Platform)
+   • sw-shared-lib (Shared)
+   ...
+
+Clone 8 repositories to ./repos/? (Y/n)
+```
+
+### Example 3: Dry Run
+**User**: `/specweave-ado:clone-repos --dry-run`
+
+**Output**:
+```
+📦 Repositories to clone (16):
+
+   • sw-frontend (Platform)
+   • sw-backend (Platform)
+   ...
+
+🔎 DRY RUN: No repositories will be cloned.
+```
+
+## Important Notes
+
+- **Background Cloning**: Repositories clone in background (non-blocking)
+- **Progress Tracking**: Check progress with `/specweave:jobs`
+- **Resumable**: Interrupted clones can resume with `/specweave:jobs --resume <id>`
+- **Auth via PAT**: Uses HTTPS clone URLs with PAT authentication
+- **Target Directory**: Repos are cloned to `./repos/<repo-name>/`
+
+## Related Commands
+
+- `/specweave:init` - Initial SpecWeave setup (includes repo cloning option)
+- `/specweave:jobs` - Monitor background jobs
+- `/specweave-ado:import-projects` - Import ADO projects with area path mapping
+
+## Error Handling
+
+- **Missing Credentials**: Prompt to run `specweave init` first
+- **Auth Failures**: Check PAT permissions (vso.code_read scope required)
+- **Clone Failures**: Individual repo failures logged, others continue
+- **Network Errors**: Job pauses, resume with `/specweave:jobs --resume`
+
+---
+
+**Multi-Repo Support**: Perfect for microservices architectures with many ADO repositories.

package/plugins/specweave-release/commands/specweave-release-npm.md

@@ -1,6 +1,6 @@
 ---
 name: specweave-release:npm
-description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Use --quick for instant release (auto-commits dirty changes, publishes to npmjs.org, pushes to git). Use --only for local publish without git push. Use --only --local for version bump only.
+description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Use --quick for instant release (auto-commits, PUSHES FIRST, then publishes to npmjs.org). Use --only for local publish without git push. Use --only --local for version bump only.
 ---
 
 # /specweave-release:npm - NPM Release Automation
@@ -12,9 +12,9 @@ You are the NPM Release Assistant. Your job is to automate the patch version rel
 | Command | Flow | Use Case |
 |---------|------|----------|
 | `/specweave-release:npm` | Bump → Push → **CI publishes** | Standard release (CI handles npm) |
-| `/specweave-release:npm --quick` | Auto-commit → Bump → Build → **Publish** → Push | **INSTANT RELEASE** (recommended!) |
+| `/specweave-release:npm --quick` | Auto-commit → **PUSH** → Bump → Build → **Publish** → Push tag | **INSTANT RELEASE** (recommended!) |
 | `/specweave-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
-| `/specweave-release:npm --only --push` | Auto-commit → Bump → Build → **Publish** → Push | Same as --quick |
+| `/specweave-release:npm --only --push` | Auto-commit → **PUSH** → Bump → Build → **Publish** → Push tag | Same as --quick |
 | `/specweave-release:npm --only --local` | **Bump ONLY** → NO build, NO publish, NO git | FASTEST: Local testing only |
 
 ## Detecting Mode
@@ -22,7 +22,7 @@ You are the NPM Release Assistant. Your job is to automate the patch version rel
 Check flags in the command invocation:
 
 ```
---quick        → INSTANT RELEASE: auto-commit dirty, publish to npmjs.org, push git
+--quick        → INSTANT RELEASE: auto-commit, PUSH FIRST, then bump+build+publish+push tag
 --only --local → Version bump ONLY (no build, no publish, no git) - FASTEST
 --only --push  → Same as --quick (legacy alias)
 --only         → Direct publish to npm (bypass CI), no git push
@@ -47,10 +47,15 @@ Check flags in the command invocation:
 
 ## QUICK MODE WORKFLOW (--quick flag) - RECOMMENDED!
 
-Use this workflow when `--quick` flag is detected. This is the **instant release** mode - auto-commits any dirty changes, publishes directly to npmjs.org, and pushes to git. One command does everything!
+Use this workflow when `--quick` flag is detected. This is the **instant release** mode - auto-commits any dirty changes, syncs git FIRST, then publishes to npmjs.org. One command does everything!
 
 **Use case**: You made changes and want to release immediately. No manual steps needed.
 
+**CRITICAL ORDER**: Git sync FIRST, then release. This ensures:
+- Your code is safe on remote before any release operations
+- If npm publish fails, git is already synced (clean state)
+- No risk of local-only commits that could be lost
+
 ### 1. Pre-flight Check (Minimal)
 
 ```bash
@@ -63,8 +68,6 @@ node -p "require('./package.json').version"
 
 **STOP if**: Not on `develop` branch (ask user to switch)
 
-**If uncommitted changes exist → AUTO-COMMIT (Step 2)**
-
 ### 2. Auto-Commit Dirty Changes (if any)
 
 ```bash
@@ -86,32 +89,50 @@ git commit -m "[auto-generated message based on changed files]"
 - `*.md` changes → `docs: update documentation`
 - Mixed → `chore: update code and documentation`
 
-### 3. Bump Patch Version
+### 3. PUSH DIRTY COMMIT TO REMOTE FIRST! (CRITICAL!)
+
+**BEFORE any release operations, sync git:**
+
+```bash
+# Push dirty commit to remote FIRST - ensures code is safe before release
+git push origin develop
+```
+
+**Why this order?**
+- ✅ Your changes are safely on GitHub BEFORE release starts
+- ✅ If npm publish fails later, git is already synced
+- ✅ No risk of "released but not pushed" state
+- ✅ Clean recovery if anything fails mid-release
+
+### 4. Bump Patch Version
 
 ```bash
 npm version patch -m "chore: bump version to %s"
 ```
 
-### 4. Build Package
+This creates a NEW commit + tag locally.
+
+### 5. Build Package
 
 ```bash
 npm run rebuild
 ```
 
-### 5. Publish to NPM (with explicit registry!)
+### 6. Publish to NPM (with explicit registry!)
 
 ```bash
 # CRITICAL: Always specify registry to avoid ~/.npmrc redirecting to private feeds!
 npm publish --registry https://registry.npmjs.org
 ```
 
-### 6. Push to Git
+### 7. Push Version Commit + Tag
 
 ```bash
+# Push the version bump commit and tag
 git push origin develop --follow-tags
 ```
 
-### 7. Report Results
+### 8. Report Results
 
 ```markdown
 ✅ **Instant release complete!**
@@ -122,10 +143,11 @@ git push origin develop --follow-tags
 
 **What happened**:
 - ✅ Dirty changes auto-committed
+- ✅ Pushed to GitHub (code safe!)
 - ✅ Version bumped to X.Y.Z
 - ✅ Package built
 - ✅ Published to npmjs.org
-- ✅ Pushed to GitHub
+- ✅ Version tag pushed to GitHub
 
 **Verify**: `npm view specweave version --registry https://registry.npmjs.org`
 ```
@@ -133,11 +155,12 @@ git push origin develop --follow-tags
 ## Quick Mode Success Criteria
 
 ✅ Any dirty changes auto-committed
+✅ **Dirty commit pushed to remote FIRST**
 ✅ Version bumped in package.json
 ✅ Git commit and tag created
 ✅ Package rebuilt
 ✅ Published to npmjs.org (explicit registry!)
-✅ Pushed to GitHub
+✅ Version commit + tag pushed to GitHub
 
 ---
 
@@ -408,6 +431,20 @@ git add -A
 git commit -m "[generated message]"
 ```
 
+### 1c. PUSH DIRTY COMMIT TO REMOTE FIRST! (CRITICAL!)
+
+**BEFORE any release operations, sync git:**
+
+```bash
+# Push dirty commit to remote FIRST - ensures code is safe before release
+git push origin develop
+```
+
+**Why this order?**
+- ✅ Your changes are safely on GitHub BEFORE release starts
+- ✅ If npm publish fails later, git is already synced
+- ✅ No risk of "released but not pushed" state
+
 Then continue with version bump.
 
 ### 2. Bump Patch Version