feat(template): add new schema based configuration infrastructures (#6567)

* feat(template): add new config schema

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(shared): add config loader utils

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): try loading config file in instrumentation hook

Signed-off-by: Nixieboluo <me@sagirii.me>

* docs(shared): config loader docs

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(shared): client app config utils

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): setup client app config

Signed-off-by: Nixieboluo <me@sagirii.me>

* fix(shared): ensure client app config is fetched before loading other parts

Signed-off-by: Nixieboluo <me@sagirii.me>

* refactor(template): remove next public env vars

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): remove env var usages

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): remove system config (slide data) usages

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): remove system env store usage

Signed-off-by: Nixieboluo <me@sagirii.me>

* refactor(template): remove sidebar store

Signed-off-by: Nixieboluo <me@sagirii.me>

* feat(template): provide schema enforced config example

Signed-off-by: Nixieboluo <me@sagirii.me>

* fix(template): ignore log rules in instrumentation hook

Signed-off-by: Nixieboluo <me@sagirii.me>

---------

Signed-off-by: Nixieboluo <me@sagirii.me>

Author: Nixieboluo

frontend/packages/shared/package.json

@@ -2,14 +2,16 @@
   "name": "@sealos/shared",
   "version": "1.0.0",
   "description": "Shared utilities, types, and components for Sealos frontend applications",
+  "license": "ISC",
   "private": true,
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./chakra": "./src/components/chakra/index.ts",
     "./shadcn": "./src/components/shadcn/index.ts",
-    "./components/shadcn/styles.css": "./src/components/shadcn/styles.css"
+    "./components/shadcn/styles.css": "./src/components/shadcn/styles.css",
+    "./server/config": "./src-server/config/index.ts"
   },
   "typesVersions": {
     "*": {
@@ -18,55 +20,98 @@
       ],
       "shadcn": [
         "src/components/shadcn/index.ts"
+      ],
+      "server/config": [
+        "src-server/config/index.ts"
       ]
     }
   },
   "scripts": {
     "build": "exit 0",
-    "lint": "eslint src --ext .ts,.tsx",
+    "lint": "eslint src src-server --ext .ts,.tsx",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": [
-    "sealos",
-    "shared"
-  ],
-  "author": "",
-  "license": "ISC",
   "peerDependencies": {
     "@chakra-ui/icons": "^2",
     "@chakra-ui/react": "^2",
+    "@tanstack/react-query": "^4",
     "immer": "^10",
+    "js-yaml": "^4.1.0",
     "lucide-react": ">=0.460.0",
+    "picocolors": "^1.1.1",
     "react": "^18.0 || ^19.0 || ^19.0.0-rc",
     "react-dom": "^18.0 || ^19.0 || ^19.0.0-rc",
     "sealos-desktop-sdk": "workspace:*",
-    "zustand": "^4 || ^5",
-    "zod": "^3 || ^4"
+    "zod": "^3 || ^4",
+    "zustand": "^4 || ^5"
   },
   "peerDependenciesMeta": {
     "@chakra-ui/icons": {
-      "optional": true
+      "optional": true,
+      "description": "Optional for frontend code (Chakra UI components)"
     },
     "@chakra-ui/react": {
-      "optional": true
+      "optional": true,
+      "description": "Optional for frontend code (Chakra UI components)"
+    },
+    "js-yaml": {
+      "optional": false,
+      "description": "Required for backend code (./server export)"
+    },
+    "picocolors": {
+      "optional": false,
+      "description": "Required for backend code (./server export, error formatting)"
+    },
+    "immer": {
+      "optional": false,
+      "description": "Required for frontend code (state management)"
+    },
+    "lucide-react": {
+      "optional": false,
+      "description": "Required for frontend code (icons)"
+    },
+    "react": {
+      "optional": false,
+      "description": "Required for frontend code"
+    },
+    "react-dom": {
+      "optional": false,
+      "description": "Required for frontend code"
+    },
+    "sealos-desktop-sdk": {
+      "optional": false,
+      "description": "Required for frontend code"
+    },
+    "zustand": {
+      "optional": false,
+      "description": "Required for frontend code (state management)"
+    },
+    "zod": {
+      "optional": false,
+      "description": "Required for frontend code (schema validation)"
     }
   },
   "devDependencies": {
     "@chakra-ui/icons": "^2.1.1",
     "@chakra-ui/react": "^2.8.1",
+    "@tanstack/react-query": "^4.36.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.7.1",
     "@types/react": "18.3.27",
     "@types/react-dom": "18.3.7",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "eslint": "^8.57.0",
     "eslint-plugin-import": "^2.29.1",
+    "immer": "^10.2.0",
+    "js-yaml": "^4.1.0",
     "lucide-react": "^0.476.0",
+    "picocolors": "^1.1.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "sealos-desktop-sdk": "workspace:*",
     "typescript": "^5.9.3",
-    "zustand": "^4.5.6",
-    "immer": "^10.2.0",
-    "zod": "^3.22.4"
+    "zod": "^4.3.5",
+    "zustand": "^4.5.6"
   }
 }

frontend/packages/shared/src-server/README.md

@@ -0,0 +1,3 @@
+# @sealos/shared/server
+
+Server-side utilities for Sealos applications.

frontend/packages/shared/src-server/config/README.md

@@ -0,0 +1,23 @@
+# Config module
+
+## Usage
+
+```typescript
+import { readConfig, prettyPrintErrors } from '@sealos/shared/server/config';
+import type { ConfigResult } from '@sealos/shared/server/config';
+
+// For example, configText can be loaded with fs module
+
+// Defaults to YAML parsing (async)
+const result = await readConfig(configText, AppConfigSchema);
+
+// Or use custom parser
+const result = await readConfig(configText, AppConfigSchema, JSON.parse);
+
+if (result.error) {
+  console.error(prettyPrintErrors(result.error.details));
+  process.exit(1);
+}
+
+console.log(result.data);
+```

frontend/packages/shared/src-server/config/error-formatter.ts

@@ -0,0 +1,132 @@
+import { ZodError } from 'zod';
+import * as pc from 'picocolors';
+
+/**
+ * Options for pretty printing errors.
+ */
+export interface PrettyPrintOptions {
+  /** Include error code in output */
+  showCode?: boolean;
+  /** Indentation string */
+  indent?: string;
+}
+
+/**
+ * Create a horizontal separator line.
+ */
+function separator(char: string = '─', length: number = 60): string {
+  return pc.dim(char.repeat(length));
+}
+
+/**
+ * Calculate the display width of a number with dot and space (without ANSI color codes).
+ * Format: "1. " = 3 chars, "10. " = 4 chars
+ */
+function numberWidth(num: number): number {
+  return String(num).length + 2; // +1 for dot, +1 for space (e.g., "1. " = 3 chars)
+}
+
+/**
+ * Pretty print Zod validation errors in a human-readable format with colors.
+ */
+export function prettyPrintErrors(
+  error: ZodError | Error,
+  options: PrettyPrintOptions = {}
+): string {
+  const { showCode = true, indent = '    ' } = options;
+
+  // Handle non-Zod errors
+  if (!(error instanceof ZodError)) {
+    return `${pc.red('✗')} ${pc.bold('Error')}: ${error.message}${
+      error.stack ? '\n' + error.stack : ''
+    }`;
+  }
+
+  const lines: string[] = [];
+
+  // Header with separator
+  lines.push(pc.red('✗ Configuration validation errors'));
+  lines.push(separator());
+  lines.push('');
+
+  // Calculate max issue number width for alignment (with at least one separating space)
+  const maxIssueNum = error.issues.length;
+  const maxIssueNumWidth = numberWidth(maxIssueNum) + 1;
+
+  error.issues.forEach((issue, index) => {
+    const path = issue.path.length > 0 ? issue.path.join(pc.dim('.')) : pc.dim('<root>');
+    const code = showCode ? pc.gray(` [${issue.code}]`) : '';
+    const issueNum = pc.yellow(`${index + 1}. `);
+    const issueNumWidth = numberWidth(index + 1);
+    const padding = ' '.repeat(maxIssueNumWidth - issueNumWidth);
+    const fieldPrefix = `${issueNum}${padding}`;
+    const spacePrefix = ' '.repeat(maxIssueNumWidth);
+
+    lines.push(`${fieldPrefix}${pc.bold('Field')}: ${pc.cyan(path)}${code}`);
+    lines.push(`${spacePrefix}${pc.bold('Message')}: ${pc.red(issue.message)}`);
+
+    // Add received value if available
+    if ('received' in issue && issue.received !== undefined) {
+      const receivedStr = JSON.stringify(issue.received);
+      lines.push(`${spacePrefix}${pc.bold('Received')}: ${pc.red(receivedStr)}`);
+    }
+
+    // Add expected value if available
+    if ('expected' in issue && issue.expected !== undefined) {
+      const expectedStr = JSON.stringify(issue.expected);
+      lines.push(`${spacePrefix}${pc.bold('Expected')}: ${pc.green(expectedStr)}`);
+    }
+
+    // Add valid values if available
+    if ('values' in issue && issue.values !== undefined) {
+      const valuesStr = JSON.stringify(issue.values);
+      lines.push(`${spacePrefix}${pc.bold('Valid values')}: ${pc.green(valuesStr)}`);
+    }
+
+    // Add union errors if available
+    if (issue.code === 'invalid_union' && 'unionErrors' in issue) {
+      const unionErrors = issue.unionErrors as ZodError[];
+      lines.push(`${spacePrefix}${pc.bold('Union errors')}:`);
+      unionErrors.forEach((unionErr: ZodError, uIdx: number) => {
+        lines.push(`${spacePrefix}${indent}${pc.yellow(`Option ${uIdx + 1}`)}:`);
+        unionErr.issues.forEach((subIssue) => {
+          const subPath =
+            subIssue.path.length > 0 ? subIssue.path.join(pc.dim('.')) : pc.dim('<root>');
+          lines.push(
+            `${spacePrefix}${indent}${indent}${pc.dim('─')} ${subPath}: ${pc.red(subIssue.message)}`
+          );
+        });
+      });
+    }
+
+    // Add separator between issues (except last one)
+    if (index < error.issues.length - 1) {
+      lines.push('');
+      lines.push(separator('·', 40));
+      lines.push('');
+    }
+  });
+
+  // Footer with summary
+  lines.push('');
+  lines.push(separator());
+  lines.push(`${pc.red('✗')} ${pc.bold('Total errors')}: ${pc.red(String(error.issues.length))}`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format Zod error for logging (compact one-line format).
+ */
+export function formatErrorCompact(error: ZodError | Error): string {
+  if (!(error instanceof ZodError)) {
+    return `Error: ${error.message}`;
+  }
+
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+    return `${path}: ${issue.message}`;
+  });
+
+  return `Validation failed: ${issues.join('; ')}`;
+}

frontend/packages/shared/src-server/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration reading and validation utilities.
+ */
+
+export { readConfig } from './reader';
+export { prettyPrintErrors, formatErrorCompact, type PrettyPrintOptions } from './error-formatter';
+export { mountToGlobalThis } from './utils';
+export type { ConfigResult, ConfigSuccess, ConfigError } from './types';

frontend/packages/shared/src-server/config/reader.ts

@@ -0,0 +1,53 @@
+import type { z } from 'zod';
+import type { ConfigResult } from './types';
+
+/**
+ * Read and validate configuration from a text string.
+ * Defaults to YAML parsing if parser is not provided.
+ *
+ * @returns frozen readonly config.
+ */
+export async function readConfig<T extends z.ZodType>(
+  text: string,
+  schema: T,
+  parser?: (text: string) => unknown
+): Promise<ConfigResult<z.output<ReturnType<T['readonly']>>>> {
+  try {
+    let parsed: unknown;
+
+    if (parser) {
+      parsed = parser(text);
+    } else {
+      // Default to YAML parsing
+      const yaml = await import('js-yaml');
+      parsed = yaml.load(text);
+    }
+
+    // Use readonly schema to ensure deep readonly types and runtime immutability
+    const readonlySchema = schema.readonly();
+    const result = readonlySchema.safeParse(parsed);
+
+    if (!result.success) {
+      return {
+        error: {
+          message: 'Configuration validation failed',
+          details: result.error
+        }
+      };
+    }
+
+    const config = result.data as z.output<ReturnType<T['readonly']>>;
+
+    return {
+      data: config
+    };
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    return {
+      error: {
+        message: `Failed to parse configuration: ${error.message}`,
+        details: error
+      }
+    };
+  }
+}

frontend/packages/shared/src-server/config/types.ts

@@ -0,0 +1,25 @@
+import type { ZodError } from 'zod';
+
+/**
+ * Result type for successful config parsing.
+ */
+export type ConfigSuccess<T> = {
+  data: T;
+  error?: never;
+};
+
+/**
+ * Result type for failed config parsing.
+ */
+export type ConfigError = {
+  data?: never;
+  error: {
+    message: string;
+    details: ZodError | Error;
+  };
+};
+
+/**
+ * Result type for config parsing operations.
+ */
+export type ConfigResult<T> = ConfigSuccess<T> | ConfigError;

frontend/packages/shared/src-server/config/utils.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely mount a value to globalThis.
+ * The value should already be readonly (from Zod's readonly()).
+ *
+ * @param key - Key to mount on globalThis
+ * @param value - Value to mount (should be readonly from Zod)
+ */
+export function mountToGlobalThis<T>(key: string, value: T): void {
+  (globalThis as Record<string, unknown>)[key] = value;
+}