Metadata-Version: 2.4
Name: lucore
Version: 0.1.0
Summary: A real distributed CLI/runtime with workers, brokered execution, and custom commands.
Author: OpenAI Codex
Keywords: cli,distributed,runtime,broker,worker
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Lucore

`lucore` is a real, working distributed CLI/runtime that installs with `pip3`.

It gives you:

- `lucore broker`: the central scheduler
- `lucore worker`: a machine that executes jobs
- `lucore run` and `lucore exec`: run raw commands locally or on the cluster
- `lucore submit`: queue distributed work without waiting
- `lucore task`: define and run project tasks from `lucore.toml`
- `lucore dev`: run the project dev task
- `lucore invoke`: run named commands from `lucore.toml`
- `lucore ps`, `lucore inspect`, and `lucore logs`: inspect jobs
- `lucore cluster workers` and `lucore cluster jobs`: inspect cluster state
- `lucore config` and `lucore doctor`: inspect local project/runtime state

The transport is newline-delimited JSON over TCP, so workers can run on completely separate machines.

## Install

After publishing to PyPI:

```bash
pip3 install lucore
```

For local development from this directory:

```bash
pip3 install -e .
```

## Quick start

Start the broker:

```bash
lucore broker --listen 127.0.0.1:7000
```

Start a worker:

```bash
lucore worker --broker 127.0.0.1:7000 --name worker-a --label queue=build --label os=mac
```

Submit a raw remote command:

```bash
lucore run --broker 127.0.0.1:7000 --label queue=build --command "uname -a"
```

Run a local command:

```bash
lucore run --local --command "python3 --version"
```

Create a starter config:

```bash
lucore init
cat lucore.toml
```

Run project tasks:

```bash
lucore task list
lucore dev
lucore task run build --broker 127.0.0.1:7000
lucore task run test --broker 127.0.0.1:7000
```

Run a named command:

```bash
lucore invoke hello --broker 127.0.0.1:7000 there
lucore invoke python-version --local
```

Inspect recent work:

```bash
lucore ps --broker 127.0.0.1:7000
lucore cluster workers --broker 127.0.0.1:7000
lucore inspect <job-id> --broker 127.0.0.1:7000
lucore logs <job-id> --broker 127.0.0.1:7000
```

## lucore.toml

Example:

```toml
[project]
name = "my-app"

[tasks.dev]
run = "python3 -m http.server 3000 {args}"
mode = "local"

[tasks.build]
run = "echo building app && uname -a"
mode = "distributed"
labels = { queue = "build" }

[tasks.test]
run = "pytest -q {args}"
mode = "distributed"
labels = { queue = "test", os = "linux" }

[commands.hello]
shell = "echo hello from lucore {args}"
labels = { queue = "build" }
```

`{args}` is replaced with any extra arguments passed to `lucore task run` or `lucore invoke`.

## Current behavior

- Jobs queue until a matching worker is available.
- Labels route work to the right class of worker.
- Workers heartbeat every 5 seconds.
- If a worker disappears mid-job, the broker requeues that job.
- Tasks can run locally or distributed depending on config and flags.
- The broker keeps recent job history and stored logs in memory.
- Named commands are real config-driven commands, not fake placeholders.

## Next production steps

If you want to harden this into a serious runtime, the next upgrades are TLS/auth, persistent broker state, streaming logs, retries, and sandboxed execution.
