@geek-fun/serverlessinsight 0.9.3 → 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 (30) 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 +2 -2
  4. package/.serverlessinsight/state-insight-poc-app-log-insight-poc-tencent-log.json.backup +3 -3
  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 +2 -2
  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 +2 -2
  11. package/.serverlessinsight/state-role-reconcile-test-app-role-reconcile-test-service.json.backup +3 -3
  12. package/CHANGELOG.md +28 -0
  13. package/README.md +246 -179
  14. package/README.zh-CN.md +244 -147
  15. package/dist/package.json +22 -19
  16. package/dist/src/commands/index.js +12 -59
  17. package/dist/src/commands/plan.js +25 -1
  18. package/dist/src/common/aliyunClient/apigwOperations.js +32 -9
  19. package/dist/src/lang/en.js +5 -4
  20. package/dist/src/lang/index.js +28 -14
  21. package/dist/src/lang/zh-CN.js +5 -4
  22. package/dist/src/stack/aliyunStack/apigwDomainPlan.js +82 -0
  23. package/dist/src/stack/aliyunStack/apigwExecutor.js +4 -1
  24. package/dist/src/stack/aliyunStack/apigwPlanner.js +115 -55
  25. package/dist/src/stack/aliyunStack/apigwResource.js +169 -124
  26. package/dist/tsconfig.tsbuildinfo +1 -1
  27. package/package.json +22 -19
  28. package/release-notes.md +33 -59
  29. package/samples/README_TENCENT_COS.md +3 -3
  30. package/samples/README_TENCENT_SCF.md +3 -3
package/README.md CHANGED
@@ -4,28 +4,30 @@
4
4
 
5
5
  # ServerlessInsight
6
6
 
7
- **Full life cycle cross-provider serverless management — describe your app, we handle the rest.**
7
+ **Full-lifecycle serverless IaC for Alibaba Cloud, Tencent Cloud and Volcengine.**
8
8
 
9
- **Open source. Multi-cloud. Infrastructure as Code.**
10
-
11
- **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.
12
10
 
13
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)
14
12
  [![npm version](https://img.shields.io/npm/v/@geek-fun/serverlessinsight?color=orange&logo=npm)](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
15
- [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg&logo=apache)](LICENSE)
16
- [![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)
17
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
18
 
19
19
  <p>
20
- <img src="https://img.shields.io/badge/Node.js-339933&logo=nodedotjs&logoColor=white"/>
21
- <img src="https://img.shields.io/badge/TypeScript-3178C6&logo=typescript&logoColor=white"/>
22
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00&logo=alibabacloud&logoColor=white"/>
23
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED&logo=tencentqq&logoColor=white"/>
24
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white"/>
25
- <img src="https://img.shields.io/badge/AWS-232F3E&logo=amazonwebservices&logoColor=white"/>
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" />
26
22
  </p>
27
23
 
28
- [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)
24
+ <p>
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" />
28
+ </p>
29
+
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)
29
31
 
30
32
  English · [简体中文](README.zh-CN.md)
31
33
 
@@ -33,151 +35,176 @@ English · [简体中文](README.zh-CN.md)
33
35
 
34
36
  ---
35
37
 
36
- 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.
37
39
 
38
- <p align="center">
39
- <img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" />
40
- <img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" />
41
- <img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white" />
42
- <img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" />
43
- <img src="https://img.shields.io/badge/AWS-232F3E?logo=amazonwebservices&logoColor=white" />
44
- <img src="https://img.shields.io/badge/Azure-0078D4?logo=microsoftazure&logoColor=white" />
45
- <img src="https://img.shields.io/badge/GCP-4285F4?logo=googlecloud&logoColor=white" />
46
- </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
47
60
 
48
- ## Installation
61
+ **Requires Node.js 22.12 or later.**
49
62
 
50
63
  ```bash
51
64
  npm install -g @geek-fun/serverlessinsight
52
65
  si --version
53
66
  ```
54
67
 
55
- ## Key Features
68
+ Create `serverlessinsight.yml`:
56
69
 
57
- ### Multi-Cloud, One Config
70
+ ```yaml
71
+ version: 0.0.1
72
+
73
+ provider:
74
+ name: aliyun
75
+ region: cn-hongkong
58
76
 
59
- 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.
77
+ app: hello-world
78
+ service: hello-world-api
60
79
 
61
- - **Unified configuration** — single `serverless.yml` format for all providers
62
- - **Provider-specific template generation** — generate native IaC templates from your config
63
- - **Cross-provider awareness** — the same abstractions work across different clouds
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
64
89
 
65
- | Provider | Functions | API Gateway | Storage | Databases | Status |
66
- | ----------------- | ---------------- | -------------- | -------------- | ---------------- | ------- |
67
- | **Alibaba Cloud** | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS, OTS, ESS | Stable |
68
- | **Tencent Cloud** | ✅ SCF | 🚧 Coming Soon | ✅ COS | ✅ TDSQL-C | Stable |
69
- | **Volcengine** | ✅ veFaaS | ✅ API Gateway | ✅ TOS | — | Stable |
70
- | **Huawei Cloud** | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | Planned |
71
- | **AWS** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
72
- | **Azure** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
73
- | **Google Cloud** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
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
+ ```
74
99
 
75
- ### Infrastructure as Code
100
+ Then:
76
101
 
77
- Declarative YAML configuration with validation, planning, and state management — following proven IaC patterns.
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
+ ```
78
109
 
79
- - **Plan before deploy** — `si plan` shows exactly what will change before anything happens
80
- - **State tracking** — incremental deployments with drift detection via local state files
81
- - **Validation** — type-safe template validation catches config errors before they reach the cloud
82
- - **Partial failure recovery** — successfully deployed resources are saved even when others fail; retry to continue
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.
83
111
 
84
- ### Quick Deployment
112
+ ## Why ServerlessInsight
85
113
 
86
- ```bash
87
- # Validate your config
88
- si validate -f serverless.yml
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.
89
120
 
90
- # Preview changes
91
- si plan -f serverless.yml
121
+ ## Features
92
122
 
93
- # Deploy to production
94
- si deploy -f serverless.yml -s prod
123
+ ### Multi-cloud, one config
95
124
 
96
- # Destroy when done
97
- si destroy -f serverless.yml
98
- ```
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.
99
126
 
100
- ### Standalone planning
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
101
130
 
102
- `si plan` and its alias `si diff` preview changes on Alibaba Cloud, Tencent Cloud,
103
- and Volcengine. Volcengine plans include functions, TOS buckets, and API Gateway
104
- resources in dependency order. Planning reads the configured state backend and
105
- cloud resources without applying changes or saving state.
131
+ ### Plan before deploy
132
+
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.
106
134
 
107
135
  ```bash
108
- si plan -f serverlessinsight.yml --stage dev
109
- si diff -f serverlessinsight.yml --stage dev --json
110
- si plan -f serverlessinsight.yml --stage dev --region cn-beijing -p memory=1024
111
- si diff -f serverlessinsight.yml --stage dev --no-refresh
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
112
140
  ```
113
141
 
114
- Use `-p, --parameter <key=value>` repeatedly to override configuration variables.
115
- `--no-refresh` skips live drift checks for tracked resources; ownership probes
116
- for new resources still run. Credentials and the selected state backend must be
117
- configured. Read failures exit with an error. Migrated legacy state produces a
118
- warning and remains unchanged.
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.
147
+
148
+ ### Infrastructure as code
149
+
150
+ Declarative YAML with validation, planning and state management, following proven IaC patterns.
119
151
 
120
- ### Using si with AI agents & scripts
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
121
159
 
122
- The CLI is built to be driven by agents and shell scripts: logs always go to
123
- **stderr** while result data goes to **stdout**, so piping stdout into `jq`
124
- always yields a single parseable JSON document.
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.
125
161
 
126
162
  ```bash
127
- si plan --json -f serverless.yml | jq '.summary'
128
- si validate --json -f serverless.yml | jq '.valid'
129
- si show --json -f serverless.yml | jq '.resourceCount'
130
- 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
131
167
  ```
132
168
 
133
- **Stable output envelopes** (each carries a version field, so shapes only ever
134
- change under a new version):
135
-
136
- - `si plan --json` → `{ planVersion: 1, provider, app, service, stage,
137
- changes: [{ logicalId, type, action: "create|update|destroy|recreate",
138
- attributes, drifted?, driftReasons? }], summary: { create, update, destroy,
139
- recreate, unchanged } }`
140
- - `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path,
141
- keyword, message, allowedValues? }] }`
142
- - `si show --json` → `{ showVersion: 1, provider, app, service, stage,
143
- stateLocation, backend: "saas|bucket_store|local", locked, lock, resources,
144
- 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, ... }`
145
177
  - failures (in `--json` mode) → `{ error: { code, message } }` on stdout
146
178
 
147
- **Exit codes**: `si plan` and `si diff` exit `0` when there are no changes, `2` when
148
- changes are present (terraform convention), `1` on errors. `si validate`
149
- 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`.
150
180
 
151
- **Stable error codes**: error `code`s are the i18n message keys behind the
152
- translated message (e.g. `RAM_ROLE_NOT_FOUND_IN_CLOUD`) — they are identical
153
- under every locale, so agents can map codes to self-healing actions regardless
154
- 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.
155
182
 
156
- **Colors**: ANSI color is disabled when the `NO_COLOR` environment variable is
157
- set ([no-color.org](https://no-color.org)) or `--no-color` is passed, keeping
158
- piped output clean in non-TTY environments.
183
+ </details>
159
184
 
160
- ### Local Development
185
+ ### Local development
161
186
 
162
- 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.
163
188
 
164
- - **LocalStack server** — test functions, buckets, and API endpoints locally
165
- - **Timer triggers fire locally** — Aliyun, Tencent and Volcengine `functions.*.triggers.timer` schedules run against UTC wall-clock (`@every` from server start) and invoke your handler with the provider's timer event shape
166
- - **Volcengine HTTP invocation** — veFaaS Node.js events, context and response translation for the [documented local subset](docs/local-development.md), with a [runnable example](samples/volcengine-local/serverlessinsight.yml)
167
- - **Tencent SCF HTTP invocation** — SCF function-URL events, native context and response translation for `nodejs10`–`nodejs18` packages, with a [runnable example](samples/tencent-local/serverlessinsight.yml)
168
- - **Bucket file serving** — access local storage files via HTTP for rapid iteration
169
- - **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
170
194
 
171
- ### 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
172
198
 
173
199
  Configure HTTP endpoints and bind custom domains with automatic DNS verification.
174
200
 
175
- - **API Gateway integration** — define triggers with HTTP methods and paths
176
- - **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
177
203
  - **CDN acceleration** — edge caching and global content delivery for static sites
178
- - **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
179
206
 
180
- ### Timer Triggers
207
+ ### Timer triggers
181
208
 
182
209
  Schedule functions with a provider-agnostic `si-cron` expression under `functions.*.triggers.timer`:
183
210
 
@@ -195,33 +222,69 @@ functions:
195
222
  cron: '@every 1h'
196
223
  ```
197
224
 
198
- `cron` accepts a standard 5-field expression (`minute hour day month weekday`),
199
- a 6-field expression with a seconds prefix, or `@every <duration>` (`30s`,
200
- `5m`, `1h`, `1d`, …). si-cron is always **UTC** — the synthesis layer
201
- translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF
202
- 7-field with year, Volcengine veFaaS 5-field crontab) including the UTC+8
203
- field shift, so the same YAML fires at the same instant everywhere. Invalid
204
- expressions and provider capability limits (Tencent SCF allows at most 10
205
- 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.
206
226
 
207
- **`functions.*.triggers` vs top-level `events`**: `triggers` (http, timer)
208
- are things that *invoke this function* — they are function-owned, die with
209
- the function, and have no independent configuration surface. Top-level
210
- `events` (e.g. `API_GATEWAY`) are infrastructure resources with their own
211
- config face — custom domains, certificates, route tables — that keep living
212
- when a backend function is removed. Rule of thumb: independent
213
- configuration surface → `events`; pure scheduling/event binding → `triggers`.
227
+ <details>
228
+ <summary><b><code>triggers</code> vs top-level <code>events</code></b></summary>
214
229
 
215
- ### 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`.
216
231
 
217
- Beyond functions — manage the full serverless stack including storage, databases, and more.
232
+ </details>
218
233
 
219
- - **Object storage** — OSS (Alibaba), COS (Tencent), TOS (Volcengine)
220
- - **Databases** — RDS, OTS, ESS, TDSQL-C with more on the way
221
- - **Elasticsearch Serverless** — deploy and manage ES clusters
222
- - **GPU functions** — deploy GPU-enabled serverless functions
234
+ ### Resource management
223
235
 
224
- ### Architecture
236
+ Beyond functions — manage the full serverless stack, including storage, databases and tables.
237
+
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
225
288
 
226
289
  ServerlessInsight follows a **functional client architecture** that cleanly separates cloud provider SDKs from business logic:
227
290
 
@@ -233,27 +296,29 @@ ServerlessInsight follows a **functional client architecture** that cleanly sepa
233
296
  ↓
234
297
  ┌─────────────────────────────────────────┐
235
298
  │ Functional Client Layer │ ← Encapsulated SDK operations
236
- │ (aliyunClient.ts, tencentClient.ts) │
299
+ │ (aliyunClient, tencentClient, │
300
+ │ volcengineClient) │
237
301
  └─────────────────────────────────────────┘
238
302
  ↓
239
303
  ┌─────────────────────────────────────────┐
240
- │ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*
304
+ │ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*, @volcengine/*
241
305
  └─────────────────────────────────────────┘
242
306
  ```
243
307
 
244
- - **Functional & pure** — business logic uses pure functions with immutable data
245
- - **SDK encapsulation** — provider SDKs accessed ONLY through client modules
246
- - **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
247
311
 
248
312
  ## Development
249
313
 
250
- 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.
251
315
 
252
316
  ### Prerequisites
253
317
 
254
- - **Node.js** >= 16
318
+ - **Node.js** >= 22.12
319
+ - **npm** (bundled with Node.js)
255
320
 
256
- ### Quick Start
321
+ ### Build from source
257
322
 
258
323
  ```bash
259
324
  git clone https://github.com/geek-fun/serverlessinsight.git
@@ -265,46 +330,44 @@ npm link
265
330
 
266
331
  ### Scripts
267
332
 
268
- | Command | Description |
269
- |---------|-------------|
270
- | `npm run build` | TypeScript compilation |
271
- | `npm test` | Run all tests with coverage |
272
- | `npm run test:unit` | Unit tests only |
273
- | `npm run test:service` | Service tests only |
274
- | `npm run lint:check` | ESLint check |
275
- | `npm run lint:fix` | Auto-fix lint issues |
276
-
277
- ### Sample Config
278
-
279
- ```yaml
280
- version: 0.0.1
281
- provider:
282
- name: aliyun
283
- 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 |
284
342
 
285
- 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.
286
344
 
287
- functions:
288
- hello_function:
289
- name: hello-world-fn
290
- code:
291
- runtime: nodejs18
292
- handler: index.handler
293
- path: ./src
294
- memory: 512
295
- timeout: 10
345
+ ### Project structure
296
346
 
297
- events:
298
- api_gateway:
299
- type: API_GATEWAY
300
- name: my-api-gateway
301
- triggers:
302
- - method: GET
303
- path: /api/hello
304
- 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
305
368
  ```
306
369
 
307
- More in the [samples](./samples) directory.
370
+ See [AGENTS.md](AGENTS.md) for coding conventions, test rules and architecture principles.
308
371
 
309
372
  ## Community
310
373
 
@@ -322,7 +385,11 @@ More in the [samples](./samples) directory.
322
385
 
323
386
  ## Contributing
324
387
 
325
- 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).
326
393
 
327
394
  ## Sponsor
328
395