plugship 1.0.1 → 1.0.2

package/README.md

@@ -1,173 +1,197 @@
 # 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
+A simple CLI tool to deploy local WordPress plugins to remote WordPress sites. No FTP, no cPanel — just `plugship deploy`.
 
-- 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/)
+## Quick Start
 
-## Installation
+### 1. Install
 
 ```bash
 npm install -g plugship
 ```
 
-## Setup
+### 2. Install Receiver Plugin
 
-### 1. Install the Receiver Plugin
+Download and install the companion plugin on your WordPress site:
 
-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 the ZIP file
+3. Activate **PlugShip Receiver**
 
-### 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
+### 3. Configure Your 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.
+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)
 
-## Usage
+### 4. Deploy
 
-### Deploy a Plugin
-
-Navigate to your WordPress plugin directory and run:
+Navigate to your plugin directory and run:
 
 ```bash
 plugship deploy
 ```
 
-This will:
+Done! Your plugin is deployed and activated.
+
+---
 
-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
+## Commands
 
-If you have multiple sites configured, you will be prompted to select one.
+### `plugship deploy`
 
-#### Options
+Deploy the plugin from the current directory.
 
 ```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                 # 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
 ```
 
-### Check Site Status
+### `plugship init`
 
-Verify connection, credentials, and receiver plugin before deploying:
+Add a new WordPress site.
 
 ```bash
-plugship status                 # Check default or select a site
-plugship status --site <name>   # Check a specific site
+plugship init
 ```
 
-### Manage Sites
+### `plugship status`
+
+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
+plugship status                 # Check default site
+plugship status --site staging  # Check specific site
 ```
 
-## Commands
+### `plugship sites`
 
-| 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 |
+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
+```
 
-## Plugin Detection
+### `plugship ignore`
 
-The CLI detects your plugin by scanning `.php` files in the current directory for a standard WordPress plugin header:
+Exclude files from deployment.
 
-```php
-<?php
-/**
- * Plugin Name: My Plugin
- * Version: 1.0.0
- * Text Domain: my-plugin
- */
+```bash
+plugship ignore                     # Create .plugshipignore template
+plugship ignore "src/**" "*.map"    # Add patterns
 ```
 
-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:
+Create a `.plugshipignore` file to exclude files from deployment:
 
 ```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:
+This creates a template with common exclusions. Edit it to add your own:
 
 ```
 # .plugshipignore
 src/**
-assets/scss/**
-webpack.config.js
+*.map
 package.json
-package-lock.json
 composer.json
-composer.lock
-*.map
+webpack.config.js
+```
+
+**Already excluded by default:**
+`node_modules`, `.git`, `.env`, `*.log`, `.vscode`, `.idea`, `tests`, `.github`, `build`
+
+---
+
+## How It Works
+
+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
+
+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.
+
+---
+
+## Examples
+
+### Deploy to Staging
+
+```bash
+cd my-plugin/
+plugship deploy --site staging
 ```
 
-- One pattern per line
-- Lines starting with `#` are comments
-- Blank lines are ignored
-- Supports `dir/**` (directory and contents), `*.ext` (extension match), and exact names
+### Deploy to All Sites
+
+```bash
+plugship deploy --all
+```
+
+### Preview What Would Be Deployed
+
+```bash
+plugship deploy --dry-run
+```
+
+### Check Connection Before Deploying
+
+```bash
+plugship status
+```
+
+---
+
+## Requirements
+
+- **Node.js** 18 or higher
+- **WordPress** 5.8 or higher
+- **Admin account** with Application Passwords enabled
+
+---
 
-The following are always excluded by default:
+## Security
 
-`node_modules`, `.git`, `.DS_Store`, `.env`, `*.log`, `.vscode`, `.idea`, `tests`, `phpunit.xml`, `.phpunit.result.cache`, `.github`, `build`
+- 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
+
+---
 
 ## Configuration
 
-Site credentials are stored in `~/.plugship/config.json` with `0600` file permissions. The config file looks like:
+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,14 +201,42 @@ Site credentials are stored in `~/.plugship/config.json` with `0600` file permis
 }
 ```
 
-## How It Works
+---
+
+## Troubleshooting
+
+### "Receiver plugin not found"
+
+The plugship-receiver plugin isn't active on your WordPress site.
+
+1. Download: https://github.com/shamim0902/plugship-receiver/releases/latest/download/plugship-receiver.zip
+2. Upload and activate in WordPress admin
+
+### "Authentication failed"
+
+Your Application Password is incorrect.
+
+1. Go to **Users > Profile** in WordPress admin
+2. Generate a new Application Password
+3. Run `plugship init` again
+
+### "Cannot reach REST API"
+
+Your 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
+
+---
 
-The WordPress REST API does not support direct ZIP upload for plugin installation. The `plugship-receiver` companion plugin adds two custom endpoints:
+## Links
 
-- `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`
+- [npm package](https://www.npmjs.com/package/plugship)
+- [Receiver plugin](https://github.com/shamim0902/plugship-receiver)
+- [Report issues](https://github.com/shamim0902/plugship/issues)
 
-If the plugin already exists on the site, it is replaced with the uploaded version.
+---
 
 ## License
 

package/package.json

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