smartvm/readme.hints.md

# Project Hints

## Architecture
- Wraps Amazon Firecracker VMM using HTTP-over-Unix-socket API
- Uses `@push.rocks/smartrequest` with URL format `http://unix:<socket>:<path>` for socket communication
- Uses `@push.rocks/smartshell` `execStreaming()` to manage Firecracker child processes
- Uses `@push.rocks/smartexit` for cleanup on process exit
- `BaseImageManager` downloads Firecracker CI demo artifacts or hosted project manifests into `/tmp/.smartvm/base-images` by default
- Base image cache keeps 2 bundles by default and warns before evicting older bundles
- Hosted manifest examples live in `assets/base-images/`
- VM runtime files default to `/dev/shm/.smartvm/runtime` when available
- Writable drives are staged into per-VM runtime storage by default and removed during cleanup; use `ephemeral: false` only for explicit persistence

## Key API Patterns
- SmartRequest: `SmartRequest.create().url(...).json(body).put()` — response has `.status`, `.ok`, `.json()`
- Smartshell: `shell.execStreaming(cmd)` returns `{ childProcess, terminate(), kill(), finalPromise }`
- SmartExit: `smartExit.addProcess(child)`, `smartExit.addCleanupFunction(fn)`, `smartExit.killAll()`

## Firecracker API
- Pre-boot config: PUT /boot-source, PUT /machine-config, PUT /drives/{id}, PUT /network-interfaces/{id}
- Start: PUT /actions { action_type: "InstanceStart" }
- Pause/Resume: PATCH /vm { state: "Paused" | "Resumed" }
- Stop: PUT /actions { action_type: "SendCtrlAltDel" }

## Integration Testing
- Default `pnpm test` skips real Firecracker boot testing
- Set `SMARTVM_RUN_INTEGRATION=true` to run the opt-in boot test
- `SMARTVM_BASE_IMAGE_PRESET` supports `latest` and `lts`; default is `latest`
- Hosted/project-owned bundles use `baseImageManifestUrl`, `baseImageManifestPath`, `manifestUrl`, or `manifestPath`