Metadata-Version: 2.4
Name: pntos-cobra-frontend
Version: 0.1.0
Summary: UI components and frontend assets for pntOS Cobra.
Author-email: IS4S <pntos@is4s.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# pntOS Cobra Frontend

This project contains the front-end for the Cobra UI plugin in pntOS-Cobra.

The front-end consists of [Vue](https://vuejs.org) components which are compiled into a
`dist/` directory containing `index.html` and an `assets/` directory which contains all
javascript, CSS, and other static assets for the Cobra UI plugin to serve in downstream
projects.

These compiled components are packaged such that if the `pntos-cobra-frontend` package
is in the Python environment, the following will return the path to the `dist/`
directory for easy deployment in downstream projects:

```sh
python -c "from pntos_cobra_frontend import get_dist_path; print(get_dist_path())"
```

**NOTE:** This project has a build-time dependency on `nodejs>=20.19.0`. If not installing
from a wheel (e.g., [editable install](#editable-install) or via git URL), Node.js is
required for expected behavior. If it is not available, the build system will fail
gracefully and no frontend assets will be built.

## Build Locally

To build the Vue components into a `dist/` folder locally, first set up the Python
environment:

```sh
uv sync
```

Then build the frontend:

```sh
uv run rebuild-cobra-frontend
```

## Development Instructions

When developing this project in tandem with the `pntos-cobra` repository (or other
downstream repositories), in order to avoid a longer development cycle of pushing and
pulling changes in this project, there are a few tools to help.

### Editable Install

To work on the frontend while developing in a downstream project, configure an editable
install in the downstream project's `pyproject.toml` (assuming both project workspaces
share the same parent folder):

```diff
 [project]
 dependencies = [
     # ... other dependencies
-    "pntos-cobra-frontend>=2.1.0",
+    "pntos-cobra-frontend",
 ]

[tool.uv.sources]
+pntos-cobra-frontend = { path = "../pntos-cobra-frontend", editable = true }
```

Then sync the downstream project:

```bash
cd path/to/pntos-cobra  # or your downstream project
uv sync
```

The frontend will be built automatically during the initial sync and installed in
editable mode. Python code changes in `pntos-cobra-frontend` will be immediately
reflected without reinstalling.

To revert back to using the published wheel from the package registry, simply reverse
the above diff then run `uv sync --no-cache` to reinstall from the registry.

### Rebuild Command

When you make changes to Vue components or other frontend source files (`.vue`, `.ts`,
`.js`, etc.), you need to rebuild the frontend assets. From your downstream project:

```bash
rebuild-cobra-frontend
```

This command:
1. Finds the `pntos-cobra-frontend` source repository
2. Runs `npm install` and `npm run build`
3. Copies the built assets to the installed package location

The rebuilt assets will be immediately available to your downstream application without
needing to reinstall the package.