@stackonward/cli 1.7.0 → 1.8.0

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/notification/contracts.go

@@ -0,0 +1,219 @@
+package notification
+
+import "time"
+
+// InboxQuery 保留原生查询的全部过滤条件，不替产品选择 scope。
+type InboxQuery struct {
+	UserID      int64    `json:"user_id"`
+	Categories  []string `json:"categories,omitempty"`
+	TargetRef   string   `json:"target_ref,omitempty"`
+	TargetScope string   `json:"target_scope"`
+	ReadStatus  string   `json:"read_status,omitempty"`
+	DeliveryIDs []int64  `json:"delivery_ids,omitempty"`
+	MessageIDs  []int64  `json:"message_ids,omitempty"`
+	Page        int      `json:"page,omitempty"`
+	PageSize    int      `json:"page_size,omitempty"`
+}
+
+// InboxMessage 是平台投影，不包含产品导航解释。
+type InboxMessage struct {
+	DeliveryID    int64             `json:"delivery_id"`
+	MessageID     int64             `json:"message_id"`
+	MessageNo     string            `json:"message_no"`
+	SourceVersion int64             `json:"source_version"`
+	Title         string            `json:"title"`
+	Subtitle      *string           `json:"subtitle,omitempty"`
+	Content       string            `json:"content"`
+	CoverURL      *string           `json:"cover_url,omitempty"`
+	ActionURL     *string           `json:"action_url,omitempty"`
+	Category      string            `json:"category"`
+	Metadata      map[string]string `json:"metadata"`
+	Status        string            `json:"status"`
+	TargetRef     *string           `json:"target_ref,omitempty"`
+	TargetKind    *string           `json:"target_kind,omitempty"`
+	ReadAt        *time.Time        `json:"read_at,omitempty"`
+	DeliveredAt   time.Time         `json:"delivered_at"`
+	CreatedAt     time.Time         `json:"created_at"`
+	UpdatedAt     time.Time         `json:"updated_at"`
+}
+
+// InboxPage 保留分页总数和分类未读汇总，供产品自行投影。
+type InboxPage struct {
+	Items         []InboxMessage   `json:"items"`
+	Total         int64            `json:"total"`
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// Unread 保留全局与分类未读事实。
+type Unread struct {
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// MessageVersion 仅确认用户已经查看的消息版本。
+type MessageVersion struct {
+	MessageNo     string `json:"message_no"`
+	SourceVersion int64  `json:"source_version"`
+}
+
+// AcknowledgeMessagesRequest 绑定可信接收人与精确消息版本。
+type AcknowledgeMessagesRequest struct {
+	UserID   int64            `json:"user_id"`
+	Messages []MessageVersion `json:"messages"`
+}
+
+// Acknowledgement 返回原子确认后的未读快照。
+type Acknowledgement struct {
+	Updated       int64            `json:"updated"`
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// DeviceRegistration 的账号与会话来自可信服务端上下文。
+type DeviceRegistration struct {
+	UserID               int64  `json:"user_id"`
+	SessionID            int64  `json:"session_id"`
+	ApplicationCode      string `json:"application_code"`
+	Environment          string `json:"environment"`
+	InstallationID       string `json:"installation_id"`
+	InstallationKey      string `json:"installation_key"`
+	RegistrationRevision int64  `json:"registration_revision"`
+	DeviceToken          string `json:"device_token"`
+	Platform             string `json:"platform"`
+	Provider             string `json:"provider"`
+	AppVersion           string `json:"app_version,omitempty"`
+	DeviceModel          string `json:"device_model,omitempty"`
+	OSVersion            string `json:"os_version,omitempty"`
+}
+
+// DeviceRevocation 使用安装能力，不要求保留已退出账号的身份。
+type DeviceRevocation struct {
+	ApplicationCode      string `json:"application_code"`
+	Environment          string `json:"environment"`
+	InstallationID       string `json:"installation_id"`
+	InstallationKey      string `json:"installation_key"`
+	RegistrationRevision int64  `json:"registration_revision"`
+}
+
+// Device 保留平台安全设备投影，不返回安装密钥或推送令牌。
+type Device struct {
+	ID                   int64      `json:"id"`
+	InstallationID       string     `json:"installation_id"`
+	ApplicationCode      string     `json:"application_code"`
+	Environment          string     `json:"environment"`
+	RegistrationRevision int64      `json:"registration_revision"`
+	Provider             string     `json:"provider"`
+	Platform             string     `json:"platform"`
+	AppVersion           *string    `json:"app_version"`
+	DeviceModel          *string    `json:"device_model"`
+	OSVersion            *string    `json:"os_version"`
+	Status               string     `json:"status"`
+	LastActiveAt         *time.Time `json:"last_active_at"`
+	CreatedAt            time.Time  `json:"created_at"`
+}
+
+// DeviceList 保留当前接收人的有效设备集合。
+type DeviceList struct {
+	Devices []Device `json:"devices"`
+}
+
+// QuietHours 表达调用方选择的静默时段，不设置产品默认值。
+type QuietHours struct {
+	Enabled  bool   `json:"enabled"`
+	Start    string `json:"start"`
+	End      string `json:"end"`
+	Timezone string `json:"timezone"`
+}
+
+// PushPreferences 同时保留渠道、分类和静默时段政策。
+type PushPreferences struct {
+	Enabled    bool            `json:"enabled"`
+	Categories map[string]bool `json:"categories"`
+	QuietHours QuietHours      `json:"quiet_hours"`
+}
+
+// PreferenceQuery 显式携带产品分类与默认值。
+type PreferenceQuery struct {
+	UserID     int64           `json:"user_id"`
+	Categories []string        `json:"categories"`
+	Defaults   PushPreferences `json:"defaults"`
+}
+
+// PreferenceUpdate 提交完整的产品作用域渠道偏好。
+type PreferenceUpdate struct {
+	UserID      int64           `json:"user_id"`
+	Preferences PushPreferences `json:"preferences"`
+}
+
+// TestPushRequest 仅供显式诊断调用，不参与构造或配置检查。
+type TestPushRequest struct {
+	UserID    int64   `json:"user_id"`
+	Title     string  `json:"title"`
+	Body      string  `json:"body"`
+	DeviceIDs []int64 `json:"device_ids"`
+}
+
+// TestPushResult 仅表示诊断发送的逐设备处理结果。
+type TestPushResult struct {
+	Succeeded int `json:"succeeded"`
+	Failed    int `json:"failed"`
+}
+
+// SourceEvent 由产品持久事件 owner 提供，不在协议层合成。
+type SourceEvent struct {
+	ID             string    `json:"id"`
+	Type           string    `json:"type"`
+	SubjectRef     string    `json:"subject_ref"`
+	SubjectVersion int64     `json:"subject_version"`
+	OccurredAt     time.Time `json:"occurred_at"`
+}
+
+// Recipient 使用平台公开用户引用，不接受调用方提供内部账号 ID。
+type Recipient struct {
+	UserPublicID string `json:"user_public_id"`
+}
+
+// InputContext 保留产品 owner 冻结的输入上下文。
+type InputContext struct {
+	Type      string `json:"type"`
+	Reference string `json:"reference"`
+}
+
+// Target 保留产品 target，不推导导航 URL。
+type Target struct {
+	Kind      string `json:"kind"`
+	Reference string `json:"reference"`
+}
+
+// DispatchStartRequest 不允许指定模板、提供商或发件身份。
+type DispatchStartRequest struct {
+	SourceEvent       SourceEvent    `json:"source_event"`
+	CommandKey        string         `json:"command_key"`
+	Channel           string         `json:"channel"`
+	Context           InputContext   `json:"context"`
+	Recipient         Recipient      `json:"recipient"`
+	Locale            string         `json:"locale"`
+	Target            Target         `json:"target"`
+	BusinessVariables map[string]any `json:"business_variables"`
+}
+
+// DispatchStartResult 表示持久入队与重放状态，不宣称设备已收到。
+type DispatchStartResult struct {
+	CommandUID string    `json:"command_uid"`
+	Status     string    `json:"status"`
+	ExpiresAt  time.Time `json:"expires_at"`
+	Replay     bool      `json:"replay"`
+}
+
+// SourceAdvanceRequest 仅推进事项版本，不携带发送内容。
+type SourceAdvanceRequest struct {
+	SourceEvent SourceEvent `json:"source_event"`
+	Recipient   Recipient   `json:"recipient"`
+}
+
+// SourceAdvanceResult 返回平台当前接受的事项版本。
+type SourceAdvanceResult struct {
+	Status        string `json:"status"`
+	SourceVersion int64  `json:"source_version"`
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/resilience.go

@@ -0,0 +1,23 @@
+package v1
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var dependencyOperationPartPattern = regexp.MustCompile(`^[a-z][a-z0-9_]{1,63}$`)
+
+// DependencyExecutor 在共享 transport 内按依赖操作隔离 bulkhead 与 circuit。
+type DependencyExecutor interface {
+	Execute(context.Context, string, func(context.Context) error) (bool, error)
+}
+
+func dependencyOperationKey(dependency, operation string) (string, error) {
+	if dependency != strings.TrimSpace(dependency) || operation != strings.TrimSpace(operation) ||
+		!dependencyOperationPartPattern.MatchString(dependency) || !dependencyOperationPartPattern.MatchString(operation) {
+		return "", fmt.Errorf("OneX dependency operation is invalid")
+	}
+	return dependency + "." + operation, nil
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/transport_policy.go

@@ -0,0 +1,96 @@
+package v1
+
+import (
+	"context"
+	"math"
+	"math/rand/v2"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+const maximumSafeReadRetries = 10
+
+// SafeReadRetryConfig 定义仅适用于 GET 的有界内联重试策略。
+type SafeReadRetryConfig struct {
+	MaxRetries     int
+	InitialBackoff time.Duration
+	MaxBackoff     time.Duration
+	JitterRatio    float64
+}
+
+// RetryWaiter 隔离重试等待，使 transport 合同可以使用确定性时钟验证。
+type RetryWaiter interface {
+	Wait(ctx context.Context, delay time.Duration) error
+}
+
+type timerRetryWaiter struct{}
+
+func (timerRetryWaiter) Wait(ctx context.Context, delay time.Duration) error {
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func validateSafeReadRetryConfig(config SafeReadRetryConfig) error {
+	if config.MaxRetries < 0 || config.MaxRetries > maximumSafeReadRetries {
+		return NewValidationError("onex_safe_read_retry_limit_invalid")
+	}
+	if config.MaxRetries == 0 {
+		return nil
+	}
+	if config.InitialBackoff <= 0 || config.MaxBackoff < config.InitialBackoff || config.JitterRatio < 0 || config.JitterRatio > 1 {
+		return NewValidationError("onex_safe_read_retry_config_invalid")
+	}
+	return nil
+}
+
+func shouldRetrySafeReadStatus(status int) bool {
+	switch status {
+	case http.StatusTooManyRequests, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+func safeReadRetryDelay(config SafeReadRetryConfig, retryNumber int, retryAfter string, now time.Time) time.Duration {
+	if retryAfterDelay, ok := parseRetryAfter(retryAfter, now); ok {
+		return retryAfterDelay
+	}
+	delay := float64(config.InitialBackoff) * math.Pow(2, float64(retryNumber-1))
+	if delay > float64(config.MaxBackoff) {
+		delay = float64(config.MaxBackoff)
+	}
+	if config.JitterRatio > 0 {
+		minimum := delay * (1 - config.JitterRatio)
+		delay = minimum + rand.Float64()*(delay-minimum) //nolint:gosec // 仅用于重试抖动，不生成安全令牌。
+	}
+	return time.Duration(delay)
+}
+
+func parseRetryAfter(value string, now time.Time) (time.Duration, bool) {
+	if value == "" {
+		return 0, false
+	}
+	if seconds, err := strconv.ParseInt(value, 10, 32); err == nil {
+		if seconds < 0 {
+			return 0, false
+		}
+		return time.Duration(seconds) * time.Second, true
+	}
+	when, err := http.ParseTime(value)
+	if err != nil {
+		return 0, false
+	}
+	delay := when.Sub(now)
+	if delay < 0 {
+		delay = 0
+	}
+	return delay, true
+}

package/dist/resources/templates/go-backend/internal/products/README.md

@@ -1,5 +1,5 @@
 # Product modules
 
-Each module owns product use cases, models and persistence. Select Full DDD, Simplified DDD or Flat using [module standards](../../.claude/docs/module-standards.md); the directory name describes its business responsibility.
+Each module owns product use cases, models and persistence. Select Full DDD, Simplified DDD or Flat using [module standards](../../.codex/docs/module-standards.md); the directory name describes its business responsibility.
 
 Compose modules through Wire in `cmd/`. Depend on generic infrastructure and consumer-defined integration ports. Platform authentication, asset execution and payment services remain upstream owners; access their published contracts without querying their internal tables.

package/dist/resources/templates/go-backend/internal/sharedevents/README.md

@@ -2,4 +2,4 @@
 
 Declare cross-module event names and typed payloads here. Producers and consumers use the same pointer payload contract, with resource identity and audit metadata in the event envelope.
 
-Register persisted payload factories and explicit event schema versions when adding durable delivery. Domain state transitions remain in the owning product module. See [event runtime boundaries](../../.claude/docs/event-runtime-boundary.md) and [backend standards](../../CLAUDE.md).
+Register persisted payload factories and explicit event schema versions when adding durable delivery. Domain state transitions remain in the owning product module. See [event runtime boundaries](../../.codex/docs/event-runtime-boundary.md) and [backend standards](../../AGENTS.md).

package/dist/resources/templates/go-backend/scripts/check-openapi-clean-deletion.sh

@@ -27,10 +27,10 @@ fail_if_matches "Swagger annotations remain" '^\s*//\s*@[[:alpha:]]' "$BACKEND_D
 fail_if_matches "Swagger-only struct tags remain" '(^|[[:space:]`])(swaggertype|example|format):"' "$BACKEND_DIR" --glob '*.go'
 fail_if_matches "Swagger runtime registry reads remain" 'swag\.ReadDoc' "$BACKEND_DIR" --glob '*.go'
 fail_if_matches "Retired Swagger commands remain" 'make swag|generate-swagger|swagger_route_inventory' \
-  "$BACKEND_DIR/Makefile" "$BACKEND_DIR/CLAUDE.md" "$BACKEND_DIR/.claude/docs" \
+  "$BACKEND_DIR/Makefile" "$BACKEND_DIR/AGENTS.md" "$BACKEND_DIR/.codex/docs" \
   --glob '!**/worktrees/**'
 fail_if_matches "Retired Swagger guidance remains" 'Swagger/security|Swagger/API docs' \
-  "$BACKEND_DIR/CLAUDE.md" "$BACKEND_DIR/.claude/docs"
+  "$BACKEND_DIR/AGENTS.md" "$BACKEND_DIR/.codex/docs"
 fail_if_matches "Retired Swagger documentation pipelines remain" \
   'swaggo/swag|CMS_SWAGGER_URL|/swagger/doc\.json|Go Swagger' "$BACKEND_DIR/docs" --glob '*.md'
 
@@ -38,7 +38,7 @@ for path in \
   "$BACKEND_DIR/scripts/generate-swagger.sh" \
   "$BACKEND_DIR/scripts/swagger_route_inventory.py" \
   "$BACKEND_DIR/scripts/swagger_route_inventory_test.py" \
-  "$BACKEND_DIR/.claude/docs/swagger.md"
+  "$BACKEND_DIR/.codex/docs/swagger.md"
 do
   if [[ -e "$path" ]]; then
     echo "retired Swagger artifact remains: ${path#"$BACKEND_DIR/"}" >&2

package/dist/resources/templates/mcp-server/.prettierignore

@@ -0,0 +1 @@
+AGENTS.md

package/dist/resources/templates/nuxt/{.claude → .codex}/docs/stack.md

@@ -45,6 +45,16 @@ ESLint composes the Nuxt-generated flat configuration with `@stackonward/eslint-
 
 Never place OAuth secrets, service credentials or provider API keys here. An enabled client feature does not prove backend credentials or permission are configured. Validate numeric input at its actual consumer rather than relying on `Number.parseInt` alone.
 
+### Optional Web Push
+
+<web_push_contract>
+
+`runtimeConfig.public.webPush` owns `NUXT_PUBLIC_WEB_PUSH_ENABLED`, `API_ORIGIN`, `PRODUCT_CODE`, `APPLICATION_CODE`, `TOPIC_KEY` and `DATABASE_NAME` under the same `NUXT_PUBLIC_WEB_PUSH_` prefix. The capability MUST remain disabled by default. The optional `@stackonward/nuxt-site-shell/web-push` module bundles the editable `app/web-push/worker.ts` into a same-origin script; building that asset NEVER grants permission or registers a subscription.
+
+MUST consume browser/worker primitives from `@stackonward/web-push`, coordination from `@stackonward/composables`, and the named HTTP/storage protocol from `@stackonward/onex-web-push`. Product consent copy, branding, navigation targets and public identifiers remain in the application. MUST preserve an existing database namespace and record key when upgrading; those records contain the capability required for withdrawal. NEVER send cookies/account authorization, follow API redirects, automatically regrant consent, or couple messaging to optional analytics. Locale aliases are validated by the backend owner, not a copied frontend locale enum. Browser permission and real delivery require separate acceptance.
+
+</web_push_contract>
+
 ## II. Project Structure and Imports
 
 | Owner                                                                 | Responsibility                                                       |

package/dist/resources/templates/nuxt/.dockerignore

@@ -1,6 +1,6 @@
 .git
 .github
-.claude
+.codex
 .husky
 .nuxt
 node_modules

package/dist/resources/templates/nuxt/.env.example

@@ -1,5 +1,11 @@
 NUXT_PUBLIC_API_BASE_URL=
 NUXT_PUBLIC_API_TIMEOUT=30000
+NUXT_PUBLIC_WEB_PUSH_ENABLED=false
+NUXT_PUBLIC_WEB_PUSH_API_ORIGIN=
+NUXT_PUBLIC_WEB_PUSH_PRODUCT_CODE=
+NUXT_PUBLIC_WEB_PUSH_APPLICATION_CODE=
+NUXT_PUBLIC_WEB_PUSH_TOPIC_KEY=
+NUXT_PUBLIC_WEB_PUSH_DATABASE_NAME="{{projectName}}-web-push"
 NUXT_PUBLIC_SITE_URL=
 NUXT_PUBLIC_SITE_ENV=development
 NUXT_PUBLIC_SITE_NAME="{{projectName}}"

package/dist/resources/templates/nuxt/.prettierignore

@@ -1,4 +1,5 @@
-.claude
+.codex
+AGENTS.md
 .nuxt
 .output
 coverage

package/dist/resources/templates/nuxt/DESIGN.md

@@ -1,6 +1,6 @@
 # Nuxt Design Standard
 
-This document defines the visual contract for the application-owned Nuxt UI foundation. Read it with the [Nuxt Engineering Standard](.claude/docs/stack.md) before changing icons, controls or theme defaults. Application branding remains in its own assets and semantic color tokens.
+This document defines the visual contract for the application-owned Nuxt UI foundation. Read it with the [Nuxt Engineering Standard](.codex/docs/stack.md) before changing icons, controls or theme defaults. Application branding remains in its own assets and semantic color tokens.
 
 ## Design Decisions
 

package/dist/resources/templates/nuxt/README.md

@@ -30,6 +30,14 @@ pnpm dlx @stackonward/cli analytics generate \
 
 Import the generated JSON into a selected GTM web-container workspace, preview the merge, and publish the reviewed version. The generated Google Tag disables automatic page views because the Nuxt integration owns SPA page-view dispatch.
 
+## Optional Web Push
+
+Web Push is disabled by default. The generated `app/plugins/web-push.ts` composes the public browser primitives, Vue controller and named OneX adapter; `app/web-push/worker.ts` is bundled by `@stackonward/nuxt-site-shell/web-push` into the same-origin `push-sw.js`. The worker source is editable product code, not an unbundled public script.
+
+Configure the public `NUXT_PUBLIC_WEB_PUSH_*` settings in `.env.example` only after the matching OneX product, application, allowed origin, consent topic and VAPID provider are configured. Keep the generated database namespace stable after users subscribe. Product code owns consent wording, the visible subscribe/withdraw controls, notification fallback title and business destinations. There is no automatic visitor subscription, and analytics consent does not authorize Web Push.
+
+`useWebPush()` exposes `state`, `subscribe(locale, event)`, `revoke(event)` and `refresh()`. Call subscribe and revoke from real user click or keyboard events, surface the controller's safe error state, and retain recovery actions when a request has an unknown outcome. Locale is forwarded to the server for validation and normalization. Browser permission, subscription persistence, provider delivery and notification-click behavior require separate browser/device acceptance; a successful build does not prove delivery.
+
 ## Engineering workflow
 
 ```bash

package/dist/resources/templates/nuxt/nuxt.config.ts

@@ -6,7 +6,11 @@ const gtmId = process.env.NUXT_PUBLIC_GTM_ID || "";
 
 export default defineNuxtConfig({
   extends: ["@stackonward/nuxt-site-shell"],
-  modules: ["@nuxt/eslint", "@stackonward/google-tag-manager-nuxt"],
+  modules: [
+    "@nuxt/eslint",
+    "@stackonward/google-tag-manager-nuxt",
+    ["@stackonward/nuxt-site-shell/web-push", { entry: "app/web-push/worker.ts" }],
+  ],
   compatibilityDate: "2025-07-15",
   css: ["~/assets/css/site-shell.css"],
   i18n: {
@@ -56,6 +60,14 @@ export default defineNuxtConfig({
   },
   runtimeConfig: {
     public: {
+      webPush: {
+        enabled: false,
+        apiOrigin: "",
+        productCode: "",
+        applicationCode: "",
+        topicKey: "",
+        databaseName: "{{projectName}}-web-push",
+      },
       api: {
         baseUrl: process.env.NUXT_PUBLIC_API_BASE_URL || "",
         timeout: Number.parseInt(process.env.NUXT_PUBLIC_API_TIMEOUT || "30000", 10),

package/dist/resources/templates/nuxt/package.json

@@ -28,11 +28,13 @@
     "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
   },
   "dependencies": {
+    "@stackonward/web-push": "^0.0.1",
+    "@stackonward/onex-web-push": "^0.0.1",
     "@stackonward/api-client": "^0.0.3",
     "@stackonward/google-tag-manager-nuxt": "^0.3.3",
     "@stackonward/nuxt-layer-base": "^0.0.4",
-    "@stackonward/nuxt-site-shell": "^0.3.2",
-    "@stackonward/composables": "^0.0.2"
+    "@stackonward/nuxt-site-shell": "^0.4.0",
+    "@stackonward/composables": "^0.1.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackonward/cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "StackOnward CLI for creating projects and installing reusable components and snippets",
   "type": "module",
   "main": "dist/index.js",