@geek-fun/serverlessinsight 0.9.2 → 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/.serverlessinsight/state-cdn-flow-app-cdn-flow-service.json.backup +1 -1
  2. package/.serverlessinsight/state-iam-test-app-iam-test-service.json.backup +2 -2
  3. package/.serverlessinsight/state-insight-poc-app-insight-poc-tencent.json.backup +4 -8
  4. package/.serverlessinsight/state-insight-poc-app-log-insight-poc-tencent-log.json.backup +3 -8
  5. package/.serverlessinsight/state-insight-poc-deploy-app-insight-poc-deploy.json.backup +4 -4
  6. package/.serverlessinsight/state-insight-poc-destroy-app-insight-poc-destroy.json.backup +1 -1
  7. package/.serverlessinsight/state-insight-poc-timer-app-insight-poc-timer.json.backup +28 -5
  8. package/.serverlessinsight/state-insight-volc-app-insight-volc.json.backup +2 -2
  9. package/.serverlessinsight/state-insight-volc-nested-app-insight-volc-nested.json.backup +3 -3
  10. package/.serverlessinsight/state-nested-drift-app-nested-drift-service.json.backup +20 -5
  11. package/.serverlessinsight/state-role-reconcile-test-app-role-reconcile-test-service.json.backup +3 -3
  12. package/AGENTS.md +10 -0
  13. package/CHANGELOG.md +62 -0
  14. package/README.md +256 -175
  15. package/README.zh-CN.md +249 -159
  16. package/dist/package.json +22 -19
  17. package/dist/src/commands/index.js +21 -52
  18. package/dist/src/commands/local.js +16 -3
  19. package/dist/src/commands/plan.js +35 -4
  20. package/dist/src/common/aliyunClient/apigwOperations.js +48 -9
  21. package/dist/src/common/aliyunClient/fc3Operations.js +7 -1
  22. package/dist/src/common/aliyunClient/ossOperations.js +214 -221
  23. package/dist/src/common/bucketPolicy.js +63 -0
  24. package/dist/src/common/domainUtils.js +4 -1
  25. package/dist/src/common/functionDefinition.js +25 -0
  26. package/dist/src/common/index.js +4 -0
  27. package/dist/src/common/jsonOutput.js +6 -1
  28. package/dist/src/common/nameBuilder.js +3 -1
  29. package/dist/src/common/planCapabilities.js +119 -0
  30. package/dist/src/common/planCompare.js +119 -66
  31. package/dist/src/common/planFormatter.js +22 -14
  32. package/dist/src/common/planRedaction.js +26 -0
  33. package/dist/src/common/refreshPlanner.js +66 -21
  34. package/dist/src/common/tencentClient/cosOperations.js +326 -322
  35. package/dist/src/common/tencentClient/scfOperations.js +9 -2
  36. package/dist/src/common/tencentClient/tdsqlcOperations.js +6 -11
  37. package/dist/src/common/triggerMapper.js +16 -1
  38. package/dist/src/common/volcengineClient/apigwOperations.js +82 -0
  39. package/dist/src/common/volcengineClient/iamOperations.js +27 -3
  40. package/dist/src/common/volcengineClient/tosOperations.js +62 -56
  41. package/dist/src/lang/en.js +33 -8
  42. package/dist/src/lang/index.js +28 -14
  43. package/dist/src/lang/zh-CN.js +33 -8
  44. package/dist/src/parser/eventParser.js +1 -0
  45. package/dist/src/parser/functionParser.js +1 -1
  46. package/dist/src/stack/aliyunStack/apigwDomainPlan.js +82 -0
  47. package/dist/src/stack/aliyunStack/apigwExecutor.js +4 -1
  48. package/dist/src/stack/aliyunStack/apigwPlanner.js +165 -25
  49. package/dist/src/stack/aliyunStack/apigwResource.js +172 -126
  50. package/dist/src/stack/aliyunStack/apigwTypes.js +3 -7
  51. package/dist/src/stack/aliyunStack/deployer.js +2 -0
  52. package/dist/src/stack/aliyunStack/esServerlessTypes.js +8 -4
  53. package/dist/src/stack/aliyunStack/fc3Executor.js +7 -3
  54. package/dist/src/stack/aliyunStack/fc3Planner.js +124 -155
  55. package/dist/src/stack/aliyunStack/fc3Resource.js +48 -52
  56. package/dist/src/stack/aliyunStack/fc3Types.js +30 -16
  57. package/dist/src/stack/aliyunStack/ossPlanner.js +15 -1
  58. package/dist/src/stack/aliyunStack/ossResource.js +113 -102
  59. package/dist/src/stack/aliyunStack/ossTypes.js +20 -20
  60. package/dist/src/stack/localStack/aliyunFc.js +1 -6
  61. package/dist/src/stack/localStack/event.js +31 -60
  62. package/dist/src/stack/localStack/function.js +24 -65
  63. package/dist/src/stack/localStack/functionRunner.js +10 -2
  64. package/dist/src/stack/localStack/httpAdapter.js +54 -0
  65. package/dist/src/stack/localStack/httpError.js +5 -0
  66. package/dist/src/stack/localStack/legacyLambda.js +26 -0
  67. package/dist/src/stack/localStack/localContext.js +29 -0
  68. package/dist/src/stack/localStack/localRoute.js +12 -0
  69. package/dist/src/stack/localStack/localRuntimes.js +22 -0
  70. package/dist/src/stack/localStack/localServer.js +8 -3
  71. package/dist/src/stack/localStack/requestBody.js +24 -0
  72. package/dist/src/stack/localStack/requestId.js +18 -0
  73. package/dist/src/stack/localStack/tencent.js +147 -0
  74. package/dist/src/stack/localStack/timer.js +23 -2
  75. package/dist/src/stack/localStack/volcengine.js +68 -0
  76. package/dist/src/stack/scfStack/cosPlanner.js +9 -14
  77. package/dist/src/stack/scfStack/cosResource.js +42 -50
  78. package/dist/src/stack/scfStack/cosTypes.js +19 -14
  79. package/dist/src/stack/scfStack/deployer.js +2 -0
  80. package/dist/src/stack/scfStack/scfExecutor.js +7 -3
  81. package/dist/src/stack/scfStack/scfHttpTrigger.js +106 -0
  82. package/dist/src/stack/scfStack/scfPlanner.js +67 -16
  83. package/dist/src/stack/scfStack/scfResource.js +170 -321
  84. package/dist/src/stack/scfStack/scfTypes.js +4 -3
  85. package/dist/src/stack/scfStack/tdsqlcPlanner.js +10 -13
  86. package/dist/src/stack/volcengineStack/apigwDomains.js +64 -0
  87. package/dist/src/stack/volcengineStack/apigwPlanner.js +71 -15
  88. package/dist/src/stack/volcengineStack/apigwResource.js +60 -24
  89. package/dist/src/stack/volcengineStack/apigwTypes.js +5 -1
  90. package/dist/src/stack/volcengineStack/deployer.js +6 -0
  91. package/dist/src/stack/volcengineStack/tosPlanner.js +8 -13
  92. package/dist/src/stack/volcengineStack/tosResource.js +22 -35
  93. package/dist/src/stack/volcengineStack/tosTypes.js +5 -8
  94. package/dist/src/stack/volcengineStack/vefaasPlanner.js +142 -49
  95. package/dist/src/stack/volcengineStack/vefaasResource.js +17 -12
  96. package/dist/src/stack/volcengineStack/vefaasTypes.js +6 -3
  97. package/dist/tsconfig.tsbuildinfo +1 -1
  98. package/package.json +22 -19
  99. package/release-notes.md +53 -0
  100. package/samples/README_TENCENT_COS.md +3 -3
  101. package/samples/README_TENCENT_SCF.md +3 -3
  102. package/samples/tencent-local/index.js +13 -0
  103. package/samples/tencent-local/serverlessinsight.yml +23 -0
  104. package/samples/volcengine-local/index.js +13 -0
  105. package/samples/volcengine-local/serverlessinsight.yml +28 -0
package/README.md CHANGED
@@ -1,29 +1,33 @@
1
1
  <div align="center">
2
2
 
3
- # ServerlessInsight
3
+ <img src="docs/brand/brand.jpg" alt="ServerlessInsight" width="420" />
4
4
 
5
- **Full life cycle cross-provider serverless management — describe your app, we handle the rest.**
5
+ # ServerlessInsight
6
6
 
7
- **Open source. Multi-cloud. Infrastructure as Code.**
7
+ **Full-lifecycle serverless IaC for Alibaba Cloud, Tencent Cloud and Volcengine.**
8
8
 
9
- **Serverless CLI for Alibaba Cloud · Tencent Cloud · Huawei Cloud · Volcengine.**
9
+ Define functions, API gateways, storage and databases in one YAML — preview the plan, deploy with confidence, and operate it in production.
10
10
 
11
11
  [![Release](https://img.shields.io/github/v/release/geek-fun/serverlessinsight?color=orange&label=release&logo=github)](https://github.com/geek-fun/serverlessinsight/releases)
12
12
  [![npm version](https://img.shields.io/npm/v/@geek-fun/serverlessinsight?color=orange&logo=npm)](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
13
- [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg&logo=apache)](LICENSE)
14
- [![Stars](https://img.shields.io/github/stars/geek-fun/serverlessinsight&logo=github)](https://github.com/geek-fun/serverlessinsight/stargazers)
13
+ [![npm downloads](https://img.shields.io/npm/dm/@geek-fun/serverlessinsight?color=orange&logo=npm)](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
14
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?logo=apache)](LICENSE)
15
15
  [![CI](https://github.com/geek-fun/serverlessinsight/actions/workflows/node.yml/badge.svg)](https://github.com/geek-fun/serverlessinsight/actions/workflows/node.yml)
16
+ [![Stars](https://img.shields.io/github/stars/geek-fun/serverlessinsight?logo=github)](https://github.com/geek-fun/serverlessinsight/stargazers)
17
+ [![Issues](https://img.shields.io/github/issues/geek-fun/serverlessinsight?logo=github)](https://github.com/geek-fun/serverlessinsight/issues)
18
+
19
+ <p>
20
+ <img src="https://img.shields.io/badge/Node.js-%3E%3D22.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 22.12" />
21
+ <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
22
+ </p>
16
23
 
17
24
  <p>
18
- <img src="https://img.shields.io/badge/Node.js-339933&logo=nodedotjs&logoColor=white"/>
19
- <img src="https://img.shields.io/badge/TypeScript-3178C6&logo=typescript&logoColor=white"/>
20
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00&logo=alibabacloud&logoColor=white"/>
21
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED&logo=tencentqq&logoColor=white"/>
22
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white"/>
23
- <img src="https://img.shields.io/badge/AWS-232F3E&logo=amazonwebservices&logoColor=white"/>
25
+ <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" alt="Alibaba Cloud" />
26
+ <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" alt="Tencent Cloud" />
27
+ <img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" alt="Volcengine" />
24
28
  </p>
25
29
 
26
- [npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [Docs](https://serverlessinsight.geekfun.club) · [Website](https://serverlessinsight.geekfun.club) · [GitHub](https://github.com/geek-fun/serverlessinsight)
30
+ [npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [Documentation](https://serverlessinsight.com/docs.html) · [Website](https://serverlessinsight.com) · [Samples](samples) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/geek-fun/serverlessinsight/issues)
27
31
 
28
32
  English · [简体中文](README.zh-CN.md)
29
33
 
@@ -31,129 +35,176 @@ English · [简体中文](README.zh-CN.md)
31
35
 
32
36
  ---
33
37
 
34
- ServerlessInsight is a **cross-provider serverless framework** — it replaces cloud-specific CLI tools, web consoles, and DIY scripts with a single unified tool. Define your serverless infrastructure in YAML once, deploy to Alibaba Cloud, Tencent Cloud, Huawei Cloud, and more. Think of it as Terraform for serverless, purpose-built for functions, API gateways, storage, and databases.
38
+ ServerlessInsight (`si`) is an open-source, cross-cloud serverless framework. Instead of juggling provider-specific CLIs, console clicks and one-off scripts, you describe the whole serverless stack — functions, HTTP endpoints, object storage, databases and tables — in a single YAML file, then let `si` plan, deploy and operate it.
35
39
 
36
- <p align="center">
37
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" />
38
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" />
39
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white" />
40
- <img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" />
41
- <img src="https://img.shields.io/badge/AWS-232F3E?logo=amazonwebservices&logoColor=white" />
42
- <img src="https://img.shields.io/badge/Azure-0078D4?logo=microsoftazure&logoColor=white" />
43
- <img src="https://img.shields.io/badge/GCP-4285F4?logo=googlecloud&logoColor=white" />
44
- </p>
40
+ Think Terraform for serverless: one declarative workflow with state tracking and drift detection, built around functions, API gateways and serverless data services. No vendor lock-in, Apache-2.0 licensed.
41
+
42
+ **Deployable today:** Alibaba Cloud, Tencent Cloud and Volcengine. Huawei Cloud, AWS, Azure and Google Cloud are on the [roadmap](#roadmap).
43
+
44
+ ## Table of contents
45
+
46
+ - [Quick start](#quick-start)
47
+ - [Why ServerlessInsight](#why-serverlessinsight)
48
+ - [Features](#features)
49
+ - [Supported providers](#supported-providers)
50
+ - [Documentation](#documentation)
51
+ - [Roadmap](#roadmap)
52
+ - [Architecture](#architecture)
53
+ - [Development](#development)
54
+ - [Community](#community)
55
+ - [Contributing](#contributing)
56
+ - [Sponsor](#sponsor)
57
+ - [License](#license)
58
+
59
+ ## Quick start
45
60
 
46
- ## Installation
61
+ **Requires Node.js 22.12 or later.**
47
62
 
48
63
  ```bash
49
64
  npm install -g @geek-fun/serverlessinsight
50
65
  si --version
51
66
  ```
52
67
 
53
- ## Key Features
68
+ Create `serverlessinsight.yml`:
69
+
70
+ ```yaml
71
+ version: 0.0.1
72
+
73
+ provider:
74
+ name: aliyun
75
+ region: cn-hongkong
76
+
77
+ app: hello-world
78
+ service: hello-world-api
79
+
80
+ functions:
81
+ hello_function:
82
+ name: hello-world-fn
83
+ code:
84
+ runtime: nodejs18
85
+ handler: index.handler
86
+ path: ./src
87
+ memory: 512
88
+ timeout: 10
89
+
90
+ events:
91
+ api_gateway:
92
+ type: API_GATEWAY
93
+ name: my-api-gateway
94
+ triggers:
95
+ - method: GET
96
+ path: /api/hello
97
+ backend: ${functions.hello_function}
98
+ ```
54
99
 
55
- ### Multi-Cloud, One Config
100
+ Then:
56
101
 
57
- Define your infrastructure once in YAML and deploy across Alibaba Cloud, Tencent Cloud, Huawei Cloud, and Volcengine — with AWS, Azure, and GCP on the roadmap. No more juggling cloud-specific CLIs or Terraform modules for every provider.
102
+ ```bash
103
+ si validate # check the config against the IaC schema
104
+ si diff # show what would change, without saving state
105
+ si deploy --stage prod # show the plan, confirm, and apply
106
+ si local # run the app locally on http://localhost:4567
107
+ si destroy --stage prod # remove everything si created
108
+ ```
58
109
 
59
- - **Unified configuration** — single `serverless.yml` format for all providers
60
- - **Provider-specific template generation** — generate native IaC templates from your config
61
- - **Cross-provider awareness** — the same abstractions work across different clouds
110
+ `si` discovers `serverlessinsight.yml` in the current directory; pass `-f <path>` for a different file name. To target another cloud, change `provider.name` to `tencent` or `volcengine` — runtimes, triggers and resources are mapped to native services per provider.
62
111
 
63
- | Provider | Functions | API Gateway | Storage | Databases | Status |
64
- | ----------------- | ---------------- | -------------- | -------------- | ---------------- | ------- |
65
- | **Alibaba Cloud** | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS, OTS, ESS | Stable |
66
- | **Tencent Cloud** | ✅ SCF | 🚧 Coming Soon | ✅ COS | ✅ TDSQL-C | Stable |
67
- | **Volcengine** | ✅ veFaaS | ✅ API Gateway | ✅ TOS | — | Stable |
68
- | **Huawei Cloud** | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | Planned |
69
- | **AWS** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
70
- | **Azure** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
71
- | **Google Cloud** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
112
+ ## Why ServerlessInsight
72
113
 
73
- ### Infrastructure as Code
114
+ - **Serverless-native, not generic IaC.** Functions, triggers, API gateways, domains, buckets, databases and tables are first-class resources with provider-aware defaults — no hand-written Terraform modules or SDK wrapper scripts.
115
+ - **One YAML across clouds.** The same primitives and stage/variable system apply to every supported provider, so switching clouds is a `provider.name` change, not a rewrite.
116
+ - **Plan before anything happens.** `si diff` reads state and live resources without writing anything; `si deploy` executes exactly the plan you approved, and manual console changes surface as drift.
117
+ - **Built for automation.** Logs go to stderr and machine-readable results to stdout, every JSON envelope is versioned, error codes are stable across locales, and exit codes follow Terraform conventions.
118
+ - **Real local development.** Run your handlers, HTTP routes, timer schedules and bucket endpoints locally with the same configuration — no cloud account or credentials needed.
119
+ - **Open source, no lock-in.** Apache-2.0, state in a local file or your own bucket, and no proprietary runtime to adopt.
74
120
 
75
- Declarative YAML configuration with validation, planning, and state management — following proven IaC patterns.
121
+ ## Features
76
122
 
77
- - **Plan before deploy** — `si plan` shows exactly what will change before anything happens
78
- - **State tracking** — incremental deployments with drift detection via local state files
79
- - **Validation** — type-safe template validation catches config errors before they reach the cloud
80
- - **Partial failure recovery** — successfully deployed resources are saved even when others fail; retry to continue
123
+ ### Multi-cloud, one config
81
124
 
82
- ### Quick Deployment
125
+ Define infrastructure once and deploy across Alibaba Cloud, Tencent Cloud and Volcengine. Provider differences — runtime identifiers, cron dialects, gateway resources, ownership tags — are resolved by the framework, not by your YAML.
83
126
 
84
- ```bash
85
- # Validate your config
86
- si validate -f serverless.yml
127
+ - **Unified configuration** — one `serverlessinsight.yml` format for every provider
128
+ - **Provider-specific mapping** — runtime names, trigger shapes and resource types are translated to native values
129
+ - **Cross-provider awareness** — the same functions, buckets, databases and events work across clouds
87
130
 
88
- # Preview changes
89
- si plan -f serverless.yml
131
+ ### Plan before deploy
90
132
 
91
- # Deploy to production
92
- si deploy -f serverless.yml -s prod
133
+ `si diff` previews every change on Alibaba Cloud, Tencent Cloud and Volcengine. It reads the configured state backend and live cloud resources without applying changes or saving state.
93
134
 
94
- # Destroy when done
95
- si destroy -f serverless.yml
135
+ ```bash
136
+ si diff --stage dev
137
+ si diff --stage dev --json
138
+ si diff --stage dev --region cn-beijing -p memory=1024
139
+ si diff --stage dev --no-refresh
96
140
  ```
97
141
 
98
- ### Using si with AI agents & scripts
142
+ Use `-p, --parameter <key=value>` repeatedly to override configuration variables. `--no-refresh` skips live drift checks for tracked resources; ownership probes for new resources still run. Credentials and the selected state backend must be configured. Read failures exit with an error. Migrated legacy state produces a warning and remains unchanged.
143
+
144
+ Volcengine plans include functions, TOS buckets and API Gateway resources in dependency order.
145
+
146
+ **Exit codes**: `si diff` exits `0` when there are no changes, `2` when changes are present (Terraform convention), and `1` on errors. `si validate` exits `0` when valid and `1` when validation fails.
99
147
 
100
- The CLI is built to be driven by agents and shell scripts: logs always go to
101
- **stderr** while result data goes to **stdout**, so piping stdout into `jq`
102
- always yields a single parseable JSON document.
148
+ ### Infrastructure as code
149
+
150
+ Declarative YAML with validation, planning and state management, following proven IaC patterns.
151
+
152
+ - **State tracking** — incremental deployments from `.serverlessinsight/` state, with local, bucket and SaaS backends
153
+ - **Drift detection** — resources changed outside `si` are flagged before the next deploy
154
+ - **Validation** — type-safe template validation catches config errors before they reach the cloud
155
+ - **Partial failure recovery** — successfully deployed resources are saved even when others fail; retry to continue
156
+ - **State locking** — concurrent deploys are blocked, with `si force-unlock` as the escape hatch
157
+
158
+ ### Built for agents and scripts
159
+
160
+ The CLI is designed to be driven by agents and shell scripts: logs always go to **stderr** while result data goes to **stdout**, so piping stdout into `jq` always yields a single parseable JSON document.
103
161
 
104
162
  ```bash
105
- si plan --json -f serverless.yml | jq '.summary'
106
- si validate --json -f serverless.yml | jq '.valid'
107
- si show --json -f serverless.yml | jq '.resourceCount'
108
- si schema | jq '.$id' # self-contained draft-07 JSON Schema of the IaC format
163
+ si diff --json | jq '.summary'
164
+ si validate --json | jq '.valid'
165
+ si show --json | jq '.resourceCount'
166
+ si schema | jq '."$id"' # self-contained draft-07 JSON Schema of the IaC format
109
167
  ```
110
168
 
111
- **Stable output envelopes** (each carries a version field, so shapes only ever
112
- change under a new version):
113
-
114
- - `si plan --json` → `{ planVersion: 1, provider, app, service, stage,
115
- changes: [{ logicalId, type, action: "create|update|destroy|recreate",
116
- attributes, drifted?, driftReasons? }], summary: { create, update, destroy,
117
- recreate, unchanged } }`
118
- - `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path,
119
- keyword, message, allowedValues? }] }`
120
- - `si show --json` → `{ showVersion: 1, provider, app, service, stage,
121
- stateLocation, backend: "saas|bucket_store|local", locked, lock, resources,
122
- resourceCount, ... }`
169
+ <details>
170
+ <summary><b>Stable output envelopes, error codes and color behavior</b></summary>
171
+
172
+ Stable output envelopes (each carries a version field, so shapes only ever change under a new version):
173
+
174
+ - `si diff --json` → `{ planVersion: 1, provider, app, service, stage, changes: [{ logicalId, type, action: "create|update|destroy|recreate", attributes, drifted?, driftReasons? }], summary: { create, update, destroy, recreate, unchanged } }`
175
+ - `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path, keyword, message, allowedValues? }] }`
176
+ - `si show --json` → `{ showVersion: 1, provider, app, service, stage, stateLocation, backend: "saas|bucket_store|local", locked, lock, resources, resourceCount, ... }`
123
177
  - failures (in `--json` mode) → `{ error: { code, message } }` on stdout
124
178
 
125
- **Exit codes**: `si plan` exits `0` when there are no changes, `2` when
126
- changes are present (terraform convention), `1` on errors. `si validate`
127
- exits `0` when valid, `1` when validation fails.
179
+ Stable error codes: error `code`s are the i18n message keys behind the translated message (e.g. `RAM_ROLE_NOT_FOUND_IN_CLOUD`) — they are identical under every locale, so agents can map codes to self-healing actions regardless of `LANG`.
128
180
 
129
- **Stable error codes**: error `code`s are the i18n message keys behind the
130
- translated message (e.g. `RAM_ROLE_NOT_FOUND_IN_CLOUD`) — they are identical
131
- under every locale, so agents can map codes to self-healing actions regardless
132
- of `LANG`.
181
+ Colors: ANSI color is disabled when the `NO_COLOR` environment variable is set ([no-color.org](https://no-color.org)) or `--no-color` is passed, keeping piped output clean in non-TTY environments.
133
182
 
134
- **Colors**: ANSI color is disabled when the `NO_COLOR` environment variable is
135
- set ([no-color.org](https://no-color.org)) or `--no-color` is passed, keeping
136
- piped output clean in non-TTY environments.
183
+ </details>
137
184
 
138
- ### Local Development
185
+ ### Local development
139
186
 
140
- Run and debug your serverless functions locally without deploying to the cloud.
187
+ Run and debug serverless functions locally without deploying to the cloud or configuring credentials.
141
188
 
142
- - **LocalStack server** — test functions, buckets, and API endpoints locally
143
- - **Timer triggers fire locally** — `functions.*.triggers.timer` schedules run against UTC wall-clock (`@every` from server start) and invoke your handler with the provider's timer event shape
144
- - **Bucket file serving** — access local storage files via HTTP for rapid iteration
145
- - **Same config, different target** — `si local -f serverless.yml -s local` uses your existing config
189
+ - **HTTP functions** — provider-native event, context and response translation for Aliyun FC, Tencent SCF function URLs and Volcengine veFaaS
190
+ - **Timer triggers** — `functions.*.triggers.timer` schedules fire against UTC wall-clock and invoke your handler with the provider's timer event shape
191
+ - **Bucket file serving** — access local storage files over HTTP for rapid iteration
192
+ - **Watch mode** — code changes reload automatically
193
+ - **Same config, different target** — `si local -s dev` reuses your existing configuration
146
194
 
147
- ### API Gateway & Custom Domain
195
+ See [Local development](docs/local-development.md) for the supported subset and runnable examples: [Tencent SCF](samples/tencent-local/serverlessinsight.yml) and [Volcengine veFaaS](samples/volcengine-local/serverlessinsight.yml).
196
+
197
+ ### API gateway & custom domains
148
198
 
149
199
  Configure HTTP endpoints and bind custom domains with automatic DNS verification.
150
200
 
151
- - **API Gateway integration** — define triggers with HTTP methods and paths
152
- - **Custom domain binding** — automatic CNAME + DNS TXT ownership verification for OSS and API Gateway
201
+ - **HTTP triggers** — define triggers with HTTP methods and paths, backed by a function
202
+ - **Custom domains** — automatic CNAME + DNS TXT ownership verification for OSS and API Gateway on Alibaba Cloud, and DNSPod-backed domains on Tencent Cloud
153
203
  - **CDN acceleration** — edge caching and global content delivery for static sites
154
- - **OSS Transfer Acceleration** — cross-region data transfers through Alibaba backbone
204
+ - **OSS transfer acceleration** — cross-region data transfers through the Alibaba backbone
205
+ - **Tencent function URLs** — HTTP entry points without a standalone gateway resource
155
206
 
156
- ### Timer Triggers
207
+ ### Timer triggers
157
208
 
158
209
  Schedule functions with a provider-agnostic `si-cron` expression under `functions.*.triggers.timer`:
159
210
 
@@ -171,33 +222,69 @@ functions:
171
222
  cron: '@every 1h'
172
223
  ```
173
224
 
174
- `cron` accepts a standard 5-field expression (`minute hour day month weekday`),
175
- a 6-field expression with a seconds prefix, or `@every <duration>` (`30s`,
176
- `5m`, `1h`, `1d`, …). si-cron is always **UTC** — the synthesis layer
177
- translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF
178
- 7-field with year, Volcengine veFaaS 5-field crontab) including the UTC+8
179
- field shift, so the same YAML fires at the same instant everywhere. Invalid
180
- expressions and provider capability limits (Tencent SCF allows at most 10
181
- timers per function) fail at `si validate`, before any deploy.
225
+ `cron` accepts a standard 5-field expression (`minute hour day month weekday`), a 6-field expression with a seconds prefix, or `@every <duration>` (`30s`, `5m`, `1h`, `1d`, …). si-cron is always **UTC** — the synthesis layer translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF 7-field with year, Volcengine veFaaS 5-field crontab), including the UTC+8 field shift, so the same YAML fires at the same instant everywhere. Invalid expressions and provider capability limits (Tencent SCF allows at most 10 timers per function) fail at `si validate`, before any deploy.
182
226
 
183
- **`functions.*.triggers` vs top-level `events`**: `triggers` (http, timer)
184
- are things that *invoke this function* — they are function-owned, die with
185
- the function, and have no independent configuration surface. Top-level
186
- `events` (e.g. `API_GATEWAY`) are infrastructure resources with their own
187
- config face — custom domains, certificates, route tables — that keep living
188
- when a backend function is removed. Rule of thumb: independent
189
- configuration surface → `events`; pure scheduling/event binding → `triggers`.
227
+ <details>
228
+ <summary><b><code>triggers</code> vs top-level <code>events</code></b></summary>
190
229
 
191
- ### Resource Management
230
+ `functions.*.triggers` (http, timer) are things that *invoke this function* — they are function-owned, die with the function, and have no independent configuration surface. Top-level `events` (e.g. `API_GATEWAY`) are infrastructure resources with their own config face — custom domains, certificates, route tables — that keep living when a backend function is removed. Rule of thumb: independent configuration surface → `events`; pure scheduling/event binding → `triggers`.
192
231
 
193
- Beyond functions — manage the full serverless stack including storage, databases, and more.
232
+ </details>
194
233
 
195
- - **Object storage** — OSS (Alibaba), COS (Tencent), TOS (Volcengine)
196
- - **Databases** — RDS, OTS, ESS, TDSQL-C with more on the way
197
- - **Elasticsearch Serverless** — deploy and manage ES clusters
198
- - **GPU functions** — deploy GPU-enabled serverless functions
234
+ ### Resource management
235
+
236
+ Beyond functions — manage the full serverless stack, including storage, databases and tables.
199
237
 
200
- ### Architecture
238
+ - **Object storage** — OSS (Alibaba), COS (Tencent), TOS (Volcengine)
239
+ - **Databases** — RDS MySQL Serverless, TDSQL-C and Elasticsearch Serverless
240
+ - **Tables** — TableStore on Alibaba Cloud
241
+ - **GPU functions** — deploy GPU-enabled serverless functions on Alibaba Cloud
242
+
243
+ ## Supported providers
244
+
245
+ | Provider | Functions | HTTP entry | Object storage | Databases & tables | Status |
246
+ | ----------------- | ---------------------------- | ------------------------- | -------------- | ----------------------------------------------------------- | ------- |
247
+ | **Alibaba Cloud** | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS MySQL Serverless, TableStore, Elasticsearch Serverless | Stable |
248
+ | **Tencent Cloud** | ✅ SCF | ✅ Function URL triggers | ✅ COS | ✅ TDSQL-C, Elasticsearch Serverless | Stable |
249
+ | **Volcengine** | ✅ veFaaS | ✅ API Gateway | ✅ TOS | — | Stable |
250
+ | **Huawei Cloud** | ⚠️ Terraform template only | — | — | — | Preview |
251
+ | **AWS** | — | — | — | — | Planned |
252
+ | **Azure** | — | — | — | — | Planned |
253
+ | **Google Cloud** | — | — | — | — | Planned |
254
+
255
+ Notes:
256
+
257
+ - Huawei Cloud configuration is parsed and can generate Terraform HCL templates, but deployment is not implemented yet.
258
+ - Tencent Cloud has no standalone API Gateway resource; HTTP entry points use function URL triggers.
259
+ - Volcengine does not yet support serverless databases or tables.
260
+ - See the [full provider matrix](https://serverlessinsight.com/reference.html) for resource-level details.
261
+
262
+ ## Documentation
263
+
264
+ | Resource | Link |
265
+ | ------------------------- | --------------------------------------------------------------------- |
266
+ | Getting started | <https://serverlessinsight.com/getting-started.html> |
267
+ | Configuration reference | <https://serverlessinsight.com/reference.html> |
268
+ | CLI reference | <https://serverlessinsight.com/cli.html> |
269
+ | JSON Schema | `si schema` (self-contained draft-07) |
270
+ | Local development | [docs/local-development.md](docs/local-development.md) |
271
+ | State locking | [docs/state-locking.md](docs/state-locking.md) |
272
+ | Architecture decisions | [docs/adr](docs/adr) |
273
+ | Samples | [samples](samples) |
274
+ | Changelog | [CHANGELOG.md](CHANGELOG.md) |
275
+ | FAQ | <https://serverlessinsight.com/faq.html> |
276
+
277
+ ## Roadmap
278
+
279
+ - Huawei Cloud function deployment (template generation exists today)
280
+ - AWS, Azure and Google Cloud providers
281
+ - Tencent Cloud standalone API Gateway resources
282
+ - Volcengine serverless databases and tables
283
+ - More serverless resources and provider capabilities
284
+
285
+ Roadmap items are directional, not commitments. Open an issue to discuss priorities.
286
+
287
+ ## Architecture
201
288
 
202
289
  ServerlessInsight follows a **functional client architecture** that cleanly separates cloud provider SDKs from business logic:
203
290
 
@@ -209,27 +296,29 @@ ServerlessInsight follows a **functional client architecture** that cleanly sepa
209
296
  ↓
210
297
  ┌─────────────────────────────────────────┐
211
298
  │ Functional Client Layer │ ← Encapsulated SDK operations
212
- │ (aliyunClient.ts, tencentClient.ts) │
299
+ │ (aliyunClient, tencentClient, │
300
+ │ volcengineClient) │
213
301
  └─────────────────────────────────────────┘
214
302
  ↓
215
303
  ┌─────────────────────────────────────────┐
216
- │ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*
304
+ │ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*, @volcengine/*
217
305
  └─────────────────────────────────────────┘
218
306
  ```
219
307
 
220
- - **Functional & pure** — business logic uses pure functions with immutable data
221
- - **SDK encapsulation** — provider SDKs accessed ONLY through client modules
222
- - **No classes** — prefer `type` over `interface`, functional patterns over classes
308
+ - **Functional and pure** — business logic uses pure functions with immutable data
309
+ - **SDK encapsulation** — provider SDKs are accessed only through client modules
310
+ - **Functional-first** — `type` over `interface`, functions over classes, declarative collection handling
223
311
 
224
312
  ## Development
225
313
 
226
- ServerlessInsight is built with [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/), [Commander.js](https://github.com/tj/commander.js/) CLI, and pure functional architecture.
314
+ ServerlessInsight is built with [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/), [Commander.js](https://github.com/tj/commander.js/) for the CLI, and a functional architecture.
227
315
 
228
316
  ### Prerequisites
229
317
 
230
- - **Node.js** >= 16
318
+ - **Node.js** >= 22.12
319
+ - **npm** (bundled with Node.js)
231
320
 
232
- ### Quick Start
321
+ ### Build from source
233
322
 
234
323
  ```bash
235
324
  git clone https://github.com/geek-fun/serverlessinsight.git
@@ -241,56 +330,52 @@ npm link
241
330
 
242
331
  ### Scripts
243
332
 
244
- | Command | Description |
245
- |---------|-------------|
246
- | `npm run build` | TypeScript compilation |
247
- | `npm test` | Run all tests with coverage |
248
- | `npm run test:unit` | Unit tests only |
249
- | `npm run test:service` | Service tests only |
250
- | `npm run lint:check` | ESLint check |
251
- | `npm run lint:fix` | Auto-fix lint issues |
252
-
253
- ### Sample Config
254
-
255
- ```yaml
256
- version: 0.0.1
257
- provider:
258
- name: aliyun
259
- region: cn-hongkong
333
+ | Command | Description |
334
+ | ---------------------- | ---------------------------- |
335
+ | `npm run build` | TypeScript compilation |
336
+ | `npm test` | All tests with coverage |
337
+ | `npm run test:unit` | Unit tests only |
338
+ | `npm run test:service` | Service tests only |
339
+ | `npm run test:ci` | CI test run |
340
+ | `npm run lint:check` | ESLint check |
341
+ | `npm run lint:fix` | Auto-fix lint issues |
260
342
 
261
- service: my-api-service
343
+ Tests are split into fast, fully mocked unit tests and service tests that exercise the real parser, planner, executor and state manager. Coverage is enforced at 85% for branches, functions, lines and statements.
262
344
 
263
- functions:
264
- hello_function:
265
- name: hello-world-fn
266
- code:
267
- runtime: nodejs18
268
- handler: index.handler
269
- path: ./src
270
- memory: 512
271
- timeout: 10
345
+ ### Project structure
272
346
 
273
- events:
274
- api_gateway:
275
- type: API_GATEWAY
276
- name: my-api-gateway
277
- triggers:
278
- - method: GET
279
- path: /api/hello
280
- backend: ${functions.hello_function}
347
+ ```
348
+ src/
349
+ ├── commands/ # CLI command handlers (deploy, destroy, diff, local, ...)
350
+ ├── common/ # Shared utilities, clients, state and lock management
351
+ │ ├── aliyunClient/
352
+ │ ├── tencentClient/
353
+ │ └── volcengineClient/
354
+ ├── lang/ # i18n translations (en.ts, zh-CN.ts)
355
+ ├── parser/ # YAML parsing and validation
356
+ ├── stack/ # Provider-specific resource logic
357
+ │ ├── aliyunStack/
358
+ │ ├── scfStack/ # Tencent Cloud
359
+ │ ├── volcengineStack/
360
+ │ ├── localStack/ # Local development server
361
+ │ └── rfsStack/ # Huawei Cloud Terraform templates (preview)
362
+ ├── types/ # TypeScript type definitions
363
+ └── validator/ # JSON Schema validation
364
+ tests/
365
+ ├── fixtures/ # Test fixtures (YAML configs, artifacts)
366
+ ├── unit/ # Isolated unit tests
367
+ └── service/ # End-to-end service tests
281
368
  ```
282
369
 
283
- More in the [samples](./samples) directory.
370
+ See [AGENTS.md](AGENTS.md) for coding conventions, test rules and architecture principles.
284
371
 
285
372
  ## Community
286
373
 
287
374
  <p align="center">
288
- <img src="https://www.geekfun.club/wechat-group.jpg" width="140" alt="WeChat Group">
375
+ <img src="docs/images/wechat_official.png" width="300" alt="WeChat Official Account">
289
376
  </p>
290
377
 
291
378
  <p align="center">
292
- <a href="https://discord.gg/5NSUyPK2E"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
293
- &nbsp;&nbsp;&nbsp;
294
379
  <a href="https://x.com/geekfun_club"><img src="https://img.shields.io/badge/X-Follow-000000?logo=x&logoColor=white" alt="X / Twitter" /></a>
295
380
  &nbsp;&nbsp;&nbsp;
296
381
  <a href="https://www.youtube.com/@geekfun-club"><img src="https://img.shields.io/badge/YouTube-Subscribe-FF0000?logo=youtube&logoColor=white" alt="YouTube" /></a>
@@ -300,24 +385,20 @@ More in the [samples](./samples) directory.
300
385
 
301
386
  ## Contributing
302
387
 
303
- Contributions welcome! Open an issue or pull request. See the [AGENTS.md](AGENTS.md) for coding conventions.
388
+ Contributions are welcome — bug reports, feature requests, documentation fixes and code.
389
+
390
+ - Open an issue with the [bug report](.github/ISSUE_TEMPLATE/bug_report.md) or [feature request](.github/ISSUE_TEMPLATE/feature_request.md) template.
391
+ - Before opening a pull request, run `npm run lint:check`, `npm run build` and `npm test`.
392
+ - Follow the conventions in [AGENTS.md](AGENTS.md) and the existing [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
304
393
 
305
394
  ## Sponsor
306
395
 
307
396
  <p align="center">
397
+ <img src="docs/images/wechat_ponsor.jpg" width="140" alt="WeChat Sponsor QR">
398
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
308
399
  <a href="https://github.com/sponsors/geek-fun"><img src="https://img.shields.io/badge/GitHub_Sponsors-%E2%9D%A4_Support-EA4AAA?logo=githubsponsors&logoColor=white" alt="GitHub Sponsors" /></a>
309
400
  </p>
310
401
 
311
- ## Star History
312
-
313
- <a href="https://www.star-history.com/?repos=geek-fun/serverlessinsight&type=date">
314
- <picture>
315
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=geek-fun/serverlessinsight&type=date&theme=dark" />
316
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=geek-fun/serverlessinsight&type=date" />
317
- <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=geek-fun/serverlessinsight&type=date" />
318
- </picture>
319
- </a>
320
-
321
402
  ## License
322
403
 
323
404
  [Apache 2.0](LICENSE) © GEEKFUN