specweave 0.32.2 → 0.32.5

package/plugins/specweave-jira/lib/jira-permission-gate.ts

@@ -0,0 +1,276 @@
+/**
+ * JIRA Permission Gate
+ *
+ * Validates that sync permissions are enabled before allowing JIRA write operations.
+ * This ensures manual JIRA commands respect the same permission settings as the
+ * sync-coordinator.
+ *
+ * Usage:
+ * ```typescript
+ * const gate = await createJiraPermissionGate();
+ * const result = gate.checkWritePermission();
+ * if (!result.allowed) {
+ *   console.log(result.reason);
+ *   return;
+ * }
+ * ```
+ *
+ * @module jira-permission-gate
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+  /**
+   * Whether the operation is allowed
+   */
+  allowed: boolean;
+
+  /**
+   * Human-readable reason for the decision
+   */
+  reason: string;
+
+  /**
+   * Suggested action if permission denied
+   */
+  suggestedAction?: string;
+
+  /**
+   * Which setting controls this permission
+   */
+  settingPath?: string;
+}
+
+/**
+ * Sync settings from config.json
+ */
+export interface SyncSettings {
+  canUpsertInternalItems: boolean;
+  canUpdateExternalItems: boolean;
+  canUpdateStatus: boolean;
+}
+
+/**
+ * Default settings (all disabled for safety)
+ */
+export const DEFAULT_SYNC_SETTINGS: SyncSettings = {
+  canUpsertInternalItems: false,
+  canUpdateExternalItems: false,
+  canUpdateStatus: false,
+};
+
+/**
+ * JIRA Permission Gate
+ *
+ * Checks permission settings before allowing JIRA write operations.
+ */
+export class JiraPermissionGate {
+  private settings: SyncSettings;
+  private configPath: string;
+
+  constructor(settings: SyncSettings, configPath: string) {
+    this.settings = settings;
+    this.configPath = configPath;
+  }
+
+  /**
+   * Check if write operations (create/update issues) are allowed
+   *
+   * Requires: canUpdateExternalItems = true
+   */
+  checkWritePermission(): PermissionCheckResult {
+    if (this.settings.canUpdateExternalItems) {
+      return {
+        allowed: true,
+        reason: 'Write operations permitted (canUpdateExternalItems=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: JIRA updates are disabled.',
+      suggestedAction: `Enable sync.settings.canUpdateExternalItems in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpdateExternalItems',
+    };
+  }
+
+  /**
+   * Check if status updates (transitions) are allowed
+   *
+   * Requires: canUpdateStatus = true
+   */
+  checkStatusPermission(): PermissionCheckResult {
+    if (this.settings.canUpdateStatus) {
+      return {
+        allowed: true,
+        reason: 'Status updates permitted (canUpdateStatus=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: JIRA status transitions are disabled.',
+      suggestedAction: `Enable sync.settings.canUpdateStatus in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpdateStatus',
+    };
+  }
+
+  /**
+   * Check if internal item creation is allowed
+   *
+   * Requires: canUpsertInternalItems = true
+   */
+  checkCreateInternalPermission(): PermissionCheckResult {
+    if (this.settings.canUpsertInternalItems) {
+      return {
+        allowed: true,
+        reason: 'Internal item creation permitted (canUpsertInternalItems=true)',
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Permission denied: Creating internal items is disabled.',
+      suggestedAction: `Enable sync.settings.canUpsertInternalItems in ${this.configPath}`,
+      settingPath: 'sync.settings.canUpsertInternalItems',
+    };
+  }
+
+  /**
+   * Check if close operation is allowed (requires both write AND status)
+   *
+   * Requires: canUpdateExternalItems = true AND canUpdateStatus = true
+   */
+  checkClosePermission(): PermissionCheckResult {
+    const writeCheck = this.checkWritePermission();
+    const statusCheck = this.checkStatusPermission();
+
+    if (writeCheck.allowed && statusCheck.allowed) {
+      return {
+        allowed: true,
+        reason: 'Close operations permitted (canUpdateExternalItems=true, canUpdateStatus=true)',
+      };
+    }
+
+    const missingPermissions: string[] = [];
+    if (!writeCheck.allowed) {
+      missingPermissions.push('canUpdateExternalItems');
+    }
+    if (!statusCheck.allowed) {
+      missingPermissions.push('canUpdateStatus');
+    }
+
+    return {
+      allowed: false,
+      reason: `Permission denied: Closing JIRA issues requires ${missingPermissions.join(' and ')}.`,
+      suggestedAction: `Enable ${missingPermissions.map(p => `sync.settings.${p}`).join(' and ')} in ${this.configPath}`,
+      settingPath: missingPermissions.map(p => `sync.settings.${p}`).join(', '),
+    };
+  }
+
+  /**
+   * Get current settings
+   */
+  getSettings(): SyncSettings {
+    return { ...this.settings };
+  }
+
+  /**
+   * Get human-readable permission summary
+   */
+  getPermissionSummary(): string {
+    const parts: string[] = [];
+
+    if (this.settings.canUpdateExternalItems) {
+      parts.push('create/update JIRA issues');
+    }
+    if (this.settings.canUpdateStatus) {
+      parts.push('transition issue status');
+    }
+    if (this.settings.canUpsertInternalItems) {
+      parts.push('create internal items');
+    }
+
+    if (parts.length === 0) {
+      return 'All JIRA write operations disabled (read-only mode)';
+    }
+
+    return `Allowed: ${parts.join(', ')}`;
+  }
+}
+
+/**
+ * Create a JiraPermissionGate from config.json
+ *
+ * @param projectRoot - Project root directory (defaults to cwd)
+ * @returns JiraPermissionGate instance
+ */
+export async function createJiraPermissionGate(
+  projectRoot: string = process.cwd()
+): Promise<JiraPermissionGate> {
+  const configPath = path.join(projectRoot, '.specweave', 'config.json');
+
+  try {
+    const content = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(content);
+
+    const settings: SyncSettings = {
+      canUpsertInternalItems: config?.sync?.settings?.canUpsertInternalItems ?? false,
+      canUpdateExternalItems: config?.sync?.settings?.canUpdateExternalItems ?? false,
+      canUpdateStatus: config?.sync?.settings?.canUpdateStatus ?? false,
+    };
+
+    return new JiraPermissionGate(settings, configPath);
+  } catch {
+    // Return gate with default (disabled) settings if config not found
+    return new JiraPermissionGate(DEFAULT_SYNC_SETTINGS, configPath);
+  }
+}
+
+/**
+ * Quick check: Are JIRA write operations allowed?
+ *
+ * Convenience function for simple permission checks.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Permission check result
+ */
+export async function canWriteToJira(
+  projectRoot: string = process.cwd()
+): Promise<PermissionCheckResult> {
+  const gate = await createJiraPermissionGate(projectRoot);
+  return gate.checkWritePermission();
+}
+
+/**
+ * Quick check: Are JIRA status updates allowed?
+ *
+ * @param projectRoot - Project root directory
+ * @returns Permission check result
+ */
+export async function canUpdateJiraStatus(
+  projectRoot: string = process.cwd()
+): Promise<PermissionCheckResult> {
+  const gate = await createJiraPermissionGate(projectRoot);
+  return gate.checkStatusPermission();
+}
+
+/**
+ * Quick check: Can JIRA issues be closed?
+ *
+ * @param projectRoot - Project root directory
+ * @returns Permission check result
+ */
+export async function canCloseJiraIssue(
+  projectRoot: string = process.cwd()
+): Promise<PermissionCheckResult> {
+  const gate = await createJiraPermissionGate(projectRoot);
+  return gate.checkClosePermission();
+}
+
+export default JiraPermissionGate;

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

@@ -0,0 +1,222 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+class JiraProfileResolver {
+  constructor(projectRoot = 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) {
+    const config = await this.loadConfig();
+    if (!config) {
+      return {
+        success: false,
+        error: "Failed to load .specweave/config.json",
+        incrementId
+      };
+    }
+    const incrementProfile = await this.getIncrementProfile(incrementId);
+    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
+      };
+    }
+    const profiles = config.sync?.profiles || {};
+    const profileConfig = profiles[profileName];
+    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
+      };
+    }
+    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) {
+    const metadataPath = path.join(this.incrementsPath, incrementId, "metadata.json");
+    try {
+      const content = await fs.readFile(metadataPath, "utf-8");
+      const metadata = JSON.parse(content);
+      return metadata?.external_sync?.jira?.profile || metadata?.external_ids?.jira?.profile || null;
+    } catch {
+      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) {
+    const metadataPath = path.join(this.incrementsPath, incrementId, "metadata.json");
+    try {
+      const content = await fs.readFile(metadataPath, "utf-8");
+      const metadata = JSON.parse(content);
+      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, profileName) {
+    const metadataPath = path.join(this.incrementsPath, incrementId, "metadata.json");
+    let metadata = {};
+    try {
+      const content = await fs.readFile(metadataPath, "utf-8");
+      metadata = JSON.parse(content);
+    } catch {
+    }
+    if (!metadata.external_sync) {
+      metadata.external_sync = {};
+    }
+    if (!metadata.external_sync.jira) {
+      metadata.external_sync.jira = {};
+    }
+    metadata.external_sync.jira.profile = profileName;
+    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, issueKey) {
+    const metadataPath = path.join(this.incrementsPath, incrementId, "metadata.json");
+    let metadata = {};
+    try {
+      const content = await fs.readFile(metadataPath, "utf-8");
+      metadata = JSON.parse(content);
+    } catch {
+    }
+    if (!metadata.external_sync) {
+      metadata.external_sync = {};
+    }
+    if (!metadata.external_sync.jira) {
+      metadata.external_sync.jira = {};
+    }
+    const jiraSync = metadata.external_sync.jira;
+    jiraSync.issueKey = issueKey;
+    jiraSync.lastSyncedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2) + "\n", "utf-8");
+  }
+  /**
+   * List available JIRA profiles
+   *
+   * @returns Array of profile names
+   */
+  async listJiraProfiles() {
+    const config = await this.loadConfig();
+    if (!config?.sync?.profiles) {
+      return [];
+    }
+    const profiles = config.sync.profiles;
+    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) {
+    const config = await this.loadConfig();
+    if (!config?.sync?.profiles) {
+      return null;
+    }
+    const profileConfig = config.sync.profiles[profileName];
+    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
+   */
+  async loadConfig() {
+    try {
+      const content = await fs.readFile(this.configPath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+}
+async function createJiraProfileResolver(projectRoot = process.cwd()) {
+  return new JiraProfileResolver(projectRoot);
+}
+async function resolveJiraProfile(incrementId, projectRoot = process.cwd()) {
+  const resolver = new JiraProfileResolver(projectRoot);
+  return resolver.resolveProfile(incrementId);
+}
+var jira_profile_resolver_default = JiraProfileResolver;
+export {
+  JiraProfileResolver,
+  createJiraProfileResolver,
+  jira_profile_resolver_default as default,
+  resolveJiraProfile
+};