typescript-virtual-container 1.2.7 → 1.2.9

package/dist/commands/alias.js

@@ -0,0 +1,58 @@
+import { ifFlag } from "./command-helpers";
+export const aliasCommand = {
+    name: "alias",
+    description: "Define or display aliases",
+    category: "shell",
+    params: ["[name[=value] ...]"],
+    run: ({ args, env }) => {
+        if (!env)
+            return { exitCode: 0 };
+        // Aliases stored in env.vars under prefix __alias_
+        if (args.length === 0) {
+            const aliases = Object.entries(env.vars)
+                .filter(([k]) => k.startsWith("__alias_"))
+                .map(([k, v]) => `alias ${k.slice("__alias_".length)}='${v}'`);
+            return { stdout: aliases.join("\n") || "", exitCode: 0 };
+        }
+        const lines = [];
+        for (const arg of args) {
+            const eq = arg.indexOf("=");
+            if (eq === -1) {
+                // Display single alias
+                const val = env.vars[`__alias_${arg}`];
+                if (val)
+                    lines.push(`alias ${arg}='${val}'`);
+                else
+                    return { stderr: `alias: ${arg}: not found`, exitCode: 1 };
+            }
+            else {
+                // Set alias
+                const name = arg.slice(0, eq);
+                const val = arg.slice(eq + 1).replace(/^['"]|['"]$/g, "");
+                env.vars[`__alias_${name}`] = val;
+            }
+        }
+        return { stdout: lines.join("\n") || undefined, exitCode: 0 };
+    },
+};
+export const unaliasCommand = {
+    name: "unalias",
+    description: "Remove alias definitions",
+    category: "shell",
+    params: ["<name...> | -a"],
+    run: ({ args, env }) => {
+        if (!env)
+            return { exitCode: 0 };
+        if (ifFlag(args, ["-a"])) {
+            for (const k of Object.keys(env.vars)) {
+                if (k.startsWith("__alias_"))
+                    delete env.vars[k];
+            }
+            return { exitCode: 0 };
+        }
+        for (const name of args) {
+            delete env.vars[`__alias_${name}`];
+        }
+        return { exitCode: 0 };
+    },
+};

package/dist/commands/apt.d.ts

@@ -0,0 +1,4 @@
+import type { ShellModule } from "../types/commands";
+export declare const aptCommand: ShellModule;
+export declare const aptCacheCommand: ShellModule;
+//# sourceMappingURL=apt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apt.d.ts","sourceRoot":"","sources":["../../src/commands/apt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,eAAO,MAAM,UAAU,EAAE,WA2IxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAoD7B,CAAC"}

package/dist/commands/apt.js

@@ -0,0 +1,182 @@
+import { ifFlag, } from "./command-helpers";
+import { getPackageManager } from "./helpers";
+export const aptCommand = {
+    name: "apt",
+    aliases: ["apt-get"],
+    description: "Package manager",
+    category: "system",
+    params: ["<install|remove|update|upgrade|search|show|list> [pkg...]"],
+    run: ({ args, shell, authUser }) => {
+        const pm = getPackageManager(shell);
+        if (!pm)
+            return { stderr: "apt: package manager not initialised", exitCode: 1 };
+        const sub = args[0]?.toLowerCase();
+        const rest = args.slice(1);
+        const quiet = ifFlag(rest, ["-q", "--quiet", "-qq"]);
+        const purge = ifFlag(rest, ["--purge"]);
+        const pkgs = rest.filter((a) => !a.startsWith("-"));
+        // Non-root check
+        const restricted = ["install", "remove", "purge", "upgrade", "update"];
+        if (restricted.includes(sub ?? "") && authUser !== "root") {
+            return {
+                stderr: "E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)\nE: Unable to acquire the dpkg frontend lock, are you root?",
+                exitCode: 100,
+            };
+        }
+        switch (sub) {
+            case "install": {
+                if (pkgs.length === 0)
+                    return { stderr: "apt: no packages specified", exitCode: 1 };
+                const { output, exitCode } = pm.install(pkgs, { quiet });
+                return { stdout: output || undefined, exitCode };
+            }
+            case "remove":
+            case "purge": {
+                if (pkgs.length === 0)
+                    return { stderr: "apt: no packages specified", exitCode: 1 };
+                const { output, exitCode } = pm.remove(pkgs, {
+                    purge: sub === "purge" || purge,
+                    quiet,
+                });
+                return { stdout: output || undefined, exitCode };
+            }
+            case "update": {
+                return {
+                    stdout: [
+                        "Hit:1 fortune://packages.fortune.local aurora InRelease",
+                        "Hit:2 fortune://security.fortune.local aurora-security InRelease",
+                        "Reading package lists... Done",
+                        "Building dependency tree... Done",
+                        "Reading state information... Done",
+                        `All packages are up to date.`,
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            case "upgrade": {
+                return {
+                    stdout: [
+                        "Reading package lists... Done",
+                        "Building dependency tree... Done",
+                        "Reading state information... Done",
+                        "Calculating upgrade... Done",
+                        "0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.",
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            case "search": {
+                const term = pkgs[0];
+                if (!term)
+                    return { stderr: "apt: search requires a term", exitCode: 1 };
+                const results = pm.search(term);
+                if (results.length === 0)
+                    return {
+                        stdout: `Sorting... Done\nFull Text Search... Done\n(no results)`,
+                        exitCode: 0,
+                    };
+                const lines = results.map((p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64\n  ${p.shortDesc ?? p.description}`);
+                return {
+                    stdout: `Sorting... Done\nFull Text Search... Done\n${lines.join("\n")}`,
+                    exitCode: 0,
+                };
+            }
+            case "show": {
+                const name = pkgs[0];
+                if (!name)
+                    return { stderr: "apt: show requires a package name", exitCode: 1 };
+                const info = pm.show(name);
+                if (!info)
+                    return { stderr: `N: Unable to locate package ${name}`, exitCode: 100 };
+                return { stdout: info, exitCode: 0 };
+            }
+            case "list": {
+                const installedFlag = ifFlag(rest, ["--installed"]);
+                if (installedFlag) {
+                    const pkgList = pm.listInstalled();
+                    if (pkgList.length === 0)
+                        return { stdout: "Listing... Done\n(no packages installed)", exitCode: 0 };
+                    const lines = pkgList.map((p) => `${p.name}/${p.section} ${p.version} ${p.architecture} [installed]`);
+                    return { stdout: `Listing... Done\n${lines.join("\n")}`, exitCode: 0 };
+                }
+                // all available
+                const all = pm.listAvailable();
+                const lines = all.map((p) => `${p.name}/${p.section ?? "misc"} ${p.version} amd64`);
+                return { stdout: `Listing... Done\n${lines.join("\n")}`, exitCode: 0 };
+            }
+            default: {
+                return {
+                    stdout: [
+                        "Usage: apt [options] command",
+                        "",
+                        "Commands:",
+                        "  install <pkg...>   Install packages",
+                        "  remove <pkg...>    Remove packages",
+                        "  purge <pkg...>     Remove packages and config files",
+                        "  update             Refresh package index",
+                        "  upgrade            Upgrade all packages",
+                        "  search <term>      Search in package descriptions",
+                        "  show <pkg>         Show package details",
+                        "  list [--installed] List packages",
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+        }
+    },
+};
+export const aptCacheCommand = {
+    name: "apt-cache",
+    description: "Query the package cache",
+    category: "system",
+    params: ["<search|show|policy> [pkg]"],
+    run: ({ args, shell }) => {
+        const pm = getPackageManager(shell);
+        if (!pm)
+            return { stderr: "apt-cache: package manager not initialised", exitCode: 1 };
+        const sub = args[0]?.toLowerCase();
+        const pkgName = args[1];
+        switch (sub) {
+            case "search": {
+                if (!pkgName)
+                    return { stderr: "Need a search term", exitCode: 1 };
+                const results = pm.search(pkgName);
+                return {
+                    stdout: results
+                        .map((p) => `${p.name} - ${p.shortDesc ?? p.description}`)
+                        .join("\n") || "(no results)",
+                    exitCode: 0,
+                };
+            }
+            case "show": {
+                if (!pkgName)
+                    return { stderr: "Need a package name", exitCode: 1 };
+                const info = pm.show(pkgName);
+                return info
+                    ? { stdout: info, exitCode: 0 }
+                    : { stderr: `N: Unable to locate package ${pkgName}`, exitCode: 100 };
+            }
+            case "policy": {
+                if (!pkgName)
+                    return { stderr: "Need a package name", exitCode: 1 };
+                const def = pm.findInRegistry(pkgName);
+                if (!def)
+                    return { stderr: `N: Unable to locate package ${pkgName}`, exitCode: 100 };
+                const inst = pm.isInstalled(pkgName);
+                return {
+                    stdout: [
+                        `${pkgName}:`,
+                        `  Installed: ${inst ? def.version : "(none)"}`,
+                        `  Candidate: ${def.version}`,
+                        `  Version table:`,
+                        `     ${def.version} 500`,
+                        `        500 fortune://packages.fortune.local aurora/main amd64 Packages`,
+                    ].join("\n"),
+                    exitCode: 0,
+                };
+            }
+            default:
+                return { stderr: `apt-cache: unknown command '${sub ?? ""}'`, exitCode: 1 };
+        }
+    },
+};

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

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

package/dist/commands/cat.js

@@ -1,17 +1,36 @@
-import { getArg } from "./command-helpers";
+import { ifFlag } from "./command-helpers";
 import { assertPathAccess, resolveReadablePath } from "./helpers";
 export const catCommand = {
     name: "cat",
     description: "Concatenate and print files",
     category: "files",
-    params: ["<file>"],
-    run: ({ authUser, shell, cwd, args }) => {
-        const fileArg = getArg(args, 0);
-        if (!fileArg) {
+    params: ["[-n] [-b] <file...>"],
+    run: ({ authUser, shell, cwd, args, stdin }) => {
+        const numberAll = ifFlag(args, ["-n", "--number"]);
+        const numberNonBlank = ifFlag(args, ["-b", "--number-nonblank"]);
+        const fileArgs = args.filter((a) => !a.startsWith("-"));
+        if (fileArgs.length === 0 && stdin !== undefined) {
+            return { stdout: stdin, exitCode: 0 };
+        }
+        if (fileArgs.length === 0) {
             return { stderr: "cat: missing file operand", exitCode: 1 };
         }
-        const target = resolveReadablePath(shell.vfs, cwd, fileArg);
-        assertPathAccess(authUser, target, "cat");
-        return { stdout: shell.vfs.readFile(target), exitCode: 0 };
+        const parts = [];
+        for (const fileArg of fileArgs) {
+            const target = resolveReadablePath(shell.vfs, cwd, fileArg);
+            assertPathAccess(authUser, target, "cat");
+            parts.push(shell.vfs.readFile(target));
+        }
+        const combined = parts.join("");
+        if (!numberAll && !numberNonBlank) {
+            return { stdout: combined, exitCode: 0 };
+        }
+        let lineNum = 1;
+        const numbered = combined.split("\n").map((line) => {
+            if (numberNonBlank && line.trim() === "")
+                return line;
+            return `${String(lineNum++).padStart(6)}\t${line}`;
+        }).join("\n");
+        return { stdout: numbered, exitCode: 0 };
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"chmod.d.ts","sourceRoot":"","sources":["../../src/commands/chmod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,eAAO,MAAM,YAAY,EAAE,WA+B1B,CAAC"}
+{"version":3,"file":"chmod.d.ts","sourceRoot":"","sources":["../../src/commands/chmod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuCrD,eAAO,MAAM,YAAY,EAAE,WAwC1B,CAAC"}

package/dist/commands/chmod.js

@@ -1,4 +1,43 @@
 import { assertPathAccess, resolvePath } from "./helpers";
+/**
+ * Parse a symbolic chmod mode string (e.g. "+x", "u+x", "go-w", "a+rx")
+ * and apply it to the existing mode bits.
+ * Returns null if the string is not a valid symbolic mode.
+ */
+function applySymbolicMode(existing, modeStr) {
+    const pattern = /^([ugoa]*)([+\-=])([rwx]*)$/;
+    const parts = modeStr.split(",");
+    let mode = existing;
+    for (const part of parts) {
+        const m = part.trim().match(pattern);
+        if (!m)
+            return null;
+        const [, who = "a", op, perms = ""] = m;
+        const targets = who === "" || who === "a" ? ["u", "g", "o"] : who.split("");
+        const bits = {
+            u: { r: 0o400, w: 0o200, x: 0o100 },
+            g: { r: 0o040, w: 0o020, x: 0o010 },
+            o: { r: 0o004, w: 0o002, x: 0o001 },
+        };
+        for (const t of targets) {
+            for (const p of perms.split("")) {
+                const bit = bits[t]?.[p];
+                if (bit === undefined)
+                    continue;
+                if (op === "+")
+                    mode |= bit;
+                else if (op === "-")
+                    mode &= ~bit;
+                else if (op === "=") {
+                    // clear all bits for this target, then set requested
+                    const mask = Object.values(bits[t] ?? {}).reduce((a, b) => a | b, 0);
+                    mode = (mode & ~mask) | bit;
+                }
+            }
+        }
+    }
+    return mode;
+}
 export const chmodCommand = {
     name: "chmod",
     description: "Change file permissions",
@@ -18,9 +57,19 @@ export const chmodCommand = {
                     exitCode: 1,
                 };
             }
-            const mode = parseInt(modeArg, 8);
-            if (Number.isNaN(mode)) {
-                return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+            let mode;
+            const octal = parseInt(modeArg, 8);
+            if (!Number.isNaN(octal) && /^[0-7]+$/.test(modeArg)) {
+                mode = octal;
+            }
+            else {
+                // symbolic mode
+                const existing = shell.vfs.stat(filePath).mode;
+                const result = applySymbolicMode(existing, modeArg);
+                if (result === null) {
+                    return { stderr: `chmod: invalid mode: ${modeArg}`, exitCode: 1 };
+                }
+                mode = result;
             }
             shell.vfs.chmod(filePath, mode);
             return { exitCode: 0 };

package/dist/commands/command-helpers.d.ts

@@ -2,14 +2,88 @@ type ArgParseOptions = {
     flags?: string[];
     flagsWithValue?: string[];
 };
+/**
+ * Returns `true` when any of the given flags appear in `args`.
+ *
+ * Matches both standalone tokens (`-s`, `--silent`) and inline forms
+ * (`--output=file`). Useful for simple boolean flag checks inside command
+ * `run` handlers.
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns `true` if at least one flag is present, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * ifFlag(args, "-r")              // single flag
+ * ifFlag(args, ["-r", "--recursive"]) // aliases
+ * ```
+ */
 export declare function ifFlag(args: string[], flags: string | string[]): boolean;
+/**
+ * Returns the value associated with a flag, or `true` if the flag is present
+ * but has no associated value, or `undefined` if the flag is absent.
+ *
+ * Handles three forms:
+ * - `--output file`   → returns `"file"` (next token)
+ * - `--output=file`   → returns `"file"` (inline `=` form)
+ * - `--verbose`       → returns `true` (flag with no value)
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns The flag value string, `true` when valueless, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const output = getFlag(args, ["-o", "--output"]);
+ * if (typeof output === "string") { /* use path *\/ }
+ * ```
+ */
 export declare function getFlag(args: string[], flags: string | string[]): string | true | undefined;
+/**
+ * Returns the positional argument at the given zero-based index, skipping
+ * known flags and their values.
+ *
+ * Flags declared in `options.flags` are treated as boolean and skipped.
+ * Flags declared in `options.flagsWithValue` consume the next token too.
+ * Tokens after `--` are always treated as positionals.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param index   Zero-based positional index to retrieve.
+ * @param options Optional flag declarations to skip during positional collection.
+ * @returns The positional value, or `undefined` if the index is out of range.
+ *
+ * @example
+ * ```ts
+ * // args = ["-r", "src", "dest"]
+ * getArg(args, 0, { flags: ["-r"] }) // "src"
+ * getArg(args, 1, { flags: ["-r"] }) // "dest"
+ * ```
+ */
 export declare function getArg(args: string[], index: number, options?: ArgParseOptions): string | undefined;
 /**
- * Parse arguments into flags, flags with values, and positionals.
- * @param args - Array of arguments to parse.
- * @param options - Parsing options for flags and flags with values.
- * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ * Parses an argument array into structured flags, flag values, and positionals.
+ *
+ * - `options.flags` — boolean flags (e.g. `["-r", "--recursive"]`); collected
+ *   into a `Set<string>` and not treated as positionals.
+ * - `options.flagsWithValue` — flags that consume the next token or an inline
+ *   `=value`; collected into a `Map<string, string>`.
+ * - All remaining tokens are positionals.
+ * - Tokens after `--` are always positionals, regardless of `-` prefix.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param options Flag declaration lists.
+ * @returns `{ flags, flagsWithValues, positionals }`.
+ *
+ * @example
+ * ```ts
+ * const { flags, flagsWithValues, positionals } = parseArgs(args, {
+ *   flags:          ["-r", "--recursive"],
+ *   flagsWithValue: ["-o", "--output"],
+ * });
+ * const recursive = flags.has("-r");
+ * const output    = flagsWithValues.get("-o");
+ * ```
  */
 export declare function parseArgs(args: string[], options?: {
     flags?: string[];

package/dist/commands/command-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/command-helpers.ts"],"names":[],"mappings":"AAAA,KAAK,eAAe,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA+EF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAYxE;AAED,wBAAgB,OAAO,CACtB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GACtB,MAAM,GAAG,IAAI,GAAG,SAAS,CA0B3B;AAED,wBAAgB,MAAM,CACrB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3D;IACF,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB,CAiDA"}
+{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/command-helpers.ts"],"names":[],"mappings":"AAAA,KAAK,eAAe,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA+EF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAYxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CACtB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GACtB,MAAM,GAAG,IAAI,GAAG,SAAS,CA0B3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CACrB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC3B,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3D;IACF,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB,CAiDA"}

package/dist/commands/command-helpers.js

@@ -54,6 +54,23 @@ function collectPositionals(args, options = {}) {
     }
     return positionals;
 }
+/**
+ * Returns `true` when any of the given flags appear in `args`.
+ *
+ * Matches both standalone tokens (`-s`, `--silent`) and inline forms
+ * (`--output=file`). Useful for simple boolean flag checks inside command
+ * `run` handlers.
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns `true` if at least one flag is present, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * ifFlag(args, "-r")              // single flag
+ * ifFlag(args, ["-r", "--recursive"]) // aliases
+ * ```
+ */
 export function ifFlag(args, flags) {
     const allFlags = toFlagList(flags);
     for (const arg of args) {
@@ -65,6 +82,25 @@ export function ifFlag(args, flags) {
     }
     return false;
 }
+/**
+ * Returns the value associated with a flag, or `true` if the flag is present
+ * but has no associated value, or `undefined` if the flag is absent.
+ *
+ * Handles three forms:
+ * - `--output file`   → returns `"file"` (next token)
+ * - `--output=file`   → returns `"file"` (inline `=` form)
+ * - `--verbose`       → returns `true` (flag with no value)
+ *
+ * @param args  Tokenized argument array from `CommandContext.args`.
+ * @param flags Single flag string or array of equivalent flag strings.
+ * @returns The flag value string, `true` when valueless, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const output = getFlag(args, ["-o", "--output"]);
+ * if (typeof output === "string") { /* use path *\/ }
+ * ```
+ */
 export function getFlag(args, flags) {
     const allFlags = toFlagList(flags);
     for (let index = 0; index < args.length; index += 1) {
@@ -86,15 +122,53 @@ export function getFlag(args, flags) {
     }
     return undefined;
 }
+/**
+ * Returns the positional argument at the given zero-based index, skipping
+ * known flags and their values.
+ *
+ * Flags declared in `options.flags` are treated as boolean and skipped.
+ * Flags declared in `options.flagsWithValue` consume the next token too.
+ * Tokens after `--` are always treated as positionals.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param index   Zero-based positional index to retrieve.
+ * @param options Optional flag declarations to skip during positional collection.
+ * @returns The positional value, or `undefined` if the index is out of range.
+ *
+ * @example
+ * ```ts
+ * // args = ["-r", "src", "dest"]
+ * getArg(args, 0, { flags: ["-r"] }) // "src"
+ * getArg(args, 1, { flags: ["-r"] }) // "dest"
+ * ```
+ */
 export function getArg(args, index, options = {}) {
     const positionals = collectPositionals(args, options);
     return positionals[index];
 }
 /**
- * Parse arguments into flags, flags with values, and positionals.
- * @param args - Array of arguments to parse.
- * @param options - Parsing options for flags and flags with values.
- * @returns Parsed arguments as { flags, flagsWithValues, positionals }.
+ * Parses an argument array into structured flags, flag values, and positionals.
+ *
+ * - `options.flags` — boolean flags (e.g. `["-r", "--recursive"]`); collected
+ *   into a `Set<string>` and not treated as positionals.
+ * - `options.flagsWithValue` — flags that consume the next token or an inline
+ *   `=value`; collected into a `Map<string, string>`.
+ * - All remaining tokens are positionals.
+ * - Tokens after `--` are always positionals, regardless of `-` prefix.
+ *
+ * @param args    Tokenized argument array from `CommandContext.args`.
+ * @param options Flag declaration lists.
+ * @returns `{ flags, flagsWithValues, positionals }`.
+ *
+ * @example
+ * ```ts
+ * const { flags, flagsWithValues, positionals } = parseArgs(args, {
+ *   flags:          ["-r", "--recursive"],
+ *   flagsWithValue: ["-o", "--output"],
+ * });
+ * const recursive = flags.has("-r");
+ * const output    = flagsWithValues.get("-o");
+ * ```
  */
 export function parseArgs(args, options = {}) {
     const flags = new Set();

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

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