skip to content
iii / worker
$worker

coder

v0.2.0

Path-jailed code worker — info/read/search/update/create/delete/move files plus paginated list-folder and tree, with non-accessible glob protection, default noise excludes (.git, node_modules, … — hide-only, per-call opt-out), and token-bounded read/search response budgets.

iiiverified
73 installs17 in 7d0 today
install
$iii worker add coder@0.2.0
binary
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
7functions0triggers1skills0depsv0.2.0version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

7

coder::tree

function

Recursive directory snapshot bounded by `max_depth` and a `per_folder_limit`. Folders that hit the limit are flagged `truncated` and the caller is pointed at coder::list-folder for pagination.

request
  • max_depthinteger· uint32min 0

    Maximum depth to descend; the root node is depth 0.

  • pathstring

    Base folder relative to `base_path`. Defaults to `.`.

  • per_folder_limitinteger· uint32min 0

    Maximum children listed per folder. When more exist, the folder is flagged `truncated` and callers should switch to `coder::list-folder`.

response
  • rootobjectrequired
    • childrenunknown[]
    • kindstringrequiredenum: file, dir, symlink, other
    • mtimeinteger· int64required
    • namestringrequired
    • non_accessiblebooleanrequired
    • pathstringrequired
    • sizeinteger· uint64requiredmin 0
    • truncatedany of

      Set on directories whose `children` was capped at `per_folder_limit` or whose subtree was cut off by `max_depth`.

      any of (2)
      variant 1
      • hintstringrequired
      • reasonstringrequired

        Reason this folder was truncated: hit `per_folder_limit` or `max_depth`.

      • showninteger· uint32requiredmin 0

        Number of children actually returned.

      • totalinteger· uint32min 0

        Total number of children in the folder (only populated when `reason == "per_folder_limit"`; for depth truncation we don't peek into the folder).

      variant 2
      valuenull

coder::list-folder

function

Paginated single-folder listing, sorted by name. Non-accessible entries are still listed with a `non_accessible: true` flag.

request
  • pageinteger· uint32min 0
  • page_sizeinteger· uint32min 0

    Capped by `config.list_max_page_size`; falls back to `config.list_default_page_size` when omitted.

  • pathstring

    Folder, relative to `base_path`. Defaults to `.` (the base itself).

response
  • entriesobject[]required
    • kindstringrequiredenum: file, dir, symlink, other
    • mtimeinteger· int64required
    • namestringrequired
    • non_accessiblebooleanrequired

      True if this entry matches `non_accessible_globs` — caller cannot read/write/delete it via `coder::*` even though it shows up here.

    • sizeinteger· uint64requiredmin 0
  • has_morebooleanrequired
  • pageinteger· uint32requiredmin 0
  • page_sizeinteger· uint32requiredmin 0
  • pathstringrequired
  • totalinteger· uint64requiredmin 0

coder::delete-file

function

Remove one or more paths. Directories need `recursive: true`; missing paths are idempotent successes; recursive removal refuses to descend through non-accessible entries.

request
  • pathsstring[]required
  • recursiveboolean

    Required for non-empty directories. Files and empty dirs ignore it.

response
  • resultsobject[]required
    • errorstring
    • pathstringrequired
    • removedbooleanrequired
    • successbooleanrequired

coder::read-file

function

Read a file relative to base_path. Returns content plus size/mtime/mode. Capped by max_read_bytes; non-accessible paths return C211.

request
  • pathstringrequired

    File to read, relative to `base_path`.

response
  • contentstringrequired

    File content as a UTF-8 string. Binary files are returned with invalid bytes replaced by U+FFFD; use a future binary-aware function if exact bytes matter.

  • is_utf8booleanrequired

    Whether `content` lost bytes to UTF-8 sanitisation.

  • modeinteger· uint32requiredmin 0

    Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644.

  • mtimeinteger· int64required

    Last-modified time as a Unix epoch in seconds.

  • pathstringrequired

    The original `path` argument echoed back for caller correlation.

  • sizeinteger· uint64requiredmin 0

coder::update-file

function

Apply batched line-oriented and regex edits across one or more files. Line ops: { op: 'insert', at_line, content } | { op: 'remove', from_line, to_line } | { op: 'update_lines', from_line, to_line, content } — 1-based, inclusive, applied bottom-up. Regex op: { op: 'replace', pattern, replacement, ignore_case? } runs on the file body after line ops. Each file commits atomically via temp + rename.

request
  • filesobject[]required
    • opsone of[]required
      one of (4)
      variant 1
      • at_lineinteger· uint32requiredmin 0
      • contentstringrequired
      • opstringrequiredenum: insert
      variant 2
      • from_lineinteger· uint32requiredmin 0
      • opstringrequiredenum: remove
      • to_lineinteger· uint32requiredmin 0
      variant 3
      • contentstringrequired
      • from_lineinteger· uint32requiredmin 0
      • opstringrequiredenum: update_lines
      • to_lineinteger· uint32requiredmin 0
      variant 4
      • ignore_caseboolean
      • opstringrequiredenum: replace
      • patternstringrequired
      • replacementstringrequired
    • pathstringrequired
response
  • resultsobject[]required
    • afterstring

      UTF-8 body after ops (only on success, capped by `max_read_bytes`).

    • appliedinteger· uint32requiredmin 0

      Number of operations applied (only meaningful when `success`).

    • beforestring

      UTF-8 body before ops (only on success, capped by `max_read_bytes`).

    • errorstring
    • new_line_countinteger· uint64requiredmin 0

      Final line count after applying (only meaningful when `success`).

    • pathstringrequired
    • successbooleanrequired

coder::search

function

Search file contents and/or paths under base_path. Supports literal or regex queries with include/exclude globs; non-accessible files are excluded from both content and path results.

request
  • exclude_globsstring[]

    Glob patterns (relative to `base_path`) that exclude matching paths.

  • ignore_caseboolean
  • include_globsstring[]

    Glob patterns (relative to `base_path`) that paths must match to be considered. Empty = include everything.

  • max_line_bytesinteger· uint32min 0

    Bytes per line to consider when scanning content; longer lines are truncated for the match snippet.

  • max_matchesinteger· uint32min 0

    Optional explicit cap. Falls back to config when unset.

  • pathstring

    Folder, relative to `base_path`, scoping the walk. Defaults to `.` (the base itself). Globs and result `path`s remain anchored at `base_path` regardless of this value.

  • querystringrequired

    Pattern to search for. Treated as a regex when `regex: true`, otherwise as a literal substring.

  • regexboolean
  • search_contentboolean

    Search file contents (default true).

  • search_pathsboolean

    Search file paths (default true).

response
  • content_matchesobject[]required
    • columninteger· uint32requiredmin 0
    • lineinteger· uint32requiredmin 0
    • pathstringrequired
    • textstringrequired

      Matched line; truncated to `max_line_bytes` and never spans newlines.

  • path_matchesobject[]required
    • pathstringrequired
  • truncatedbooleanrequired

    True if either match list was cut off at the configured cap.

coder::create-file

function

Create one or more files. Per-file `overwrite` and `parents` flags; non-accessible paths return C211.

request
  • filesobject[]required
    • contentstringrequired
    • modestring

      Octal permission bits as a string, e.g. "0644". Defaults to "0644".

    • overwriteboolean

      When false (the default), refuse to write if `path` already exists.

    • parentsboolean

      Create missing parent directories. Defaults to true so a single `coder::create-file` call can scaffold a fresh subtree.

    • pathstringrequired
response
  • resultsobject[]required
    • bytes_writteninteger· uint64requiredmin 0
    • errorstring
    • pathstringrequired
    • successbooleanrequired

triggers

0
no triggers registered