@jant/core 0.6.16 → 0.7.1

package/src/runtime/__tests__/node.test.ts

@@ -5,10 +5,15 @@ import {
 } from "../../__tests__/helpers/db.js";
 import { sqliteSchemaBundle } from "../../db/schema-bundle.js";
 import { createRequestRuntime } from "../index.js";
-import { createNodeRequestRuntime } from "../node.js";
+import { createNodeCliRuntime, createNodeRequestRuntime } from "../node.js";
+import type { CliSiteSelector } from "../site.js";
 import type { Bindings } from "../../types.js";
 import { siteDomains, sites } from "../../db/schema.js";
-import { ConflictError, NotFoundError } from "../../lib/errors.js";
+import {
+  ConflictError,
+  NotFoundError,
+  SiteUnavailableError,
+} from "../../lib/errors.js";
 import { TRANSIENT_SINGLE_SITE_ID } from "../../services/site.js";
 
 afterEach(() => {
@@ -217,7 +222,7 @@ describe("createNodeRequestRuntime", () => {
     );
   });
 
-  it("treats suspended host-based sites as not found", async () => {
+  it("treats suspended host-based sites as unavailable, not missing", async () => {
     const { db, sqlite } = createTestDatabase();
     const consoleError = vi
       .spyOn(console, "error")
@@ -250,9 +255,129 @@ describe("createNodeRequestRuntime", () => {
         } as Bindings,
         "http://suspended.localtest.me/",
       ),
-    ).rejects.toBeInstanceOf(NotFoundError);
+    ).rejects.toBeInstanceOf(SiteUnavailableError);
     expect(consoleError).toHaveBeenCalledWith(
       "[Jant] Hosted site resolution failed: host=suspended.localtest.me path=/ reason=site-not-active siteId=sit_test00000000000000000000000 siteKey=default siteStatus=suspended",
     );
   });
 });
+
+describe("createNodeCliRuntime", () => {
+  const OTHER_SITE_ID = "sit_other0000000000000000000000";
+
+  function nodeDatabaseBindings(
+    testDb: ReturnType<typeof createTestDatabase>,
+    env: Partial<Bindings> = {},
+  ): Bindings {
+    return {
+      NODE_DATABASE: {
+        db: testDb.db,
+        dialect: "sqlite",
+        rawQuery: createSqliteRawQuery(testDb.sqlite),
+        schema: sqliteSchemaBundle,
+      },
+      ...env,
+    } as Bindings;
+  }
+
+  /** The default test site plus a second tenant on its own host. */
+  function createDatabaseWithTwoSites() {
+    const testDb = createTestDatabase();
+    testDb.sqlite
+      .prepare(
+        `
+          INSERT INTO site (id, key, status, created_at, updated_at)
+          VALUES (?, 'other', 'active', 1774200001, 1774200001)
+        `,
+      )
+      .run(OTHER_SITE_ID);
+    testDb.sqlite
+      .prepare(
+        `
+          INSERT INTO site_domain (id, site_id, host, path_prefix, kind, redirect_to_primary, created_at, updated_at)
+          VALUES ('std_other_1', ?, 'other.localtest.me', NULL, 'primary', 1, 1774200001, 1774200001)
+        `,
+      )
+      .run(OTHER_SITE_ID);
+    return testDb;
+  }
+
+  // A hosted database holds every tenant, so there is no "only site" to fall
+  // back to. The single-site lookup would blame SITE_RESOLUTION_MODE, which is
+  // already host-based; the CLI has to say which flag picks the site.
+  it("requires a site selector in host-based mode with several sites", async () => {
+    const testDb = createDatabaseWithTwoSites();
+
+    await expect(
+      createNodeCliRuntime(
+        nodeDatabaseBindings(testDb, { SITE_RESOLUTION_MODE: "host-based" }),
+      ),
+    ).rejects.toThrow(
+      "host-based mode needs a target site. Pass --site <key|id>, --host <host>, or --url <url>.",
+    );
+  });
+
+  it.each<[string, CliSiteSelector]>([
+    ["key", { kind: "site", idOrKey: "other" }],
+    ["id", { kind: "site", idOrKey: OTHER_SITE_ID }],
+    ["host", { kind: "host", host: "other.localtest.me", pathPrefix: null }],
+  ])(
+    "scopes a host-based runtime to the site selected by %s",
+    async (_label, selector) => {
+      const testDb = createDatabaseWithTwoSites();
+
+      const runtime = await createNodeCliRuntime(
+        nodeDatabaseBindings(testDb, { SITE_RESOLUTION_MODE: "host-based" }),
+        selector,
+      );
+      await runtime.services.settings.set("PASSWORD_RESET_TOKEN", "hash:1");
+
+      expect(runtime.currentSite.id).toBe(OTHER_SITE_ID);
+      expect(runtime.currentSiteDomain?.host).toBe("other.localtest.me");
+      expect(
+        testDb.sqlite
+          .prepare(
+            `SELECT site_id FROM site_setting WHERE key = 'PASSWORD_RESET_TOKEN'`,
+          )
+          .pluck()
+          .all(),
+      ).toEqual([OTHER_SITE_ID]);
+    },
+  );
+
+  it("names the selector that matched no site", async () => {
+    const testDb = createDatabaseWithTwoSites();
+    const env = nodeDatabaseBindings(testDb, {
+      SITE_RESOLUTION_MODE: "host-based",
+    });
+
+    await expect(
+      createNodeCliRuntime(env, { kind: "site", idOrKey: "missing" }),
+    ).rejects.toThrow("No site found for --site missing.");
+    await expect(
+      createNodeCliRuntime(env, {
+        kind: "host",
+        host: "other.localtest.me",
+        pathPrefix: "/blog",
+      }),
+    ).rejects.toThrow(
+      'No site found for host "other.localtest.me" and path prefix "/blog".',
+    );
+  });
+
+  it("uses the instance's one site in single-site mode", async () => {
+    const runtime = await createNodeCliRuntime(
+      nodeDatabaseBindings(createTestDatabase()),
+    );
+
+    expect(runtime.currentSite.id).toBe(DEFAULT_TEST_SITE_ID);
+  });
+
+  // Here the single-site error is the accurate one: the database really does
+  // belong to a host-based install.
+  it("reports a multi-site database in single-site mode as misconfigured", async () => {
+    await expect(
+      createNodeCliRuntime(nodeDatabaseBindings(createDatabaseWithTwoSites())),
+    ).rejects.toThrow("single-site mode found multiple sites in the database:");
+  });
+});

package/src/runtime/__tests__/readiness.test.ts

@@ -24,6 +24,7 @@ describe("getInstanceReadiness", () => {
       }),
     ).resolves.toEqual({
       status: "ok",
+      version: "test-version",
       checks: {
         startupConfig: { ok: true },
         database: { ok: true },
@@ -40,6 +41,7 @@ describe("getInstanceReadiness", () => {
       }),
     ).resolves.toEqual({
       status: "error",
+      version: "test-version",
       checks: {
         startupConfig: {
           ok: false,
@@ -104,6 +106,26 @@ describe("getInstanceReadiness", () => {
     );
   });
 
+  // What a deploy check compares: the build that answers, and when its
+  // process started. A Worker has no process, so it reports only the build.
+  it("reports the build, and the process start where there is one", async () => {
+    const { sqlite } = createTestDatabase();
+    const env = {
+      AUTH_SECRET: "test-secret-with-enough-entropy-for-readiness",
+      NODE_SQLITE: sqlite,
+    };
+
+    const withoutStart = await getInstanceReadiness(env);
+    expect(withoutStart.version).toBe("test-version");
+    expect(withoutStart).not.toHaveProperty("startedAt");
+
+    const withStart = await getInstanceReadiness({
+      ...env,
+      NODE_STARTED_AT: 1789000000,
+    });
+    expect(withStart.startedAt).toBe(1789000000);
+  });
+
   it("reports a missing database binding", async () => {
     await expect(
       getInstanceReadiness({
@@ -111,6 +133,7 @@ describe("getInstanceReadiness", () => {
       }),
     ).resolves.toEqual({
       status: "error",
+      version: "test-version",
       checks: {
         startupConfig: { ok: true },
         database: {

package/src/runtime/cloudflare.ts

@@ -52,6 +52,13 @@ export interface CloudflareRequestRuntime {
 export async function createCloudflareRequestRuntime(
   env: Bindings,
   publicRequestUrl: string,
+  options?: {
+    /**
+     * Anchor this request's first read to the primary instead of any replica.
+     * Set for requests that carry a session cookie — see `createRequestRuntime`.
+     */
+    anchorReadsToPrimary?: boolean;
+  },
 ): Promise<CloudflareRequestRuntime> {
   if (!env.DB) {
     throw new Error("Cloudflare runtime requires a DB binding.");
@@ -62,8 +69,19 @@ export async function createCloudflareRequestRuntime(
     throw new Error("AUTH_SECRET should be set after startup validation.");
   }
 
-  // Use withSession() to enable D1 Read Replication.
-  const session = env.DB.withSession();
+  // Use withSession() to enable D1 Read Replication. The constraint applies to
+  // the session's *first* query; every later query is anchored to the bookmark
+  // that one returns, so the whole request is sequentially consistent.
+  //
+  // Bookmarks are not carried across requests, so an unconstrained first read
+  // may land on a replica that has not caught up yet. For anonymous traffic
+  // that is fine and it is the point of replication. For a request holding a
+  // session cookie it is not: the session row is written on the primary, and a
+  // lagging replica answers "no such session" — the visitor is bounced to
+  // sign-in even though they never signed out.
+  const session = env.DB.withSession(
+    options?.anchorReadsToPrimary ? "first-primary" : "first-unconstrained",
+  );
 
   // Note: Drizzle ORM doesn't officially support D1DatabaseSession yet
   // (issue #2226), but it works at runtime.
@@ -89,6 +107,7 @@ export async function createCloudflareRequestRuntime(
 
   const servicesConfig = {
     databaseDialect: "sqlite" as const,
+    authSecret,
     bootstrapSite: getSingleSiteBootstrapOptions(env),
     enforceHostedMediaQuota: getSiteResolutionMode(env) === "host-based",
     hostedControlPlane: createHostedControlPlaneClient(env),

package/src/runtime/index.ts

@@ -2,13 +2,39 @@ import { createCloudflareRequestRuntime } from "./cloudflare.js";
 import { createNodeRequestRuntime } from "./node.js";
 import type { Bindings } from "../types/bindings.js";
 
+/**
+ * Whether a `Cookie` header carries a better-auth session token.
+ *
+ * Matched on the `.session_token` suffix so it holds for both the plain and
+ * the `__Secure-`-prefixed cookie name. This is a cheap "probably signed in"
+ * hint used to pick a database consistency mode — it does not verify the
+ * cookie's signature, and it must not be used to make an auth decision.
+ *
+ * @param cookieHeader - Raw `Cookie` request header, if any
+ * @returns `true` when a session token cookie appears to be present
+ *
+ * @example
+ * ```ts
+ * hasSessionCookie("__Secure-better-auth.session_token=abc"); // true
+ * hasSessionCookie("theme=dark");                             // false
+ * ```
+ */
+export function hasSessionCookie(
+  cookieHeader: string | null | undefined,
+): boolean {
+  return !!cookieHeader?.includes(".session_token=");
+}
+
 export async function createRequestRuntime(
   env: Bindings,
   publicRequestUrl: string,
+  request?: Request,
 ) {
   if (env.NODE_DATABASE || env.NODE_SQLITE) {
     return createNodeRequestRuntime(env, publicRequestUrl);
   }
 
-  return createCloudflareRequestRuntime(env, publicRequestUrl);
+  return createCloudflareRequestRuntime(env, publicRequestUrl, {
+    anchorReadsToPrimary: hasSessionCookie(request?.headers.get("cookie")),
+  });
 }

package/src/runtime/node.ts

@@ -12,14 +12,21 @@ import {
   shouldUseSecureCookies,
 } from "../lib/env.js";
 import { createHostedControlPlaneClient } from "../lib/hosted-control-plane.js";
+import { ValidationError } from "../lib/errors.js";
 import { createMemoryRateLimiter } from "../lib/rate-limit-memory.js";
 import type { RateLimiter } from "../lib/rate-limit.js";
+import { InstanceSetupSchema } from "../lib/schemas.js";
 import { createStorageDriver, type StorageDriver } from "../lib/storage.js";
 import {
   createHostedHandoffService,
   type HostedHandoffService,
 } from "../services/hosted-handoff.js";
+import {
+  createBootstrapService,
+  type SetUpInstanceResult,
+} from "../services/bootstrap.js";
 import { createServices, type Services } from "../services/index.js";
+import { TRANSIENT_SINGLE_SITE_ID } from "../services/site.js";
 import type { Site, SiteDomain } from "../types/entities.js";
 import type { Bindings } from "../types/bindings.js";
 import {
@@ -27,6 +34,7 @@ import {
   getResolvedSiteBaseUrl,
   resolveCliSite,
   resolveRequestSite,
+  type CliSiteSelector,
 } from "./site.js";
 
 export interface NodeRequestRuntime {
@@ -144,6 +152,7 @@ export async function createNodeRequestRuntime(
 
   const servicesConfig = {
     databaseDialect,
+    authSecret,
     bootstrapSite: getSingleSiteBootstrapOptions(env),
     enforceHostedMediaQuota: getSiteResolutionMode(env) === "host-based",
     hostedControlPlane: createHostedControlPlaneClient(env),
@@ -175,9 +184,24 @@ export async function createNodeRequestRuntime(
  * Builds the runtime objects needed by local CLI commands.
  *
  * Unlike the request runtime, this path does not require auth configuration.
+ *
+ * @param env - Bindings with a resolved `NODE_DATABASE` or `NODE_SQLITE`
+ * @param selector - The site the command acts on. Required in host-based
+ *   mode; single-site mode falls back to the instance's one site.
+ * @returns Services, storage and database scoped to that site
+ * @throws {Error} When host-based mode has no selector, or the selector
+ *   matches no site
+ * @example
+ * ```ts
+ * const runtime = await createNodeCliRuntime(bindings, {
+ *   kind: "site",
+ *   idOrKey: "demo",
+ * });
+ * ```
  */
 export async function createNodeCliRuntime(
   env: Bindings,
+  selector: CliSiteSelector | null = null,
 ): Promise<NodeCliRuntime> {
   const nodeDatabase = env.NODE_DATABASE;
   const sqlite = env.NODE_SQLITE;
@@ -194,7 +218,7 @@ export async function createNodeCliRuntime(
 
   const slugIdLength =
     parseInt(getEnvString(env, "SLUG_ID_LENGTH") ?? "5", 10) || 5;
-  const siteLookup = await resolveCliSite(db, env, databaseSchema);
+  const siteLookup = await resolveCliSite(db, env, selector, databaseSchema);
 
   return {
     currentSite: siteLookup.site,
@@ -212,3 +236,45 @@ export async function createNodeCliRuntime(
     storage: createStorageDriver(env),
   };
 }
+
+/**
+ * Set up a self-hosted Node install without a browser, the way the two setup
+ * screens would. Backs `jant setup`.
+ *
+ * @param env - Bindings with a resolved `NODE_DATABASE`
+ * @param input - The owner's credentials and the site's answers, unvalidated
+ * @returns What setup found, and the site
+ * @throws {ValidationError} When the input fails `InstanceSetupSchema`
+ * @throws {Error} Whenever `BootstrapService.setUpInstance` refuses
+ * @example
+ * ```ts
+ * await setUpNodeInstance(bindings, {
+ *   email: "owner@example.com",
+ *   password: "correct horse battery",
+ * });
+ * ```
+ */
+export async function setUpNodeInstance(
+  env: Bindings,
+  input: unknown,
+): Promise<SetUpInstanceResult> {
+  const nodeDatabase = env.NODE_DATABASE;
+  if (!nodeDatabase) {
+    throw new Error("Node setup requires a resolved database binding.");
+  }
+
+  const parsed = InstanceSetupSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new ValidationError(
+      parsed.error.issues[0]?.message ?? "Invalid setup input.",
+    );
+  }
+
+  // No request resolved a site, and setup never reads the one it is bound to.
+  return createBootstrapService(nodeDatabase.db, TRANSIENT_SINGLE_SITE_ID, {
+    schema: nodeDatabase.schema,
+    databaseDialect: nodeDatabase.dialect,
+    bootstrapSite: getSingleSiteBootstrapOptions(env),
+    siteResolutionMode: getSiteResolutionMode(env),
+  }).setUpInstance(parsed.data);
+}

package/src/runtime/readiness.ts

@@ -5,6 +5,7 @@ import {
   getAuthSecretReadinessError,
   getHostBasedStartupConfigurationIssues,
 } from "../lib/startup-config.js";
+import { CORE_VERSION } from "../lib/version.js";
 import { createSiteService } from "../services/site.js";
 import type { Bindings } from "../types/bindings.js";
 
@@ -15,6 +16,15 @@ export interface ReadinessCheckStatus {
 
 export interface InstanceReadinessResult {
   status: "ok" | "error";
+  /** The running build: the package version, then the build's commit id. */
+  version: string;
+  /**
+   * When the Node process started serving, in Unix seconds. With `version`,
+   * it lets a deploy check from outside that the instance answering is one
+   * started after the deploy, not an older one a rollback left running.
+   * Absent on Workers.
+   */
+  startedAt?: number;
   checks: {
     startupConfig: ReadinessCheckStatus;
     database: ReadinessCheckStatus;
@@ -117,6 +127,7 @@ export async function getInstanceReadiness(
     | "INTERNAL_ADMIN_TOKEN"
     | "NODE_DATABASE"
     | "NODE_SQLITE"
+    | "NODE_STARTED_AT"
     | "SITE_RESOLUTION_MODE"
   >,
 ): Promise<InstanceReadinessResult> {
@@ -125,6 +136,10 @@ export async function getInstanceReadiness(
 
   return {
     status: startupConfig.ok && database.ok ? "ok" : "error",
+    version: CORE_VERSION,
+    ...(env.NODE_STARTED_AT === undefined
+      ? {}
+      : { startedAt: env.NODE_STARTED_AT }),
     checks: {
       startupConfig,
       database,

package/src/runtime/site.ts

@@ -17,7 +17,7 @@ import {
   type SiteLookupResult,
   TRANSIENT_SINGLE_SITE_ID,
 } from "../services/site.js";
-import { NotFoundError } from "../lib/errors.js";
+import { NotFoundError, SiteUnavailableError } from "../lib/errors.js";
 import type { Bindings } from "../types/bindings.js";
 
 function logHostedSiteResolutionFailure(input: {
@@ -115,45 +115,116 @@ export async function resolveRequestSite(
       siteKey: resolved.site.key,
       siteStatus: resolved.site.status,
     });
-    throw new NotFoundError("Site");
+    // The host resolved, so the site is real — it is just suspended (hosted
+    // plan ended, or an operator took it down). Serving a 404 here told the
+    // visitor the address was wrong and told crawlers to drop the site, both
+    // of which are false while it can still be restored.
+    throw new SiteUnavailableError();
   }
   return resolved;
 }
 
-export async function resolveCliSite(
+/**
+ * The site a CLI command was told to act on. The `jant` CLI builds it from
+ * `--site <key|id>`, `--host <host>` with `--path-prefix`, or `--url <url>`
+ * (see `parseCliSiteSelector` in `bin/lib/site-selection.js`).
+ */
+export type CliSiteSelector =
+  | { kind: "site"; idOrKey: string }
+  | {
+      kind: "host";
+      host: string;
+      /** The domain's stored prefix (`/blog`), or null for a root domain. */
+      pathPrefix: string | null;
+    };
+
+/**
+ * Printed when a host-based CLI command names no site. Kept word for word with
+ * the raw-SQL resolver the D1 path uses in `bin/lib/site-selection.js`.
+ */
+const HOST_BASED_CLI_SITE_REQUIRED_MESSAGE =
+  "host-based mode needs a target site. Pass --site <key|id>, --host <host>, or --url <url>.";
+
+async function resolveSelectedCliSite(
   db: Database,
-  env: Bindings,
-  databaseSchema: DatabaseSchema = sqliteSchemaBundle,
+  selector: CliSiteSelector,
+  databaseSchema: DatabaseSchema,
 ): Promise<SiteLookupResult> {
   const siteService = createSiteService(db, databaseSchema);
-  const resolutionMode = getSiteResolutionMode(env);
 
-  if (resolutionMode === "single-site") {
-    const resolved = await siteService.resolveSingleSite({
-      ...getSingleSiteBootstrapOptions(env),
-      createIfMissing: false,
-    });
-
-    if (resolved.site.id === TRANSIENT_SINGLE_SITE_ID) {
-      throw new Error(
-        "No site is configured for this instance yet. Finish /setup before running this command.",
-      );
+  if (selector.kind === "site") {
+    const site = await siteService.getByIdOrKey(selector.idOrKey);
+    if (!site) {
+      throw new Error(`No site found for --site ${selector.idOrKey}.`);
     }
+    return {
+      site,
+      domain: await siteService.getPrimaryDomainForSite(site.id),
+    };
+  }
 
-    return resolved;
+  const resolved = await siteService.resolveByHost(
+    selector.host,
+    selector.pathPrefix,
+  );
+  if (!resolved) {
+    throw new Error(
+      `No site found for host "${selector.host}"${selector.pathPrefix ? ` and path prefix "${selector.pathPrefix}"` : ""}.`,
+    );
   }
+  return resolved;
+}
+
+/**
+ * Resolve the site a CLI command acts on.
+ *
+ * A selector wins in either mode. Without one, single-site mode uses the
+ * instance's one site, and host-based mode fails before touching the
+ * database: a hosted database holds every tenant, so there is no default to
+ * fall back to — not even when it happens to hold one site today.
+ *
+ * @param db - The database
+ * @param env - Bindings that carry `SITE_RESOLUTION_MODE` and the single-site
+ *   origin
+ * @param selector - The site the command was told to act on, if any
+ * @param databaseSchema - The schema bundle for the database's dialect
+ * @returns The site and its domain
+ * @throws {Error} When the selector matches no site, when host-based mode has
+ *   no selector, or when single-site mode has not finished setup
+ * @example
+ * ```ts
+ * await resolveCliSite(db, env, { kind: "site", idOrKey: "demo" });
+ * ```
+ */
+export async function resolveCliSite(
+  db: Database,
+  env: Bindings,
+  selector: CliSiteSelector | null = null,
+  databaseSchema: DatabaseSchema = sqliteSchemaBundle,
+): Promise<SiteLookupResult> {
+  if (selector) {
+    return resolveSelectedCliSite(db, selector, databaseSchema);
+  }
+
+  if (getSiteResolutionMode(env) === "host-based") {
+    throw new Error(HOST_BASED_CLI_SITE_REQUIRED_MESSAGE);
+  }
+
+  const resolved = await createSiteService(
+    db,
+    databaseSchema,
+  ).resolveSingleSite({
+    ...getSingleSiteBootstrapOptions(env),
+    createIfMissing: false,
+  });
 
-  const onlySite = await siteService.getOnlySite();
-  if (!onlySite) {
+  if (resolved.site.id === TRANSIENT_SINGLE_SITE_ID) {
     throw new Error(
-      "CLI site selection for host-based mode is not implemented yet.",
+      "No site is configured for this instance yet. Finish /setup before running this command.",
     );
   }
 
-  return {
-    site: onlySite,
-    domain: null,
-  };
+  return resolved;
 }
 
 export function getResolvedSiteBaseUrl(