@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/storage/validation_test.go

@@ -0,0 +1,495 @@
+package storage
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ===============================================================
+// ValidateFileMetadata 测试
+// ===============================================================
+
+func TestValidateFileMetadata_ValidFile(t *testing.T) {
+	cfg := ValidationConfig{
+		MaxFileSize: 10 * 1024 * 1024, // 10 MB
+	}
+	err := ValidateFileMetadata("photo.jpg", "image/jpeg", 512*1024, cfg)
+	require.NoError(t, err)
+}
+
+func TestValidateFileMetadata_SizeLimit(t *testing.T) {
+	tests := []struct {
+		name        string
+		size        int64
+		maxFileSize int64
+		wantErr     bool
+	}{
+		{
+			name:        "exactly at limit passes",
+			size:        5 * 1024 * 1024,
+			maxFileSize: 5 * 1024 * 1024,
+			wantErr:     false,
+		},
+		{
+			name:        "one byte over limit fails",
+			size:        5*1024*1024 + 1,
+			maxFileSize: 5 * 1024 * 1024,
+			wantErr:     true,
+		},
+		{
+			name:        "zero max size means no limit",
+			size:        1000 * 1024 * 1024,
+			maxFileSize: 0,
+			wantErr:     false,
+		},
+		{
+			name:        "well under limit passes",
+			size:        1024,
+			maxFileSize: 10 * 1024 * 1024,
+			wantErr:     false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := ValidationConfig{
+				MaxFileSize:      tc.maxFileSize,
+				AllowedMimeTypes: []string{"image/jpeg"},
+			}
+			err := ValidateFileMetadata("photo.jpg", "image/jpeg", tc.size, cfg)
+			if tc.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), "exceeds maximum")
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestValidateFileMetadata_DisallowedMimeType(t *testing.T) {
+	tests := []struct {
+		name        string
+		contentType string
+		wantErr     bool
+	}{
+		{
+			name:        "application/x-executable is rejected by default whitelist",
+			contentType: "application/x-executable",
+			wantErr:     true,
+		},
+		{
+			name:        "application/x-php is rejected",
+			contentType: "application/x-php",
+			wantErr:     true,
+		},
+		{
+			name:        "image/jpeg is allowed by default whitelist",
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			name:        "custom whitelist rejects type not in list",
+			contentType: "image/jpeg",
+			wantErr:     true,
+		},
+	}
+
+	for i, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := ValidationConfig{}
+			// 第 4 个 case 使用自定义白名单，只允许 image/png
+			if i == 3 {
+				cfg.AllowedMimeTypes = []string{"image/png"}
+			}
+			err := ValidateFileMetadata("file.jpg", tc.contentType, 1024, cfg)
+			if tc.wantErr {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), "not allowed")
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestValidateFileMetadata_CustomAllowlistAcceptsQuickTime(t *testing.T) {
+	cfg := ValidationConfig{
+		AllowedMimeTypes: []string{"video/mp4", "video/webm", "video/quicktime"},
+	}
+
+	err := ValidateFileMetadata("clip.mov", "video/quicktime", 1024, cfg)
+
+	require.NoError(t, err)
+}
+
+func TestValidateFileMetadata_CustomWildcardAllowlistUsesKnownMimeTypes(t *testing.T) {
+	cfg := ValidationConfig{
+		AllowedMimeTypes: []string{"video/*", "application/*"},
+	}
+
+	require.NoError(t, ValidateFileMetadata("clip.mov", "video/quicktime", 1024, cfg))
+	require.Error(t, ValidateFileMetadata("malware.exe", "application/x-executable", 1024, cfg))
+}
+
+func TestValidateFileMetadata_ExtensionMismatch(t *testing.T) {
+	tests := []struct {
+		name        string
+		filename    string
+		contentType string
+		wantErr     bool
+		errContains string
+	}{
+		{
+			name:        ".jpg with text/plain is rejected",
+			filename:    "photo.jpg",
+			contentType: "text/plain",
+			wantErr:     true,
+			errContains: "does not match content type",
+		},
+		{
+			name:        ".png with image/jpeg is rejected",
+			filename:    "image.png",
+			contentType: "image/jpeg",
+			wantErr:     true,
+			errContains: "does not match content type",
+		},
+		{
+			name:        ".jpg with image/jpeg is accepted",
+			filename:    "photo.jpg",
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			name:        ".jpeg with image/jpeg is accepted",
+			filename:    "photo.jpeg",
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			name:        "no extension skips extension check",
+			filename:    "noextension",
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			name:        "empty filename skips extension check",
+			filename:    "",
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			name:        ".pdf with application/pdf is accepted",
+			filename:    "document.pdf",
+			contentType: "application/pdf",
+			wantErr:     false,
+		},
+		{
+			name:        ".mp3 with audio/mpeg is accepted",
+			filename:    "song.mp3",
+			contentType: "audio/mpeg",
+			wantErr:     false,
+		},
+		{
+			name:        ".mp4 with video/mp4 is accepted",
+			filename:    "video.mp4",
+			contentType: "video/mp4",
+			wantErr:     false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := ValidationConfig{}
+			err := ValidateFileMetadata(tc.filename, tc.contentType, 1024, cfg)
+			if tc.wantErr {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.errContains)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestValidateFileMetadata_AllWhitelistedMimeTypes(t *testing.T) {
+	// 验证全部 30 个白名单 MIME 类型均能通过校验
+	testCases := []struct {
+		contentType string
+		filename    string
+	}{
+		{"image/jpeg", "file.jpg"},
+		{"image/png", "file.png"},
+		{"image/gif", "file.gif"},
+		{"image/webp", "file.webp"},
+		{"image/svg+xml", "file.svg"},
+		{"image/bmp", "file.bmp"},
+		{"image/tiff", "file.tif"},
+		{"application/pdf", "file.pdf"},
+		{"application/msword", "file.doc"},
+		{"application/vnd.openxmlformats-officedocument.wordprocessingml.document", "file.docx"},
+		{"application/vnd.ms-excel", "file.xls"},
+		{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "file.xlsx"},
+		{"application/vnd.ms-powerpoint", "file.ppt"},
+		{"application/vnd.openxmlformats-officedocument.presentationml.presentation", "file.pptx"},
+		{"text/plain", "file.txt"},
+		{"text/csv", "file.csv"},
+		{"text/html", "file.html"},
+		{"text/markdown", "file.md"},
+		{"application/json", "file.json"},
+		{"application/xml", "file.xml"},
+		{"audio/mpeg", "file.mp3"},
+		{"audio/wav", "file.wav"},
+		{"audio/ogg", "file.ogg"},
+		{"audio/webm", "file.weba"},
+		{"audio/aac", "file.aac"},
+		{"video/mp4", "file.mp4"},
+		{"video/webm", "file.webm"},
+		{"video/ogg", "file.ogv"},
+		{"video/quicktime", "file.mov"},
+		{"application/zip", "file.zip"},
+		{"application/gzip", "file.gz"},
+		{"application/x-tar", "file.tar"},
+		{"application/x-7z-compressed", "file.7z"},
+		{"application/x-rar-compressed", "file.rar"},
+	}
+
+	// defaultAllowedMimeTypes 实际包含 34 个条目（7 图片 + 7 文档 + 6 文本 + 5 音频 + 4 视频 + 5 压缩包）
+	assert.Equal(t, len(defaultAllowedMimeTypes), len(testCases),
+		"testCases must cover every entry in defaultAllowedMimeTypes")
+
+	cfg := ValidationConfig{} // 使用默认白名单
+	for _, tc := range testCases {
+		t.Run(tc.contentType, func(t *testing.T) {
+			err := ValidateFileMetadata(tc.filename, tc.contentType, 1024, cfg)
+			assert.NoError(t, err, "MIME type %q with file %q should be allowed", tc.contentType, tc.filename)
+		})
+	}
+}
+
+// ===============================================================
+// ValidateFileContent 测试
+// ===============================================================
+
+func TestValidateFileContent_MagicBytesMatch(t *testing.T) {
+	tests := []struct {
+		name        string
+		header      []byte
+		contentType string
+		wantErr     bool
+	}{
+		{
+			// PNG magic bytes: 0x89 0x50 0x4E 0x47
+			name:        "PNG magic bytes match image/png",
+			header:      []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0},
+			contentType: "image/png",
+			wantErr:     false,
+		},
+		{
+			// GIF magic bytes: GIF87a or GIF89a
+			name:        "GIF magic bytes match image/gif",
+			header:      append([]byte("GIF89a"), make([]byte, 100)...),
+			contentType: "image/gif",
+			wantErr:     false,
+		},
+		{
+			// JPEG magic bytes: 0xFF 0xD8 0xFF
+			name:        "JPEG magic bytes match image/jpeg",
+			header:      []byte{0xFF, 0xD8, 0xFF, 0xE0, 0, 0x10, 0x4A, 0x46, 0x49, 0x46, 0, 0x01},
+			contentType: "image/jpeg",
+			wantErr:     false,
+		},
+		{
+			// 纯文本内容
+			name:        "plain text matches text/plain",
+			header:      []byte("Hello, this is plain text content for testing purposes."),
+			contentType: "text/plain",
+			wantErr:     false,
+		},
+		{
+			// PDF magic bytes: %PDF
+			name:        "PDF magic bytes do not match image",
+			header:      []byte("%PDF-1.4 this is a pdf file content here and more content"),
+			contentType: "image/jpeg",
+			wantErr:     true,
+		},
+		{
+			// 视频内容声明为音频——主类型不同应通过（video vs audio → 不同主类型 → 报错）
+			name:        "image magic bytes declared as audio fails",
+			header:      []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0},
+			contentType: "audio/mpeg",
+			wantErr:     true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateFileContent(tc.header, tc.contentType)
+			if tc.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestValidateFileContent_EmptyHeader(t *testing.T) {
+	err := ValidateFileContent([]byte{}, "image/jpeg")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "empty")
+}
+
+func TestValidateFileContent_OctetStreamSkipsCheck(t *testing.T) {
+	// application/octet-stream 由 http.DetectContentType 返回时跳过校验
+	// 使用随机二进制数据触发 octet-stream 检测
+	binaryData := []byte{0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0xFF, 0xFE, 0xFD}
+	err := ValidateFileContent(binaryData, "application/zip")
+	assert.NoError(t, err, "octet-stream detection should skip validation")
+}
+
+func TestValidateFileContent_MagicBytesMismatch(t *testing.T) {
+	tests := []struct {
+		name            string
+		header          []byte
+		declaredType    string
+		expectedErrFrag string
+	}{
+		{
+			name:            "PNG bytes declared as text/plain fails",
+			header:          []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0},
+			declaredType:    "text/plain",
+			expectedErrFrag: "does not match declared type",
+		},
+		{
+			name:            "GIF bytes declared as audio/mpeg fails",
+			header:          append([]byte("GIF89a"), make([]byte, 100)...),
+			declaredType:    "audio/mpeg",
+			expectedErrFrag: "does not match declared type",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateFileContent(tc.header, tc.declaredType)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tc.expectedErrFrag)
+		})
+	}
+}
+
+// ===============================================================
+// SanitizeFilename 测试
+// ===============================================================
+
+func TestSanitizeFilename(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "valid filename is preserved",
+			input:    "my-photo_2024.jpg",
+			expected: "my-photo_2024.jpg",
+		},
+		{
+			name:     "strips Unix path traversal",
+			input:    "../../../etc/passwd",
+			expected: "passwd",
+		},
+		{
+			// filepath.Base 在 Linux/macOS 上不将反斜杠视为路径分隔符，
+			// 因此整个字符串被视为单一文件名，反斜杠被替换为下划线。
+			// Windows 路径遍历防护需在应用层拒绝含反斜杠的输入，而非依赖 SanitizeFilename。
+			name:     "Windows backslash path treated as single filename segment on Unix",
+			input:    `..\..\windows\system32\config`,
+			expected: ".._.._windows_system32_config",
+		},
+		{
+			name:     "strips absolute Unix path",
+			input:    "/etc/shadow",
+			expected: "shadow",
+		},
+		{
+			name:     "strips nested path",
+			input:    "uploads/../secret.txt",
+			expected: "secret.txt",
+		},
+		{
+			name:     "empty filename becomes unnamed",
+			input:    "",
+			expected: "unnamed",
+		},
+		{
+			name:     "dot-only becomes unnamed",
+			input:    ".",
+			expected: "unnamed",
+		},
+		{
+			name:     "removes non-printable characters",
+			input:    "file\x00name.txt",
+			expected: "filename.txt",
+		},
+		{
+			name:     "removes null bytes",
+			input:    "evil\x00.php.jpg",
+			expected: "evil.php.jpg",
+		},
+		{
+			name:     "spaces replaced with underscore",
+			input:    "my file name.jpg",
+			expected: "my_file_name.jpg",
+		},
+		{
+			name:     "special characters replaced with underscore",
+			input:    "file@name#2024!.png",
+			expected: "file_name_2024_.png",
+		},
+		{
+			// unicode.IsLetter 对 CJK 字符返回 true，因此中文字符被视为合法字母保留。
+			// SanitizeFilename 不对非 ASCII 字母进行额外过滤。
+			name:     "Chinese characters preserved as letters by unicode.IsLetter",
+			input:    "照片.jpg",
+			expected: "照片.jpg",
+		},
+		{
+			name:     "alphanumeric only filename preserved",
+			input:    "document123",
+			expected: "document123",
+		},
+		{
+			name:     "hyphen and underscore preserved",
+			input:    "my-file_name.tar.gz",
+			expected: "my-file_name.tar.gz",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := SanitizeFilename(tc.input)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}
+
+func TestSanitizeFilename_NeverEmpty(t *testing.T) {
+	// 无论输入什么，结果都不应为空字符串
+	inputs := []string{
+		"",
+		".",
+		"\x00",
+		"\t\n",
+		"   ",
+		"@#$%^&*()",
+	}
+	for _, input := range inputs {
+		t.Run("input="+strings.ReplaceAll(input, "\x00", "NUL"), func(t *testing.T) {
+			result := SanitizeFilename(input)
+			assert.NotEmpty(t, result)
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/core/temporal/logger.go

@@ -0,0 +1,38 @@
+package temporal
+
+import (
+	tlog "go.temporal.io/sdk/log"
+	"go.uber.org/zap"
+)
+
+// zapAdapter 将 zap.Logger 适配为 Temporal SDK 的 log.Logger 接口
+type zapAdapter struct {
+	logger *zap.SugaredLogger
+}
+
+var _ tlog.Logger = (*zapAdapter)(nil)
+
+// NewZapAdapter 创建 Temporal SDK 日志适配器
+func NewZapAdapter(logger *zap.Logger) tlog.Logger {
+	return &zapAdapter{logger: logger.Sugar()}
+}
+
+// Debug 输出 Debug 级别日志
+func (a *zapAdapter) Debug(msg string, keyvals ...any) {
+	a.logger.Debugw(msg, keyvals...)
+}
+
+// Info 输出 Info 级别日志
+func (a *zapAdapter) Info(msg string, keyvals ...any) {
+	a.logger.Infow(msg, keyvals...)
+}
+
+// Warn 输出 Warn 级别日志
+func (a *zapAdapter) Warn(msg string, keyvals ...any) {
+	a.logger.Warnw(msg, keyvals...)
+}
+
+// Error 输出 Error 级别日志
+func (a *zapAdapter) Error(msg string, keyvals ...any) {
+	a.logger.Errorw(msg, keyvals...)
+}

package/dist/resources/templates/go-backend/internal/core/temporal/provider.go

@@ -0,0 +1,126 @@
+package temporal
+
+import (
+	"crypto/tls"
+	"crypto/x509"
+	"fmt"
+	"os"
+	"strings"
+
+	"go.temporal.io/sdk/client"
+	"go.temporal.io/sdk/worker"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// ProvideClient 创建 Temporal SDK 客户端
+//
+// 当配置中 temporal.enabled=false 时返回 nil（不连接）。
+// 一旦启用 Temporal，host_port / namespace 必须显式配置，避免把运行时编排降级成隐式可选项。
+func ProvideClient(cfg *config.Config, logger *zap.Logger) (client.Client, func(), error) {
+	if !cfg.Temporal.Enabled {
+		logger.Info("temporal client disabled, skipping connection")
+		return nil, func() {}, nil
+	}
+
+	hostPort := strings.TrimSpace(cfg.Temporal.HostPort)
+	if hostPort == "" {
+		return nil, nil, fmt.Errorf("temporal host port is required when temporal is enabled")
+	}
+
+	namespace := strings.TrimSpace(cfg.Temporal.Namespace)
+	if namespace == "" {
+		return nil, nil, fmt.Errorf("temporal namespace is required when temporal is enabled")
+	}
+
+	tlsConfig, err := buildTLSConfig(cfg.Temporal)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	options := client.Options{
+		HostPort:  hostPort,
+		Namespace: namespace,
+		Logger:    NewZapAdapter(logger.Named("temporal")),
+	}
+	if tlsConfig != nil {
+		options.ConnectionOptions.TLS = tlsConfig
+	}
+
+	c, err := client.Dial(options)
+	if err != nil {
+		return nil, nil, fmt.Errorf("dial temporal server %s: %w", hostPort, err)
+	}
+
+	cleanup := func() {
+		c.Close()
+		logger.Info("temporal client closed")
+	}
+
+	logger.Info("temporal client connected",
+		zap.String("hostPort", hostPort),
+		zap.String("namespace", namespace),
+	)
+
+	return c, cleanup, nil
+}
+
+func buildTLSConfig(cfg config.TemporalConfig) (*tls.Config, error) {
+	if !cfg.TLS.Enabled {
+		var tlsConfig *tls.Config
+		return tlsConfig, nil
+	}
+
+	tlsConfig := &tls.Config{
+		MinVersion:         tls.VersionTLS12,
+		ServerName:         strings.TrimSpace(cfg.TLS.ServerName),
+		InsecureSkipVerify: cfg.TLS.DisableHostVerification, //nolint:gosec // 仅由显式 Temporal TLS 配置开启，默认关闭。
+	}
+
+	caPath := strings.TrimSpace(cfg.TLS.CAPath)
+	if caPath != "" {
+		caPEM, err := os.ReadFile(caPath)
+		if err != nil {
+			return nil, fmt.Errorf("read temporal TLS CA file %s: %w", caPath, err)
+		}
+		rootCAs, err := x509.SystemCertPool()
+		if err != nil || rootCAs == nil {
+			rootCAs = x509.NewCertPool()
+		}
+		if ok := rootCAs.AppendCertsFromPEM(caPEM); !ok {
+			return nil, fmt.Errorf("append temporal TLS CA file %s: invalid PEM", caPath)
+		}
+		tlsConfig.RootCAs = rootCAs
+	}
+
+	certPath := strings.TrimSpace(cfg.TLS.CertPath)
+	keyPath := strings.TrimSpace(cfg.TLS.KeyPath)
+	if certPath == "" && keyPath == "" {
+		return tlsConfig, nil
+	}
+	if certPath == "" || keyPath == "" {
+		return nil, fmt.Errorf("temporal TLS cert_path and key_path must be configured together")
+	}
+
+	certificate, err := tls.LoadX509KeyPair(certPath, keyPath)
+	if err != nil {
+		return nil, fmt.Errorf("load temporal TLS client certificate: %w", err)
+	}
+	tlsConfig.Certificates = []tls.Certificate{certificate}
+	return tlsConfig, nil
+}
+
+// ProvideWorker 创建 Temporal Worker（绑定到指定任务队列）
+//
+// 当 Temporal Client 为 nil（未启用）时返回 nil，调用方应跳过 Worker 启动。
+func ProvideWorker(c client.Client, taskQueue string, logger *zap.Logger) worker.Worker {
+	if c == nil {
+		logger.Info("temporal client is nil, skipping worker creation")
+		return nil
+	}
+
+	w := worker.New(c, taskQueue, worker.Options{})
+	logger.Info("temporal worker created", zap.String("taskQueue", taskQueue))
+	return w
+}