@jant/core 0.6.15 → 0.7.0

package/bin/lib/node-env.js

@@ -22,13 +22,46 @@ function fileExists(envPath) {
 }
 
 /**
- * Locate `.env.node` for CLI auto-load. Searches, in order:
+ * Locate `.env.node` for CLI auto-load.
+ *
+ * `JANT_ENV_FILE` overrides the search whenever it is set: a path names the
+ * file to load, and an empty value means "load nothing". The empty form is
+ * what keeps a developer's `packages/core/.env.node` out of the test suite —
+ * see the `env` block in `vitest.config.ts`.
+ *
+ * Without the override, the search order is:
  *   1. `<cwd>/.env.node`             — user's site directory
  *   2. `<bin>/../../.env.node`        — `packages/core/.env.node` (in-repo dev)
  *
- * Returns the first existing path, or `null` if none is found.
+ * @param {string} [cwd] - Directory searched first, and the base a relative
+ *   `JANT_ENV_FILE` resolves against. Defaults to `process.cwd()`.
+ * @param {Record<string, string | undefined>} [env] - Environment to read
+ *   `JANT_ENV_FILE` from. Defaults to `process.env`.
+ * @returns {string | null} The env file to load, or `null` when there is none.
+ * @throws {Error} When `JANT_ENV_FILE` names a file that does not exist.
+ * @example
+ * findNodeEnvPath(process.cwd(), { JANT_ENV_FILE: "" }); // null
+ * findNodeEnvPath(process.cwd(), { JANT_ENV_FILE: "./staging.env" });
  */
-export function findNodeEnvPath(cwd = process.cwd()) {
+export function findNodeEnvPath(cwd = process.cwd(), env = process.env) {
+  const override = env.JANT_ENV_FILE;
+  if (override !== undefined) {
+    const trimmed = override.trim();
+    if (trimmed === "") {
+      return null;
+    }
+
+    const overridePath = resolve(cwd, trimmed);
+    if (!fileExists(overridePath)) {
+      throw new Error(
+        `JANT_ENV_FILE points at "${override}", which does not exist. ` +
+          "Set it to a readable env file, or to an empty value to skip the env file.",
+      );
+    }
+
+    return overridePath;
+  }
+
   const candidates = [
     resolve(cwd, ".env.node"),
     resolve(dirname(fileURLToPath(import.meta.url)), "../../.env.node"),
@@ -90,9 +123,12 @@ export function loadNodeEnvFile(envPath, env = process.env) {
  * Always called before `resolveCliRuntime()`, so DATABASE_URL / DATA_DIR
  * defined in `.env.node` make `--node` (or auto-detect) work without
  * requiring the user to source the file manually.
+ *
+ * Honours `JANT_ENV_FILE` through {@link findNodeEnvPath}, so a caller that
+ * needs a fully controlled environment can opt out of the file entirely.
  */
 export function autoloadNodeEnv(env = process.env) {
-  const envPath = findNodeEnvPath();
+  const envPath = findNodeEnvPath(process.cwd(), env);
   if (!envPath) {
     return { envPath: null, found: false, assignedKeys: [], skippedKeys: [] };
   }

package/bin/lib/site-selection.js

@@ -39,16 +39,45 @@ function normalizePathPrefix(value) {
   return normalized || null;
 }
 
-function resolveSelector(options = {}) {
-  if (typeof options.site === "string" && options.site.trim()) {
-    return {
-      kind: "site",
-      siteId: options.site.trim(),
-    };
+/**
+ * Printed when a host-based command names no site. Kept word for word with
+ * `resolveCliSite` in `src/runtime/site.ts`, which the Node path uses.
+ */
+const HOST_BASED_SITE_REQUIRED_MESSAGE =
+  "host-based mode needs a target site. Pass --site <key|id>, --host <host>, or --url <url>.";
+
+function getTrimmedOption(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+/**
+ * Turn the site flags a command parsed into the selector both resolvers take:
+ * this file's raw-SQL `resolveCliSite` and `createNodeCliRuntime`.
+ *
+ * @param {{ site?: string, host?: string, pathPrefix?: string, url?: string }} [options]
+ *   The `--site`, `--host`, `--path-prefix` and `--url` values
+ * @returns {{ kind: "site", idOrKey: string } | { kind: "host", host: string, pathPrefix: string | null } | null}
+ *   The selector, or null when no site flag was passed
+ * @throws {Error} When more than one of `--site`, `--host` and `--url` is set
+ * @example
+ * parseCliSiteSelector({ url: "https://example.com/blog/" });
+ * // { kind: "host", host: "example.com", pathPrefix: "/blog" }
+ */
+export function parseCliSiteSelector(options = {}) {
+  const site = getTrimmedOption(options.site);
+  const host = getTrimmedOption(options.host);
+  const url = getTrimmedOption(options.url);
+
+  if ([site, host, url].filter(Boolean).length > 1) {
+    throw new Error("Choose only one of --site, --host, or --url.");
+  }
+
+  if (site) {
+    return { kind: "site", idOrKey: site };
   }
 
-  if (typeof options.url === "string" && options.url.trim()) {
-    const parsed = new URL(options.url.trim());
+  if (url) {
+    const parsed = new URL(url);
     return {
       kind: "host",
       host: parsed.host,
@@ -56,10 +85,10 @@ function resolveSelector(options = {}) {
     };
   }
 
-  if (typeof options.host === "string" && options.host.trim()) {
+  if (host) {
     return {
       kind: "host",
-      host: options.host.trim(),
+      host,
       pathPrefix: normalizePathPrefix(options.pathPrefix),
     };
   }
@@ -67,21 +96,26 @@ function resolveSelector(options = {}) {
   return null;
 }
 
-async function resolveSiteById(queryRunner, siteId) {
+// Mirrors `SiteService.getByIdOrKey`: an id match wins over a key match.
+async function resolveSiteByIdOrKey(queryRunner, idOrKey) {
+  const escaped = escapeSqlString(idOrKey);
   const rows = await queryRunner.query(`
     SELECT "id", "key", "status", "created_at", "updated_at"
     FROM "site"
-    WHERE "id" = '${escapeSqlString(siteId)}'
-    LIMIT 1
+    WHERE "id" = '${escaped}' OR "key" = '${escaped}'
+    LIMIT 2
   `);
 
-  if (rows.length === 0) {
-    throw new Error(`No site found for --site ${siteId}.`);
+  const row =
+    rows.find((candidate) => getOptionalString(candidate, "id") === idOrKey) ??
+    rows[0];
+  if (!row) {
+    throw new Error(`No site found for --site ${idOrKey}.`);
   }
 
   return {
     created: false,
-    site: toSite(rows[0]),
+    site: toSite(row),
   };
 }
 
@@ -148,18 +182,48 @@ export function getCliSiteResolutionMode(env = process.env) {
     : "single-site";
 }
 
+/**
+ * Resolve the site a command acts on with raw SQL, for runtimes that cannot
+ * run the site service (D1 through Wrangler, snapshot tooling).
+ *
+ * A site flag wins in either mode. Without one, single-site mode uses the
+ * instance's one site, and host-based mode fails before querying: a hosted
+ * database holds every tenant, so there is no default to fall back to.
+ *
+ * @param {{ query(sql: string): Promise<Record<string, unknown>[]>, execute?(sql: string): Promise<void> }} queryRunner
+ *   Runs SQL against the target database
+ * @param {{ env?: Record<string, string | undefined>, site?: string, host?: string, pathPrefix?: string, url?: string, createIfMissing?: boolean, bootstrapSite?: { id?: string, key?: string } }} [options]
+ *   The environment, the command's site flags, and whether single-site mode
+ *   may create the site shell when none exists
+ * @returns {Promise<{ created: boolean, site: { id: string, key: string, status: string, createdAt: number, updatedAt: number } }>}
+ *   The site, and whether this call created it
+ * @throws {Error} When the flags match no site, when host-based mode has none,
+ *   or when single-site mode finds zero sites it may not create or several
+ * @example
+ * const { site } = await resolveCliSite(context, {
+ *   env: process.env,
+ *   site: values.site,
+ *   host: values.host,
+ *   pathPrefix: values["path-prefix"],
+ *   url: values.url,
+ * });
+ */
 export async function resolveCliSite(queryRunner, options = {}) {
   const resolutionMode = getCliSiteResolutionMode(options.env);
-  const selector = resolveSelector(options);
+  const selector = parseCliSiteSelector(options);
 
   if (selector?.kind === "site") {
-    return resolveSiteById(queryRunner, selector.siteId);
+    return resolveSiteByIdOrKey(queryRunner, selector.idOrKey);
   }
 
   if (selector?.kind === "host") {
     return resolveSiteByHost(queryRunner, selector.host, selector.pathPrefix);
   }
 
+  if (resolutionMode === "host-based") {
+    throw new Error(HOST_BASED_SITE_REQUIRED_MESSAGE);
+  }
+
   const rows = await queryRunner.query(`
     SELECT "id", "key", "status", "created_at", "updated_at"
     FROM "site"
@@ -168,12 +232,6 @@ export async function resolveCliSite(queryRunner, options = {}) {
   `);
 
   if (rows.length === 0) {
-    if (resolutionMode !== "single-site") {
-      throw new Error(
-        "No site configured for this instance. Create a site before using host-based mode.",
-      );
-    }
-
     if (!options.createIfMissing || typeof queryRunner.execute !== "function") {
       throw new Error(
         "single-site mode requires an initialized site. Complete /setup first or run a command that can bootstrap the site shell.",
@@ -208,11 +266,9 @@ export async function resolveCliSite(queryRunner, options = {}) {
   }
 
   if (rows.length > 1) {
-    const message =
-      resolutionMode === "single-site"
-        ? `single-site mode found multiple sites in the database: ${formatSiteSummary(rows)}. Restore SITE_RESOLUTION_MODE=host-based for this database, or remove the extra sites before restarting in single-site mode.`
-        : "host-based mode requires --site, --host, or --url when the database contains multiple sites.";
-    throw new Error(message);
+    throw new Error(
+      `single-site mode found multiple sites in the database: ${formatSiteSummary(rows)}. Restore SITE_RESOLUTION_MODE=host-based for this database, or remove the extra sites before restarting in single-site mode.`,
+    );
   }
 
   return {

package/bin/lib/wrangler-cli.js

@@ -1,14 +1,28 @@
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/**
+ * Resolve the CLI entry point of the locally installed Wrangler.
+ *
+ * Wrangler ships an `exports` map (since 4.x) that does not expose
+ * `./bin/wrangler.js`, so the executable is derived from the package manifest
+ * — `./package.json` stays exported — instead of being resolved directly.
+ *
+ * @param {string} [cwd] Directory to resolve `wrangler` from first.
+ * @returns {string} Absolute path to Wrangler's CLI entry point.
+ * @example
+ * resolveWranglerBin("/repo/packages/core");
+ * // => "/repo/node_modules/.pnpm/wrangler@4.122.0/node_modules/wrangler/bin/wrangler.js"
+ */
 function resolveWranglerBin(cwd = process.cwd()) {
   const require = createRequire(import.meta.url);
   const fallbackPath = dirname(fileURLToPath(import.meta.url));
+  let manifestPath;
 
   try {
-    return require.resolve("wrangler/bin/wrangler.js", {
+    manifestPath = require.resolve("wrangler/package.json", {
       paths: [cwd, fallbackPath],
     });
   } catch (error) {
@@ -20,6 +34,18 @@ function resolveWranglerBin(cwd = process.cwd()) {
       { cause: error },
     );
   }
+
+  const manifest = require(manifestPath);
+  const binEntry =
+    typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.wrangler;
+
+  if (!binEntry) {
+    throw new Error(
+      `Wrangler ${manifest.version ?? "(unknown version)"} at ${dirname(manifestPath)} declares no \`wrangler\` executable. Reinstall dependencies to get a supported Wrangler build.`,
+    );
+  }
+
+  return resolve(dirname(manifestPath), binEntry);
 }
 
 export function runLocalWrangler(args, options = {}) {

package/bin/lib/wrangler-json.js

@@ -0,0 +1,35 @@
+/**
+ * Parsing helpers for Wrangler's stdout.
+ *
+ * Deliberately separate from `wrangler-cli.js`: that module spawns processes
+ * and is stubbed wholesale in tests, while this one is pure and must always be
+ * the real implementation.
+ */
+
+/**
+ * Strip the non-JSON preamble Wrangler sometimes writes to stdout before the
+ * actual payload.
+ *
+ * Wrangler announces things like "Proxy environment variables detected. We'll
+ * use your proxy for fetch requests." on stdout rather than stderr, which makes
+ * a bare `JSON.parse` of `--json` output throw for anyone with `HTTPS_PROXY` or
+ * `ALL_PROXY` set. Every caller that parses Wrangler JSON must go through here.
+ *
+ * @param {string} raw Raw stdout captured from a Wrangler invocation.
+ * @returns {string} The payload starting at the first JSON object or array.
+ * @example
+ * extractWranglerJson('Proxy environment variables detected.\n[{"results":[]}]');
+ * // => '[{"results":[]}]'
+ */
+export function extractWranglerJson(raw) {
+  const arrayStart = raw.indexOf("[");
+  const objectStart = raw.indexOf("{");
+  if (arrayStart === -1 && objectStart === -1) return raw;
+  const start =
+    arrayStart === -1
+      ? objectStart
+      : objectStart === -1
+        ? arrayStart
+        : Math.min(arrayStart, objectStart);
+  return raw.slice(start);
+}