initial

readme.hints.md

@@ -0,0 +1,18 @@
+# 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
+
+## 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" }