feat(builtins): add readlink command (#579)

## Summary
- Add `readlink` builtin with `-f`, `-m`, `-e` canonicalization modes
and raw symlink target reading
- Register in interpreter alongside `basename`, `dirname`, `realpath`
- 10 unit tests covering symlinks, canonicalization, missing paths, and
error cases

## Test plan
- [x] Unit tests for all modes: raw, -f, -m, -e
- [x] Error cases: missing operand, invalid option, non-symlink,
nonexistent path
- [x] `cargo clippy --all-targets --all-features -- -D warnings` passes
- [x] Full test suite passes (1611+ tests)

Closes #537

Author: chaliy

crates/bashkit/src/builtins/mod.rs

@@ -106,7 +106,7 @@ pub use ls::{Find, Ls, Rmdir};
 pub use navigation::{Cd, Pwd};
 pub use nl::Nl;
 pub use paste::Paste;
-pub use path::{Basename, Dirname, Realpath};
+pub use path::{Basename, Dirname, Readlink, Realpath};
 pub use pipeline::{Tee, Watch, Xargs};
 pub use printf::Printf;
 pub use read::Read;

crates/bashkit/src/builtins/path.rs

@@ -150,6 +150,137 @@ impl Builtin for Realpath {
     }
 }
 
+/// The readlink builtin - print resolved symbolic links or canonical file names.
+///
+/// Usage: readlink [-f|-m|-e] FILE...
+///
+/// Options:
+///   -f    canonicalize: follow symlinks, resolve `.`/`..`; all but last component must exist
+///   -m    canonicalize-missing: like -f but no component needs to exist
+///   -e    canonicalize-existing: like -f but all components must exist
+///   (no flag) print symlink target without canonicalization
+pub struct Readlink;
+
+#[async_trait]
+impl Builtin for Readlink {
+    #[allow(clippy::collapsible_if)]
+    async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
+        if ctx.args.is_empty() {
+            return Ok(ExecResult::err(
+                "readlink: missing operand\n".to_string(),
+                1,
+            ));
+        }
+
+        let mut mode = ReadlinkMode::Raw;
+        let mut files: Vec<&str> = Vec::new();
+
+        for arg in ctx.args {
+            match arg.as_str() {
+                "-f" => mode = ReadlinkMode::Canonicalize,
+                "-m" => mode = ReadlinkMode::CanonicalizeMissing,
+                "-e" => mode = ReadlinkMode::CanonicalizeExisting,
+                "-n" | "-v" | "-q" | "-s" | "--no-newline" => { /* silently accept */ }
+                s if s.starts_with('-') && s.len() > 1 && !s.starts_with("--") => {
+                    // Could be combined flags like -fn
+                    for ch in s[1..].chars() {
+                        match ch {
+                            'f' => mode = ReadlinkMode::Canonicalize,
+                            'm' => mode = ReadlinkMode::CanonicalizeMissing,
+                            'e' => mode = ReadlinkMode::CanonicalizeExisting,
+                            'n' | 'v' | 'q' | 's' => {}
+                            _ => {
+                                return Ok(ExecResult::err(
+                                    format!("readlink: invalid option -- '{}'\n", ch),
+                                    1,
+                                ));
+                            }
+                        }
+                    }
+                }
+                _ => files.push(arg),
+            }
+        }
+
+        if files.is_empty() {
+            return Ok(ExecResult::err(
+                "readlink: missing operand\n".to_string(),
+                1,
+            ));
+        }
+
+        let mut output = String::new();
+        let mut exit_code = 0;
+
+        for file in &files {
+            let resolved = super::resolve_path(ctx.cwd, file);
+
+            match mode {
+                ReadlinkMode::Raw => {
+                    // No flag: read symlink target
+                    match ctx.fs.read_link(&resolved).await {
+                        Ok(target) => {
+                            output.push_str(&target.to_string_lossy());
+                            output.push('\n');
+                        }
+                        Err(_) => {
+                            exit_code = 1;
+                        }
+                    }
+                }
+                ReadlinkMode::Canonicalize | ReadlinkMode::CanonicalizeMissing => {
+                    // -f and -m: canonicalize path (resolve . and ..)
+                    // -m doesn't require existence, -f requires all but last
+                    let parent_missing = if mode == ReadlinkMode::Canonicalize {
+                        resolved
+                            .parent()
+                            .filter(|p| !p.as_os_str().is_empty())
+                            .map(|p| ctx.fs.exists(p))
+                    } else {
+                        None
+                    };
+                    if let Some(fut) = parent_missing {
+                        if !fut.await.unwrap_or(false) {
+                            exit_code = 1;
+                            continue;
+                        }
+                    }
+                    output.push_str(&resolved.to_string_lossy());
+                    output.push('\n');
+                }
+                ReadlinkMode::CanonicalizeExisting => {
+                    // -e: all components must exist
+                    if ctx.fs.exists(&resolved).await.unwrap_or(false) {
+                        output.push_str(&resolved.to_string_lossy());
+                        output.push('\n');
+                    } else {
+                        exit_code = 1;
+                    }
+                }
+            }
+        }
+
+        if exit_code != 0 && output.is_empty() {
+            Ok(ExecResult::err(String::new(), exit_code))
+        } else if exit_code != 0 {
+            // Some files succeeded, some failed
+            let mut result = ExecResult::with_code(output, exit_code);
+            result.exit_code = exit_code;
+            Ok(result)
+        } else {
+            Ok(ExecResult::ok(output))
+        }
+    }
+}
+
+#[derive(PartialEq)]
+enum ReadlinkMode {
+    Raw,
+    Canonicalize,
+    CanonicalizeMissing,
+    CanonicalizeExisting,
+}
+
 #[cfg(test)]
 #[allow(clippy::unwrap_used)]
 mod tests {
@@ -282,4 +413,110 @@ mod tests {
         assert_eq!(result.exit_code, 1);
         assert!(result.stderr.contains("missing operand"));
     }
+
+    // readlink tests
+
+    use crate::fs::FileSystem;
+
+    async fn run_readlink_with_fs(args: &[&str], fs: Arc<dyn FileSystem>) -> ExecResult {
+        let mut variables = HashMap::new();
+        let env = HashMap::new();
+        let mut cwd = PathBuf::from("/");
+
+        let args: Vec<String> = args.iter().map(|s| s.to_string()).collect();
+        let ctx = Context {
+            args: &args,
+            env: &env,
+            variables: &mut variables,
+            cwd: &mut cwd,
+            fs,
+            stdin: None,
+            #[cfg(feature = "http_client")]
+            http_client: None,
+            #[cfg(feature = "git")]
+            git_client: None,
+        };
+
+        Readlink.execute(ctx).await.unwrap()
+    }
+
+    #[tokio::test]
+    async fn test_readlink_missing_operand() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        let result = run_readlink_with_fs(&[], fs).await;
+        assert_eq!(result.exit_code, 1);
+        assert!(result.stderr.contains("missing operand"));
+    }
+
+    #[tokio::test]
+    async fn test_readlink_raw_symlink() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        fs.symlink(Path::new("/target"), Path::new("/link"))
+            .await
+            .unwrap();
+        let result = run_readlink_with_fs(&["/link"], fs).await;
+        assert_eq!(result.exit_code, 0);
+        assert_eq!(result.stdout, "/target\n");
+    }
+
+    #[tokio::test]
+    async fn test_readlink_raw_not_symlink() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        fs.write_file(Path::new("/file"), b"data").await.unwrap(); // write a regular file
+        let result = run_readlink_with_fs(&["/file"], fs).await;
+        // Not a symlink → failure, no output
+        assert_eq!(result.exit_code, 1);
+        assert!(result.stdout.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_readlink_raw_nonexistent() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        let result = run_readlink_with_fs(&["/nonexistent"], fs).await;
+        assert_eq!(result.exit_code, 1);
+    }
+
+    #[tokio::test]
+    async fn test_readlink_f_canonicalize() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        fs.mkdir(Path::new("/home"), true).await.unwrap();
+        fs.mkdir(Path::new("/home/user"), true).await.unwrap();
+        let result = run_readlink_with_fs(&["-f", "/home/user/../user/./file"], fs).await;
+        assert_eq!(result.exit_code, 0);
+        assert_eq!(result.stdout, "/home/user/file\n");
+    }
+
+    #[tokio::test]
+    async fn test_readlink_m_canonicalize_missing() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        // -m doesn't require existence
+        let result = run_readlink_with_fs(&["-m", "/a/b/../c"], fs).await;
+        assert_eq!(result.exit_code, 0);
+        assert_eq!(result.stdout, "/a/c\n");
+    }
+
+    #[tokio::test]
+    async fn test_readlink_e_existing() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        fs.mkdir(Path::new("/existing"), false).await.unwrap();
+        let result = run_readlink_with_fs(&["-e", "/existing"], fs).await;
+        assert_eq!(result.exit_code, 0);
+        assert_eq!(result.stdout, "/existing\n");
+    }
+
+    #[tokio::test]
+    async fn test_readlink_e_nonexistent() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        let result = run_readlink_with_fs(&["-e", "/nonexistent"], fs).await;
+        assert_eq!(result.exit_code, 1);
+        assert!(result.stdout.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_readlink_invalid_option() {
+        let fs = Arc::new(InMemoryFs::new()) as Arc<dyn FileSystem>;
+        let result = run_readlink_with_fs(&["-z", "/file"], fs).await;
+        assert_eq!(result.exit_code, 1);
+        assert!(result.stderr.contains("invalid option"));
+    }
 }

crates/bashkit/src/interpreter/mod.rs

@@ -372,6 +372,7 @@ impl Interpreter {
         builtins.insert("basename".to_string(), Box::new(builtins::Basename));
         builtins.insert("dirname".to_string(), Box::new(builtins::Dirname));
         builtins.insert("realpath".to_string(), Box::new(builtins::Realpath));
+        builtins.insert("readlink".to_string(), Box::new(builtins::Readlink));
         builtins.insert("mkdir".to_string(), Box::new(builtins::Mkdir));
         builtins.insert("mktemp".to_string(), Box::new(builtins::Mktemp));
         builtins.insert("rm".to_string(), Box::new(builtins::Rm));