typescript-virtual-container 1.2.8 → 1.2.9

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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"}