# ExecuteSoft CLI

`exe` is the Rust command-line tool for ExecuteSoft repository automation. Keep
workflow logic here instead of adding new Bash or Makefile implementations.

## Source Layout

- `src/main.rs`: binary entrypoint only.
- `src/cli.rs`: Clap command, subcommand, and argument definitions.
- `src/commands.rs`: top-level command dispatch, sync, release, and deployment.
- `src/service.rs`: service generation, service discovery, and compliance checks.
- `src/gateway.rs`: gateway route generation wrappers and route source validation.
- `src/db.rs`: database migration helper commands.
- `src/dev.rs`: service-local dev, explicit compose helpers, and polling watch helper.
- `src/service_local.rs`: service-only checkout setup and dev runner.
- `src/util.rs`: shared repository path, process, and Make variable helpers.
- `src/tests.rs`: focused CLI, generator, compliance helper, and help-output tests.

## Local Use

From the repository root, build the local binary:

```bash
make cli
```

Run it from `bin/exe`:

```bash
./bin/exe service check-all
./bin/exe service create --name recommendation-engine --domain core --template rust
./bin/exe gateway generate
./bin/exe setup
./bin/exe dev
./bin/exe dev up DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
```

Run without building `bin/exe`:

```bash
cargo run -p executesoft --bin exe -- service check-all
```

Install for the current user:

```bash
cargo install --path tools/exe
exe service check-all
```

If `exe` is not found after installation, add Cargo binaries to the shell path:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

## Use Cases

### Check Service Compliance

Use this before committing service or template changes:

```bash
exe service check services/core/auth
exe service check-all
```

`check-all` validates service roots under `services/` and certified template
skeletons under `tools/templates/`.

### Service-Only Checkout

Use this flow for developers who only receive one service repository or folder:

```bash
git clone <service-repo>
cd <service-repo>
exe setup
exe dev
```

`exe setup` walks upward to find `service.yaml`, validates the service contract,
runs the local generator when one exists, downloads language dependencies, and
starts `development/compose.dev.yml` dependencies. Pass setup variables as
`key=value` pairs when needed:

```bash
exe setup SKIP_DOCKER=1
exe setup SKIP_DEPS=1
exe setup SKIP_GENERATE=1
```

Plain `exe dev` runs inside a service checkout. It starts service-local Docker
dependencies, loads `configs/app.env.example`, watches the service directory,
and runs the command implied by `service.yaml`:

- Go: `go run ./cmd/server`
- Rust: `cargo run`
- TypeScript: `bun run dev` or `npm run dev` when a `dev` script exists
- Python: `python -m src.server`

When several services run locally at once, `exe` assigns stable per-service
host ports for Postgres, Redis, NATS, and NATS monitoring, then rewrites
localhost URLs from `configs/app.env.example` in the current process. Override
ports explicitly when needed:

```bash
POSTGRES_PORT=15432 REDIS_PORT=16379 NATS_PORT=14222 exe dev
```

### Create A Service

Use the generator instead of copying service folders manually:

```bash
exe service create \
  --name recommendation-engine \
  --domain core \
  --template rust \
  --owner-team team-recommendation-engine
```

The generator copies the selected certified template, replaces template tokens,
creates the service folder, and creates the shared protobuf contract when the
local service contract exists.

### Run Service Make Targets

Use service names for common operations:

```bash
exe service test auth
exe service build gateway
exe service generate notification
exe service clippy services/core/auth
```

When a service name is ambiguous, pass the service path.

### Manage Gateway Routes

Generated gateway artifacts must come from route source files and protobufs:

```bash
exe gateway route create --service auth
exe gateway route from-proto --service auth
exe gateway route entry --service auth --rpc Login
exe gateway generate
```

Do not manually edit generated route artifacts.

### Run Local Development Helpers

```bash
exe dev
exe dev up DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev all DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev down DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev logs DEV_COMPOSE_FILE=services/core/auth/development/compose.dev.yml
exe dev watch -- cargo run
```

Plain `exe dev` is the normal service-local flow. Compose subcommands require
an explicit `DEV_COMPOSE_FILE`. Use `dev watch` for simple polling reloads in
services that need it.

### Release And Deployment

`release` and deployment commands keep repository sync first-class:

```bash
exe sync
exe release tag=latest
exe release-sync
exe deploy kubernetes tag=latest
exe deploy docker tag=latest
exe deploy migrations
exe deploy backup-now
exe deploy release-sync
exe deploy reload-caddy
exe deploy restart-cdn
exe deploy recreate CONTAINER=cdn
```

`deploy kubernetes` runs `sync` before delegating to the deployment Make target.

## crates.io Publishing

The crate is publish-enabled in `tools/exe/Cargo.toml`:

```toml
publish = true
```

To publish, first update `tools/exe/Cargo.toml` with public package metadata:

```toml
[package]
name = "executesoft"
version = "0.1.0"
edition = "2024"
rust-version = "1.95"
description = "ExecuteSoft repository automation CLI"
license = "MIT"
repository = "https://github.com/execute-soft/executsoft"
readme = "README.md"
publish = true
```

The package name is global on crates.io. If `executesoft` is unavailable,
choose another package name. The installed binary can still be named `exe`
because the binary target controls the command name:

```toml
[[bin]]
name = "exe"
path = "src/main.rs"
```

Authenticate and verify:

```bash
cargo login
cargo package --manifest-path tools/exe/Cargo.toml --list
cargo publish --manifest-path tools/exe/Cargo.toml --dry-run
```

Publish:

```bash
cargo publish --manifest-path tools/exe/Cargo.toml
```

After publishing, install from crates.io:

```bash
cargo install executesoft
exe service check-all
```

For private company tooling, prefer local or private-registry installation until
the command surface and package metadata are stable.
