@wpmoo/toolkit 0.9.25 → 0.9.27

package/README.md

@@ -170,12 +170,31 @@ npx @wpmoo/toolkit doctor --json --postgres
 ```
 
 JSON output is optional; human-readable output remains the default.
-`doctor --postgres` adds read-only PostgreSQL health and performance diagnostics
-such as database size, sessions currently running queries with
-`pg_stat_activity.state = 'active'`, connection utilization against
-`max_connections`, slow-query readiness, extension visibility, and settings.
+`doctor --postgres` runs read-only PostgreSQL diagnostics as advisory checks only; it
+does not perform automatic tuning.
+Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics
+instead of being treated as successful checks.
+
+Current advisory checks include:
+
+- sessions currently running queries where `pg_stat_activity.state = 'active'`;
+- connection utilization against `max_connections`;
+- long transaction / idle-in-transaction warnings from `pg_stat_activity`;
+- table health visibility (for example table and index bloat signals, index scan
+  efficiency, and vacuum-related blockers);
+- optional unused index advisory output when index usage data is available;
+- WAL and capacity visibility including WAL activity and disk-level pressure context;
+- slow-query and query-plan readiness checks for common `log_min_duration_statement`
+  and `pg_stat_statements` prerequisites.
+
+`npx @wpmoo/toolkit doctor --postgres` and
+`npx @wpmoo/toolkit doctor --json --postgres` use the same checks, and the
+JSON variant exposes a versioned PostgreSQL diagnostics contract.
+
 `doctor --json --postgres` includes a structured `postgres` object for automation.
-Incomplete or malformed PostgreSQL metric rows are reported as unavailable diagnostics.
+`doctor --json --postgres` keeps the JSON contract stable by versioning the
+`postgres` payload; individual fields are optional so automation can safely handle
+environments where PostgreSQL does not expose a metric.
 
 ## Release Artifacts
 

package/dist/audit-log.js

@@ -0,0 +1,78 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const secretFlagNames = new Set([
+    'password',
+    'api-key',
+    'token',
+    'secret',
+    'api_key',
+]);
+function isSecretFlagToken(token) {
+    return token === '--password'
+        ? '--password'
+        : token === '--api-key'
+            ? '--api-key'
+            : token === '--token'
+                ? '--token'
+                : token === '--secret'
+                    ? '--secret'
+                    : undefined;
+}
+function isSecretKVToken(token) {
+    const firstEquals = token.indexOf('=');
+    if (firstEquals < 0) {
+        return undefined;
+    }
+    const [name] = [token.slice(0, firstEquals), token.slice(firstEquals + 1)];
+    return secretFlagNames.has(name.replace(/^--+/, '').toLowerCase()) ? name : undefined;
+}
+function normalizeFlag(flag) {
+    return flag.startsWith('--') ? flag : `--${flag}`;
+}
+/**
+ * Redacts values for common secret-like arguments.
+ */
+export function sanitizeCommandArgs(args) {
+    const sanitized = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const secretKV = isSecretKVToken(arg);
+        if (secretKV) {
+            sanitized.push(`${secretKV}=***`);
+            continue;
+        }
+        const secretFlag = isSecretFlagToken(arg);
+        if (secretFlag && index + 1 < args.length && !args[index + 1].startsWith('--')) {
+            sanitized.push(arg);
+            sanitized.push('***');
+            index += 1;
+            continue;
+        }
+        sanitized.push(arg);
+    }
+    return sanitized;
+}
+export function extractApprovedFlags(args, approvedFlagNames) {
+    const present = [];
+    const argsByIndex = args.map((arg) => arg.toLowerCase());
+    approvedFlagNames.forEach((name) => {
+        const normalized = normalizeFlag(name).toLowerCase();
+        if (argsByIndex.some((arg) => arg === normalized || arg.startsWith(`${normalized}=`))) {
+            present.push(name);
+        }
+    });
+    return present;
+}
+export async function appendAuditLog(options) {
+    const logPath = join(options.environmentPath, '.wpmoo', 'audit.log');
+    const event = {
+        timestamp: (options.timestamp ?? new Date()).toISOString(),
+        command: options.command,
+        environment: options.environment,
+        dryRun: options.dryRun,
+        approvedFlags: [...(options.approvedFlags ?? extractApprovedFlags(options.args, options.approvedFlagNames))],
+        args: sanitizeCommandArgs(options.args),
+    };
+    await mkdir(dirname(logPath), { recursive: true });
+    await appendFile(logPath, `${JSON.stringify(event)}\n`, 'utf8');
+}

package/dist/daily-actions.js

@@ -1,9 +1,12 @@
 import { spawn } from 'node:child_process';
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { appendAuditLog } from './audit-log.js';
 import { readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
-import { normalizeDatabaseName } from './databases.js';
+import { defaultDatabaseSnapshotMaxAgeMs, findDatabaseSnapshots, normalizeDatabaseName } from './databases.js';
+import { evaluateDailyActionPolicy, } from './environment-policy.js';
 import { markerPath } from './environment.js';
+import { scanMigrationRisks } from './migrations.js';
 export const dailyActionCommands = [
     'start',
     'stop',
@@ -185,68 +188,6 @@ function scriptArgs(command, argv) {
         return ensureNoArgs(command, argv);
     return validateDatabaseArg(positionalArgs(command, argv, 1, 3), 1);
 }
-function isDestructiveCommand(command, args) {
-    if (command === 'resetdb')
-        return true;
-    return command === 'restore-snapshot' && args[0] !== '--dry-run';
-}
-function isProductionLifecycleCommand(command) {
-    return command === 'install' || command === 'update' || command === 'test';
-}
-function isStageLifecycleCommand(command) {
-    return command === 'install' || command === 'update';
-}
-function destructiveCommandError(command, envName) {
-    return `Refusing destructive command '${command}' in WPMOO_ENV=${envName}. Set WPMOO_ALLOW_DESTRUCTIVE=1 to run it intentionally.`;
-}
-function stageLifecycleCommandError(command) {
-    return `Refusing stage lifecycle command '${command}' in WPMOO_ENV=stage. Set WPMOO_ALLOW_STAGE_LIFECYCLE=1 to run it intentionally.`;
-}
-function productionLifecycleCommandError(command) {
-    return `Refusing production lifecycle command '${command}' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally.`;
-}
-async function assertDestructiveCommandAllowed(command, args, cwd) {
-    if (!isDestructiveCommand(command, args)) {
-        return;
-    }
-    const env = await readEnvFile(cwd);
-    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
-    if (envName !== 'stage' && envName !== 'prod') {
-        return;
-    }
-    const allowDestructive = process.env.WPMOO_ALLOW_DESTRUCTIVE?.trim() || env?.get('WPMOO_ALLOW_DESTRUCTIVE')?.trim();
-    if (allowDestructive !== '1') {
-        throw new Error(destructiveCommandError(command, envName));
-    }
-}
-async function assertProductionLifecycleCommandAllowed(command, cwd) {
-    if (!isProductionLifecycleCommand(command)) {
-        return;
-    }
-    const env = await readEnvFile(cwd);
-    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
-    if (envName !== 'prod') {
-        return;
-    }
-    const allowProdLifecycle = process.env.WPMOO_ALLOW_PROD_LIFECYCLE?.trim() || env?.get('WPMOO_ALLOW_PROD_LIFECYCLE')?.trim();
-    if (allowProdLifecycle !== '1') {
-        throw new Error(productionLifecycleCommandError(command));
-    }
-}
-async function assertStageLifecycleCommandAllowed(command, cwd) {
-    if (!isStageLifecycleCommand(command)) {
-        return;
-    }
-    const env = await readEnvFile(cwd);
-    const envName = process.env.WPMOO_ENV?.trim() || selectedComposeEnvironment(env);
-    if (envName !== 'stage') {
-        return;
-    }
-    const allowStageLifecycle = process.env.WPMOO_ALLOW_STAGE_LIFECYCLE?.trim() || env?.get('WPMOO_ALLOW_STAGE_LIFECYCLE')?.trim();
-    if (allowStageLifecycle !== '1') {
-        throw new Error(stageLifecycleCommandError(command));
-    }
-}
 async function assertEnvironmentRoot(cwd) {
     try {
         await access(join(cwd, markerPath));
@@ -265,17 +206,121 @@ async function assertScriptExists(cwd, script) {
     }
     return scriptPath;
 }
-export async function dailyActionPlan(command, argv, cwd = process.cwd()) {
+function envValue(env, key) {
+    return process.env[key]?.trim() || env?.get(key)?.trim();
+}
+function flagEnabled(env, key) {
+    return envValue(env, key) === '1';
+}
+function approvedFlags(env) {
+    return [
+        'WPMOO_ALLOW_DESTRUCTIVE',
+        'WPMOO_ALLOW_STAGE_LIFECYCLE',
+        'WPMOO_ALLOW_PROD_LIFECYCLE',
+        'WPMOO_ALLOW_NO_RECENT_SNAPSHOT',
+        'WPMOO_ALLOW_MIGRATIONS',
+    ].filter((key) => flagEnabled(env, key));
+}
+function requiresMigrationApproval(command) {
+    return command === 'install' || command === 'update' || command === 'test';
+}
+function noRecentSnapshotMessage(command, environment) {
+    return `Refusing destructive command '${command}' in WPMOO_ENV=${environment} without a recent database snapshot. Create a snapshot first or set WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1 to run it intentionally.`;
+}
+function migrationRiskMessage(command, environment) {
+    return `Refusing migration-risk command '${command}' in WPMOO_ENV=${environment}. Review detected migration scripts or set WPMOO_ALLOW_MIGRATIONS=1 to run it intentionally.`;
+}
+async function auditDailyActionPreview(preview) {
+    if (preview.environment !== 'prod' || !preview.auditWorthy) {
+        return;
+    }
+    await appendAuditLog({
+        environmentPath: preview.cwd,
+        command: preview.command,
+        environment: preview.environment,
+        dryRun: preview.dryRun,
+        args: preview.args,
+        approvedFlagNames: [],
+        approvedFlags: preview.approvedFlags,
+    });
+}
+export async function dailyActionSafetyPreview(command, argv, cwd = process.cwd()) {
     await assertEnvironmentRoot(cwd);
     const scriptPath = await assertScriptExists(cwd, dailyActionScripts[command]);
     const args = scriptArgs(command, argv);
-    await assertStageLifecycleCommandAllowed(command, cwd);
-    await assertProductionLifecycleCommandAllowed(command, cwd);
-    await assertDestructiveCommandAllowed(command, args, cwd);
+    const env = await readEnvFile(cwd);
+    const envName = envValue(env, 'WPMOO_ENV') || selectedComposeEnvironment(env);
+    const policy = evaluateDailyActionPolicy(command, args, {
+        envName,
+        allowDestructive: envValue(env, 'WPMOO_ALLOW_DESTRUCTIVE'),
+        allowStageLifecycle: envValue(env, 'WPMOO_ALLOW_STAGE_LIFECYCLE'),
+        allowProdLifecycle: envValue(env, 'WPMOO_ALLOW_PROD_LIFECYCLE'),
+    });
+    const warnings = [];
+    const snapshotRequired = policy.isDestructive && (policy.env === 'stage' || policy.env === 'prod');
+    const snapshot = snapshotRequired ? findDatabaseSnapshots(cwd) : undefined;
+    const noRecentSnapshot = snapshotRequired &&
+        snapshot &&
+        (snapshot.newestSnapshotAgeMs === null || snapshot.newestSnapshotAgeMs > defaultDatabaseSnapshotMaxAgeMs) &&
+        !flagEnabled(env, 'WPMOO_ALLOW_NO_RECENT_SNAPSHOT');
+    if (noRecentSnapshot) {
+        warnings.push({
+            kind: 'no-recent-snapshot',
+            requiredFlag: 'WPMOO_ALLOW_NO_RECENT_SNAPSHOT',
+            blocking: true,
+            message: noRecentSnapshotMessage(command, policy.env),
+        });
+    }
+    const migrations = requiresMigrationApproval(command) && (policy.env === 'stage' || policy.env === 'prod')
+        ? await scanMigrationRisks(cwd)
+        : undefined;
+    if (migrations?.risk && !flagEnabled(env, 'WPMOO_ALLOW_MIGRATIONS')) {
+        warnings.push({
+            kind: 'migration-risk',
+            requiredFlag: 'WPMOO_ALLOW_MIGRATIONS',
+            blocking: true,
+            message: migrationRiskMessage(command, policy.env),
+        });
+    }
     return {
         cwd,
         scriptPath,
         args,
+        command,
+        environment: policy.env,
+        dryRun: policy.isDryRunPreview,
+        destructive: policy.isDestructive,
+        auditWorthy: policy.isAuditWorthy,
+        allowed: policy.allowed,
+        deny: policy.allowed ? undefined : { ...policy.deny, message: policy.message },
+        refusalMessage: policy.allowed ? undefined : policy.message,
+        requiredFlag: policy.allowed ? undefined : policy.deny.requiredFlag,
+        warnings,
+        snapshot: snapshot
+            ? {
+                requiredRecent: true,
+                newestSnapshotAgeMs: snapshot.newestSnapshotAgeMs,
+                snapshotPaths: snapshot.snapshotPaths,
+            }
+            : undefined,
+        migrations,
+        approvedFlags: approvedFlags(env),
+    };
+}
+export async function dailyActionPlan(command, argv, cwd = process.cwd()) {
+    const preview = await dailyActionSafetyPreview(command, argv, cwd);
+    await auditDailyActionPreview(preview);
+    if (!preview.allowed) {
+        throw new Error(preview.refusalMessage);
+    }
+    const blockingWarning = preview.warnings.find((warning) => warning.blocking);
+    if (blockingWarning) {
+        throw new Error(blockingWarning.message);
+    }
+    return {
+        cwd: preview.cwd,
+        scriptPath: preview.scriptPath,
+        args: preview.args,
     };
 }
 async function spawnDailyAction(plan) {

package/dist/databases.js

@@ -1,4 +1,13 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { spawn } from 'node:child_process';
+export const defaultDatabaseSnapshotMaxAgeMs = 24 * 60 * 60 * 1000;
+export const databaseSnapshotDirectoryNames = ['backups', 'backup', 'snapshots'];
+export const databaseSnapshotExtensions = ['.dump', '.sql', '.sql.gz', '.zip', '.tar', '.tar.gz'];
+function isDatabaseSnapshotFile(fileName, extensions) {
+    const normalized = fileName.toLowerCase();
+    return extensions.some((extension) => normalized.endsWith(extension));
+}
 const maintenanceDatabases = new Set(['postgres']);
 const databaseNamePattern = /^[A-Za-z0-9_.-]+$/u;
 export function isValidDatabaseName(value) {
@@ -46,6 +55,54 @@ export function parseDatabaseListOutput(output, options = {}) {
     }
     return databases;
 }
+export function findDatabaseSnapshots(targetDirectory, options = {}) {
+    const { nowMs = Date.now(), snapshotDirectories = [...databaseSnapshotDirectoryNames], snapshotExtensions = [...databaseSnapshotExtensions], } = options;
+    const snapshots = [];
+    for (const directoryName of snapshotDirectories) {
+        const directory = join(targetDirectory, directoryName);
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!isDatabaseSnapshotFile(entry.name, snapshotExtensions)) {
+                continue;
+            }
+            const path = join(directory, entry.name);
+            let stats;
+            try {
+                stats = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            if (!stats.isFile()) {
+                continue;
+            }
+            const mtimeMs = stats.mtimeMs;
+            const ageMs = Math.max(0, nowMs - mtimeMs);
+            snapshots.push({ path, mtimeMs, ageMs });
+        }
+    }
+    snapshots.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
+    const newestSnapshot = snapshots[0] ?? null;
+    return {
+        snapshots,
+        snapshotPaths: snapshots.map((snapshot) => snapshot.path),
+        newestSnapshotAgeMs: newestSnapshot ? newestSnapshot.ageMs : null,
+    };
+}
+export function hasRecentDatabaseSnapshot(targetDirectory, options = {}) {
+    const { maxAgeMs = defaultDatabaseSnapshotMaxAgeMs, ...scanOptions } = options;
+    const result = findDatabaseSnapshots(targetDirectory, scanOptions);
+    return result.newestSnapshotAgeMs !== null && result.newestSnapshotAgeMs <= maxAgeMs;
+}
 export function normalizeDatabaseListResult(result) {
     if (Array.isArray(result)) {
         return { ok: true, databases: result };