typescript-virtual-container 1.5.11 → 1.6.0

package/dist/VirtualUserManager/index.js

@@ -29,6 +29,8 @@ export class VirtualUserManager extends EventEmitter {
     activeProcesses = new Map();
     nextTty = 0;
     nextPid = 1000;
+    nextUid = 1001;
+    nextGid = 1001;
     /**
      * Creates a user manager instance backed by a virtual filesystem.
      *
@@ -59,14 +61,6 @@ export class VirtualUserManager extends EventEmitter {
             changed = true;
         }
         this.sudoers.add("root");
-        // Auto-create current system user for easier authentication
-        // const currentUser = process.env.USER || process.env.USERNAME;
-        // if (currentUser && currentUser !== "root" && !this.users.has(currentUser)) {
-        // 	const userPassword = this.defaultRootPassword;
-        // 	this.users.set(currentUser, this.createRecord(currentUser, userPassword));
-        // 	this.sudoers.add(currentUser);
-        // 	changed = true;
-        // }
         const homePath = "/root";
         if (!this.vfs.exists(homePath)) {
             this.vfs.mkdir(homePath, 0o755);
@@ -403,11 +397,19 @@ export class VirtualUserManager extends EventEmitter {
     listUsers() {
         return Array.from(this.users.keys()).sort();
     }
+    /** Returns the numeric UID for a username, or 0 if unknown. */
+    getUid(username) {
+        return this.users.get(username)?.uid ?? 0;
+    }
+    /** Returns the primary GID for a username, or 0 if unknown. */
+    getGid(username) {
+        return this.users.get(username)?.gid ?? 0;
+    }
     /**
      * Registers a running command as a virtual process.
      * Returns the assigned PID so the caller can deregister on completion.
      */
-    registerProcess(username, command, argv, tty) {
+    registerProcess(username, command, argv, tty, abortController) {
         const pid = this.nextPid++;
         this.activeProcesses.set(pid, {
             pid,
@@ -416,6 +418,8 @@ export class VirtualUserManager extends EventEmitter {
             argv,
             tty,
             startedAt: new Date().toISOString(),
+            status: "running",
+            abortController,
         });
         return pid;
     }
@@ -423,10 +427,27 @@ export class VirtualUserManager extends EventEmitter {
     unregisterProcess(pid) {
         this.activeProcesses.delete(pid);
     }
+    /** Marks a process as done (keeps it in the table briefly for jobs/ps). */
+    markProcessDone(pid) {
+        const proc = this.activeProcesses.get(pid);
+        if (proc)
+            proc.status = "done";
+    }
     /** Returns all currently running processes sorted by PID. */
     listProcesses() {
         return Array.from(this.activeProcesses.values()).sort((a, b) => a.pid - b.pid);
     }
+    /** Terminate a process by PID. Returns true if the process was found and signalled. */
+    killProcess(pid) {
+        const proc = this.activeProcesses.get(pid);
+        if (!proc)
+            return false;
+        if (proc.abortController) {
+            proc.abortController.abort();
+        }
+        proc.status = "stopped";
+        return true;
+    }
     loadFromVfs() {
         this.users.clear();
         if (!this.vfs.exists(this.usersPath)) {
@@ -442,11 +463,23 @@ export class VirtualUserManager extends EventEmitter {
             if (parts.length < 3) {
                 continue;
             }
-            const [username, salt, passwordHash] = parts;
-            if (!username || !salt || !passwordHash) {
-                continue;
+            // Format: username:uid:gid:salt:passwordHash (new) or username:salt:passwordHash (legacy)
+            if (parts.length >= 5) {
+                const [username, uidStr, gidStr, salt, passwordHash] = parts;
+                if (!username || !salt || !passwordHash)
+                    continue;
+                const uid = parseInt(uidStr ?? "1001", 10);
+                const gid = parseInt(gidStr ?? "1001", 10);
+                this.users.set(username, { username, uid, gid, salt, passwordHash });
+            }
+            else {
+                const [username, salt, passwordHash] = parts;
+                if (!username || !salt || !passwordHash)
+                    continue;
+                const uid = username === "root" ? 0 : this.nextUid++;
+                const gid = username === "root" ? 0 : this.nextGid++;
+                this.users.set(username, { username, uid, gid, salt, passwordHash });
             }
-            this.users.set(username, { username, salt, passwordHash });
         }
     }
     loadSudoersFromVfs() {
@@ -487,7 +520,7 @@ export class VirtualUserManager extends EventEmitter {
         }
         const authContent = Array.from(this.users.values())
             .sort((left, right) => left.username.localeCompare(right.username))
-            .map((record) => [record.username, record.salt, record.passwordHash].join(":"))
+            .map((record) => [record.username, record.uid, record.gid, record.salt, record.passwordHash].join(":"))
             .join("\n");
         const sudoersContent = Array.from(this.sudoers.values()).sort().join("\n");
         const quotasContent = Array.from(this.quotas.entries())
@@ -516,7 +549,9 @@ export class VirtualUserManager extends EventEmitter {
         this.vfs.writeFile(targetPath, content, { mode });
         return true;
     }
-    createRecord(username, password) {
+    createRecord(username, password, uid, gid) {
+        const assignedUid = uid ?? (username === "root" ? 0 : this.nextUid++);
+        const assignedGid = gid ?? (username === "root" ? 0 : this.nextGid++);
         // Cache key is a hash of the inputs — never store plaintext password in memory
         const cacheKey = createHash("sha256").update(username).update(":").update(password).digest("hex");
         const cached = VirtualUserManager.recordCache.get(cacheKey);
@@ -526,6 +561,8 @@ export class VirtualUserManager extends EventEmitter {
         const salt = randomBytes(16).toString("hex");
         const record = {
             username,
+            uid: assignedUid,
+            gid: assignedGid,
             salt,
             // Hash uses the generated salt — verifyPassword must use record.salt
             passwordHash: this.hashPassword(password, salt),

package/dist/commands/bc.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Arbitrary precision calculator language.
+ * @category system
+ * @params ["[expression]"]
+ */
 export declare const bcCommand: ShellModule;

package/dist/commands/bc.js

@@ -1,4 +1,9 @@
 import { evalArith } from "../utils/expand";
+/**
+ * Arbitrary precision calculator language.
+ * @category system
+ * @params ["[expression]"]
+ */
 export const bcCommand = {
     name: "bc",
     description: "Arbitrary precision calculator language",

package/dist/commands/cat.js

@@ -1,5 +1,5 @@
 import { ifFlag } from "./command-helpers";
-import { assertPathAccess, resolveReadablePath } from "./helpers";
+import { checkFilePermission, resolveReadablePath } from "./helpers";
 /**
  * Concatenate and print files to stdout.
  * @category files
@@ -23,7 +23,7 @@ export const catCommand = {
         const parts = [];
         for (const fileArg of fileArgs) {
             const target = resolveReadablePath(shell.vfs, cwd, fileArg);
-            assertPathAccess(authUser, target, "cat");
+            checkFilePermission(shell.vfs, shell.users, authUser, target, 4);
             parts.push(shell.vfs.readFile(target));
         }
         const combined = parts.join("");

package/dist/commands/chgrp.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Change group ownership.
+ * @category files
+ * @params ["<group> <file>"]
+ */
+export declare const chgrpCommand: ShellModule;

package/dist/commands/chgrp.js

@@ -0,0 +1,42 @@
+import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Change group ownership.
+ * @category files
+ * @params ["<group> <file>"]
+ */
+export const chgrpCommand = {
+    name: "chgrp",
+    description: "Change group ownership",
+    category: "files",
+    params: ["<group> <file>"],
+    run: ({ authUser, shell, cwd, args }) => {
+        const [groupArg, fileArg] = args;
+        if (!groupArg || !fileArg) {
+            return { stderr: "chgrp: missing operand", exitCode: 1 };
+        }
+        if (authUser !== "root") {
+            return { stderr: "chgrp: changing group: Operation not permitted", exitCode: 1 };
+        }
+        const filePath = resolvePath(cwd, fileArg);
+        try {
+            assertPathAccess(authUser, filePath, "chgrp");
+            if (!shell.vfs.exists(filePath)) {
+                return {
+                    stderr: `chgrp: ${fileArg}: No such file or directory`,
+                    exitCode: 1,
+                };
+            }
+            const gid = parseInt(groupArg, 10);
+            if (Number.isNaN(gid)) {
+                return { stderr: `chgrp: invalid group: ${groupArg}`, exitCode: 1 };
+            }
+            const current = shell.vfs.getOwner(filePath);
+            shell.vfs.chown(filePath, current.uid, gid);
+            return { exitCode: 0 };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { stderr: `chgrp: ${msg}`, exitCode: 1 };
+        }
+    },
+};

package/dist/commands/chown.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Change file owner and group.
+ * @category files
+ * @params ["<owner>[:<group>] <file>"]
+ */
+export declare const chownCommand: ShellModule;

package/dist/commands/chown.js

@@ -0,0 +1,79 @@
+import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Change file owner and group.
+ * @category files
+ * @params ["<owner>[:<group>] <file>"]
+ */
+export const chownCommand = {
+    name: "chown",
+    description: "Change file owner and group",
+    category: "files",
+    params: ["<owner>[:<group>] <file>"],
+    run: ({ authUser, shell, cwd, args }) => {
+        const [ownerArg, fileArg] = args;
+        if (!ownerArg || !fileArg) {
+            return { stderr: "chown: missing operand", exitCode: 1 };
+        }
+        if (authUser !== "root") {
+            return { stderr: "chown: changing ownership: Operation not permitted", exitCode: 1 };
+        }
+        const filePath = resolvePath(cwd, fileArg);
+        try {
+            assertPathAccess(authUser, filePath, "chown");
+            if (!shell.vfs.exists(filePath)) {
+                return {
+                    stderr: `chown: ${fileArg}: No such file or directory`,
+                    exitCode: 1,
+                };
+            }
+            let uid = null;
+            let gid = null;
+            const colonIdx = ownerArg.indexOf(":");
+            if (colonIdx === -1) {
+                // Just a user name
+                uid = resolveUser(shell, ownerArg);
+                if (uid === null) {
+                    return { stderr: `chown: invalid user: ${ownerArg}`, exitCode: 1 };
+                }
+            }
+            else {
+                const userPart = ownerArg.slice(0, colonIdx);
+                const groupPart = ownerArg.slice(colonIdx + 1);
+                if (userPart) {
+                    uid = resolveUser(shell, userPart);
+                    if (uid === null) {
+                        return { stderr: `chown: invalid user: ${userPart}`, exitCode: 1 };
+                    }
+                }
+                if (groupPart) {
+                    gid = resolveGroup(shell, groupPart);
+                    if (gid === null) {
+                        return { stderr: `chown: invalid group: ${groupPart}`, exitCode: 1 };
+                    }
+                }
+            }
+            const current = shell.vfs.getOwner(filePath);
+            shell.vfs.chown(filePath, uid ?? current.uid, gid ?? current.gid);
+            return { exitCode: 0 };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { stderr: `chown: ${msg}`, exitCode: 1 };
+        }
+    },
+};
+function resolveUser(shell, name) {
+    const users = shell.users.listUsers();
+    if (users.includes(name))
+        return shell.users.getUid(name);
+    const num = parseInt(name, 10);
+    if (!Number.isNaN(num))
+        return num;
+    return null;
+}
+function resolveGroup(_shell, name) {
+    const num = parseInt(name, 10);
+    if (!Number.isNaN(num))
+        return num;
+    return 0; // fallback: root group
+}

package/dist/commands/cp.js

@@ -1,5 +1,6 @@
+import * as path from "node:path";
 import { ifFlag } from "./command-helpers";
-import { assertPathAccess, resolvePath } from "./helpers";
+import { checkFilePermission, resolvePath } from "./helpers";
 /**
  * Copy files or directories inside the virtual filesystem.
  * @category files
@@ -20,8 +21,8 @@ export const cpCommand = {
         const srcPath = resolvePath(cwd, srcArg);
         const destPath = resolvePath(cwd, destArg);
         try {
-            assertPathAccess(authUser, srcPath, "cp");
-            assertPathAccess(authUser, destPath, "cp");
+            checkFilePermission(shell.vfs, shell.users, authUser, srcPath, 4);
+            checkFilePermission(shell.vfs, shell.users, authUser, path.posix.dirname(destPath), 2);
             if (!shell.vfs.exists(srcPath)) {
                 return {
                     stderr: `cp: ${srcArg}: No such file or directory`,

package/dist/commands/dd.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Convert and copy a file
+ * @category files
+ * @params ["if=<file> of=<file> [bs=1024] [count=N]"]
+ */
+export declare const ddCommand: ShellModule;

package/dist/commands/dd.js

@@ -0,0 +1,60 @@
+import { resolvePath } from "./helpers";
+/**
+ * Convert and copy a file
+ * @category files
+ * @params ["if=<file> of=<file> [bs=1024] [count=N]"]
+ */
+export const ddCommand = {
+    name: "dd",
+    description: "Convert and copy a file",
+    category: "files",
+    params: ["if=<file> of=<file> [bs=1024] [count=N]"],
+    run: ({ authUser, shell, cwd, args }) => {
+        const kv = {};
+        for (const arg of args) {
+            const eqIdx = arg.indexOf("=");
+            if (eqIdx !== -1) {
+                kv[arg.slice(0, eqIdx)] = arg.slice(eqIdx + 1);
+            }
+        }
+        const ifPath = kv.if ? resolvePath(cwd, kv.if) : undefined;
+        const ofPath = kv.of ? resolvePath(cwd, kv.of) : undefined;
+        if (!ifPath || !ofPath) {
+            return { stderr: "dd: missing 'if' or 'of' operand\n", exitCode: 1 };
+        }
+        if (!shell.vfs.exists(ifPath)) {
+            return { stderr: `dd: ${kv.if}: No such file or directory\n`, exitCode: 1 };
+        }
+        const bs = parseInt(kv.bs || "512", 10);
+        const content = shell.vfs.readFile(ifPath);
+        const skipBlocks = parseInt(kv.skip || "0", 10);
+        const seekBlocks = parseInt(kv.seek || "0", 10);
+        const countBlocks = kv.count !== undefined ? parseInt(kv.count, 10) : undefined;
+        const startByte = skipBlocks * bs;
+        const available = content.slice(startByte);
+        const totalBytes = countBlocks !== undefined
+            ? Math.min(available.length, countBlocks * bs)
+            : available.length;
+        const data = available.slice(0, totalBytes);
+        let output;
+        try {
+            output = shell.vfs.readFile(ofPath);
+        }
+        catch {
+            output = "";
+        }
+        const seekByte = seekBlocks * bs;
+        if (seekByte > 0) {
+            if (output.length < seekByte) {
+                output = output.padEnd(seekByte, "\0");
+            }
+            output = output.slice(0, seekByte) + data + output.slice(seekByte + data.length);
+        }
+        else {
+            output = data;
+        }
+        shell.writeFileAsUser(authUser, ofPath, output);
+        const recordsIn = Math.ceil(data.length / bs);
+        return { stdout: `${recordsIn}+0 records in\n${recordsIn}+0 records out\n`, exitCode: 0 };
+    },
+};

package/dist/commands/declare.js

@@ -14,8 +14,6 @@ export const declareCommand = {
         if (!env)
             return { exitCode: 0 };
         const integer = ifFlag(args, ["-i"]);
-        const _readonly = ifFlag(args, ["-r"]);
-        const _export_ = ifFlag(args, ["-x"]);
         const printAll = args.filter((a) => !a.startsWith("-")).length === 0;
         if (printAll) {
             const lines = Object.entries(env.vars).map(([k, v]) => `declare -- ${k}="${v}"`);

package/dist/commands/expr.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Evaluate expressions
+ * @category shell
+ * @params ["<expression>"]
+ */
+export declare const exprCommand: ShellModule;

package/dist/commands/expr.js

@@ -0,0 +1,63 @@
+/**
+ * Evaluate expressions
+ * @category shell
+ * @params ["<expression>"]
+ */
+export const exprCommand = {
+    name: "expr",
+    description: "Evaluate expressions",
+    category: "shell",
+    params: ["<expression>"],
+    run: ({ args }) => {
+        const colonIdx = args.indexOf(":");
+        if (colonIdx > 0 && colonIdx <= args.length - 2) {
+            const str = args[colonIdx - 1];
+            const pattern = args[colonIdx + 1];
+            try {
+                const re = new RegExp(pattern);
+                const match = str.match(re);
+                if (match && match.index !== undefined) {
+                    return { stdout: `${match[0].length}\n`, exitCode: 0 };
+                }
+                return { stdout: "0\n", exitCode: 1 };
+            }
+            catch {
+                return { stderr: "expr: invalid regex\n", exitCode: 2 };
+            }
+        }
+        if (args.length >= 3) {
+            const left = parseInt(args[0], 10);
+            const op = args[1];
+            const right = parseInt(args[2], 10);
+            if (isNaN(left) || isNaN(right)) {
+                return { stderr: "expr: non-integer argument\n", exitCode: 1 };
+            }
+            let result;
+            switch (op) {
+                case "+":
+                    result = left + right;
+                    break;
+                case "-":
+                    result = left - right;
+                    break;
+                case "*":
+                    result = left * right;
+                    break;
+                case "/":
+                    if (right === 0)
+                        return { stderr: "expr: division by zero\n", exitCode: 2 };
+                    result = Math.trunc(left / right);
+                    break;
+                case "%":
+                    if (right === 0)
+                        return { stderr: "expr: division by zero\n", exitCode: 2 };
+                    result = left % right;
+                    break;
+                default:
+                    return { stderr: "expr: syntax error\n", exitCode: 2 };
+            }
+            return { stdout: `${result}\n`, exitCode: 0 };
+        }
+        return { stderr: "expr: syntax error\n", exitCode: 2 };
+    },
+};

package/dist/commands/fun.d.ts

@@ -17,6 +17,11 @@ export declare const fortuneCommand: ShellModule;
  * @params ["[message]"]
  */
 export declare const cowsayCommand: ShellModule;
+/**
+ * Generate ASCII cow thinking.
+ * @category misc
+ * @params ["[message]"]
+ */
 export declare const cowthinkCommand: ShellModule;
 /**
  * Show falling characters in the terminal like the Matrix movie.

package/dist/commands/fun.js

@@ -57,7 +57,6 @@ export const fortuneCommand = {
 function cowsay(message, dead = false) {
     const lines = message.split("\n");
     const maxLen = Math.max(...lines.map(l => l.length));
-    const _border = "-".repeat(maxLen + 2);
     const body = lines.length === 1
         ? `< ${lines[0]} >`
         : lines.map((l, i) => {
@@ -95,6 +94,11 @@ export const cowsayCommand = {
         return { stdout: cowsay(msg), exitCode: 0 };
     },
 };
+/**
+ * Generate ASCII cow thinking.
+ * @category misc
+ * @params ["[message]"]
+ */
 export const cowthinkCommand = {
     name: "cowthink",
     description: "Generate ASCII cow thinking",

package/dist/commands/help.d.ts

@@ -1,2 +1,7 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * List all commands, or show usage for a specific command.
+ * @category shell
+ * @params ["[command]"]
+ */
 export declare function createHelpCommand(_getNames: () => string[]): ShellModule;

package/dist/commands/help.js

@@ -98,6 +98,11 @@ function renderDetail(mod) {
     return lines.join("\n");
 }
 // ─── export ───────────────────────────────────────────────────────────────────
+/**
+ * List all commands, or show usage for a specific command.
+ * @category shell
+ * @params ["[command]"]
+ */
 export function createHelpCommand(_getNames) {
     return {
         name: "help",

package/dist/commands/helpers.d.ts

@@ -1,8 +1,51 @@
 import type VirtualFileSystem from "../VirtualFileSystem";
 import type { VirtualPackageManager } from "../VirtualPackageManager";
 import type { VirtualShell } from "../VirtualShell";
+/**
+ * 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 declare function resolvePath(cwd: string, inputPath: string, homeDir?: string): string;
 export declare function assertPathAccess(authUser: string, targetPath: string, operation: string): void;
+/**
+ * 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 declare function stripUrlFilename(url: string): string;
+/**
+ * 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 declare function resolveReadablePath(vfs: VirtualFileSystem, cwd: string, inputPath: string): string;
+/**
+ * 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 declare function getPackageManager(shell: VirtualShell): VirtualPackageManager | undefined;
+/**
+ * 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 declare function checkFilePermission(vfs: VirtualFileSystem, users: {
+    getUid: (u: string) => number;
+    getGid: (u: string) => number;
+}, authUser: string, filePath: string, want: number): void;