Metadata-Version: 2.4
Name: bluecopa-robot
Version: 0.1.1
Summary: Scaffold a new Bluecopa RPA robot — minimal, runnable, with docs-for-Claude baked in.
Author: Bluecopa
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# bluecopa-robot

Scaffold a new Bluecopa RPA robot — minimal, runnable, with **docs-for-Claude** baked in.

The robot equivalent of `create-bluecopa-react-app`: one command lays down a runnable
robot skeleton **and** the `CLAUDE.md` + `docs/building-a-bluecopa-robot.md` that tell a
human or Claude exactly how to build and deploy it.

## Install (one time)

**Prerequisite:** Python 3.9+ (the same version the robots run on).

```bash
pip install bluecopa-robot
```

That's it — the `bluecopa-robot` command now works from anywhere. Check it:

```bash
bluecopa-robot --version      # prints: bluecopa-robot 0.1.0
```

> Prefer an isolated install? `pipx install bluecopa-robot` — same result,
> the command just lives in its own environment. Update later with
> `pipx upgrade bluecopa-robot` (or `pip install --upgrade bluecopa-robot`).

## Use — create a robot

The one command you'll use is `bluecopa-robot new <name>`. It creates a **new folder named
`<name>`** containing a complete, ready-to-run robot.

```bash
bluecopa-robot new invoice_splitter
```

That creates an `invoice_splitter/` folder in your current directory. Run this with **no
flags** and it will *ask you* three things (title, one-line description, and whether the
robot needs GCS), then generate the robot from your answers.

If you'd rather not be asked, pass the answers as flags:

```bash
bluecopa-robot new invoice_splitter --gcs --title "Invoice Splitter" --description "Splits invoices"
```

### The flags

| Flag | What it does |
|------|--------------|
| *(the name)* | `invoice_splitter` becomes the folder name, the module `rpa/invoice_splitter.py`, and the class `InvoiceSplitterRobot`. You can type `"Invoice Splitter"` too — it's converted to `invoice_splitter`. |
| `--gcs` | Include Google Cloud Storage support: adds `rpa/gcs.py` (read/write GCS with ambient auth) and `google-cloud-storage` to requirements. Use this when the robot reads or writes files in GCS. |
| `--no-gcs` | The opposite — a bare robot with no storage code or dependency. Use this when the robot doesn't touch GCS. |
| `--title "..."` | The human name shown in the platform's setup form (e.g. "Invoice Splitter"). |
| `--description "..."` | A one-line description, used in the generated README and `CLAUDE.md`. |
| `--dir <path>` | *Where* to create the robot folder. Defaults to your current directory. |

`--gcs` and `--no-gcs` are opposites — pass at most one. If you pass neither and you're in
an interactive terminal, it asks; otherwise it defaults to **no GCS**.

### The three examples explained

```bash
bluecopa-robot new invoice_splitter
```
→ Creates `invoice_splitter/` here, **asking you** for title, description, and GCS.

```bash
bluecopa-robot new invoice_splitter --gcs --title "Invoice Splitter" --description "Splits invoices"
```
→ Creates `invoice_splitter/` here **with** the GCS helper, and no questions — the title and
description are supplied as flags.

```bash
bluecopa-robot new invoice_splitter --no-gcs --dir ../robots
```
→ Creates the robot **without** GCS, in the `../robots` folder (one level up) instead of the
current directory.

After generating, `cd` into the new folder and follow the "Next steps" the command prints
(install deps, implement `run_robot`, test locally) — also in the robot's own `README.md`.

## What you get

A standalone `<name>/` folder:

- `main.py`, `Dockerfile` (`python:3.9-slim`), `requirements.txt`, the SDK wheel in `libs/`
- `rpa/<name>.py` — a **runnable** `run_robot` stub (writes a placeholder output) with
  `_unwrap_data`
- `rpa/spec.json`, `secrets/*.sample.json`
- `rpa/gcs.py` **only** with `--gcs` (ambient-auth GCS helper) + `google-cloud-storage`
- `CLAUDE.md` + `docs/building-a-bluecopa-robot.md` — the runtime contract, config/spec
  traps, filebox gotchas, and a client-agnostic deploy guide

It is **client-agnostic**: no client repo name, registry, or ECR path is ever emitted.

## Maintaining the template

- The vendored SDK wheel lives at `src/bluecopa_robot/_assets/`. When the SDK updates,
  replace it and bump the filename in `generator.py` (`WHEEL_NAME`) + the `Dockerfile`
  template.
- Template files live under `src/bluecopa_robot/_templates/` (each ends `.tmpl`; the
  generator strips that and substitutes `{{placeholders}}`). `requirements.txt` is
  generated in code, not templated.

## Test

```bash
python -m pytest        # or: python tests/test_generate.py
```
