RELEASING: Releasing 2 package(s)

Releases:
  [email protected]
  @repo/[email protected]

Author: mayank1513

PLUGIN_GUIDE.md

@@ -0,0 +1,113 @@
+# Plugin System Guide
+
+## Overview
+
+The plugin system allows extending git-json-resolver with custom merge strategies while maintaining JSON config compatibility.
+
+## Creating a Plugin
+
+### 1. Plugin Structure
+
+```typescript
+import { StrategyPlugin, StrategyStatus } from "git-json-resolver";
+
+// Augment types for TypeScript support
+declare module "git-json-resolver" {
+  interface PluginStrategies {
+    "my-strategy": string;
+  }
+}
+
+// Individual strategy function (can be imported directly)
+export const myStrategy = ({ ours, theirs, base, path }) => {
+  // Custom logic here
+  return { status: StrategyStatus.OK, value: result };
+};
+
+// Plugin interface for dynamic loading
+const plugin: StrategyPlugin = {
+  strategies: {
+    "my-strategy": myStrategy,
+  },
+  init: async (config) => {
+    // Optional initialization
+  }
+};
+
+export default plugin;
+```
+
+### 2. Publishing
+
+```bash
+npm publish my-git-json-resolver-plugin
+```
+
+## Using Plugins
+
+### Direct Import (Recommended)
+
+```typescript
+import { myStrategy } from "my-plugin";
+import { resolveConflicts } from "git-json-resolver";
+
+await resolveConflicts({
+  customStrategies: {
+    "my-strategy": myStrategy,
+  },
+  rules: {
+    version: ["my-strategy"]
+  }
+});
+```
+
+### Dynamic Loading (JSON Config)
+
+```json
+{
+  "plugins": ["my-plugin"],
+  "pluginConfig": {
+    "my-plugin": {
+      "customOption": "value"
+    }
+  },
+  "rules": {
+    "version": ["my-strategy"]
+  }
+}
+```
+
+### TypeScript Config
+
+```typescript
+// git-json-resolver.config.ts
+import type { Config } from "git-json-resolver";
+
+const config: Config = {
+  plugins: ["my-plugin"],
+  pluginConfig: {
+    "my-plugin": { customOption: "value" }
+  },
+  rules: {
+    version: ["my-strategy"] // TypeScript will know about this strategy
+  }
+};
+
+export default config;
+```
+
+## Plugin Development Best Practices
+
+1. **Naming**: Use descriptive strategy names
+2. **Fallback**: Return `CONTINUE` when strategy doesn't apply
+3. **Validation**: Check input types before processing
+4. **Error Handling**: Return `FAIL` for unrecoverable errors
+5. **Type Safety**: Augment `PluginStrategies` interface
+
+## Example Strategies
+
+- `semantic-version`: Compare semantic versions
+- `timestamp-latest`: Choose most recent timestamp
+- `array-union`: Merge arrays with unique values
+- `file-size-larger`: Choose larger file content
+- `priority-field`: Use priority-based resolution

README.md

@@ -28,6 +28,7 @@ A Git-aware conflict resolver for **JSON-first structured data**.
 - 🔄 **Backup and restore** functionality
 - 📊 **Configurable logging** (memory or file-based)
 - 🔀 **Git merge driver** support for seamless Git integration
+- 🔧 **Plugin system** for custom strategies with JSON config support
 
 ## Installation
 
@@ -114,7 +115,9 @@ await resolveConflicts({
 });
 ```
 
-### Config File (`git-json-resolver.config.js`)
+### Config File
+
+**JavaScript Config (`git-json-resolver.config.js`)**
 
 ```js
 module.exports = {
@@ -151,6 +154,37 @@ module.exports = {
 };
 ```
 
+**JSON Config (`git-json-resolver.config.json`) - ⚠️ Experimental**
+
+```json
+{
+  "$schema": "https://cdn.jsdelivr.net/npm/git-json-resolver@latest/schema/config.schema.json",
+  "defaultStrategy": ["merge", "ours"],
+  "plugins": ["my-plugin"],
+  "pluginConfig": {
+    "my-plugin": {
+      "option": "value"
+    }
+  },
+  "rules": {
+    "package.json": {
+      "version": ["semantic-version", "theirs"],
+      "dependencies": ["ours"]
+    }
+  },
+  "byStrategy": {
+    "ours": ["dependencies.*", "devDependencies.*"],
+    "theirs!": ["version", "name"]
+  }
+}
+```
+
+**⚠️ JSON Config Limitations:**
+- No TypeScript intellisense for plugin strategies
+- Limited validation for custom strategy names
+- No compile-time type checking
+- **Recommended:** Use `.js` or `.ts` config for better developer experience
+
 ## Supported Strategies
 
 - **merge** → deep merge objects/arrays where possible
@@ -217,7 +251,115 @@ All non-JSON formats are converted to JSON → resolved → converted back to or
 - **Glob patterns**: `"dependencies.*"`, `"**.config.**"`
 - **Wildcards**: `"*.json"`, `"src/**/*.config.js"`
 
-### Custom Strategies
+### Plugin System
+
+**For TypeScript/JavaScript configs, you can use either approach:**
+
+#### 1. Direct Import (Recommended)
+
+```ts
+import { strategies } from "my-plugin";
+// or import { semanticVersion, timestampLatest } from "my-plugin";
+import { resolveConflicts } from "git-json-resolver";
+
+await resolveConflicts({
+  customStrategies: {
+    ...strategies,
+    // or "semantic-version": semanticVersion,
+  },
+  rules: {
+    version: ["semantic-version", "theirs"]
+  }
+});
+```
+
+#### 2. Dynamic Loading
+
+```ts
+// Also works in .js/.ts configs
+const config = {
+  plugins: ["my-plugin"],
+  pluginConfig: {
+    "my-plugin": { option: "value" }
+  },
+  rules: {
+    version: ["semantic-version", "theirs"]
+  }
+};
+```
+
+#### 3. JSON Config (Dynamic Loading Only)
+
+```json
+{
+  "plugins": ["my-plugin"],
+  "pluginConfig": {
+    "my-plugin": { "option": "value" }
+  },
+  "rules": {
+    "version": ["semantic-version", "theirs"]
+  }
+}
+```
+
+**⚠️ If plugin doesn't provide global types:**
+
+```ts
+import type { Config } from "git-json-resolver";
+
+const config: Config<AllStrategies | "semantic-version" | "timestamp-latest"> = {
+  // ... your config
+};
+```
+
+**Creating a Plugin**
+
+```ts
+import { StrategyPlugin, StrategyStatus, StrategyFn } from "git-json-resolver";
+
+// Augment types for TypeScript support
+declare module "git-json-resolver" {
+  interface PluginStrategies {
+    "semantic-version": string;
+    "timestamp-latest": string;
+  }
+}
+
+// Individual strategy functions (can be imported directly)
+export const semanticVersion: StrategyFn = ({ ours, theirs }) => {
+  if (isNewerVersion(theirs, ours)) {
+    return { status: StrategyStatus.OK, value: theirs };
+  }
+  return { status: StrategyStatus.CONTINUE };
+};
+
+export const timestampLatest: StrategyFn = ({ ours, theirs }) => {
+  const oursTime = new Date(ours as string).getTime();
+  const theirsTime = new Date(theirs as string).getTime();
+  return {
+    status: StrategyStatus.OK,
+    value: oursTime > theirsTime ? ours : theirs
+  };
+};
+
+// Export strategies object for direct import
+export const strategies = {
+  "semantic-version": semanticVersion,
+  "timestamp-latest": timestampLatest,
+};
+
+// Plugin interface for dynamic loading
+const plugin: StrategyPlugin = {
+  strategies,
+  init: async (config) => {
+    console.log('Plugin initialized with:', config);
+  }
+};
+
+export default plugin;
+```
+
+### Custom Strategies (Inline)
 
 ```ts
 import { StrategyStatus } from "git-json-resolver";
@@ -245,6 +387,10 @@ const config = {
 - **Per-file logs**: Separate log files for each processed file
 - **Debug mode**: Detailed conflict information and strategy traces
 
+## Plugin Development
+
+See [PLUGIN_GUIDE.md](./PLUGIN_GUIDE.md) for detailed plugin development documentation.
+
 ## Contributing
 
 Contributions welcome 🙌

examples/plugin/git-json-resolver.config.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://cdn.jsdelivr.net/npm/git-json-resolver@latest/schema/config.schema.json",
+  "defaultStrategy": ["merge", "ours"],
+  "plugins": ["example-plugin"],
+  "pluginConfig": {
+    "example-plugin": {
+      "semverPreferStable": true,
+      "timestampFormat": "ISO"
+    }
+  },
+  "rules": {
+    "package.json": {
+      "version": ["semantic-version", "theirs"],
+      "dependencies": ["ours"],
+      "scripts": ["merge"]
+    },
+    "*.config.json": {
+      "lastModified": ["timestamp-latest"],
+      "features": ["array-union"]
+    }
+  },
+  "byStrategy": {
+    "ours": ["devDependencies.*", "peerDependencies.*"],
+    "theirs!": ["name", "description"]
+  },
+  "include": ["**/*.json", "**/*.yaml"],
+  "exclude": ["**/node_modules/**", "**/dist/**"],
+  "matcher": "picomatch",
+  "debug": false,
+  "writeConflictSidecar": true,
+  "backupDir": ".merge-backups"
+}

examples/plugin/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@example/plugin",
+  "version": "1.0.0",
+  "description": "A Plugin example",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@repo/typescript-config": "workspace:*",
+    "@types/node": "^24.3.0",
+    "git-json-resolver": "workspace:*",
+    "typescript": "^5.9.2"
+  }
+}