Metadata-Version: 2.4
Name: catoptromancy
Version: 0.1.0
Summary: Mirror Google Drive folders to local directories with format conversion
Project-URL: Homepage, https://github.com/terra-hq/catoptromancy
Project-URL: Repository, https://github.com/terra-hq/catoptromancy
Project-URL: Issues, https://github.com/terra-hq/catoptromancy/issues
Author: Nathaniel Kelner
License-Expression: MIT
License-File: LICENSE
Keywords: cli,google-drive,mirror,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: google-auth-oauthlib>=1.2
Requires-Dist: google-auth>=2.25
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=8.2
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

[![ascii-art-(3).jpg](https://i.postimg.cc/zffQBPSY/ascii-art-(3).jpg)](https://postimg.cc/QFRmYmyf)
# Catoptromancy — _divination by mirrors_.

SOTA coding agents like Claude Code and Codex turn out to be very good _everthing agents_. Indeed, Claude Cowork, Anthropic's all purpose agent, is a close cousin of Claude Code and is built on the same stack (the anthropic agent SDK). And so agents (coding or no) work best when situated in an actual folder of files. They like to read text files, search through excels and explore folder strucutres. They have the best tools for exploring and understanding knowledge and context when it's hosted in a file system structure.

Google Drive Folders, while exteremely useful for collaboration, are not *actially* filesystems. Behind the scenes you can't download a google doc into a real file. Even the Google Drive Mac Apps just syncs links to files, not the actual fiels themselves. This makes it surprisingly hard to point an agent at a google drive folder and get the results you expect.

To solve this problem, Catoptromancy mirrors Google Drive folders into a local folder workspace where AI agents can actually work and into formats they can actually use. `cato` currently converts Google Docs into Markdown, Sheets into Excel, and Slides into PowerPoint.

This local copy also acts as a sandbox. Agents can read, edit, and create freely without touching the original data. Nothing syncs back to Drive. This version supports pull-only mirroring, so remote changes come down locally but there is no push command yet. 

## Installation

### Install As A Tool

Install the latest version directly from Git:

```bash
uv tool install git+ssh://git@github.com/terra-hq/catoptromancy.git
```

### Install Into The Current Environment

Install the package into the current virtualenv:

```bash
uv pip install git+ssh://git@github.com/terra-hq/catoptromancy.git
```

### Updating

If installed as a tool:

```bash
uv tool upgrade catoptromancy
```

If installed into a virtualenv:

```bash
uv pip install --upgrade git+ssh://git@github.com/terra-hq/catoptromancy.git
```

### Development Setup

Clone the repo, then install the project and dev dependencies:

```bash
git clone git@github.com:terra-hq/catoptromancy.git
cd catoptromancy
uv sync --extra dev
```

That creates or updates `.venv/` with the package, `pytest`, `ruff`, and the other development dependencies.

Run the test suite with:

```bash
.venv/bin/pytest -q
```

Run the CLI from the project environment with:

```bash
.venv/bin/cato --help
```

## Google Cloud Setup

For OAuth, create a desktop-app credentials file:

1. Go to <https://console.cloud.google.com/apis/credentials>
2. Create a project, or use an existing one
3. Enable the Google Drive API
4. Create an OAuth client ID for a Desktop app
5. Download the JSON file
6. Save it to `~/.config/catoptromancy/credentials.json`

For service-account auth, pass `--service-account /path/to/service-account.json` to `cato init` instead of using OAuth.

## Usage

### Initialize A Workspace

For OAuth, `cato init` opens a browser for consent:

```bash
cato init <FOLDER_ID_OR_URL>
```

The folder reference can be either:

- A raw Google Drive folder ID
- A full Google Drive folder URL

The folder ID is the last part of a Drive folder URL:

```text
https://drive.google.com/drive/folders/<THIS_PART>
```

### Pull Files

```bash
cato pull
```

### Force A Full Re-Download

```bash
cato pull --force
```

### Check Status

```bash
cato status
```

### Show Command Help

```bash
cato --help
```

## Packaging

Catoptromancy is packaged as a standard Python project. Build configuration lives in `pyproject.toml` and uses `hatchling`.

### Build Distributable Artifacts

```bash
uv build
```

This creates:

- `dist/*.whl`
- `dist/*.tar.gz`

### Verify A Built Wheel Locally

```bash
uv pip install dist/*.whl
```

### Publish A Release

1. Bump the version in `pyproject.toml`.
2. Run `uv build`.
3. Publish the contents of `dist/` to your package index.

### Console Script

`cato`
