cedarcli

Start with the published documentation:

• cedarcli Manual explains repositories, Maven, builds, publication, and the native, hybrid, and Docker modes.
• Developer Install installs cedarcli as part of a source development environment.
• Docker Install installs cedarcli as part of a container deployment.
• CEDAR CLI Cheat Sheet is the compact command reference.

This README is for contributors to the CLI itself. The published manual is the user guide.

What This Repository Implements

cedarcli is a Python command-line coordinator for a multi-repository CEDAR installation. It invokes Git, Maven, npm, Docker Compose, and the native process controllers while preserving CEDAR's dependency order and deployment-mode boundaries. It is not a daemon and does not replace those underlying tools.

Backend test builds also guard their process boundary. cedarcli test status inventories orphaned embedded MongoDB processes, and cedarcli test cleanup terminates only mongod executables under .embedmongo; ordinary CLI and release Maven test tasks enforce the same check before and after they run.

The main implementation areas are:

• cedar.py registers the top-level command groups.
• org/metadatacenter/*.py defines the Typer command surfaces.
• org/metadatacenter/release_support/ owns release planning, state, package comparison, workspaces, version stamping, validation, Git integration, publication, preflight, and presentation in separate modules. release_train.py registers commands and explicitly re-exports the existing component API; components never import that command facade.
• org/metadatacenter/docker_support/ separates engine calls, deployment state, images, setup, lifecycle, health checks, and status reporting. train_support/ separates source surveys, GitHub workflow access, preflight, dispatch, and reporting. The existing worker classes delegate to these components with their original call signatures.
• org/metadatacenter/config/ and org/metadatacenter/model/ describe repositories, images, targets, and plans.
• org/metadatacenter/planner/, org/metadatacenter/executor/, and org/metadatacenter/worker/ translate commands into work and run it.
• org/metadatacenter/util/ contains shared environment, mode, build-train, Docker, and process safeguards.
• tests/ exercises command paths without starting a real CEDAR deployment.
• cli.sh is the shell wrapper the cedarcli alias sources, and the only one. It activates the repository virtual environment in a subshell, preserves the caller's working directory for build this and publish this, and returns the Python process's exit status without exiting the caller's shell. Setup failures stop before Python runs; only successful commands may consume a pending Git navigation record.

Release start, resume, and abandon hold an exclusive process lock in the release state directory for the whole operation, including preflight and retries. A competing modifying command refuses immediately; release status --watch remains available. The OS releases ownership when the command exits, including after a crash. The persistent release.lock file must not be deleted while a release command is running.

Estate-wide Git commands visit every selected repository and return a nonzero exit status if any repository fails. Their result records retain each repository's process exit code, including failures that produce no stderr. A failed status scan does not update git next navigation.

Shared streamed subprocess execution lives in util/ProcessRunner.py: run_process takes literal arguments, and run_shell takes one explicit script. Both return output lines with a returncode. Worker script lists run in order and stop at the first failed script; shell state is local to each script. Output preserves indentation and replaces invalid UTF-8 bytes. An interrupted reader kills its owned process group, reaps the child, and closes the pipe.

Each root CLI invocation binds an InvocationContext containing its environment, settings, repository/server catalogs, and task registries. Profile resolution updates that environment; subprocesses receive it explicitly. create_app() registers commands without host inspection, and importing cedar does not bootstrap a profile. GlobalContext, Util.cedar_home, and CedarCliSettings remain compatibility accessors rather than owners of mutable process state. Library callers can use with use_context(InvocationContext(environment=...)): or supply a context as the root application's obj. Calls made outside a bound context retain ambient library behavior. Change settings on context.settings, rather than assigning class attributes.

Contributor Setup

Python 3.10 is the minimum supported version (including Ubuntu 22.04 deployment hosts). CI tests Python 3.10 and 3.12. Git checkout supports Git 2.34.1; deployment does not require replacing the system Python or adding a newer Git package repository.

Frontend builds check the selected Node interpreter before installing dependencies or compiling. The build directory's .nvmrc supplies the exact version when present; otherwise the shared release-toolchain pin applies (currently 24.19.0). A mixed Java/frontend plan checks all enabled frontends before starting any task. Java-only plans and dry runs do not require Node. The CLI reports the required version, detected version and executable path on a mismatch; it does not install Node or change the host's default interpreter.

The installation guides establish CEDAR_HOME, clone the companion repositories, and create the normal alias. For work on cedarcli itself, create its isolated Python environment and install the runtime and test dependencies:

cd "$CEDAR_HOME/cedar-cli"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt pytest

Run the test suite from this repository:

python -m pytest tests -v

The tests expect cedar-development and cedar-docker-build beside cedar-cli, matching the normal $CEDAR_HOME layout. They mock external process and network work or use inspection-only controller paths; the CI suite does not start CEDAR.

Changing Commands

Keep command parsing in the command module and put orchestration in a planner or worker. Reuse the repository catalog and shared target models instead of restating repository, service, frontend, or image inventories. Mode checks belong at the command boundary so a new operation cannot silently cross from native ownership into Docker ownership, or the reverse.

When a user-facing command changes, update its tests, the cedarcli Manual, and the cheat-sheet generator. Regenerate assets/docs/cedar-cli.pdf and assets/docs/cedar-cli.png rather than editing those artifacts directly.

Native Restart Targets

Use cedarcli native restart microservice repo or restart frontend openview for one application, and restart microservices or restart frontends for a group. restart frontend split-frontends selects Workspace and Designer. restart all restarts all managed applications and leaves infrastructure running; bare restart retains that behavior. The old flat syntax, such as restart repo ui-openview, remains supported. Hybrid mode permits only frontend targets.

Design-token adoption

cedarcli check design-tokens reports shared-style debt and token dependency pins across the CEDAR frontends and the session page that cedar-cee-mcp serves. Use --strict to fail on new style findings, missing or stale baselines and invalid pins, --json for automation, --repo <path> to select one repository by its path under CEDAR_HOME, such as cedar-workspace or mcp/cedar-cee-mcp, and --prune-baseline after fixing existing findings. The implementation and CI contract live in cedar-design-tokens/tools/check_adoption.py; that repository's README explains exceptions, scope and rollout.

Build concurrency

cedarcli build --jobs 2 --workers 2 frontends schedules independent isolated repositories from their package and integration-test dependencies. Repository concurrency defaults to two; workers default to half the detected CPUs, at least one and capped at eight. Use --jobs 1 --workers 1 for serial diagnosis. Full frontend deployment and smoke gates remain mandatory. cedarcli build java uses Maven's dependency-aware module scheduling, with one reactor thread per detected CPU, at least one and capped at sixteen. It preserves the parent → libraries → project → clients order and serial tests within individual JVMs. Only one Maven reactor runs at a time, so its thread count follows the host, while frontend repository concurrency stays at two because each repository also spends its own worker budget. An explicit --jobs N sets both to N. Options belong before the build target. Command timings and task results are saved to $CEDAR_HOME/.cedar/build-reports/, including failures.

cedarcli test e2e --rest-workers 4 runs up to four independent REST smoke suites concurrently, followed by the browser smoke. The REST default is two workers; --rest-workers 1 restores serial suite execution. Global-state suites stay exclusive, all check-inventory and cleanup gates remain required, and the REST report includes per-suite and phase timings.