@qodalis/cli-files 2.0.0-beta.8 → 2.0.0-rc.1

package/public-api.js

@@ -3,11 +3,14 @@
 var cliCore = require('@qodalis/cli-core');
 
 // src/lib/interfaces/i-file-system-service.ts
-var IFileSystemService_TOKEN = "cli-file-system-service";
+var IFileSystemService_TOKEN = cliCore.createCliToken("cli-file-system-service");
 
 // src/lib/version.ts
-var LIBRARY_VERSION = "2.0.0-beta.8";
+var LIBRARY_VERSION = "2.0.0-rc.1";
 var API_VERSION = 2;
+function splitArgs(raw) {
+  return cliCore.splitShellWords(raw);
+}
 
 // src/lib/processors/cli-ls-command-processor.ts
 var CliLsCommandProcessor = class {
@@ -32,41 +35,63 @@ var CliLsCommandProcessor = class {
         description: "Use long listing format",
         required: false,
         type: "boolean"
+      },
+      {
+        name: "human-readable",
+        aliases: ["h"],
+        description: "With -l, print sizes like 1.5K and 2M",
+        required: false,
+        type: "boolean"
       }
     ];
+    this.humanReadable = false;
   }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const targetPath = command.value || fs.getCurrentDirectory();
+    const paths = splitArgs(command.value || "");
     const showAll = command.args["all"] || command.args["a"];
     const longFormat = command.args["long"] || command.args["l"];
-    try {
-      const entries = fs.listDirectory(targetPath);
-      const filtered = showAll ? entries : entries.filter((e) => !e.name.startsWith("."));
-      if (filtered.length === 0) {
-        return;
-      }
-      filtered.sort((a, b) => {
-        if (a.type !== b.type) {
-          return a.type === "directory" ? -1 : 1;
+    this.humanReadable = !!(command.args["human-readable"] || command.args["h"]);
+    const targets = paths.length > 0 ? paths : [fs.getCurrentDirectory()];
+    const piped = [];
+    targets.forEach((targetPath, index) => {
+      try {
+        const node = fs.getNode(targetPath);
+        const entries = node && node.type !== "directory" ? [{ ...node, name: targetPath }] : fs.listDirectory(targetPath);
+        const filtered = showAll ? entries : entries.filter((e) => !e.name.startsWith("."));
+        if (targets.length > 1) {
+          if (index > 0) context.writer.writeln();
+          context.writer.writeln(`${targetPath}:`);
         }
-        return a.name.localeCompare(b.name);
-      });
-      if (longFormat) {
-        this.writeLongFormat(filtered, context);
-      } else {
-        this.writeShortFormat(filtered, context);
+        if (filtered.length === 0) {
+          return;
+        }
+        filtered.sort((a, b) => {
+          if (a.type !== b.type) {
+            return a.type === "directory" ? -1 : 1;
+          }
+          return a.name.localeCompare(b.name);
+        });
+        if (longFormat) {
+          this.writeLongFormat(filtered, context);
+        } else {
+          this.writeShortFormat(filtered, context);
+          piped.push(...filtered.map((e) => e.name));
+        }
+      } catch (e) {
+        context.writer.writeError(e.message);
       }
-    } catch (e) {
-      context.writer.writeError(e.message);
+    });
+    if (!longFormat && piped.length > 0) {
+      context.process.output(piped.join("\n"));
     }
   }
   writeDescription(context) {
     context.writer.writeln(this.description);
     context.writer.writeln();
-    context.writer.writeln("Usage: ls [path] [--all] [--long]");
+    context.writer.writeln("Usage: ls [path...] [-a|--all] [-l|--long] [-h|--human-readable]");
   }
   writeLongFormat(entries, context) {
     const { writer } = context;
@@ -75,7 +100,7 @@ var CliLsCommandProcessor = class {
       const perms = entry.permissions || (entry.type === "directory" ? "rwxr-xr-x" : "rw-r--r--");
       const owner = entry.ownership?.uid || "-";
       const group = entry.ownership?.gid || "-";
-      const size = entry.type === "file" ? entry.size.toString() : "-";
+      const size = entry.type !== "file" ? "-" : this.humanReadable ? this.formatSize(entry.size) : entry.size.toString();
       const date = new Date(entry.modifiedAt);
       const dateStr = date.toLocaleDateString("en-US", {
         month: "short",
@@ -89,6 +114,17 @@ var CliLsCommandProcessor = class {
       );
     }
   }
+  formatSize(bytes) {
+    const units = ["K", "M", "G", "T"];
+    let size = bytes;
+    let unit = "";
+    for (const next of units) {
+      if (size < 1024) break;
+      size /= 1024;
+      unit = next;
+    }
+    return unit ? `${size < 10 ? size.toFixed(1) : Math.round(size)}${unit}` : String(bytes);
+  }
   writeShortFormat(entries, context) {
     const { writer } = context;
     const names = entries.map(
@@ -106,11 +142,30 @@ var CliCdCommandProcessor = class {
     this.acceptsRawInput = true;
     this.metadata = { icon: "\u{1F4C1}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.cd.help.change_current_directory_without", "Change the current directory. Without a path it goes to your home directory. Paths can be absolute (/...), relative to where you are, or start with ~ for home.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["cd", t.t("cli.cd.help.go_home_directory", "Go to your home directory")],
+      ["cd <dir>", t.t("cli.cd.help.go_directory", "Go into a directory")],
+      ["cd ..", t.t("cli.cd.help.go_up_one_level", "Go up one level")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cd ~/docs", t.t("cli.cd.help.go_docs_home", "Go to docs in your home")],
+      ["cd ../projects", t.t("cli.cd.help.go_sibling_directory", "Go to a sibling directory")],
+      ["cd /", t.t("cli.cd.help.go_root", "Go to the root")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const target = command.value || "~";
+    const target = splitArgs(command.value || "").join(" ") || "~";
     try {
       fs.setCurrentDirectory(target);
       await fs.persist();
@@ -127,8 +182,24 @@ var CliPwdCommandProcessor = class {
     this.version = LIBRARY_VERSION;
     this.metadata = { icon: "\u{1F4C2}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.pwd.help.print_full_path_directory", "Print the full path of the directory you are in. Relative paths in other commands start from here.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["pwd", t.t("cli.pwd.help.show_current_directory", "Show the current directory")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["pwd", t.t("cli.pwd.help.example_home_user", "For example /home/user")],
+      ["cd ~/docs; pwd", t.t("cli.pwd.help.prints_home_user_docs", "Prints /home/user/docs")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     context.writer.writeln(fs.getCurrentDirectory());
@@ -153,22 +224,44 @@ var CliMkdirCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.mkdir.help.create_new_directory_p", "Create a new directory. With -p, any missing parent directories are created too.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["mkdir <dir...>", t.t("cli.mkdir.help.create_one_more_directories", "Create one or more directories")],
+      ["mkdir -p <path>", t.t("cli.mkdir.help.create_directory_missing_parents", "Create a directory and its missing parents")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["mkdir projects", t.t("cli.mkdir.help.create_projects_current_directory", "Create projects in the current directory")],
+      ["mkdir -p ~/docs/2026/notes", t.t("cli.mkdir.help.create_whole_path_once", "Create the whole path at once")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const path = command.value;
+    const paths = splitArgs(command.value || "");
     const recursive = command.args["parents"] || command.args["p"];
-    if (!path) {
+    if (paths.length === 0) {
       context.writer.writeError("mkdir: missing operand");
       return;
     }
-    try {
-      fs.createDirectory(path, recursive);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
+    let changed = false;
+    for (const path of paths) {
+      try {
+        if (recursive && fs.isDirectory(path)) continue;
+        fs.createDirectory(path, recursive);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
+      }
     }
+    if (changed) await fs.persist();
   }
 };
 var CliRmdirCommandProcessor = class {
@@ -181,38 +274,58 @@ var CliRmdirCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F5D1}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.rmdir.help.remove_empty_directory_refuses", "Remove an empty directory. It refuses to remove a directory that still contains files; use rm -r for that.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["rmdir <dir...>", t.t("cli.rmdir.help.remove_empty_directories", "Remove empty directories")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["rmdir empty-folder", t.t("cli.rmdir.help.remove_directory_current_one", "Remove a directory in the current one")],
+      ["rmdir ~/docs/old", t.t("cli.rmdir.help.remove_full_path", "Remove by full path")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const path = command.value;
-    if (!path) {
+    const paths = splitArgs(command.value || "");
+    if (paths.length === 0) {
       context.writer.writeError("rmdir: missing operand");
       return;
     }
-    try {
-      const node = fs.getNode(path);
-      if (!node) {
-        context.writer.writeError(
-          `rmdir: ${path}: No such file or directory`
-        );
-        return;
-      }
-      if (node.type !== "directory") {
-        context.writer.writeError(`rmdir: ${path}: Not a directory`);
-        return;
-      }
-      if (node.children && node.children.length > 0) {
-        context.writer.writeError(
-          `rmdir: ${path}: Directory not empty`
-        );
-        return;
+    let changed = false;
+    for (const path of paths) {
+      try {
+        const node = fs.getNode(path);
+        if (!node) {
+          context.writer.writeError(
+            `rmdir: ${path}: No such file or directory`
+          );
+          continue;
+        }
+        if (node.type !== "directory") {
+          context.writer.writeError(`rmdir: ${path}: Not a directory`);
+          continue;
+        }
+        if (node.children && node.children.length > 0) {
+          context.writer.writeError(
+            `rmdir: ${path}: Directory not empty`
+          );
+          continue;
+        }
+        fs.remove(path, true);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
       }
-      fs.remove(path);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
     }
+    if (changed) await fs.persist();
   }
 };
 var CliTouchCommandProcessor = class {
@@ -225,23 +338,56 @@ var CliTouchCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F4C4}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.touch.help.create_empty_file_update", "Create an empty file, or update the modified time of a file that already exists. The parent directory must already exist.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["touch <file...>", t.t("cli.touch.help.create_files_refresh_their", "Create the files, or refresh their timestamps")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["touch notes.txt", t.t("cli.touch.help.create_empty_notes_txt", "Create an empty notes.txt")],
+      ["touch ~/docs/todo.md", t.t("cli.touch.help.create_file_docs", "Create a file in ~/docs")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const path = command.value;
-    if (!path) {
+    const paths = splitArgs(command.value || "");
+    if (paths.length === 0) {
       context.writer.writeError("touch: missing file operand");
       return;
     }
-    try {
-      fs.createFile(path);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
+    let changed = false;
+    for (const path of paths) {
+      try {
+        fs.createFile(path);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
+      }
     }
+    if (changed) await fs.persist();
   }
 };
+
+// src/lib/utils/lines.ts
+function splitLines(content) {
+  if (content === "") return [];
+  const lines = content.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+function pipedText(data) {
+  return typeof data === "string" ? data : JSON.stringify(data);
+}
+
+// src/lib/processors/cli-cat-command-processor.ts
 var CliCatCommandProcessor = class {
   constructor() {
     this.command = "cat";
@@ -252,22 +398,58 @@ var CliCatCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F4D6}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.cat.help.print_contents_one_more", "Print the contents of one or more files, joined in order, or of piped input. Pipe the output into other commands to search, sort or count it.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["cat <file...>", t.t("cli.cat.help.print_files_one_after", "Print files one after another")],
+      ["cat <file> | <command>", t.t("cli.cat.help.send_file_another_command", "Send a file to another command")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cat notes.txt", t.t("cli.cat.help.show_whole_file", "Show the whole file")],
+      ["cat app.log | grep error", t.t("cli.cat.help.show_only_lines_error", "Show only lines with error")],
+      ["cat names.txt | sort", t.t("cli.cat.help.print_lines_sorted", "Print the lines sorted")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const path = command.value;
-    if (!path) {
+    const paths = splitArgs(command.value || "");
+    if (paths.length === 0) {
+      if (command.data != null) {
+        context.writer.writeln(pipedText(command.data));
+        return;
+      }
       context.writer.writeError("cat: missing file operand");
       return;
     }
-    try {
-      const content = fs.readFile(path);
-      if (content !== null) {
-        context.writer.writeln(content);
+    let output = "";
+    for (const path of paths) {
+      try {
+        if (fs.isDirectory(path)) {
+          context.writer.writeError(`cat: ${path}: Is a directory`);
+          continue;
+        }
+        const content = fs.readFile(path);
+        if (content === null) {
+          context.writer.writeError(
+            `cat: ${path}: No such file or directory`
+          );
+          continue;
+        }
+        output += content;
+      } catch (e) {
+        context.writer.writeError(e.message);
       }
-    } catch (e) {
-      context.writer.writeError(e.message);
+    }
+    if (output !== "") {
+      context.writer.writeln(output.replace(/\n$/, ""));
     }
   }
 };
@@ -281,60 +463,33 @@ var CliEchoCommandProcessor = class {
     this.extendsProcessor = true;
     this.metadata = { icon: "\u{1F4AC}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.echo.help.print_text_terminal_add", "Print text to the terminal. Add > file to save it to a file (replacing it) or >> file to add it to the end.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["echo <text>", t.t("cli.echo.help.print_text", "Print text")],
+      ["echo <text> > <file>", t.t("cli.echo.help.write_text_file", "Write text to a file")],
+      ["echo <text> >> <file>", t.t("cli.echo.help.append_text_file", "Append text to a file")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["echo Hello world", t.t("cli.echo.help.print_greeting", "Print a greeting")],
+      ["echo first line > notes.txt", t.t("cli.echo.help.create_replace_notes_txt", "Create or replace notes.txt")],
+      ["echo another line >> notes.txt", t.t("cli.echo.help.add_line", "Add a line to it")]
+    ]);
+  }
   async processCommand(command, context) {
-    const afterEcho = command.value || "";
-    const hasRedirection = />>?\s*.+$/.test(afterEcho);
-    if (!hasRedirection) {
-      if (this.originalProcessor) {
-        await this.originalProcessor.processCommand(command, context);
-      } else {
-        context.writer.writeln(afterEcho);
-      }
+    if (this.originalProcessor) {
+      await this.originalProcessor.processCommand(command, context);
       return;
     }
-    const fs = context.services.get(
-      IFileSystemService_TOKEN
-    );
-    let text;
-    let filePath;
-    let append = false;
-    const appendMatch = afterEcho.match(/^(.*?)\s*>>\s*(.+)$/);
-    const overwriteMatch = afterEcho.match(/^(.*?)\s*>\s*(.+)$/);
-    if (appendMatch) {
-      text = appendMatch[1].trim();
-      filePath = appendMatch[2].trim();
-      append = true;
-    } else {
-      text = overwriteMatch[1].trim();
-      filePath = overwriteMatch[2].trim();
-    }
-    if (text.startsWith('"') && text.endsWith('"') || text.startsWith("'") && text.endsWith("'")) {
-      text = text.slice(1, -1);
-    }
-    text = text.replace(/\\([\\nrtv0])/g, (_, ch) => {
-      switch (ch) {
-        case "n":
-          return "\n";
-        case "t":
-          return "	";
-        case "r":
-          return "\r";
-        case "v":
-          return "\v";
-        case "0":
-          return "\0";
-        case "\\":
-          return "\\";
-        default:
-          return ch;
-      }
-    });
-    try {
-      fs.writeFile(filePath, text + "\n", append);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
-    }
+    const text = cliCore.joinShellWords(command.value || "");
+    context.writer.writeln(text);
+    context.process.output(text);
   }
 };
 var CliRmCommandProcessor = class {
@@ -363,35 +518,58 @@ var CliRmCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.rm.help.delete_file_directories_only", "Delete a file. Directories are only removed with -r, which deletes everything inside them. Deleted files cannot be recovered.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["rm <file...>", t.t("cli.rm.help.delete_one_more_files", "Delete one or more files")],
+      ["rm -r <dir>", t.t("cli.rm.help.delete_directory_contents", "Delete a directory and its contents")],
+      ["rm -f <file>", t.t("cli.rm.help.delete_without_error_if", "Delete without an error if it is missing")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["rm notes.bak", t.t("cli.rm.help.delete_one_file", "Delete one file")],
+      ["rm -r old-project", t.t("cli.rm.help.delete_whole_directory", "Delete a whole directory")],
+      ["rm -f maybe.txt", t.t("cli.rm.help.quiet_if_file_does", "Quiet if the file does not exist")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const path = command.value;
+    const paths = splitArgs(command.value || "");
     const recursive = command.args["recursive"] || command.args["r"] || command.args["R"];
     const force = command.args["force"] || command.args["f"];
-    if (!path) {
-      context.writer.writeError("rm: missing operand");
+    if (paths.length === 0) {
+      if (!force) context.writer.writeError("rm: missing operand");
       return;
     }
-    try {
-      if (!fs.exists(path)) {
-        if (!force) {
-          context.writer.writeError(
-            `rm: ${path}: No such file or directory`
-          );
+    let changed = false;
+    for (const path of paths) {
+      try {
+        if (!fs.exists(path)) {
+          if (!force) {
+            context.writer.writeError(
+              `rm: ${path}: No such file or directory`
+            );
+          }
+          continue;
         }
-        return;
-      }
-      if (fs.isDirectory(path) && !recursive) {
-        context.writer.writeError(`rm: ${path}: Is a directory`);
-        return;
+        if (fs.isDirectory(path) && !recursive) {
+          context.writer.writeError(`rm: ${path}: Is a directory`);
+          continue;
+        }
+        fs.remove(path, recursive);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
       }
-      fs.remove(path, recursive);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
     }
+    if (changed) await fs.persist();
   }
 };
 var CliCpCommandProcessor = class {
@@ -409,11 +587,37 @@ var CliCpCommandProcessor = class {
         description: "Copy directories recursively",
         required: false,
         type: "boolean"
+      },
+      {
+        name: "force",
+        aliases: ["f"],
+        description: "Overwrite existing files (always done; accepted for -rf)",
+        required: false,
+        type: "boolean"
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.cp.help.copy_file_new_path", "Copy a file to a new path, or into an existing directory. Copying a directory needs -r, which copies everything inside it. A file already at the destination is replaced.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["cp <source> <dest>", t.t("cli.cp.help.copy_file_new_name", "Copy a file to a new name")],
+      ["cp <source...> <dir>", t.t("cli.cp.help.copy_files_directory", "Copy files into a directory")],
+      ["cp -r <dir> <dest>", t.t("cli.cp.help.copy_directory_contents", "Copy a directory and its contents")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cp notes.txt notes.bak", t.t("cli.cp.help.make_backup_copy", "Make a backup copy")],
+      ["cp report.txt ~/docs", t.t("cli.cp.help.copy_docs", "Copy into ~/docs")],
+      ["cp -r project project-copy", t.t("cli.cp.help.duplicate_whole_directory", "Duplicate a whole directory")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const recursive = command.args["recursive"] || command.args["r"] || command.args["R"];
@@ -425,18 +629,26 @@ var CliCpCommandProcessor = class {
       );
       return;
     }
-    const src = parts[0];
-    const dest = parts[1];
-    try {
-      fs.copy(src, dest, recursive);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
+    const dest = parts[parts.length - 1];
+    const sources = parts.slice(0, -1);
+    if (sources.length > 1 && !fs.isDirectory(dest)) {
+      context.writer.writeError(`cp: target '${dest}' is not a directory`);
+      return;
+    }
+    let changed = false;
+    for (const src of sources) {
+      try {
+        fs.copy(src, dest, recursive);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
+      }
     }
+    if (changed) await fs.persist();
   }
   parseArgs(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter((t) => t && !t.startsWith("--") && !t.startsWith("-"));
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliMvCommandProcessor = class {
@@ -448,8 +660,26 @@ var CliMvCommandProcessor = class {
     this.acceptsRawInput = true;
     this.metadata = { icon: "\u{1F4E6}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.mv.help.move_rename_file_directory", "Move or rename a file or directory. If the destination is an existing directory, the source is moved into it; otherwise it is renamed. A file already at the destination is replaced.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["mv <source> <dest>", t.t("cli.mv.help.rename_file_directory", "Rename a file or directory")],
+      ["mv <source...> <dir>", t.t("cli.mv.help.move_them_directory", "Move them into a directory")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["mv draft.txt final.txt", t.t("cli.mv.help.rename_file", "Rename a file")],
+      ["mv final.txt ~/docs", t.t("cli.mv.help.move_docs", "Move it into ~/docs")],
+      ["mv old-dir new-dir", t.t("cli.mv.help.rename_directory", "Rename a directory")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const parts = this.parseArgs(command);
@@ -458,20 +688,36 @@ var CliMvCommandProcessor = class {
       context.writer.writeln("Usage: mv <source> <destination>");
       return;
     }
-    const src = parts[0];
-    const dest = parts[1];
-    try {
-      fs.move(src, dest);
-      await fs.persist();
-    } catch (e) {
-      context.writer.writeError(e.message);
+    const dest = parts[parts.length - 1];
+    const sources = parts.slice(0, -1);
+    if (sources.length > 1 && !fs.isDirectory(dest)) {
+      context.writer.writeError(`mv: target '${dest}' is not a directory`);
+      return;
     }
+    let changed = false;
+    for (const src of sources) {
+      try {
+        fs.move(src, dest);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(e.message);
+      }
+    }
+    if (changed) await fs.persist();
   }
   parseArgs(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter((t) => t && !t.startsWith("--") && !t.startsWith("-"));
+    return splitArgs(raw).filter(Boolean);
   }
 };
+function readableChildren(fs, path) {
+  try {
+    return fs.listDirectory(path);
+  } catch (e) {
+    if (cliCore.isCliAccessDeniedError(e)) return null;
+    throw e;
+  }
+}
 var CliTreeCommandProcessor = class {
   constructor() {
     this.command = "tree";
@@ -490,11 +736,29 @@ var CliTreeCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.tree.help.draw_directory_everything_below", "Draw a directory and everything below it as a tree, directories first, followed by a count of directories and files. Defaults to the current directory.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["tree [dir]", t.t("cli.tree.help.show_whole_tree", "Show the whole tree")],
+      ["tree -L <n> [dir]", t.t("cli.tree.help.only_levels_deep", "Only <n> levels deep")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["tree", t.t("cli.tree.help.tree_current_directory", "Tree of the current directory")],
+      ["tree ~/docs", t.t("cli.tree.help.tree_docs", "Tree of ~/docs")],
+      ["tree -L 2", t.t("cli.tree.help.top_two_levels_only", "Top two levels only")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const targetPath = command.value || fs.getCurrentDirectory();
+    const targetPath = splitArgs(command.value || "").join(" ") || fs.getCurrentDirectory();
     const maxDepth = command.args["depth"] ? parseInt(command.args["depth"]) : command.args["L"] ? parseInt(command.args["L"]) : Infinity;
     try {
       const node = fs.getNode(targetPath);
@@ -518,7 +782,8 @@ var CliTreeCommandProcessor = class {
         )
       );
       const counts = { dirs: 0, files: 0 };
-      this.printTree(node, "", true, 0, maxDepth, context, counts);
+      this.fs = fs;
+      this.printTree(node, "", true, 0, maxDepth, context, counts, resolvedPath);
       context.writer.writeln();
       context.writer.writeln(
         `${counts.dirs} directories, ${counts.files} files`
@@ -527,11 +792,15 @@ var CliTreeCommandProcessor = class {
       context.writer.writeError(e.message);
     }
   }
-  printTree(node, prefix, isRoot, depth, maxDepth, context, counts) {
-    if (!node.children || depth >= maxDepth) {
+  printTree(node, prefix, isRoot, depth, maxDepth, context, counts, path = "/") {
+    if (depth >= maxDepth) {
+      return;
+    }
+    const visible = this.fs ? readableChildren(this.fs, path) : node.children;
+    if (!visible) {
       return;
     }
-    const children = [...node.children].sort((a, b) => {
+    const children = [...visible].sort((a, b) => {
       if (a.type !== b.type) {
         return a.type === "directory" ? -1 : 1;
       }
@@ -556,7 +825,8 @@ var CliTreeCommandProcessor = class {
           depth + 1,
           maxDepth,
           context,
-          counts
+          counts,
+          path === "/" ? `/${child.name}` : `${path}/${child.name}`
         );
       } else {
         counts.files++;
@@ -583,21 +853,40 @@ var CliHeadCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.head.help.print_first_lines_file", "Print the first lines of a file, 10 by default. Works on piped input too. With several files, each one gets a ==> name <== header.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["head <file>", t.t("cli.head.help.first_10_lines", "First 10 lines")],
+      ["head -n <count> <file>", t.t("cli.head.help.first_lines", "First <count> lines")],
+      ["<command> | head", t.t("cli.head.help.first_lines_piped_input", "First lines of piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["head notes.txt", t.t("cli.head.help.show_start_file", "Show the start of a file")],
+      ["head -n 3 a.txt b.txt", t.t("cli.head.help.first_3_lines_each", "First 3 lines of each file")],
+      ["cat app.log | head -n 20", t.t("cli.head.help.first_20_lines_log", "First 20 lines of the log")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const count = parseInt(
-      command.args["lines"] || command.args["n"] || "10",
-      10
-    );
+    const countArg = command.args["lines"] ?? command.args["n"] ?? Object.keys(command.args).find((k) => /^\d+$/.test(k));
+    const parsedCount = parseInt(String(countArg ?? "10"), 10);
+    const count = isNaN(parsedCount) ? 10 : Math.abs(parsedCount);
     const paths = this.parsePaths(command);
     if (paths.length === 0) {
       if (command.data != null) {
-        const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        const lines = content.split("\n");
+        const lines = splitLines(pipedText(command.data));
         const selected = lines.slice(0, count);
-        context.writer.writeln(selected.join("\n"));
+        if (selected.length > 0) {
+          context.writer.writeln(selected.join("\n"));
+        }
         return;
       }
       context.writer.writeError("head: missing file operand");
@@ -616,9 +905,11 @@ var CliHeadCommandProcessor = class {
           if (i > 0) context.writer.writeln();
           context.writer.writeln(`==> ${path} <==`);
         }
-        const lines = content.split("\n");
+        const lines = splitLines(content);
         const selected = lines.slice(0, count);
-        context.writer.writeln(selected.join("\n"));
+        if (selected.length > 0) {
+          context.writer.writeln(selected.join("\n"));
+        }
       } catch (e) {
         context.writer.writeError(`head: ${e.message}`);
       }
@@ -626,7 +917,7 @@ var CliHeadCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliTailCommandProcessor = class {
@@ -648,21 +939,40 @@ var CliTailCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.tail.help.print_last_lines_file", "Print the last lines of a file, 10 by default. Works on piped input too. With several files, each one gets a ==> name <== header.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["tail <file>", t.t("cli.tail.help.last_10_lines", "Last 10 lines")],
+      ["tail -n <count> <file>", t.t("cli.tail.help.last_lines", "Last <count> lines")],
+      ["<command> | tail", t.t("cli.tail.help.last_lines_piped_input", "Last lines of piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["tail app.log", t.t("cli.tail.help.show_end_log", "Show the end of a log")],
+      ["tail -n 5 notes.txt", t.t("cli.tail.help.last_5_lines", "Last 5 lines")],
+      ["cat app.log | tail -n 20", t.t("cli.tail.help.last_20_lines_log", "Last 20 lines of the log")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const count = parseInt(
-      command.args["lines"] || command.args["n"] || "10",
-      10
-    );
+    const countArg = command.args["lines"] ?? command.args["n"] ?? Object.keys(command.args).find((k) => /^\d+$/.test(k));
+    const parsedCount = parseInt(String(countArg ?? "10"), 10);
+    const count = isNaN(parsedCount) ? 10 : Math.abs(parsedCount);
     const paths = this.parsePaths(command);
     if (paths.length === 0) {
       if (command.data != null) {
-        const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        const lines = content.split("\n");
-        const selected = lines.slice(-count);
-        context.writer.writeln(selected.join("\n"));
+        const lines = splitLines(pipedText(command.data));
+        const selected = count > 0 ? lines.slice(-count) : [];
+        if (selected.length > 0) {
+          context.writer.writeln(selected.join("\n"));
+        }
         return;
       }
       context.writer.writeError("tail: missing file operand");
@@ -681,9 +991,11 @@ var CliTailCommandProcessor = class {
           if (i > 0) context.writer.writeln();
           context.writer.writeln(`==> ${path} <==`);
         }
-        const lines = content.split("\n");
-        const selected = lines.slice(-count);
-        context.writer.writeln(selected.join("\n"));
+        const lines = splitLines(content);
+        const selected = count > 0 ? lines.slice(-count) : [];
+        if (selected.length > 0) {
+          context.writer.writeln(selected.join("\n"));
+        }
       } catch (e) {
         context.writer.writeError(`tail: ${e.message}`);
       }
@@ -691,7 +1003,7 @@ var CliTailCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliWcCommandProcessor = class {
@@ -727,8 +1039,30 @@ var CliWcCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.wc.help.count_lines_words_characters", "Count lines, words and characters in files or piped input. With several files, a total line is printed at the end.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["wc <file...>", t.t("cli.wc.help.lines_words_characters", "Lines, words and characters")],
+      ["wc -l <file>", t.t("cli.wc.help.only_line_count", "Only the line count")],
+      ["<command> | wc", t.t("cli.wc.help.count_piped_input", "Count piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["wc notes.txt", t.t("cli.wc.help.all_three_counts", "All three counts")],
+      ["wc -l a.txt b.txt", t.t("cli.wc.help.line_counts_total", "Line counts with a total")],
+      [
+        "cat app.log | grep error | wc -l",
+        t.t("cli.wc.help.how_many_lines_mention", "How many lines mention error")
+      ]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const showLines = command.args["lines"] || command.args["l"] || false;
@@ -738,10 +1072,9 @@ var CliWcCommandProcessor = class {
     const paths = this.parsePaths(command);
     if (paths.length === 0) {
       if (command.data != null) {
-        const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        const lineCount = content === "" ? 0 : content.split("\n").length;
-        const wordCount = content.trim() === "" ? 0 : content.trim().split(/\s+/).length;
-        const charCount = content.length;
+        let content = pipedText(command.data);
+        if (content !== "" && !content.endsWith("\n")) content += "\n";
+        const { lineCount, wordCount, charCount } = this.count(content);
         const parts = [];
         if (showAll || showLines) parts.push(String(lineCount).padStart(8));
         if (showAll || showWords) parts.push(String(wordCount).padStart(8));
@@ -762,9 +1095,7 @@ var CliWcCommandProcessor = class {
           continue;
         }
         const content = fs.readFile(path) ?? "";
-        const lineCount = content === "" ? 0 : content.split("\n").length;
-        const wordCount = content.trim() === "" ? 0 : content.trim().split(/\s+/).length;
-        const charCount = content.length;
+        const { lineCount, wordCount, charCount } = this.count(content);
         totalLines += lineCount;
         totalWords += wordCount;
         totalChars += charCount;
@@ -787,9 +1118,17 @@ var CliWcCommandProcessor = class {
       context.writer.writeln(parts.join(""));
     }
   }
+  /** Counts like Unix wc: lines are newline characters. */
+  count(content) {
+    return {
+      lineCount: (content.match(/\n/g) ?? []).length,
+      wordCount: content.trim() === "" ? 0 : content.trim().split(/\s+/).length,
+      charCount: content.length
+    };
+  }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliFindCommandProcessor = class {
@@ -803,7 +1142,13 @@ var CliFindCommandProcessor = class {
     this.parameters = [
       {
         name: "name",
-        description: "Match filename pattern (glob: * and ? supported)",
+        description: "Match filename pattern (glob: * and ? supported), case-sensitive",
+        required: false,
+        type: "string"
+      },
+      {
+        name: "iname",
+        description: "Like --name, but case-insensitive",
         required: false,
         type: "string"
       },
@@ -815,20 +1160,42 @@ var CliFindCommandProcessor = class {
       },
       {
         name: "maxdepth",
-        description: "Maximum directory depth to search",
+        description: "Maximum depth: 0 is only the start path, 1 its direct children",
         required: false,
         type: "number"
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.find.help.list_files_directories_under", "List files and directories under a path (the current directory by default), searching all subdirectories. The start path itself is listed first. Filter by name with a glob pattern (* and ?; --name is case-sensitive, --iname is not) or by type.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["find [path]", t.t("cli.find.help.list_everything_under_path", "List everything under a path")],
+      ["find [path] --name <pattern>", t.t("cli.find.help.match_names_against_glob", "Match names against a glob")],
+      ["find [path] --iname <pattern>", t.t("cli.find.help.same_ignoring_case", "Same, ignoring case")],
+      ["find [path] --type f|d", t.t("cli.find.help.only_files_f_directories", "Only files (f) or directories (d)")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["find ~/docs", t.t("cli.find.help.list_everything_docs", "List everything in ~/docs")],
+      ['find . --name "*.txt"', t.t("cli.find.help.find_all_txt_files", "Find all .txt files")],
+      ["find . --type d --maxdepth 1", t.t("cli.find.help.directories_near_top", "Directories near the top")],
+      ['find . --name "*.tmp" | xargs rm', t.t("cli.find.help.delete_all_tmp_files", "Delete all .tmp files")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const searchPath = this.parseSearchPath(command) || fs.getCurrentDirectory();
-    const namePattern = command.args["name"] || null;
     const typeFilter = command.args["type"] || null;
-    const maxDepth = command.args["maxdepth"] ? parseInt(command.args["maxdepth"], 10) : Infinity;
+    const maxDepthArg = command.args["maxdepth"];
+    const parsedDepth = parseInt(String(maxDepthArg ?? ""), 10);
+    const maxDepth = maxDepthArg != null && maxDepthArg !== true && !isNaN(parsedDepth) ? parsedDepth : Infinity;
     try {
       const node = fs.getNode(searchPath);
       if (!node) {
@@ -837,24 +1204,25 @@ var CliFindCommandProcessor = class {
         );
         return;
       }
-      if (node.type !== "directory") {
-        context.writer.writeError(
-          `find: '${searchPath}': Not a directory`
-        );
-        return;
-      }
       const resolvedBase = fs.resolvePath(searchPath);
-      const nameRegex = namePattern ? this.globToRegex(namePattern) : null;
+      const nameRegex = this.nameRegex(command);
       const results = [];
-      this.walk(
-        node,
-        resolvedBase,
-        0,
-        maxDepth,
-        nameRegex,
-        typeFilter,
-        results
-      );
+      this.fs = fs;
+      const baseName = resolvedBase.split("/").filter(Boolean).pop() ?? "/";
+      if (this.matches(baseName, node.type, nameRegex, typeFilter)) {
+        results.push(resolvedBase);
+      }
+      if (node.type === "directory" && maxDepth > 0) {
+        this.walk(
+          node,
+          resolvedBase,
+          1,
+          maxDepth,
+          nameRegex,
+          typeFilter,
+          results
+        );
+      }
       for (const r of results) {
         context.writer.writeln(r);
       }
@@ -862,31 +1230,41 @@ var CliFindCommandProcessor = class {
       context.writer.writeError(`find: ${e.message}`);
     }
   }
+  /** `--name` matches case-sensitively, `--iname` ignoring case. */
+  nameRegex(command) {
+    const name = command.args["name"];
+    if (name != null && name !== true) {
+      return this.globToRegex(String(name), false);
+    }
+    const iname = command.args["iname"];
+    if (iname != null && iname !== true) {
+      return this.globToRegex(String(iname), true);
+    }
+    return null;
+  }
+  matches(name, type, nameRegex, typeFilter) {
+    if (nameRegex && !nameRegex.test(name)) return false;
+    if (typeFilter === "f" && type !== "file") return false;
+    if (typeFilter === "d" && type !== "directory") return false;
+    return true;
+  }
   parseSearchPath(command) {
     const raw = command.value || "";
-    const tokens = raw.split(/\s+/).filter(Boolean);
+    const tokens = splitArgs(raw).filter(Boolean);
     return tokens.length > 0 ? tokens[0] : null;
   }
-  globToRegex(pattern) {
+  globToRegex(pattern, ignoreCase) {
     const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     const regexStr = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
-    return new RegExp(`^${regexStr}$`, "i");
+    return new RegExp(`^${regexStr}$`, ignoreCase ? "i" : "");
   }
+  /** Lists the children of `node`, which are at `depth` (1 = direct children). */
   walk(node, currentPath, depth, maxDepth, nameRegex, typeFilter, results) {
-    if (!node.children) return;
-    for (const child of node.children) {
+    const children = this.fs ? readableChildren(this.fs, currentPath) : node.children;
+    if (!children) return;
+    for (const child of children) {
       const childPath = currentPath === "/" ? `/${child.name}` : `${currentPath}/${child.name}`;
-      let matches = true;
-      if (nameRegex && !nameRegex.test(child.name)) {
-        matches = false;
-      }
-      if (typeFilter === "f" && child.type !== "file") {
-        matches = false;
-      }
-      if (typeFilter === "d" && child.type !== "directory") {
-        matches = false;
-      }
-      if (matches) {
+      if (this.matches(child.name, child.type, nameRegex, typeFilter)) {
         results.push(childPath);
       }
       if (child.type === "directory" && depth < maxDepth) {
@@ -940,6 +1318,13 @@ var CliGrepCommandProcessor = class {
         required: false,
         type: "boolean"
       },
+      {
+        name: "quiet",
+        aliases: ["q"],
+        description: "Print nothing; only the exit status tells whether a line matched",
+        required: false,
+        type: "boolean"
+      },
       {
         name: "files-with-matches",
         aliases: ["l"],
@@ -953,11 +1338,52 @@ var CliGrepCommandProcessor = class {
         description: "Select non-matching lines",
         required: false,
         type: "boolean"
+      },
+      {
+        name: "word-regexp",
+        aliases: ["w"],
+        description: "Match only whole words",
+        required: false,
+        type: "boolean"
+      },
+      {
+        name: "only-matching",
+        aliases: ["o"],
+        description: "Print only the matched parts, one per line",
+        required: false,
+        type: "boolean"
+      },
+      {
+        name: "extended-regexp",
+        aliases: ["E"],
+        description: "Extended regular expressions (patterns always are)",
+        required: false,
+        type: "boolean"
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.grep.help.print_lines_match_pattern", "Print the lines that match a pattern. The pattern is a regular expression, matches are highlighted, and the input can be files, directories (with -r) or piped text.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["grep <pattern> <file...>", t.t("cli.grep.help.search_one_more_files", "Search one or more files")],
+      ["grep -r <pattern> <dir>", t.t("cli.grep.help.search_every_file_under", "Search every file under a directory")],
+      ["<command> | grep <pattern>", t.t("cli.grep.help.filter_piped_input", "Filter piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["grep -i error app.log", t.t("cli.grep.help.case_insensitive_search", "Case-insensitive search")],
+      ["grep -r -n TODO src", t.t("cli.grep.help.find_todos_line_numbers", "Find TODOs with line numbers")],
+      ["grep -v ^# config.txt", t.t("cli.grep.help.hide_comment_lines", "Hide comment lines")],
+      ["cat app.log | grep -c ERROR", t.t("cli.grep.help.count_matching_lines", "Count matching lines")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const ignoreCase = command.args["ignore-case"] || command.args["i"] || false;
@@ -966,51 +1392,56 @@ var CliGrepCommandProcessor = class {
     const countOnly = command.args["count"] || command.args["c"] || false;
     const filesOnly = command.args["files-with-matches"] || command.args["l"] || false;
     const invert = command.args["invert-match"] || command.args["v"] || false;
+    const wordRegexp = command.args["word-regexp"] || command.args["w"] || false;
+    const onlyMatching = command.args["only-matching"] || command.args["o"] || false;
+    const quiet = command.args["quiet"] || command.args["q"] || false;
     const { pattern, paths } = this.parseArgs(command);
     if (!pattern) {
       context.writer.writeError(
         "grep: missing pattern. Usage: grep [options] <pattern> <file>"
       );
+      context.process.exit(2, { silent: true });
+      return;
+    }
+    let regex;
+    try {
+      const source = wordRegexp ? `(?<!\\w)(?:${pattern})(?!\\w)` : pattern;
+      regex = new RegExp(source, ignoreCase ? "gi" : "g");
+    } catch {
+      context.writer.writeError(`grep: invalid pattern '${pattern}'`);
+      context.process.exit(2, { silent: true });
       return;
     }
     if (paths.length === 0) {
       if (command.data != null) {
-        let regex2;
-        try {
-          regex2 = new RegExp(pattern, ignoreCase ? "gi" : "g");
-        } catch {
-          context.writer.writeError(`grep: invalid pattern '${pattern}'`);
-          return;
-        }
         const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        this.grepContent(content, null, regex2, {
+        const found2 = this.grepContent(content, null, regex, {
           ignoreCase,
           showLineNum,
           countOnly,
           filesOnly,
-          invert
+          invert,
+          onlyMatching,
+          quiet
         }, context, false);
+        this.exitStatus(context, found2, false);
         return;
       }
       context.writer.writeError(
         "grep: missing file operand. Usage: grep [options] <pattern> <file>"
       );
-      return;
-    }
-    let regex;
-    try {
-      regex = new RegExp(pattern, ignoreCase ? "gi" : "g");
-    } catch {
-      context.writer.writeError(`grep: invalid pattern '${pattern}'`);
+      context.process.exit(2, { silent: true });
       return;
     }
     const filePaths = [];
+    let failed = false;
     for (const p of paths) {
       try {
         if (!fs.exists(p)) {
           context.writer.writeError(
             `grep: ${p}: No such file or directory`
           );
+          failed = true;
           continue;
         }
         if (fs.isDirectory(p)) {
@@ -1018,6 +1449,7 @@ var CliGrepCommandProcessor = class {
             context.writer.writeError(
               `grep: ${p}: Is a directory`
             );
+            failed = true;
             continue;
           }
           this.collectFiles(fs, fs.resolvePath(p), fs.getNode(p), filePaths);
@@ -1026,26 +1458,40 @@ var CliGrepCommandProcessor = class {
         }
       } catch (e) {
         context.writer.writeError(`grep: ${e.message}`);
+        failed = true;
       }
     }
     const multiFile = filePaths.length > 1;
+    let found = 0;
     for (const filePath of filePaths) {
       try {
         const content = fs.readFile(filePath) ?? "";
-        this.grepContent(content, filePath, regex, {
+        found += this.grepContent(content, filePath, regex, {
           ignoreCase,
           showLineNum,
           countOnly,
           filesOnly,
-          invert
+          invert,
+          onlyMatching,
+          quiet
         }, context, multiFile);
       } catch (e) {
         context.writer.writeError(`grep: ${filePath}: ${e.message}`);
+        failed = true;
       }
     }
+    this.exitStatus(context, found, failed);
+  }
+  /**
+   * As Unix grep: 0 when a line matched, 1 when none did, 2 after an
+   * error (so `if grep -q ...` and `grep x f && ...` work).
+   */
+  exitStatus(context, found, failed) {
+    if (found > 0) return;
+    context.process.exit(failed ? 2 : 1, { silent: true });
   }
   grepContent(content, filePath, regex, options, context, multiFile) {
-    const lines = content.split("\n");
+    const lines = splitLines(content);
     let matchCount = 0;
     const matchingLines = [];
     for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
@@ -1058,6 +1504,7 @@ var CliGrepCommandProcessor = class {
         matchingLines.push({ num: lineIdx + 1, text: line });
       }
     }
+    if (options.quiet) return matchCount;
     if (options.filesOnly) {
       if (matchCount > 0 && filePath) {
         context.writer.writeln(filePath);
@@ -1076,6 +1523,18 @@ var CliGrepCommandProcessor = class {
           parts.push(context.writer.wrapInColor(String(m.num), cliCore.CliForegroundColor.Green));
           parts.push(":");
         }
+        if (options.onlyMatching && !options.invert) {
+          regex.lastIndex = 0;
+          const prefix = parts.join("");
+          for (const match of m.text.match(regex) ?? []) {
+            if (match !== "") {
+              context.writer.writeln(
+                prefix + context.writer.wrapInColor(match, cliCore.CliForegroundColor.Red)
+              );
+            }
+          }
+          continue;
+        }
         if (!options.invert) {
           regex.lastIndex = 0;
           const highlighted = m.text.replace(
@@ -1089,10 +1548,11 @@ var CliGrepCommandProcessor = class {
         context.writer.writeln(parts.join(""));
       }
     }
+    return matchCount;
   }
   parseArgs(command) {
     const raw = command.value || "";
-    const tokens = raw.split(/\s+/).filter(Boolean);
+    const tokens = splitArgs(raw).filter(Boolean);
     if (tokens.length === 0) {
       return { pattern: null, paths: [] };
     }
@@ -1105,8 +1565,9 @@ var CliGrepCommandProcessor = class {
     };
   }
   collectFiles(fs, basePath, node, result) {
-    if (!node.children) return;
-    for (const child of node.children) {
+    const children = readableChildren(fs, basePath);
+    if (!children) return;
+    for (const child of children) {
       const childPath = basePath === "/" ? `/${child.name}` : `${basePath}/${child.name}`;
       if (child.type === "file") {
         result.push(childPath);
@@ -1126,8 +1587,25 @@ var CliTacCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F504}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.tac.help.print_file_lines_reverse", "Print a file with its lines in reverse order, last line first. Works on piped input too.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["tac <file>", t.t("cli.tac.help.print_file_bottom_top", "Print a file bottom to top")],
+      ["<command> | tac", t.t("cli.tac.help.reverse_piped_input", "Reverse piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["tac app.log", t.t("cli.tac.help.newest_log_lines_first", "Newest log lines first")],
+      ["cat list.txt | tac", t.t("cli.tac.help.reverse_list", "Reverse a list")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const paths = this.parsePaths(command);
@@ -1171,7 +1649,7 @@ var CliTacCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliBasenameCommandProcessor = class {
@@ -1184,6 +1662,24 @@ var CliBasenameCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F4DB}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.basename.help.print_last_part_path", "Print the last part of a path, the file or directory name, without the directories in front. If a suffix is given, it is removed from the end too.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["basename <path>", t.t("cli.basename.help.name_without_directories", "Name without the directories")],
+      ["basename <path> <suffix>", t.t("cli.basename.help.also_remove_trailing_suffix", "Also remove a trailing suffix")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["basename /home/user/notes.txt", t.t("cli.basename.help.prints_notes_txt", "Prints notes.txt")],
+      ["basename /home/user/notes.txt .txt", t.t("cli.basename.help.prints_notes", "Prints notes")],
+      ["basename /home/user/", t.t("cli.basename.help.prints_user", "Prints user")]
+    ]);
+  }
   async processCommand(command, context) {
     const tokens = this.parseTokens(command);
     if (tokens.length === 0) {
@@ -1209,7 +1705,7 @@ var CliBasenameCommandProcessor = class {
   }
   parseTokens(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliDirnameCommandProcessor = class {
@@ -1222,6 +1718,23 @@ var CliDirnameCommandProcessor = class {
     this.valueRequired = true;
     this.metadata = { icon: "\u{1F4C2}", module: "file management" };
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.dirname.help.print_directory_part_path", "Print the directory part of a path, everything before the last /. A bare name with no / gives . (the current directory).")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["dirname <path>", t.t("cli.dirname.help.path_without_last_part", "Path without its last part")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["dirname /home/user/notes.txt", t.t("cli.dirname.help.prints_home_user", "Prints /home/user")],
+      ["dirname notes.txt", t.t("cli.dirname.help.prints", "Prints .")],
+      ["dirname /home", t.t("cli.dirname.help.prints_2", "Prints /")]
+    ]);
+  }
   async processCommand(command, context) {
     const tokens = this.parseTokens(command);
     if (tokens.length === 0) {
@@ -1248,7 +1761,7 @@ var CliDirnameCommandProcessor = class {
   }
   parseTokens(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliSortCommandProcessor = class {
@@ -1298,117 +1811,97 @@ var CliSortCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.sort.help.sort_lines_file_piped", "Sort the lines of a file or piped input, alphabetically by default. Sort numerically, in reverse, by a field, or drop duplicates. Several files are sorted together into one list.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["sort <file>", t.t("cli.sort.help.sort_lines_alphabetically", "Sort lines alphabetically")],
+      [
+        "sort -k <n> -t <sep> <file>",
+        t.t("cli.sort.help.sort_field_split", "Sort by field <n>, split on <sep>")
+      ],
+      ["<command> | sort", t.t("cli.sort.help.sort_piped_input", "Sort piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["sort names.txt", t.t("cli.sort.help.z", "A to Z")],
+      ["sort -n -r scores.txt", t.t("cli.sort.help.largest_number_first", "Largest number first")],
+      ["sort -t , -k 2 data.csv", t.t("cli.sort.help.sort_csv_second_column", "Sort a CSV by its second column")],
+      ["cat words.txt | sort -u", t.t("cli.sort.help.sorted_without_duplicates", "Sorted, without duplicates")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const reverse = !!command.args["r"] || !!command.args["reverse"];
     const numeric = !!command.args["n"] || !!command.args["numeric-sort"];
     const unique = !!command.args["u"] || !!command.args["unique"];
-    const keyField = command.args["k"] || command.args["key"];
-    const delimiter = command.args["t"] || command.args["field-separator"];
+    const keyField = command.args["k"] ?? command.args["key"];
+    const delimiter = command.args["t"] ?? command.args["field-separator"];
     const paths = this.parsePaths(command);
+    let lines = [];
     if (paths.length === 0) {
-      if (command.data != null) {
-        const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        let lines = content.split("\n");
-        if (lines.length > 0 && lines[lines.length - 1] === "") {
-          lines.pop();
-        }
-        const keyIndex = keyField ? parseInt(keyField, 10) - 1 : void 0;
-        lines.sort((a, b) => {
-          let va = a;
-          let vb = b;
-          if (keyIndex !== void 0 && keyIndex >= 0) {
-            const sepRegex = delimiter ? new RegExp(
-              delimiter.replace(
-                /[.*+?^${}()|[\]\\]/g,
-                "\\$&"
-              )
-            ) : /\s+/;
-            const fieldsA = a.split(sepRegex);
-            const fieldsB = b.split(sepRegex);
-            va = fieldsA[keyIndex] || "";
-            vb = fieldsB[keyIndex] || "";
-          }
-          if (numeric) {
-            const na = parseFloat(va) || 0;
-            const nb = parseFloat(vb) || 0;
-            return na - nb;
-          }
-          return va.localeCompare(vb);
-        });
-        if (unique) {
-          lines = lines.filter(
-            (line, i, arr) => i === 0 || line !== arr[i - 1]
-          );
-        }
-        if (reverse) {
-          lines.reverse();
-        }
-        context.writer.writeln(lines.join("\n"));
+      if (command.data == null) {
+        context.writer.writeError("sort: missing file operand");
         return;
       }
-      context.writer.writeError("sort: missing file operand");
-      return;
-    }
-    for (const path of paths) {
-      try {
-        if (fs.isDirectory(path)) {
-          context.writer.writeError(`sort: ${path}: Is a directory`);
-          continue;
-        }
-        const content = fs.readFile(path);
-        if (content === null) {
-          context.writer.writeError(
-            `sort: ${path}: No such file or directory`
-          );
-          continue;
-        }
-        let lines = content.split("\n");
-        if (lines.length > 0 && lines[lines.length - 1] === "") {
-          lines.pop();
-        }
-        const keyIndex = keyField ? parseInt(keyField, 10) - 1 : void 0;
-        lines.sort((a, b) => {
-          let va = a;
-          let vb = b;
-          if (keyIndex !== void 0 && keyIndex >= 0) {
-            const sepRegex = delimiter ? new RegExp(
-              delimiter.replace(
-                /[.*+?^${}()|[\]\\]/g,
-                "\\$&"
-              )
-            ) : /\s+/;
-            const fieldsA = a.split(sepRegex);
-            const fieldsB = b.split(sepRegex);
-            va = fieldsA[keyIndex] || "";
-            vb = fieldsB[keyIndex] || "";
+      lines = splitLines(pipedText(command.data));
+    } else {
+      for (const path of paths) {
+        try {
+          if (fs.isDirectory(path)) {
+            context.writer.writeError(
+              `sort: ${path}: Is a directory`
+            );
+            continue;
           }
-          if (numeric) {
-            const na = parseFloat(va) || 0;
-            const nb = parseFloat(vb) || 0;
-            return na - nb;
+          const content = fs.readFile(path);
+          if (content === null) {
+            context.writer.writeError(
+              `sort: ${path}: No such file or directory`
+            );
+            continue;
           }
-          return va.localeCompare(vb);
-        });
-        if (unique) {
-          lines = lines.filter(
-            (line, i, arr) => i === 0 || line !== arr[i - 1]
-          );
+          lines.push(...splitLines(content));
+        } catch (e) {
+          context.writer.writeError(`sort: ${e.message}`);
         }
-        if (reverse) {
-          lines.reverse();
-        }
-        context.writer.writeln(lines.join("\n"));
-      } catch (e) {
-        context.writer.writeError(`sort: ${e.message}`);
       }
     }
+    const keyIndex = keyField != null && keyField !== true ? parseInt(String(keyField), 10) - 1 : void 0;
+    const sepRegex = delimiter != null && delimiter !== true ? new RegExp(
+      String(delimiter).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    ) : /\s+/;
+    const keyOf = (line) => keyIndex !== void 0 && keyIndex >= 0 ? line.split(sepRegex)[keyIndex] || "" : line;
+    const compare = (a, b) => {
+      const va = keyOf(a);
+      const vb = keyOf(b);
+      if (numeric) {
+        return (parseFloat(va) || 0) - (parseFloat(vb) || 0);
+      }
+      return va.localeCompare(vb);
+    };
+    lines.sort(compare);
+    if (unique) {
+      lines = lines.filter(
+        (line, i, arr) => i === 0 || compare(line, arr[i - 1]) !== 0
+      );
+    }
+    if (reverse) {
+      lines.reverse();
+    }
+    if (lines.length > 0) {
+      context.writer.writeln(lines.join("\n"));
+    }
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliUniqCommandProcessor = class {
@@ -1451,8 +1944,26 @@ var CliUniqCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.uniq.help.collapse_repeated_lines_next", "Collapse repeated lines that are next to each other into one. Only adjacent duplicates are merged, so sort the input first to catch them all.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["uniq <file>", t.t("cli.uniq.help.drop_adjacent_duplicate_lines", "Drop adjacent duplicate lines")],
+      ["<command> | uniq", t.t("cli.uniq.help.filter_piped_input", "Filter piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["uniq log.txt", t.t("cli.uniq.help.collapse_repeated_lines", "Collapse repeated lines")],
+      ["sort words.txt | uniq -c", t.t("cli.uniq.help.count_how_often_each", "Count how often each line appears")],
+      ["sort words.txt | uniq -d", t.t("cli.uniq.help.show_only_duplicated_lines", "Show only the duplicated lines")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const showCount = !!command.args["c"] || !!command.args["count"];
@@ -1463,7 +1974,7 @@ var CliUniqCommandProcessor = class {
     if (paths.length === 0) {
       if (command.data != null) {
         const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        let lines = content.split("\n");
+        const lines = content.split("\n");
         if (lines.length > 0 && lines[lines.length - 1] === "") {
           lines.pop();
         }
@@ -1511,7 +2022,7 @@ var CliUniqCommandProcessor = class {
           );
           continue;
         }
-        let lines = content.split("\n");
+        const lines = content.split("\n");
         if (lines.length > 0 && lines[lines.length - 1] === "") {
           lines.pop();
         }
@@ -1546,7 +2057,7 @@ var CliUniqCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliCutCommandProcessor = class {
@@ -1582,26 +2093,45 @@ var CliCutCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.cut.help.print_selected_parts_each", "Print selected parts of each line: fields split by a delimiter (-f, tab by default) or character positions (-c). A list can be single numbers, ranges or both, such as 1,3 or 2-4 or 3-.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["cut -d <sep> -f <list> <file>", t.t("cli.cut.help.select_fields", "Select fields")],
+      ["cut -c <list> <file>", t.t("cli.cut.help.select_character_positions", "Select character positions")],
+      ["<command> | cut -f <list>", t.t("cli.cut.help.cut_piped_input", "Cut piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cut -d , -f 1,3 data.csv", t.t("cli.cut.help.first_third_csv_column", "First and third CSV column")],
+      ["cut -c 1-10 notes.txt", t.t("cli.cut.help.first_10_characters_each", "First 10 characters of each line")],
+      ["cat users.txt | cut -d : -f 1-2", t.t("cli.cut.help.first_two_fields_split", "First two fields split on :")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const delimiter = command.args["d"] || command.args["delimiter"] || "	";
-    const fieldsSpec = command.args["f"] || command.args["fields"];
-    const charsSpec = command.args["c"] || command.args["characters"];
-    if (!fieldsSpec && !charsSpec) {
+    const fieldsSpec = command.args["f"] ?? command.args["fields"];
+    const charsSpec = command.args["c"] ?? command.args["characters"];
+    if ((fieldsSpec === void 0 || fieldsSpec === "") && (charsSpec === void 0 || charsSpec === "")) {
       context.writer.writeError(
         "cut: you must specify either -f (fields) or -c (characters)"
       );
       return;
     }
-    const spec = fieldsSpec || charsSpec;
+    const spec = String(fieldsSpec ?? charsSpec);
     const indices = this.parseSpec(spec);
     const paths = this.parsePaths(command);
     if (paths.length === 0) {
       if (command.data != null) {
         const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-        let lines = content.split("\n");
+        const lines = content.split("\n");
         if (lines.length > 0 && lines[lines.length - 1] === "") {
           lines.pop();
         }
@@ -1643,7 +2173,7 @@ var CliCutCommandProcessor = class {
           );
           continue;
         }
-        let lines = content.split("\n");
+        const lines = content.split("\n");
         if (lines.length > 0 && lines[lines.length - 1] === "") {
           lines.pop();
         }
@@ -1703,7 +2233,7 @@ var CliCutCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliPasteCommandProcessor = class {
@@ -1732,23 +2262,47 @@ var CliPasteCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.paste.help.join_files_side_side", "Join files side by side: line 1 of each file goes on one output line, separated by a tab, then line 2, and so on. With -s, each file is joined onto a single line instead. Piped input is read as the file - (or as the only input when no file is named); -d takes a list of delimiters used in turn.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["paste <file1> <file2...>", t.t("cli.paste.help.merge_files_line_line", "Merge files line by line")],
+      ["paste -s <file>", t.t("cli.paste.help.join_all_lines_file", "Join all lines of a file into one")],
+      ["<command> | paste - <file>", t.t("cli.paste.help.merge_piped_input_file", "Merge piped input with a file")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["paste names.txt ages.txt", t.t("cli.paste.help.two_columns_tab_separated", "Two columns, tab separated")],
+      ["paste -d , a.txt b.txt", t.t("cli.paste.help.merge_comma_separated", "Merge as comma-separated")],
+      ["paste -s -d , list.txt", t.t("cli.paste.help.turn_list_one_csv", "Turn a list into one CSV line")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const delimiter = command.args["d"] || command.args["delimiters"] || "	";
+    const delimiterArg = command.args["d"] ?? command.args["delimiters"] ?? "	";
+    const delimiters = this.parseDelimiters(String(delimiterArg));
     const serial = !!command.args["s"] || !!command.args["serial"];
     const paths = this.parsePaths(command);
+    const hasStdin = command.data != null;
     if (paths.length === 0) {
-      context.writer.writeError("paste: missing file operand");
-      return;
-    }
-    if (!serial && paths.length < 2) {
-      context.writer.writeError("paste: missing file operand");
-      return;
+      if (!hasStdin) {
+        context.writer.writeError("paste: missing file operand");
+        return;
+      }
+      paths.push("-");
     }
     const fileLines = [];
     for (const path of paths) {
+      if (path === "-" && hasStdin) {
+        fileLines.push(splitLines(pipedText(command.data)));
+        continue;
+      }
       try {
         if (fs.isDirectory(path)) {
           context.writer.writeError(
@@ -1763,20 +2317,18 @@ var CliPasteCommandProcessor = class {
           );
           return;
         }
-        let lines = content.split("\n");
-        if (lines.length > 0 && lines[lines.length - 1] === "") {
-          lines.pop();
-        }
-        fileLines.push(lines);
+        fileLines.push(splitLines(content));
       } catch (e) {
         context.writer.writeError(`paste: ${e.message}`);
         return;
       }
     }
+    const join = (parts) => parts.reduce(
+      (line, part, i) => i === 0 ? part : line + delimiters[(i - 1) % delimiters.length] + part,
+      ""
+    );
     if (serial) {
-      const output = fileLines.map(
-        (lines) => lines.join(delimiter)
-      );
+      const output = fileLines.map((lines) => join(lines));
       context.writer.writeln(output.join("\n"));
     } else {
       const maxLines = Math.max(
@@ -1784,21 +2336,59 @@ var CliPasteCommandProcessor = class {
       );
       const output = [];
       for (let i = 0; i < maxLines; i++) {
-        const parts = fileLines.map((lines) => lines[i] || "");
-        output.push(parts.join(delimiter));
+        output.push(join(fileLines.map((lines) => lines[i] ?? "")));
       }
       context.writer.writeln(output.join("\n"));
     }
   }
+  /** `-d` list: each character in turn, with \t, \n, \\ and \0 (empty) escapes. */
+  parseDelimiters(list) {
+    const result = [];
+    for (let i = 0; i < list.length; i++) {
+      if (list[i] === "\\" && i + 1 < list.length) {
+        const next = list[++i];
+        result.push(
+          next === "t" ? "	" : next === "n" ? "\n" : next === "0" ? "" : next
+        );
+      } else {
+        result.push(list[i]);
+      }
+    }
+    return result.length > 0 ? result : ["	"];
+  }
+  /**
+   * The file operands. The engine drops a lone `-` from the value, so with
+   * piped input they are read from the raw command line to keep it.
+   */
   parsePaths(command) {
-    const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    const fromValue = splitArgs(command.value || "").filter(Boolean);
+    if (command.data == null || !command.rawCommand) return fromValue;
+    const words = splitArgs(command.rawCommand).slice(1);
+    if (!words.includes("-")) return fromValue;
+    const result = [];
+    for (let i = 0; i < words.length; i++) {
+      const word = words[i];
+      if (word === "-" || !word.startsWith("-")) {
+        result.push(word);
+      } else if (/^(-d|--delimiters)$/.test(word)) {
+        i++;
+      }
+    }
+    return result;
   }
 };
 function expandSet(set) {
   const chars = [];
   let i = 0;
   while (i < set.length) {
+    if (set[i] === "\\" && i + 1 < set.length) {
+      const next = set[i + 1];
+      chars.push(
+        next === "n" ? "\n" : next === "t" ? "	" : next === "r" ? "\r" : next
+      );
+      i += 2;
+      continue;
+    }
     if (set[i] === "[" && set[i + 1] === ":") {
       const end = set.indexOf(":]", i + 2);
       if (end !== -1) {
@@ -1808,7 +2398,7 @@ function expandSet(set) {
         continue;
       }
     }
-    if (i + 2 < set.length && set[i + 1] === "-" && set[i + 2] !== void 0) {
+    if (i + 2 < set.length && set[i + 1] === "-" && set[i + 2] !== "\\") {
       const start = set.charCodeAt(i);
       const finish = set.charCodeAt(i + 2);
       if (start <= finish) {
@@ -1878,7 +2468,7 @@ function parseTokens(raw) {
 var CliTrCommandProcessor = class {
   constructor() {
     this.command = "tr";
-    this.description = "Translate or delete characters in a file";
+    this.description = "Translate or delete characters in piped input";
     this.author = cliCore.DefaultLibraryAuthor;
     this.version = LIBRARY_VERSION;
     this.acceptsRawInput = true;
@@ -1886,103 +2476,76 @@ var CliTrCommandProcessor = class {
     this.metadata = { icon: "\u{1F500}", module: "file management" };
     this.parameters = [
       {
-        name: "d",
+        name: "delete",
+        aliases: ["d"],
         description: "Delete characters in SET1",
         required: false,
         type: "boolean"
       },
       {
-        name: "s",
+        name: "squeeze-repeats",
+        aliases: ["s"],
         description: "Squeeze repeated characters in last operand set",
         required: false,
         type: "boolean"
       }
     ];
   }
-  async processCommand(command, context) {
-    const fs = context.services.get(
-      IFileSystemService_TOKEN
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.tr.help.translate_characters_set1_matching", "Translate characters from SET1 into the matching characters of SET2, delete them (-d) or squeeze repeats into one (-s). Sets can use ranges like a-z and classes like [:upper:], [:lower:], [:digit:], [:alpha:], [:alnum:] and [:space:]. Escapes \\n, \\t and \\\\ are understood. Like Unix tr, it reads only piped input and takes no file operands: to transform a file, pipe it in with cat.")
     );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["<command> | tr <set1> <set2>", t.t("cli.tr.help.replace_characters", "Replace characters")],
+      ["<command> | tr -d <set1>", t.t("cli.tr.help.delete_characters", "Delete characters")],
+      ["<command> | tr -s <set1> [set2]", t.t("cli.tr.help.squeeze_repeated_characters", "Squeeze repeated characters")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cat notes.txt | tr a-z A-Z", t.t("cli.tr.help.convert_file_upper_case", "Convert a file to upper case")],
+      ["echo hello | tr a-z A-Z", t.t("cli.tr.help.upper_case_piped_text", "Upper-case piped text")],
+      ["cat notes.txt | tr -d 0-9", t.t("cli.tr.help.remove_all_digits", "Remove all digits")],
+      ["cat notes.txt | tr -s ' '", t.t("cli.tr.help.collapse_runs_spaces", "Collapse runs of spaces")]
+    ]);
+  }
+  async processCommand(command, context) {
     const raw = command.value || "";
     const positional = parseTokens(raw);
-    const deleteMode = !!command.args["d"];
-    const squeezeMode = !!command.args["s"];
+    const deleteMode = !!command.args["d"] || !!command.args["delete"];
+    const squeezeMode = !!command.args["s"] || !!command.args["squeeze-repeats"];
     if (positional.length === 0) {
-      context.writer.writeError("tr: missing operand");
+      this.fail(context, "tr: missing operand");
       return;
     }
-    let set1Str;
-    let set2Str;
-    let filePath;
-    if (deleteMode && squeezeMode) {
-      if (positional.length < 2) {
-        context.writer.writeError("tr: missing operand");
-        return;
-      }
-      set1Str = positional[0];
-      set2Str = positional[1];
-      if (positional.length >= 3) {
-        filePath = positional[2];
-      }
-    } else if (deleteMode) {
-      if (positional.length < 1) {
-        context.writer.writeError("tr: missing operand");
-        return;
-      }
-      set1Str = positional[0];
-      if (positional.length >= 2) {
-        filePath = positional[1];
-      }
+    let setCount;
+    if (deleteMode) {
+      setCount = squeezeMode ? 2 : 1;
     } else if (squeezeMode) {
-      if (positional.length < 1) {
-        context.writer.writeError("tr: missing operand");
-        return;
-      }
-      if (positional.length >= 3) {
-        set1Str = positional[0];
-        set2Str = positional[1];
-        filePath = positional[2];
-      } else if (positional.length === 2) {
-        set1Str = positional[0];
-        filePath = positional[1];
-      } else {
-        set1Str = positional[0];
-      }
+      setCount = Math.min(positional.length, 2);
     } else {
-      if (positional.length < 2) {
-        context.writer.writeError("tr: missing operand");
-        return;
-      }
-      set1Str = positional[0];
-      set2Str = positional[1];
-      if (positional.length >= 3) {
-        filePath = positional[2];
-      }
+      setCount = 2;
     }
-    let content;
-    if (filePath) {
-      try {
-        if (fs.isDirectory(filePath)) {
-          context.writer.writeError(`tr: ${filePath}: Is a directory`);
-          return;
-        }
-        content = fs.readFile(filePath);
-        if (content === null) {
-          context.writer.writeError(
-            `tr: ${filePath}: No such file or directory`
-          );
-          return;
-        }
-      } catch (e) {
-        context.writer.writeError(`tr: ${e.message}`);
-        return;
-      }
-    } else if (command.data != null) {
-      content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-    } else {
-      context.writer.writeError("tr: missing file operand");
+    if (positional.length < setCount) {
+      this.fail(context, "tr: missing operand");
+      return;
+    }
+    if (positional.length > setCount) {
+      this.fail(context, `tr: extra operand '${positional[setCount]}'`);
+      return;
+    }
+    if (command.data == null) {
+      this.fail(
+        context,
+        "tr: no input: tr reads only piped input and takes no file operands; use 'cat file | tr a-z A-Z'"
+      );
       return;
     }
+    const set1Str = positional[0];
+    const set2Str = setCount === 2 ? positional[1] : void 0;
+    const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
     try {
       const set1 = expandSet(set1Str);
       const set1Set = new Set(set1);
@@ -2005,9 +2568,13 @@ var CliTrCommandProcessor = class {
       }
       context.writer.writeln(result);
     } catch (e) {
-      context.writer.writeError(`tr: ${e.message}`);
+      this.fail(context, `tr: ${e.message}`);
     }
   }
+  fail(context, message) {
+    context.writer.writeError(message);
+    context.process.exit(1, { silent: true });
+  }
   deleteChars(content, deleteSet) {
     let result = "";
     for (const ch of content) {
@@ -2054,8 +2621,24 @@ var CliStatCommandProcessor = class {
     this.metadata = { icon: "\u{1F4CA}", module: "file management" };
     this.parameters = [];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.stat.help.show_details_about_files", "Show details about files or directories: full path, size, type, permissions, owner, group, and when it was created and last modified.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["stat <path...>", t.t("cli.stat.help.show_details_each_path", "Show details for each path")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["stat notes.txt", t.t("cli.stat.help.details_one_file", "Details of one file")],
+      ["stat ~/docs notes.txt", t.t("cli.stat.help.several_paths_once", "Several paths at once")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const paths = this.parsePaths(command);
@@ -2065,6 +2648,10 @@ var CliStatCommandProcessor = class {
     }
     for (const path of paths) {
       const resolved = fs.resolvePath(path);
+      if (fs.canTraverse && !fs.canTraverse(resolved)) {
+        context.writer.writeError(`stat: cannot stat '${path}': Permission denied`);
+        continue;
+      }
       const node = fs.getNode(resolved);
       if (!node) {
         context.writer.writeError(
@@ -2086,7 +2673,7 @@ var CliStatCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliChmodCommandProcessor = class {
@@ -2107,8 +2694,30 @@ var CliChmodCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.chmod.help.change_who_can_read", "Change who can read (r), write (w) and execute (x) a file. Use an octal mode such as 755 or a symbolic one: who (u user, g group, o others, a all), then + to add, - to remove or = to set, then the permissions.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["chmod <mode> <file...>", t.t("cli.chmod.help.set_permissions", "Set permissions")],
+      [
+        "chmod -R <mode> <dir>",
+        t.t("cli.chmod.help.apply_directory_everything", "Apply to a directory and everything in it")
+      ]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["chmod 644 notes.txt", t.t("cli.chmod.help.rw_r_r_owner", "rw-r--r--: owner writes, others read")],
+      ["chmod u+x script.sh", t.t("cli.chmod.help.let_owner_execute", "Let the owner execute it")],
+      ["chmod go-w shared.txt", t.t("cli.chmod.help.take_away_write_group", "Take away write for group and others")],
+      ["chmod -R 755 site", t.t("cli.chmod.help.set_whole_directory_tree", "Set a whole directory tree")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const { recursive, mode, paths } = this.parseArgs(command);
@@ -2140,7 +2749,7 @@ var CliChmodCommandProcessor = class {
   }
   parseArgs(command) {
     const raw = command.value || "";
-    const tokens = raw.split(/\s+/).filter(Boolean);
+    const tokens = splitArgs(raw).filter(Boolean);
     const recursive = command.args["R"] || false;
     const mode = tokens.length > 0 ? tokens[0] : null;
     const paths = tokens.slice(1);
@@ -2227,8 +2836,33 @@ var CliChownCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.chown.help.change_owner_group_files", "Change the owner and/or group of files. Give user, user:group, user: (owner only) or :group (group only).")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      [
+        "chown <user>[:<group>] <file...>",
+        t.t("cli.chown.help.change_owner_group_if", "Change owner, and group if given")
+      ],
+      ["chown :<group> <file>", t.t("cli.chown.help.change_only_group", "Change only the group")],
+      [
+        "chown -R <user> <dir>",
+        t.t("cli.chown.help.apply_directory_everything", "Apply to a directory and everything in it")
+      ]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["chown alice notes.txt", t.t("cli.chown.help.make_alice_owner", "Make alice the owner")],
+      ["chown alice:staff report.txt", t.t("cli.chown.help.set_owner_group", "Set owner and group")],
+      ["chown -R bob ~/shared", t.t("cli.chown.help.give_bob_whole_directory", "Give bob a whole directory")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const { recursive, ownerSpec, paths } = this.parseArgs(command);
@@ -2260,7 +2894,7 @@ var CliChownCommandProcessor = class {
   }
   parseArgs(command) {
     const raw = command.value || "";
-    const tokens = raw.split(/\s+/).filter(Boolean);
+    const tokens = splitArgs(raw).filter(Boolean);
     const recursive = command.args["R"] || false;
     const ownerSpec = tokens.length > 0 ? tokens[0] : null;
     const paths = tokens.slice(1);
@@ -2298,7 +2932,6 @@ var CliDuCommandProcessor = class {
     this.author = cliCore.DefaultLibraryAuthor;
     this.version = LIBRARY_VERSION;
     this.acceptsRawInput = true;
-    this.valueRequired = true;
     this.metadata = { icon: "\u{1F4CF}", module: "file management" };
     this.parameters = [
       {
@@ -2322,17 +2955,39 @@ var CliDuCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.du.help.show_how_much_space", "Show how much space files and directories use, in bytes. For a directory, every subdirectory is listed with its total size; use -s for just the total or -d to limit how deep it goes.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["du [path...]", t.t("cli.du.help.sizes_path_default_current", "Sizes of a path (default: the current directory) and its subdirectories")],
+      ["du -s <path>", t.t("cli.du.help.only_total", "Only the total")],
+      ["du -d <n> <path>", t.t("cli.du.help.only_levels_deep", "Only <n> levels deep")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["du ~/docs", t.t("cli.du.help.size_each_directory_docs", "Size of each directory in ~/docs")],
+      ["du -h -s ~", t.t("cli.du.help.total_home_k_m", "Total of your home in K/M/G")],
+      ["du -h -d 1 .", t.t("cli.du.help.size_each_top_level", "Size of each top-level folder")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const { humanReadable, summaryOnly, maxDepth, paths } = this.parseArgs(command);
     if (paths.length === 0) {
-      context.writer.writeError("du: missing operand");
-      return;
+      paths.push(fs.getCurrentDirectory());
     }
     for (const path of paths) {
       const resolved = fs.resolvePath(path);
+      if (fs.canTraverse && !fs.canTraverse(resolved)) {
+        context.writer.writeError(`du: cannot access '${path}': Permission denied`);
+        continue;
+      }
       const node = fs.getNode(resolved);
       if (!node) {
         context.writer.writeError(
@@ -2346,6 +3001,7 @@ var CliDuCommandProcessor = class {
         );
       } else {
         const entries = [];
+        this.fs = fs;
         this.collectSizes(node, resolved, 0, maxDepth, summaryOnly, entries);
         for (const entry of entries) {
           context.writer.writeln(
@@ -2357,10 +3013,12 @@ var CliDuCommandProcessor = class {
   }
   parseArgs(command) {
     const raw = command.value || "";
-    const paths = raw.split(/\s+/).filter(Boolean);
+    const paths = splitArgs(raw).filter(Boolean);
     const humanReadable = !!command.args["h"];
     const summaryOnly = !!command.args["s"];
-    const maxDepth = command.args["d"] || command.args["max-depth"] ? parseInt(command.args["d"] || command.args["max-depth"] || "0", 10) : Infinity;
+    const depthArg = command.args["max-depth"] ?? command.args["d"];
+    const parsedDepth = parseInt(String(depthArg ?? ""), 10);
+    const maxDepth = depthArg != null && depthArg !== true && !isNaN(parsedDepth) ? parsedDepth : Infinity;
     return { humanReadable, summaryOnly, maxDepth, paths };
   }
   collectSizes(node, path, depth, maxDepth, summaryOnly, entries) {
@@ -2368,8 +3026,9 @@ var CliDuCommandProcessor = class {
       return node.size;
     }
     let total = 0;
-    if (node.children) {
-      for (const child of node.children) {
+    const children = this.fs ? readableChildren(this.fs, path) : node.children;
+    if (children) {
+      for (const child of children) {
         const childPath = path === "/" ? `/${child.name}` : `${path}/${child.name}`;
         total += this.collectSizes(
           child,
@@ -2416,11 +3075,34 @@ var CliLnCommandProcessor = class {
         description: "Create a symbolic link",
         required: false,
         type: "boolean"
+      },
+      {
+        name: "force",
+        aliases: ["f"],
+        description: "Replace an existing file at the link path",
+        required: false,
+        type: "boolean"
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.ln.help.create_symbolic_link_new", "Create a symbolic link: a new path that points to another file or directory. Only symbolic links (-s) are supported, and the target does not need to exist yet.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["ln -s <target> <link>", t.t("cli.ln.help.create_pointing", "Create <link> pointing at <target>")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["ln -s ~/docs/notes.txt notes", t.t("cli.ln.help.shortcut_file", "Shortcut to a file")],
+      ["ln -s /var/log logs", t.t("cli.ln.help.shortcut_directory", "Shortcut to a directory")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const { symbolic, target, linkName } = this.parseArgs(command);
@@ -2436,6 +3118,10 @@ var CliLnCommandProcessor = class {
     }
     const resolvedLink = fs.resolvePath(linkName);
     const resolvedTarget = fs.resolvePath(target);
+    const force = !!(command.args["force"] || command.args["f"]);
+    if (force && fs.exists(resolvedLink) && !fs.isDirectory(resolvedLink)) {
+      fs.remove(resolvedLink);
+    }
     if (fs.exists(resolvedLink)) {
       context.writer.writeError(
         `ln: failed to create symbolic link '${linkName}': File exists`
@@ -2452,7 +3138,7 @@ var CliLnCommandProcessor = class {
   }
   parseArgs(command) {
     const raw = command.value || "";
-    const tokens = raw.split(/\s+/).filter(Boolean);
+    const tokens = splitArgs(raw).filter(Boolean);
     const symbolic = command.args["s"] || false;
     return {
       symbolic,
@@ -2487,25 +3173,75 @@ var CliSedCommandProcessor = class {
       {
         name: "expression",
         aliases: ["e"],
-        description: "Add the expression to the commands to be executed",
+        description: "Add the expression to the commands to be executed (repeatable)",
         required: false,
-        type: "string"
+        type: "array"
+      },
+      {
+        name: "regexp-extended",
+        aliases: ["E", "r"],
+        description: "Use extended regular expressions: (, ), +, ?, | and { } without backslashes",
+        required: false,
+        type: "boolean"
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.sed.help.edit_text_line_line", "Edit text line by line with a script: substitute (s/old/new/), delete (d), print (p) or quit (q), optionally limited to a line number, a range (1,5, 3,$ or /start/,/end/) or lines matching /regex/; ! after an address inverts it and ; separates commands. The replacement can use & (the match) and \\1 to \\9 (groups, written \\(...\\) or, with -E, (...)). Reads files or piped input and prints the result, or rewrites the files with -i.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["sed '<script>' <file>", t.t("cli.sed.help.print_edited_file", "Print the edited file")],
+      ["sed -i '<script>' <file>", t.t("cli.sed.help.save_edits_file", "Save the edits into the file")],
+      ["sed -n '<script>p' <file>", t.t("cli.sed.help.print_only_selected_lines", "Print only selected lines")],
+      ["<command> | sed '<script>'", t.t("cli.sed.help.edit_piped_input", "Edit piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["sed 's/cat/dog/g' pets.txt", t.t("cli.sed.help.replace_every_cat_dog", "Replace every cat with dog")],
+      ["sed -i 's/v1/v2/' config.txt", t.t("cli.sed.help.edit_file_place", "Edit the file in place")],
+      ["sed '/^#/d' config.txt", t.t("cli.sed.help.drop_comment_lines", "Drop comment lines")],
+      ["sed -n '1,5p' notes.txt", t.t("cli.sed.help.print_lines_1_5", "Print lines 1 to 5")],
+      ["sed -E 's/(\\w+) (\\w+)/\\2 \\1/' names.txt", t.t("cli.sed.help.swap_two_words", "Swap two words")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const { inPlace, suppress, expressions, filePath } = this.parseRawCommand(command);
+    const { inPlace, suppress, extended, expressions, filePaths } = this.parseRawCommand(command);
     if (expressions.length === 0) {
       context.writer.writeError(
         "sed: missing expression. Usage: sed [options] 'expression' <file>"
       );
       return;
     }
-    let content;
-    if (filePath) {
+    const parse = () => {
+      try {
+        return expressions.flatMap((e) => this.parseScript(e, extended));
+      } catch (e) {
+        context.writer.writeError(`sed: ${e.message}`);
+        return null;
+      }
+    };
+    if (filePaths.length === 0) {
+      if (command.data == null) {
+        context.writer.writeError(
+          "sed: missing file operand. Usage: sed [options] 'expression' <file>"
+        );
+        return;
+      }
+      const script2 = parse();
+      if (!script2) return;
+      const content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
+      this.writeLines(context, this.run(script2, splitLines(content), suppress));
+      return;
+    }
+    const contents = [];
+    for (const filePath of filePaths) {
       const resolved = fs.resolvePath(filePath);
       if (!fs.exists(resolved)) {
         context.writer.writeError(
@@ -2517,116 +3253,125 @@ var CliSedCommandProcessor = class {
         context.writer.writeError(`sed: ${filePath}: Is a directory`);
         return;
       }
-      content = fs.readFile(resolved) ?? "";
-    } else if (command.data != null) {
-      content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-    } else {
-      context.writer.writeError(
-        "sed: missing file operand. Usage: sed [options] 'expression' <file>"
-      );
-      return;
-    }
-    const parsedExpressions = [];
-    for (const expr of expressions) {
       try {
-        const parsed = this.parseExpression(expr);
-        parsedExpressions.push(parsed);
+        contents.push(fs.readFile(resolved) ?? "");
       } catch (e) {
         context.writer.writeError(`sed: ${e.message}`);
         return;
       }
     }
-    const lines = content.split("\n");
-    const outputLines = [];
+    if (inPlace) {
+      for (let i = 0; i < filePaths.length; i++) {
+        const script2 = parse();
+        if (!script2) return;
+        const output = this.run(script2, splitLines(contents[i]), suppress);
+        const keepNewline = contents[i].endsWith("\n") && output.length > 0;
+        try {
+          fs.writeFile(
+            fs.resolvePath(filePaths[i]),
+            output.join("\n") + (keepNewline ? "\n" : "")
+          );
+        } catch (e) {
+          context.writer.writeError(`sed: ${e.message}`);
+          return;
+        }
+      }
+      await fs.persist();
+      return;
+    }
+    const script = parse();
+    if (!script) return;
+    const lines = contents.flatMap((c) => splitLines(c));
+    this.writeLines(context, this.run(script, lines, suppress));
+  }
+  writeLines(context, lines) {
+    for (const line of lines) {
+      context.writer.writeln(line);
+    }
+  }
+  /** Runs the script over the lines and returns the output lines. */
+  run(script, lines, suppress) {
+    const output = [];
     for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
       let line = lines[lineIdx];
       let deleted = false;
-      let printed = false;
-      for (const expr of parsedExpressions) {
-        if (deleted) break;
-        if (!this.addressMatches(
-          expr.address,
-          lineIdx + 1,
-          lines.length,
-          line
-        )) {
+      let quit = false;
+      for (const expr of script) {
+        if (!this.addressMatches(expr, lineIdx + 1, lines.length, line)) {
           continue;
         }
-        switch (expr.command) {
-          case "s": {
-            const pattern = expr.pattern;
-            pattern.lastIndex = 0;
-            const newLine = line.replace(pattern, (...args) => {
-              const match = args[0];
-              return expr.replacement.replace(/&/g, match);
-            });
-            const matched = newLine !== line;
-            line = newLine;
-            if (matched && expr.printFlag) {
-              printed = true;
+        if (expr.command === "s") {
+          let replaced = false;
+          let seen = 0;
+          const pattern = expr.pattern;
+          pattern.lastIndex = 0;
+          line = line.replace(pattern, (...args) => {
+            seen++;
+            const nth = expr.occurrence;
+            if (nth && (expr.globalFlag ? seen < nth : seen !== nth)) {
+              return args[0];
             }
-            break;
-          }
-          case "d":
-            deleted = true;
-            break;
-          case "p":
-            printed = true;
-            break;
+            replaced = true;
+            const groups = args.slice(0, expr.groupCount + 1);
+            return this.expandReplacement(expr.replacement, groups);
+          });
+          if (replaced && expr.printFlag) output.push(line);
+        } else if (expr.command === "p") {
+          output.push(line);
+        } else if (expr.command === "d") {
+          deleted = true;
+          break;
+        } else if (expr.command === "q") {
+          quit = true;
+          break;
         }
       }
-      if (!deleted) {
-        if (suppress) {
-          if (printed) {
-            outputLines.push(line);
-          }
+      if (!deleted && !suppress) output.push(line);
+      if (quit) break;
+    }
+    return output;
+  }
+  /** `&` is the match, `\1`..`\9` the groups, `\n` a newline, `\x` a literal x. */
+  expandReplacement(replacement, groups) {
+    let out = "";
+    for (let i = 0; i < replacement.length; i++) {
+      const ch = replacement[i];
+      if (ch === "\\" && i + 1 < replacement.length) {
+        const next = replacement[++i];
+        if (next >= "0" && next <= "9") {
+          out += groups[Number(next)] ?? "";
+        } else if (next === "n") {
+          out += "\n";
+        } else if (next === "t") {
+          out += "	";
         } else {
-          outputLines.push(line);
+          out += next;
         }
+      } else if (ch === "&") {
+        out += groups[0];
+      } else {
+        out += ch;
       }
     }
-    const result = outputLines.join("\n");
-    if (inPlace && filePath) {
-      const resolved = fs.resolvePath(filePath);
-      fs.writeFile(resolved, result);
-      await fs.persist();
-    } else {
-      const resultLines = result.split("\n");
-      for (const line of resultLines) {
-        context.writer.writeln(line);
-      }
-    }
+    return out;
   }
   parseRawCommand(command) {
     const raw = command.value || "";
     const tokens = this.tokenize(raw);
     const inPlace = !!command.args["in-place"] || !!command.args["i"];
     const suppress = !!command.args["quiet"] || !!command.args["n"];
+    const extended = !!command.args["regexp-extended"] || !!command.args["E"] || !!command.args["r"];
     const expressions = [];
-    let filePath = null;
-    const nonFlagTokens = [];
-    if (command.args["expression"] || command.args["e"]) {
-      const eValue = command.args["expression"] || command.args["e"];
-      if (Array.isArray(eValue)) {
-        for (const v of eValue) {
-          if (v && typeof v === "string") {
-            expressions.push(v);
-          }
-        }
-      } else if (eValue && typeof eValue === "string") {
-        expressions.push(eValue);
+    const eValue = command.args["expression"] ?? command.args["e"];
+    for (const v of Array.isArray(eValue) ? eValue : [eValue]) {
+      if (v != null && v !== true && v !== "") {
+        expressions.push(String(v));
       }
     }
-    for (const t of tokens) {
-      nonFlagTokens.push(t);
-    }
-    if (expressions.length === 0 && nonFlagTokens.length > 0) {
-      expressions.push(nonFlagTokens.shift());
+    if (expressions.length === 0 && tokens.length > 0) {
+      expressions.push(tokens.shift());
     }
-    if (nonFlagTokens.length > 0) {
-      filePath = nonFlagTokens[nonFlagTokens.length - 1];
-    }
-    return { inPlace, suppress, expressions, filePath };
+    return { inPlace, suppress, extended, expressions, filePaths: tokens };
   }
   tokenize(raw) {
     const tokens = [];
@@ -2636,73 +3381,85 @@ var CliSedCommandProcessor = class {
         i++;
         continue;
       }
-      if (raw[i] === "'" || raw[i] === '"') {
-        const quote = raw[i];
-        i++;
-        let token2 = "";
-        while (i < raw.length && raw[i] !== quote) {
-          token2 += raw[i];
-          i++;
-        }
-        if (i < raw.length) i++;
-        tokens.push(token2);
-        continue;
-      }
       let token = "";
       while (i < raw.length && raw[i] !== " " && raw[i] !== "	") {
-        token += raw[i];
-        i++;
+        if (raw[i] === "'" || raw[i] === '"') {
+          const quote = raw[i];
+          i++;
+          while (i < raw.length && raw[i] !== quote) {
+            token += raw[i];
+            i++;
+          }
+          if (i < raw.length) i++;
+        } else {
+          token += raw[i];
+          i++;
+        }
       }
       tokens.push(token);
     }
-    return tokens;
+    return tokens;
+  }
+  /** Commands of a script, separated by `;` or newlines. */
+  parseScript(script, extended) {
+    const result = [];
+    let pos = 0;
+    const skipSeparators = () => {
+      while (pos < script.length && /[\s;]/.test(script[pos])) pos++;
+    };
+    skipSeparators();
+    while (pos < script.length) {
+      const parsed = this.parseCommand(script, pos, extended);
+      result.push(parsed.expression);
+      pos = parsed.pos;
+      while (pos < script.length && /[ \t]/.test(script[pos])) pos++;
+      if (pos < script.length && !/[;\n]/.test(script[pos])) {
+        throw new Error(`extra characters after command: '${script.slice(pos)}'`);
+      }
+      skipSeparators();
+    }
+    if (result.length === 0) {
+      throw new Error(`invalid expression: '${script}'`);
+    }
+    return result;
   }
-  parseExpression(expr) {
-    let pos = 0;
-    let address = null;
-    if (pos < expr.length) {
-      const addrResult = this.parseAddress(expr, pos);
-      if (addrResult) {
-        address = addrResult.address;
-        pos = addrResult.pos;
-        if (pos < expr.length && expr[pos] === ",") {
-          pos++;
-          const endResult = this.parseAddress(expr, pos);
-          if (endResult) {
-            if (endResult.address.type === "last") {
-              address = {
-                type: "range",
-                startLine: address.line,
-                endLine: 0,
-                endIsLast: true
-              };
-            } else {
-              address = {
-                type: "range",
-                startLine: address.line,
-                endLine: endResult.address.line
-              };
-            }
-            pos = endResult.pos;
-          }
+  parseCommand(expr, pos, extended) {
+    let start = null;
+    let end = null;
+    const first = this.parseAddress(expr, pos, extended);
+    if (first) {
+      start = first.address;
+      pos = first.pos;
+      if (expr[pos] === ",") {
+        const second = this.parseAddress(expr, pos + 1, extended);
+        if (!second) {
+          throw new Error(`unexpected ',' in '${expr}'`);
         }
+        end = second.address;
+        pos = second.pos;
       }
     }
+    while (pos < expr.length && /[ \t]/.test(expr[pos])) pos++;
+    let negate = false;
+    if (expr[pos] === "!") {
+      negate = true;
+      pos++;
+      while (pos < expr.length && /[ \t]/.test(expr[pos])) pos++;
+    }
     if (pos >= expr.length) {
       throw new Error(`invalid expression: '${expr}'`);
     }
+    const base = { start, end, negate, active: false };
     const cmd = expr[pos];
     if (cmd === "s") {
-      return this.parseSubstitution(expr, pos, address);
-    } else if (cmd === "d") {
-      return { address, command: "d" };
-    } else if (cmd === "p") {
-      return { address, command: "p" };
-    } else {
-      throw new Error(`unknown command: '${cmd}'`);
+      return this.parseSubstitution(expr, pos, base, extended);
+    }
+    if (cmd === "d" || cmd === "p" || cmd === "q") {
+      return { expression: { ...base, command: cmd }, pos: pos + 1 };
     }
+    throw new Error(`unknown command: '${cmd}'`);
   }
-  parseAddress(expr, pos) {
+  parseAddress(expr, pos, extended) {
     if (pos >= expr.length) return null;
     if (expr[pos] >= "0" && expr[pos] <= "9") {
       let numStr = "";
@@ -2719,51 +3476,73 @@ var CliSedCommandProcessor = class {
       return { address: { type: "last" }, pos: pos + 1 };
     }
     if (expr[pos] === "/") {
-      pos++;
-      let pattern = "";
-      while (pos < expr.length && expr[pos] !== "/") {
-        if (expr[pos] === "\\" && pos + 1 < expr.length) {
-          pattern += expr[pos + 1];
-          pos += 2;
-        } else {
-          pattern += expr[pos];
-          pos++;
-        }
-      }
-      if (pos < expr.length) pos++;
+      const parsed = this.readDelimited(expr, pos + 1, "/");
       try {
         return {
-          address: { type: "regex", regex: new RegExp(pattern) },
-          pos
+          address: {
+            type: "regex",
+            regex: new RegExp(this.toJsRegex(parsed.text, extended))
+          },
+          pos: parsed.pos
         };
       } catch {
-        throw new Error(`invalid regex in address: '${pattern}'`);
+        throw new Error(`invalid regex in address: '${parsed.text}'`);
       }
     }
     return null;
   }
-  parseSubstitution(expr, pos, address) {
-    pos++;
-    if (pos >= expr.length) {
-      throw new Error(`invalid substitution expression: '${expr}'`);
-    }
-    const delimiter = expr[pos];
-    pos++;
-    let pattern = "";
+  /**
+   * Text up to the next unescaped delimiter, escapes kept (an escaped
+   * delimiter becomes the plain character when it has no regex meaning).
+   */
+  readDelimited(expr, pos, delimiter) {
+    let text = "";
     while (pos < expr.length && expr[pos] !== delimiter) {
       if (expr[pos] === "\\" && pos + 1 < expr.length) {
-        pattern += "\\" + expr[pos + 1];
+        const next = expr[pos + 1];
+        text += next === delimiter && /\w|\//.test(next) ? next : "\\" + next;
         pos += 2;
       } else {
-        pattern += expr[pos];
+        text += expr[pos];
         pos++;
       }
     }
     if (pos < expr.length) pos++;
+    return { text, pos };
+  }
+  /**
+   * Basic regular expressions use \( \) \{ \} \+ \? \| for groups and
+   * operators. When a pattern uses them (or never in -E mode), they are
+   * turned into the JavaScript form and the bare characters made literal.
+   */
+  toJsRegex(pattern, extended) {
+    if (extended || !/\\[(){}+?|]/.test(pattern)) return pattern;
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+      const ch = pattern[i];
+      if (ch === "\\" && i + 1 < pattern.length) {
+        const next = pattern[++i];
+        out += "(){}+?|".includes(next) ? next : "\\" + next;
+      } else if ("(){}+?|".includes(ch)) {
+        out += "\\" + ch;
+      } else {
+        out += ch;
+      }
+    }
+    return out;
+  }
+  parseSubstitution(expr, pos, base, extended) {
+    pos++;
+    if (pos >= expr.length) {
+      throw new Error(`invalid substitution expression: '${expr}'`);
+    }
+    const delimiter = expr[pos];
+    const pattern = this.readDelimited(expr, pos + 1, delimiter);
+    pos = pattern.pos;
     let replacement = "";
     while (pos < expr.length && expr[pos] !== delimiter) {
       if (expr[pos] === "\\" && pos + 1 < expr.length) {
-        replacement += expr[pos + 1];
+        replacement += expr[pos + 1] === delimiter ? delimiter : "\\" + expr[pos + 1];
         pos += 2;
       } else {
         replacement += expr[pos];
@@ -2774,47 +3553,75 @@ var CliSedCommandProcessor = class {
     let globalFlag = false;
     let caseInsensitive = false;
     let printFlag = false;
-    while (pos < expr.length) {
+    let occurrence = "";
+    while (pos < expr.length && !/[;\n\s}]/.test(expr[pos])) {
       const f = expr[pos];
       if (f === "g") globalFlag = true;
-      else if (f === "i") caseInsensitive = true;
+      else if (f === "i" || f === "I") caseInsensitive = true;
       else if (f === "p") printFlag = true;
+      else if (f >= "0" && f <= "9") occurrence += f;
+      else throw new Error(`unknown option to 's': '${f}'`);
       pos++;
     }
+    const nth = occurrence ? parseInt(occurrence, 10) : void 0;
+    if (nth === 0) {
+      throw new Error("number option to 's' command may not be zero");
+    }
     let regexFlags = "";
     if (caseInsensitive) regexFlags += "i";
-    if (globalFlag) regexFlags += "g";
+    if (globalFlag || nth) regexFlags += "g";
     let regex;
+    let groupCount;
     try {
-      regex = new RegExp(pattern, regexFlags);
+      const source = this.toJsRegex(pattern.text, extended);
+      regex = new RegExp(source, regexFlags);
+      groupCount = (new RegExp(`${source}|`).exec("")?.length ?? 1) - 1;
     } catch {
-      throw new Error(`invalid regex: '${pattern}'`);
+      throw new Error(`invalid regex: '${pattern.text}'`);
     }
     return {
-      address,
-      command: "s",
-      pattern: regex,
-      replacement,
-      globalFlag,
-      printFlag
+      expression: {
+        ...base,
+        command: "s",
+        pattern: regex,
+        replacement,
+        groupCount,
+        printFlag,
+        occurrence: nth,
+        globalFlag
+      },
+      pos
     };
   }
-  addressMatches(address, lineNum, totalLines, lineText) {
-    if (!address) return true;
+  addressMatches(expr, lineNum, totalLines, lineText) {
+    let matches;
+    if (!expr.start) {
+      matches = true;
+    } else if (!expr.end) {
+      matches = this.singleMatches(expr.start, lineNum, totalLines, lineText);
+    } else if (!expr.active) {
+      matches = this.singleMatches(expr.start, lineNum, totalLines, lineText);
+      if (matches) {
+        const end = expr.end;
+        const endsHere = end.type === "line" && end.line <= lineNum || end.type === "last" && lineNum === totalLines;
+        expr.active = !endsHere;
+      }
+    } else {
+      matches = true;
+      const end = expr.end;
+      const endsHere = end.type === "line" ? lineNum >= end.line : this.singleMatches(end, lineNum, totalLines, lineText);
+      if (endsHere) expr.active = false;
+    }
+    return expr.negate ? !matches : matches;
+  }
+  singleMatches(address, lineNum, totalLines, lineText) {
     switch (address.type) {
       case "line":
         return lineNum === address.line;
       case "last":
         return lineNum === totalLines;
-      case "range": {
-        const start = address.startLine;
-        const end = address.endIsLast ? totalLines : address.endLine;
-        return lineNum >= start && lineNum <= end;
-      }
       case "regex":
         return address.regex.test(lineText);
-      default:
-        return true;
     }
   }
 };
@@ -2836,11 +3643,34 @@ var CliAwkCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.awk.help.process_text_records_fields", "Process text as records and fields: each line is split into fields $1, $2, ... ($0 is the whole line), and each rule runs its { action } on matching lines. Supports BEGIN and END blocks, /regex/ and field comparison patterns, print, variables, NR and NF. Quote the program; a simple one also works unquoted (awk {print $1} file).")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["awk '<program>' <file>", t.t("cli.awk.help.run_program_over_file", "Run a program over a file")],
+      [
+        "awk -F <sep> '<program>' <file>",
+        t.t("cli.awk.help.split_fields_instead_spaces", "Split fields on <sep> instead of spaces")
+      ],
+      ["<command> | awk '<program>'", t.t("cli.awk.help.run_program_over_piped", "Run a program over piped input")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["awk '{print $1}' data.txt", t.t("cli.awk.help.print_first_column", "Print the first column")],
+      ["awk -F , '{print $2}' data.csv", t.t("cli.awk.help.second_column_csv", "Second column of a CSV")],
+      ["awk '$3 > 100 {print $1}' sales.txt", t.t("cli.awk.help.filter_rows_field", "Filter rows by a field")],
+      ["awk '{s += $2} END {print s}' data.txt", t.t("cli.awk.help.sum_second_column", "Sum the second column")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const { program, filePath, fieldSep } = this.parseArgs(command);
+    const { program, filePaths, fieldSep } = this.parseArgs(command, fs);
     if (!program) {
       context.writer.writeError(
         "awk: missing program. Usage: awk [-F sep] 'program' file"
@@ -2848,18 +3678,21 @@ var CliAwkCommandProcessor = class {
       return;
     }
     let content = "";
-    if (filePath) {
-      try {
-        if (!fs.exists(filePath)) {
-          context.writer.writeError(
-            `awk: ${filePath}: No such file or directory`
-          );
+    if (filePaths.length > 0) {
+      for (const filePath of filePaths) {
+        try {
+          if (!fs.exists(filePath)) {
+            context.writer.writeError(
+              `awk: ${filePath}: No such file or directory`
+            );
+            return;
+          }
+          const text = fs.readFile(filePath) ?? "";
+          content += text === "" || text.endsWith("\n") ? text : text + "\n";
+        } catch (e) {
+          context.writer.writeError(`awk: ${e.message}`);
           return;
         }
-        content = fs.readFile(filePath) ?? "";
-      } catch (e) {
-        context.writer.writeError(`awk: ${e.message}`);
-        return;
       }
     } else if (command.data != null) {
       content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
@@ -2921,24 +3754,58 @@ var CliAwkCommandProcessor = class {
       context.writer.writeln(line);
     }
   }
-  parseArgs(command) {
-    const raw = command.value || "";
-    const fieldSep = command.args["F"] || null;
-    let rest = raw;
-    let program = null;
-    const sqMatch = rest.match(/^'((?:[^'\\]|\\.)*)'\s*/);
-    if (sqMatch) {
-      program = sqMatch[1];
-      rest = rest.slice(sqMatch[0].length);
-    } else {
-      const dqMatch = rest.match(/^"((?:[^"\\]|\\.)*)"\s*/);
-      if (dqMatch) {
-        program = dqMatch[1];
-        rest = rest.slice(dqMatch[0].length);
+  /**
+   * The program is the first operand, usually quoted. Unquoted, it may span
+   * several words (`awk {print $1} file`): it is then everything before the
+   * trailing operands that are existing files, or the whole value with
+   * piped input.
+   */
+  parseArgs(command, fs) {
+    const raw = (command.value || "").trim();
+    const fieldArg = command.args["F"];
+    const fieldSep = fieldArg != null && fieldArg !== true ? String(fieldArg) : null;
+    const quoted = raw.match(/^'((?:[^'\\]|\\.)*)'(?:\s+|$)/) ?? raw.match(/^"((?:[^"\\]|\\.)*)"(?:\s+|$)/);
+    if (quoted) {
+      return {
+        program: quoted[1],
+        filePaths: splitArgs(raw.slice(quoted[0].length)),
+        fieldSep
+      };
+    }
+    const words = raw.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+      return { program: null, filePaths: [], fieldSep };
+    }
+    const isFile = (word) => {
+      try {
+        const path = splitArgs(word).join(" ");
+        return fs.exists(path) && !fs.isDirectory(path);
+      } catch {
+        return false;
       }
+    };
+    let split = words.length;
+    while (split > 1 && isFile(words[split - 1])) split--;
+    if (split === words.length && command.data == null && words.length > 1) {
+      const program = words.slice(0, -1).join(" ");
+      const last = words[words.length - 1];
+      if (this.bracesBalanced(program) && !/[{}]/.test(last)) {
+        split = words.length - 1;
+      }
+    }
+    return {
+      program: words.slice(0, split).join(" "),
+      filePaths: words.slice(split).map((w) => splitArgs(w).join(" ")),
+      fieldSep
+    };
+  }
+  bracesBalanced(text) {
+    let depth = 0;
+    for (const ch of text) {
+      if (ch === "{") depth++;
+      else if (ch === "}" && --depth < 0) return false;
     }
-    const filePath = rest.trim() || null;
-    return { program, filePath, fieldSep };
+    return depth === 0;
   }
   parseProgram(program) {
     const rules = [];
@@ -3312,8 +4179,26 @@ var CliDiffCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.diff.help.compare_two_files_line", "Compare two files line by line and show what changed: lines starting with < (or -) are only in the first file, lines starting with > (or +) only in the second.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["diff <file1> <file2>", t.t("cli.diff.help.show_differences", "Show the differences")],
+      ["diff -u <file1> <file2>", t.t("cli.diff.help.unified_format_context", "Unified format with context")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["diff old.txt new.txt", t.t("cli.diff.help.what_changed_between_versions", "What changed between versions")],
+      ["diff -u config.bak config.txt", t.t("cli.diff.help.review_edits_git_style", "Review edits, git style")],
+      ["diff -i a.txt b.txt", t.t("cli.diff.help.ignore_upper_lower_case", "Ignore upper/lower case")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const unified = command.args["unified"] || command.args["u"] || false;
@@ -3476,13 +4361,13 @@ var CliDiffCommandProcessor = class {
   }
   parsePaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliTeeCommandProcessor = class {
   constructor() {
     this.command = "tee";
-    this.description = "Read from a file and write to output files and stdout";
+    this.description = "Copy piped input to files and to the output";
     this.author = cliCore.DefaultLibraryAuthor;
     this.version = LIBRARY_VERSION;
     this.acceptsRawInput = true;
@@ -3498,72 +4383,56 @@ var CliTeeCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.tee.help.pass_piped_input_through", "Pass piped input through unchanged and save a copy of it to every file named, overwriting them or appending with -a. Like Unix tee, it reads only piped input: to copy a file, pipe it in with cat.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["<command> | tee <file...>", t.t("cli.tee.help.show_piped_output_save", "Show piped output and save it")],
+      ["<command> | tee -a <file>", t.t("cli.tee.help.append_instead_overwriting", "Append instead of overwriting")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ["cat notes.txt | tee copy.txt", t.t("cli.tee.help.show_save_copy", "Show and save a copy")],
+      ["echo done | tee -a log.txt", t.t("cli.tee.help.add_line_log", "Add a line to a log")],
+      [
+        "cat source.txt | tee a.txt b.txt",
+        t.t("cli.tee.help.copy_source_txt_txt", "Copy source.txt into a.txt and b.txt")
+      ]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     const append = command.args["append"] || command.args["a"] || false;
-    const parsed = this.parseArgs(command);
-    let content;
-    if (command.data != null) {
-      content = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
-      const outputFiles = this.getAllPaths(command);
-      context.writer.writeln(content);
-      for (const outFile of outputFiles) {
-        if (append && fs.exists(outFile)) {
-          fs.writeFile(outFile, content, true);
-        } else {
-          fs.writeFile(outFile, content);
-        }
-      }
-      await fs.persist();
-    } else {
-      if (parsed.outputFiles.length === 0 && !parsed.inputFile) {
-        context.writer.writeError("tee: missing operand");
-        return;
-      }
-      if (!parsed.inputFile) {
-        context.writer.writeError("tee: missing input file");
-        return;
-      }
-      if (parsed.outputFiles.length === 0) {
-        context.writer.writeError("tee: missing output file");
-        return;
-      }
-      if (!fs.exists(parsed.inputFile)) {
-        context.writer.writeError(
-          `tee: ${parsed.inputFile}: No such file or directory`
-        );
-        return;
-      }
-      content = fs.readFile(parsed.inputFile) || "";
-      context.writer.writeln(content);
-      for (const outFile of parsed.outputFiles) {
-        if (append && fs.exists(outFile)) {
-          fs.writeFile(outFile, content, true);
-        } else {
-          fs.writeFile(outFile, content);
-        }
+    if (command.data == null) {
+      context.writer.writeError(
+        "tee: no input: tee copies piped input to files and the output; use 'cat file | tee out.txt'"
+      );
+      context.process.exit(1, { silent: true });
+      return;
+    }
+    const content = pipedText(command.data);
+    context.writer.writeln(content);
+    const fileText = content === "" || content.endsWith("\n") ? content : content + "\n";
+    let changed = false;
+    for (const outFile of this.getAllPaths(command)) {
+      try {
+        fs.writeFile(outFile, fileText, append);
+        changed = true;
+      } catch (e) {
+        context.writer.writeError(`tee: ${e.message}`);
       }
-      await fs.persist();
     }
+    if (changed) await fs.persist();
   }
   getAllPaths(command) {
     const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
-  }
-  parseArgs(command) {
-    const raw = command.value || "";
-    const paths = raw.split(/\s+/).filter(Boolean);
-    if (paths.length < 2) {
-      return {
-        outputFiles: [],
-        inputFile: paths[0] || null
-      };
-    }
-    const inputFile = paths[paths.length - 1];
-    const outputFiles = paths.slice(0, paths.length - 1);
-    return { outputFiles, inputFile };
+    return splitArgs(raw).filter(Boolean);
   }
 };
 var CliXargsCommandProcessor = class {
@@ -3592,65 +4461,91 @@ var CliXargsCommandProcessor = class {
       }
     ];
   }
+  writeDescription(context) {
+    const t = context.translator;
+    cliCore.writeWrapped(
+      context,
+      t.t("cli.xargs.help.run_command_arguments_taken", "Run a command with arguments taken from input, separated by blanks or newlines. By default all of them are appended to one command; -n runs it in batches and -I runs it once per line, replacing a placeholder. xargs options go before the command; everything after it, flags included, belongs to the command. Input is piped text or, without a pipe, the last file named.")
+    );
+    context.writer.writeln();
+    cliCore.writeUsage(context, [
+      ["<command> | xargs <cmd>", t.t("cli.xargs.help.append_input_lines", "Append input lines to <cmd>")],
+      ["<command> | xargs -I {} <cmd {}>", t.t("cli.xargs.help.run_once_per_line", "Run <cmd> once per line")],
+      ["xargs <cmd> <file>", t.t("cli.xargs.help.read_arguments_file", "Read the arguments from a file")]
+    ]);
+    context.writer.writeln();
+    cliCore.writeExamples(context, [
+      ['find . --name "*.tmp" | xargs rm', t.t("cli.xargs.help.delete_every_tmp_file", "Delete every .tmp file")],
+      [
+        "cat files.txt | xargs -I {} cp {} backup",
+        t.t("cli.xargs.help.copy_each_listed_file", "Copy each listed file")
+      ],
+      ["cat dirs.txt | xargs -n 1 mkdir", t.t("cli.xargs.help.one_mkdir_per_line", "One mkdir per line")],
+      ['find . --name "*.bak" | xargs rm -r', t.t("cli.xargs.help.inner_command_keeps_flags", "The inner command keeps its flags")]
+    ]);
+  }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const replaceStr = command.args["replace"] || command.args["I"] || null;
-    const maxArgs = parseInt(
-      command.args["max-args"] || command.args["n"] || "0",
-      10
-    );
-    const parsed = this.parseArgs(command);
+    let parsed;
+    try {
+      parsed = command.rawCommand ? parseXargsLine(command.rawCommand) : {
+        replace: stringArg(command.args["replace"] ?? command.args["I"]),
+        maxArgs: parseInt(
+          String(command.args["max-args"] ?? command.args["n"] ?? ""),
+          10
+        ) || void 0,
+        words: splitWords(command.value ?? "")
+      };
+    } catch (e) {
+      context.writer.writeError(`xargs: ${e.message}`);
+      return;
+    }
+    const replaceStr = parsed.replace;
+    const maxArgs = parsed.maxArgs ?? 0;
     let commandTemplate;
     let argContent;
     if (command.data != null) {
-      commandTemplate = this.getAllNonFlagTokens(command).join(" ");
-      if (!commandTemplate) {
-        context.writer.writeError("xargs: missing command");
-        return;
-      }
-      argContent = typeof command.data === "string" ? command.data : JSON.stringify(command.data);
+      commandTemplate = parsed.words.map((w) => w.raw).join(" ") || "echo";
+      argContent = pipedText(command.data);
     } else {
-      if (!parsed.commandTemplate) {
+      if (parsed.words.length === 0) {
         context.writer.writeError("xargs: missing command");
         return;
       }
-      commandTemplate = parsed.commandTemplate;
-      if (!parsed.inputFile) {
+      if (parsed.words.length < 2) {
         context.writer.writeError("xargs: missing input file");
         return;
       }
-      if (!fs.exists(parsed.inputFile)) {
+      const inputFile = parsed.words[parsed.words.length - 1].value;
+      commandTemplate = parsed.words.slice(0, -1).map((w) => w.raw).join(" ");
+      if (!fs.exists(inputFile)) {
         context.writer.writeError(
-          `xargs: ${parsed.inputFile}: No such file or directory`
+          `xargs: ${inputFile}: No such file or directory`
         );
         return;
       }
-      argContent = fs.readFile(parsed.inputFile) || "";
+      argContent = fs.readFile(inputFile) || "";
     }
-    const args = argContent.split("\n").map((l) => l.trim()).filter(Boolean);
-    if (args.length === 0) return;
     const commands = [];
     if (replaceStr) {
-      for (const arg of args) {
-        const cmd = commandTemplate.replace(
-          new RegExp(this.escapeRegex(replaceStr), "g"),
-          arg
+      const lines = argContent.split("\n").map((l) => l.trim()).filter(Boolean);
+      const placeholder = new RegExp(this.escapeRegex(replaceStr), "g");
+      for (const line of lines) {
+        commands.push(
+          commandTemplate.replace(placeholder, () => quoteArg(line))
         );
-        commands.push(cmd);
       }
-    } else if (maxArgs > 0) {
-      for (let i = 0; i < args.length; i += maxArgs) {
-        const group = args.slice(i, i + maxArgs);
+    } else {
+      const args = splitArgs(argContent).map(quoteArg);
+      if (args.length === 0) return;
+      const size = maxArgs > 0 ? maxArgs : args.length;
+      for (let i = 0; i < args.length; i += size) {
         commands.push(
-          `${commandTemplate} ${group.join(" ")}`
+          `${commandTemplate} ${args.slice(i, i + size).join(" ")}`
         );
       }
-    } else {
-      commands.push(
-        `${commandTemplate} ${args.join(" ")}`
-      );
     }
     const executor = context.executor;
     for (const cmd of commands) {
@@ -3665,27 +4560,64 @@ var CliXargsCommandProcessor = class {
       }
     }
   }
-  getAllNonFlagTokens(command) {
-    const raw = command.value || "";
-    return raw.split(/\s+/).filter(Boolean);
-  }
   escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   }
-  parseArgs(command) {
-    const raw = command.value || "";
-    const nonFlagTokens = raw.split(/\s+/).filter(Boolean);
-    if (nonFlagTokens.length < 2) {
-      return {
-        commandTemplate: nonFlagTokens[0] || null,
-        inputFile: null
-      };
+};
+function parseXargsLine(raw) {
+  const words = splitWords(raw).slice(1);
+  const result = { words: [] };
+  let i = 0;
+  const valueOf = (option, inline) => {
+    if (inline !== "") return inline;
+    if (i + 1 >= words.length) {
+      throw new Error(`option requires an argument -- '${option}'`);
+    }
+    return words[++i].value;
+  };
+  for (; i < words.length; i++) {
+    const word = words[i].raw;
+    if (word === "--") {
+      i++;
+      break;
+    }
+    if (!word.startsWith("-") || word === "-") break;
+    let match;
+    if (match = word.match(/^(?:-I|--replace(?:=|$))(.*)$/)) {
+      result.replace = valueOf("I", unquote(match[1]));
+    } else if (word === "-i") {
+      result.replace = "{}";
+    } else if (match = word.match(/^(?:-n|--max-args(?:=|$))(.*)$/)) {
+      const value = valueOf("n", unquote(match[1]));
+      const count = parseInt(value, 10);
+      if (isNaN(count) || count < 1) {
+        throw new Error(`invalid number of arguments: '${value}'`);
+      }
+      result.maxArgs = count;
+    } else {
+      throw new Error(`invalid option -- '${word.replace(/^-+/, "")}'`);
     }
-    const inputFile = nonFlagTokens[nonFlagTokens.length - 1];
-    const commandTemplate = nonFlagTokens.slice(0, nonFlagTokens.length - 1).join(" ");
-    return { commandTemplate, inputFile };
   }
-};
+  result.words = words.slice(i);
+  return result;
+}
+function splitWords(raw) {
+  const words = [];
+  const regex = /(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']|["'])+/g;
+  for (const match of raw.matchAll(regex)) {
+    words.push({ raw: match[0], value: splitArgs(match[0]).join(" ") });
+  }
+  return words;
+}
+function unquote(value) {
+  return splitArgs(value).join(" ");
+}
+function stringArg(value) {
+  return value == null || value === true || value === "" ? void 0 : String(value);
+}
+function quoteArg(arg) {
+  return cliCore.quoteShellWord(arg);
+}
 var CliShCommandProcessor = class {
   constructor() {
     this.command = "sh";
@@ -3706,17 +4638,14 @@ var CliShCommandProcessor = class {
     ];
   }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    let filePath = (command.value || "").trim();
-    if (!filePath && command.rawCommand) {
-      const raw = command.rawCommand.trim();
-      const firstSpace = raw.indexOf(" ");
-      if (firstSpace > -1) {
-        filePath = raw.slice(firstSpace + 1).trim();
-      }
+    let words = splitArgs(command.value || "");
+    if (words.length === 0 && command.rawCommand) {
+      words = splitArgs(command.rawCommand).slice(1).filter((w) => !w.startsWith("-"));
     }
+    const filePath = words[0] ?? "";
     if (!filePath) {
       context.writer.writeError("sh: missing file operand");
       context.process.exit(1, { silent: true });
@@ -3749,10 +4678,10 @@ var CliShCommandProcessor = class {
     await executeScript(content, context);
   }
   writeDescription(context) {
-    const { writer } = context;
-    writer.writeln(this.description);
+    const { writer, translator: t } = context;
+    writer.writeln(t.t("cli.sh.description", this.description));
     writer.writeln();
-    writer.writeln("Usage:");
+    writer.writeln(t.t("cli.common.usage", "Usage:"));
     writer.writeln(
       `  ${writer.wrapInColor("sh <script.sh>", cliCore.CliForegroundColor.Cyan)}`
     );
@@ -3763,83 +4692,57 @@ var CliShCommandProcessor = class {
       `  ${writer.wrapInColor(". <script.sh>", cliCore.CliForegroundColor.Cyan)}`
     );
     writer.writeln(
-      `  ${writer.wrapInColor("./script.sh", cliCore.CliForegroundColor.Cyan)}     (requires execute permission)`
+      `  ${writer.wrapInColor("./script.sh", cliCore.CliForegroundColor.Cyan)}     ${t.t("cli.sh.help.requires_execute", "(requires execute permission)")}`
     );
     writer.writeln();
-    writer.writeln("Script syntax:");
-    writer.writeln("  # Lines starting with # are comments");
-    writer.writeln("  VAR=value          # Variable assignment");
-    writer.writeln("  echo $VAR          # Variable substitution");
-    writer.writeln("  set -e             # Stop on error (default)");
-    writer.writeln("  set +e             # Continue on errors");
+    writer.writeln(t.t("cli.sh.help.script_syntax", "Script syntax:"));
+    writer.writeln(`  # ${t.t("cli.sh.help.comments", "Lines starting with # are comments")}`);
+    writer.writeln(`  cmd1; cmd2         # ${t.t("cli.sh.help.several_commands", "Several commands on one line")}`);
+    writer.writeln(`  VAR=value          # ${t.t("cli.sh.help.assignment", "Variable assignment")}`);
+    writer.writeln(`  echo $VAR          # ${t.t("cli.sh.help.substitution", "Variable substitution")}`);
+    writer.writeln(`  set -e             # ${t.t("cli.sh.help.stop_on_error", "Stop on error (default)")}`);
+    writer.writeln(`  set +e             # ${t.t("cli.sh.help.continue_on_errors", "Continue on errors")}`);
+    writer.writeln(`  exit [n]           # ${t.t("cli.sh.help.exit", "Stop the script with status n")}`);
+    writer.writeln();
+    writer.writeln(t.t("cli.sh.help.control_flow", "Control flow:"));
+    writer.writeln("  if cmd; then ...; elif cmd; then ...; else ...; fi");
+    writer.writeln("  for NAME in a b *.txt; do ...; done");
+    writer.writeln(`  while cmd; do ...; done      ${t.t("cli.sh.help.until", "(until cmd: the opposite)")}`);
+    writer.writeln(`  break / continue [n]         # ${t.t("cli.sh.help.break_continue", "Leave / skip in a loop")}`);
+    writer.writeln(`  ! cmd                        # ${t.t("cli.sh.help.negate", "Negate the exit status")}`);
+    writer.writeln(
+      `  ${t.t("cli.sh.help.conditions", "Conditions are commands:")} ${writer.wrapInColor("[ -f file ]", cliCore.CliForegroundColor.Cyan)}, ${writer.wrapInColor('test "$A" = b', cliCore.CliForegroundColor.Cyan)}, ${writer.wrapInColor("true", cliCore.CliForegroundColor.Cyan)}, ${writer.wrapInColor("grep x file", cliCore.CliForegroundColor.Cyan)}`
+    );
+    writer.writeln(`  ${t.t("cli.sh.help.conditions_status", "(status 0 = true; see help test). Loops stop after 10000 iterations")}`);
+    writer.writeln(`  ${t.t("cli.sh.help.conditions_loops", "of while/until; Ctrl+C stops the script.")}`);
     writer.writeln();
-    writer.writeln("Example script:");
+    writer.writeln(t.t("cli.sh.help.example_script", "Example script:"));
     writer.writeln(
       writer.wrapInColor(
-        "  #!/bin/sh\n  # Setup script\n  NAME=world\n  echo Hello $NAME\n  mkdir -p /tmp/test\n  echo done > /tmp/test/status.txt",
+        "  #!/bin/sh\n  # Setup script\n  NAME=world\n  echo Hello $NAME\n  mkdir -p /tmp/test\n  for f in a b c; do\n      echo $f > /tmp/test/$f.txt\n  done\n  if [ -f /tmp/test/a.txt ]; then\n      echo done > /tmp/test/status.txt\n  fi",
         cliCore.CliForegroundColor.Green
       )
     );
   }
 };
+var SCRIPT_RUNNER_TOKEN = "cli-script-runner";
 async function executeScript(content, context) {
-  const lines = content.split("\n");
-  const variables = {};
-  let stopOnError = true;
-  for (const rawLine of lines) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) {
-      continue;
-    }
-    if (line === "set -e") {
-      stopOnError = true;
-      continue;
-    }
-    if (line === "set +e") {
-      stopOnError = false;
-      continue;
-    }
-    const assignMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-    if (assignMatch) {
-      const varName = assignMatch[1];
-      let varValue = assignMatch[2];
-      if (varValue.startsWith('"') && varValue.endsWith('"') || varValue.startsWith("'") && varValue.endsWith("'")) {
-        varValue = varValue.slice(1, -1);
-      }
-      varValue = substituteVariables(varValue, variables);
-      variables[varName] = varValue;
-      continue;
-    }
-    const expanded = substituteVariables(line, variables);
-    await context.executor.executeCommand(expanded, context);
-    const exitCode = context.process.exitCode;
-    if (stopOnError && exitCode !== void 0 && exitCode !== 0) {
-      context.writer.writeError(
-        `sh: script aborted at line: ${line}`
-      );
-      return;
-    }
+  const runner = context.services.get(SCRIPT_RUNNER_TOKEN);
+  if (!runner) {
+    context.writer.writeError("sh: script runner not available (update @qodalis/cli)");
+    context.process.exit(1, { silent: true });
+    return;
   }
+  await runner.run(content, context, { name: "sh" });
 }
-function substituteVariables(input, variables) {
-  let result = input.replace(
-    /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
-    (_, name) => variables[name] ?? ""
-  );
-  result = result.replace(
-    /\$([A-Za-z_][A-Za-z0-9_]*)/g,
-    (_, name) => variables[name] ?? ""
-  );
-  return result;
-}
-
-// src/lib/services/indexed-db-file-system.service.ts
 var DB_NAME = "qodalis-cli-filesystem";
 var STORE_NAME = "filesystem";
 var ROOT_KEY = "root";
 var CWD_KEY = "cwd";
 var HOME_KEY = "home";
 var DEFAULT_HOME = "/";
+var SYSTEM_OWNERSHIP = { uid: "root", gid: "admin" };
+var ANONYMOUS_OWNERSHIP = { uid: "nobody", gid: "nogroup" };
 function createSeedFileSystem() {
   const now = Date.now();
   return {
@@ -3887,6 +4790,88 @@ var IndexedDbFileSystemService = class {
     this.homePath = DEFAULT_HOME;
     this.currentUid = null;
     this.currentGroups = [];
+    this.systemDepth = 0;
+  }
+  // --- Access control ---
+  setAccessPolicy(policy) {
+    this.accessPolicy = policy;
+  }
+  runAsSystem(fn) {
+    this.systemDepth++;
+    try {
+      return fn();
+    } finally {
+      this.systemDepth--;
+    }
+  }
+  reassignOwner(fromUid, toUid) {
+    const from = fromUid.toLowerCase();
+    if (!from || !toUid) return 0;
+    let changed = 0;
+    const visit = (node) => {
+      if (node.ownership && node.ownership.uid.toLowerCase() === from) {
+        node.ownership = { ...node.ownership, uid: toUid };
+        changed++;
+      }
+      node.children?.forEach(visit);
+    };
+    visit(this.root);
+    return changed;
+  }
+  canTraverse(path) {
+    try {
+      this.assertTraverse(this.resolvePath(path), "stat", path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  get enforcing() {
+    return !!this.accessPolicy && this.systemDepth === 0;
+  }
+  deny(op, path, reason = "Permission denied") {
+    throw new cliCore.CliAccessDeniedError(`${op}: ${path}: ${reason}`);
+  }
+  /** `x` on every existing directory on the way to `resolved` (excluding the target). */
+  assertTraverse(resolved, op, display) {
+    if (!this.enforcing) return;
+    const parts = resolved.split("/").filter(Boolean);
+    let current = this.root;
+    for (let i = 0; i < parts.length; i++) {
+      if (!current || current.type !== "directory") return;
+      if (!this.accessPolicy.canAccess(current, "execute")) this.deny(op, display);
+      current = current.children?.find((c) => c.name === parts[i]);
+    }
+  }
+  assertAccess(node, action, op, display) {
+    if (this.enforcing && !this.accessPolicy.canAccess(node, action)) this.deny(op, display);
+  }
+  /** Recursive delete: every directory inside must allow removing its entries (`w` + `x`, readable). */
+  assertRemovableTree(dir, dirPath, display) {
+    if (!this.enforcing) return;
+    this.assertAccess(dir, "read", "rm", display);
+    this.assertAccess(dir, "execute", "rm", display);
+    if ((dir.children?.length ?? 0) > 0) this.assertAccess(dir, "write", "rm", display);
+    for (const child of dir.children ?? []) {
+      if (child.type === "directory") this.assertRemovableTree(child, `${dirPath}/${child.name}`, display);
+    }
+  }
+  /** Copying reads everything it copies: `r` on every file, `r` + `x` on every directory. */
+  assertReadableTree(node, display) {
+    if (!this.enforcing) return;
+    this.assertAccess(node, "read", "cp", display);
+    if (node.type !== "directory") return;
+    this.assertAccess(node, "execute", "cp", display);
+    for (const child of node.children ?? []) {
+      this.assertReadableTree(child, `${display.replace(/\/+$/, "")}/${child.name}`);
+    }
+  }
+  /** Creating/removing entries needs `w` and `x` on the containing directory. */
+  assertModifyDir(dir, dirPath, op, display) {
+    if (!this.enforcing) return;
+    this.assertTraverse(dirPath, op, display);
+    this.assertAccess(dir, "execute", op, display);
+    this.assertAccess(dir, "write", op, display);
   }
   // --- User context ---
   setCurrentUser(uid, groups) {
@@ -3894,7 +4879,9 @@ var IndexedDbFileSystemService = class {
     this.currentGroups = groups;
   }
   getDefaultOwnership() {
-    if (!this.currentUid) return void 0;
+    if (!this.currentUid) {
+      return this.accessPolicy ? { ...ANONYMOUS_OWNERSHIP } : void 0;
+    }
     return {
       uid: this.currentUid,
       gid: this.currentGroups[0] || "users"
@@ -3913,6 +4900,8 @@ var IndexedDbFileSystemService = class {
     if (node.type !== "directory") {
       throw new Error(`cd: ${path}: Not a directory`);
     }
+    this.assertTraverse(resolved, "cd", path);
+    this.assertAccess(node, "execute", "cd", path);
     this.cwd = resolved;
   }
   getHomePath() {
@@ -3969,6 +4958,8 @@ var IndexedDbFileSystemService = class {
     if (node.type !== "directory") {
       throw new Error(`ls: ${path}: Not a directory`);
     }
+    this.assertTraverse(this.resolvePath(path), "ls", path);
+    this.assertAccess(node, "read", "ls", path);
     return node.children || [];
   }
   readFile(path) {
@@ -3979,6 +4970,8 @@ var IndexedDbFileSystemService = class {
     if (node.type === "directory") {
       throw new Error(`cat: ${path}: Is a directory`);
     }
+    this.assertTraverse(this.resolvePath(path), "cat", path);
+    this.assertAccess(node, "read", "cat", path);
     return node.content ?? "";
   }
   exists(path) {
@@ -4003,6 +4996,10 @@ var IndexedDbFileSystemService = class {
         }
         let child = current.children.find((c) => c.name === part);
         if (!child) {
+          if (this.enforcing) {
+            this.assertAccess(current, "execute", "mkdir", path);
+            this.assertAccess(current, "write", "mkdir", path);
+          }
           const now = Date.now();
           child = {
             name: part,
@@ -4018,6 +5015,8 @@ var IndexedDbFileSystemService = class {
           current.modifiedAt = now;
         } else if (child.type !== "directory") {
           throw new Error(`mkdir: ${part}: Not a directory`);
+        } else {
+          this.assertAccess(child, "execute", "mkdir", path);
         }
         current = child;
       }
@@ -4036,6 +5035,7 @@ var IndexedDbFileSystemService = class {
       if (parent.children?.find((c) => c.name === dirName)) {
         throw new Error(`mkdir: ${path}: File exists`);
       }
+      this.assertModifyDir(parent, parentPath, "mkdir", path);
       const now = Date.now();
       if (!parent.children) {
         parent.children = [];
@@ -4070,6 +5070,12 @@ var IndexedDbFileSystemService = class {
     }
     const existing = parent.children?.find((c) => c.name === fileName);
     const now = Date.now();
+    if (existing) {
+      this.assertTraverse(resolved, "touch", path);
+      this.assertAccess(existing, "write", "touch", path);
+    } else {
+      this.assertModifyDir(parent, parentPath, "touch", path);
+    }
     if (existing) {
       existing.modifiedAt = now;
     } else {
@@ -4096,6 +5102,8 @@ var IndexedDbFileSystemService = class {
       if (node.type === "directory") {
         throw new Error(`write: ${path}: Is a directory`);
       }
+      this.assertTraverse(resolved, "write", path);
+      this.assertAccess(node, "write", "write", path);
       const now = Date.now();
       node.content = append ? (node.content ?? "") + content : content;
       node.size = new Blob([node.content]).size;
@@ -4124,6 +5132,8 @@ var IndexedDbFileSystemService = class {
     if (target.type === "directory" && !recursive) {
       throw new Error(`rm: ${path}: Is a directory`);
     }
+    this.assertModifyDir(parent, parentPath, "rm", path);
+    if (target.type === "directory") this.assertRemovableTree(target, resolved, path);
     parent.children.splice(index, 1);
     parent.modifiedAt = Date.now();
   }
@@ -4138,10 +5148,13 @@ var IndexedDbFileSystemService = class {
         `cp: -r not specified; omitting directory '${src}'`
       );
     }
+    this.assertTraverse(srcResolved, "cp", src);
+    this.assertReadableTree(srcNode, src);
     const destResolved = this.resolvePath(dest);
     const destNode = this.getNode(destResolved);
     if (destNode && destNode.type === "directory") {
-      const clone = this.cloneNode(srcNode);
+      this.assertModifyDir(destNode, destResolved, "cp", dest);
+      const clone = this.ownedByCurrentUser(this.cloneNode(srcNode));
       if (!destNode.children) {
         destNode.children = [];
       }
@@ -4161,7 +5174,8 @@ var IndexedDbFileSystemService = class {
       if (!parent || parent.type !== "directory") {
         throw new Error(`cp: ${parentPath}: No such file or directory`);
       }
-      const clone = this.cloneNode(srcNode);
+      this.assertModifyDir(parent, parentPath, "cp", dest);
+      const clone = this.ownedByCurrentUser(this.cloneNode(srcNode));
       clone.name = newName;
       if (!parent.children) {
         parent.children = [];
@@ -4187,16 +5201,23 @@ var IndexedDbFileSystemService = class {
     }
     const destResolved = this.resolvePath(dest);
     const destNode = this.getNode(destResolved);
+    if (srcNode.type === "directory" && (destResolved === srcResolved || destResolved.startsWith(srcResolved + "/"))) {
+      throw new Error(
+        `mv: cannot move '${src}' to a subdirectory of itself, '${dest}'`
+      );
+    }
     const srcParts = srcResolved.split("/").filter(Boolean);
     const srcParentPath = "/" + srcParts.slice(0, -1).join("/");
     const srcParent = this.getNode(srcParentPath);
     if (!srcParent || !srcParent.children) {
       throw new Error(`mv: ${src}: No such file or directory`);
     }
-    const srcIndex = srcParent.children.findIndex(
-      (c) => c.name === srcNode.name
-    );
+    this.assertModifyDir(srcParent, srcParentPath, "mv", src);
+    if (destResolved === srcResolved || destNode && destNode.type === "directory" && destNode === srcParent) {
+      throw new Error(`mv: '${src}' and '${dest}' are the same file`);
+    }
     if (destNode && destNode.type === "directory") {
+      this.assertModifyDir(destNode, destResolved, "mv", dest);
       if (!destNode.children) {
         destNode.children = [];
       }
@@ -4206,7 +5227,7 @@ var IndexedDbFileSystemService = class {
       if (existingIdx !== -1) {
         destNode.children.splice(existingIdx, 1);
       }
-      srcParent.children.splice(srcIndex, 1);
+      srcParent.children.splice(srcParent.children.indexOf(srcNode), 1);
       destNode.children.push(srcNode);
       destNode.modifiedAt = Date.now();
     } else {
@@ -4219,7 +5240,8 @@ var IndexedDbFileSystemService = class {
           `mv: ${destParentPath}: No such file or directory`
         );
       }
-      srcParent.children.splice(srcIndex, 1);
+      this.assertModifyDir(destParent, destParentPath, "mv", dest);
+      srcParent.children.splice(srcParent.children.indexOf(srcNode), 1);
       srcNode.name = newName;
       if (!destParent.children) {
         destParent.children = [];
@@ -4242,6 +5264,9 @@ var IndexedDbFileSystemService = class {
     if (!node) {
       throw new Error(`chmod: ${path}: No such file or directory`);
     }
+    if (this.enforcing && !this.accessPolicy.canChangeOwnership(node)) {
+      this.deny("chmod", path, "Operation not permitted");
+    }
     node.permissions = permissions;
   }
   chown(path, ownership) {
@@ -4250,6 +5275,9 @@ var IndexedDbFileSystemService = class {
     if (!node) {
       throw new Error(`chown: ${path}: No such file or directory`);
     }
+    if (this.enforcing && !this.accessPolicy.canChangeOwnership(node, ownership)) {
+      this.deny("chown", path, "Operation not permitted");
+    }
     node.ownership = ownership;
   }
   // --- Persistence ---
@@ -4280,8 +5308,10 @@ var IndexedDbFileSystemService = class {
       const tx = db.transaction(STORE_NAME, "readwrite");
       const store = tx.objectStore(STORE_NAME);
       store.put(this.root, ROOT_KEY);
-      store.put(this.cwd, CWD_KEY);
-      store.put(this.homePath, HOME_KEY);
+      if (!this.currentUid) {
+        store.put(this.cwd, CWD_KEY);
+        store.put(this.homePath, HOME_KEY);
+      }
       await new Promise((resolve, reject) => {
         tx.oncomplete = () => resolve();
         tx.onerror = () => reject(tx.error);
@@ -4291,6 +5321,18 @@ var IndexedDbFileSystemService = class {
     }
   }
   // --- Private helpers ---
+  /** A copy belongs to whoever made it (like `cp` without `-p`) */
+  ownedByCurrentUser(node) {
+    const owner = this.getDefaultOwnership();
+    if (owner) {
+      const apply = (n) => {
+        n.ownership = { ...owner };
+        n.children?.forEach(apply);
+      };
+      apply(node);
+    }
+    return node;
+  }
   cloneNode(node) {
     const now = Date.now();
     const clone = {
@@ -4332,8 +5374,6 @@ var IndexedDbFileSystemService = class {
     });
   }
 };
-
-// src/lib/services/server-file-system.service.ts
 var DEFAULT_HOME2 = "/home/user";
 function createSeedFileSystem2() {
   const now = Date.now();
@@ -4383,6 +5423,7 @@ var ServerFileSystemService = class {
     this.currentUid = null;
     this.currentGroups = [];
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.headersProvider = options.headers;
   }
   // --- User context ---
   setCurrentUser(uid, groups) {
@@ -4699,15 +5740,20 @@ var ServerFileSystemService = class {
     }
     const destResolved = this.resolvePath(dest);
     const destNode = this.getNode(destResolved);
+    if (srcNode.type === "directory" && (destResolved === srcResolved || destResolved.startsWith(srcResolved + "/"))) {
+      throw new Error(
+        `mv: cannot move '${src}' to a subdirectory of itself, '${dest}'`
+      );
+    }
     const srcParts = srcResolved.split("/").filter(Boolean);
     const srcParentPath = "/" + srcParts.slice(0, -1).join("/");
     const srcParent = this.getNode(srcParentPath);
     if (!srcParent || !srcParent.children) {
       throw new Error(`mv: ${src}: No such file or directory`);
     }
-    const srcIndex = srcParent.children.findIndex(
-      (c) => c.name === srcNode.name
-    );
+    if (destResolved === srcResolved || destNode && destNode.type === "directory" && destNode === srcParent) {
+      throw new Error(`mv: '${src}' and '${dest}' are the same file`);
+    }
     if (destNode && destNode.type === "directory") {
       if (!destNode.children) {
         destNode.children = [];
@@ -4718,7 +5764,7 @@ var ServerFileSystemService = class {
       if (existingIdx !== -1) {
         destNode.children.splice(existingIdx, 1);
       }
-      srcParent.children.splice(srcIndex, 1);
+      srcParent.children.splice(srcParent.children.indexOf(srcNode), 1);
       destNode.children.push(srcNode);
       destNode.modifiedAt = Date.now();
     } else {
@@ -4731,7 +5777,7 @@ var ServerFileSystemService = class {
           `mv: ${destParentPath}: No such file or directory`
         );
       }
-      srcParent.children.splice(srcIndex, 1);
+      srcParent.children.splice(srcParent.children.indexOf(srcNode), 1);
       srcNode.name = newName;
       if (!destParent.children) {
         destParent.children = [];
@@ -4790,7 +5836,14 @@ var ServerFileSystemService = class {
   // --- Private: server communication ---
   async serverFetch(endpoint, options) {
     const url = `${this.baseUrl}/api/qcli/fs${endpoint}`;
-    const response = await fetch(url, options);
+    const mergedHeaders = {
+      ...cliCore.resolveHeaders(this.headersProvider),
+      ...options?.headers ?? {}
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers: mergedHeaders
+    });
     if (!response.ok) {
       const body = await response.text();
       throw new Error(
@@ -4959,6 +6012,115 @@ var VirtualFsFileTransferService = class {
     return this._browserService.uploadFromBrowser(accept);
   }
 };
+var CliFilesPermissions = {
+  /** Bypass all file permission checks */
+  Admin: "files:admin",
+  /** chmod/chown files you do not own */
+  Chown: "files:chown"
+};
+var HOME_DIR_PERMISSIONS = "rwxr-x---";
+function authorization(context) {
+  try {
+    return context.services.get(cliCore.ICliAuthorizationService_TOKEN);
+  } catch {
+    return void 0;
+  }
+}
+function createFileAccessPolicy(context) {
+  return {
+    // Nodes without an owner (system seed, legacy data) belong to root:admin
+    canAccess: (node, action) => cliCore.cliCanAccess(
+      context,
+      node.ownership ? node : { ...node, ownership: SYSTEM_OWNERSHIP },
+      action,
+      [CliFilesPermissions.Admin]
+    ),
+    canChangeOwnership: (node, newOwnership) => {
+      const auth = authorization(context);
+      if (!auth) return true;
+      if (auth.can(CliFilesPermissions.Admin) || auth.can(CliFilesPermissions.Chown)) return true;
+      const principal = auth.getPrincipal();
+      if (!principal) return false;
+      const owns = !!node.ownership && (node.ownership.uid === principal.name || node.ownership.uid === principal.id);
+      const keepsOwner = !newOwnership || newOwnership.uid === node.ownership?.uid || newOwnership.uid === principal.name;
+      return owns && keepsOwner;
+    }
+  };
+}
+function followUserSession(context, fs) {
+  let sessions;
+  try {
+    sessions = context.services.get(cliCore.ICliUserSessionService_TOKEN);
+  } catch {
+    sessions = void 0;
+  }
+  if (!sessions) return void 0;
+  let previousUser = null;
+  return sessions.getUserSession().subscribe((session) => {
+    if (!session?.user) {
+      fs.setCurrentUser("", []);
+      if (previousUser !== null || !canEnter(fs, fs.getCurrentDirectory())) {
+        try {
+          fs.setCurrentDirectory("/");
+          void fs.persist();
+        } catch {
+        }
+      }
+      previousUser = null;
+      return;
+    }
+    const user = session.user;
+    fs.setCurrentUser(user.name, user.groups ?? []);
+    if (user.homeDir) {
+      const home = user.homeDir;
+      const system = (fn) => fs.runAsSystem ? fs.runAsSystem(fn) : fn();
+      if (!fs.exists(home)) {
+        system(() => {
+          fs.createDirectory(home, true);
+          if (home !== "/") {
+            fs.chown(home, { uid: user.name, gid: user.groups?.[0] ?? "users" });
+            fs.chmod(home, HOME_DIR_PERMISSIONS);
+          }
+        });
+        void fs.persist();
+      }
+      fs.setHomePath(home);
+      if (previousUser !== user.id) {
+        try {
+          fs.setCurrentDirectory(home);
+        } catch {
+        }
+      }
+    }
+    previousUser = user.id;
+  });
+}
+function canEnter(fs, path) {
+  try {
+    fs.setCurrentDirectory(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function followUserAccounts(context, fs) {
+  let events;
+  try {
+    events = context.services.get(cliCore.ICliUserEventService_TOKEN);
+  } catch {
+    events = void 0;
+  }
+  if (!events || !fs.reassignOwner) return void 0;
+  return events.events$.subscribe((event) => {
+    let changed = 0;
+    if (event.type === "user_updated" && event.previousName && event.previousName !== event.user?.name) {
+      changed = fs.reassignOwner(event.previousName, event.user.name);
+    } else if (event.type === "user_deleted" && event.user?.name) {
+      changed = fs.reassignOwner(event.user.name, SYSTEM_OWNERSHIP.uid);
+    }
+    if (changed > 0) void fs.persist().catch(() => void 0);
+  });
+}
 
 // src/lib/completion/file-path-completion-provider.ts
 var FILE_COMMANDS = /* @__PURE__ */ new Set([
@@ -4979,7 +6141,26 @@ var FILE_COMMANDS = /* @__PURE__ */ new Set([
   "find",
   "head",
   "tail",
-  "wc"
+  "wc",
+  "sort",
+  "uniq",
+  "cut",
+  "paste",
+  "tac",
+  "diff",
+  "sed",
+  "awk",
+  "du",
+  "stat",
+  "chmod",
+  "chown",
+  "ln",
+  "tee",
+  "basename",
+  "dirname",
+  "sh",
+  "source",
+  "xargs"
 ]);
 var FilePathCompletionProvider = class {
   constructor(fs) {
@@ -4998,7 +6179,14 @@ var FilePathCompletionProvider = class {
     if (token.startsWith("-")) {
       return [];
     }
-    return this.completePath(token);
+    const quote = token.startsWith('"') || token.startsWith("'") ? token[0] : "";
+    const partial = quote ? token.slice(1).replace(new RegExp(`${quote}$`), "") : token;
+    const paths = this.completePath(partial);
+    if (!quote && !paths.some((p) => /\s/.test(p))) {
+      return paths;
+    }
+    const q = quote || '"';
+    return paths.map((p) => p.endsWith("/") ? `${q}${p}` : `${q}${p}${q}`);
   }
   completePath(partial) {
     let dirPath;
@@ -5059,10 +6247,10 @@ var CliUploadCommandProcessor = class {
     ];
   }
   async processCommand(command, context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
-    const fileService = context.services.get(
+    const fileService = context.services.getRequired(
       cliCore.ICliFileTransferService_TOKEN
     );
     if (!fileService) {
@@ -5072,6 +6260,7 @@ var CliUploadCommandProcessor = class {
     const accept = command.args?.["accept"];
     const destPath = command.value?.trim() || void 0;
     context.spinner?.show("Waiting for file selection...");
+    context.notifier.info("Waiting for file selection");
     const picked = await fileService.uploadFromBrowser(accept);
     if (!picked) {
       context.spinner?.hide();
@@ -5084,6 +6273,7 @@ var CliUploadCommandProcessor = class {
       filename.startsWith("/") ? filename : cwd + "/" + filename
     );
     context.spinner?.show(`Saving "${picked.name}" (${picked.content.length} bytes)...`);
+    context.notifier.info(`Saving ${picked.name}`);
     try {
       fs.writeFile(resolved, picked.content);
       await fs.persist();
@@ -5151,6 +6341,10 @@ var filesModule = {
     new CliShCommandProcessor(),
     new CliUploadCommandProcessor()
   ],
+  permissions: [
+    { name: CliFilesPermissions.Admin, description: "Bypass file permission checks" },
+    { name: CliFilesPermissions.Chown, description: "chmod/chown files owned by others" }
+  ],
   services: [
     {
       provide: IFileSystemService_TOKEN,
@@ -5182,7 +6376,7 @@ var filesModule = {
     return { ...this, config };
   },
   async onInit(context) {
-    const fs = context.services.get(
+    const fs = context.services.getRequired(
       IFileSystemService_TOKEN
     );
     await fs.initialize();
@@ -5193,7 +6387,7 @@ var filesModule = {
     }
     let dragDrop;
     try {
-      dragDrop = context.services.get(cliCore.ICliDragDropService_TOKEN);
+      dragDrop = context.services.getRequired(cliCore.ICliDragDropService_TOKEN);
     } catch {
     }
     if (dragDrop) {
@@ -5222,13 +6416,26 @@ var filesModule = {
       });
     }
   },
+  async onAfterBoot(context) {
+    const fs = context.services.getRequired(IFileSystemService_TOKEN);
+    fs.setAccessPolicy?.(createFileAccessPolicy(context));
+    this._sessionSubscription?.unsubscribe();
+    this._sessionSubscription = followUserSession(context, fs);
+    this._accountsSubscription?.unsubscribe();
+    this._accountsSubscription = followUserAccounts(context, fs);
+  },
   async onDestroy(_context) {
     const sub = this._dragDropSubscription;
     sub?.unsubscribe();
     this._dragDropSubscription = void 0;
+    this._sessionSubscription?.unsubscribe();
+    this._sessionSubscription = void 0;
+    this._accountsSubscription?.unsubscribe();
+    this._accountsSubscription = void 0;
   }
 };
 
+exports.ANONYMOUS_OWNERSHIP = ANONYMOUS_OWNERSHIP;
 exports.CliAwkCommandProcessor = CliAwkCommandProcessor;
 exports.CliBasenameCommandProcessor = CliBasenameCommandProcessor;
 exports.CliCatCommandProcessor = CliCatCommandProcessor;
@@ -5241,6 +6448,7 @@ exports.CliDiffCommandProcessor = CliDiffCommandProcessor;
 exports.CliDirnameCommandProcessor = CliDirnameCommandProcessor;
 exports.CliDuCommandProcessor = CliDuCommandProcessor;
 exports.CliEchoCommandProcessor = CliEchoCommandProcessor;
+exports.CliFilesPermissions = CliFilesPermissions;
 exports.CliFindCommandProcessor = CliFindCommandProcessor;
 exports.CliGrepCommandProcessor = CliGrepCommandProcessor;
 exports.CliHeadCommandProcessor = CliHeadCommandProcessor;
@@ -5266,11 +6474,16 @@ exports.CliUniqCommandProcessor = CliUniqCommandProcessor;
 exports.CliWcCommandProcessor = CliWcCommandProcessor;
 exports.CliXargsCommandProcessor = CliXargsCommandProcessor;
 exports.FilePathCompletionProvider = FilePathCompletionProvider;
+exports.HOME_DIR_PERMISSIONS = HOME_DIR_PERMISSIONS;
 exports.IFileSystemService_TOKEN = IFileSystemService_TOKEN;
 exports.IndexedDbFileSystemService = IndexedDbFileSystemService;
+exports.SYSTEM_OWNERSHIP = SYSTEM_OWNERSHIP;
 exports.ServerFileSystemService = ServerFileSystemService;
 exports.VirtualFsFileTransferService = VirtualFsFileTransferService;
+exports.createFileAccessPolicy = createFileAccessPolicy;
 exports.executeScript = executeScript;
 exports.filesModule = filesModule;
+exports.followUserAccounts = followUserAccounts;
+exports.followUserSession = followUserSession;
 //# sourceMappingURL=public-api.js.map
 //# sourceMappingURL=public-api.js.map