Metadata-Version: 2.4
Name: maestro-install
Version: 0.1.6
Summary: One-shot interactive bootstrap for a CARE development workspace.
Project-URL: Homepage, https://github.com/Glazkoff/care-install
Project-URL: Repository, https://github.com/Glazkoff/care-install
Project-URL: Issues, https://github.com/Glazkoff/care-install/issues
Keywords: bootstrap,care,carl,gigaevo,mage,wizard
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# maestro-install

One-line bootstrap for a CARE development workspace.

Clones every repo the CARE TUI depends on (`care`, `gigaevo-platform`,
`gigaevo-memory`, `gigaevo-client`, `carl-experiments`, `carl-mage`) into
a directory of your choice and checks out the branch each component is
currently developed on.

## TL;DR — run from anywhere with `uvx`

If you have [`uv`](https://docs.astral.sh/uv/) installed, you don't need to
clone this repo at all. Run:

```bash
uvx maestro-install
```

That fetches the latest `maestro-install` from PyPI into an isolated, cached
environment and launches the interactive wizard. The wizard asks where to
put the workspace, how each backing service should be provisioned (local
docker stack vs. already-running remote), collects your MAGE provider /
key / model, clones whatever you picked "local", writes `<workspace>/.env`,
and can bring the docker stacks up for you.

Re-run `uvx maestro-install` any time — every prompt defaults to whatever the
previous run wrote, so it doubles as a config editor. To force a fresh
download of the latest release, add `--refresh`:

```bash
uvx --refresh maestro-install
```

To pin a specific version:

```bash
uvx --from 'maestro-install==0.1.1' maestro-install
```

## Requirements

- `git` in `PATH`
- [`uv`](https://docs.astral.sh/uv/) (handles Python + PyYAML automatically
  via the script's inline dependencies)

## Quick start — interactive wizard

The fastest path to a working CARE setup is the wizard. It asks how
each service should be provisioned (local docker stack vs. an
already-running remote), collects the required `.env` values
(MAGE provider + key + model, optional Tavily / Langfuse), clones
whatever you picked "local", writes `<workspace>/.env`, and can bring
the docker stacks up for you.

```bash
make wizard DIR=~/Development/care-workspace
# or:
uv run wizard.py
```

It probes `uvx care` and falls back to a local CARE clone if PyPI
can't satisfy it. Re-run any time — every prompt defaults to whatever
the previous run wrote to `.env`.

At the end the wizard offers to install a system-wide **`care`**
command (a small shim symlinked into `~/.local/bin`). Once it's on
your PATH you can run `care` from any directory — the shim cd's
into the workspace so `.env` is loaded, and dispatches to either
`uvx care` or the local clone depending on what you chose.

State the shim reads lives at `~/.config/care-install/state`.

### Preset files and unattended (fast) install

Pass a **preset file** of `CARE_*` variables so you don't have to type
answers — every prompt is pre-filled from it (you can still hit Enter
through them). The preset is a `.env`-style `KEY=VALUE` file or a YAML
mapping (nested keys join with `__`); see `preset.example.yaml` /
`preset.example.env`.

```bash
# pre-fill the prompts from a preset, walk through interactively
uv run wizard.py --preset preset.example.yaml
```

Add `--fast` (aka `-y` / `--yes`) for a fully **unattended** install —
no prompts at all, every default accepted, then it clones, writes
`.env`, and brings the stacks up:

```bash
uv run wizard.py --preset my-preset.yaml --fast
```

In fast mode a required value with no default (the MAGE API key) aborts
with a clear message, so make sure your preset sets `CARE_MAGE__API_KEY`.
The preset path can also come from `CARE_INSTALL_PRESET`, and it may set
`CARE_DEFAULTS__UI_LANGUAGE` to pick the language — that's CARE's own
variable, so it drives both the wizard and the CARE TUI.

**Export a preset from the current setup** — the inverse direction. Pick
**Export preset** from the menu, or run `export`, to dump your live
`.env` (plus the current language) into a reusable preset file. The
extension picks the format (`.yaml`/`.yml` → YAML, anything else →
`.env`):

```bash
uv run wizard.py export -o my-preset.yaml
# then on another machine / for someone else:
uv run wizard.py --preset my-preset.yaml --fast
```

The exported file is written `chmod 600` and **contains your API keys**,
so keep it private.

### Removing CARE (uninstall)

Pick **Delete setup** from the wizard menu, or run it directly, to wipe
every local trace of CARE — it stops and removes the docker stacks
(containers, volumes and the images compose built), deletes the
workspace / `~/.care`, removes the `care` shim, and clears the config:

```bash
uv run wizard.py uninstall          # asks to confirm first (default: no)
uv run wizard.py uninstall --yes    # unattended (no confirmation)
```

## Manual usage

```bash
make prepare DIR=~/Development/care-workspace
```

Or call the script directly:

```bash
uv run prepare.py ~/Development/care-workspace
```

Re-running is idempotent: existing clones are fetched, switched to the
configured branch, and fast-forwarded.

Every run finishes with a verification pass that checks each repo
exists, is a git repo, sits on the configured branch, and points at
the expected origin. The script exits non-zero if anything fails.

Run the check on its own at any time:

```bash
make verify DIR=~/Development/care-workspace
# or: uv run prepare.py ~/Development/care-workspace --verify-only
```

Override the config path with `--config /path/to/repos.yaml`.

## Running services

`care` talks to GigaEvo Memory (`localhost:8002`) and GigaEvo
Platform (`localhost:8000`). Bring both stacks up locally with:

```bash
make up DIR=~/Development/care-workspace
```

This runs `docker compose -f <file> up -d` for every repo in
`repos.yaml` that declares a `compose` entry. Stop, inspect, tail logs,
or restart the same set:

```bash
make down DIR=~/Development/care-workspace
make ps   DIR=~/Development/care-workspace
make logs DIR=~/Development/care-workspace
make restart DIR=~/Development/care-workspace
```

Target a single repo with `--only`, or run in the foreground:

```bash
uv run services.py ~/Development/care-workspace up --only gigaevo-memory
uv run services.py ~/Development/care-workspace up --no-detach
```

## Global `c-*` commands

For quick access from any directory, install the wrapper scripts in
[`bin/`](./bin) into `~/.local/bin` (or another PATH dir):

```bash
make install-cli                 # symlinks bin/c-* into ~/.local/bin
make install-cli BIN=~/bin       # or a custom location
```

Make sure that directory is on `PATH` (e.g. `export
PATH="$HOME/.local/bin:$PATH"` in `~/.zshrc`). Set the workspace once:

```bash
export CARE_WORKSPACE=~/Development/care-workspace
```

Then from anywhere:

| Command       | Effect                                |
| ------------- | ------------------------------------- |
| `c-up`        | bring up all docker stacks            |
| `c-down`      | stop all docker stacks                |
| `c-ps`        | status of all stacks                  |
| `c-logs`      | tail logs across all stacks           |
| `c-restart`   | restart all stacks                    |
| `c-mem-up`    | GigaEvo Memory only — up              |
| `c-mem-down`  | …down                                 |
| `c-mem-ps`    | …status                               |
| `c-mem-logs`  | …logs                                 |
| `c-mem-restart` | …restart                            |
| `c-plat-up`   | GigaEvo Platform only — up            |
| `c-plat-down` | …down                                 |
| `c-plat-ps`   | …status                               |
| `c-plat-logs` | …logs                                 |
| `c-plat-restart` | …restart                           |
| `c-mage`      | print MAGE repo path + git status (MAGE is in-process, no docker) |
| `c-ws`        | print the resolved workspace path     |

All wrappers forward extra arguments to the underlying
`services.py` / `docker compose` call:

```bash
c-mem-logs -f                      # follow logs
c-plat-up --no-detach              # foreground
c-dev mem up --only gigaevo-memory # explicit dispatcher form
```

Uninstall with `make uninstall-cli` (respects the same `BIN=` override).

## Configuration

Origins and branches live in [`repos.yaml`](./repos.yaml). Each entry:

```yaml
- name: <local directory name>
  origin: <git remote url>
  branch: <branch to check out>
  compose:                      # optional
    - <path/to/docker-compose.yml relative to the repo root>
```

Edit the file to add a repo, pin a different branch, point at a fork,
or change which compose files `make up` brings online.
