typescript-virtual-container 1.3.4 → 1.4.0

package/dist/commands/ping.js

@@ -1,4 +1,9 @@
 import { parseArgs } from "./command-helpers";
+/**
+ * Send ICMP ECHO_REQUEST packets (mock implementation).
+ * @category network
+ * @params ["[-c <count>] <host>"]
+ */
 export const pingCommand = {
     name: "ping",
     description: "Send ICMP ECHO_REQUEST (mock)",

package/dist/commands/printf.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Format and print data to stdout.
+ * @category shell
+ * @params ["<format> [args...]"]
+ */
 export declare const printfCommand: ShellModule;
 //# sourceMappingURL=printf.d.ts.map

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

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

package/dist/commands/printf.js

@@ -48,38 +48,64 @@ function renderPrintf(fmt, args) {
             }
         }
         if (fmt[i] === "%" && i + 1 < fmt.length) {
-            // Optional width/precision: %[-][width][.prec]spec
             let j = i + 1;
-            if (fmt[j] === "-")
+            let leftAlign = false;
+            if (fmt[j] === "-") {
+                leftAlign = true;
                 j++;
-            while (j < fmt.length && /\d/.test(fmt[j]))
+            }
+            let zeroPad = false;
+            if (fmt[j] === "0") {
+                zeroPad = true;
+                j++;
+            }
+            let width = 0;
+            while (j < fmt.length && /\d/.test(fmt[j])) {
+                width = width * 10 + parseInt(fmt[j], 10);
                 j++;
+            }
+            let precision = -1;
             if (fmt[j] === ".") {
                 j++;
-                while (j < fmt.length && /\d/.test(fmt[j]))
+                precision = 0;
+                while (j < fmt.length && /\d/.test(fmt[j])) {
+                    precision = precision * 10 + parseInt(fmt[j], 10);
                     j++;
+                }
             }
             const spec = fmt[j];
             const arg = args[argIdx++] ?? "";
+            const pad = (s, ch = " ") => {
+                if (width <= 0 || s.length >= width)
+                    return s;
+                const fill = ch.repeat(width - s.length);
+                return leftAlign ? s + fill : fill + s;
+            };
             switch (spec) {
-                case "s":
-                    out += arg;
+                case "s": {
+                    let val = String(arg);
+                    if (precision >= 0)
+                        val = val.slice(0, precision);
+                    out += pad(val);
                     break;
+                }
                 case "d":
                 case "i":
-                    out += String(parseInt(arg, 10) || 0);
+                    out += pad(String(parseInt(arg, 10) || 0), zeroPad ? "0" : " ");
                     break;
-                case "f":
-                    out += String(parseFloat(arg) || 0);
+                case "f": {
+                    const prec = precision >= 0 ? precision : 6;
+                    out += pad((parseFloat(arg) || 0).toFixed(prec));
                     break;
+                }
                 case "o":
-                    out += (parseInt(arg, 10) || 0).toString(8);
+                    out += pad((parseInt(arg, 10) || 0).toString(8), zeroPad ? "0" : " ");
                     break;
                 case "x":
-                    out += (parseInt(arg, 10) || 0).toString(16);
+                    out += pad((parseInt(arg, 10) || 0).toString(16), zeroPad ? "0" : " ");
                     break;
                 case "X":
-                    out += (parseInt(arg, 10) || 0).toString(16).toUpperCase();
+                    out += pad((parseInt(arg, 10) || 0).toString(16).toUpperCase(), zeroPad ? "0" : " ");
                     break;
                 case "%":
                     out += "%";
@@ -98,6 +124,11 @@ function renderPrintf(fmt, args) {
     }
     return out;
 }
+/**
+ * Format and print data to stdout.
+ * @category shell
+ * @params ["<format> [args...]"]
+ */
 export const printfCommand = {
     name: "printf",
     description: "Format and print data",

package/dist/commands/ps.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Report process status with various formatting options.
+ * @category system
+ * @params ["[-a] [-u] [-x] [aux]"]
+ */
 export declare const psCommand: ShellModule;
 //# sourceMappingURL=ps.d.ts.map

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

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

package/dist/commands/ps.js

@@ -1,4 +1,9 @@
 import { ifFlag } from "./command-helpers";
+/**
+ * Report process status with various formatting options.
+ * @category system
+ * @params ["[-a] [-u] [-x] [aux]"]
+ */
 export const psCommand = {
     name: "ps",
     description: "Report process status",

package/dist/commands/read.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Read a line from stdin into one or more variables.
+ * @category shell
+ * @params ["[-r] [-p prompt] <var...>"]
+ */
 export declare const readCommand: ShellModule;
 //# sourceMappingURL=read.d.ts.map

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

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

package/dist/commands/read.js

@@ -1,4 +1,9 @@
 import { ifFlag } from "./command-helpers";
+/**
+ * Read a line from stdin into one or more variables.
+ * @category shell
+ * @params ["[-r] [-p prompt] <var...>"]
+ */
 export const readCommand = {
     name: "read",
     description: "Read a line from stdin into variables",

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/commands/registry.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgNpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAYzD;AAED,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAClE,WAAW,CAEb;AAED,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAG1C;AAED,wBAAgB,uBAAuB,IAAI,WAAW,EAAE,CAEvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGnE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/commands/registry.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmNpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAYzD;AAED,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAClE,WAAW,CAEb;AAED,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAG1C;AAED,wBAAgB,uBAAuB,IAAI,WAAW,EAAE,CAEvD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGnE"}

package/dist/commands/registry.js

@@ -33,7 +33,8 @@ import { hostnameCommand } from "./hostname";
 import { htopCommand } from "./htop";
 import { idCommand } from "./id";
 import { killCommand } from "./kill";
-import { lnCommand } from "./ln";
+import { lnCommand, readlinkCommand } from "./ln";
+import { statCommand } from "./stat";
 import { lsCommand } from "./ls";
 import { lsbReleaseCommand } from "./lsb-release";
 import { manCommand } from "./man";
@@ -93,7 +94,9 @@ const BASE_COMMANDS = [
     cpCommand,
     mvCommand,
     lnCommand,
+    readlinkCommand,
     chmodCommand,
+    statCommand,
     findCommand,
     // Text processing
     grepCommand,

package/dist/commands/rm.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Remove files or directories from the filesystem.
+ * @category files
+ * @params ["[-r|-rf] <path>"]
+ */
 export declare const rmCommand: ShellModule;
 //# sourceMappingURL=rm.d.ts.map

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

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

package/dist/commands/rm.js

@@ -1,5 +1,10 @@
 import { getArg, ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Remove files or directories from the filesystem.
+ * @category files
+ * @params ["[-r|-rf] <path>"]
+ */
 export const rmCommand = {
     name: "rm",
     description: "Remove files or directories",

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

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EACR,WAAW,EACX,aAAa,EACb,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAiE3B,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAc3E;AAyCD,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,EAAE,QAAQ,GACX,OAAO,CAAC,aAAa,CAAC,CA4ExB;AAED,wBAAsB,UAAU,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,aAAa,CAAC,CA+HxB"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EACR,WAAW,EACX,aAAa,EACb,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAK3B,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAc3E;AAyCD,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,EAAE,QAAQ,GACX,OAAO,CAAC,aAAa,CAAC,CA4ExB;AAED,wBAAsB,UAAU,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,aAAa,CAAC,CA+HxB"}

package/dist/commands/runtime.js

@@ -2,64 +2,8 @@
 import { executeStatements } from "../SSHMimic/executor";
 import { parseScript } from "../VirtualShell/shellParser";
 import { expandAsync } from "../utils/expand";
+import { tokenizeCommand } from "../utils/tokenize";
 import { resolveModule } from "./registry";
-// ── Tokenize command input respecting quotes ──────────────────────────────────
-function tokenizeCommand(input) {
-    const tokens = [];
-    let current = "";
-    let inQ = false;
-    let qChar = "";
-    let i = 0;
-    while (i < input.length) {
-        const ch = input[i];
-        const next = input[i + 1];
-        if ((ch === '"' || ch === "'") && !inQ) {
-            inQ = true;
-            qChar = ch;
-            i++;
-            continue;
-        }
-        if (inQ && ch === qChar) {
-            inQ = false;
-            qChar = "";
-            i++;
-            continue;
-        }
-        if (inQ) {
-            current += ch;
-            i++;
-            continue;
-        }
-        if (ch === " ") {
-            if (current) {
-                tokens.push(current);
-                current = "";
-            }
-            i++;
-            continue;
-        }
-        if ((ch === ">" || ch === "<") && !inQ) {
-            if (current) {
-                tokens.push(current);
-                current = "";
-            }
-            if (ch === ">" && next === ">") {
-                tokens.push(">>");
-                i += 2;
-            }
-            else {
-                tokens.push(ch);
-                i++;
-            }
-            continue;
-        }
-        current += ch;
-        i++;
-    }
-    if (current)
-        tokens.push(current);
-    return tokens;
-}
 export function makeDefaultEnv(authUser, hostname) {
     return {
         vars: {

package/dist/commands/sed.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Stream editor for filtering and transforming text lines.
+ * @category text
+ * @params ["-e <expr> [file]", "s/pattern/replace/[g]"]
+ */
 export declare const sedCommand: ShellModule;
 //# sourceMappingURL=sed.d.ts.map

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

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

package/dist/commands/sed.js

@@ -1,5 +1,10 @@
 import { getFlag, ifFlag } from "./command-helpers";
 import { resolvePath } from "./helpers";
+/**
+ * Stream editor for filtering and transforming text lines.
+ * @category text
+ * @params ["-e <expr> [file]", "s/pattern/replace/[g]"]
+ */
 export const sedCommand = {
     name: "sed",
     description: "Stream editor for filtering and transforming text",

package/dist/commands/set.d.ts

@@ -1,10 +1,9 @@
 /** biome-ignore-all lint/style/useNamingConvention: env variables */
 import type { ShellModule } from "../types/commands";
-/** @deprecated use env.vars from CommandContext */
-export declare function getEnvVar(name: string): string | undefined;
-/** @deprecated use env.vars from CommandContext */
-export declare function setEnvVar(name: string, value: string): void;
-/** @deprecated use env.vars from CommandContext */
-export declare function getAllEnvVars(authUser: string): Record<string, string>;
+/**
+ * Display or set shell variables and options.
+ * @category shell
+ * @params ["[VAR=value]"]
+ */
 export declare const setCommand: ShellModule;
 //# sourceMappingURL=set.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/commands/set.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAWrD,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1D;AACD,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE3D;AACD,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAItE;AAED,eAAO,MAAM,UAAU,EAAE,WAoBxB,CAAC"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/commands/set.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAoBxB,CAAC"}

package/dist/commands/set.js

@@ -1,25 +1,8 @@
-// Legacy global store kept for compatibility with older callers
-const _globalEnv = {
-    PATH: "/usr/local/bin:/usr/bin:/bin",
-    HOME: "/home/user",
-    SHELL: "/bin/sh",
-    TERM: "xterm-256color",
-    USER: "user",
-};
-/** @deprecated use env.vars from CommandContext */
-export function getEnvVar(name) {
-    return _globalEnv[name];
-}
-/** @deprecated use env.vars from CommandContext */
-export function setEnvVar(name, value) {
-    _globalEnv[name] = value;
-}
-/** @deprecated use env.vars from CommandContext */
-export function getAllEnvVars(authUser) {
-    _globalEnv.USER = authUser;
-    _globalEnv.HOME = `/home/${authUser}`;
-    return { ..._globalEnv };
-}
+/**
+ * Display or set shell variables and options.
+ * @category shell
+ * @params ["[VAR=value]"]
+ */
 export const setCommand = {
     name: "set",
     description: "Display or set shell variables",

package/dist/commands/sh.d.ts

@@ -1,3 +1,9 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Execute shell scripts or commands with a minimal shell interpreter.
+ * Supports if/elif/else, for loops, while loops, and variable expansion.
+ * @category shell
+ * @params ["-c <script>", "[<file>]"]
+ */
 export declare const shCommand: ShellModule;
 //# sourceMappingURL=sh.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sh.d.ts","sourceRoot":"","sources":["../../src/commands/sh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGR,WAAW,EACd,MAAM,mBAAmB,CAAC;AA4R3B,eAAO,MAAM,SAAS,EAAE,WA4CvB,CAAC"}
+{"version":3,"file":"sh.d.ts","sourceRoot":"","sources":["../../src/commands/sh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGX,WAAW,EACX,MAAM,mBAAmB,CAAC;AA4R3B;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,WA4CvB,CAAC"}

package/dist/commands/sh.js

@@ -233,6 +233,12 @@ async function runBlocks(blocks, ctx) {
     }
     return { ...lastResult, stdout: output.trim() || lastResult.stdout };
 }
+/**
+ * Execute shell scripts or commands with a minimal shell interpreter.
+ * Supports if/elif/else, for loops, while loops, and variable expansion.
+ * @category shell
+ * @params ["-c <script>", "[<file>]"]
+ */
 export const shCommand = {
     name: "sh",
     aliases: ["bash"],

package/dist/commands/shift.d.ts

@@ -1,5 +1,15 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Shift positional parameters (remove first N arguments).
+ * @category shell
+ * @params ["[n]"]
+ */
 export declare const shiftCommand: ShellModule;
+/**
+ * Trap signals and execute actions on signal receipt or shell exit.
+ * @category shell
+ * @params ["[action] [signal...]"]
+ */
 export declare const trapCommand: ShellModule;
 export declare const returnCommand: ShellModule;
 //# sourceMappingURL=shift.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shift.d.ts","sourceRoot":"","sources":["../../src/commands/shift.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,eAAO,MAAM,YAAY,EAAE,WAoB1B,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAezB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAW3B,CAAC"}
+{"version":3,"file":"shift.d.ts","sourceRoot":"","sources":["../../src/commands/shift.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,WAoB1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,WAezB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAW3B,CAAC"}

package/dist/commands/shift.js

@@ -1,3 +1,8 @@
+/**
+ * Shift positional parameters (remove first N arguments).
+ * @category shell
+ * @params ["[n]"]
+ */
 export const shiftCommand = {
     name: "shift",
     description: "Shift positional parameters",
@@ -20,6 +25,11 @@ export const shiftCommand = {
         return { exitCode: 0 };
     },
 };
+/**
+ * Trap signals and execute actions on signal receipt or shell exit.
+ * @category shell
+ * @params ["[action] [signal...]"]
+ */
 export const trapCommand = {
     name: "trap",
     description: "Trap signals and events",

package/dist/commands/sleep.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Delay execution for a specified number of seconds.
+ * @category system
+ * @params ["<seconds>"]
+ */
 export declare const sleepCommand: ShellModule;
 //# sourceMappingURL=sleep.d.ts.map

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

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

package/dist/commands/sleep.js

@@ -1,3 +1,8 @@
+/**
+ * Delay execution for a specified number of seconds.
+ * @category system
+ * @params ["<seconds>"]
+ */
 export const sleepCommand = {
     name: "sleep",
     description: "Delay execution",

package/dist/commands/sort.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Sort lines of text with various options (reverse, numeric, unique).
+ * @category text
+ * @params ["[-r] [-n] [-u] [-k <col>] [file...]"]
+ */
 export declare const sortCommand: ShellModule;
 //# sourceMappingURL=sort.d.ts.map

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

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

package/dist/commands/sort.js

@@ -1,5 +1,10 @@
 import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Sort lines of text with various options (reverse, numeric, unique).
+ * @category text
+ * @params ["[-r] [-n] [-u] [-k <col>] [file...]"]
+ */
 export const sortCommand = {
     name: "sort",
     description: "Sort lines of text",

package/dist/commands/source.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Execute commands from a file in the current shell environment.
+ * @category shell
+ * @params ["<file> [args...]"]
+ */
 export declare const sourceCommand: ShellModule;
 //# sourceMappingURL=source.d.ts.map

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

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

package/dist/commands/source.js

@@ -1,5 +1,10 @@
 import { resolvePath } from "./helpers";
 import { runCommand } from "./runtime";
+/**
+ * Execute commands from a file in the current shell environment.
+ * @category shell
+ * @params ["<file> [args...]"]
+ */
 export const sourceCommand = {
     name: "source",
     aliases: ["."],

package/dist/commands/stat.d.ts

@@ -0,0 +1,7 @@
+import type { ShellModule } from "../types/commands";
+/**
+ * Display file or filesystem status.
+ * Outputs: path, size, mode, type, timestamps — similar to `stat` on Linux.
+ */
+export declare const statCommand: ShellModule;
+//# sourceMappingURL=stat.d.ts.map

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

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

package/dist/commands/stat.js

@@ -0,0 +1,56 @@
+import { resolvePath } from "./helpers";
+/**
+ * Display file or filesystem status.
+ * Outputs: path, size, mode, type, timestamps — similar to `stat` on Linux.
+ */
+export const statCommand = {
+    name: "stat",
+    description: "Display file status",
+    category: "files",
+    params: ["[-c <format>] <file>"],
+    run: ({ shell, cwd, args }) => {
+        const fmtIdx = args.findIndex((a) => a === "-c" || a === "--format");
+        const fmt = fmtIdx !== -1 ? args[fmtIdx + 1] : undefined;
+        const file = args.find((a) => !a.startsWith("-") && a !== fmt);
+        if (!file)
+            return { stderr: "stat: missing operand\n", exitCode: 1 };
+        const p = resolvePath(cwd, file);
+        if (!shell.vfs.exists(p)) {
+            return { stderr: `stat: cannot stat '${file}': No such file or directory\n`, exitCode: 1 };
+        }
+        const st = shell.vfs.stat(p);
+        const isDir = st.type === "directory";
+        const _isLink = shell.vfs.isSymlink(p);
+        const isSymlink = shell.vfs.isSymlink(p);
+        const modePerm = (mode) => {
+            const bits = [0o400, 0o200, 0o100, 0o040, 0o020, 0o010, 0o004, 0o002, 0o001];
+            const syms = ["r", "w", "x", "r", "w", "x", "r", "w", "x"];
+            return (isDir ? "d" : isSymlink ? "l" : "-") +
+                bits.map((b, i) => mode & b ? syms[i] : "-").join("");
+        };
+        const octal = (st.mode).toString(8).padStart(4, "0");
+        const modeStr = modePerm(st.mode);
+        const size = "size" in st ? st.size : 0;
+        const ts = (d) => d.toISOString().replace("T", " ").replace(/\.\d+Z$/, " +0000");
+        // -c format string support
+        if (fmt) {
+            const out = fmt
+                .replace("%n", file)
+                .replace("%s", String(size))
+                .replace("%a", octal.slice(1)) // access in octal (no leading 0)
+                .replace("%A", modeStr)
+                .replace("%F", isSymlink ? "symbolic link" : isDir ? "directory" : "regular file")
+                .replace("%y", ts(st.updatedAt))
+                .replace("%z", ts(st.updatedAt));
+            return { stdout: `${out}\n`, exitCode: 0 };
+        }
+        const out = [
+            `  File: ${file}${isSymlink ? ` -> ${shell.vfs.resolveSymlink(p)}` : ""}`,
+            `  Size: ${size}${"\t".repeat(3)}${isSymlink ? "symbolic link" : isDir ? "directory" : "regular file"}`,
+            `Access: (${octal}/${modeStr})  Uid: (    0/    root)   Gid: (    0/    root)`,
+            `Modify: ${ts(st.updatedAt)}`,
+            `Change: ${ts(st.updatedAt)}`,
+        ].join("\n");
+        return { stdout: `${out}\n`, exitCode: 0 };
+    },
+};

package/dist/commands/su.d.ts

@@ -1,3 +1,16 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Switch to another user account.
+ *
+ * Usage:
+ *   su [username]        — switch to username (defaults to root)
+ *   su - [username]      — login shell (changes cwd to target home)
+ *   su -c 'cmd' [user]   — run command as user
+ *
+ * - Root can switch to any user without a password.
+ * - Non-root sudoers must enter the target user's password.
+ * - Non-sudoers are denied.
+ * - Switching to a non-existent user returns an error immediately.
+ */
 export declare const suCommand: ShellModule;
 //# sourceMappingURL=su.d.ts.map

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

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