types.lua

--- Props passed to `machine:start()` and `machine:create_start_command()`
---@class LuaShipStartProps
---@field name? string          Optional image name. If nil, a SHA-256 hash of the Dockerfile is used.
---@field rebuild? boolean      Whether to rebuild the image before running (default: true)
---@field flags? string[]       Extra flags forwarded to `docker/podman run` (e.g. `"--rm"`, `"-d"`)
---@field volumes? string[][]   Volume mounts — each entry is a two-element array `{host_path, container_path}`
---@field command? string|string[]  Command(s) to execute inside the container via `sh -c`


--- Represents a container image that is being assembled and can be started
---@class LuaShipMachine
---@field provider "podman"|"docker"  Container runtime used to build and run the image
---@field docker_file string          Accumulated Dockerfile content
---@field quiet boolean               When true, build output is suppressed (redirected to /dev/null)
---@field cache_folder string         Directory where temporary Dockerfiles are stored (default: `/tmp`)
---@field add_comptime_command fun(command:string)          Appends a `RUN` instruction to the Dockerfile
---@field add_runtime_command fun(command:string)           Appends a `CMD` instruction to the Dockerfile
---@field copy fun(host_data:string,dest_data:string)       Appends a `COPY` instruction to the Dockerfile
---@field env fun(name:string,value:string)                 Appends an `ENV` instruction to the Dockerfile
---@field save_to_file fun(filename:string)                 Writes the current Dockerfile to `filename`
---@field build fun(name?:string):string                    Builds the container image; returns the image name
---@field create_start_command fun(props:LuaShipStartProps):string  Constructs and returns the `run` command string
---@field start fun(props:LuaShipStartProps)                Builds the image (if needed) and runs the container


--- Main LuaShip API — the object returned by `require("LuaShip")`
---@class LuaShip
---@field create_machine fun(start_image:string):LuaShipMachine  Creates a new machine from the given base image
---@field open fun(filename:string,mode:string):file*            Opens a file; wraps `io.open`
---@field os_execute fun(command:string):boolean                 Executes a shell command; wraps `os.execute`
---@field os_remove fun(filename:string)                         Removes a file; wraps `os.remove`
---@field error fun(err:string)                                  Raises an error; wraps `error()`