Metadata-Version: 2.4
Name: mira-transplier
Version: 1.0.2
Summary: LLM context transpiler that builds a synced .mira workspace view for codebases.
Author: xavuye
Keywords: llm,codebase,transpiler,context,cli
Classifier: Development Status :: 5 - Production/Stable
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 the build writes

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

The tool 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 command from inside a built workspace:

```bash
mira !project
mira !structure
mira !list
mira !create file src/stack.py "class Stack:\n    pass"
mira !expand 12_3
mira !edit_after 12_3 "new lines"
```

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

You only need to run `mira .` once per workspace. After that, source edits, chunk edits, creates, deletes, comments, and environment changes sync 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`, `!structure`, `!explore`, `!expand`, `!find_line`, `!search`
- file operations: `!create`, `!delete`, `!move`, `!copy`, `!paste`
- edits: `!edit`, `!edit_after`, `!edit_before`, `!delete_chunk`
- 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>]`
- `!diff <file_id|path>`, `!history <file_id|path>`, `!restore <file_id|path> <version>`
- `!tool_wrapper [reset|call <prefix> <suffix>|response <prefix> <suffix>]`

`!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

- use exactly one command inside each tool call; do not chain multiple commands in a single `tool_call`
- folder indexing is shallow: subfolders need their own index entry
- dotfiles are ignored by default except `.gitignore`
- `!create` accepts inline file content after the target path when creating a file
- file targets accept file IDs, workspace-relative paths, and absolute workspace paths inside the workspace
- create, delete, move, copy, and paste accept relative paths, leading-slash paths, and absolute workspace paths inside the workspace
- `!copy` only accepts files; folder copy attempts are rejected explicitly
- wrapped placeholder labels such as `<file_id|path>`, `<chunk_id>`, and `[text]` are ignored when they appear before the real argument
- wrapped text payloads such as `[...]`, `<...>`, `"..."`, `'...'`, and triple-quoted wrappers are unwrapped before file edits when they are clearly acting as outer wrappers
- files with parser errors stay explorable through generic fallback chunking instead of disappearing from the index
- `!explore` rejects folders explicitly and points back to file paths instead of guessed file IDs
- whole-file edits show a before/after preview, warn above 400 lines, and are blocked above 1000 lines; use `!explore <path>` for chunked edits on large files
- confirmations accept wrapped `y`/`n` answers such as `[y]`, `"y"`, `yes`, and `no`, and reject anything else with a clear retry message
- selectors ignore surrounding `<>`, `[]`, and matching quotes, and chunk ranges ignore extra spaces around `-`

## Requirements

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