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

cmd/testsuite/main.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+
+	featuresets "github.com/tuihub/protos/docs/feature_sets"
+)
+
+// Testsuite is the entry point of testsuite command
+// It parses command line flags and runs the test suite
+// The following flags are supported:
+// -server-host: Server host (default: 127.0.0.1)
+// -server-port: Server port (default: 10000)
+// -v: Verbose
+// -vv: Very verbose
+// -vvv: Extremely verbose
+func main() {
+	serverHost := flag.String("server-host", "127.0.0.1", "Server host")
+	serverPort := flag.Int("server-port", 10000, "Server port")
+	verboseFlag := flag.Bool("v", false, "Verbose")
+	veryVerboseFlag := flag.Bool("vv", false, "Very verbose")
+	extremelyVerboseFlag := flag.Bool("vvv", false, "Extremely verbose")
+
+	flag.Parse()
+
+	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)
+	}
+	fmt.Printf("TestSuite Ran Successfully\n")
+}