@langchain/langgraph-cli 1.3.1 → 1.4.0

package/dist/cli/utils/archive.mjs

@@ -0,0 +1,130 @@
+/**
+ * Create a tarball of project source for remote builds, ported from the
+ * Python CLI's `archive.py`.
+ *
+ * The JS `assembleLocalDeps` requires every local dependency to live inside
+ * the config directory, so (unlike the Python CLI) there are no external
+ * build contexts to splice in: the archive root is always the config's parent
+ * directory and the config path is included at its natural relative location.
+ */
+import path from "node:path";
+import os from "node:os";
+import { promises as fs } from "node:fs";
+import { create as tarCreate } from "tar";
+import { ALWAYS_EXCLUDE_NAMES, buildIgnoreSpec } from "./deploy-ignore.mjs";
+/** Number of bytes in one mebibyte, used for human-readable size output. */
+const BYTES_PER_MIB = 1_048_576;
+/** Archive size above which a warning is emitted (50 MB). */
+const WARN_SIZE = 50 * 1024 * 1024;
+/** Hard archive size limit enforced by the host backend (200 MB). */
+const MAX_SIZE = 200 * 1024 * 1024;
+/**
+ * Recursively collect the POSIX-relative paths of every file under `rootDir`
+ * that should be included in the archive.
+ *
+ * @remarks
+ * Symlinks (and other non-regular entries) are skipped. Always-excluded
+ * directories are pruned by name; other ignored directories are pruned too,
+ * unless a negation (`!pattern`) could re-include one of their descendants (see
+ * {@link IgnoreSpec.requiresDirWalk}), in which case the directory is still
+ * walked and filtering happens per-file.
+ *
+ * @param rootDir - Absolute directory to walk (the archive root).
+ * @returns Sorted-by-walk list of relative file paths to include.
+ */
+async function collectFiles(rootDir) {
+    const spec = await buildIgnoreSpec(rootDir, { includeGitignore: true });
+    const files = [];
+    async function walk(dir, relPrefix) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+            const abs = path.join(dir, entry.name);
+            // Strip symlinks (and other non-regular entries) for safety, mirroring
+            // the Python `_tar_filter`.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (ALWAYS_EXCLUDE_NAMES.has(entry.name))
+                    continue;
+                const dirRel = `${rel}/`;
+                // Prune ignored directories, but still descend into the (usually
+                // small) set a negation could re-include from, instead of walking
+                // every ignored directory whenever any negation exists.
+                if (spec.ignores(dirRel) && !spec.requiresDirWalk(rel))
+                    continue;
+                await walk(abs, rel);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (spec.ignores(rel))
+                continue;
+            files.push(rel);
+        }
+    }
+    await walk(rootDir, "");
+    return files;
+}
+/**
+ * Create a `source.tar.gz` of the project rooted at the config's parent
+ * directory.
+ *
+ * @remarks
+ * Source files are filtered through {@link buildIgnoreSpec} (honoring
+ * `.dockerignore` and `.gitignore`). The archive is validated to contain the
+ * config file and checked against the size warning/limit thresholds. The
+ * caller is responsible for invoking {@link Archive.cleanup} when done; on
+ * failure the temp directory is cleaned up automatically.
+ *
+ * @param configPath - Path to `langgraph.json` (its parent is the archive root).
+ * @param options - Behavior options.
+ * @param options.onWarn - Invoked with a warning message when the archive
+ * exceeds {@link WARN_SIZE} but is still under the hard limit.
+ * @returns The created {@link Archive}.
+ * @throws Error if the config file is missing from the archive or the archive
+ * exceeds the 200 MB limit.
+ */
+export async function createArchive(configPath, options = {}) {
+    const resolvedConfig = path.resolve(configPath);
+    const contextDir = path.dirname(resolvedConfig);
+    const configRel = path
+        .relative(contextDir, resolvedConfig)
+        .split(path.sep)
+        .join("/");
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "langgraph-deploy-"));
+    const archivePath = path.join(tmpDir, "source.tar.gz");
+    const cleanup = async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    };
+    try {
+        const files = await collectFiles(contextDir);
+        if (!files.includes(configRel)) {
+            throw new Error(`Archive validation failed: ${configRel} not found in archive`);
+        }
+        await tarCreate({
+            gzip: true,
+            file: archivePath,
+            cwd: contextDir,
+            portable: true,
+            follow: false,
+            noDirRecurse: true,
+        }, files);
+        const { size: fileSize } = await fs.stat(archivePath);
+        if (fileSize > MAX_SIZE) {
+            throw new Error(`Source archive is ${(fileSize / BYTES_PER_MIB).toFixed(1)} MB, which ` +
+                "exceeds the 200 MB limit. Add large files to .dockerignore or " +
+                ".gitignore (model weights, data sets, etc.).");
+        }
+        if (fileSize > WARN_SIZE && options.onWarn) {
+            options.onWarn(`Warning: source archive is ${(fileSize / BYTES_PER_MIB).toFixed(1)} MB. ` +
+                "Consider adding large files to .dockerignore or .gitignore.");
+        }
+        return { archivePath, fileSize, configRel, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+export { BYTES_PER_MIB };

package/dist/cli/utils/deploy-helpers.mjs

@@ -0,0 +1,396 @@
+/**
+ * Pure helpers for the `deploy` command, ported from `deploy.py`. Kept free of
+ * I/O so they can be unit-tested in isolation.
+ */
+import path from "node:path";
+/**
+ * Env vars that must never be forwarded as deployment secrets. Mirrors
+ * `RESERVED_ENV_VARS` in the Python CLI (LANGCHAIN_RESERVED_ENV_VARS plus
+ * ALLOWED_SELF_HOSTED_ENV_VARS).
+ */
+export const RESERVED_ENV_VARS = new Set([
+    "LANGCHAIN_TRACING_V2",
+    "LANGSMITH_TRACING_V2",
+    "LANGCHAIN_ENDPOINT",
+    "LANGCHAIN_PROJECT",
+    "LANGSMITH_PROJECT",
+    "LANGSMITH_LANGGRAPH_GIT_REPO",
+    "LANGGRAPH_GIT_REPO_PATH",
+    "LANGCHAIN_API_KEY",
+    "LANGGRAPH_HOST_API_KEY",
+    "LANGSMITH_CONTROL_PLANE_API_KEY",
+    "POSTGRES_URI",
+    "POSTGRES_PASSWORD",
+    "DATABASE_URI",
+    "LANGSMITH_LANGGRAPH_GIT_REF",
+    "LANGSMITH_LANGGRAPH_GIT_REF_SHA",
+    "LANGGRAPH_AUTH_TYPE",
+    "LANGSMITH_AUTH_ENDPOINT",
+    "LANGSMITH_TENANT_ID",
+    "LANGSMITH_AUTH_VERIFY_TENANT_ID",
+    "LANGSMITH_HOST_PROJECT_ID",
+    "LANGSMITH_HOST_PROJECT_NAME",
+    "LANGSMITH_HOST_REVISION_ID",
+    "LOG_JSON",
+    "LOG_DICT_TRACEBACKS",
+    "REDIS_URI",
+    "LANGCHAIN_CALLBACKS_BACKGROUND",
+    "DD_TRACE_PSYCOPG_ENABLED",
+    "DD_TRACE_REDIS_ENABLED",
+    "LANGSMITH_DEPLOYMENT_NAME",
+    "LANGGRAPH_CLOUD_LICENSE_KEY",
+    "LANGSMITH_API_KEY",
+    "LANGSMITH_ENDPOINT",
+    "POSTGRES_URI_CUSTOM",
+    "REDIS_URI_CUSTOM",
+    "PATH",
+    "PORT",
+    "MOUNT_PREFIX",
+    "LSD_ENV",
+    "LSD_DD_API_KEY",
+    "LSD_DD_ENDPOINT",
+    "LSD_DEPLOYMENT_TYPE",
+]);
+/** Environment variable names checked, in order, when resolving the API key. */
+export const API_KEY_ENV_NAMES = [
+    "LANGGRAPH_HOST_API_KEY",
+    "LANGSMITH_API_KEY",
+    "LANGCHAIN_API_KEY",
+];
+/** Env var holding a default deployment name. */
+export const DEPLOYMENT_NAME_ENV = "LANGSMITH_DEPLOYMENT_NAME";
+/**
+ * Whether `child` resolves to a location strictly inside `parent`.
+ *
+ * @remarks
+ * Used to keep configuration-supplied paths (e.g. the `env` file referenced
+ * from `langgraph.json`) contained within the project directory, preventing
+ * traversal (`../`) or absolute paths from reaching files outside the project.
+ * Both arguments are expected to be absolute paths.
+ *
+ * @param parent - Absolute path to the directory that must contain `child`.
+ * @param child - Absolute path to validate.
+ * @returns `true` when `child` is strictly inside `parent`.
+ */
+export function isPathWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/** Default host backend API URL. */
+export const DEFAULT_HOST_URL = "https://api.host.langchain.com";
+/** Revision statuses that end status polling (success or failure). */
+export const TERMINAL_STATUSES = new Set([
+    "DEPLOYED",
+    "CREATE_FAILED",
+    "BUILD_FAILED",
+    "DEPLOY_FAILED",
+    "SKIPPED",
+]);
+/** Characters disallowed in custom install/build commands. */
+const DISALLOWED_BUILD_COMMAND_CHARS = [
+    '"',
+    "`",
+    "\\",
+    "\n",
+    "\r",
+    "\0",
+    "\t",
+    "|",
+    ";",
+    "$",
+    ">",
+    "<",
+];
+// Matches a single "&" that is NOT part of "&&" (blocks background execution
+// while allowing `cmd1 && cmd2`).
+const SINGLE_AMPERSAND_RE = /(?<!&)&(?:&&)*(?!&)/;
+/**
+ * Whether a custom install/build command contains disallowed shell content.
+ *
+ * @remarks
+ * Rejects shell metacharacters (see {@link DISALLOWED_BUILD_COMMAND_CHARS}) and
+ * a lone `&` (background execution), while still allowing `cmd1 && cmd2`.
+ *
+ * @param command - The command string to validate.
+ * @returns `true` if the command contains disallowed characters or patterns.
+ */
+export function hasDisallowedBuildCommandContent(command) {
+    if (DISALLOWED_BUILD_COMMAND_CHARS.some((char) => command.includes(char))) {
+        return true;
+    }
+    return SINGLE_AMPERSAND_RE.test(command);
+}
+/**
+ * Sanitize a deployment/directory name into a valid LangSmith Deployment name.
+ *
+ * @remarks
+ * Deployment names allow only lowercase `[a-z0-9-]`; invalid characters become
+ * hyphens and leading/trailing hyphens are trimmed.
+ *
+ * @param value - The raw name (e.g. a directory name), may be nullish.
+ * @returns A normalized name, or `"app"` when empty/fully invalid.
+ */
+export function normalizeName(value) {
+    if (!value)
+        return "app";
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "app";
+}
+/**
+ * Validate a Docker image tag (`[A-Za-z0-9_.-]`), defaulting to `latest`.
+ *
+ * @param value - The requested tag (empty becomes `latest`).
+ * @returns The validated tag.
+ * @throws Error if the tag contains characters outside `[A-Za-z0-9_.-]`.
+ */
+export function normalizeImageTag(value) {
+    const tag = value || "latest";
+    if (!/^[A-Za-z0-9_.-]+$/.test(tag)) {
+        throw new Error("Image tag may only contain characters A-Z, a-z, 0-9, '_', '-', '.'");
+    }
+    return tag;
+}
+/**
+ * Convert an env dict to a deployment secrets list, dropping reserved and
+ * empty-valued variables.
+ *
+ * @param envVars - Environment variables to convert.
+ * @param onSkip - Optional callback invoked with the name of each reserved
+ * variable that is skipped.
+ * @returns The list of forwardable secrets.
+ */
+export function secretsFromEnv(envVars, onSkip) {
+    const secrets = [];
+    for (const [name, value] of Object.entries(envVars)) {
+        if (RESERVED_ENV_VARS.has(name)) {
+            onSkip?.(name);
+            continue;
+        }
+        if (!value)
+            continue;
+        secrets.push({ name, value });
+    }
+    return secrets;
+}
+/**
+ * Return a copy of env vars without the deployment-name key (so it is not
+ * forwarded as a secret).
+ *
+ * @param envVars - Environment variables to copy.
+ * @returns A new object without {@link DEPLOYMENT_NAME_ENV}.
+ */
+export function envWithoutDeploymentName(envVars) {
+    const filtered = { ...envVars };
+    delete filtered[DEPLOYMENT_NAME_ENV];
+    return filtered;
+}
+/**
+ * Extract a deployment's public URL from its `source_config.custom_url`.
+ *
+ * @param deployment - The deployment object.
+ * @returns The custom URL, or `"-"` when absent.
+ */
+function extractDeploymentUrl(deployment) {
+    const sourceConfig = deployment.source_config;
+    if (sourceConfig && typeof sourceConfig === "object") {
+        const customUrl = sourceConfig.custom_url;
+        if (typeof customUrl === "string" && customUrl)
+            return customUrl;
+    }
+    return "-";
+}
+/**
+ * Render a single table row, left-padding each cell to its column width.
+ *
+ * @param row - Cell values for the row.
+ * @param widths - Column widths (parallel to `row`).
+ * @returns The formatted, two-space-separated row string.
+ */
+function formatRow(row, widths) {
+    return row.map((value, index) => value.padEnd(widths[index])).join("  ");
+}
+/**
+ * Render a fixed-width text table with a header and separator row.
+ *
+ * @param headers - Column header labels.
+ * @param rows - Row data (each parallel to `headers`).
+ * @returns The full table as a newline-joined string.
+ */
+function buildTable(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index].length)));
+    const lines = [
+        formatRow(headers, widths),
+        formatRow(widths.map((width) => "-".repeat(width)), widths),
+    ];
+    for (const row of rows)
+        lines.push(formatRow(row, widths));
+    return lines.join("\n");
+}
+/**
+ * Render a table of deployments with ID, name, and URL columns.
+ *
+ * @param deployments - Deployment objects to display.
+ * @returns The formatted table string.
+ */
+export function formatDeploymentsTable(deployments) {
+    const rows = deployments.map((deployment) => [
+        String(deployment.id ?? "-") || "-",
+        String(deployment.name ?? "-") || "-",
+        extractDeploymentUrl(deployment),
+    ]);
+    return buildTable(["Deployment ID", "Deployment Name", "Deployment URL"], rows);
+}
+/**
+ * Render a table of revisions with ID, status, and creation time.
+ *
+ * @remarks
+ * Since revisions are listed newest-first, only the first `DEPLOYED` revision
+ * keeps that status; subsequent `DEPLOYED` rows are relabeled `REPLACED`.
+ *
+ * @param revisions - Revision objects to display (newest first).
+ * @returns The formatted table string.
+ */
+export function formatRevisionsTable(revisions) {
+    let latestDeployedSeen = false;
+    const rows = revisions.map((revision) => {
+        let status = String(revision.status ?? "-") || "-";
+        if (status === "DEPLOYED") {
+            if (latestDeployedSeen) {
+                status = "REPLACED";
+            }
+            else {
+                latestDeployedSeen = true;
+            }
+        }
+        return [
+            String(revision.id ?? "-") || "-",
+            status,
+            String(revision.created_at ?? "-") || "-",
+        ];
+    });
+    return buildTable(["Revision ID", "Status", "Created At"], rows);
+}
+/**
+ * Convert a timestamp to a readable UTC string (`YYYY-MM-DD HH:MM:SS`).
+ *
+ * @param ts - Epoch milliseconds (number) or a pre-formatted value.
+ * @returns The formatted timestamp, or an empty string for falsy input.
+ */
+export function formatTimestamp(ts) {
+    if (typeof ts === "number") {
+        const date = new Date(ts);
+        return date.toISOString().slice(0, 19).replace("T", " ");
+    }
+    return ts ? String(ts) : "";
+}
+/**
+ * Format a single log entry as `[timestamp] [level] message`, omitting any
+ * missing parts.
+ *
+ * @param entry - A log entry with optional `timestamp`, `level`, `message`.
+ * @returns The formatted log line.
+ */
+export function formatLogEntry(entry) {
+    const ts = formatTimestamp(entry.timestamp ?? "");
+    const level = entry.level ?? "";
+    const message = entry.message ?? "";
+    if (ts && level)
+        return `[${ts}] [${level}] ${message}`;
+    if (ts)
+        return `[${ts}] ${message}`;
+    return String(message);
+}
+/**
+ * Map a log level to a display color.
+ *
+ * @param level - The log level (case-insensitive).
+ * @returns `"red"` for errors, `"yellow"` for warnings, otherwise `undefined`.
+ */
+export function levelColor(level) {
+    const upper = typeof level === "string" ? level.toUpperCase() : "";
+    if (upper === "ERROR" || upper === "CRITICAL")
+        return "red";
+    if (upper === "WARNING")
+        return "yellow";
+    return undefined;
+}
+/**
+ * Derive the LangSmith dashboard base URL from the API host URL.
+ *
+ * @remarks
+ * Maps the prod host to `smith.langchain.com`, regional hosts (e.g.
+ * `eu.api.host.langchain.com`) to their regional dashboard, passes through
+ * localhost, and defaults to the prod dashboard for anything unrecognized.
+ *
+ * @param hostUrl - The host backend API URL, may be nullish.
+ * @returns The dashboard base URL (no trailing slash).
+ */
+export function smithDashboardBaseUrl(hostUrl) {
+    if (!hostUrl)
+        return "https://smith.langchain.com";
+    let parsed;
+    try {
+        parsed = new URL(hostUrl);
+    }
+    catch {
+        return "https://smith.langchain.com";
+    }
+    const hostname = parsed.hostname || "";
+    if (hostname === "localhost" || hostname === "127.0.0.1") {
+        return hostUrl.replace(/\/+$/, "");
+    }
+    const apiHostSuffix = "api.host.langchain.com";
+    if (hostname === apiHostSuffix)
+        return "https://smith.langchain.com";
+    if (hostname.endsWith(`.${apiHostSuffix}`)) {
+        const prefix = hostname.slice(0, -(apiHostSuffix.length + 1));
+        return `https://${prefix}.smith.langchain.com`;
+    }
+    return "https://smith.langchain.com";
+}
+/**
+ * Compute the LangSmith dashboard URL for a deployment, if possible.
+ *
+ * @param updated - A deployment object that may carry a `tenant_id`.
+ * @param deploymentId - The deployment ID.
+ * @param hostUrl - The host backend API URL, used to derive the dashboard host.
+ * @returns The dashboard URL, or `null` when no tenant ID is available.
+ */
+export function getDeploymentStatusUrl(updated, deploymentId, hostUrl) {
+    const tenantId = updated && typeof updated === "object"
+        ? updated.tenant_id
+        : undefined;
+    if (!tenantId)
+        return null;
+    const base = smithDashboardBaseUrl(hostUrl);
+    return `${base}/o/${tenantId}/host/deployments/${deploymentId}`;
+}
+/**
+ * Find a deployment ID by exact name match within a list response.
+ *
+ * @param response - A list-deployments response with a `resources` array.
+ * @param name - The exact deployment name to match, may be nullish.
+ * @returns The matching deployment ID, or `null` when not found.
+ */
+export function findDeploymentIdByName(response, name) {
+    if (!name)
+        return null;
+    if (response && typeof response === "object") {
+        const resources = response.resources;
+        if (Array.isArray(resources)) {
+            for (const dep of resources) {
+                if (dep &&
+                    typeof dep === "object" &&
+                    dep.name === name) {
+                    const id = dep.id;
+                    if (id)
+                        return String(id);
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/cli/utils/deploy-ignore.mjs

@@ -0,0 +1,163 @@
+/**
+ * Shared ignore-file handling for local source filtering, ported from the
+ * Python CLI's `_ignore.py`. Combines a set of always-excluded directories
+ * with patterns from `.dockerignore` (and optionally `.gitignore`), using
+ * gitignore semantics via the `ignore` package.
+ */
+import ignore, {} from "ignore";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+/** Directories always excluded from source filtering, regardless of config. */
+const ALWAYS_EXCLUDE = [
+    "__pycache__/",
+    ".git/",
+    ".venv/",
+    "venv/",
+    "node_modules/",
+    ".tox/",
+    ".mypy_cache/",
+];
+/**
+ * Base names of the {@link ALWAYS_EXCLUDE} directories, used to prune the
+ * filesystem walk before consulting the gitignore matcher.
+ */
+export const ALWAYS_EXCLUDE_NAMES = new Set(ALWAYS_EXCLUDE.map((pattern) => pattern.replace(/\/$/, "").split("/").pop()));
+/** Characters that mark a path segment as a glob pattern. */
+const GLOB_CHARS = ["*", "?", "["];
+/** Whether `ancestor` is a strict path-prefix (ancestor) of `descendant`. */
+function isAncestor(ancestor, descendant) {
+    return descendant.startsWith(`${ancestor}/`);
+}
+/**
+ * Build {@link NegationHints} from raw ignore-file lines.
+ *
+ * @param lines - Raw lines from the loaded ignore files.
+ * @returns The aggregated negation hints.
+ */
+function buildNegationHints(lines) {
+    const exactDirs = new Set();
+    const wildcardPrefixes = new Set();
+    let recurseAll = false;
+    for (const rawLine of lines) {
+        let line = rawLine.trim();
+        if (!line || line.startsWith("#") || line.startsWith("\\!"))
+            continue;
+        if (line.startsWith("\\#"))
+            line = line.slice(1);
+        if (!line.startsWith("!"))
+            continue;
+        let pattern = line.slice(1).replace(/^\/+/, "");
+        while (pattern.startsWith("./"))
+            pattern = pattern.slice(2);
+        pattern = pattern.replace(/\/+$/, "");
+        const parts = pattern.split("/").filter((part) => part && part !== ".");
+        if (!parts.length) {
+            recurseAll = true;
+            continue;
+        }
+        const wildcardIndex = parts.findIndex((part) => GLOB_CHARS.some((char) => part.includes(char)));
+        if (wildcardIndex !== -1) {
+            const literalParts = parts.slice(0, wildcardIndex);
+            if (!literalParts.length) {
+                recurseAll = true;
+                continue;
+            }
+            wildcardPrefixes.add(literalParts.join("/"));
+            continue;
+        }
+        const parentParts = parts.slice(0, -1);
+        for (let idx = 1; idx <= parentParts.length; idx += 1) {
+            exactDirs.add(parentParts.slice(0, idx).join("/"));
+        }
+    }
+    return { recurseAll, exactDirs, wildcardPrefixes: [...wildcardPrefixes] };
+}
+/**
+ * Whether the directory at `relPath` must be walked given the negation hints.
+ *
+ * @param hints - The aggregated negation hints.
+ * @param relPath - Directory path relative to the spec root (no trailing `/`).
+ * @returns `true` if the directory must be walked despite being ignored.
+ */
+function requiresDirWalkWith(hints, relPath) {
+    if (hints.recurseAll || hints.exactDirs.has(relPath))
+        return true;
+    return hints.wildcardPrefixes.some((prefix) => relPath === prefix ||
+        isAncestor(relPath, prefix) ||
+        isAncestor(prefix, relPath));
+}
+/**
+ * Read a text file split into lines, returning `null` if it does not exist or
+ * is not a regular file.
+ *
+ * @param file - Absolute path to the file to read.
+ * @returns The file's lines, or `null` when unreadable/missing.
+ */
+async function readLines(file) {
+    try {
+        const stat = await fs.stat(file);
+        if (!stat.isFile())
+            return null;
+        const content = await fs.readFile(file, "utf-8");
+        return content.split(/\r?\n/);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build an {@link IgnoreSpec} for `directory`.
+ *
+ * @remarks
+ * Always excludes the common non-source directories in {@link ALWAYS_EXCLUDE}.
+ * On top of that, `.dockerignore` patterns are merged in, and `.gitignore`
+ * patterns are added when `includeGitignore` is enabled (archive creation
+ * wants both, while Docker build-context semantics want only `.dockerignore`).
+ *
+ * @param directory - Absolute directory whose ignore files are loaded.
+ * @param options - Behavior options.
+ * @param options.includeGitignore - Merge `.gitignore` patterns too (default
+ * `true`).
+ * @returns A spec exposing {@link IgnoreSpec.ignores} and `hasNegation`.
+ */
+export async function buildIgnoreSpec(directory, options = {}) {
+    const includeGitignore = options.includeGitignore ?? true;
+    const lines = [...ALWAYS_EXCLUDE];
+    // Raw negation-bearing lines from the loaded ignore files (excluding the
+    // built-in ALWAYS_EXCLUDE, which never contains negations) used to compute
+    // which ignored directories must still be walked.
+    const ignoreFileLines = [];
+    let hasNegation = false;
+    const ignoreFiles = [".dockerignore"];
+    if (includeGitignore)
+        ignoreFiles.push(".gitignore");
+    for (const name of ignoreFiles) {
+        const fileLines = await readLines(path.join(directory, name));
+        if (!fileLines)
+            continue;
+        for (const raw of fileLines) {
+            const line = raw.trim();
+            if (line && !line.startsWith("#") && line.startsWith("!")) {
+                hasNegation = true;
+            }
+        }
+        ignoreFileLines.push(...fileLines);
+        lines.push(...fileLines);
+    }
+    const ig = ignore().add(lines);
+    const negationHints = buildNegationHints(ignoreFileLines);
+    return {
+        ignores(relPath) {
+            // The `ignore` package rejects "." and absolute paths.
+            if (!relPath || relPath === ".")
+                return false;
+            return ig.ignores(relPath);
+        },
+        hasNegation,
+        requiresDirWalk(relPath) {
+            if (!relPath || relPath === ".")
+                return true;
+            return requiresDirWalkWith(negationHints, relPath);
+        },
+    };
+}