GitHub Prompts Sync — VSCode Extension

Keep your .github directories synchronized across all your workspaces and projects using profiles and templates.

Features

• Profile-based sync: Define .github template profiles (e.g., default, oss, private) and assign them to workspaces
• Auto-sync on open: Automatically sync when a registered workspace is opened
• Watch mode: Template changes propagate to all registered workspaces in real time
• Per-workspace overrides: Ignore, preserve local-only, or merge specific files per workspace
• Three-way conflict resolution: Side-by-side diff with accept/keep/merge/skip options
• Template variables: Replace {{VARIABLE}} placeholders during sync (e.g., {{GITHUB_ORG}})
• Status bar integration: See sync status at a glance with one-click actions
• Sidebar tree view: Browse profiles, workspaces, and file-level sync status
• First-time wizard: Guided setup to scaffold template store and import existing .github
• Cross-platform: Works on Windows, macOS, and Linux

Screenshots

Tech Stack

Prerequisites

• Node.js >= 18.x
• npm >= 8.x
• VSCode >= 1.85.0

Quick Start

# Clone the repository
git clone <repo-url>
cd github-prompts-sync-vscode

# Install dependencies
npm install

# Compile
npm run compile

# Run in VSCode Extension Development Host
# Press F5 in VSCode, or:
code --extensionDevelopmentPath=.

Available Scripts

Project Structure

github-prompts-sync-vscode/
├── src/
│   ├── extension.ts              # Entry point: activation, command registration
│   ├── types.ts                  # All shared TypeScript type definitions
│   ├── commands/                 # Command handlers (one per command)
│   │   ├── syncNow.ts            # Sync current workspace
│   │   ├── syncAll.ts            # Sync all registered workspaces
│   │   ├── assignProfile.ts      # Assign profile to workspace
│   │   ├── createProfile.ts      # Create new profile
│   │   ├── editProfile.ts        # Open profile directory
│   │   ├── register.ts           # Register workspace
│   │   ├── unregister.ts         # Unregister workspace
│   │   ├── importFromWorkspace.ts # Import .github to profile
│   │   ├── manageOverrides.ts    # Configure ignore/localOnly/merge
│   │   ├── showStatus.ts         # Display sync status
│   │   └── openStore.ts          # Open template store
│   ├── core/                     # Business logic
│   │   ├── syncEngine.ts         # Main sync algorithm
│   │   ├── profileManager.ts     # Profile CRUD operations
│   │   ├── registry.ts           # Workspace registry read/write
│   │   ├── diffEngine.ts         # File comparison & three-way merge
│   │   ├── cacheManager.ts       # Cached snapshots for diffs
│   │   ├── fileWatcher.ts        # Template directory watcher
│   │   └── templateVariables.ts  # {{VAR}} replacement engine
│   ├── views/                    # UI components
│   │   ├── statusBar.ts          # Status bar item
│   │   ├── treeView.ts           # Sidebar tree data provider
│   │   └── treeItems.ts          # Tree item definitions
│   ├── utils/                    # Shared utilities
│   │   ├── fs.ts                 # File system helpers
│   │   ├── hash.ts               # SHA-256 hashing
│   │   ├── config.ts             # Settings reader
│   │   └── mutex.ts              # Async mutex for sync locking
│   └── test/                     # Test files
│       ├── runTest.ts            # Test launcher
│       └── suite/                # Test suites
├── resources/icons/              # Extension icons
├── docs/                         # Documentation
├── package.json                  # Extension manifest
├── tsconfig.json                 # TypeScript configuration
└── .vscodeignore                 # Files excluded from VSIX

Development Workflow

Adding a New Command

1. Create a handler in src/commands/myCommand.ts
2. Add the command to package.json under contributes.commands
3. Register it in src/extension.ts in the registerCommands function
4. Add menu contributions in package.json if needed

Adding a New Setting

1. Add to contributes.configuration.properties in package.json
2. Add the setting to ExtensionConfig interface in src/utils/config.ts
3. Read it in getConfig() in the same file

Running Tests

# Compile first
npm run compile

# Run all tests
npm test

Testing

Tests use Mocha with @vscode/test-electron to run inside a real VSCode instance.

• Unit tests: src/test/suite/*.test.ts — test core logic with temp directories
• Integration tests: Same files, but can access vscode API directly

Run tests: npm test

Installation

From VSIX (sideload)

npm run package
code --install-extension github-prompts-sync-vscode-0.1.0.vsix

From Source (development)

1. Clone the repository
2. npm install
3. npm run compile
4. Press F5 in VSCode to launch Extension Development Host

From Marketplace (if published)

ext install github-prompts-sync-vscode

Environment Variables

The extension stores configuration in ~/.github-sync/ by default. This path is configurable via settings.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Follow the code standards (ESLint + Prettier enforced)
4. Write tests for new functionality
5. Run npm run check-all before committing
6. Submit a pull request

Commit Messages

Use conventional commits: feat:, fix:, docs:, test:, refactor:, chore:

License

MIT