typescript-virtual-container 1.5.10 → 1.6.0

package/dist/commands/helpers.js

@@ -1,5 +1,15 @@
 import * as path from "node:path";
 const PROTECTED_PREFIXES = ["/.virtual-env-js/.auth", "/etc/htpasswd"];
+/**
+ * Resolves a path string against the virtual file system.
+ * Supports `~` as shorthand for the home directory. If `inputPath` is
+ * absolute it is returned as-is; otherwise it is joined to `cwd`.
+ *
+ * @param cwd       - The current working directory
+ * @param inputPath - The path string to resolve
+ * @param homeDir   - The home directory to use for `~` expansion (defaults to `/root`)
+ * @returns The normalized absolute path
+ */
 export function resolvePath(cwd, inputPath, homeDir) {
     if (!inputPath || inputPath.trim() === "") {
         return cwd;
@@ -26,6 +36,14 @@ export function assertPathAccess(authUser, targetPath, operation) {
         throw new Error(`${operation}: permission denied: ${targetPath}`);
     }
 }
+/**
+ * Strips the filename from a URL path, extracting the last path segment.
+ * Removes query strings and fragments first. Returns `"index.html"` when
+ * no segment is found.
+ *
+ * @param url - The URL or path string to process
+ * @returns The extracted filename, or "index.html" as a fallback
+ */
 export function stripUrlFilename(url) {
     const cleaned = url.split("?")[0]?.split("#")[0] ?? url;
     const lastPart = cleaned.split("/").filter(Boolean).pop();
@@ -47,6 +65,16 @@ function levenshtein(a, b) {
     }
     return dp[a.length][b.length];
 }
+/**
+ * Resolves a path with readable error messages by attempting an exact match
+ * first, then falling back to case-insensitive matching, and finally to a
+ * Levenshtein-distance (≤1) fuzzy match against sibling entries.
+ *
+ * @param vfs       - The virtual file system instance
+ * @param cwd       - The current working directory
+ * @param inputPath - The path string to resolve
+ * @returns The best matching path (exact, case-insensitive, or fuzzy)
+ */
 export function resolveReadablePath(vfs, cwd, inputPath) {
     const exactPath = resolvePath(cwd, inputPath);
     if (vfs.exists(exactPath)) {
@@ -65,6 +93,39 @@ export function resolveReadablePath(vfs, cwd, inputPath) {
     }
     return exactPath;
 }
+/**
+ * Returns the active package manager associated with the given shell.
+ *
+ * @param shell - The VirtualShell instance
+ * @returns The VirtualPackageManager, or undefined if none is configured
+ */
 export function getPackageManager(shell) {
     return shell.packageManager;
 }
+/**
+ * POSIX-style permission check: does `authUser` have `want` access to `filePath`?
+ * `want` is a bitmask: 4=R_OK, 2=W_OK, 1=X_OK, 0=F_OK (check existence).
+ * Root bypasses all checks. Throws on EACCES.
+ */
+export function checkFilePermission(vfs, users, authUser, filePath, want) {
+    if (authUser === "root")
+        return;
+    if (want === 0)
+        return; // F_OK — just existence
+    assertPathAccess(authUser, filePath, "access");
+    const uid = users.getUid(authUser);
+    const gid = users.getGid(authUser);
+    if (!vfs.checkAccess(filePath, uid, gid, want)) {
+        const mode = vfs.stat(filePath).mode;
+        const permStr = (mode & 0o400 ? "r" : "-") +
+            (mode & 0o200 ? "w" : "-") +
+            (mode & 0o100 ? "x" : "-") +
+            (mode & 0o040 ? "r" : "-") +
+            (mode & 0o020 ? "w" : "-") +
+            (mode & 0o010 ? "x" : "-") +
+            (mode & 0o004 ? "r" : "-") +
+            (mode & 0o002 ? "w" : "-") +
+            (mode & 0o001 ? "x" : "-");
+        throw new Error(`access: permission denied (mode=${permStr})`);
+    }
+}

package/dist/commands/id.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Print user identity.
+ * @category system
+ * @params ["[user]"]
+ */
 export declare const idCommand: ShellModule;

package/dist/commands/id.js

@@ -1,3 +1,8 @@
+/**
+ * Print user identity.
+ * @category system
+ * @params ["[user]"]
+ */
 export const idCommand = {
     name: "id",
     description: "Print user identity",

package/dist/commands/ip.d.ts

@@ -1,6 +1,7 @@
 import type { ShellModule } from "../types/commands";
 /**
  * Show/manipulate routing, network devices, interfaces and tunnels.
+ * Uses the shell's VirtualNetworkManager for dynamic output.
  * @category network
  * @params ["<object> <command>"]
  */

package/dist/commands/ip.js

@@ -1,23 +1,6 @@
-const ADDR_OUTPUT = `1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
-    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
-    inet 127.0.0.1/8 scope host lo
-       valid_lft forever preferred_lft forever
-    inet6 ::1/128 scope host
-       valid_lft forever preferred_lft forever
-2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
-    link/ether 02:42:0a:00:00:02 brd ff:ff:ff:ff:ff:ff
-    inet 10.0.0.2/24 brd 10.0.0.255 scope global eth0
-       valid_lft forever preferred_lft forever
-    inet6 fe80::42:aff:fe00:2/64 scope link
-       valid_lft forever preferred_lft forever`;
-const ROUTE_OUTPUT = `default via 10.0.0.1 dev eth0
-10.0.0.0/24 dev eth0 proto kernel scope link src 10.0.0.2`;
-const LINK_OUTPUT = `1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
-    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
-2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
-    link/ether 02:42:0a:00:00:02 brd ff:ff:ff:ff:ff:ff`;
 /**
  * Show/manipulate routing, network devices, interfaces and tunnels.
+ * Uses the shell's VirtualNetworkManager for dynamic output.
  * @category network
  * @params ["<object> <command>"]
  */
@@ -26,23 +9,67 @@ export const ipCommand = {
     description: "Show/manipulate routing, network devices, interfaces",
     category: "network",
     params: ["<object> <command>"],
-    run: ({ args }) => {
+    run: ({ args, shell }) => {
+        const net = shell.network;
         const obj = args[0]?.toLowerCase();
         const cmd = args[1]?.toLowerCase() ?? "show";
         if (!obj) {
             return { stderr: "Usage: ip [ OPTIONS ] OBJECT { COMMAND | help }\nOBJECT := { link | addr | route | neigh }", exitCode: 1 };
         }
         if (obj === "addr" || obj === "address" || obj === "a") {
-            return { stdout: ADDR_OUTPUT, exitCode: 0 };
+            if (cmd === "add") {
+                // ip addr add <ip>/<mask> dev <dev>
+                const ipArg = args.find((a) => a.includes("/"));
+                const devIdx = args.indexOf("dev");
+                const dev = devIdx !== -1 && devIdx + 1 < args.length ? args[devIdx + 1] : undefined;
+                if (ipArg && dev) {
+                    const [ip, maskStr] = ipArg.split("/");
+                    const mask = parseInt(maskStr ?? "24", 10);
+                    net.setInterfaceIp(dev, ip ?? "0.0.0.0", mask);
+                }
+                return { exitCode: 0 };
+            }
+            if (cmd === "del") {
+                const devIdx = args.indexOf("dev");
+                const dev = devIdx !== -1 && devIdx + 1 < args.length ? args[devIdx + 1] : undefined;
+                if (dev)
+                    net.setInterfaceIp(dev, "0.0.0.0", 0);
+                return { exitCode: 0 };
+            }
+            return { stdout: `${net.formatIpAddr()}\n`, exitCode: 0 };
         }
         if (obj === "route" || obj === "r" || obj === "ro") {
-            return { stdout: ROUTE_OUTPUT, exitCode: 0 };
+            if (cmd === "add") {
+                const viaIdx = args.indexOf("via");
+                const devIdx = args.indexOf("dev");
+                const dest = args[1] !== "add" ? args[1] : args[2]; // ip route add <dest> ...
+                const gateway = viaIdx !== -1 ? args[viaIdx + 1] : "0.0.0.0";
+                const device = devIdx !== -1 ? args[devIdx + 1] : "eth0";
+                if (dest && dest !== "add")
+                    net.addRoute(dest, gateway ?? "0.0.0.0", "255.255.255.0", device ?? "eth0");
+                return { exitCode: 0 };
+            }
+            if (cmd === "del") {
+                const dest = args[1] !== "del" ? args[1] : args[2];
+                if (dest && dest !== "del")
+                    net.delRoute(dest);
+                return { exitCode: 0 };
+            }
+            return { stdout: `${net.formatIpRoute()}\n`, exitCode: 0 };
         }
         if (obj === "link" || obj === "l") {
-            return { stdout: LINK_OUTPUT, exitCode: 0 };
+            if (cmd === "set") {
+                const dev = args[2]; // ip link set <dev> ...
+                if (args.includes("up") && dev)
+                    net.setInterfaceState(dev, "UP");
+                if (args.includes("down") && dev)
+                    net.setInterfaceState(dev, "DOWN");
+                return { exitCode: 0 };
+            }
+            return { stdout: `${net.formatIpLink()}\n`, exitCode: 0 };
         }
         if (obj === "neigh" || obj === "n") {
-            return { stdout: "10.0.0.1 dev eth0 lladdr 02:42:0a:00:00:01 REACHABLE", exitCode: 0 };
+            return { stdout: `${net.formatIpNeigh()}\n`, exitCode: 0 };
         }
         if (["set", "add", "del", "flush", "change", "replace"].includes(cmd)) {
             return { exitCode: 0 }; // silently succeed mutations

package/dist/commands/jobs.js

@@ -1,27 +1,61 @@
+function parseJobspec(arg, procs) {
+    if (!arg) {
+        // Default to most recent background job
+        return procs.filter((p) => p.status !== "stopped").pop();
+    }
+    const pid = parseInt(arg.replace(/^%/, ""), 10);
+    return procs.find((p) => p.pid === pid);
+}
 export const jobsCommand = {
     name: "jobs",
     description: "List active jobs",
     category: "shell",
     params: [],
-    run: () => ({ stdout: "", exitCode: 0 }),
+    run: ({ shell }) => {
+        const procs = shell.users.listProcesses();
+        if (procs.length === 0)
+            return { stdout: "", exitCode: 0 };
+        const lines = procs.map((p, i) => {
+            const label = `[${i + 1}]`;
+            const status = p.status === "running" ? "running" : p.status === "done" ? "done" : "stopped";
+            return `${label}  ${String(p.pid).padStart(5)} ${status.padEnd(8)} ${p.argv.join(" ")}`;
+        });
+        return { stdout: `${lines.join("\n")}\n`, exitCode: 0 };
+    },
 };
 export const bgCommand = {
     name: "bg",
     description: "Resume a suspended job in the background",
     category: "shell",
     params: ["[%jobspec]"],
-    run: ({ args }) => ({
-        stderr: `bg: ${args[0] ?? "%1"}: no such job`,
-        exitCode: 1,
-    }),
+    run: ({ args, shell }) => {
+        const procs = shell.users.listProcesses();
+        const proc = parseJobspec(args[0], procs);
+        if (!proc) {
+            return { stderr: `bg: ${args[0] ?? "%1"}: no such job`, exitCode: 1 };
+        }
+        if (proc.status === "done") {
+            return { stderr: `bg: ${args[0]}: job has finished`, exitCode: 1 };
+        }
+        proc.status = "running";
+        return { stdout: `[${procs.indexOf(proc) + 1}]  ${proc.pid}  ${proc.argv.join(" ")} &\n`, exitCode: 0 };
+    },
 };
 export const fgCommand = {
     name: "fg",
     description: "Resume a suspended job in the foreground",
     category: "shell",
     params: ["[%jobspec]"],
-    run: ({ args }) => ({
-        stderr: `fg: ${args[0] ?? "%1"}: no such job`,
-        exitCode: 1,
-    }),
+    run: ({ args, shell }) => {
+        const procs = shell.users.listProcesses();
+        const proc = parseJobspec(args[0], procs);
+        if (!proc) {
+            return { stderr: `fg: ${args[0] ?? "%1"}: no such job`, exitCode: 1 };
+        }
+        if (proc.status === "done") {
+            return { stderr: `fg: ${args[0]}: job has finished`, exitCode: 1 };
+        }
+        proc.status = "running";
+        return { stdout: `${proc.argv.join(" ")}\n`, exitCode: 0 };
+    },
 };

package/dist/commands/kill.d.ts

@@ -1,6 +1,7 @@
 import type { ShellModule } from "../types/commands";
 /**
  * Send a signal to a process by PID.
+ * Supports SIGTERM (default) and SIGKILL (-9). Aborts background processes.
  * @category system
  * @params ["[-9] <pid>"]
  */

package/dist/commands/kill.js

@@ -1,5 +1,6 @@
 /**
  * Send a signal to a process by PID.
+ * Supports SIGTERM (default) and SIGKILL (-9). Aborts background processes.
  * @category system
  * @params ["[-9] <pid>"]
  */
@@ -8,11 +9,18 @@ export const killCommand = {
     description: "Send signal to process",
     category: "system",
     params: ["[-9] <pid>"],
-    run: ({ args }) => {
-        const pid = args.find((a) => !a.startsWith("-"));
-        if (!pid)
+    run: ({ args, shell }) => {
+        const pidStr = args.find((a) => !a.startsWith("-"));
+        if (!pidStr)
             return { stderr: "kill: no pid specified", exitCode: 1 };
-        // In virtual env, we just acknowledge the kill
-        return { stdout: ``, exitCode: 0 };
+        const pid = parseInt(pidStr, 10);
+        if (Number.isNaN(pid)) {
+            return { stderr: `kill: invalid pid: ${pidStr}`, exitCode: 1 };
+        }
+        const found = shell.users.killProcess(pid);
+        if (!found) {
+            return { stderr: `kill: (${pid}) - No such process`, exitCode: 1 };
+        }
+        return { stdout: "", exitCode: 0 };
     },
 };

package/dist/commands/last.js

@@ -22,7 +22,7 @@ export const lastCommand = {
                 }).replace(",", "")}`;
                 lines.push(`${target.padEnd(10)} pts/0        ${(log.from ?? "browser").padEnd(16)} ${ds}   still logged in`);
             }
-            catch { }
+            catch { /* log entry may be corrupt */ }
         }
         lines.push("");
         lines.push(`wtmp begins ${new Date().toDateString()}`);

package/dist/commands/ln.d.ts

@@ -1,4 +1,9 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Create links.
+ * @category files
+ * @params ["[-s] <target> <link_name>"]
+ */
 export declare const lnCommand: ShellModule;
 /** Shell command: print the value of a symbolic link. */
 export declare const readlinkCommand: ShellModule;

package/dist/commands/ln.js

@@ -1,5 +1,10 @@
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Create links.
+ * @category files
+ * @params ["[-s] <target> <link_name>"]
+ */
 export const lnCommand = {
     name: "ln",
     description: "Create links",

package/dist/commands/ls.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * List directory contents.
+ * @category navigation
+ * @params ["[-la] [path]"]
+ */
 export declare const lsCommand: ShellModule;

package/dist/commands/ls.js

@@ -145,13 +145,26 @@ function longListing(vfs, dir, items) {
     });
     const wNlink = Math.max(...rows.map((r) => r.nlink.length));
     const wSize = Math.max(...rows.map((r) => r.size.length));
-    const owner = "root";
-    const group = "root";
     const total = items.length * 8;
-    const lines = rows.map((r) => `${r.perms} ${r.nlink.padStart(wNlink)} ${owner} ${group} ${r.size.padStart(wSize)} ${r.date} ${r.label}`);
+    const lines = rows.map((r, i) => {
+        const st = (() => { try {
+            return vfs.stat(`${base}/${items[i]}`);
+        }
+        catch {
+            return null;
+        } })();
+        const uidStr = st && "uid" in st ? String(st.uid) : "0";
+        const gidStr = st && "gid" in st ? String(st.gid) : "0";
+        return `${r.perms} ${r.nlink.padStart(wNlink)} ${uidStr} ${gidStr} ${r.size.padStart(wSize)} ${r.date} ${r.label}`;
+    });
     return `total ${total}\n${lines.join("\n")}`;
 }
 // ─── command ─────────────────────────────────────────────────────────────────
+/**
+ * List directory contents.
+ * @category navigation
+ * @params ["[-la] [path]"]
+ */
 export const lsCommand = {
     name: "ls",
     description: "List directory contents",
@@ -181,8 +194,10 @@ export const lsCommand = {
                     const label = isLink
                         ? `${colorize(name, color)} -> ${readlinkTarget(shell.vfs, target)}`
                         : colorize(name, color);
+                    const uidStr = "uid" in st ? String(st.uid) : "0";
+                    const gidStr = "gid" in st ? String(st.gid) : "0";
                     return {
-                        stdout: `${perms} 1 root root ${size} ${formatDate(st.updatedAt)} ${label}\n`,
+                        stdout: `${perms} 1 ${uidStr} ${gidStr} ${size} ${formatDate(st.updatedAt)} ${label}\n`,
                         exitCode: 0,
                     };
                 }

package/dist/commands/lsb-release.js

@@ -30,7 +30,7 @@ export const lsbReleaseCommand = {
                         .trim();
             }
         }
-        catch { }
+        catch { /* /etc/os-release may not exist */ }
         const all = ifFlag(args, ["-a", "--all"]);
         const showId = ifFlag(args, ["-i", "--id"]);
         const showDesc = ifFlag(args, ["-d", "--description"]);

package/dist/commands/man.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Interface to the system reference manuals.
+ * @category shell
+ * @params ["<command>"]
+ */
 export declare const manCommand: ShellModule;

package/dist/commands/man.js

@@ -2,6 +2,11 @@ import { MANUALS } from "./manuals-bundle";
 const MANUAL_ALIASES = {
     gunzip: "gzip",
 };
+/**
+ * Interface to the system reference manuals.
+ * @category shell
+ * @params ["<command>"]
+ */
 export const manCommand = {
     name: "man",
     description: "Interface to the system reference manuals",