---@meta
---@diagnostic disable: missing-return
-- Type stubs for the `fs` module (fully native). Reference: docs/fs.md
--
-- Every operation runs under the folder permission system: recorded grants
-- (per script, per directory, recursive) answer silently; unknown ones ask on
-- the terminal — y/n for this run, A/N recorded in access.json. Denials and
-- OS-level failures raise Lua errors; trap with pcall/utils.try where needed.
-- `--allow-fs`, `--no-fs` and `--sandbox` override the whole system.

fs = {}

---Read a whole file into a string (byte-exact; no encoding assumed).
---Errors if the path is not a regular file or not accessible.
---@param path string
---@return string content
function fs.readAll(path) end

---Write a whole file from a string: created if missing, truncated if not.
---The containing directory must already exist. Errors if the file can't be
---created or is not accessible.
---@param path string
---@param content string
function fs.writeAll(path, content) end

---Names of a directory's entries (files and subdirectories), sorted.
---Errors if the path is not a directory or not accessible.
---@param path string
---@return string[] names
function fs.list(path) end

---true iff the path exists, is a directory, and is readable under the
---permission system. Never errors; a nonexistent path is false without any
---permission prompt.
---@param path string
---@return boolean
function fs.isDir(path) end

---true iff the path exists, is a regular file, and is readable under the
---permission system. Never errors; a nonexistent path is false without any
---permission prompt.
---@param path string
---@return boolean
function fs.isFile(path) end

---The process's current working directory (absolute path) — what relative
---paths in the other fs functions resolve against. Not permission-gated.
---@return string dir
function fs.getWorkdir() end

---Run the permission cycle for a directory explicitly: recorded answer, else
---interactive prompt, else false (nothing recorded when there is no terminal
---to ask on). Errors if the path is not an existing directory.
---@param dir string
---@param mode "r"|"w"
---@return boolean granted
function fs.access(dir, mode) end