@francescomalatesta/laravel-forge-mcp 0.7.0 → 0.9.0

package/README.md

@@ -127,6 +127,27 @@ npm run build
 | `forge_set_php_opcache` | servers | Enable or disable OPcache |
 | `forge_get_php_config` | servers | FPM or CLI php.ini, or the FPM pool configuration |
 | `forge_update_php_config` | servers | Replace a PHP configuration file |
+| `forge_list_databases` | databases | Database schemas on a server |
+| `forge_create_database` | databases | Create a database (optionally with a user) and wait until installed |
+| `forge_delete_database` | databases | Drop a database |
+| `forge_sync_databases` | databases | Import databases created outside Forge |
+| `forge_list_database_users` | databases | Database users on a server |
+| `forge_create_database_user` | databases | Create a user with access to databases (by ID or name) |
+| `forge_update_database_user` | databases | Change a user's password or databases |
+| `forge_delete_database_user` | databases | Delete a database user |
+| `forge_update_database_root_password` | databases | Change the database root password |
+| `forge_list_backup_configurations` | databases | Scheduled database backups: storage, schedule, retention, next run |
+| `forge_create_backup_configuration` | databases | Schedule backups of databases (by ID or name) to a storage provider |
+| `forge_update_backup_configuration` | databases | Change storage, databases, schedule or retention |
+| `forge_delete_backup_configuration` | databases | Stop scheduled backups |
+| `forge_list_backups` | databases | Backups of a configuration with status and size |
+| `forge_create_backup` | databases | Run a backup now and wait until it finishes |
+| `forge_delete_backup` | databases | Delete a backup |
+| `forge_restore_backup` | databases | Restore a database from a backup (overwrites it) |
+| `forge_list_storage_providers` | storage | S3, Spaces, Hetzner, OVH, Scaleway or S3-compatible storage for backups |
+| `forge_create_storage_provider` | storage | Add a storage provider (credentials are never returned) |
+| `forge_update_storage_provider` | storage | Change name, location or credentials |
+| `forge_delete_storage_provider` | storage | Remove a storage provider that no backup uses |
 | `forge_list_deployments` | deployments | Deployments of a site or of every site on a server |
 | `forge_get_deployment` | deployments | A deployment with the end of its log |
 | `forge_get_deployment_status` | deployments | Whether a deployment is running |

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

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.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';
+const CHECK_WITH = 'forge_list_backup_configurations';
+export const createBackupConfiguration = defineTool({
+    name: 'forge_create_backup_configuration',
+    title: 'Create backup configuration',
+    description: 'Schedule database backups on a server to a storage provider (S3, Spaces, …): which databases, how often, how many to keep. Waits until the configuration is installed unless `wait` is false. Run a backup immediately with forge_create_backup.',
+    toolset: 'databases',
+    operations: [
+        'organizations.servers.database.backups.store',
+        'organizations.servers.database.backups.index',
+        'organizations.servers.database.schemas.index',
+        'organizations.storage-providers.index',
+    ],
+    permissions: ['server:create-backups', 'server:view', 'storage:manage'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        storage_provider: storageProviderRefInput,
+        databases: databaseRefsInput.min(1).describe('Databases to back up, by ID or name, e.g. [12, "shop"].'),
+        retention: z.number().int().min(1).max(8760).describe('Number of backups to keep (older ones are deleted).'),
+        ...scheduleInput,
+        name: z.string().min(1).max(255).optional().describe('Name of the configuration.'),
+        include_new_databases: z.boolean().optional().describe('Also back up databases created later on this server.'),
+        bucket: z.string().min(1).optional().describe("Bucket, if different from the storage provider's."),
+        directory: z.string().min(1).optional().describe('Directory inside the bucket.'),
+        notification_email: z.string().email().optional().describe('Email notified when a backup fails.'),
+        ...waitInput(120),
+    },
+    outputSchema: {
+        ...operationOutput,
+        backup_configuration: backupConfigurationOutput.nullable().describe('The new configuration once it shows up.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const schedule = scheduleBody(args);
+        const org = organization(args.organization);
+        const storageProviderId = await resolveStorageProviderId(client, org, args.storage_provider, signal);
+        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;
+        await client.post(base, {
+            body: {
+                storage_provider_id: storageProviderId,
+                name: args.name,
+                bucket: args.bucket,
+                directory: args.directory,
+                ...schedule,
+                include_new_databases: args.include_new_databases,
+                database_ids: databaseIds,
+                retention: args.retention,
+                notification_email: args.notification_email,
+            },
+            signal,
+        });
+        const action = `create the backup configuration${args.name ? ` ${args.name}` : ''}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, backup_configuration: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            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,
+            context: { sleep, progress },
+        });
+        const configuration = result.value ? formatBackupConfiguration(result.value) : null;
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: configuration ? `Configuration ID: ${configuration.id}; next run: ${configuration.next_run_time}.` : undefined,
+        });
+        return { structured: { ...done.structured, backup_configuration: configuration }, summary: done.summary };
+    },
+});

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

@@ -0,0 +1,56 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupOutput, backupPhase, backupsPath, formatBackup, newestFirst, } from './shared.js';
+const CHECK_WITH = 'forge_list_backups';
+export const createBackup = defineTool({
+    name: 'forge_create_backup',
+    title: 'Run backup now',
+    description: 'Back up the databases of a backup configuration now, outside its schedule (e.g. before a risky deployment or migration). Waits until the backup finishes unless `wait` is false.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.instances.store', 'organizations.servers.database.backups.instances.index'],
+    permissions: ['server:create-backups'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: BACKUP_CONFIGURATION_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput,
+        ...waitInput(300),
+    },
+    outputSchema: {
+        ...operationOutput,
+        backup: backupOutput.nullable().describe('The new backup once it shows up.'),
+    },
+    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;
+        await client.post(base, { signal });
+        const action = `back up configuration ${args.backup_configuration}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, backup: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            phase: (backup) => (backup ? backupPhase(backup.status) : 'pending'),
+            describe: (backup) => (backup ? `Backup is ${backup.status}` : 'Waiting for the backup to start'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const backup = result.value ? formatBackup(result.value) : null;
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: backup ? `Backup ID: ${backup.id}.` : undefined,
+        });
+        return { structured: { ...done.structured, backup }, summary: done.summary };
+    },
+});

package/dist/tools/backups/delete-backup-configuration.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 { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupConfigurationPath } from './shared.js';
+const CHECK_WITH = 'forge_list_backup_configurations';
+export const deleteBackupConfiguration = defineTool({
+    name: 'forge_delete_backup_configuration',
+    title: 'Delete backup configuration',
+    description: 'Stop scheduled backups by deleting a backup configuration. The databases are not touched.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.destroy', 'organizations.servers.database.backups.show'],
+    permissions: ['server:delete-backups', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: BACKUP_CONFIGURATION_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = backupConfigurationPath(organization(args.organization), args.server, args.backup_configuration);
+        await client.delete(path, { signal });
+        const action = `delete backup configuration ${args.backup_configuration}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (configuration) => (configuration === null ? 'completed' : 'pending'),
+            describe: (configuration) => `Backup configuration is ${configuration?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

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

@@ -0,0 +1,42 @@
+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 { backupConfigurationInput, backupInput, backupsPath } from './shared.js';
+const CHECK_WITH = 'forge_list_backups';
+export const deleteBackup = defineTool({
+    name: 'forge_delete_backup',
+    title: 'Delete backup',
+    description: 'Delete a backup from storage. It can no longer be restored.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.instances.destroy', 'organizations.servers.database.backups.instances.show'],
+    permissions: ['server:delete-backups', 'server:create-backups'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: 'Check the backup configuration ID with forge_list_backup_configurations and the backup ID with forge_list_backups.',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput,
+        backup: backupInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${backupsPath(organization(args.organization), args.server, args.backup_configuration)}/${encodeURIComponent(String(args.backup))}`;
+        await client.delete(path, { signal });
+        const action = `delete backup ${args.backup}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (backup) => (backup === null ? 'completed' : 'pending'),
+            describe: () => 'Waiting for the backup to be deleted',
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/backups/list-backup-configurations.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { backupConfigurationInput, backupConfigurationOutput, backupConfigurationPath, backupConfigurationsPath, formatBackupConfiguration, } from './shared.js';
+const SORT = ['name', '-name', 'created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listBackupConfigurations = defineTool({
+    name: 'forge_list_backup_configurations',
+    title: 'List backup configurations',
+    description: 'List the database backup configurations of a server (schedule, storage, databases, retention, next run), or get one with `backup_configuration`. Use forge_list_backups to see the backups it produced.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.index', 'organizations.servers.database.backups.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput.optional().describe('Return only this backup configuration.'),
+        name: z.string().min(1).optional().describe('Filter by name.'),
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "installed".'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        backup_configurations: z.array(backupConfigurationOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        if (args.backup_configuration !== undefined) {
+            const configuration = formatBackupConfiguration(await readResource(client, backupConfigurationPath(org, args.server, args.backup_configuration), signal));
+            return {
+                structured: { backup_configurations: [configuration], next_cursor: null, has_more: false },
+                summary: `Backup configuration ${configuration.name} is ${configuration.status}; schedule: ${configuration.displayable_schedule}, next run: ${configuration.next_run_time}.`,
+            };
+        }
+        const response = await client.get(backupConfigurationsPath(org, args.server), {
+            query: { filter: { name: args.name, status: args.status }, sort: args.sort, page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const configurations = page.items.map(formatBackupConfiguration);
+        return {
+            structured: { backup_configurations: configurations, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: configurations.length === 0
+                ? 'No backup configurations found. Create one with forge_create_backup_configuration.'
+                : `Found ${configurations.length} backup configuration(s): ${configurations
+                    .map((c) => `${c.name} (${c.id}, ${c.displayable_schedule})`)
+                    .join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/backups/list-backups.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupInput, backupOutput, backupsPath, formatBackup, } from './shared.js';
+const SORT = ['created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listBackups = defineTool({
+    name: 'forge_list_backups',
+    title: 'List backups',
+    description: 'List the backups produced by a backup configuration (status, size, completion time), or get one with `backup`. Restore one with forge_restore_backup.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.instances.index', 'organizations.servers.database.backups.instances.show'],
+    permissions: ['server:create-backups'],
+    readOnly: true,
+    notFoundHint: BACKUP_CONFIGURATION_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput,
+        backup: backupInput.optional().describe('Return only this backup.'),
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "finished".'),
+        sort: z.array(z.enum(SORT)).min(1).optional().describe('Defaults to newest first.'),
+        ...paginationInput,
+    },
+    outputSchema: {
+        backups: z.array(backupOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = backupsPath(organization(args.organization), args.server, args.backup_configuration);
+        if (args.backup !== undefined) {
+            const backup = formatBackup(await readResource(client, `${base}/${encodeURIComponent(String(args.backup))}`, signal));
+            return { structured: { backups: [backup], next_cursor: null, has_more: false }, summary: `Backup ${backup.id} is ${backup.status}.` };
+        }
+        const response = await client.get(base, {
+            query: { filter: { status: args.status }, sort: args.sort ?? ['-created_at'], page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const backups = page.items.map(formatBackup);
+        return {
+            structured: { backups, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: backups.length === 0
+                ? 'No backups found. Run one now with forge_create_backup.'
+                : `Found ${backups.length} backup(s); the first is ${backups[0].id} (${backups[0].status}).${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

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

@@ -0,0 +1,37 @@
+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 { resolveDatabaseIds } from '../databases/shared.js';
+import { backupConfigurationInput, backupInput, backupsPath } from './shared.js';
+export const restoreBackup = defineTool({
+    name: 'forge_restore_backup',
+    title: 'Restore backup',
+    description: 'Restore a database from a backup. This OVERWRITES the current content of the database with the backup: data written since the backup is lost. Confirm with the user first and consider running forge_create_backup before.',
+    toolset: 'databases',
+    operations: ['organizations.servers.database.backups.instances.restores.store', 'organizations.servers.database.schemas.index'],
+    permissions: ['server:create-backups', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: 'Check the backup configuration ID with forge_list_backup_configurations and the backup ID with forge_list_backups.',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        backup_configuration: backupConfigurationInput,
+        backup: backupInput,
+        database: z
+            .union([z.number().int().nonnegative(), z.string().min(1)])
+            .describe('Database to restore, by ID or name (it must be included in the backup).'),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const [databaseId] = await resolveDatabaseIds(client, org, args.server, [args.database], signal);
+        const path = `${backupsPath(org, args.server, args.backup_configuration)}/${encodeURIComponent(String(args.backup))}/restores`;
+        await client.post(path, { body: { database_id: databaseId }, signal });
+        // The API exposes no restore status: Forge records the outcome as a server event.
+        return queued(`restore database ${args.database} from backup ${args.backup}`, 'forge_list_server_events');
+    },
+});

package/dist/tools/backups/shared.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { ToolInputError } from '../errors.js';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { serverPath } from '../servers/shared.js';
+import { storageProvidersPath } from '../storage/shared.js';
+export function backupConfigurationsPath(org, server) {
+    return `${serverPath(org, server)}/database/backups`;
+}
+export function backupConfigurationPath(org, server, configuration) {
+    return `${backupConfigurationsPath(org, server)}/${encodeURIComponent(String(configuration))}`;
+}
+export function backupsPath(org, server, configuration) {
+    return `${backupConfigurationPath(org, server, configuration)}/instances`;
+}
+export const backupConfigurationInput = idInput('Backup configuration ID. Use forge_list_backup_configurations to find it.');
+export const backupInput = idInput('Backup ID. Use forge_list_backups to find it.');
+export const BACKUP_CONFIGURATION_NOT_FOUND_HINT = 'Check the server ID with forge_list_servers and the backup configuration ID with forge_list_backup_configurations.';
+export const storageProviderRefInput = z
+    .union([z.number().int().nonnegative(), z.string().min(1)])
+    .describe('Storage provider (S3, Spaces, …) by ID or name. Use forge_list_storage_providers (storage toolset) to find it.');
+export const FREQUENCIES = ['hourly', 'daily', 'weekly', 'custom'];
+/** Backups start on the hour or half hour (server time). */
+export const BACKUP_TIMES = Array.from({ length: 48 }, (_, i) => `${String(Math.floor(i / 2)).padStart(2, '0')}:${i % 2 ? '30' : '00'}`);
+export const scheduleInput = {
+    frequency: z.enum(FREQUENCIES).describe('hourly, daily (at `time`), weekly (on `day` at `time`) or custom (`cron`).'),
+    day: z.number().int().min(0).max(6).optional().describe('Weekly backups only: day of the week, cron numbering (0 = Sunday … 6 = Saturday).'),
+    time: z.enum(BACKUP_TIMES).optional().describe('Daily and weekly backups only: time of day, on the hour or half hour, e.g. "03:30".'),
+    cron: z.string().min(1).optional().describe('Custom frequency only: cron expression, e.g. "0 */6 * * *".'),
+};
+/** Validates that schedule fields match the frequency and maps them to the request body. */
+export function scheduleBody({ frequency, day, time, cron }) {
+    if (frequency === 'custom' && cron === undefined)
+        throw new ToolInputError('A custom frequency needs a `cron` expression.');
+    if (frequency !== 'custom' && cron !== undefined)
+        throw new ToolInputError('`cron` is only used with frequency "custom".');
+    if (frequency !== 'weekly' && day !== undefined)
+        throw new ToolInputError('`day` is only used with frequency "weekly".');
+    if ((frequency === 'hourly' || frequency === 'custom') && time !== undefined) {
+        throw new ToolInputError('`time` is only used with frequency "daily" or "weekly".');
+    }
+    return { frequency, day: day === undefined ? undefined : String(day), time, cron };
+}
+const CONFIGURATION_FIELDS = [
+    'id',
+    'name',
+    'status',
+    'storage_provider_id',
+    'provider',
+    'bucket',
+    'directory',
+    'displayable_schedule',
+    'next_run_time',
+    'schedule',
+    'day_of_week',
+    'time',
+    'cron_schedule',
+    'database_ids',
+    'include_new_databases',
+    'retention',
+    'notify_email',
+];
+export const backupConfigurationOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    status: z.string().nullable().describe('e.g. installing, installed, removing.'),
+    storage_provider_id: z.number().nullable(),
+    provider: z.string().nullable(),
+    bucket: z.string().nullable(),
+    directory: z.string().nullable(),
+    displayable_schedule: z.string().nullable(),
+    next_run_time: z.string().nullable(),
+    schedule: z.string().nullable(),
+    day_of_week: z.number().nullable(),
+    time: z.string().nullable(),
+    cron_schedule: z.string().nullable(),
+    database_ids: z.array(z.unknown()).nullable(),
+    include_new_databases: z.boolean().nullable(),
+    retention: z.number().nullable().describe('Number of backups kept.'),
+    notify_email: z.string().nullable(),
+});
+export function formatBackupConfiguration(flat) {
+    return pick(flat, CONFIGURATION_FIELDS);
+}
+export function backupConfigurationPhase(status) {
+    return phaseOf(status, { pending: ['installing', 'updating', 'removing'], failed: ['failed'] });
+}
+export const backupOutput = z.looseObject({
+    id: z.string(),
+    status: z.string().nullable().describe('"finished" when the backup succeeded.'),
+    is_partial: z.unknown().nullable().describe('Whether some databases could not be backed up.'),
+    size: z.number().nullable().describe('Size in bytes.'),
+    finished_at: z.number().nullable().describe('Unix timestamp.'),
+});
+export function formatBackup(flat) {
+    return pick(flat, ['id', 'status', 'is_partial', 'size', 'finished_at']);
+}
+/** Only "finished" means the backup succeeded: any other value is still running. */
+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))
+        return Number(ref);
+    const response = await client.get(storageProvidersPath(org), { query: { page: { size: 100 } }, signal });
+    const match = flattenCollection(response.data).items.find((provider) => provider.name === ref);
+    if (!match) {
+        throw new ToolInputError(`Storage provider "${ref}" not found. Check the name with forge_list_storage_providers (storage toolset).`);
+    }
+    return Number(match.id);
+}