smelt.fs¶

Tier: Host - Available in every runtime, including headless mode.

Visibility: Public - Stable Lua API intended for user config and plugins.

Sync filesystem primitives. Errors use the (value, err_string) convention so callers can distinguish failures without pcall.

smelt.fs.complete_path¶

fun(dir: string, prefix: string, opts: table?): table?, string?

List immediate filesystem completions under dir matching prefix. Directory entries are returned first, then files, case-insensitive alphabetical, capped by opts.limit (default 200). Hidden names are included only when prefix starts with .. opts.insert_prefix controls inserted text and defaults to dir with a trailing separator. Returns ({ items }, nil) or (nil, err_string). Items are { label, path, insert_text, kind, description }.

smelt.fs.copy¶

fun(from: string, to: string): integer?, string?

Copy file from to to. Returns (bytes_copied, nil) on success or (nil, err_string) on failure.

smelt.fs.exists¶

fun(p: string): boolean

Return true if a filesystem entry exists at p.

smelt.fs.file_info_async¶

fun(path: string): table?, string?

Return { is_file, len, mtime_ms } for path off the main thread, or (nil, err).

smelt.fs.glob¶

fun(pattern: string, path: string?, opts: table?): string[]?, string?

Find paths matching pattern under path (defaults to cwd). Returns the matches sorted newest-first, capped at opts.max (default 200). On error returns (nil, err_string).

smelt.fs.glob_async¶

fun(pattern: string, path: string?, opts: table?): table?, string?

Find paths matching pattern under path off the main thread. opts accepts max, max_scanned, and timeout_ms. Returns a table with { paths, scanned, truncated, timed_out } or (nil, err).

smelt.fs.is_dir¶

fun(p: string): boolean

Return true if p exists and refers to a directory.

smelt.fs.is_file¶

fun(p: string): boolean

Return true if p exists and refers to a regular file.

smelt.fs.mkdir¶

fun(p: string): boolean, string?

Create directory p (parents must exist). Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.mkdir_all¶

fun(p: string): boolean, string?

Create directory p along with any missing parent directories. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.mkdir_all_async¶

fun(path: string): boolean, string?

Create path and parents off the main thread. Same return shape as smelt.fs.mkdir_all.

smelt.fs.read¶

fun(p: string): string?, string?

Read p into a string. Returns (content, nil) on success or (nil, err_string) on failure.

smelt.fs.read_async¶

fun(path: string): string?, string?, integer?

Read path off the main thread. Must be called from inside smelt.spawn(fn) or a tool.execute (anything that runs on the Lua task runtime). Returns (content, nil) on success or (nil, err) on failure - same convention as smelt.fs.read. Third return value is the file mtime in milliseconds when available.

smelt.fs.read_dir¶

fun(p: string): string[]?, string?

List the immediate entries of directory p. Returns (entries, nil) on success or (nil, err_string) on failure.

smelt.fs.read_limited¶

fun(p: string, max_bytes: integer): table?, string?

Read at most max_bytes bytes from p. Returns ({ content, truncated }, nil) on success or (nil, err_string) on failure.

smelt.fs.remove_dir¶

fun(p: string): boolean, string?

Delete the empty directory at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.remove_dir_all¶

fun(p: string): boolean, string?

Recursively delete the directory tree rooted at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.remove_file¶

fun(p: string): boolean, string?

Delete the file at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.rename¶

fun(from: string, to: string): boolean, string?

Rename or move from to to. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.size¶

fun(p: string): integer?, string?

Return the size of file p in bytes. Returns (size, nil) or (nil, err_string) on failure.

smelt.fs.watch¶

fun(path: string, handler: fun(event: { kind: string, detail: string?, paths: string[] }), opts: table?): smelt.Reg

Types: smelt.Reg

Filesystem watcher. Calls handler(event) for each event, where event = { kind, detail?, paths }. kind is one of "create" | "modify" | "remove" | "rename" | "access" | "other" | "any"; detail carries notify's sub-kind when one is reported (e.g. kind = "create" → detail = "file" | "folder"). opts.recursive defaults to true; set false to watch only the immediate entries of a directory. Returns a Reg whose :remove() stops the watcher and cancels the polling coroutine.

smelt.fs.write¶

fun(p: string, contents: string): boolean, string?

Write contents to file p, creating it if necessary. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.write_async¶

fun(path: string, contents: string): boolean, string?, integer?

Write contents to path off the main thread. Same yielding rules as smelt.fs.read_async. Returns (true, nil, mtime_ms) on success or (false, err, nil) on failure - mirrors smelt.fs.write.