Environment Bootstrapping
Palyra uses a multi-layered bootstrapping process to handle Rust toolchains, Node.js workspaces, and system-level dependencies. The primary entry point for developers is theMakefile or justfile, which wraps the palyra-cli diagnostic tools.
The Doctor Command
Before development begins, the environment must pass a strict validation check. This is implemented via thepalyra doctor command Makefile#7-10.
- Strict Mode: The
--strictflag ensures that all required dependencies (Rust, Cargo, Protoc, etc.) are present and compatible Makefile#10. - Integration: Both
make devandjust devtriggervalidate-env, which executes the doctor check before attempting a build Makefile#13-16, justfile#13-17.
Web Workspace Setup
The web frontend and desktop UI rely on a unified JavaScript workspace.vp install: This command is used to materialize the root JS workspace Makefile#17, justfile#20.- Cleanroom Builds: For a fresh state,
make web-cleanroomremovesnode_modulesand re-installs dependencies before running CI checks Makefile#89-92.
Setup Flow Diagram
The following diagram illustrates the transition from a fresh clone to a ready development environment. Development Environment Bootstrapping Flow Sources: Makefile#7-19, justfile#7-22, crates/palyra-cli/src/commands/setup.rs#1-20Development Workflow and Task Runner
Palyra provides a consistent interface for common tasks viamake and just. These tools manage the lifecycle of the daemon, CLI, and web apps.
Key Makefile Targets
| Target | Description | Implementation |
|---|---|---|
make dev | Full bootstrap and build | validate-env + build Makefile#16 |
make test | Run all workspace tests | cargo test --workspace --locked Makefile#34-36 |
make lint | Run clippy with warnings as errors | cargo clippy ... -D warnings Makefile#20-21 |
make protocol | Validate and generate Protobuf stubs | validate-proto.sh + generate-stubs.sh Makefile#29-33 |
make security | Run local security audit | cargo audit + cargo deny + pattern scans Makefile#56-62 |
Protocol Management
Palyra uses Protobuf for cross-process communication (daemon to browser, daemon to CLI). Theprotocol target ensures that Rust stubs are synchronized with .proto definitions Makefile#23-33, justfile#97-107.
Sources: Makefile#1-164, justfile#1-171
Testing and Quality Assurance
The testing strategy is divided into unit tests, integration tests, and deterministic “soak” tests.Deterministic Core Tests
Thedeterministic-core suite runs agents in a controlled environment to verify orchestration logic without network flakiness Makefile#97-98.
- Fixtures: Developers can update expected outcomes using
make deterministic-fixtures-updateMakefile#141-142. - Soak Testing: For stress testing,
deterministic-soakruns extended scenarios Makefile#132-133.
Regression and Smoke Tests
- CLI Regression: Validates CLI command outputs against known snapshots Makefile#103-104.
- Install Smoke: Tests the installation scripts in a clean environment Makefile#106-111.
- Performance Smoke: Monitors latency and resource usage Makefile#135-136.
Pre-push Check Pipeline
To maintain high CI pass rates, Palyra enforces a local pre-push hook. This hook executesscripts/run-pre-push-checks.sh scripts/run-pre-push-checks.sh#1-5.
Profiles
The pipeline supports two execution profiles via thePALYRA_PRE_PUSH_PROFILE environment variable scripts/run-pre-push-checks.sh#5:
- Fast (Default): Focuses on formatting, high-risk patterns, and the deterministic smoke suite scripts/run-pre-push-checks.sh#49-69.
- Full: Adds
clippy, full workspace tests, and protocol validation scripts/run-pre-push-checks.sh#71-102.
Security and Hygiene Guards
The pipeline includes several specialized scripts to prevent common mistakes:- Artifact Hygiene:
check-runtime-artifacts.shensures temporary files aren’t committed scripts/run-pre-push-checks.sh#55-56. - Local-only Guard:
check-local-only-tracked-files.shblocks accidental tracking of internal roadmaps or private configs scripts/check-local-only-tracked-files.sh#1-24. - Vendored Artifact Guard:
check-no-vendored-artifacts.shpreventsnode_modulesor generated SBOMs from entering the index scripts/check-no-vendored-artifacts.sh#1-63. - High-Risk Pattern Scan: Searches for hardcoded secrets or unsafe code patterns scripts/run-pre-push-checks.sh#67-68.