Metadata-Version: 2.4
Name: lucore
Version: 0.2.1
Summary: A real distributed CLI/runtime with workers, brokered execution, and custom commands.
Author: Lucas Smith
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 distributed CLI/runtime for local commands, project workflows, and remote execution.

It gives you:

- `lucore hello`: project overview and common commands
- `lucore new`: create a project
- `lucore dev`, `lucore build`, `lucore check`, `lucore start`: default project workflows
- `lucore tasks` and `lucore make`: task aliases
- `lucore check ...`: direct checks such as `lucore check ports`
- `lucore do`, `lucore find`, `lucore clean`, and `lucore fix`: common operations
- `lucore scan`, `lucore health`, and `lucore service`: operations and runtime commands
- `lucore local-ip`, `lucore wifi`, `lucore share`, `lucore where`, `lucore open`, `lucore stop`: network and utility commands
- `lucore monitor`, `lucore tail`, `lucore backup`, `lucore sync`, `lucore ssh`, `lucore git`, `lucore db`: more built-in power
- `lucore http`, `lucore json`, `lucore csv`, `lucore image`, `lucore cron`, `lucore watch`: everyday helpers
- `lucore process`, `lucore download`, `lucore archive`, `lucore hash`, `lucore uuid`, `lucore time`, `lucore sysinfo`: system utility commands
- `lucore deploy`, `lucore plugin`, `lucore cloud`, `lucore docker`, `lucore ai`: even more built-in power
- `lucore ports`, `lucore memory`, `lucore disk`, `lucore workers`, `lucore jobs`, `lucore scripts`: direct shortcuts
- `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 hello
lucore tasks
lucore make build
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
```

Beginner-friendly project flow:

```bash
lucore new my-app
cd my-app
lucore status
lucore dev
lucore build
lucore check
```

Plain-English checks:

```bash
lucore check ports
lucore check memory
lucore check scripts
lucore check tasks
lucore check all
```

Simple everyday commands:

```bash
lucore ports
lucore local-ip
lucore wifi
lucore share 3000
lucore where node
lucore stop port 3000
lucore find text "hello"
lucore do start
lucore clean build
lucore fix deps
lucore make app my-app
lucore health
lucore scan ports
lucore service start ip
lucore monitor cpu
lucore http get https://example.com
lucore json pretty package.json
lucore csv columns data.csv
lucore image info photo.png
lucore process port 3000
lucore download https://example.com page.html
lucore archive create app.zip my-app/
lucore archive extract app.zip --to ./out
lucore hash package.json
lucore uuid --count 3
lucore time utc
lucore sysinfo
lucore cron example "*/5 * * * *" "lucore check ports"
lucore watch --seconds 5 lucore check ports
lucore tail /var/log/system.log
lucore backup my-folder/ my-backup/
lucore ssh user@host
lucore git status
lucore db tables app.db
lucore plugin add greet "echo hi"
lucore do greet
lucore ai prompt deploy
```

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`.

## Common Commands

Examples:

```bash
lucore local-ip
lucore wifi
lucore share 3000
lucore check ports
lucore check memory
lucore scan text lucore
lucore find file cli
lucore make ip
lucore do greet
lucore service status
lucore process list node
lucore http head https://example.com
lucore json query package.json '.name'
lucore hash "hello" --string
lucore time now
```

## 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.
