npm package: @microfox/serverless-yml
Description: Serverless YML - Validate and update serverless.yml files
Latest version: 1.1.0

# @microfox/serverless-yml

A utility package for validating and mutating `serverless.yml` files, with a focus on automating configurations for services using `@microfox` packages.

## Features

- **Validation**: Ensures your `serverless.yml` follows best practices and required structures.
- **Automatic Configuration**: Automatically mutates the `serverless.yml` file to include necessary configurations based on the `@microfox` packages your service uses.

## Installation

```bash
npm install @microfox/serverless-yml
# or
yarn add @microfox/serverless-yml
```

## Usage

### Validation

You can validate your `serverless.yml` content to ensure it's correctly configured.

```typescript
import { validateServerlessYML } from '@microfox/serverless-yml';
import fs from 'fs';

const yamlContent = fs.readFileSync('serverless.yml', 'utf-8');
const { isValid, errors } = validateServerlessYML(yamlContent);

if (!isValid) {
  console.error('Serverless YML validation failed:', errors);
}
```

The `validateServerlessYML` function checks for:

- The presence of a `functions` section.
- Each function (except `getDocs`) having `events` (with at least one `http` event) and a `handler`.

### Mutation

The package can automatically apply configurations to your `serverless.yml` based on the `@microfox` packages detected in your function files' imports.

```typescript
import { mutateServerlessYML } from '@microfox/serverless-yml';
import fs from 'fs';

// Assume functionFiles is an array of objects describing your function files.
// This is typically generated by analyzing your codebase.
const functionFiles = [
  {
    fileName: 'handler.ts',
    filePath: 'src/handler.ts',
    imports: ['@microfox/puppeteer-sls'],
    exports: ['myHandler'],
  },
];

const yamlContent = fs.readFileSync('serverless.yml', 'utf-8');

// Define a custom mutator if needed (optional)
const myMutator = (yamlContent, functionFiles) => {
  // Your custom logic to modify yamlContent
  return yamlContent;
};

const newYamlContent = await mutateServerlessYML(
  yamlContent,
  functionFiles,
  myMutator, // This will be applied along with the default packageMutator
);

fs.writeFileSync('serverless.yml', newYamlContent);
```

You can also apply a batch of mutators:

```typescript
import { batchMutateServerlessYML } from '@microfox/serverless-yml';

// ...

const newYamlContent = await batchMutateServerlessYML(
  yamlContent,
  functionFiles,
  [myMutator1, myMutator2], // your custom mutators
);
```

## Automatic Configuration with `config.serverless.json`

When you use a `@microfox` package (e.g., `@microfox/puppeteer-sls`), this utility looks for a `config.serverless.json` file within that package's directory in the `@microfox` monorepo. It then automatically merges the configurations into your service's `serverless.yml`.

### `config.serverless.json` Structure

This file defines how a `@microfox` package affects the `serverless.yml`.

- `package`: Defines packaging configurations.
- `provider`: Defines provider-level configurations.
- `functions`: Defines function-level configurations.

#### `package`

This section is merged with the `package` section of `serverless.yml`. Arrays like `include` and `exclude` are merged, and duplicates are removed.

**Example:**

```json
{
  "package": {
    "include": ["some-file.js"],
    "exclude": ["node_modules/unwanted-dep/**"],
    "individually": true
  }
}
```

#### `provider`

This section is merged with the `provider` section of `serverless.yml`.

**Example:**

```json
{
  "provider": {
    "timeout": 60,
    "memorySize": 512
  }
}
```

#### `functions`

This section allows modification of all functions in the service. It's useful for adding shared configurations like layers.

**Example:**

```json
{
  "functions": {
    "layers": ["arn:aws:lambda:us-east-1:xxxx:layer:my-layer:1"]
  }
}
```

## Example Workflow

1.  A developer adds the `@microfox/puppeteer-sls` package to their service.
2.  In their deployment script or a dedicated tool, they use `@microfox/serverless-yml`.
3.  The tool scans the function files and detects that `@microfox/puppeteer-sls` is imported.
4.  The `packageMutator` from `@microfox/serverless-yml` fetches `packages/puppeteer-sls/config.serverless.json` from the `microfox-ai/microfox` GitHub repository.
5.  The configurations from this JSON file (e.g., provider settings, layers for functions, packaging includes/excludes) are automatically merged into the service's `serverless.yml`.
6.  The final, mutated `serverless.yml` is used for deployment.

This process simplifies configuration management and ensures consistency across services using the same `@microfox` packages.