Scribo (AetherOS)

Template:Scribo Version Template:Project Status 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-apply" toolset, consisting of a patch generation script and a background watcher that applies patches automatically.

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:

• Formalizing the Patch: Creating self-contained patch files that include all necessary metadata, eliminating ambiguity.
• Automating the Application: Using a background file system watcher to apply these patches the moment they are created.
• Ensuring Code Quality: Automatically running formatters and linters (like Black and Ruff) on every patched file.
• Learning from Failure: Establishing a quarantine system for failed patches, which form the basis of a regression testing suite.

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.

Prerequisites

• Python 3.8+
• [pipx]
• [Git]

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 from the local directory. This will build the tool and make the `scribo-diff` and `scribo-watcher` commands globally available. pipx install .

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

Operation

The standard workflow involves two components: the patch generator (`scribo-diff`) and the background watcher (`scribo-watcher`).

Step 1: Run the Watcher

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. scribo-watcher The watcher will provide real-time feedback as it processes files.

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`).

To integrate the changes, run the `scribo-diff` command: scribo-diff project/module/guide.py /tmp/guide_revised.py

What this command does:

1. Calculates the `diff` between the two files.
2. 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`).
3. 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

This section documents the ongoing development, architectural decisions, and future roadmap for Scribo.

Version 1.1 (Current)

• 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)

• 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.
• 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`.
• 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.
• 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

• The official source code is hosted on GitHub: [[1]]