minutework 0.1.40 → 0.1.41

package/assets/templates/vuilder-shell/src/lib/platform/endpoints.server.ts

@@ -0,0 +1,29 @@
+import "server-only";
+
+import { getEnv } from "@/lib/platform/env.server";
+
+function getPlatformBaseUrl() {
+  const { MW_PLATFORM_BASE_URL } = getEnv();
+
+  return new URL(
+    MW_PLATFORM_BASE_URL.endsWith("/")
+      ? MW_PLATFORM_BASE_URL
+      : `${MW_PLATFORM_BASE_URL}/`,
+  );
+}
+
+function buildPlatformEndpoint(path: string) {
+  return new URL(path.replace(/^\//, ""), getPlatformBaseUrl()).toString();
+}
+
+export const platformAuthEndpoints = {
+  get shellTokenExchange() {
+    return buildPlatformEndpoint("/api/v1/session/shell-token/exchange/");
+  },
+  get shellTokenContext() {
+    return buildPlatformEndpoint("/api/v1/session/shell-token/context/");
+  },
+  get shellTokenRevoke() {
+    return buildPlatformEndpoint("/api/v1/session/shell-token/revoke/");
+  },
+};

package/assets/templates/vuilder-shell/src/lib/platform/env.server.ts

@@ -0,0 +1,82 @@
+import "server-only";
+
+import { z } from "zod";
+
+const LOCAL_PLATFORM_BASE_URL = "http://127.0.0.1:8000";
+const LOCAL_AUTH_BASE_URL = "http://127.0.0.1:3400";
+const LOCAL_PUBLIC_BASE_URL = "http://127.0.0.1:3301";
+
+function normalizeOptionalEnv(value: string | undefined): string | undefined {
+  const trimmedValue = value?.trim();
+  return trimmedValue ? trimmedValue : undefined;
+}
+
+const envSchema = z.object({
+  MW_AUTH_BASE_URL: z.string().url(),
+  MW_PUBLIC_BASE_URL: z.string().url(),
+  MW_PLATFORM_BASE_URL: z.string().url(),
+  MW_PLATFORM_FETCH_TIMEOUT_MS: z.coerce.number().int().positive().default(15000),
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+});
+
+export type PlatformEnv = z.infer<typeof envSchema>;
+
+let cachedEnv: PlatformEnv | null = null;
+
+export function parsePlatformEnv(
+  input: Record<string, string | undefined>,
+): PlatformEnv {
+  const nodeEnv = input.NODE_ENV ?? "development";
+  const isProduction = nodeEnv === "production";
+  const defaultPlatformBaseUrl =
+    normalizeOptionalEnv(input.MW_PLATFORM_BASE_URL) ??
+    (isProduction ? undefined : LOCAL_PLATFORM_BASE_URL);
+  const defaultAuthBaseUrl =
+    normalizeOptionalEnv(input.MW_AUTH_BASE_URL) ??
+    (isProduction ? undefined : LOCAL_AUTH_BASE_URL);
+  const defaultPublicBaseUrl =
+    normalizeOptionalEnv(input.MW_PUBLIC_BASE_URL) ??
+    (isProduction ? undefined : LOCAL_PUBLIC_BASE_URL);
+
+  const parsedEnv = envSchema.safeParse({
+    MW_AUTH_BASE_URL: defaultAuthBaseUrl,
+    MW_PUBLIC_BASE_URL: defaultPublicBaseUrl,
+    MW_PLATFORM_BASE_URL: defaultPlatformBaseUrl,
+    MW_PLATFORM_FETCH_TIMEOUT_MS: normalizeOptionalEnv(
+      input.MW_PLATFORM_FETCH_TIMEOUT_MS,
+    ),
+    NODE_ENV: nodeEnv,
+  });
+
+  if (!parsedEnv.success) {
+    if (isProduction && !normalizeOptionalEnv(input.MW_AUTH_BASE_URL)) {
+      throw new Error("MW_AUTH_BASE_URL must be set in production.");
+    }
+
+    if (isProduction && !normalizeOptionalEnv(input.MW_PUBLIC_BASE_URL)) {
+      throw new Error("MW_PUBLIC_BASE_URL must be set in production.");
+    }
+
+    if (isProduction && !normalizeOptionalEnv(input.MW_PLATFORM_BASE_URL)) {
+      throw new Error("MW_PLATFORM_BASE_URL must be set in production.");
+    }
+
+    throw new Error("Invalid server environment for vuilder-shell.");
+  }
+
+  return parsedEnv.data;
+}
+
+export function getEnv(): PlatformEnv {
+  if (!cachedEnv) {
+    cachedEnv = parsePlatformEnv(process.env);
+  }
+
+  return cachedEnv;
+}
+
+export const env = new Proxy({} as PlatformEnv, {
+  get(_target, property) {
+    return getEnv()[property as keyof PlatformEnv];
+  },
+});

package/assets/templates/vuilder-shell/src/lib/platform/route-response.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+
+import { PlatformClientError } from "@/lib/platform/client.server";
+import type { PlatformAuthState } from "@/lib/platform/session.server";
+import { syncPlatformAuthStateToResponse } from "@/lib/platform/session.server";
+
+export function toPlatformErrorResponse(
+  error: unknown,
+  fallbackDetail: string,
+  previousAuthState?: PlatformAuthState,
+) {
+  if (error instanceof PlatformClientError) {
+    const response = NextResponse.json(
+      {
+        detail: error.message,
+        code: error.code,
+      },
+      { status: error.status },
+    );
+
+    if (previousAuthState && error.authState) {
+      syncPlatformAuthStateToResponse(
+        response,
+        previousAuthState,
+        error.authState,
+      );
+    }
+
+    return response;
+  }
+
+  return NextResponse.json({ detail: fallbackDetail }, { status: 500 });
+}

package/assets/templates/vuilder-shell/src/lib/platform/session.server.ts

@@ -0,0 +1,145 @@
+import "server-only";
+
+import { randomBytes } from "node:crypto";
+
+import { cookies } from "next/headers";
+import type { NextResponse } from "next/server";
+
+import { env } from "@/lib/platform/env.server";
+
+export const VUILDER_SHELL_SESSION_COOKIE = "mw_vuilder_shell_session";
+export const VUILDER_SHELL_HANDOFF_STATE_COOKIE =
+  "mw_vuilder_shell_handoff_state";
+const VUILDER_SHELL_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 12;
+const VUILDER_SHELL_HANDOFF_STATE_MAX_AGE_SECONDS = 60 * 5;
+const LEGACY_PLATFORM_SESSION_COOKIE = "mw_platform_session";
+const LEGACY_PLATFORM_CSRF_COOKIE = "mw_platform_csrf";
+
+export type PlatformAuthState = {
+  shellSessionToken: string | null;
+};
+
+type ShellCookie = {
+  name: string;
+  value: string;
+  httpOnly: boolean;
+  maxAge: number;
+  sameSite: "lax";
+  path: string;
+  secure: boolean;
+};
+
+function boundedShellCookieMaxAge(expiresAt?: string | null) {
+  const parsedExpiresAt = Date.parse(String(expiresAt ?? ""));
+  if (!Number.isFinite(parsedExpiresAt)) {
+    return VUILDER_SHELL_COOKIE_MAX_AGE_SECONDS;
+  }
+  const secondsUntilExpiry = Math.floor((parsedExpiresAt - Date.now()) / 1000);
+  if (secondsUntilExpiry <= 0) {
+    return 0;
+  }
+  return Math.min(secondsUntilExpiry, VUILDER_SHELL_COOKIE_MAX_AGE_SECONDS);
+}
+
+function shellSessionCookie(value: string, expiresAt?: string | null): ShellCookie {
+  return {
+    name: VUILDER_SHELL_SESSION_COOKIE,
+    value,
+    httpOnly: true,
+    maxAge: boundedShellCookieMaxAge(expiresAt),
+    sameSite: "lax",
+    path: "/",
+    secure: env.NODE_ENV === "production",
+  };
+}
+
+function shellHandoffStateCookie(value: string): ShellCookie {
+  return {
+    name: VUILDER_SHELL_HANDOFF_STATE_COOKIE,
+    value,
+    httpOnly: true,
+    maxAge: VUILDER_SHELL_HANDOFF_STATE_MAX_AGE_SECONDS,
+    sameSite: "lax",
+    path: "/",
+    secure: env.NODE_ENV === "production",
+  };
+}
+
+function expiredCookie(name: string): ShellCookie {
+  return {
+    name,
+    value: "",
+    httpOnly: true,
+    maxAge: 0,
+    sameSite: "lax",
+    path: "/",
+    secure: env.NODE_ENV === "production",
+  };
+}
+
+export function createVuilderShellHandoffState() {
+  return randomBytes(32).toString("base64url");
+}
+
+export async function readPlatformAuthState(): Promise<PlatformAuthState> {
+  const cookieStore = await cookies();
+
+  return {
+    shellSessionToken:
+      cookieStore.get(VUILDER_SHELL_SESSION_COOKIE)?.value ?? null,
+  };
+}
+
+export async function readVuilderShellHandoffState() {
+  const cookieStore = await cookies();
+  return cookieStore.get(VUILDER_SHELL_HANDOFF_STATE_COOKIE)?.value ?? null;
+}
+
+export function applyVuilderShellSessionToResponse(
+  response: NextResponse,
+  shellSessionToken: string,
+  expiresAt?: string | null,
+) {
+  response.cookies.set(shellSessionCookie(shellSessionToken, expiresAt));
+}
+
+export function applyVuilderShellHandoffStateToResponse(
+  response: NextResponse,
+  handoffState: string,
+) {
+  response.cookies.set(shellHandoffStateCookie(handoffState));
+}
+
+export function clearVuilderShellHandoffStateFromResponse(
+  response: NextResponse,
+) {
+  response.cookies.set(expiredCookie(VUILDER_SHELL_HANDOFF_STATE_COOKIE));
+}
+
+export function syncPlatformAuthStateToResponse(
+  response: NextResponse,
+  previousAuthState: PlatformAuthState,
+  nextAuthState: PlatformAuthState,
+) {
+  if (previousAuthState.shellSessionToken !== nextAuthState.shellSessionToken) {
+    if (nextAuthState.shellSessionToken) {
+      applyVuilderShellSessionToResponse(
+        response,
+        nextAuthState.shellSessionToken,
+      );
+    } else {
+      clearPlatformSessionFromResponse(response);
+    }
+  }
+}
+
+export function clearPlatformSessionFromResponse(response: NextResponse) {
+  for (const cookieName of [
+    VUILDER_SHELL_SESSION_COOKIE,
+    VUILDER_SHELL_HANDOFF_STATE_COOKIE,
+    LEGACY_PLATFORM_SESSION_COOKIE,
+    LEGACY_PLATFORM_CSRF_COOKIE,
+  ]) {
+    response.cookies.set(expiredCookie(cookieName));
+  }
+}

package/assets/templates/vuilder-shell/src/lib/public-site.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { buildPublicMetadata, resolvePublicSiteUrl } from "@/lib/public-site";
+
+describe("public-site helpers", () => {
+  it("builds canonical urls from MW_PUBLIC_BASE_URL", () => {
+    expect(process.env.MW_PUBLIC_BASE_URL).toBe("http://127.0.0.1:3301");
+
+    const metadata = buildPublicMetadata({
+      title: "Docs",
+      description: "Starter documentation",
+      path: "/docs",
+      siteName: "MinuteWork Combined Starter",
+    });
+
+    expect(resolvePublicSiteUrl("/docs")?.toString()).toBe("http://127.0.0.1:3301/docs");
+    expect(metadata.alternates?.canonical).toBe("http://127.0.0.1:3301/docs");
+    expect(metadata.openGraph?.url).toBe("http://127.0.0.1:3301/docs");
+  });
+});

package/assets/templates/vuilder-shell/src/lib/public-site.ts

@@ -0,0 +1,48 @@
+import type { Metadata } from "next";
+
+export function resolvePublicMetadataBase() {
+  const value = process.env.MW_PUBLIC_BASE_URL || "";
+  if (!value) {
+    return null;
+  }
+  return new URL(value.endsWith("/") ? value : `${value}/`);
+}
+
+export function resolvePublicSiteUrl(pathname = "/") {
+  const metadataBase = resolvePublicMetadataBase();
+  return metadataBase
+    ? new URL(pathname.replace(/^\/*/, "/"), metadataBase)
+    : null;
+}
+
+export function buildPublicMetadata(input: {
+  title: string;
+  description: string;
+  path: string;
+  siteName?: string;
+}): Metadata {
+  const canonicalUrl = resolvePublicSiteUrl(input.path)?.toString();
+  return {
+    title: input.title,
+    description: input.description,
+    ...(canonicalUrl
+      ? {
+          alternates: {
+            canonical: canonicalUrl,
+          },
+        }
+      : {}),
+    openGraph: {
+      title: input.title,
+      description: input.description,
+      siteName: input.siteName ?? process.env.MW_TEMPLATE_APP_NAME ?? "Vuilder Shell",
+      type: "website",
+      ...(canonicalUrl ? { url: canonicalUrl } : {}),
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: input.title,
+      description: input.description,
+    },
+  };
+}

package/assets/templates/vuilder-shell/src/lib/theme-config.ts

@@ -0,0 +1,10 @@
+export type ThemeMode = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+export const THEME_STORAGE_KEY = "next-tenant-app-theme";
+export const THEME_COOKIE_NAME = "next-tenant-app-theme";
+export const SYSTEM_THEME_QUERY = "(prefers-color-scheme: dark)";
+
+export function isThemeMode(value: string | null | undefined): value is ThemeMode {
+  return value === "light" || value === "dark" || value === "system";
+}

package/assets/templates/vuilder-shell/src/lib/theme.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  isThemeMode,
+  SYSTEM_THEME_QUERY,
+  THEME_COOKIE_NAME,
+  THEME_STORAGE_KEY,
+  type ResolvedTheme,
+  type ThemeMode,
+} from "@/lib/theme-config";
+
+type ThemeContextValue = {
+  theme: ThemeMode;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (theme: ThemeMode) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function getSystemTheme(): ResolvedTheme {
+  return window.matchMedia(SYSTEM_THEME_QUERY).matches ? "dark" : "light";
+}
+
+function resolveTheme(theme: ThemeMode, systemTheme: ResolvedTheme): ResolvedTheme {
+  return theme === "system" ? systemTheme : theme;
+}
+
+function applyThemeToDocument(resolvedTheme: ResolvedTheme, attribute: string) {
+  const root = document.documentElement;
+
+  if (attribute === "class") {
+    root.classList.remove("light", "dark");
+    root.classList.add(resolvedTheme);
+  } else {
+    root.setAttribute(attribute, resolvedTheme);
+  }
+
+  root.style.colorScheme = resolvedTheme;
+}
+
+function disableTransitionsTemporarily() {
+  const style = document.createElement("style");
+  style.appendChild(
+    document.createTextNode(
+      "*{-webkit-transition:none !important;transition:none !important}",
+    ),
+  );
+  document.head.appendChild(style);
+
+  return () => {
+    window.getComputedStyle(document.body);
+    window.setTimeout(() => {
+      style.remove();
+    }, 0);
+  };
+}
+
+export function ThemeProvider({
+  children,
+  attribute = "class",
+  defaultTheme = "system",
+  enableSystem = true,
+  disableTransitionOnChange = false,
+}: {
+  children: ReactNode;
+  attribute?: string;
+  defaultTheme?: ThemeMode;
+  enableSystem?: boolean;
+  disableTransitionOnChange?: boolean;
+}) {
+  const [theme, setThemeState] = useState<ThemeMode>(() => {
+    if (typeof window === "undefined") {
+      return defaultTheme;
+    }
+
+    try {
+      const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY);
+      if (isThemeMode(storedTheme)) {
+        return storedTheme;
+      }
+    } catch {}
+
+    return defaultTheme;
+  });
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(() => {
+    if (typeof window === "undefined") {
+      return "light";
+    }
+
+    return getSystemTheme();
+  });
+  const resolvedTheme = resolveTheme(
+    theme,
+    enableSystem ? systemTheme : ("light" as ResolvedTheme),
+  );
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(SYSTEM_THEME_QUERY);
+    const syncSystemTheme = () => {
+      setSystemTheme(mediaQuery.matches ? "dark" : "light");
+    };
+
+    syncSystemTheme();
+    mediaQuery.addEventListener("change", syncSystemTheme);
+
+    return () => {
+      mediaQuery.removeEventListener("change", syncSystemTheme);
+    };
+  }, []);
+
+  useEffect(() => {
+    const restoreTransitions = disableTransitionOnChange
+      ? disableTransitionsTemporarily()
+      : null;
+
+    applyThemeToDocument(resolvedTheme, attribute);
+
+    if (restoreTransitions) {
+      restoreTransitions();
+    }
+  }, [attribute, disableTransitionOnChange, resolvedTheme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      resolvedTheme,
+      setTheme: (nextTheme) => {
+        setThemeState(nextTheme);
+
+        try {
+          window.localStorage.setItem(THEME_STORAGE_KEY, nextTheme);
+          document.cookie = `${THEME_COOKIE_NAME}=${nextTheme}; path=/; max-age=31536000; SameSite=Lax`;
+        } catch {}
+      },
+    }),
+    [resolvedTheme, theme],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+
+  if (!context) {
+    throw new Error("useTheme must be used within ThemeProvider");
+  }
+
+  return context;
+}

package/assets/templates/vuilder-shell/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/assets/templates/vuilder-shell/template.json

@@ -0,0 +1,28 @@
+{
+  "template_id": "vuilder-shell",
+  "template_kind": "vuilder_shell",
+  "template_profile": "vuilder_shell_token",
+  "template_bundle_ref": "runtime/builder/templates/vuilder-shell",
+  "template_version": "0.1.0",
+  "materialize": {
+    "destination": "vuilder-shell"
+  },
+  "builder_edit_mode": "workspace_copy_only",
+  "seed_source": "apps/mw-next-client",
+  "required_bootstrap_steps": [
+    "next_typegen",
+    "design_system_tokens"
+  ],
+  "runtime_contract_refs": [
+    "reference/mwv3-dj6-docs/auth_and_credential_contract.md",
+    "reference/mwv3-dj6-docs/gateway_shell_server_channel_thread_contract.md",
+    "reference/mwv3-dj6-docs/published_web_property_contract.md",
+    "reference/mwv3-dj6-docs/runtime_app_pack_contract.md",
+    "reference/mwv3-dj6-docs/runtime_compute_isolation_and_sandboxing_contract.md"
+  ],
+  "example_features": {
+    "vuilder_shell_token_demo": {
+      "default_enabled": true
+    }
+  }
+}