Initialize Eagle Plugin Repository

Purpose

This skill initializes a new Eagle plugin repository by cloning a template repository, removing git history, randomizing the manifest ID, and customizing the manifest.json file based on user input.

Template Options

React Template

• •Repository: https://github.com/ZackaryW/eagle-plugin-react-template
• •Stack: React + TypeScript + Vite + TailwindCSS + DaisyUI
• •Use Case: Modern React-based plugins with UI components
• •Recommended: When using React template, actively recommend incorporating eagle-cooltils utility package

Pure JavaScript Template

• •Repository: https://github.com/ZackaryW/eagle-plugin-template
• •Stack: Pure JavaScript/TypeScript
• •Use Case: Lightweight plugins without React dependencies

Workflow

1. •Clone Template: Clone the selected template repository to the target directory
2. •Remove Git History: Delete .git directory to create a fresh repository
3. •Randomize Manifest ID: Generate a unique plugin ID using UUID v4
4. •Update Manifest: Modify manifest.json with user-provided values:
   • •id: Randomized unique ID (UUID v4)
   • •name: User-provided name (or default from template)
   • •version: User-provided version (default: "1.0.0")
   • •keywords: User-provided keywords array
   • •main.width: User-provided width (default: 1200)
   • •main.height: User-provided height (default: 800)
5. •React Template - eagle-cooltils Recommendation: When using React template, actively engage with the user about adding eagle-cooltils dependency

Implementation Details

Script Language

This skill uses JavaScript/Node.js for execution:

• •No Python dependency required
• •Uses Node.js built-in modules (fs, path, child_process, crypto)
• •Cross-platform support via Node.js
• •Direct integration with JavaScript ecosystem

Cloning Without Git

Use git clone with --depth 1 and then remove .git directory, or use a method that doesn't include git history.

Manifest ID Randomization

Generate a unique ID using UUID v4 (random UUID):

• •The id field in manifest.json is replaced with a full UUID v4: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
• •UUID v4 ensures cryptographically random, unique identifiers
• •Format is URL-safe and follows Eagle plugin ID conventions
• •The name field is updated separately from the id field (name is for display, id is the unique identifier)

Manifest Updates

• •Read existing manifest.json
• •Update fields while preserving structure
• •Ensure JSON is properly formatted
• •Validate required fields are present

Parameters

• •template: "react" or "js" (required)
• •target_dir: Target directory path (required)
• •name: Plugin name (optional, uses template default if not provided)
• •version: Plugin version (optional, default: "1.0.0")
• •keywords: Array of keyword strings (optional)
• •width: Window width (optional, default: 1200)
• •height: Window height (optional, default: 800)

Cross-Platform Support

The script is designed to work on Windows and macOS (and Linux):

• •Path Handling: Uses pathlib.Path for cross-platform path operations
• •Git Detection: Checks if git is available before attempting clone
• •File Operations: Handles Windows file locking and permissions
• •Atomic Writes: Uses temporary files for safe manifest.json updates
• •Error Recovery: Retries file operations on Windows with exponential backoff
• •Cleanup: Properly handles cleanup on both platforms, including readonly files

Error Handling

• •Verify target directory doesn't exist or is empty
• •Check git availability before cloning
• •Handle git clone failures with clear error messages
• •Validate manifest.json structure
• •Ensure all required manifest fields are present after updates
• •Handle file permission errors (Windows readonly files)
• •Retry operations on transient failures
• •Clean up partial clones on errors

React Template - eagle-cooltils Integration

When initializing a React template, actively recommend incorporating eagle-cooltils:

Recommendation Process

1. •Engage with User: After template setup, ask the user if they want to add eagle-cooltils
2. •Explain Benefits:
   • •Item filtering with fluent API
   • •Config management (persistent storage)
   • •Subscription system for reactive updates
   • •Private fields handling utilities
   • •Web API client
   • •TypeScript definitions for Eagle API
3. •User Decision: Let user decide whether to add the dependency
4. •If Accepted: Guide user to add eagle-cooltils to package.json and install

Installation Steps (if user accepts)

# Add to package.json dependencies
pnpm add eagle-cooltils
# or
npm install eagle-cooltils

Basic Setup (for user reference)

// In App.tsx or main component
import { initEagleConfig } from 'eagle-cooltils/universal';

eagle.onPluginCreate((plugin) => {
  initEagleConfig(plugin);
});

Documentation Reference

See memory-bank/details/package_eagle_cooltils.md for complete eagle-cooltils documentation.

Output

A new Eagle plugin directory ready for development with:

• •Customized manifest.json
• •Template files in place
• •No git history (fresh start)
• •Ready to initialize new git repository if needed
• •(For React) Recommendation to consider eagle-cooltils integration