repo-commands

name	repo-commands
description	Repository command reference for the HostVault project. Contains all available just commands for building, testing, linting, and maintaining the codebase. Use this skill when you need to execute build commands, run tests, check code quality, or perform maintenance tasks on the HostVault Turbo monorepo.
metadata	{"author":"hostvault","version":"1.0","type":"repository-commands"}

HostVault Repository Commands

This skill provides access to all build, test, and maintenance commands for the HostVault project. The project uses just as the task runner with Turborepo for monorepo orchestration.

Quick Reference

# Building
just build                    # Build all artifacts
just build cli                # Build CLI only (Rust)
just build macos              # Build macOS app only (Swift)
just build --watch            # Build and watch for changes
just build cli --watch        # Build CLI with watch mode

# Testing & Quality
just test                     # Run all tests via turbo
just test --watch             # Run tests with watch mode
just static                   # Run static analysis (format + lint)
just static --fix             # Run static analysis with auto-fix
just doctor                   # Check environment health
just doctor --fix             # Check and fix environment issues

# Formatting
just format                   # Format code in-place
just format --check           # Check formatting without modifying

# Maintenance
just clean                    # Remove build artifacts
just clean --deep             # Deep clean (includes generated files)

# Help
just help                     # Show all commands

Detailed Command Reference

Build Commands

just build [variant] [--watch]

Builds the deploy artifacts. Uses Turborepo for efficient orchestration.

• variant: all (default), cli, or macos
• --watch: Enable watch mode for development

Examples:

just build                    # Build CLI + macOS app
just build cli                # Build CLI only
just build macos              # Build macOS app only
just build --watch            # Watch all
just build cli --watch        # Watch CLI changes only

Implementation Details:

• CLI uses cargo build --release (Rust)
• macOS app uses scripts/build_macos_app.sh (Swift/Xcode)
• Watch mode uses language-native watchers (cargo-watch for Rust, watchexec for Swift)

Test Commands

just test [--watch]

Runs the test suite via turbo test.

• Uses checksy configuration in test.checksy.yaml
• Executes turbo test command
• Integrates with CI/CD pipelines

Watch mode:

just test --watch             # Uses watchexec for file watching

Static Analysis

just static [--fix]

Runs static analysis checks including:

• Trailing whitespace detection (yaml/json files)
• Format checking (just format --check)
• Turbo lint (turbo lint)

With auto-fix:

just static --fix             # Runs format fix + lint

Configuration:

• Rules defined in static.checksy.yaml
• Format fix: just format

Doctor (Environment Check)

just doctor [--fix]

Checks environment health and prerequisites.

• Uses doctor.checksy.yaml configuration
• Verifies system dependencies
• Checks tool availability

Auto-fix:

just doctor --fix             # Attempt to fix issues automatically

Format Commands

just format [--check]

Formats code in the repository.

just format                   # Format in-place
just format --check           # Check only, don't modify

Clean Commands

just clean [--deep]

Removes build artifacts.

just clean                    # Standard clean
just clean --deep             # Deep clean + remove .schemas/*.json

Artifacts cleaned:

• dist/, build/, out/, target/
• node_modules/ (optional)
• .turbo/ cache
• Generated schema files (with --deep)

Turborepo Integration

The project uses Turborepo with these key commands:

turbo run build               # Build all packages
turbo run dev                 # Development mode with watchers
turbo run lint                # Lint all packages
turbo run test                # Test all packages
turbo run build --filter=cli  # Build CLI only
turbo run build --filter=macos-app  # Build macOS app only

Pipeline configuration: turbo.json

• build: Depends on ^build, outputs to dist/, target/release/, build/
• dev: Persistent, no cache, depends on ^dev
• lint: Depends on ^build
• test: Depends on ^build

Project Structure

hostvault/
├── apps/
│   ├── cli/              # Rust CLI (cargo)
│   └── macos-app/        # Swift macOS app (xcodebuild)
├── packages/
│   └── protocol/         # Shared protocol (Rust library)
├── scripts/
│   └── build_macos_app.sh
├── justfile              # Task definitions
├── turbo.json            # Turborepo config
└── *.checksy.yaml        # Checksy rules

Common Workflows

Development Workflow

just build cli --watch      # Start CLI in watch mode
# Make changes to apps/cli/src/
# Cargo automatically rebuilds on save

Pre-commit Check

just static                 # Run all static checks
just test                   # Run tests

Full Build

just clean                  # Clean previous builds
just build                  # Build all artifacts
just test                   # Run tests

CI/CD Pipeline

just doctor                 # Verify environment
just format --check         # Check formatting
just static                 # Static analysis
just build                  # Build artifacts
just test                   # Run tests

Exit Codes

Build and test commands follow these conventions:

• 0: Success
• 1: General error / Connection error (CLI)
• 2-14: Specific CLI error codes (see CLI.md)
• Non-zero: Command-specific errors

Troubleshooting

Issue: Build fails with "command not found"

• Fix: Run just doctor to check dependencies

Issue: Watch mode not detecting changes

• Fix: Check that cargo-watch (for CLI) or watchexec (for macOS) is installed

Issue: Turbo cache issues

• Fix: Run rm -rf .turbo/ or just clean --deep

Issue: Permission denied on socket (CLI)

• Fix: Check HostVault macOS app is running and socket path is correct

References

• Just documentation
• Turborepo documentation
• PRD: CLI Specification
• PRD: macOS App Specification