plugship 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shamim0902
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# plugship
+
+A CLI tool to deploy local WordPress plugins to remote WordPress sites.
+
+## Prerequisites
+
+- 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/)
+
+## Installation
+
+```bash
+npm install -g plugship
+```
+
+## Setup
+
+### 1. Install the Receiver Plugin
+
+The `plugship-receiver` companion plugin must be installed on your WordPress site. It adds a REST endpoint that accepts plugin ZIP uploads.
+
+1. Get [plugship-receiver](https://github.com/plugship/plugship-receiver) and copy `plugship-receiver.php` to your site's `wp-content/plugins/` directory
+2. Activate **PlugShip Receiver** from the WordPress admin Plugins page
+
+### 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. Configure a Site
+
+```bash
+plugship init
+```
+
+You will be prompted for:
+
+- **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
+
+The command will verify the connection, credentials, and receiver plugin status.
+
+## Usage
+
+### Deploy a Plugin
+
+Navigate to your WordPress plugin directory and run:
+
+```bash
+plugship deploy
+```
+
+This will:
+
+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.
+
+#### Options
+
+```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
+```
+
+### Check Site Status
+
+Verify connection, credentials, and receiver plugin before deploying:
+
+```bash
+plugship status                 # Check default or select a site
+plugship status --site <name>   # Check a specific site
+```
+
+### Manage Sites
+
+```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
+```
+
+## Commands
+
+| 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
+
+The CLI detects your plugin by scanning `.php` files in the current directory for a standard WordPress plugin header:
+
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ * Version: 1.0.0
+ * Text Domain: my-plugin
+ */
+```
+
+The `Text Domain` is used as the plugin slug. If not provided, the slug is derived from the plugin name.
+
+## Ignoring Files
+
+Use the `ignore` command to create a `.plugshipignore` file with a default template:
+
+```bash
+plugship ignore
+```
+
+Or add specific patterns directly:
+
+```bash
+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:
+
+```
+# .plugshipignore
+src/**
+assets/scss/**
+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
+
+The following are always excluded by default:
+
+`node_modules`, `.git`, `.DS_Store`, `.env`, `*.log`, `.vscode`, `.idea`, `tests`, `phpunit.xml`, `.phpunit.result.cache`, `.github`, `build`
+
+## Configuration
+
+Site credentials are stored in `~/.plugship/config.json` with `0600` file permissions. The config file looks like:
+
+```json
+{
+  "defaultSite": "staging",
+  "sites": {
+    "staging": {
+      "url": "https://staging.example.com",
+      "username": "admin",
+      "appPassword": "xxxx xxxx xxxx xxxx"
+    }
+  }
+}
+```
+
+## How It Works
+
+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`
+
+If the plugin already exists on the site, it is replaced with the uploaded version.
+
+## License
+
+MIT

package/bin/plugship.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "plugship",
+  "version": "1.0.0",
+  "description": "Deploy local WordPress plugins to remote sites from the command line",
+  "type": "module",
+  "bin": {
+    "plugship": "bin/plugship.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shamim0902/plugship.git"
+  },
+  "homepage": "https://github.com/shamim0902/plugship#readme",
+  "bugs": {
+    "url": "https://github.com/shamim0902/plugship/issues"
+  },
+  "author": "shamim0902",
+  "keywords": [
+    "wordpress",
+    "deploy",
+    "plugin",
+    "cli",
+    "wp",
+    "plugship"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "archiver": "^7.0.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "@inquirer/prompts": "^7.2.1",
+    "form-data": "^4.0.1",
+    "ora": "^8.1.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,77 @@
+import { Command } from 'commander';
+
+const program = new Command();
+
+program
+  .name('plugship')
+  .description('Deploy local WordPress plugins to remote sites')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Configure a WordPress site for deployment')
+  .action(async () => {
+    const { initCommand } = await import('./commands/init.js');
+    await initCommand();
+  });
+
+program
+  .command('deploy')
+  .description('Deploy the plugin from the current directory')
+  .option('--site <name>', 'Target site alias')
+  .option('--no-activate', 'Skip plugin activation after deploy')
+  .option('--dry-run', 'Preview deploy without uploading')
+  .option('--all', 'Deploy to all configured sites')
+  .action(async (options) => {
+    const { deployCommand } = await import('./commands/deploy.js');
+    await deployCommand(options);
+  });
+
+program
+  .command('status')
+  .description('Check connection and receiver status for a site')
+  .option('--site <name>', 'Target site alias')
+  .action(async (options) => {
+    const { statusCommand } = await import('./commands/status.js');
+    await statusCommand(options);
+  });
+
+program
+  .command('ignore [patterns...]')
+  .description('Create .plugshipignore or add patterns to it')
+  .action(async (patterns) => {
+    const { ignoreCommand } = await import('./commands/ignore.js');
+    await ignoreCommand(patterns);
+  });
+
+const sites = program
+  .command('sites')
+  .description('Manage saved WordPress sites');
+
+sites
+  .command('list')
+  .description('List all saved sites')
+  .action(async () => {
+    const { listSitesCommand } = await import('./commands/sites/list.js');
+    await listSitesCommand();
+  });
+
+sites
+  .command('remove <name>')
+  .description('Remove a saved site')
+  .action(async (name) => {
+    const { removeSiteCommand } = await import('./commands/sites/remove.js');
+    await removeSiteCommand(name);
+  });
+
+sites
+  .command('set-default <name>')
+  .description('Set the default site')
+  .action(async (name) => {
+    const { setDefaultCommand } = await import('./commands/sites/set-default.js');
+    await setDefaultCommand(name);
+  });
+
+export async function run() {
+  await program.parseAsync(process.argv);
+}

package/src/commands/deploy.js

@@ -0,0 +1,16 @@
+import { deploy } from '../lib/deployer.js';
+import * as logger from '../lib/logger.js';
+
+export async function deployCommand(options) {
+  try {
+    await deploy({
+      siteName: options.site,
+      activate: options.activate,
+      dryRun: options.dryRun,
+      all: options.all,
+    });
+  } catch (err) {
+    logger.error(err.message);
+    process.exitCode = 1;
+  }
+}

package/src/commands/ignore.js

@@ -0,0 +1,70 @@
+import { join } from 'node:path';
+import { readFile, writeFile, access } from 'node:fs/promises';
+import * as logger from '../lib/logger.js';
+
+const IGNORE_FILE = '.plugshipignore';
+
+const DEFAULT_TEMPLATE = `# .plugshipignore
+# Add patterns here to exclude files from the deployment ZIP.
+# One pattern per line. Supports dir/**, *.ext, and exact names.
+#
+# 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
+
+# Source files (uncomment as needed)
+# src/**
+# *.map
+
+# Build tools
+package.json
+package-lock.json
+composer.json
+composer.lock
+webpack.config.js
+`;
+
+export async function ignoreCommand(patterns) {
+  const filePath = join(process.cwd(), IGNORE_FILE);
+
+  // No patterns provided — create template file
+  if (patterns.length === 0) {
+    try {
+      await access(filePath);
+      logger.info(`${IGNORE_FILE} already exists.`);
+    } catch {
+      await writeFile(filePath, DEFAULT_TEMPLATE);
+      logger.success(`Created ${IGNORE_FILE} with default template.`);
+    }
+    return;
+  }
+
+  // Append patterns to existing file or create new one
+  let existing = '';
+  try {
+    existing = await readFile(filePath, 'utf-8');
+  } catch {
+    // File doesn't exist yet
+  }
+
+  const existingPatterns = new Set(
+    existing.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
+  );
+
+  const newPatterns = patterns.filter((p) => !existingPatterns.has(p));
+
+  if (newPatterns.length === 0) {
+    logger.info('All patterns already in .plugshipignore.');
+    return;
+  }
+
+  const content = existing
+    ? existing.trimEnd() + '\n' + newPatterns.join('\n') + '\n'
+    : newPatterns.join('\n') + '\n';
+
+  await writeFile(filePath, content);
+
+  for (const p of newPatterns) {
+    logger.success(`Added: ${p}`);
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,107 @@
+import { input, password } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { addSite } from '../lib/config.js';
+import { WordPressApi } from '../lib/wordpress-api.js';
+import { RECEIVER_DOWNLOAD_URL } from '../lib/constants.js';
+import * as logger from '../lib/logger.js';
+
+export async function initCommand() {
+  console.log(chalk.bold('\nConfigure a WordPress site for deployment\n'));
+
+  const name = await input({
+    message: 'Site alias (e.g. "my-site"):',
+    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://';
+        }
+        return true;
+      } catch {
+        return 'Invalid URL';
+      }
+    },
+  });
+
+  const username = await input({
+    message: 'WordPress username:',
+    validate: (v) => (v.trim() ? true : 'Required'),
+  });
+
+  const appPassword = await password({
+    message: 'Application password:',
+    mask: '*',
+    validate: (v) => (v.trim() ? true : 'Required'),
+  });
+
+  const siteUrl = url.replace(/\/+$/, '');
+  const api = new WordPressApi({ url: siteUrl, username, appPassword });
+
+  // Test connection
+  const spin = logger.spinner('Testing connection to WordPress REST API...');
+  spin.start();
+
+  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;
+  }
+
+  // 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;
+    }
+    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;
+  }
+
+  // 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'
+      )
+    );
+  }
+
+  // Save config
+  await addSite(name.trim(), {
+    url: siteUrl,
+    username: username.trim(),
+    appPassword,
+  });
+
+  logger.success(`Site "${name.trim()}" saved and set as default.\n`);
+}

package/src/commands/sites/list.js

@@ -0,0 +1,23 @@
+import chalk from 'chalk';
+import { listSites } from '../../lib/config.js';
+import * as logger from '../../lib/logger.js';
+
+export async function listSitesCommand() {
+  const { sites, defaultSite } = await listSites();
+  const names = Object.keys(sites);
+
+  if (names.length === 0) {
+    logger.info('No sites configured. Run "plugship init" to add one.');
+    return;
+  }
+
+  console.log(chalk.bold('\nSaved sites:\n'));
+  for (const name of names) {
+    const site = sites[name];
+    const isDefault = name === defaultSite;
+    const label = isDefault ? chalk.green(`${name} (default)`) : name;
+    console.log(`  ${label}`);
+    console.log(`    URL:  ${site.url}`);
+    console.log(`    User: ${site.username}\n`);
+  }
+}

package/src/commands/sites/remove.js

@@ -0,0 +1,23 @@
+import { confirm } from '@inquirer/prompts';
+import { removeSite } from '../../lib/config.js';
+import * as logger from '../../lib/logger.js';
+
+export async function removeSiteCommand(name) {
+  const confirmed = await confirm({
+    message: `Remove site "${name}"?`,
+    default: false,
+  });
+
+  if (!confirmed) {
+    logger.info('Cancelled.');
+    return;
+  }
+
+  try {
+    await removeSite(name);
+    logger.success(`Site "${name}" removed.`);
+  } catch (err) {
+    logger.error(err.message);
+    process.exitCode = 1;
+  }
+}

package/src/commands/sites/set-default.js

@@ -0,0 +1,12 @@
+import { setDefaultSite } from '../../lib/config.js';
+import * as logger from '../../lib/logger.js';
+
+export async function setDefaultCommand(name) {
+  try {
+    await setDefaultSite(name);
+    logger.success(`Default site set to "${name}".`);
+  } catch (err) {
+    logger.error(err.message);
+    process.exitCode = 1;
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,89 @@
+import { select } from '@inquirer/prompts';
+import { getSite, listSites } from '../lib/config.js';
+import { WordPressApi } from '../lib/wordpress-api.js';
+import { RECEIVER_DOWNLOAD_URL } from '../lib/constants.js';
+import * as logger from '../lib/logger.js';
+
+export async function statusCommand(options) {
+  let site;
+  try {
+    if (options.site) {
+      site = await getSite(options.site);
+    } else {
+      const { sites, defaultSite } = await listSites();
+      const names = Object.keys(sites);
+
+      if (names.length === 0) {
+        logger.error('No sites configured. Run "plugship init" first.');
+        process.exitCode = 1;
+        return;
+      }
+
+      if (names.length === 1) {
+        site = { name: names[0], ...sites[names[0]] };
+      } else {
+        const chosen = await select({
+          message: 'Which site do you want to check?',
+          choices: names.map((n) => ({
+            name: n === defaultSite ? `${n} (default)` : n,
+            value: n,
+          })),
+          default: defaultSite,
+        });
+        site = { name: chosen, ...sites[chosen] };
+      }
+    }
+  } catch (err) {
+    logger.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const api = new WordPressApi(site);
+  console.log(`\nChecking ${site.name} (${site.url})...\n`);
+
+  // Connection
+  const spin = logger.spinner('Testing REST API connection...');
+  spin.start();
+  try {
+    await api.testConnection();
+    spin.succeed('REST API is accessible');
+  } catch {
+    spin.fail('Cannot reach REST API');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Auth
+  spin.start('Verifying credentials...');
+  try {
+    const user = await api.testAuth();
+    const caps = user.capabilities || {};
+    if (!caps.install_plugins) {
+      spin.fail(`Authenticated as "${user.name}" but missing install_plugins capability`);
+      process.exitCode = 1;
+      return;
+    }
+    spin.succeed(`Authenticated as "${user.name}"`);
+  } catch {
+    spin.fail('Authentication failed');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Receiver
+  spin.start('Checking receiver plugin...');
+  try {
+    const status = await api.checkReceiver();
+    spin.succeed(`Receiver plugin active (v${status.version})`);
+  } catch {
+    spin.fail('Receiver plugin not found');
+    logger.info(`Download: ${RECEIVER_DOWNLOAD_URL}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('');
+  logger.success('All checks passed. Ready to deploy.');
+  console.log('');
+}

package/src/lib/config.js

@@ -0,0 +1,71 @@
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { CONFIG_DIR, CONFIG_FILE, CONFIG_PERMISSIONS } from './constants.js';
+import { ConfigError } from './errors.js';
+
+const EMPTY_CONFIG = { defaultSite: null, sites: {} };
+
+export async function loadConfig() {
+  try {
+    await access(CONFIG_FILE);
+    const data = await readFile(CONFIG_FILE, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return { ...EMPTY_CONFIG };
+  }
+}
+
+export async function saveConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', {
+    mode: CONFIG_PERMISSIONS,
+  });
+}
+
+export async function getSite(name) {
+  const config = await loadConfig();
+  const siteName = name || config.defaultSite;
+  if (!siteName) {
+    throw new ConfigError('No site specified and no default site configured. Run "wpdeploy init" first.');
+  }
+  const site = config.sites[siteName];
+  if (!site) {
+    throw new ConfigError(`Site "${siteName}" not found. Run "wpdeploy sites list" to see available sites.`);
+  }
+  return { name: siteName, ...site };
+}
+
+export async function addSite(name, siteConfig) {
+  const config = await loadConfig();
+  config.sites[name] = siteConfig;
+  if (!config.defaultSite || Object.keys(config.sites).length === 1) {
+    config.defaultSite = name;
+  }
+  await saveConfig(config);
+}
+
+export async function removeSite(name) {
+  const config = await loadConfig();
+  if (!config.sites[name]) {
+    throw new ConfigError(`Site "${name}" not found.`);
+  }
+  delete config.sites[name];
+  if (config.defaultSite === name) {
+    const remaining = Object.keys(config.sites);
+    config.defaultSite = remaining.length > 0 ? remaining[0] : null;
+  }
+  await saveConfig(config);
+}
+
+export async function setDefaultSite(name) {
+  const config = await loadConfig();
+  if (!config.sites[name]) {
+    throw new ConfigError(`Site "${name}" not found.`);
+  }
+  config.defaultSite = name;
+  await saveConfig(config);
+}
+
+export async function listSites() {
+  const config = await loadConfig();
+  return { sites: config.sites, defaultSite: config.defaultSite };
+}

package/src/lib/constants.js

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const CONFIG_DIR = join(homedir(), '.plugship');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+export const CONFIG_PERMISSIONS = 0o600;
+export const RECEIVER_DOWNLOAD_URL = 'https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip';
+
+export const PLUGIN_HEADER_FIELDS = {
+  'Plugin Name': 'name',
+  'Plugin URI': 'pluginUri',
+  'Description': 'description',
+  'Version': 'version',
+  'Author': 'author',
+  'Author URI': 'authorUri',
+  'Text Domain': 'textDomain',
+  'Domain Path': 'domainPath',
+  'Requires at least': 'requiresWp',
+  'Requires PHP': 'requiresPhp',
+  'License': 'license',
+  'License URI': 'licenseUri',
+};
+
+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

@@ -0,0 +1,164 @@
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+import { select, confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { getSite, listSites } from './config.js';
+import { detectPlugin } from './plugin-detector.js';
+import { createPluginZip } from './zipper.js';
+import { WordPressApi } from './wordpress-api.js';
+import { DeployError, ConfigError } from './errors.js';
+import { RECEIVER_DOWNLOAD_URL } from './constants.js';
+import * as logger from './logger.js';
+
+async function resolveSite(siteName) {
+  if (siteName) return getSite(siteName);
+
+  const { sites, defaultSite } = await listSites();
+  const names = Object.keys(sites);
+
+  if (names.length === 0) {
+    throw new ConfigError('No sites configured. Run "plugship init" first.');
+  }
+
+  if (names.length === 1) {
+    return { name: names[0], ...sites[names[0]] };
+  }
+
+  const chosen = await select({
+    message: 'Which site do you want to deploy to?',
+    choices: names.map((name) => ({
+      name: name === defaultSite ? `${name} (default)` : name,
+      value: name,
+    })),
+    default: defaultSite,
+  });
+
+  return { name: chosen, ...sites[chosen] };
+}
+
+async function getAllSites() {
+  const { sites } = await listSites();
+  const names = Object.keys(sites);
+
+  if (names.length === 0) {
+    throw new ConfigError('No sites configured. Run "plugship init" first.');
+  }
+
+  return names.map((name) => ({ name, ...sites[name] }));
+}
+
+async function checkIgnoreFile(cwd) {
+  try {
+    await access(join(cwd, '.plugshipignore'));
+  } catch {
+    logger.warn('No .plugshipignore file found.');
+    const create = await confirm({
+      message: 'Create one with default template?',
+      default: true,
+    });
+    if (create) {
+      const { ignoreCommand } = await import('../commands/ignore.js');
+      await ignoreCommand([]);
+    }
+  }
+}
+
+function printPluginInfo(plugin, site) {
+  console.log('');
+  logger.info(`Plugin:  ${plugin.name}`);
+  logger.info(`Version: ${plugin.version}`);
+  logger.info(`Slug:    ${plugin.slug}`);
+  if (site) {
+    logger.info(`Site:    ${site.name} (${site.url})`);
+  }
+  console.log('');
+}
+
+export async function deploy({ siteName, activate = true, dryRun = false, all = false }) {
+  const cwd = process.cwd();
+
+  // Check for .plugshipignore
+  await checkIgnoreFile(cwd);
+
+  // 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)`);
+
+  // Dry run — show summary and exit
+  if (dryRun) {
+    const targets = all ? await getAllSites() : [await resolveSite(siteName)];
+    console.log(chalk.bold('\n--- Dry Run ---\n'));
+    logger.info(`Plugin:  ${plugin.name}`);
+    logger.info(`Version: ${plugin.version}`);
+    logger.info(`Slug:    ${plugin.slug}`);
+    logger.info(`ZIP:     ${zipPath} (${sizeMB} MB)`);
+    logger.info(`Activate: ${activate ? 'yes' : 'no'}`);
+    console.log('');
+    logger.info('Target sites:');
+    for (const s of targets) {
+      console.log(`  - ${s.name} (${s.url})`);
+    }
+    console.log(chalk.dim('\nNo changes were made. Remove --dry-run to deploy.\n'));
+    return;
+  }
+
+  // Resolve targets
+  const targets = all ? await getAllSites() : [await resolveSite(siteName)];
+
+  for (const site of targets) {
+    if (targets.length > 1) {
+      console.log(chalk.bold(`\n--- Deploying to ${site.name} ---`));
+    }
+
+    printPluginInfo(plugin, site);
+
+    const api = new WordPressApi(site);
+
+    // Check receiver
+    const s = logger.spinner('Checking receiver plugin...');
+    s.start();
+    try {
+      await api.checkReceiver();
+      s.succeed('Receiver plugin is active');
+    } catch {
+      s.fail('Receiver plugin not found');
+      logger.error(
+        `The plugship-receiver plugin is not active on ${site.name}. Download and install it first.\n  ${RECEIVER_DOWNLOAD_URL}`
+      );
+      if (targets.length > 1) continue;
+      throw new DeployError('Receiver plugin not found.');
+    }
+
+    // Upload
+    s.start('Uploading plugin...');
+    let result;
+    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;
+      }
+      throw new DeployError(`Deploy failed: ${err.message}`);
+    }
+
+    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).');
+      }
+    }
+  }
+
+  console.log('');
+}

package/src/lib/errors.js

@@ -0,0 +1,36 @@
+export class WpDeployError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WpDeployError';
+  }
+}
+
+export class ConfigError extends WpDeployError {
+  constructor(message) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export class ApiError extends WpDeployError {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}
+
+export class PluginDetectionError extends WpDeployError {
+  constructor(message) {
+    super(message);
+    this.name = 'PluginDetectionError';
+  }
+}
+
+export class DeployError extends WpDeployError {
+  constructor(message) {
+    super(message);
+    this.name = 'DeployError';
+  }
+}

package/src/lib/logger.js

@@ -0,0 +1,22 @@
+import chalk from 'chalk';
+import ora from 'ora';
+
+export function info(message) {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+export function success(message) {
+  console.log(chalk.green('✔'), message);
+}
+
+export function warn(message) {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+export function error(message) {
+  console.error(chalk.red('✖'), message);
+}
+
+export function spinner(text) {
+  return ora({ text, color: 'cyan' });
+}

package/src/lib/plugin-detector.js

@@ -0,0 +1,67 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { PLUGIN_HEADER_FIELDS } from './constants.js';
+import { PluginDetectionError } from './errors.js';
+
+export async function detectPlugin(directory) {
+  const entries = await readdir(directory);
+  const phpFiles = entries.filter((f) => f.endsWith('.php'));
+
+  if (phpFiles.length === 0) {
+    throw new PluginDetectionError('No PHP files found in current directory. Are you in a WordPress plugin directory?');
+  }
+
+  for (const file of phpFiles) {
+    const filePath = join(directory, file);
+    const content = await readFile(filePath, 'utf-8');
+    const headers = parseHeaders(content);
+
+    if (headers.name) {
+      const slug = deriveSlug(headers.textDomain, headers.name);
+      return {
+        name: headers.name,
+        version: headers.version || '0.0.0',
+        slug,
+        textDomain: headers.textDomain || slug,
+        description: headers.description || '',
+        directory: basename(directory),
+        mainFile: file,
+        headers,
+      };
+    }
+  }
+
+  throw new PluginDetectionError(
+    'No WordPress plugin header found. Ensure a PHP file contains a "Plugin Name:" header comment.'
+  );
+}
+
+function parseHeaders(content) {
+  const headerBlock = content.match(/\/\*\*?[\s\S]*?\*\//);
+  if (!headerBlock) return {};
+
+  const block = headerBlock[0];
+  const result = {};
+
+  for (const [field, key] of Object.entries(PLUGIN_HEADER_FIELDS)) {
+    const regex = new RegExp(`^\\s*\\*?\\s*${escapeRegex(field)}:\\s*(.+)$`, 'mi');
+    const match = block.match(regex);
+    if (match) {
+      result[key] = match[1].trim();
+    }
+  }
+
+  return result;
+}
+
+function deriveSlug(textDomain, name) {
+  if (textDomain) return textDomain;
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/lib/wordpress-api.js

@@ -0,0 +1,101 @@
+import FormData from 'form-data';
+import { readFile } from 'node:fs/promises';
+import { ApiError } from './errors.js';
+
+export class WordPressApi {
+  constructor({ url, username, appPassword }) {
+    this.baseUrl = url.replace(/\/+$/, '');
+    this.auth = 'Basic ' + Buffer.from(`${username}:${appPassword}`).toString('base64');
+  }
+
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}/wp-json${path}`;
+    const headers = { ...options.headers };
+
+    if (options.auth !== false) {
+      headers['Authorization'] = this.auth;
+    }
+
+    const res = await fetch(url, { ...options, headers });
+    const contentType = res.headers.get('content-type') || '';
+    const body = contentType.includes('application/json') ? await res.json() : await res.text();
+
+    if (!res.ok) {
+      const msg = typeof body === 'object' && body.message ? body.message : `HTTP ${res.status}`;
+      throw new ApiError(msg, res.status, body);
+    }
+
+    return body;
+  }
+
+  async testConnection() {
+    return this.request('/', { auth: false });
+  }
+
+  async testAuth() {
+    return this.request('/wp/v2/users/me?context=edit');
+  }
+
+  async getPlugins() {
+    return this.request('/wp/v2/plugins');
+  }
+
+  async getPlugin(slug) {
+    return this.request(`/wp/v2/plugins/${slug}`);
+  }
+
+  async activatePlugin(plugin) {
+    return this.request(`/wp/v2/plugins/${plugin}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ status: 'active' }),
+    });
+  }
+
+  async deactivatePlugin(plugin) {
+    return this.request(`/wp/v2/plugins/${plugin}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ status: 'inactive' }),
+    });
+  }
+
+  async deletePlugin(plugin) {
+    return this.request(`/wp/v2/plugins/${plugin}`, {
+      method: 'DELETE',
+    });
+  }
+
+  async checkReceiver() {
+    return this.request('/plugship/v1/status');
+  }
+
+  async deployPlugin(zipPath, filename) {
+    const fileBuffer = await readFile(zipPath);
+    const form = new FormData();
+    form.append('plugin', fileBuffer, {
+      filename,
+      contentType: 'application/zip',
+    });
+
+    const url = `${this.baseUrl}/wp-json/plugship/v1/deploy`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': this.auth,
+        ...form.getHeaders(),
+      },
+      body: form.getBuffer(),
+    });
+
+    const contentType = res.headers.get('content-type') || '';
+    const body = contentType.includes('application/json') ? await res.json() : 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);
+    }
+
+    return body;
+  }
+}

package/src/lib/zipper.js

@@ -0,0 +1,65 @@
+import { createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { stat, mkdir, readFile } from 'node:fs/promises';
+import archiver from 'archiver';
+import { DEFAULT_EXCLUDES } from './constants.js';
+
+async function loadIgnorePatterns(sourceDir) {
+  const patterns = [...DEFAULT_EXCLUDES];
+  try {
+    const content = await readFile(join(sourceDir, '.plugshipignore'), 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#')) {
+        patterns.push(trimmed);
+      }
+    }
+  } catch {
+    // No .plugshipignore file — use defaults only
+  }
+  return patterns;
+}
+
+export async function createPluginZip(sourceDir, slug) {
+  const buildDir = join(sourceDir, 'build');
+  await mkdir(buildDir, { recursive: true });
+  const zipName = `${slug}.zip`;
+  const zipPath = join(buildDir, zipName);
+  const excludes = await loadIgnorePatterns(sourceDir);
+
+  await new Promise((resolve, reject) => {
+    const output = createWriteStream(zipPath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', resolve);
+    archive.on('error', reject);
+    archive.on('warning', (err) => {
+      if (err.code !== 'ENOENT') reject(err);
+    });
+
+    archive.pipe(output);
+    archive.directory(sourceDir, slug, (entry) => {
+      for (const pattern of excludes) {
+        if (matchGlob(entry.name, pattern)) return false;
+      }
+      return entry;
+    });
+    archive.finalize();
+  });
+
+  const zipStat = await stat(zipPath);
+  return { zipPath, size: zipStat.size };
+}
+
+function matchGlob(filePath, pattern) {
+  // Strip trailing /** for directory matching
+  if (pattern.endsWith('/**')) {
+    const dir = pattern.slice(0, -3);
+    return filePath === dir || filePath.startsWith(dir + '/');
+  }
+  // Exact match or wildcard prefix
+  if (pattern.startsWith('*.')) {
+    return filePath.endsWith(pattern.slice(1));
+  }
+  return filePath === pattern;
+}