From 9687cdf92a90d12736eacd357860b76334342009 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 03:28:17 +0000 Subject: [PATCH 1/2] Update project documentation with details and conventions - Filled `documentation/architecture/openspec/project.md` with project purpose, tech stack, and conventions. - Added references to `documentation/architecture/filesystem.rst` as requested. - Documented testing strategy, git workflow, and domain context. --- .../architecture/openspec/project.md | 57 +++++++++++++++---- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index 3da5119..9d111e5 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,31 +1,68 @@ # Project Context ## Purpose -[Describe your project's purpose and goals] +Mimeogram is a command-line tool for **exchanging collections of files with Large Language Models (LLMs)**. It bundles multiple files into a single clipboard-ready document while preserving directory structure and metadata, making it ideal for code reviews, project sharing, and LLM interactions. It supports interactive reviews, clipboard integration, and path protection. ## Tech Stack -- [List your primary technologies] -- [e.g., TypeScript, React, Node.js] +- **Language**: Python 3.10+ +- **Build System**: Hatch +- **Packaging**: PyInstaller (for standalone executable) +- **Key Libraries**: + - `accretive` (accretive data structures) + - `aiofiles` (async file I/O) + - `detextive` (text detection) + - `httpx` (HTTP client) + - `icecream-truck` (debugging) + - `patiencediff` (diff generation) + - `pyperclip` (clipboard integration) + - `rich` (terminal formatting) + - `tiktoken` (token counting) + - `tomli` (TOML parsing) + - `tyro` (CLI argument parsing) + - `appcore` (application core utilities) ## Project Conventions ### Code Style -[Describe your code style preferences, formatting rules, and naming conventions] +- **Line Length**: 79 characters +- **Indentation**: 4 spaces +- **Type Hinting**: Strict type checking with `pyright` (reportUnknownArgumentType, etc. are true). +- **Linters**: + - `ruff` (general linting) + - `isort` (import sorting) + - `vibelinter` (custom linter) +- **Configuration**: See `pyproject.toml` for detailed linter configurations. ### Architecture Patterns -[Document your architectural decisions and patterns] +- **Filesystem Organization**: See [`documentation/architecture/filesystem.rst`](../filesystem.rst) for details on the project structure. +- **Import Hub Pattern**: Uses a centralized `__` import hub (e.g., `from . import __`) to manage internal and external dependencies. +- **CLI Separation**: The CLI logic is separated into `cli.py` and `__main__.py` to allow independent testing and execution. +- **Immutability**: Uses `frigid` and `accretive` for immutable and append-only data structures where appropriate. ### Testing Strategy -[Explain your testing approach and requirements] +- **Framework**: `pytest` +- **Property-based Testing**: `hypothesis` +- **Coverage**: Branch coverage enabled, enforced via CI. +- **Doctests**: Run via Sphinx. +- **Test Naming**: `test_[0-9][0-9][0-9]_*` pattern for test functions. +- **Location**: All tests are located in the `tests/` directory. ### Git Workflow -[Describe your branching strategy and commit conventions] +- **Branching**: Pull Request (PR) based workflow. +- **Changelog**: Managed via `towncrier`. Changelog fragments are stored in `.auxiliary/data/towncrier` and compiled into `documentation/changelog.rst`. +- **CI/CD**: GitHub Actions for testing and linting. ## Domain Context -[Add domain-specific knowledge that AI assistants need to understand] +- **LLM Context Windows**: The tool is designed to optimize for limited context windows of LLMs. +- **Mimeogram Format**: A specific textual format for bundling files that LLMs can understand and generate. +- **Clipboard Operations**: Heavy reliance on system clipboard for data transfer between the tool and LLM interfaces (web/desktop). +- **Path Protection**: Security mechanism to prevent LLMs from modifying sensitive files or directories. ## Important Constraints -[List any technical, business, or regulatory constraints] +- **Platform Support**: Must work on Linux, macOS, and Windows. +- **Python Support**: Supports Python 3.10 to 3.14. +- **No Automatic Sync**: The tool does not automatically sync files; it relies on manual `create` and `apply` steps. ## External Dependencies -[Document key external services, APIs, or systems] +- **LLM Providers**: Interacts with LLMs (OpenAI, Anthropic, etc.) indirectly via text/clipboard. +- **GitHub**: Supports fetching files from remote GitHub URLs. From f8df2261934fcf746945dd7047e82b5eb0049e74 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 12 Dec 2025 04:45:19 +0000 Subject: [PATCH 2/2] Update project documentation with details and conventions - Filled `documentation/architecture/openspec/project.md` with project purpose, tech stack, and conventions. - Added references to `documentation/architecture/filesystem.rst` as requested. - Documented testing strategy, git workflow, and domain context. - Addressed review feedback: - Changed "Mimeogram is a" to "This is a" in Purpose section. - Removed reference to `vibelinter`. --- documentation/architecture/openspec/project.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/architecture/openspec/project.md b/documentation/architecture/openspec/project.md index 9d111e5..a8e44ee 100644 --- a/documentation/architecture/openspec/project.md +++ b/documentation/architecture/openspec/project.md @@ -1,7 +1,7 @@ # Project Context ## Purpose -Mimeogram is a command-line tool for **exchanging collections of files with Large Language Models (LLMs)**. It bundles multiple files into a single clipboard-ready document while preserving directory structure and metadata, making it ideal for code reviews, project sharing, and LLM interactions. It supports interactive reviews, clipboard integration, and path protection. +This is a command-line tool for **exchanging collections of files with Large Language Models (LLMs)**. It bundles multiple files into a single clipboard-ready document while preserving directory structure and metadata, making it ideal for code reviews, project sharing, and LLM interactions. It supports interactive reviews, clipboard integration, and path protection. ## Tech Stack - **Language**: Python 3.10+ @@ -30,7 +30,6 @@ Mimeogram is a command-line tool for **exchanging collections of files with Larg - **Linters**: - `ruff` (general linting) - `isort` (import sorting) - - `vibelinter` (custom linter) - **Configuration**: See `pyproject.toml` for detailed linter configurations. ### Architecture Patterns