plugship 1.0.2 → 1.0.4

package/README.md

@@ -2,119 +2,200 @@
 
 > Deploy WordPress plugins from your terminal to any WordPress site instantly.
 
+[![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)
+
 A simple CLI tool to deploy local WordPress plugins to remote WordPress sites. No FTP, no cPanel — just `plugship deploy`.
 
-## Quick Start
+**[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
 
-### 1. Install
+### Global Install (Recommended)
 
 ```bash
 npm install -g plugship
 ```
 
-### 2. Install Receiver Plugin
+### Verify Installation
+
+```bash
+plugship --version
+```
+
+---
+
+## 🚀 Quick Start
 
-Download and install the companion plugin on your WordPress site:
+### Step 1: Install the Receiver Plugin
 
-**[Download plugship-receiver.zip](https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip)**
+The `plugship-receiver` plugin must be installed on your WordPress site first. It adds secure REST endpoints to receive plugin uploads.
+
+**[Download plugship-receiver.zip →](https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip)**
 
 1. Go to **Plugins > Add New > Upload Plugin** in WordPress admin
-2. Upload the ZIP file
+2. Upload `plugship-receiver.zip`
 3. Activate **PlugShip Receiver**
 
-### 3. Configure Your Site
+**[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 "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/)**
+
+### Step 3: Configure Your First Site
 
 ```bash
 plugship init
 ```
 
 You'll be prompted for:
-- Site alias (e.g., "production")
-- WordPress site URL
-- Admin username
-- [Application Password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/) (create one in Users > Profile)
+- **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
 
-### 4. Deploy
+### Step 4: Deploy Your Plugin
 
-Navigate to your plugin directory and run:
+Navigate to your WordPress plugin directory:
 
 ```bash
+cd my-awesome-plugin/
 plugship deploy
 ```
 
-Done! Your plugin is deployed and activated.
+✅ Done! Your plugin is deployed and activated on the remote site.
 
 ---
 
-## Commands
+## 📚 Commands
 
 ### `plugship deploy`
 
 Deploy the plugin from the current directory.
 
 ```bash
-plugship deploy                 # Deploy to default site
-plugship deploy --site staging  # Deploy to specific site
-plugship deploy --all           # Deploy to all configured sites
-plugship deploy --dry-run       # Preview without uploading
-plugship deploy --no-activate   # Deploy without activating
+# 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
 ```
 
+**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`)
+
+---
+
 ### `plugship init`
 
-Add a new WordPress site.
+Add a new WordPress site to your configuration.
 
 ```bash
 plugship init
 ```
 
+Interactive prompts guide you through:
+- Site alias
+- URL
+- Username
+- Application Password
+
+The CLI automatically tests the connection and verifies the receiver plugin is active.
+
+---
+
 ### `plugship status`
 
 Check if a site is ready for deployment.
 
 ```bash
-plugship status                 # Check default site
-plugship status --site staging  # Check specific site
+# Check default site
+plugship status
+
+# Check a specific site
+plugship status --site staging
 ```
 
+Verifies:
+- ✅ REST API is accessible
+- ✅ Credentials are valid
+- ✅ User has `install_plugins` capability
+- ✅ Receiver plugin is active
+
+---
+
 ### `plugship sites`
 
 Manage your saved sites.
 
 ```bash
-plugship sites list                 # List all sites
-plugship sites set-default staging  # Set default site
-plugship sites remove staging       # Remove a site
-```
+# List all configured sites
+plugship sites list
 
-### `plugship ignore`
+# Set the default site
+plugship sites set-default production
 
-Exclude files from deployment.
-
-```bash
-plugship ignore                     # Create .plugshipignore template
-plugship ignore "src/**" "*.map"    # Add patterns
+# Remove a site
+plugship sites remove staging
 ```
 
 ---
 
-## Ignoring Files
+### `plugship ignore`
 
-Create a `.plugshipignore` file to exclude files from deployment:
+Manage file exclusions for deployment.
 
 ```bash
+# Create .plugshipignore with default template
 plugship ignore
+
+# Add specific patterns
+plugship ignore "src/**" "*.map" "composer.json"
 ```
 
-This creates a template with common exclusions. Edit it to add your own:
+Creates a `.plugshipignore` file in your plugin directory. Example:
 
 ```
 # .plugshipignore
 src/**
 *.map
+webpack.config.js
 package.json
+package-lock.json
 composer.json
-webpack.config.js
 ```
 
 **Already excluded by default:**
@@ -122,64 +203,108 @@ webpack.config.js
 
 ---
 
-## How It Works
+## 💡 Usage Examples
 
-1. **Detects your plugin** from the WordPress plugin header in your PHP files
-2. **Creates a ZIP** with only the files you need (excludes dev files)
-3. **Uploads via REST API** to the WordPress site using the receiver plugin
-4. **Installs and activates** the plugin automatically
+### Multi-Site Workflow
 
-The [plugship-receiver](https://github.com/shamim0902/plugship-receiver) plugin adds secure REST endpoints to accept the upload. Only admin users with Application Passwords can deploy.
+Configure multiple environments:
 
----
-
-## Examples
+```bash
+plugship init  # Add production
+plugship init  # Add staging
+plugship init  # Add local test site
+```
 
-### Deploy to Staging
+Deploy to each:
 
 ```bash
-cd my-plugin/
-plugship deploy --site staging
+plugship deploy --site staging     # Test on staging first
+plugship deploy --site production  # Then push to prod
 ```
 
-### Deploy to All Sites
+Or deploy everywhere at once:
 
 ```bash
 plugship deploy --all
 ```
 
-### Preview What Would Be Deployed
+---
+
+### Preview Before Deploy
+
+See what would be deployed without uploading:
 
 ```bash
 plugship deploy --dry-run
 ```
 
-### Check Connection Before Deploying
+Output shows:
+- Plugin name, version, slug
+- ZIP file size
+- Target site(s)
+- Activation setting
+
+---
+
+### Exclude Dev Files
+
+Auto-suggest on first deploy, or create manually:
 
 ```bash
-plugship status
+plugship ignore
+```
+
+Edit `.plugshipignore` to add project-specific exclusions:
+
+```
+# Custom exclusions
+assets/src/**
+*.scss
+*.ts
+tsconfig.json
 ```
 
 ---
 
-## Requirements
+## 🔧 How It Works
 
-- **Node.js** 18 or higher
-- **WordPress** 5.8 or higher
-- **Admin account** with Application Passwords enabled
+```
+┌──────────────┐
+│ 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:
 
-## Security
+- `GET /wp-json/plugship/v1/status` — Health check
+- `POST /wp-json/plugship/v1/deploy` — Accept plugin ZIP upload
 
-- All credentials are stored locally in `~/.plugship/config.json` with `0600` permissions
-- Uses WordPress Application Passwords (not your main password)
-- Only users with `install_plugins` capability can deploy
-- All uploads are authenticated via WordPress REST API
+WordPress's native `Plugin_Upgrader` with `overwrite_package => true` handles installation. Existing plugins are replaced automatically.
 
 ---
 
-## Configuration
+## ⚙️ Configuration
 
 Config file: `~/.plugship/config.json`
 
@@ -201,43 +326,120 @@ Config file: `~/.plugship/config.json`
 }
 ```
 
+**File permissions:** `0600` (only you can read/write)
+
+---
+
+## 🔒 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
+## ❓ Troubleshooting
 
 ### "Receiver plugin not found"
 
-The plugship-receiver plugin isn't active on your WordPress site.
+**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 and activate in WordPress admin
+2. Upload via **Plugins > Add New > Upload Plugin**
+3. Activate **PlugShip Receiver**
+4. Run `plugship status` to verify
+
+---
 
 ### "Authentication failed"
 
-Your Application Password is incorrect.
+**Problem:** Your Application Password is incorrect or expired.
 
+**Solution:**
 1. Go to **Users > Profile** in WordPress admin
-2. Generate a new Application Password
-3. Run `plugship init` again
+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"
 
-Your WordPress REST API isn't accessible.
+**Problem:** The WordPress REST API isn't accessible.
 
-- Check that `https://yoursite.com/wp-json/` loads
-- Disable security plugins temporarily to test
-- Check for firewall/hosting restrictions
+**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)
 
 ---
 
-## Links
+### Deploy fails with "permission denied"
 
-- [npm package](https://www.npmjs.com/package/plugship)
-- [Receiver plugin](https://github.com/shamim0902/plugship-receiver)
-- [Report issues](https://github.com/shamim0902/plugship/issues)
+**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
 
 ---
 
-## License
+## 📖 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.
+
+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
+
+---
 
-MIT
+**Made with ❤️ for the WordPress community**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugship",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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

@@ -10,7 +10,7 @@ const DEFAULT_TEMPLATE = `# .plugshipignore
 #
 # The following are always excluded by default (no need to list them):
 #   node_modules, .git, .github, .DS_Store, .env, *.log,
-#   .vscode, .idea, tests, phpunit.xml, build
+#   .vscode, .idea, tests, phpunit.xml, builds
 
 # Source files (uncomment as needed)
 # src/**
@@ -19,7 +19,6 @@ const DEFAULT_TEMPLATE = `# .plugshipignore
 # Build tools
 package.json
 package-lock.json
-composer.json
 composer.lock
 webpack.config.js
 `;

package/src/commands/init.js

@@ -1,4 +1,4 @@
-import { input, password } from '@inquirer/prompts';
+import { input, password, confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { addSite } from '../lib/config.js';
 import { WordPressApi } from '../lib/wordpress-api.js';
@@ -13,87 +13,119 @@ export async function initCommand() {
     validate: (v) => (v.trim() ? true : 'Required'),
   });
 
-  const url = await input({
-    message: 'WordPress site URL:',
-    validate: (v) => {
-      if (!v.trim()) return 'Required';
-      try {
-        const parsed = new URL(v);
-        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-          return 'URL must start with https:// or http://';
+  let siteUrl, username, appPassword, api;
+  let connected = false;
+
+  // Loop until connection + auth succeed
+  while (!connected) {
+    siteUrl = await input({
+      message: 'WordPress site URL:',
+      validate: (v) => {
+        if (!v.trim()) return 'Required';
+        try {
+          const parsed = new URL(v);
+          if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            return 'URL must start with https:// or http://';
+          }
+          return true;
+        } catch {
+          return 'Invalid URL';
         }
-        return true;
-      } catch {
-        return 'Invalid URL';
-      }
-    },
-  });
+      },
+    });
 
-  const username = await input({
-    message: 'WordPress username:',
-    validate: (v) => (v.trim() ? true : 'Required'),
-  });
+    siteUrl = siteUrl.replace(/\/+$/, '');
 
-  const appPassword = await password({
-    message: 'Application password:',
-    mask: '*',
-    validate: (v) => (v.trim() ? true : 'Required'),
-  });
+    // Test connection
+    const spin = logger.spinner('Testing connection to WordPress REST API...');
+    spin.start();
 
-  const siteUrl = url.replace(/\/+$/, '');
-  const api = new WordPressApi({ url: siteUrl, username, appPassword });
+    try {
+      const tempApi = new WordPressApi({ url: siteUrl, username: '', appPassword: '' });
+      await tempApi.testConnection();
+      spin.succeed('REST API is accessible');
+    } catch (err) {
+      spin.stop();
+      spin.clear();
+      logger.error('Cannot reach WordPress REST API');
+      logger.error(`Make sure ${siteUrl}/wp-json/ is accessible.\n  ${err.message}`);
+      console.log('');
+      const retry = await confirm({ message: 'Try a different URL?', default: true });
+      if (!retry) return;
+      continue;
+    }
 
-  // Test connection
-  const spin = logger.spinner('Testing connection to WordPress REST API...');
-  spin.start();
+    // Loop until auth succeeds or user quits
+    let authenticated = false;
+    while (!authenticated) {
+      username = await input({
+        message: 'WordPress username:',
+        validate: (v) => (v.trim() ? true : 'Required'),
+      });
 
-  try {
-    await api.testConnection();
-    spin.succeed('REST API is accessible');
-  } catch (err) {
-    spin.fail('Cannot reach WordPress REST API');
-    logger.error(`Make sure ${siteUrl}/wp-json/ is accessible.\n  ${err.message}`);
-    process.exitCode = 1;
-    return;
-  }
+      appPassword = await password({
+        message: 'Application password:',
+        mask: '*',
+        validate: (v) => (v.trim() ? true : 'Required'),
+      });
 
-  // Test authentication
-  spin.start('Verifying credentials...');
-  try {
-    const user = await api.testAuth();
-    const caps = user.capabilities || {};
-    if (!caps.install_plugins) {
-      spin.fail('User does not have the "install_plugins" capability');
-      logger.error('The user must be an Administrator to deploy plugins.');
-      process.exitCode = 1;
-      return;
+      api = new WordPressApi({ url: siteUrl, username, appPassword });
+
+      const spin2 = logger.spinner('Verifying credentials...');
+      spin2.start();
+      try {
+        const user = await api.testAuth();
+        const caps = user.capabilities || {};
+        if (!caps.install_plugins) {
+          spin2.stop();
+          spin2.clear();
+          logger.error('User does not have the "install_plugins" capability');
+          logger.error('The user must be an Administrator to deploy plugins.');
+          console.log('');
+          const retry = await confirm({ message: 'Try different credentials?', default: true });
+          if (!retry) return;
+          continue;
+        }
+        spin2.succeed(`Authenticated as "${user.name}"`);
+        authenticated = true;
+      } catch (err) {
+        spin2.stop();
+        spin2.clear();
+        logger.error(`Authentication failed`);
+        logger.error(`Check your username and application password.\n  ${err.message}`);
+        console.log('');
+        const retry = await confirm({ message: 'Try again?', default: true });
+        if (!retry) return;
+      }
     }
-    spin.succeed(`Authenticated as "${user.name}"`);
-  } catch (err) {
-    spin.fail('Authentication failed');
-    logger.error(`Check your username and application password.\n  ${err.message}`);
-    process.exitCode = 1;
-    return;
+
+    connected = true;
   }
 
   // Check receiver plugin
-  spin.start('Checking for plugship-receiver plugin...');
-  try {
-    const status = await api.checkReceiver();
-    spin.succeed(`Receiver plugin active (v${status.version})`);
-  } catch {
-    spin.warn('Receiver plugin not detected');
-    console.log('');
-    logger.warn(
-      'The plugship-receiver plugin must be installed and activated on your WordPress site.'
-    );
-    console.log(
-      chalk.dim(
-        `  1. Download: ${RECEIVER_DOWNLOAD_URL}\n` +
-        '  2. Upload and activate in WordPress admin (Plugins > Add New > Upload Plugin)\n' +
-        '  3. Run "plugship init" again to verify\n'
-      )
-    );
+  let receiverActive = false;
+  while (!receiverActive) {
+    const spin = logger.spinner('Checking for plugship-receiver plugin...');
+    spin.start();
+    try {
+      const status = await api.checkReceiver();
+      spin.succeed(`Receiver plugin active (v${status.version})`);
+      receiverActive = true;
+    } catch {
+      spin.warn('Receiver plugin not detected');
+      console.log('');
+      logger.warn(
+        'The plugship-receiver plugin must be installed and activated on your WordPress site.'
+      );
+      console.log(
+        chalk.dim(
+          `  1. Download: ${RECEIVER_DOWNLOAD_URL}\n` +
+          '  2. Upload and activate in WordPress admin (Plugins > Add New > Upload Plugin)\n'
+        )
+      );
+      const retry = await confirm({ message: 'Check again?', default: true });
+      if (!retry) break;
+    }
   }
 
   // Save config
@@ -103,5 +135,12 @@ export async function initCommand() {
     appPassword,
   });
 
-  logger.success(`Site "${name.trim()}" saved and set as default.\n`);
+  logger.success(`Site "${name.trim()}" saved and set as default.`);
+  console.log(chalk.bold('\nNext steps:\n'));
+  console.log(`  Navigate to your plugin directory and run:\n`);
+  console.log(chalk.cyan(`    plugship deploy\n`));
+  console.log(chalk.dim(`  Other useful commands:`));
+  console.log(chalk.dim(`    plugship deploy --dry-run       Preview without uploading`));
+  console.log(chalk.dim(`    plugship deploy --site ${name.trim()}   Deploy to this site`));
+  console.log(chalk.dim(`    plugship ignore                 Set up file exclusions\n`));
 }

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',
+  'builds/**',
 ];

package/src/lib/deployer.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { access } from 'node:fs/promises';
+import { access, stat } from 'node:fs/promises';
 import { select, confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import { getSite, listSites } from './config.js';
@@ -83,12 +83,37 @@ export async function deploy({ siteName, activate = true, dryRun = false, all =
   // Detect plugin
   const plugin = await detectPlugin(cwd);
 
-  // Build ZIP once (shared across all targets)
-  const spin = logger.spinner('Creating ZIP archive...');
-  spin.start();
-  const { zipPath, size } = await createPluginZip(cwd, plugin.slug);
-  const sizeMB = (size / 1024 / 1024).toFixed(2);
-  spin.succeed(`ZIP created (${sizeMB} MB)`);
+  // Check for existing ZIP
+  const existingZipPath = join(cwd, 'builds', `${plugin.slug}.zip`);
+  let zipPath, size;
+
+  try {
+    const zipStat = await stat(existingZipPath);
+    const sizeMB = (zipStat.size / 1024 / 1024).toFixed(2);
+    logger.info(`Existing ZIP found: builds/${plugin.slug}.zip (${sizeMB} MB)`);
+    const action = await select({
+      message: 'What do you want to do?',
+      choices: [
+        { name: 'Use existing ZIP', value: 'existing' },
+        { name: 'Build a new ZIP', value: 'rebuild' },
+      ],
+    });
+    if (action === 'rebuild') {
+      const spin = logger.spinner('Creating ZIP archive...');
+      spin.start();
+      ({ zipPath, size } = await createPluginZip(cwd, plugin.slug));
+      spin.succeed(`ZIP created (${(size / 1024 / 1024).toFixed(2)} MB)`);
+    } else {
+      zipPath = existingZipPath;
+      size = zipStat.size;
+      logger.success(`Using existing ZIP (${sizeMB} MB)`);
+    }
+  } catch {
+    const spin = logger.spinner('Creating ZIP archive...');
+    spin.start();
+    ({ zipPath, size } = await createPluginZip(cwd, plugin.slug));
+    spin.succeed(`ZIP created (${(size / 1024 / 1024).toFixed(2)} MB)`);
+  }
 
   // Dry run — show summary and exit
   if (dryRun) {
@@ -138,24 +163,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

@@ -21,7 +21,7 @@ async function loadIgnorePatterns(sourceDir) {
 }
 
 export async function createPluginZip(sourceDir, slug) {
-  const buildDir = join(sourceDir, 'build');
+  const buildDir = join(sourceDir, 'builds');
   await mkdir(buildDir, { recursive: true });
   const zipName = `${slug}.zip`;
   const zipPath = join(buildDir, zipName);
@@ -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;
 }