primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/env-resolver.js

@@ -0,0 +1,153 @@
+/**
+ * Environment resolution (CLI side).
+ *
+ * The algorithm itself lives in `env-resolver-core.ts` — the one copy the Vite
+ * plugin and the Swift pre-build script also run (#2873). This module is the
+ * CLI's thin wrapper around it: process-lifetime caching, the `--env` override
+ * commander sets, and — load-bearing — the CLI's own FULL field-level
+ * validation via `validateProjectConfig()`. The core carries only the version
+ * and structural checks the other readers need; running the CLI's validation
+ * first is what keeps `getProjectConfig()` and `getCurrentEnvironment()` from
+ * ever disagreeing about the same file.
+ *
+ * The resolution order is:
+ *
+ *   1. Explicit --env <name> flag (set via setCurrentEnvName from bin/primitive.ts)
+ *   2. PRIMITIVE_ENV environment variable
+ *   3. The per-machine selection in .primitive/local.json (`primitive env use`)
+ *   4. The project config's committed defaultEnvironment
+ *   5. If the project has exactly one environment, that one
+ *   6. null (legacy mode — fall back to ~/.primitive/credentials.json)
+ *
+ * Commands read the resolved environment once via getCurrentEnvironment().
+ * The resolution is cached for the lifetime of the process.
+ */
+import { loadProjectConfig, findProjectConfigPath, findProjectRoot, } from "./project-config.js";
+import { PrimitiveEnvError, localStatePathForConfigPath, missingConfigMessage, readLocalSelection, selectEnvironmentName, } from "./env-resolver-core.js";
+/** Process-lifetime cache for resolution results. */
+let cachedResolution;
+let explicitEnvName = null;
+let cachedProjectConfig;
+/**
+ * Called by bin/primitive.ts when the user passes --env <name> on the command
+ * line. Must be called before any command code runs so subsequent calls to
+ * getCurrentEnvironment() see the override.
+ */
+export function setCurrentEnvName(name) {
+    explicitEnvName = name;
+    // Invalidate any cached resolution so the next getCurrentEnvironment()
+    // picks up the new override.
+    cachedResolution = undefined;
+}
+/**
+ * Forces the resolver to re-read the project config on the next call.
+ * Used by tests and by commands that mutate the project config.
+ */
+export function resetEnvResolver() {
+    cachedResolution = undefined;
+    cachedProjectConfig = undefined;
+}
+/**
+ * Loads and caches the project config. Returns null if no
+ * primitive/config.json is present. Throws ProjectConfigError on a broken config.
+ */
+export function getProjectConfig() {
+    if (cachedProjectConfig === undefined) {
+        cachedProjectConfig = loadProjectConfig();
+    }
+    return cachedProjectConfig ?? null;
+}
+/**
+ * Reads this machine's environment selection (`primitive env use`), or null
+ * when nothing is selected. Throws PrimitiveEnvError on corrupt local state —
+ * `env list` / `env show` surface that distinctly instead of quietly falling
+ * back to the committed default.
+ */
+export function getLocalSelection() {
+    const configPath = findProjectConfigPath();
+    if (!configPath)
+        return null;
+    return readLocalSelection(configPath);
+}
+/** Absolute path of the local-state file for the current project, if any. */
+export function getLocalStatePath() {
+    const configPath = findProjectConfigPath();
+    return configPath ? localStatePathForConfigPath(configPath) : null;
+}
+/**
+ * Resolves the current environment, or returns null if we're running in
+ * legacy mode (no primitive/config.json present).
+ *
+ * This never throws for a missing project config — that's legitimate
+ * "legacy mode" usage. It DOES throw if the project config exists but the
+ * requested environment doesn't.
+ */
+export function getCurrentEnvironment() {
+    if (cachedResolution !== undefined)
+        return cachedResolution;
+    // Validate through the CLI's own loader first: the core's checks are a
+    // subset, and a config the CLI rejects must never resolve here.
+    const project = getProjectConfig();
+    if (!project) {
+        cachedResolution = null;
+        return null;
+    }
+    const configPath = findProjectConfigPath();
+    const projectRoot = findProjectRoot();
+    const { name, source } = selectEnvironmentName(project, {
+        explicitEnvName,
+        envVarName: process.env.PRIMITIVE_ENV || null,
+        localSelection: readLocalSelection(configPath),
+        configPath,
+    });
+    cachedResolution = {
+        name,
+        config: project.environments[name],
+        projectConfigPath: configPath,
+        projectRoot,
+        source,
+    };
+    return cachedResolution;
+}
+/**
+ * The resolved environment, or the one refusal (#3154, intent criterion 5).
+ *
+ * `getCurrentEnvironment()` answers `null` outside a project, which used to
+ * mean "legacy mode — fall back to `./config` and `~/.primitive/`". There is
+ * no such mode any more: the environment is the ONLY thing that names the
+ * configuration tree, the app and the server, so a caller that needs one asks
+ * here and gets an error naming what is missing instead of a second answer.
+ *
+ * Everything else propagates untouched. `no-selection`, `unknown-environment`,
+ * `corrupt-local-state` and `stale-layout` are real answers about a real
+ * project, and the old `safeEnv()` swallowing them is exactly how a typo in
+ * `--env` used to end up writing into `./config`.
+ */
+export function requireCurrentEnvironment() {
+    const env = getCurrentEnvironment();
+    if (env)
+        return env;
+    throw new PrimitiveEnvError("missing-config", missingConfigMessage(process.cwd()));
+}
+/**
+ * Returns the current environment name for display purposes (e.g. in status
+ * headers). Returns null in legacy mode. Swallows resolution errors so the
+ * header never crashes the CLI.
+ */
+export function getCurrentEnvNameSafe() {
+    try {
+        return getCurrentEnvironment()?.name ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the explicit name set via setCurrentEnvName(), for commands that
+ * need to know whether the user passed --env vs. relying on defaults.
+ */
+export function getExplicitEnvName() {
+    return explicitEnvName;
+}
+export { PrimitiveEnvError };
+//# sourceMappingURL=env-resolver.js.map

package/dist/src/lib/env-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-resolver.js","sourceRoot":"","sources":["../../../src/lib/env-resolver.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/fetch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Custom fetch that accepts self-signed certificates for localhost.
+ * Used for local development with HTTPS.
+ */
+export declare function fetchWithTLS(url: string, options?: RequestInit): Promise<Response>;

package/dist/src/lib/function-bundle.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Building a server function's bundle, in the CLI (#3179, project
+ * `server-functions`).
+ *
+ * The intent decides that the build happens here and never on the server:
+ * `config push` runs esbuild over the authored `entry`, inlines the npm
+ * dependencies, and ships the built bundle next to the authored source bytes
+ * in one envelope. The server verifies the hash and stores the object; it does
+ * not compile anything.
+ *
+ * ── The two import rules ─────────────────────────────────────────────────
+ *
+ * They look contradictory and are not (F-005):
+ *
+ *   - A **filesystem import** — relative or absolute — must stay inside the
+ *     config tree. `entry`, every import it reaches, and every symlink they
+ *     traverse are realpath-resolved and checked against the tree root, so a
+ *     push can never read a file off a developer's disk that the tree does not
+ *     contain.
+ *   - A **bare package specifier** is exempt. It resolves through Node into an
+ *     ancestor `node_modules`, which is outside every config tree by
+ *     construction; esbuild inlines it into the bundle, and it is never
+ *     captured as an authored source (so `config pull` never writes
+ *     `node_modules` content back).
+ *
+ * The exemption follows the specifier, not the path a file happens to sit at.
+ * A resolver plugin records the files a BARE specifier reached (and the files
+ * those reach in turn), so `import "../../node_modules/private/index.js"` — a
+ * relative filesystem import that merely lands in a `node_modules` directory —
+ * is still an escape and still refused. Deciding by path would have let that
+ * one specifier read any file on the disk and upload it.
+ *
+ * `primitive-functions` is the one bare specifier left EXTERNAL: the loader
+ * (#3180) supplies it at invoke time, so baking a copy into every bundle would
+ * pin the SDK version to whenever the function was last pushed.
+ *
+ * ── The retired specifier ────────────────────────────────────────────────
+ *
+ * That module was called `primitive-sdk` until #3209. This file is the one
+ * place in the repo that still writes the old name on purpose: without a
+ * detector, an author who copied an older example gets esbuild's generic
+ * `Could not resolve "primitive-sdk"`, which reads as a missing dependency
+ * rather than a rename. `RETIRED_SDK_MODULE` below is that detector, and
+ * `cli/tests/unit/retired-sdk-name-guard-3209.test.ts` allowlists exactly this
+ * site while proving the name appears nowhere else.
+ *
+ * The refusal is made TWICE, because one mechanism cannot see both halves:
+ *
+ *   - the resolver plugin catches a runtime import, which is the one that
+ *     would otherwise reach the loader and fail there;
+ *   - a scan of the authored source catches the TYPE-ONLY spellings —
+ *     `import type … from`, `export type … from`, and a plain named import
+ *     used only in type position. TypeScript erases all three, and esbuild
+ *     erases them before any resolver callback runs, so the plugin never sees
+ *     a specifier to compare. Those imports build and push silently, leaving
+ *     the stored source teaching an import that no longer exists.
+ *
+ * The scan is anchored at the start of a line so that prose about the retired
+ * name — a `//` comment, a `*` doc-comment line, a string holding an example —
+ * does not refuse a push. Missing an import someone hid mid-line is the safe
+ * direction to be wrong in; refusing a valid push is not.
+ *
+ * ── The canonical envelope encoding ──────────────────────────────────────
+ *
+ * `canonicalFunctionEnvelopeBytes` reproduces `canonicalEnvelopeBytes` in
+ * `src/services/function-bundle-storage.ts` byte for byte. The server hashes
+ * the envelope to decide whether a push is a no-op; the CLI hashes it to decide
+ * whether to make the call at all, and the two answers have to agree or a push
+ * the CLI called unchanged lands as a new version (or worse, the reverse).
+ * `cli/tests/unit/function-bundle-3179.test.ts` pins them against each other.
+ */
+/** The module the loader supplies; never bundled. */
+export declare const PRIMITIVE_FUNCTIONS_MODULE = "primitive-functions";
+/** What that module was called before #3209. Refused at push, by name. */
+export declare const RETIRED_SDK_MODULE = "primitive-sdk";
+/** Whether an authored source imports the retired module in any spelling. */
+export declare function importsRetiredModule(source: string): boolean;
+/** Matches the server's `FUNCTION_ENVELOPE_SCHEMA_VERSION`. */
+/**
+ * 2 since #3187: the envelope carries the collected query MANIFEST.
+ *
+ * Bumped rather than added quietly, because the encoding the hash is taken
+ * over changed: the manifest is part of config-version identity (D3187-SO-005)
+ * precisely so a manifest change makes a new version and a collector fix can
+ * reach a tree that was pushed before it.
+ */
+export declare const FUNCTION_ENVELOPE_SCHEMA_VERSION = 2;
+/** A push that cannot proceed: a missing entry, a build error, or an escape. */
+export declare class FunctionBuildError extends Error {
+    constructor(message: string);
+}
+export interface FunctionSourceFile {
+    /** Tree-relative, POSIX-separated — the path stored in the envelope. */
+    path: string;
+    /** The authored bytes, untouched. */
+    content: Buffer;
+}
+export interface BuiltFunctionBundle {
+    /** The entry, normalized tree-relative. */
+    entry: string;
+    /** The built bundle. */
+    bundle: Buffer;
+    /** sha256 of the bundle — what a durable run pins its code by. */
+    contentHash: string;
+    /** Every authored file the build read, sorted by path. */
+    sources: FunctionSourceFile[];
+}
+export interface EnvelopeShape {
+    schemaVersion: number;
+    entry: string;
+    toml: string;
+    sources: Array<{
+        path: string;
+        content: string;
+    }>;
+    bundle: string;
+    /** base64 of the collected manifest JSON, or null when there is none. */
+    manifest?: string | null;
+    /**
+     * base64 of the project's authored `models/models.toml` bytes, or absent
+     * when the project declares no document schema (#3455). Must stay identical
+     * to the server's `FunctionEnvelope.documentSchema`.
+     */
+    documentSchema?: string | null;
+}
+/**
+ * The canonical encoding both sides hash. Fixed key order, sources sorted by
+ * path — see the module note; this must stay identical to the server's.
+ */
+export declare function canonicalFunctionEnvelopeBytes(envelope: EnvelopeShape): Uint8Array;
+export declare function functionEnvelopeHash(envelope: EnvelopeShape): string;
+/** Whether a tree-relative path names a `node_modules` file. */
+export declare function isDependencyPath(path: string): boolean;
+/**
+ * Build one function's bundle and collect its authored sources.
+ *
+ * Throws `FunctionBuildError` — never a raw esbuild error — so `config push`
+ * has one thing to report and nothing is pushed for that function.
+ */
+export declare function buildFunctionBundle(options: {
+    /** The config tree root (`.primitive/` or the configured dir). */
+    configDir: string;
+    /** `entry` as authored in the TOML, relative to the config tree root. */
+    entry: string;
+    /** Only for the message; the key is not part of the build. */
+    functionKey: string;
+}): Promise<BuiltFunctionBundle>;

package/dist/src/lib/function-bundle.js

@@ -0,0 +1,341 @@
+/**
+ * Building a server function's bundle, in the CLI (#3179, project
+ * `server-functions`).
+ *
+ * The intent decides that the build happens here and never on the server:
+ * `config push` runs esbuild over the authored `entry`, inlines the npm
+ * dependencies, and ships the built bundle next to the authored source bytes
+ * in one envelope. The server verifies the hash and stores the object; it does
+ * not compile anything.
+ *
+ * ── The two import rules ─────────────────────────────────────────────────
+ *
+ * They look contradictory and are not (F-005):
+ *
+ *   - A **filesystem import** — relative or absolute — must stay inside the
+ *     config tree. `entry`, every import it reaches, and every symlink they
+ *     traverse are realpath-resolved and checked against the tree root, so a
+ *     push can never read a file off a developer's disk that the tree does not
+ *     contain.
+ *   - A **bare package specifier** is exempt. It resolves through Node into an
+ *     ancestor `node_modules`, which is outside every config tree by
+ *     construction; esbuild inlines it into the bundle, and it is never
+ *     captured as an authored source (so `config pull` never writes
+ *     `node_modules` content back).
+ *
+ * The exemption follows the specifier, not the path a file happens to sit at.
+ * A resolver plugin records the files a BARE specifier reached (and the files
+ * those reach in turn), so `import "../../node_modules/private/index.js"` — a
+ * relative filesystem import that merely lands in a `node_modules` directory —
+ * is still an escape and still refused. Deciding by path would have let that
+ * one specifier read any file on the disk and upload it.
+ *
+ * `primitive-functions` is the one bare specifier left EXTERNAL: the loader
+ * (#3180) supplies it at invoke time, so baking a copy into every bundle would
+ * pin the SDK version to whenever the function was last pushed.
+ *
+ * ── The retired specifier ────────────────────────────────────────────────
+ *
+ * That module was called `primitive-sdk` until #3209. This file is the one
+ * place in the repo that still writes the old name on purpose: without a
+ * detector, an author who copied an older example gets esbuild's generic
+ * `Could not resolve "primitive-sdk"`, which reads as a missing dependency
+ * rather than a rename. `RETIRED_SDK_MODULE` below is that detector, and
+ * `cli/tests/unit/retired-sdk-name-guard-3209.test.ts` allowlists exactly this
+ * site while proving the name appears nowhere else.
+ *
+ * The refusal is made TWICE, because one mechanism cannot see both halves:
+ *
+ *   - the resolver plugin catches a runtime import, which is the one that
+ *     would otherwise reach the loader and fail there;
+ *   - a scan of the authored source catches the TYPE-ONLY spellings —
+ *     `import type … from`, `export type … from`, and a plain named import
+ *     used only in type position. TypeScript erases all three, and esbuild
+ *     erases them before any resolver callback runs, so the plugin never sees
+ *     a specifier to compare. Those imports build and push silently, leaving
+ *     the stored source teaching an import that no longer exists.
+ *
+ * The scan is anchored at the start of a line so that prose about the retired
+ * name — a `//` comment, a `*` doc-comment line, a string holding an example —
+ * does not refuse a push. Missing an import someone hid mid-line is the safe
+ * direction to be wrong in; refusing a valid push is not.
+ *
+ * ── The canonical envelope encoding ──────────────────────────────────────
+ *
+ * `canonicalFunctionEnvelopeBytes` reproduces `canonicalEnvelopeBytes` in
+ * `src/services/function-bundle-storage.ts` byte for byte. The server hashes
+ * the envelope to decide whether a push is a no-op; the CLI hashes it to decide
+ * whether to make the call at all, and the two answers have to agree or a push
+ * the CLI called unchanged lands as a new version (or worse, the reverse).
+ * `cli/tests/unit/function-bundle-3179.test.ts` pins them against each other.
+ */
+import * as esbuild from "esbuild";
+import { createHash } from "crypto";
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { isAbsolute, relative, resolve, sep } from "path";
+/** The module the loader supplies; never bundled. */
+export const PRIMITIVE_FUNCTIONS_MODULE = "primitive-functions";
+/** What that module was called before #3209. Refused at push, by name. */
+export const RETIRED_SDK_MODULE = "primitive-sdk";
+/** The refusal both detectors report, so an author reads one sentence. */
+const retiredModuleRefusal = () => `the '${RETIRED_SDK_MODULE}' module was renamed: import from ` +
+    `'${PRIMITIVE_FUNCTIONS_MODULE}' instead`;
+/**
+ * Import and export forms naming the retired module, in the type-only
+ * spellings esbuild erases before the resolver plugin can see them (see the
+ * module note). Anchored at the start of a line, and the specifier must be the
+ * WHOLE quoted string, so `primitive-sdk-utils` and `./primitive-sdk.js` are
+ * untouched — the same exact match the plugin makes.
+ */
+const RETIRED_IMPORT_FORMS = [
+    // `import type { X } from "…"`, `export type { X } from "…"`, `export * from
+    // "…"`, and every value spelling in between, on one line.
+    new RegExp(`^[ \\t]*(?:import|export)[ \\t\\w*{},$]*[ \\t]from[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+    // The tail of a multi-line named list: `} from "…"`.
+    new RegExp(`^[ \\t]*\\}[ \\t]*from[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+    // A bare side-effect import. The plugin catches this one too; it costs
+    // nothing to be sure the scan agrees with it.
+    new RegExp(`^[ \\t]*import[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+];
+/** Whether an authored source imports the retired module in any spelling. */
+export function importsRetiredModule(source) {
+    return RETIRED_IMPORT_FORMS.some((pattern) => pattern.test(source));
+}
+/** Matches the server's `FUNCTION_ENVELOPE_SCHEMA_VERSION`. */
+/**
+ * 2 since #3187: the envelope carries the collected query MANIFEST.
+ *
+ * Bumped rather than added quietly, because the encoding the hash is taken
+ * over changed: the manifest is part of config-version identity (D3187-SO-005)
+ * precisely so a manifest change makes a new version and a collector fix can
+ * reach a tree that was pushed before it.
+ */
+export const FUNCTION_ENVELOPE_SCHEMA_VERSION = 2;
+/** A push that cannot proceed: a missing entry, a build error, or an escape. */
+export class FunctionBuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FunctionBuildError";
+    }
+}
+/**
+ * The canonical encoding both sides hash. Fixed key order, sources sorted by
+ * path — see the module note; this must stay identical to the server's.
+ */
+export function canonicalFunctionEnvelopeBytes(envelope) {
+    const canonical = {
+        schemaVersion: envelope.schemaVersion,
+        entry: envelope.entry,
+        toml: envelope.toml,
+        sources: [...envelope.sources]
+            .map((s) => ({ path: s.path, content: s.content }))
+            .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+        bundle: envelope.bundle,
+        // #3187 — inside the hash, so a manifest change is a new version.
+        // `null` rather than absent when there is none, so the encoding of a
+        // manifest-less push is stable rather than depending on a missing key.
+        manifest: envelope.manifest ?? null,
+        // #3455 — the twin of the server's rule: the key is emitted ONLY when
+        // there is a schema, so a tree with no `models/models.toml` builds the
+        // same bytes it built before this change and its no-op detection is
+        // intact. `undefined` would be dropped by `JSON.stringify` anyway; the
+        // spread says the rule rather than relying on that.
+        ...(typeof envelope.documentSchema === "string" && envelope.documentSchema
+            ? { documentSchema: envelope.documentSchema }
+            : {}),
+    };
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+export function functionEnvelopeHash(envelope) {
+    return createHash("sha256")
+        .update(Buffer.from(canonicalFunctionEnvelopeBytes(envelope)))
+        .digest("hex");
+}
+/** POSIX spelling, so a Windows push stores the same paths a macOS one does. */
+const toPosix = (value) => value.split(sep).join("/");
+/** Whether a tree-relative path names a `node_modules` file. */
+export function isDependencyPath(path) {
+    return path.split("/").includes("node_modules");
+}
+/**
+ * `null` when `candidate` is inside `root`, else the tree-relative-ish spelling
+ * to name in the refusal. Lexical only — the caller realpaths first.
+ */
+function outsideRoot(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return null;
+    return toPosix(rel);
+}
+function escapeRefusal(what, path) {
+    return new FunctionBuildError(`${what} '${path}' resolves outside the config tree root. ` +
+        "Filesystem imports must stay inside the config tree; npm packages are " +
+        "imported by name and inlined into the bundle.");
+}
+/**
+ * Build one function's bundle and collect its authored sources.
+ *
+ * Throws `FunctionBuildError` — never a raw esbuild error — so `config push`
+ * has one thing to report and nothing is pushed for that function.
+ */
+export async function buildFunctionBundle(options) {
+    const { configDir, entry, functionKey } = options;
+    const treeRoot = realpathSync(resolve(configDir));
+    // 1. The entry, lexically. An escaping entry is refused as an escape even
+    //    when the file it names does not exist — "no such file" would be a
+    //    misleading answer to `entry = "../../etc/passwd"`.
+    const entryAbs = resolve(treeRoot, entry);
+    const entryEscape = outsideRoot(treeRoot, entryAbs);
+    if (entryEscape !== null)
+        throw escapeRefusal("entry", toPosix(entry));
+    if (!existsSync(entryAbs)) {
+        throw new FunctionBuildError(`function '${functionKey}': entry file '${toPosix(entry)}' does not exist`);
+    }
+    // 2. …and after symlinks.
+    const entryReal = realpathSync(entryAbs);
+    if (outsideRoot(treeRoot, entryReal) !== null) {
+        throw escapeRefusal("entry", toPosix(entry));
+    }
+    const entryRelative = toPosix(relative(treeRoot, entryReal));
+    // Which files a BARE specifier reached. Membership — not the presence of a
+    // `node_modules` segment in the path — is what exempts a file from the tree
+    // boundary, so a relative or absolute import can never buy the exemption by
+    // pointing at a `node_modules` directory (see the module note).
+    const dependencyFiles = new Set();
+    const rememberDependency = (path) => {
+        if (!path)
+            return;
+        dependencyFiles.add(path);
+        try {
+            dependencyFiles.add(realpathSync(path));
+        }
+        catch {
+            /* a virtual or already-resolved path; the raw spelling is enough */
+        }
+    };
+    const isDependencyFile = (path) => {
+        if (dependencyFiles.has(path))
+            return true;
+        try {
+            return dependencyFiles.has(realpathSync(path));
+        }
+        catch {
+            return false;
+        }
+    };
+    const importBoundaryPlugin = {
+        name: "primitive-function-import-boundary",
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, async (args) => {
+                // The nested `build.resolve` below re-enters this callback; the marker
+                // is what stops it recursing forever.
+                if (args.pluginData?.primitiveBoundaryResolved)
+                    return null;
+                if (args.kind === "entry-point")
+                    return null;
+                // The retired specifier, refused before esbuild can report it as a
+                // missing package (#3209). An EXACT match only: `primitive-sdk-utils`
+                // is a different package and `./primitive-sdk.ts` is a tree-local file,
+                // and both still resolve normally.
+                if (args.path === RETIRED_SDK_MODULE) {
+                    return { errors: [{ text: retiredModuleRefusal() }] };
+                }
+                const bare = !args.path.startsWith(".") && !isAbsolute(args.path);
+                // A dependency's own relative imports are dependency files too — the
+                // exemption is inherited down the package's internal graph.
+                const fromDependency = !!args.importer && isDependencyFile(args.importer);
+                if (!bare && !fromDependency)
+                    return null;
+                const resolved = await build.resolve(args.path, {
+                    importer: args.importer,
+                    namespace: args.namespace,
+                    resolveDir: args.resolveDir,
+                    kind: args.kind,
+                    pluginData: { primitiveBoundaryResolved: true },
+                });
+                // Let esbuild resolve (and report) it the way it would have; nothing
+                // was recorded, so an unresolvable import stays esbuild's error.
+                if (resolved.errors.length > 0)
+                    return null;
+                if (!resolved.external && resolved.path) {
+                    rememberDependency(resolved.path);
+                }
+                return resolved;
+            });
+        },
+    };
+    let result;
+    try {
+        result = await esbuild.build({
+            entryPoints: [entryRelative],
+            absWorkingDir: treeRoot,
+            bundle: true,
+            write: false,
+            metafile: true,
+            format: "esm",
+            platform: "neutral",
+            target: "es2022",
+            // The loader supplies it; see the module note.
+            external: [PRIMITIVE_FUNCTIONS_MODULE],
+            plugins: [importBoundaryPlugin],
+            logLevel: "silent",
+        });
+    }
+    catch (error) {
+        const messages = Array.isArray(error?.errors)
+            ? error.errors.map((e) => {
+                const where = e?.location?.file
+                    ? toPosix(String(e.location.file))
+                    : toPosix(entry);
+                const line = e?.location?.line ? `:${e.location.line}` : "";
+                return `  ${where}${line}: ${e?.text ?? "build error"}`;
+            })
+            : [`  ${toPosix(entry)}: ${error?.message ?? String(error)}`];
+        throw new FunctionBuildError(`function '${functionKey}' failed to build:\n${messages.join("\n")}`);
+    }
+    const output = result.outputFiles?.[0];
+    if (!output) {
+        throw new FunctionBuildError(`function '${functionKey}': the build produced no output for '${toPosix(entry)}'`);
+    }
+    const bundle = Buffer.from(output.contents);
+    // 3. Every file the build actually read, from the metafile — the honest list,
+    //    rather than a re-parse of the imports. A file a BARE specifier reached is
+    //    an inlined dependency and is dropped; every other input is a filesystem
+    //    import, and one outside the tree is an escape esbuild followed that the
+    //    push refuses.
+    const sources = [];
+    for (const input of Object.keys(result.metafile?.inputs ?? {})) {
+        const path = toPosix(input);
+        const absolute = resolve(treeRoot, input);
+        if (isDependencyFile(absolute))
+            continue;
+        if (path.startsWith("..") || isAbsolute(input)) {
+            throw escapeRefusal("import", path);
+        }
+        if (outsideRoot(treeRoot, realpathSync(absolute)) !== null) {
+            throw escapeRefusal("import", path);
+        }
+        // In-tree `node_modules` reached by a filesystem import: inside the
+        // boundary, so it builds — but `config pull` refuses to write a stored
+        // `node_modules` path, so capturing it would promise a round trip that
+        // cannot be kept.
+        if (isDependencyPath(path))
+            continue;
+        const content = readFileSync(absolute);
+        // The type-only half of the retired-specifier refusal (see the module
+        // note): esbuild erased these imports before the plugin could see them,
+        // so the build succeeded and the source would have been stored as pushed.
+        if (importsRetiredModule(content.toString("utf-8"))) {
+            throw new FunctionBuildError(`function '${functionKey}' failed to build:\n  ${path}: ${retiredModuleRefusal()}`);
+        }
+        sources.push({ path, content });
+    }
+    sources.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+        entry: entryRelative,
+        bundle,
+        contentHash: createHash("sha256").update(bundle).digest("hex"),
+        sources,
+    };
+}
+//# sourceMappingURL=function-bundle.js.map