koki-develop/clive

Purpose and Entrypoints

cLive is a Go CLI that automates terminal demonstrations: it launches a terminal through ttyd, opens it in a browser, and replays configured typing, key, pause, delay, and screenshot actions. Process entry is main.go; command wiring and user-facing commands are in cmd/root.go, cmd/start.go, cmd/init.go, cmd/validate.go, and cmd/notify.go.

CLI Command Boundary

The CLI separates configuration lifecycle from execution:

• init creates a starter clive.yml.

• validate parses and checks a configuration without running it.

• start drives the terminal/browser automation workflow.

• Shell completion is exposed from the root command.

Command implementation is concentrated in cmd/, while reusable CLI initialization and embedded starter assets live in internal/cli/cli.go, internal/cli/init.go, and internal/cli/static/clive.yml.

Configuration Model and Validation

YAML configuration is the primary input boundary. It contains global settings (login command, visual/browser dimensions, headless mode, screenshot directory, default speed) and an ordered action list. The domain model and validation rules are in internal/config/config.go, internal/config/settings.go, internal/config/action.go, internal/config/key.go, and internal/config/error.go. This layer normalizes action forms such as type/key/ctrl/sleep/pause/screenshot and rejects invalid action or key definitions before runtime automation begins. schema.json is the machine-readable contract for the config format.

Execution Pipeline

start likely follows this control flow: load and validate config → allocate a local endpoint → launch ttyd with the configured login shell → open a configured browser session against the terminal URL → execute actions in declaration order → optionally pause before exit. Terminal-server integration is isolated in internal/ttyd/ttyd.go; local listener allocation is in internal/net/listener.go. This is a local-process orchestration tool rather than a hosted service.

Browser and Terminal Automation

The browser boundary is encapsulated by internal/browser/browser.go. It applies settings including browser binary, viewport dimensions, font presentation, and headless mode, then sends keyboard-oriented actions to the ttyd-rendered terminal and captures screenshots. ttyd is an external runtime prerequisite (v1.7.4+); a compatible installed browser is also required, with an optional explicit binary path. The terminal command itself is user-controlled through settings.loginCommand.

UI, Pause, and Action Progression

Interactive pause behavior and action progression are represented as a UI model/update/view split in internal/ui/model.go, internal/ui/update.go, internal/ui/view.go, and internal/ui/init.go. This forms the human-interaction boundary: automated actions can stop for Enter before continuing, while skipPauseBeforeQuit controls the final pause. Styling is centralized in internal/styles/styles.go.

State, Files, and Delivery

Runtime artifacts include generated config files and screenshots; filesystem handling is centralized in internal/util/files.go. internal/cache/cache.go and internal/cache/store.go provide a persistence/cache boundary for execution-related state. The project is built and released as a Go binary, with release packaging defined in .goreleaser.yaml; CI and release automation run through .github/workflows/ci.yml and .github/workflows/release-please.yml.