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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pugpigjs/create-wp-project
 
+## 0.0.2-beta.2
+
+### Patch Changes
+
+- 3809018: Add environment variable support (PUGPIG_WORDPRESS_TEMPLATE_REPO_URL) and shorthand CLI flags (-g, -d, -t, -b) for improved developer experience.
+
+## 0.0.2-beta.1
+
+### Patch Changes
+
+- 13f211a: Add --branch option and shorthand flags (-g, -d, -t, -b) to CLI for easier command usage.
+
 ## 0.0.2-beta.0
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ CLI tool to scaffold WordPress plugins and themes from a template repo.
 The easiest way to scaffold a new WordPress project:
 
 ```bash
-npx @pugpigjs/create-wp-project init --git-url <repository-url> --directory <target-directory>
+npm create @pugpigjs/wp-project -- init --git-url <repository-url> --directory <target-directory>
 ```
 
 **Note:** Both `--git-url` and `--directory` are required for all commands.
@@ -24,20 +24,25 @@ This CLI tool uses a **placeholder-based templating system** to scaffold WordPre
 
 ### 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`)
+The template uses **case-insensitive** placeholder markers throughout all files. You can use either uppercase (`TPL_*`) or lowercase (`tpl_*`) variants. For JSON files or schemas that require lowercase keys, simply use the lowercase form.
+
+| Placeholder                      | Example Value                 | Description                                                        |
+|----------------------------------|-------------------------------|--------------------------------------------------------------------|
+| `TPL_NAMESPACE`                  | `Pugpig`                      | Namespace in PascalCase                                            |
+| `TPL_NAMESPACE_LOWER`            | `pugpig`                      | Lowercase namespace                                                |
+| `TPL_PROJECT_NAME`               | `my_plugin`                   | Project name in snake_case                                         |
+| `TPL_PROJECT_NAME_PASCAL`        | `MyPlugin`                    | Project name in PascalCase                                         |
+| `TPL_PROJECT_NAME_SLUG`          | `my-plugin`                   | Project name in kebab-case (for NPM/URLs)                          |
+| `TPL_PROJECT_NAME_FLAT`          | `myplugin`                    | Project name with no separators                                    |
+| `TPL_FULL_PROJECT_NAME`          | `pugpig_my_plugin`            | Full project name with namespace (snake_case)                      |
+| `TPL_FULL_PROJECT_NAME_SLUG`     | `pugpig-my-plugin`            | Full project name in kebab-case                                    |
+| `TPL_FULL_PROJECT_NAME_TITLE`    | `Pugpig My Plugin`            | Full project name in Title Case                                    |
+| `TPL_FULL_PROJECT_NAME_UPPER`    | `PUGPIG MY PLUGIN`            | Full project name in UPPERCASE                                     |
+| `TPL_DESCRIPTION`                | `A human-readable description`| Human-readable description                                         |
+| `pkg_*` (wildcard)               | `pkg_example_theme` → `pugpig-my-theme` | Any package name starting with `pkg_` gets replaced with the full project name slug |
+
+
+_Use lowercase keys for compatibility with JSON schemas or config files that require them._
 
 **Usage Examples:**
 ```php
@@ -58,7 +63,7 @@ The CLI automatically computes all these variations from your namespace and proj
 ### `init` - Initialise a New Project
 
 ```bash
-npx @pugpigjs/create-wp-project init --git-url <repository-url> --directory <target-directory>
+npm create @pugpigjs/wp-project -- init --git-url <repository-url> --directory <target-directory>
 ```
 
 This interactive CLI will:
@@ -75,7 +80,7 @@ This interactive CLI will:
 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>
+npm create @pugpigjs/wp-project -- add --git-url <repository-url> --directory <target-directory>
 ```
 
 This will:
@@ -91,7 +96,7 @@ This will:
 To remove a plugin or theme from your project:
 
 ```bash
-npx @pugpigjs/create-wp-project remove --directory <target-directory>
+npm create @pugpigjs/wp-project -- remove --directory <target-directory>
 ```
 
 This will:
@@ -107,7 +112,7 @@ This will:
 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>
+npm create @pugpigjs/wp-project -- update --git-url <repository-url> --directory <target-directory>
 ```
 
 This will:
@@ -127,48 +132,72 @@ This is useful when:
 
 All commands (`init`, `add`, and `update`) require:
 
-- `--git-url <url>` - **(Required)** Git repository URL or local path to the template
+- `-g, --git-url <url>` - Git repository URL or local path to the template
+  - **Can be set via environment variable** `PUGPIG_WORDPRESS_TEMPLATE_REPO_URL` to avoid passing it every time
   - 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
+- `-d, --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`)
+- `-t, --template-dir <path>` - Template source directory within the repository (defaults to `repo_template`)
+- `-b, --branch <name>` - Git branch to clone from (defaults to `master`)
+
+### Environment Variables
+
+You can set the following environment variable to simplify usage:
+
+- `PUGPIG_WORDPRESS_TEMPLATE_REPO_URL` - Default git repository URL
+  - When set, the `-g, --git-url` flag becomes optional
+  - Add to your shell config (`~/.zshrc` or `~/.bashrc`):
+    ```bash
+    export PUGPIG_WORDPRESS_TEMPLATE_REPO_URL=https://github.com/your-org/your-wp-template.git
+    ```
+  - After setting, you can omit the `-g` flag:
+    ```bash
+    npm create @pugpigjs/wp-project -- init -d ./my-project-server
+    ```
+
 
 ## 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
+npm create @pugpigjs/wp-project -- init \
+  -g https://github.com/your-org/your-wp-template.git \
+  -d ./my-project-server
 ```
 
 ### Initialise from a local template (for development)
 ```bash
-npx @pugpigjs/create-wp-project init \
-  --git-url . \
-  --directory ./test-server
+npm create @pugpigjs/wp-project -- init -g . -d ./test-server
+```
+
+### Initialise from a specific branch
+```bash
+npm create @pugpigjs/wp-project -- init \
+  -g https://github.com/your-org/your-wp-template.git \
+  -d ./my-project-server \
+  -b beta
 ```
 
 ### 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
+npm create @pugpigjs/wp-project -- add \
+  -g https://github.com/your-org/your-wp-template.git \
+  -d ./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
+npm create @pugpigjs/wp-project -- update \
+  -g https://github.com/your-org/your-wp-template.git \
+  -d ./my-project-server
 ```
 
 ## Safety Features
@@ -184,31 +213,16 @@ This CLI tool includes multiple safety checks to prevent accidental data loss:
 
 ## Requirements
 
-- Node.js 14 or higher
+- Node.js 24 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
+* `Rich Plugin`: A full-featured plugin template with Vue.js, SCSS, and an advanced build setup. Includes Vite build system with hot module replacement (HMR), Vue.js component support, SCSS preprocessing, Composer dependencies managed with PHP-Scoper, and utilities for seamless WordPress integration.
+
+* `Simple Plugin`: A lightweight plugin template with a simple Vite build setup, vanilla JavaScript, basic CSS, and minimal dependencies.
+
+* `Theme`: A WordPress theme template with a modern Vite-based build system, supporting modern CSS/JS compilation and a standard theme template structure.
 
 ## Development
 
@@ -216,19 +230,16 @@ 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
+node packages/create-wp-project/src/cli.js init -g . -d ./test-server
 
 # Or test the add command
-node packages/create-wp-project/src/cli.js add \
-  --git-url . \
-  --directory ./test-server
+node packages/create-wp-project/src/cli.js add -g . -d ./test-server
 
 # Or test the update command
-node packages/create-wp-project/src/cli.js update \
-  --git-url . \
-  --directory ./test-server
+node packages/create-wp-project/src/cli.js update -g . -d ./test-server
+
+# Test with a specific branch
+node packages/create-wp-project/src/cli.js init -g . -d ./test-server -b beta
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugpigjs/create-wp-project",
-  "version": "0.0.2-beta.0",
+  "version": "0.0.2-beta.2",
   "description": "CLI tool to scaffold WordPress plugins and themes from a template repo.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -8,6 +8,9 @@ import { updateProject } from './commands/update.js'
 
 const program = new Command()
 
+// Get default git URL from environment variable if set
+const defaultGitUrl = process.env.PUGPIG_WORDPRESS_TEMPLATE_REPO_URL
+
 program
   .name('create-wp-project')
   .description('CLI tool to scaffold WordPress plugins and themes from a template repo.')
@@ -17,16 +20,18 @@ 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')
+  .option('-g, --git-url <url>', 'Git repository URL or local path to template', defaultGitUrl)
+  .option('-t, --template-dir <path>', 'Template source directory', 'repo_template')
+  .option('-b, --branch <name>', 'Git branch to clone from', 'master')
   .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')
+  .option('-g, --git-url <url>', 'Git repository URL or local path to template', defaultGitUrl)
+  .option('-t, --template-dir <path>', 'Template source directory', 'repo_template')
+  .option('-b, --branch <name>', 'Git branch to clone from', 'master')
   .action(addTemplate)
 
 program
@@ -39,8 +44,9 @@ 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')
+  .option('-g, --git-url <url>', 'Git repository URL or local path to template', defaultGitUrl)
+  .option('-t, --template-dir <path>', 'Template source directory', 'repo_template')
+  .option('-b, --branch <name>', 'Git branch to clone from', 'master')
   .action(updateProject)
 
 program.parse()

package/src/commands/add.js

@@ -108,7 +108,7 @@ export async function addTemplate(options) {
 
   try {
     // Step 1: Clone repository
-    await cloneRepo(options.gitUrl, tempDir)
+    await cloneRepo(options.gitUrl, tempDir, options.branch)
 
     // Step 2: Copy selected template
     const spinner = ora(`Copying ${TEMPLATES[template].name} template...`).start()

package/src/commands/init.js

@@ -136,7 +136,7 @@ export async function initProject(options) {
 
   try {
     // Step 1: Clone repository
-    await cloneRepo(options.gitUrl, tempDir)
+    await cloneRepo(options.gitUrl, tempDir, options.branch)
 
     // Step 2: Copy root files from repo_template directory
     const templateRoot = path.join(tempDir, options.templateDir)

package/src/commands/update.js

@@ -146,7 +146,7 @@ export async function updateProject(options) {
 
   try {
     // Clone repository to get latest templates
-    await cloneRepo(options.gitUrl, tempDir)
+    await cloneRepo(options.gitUrl, tempDir, options.branch)
 
     const templateRoot = path.join(tempDir, options.templateDir)
 

package/src/utils/shared.js

@@ -116,8 +116,16 @@ export const prompts = {
  * Clone the git repository to a temporary directory, or copy from local path
  * @param {string} gitUrlOrPath - Git URL or local filesystem path
  * @param {string} tempDir - Temporary directory to clone/copy into
+ * @param {string} branch - Git branch to clone (optional, defaults to remote's default branch)
  */
-export async function cloneRepo(gitUrlOrPath, tempDir) {
+export async function cloneRepo(gitUrlOrPath, tempDir, branch = null) {
+  // Validate git URL is provided
+  if (!gitUrlOrPath) {
+    console.error(chalk.red('\n❌ Error: --git-url is required'))
+    console.error(chalk.yellow('Set PUGPIG_WORDPRESS_TEMPLATE_REPO_URL environment variable or provide --git-url flag'))
+    process.exit(1)
+  }
+
   // Check if it's a local path
   const isLocalPath = !gitUrlOrPath.startsWith('http://') &&
                       !gitUrlOrPath.startsWith('https://') &&
@@ -136,11 +144,16 @@ export async function cloneRepo(gitUrlOrPath, tempDir) {
       throw error
     }
   } else {
-    const spinner = ora('Cloning template repository...').start()
+    const branchMsg = branch ? ` (branch: ${branch})` : ''
+    const spinner = ora(`Cloning template repository${branchMsg}...`).start()
     try {
       const git = simpleGit()
-      await git.clone(gitUrlOrPath, tempDir, ['--depth', '1'])
-      spinner.succeed('Template repository cloned')
+      const cloneOptions = ['--depth', '1']
+      if (branch) {
+        cloneOptions.push('--branch', branch)
+      }
+      await git.clone(gitUrlOrPath, tempDir, cloneOptions)
+      spinner.succeed(`Template repository cloned${branchMsg}`)
     } catch (error) {
       spinner.fail('Failed to clone repository')
       throw error
@@ -328,7 +341,7 @@ export async function cleanup(tempDir) {
 }
 
 /**
- * Display next steps after project initialization or template addition
+ * Display next steps after project initialisation or template addition
  * @param {string} targetDir - The target directory where files were created
  * @param {string} projectName - The project name
  * @param {string} templateType - The template type key