flu-cli-core 1.0.0

package/dist/upgrade_snippets-XFR7Q444.js

@@ -0,0 +1,8 @@
+import {
+  checkSnippetsVersion,
+  upgradeSnippets
+} from "./chunk-SW6YDKXI.js";
+export {
+  checkSnippetsVersion,
+  upgradeSnippets
+};

package/locales/en-US.json

@@ -0,0 +1,59 @@
+{
+  "cli.description": "🚀 Flutter MVVM Scaffolding Tool",
+  "cmd.new.desc": "Create Flutter project with real-time template preview",
+  "cmd.new.opt.template": "Template type: lite, modular, clean",
+  "cmd.new.opt.state": "State manager: default, provider, getx",
+  "cmd.new.opt.dir": "Project storage directory",
+  "cmd.new.opt.no_cache": "Do not use cache, force pull from Git",
+  "cmd.new.opt.remote": "Use remote Gitee templates (default uses local)",
+  "cmd.sync.desc": "Sync the latest standard code snippets to the current project",
+  "cmd.add.desc": "Add Flutter code component (page/p, widget/w, component/c, ...)",
+  "cmd.add.opt.feature": "Target feature module (modular/clean mode only)",
+  "cmd.add.opt.stateful": "Create StatefulWidget (StatelessWidget by default)",
+  "cmd.add.opt.stateless": "Force create StatelessWidget (even if with ViewModel, not recommended)",
+  "cmd.add.opt.list_page": "Create list page (BaseListPage)",
+  "cmd.add.opt.no_vm": "Do not generate ViewModel (page type only)",
+  "cmd.add.opt.json": "Generate from JSON file (model type only)",
+  "cmd.add.opt.list": "View supported types list",
+  "cmd.templates.desc": "View all templates or specific template details",
+  "cmd.update.desc": "Update template cache",
+  "cmd.update.opt.force": "Force refresh and clean untracked files",
+  "cmd.cache.desc": "Cache management (action: clean)",
+  "cmd.assets.desc": "Configure app icon and splash screen",
+  "cmd.template.desc": "Manage custom project templates",
+  "cmd.template.list.desc": "List all templates",
+  "cmd.template.add.desc": "Add custom template (id: unique ID, source: Git URL or local path)",
+  "cmd.template.add.opt.local": "Add local template (source is a path)",
+  "cmd.template.add.opt.name": "Display name",
+  "cmd.template.add.opt.branch": "Git branch (default is main)",
+  "cmd.template.add.opt.desc": "Description information",
+  "cmd.template.add.opt.force": "Overwrite existing template",
+  "cmd.template.remove.desc": "Delete custom template",
+  "cmd.completion.desc": "Generate Shell auto-completion script (bash/zsh)",
+  "cmd.config.desc": "Manage project generation config (.flu-cli.json)",
+  "cmd.config.init.desc": "Initialize config file (based on current project structure)",
+  "assets.intro": "🎨 Configure App Assets (Icon & Splash)",
+  "assets.setup_icon": "Do you want to set up an App Icon?",
+  "assets.icon_path": "Enter icon path (suggested 1024x1024 PNG)",
+  "assets.setup_splash": "Do you want to set up a Splash Screen?",
+  "assets.splash_logo": "Enter Splash Logo path",
+  "assets.bg_color": "Enter Splash background color (Hex)",
+  "assets.use_bg_image": "Use a background image for Splash?",
+  "assets.bg_image_path": "Enter background image path",
+  "assets.setup_dark": "Configure Splash for Dark Mode?",
+  "assets.dark_bg_color": "Enter Dark Mode background color (Hex)",
+  "assets.use_dark_logo": "Use a separate Logo for Dark Mode?",
+  "assets.dark_logo_path": "Enter Dark Mode Logo path",
+  "assets.no_assets": "No assets selected, operation ended",
+  "assets.configuring": "Configuring assets...",
+  "assets.success": "✓ Assets configured successfully",
+  "assets.done": "✨ App assets mapping completed!",
+  "assets.failed": "Failed to configure assets",
+  "assets.error_outro": "❌ Error occurred during configuration, please check logs",
+  "assets.not_flutter": "pubspec.yaml not found. Please run this command in a Flutter project root.",
+  "common.cancel": "Operation cancelled",
+  "common.bye": "Goodbye",
+  "snippets.sync_success": "✅ Code snippets synced successfully!",
+  "snippets.detect_config": "ℹ️  Project config detected, filtering snippets...",
+  "snippets.applied_filter": "Architecture-aware filtering applied (BasePage: {basePage}, ViewModel: {viewModel})"
+}

package/locales/zh-CN.json

@@ -0,0 +1,59 @@
+{
+  "cli.description": "🚀 Flutter MVVM 脚手架工具",
+  "cmd.new.desc": "创建 Flutter 项目（实时模板预览）",
+  "cmd.new.opt.template": "模板类型: lite, modular, clean",
+  "cmd.new.opt.state": "状态管理器: default, provider, getx",
+  "cmd.new.opt.dir": "项目存放目录",
+  "cmd.new.opt.no_cache": "不使用缓存，强制从 Git 拉取",
+  "cmd.new.opt.remote": "使用远程 Gitee 模板（默认使用本地模板）",
+  "cmd.sync.desc": "同步最新版本的标准代码片段到当前项目",
+  "cmd.add.desc": "添加 Flutter 代码组件 (page/p, widget/w, component/c, ...)",
+  "cmd.add.opt.feature": "所属功能模块（仅 modular/clean 模式）",
+  "cmd.add.opt.stateful": "创建 StatefulWidget（默认 StatelessWidget）",
+  "cmd.add.opt.stateless": "强制创建 StatelessWidget（即使有 ViewModel，不推荐）",
+  "cmd.add.opt.list_page": "创建列表页 (BaseListPage)",
+  "cmd.add.opt.no_vm": "不生成 ViewModel（仅 page 类型）",
+  "cmd.add.opt.json": "从 JSON 文件生成（仅 model 类型）",
+  "cmd.add.opt.list": "查看支持的类型列表",
+  "cmd.templates.desc": "查看所有模板或指定模板详情",
+  "cmd.update.desc": "更新模板缓存",
+  "cmd.update.opt.force": "强制刷新并清理未跟踪文件",
+  "cmd.cache.desc": "缓存管理 (action: clean)",
+  "cmd.assets.desc": "配置应用图标和启动图",
+  "cmd.template.desc": "管理自定义项目模板",
+  "cmd.template.list.desc": "列出所有模板",
+  "cmd.template.add.desc": "添加自定义模板 (id: 唯一标识, source: Git URL 或本地路径)",
+  "cmd.template.add.opt.local": "添加本地模板 (source 为路径)",
+  "cmd.template.add.opt.name": "显示名称",
+  "cmd.template.add.opt.branch": "Git 分支 (默认 main)",
+  "cmd.template.add.opt.desc": "描述信息",
+  "cmd.template.add.opt.force": "覆盖已存在的模板",
+  "cmd.template.remove.desc": "删除自定义模板",
+  "cmd.completion.desc": "生成 Shell 自动补全脚本 (bash/zsh)",
+  "cmd.config.desc": "管理项目生成配置 (.flu-cli.json)",
+  "cmd.config.init.desc": "初始化配置文件 (基于当前项目结构)",
+  "assets.intro": "🎨 配置应用资源 (图标 & 启动图)",
+  "assets.setup_icon": "是否要设置应用图标 (App Icon)?",
+  "assets.icon_path": "请输入图标路径 (建议 1024x1024 PNG)",
+  "assets.setup_splash": "是否要设置启动图 (Splash Screen)?",
+  "assets.splash_logo": "请输入启动页 Logo 路径",
+  "assets.bg_color": "请输入启动页背景颜色 (Hex)",
+  "assets.use_bg_image": "是否使用启动页背景图?",
+  "assets.bg_image_path": "请输入背景图路径",
+  "assets.setup_dark": "是否配置暗黑模式下的启动页?",
+  "assets.dark_bg_color": "请输入暗黑模式背景颜色 (Hex)",
+  "assets.use_dark_logo": "是否使用独立的暗黑模式 Logo?",
+  "assets.dark_logo_path": "请输入暗黑模式 Logo 路径",
+  "assets.no_assets": "未选择任何资源，操作结束",
+  "assets.configuring": "正在配置资源...",
+  "assets.success": "✓ 资源配置成功",
+  "assets.done": "✨ 应用资源映射完成！",
+  "assets.failed": "资源配置失败",
+  "assets.error_outro": "❌ 配置过程中出现错误，请检查日志",
+  "assets.not_flutter": "未检测到 pubspec.yaml，请在 Flutter 项目根目录下运行此命令",
+  "common.cancel": "操作已取消",
+  "common.bye": "再见",
+  "snippets.sync_success": "✅ 代码片段同步成功！",
+  "snippets.detect_config": "ℹ️  检测到项目配置，正在按需过滤代码片段...",
+  "snippets.applied_filter": "已应用架构感知过滤 (BasePage: {basePage}, ViewModel: {viewModel})"
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "flu-cli-core",
+    "version": "1.0.0",
+    "description": "Core logic for flu-cli",
+    "main": "dist/index.cjs",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "files": [
+        "dist",
+        "templates",
+        "locales"
+    ],
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+    },
+    "keywords": [
+        "flutter",
+        "cli",
+        "core"
+    ],
+    "author": "火叶工作室",
+    "license": "MIT",
+    "dependencies": {
+        "chalk": "^4.1.2",
+        "fs-extra": "^11.2.0",
+        "handlebars": "^4.7.8",
+        "json5": "^2.2.3",
+        "simple-git": "^3.20.0"
+    },
+    "devDependencies": {
+        "@types/chalk": "^0.4.31",
+        "@types/fs-extra": "^11.0.4",
+        "@types/handlebars": "^4.0.40",
+        "@types/node": "^20.19.25",
+        "tsup": "^8.0.1",
+        "typescript": "^5.3.3"
+    }
+}

package/templates/README.md

@@ -0,0 +1,129 @@
+# Flu-CLI 模板与基础设施资源
+
+此目录包含 CLI 核心引擎使用的 **基础资源**。在 V6.0 架构中，这些资源分为 **“骨架配套”** 与 **“高级增强”** 两部分。
+
+## 📂 目录结构
+
+```
+packages/core/templates/
+├── core_files/           # 🔹 高级增强 (Enrichment Modules)
+│   ├── base/             # 统一的 MVVM 基类 (BasePage, BaseViewModel)
+│   ├── network/          # 统一的网络封装 (Dio, ApiResponse, HttpUtil)
+│   ├── router/           # 统一的路由工具与常量模板
+│   ├── theme/            # 预置的状态视图主题
+│   └── utils/            # 🔹 核心工具类 (Loading, Toast, RequestHelper)
+│
+├── snippets/             # 🔹 生成代码片段 (Smart Snippets)
+│   ├── pages/            # Page 与 ViewModel 模板逻辑
+│   ├── widgets/          # 各种 Widget 变体
+│   └── ...
+│
+└── README.md             # 本文档
+```
+
+---
+
+## 🏗️ 架构总览
+
+Flu-CLI 采用 **"双层架构"** 设计，确保所有架构风格的项目都拥有统一、高质量的基础设施。
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              应用层（架构层 - 可变）                     │
+├─────────────────────────────────────────────────────────┤
+│  Lite: 平房（简单）                                      │
+│    lib/pages/          # 页面                           │
+│    lib/viewmodels/     # ViewModel                      │
+│    lib/services/       # 服务                           │
+│    lib/models/         # 模型                           │
+├─────────────────────────────────────────────────────────┤
+│  Modular: 公寓（模块化）                                 │
+│    lib/features/home/                                   │
+│      ├── pages/                                         │
+│      ├── viewmodels/                                    │
+│      ├── services/                                      │
+│      └── models/                                        │
+├─────────────────────────────────────────────────────────┤
+│  Clean: 摩天大楼（复杂）                                 │
+│    lib/features/home/                                   │
+│      ├── presentation/  # 表现层                        │
+│      ├── domain/        # 领域层                        │
+│      └── data/          # 数据层                        │
+└─────────────────────────────────────────────────────────┘
+                           ▲
+                           │ 都依赖
+                           │
+┌──────────────────────────┴──────────────────────────────┐
+│           基础设施层（统一维护 - 不变）                  │
+├─────────────────────────────────────────────────────────┤
+│  lib/core/                                              │
+│    ├── base/              # MVVM 基础组件               │
+│    │   ├── base_viewmodel.dart                         │
+│    │   ├── base_page.dart                              │
+│    │   ├── base_list_viewmodel.dart                    │
+│    │   ├── base_list_page.dart                         │
+│    │   └── theme/status_views_theme.dart               │
+│    │                                                     │
+│    ├── network/           # 网络层（可选）              │
+│    │   └── http_util.dart                              │
+│    │                                                     │
+│    ├── router/            # 路由系统（可选）            │
+│    │   ├── app_routes.dart                             │
+│    │   └── navigator_util.dart                         │
+│    │                                                     │
+│    ├── utils/             # 工具类（零依赖）            │
+│    │   ├── loading_util.dart                           │
+│    │   ├── toast_util.dart                             │
+│    │   └── request_helper.dart                         │
+│    │                                                     │
+│    ├── config/            # 应用配置                    │
+│    │   └── app_config.dart                             │
+│    │                                                     │
+│    └── storage/           # 本地存储（可选）            │
+│        └── storage_util.dart                            │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 核心理念
+
+- **应用层可变**：根据项目复杂度选择 Lite / Modular / Clean 架构风格
+- **基础设施不变**：所有架构风格共享同一套高质量的 `lib/core/` 基础设施
+- **依赖向下**：应用层依赖基础设施层，确保架构清晰
+
+---
+
+## 🚀 核心设计：Skeleton + Enrichment
+
+从 V6.0 开始，我们采用了 **“骨架 + 插件化增强”** 的模式。
+
+### 1. Skeleton (骨架)
+
+即外层提供的 `template_lite`, `template_modular` 等项目基础包。它们只包含最基础的、编译通过的 Flutter 代码。
+
+### 2. Enrichment (增强) - 位于 `core_files/`
+
+这些是 CLI 动态注入的“水电系统”。即便是一个纯净的 Flutter 项目，通过 CLI 的 `NetworkEnrichTask`，也可以一秒钟注入我们标准化的网络层。
+
+- **Base 层**：所有模板（Lite/Modular/Clean）使用完全相同的 `BasePage` 和 `BaseViewModel`。
+- **Network 层**：由 CLI 任务驱动，自动处理依赖注入、代码复制与示例代码生成。
+- **Router 层**：包含动态路由扫描所需的基础骨架（如自动注入业务路由的 TODO 标记）。
+
+## 📝 开发者指南
+
+### 修改基础设施
+
+如果你想升级所有生成项目的 `BasePage` 逻辑：
+
+1. 修改 `core_files/base/base_page.dart.template`。
+2. 运行 `npm run build` 以确保 CLI 索引更新。
+3. 下次执行 `flu-cli new` 时，所有新项目都将获得更新。
+
+### 修改代码片段
+
+代码片段位于 `snippets/` 目录下，主要服务于 `generate page` 等文件级生成器。
+
+- 修改这些文件将直接影响到 `flu-cli g` 命令的输出效果。
+
+---
+
+> **架构哲学**：骨架定义项目的“形状”，而基础设施定义项目的“灵魂”。Flu-CLI 确保了所有形状的项目都拥有同样健壮的灵魂。 🚀

package/templates/core_files/base/base_list_page.dart.template

@@ -0,0 +1,225 @@
+import 'package:flutter/material.dart';
+
+import '../theme/index.dart';
+import 'base_list_viewmodel.dart';
+import 'base_page.dart';
+
+/// 列表页面基类：在 BasePage 基础上扩展列表体与触底加载能力
+abstract class BaseListPage<T, VM extends BaseListViewModel<T>>
+    extends BasePage<VM> {
+  /// 构造函数
+  const BaseListPage({super.key});
+
+  @override
+  State<BaseListPage<T, VM>> createState();
+}
+
+/// 列表页面State基类 - 用户继承此类
+abstract class BaseListPageState<T, VM extends BaseListViewModel<T>,
+    W extends BaseListPage<T, VM>> extends BasePageState<VM, W> {
+  late final ScrollController _controller;
+
+  // ==================== 子类必须实现 ====================
+
+  /// 渲染单个条目
+  Widget buildItem(BuildContext context, T item, int index);
+
+  // ==================== 可选重写的列表配置 ====================
+
+  /// 构建列表容器（可选）
+  ///
+  /// **返回 null**：使用默认 ListView.builder
+  ///
+  /// **自定义列表容器**：
+  /// - 请使用 `scrollController` 以支持上拉加载
+  /// - 原生刷新功能仍然生效（除非 `enableRefresh = false`）
+  ///
+  /// 示例：
+  /// ```dart
+  /// @override
+  /// Widget buildListWidget(BuildContext context) {
+  ///   return GridView.builder(
+  ///     controller: scrollController,  // 必须绑定！
+  ///     itemCount: viewModel.items.length,
+  ///     itemBuilder: (ctx, i) => buildItem(ctx, viewModel.items[i], i),
+  ///   );
+  /// }
+  /// ```
+  Widget? buildListWidget(BuildContext context) => null;
+
+  /// 构建列表 Header（可选）
+  Widget? buildHeader(BuildContext context) => null;
+
+  /// 自定义"加载更多"视图（可选）
+  ///
+  /// @param hasMore 是否还有更多数据
+  /// @param isLoadingMore 是否正在加载
+  ///
+  /// 返回 null 使用默认样式
+  Widget? loadMoreFooterBuilder(
+    BuildContext context,
+    bool hasMore,
+    bool isLoadingMore,
+  ) =>
+      null;
+
+  /// 刷新容器包裹（用于接入第三方刷新库）
+  /// 默认使用 RefreshIndicator，可重写此方法接入第三方库（如 pull_to_refresh）
+  Widget refreshWrapperBuilder(BuildContext context, Widget child) {
+    if (!enableRefresh) return child;
+    return RefreshIndicator(
+      onRefresh: onRefreshCallback,
+      child: child,
+    );
+  }
+
+  /// 列表体外层包裹
+  /// 用于添加 Scrollbar、NotificationListener、吸顶 Header 等额外结构
+  Widget listWrapperBuilder(BuildContext context, Widget list) => list;
+
+  /// 提供自定义 ScrollController
+  /// 返回 null 使用内部控制器；非空时由外部管理其生命周期
+  ScrollController? provideScrollController(BuildContext context) => null;
+
+  /// 下拉刷新回调（供第三方库使用）
+  Future<void> onRefreshCallback() async {
+    await viewModel.refreshData();
+  }
+
+  /// 上拉加载回调（供第三方库使用）
+  Future<void> onLoadMoreCallback() async {
+    await viewModel.loadMore();
+  }
+
+  /// 滚动事件回调
+  /// 可用于自定义触底策略或滚动埋点
+  void onScroll(BuildContext context, ScrollPosition position) {}
+
+  /// 是否启用自动触底加载
+  bool get enableAutoLoadMore => true;
+
+  /// 触底阈值
+  double get loadMoreThreshold => 100;
+
+  /// 是否启用下拉刷新
+  bool get enableRefresh => false;
+
+  /// 列表页 默认关闭 safeAreaBottom
+  @override
+  bool get safeAreaBottom => false;
+
+  // ==================== 内部实现 ====================
+
+  /// 页面是否为空：依据列表数据判断
+  @override
+  bool get isEmptyContent => viewModel.items.isEmpty;
+
+  /// 内部 ScrollController（供子类使用）
+  /// 当重写 buildListWidget 时，请绑定此 controller 以支持上拉加载
+  @protected
+  ScrollController get scrollController => _controller;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = provideScrollController(context) ?? ScrollController();
+    _controller.addListener(_onScroll);
+  }
+
+  @override
+  void dispose() {
+    _controller.removeListener(_onScroll);
+    if (provideScrollController(context) == null) {
+      _controller.dispose();
+    }
+    super.dispose();
+  }
+
+  /// 触底检测：接近底部时尝试加载更多
+  void _onScroll() {
+    onScroll(context, _controller.position);
+    if (!enableAutoLoadMore) return;
+    if (!_controller.hasClients) return;
+    final max = _controller.position.maxScrollExtent;
+    final offset = _controller.offset;
+    if (offset >= max - loadMoreThreshold) {
+      onLoadMoreCallback();
+    }
+  }
+
+  /// 构建成功态内容：列表 + 刷新包裹
+  @override
+  Widget buildContent(BuildContext context) {
+    Widget body = _buildListWidget();
+    body = refreshWrapperBuilder(context, body);
+    return body;
+  }
+
+  /// 构建列表视图：支持自定义或默认实现
+  Widget _buildListWidget() {
+    final vm = viewModel;
+    final theme = Theme.of(context).extension<StatusViewsTheme>();
+    final list = buildListWidget(context) ??
+        ListView.builder(
+          controller: _controller,
+          itemCount: vm.items.length + 1,
+          itemBuilder: (ctx, i) {
+            // 支持自定义 Header
+            if (i == 0) {
+              final header = buildHeader(ctx);
+              if (header != null) return header;
+            }
+
+            final last = i == vm.items.length;
+            if (last) {
+              // 加载失败：显示重试按钮
+              if (vm.loadMoreFailed) {
+                return Padding(
+                  padding: const EdgeInsets.all(16),
+                  child: Column(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Text(
+                        vm.loadMoreError?.toString() ?? '加载更多失败',
+                        style: const TextStyle(color: Colors.red),
+                      ),
+                      const SizedBox(height: 8),
+                      ElevatedButton(
+                        onPressed: vm.loadMore,
+                        child: const Text('重试'),
+                      ),
+                    ],
+                  ),
+                );
+              }
+
+              // 用户自定义加载视图
+              final customFooter = loadMoreFooterBuilder(
+                ctx,
+                vm.hasMore,
+                vm.isLoadingMore,
+              );
+              if (customFooter != null) return customFooter;
+
+              // 主题自定义加载视图
+              final globalFooter =
+                  theme?.loadMoreBuilder?.call(ctx, vm.hasMore);
+              if (globalFooter != null) return globalFooter;
+
+              // 默认加载视图
+              return Padding(
+                padding: const EdgeInsets.all(16),
+                child: Center(
+                  child: vm.hasMore
+                      ? const CircularProgressIndicator()
+                      : const Text('没有更多了'),
+                ),
+              );
+            }
+            final item = vm.items[i];
+            return buildItem(ctx, item, i);
+          },
+        );
+    return listWrapperBuilder(context, list);
+  }
+}