@geek-fun/serverlessinsight 0.6.14 → 0.7.0

package/AGENTS.md

@@ -247,22 +247,99 @@ logger.error(lang.__('FAILED_TO_DEPLOY_STACK', { error }));
 
 ### Testing
 
-- Tests live in `tests/` mirroring the `src/` structure
-- Use Jest with `jest.fn()` for mocks
-- Group mocks at the top of the test file
-- Use `jest.mock()` for module mocking before imports
-- Use `describe/it` blocks for organization
+**Test Folder Structure**:
+
+```
+tests/
+├── fixtures/           # Test fixtures (YAML configs, artifacts)
+├── unit/               # Unit tests (end with .test.ts)
+│   ├── common/
+│   ├── stack/
+│   └── ...
+└── service/            # Service tests (end with .spec.test.ts)
+    └── ...
+```
+
+**Test Commands**:
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run service tests only
+npm run test:service
+
+# Run CI tests
+npm run test:ci
+```
+
+**Unit Tests** (`.test.ts`):
+
+- Test individual functions/modules in complete isolation
+- Mock ALL external dependencies (SDK clients, file system, network)
+- Focus on business logic and edge cases
+- Run fast (< 100ms per test)
+- Located in `tests/unit/`
+
+**Service Tests** (`.spec.test.ts`):
+
+- Test the complete flow from command entry to final result
+- Mock ONLY external cloud SDK clients
+- Test framework internals: parser → planner → executor → state
+- Verify component interaction and state consistency
+- Run slower (1-10s per test)
+- Located in `tests/service/`
+
+**When to Write Which Test**:
+
+| Scenario                            | Unit Test | Service Test |
+| ----------------------------------- | --------- | ------------ |
+| New utility function                | ✅        | ❌           |
+| New SDK operation wrapper           | ✅        | ❌           |
+| New resource planner                | ✅        | ❌           |
+| Deploy command flow                 | ❌        | ✅           |
+| State persistence across operations | ❌        | ✅           |
+| Error handling in full flow         | ❌        | ✅           |
+
+**Mock Strategy**:
+
+```typescript
+// Unit Test: Mock everything external
+jest.mock('../../../../src/common/aliyunClient', () => ({
+  createAliyunClient: jest.fn(() => ({
+    fc3: { createFunction: jest.fn() },
+  })),
+}));
+
+// Service Test: Mock only cloud SDK
+const mockCloudClient = {
+  fc3: { createFunction: jest.fn() },
+  apigw: { createApi: jest.fn() },
+};
+// Use real parser, real planner, real executor
+```
+
+**CRITICAL: Test Coverage Requirements**
+
+- Coverage threshold is set to **85%** for all metrics (branches, functions, lines, statements)
+- **NEVER modify the coverage threshold** in `jest.config.js`
+- If tests fail due to coverage, add more tests - do not lower the threshold
+- This is a mandatory quality gate for the framework
+
+**Unit Test Example**:
 
 ```typescript
 describe('updateResource', () => {
   it('should update resource and refresh state from provider', async () => {
-    // Arrange
-    mockedFc3Operations.updateFunctionConfiguration.mockResolvedValue(undefined);
+    const mockedFc3Operations = {
+      updateFunctionConfiguration: jest.fn(),
+    };
 
-    // Act
-    const result = await updateResource(mockContext, testFunction, initialState);
+    await updateResource(mockContext, testFunction, initialState);
 
-    // Assert
     expect(mockedFc3Operations.updateFunctionConfiguration).toHaveBeenCalledWith(
       expect.objectContaining({ functionName: 'test-function' }),
     );
@@ -270,6 +347,284 @@ describe('updateResource', () => {
 });
 ```
 
+**Service Test Example**:
+
+```typescript
+describe('Deploy Flow', () => {
+  it('should parse YAML, generate plan, execute, and save state', async () => {
+    const mockClient = createMockAliyunClient();
+    const config = loadTestConfig('fixtures/deploy-fixtures/oneFc');
+
+    await deployCommand({ config, client: mockClient });
+
+    expect(mockClient.fc3.createFunction).toHaveBeenCalled();
+    const state = await loadState(config.app, config.service);
+    expect(state.resources).toHaveLength(1);
+  });
+});
+```
+
+## Test Architecture & Rules (CRITICAL)
+
+### Test Pyramid
+
+```
+        /\
+       /  \
+      / E2E \     (Future: Full integration tests)
+     /--------\
+    /  Service \   (Integration-style, mock ONLY cloud SDKs)
+   /------------\
+  /     Unit      \ (Isolated, mock ALL externals)
+ /----------------\
+```
+
+### Unit Test Rules (`.test.ts`)
+
+**Purpose**: Test individual functions/modules in complete isolation
+
+**DO**:
+
+- Mock ALL external dependencies (SDK clients, file system, network, logger)
+- Test pure business logic
+- Use inline `jest.mock()` for dependencies
+- Keep tests fast (< 100ms)
+- Test edge cases and error handling
+- Use descriptive test names that explain the scenario
+
+**DON'T**:
+
+- Import real cloud SDKs
+- Access real file system
+- Make network calls
+- Test multiple functions together
+- Rely on external state
+
+**Example**:
+
+```typescript
+// tests/unit/common/aliyunClient/fc3Operations.test.ts
+import { createFc3Operations } from '../../../../src/common/aliyunClient/fc3Operations';
+
+jest.mock('../../../../src/common/logger', () => ({
+  logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+}));
+
+jest.mock('../../../../src/lang', () => ({
+  lang: { __: (key: string) => key },
+}));
+
+const mockFc3SdkClient = {
+  createFunction: jest.fn(),
+  getFunction: jest.fn(),
+  deleteFunction: jest.fn(),
+};
+
+describe('createFc3Operations', () => {
+  let operations: ReturnType<typeof createFc3Operations>;
+
+  beforeEach(() => {
+    operations = createFc3Operations(mockFc3SdkClient as any);
+    jest.clearAllMocks();
+  });
+
+  it('should create function successfully', async () => {
+    mockFc3SdkClient.createFunction.mockResolvedValue({ body: { functionName: 'test-fn' } });
+
+    const result = await operations.createFunction({ functionName: 'test-fn' }, 'base64code');
+
+    expect(result).toEqual({ functionName: 'test-fn' });
+    expect(mockFc3SdkClient.createFunction).toHaveBeenCalledWith(
+      expect.objectContaining({ functionName: 'test-fn' }),
+      'base64code',
+    );
+  });
+});
+```
+
+### Service Test Rules (`.spec.test.ts`)
+
+**Purpose**: Test complete flows from command entry to final result
+
+**DO**:
+
+- Mock ONLY external cloud SDK clients via `createMockAliyunClient()` / `createMockTencentClient()`
+- Use REAL internal modules (parser, planner, executor, state manager, lock manager)
+- Use REAL fixture files from `tests/fixtures/`
+- Test end-to-end scenarios
+- Verify state persistence and component interactions
+- Use `jest.mock()` at the top level for SDK modules only
+
+**DON'T**:
+
+- Mock internal modules (parser, planner, executor, stateManager, lockManager, etc.)
+- Mock file system operations (use real fixtures)
+- Mock logger (service tests can log)
+- Mock hashUtils or other utilities
+- Override `jest.requireActual()` - let internal code run normally
+
+**CRITICAL**: Service tests are integration tests. They verify that all internal components work together correctly. Over-mocking defeats their purpose.
+
+**Example**:
+
+```typescript
+// tests/service/deploy-flow.spec.test.ts
+import { deploy } from '../../src/commands/deploy';
+import { createMockAliyunClient } from './mockCloudClient';
+
+// ONLY mock external SDK
+jest.mock('../../src/common/aliyunClient', () => ({
+  createAliyunClient: jest.fn(),
+}));
+
+jest.mock('../../src/common/imsClient', () => ({
+  getIamInfo: jest.fn().mockResolvedValue({
+    accountId: '123456789012',
+    displayName: 'Test User',
+    userId: 'test-user-id',
+  }),
+}));
+
+jest.mock('../../src/common/logger', () => ({
+  logger: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+jest.mock('../../src/lang', () => ({
+  lang: { __: (key: string) => key },
+}));
+
+const mockCreateAliyunClient = require('../../src/common/aliyunClient').createAliyunClient;
+
+describe('Deploy Flow Service Test', () => {
+  let mockClient: ReturnType<typeof createMockAliyunClient>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockClient = createMockAliyunClient();
+    mockCreateAliyunClient.mockReturnValue(mockClient);
+  });
+
+  it('should deploy FC3 function and save state', async () => {
+    // Use REAL fixtures, REAL parser, REAL planner, REAL executor
+    await deploy({
+      location: path.join(__dirname, '../fixtures'),
+      stage: 'dev',
+      autoApprove: true,
+      region: 'cn-hangzhou',
+      provider: 'aliyun',
+    });
+
+    // Verify cloud SDK was called correctly
+    expect(mockClient.fc3.createFunction).toHaveBeenCalled();
+  });
+});
+```
+
+### Mock Cloud Client Pattern
+
+**Location**: `tests/service/mockCloudClient.ts`
+
+All service tests should use the shared mock cloud client:
+
+```typescript
+// Create mock client with all services
+const mockClient = createMockAliyunClient();
+
+// Configure specific behavior per test
+mockClient.fc3.getFunction.mockRejectedValueOnce({ code: 'FunctionNotFound' });
+mockClient.fc3.createFunction.mockResolvedValue({ body: { functionName: 'test-fn' } });
+
+// Return from mocked createAliyunClient
+mockCreateAliyunClient.mockReturnValue(mockClient);
+```
+
+**Services to Mock**:
+
+- `fc3` - Function Compute
+- `apigw` - API Gateway
+- `oss` - Object Storage Service
+- `sls` - Log Service
+- `ram` - Resource Access Management
+- `nas` - Network Attached Storage
+- `rds` - Relational Database Service
+- `ecs` - Elastic Compute Service
+- `es` - Elasticsearch Serverless
+- `dns` - DNS (for domain operations)
+- `cas` - Certificate Authority Service
+
+### Common Mistakes to Avoid
+
+**WRONG - Over-mocking in service tests**:
+
+```typescript
+// DON'T DO THIS in service tests
+jest.mock('../../src/parser', () => ({
+  parseYaml: jest.fn(() => ({
+    /* mock data */
+  })),
+}));
+
+jest.mock('../../src/common/stateManager', () => ({
+  getResource: jest.fn(),
+  setResource: jest.fn(),
+}));
+
+jest.mock('../../src/common/lockManager', () => ({
+  withLock: jest.fn(),
+}));
+```
+
+**CORRECT - Only mock external SDKs**:
+
+```typescript
+// DO THIS - only mock cloud SDK
+jest.mock('../../src/common/aliyunClient', () => ({
+  createAliyunClient: jest.fn(),
+}));
+
+jest.mock('../../src/common/imsClient', () => ({
+  getIamInfo: jest.fn().mockResolvedValue({
+    /* IAM data */
+  }),
+}));
+```
+
+### Test File Naming
+
+- **Unit tests**: `*.test.ts` (e.g., `fc3Resource.test.ts`)
+- **Service tests**: `*.spec.test.ts` (e.g., `deploy-flow.spec.test.ts`)
+- **Fixtures**: `tests/fixtures/` (YAML configs, artifacts, state files)
+
+### Running Tests
+
+```bash
+# All tests
+npm test
+
+# Unit tests only (fast, isolated)
+npm run test:unit
+
+# Service tests only (slower, integration)
+npm run test:service
+
+# CI mode (no coverage, faster)
+npm run test:ci
+
+# Specific test file
+npm test -- tests/unit/common/aliyunClient/fc3Operations.test.ts
+
+# Test name pattern
+npm test -- --testNamePattern="should create function"
+```
+
+### Coverage Requirements
+
+- **Minimum 85%** for all metrics (branches, functions, lines, statements)
+- **NEVER lower the threshold** in `jest.config.js`
+- If coverage fails, add more tests
+- Unit tests should cover edge cases
+- Service tests should cover full flows
+
 ## Formatting
 
 Prettier configuration (`.prettierrc`):
@@ -370,3 +725,43 @@ export const createRamOperations = (ramClient: RamSdkClient) => ({
 - State is stored in `.serverlessinsight/state-{app}-{service}.json`
 - Use `setResource`, `getResource`, `removeResource` from `src/common/stateManager`
 - Resources have a `status`: `'ready'` | `'tainted'`
+
+## Commit Policy - CRITICAL
+
+**NEVER commit changes unless the user explicitly requests it.**
+
+- Do NOT commit after implementing features
+- Do NOT commit after fixing bugs
+- Do NOT commit after refactoring
+- Do NOT commit for "cleanliness" or "convenience"
+- Wait for explicit user instruction like "commit the changes" or "create a commit"
+
+**Rationale**: Users may want to:
+
+- Review changes before committing
+- Combine multiple changes into one commit
+- Split changes into different commits
+- Test changes before committing
+- Discard changes without polluting git history
+
+**If you accidentally commit**: Immediately revert and apologize.
+
+## Commit Policy - CRITICAL
+
+**NEVER commit changes unless the user explicitly requests it.**
+
+- Do NOT commit after implementing features
+- Do NOT commit after fixing bugs
+- Do NOT commit after refactoring
+- Do NOT commit for "cleanliness" or "convenience"
+- Wait for explicit user instruction like "commit the changes" or "create a commit"
+
+**Rationale**: Users may want to:
+
+- Review changes before committing
+- Combine multiple changes into one commit
+- Split changes into different commits
+- Test changes before committing
+- Discard changes without polluting git history
+
+**If you accidentally commit**: Immediately revert and apologize.

package/README.md

@@ -52,6 +52,7 @@ ServerlessInsight supports the following cloud providers:
 | ----------------- | ---------------- | -------------- | -------------- | ---------------- | ------- |
 | **Alibaba Cloud** | ✅ FC3           | ✅ API Gateway | ✅ OSS         | ✅ RDS, OTS, ESS | Stable  |
 | **Tencent Cloud** | ✅ SCF           | 🚧 Coming Soon | ✅ COS         | ✅ TDSQL-C       | Stable  |
+| **Volcengine**    | ✅ veFaaS        | ✅ API Gateway | ✅ TOS         | —                | Stable  |
 | **Huawei Cloud**  | ✅ FunctionGraph | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon   | Beta    |
 | **AWS**           | 🔜 Planned       | 🔜 Planned     | 🔜 Planned     | 🔜 Planned       | Planned |
 | **Azure**         | 🔜 Planned       | 🔜 Planned     | 🔜 Planned     | 🔜 Planned       | Planned |

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@geek-fun/serverlessinsight",
-    "version": "0.6.14",
+    "version": "0.7.0",
     "description": "Full life cycle cross providers serverless application management for your fast-growing business.",
     "homepage": "https://serverlessinsight.geekfun.club",
     "main": "dist/src/index.js",
@@ -10,7 +10,9 @@
     },
     "scripts": {
         "test": "cross-env DEBUG=ServerlessInsight jest --runInBand --detectOpenHandles --coverage --coverageReporters json-summary text html lcov",
-        "test:ci": "jest --runInBand --ci --coverage --coverageReporters json-summary text html lcov",
+        "test:unit": "cross-env DEBUG=ServerlessInsight jest --runInBand --detectOpenHandles --testPathPattern=unit",
+        "test:service": "cross-env DEBUG=ServerlessInsight TEST_TYPE=service jest --runInBand --detectOpenHandles --testPathPattern=service",
+        "test:ci": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192\" jest --runInBand --ci --coverage --coverageReporters json-summary text html lcov",
         "build": "tsc --build",
         "lint:fix": "eslint --fix ./",
         "lint:check": "eslint ./",
@@ -35,6 +37,7 @@
         "tencent-cloud-functions",
         "alibaba-cloud-functions",
         "huawei-cloud-functions",
+        "volcengine-cloud-functions",
         "serverless-framework",
         "serverless-management",
         "serverless-automation",
@@ -46,6 +49,7 @@
         "azure",
         "huawei",
         "google",
+        "volcengine",
         "function"
     ],
     "dependencies": {
@@ -61,6 +65,8 @@
         "@alicloud/ram20150501": "^1.2.0",
         "@alicloud/rds20140815": "^15.5.1",
         "@alicloud/sls20201230": "^5.9.0",
+        "@volcengine/openapi": "^1.36.0",
+        "@volcengine/tos-sdk": "^2.7.0",
         "ajv": "^8.18.0",
         "ali-oss": "^6.23.0",
         "commander": "^14.0.3",

package/dist/src/commands/deploy.js

@@ -41,6 +41,7 @@ const stateBackend_1 = require("../common/stateBackend");
 const parser_1 = require("../parser");
 const scfStack_1 = require("../stack/scfStack");
 const aliyunStack_1 = require("../stack/aliyunStack");
+const volcengineStack_1 = require("../stack/volcengineStack");
 const lang_1 = require("../lang");
 const askConfirmation = async () => {
     if (!process.stdin.isTTY) {
@@ -82,6 +83,9 @@ const deploy = async (options) => {
     else if (iac.provider.name === common_1.ProviderEnum.ALIYUN) {
         planResult = await (0, aliyunStack_1.generateAliyunPlan)(iac, backend);
     }
+    else if (iac.provider.name === common_1.ProviderEnum.VOLCENGINE) {
+        planResult = await (0, volcengineStack_1.generateVolcenginePlan)(iac, backend);
+    }
     else {
         throw new Error(lang_1.lang.__('PLAN_COMMAND_NOT_SUPPORTED'));
     }

package/dist/src/commands/destroy.js

@@ -7,6 +7,7 @@ const parser_1 = require("../parser");
 const lang_1 = require("../lang");
 const scfStack_1 = require("../stack/scfStack");
 const aliyunStack_1 = require("../stack/aliyunStack");
+const volcengineStack_1 = require("../stack/volcengineStack");
 const destroyStack = async (options) => {
     const iacLocation = (0, common_1.getIacLocation)(options.location);
     const rawIac = (0, parser_1.parseYaml)(iacLocation);
@@ -33,6 +34,9 @@ const destroyStack = async (options) => {
         else if (iac.provider.name === common_1.ProviderEnum.ALIYUN) {
             await (0, aliyunStack_1.destroyAliyunStack)(backend);
         }
+        else if (iac.provider.name === common_1.ProviderEnum.VOLCENGINE) {
+            await (0, volcengineStack_1.destroyVolcengineStack)(backend);
+        }
         else {
             throw new Error(`Unsupported provider: ${iac.provider.name}`);
         }

package/dist/src/common/credentials.js

@@ -11,6 +11,18 @@ const getCredentials = (config, provider) => {
         };
     }
     switch (provider) {
+        case providerEnum_1.ProviderEnum.VOLCENGINE:
+            return {
+                accessKeyId: config?.accessKeyId ??
+                    process.env.VOLCSTACK_ACCESS_KEY_ID ??
+                    process.env.VOLCENGINE_ACCESS_KEY_ID,
+                accessKeySecret: config?.accessKeySecret ??
+                    process.env.VOLCSTACK_SECRET_ACCESS_KEY ??
+                    process.env.VOLCENGINE_ACCESS_KEY_SECRET,
+                securityToken: config?.securityToken ??
+                    process.env.VOLCSTACK_SESSION_TOKEN ??
+                    process.env.VOLCENGINE_SESSION_TOKEN,
+            };
         case providerEnum_1.ProviderEnum.TENCENT:
             return {
                 accessKeyId: config?.accessKeyId ?? process.env.TENCENTCLOUD_SECRET_ID,

package/dist/src/common/providerEnum.js

@@ -7,4 +7,5 @@ var ProviderEnum;
     ProviderEnum["ALIYUN"] = "aliyun";
     ProviderEnum["TENCENT"] = "tencent";
     ProviderEnum["AWS"] = "aws";
+    ProviderEnum["VOLCENGINE"] = "volcengine";
 })(ProviderEnum || (exports.ProviderEnum = ProviderEnum = {}));

package/dist/src/common/runtimeMapper.js

@@ -144,14 +144,35 @@ const mapRuntime = (standardRuntime, provider) => {
     return providerRuntime;
 };
 exports.mapRuntime = mapRuntime;
-const isRuntimeSupported = (standardRuntime, provider) => {
-    const mapping = runtimeMappings[standardRuntime];
+const VOLCENGINE_NATIVE_RUNTIMES = [
+    'nodejs/v20',
+    'nodejs/v18',
+    'nodejs/v16',
+    'nodejs/v14',
+    'python/v3.12',
+    'python/v3.11',
+    'python/v3.10',
+    'python/v3.9',
+    'golang/v1',
+    'java/v21',
+    'java/v17',
+    'java/v11',
+    'java/v8',
+];
+const isRuntimeSupported = (runtime, provider) => {
+    if (provider === providerEnum_1.ProviderEnum.VOLCENGINE) {
+        return VOLCENGINE_NATIVE_RUNTIMES.includes(runtime);
+    }
+    const mapping = runtimeMappings[runtime];
     return !!mapping && !!mapping[provider];
 };
 exports.isRuntimeSupported = isRuntimeSupported;
 const getSupportedRuntimes = (provider) => {
     if (!provider) {
-        return Object.values(StandardRuntime);
+        return [...Object.values(StandardRuntime), ...VOLCENGINE_NATIVE_RUNTIMES];
+    }
+    if (provider === providerEnum_1.ProviderEnum.VOLCENGINE) {
+        return VOLCENGINE_NATIVE_RUNTIMES;
     }
     return Object.entries(runtimeMappings)
         .filter(([, mapping]) => !!mapping[provider])