Scribo (AetherOS): Difference between revisions

From OODA WIKI
Jump to navigation Jump to search
AdminIsidore (talk | contribs)
aether-access, Bureaucrats, contubadmin, duffers, Interface administrators, latin, liberty, mystery, proveit, Administrators (Semantic MediaWiki), Curators (Semantic MediaWiki), Editors (Semantic MediaWiki), Suppressors, swift, Administrators, Upload Wizard campaign editors, visualdata-admin, visualdata-editor, wayfinder
675 edits
Created page with "{{Scribo Version|1.1.0}} {{Project Status|Alpha}} '''Scribo''' is a command-line utility designed to intelligently and automatically apply code changes from a revised file to an original source file. It streamlines the development workflow by eliminating the tedious and error-prone task of manual code merging for discrete revisions. It was co-developed by Isidore Lands and the AetherOS architect, Alex. The system is architected as a "diff-and-appl..."
 
AdminIsidore (talk | contribs)
aether-access, Bureaucrats, contubadmin, duffers, Interface administrators, latin, liberty, mystery, proveit, Administrators (Semantic MediaWiki), Curators (Semantic MediaWiki), Editors (Semantic MediaWiki), Suppressors, swift, Administrators, Upload Wizard campaign editors, visualdata-admin, visualdata-editor, wayfinder
675 edits
No edit summary
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
{{Scribo Version|1.1.0}}
{{Scribo Version|3.1.0}}
{{Project Status|Alpha}}
{{Project Status|Beta}}
'''Scribo''' is a command-line utility designed to intelligently and automatically apply code changes from a revised file to an original source file. It streamlines the development workflow by eliminating the tedious and error-prone task of manual code merging for discrete revisions. It was co-developed by [[User:Isidore Lands|Isidore Lands]] and the AetherOS architect, Alex.
'''Scriptor''' is a unified, command-line SDK 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:Isidore Lands|Isidore Lands]] and [[User:Alex M. Xlea|Alex M. Xlea]].


The system is architected as a "diff-and-apply" toolset, consisting of a patch generation script and a background watcher that applies patches automatically.
The system is architected as a producer/consumer toolset, consisting of the patch generator command, '''scriptor compara''', and an autonomous background daemon, '''scriptor speculator''', which detects and processes patches.


== Architecture and Philosophy ==
== Architecture and Philosophy ==
The core philosophy of Scribo is to make the revision process invisible and robust. A developer should only need to be concerned with writing the code, not the mechanics of integrating it. Scribo achieves this by:
The core philosophy of Scriptor 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. Scriptor v3.1 achieves this through a sophisticated, multi-stage pipeline:
*   '''Formalizing the Patch:''' Creating self-contained patch files that include all necessary metadata, eliminating ambiguity.
* '''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.
*   '''Automating the Application:''' Using a background file system watcher to apply these patches the moment they are created.
* '''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.
*   '''Ensuring Code Quality:''' Automatically running formatters and linters (like Black and Ruff) on every patched file.
* '''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.
*   '''Learning from Failure:''' Establishing a quarantine system for failed patches, which form the basis of a regression testing suite.
* '''Persistent Logging:''' All actions are recorded in a rotating log file, '''Acta Scriptoris''' (The Records of Scriptor), providing a durable audit trail of every patch that was applied, rejected, or quarantined.
* '''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.
 
== Core Components & Commands ==
The Scriptor SDK is a single, unified tool (`scriptor`) that provides several subcommands.
* '''`scriptor compara`''' (The Comparer): Generates a self-contained `.patch` file by comparing an original and a revised source file.
* '''`scriptor speculator`''' (The Watcher): The file system watcher daemon that detects new patches in the inbox.
* '''`scriptor inceptor`''' (The Inceptor): A project scaffolding tool that creates new, sandboxed development initiatives.
* '''`scriptor praetor`''' (The Praetor): The Fleet Commander, used for deploying tools and managing multiple development nodes.
 
The core modules that power these commands are:
* '''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 newly patched files.
* '''Probator''' (The Tester): The verification module that runs the project's test suite to confirm the patch's integrity.


== Installation ==
== Installation ==
Scribo is designed as a global command-line tool using `pipx` to ensure it operates in an isolated environment and does not conflict with project-specific dependencies.
Scriptor is designed as a global command-line tool using `pipx` to ensure it operates in an isolated environment.


=== Prerequisites ===
=== Prerequisites ===
*   Python 3.8+
* Python 3.8+
*   [[https://pypa.github.io/pipx/ pipx]]
* [[https://pypa.github.io/pipx/ pipx]]
*   [[https://git-scm.com/ Git]]
* [[https://git-scm.com/ Git]] (for the Probator's project root discovery)


=== Installation Steps ===
=== Installation Steps ===
Line 27: Line 41:
</code>
</code>


2. Use `pipx` to install the package from the local directory. This will build the tool and make the `scribo-diff` and `scribo-watcher` commands globally available.
2. Use `pipx` to install the package. This builds the tool and makes the `scriptor` command globally available.
<code>
<code>
pipx install .
pipx install .
</code>
</code>


3. Create the inbox directory that the watcher will monitor:
3. Create the inbox directory that the Speculator will monitor:
<code>
<code>
mkdir ~/scribo_inbox
mkdir ~/scribo_inbox
Line 38: Line 52:


== Operation ==
== Operation ==
The standard workflow involves two components: the patch generator (`scribo-diff`) and the background watcher (`scribo-watcher`).
The standard workflow involves running the `speculator` daemon as a background service and using the other `scriptor` commands to perform tasks.
 
=== Step 1: Run Speculator as a Service ===
The recommended way to run the watcher is as a `systemd` user service.


=== Step 1: Run the Watcher ===
1. Create the service file at `~/.config/systemd/user/scriptor.service`:
In a dedicated terminal, or as a background process (e.g., in `tmux` or `screen`), start the watcher. It will now monitor the inbox for incoming patches.
<code>
<code>
scribo-watcher
[Unit]
Description=Scriptor Daemon (via Scriptor SDK)
After=network.target
 
[Service]
ExecStart=%h/.local/bin/scriptor speculator
Restart=on-failure
RestartSec=5s
 
[Install]
WantedBy=default.target
</code>
</code>
The watcher will provide real-time feedback as it processes files.
 
2. Enable and start the service:
<code>
systemctl --user daemon-reload
systemctl --user enable --now scriptor.service
</code>
 
You can check its status or view live logs with `systemctl --user status scriptor.service` and `journalctl --user -u scriptor.service -f`.


=== Step 2: Generate a Patch ===
=== Step 2: Generate a Patch ===
As a developer, you have your original file (e.g., `project/module/guide.py`) and you have created a revised version (e.g., `/tmp/guide_revised.py`).
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:
 
To integrate the changes, run the `scribo-diff` command:
<code>
<code>
scribo-diff project/module/guide.py /tmp/guide_revised.py
scriptor compara guide_main.py guide_v4.py
</code>
</code>


'''What this command does:'''
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.
# Calculates the `diff` between the two files.
# Creates a new patch file inside `~/scribo_inbox/`. The patch file is named with a timestamp for easy tracking (e.g., `20250825-171500-guide.patch`).
# Critically, it embeds the absolute path of the '''original''' file inside the patch, so the watcher knows which file to modify.
 
The moment this file is created, the `scribo-watcher` will detect it, apply the patch, run formatters, and clean up. Your work is done.


== Development Journal ==
== Development Journal ==
This section documents the ongoing development, architectural decisions, and future roadmap for Scribo.
=== Version 3.1 (Current) ===
* '''Architectural Unification:''' All tools have been refactored into a single, unified SDK with a main `scriptor` command and logical subcommands (`speculator`, `compara`, `praetor`, `inceptor`).
* '''Enhanced Patching Logic:''' The core patching engine (`Perfector` and `Comparator`) was completely overhauled to use git-style relative paths, making it vastly more robust and reliable.
* '''Hardened Verification:''' The `Probator` and `Ornator` modules were refined to be more intelligent and fault-tolerant, correctly handling non-Python files and projects without tests.


=== Version 1.1 (Current) ===
''(For previous versions, see the Git history.)''
*  '''Architecture Refactor:''' Split the original monolithic `patcher` script into a two-part system: `scribo-diff` and `scribo-watcher`. This enables true background automation and a more robust workflow.
*  '''Formalized Patch Format:''' Patches now contain a metadata header specifying the target file path.
*  '''Quarantine System:''' Added logic for the watcher to move failing patches to a `~/scribo_inbox/quarantine/` directory for later analysis.


=== Roadmap (Future Development) ===
== Roadmap (Future Development) ==
*   '''Test Harness Implementation:''' Develop a `pytest` suite that automatically discovers and runs tests against patches in the `quarantine/` directory. This will form the core of the "self-learning" capability, ensuring that once a bug is fixed, it never returns.
* '''Praetor Fleet Command:''' Fully implement the `praetor deploy-sensor` command to provision new machines with the System Maneuverability toolset. Integrate the SM and Agentic Maneuverability (AM) scores into the Praetor's decision-making process for intelligent task dispatching.
*   '''Conflict Resolution UI:''' For patches that cannot be applied cleanly, develop a simple TUI (Text-based User Interface) that presents the conflicting hunks to the user for manual resolution, similar to `git mergetool`.
* '''ARC Integration:''' Bridge the Scriptor SDK with the AetherOS `Navigator` ARC, allowing the ARC to autonomously propose and test patches to its own codebase.
*   '''Plugin System:''' Allow for custom post-patch scripts. For instance, a user might want to run project-specific tests or trigger a notification after a successful patch.
* '''Initiative Scaffolding:''' Evolve the `inceptor` into a full-fledged project scaffolding tool that can bootstrap new initiatives with pre-configured ARCs and best-practice repository structures.
*  '''Remote Inbox:''' Explore options for using a shared directory (e.g., on a NAS) or a simple message queue as an inbox, allowing for distributed development workflows.


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

Latest revision as of 15:02, 26 August 2025

Template:Scribo Version Template:Project Status Scriptor is a unified, command-line SDK 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 Isidore Lands and Alex M. Xlea.

The system is architected as a producer/consumer toolset, consisting of the patch generator command, scriptor compara, and an autonomous background daemon, scriptor speculator, which detects and processes patches.

Architecture and Philosophy

The core philosophy of Scriptor 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. Scriptor v3.1 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.
  • Persistent Logging: All actions are recorded in a rotating log file, Acta Scriptoris (The Records of Scriptor), providing a durable audit trail of every patch that was applied, rejected, or quarantined.
  • 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.

Core Components & Commands

The Scriptor SDK is a single, unified tool (`scriptor`) that provides several subcommands.

  • `scriptor compara` (The Comparer): Generates a self-contained `.patch` file by comparing an original and a revised source file.
  • `scriptor speculator` (The Watcher): The file system watcher daemon that detects new patches in the inbox.
  • `scriptor inceptor` (The Inceptor): A project scaffolding tool that creates new, sandboxed development initiatives.
  • `scriptor praetor` (The Praetor): The Fleet Commander, used for deploying tools and managing multiple development nodes.

The core modules that power these commands are:

  • 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 newly patched files.
  • Probator (The Tester): The verification module that runs the project's test suite to confirm the patch's integrity.

Installation

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

Prerequisites

  • Python 3.8+
  • [pipx]
  • [Git] (for the Probator's project root discovery)

Installation Steps

1. Clone the repository from GitHub: git clone https://github.com/IsidoreLands/scribo.git cd scribo

2. Use `pipx` to install the package. This builds the tool and makes the `scriptor` command globally available. pipx install .

3. Create the inbox directory that the Speculator will monitor: mkdir ~/scribo_inbox

Operation

The standard workflow involves running the `speculator` daemon as a background service and using the other `scriptor` commands to perform tasks.

Step 1: Run Speculator as a Service

The recommended way to run the watcher is as a `systemd` user service.

1. Create the service file at `~/.config/systemd/user/scriptor.service`: [Unit] Description=Scriptor Daemon (via Scriptor SDK) After=network.target

[Service] ExecStart=%h/.local/bin/scriptor speculator Restart=on-failure RestartSec=5s

[Install] WantedBy=default.target

2. Enable and start the service: systemctl --user daemon-reload systemctl --user enable --now scriptor.service

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

Step 2: Generate a Patch

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: scriptor 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.

Development Journal

Version 3.1 (Current)

  • Architectural Unification: All tools have been refactored into a single, unified SDK with a main `scriptor` command and logical subcommands (`speculator`, `compara`, `praetor`, `inceptor`).
  • Enhanced Patching Logic: The core patching engine (`Perfector` and `Comparator`) was completely overhauled to use git-style relative paths, making it vastly more robust and reliable.
  • Hardened Verification: The `Probator` and `Ornator` modules were refined to be more intelligent and fault-tolerant, correctly handling non-Python files and projects without tests.

(For previous versions, see the Git history.)

Roadmap (Future Development)

  • Praetor Fleet Command: Fully implement the `praetor deploy-sensor` command to provision new machines with the System Maneuverability toolset. Integrate the SM and Agentic Maneuverability (AM) scores into the Praetor's decision-making process for intelligent task dispatching.
  • ARC Integration: Bridge the Scriptor SDK with the AetherOS `Navigator` ARC, allowing the ARC to autonomously propose and test patches to its own codebase.
  • Initiative Scaffolding: Evolve the `inceptor` into a full-fledged project scaffolding tool that can bootstrap new initiatives with pre-configured ARCs and best-practice repository structures.

Repository

  • The official source code is hosted on GitHub: [[1]]
Retrieved from "https://www.ooda.wiki/index.php?title=Scribo_(AetherOS)&oldid=679"