@francescomalatesta/laravel-forge-mcp 0.10.0 → 0.12.0

package/README.md

@@ -164,6 +164,34 @@ npm run build
 | `forge_delete_deploy_key` | deployments | Remove the deploy key |
 | `forge_get_deploy_hook` 🔑 | deployments | The deployment trigger URL |
 | `forge_regenerate_deploy_hook` 🔑 | deployments | Generate a new deployment trigger URL |
+| `forge_list_scheduled_jobs` | jobs | Scheduled jobs (cron) of a server or a site |
+| `forge_get_scheduled_job` | jobs | A scheduled job with the output of its last run |
+| `forge_create_scheduled_job` | jobs | Schedule a command, optionally with a heartbeat |
+| `forge_delete_scheduled_job` | jobs | Remove a scheduled job |
+| `forge_list_background_processes` | jobs | Supervisor daemons (queue workers, …) and their status |
+| `forge_get_background_process_log` | jobs | End of a background process log |
+| `forge_create_background_process` | jobs | Run a command permanently under Supervisor and wait until it is running |
+| `forge_update_background_process` | jobs | Rename or replace the Supervisor configuration |
+| `forge_run_background_process_action` | jobs | Start, stop or restart a background process, or empty its log |
+| `forge_delete_background_process` | jobs | Stop and remove a background process |
+| `forge_list_firewall_rules` | security | Open and blocked ports of a server |
+| `forge_create_firewall_rule` | security | Allow or deny a port (range) for everyone or an IP/subnet |
+| `forge_delete_firewall_rule` | security | Remove a firewall rule |
+| `forge_list_security_rules` | security | Password-protected (basic auth) paths of a site |
+| `forge_create_security_rule` | security | Protect a site or a path with a password |
+| `forge_update_security_rule` | security | Change name, path or users of a security rule |
+| `forge_delete_security_rule` | security | Remove a password protection |
+| `forge_list_redirect_rules` | security | Redirect rules of a site |
+| `forge_create_redirect_rule` | security | Add a 301 or 302 redirect |
+| `forge_delete_redirect_rule` | security | Remove a redirect |
+| `forge_reorder_redirect_rules` | security | Set the evaluation order of the redirects |
+| `forge_export_redirect_rules` | security | Redirects as CSV, in evaluation order |
+| `forge_import_redirect_rules` | security | Import redirects from CSV (append or replace) |
+| `forge_list_ssh_keys` | security | SSH keys authorized on a server |
+| `forge_add_ssh_key` | security | Authorize a public key |
+| `forge_delete_ssh_key` | security | Revoke an SSH key |
+| `forge_get_server_public_key` | security | The server's own public key (for Git providers, other servers) |
+| `forge_regenerate_server_key` | security | Replace the server's own key pair |
 | `forge_get_site_integrations` | integrations | Horizon, Octane, Reverb, Pulse, Inertia SSR, scheduler and maintenance mode status |
 | `forge_enable_site_integration` | integrations | Enable an integration (e.g. put the site in maintenance mode) and wait until it is active |
 | `forge_disable_site_integration` | integrations | Disable an integration (e.g. bring the site back up) |

package/dist/forge/client.js

@@ -78,11 +78,15 @@ export class ForgeClient {
     send(method, url, options) {
         const headers = {
             Authorization: `Bearer ${this.apiToken}`,
-            Accept: 'application/json',
+            Accept: options.accept ?? 'application/json',
             'User-Agent': this.userAgent,
         };
         let body;
-        if (options.body !== undefined) {
+        if (options.body instanceof FormData) {
+            // fetch sets the multipart Content-Type with its boundary.
+            body = options.body;
+        }
+        else if (options.body !== undefined) {
             headers['Content-Type'] = 'application/json';
             body = JSON.stringify(options.body);
         }

package/dist/tools/background-processes/create-background-process.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { idInput, organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { backgroundProcessOutput, backgroundProcessesPath, formatBackgroundProcess, processPhase } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+export const createBackgroundProcess = defineTool({
+    name: 'forge_create_background_process',
+    title: 'Create background process',
+    description: 'Run a command permanently in the background under Supervisor (e.g. `php artisan queue:work`), restarting it when it exits. For Horizon, Octane, Reverb, Pulse or Inertia SSR prefer forge_enable_site_integration. Waits until it is running unless `wait` is false.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.store', 'organizations.servers.background-processes.show'],
+    permissions: ['server:create-daemons', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).describe('Name of the background process, e.g. "Queue worker".'),
+        command: z.string().min(1).describe('Command to run, e.g. "php artisan queue:work --tries=3".'),
+        user: z.enum(['forge', 'root']).default('forge').describe('User the process runs as.'),
+        site: idInput('Site the process belongs to.').optional(),
+        directory: z.string().min(1).optional().describe('Working directory, e.g. "/home/forge/example.com/current".'),
+        processes: z.number().int().min(1).default(1).describe('Number of processes to keep running.'),
+        startsecs: z.number().int().min(0).optional().describe('Seconds the process must stay up to be considered started.'),
+        stopwaitsecs: z.number().int().min(0).optional().describe('Seconds to wait for a graceful stop before killing it.'),
+        stopsignal: z.string().min(1).optional().describe('Signal sent to stop it, e.g. "SIGTERM".'),
+        ...waitInput(120),
+    },
+    outputSchema: {
+        ...operationOutput,
+        background_process: backgroundProcessOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = backgroundProcessesPath(organization(args.organization), args.server);
+        const response = await client.post(base, {
+            body: {
+                name: args.name,
+                site_id: args.site === undefined ? undefined : Number(args.site),
+                command: args.command,
+                user: args.user,
+                directory: args.directory,
+                processes: args.processes,
+                startsecs: args.startsecs,
+                stopwaitsecs: args.stopwaitsecs,
+                stopsignal: args.stopsignal,
+            },
+            signal,
+        });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `start \`${args.command}\` in the background`;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, background_process: initial ? formatBackgroundProcess(initial) : null },
+                summary: `Forge accepted the request to ${action}. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readResource(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: (process) => processPhase(process.status, 'running'),
+            describe: (process) => `Background process is ${process.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const process = formatBackgroundProcess(result.value ?? initial);
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: `Process ID: ${process.id}.${result.status === 'failed' ? ' Read why with forge_get_background_process_log.' : ''}`,
+        });
+        return { structured: { ...done.structured, background_process: process }, summary: done.summary };
+    },
+});

package/dist/tools/background-processes/delete-background-process.js

@@ -0,0 +1,41 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+export const deleteBackgroundProcess = defineTool({
+    name: 'forge_delete_background_process',
+    title: 'Delete background process',
+    description: 'Stop a background process and remove it from Supervisor.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.destroy', 'organizations.servers.background-processes.show'],
+    permissions: ['server:delete-daemons', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = backgroundProcessPath(organization(args.organization), args.server, args.background_process);
+        await client.delete(path, { signal });
+        const action = `delete background process ${args.background_process}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (process) => (process === null ? 'completed' : 'pending'),
+            describe: (process) => `Background process is ${process?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/background-processes/get-background-process-log.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput, tail } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+export const getBackgroundProcessLog = defineTool({
+    name: 'forge_get_background_process_log',
+    title: 'Get background process log',
+    description: 'Read the end of the log of a background process (what the worker printed, crash traces). Empty it with forge_run_background_process_action.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.log.show'],
+    permissions: ['server:create-daemons'],
+    readOnly: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        lines: z.number().int().min(0).max(5000).default(100).describe('Return only the last N lines (0 = whole log).'),
+    },
+    outputSchema: {
+        log: z.string(),
+        truncated: z.boolean(),
+        total_lines: z.number().int(),
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = `${backgroundProcessPath(organization(args.organization), args.server, args.background_process)}/log`;
+        const log = tail((await readResource(client, path, signal)).content, args.lines);
+        return {
+            structured: { log: log.text, truncated: log.truncated, total_lines: log.total_lines },
+            summary: log.total_lines === 0 ? 'The log is empty.' : `Showing ${log.truncated ? `the last ${args.lines} of ` : ''}${log.total_lines} line(s).`,
+        };
+    },
+});

package/dist/tools/background-processes/list-background-processes.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { idInput, organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { backgroundProcessInput, backgroundProcessOutput, backgroundProcessPath, backgroundProcessesPath, formatBackgroundProcess, } from './shared.js';
+export const listBackgroundProcesses = defineTool({
+    name: 'forge_list_background_processes',
+    title: 'List background processes',
+    description: 'List the background processes (Supervisor daemons such as queue workers, Horizon or Reverb) on a server with their status, or get one with `background_process`. Filter by site, user or directory.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.index', 'organizations.servers.background-processes.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput.optional().describe('Return only this background process.'),
+        site: idInput('Only processes of this site.').optional(),
+        user: z.string().min(1).optional().describe('Only processes running as this user.'),
+        directory: z.string().min(1).optional().describe('Only processes running in this directory.'),
+        sort: z.array(z.enum(['user', '-user'])).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        background_processes: z.array(backgroundProcessOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        if (args.background_process !== undefined) {
+            const process = formatBackgroundProcess(await readResource(client, backgroundProcessPath(org, args.server, args.background_process), signal));
+            return {
+                structured: { background_processes: [process], next_cursor: null, has_more: false },
+                summary: `\`${process.command}\` is ${process.status}.`,
+            };
+        }
+        const response = await client.get(backgroundProcessesPath(org, args.server), {
+            query: {
+                filter: { site_id: args.site === undefined ? undefined : String(args.site), user: args.user, directory: args.directory },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const processes = page.items.map(formatBackgroundProcess);
+        const notRunning = processes.filter((process) => process.status !== 'running');
+        return {
+            structured: { background_processes: processes, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: processes.length === 0
+                ? 'No background processes found.'
+                : `Found ${processes.length} background process(es)${notRunning.length > 0 ? `; not running: ${notRunning.map((p) => `${p.id} (${p.status})`).join(', ')}` : ', all running'}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/background-processes/run-background-process-action.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessOutput, backgroundProcessPath, formatBackgroundProcess, processPhase, } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+const TARGET = { start: 'running', stop: 'stopped' };
+export const runBackgroundProcessAction = defineTool({
+    name: 'forge_run_background_process_action',
+    title: 'Run background process action',
+    description: 'Start, stop or restart a background process (e.g. restart queue workers after changing code outside a deployment), or empty its log. Waits for start and stop; restart and empty-log cannot be observed through the API.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.actions.store', 'organizations.servers.background-processes.show'],
+    permissions: ['server:create-daemons', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        action: z.enum(['restart', 'start', 'stop', 'empty-log']).describe('Action to run.'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        background_process: backgroundProcessOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = backgroundProcessPath(organization(args.organization), args.server, args.background_process);
+        await client.post(`${path}/actions`, { body: { action: args.action }, signal });
+        const action = `${args.action} background process ${args.background_process}`;
+        const target = args.action === 'start' || args.action === 'stop' ? TARGET[args.action] : undefined;
+        if (!target || !args.wait) {
+            // A restart ends in "running" like before it, and the log content is not compared: nothing to wait for.
+            const accepted = queued(action, CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, background_process: null } };
+        }
+        const result = await waitFor({
+            poll: () => readResource(client, path, signal),
+            phase: (process) => processPhase(process.status, target),
+            describe: (process) => `Background process is ${process.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return {
+            structured: { ...done.structured, background_process: result.value ? formatBackgroundProcess(result.value) : null },
+            summary: done.summary,
+        };
+    },
+});

package/dist/tools/background-processes/shared.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { serverPath } from '../servers/shared.js';
+export function backgroundProcessesPath(org, server) {
+    return `${serverPath(org, server)}/background-processes`;
+}
+export function backgroundProcessPath(org, server, process) {
+    return `${backgroundProcessesPath(org, server)}/${encodeURIComponent(String(process))}`;
+}
+export const backgroundProcessInput = idInput('Background process ID. Use forge_list_background_processes to find it.');
+export const BACKGROUND_PROCESS_NOT_FOUND_HINT = 'Check the background process ID with forge_list_background_processes.';
+const FIELDS = ['id', 'command', 'user', 'directory', 'processes', 'status', 'created_at'];
+export const backgroundProcessOutput = z.looseObject({
+    id: z.string(),
+    command: z.string().nullable(),
+    user: z.string().nullable(),
+    directory: z.string().nullable(),
+    processes: z.number().nullable().describe('Number of processes Supervisor keeps running.'),
+    status: z
+        .string()
+        .nullable()
+        .describe('installing, removing, restarting, starting, stopping, running, stopped, fatal, backoff, exited or unknown.'),
+    created_at: z.string().nullable(),
+});
+export function formatBackgroundProcess(flat) {
+    return pick(flat, FIELDS);
+}
+/** Waits for `target`; fatal and exited mean Supervisor gave up (backoff is still retrying). */
+export function processPhase(status, target) {
+    return phaseOf(status, { completed: [target], failed: ['fatal', 'exited'] });
+}

package/dist/tools/background-processes/update-background-process.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, queued } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+export const updateBackgroundProcess = defineTool({
+    name: 'forge_update_background_process',
+    title: 'Update background process',
+    description: 'Rename a background process and/or replace its Supervisor configuration (the [program:…] section: command, numprocs, user, stopwaitsecs, …). Supervisor reloads it.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.update'],
+    permissions: ['server:create-daemons'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        name: z.string().min(1).describe('Name of the background process (required by Forge: pass the current one to keep it).'),
+        config: z.string().min(1).optional().describe('Complete Supervisor configuration replacing the current one.'),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        await client.put(backgroundProcessPath(organization(args.organization), args.server, args.background_process), {
+            body: { name: args.name, config: args.config },
+            signal,
+        });
+        // Neither the name nor the configuration is exposed by the API: nothing to compare.
+        return queued(`update background process ${args.background_process}`, 'forge_list_background_processes', '(its status shows whether it is running again)');
+    },
+});

package/dist/tools/backups/create-backup-configuration.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import { defineTool } from '../define-tool.js';
 import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
 import { organizationInput, serverInput } from '../shared/schemas.js';
 import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
 import { databaseRefsInput, resolveDatabaseIds } from '../databases/shared.js';
-import { backupConfigurationOutput, backupConfigurationPhase, backupConfigurationsPath, formatBackupConfiguration, newestFirst, resolveStorageProviderId, scheduleBody, scheduleInput, storageProviderRefInput, } from './shared.js';
+import { backupConfigurationOutput, backupConfigurationPhase, backupConfigurationsPath, formatBackupConfiguration, resolveStorageProviderId, scheduleBody, scheduleInput, storageProviderRefInput, } from './shared.js';
 const CHECK_WITH = 'forge_list_backup_configurations';
 export const createBackupConfiguration = defineTool({
     name: 'forge_create_backup_configuration',
@@ -48,7 +49,7 @@ export const createBackupConfiguration = defineTool({
         const databaseIds = await resolveDatabaseIds(client, org, args.server, args.databases, signal);
         const base = backupConfigurationsPath(org, args.server);
         // Forge returns no body: remember the existing configurations to spot the new one.
-        const existing = args.wait ? new Set((await newestFirst(client, base, signal)).map((item) => item.id)) : undefined;
+        const existing = args.wait ? new Set((await listNewestFirst(client, base, signal)).map((item) => item.id)) : undefined;
         await client.post(base, {
             body: {
                 storage_provider_id: storageProviderId,
@@ -71,7 +72,7 @@ export const createBackupConfiguration = defineTool({
             };
         }
         const result = await waitFor({
-            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            poll: async () => findNew(await listNewestFirst(client, base, signal), existing),
             phase: (configuration) => (configuration ? backupConfigurationPhase(configuration.status) : 'pending'),
             describe: (configuration) => (configuration ? `Backup configuration is ${configuration.status}` : 'Waiting for the configuration to appear'),
             timeoutSeconds: args.timeout_seconds,

package/dist/tools/backups/create-backup.js

@@ -1,7 +1,8 @@
 import { defineTool } from '../define-tool.js';
 import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
 import { organizationInput, serverInput } from '../shared/schemas.js';
-import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupOutput, backupPhase, backupsPath, formatBackup, newestFirst, } from './shared.js';
+import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupOutput, backupPhase, backupsPath, formatBackup, } from './shared.js';
 const CHECK_WITH = 'forge_list_backups';
 export const createBackup = defineTool({
     name: 'forge_create_backup',
@@ -28,7 +29,7 @@ export const createBackup = defineTool({
     async handler(args, { client, organization, signal, sleep, progress }) {
         const base = backupsPath(organization(args.organization), args.server, args.backup_configuration);
         // Forge returns no body: remember the existing backups to spot the new one.
-        const existing = args.wait ? new Set((await newestFirst(client, base, signal)).map((item) => item.id)) : undefined;
+        const existing = args.wait ? new Set((await listNewestFirst(client, base, signal)).map((item) => item.id)) : undefined;
         await client.post(base, { signal });
         const action = `back up configuration ${args.backup_configuration}`;
         if (!existing) {
@@ -38,7 +39,7 @@ export const createBackup = defineTool({
             };
         }
         const result = await waitFor({
-            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            poll: async () => findNew(await listNewestFirst(client, base, signal), existing),
             phase: (backup) => (backup ? backupPhase(backup.status) : 'pending'),
             describe: (backup) => (backup ? `Backup is ${backup.status}` : 'Waiting for the backup to start'),
             timeoutSeconds: args.timeout_seconds,

package/dist/tools/backups/shared.js

@@ -100,11 +100,6 @@ export function formatBackup(flat) {
 export function backupPhase(status) {
     return phaseOf(status, { completed: ['finished'], failed: ['failed'] });
 }
-/** First page of a collection, newest first: used to spot items created by a write that returns no body. */
-export async function newestFirst(client, path, signal) {
-    const response = await client.get(path, { query: { sort: ['-created_at'], page: { size: 100 } }, signal });
-    return flattenCollection(response.data).items;
-}
 /** Resolves a storage provider ID or name to its ID. */
 export async function resolveStorageProviderId(client, org, ref, signal) {
     if (typeof ref === 'number' || /^\d+$/.test(ref))

package/dist/tools/commands/get-site-command.js

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import { defineTool } from '../define-tool.js';
 import { readResource } from '../shared/read.js';
 import { siteScopeInput } from '../shared/site-scope.js';
-import { commandInput, commandOutput, commandsPath, fetchOutput, formatCommand, NO_OUTPUT, outputFields, outputLinesInput } from './shared.js';
+import { fetchOutput, NO_OUTPUT, outputFields, outputLinesInput } from '../shared/output.js';
+import { commandInput, commandOutput, commandsPath, formatCommand } from './shared.js';
 export const getSiteCommand = defineTool({
     name: 'forge_get_site_command',
     title: 'Get site command',

package/dist/tools/commands/run-site-command.js

@@ -3,7 +3,8 @@ import { flattenCollection } from '../../forge/jsonapi.js';
 import { defineTool } from '../define-tool.js';
 import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
 import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
-import { commandOutput, commandPhase, commandsPath, fetchOutput, formatCommand, NO_OUTPUT, outputFields, outputLinesInput } from './shared.js';
+import { fetchOutput, NO_OUTPUT, outputFields, outputLinesInput } from '../shared/output.js';
+import { commandOutput, commandPhase, commandsPath, formatCommand } from './shared.js';
 const CHECK_WITH = 'forge_get_site_command';
 export const runSiteCommand = defineTool({
     name: 'forge_run_site_command',

package/dist/tools/commands/shared.js

@@ -1,8 +1,6 @@
 import { z } from 'zod';
-import { ForgeApiError } from '../../forge/errors.js';
 import { phaseOf } from '../shared/async.js';
-import { readResource } from '../shared/read.js';
-import { idInput, pick, tail } from '../shared/schemas.js';
+import { idInput, pick } from '../shared/schemas.js';
 import { sitePath } from '../shared/site-scope.js';
 export const COMMAND_STATUSES = ['waiting', 'running', 'finished', 'timeout', 'failed'];
 export function commandsPath(org, server, site) {
@@ -31,22 +29,3 @@ export function commandPhase(command) {
         return 'failed';
     return phase;
 }
-export const outputLinesInput = (fallback) => z.number().int().min(0).max(5000).default(fallback).describe('Return only the last N lines of the output (0 = full output).');
-export const outputFields = {
-    output: z.string().nullable().describe('Command output (last `output_lines` lines), or null when unavailable.'),
-    output_truncated: z.boolean(),
-    output_total_lines: z.number().int().nullable(),
-};
-export const NO_OUTPUT = { output: null, output_truncated: false, output_total_lines: null };
-/** Reads the output of a command run; null output when there is none yet. */
-export async function fetchOutput(client, path, lines, signal) {
-    try {
-        const output = tail((await readResource(client, `${path}/output`, signal)).output, lines);
-        return { output: output.text, output_truncated: output.truncated, output_total_lines: output.total_lines };
-    }
-    catch (error) {
-        if (error instanceof ForgeApiError && error.status === 404)
-            return NO_OUTPUT;
-        throw error;
-    }
-}

package/dist/tools/firewall/create-firewall-rule.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { firewallRuleOutput, firewallRulesPath, formatFirewallRule } from './shared.js';
+const CHECK_WITH = 'forge_list_firewall_rules';
+export const createFirewallRule = defineTool({
+    name: 'forge_create_firewall_rule',
+    title: 'Create firewall rule',
+    description: 'Open (allow) or block (deny) a port or port range on a server, for everyone or for an IP address or subnet. Waits until the rule is installed unless `wait` is false.',
+    toolset: 'security',
+    operations: ['organizations.servers.firewall-rules.store', 'organizations.servers.firewall-rules.index'],
+    permissions: ['server:manage-network'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).max(50).describe('Name of the rule, e.g. "MySQL from office".'),
+        port: z.string().min(1).optional().describe('Port or range, e.g. "3306" or "8000:8010". Omit for every port.'),
+        ip_address: z.string().min(1).optional().describe('IP address or subnet allowed/blocked, e.g. "203.0.113.4" or "10.0.0.0/16". Omit for any address.'),
+        type: z.enum(['allow', 'deny']).default('allow'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        rule: firewallRuleOutput.nullable().describe('The new rule once it shows up.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = firewallRulesPath(organization(args.organization), args.server);
+        // Forge returns no body: remember the existing rules with this name to spot the new one.
+        const lookup = () => listNewestFirst(client, base, signal, { name: args.name });
+        const existing = args.wait ? new Set((await lookup()).map((rule) => rule.id)) : undefined;
+        await client.post(base, { body: { name: args.name, port: args.port, ip_address: args.ip_address, type: args.type }, signal });
+        const action = `${args.type} ${args.port ? `port ${args.port}` : 'every port'}${args.ip_address ? ` from ${args.ip_address}` : ''}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, rule: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => findNew(await lookup(), existing),
+            phase: (rule) => (rule ? installationPhase(rule.status) : 'pending'),
+            describe: (rule) => (rule ? `Firewall rule is ${rule.status}` : 'Waiting for the rule to appear'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const rule = result.value ? formatFirewallRule(result.value) : null;
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: rule ? `Rule ID: ${rule.id}.` : undefined });
+        return { structured: { ...done.structured, rule }, summary: done.summary };
+    },
+});

package/dist/tools/firewall/delete-firewall-rule.js

@@ -0,0 +1,41 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { FIREWALL_RULE_NOT_FOUND_HINT, firewallRuleInput, firewallRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_firewall_rules';
+export const deleteFirewallRule = defineTool({
+    name: 'forge_delete_firewall_rule',
+    title: 'Delete firewall rule',
+    description: 'Remove a firewall rule from a server. Removing an allow rule closes the port: check that nothing (SSH, HTTP) depends on it.',
+    toolset: 'security',
+    operations: ['organizations.servers.firewall-rules.destroy', 'organizations.servers.firewall-rules.show'],
+    permissions: ['server:manage-network'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: FIREWALL_RULE_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        rule: firewallRuleInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${firewallRulesPath(organization(args.organization), args.server)}/${encodeURIComponent(String(args.rule))}`;
+        await client.delete(path, { signal });
+        const action = `delete firewall rule ${args.rule}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (rule) => (rule === null ? 'completed' : 'pending'),
+            describe: (rule) => `Firewall rule is ${rule?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});