@saena-io/create 0.1.0

package/template/base/src/routes/index.tsx

@@ -0,0 +1,19 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+// Your public homepage. SAENA renders the admin at /admin; everything outside /admin is yours to build.
+export const Route = createFileRoute('/')({ component: Home });
+
+function Home() {
+  return (
+    <main className="mx-auto flex min-h-screen max-w-2xl flex-col justify-center gap-4 p-8">
+      <h1 className="font-semibold text-3xl tracking-tight">{{PROJECT_NAME}}</h1>
+      <p className="text-muted-foreground">
+        Your SAENA app is running. Manage content and settings in the{' '}
+        <a className="underline underline-offset-4" href="/admin">
+          admin
+        </a>
+        .
+      </p>
+    </main>
+  );
+}

package/template/base/src/server/admin-context.ts

@@ -0,0 +1,39 @@
+import { serverPlugins } from '@/plugins';
+import { PLUGIN_CATALOG } from '@saena-io/catalog';
+import { describePredefinedRoles } from '@saena-io/core';
+import {
+  type AdminContextData,
+  CORE_PERMISSIONS,
+  type Permission,
+  type PluginCatalogView,
+} from '@saena-io/plugin-sdk';
+import { createServerFn } from '@tanstack/react-start';
+import { requireCtx } from './require-ctx';
+
+// The admin shell's per-request context (ADR-0012 phase 3 + roadmap M5). Returns the signed-in actor's resolved
+// permission ids — for ADVISORY client-side nav/section gating (hiding what they can't use; the server fns are
+// still the real boundary, §10) — a read-only reference of the predefined roles, and the plugin catalog annotated
+// with what THIS project has installed (for the Help screen). Any authenticated staff may read it: it's their own
+// permission set + the public role/plugin catalogues, so it gates on a session (requireCtx) without a permission.
+export const getAdminContextFn = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<AdminContextData> => {
+    const ctx = await requireCtx();
+    const permissions = ctx.actor.kind === 'staff' ? [...ctx.actor.permissions] : [];
+    const catalogue: Permission[] = [
+      ...CORE_PERMISSIONS,
+      ...serverPlugins.flatMap((p) => p.permissions ?? []),
+    ];
+    const installed = new Set(serverPlugins.map((p) => p.id));
+    const plugins: PluginCatalogView[] = PLUGIN_CATALOG.map((e) => ({
+      id: e.id,
+      name: e.name,
+      summary: e.summary,
+      category: e.category,
+      package: e.package,
+      dependsOn: e.dependsOn,
+      status: e.status,
+      installed: installed.has(e.id),
+    }));
+    return { permissions, roles: describePredefinedRoles(catalogue), plugins };
+  },
+);

package/template/base/src/server/auth.ts

@@ -0,0 +1,32 @@
+import { createStaffAuth, resolveActor } from '@saena-io/core';
+import type { Actor } from '@saena-io/plugin-sdk';
+import { getCoreDb } from './core';
+
+const SECRET = process.env.BETTER_AUTH_SECRET ?? 'dev-secret-change-me-0123456789abcdef';
+// Must match the dev server origin (WEB_PORT) so better-auth's origin/CSRF check passes.
+const BASE_URL = process.env.BETTER_AUTH_URL ?? 'http://localhost:3100';
+
+// Server-only: the staff (admin) better-auth audience (§10). The customer audience moved to @saena-io/customers
+// (roadmap M0); a logged-in storefront wires its instance (createCustomerAuth) post-launch. Lazy so a build
+// doesn't require DATABASE_URL at import.
+let staffAuth: ReturnType<typeof createStaffAuth> | null = null;
+
+export function getStaffAuth() {
+  if (!staffAuth) {
+    staffAuth = createStaffAuth(getCoreDb(), {
+      secret: SECRET,
+      baseURL: BASE_URL,
+      basePath: '/api/auth/staff',
+    });
+  }
+  return staffAuth;
+}
+
+/**
+ * The auth-vendor seam (roadmap M0): resolve a request's `Actor` from the staff better-auth session. Passed to
+ * `createRequestContext` as `resolveActor`, so core's request context carries no auth-vendor dependency — this one
+ * function is the single point a different identity provider (Clerk/Auth0) would replace.
+ */
+export function resolveRequestActor(headers: Headers): Promise<Actor> {
+  return resolveActor({ staff: getStaffAuth() }, getCoreDb(), headers);
+}

package/template/base/src/server/branding.ts

@@ -0,0 +1,19 @@
+import { getBranding, upsertBranding } from '@saena-io/core';
+import { brandingInputSchema } from '@saena-io/plugin-sdk';
+import { createServerFn } from '@tanstack/react-start';
+import { getCoreDb } from './core';
+import { requireCtx } from './require-ctx';
+
+/** Read the editable branding — null before it's first configured. */
+export const getBrandingFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('settings.manage');
+  return getBranding(getCoreDb());
+});
+
+/** Persist branding, validated against the shared schema. */
+export const saveBrandingFn = createServerFn({ method: 'POST' })
+  .validator(brandingInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('settings.manage');
+    return upsertBranding(getCoreDb(), data);
+  });

package/template/base/src/server/business-profile.ts

@@ -0,0 +1,19 @@
+import { getBusinessProfile, upsertBusinessProfile } from '@saena-io/core';
+import { businessProfileInputSchema } from '@saena-io/plugin-sdk';
+import { createServerFn } from '@tanstack/react-start';
+import { getCoreDb } from './core';
+import { requireCtx } from './require-ctx';
+
+/** Read the editable business profile — null before it's first configured. */
+export const getBusinessProfileFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('settings.manage');
+  return getBusinessProfile(getCoreDb());
+});
+
+/** Persist the business profile, validated against the shared schema. */
+export const saveBusinessProfileFn = createServerFn({ method: 'POST' })
+  .validator(businessProfileInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('settings.manage');
+    return upsertBusinessProfile(getCoreDb(), data);
+  });

package/template/base/src/server/core.ts

@@ -0,0 +1,41 @@
+import {
+  type Db,
+  createCoreContext,
+  createDb,
+  createLocalDiskProvider,
+  createStorageService,
+} from '@saena-io/core';
+import type { CoreContext } from '@saena-io/plugin-sdk';
+
+// Server-only: the core's Postgres handle, opened lazily (a build — or a request that never touches
+// core data — doesn't need DATABASE_URL at import time). Shared across the admin server functions.
+let db: Db | null = null;
+
+export function getCoreDb(): Db {
+  if (!db) {
+    const connectionString = process.env.DATABASE_URL;
+    if (!connectionString) {
+      throw new Error('DATABASE_URL is not set — admin data access needs Postgres (see .env).');
+    }
+    db = createDb(connectionString);
+  }
+  return db;
+}
+
+// The system CoreContext (db + i18n + profile + events + warn-only jobs), built once. The plugin host and
+// the /api/plugin dispatch share it; the dispatch wraps it per-request into a RequestContext (actor + locale).
+let coreContext: CoreContext | null = null;
+
+export function getCoreContext(): CoreContext {
+  if (!coreContext) {
+    const db = getCoreDb();
+    // Asset storage (ADR-0002): the local/Railway-disk provider by default. This is the seam to swap in an
+    // S3/R2 adapter later — set SAENA_ASSETS_DIR to a mounted volume in production.
+    const storage = createStorageService({
+      db,
+      provider: createLocalDiskProvider({ dir: process.env.SAENA_ASSETS_DIR ?? '.data/assets' }),
+    });
+    coreContext = createCoreContext({ db, storage });
+  }
+  return coreContext;
+}

package/template/base/src/server/plugin-host.ts

@@ -0,0 +1,21 @@
+import { serverPlugins } from '@/plugins';
+import { type PluginHost, createPluginHost } from '@saena-io/core';
+import { getCoreContext } from './core';
+
+// Server-only: the plugin host as a once-per-process singleton (mirrors getCoreDb). Runtime only — it wires
+// event subscriptions (host.start) and exposes the ordered plugins so the /api/plugin dispatch can resolve a
+// plugin's server functions (ADR-0006). The MUTATING lifecycle (migrateCore → runPluginMigrations →
+// host.install) runs at deploy time via scripts/migrate.ts, never here in a request path.
+let host: PluginHost | null = null;
+
+export function getPluginHost(): PluginHost {
+  if (!host) {
+    // Build the host on the SHARED system context (getCoreContext) — NOT a fresh one — so the capabilities the
+    // host registers from each plugin's `provides` (ADR-0010) live on the same registry the /api/plugin
+    // dispatch reads through its per-request RequestContext. A separate context would leave that registry empty
+    // and every `ctx.capabilities.require(...)` would throw.
+    host = createPluginHost(serverPlugins, getCoreContext());
+    host.start();
+  }
+  return host;
+}

package/template/base/src/server/require-ctx.ts

@@ -0,0 +1,25 @@
+import { createRequestContext } from '@saena-io/core';
+import type { RequestContext } from '@saena-io/plugin-sdk';
+import { getRequest } from '@tanstack/react-start/server';
+import { resolveRequestActor } from './auth';
+import { getCoreContext, getCoreDb } from './core';
+
+// The authorization seam for admin server functions (ADR-0012). Builds a per-request RequestContext (resolved
+// actor + locale) from the current request's headers — the same factory the /api/plugin dispatch + asset routes
+// use. Each protected server fn does `const ctx = await requireCtx(); ctx.requirePermission('…')`; a missing
+// permission throws PermissionDeniedError, which createServerFn surfaces to the client as an error (the admin's
+// client-side gate is UX only — this is the real boundary, §10). Replaces the old session-only requireStaff.
+export async function requireCtx(): Promise<RequestContext> {
+  return createRequestContext({
+    core: getCoreContext(),
+    db: getCoreDb(),
+    resolveActor: resolveRequestActor,
+    headers: getRequest().headers,
+  });
+}
+
+/** The signed-in staff member's id after a `staff.manage` check — for the team service's RBAC invariants. */
+export function staffActorId(ctx: RequestContext): string {
+  if (ctx.actor.kind !== 'staff') throw new Error('staff actor required');
+  return ctx.actor.userId;
+}

package/template/base/src/server/team.ts

@@ -0,0 +1,58 @@
+import {
+  createStaffMember,
+  deleteStaffMember,
+  listRoles,
+  listStaff,
+  setStaffRole,
+} from '@saena-io/core';
+import { idRefSchema, staffCreateSchema, staffRoleUpdateSchema } from '@saena-io/plugin-sdk';
+import { createServerFn } from '@tanstack/react-start';
+import { getStaffAuth } from './auth';
+import { getCoreDb } from './core';
+import { requireCtx, staffActorId } from './require-ctx';
+
+// Team / RBAC server functions (§10). All gate on `staff.manage` (Owner+) via requirePermission — the real
+// boundary (ADR-0012); the admin's client-side gate is UX only. Mutations thread the signed-in staff id so the
+// team service can enforce its invariants (no privilege escalation, last-Admin protection, no self-removal). The
+// predefined roles + the bootstrap Admin are seeded at deploy time by `ensureRoles` (migrate); roles are NOT
+// editable here (no custom-role builder, ADR-0012 phase 3) — `listRolesFn` is read-only, for assignment.
+
+/** List staff members. */
+export const listStaffFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('staff.manage');
+  return listStaff(getCoreDb());
+});
+
+/** Create a staff member with an admin-set initial password. */
+export const createStaffFn = createServerFn({ method: 'POST' })
+  .validator(staffCreateSchema)
+  .handler(async ({ data }) => {
+    const ctx = await requireCtx();
+    ctx.requirePermission('staff.manage');
+    return createStaffMember(getCoreDb(), getStaffAuth(), data, staffActorId(ctx));
+  });
+
+/** Reassign (or clear) a staff member's role. */
+export const updateStaffRoleFn = createServerFn({ method: 'POST' })
+  .validator(staffRoleUpdateSchema)
+  .handler(async ({ data }) => {
+    const ctx = await requireCtx();
+    ctx.requirePermission('staff.manage');
+    await setStaffRole(getCoreDb(), data.id, data.roleId, staffActorId(ctx));
+    return data;
+  });
+
+/** Remove a staff member. */
+export const deleteStaffFn = createServerFn({ method: 'POST' })
+  .validator(idRefSchema)
+  .handler(async ({ data }) => {
+    const ctx = await requireCtx();
+    ctx.requirePermission('staff.manage');
+    await deleteStaffMember(getCoreDb(), data.id, staffActorId(ctx));
+  });
+
+/** List the predefined roles (read-only) — the assignable set for the member role selector. */
+export const listRolesFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('staff.manage');
+  return listRoles(getCoreDb());
+});

package/template/base/src/server/translations.ts

@@ -0,0 +1,74 @@
+import {
+  addLocale,
+  listLocales,
+  listTranslations,
+  removeLocale,
+  setMainLocale,
+  setReviewed,
+  setTranslation,
+} from '@saena-io/core';
+import {
+  localeInputSchema,
+  mainLocaleInputSchema,
+  translationReviewInputSchema,
+  translationValueInputSchema,
+} from '@saena-io/plugin-sdk';
+import { createServerFn } from '@tanstack/react-start';
+import { getCoreDb } from './core';
+import { requireCtx } from './require-ctx';
+
+// Host server functions for the i18n foundation (§9, ADR-0005). They reach core (where the db lives)
+// and are injected into the shell as TanStack DB collections (see ../admin/data.ts), so @saena-io/admin
+// never imports core. Auth is enforced server-side via requirePermission('translations.manage') (ADR-0012).
+
+/** Every translatable value, grid-shaped (key × locale + status). Loaded whole; filtered client-side. */
+export const listTranslationsFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('translations.manage');
+  return listTranslations(getCoreDb());
+});
+
+/** The project's configured locales (exactly one is main). */
+export const listLocalesFn = createServerFn({ method: 'GET' }).handler(async () => {
+  (await requireCtx()).requirePermission('translations.manage');
+  return listLocales(getCoreDb());
+});
+
+/** Set a locale's value for a key — editing the main locale re-stales the other locales. */
+export const setTranslationFn = createServerFn({ method: 'POST' })
+  .validator(translationValueInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('translations.manage');
+    await setTranslation(getCoreDb(), data);
+  });
+
+/** Lock/unlock a value's reviewed ("checked") state. */
+export const setReviewedFn = createServerFn({ method: 'POST' })
+  .validator(translationReviewInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('translations.manage');
+    await setReviewed(getCoreDb(), data);
+  });
+
+/** Swap the main (source) locale — re-anchors staleness across every key. */
+export const setMainLocaleFn = createServerFn({ method: 'POST' })
+  .validator(mainLocaleInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('translations.manage');
+    await setMainLocale(getCoreDb(), data.code);
+  });
+
+/** Add a project locale (a new target language). */
+export const addLocaleFn = createServerFn({ method: 'POST' })
+  .validator(localeInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('translations.manage');
+    await addLocale(getCoreDb(), data);
+  });
+
+/** Remove a locale and all its translations (refuses the main locale). */
+export const removeLocaleFn = createServerFn({ method: 'POST' })
+  .validator(mainLocaleInputSchema)
+  .handler(async ({ data }) => {
+    (await requireCtx()).requirePermission('translations.manage');
+    await removeLocale(getCoreDb(), data.code);
+  });

package/template/base/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"],
+    "allowImportingTsExtensions": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/base/vite.config.ts

@@ -0,0 +1,25 @@
+import tailwindcss from '@tailwindcss/vite';
+import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+import viteReact from '@vitejs/plugin-react';
+import { defineConfig, loadEnv } from 'vite';
+
+export default defineConfig(({ mode }) => {
+  // Load this project's .env into process.env so the SSR server (the auth handler + db) sees
+  // DATABASE_URL / BETTER_AUTH_SECRET. Server-only — only VITE_-prefixed vars reach the client
+  // (via import.meta.env), and real env vars take precedence over the file.
+  for (const [key, value] of Object.entries(loadEnv(mode, process.cwd(), ''))) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+  const port = Number(process.env.PORT) || 3000;
+  return {
+    server: { port, host: true },
+    // Production server (`bun run start` → `vite preview`) binds the platform's PORT (e.g. Railway) on
+    // 0.0.0.0 so the deploy is reachable.
+    preview: { port, host: true },
+    resolve: { tsconfigPaths: true },
+    // The @saena-io/* packages ship TypeScript source (consumed via Vite). Bundle them for SSR so Vite
+    // transpiles them instead of treating them as pre-built external CommonJS.
+    ssr: { noExternal: [/@saena-io\//] },
+    plugins: [tailwindcss(), tanstackStart(), viteReact()],
+  };
+});