AdminIsidore at 15:02, 26 August 2025

2025-08-26T15:02:40Z

AdminIsidore at 19:49, 25 August 2025

2025-08-25T19:49:21Z

AdminIsidore: 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..."

2025-08-25T17:05:35Z

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..."

New page

{{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 [[User:Isidore Lands|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+
* [[https://pypa.github.io/pipx/ pipx]]
* [[https://git-scm.com/ Git]]

=== Installation Steps ===
1. Clone the repository from GitHub:
<code>
git clone https://github.com/IsidoreLands/scribo.git
cd scribo
</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.
<code>
pipx install .
</code>

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

== 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.
<code>
scribo-watcher
</code>
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:
<code>
scribo-diff project/module/guide.py /tmp/guide_revised.py
</code>

'''What this command does:'''
# 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 ==
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: [[https://github.com/IsidoreLands/scribo]]

Scribo (AetherOS) - Revision history

AdminIsidore at 15:02, 26 August 2025

AdminIsidore at 19:49, 25 August 2025