@bloomreach/brxm-upgrade 0.1.1

package/README.md

@@ -0,0 +1,217 @@
+# brXM Upgrade Tool
+
+AI-powered CLI tool for Bloomreach Experience Manager (brXM) version upgrades.
+
+## Overview
+
+The brXM Upgrade Tool simplifies version upgrades by:
+- **Analyzing** your project to understand its structure and customizations
+- **Planning** upgrades based on version-specific manifests
+- **Executing** transformations with AI assistance
+- **Guiding** you through manual steps when needed
+
+## Installation
+
+### Via npx (recommended)
+
+The package is published publicly on npmjs.com — no authentication or registry configuration required. Run from any brXM project directory:
+
+```bash
+npx @bloomreach/brxm-upgrade discover
+npx @bloomreach/brxm-upgrade plan
+```
+
+To force a fresh fetch (bypass npx cache):
+
+```bash
+npx --yes @bloomreach/brxm-upgrade@latest <command>
+```
+
+### MCP Server (Claude Code integration)
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "brxm-upgrade": {
+      "command": "npx",
+      "args": ["-p", "@bloomreach/brxm-upgrade", "brxm-upgrade-mcp"]
+    }
+  }
+}
+```
+
+### From source (development)
+
+```bash
+cd tools/brxm-upgrade
+npm install
+npm run build
+```
+
+## Quick Start
+
+```bash
+# Navigate to your brXM project root
+cd /path/to/your/brxm-project
+
+# Check tool information
+brxm-upgrade info
+
+# Analyze your project
+brxm-upgrade discover
+
+# Generate upgrade plan
+brxm-upgrade plan --to 16.3
+
+# Execute the upgrade
+brxm-upgrade execute
+```
+
+## Configuration
+
+Create a `.brxmrc` file in your project root or home directory:
+
+```yaml
+ai:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  apiKeyEnv: ANTHROPIC_API_KEY
+
+upgrade:
+  source: bundled
+
+output:
+  verbose: false
+  color: true
+  exportPath: ./.brxm-upgrade
+```
+
+See `fixtures/.brxmrc.example.yaml` for a complete example.
+
+## Supported AI Providers
+
+The tool supports multiple AI providers (BYOK - Bring Your Own Key):
+
+| Provider | Environment Variable | Default Model |
+|----------|---------------------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 |
+| OpenAI | `OPENAI_API_KEY` | gpt-4-turbo |
+| Google | `GOOGLE_AI_API_KEY` | gemini-pro |
+
+## Commands
+
+| Command | Description | Status |
+|---------|-------------|--------|
+| `info` | Display tool information | Available |
+| `discover` | Analyze project structure | Available |
+| `plan` | Generate upgrade plan | Available |
+| `execute` | Execute upgrade steps | Available |
+| `log-change` | Create manifest entries | Available |
+| `finalize` | Promote unreleased manifest to versioned release | Available |
+| `export` | Export for manual AI use | Available |
+
+## Release Manifest Generation
+
+The `scripts/generate-release-manifests.sh` script generates upgrade manifests from git history. It can optionally enrich triage and documentation with Jira ticket data (summary, description, labels, comments).
+
+### Jira Enrichment (optional)
+
+Set the following environment variables to enable Jira enrichment:
+
+```bash
+export JIRA_BASE_URL="https://bloomreach.atlassian.net"
+export JIRA_USER="your-email@bloomreach.com"
+export JIRA_API_TOKEN="your-api-token"
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JIRA_BASE_URL` | Yes | Base URL of the Jira instance |
+| `JIRA_API_TOKEN` | Yes | API token ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
+| `JIRA_USER` | For Cloud | Email address for Basic Auth. Omit for Bearer token auth (Data Center PATs). |
+
+If these variables are not set, the script runs without Jira data — using only git context.
+
+### Usage
+
+```bash
+# Full pipeline
+./scripts/generate-release-manifests.sh --from 16.6.0 --to 16.7.0
+
+# Dry run (list JIRA groups only)
+./scripts/generate-release-manifests.sh --from 16.6.0 --to 16.7.0 --dry-run
+
+# Generate change docs without running log-change
+./scripts/generate-release-manifests.sh --from 16.6.0 --to 16.7.0 --skip-log-change
+
+# Verbose mode — save all AI prompts/responses and Jira data
+./scripts/generate-release-manifests.sh --from 16.6.0 --to 16.7.0 --verbose
+```
+
+### Verbose mode
+
+Use `--verbose` (or `-v`) to save the full round-trip data for every ticket to `scripts/output/verbose/`:
+
+| File | Content |
+|------|---------|
+| `CMS-12345.jira.json` | Fetched Jira issue data (summary, description, comments) |
+| `CMS-12345.triage-prompt.txt` | Full prompt sent to Claude for triage |
+| `CMS-12345.triage-response.txt` | Claude's triage response (JSON with decision/reason) |
+| `CMS-12345.doc-prompt.txt` | Full prompt sent to Claude for change doc generation (includes diff) |
+| `CMS-12345.doc-response.txt` | Claude's generated change document (markdown) |
+
+The directory is cleared on each run. Files are already covered by `scripts/output/.gitignore`.
+
+## Publishing
+
+Both the CLI tool and the manifests bundle are published manually. See **[docs/PUBLISHING.md](docs/PUBLISHING.md)** for the full maintainer runbook (prerequisites, step-by-step commands, verification, and rollback for both flows).
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Lint code
+npm run lint
+```
+
+### Running locally from anywhere
+
+To run the tool from any directory without publishing to npm, add one of the following to your shell config (`~/.zshrc` or `~/.bashrc`), then reload with `source ~/.zshrc`.
+
+**Option 1 — built output (recommended):**
+
+Build once with `npm run build`, then point the alias at the compiled entry point:
+
+```bash
+alias brxm-upgrade='node /absolute/path/to/brxm/tools/brxm-upgrade/dist/index.js'
+```
+
+Rebuild after code changes: `cd /absolute/path/to/brxm/tools/brxm-upgrade && npm run build`
+
+**Option 2 — TypeScript source via tsx (no build step):**
+
+Use a shell function so the absolute path to `src/index.ts` is resolved at definition time, not at call time:
+
+```bash
+BRXM_UPGRADE_DIR="/absolute/path/to/brxm/tools/brxm-upgrade"
+brxm-upgrade() { node --import "$BRXM_UPGRADE_DIR/node_modules/tsx/dist/esm/index.mjs" "$BRXM_UPGRADE_DIR/src/index.ts" "$@"; }
+```
+
+> **Note:** A plain `alias` with a relative path like `tsx src/index.ts` will fail when run from a different directory, because the path resolves against the current working directory rather than the tool directory.
+
+## License
+
+Apache-2.0 - See LICENSE file for details.

package/dist/ai/index.d.ts

@@ -0,0 +1,3 @@
+export { createAIClient, getSupportedProviders, isProviderSupported, } from './providers.js';
+export type { AIClient, AIClientFactory, GenerateOptions, GenerateResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/ai/index.js

@@ -0,0 +1,2 @@
+export { createAIClient, getSupportedProviders, isProviderSupported, } from './providers.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/ai/providers.d.ts

@@ -0,0 +1,27 @@
+import type { AIProvider } from '../types/index.js';
+import type { AIClient } from './types.js';
+/**
+ * Get list of supported AI providers.
+ *
+ * @returns Array of supported provider identifiers
+ */
+export declare function getSupportedProviders(): AIProvider[];
+/**
+ * Check if a provider is supported.
+ *
+ * @param provider - Provider identifier to check
+ * @returns True if the provider is supported
+ */
+export declare function isProviderSupported(provider: string): provider is AIProvider;
+/**
+ * Create an AI client for the specified provider.
+ *
+ * @param provider - AI provider identifier
+ * @param model - Model identifier (provider-specific)
+ * @param apiKey - API key for authentication
+ * @param baseUrl - Optional base URL for API proxies or custom endpoints
+ * @returns Configured AI client
+ * @throws Error if provider is not supported
+ */
+export declare function createAIClient(provider: AIProvider, model: string, apiKey: string, baseUrl?: string): AIClient;
+//# sourceMappingURL=providers.d.ts.map

package/dist/ai/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAmC,MAAM,YAAY,CAAC;AAoC5E;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,UAAU,EAAE,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,UAAU,CAE5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,QAAQ,CA6DV"}

package/dist/ai/providers.js

@@ -0,0 +1,105 @@
+import { generateText } from 'ai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+/**
+ * Registry of supported AI providers.
+ * Each entry maps a provider to its SDK factory that accepts apiKey/baseURL configuration.
+ */
+/**
+ * Resolve the Anthropic base URL, ensuring it ends with /v1.
+ * The SDK expects /v1 in the base URL (default: https://api.anthropic.com/v1),
+ * but ANTHROPIC_BASE_URL is commonly set without it (e.g., for LiteLLM proxies).
+ */
+function resolveAnthropicBaseUrl(baseURL) {
+    const url = baseURL ?? process.env['ANTHROPIC_BASE_URL'];
+    if (!url)
+        return undefined;
+    return url.replace(/\/+$/, '').endsWith('/v1') ? url : url.replace(/\/+$/, '') + '/v1';
+}
+const providerRegistry = new Map([
+    ['anthropic', (model, config) => createAnthropic({ apiKey: config.apiKey, baseURL: resolveAnthropicBaseUrl(config.baseURL) })(model)],
+    ['openai', (model, config) => createOpenAI({ apiKey: config.apiKey, baseURL: config.baseURL })(model)],
+    ['google', (model, config) => createGoogleGenerativeAI({ apiKey: config.apiKey, baseURL: config.baseURL })(model)],
+]);
+/**
+ * Get list of supported AI providers.
+ *
+ * @returns Array of supported provider identifiers
+ */
+export function getSupportedProviders() {
+    return Array.from(providerRegistry.keys());
+}
+/**
+ * Check if a provider is supported.
+ *
+ * @param provider - Provider identifier to check
+ * @returns True if the provider is supported
+ */
+export function isProviderSupported(provider) {
+    return providerRegistry.has(provider);
+}
+/**
+ * Create an AI client for the specified provider.
+ *
+ * @param provider - AI provider identifier
+ * @param model - Model identifier (provider-specific)
+ * @param apiKey - API key for authentication
+ * @param baseUrl - Optional base URL for API proxies or custom endpoints
+ * @returns Configured AI client
+ * @throws Error if provider is not supported
+ */
+export function createAIClient(provider, model, apiKey, baseUrl) {
+    if (!isProviderSupported(provider)) {
+        throw new Error(`Unsupported AI provider: ${String(provider)}`);
+    }
+    // Safe to assert: isProviderSupported above guarantees the key exists.
+    const providerFactory = providerRegistry.get(provider);
+    const modelInstance = providerFactory(model, { apiKey, baseURL: baseUrl });
+    const client = {
+        provider,
+        model,
+        isConfigured() {
+            return Boolean(apiKey && apiKey.trim().length > 0);
+        },
+        async generate(prompt, options) {
+            if (!this.isConfigured()) {
+                throw new Error(`AI provider ${provider} is not configured. Missing API key.`);
+            }
+            try {
+                const result = await generateText({
+                    model: modelInstance,
+                    prompt,
+                    maxOutputTokens: options?.maxTokens,
+                    temperature: options?.temperature,
+                    system: options?.system,
+                    ...(options?.stopSequences && { stopSequences: options.stopSequences }),
+                });
+                return {
+                    text: result.text,
+                    usage: result.usage
+                        ? {
+                            inputTokens: result.usage.inputTokens,
+                            outputTokens: result.usage.outputTokens,
+                            totalTokens: result.usage.totalTokens,
+                        }
+                        : undefined,
+                    finishReason: result.finishReason,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                const details = error instanceof Error && 'cause' in error ? ` (cause: ${String(error.cause)})` : '';
+                const body = error != null && typeof error === 'object' && 'responseBody' in error
+                    ? ` | response: ${String(error.responseBody)}`
+                    : '';
+                const status = error != null && typeof error === 'object' && 'statusCode' in error
+                    ? ` | status: ${String(error.statusCode)}`
+                    : '';
+                throw new Error(`AI generation failed: ${message}${status}${body}${details}`);
+            }
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=providers.js.map

package/dist/ai/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/ai/providers.ts"],"names":[],"mappings":"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"}

package/dist/ai/types.d.ts

@@ -0,0 +1,47 @@
+import type { AIProvider } from '../types/index.js';
+/**
+ * Options for AI text generation.
+ */
+export interface GenerateOptions {
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Temperature for randomness (0-1) */
+    temperature?: number;
+    /** System prompt to set context */
+    system?: string;
+    /** Stop sequences to end generation */
+    stopSequences?: string[];
+}
+/**
+ * Result of AI text generation.
+ */
+export interface GenerateResult {
+    /** Generated text */
+    text: string;
+    /** Token usage statistics */
+    usage?: {
+        inputTokens: number | undefined;
+        outputTokens: number | undefined;
+        totalTokens: number | undefined;
+    };
+    /** Finish reason */
+    finishReason?: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other' | 'unknown';
+}
+/**
+ * AI client interface for provider abstraction.
+ */
+export interface AIClient {
+    /** Provider identifier */
+    provider: AIProvider;
+    /** Model being used */
+    model: string;
+    /** Generate text from a prompt */
+    generate: (prompt: string, options?: GenerateOptions) => Promise<GenerateResult>;
+    /** Check if the client is properly configured */
+    isConfigured: () => boolean;
+}
+/**
+ * Factory function type for creating AI clients.
+ */
+export type AIClientFactory = (model: string, apiKey: string, baseUrl?: string) => AIClient;
+//# sourceMappingURL=types.d.ts.map

package/dist/ai/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ai/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,KAAK,CAAC,EAAE;QACN,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;KACjC,CAAC;IACF,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,gBAAgB,GAAG,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACpG;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,QAAQ,EAAE,UAAU,CAAC;IACrB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjF,iDAAiD;IACjD,YAAY,EAAE,MAAM,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC"}

package/dist/ai/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/ai/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/ai/types.ts"],"names":[],"mappings":""}

package/dist/capture/change-scanner.d.ts

@@ -0,0 +1,20 @@
+import type { ChangeDocument, ChangeDocMetadata, AIContextTags } from './types.js';
+/**
+ * Extract metadata (JIRA ticket, date, branch, author) from change document content.
+ */
+export declare function extractMetadata(content: string): ChangeDocMetadata;
+/**
+ * Extract AI Context Tags from the last YAML fenced code block in the content.
+ */
+export declare function extractContextTags(content: string): AIContextTags;
+/**
+ * Parse a single change document file into a structured ChangeDocument.
+ */
+export declare function parseChangeDocument(filePath: string): Promise<ChangeDocument>;
+/**
+ * Scan a directory for Markdown change documents and parse them all.
+ *
+ * @throws Error if the directory does not exist
+ */
+export declare function scanChangeDocuments(changesDir: string): Promise<ChangeDocument[]>;
+//# sourceMappingURL=change-scanner.d.ts.map

package/dist/capture/change-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-scanner.d.ts","sourceRoot":"","sources":["../../src/capture/change-scanner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnF;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAYlE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAqBjE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAWnF;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAWvF"}

package/dist/capture/change-scanner.js

@@ -0,0 +1,71 @@
+import { readdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import yaml from 'js-yaml';
+import { readTextFile, pathExists } from '../utils/index.js';
+/**
+ * Extract metadata (JIRA ticket, date, branch, author) from change document content.
+ */
+export function extractMetadata(content) {
+    const jiraMatch = /\*\*JIRA\*\*:\s*([A-Z]+-\d+)/i.exec(content);
+    const dateMatch = /\*\*Date\*\*:\s*(\d{4}-\d{2}-\d{2})/i.exec(content);
+    const branchMatch = /\*\*Branch\*\*:\s*(.+)/i.exec(content);
+    const authorMatch = /\*\*Author\*\*:\s*(.+)/i.exec(content);
+    return {
+        jiraTicket: jiraMatch?.[1],
+        date: dateMatch?.[1],
+        branch: branchMatch?.[1]?.trim(),
+        author: authorMatch?.[1]?.trim(),
+    };
+}
+/**
+ * Extract AI Context Tags from the last YAML fenced code block in the content.
+ */
+export function extractContextTags(content) {
+    const yamlBlockRegex = /```yaml\n([\s\S]*?)```/g;
+    let lastMatch = null;
+    let match;
+    while ((match = yamlBlockRegex.exec(content)) !== null) {
+        lastMatch = match;
+    }
+    if (!lastMatch?.[1]) {
+        return {};
+    }
+    try {
+        const parsed = yaml.load(lastMatch[1]);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return {};
+        }
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Parse a single change document file into a structured ChangeDocument.
+ */
+export async function parseChangeDocument(filePath) {
+    const content = await readTextFile(filePath);
+    const filename = basename(filePath);
+    return {
+        filename,
+        filePath,
+        metadata: extractMetadata(content),
+        contextTags: extractContextTags(content),
+        content,
+    };
+}
+/**
+ * Scan a directory for Markdown change documents and parse them all.
+ *
+ * @throws Error if the directory does not exist
+ */
+export async function scanChangeDocuments(changesDir) {
+    if (!(await pathExists(changesDir))) {
+        throw new Error(`Changes directory not found: ${changesDir}`);
+    }
+    const files = await readdir(changesDir);
+    const mdFiles = files.filter(f => f.endsWith('.md')).sort();
+    return Promise.all(mdFiles.map((file) => parseChangeDocument(join(changesDir, file))));
+}
+//# sourceMappingURL=change-scanner.js.map

package/dist/capture/change-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-scanner.js","sourceRoot":"","sources":["../../src/capture/change-scanner.ts"],"names":[],"mappings":"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"}

package/dist/capture/conflict-resolver.d.ts

@@ -0,0 +1,21 @@
+import type { ManifestEntry, UpgradeManifest } from '../planning/types.js';
+import type { ConflictCheckResult } from './types.js';
+/**
+ * Check whether a JIRA ticket already has entries in the manifest.
+ *
+ * @param jiraTicket - JIRA ticket identifier (e.g., "CMS-18384"), or undefined
+ * @param manifest - The upgrade manifest to check against
+ * @returns Conflict check result with matching entries
+ */
+export declare function checkConflict(jiraTicket: string | undefined, manifest: UpgradeManifest): ConflictCheckResult;
+/**
+ * Resolve a conflict by either replacing existing entries or adding alongside them.
+ *
+ * @param manifest - The current upgrade manifest
+ * @param newEntry - The new manifest entry to add
+ * @param jiraTicket - The JIRA ticket that has a conflict
+ * @param decision - Whether to replace existing entries or add separately
+ * @returns A new manifest with the conflict resolved
+ */
+export declare function resolveConflict(manifest: UpgradeManifest, newEntry: ManifestEntry, jiraTicket: string, decision: 'replace' | 'add_separate'): UpgradeManifest;
+//# sourceMappingURL=conflict-resolver.d.ts.map

package/dist/capture/conflict-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-resolver.d.ts","sourceRoot":"","sources":["../../src/capture/conflict-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,eAAe,GACxB,mBAAmB,CAarB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,GAAG,cAAc,GACnC,eAAe,CAqBjB"}

package/dist/capture/conflict-resolver.js

@@ -0,0 +1,45 @@
+/**
+ * Check whether a JIRA ticket already has entries in the manifest.
+ *
+ * @param jiraTicket - JIRA ticket identifier (e.g., "CMS-18384"), or undefined
+ * @param manifest - The upgrade manifest to check against
+ * @returns Conflict check result with matching entries
+ */
+export function checkConflict(jiraTicket, manifest) {
+    if (!jiraTicket) {
+        return { hasConflict: false, existingEntries: [] };
+    }
+    const existing = manifest.entries.filter((e) => e.jira_ticket === jiraTicket);
+    return {
+        hasConflict: existing.length > 0,
+        existingEntries: existing,
+    };
+}
+/**
+ * Resolve a conflict by either replacing existing entries or adding alongside them.
+ *
+ * @param manifest - The current upgrade manifest
+ * @param newEntry - The new manifest entry to add
+ * @param jiraTicket - The JIRA ticket that has a conflict
+ * @param decision - Whether to replace existing entries or add separately
+ * @returns A new manifest with the conflict resolved
+ */
+export function resolveConflict(manifest, newEntry, jiraTicket, decision) {
+    if (newEntry.jira_ticket && jiraTicket !== newEntry.jira_ticket) {
+        throw new Error(`Ticket mismatch: resolving for ${jiraTicket} but entry has ${newEntry.jira_ticket}`);
+    }
+    if (decision === 'replace') {
+        return {
+            ...manifest,
+            entries: [
+                ...manifest.entries.filter((e) => e.jira_ticket !== jiraTicket),
+                newEntry,
+            ],
+        };
+    }
+    return {
+        ...manifest,
+        entries: [...manifest.entries, newEntry],
+    };
+}
+//# sourceMappingURL=conflict-resolver.js.map

package/dist/capture/conflict-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-resolver.js","sourceRoot":"","sources":["../../src/capture/conflict-resolver.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,UAA8B,EAC9B,QAAyB;IAEzB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IACrD,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,UAAU,CACpC,CAAC;IAEF,OAAO;QACL,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;QAChC,eAAe,EAAE,QAAQ;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAyB,EACzB,QAAuB,EACvB,UAAkB,EAClB,QAAoC;IAEpC,IAAI,QAAQ,CAAC,WAAW,IAAI,UAAU,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,kCAAkC,UAAU,kBAAkB,QAAQ,CAAC,WAAW,EAAE,CACrF,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO;YACL,GAAG,QAAQ;YACX,OAAO,EAAE;gBACP,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,UAAU,CAAC;gBAC/D,QAAQ;aACT;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,QAAQ;QACX,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;KACzC,CAAC;AACJ,CAAC"}