Scribo (AetherOS): Difference between revisions

{{Scribo Version|3.0.0}}

{{Project Status|Beta}}

'''Scribo''' is a suite of command-line utilities designed to intelligently and automatically apply code changes from a revised file to an original source file. It streamlines the development workflow by creating a robust, autonomous system for integrating discrete revisions. It was co-developed by [[User:AdminIsidore|Isidore Lands]] and [[User:AlexMXlea|Alex M. Xlea]].

The system is architected as a producer/consumer toolset, consisting of the patch generator, '''Compara''', and an autonomous background daemon, '''Speculator''', which detects and processes patches.

The core philosophy of Scribo is to make the revision process invisible, robust, and safe. A developer should only need to be concerned with writing the code, not the mechanics of integrating it. Scribo v3.0 achieves this through a sophisticated, multi-stage pipeline:

* '''Producer/Consumer Model:''' The '''Speculator''' daemon's sole responsibility is to detect new patches and place them on a work queue. A separate worker thread, the '''Operarius''' (workman), pulls from this queue to process each patch sequentially, ensuring the system is resilient to rapid, multiple patch submissions.

* '''Atomic Operations:''' No change is committed until it is fully verified. Before patching, a temporary backup of the original file is created. The system then applies the patch, formats the code, and runs tests. Only if all stages succeed is the backup removed. If any stage fails, the original file is instantly restored from the backup and the faulty patch is quarantined.

* '''Automated Verification (The Probator):''' After a patch is applied and formatted, the '''Probator''' (tester) automatically discovers and runs the project's '''pytest''' suite. This crucial step prevents patches that break existing functionality from ever being integrated.

* '''True Daemonization:''' The '''Speculator''' is designed to run as a proper background service using '''systemd''', ensuring it is always running, automatically starts on login, and restarts itself on failure.

 

* '''Speculator''' (The Watcher): The file system watcher daemon that detects new patches in the inbox.

* '''Operarius''' (The Workman): The background worker thread that executes the processing pipeline for each patch.

* '''Perfector''' (The Completer): The module responsible for applying the patch to the target file.

* '''Ornator''' (The Arranger): The module that runs code formatters (like Black and Ruff) on the newly patched file.

* '''Probator''' (The Tester): The verification module that runs the project's test suite to confirm the patch's integrity.

Scribo is designed as a global command-line tool using `pipx` to ensure it operates in an isolated environment.

* Python 3.8+

* [[https://pypa.github.io/pipx/ pipx]]

* [[https://git-scm.com/ Git]] (for the Probator's project root discovery)

# Clone the repository from GitHub:

cd scribo/coniunctor

# Use `pipx` to install the package. This builds the tool and makes the `compara` and `speculator` commands globally available.

# Create the inbox directory that the Speculator will monitor:

The standard workflow involves running the `speculator` daemon as a background service and using `compara` to generate patches.

 

=== Step 1: Run Speculator as a Service ===

The recommended way to run the watcher is as a `systemd` user service. This ensures it's always running in the background.

 

1. Create the service file at `~/.config/systemd/user/scriptor.service`:

 

Restart=on-failure

 

WantedBy=default.target

2. Enable and start the service:

systemctl --user daemon-reload

 

You can check its status or view live logs with `systemctl --user status scriptor.service` and `journalctl --user -u scriptor.service -f`.

As a developer, you have your original file (`guide_main.py`) and a revised version (`guide_v4.py`). To integrate the changes, run the `compara` command:

compara guide_main.py guide_v4.py

The moment the patch file is created in `~/scribo_inbox/`, the `speculator` service will detect it and trigger the full automated pipeline: apply, format, test, and commit or revert. Your work is done.

* '''Test-Driven Verification:''' Introduced the '''Probator''' module, which integrates `pytest` directly into the pipeline, enabling automated regression testing for every patch.

* '''Atomic Operations:''' The entire patch process is now atomic, with an automatic backup and revert mechanism that guarantees a patch either succeeds completely or the system is returned to its original state.

* '''Daemonization:''' Added full support for running '''Speculator''' as a `systemd` service for true "fire-and-forget" background operation.

* '''Persistent Logging:''' Replaced console output with a formal, rotating log file (`Acta_Scriptoris.log`) via Python's `logging` module.

=== Version 1.1 ===

* '''Architecture Refactor:''' Split the original monolithic `patcher` script into a two-part system.

* '''Formalized Patch Format:''' Patches now contain a metadata header specifying the target file path.

* '''Quarantine System:''' Added logic to move failing patches to a quarantine directory.

* '''Conflict Resolution TUI:''' For patches that cannot be applied cleanly, develop a simple Text-based User Interface (TUI) that presents conflicting hunks for manual resolution.

* '''Plugin System:''' Allow for custom post-verification scripts (e.g., trigger notifications, deploy to staging).

* '''Remote Inbox:''' Explore options for using a message queue (like RabbitMQ or Redis) as an inbox for distributed development workflows.

* The official source code is hosted on GitHub: [[https://github.com/IsidoreLands/scribo]]