typescript-virtual-container 1.2.9 → 1.3.0

package/dist/commands/dpkg.d.ts

@@ -1,4 +1,9 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * dpkg compatibility command (query/remove/list) backed by the virtual package manager.
+ * @category package
+ * @params ["[-l] [-s pkg] [-L pkg] [-i pkg] [--remove pkg]"]
+ */
 export declare const dpkgCommand: ShellModule;
 export declare const dpkgQueryCommand: ShellModule;
 //# sourceMappingURL=dpkg.d.ts.map

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

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

package/dist/commands/dpkg.js

@@ -1,9 +1,14 @@
 import { ifFlag, parseArgs } from "./command-helpers";
 import { getPackageManager } from "./helpers";
+/**
+ * dpkg compatibility command (query/remove/list) backed by the virtual package manager.
+ * @category package
+ * @params ["[-l] [-s pkg] [-L pkg] [-i pkg] [--remove pkg]"]
+ */
 export const dpkgCommand = {
     name: "dpkg",
     description: "Debian package manager low-level tool",
-    category: "system",
+    category: "package",
     params: ["[-l] [-s pkg] [-L pkg] [-i pkg] [--remove pkg]"],
     run: ({ args, authUser, shell }) => {
         const pm = getPackageManager(shell);
@@ -15,7 +20,18 @@ export const dpkgCommand = {
         const removeFlag = ifFlag(args, ["-r", "--remove"]);
         const purgeFlag = ifFlag(args, ["-P", "--purge"]);
         const { positionals } = parseArgs(args, {
-            flags: ["-l", "--list", "-s", "--status", "-L", "--listfiles", "-r", "--remove", "-P", "--purge"],
+            flags: [
+                "-l",
+                "--list",
+                "-s",
+                "--status",
+                "-L",
+                "--listfiles",
+                "-r",
+                "--remove",
+                "-P",
+                "--purge",
+            ],
         });
         if (listFlag) {
             const pkgList = pm.listInstalled();
@@ -104,12 +120,15 @@ export const dpkgCommand = {
 export const dpkgQueryCommand = {
     name: "dpkg-query",
     description: "Show information about installed packages",
-    category: "system",
+    category: "package",
     params: ["-W [pkg] | -l [pattern]"],
     run: ({ args, shell }) => {
         const pm = getPackageManager(shell);
         if (!pm)
-            return { stderr: "dpkg-query: package manager not initialised", exitCode: 1 };
+            return {
+                stderr: "dpkg-query: package manager not initialised",
+                exitCode: 1,
+            };
         const listFlag = ifFlag(args, ["-l"]);
         const showFlag = ifFlag(args, ["-W", "--show"]);
         const { positionals } = parseArgs(args, {
@@ -123,9 +142,7 @@ export const dpkgQueryCommand = {
                 : pkgList;
             if (showFlag) {
                 return {
-                    stdout: filtered
-                        .map((p) => `${p.name}\t${p.version}`)
-                        .join("\n"),
+                    stdout: filtered.map((p) => `${p.name}\t${p.version}`).join("\n"),
                     exitCode: 0,
                 };
             }

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

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

package/dist/commands/du.js

@@ -12,9 +12,15 @@ export const duCommand = {
         const p = resolvePath(cwd, target);
         const fmt = (b) => human ? `${(b / 1024).toFixed(1)}K` : String(Math.ceil(b / 1024));
         if (!shell.vfs.exists(p))
-            return { stderr: `du: ${target}: No such file or directory`, exitCode: 1 };
+            return {
+                stderr: `du: ${target}: No such file or directory`,
+                exitCode: 1,
+            };
         if (summary || shell.vfs.stat(p).type === "file") {
-            return { stdout: `${fmt(shell.vfs.getUsageBytes(p))}\t${target}`, exitCode: 0 };
+            return {
+                stdout: `${fmt(shell.vfs.getUsageBytes(p))}\t${target}`,
+                exitCode: 0,
+            };
         }
         const lines = [];
         const walk = (dir, rel) => {

package/dist/commands/echo.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Echo text to stdout with shell-style expansion and escape support.
+ * @category shell
+ * @params ["[-n] [-e] [text...]"]
+ */
 export declare const echoCommand: ShellModule;
 //# sourceMappingURL=echo.d.ts.map

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

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

package/dist/commands/echo.js

@@ -1,4 +1,5 @@
 import { parseArgs } from "./command-helpers";
+import { expandSync } from "../utils/expand";
 /**
  * Expand escape sequences for `echo -e`.
  * Handles \n \t \r \\ \a \b \f \v and \0NNN (octal).
@@ -15,19 +16,27 @@ function expandEscapes(text) {
         .replace(/\\v/g, "\x0B")
         .replace(/\\0(\d{1,3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)));
 }
+/**
+ * Echo text to stdout with shell-style expansion and escape support.
+ * @category shell
+ * @params ["[-n] [-e] [text...]"]
+ */
 export const echoCommand = {
     name: "echo",
     description: "Display text",
     category: "shell",
     params: ["[-n] [-e] [text...]"],
     run: ({ args, stdin, env }) => {
-        const { flags, positionals } = parseArgs(args, { flags: ["-n", "-e", "-E"] });
+        const { flags, positionals } = parseArgs(args, {
+            flags: ["-n", "-e", "-E"],
+        });
         const noNewline = flags.has("-n");
         const escapes = flags.has("-e");
         const rawText = positionals.length > 0 ? positionals.join(" ") : (stdin ?? "");
-        // Expand $VAR references using the session env (not the legacy global store)
-        const varsExpanded = rawText.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) => env?.vars[name] ?? "");
-        const text = escapes ? expandEscapes(varsExpanded) : varsExpanded;
+        // Full expansion: $? ${#VAR} $((expr)) ~ ${VAR:-def} $VAR etc.
+        // $(cmd) is already resolved upstream by runCommand before echo.run is called.
+        const expanded = expandSync(rawText, env?.vars ?? {}, env?.lastExitCode ?? 0);
+        const text = escapes ? expandEscapes(expanded) : expanded;
         return {
             stdout: noNewline ? text : `${text}\n`,
             exitCode: 0,

package/dist/commands/env.d.ts

@@ -1,4 +1,9 @@
 /** biome-ignore-all lint/style/useNamingConvention: ENV VARS */
 import type { ShellModule } from "../types/commands";
+/**
+ * Print environment variables for the current session.
+ * @category shell
+ * @params []
+ */
 export declare const envCommand: ShellModule;
 //# sourceMappingURL=env.d.ts.map

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

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

package/dist/commands/env.js

@@ -1,3 +1,8 @@
+/**
+ * Print environment variables for the current session.
+ * @category shell
+ * @params []
+ */
 export const envCommand = {
     name: "env",
     description: "Print environment variables",
@@ -5,6 +10,11 @@ export const envCommand = {
     params: [],
     run: ({ env, authUser }) => {
         const vars = { ...env.vars, USER: authUser, HOME: `/home/${authUser}` };
-        return { stdout: Object.entries(vars).map(([k, v]) => `${k}=${v}`).join("\n"), exitCode: 0 };
+        return {
+            stdout: Object.entries(vars)
+                .map(([k, v]) => `${k}=${v}`)
+                .join("\n"),
+            exitCode: 0,
+        };
     },
 };

package/dist/commands/exit.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Exit the current shell session (closeSession flag).
+ * @category shell
+ * @params ["[code]"]
+ */
 export declare const exitCommand: ShellModule;
 //# sourceMappingURL=exit.d.ts.map

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

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

package/dist/commands/exit.js

@@ -1,6 +1,16 @@
+/**
+ * Exit the current shell session (closeSession flag).
+ * @category shell
+ * @params ["[code]"]
+ */
 export const exitCommand = {
     name: "exit",
     aliases: ["bye"],
-    params: [],
-    run: () => ({ closeSession: true, exitCode: 0 }),
+    description: "Exit the shell session",
+    category: "shell",
+    params: ["[code]"],
+    run: ({ args }) => ({
+        closeSession: true,
+        exitCode: parseInt(args[0] ?? "0", 10) || 0,
+    }),
 };

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

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,eAAO,MAAM,aAAa,EAAE,WAsB3B,CAAC"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,eAAO,MAAM,aAAa,EAAE,WAwB3B,CAAC"}

package/dist/commands/export.js

@@ -5,7 +5,9 @@ export const exportCommand = {
     params: ["[VAR=value]"],
     run: ({ args, env }) => {
         if (args.length === 0) {
-            const out = Object.entries(env.vars).map(([k, v]) => `declare -x ${k}="${v}"`).join("\n");
+            const out = Object.entries(env.vars)
+                .map(([k, v]) => `declare -x ${k}="${v}"`)
+                .join("\n");
             return { stdout: out, exitCode: 0 };
         }
         for (const arg of args) {

package/dist/commands/find.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Find files and directories by name and type with minimal pattern support.
+ * @category files
+ * @params ["[path] [-name <pattern>] [-type f|d]"]
+ */
 export declare const findCommand: ShellModule;
 //# sourceMappingURL=find.d.ts.map

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

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

package/dist/commands/find.js

@@ -1,5 +1,10 @@
 import { getFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Find files and directories by name and type with minimal pattern support.
+ * @category files
+ * @params ["[path] [-name <pattern>] [-type f|d]"]
+ */
 export const findCommand = {
     name: "find",
     description: "Search for files",

package/dist/commands/free.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Display memory usage information (human / MB / GB options).
+ * @category system
+ * @params ["[-h] [-m] [-g]"]
+ */
 export declare const freeCommand: ShellModule;
 //# sourceMappingURL=free.d.ts.map

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

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

package/dist/commands/free.js

@@ -1,5 +1,10 @@
 import * as os from "node:os";
 import { ifFlag } from "./command-helpers";
+/**
+ * Display memory usage information (human / MB / GB options).
+ * @category system
+ * @params ["[-h] [-m] [-g]"]
+ */
 export const freeCommand = {
     name: "free",
     description: "Display amount of free and used memory",

package/dist/commands/grep.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Search for a regex pattern in files or stdin with common flags.
+ * @category text
+ * @params ["[-i] [-v] [-n] [-r] <pattern> [file...]"]
+ */
 export declare const grepCommand: ShellModule;
 //# sourceMappingURL=grep.d.ts.map

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

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

package/dist/commands/grep.js

@@ -1,12 +1,19 @@
 import { parseArgs } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Search for a regex pattern in files or stdin with common flags.
+ * @category text
+ * @params ["[-i] [-v] [-n] [-r] <pattern> [file...]"]
+ */
 export const grepCommand = {
     name: "grep",
     description: "Search text patterns",
     category: "text",
     params: ["[-i] [-v] [-n] [-r] <pattern> [file...]"],
     run: ({ authUser, shell, cwd, args, stdin }) => {
-        const { flags, positionals } = parseArgs(args, { flags: ["-i", "-v", "-n", "-r"] });
+        const { flags, positionals } = parseArgs(args, {
+            flags: ["-i", "-v", "-n", "-r"],
+        });
         const caseInsensitive = flags.has("-i");
         const invertMatch = flags.has("-v");
         const showLineNumbers = flags.has("-n");
@@ -80,7 +87,10 @@ export const grepCommand = {
                     results.push(...matchLines(content, prefix));
                 }
                 catch {
-                    return { stderr: `grep: ${file}: No such file or directory`, exitCode: 1 };
+                    return {
+                        stderr: `grep: ${file}: No such file or directory`,
+                        exitCode: 1,
+                    };
                 }
             }
         }

package/dist/commands/gzip.d.ts

@@ -1,4 +1,9 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Compress files using gzip (stores in VFS as compressed content).
+ * @category archive
+ * @params ["<file>"]
+ */
 export declare const gzipCommand: ShellModule;
 export declare const gunzipCommand: ShellModule;
 //# sourceMappingURL=gzip.d.ts.map

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

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

package/dist/commands/gzip.js

@@ -1,4 +1,9 @@
 import { resolvePath } from "./helpers";
+/**
+ * Compress files using gzip (stores in VFS as compressed content).
+ * @category archive
+ * @params ["<file>"]
+ */
 export const gzipCommand = {
     name: "gzip",
     description: "Compress files",
@@ -14,11 +19,19 @@ export const gzipCommand = {
             return { exitCode: 0 };
         }
         catch {
-            return { stderr: `gzip: ${file}: No such file or directory`, exitCode: 1 };
+            return {
+                stderr: `gzip: ${file}: No such file or directory`,
+                exitCode: 1,
+            };
         }
     },
 };
 export const gunzipCommand = {
+    /**
+     * Decompress gzip files (or zcat alias).
+     * @category archive
+     * @params ["<file>"]
+     */
     name: "gunzip",
     description: "Decompress files",
     category: "archive",
@@ -34,7 +47,10 @@ export const gunzipCommand = {
             return { exitCode: 0 };
         }
         catch {
-            return { stderr: `gunzip: ${file}: No such file or directory`, exitCode: 1 };
+            return {
+                stderr: `gunzip: ${file}: No such file or directory`,
+                exitCode: 1,
+            };
         }
     },
 };

package/dist/commands/head.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Output the first part of files or stdin (head).
+ * @category text
+ * @params ["[-n <lines>] [file...]"]
+ */
 export declare const headCommand: ShellModule;
 //# sourceMappingURL=head.d.ts.map

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

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

package/dist/commands/head.js

@@ -1,5 +1,10 @@
 import { getFlag } from "./command-helpers";
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Output the first part of files or stdin (head).
+ * @category text
+ * @params ["[-n <lines>] [file...]"]
+ */
 export const headCommand = {
     name: "head",
     description: "Output first lines",

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

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/commands/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAoBrD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,MAAM,EAAE,GAAG,WAAW,CAyDxE"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/commands/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6HrD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,MAAM,EAAE,GAAG,WAAW,CA0BxE"}

package/dist/commands/help.js

@@ -1,70 +1,123 @@
-import { getCommandModulesPublic } from "./index";
-const CATEGORY_ORDER = ["navigation", "files", "text", "archive", "system", "network", "shell", "users", "misc"];
+import { getCommandModulesPublic } from "./registry";
+// ─── category config ──────────────────────────────────────────────────────────
+const CATEGORY_ORDER = [
+    "navigation",
+    "files",
+    "text",
+    "archive",
+    "system",
+    "package",
+    "network",
+    "shell",
+    "users",
+    "misc",
+];
 const CATEGORY_LABELS = {
     navigation: "Navigation",
     files: "Files & Filesystem",
     text: "Text Processing",
     archive: "Archive & Compression",
     system: "System",
+    package: "Package Management",
     network: "Network",
-    shell: "Shell",
+    shell: "Shell & Scripting",
     users: "Users & Permissions",
     misc: "Miscellaneous",
 };
-function padRight(s, n) {
+// ─── formatting helpers ───────────────────────────────────────────────────────
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+const CYAN = "\x1b[36m";
+const YLW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+function pad(s, n) {
     return s.length >= n ? s : s + " ".repeat(n - s.length);
 }
+function formatCmdLine(mod) {
+    const aliases = mod.aliases?.length
+        ? ` ${DIM}(${mod.aliases.join(", ")})${RESET}`
+        : "";
+    return `  ${CYAN}${pad(mod.name, 16)}${RESET}${aliases}${pad("", mod.aliases?.length ? 0 : 0)} ${mod.description ?? ""}`;
+}
+// ─── full grouped listing ─────────────────────────────────────────────────────
+function renderFull(modules) {
+    const grouped = {};
+    for (const mod of modules) {
+        const cat = mod.category ?? "misc";
+        if (!grouped[cat])
+            grouped[cat] = [];
+        grouped[cat].push(mod);
+    }
+    const lines = [
+        `${BOLD}Available commands${RESET}`,
+        `${DIM}Type 'help <command>' for detailed usage.${RESET}`,
+        "",
+    ];
+    const cats = [
+        ...CATEGORY_ORDER.filter((c) => grouped[c]),
+        ...Object.keys(grouped)
+            .filter((c) => !CATEGORY_ORDER.includes(c))
+            .sort(),
+    ];
+    for (const cat of cats) {
+        const mods = grouped[cat];
+        if (!mods?.length)
+            continue;
+        lines.push(`${YLW}${CATEGORY_LABELS[cat] ?? cat}${RESET}`);
+        const sorted = [...mods].sort((a, b) => a.name.localeCompare(b.name));
+        for (const mod of sorted) {
+            lines.push(formatCmdLine(mod));
+        }
+        lines.push("");
+    }
+    const total = modules.length;
+    lines.push(`${DIM}${total} commands available.${RESET}`);
+    return lines.join("\n");
+}
+// ─── single-command detail ────────────────────────────────────────────────────
+function renderDetail(mod) {
+    const lines = [];
+    lines.push(`${BOLD}${mod.name}${RESET} — ${mod.description ?? "no description"}`);
+    if (mod.aliases?.length) {
+        lines.push(`${DIM}Aliases: ${mod.aliases.join(", ")}${RESET}`);
+    }
+    lines.push("");
+    lines.push(`${GREEN}Usage:${RESET}`);
+    if (mod.params.length) {
+        for (const p of mod.params) {
+            lines.push(`  ${mod.name} ${p}`);
+        }
+    }
+    else {
+        lines.push(`  ${mod.name}`);
+    }
+    const catLabel = CATEGORY_LABELS[mod.category ?? "misc"] ?? mod.category ?? "misc";
+    lines.push("");
+    lines.push(`${DIM}Category: ${catLabel}${RESET}`);
+    return lines.join("\n");
+}
+// ─── export ───────────────────────────────────────────────────────────────────
 export function createHelpCommand(_getNames) {
     return {
         name: "help",
-        description: "Display this help message",
+        description: "List all commands, or show usage for a specific command",
         category: "shell",
         params: ["[command]"],
         run: ({ args }) => {
             const modules = getCommandModulesPublic();
-            // help <command>
             if (args[0]) {
-                const mod = modules.find((m) => m.name === args[0] || m.aliases?.includes(args[0]));
-                if (!mod)
-                    return { stderr: `help: no help for '${args[0]}'`, exitCode: 1 };
-                const aliases = mod.aliases?.length ? `  aliases: ${mod.aliases.join(", ")}\n` : "";
-                const params = mod.params.map((p) => `  ${mod.name} ${p}`).join("\n");
-                return {
-                    stdout: [
-                        `\x1b[1m${mod.name}\x1b[0m — ${mod.description ?? "no description"}`,
-                        aliases,
-                        "Usage:",
-                        params || `  ${mod.name}`,
-                    ].filter(Boolean).join("\n"),
-                    exitCode: 0,
-                };
-            }
-            // Full help — grouped by category
-            const grouped = {};
-            for (const mod of modules) {
-                const cat = mod.category ?? "misc";
-                if (!grouped[cat])
-                    grouped[cat] = [];
-                grouped[cat].push(mod);
-            }
-            const lines = [];
-            lines.push("\x1b[1mAvailable commands\x1b[0m");
-            lines.push("");
-            const cats = [
-                ...CATEGORY_ORDER.filter((c) => grouped[c]),
-                ...Object.keys(grouped).filter((c) => !CATEGORY_ORDER.includes(c)),
-            ];
-            for (const cat of cats) {
-                const mods = grouped[cat];
-                if (!mods || mods.length === 0)
-                    continue;
-                lines.push(`\x1b[33m${CATEGORY_LABELS[cat] ?? cat}\x1b[0m`);
-                const sorted = [...mods].sort((a, b) => a.name.localeCompare(b.name));
-                for (const mod of sorted) {
-                    lines.push(`  \x1b[36m${padRight(mod.name, 14)}\x1b[0m ${mod.description ?? ""}`);
+                const target = args[0].toLowerCase();
+                const mod = modules.find((m) => m.name === target || m.aliases?.includes(target));
+                if (!mod) {
+                    return {
+                        stderr: `help: no help entry for '${args[0]}'`,
+                        exitCode: 1,
+                    };
                 }
+                return { stdout: renderDetail(mod), exitCode: 0 };
             }
-            return { stdout: lines.join("\n"), exitCode: 0 };
+            return { stdout: renderFull(modules), exitCode: 0 };
         },
     };
 }

package/dist/commands/history.d.ts

@@ -1,3 +1,8 @@
 import type { ShellModule } from "../types/commands";
+/**
+ * Display persisted command history for the session (from VFS).
+ * @category shell
+ * @params ["[n]"]
+ */
 export declare const historyCommand: ShellModule;
 //# sourceMappingURL=history.d.ts.map

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

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

package/dist/commands/history.js

@@ -1,3 +1,8 @@
+/**
+ * Display persisted command history for the session (from VFS).
+ * @category shell
+ * @params ["[n]"]
+ */
 export const historyCommand = {
     name: "history",
     description: "Display command history",