@hyperbrowser/sdk 0.92.7 → 1.0.0

package/dist/sandbox/image-build/dockerfile-analysis.js

@@ -0,0 +1,409 @@
+"use strict";
+/**
+ * Conservative Dockerfile analysis for remote build context selection.
+ *
+ * This module intentionally does not try to execute or fully reproduce the
+ * BuildKit Dockerfile frontend. It recognizes the context-consuming syntax the
+ * SDK can analyze safely and requests a full context for anything ambiguous.
+ * That keeps sparse uploads an optimization rather than a correctness
+ * requirement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeDockerfileSources = exports.shlexSplit = void 0;
+const KNOWN_INSTRUCTIONS = new Set([
+    "ADD",
+    "ARG",
+    "CMD",
+    "COPY",
+    "ENTRYPOINT",
+    "ENV",
+    "EXPOSE",
+    "FROM",
+    "HEALTHCHECK",
+    "LABEL",
+    "MAINTAINER",
+    "ONBUILD",
+    "RUN",
+    "SHELL",
+    "STOPSIGNAL",
+    "USER",
+    "VOLUME",
+    "WORKDIR",
+]);
+const KNOWN_RUN_FLAGS = new Set(["device", "mount", "network", "security"]);
+const INSTRUCTION_PATTERN = /^([A-Za-z]+)(?:[ \t]+(.*))?$/s;
+const DIRECTIVE_PATTERN = /^\s*#\s*(escape|syntax)\s*=\s*(\S+)/gim;
+const FLAG_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const SCP_GIT_SOURCE_PATTERN = /^git@[^:/\s]+:.+/;
+// Python splitlines includes these control separators.
+// eslint-disable-next-line no-control-regex
+const LINE_SEPARATOR_PATTERN = /\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/;
+class AnalysisFallback extends Error {
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+class ParseError extends Error {
+}
+/** Python `str.strip()` semantics: a UTF-8 BOM is not whitespace and must not be trimmed. */
+const stripWhitespace = (value) => value.replace(/^(?:(?!\ufeff)\s)+|(?:(?!\ufeff)\s)+$/g, "");
+/** POSIX `shlex.split` word splitting. */
+const shlexSplit = (value) => {
+    const words = [];
+    let current = "";
+    let inWord = false;
+    let quote = null;
+    let index = 0;
+    while (index < value.length) {
+        const character = value[index];
+        index += 1;
+        if (quote === "'") {
+            if (character === "'") {
+                quote = null;
+            }
+            else {
+                current += character;
+            }
+            continue;
+        }
+        if (quote === '"') {
+            if (character === '"') {
+                quote = null;
+            }
+            else if (character === "\\") {
+                if (index >= value.length) {
+                    throw new ParseError("No escaped character");
+                }
+                const escaped = value[index];
+                index += 1;
+                if (escaped === '"' || escaped === "\\") {
+                    current += escaped;
+                }
+                else {
+                    current += "\\" + escaped;
+                }
+            }
+            else {
+                current += character;
+            }
+            continue;
+        }
+        if (character === "\\") {
+            if (index >= value.length) {
+                throw new ParseError("No escaped character");
+            }
+            current += value[index];
+            index += 1;
+            inWord = true;
+        }
+        else if (character === '"' || character === "'") {
+            quote = character;
+            inWord = true;
+        }
+        else if (/\s/.test(character)) {
+            if (inWord) {
+                words.push(current);
+                current = "";
+                inWord = false;
+            }
+        }
+        else {
+            current += character;
+            inWord = true;
+        }
+    }
+    if (quote !== null) {
+        throw new ParseError("No closing quotation");
+    }
+    if (inWord) {
+        words.push(current);
+    }
+    return words;
+};
+exports.shlexSplit = shlexSplit;
+const isOfficialDockerfileFrontend = (reference) => {
+    let normalized = reference.trim();
+    if (normalized.startsWith("docker-image://")) {
+        normalized = normalized.slice("docker-image://".length);
+    }
+    normalized = normalized.split("@", 1)[0];
+    const lastSlash = normalized.lastIndexOf("/");
+    const lastColon = normalized.lastIndexOf(":");
+    if (lastColon > lastSlash) {
+        normalized = normalized.slice(0, lastColon);
+    }
+    return new Set([
+        "docker/dockerfile",
+        "docker.io/docker/dockerfile",
+        "index.docker.io/docker/dockerfile",
+        "docker/dockerfile-upstream",
+        "docker.io/docker/dockerfile-upstream",
+        "index.docker.io/docker/dockerfile-upstream",
+    ]).has(normalized);
+};
+const isRemoteAddSource = (source) => {
+    if (SCP_GIT_SOURCE_PATTERN.test(source)) {
+        return true;
+    }
+    return ["http://", "https://", "git://", "ssh://"].some((prefix) => source.startsWith(prefix));
+};
+const sourceHasPattern = (source) => source.includes("*") || source.includes("?") || source.includes("[");
+const takeWord = (value) => {
+    let quote = null;
+    let escaped = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote !== null) {
+            if (character === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (/\s/.test(character)) {
+            return [value.slice(0, index), value.slice(index)];
+        }
+    }
+    if (quote !== null || escaped) {
+        throw new ParseError("unterminated Dockerfile instruction word");
+    }
+    return [value, ""];
+};
+const splitLeadingFlags = (body) => {
+    const flags = [];
+    let remaining = body.trimStart();
+    while (remaining.startsWith("--")) {
+        const [rawToken, rest] = takeWord(remaining);
+        remaining = rest;
+        const decoded = (0, exports.shlexSplit)(rawToken);
+        if (decoded.length !== 1 || !decoded[0].startsWith("--")) {
+            throw new ParseError("invalid Dockerfile instruction flag");
+        }
+        const flag = decoded[0].slice(2);
+        const separator = flag.indexOf("=");
+        const key = (separator === -1 ? flag : flag.slice(0, separator)).toLowerCase();
+        const value = separator === -1 ? "" : flag.slice(separator + 1);
+        if (!FLAG_NAME_PATTERN.test(key)) {
+            throw new ParseError("invalid Dockerfile instruction flag");
+        }
+        if (key === "mount" && (rawToken.includes('"') || rawToken.includes("'"))) {
+            // BuildKit parses mount values as CSV after Dockerfile word processing.
+            // Quoted CSV values are deliberately outside the subset implemented here.
+            throw new ParseError("quoted RUN mount requires full context");
+        }
+        flags.push([key, value]);
+        remaining = remaining.trimStart();
+    }
+    return [flags, remaining];
+};
+const parseCopyAddValues = (body) => {
+    const [parsedFlags, remaining] = splitLeadingFlags(body);
+    const flags = new Map(parsedFlags);
+    let values;
+    if (remaining.startsWith("[")) {
+        const parsed = JSON.parse(remaining);
+        if (!Array.isArray(parsed) || !parsed.every((value) => typeof value === "string")) {
+            throw new ParseError("invalid JSON COPY/ADD");
+        }
+        values = parsed;
+    }
+    else {
+        if (remaining.includes("\\")) {
+            // BuildKit's shell-form COPY/ADD word splitting is not POSIX shlex.
+            // Backslash-containing forms use the full context rather than risk
+            // selecting a different set of sources.
+            throw new ParseError("escaped shell COPY/ADD requires full context");
+        }
+        values = (0, exports.shlexSplit)(remaining);
+    }
+    if (values.length < 2) {
+        throw new ParseError("COPY/ADD is missing source or destination");
+    }
+    return [flags, values];
+};
+const parseMountOptions = (value) => {
+    const options = new Map();
+    for (const field of value.split(",")) {
+        const separator = field.indexOf("=");
+        const key = (separator === -1 ? field : field.slice(0, separator)).trim().toLowerCase();
+        if (!key) {
+            throw new AnalysisFallback("run_mount_parse_failed");
+        }
+        options.set(key, separator === -1 ? "" : field.slice(separator + 1).trim());
+    }
+    return options;
+};
+const parseInstruction = (line) => {
+    const match = INSTRUCTION_PATTERN.exec(line);
+    if (match === null) {
+        throw new AnalysisFallback("dockerfile_parse_failed");
+    }
+    return [match[1].toUpperCase(), match[2] || ""];
+};
+const validateParserDirectives = (text) => {
+    for (const match of text.matchAll(DIRECTIVE_PATTERN)) {
+        const name = match[1].toLowerCase();
+        const value = match[2];
+        if (name === "escape" && value !== "\\") {
+            throw new AnalysisFallback("dockerfile_parse_failed");
+        }
+        if (name === "syntax" && !isOfficialDockerfileFrontend(value)) {
+            throw new AnalysisFallback("custom_dockerfile_frontend");
+        }
+    }
+};
+const logicalLines = (text) => {
+    const lines = [];
+    let parts = [];
+    const rawLines = text.split(LINE_SEPARATOR_PATTERN);
+    if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+        rawLines.pop();
+    }
+    for (const rawLine of rawLines) {
+        const stripped = stripWhitespace(rawLine);
+        if (parts.length === 0 && (!stripped || stripped.startsWith("#"))) {
+            continue;
+        }
+        if (parts.length > 0 && (!stripped || stripped.startsWith("#"))) {
+            // BuildKit has nuanced rules for comments and empty lines in a
+            // continuation. Full context is the safe answer here.
+            throw new AnalysisFallback("dockerfile_parse_failed");
+        }
+        if (stripped.endsWith("\\")) {
+            parts.push(stripped.slice(0, -1).trimEnd());
+            continue;
+        }
+        parts.push(stripped);
+        lines.push(parts.join(" "));
+        parts = [];
+    }
+    if (parts.length > 0) {
+        throw new AnalysisFallback("dockerfile_parse_failed");
+    }
+    return lines;
+};
+const analyzeCopyOrAdd = (instruction, body) => {
+    let flags;
+    let values;
+    try {
+        [flags, values] = parseCopyAddValues(body);
+    }
+    catch (error) {
+        if (error instanceof ParseError || error instanceof SyntaxError) {
+            throw new AnalysisFallback("dockerfile_instruction_parse_failed");
+        }
+        throw error;
+    }
+    if (instruction === "COPY" && flags.has("from")) {
+        return [];
+    }
+    const localSources = [];
+    for (const source of values.slice(0, -1)) {
+        if (source.includes("$") || source.includes("\x00")) {
+            throw new AnalysisFallback(instruction === "COPY" ? "copy_source_requires_expansion" : "add_source_requires_expansion");
+        }
+        if (source.includes("\\")) {
+            // A backslash is a path character on Unix but a separator on Windows.
+            // Full context keeps selection platform-independent.
+            throw new AnalysisFallback("dockerfile_source_path");
+        }
+        if (instruction === "ADD" && isRemoteAddSource(source)) {
+            continue;
+        }
+        if (sourceHasPattern(source)) {
+            throw new AnalysisFallback("dockerfile_source_pattern");
+        }
+        localSources.push(source);
+    }
+    return localSources;
+};
+const analyzeRun = (body) => {
+    let flags;
+    try {
+        [flags] = splitLeadingFlags(body);
+    }
+    catch (error) {
+        if (error instanceof ParseError) {
+            throw new AnalysisFallback("run_mount_parse_failed");
+        }
+        throw error;
+    }
+    const groups = [];
+    for (const [name, value] of flags) {
+        if (!KNOWN_RUN_FLAGS.has(name)) {
+            throw new AnalysisFallback("dockerfile_instruction_parse_failed");
+        }
+        if (name !== "mount") {
+            continue;
+        }
+        if (!value || value.includes('"') || value.includes("'")) {
+            throw new AnalysisFallback("run_mount_parse_failed");
+        }
+        const options = parseMountOptions(value);
+        if ((options.get("type") ?? "bind") !== "bind" || options.get("from")) {
+            continue;
+        }
+        const source = options.get("source") || options.get("src") || ".";
+        if (source.includes("$") || source.includes("\x00")) {
+            throw new AnalysisFallback("run_bind_source_requires_expansion");
+        }
+        groups.push([source]);
+    }
+    return groups;
+};
+const analyzeLines = (lines) => {
+    const groups = [];
+    for (const line of lines) {
+        const [instruction, body] = parseInstruction(line);
+        if (!KNOWN_INSTRUCTIONS.has(instruction)) {
+            throw new AnalysisFallback("dockerfile_instruction_parse_failed");
+        }
+        if (instruction === "COPY" || instruction === "ADD") {
+            const group = analyzeCopyOrAdd(instruction, body);
+            if (group.length > 0) {
+                groups.push(group);
+            }
+        }
+        else if (instruction === "RUN") {
+            groups.push(...analyzeRun(body));
+        }
+    }
+    return groups;
+};
+/** Return local source groups or a reason to upload the full context. */
+const analyzeDockerfileSources = (data) => {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(data);
+    }
+    catch {
+        return { groups: [], fallbackReason: "dockerfile_parse_failed" };
+    }
+    try {
+        validateParserDirectives(text);
+        // Heredocs are valid BuildKit syntax, but treating the entire Dockerfile
+        // as full context is safer than partially parsing them.
+        if (text.includes("<<")) {
+            throw new AnalysisFallback("dockerfile_instruction_parse_failed");
+        }
+        return { groups: analyzeLines(logicalLines(text)), fallbackReason: "" };
+    }
+    catch (error) {
+        if (error instanceof AnalysisFallback) {
+            return { groups: [], fallbackReason: error.reason };
+        }
+        throw error;
+    }
+};
+exports.analyzeDockerfileSources = analyzeDockerfileSources;

package/dist/sandbox/image-build/dockerignore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Docker-compatible `.dockerignore` parsing and matching.
+ *
+ * The matching contract intentionally follows Moby `patternmatcher` v0.6.1,
+ * which is also what the Hyperbrowser CLI reaches through BuildKit's
+ * filesystem utilities.
+ */
+/** Parse ignore-file lines like Moby's `ignorefile.ReadAll`. */
+export declare const readIgnorePatterns: (text: string) => string[];
+/** Ordered Docker ignore matcher with parent-directory semantics. */
+export declare class DockerIgnoreMatcher {
+    private readonly patterns;
+    readonly hasNegations: boolean;
+    constructor(patterns: Iterable<string>);
+    static fromFile(path: string): DockerIgnoreMatcher;
+    static fromText(text: string): DockerIgnoreMatcher;
+    matches(relativePath: string): boolean;
+}

package/dist/sandbox/image-build/dockerignore.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * Docker-compatible `.dockerignore` parsing and matching.
+ *
+ * The matching contract intentionally follows Moby `patternmatcher` v0.6.1,
+ * which is also what the Hyperbrowser CLI reaches through BuildKit's
+ * filesystem utilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerIgnoreMatcher = exports.readIgnorePatterns = void 0;
+const fs_1 = require("fs");
+const common_1 = require("./common");
+const REGEX_META_WITHOUT_GLOB_MEANING = new Set(".+()|{}$");
+/** Apply the Unix `filepath.Clean` behavior used by the CLI. */
+const cleanPath = (value) => {
+    if (value.startsWith("//")) {
+        value = "/" + value.replace(/^\/+/, "");
+    }
+    return (0, common_1.posixNormpath)(value);
+};
+/** Parse ignore-file lines like Moby's `ignorefile.ReadAll`. */
+const readIgnorePatterns = (text) => {
+    const patterns = [];
+    text.split("\n").forEach((rawLine, index) => {
+        if (rawLine.endsWith("\r")) {
+            rawLine = rawLine.slice(0, -1);
+        }
+        if (index === 0 && rawLine.startsWith("\ufeff")) {
+            rawLine = rawLine.slice(1);
+        }
+        if (rawLine.startsWith("#")) {
+            return;
+        }
+        let value = rawLine.trim();
+        if (!value) {
+            return;
+        }
+        const exclusion = value.startsWith("!");
+        if (exclusion) {
+            value = value.slice(1).trim();
+        }
+        if (value) {
+            value = cleanPath(value);
+            if (value.length > 1 && value.startsWith("/")) {
+                value = value.slice(1);
+            }
+        }
+        patterns.push((exclusion ? "!" : "") + value);
+    });
+    return patterns;
+};
+exports.readIgnorePatterns = readIgnorePatterns;
+const validateCharacterClass = (pattern, cursor) => {
+    const consumeValue = (position) => {
+        if (position >= pattern.length || pattern[position] === "-" || pattern[position] === "]") {
+            throw new Error(`invalid Docker ignore pattern "${pattern}"`);
+        }
+        if (pattern[position] === "\\") {
+            position += 1;
+            if (position >= pattern.length) {
+                throw new Error(`invalid Docker ignore pattern "${pattern}"`);
+            }
+        }
+        position += 1;
+        if (position >= pattern.length) {
+            throw new Error(`invalid Docker ignore pattern "${pattern}"`);
+        }
+        return position;
+    };
+    if (cursor < pattern.length && pattern[cursor] === "^") {
+        cursor += 1;
+    }
+    let ranges = 0;
+    while (true) {
+        if (cursor < pattern.length && pattern[cursor] === "]" && ranges) {
+            return cursor + 1;
+        }
+        cursor = consumeValue(cursor);
+        if (cursor < pattern.length && pattern[cursor] === "-") {
+            cursor = consumeValue(cursor + 1);
+        }
+        ranges += 1;
+    }
+};
+/** Reject malformed patterns using Go filepath.Match's Unix grammar. */
+const validateFilepathPattern = (pattern) => {
+    let cursor = 0;
+    while (cursor < pattern.length) {
+        const character = pattern[cursor];
+        if (character === "\\") {
+            cursor += 1;
+            if (cursor === pattern.length) {
+                throw new Error(`invalid Docker ignore pattern "${pattern}": trailing escape`);
+            }
+        }
+        else if (character === "[") {
+            cursor = validateCharacterClass(pattern, cursor + 1);
+            continue;
+        }
+        cursor += 1;
+    }
+};
+/** Compile one cleaned Moby pattern into its optimized match form. */
+const compilePattern = (pattern) => {
+    const parts = ["^"];
+    let matchType = "exact";
+    let cursor = 0;
+    let tokenIndex = 0;
+    let inClass = false;
+    while (cursor < pattern.length) {
+        const character = pattern[cursor];
+        cursor += 1;
+        if (character === "*") {
+            if (cursor < pattern.length && pattern[cursor] === "*") {
+                cursor += 1;
+                if (cursor < pattern.length && pattern[cursor] === "/") {
+                    cursor += 1;
+                }
+                if (cursor === pattern.length) {
+                    if (matchType === "exact") {
+                        matchType = "prefix";
+                    }
+                    else {
+                        parts.push(".*");
+                        matchType = "regexp";
+                    }
+                }
+                else {
+                    parts.push("(?:.*/)?");
+                    matchType = "regexp";
+                }
+                if (tokenIndex === 0) {
+                    matchType = "suffix";
+                }
+            }
+            else {
+                parts.push("[^/]*");
+                matchType = "regexp";
+            }
+        }
+        else if (character === "?") {
+            parts.push("[^/]");
+            matchType = "regexp";
+        }
+        else if (REGEX_META_WITHOUT_GLOB_MEANING.has(character)) {
+            parts.push("\\" + character);
+        }
+        else if (character === "\\") {
+            if (cursor < pattern.length) {
+                const codepoint = pattern.codePointAt(cursor);
+                parts.push(`\\u{${codepoint.toString(16)}}`);
+                cursor += codepoint > 0xffff ? 2 : 1;
+                matchType = "regexp";
+            }
+            else {
+                throw new Error(`invalid Docker ignore pattern "${pattern}": trailing escape`);
+            }
+        }
+        else {
+            // Brackets remain regex syntax because they are also filepath glob
+            // syntax. All other characters are literal in the Moby compiler.
+            parts.push(character === "]" && !inClass ? "\\]" : character);
+            if (character === "[")
+                inClass = true;
+            else if (character === "]")
+                inClass = false;
+            if (character === "[" || character === "]") {
+                matchType = "regexp";
+            }
+        }
+        tokenIndex += 1;
+    }
+    if (matchType !== "regexp") {
+        return { matchType, regexp: null };
+    }
+    parts.push("$");
+    try {
+        // Python and Go wildcards consume Unicode codepoints, not UTF-16 units.
+        return { matchType, regexp: new RegExp(parts.join(""), "u") };
+    }
+    catch (error) {
+        throw new Error(`invalid Docker ignore pattern "${pattern}": ${error instanceof Error ? error.message : error}`);
+    }
+};
+class DockerIgnorePattern {
+    constructor(rawPattern) {
+        let value = cleanPath(rawPattern.trim());
+        const exclusion = value.startsWith("!");
+        if (exclusion) {
+            if (value === "!") {
+                throw new Error('illegal exclusion pattern: "!"');
+            }
+            value = value.slice(1);
+        }
+        validateFilepathPattern(value);
+        const compiled = compilePattern(value);
+        this.value = value;
+        this.exclusion = exclusion;
+        this.matchType = compiled.matchType;
+        this.regexp = compiled.regexp;
+    }
+    matchesPath(path) {
+        if (this.matchType === "exact") {
+            return path === this.value;
+        }
+        if (this.matchType === "prefix") {
+            return path.startsWith(this.value.slice(0, -2));
+        }
+        if (this.matchType === "suffix") {
+            const suffix = this.value.slice(2);
+            return path.endsWith(suffix) || (suffix.startsWith("/") && path === suffix.slice(1));
+        }
+        if (this.regexp === null) {
+            throw new Error(`invalid Docker ignore pattern: "${this.value}"`);
+        }
+        return this.regexp.test(path);
+    }
+}
+/** Ordered Docker ignore matcher with parent-directory semantics. */
+class DockerIgnoreMatcher {
+    constructor(patterns) {
+        const compiled = [];
+        for (const pattern of patterns) {
+            const cleaned = pattern.trim();
+            if (!cleaned) {
+                continue;
+            }
+            compiled.push(new DockerIgnorePattern(cleaned));
+        }
+        this.patterns = compiled;
+        this.hasNegations = compiled.some((pattern) => pattern.exclusion);
+    }
+    static fromFile(path) {
+        let text = (0, fs_1.readFileSync)(path).toString("utf8");
+        if (text.startsWith("\ufeff")) {
+            text = text.slice(1);
+        }
+        return new DockerIgnoreMatcher((0, exports.readIgnorePatterns)(text));
+    }
+    static fromText(text) {
+        return new DockerIgnoreMatcher((0, exports.readIgnorePatterns)(text));
+    }
+    matches(relativePath) {
+        // Traversal supplies slash-delimited paths. On Unix, a backslash can be
+        // part of a filename and must remain available for glob escaping.
+        const path = cleanPath(relativePath);
+        if (path === ".") {
+            return false;
+        }
+        const parent = (0, common_1.posixDirname)(path);
+        const parentParts = parent && parent !== "." ? parent.split("/") : [];
+        let matched = false;
+        for (const pattern of this.patterns) {
+            // An exclusion can only re-include an ignored path, and a normal pattern
+            // only needs checking while the path is included.
+            if (pattern.exclusion !== matched) {
+                continue;
+            }
+            let patternMatches = pattern.matchesPath(path);
+            if (!patternMatches) {
+                for (let length = 1; length <= parentParts.length; length += 1) {
+                    if (pattern.matchesPath(parentParts.slice(0, length).join("/"))) {
+                        patternMatches = true;
+                        break;
+                    }
+                }
+            }
+            if (patternMatches) {
+                matched = !pattern.exclusion;
+            }
+        }
+        return matched;
+    }
+}
+exports.DockerIgnoreMatcher = DockerIgnoreMatcher;