@finesoft/create-app 0.1.0

package/dist/index.mjs

@@ -0,0 +1,129 @@
+import * as prompts from "@clack/prompts";
+import { bold, cyan, green, red } from "kolorist";
+import * as fs from "node:fs";
+import * as path from "node:path";
+//#region src/index.ts
+const FRAMEWORKS = [
+	{
+		name: "vue",
+		display: "Vue",
+		color: green,
+		variants: [{
+			name: "vue",
+			display: "Full (SSR + routing + DI + guards)"
+		}, {
+			name: "vue-minimal",
+			display: "Minimal"
+		}]
+	},
+	{
+		name: "react",
+		display: "React",
+		color: cyan,
+		variants: [{
+			name: "react",
+			display: "Full (SSR + routing + DI + guards)"
+		}, {
+			name: "react-minimal",
+			display: "Minimal"
+		}]
+	},
+	{
+		name: "svelte",
+		display: "Svelte",
+		color: red,
+		variants: [{
+			name: "svelte",
+			display: "Full (SSR + routing + DI + guards)"
+		}, {
+			name: "svelte-minimal",
+			display: "Minimal"
+		}]
+	}
+];
+async function main() {
+	prompts.intro(bold("Create Finesoft App"));
+	const project = await prompts.group({
+		name: () => prompts.text({
+			message: "Project name",
+			placeholder: "my-finesoft-app",
+			defaultValue: "my-finesoft-app",
+			validate: (value) => {
+				if (!value) return "Project name is required";
+				if (/[^\w\-.]/.test(value)) return "Invalid project name";
+			}
+		}),
+		framework: () => prompts.select({
+			message: "Framework",
+			options: FRAMEWORKS.map((f) => ({
+				value: f.name,
+				label: f.color(f.display)
+			}))
+		}),
+		variant: ({ results }) => {
+			const fw = FRAMEWORKS.find((f) => f.name === results.framework);
+			return prompts.select({
+				message: "Template",
+				options: fw.variants.map((v) => ({
+					value: v.name,
+					label: v.display
+				}))
+			});
+		}
+	}, { onCancel: () => {
+		prompts.cancel("Operation cancelled.");
+		process.exit(0);
+	} });
+	const targetDir = path.resolve(process.cwd(), project.name);
+	const templateName = project.variant;
+	const templateDir = path.resolve(new URL(".", import.meta.url).pathname, "..", "templates", templateName);
+	if (!fs.existsSync(templateDir)) {
+		prompts.log.error(`Template "${templateName}" not found at ${templateDir}`);
+		process.exit(1);
+	}
+	if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+		const overwrite = await prompts.confirm({ message: `Directory "${project.name}" is not empty. Overwrite?` });
+		if (!overwrite || prompts.isCancel(overwrite)) {
+			prompts.cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		fs.rmSync(targetDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	copyDir(templateDir, targetDir);
+	const pkgPath = path.join(targetDir, "package.json");
+	if (fs.existsSync(pkgPath)) {
+		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+		pkg.name = project.name;
+		if (pkg.devDependencies) {
+			for (const [key, value] of Object.entries(pkg.devDependencies)) if (value === "catalog:") pkg.devDependencies[key] = "latest";
+		}
+		fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 4) + "\n");
+	}
+	const fw = FRAMEWORKS.find((f) => f.name === project.framework);
+	prompts.log.success(green(`Created ${bold(project.name)} with ${fw.color(fw.display)}`));
+	prompts.note([
+		`cd ${project.name}`,
+		"vp install",
+		"vp dev"
+	].join("\n"), "Next steps");
+	prompts.outro("Happy coding!");
+}
+function copyDir(src, dest) {
+	fs.mkdirSync(dest, { recursive: true });
+	for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+		const srcPath = path.join(src, entry.name);
+		const destPath = path.join(dest, entry.name);
+		if (entry.name === "node_modules" || entry.name === "dist") continue;
+		if (entry.isDirectory()) copyDir(srcPath, destPath);
+		else fs.copyFileSync(srcPath, destPath);
+	}
+}
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@finesoft/create-app",
+  "version": "0.1.0",
+  "description": "Scaffold a new Finesoft Front project",
+  "license": "MIT",
+  "bin": {
+    "create-finesoft-app": "dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "kolorist": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "vite-plus": "latest"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch"
+  }
+}

package/templates/react/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!--ssr-head-->
+    </head>
+    <body>
+        <div id="app"><!--ssr-body--></div>
+        <!--ssr-data-->
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

package/templates/react/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "finesoft-react",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vp dev",
+        "build": "vp build",
+        "preview": "vp preview"
+    },
+    "dependencies": {
+        "@finesoft/front": "workspace:*",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^4.0.0",
+        "vite-plus": "catalog:"
+    }
+}

package/templates/react/src/App.tsx

@@ -0,0 +1,20 @@
+import type { Action } from "@finesoft/front";
+import { Layout } from "./components/Layout";
+import { Loading } from "./components/Loading";
+import { PageRenderer } from "./components/PageRenderer";
+import type { AppPage } from "./lib/models/product";
+
+interface AppProps {
+    page?: AppPage | null;
+    loading?: boolean;
+    onAction?: (action: Action) => void;
+}
+
+export default function App({ page, loading = false, onAction }: AppProps) {
+    return (
+        <Layout currentPath={page?.url ?? "/"} onAction={onAction}>
+            {loading && <Loading />}
+            {page && <PageRenderer page={page} onAction={onAction} />}
+        </Layout>
+    );
+}

package/templates/react/src/actions.ts

@@ -0,0 +1,14 @@
+import { makeExternalUrlAction, makeFlowAction, type Action } from "@finesoft/front";
+
+/** 创建指向商品详情的 FlowAction */
+export function productDetailAction(id: string): Action {
+    return makeFlowAction(`/products/${id}`);
+}
+
+/** 导航 Actions */
+export const NAV_ACTIONS = {
+    home: makeFlowAction("/"),
+    search: makeFlowAction("/search"),
+    about: makeFlowAction("/about"),
+    github: makeExternalUrlAction("https://github.com/nicepkg/finesoft"),
+} as const;

package/templates/react/src/bootstrap.ts

@@ -0,0 +1,36 @@
+import { type Framework, defineRoutes } from "@finesoft/front";
+import { AboutController } from "./lib/controllers/about";
+import { HomeController } from "./lib/controllers/home";
+import { ProductDetailController } from "./lib/controllers/product-detail";
+import { SearchController } from "./lib/controllers/search";
+import { authGuard } from "./lib/guards/auth";
+import { seoGuard } from "./lib/guards/seo";
+
+export function bootstrap(framework: Framework): void {
+    framework.afterLoad(seoGuard);
+
+    defineRoutes(framework, [
+        { path: "/", intentId: "home", controller: new HomeController() },
+        {
+            path: "/products/:id",
+            intentId: "product-detail",
+            controller: new ProductDetailController(),
+        },
+        {
+            path: "/search",
+            intentId: "search",
+            controller: new SearchController(),
+        },
+        {
+            path: "/about",
+            intentId: "about",
+            controller: new AboutController(),
+            renderMode: "csr",
+        },
+        {
+            path: "/admin",
+            intentId: "home",
+            beforeLoad: [authGuard],
+        },
+    ]);
+}

package/templates/react/src/components/Layout.tsx

@@ -0,0 +1,63 @@
+import type { Action } from "@finesoft/front";
+import { NAV_ACTIONS } from "../actions";
+
+interface LayoutProps {
+    children: React.ReactNode;
+    currentPath?: string;
+    onAction?: (action: Action) => void;
+}
+
+/** 公共布局 — 顶部导航栏 + 内容区 */
+export function Layout({ children, currentPath = "/", onAction }: LayoutProps) {
+    const handleNav = (action: Action) => (e: React.MouseEvent) => {
+        e.preventDefault();
+        onAction?.(action);
+    };
+
+    const navItems = [
+        { label: "Home", action: NAV_ACTIONS.home, path: "/" },
+        { label: "Search", action: NAV_ACTIONS.search, path: "/search" },
+        { label: "About", action: NAV_ACTIONS.about, path: "/about" },
+    ];
+
+    return (
+        <div>
+            <nav
+                style={{
+                    display: "flex",
+                    gap: "1rem",
+                    padding: "1rem",
+                    borderBottom: "1px solid #eee",
+                    alignItems: "center",
+                }}
+            >
+                {navItems.map((item) => (
+                    <a
+                        key={item.path}
+                        href={item.path}
+                        style={{
+                            textDecoration: "none",
+                            color: currentPath === item.path ? "#007bff" : "#333",
+                            fontWeight: currentPath === item.path ? "bold" : "normal",
+                        }}
+                        onClick={handleNav(item.action)}
+                    >
+                        {item.label}
+                    </a>
+                ))}
+                <a
+                    href={NAV_ACTIONS.github.url}
+                    style={{
+                        marginLeft: "auto",
+                        textDecoration: "none",
+                        color: "#333",
+                    }}
+                    onClick={handleNav(NAV_ACTIONS.github)}
+                >
+                    GitHub ↗
+                </a>
+            </nav>
+            <main style={{ padding: "1rem" }}>{children}</main>
+        </div>
+    );
+}

package/templates/react/src/components/Loading.tsx

@@ -0,0 +1,3 @@
+export function Loading() {
+    return <div style={{ padding: "2rem", textAlign: "center", color: "#999" }}>Loading…</div>;
+}

package/templates/react/src/components/Navigation.tsx

@@ -0,0 +1,51 @@
+import type { Action } from "@finesoft/front";
+import { makeExternalUrlAction, makeFlowAction } from "@finesoft/front";
+
+const links = [
+    { label: "Home", action: makeFlowAction("/"), path: "/" },
+    { label: "Search", action: makeFlowAction("/search"), path: "/search" },
+    { label: "About", action: makeFlowAction("/about"), path: "/about" },
+    {
+        label: "GitHub",
+        action: makeExternalUrlAction("https://github.com/nicepkg/finesoft"),
+        path: null,
+    },
+];
+
+interface NavigationProps {
+    currentPath?: string;
+    onAction?: (action: Action) => void;
+}
+
+export default function Navigation({ currentPath = "/", onAction }: NavigationProps) {
+    const handleNav = (action: Action) => (e: React.MouseEvent) => {
+        e.preventDefault();
+        onAction?.(action);
+    };
+
+    return (
+        <nav
+            style={{
+                display: "flex",
+                gap: "1rem",
+                padding: "1rem",
+                borderBottom: "1px solid #eee",
+            }}
+        >
+            {links.map((link) => (
+                <a
+                    key={link.label}
+                    href={link.action.url}
+                    style={{
+                        textDecoration: "none",
+                        color: link.path === currentPath ? "#007bff" : "#333",
+                        fontWeight: link.path === currentPath ? "bold" : "normal",
+                    }}
+                    onClick={handleNav(link.action)}
+                >
+                    {link.label}
+                </a>
+            ))}
+        </nav>
+    );
+}

package/templates/react/src/components/PageRenderer.tsx

@@ -0,0 +1,41 @@
+import type { Action } from "@finesoft/front";
+import type { AppPage } from "../lib/models/product";
+import About from "../pages/About";
+import Home from "../pages/Home";
+import NotFound from "../pages/NotFound";
+import ProductDetail from "../pages/ProductDetail";
+import Search from "../pages/Search";
+
+interface PageRendererProps {
+    page: AppPage;
+    onAction?: (action: Action) => void;
+}
+
+/** 根据 pageType 分发渲染对应组件 */
+export function PageRenderer({ page, onAction }: PageRendererProps) {
+    switch (page.pageType) {
+        case "home":
+            return <Home page={page} onAction={onAction} />;
+        case "product":
+            return <ProductDetail page={page} onAction={onAction} />;
+        case "search":
+            return <Search page={page} onAction={onAction} />;
+        case "about":
+            return <About page={page} onAction={onAction} />;
+        case "error":
+            return <NotFound page={page} onAction={onAction} />;
+        default:
+            return (
+                <NotFound
+                    page={{
+                        id: "unknown",
+                        pageType: "error",
+                        title: "Unknown Page",
+                        description: "Page not found",
+                        status: 404,
+                    }}
+                    onAction={onAction}
+                />
+            );
+    }
+}

package/templates/react/src/components/ProductCard.tsx

@@ -0,0 +1,35 @@
+import type { Action } from "@finesoft/front";
+import type { ProductItem } from "../lib/models/product";
+
+interface ProductCardProps {
+    item: ProductItem;
+    onAction?: (action: Action) => void;
+}
+
+export default function ProductCard({ item, onAction }: ProductCardProps) {
+    const handleClick = item.clickAction
+        ? (e: React.MouseEvent) => {
+              e.preventDefault();
+              onAction?.(item.clickAction!);
+          }
+        : undefined;
+
+    return (
+        <div
+            style={{
+                border: "1px solid #eee",
+                borderRadius: "8px",
+                padding: "1rem",
+                minWidth: "200px",
+            }}
+        >
+            <h3>{item.name}</h3>
+            <p style={{ color: "#007bff", fontWeight: "bold" }}>${item.price.toFixed(2)}</p>
+            {item.clickAction && "url" in item.clickAction && (
+                <a href={item.clickAction.url} onClick={handleClick}>
+                    View Details &rarr;
+                </a>
+            )}
+        </div>
+    );
+}

package/templates/react/src/lib/controllers/about.ts

@@ -0,0 +1,18 @@
+import { BaseController } from "@finesoft/front";
+import type { AboutPage } from "../models/product";
+
+export class AboutController extends BaseController<Record<string, string>, AboutPage> {
+    readonly intentId = "about";
+
+    execute(): AboutPage {
+        return {
+            id: "about",
+            pageType: "about",
+            title: "About",
+            description: "About Finesoft Front",
+            url: "/about",
+            content:
+                "Finesoft Front is a full-stack TypeScript framework with router, DI, middleware, SSR, and multi-platform deployment.",
+        };
+    }
+}

package/templates/react/src/lib/controllers/error.ts

@@ -0,0 +1,11 @@
+import type { ErrorPage } from "../models/product";
+
+export function getErrorPage(status: number, message: string): ErrorPage {
+    return {
+        id: "error",
+        pageType: "error",
+        title: `Error ${status}`,
+        description: message,
+        status,
+    };
+}

package/templates/react/src/lib/controllers/home.ts

@@ -0,0 +1,53 @@
+import { BaseController, makeFlowAction } from "@finesoft/front";
+import type { HomePage, ProductItem, ProductShelf } from "../models/product";
+
+const MOCK_PRODUCTS: ProductItem[] = [
+    {
+        id: "1",
+        itemType: "product",
+        name: "TypeScript Handbook",
+        price: 29.99,
+        imageUrl: "/img/ts.svg",
+        clickAction: makeFlowAction("/products/1"),
+    },
+    {
+        id: "2",
+        itemType: "product",
+        name: "Vite Starter Kit",
+        price: 19.99,
+        imageUrl: "/img/vite.svg",
+        clickAction: makeFlowAction("/products/2"),
+    },
+    {
+        id: "3",
+        itemType: "product",
+        name: "Hono Framework Guide",
+        price: 24.99,
+        imageUrl: "/img/hono.svg",
+        clickAction: makeFlowAction("/products/3"),
+    },
+];
+
+export class HomeController extends BaseController<Record<string, string>, HomePage> {
+    readonly intentId = "home";
+
+    execute(): HomePage {
+        const shelf: ProductShelf = {
+            id: "featured",
+            shelfType: "products",
+            title: "Featured Products",
+            isHorizontal: true,
+            seeAllAction: makeFlowAction("/search"),
+            items: MOCK_PRODUCTS,
+        };
+
+        return {
+            id: "home",
+            pageType: "home",
+            title: "Home",
+            description: "Welcome to Finesoft Front Demo",
+            url: "/",
+            shelves: [shelf],
+        };
+    }
+}

package/templates/react/src/lib/controllers/product-detail.ts

@@ -0,0 +1,52 @@
+import {
+    BaseController,
+    type Container,
+    DEP_KEYS,
+    type Logger,
+    type LoggerFactory,
+} from "@finesoft/front";
+import type { ProductPage } from "../models/product";
+
+export class ProductDetailController extends BaseController<{ id: string }, ProductPage> {
+    readonly intentId = "product-detail";
+
+    async execute(params: { id: string }, container: Container): Promise<ProductPage> {
+        const loggerFactory = container.resolve<LoggerFactory>(DEP_KEYS.LOGGER_FACTORY);
+        const log: Logger = loggerFactory.loggerFor("ProductDetailController");
+        log.info(`Loading product ${params.id}`);
+
+        // Simulated API fetch — replace with real HttpClient call
+        return {
+            id: `product-${params.id}`,
+            pageType: "product",
+            title: `Product ${params.id}`,
+            description: `Details for product ${params.id}`,
+            url: `/products/${params.id}`,
+            product: {
+                id: params.id,
+                name: `Product ${params.id}`,
+                price: 29.99,
+                description:
+                    "This is a demo product showcasing BaseController with typed params and DI container usage.",
+                imageUrl: `/img/product-${params.id}.svg`,
+            },
+        };
+    }
+
+    fallback(params: { id: string }, error: Error): ProductPage {
+        return {
+            id: `product-${params.id}`,
+            pageType: "product",
+            title: "Product Not Found",
+            description: error.message,
+            url: `/products/${params.id}`,
+            product: {
+                id: params.id,
+                name: "Unknown Product",
+                price: 0,
+                description: "Could not load product data.",
+                imageUrl: "/img/placeholder.svg",
+            },
+        };
+    }
+}

package/templates/react/src/lib/controllers/search.ts

@@ -0,0 +1,58 @@
+import { BaseController, makeFlowAction } from "@finesoft/front";
+import type { ProductItem, SearchPage } from "../models/product";
+
+const ALL_PRODUCTS: ProductItem[] = [
+    {
+        id: "1",
+        itemType: "product",
+        name: "TypeScript Handbook",
+        price: 29.99,
+        imageUrl: "/img/ts.svg",
+        clickAction: makeFlowAction("/products/1"),
+    },
+    {
+        id: "2",
+        itemType: "product",
+        name: "Vite Starter Kit",
+        price: 19.99,
+        imageUrl: "/img/vite.svg",
+        clickAction: makeFlowAction("/products/2"),
+    },
+    {
+        id: "3",
+        itemType: "product",
+        name: "Hono Framework Guide",
+        price: 24.99,
+        imageUrl: "/img/hono.svg",
+        clickAction: makeFlowAction("/products/3"),
+    },
+    {
+        id: "4",
+        itemType: "product",
+        name: "SSR Deep Dive",
+        price: 34.99,
+        imageUrl: "/img/ssr.svg",
+        clickAction: makeFlowAction("/products/4"),
+    },
+];
+
+export class SearchController extends BaseController<{ q?: string }, SearchPage> {
+    readonly intentId = "search";
+
+    execute(params: { q?: string }): SearchPage {
+        const query = params.q ?? "";
+        const results = query
+            ? ALL_PRODUCTS.filter((p) => p.name.toLowerCase().includes(query.toLowerCase()))
+            : ALL_PRODUCTS;
+
+        return {
+            id: "search",
+            pageType: "search",
+            title: query ? `Search: ${query}` : "All Products",
+            description: `${results.length} result(s)`,
+            url: "/search",
+            query,
+            results,
+        };
+    }
+}