typescript-virtual-container 1.2.8 → 1.3.0

package/dist/commands/adduser.d.ts

@@ -1,3 +1,9 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Add a new user to the virtual user database.
+ * @category users
+ * @params ["<username> <password>"]
+ * @returns ShellModule
+ */
 export declare const adduserCommand: ShellModule;
 //# sourceMappingURL=adduser.d.ts.map

package/dist/commands/adduser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adduser.d.ts","sourceRoot":"","sources":["../../src/commands/adduser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,eAAO,MAAM,cAAc,EAAE,WAqB5B,CAAC"}
+{"version":3,"file":"adduser.d.ts","sourceRoot":"","sources":["../../src/commands/adduser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,WAqB5B,CAAC"}

package/dist/commands/adduser.js

@@ -1,3 +1,9 @@
+/**
+ * Add a new user to the virtual user database.
+ * @category users
+ * @params ["<username> <password>"]
+ * @returns ShellModule
+ */
 export const adduserCommand = {
     name: "adduser",
     description: "Add a new user",

package/dist/commands/alias.d.ts

@@ -0,0 +1,9 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Manage shell aliases (list / set / remove).
+ * @category shell
+ * @params ["[name[=value] ...]"]
+ */
+export declare const aliasCommand: ShellModule;
+export declare const unaliasCommand: ShellModule;
+//# sourceMappingURL=alias.d.ts.map

package/dist/commands/alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias.d.ts","sourceRoot":"","sources":["../../src/commands/alias.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAkC1B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAoB5B,CAAC"}

package/dist/commands/alias.js

@@ -0,0 +1,63 @@
+import { ifFlag } from "./command-helpers";
+/**
+ * Manage shell aliases (list / set / remove).
+ * @category shell
+ * @params ["[name[=value] ...]"]
+ */
+export const aliasCommand = {
+    name: "alias",
+    description: "Define or display aliases",
+    category: "shell",
+    params: ["[name[=value] ...]"],
+    run: ({ args, env }) => {
+        if (!env)
+            return { exitCode: 0 };
+        // Aliases stored in env.vars under prefix __alias_
+        if (args.length === 0) {
+            const aliases = Object.entries(env.vars)
+                .filter(([k]) => k.startsWith("__alias_"))
+                .map(([k, v]) => `alias ${k.slice("__alias_".length)}='${v}'`);
+            return { stdout: aliases.join("\n") || "", exitCode: 0 };
+        }
+        const lines = [];
+        for (const arg of args) {
+            const eq = arg.indexOf("=");
+            if (eq === -1) {
+                // Display single alias
+                const val = env.vars[`__alias_${arg}`];
+                if (val)
+                    lines.push(`alias ${arg}='${val}'`);
+                else
+                    return { stderr: `alias: ${arg}: not found`, exitCode: 1 };
+            }
+            else {
+                // Set alias
+                const name = arg.slice(0, eq);
+                const val = arg.slice(eq + 1).replace(/^['"]|['"]$/g, "");
+                env.vars[`__alias_${name}`] = val;
+            }
+        }
+        return { stdout: lines.join("\n") || undefined, exitCode: 0 };
+    },
+};
+export const unaliasCommand = {
+    name: "unalias",
+    description: "Remove alias definitions",
+    category: "shell",
+    params: ["<name...> | -a"],
+    run: ({ args, env }) => {
+        if (!env)
+            return { exitCode: 0 };
+        if (ifFlag(args, ["-a"])) {
+            for (const k of Object.keys(env.vars)) {
+                if (k.startsWith("__alias_"))
+                    delete env.vars[k];
+            }
+            return { exitCode: 0 };
+        }
+        for (const name of args) {
+            delete env.vars[`__alias_${name}`];
+        }
+        return { exitCode: 0 };
+    },
+};

package/dist/commands/apt.d.ts

@@ -0,0 +1,9 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * APT package manager front-end (simulated).
+ * @category package
+ * @params ["<install|remove|update|upgrade|search|show|list> [pkg...]"]
+ */
+export declare const aptCommand: ShellModule;
+export declare const aptCacheCommand: ShellModule;
+//# sourceMappingURL=apt.d.ts.map

package/dist/commands/apt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apt.d.ts","sourceRoot":"","sources":["../../src/commands/apt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAyJxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WA+D7B,CAAC"}

package/dist/commands/apt.js

@@ -0,0 +1,205 @@
+import { ifFlag } from "./command-helpers";
+import { getPackageManager } from "./helpers";
+/**
+ * APT package manager front-end (simulated).
+ * @category package
+ * @params ["<install|remove|update|upgrade|search|show|list> [pkg...]"]
+ */
+export const aptCommand = {
+    name: "apt",
+    aliases: ["apt-get"],
+    description: "Package manager",
+    category: "package",
+    params: ["<install|remove|update|upgrade|search|show|list> [pkg...]"],
+    run: ({ args, shell, authUser }) => {
+        const pm = getPackageManager(shell);
+        if (!pm)
+            return { stderr: "apt: package manager not initialised", exitCode: 1 };
+        const sub = args[0]?.toLowerCase();
+        const rest = args.slice(1);
+        const quiet = ifFlag(rest, ["-q", "--quiet", "-qq"]);
+        const purge = ifFlag(rest, ["--purge"]);
+        const pkgs = rest.filter((a) => !a.startsWith("-"));
+        // Non-root check
+        const restricted = ["install", "remove", "purge", "upgrade", "update"];
+        if (restricted.includes(sub ?? "") && authUser !== "root") {
+            return {
+                stderr: "E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock, are you root?",
+                exitCode: 100,
+            };
+        }
+        switch (sub) {
+            case "install": {
+                if (pkgs.length === 0)
+                    return { stderr: "apt: no packages specified", exitCode: 1 };
+                const { output, exitCode } = pm.install(pkgs, { quiet });
+                return { stdout: output || undefined, exitCode };
+            }
+            case "remove":
+            case "purge": {
+                if (pkgs.length === 0)
+                    return { stderr: "apt: no packages specified", exitCode: 1 };
+                const { output, exitCode } = pm.remove(pkgs, {
+                    purge: sub === "purge" || purge,
+                    quiet,
+                });
+                return { stdout: output || undefined, exitCode };
+            }
+            case "update": {
+                return {
+                    stdout: [
+                        "Hit:1 fortune://packages.fortune.local aurora InRelease",
+                        "Hit:2 fortune://security.fortune.local aurora-security InRelease",
+                        "Reading package lists... Done",
+                        "Building dependency tree... Done",
+                        "Reading state information... Done",
+                        `All packages are up to date.`,
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            case "upgrade": {
+                return {
+                    stdout: [
+                        "Reading package lists... Done",
+                        "Building dependency tree... Done",
+                        "Reading state information... Done",
+                        "Calculating upgrade... Done",
+                        "0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.",
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            case "search": {
+                const term = pkgs[0];
+                if (!term)
+                    return { stderr: "apt: search requires a term", exitCode: 1 };
+                const results = pm.search(term);
+                if (results.length === 0)
+                    return {
+                        stdout: `Sorting... Done\nFull Text Search... Done\n(no results)`,
+                        exitCode: 0,
+                    };
+                const lines = results.map((p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64\n  ${p.shortDesc ?? p.description}`);
+                return {
+                    stdout: `Sorting... Done\nFull Text Search... Done\n${lines.join("\n")}`,
+                    exitCode: 0,
+                };
+            }
+            case "show": {
+                const name = pkgs[0];
+                if (!name)
+                    return { stderr: "apt: show requires a package name", exitCode: 1 };
+                const info = pm.show(name);
+                if (!info)
+                    return {
+                        stderr: `N: Unable to locate package ${name}`,
+                        exitCode: 100,
+                    };
+                return { stdout: info, exitCode: 0 };
+            }
+            case "list": {
+                const installedFlag = ifFlag(rest, ["--installed"]);
+                if (installedFlag) {
+                    const pkgList = pm.listInstalled();
+                    if (pkgList.length === 0)
+                        return {
+                            stdout: "Listing... Done\n(no packages installed)",
+                            exitCode: 0,
+                        };
+                    const lines = pkgList.map((p) => `${p.name}/${p.section} ${p.version} ${p.architecture} [installed]`);
+                    return {
+                        stdout: `Listing... Done\n${lines.join("\n")}`,
+                        exitCode: 0,
+                    };
+                }
+                // all available
+                const all = pm.listAvailable();
+                const lines = all.map((p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64`);
+                return { stdout: `Listing... Done\n${lines.join("\n")}`, exitCode: 0 };
+            }
+            default: {
+                return {
+                    stdout: [
+                        "Usage: apt [options] command",
+                        "",
+                        "Commands:",
+                        "  install <pkg...>   Install packages",
+                        "  remove <pkg...>    Remove packages",
+                        "  purge <pkg...>     Remove packages and config files",
+                        "  update             Refresh package index",
+                        "  upgrade            Upgrade all packages",
+                        "  search <term>      Search in package descriptions",
+                        "  show <pkg>         Show package details",
+                        "  list [--installed] List packages",
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+        }
+    },
+};
+export const aptCacheCommand = {
+    name: "apt-cache",
+    description: "Query the package cache",
+    category: "package",
+    params: ["<search|show|policy> [pkg]"],
+    run: ({ args, shell }) => {
+        const pm = getPackageManager(shell);
+        if (!pm)
+            return {
+                stderr: "apt-cache: package manager not initialised",
+                exitCode: 1,
+            };
+        const sub = args[0]?.toLowerCase();
+        const pkgName = args[1];
+        switch (sub) {
+            case "search": {
+                if (!pkgName)
+                    return { stderr: "Need a search term", exitCode: 1 };
+                const results = pm.search(pkgName);
+                return {
+                    stdout: results
+                        .map((p) => `${p.name} - ${p.shortDesc ?? p.description}`)
+                        .join("\n") || "(no results)",
+                    exitCode: 0,
+                };
+            }
+            case "show": {
+                if (!pkgName)
+                    return { stderr: "Need a package name", exitCode: 1 };
+                const info = pm.show(pkgName);
+                return info
+                    ? { stdout: info, exitCode: 0 }
+                    : { stderr: `N: Unable to locate package ${pkgName}`, exitCode: 100 };
+            }
+            case "policy": {
+                if (!pkgName)
+                    return { stderr: "Need a package name", exitCode: 1 };
+                const def = pm.findInRegistry(pkgName);
+                if (!def)
+                    return {
+                        stderr: `N: Unable to locate package ${pkgName}`,
+                        exitCode: 100,
+                    };
+                const inst = pm.isInstalled(pkgName);
+                return {
+                    stdout: [
+                        `${pkgName}:`,
+                        `  Installed: ${inst ? def.version : "(none)"}`,
+                        `  Candidate: ${def.version}`,
+                        `  Version table:`,
+                        `     ${def.version} 500`,
+                        `        500 fortune://packages.fortune.local aurora/main amd64 Packages`,
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            default:
+                return {
+                    stderr: `apt-cache: unknown command '${sub ?? ""}'`,
+                    exitCode: 1,
+                };
+        }
+    },
+};

package/dist/commands/awk.d.ts

@@ -1,3 +1,14 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Minimal `awk`-like pattern scanner (supports simple print patterns).
+ * @category text
+ * @params ["[-F <sep>] '<program>' [file]"]
+ *
+ * Supported program patterns:
+ * - `print $N` (e.g. `print $1`, `print $2, $3`, `print $0`)
+ * - `{print $N}` (e.g. `{print $1}`, `{print $2, $3}`, `{print $0}`)
+ *
+ * The field separator can be set with `-F` (default is space, which splits on any whitespace).
+ */
 export declare const awkCommand: ShellModule;
 //# sourceMappingURL=awk.d.ts.map

package/dist/commands/awk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"awk.d.ts","sourceRoot":"","sources":["../../src/commands/awk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,UAAU,EAAE,WA0BxB,CAAC"}
+{"version":3,"file":"awk.d.ts","sourceRoot":"","sources":["../../src/commands/awk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,WA6BxB,CAAC"}

package/dist/commands/awk.js

@@ -1,4 +1,15 @@
 import { getFlag } from "./command-helpers";
+/**
+ * Minimal `awk`-like pattern scanner (supports simple print patterns).
+ * @category text
+ * @params ["[-F <sep>] '<program>' [file]"]
+ *
+ * Supported program patterns:
+ * - `print $N` (e.g. `print $1`, `print $2, $3`, `print $0`)
+ * - `{print $N}` (e.g. `{print $1}`, `{print $2, $3}`, `{print $0}`)
+ *
+ * The field separator can be set with `-F` (default is space, which splits on any whitespace).
+ */
 export const awkCommand = {
     name: "awk",
     description: "Pattern scanning and processing language (minimal)",
@@ -17,12 +28,14 @@ export const awkCommand = {
         const lines = (stdin ?? "").split("\n").filter(Boolean);
         const out = lines.map((line) => {
             const parts = line.split(sep === " " ? /\s+/ : sep);
-            return fields.map((f) => {
+            return fields
+                .map((f) => {
                 if (f === "$0")
                     return line;
                 const n = parseInt(f.replace("$", ""), 10);
                 return Number.isNaN(n) ? f.replace(/"/g, "") : (parts[n - 1] ?? "");
-            }).join(sep === " " ? "\t" : sep);
+            })
+                .join(sep === " " ? "\t" : sep);
         });
         return { stdout: out.join("\n"), exitCode: 0 };
     },

package/dist/commands/base64.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Encode or decode base64 data.
+ * @category text
+ * @params ["[-d] [file]"]
+ */
 export declare const base64Command: ShellModule;
 //# sourceMappingURL=base64.d.ts.map

package/dist/commands/base64.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/commands/base64.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,aAAa,EAAE,WAc3B,CAAC"}
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/commands/base64.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAoB3B,CAAC"}

package/dist/commands/base64.js

@@ -1,4 +1,9 @@
 import { ifFlag } from "./command-helpers";
+/**
+ * Encode or decode base64 data.
+ * @category text
+ * @params ["[-d] [file]"]
+ */
 export const base64Command = {
     name: "base64",
     description: "Encode/decode base64",
@@ -9,7 +14,10 @@ export const base64Command = {
         const input = stdin ?? "";
         if (decode) {
             try {
-                return { stdout: Buffer.from(input.trim(), "base64").toString("utf8"), exitCode: 0 };
+                return {
+                    stdout: Buffer.from(input.trim(), "base64").toString("utf8"),
+                    exitCode: 0,
+                };
             }
             catch {
                 return { stderr: "base64: invalid input", exitCode: 1 };

package/dist/commands/cat.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Concatenate and print files to stdout.
+ * @category files
+ * @params ["[-n] [-b] <file...>"]
+ */
 export declare const catCommand: ShellModule;
 //# sourceMappingURL=cat.d.ts.map

package/dist/commands/cat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cat.d.ts","sourceRoot":"","sources":["../../src/commands/cat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,eAAO,MAAM,UAAU,EAAE,WAexB,CAAC"}
+{"version":3,"file":"cat.d.ts","sourceRoot":"","sources":["../../src/commands/cat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WA0CxB,CAAC"}

package/dist/commands/cat.js

@@ -1,17 +1,44 @@
-import { getArg } from "./command-helpers";
+import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolveReadablePath } from "./helpers";
+/**
+ * Concatenate and print files to stdout.
+ * @category files
+ * @params ["[-n] [-b] <file...>"]
+ */
 export const catCommand = {
     name: "cat",
     description: "Concatenate and print files",
     category: "files",
-    params: ["<file>"],
-    run: ({ authUser, shell, cwd, args }) => {
-        const fileArg = getArg(args, 0);
-        if (!fileArg) {
+    params: ["[-n] [-b] <file...>"],
+    run: ({ authUser, shell, cwd, args, stdin }) => {
+        const numberAll = ifFlag(args, ["-n", "--number"]);
+        const numberNonBlank = ifFlag(args, ["-b", "--number-nonblank"]);
+        const fileArgs = args.filter((a) => !a.startsWith("-"));
+        if (fileArgs.length === 0 && stdin !== undefined) {
+            return { stdout: stdin, exitCode: 0 };
+        }
+        if (fileArgs.length === 0) {
             return { stderr: "cat: missing file operand", exitCode: 1 };
         }
-        const target = resolveReadablePath(shell.vfs, cwd, fileArg);
-        assertPathAccess(authUser, target, "cat");
-        return { stdout: shell.vfs.readFile(target), exitCode: 0 };
+        const parts = [];
+        for (const fileArg of fileArgs) {
+            const target = resolveReadablePath(shell.vfs, cwd, fileArg);
+            assertPathAccess(authUser, target, "cat");
+            parts.push(shell.vfs.readFile(target));
+        }
+        const combined = parts.join("");
+        if (!numberAll && !numberNonBlank) {
+            return { stdout: combined, exitCode: 0 };
+        }
+        let lineNum = 1;
+        const numbered = combined
+            .split("\n")
+            .map((line) => {
+            if (numberNonBlank && line.trim() === "")
+                return line;
+            return `${String(lineNum++).padStart(6)}\t${line}`;
+        })
+            .join("\n");
+        return { stdout: numbered, exitCode: 0 };
     },
 };

package/dist/commands/cd.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Change current working directory.
+ * @category navigation
+ * @params ["[path]"]
+ */
 export declare const cdCommand: ShellModule;
 //# sourceMappingURL=cd.d.ts.map

package/dist/commands/cd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cd.d.ts","sourceRoot":"","sources":["../../src/commands/cd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,SAAS,EAAE,WAmBvB,CAAC"}
+{"version":3,"file":"cd.d.ts","sourceRoot":"","sources":["../../src/commands/cd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,WAmBvB,CAAC"}

package/dist/commands/cd.js

@@ -1,4 +1,9 @@
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Change current working directory.
+ * @category navigation
+ * @params ["[path]"]
+ */
 export const cdCommand = {
     name: "cd",
     description: "Change directory",

package/dist/commands/chmod.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Change file permissions (octal or symbolic).
+ * @category files
+ * @params ["<mode> <file>"]
+ */
 export declare const chmodCommand: ShellModule;
 //# sourceMappingURL=chmod.d.ts.map

package/dist/commands/chmod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chmod.d.ts","sourceRoot":"","sources":["../../src/commands/chmod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,YAAY,EAAE,WA+B1B,CAAC"}
+{"version":3,"file":"chmod.d.ts","sourceRoot":"","sources":["../../src/commands/chmod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuCrD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAwC1B,CAAC"}

package/dist/commands/chmod.js

@@ -1,4 +1,48 @@
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Parse a symbolic chmod mode string (e.g. "+x", "u+x", "go-w", "a+rx")
+ * and apply it to the existing mode bits.
+ * Returns null if the string is not a valid symbolic mode.
+ */
+function applySymbolicMode(existing, modeStr) {
+    const pattern = /^([ugoa]*)([+\-=])([rwx]*)$/;
+    const parts = modeStr.split(",");
+    let mode = existing;
+    for (const part of parts) {
+        const m = part.trim().match(pattern);
+        if (!m)
+            return null;
+        const [, who = "a", op, perms = ""] = m;
+        const targets = who === "" || who === "a" ? ["u", "g", "o"] : who.split("");
+        const bits = {
+            u: { r: 0o400, w: 0o200, x: 0o100 },
+            g: { r: 0o040, w: 0o020, x: 0o010 },
+            o: { r: 0o004, w: 0o002, x: 0o001 },
+        };
+        for (const t of targets) {
+            for (const p of perms.split("")) {
+                const bit = bits[t]?.[p];
+                if (bit === undefined)
+                    continue;
+                if (op === "+")
+                    mode |= bit;
+                else if (op === "-")
+                    mode &= ~bit;
+                else if (op === "=") {
+                    // clear all bits for this target, then set requested
+                    const mask = Object.values(bits[t] ?? {}).reduce((a, b) => a | b, 0);
+                    mode = (mode & ~mask) | bit;
+                }
+            }
+        }
+    }
+    return mode;
+}
+/**
+ * Change file permissions (octal or symbolic).
+ * @category files
+ * @params ["<mode> <file>"]
+ */
 export const chmodCommand = {
     name: "chmod",
     description: "Change file permissions",
@@ -18,9 +62,19 @@ export const chmodCommand = {
                     exitCode: 1,
                 };
             }
-            const mode = parseInt(modeArg, 8);
-            if (Number.isNaN(mode)) {
-                return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+            let mode;
+            const octal = parseInt(modeArg, 8);
+            if (!Number.isNaN(octal) && /^[0-7]+$/.test(modeArg)) {
+                mode = octal;
+            }
+            else {
+                // symbolic mode
+                const existing = shell.vfs.stat(filePath).mode;
+                const result = applySymbolicMode(existing, modeArg);
+                if (result === null) {
+                    return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+                }
+                mode = result;
             }
             shell.vfs.chmod(filePath, mode);
             return { exitCode: 0 };