permachine 0.2.0 → 0.3.0

package/README.md

@@ -77,6 +77,20 @@ EXAMPLES:
 
 ### File Naming Convention
 
+**New Advanced Syntax (Recommended):**
+
+Filter-based syntax for precise control:
+
+| Purpose               | Filename                      | In Git?            |
+| --------------------- | ----------------------------- | ------------------ |
+| Base config (shared)  | `config.base.json`            | ✅ Yes             |
+| OS-specific           | `config.{os=windows}.json`    | ✅ Yes             |
+| Machine-specific      | `config.{machine=laptop}.json`| ✅ Yes             |
+| Multi-filter          | `secrets.{machine=laptop}{user=josxa}.json` | ✅ Yes |
+| Final output (merged) | `config.json`                 | ❌ No (gitignored) |
+
+**Legacy Syntax (Still Supported):**
+
 Given machine name `my-laptop` (auto-detected from hostname):
 
 | Purpose               | Filename                | In Git?            |
@@ -85,13 +99,25 @@ Given machine name `my-laptop` (auto-detected from hostname):
 | Machine-specific      | `config.my-laptop.json` | ✅ Yes             |
 | Final output (merged) | `config.json`           | ❌ No (gitignored) |
 
+**Supported Filters:**
+
+- `{os=windows}`, `{os=macos}`, `{os=linux}` - Operating system
+- `{arch=x64}`, `{arch=arm64}` - CPU architecture  
+- `{machine=hostname}` - Machine/hostname (same as legacy)
+- `{user=username}` - Username
+- `{env=prod}`, `{env=dev}` - Environment (from NODE_ENV)
+- Multiple filters: `{os=windows}{arch=x64}` (AND logic)
+- OR logic: `{os=windows,macos,linux}` (comma-separated)
+
+**📚 See [File Filters Documentation](docs/FILE_FILTERS.md) for complete guide and examples.**
+
 Same pattern works for `.env` files:
 
-| Purpose          | Filename         | In Git?            |
-| ---------------- | ---------------- | ------------------ |
-| Base config      | `.env.base`      | ✅ Yes             |
-| Machine-specific | `.env.my-laptop` | ✅ Yes             |
-| Final output     | `.env`           | ❌ No (gitignored) |
+| Purpose          | Filename                   | In Git?            |
+| ---------------- | -------------------------- | ------------------ |
+| Base config      | `.env.base`                | ✅ Yes             |
+| Machine-specific | `.env.{machine=laptop}`    | ✅ Yes             |
+| Final output     | `.env`                     | ❌ No (gitignored) |
 
 ### Basic Commands
 
@@ -186,12 +212,13 @@ Different settings for work laptop vs home desktop:
   └── settings.json              # ← Merged output (gitignored)
 ```
 
-**setup.base.json:**
+**settings.base.json:**
 
 ```json
 {
   "editor.fontSize": 14,
-  "workbench.colorTheme": "Dark+"
+  "workbench.colorTheme": "Dark+",
+  "terminal.integrated.shell.windows": "powershell.exe"
 }
 ```
 
@@ -200,34 +227,92 @@ Different settings for work laptop vs home desktop:
 ```json
 {
   "http.proxy": "http://proxy.company.com:8080",
-  "terminal.integrated.cwd": "C:/Projects"
+  "terminal.integrated.cwd": "C:/Projects/Work"
 }
 ```
 
-### Recipe 2: Environment Variables
+**settings.desktop.json:**
 
-Different database credentials per environment:
+```json
+{
+  "terminal.integrated.cwd": "C:/Code/Personal",
+  "git.path": "C:/Program Files/Git/bin/git.exe"
+}
+```
+
+### Recipe 2: OpenCode Config (AI Assistant)
+
+[OpenCode](https://opencode.ai) supports machine-specific MCP servers and model preferences:
 
 ```bash
-# .env.base (shared defaults)
-NODE_ENV=development
-LOG_LEVEL=info
-API_PORT=3000
+~/.config/opencode/
+  ├── config.base.json         # Shared: agents, themes, keybinds
+  ├── config.worklaptop.json   # Work: Google Sheets MCP
+  ├── config.homezone.json     # Home: Telegram MCP, local paths
+  └── config.json              # ← Merged output (gitignored)
+```
 
-# .env.laptop (local dev)
-DATABASE_URL=postgresql://localhost:5432/myapp_dev
-API_KEY=dev_key_123
+**config.base.json:**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "theme": "nightowl-transparent",
+  "keybinds": {
+    "input_newline": "shift+return"
+  },
+  "mcp": {
+    "perplexity-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": ["uvx", "perplexity-mcp"]
+    }
+  }
+}
+```
+
+**config.homezone.json:**
+
+```json
+{
+  "mcp": {
+    "telegram-mcp": {
+      "enabled": true,
+      "type": "local",
+      "command": ["uv", "--directory", "D:\\git\\telegram-mcp", "run", "main.py"]
+    },
+    "google-sheets": {
+      "enabled": true,
+      "environment": {
+        "SERVICE_ACCOUNT_PATH": "C:/Users/josch/.config/opencode/secrets/service-account.json"
+      }
+    }
+  }
+}
+```
 
-# .env.prodserver (production)
-DATABASE_URL=postgresql://prod.db.com:5432/myapp
-API_KEY=prod_key_xyz
+**config.worklaptop.json:**
 
-# .env ← Merged output (gitignored)
+```json
+{
+  "mcp": {
+    "telegram-mcp": {
+      "enabled": false
+    },
+    "google-sheets": {
+      "enabled": true,
+      "environment": {
+        "SERVICE_ACCOUNT_PATH": "/work/credentials/google-service-account.json",
+        "DRIVE_FOLDER_ID": "work-folder-id-123"
+      }
+    }
+  }
+}
 ```
 
-### Recipe 3: Package.json Scripts
+### Recipe 3: Package.json Scripts (Platform-Specific)
 
-Different build scripts for different machines:
+Different scripts for macOS vs Windows development:
 
 ```bash
 # package.base.json
@@ -235,127 +320,167 @@ Different build scripts for different machines:
   "name": "my-app",
   "version": "1.0.0",
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "lint": "eslint src/"
   },
   "dependencies": {
     "express": "^4.18.0"
   }
 }
 
-# package.laptop.json (local development)
+# package.macos.json
 {
   "scripts": {
-    "dev": "nodemon src/index.js",
-    "build": "webpack --mode development"
+    "dev": "NODE_ENV=development nodemon src/index.js",
+    "build": "rm -rf dist && webpack",
+    "open": "open http://localhost:3000"
   }
 }
 
-# package.buildserver.json (CI/CD)
+# package.windows.json
 {
   "scripts": {
-    "build": "webpack --mode production",
-    "deploy": "aws s3 sync dist/ s3://my-bucket"
+    "dev": "set NODE_ENV=development && nodemon src/index.js",
+    "build": "rmdir /s /q dist && webpack",
+    "open": "start http://localhost:3000"
   }
 }
 
 # package.json ← Merged output
-# Each machine gets appropriate scripts!
+# Each OS gets appropriate shell commands!
 ```
 
-### Recipe 4: Database Configuration
+### Recipe 4: Git Config
 
-Multi-environment database setup:
+Personal vs work Git settings:
 
 ```bash
-# config/database.base.json
-{
-  "pool": {
-    "min": 2,
-    "max": 10
-  },
-  "migrations": {
-    "directory": "./migrations"
-  }
-}
+# .gitconfig.base
+[core]
+  editor = code --wait
+  autocrlf = true
+[pull]
+  rebase = true
+[init]
+  defaultBranch = main
+
+# .gitconfig.worklaptop
+[user]
+  name = John Doe
+  email = john.doe@company.com
+[url "https://"]
+  insteadOf = git://
+[http]
+  proxy = http://proxy.company.com:8080
+
+# .gitconfig.homezone
+[user]
+  name = JohnD
+  email = johndoe@personal.com
+[github]
+  user = johnd-personal
+```
 
-# config/database.laptop.json
-{
-  "connection": {
-    "host": "localhost",
-    "port": 5432,
-    "database": "myapp_dev",
-    "user": "dev",
-    "password": "dev123"
-  }
-}
+### Recipe 5: Multi-File Dotfiles
 
-# config/database.prodserver.json
-{
-  "connection": {
-    "host": "db.production.com",
-    "port": 5432,
-    "database": "myapp_production",
-    "user": "produser",
-    "password": "secure_password_from_vault"
-  },
-  "pool": {
-    "min": 10,
-    "max": 50
-  }
-}
+Complete dotfiles setup across machines:
+
+```bash
+~/.config/
+├── nvim/
+│   ├── init.base.vim        # Shared vim config
+│   ├── init.worklaptop.vim  # Work-specific plugins
+│   ├── init.homezone.vim    # Personal plugins
+│   └── init.vim             # ← Merged
+├── alacritty/
+│   ├── alacritty.base.yml   # Shared terminal config
+│   ├── alacritty.macos.yml  # macOS font paths
+│   ├── alacritty.windows.yml # Windows font paths
+│   └── alacritty.yml        # ← Merged
+├── opencode/
+│   ├── config.base.json
+│   ├── config.worklaptop.json
+│   └── config.json          # ← Merged
+└── .env.base
+    .env.worklaptop
+    .env                     # ← Merged
+
+# After `permachine init`, sync your dotfiles repo across machines!
+# Each machine automatically gets the right config.
 ```
 
-### Recipe 5: Multi-File Projects
+### Recipe 6: Advanced Filters - Cross-Platform Development
 
-Complex projects with multiple config files:
+**NEW**: Use the advanced filter syntax for precise control:
 
 ```bash
+# Project structure
 project/
-├── config.base.json
-├── config.laptop.json
-├── settings/
-│   ├── app.base.json
-│   ├── app.laptop.json
-│   ├── database.base.json
-│   └── database.laptop.json
-├── .env.base
-└── .env.laptop
-
-# After `permachine init`, all files auto-merge:
-# - config.json
-# - settings/app.json
-# - settings/database.json
-# - .env
+├── config.base.json                    # Shared config
+├── config.{os=windows}.json            # Windows-specific paths
+├── config.{os=macos}.json              # macOS-specific paths
+├── config.{os=linux}.json              # Linux-specific paths
+├── secrets.{machine=work}{user=alice}.json   # Alice's work secrets
+├── secrets.{machine=home}{user=alice}.json   # Alice's home secrets
+├── build.{os=windows}{arch=x64}.json   # Windows x64 build config
+├── build.{os=windows}{arch=arm64}.json # Windows ARM build config
+└── config.json                         # ← Merged (gitignored)
 ```
 
+**Example use cases:**
+
+```bash
+# Multiple platforms with OR logic
+package.{os=windows,macos}.json   # Matches Windows OR macOS
+
+# Specific environment AND machine
+secrets.{env=prod}{machine=server-us-east}.json
+
+# User-specific on specific machine
+.vscode/settings.{machine=laptop}{user=josxa}.json
+
+# Multiple users on shared machine
+preferences.{user=alice}.json
+preferences.{user=bob}.json
+```
+
+**See [File Filters Documentation](docs/FILE_FILTERS.md) for complete guide and examples.**
+
 ## How It Works
 
-`permachine` uses a simple three-step process:
+`permachine` uses a simple process:
 
-1. **Machine Detection** - Automatically detects your machine name from hostname (Windows: `COMPUTERNAME`, Linux/Mac: `hostname()`)
+1. **Machine Detection** - Automatically detects your machine name from hostname (Windows: `COMPUTERNAME`, Linux/Mac: `hostname()`) and other system properties (OS, architecture, username, environment)
 
-2. **File Discovery** - Scans your repository for files matching the pattern `*.{machine}.*` (e.g., `config.laptop.json`, `.env.desktop`)
+2. **File Discovery** - Scans your repository for files matching patterns:
+   - **New**: `{key=value}` syntax (e.g., `config.{os=windows}.json`, `secrets.{machine=laptop}{user=josxa}.json`)
+   - **Legacy**: `*.{machine}.*` syntax (e.g., `config.laptop.json`, `.env.desktop`)
 
-3. **Smart Merging** - Merges base and machine-specific configs:
+3. **Filter Matching** - For new syntax, evaluates filters against current system context:
+   - AND logic: ALL filters must match (e.g., `{os=windows}{arch=x64}`)
+   - OR logic: ANY value in list matches (e.g., `{os=windows,macos}`)
 
+4. **Smart Merging** - Merges base and machine-specific configs:
    - **JSON**: Deep recursive merge (machine values override base)
    - **ENV**: Key-value merge with comment preservation
 
-4. **Gitignore Management** - Automatically adds output files to `.gitignore` and removes already-tracked files from git
+5. **Gitignore Management** - Automatically adds output files to `.gitignore` and removes already-tracked files from git
 
-5. **Git Hooks** - Installs hooks to auto-merge on checkout, merge, and commit operations
+6. **Git Hooks** - Installs hooks to auto-merge on checkout, merge, and commit operations
 
-For detailed implementation information, see [CONTRIBUTING.md](CONTRIBUTING.md).
+For detailed implementation information, see [CONTRIBUTING.md](CONTRIBUTING.md) and [File Filters Documentation](docs/FILE_FILTERS.md).
 
 ## Supported File Types
 
-| Type  | Extensions            | Merge Strategy                    | Status       |
-| ----- | --------------------- | --------------------------------- | ------------ |
-| JSON  | `.json`               | Deep recursive merge              | ✅ Supported |
-| JSONC | `.json` with comments | Deep merge + comment preservation | ✅ Supported |
-| ENV   | `.env`, `.env.*`      | Key-value override                | ✅ Supported |
-| YAML  | `.yaml`, `.yml`       | Deep recursive merge              | 🔜 Planned   |
-| TOML  | `.toml`               | Deep recursive merge              | 🔜 Planned   |
+| Type     | Extensions            | Merge Strategy                    | Status                                         |
+| -------- | --------------------- | --------------------------------- | ---------------------------------------------- |
+| JSON     | `.json`               | Deep recursive merge              | ✅ Supported                                   |
+| JSONC    | `.json` with comments | Deep merge + comment preservation | ✅ Supported                                   |
+| ENV      | `.env`, `.env.*`      | Key-value upsert                  | ✅ Supported                                   |
+| Markdown | `.md`                 | Append (base + machine)           | 🔜 [Planned](#3)                               |
+| YAML     | `.yaml`, `.yml`       | Deep recursive merge              | 🔜 [Planned](#1)                               |
+| TOML     | `.toml`               | Deep recursive merge              | 🔜 [Planned](#2)                               |
+| Patch    | `.patch`              | Apply git-style patch to base     | 💡 [Proposed](#4) |
 
 ## Troubleshooting
 
@@ -460,11 +585,13 @@ MIT © [JosXa](https://github.com/JosXa)
 - [x] Comprehensive tests (81 tests)
 - [x] npm package publication
 - [x] Watch mode for development
-- [ ] YAML support
-- [ ] TOML support
-- [ ] Custom merge strategies
-- [ ] Config file for patterns
-- [ ] Dry-run mode
+- [ ] YAML support ([#1](https://github.com/JosXa/permachine/issues/1))
+- [ ] TOML support ([#2](https://github.com/JosXa/permachine/issues/2))
+- [ ] Markdown support ([#3](https://github.com/JosXa/permachine/issues/3))
+- [ ] Patch file support ([#4](https://github.com/JosXa/permachine/issues/4))
+- [ ] Custom merge strategies ([#5](https://github.com/JosXa/permachine/issues/5))
+- [ ] Config file for patterns ([#6](https://github.com/JosXa/permachine/issues/6))
+- [ ] Dry-run mode ([#7](https://github.com/JosXa/permachine/issues/7))
 
 ## Credits
 

package/dist/cli.js

@@ -5801,9 +5801,144 @@ glob.glob = glob;
 
 // src/core/file-scanner.ts
 import path2 from "node:path";
+
+// src/core/file-filters.ts
+import os2 from "node:os";
+var cachedContext = null;
+function getFilterContext() {
+  if (cachedContext) {
+    return cachedContext;
+  }
+  const platform = os2.platform();
+  let osName;
+  switch (platform) {
+    case "win32":
+      osName = "windows";
+      break;
+    case "darwin":
+      osName = "macos";
+      break;
+    case "linux":
+      osName = "linux";
+      break;
+    case "freebsd":
+      osName = "freebsd";
+      break;
+    case "openbsd":
+      osName = "openbsd";
+      break;
+    default:
+      osName = platform;
+  }
+  cachedContext = {
+    os: osName,
+    arch: os2.arch(),
+    machine: getMachineName(),
+    user: os2.userInfo().username.toLowerCase(),
+    env: "development"?.toLowerCase() || null,
+    platform
+  };
+  return cachedContext;
+}
+function createCustomContext(overrides) {
+  const base = getFilterContext();
+  return { ...base, ...overrides };
+}
+var FILTER_REGEX = /\{([a-zA-Z0-9_-]+)(=|!=|~|\^)([a-zA-Z0-9_*.,\-]+)\}/g;
+function parseFilters(filename) {
+  const filters = [];
+  let match2;
+  FILTER_REGEX.lastIndex = 0;
+  while ((match2 = FILTER_REGEX.exec(filename)) !== null) {
+    const [raw, key, operator, value] = match2;
+    filters.push({
+      key: key.toLowerCase(),
+      operator,
+      value: value.toLowerCase(),
+      raw
+    });
+  }
+  let baseFilename = filename.replace(/\.?\{[^}]+\}/g, "");
+  baseFilename = baseFilename.replace(/\.{2,}/g, ".");
+  return { filters, baseFilename };
+}
+function hasFilters(filename) {
+  FILTER_REGEX.lastIndex = 0;
+  return FILTER_REGEX.test(filename);
+}
+function evaluateFilter(filter2, context) {
+  const contextValue = context[filter2.key];
+  if (contextValue === null || contextValue === undefined) {
+    return false;
+  }
+  switch (filter2.operator) {
+    case "=":
+      return evaluateEquals(filter2.value, contextValue);
+    case "!=":
+      return !evaluateEquals(filter2.value, contextValue);
+    case "~":
+      return evaluateWildcard(filter2.value, contextValue);
+    case "^":
+      return evaluateRange(filter2.value, contextValue);
+    default:
+      return false;
+  }
+}
+function evaluateEquals(filterValue, contextValue) {
+  const options = filterValue.split(",").map((v) => v.trim().toLowerCase());
+  return options.includes(contextValue.toLowerCase());
+}
+function evaluateWildcard(filterValue, contextValue) {
+  const regexPattern = filterValue.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  const regex = new RegExp(`^${regexPattern}$`, "i");
+  return regex.test(contextValue);
+}
+function evaluateRange(filterValue, contextValue) {
+  const [min, max] = filterValue.split("-").map((v) => v.trim());
+  const numContext = parseFloat(contextValue);
+  const numMin = parseFloat(min);
+  const numMax = parseFloat(max);
+  if (!isNaN(numContext) && !isNaN(numMin) && !isNaN(numMax)) {
+    return numContext >= numMin && numContext <= numMax;
+  }
+  return contextValue >= min && contextValue <= max;
+}
+function matchFilters(filename, context) {
+  const ctx = context || getFilterContext();
+  const { filters } = parseFilters(filename);
+  if (filters.length === 0) {
+    return {
+      matches: true,
+      failedFilters: [],
+      context: ctx
+    };
+  }
+  const failedFilters = [];
+  for (const filter2 of filters) {
+    if (!evaluateFilter(filter2, ctx)) {
+      failedFilters.push(filter2);
+    }
+  }
+  return {
+    matches: failedFilters.length === 0,
+    failedFilters,
+    context: ctx
+  };
+}
+function getBaseFilename(filename) {
+  return parseFilters(filename).baseFilename;
+}
+function isLegacyFilename(filename, machineName) {
+  const middlePattern = new RegExp(`\\.${machineName}\\.`, "i");
+  const endPattern = new RegExp(`\\.${machineName}$`, "i");
+  return (middlePattern.test(filename) || endPattern.test(filename)) && !hasFilters(filename);
+}
+
+// src/core/file-scanner.ts
 async function scanForMergeOperations(machineName, cwd = process.cwd()) {
   const operations = [];
   const patterns = [
+    "**/*{*}*",
     `**/*.${machineName}.*`,
     `**/.*.${machineName}`,
     `**/.*.${machineName}.*`
@@ -5813,7 +5948,7 @@ async function scanForMergeOperations(machineName, cwd = process.cwd()) {
     try {
       const files = await glob(pattern, {
         cwd,
-        ignore: ["node_modules/**", ".git/**", "dist/**"],
+        ignore: ["node_modules/**", ".git/**", "dist/**", "**/*.base.*", "**/.*base*"],
         dot: true,
         nodir: true
       });
@@ -5821,10 +5956,24 @@ async function scanForMergeOperations(machineName, cwd = process.cwd()) {
     } catch (error) {}
   }
   const uniqueFiles = [...new Set(foundFiles)];
+  const context = createCustomContext({ machine: machineName });
   for (const file of uniqueFiles) {
-    const operation = createMergeOperation(file, machineName, cwd);
-    if (operation) {
-      operations.push(operation);
+    const basename = path2.basename(file);
+    if (basename.includes(".base.") || basename.includes(".base")) {
+      continue;
+    }
+    let shouldProcess = false;
+    if (hasFilters(basename)) {
+      const result = matchFilters(basename, context);
+      shouldProcess = result.matches;
+    } else if (isLegacyFilename(basename, machineName)) {
+      shouldProcess = true;
+    }
+    if (shouldProcess) {
+      const operation = createMergeOperation(file, machineName, cwd);
+      if (operation) {
+        operations.push(operation);
+      }
     }
   }
   return operations;
@@ -5847,21 +5996,35 @@ function createMergeOperation(machineFile, machineName, cwd) {
   if (type === "unknown") {
     return null;
   }
-  const basename = type === "env" ? fullBasename : path2.basename(machineFile, ext2);
-  const machinePattern = `.${machineName}`;
-  const basePattern = ".base";
   let baseName;
   let outputName;
-  if (basename.endsWith(machinePattern)) {
-    const withoutMachine = basename.substring(0, basename.length - machinePattern.length);
-    baseName = withoutMachine + basePattern;
-    outputName = withoutMachine;
+  if (hasFilters(fullBasename)) {
+    outputName = getBaseFilename(fullBasename);
+    if (type === "env") {
+      const nameWithoutExt = outputName;
+      baseName = nameWithoutExt + ".base";
+    } else {
+      const nameWithoutExt = outputName.replace(ext2, "");
+      baseName = nameWithoutExt + ".base" + ext2;
+    }
   } else {
-    return null;
+    const basename = type === "env" ? fullBasename : path2.basename(machineFile, ext2);
+    const machinePattern = `.${machineName}`;
+    if (basename.endsWith(machinePattern)) {
+      const withoutMachine = basename.substring(0, basename.length - machinePattern.length);
+      baseName = withoutMachine + ".base";
+      outputName = withoutMachine;
+      if (type !== "env") {
+        baseName = baseName + ext2;
+        outputName = outputName + ext2;
+      }
+    } else {
+      return null;
+    }
   }
-  const basePath = path2.join(cwd, dir, baseName + ext2);
+  const basePath = path2.join(cwd, dir, baseName);
   const machinePath = path2.join(cwd, machineFile);
-  const outputPath = path2.join(cwd, dir, outputName + ext2);
+  const outputPath = path2.join(cwd, dir, outputName);
   return {
     basePath,
     machinePath,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "permachine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Automatically merge machine-specific config files with base configs using git hooks",
   "type": "module",
   "bin": {
-    "permachine": "./dist/cli.js"
+    "permachine": "dist/cli.js"
   },
   "scripts": {
     "build": "bun build src/cli.ts --outdir dist --target node --format esm",