Surgery

A powerful npm module and npx script for replacing text in files using YAML configuration files.

Features

• 🔧 Text replacement using regex patterns
• 📁 File glob pattern matching
• 🌐 Remote YAML config support (URLs)
• 🔗 GitHub integration with @org/repo syntax
• 🔍 Dry run mode for previewing changes
• 📝 Verbose logging
• ⚡ Fast batch processing

Installation

# Install globally
npm install -g surgery

# Or use with npx (recommended)
npx surgery <config>

# Or install as a dependency for programmatic use
npm install surgery

Usage

NPX Script (Command Line)

# Use local YAML config file
npx surgery config.yml

# Use remote config file
npx surgery https://example.com/config.yml

# Use GitHub repo config (downloads from n-p-x org)
npx surgery @myorg/myconfig

NPM Module (Programmatic)

import surgery from 'surgery';
// or
import { executeSurgery, downloadConfig, performReplacement } from 'surgery';

// Execute surgery with configuration
const result = await surgery.executeSurgery('config.yml', {
  dryRun: true,
  verbose: false
});

console.log('Files processed:', result.totalFilesProcessed);

// Download and parse config separately
const configContent = await surgery.downloadConfig('@myorg/config');

// Apply individual rules
const ruleResult = await surgery.performReplacement(rule, {
  dryRun: false,
  verbose: true
});

Options

# Dry run (preview changes without applying)
npx surgery config.yml --dry-run

# Verbose output
npx surgery config.yml --verbose

# Combine options
npx surgery config.yml --dry-run --verbose

YAML Configuration Format

rules:
  - description: "Human-readable description"
    files: "glob/pattern/**/*.js"
    find: "regex pattern to find"
    replace: "replacement text"
  
  - description: "Another rule"
    files: ["multiple", "patterns/**/*.{js,ts}"]
    find: "another\\s+pattern"
    replace: "replacement"

Configuration Fields

• rules (array): List of replacement rules
  • description (string, optional): Human-readable description of the rule
  • files (string|array): Glob pattern(s) for files to process
  • find (string): Regex pattern to search for
  • replace (string): Text to replace matches with
  • already (string, optional): Text to check for - if found, skip this file to prevent duplicate modifications

Examples

Replace package names

rules:
  - description: "Update package name"
    files: "**/package.json"
    find: '"name":\s*"old-name"'
    replace: '"name": "new-name"'

Update import statements

rules:
  - description: "Modernize imports"
    files: "src/**/*.js"
    find: "var\\s+(\\w+)\\s*=\\s*require\\(['\"]([^'\"]+)['\"]\\)"
    replace: "import $1 from '$2'"

Remove deprecated code

rules:
  - description: "Remove TODO comments"
    files: "**/*.{js,ts}"
    find: "// TODO:.*\\n"
    replace: ""

Prevent Duplicate Modifications

rules:
  - description: "Add logger import (only if not already present)"
    files: "src/**/*.js"
    find: "^"
    replace: "import { logger } from './logger.js';\n"
    already: "import { logger } from './logger.js'"
  
  - description: "Replace console.log with logger"
    files: "src/**/*.js"
    find: "console\\.log\\("
    replace: "logger.info("
    already: "logger.info("

Remote Configuration

GitHub Integration

Use the @org/repo format to download configs from the n-p-x GitHub organization:

npx surgery @myconfig/rules

This downloads from: https://raw.githubusercontent.com/n-p-x/rules/main/myconfig.yml

Custom URLs

npx surgery https://raw.githubusercontent.com/user/repo/main/config.yml

Development

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
node dist/index.js example-config.yml --dry-run

License

ISC