create-sailor 1.9.6 → 1.10.0

package/bin/create-sailor.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Committed bin entry for `create-sailor`.
+//
+// pnpm links bins before any lifecycle script or build runs, so package.json#bin
+// must point at a file that exists in a fresh checkout — dist/ does not. This
+// file exists at link time and hands off to the tsup output once it is built.
+// Guarded by tests/architecture/workspace-bin-stubs.test.ts.
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const entry = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/index.js");
+
+if (!existsSync(entry)) {
+  process.stderr.write(
+    [
+      `create-sailor: built entry not found at ${entry}`,
+      "The package has not been built yet. Run `pnpm --filter create-sailor build` and retry.",
+      "",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+// Keep argv identical to a direct `node dist/index.js …` so commander and any
+// main-module check in the built entry see exactly what they saw before.
+process.argv[1] = entry;
+await import(pathToFileURL(entry).href);

package/dist/index.js

@@ -270,7 +270,7 @@ gdp("send");
 }
 `)}function Hs(){return`# GrowingIO \u2014 \u5168\u57CB\u70B9 CDP (\u4E2D\u56FD\u533A)
 NEXT_PUBLIC_GROWINGIO_ACCOUNT_ID=
-`}async function io(e,t,n="global"){let o=so(t);if(!o||o.id==="none")return;let r=B.join(e,"apps","web");if(!nt.existsSync(r))return;let s=o.id;try{switch(s){case"posthog":Ls(r),ke(e,Us());return;case"plausible":Ds(r),ke(e,Ms());return;case"umami":Fs(r),ke(e,js());return;case"mixpanel":Bs(r),ke(e,$s());return;case"baidu":Vs(r),ke(e,Ks());return;case"sensors":Ys(r),ke(e,qs());return;case"growingio":Gs(r),ke(e,Hs());return;default:return}}catch(i){throw console.error(`Failed to apply analytics selection "${t}":`,i),new Error(`Analytics scaffold for "${t}" failed \u2014 see stderr for details.`)}}var Ws={name:"Nebutra",nameCn:"\u4E91\u6BD3\u667A\u80FD",nameFull:"\u65E0\u9521\u4E91\u6BD3\u667A\u80FD\u79D1\u6280\u6709\u9650\u516C\u53F8",nameFullEn:"Wuxi Nebutra Intelligence Technology Co., Ltd.",tagline:"Ship AI products, not boilerplate.",taglineCn:"AI\u539F\u751F\xB7\u5FEB\u901F\u51FA\u6D77\xB7\u5373\u523B\u4EA4\u4ED8",description:"Production-ready Next.js monorepo template for AI SaaS products. Auth, billing, multi-tenancy, AI services, design system, and enterprise infrastructure \u2014 pre-configured.",descriptionCn:"\u9762\u5411AI\u521B\u4E1A\u8005\u7684\u4E00\u4F53\u5316SaaS\u57FA\u7840\u8BBE\u65BD\u6A21\u677F\uFF0C\u8986\u76D6\u8BA4\u8BC1\u3001\u8BA1\u8D39\u3001\u591A\u79DF\u6237\u3001AI\u670D\u52A1\u4E0E\u8BBE\u8BA1\u7CFB\u7EDF\uFF0C\u5F00\u7BB1\u5373\u4EA7\u54C1",story:{concept:"Logo\u4EE5\u9996\u5B57\u6BCDN\u7684\u57FA\u7840\u9020\u578B\u6982\u5FF5\u4E3A\u4E3B\u8981\u8BBE\u8BA1\u6846\u67B6\uFF0C\u901A\u8FC7\u51E0\u4F55\u6B63\u8D1F\u7A7A\u95F4\u6784\u5EFA\u9690\u5F62'N'\uFF0C\u5F62\u6210\u8FD1\u4F3C\u516D\u8FB9\u5F62\u7684\u7A33\u5B9A\u7ED3\u6784",colorMeaning:"\u84DD\u7EFF\u6E10\u53D8\u4F53\u73B0\u672A\u6765\u611F\u4E0E\u79D1\u6280\u950B\u8292\uFF0C'\u4E91'\u4EE3\u8868\u4E91\u7AEF\u5E73\u53F0\uFF0C'\u6BD3'\u5BD3\u610F\u5B55\u80B2\u4E0E\u8F6C\u5316",values:["AI Native","Ship Fast","Open by Default","Global-Ready","Enterprise-Grade"],missionStatement:"Help AI founders and SaaS teams go from idea to production 10x faster by providing the infrastructure layer they shouldn't have to build."},domains:{landing:"nebutra.com",app:"app.nebutra.com",api:"api.nebutra.com",auth:"auth.nebutra.com",sso:"sso.nebutra.com",docs:"docs.nebutra.com",studio:"studio.nebutra.com",cdn:"cdn.nebutra.com",router:"router.nebutra.com",forge:"forge.nebutra.com",design:"design.nebutra.com",status:"status.nebutra.com",admin:"admin.nebutra.com",analytics:"analytics.nebutra.com",pebble:"pebble.nebutra.com",carina:"carina.nebutra.com",origin:"origin.nebutra.com"},social:{twitter:"https://twitter.com/nebutra",github:"https://github.com/nebutra",discord:"https://discord.gg/nebutra",linkedin:"https://linkedin.com/company/nebutra"}};function ao(e){let t=Ws.domains[e];if(!t?.trim())throw new Error(`brand.domains.${String(e)} is empty \u2014 run brand:apply`);return`https://${t.replace(/^https?:\/\//,"").replace(/\/+$/,"")}`}var Xs=ao("analytics");function zs(e={}){if(e.noTelemetry===!0)return!0;let t=process.env.NEBUTRA_TELEMETRY;return t==="0"||t==="false"}function co(e,t={}){zs(t)||(async()=>{try{let n=await import("@nebutra/analytics");if(typeof n.createProductAnalyticsClient!="function")return;let o=n.createProductAnalyticsClient({posthog:{apiKey:process.env.POSTHOG_KEY??process.env.NEXT_PUBLIC_POSTHOG_KEY??process.env.NEBUTRA_POSTHOG_KEY??"",host:process.env.POSTHOG_HOST??process.env.NEXT_PUBLIC_POSTHOG_HOST??process.env.NEBUTRA_POSTHOG_HOST??Xs},onError:()=>{}});if(typeof o?.track!="function")return;let r=o.track("scaffold.completed",e);r&&typeof r.then=="function"&&await r.catch(()=>{})}catch{}})()}import G from"fs";import k from"path";function $(e){G.existsSync(e)&&G.rmSync(e,{recursive:!0,force:!0})}function xt(e,t){let n=k.join(e,".env.example");G.existsSync(n)?G.appendFileSync(n,`
+`}async function io(e,t,n="global"){let o=so(t);if(!o||o.id==="none")return;let r=B.join(e,"apps","web");if(!nt.existsSync(r))return;let s=o.id;try{switch(s){case"posthog":Ls(r),ke(e,Us());return;case"plausible":Ds(r),ke(e,Ms());return;case"umami":Fs(r),ke(e,js());return;case"mixpanel":Bs(r),ke(e,$s());return;case"baidu":Vs(r),ke(e,Ks());return;case"sensors":Ys(r),ke(e,qs());return;case"growingio":Gs(r),ke(e,Hs());return;default:return}}catch(i){throw console.error(`Failed to apply analytics selection "${t}":`,i),new Error(`Analytics scaffold for "${t}" failed \u2014 see stderr for details.`)}}var Ws={name:"Nebutra",nameCn:"\u4E91\u6BD3\u667A\u80FD",nameFull:"\u65E0\u9521\u4E91\u6BD3\u667A\u80FD\u79D1\u6280\u6709\u9650\u516C\u53F8",nameFullEn:"Wuxi Nebutra Intelligence Technology Co., Ltd.",tagline:"Ship AI products, not boilerplate.",taglineCn:"AI\u539F\u751F\xB7\u5FEB\u901F\u51FA\u6D77\xB7\u5373\u523B\u4EA4\u4ED8",description:"Production-ready Next.js monorepo template for AI SaaS products. Auth, billing, multi-tenancy, AI services, design system, and enterprise infrastructure \u2014 pre-configured.",descriptionCn:"\u9762\u5411AI\u521B\u4E1A\u8005\u7684\u4E00\u4F53\u5316SaaS\u57FA\u7840\u8BBE\u65BD\u6A21\u677F\uFF0C\u8986\u76D6\u8BA4\u8BC1\u3001\u8BA1\u8D39\u3001\u591A\u79DF\u6237\u3001AI\u670D\u52A1\u4E0E\u8BBE\u8BA1\u7CFB\u7EDF\uFF0C\u5F00\u7BB1\u5373\u4EA7\u54C1",story:{concept:"Logo\u4EE5\u9996\u5B57\u6BCDN\u7684\u57FA\u7840\u9020\u578B\u6982\u5FF5\u4E3A\u4E3B\u8981\u8BBE\u8BA1\u6846\u67B6\uFF0C\u901A\u8FC7\u51E0\u4F55\u6B63\u8D1F\u7A7A\u95F4\u6784\u5EFA\u9690\u5F62'N'\uFF0C\u5F62\u6210\u8FD1\u4F3C\u516D\u8FB9\u5F62\u7684\u7A33\u5B9A\u7ED3\u6784",colorMeaning:"\u84DD\u7EFF\u6E10\u53D8\u4F53\u73B0\u672A\u6765\u611F\u4E0E\u79D1\u6280\u950B\u8292\uFF0C'\u4E91'\u4EE3\u8868\u4E91\u7AEF\u5E73\u53F0\uFF0C'\u6BD3'\u5BD3\u610F\u5B55\u80B2\u4E0E\u8F6C\u5316",values:["AI Native","Ship Fast","Open by Default","Global-Ready","Enterprise-Grade"],missionStatement:"Help AI founders and SaaS teams go from idea to production 10x faster by providing the infrastructure layer they shouldn't have to build."},domains:{landing:"nebutra.com",app:"app.nebutra.com",api:"api.nebutra.com",auth:"auth.nebutra.com",sso:"sso.nebutra.com",docs:"docs.nebutra.com",studio:"studio.nebutra.com",cdn:"cdn.nebutra.com",router:"router.nebutra.com",forge:"forge.nebutra.com",design:"design.nebutra.com",status:"status.nebutra.com",open:"open.nebutra.com",admin:"admin.nebutra.com",analytics:"analytics.nebutra.com",pebble:"pebble.nebutra.com",carina:"carina.nebutra.com",kuanlan:"kuanlan.nebutra.com",origin:"origin.nebutra.com"},social:{twitter:"https://twitter.com/nebutra",github:"https://github.com/nebutra",discord:"https://discord.gg/nebutra",linkedin:"https://linkedin.com/company/nebutra"}};function ao(e){let t=Ws.domains[e];if(!t?.trim())throw new Error(`brand.domains.${String(e)} is empty \u2014 run brand:apply`);return`https://${t.replace(/^https?:\/\//,"").replace(/\/+$/,"")}`}var Xs=ao("analytics");function zs(e={}){if(e.noTelemetry===!0)return!0;let t=process.env.NEBUTRA_TELEMETRY;return t==="0"||t==="false"}function co(e,t={}){zs(t)||(async()=>{try{let n=await import("@nebutra/analytics");if(typeof n.createProductAnalyticsClient!="function")return;let o=n.createProductAnalyticsClient({posthog:{apiKey:process.env.POSTHOG_KEY??process.env.NEXT_PUBLIC_POSTHOG_KEY??process.env.NEBUTRA_POSTHOG_KEY??"",host:process.env.POSTHOG_HOST??process.env.NEXT_PUBLIC_POSTHOG_HOST??process.env.NEBUTRA_POSTHOG_HOST??Xs},onError:()=>{}});if(typeof o?.track!="function")return;let r=o.track("scaffold.completed",e);r&&typeof r.then=="function"&&await r.catch(()=>{})}catch{}})()}import G from"fs";import k from"path";function $(e){G.existsSync(e)&&G.rmSync(e,{recursive:!0,force:!0})}function xt(e,t){let n=k.join(e,".env.example");G.existsSync(n)?G.appendFileSync(n,`
 `+t):G.writeFileSync(n,t)}function Rt(e,t){if(!G.existsSync(e))return;let n=G.readFileSync(e,"utf8"),o=n.replace(/export type AuthProviderId\s*=\s*(?:"[^"]+"\s*\|\s*)+"[^"]+";/,`export type AuthProviderId = "${t}";`);o!==n&&G.writeFileSync(e,o)}function Js(e,t){let n=k.join(e,"README.md");if(!G.existsSync(n)){G.writeFileSync(n,t);return}G.appendFileSync(n,`
 `+t)}async function po(e,t){let n=k.join(e,"packages","iam","auth");if(!G.existsSync(n))return;if(t==="none"){$(n),Js(e,`
 ## Auth
@@ -434,7 +434,7 @@ ${o[e.id]}
  * page. The OAuth callback lives at \`/api/auth/callback/<id>\`.
  */
 
-import { Button } from "@nebutra/ui/components";
+import { Button } from "@nebutra/ui/primitives";
 
 interface SocialProvider {
   id: string;

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "create-sailor",
-  "version": "1.9.6",
+  "version": "1.10.0",
+  "nebutra": {
+    "status": "foundation",
+    "graph": "core",
+    "productionReady": false
+  },
   "description": "Governed AI-native SaaS scaffolder for Nebutra Sailor. Bootstrap a production-ready Next.js + Hono + Prisma monorepo with multi-tenant foundations, region-aware defaults, and AI integrations.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "create-sailor": "dist/index.js"
+    "create-sailor": "./bin/create-sailor.js"
   },
   "files": [
+    "bin",
     "dist",
     "templates",
     "README.md",

package/templates/infra/ops/README.md

@@ -1,3 +1,18 @@
 # infra/ops
 
 Operational scripts and runbooks — backup, restore, on-call playbooks, incident response.
+
+## Declared provider state
+
+`platform-expected.example.json` declares the settings that live only in a
+provider dashboard — Vercel build machine and ignore step, Git links, env vars
+that must not be flagged Sensitive, Fly secret names that must exist or must
+not, GitHub repository variables, Cloudflare Worker bindings. Copy it to
+`platform-expected.json`, replace the names, delete the sections you do not
+use, and run the read-only engine from Nebutra-Sailor against it on a schedule:
+
+```bash
+node scripts/ops/platform-reconcile.mjs infra/ops/platform-expected.json --strict
+```
+
+Exit 1 is the alert. Only names are ever declared or printed, never values.

package/templates/infra/ops/platform-expected.example.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "Declare the provider settings that live only in a dashboard, then run scripts/ops/platform-reconcile.mjs against this file on a schedule. Delete every section you do not use; every check is optional. Never put a secret value here — only names.",
+  "version": 1,
+  "vercel": {
+    "projects": [
+      {
+        "name": "{PRODUCT_NAME}-landing",
+        "buildMachineType": "standard",
+        "ignoreBuildStep": "exit 0",
+        "gitLinked": false,
+        "envNotSensitive": {
+          "production": ["NEXT_PUBLIC_SITE_URL", "NEXT_PUBLIC_API_URL"]
+        }
+      },
+      {
+        "name": "{PRODUCT_NAME}-web",
+        "buildMachineType": "standard",
+        "ignoreBuildStep": "exit 0"
+      }
+    ]
+  },
+  "fly": {
+    "apps": [
+      {
+        "name": "{PRODUCT_NAME}-gateway",
+        "secretsPresent": ["QUEUE_PROVIDER", "UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"],
+        "secretsAbsent": ["REDIS_URL", "ALLOW_MEMORY_QUEUE_IN_PRODUCTION"]
+      }
+    ]
+  },
+  "github": {
+    "repo": "your-org/{PRODUCT_NAME}",
+    "variables": {
+      "DEPLOY_TARGET_GATEWAY": "cloudflare-workers"
+    }
+  },
+  "cloudflare": {
+    "workers": [
+      {
+        "name": "{PRODUCT_NAME}-gateway-edge",
+        "bindings": [{ "name": "IP_LIMITER", "type": "ratelimit" }]
+      }
+    ]
+  }
+}

package/templates/tests/README.md

@@ -6,3 +6,21 @@ Cross-cutting tests that don't belong to a single package.
 |--------|------|---------|
 | `architecture/` | vitest | Architecture rules — import boundaries, layering, no-cycle |
 | `load/` | k6 | Load + perf tests against deployed environments |
+
+## `degradation.test.example.ts`
+
+A template, not a live test — no vitest glob matches `.example.ts`, so it is
+inert until you activate it. It is the gateway degradation suite: one
+`describe` per dependency outage (Redis failing every command, Redis
+credentials missing, Redis healthy, database down), each `it` stating the
+behaviour the gateway must have while the outage lasts — which routes keep
+answering, what the health endpoint reports, which failures are logged rather
+than surfaced.
+
+To activate it, move the file to `backends/gateway/src/__tests__/degradation.test.ts`
+(drop `.example`) and follow the numbered steps in its header: point the
+imports at your middleware chain and health routes, mounted in the same order
+as your `index.ts`, and point the `vi.mock()` specifiers at whatever your
+gateway imports for cache, database and logging. The point of the suite is
+that a misconfigured dependency has a tested behaviour before it has an
+incident; add a `describe` for every dependency your gateway gains.

package/templates/tests/degradation.test.example.ts

@@ -0,0 +1,469 @@
+/**
+ * Gateway degradation suite — template.
+ *
+ * A dependency outage is a code path like any other, and it needs a test that
+ * states the intended behaviour: which routes keep answering, what the health
+ * endpoint reports, and which failures are logged rather than surfaced. This
+ * file is the shape Nebutra-Sailor uses for that in
+ * `backends/gateway/src/__tests__/degradation.test.ts`.
+ *
+ * To activate it in a scaffold:
+ *
+ *   1. Move it to `backends/gateway/src/__tests__/degradation.test.ts` — drop
+ *      the `.example` so the gateway's vitest `include` picks it up.
+ *   2. Point the imports in `buildGateway()` at your middleware chain and
+ *      health routes, mounted in the same order and on the same path scopes as
+ *      your `index.ts`. Do not import `index.ts` itself if its module body
+ *      boots telemetry or route groups; compose the pieces instead.
+ *   3. Point the `vi.mock()` specifiers at whatever your gateway imports for
+ *      cache, database and logging. The doubles below match the
+ *      `@nebutra/cache` client surface (get/set/del/eval/ping/incr/incrby/expire).
+ *   4. Replace `s2sHeaders` with however your tenant middleware resolves a
+ *      tenant in tests, so rate-limit and metering keys are real, not
+ *      "anonymous".
+ *
+ * Scenarios, one `describe` each:
+ *
+ *   (a) Redis constructs but every command fails (malformed URL, bad token,
+ *       outage): rate-limited routes answer from the in-memory bucket and
+ *       carry rate-limit headers; health is 200 degraded with cache down.
+ *   (b) Redis credentials missing entirely: same outcome as (a).
+ *   (c) Redis healthy: remaining tokens decrease across requests and the
+ *       limiter issues exactly one EVAL per request.
+ *   (d) Database down: health is 200 degraded with database down; routes that
+ *       do not touch the database keep answering; with Redis also down health
+ *       is 503 unhealthy while those routes still answer.
+ *
+ * When you add a readiness route, it belongs here next to the health route.
+ */
+
+import { Hono } from "hono";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { s2sHeaders, TEST_SERVICE_SECRET } from "./helpers/s2s-token.js";
+
+// ---------------------------------------------------------------------------
+// Module mocks. Hoisted handles survive `vi.resetModules()`, which re-runs the
+// factories below; each re-run hands back the same vi.fn instances.
+// ---------------------------------------------------------------------------
+
+const { getRedis, queryRaw, logger } = vi.hoisted(() => ({
+  getRedis: vi.fn<() => Promise<unknown>>(),
+  queryRaw: vi.fn<() => Promise<unknown>>(),
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+
+vi.mock("@nebutra/cache", () => ({
+  getRedis: () => getRedis(),
+}));
+
+vi.mock("@nebutra/db", () => ({
+  getSystemDb: () => ({ $queryRaw: queryRaw }),
+  prisma: { $queryRaw: queryRaw },
+}));
+
+vi.mock("@nebutra/logger", () => ({ logger }));
+
+// tenantContext imports the auth provider factory statically. It is only
+// invoked for Bearer tokens, which this suite never sends; mocking it keeps
+// the provider SDKs out of the module graph.
+vi.mock("@nebutra/auth/server", () => ({
+  createAuth: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Redis doubles
+// ---------------------------------------------------------------------------
+
+type RedisDouble = {
+  get: ReturnType<typeof vi.fn>;
+  set: ReturnType<typeof vi.fn>;
+  del: ReturnType<typeof vi.fn>;
+  eval: ReturnType<typeof vi.fn>;
+  ping: ReturnType<typeof vi.fn>;
+  incr: ReturnType<typeof vi.fn>;
+  incrby: ReturnType<typeof vi.fn>;
+  expire: ReturnType<typeof vi.fn>;
+};
+
+/**
+ * A client that constructs but fails every command. This is what a malformed
+ * URL, a bad token or an outage looks like from the caller: `getRedis()`
+ * resolves, the first command rejects.
+ */
+function brokenRedis(): RedisDouble {
+  const rejecting = () => vi.fn(async () => Promise.reject(new TypeError("Invalid URL")));
+  return {
+    get: rejecting(),
+    set: rejecting(),
+    del: rejecting(),
+    eval: rejecting(),
+    ping: rejecting(),
+    incr: rejecting(),
+    incrby: rejecting(),
+    expire: rejecting(),
+  };
+}
+
+/**
+ * A working client with just enough state to answer the chain: the token
+ * bucket EVAL decrements by the request cost and reports what is left, the
+ * counters increment, everything else is a key-value map. No refill — the
+ * assertions want determinism, not a second bucket implementation.
+ */
+function healthyRedis(): RedisDouble {
+  const buckets = new Map<string, number>();
+  const kv = new Map<string, unknown>();
+  return {
+    eval: vi.fn(async (_script: string, keys: string[], args: Array<string | number>) => {
+      const key = keys[0] ?? "";
+      // ARGV: now (ms), maxTokens, refillRate, refillInterval (ms), cost, ttl (s)
+      const now = Number(args[0]);
+      const maxTokens = Number(args[1]);
+      const cost = Number(args[4]);
+      const tokens = (buckets.get(key) ?? maxTokens) - cost;
+      buckets.set(key, Math.max(tokens, 0));
+      return [tokens >= 0 ? 1 : 0, Math.max(tokens, 0), now];
+    }),
+    get: vi.fn(async (key: string) => kv.get(key) ?? null),
+    set: vi.fn(async (key: string, value: unknown) => {
+      kv.set(key, value);
+      return "OK";
+    }),
+    del: vi.fn(async (key: string) => (kv.delete(key) ? 1 : 0)),
+    incr: vi.fn(async (key: string) => {
+      const next = Number(kv.get(key) ?? 0) + 1;
+      kv.set(key, next);
+      return next;
+    }),
+    incrby: vi.fn(async (key: string, by: number) => {
+      const next = Number(kv.get(key) ?? 0) + by;
+      kv.set(key, next);
+      return next;
+    }),
+    expire: vi.fn(async () => 1),
+    ping: vi.fn(async () => "PONG"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// App under test — adapt the imports and mounts to your gateway.
+// ---------------------------------------------------------------------------
+
+async function buildGateway() {
+  vi.resetModules();
+
+  const [
+    { tenantContextMiddleware },
+    { usageMeteringMiddleware },
+    { idempotencyMiddleware },
+    { rateLimitMiddleware },
+    { shouldSkipGlobalRateLimit },
+    { healthRoutes },
+  ] = await Promise.all([
+    import("../middlewares/tenantContext.js"),
+    import("../middlewares/usageMetering.js"),
+    import("../middlewares/idempotency.js"),
+    import("../middlewares/rateLimit.js"),
+    import("../middlewares/rateLimitSkip.js"),
+    import("../routes/misc/health.js"),
+  ]);
+
+  const handled = vi.fn();
+  const app = new Hono();
+
+  // Same mounts, same order, same path scopes as index.ts.
+  app.use("*", tenantContextMiddleware);
+  app.use("/api/v1/*", usageMeteringMiddleware);
+  app.use("/api/v1/*", idempotencyMiddleware);
+  app.use("/api/*", async (c, next) => {
+    const path = new URL(c.req.url).pathname;
+    if (shouldSkipGlobalRateLimit(path)) return next();
+    return rateLimitMiddleware(c, next);
+  });
+
+  app.route("/api/misc", healthRoutes);
+  app.get("/api/v1/things", (c) => {
+    handled();
+    return c.json({ items: [] });
+  });
+  app.post("/api/v1/things", (c) => {
+    handled();
+    return c.json({ id: "thing_1" }, 201);
+  });
+
+  return { app, handled };
+}
+
+type Gateway = Awaited<ReturnType<typeof buildGateway>>;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const REDIS_ENV = [
+  "UPSTASH_REDIS_REST_URL",
+  "UPSTASH_REDIS_REST_TOKEN",
+  "UPSTASH_REDIS_URL",
+  "UPSTASH_REDIS_TOKEN",
+] as const;
+
+function redisConfigured(present: boolean) {
+  for (const name of REDIS_ENV) vi.stubEnv(name, undefined);
+  if (present) {
+    vi.stubEnv("UPSTASH_REDIS_REST_URL", "https://x.upstash.io");
+    vi.stubEnv("UPSTASH_REDIS_REST_TOKEN", "t");
+  }
+}
+
+/** A resolved tenant, so rate-limit and metering keys are real, not "anonymous". */
+function tenantHeaders() {
+  return s2sHeaders({
+    userId: "user_degradation",
+    orgId: "org_degradation",
+    role: "org:member",
+    plan: "FREE",
+  });
+}
+
+async function getThings(app: Gateway["app"]) {
+  return app.request("/api/v1/things", { method: "GET", headers: await tenantHeaders() });
+}
+
+async function getHealth(app: Gateway["app"]) {
+  return app.request("/api/misc/health", { method: "GET" });
+}
+
+/** Metering writes behind `void (async () => …)()`; let the microtasks drain. */
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+const FREE_LIMIT = "100";
+
+beforeEach(() => {
+  vi.stubEnv("SERVICE_SECRET", TEST_SERVICE_SECRET);
+  queryRaw.mockResolvedValue([{ "?column?": 1 }]);
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+});
+
+// ===========================================================================
+// (a) Redis constructs but every command fails
+// ===========================================================================
+
+describe("Redis constructs but every command fails (TypeError: Invalid URL)", () => {
+  let redis: RedisDouble;
+  let gateway: Gateway;
+
+  beforeEach(async () => {
+    redisConfigured(true);
+    redis = brokenRedis();
+    getRedis.mockResolvedValue(redis);
+    gateway = await buildGateway();
+  });
+
+  it("GET /api/v1/things answers from the route, rate-limited by the in-memory bucket", async () => {
+    const res = await getThings(gateway.app);
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ items: [] });
+    expect(gateway.handled).toHaveBeenCalledOnce();
+
+    // The store was tried and failed — this is the fallback, not a skip.
+    expect(redis.eval).toHaveBeenCalled();
+    expect(res.headers.get("x-ratelimit-limit")).toBe(FREE_LIMIT);
+    const remaining = Number(res.headers.get("x-ratelimit-remaining"));
+    expect(remaining).toBeGreaterThanOrEqual(0);
+    expect(remaining).toBeLessThan(Number(FREE_LIMIT));
+    expect(res.headers.get("x-ratelimit-reset")).toMatch(/^\d+$/);
+  });
+
+  it("keeps serving after repeated failures — the fallback is per request, not per process", async () => {
+    const first = await getThings(gateway.app);
+    const second = await getThings(gateway.app);
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(gateway.handled).toHaveBeenCalledTimes(2);
+    expect(Number(second.headers.get("x-ratelimit-remaining"))).toBeLessThan(
+      Number(first.headers.get("x-ratelimit-remaining")),
+    );
+  });
+
+  it("logs the metering write failure instead of surfacing it", async () => {
+    const res = await getThings(gateway.app);
+    await flush();
+
+    expect(res.status).toBe(200);
+    expect(redis.incr).toHaveBeenCalledOnce();
+    expect(logger.warn).toHaveBeenCalledWith(
+      "Usage metering write failed",
+      expect.objectContaining({ tenantId: "org_degradation" }),
+    );
+  });
+
+  it("GET /api/misc/health reports cache down and stays 200 degraded", async () => {
+    const res = await getHealth(gateway.app);
+    const body = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.status).toBe("degraded");
+    expect(body.dependencies.cache.status).toBe("down");
+    expect(body.dependencies.database.status).toBe("up");
+  });
+
+  it.todo(
+    "POST /api/v1/things with an Idempotency-Key needs a decided behaviour while Redis is down — an idempotency store with no fallback surfaces the outage as a 500; fail-closed (503 + Retry-After) or fail-open is a product call, pin it here once made",
+  );
+});
+
+// ===========================================================================
+// (b) Redis credentials are missing entirely
+// ===========================================================================
+
+describe("Redis credentials are missing entirely", () => {
+  let gateway: Gateway;
+
+  beforeEach(async () => {
+    redisConfigured(false);
+    // What @nebutra/cache's getRedisConfig() throws when no URL/token is set.
+    getRedis.mockRejectedValue(new Error("Redis credentials not configured"));
+    gateway = await buildGateway();
+  });
+
+  it("GET /api/v1/things answers from the route, rate-limited by the in-memory bucket", async () => {
+    const res = await getThings(gateway.app);
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ items: [] });
+    expect(gateway.handled).toHaveBeenCalledOnce();
+    expect(res.headers.get("x-ratelimit-limit")).toBe(FREE_LIMIT);
+    expect(Number(res.headers.get("x-ratelimit-remaining"))).toBeLessThan(Number(FREE_LIMIT));
+  });
+
+  it("does not surface the metering no-op as an error", async () => {
+    const res = await getThings(gateway.app);
+    await flush();
+
+    expect(res.status).toBe(200);
+    // usageMetering resolves the client once and treats "not configured" as
+    // a local-dev no-op: nothing to warn about.
+    expect(logger.warn).not.toHaveBeenCalledWith("Usage metering write failed", expect.anything());
+  });
+
+  it("GET /api/misc/health reports cache down and stays 200 degraded", async () => {
+    const res = await getHealth(gateway.app);
+    const body = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.status).toBe("degraded");
+    expect(body.dependencies.cache.status).toBe("down");
+    expect(body.dependencies.database.status).toBe("up");
+  });
+});
+
+// ===========================================================================
+// (c) Redis is healthy
+// ===========================================================================
+
+describe("Redis is healthy", () => {
+  let redis: RedisDouble;
+  let gateway: Gateway;
+
+  beforeEach(async () => {
+    redisConfigured(true);
+    redis = healthyRedis();
+    getRedis.mockResolvedValue(redis);
+    gateway = await buildGateway();
+  });
+
+  it("x-ratelimit-remaining decreases across two requests, one EVAL per request", async () => {
+    const first = await getThings(gateway.app);
+    expect(first.status).toBe(200);
+    expect(redis.eval).toHaveBeenCalledTimes(1);
+
+    const second = await getThings(gateway.app);
+    expect(second.status).toBe(200);
+    expect(redis.eval).toHaveBeenCalledTimes(2);
+
+    // Default API weight is 2 tokens; FREE starts at 100.
+    expect(first.headers.get("x-ratelimit-limit")).toBe(FREE_LIMIT);
+    expect(first.headers.get("x-ratelimit-remaining")).toBe("98");
+    expect(second.headers.get("x-ratelimit-remaining")).toBe("96");
+
+    // The atomic script is the only rate-limit command: no GET+SET fallback ran.
+    expect(redis.get).not.toHaveBeenCalled();
+    expect(redis.set).not.toHaveBeenCalled();
+    expect(gateway.handled).toHaveBeenCalledTimes(2);
+  });
+
+  it("meters each request once under the tenant's billing-period key", async () => {
+    await getThings(gateway.app);
+    await getThings(gateway.app);
+    await flush();
+
+    expect(redis.incr).toHaveBeenCalledTimes(2);
+    expect(redis.incr.mock.calls[0]?.[0]).toMatch(/^usage:org_degradation:\d{4}-\d{2}:api_calls$/);
+    expect(logger.warn).not.toHaveBeenCalledWith("Usage metering write failed", expect.anything());
+  });
+
+  it("GET /api/misc/health is 200 healthy with both dependencies up", async () => {
+    const res = await getHealth(gateway.app);
+    const body = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.status).toBe("healthy");
+    expect(body.dependencies.database.status).toBe("up");
+    expect(body.dependencies.cache.status).toBe("up");
+    expect(redis.ping).toHaveBeenCalledOnce();
+  });
+});
+
+// ===========================================================================
+// (d) The database is down
+// ===========================================================================
+
+describe("The database is down", () => {
+  let gateway: Gateway;
+
+  beforeEach(async () => {
+    redisConfigured(true);
+    getRedis.mockResolvedValue(healthyRedis());
+    queryRaw.mockRejectedValue(new Error("connection refused"));
+    gateway = await buildGateway();
+  });
+
+  it("GET /api/misc/health reports database down and stays 200 degraded", async () => {
+    const res = await getHealth(gateway.app);
+    const body = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.status).toBe("degraded");
+    expect(body.dependencies.database.status).toBe("down");
+    expect(body.dependencies.cache.status).toBe("up");
+  });
+
+  it("routes that do not touch the database keep answering", async () => {
+    const res = await getThings(gateway.app);
+
+    expect(res.status).toBe(200);
+    expect(gateway.handled).toHaveBeenCalledOnce();
+  });
+
+  it("with Redis also down, health is 503 unhealthy while the route still answers", async () => {
+    getRedis.mockResolvedValue(brokenRedis());
+    gateway = await buildGateway();
+
+    const health = await getHealth(gateway.app);
+    const body = await health.json();
+    expect(health.status).toBe(503);
+    expect(body.status).toBe("unhealthy");
+    expect(body.dependencies.database.status).toBe("down");
+    expect(body.dependencies.cache.status).toBe("down");
+
+    const things = await getThings(gateway.app);
+    expect(things.status).toBe(200);
+    expect(things.headers.get("x-ratelimit-limit")).toBe(FREE_LIMIT);
+  });
+});