feat: add configuration tooling commands

Author: lizy-coding

CONFIGURATION_STRATEGY.md

@@ -37,7 +37,7 @@ Behavior:
 - Does not enforce layers/modules unless they are declared
 
 Use this level when the user wants a quick signal and has not agreed on project
-architecture boundaries yet.
+architecture boundaries yet. No YAML file is required.
 
 ### Level 1: Basic Project Config
 
@@ -83,6 +83,13 @@ rules:
 
 Use this level when teams want stable thresholds or custom excludes.
 
+Create it with:
+
+```bash
+flutterguard init
+flutterguard config doctor
+```
+
 ### Level 2: CI Gate Config
 
 Best for pull requests and release checks.
@@ -96,11 +103,18 @@ Recommended policy:
 - Start with `--fail-on high`
 - Add `--min-score 80` once the baseline is clean enough
 - Avoid `--fail-on low` early in adoption because it can create noisy rollouts
+- Run `flutterguard config doctor` before adding CI gates
 
 ### Level 3: Architecture Config
 
 Best when the project has agreed boundaries.
 
+Create a starter template with:
+
+```bash
+flutterguard init --with-architecture
+```
+
 ```yaml
 architecture:
   layers:
@@ -154,9 +168,9 @@ CLI responses should stay short and operational:
 Avoid long explanations in command output. Point to this guide when the user
 needs examples or architecture detail.
 
-## Future Enhancements
+## Config Tooling
 
-The next usability improvements should be command-level helpers:
+The core configuration helpers are available as CLI commands:
 
 - `flutterguard init`: write a minimal `flutterguard.yaml`
 - `flutterguard init --with-architecture`: write a layered/module template
@@ -165,4 +179,4 @@ The next usability improvements should be command-level helpers:
   architecture overlap
 
 These commands are preferable to adding more prose to `scan`, because they keep
-the scan output focused while still making configuration discoverable.
+scan output focused while still making configuration discoverable.

README.md

@@ -143,6 +143,13 @@ flutterguard --help
 # Scan the current directory
 flutterguard scan
 
+# Create and validate a starter config
+flutterguard init
+flutterguard config doctor
+
+# Inspect the merged effective config
+flutterguard config print
+
 # Scan a specific project
 flutterguard scan ./my_flutter_app          # macOS / Linux
 flutterguard scan .\my_flutter_app          # Windows
@@ -174,6 +181,10 @@ Commands:
 | Command | Description |
 |---------|-------------|
 | `flutterguard scan [<path>]` | Scan a project (path defaults to current directory) |
+| `flutterguard init` | Create a starter `flutterguard.yaml` |
+| `flutterguard init --with-architecture` | Create config with architecture layer/module templates |
+| `flutterguard config print` | Print the merged effective configuration |
+| `flutterguard config doctor` | Validate config, globs, and architecture references |
 | `flutterguard --help` / `-h` | Show usage |
 | `flutterguard --version` / `-V` | Show version |
 
@@ -218,9 +229,10 @@ Create `flutterguard.yaml` in your project root.
 Recommended strategy:
 
 1. Start with zero config: `flutterguard scan`.
-2. Add a basic config only when you need custom thresholds or excludes.
-3. Add CI gates with `--format json --fail-on high --min-score 80`.
-4. Add architecture layers/modules only after project boundaries are agreed.
+2. Run `flutterguard init` when you need custom thresholds or excludes.
+3. Use `flutterguard config print` to inspect merged defaults.
+4. Use `flutterguard config doctor` before enabling CI gates.
+5. Add architecture layers/modules only after project boundaries are agreed.
 
 For the full decision model, see [Configuration Strategy](CONFIGURATION_STRATEGY.md).
 

README.zh.md

@@ -142,6 +142,13 @@ flutterguard --help
 # 扫描当前目录
 flutterguard scan
 
+# 创建并检查基础配置
+flutterguard init
+flutterguard config doctor
+
+# 查看合并后的有效配置
+flutterguard config print
+
 # 扫描指定项目
 flutterguard scan ./my_flutter_app          # macOS / Linux
 flutterguard scan .\my_flutter_app          # Windows
@@ -173,6 +180,10 @@ flutterguard scan examples/scan_demo
 | 命令 | 说明 |
 |------|------|
 | `flutterguard scan [<path>]` | 扫描项目（路径默认为当前目录） |
+| `flutterguard init` | 创建基础 `flutterguard.yaml` |
+| `flutterguard init --with-architecture` | 创建包含架构层/模块模板的配置 |
+| `flutterguard config print` | 输出合并后的有效配置 |
+| `flutterguard config doctor` | 检查配置、glob 和架构引用 |
 | `flutterguard --help` / `-h` | 显示帮助 |
 | `flutterguard --version` / `-V` | 显示版本 |
 
@@ -217,9 +228,10 @@ FlutterGuard 从当前目录向上遍历，自动发现项目根目录（查找
 推荐策略：
 
 1. 先零配置运行：`flutterguard scan`。
-2. 只有需要自定义阈值或排除文件时，再添加基础配置。
-3. CI 场景使用 `--format json --fail-on high --min-score 80`。
-4. 只有项目边界已经明确时，再添加 architecture layers/modules。
+2. 需要自定义阈值或排除文件时，运行 `flutterguard init`。
+3. 使用 `flutterguard config print` 查看合并后的默认值。
+4. 启用 CI 门禁前先运行 `flutterguard config doctor`。
+5. 只有项目边界已经明确时，再添加 architecture layers/modules。
 
 完整决策模型见 [配置策略](CONFIGURATION_STRATEGY.md)。
 

packages/flutterguard_cli/README.md

@@ -16,6 +16,10 @@ dart pub global activate flutterguard_cli
 # Scan a Flutter project
 flutterguard scan -p /path/to/flutter_project
 
+# Create and validate a starter config
+flutterguard init
+flutterguard config doctor
+
 # JSON output with CI gate
 flutterguard scan -p . --format json --fail-on high --min-score 80
 ```
@@ -42,8 +46,10 @@ flutterguard scan -p . --format json --fail-on high --min-score 80
 
 Create `flutterguard.yaml` in your project root:
 
-Start without config, then add YAML only when you need custom thresholds,
-excludes, CI gates, or explicit architecture boundaries.
+Start without config, then run `flutterguard init` only when you need custom
+thresholds, excludes, CI gates, or explicit architecture boundaries. Use
+`flutterguard config print` to inspect merged defaults and
+`flutterguard config doctor` before enabling CI gates.
 
 ```yaml
 rules:
@@ -73,14 +79,18 @@ If no config file exists, defaults are used (all default rules enabled, no archi
 ## CLI Reference
 
 ```
-flutterguard scan [options]
+flutterguard scan [<path>] [options]
   -p, --path       Project path (default: .)
   -c, --config     Config file (default: flutterguard.yaml)
   -f, --format     table | json (default: table)
   -o, --output     Output directory (default: .flutterguard)
   -v, --verbose    Show detailed context
   --fail-on        CI gate: none | high | medium | low
   --min-score      Minimum score threshold 0-100
+
+flutterguard init [--with-architecture] [--force]
+flutterguard config print
+flutterguard config doctor
 ```
 
 Exit codes: `0` success, `1` CI gate failed, `2` scan error.