plugship 1.0.1 → 1.0.3

package/README.md

@@ -1,173 +1,322 @@
 # plugship
 
-A CLI tool to deploy local WordPress plugins to remote WordPress sites.
+> Deploy WordPress plugins from your terminal to any WordPress site instantly.
 
-## Prerequisites
+[![npm version](https://img.shields.io/npm/v/plugship.svg)](https://www.npmjs.com/package/plugship)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-- Node.js 18+
-- A WordPress site with REST API enabled
-- An Administrator account with an [Application Password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/)
+A simple CLI tool to deploy local WordPress plugins to remote WordPress sites. No FTP, no cPanel — just `plugship deploy`.
 
-## Installation
+**[View on npm →](https://www.npmjs.com/package/plugship)**
+
+---
+
+## ✨ Features
+
+- 🚀 **One-command deploys** — `plugship deploy` and you're done
+- 🔐 **Secure** — uses WordPress Application Passwords (not your main password)
+- 🎯 **Multi-site** — configure once, deploy to staging/production/any site
+- 📦 **Smart packaging** — auto-excludes dev files (node_modules, tests, src, etc.)
+- 🔄 **Auto-updates** — replaces existing plugins automatically
+- 🌐 **No server access needed** — works entirely via WordPress REST API
+
+---
+
+## 📦 Installation
+
+### Global Install (Recommended)
 
 ```bash
 npm install -g plugship
 ```
 
-## Setup
+### Verify Installation
+
+```bash
+plugship --version
+```
+
+---
+
+## 🚀 Quick Start
+
+### Step 1: Install the Receiver Plugin
 
-### 1. Install the Receiver Plugin
+The `plugship-receiver` plugin must be installed on your WordPress site first. It adds secure REST endpoints to receive plugin uploads.
 
-The `plugship-receiver` companion plugin must be installed on your WordPress site. It adds a REST endpoint that accepts plugin ZIP uploads.
+**[Download plugship-receiver.zip →](https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip)**
 
-1. Download [plugship-receiver.zip](https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip) or get it from the [repo](https://github.com/shamim0902/plugship-receiver)
-2. Go to **Plugins > Add New > Upload Plugin** in WordPress admin
-3. Upload the ZIP and activate **PlugShip Receiver**
+1. Go to **Plugins > Add New > Upload Plugin** in WordPress admin
+2. Upload `plugship-receiver.zip`
+3. Activate **PlugShip Receiver**
 
-### 2. Create an Application Password
+**[View receiver plugin source →](https://github.com/shamim0902/plugship-receiver)**
+
+### Step 2: Create an Application Password
 
 1. Go to **Users > Profile** in WordPress admin
 2. Scroll to **Application Passwords**
-3. Enter a name (e.g. "plugship") and click **Add New Application Password**
-4. Copy the generated password
+3. Enter "plugship" as the name
+4. Click **Add New Application Password**
+5. Copy the generated password (you'll need it in the next step)
+
+**[Learn more about Application Passwords →](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/)**
 
-### 3. Configure a Site
+### Step 3: Configure Your First Site
 
 ```bash
 plugship init
 ```
 
-You will be prompted for:
+You'll be prompted for:
+- **Site alias** — a short name like "production" or "staging"
+- **WordPress site URL** — e.g., `https://example.com`
+- **Admin username** — your WordPress admin username
+- **Application Password** — paste the password from Step 2
+
+### Step 4: Deploy Your Plugin
+
+Navigate to your WordPress plugin directory:
 
-- **Site alias** — a short name for this site (e.g. "staging")
-- **Site URL** — your WordPress site URL (e.g. `https://example.com`)
-- **Username** — your WordPress admin username
-- **Application password** — the password from step 2
+```bash
+cd my-awesome-plugin/
+plugship deploy
+```
+
+✅ Done! Your plugin is deployed and activated on the remote site.
 
-The command will verify the connection, credentials, and receiver plugin status.
+---
 
-## Usage
+## 📚 Commands
 
-### Deploy a Plugin
+### `plugship deploy`
 
-Navigate to your WordPress plugin directory and run:
+Deploy the plugin from the current directory.
 
 ```bash
+# Deploy to default site
 plugship deploy
+
+# Deploy to a specific site
+plugship deploy --site staging
+
+# Deploy to all configured sites
+plugship deploy --all
+
+# Preview what would be deployed (no upload)
+plugship deploy --dry-run
+
+# Deploy without activating the plugin
+plugship deploy --no-activate
 ```
 
-This will:
+**What happens:**
+1. Detects your plugin from PHP headers
+2. Creates a ZIP excluding dev files
+3. Uploads to the WordPress site
+4. Installs/updates the plugin
+5. Activates it (unless `--no-activate`)
 
-1. Detect the plugin from PHP file headers
-2. Create a ZIP archive in the `build/` directory
-3. Upload and install the plugin on the remote site
-4. Activate the plugin
+---
 
-If you have multiple sites configured, you will be prompted to select one.
+### `plugship init`
 
-#### Options
+Add a new WordPress site to your configuration.
 
 ```bash
-plugship deploy --site <name>   # Deploy to a specific site
-plugship deploy --no-activate   # Deploy without activating the plugin
-plugship deploy --dry-run       # Preview what would be deployed without uploading
-plugship deploy --all           # Deploy to all configured sites
+plugship init
 ```
 
-### Check Site Status
+Interactive prompts guide you through:
+- Site alias
+- URL
+- Username
+- Application Password
 
-Verify connection, credentials, and receiver plugin before deploying:
+The CLI automatically tests the connection and verifies the receiver plugin is active.
 
-```bash
-plugship status                 # Check default or select a site
-plugship status --site <name>   # Check a specific site
-```
+---
+
+### `plugship status`
 
-### Manage Sites
+Check if a site is ready for deployment.
 
 ```bash
-plugship sites list                 # List all saved sites
-plugship sites remove <name>        # Remove a saved site
-plugship sites set-default <name>   # Set the default site
+# Check default site
+plugship status
+
+# Check a specific site
+plugship status --site staging
 ```
 
-## Commands
+Verifies:
+- ✅ REST API is accessible
+- ✅ Credentials are valid
+- ✅ User has `install_plugins` capability
+- ✅ Receiver plugin is active
 
-| Command | Description |
-| --- | --- |
-| `plugship init` | Configure a new WordPress site |
-| `plugship deploy` | Deploy the plugin from the current directory |
-| `plugship deploy --dry-run` | Preview deploy without uploading |
-| `plugship deploy --all` | Deploy to all configured sites |
-| `plugship status` | Check site connection and receiver status |
-| `plugship sites list` | List all saved sites |
-| `plugship sites remove <name>` | Remove a saved site |
-| `plugship sites set-default <name>` | Set the default site |
-| `plugship ignore` | Create `.plugshipignore` with default template |
-| `plugship ignore <patterns...>` | Add patterns to `.plugshipignore` |
-| `plugship --help` | Show help |
-| `plugship --version` | Show version |
+---
 
-## Plugin Detection
+### `plugship sites`
 
-The CLI detects your plugin by scanning `.php` files in the current directory for a standard WordPress plugin header:
+Manage your saved sites.
 
-```php
-<?php
-/**
- * Plugin Name: My Plugin
- * Version: 1.0.0
- * Text Domain: my-plugin
- */
+```bash
+# List all configured sites
+plugship sites list
+
+# Set the default site
+plugship sites set-default production
+
+# Remove a site
+plugship sites remove staging
 ```
 
-The `Text Domain` is used as the plugin slug. If not provided, the slug is derived from the plugin name.
+---
 
-## Ignoring Files
+### `plugship ignore`
 
-Use the `ignore` command to create a `.plugshipignore` file with a default template:
+Manage file exclusions for deployment.
 
 ```bash
+# Create .plugshipignore with default template
 plugship ignore
-```
 
-Or add specific patterns directly:
-
-```bash
-plugship ignore "src/**" "*.map" composer.json
+# Add specific patterns
+plugship ignore "src/**" "*.map" "composer.json"
 ```
 
-You can also manually create or edit `.plugshipignore` in your plugin directory to exclude files and folders from the deployment ZIP:
+Creates a `.plugshipignore` file in your plugin directory. Example:
 
 ```
 # .plugshipignore
 src/**
-assets/scss/**
+*.map
 webpack.config.js
 package.json
 package-lock.json
 composer.json
-composer.lock
-*.map
 ```
 
-- One pattern per line
-- Lines starting with `#` are comments
-- Blank lines are ignored
-- Supports `dir/**` (directory and contents), `*.ext` (extension match), and exact names
+**Already excluded by default:**
+`node_modules`, `.git`, `.env`, `*.log`, `.vscode`, `.idea`, `tests`, `.github`, `build`
+
+---
+
+## 💡 Usage Examples
+
+### Multi-Site Workflow
+
+Configure multiple environments:
+
+```bash
+plugship init  # Add production
+plugship init  # Add staging
+plugship init  # Add local test site
+```
+
+Deploy to each:
+
+```bash
+plugship deploy --site staging     # Test on staging first
+plugship deploy --site production  # Then push to prod
+```
+
+Or deploy everywhere at once:
+
+```bash
+plugship deploy --all
+```
+
+---
+
+### Preview Before Deploy
+
+See what would be deployed without uploading:
+
+```bash
+plugship deploy --dry-run
+```
+
+Output shows:
+- Plugin name, version, slug
+- ZIP file size
+- Target site(s)
+- Activation setting
 
-The following are always excluded by default:
+---
 
-`node_modules`, `.git`, `.DS_Store`, `.env`, `*.log`, `.vscode`, `.idea`, `tests`, `phpunit.xml`, `.phpunit.result.cache`, `.github`, `build`
+### Exclude Dev Files
 
-## Configuration
+Auto-suggest on first deploy, or create manually:
 
-Site credentials are stored in `~/.plugship/config.json` with `0600` file permissions. The config file looks like:
+```bash
+plugship ignore
+```
+
+Edit `.plugshipignore` to add project-specific exclusions:
+
+```
+# Custom exclusions
+assets/src/**
+*.scss
+*.ts
+tsconfig.json
+```
+
+---
+
+## 🔧 How It Works
+
+```
+┌──────────────┐
+│ Your Plugin  │
+│  Directory   │
+└──────┬───────┘
+       │
+       │ plugship deploy
+       ▼
+┌──────────────┐
+│   ZIP File   │  (excludes dev files)
+└──────┬───────┘
+       │
+       │ Upload via REST API
+       ▼
+┌──────────────────────┐
+│  WordPress Site      │
+│  (plugship-receiver) │
+└──────┬───────────────┘
+       │
+       │ Install/Update
+       ▼
+┌──────────────┐
+│    Plugin    │
+│   Active!    │
+└──────────────┘
+```
+
+The [plugship-receiver](https://github.com/shamim0902/plugship-receiver) plugin adds two REST endpoints:
+
+- `GET /wp-json/plugship/v1/status` — Health check
+- `POST /wp-json/plugship/v1/deploy` — Accept plugin ZIP upload
+
+WordPress's native `Plugin_Upgrader` with `overwrite_package => true` handles installation. Existing plugins are replaced automatically.
+
+---
+
+## ⚙️ Configuration
+
+Config file: `~/.plugship/config.json`
 
 ```json
 {
-  "defaultSite": "staging",
+  "defaultSite": "production",
   "sites": {
+    "production": {
+      "url": "https://example.com",
+      "username": "admin",
+      "appPassword": "xxxx xxxx xxxx xxxx"
+    },
     "staging": {
       "url": "https://staging.example.com",
       "username": "admin",
@@ -177,15 +326,120 @@ Site credentials are stored in `~/.plugship/config.json` with `0600` file permis
 }
 ```
 
-## How It Works
+**File permissions:** `0600` (only you can read/write)
 
-The WordPress REST API does not support direct ZIP upload for plugin installation. The `plugship-receiver` companion plugin adds two custom endpoints:
+---
 
-- `GET /wp-json/plugship/v1/status` — Health check
-- `POST /wp-json/plugship/v1/deploy` — Accepts a ZIP file and installs it using WordPress's built-in `Plugin_Upgrader` with `overwrite_package => true`
+## 🔒 Security
+
+- ✅ **Application Passwords only** — never uses your main WordPress password
+- ✅ **Local storage** — credentials stored in `~/.plugship/config.json` with restricted permissions
+- ✅ **Capability checks** — only users with `install_plugins` can deploy
+- ✅ **ZIP validation** — receiver plugin validates MIME type and ZIP integrity
+- ✅ **Path traversal protection** — rejects ZIPs with malicious entries
+- ✅ **50 MB upload limit** — prevents abuse
+
+---
+
+## 🛠️ Requirements
+
+- **Node.js** 18 or higher
+- **WordPress** 5.8 or higher
+- **Admin account** with Application Passwords enabled
+
+---
+
+## ❓ Troubleshooting
+
+### "Receiver plugin not found"
+
+**Problem:** The plugship-receiver plugin isn't active on your WordPress site.
+
+**Solution:**
+1. Download: https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip
+2. Upload via **Plugins > Add New > Upload Plugin**
+3. Activate **PlugShip Receiver**
+4. Run `plugship status` to verify
+
+---
+
+### "Authentication failed"
+
+**Problem:** Your Application Password is incorrect or expired.
+
+**Solution:**
+1. Go to **Users > Profile** in WordPress admin
+2. Delete the old Application Password
+3. Create a new one
+4. Run `plugship init` again and paste the new password
+
+---
+
+### "Cannot reach REST API"
+
+**Problem:** The WordPress REST API isn't accessible.
+
+**Solution:**
+1. Check that `https://yoursite.com/wp-json/` loads in your browser
+2. Temporarily disable security plugins (Wordfence, iThemes, etc.)
+3. Check hosting firewall rules
+4. Verify mod_rewrite is enabled (permalinks must work)
+
+---
+
+### Deploy fails with "permission denied"
+
+**Problem:** User doesn't have `install_plugins` capability.
+
+**Solution:**
+- Ensure you're using an **Administrator** account
+- Other roles (Editor, Author, etc.) can't install plugins
+
+---
+
+## 📖 Plugin Detection
+
+PlugShip detects your plugin by scanning `.php` files in the current directory for WordPress plugin headers:
+
+```php
+<?php
+/**
+ * Plugin Name: My Awesome Plugin
+ * Version: 1.0.0
+ * Text Domain: my-awesome-plugin
+ */
+```
+
+- The `Text Domain` is used as the plugin slug
+- If no `Text Domain` is found, the slug is derived from the plugin name
+- Version is read from the header and displayed during deploy
+
+---
+
+## 🌐 Links
+
+- **npm package:** https://www.npmjs.com/package/plugship
+- **Receiver plugin:** https://github.com/shamim0902/plugship-receiver
+- **Report issues:** https://github.com/shamim0902/plugship/issues
+
+---
+
+## 📄 License
+
+MIT © [shamim0902](https://github.com/shamim0902)
+
+---
+
+## 🙌 Contributing
+
+Contributions are welcome! Please open an issue or PR.
 
-If the plugin already exists on the site, it is replaced with the uploaded version.
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -am 'Add my feature'`
+4. Push: `git push origin feature/my-feature`
+5. Open a Pull Request
 
-## License
+---
 
-MIT
+**Made with ❤️ for the WordPress community**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugship",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Deploy local WordPress plugins to remote sites from the command line",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,11 +1,17 @@
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
 
 const program = new Command();
 
 program
   .name('plugship')
   .description('Deploy local WordPress plugins to remote sites')
-  .version('1.0.0');
+  .version(pkg.version);
 
 program
   .command('init')

package/src/commands/ignore.js

@@ -19,7 +19,6 @@ const DEFAULT_TEMPLATE = `# .plugshipignore
 # Build tools
 package.json
 package-lock.json
-composer.json
 composer.lock
 webpack.config.js
 `;

package/src/lib/constants.js

@@ -22,17 +22,10 @@ export const PLUGIN_HEADER_FIELDS = {
 };
 
 export const DEFAULT_EXCLUDES = [
+  '.*',
   'node_modules/**',
-  '.git/**',
-  '.DS_Store',
-  '.env',
   '*.log',
-  '.vscode/**',
-  '.idea/**',
   'tests/**',
   'phpunit.xml',
-  '.phpunit.result.cache',
-  '.github/**',
   'build/**',
-  '.plugshipignore',
 ];

package/src/lib/deployer.js

@@ -138,24 +138,98 @@ export async function deploy({ siteName, activate = true, dryRun = false, all =
     // Upload
     s.start('Uploading plugin...');
     let result;
+    let uploadWarnings = null;
     try {
       result = await api.deployPlugin(zipPath, `${plugin.slug}.zip`);
-      s.succeed('Plugin uploaded and installed');
     } catch (err) {
-      s.fail('Upload failed');
-      if (targets.length > 1) {
-        logger.error(`Deploy to ${site.name} failed: ${err.message}`);
-        continue;
+      // Non-JSON response — plugin might still have installed
+      if (err.body && err.body.rawWarnings) {
+        s.succeed('Plugin uploaded');
+        uploadWarnings = err.body.rawWarnings;
+      } else {
+        s.fail('Upload failed');
+        if (targets.length > 1) {
+          logger.error(`Deploy to ${site.name} failed: ${err.message}`);
+          continue;
+        }
+        throw new DeployError(`Upload failed: ${err.message}`);
       }
-      throw new DeployError(`Deploy failed: ${err.message}`);
     }
 
+    // If we got warnings instead of clean JSON, verify installation via WP API
+    if (uploadWarnings) {
+      s.start('Verifying installation...');
+      try {
+        const pluginInfo = await api.getPlugin(`${plugin.slug}/${plugin.slug}`);
+        s.succeed('Plugin installed successfully');
+        result = {
+          success: true,
+          name: pluginInfo.name || plugin.name,
+          version: pluginInfo.version || plugin.version,
+          activated: pluginInfo.status === 'active',
+        };
+        for (const w of uploadWarnings) {
+          logger.warn(w);
+        }
+      } catch {
+        // Try alternative slug format (slug/main-file)
+        try {
+          const plugins = await api.getPlugins();
+          const found = plugins.find((p) => p.textdomain === plugin.slug || p.plugin.startsWith(plugin.slug + '/'));
+          if (found) {
+            s.succeed('Plugin installed successfully');
+            result = {
+              success: true,
+              name: found.name || plugin.name,
+              version: found.version || plugin.version,
+              activated: found.status === 'active',
+            };
+            for (const w of uploadWarnings) {
+              logger.warn(w);
+            }
+          } else {
+            s.fail('Installation could not be verified');
+            for (const w of uploadWarnings) {
+              logger.error(w);
+            }
+            if (targets.length > 1) continue;
+            throw new DeployError('Plugin installation could not be verified.');
+          }
+        } catch (verifyErr) {
+          if (verifyErr instanceof DeployError) throw verifyErr;
+          s.fail('Installation could not be verified');
+          for (const w of uploadWarnings) {
+            logger.error(w);
+          }
+          if (targets.length > 1) continue;
+          throw new DeployError('Plugin installation could not be verified.');
+        }
+      }
+    } else {
+      // Clean JSON response
+      if (!result.success) {
+        s.fail('Installation failed');
+        logger.error('Plugin uploaded but installation failed.');
+        if (targets.length > 1) continue;
+        throw new DeployError('Installation failed on remote server.');
+      }
+      s.succeed('Plugin uploaded and installed');
+    }
+
+    // Show warnings if any
+    if (result.warnings) {
+      logger.warn(`Warning: ${result.warnings}`);
+    }
+
+    // Activation status
     if (result.activated) {
       logger.success(`Plugin "${result.name || plugin.name}" v${result.version || plugin.version} is active on ${site.url}`);
     } else {
       logger.success(`Plugin "${result.name || plugin.name}" v${result.version || plugin.version} installed on ${site.url}`);
-      if (activate && !result.activated) {
-        logger.info('Plugin was not activated (may already be active or activation was skipped).');
+      if (activate && result.activation_error) {
+        logger.error(`Activation failed: ${result.activation_error}`);
+      } else if (activate) {
+        logger.warn('Plugin installed but not activated. It may have errors — check WordPress admin.');
       }
     }
   }

package/src/lib/wordpress-api.js

@@ -88,14 +88,53 @@ export class WordPressApi {
       body: form.getBuffer(),
     });
 
-    const contentType = res.headers.get('content-type') || '';
-    const body = contentType.includes('application/json') ? await res.json() : await res.text();
+    const rawBody = await res.text();
 
-    if (!res.ok) {
-      const msg = typeof body === 'object' && body.message ? body.message : `Upload failed (HTTP ${res.status})`;
-      throw new ApiError(msg, res.status, body);
+    // Try to extract JSON from response (may have HTML errors prepended)
+    const body = this._extractJson(rawBody);
+
+    if (body) {
+      if (!res.ok && body.message) {
+        throw new ApiError(body.message, res.status, body);
+      }
+      return body;
     }
 
-    return body;
+    // No valid JSON found — response is pure HTML/error
+    // Extract readable error from HTML
+    const warnings = this._extractHtmlErrors(rawBody);
+    throw new ApiError(
+      'non_json_response',
+      res.status,
+      { rawWarnings: warnings }
+    );
+  }
+
+  _extractJson(text) {
+    // Try direct parse first
+    try {
+      return JSON.parse(text);
+    } catch {
+      // JSON might be buried after HTML errors — find it
+      const jsonStart = text.indexOf('{"');
+      if (jsonStart > 0) {
+        try {
+          return JSON.parse(text.slice(jsonStart));
+        } catch {
+          // ignore
+        }
+      }
+      return null;
+    }
+  }
+
+  _extractHtmlErrors(html) {
+    const errors = [];
+    const regex = /<b>(Warning|Fatal error|Parse error|Notice)<\/b>:\s*(.*?)<br/gi;
+    let match;
+    while ((match = regex.exec(html)) !== null) {
+      errors.push(match[1] + ': ' + match[2].replace(/<[^>]+>/g, '').trim());
+    }
+    return errors.length > 0 ? errors : ['Server returned non-JSON response'];
   }
 }

package/src/lib/zipper.js

@@ -61,5 +61,10 @@ function matchGlob(filePath, pattern) {
   if (pattern.startsWith('*.')) {
     return filePath.endsWith(pattern.slice(1));
   }
+  // Dotfile pattern — match root-level files/dirs starting with .
+  if (pattern === '.*') {
+    const firstSegment = filePath.split('/')[0];
+    return firstSegment.startsWith('.');
+  }
   return filePath === pattern;
 }