@haakco/hostingctl 1.0.819 → 1.0.833

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -74,6 +74,7 @@ machine older than the floor above is not covered by this statement.
74
74
  ```bash
75
75
  npm uninstall -g @haakco/hostingctl
76
76
  rm -rf ~/.config/hostingctl # the stored sessions; Windows: %APPDATA%\hostingctl
77
+ rm -rf ~/.cache/hostingctl # the files copy engine; see "Environment files from this computer"
77
78
  ```
78
79
 
79
80
  If `HOSTINGCTL_CONFIG_HOME` or `XDG_CONFIG_HOME` is set, sessions live in that directory instead: remove
@@ -239,8 +240,9 @@ own parser (`hostingctl reference`) and compared against it in CI. The groups, i
239
240
  | `backup-destination` | The company's own bucket that also receives its backups |
240
241
  | `backups` | An environment's backup tracks, the newest restore point, and the fresh backup it has asked for: `requests`, `request-show` and the `request` write |
241
242
  | `secret-connection` | An environment's connections to a customer's own secret manager |
242
- | `provider-connections` | Saved SFTP, FTPS and FTP logins: list, show, add, update, check, check-show, rotate, revoke and remove. Native guided setup or private typed request files; writes require confirmation |
243
+ | `provider-connections` | A company's saved SFTP, FTPS and FTP logins to the old hosts it moves sites and files from: list, show, add, update, check, check-show, rotate, revoke and remove. Native guided setup or private typed request files (`--file` or `--stdin`). The old-host limits (`--preset` normal, gentle or very-gentle, or `--connections`, `--speed-limit`, `--requests-per-second`, `--host-imports`, `--retry-wait`) override the same JSON fields; `update` with only limit flags changes just those. `check --wait` follows the check, prints each stage as pass or FAIL and exits 1 when it failed. Writes, `check` included, require confirmation |
243
244
  | `registry-connections` | A company's container-registry connections: the account, the repository scope, one verified manifest check, credential rotation and revocation. It stores no customer image and starts no workload |
245
+ | `files` | `files import start` copies a folder from a checked provider connection, or once from `--source sftp://user@host/path` with nothing saved, into an application folder on the server (`--dry-run` is the API's preview, `--confirm` starts it); `list`, `status --wait` (exit 0 only when it completed) and `stop` follow it. `--schedule '<cron>'` (repeat for up to five, `--timezone`, default UTC, and `--until <time>`) keeps it in sync; `run-now`, `pause`, `resume` and `schedule` (change times, zone or end date) act on a schedule. `--mirror` (advanced) also deletes, at most `--max-delete` a run |
244
246
  | `storage` | Purchased object storage: a capacity's price, the purchase, an increase or a resize at that price, which basis the bucket is billed on, the bucket's connection facts, its keys, objects and bindings, the downloads measured for a month, the ceiling that caps the overage bill, and the optional stored-byte maximum that limits growth without buying capacity |
245
247
  | `company` | The company itself, its members and roles, its activity, its logo and favicon, and the invitation journey |
246
248
  | `environment` | Create, read, scale, retry; profile coverage, domains and redirects, databases and exports, configuration and secrets, services, site access, tools, tuning, retention, portable export, and the release bundle |
@@ -270,6 +272,79 @@ Exit status: **0** ok, **1** refused by the API, **2** unusable — bad usage, n
270
272
  API. A refusal prints the API's message, its actionable `detail` when it sent one, and its `X-Request-Id`,
271
273
  which is what joins a failed command to the log line that explains it.
272
274
 
275
+ ## Environment files from this computer
276
+
277
+ `files ls|copy|mkdir|move|rm|pull|push|sync|mount` work on an environment's files over its SFTP login, and
278
+ `files connect` prints that login as a `known_hosts` line, an `ssh_config` Host block and an rclone remote
279
+ for your own `ssh`, `sftp` and `rclone` (it needs `--user`, names `--key-file` when given, otherwise your SSH
280
+ agent, and never prints a password). Every connection is checked against the SSH host key the platform
281
+ serves; a command refuses when it serves none. A key with a passphrase reads it with `--password-stdin` or
282
+ `--password-file` beside `--key-file`. While a transfer runs, each minute prints the files and bytes done
283
+ and, after two minutes and 20 files, the time left as a range ("about 11–16 min left"), fitted from both
284
+ the per-file and the per-byte rate. Ctrl-C during a transfer stops the copy engine cleanly and prints the
285
+ same report with the `interrupted` outcome (exit 1); run the command again to finish.
286
+
287
+ **Two-way sync.** `files sync env:/path ./folder --two-way --environment <uuid> --user <login> --confirm`
288
+ keeps a local folder and an environment folder the same both ways with rclone `bisync`. The first run (or
289
+ `--resync`) copies each side's missing and newer files to the other and deletes nothing; later runs carry
290
+ changes and deletions across in both directions. A file changed on both sides keeps both copies as
291
+ `name.conflict1` and `name.conflict2`, and the report lists every conflict copy still in the folder. A run
292
+ that would delete more than `--max-delete-percent` (default 50) of either side stops before deleting
293
+ (`too-many-deletes`, exit 1). The folder's `.hostingctl/` keeps which environment folder it is linked to and
294
+ the sync listings; it is never copied by `pull`, `push` or `sync`, and a folder linked to one environment folder
295
+ refuses another (`linked-elsewhere`). Like `push`, `sync` leaves `wp-config.php` alone unless
296
+ `--with-wp-config`. There is no `--preview` yet: `--dry-run` describes the run and contacts nothing.
297
+
298
+ **Mount.** `files mount env:/path ./empty-folder --environment <uuid> --user <login>` shows the environment
299
+ folder read-only in an empty local folder until Ctrl-C unmounts it; it writes nothing, so it needs no
300
+ `--confirm`. It needs macFUSE or FUSE-T on macOS and FUSE (`/dev/fuse` and `fusermount3`) on Linux; without
301
+ them, and on Windows for now, it refuses with what to install and exits 2 (`mount-unavailable`).
302
+
303
+ **The copy engine.** The first local `files` command fetches the official rclone 1.75.2 release (about
304
+ 32 MB) from `downloads.rclone.org`, checks it against its pinned SHA-256, and keeps only the program, about
305
+ 86 MB, in the cache folder. Both CLIs share it, every launch re-checks its checksum, an rclone on `PATH` is
306
+ never used, and `hostingctl update` moves the pin. `files connect` fetches nothing.
307
+
308
+ | System | Cache folder |
309
+ | --- | --- |
310
+ | Linux | `$XDG_CACHE_HOME/hostingctl/rclone/1.75.2/`, else `~/.cache/hostingctl/rclone/1.75.2/` |
311
+ | macOS | `~/Library/Caches/hostingctl/rclone/1.75.2/` (or under `$XDG_CACHE_HOME` when set) |
312
+ | Windows | `%LOCALAPPDATA%\hostingctl\cache\rclone\1.75.2\` (or under `%XDG_CACHE_HOME%` when set) |
313
+
314
+ To remove it, delete the `rclone` folder inside that cache folder; the next local `files` command fetches it
315
+ again. An older version is removed by itself when the pin moves.
316
+
317
+ **Where `files` runs.** The engine is built with Go 1.26, so the local commands need 64-bit Linux (x64 or
318
+ arm64) with kernel 3.2 or newer, macOS 12 or newer (Intel or Apple silicon), or 64-bit Windows 10 /
319
+ Server 2016 or newer. On an older Mac they refuse with that floor before anything is fetched. `files import`
320
+ runs on the server and has no such floor.
321
+
322
+ ## A local copy of a WordPress site
323
+
324
+ `hostingctl dev` makes and runs a local copy of one WordPress site with its database, using Docker:
325
+
326
+ ```bash
327
+ hostingctl dev prepare ./acme-site --company acme --environment <uuid> --database <database-uuid> \
328
+ --from env:/wordpress --user <login> --key-file ~/.ssh/acme --confirm
329
+ hostingctl dev start ./acme-site # http://localhost:<port>; mail is caught by Mailpit
330
+ hostingctl dev status ./acme-site # where it came from, when files and database were taken, what runs
331
+ hostingctl dev stop | refresh | delete ./acme-site
332
+ ```
333
+
334
+ `prepare` pulls the site's files into `files/` with the same engine as `files pull`, asks for a fresh
335
+ database export (the one `environment database-export-create` makes), waits for it, downloads it into
336
+ `database/` and checks it is the whole gzip file the platform measured. It then replaces the site's
337
+ `wp-config.php` with a local one (new database settings and salts, cron and automatic updates off,
338
+ `WP_HTTP_BLOCK_EXTERNAL`, mail to Mailpit) and writes `compose.yaml`: MariaDB 12.3, the public
339
+ `wordpress:6.8.3-php8.3-apache` image and Mailpit, with the site and Mailpit published on `127.0.0.1` only
340
+ and no database port. The first `start` imports the database and runs WP-CLI `search-replace` from the
341
+ site's address to the local one, skipping GUIDs. `refresh` prepares a sibling copy (starting from the
342
+ current files, so the pull fetches only changes), swaps it in when complete and keeps the old copy as
343
+ `<folder>.previous-<time>`; a failed refresh leaves the working copy as it was. `delete` removes the folder
344
+ and its database volume. The copy is unsanitized: it is your own data. The files and the database are
345
+ taken at different moments, and the database is never pushed back; `files push` from `files/` leaves
346
+ `wp-config.php` alone. Without Docker, `start` exits 2.
347
+
273
348
  ## Guided old-host connection setup
274
349
 
275
350
  In the native client, run `hostingctl provider-connections add --company <slug> --confirm` in a terminal.
@@ -278,10 +353,18 @@ a password, a generated SSH key or an existing private-key file. Connection deta
278
353
  host's FTP/SSH settings or welcome email. Generated-key setup explains where to authorize its public key.
279
354
  Private keys are read from a private local file; they are never command-line arguments.
280
355
 
356
+ The **Old host limits** step follows the login. **Normal** (2 connections at once, no speed or request limit) suits
357
+ most hosts; choose **Gentle** (1 connection, 2 requests a second) or **Very gentle** (1 connection, 1M a second,
358
+ 1 request a second) for a host that limits connections or speed. **Advanced** shows the five values; changing one
359
+ makes the preset **Custom**. Limit flags given to `add` fill this step in first.
360
+
281
361
  If the login or connection details fail, choose **Edit** to return to the relevant field with your
282
362
  other values kept. Use Ctrl+U to replace a hidden password. The saved connection and generated key
283
363
  are retained; the screen explains what to correct and where to find it. Session, transport and
284
364
  changed-server-identity failures stop with recovery commands rather than silently retrying.
365
+ If the old host refuses another connection, **Switch to Gentle and retry** saves Gentle on the same connection and
366
+ checks it again. Without the guided setup, `check` and `check-show` print the same suggestion:
367
+ `provider-connections update <uuid> --preset gentle --confirm`, then check again.
285
368
 
286
369
  The check reports its ID and stages, then offers detected site folders or a typed folder path.
287
370
  The old host's File Manager shows the path if it is unclear; Esc keeps the current folder. A changed