Metadata-Version: 2.4
Name: mira-transplier
Version: 0.3.0
Summary: LLM context transpiler that builds a synced .mira workspace view for codebases.
Author: xavuye
Keywords: llm,codebase,transpiler,context,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# mira-transplier

`mira-transplier` turns a script or repository into a synced `.mira` view that is easier for coding agents and LLMs to navigate with less noise.

## What MIRA builds

When you run MIRA on a folder, it generates a `.mira` directory with:

- `project.mira` for the compact file tree and public command surface
- `GUIDE.txt` for public commands plus admin commands
- per-file chunk metadata, skeletons, and indexes
- history baselines and runtime state for edits and managed terminals

MIRA keeps source and `.mira` in sync, supports history and restore, and works with regular code files, metadata-only document files, and adaptive generic chunking for unsupported text formats such as `.java`.

## Install

```bash
pip install mira-transplier
```

## Basic usage

Build the `.mira` view for the current folder:

```bash
mira .
```

Build a different folder:

```bash
mira path/to/project
```

Run a MIRA command from inside a built workspace:

```bash
mira !project
mira !list
mira !expand 12_3
mira !edit 12_3+ "new lines"
```

If inline text is omitted and stdin is piped, MIRA reads the piped text automatically.

You only need to run `mira .` once per workspace. After that, MIRA syncs source edits, chunk edits, creates, deletes, comments, and environment changes back into `.mira` automatically.

Later syncs only reparse touched source files, keep stable file IDs, and rewrite only the generated `.mira` artifacts whose content actually changed.

## Main command groups

- project navigation: `!project`, `!explore`, `!expand`, `!find_line`, `!search`
- edits and history: `!edit`, `!diff`, `!history`, `!restore`
- workspace metadata: `!memory`, `!goals`, descriptions, chunk comments
- managed terminals: `!terminals`, `!terminal`

## Admin commands

Admin commands stay in `.mira/GUIDE.txt` and are hidden from the public command surface.

- `!index`, `!index add <path>`, `!index remove <path>`
- `!environment [path|clear|create <name>]`

`!environment` lists detected virtual environments in the workspace by checking for activation scripts in `Scripts`. `!environment create <name>` creates a new virtual environment directly in the workspace root and configures it immediately. You can also configure a custom environment root with a full absolute path. Once configured, `project.mira` shows the selected environment as:

```text
ENVIRONMENT: .venv (C:\path\to\workspace\.venv)
```

## Chunk comments

Chunk comments are metadata, not source code. They appear in skeleton structure lines and stay attached when the commented chunk keeps the same code but moves to a different chunk ID.

- `!add_comment <chunk_id> [text]`
- `!edit_comment <chunk_id> [text]`
- `!delete_comment <chunk_id>`

When a commented chunk is edited and its code changes, MIRA prompts to update the comment. When edited or inserted chunks do not have a comment yet, MIRA can prompt to add one.

## Generic chunking

Unsupported code-like text files use adaptive generic chunking.

- target chunk size: 100 lines
- minimum preferred size before cutting early: 80 lines
- hard maximum when no blank boundary exists: 500 lines
- chunk boundaries prefer blank lines, and can extend up to 50 extra lines to land on a double-blank boundary
- blank separator lines stay at the end of the previous chunk so the next chunk does not begin with empty lines

## Notes

- folder indexing is shallow: subfolders need their own index entry
- dotfiles are ignored by default except `.gitignore`
- `!create` and `!delete` accept relative paths, leading-slash paths, and absolute workspace paths
- `!delete` also accepts file IDs

## Requirements

- Python 3.10+
- Windows is the primary tested target right now
