create-windy 0.1.0

package/template/apps/web/dev/dev-identity.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import type { Plugin } from "vite";
+
+export const WINDY_DEV_PRODUCT = "windy-platform";
+export const WINDY_DEV_PROTOCOL = "windy-dev/v1";
+
+export interface WindyDevIdentity {
+  product: typeof WINDY_DEV_PRODUCT;
+  protocol: typeof WINDY_DEV_PROTOCOL;
+  projectFingerprint: string;
+}
+
+export function projectFingerprint(projectRoot: string): string {
+  return createHash("sha256")
+    .update(realpathSync(projectRoot))
+    .digest("hex")
+    .slice(0, 24);
+}
+
+export function windyDevIdentity(fingerprint: string): WindyDevIdentity {
+  return {
+    product: WINDY_DEV_PRODUCT,
+    protocol: WINDY_DEV_PROTOCOL,
+    projectFingerprint: fingerprint,
+  };
+}
+
+export function windyDevIdentityPlugin(fingerprint: string): Plugin {
+  const identity = windyDevIdentity(fingerprint);
+  return {
+    name: "windy-dev-identity",
+    configureServer(server) {
+      server.middlewares.use((request, response, next) => {
+        const pathname = new URL(request.url || "/", "http://windy.local")
+          .pathname;
+        if (pathname !== "/-/windy-dev") {
+          next();
+          return;
+        }
+        response.statusCode = 200;
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        response.end(JSON.stringify(identity));
+      });
+    },
+  };
+}
+
+export function isWindyDevIdentity(value: unknown): value is WindyDevIdentity {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    candidate.product === WINDY_DEV_PRODUCT &&
+    candidate.protocol === WINDY_DEV_PROTOCOL &&
+    typeof candidate.projectFingerprint === "string"
+  );
+}

package/template/apps/web/dev/dev-port.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { selectDevPort, type PortState } from "./dev-port";
+import { windyDevIdentity } from "./dev-identity";
+
+describe("Windy 本地开发端口", () => {
+  test("默认选择 8746", async () => {
+    const result = await selectDevPort({
+      fingerprint: "project-a",
+      inspect: async () => ({ kind: "available" }),
+    });
+
+    expect(result).toEqual({ kind: "selected", port: 8_746 });
+  });
+
+  test("外部服务或其他 Windy 项目占用时自动递增", async () => {
+    const states = new Map<number, PortState>([
+      [8_746, { kind: "occupied" }],
+      [8_747, { kind: "occupied", identity: windyDevIdentity("project-b") }],
+    ]);
+    const result = await selectDevPort({
+      fingerprint: "project-a",
+      inspect: async (port) => states.get(port) || { kind: "available" },
+    });
+
+    expect(result).toEqual({ kind: "selected", port: 8_748 });
+  });
+
+  test("检测到同一项目时返回已有地址而不启动重复服务", async () => {
+    const result = await selectDevPort({
+      fingerprint: "project-a",
+      inspect: async () => ({
+        kind: "occupied",
+        identity: windyDevIdentity("project-a"),
+      }),
+    });
+
+    expect(result).toEqual({ kind: "existing", port: 8_746 });
+  });
+
+  test("最多扫描 100 个端口", async () => {
+    let inspections = 0;
+    await expect(
+      selectDevPort({
+        fingerprint: "project-a",
+        inspect: async () => {
+          inspections += 1;
+          return { kind: "occupied" };
+        },
+      }),
+    ).rejects.toThrow("100 个端口均已被占用");
+    expect(inspections).toBe(100);
+  });
+});

package/template/apps/web/dev/dev-port.ts

@@ -0,0 +1,68 @@
+import { isWindyDevIdentity, type WindyDevIdentity } from "./dev-identity";
+
+export const DEFAULT_DEV_PORT = 8_746;
+export const DEV_PORT_SCAN_LIMIT = 100;
+
+export type PortState =
+  | { kind: "available" }
+  | { kind: "occupied"; identity?: WindyDevIdentity };
+
+export interface DevPortSelection {
+  kind: "selected" | "existing";
+  port: number;
+}
+
+export async function selectDevPort(input: {
+  fingerprint: string;
+  startPort?: number;
+  scanLimit?: number;
+  inspect?: (port: number) => Promise<PortState>;
+}): Promise<DevPortSelection> {
+  const startPort = input.startPort ?? DEFAULT_DEV_PORT;
+  const scanLimit = input.scanLimit ?? DEV_PORT_SCAN_LIMIT;
+  const inspect = input.inspect ?? inspectDevPort;
+  for (let offset = 0; offset < scanLimit; offset += 1) {
+    const port = startPort + offset;
+    const state = await inspect(port);
+    if (state.kind === "available") return { kind: "selected", port };
+    if (state.identity?.projectFingerprint === input.fingerprint) {
+      return { kind: "existing", port };
+    }
+  }
+  throw new Error(
+    `从 ${startPort} 开始的 ${scanLimit} 个端口均已被占用，请释放端口后重试。`,
+  );
+}
+
+export async function inspectDevPort(port: number): Promise<PortState> {
+  const identity = await fetchIdentity(port);
+  if (identity) return { kind: "occupied", identity };
+
+  try {
+    const reservation = Bun.serve({
+      hostname: "127.0.0.1",
+      port,
+      fetch: () => new Response("reserved"),
+    });
+    await reservation.stop(true);
+    return { kind: "available" };
+  } catch {
+    return { kind: "occupied" };
+  }
+}
+
+async function fetchIdentity(
+  port: number,
+): Promise<WindyDevIdentity | undefined> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/-/windy-dev`, {
+      signal: AbortSignal.timeout(400),
+      headers: { accept: "application/json" },
+    });
+    if (!response.ok) return undefined;
+    const value: unknown = await response.json();
+    return isWindyDevIdentity(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/template/apps/web/dev/start.ts

@@ -0,0 +1,37 @@
+import { projectFingerprint } from "./dev-identity";
+import { selectDevPort } from "./dev-port";
+
+const fingerprint = projectFingerprint(process.cwd());
+const configuredPort = parseConfiguredPort(process.env.WINDY_DEV_PORT);
+const selection = configuredPort
+  ? { kind: "selected" as const, port: configuredPort }
+  : await selectDevPort({ fingerprint });
+const url = `http://localhost:${selection.port}`;
+
+if (selection.kind === "existing") {
+  console.info(`当前项目的开发服务已在运行：${url}`);
+  process.exit(0);
+}
+
+console.info(`启动 Windy Web：${url}`);
+const child = Bun.spawn(["bunx", "--bun", "vite"], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    WINDY_DEV_PORT: String(selection.port),
+    WINDY_DEV_FINGERPRINT: fingerprint,
+  },
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+});
+process.exit(await child.exited);
+
+function parseConfiguredPort(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("WINDY_DEV_PORT 必须是 1 到 65535 之间的整数。");
+  }
+  return port;
+}

package/template/apps/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Windy Platform Template</title>
+    <!-- Tailwind CSS -->
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body class="bg-gray-50 text-gray-900">
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/apps/web/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@windy/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun run dev/start.ts",
+    "build": "vite build",
+    "start": "bun run server.ts",
+    "serve": "vite preview",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@antv/g2": "^5.4.8",
+    "@lucide/vue": "^1.23.0",
+    "@tailwindcss/vite": "^4.3.2",
+    "@tanstack/vue-form": "^1.33.0",
+    "@tanstack/vue-table": "^8.21.3",
+    "@vueuse/core": "^14.3.0",
+    "@windy/license-sdk": "workspace:*",
+    "@windy/shared": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "pinia": "^3.0.4",
+    "reka-ui": "^2.10.1",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
+    "vee-validate": "^4.15.1",
+    "vue": "^3.5.39",
+    "vue-router": "^5.1.0",
+    "vue-sonner": "^2.0.9"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vue/test-utils": "^2.4.11",
+    "@windy/modules": "workspace:*",
+    "happy-dom": "^20.10.6",
+    "tw-animate-css": "^1.4.0",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10",
+    "vue-tsc": "^3.3.7"
+  }
+}

package/template/apps/web/runtime-server.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, mock, test } from "bun:test";
+import { mkdir, rm } from "node:fs/promises";
+import { createWebFetchHandler } from "./runtime-server";
+
+describe("Web 生产同源 API 代理", () => {
+  test("保留 Cookie/Origin 并把 /api 精确转发到内部 Server", async () => {
+    const fetcher = mock(
+      async (_url: string | URL | Request, init?: RequestInit) => {
+        expect(init?.credentials).toBeUndefined();
+        return Response.json(
+          { ok: true },
+          { headers: { "set-cookie": "windy.sid=session; HttpOnly" } },
+        );
+      },
+    );
+    const handler = createWebFetchHandler({
+      distDir: "/tmp/not-used",
+      apiUpstream: "http://server:3000",
+      fetcher,
+    });
+
+    const response = await handler(
+      new Request("https://platform.example/api/auth/session?fresh=1", {
+        headers: {
+          cookie: "windy.sid=session",
+          origin: "https://platform.example",
+          "x-request-id": "request-web-1",
+        },
+      }),
+    );
+
+    const [target, init] = fetcher.mock.calls[0]!;
+    expect(String(target)).toBe("http://server:3000/api/auth/session?fresh=1");
+    const headers = new Headers(init?.headers);
+    expect(headers.get("cookie")).toBe("windy.sid=session");
+    expect(headers.get("origin")).toBe("https://platform.example");
+    expect(headers.get("x-forwarded-host")).toBe("platform.example");
+    expect(headers.get("x-forwarded-proto")).toBe("https");
+    expect(headers.get("x-request-id")).toBe("request-web-1");
+    expect(response.headers.get("x-request-id")).toBe("request-web-1");
+    expect(response.headers.get("set-cookie")).toContain("windy.sid=session");
+  });
+
+  test("未配置内部 Server 时 fail closed", async () => {
+    const fetcher = mock();
+    const handler = createWebFetchHandler({
+      distDir: "/tmp/not-used",
+      fetcher,
+    });
+
+    const response = await handler(
+      new Request("http://localhost:9746/api/auth/session"),
+    );
+
+    expect(response.status).toBe(503);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  test("liveness 独立存活，readiness 同时验证静态产物和 API 上游", async () => {
+    const distDir = `${process.cwd()}/.tmp-web-readiness-${crypto.randomUUID()}`;
+    await mkdir(distDir, { recursive: true });
+    await Bun.write(`${distDir}/index.html`, "ready");
+    const fetcher = mock(async () => Response.json({ status: "ready" }));
+    const handler = createWebFetchHandler({
+      distDir,
+      apiUpstream: "http://server:3000",
+      fetcher,
+    });
+    try {
+      const live = await handler(new Request("http://web/-/live"));
+      const ready = await handler(
+        new Request("http://web/-/ready", {
+          headers: { "x-request-id": "readiness-1" },
+        }),
+      );
+      expect(live.status).toBe(200);
+      expect(ready.status).toBe(200);
+      expect(ready.headers.get("x-request-id")).toBe("readiness-1");
+      expect(String(fetcher.mock.calls[0]?.[0])).toBe(
+        "http://server:3000/api/ready",
+      );
+    } finally {
+      await rm(distDir, { recursive: true, force: true });
+    }
+  });
+});

package/template/apps/web/runtime-server.ts

@@ -0,0 +1,143 @@
+import { extname, join, normalize } from "node:path";
+import { correlationId } from "@windy/shared";
+
+export interface WebFetchHandlerOptions {
+  distDir: string;
+  apiUpstream?: string;
+  fetcher?: typeof fetch;
+}
+
+const contentTypes: Record<string, string> = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".ico": "image/x-icon",
+};
+
+export function createWebFetchHandler(options: WebFetchHandlerOptions) {
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const requestId = correlationId(request.headers.get("x-request-id"));
+    if (url.pathname === "/-/live") {
+      return json({ status: "alive" }, 200, requestId);
+    }
+    if (url.pathname === "/-/ready") {
+      return webReadiness(options, requestId);
+    }
+    if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+      return proxyApi(request, url, options, requestId);
+    }
+    return withRequestId(
+      await serveStatic(url.pathname, options.distDir),
+      requestId,
+    );
+  };
+}
+
+async function serveStatic(
+  pathname: string,
+  distDir: string,
+): Promise<Response> {
+  const filePath = resolveFile(pathname, distDir);
+  const file = Bun.file(filePath);
+  if (await file.exists()) {
+    return new Response(file, {
+      headers: {
+        "content-type":
+          contentTypes[extname(filePath)] || "application/octet-stream",
+      },
+    });
+  }
+  return new Response(Bun.file(join(distDir, "index.html")), {
+    headers: { "content-type": contentTypes[".html"] },
+  });
+}
+
+function resolveFile(pathname: string, distDir: string): string {
+  const safePath = normalize(pathname).replace(/^(\.\.(\/|\\|$))+/, "");
+  return join(distDir, safePath === "/" ? "index.html" : safePath);
+}
+
+async function proxyApi(
+  request: Request,
+  url: URL,
+  options: WebFetchHandlerOptions,
+  requestId: string,
+): Promise<Response> {
+  if (!options.apiUpstream) {
+    return json({ error: "API_UPSTREAM_NOT_CONFIGURED" }, 503, requestId);
+  }
+  const target = new URL(`${url.pathname}${url.search}`, options.apiUpstream);
+  const headers = new Headers(request.headers);
+  headers.delete("connection");
+  headers.delete("content-length");
+  headers.delete("host");
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.slice(0, -1));
+  headers.set("x-request-id", requestId);
+  try {
+    const response = await (options.fetcher || fetch)(target, {
+      method: request.method,
+      headers,
+      body:
+        request.method === "GET" || request.method === "HEAD"
+          ? undefined
+          : await request.arrayBuffer(),
+      redirect: "manual",
+    });
+    return withRequestId(response, requestId);
+  } catch {
+    return json({ error: "API_UPSTREAM_UNAVAILABLE" }, 502, requestId);
+  }
+}
+
+async function webReadiness(
+  options: WebFetchHandlerOptions,
+  requestId: string,
+): Promise<Response> {
+  if (!(await Bun.file(join(options.distDir, "index.html")).exists())) {
+    return json(
+      { status: "not-ready", check: "static-assets" },
+      503,
+      requestId,
+    );
+  }
+  if (!options.apiUpstream) {
+    return json({ status: "not-ready", check: "api-upstream" }, 503, requestId);
+  }
+  try {
+    const response = await (options.fetcher || fetch)(
+      new URL("/api/ready", options.apiUpstream),
+      { headers: { "x-request-id": requestId } },
+    );
+    return json(
+      { status: response.ok ? "ready" : "not-ready", check: "api-upstream" },
+      response.ok ? 200 : 503,
+      requestId,
+    );
+  } catch {
+    return json({ status: "not-ready", check: "api-upstream" }, 503, requestId);
+  }
+}
+
+function withRequestId(response: Response, requestId: string): Response {
+  const headers = new Headers(response.headers);
+  headers.set("x-request-id", requestId);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+function json(body: unknown, status: number, requestId: string): Response {
+  return Response.json(body, {
+    status,
+    headers: { "cache-control": "no-store", "x-request-id": requestId },
+  });
+}

package/template/apps/web/server.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+import { createWebFetchHandler } from "./runtime-server";
+
+const port = process.env.PORT ? Number(process.env.PORT) : 9_746;
+const server = Bun.serve({
+  port,
+  fetch: createWebFetchHandler({
+    distDir: join(process.cwd(), "dist"),
+    apiUpstream: process.env.API_UPSTREAM?.trim(),
+  }),
+});
+
+console.info(
+  JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level: "info",
+    event: "service.started",
+    component: "windy-web",
+    port: server.port,
+  }),
+);

package/template/apps/web/src/App.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import AppShell from "@/layout/AppShell.vue";
+import AppLayout from "@/app/layouts/AppLayout.vue";
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { usePlatformSettings } from "@/composables/usePlatformSettings";
+
+const route = useRoute();
+const platformSettings = usePlatformSettings();
+const layout = computed(() => route.meta.layout);
+void platformSettings.ensureLoaded();
+</script>
+
+<template>
+  <AppShell v-if="layout === 'admin'">
+    <RouterView />
+  </AppShell>
+  <AppLayout v-else-if="layout === 'app'">
+    <RouterView />
+  </AppLayout>
+  <RouterView v-else />
+</template>

package/template/apps/web/src/app/home/HomePage.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { computed, onMounted, shallowRef } from "vue";
+import { useRouter } from "vue-router";
+import { resetAccessSnapshot } from "@/composables/useAccessSnapshot";
+import { useAppToast } from "@/composables/useAppToast";
+import { useAuthSession } from "@/composables/useAuthSession";
+// @windy-module system.license begin
+import { resetLicenseRuntime } from "@/composables/useLicenseRuntime";
+// @windy-module system.license end
+import { usePlatformSettings } from "@/composables/usePlatformSettings";
+import {
+  resetSessionContext,
+  useSessionContext,
+} from "@/composables/useSessionContext";
+import HomeWelcome from "./HomeWelcome.vue";
+
+const router = useRouter();
+const auth = useAuthSession();
+const platform = usePlatformSettings();
+const session = useSessionContext();
+const toast = useAppToast();
+const loggingOut = shallowRef(false);
+const displayName = computed(
+  () =>
+    session.context.value?.user.displayName ||
+    auth.actor.value?.displayName ||
+    auth.actor.value?.name ||
+    "用户",
+);
+
+onMounted(() => void loadContext());
+
+async function loadContext(force = false): Promise<void> {
+  try {
+    await (force ? session.refresh() : session.ensureLoaded());
+  } catch {
+    // 首页保留可用；错误状态由展示组件提供重试入口。
+  }
+}
+
+async function logout(): Promise<void> {
+  if (loggingOut.value) return;
+  loggingOut.value = true;
+  try {
+    await auth.logout();
+    resetSessionContext();
+    resetAccessSnapshot();
+    // @windy-module system.license begin
+    resetLicenseRuntime();
+    // @windy-module system.license end
+    await router.replace({ name: "login" });
+  } catch {
+    toast.error("退出失败", {
+      description: auth.error.value || "服务暂时不可用，请稍后重试。",
+    });
+  } finally {
+    loggingOut.value = false;
+  }
+}
+</script>
+
+<template>
+  <HomeWelcome
+    :project-name="platform.softwareName.value"
+    :display-name="displayName"
+    :username="session.context.value?.user.username"
+    :admin-access="session.context.value?.capabilities.adminAccess === true"
+    :loading="session.loading.value"
+    :logging-out="loggingOut"
+    :error="session.error.value"
+    @enter-admin="router.push('/admin')"
+    @logout="logout"
+    @retry="loadContext(true)"
+  />
+</template>