@amoghvj/txr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amogh Vijay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# txr - Transactional Command Runner
+
+`txr` is a standalone CLI tool that provides transactional execution of shell commands. It acts as a safety net, allowing you to run commands (like `npm install`, generators, or scripts) and undo them completely if they don't produce the desired outcome. 
+
+It works independently of any user Git repository, maintaining its own internal state store to track and rollback filesystem changes with strict safety guarantees.
+
+## Philosophy
+
+* **One executed command = one transaction.**
+* **Correctness over convenience:** `txr` will strictly refuse to undo if a file was externally modified. It never guesses.
+* **Linear History:** There are no branches or merges. It works like an editor's undo stack.
+* **Invisible Storage:** The internal Git repo is hidden and purely used as an efficient storage engine.
+
+## Installation
+
+Currently, `txr` is available as a local package.
+
+```bash
+# Clone or navigate to the repository
+cd agent-cli
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Link globally (optional, so you can run 'txr' anywhere)
+npm link
+```
+
+If you don't link it, you can run it via `node dist/index.js` or `npx .`.
+
+## Usage Instructions
+
+### 1. Initialize a Workspace
+
+Before running transactional commands, initialize `txr` in your project root. This creates a `.txr/` hidden directory to store history and internal state.
+
+```bash
+txr init
+```
+
+By default, `txr` runs in **workspace scope**. This means it only tracks files inside your project directory. If you run a command that modifies files outside the project (like `npm install -g` or writing to an absolute path), `txr` will detect this, flag it as a scope violation, and ask for confirmation before running (and it won't track those external changes).
+
+If you want `txr` to track *everything* a command does, no matter where it writes on your system, initialize with global scope:
+
+```bash
+txr init --global
+```
+
+**Using `txr` everywhere on your system:**
+If you want to use `txr run` in *any* folder on your computer without typing `init` for every new project, you can initialize a single global state store in your user's home directory:
+
+```bash
+cd ~
+txr init --global
+```
+With this setup, `txr` will place the `.txr` folder in your home directory (`~/.txr`). Whenever you use `txr run` anywhere on your machine, it will traverse up the folder tree, find `~/.txr`, and record the transaction there. Because you used `--global`, it will gladly track changes across your entire filesystem.
+
+### 2. Run Commands
+
+Execute any command through `txr`. It will automatically track the filesystem changes and record a transaction.
+
+```bash
+txr run "npm install express"
+txr run "npx create-react-app frontend"
+txr run "node script.js"
+```
+
+**Non-transactional Commands:**
+`txr` analyzes commands before running. If you try to run a command that modifies state outside the filesystem (like databases or containers), it will warn you:
+
+```bash
+txr run "docker compose up -d"
+# ⚠ WARNING: This command may modify state outside the transaction engine.
+# Continue? [y/N]
+```
+You can bypass the prompt with `-y`: `txr run -y "docker compose up -d"`. These commands are logged in history but don't create a transaction.
+
+### 3. Undo a Transaction
+
+If a command broke your project, simply undo the most recent transaction. This restores all created, modified, or deleted files to their exact previous state.
+
+```bash
+txr undo
+```
+
+*Note: If any touched file was manually edited outside of `txr` after the transaction, `txr undo` will safely abort to prevent data loss.*
+
+### 4. Redo a Transaction
+
+If you undid a transaction by mistake, you can redo it (as long as you haven't run any new commands since).
+
+```bash
+txr redo
+```
+
+### 5. Check Status and History
+
+View the current active transaction and attribution tier:
+
+```bash
+txr status
+```
+
+View an audit log of all commands run through `txr`:
+
+```bash
+txr history
+```
+
+## Advanced Options
+
+* `txr run --transactional "cmd"`: Force a command to be tracked as transactional, even if the classifier flags it as unsafe.
+* `txr run --no-transaction "cmd"`: Force a command to run directly without tracking or generating a transaction.
+
+## Attribution Tiers
+
+`txr` uses different methods to track process changes depending on your OS and privileges:
+* **Tier 3 (Hybrid / Scoped Diff):** Default for unprivileged execution. It tracks process lifetimes and diffs declared watch paths.
+* **Tier 2 (Linux ptrace):** *Planned.* Exact syscall interception without root.
+* **Tier 1 (ETW / eBPF):** *Planned.* Exact low-overhead tracking requiring Admin/Root.
+
+## Configuration
+
+You can tweak settings in `.txr/metadata/config.json`, such as:
+* `watchPaths`: Array of directories to track for changes (defaults to `["."]`).
+* `ignorePaths`: Glob patterns to ignore (e.g., `node_modules/.cache`).