rmx: Instructions file for Codex

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Project Overview

rmx (github.com/braswelljr/rmx) is a cross-platform, drop-in replacement for the GNU/UNIX rm command. It mirrors rm's flag surface and semantics — prompting, recursion, write-protected handling, --preserve-root, faithful diagnostics — while adding concurrent removal on the non-interactive path.

It is a single top-level command invoked as rmx [OPTION]... [FILE]..., exactly like rm.

Architecture at a glance

Two layers:

• core/ — one correct removal engine. Owns the tree walk, prompting, permission checks, diagnostics and concurrency. Everything routes through it.
• cmd/ — one package per flag (cmd/force, cmd/interactive, …). Each package is a thin adapter: it registers its flag(s) and folds the parsed value into a single core.Options. cmd/execute.go composes them and runs the engine once.

This split keeps flag composition (rmx -rvf, -ri) correct: there is exactly one walk, driven by one core.Options, rather than each flag re-implementing traversal.

Project Structure

rmx/
  main.go                  # Thin entry point; //go:generate hook for docs
  cmd/                     # One package per flag (adapters over the rm engine)
    root.go                # NewRoot(in,out,err) — builds the configured cobra command
    execute.go             # package cmd — Register(fs) + Execute() + buildOptions()
    docs/                  # Reference generator (cobra/doc: md/man/yaml/rest); tool-only dep
    force/                 # -f / --force
    interactive/           # -i, -I, --interactive[=WHEN]
    recursive/             # -r, -R, --recursive
    directory/             # -d / --dir
    verbose/               # -v / --verbose
    onefilesystem/         # --one-file-system
    preserveroot/          # --preserve-root / --no-preserve-root
    version/               # --version
  core/                    # The removal engine
    model.go               # Options, Mode, Rm struct, injection points
    core.go                # New, Run, the walk, prompting, diagnostics, concurrency
    permission_unix.go     # writable()/deviceID() via syscall (build tag !windows)
    permission_windows.go  # writable()/deviceID() via os.FileInfo (build tag windows)
  internal/
    common/                # AppName + link-time Version
    docmeta/               # zero-dep doc metadata type each cmd/<flag> exposes via Meta()
  tools/gendocs/           # `go run ./tools/gendocs [dir] [format]` — reference generator
  docs/                    # Generated reference (committed, deterministic), grouped by format:
                           #   <format>/{index.*, guide.*, flags/<flag>.*}
  .github/workflows/       # go.yml (build+test matrix), lint.yml (gofmt/tidy + golangci-lint)