@pugpigjs/create-wp-project 0.0.2-beta.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @pugpigjs/create-wp-project
+
+## 0.0.2-beta.0
+
+### Patch Changes
+
+- c2f5db8: Initial release of CLI tool for scaffolding WordPress plugins and themes with interactive prompts, case-insensitive placeholder replacement, and commands for initialising, adding, removing, and updating projects from template repositories.

package/README.md

@@ -0,0 +1,236 @@
+# @pugpigjs/create-wp-project
+
+CLI tool to scaffold WordPress plugins and themes from a template repo.
+
+## Quick Start
+
+The easiest way to scaffold a new WordPress project:
+
+```bash
+npx @pugpigjs/create-wp-project init --git-url <repository-url> --directory <target-directory>
+```
+
+**Note:** Both `--git-url` and `--directory` are required for all commands.
+
+## How It Works
+
+This CLI tool uses a **placeholder-based templating system** to scaffold WordPress projects:
+
+1. **Clone template** - Fetches the template repository
+2. **Interactive prompts** - Asks for namespace, project name, and description
+3. **Placeholder replacement** - Automatically replaces `TPL_*`/`tpl_*` and `pkg_*` markers in all template files
+4. **Generate config** - Creates a customised docker-compose.yml for your project
+5. **Validation** - Ensures naming conventions and prevents common mistakes
+
+### Template Placeholders
+
+The template uses **case-insensitive** placeholder markers throughout all files. You can use either uppercase (`TPL_*`) or lowercase (`tpl_*`) variants:
+
+- `TPL_NAMESPACE` / `tpl_namespace` - Namespace in PascalCase (e.g., "Pugpig")
+- `TPL_NAMESPACE_LOWER` / `tpl_namespace_lower` - Lowercase namespace (e.g., "pugpig")
+- `TPL_PROJECT_NAME` / `tpl_project_name` - Project name in snake_case (e.g., "my_plugin")
+- `TPL_PROJECT_NAME_PASCAL` / `tpl_project_name_pascal` - PascalCase name (e.g., "MyPlugin")
+- `TPL_PROJECT_NAME_SLUG` / `tpl_project_name_slug` - Kebab-case for NPM/URLs (e.g., "my-plugin")
+- `TPL_PROJECT_NAME_FLAT` / `tpl_project_name_flat` - No separators (e.g., "myplugin")
+- `TPL_FULL_PROJECT_NAME` / `tpl_full_project_name` - Full project name with namespace (e.g., "pugpig_my_plugin")
+- `TPL_FULL_PROJECT_NAME_SLUG` / `tpl_full_project_name_slug` - Kebab-case full name (e.g., "pugpig-my-plugin")
+- `TPL_FULL_PROJECT_NAME_TITLE` / `tpl_full_project_name_title` - Title Case full name (e.g., "Pugpig My Plugin")
+- `TPL_FULL_PROJECT_NAME_UPPER` / `tpl_full_project_name_upper` - For plugin/theme headers (e.g., "PUGPIG MY PLUGIN")
+- `TPL_DESCRIPTION` / `tpl_description` - Human-readable description
+- `pkg_*` (wildcard) - Any package name starting with `pkg_` gets replaced with the full project name slug (e.g., `pkg_example_theme` → `pugpig-my-theme`)
+
+**Usage Examples:**
+```php
+// PHP - uppercase convention
+namespace TPL_NAMESPACE\TPL_PROJECT_NAME_PASCAL;
+
+// composer.json - lowercase convention
+"name": "tpl_namespace_lower/tpl_project_name_flat"
+
+// package.json - wildcards
+"name": "pkg_example_theme"  // becomes "pugpig-my-theme"
+```
+
+The CLI automatically computes all these variations from your namespace and project name inputs.
+
+## Commands
+
+### `init` - Initialise a New Project
+
+```bash
+npx @pugpigjs/create-wp-project init --git-url <repository-url> --directory <target-directory>
+```
+
+This interactive CLI will:
+1. Clone the template repository
+2. Let you choose between Rich Plugin, Simple Plugin, or Theme templates
+3. Prompt for namespace (e.g., "Pugpig"), project name (e.g., "my_plugin"), and description
+4. Validate inputs (prevents namespace duplication, ensures snake_case format)
+5. Copy configuration files to your directory
+6. Generate a customised docker-compose.yml
+7. Replace all `TPL_*`/`tpl_*` and `pkg_*` markers throughout the project with computed values
+
+### `add` - Add Another Template to Existing Project
+
+If you've already initialised a project and want to add another plugin or theme:
+
+```bash
+npx @pugpigjs/create-wp-project add --git-url <repository-url> --directory <target-directory>
+```
+
+This will:
+1. Clone the template repository
+2. Let you choose which template to add
+3. Prompt for namespace, project name, and description
+4. Validate inputs and replace all placeholders
+5. Copy the template to a new directory (e.g., `namespace_project_name`)
+6. Update your docker-compose.yml with the new service
+
+### `remove` - Remove a Template from Project
+
+To remove a plugin or theme from your project:
+
+```bash
+npx @pugpigjs/create-wp-project remove --directory <target-directory>
+```
+
+This will:
+1. Show you a list of existing projects in the directory
+2. Ask you to confirm the removal
+3. Remove the service from docker-compose.yml (with backup)
+4. Delete the project directory
+
+**Note:** This action cannot be undone. A backup of docker-compose.yml is created automatically.
+
+### `update` - Update Root Configuration Files
+
+To refresh configuration files (like bitbucket-pipelines.yml, renovate.json, etc.) from the latest template:
+
+```bash
+npx @pugpigjs/create-wp-project update --git-url <repository-url> --directory <target-directory>
+```
+
+This will:
+1. Clone the latest template repository
+2. Show you a list of available root configuration files
+3. Let you select which files to update
+4. Optionally create backups (.backup) of existing files before updating
+5. Copy the selected files from the template
+
+This is useful when:
+- The template's pipeline configuration has been updated
+- New ESLint rules or TypeScript configs are available
+- Renovate configuration has changed
+- You want to sync with the latest best practices
+
+## CLI Options
+
+All commands (`init`, `add`, and `update`) require:
+
+- `--git-url <url>` - **(Required)** Git repository URL or local path to the template
+  - Example: `https://github.com/user/wp-template.git`
+  - Example: `/path/to/local/template`
+  - Example: `.` (current directory for local development)
+
+- `--directory <path>` - **(Required)** Target/project directory
+  - **Must end with `-server`** for safety (e.g., `my-project-server`)
+  - Example: `./my-project-server`
+  - Example: `/absolute/path/to/project-server`
+
+Optional:
+
+- `--template-dir <path>` - Template source directory within the repository (defaults to `repo_template`)
+
+## Examples
+
+### Initialise from a remote repository
+```bash
+npx @pugpigjs/create-wp-project init \
+  --git-url https://github.com/your-org/your-wp-template.git \
+  --directory ./my-project-server
+```
+
+### Initialise from a local template (for development)
+```bash
+npx @pugpigjs/create-wp-project init \
+  --git-url . \
+  --directory ./test-server
+```
+
+### Add another template to existing project
+```bash
+npx @pugpigjs/create-wp-project add \
+  --git-url https://github.com/your-org/your-wp-template.git \
+  --directory ./my-project-server
+```
+
+### Update configuration files
+```bash
+npx @pugpigjs/create-wp-project update \
+  --git-url https://github.com/your-org/your-wp-template.git \
+  --directory ./my-project-server
+```
+
+## Safety Features
+
+This CLI tool includes multiple safety checks to prevent accidental data loss:
+
+- ✅ **Directory validation** - Target directory must end with `-server`
+- ✅ **System directory protection** - Blocks operations in `/`, `/usr`, `/etc`, home directory, etc.
+- ✅ **Sandboxed operations** - Temporary files only created within project directory
+- ✅ **Backup creation** - Creates `.backup` files before modifying docker-compose.yml
+- ✅ **File comparison** - Only updates files that have actually changed
+- ✅ **Project directory check** - Won't overwrite existing project directories
+
+## Requirements
+
+- Node.js 14 or higher
+- A directory ending with `-server` (e.g., `my-project-server`)
+
+## Template Types
+
+### Rich Plugin
+Full-featured plugin with Vue.js, SCSS, and advanced build setup. Includes:
+- Vite build system with HMR support
+- Vue.js components
+- SCSS preprocessing
+- Composer dependencies with PHP-Scoper
+- WordPress integration utilities
+
+### Simple Plugin
+Lightweight plugin with basic JavaScript and CSS. Includes:
+- Simple Vite build setup
+- Vanilla JavaScript
+- Basic CSS
+- Minimal dependencies
+
+### Theme
+WordPress theme with modern build tooling. Includes:
+- Vite build system
+- Modern CSS/JS compilation
+- Theme template structure
+
+## Development
+
+For local development and testing from within this repository:
+
+```bash
+# From the repository root
+node packages/create-wp-project/src/cli.js init \
+  --git-url . \
+  --directory ./test-server
+
+# Or test the add command
+node packages/create-wp-project/src/cli.js add \
+  --git-url . \
+  --directory ./test-server
+
+# Or test the update command
+node packages/create-wp-project/src/cli.js update \
+  --git-url . \
+  --directory ./test-server
+```
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pugpigjs/create-wp-project",
+  "version": "0.0.2-beta.0",
+  "description": "CLI tool to scaffold WordPress plugins and themes from a template repo.",
+  "type": "module",
+  "bin": {
+    "create-wp-project": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "wordpress",
+    "scaffold",
+    "cli",
+    "pugpig"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.0.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.0.0",
+    "inquirer": "^12.10.0",
+    "ora": "^8.0.0",
+    "simple-git": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { initProject } from './commands/init.js'
+import { addTemplate } from './commands/add.js'
+import { removeTemplate } from './commands/remove.js'
+import { updateProject } from './commands/update.js'
+
+const program = new Command()
+
+program
+  .name('create-wp-project')
+  .description('CLI tool to scaffold WordPress plugins and themes from a template repo.')
+  .version('0.0.1')
+
+program
+  .command('init')
+  .description('Initialise a new WordPress project from the template')
+  .requiredOption('-d, --directory <path>', 'Target directory (must end with -server)')
+  .requiredOption('--git-url <url>', 'Git repository URL or local path to template')
+  .option('--template-dir <path>', 'Template source directory', 'repo_template')
+  .action(initProject)
+
+program
+  .command('add')
+  .description('Add another plugin or theme to an existing project')
+  .requiredOption('-d, --directory <path>', 'Project directory (must end with -server)')
+  .requiredOption('--git-url <url>', 'Git repository URL or local path to template')
+  .option('--template-dir <path>', 'Template source directory', 'repo_template')
+  .action(addTemplate)
+
+program
+  .command('remove')
+  .description('Remove a plugin or theme from the project')
+  .requiredOption('-d, --directory <path>', 'Project directory (must end with -server)')
+  .action(removeTemplate)
+
+program
+  .command('update')
+  .description('Update root configuration files from the template')
+  .requiredOption('-d, --directory <path>', 'Project directory (must end with -server)')
+  .requiredOption('--git-url <url>', 'Git repository URL or local path to template')
+  .option('--template-dir <path>', 'Template source directory', 'repo_template')
+  .action(updateProject)
+
+program.parse()

package/src/commands/add.js

@@ -0,0 +1,151 @@
+import fse from 'fs-extra'
+import path from 'path'
+import crypto from 'crypto'
+import inquirer from 'inquirer'
+import chalk from 'chalk'
+import ora from 'ora'
+import {
+  prompts,
+  validateTargetDirectory,
+  cloneRepo,
+  copyDirectory,
+  replacePlaceholdersInFiles,
+  cleanup,
+  displayNextSteps
+} from '../utils/shared.js'
+import { TEMPLATES } from '../utils/constants.js'
+import { replacePlaceholders } from '../utils/docker-compose.js'
+
+/**
+ * Add service to existing docker-compose.yml
+ */
+async function addDockerComposeService(targetDir, tempDir, templateType, projectName, directoryName) {
+  const spinner = ora('Updating docker-compose.yml...').start()
+
+  try {
+    const dockerComposePath = path.join(targetDir, 'docker-compose.yml')
+    const templateDir = path.join(tempDir, 'repo_template', '.templates', 'docker-compose')
+    const partialPath = path.join(templateDir, `${templateType}.partial.yml`)
+
+    // Check if docker-compose.yml exists
+    if (!await fse.pathExists(dockerComposePath)) {
+      spinner.warn('docker-compose.yml not found, skipping')
+      return
+    }
+
+    // Check if partial exists
+    if (!await fse.pathExists(partialPath)) {
+      spinner.warn('Template partial not found, skipping docker-compose update')
+      return
+    }
+
+    // Create backup of docker-compose.yml
+    const backupPath = `${dockerComposePath}.backup`
+    await fse.copy(dockerComposePath, backupPath)
+    console.log(chalk.gray(`  Created backup: ${backupPath}`))
+
+    // Read existing docker-compose and partial
+    let dockerComposeContent = await fse.readFile(dockerComposePath, 'utf-8')
+    let partial = await fse.readFile(partialPath, 'utf-8')
+
+    // Remove 'services:' from the beginning of partial if it exists (for add command)
+    partial = partial.replace(/^services:\s*\n/, '')
+
+    // Replace placeholders in partial
+    const serviceContent = replacePlaceholders(partial, directoryName)
+
+    // Insert service before the global networks section (not indented networks within services)
+    // Match 'networks:' at the start of a line (no leading spaces)
+    const networksMatch = dockerComposeContent.match(/^networks:/m)
+    if (networksMatch && networksMatch.index !== undefined) {
+      const networksIndex = networksMatch.index
+      dockerComposeContent =
+        dockerComposeContent.slice(0, networksIndex) +
+        serviceContent + '\n' +
+        dockerComposeContent.slice(networksIndex)
+    } else {
+      // No networks section, append to end
+      dockerComposeContent += '\n' + serviceContent
+    }
+
+    await fse.writeFile(dockerComposePath, dockerComposeContent)
+    spinner.succeed('docker-compose.yml updated')
+  } catch (error) {
+    spinner.fail(`Failed to update docker-compose.yml: ${error.message}`)
+  }
+}
+
+
+/**
+ * Main add command handler
+ */
+export async function addTemplate(options) {
+  console.log(chalk.blue.bold('\n➕ Add Template to Existing Project\n'))
+
+  // Validate target directory is safe
+  const targetDir = await validateTargetDirectory(options.directory)
+
+  // Prompt for template selection and project name
+  // First get template and namespace
+  const initialAnswers = await inquirer.prompt([
+    prompts.template,
+    prompts.namespace
+  ])
+
+  // Then get project name with validation based on namespace
+  const projectAnswers = await inquirer.prompt([
+    prompts.getProjectNamePrompt(initialAnswers),
+    prompts.description
+  ])
+
+  const answers = { ...initialAnswers, ...projectAnswers }
+
+  const { template, namespace, projectName, description } = answers
+  // Use temp directory INSIDE the target directory - much safer!
+  // This ensures we can only delete files within the project scope
+  const uniqueId = crypto.randomBytes(4).toString('hex')
+  const tempDir = path.join(targetDir, `.temp-${uniqueId}`)
+
+  try {
+    // Step 1: Clone repository
+    await cloneRepo(options.gitUrl, tempDir)
+
+    // Step 2: Copy selected template
+    const spinner = ora(`Copying ${TEMPLATES[template].name} template...`).start()
+    const templateRoot = path.join(tempDir, options.templateDir)
+    const templateSource = path.join(templateRoot, TEMPLATES[template].directory)
+    const directoryName = `${namespace.toLowerCase()}_${projectName}`
+    const templateTarget = path.join(targetDir, directoryName)
+
+    // Check if target already exists
+    if (await fse.pathExists(templateTarget)) {
+      spinner.fail(`Directory ${directoryName} already exists`)
+      try {
+        await cleanup(tempDir)
+      } catch {}
+      process.exit(1)
+    }
+
+    await copyDirectory(templateSource, templateTarget)
+    spinner.succeed(`${TEMPLATES[template].name} template copied`)
+
+    // Step 3: Replace template placeholders
+    await replacePlaceholdersInFiles(targetDir, namespace, projectName, description)
+
+    // Step 4: Update docker-compose.yml
+    await addDockerComposeService(targetDir, tempDir, template, projectName, directoryName)
+
+    // Step 5: Cleanup
+    await cleanup(tempDir)
+
+    console.log(chalk.green.bold('\n✨ Template added successfully!\n'))
+    displayNextSteps(targetDir, directoryName, template, false)
+  } catch (error) {
+    console.error(chalk.red('\n❌ Error adding template:'), error.message)
+    // Cleanup on error
+    try {
+      await cleanup(tempDir)
+    } catch {}
+    process.exit(1)
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,187 @@
+import fse from 'fs-extra'
+import path from 'path'
+import crypto from 'crypto'
+import inquirer from 'inquirer'
+import chalk from 'chalk'
+import ora from 'ora'
+import {
+  prompts,
+  validateTargetDirectory,
+  cloneRepo,
+  copyDirectory,
+  replacePlaceholdersInFiles,
+  cleanup,
+  displayNextSteps
+} from '../utils/shared.js'
+import { TEMPLATES, ROOT_FILES } from '../utils/constants.js'
+import { replacePlaceholders } from '../utils/docker-compose.js'
+
+/**
+ * Copy root files from template to target directory
+ */
+async function copyRootFiles(templateRoot, targetDir, filesToCopy) {
+  const spinner = ora('Copying root configuration files...').start()
+  let copiedCount = 0
+  const overwrittenFiles = []
+
+  for (const file of filesToCopy) {
+    const sourcePath = path.join(templateRoot, file)
+    const targetPath = path.join(targetDir, file)
+
+    try {
+      if (await fse.pathExists(sourcePath)) {
+        const targetExists = await fse.pathExists(targetPath)
+        if (targetExists) {
+          overwrittenFiles.push(file)
+        }
+        await fse.copy(sourcePath, targetPath)
+        copiedCount++
+      }
+    } catch (error) {
+      console.warn(chalk.yellow(`  Warning: Could not copy ${file}`))
+    }
+  }
+
+  spinner.succeed(`Copied ${copiedCount} configuration files`)
+
+  if (overwrittenFiles.length > 0) {
+    console.log(chalk.yellow(`  ⚠️  Overwrote ${overwrittenFiles.length} existing file${overwrittenFiles.length !== 1 ? 's' : ''}: ${overwrittenFiles.join(', ')}`))
+  }
+}
+
+/**
+ * Generate docker-compose.yml based on selected template
+ */
+async function generateDockerCompose(targetDir, templateType, projectName, directoryName) {
+  const spinner = ora('Generating docker-compose.yml...').start()
+
+  try {
+    const templateDir = path.join(targetDir, '.templates', 'docker-compose')
+    const basePath = path.join(templateDir, 'base.yml')
+    const partialPath = path.join(templateDir, `${templateType}.partial.yml`)
+
+    let servicesContent = ''
+    let networksContent = ''
+
+    // Read the service partial
+    if (await fse.pathExists(partialPath)) {
+      const partial = await fse.readFile(partialPath, 'utf-8')
+      servicesContent = replacePlaceholders(partial, directoryName)
+    }
+
+    // Read the networks base
+    if (await fse.pathExists(basePath)) {
+      networksContent = await fse.readFile(basePath, 'utf-8')
+    }
+
+    // Combine with services first, then networks at the bottom
+    const dockerComposeContent = servicesContent + '\n' + networksContent
+
+    await fse.writeFile(path.join(targetDir, 'docker-compose.yml'), dockerComposeContent)
+
+    // Clean up templates directory
+    await fse.remove(path.join(targetDir, '.templates'))
+
+    spinner.succeed('docker-compose.yml generated')
+  } catch (error) {
+    spinner.warn('Could not generate docker-compose.yml (templates may not exist)')
+  }
+}
+
+/**
+ * Main init command handler
+ */
+export async function initProject(options) {
+  console.log(chalk.blue.bold('\n🚀 Pugpig WordPress Project Scaffolder\n'))
+
+  // Validate target directory is safe
+  const targetDir = await validateTargetDirectory(options.directory)
+
+  // Prompt for template selection and project name
+  // First get template and namespace
+  const initialAnswers = await inquirer.prompt([
+    prompts.template,
+    prompts.namespace
+  ])
+
+  // Then get project name with validation based on namespace
+  const projectAnswers = await inquirer.prompt([
+    prompts.getProjectNamePrompt(initialAnswers),
+    prompts.description,
+    {
+      type: 'input',
+      name: 'rootFiles',
+      message: 'Root files to copy (comma-separated, leave blank for defaults):',
+      default: ROOT_FILES.join(', '),
+      filter: (input) => input.split(',').map(f => f.trim()).filter(Boolean)
+    }
+  ])
+
+  const answers = { ...initialAnswers, ...projectAnswers }
+
+  const { template, namespace, projectName, description, rootFiles } = answers
+  const directoryName = `${namespace.toLowerCase()}_${projectName}`
+  const projectTarget = path.join(targetDir, directoryName)
+  // Use temp directory INSIDE the target directory - much safer!
+  // This ensures we can only delete files within the project scope
+  const uniqueId = crypto.randomBytes(4).toString('hex')
+  const tempDir = path.join(targetDir, `.temp-${uniqueId}`)
+
+  // Safety check: Don't overwrite existing project directory
+  if (await fse.pathExists(projectTarget)) {
+    console.error(chalk.red(`\n❌ Directory ${directoryName} already exists in ${targetDir}`))
+    console.error(chalk.yellow('Please choose a different project name or remove the existing directory.'))
+    process.exit(1)
+  }
+
+  try {
+    // Step 1: Clone repository
+    await cloneRepo(options.gitUrl, tempDir)
+
+    // Step 2: Copy root files from repo_template directory
+    const templateRoot = path.join(tempDir, options.templateDir)
+    await copyRootFiles(templateRoot, targetDir, rootFiles)
+
+    // Step 3: Copy selected template
+    const spinner = ora(`Copying ${TEMPLATES[template].name} template...`).start()
+    const templateSource = path.join(templateRoot, TEMPLATES[template].directory)
+    const templateTarget = path.join(targetDir, directoryName)
+    await copyDirectory(templateSource, templateTarget)
+    spinner.succeed(`${TEMPLATES[template].name} template copied`)
+
+    // Step 4: Copy .templates directory for docker-compose generation
+    const templatesSource = path.join(templateRoot, '.templates')
+    const templatesTarget = path.join(targetDir, '.templates')
+    if (await fse.pathExists(templatesSource)) {
+      await copyDirectory(templatesSource, templatesTarget)
+    }
+
+    // Step 5: Replace template placeholders (including root files for init)
+    const rootFilesToProcess = [
+      'package.json',
+      'docker-compose.yml',
+      'bitbucket-pipelines.yml'
+    ]
+    await replacePlaceholdersInFiles(targetDir, namespace, projectName, description, rootFilesToProcess)
+
+    // Step 6: Generate docker-compose.yml
+    await generateDockerCompose(targetDir, template, projectName, directoryName)
+
+    // Step 7: Cleanup
+    await cleanup(tempDir)
+
+    console.log(chalk.green.bold('\n✨ Project initialised successfully!\n'))
+    displayNextSteps(targetDir, directoryName, template, true)
+  } catch (error) {
+    console.error(chalk.red('\n❌ Error initialising project:'), error.message)
+    // Cleanup on error
+    try {
+      await cleanup(tempDir)
+    } catch {}
+    // Also cleanup .templates directory if it was copied
+    try {
+      await fse.remove(path.join(targetDir, '.templates'))
+    } catch {}
+    process.exit(1)
+  }
+}