CresignSys Learn

CresignSys Learn — Lesson 084

Written by

cresignsys

in

Build the CHP Repair-Plan Engine

We now have:

hosting-db-import
hosting-reconcile
hosting-health
hosting-site-status

The next layer is the write-control system.

The first rule is:

Detection must never directly cause a server modification.

Instead:

DRIFT
  ↓
ANALYZE
  ↓
REPAIR PLAN
  ↓
VALIDATE
  ↓
APPROVE
  ↓
APPLY
  ↓
VERIFY

1. New Command

Create:

sudo nano /usr/local/bin/hosting-repair-plan

Usage:

sudo hosting-repair-plan example.com

Optional:

sudo hosting-repair-plan example.com --json
sudo hosting-repair-plan example.com --verbose

This command must be read-only.

2. Why a Repair Plan?

Suppose reconciliation reports:

PHP:
DRIFT

Expected:
8.3

Actual:
8.2

Do not immediately execute:

systemctl restart php8.3-fpm

There could be several explanations.

Instead generate:

Repair Plan
-----------
Problem:
PHP version drift

Expected:
8.3

Actual:
8.2

Possible action:
Change site PHP-FPM target from 8.2 to 8.3

3. Repair Architecture

                 RECONCILIATION
                       │
                       ▼
                     DRIFT
                       │
                       ▼
               REPAIR ANALYZER
                       │
             ┌─────────┼─────────┐
             ▼         ▼         ▼
           PHP       Nginx      SSL
             │         │         │
             └─────────┼─────────┘
                       ▼
                 REPAIR PLAN
                       │
                       ▼
                  VALIDATION
                       │
                       ▼
                   APPROVAL
                       │
                       ▼
                    APPLY
                       │
                       ▼
                  VERIFICATION

4. Repair Plan Is Not Repair

These are separate commands:

hosting-repair-plan
        ↓
READ ONLY

and later:

hosting-repair
        ↓
WRITE

This separation should remain permanent.

5. Repair Plan Structure

Every repair plan should contain:

PLAN ID
SITE
PROBLEM
CURRENT STATE
EXPECTED STATE
PROPOSED ACTION
FILES AFFECTED
SERVICES AFFECTED
RISK
BACKUP REQUIREMENT
ROLLBACK METHOD
VALIDATION

6. Example

CresignSys Repair Plan
======================

Plan:
RP-000021

Site:
example.com

Problem:
PHP version drift

Current:
PHP 8.2

Expected:
PHP 8.3

Proposed Action:
Change PHP-FPM target to 8.3

Files:
1 Nginx configuration

Services:
Nginx

Backup:
Required

Rollback:
Restore previous Nginx configuration

Risk:
MEDIUM

Validation:
nginx -t
HTTP health check
PHP-FPM check

No changes made.

7. Repair Plan Database

Create a new table:

CREATE TABLE repair_plans (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    site_id INTEGER NOT NULL,
    plan_code TEXT NOT NULL UNIQUE,
    repair_type TEXT NOT NULL,
    status TEXT NOT NULL,
    risk_level TEXT NOT NULL,
    description TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,

    FOREIGN KEY (site_id)
        REFERENCES sites(id)
        ON DELETE CASCADE
);

8. Plan Status

Use:

DRAFT
VALID
APPROVED
APPLYING
APPLIED
FAILED
CANCELLED
EXPIRED

Initial state:

DRAFT

After validation:

VALID

Only explicit approval moves it to:

APPROVED

9. Repair Type

Examples:

PHP_VERSION
NGINX_CONFIGURATION
SSL
DNS
PERMISSIONS
WORDPRESS
DATABASE
STORAGE
SERVICE

For example:

repair_type=PHP_VERSION

10. Risk Levels

Start with:

LOW
MEDIUM
HIGH
CRITICAL

Example:

PHP configuration:
MEDIUM

File ownership:
MEDIUM

SSL renewal:
LOW/MEDIUM

DNS:
HIGH

Database repair:
HIGH

WordPress database modification:
HIGH

The exact risk policy should be configurable later.

11. Never Automatically Repair HIGH-Risk Operations

For the first version:

LOW:
possible automatic execution later

MEDIUM:
explicit approval

HIGH:
explicit approval + stronger validation

CRITICAL:
manual operator intervention

Do not implement automatic critical repairs.

12. Repair Plan Items

A plan can contain multiple actions.

Create:

CREATE TABLE repair_plan_items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    plan_id INTEGER NOT NULL,
    sequence_no INTEGER NOT NULL,
    action_type TEXT NOT NULL,
    target TEXT,
    old_value TEXT,
    new_value TEXT,
    risk_level TEXT NOT NULL,
    status TEXT NOT NULL,
    FOREIGN KEY (plan_id)
        REFERENCES repair_plans(id)
        ON DELETE CASCADE
);

13. Example Plan

PLAN RP-000021

Item 1
------
Action:
BACKUP_CONFIG

Target:
/etc/nginx/sites-enabled/example.com.conf

Item 2
------
Action:
UPDATE_NGINX_PHP_TARGET

Old:
php8.2-fpm.sock

New:
php8.3-fpm.sock

Item 3
------
Action:
NGINX_CONFIG_TEST

Item 4
------
Action:
NGINX_RELOAD

Item 5
------
Action:
HEALTH_CHECK

14. Why Sequence Numbers?

Repairs must happen in a controlled order.

Bad:

reload Nginx
 ↓
create backup

Correct:

backup
 ↓
modify
 ↓
validate
 ↓
reload
 ↓
verify

Therefore:

sequence_no

is important.

15. Action Types

Define a controlled vocabulary.

For example:

BACKUP_FILE
WRITE_FILE
REPLACE_TEXT
CREATE_DIRECTORY
SET_OWNER
SET_PERMISSION
RELOAD_NGINX
RESTART_SERVICE
RUN_HEALTH_CHECK
VERIFY

Do not allow arbitrary shell commands inside a repair plan.

16. Never Store Arbitrary Shell Commands

Avoid:

command:
rm -rf /something

inside the database.

Instead use structured actions:

action_type:
BACKUP_FILE

target:
/etc/nginx/sites-enabled/example.com.conf

The repair engine decides what that action means.

This prevents the repair database from becoming an arbitrary command-execution system.

17. PHP Repair Example

Suppose:

Expected:
8.3

Actual:
8.2

The analyzer checks:

php8.3-fpm installed?
php8.3-fpm running?
socket exists?
Nginx configuration?

Only if the required components exist should it propose:

UPDATE_NGINX_PHP_TARGET

18. Don’t Install Missing PHP Automatically

Suppose:

Expected:
8.3

Actual:
8.2

php8.3-fpm:
NOT INSTALLED

Do not generate:

apt install php8.3-fpm

as an automatic repair.

Instead:

Repair:
BLOCKED

Reason:
Required PHP-FPM version is not installed.

Manual prerequisite:
Install and configure PHP 8.3-FPM.

19. Repair Prerequisites

A repair plan should distinguish:

READY

from:

BLOCKED

Example:

PHP 8.3-FPM:
AVAILABLE

PHP socket:
AVAILABLE

Nginx:
VALID

Repair:
READY

20. Example Blocked Plan

Repair Plan
===========

Problem:
PHP version drift

Expected:
8.3

Actual:
8.2

PHP 8.3-FPM:
NOT AVAILABLE

Status:
BLOCKED

No changes proposed.

This is much safer.

21. Nginx Repair

Suppose:

Expected:
php8.3-fpm.sock

Actual:
php8.2-fpm.sock

The plan can identify:

/etc/nginx/sites-enabled/example.com.conf

as the affected file.

22. Backup Before Modification

The plan must include:

BACKUP_FILE

before:

WRITE_FILE

Example:

1. Backup configuration
2. Modify configuration
3. nginx -t
4. Reload nginx
5. Health check

23. Backup Location

Use your CHP backup/configuration area.

For example:

/var/lib/cresignsys/repair-backups/

Structure:

/var/lib/cresignsys/repair-backups/
└── example.com/
    └── RP-000021/
        └── nginx-example.com.conf

24. Never Overwrite the Previous Repair Backup

Each plan gets a unique directory:

RP-000021
RP-000022
RP-000023

This makes rollback traceable.

25. File Hash

Before modification, record:

SHA-256

of the original file.

For example:

old_sha256:
abc123...

After modification:

new_sha256:
def456...

This provides verification.

26. Prevent Stale Repair Plans

This is very important.

Suppose the plan was created at:

16:00

and actual configuration changes manually at:

16:30

The plan may now be outdated.

Therefore before applying a plan:

RECONCILE AGAIN

27. Apply Preconditions

Before applying:

Plan created:
PHP 8.2 → 8.3

Current:
PHP 8.2 → 8.3

Good.

If current state is now:

PHP 8.4

then:

PLAN STALE

and application must stop.

28. Plan Fingerprint

Store a fingerprint of important state.

For example:

expected_hash

based on:

web root
PHP target
Nginx configuration hash
SSL state

Before application:

current fingerprint == plan fingerprint?

If not:

STALE

29. Repair Plan Expiration

Plans should eventually expire.

For example:

created:
16:00

expires:
18:00

If an old plan is used:

Plan:
EXPIRED

Generate a fresh plan.

30. Why This Matters

Without stale-plan detection:

Operator A:
creates plan

Operator B:
changes server

Operator A:
applies old plan

The old plan could overwrite the newer change.

CHP must prevent this.

31. Validation Before Approval

Run:

hosting-repair-plan
        ↓
validate prerequisites
        ↓
VALID

Example:

PHP 8.3-FPM installed       YES
PHP 8.3 socket available    YES
Nginx config found          YES
Backup location writable    YES
Site currently reachable    YES

Then:

Plan:
VALID

32. Approval

Eventually:

sudo hosting-repair-approve RP-000021

This changes:

VALID

to:

APPROVED

But don’t implement approval yet.

First make sure the plan generation works correctly.

33. Human-Readable Plan

The first version should output:

CresignSys Repair Plan
======================

Plan ID:
RP-000021

Site:
example.com

Risk:
MEDIUM

Status:
VALID

Problem:
PHP-FPM configuration drift

Current:
8.2

Expected:
8.3

Actions:

1. Backup Nginx configuration
2. Change PHP-FPM socket
3. Validate Nginx configuration
4. Reload Nginx
5. Run site health check

Rollback:
Restore previous Nginx configuration

No changes have been made.

34. JSON Plan

sudo hosting-repair-plan example.com --json

Example:

{
  "plan_id": "RP-000021",
  "site": "example.com",
  "status": "VALID",
  "risk": "MEDIUM",
  "problem": "PHP_VERSION_DRIFT",
  "actions": [
    {
      "sequence": 1,
      "type": "BACKUP_FILE"
    },
    {
      "sequence": 2,
      "type": "UPDATE_NGINX_PHP_TARGET"
    },
    {
      "sequence": 3,
      "type": "NGINX_CONFIG_TEST"
    },
    {
      "sequence": 4,
      "type": "RELOAD_NGINX"
    },
    {
      "sequence": 5,
      "type": "HEALTH_CHECK"
    }
  ]
}

35. Repair Plan for SSL

Suppose:

SSL:
EXPIRING

A future plan might be:

Problem:
CERTIFICATE_EXPIRING

Proposed action:
Renew certificate

Prerequisites:
DNS valid
Port 80/443 accessible
ACME configuration available

Risk:
MEDIUM

Don’t implement certificate renewal yet.

SSL renewal deserves its own carefully tested subsystem.

36. Repair Plan for Ownership

Suppose:

Expected:
www-data:www-data

Actual:
root:root

The plan might be:

Action:
SET_OWNER

Old:
root:root

New:
www-data:www-data

But this should be considered MEDIUM/HIGH risk because recursively changing ownership can break applications.

37. Never Recursively Change Ownership by Default

Avoid automatically proposing:

chown -R www-data:www-data /

or even:

chown -R www-data:www-data /storage/websites/example.com

without analyzing:

uploads
cache
application files
shared directories
symlinks
runtime directories

The repair engine must have precise targets.

38. Symlink Safety

Before modifying a file:

readlink

should be used to determine whether the target is a symlink.

A repair engine must not blindly follow a symlink and modify an unexpected file.

This is especially important for:

Nginx configuration
WordPress uploads
certificate files
site directories

39. Path Validation

Before any future write:

target path

must be validated against an allowed directory.

For example:

Allowed:
 /etc/nginx/sites-enabled/
 /storage/websites/example.com/
 /var/lib/cresignsys/

Reject:

/etc/passwd
/etc/shadow
/home/other-user/

unless explicitly supported by the operation.

40. Never Trust Database Paths Blindly

Even if the database contains:

web_root=/storage/websites/example.com/public

the repair engine should validate it before writing.

Database data is input.

Always verify:

path exists
path is expected
path is inside allowed root

41. Repair Plan Validation Layers

Use:

Layer 1
Syntax validation

Layer 2
Path validation

Layer 3
Prerequisite validation

Layer 4
Risk validation

Layer 5
State/fingerprint validation

Layer 6
Backup validation

Only then:

VALID

42. Repair Plan State Machine

DRAFT
  │
  ▼
VALIDATING
  │
  ├── failure ──→ BLOCKED
  │
  ▼
VALID
  │
  ▼
APPROVED
  │
  ▼
APPLYING
  │
  ├── failure ──→ FAILED
  │
  ▼
APPLIED
  │
  ▼
VERIFIED

A later rollback can transition:

APPLIED
   ↓
ROLLING_BACK
   ↓
ROLLED_BACK

43. VERIFIED Is Important

Don’t consider:

APPLIED

equal to:

WORKING

Example:

Nginx configuration changed

successfully, but then:

HTTP 502

occurs.

Therefore:

APPLIED

must be followed by:

VERIFY

44. Apply Loop

The eventual repair engine should execute:

Pre-check
   ↓
Backup
   ↓
Action 1
   ↓
Action 2
   ↓
Validation
   ↓
Reload/restart if required
   ↓
Health check
   ↓
Reconcile
   ↓
Verified

45. Failure Handling

Suppose:

Backup:
SUCCESS

Modify Nginx:
SUCCESS

nginx -t:
FAIL

Do not reload Nginx.

Instead:

ROLLBACK

to the previous configuration.

46. Transaction-Like Repair

Unlike SQLite transactions, server changes cannot always be rolled back automatically.

Therefore CHP needs:

BACKUP
+
VALIDATION
+
ROLLBACK

to approximate transactional behavior.

47. Repair Journal

Every action should be recorded:

repair_plan_items

sequence | action | status
---------|--------|--------
1        | backup | SUCCESS
2        | write  | SUCCESS
3        | test   | FAILED
4        | reload | SKIPPED
5        | rollback | SUCCESS

This creates a complete repair journal.

48. Never Hide Skipped Actions

If Nginx validation fails:

Reload:
SKIPPED

not:

Reload:
SUCCESS

This is important for auditing.

49. Example Failed Repair

Repair RP-000021
================

1. Backup configuration
   SUCCESS

2. Modify configuration
   SUCCESS

3. nginx -t
   FAILED

4. Reload nginx
   SKIPPED

5. Rollback
   SUCCESS

Final:
ROLLED_BACK

50. Repair Operation

Record:

operation:
REPAIR

with:

plan_id:
RP-000021

status:
FAILED

result:
ROLLED_BACK

The operator can then see exactly what happened.

51. Audit Trail

The system should eventually answer:

Who approved this repair?
When?
What changed?
Which files changed?
What was the old value?
What was the new value?
Did validation pass?
Was rollback required?

This becomes critical when managing multiple customer websites.

52. Operator Identity

For the initial local CLI:

operator:
root

But don’t assume root is a useful long-term identity.

The future web control panel should have authenticated users.

Then:

operator_id

can be stored with:

repair_plan
operation
approval

53. Approval History

Eventually:

repair_approvals

id
plan_id
operator_id
approved_at
decision
comment

Example:

RP-000021
Approved by:
admin

Decision:
APPROVED

Time:
2026-08-13 16:25

54. Repair Plan CLI

The eventual command family:

hosting-repair-plan
hosting-repair-validate
hosting-repair-approve
hosting-repair
hosting-repair-rollback

But don’t implement all five now.

Lesson 084 only builds:

hosting-repair-plan

55. First Repair Types

Start with only one:

PHP_VERSION

Why?

Because it exercises:

drift detection
prerequisites
file backup
configuration modification
syntax validation
service reload
health verification
rollback

It is a good architecture test.

56. But Don’t Apply It Yet

Even though we are designing PHP repair, Lesson 084 remains:

PLAN ONLY

No:

sed -i
systemctl reload
systemctl restart

inside the plan-generation command.

57. PHP Plan Analyzer

Create:

sudo nano /etc/cresignsys/lib/repair-plan.sh

Add:

analyze_php_drift
create_php_repair_plan
validate_php_prerequisites

58. Analyze Drift

The analyzer should first run reconciliation.

If:

PHP:
MATCH

then:

No repair plan required.

If:

PHP:
DRIFT

continue.

59. Determine Current Configuration

Discover:

current PHP-FPM socket

For example:

/run/php/php8.2-fpm.sock

Expected:

/run/php/php8.3-fpm.sock

60. Verify Target Exists

Check:

test -S /run/php/php8.3-fpm.sock

If true:

Target:
AVAILABLE

If false:

Target:
UNAVAILABLE

Then plan:

BLOCKED

61. Verify Service

Check:

systemctl is-active php8.3-fpm

If active:

PHP 8.3-FPM:
READY

If not:

BLOCKED

62. Verify Nginx File

Determine:

/etc/nginx/sites-enabled/example.com.conf

Check:

test -f "$NGINX_CONFIG"

Then:

Nginx configuration:
FOUND

63. Verify Configuration Ownership

Record:

owner
group
permissions

before modification.

For example:

root:root
0644

The repair engine should preserve these.

64. Verify File Hash

sha256sum "$NGINX_CONFIG"

Store:

original_hash

in the repair plan.

65. Plan Fingerprint

A plan could contain:

state_fingerprint:
SHA256(...)

constructed from:

current PHP socket
Nginx configuration hash
site ID

Before application, calculate again.

If different:

STALE

66. Plan Example

CresignSys Repair Plan
======================

Plan:
RP-000021

Site:
example.com

Problem:
PHP_VERSION_DRIFT

Current:
8.2

Expected:
8.3

Target socket:
/run/php/php8.3-fpm.sock

Target service:
php8.3-fpm

Prerequisites:
[OK] PHP-FPM available
[OK] PHP-FPM running
[OK] Nginx configuration found
[OK] Configuration backup possible
[OK] nginx validation available

Risk:
MEDIUM

Status:
VALID

67. Proposed Actions

1. Backup:
   /etc/nginx/sites-enabled/example.com.conf

2. Update:
   php8.2-fpm.sock
   →
   php8.3-fpm.sock

3. Run:
   nginx -t

4. Reload:
   nginx

5. Verify:
   HTTPS

6. Reconcile:
   example.com

68. No Changes Yet

End with:

NO CHANGES HAVE BEEN MADE.

This line should always appear in hosting-repair-plan.

It makes the command’s safety boundary explicit.

69. What We Are Building

The CHP architecture is becoming:

                SITE
                 │
                 ▼
             DISCOVERY
                 │
                 ▼
            RECONCILIATION
                 │
             ┌───┴───┐
             │       │
           MATCH    DRIFT
             │       │
             │       ▼
             │   REPAIR PLAN
             │       │
             │       ▼
             │   VALIDATION
             │       │
             │       ▼
             │    APPROVAL
             │       │
             │       ▼
             │      APPLY
             │       │
             │       ▼
             └── VERIFY

70. Lesson 084 — Core Principle

A professional hosting platform should not respond to:

DRIFT

with:

CHANGE

It should respond:

DRIFT
 ↓
UNDERSTAND
 ↓
PLAN
 ↓
VALIDATE
 ↓
APPROVE
 ↓
CHANGE
 ↓
VERIFY

This gives CHP a controlled path from observation to automation without turning the management system into an uncontrolled shell-command executor.

Next Lesson — 085

The next step is the actual repair execution engine:

sudo hosting-repair RP-000021

It will implement:

1. Verify plan
2. Acquire site lock
3. Reconcile again
4. Check plan fingerprint
5. Create backup
6. Apply one action
7. Validate
8. Apply next action
9. Run health check
10. Run reconciliation
11. Mark VERIFIED

The most important part will be rollback:

BACKUP
  ↓
CHANGE
  ↓
VALIDATION FAILS
  ↓
AUTOMATIC ROLLBACK
  ↓
HEALTH CHECK
  ↓
ROLLED_BACK

This will be the first CHP component that is allowed to modify a live website, so its safety boundaries need to be considerably stricter than the discovery and monitoring components.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts