RepoWeaver

A GitHub App that skillfully weaves multiple templates together to create and update repositories with intelligent merge strategies and automatic updates.

Features

• 🚀 GitHub App Integration: Native GitHub integration with OAuth authentication
• 🔄 Auto Updates: Automatically update repositories when templates change
• 🎯 Multi-Template Support: Apply multiple templates to a single repository
• 🌿 Template Branch Support: Use specific branches or subdirectories from templates
• 🔧 Advanced Merge Strategies: File pattern-based strategies, custom implementations, and plugin system
• 🚫 File Exclusion: Flexible patterns to exclude files during template processing
• 📦 Pull Request Workflow: All updates create pull requests for review
• 🔐 Secure: Uses GitHub App authentication with fine-grained permissions
• 🌐 Web Interface: Easy-to-use web interface for configuration and management

Installation & Setup

As a GitHub App

1. Install the GitHub App (coming soon - will be available in GitHub Marketplace)
2. Configure permissions for your repositories
3. Access the web interface at your app installation URL

Self-Hosted Setup

1. Clone the repository:

   git clone https://github.com/your-org/repoweaver.git
   cd repoweaver

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your GitHub App credentials

4. Build and start:

   npm run build
   npm start

CLI Usage (Legacy)

The original CLI tool is still available:

# Install globally
npm install -g repoweaver

# Or run directly with npx
npx repoweaver --help

Usage

Configuration Files

RepoWeaver supports configuration files to make template management easier:

weaver.json (or .weaver.json)

{
	"name": "my-awesome-project",
	"description": "A project created with RepoWeaver",
	"templates": [
		"https://github.com/user/frontend-template.git",
		{
			"url": "https://github.com/user/backend-template.git",
			"name": "backend",
			"branch": "main",
			"subDirectory": "api"
		}
	],
	"mergeStrategy": "merge",
	"mergeStrategies": [
		{
			"patterns": ["package.json"],
			"strategy": { "type": "package-json" },
			"priority": 100
		},
		{
			"patterns": ["*.json"],
			"strategy": { "type": "json" },
			"priority": 90
		},
		{
			"patterns": ["*.md"],
			"strategy": { "type": "markdown" },
			"priority": 80
		},
		{
			"patterns": ["src/**/*.js", "src/**/*.ts"],
			"strategy": { "type": "overwrite" },
			"priority": 70
		}
	],
	"excludePatterns": ["*.log", "node_modules/**", ".env*"],
	"includePatterns": ["!.env.example"],
	"autoUpdate": true,
	"hooks": {
		"postBootstrap": ["npm install", "npm run build"]
	},
	"variables": {
		"PROJECT_NAME": "my-project",
		"AUTHOR_NAME": "John Doe"
	},
	"plugins": ["npm-merger"]
}

.weaverignore

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/

# Environment files
.env
.env.local

# Include exceptions
!.env.example
!README.md

.weaver.js (Dynamic Configuration)

module.exports = {
	name: process.env.PROJECT_NAME || 'my-project',
	templates: ['https://github.com/user/base-template.git', ...(process.env.NODE_ENV === 'production' ? ['https://github.com/user/prod-template.git'] : ['https://github.com/user/dev-template.git'])],
	mergeStrategy: 'merge',
	variables: {
		NODE_ENV: process.env.NODE_ENV,
		VERSION: require('./package.json').version,
	},
};

Web Interface

1. Login with your GitHub account
2. Select a repository from your installation
3. Configure templates by adding GitHub repository URLs or upload a weaver.json file
4. Choose merge strategy: merge, overwrite, or skip
5. Set exclude patterns to skip certain files (or use .weaverignore)
6. Bootstrap or update your repository

API Endpoints

The GitHub App provides REST API endpoints:

• GET /api/repositories - List accessible repositories
• GET /api/repositories/:owner/:repo/config - Get repository configuration
• PUT /api/repositories/:owner/:repo/config - Update repository configuration
• POST /api/repositories/:owner/:repo/bootstrap - Bootstrap repository
• POST /api/repositories/:owner/:repo/update - Update repository

Webhook Integration

The app automatically responds to:

• Repository pushes: Updates dependent repositories when templates change
• Installation events: Manages app installation lifecycle
• Pull request events: Handles template update reviews

CLI Usage

Initialize a new project

# Create sample configuration files
repoweaver init

# Or create just the config file
repoweaver init --config-only

# Or create just the ignore file
repoweaver init --ignore-only

Bootstrap a new repository

# Using configuration file
repoweaver bootstrap my-project ./my-project

# Using command line options (overrides config file)
repoweaver bootstrap my-project ./my-project \
  --template https://github.com/user/template1.git \
  --template https://github.com/user/template2.git \
  --git \
  --remote https://github.com/myuser/my-project.git

Update an existing repository

# Using configuration file
repoweaver update ./my-project

# Using command line options (overrides config file)
repoweaver update ./my-project \
  --template https://github.com/user/updated-template.git \
  --merge-strategy merge

CLI Options

Bootstrap Command

• <name> - Repository name
• <path> - Target path for the new repository
• -t, --template <url> - Template repository URL (can be used multiple times)
• -b, --branch <branch> - Template branch (default: main)
• -s, --subdir <path> - Use subdirectory from template
• --git - Initialize git repository
• --remote <url> - Add git remote origin
• --exclude <pattern> - Exclude patterns (can be used multiple times)
• --merge-strategy <strategy> - Merge strategy: overwrite|merge|skip (default: merge)

Update Command

• <path> - Path to the existing repository
• -t, --template <url> - Template repository URL (can be used multiple times)
• -b, --branch <branch> - Template branch (default: main)
• -s, --subdir <path> - Use subdirectory from template
• --exclude <pattern> - Exclude patterns (can be used multiple times)
• --merge-strategy <strategy> - Merge strategy: overwrite|merge|skip (default: merge)

Examples

Simple bootstrap

repoweaver bootstrap my-app ./my-app \
  --template https://github.com/facebook/create-react-app.git \
  --git

Multi-template setup

repoweaver bootstrap full-stack-app ./my-app \
  --template https://github.com/user/frontend-template.git \
  --template https://github.com/user/backend-template.git \
  --exclude "*.log" \
  --exclude "node_modules/**" \
  --git \
  --remote https://github.com/myuser/full-stack-app.git

Using template subdirectories

repoweaver bootstrap docs-site ./docs \
  --template https://github.com/user/monorepo-template.git \
  --subdir docs \
  --branch develop

Programmatic Usage

import { Bootstrapper, BootstrapOptions } from 'repoweaver';

const bootstrapper = new Bootstrapper();

const options: BootstrapOptions = {
	targetPath: './my-project',
	templates: [
		{
			url: 'https://github.com/user/template.git',
			name: 'main-template',
			branch: 'main',
		},
	],
	repositoryName: 'my-project',
	initGit: true,
	addRemote: 'https://github.com/myuser/my-project.git',
};

const result = await bootstrapper.bootstrap(options);

if (result.success) {
	console.log(`✅ Repository created at: ${result.repositoryPath}`);
} else {
	console.error('❌ Bootstrap failed:', result.errors);
}

Development

GitHub App Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (GitHub App)
npm run dev

# Run CLI in development mode
npm run cli:dev

# Lint code
npm run lint

# Type check
npm run typecheck

Environment Variables

Create a .env file with the following variables:

# GitHub App Configuration
GITHUB_APP_ID=your_app_id
GITHUB_PRIVATE_KEY=your_private_key
GITHUB_WEBHOOK_SECRET=your_webhook_secret
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

# Database
DATABASE_URL=sqlite:./app.db

# Server Configuration
PORT=3000
NODE_ENV=development
APP_URL=http://localhost:3000

Database

The app uses SQLite for development and can be configured to use other databases in production. The database schema includes:

• installations: GitHub App installations
• user_sessions: User authentication sessions
• repository_configs: Repository template configurations
• jobs: Background job queue
• template_configurations: Template to repository mappings

Mobile App Development

The React Native companion app is located in the mobile/ directory:

# Install mobile dependencies
npm run mobile:install

# Start Expo development server
npm run mobile:start

# Run on iOS
npm run mobile:ios

# Run on Android
npm run mobile:android

License

MIT