@starci/hfs 4.0.7 → 4.0.9

package/templates/fe/skeleton-lite/apps/web/src/modules/db/server.ts

@@ -0,0 +1,70 @@
+import "server-only"
+
+import { createServerClient } from "@supabase/ssr"
+import type { SupabaseClient } from "@supabase/supabase-js"
+import { cookies } from "next/headers"
+import type { NextRequest, NextResponse } from "next/server"
+import type { Database } from "../../../../../../supabase/types/database.types"
+import { sessionCookieOptions, supabaseAnonKey, supabaseUrl } from "@/modules/config"
+import { toOutcome } from "./outcome"
+import type { DbOutcome, SupabaseData, SupabaseResult } from "./outcome"
+
+interface OwnedRowIdentity {
+    readonly id: string
+    readonly owner_id: string
+}
+
+type InsertOwnedRow<T extends SupabaseResult> = (
+    client: SupabaseClient<Database>,
+    row: OwnedRowIdentity,
+) => PromiseLike<T>
+
+/** Creates the cookie-backed server client; the public key keeps every database call under RLS. */
+export const createServerDbClient = async (): Promise<SupabaseClient<Database>> => {
+    const store = await cookies()
+    return createServerClient<Database>(supabaseUrl(), supabaseAnonKey(), {
+        cookies: {
+            getAll: () => store.getAll(),
+            setAll: (changes) => {
+                try {
+                    for (const change of changes) {
+                        store.set(change.name, change.value, {
+                            ...change.options,
+                            ...sessionCookieOptions,
+                        })
+                    }
+                } catch (cause) {
+                    if (!(cause instanceof Error) || !cause.message.includes("Cookies can only be modified"))
+                        throw cause
+                }
+            },
+        },
+    })
+}
+
+/** Inserts one validated principal-owned row through the typed server client. */
+export const insertRow = async <T extends SupabaseResult>(
+    id: string,
+    ownerId: string,
+    insert: InsertOwnedRow<T>,
+): Promise<DbOutcome<SupabaseData<T>>> => {
+    const client = await createServerDbClient()
+    return toOutcome(await insert(client, { id, owner_id: ownerId }))
+}
+
+/** Creates the proxy client and writes every refreshed cookie onto the response that will be returned. */
+export const createRequestDbClient = (request: NextRequest, response: NextResponse): SupabaseClient<Database> =>
+    createServerClient<Database>(supabaseUrl(), supabaseAnonKey(), {
+        cookies: {
+            getAll: () => request.cookies.getAll(),
+            setAll: (changes) => {
+                for (const change of changes) {
+                    request.cookies.set(change.name, change.value)
+                    response.cookies.set(change.name, change.value, {
+                        ...change.options,
+                        ...sessionCookieOptions,
+                    })
+                }
+            },
+        },
+    })

package/templates/fe/skeleton-lite/apps/web/src/modules/db/validation/validation.mapper.ts

@@ -0,0 +1,50 @@
+interface OwnedRowInput {
+    readonly id: string
+}
+
+type OwnedRowParse = { readonly success: true; readonly data: OwnedRowInput } | { readonly success: false }
+
+interface SignInInput {
+    readonly email: string
+    readonly password: string
+}
+
+type SignInParse = { readonly success: true; readonly data: SignInInput } | { readonly success: false }
+
+const UUID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/u
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u
+
+/** The bounded UUID schema shared by generated table Server Actions. */
+export const rowSchema = {
+    safeParse: (input: unknown): OwnedRowParse => {
+        if (
+            typeof input !== "object" ||
+            input === null ||
+            !("id" in input) ||
+            typeof input.id !== "string" ||
+            !UUID.test(input.id)
+        ) {
+            return { success: false }
+        }
+        return { success: true, data: { id: input.id } }
+    },
+}
+
+/** Bounds credentials before a sign-in request reaches Supabase Auth. */
+export const signInInputSchema = {
+    safeParse: (input: FormData): SignInParse => {
+        const email = input.get("email")
+        const password = input.get("password")
+        if (
+            typeof email !== "string" ||
+            email.length > 254 ||
+            !EMAIL.test(email) ||
+            typeof password !== "string" ||
+            password.length < 8 ||
+            password.length > 256
+        ) {
+            return { success: false }
+        }
+        return { success: true, data: { email, password } }
+    },
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/i18n/index.ts

@@ -0,0 +1,8 @@
+import { createNavigation } from "next-intl/navigation"
+import { routing } from "./routing"
+
+/** The locale served at the unprefixed path and used by the global error boundary. */
+export { DEFAULT_LOCALE, PRODUCT_TIME_ZONE, routing } from "./routing"
+
+/** Locale-aware navigation for client components. */
+export const navigation = createNavigation(routing)

package/templates/fe/skeleton-lite/apps/web/src/modules/i18n/messages/vi.json

@@ -0,0 +1,48 @@
+{
+  "app": {
+    "title": "{{project}}",
+    "shell": {
+      "brand": "{{project}}"
+    },
+    "home": {
+      "title": "Home",
+      "signedIn": "Signed in"
+    },
+    "signIn": {
+      "title": "Sign in",
+      "email": "Email",
+      "password": "Password",
+      "submit": "Continue",
+      "working": "Signing in",
+      "refused": "The credentials were refused.",
+      "not-found": "The credentials were refused.",
+      "invalid": "Enter a valid email and password.",
+      "unavailable": "Sign-in is unavailable. Try again shortly."
+    },
+    "signOut": {
+      "submit": "Sign out",
+      "working": "Signing out",
+      "refused": "The session has already ended.",
+      "not-found": "The session has already ended.",
+      "invalid": "The session could not be ended.",
+      "unavailable": "Sign-out is unavailable. Try again shortly."
+    },
+    "loading": {
+      "message": "Loading"
+    },
+    "notFound": {
+      "title": "Page not found",
+      "home": "Return home"
+    },
+    "errors": {
+      "page": {
+        "title": "Something went wrong",
+        "retry": "Try again"
+      },
+      "global": {
+        "title": "The application could not continue",
+        "retry": "Try again"
+      }
+    }
+  }
+}

package/templates/fe/{skeleton/apps/__app__ → skeleton-lite/apps/web}/src/modules/i18n/request.ts

@@ -1,14 +1,16 @@
 import "server-only"
 import { hasLocale } from "next-intl"
 import { getRequestConfig } from "next-intl/server"
-import { routing } from "./routing"
+import { PRODUCT_TIME_ZONE, routing } from "./routing"
 
-/** Resolves the locale of a request and loads its catalog; an unknown locale falls back to the default. */
+/** The request config next-intl's plugin loads. */
 export default getRequestConfig(async ({ requestLocale }) => {
     const requested = await requestLocale
     const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale
     return {
         locale,
+        timeZone: PRODUCT_TIME_ZONE,
         messages: (await import(`./messages/${locale}.json`)).default,
+        getMessageFallback: ({ namespace, key }) => `web:${namespace ?? ""}.${key}`,
     }
 })

package/templates/fe/skeleton-lite/apps/web/src/modules/i18n/routing.ts

@@ -0,0 +1,14 @@
+const LOCALES = ["vi"] as const
+
+/** The locale served at the unprefixed path. */
+export const DEFAULT_LOCALE = "vi" as const
+
+/** The fixed product time zone used by the server and hydrated client. */
+export const PRODUCT_TIME_ZONE = "Asia/Ho_Chi_Minh"
+
+/** The one locale-routing table of the web app. */
+export const routing = {
+    locales: LOCALES,
+    defaultLocale: DEFAULT_LOCALE,
+    localePrefix: "as-needed" as const,
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/routes/index.ts

@@ -0,0 +1,7 @@
+/** Every internal destination the web app links to, named once. */
+export const APP_ROUTES = {
+    home: "/",
+    authCallback: "/auth/callback",
+} as const
+
+export { safeNextPath } from "./safe-next-path"

package/templates/fe/skeleton-lite/apps/web/src/modules/routes/safe-next-path.ts

@@ -0,0 +1,26 @@
+const INVALID_PATH_CHARACTER = /[\\\u0000-\u001F\u007F]/u
+
+const isSingleSlashPath = (value: string): boolean => value.startsWith("/") && !value.startsWith("//")
+
+/** Normalizes a same-origin callback destination or falls back to the app root. */
+export const safeNextPath = (candidate: string | null, origin: string): string => {
+    if (candidate === null) return "/"
+    let destination: URL
+    let decoded: string
+    try {
+        destination = new URL(candidate, origin)
+        decoded = decodeURIComponent(candidate)
+    } catch {
+        return "/"
+    }
+    if (
+        destination.origin !== origin ||
+        !isSingleSlashPath(candidate) ||
+        !isSingleSlashPath(decoded) ||
+        INVALID_PATH_CHARACTER.test(candidate) ||
+        INVALID_PATH_CHARACTER.test(decoded)
+    ) {
+        return "/"
+    }
+    return `${destination.pathname}${destination.search}${destination.hash}`
+}

package/templates/fe/skeleton-lite/apps/web/src/proxy.ts

@@ -0,0 +1,43 @@
+import createMiddleware from "next-intl/middleware"
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+import { sessionCookieOptions } from "@/modules/config"
+import { refreshSession } from "@/modules/db"
+import { routing } from "@/modules/i18n"
+import { APP_ROUTES } from "@/modules/routes"
+
+const UNNEGOTIATED_ROOTS: ReadonlySet<string> = new Set(["auth", "health", "_next", "_vercel"])
+const negotiate = createMiddleware(routing)
+
+const firstSegment = (pathname: string): string => pathname.split("/")[1] ?? ""
+
+const isUnnegotiated = (pathname: string): boolean => {
+    const last = pathname.split("/").at(-1) ?? ""
+    return UNNEGOTIATED_ROOTS.has(firstSegment(pathname)) || (last.includes(".") && !last.endsWith("."))
+}
+
+const isPublic = (pathname: string): boolean =>
+    pathname === "/" || pathname === `/${routing.defaultLocale}` || isUnnegotiated(pathname)
+
+/** Refreshes the Supabase session, gates private paths with verified claims, then returns locale routing. */
+export const proxy = async (request: NextRequest): Promise<NextResponse> => {
+    const response = isUnnegotiated(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request)
+    const principal = await refreshSession(request, response)
+    if (principal.kind === "ok" || isPublic(request.nextUrl.pathname)) return response
+    const destination = request.nextUrl.clone()
+    destination.pathname = APP_ROUTES.home
+    destination.searchParams.set("next", request.nextUrl.pathname)
+    const redirect = NextResponse.redirect(destination)
+    for (const cookie of response.cookies.getAll()) {
+        redirect.cookies.set(cookie.name, cookie.value, {
+            ...cookie,
+            ...sessionCookieOptions,
+        })
+    }
+    return redirect
+}
+
+/** Routes that pass through session refresh and locale negotiation. */
+export const config = {
+    matcher: "/((?!_next/static|_next/image|favicon.ico).*)",
+}

package/templates/fe/table/read.ts.tpl

@@ -0,0 +1,16 @@
+import "server-only"
+
+import { cache } from "react"
+import type { Database } from "../../../../../../../supabase/types/database.types"
+import { createServerDbClient } from "../server"
+import { toOutcome } from "../outcome"
+import type { DbOutcome } from "../outcome"
+
+/** One {{table}} row from the generated database contract. */
+type {{Name}}Row = Database["public"]["Tables"]["{{table}}"]["Row"]
+
+/** Reads a bounded page of {{table}} rows visible to the current RLS principal. */
+export const read{{Name}} = cache(async (): Promise<DbOutcome<ReadonlyArray<{{Name}}Row>>> => {
+    const client = await createServerDbClient()
+    return toOutcome(await client.from("{{table}}").select("*").limit(100))
+})

package/templates/fe/table/write.ts.tpl

@@ -0,0 +1,16 @@
+"use server"
+import "server-only"
+
+import { getPrincipal } from "../principal"
+import { dbFailure } from "../outcome"
+import { insertRow } from "../server"
+import { rowSchema } from "../validation/validation.mapper"
+
+/** Writes one validated {{table}} row for the current principal. */
+export const write{{Name}} = async (input: unknown) => {
+    const principal = await getPrincipal()
+    if (principal.kind !== "ok") return dbFailure("refused", "principal")
+    const parsed = rowSchema.safeParse(input)
+    if (!parsed.success) return dbFailure("invalid", "{{table}}-input")
+    return insertRow(parsed.data.id, principal.value.id, (db, row) => db.from("{{table}}").insert(row).select().single())
+}

package/upgrade/check.mjs

@@ -0,0 +1,137 @@
+// The `starci app check --edition full` view of a lite app. The app stays byte-for-byte untouched: its declaration is cloned without
+// `edition`, then passed to the existing slot resolver, rule filter and architecture engine as an injected declaration.
+import fs from "node:fs";
+import path from "node:path";
+import { checkArchitecture } from "../runtime/scripts/hfs/architecture/index.mjs";
+import {
+  checkDatabase,
+  checkRepo,
+  trackedFiles,
+} from "../runtime/scripts/hfs/check.mjs";
+import { loadSlotManifest, openHfs } from "../runtime/scripts/hfs/slots.mjs";
+import { formatFindings } from "../sync/format.mjs";
+import {
+  checkTargets,
+  loadHfs,
+  renderTargets,
+} from "../sync/index.mjs";
+import {
+  UPGRADE_PRESETS,
+  UpgradeError,
+  fullEditionDeclaration,
+} from "./index.mjs";
+
+const ONE_LINER = new Set(["eslint.config.mjs", "stylelint.config.mjs"]);
+
+function fullManagedFindings(repoRoot, targets) {
+  const findings = [];
+  for (const result of checkTargets(repoRoot, targets)) {
+    if (
+      result.status === "ok" ||
+      !fs.existsSync(path.join(repoRoot, ...result.path.split("/")))
+    )
+      continue;
+    const target = targets.find((candidate) => candidate.path === result.path);
+    const code =
+      target.mode === "block"
+        ? "HFS_GITIGNORE_BLOCK_DRIFT"
+        : ONE_LINER.has(path.posix.basename(result.path))
+          ? "HFS_RULE_OFF_WITHOUT_REPLACEMENT"
+          : result.path === "sonar-project.properties"
+            ? "HFS_SONAR_CONFIG"
+            : "HFS_MANAGED_FILE_DRIFT";
+    findings.push({
+      code,
+      level: "error",
+      path: result.path,
+      message: `${result.path} is not its full-edition render (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ""}); run starci app upgrade --edition full`,
+    });
+  }
+  return findings;
+}
+
+const machineFinding = (side, item) => ({
+  code: item.ruleId,
+  level: "error",
+  ...(item.path ? { path: `${side}/${item.path}` } : {}),
+  ...(item.line ? { line: item.line, column: item.column } : {}),
+  source: "machine",
+  message: `${item.path ? `${side}/${item.path}${item.line ? `:${item.line}` : ""}: ` : ""}${item.message}`,
+});
+
+/**
+ * Runs the normal check when the requested edition matches hfs.json. The sole override is lite -> full; every other mismatch is
+ * a usage refusal. `normal` is the CLI's ordinary check closure, which keeps the existing full and lite paths unchanged.
+ */
+export async function checkEdition({
+  repoRoot,
+  edition,
+  normal,
+  presets,
+  prettier,
+  manifest = loadSlotManifest(),
+}) {
+  if (edition === undefined) return normal();
+  if (!["full", "lite"].includes(edition))
+    throw new UpgradeError(
+      "HFS_EDITION_INVALID",
+      `--edition is ${JSON.stringify(edition)}; expected full or lite`,
+    );
+  const declaration = loadHfs(repoRoot, manifest);
+  const actual = declaration.edition ?? "full";
+  if (edition === actual) return normal();
+  if (!(actual === "lite" && edition === "full"))
+    throw new UpgradeError(
+      "HFS_EDITION_INVALID",
+      `hfs.json edition is ${actual}; check may override only an edition lite app to full`,
+    );
+
+  const full = fullEditionDeclaration(declaration, manifest);
+  const tracked = trackedFiles(repoRoot);
+  // A lite app cannot have the full-only Jest preset installed yet. The upgrade model carries the preset's public sync inputs
+  // specifically so both the dry full-edition view and the upgrade plan render the same targets before dependencies are added.
+  const resolvedPresets = presets ?? UPGRADE_PRESETS;
+  const managed = renderTargets(full, resolvedPresets, { manifest });
+  const extra = [
+    ...fullManagedFindings(repoRoot, managed),
+    ...(await checkDatabase({ repoRoot, files: tracked })),
+    ...(await formatFindings({ repoRoot, files: tracked, prettier })),
+  ];
+  const runs = [];
+  for (const side of ["be", "fe"]) {
+    const report = checkArchitecture({
+      repositoryRoot: path.join(repoRoot, side),
+      hfs: openHfs({ manifest, declaration: full, side }),
+      surface: "check",
+    });
+    runs.push({
+      side,
+      status: "ran",
+      files: report.files,
+      kinds: report.kinds,
+    });
+    extra.push(
+      ...report.errors.map((item) => machineFinding(side, item)),
+      ...report.violations.map((item) => machineFinding(side, item)),
+    );
+  }
+  const result = checkRepo({
+    repoRoot,
+    declaration: full,
+    files: tracked,
+    extraFindings: extra,
+    manifest,
+    surface: "check",
+    tree: true,
+  });
+  return {
+    ...result,
+    machine: {
+      status: "ran",
+      files: runs.reduce((sum, run) => sum + run.files, 0),
+      kinds: [...new Set(runs.flatMap((run) => run.kinds))],
+      sides: runs,
+    },
+    editionOverride: { declared: actual, judged: edition },
+  };
+}