@poe-platform/safe-bash 0.1.629 → 0.1.631

package/dist/safe-bash/opt-in/commands/install/mode.js

@@ -0,0 +1,71 @@
+import { InstallError, quote } from "./options.js";
+export function parseMode(text, rawBytes) {
+    if (text === undefined)
+        return { file: 0o755, directory: 0o755, directoryMask: 0o7777 };
+    const invalid = () => new InstallError(`invalid mode ${quote(text, true, rawBytes)}`);
+    const numeric = "+-=".includes(text[0] ?? "!") ? text.slice(1) : text;
+    if (numeric && Array.from(numeric).every(character => character >= "0" && character <= "7")) {
+        const bits = Number.parseInt(numeric, 8);
+        if (bits > 0o7777 || !Number.isSafeInteger(bits))
+            throw invalid();
+        const subtract = text[0] === "-";
+        return { file: subtract ? 0 : bits, directory: subtract ? 0 : bits, directoryMask: text[0] === "+" || subtract ? bits : 0o7777 };
+    }
+    let file = 0, directory = 0, directoryMask = 0;
+    for (const clause of text.split(",")) {
+        let offset = 0, who = "";
+        while (offset < clause.length && "ugoa".includes(clause[offset]))
+            who += clause[offset++];
+        const all = !who || who.includes("a");
+        const users = (all || who.includes("u") ? 0o4700 : 0) | (all || who.includes("g") ? 0o2070 : 0) | (all || who.includes("o") ? 0o1007 : 0);
+        if (offset === clause.length)
+            throw invalid();
+        while (offset < clause.length) {
+            const operator = clause[offset++];
+            if (!"+-=".includes(operator))
+                throw invalid();
+            let permissions = "";
+            while (offset < clause.length && !"+-=".includes(clause[offset]))
+                permissions += clause[offset++];
+            const copy = permissions.length === 1 && "ugo".includes(permissions);
+            if (!copy && !Array.from(permissions).every(character => "rwxXst".includes(character)))
+                throw invalid();
+            const bitsFor = (current, isDirectory) => {
+                let bits = 0;
+                if (copy) {
+                    const shift = permissions === "u" ? 6 : permissions === "g" ? 3 : 0;
+                    const value = current >> shift & 7;
+                    bits = value << 6 | value << 3 | value;
+                }
+                else {
+                    if (permissions.includes("r"))
+                        bits |= 0o444;
+                    if (permissions.includes("w"))
+                        bits |= 0o222;
+                    if (permissions.includes("x") || permissions.includes("X") && (isDirectory || (current & 0o111) !== 0))
+                        bits |= 0o111;
+                    if (permissions.includes("s"))
+                        bits |= 0o6000;
+                    if (permissions.includes("t"))
+                        bits |= 0o1000;
+                }
+                return bits & users;
+            };
+            const fileBits = bitsFor(file, false), directoryBits = bitsFor(directory, true);
+            if (operator === "+") {
+                file |= fileBits;
+                directory |= directoryBits;
+            }
+            else if (operator === "-") {
+                file &= ~fileBits;
+                directory &= ~directoryBits;
+            }
+            else {
+                file = file & ~users | fileBits;
+                directory = directory & ~users | directoryBits;
+            }
+            directoryMask |= operator === "=" ? users : directoryBits;
+        }
+    }
+    return { file, directory, directoryMask };
+}

package/dist/safe-bash/opt-in/commands/install/options.d.ts

@@ -0,0 +1,36 @@
+import type { CommandContext } from "@poe-platform/safe-bash/contracts/index";
+export interface InstallContextRequest {
+    readonly path: string;
+    readonly source?: string;
+    readonly label?: string;
+    readonly mode: "default" | "preserve" | "explicit";
+}
+export interface InstallModeRequest {
+    readonly path: string;
+    readonly mode: number;
+    readonly kind: "file" | "new-directory" | "existing-directory";
+}
+export interface InstallCommandsOptions {
+    readonly replace?: boolean;
+    readonly identity?: {
+        readonly uid: number;
+        readonly gid: number;
+    };
+    readonly resolveUser?: (name: string, context: CommandContext) => number | undefined | Promise<number | undefined>;
+    readonly resolveGroup?: (name: string, context: CommandContext) => number | undefined | Promise<number | undefined>;
+    readonly chown?: (path: string, uid: number | undefined, gid: number | undefined, context: CommandContext) => void | Promise<void>;
+    readonly setMode?: (request: InstallModeRequest, context: CommandContext) => void | Promise<void>;
+    readonly strip?: (path: string, program: string, context: CommandContext) => number | Promise<number>;
+    readonly renameExclusive?: (source: string, destination: string, context: CommandContext) => void | Promise<void>;
+    readonly maxFileBytes?: number;
+    readonly securityContext?: {
+        readonly enabled: boolean;
+        readonly apply?: (request: InstallContextRequest, context: CommandContext) => void | Promise<void>;
+        readonly matches?: (source: string, destination: string, context: CommandContext) => boolean | Promise<boolean>;
+    };
+}
+export declare class InstallError extends Error {
+    readonly usage: boolean;
+    constructor(message: string, usage?: boolean);
+}
+export declare function quote(value: string, numeric?: boolean, rawBytes?: Uint8Array): string;

package/dist/safe-bash/opt-in/commands/install/options.js

@@ -0,0 +1,27 @@
+export class InstallError extends Error {
+    usage;
+    constructor(message, usage = false) {
+        super(message);
+        this.usage = usage;
+    }
+}
+export function quote(value, numeric = false, rawBytes) {
+    const escapes = new Map([[7, "a"], [8, "b"], [9, "t"], [10, "n"], [11, "v"], [12, "f"], [13, "r"]]);
+    const bytes = rawBytes ?? new TextEncoder().encode(value);
+    if (!numeric && bytes.every(byte => byte >= 32 && byte < 127)) {
+        return value.includes("'") && !["\"", "$", "`", "\\"].some(character => value.includes(character))
+            ? `"${value}"` : `'${value.replaceAll("'", "'\\''")}'`;
+    }
+    let result = "'", escaped = false;
+    for (const byte of bytes) {
+        const special = byte < 32 || byte >= 127;
+        if (!numeric && special !== escaped) {
+            result += special ? "'$'" : "''";
+            escaped = special;
+        }
+        result += special ? `\\${escapes.get(byte) ?? byte.toString(8).padStart(3, "0")}`
+            : numeric && (byte === 39 || byte === 92) ? `\\${String.fromCharCode(byte)}`
+                : byte === 39 ? "'\\''" : String.fromCharCode(byte);
+    }
+    return `${result}'`;
+}

package/dist/safe-bash/opt-in/commands/shuf/args.js

@@ -0,0 +1,179 @@
+import { getCommandArguments } from "@poe-platform/safe-bash/contracts/index";
+export const wordMax = (1n << 64n) - 1n;
+export const countMax = (1n << 63n) - 1n;
+export class Diagnostic extends Error {
+    bytes;
+    constructor(message, bytes) {
+        super(message);
+        this.bytes = bytes;
+    }
+}
+export function quote(value) {
+    let result = "'";
+    const escapes = { "\n": "\\n", "\r": "\\r", "\t": "\\t", "\b": "\\b", "\f": "\\f", "\v": "\\v", "\u0007": "\\a", "\\": "\\\\", "'": "\\'" };
+    for (const code of typeof value === "string" ? Buffer.from(value) : value) {
+        const character = String.fromCharCode(code);
+        result += escapes[character] ?? (code < 32 || code >= 127 ? `\\${code.toString(8).padStart(3, "0")}` : character);
+    }
+    return `${result}'`;
+}
+export function fileQuote(value) {
+    if (value && value !== "{" && value !== "}" && !"#~".includes(value[0]) && Array.from(value).every(character => "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_+-./,%#@]{}~".includes(character)))
+        return value;
+    if (!value.includes("'") && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127))
+        return `'${value}'`;
+    if (value.includes("'") && !Array.from(value).some(character => "\"\\$`".includes(character) || character.charCodeAt(0) < 32 || character.charCodeAt(0) >= 127))
+        return `"${value}"`;
+    let result = "'";
+    let escaped = false;
+    for (const code of Buffer.from(value)) {
+        const character = String.fromCharCode(code);
+        const control = code < 32 || code >= 127;
+        if (control !== escaped) {
+            result += control ? "'$'" : "''";
+            escaped = control;
+        }
+        result += control ? code >= 127 ? `\\${code.toString(8).padStart(3, "0")}` : quote(character).slice(1, -1) : character === "'" ? "'\\''" : character;
+    }
+    return `${result}'`;
+}
+function usage(message) {
+    throw new Diagnostic(`shuf: ${message}\nTry 'shuf --help' for more information.\n`);
+}
+function unsigned(value, start = 0) {
+    let cursor = start;
+    while (cursor < value.length && " \t\n\r\v\f".includes(value[cursor]))
+        cursor++;
+    if (value[cursor] === "+")
+        cursor++;
+    const first = cursor;
+    let number = 0n;
+    while (cursor < value.length && value[cursor] >= "0" && value[cursor] <= "9") {
+        if (number <= wordMax)
+            number = number * 10n + BigInt(value[cursor]);
+        cursor++;
+    }
+    return { number, cursor, valid: cursor > first, overflow: number > wordMax };
+}
+const longOptions = ["echo", "input-range", "head-count", "output", "random-source", "repeat", "zero-terminated", "help", "version"];
+export function parse(context) {
+    const result = {
+        echo: false, repeat: false, delimiter: 10, count: countMax,
+        range: undefined,
+        output: undefined, random: undefined,
+        action: undefined, operands: [],
+    };
+    const apply = (option, value, valueIndex, valueOffset) => {
+        switch (option) {
+            case "e":
+                result.echo = true;
+                break;
+            case "r":
+                result.repeat = true;
+                break;
+            case "z":
+                result.delimiter = 0;
+                break;
+            case "i": {
+                if (result.range)
+                    throw new Diagnostic("shuf: multiple -i options specified\n");
+                const low = unsigned(value);
+                const high = unsigned(value, low.cursor + 1);
+                const overflow = low.overflow || low.valid && value[low.cursor] === "-" && high.overflow && high.cursor === value.length;
+                const size = high.number - low.number + 1n;
+                if (!low.valid || !high.valid || value[low.cursor] !== "-" || high.cursor !== value.length || overflow || size < 0n || size > wordMax) {
+                    throw new Diagnostic(`shuf: invalid input range: ${quote(value)}${overflow ? ": Value too large to be stored in data type" : ""}\n`);
+                }
+                result.range = { low: low.number, size };
+                break;
+            }
+            case "n": {
+                const parsed = unsigned(value);
+                if (!parsed.valid || parsed.cursor !== value.length) {
+                    throw new Diagnostic(`shuf: invalid line count: ${quote(getCommandArguments(context).bytes(valueIndex).subarray(valueOffset))}\n`);
+                }
+                if (!parsed.overflow && parsed.number < result.count)
+                    result.count = parsed.number;
+                break;
+            }
+            case "o":
+                if (result.output !== undefined && result.output !== value)
+                    throw new Diagnostic("shuf: multiple output files specified\n");
+                result.output = value;
+                break;
+            case "random-source":
+                if (result.random !== undefined && result.random !== value)
+                    throw new Diagnostic("shuf: multiple random sources specified\n");
+                result.random = value;
+                break;
+            case "help":
+            case "version":
+                result.action = option;
+                break;
+        }
+    };
+    let ended = false;
+    for (let index = 0; index < context.args.length; index++) {
+        context.signal.throwIfAborted();
+        const argument = context.args[index];
+        if (ended || argument === "-" || !argument.startsWith("-")) {
+            result.operands.push(index);
+            if (Object.hasOwn(context.env, "POSIXLY_CORRECT"))
+                ended = true;
+        }
+        else if (argument === "--")
+            ended = true;
+        else if (argument.startsWith("--")) {
+            const equal = argument.indexOf("=");
+            const name = argument.slice(2, equal < 0 ? undefined : equal);
+            const matches = longOptions.includes(name) ? [name] : longOptions.filter(option => option.startsWith(name));
+            if (!matches.length)
+                usage(`unrecognized option '${argument}'`);
+            if (matches.length > 1)
+                usage(`option '${argument}' is ambiguous; possibilities:${matches.map(option => ` '--${option}'`).join("")}`);
+            const option = matches[0];
+            const required = ["input-range", "head-count", "output", "random-source"].includes(option);
+            if (!required && equal >= 0)
+                usage(`option '--${option}' doesn't allow an argument`);
+            let value = equal < 0 ? "" : argument.slice(equal + 1);
+            if (required && equal < 0) {
+                if (++index >= context.args.length)
+                    usage(`option '--${option}' requires an argument`);
+                value = context.args[index];
+            }
+            const short = { echo: "e", "input-range": "i", "head-count": "n", output: "o", repeat: "r", "zero-terminated": "z" };
+            apply(short[option] ?? option, value, index, equal < 0 ? 0 : equal + 1);
+        }
+        else {
+            for (let cursor = 1; cursor < argument.length; cursor++) {
+                const option = argument[cursor];
+                if (!"einorz".includes(option)) {
+                    const byte = getCommandArguments(context).bytes(index)[cursor];
+                    const bytes = Buffer.concat([Buffer.from("shuf: invalid option -- '"), Buffer.from([byte]), Buffer.from("'\nTry 'shuf --help' for more information.\n")]);
+                    throw new Diagnostic(bytes.toString(), bytes);
+                }
+                let value = "";
+                let valueOffset = cursor + 1;
+                if ("ino".includes(option)) {
+                    value = argument.slice(cursor + 1);
+                    if (!value) {
+                        if (++index >= context.args.length)
+                            usage(`option requires an argument -- '${option}'`);
+                        value = context.args[index];
+                        valueOffset = 0;
+                    }
+                    cursor = argument.length;
+                }
+                apply(option, value, index, valueOffset);
+            }
+        }
+        if (result.action)
+            return result;
+    }
+    if (result.echo && result.range)
+        usage("cannot combine -e and -i options");
+    if (result.range ? result.operands.length > 0 : !result.echo && result.operands.length > 1) {
+        usage(`extra operand ${quote(context.args[result.operands[result.range ? 0 : 1]])}`);
+    }
+    return result;
+}

package/dist/safe-bash/opt-in/commands/shuf/index.d.ts

@@ -0,0 +1,6 @@
+import type { CommandDefinition, VirtualShellPlugin } from "@poe-platform/safe-bash/contracts/index";
+import type { ShufCommandsOptions } from "./options.js";
+export { createShufCommand } from "./shuf.js";
+export type { ShufCommandsOptions } from "./options.js";
+export declare function createShufCommands(options?: ShufCommandsOptions): readonly CommandDefinition[];
+export declare function shufCommands(options?: ShufCommandsOptions): VirtualShellPlugin;

package/dist/safe-bash/opt-in/commands/shuf/index.js

@@ -0,0 +1,20 @@
+import { createShufCommand } from "./shuf.js";
+export { createShufCommand } from "./shuf.js";
+export function createShufCommands(options = {}) {
+    return Object.freeze([createShufCommand(options)]);
+}
+export function shufCommands(options = {}) {
+    const commands = createShufCommands(options);
+    return {
+        name: "shuf-commands",
+        setup(host) {
+            if (!options.replace)
+                for (const command of commands) {
+                    if (host.commands.has(command.name))
+                        throw new Error(`Command already registered: ${command.name}`);
+                }
+            for (const command of commands)
+                host.commands.register(command, { replace: options.replace ?? false });
+        },
+    };
+}

package/dist/safe-bash/opt-in/commands/shuf/input.js

@@ -0,0 +1,93 @@
+import { FsError, readBytes } from "@poe-platform/safe-bash/contracts/index";
+import { yieldTurn } from "@poe-platform/safe-bash/contracts/yield";
+import { Diagnostic } from "./args.js";
+export function virtualPath(cwd, name) {
+    if (name === "")
+        throw new FsError("ENOENT");
+    return name.startsWith("/") ? name : `${cwd.endsWith("/") ? cwd : `${cwd}/`}${name}`;
+}
+export function ownedBytes(source, signal) {
+    const iterator = source[Symbol.asyncIterator]();
+    const controller = new AbortController();
+    const readingSignal = AbortSignal.any([signal, controller.signal]);
+    let finished = false;
+    let closing;
+    const close = () => {
+        controller.abort(new Error("shuf input is closed"));
+        return closing ??= Promise.resolve().then(async () => {
+            if (!finished && iterator.return)
+                return iterator.return();
+            return { done: true, value: undefined };
+        });
+    };
+    const tracked = {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    const next = await iterator.next();
+                    finished = next.done === true;
+                    return next;
+                },
+                return: close,
+            };
+        },
+    };
+    const stream = (async function* () {
+        let chunks = 0;
+        try {
+            for await (const chunk of readBytes(tracked, readingSignal)) {
+                yield chunk;
+                if (++chunks % 1024 === 0)
+                    await yieldTurn(readingSignal);
+            }
+        }
+        finally {
+            await close();
+        }
+    })();
+    return {
+        [Symbol.asyncIterator]() { return this; },
+        async [Symbol.asyncDispose]() { await close(); await stream.return(undefined); },
+        next: stream.next.bind(stream),
+        async return(value) { await close(); return stream.return(value); },
+        async throw(reason) { controller.abort(reason); await close(); return stream.throw(reason); },
+    };
+}
+export async function* records(source, delimiter, limit, signal) {
+    let pending = new Uint8Array(Math.min(256, limit));
+    let used = 0;
+    let scanned = 0;
+    for await (const chunk of source) {
+        let start = 0;
+        while (start < chunk.length) {
+            signal.throwIfAborted();
+            const boundary = chunk.indexOf(delimiter, start);
+            const end = boundary < 0 ? chunk.length : boundary + 1;
+            const needed = used + end - start;
+            if (needed > limit)
+                throw new Diagnostic("shuf: maxInputBytes limit exceeded\n");
+            if (pending.length < needed) {
+                const grown = new Uint8Array(Math.min(limit, Math.max(needed, pending.length * 2)));
+                grown.set(pending.subarray(0, used));
+                pending = grown;
+            }
+            pending.set(chunk.subarray(start, end), used);
+            used = needed;
+            start = end;
+            if (boundary >= 0) {
+                yield pending.slice(0, used);
+                used = 0;
+            }
+            if (++scanned % 1024 === 0)
+                await yieldTurn(signal);
+        }
+    }
+    if (used) {
+        if (used >= limit)
+            throw new Diagnostic("shuf: maxInputBytes limit exceeded\n");
+        const last = new Uint8Array(used + 1);
+        last.set(pending.subarray(0, used));
+        last[used] = delimiter;
+        yield last;
+    }
+}

package/dist/safe-bash/opt-in/commands/shuf/options.d.ts

@@ -0,0 +1,9 @@
+export interface ShufCommandsOptions {
+    readonly replace?: boolean;
+    readonly maxInputBytes?: number;
+    readonly maxSampleSize?: number;
+}
+export declare function settings(options: ShufCommandsOptions): Readonly<{
+    maxInputBytes: number;
+    maxSampleSize: number;
+}>;

package/dist/safe-bash/opt-in/commands/shuf/options.js

@@ -0,0 +1,8 @@
+export function settings(options) {
+    const limits = { maxInputBytes: options.maxInputBytes ?? 64 * 1024 * 1024, maxSampleSize: options.maxSampleSize ?? 1_000_000 };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new RangeError(`Invalid shuf ${name}`);
+    }
+    return Object.freeze(limits);
+}

package/dist/safe-bash/opt-in/commands/shuf/random.js

@@ -0,0 +1,114 @@
+import { randomFillSync } from "node:crypto";
+import { yieldTurn } from "@poe-platform/safe-bash/contracts/yield";
+import { Diagnostic, quote, wordMax } from "./args.js";
+import { ownedBytes, virtualPath } from "./input.js";
+export class RandomIntegers {
+    context;
+    name;
+    maxBytes;
+    value = 0n;
+    maximum = 0n;
+    bytes = new Uint8Array();
+    offset = 0;
+    source;
+    closed = false;
+    closing;
+    opening;
+    controller = new AbortController();
+    signal;
+    constructor(context, name, maxBytes = 64 * 1024 * 1024) {
+        this.context = context;
+        this.name = name;
+        this.maxBytes = maxBytes;
+        this.signal = AbortSignal.any([context.signal, this.controller.signal]);
+        context.registerCleanup?.(() => this.close());
+    }
+    open() {
+        if (this.closed)
+            return Promise.reject(this.signal.reason);
+        return this.opening ??= Promise.resolve().then(async () => {
+            const { fs } = this.context;
+            const signal = this.signal;
+            signal.throwIfAborted();
+            if (this.name === undefined)
+                return;
+            const path = virtualPath(this.context.cwd, this.name);
+            await fs.access(path, 4, { signal });
+            signal.throwIfAborted();
+            if (fs.readStream)
+                this.source = ownedBytes(fs.readStream(path, { signal, chunkSize: Math.min(4096, this.maxBytes) }), signal);
+            else {
+                const maxBytes = this.maxBytes;
+                this.source = ownedBytes((async function* () {
+                    const bytes = await fs.readFile(path, { signal, maxBytes });
+                    if (bytes.byteLength > maxBytes)
+                        throw new Diagnostic("shuf: maxInputBytes limit exceeded\n");
+                    yield bytes;
+                })(), signal);
+            }
+            signal.throwIfAborted();
+        });
+    }
+    async close() {
+        this.closed = true;
+        this.controller.abort(new Error("shuf random source is closed"));
+        return this.closing ??= (async () => {
+            await this.opening?.catch(() => { });
+            await this.source?.return(undefined);
+            this.bytes.fill(0);
+            this.value = this.maximum = 0n;
+        })();
+    }
+    async byte() {
+        this.signal.throwIfAborted();
+        if (this.closed)
+            throw new Error("shuf random source is closed");
+        while (this.offset === this.bytes.length) {
+            if (this.source) {
+                const next = await this.source.next();
+                this.signal.throwIfAborted();
+                if (next.done)
+                    throw new Diagnostic(`shuf: ${quote(this.name)}: end of file\n`);
+                if (next.value.byteLength > this.maxBytes)
+                    throw new Diagnostic("shuf: maxInputBytes limit exceeded\n");
+                this.bytes = new Uint8Array(next.value);
+            }
+            else {
+                this.bytes = randomFillSync(new Uint8Array(4096));
+            }
+            this.offset = 0;
+            this.signal.throwIfAborted();
+        }
+        return this.bytes[this.offset++];
+    }
+    async choose(size) {
+        if (size < 1n || size > wordMax)
+            throw new RangeError("shuf choice size out of range");
+        const target = size - 1n;
+        let attempts = 0;
+        while (true) {
+            this.signal.throwIfAborted();
+            if (++attempts % 256 === 0)
+                await yieldTurn(this.signal);
+            while (this.maximum < target) {
+                this.value = ((this.value << 8n) + BigInt(await this.byte())) & wordMax;
+                this.maximum = ((this.maximum << 8n) + 255n) & wordMax;
+            }
+            if (this.maximum === target) {
+                const chosen = this.value;
+                this.value = this.maximum = 0n;
+                return chosen;
+            }
+            const excess = this.maximum - target;
+            const unusable = excess % size;
+            const remainder = this.value % size;
+            if (this.value <= this.maximum - unusable) {
+                this.value /= size;
+                this.maximum = excess / size;
+                return remainder;
+            }
+            this.value = remainder;
+            this.maximum = unusable - 1n;
+        }
+    }
+}

package/dist/safe-bash/opt-in/commands/shuf/shuf.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDefinition } from "@poe-platform/safe-bash/contracts/index";
+import { type ShufCommandsOptions } from "./options.js";
+export declare function createShufCommand(options?: ShufCommandsOptions): CommandDefinition;