@studiometa/forge-cli 0.5.0 → 0.5.2

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { C as isOutputFormat, _ as setToken, a as runCommand, c as OutputFormatter, d as createConfigStore$1, f as deleteToken, g as setOrganizationSlug, h as getToken$1, l as colors, m as getOrganizationSlug, n as exitWithError, o as createContext, r as exitWithValidationError, t as ExitCode, u as setColorEnabled, v as ApiError, x as ValidationError } from "./error-handler-Adi84RcF.js";
+import { C as isOutputFormat, _ as setToken, a as runCommand, c as OutputFormatter, d as createConfigStore$1, f as deleteToken, g as setOrganizationSlug, h as getToken$1, l as colors, m as getOrganizationSlug, n as exitWithError, o as createContext, r as exitWithValidationError, t as ExitCode, u as setColorEnabled, v as ApiError, x as ValidationError, y as CliError } from "./error-handler-s-BOJ1-h.js";
 import { STORAGE_PROVIDER_TYPES } from "@studiometa/forge-api";
-import { PHP_CONFIG_TYPES, RESTARTABLE_SERVICES, activateCertificate, createAuditLogger, createBackupConfig, createCommand, createDatabaseUser, createMonitor, createNginxTemplate, createRedirectRule, createScheduledJob, createSecurityRule, createServer, createSshKey, createStorageProvider, deleteBackupConfig, deleteDatabaseUser, deleteMonitor, deleteNginxTemplate, deleteRedirectRule, deleteScheduledJob, deleteSecurityRule, deleteSshKey, deleteStorageProvider, deploySiteAndWait, disablePhpOpcache, enablePhpOpcache, getBackupConfig, getCertificate, getCommand, getDaemon, getDaemonLog, getDatabase, getDatabaseUser, getDeploymentLog, getDeploymentScript, getEnv, getFirewallRule, getMonitor, getNginxConfig, getNginxTemplate, getPhpConfig, getPhpMaxExecutionTime, getPhpMaxUploadSize, getPhpOpcache, getRecipe, getRedirectRule, getScheduledJob, getSecurityRule, getServer, getSite, getSshKey, getStorageProvider, getUser, listBackupConfigs, listCommands, listDaemons, listDatabaseUsers, listDatabases, listDeployments, listFirewallRules, listMonitors, listNginxTemplates, listPhpVersions, listRecipes, listRedirectRules, listScheduledJobs, listSecurityRules, listServers, listServices, listSites, listSshKeys, listStorageProviders, matchByName, rebootServer, restartDaemon, restartService, runRecipe, updateBackupConfig, updateDaemon, updateDatabaseUser, updateDeploymentScript, updateEnv, updateNginxConfig, updateNginxTemplate, updatePhpConfig, updatePhpMaxExecutionTime, updatePhpMaxUploadSize, updateRecipe, updateSecurityRule, updateSite } from "@studiometa/forge-core";
+import { PHP_CONFIG_TYPES, RESTARTABLE_SERVICES, activateCertificate, createAuditLogger, createBackupConfig, createCommand, createDaemon, createDatabase, createDatabaseUser, createDomain, createMonitor, createNginxTemplate, createRedirectRule, createScheduledJob, createSecurityRule, createServer, createSite, createSshKey, createStorageProvider, deleteBackupConfig, deleteDaemon, deleteDatabaseUser, deleteMonitor, deleteNginxTemplate, deleteRedirectRule, deleteScheduledJob, deleteSecurityRule, deleteSshKey, deleteStorageProvider, deploySiteAndWait, disablePhpOpcache, enablePhpOpcache, getBackupConfig, getCertificate, getCommand, getDaemon, getDaemonLog, getDatabase, getDatabaseUser, getDeploymentLog, getDeploymentScript, getEnv, getFirewallRule, getMonitor, getNginxConfig, getNginxTemplate, getPhpConfig, getPhpMaxExecutionTime, getPhpMaxUploadSize, getPhpOpcache, getRecipe, getRedirectRule, getScheduledJob, getSecurityRule, getServer, getSite, getSshKey, getStorageProvider, getUser, listBackupConfigs, listCommands, listDaemons, listDatabaseUsers, listDatabases, listDeployments, listFirewallRules, listMonitors, listNginxTemplates, listPhpVersions, listRecipes, listRedirectRules, listScheduledJobs, listSecurityRules, listServers, listServices, listSites, listSshKeys, listStorageProviders, matchByName, rebootServer, restartDaemon, restartService, runRecipe, updateBackupConfig, updateDaemon, updateDatabaseUser, updateDeploymentScript, updateEnv, updateNginxConfig, updateNginxTemplate, updatePhpConfig, updatePhpMaxExecutionTime, updatePhpMaxUploadSize, updateRecipe, updateSecurityRule, updateSite } from "@studiometa/forge-core";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import { diff } from "node:util";
+import { createHash, randomBytes } from "node:crypto";
+import * as v from "valibot";
 import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
 //#region src/audit.ts
 /**
 * Shared audit logger for CLI write operations.
@@ -68,59 +69,65 @@ function createCommandRouter(config) {
 * Smart resolution utilities for --server and --site options.
 *
 * Accepts numeric IDs (used as-is) or plain strings (resolved by name/partial match).
+* In exact mode (`--exact` or `FORGE_EXACT_MATCH=1`), a plain string must match a name exactly.
 */
+var EXACT_MATCH_HINT = "Pass the numeric ID or the exact name, or turn off exact matching: remove --exact and unset FORGE_EXACT_MATCH";
+function formatResources(resources) {
+	return resources.map((r) => `  ${r.name} (${r.id})`).join("\n");
+}
+/**
+* Match a --server or --site value against a list of resources.
+*
+* - Numeric string → returned as-is
+* - Exact name (case-insensitive) → its ID
+* - Exact mode: no exact name → ValidationError listing the near (partial) matches
+* - Otherwise one partial match → its ID; 0 or 2+ partial matches → ValidationError
+*/
+function matchResourceId(value, resources, kind, scope, exactMatch) {
+	if (/^\d+$/.test(value)) return value;
+	const { exact, partial } = matchByName(resources, value, (r) => r.name);
+	if (exact.length === 1) return String(exact[0].id);
+	if (exactMatch && exact.length === 0) {
+		const candidates = partial.length > 0 ? `Near matches:\n${formatResources(partial)}` : `Available ${kind}s:\n${formatResources(resources)}`;
+		throw new ValidationError(`No ${kind} named "${value}"${scope} (exact match required)`, kind, [candidates, EXACT_MATCH_HINT]);
+	}
+	if (partial.length === 0) throw new ValidationError(`No ${kind} found matching "${value}"${scope}`, kind, [`Available ${kind}s:\n${formatResources(resources)}`]);
+	if (partial.length > 1) throw new ValidationError(`Ambiguous ${kind} name "${value}" — ${partial.length} matches found`, kind, [`Matching ${kind}s:\n${formatResources(partial)}`, "Use a more specific name or pass the numeric ID"]);
+	return String(partial[0].id);
+}
 /**
 * Resolve a --server value to a numeric server ID string.
 *
 * - Numeric string → returned as-is (no API call)
-* - Plain string → fetch all servers, exact match first, then partial match
-*   - 0 matches → ValidationError listing available servers
-*   - 2+ matches → ValidationError listing ambiguous matches
+* - Plain string → fetch all servers, then see {@link matchServerId}
 */
 async function resolveServerId(value, execCtx) {
 	if (/^\d+$/.test(value)) return value;
-	return matchServerId(value, (await listServers({}, execCtx)).data);
+	return matchServerId(value, (await listServers({}, execCtx)).data, execCtx.exactMatch);
 }
 /**
 * Resolve a --server value to a numeric server ID string, against a list of servers
-* that is already loaded. Same rules as {@link resolveServerId}, with no API call.
+* that is already loaded, with no API call.
+*
+* - Exact name match first, then a single partial match (unless `exactMatch`)
+*   - 0 matches → ValidationError listing available servers (near matches in exact mode)
+*   - 2+ matches → ValidationError listing ambiguous matches
 */
-function matchServerId(value, servers) {
-	if (/^\d+$/.test(value)) return value;
-	const { exact, partial } = matchByName(servers, value, (s) => s.name);
-	if (exact.length === 1) return String(exact[0].id);
-	if (partial.length === 0) {
-		const available = servers.map((s) => `  ${s.name} (${s.id})`).join("\n");
-		throw new ValidationError(`No server found matching "${value}"`, "server", [`Available servers:\n${available}`]);
-	}
-	if (partial.length > 1) {
-		const matches = partial.map((s) => `  ${s.name} (${s.id})`).join("\n");
-		throw new ValidationError(`Ambiguous server name "${value}" — ${partial.length} matches found`, "server", [`Matching servers:\n${matches}`, "Use a more specific name or pass the numeric ID"]);
-	}
-	return String(partial[0].id);
+function matchServerId(value, servers, exactMatch) {
+	return matchResourceId(value, servers, "server", "", exactMatch);
 }
 /**
 * Resolve a --site value to a numeric site ID string.
 *
 * - Numeric string → returned as-is (no API call)
-* - Plain string → fetch all sites for the server, exact domain match first, then partial
-*   - 0 matches → ValidationError listing available sites
+* - Plain string → fetch all sites for the server, exact domain match first, then a single
+*   partial match (unless `execCtx.exactMatch`)
+*   - 0 matches → ValidationError listing available sites (near matches in exact mode)
 *   - 2+ matches → ValidationError listing ambiguous matches
 */
 async function resolveSiteId(value, serverId, execCtx) {
 	if (/^\d+$/.test(value)) return value;
-	const sites = (await listSites({ server_id: serverId }, execCtx)).data;
-	const { exact, partial } = matchByName(sites, value, (s) => s.name);
-	if (exact.length === 1) return String(exact[0].id);
-	if (partial.length === 0) {
-		const available = sites.map((s) => `  ${s.name} (${s.id})`).join("\n");
-		throw new ValidationError(`No site found matching "${value}" on server ${serverId}`, "site", [`Available sites:\n${available}`]);
-	}
-	if (partial.length > 1) {
-		const matches = partial.map((s) => `  ${s.name} (${s.id})`).join("\n");
-		throw new ValidationError(`Ambiguous site name "${value}" — ${partial.length} matches found`, "site", [`Matching sites:\n${matches}`, "Use a more specific name or pass the numeric ID"]);
-	}
-	return String(partial[0].id);
+	return matchResourceId(value, (await listSites({ server_id: serverId }, execCtx)).data, "site", ` on server ${serverId}`, execCtx.exactMatch);
 }
 //#endregion
 //#region src/commands/backups/options.ts
@@ -454,7 +461,7 @@ _forge_completions() {
   # Subcommands for each command
   local config_cmds="set get delete"
   local servers_cmds="list ls get create reboot"
-  local sites_cmds="list ls get"
+  local sites_cmds="list ls get apply"
   local deployments_cmds="list ls deploy logs log script update-script"
   local databases_cmds="list ls get"
   local database_users_cmds="list ls get create delete"
@@ -479,7 +486,7 @@ _forge_completions() {
   local completion_cmds="bash zsh fish"
 
   # Global options
-  options="--token --server --site -f --format --no-color -h --help -v --version --name --command --content --from --to --provider --frequency --cron --type --operator --threshold --minutes --key --port --ip-address --user --private --dry-run --script --servers --domain --password --credential-id --region --size --project-type --directory --file --script-file --check --all-servers --prune --ubuntu-version --php-version --database --private-ip --ssh-port --tag --storage-provider --databases --retention --time --day --bucket --notification-email --include-new-databases --endpoint --access-key --secret-key-file --assume-role"
+  options="--token --server --site --exact -f --format --no-color -h --help -v --version --name --command --content --from --to --provider --frequency --cron --type --operator --threshold --minutes --key --port --ip-address --user --private --dry-run --script --servers --domain --password --credential-id --region --size --project-type --directory --file --script-file --check --all-servers --prune --ubuntu-version --php-version --database --private-ip --ssh-port --tag --storage-provider --databases --retention --time --day --bucket --notification-email --include-new-databases --endpoint --access-key --secret-key-file --assume-role"
 
   # Format options
   local formats="json human table"
@@ -676,6 +683,7 @@ _forge() {
             'list:List sites'
             'ls:List sites (alias)'
             'get:Get site details'
+            'apply:Make a site match a site file'
           )
           _describe 'sites command' sites_cmds
           ;;
@@ -915,6 +923,7 @@ _forge() {
         '--token[API token]:token:' \\
         '--server[Server ID]:server id:' \\
         '--site[Site ID]:site id:' \\
+        '--exact[Match server and site names exactly]' \\
         '(-f --format)'{-f,--format}'[Output format]:format:(json human table)' \\
         '--no-color[Disable colored output]' \\
         '(-h --help)'{-h,--help}'[Show help]' \\
@@ -1028,6 +1037,7 @@ complete -c forge -f -n "__fish_seen_subcommand_from servers s" -a "reboot" -d "
 complete -c forge -f -n "__fish_seen_subcommand_from sites" -a "list" -d "List sites"
 complete -c forge -f -n "__fish_seen_subcommand_from sites" -a "ls" -d "List sites (alias)"
 complete -c forge -f -n "__fish_seen_subcommand_from sites" -a "get" -d "Get site details"
+complete -c forge -f -n "__fish_seen_subcommand_from sites" -a "apply" -d "Make a site match a site file"
 
 # deployments subcommands
 complete -c forge -f -n "__fish_seen_subcommand_from deployments d" -a "list" -d "List deployments"
@@ -1175,6 +1185,7 @@ complete -c forge -f -n "__fish_seen_subcommand_from completion" -a "fish" -d "I
 complete -c forge -l token -d "API token" -r
 complete -c forge -l server -d "Server ID" -r
 complete -c forge -l site -d "Site ID" -r
+complete -c forge -l exact -d "Match server and site names exactly"
 complete -c forge -s f -l format -d "Output format" -xa "json human table"
 complete -c forge -l no-color -d "Disable colored output"
 complete -c forge -s h -l help -d "Show help"
@@ -4576,6 +4587,893 @@ Run ${colors.cyan("forge services <subcommand> --help")} for details.
 `);
 }
 //#endregion
+//#region src/commands/sites/apply/ownership.ts
+/**
+* Path and command helpers of `forge sites apply`: normalize commands so that
+* equivalent spellings compare equal, and find which site owns a daemon or a scheduled job.
+*
+* Ownership is strict on purpose: `apply` deletes the workers and scheduled jobs of a site
+* that the site file does not declare, and a server often hosts many sites.
+*/
+/**
+* Normalize an absolute path: resolve `.` and `..`, collapse repeated slashes
+* and drop the trailing slash.
+*/
+function normalizePath(path) {
+	const normalized = posix.normalize(path.trim());
+	return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+/**
+* Whether `path` is `root` or inside it, compared on whole path segments:
+* `/home/forge/a.com` contains `/home/forge/a.com/current` but not `/home/forge/a.com-staging`.
+*/
+function isPathInside(path, root) {
+	const child = normalizePath(path);
+	const parent = normalizePath(root);
+	if (parent === "/") return child.startsWith("/");
+	return child === parent || child.startsWith(`${parent}/`);
+}
+/**
+* Resolve `path` against `base` when it is relative.
+*/
+function resolvePath(base, path) {
+	return normalizePath(path.startsWith("/") ? path : posix.join(base, path));
+}
+function escapeRegExp(value) {
+	return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+/**
+* Whether a shell command uses `root` as a whole path: `root` must start the command or follow
+* a space, a quote, `=` or a shell operator, and must end the command or be followed by `/`,
+* a space, a quote or a shell operator. `/home/forge/a.com` is not found in
+* `/home/forge/a.com-staging/artisan`, `/home/forge/a.com.old` or `/home/forge/*`.
+*/
+function commandUsesPath(command, root) {
+	const path = normalizePath(root);
+	if (path === "/") return false;
+	return new RegExp(String.raw`(?:^|[\s'"=(;&|<>:])${escapeRegExp(path)}(?=$|[/\s'";&|)<>])`).test(command);
+}
+/**
+* Split a shell command into words, with the quoting rules of a POSIX shell:
+* single quotes keep everything, double quotes and a backslash escape one character.
+*/
+function splitCommand(command) {
+	const words = [];
+	let word = "";
+	let inWord = false;
+	let quote = null;
+	for (let index = 0; index < command.length; index++) {
+		const char = command[index];
+		if (quote === "'") if (char === "'") quote = null;
+		else word += char;
+		else if (quote === "\"") if (char === "\"") quote = null;
+		else if (char === "\\" && index + 1 < command.length && "\"\\$`".includes(command[index + 1])) word += command[++index];
+		else word += char;
+		else if (char === "'" || char === "\"") {
+			quote = char;
+			inWord = true;
+		} else if (char === "\\" && index + 1 < command.length) {
+			word += command[++index];
+			inWord = true;
+		} else if (/\s/.test(char)) {
+			if (inWord) words.push(word);
+			word = "";
+			inWord = false;
+		} else {
+			word += char;
+			inWord = true;
+		}
+	}
+	if (inWord) words.push(word);
+	return words;
+}
+/**
+* Quote a word for a POSIX shell when it needs quotes.
+*/
+function quoteWord(word) {
+	if (word !== "" && /^[\w@%+=:,./-]+$/.test(word)) return word;
+	return `'${word.replaceAll("'", String.raw`'\''`)}'`;
+}
+/**
+* Write a command in one canonical form, so that equivalent spellings compare equal:
+* quotes only where needed, single spaces, and a relative `artisan` (or `./artisan`)
+* replaced by its absolute path in `directory`.
+*
+* `php artisan queue:work 'database'  --queue="default"` in `/home/forge/example.com/`
+* gives `php /home/forge/example.com/artisan queue:work database --queue=default`.
+*/
+function canonicalCommand(command, directory) {
+	return splitCommand(command).map((word) => {
+		if (directory && (word === "artisan" || word === "./artisan")) return `${normalizePath(directory)}/artisan`;
+		return word;
+	}).map(quoteWord).join(" ");
+}
+/**
+* The site whose root holds `path`: the most specific root wins, so a site in
+* `/home/forge/a.com/admin` is not owned by `/home/forge/a.com`. Returns null when no site holds it.
+*/
+function siteOfPath(path, sites) {
+	let best = null;
+	for (const site of sites) for (const root of site.roots) if (isPathInside(path, root)) {
+		const length = normalizePath(root).length;
+		if (!best || length > best.length) best = {
+			id: site.id,
+			length
+		};
+	}
+	return best?.id ?? null;
+}
+/**
+* The sites whose roots a command uses as a path.
+*/
+function sitesOfCommand(command, sites) {
+	return sites.filter((site) => site.roots.some((root) => commandUsesPath(command, root))).map((site) => site.id);
+}
+/**
+* Ownership of a daemon (a Forge background process).
+*
+* - With a directory: the site that holds the directory (see {@link siteOfPath}).
+* - Without a directory: `ambiguous` when the command uses the site root, `site` only when
+*   the command uses no other site root and Forge also associates the daemon with the site.
+*/
+function daemonOwnership(daemon, siteId, sites, associatedWithSite) {
+	if (daemon.directory && daemon.directory.trim()) return siteOfPath(daemon.directory, sites) === siteId ? "site" : "other";
+	const owners = sitesOfCommand(daemon.command, sites);
+	if (!owners.includes(siteId)) return "other";
+	return owners.length === 1 && associatedWithSite ? "site" : "ambiguous";
+}
+/**
+* Ownership of a scheduled job. Forge lists the jobs of a site on a site route: those
+* belong to the site. A job of the server belongs to the site when its command uses the
+* site root and no other site root; when it uses several site roots, it is `ambiguous`.
+*/
+function scheduledJobOwnership(job, siteId, sites, listedOnSite) {
+	if (listedOnSite) return "site";
+	const owners = sitesOfCommand(job.command, sites);
+	if (!owners.includes(siteId)) return "other";
+	return owners.length === 1 ? "site" : "ambiguous";
+}
+//#endregion
+//#region src/commands/sites/apply/plan.ts
+/** Shown in place of a generated password. */
+var GENERATED = "<generated>";
+/** The path of the site folder, e.g. `/home/forge/example.com`. */
+function siteHome(site) {
+	return `/home/${site.user}/${site.name}`;
+}
+/** The directory that workers run in and relative `artisan` resolves against. */
+function siteWorkDirectory(site) {
+	return inSiteHome(site, site.root_directory || "/");
+}
+/**
+* Read a directory of a site, absolute (`/home/forge/example.com/public`) or relative to the
+* site folder (`/public`), as an absolute path inside the site folder. A relative `/` never
+* becomes the root of the server.
+*/
+function inSiteHome(site, directory) {
+	const home = siteHome(site);
+	return isPathInside(directory, home) ? normalizePath(directory) : resolvePath(home, directory.replace(/^\/+/, ""));
+}
+/** The paths that belong to each site, for ownership. */
+function siteRoots(sites) {
+	return sites.map((site) => ({
+		id: site.id,
+		roots: [...new Set([siteHome(site), siteWorkDirectory(site)].map(normalizePath))]
+	}));
+}
+/** `PHP 8.3`, `php83` and `php8.3` all give `php83`. */
+function normalizePhp(version) {
+	return version ? version.toLowerCase().replaceAll(/[^a-z0-9]/g, "") : null;
+}
+/** Forge displays frequencies in title case, e.g. `Minutely`. */
+function normalizeFrequency(frequency) {
+	return frequency.trim().toLowerCase();
+}
+/** The path a declared site uses before it exists, from its domain. */
+function plannedWorkDirectory(file) {
+	return `/home/forge/${file.domain}`;
+}
+function sameName(a, b) {
+	return a.toLowerCase() === b.toLowerCase();
+}
+/**
+* Pair declared items with existing ones that have the same key, each existing item once.
+* Returns the declared items without a match and the existing items without a match.
+*/
+function matchByKey(declared, existing, declaredKey, existingKey) {
+	const pool = existing.map((item) => ({
+		item,
+		key: existingKey(item),
+		used: false
+	}));
+	const missing = [];
+	for (const item of declared) {
+		const key = declaredKey(item);
+		const match = pool.find((entry) => !entry.used && entry.key === key);
+		if (match) match.used = true;
+		else missing.push(item);
+	}
+	return {
+		missing,
+		unmatched: pool.filter((entry) => !entry.used).map((entry) => entry.item)
+	};
+}
+function planSite(file, site, changes, warnings) {
+	if (!site) {
+		changes.push({
+			action: "create-site",
+			name: file.domain,
+			settings: {
+				type: file.type,
+				php_version: file.php,
+				web_directory: file.webDirectory,
+				source_control_provider: file.repository?.provider,
+				repository: file.repository?.url,
+				branch: file.repository?.branch
+			}
+		});
+		return;
+	}
+	const updates = [];
+	if (file.php && normalizePhp(site.php_version) !== normalizePhp(file.php)) updates.push({
+		field: "php_version",
+		from: site.php_version,
+		to: file.php
+	});
+	if (file.webDirectory) {
+		const root = siteWorkDirectory(site);
+		const expected = resolvePath(root, file.webDirectory.replace(/^\/+/, ""));
+		if ((isPathInside(site.web_directory, root) ? normalizePath(site.web_directory) : resolvePath(root, site.web_directory.replace(/^\/+/, ""))) !== expected) updates.push({
+			field: "web_directory",
+			from: site.web_directory,
+			to: file.webDirectory
+		});
+	}
+	if (file.repository?.branch && site.repository?.branch !== file.repository.branch) updates.push({
+		field: "branch",
+		from: site.repository?.branch ?? null,
+		to: file.repository.branch
+	});
+	if (updates.length > 0) changes.push({
+		action: "update-site",
+		changes: updates
+	});
+	const url = site.repository?.url;
+	if (file.repository && url && url.replace(/\.git$/, "") !== file.repository.url.replace(/\.git$/, "")) warnings.push(`Repository differs on Forge (${url}): apply does not change the repository of a site.`);
+	if (file.type && site.app_type && !sameName(site.app_type, file.type)) warnings.push(`Site type differs on Forge (${site.app_type}): apply does not change the type of a site.`);
+}
+function planAliases(file, site, changes) {
+	const existing = site ? [site.name, ...site.aliases ?? []].map(String) : [];
+	for (const alias of new Set(file.aliases ?? [])) if (!existing.some((name) => sameName(name, alias))) changes.push({
+		action: "add-alias",
+		name: alias
+	});
+}
+/**
+* Plan the database and its user. Returns the names of the .env keys that get generated values.
+*/
+function planDatabase(file, state, changes, warnings) {
+	if (!file.database) return [];
+	const { name, user } = file.database;
+	const databaseExists = (state.databases ?? []).some((db) => db.name === name);
+	const userExists = (state.databaseUsers ?? []).some((u) => u.name === user);
+	if (!databaseExists) changes.push({
+		action: "create-database",
+		name
+	});
+	if (!userExists) {
+		changes.push({
+			action: "create-database-user",
+			name: user,
+			database: name
+		});
+		return [
+			"DB_DATABASE",
+			"DB_USERNAME",
+			"DB_PASSWORD"
+		];
+	}
+	if (!databaseExists) warnings.push(`Database user ${user} exists: apply does not give it access to the new database ${name}.`);
+	return [];
+}
+function planEnv(file, state, generated, changes, warnings) {
+	const remote = parseEnv(state.env ?? "");
+	const keys = [];
+	for (const [key, value] of Object.entries(file.env ?? {})) {
+		if (generated.includes(key)) continue;
+		if (!remote.has(key)) keys.push(key);
+		else if (remote.get(key) !== String(value)) warnings.push(`.env key ${key} has another value on Forge: apply does not overwrite it.`);
+	}
+	if (keys.length > 0 || generated.length > 0) changes.push({
+		action: "add-env",
+		keys,
+		generated
+	});
+}
+function describeOwnership(ownership) {
+	return ownership === "ambiguous" ? "its owner is not certain" : "it runs as root";
+}
+function planWorkers(file, state, changes, warnings) {
+	if (!file.workers) return;
+	const site = state.site;
+	const workDirectory = site ? siteWorkDirectory(site) : plannedWorkDirectory(file);
+	const declared = file.workers.map((worker) => {
+		const directory = worker.directory ? resolvePath(workDirectory, worker.directory) : workDirectory;
+		return {
+			command: worker.command,
+			directory,
+			processes: worker.processes,
+			key: [
+				canonicalCommand(worker.command, directory),
+				directory,
+				worker.processes,
+				"forge"
+			].join("\n")
+		};
+	});
+	const roots = siteRoots(state.sites);
+	const { missing, unmatched } = matchByKey(declared, site ? (state.daemons ?? []).flatMap((daemon) => {
+		const ownership = daemonOwnership(daemon, site.id, roots, state.siteDaemonIds?.has(daemon.id) ?? false);
+		return ownership === "other" ? [] : [{
+			daemon,
+			ownership
+		}];
+	}) : [], (worker) => worker.key, ({ daemon }) => {
+		const directory = daemon.directory?.trim() ? normalizePath(daemon.directory) : null;
+		return [
+			canonicalCommand(daemon.command, directory),
+			directory ?? workDirectory,
+			daemon.processes,
+			daemon.user
+		].join("\n");
+	});
+	for (const worker of missing) changes.push({
+		action: "create-worker",
+		command: worker.command,
+		directory: worker.directory,
+		processes: worker.processes
+	});
+	for (const { daemon, ownership } of unmatched) if (ownership === "site" && daemon.user !== "root") changes.push({
+		action: "delete-worker",
+		id: daemon.id,
+		command: daemon.command,
+		directory: daemon.directory,
+		processes: daemon.processes
+	});
+	else warnings.push(`Kept daemon ${daemon.id} (${daemon.command}): not declared, but ${describeOwnership(ownership)}.`);
+}
+function planSchedule(file, state, changes, warnings) {
+	if (!file.schedule) return;
+	const site = state.site;
+	const workDirectory = site ? siteWorkDirectory(site) : plannedWorkDirectory(file);
+	const declared = file.schedule.map((job) => {
+		const command = canonicalCommand(job.command, workDirectory);
+		const frequency = normalizeFrequency(job.frequency);
+		return {
+			command,
+			frequency,
+			cron: job.cron,
+			key: [
+				command,
+				"forge",
+				frequency,
+				frequency === "custom" ? job.cron : ""
+			].join("\n")
+		};
+	});
+	const roots = siteRoots(state.sites);
+	const seen = /* @__PURE__ */ new Set();
+	const { missing, unmatched } = matchByKey(declared, site ? (state.jobs ?? []).flatMap((job) => {
+		if (seen.has(job.id)) return [];
+		seen.add(job.id);
+		const onSite = state.siteJobIds?.has(job.id) ?? false;
+		const ownership = scheduledJobOwnership(job, site.id, roots, onSite);
+		return ownership === "other" ? [] : [{
+			job,
+			ownership,
+			onSite
+		}];
+	}) : [], (job) => job.key, ({ job }) => {
+		const frequency = normalizeFrequency(job.frequency);
+		return [
+			canonicalCommand(job.command, workDirectory),
+			job.user,
+			frequency,
+			frequency === "custom" ? job.cron : ""
+		].join("\n");
+	});
+	for (const job of missing) changes.push({
+		action: "create-job",
+		command: job.command,
+		frequency: job.frequency,
+		...job.frequency === "custom" ? { cron: job.cron } : {}
+	});
+	for (const { job, ownership, onSite } of unmatched) if (ownership === "site" && job.user !== "root") changes.push({
+		action: "delete-job",
+		id: job.id,
+		command: job.command,
+		frequency: job.frequency,
+		cron: job.cron,
+		onSite
+	});
+	else warnings.push(`Kept scheduled job ${job.id} (${job.command}): not declared, but ${describeOwnership(ownership)}.`);
+}
+/**
+* Compare the site file with the state of Forge. Keys that the file does not have are not
+* compared. The plan creates and updates what differs, and deletes only the workers and
+* scheduled jobs that surely belong to the site and that the file does not declare.
+*/
+function buildPlan(file, state) {
+	const changes = [];
+	const warnings = [];
+	planSite(file, state.site, changes, warnings);
+	planAliases(file, state.site, changes);
+	const generated = planDatabase(file, state, changes, warnings);
+	if (file.env || generated.length > 0) planEnv(file, state, generated, changes, warnings);
+	planWorkers(file, state, changes, warnings);
+	planSchedule(file, state, changes, warnings);
+	return {
+		changes,
+		warnings
+	};
+}
+function quoted(value) {
+	return value ?? "(none)";
+}
+/**
+* One line per change, for human output. Values of .env keys never show.
+*/
+function describeChange(change) {
+	switch (change.action) {
+		case "create-site": {
+			const settings = Object.entries(change.settings).filter(([, value]) => value !== void 0).map(([key, value]) => `${key}: ${value}`);
+			return `+ create site ${change.name}${settings.length ? ` (${settings.join(", ")})` : ""}`;
+		}
+		case "update-site": return `~ update site: ${change.changes.map((c) => `${c.field} ${quoted(c.from)} → ${c.to}`).join(", ")}`;
+		case "add-alias": return `+ add alias ${change.name}`;
+		case "create-database": return `+ create database ${change.name}`;
+		case "create-database-user": return `+ create database user ${change.name} for ${change.database} (password: ${GENERATED})`;
+		case "add-env": return `+ add .env keys: ${[...change.keys, ...change.generated.map((key) => key === "DB_PASSWORD" ? `${key}=${GENERATED}` : key)].join(", ")}`;
+		case "create-worker": return `+ create worker: ${change.command} (directory: ${change.directory}, processes: ${change.processes})`;
+		case "delete-worker": return `- delete worker ${change.id}: ${change.command} (directory: ${quoted(change.directory)}, processes: ${change.processes})`;
+		case "create-job": return `+ create scheduled job: ${change.command} (${change.frequency}${change.cron ? ` ${change.cron}` : ""})`;
+		case "delete-job": return `- delete scheduled job ${change.id}: ${change.command} (${change.frequency.toLowerCase()} ${change.cron})`;
+	}
+}
+//#endregion
+//#region src/commands/sites/apply/apply.ts
+/**
+* Read the state of Forge for a site file, and run a plan against Forge.
+*/
+/** Error of `apply` that is not a validation error, e.g. a site that never gets installed. */
+var ApplyError = class extends CliError {
+	code = "APPLY_ERROR";
+	isRecoverable = false;
+};
+/**
+* Resolve the server of the site file, always with an exact name (never a partial match).
+*/
+async function resolveApplyServer(server, ctx) {
+	const value = String(server);
+	if (/^\d+$/.test(value)) return value;
+	return matchServerId(value, (await listServers({}, ctx)).data, true);
+}
+/**
+* The site named `domain` on the server, compared without case. A partial match never counts.
+*/
+function findSite(sites, domain) {
+	return sites.find((site) => site.name.toLowerCase() === domain.toLowerCase()) ?? null;
+}
+/**
+* Read from Forge what the site file manages, and nothing else.
+*/
+async function readRemoteState(file, serverId, ctx) {
+	const sites = (await listSites({ server_id: serverId }, ctx)).data;
+	const site = findSite(sites, file.domain);
+	const siteId = site ? String(site.id) : void 0;
+	const state = {
+		sites,
+		site
+	};
+	if (file.database) {
+		state.databases = (await listDatabases({ server_id: serverId }, ctx)).data;
+		state.databaseUsers = (await listDatabaseUsers({ server_id: serverId }, ctx)).data;
+	}
+	if (file.env || file.database) state.env = siteId ? (await getEnv({
+		server_id: serverId,
+		site_id: siteId
+	}, ctx)).data : null;
+	if (file.workers) {
+		state.daemons = (await listDaemons({ server_id: serverId }, ctx)).data;
+		state.siteDaemonIds = new Set(siteId ? (await listDaemons({
+			server_id: serverId,
+			site_id: siteId
+		}, ctx)).data.map((d) => d.id) : []);
+	}
+	if (file.schedule) {
+		const siteJobs = siteId ? (await listScheduledJobs({
+			server_id: serverId,
+			site_id: siteId
+		}, ctx)).data : [];
+		const serverJobs = (await listScheduledJobs({ server_id: serverId }, ctx)).data;
+		state.jobs = [...siteJobs, ...serverJobs];
+		state.siteJobIds = new Set(siteJobs.map((job) => job.id));
+	}
+	return state;
+}
+/**
+* Exit with a validation error when the site does not exist and the site file cannot create it.
+*/
+function assertCanCreateSite(file, state) {
+	if (!state.site && !file.type) throw new ValidationError(`Site ${file.domain} does not exist and the site file has no type to create it`, "type", ["Add \"type\" to the site file, e.g. \"type\": \"php\"", "Check the domain and the server"]);
+}
+/** A random password for a database user: 32 characters, letters and digits only. */
+function generatePassword() {
+	const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+	let password = "";
+	while (password.length < 32) for (const byte of randomBytes(64)) if (byte < 248 && password.length < 32) password += alphabet[byte % 62];
+	return password;
+}
+/** Write a value for a .env file, quoted when it needs quotes. */
+function formatEnvValue(value) {
+	if (/^[\w.,:/@+-]*$/.test(value)) return value;
+	if (!value.includes("'") && !value.includes("\n")) return `'${value}'`;
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n")}"`;
+}
+/**
+* Set .env variables: replace the line of a variable that exists, append the others.
+*/
+function setEnvValues(content, values) {
+	const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
+	const pending = new Map(values);
+	const result = lines.map((line) => {
+		const name = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=/.exec(line)?.[1];
+		if (name && pending.has(name)) {
+			const value = pending.get(name);
+			pending.delete(name);
+			return `${name}=${formatEnvValue(value)}`;
+		}
+		return line;
+	});
+	for (const [name, value] of pending) result.push(`${name}=${formatEnvValue(value)}`);
+	return `${result.join("\n")}\n`;
+}
+var defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+async function waitForSite(serverId, siteId, ctx, options) {
+	const sleep = options.sleep ?? defaultSleep;
+	const interval = options.pollIntervalMs ?? 5e3;
+	const timeout = options.timeoutMs ?? 6e5;
+	for (let waited = 0;; waited += interval) {
+		const site = (await getSite({
+			server_id: serverId,
+			site_id: siteId
+		}, ctx)).data;
+		if (site.status === "installed") return;
+		if (waited >= timeout) throw new ApplyError(`Site ${site.name} is still ${site.status} on Forge`, ["Run forge sites apply again once the site is installed"]);
+		await sleep(interval);
+	}
+}
+/**
+* Create the database and its user. Returns their IDs and the .env values to write.
+*/
+async function applyDatabase(file, plan, state, serverId, ctx, options) {
+	const env = /* @__PURE__ */ new Map();
+	const ids = {};
+	if (!file.database) return {
+		ids,
+		env
+	};
+	let databaseId = state.databases?.find((db) => db.name === file.database.name)?.id;
+	for (const change of plan.changes) if (change.action === "create-database") {
+		options.onChange?.(change);
+		databaseId = (await createDatabase({
+			server_id: serverId,
+			name: change.name
+		}, ctx)).data.id;
+	} else if (change.action === "create-database-user") {
+		options.onChange?.(change);
+		const password = (options.generatePassword ?? generatePassword)();
+		const user = await createDatabaseUser({
+			server_id: serverId,
+			name: change.name,
+			password,
+			...databaseId === void 0 ? {} : { database_ids: [databaseId] }
+		}, ctx);
+		ids.database_user_id = String(user.data.id);
+		env.set("DB_DATABASE", change.database);
+		env.set("DB_USERNAME", change.name);
+		env.set("DB_PASSWORD", password);
+	}
+	if (databaseId !== void 0) ids.database_id = databaseId;
+	return {
+		ids,
+		env
+	};
+}
+/**
+* Run the changes of a plan for a site that exists.
+*/
+async function applyChanges(file, plan, state, serverId, site, generatedEnv, ctx, options) {
+	const params = {
+		server_id: serverId,
+		site_id: String(site.id)
+	};
+	const { env: databaseEnv } = await applyDatabase(file, plan, state, serverId, ctx, options);
+	const env = new Map([...generatedEnv, ...databaseEnv]);
+	const creations = [];
+	const deletions = [];
+	for (const change of plan.changes) switch (change.action) {
+		case "update-site": {
+			options.onChange?.(change);
+			const update = {};
+			for (const { field, to } of change.changes) {
+				if (field === "php_version") update.php_version = to;
+				if (field === "web_directory") update.directory = to;
+				if (field === "branch") update.repository_branch = to;
+			}
+			await updateSite({
+				...params,
+				...update
+			}, ctx);
+			break;
+		}
+		case "add-alias":
+			options.onChange?.(change);
+			await createDomain({
+				...params,
+				name: change.name,
+				allow_wildcard_subdomains: false,
+				www_redirect_type: "none"
+			}, ctx);
+			break;
+		case "add-env":
+			for (const key of change.keys) env.set(key, String(file.env?.[key]));
+			break;
+		case "create-worker":
+		case "create-job":
+			creations.push(change);
+			break;
+		case "delete-worker":
+		case "delete-job":
+			deletions.push(change);
+			break;
+		default: break;
+	}
+	if (env.size > 0) {
+		const addEnv = plan.changes.find((change) => change.action === "add-env");
+		if (addEnv) options.onChange?.(addEnv);
+		const content = (await getEnv(params, ctx)).data;
+		await updateEnv({
+			...params,
+			content: setEnvValues(content, env)
+		}, ctx);
+	}
+	for (const change of creations) {
+		options.onChange?.(change);
+		if (change.action === "create-worker") await createDaemon({
+			server_id: serverId,
+			site_id: site.id,
+			name: change.command.slice(0, 255),
+			command: change.command,
+			user: "forge",
+			directory: change.directory,
+			processes: change.processes
+		}, ctx);
+		else if (change.action === "create-job") await createScheduledJob({
+			...params,
+			command: change.command,
+			user: "forge",
+			frequency: change.frequency,
+			...change.cron ? { cron: change.cron } : {}
+		}, ctx);
+	}
+	for (const change of deletions) {
+		options.onChange?.(change);
+		if (change.action === "delete-worker") await deleteDaemon({
+			server_id: serverId,
+			id: String(change.id)
+		}, ctx);
+		else if (change.action === "delete-job") await deleteScheduledJob({
+			server_id: serverId,
+			id: String(change.id),
+			...change.onSite ? { site_id: params.site_id } : {}
+		}, ctx);
+	}
+}
+/**
+* Apply a site file: create the site when it does not exist and wait until Forge installs it,
+* then read the state again and run the other changes. Returns the plan that ran first.
+*/
+async function applySiteFile(file, serverId, ctx, options = {}) {
+	let state = await readRemoteState(file, serverId, ctx);
+	const firstPlan = buildPlan(file, state);
+	let plan = firstPlan;
+	let generatedEnv = /* @__PURE__ */ new Map();
+	const createSiteChange = plan.changes.find((change) => change.action === "create-site");
+	if (createSiteChange && createSiteChange.action === "create-site") {
+		assertCanCreateSite(file, state);
+		const database = await applyDatabase(file, plan, state, serverId, ctx, options);
+		generatedEnv = database.env;
+		options.onChange?.(createSiteChange);
+		const { settings } = createSiteChange;
+		const created = await createSite({
+			server_id: serverId,
+			type: file.type,
+			name: file.domain,
+			...settings.php_version ? { php_version: settings.php_version } : {},
+			...settings.web_directory ? { web_directory: settings.web_directory } : {},
+			...settings.source_control_provider ? { source_control_provider: settings.source_control_provider } : {},
+			...settings.repository ? { repository: settings.repository } : {},
+			...settings.branch ? { branch: settings.branch } : {},
+			...database.ids
+		}, ctx);
+		await waitForSite(serverId, String(created.data.id), ctx, options);
+		state = await readRemoteState(file, serverId, ctx);
+		plan = buildPlan(file, state);
+	}
+	const site = state.site;
+	if (!site) throw new ApplyError(`Site ${file.domain} is not on server ${serverId} after its creation`);
+	await applyChanges(file, plan, state, serverId, site, generatedEnv, ctx, options);
+	return firstPlan;
+}
+//#endregion
+//#region src/commands/sites/apply/site-file.ts
+/**
+* The site file of `forge sites apply`: a JSON file that declares one Forge site.
+* A key that is absent is not managed; only `server` and `domain` are required.
+*/
+var text = v.pipe(v.string(), v.trim(), v.nonEmpty());
+var SITE_TYPES = [
+	"laravel",
+	"symfony",
+	"statamic",
+	"wordpress",
+	"phpmyadmin",
+	"php",
+	"nextjs",
+	"nuxtjs",
+	"static-html",
+	"other",
+	"custom"
+];
+var SOURCE_CONTROL_PROVIDERS = [
+	"github",
+	"gitlab",
+	"bitbucket",
+	"gitlab-custom",
+	"custom"
+];
+var SCHEDULE_FREQUENCIES = [
+	"minutely",
+	"hourly",
+	"nightly",
+	"weekly",
+	"monthly",
+	"reboot",
+	"custom"
+];
+var WorkerSchema = v.strictObject({
+	command: text,
+	processes: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+	directory: v.optional(text)
+});
+var ScheduledJobSchema = v.pipe(v.strictObject({
+	command: text,
+	frequency: v.picklist(SCHEDULE_FREQUENCIES),
+	cron: v.optional(text)
+}), v.check((job) => job.frequency === "custom" === (job.cron !== void 0), "cron is required with the custom frequency, and only with it"));
+var SiteFileSchema = v.strictObject({
+	$schema: v.optional(v.string()),
+	server: v.union([text, v.pipe(v.number(), v.integer(), v.minValue(1))]),
+	domain: text,
+	aliases: v.optional(v.array(text)),
+	type: v.optional(v.picklist(SITE_TYPES)),
+	php: v.optional(v.pipe(v.string(), v.regex(/^php\d+$/, "php must look like php83"))),
+	webDirectory: v.optional(text),
+	repository: v.optional(v.strictObject({
+		provider: v.picklist(SOURCE_CONTROL_PROVIDERS),
+		url: text,
+		branch: v.optional(text)
+	})),
+	database: v.optional(v.strictObject({
+		name: text,
+		user: text
+	})),
+	env: v.optional(v.record(v.pipe(v.string(), v.regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "invalid .env variable name")), v.union([
+		v.string(),
+		v.number(),
+		v.boolean()
+	]))),
+	workers: v.optional(v.array(WorkerSchema)),
+	schedule: v.optional(v.array(ScheduledJobSchema))
+});
+/**
+* Validate parsed JSON as a site file. Throws a ValidationError that lists every issue.
+*/
+function parseSiteFile(data, source = "site file") {
+	const result = v.safeParse(SiteFileSchema, data);
+	if (!result.success) {
+		const issues = result.issues.map((issue) => {
+			return `${v.getDotPath(issue) ?? "(root)"}: ${issue.message}`;
+		});
+		throw new ValidationError(`Invalid ${source}`, "file", issues);
+	}
+	return result.output;
+}
+/**
+* Read and validate a site file from disk.
+*/
+function readSiteFile(path) {
+	let content;
+	try {
+		content = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new ValidationError(`Cannot read site file ${path}: ${error instanceof Error ? error.message : String(error)}`, "file");
+	}
+	let data;
+	try {
+		data = JSON.parse(content);
+	} catch (error) {
+		throw new ValidationError(`Site file ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, "file");
+	}
+	return parseSiteFile(data, `site file ${path}`);
+}
+//#endregion
+//#region src/commands/sites/apply/handler.ts
+/**
+* `forge sites apply --file site.json [--check]`: make a Forge site match a site file.
+* With `--check`, print the plan and exit 1 when Forge differs, without any change.
+*/
+async function sitesApply(ctx, applyOptions = {}) {
+	const usage = "forge sites apply --file <site.json> [--check]";
+	const path = ctx.options.file;
+	const check = Boolean(ctx.options.check);
+	if (typeof path !== "string" || !path) exitWithValidationError("file", usage, ctx.formatter);
+	await runCommand(async () => {
+		const file = readSiteFile(path);
+		const token = ctx.getToken();
+		const execCtx = ctx.createExecutorContext(token);
+		const server_id = await resolveApplyServer(file.server, execCtx);
+		if (check) {
+			const state = await readRemoteState(file, server_id, execCtx);
+			assertCanCreateSite(file, state);
+			const plan = buildPlan(file, state);
+			const inSync = plan.changes.length === 0;
+			if (ctx.formatter.isJson()) ctx.formatter.output({
+				inSync,
+				changes: plan.changes,
+				warnings: plan.warnings
+			});
+			else {
+				for (const change of plan.changes) console.log(describeChange(change));
+				for (const warning of plan.warnings) ctx.formatter.warning(warning);
+				if (inSync) ctx.formatter.success(`Site ${file.domain} is in sync with Forge.`);
+				else ctx.formatter.error(`Site ${file.domain} differs from Forge.`);
+			}
+			if (!inSync) process.exitCode = ExitCode.GENERAL_ERROR;
+			return;
+		}
+		const applied = [];
+		const plan = await applySiteFile(file, server_id, execCtx, {
+			...applyOptions,
+			onChange: (change) => {
+				applied.push(change.action);
+				if (!ctx.formatter.isJson()) console.log(describeChange(change));
+			}
+		});
+		if (ctx.formatter.isJson()) ctx.formatter.output({
+			changes: plan.changes,
+			warnings: plan.warnings
+		});
+		else {
+			for (const warning of plan.warnings) ctx.formatter.warning(warning);
+			ctx.formatter.success(applied.length === 0 ? `Site ${file.domain} is in sync with Forge.` : `Site ${file.domain} applied: ${applied.length} change(s).`);
+		}
+	}, ctx.formatter);
+}
+//#endregion
 //#region src/commands/sites/handlers.ts
 async function sitesList(ctx) {
 	const server = String(ctx.options.server ?? "");
@@ -4660,8 +5558,10 @@ var handleSitesCommand = createCommandRouter({
 		list: sitesList,
 		ls: sitesList,
 		get: [sitesGet, "args"],
-		update: [sitesUpdate, "args"]
-	}
+		update: [sitesUpdate, "args"],
+		apply: (ctx) => sitesApply(ctx)
+	},
+	writeSubcommands: ["apply"]
 });
 //#endregion
 //#region src/commands/sites/help.ts
@@ -4692,6 +5592,38 @@ ${colors.bold("ARGUMENTS:")}
 ${colors.bold("OPTIONS:")}
   --server <id>       Server ID (required)
   -f, --format <fmt>  Output format: json, human, table
+`);
+	else if (subcommand === "apply") console.log(`
+${colors.bold("forge sites apply")} - Make a site match a site file
+
+${colors.bold("USAGE:")}
+  forge sites apply --file <site.json> [--check] [options]
+
+${colors.bold("OPTIONS:")}
+  --file <path>       Site file (required), e.g. config/forge/production/site.json
+  --check             Print the plan and change nothing: exit 0 when Forge matches,
+                      exit 1 when it differs, another code on error
+  -f, --format <fmt>  Output format: json, human
+
+${colors.bold("SITE FILE:")}
+  Only "server" (exact name or ID) and "domain" (exact site name) are required.
+  A key that is absent is not managed: apply does not read or change it.
+    type, php, webDirectory, repository   Create the site, or update php, web directory, branch
+    aliases                               Add missing aliases, never remove one
+    database { name, user }               Create when missing; a new user gets a random
+                                          password, written into the site .env only
+    env                                   Add missing keys, never overwrite a value
+    workers, schedule                     Create missing ones, delete the ones of the site
+                                          that the file does not declare ([] deletes all)
+
+  A worker or scheduled job is deleted only when it surely belongs to the site:
+  Forge lists it on the site, or its directory (or, without a directory, its command)
+  uses the site path, compared on whole path segments. Jobs of root are never deleted.
+  The plan never prints .env values.
+
+${colors.bold("EXAMPLES:")}
+  forge sites apply --file config/forge/production/site.json --check
+  forge sites apply --file config/forge/production/site.json
 `);
 	else console.log(`
 ${colors.bold("forge sites")} - Manage sites
@@ -4702,6 +5634,7 @@ ${colors.bold("USAGE:")}
 ${colors.bold("SUBCOMMANDS:")}
   list, ls            List sites on a server
   get <id>            Get site details
+  apply               Make a site match a site file (--file, --check)
 
 ${colors.bold("OPTIONS:")}
   --server <id>       Server ID (required for most commands)
@@ -4711,6 +5644,7 @@ ${colors.bold("OPTIONS:")}
 ${colors.bold("EXAMPLES:")}
   forge sites list --server 123
   forge sites get 456 --server 123
+  forge sites apply --file config/forge/production/site.json --check
 
 Run ${colors.cyan("forge sites <subcommand> --help")} for subcommand details.
 `);
@@ -5042,7 +5976,7 @@ async function resolveTargets(values, allServers, execCtx) {
 	}));
 	const targets = /* @__PURE__ */ new Map();
 	for (const value of values) {
-		const id = Number(matchServerId(value, servers));
+		const id = Number(matchServerId(value, servers, execCtx.exactMatch));
 		targets.set(id, servers.find((s) => s.id === id)?.name ?? String(id));
 	}
 	return [...targets].map(([id, name]) => ({
@@ -5502,6 +6436,11 @@ var REPEATABLE = /* @__PURE__ */ new Set([
 	"databases"
 ]);
 /**
+* Long options that never take a value, so the argument after them stays a command
+* or a positional argument (`forge --exact deployments deploy`).
+*/
+var FLAGS = /* @__PURE__ */ new Set(["exact"]);
+/**
 * Set an option value. A repeatable option given more than once collects its string
 * values into an array (`--server 1 --server 2` → `["1", "2"]`).
 */
@@ -5522,7 +6461,7 @@ function parseArgs(argv = process.argv.slice(2)) {
 			else {
 				const key = arg.slice(2);
 				const nextArg = argv[i + 1];
-				if (nextArg !== void 0 && isOptionValue(nextArg)) {
+				if (!FLAGS.has(key) && nextArg !== void 0 && isOptionValue(nextArg)) {
 					setOption(options, key, nextArg);
 					i++;
 				} else setOption(options, key, true);
@@ -5554,7 +6493,7 @@ function isVersionRequest({ command, options }) {
 }
 //#endregion
 //#region src/cli.ts
-var VERSION = "0.5.0";
+var VERSION = "0.5.2";
 function showHelp() {
 	console.log(`
 ${colors.bold("forge")} v${VERSION}
@@ -5577,6 +6516,7 @@ ${colors.bold("COMMANDS:")}
   sites               Manage sites
     list, ls            List sites (requires --server)
     get <id>            Get site details (requires --server)
+    apply               Make a site match a site file (--file, --check)
 
   deployments, d      Manage deployments
     list, ls            List deployments (requires --server --site)
@@ -5710,6 +6650,7 @@ ${colors.bold("OPTIONS:")}
   --org <slug>        Organization slug (overrides config and FORGE_ORG)
   --server <id>       Server ID (required for server-scoped commands)
   --site <id>         Site ID (required for site-scoped commands)
+  --exact             Match --server and --site names exactly (no partial match)
   --domain <id>       Domain record ID (for certificate commands)
   -f, --format <fmt>  Output format: json, human, table (default: human)
   --no-color          Disable colored output
@@ -5743,6 +6684,7 @@ ${colors.bold("CREDENTIAL PRIORITY:")}
 ${colors.bold("ENVIRONMENT VARIABLES:")}
   FORGE_API_TOKEN    API token
   FORGE_ORG          Organization slug (e.g. studio-meta)
+  FORGE_EXACT_MATCH  Set to 1 to match --server and --site names exactly (same as --exact)
   NO_COLOR           Disable colors
   XDG_CONFIG_HOME    Config directory (respects XDG spec)
 `);