create-stitchkit 0.3.3 → 0.4.1

package/template/packages/frontend/src/lib/seo/metadata.ts

@@ -1,25 +1,57 @@
-import type { Metadata } from 'next';
-import { env } from '@/env';
+import type { Metadata, MetadataRoute } from 'next';
 import type { AppLocale } from '@/i18n/locales';
 import { locales } from '@/i18n/locales';
+import { cacheByOrigin } from './cache-by-origin';
 import type { SeoPageId } from './pages';
-import { getSeoPage, localizedPagePath, SITE_NAME } from './pages';
+import { getSeoPage, localizedPagePath, publicPageIds, SITE_NAME } from './pages';
+import { requestOrigin } from './request-origin';
 
-export const siteOrigin = new URL(env.NEXT_PUBLIC_WEB_URL).origin;
+/** Absolute URL for `path` on the origin this response is being served from. */
+export async function absoluteSiteUrl(path: string): Promise<string> {
+  return siteUrl(await requestOrigin(), path);
+}
+
+function siteUrl(origin: string, path: string): string {
+  return new URL(path, origin).toString();
+}
 
-export function absoluteSiteUrl(path: string): string {
-  return new URL(path, siteOrigin).toString();
+interface PageMetadataInput {
+  origin: string;
+  pageId: SeoPageId;
+  locale: AppLocale;
 }
 
-export function createPageMetadata(pageId: SeoPageId, locale: AppLocale): Metadata {
+/**
+ * Page metadata for one origin. Pure in its inputs, so it is built once per
+ * (origin, page, locale) instead of once per request — the cost of trading a
+ * build-time constant for a request-time value, paid once per address.
+ */
+const metadataFor = cacheByOrigin(
+  ({ origin, pageId, locale }: PageMetadataInput) => `${origin}|${pageId}|${locale}`,
+  ({ origin, pageId, locale }: PageMetadataInput) => buildPageMetadata(origin, pageId, locale),
+);
+
+export async function createPageMetadata(
+  pageId: SeoPageId,
+  locale: AppLocale,
+): Promise<Metadata> {
+  return metadataFor({ origin: await requestOrigin(), pageId, locale });
+}
+
+/** `metadataBase` for the origin in hand — relative metadata resolves against it. */
+export async function siteMetadataBase(): Promise<URL> {
+  return new URL(await requestOrigin());
+}
+
+function buildPageMetadata(origin: string, pageId: SeoPageId, locale: AppLocale): Metadata {
   const page = getSeoPage(pageId, locale);
   const title = pageId === 'home' ? SITE_NAME : `${page.title} · ${SITE_NAME}`;
   const canonicalPath = localizedPagePath(pageId, locale);
-  const image = absoluteSiteUrl(`/api/og/${locale}/${pageId}`);
+  const image = siteUrl(origin, `/api/og/${locale}/${pageId}`);
   const languageAlternates = Object.fromEntries(
     locales.map((availableLocale) => [
       availableLocale,
-      absoluteSiteUrl(localizedPagePath(pageId, availableLocale)),
+      siteUrl(origin, localizedPagePath(pageId, availableLocale)),
     ]),
   );
 
@@ -27,7 +59,7 @@ export function createPageMetadata(pageId: SeoPageId, locale: AppLocale): Metada
     title,
     description: page.description,
     alternates: {
-      canonical: absoluteSiteUrl(canonicalPath),
+      canonical: siteUrl(origin, canonicalPath),
       languages: languageAlternates,
     },
     openGraph: {
@@ -35,7 +67,7 @@ export function createPageMetadata(pageId: SeoPageId, locale: AppLocale): Metada
       siteName: SITE_NAME,
       title,
       description: page.description,
-      url: absoluteSiteUrl(canonicalPath),
+      url: siteUrl(origin, canonicalPath),
       locale: locale === 'ru' ? 'ru_RU' : 'en_US',
       alternateLocale: locale === 'ru' ? ['en_US'] : ['ru_RU'],
       images: [{ url: image, width: 1200, height: 630, alt: `${title} — ${page.eyebrow}` }],
@@ -48,3 +80,28 @@ export function createPageMetadata(pageId: SeoPageId, locale: AppLocale): Metada
     },
   };
 }
+
+/**
+ * Sitemap entries for one origin — the same value for every request that
+ * arrives on that address, so it is built once per address.
+ */
+export const sitemapForOrigin = cacheByOrigin(
+  (origin: string) => origin,
+  (origin: string): MetadataRoute.Sitemap =>
+    publicPageIds.flatMap(
+      (pageId): MetadataRoute.Sitemap =>
+        locales.map((locale) => ({
+          url: siteUrl(origin, localizedPagePath(pageId, locale)),
+          changeFrequency: pageId === 'home' ? 'weekly' : 'monthly',
+          priority: pageId === 'home' ? 1 : 0.7,
+          alternates: {
+            languages: Object.fromEntries(
+              locales.map((availableLocale) => [
+                availableLocale,
+                siteUrl(origin, localizedPagePath(pageId, availableLocale)),
+              ]),
+            ),
+          },
+        })),
+    ),
+);

package/template/packages/frontend/src/lib/seo/pages.ts

@@ -1,4 +1,4 @@
-import { appIdentity } from '@app/config/identity';
+import { appIdentity } from '@app/config/app-identity';
 import { z } from 'zod';
 import type { AppLocale } from '@/i18n/locales';
 

package/template/packages/frontend/src/lib/seo/request-origin.ts

@@ -0,0 +1,89 @@
+import { headers } from 'next/headers';
+import { env } from '@/env';
+
+/**
+ * The public origin this response is being served on.
+ *
+ * Derived from the REQUEST, never from the build. An absolute address read at
+ * build time is frozen into the artifact — `robots.txt` and `sitemap.xml` were
+ * prerendered with one origin inside their bytes, so a single build could not
+ * serve a second address. Reading the request instead makes one artifact
+ * correct at every address it is ever routed to.
+ *
+ * **The request is not trusted on its own.** `x-forwarded-host` is set by
+ * whoever is in front of this process, and a request that reaches the role
+ * directly can set it too. An unchecked value would put an attacker's host into
+ * canonical URLs, the sitemap and OG metadata — the artifact would be portable
+ * and also forgeable. So a forwarded host is honoured only when the deployment
+ * has said which hosts it serves, and `PUBLIC_WEB_ORIGIN` remains the way to
+ * state a single one.
+ *
+ * Both are read at RUNTIME (no `NEXT_PUBLIC_` prefix, so nothing is substituted
+ * at build time).
+ */
+export async function requestOrigin(): Promise<string> {
+  const configured = env.PUBLIC_WEB_ORIGIN;
+  if (configured) return new URL(configured).origin;
+
+  const incoming = await headers();
+  const host = firstValue(incoming.get('x-forwarded-host') ?? incoming.get('host'));
+  if (!host) {
+    throw new Error(
+      'Cannot determine the public origin: the request carried no Host header. Set PUBLIC_WEB_ORIGIN.',
+    );
+  }
+  if (!isAllowedHost(host)) {
+    throw new Error(
+      `Refusing to answer for host "${host}": it is not in PUBLIC_WEB_HOSTS. Set PUBLIC_WEB_ORIGIN for a single address, or PUBLIC_WEB_HOSTS for several.`,
+    );
+  }
+  return new URL(`${protocolOf(incoming.get('x-forwarded-proto'))}://${host}`).origin;
+}
+
+/**
+ * Which hosts this deployment serves.
+ *
+ * Empty means "only what `PUBLIC_WEB_ORIGIN` says", and since that short-circuits
+ * above, an empty list with no origin set is a deployment that has not been told
+ * where it lives — which is an error, not a licence to believe the caller.
+ *
+ * There is deliberately no wildcard: serving any host is the same as having no
+ * canonical origin, and every answer this module gives is a canonical origin.
+ */
+function isAllowedHost(host: string): boolean {
+  const allowed = env.PUBLIC_WEB_HOSTS?.split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0);
+  if (!allowed || allowed.length === 0) return false;
+  // No wildcard. `*` read as "serve any host" — which is the same as having no
+  // canonical origin at all, and therefore no meaningful answer to give for a
+  // canonical URL, a sitemap or an OG card. A deployment that genuinely serves
+  // many addresses lists them; one that does not know which it serves has a
+  // configuration problem, not a licence to believe the caller.
+  return allowed.includes(host.toLowerCase());
+}
+
+/**
+ * The scheme this response is being served over.
+ *
+ * Only two are possible, and anything else is a misconfigured proxy or a
+ * forgery — both of which must be seen, not normalised. Mapping every unknown
+ * value to `http` meant `ftp`, `javascript` and a truncated header all produced
+ * a plausible-looking origin, and the answer went into canonical URLs.
+ *
+ * A missing header is not a failure: a deployment reached directly has no
+ * forwarding layer, and `http` is then the truth.
+ */
+function protocolOf(header: string | null): 'http' | 'https' {
+  const forwarded = firstValue(header)?.toLowerCase();
+  if (forwarded === undefined) return 'http';
+  if (forwarded === 'http' || forwarded === 'https') return forwarded;
+  throw new Error(
+    `Refusing to answer for forwarded protocol "${forwarded}": x-forwarded-proto must be http or https. Fix the proxy, or set PUBLIC_WEB_ORIGIN to state the public origin outright.`,
+  );
+}
+
+/** A forwarded header may carry the whole proxy chain — the first hop is ours. */
+function firstValue(header: string | null): string | undefined {
+  return header?.split(',')[0]?.trim() || undefined;
+}

package/template/packages/frontend/src/theme/config.ts

@@ -1,4 +1,4 @@
-import { appIdentity } from '@app/config/identity';
+import { appIdentity } from '@app/config/app-identity';
 import type { ThemeProviderProps } from '@wrksz/themes/next';
 
 export type AppTheme = 'light' | 'dark';

package/template/packages/frontend/tsconfig.json

@@ -5,15 +5,22 @@
     "jsx": "react-jsx",
     "incremental": true,
     "types": ["bun"],
-    "plugins": [{ "name": "next" }],
-    "paths": { "@/*": ["./src/*"] }
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
   },
   "include": [
     "next-env.d.ts",
     "next.config.ts",
     "src/**/*.ts",
     "src/**/*.tsx",
-    ".next/types/**/*.ts"
+    ".next/types/**/*.ts",
+    "scripts/**/*.ts"
   ],
   "exclude": ["node_modules"]
 }

package/template/packages/shared/package.json

@@ -16,7 +16,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   }
 }

package/template/playwright.config.ts

@@ -2,7 +2,7 @@ import { defineConfig, devices } from '@playwright/test';
 import { loadToolingEnv } from './scripts/tooling-env';
 
 const toolingEnv = loadToolingEnv();
-const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.NEXT_PUBLIC_WEB_URL;
+const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.SMOKE_WEB_ORIGIN;
 
 export default defineConfig({
   testDir: './e2e',

package/template/project.json

@@ -0,0 +1,169 @@
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "identity": {
+    "slug": "stitchkit-starter",
+    "name": "Stitchkit Starter",
+    "version": "0.1.0",
+    "description": {
+      "en": "Stitchkit Starter is a production application built with Stitchkit.",
+      "ru": "Stitchkit Starter — production-приложение на Stitchkit."
+    }
+  },
+  "roles": [
+    {
+      "name": "api",
+      "workingDirectory": "packages/backend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "--watch",
+            "src/index.ts"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "dist/index.js"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "API_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/health"
+      },
+      "drainFloorMs": 15000
+    },
+    {
+      "name": "web",
+      "workingDirectory": "packages/frontend",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "development"
+          ]
+        },
+        "production": {
+          "executable": "bun",
+          "args": [
+            "scripts/serve.ts",
+            "production"
+          ]
+        }
+      },
+      "listener": {
+        "portVariable": "WEB_PORT",
+        "bindVariable": "BIND_HOST",
+        "readinessPath": "/"
+      },
+      "drainFloorMs": 5000
+    }
+  ],
+  "build": {
+    "command": {
+      "executable": "bun",
+      "args": [
+        "run",
+        "build"
+      ]
+    },
+    "artifacts": [
+      "packages/backend/dist",
+      "packages/frontend/.next",
+      "packages/db/src/generated"
+    ]
+  },
+  "requires": [
+    {
+      "name": "postgres",
+      "phases": [
+        "release",
+        "start"
+      ]
+    }
+  ],
+  "release": {
+    "migrations": {
+      "engine": "prisma",
+      "root": "packages/db/migrations",
+      "lockfile": "packages/db/migrations/migration_lock.toml"
+    }
+  },
+  "env": {
+    "variables": [
+      {
+        "name": "API_PORT",
+        "shape": "integer",
+        "required": true
+      },
+      {
+        "name": "BIND_HOST",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "CORS_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "DATABASE_URL",
+        "shape": "url",
+        "required": true
+      },
+      {
+        "name": "INTERNAL_API_URL",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "LOG_FORMAT",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "pretty",
+          "json"
+        ]
+      },
+      {
+        "name": "NODE_ENV",
+        "shape": "enum",
+        "required": false,
+        "members": [
+          "development",
+          "test",
+          "production"
+        ]
+      },
+      {
+        "name": "PUBLIC_API_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_REALTIME_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_HOSTS",
+        "shape": "string",
+        "required": false
+      },
+      {
+        "name": "PUBLIC_WEB_ORIGIN",
+        "shape": "url",
+        "required": false
+      },
+      {
+        "name": "WEB_PORT",
+        "shape": "integer",
+        "required": true
+      }
+    ]
+  }
+}

package/template/scripts/acceptance-database.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test';
+import { resolveAcceptanceDatabase } from './acceptance-database';
+
+const deployment = 'postgresql://app:secret@127.0.0.1:5432/starter';
+
+describe('the acceptance gate writes only to a database of its own', () => {
+  test('a distinct database is accepted', () => {
+    expect(
+      resolveAcceptanceDatabase({
+        DATABASE_URL: deployment,
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app:secret@127.0.0.1:5432/starter_acceptance',
+      }),
+    ).toBe('postgresql://app:secret@127.0.0.1:5432/starter_acceptance');
+  });
+
+  test('an unset variable is refused with the line to paste', () => {
+    // The gate used to inherit DATABASE_URL. Defaulting to it is exactly the
+    // behaviour this replaces, so absence has to be a refusal, not a fallback.
+    expect(() => resolveAcceptanceDatabase({ DATABASE_URL: deployment })).toThrow(
+      /ACCEPTANCE_DATABASE_URL=postgresql:\/\/app:secret@127\.0\.0\.1:5432\/starter_acceptance/,
+    );
+  });
+
+  test('the same database written differently is still the same database', () => {
+    // Credentials and the scheme do not make it another database; host, port
+    // and name do. A check on the raw string would pass this and then migrate
+    // the deployment.
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: deployment,
+        ACCEPTANCE_DATABASE_URL: 'postgres://someone:else@127.0.0.1/starter',
+      }),
+    ).toThrow(/which is the one DATABASE_URL names/);
+  });
+
+  test('a default port on one side and 5432 on the other is one database', () => {
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@db.internal/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@db.internal:5432/starter',
+      }),
+    ).toThrow(/which is the one DATABASE_URL names/);
+  });
+
+  test('the same name on another hostname is refused, because a hostname proves nothing', () => {
+    // `localhost` and `127.0.0.1` are one server; so are two DNS names for the
+    // same PostgreSQL. A guard that compared `host:port/name` called these two
+    // different databases and let the gate migrate the deployment's own.
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@localhost:5432/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@127.0.0.1:5432/starter',
+      }),
+    ).toThrow(/A different host is not proof of a different server/);
+  });
+
+  test('a different name on the same host is fine — the name is what decides', () => {
+    // The control. Without it the rule "refuse everything" would pass the case
+    // above, and no acceptance database would ever be accepted.
+    expect(
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@localhost:5432/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@localhost:5432/starter_acceptance',
+      }),
+    ).toContain('starter_acceptance');
+  });
+
+  test('a value that is not a URL is named, not silently used', () => {
+    expect(() =>
+      resolveAcceptanceDatabase({ ACCEPTANCE_DATABASE_URL: 'starter_acceptance' }),
+    ).toThrow(/ACCEPTANCE_DATABASE_URL is not a valid URL/);
+  });
+});

package/template/scripts/acceptance-database.ts

@@ -0,0 +1,92 @@
+/**
+ * The database the local acceptance gate is allowed to write to.
+ *
+ * `acceptance:local` creates and destroys its own deployment — its own PM2 home,
+ * its own ephemeral ports, its own host allowlist. The database was the one
+ * thing it still borrowed: it inherited `DATABASE_URL`, and the runtime gates
+ * WRITE. The repository example's smoke posts `/api/repository/refresh` twice,
+ * which upserts. So a gate a developer is told to run before handing work off
+ * wrote rows into whatever `.env` happened to name — including a production
+ * database, if that is what the machine was pointed at.
+ *
+ * Fail-closed on purpose. An acceptance database that is merely *probably*
+ * separate is the same defect one edit later, so an unset variable and one that
+ * names the deployment's own database are both refused before a role starts,
+ * and the refusal carries the line to paste.
+ */
+
+/**
+ * The database NAME, which is all a refusal may rely on.
+ *
+ * Comparing `host:port/name` catches the ordinary mistake and misses the ones
+ * that matter: `localhost` and `127.0.0.1` are one server, and so are two DNS
+ * names pointing at the same PostgreSQL. A guard that reads those as different
+ * databases lets this gate migrate and write into the deployment's own.
+ *
+ * A hostname is not proof of a different server, so it does not take part in
+ * the decision. The cost is a false refusal when two genuinely separate servers
+ * host a database of the same name — answered by renaming the throwaway one,
+ * which the message asks for. That is the trade a fail-closed gate is supposed
+ * to make.
+ */
+function databaseName(url: URL): string {
+  return decodeURIComponent(url.pathname.replace(/^\//, '').replace(/\/+$/, ''));
+}
+
+function parse(name: string, value: string): URL {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`${name} is not a valid URL.`);
+  }
+}
+
+/** `…/app` → `…/app_acceptance`, so the refusal can name a line worth pasting. */
+function suggestionFrom(deploymentUrl: string | undefined): string {
+  if (!deploymentUrl) return 'postgresql://USER:PASSWORD@127.0.0.1:5432/acceptance';
+  try {
+    const url = new URL(deploymentUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, '')}_acceptance`;
+    return url.toString();
+  } catch {
+    return 'postgresql://USER:PASSWORD@127.0.0.1:5432/acceptance';
+  }
+}
+
+/**
+ * The acceptance database URL, or a refusal explaining exactly what to add.
+ *
+ * Takes the environment rather than reading it, so the rule that keeps a gate
+ * off the deployment's database is testable without one.
+ */
+export function resolveAcceptanceDatabase(
+  environment: Record<string, string | undefined>,
+): string {
+  const acceptance = environment.ACCEPTANCE_DATABASE_URL?.trim();
+  const deployment = environment.DATABASE_URL?.trim();
+
+  if (!acceptance) {
+    throw new Error(
+      'ACCEPTANCE_DATABASE_URL is not set, and `bun run acceptance:local` will not write to the ' +
+        'database this deployment uses. Add a line naming a throwaway database to `.env`:\n' +
+        `  ACCEPTANCE_DATABASE_URL=${suggestionFrom(deployment)}`,
+    );
+  }
+
+  const acceptanceUrl = parse('ACCEPTANCE_DATABASE_URL', acceptance);
+  if (deployment) {
+    const deploymentUrl = parse('DATABASE_URL', deployment);
+    if (databaseName(acceptanceUrl) === databaseName(deploymentUrl)) {
+      throw new Error(
+        `ACCEPTANCE_DATABASE_URL uses the database name "${databaseName(acceptanceUrl)}", which is ` +
+          'the one DATABASE_URL names. A different host is not proof of a different server — ' +
+          '`localhost` and `127.0.0.1` are one, and so are two DNS names for the same ' +
+          'PostgreSQL — and this gate applies migrations and writes rows. Give it a name of ' +
+          'its own:\n' +
+          `  ACCEPTANCE_DATABASE_URL=${suggestionFrom(deployment)}`,
+      );
+    }
+  }
+
+  return acceptanceUrl.toString();
+}