typescript-virtual-container 1.2.7 → 1.2.9

package/dist/SSHMimic/executor.js

@@ -1,4 +1,4 @@
-import { runCommand as runSingleCommand } from "../commands";
+import { runCommandDirect } from "../commands";
 import { resolvePath } from "../commands/helpers";
 // ── Script executor (handles &&/||/;) ────────────────────────────────────────
 export async function executeScript(script, authUser, hostname, mode, cwd, shell, env) {
@@ -71,8 +71,7 @@ async function executeSingleCommandWithRedirections(cmd, authUser, hostname, mod
             return { stderr: `${cmd.inputFile}: No such file or directory`, exitCode: 1 };
         }
     }
-    const rawInput = [cmd.name, ...cmd.args].join(" ");
-    const result = await runSingleCommand(rawInput, authUser, hostname, mode, cwd, shell, stdin, env);
+    const result = await runCommandDirect(cmd.name, cmd.args, authUser, hostname, mode, cwd, shell, stdin, env);
     if (cmd.outputFile) {
         const outputPath = resolvePath(cwd, cmd.outputFile);
         const output = result.stdout || "";
@@ -111,8 +110,7 @@ async function executePipelineChain(commands, authUser, hostname, mode, cwd, she
                 return { stderr: `${cmd.inputFile}: No such file or directory`, exitCode: 1 };
             }
         }
-        const rawInput = [cmd.name, ...cmd.args].join(" ");
-        const result = await runSingleCommand(rawInput, authUser, hostname, mode, cwd, shell, currentOutput, env);
+        const result = await runCommandDirect(cmd.name, cmd.args, authUser, hostname, mode, cwd, shell, currentOutput, env);
         exitCode = result.exitCode ?? 0;
         if (i === commands.length - 1 && cmd.outputFile) {
             const outputPath = resolvePath(cwd, cmd.outputFile);

package/dist/VirtualFileSystem/binaryPack.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Binary serialisation format for VirtualFileSystem snapshots.
+ *
+ * Replaces the JSON+base64 approach. No external dependencies.
+ *
+ * Wire format (little-endian throughout):
+ *
+ *   File header:
+ *     [4]  magic  = 0x56 0x46 0x53 0x21  ("VFS!")
+ *     [1]  version = 0x01
+ *
+ *   Node (recursive):
+ *     [1]  type    = 0x01 (file) | 0x02 (directory)
+ *     [2]  name length (uint16)
+ *     [N]  name bytes (utf8)
+ *     [4]  mode (uint32)
+ *     [8]  createdAt ms (float64)
+ *     [8]  updatedAt ms (float64)
+ *
+ *   File node extra:
+ *     [1]  compressed flag (0x00 | 0x01)
+ *     [4]  content length (uint32)
+ *     [N]  content bytes (raw — no base64)
+ *
+ *   Directory node extra:
+ *     [4]  children count (uint32)
+ *     [N]  children nodes (recursive)
+ *
+ * Total overhead vs JSON+base64 for 1 MB of file data:
+ *   JSON+base64 :  ~1.37 MB (base64 33% bloat) + JSON string wrapping
+ *   Binary pack :  ~1.00 MB + ~40 bytes/node header  → ~27% smaller, no string parsing
+ */
+import type { InternalDirectoryNode } from "./internalTypes";
+/**
+ * Serialise an in-memory VFS root to a compact binary Buffer.
+ * No base64, no JSON. ~27% smaller than the JSON+base64 format for typical VFS trees.
+ */
+export declare function encodeVfs(root: InternalDirectoryNode): Buffer;
+/**
+ * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
+ * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.
+ */
+export declare function decodeVfs(buf: Buffer): InternalDirectoryNode;
+/**
+ * Returns true if `buf` looks like a VFS binary snapshot (starts with magic bytes).
+ * Used to auto-detect format when loading from disk.
+ */
+export declare function isBinarySnapshot(buf: Buffer): boolean;
+//# sourceMappingURL=binaryPack.d.ts.map

package/dist/VirtualFileSystem/binaryPack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binaryPack.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/binaryPack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAkC,MAAM,iBAAiB,CAAC;AA2E7F;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAM7D;AAuED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAiB5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/VirtualFileSystem/binaryPack.js

@@ -0,0 +1,193 @@
+/**
+ * Binary serialisation format for VirtualFileSystem snapshots.
+ *
+ * Replaces the JSON+base64 approach. No external dependencies.
+ *
+ * Wire format (little-endian throughout):
+ *
+ *   File header:
+ *     [4]  magic  = 0x56 0x46 0x53 0x21  ("VFS!")
+ *     [1]  version = 0x01
+ *
+ *   Node (recursive):
+ *     [1]  type    = 0x01 (file) | 0x02 (directory)
+ *     [2]  name length (uint16)
+ *     [N]  name bytes (utf8)
+ *     [4]  mode (uint32)
+ *     [8]  createdAt ms (float64)
+ *     [8]  updatedAt ms (float64)
+ *
+ *   File node extra:
+ *     [1]  compressed flag (0x00 | 0x01)
+ *     [4]  content length (uint32)
+ *     [N]  content bytes (raw — no base64)
+ *
+ *   Directory node extra:
+ *     [4]  children count (uint32)
+ *     [N]  children nodes (recursive)
+ *
+ * Total overhead vs JSON+base64 for 1 MB of file data:
+ *   JSON+base64 :  ~1.37 MB (base64 33% bloat) + JSON string wrapping
+ *   Binary pack :  ~1.00 MB + ~40 bytes/node header  → ~27% smaller, no string parsing
+ */
+const MAGIC = Buffer.from([0x56, 0x46, 0x53, 0x21]); // "VFS!"
+const VERSION = 0x01;
+const TYPE_FILE = 0x01;
+const TYPE_DIR = 0x02;
+// ── Encoder ───────────────────────────────────────────────────────────────────
+class Encoder {
+    chunks = [];
+    write(buf) { this.chunks.push(buf); }
+    writeUint8(n) {
+        const b = Buffer.allocUnsafe(1);
+        b.writeUInt8(n, 0);
+        this.chunks.push(b);
+    }
+    writeUint16(n) {
+        const b = Buffer.allocUnsafe(2);
+        b.writeUInt16LE(n, 0);
+        this.chunks.push(b);
+    }
+    writeUint32(n) {
+        const b = Buffer.allocUnsafe(4);
+        b.writeUInt32LE(n, 0);
+        this.chunks.push(b);
+    }
+    writeFloat64(n) {
+        const b = Buffer.allocUnsafe(8);
+        b.writeDoubleBE(n, 0);
+        this.chunks.push(b);
+    }
+    writeString(s) {
+        const encoded = Buffer.from(s, "utf8");
+        this.writeUint16(encoded.length);
+        this.chunks.push(encoded);
+    }
+    writeBytes(bytes) {
+        this.writeUint32(bytes.length);
+        this.chunks.push(bytes);
+    }
+    toBuffer() { return Buffer.concat(this.chunks); }
+}
+function encodeNode(enc, node) {
+    if (node.type === "file") {
+        const f = node;
+        enc.writeUint8(TYPE_FILE);
+        enc.writeString(f.name);
+        enc.writeUint32(f.mode);
+        enc.writeFloat64(f.createdAt.getTime());
+        enc.writeFloat64(f.updatedAt.getTime());
+        enc.writeUint8(f.compressed ? 0x01 : 0x00);
+        enc.writeBytes(f.content);
+    }
+    else {
+        const d = node;
+        enc.writeUint8(TYPE_DIR);
+        enc.writeString(d.name);
+        enc.writeUint32(d.mode);
+        enc.writeFloat64(d.createdAt.getTime());
+        enc.writeFloat64(d.updatedAt.getTime());
+        const children = Array.from(d.children.values());
+        enc.writeUint32(children.length);
+        for (const child of children)
+            encodeNode(enc, child);
+    }
+}
+/**
+ * Serialise an in-memory VFS root to a compact binary Buffer.
+ * No base64, no JSON. ~27% smaller than the JSON+base64 format for typical VFS trees.
+ */
+export function encodeVfs(root) {
+    const enc = new Encoder();
+    enc.write(MAGIC);
+    enc.writeUint8(VERSION);
+    encodeNode(enc, root);
+    return enc.toBuffer();
+}
+// ── Decoder ───────────────────────────────────────────────────────────────────
+class Decoder {
+    buf;
+    pos = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    readUint8() { return this.buf.readUInt8(this.pos++); }
+    readUint16() {
+        const v = this.buf.readUInt16LE(this.pos);
+        this.pos += 2;
+        return v;
+    }
+    readUint32() {
+        const v = this.buf.readUInt32LE(this.pos);
+        this.pos += 4;
+        return v;
+    }
+    readFloat64() {
+        const v = this.buf.readDoubleBE(this.pos);
+        this.pos += 8;
+        return v;
+    }
+    readString() {
+        const len = this.readUint16();
+        const s = this.buf.toString("utf8", this.pos, this.pos + len);
+        this.pos += len;
+        return s;
+    }
+    readBytes() {
+        const len = this.readUint32();
+        const b = this.buf.slice(this.pos, this.pos + len);
+        this.pos += len;
+        return b;
+    }
+    remaining() { return this.buf.length - this.pos; }
+}
+function decodeNode(dec) {
+    const type = dec.readUint8();
+    const name = dec.readString();
+    const mode = dec.readUint32();
+    const createdAt = new Date(dec.readFloat64());
+    const updatedAt = new Date(dec.readFloat64());
+    if (type === TYPE_FILE) {
+        const compressed = dec.readUint8() === 0x01;
+        const content = dec.readBytes();
+        return { type: "file", name, mode, createdAt, updatedAt, compressed, content };
+    }
+    if (type === TYPE_DIR) {
+        const count = dec.readUint32();
+        const children = new Map();
+        for (let i = 0; i < count; i++) {
+            const child = decodeNode(dec);
+            children.set(child.name, child);
+        }
+        return { type: "directory", name, mode, createdAt, updatedAt, children };
+    }
+    throw new Error(`[VFS binary] Unknown node type: 0x${type.toString(16)}`);
+}
+/**
+ * Deserialise a binary Buffer produced by {@link encodeVfs} back into an
+ * InternalDirectoryNode tree. Throws on magic/version mismatch or truncation.
+ */
+export function decodeVfs(buf) {
+    if (buf.length < 5)
+        throw new Error("[VFS binary] Buffer too short");
+    const magic = buf.slice(0, 4);
+    if (!magic.equals(MAGIC)) {
+        throw new Error("[VFS binary] Invalid magic — not a VFS binary snapshot");
+    }
+    const dec = new Decoder(buf);
+    // skip magic (4) + version (1)
+    for (let i = 0; i < 5; i++)
+        dec.readUint8();
+    const root = decodeNode(dec);
+    if (root.type !== "directory") {
+        throw new Error("[VFS binary] Root node must be a directory");
+    }
+    return root;
+}
+/**
+ * Returns true if `buf` looks like a VFS binary snapshot (starts with magic bytes).
+ * Used to auto-detect format when loading from disk.
+ */
+export function isBinarySnapshot(buf) {
+    return buf.length >= 4 && buf.slice(0, 4).equals(MAGIC);
+}

package/dist/VirtualFileSystem/index.d.ts

@@ -4,8 +4,8 @@ import type { RemoveOptions, VfsNodeStats, VfsSnapshot, WriteFileOptions } from
  * "memory" — pure in-memory, no disk I/O (default).
  *
  * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
- *             `snapshotPath` must be set to the directory where the JSON
- *             snapshot file will be read/written.
+ *             `snapshotPath` must be set to the directory where the binary
+ *             snapshot file will be read/written (`vfs-snapshot.vfsb`).
  */
 export type VfsPersistenceMode = "memory" | "fs";
 export interface VfsOptions {
@@ -29,7 +29,7 @@ export interface VfsOptions {
  * **Memory mode** (default) — all state lives in a fast recursive tree.
  * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
  *
- * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a binary
  * snapshot from disk and `flushMirror()` writes it back.  This gives you
  * persistent VFS state across process restarts without any real POSIX filesystem
  * semantics leaking through.
@@ -55,14 +55,16 @@ declare class VirtualFileSystem extends EventEmitter {
     private makeFile;
     private mkdirRecursive;
     /**
-     * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+     * In `"fs"` mode: reads the binary snapshot (`vfs-snapshot.vfsb`) from disk.
+     * Automatically falls back to legacy JSON format for backward compatibility.
      * Silently succeeds when the snapshot file does not exist yet.
      *
      * In `"memory"` mode: no-op (kept for API compatibility).
      */
     restoreMirror(): Promise<void>;
     /**
-     * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+     * In `"fs"` mode: serialises the in-memory tree to a binary snapshot on disk
+     * (`vfs-snapshot.vfsb`). ~27% smaller and significantly faster than JSON+base64.
      * The directory is created if it does not exist.
      *
      * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).

package/dist/VirtualFileSystem/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualFileSystem/index.ts"],"names":[],"mappings":"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"}

package/dist/VirtualFileSystem/index.js

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import * as fsSync from "node:fs";
 import * as path from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
+import { decodeVfs, encodeVfs, isBinarySnapshot } from "./binaryPack";
 import { getNode, getParentDirectory, normalizePath } from "./path";
 // ── VirtualFileSystem ─────────────────────────────────────────────────────────
 /**
@@ -10,7 +11,7 @@ import { getNode, getParentDirectory, normalizePath } from "./path";
  * **Memory mode** (default) — all state lives in a fast recursive tree.
  * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
  *
- * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a binary
  * snapshot from disk and `flushMirror()` writes it back.  This gives you
  * persistent VFS state across process restarts without any real POSIX filesystem
  * semantics leaking through.
@@ -38,7 +39,7 @@ class VirtualFileSystem extends EventEmitter {
             if (!options.snapshotPath) {
                 throw new Error('VirtualFileSystem: "snapshotPath" is required when mode is "fs".');
             }
-            this.snapshotFile = path.resolve(options.snapshotPath, "vfs-snapshot.json");
+            this.snapshotFile = path.resolve(options.snapshotPath, "vfs-snapshot.vfsb");
         }
         else {
             this.snapshotFile = null;
@@ -92,7 +93,8 @@ class VirtualFileSystem extends EventEmitter {
     }
     // ── Persistence ───────────────────────────────────────────────────────────
     /**
-     * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+     * In `"fs"` mode: reads the binary snapshot (`vfs-snapshot.vfsb`) from disk.
+     * Automatically falls back to legacy JSON format for backward compatibility.
      * Silently succeeds when the snapshot file does not exist yet.
      *
      * In `"memory"` mode: no-op (kept for API compatibility).
@@ -103,9 +105,17 @@ class VirtualFileSystem extends EventEmitter {
         if (!fsSync.existsSync(this.snapshotFile))
             return;
         try {
-            const raw = fsSync.readFileSync(this.snapshotFile, "utf8");
-            const snapshot = JSON.parse(raw);
-            this.root = this.deserializeDir(snapshot.root, "");
+            const raw = fsSync.readFileSync(this.snapshotFile);
+            if (isBinarySnapshot(raw)) {
+                // Fast binary format (current)
+                this.root = decodeVfs(raw);
+            }
+            else {
+                // Legacy JSON fallback — auto-migrates on next flushMirror()
+                const snapshot = JSON.parse(raw.toString("utf8"));
+                this.root = this.deserializeDir(snapshot.root, "");
+                console.info("[VirtualFileSystem] Migrating legacy JSON snapshot to binary format.");
+            }
             this.emit("snapshot:restore", { path: this.snapshotFile });
         }
         catch (err) {
@@ -114,7 +124,8 @@ class VirtualFileSystem extends EventEmitter {
         }
     }
     /**
-     * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+     * In `"fs"` mode: serialises the in-memory tree to a binary snapshot on disk
+     * (`vfs-snapshot.vfsb`). ~27% smaller and significantly faster than JSON+base64.
      * The directory is created if it does not exist.
      *
      * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
@@ -126,8 +137,8 @@ class VirtualFileSystem extends EventEmitter {
         }
         const dir = path.dirname(this.snapshotFile);
         fsSync.mkdirSync(dir, { recursive: true });
-        const snapshot = this.toSnapshot();
-        fsSync.writeFileSync(this.snapshotFile, JSON.stringify(snapshot), "utf8");
+        const binary = encodeVfs(this.root);
+        fsSync.writeFileSync(this.snapshotFile, binary);
         this.emit("mirror:flush", { path: this.snapshotFile });
     }
     /** Returns the current persistence mode. */

package/dist/VirtualPackageManager/index.d.ts

@@ -0,0 +1,202 @@
+import type VirtualFileSystem from "../VirtualFileSystem";
+import type { VirtualUserManager } from "../VirtualUserManager";
+/**
+ * A single file entry written into the VFS when a package is installed.
+ */
+export interface PackageFile {
+    /** Absolute VFS destination path (e.g. `"/usr/bin/vim"`). */
+    path: string;
+    /** Text content to write. */
+    content: string;
+    /** POSIX mode bits (default `0o644`; use `0o755` for executables). */
+    mode?: number;
+}
+/**
+ * Metadata and behaviour definition for a single package in the registry.
+ *
+ * Used both for the built-in registry entries and for consumer-supplied custom
+ * packages. `files` are written to the VFS on `install()`, and `onInstall` /
+ * `onRemove` hooks allow arbitrary VFS mutations.
+ */
+export interface PackageDefinition {
+    /** Package name — lowercase, no spaces (e.g. `"vim"`, `"build-essential"`). */
+    name: string;
+    /** Debian-style version string (e.g. `"2:9.0.1378-2"`). */
+    version: string;
+    /** CPU architecture label (default `"amd64"`). */
+    architecture?: string;
+    /** Maintainer name and email shown in `apt show` output. */
+    maintainer?: string;
+    /** Full package description. */
+    description: string;
+    /** Short one-line summary shown in `apt search` results. */
+    shortDesc?: string;
+    /** Installed disk usage in kilobytes (informational). */
+    installedSizeKb?: number;
+    /** Other package names that must be installed first (resolved recursively). */
+    depends?: string[];
+    /** Repository section (e.g. `"utils"`, `"net"`, `"editors"`, `"devel"`). */
+    section?: string;
+    /** Files to write into the VFS during installation. */
+    files?: PackageFile[];
+    /**
+     * Hook called after all files are written.
+     * Use to create directories, write config, or register shell commands.
+     */
+    onInstall?: (vfs: VirtualFileSystem, users: VirtualUserManager) => void;
+    /** Hook called before VFS files are removed during uninstall. */
+    onRemove?: (vfs: VirtualFileSystem) => void;
+}
+/**
+ * Runtime record of an installed package, persisted to `/var/lib/dpkg/status`.
+ */
+export interface InstalledPackage {
+    /** Package name. */
+    name: string;
+    /** Installed version string. */
+    version: string;
+    /** CPU architecture. */
+    architecture: string;
+    /** Maintainer display string. */
+    maintainer: string;
+    /** Full description. */
+    description: string;
+    /** Repository section. */
+    section: string;
+    /** Installed disk usage in kilobytes. */
+    installedSizeKb: number;
+    /** ISO-8601 timestamp of when the package was installed. */
+    installedAt: string;
+    /** Absolute VFS paths written by this package (used by `dpkg -L`). */
+    files: string[];
+}
+/**
+ * Pure-TypeScript APT/dpkg package manager backed by a built-in registry.
+ *
+ * Accessed via `shell.packageManager` — not constructed directly.
+ *
+ * `install()` resolves dependencies recursively, writes declared files to the
+ * VFS, runs `onInstall` hooks, and persists state to `/var/lib/dpkg/status`.
+ * `remove()` reverses the process. All state survives VFS snapshot round-trips.
+ *
+ * @example
+ * ```ts
+ * const pm = shell.packageManager;
+ * pm.install(["vim", "git"]);
+ * console.log(pm.isInstalled("vim")); // true
+ * console.log(pm.installedCount());   // 2
+ * ```
+ */
+export declare class VirtualPackageManager {
+    private readonly vfs;
+    private readonly users;
+    private readonly installed;
+    private readonly registryPath;
+    private readonly logPath;
+    private readonly aptLogPath;
+    /**
+     * @param vfs   Backing virtual filesystem for file I/O and dpkg status persistence.
+     * @param users User manager reference passed to `onInstall` hooks.
+     */
+    constructor(vfs: VirtualFileSystem, users: VirtualUserManager);
+    /**
+     * Loads installed package state from `/var/lib/dpkg/status` in the VFS.
+     *
+     * Called automatically by `VirtualShell` after `bootstrapLinuxRootfs`.
+     * Safe to call again to reload state after a snapshot restore.
+     */
+    load(): void;
+    /** Persist installed state to /var/lib/dpkg/status. */
+    private persist;
+    private parseFields;
+    private log;
+    private aptLog;
+    /**
+     * Looks up a package definition in the built-in registry by name.
+     *
+     * @param name Package name (case-insensitive).
+     * @returns The matching `PackageDefinition`, or `undefined` if not found.
+     */
+    findInRegistry(name: string): PackageDefinition | undefined;
+    /**
+     * Returns all packages in the built-in registry, sorted alphabetically.
+     *
+     * @returns Array of `PackageDefinition` entries.
+     */
+    listAvailable(): PackageDefinition[];
+    /**
+     * Returns all currently installed packages, sorted alphabetically.
+     *
+     * @returns Array of `InstalledPackage` records.
+     */
+    listInstalled(): InstalledPackage[];
+    /**
+     * Returns `true` when the given package is currently installed.
+     *
+     * @param name Package name (case-insensitive).
+     */
+    isInstalled(name: string): boolean;
+    /**
+     * Returns the total number of installed packages.
+     *
+     * Used by `neofetch` to populate the `Packages:` field.
+     */
+    installedCount(): number;
+    /**
+     * Installs one or more packages from the registry.
+     *
+     * Dependencies listed in `PackageDefinition.depends` are resolved and
+     * installed automatically. Already-installed packages are skipped. Files
+     * declared in `PackageDefinition.files` are written to the VFS and
+     * `onInstall` hooks are called in dependency order.
+     *
+     * @param names   Package names to install.
+     * @param opts    Installation options.
+     * @param opts.quiet  Suppress progress output lines when `true`.
+     * @returns Terminal-style `output` string and an APT-compatible `exitCode`
+     *          (`0` on success, `100` when a package is not found).
+     */
+    install(names: string[], opts?: {
+        quiet?: boolean;
+    }): {
+        output: string;
+        exitCode: number;
+    };
+    /**
+     * Removes one or more installed packages.
+     *
+     * Package files are deleted from the VFS. Config files (paths under
+     * `/etc/` or ending in `.conf`) are preserved unless `opts.purge` is set.
+     * The `onRemove` hook is called for each package.
+     *
+     * @param names       Package names to remove.
+     * @param opts        Removal options.
+     * @param opts.purge  Also delete configuration files when `true`.
+     * @param opts.quiet  Suppress progress output lines when `true`.
+     * @returns Terminal-style `output` string and exit code (`0` on success).
+     */
+    remove(names: string[], opts?: {
+        purge?: boolean;
+        quiet?: boolean;
+    }): {
+        output: string;
+        exitCode: number;
+    };
+    /**
+     * Searches the registry for packages whose name or description contains
+     * the given term (case-insensitive). Equivalent to `apt-cache search`.
+     *
+     * @param term Search string.
+     * @returns Matching `PackageDefinition` entries sorted alphabetically.
+     */
+    search(term: string): PackageDefinition[];
+    /**
+     * Returns a dpkg-style metadata block for a package, including its
+     * install status. Equivalent to `apt-cache show` / `dpkg -s`.
+     *
+     * @param name Package name.
+     * @returns Multi-line metadata string, or `null` if not in the registry.
+     */
+    show(name: string): string | null;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/VirtualPackageManager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualPackageManager/index.ts"],"names":[],"mappings":"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"}