specweave 0.32.2 → 0.32.5

package/plugins/specweave-jira/lib/jira-profile-resolver.ts

@@ -0,0 +1,427 @@
+/**
+ * JIRA Profile Resolver
+ *
+ * Resolves the correct JIRA profile to use for sync operations.
+ * Priority:
+ * 1. Increment's stored profile (metadata.json -> external_sync.jira.profile)
+ * 2. Global defaultProfile (config.json -> sync.defaultProfile)
+ * 3. Legacy: Global activeProfile (config.json -> sync.activeProfile)
+ *
+ * This allows each increment to sync to its designated JIRA project
+ * without requiring manual profile switching.
+ *
+ * NOTE (v0.31.0): Renamed from "activeProfile" to "defaultProfile" for clarity.
+ * The default profile is a FALLBACK, not a constraint. Bulk operations
+ * iterate ALL profiles.
+ *
+ * Usage:
+ * ```typescript
+ * const resolver = await createJiraProfileResolver();
+ * const profile = await resolver.resolveProfile('0093-my-increment');
+ * // profile contains domain, projectKey, etc.
+ * ```
+ *
+ * @module jira-profile-resolver
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * JIRA profile configuration
+ */
+export interface JiraProfileConfig {
+  /**
+   * Profile name (for display/logging)
+   */
+  profileName: string;
+
+  /**
+   * JIRA domain (e.g., company.atlassian.net)
+   */
+  domain: string;
+
+  /**
+   * JIRA project key (e.g., PROJ)
+   */
+  projectKey: string;
+
+  /**
+   * Display name (optional)
+   */
+  displayName?: string;
+
+  /**
+   * Board ID (optional, for 2-level structure)
+   */
+  boardId?: number;
+
+  /**
+   * Board name (optional)
+   */
+  boardName?: string;
+
+  /**
+   * Instance type: cloud or server
+   */
+  instanceType?: 'cloud' | 'server';
+}
+
+/**
+ * Profile resolution result
+ */
+export interface ProfileResolutionResult {
+  /**
+   * Whether resolution succeeded
+   */
+  success: boolean;
+
+  /**
+   * Resolved profile config (if success)
+   */
+  profile?: JiraProfileConfig;
+
+  /**
+   * Source of the profile
+   */
+  source?: 'increment' | 'global';
+
+  /**
+   * Error message (if failed)
+   */
+  error?: string;
+
+  /**
+   * Increment ID that was checked
+   */
+  incrementId?: string;
+}
+
+/**
+ * Sync profile from config.json
+ */
+interface ConfigProfile {
+  provider: string;
+  displayName?: string;
+  config: {
+    domain: string;
+    projectKey: string;
+    boardId?: number;
+    boardName?: string;
+    instanceType?: 'cloud' | 'server';
+  };
+}
+
+/**
+ * Sync config from config.json
+ */
+interface SyncConfig {
+  /** @since v0.31.0 - preferred */
+  defaultProfile?: string;
+  /** @deprecated Use defaultProfile */
+  activeProfile?: string;
+  profiles?: Record<string, ConfigProfile>;
+}
+
+/**
+ * Config structure
+ */
+interface SpecWeaveConfig {
+  sync?: SyncConfig;
+}
+
+/**
+ * JIRA Profile Resolver
+ */
+export class JiraProfileResolver {
+  private projectRoot: string;
+  private configPath: string;
+  private incrementsPath: string;
+
+  constructor(projectRoot: string = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.configPath = path.join(projectRoot, '.specweave', 'config.json');
+    this.incrementsPath = path.join(projectRoot, '.specweave', 'increments');
+  }
+
+  /**
+   * Resolve the JIRA profile for an increment
+   *
+   * Priority:
+   * 1. Increment's metadata.json -> external_sync.jira.profile
+   * 2. Config.json -> sync.defaultProfile (v0.31.0+)
+   * 3. Config.json -> sync.activeProfile (legacy fallback)
+   *
+   * @param incrementId - Increment ID (e.g., "0093-my-feature")
+   * @returns Profile resolution result
+   */
+  async resolveProfile(incrementId: string): Promise<ProfileResolutionResult> {
+    // Load global config
+    const config = await this.loadConfig();
+    if (!config) {
+      return {
+        success: false,
+        error: 'Failed to load .specweave/config.json',
+        incrementId,
+      };
+    }
+
+    // Try to get increment-specific profile first
+    const incrementProfile = await this.getIncrementProfile(incrementId);
+
+    // Determine which profile to use (defaultProfile preferred over activeProfile)
+    const globalDefaultProfile = config.sync?.defaultProfile ?? config.sync?.activeProfile;
+    const profileName = incrementProfile || globalDefaultProfile;
+
+    if (!profileName) {
+      return {
+        success: false,
+        error: 'No JIRA profile configured. Set sync.defaultProfile in config.json or external_sync.jira.profile in increment metadata.',
+        incrementId,
+      };
+    }
+
+    // Check if profile is for JIRA provider
+    const profiles = config.sync?.profiles || {};
+    const profileConfig = profiles[profileName] as ConfigProfile | undefined;
+
+    if (!profileConfig) {
+      return {
+        success: false,
+        error: `Profile "${profileName}" not found in config.sync.profiles`,
+        incrementId,
+      };
+    }
+
+    if (profileConfig.provider !== 'jira') {
+      return {
+        success: false,
+        error: `Profile "${profileName}" is not a JIRA profile (provider: ${profileConfig.provider})`,
+        incrementId,
+      };
+    }
+
+    // Validate required fields
+    if (!profileConfig.config?.domain || !profileConfig.config?.projectKey) {
+      return {
+        success: false,
+        error: `Profile "${profileName}" missing required fields (domain, projectKey)`,
+        incrementId,
+      };
+    }
+
+    return {
+      success: true,
+      profile: {
+        profileName,
+        domain: profileConfig.config.domain,
+        projectKey: profileConfig.config.projectKey,
+        displayName: profileConfig.displayName,
+        boardId: profileConfig.config.boardId,
+        boardName: profileConfig.config.boardName,
+        instanceType: profileConfig.config.instanceType ?? 'cloud',
+      },
+      source: incrementProfile ? 'increment' : 'global',
+      incrementId,
+    };
+  }
+
+  /**
+   * Get increment's stored JIRA profile name
+   *
+   * @param incrementId - Increment ID
+   * @returns Profile name or null if not set
+   */
+  async getIncrementProfile(incrementId: string): Promise<string | null> {
+    const metadataPath = path.join(this.incrementsPath, incrementId, 'metadata.json');
+
+    try {
+      const content = await fs.readFile(metadataPath, 'utf-8');
+      const metadata = JSON.parse(content);
+
+      // Check for profile in external_sync.jira.profile (standardized naming)
+      // Also support legacy external_ids.jira for backwards compatibility
+      return metadata?.external_sync?.jira?.profile
+        || metadata?.external_ids?.jira?.profile
+        || null;
+    } catch {
+      // Metadata not found or invalid - return null
+      return null;
+    }
+  }
+
+  /**
+   * Get increment's stored JIRA issue key
+   *
+   * @param incrementId - Increment ID
+   * @returns Issue key (e.g., PROJ-123) or null if not linked
+   */
+  async getIncrementIssueKey(incrementId: string): Promise<string | null> {
+    const metadataPath = path.join(this.incrementsPath, incrementId, 'metadata.json');
+
+    try {
+      const content = await fs.readFile(metadataPath, 'utf-8');
+      const metadata = JSON.parse(content);
+
+      // Check both standardized and legacy paths
+      return metadata?.external_sync?.jira?.issueKey
+        || metadata?.external_ids?.jira?.epic
+        || metadata?.external_ids?.jira?.issueKey
+        || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Set increment's JIRA profile
+   *
+   * Stores the profile name in the increment's metadata.json
+   *
+   * @param incrementId - Increment ID
+   * @param profileName - Profile name to set
+   */
+  async setIncrementProfile(incrementId: string, profileName: string): Promise<void> {
+    const metadataPath = path.join(this.incrementsPath, incrementId, 'metadata.json');
+
+    // Load existing metadata
+    let metadata: Record<string, unknown> = {};
+    try {
+      const content = await fs.readFile(metadataPath, 'utf-8');
+      metadata = JSON.parse(content);
+    } catch {
+      // Start with empty metadata if not found
+    }
+
+    // Set external_sync.jira.profile (standardized naming)
+    if (!metadata.external_sync) {
+      metadata.external_sync = {};
+    }
+    if (!(metadata.external_sync as Record<string, unknown>).jira) {
+      (metadata.external_sync as Record<string, unknown>).jira = {};
+    }
+    ((metadata.external_sync as Record<string, unknown>).jira as Record<string, unknown>).profile = profileName;
+
+    // Write back
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+  }
+
+  /**
+   * Set increment's JIRA issue key
+   *
+   * @param incrementId - Increment ID
+   * @param issueKey - JIRA issue key (e.g., PROJ-123)
+   */
+  async setIncrementIssueKey(incrementId: string, issueKey: string): Promise<void> {
+    const metadataPath = path.join(this.incrementsPath, incrementId, 'metadata.json');
+
+    // Load existing metadata
+    let metadata: Record<string, unknown> = {};
+    try {
+      const content = await fs.readFile(metadataPath, 'utf-8');
+      metadata = JSON.parse(content);
+    } catch {
+      // Start with empty metadata if not found
+    }
+
+    // Set external_sync.jira.issueKey (standardized naming)
+    if (!metadata.external_sync) {
+      metadata.external_sync = {};
+    }
+    if (!(metadata.external_sync as Record<string, unknown>).jira) {
+      (metadata.external_sync as Record<string, unknown>).jira = {};
+    }
+    const jiraSync = (metadata.external_sync as Record<string, unknown>).jira as Record<string, unknown>;
+    jiraSync.issueKey = issueKey;
+    jiraSync.lastSyncedAt = new Date().toISOString();
+
+    // Write back
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+  }
+
+  /**
+   * List available JIRA profiles
+   *
+   * @returns Array of profile names
+   */
+  async listJiraProfiles(): Promise<string[]> {
+    const config = await this.loadConfig();
+    if (!config?.sync?.profiles) {
+      return [];
+    }
+
+    const profiles = config.sync.profiles as Record<string, ConfigProfile>;
+    return Object.entries(profiles)
+      .filter(([_, p]) => p.provider === 'jira')
+      .map(([name]) => name);
+  }
+
+  /**
+   * Get profile details by name
+   *
+   * @param profileName - Profile name
+   * @returns Profile config or null
+   */
+  async getProfileByName(profileName: string): Promise<JiraProfileConfig | null> {
+    const config = await this.loadConfig();
+    if (!config?.sync?.profiles) {
+      return null;
+    }
+
+    const profileConfig = config.sync.profiles[profileName] as ConfigProfile | undefined;
+    if (!profileConfig || profileConfig.provider !== 'jira') {
+      return null;
+    }
+
+    return {
+      profileName,
+      domain: profileConfig.config.domain,
+      projectKey: profileConfig.config.projectKey,
+      displayName: profileConfig.displayName,
+      boardId: profileConfig.config.boardId,
+      boardName: profileConfig.config.boardName,
+      instanceType: profileConfig.config.instanceType ?? 'cloud',
+    };
+  }
+
+  /**
+   * Load config.json
+   */
+  private async loadConfig(): Promise<SpecWeaveConfig | null> {
+    try {
+      const content = await fs.readFile(this.configPath, 'utf-8');
+      return JSON.parse(content) as SpecWeaveConfig;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Create a JiraProfileResolver instance
+ *
+ * @param projectRoot - Project root directory (defaults to cwd)
+ * @returns JiraProfileResolver instance
+ */
+export async function createJiraProfileResolver(
+  projectRoot: string = process.cwd()
+): Promise<JiraProfileResolver> {
+  return new JiraProfileResolver(projectRoot);
+}
+
+/**
+ * Quick resolve: Get JIRA profile for an increment
+ *
+ * @param incrementId - Increment ID
+ * @param projectRoot - Project root directory
+ * @returns Profile resolution result
+ */
+export async function resolveJiraProfile(
+  incrementId: string,
+  projectRoot: string = process.cwd()
+): Promise<ProfileResolutionResult> {
+  const resolver = new JiraProfileResolver(projectRoot);
+  return resolver.resolveProfile(incrementId);
+}
+
+export default JiraProfileResolver;

package/plugins/specweave-jira/reference/jira-specweave-mapping.md

@@ -41,16 +41,21 @@ This is the **MOST CRITICAL** mapping. Never deviate from this 1:1 relationship.
 ```yaml
 # .specweave/increments/####-{name}/metadata.json
 {
-  "external_ids": {
+  "external_sync": {
     "jira": {
-      "epic": "PROJ-123",
-      "epic_url": "https://company.atlassian.net/browse/PROJ-123",
-      "project_key": "PROJ"
+      "profile": "jira-my-project",
+      "issueKey": "PROJ-123",
+      "issueUrl": "https://company.atlassian.net/browse/PROJ-123",
+      "projectKey": "PROJ",
+      "lastSyncedAt": "2025-12-07T04:30:00Z"
     }
   }
 }
 ```
 
+**NOTE (v0.32.0+)**: Standardized to `external_sync.jira.*` for consistency with ADO (`external_sync.ado.*`).
+Legacy `external_ids.jira.*` is still supported for backwards compatibility.
+
 **Example**:
 ```
 Jira Epic: PROJ-123 "User Authentication"
@@ -180,12 +185,12 @@ SpecWeave: .specweave/docs/internal/delivery/release-v1.0.md
 ```yaml
 # metadata.json
 {
-  "external_ids": {
+  "external_sync": {
     "jira": {
       "tasks": [
-        {"id": "T-001", "jira_key": "PROJ-126"},
-        {"id": "T-002", "jira_key": "PROJ-127"},
-        {"id": "T-003", "jira_key": "PROJ-128"}
+        {"id": "T-001", "issueKey": "PROJ-126"},
+        {"id": "T-002", "issueKey": "PROJ-127"},
+        {"id": "T-003", "issueKey": "PROJ-128"}
       ]
     }
   }
@@ -264,7 +269,7 @@ SpecWeave: .specweave/docs/internal/architecture/frontend-auth/
 3. SpecWeave creates new increment:
    ```bash
    .specweave/increments/0001-user-authentication/
-   ├── metadata.json  # external_ids.jira.epic = PROJ-123
+   ├── metadata.json  # external_sync.jira.issueKey = PROJ-123
    ├── spec.md
    ├── plan.md
    └── tasks.md
@@ -301,7 +306,7 @@ SpecWeave: .specweave/docs/internal/architecture/frontend-auth/
 4. SpecWeave updates `metadata.json`:
    ```json
    {
-     "external_ids": {
+     "external_sync": {
        "jira": {
          "stories": ["PROJ-124"]
        }
@@ -330,7 +335,7 @@ SpecWeave: .specweave/docs/internal/architecture/frontend-auth/
 6. SpecWeave updates `metadata.json`:
    ```json
    {
-     "external_ids": {
+     "external_sync": {
        "jira": {
          "stories": ["PROJ-124", "PROJ-131"]
        }

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

@@ -1,6 +1,6 @@
 ---
 name: specweave-release:npm
-description: Bump patch version, auto-commit dirty changes, push to GitHub, build, publish to npmjs.org. Use --ci for GitHub Actions publish. Use --only for local publish without git push. Use --only --local for version bump only.
+description: Bump patch version, auto-commit dirty changes, push to GitHub, build, publish to npmjs.org. Use --quick for save+release (no GH workflow). Use --ci for GitHub Actions publish. Use --only for local publish without git push. Use --only --local for version bump only.
 ---
 
 # /specweave-release:npm - NPM Release Automation
@@ -12,6 +12,7 @@ You are the NPM Release Assistant. Your job is to automate the patch version rel
 | Command | Flow | Use Case |
 |---------|------|----------|
 | `/specweave-release:npm` | Auto-commit → **PUSH** → Bump → Build → **Publish** → Push tag | **DEFAULT: INSTANT RELEASE** |
+| `/specweave-release:npm --quick` | Auto-commit → **PUSH** → Bump → Build → **Publish locally** → NO GH workflow | **QUICK: Save + Local Release** |
 | `/specweave-release:npm --ci` | Bump → Push → **CI publishes** | Let GitHub Actions handle npm publish |
 | `/specweave-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
 | `/specweave-release:npm --only --local` | **Bump ONLY** → NO build, NO publish, NO git | FASTEST: Local testing only |
@@ -21,6 +22,7 @@ You are the NPM Release Assistant. Your job is to automate the patch version rel
 Check flags in the command invocation:
 
 ```
+--quick        → QUICK MODE: save (commit+push) + local npm publish (NO GH workflow trigger)
 --ci           → CI MODE: push to git, GitHub Actions publishes (requires clean working tree)
 --only --local → Version bump ONLY (no build, no publish, no git) - FASTEST
 --only         → Direct publish to npm (bypass CI), no git push
@@ -28,12 +30,14 @@ Check flags in the command invocation:
 ```
 
 **Flag Detection Order:**
-1. Check for `--ci` flag → CI MODE (GitHub Actions publishes)
-2. Check for `--only` flag
-3. If `--only` present, check for `--local` flag → LOCAL MODE (fastest)
-4. If `--only` only → DIRECT MODE
-5. No flags → **DEFAULT: INSTANT RELEASE** (auto-commit dirty, push, build, publish)
-
+1. Check for `--quick` flag → QUICK MODE (save + local publish, NO GH workflow)
+2. Check for `--ci` flag → CI MODE (GitHub Actions publishes)
+3. Check for `--only` flag
+4. If `--only` present, check for `--local` flag → LOCAL MODE (fastest)
+5. If `--only` only → DIRECT MODE
+6. No flags → **DEFAULT: INSTANT RELEASE** (auto-commit dirty, push, build, publish)
+
+**If `--quick`**: Use QUICK MODE (section "Quick Mode Workflow")
 **If `--ci`**: Use CI MODE (section "CI Mode Workflow")
 **If `--only --local`**: Use LOCAL MODE (section "Local Mode Workflow") - FASTEST!
 **If `--only` only**: Use DIRECT MODE (section "Direct Mode Workflow")
@@ -160,6 +164,124 @@ git push origin develop --follow-tags
 
 ---
 
+## QUICK MODE WORKFLOW (--quick flag) - SAVE + LOCAL RELEASE
+
+Use this workflow when `--quick` flag is detected. This combines `/specweave:save` behavior with local npm publish. **NO GitHub workflow trigger** - everything happens locally.
+
+**Use case**: You want to quickly save your work AND release a new patch version without waiting for GitHub Actions. Perfect for:
+- Hotfixes that need immediate npm availability
+- Iterative releases during active development
+- When GitHub Actions are slow or unavailable
+
+**Key difference from DEFAULT mode**: Does NOT push the version tag, so GitHub Actions release workflow is NOT triggered.
+
+### 1. Pre-flight Check
+
+```bash
+# Verify we're on develop branch
+git rev-parse --abbrev-ref HEAD
+
+# Get current version
+node -p "require('./package.json').version"
+```
+
+**STOP if**: Not on `develop` branch (ask user to switch)
+
+### 2. Auto-Commit Dirty Changes (if any)
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If dirty, generate smart commit message and commit:
+
+```bash
+git add -A
+git commit -m "[auto-generated message based on changed files]"
+```
+
+**Message generation rules:**
+- `src/**` changes → `fix: update implementation`
+- `plugins/**` changes → `feat(plugins): update plugin`
+- `.specweave/**` changes → `chore: update specweave config`
+- `*.md` changes → `docs: update documentation`
+- Mixed → `chore: update code and documentation`
+
+### 3. Push Dirty Commit to Remote
+
+```bash
+# Push dirty commit to remote - ensures code is safe before release
+git push origin develop
+```
+
+### 4. Bump Patch Version
+
+```bash
+npm version patch -m "chore: bump version to %s"
+```
+
+This creates a NEW commit + tag locally.
+
+### 5. Build Package
+
+```bash
+npm run rebuild
+```
+
+### 6. Publish to NPM Locally
+
+```bash
+# Publish directly to npmjs.org (NO GitHub Actions!)
+npm publish --registry https://registry.npmjs.org
+```
+
+### 7. Push Version Commit ONLY (NO tag!)
+
+```bash
+# Push ONLY the version commit, NOT the tag
+# This prevents GitHub Actions release workflow from triggering
+git push origin develop
+```
+
+**CRITICAL**: Do NOT use `--follow-tags`! We want local npm publish only.
+
+### 8. Report Results
+
+```markdown
+✅ **Quick release complete!**
+
+📦 **Version**: vX.Y.Z
+🔗 **NPM**: https://www.npmjs.com/package/specweave
+🏷️ **Git Tag**: vX.Y.Z (local only - NOT pushed)
+
+**What happened**:
+- ✅ Dirty changes auto-committed
+- ✅ Pushed to GitHub (code safe!)
+- ✅ Version bumped to X.Y.Z
+- ✅ Package built
+- ✅ Published to npmjs.org (locally)
+- ⏭️ Tag NOT pushed (no GitHub Actions triggered)
+
+**Verify**: `npm view specweave version --registry https://registry.npmjs.org`
+
+**If you want to push the tag later** (triggers GH release):
+`git push origin vX.Y.Z`
+```
+
+## Quick Mode Success Criteria
+
+✅ Any dirty changes auto-committed
+✅ Dirty commit pushed to remote
+✅ Version bumped in package.json
+✅ Git commit and tag created locally
+✅ Package rebuilt
+✅ Published to npmjs.org (explicit registry!)
+✅ Version commit pushed to GitHub
+⏭️ Tag NOT pushed (no GitHub Actions)
+
+---
+
 ## CI MODE WORKFLOW (--ci flag)
 
 Use this workflow when `--ci` flag is detected. Push to git and let GitHub Actions handle npm publish.
@@ -337,9 +459,12 @@ Show the user:
 ## Quick Reference
 
 ```bash
-# DEFAULT: Instant release (auto-commits dirty, publishes, pushes)
+# DEFAULT: Instant release (auto-commits dirty, publishes, pushes + tag)
 /specweave-release:npm
 
+# QUICK: Save + local release (auto-commits, pushes, publishes - NO GH workflow)
+/specweave-release:npm --quick
+
 # CI release (GitHub Actions handles npm publish) - requires clean tree
 /specweave-release:npm --ci
 
@@ -350,12 +475,13 @@ Show the user:
 /specweave-release:npm --only --local
 ```
 
-| Scenario | Command | Auto-Commit Dirty? | NPM Published By | Git Pushed |
-|----------|---------|-------------------|------------------|------------|
-| **INSTANT RELEASE** | (no flags) | ✅ Yes | You (npmjs.org) | ✅ Yes |
-| CI release | `--ci` | ❌ STOP | GitHub Actions | ✅ Yes |
-| Quick local, push later | `--only` | ❌ STOP | You (npmjs.org) | ❌ No |
-| **FASTEST local test** | `--only --local` | N/A | ❌ None | ❌ No |
+| Scenario | Command | Auto-Commit Dirty? | NPM Published By | Git Pushed | Tag Pushed |
+|----------|---------|-------------------|------------------|------------|------------|
+| **INSTANT RELEASE** | (no flags) | ✅ Yes | You (npmjs.org) | ✅ Yes | ✅ Yes (triggers GH) |
+| **QUICK RELEASE** | `--quick` | ✅ Yes | You (npmjs.org) | ✅ Yes | ❌ No (no GH workflow) |
+| CI release | `--ci` | ❌ STOP | GitHub Actions | ✅ Yes | ✅ Yes |
+| Quick local, push later | `--only` | ❌ STOP | You (npmjs.org) | ❌ No | ❌ No |
+| **FASTEST local test** | `--only --local` | N/A | ❌ None | ❌ No | ❌ No |
 
 ---