Metadata-Version: 2.4
Name: ovllib_dev
Version: 0.1.3
Summary: Make desktop overlays using existing web-techs
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: InquirerPy
Requires-Dist: pydantic
Requires-Dist: tomlkit

# ovllib_dev

`ovllib_dev` is a small CLI for creating desktop overlay projects with modern web
tooling. It can scaffold a frontend project, generate an overlay configuration
file, and package the built static site into a `.ovl` archive.

## Features

- Interactive project setup
- Support for React, Vue, Solid, SvelteKit, and vanilla Vite projects
- TypeScript and JavaScript project templates
- Package manager support for `npm`, `pnpm`, `yarn`, and `bun`
- Static build configuration for overlay packaging
- `.ovl` archive generation from frontend build output

## Requirements

- Python 3.10 or newer
- `uv` for local development
- One supported JavaScript package manager:
  - `npm`
  - `pnpm`
  - `yarn`
  - `bun`

The selected package manager must be installed before running project setup or
build commands.

## Installation

```bash
pip install ovllib_dev
ovllib_dev --version
```

## Usage

### Create a new overlay project

```sh
ovllib_dev init
```

The setup flow asks for:

- Project name
- Package manager
- Frontend framework
- Frontend language

After confirmation, `ovllib_dev` creates the frontend project and writes an
`ovl_config.toml` file into the generated project directory.

### Build an overlay package

From inside a generated overlay project, run:

```sh
uv run python /path/to/ovllib_dev/main.py build
```

The build command:

1. Reads `ovl_config.toml`
2. Runs the configured frontend build command
3. Copies the static frontend output and overlay config into a temporary package
4. Creates a `.ovl` archive in the configured build output directory

By default, packaged overlays are written to:

```text
build/ovl/<project-name>.ovl
```

## Configuration

Generated projects include an `ovl_config.toml` file like this:

```toml
# Auto-generated by ovl setup

[project]
name = "my-overlay"
entry_dir = "web"
entry_file = "index.html"

[window]
width = 600
height = 400
x = 40
y = 40
movable = true
move_element = ""

[build]
framework = "react"
package_manager = "npm"
frontend_output = "build"
build_dist = "build/ovl"
```

### Project settings

- `name`: Project and output package name
- `entry_dir`: Directory inside the package that contains the frontend files
- `entry_file`: HTML file used as the overlay entry point

### Window settings

- `width` and `height`: Initial overlay size
- `x` and `y`: Initial overlay position
- `movable`: Whether the overlay can be moved
- `move_element`: Optional selector or element identifier used for dragging

### Build settings

- `framework`: Frontend framework selected during setup
- `package_manager`: Package manager used for build commands
- `frontend_output`: Static frontend build directory
- `build_dist`: Directory where `.ovl` packages are written

## Supported frontend stacks

| Framework | TypeScript | JavaScript |
| --- | --- | --- |
| React | Yes | Yes |
| Vue | Yes | Yes |
| Solid | Yes | Yes |
| SvelteKit | Yes | Yes |
| Vanilla | Yes | Yes |

Vite-based projects are configured to emit static files into `build`.
SvelteKit projects are configured with `@sveltejs/adapter-static` and
prerendering enabled.

## Development

Run the CLI locally:

```sh
uv run python main.py init
uv run python main.py build
```

Check Python syntax:

```sh
uv run python -m py_compile main.py build.py init.py
```

## Project structure

```text
.
├── build.py          # Packages a built frontend into a .ovl archive
├── init.py           # Interactive project scaffolding
├── main.py           # CLI entry point
├── pyproject.toml    # Python project metadata and dependencies
├── uv.lock           # Locked Python dependencies
└── README.md
```

## Notes

- `robots.txt` is excluded from packaged frontend output.
- Existing overlay build output is ignored while copying frontend files, which
  prevents previously generated `.ovl` packages from being nested in new builds.
- The `build` command expects `ovl_config.toml` to be present in the current
  working directory.
