electron-pinia-sync 1.0.0 → 1.2.0

package/CONTRIBUTING.md

@@ -2,24 +2,52 @@
 
 Thank you for your interest in contributing! This guide will help you get started with local development.
 
+> 🚀 **New to contributing?** Check out our [Quick Start Guide](.github/CONTRIBUTING-QUICK-START.md) for a condensed version!
+
+**Important for External Contributors:**
+- The `main` branch is protected - you cannot push directly to it
+- All contributions must go through Pull Requests
+- All CI checks must pass before a PR can be merged
+- Use [Conventional Commits](https://www.conventionalcommits.org/) format for all commits
+- CHANGELOG.md is auto-generated - do not edit it manually
+
+## Quick Start for Contributors
+
+1. **Fork** the repository on GitHub
+2. **Clone** your fork locally
+3. **Create a feature branch** from `develop` (or `main`)
+4. **Make your changes** and commit using conventional commit format
+5. **Push** to your fork
+6. **Open a Pull Request** to the original repository
+
 ## Development Setup
 
 ### Prerequisites
 
-- Node.js >= 18.0.0
-- npm (recommended) or npm/yarn
+- Node.js >= 22.14.0
+- npm >= 10.x
 - Git
 
 ### Initial Setup
 
-1. **Fork and Clone**
+1. **Fork the Repository**
+
+Visit [https://github.com/simpli-fyi/electron-pinia-sync](https://github.com/simpli-fyi/electron-pinia-sync) and click the "Fork" button.
+
+2. **Clone Your Fork**
 
 ```bash
-git clone https://github.com/simpli-fyi/electron-pinia-sync.git
+git clone https://github.com/YOUR_USERNAME/electron-pinia-sync.git
 cd electron-pinia-sync
 ```
 
-2. **Install Dependencies**
+3. **Add Upstream Remote**
+
+```bash
+git remote add upstream https://github.com/simpli-fyi/electron-pinia-sync.git
+```
+
+4. **Install Dependencies**
 
 ```bash
 npm install
@@ -61,13 +89,6 @@ Build all modules:
 npm run build
 ```
 
-Build specific modules:
-
-```bash
-npm run build:main
-npm run build:renderer
-npm run build:preload
-```
 
 Watch mode for development:
 
@@ -212,29 +233,72 @@ export function createMainSync(options?: MainSyncOptions): MainSync {
 
 ### Before Submitting
 
-1. **Create a feature branch**
+1. **Sync Your Fork** (important!)
+
+```bash
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+2. **Create a Feature Branch**
 
 ```bash
 git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
 ```
 
-2. **Make your changes**
+3. **Make Your Changes**
    - Write code
    - Add/update tests
-   - Update documentation
+   - Update documentation (README.md if API changes)
+   - Use conventional commit format (see below)
 
-3. **Run quality checks**
+4. **Run Quality Checks**
 
 ```bash
-npm run typecheck
-npm run lint
-npm test
+npm run typecheck  # Must pass
+npm run lint       # Must pass (use lint:fix for auto-fixes)
+npm test           # Must pass
+npm run build      # Must succeed
 ```
 
-4. **Build the project**
+5. **Commit Your Changes**
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
 
 ```bash
-npm run build
+git add .
+git commit -m "feat: add support for encrypted storage"
+# or
+git commit -m "fix: prevent race condition during initialization"
+```
+
+6. **Push to Your Fork**
+
+```bash
+git push origin feature/your-feature-name
+```
+
+7. **Create Pull Request**
+
+- Go to your fork on GitHub
+- Click "New Pull Request"
+- Select your feature branch
+- Fill out the PR template
+- Click "Create Pull Request"
+
+### Keeping Your Fork Updated
+
+Before starting new work, always sync with upstream:
+
+```bash
+git checkout main
+git fetch upstream
+git merge upstream/main
+git push origin main
 ```
 
 ### PR Guidelines
@@ -339,7 +403,7 @@ All public APIs should have JSDoc comments:
  * mainSync.registerStore('counter', counterStore, {
  *   persist: true
  * });
- * ```
+ * 
  */
 public registerStore(
   storeId: string,
@@ -350,22 +414,139 @@ public registerStore(
 }
 ```
 
-## Release Process
+## Commit Message Convention
 
-(For maintainers)
+This project uses **Conventional Commits**. This is crucial because our release process is fully automated. The type of commit determines how the version number is bumped:
 
-1. Update version in `package.json`
-2. Update CHANGELOG.md
-3. Create a git tag
-4. Push to GitHub
-5. Publish to npm
+* **`fix:`** Bumps the **patch** version (e.g., `1.0.0` -> `1.0.1`).
+* **`feat:`** Bumps the **minor** version (e.g., `1.0.0` -> `1.1.0`).
+* **`feat!:`** or **`BREAKING CHANGE:`** Bumps the **major** version (e.g., `1.0.0` -> `2.0.0`).
+* **`chore:`, `docs:`, `style:`, `refactor:`, `test:**` Do not trigger a new release.
 
+> **Note:** Always use lowercase for the type. Scope is optional but recommended (e.g., `feat(main): ...`).
+
+---
+
+## GitHub Workflows
+
+This project uses several automated workflows to ensure code quality and streamline releases. Understanding these workflows helps you contribute effectively.
+
+### For Contributors
+
+When you submit a Pull Request, the following automated checks will run:
+
+#### 1. **CI Workflow** (`.github/workflows/ci.yml`)
+Runs on every push and PR to `main` and `develop` branches.
+
+**What it does:**
+- Tests on Node.js 22.x and 24.x
+- Runs TypeScript type checking
+- Runs ESLint
+- Runs unit tests
+- Builds the package
+
+**How to fix failures:**
+```bash
+npm run typecheck  # Fix TypeScript errors
+npm run lint:fix   # Fix linting issues
+npm test           # Fix test failures
+npm run build      # Fix build issues
+```
+
+#### 2. **E2E Tests Workflow** (`.github/workflows/e2e.yml`)
+Runs end-to-end tests on Ubuntu, macOS, and Windows.
+
+**What it does:**
+- Builds the library
+- Installs Playwright
+- Runs E2E tests across different operating systems
+
+**How to run locally:**
 ```bash
-npm version patch|minor|major
-git push --follow-tags
-npm publish
+npm run build
+npm run test:e2e
 ```
 
+### Branch Protection
+
+The `main` branch is protected and requires:
+- ✅ All CI checks to pass
+- ✅ At least one maintainer approval
+- ✅ Up-to-date with base branch
+- ✅ No direct pushes (must use Pull Requests)
+
+**Important:** You cannot push directly to `main`. Always work in a feature branch and create a Pull Request.
+
+## Release Process
+
+(For maintainers)
+
+We use **Semantic Release** to fully automate versioning and publishing. The process is **commit-based** - no manual version changes needed!
+
+### How it works
+
+1. **Merge to Main**: Once a Pull Request is merged into the `main` branch, a GitHub Action is triggered.
+2. **Semantic Release** (`.github/workflows/prepare-release.yml`):
+   - Analyzes all new commits since the last release
+   - Determines the next version based on commit types
+   - Generates CHANGELOG.md content
+   - Creates a Git tag (e.g., `v1.1.0`)
+   - Creates a GitHub Release with release notes
+   - **Note**: Does NOT commit back to `main` (respects branch protection)
+3. **NPM Publish** (`.github/workflows/publish.yml`):
+   - Triggered when a new GitHub Release is created
+   - Updates package.json version
+   - Runs all tests and quality checks
+   - Publishes to NPM with provenance
+   - Requires `NPM_TOKEN` secret
+
+### Version Bumping Rules
+
+The commit type determines the version bump:
+- **`fix:`** → Patch version (1.0.0 → 1.0.1)
+- **`feat:`** → Minor version (1.0.0 → 1.1.0)
+- **`feat!:`** or **`BREAKING CHANGE:`** → Major version (1.0.0 → 2.0.0)
+- **`chore:`, `docs:`, `style:`, `refactor:`, `test:`** → No release
+
+### Important: Branch Protection Compatible
+
+Our Semantic Release setup is **compatible with branch protection**:
+- ✅ Creates GitHub Releases directly (no commit to main needed)
+- ✅ Tag is created by GitHub (not pushed to main)
+- ✅ CHANGELOG is generated in the release notes
+- ✅ package.json version is updated during NPM publish workflow (not in repo)
+
+**Version Management:**
+- The `package.json` in the main branch stays at the initial version (e.g., 1.0.0)
+- The **actual version** is managed via Git Tags (e.g., v1.1.0)
+- The NPM package will have the correct version from the Git Tag
+- This is intentional to avoid Branch Protection conflicts
+
+**To find the current version:**
+- Check Git Tags: `git fetch --tags && git tag -l`
+- Check GitHub Releases: https://github.com/simpli-fyi/electron-pinia-sync/releases
+- Check NPM: `npm view electron-pinia-sync version`
+
+See `.github/RELEASE-WORKFLOW-EXPLAINED.md` for detailed information.
+
+**Skip a release:**
+Include `[skip ci]` in your merge commit message.
+
+**Manual release (emergency only):**
+Semantic Release runs automatically. Manual releases should only be done if the automation fails.
+
+**Check release status:**
+- View releases: https://github.com/simpli-fyi/electron-pinia-sync/releases
+- View workflow runs: https://github.com/simpli-fyi/electron-pinia-sync/actions
+
+### Dependabot
+
+Dependabot automatically creates PRs for dependency updates:
+- **npm packages:** Weekly (Mondays)
+- **GitHub Actions:** Monthly
+- Dependencies are grouped (dev vs core) for easier review
+- Security updates are created immediately
+
 ## Getting Help
 
 - **Issues**: Open an issue for bugs or feature requests
@@ -399,7 +580,7 @@ Feel free to reach out:
 
 - Open an issue
 - Start a discussion
-- Email: [your-email@example.com]
+- Email: [hello@simpli.fyi]
 
 Thank you for contributing! 🎉
 

package/README.md

@@ -13,7 +13,7 @@
 - 🔒 **Type-Safe**: Full TypeScript support with strict mode
 - 🚀 **Zero Config**: Works out of the box with sensible defaults
 - 🔁 **Echo Prevention**: Intelligent transaction tracking prevents infinite loops
-- 📦 **ESM-Only**: Modern ES Modules build (~4 KB per module)
+- 📦 **Dual Package**: ESM and CommonJS builds (~4 KB per module)
 - ⚡ **Performance**: Efficient diffing with `microdiff` minimizes data transfer
 
 ## Installation
@@ -35,10 +35,10 @@ npm install electron pinia vue
 ```
 
 **Required versions**:
-- Electron >= 28
+- Electron >= 40
 - Pinia >= 3.0
 - Vue >= 3.5
-- Node.js >= 20
+- Node.js >= 22.14
 
 **Why?** This keeps the bundle size small and prevents dependency conflicts. You use your own versions of Electron and Pinia.
 
@@ -402,8 +402,6 @@ pinia.use(createRendererSync({
 - `true`: Important operations
 - `'verbose'`: Detailed logs with state diffs
 
-For advanced debugging, see [DEBUG.md](./DEBUG.md).
-
 ## Troubleshooting
 
 ### Store not syncing

package/dist/main/index.cjs

@@ -0,0 +1,266 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/main/index.ts
+var main_exports = {};
+__export(main_exports, {
+  MainSync: () => MainSync,
+  createDebugLogger: () => createDebugLogger,
+  createMainSync: () => createMainSync,
+  formatPatchForDebug: () => formatPatchForDebug,
+  formatStateForDebug: () => formatStateForDebug
+});
+module.exports = __toCommonJS(main_exports);
+var import_electron = require("electron");
+var import_pinia = require("pinia");
+var import_electron_store = __toESM(require("electron-store"), 1);
+
+// src/types.ts
+var IPC_CHANNELS = {
+  /** Renderer requests initial state from Main */
+  STATE_PULL: "pinia-sync:state-pull",
+  /** Renderer sends patch to Main */
+  STATE_PATCH: "pinia-sync:state-patch",
+  /** Main broadcasts state update to all Renderers */
+  STATE_UPDATED: "pinia-sync:state-updated",
+  /** Renderer requests full state sync */
+  STATE_SYNC: "pinia-sync:state-sync"
+};
+
+// src/debug.ts
+function createDebugLogger(namespace, debugLevel = false, customLogger) {
+  const isEnabled = debugLevel !== false;
+  const isVerbose = debugLevel === "verbose" || debugLevel === true;
+  const prefix = `[${namespace}]`;
+  const noop = () => {
+  };
+  const logger = customLogger || console;
+  return {
+    log: logger.log?.bind(logger, prefix) || console.log.bind(console, prefix),
+    warn: logger.warn?.bind(logger, prefix) || console.warn.bind(console, prefix),
+    error: logger.error?.bind(logger, prefix) || console.error.bind(console, prefix),
+    debug: isEnabled ? logger.log?.bind(logger, prefix) || console.log.bind(console, prefix) : noop,
+    verbose: isVerbose ? logger.log?.bind(logger, `${prefix}[VERBOSE]`) || console.log.bind(console, `${prefix}[VERBOSE]`) : noop
+  };
+}
+function formatStateForDebug(state, maxLength = 200) {
+  try {
+    const json = JSON.stringify(state);
+    if (json.length > maxLength) {
+      return json.substring(0, maxLength) + `... (${json.length} chars total)`;
+    }
+    return json;
+  } catch {
+    return "[Circular or non-serializable]";
+  }
+}
+function formatPatchForDebug(patch) {
+  try {
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+      return "{}";
+    }
+    if (keys.length > 5) {
+      return `{ ${keys.slice(0, 5).join(", ")}, ... (${keys.length} keys) }`;
+    }
+    return JSON.stringify(patch, null, 2);
+  } catch {
+    return "[Invalid patch]";
+  }
+}
+
+// src/utils/toRawState.ts
+function toRawState(state) {
+  return JSON.parse(JSON.stringify(state));
+}
+
+// src/main/index.ts
+var MainSync = class {
+  pinia;
+  electronStore;
+  storeMetadata = /* @__PURE__ */ new Map();
+  processingTransactions = /* @__PURE__ */ new Set();
+  MAX_TRANSACTION_HISTORY = 100;
+  debug;
+  constructor(options = {}) {
+    this.debug = createDebugLogger("electron-pinia-sync:main", options.debug ?? false, options.logger);
+    this.debug.debug("Initializing MainSync");
+    this.pinia = options.pinia ?? (0, import_pinia.createPinia)();
+    this.electronStore = new import_electron_store.default({
+      name: "pinia-sync-store",
+      ...options.storeOptions
+    });
+    this.debug.verbose("electron-store initialized with options:", options.storeOptions);
+    this.setupIpcHandlers();
+    this.debug.debug("MainSync initialized successfully");
+  }
+  /**
+   * Get the Pinia instance managed by this sync manager
+   */
+  getPinia() {
+    return this.pinia;
+  }
+  /**
+   * Register a store with the sync manager
+   */
+  registerStore(storeId, store, options = {}) {
+    this.debug.debug(`Registering store: ${storeId}`);
+    const persistConfig = this.normalizePersistOptions(options.persist);
+    this.storeMetadata.set(storeId, {
+      persist: persistConfig
+    });
+    if (persistConfig) {
+      const key = persistConfig.key ?? storeId;
+      const persistedState = this.electronStore.get(key);
+      if (persistedState) {
+        this.debug.verbose(`Loading persisted state for ${storeId}:`, formatStateForDebug(persistedState));
+        store.$patch(persistedState);
+      } else {
+        this.debug.verbose(`No persisted state found for ${storeId}`);
+      }
+    }
+    store.$subscribe((_mutation, state) => {
+      this.debug.verbose(`Store ${storeId} changed:`, formatStateForDebug(state));
+      const serializedState = toRawState(state);
+      if (persistConfig) {
+        const key = persistConfig.key ?? storeId;
+        this.electronStore.set(key, serializedState);
+        this.debug.verbose(`Persisted state for ${storeId} to key: ${key}`);
+      }
+      this.broadcastStateUpdate(storeId, serializedState);
+    }, { detached: true });
+    this.debug.debug(`Store ${storeId} registered successfully (persist: ${!!persistConfig})`);
+  }
+  /**
+   * Normalize persist options to standard format
+   */
+  normalizePersistOptions(persist) {
+    if (persist === true) {
+      return { enabled: true };
+    } else if (persist === false || persist === void 0) {
+      return false;
+    } else {
+      return persist;
+    }
+  }
+  /**
+   * Setup IPC handlers for communication with renderers
+   */
+  setupIpcHandlers() {
+    this.debug.debug("Setting up IPC handlers");
+    import_electron.ipcMain.handle(
+      IPC_CHANNELS.STATE_PULL,
+      async (_event, request) => {
+        this.debug.debug(`IPC handler called: STATE_PULL for store: ${request.storeId}`);
+        const store = this.pinia._s.get(request.storeId);
+        if (store) {
+          this.debug.verbose(`Sending state for ${request.storeId}:`, formatStateForDebug(store.$state));
+        } else {
+          this.debug.warn(`Store "${request.storeId}" not found in Main process`);
+        }
+        return {
+          storeId: request.storeId,
+          state: store ? toRawState(store.$state) : null
+        };
+      }
+    );
+    this.debug.debug(`IPC handler registered: ${IPC_CHANNELS.STATE_PULL}`);
+    import_electron.ipcMain.handle(
+      IPC_CHANNELS.STATE_PATCH,
+      async (_event, message) => {
+        this.debug.debug(`IPC handler called: STATE_PATCH for store: ${message.storeId}, transaction: ${message.transactionId}`);
+        this.debug.verbose(`Patch data:`, formatPatchForDebug(message.patch));
+        const store = this.pinia._s.get(message.storeId);
+        if (!store) {
+          this.debug.warn(`Store "${message.storeId}" not found in Main process`);
+          return;
+        }
+        this.addTransaction(message.transactionId);
+        try {
+          store.$patch(message.patch);
+          this.debug.debug(`Successfully applied patch to store: ${message.storeId}`);
+        } catch (error) {
+          this.debug.error(`Failed to patch store "${message.storeId}":`, error);
+        }
+      }
+    );
+    this.debug.debug(`IPC handler registered: ${IPC_CHANNELS.STATE_PATCH}`);
+    this.debug.debug("IPC handlers setup complete");
+  }
+  addTransaction(id) {
+    this.processingTransactions.add(id);
+    if (this.processingTransactions.size > this.MAX_TRANSACTION_HISTORY) {
+      const first = this.processingTransactions.values().next().value;
+      if (first) this.processingTransactions.delete(first);
+    }
+    setTimeout(() => this.processingTransactions.delete(id), 5e3);
+  }
+  /**
+   * Broadcast state update to all renderer processes
+   */
+  broadcastStateUpdate(storeId, state, transactionId) {
+    this.debug.verbose(`Broadcasting state update for store: ${storeId}`, transactionId ? `(transaction: ${transactionId})` : "");
+    const message = {
+      storeId,
+      state,
+      transactionId
+    };
+    const windows = import_electron.BrowserWindow.getAllWindows();
+    this.debug.verbose(`Broadcasting to ${windows.length} window(s)`);
+    windows.forEach((window, index) => {
+      if (!window.isDestroyed()) {
+        this.debug.verbose(`Sending ${IPC_CHANNELS.STATE_UPDATED} to window ${index + 1}`);
+        window.webContents.send(IPC_CHANNELS.STATE_UPDATED, message);
+      } else {
+        this.debug.verbose(`Skipping destroyed window ${index + 1}`);
+      }
+    });
+    this.debug.debug(`Broadcast complete for store: ${storeId}`);
+  }
+  /**
+   * Cleanup IPC handlers
+   */
+  destroy() {
+    this.debug.debug("Destroying MainSync, cleaning up IPC handlers");
+    import_electron.ipcMain.removeHandler(IPC_CHANNELS.STATE_PULL);
+    import_electron.ipcMain.removeHandler(IPC_CHANNELS.STATE_PATCH);
+    this.debug.debug("MainSync destroyed");
+  }
+};
+function createMainSync(options) {
+  return new MainSync(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MainSync,
+  createDebugLogger,
+  createMainSync,
+  formatPatchForDebug,
+  formatStateForDebug
+});