feat: scaffold safe staging guard plugin

Author: Septiyan Nariyanto

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '7.4'
+      - name: Run tests
+        run: php tests/run.php
+      - name: PHP syntax check
+        run: find . -path ./.git -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l
+      - name: Build release ZIP
+        run: bash scripts/build-release.sh

.gitignore

@@ -0,0 +1,2 @@
+dist/
+.DS_Store

README.md

@@ -0,0 +1,53 @@
+# Safe Staging Guard
+
+Prevent staging-site accidents with visible environment labels, noindex controls, and safe email handling.
+
+## Why
+
+Staging sites are useful, but they can accidentally:
+
+- get indexed by search engines,
+- send real emails to users,
+- look too similar to production,
+- confuse support and testing workflows.
+
+Safe Staging Guard adds a small safety layer for WordPress staging/local environments.
+
+## v0.1.0 features
+
+- Admin bar environment label.
+- Frontend staging banner for logged-in users.
+- Noindex/nofollow for local/staging environments.
+- Email block or redirect mode.
+- Production mode disables email interception and noindex.
+
+## Development
+
+Run tests:
+
+```bash
+php tests/run.php
+```
+
+Run PHP syntax checks:
+
+```bash
+find . -path ./.git -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l
+```
+
+Build release ZIP:
+
+```bash
+bash scripts/build-release.sh
+```
+
+## Safety notes
+
+- No tracking by default.
+- No external network calls.
+- No destructive operations.
+- Production mode keeps emails and robots behavior untouched.
+
+## License
+
+GPL-2.0-or-later.

docs/roadmap.md

@@ -0,0 +1,17 @@
+# Safe Staging Guard Roadmap
+
+## v0.1.0
+
+- Environment setting: Local / Staging / Production.
+- Admin bar label.
+- Frontend staging banner for logged-in users.
+- Noindex/nofollow for local/staging.
+- Email block/redirect/allow mode.
+
+## Later ideas
+
+- Payment gateway staging warnings.
+- Webhook safety checks.
+- WP-CLI status command.
+- Production-looking domain warning.
+- Exportable safety report.

readme.txt

@@ -0,0 +1,57 @@
+=== Safe Staging Guard ===
+Contributors: nariyanto
+Tags: staging, noindex, email, development, safety
+Requires at least: 6.0
+Tested up to: 7.0
+Requires PHP: 7.4
+Stable tag: 0.1.0
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+
+Prevent staging-site accidents with visible environment labels, noindex controls, and safe email handling.
+
+== Description ==
+
+Safe Staging Guard helps WordPress site owners and developers avoid common staging-site mistakes.
+
+Version 0.1.0 focuses on simple, review-friendly safety controls:
+
+* Admin bar environment label for administrators.
+* Optional frontend staging banner for logged-in users.
+* Noindex/nofollow robots control for local and staging environments.
+* Email safety mode to block or redirect outgoing staging emails.
+* Production mode automatically disables noindex and email interception.
+
+The plugin does not send data to external services and does not collect analytics.
+
+== Installation ==
+
+1. Upload the plugin folder to `/wp-content/plugins/`.
+2. Activate Safe Staging Guard from the Plugins screen.
+3. Open Settings > Safe Staging Guard.
+4. Select the environment and safety options.
+
+== Frequently Asked Questions ==
+
+= Does this plugin change production email delivery? =
+
+If Environment is set to Production, Safe Staging Guard does not block or redirect outgoing email.
+
+= Does this plugin send data externally? =
+
+No. Version 0.1.0 does not send data to external services and does not collect analytics.
+
+= Is this a replacement for a proper staging environment? =
+
+No. It is a helper layer for visibility and safety. You should still keep staging and production separate.
+
+== Screenshots ==
+
+1. Safe Staging Guard settings page.
+2. Admin bar environment label.
+3. Frontend staging banner.
+
+== Changelog ==
+
+= 0.1.0 =
+* Initial release with environment label, staging banner, noindex control, and email safety mode.

safe-staging-guard.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Plugin Name: Safe Staging Guard
+ * Plugin URI: https://github.com/nariyanto/wp-safe-staging-guard
+ * Description: Prevent staging-site accidents with visible environment labels, noindex controls, and safe email handling.
+ * Version: 0.1.0
+ * Requires at least: 6.0
+ * Requires PHP: 7.4
+ * Author: Septiyan Nariyanto
+ * Author URI: https://nariyanto.id
+ * License: GPL-2.0-or-later
+ * License URI: https://www.gnu.org/licenses/gpl-2.0.html
+ * Text Domain: safe-staging-guard
+ * Domain Path: /languages
+ */
+
+declare(strict_types=1);
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+require_once __DIR__ . '/src/EnvironmentSettings.php';
+require_once __DIR__ . '/src/EmailSafety.php';
+require_once __DIR__ . '/src/NoindexPolicy.php';
+require_once __DIR__ . '/src/Plugin.php';
+
+add_action('plugins_loaded', static function (): void {
+    $plugin = new \Nariyanto\SafeStagingGuard\Plugin();
+    $plugin->register();
+});

scripts/build-release.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DIST="$ROOT/dist"
+BUILD="$DIST/safe-staging-guard"
+ZIP="$DIST/safe-staging-guard.zip"
+rm -rf "$DIST"
+mkdir -p "$BUILD"
+rsync -a "$ROOT/" "$BUILD/" \
+  --exclude='.git' \
+  --exclude='.github' \
+  --exclude='dist' \
+  --exclude='tests' \
+  --exclude='docs' \
+  --exclude='scripts' \
+  --exclude='.gitignore'
+if command -v zip >/dev/null 2>&1; then
+  (cd "$DIST" && zip -qr "$ZIP" safe-staging-guard)
+else
+  python3 - <<'PY' "$DIST" "$ZIP"
+import os
+import sys
+import zipfile
+from pathlib import Path
+
+dist = Path(sys.argv[1])
+zip_path = Path(sys.argv[2])
+root = dist / 'safe-staging-guard'
+with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as archive:
+    for path in sorted(root.rglob('*')):
+        if path.is_file():
+            archive.write(path, path.relative_to(dist).as_posix())
+PY
+fi
+echo "$ZIP"

src/EmailSafety.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nariyanto\SafeStagingGuard;
+
+final class EmailSafety
+{
+    /**
+     * @param array<string, mixed> $args
+     * @return array<string, mixed>
+     */
+    public static function apply(array $args, EnvironmentSettings $settings): array
+    {
+        $args += [
+            'to' => [],
+            'subject' => '',
+            'message' => '',
+            'headers' => [],
+            'attachments' => [],
+        ];
+
+        if ($settings->isProduction() || $settings->emailMode() === 'allow') {
+            $args['blocked'] = false;
+            return $args;
+        }
+
+        $originalRecipients = self::recipientList($args['to']);
+
+        if ($settings->emailMode() === 'redirect' && $settings->redirectEmail() !== '') {
+            $args['to'] = [$settings->redirectEmail()];
+            $args['message'] = self::prependAuditNote((string)$args['message'], $originalRecipients, $settings);
+            $args['blocked'] = false;
+            return $args;
+        }
+
+        $args['to'] = [];
+        $args['subject'] = 'Safe Staging Guard blocked a staging email.';
+        $args['message'] = self::prependAuditNote('Email delivery was blocked by Safe Staging Guard.', $originalRecipients, $settings);
+        $args['headers'] = [];
+        $args['attachments'] = [];
+        $args['blocked'] = true;
+        return $args;
+    }
+
+    /** @param mixed $to */
+    private static function recipientList($to): string
+    {
+        if (is_array($to)) {
+            return implode(', ', array_map('strval', $to));
+        }
+        return (string)$to;
+    }
+
+    private static function prependAuditNote(string $message, string $originalRecipients, EnvironmentSettings $settings): string
+    {
+        $note = "Safe Staging Guard environment: " . $settings->environment() . "\n";
+        $note .= "Original recipients: " . ($originalRecipients !== '' ? $originalRecipients : '(none)') . "\n\n";
+        return $note . $message;
+    }
+}

src/EnvironmentSettings.php

@@ -0,0 +1,108 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nariyanto\SafeStagingGuard;
+
+final class EnvironmentSettings
+{
+    /** @var array<string, mixed> */
+    private array $values;
+
+    /** @param array<string, mixed> $values */
+    private function __construct(array $values)
+    {
+        $this->values = $values;
+    }
+
+    /** @param array<string, mixed> $raw */
+    public static function fromArray(array $raw): self
+    {
+        $environment = self::choice((string)($raw['environment'] ?? 'staging'), ['local', 'staging', 'production'], 'staging');
+        $emailMode = self::choice((string)($raw['email_mode'] ?? 'block'), ['block', 'redirect', 'allow'], 'block');
+        $redirectEmail = strtolower(trim((string)($raw['redirect_email'] ?? '')));
+        if (!filter_var($redirectEmail, FILTER_VALIDATE_EMAIL)) {
+            $redirectEmail = '';
+        }
+
+        $noindex = self::boolValue($raw['noindex_enabled'] ?? true);
+        if ($environment === 'production') {
+            $noindex = false;
+        }
+
+        return new self([
+            'environment' => $environment,
+            'show_admin_bar_label' => self::boolValue($raw['show_admin_bar_label'] ?? true),
+            'show_frontend_banner' => self::boolValue($raw['show_frontend_banner'] ?? true),
+            'noindex_enabled' => $noindex,
+            'email_mode' => $emailMode,
+            'redirect_email' => $redirectEmail,
+        ]);
+    }
+
+    public static function defaults(): self
+    {
+        return self::fromArray([]);
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return $this->values;
+    }
+
+    public function environment(): string
+    {
+        return (string)$this->values['environment'];
+    }
+
+    public function showAdminBarLabel(): bool
+    {
+        return (bool)$this->values['show_admin_bar_label'];
+    }
+
+    public function showFrontendBanner(): bool
+    {
+        return (bool)$this->values['show_frontend_banner'];
+    }
+
+    public function noindexEnabled(): bool
+    {
+        return (bool)$this->values['noindex_enabled'];
+    }
+
+    public function emailMode(): string
+    {
+        return (string)$this->values['email_mode'];
+    }
+
+    public function redirectEmail(): string
+    {
+        return (string)$this->values['redirect_email'];
+    }
+
+    public function isProduction(): bool
+    {
+        return $this->environment() === 'production';
+    }
+
+    /** @param array<int, string> $allowed */
+    private static function choice(string $value, array $allowed, string $default): string
+    {
+        $value = strtolower(trim($value));
+        return in_array($value, $allowed, true) ? $value : $default;
+    }
+
+    /** @param mixed $value */
+    private static function boolValue($value): bool
+    {
+        if (is_bool($value)) {
+            return $value;
+        }
+        if (is_numeric($value)) {
+            return (int)$value === 1;
+        }
+        $normalized = strtolower(trim((string)$value));
+        return in_array($normalized, ['1', 'true', 'yes', 'on'], true);
+    }
+}