@studiometa/forge-cli 0.5.1 → 0.5.3

package/README.md

@@ -45,7 +45,7 @@ forge <command> [subcommand] [options]
 | ------------------- | ------- | ---------------------------------------------------- |
 | `config`            |         | Manage CLI configuration (`set`, `get`, `delete`)    |
 | `servers`           | `s`     | List, get, reboot servers                            |
-| `sites`             |         | List, get sites on a server                          |
+| `sites`             |         | List, get sites; apply a site file                   |
 | `deployments`       | `d`     | List deployments, trigger deploys, deploy script     |
 | `databases`         | `db`    | List, get databases on a server                      |
 | `database-users`    |         | List, get, create, delete database users on a server |
@@ -121,6 +121,7 @@ forge config delete                            # Delete all stored config
 ```bash
 forge servers list                  # List all servers
 forge servers get <id>              # Get server details
+forge servers public-key <id>       # Print the public key of the forge user, for the git host
 forge servers reboot <id>           # Reboot a server
 forge servers create --name <name> --ip-address <ip> [--php-version php84 --database mariadb1011]
                                     # Create a server (Custom VPS by default)
@@ -131,6 +132,97 @@ forge servers create --name <name> --ip-address <ip> [--php-version php84 --data
 ```bash
 forge sites list --server <id>              # List sites on a server
 forge sites get <site_id> --server <id>     # Get site details
+forge sites apply --file site.json --check  # Print the plan, change nothing
+forge sites apply --file site.json          # Make the site match the file
+```
+
+#### Declare a site in a file with `sites apply`
+
+`sites apply` makes a Forge site match a JSON file kept in the project, for example `config/forge/production/site.json`. Only `server` and `domain` are required. A key that is absent is not managed: `apply` does not read it, compare it or change it.
+
+```json
+{
+  "$schema": "https://unpkg.com/@studiometa/forge-cli/schemas/site.schema.json",
+  "server": "web-1",
+  "domain": "www.example.com",
+  "aliases": ["example.com"],
+  "type": "php",
+  "php": "php83",
+  "webDirectory": "/public",
+  "repository": {
+    "provider": "custom",
+    "url": "https://git.example.com/group/project.git",
+    "branch": "main"
+  },
+  "database": { "name": "example", "user": "example" },
+  "env": { "APP_ENV": "production" },
+  "nginx": "nginx.conf",
+  "workers": [{ "command": "php artisan queue:work database --queue=default", "processes": 4 }],
+  "schedule": [{ "command": "php artisan schedule:run", "frequency": "minutely" }]
+}
+```
+
+| Key                                         | What `apply` does                                                                                                                                                                      |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`, `domain`                          | Find the server and the site by exact name (never a partial match, with or without `--exact`). `server` can also be an ID                                                              |
+| `type`, `php`, `webDirectory`, `repository` | Create the site when it is missing (`type` is then required) and wait until Forge installs it. On an existing site, update `php`, `webDirectory` and the branch                        |
+| `aliases`                                   | Add the missing aliases. Never remove one                                                                                                                                              |
+| `database`                                  | Create the database and the user when they are missing. A new user gets a random password, written only into the site `.env` (`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, see below)  |
+| `env`                                       | Add the missing keys to the site `.env`. A key with another value on Forge is reported, never overwritten                                                                              |
+| `nginx`                                     | Nginx file, relative to the site file, with Forge template variables. Rendered for the site and written when it differs from Forge (see below)                                         |
+| `workers`                                   | Forge background processes of the site. Create the missing ones, delete the ones of the site that the file does not declare. The directory defaults to the site root                   |
+| `schedule`                                  | Forge scheduled jobs of the site (`minutely`, `hourly`, `nightly`, `weekly`, `monthly`, `reboot`, or `custom` with `cron`). A relative `artisan` becomes the absolute path of the site |
+
+For an application that does not read the Laravel names, `database.env` maps the database name, the user and the password to other `.env` keys. Each key is optional and defaults to the Laravel name. Other values, such as the host, go in `env`:
+
+```json
+{
+  "database": {
+    "name": "example",
+    "user": "example",
+    "env": { "name": "DB_NAME", "user": "DB_USER", "password": "DB_PASSWD" }
+  },
+  "env": { "DB_SERVER": "127.0.0.1" }
+}
+```
+
+`nginx` points to an Nginx file that uses the variables of [Forge Nginx templates](https://forge.laravel.com/docs/servers/nginx-templates). `apply` renders the file locally with the values of the site, so one file works on any server, without a template on the server:
+
+| Variable                                        | Value                                                                                                    |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `{{SITE}}`, `{{SITE_ID}}`, `{{USER}}`           | Site name (`www.example.com`), site ID (`456`), site user (`forge`)                                      |
+| `{{DOMAINS}}`                                   | Site name and aliases, separated by spaces                                                               |
+| `{{ROOT_PATH}}`, `{{PATH}}`, `{{DIRECTORY}}`    | Site root, web directory (`/home/forge/www.example.com/public`) and its relative path (`/public`)        |
+| `{{PROXY_PASS}}`                                | PHP-FPM socket, e.g. `unix:/var/run/php/php8.3-fpm.sock` (`php8.3-fpm-<user>.sock` for an isolated site) |
+| `{{PORT}}`, `{{PORT_V6}}`                       | `80` and `[::]:80` (with `default_server` for the site named `default`)                                  |
+| `{{SERVER_PUBLIC_IP}}`, `{{SERVER_PRIVATE_IP}}` | IP addresses of the server (empty when there is no private IP)                                           |
+
+Spaces inside the braces are allowed (`{{ SITE_ID }}`). An unknown variable is an error (exit `3`). On a new site, `apply` writes the file after Forge installs the site. On an existing site, the plan shows the diff from Forge to the rendered file (CRLF and the final newline do not count), and `apply` writes it. When `apply` also changes the site or its aliases, it reads the site again and renders the file with the new values. Forge returns the full `server` block on old servers and only its content on recent ones: write the file in the same form as `forge nginx get` prints it.
+
+Forge clones the repository when it creates the site, with the key of the `forge` user of the server. Add this key to the git host (for example as a deploy key) before `apply` creates the site:
+
+```bash
+forge servers public-key web-1 > server.pub   # The key only; --format json gives { "public_key": "..." }
+```
+
+A worker or a scheduled job matches the file when its command, directory, processes (or frequency) and user are the same. Commands are compared after normalization: quotes (`'database'` and `database`), repeated spaces and a relative `artisan` (`php artisan` and `php /home/forge/www.example.com/artisan`) do not count as differences. Forge cannot update a worker: a changed worker is created again, then the old one is deleted.
+
+`workers` and `schedule` delete what the file does not declare, so `apply` deletes only what surely belongs to the site, because a server often hosts several sites:
+
+- A scheduled job belongs to the site when Forge lists it on the site, or when its command uses the site path and no other site path.
+- A worker belongs to the site when its directory is the site path or inside it. Without a directory, its command must use the site path and no other site path, and Forge must associate it with the site.
+- Paths are compared on whole segments: `/home/forge/example.com` does not own `/home/forge/example.com-staging` or `/home/forge/example.com.old`.
+- Workers and scheduled jobs that run as `root` are never deleted, and neither are the ones whose owner is not certain: they are reported as kept.
+- Without the `workers` key, no worker is read or deleted. With `"workers": []`, all the workers of the site are deleted. The same applies to `schedule`.
+- The site, its aliases, its database and its `.env` keys are never deleted.
+
+With `--check`, `apply` prints the plan and changes nothing. It exits `0` when Forge matches the file, `1` when it differs, and another code on an error (`3` for an invalid file). Every deletion shows its ID and full command. The plan gives `.env` key names only, never values, and shows a generated password as `<generated>`. With `--format json`, it prints `{ "inSync": false, "changes": [...], "warnings": [...] }`.
+
+Run `--check` in merge request pipelines and `apply` on the main branch:
+
+```bash
+forge sites apply --file config/forge/production/site.json --check
+forge sites apply --file config/forge/production/site.json
 ```
 
 ### `deployments` (`d`) — Manage deployments
@@ -340,11 +432,23 @@ All write operations (`deploy`, `create`, `delete`, `reboot`, `restart`, `update
 | `--org <slug>`    |       | Organization slug (overrides config and env)     |
 | `--server <id>`   |       | Server ID or name (auto-resolved if non-numeric) |
 | `--site <id>`     |       | Site ID or domain (auto-resolved if non-numeric) |
+| `--exact`         |       | Match `--server` and `--site` names exactly      |
 | `--format <fmt>`  | `-f`  | Output format: `json`, `human`, `table`          |
 | `--no-color`      |       | Disable colored output                           |
 | `--help`          | `-h`  | Show help                                        |
 | `--version`       | `-v`  | Show version                                     |
 
+### Exact name matching
+
+`--server` and `--site` accept a numeric ID or a name. A name resolves to the server or site with that exact name first, then to a single partial match: `--site example.com` resolves to `shop.example.com` when no site is named `example.com`.
+
+In CI and scripts, turn on exact matching with the `--exact` flag or the `FORGE_EXACT_MATCH=1` environment variable. A name must then match exactly (case-insensitive); otherwise the command fails and lists the near matches.
+
+```bash
+FORGE_EXACT_MATCH=1 forge deployments deploy --server 123 --site example.com
+forge deployments deploy --server 123 --site example.com --exact
+```
+
 ## AI Agent Integration
 
 The CLI is designed for programmatic use by AI agents: