@wneng/create-keel 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",

package/src/templates/ci-gitee/files/pipeline.yml

@@ -1,18 +1,152 @@
+# Gitee Pipelines for <%= it.options.projectName %>
+#
+# Generated by `@wneng/create-keel` (Contract First + Vibe Coding).
+#
+# Gitee Pipelines and GitHub Actions speak different YAML dialects;
+# this file uses the documented `stages + jobs` shape supported by
+# Gitee. If your team migrates to GitHub Actions, regenerate with
+# `--ci github` instead of porting by hand.
+#
+# Each stage runs sequentially; jobs within a stage run in parallel.
+# Failure in any stage aborts the pipeline.
+
 name: ci
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+
+stages:
+  - lint
+  - test
+  - scan
+
 jobs:
-  checks:
-    runs-on: ubuntu-latest
-    steps:
-      - name: checkout
-        run: echo "checkout <%= it.options.projectName %>"
-      - name: contract lint
-        run: echo "spectral lint contracts/openapi/api.yaml"
-      - name: json schema validate
-        run: echo "ajv-cli validate -s contracts/**/*.schema.json"
-      - name: dependency scan
-        run: echo "npm audit / pip-audit / trivy"
+  governance-lint:
+    stage: lint
+    image: node:20-alpine
+    script:
+      - |
+        if [ -f tools/governance-lint/index.js ]; then
+          node tools/governance-lint/index.js --strict
+        else
+          echo "tools/governance-lint/ not present; skipping"
+        fi
+
+  contract-lint:
+    stage: lint
+    image: node:20-alpine
+    script:
+<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>      - npx --yes @stoplight/spectral-cli lint contracts/openapi/api.yaml
+<% } %><% if (it.options.contract === 'rest+events' || it.options.contract === 'events-only') { %>      - |
+        if [ -f contracts/asyncapi/asyncapi.yaml ]; then
+          npx --yes @stoplight/spectral-cli lint contracts/asyncapi/asyncapi.yaml
+        fi
+<% } %>      - |
+        for s in contracts/**/*.schema.json; do
+          [ -e "$s" ] || continue
+          npx --yes ajv-cli compile -s "$s"
+        done
+
+<% if (it.options.backend === 'node') { %>  server-node:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd server
+      - npm ci
+      - npm run lint --if-present
+      - npm run typecheck --if-present
+      - npm test --if-present
+<% } %><% if (it.options.backend === 'java') { %>  server-java:
+    stage: test
+    image: maven:3.9-eclipse-temurin-21
+    script:
+      - cd server
+      - mvn -B verify
+<% } %><% if (it.options.backend === 'go') { %>  server-go:
+    stage: test
+    image: golang:1.22-alpine
+    script:
+      - cd server
+      - go vet ./...
+      - go test ./...
+<% } %><% if (it.options.backend === 'python') { %>  server-python:
+    stage: test
+    image: python:3.12-slim
+    script:
+      - cd server
+      - pip install -e .[dev] || pip install -e .
+      - ruff check .
+      - ruff format --check .
+      - pytest -q
+<% } %>
+<% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>  web:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd web
+      - npm ci
+      - npm run lint --if-present
+      - npm run typecheck --if-present || npx tsc --noEmit
+      - npm test --if-present
+      - npm run build
+<% } %>
+<% if (it.options.mobile === 'flutter') { %>  mobile-flutter:
+    stage: test
+    image: cirrusci/flutter:stable
+    script:
+      - cd mobile
+      - flutter pub get
+      - flutter analyze
+      - flutter test
+<% } %><% if (it.options.mobile === 'react-native') { %>  mobile-react-native:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd mobile
+      - npm ci
+      - npm run lint --if-present
+      - npm test --if-present
+<% } %>
+<% if (it.options.miniapp === 'wechat') { %>  miniapp-wechat:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd miniapp
+      - |
+        if [ -f tsconfig.json ]; then npx tsc --noEmit; else echo "no tsconfig"; fi
+<% } %>
+<% if (it.options.agent === 'rust-desktop') { %>  agent-rust:
+    stage: test
+    image: rust:1.78
+    script:
+      - cd agent
+      - cargo fmt --check
+      - cargo clippy --all-targets -- -D warnings
+      - cargo test
+<% } %>
+  secret-scan:
+    stage: scan
+    image: zricethezav/gitleaks:latest
+    script:
+      - gitleaks detect --redact --no-git -v
+
+<% if (it.options.backend === 'node' || it.options.frontend === 'react' || it.options.frontend === 'vue' || it.options.mobile === 'react-native' || it.options.miniapp === 'wechat') { %>  npm-audit:
+    stage: scan
+    image: node:20-alpine
+    script:
+<% if (it.options.backend === 'node') { %>      - cd server && npm audit --audit-level=high && cd ..
+<% } %><% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>      - cd web && npm audit --audit-level=high && cd ..
+<% } %><% if (it.options.mobile === 'react-native') { %>      - cd mobile && npm audit --audit-level=high && cd ..
+<% } %><% } %>
+<% if (it.options.backend === 'go') { %>  go-vulncheck:
+    stage: scan
+    image: golang:1.22-alpine
+    script:
+      - cd server
+      - go install golang.org/x/vuln/cmd/govulncheck@latest
+      - govulncheck ./...
+<% } %><% if (it.options.backend === 'python') { %>  pip-audit:
+    stage: scan
+    image: python:3.12-slim
+    script:
+      - cd server
+      - pip install pip-audit
+      - pip-audit
+<% } %>

package/src/templates/ci-gitee/fragment.yaml

@@ -1,5 +1,5 @@
 name: ci-gitee
-version: 1.1.0
+version: 1.2.0
 appliesWhen:
   ci: gitee
 priority: 20

package/src/templates/ci-github/files/ci.yml

@@ -4,14 +4,207 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+
+# CI for <%= it.options.projectName %>
+#
+# Generated by `@wneng/create-keel` (Contract First + Vibe Coding).
+# Each job below is independent so a failure in one (e.g. server) does
+# not skip the others. The `governance-lint` and `contract-lint` jobs
+# are always present; per-environment jobs are conditionally included
+# based on the project's options.
+#
+# Tweak version pins / cache keys / extra steps freely; do not delete
+# governance-lint or contract-lint without an ADR.
+
 jobs:
-  checks:
+  governance-lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: contract lint
-        run: echo "spectral lint for <%= it.options.projectName %>"
-      - name: json schema validate
-        run: echo "ajv-cli validate"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: governance-lint
+        run: |
+          if [ -f tools/governance-lint/index.js ]; then
+            node tools/governance-lint/index.js --strict
+          else
+            echo "tools/governance-lint/ not present; skipping"
+          fi
+
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  contract-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>      - name: spectral lint (OpenAPI)
+        run: npx --yes @stoplight/spectral-cli lint contracts/openapi/api.yaml
+<% } %><% if (it.options.contract === 'rest+events' || it.options.contract === 'events-only') { %>      - name: spectral lint (AsyncAPI)
+        run: |
+          if [ -f contracts/asyncapi/asyncapi.yaml ]; then
+            npx --yes @stoplight/spectral-cli lint contracts/asyncapi/asyncapi.yaml
+          else
+            echo "no asyncapi.yaml; skipping"
+          fi
+<% } %>      - name: json-schema validate
+        run: |
+          shopt -s nullglob
+          for s in contracts/**/*.schema.json; do
+            npx --yes ajv-cli compile -s "$s"
+          done
+
+<% if (it.options.backend === 'node') { %>  server-node:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: server/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm run typecheck --if-present
+      - run: npm test --if-present
+      - name: dependency scan
+        run: npm audit --audit-level=high
+<% } %><% if (it.options.backend === 'java') { %>  server-java:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - run: mvn -B verify
+<% } %><% if (it.options.backend === 'go') { %>  server-go:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - run: go vet ./...
+      - run: go test ./...
+      - name: govulncheck
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          govulncheck ./...
+<% } %><% if (it.options.backend === 'python') { %>  server-python:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -e .[dev] || pip install -e .
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy . || true
+      - run: pytest -q
+      - name: pip-audit
+        run: pip install pip-audit && pip-audit
+<% } %>
+<% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>  web:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm run typecheck --if-present || npx tsc --noEmit
+      - run: npm test --if-present
+      - run: npm run build
       - name: dependency scan
-        run: echo "npm audit / pip-audit / trivy"
+        run: npm audit --audit-level=high
+<% } %>
+<% if (it.options.mobile === 'flutter') { %>  mobile-flutter:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mobile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+      - run: flutter pub get
+      - run: flutter analyze
+      - run: flutter test
+<% } %><% if (it.options.mobile === 'react-native') { %>  mobile-react-native:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mobile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: mobile/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm test --if-present
+<% } %>
+<% if (it.options.miniapp === 'wechat') { %>  miniapp-wechat:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: miniapp
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: typecheck
+        run: |
+          if [ -f tsconfig.json ]; then npx tsc --noEmit; else echo "no tsconfig"; fi
+<% } %>
+<% if (it.options.agent === 'rust-desktop') { %>  agent-rust:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: agent
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test
+<% } %>

package/src/templates/ci-github/fragment.yaml

@@ -1,5 +1,5 @@
 name: ci-github
-version: 1.1.0
+version: 1.2.0
 appliesWhen:
   ci: github
 priority: 20

package/src/templates/contracts-base/files/_spectral.yaml

@@ -0,0 +1,21 @@
+# Spectral lint config for OpenAPI / AsyncAPI contracts.
+#
+# Source of truth referenced by docs/governance/integrations.md.
+# CI runs `npx @stoplight/spectral-cli lint contracts/openapi/api.yaml`
+# and aborts on errors.
+
+extends:
+  - 'spectral:oas'
+
+rules:
+  # Make these MUST-have for keel projects.
+  operation-operationId: error
+  operation-tag-defined: error
+  contact-properties: warn
+  info-contact: warn
+  info-license: warn
+
+  # Don't enforce description on every parameter — too noisy on first
+  # commit. Re-enable per project once the API stabilises.
+  operation-description: off
+  operation-parameters: warn

package/src/templates/contracts-base/fragment.yaml

@@ -1,5 +1,5 @@
 name: contracts-base
-version: 1.0.0
+version: 1.1.0
 appliesWhen: {}
 priority: 10
 files:
@@ -12,6 +12,9 @@ files:
   - from: files/CHANGELOG.md
     to: contracts/CHANGELOG.md
     render: false
+  - from: files/_spectral.yaml
+    to: contracts/.spectral.yaml
+    render: false
   - from: files/dictionaries/domain-models.yaml
     to: contracts/dictionaries/domain-models.yaml
     render: false

package/src/templates/server-go/files/_golangci.yml

@@ -0,0 +1,41 @@
+# golangci-lint config for <%= it.options.projectName %>-server.
+# Source of truth referenced by docs/03-工程规范与研发基础设施/coding-style-go.md.
+# CI runs `golangci-lint run` and aborts on errors.
+
+run:
+  timeout: 3m
+  tests: true
+
+linters:
+  disable-all: true
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - revive
+    - gofmt
+    - goimports
+    - misspell
+    - unconvert
+    - nakedret
+
+linters-settings:
+  revive:
+    rules:
+      - name: package-comments
+      - name: exported
+        arguments: ['checkPrivateReceivers', 'sayRepetitiveInsteadOfStutters']
+  goimports:
+    local-prefixes: example.com
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  exclude-rules:
+    - path: _test\.go
+      linters:
+        - errcheck

package/src/templates/server-go/fragment.yaml

@@ -1,5 +1,5 @@
 name: server-go
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   backend: go
 priority: 30
@@ -13,6 +13,9 @@ files:
   - from: files/main.go
     to: server/cmd/server/main.go
     render: false
+  - from: files/_golangci.yml
+    to: server/.golangci.yml
+    render: true
   - from: files/generated-gitkeep
     to: server/generated/.gitkeep
     render: false

package/src/templates/server-java/files/checkstyle.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+    "https://checkstyle.org/dtds/configuration_1_3.dtd">
+<!--
+  Checkstyle config for <%= it.options.projectName %>-server.
+  Source of truth referenced by:
+    docs/03-工程规范与研发基础设施/coding-style-java.md
+
+  Tweak rules with care. CI runs `mvn verify` which invokes
+  `maven-checkstyle-plugin` and aborts on errors.
+-->
+<module name="Checker">
+  <property name="charset" value="UTF-8"/>
+  <property name="severity" value="error"/>
+  <property name="fileExtensions" value="java, properties, xml"/>
+
+  <module name="FileTabCharacter">
+    <property name="eachLine" value="true"/>
+  </module>
+
+  <module name="LineLength">
+    <property name="max" value="120"/>
+    <property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
+  </module>
+
+  <module name="TreeWalker">
+    <!-- Imports -->
+    <module name="AvoidStarImport"/>
+    <module name="UnusedImports"/>
+
+    <!-- Naming -->
+    <module name="PackageName">
+      <property name="format" value="^[a-z]+(\.[a-z][a-z0-9]*)*$"/>
+    </module>
+    <module name="TypeName"/>
+    <module name="MethodName"/>
+    <module name="LocalVariableName"/>
+    <module name="ConstantName"/>
+
+    <!-- Whitespace / blocks -->
+    <module name="EmptyBlock"/>
+    <module name="LeftCurly"/>
+    <module name="RightCurly"/>
+    <module name="NeedBraces"/>
+
+    <!-- JavaDoc on public types and methods -->
+    <module name="MissingJavadocType">
+      <property name="scope" value="public"/>
+    </module>
+    <module name="JavadocMethod">
+      <property name="accessModifiers" value="public"/>
+    </module>
+
+    <!-- Misc -->
+    <module name="ModifierOrder"/>
+    <module name="RedundantModifier"/>
+    <module name="MissingSwitchDefault"/>
+    <module name="EqualsHashCode"/>
+    <module name="StringLiteralEquality"/>
+  </module>
+</module>

package/src/templates/server-java/files/pom.xml

@@ -92,6 +92,63 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
+
+            <!--
+                Checkstyle: enforces naming, structure, JavaDoc rules from
+                docs/03-工程规范与研发基础设施/coding-style-java.md.
+                Aborts the build on violations during `mvn verify`.
+            -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>3.5.0</version>
+                <configuration>
+                    <configLocation>checkstyle.xml</configLocation>
+                    <consoleOutput>true</consoleOutput>
+                    <failsOnError>true</failsOnError>
+                    <linkXRef>false</linkXRef>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>verify-checkstyle</id>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <!--
+                Spotless: format checker (Google Java Format AOSP style).
+                `mvn spotless:check` is wired into verify; run
+                `mvn spotless:apply` locally to auto-format.
+            -->
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>2.43.0</version>
+                <configuration>
+                    <java>
+                        <googleJavaFormat>
+                            <version>1.22.0</version>
+                            <style>AOSP</style>
+                        </googleJavaFormat>
+                        <removeUnusedImports/>
+                        <trimTrailingWhitespace/>
+                        <endWithNewline/>
+                    </java>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>verify-spotless</id>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 </project>

package/src/templates/server-java/fragment.yaml

@@ -1,5 +1,5 @@
 name: server-java
-version: 1.1.0
+version: 1.2.0
 appliesWhen:
   backend: java
 priority: 30
@@ -19,6 +19,9 @@ files:
   - from: files/application-test.yaml
     to: server/src/test/resources/application-test.yaml
     render: false
+  - from: files/checkstyle.xml
+    to: server/checkstyle.xml
+    render: true
   - from: files/generated-gitkeep
     to: server/generated/.gitkeep
     render: false

package/src/templates/server-node/files/_eslintrc.cjs

@@ -0,0 +1,20 @@
+/**
+ * ESLint configuration for the Node + TypeScript server.
+ *
+ * Source of truth referenced by:
+ *   docs/03-工程规范与研发基础设施/coding-style-typescript.md
+ */
+module.exports = {
+  root: true,
+  env: { node: true, es2022: true },
+  parser: '@typescript-eslint/parser',
+  parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
+  plugins: ['@typescript-eslint'],
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/consistent-type-imports': 'warn',
+  },
+  ignorePatterns: ['dist', 'node_modules', 'generated'],
+};

package/src/templates/server-node/files/_prettierrc

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}