@starci/hfs 4.2.17 → 4.4.0

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignOut.ts

@@ -1,16 +1,15 @@
 "use client"
 
 import { useTransition } from "react"
-import type { GraphQLResponse } from "@/modules/api"
 import { authClient } from "@/modules/auth"
 import type { AuthFailure } from "@/modules/auth"
 import { useGraphQLWithToast } from "@/modules/toast"
 
 /** The app's one outcome of an auth call, so modules/toast reports it like any other write. */
-const responseOf = (failure: AuthFailure | undefined): GraphQLResponse<null> =>
+const responseOf = (failure: AuthFailure | undefined) =>
     failure === undefined
-        ? { success: true, data: null }
-        : { success: false, error: failure.code, kind: failure.kind, message: failure.message }
+        ? { success: true as const, data: null }
+        : { success: false as const, error: failure.code, kind: failure.kind, message: failure.message }
 
 /**
  * Ends the reader's session through modules/auth: whether the request runs and the sign-out itself. A failure is reported by

package/templates/fe/skeleton/apps/__app__/src/hooks/zustand/appGuide/index.ts

@@ -0,0 +1 @@
+export { useAppGuideStore } from "./store"

package/templates/fe/skeleton/apps/__app__/src/hooks/zustand/appGuide/store.ts

@@ -0,0 +1,15 @@
+"use client"
+
+import { create } from "zustand"
+
+/** The home guide's local UI state; it carries no session or server data. */
+type AppGuideState = {
+    readonly isOpen: boolean
+    readonly setOpen: (isOpen: boolean) => void
+}
+
+/** One feature-local store, shared by the guide trigger and its controlled dialog. */
+export const useAppGuideStore = create<AppGuideState>()((set) => ({
+    isOpen: false,
+    setOpen: (isOpen) => set({ isOpen }),
+}))

package/templates/fe/skeleton/apps/__app__/src/modules/auth/pkce-client.ts

@@ -0,0 +1,18 @@
+import { createBrowserClient } from "@supabase/ssr"
+import type { Session, SupabaseClient } from "@supabase/supabase-js"
+import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+import type { AuthClient, AuthFailure, AuthSession } from "./contracts"
+
+let client: SupabaseClient | undefined
+
+/**
+ * The cookie-backed browser client of the opt-in server PKCE flow, used for Supabase Auth only.
+ * The callback exchanges the code; this client shares its verifier and session cookies. It never calls `.from()`, `.rpc()` or storage:
+ * data goes through modules/api to the back end, which verifies the access token.
+ */
+const supabase = (): SupabaseClient =>
+    (client ??= createBrowserClient(supabaseUrl(), supabaseAnonKey(), {
+        auth: { flowType: "pkce", detectSessionInUrl: false, persistSession: true, autoRefreshToken: true },
+    }))
+
+// {{> fe/auth/supabase-client.ts.tpl}}

package/templates/fe/skeleton/apps/__app__/src/modules/auth/server.ts

@@ -0,0 +1,19 @@
+import "server-only"
+import { createServerClient } from "@supabase/ssr"
+import { cookies } from "next/headers"
+import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+
+/** The server auth owner reads the PKCE verifier and persists the exchanged session in cookies. */
+export async function exchangeAuthCode(code: string): Promise<void> {
+    const cookieStore = await cookies()
+    const client = createServerClient(supabaseUrl(), supabaseAnonKey(), {
+        cookies: {
+            getAll: () => cookieStore.getAll(),
+            setAll: (values) => {
+                for (const { name, value, options } of values) cookieStore.set(name, value, options)
+            },
+        },
+    })
+    const { error } = await client.auth.exchangeCodeForSession(code)
+    if (error) throw error
+}

package/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/index.tsx

@@ -1,5 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
+import { AppGuideOverlay } from "@/features/overlays/AppGuideOverlay"
 import { AppHomePageBase } from "./component"
 
 /** The document title of the home page, from the catalog of the requested locale. */
@@ -11,5 +12,10 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
 /** The first page of the product app: a server component; the session surface it draws runs on the client. */
 export const AppHomePage = async () => {
     const t = await getTranslations("app.home")
-    return <AppHomePageBase props={{ title: t("title") }} />
+    return (
+        <>
+            <AppHomePageBase props={{ title: t("title") }} />
+            <AppGuideOverlay />
+        </>
+    )
 }

package/templates/fe/skeleton/apps/app/src/modules/i18n/messages/en.json

@@ -0,0 +1,57 @@
+{
+  "app": {
+    "title": "{{project}}",
+    "shell": {
+      "brand": "{{project}}"
+    },
+    "home": {
+      "title": "Home"
+    },
+    "signIn": {
+      "title": "Sign in",
+      "email": "Email",
+      "password": "Password",
+      "submit": "Continue",
+      "working": "Signing in",
+      "refused": "The credentials were refused.",
+      "invalid": "Enter a valid email and password.",
+      "unavailable": "Sign-in is unavailable. Try again shortly."
+    },
+    "signOut": {
+      "signedIn": "Signed in",
+      "submit": "Sign out",
+      "working": "Signing out"
+    },
+    "toast": {
+      "successTitle": "Done",
+      "errorTitle": "Error",
+      "unauthorizedTitle": "Not signed in",
+      "unauthorizedDescription": "Sign in to continue.",
+      "defaultSuccess": "The change was saved.",
+      "defaultError": "Something went wrong."
+    },
+    "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"
+      }
+    },
+    "guide": {
+      "open": "View guide",
+      "title": "Getting started",
+      "description": "Sign in to use the application. You can close this guide and open it again at any time.",
+      "close": "Close"
+    }
+  }
+}

package/templates/fe/skeleton/apps/app/src/modules/i18n/messages/vi.json

@@ -46,6 +46,12 @@
         "title": "Đã xảy ra lỗi nghiêm trọng",
         "retry": "Thử lại"
       }
+    },
+    "guide": {
+      "open": "Xem hướng dẫn",
+      "title": "Bắt đầu",
+      "description": "Đăng nhập để sử dụng ứng dụng. Bạn có thể đóng hướng dẫn này và mở lại bất cứ lúc nào.",
+      "close": "Đóng"
     }
   }
 }

package/templates/fe/skeleton/apps/landing/src/modules/i18n/messages/en.json

@@ -0,0 +1,31 @@
+{
+  "landing": {
+    "title": "{{project}}",
+    "description": "The introduction to {{project}}.",
+    "shell": {
+      "brand": "{{project}}"
+    },
+    "home": {
+      "title": "Welcome to {{project}}",
+      "lede": "Everything you need is in the application.",
+      "openApp": "Open the application"
+    },
+    "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/packages/__project__-i18n/src/routing.ts

@@ -1,7 +1,7 @@
 import { defineRouting } from "next-intl/routing"
 
 /** The locales every app of the product serves; every catalog of an app has the same keys in each. */
-const LOCALES = ["vi"] as const
+const LOCALES = ["vi", "en"] as const
 
 /** The locale served at the unprefixed path, and the language of a document no locale reached (the global error boundary). */
 export const DEFAULT_LOCALE = "vi"

package/templates/fe/skeleton/packages/__project__-ui/src/index.ts

@@ -4,3 +4,4 @@ export { LoadingNotice } from "./composites/LoadingNotice"
 export { LocaleShell } from "./composites/LocaleShell"
 export { NotFoundNotice } from "./composites/NotFoundNotice"
 export { SiteShell } from "./composites/SiteShell"
+export { Icon } from "./leaves/Icon"

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/client.ts

@@ -15,37 +15,4 @@ const supabase = (): SupabaseClient =>
         auth: { flowType: "pkce", detectSessionInUrl: true, persistSession: true, autoRefreshToken: true },
     }))
 
-const sessionOf = (session: Session | null): AuthSession | undefined =>
-    session === null
-        ? undefined
-        : { userId: session.user.id, ...(session.user.email === undefined ? {} : { email: session.user.email }) }
-
-/** A Supabase Auth error as the provider reports it: its HTTP status, its code and its message. */
-type ProviderError = { readonly status?: number; readonly code?: string; readonly message: string }
-
-/** The failure kind of a Supabase Auth error: refused credentials, rejected input, or the provider unavailable. */
-const kindOf = (status: number | undefined): string => {
-    if (status === 400 || status === 401 || status === 403) return "refused"
-    return status === 422 ? "invalid" : "unavailable"
-}
-
-/** The failure of a Supabase Auth call, or undefined when it succeeded. */
-const failureOf = (error: ProviderError | null): AuthFailure | undefined =>
-    error === null
-        ? undefined
-        : { code: error.code ?? String(error.status ?? "auth"), kind: kindOf(error.status), message: error.message }
-
-/** The identity-provider client of a lite app: Supabase Auth in the browser. */
-export const authClient: AuthClient = {
-    session: async () => sessionOf((await supabase().auth.getSession()).data.session),
-    accessToken: async () => (await supabase().auth.getSession()).data.session?.access_token,
-    refreshAccessToken: async () => (await supabase().auth.refreshSession()).data.session?.access_token,
-    signInWithPassword: async (email, password) =>
-        failureOf((await supabase().auth.signInWithPassword({ email, password })).error),
-    signOut: async () => failureOf((await supabase().auth.signOut()).error),
-    // Supabase reports INITIAL_SESSION on subscribe, then every change: the subscription alone keeps the session current.
-    onChange: (listener) => {
-        const { data } = supabase().auth.onAuthStateChange((_event, session) => listener(sessionOf(session)))
-        return () => data.subscription.unsubscribe()
-    },
-}
+// {{> fe/auth/supabase-client.ts.tpl}}

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/index.tsx

@@ -1,5 +1,6 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
+import { AppGuideOverlay } from "@/features/overlays/AppGuideOverlay"
 import { AppHomePageBase } from "./component"
 
 /** The document title of the home page. */
@@ -11,5 +12,10 @@ export const appHomeMetadata = async (): Promise<Metadata> => {
 /** The front door (the session is client-side, drawn by the blocks the page composes). */
 export const AppHomePage = async () => {
     const t = await getTranslations("app.home")
-    return <AppHomePageBase props={{ title: t("title") }} />
+    return (
+        <>
+            <AppHomePageBase props={{ title: t("title") }} />
+            <AppGuideOverlay />
+        </>
+    )
 }

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

@@ -0,0 +1,57 @@
+{
+  "app": {
+    "title": "{{project}}",
+    "shell": {
+      "brand": "{{project}}"
+    },
+    "home": {
+      "title": "Home"
+    },
+    "signIn": {
+      "title": "Sign in",
+      "email": "Email",
+      "password": "Password",
+      "submit": "Continue",
+      "working": "Signing in",
+      "refused": "The credentials were refused.",
+      "invalid": "Enter a valid email and password.",
+      "unavailable": "Sign-in is unavailable. Try again shortly."
+    },
+    "signOut": {
+      "signedIn": "Signed in",
+      "submit": "Sign out",
+      "working": "Signing out"
+    },
+    "toast": {
+      "successTitle": "Done",
+      "errorTitle": "Error",
+      "unauthorizedTitle": "Not signed in",
+      "unauthorizedDescription": "Sign in to continue.",
+      "defaultSuccess": "The change was saved.",
+      "defaultError": "Something went wrong."
+    },
+    "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"
+      }
+    },
+    "guide": {
+      "open": "View guide",
+      "title": "Getting started",
+      "description": "Sign in to use the application. You can close this guide and open it again at any time.",
+      "close": "Close"
+    }
+  }
+}

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

@@ -5,47 +5,53 @@
       "brand": "{{project}}"
     },
     "home": {
-      "title": "Home"
+      "title": "Trang chủ"
     },
     "signIn": {
-      "title": "Sign in",
+      "title": "Đăng nhập",
       "email": "Email",
-      "password": "Password",
-      "submit": "Continue",
-      "working": "Signing in",
-      "refused": "The credentials were refused.",
-      "invalid": "Enter a valid email and password.",
-      "unavailable": "Sign-in is unavailable. Try again shortly."
+      "password": "Mật khẩu",
+      "submit": "Tiếp tục",
+      "working": "Đang đăng nhập",
+      "refused": "Thông tin đăng nhập không đúng.",
+      "invalid": "Hãy nhập email và mật khẩu hợp lệ.",
+      "unavailable": "Chưa thể đăng nhập. Hãy thử lại sau."
     },
     "signOut": {
-      "signedIn": "Signed in",
-      "submit": "Sign out",
-      "working": "Signing out"
+      "signedIn": "Đã đăng nhập",
+      "submit": "Đăng xuất",
+      "working": "Đang đăng xuất"
     },
     "toast": {
-      "successTitle": "Done",
-      "errorTitle": "Error",
-      "unauthorizedTitle": "Not signed in",
-      "unauthorizedDescription": "Sign in to continue.",
-      "defaultSuccess": "The change was saved.",
-      "defaultError": "Something went wrong."
+      "successTitle": "Thành công",
+      "errorTitle": "Lỗi",
+      "unauthorizedTitle": "Chưa đăng nhập",
+      "unauthorizedDescription": "Hãy đăng nhập để tiếp tục.",
+      "defaultSuccess": "Đã hoàn tất.",
+      "defaultError": "Đã xảy ra lỗi."
     },
     "loading": {
-      "message": "Loading"
+      "message": "Đang tải"
     },
     "notFound": {
-      "title": "Page not found",
-      "home": "Return home"
+      "title": "Không tìm thấy trang",
+      "home": "Về trang chủ"
     },
     "errors": {
       "page": {
-        "title": "Something went wrong",
-        "retry": "Try again"
+        "title": "Đã xảy ra lỗi",
+        "retry": "Thử lại"
       },
       "global": {
-        "title": "The application could not continue",
-        "retry": "Try again"
+        "title": "Đã xảy ra lỗi nghiêm trọng",
+        "retry": "Thử lại"
       }
+    },
+    "guide": {
+      "open": "Xem hướng dẫn",
+      "title": "Bắt đầu",
+      "description": "Đăng nhập để sử dụng ứng dụng. Bạn có thể đóng hướng dẫn này và mở lại bất cứ lúc nào.",
+      "close": "Đóng"
     }
   }
 }

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

@@ -1,4 +1,4 @@
-const LOCALES = ["vi"] as const
+const LOCALES = ["vi", "en"] as const
 
 /** The locale served at the unprefixed path. */
 export const DEFAULT_LOCALE = "vi" as const

package/templates/fe/transport/graphql/clients/clients/auth.ts

@@ -21,7 +21,7 @@ export interface CreateAuthApolloClientOptions {
 /**
  * The authenticated Apollo client. The link chain runs outer to inner:
  * retry (transient network failures) -> error (report) -> timeout -> refresh (one token refresh and replay on
- * UNAUTHENTICATED) -> locale (`x-locale`) -> access token (`Authorization: Bearer`, from modules/auth) -> http (terminal).
+ * UNAUTHENTICATED) -> locale (`Accept-Language`) -> access token (`Authorization: Bearer`, from modules/auth) -> http (terminal).
  */
 export const createAuthApolloClient = ({ signal, report }: CreateAuthApolloClientOptions = {}) =>
     new ApolloClient({

package/templates/fe/transport/graphql/clients/links/locale.ts

@@ -4,10 +4,10 @@ import { SetContextLink } from "@apollo/client/link/context"
 const documentLocale = (): string | undefined =>
     typeof document === "undefined" || document.documentElement.lang === "" ? undefined : document.documentElement.lang
 
-/** The one writer of `x-locale`: every operation declares the language the back end answers and localizes its errors in. */
+/** The one writer of `Accept-Language`: every operation declares the language the back end answers and localizes its errors in. */
 export const createAttachLocaleLink = (locale: () => string | undefined = documentLocale) =>
     new SetContextLink((context) => {
         const value = locale()
         if (value === undefined) return {}
-        return { headers: { ...context.headers, "x-locale": value } }
+        return { headers: { ...context.headers, "Accept-Language": value } }
     })

package/upgrade/check.mjs

@@ -11,10 +11,12 @@ import {
 import { loadSlotManifest, openHfs } from "../runtime/scripts/hfs/slots.mjs";
 import { formatFindings } from "../sync/format.mjs";
 import {
+  appSource,
   checkTargets,
   loadHfs,
   renderTargets,
 } from "../sync/index.mjs";
+import { readDeclaredStack } from "../sync/stack-images.mjs";
 import {
   UPGRADE_PRESETS,
   UpgradeError,
@@ -91,7 +93,7 @@ export async function checkEdition({
   // A lite app scaffolded before the 2026-10-12 ruling has no Jest preset installed. 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 managed = renderTargets(full, resolvedPresets, { manifest, source: { ...appSource(repoRoot), stack: readDeclaredStack(repoRoot) } });
   const extra = [
     ...fullManagedFindings(repoRoot, managed),
     ...(await checkDatabase({ repoRoot, files: tracked })),

package/upgrade/file-state.mjs

@@ -0,0 +1,68 @@
+// Authored-file preservation, snapshots and rollback for an additive edition upgrade.
+import fs from "node:fs";
+import path from "node:path";
+import { dockerfilePath } from "../runtime/scripts/hfs/rules/docker.mjs";
+
+/** App-owned additions are preserved; only declared regular optional front-end images receive that treatment. */
+export function authoredAdditionReasons(declaration, source) {
+  const reasons = new Map([[
+    ".starcistacks/application-stacks.yaml",
+    "The app already declares its stacks; the declaration stays as the app wrote it.",
+  ]]);
+  for (const app of declaration.sides.fe.apps) {
+    const file = dockerfilePath("fe", app.name);
+    if (source.hasImage(file)) reasons.set(file,
+      "The lite app already authors this optional front-end image; its Dockerfile stays as the app wrote it.");
+  }
+  return reasons;
+}
+
+export function remember(snapshot, target) {
+  if (snapshot.has(target)) return;
+  snapshot.set(
+    target,
+    fs.existsSync(target) && fs.statSync(target).isFile()
+      ? fs.readFileSync(target)
+      : null,
+  );
+}
+
+export function ensureParent(root, target, directories) {
+  const missing = [];
+  for (
+    let at = path.dirname(target);
+    at.startsWith(root) && at !== root && !fs.existsSync(at);
+    at = path.dirname(at)
+  )
+    missing.push(at);
+  for (const directory of missing.reverse()) {
+    fs.mkdirSync(directory);
+    directories.push(directory);
+  }
+}
+
+export function writeFile(root, file, content, snapshot, directories) {
+  const target = path.join(root, ...file.split("/"));
+  remember(snapshot, target);
+  ensureParent(root, target, directories);
+  fs.writeFileSync(target, content);
+}
+
+export function restore(snapshot, directories) {
+  for (const [target, content] of [...snapshot.entries()].reverse()) {
+    if (content === null) {
+      if (fs.existsSync(target) && fs.statSync(target).isFile())
+        fs.unlinkSync(target);
+    } else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, content);
+    }
+  }
+  for (const directory of [...directories].reverse()) {
+    try {
+      fs.rmdirSync(directory);
+    } catch {
+      /* It is non-empty or already absent: preserve it. */
+    }
+  }
+}