pockethost 1.7.0 → 3.1.0

package/CHANGELOG.md

@@ -1,134 +1,186 @@
-# pockethost
+# pockethost (CLI)
 
-## 1.7.0
+Formerly published as `phio`. Versions below 3.0.0 are phio's history.
+
+## 3.1.0
 
 ### Minor Changes
 
-- 3c7e9bf: Added plugin template command and updated docs
+- `deploy` and `dev` now upload over HTTPS instead of SFTP. The CLI sends a list of file hashes, uploads only the
+  files PocketHost doesn't have yet (compressed), and PocketHost swaps the new set in all at once, restarting the
+  instance when anything outside `pb_public` changed. Files in the deployed folders that aren't in your project are
+  removed. Dotfiles (for example `pb_public/.well-known/`) are now deployed; `.git*` and `node_modules` stay excluded.
+- Personal access tokens: set `POCKETHOST_TOKEN`, or run `pockethost token set` / `pockethost login --token`. Deploys
+  need no password or SSH key, so CI works on fresh runners (previously a new runner generated a new deploy key that
+  didn't match the registered `PocketHost CLI` key).
+- New `pockethost token [set|clear|status]`. `info` shows the token in use. `logout` also removes a saved token.
+- `deploy --commit <sha>` and `-m/--message <note>` are recorded with each deploy (`$GITHUB_SHA` is used
+  automatically).
+- `--sftp` on `deploy` and `dev` keeps the previous SFTP sync.
+- PocketHost no longer runs `bun install` when `package.json`, `bun.lock(b)` or `patches/` change (over SFTP or the
+  deploy API). Those files are copied as-is, and an existing `node_modules` on the instance is left alone. Bundle npm
+  code your hooks need into `pb_hooks`.
+
+## 3.0.0
+
+### Major Changes
+
+- Renamed from `phio` to `pockethost`. Install with `npm i -g pockethost`; the command is `pockethost`. The `phio`
+  npm package is deprecated.
+- Installs and runs on plain Node (>=20): the CLI ships as a single bundled `dist/cli.js` and no longer needs `tsx`
+  on your PATH (a clean `npm i -g phio@0.4.0` failed with `/usr/bin/env: 'tsx': No such file or directory`).
+- New names, migrated automatically on first run:
+  - project file `.phioconfig` → `.pockethostconfig`
+  - config folder `~/.config/phio-nodejs` → `~/.config/pockethost` (Linux; macOS/Windows equivalents) (login and deploy key are copied over)
+  - environment variables `PHIO_*` → `POCKETHOST_*` (old names still work, with a warning)
+  - new deploy keys are labeled `PocketHost CLI`; existing `Phio` keys are reused
+- Removed the undocumented library entry point (`main`/`types`); the package is CLI-only.
+- `list` help text now says "List your instances".
+
+## 1.0.0 (never published; shipped as 3.0.0)
+
+### Major Changes
+
+- SFTP-only deploy vendor: dropped legacy FTPS/FTP codepath and `basic-ftp` dependency
+- Node `>=18` (hosting stack still requires Node 24)
+- Dropped `fs-extra` and `email-validator`; leaner install
+
+## 0.4.0
+
+### Minor Changes
 
-## 1.6.1
+- SFTP deploy and dev sync (`ftp.pockethost.io:2222`, Ed25519 key auth)
+- `phio sftp` — interactive SFTP via system client (`--print` for the command line)
+- Auto-provision deploy key labeled `Phio` under Account → Keys
+- Project instance linking via `.phioconfig` (migrates legacy `package.json` / `pockethost.json`)
+- Walk up to project root from subdirectories before sync
+
+## 0.3.5
 
 ### Patch Changes
 
-- dc8f70b: Updated docs
+- Fix: add support for bun.lock
 
-## 1.6.0
+## 0.3.4
 
-### Minor Changes
+### Patch Changes
 
-- 40bbb3c: Improve tryFetch by accepting node-fetch params
-- 12f029a: Add changeset maker
-- b7277cf: Add public instance URL calculators and refactor HTTP protocol detection
-- 45a8f45: Add internal app (remote control) support
-- 55b43a1: Remove unneeded params from GetOrProvisionInstanceUrl filter
-- 5be2c9e: Initial commit
-- a236f3e: Added several more filters
-- 35edc77: Enhancement: actions execute sequentially
-- 879845a: Enhancement: unsubscribe from filters
-- c473ed9: Added support for priorities in actions
-- 795fcd7: New action: KillInstance
-- c32b845: Added support for Settings filter whereby all settings are collected and displayed in DEBUG() mode
-- cce72b3: New action: AfterPluginsLoaded
-- 82dde2d: Enhancement: filters now have extensible data types
-
-### Patch Changes
-
-- b55c585: Clean up dead code
-- 0e4bf43: Updated commit parser deps
-- f79b067: Added serve command details
-- dd3ceaa: Added filter debugging
-- 7931204: Fixed a bug where adding plugins was not saved correctly
-- 6e14f57: Updated plugin authoring guide
-- 7604930: Minor fix to GetOrProvisionInstanceUrl filter
-- 52b70cb: Fixed bug where --extra-plugins was not defaulting to '' correctly
-- Updated dependencies [c32b845]
-  - @pockethost/plugin-launcher-spawn@1.0.0
-  - @pockethost/plugin-auto-admin@1.0.0
-  - @pockethost/plugin-console-logger@1.0.0
-
-## 1.5.0
+- 24988ee: Feat: logout command
+- de7168b: Fix: various auth fixes
+- 6262058: Fix: use correct token for log watching
+- 5d28256: Enhance logs command with improved streaming and error handling
 
-### Minor Changes
+## 0.3.3
+
+### Patch Changes
+
+- 4bf6d1e: Fix: use client auth token instead of stored token
 
-- 5e9ed51: Added `--extra-plugins` global switch to temporarily load extra plugins from CLI
-- 2376b0d: Add InstanceConfig filter, fix instance logger namespace, add core instance app lib
-- 737b4b8: logSettings now exported from core
-- 114b1d2: Add namespace() export to core Logger service
+## 0.3.2
 
 ### Patch Changes
 
-- 211fba6: Plugin authoring docs update
-- 675e634: Added docs and updated maildev with plugin hook guards
-- 3daf7f5: Fix: [INFO] logging prefixes
-- 139468f: Updated documentation
-- 1e5321b: Fix: improve plugin loading order
-- Updated dependencies [517f602]
-  - @pockethost/plugin-launcher-spawn@0.3.0
-  - @pockethost/plugin-console-logger@0.2.1
-  - @pockethost/plugin-auto-admin@0.1.1
+- b85e156: Fix: nodev22 compat
 
-## 1.4.0
+## 0.3.1
+
+### Patch Changes
+
+- fd128bc: Node v22 compat
+
+## 0.3.0
 
 ### Minor Changes
 
-- b7e4323: Added ability for plugins to respond to `pockethost serve`
+- 82b4c6b: Add support for PHIO_USERNAME, PHIO_PASSWORD, and PHIO_INSTANCE_NAME env vars
+- 82b4c6b: Migrate to instance names only (no IDs)
+- 82b4c6b: Remove support for global instance name - local package.json or pockethost.json required now
+
+### Patch Changes
+
+- 1b46e08: Alphabetize instance lists
+- 82b4c6b: Improved error message reporting
 
-## 1.3.2
+## 0.2.5
 
 ### Patch Changes
 
-- b0a78d8: Updated plugin authoring guide
-- ac63ea7: Updated plugin documentation
-- Updated dependencies [eb0d011]
-- Updated dependencies [38d2c93]
-  - @pockethost/plugin-launcher-spawn@0.2.0
-  - @pockethost/plugin-console-logger@0.2.0
-  - @pockethost/plugin-auto-admin@0.1.0
+- 283da4e: Add 'info' command
+- b17fca2: Add error handling when 'link' returns no instances
+- 8aaa611: Add 'ls' alias
 
-## 1.3.1
+## 0.2.4
 
 ### Patch Changes
 
-- 8288197: Added plugin authoring guide
+- Fix: --include and --exclude now parse comma separated values correctly
 
-## 1.3.0
+## 0.2.3
 
-### Minor Changes
+### Patch Changes
+
+- Fix: bad include path
 
-- 96f355a: Now auto-creates first admin account by default
-- 2fc2eeb: Added before/after instance start/stop events
-- 3f99ea0: Added subdomain to request action and filter context
-- 1384a86: BREAKING: refactored actions/filters
+## 0.2.2
 
 ### Patch Changes
 
-- 6812784: Added improved error parsing support
-- da82667: Fix: properly determine hostname when running on nonstandard port
-- cc4aa02: Moved mothership-related code into mothership plugin
-- Updated dependencies [9d626ec]
-  - @pockethost/plugin-launcher-spawn@0.1.0
-  - @pockethost/plugin-console-logger@0.1.0
+- 467c4ba: Enh: Validate auth before tailing instance logs
+- 4e8ddb5: Fix: auth token now stored correctly after refresh
 
-## 1.2.0
+## 0.2.1
+
+### Patch Changes
+
+- Fix: Link now uses package.json
+
+## 0.2.0
 
 ### Minor Changes
 
-- 72a6c6d: --version now displays version number
-- ac10d1f: Display notification when new pockethost update is available.
-- f9aea10: Debugging info removed from `plugin ls`
+- Introduced deploy command
+
+### Patch Changes
+
+- Command refactoring
+
+## 0.1.2
+
+### Patch Changes
+
+- Enh: add --verbose flag to dev mode
+
+## 0.1.1
 
 ### Patch Changes
 
-- 76d57f6: CHANGELOG.md is now published with package.
-- 3783447: plugin-console-logger and plugin-launcher-spawn are now automatically installed.
+- Fix: include and exclude defaults
 
-## 1.1.0
+## 0.1.0
 
 ### Minor Changes
 
-- 1695b59: New feature: list plugins (pockethost plugin ls)
+- afc6e91: Added `link` command to link to a specific instance
+- fff79df: pockethost.io now runs `bun install` when uploading a `bun.lockb`
+- 9fc57d6: Added whoami command
+- 9fc57d6: Added list command
+- afc6e91: Added --include and --exclude options to dev watch mode
+
+### Patch Changes
+
+- afc6e91: Fix: log tailer will now restart on disconnect
+- fff79df: Enh: watcher now looks for package.json and bun.lockb
+- fff79df: Fix: watcher was incorrectly applying --include and --exclude
+- fff79df: Enh: watcher now queues successive deployments that happen in rapid succession
+
+## 0.0.2
+
+### Patch Changes
+
+- Forgot tsx dep
+
+## 0.0.1
 
 ### Patch Changes
 
-- 2514c09: Fix: make sure PH_PLUGINS contains only unique values.
-- 1228840: Fixed extra newline when listing configs
+- a5bf2f3: Initial version

package/README.md

@@ -0,0 +1,133 @@
+# pockethost: the PocketHost CLI
+
+Deploy, sync, and tail logs for your [PocketHost](https://pockethost.io) instances.
+
+Install globally (Node.js 20+):
+
+```bash
+npm install -g pockethost
+```
+
+### Upgrading from `phio`
+
+`phio` is now `pockethost`. Swap the package:
+
+```bash
+npm rm -g phio && npm i -g pockethost
+```
+
+Everything carries over on first run: your login and deploy key are copied from phio's config folder (`~/.config/phio-nodejs` on Linux), `.phioconfig` is
+renamed to `.pockethostconfig` (commit it), and the `PHIO_*` environment variables keep working with a warning until
+you rename them to `POCKETHOST_*`.
+
+## Commands
+
+```bash
+pockethost login             # or: pockethost login --token
+pockethost token [set|clear|status]
+pockethost logout
+pockethost info          # alias: pockethost whoami
+pockethost list          # alias: pockethost ls
+pockethost link [instance]
+pockethost dev [instance]
+pockethost deploy [instance]
+pockethost sftp [instance]
+pockethost logs [instance]
+```
+
+- **`pockethost dev`**: watch local changes and deploy them
+- **`pockethost deploy`**: deploy once
+- **`pockethost token`**: save, clear, or check a personal access token
+- **`pockethost sftp`**: interactive SFTP session (uses system `sftp` when available)
+- **`pockethost logs`**: tail instance logs
+
+`dev` and `deploy` accept `-v/--verbose`, `-i/--include`, `-e/--exclude`, and `--sftp` (sync over SFTP instead of
+HTTPS). `deploy` also takes `--commit <sha>` and `-m/--message <note>`.
+
+Default includes: `pb_*`, `package.json`, `bun.lock`, `bun.lockb`, `patches/**`.
+
+Default excludes: `pb_data/**`.
+
+## Configuration
+
+Link a project directory to an instance:
+
+```bash
+pockethost link my-instance
+```
+
+This writes `.pockethostconfig`:
+
+```json
+{
+  "instanceName": "my-instance"
+}
+```
+
+Older project files (`.phioconfig`, `package.json` → `pockethost.instanceName`, `pockethost.json`) are migrated to
+`.pockethostconfig` automatically on first use.
+
+## How deploys work
+
+`deploy` and `dev` talk to the instance over HTTPS (`https://<instance>.pockethost.io/_ph/deploy/v1`):
+
+1. Send a manifest of `{ path: sha256 }` for the matched files.
+2. Upload only the files the server is missing, as one gzip bundle per ~32 MB.
+3. Commit: the server swaps the file set in atomically (stopping the instance when anything outside `pb_public`
+   changes) and starts the instance again.
+
+PocketHost doesn't install npm packages. `package.json`, `bun.lock(b)` and `patches/` are copied as plain files. Bundle
+any npm code your hooks need into `pb_hooks`.
+
+Only `pb_*` folders (never `pb_data`), `package.json`, `bun.lock(b)` and `patches/` are deployed. Files in those folders
+on the instance that aren't in your project are removed. `node_modules` and `.git*` are never touched.
+
+## Authentication
+
+`deploy` and `dev` use, in order:
+
+1. `POCKETHOST_TOKEN` (a personal access token, `ph_pat_…`)
+2. a token saved with `pockethost token set` (or `pockethost login --token`)
+3. your email/password login (`pockethost login`, or `POCKETHOST_USERNAME`/`POCKETHOST_PASSWORD`)
+
+Create tokens under Account → API Tokens in the dashboard. Deploy from GitHub Actions:
+
+```yaml
+- run: npx pockethost@latest deploy myapp-${{ github.ref_name }}
+  env:
+    POCKETHOST_TOKEN: ${{ secrets.POCKETHOST_TOKEN }}
+```
+
+Docs: https://pockethost.io/docs/deploy-from-ci
+
+## Deploy key (`--sftp` and `pockethost sftp`)
+
+`pockethost dev --sftp`, `pockethost deploy --sftp` and `pockethost sftp` use **SFTP** (`ftp.pockethost.io:2222`) using an Ed25519 deploy key
+stored under `POCKETHOST_HOME` (default `~/.config/pockethost/`). The CLI auto-registers a **`PocketHost CLI`** key
+under Account → Keys on first use (an existing **`Phio`** key from phio is reused). Run `pockethost info` to inspect
+key status.
+
+Customer docs: https://pockethost.io/docs/cli
+
+## Environment variables
+
+| Variable | Purpose |
+| -------- | ------- |
+| `POCKETHOST_TOKEN` | Personal access token for `deploy`/`dev` (CI) |
+| `POCKETHOST_USERNAME` | Override saved email (non-interactive login) |
+| `POCKETHOST_PASSWORD` | Override saved password |
+| `POCKETHOST_INSTANCE_NAME` | Override linked instance name |
+| `POCKETHOST_MOTHERSHIP_URL` | Override mothership API URL |
+| `POCKETHOST_HOME` | Override config directory |
+| `POCKETHOST_PROJECT_DIR` | Override project root detection |
+
+Environment variables take precedence over `.pockethostconfig`. The old `PHIO_*` names still work (with a deprecation
+warning) and will be removed in the next major version.
+
+## Development (monorepo)
+
+```bash
+pnpm dev:cli-client -- --help          # from the repo root, runs src/ with tsx
+pnpm --filter pockethost build         # bundle to dist/cli.js
+pnpm --filter pockethost test
+```