feat: init feature set and testsuite

AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md
+
+## Project Overview
+
+This repository contains protobuf definitions and generated code for TuiHub platform. It serves as the central API contract repository that supports multiple programming languages (Go, JavaScript/TypeScript, Rust, C#, and Dart).
+
+**Key Architecture:**
+- **Proto definitions**: Located in `proto/` directory
+- **Generated code**: Multiple language targets in `pkg/`, `node/`, `src/`, `Assets/src/`, and `lib/`
+- **Services**: Four main service types:
+  - `LibrarianSephirahService`: Core service for the platform
+  - `LibrarianPorterService`: Integration service
+  - `LibrarianMinerService`: Data mining service
+  - `LibrarianSentinelService`: Monitoring service
+- **Build tool**: Uses [buf](https://buf.build) for proto management and code generation
+
+**Important**: Generated code directories (`pkg/`, `node/`, `src/`, `Assets/src/`, `lib/`) should NOT be directly edited. Always modify proto files in `proto/` and regenerate.
+
+## Setup Commands
+
+### Prerequisites
+
+Install required tools:
+```bash
+# buf CLI
+# Install manually
+
+# Optional: Install all language plugins
+make install-plugins
+```
+
+### Quick Start
+
+```bash
+# Install dependencies for all languages
+npm install          # JavaScript/TypeScript
+go mod tidy         # Go
+cargo check         # Rust
+dart pub get        # Dart
+```
+
+## Build Instructions
+
+### Lint Proto Files
+
+```bash
+make buf-lint
+```
+
+### Generate Code Locally (Optional)
+
+```bash
+make generate
+```
+
+### Individual Language Builds
+
+```bash
+# Go
+make go
+
+# Rust (with full proto features)
+make rust
+cargo check --features proto_full
+
+# Dart
+make dart
+dart analyze
+
+# JavaScript/TypeScript
+npm install
+```
+
+## Testing Instructions
+
+### Proto Validation
+
+```bash
+make check
+```
+
+### Language-Specific Tests
+
+```bash
+# Go
+go test ./pkg/...
+
+# Rust
+cargo test
+
+# Dart
+dart test
+```
+
+## Code Style Guidelines
+
+### Proto Files
+- **Location**: All `.proto` files must be in `proto/` directory
+- **Versioning**: Use versioned paths (e.g., `v1/`)
+- **Naming**: Follow standard protobuf naming conventions
+  - Services: PascalCase with "Service" suffix (e.g., `LibrarianSephirahService`)
+  - Messages: PascalCase (e.g., `GetUserRequest`)
+  - Fields: snake_case (e.g., `user_id`)
+- **Comments**: Use line comments (`//`) for documentation
+- **Validation**: Use buf.build/bufbuild/protovalidate for field validation
+
+### Linting Rules
+- Uses `buf lint` with STANDARD ruleset
+- Exceptions:
+  - `PACKAGE_VERSION_SUFFIX` allowed for `proto/errors/errors.proto`
+- Breaking change detection enabled (FILE strategy)
+
+### Generated Code
+- **Never edit generated code directly**
+- Generated code directories are cleaned and regenerated on each build
+- If you need changes, modify the proto files
+
+## Development Workflow
+
+### Adding New Proto Definitions
+
+1. Create or modify `.proto` files in appropriate `proto/` subdirectory
+2. Run `buf format -w` to format
+3. Run `buf lint` to validate
+4. Test locally with `make generate` (optional)
+5. Commit proto files only (CI will handle generation)
+
+### Modifying Existing APIs
+
+1. Check for breaking changes:
+   ```bash
+   buf breaking --against '.git#branch=master'
+   ```
+2. If breaking changes are necessary, document them in CHANGELOG.md
+3. Update proto files following the same workflow as new definitions
+
+### PR Guidelines
+
+- **Title format**: `[scope] Brief description`
+  - Scope examples: `proto`, `docs`, `build`, `ci`
+- **Always run before committing**:
+  ```bash
+  buf format -w
+  buf lint
+  ```
+- **Do NOT commit**:
+  - Generated code (it will be auto-generated by CI)
+  - Build artifacts from `target/` directory
+  - IDE-specific files
+
+### Commit Message Format
+
+Follow conventional commits:
+- `feat(proto)`: New proto definitions
+- `fix(proto)`: Bug fixes in proto
+- `docs`: Documentation updates
+- `build`: Build system changes
+- `ci`: CI configuration changes
+
+## Directory Structure
+
+```
+proto/                    # Source proto definitions (EDIT HERE)
+├── errors/              # Error definitions
+└── librarian/           # Main service definitions
+    ├── miner/v1/        # Miner service
+    ├── porter/v1/       # Porter service
+    ├── sentinel/v1/     # Sentinel service
+    ├── sephirah/v1/     # Sephirah service
+    └── v1/              # Common definitions
+
+Generated Code (DO NOT EDIT):
+├── pkg/                 # Go
+├── node/                # JavaScript/TypeScript
+├── src/                 # Rust
+├── Assets/src/          # C#
+└── lib/                 # Dart
+
+Configuration:
+├── buf.yaml             # Buf configuration
+├── buf.gen.yaml         # Code generation config
+├── Makefile             # Build automation
+└── docs/                # Documentation
+```
+
+## Documentation
+
+- **Generated docs**: https://tuihub.github.io/protos
+- **Proto files**: [proto/](proto/)
+- **Feature Sets**: [docs/feature_sets/](docs/feature_sets/)
+
+## Useful Commands Reference
+
+```bash
+# Clean generated code
+make clean
+
+# Full regeneration
+make clean && make generate
+
+# Check specific language
+make go     # Go modules
+make rust   # Rust check
+make dart   # Dart analysis
+
+# View generated OpenAPI
+cat docs/openapi.json
+```
+
+## Troubleshooting
+
+### "buf: command not found"
+Install buf: https://buf.build/docs/installation
+
+### Generated code conflicts
+```bash
+make clean
+make generate
+```
+
+### Lint failures
+```bash
+# Auto-fix formatting
+buf format -w
+
+# View detailed lint errors
+buf lint --error-format=json
+```
+
+### Breaking changes detected
+Review changes carefully. If intentional, document in CHANGELOG.md. Breaking changes should be rare and well-justified.
+
+## CI/CD Behavior
+
+- **On push**: CI automatically generates code for all languages
+- **On PR**: Linting and breaking change detection runs
+- **Documentation**: Auto-generated and deployed to GitHub Pages
+- **Releases**: Managed by release-please bot
+
+## Additional Notes
+
+- This is a polyglot repository supporting 5+ languages
+- Generated code is committed to the repository for easy consumption
+- Each language has its own package distribution method (see README.md)
+- Feature Sets documentation uses Gherkin format for behavior specification

Makefile

@@ -11,7 +11,7 @@ install-plugins:
 	cargo install --locked protoc-gen-prost-crate
 	dart pub global activate protoc_plugin 22.5.0
 
-generate: clean buf go rust dart
+generate: clean buf go rust dart dependency-tree
 
 check: buf-lint go rust dart
 
@@ -24,6 +24,9 @@ buf-lint:
 buf-generate:
 	PATH="${PATH}:${HOME}/.pub-cache/bin" buf generate --include-imports
 
+testsuite-tree:
+	go run ./cmd/testsuite tree > docs/testsuite_tree.md
+
 go:
 	GO111MODULE=on go mod tidy
 
@@ -37,6 +40,7 @@ dart:
 clean:
 	-rm -r Assets/src
 	-rm docs/protos.md
+	-rm docs/dependency-tree.md
 	-rm -r pkg
 	-rm -r node
 	-rm -r src

cmd/testsuite/main.go

@@ -0,0 +1,112 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+
+	featuresets "github.com/tuihub/protos/docs/feature_sets"
+)
+
+// Testsuite is the entry point of testsuite command
+// It supports the following subcommands:
+// - run: Run the test suite (default if no subcommand specified)
+// - tree: Generate dependency tree visualization
+// - help: Show usage information
+func main() {
+	if len(os.Args) < 2 {
+		// Default to run command when no arguments provided
+		runCommand(os.Args[1:])
+		return
+	}
+
+	subcommand := os.Args[1]
+
+	// Check if first argument looks like a flag (backward compatibility)
+	if len(subcommand) > 0 && subcommand[0] == '-' {
+		// Treat as run command with flags
+		runCommand(os.Args[1:])
+		return
+	}
+
+	switch subcommand {
+	case "run":
+		runCommand(os.Args[2:])
+	case "tree":
+		treeCommand(os.Args[2:])
+	case "help", "--help", "-h":
+		printUsage()
+	default:
+		// Unknown subcommand, default to run for backward compatibility
+		runCommand(os.Args[1:])
+	}
+}
+
+func runCommand(args []string) {
+	fs := flag.NewFlagSet("run", flag.ExitOnError)
+	serverHost := fs.String("server-host", "127.0.0.1", "Server host")
+	serverPort := fs.Int("server-port", 10000, "Server port")
+	verboseFlag := fs.Bool("v", false, "Verbose")
+	veryVerboseFlag := fs.Bool("vv", false, "Very verbose")
+	extremelyVerboseFlag := fs.Bool("vvv", false, "Extremely verbose")
+
+	fs.Parse(args)
+
+	sephirahServerHost := *serverHost
+	sephirahServerPort := *serverPort
+
+	verbose := 0
+	if *verboseFlag {
+		verbose = 1
+	}
+	if *veryVerboseFlag {
+		verbose = 2
+	}
+	if *extremelyVerboseFlag {
+		verbose = 3
+	}
+
+	fmt.Printf("Running TestSuite on %s:%d, Verbose Level: %d\n", sephirahServerHost, sephirahServerPort, verbose)
+	err := featuresets.RunTestSuite(context.Background(), sephirahServerHost, sephirahServerPort, verbose)
+	if err != nil {
+		fmt.Printf("TestSuite Failed to Run, Error: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Printf("TestSuite Ran Successfully\n")
+}
+
+func treeCommand(args []string) {
+	fs := flag.NewFlagSet("tree", flag.ExitOnError)
+	fs.Parse(args)
+
+	if err := featuresets.PrintMermaidTree(os.Stdout); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to generate dependency tree: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+func printUsage() {
+	fmt.Println(`Usage: testsuite [subcommand] [flags]
+
+Subcommands:
+  run       Run the test suite (default)
+  tree      Generate dependency tree visualization in Mermaid format
+  help      Show this help message
+
+Run command flags:
+  -server-host string
+        Server host (default "127.0.0.1")
+  -server-port int
+        Server port (default 10000)
+  -v    Verbose output (level 1)
+  -vv   Very verbose output (level 2)
+  -vvv  Extremely verbose output (level 3)
+
+Examples:
+  testsuite run --server-host=localhost --server-port=8080
+  testsuite tree > dependency-tree.md
+  testsuite tree | pbcopy  # Copy to clipboard on macOS
+
+For more information, see docs/feature_sets/AGENTS.md`)
+}

docs/.gitignore

@@ -1,2 +1,3 @@
 protos.md
-openapi.json
+openapi.json
+testsuite_tree.md