@vendure/cloud 0.2.0 → 0.3.0

package/dist/local-cache-plugin.js

@@ -0,0 +1,68 @@
+import { CLOUD_PLUGIN_COMPATIBILITY } from "@vendure/cloud-config";
+import { RedisCacheStrategy, VendurePlugin } from "@vendure/core";
+import { assertLocalCacheReachable } from "./local-cache.js";
+// The local substitute for the cache capability (ADR-0017). The protocol work is Vendure's own
+// `RedisCacheStrategy`, which stores a value and its tag memberships in one transaction and declares
+// no entity. `PlatformCacheStrategy` is not reused: it is in a private package that already depends
+// on this one, and everything it adds is production infrastructure — a SigV4 IAM token per
+// connection, mandatory TLS, and an RBAC-user key prefix.
+// One namespace, fixed rather than derived, because the separately supervised server and worker
+// each compose their own configuration and have to arrive at the same keyspace. Two projects
+// sharing one server are separated by the connection's database index instead.
+export const LOCAL_CACHE_NAMESPACE = "vendure-cloud-local";
+// Vendure's cache service calls this during bootstrap, which is where a cache that is not there has
+// to be reported. The upstream strategy constructs its client and never awaits a connection, so an
+// unreachable server would otherwise surface as a repeating client error and a store that quietly
+// caches nothing.
+class LocalCacheStrategy extends RedisCacheStrategy {
+    connection;
+    constructor(connection) {
+        super({
+            namespace: LOCAL_CACHE_NAMESPACE,
+            // No `maxItemSizeInBytes`, which is the strategy's own default when it is constructed
+            // directly. The managed cache strategy imposes no size limit either, and a limit that exists
+            // only locally would drop an entry the deployed store keeps.
+            redisOptions: {
+                host: connection.host,
+                port: connection.port,
+                username: connection.username,
+                password: connection.password,
+                db: connection.db,
+            },
+        });
+        this.connection = connection;
+    }
+    async init() {
+        await assertLocalCacheReachable(this.connection);
+        await super.init();
+    }
+}
+// A plugin of the platform's own rather than upstream `RedisCachePlugin`.
+//
+// **Do not rename this to an upstream plugin's name.** `assertNoCustomerPluginWroteAPlatformField`
+// ignores writes made under the names the composed Cloud Plugins carry, so an upstream name here
+// would exempt a customer's own copy of that plugin: they would set
+// `systemOptions.cacheStrategy`, this composition would overwrite it, and the boot would succeed
+// with their strategy discarded. That is CLO-429's failure, and it is what the managed runtime's
+// `CloudCachePlugin` carries the same warning about. Under a name of its own, a customer declaring
+// `DefaultCachePlugin` or `RedisCachePlugin` is refused here for the same reason and with the same
+// message as in a deployed environment.
+//
+// A class per call, holding its strategy in a closure rather than in a module-level variable. Two
+// compositions in one process are what `test/local-cache.integration.test.ts` uses to stand in for
+// the separately supervised server and worker, and a shared variable would give both of them one
+// strategy — so the suite would pass while proving nothing.
+export function localCachePlugin(connection) {
+    const strategy = new LocalCacheStrategy(connection);
+    class LocalCachePlugin {
+    }
+    VendurePlugin({
+        compatibility: CLOUD_PLUGIN_COMPATIBILITY,
+        configuration: (config) => {
+            config.systemOptions.cacheStrategy = strategy;
+            return config;
+        },
+    })(LocalCachePlugin);
+    return LocalCachePlugin;
+}
+//# sourceMappingURL=local-cache-plugin.js.map

package/dist/local-cache-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-cache-plugin.js","sourceRoot":"","sources":["../src/local-cache-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAmB,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAA6B,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAExF,+FAA+F;AAC/F,qGAAqG;AACrG,oGAAoG;AACpG,2FAA2F;AAC3F,0DAA0D;AAE1D,gGAAgG;AAChG,6FAA6F;AAC7F,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAE3D,oGAAoG;AACpG,mGAAmG;AACnG,kGAAkG;AAClG,kBAAkB;AAClB,MAAM,kBAAmB,SAAQ,kBAAkB;IACpB;IAA7B,YAA6B,UAAgC;QAC3D,KAAK,CAAC;YACJ,SAAS,EAAE,qBAAqB;YAChC,sFAAsF;YACtF,6FAA6F;YAC7F,6DAA6D;YAC7D,YAAY,EAAE;gBACZ,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,EAAE,EAAE,UAAU,CAAC,EAAE;aAClB;SACF,CAAC,CAAC;QAbwB,eAAU,GAAV,UAAU,CAAsB;IAc7D,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,yBAAyB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;CACF;AAED,0EAA0E;AAC1E,EAAE;AACF,mGAAmG;AACnG,iGAAiG;AACjG,oEAAoE;AACpE,iGAAiG;AACjG,iGAAiG;AACjG,mGAAmG;AACnG,mGAAmG;AACnG,wCAAwC;AACxC,EAAE;AACF,kGAAkG;AAClG,mGAAmG;AACnG,iGAAiG;AACjG,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,UAAgC;IAC/D,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAEpD,MAAM,gBAAgB;KAAG;IAEzB,aAAa,CAAC;QACZ,aAAa,EAAE,0BAA0B;QACzC,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE;YACxB,MAAM,CAAC,aAAa,CAAC,aAAa,GAAG,QAAQ,CAAC;YAC9C,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAErB,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/dist/local-cache.d.ts

@@ -0,0 +1,17 @@
+export interface LocalCacheConnection {
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+    db?: number;
+}
+export declare const LOCAL_CACHE_URL_VAR = "VENDURE_LOCAL_CACHE_URL";
+export declare class LocalCacheUnavailableError extends Error {
+    constructor(detail: string, options?: ErrorOptions);
+}
+export declare function resolveLocalCache(supplied: LocalCacheConnection | undefined, environment: NodeJS.ProcessEnv): LocalCacheConnection;
+export declare function parseLocalCacheUrl(url: string): LocalCacheConnection;
+export declare function describeLocalCache(connection: LocalCacheConnection): string;
+export declare function assertLocalCacheDriverAvailable(): void;
+export declare function assertLocalCacheReachable(connection: LocalCacheConnection): Promise<void>;
+//# sourceMappingURL=local-cache.d.ts.map

package/dist/local-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-cache.d.ts","sourceRoot":"","sources":["../src/local-cache.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IAGb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAQD,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAS7D,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAOnD;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,WAAW,EAAE,MAAM,CAAC,UAAU,GAC7B,oBAAoB,CAQtB;AAKD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAsBpE;AA8BD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,GAAG,MAAM,CAG3E;AAKD,wBAAgB,+BAA+B,IAAI,IAAI,CAStD;AASD,wBAAsB,yBAAyB,CAAC,UAAU,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C/F"}

package/dist/local-cache.js

@@ -0,0 +1,144 @@
+import { createRequire } from "node:module";
+// The variable `vendure dev` sets when it runs the server or the worker as a child process,
+// carrying the cache it provisioned. The in-process form is `LocalRuntimeOptions`'s `cache`, and
+// both resolve to the same shape.
+//
+// Deliberately not a `VC_*` name, for the reason `LOCAL_DATABASE_URL_VAR` is not one: ADR-0043
+// makes `VC_*` the signal that a process is a platform process and must refuse local substitutes.
+export const LOCAL_CACHE_URL_VAR = "VENDURE_LOCAL_CACHE_URL";
+// Both spellings of the same wire protocol. Valkey is the engine, and `redis://` is the scheme
+// every client and every URL that predates the fork uses for it, so refusing one of them would
+// refuse a correct connection string over its spelling.
+const CACHE_URL_SCHEMES = ["valkey:", "redis:"];
+const DEFAULT_CACHE_PORT = 6379;
+export class LocalCacheUnavailableError extends Error {
+    constructor(detail, options) {
+        super(`Vendure Cloud: the local runtime needs a Valkey cache, and ${detail}\n  \`vendure dev\` provisions one, keeps it between runs and passes its connection to this process. Start the application through it rather than running this process directly.\n`, options);
+        this.name = "LocalCacheUnavailableError";
+    }
+}
+export function resolveLocalCache(supplied, environment) {
+    if (supplied)
+        return supplied;
+    const url = environment[LOCAL_CACHE_URL_VAR];
+    if (url === undefined || url === "") {
+        throw new LocalCacheUnavailableError("no connection was supplied to it.");
+    }
+    return parseLocalCacheUrl(url);
+}
+// Parsed here rather than handed to the client as a URL string, so that the announcement can name
+// the host without printing the password beside it, and so that a malformed value is our message
+// rather than a client's.
+export function parseLocalCacheUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new LocalCacheUnavailableError(`${LOCAL_CACHE_URL_VAR} is not a URL. It carries a valkey:// connection string.`);
+    }
+    if (!CACHE_URL_SCHEMES.includes(parsed.protocol)) {
+        throw new LocalCacheUnavailableError(`${LOCAL_CACHE_URL_VAR} names the ${parsed.protocol.replace(":", "")} scheme, and the local cache is reached over ${CACHE_URL_SCHEMES.map((scheme) => `${scheme}//`).join(" or ")}. A local cache is on loopback and is not encrypted.`);
+    }
+    return {
+        host: parsed.hostname === "" ? "127.0.0.1" : decodeURIComponent(parsed.hostname),
+        port: parsed.port === "" ? DEFAULT_CACHE_PORT : Number(parsed.port),
+        username: optionalCredential(parsed.username),
+        password: optionalCredential(parsed.password),
+        db: parseDatabaseIndex(parsed.pathname),
+    };
+}
+// Empty userinfo is absent rather than an empty credential. `new URL` reports both as "", and
+// presenting an empty username to a server that wants none is refused rather than ignored.
+function optionalCredential(value) {
+    return value === "" ? undefined : decodeURIComponent(value);
+}
+// The path of a cache URL is the logical database index, the way the path of a PostgreSQL URL is
+// the database name. Read rather than ignored: a caller that wrote one and had it dropped would
+// share a keyspace it believed it had left.
+//
+// Matched against digits before it is converted, rather than converted and then checked. `Number`
+// reads `1e2` as 100 and `0x9` as 9, both of which are integers, so a check on the converted value
+// alone accepts spellings this message says are not allowed and silently picks a database the
+// caller did not name.
+function parseDatabaseIndex(pathname) {
+    const path = pathname.replace(/^\//, "");
+    if (path === "")
+        return undefined;
+    if (!/^\d+$/.test(path)) {
+        throw new LocalCacheUnavailableError(`${LOCAL_CACHE_URL_VAR} names ${JSON.stringify(path)} as its database. The path of the URL is the logical database index, written as digits: a whole number from zero up.`);
+    }
+    return Number(path);
+}
+// For the startup announcement, which goes to a terminal and into whatever collects that terminal's
+// output, so it names the server without the password used to reach it.
+export function describeLocalCache(connection) {
+    const database = connection.db === undefined ? "" : `, database ${connection.db}`;
+    return `Valkey at ${connection.host}:${connection.port}${database}`;
+}
+// The client is an optional peer dependency, so it is absent from a tree that never runs locally.
+// Resolved rather than imported, because the cache strategy is what loads it and this only has to
+// decide whether the failure is ours to explain.
+export function assertLocalCacheDriverAvailable() {
+    try {
+        createRequire(import.meta.url).resolve("ioredis");
+    }
+    catch (cause) {
+        throw new Error("Vendure Cloud: connecting to the local Valkey cache requires ioredis. Install it as a development dependency; deployed images carry their own copy.", { cause });
+    }
+}
+// One connection, opened and closed, before anything that will keep one opens it. The probe is what
+// turns an absent cache into a single actionable message naming the server that did not answer,
+// rather than into a client retrying in the background for the life of the process.
+//
+// A `vendure dev` run makes this check twice, deliberately: once in the command, which is what
+// stops a refused cache from reaching a process at all, and once in the cache strategy as it boots,
+// which is the check a process started any other way still gets.
+export async function assertLocalCacheReachable(connection) {
+    // Imported here rather than at module scope. `ioredis` is an optional peer dependency, so an
+    // application that never composes a local configuration must not load it, and `local-runtime.ts`
+    // has already reported its absence by the time this runs.
+    const { Redis } = await import("ioredis");
+    const probe = new Redis({
+        host: connection.host,
+        port: connection.port,
+        username: connection.username,
+        password: connection.password,
+        db: connection.db,
+        lazyConnect: true,
+        // One attempt. The point of this connection is to answer whether the cache is there now, and a
+        // client that retries in the background answers it by hanging.
+        retryStrategy: () => null,
+        maxRetriesPerRequest: 1,
+        enableOfflineQueue: false,
+    });
+    // Without a listener, `ioredis` treats a connection error as an unhandled error event and takes
+    // the process down before the message below is ever built.
+    probe.on("error", () => undefined);
+    try {
+        await probe.connect();
+        await probe.ping();
+        // `SELECT` again, explicitly, when an index was asked for. `ioredis` selects the database while
+        // it connects, but it reports a refusal as an `error` event rather than by failing the connect —
+        // so an index the server does not have leaves an open, working connection on database 0. Every
+        // key then lands in a keyspace the caller believed it had left, which is the whole failure the
+        // index exists to prevent. Issued as a command, its rejection is ours to catch.
+        if (connection.db !== undefined) {
+            await probe.select(connection.db);
+        }
+    }
+    catch (cause) {
+        // The server's own reason, not just the fact that this did not complete. A cache that answered
+        // and refused the credentials, or refused the database index, is a different problem from one
+        // that is not running, and a message saying only that nothing answered sends the reader to the
+        // wrong place.
+        throw new LocalCacheUnavailableError(`${describeLocalCache(connection)} did not accept a connection: ${describe(cause)}`, { cause });
+    }
+    finally {
+        probe.disconnect();
+    }
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+//# sourceMappingURL=local-cache.js.map

package/dist/local-cache.js.map

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

package/dist/local-dashboard-plugin.d.ts

@@ -0,0 +1,9 @@
+import type { PluginLike } from "@vendure/cloud-config";
+export interface LocalDashboardOptions {
+    route: string;
+    appDir: string;
+    viteDevServerPort: number;
+}
+export declare const DEFAULT_VITE_DEV_SERVER_PORT = 5173;
+export declare function localDashboardPlugin(options: LocalDashboardOptions): PluginLike;
+//# sourceMappingURL=local-dashboard-plugin.d.ts.map

package/dist/local-dashboard-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-dashboard-plugin.d.ts","sourceRoot":"","sources":["../src/local-dashboard-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQxD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAKD,eAAO,MAAM,4BAA4B,OAAO,CAAC;AASjD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAE/E"}

package/dist/local-dashboard-plugin.js

@@ -0,0 +1,37 @@
+import { createRequire } from "node:module";
+// `vite`'s own default port, which is where a developer running the Dashboard's development server
+// lands unless they moved it. Passed to the plugin explicitly rather than left to its default, so
+// the startup announcement names the port that is actually being probed.
+export const DEFAULT_VITE_DEV_SERVER_PORT = 5173;
+export function localDashboardPlugin(options) {
+    return loadUpstreamDashboardPlugin().init(options);
+}
+// `@vendure/dashboard` is an optional peer dependency, loaded here when the Dashboard capability is
+// composed and never at import time. Two things follow. A customer's application does not carry it
+// into a managed build, where the build installs and prunes it itself. And an application that
+// never composes a local configuration does not pay for it: the plugin's entry point loads a few
+// hundred modules of its own, against the facade's budget in `published-output.test.ts`.
+//
+// Resolved before it is required, so that a package that is not installed produces the message
+// below and a package that is installed but throws while loading produces its own error rather than
+// advice to install what is already there.
+function loadUpstreamDashboardPlugin() {
+    const require = createRequire(import.meta.url);
+    try {
+        require.resolve("@vendure/dashboard/plugin");
+    }
+    catch (cause) {
+        throw new Error("Vendure Cloud: serving the Dashboard locally requires @vendure/dashboard. Install it as a development dependency; deployed images build the Dashboard and do not install it.", { cause });
+    }
+    const module = require("@vendure/dashboard/plugin");
+    const exported = module?.DashboardPlugin;
+    if (!isUpstreamDashboardPlugin(exported)) {
+        throw new Error("Vendure Cloud: the installed @vendure/dashboard does not export a DashboardPlugin with an init method. Install a version compatible with the @vendure/core this application declares.");
+    }
+    return exported;
+}
+function isUpstreamDashboardPlugin(value) {
+    return (typeof value === "function" &&
+        typeof value.init === "function");
+}
+//# sourceMappingURL=local-dashboard-plugin.js.map

package/dist/local-dashboard-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-dashboard-plugin.js","sourceRoot":"","sources":["../src/local-dashboard-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAe5C,mGAAmG;AACnG,kGAAkG;AAClG,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AASjD,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,OAAO,2BAA2B,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACrD,CAAC;AAED,oGAAoG;AACpG,mGAAmG;AACnG,+FAA+F;AAC/F,iGAAiG;AACjG,yFAAyF;AACzF,EAAE;AACF,+FAA+F;AAC/F,oGAAoG;AACpG,2CAA2C;AAC3C,SAAS,2BAA2B;IAClC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,8KAA8K,EAC9K,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAY,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAa,MAA+C,EAAE,eAAe,CAAC;IAC5F,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,uLAAuL,CACxL,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,UAAU;QAC3B,OAAQ,KAA0C,CAAC,IAAI,KAAK,UAAU,CACvE,CAAC;AACJ,CAAC"}

package/dist/local-database.d.ts

@@ -0,0 +1,15 @@
+export interface LocalDatabaseConnection {
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+}
+export declare const LOCAL_DATABASE_URL_VAR = "VENDURE_LOCAL_DATABASE_URL";
+export declare class LocalDatabaseUnavailableError extends Error {
+    constructor(detail: string);
+}
+export declare function resolveLocalDatabase(supplied: LocalDatabaseConnection | undefined, environment: NodeJS.ProcessEnv): LocalDatabaseConnection;
+export declare function parseLocalDatabaseUrl(url: string): LocalDatabaseConnection;
+export declare function assertLocalDatabaseDriverAvailable(): void;
+//# sourceMappingURL=local-database.d.ts.map

package/dist/local-database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-database.d.ts","sourceRoot":"","sources":["../src/local-database.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,MAAM,EAAE,MAAM;CAM3B;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,EAC7C,WAAW,EAAE,MAAM,CAAC,UAAU,GAC7B,uBAAuB,CAQzB;AAKD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CA+B1E;AAKD,wBAAgB,kCAAkC,IAAI,IAAI,CASzD"}

package/dist/local-database.js

@@ -0,0 +1,64 @@
+import { createRequire } from "node:module";
+// The variable `vendure dev` sets when it runs the server, the worker or a migration as a child
+// process, carrying the connection it provisioned. The in-process form is `LocalRuntimeOptions`'s
+// `database`, and both resolve to the same shape.
+//
+// Deliberately not a `VC_*` name. ADR-0043 makes `VC_*` the signal that a process is a platform
+// process and must refuse local substitutes, so a local variable under that prefix would be a
+// name in the space of the thing it is the opposite of.
+export const LOCAL_DATABASE_URL_VAR = "VENDURE_LOCAL_DATABASE_URL";
+export class LocalDatabaseUnavailableError extends Error {
+    constructor(detail) {
+        super(`Vendure Cloud: the local runtime needs a PostgreSQL database, and ${detail}\n  \`vendure dev\` provisions one, keeps it between runs and passes its connection to this process. Start the application through it rather than running this process directly.\n`);
+        this.name = "LocalDatabaseUnavailableError";
+    }
+}
+export function resolveLocalDatabase(supplied, environment) {
+    if (supplied)
+        return supplied;
+    const url = environment[LOCAL_DATABASE_URL_VAR];
+    if (url === undefined || url === "") {
+        throw new LocalDatabaseUnavailableError("no connection was supplied to it.");
+    }
+    return parseLocalDatabaseUrl(url);
+}
+// Parsed here rather than handed to TypeORM as a `url`, so that the announcement can name the host
+// and the database without printing the password beside them, and so that a malformed value is our
+// message rather than a driver's.
+export function parseLocalDatabaseUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new LocalDatabaseUnavailableError(`${LOCAL_DATABASE_URL_VAR} is not a URL. It carries a postgres:// connection string.`);
+    }
+    if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") {
+        throw new LocalDatabaseUnavailableError(`${LOCAL_DATABASE_URL_VAR} names the ${parsed.protocol.replace(":", "")} scheme. A deployed VC Environment runs PostgreSQL, so the local runtime does too.`);
+    }
+    // The path is `/database`, so one leading slash comes off and anything left is a name a
+    // PostgreSQL database cannot have.
+    const database = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
+    if (database === "" || database.includes("/")) {
+        throw new LocalDatabaseUnavailableError(`${LOCAL_DATABASE_URL_VAR} names no database. The path of the URL is the database name.`);
+    }
+    return {
+        host: parsed.hostname === "" ? "127.0.0.1" : decodeURIComponent(parsed.hostname),
+        port: parsed.port === "" ? 5432 : Number(parsed.port),
+        database,
+        username: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password),
+    };
+}
+// The driver is an optional peer dependency, so it is absent from a tree that never runs locally.
+// Resolved rather than imported, because TypeORM is what loads it and this only has to decide
+// whether the failure is ours to explain.
+export function assertLocalDatabaseDriverAvailable() {
+    try {
+        createRequire(import.meta.url).resolve("pg");
+    }
+    catch (cause) {
+        throw new Error("Vendure Cloud: connecting to a local PostgreSQL database requires pg. Install it as a development dependency; deployed images carry their own copy.", { cause });
+    }
+}
+//# sourceMappingURL=local-database.js.map

package/dist/local-database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-database.js","sourceRoot":"","sources":["../src/local-database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAuB5C,gGAAgG;AAChG,kGAAkG;AAClG,kDAAkD;AAClD,EAAE;AACF,gGAAgG;AAChG,8FAA8F;AAC9F,wDAAwD;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAEnE,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,YAAY,MAAc;QACxB,KAAK,CACH,qEAAqE,MAAM,oLAAoL,CAChQ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAClC,QAA6C,EAC7C,WAA8B;IAE9B,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,GAAG,GAAG,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAChD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,6BAA6B,CAAC,mCAAmC,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,qBAAqB,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,mGAAmG;AACnG,mGAAmG;AACnG,kCAAkC;AAClC,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,6BAA6B,CACrC,GAAG,sBAAsB,4DAA4D,CACtF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACzE,MAAM,IAAI,6BAA6B,CACrC,GAAG,sBAAsB,cAAc,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,oFAAoF,CAC5J,CAAC;IACJ,CAAC;IAED,wFAAwF;IACxF,mCAAmC;IACnC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACxE,IAAI,QAAQ,KAAK,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,6BAA6B,CACrC,GAAG,sBAAsB,+DAA+D,CACzF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC;QAChF,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACrD,QAAQ;QACR,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC7C,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,8FAA8F;AAC9F,0CAA0C;AAC1C,MAAM,UAAU,kCAAkC;IAChD,IAAI,CAAC;QACH,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,qJAAqJ,EACrJ,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/local-runtime.d.ts

@@ -1,7 +1,14 @@
-import { type CloudConfigHandle } from "@vendure/cloud-config";
+import { type CloudConfigHandle, type MigrationClass } from "@vendure/cloud-config";
 import { type VendureConfig, bootstrap, bootstrapWorker } from "@vendure/core";
+import { type LocalCacheConnection } from "./local-cache.js";
+import { type LocalDatabaseConnection } from "./local-database.js";
 export interface LocalRuntimeOptions {
-    databasePath?: string;
+    database?: LocalDatabaseConnection;
+    cache?: LocalCacheConnection;
+    migrations?: readonly MigrationClass[];
+    assetUploadDir?: string;
+    dashboardAppDir?: string;
+    dashboardViteDevServerPort?: number;
     port?: number;
     superadminIdentifier?: string;
     superadminPassword?: string;
@@ -10,5 +17,11 @@ export interface LocalRuntimeOptions {
 export declare function bootstrapLocalServer(handle: CloudConfigHandle, options?: LocalRuntimeOptions): ReturnType<typeof bootstrap>;
 export declare function bootstrapLocalWorker(handle: CloudConfigHandle, options?: LocalRuntimeOptions): ReturnType<typeof bootstrapWorker>;
 export declare function runLocalMigrations(handle: CloudConfigHandle, options?: LocalRuntimeOptions): Promise<void>;
+export declare class LocalMigrationFailedError extends Error {
+    constructor();
+}
+export declare class NoDeclaredMigrationsError extends Error {
+    constructor();
+}
 export declare function composeLocalConfig(handle: CloudConfigHandle, options?: LocalRuntimeOptions): VendureConfig;
 //# sourceMappingURL=local-runtime.d.ts.map

package/dist/local-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-runtime.d.ts","sourceRoot":"","sources":["../src/local-runtime.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,iBAAiB,EAKvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAML,KAAK,aAAa,EAElB,SAAS,EACT,eAAe,EAEhB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAAC,OAAO,SAAS,CAAC,CAE9B;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAAC,OAAO,eAAe,CAAC,CAEpC;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,aAAa,CAoCf"}
+{"version":3,"file":"local-runtime.d.ts","sourceRoot":"","sources":["../src/local-runtime.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAWpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAKL,KAAK,aAAa,EAElB,SAAS,EACT,eAAe,EAEhB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,oBAAoB,EAI1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,KAAK,uBAAuB,EAG7B,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,WAAW,mBAAmB;IAGlC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAInC,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAG7B,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAGvC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAAC,OAAO,SAAS,CAAC,CAE9B;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAAC,OAAO,eAAe,CAAC,CAEpC;AAID,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,qBAAa,yBAA0B,SAAQ,KAAK;;CAOnD;AAED,qBAAa,yBAA0B,SAAQ,KAAK;;CAanD;AAsBD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,aAAa,CAkFf"}