/**
 * Reports the filesystem boundaries these tools operate within.
 *
 * - readRoots         — absolute roots that may be READ (recursively).
 * - workingDirectory  — the single writable dir; relative paths resolve here.
 *
 * Uses host helpers: safety.fs.readRoots, safety.fs.workspace.
 */

return {
  readRoots: Array.from(safety.fs.readRoots()),
  workingDirectory: safety.fs.workspace(),
};

/**
 * Reads a UTF-8 text file inside the playground's FS base directory.
 *
 * Path is resolved RELATIVE to the base path (which is set via
 * `spring.ai.playground.tool-studio.fs.base-path`,
 * defaulting to the user's home directory). Anything attempting
 * to escape the base (e.g. `../`) is rejected by safety.fs.
 *
 * Uses host helper: safety.fs.readText.
 */

if (path == null || path === '') throw new Error('path required');
return safety.fs.readText(path);

/**
 * Lists immediate entries (files + directories) of a directory.
 *
 * Returned as an array of leaf names - no recursion, no full paths.
 * Use `findFiles` for recursive globbing.
 *
 * Uses host helper: safety.fs.list.
 */

const target = (dir == null || dir === '') ? '.' : dir;
return safety.fs.list(target);

/**
 * Returns { size, mtime, directory } for a path inside the FS base.
 *
 * - size       - file size in bytes (0 for directories).
 * - mtime      - ISO timestamp of last modification.
 * - directory  - true if the path is a directory.
 *
 * Uses host helper: safety.fs.stat.
 */

if (path == null || path === '') throw new Error('path required');
return safety.fs.stat(path);

/**
 * Counts lines in a UTF-8 text file inside the FS base.
 *
 * Uses host helper: safety.fs.lineCount.
 */

if (path == null || path === '') throw new Error('path required');
return safety.fs.lineCount(path);

/**
 * Returns lines [start, end) from a UTF-8 text file (Python-slice semantics).
 *
 * - `start` is 0-based and inclusive.
 * - `end`   is 0-based and exclusive.
 * - Negative values count from the end: -1 == size - 1.
 * - Missing `start` / `end` defaults to the file's full range.
 *
 * Uses host helper: safety.fs.slice.
 */

if (path == null || path === '') throw new Error('path required');
return safety.fs.slice(path, start, end);

/**
 * Sorts a file's lines and returns them as an array.
 *
 * Options:
 *   reverse           - descending order
 *   numeric           - numeric comparison (otherwise lexical)
 *   caseInsensitive   - compare lowercased
 *   unique            - drop duplicates
 *
 * Uses host helper: safety.fs.sort.
 */

if (path == null || path === '') throw new Error('path required');
return safety.fs.sort(path, {
  reverse: !!reverse,
  numeric: !!numeric,
  caseInsensitive: !!caseInsensitive,
  unique: !!unique,
});

/**
 * Greps a file's lines against a regex and returns the hits.
 *
 * Result is an array of matching lines. With `numbered=true` each entry
 * is prefixed by its 1-based line number, e.g. "42: TODO fix this".
 *
 * Uses host helper: safety.fs.grep.
 */

if (pattern == null || pattern === '') throw new Error('pattern required');
if (path == null || path === '')       throw new Error('path required');
return safety.fs.grep(pattern, path, {
  caseInsensitive: !!caseInsensitive,
  numbered: !!numbered,
  limit: Number.isInteger(limit) ? limit : 0,
});

/**
 * Recursively finds entries matching a glob inside a directory.
 *
 * - Glob accepts `*` and `?` wildcards (POSIX glob, NOT regex).
 * - maxDepth limits recursion; 0 means unlimited.
 * - type='file' / 'dir' filters; omit to return both.
 *
 * Uses host helper: safety.fs.find.
 */

const target = (dir == null || dir === '') ? '.' : dir;
const pattern = (glob == null || glob === '') ? '*' : glob;
return safety.fs.find(target, pattern, {
  maxDepth: Number.isInteger(maxDepth) ? maxDepth : 0,
  type: (type === 'file' || type === 'dir') ? type : null,
});

/**
 * Extracts selected fields from each line of a delimited file.
 *
 * - `fields`     - 1-based field indices to keep (array). [1, 3] picks columns 1 and 3.
 * - `delimiter`  - single character (literal) OR a regex pattern when `regex=true`.
 *                  Defaults to tab (\t).
 *
 * Uses host helper: safety.fs.cut. Each returned row is a delimiter-joined string.
 */

if (path == null || path === '') throw new Error('path required');
if (fields == null) throw new Error('fields required');
const fieldArr = [];
for (const f of fields) fieldArr.push(Number(f));

return safety.fs.cut(path, {
  fields:    fieldArr,
  delimiter: (typeof delimiter === 'string' && delimiter.length > 0) ? delimiter : null,
  regex:     !!regex,
});

/**
 * Writes a UTF-8 text file inside the workspace directory.
 *
 * - Overwrites any existing file at `path`.
 * - Path is resolved RELATIVE to the workspace; escape attempts are rejected.
 * - This tool needs the `fileWrite` sandbox permission (set on the spec).
 *
 * Uses host helper: safety.fs.writeText.
 */

if (path == null || path === '') throw new Error('path required');
if (content == null)             throw new Error('content required');
const writtenPath = safety.fs.writeText(path, String(content));
return { ok: true, path: writtenPath, bytes: new TextEncoder().encode(String(content)).length };

if (pattern == null || pattern === '') throw new Error('pattern required');
const target = (dir == null || dir === '') ? '.' : dir;
const g = (glob == null || glob === '') ? '*' : glob;
return safety.fs.searchInFiles(target, g, pattern, {
  caseInsensitive: !!caseInsensitive,
  maxDepth: Number.isInteger(maxDepth) ? maxDepth : 0,
  limit: Number.isInteger(limit) ? limit : 0,
});

if (path == null || path === '') throw new Error('path required');
if (content == null)             throw new Error('content required');
const writtenPath = safety.fs.appendText(path, String(content));
return { ok: true, path: writtenPath, bytesAppended: new TextEncoder().encode(String(content)).length };

if (path == null || path === '')           throw new Error('path required');
if (oldString == null || oldString === '') throw new Error('oldString required');
const result = safety.fs.editText(path, String(oldString), newString == null ? '' : String(newString), !!replaceAll);
return { ok: true, path: result.path, replacements: result.replacements };

if (from == null || from === '') throw new Error('from required');
if (to == null || to === '')     throw new Error('to required');
const path = safety.fs.copy(String(from), String(to));
return { ok: true, path };

if (from == null || from === '') throw new Error('from required');
if (to == null || to === '')     throw new Error('to required');
const path = safety.fs.move(String(from), String(to));
return { ok: true, path };

if (path == null || path === '') throw new Error('path required');
const deleted = safety.fs.delete(String(path));
return { ok: true, deleted, path: String(path) };

if (path == null || path === '') throw new Error('path required');
const removed = safety.fs.deleteDir(String(path));
return { ok: true, removed, path: String(path) };