### Install Dependencies with npm ci

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Install project dependencies deterministically using `npm ci`. This command installs exactly what is pinned in `package-lock.json` and automatically runs the `prepare` script, which is necessary for Husky hook installation.

```bash
npm ci
```

--------------------------------

### Check Node and npm Versions

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Verify that the correct Node.js and npm versions are installed. This is important as the release workflow is configured for Node 22.x.

```bash
node -v
npm -v
```

--------------------------------

### Load Single Authoritative JSON Config

Source: https://github.com/constantiner/yassa/blob/main/README.md

This example shows how to load a single, authoritative JSON configuration file for a specific environment (e.g., 'production'). It uses `resolveConfigFileFor` to get the file path and then reads and parses the JSON content. An error is thrown if the config file is not found.

```typescript
import { readFile } from "node:fs/promises";

import { resolveConfigFileFor } from "yassa";

const resolveProdConfig = resolveConfigFileFor("production");
const configPath = await resolveProdConfig("config/app.json");

if (!configPath) {
	throw new Error("No production config file found");
}

const config = JSON.parse(await readFile(configPath, "utf8"));
```

--------------------------------

### Verify Husky Hooks

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Check if the Husky hooks were installed correctly by listing the contents of the `.husky` directory and viewing the `pre-commit` hook file. This ensures local pre-commit automation is active.

```bash
ls -la .husky
```

```bash
cat .husky/pre-commit
```

--------------------------------

### Install Yassa Package

Source: https://github.com/constantiner/yassa/blob/main/README.md

Install the yassa package using npm. This package is compatible with Node.js version 16 and above, and works with both ESM and CJS modules.

```bash
npm install yassa
```

--------------------------------

### Start a New Feature Branch

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Create a new Git branch for feature development or bug fixes. This follows best practices for clean review processes and clear changeset ownership.

```bash
git checkout -b feat/short-description
```

--------------------------------

### Resolve config file chain with NODE_ENV

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigChain` to asynchronously get all existing hierarchy files for the current NODE_ENV. Throws if NODE_ENV is missing. Pass `localIgnoredEnvironments` to exclude `.local` variants.

```typescript
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = "development";

// Given these files exist on disk:
//   /app/.env.development.local
//   /app/.env.local
//   /app/.env.development
//   /app/.env
const files = await resolveConfigChain(".env");
console.log(files);
// [
//   "/app/.env.development.local",
//   "/app/.env.local",
//   "/app/.env.development",
//   "/app/.env"
// ]

// Pass localIgnoredEnvironments to strip .local variants in test runs:
process.env.NODE_ENV = "test";
const testFiles = await resolveConfigChain(".env", ["test"]);
// ["/app/.env.test", "/app/.env"]  — .env.test.local and .env.local excluded

// Missing NODE_ENV throws:
delete process.env.NODE_ENV;
try {
  await resolveConfigChain(".env");
} catch (err) {
  console.error(err.message);
  // "The NODE_ENV environment variable is required. ..."
}
```

--------------------------------

### Resolve Config Chain for Current NODE_ENV

Source: https://github.com/constantiner/yassa/blob/main/README.md

Use `resolveConfigChain` to get an array of existing configuration files based on the current `NODE_ENV`. This is useful for loading environment variables or config files with a precedence chain.

```typescript
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = "development";

const files = await resolveConfigChain(".env");
// Example result:
// [
//   "/app/.env.development.local",
//   "/app/.env.local",
//   "/app/.env.development",
//   "/app/.env"
// ]
```

--------------------------------

### Prepare for Release with npm

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Commands for preparing and executing package releases, including changeset generation, version bumping, and publishing.

```bash
npm run changeset
npm run version-packages
npm run release
npm run release:publish
npm run pack:dry-run
```

--------------------------------

### Build Project Outputs with npm

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Compile and bundle project assets for distribution.

```bash
npm run build
```

--------------------------------

### resolveConfigChain(file, localIgnoredEnvironments?)

Source: https://context7.com/constantiner/yassa/llms.txt

Async runtime wrapper. Reads process.env.NODE_ENV and returns all existing hierarchy files in precedence order (most specific first). Throws if NODE_ENV is missing or blank. Returns an empty array when no candidates exist on disk.

```APIDOC
## resolveConfigChain(file, localIgnoredEnvironments?)

### Description
Async runtime wrapper. Reads `process.env.NODE_ENV` and returns all existing hierarchy files in precedence order (most specific first). Throws if `NODE_ENV` is missing or blank. Returns an empty array when no candidates exist on disk.

### Parameters
#### Path Parameters
- **file** (string) - Required - The base name of the configuration file to resolve.
- **localIgnoredEnvironments** (string[]) - Optional - An array of environment names for which `.local` variants should be ignored.

### Request Example
```typescript
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = "development";

// Given these files exist on disk:
//   /app/.env.development.local
//   /app/.env.local
//   /app/.env.development
//   /app/.env
const files = await resolveConfigChain(".env");
console.log(files);
// [
//   "/app/.env.development.local",
//   "/app/.env.local",
//   "/app/.env.development",
//   "/app/.env"
// ]

// Pass localIgnoredEnvironments to strip .local variants in test runs:
process.env.NODE_ENV = "test";
const testFiles = await resolveConfigChain(".env", ["test"]);
// ["/app/.env.test", "/app/.env"]  — .env.test.local and .env.local excluded

// Missing NODE_ENV throws:
delete process.env.NODE_ENV;
try {
  await resolveConfigChain(".env");
} catch (err) {
  console.error(err.message);
  // "The NODE_ENV environment variable is required. ..."
}
```

### Response
#### Success Response (200)
- **files** (string[]) - An array of existing configuration file paths in precedence order.
```

--------------------------------

### Run Baseline Project Checks

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Execute a suite of commands to confirm the local development environment matches CI and release expectations. This includes linting, type checking, unit tests, and simulating an npm package build.

```bash
npm run checks
```

```bash
npm run test
```

```bash
npm run build
```

```bash
npm run pack:dry-run
```

--------------------------------

### Build Reusable Synchronous Resolvers

Source: https://github.com/constantiner/yassa/blob/main/README.md

Demonstrates creating reusable synchronous configuration resolvers using `resolveConfigChainForSync`. This is useful for setting up configuration resolution logic that can be called multiple times without re-initializing the resolver.

```typescript
import { resolveConfigChainForSync } from "yassa";

const resolveTestChainSync = resolveConfigChainForSync("test");

const files = resolveTestChainSync(".env", ["test"]);
```

--------------------------------

### Publish Packages

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Run this command to publish packages to npm and create GitHub releases/tags. This command expands to 'npm run build' followed by 'changeset publish'.

```bash
npm run release:publish
```

--------------------------------

### Create a Changeset

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Run this command to generate a changeset file for user-facing changes. You will be prompted to select the package, the type of bump (patch, minor, or major), and to write a release summary.

```bash
npm run changeset
```

--------------------------------

### Match Node Version and Run CI Checks

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

To resolve CI failures that occur locally, match your local Node.js version to the CI environment (recommended: 22) and then run `npm ci` followed by `npm run ci` from a clean working directory.

```bash
npm ci
```

```bash
npm run ci
```

--------------------------------

### resolveConfigChain(file, localIgnoredEnvironments?)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Asynchronously resolves the full precedence chain of existing configuration files for the current NODE_ENV. It returns an array of file paths, from most specific to least specific. Optionally, it can ignore certain local environments.

```APIDOC
## resolveConfigChain(file, localIgnoredEnvironments?)

### Description
Asynchronously resolves the full precedence chain of existing configuration files for the current NODE_ENV. It returns an array of file paths, from most specific to least specific. Optionally, it can ignore certain local environments.

### Parameters
#### Path Parameters
- **file** (string) - Required - The base name of the configuration file (e.g., ".env").
- **localIgnoredEnvironments** (string[]) - Optional - An array of environment names to ignore for local overrides.

### Request Example
```ts
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = "development";

const files = await resolveConfigChain(".env");
// Example result:
// [
//   "/app/.env.development.local",
//   "/app/.env.local",
//   "/app/.env.development",
//   "/app/.env"
// ]
```

### Response
#### Success Response (Array<string>)
- An array of strings, where each string is a path to an existing configuration file, ordered by precedence (most specific first).

#### Response Example
```json
[
  "/app/.env.development.local",
  "/app/.env.local",
  "/app/.env.development",
  "/app/.env"
]
```
```

--------------------------------

### Run Quality Checks with npm

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Execute common quality assurance tasks including tests and CI checks.

```bash
npm run checks
npm run test
npm run ci
```

--------------------------------

### resolveConfigChainSync(file, localIgnoredEnvironments?)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronously resolves the full precedence chain of existing configuration files for the current NODE_ENV. It returns an array of file paths, from most specific to least specific. Optionally, it can ignore certain local environments.

```APIDOC
## resolveConfigChainSync(file, localIgnoredEnvironments?)

### Description
Synchronously resolves the full precedence chain of existing configuration files for the current NODE_ENV. It returns an array of file paths, from most specific to least specific. Optionally, it can ignore certain local environments.

### Parameters
#### Path Parameters
- **file** (string) - Required - The base name of the configuration file (e.g., ".env").
- **localIgnoredEnvironments** (string[]) - Optional - An array of environment names to ignore for local overrides.

### Response
#### Success Response (Array<string>)
- An array of strings, where each string is a path to an existing configuration file, ordered by precedence (most specific first).

#### Response Example
```json
[
  "/app/.env.development.local",
  "/app/.env.local",
  "/app/.env.development",
  "/app/.env"
]
```
```

--------------------------------

### Yassa: Synchronous Bootstrap Before Async Context

Source: https://context7.com/constantiner/yassa/llms.txt

Loads configuration files synchronously using `resolveConfigChainForSync`. This pattern is essential for bootstrapping applications or libraries before the asynchronous event loop is available.

```typescript
// Pattern 3 — synchronous bootstrap before async context:
import { resolveConfigChainForSync } from "yassa";

const resolveBootstrapChain = resolveConfigChainForSync("production");
const bootstrapFiles = resolveBootstrapChain(".env");
// load synchronously before starting the event loop
```

--------------------------------

### Format and Lint Code with npm

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Apply code formatting and linting rules, with options to fix issues or just check compliance.

```bash
npm run lint
npm run lint:fix
npm run format
npm run format:check
```

--------------------------------

### resolveConfigFileSync

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronous counterpart of resolveConfigFile. Throws if NODE_ENV is missing or empty.

```APIDOC
## resolveConfigFileSync(file, localIgnoredEnvironments?)

### Description
Synchronous counterpart of `resolveConfigFile`.
Throws if `NODE_ENV` is missing or empty.

### Method
`resolveConfigFileSync`

### Parameters
#### Path Parameters
- **file** (string) - Required - The base configuration file name.
- **localIgnoredEnvironments** (string[]) - Optional - An array of environments whose local overrides should be ignored.

### Response
#### Success Response (string | undefined)
- The path to the top configuration file, or `undefined` if none is found.
```

--------------------------------

### resolveConfigChainFor(environment)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Asynchronously resolves the full precedence chain of existing configuration files for a specified environment, independent of NODE_ENV. It returns an array of file paths, from most specific to least specific.

```APIDOC
## resolveConfigChainFor(environment)

### Description
Asynchronously resolves the full precedence chain of existing configuration files for a specified environment, independent of NODE_ENV. It returns an array of file paths, from most specific to least specific.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name (e.g., "production").

### Response
#### Success Response (Array<string>)
- An array of strings, where each string is a path to an existing configuration file, ordered by precedence (most specific first).

#### Response Example
```json
[
  "/app/.env.production.local",
  "/app/.env.local",
  "/app/.env.production",
  "/app/.env"
]
```
```

--------------------------------

### resolveConfigFile

Source: https://github.com/constantiner/yassa/blob/main/README.md

Returns the top configuration file from resolveConfigChain. Returns undefined when no candidates exist. Throws if NODE_ENV is missing or empty.

```APIDOC
## resolveConfigFile(file, localIgnoredEnvironments?)

### Description
Returns the top file from `resolveConfigChain`.
Returns `undefined` when no candidates exist.
Throws if `NODE_ENV` is missing or empty.

### Method
`resolveConfigFile`

### Parameters
#### Path Parameters
- **file** (string) - Required - The base configuration file name.
- **localIgnoredEnvironments** (string[]) - Optional - An array of environments whose local overrides should be ignored.

### Response
#### Success Response (Promise<string | undefined>)
- The path to the top configuration file, or `undefined` if none is found.
```

--------------------------------

### Apply Versions from Changesets for Manual Release

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Use `npm run version-packages` to apply version bumps and generate changelogs based on pending changeset files during a manual release process.

```bash
npm run version-packages
```

--------------------------------

### resolveConfigFileFor

Source: https://github.com/constantiner/yassa/blob/main/README.md

Curried async factory for single-file resolution.

```APIDOC
## resolveConfigFileFor(environment)

### Description
Curried async factory for single-file resolution.

### Method
`resolveConfigFileFor`

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name.

### Response
#### Success Response ((file: string, localIgnoredEnvironments?: string[]) => Promise<string | undefined>)
- A function that resolves the top configuration file for the specified environment.
```

--------------------------------

### Verify Git Tags

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

List all git tags prefixed with 'v' using `git tag --list 'v*'` to confirm that release tags have been applied correctly.

```bash
git tag --list 'v*'
```

--------------------------------

### Run Project Checks and Formatting

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

If a pre-commit hook fails, run `npm run checks` to execute all project checks. Subsequently, use `npm run format` or `npm run lint:fix` to address any formatting or linting issues.

```bash
npm run checks
```

```bash
npm run format
```

```bash
npm run lint:fix
```

--------------------------------

### resolveConfigChainForSync(environment)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronously resolves the full precedence chain of existing configuration files for a specified environment, independent of NODE_ENV. It returns an array of file paths, from most specific to least specific.

```APIDOC
## resolveConfigChainForSync(environment)

### Description
Synchronously resolves the full precedence chain of existing configuration files for a specified environment, independent of NODE_ENV. It returns an array of file paths, from most specific to least specific.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name (e.g., "production").

### Response
#### Success Response (Array<string>)
- An array of strings, where each string is a path to an existing configuration file, ordered by precedence (most specific first).

#### Response Example
```json
[
  "/app/.env.production.local",
  "/app/.env.local",
  "/app/.env.production",
  "/app/.env"
]
```
```

--------------------------------

### resolveConfigFile(file, localIgnoredEnvironments?)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Asynchronously resolves the single most authoritative configuration file for the current NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found. Optionally, it can ignore certain local environments.

```APIDOC
## resolveConfigFile(file, localIgnoredEnvironments?)

### Description
Asynchronously resolves the single most authoritative configuration file for the current NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found. Optionally, it can ignore certain local environments.

### Parameters
#### Path Parameters
- **file** (string) - Required - The base name of the configuration file (e.g., ".env").
- **localIgnoredEnvironments** (string[]) - Optional - An array of environment names to ignore for local overrides.

### Response
#### Success Response (string | undefined)
- A string representing the path to the most authoritative configuration file, or `undefined` if no file is found.

#### Response Example
```json
"/app/.env.development.local"
```
```

--------------------------------

### resolveConfigFileFor(environment)

Source: https://context7.com/constantiner/yassa/llms.txt

Factory that creates a curried asynchronous single-file resolver. It returns the highest-precedence existing file path or `undefined` for a given environment.

```APIDOC
## resolveConfigFileFor(environment)

### Description
Factory that creates a curried async single-file resolver bound to an explicit environment. Returns the highest-precedence existing file or `undefined`. Internally calls `resolveConfigChainFor` and takes the first result.

### Method
Factory function that returns an async resolver function.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The environment string to bind the resolver to (e.g., "production", "staging").

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
import { resolveConfigFileFor } from "yassa";
import { readFile } from "node:fs/promises";

// Build an environment-specific file resolver:
const resolveProductionConfig = resolveConfigFileFor("production");

// Resolve and load config:
const prodConfigPath = await resolveProductionConfig("config/database.json");
if (!prodConfigPath) {
  throw new Error("Production database config not found");
}
const dbConfig = JSON.parse(await readFile(prodConfigPath, "utf8"));
console.log("Using DB config:", prodConfigPath);

// Staged resolution with fallback:
const resolveStagingConfig = resolveConfigFileFor("staging");
const stagingEnvFile = await resolveStagingConfig(".env");
console.log("Staging env file:", stagingEnvFile ?? "none found");

// Suppress local overrides in tests:
const resolveTestConfig = resolveConfigFileFor("test");
const testEnvPath = await resolveTestConfig(".env", ["test"]);
// Expected output: ".env.test" or ".env" — never a .local variant
```

### Response
#### Success Response
The file path of the highest-precedence existing configuration file, or `undefined` if no file is found.

#### Response Example
```json
"/app/config/database.production.json"
```
```

--------------------------------

### resolveConfigChainSync

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronous counterpart of resolveConfigChain. Throws if NODE_ENV is missing or empty.

```APIDOC
## resolveConfigChainSync(file, localIgnoredEnvironments?)

### Description
Synchronous counterpart of `resolveConfigChain`.
Throws if `NODE_ENV` is missing or empty.

### Method
`resolveConfigChainSync`

### Parameters
#### Path Parameters
- **file** (string) - Required - The base configuration file name.
- **localIgnoredEnvironments** (string[]) - Optional - An array of environments whose local overrides should be ignored.

### Response
#### Success Response (string[])
- An array of configuration file paths in order of precedence.
```

--------------------------------

### Run Fast Local Checks During Development

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Execute quick checks during development to maintain code quality and ensure tests pass. These commands help catch issues early before committing.

```bash
npm run checks
```

```bash
npm run test
```

--------------------------------

### Load Env Files with Precedence Chain

Source: https://github.com/constantiner/yassa/blob/main/README.md

This pattern demonstrates how to load environment variables using the `dotenv` library by first resolving the configuration chain with `yassa`. It iterates through the resolved files and applies them, respecting the precedence order.

```typescript
import { config as dotenvConfig } from "dotenv";
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = process.env.NODE_ENV || "development";

for (const file of await resolveConfigChain(".env", ["test"])) {
	dotenvConfig({ path: file, override: false });
}
```

--------------------------------

### Configure npm Token Authentication in Workflow

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

If switching to token-based fallback publishing, configure the workflow to write the npm authentication token to the user's home directory. This ensures the token is used for publishing without being committed to the project's `.npmrc`.

```bash
//registry.npmjs.org/:_authToken=$NPM_TOKEN
```

--------------------------------

### Create Async Single File Resolver

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigFileFor` to create a factory for async single-file resolvers. It returns the highest-precedence existing file path or `undefined`, internally using `resolveConfigChainFor`.

```typescript
import { resolveConfigFileFor } from "yassa";
import { readFile } from "node:fs/promises";

// Build an environment-specific file resolver:
const resolveProductionConfig = resolveConfigFileFor("production");
const resolveStagingConfig = resolveConfigFileFor("staging");

// Resolve and load config:
const prodConfigPath = await resolveProductionConfig("config/database.json");
if (!prodConfigPath) {
  throw new Error("Production database config not found");
}
const dbConfig = JSON.parse(await readFile(prodConfigPath, "utf8"));
console.log("Using DB config:", prodConfigPath);

// Staged resolution with fallback:
const stagingEnvFile = await resolveStagingConfig(".env");
console.log("Staging env file:", stagingEnvFile ?? "none found");

// Suppress local overrides in tests:
const resolveTestConfig = resolveConfigFileFor("test");
const testEnvPath = await resolveTestConfig(".env", ["test"]);
// Returns ".env.test" or ".env" — never a .local variant
```

--------------------------------

### resolveConfigFileForSync

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronous counterpart of resolveConfigFileFor.

```APIDOC
## resolveConfigFileForSync(environment)

### Description
Synchronous counterpart of `resolveConfigFileFor`.

### Method
`resolveConfigFileForSync`

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name.

### Response
#### Success Response ((file: string, localIgnoredEnvironments?: string[]) => string | undefined)
- A function that synchronously resolves the top configuration file for the specified environment.
```

--------------------------------

### resolveConfigFileSync(file, localIgnoredEnvironments?)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronously resolves the single most authoritative configuration file for the current NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found. Optionally, it can ignore certain local environments.

```APIDOC
## resolveConfigFileSync(file, localIgnoredEnvironments?)

### Description
Synchronously resolves the single most authoritative configuration file for the current NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found. Optionally, it can ignore certain local environments.

### Parameters
#### Path Parameters
- **file** (string) - Required - The base name of the configuration file (e.g., ".env").
- **localIgnoredEnvironments** (string[]) - Optional - An array of environment names to ignore for local overrides.

### Response
#### Success Response (string | undefined)
- A string representing the path to the most authoritative configuration file, or `undefined` if no file is found.

#### Response Example
```json
"/app/.env.development.local"
```
```

--------------------------------

### Manual Release Fallback

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Use this command as a manual fallback for the release process. It intentionally runs full validation ('npm run ci') before executing the publish step ('npm run release:publish').

```bash
npm run release
```

--------------------------------

### resolveConfigFileFor(environment)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Asynchronously resolves the single most authoritative configuration file for a specified environment, independent of NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found.

```APIDOC
## resolveConfigFileFor(environment)

### Description
Asynchronously resolves the single most authoritative configuration file for a specified environment, independent of NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name (e.g., "production").

### Response
#### Success Response (string | undefined)
- A string representing the path to the most authoritative configuration file, or `undefined` if no file is found.

#### Response Example
```json
"/app/.env.production.local"
```
```

--------------------------------

### Create Sync Config Chain Resolver

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigChainForSync` for synchronous configuration loading during app bootstrap. It provides a curried sync resolver bound to a specified environment, mirroring the async version's contract and precedence.

```typescript
import { resolveConfigChainForSync } from "yassa";

const resolveProdChainSync = resolveConfigChainForSync("production");

// Use during synchronous app bootstrap:
const files = resolveProdChainSync("config/app.json");
// e.g. [
//   "/app/config/app.production.local.json",
//   "/app/config/app.production.json",
//   "/app/config/app.json"
// ]

// Supports dotted filenames (.env.json):
const resolveQaChainSync = resolveConfigChainForSync("qa");
const dotEnvJsonFiles = resolveQaChainSync(".env.json");
// ["/app/.env.qa.local.json", "/app/.env.local.json", "/app/.env.qa.json", "/app/.env.json"]

// Trailing-dot filenames (index.) are also supported:
const trailingDotFiles = resolveQaChainSync("index.");
// ["/app/index.qa.local.", "/app/index.local.", "/app/index.qa.", "/app/index."]
```

--------------------------------

### resolveConfigFileForSync(environment)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronously resolves the single most authoritative configuration file for a specified environment, independent of NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found.

```APIDOC
## resolveConfigFileForSync(environment)

### Description
Synchronously resolves the single most authoritative configuration file for a specified environment, independent of NODE_ENV. It returns the path to the most specific existing file, or undefined if no file is found.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name (e.g., "production").

### Response
#### Success Response (string | undefined)
- A string representing the path to the most authoritative configuration file, or `undefined` if no file is found.

#### Response Example
```json
"/app/.env.production.local"
```
```

--------------------------------

### Create Sync Single File Resolver

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigFileForSync` for synchronous resolution of a single configuration file. It returns the most specific existing file path or `undefined`, suitable for synchronous app bootstrapping.

```typescript
import { resolveConfigFileForSync } from "yassa";

const resolveProdConfigSync = resolveConfigFileForSync("production");
const resolveDevConfigSync = resolveConfigFileForSync("development");

// Synchronous use — e.g. in a CLI entry point before async context is available:
const prodEnvFile = resolveProdConfigSync(".env");
console.log("Production env file:", prodEnvFile ?? "not found");
// e.g. "/app/.env.production.local"

const devAppConfig = resolveDevConfigSync("config/app.json");
if (devAppConfig) {
  console.log("Dev config path:", devAppConfig);
}

// localIgnoredEnvironments works the same as async variant:
const resolveTestConfigSync = resolveConfigFileForSync("test");
const testFile = resolveTestConfigSync(".env", ["test"]);
// ".env.test" or ".env" — never a .local variant
```

--------------------------------

### resolveConfigChain

Source: https://github.com/constantiner/yassa/blob/main/README.md

Resolves an existing chain of configuration files for the current NODE_ENV. Throws if NODE_ENV is missing or empty.

```APIDOC
## resolveConfigChain(file, localIgnoredEnvironments?)

### Description
Resolves existing chain for current `NODE_ENV`.
Throws if `NODE_ENV` is missing or empty.

### Method
`resolveConfigChain`

### Parameters
#### Path Parameters
- **file** (string) - Required - The base configuration file name.
- **localIgnoredEnvironments** (string[]) - Optional - An array of environments whose local overrides should be ignored.

### Response
#### Success Response (Promise<string[]>)
- An array of configuration file paths in order of precedence.
```

--------------------------------

### resolveConfigChainFor

Source: https://github.com/constantiner/yassa/blob/main/README.md

Curried async factory for environment-bound chain resolution.

```APIDOC
## resolveConfigChainFor(environment)

### Description
Curried async factory for environment-bound chain resolution.

### Method
`resolveConfigChainFor`

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name.

### Response
#### Success Response ((file: string, localIgnoredEnvironments?: string[]) => Promise<string[]>)
- A function that resolves an existing chain for the specified environment.
```

--------------------------------

### resolveConfigChainForSync

Source: https://github.com/constantiner/yassa/blob/main/README.md

Synchronous counterpart of resolveConfigChainFor.

```APIDOC
## resolveConfigChainForSync(environment)

### Description
Synchronous counterpart of `resolveConfigChainFor`.

### Method
`resolveConfigChainForSync`

### Parameters
#### Path Parameters
- **environment** (string) - Required - The explicit environment name.

### Response
#### Success Response ((file: string, localIgnoredEnvironments?: string[]) => string[])
- A function that synchronously resolves an existing chain for the specified environment.
```

--------------------------------

### Yassa: dotenv Multi-layer Bootstrap (Async)

Source: https://context7.com/constantiner/yassa/llms.txt

Loads environment variables from multiple .env files in precedence order using Yassa's `resolveConfigChain` and `dotenv`. This pattern is suitable for runtime environment variable bootstrapping where `NODE_ENV` is dynamically set.

```typescript
// Pattern 1 — dotenv multi-layer bootstrap (async, runtime NODE_ENV):
import { config as dotenvConfig } from "dotenv";
import { resolveConfigChain } from "yassa";

process.env.NODE_ENV = process.env.NODE_ENV ?? "development";

for (const file of await resolveConfigChain(".env", ["test"])) {
  dotenvConfig({ path: file, override: false });
}
```

--------------------------------

### Resolve config file chain synchronously

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigChainSync` for a synchronous counterpart to `resolveConfigChain`. It uses synchronous filesystem calls and throws if NODE_ENV is missing.

```typescript
import { resolveConfigChainSync } from "yassa";

process.env.NODE_ENV = "production";

const files = resolveConfigChainSync("config/app.json");
// e.g. [
//   "/app/config/app.production.local.json",
//   "/app/config/app.production.json",
//   "/app/config/app.json"
// ]

// Use result to drive synchronous config loading:
for (const file of files) {
  console.log("Loading:", file);
}

// Throws synchronously on missing NODE_ENV:
delete process.env.NODE_ENV;
try {
  resolveConfigChainSync("config/app.json");
} catch (err) {
  console.error(err.message); // "The NODE_ENV environment variable is required. ..."
}
```

--------------------------------

### Verify GitHub Releases

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

List all releases associated with the GitHub repository using the `gh release list` command to ensure they are correctly created.

```bash
gh release list
```

--------------------------------

### resolveConfigChainFor(environment)

Source: https://context7.com/constantiner/yassa/llms.txt

Factory that creates a curried asynchronous chain resolver bound to a specific environment. It resolves multiple configuration files based on precedence rules, supporting environment-specific and local overrides.

```APIDOC
## resolveConfigChainFor(environment)

### Description
Factory that creates a curried async chain resolver bound to an explicit environment string, independent of `process.env.NODE_ENV`. Throws at call time (not factory time) when the bound environment is blank or whitespace-only.

### Method
Factory function that returns an async resolver function.

### Parameters
#### Path Parameters
- **environment** (string) - Required - The environment string to bind the resolver to (e.g., "development", "staging").

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
import { resolveConfigChainFor } from "yassa";

// Create reusable resolver for a specific environment:
const resolveDevChain = resolveConfigChainFor("development");

// Resolve multiple files with the same resolver:
const envFiles = await resolveDevChain(".env");
// Expected output: ["/app/.env.development.local", "/app/.env.local", "/app/.env.development", "/app/.env"]

// Team-reproducible test mode (no .local overrides):
const resolveTestChain = resolveConfigChainFor("test");
const testFiles = await resolveTestChain(".env", ["test"]);
// Expected output: ["/app/.env.test", "/app/.env"]

// Blank environment throws when resolver is invoked:
const badResolver = resolveConfigChainFor("   ");
try {
  await badResolver(".env");
} catch (err) {
  console.error(err.message); // "Environment must be a non-empty string."
}
```

### Response
#### Success Response
An array of file paths in order of precedence.

#### Response Example
```json
[
  "/app/.env.development.local",
  "/app/.env.local",
  "/app/.env.development",
  "/app/.env"
]
```
```

--------------------------------

### Run Full CI Validation

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Execute the full CI validation pipeline locally before creating a changeset or pushing. This ensures all checks pass, including formatting, linting, type checking, test coverage, and building.

```bash
npm run ci
```

--------------------------------

### Verify Published npm Package Versions

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Check the published versions of the `yassa` package on npm using `npm view` with the `--json` flag for structured output.

```bash
npm view yassa versions --json
```

--------------------------------

### Optional Development Workflow Commands

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Utilize these optional commands for tasks like automatically fixing linting issues, applying formatting, or running tests in watch mode during active development.

```bash
npm run lint:fix
```

```bash
npm run format
```

```bash
npm run test:watch
```

--------------------------------

### Yassa: Reusable Typed Resolver as Dependency

Source: https://context7.com/constantiner/yassa/llms.txt

Creates a reusable environment loader function that accepts a typed `ConfigHierarchyFilesResolver`. This pattern promotes clean dependency injection and testability by abstracting the resolver logic.

```typescript
// Pattern 4 — reusable typed resolver passed as dependency:
import type { ConfigHierarchyFilesResolver } from "yassa";
import { resolveConfigChainFor } from "yassa";

function createEnvLoader(resolver: ConfigHierarchyFilesResolver) {
  return (file: string, ignoredEnvs?: string[]) => resolver(file, ignoredEnvs);
}

const loadTestEnv = createEnvLoader(resolveConfigChainFor("test"));
const testFiles = await loadTestEnv(".env", ["test"]);
```

--------------------------------

### Create Async Config Chain Resolver

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigChainFor` to create a reusable async resolver for a specific environment. This factory function is useful for setting up environment-specific configuration loading logic that can be invoked multiple times.

```typescript
import { resolveConfigChainFor } from "yassa";

// Create reusable resolver for a specific environment:
const resolveDevChain = resolveConfigChainFor("development");
const resolveStagingChain = resolveConfigChainFor("staging");

// Resolve multiple files with the same resolver:
const envFiles = await resolveDevChain(".env");
// ["/app/.env.development.local", "/app/.env.local", "/app/.env.development", "/app/.env"]

const appConfigs = await resolveDevChain("config/app.json");
// ["/app/config/app.development.local.json", "/app/config/app.development.json", ...]

// Team-reproducible test mode (no .local overrides):
const resolveTestChain = resolveConfigChainFor("test");
const testFiles = await resolveTestChain(".env", ["test"]);
// ["/app/.env.test", "/app/.env"]  — .env.test.local and .env.local excluded

// Blank environment throws when resolver is invoked:
const badResolver = resolveConfigChainFor("   ");
try {
  await badResolver(".env");
} catch (err) {
  console.error(err.message); // "Environment must be a non-empty string."
}
```

--------------------------------

### View a Specific Release Workflow Run

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Inspect the details of a particular release workflow run by providing its unique `RUN_ID` to the `gh run view` command.

```bash
gh run view RUN_ID
```

--------------------------------

### Commit Changes

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Stage all changes and commit them with a message. This command also triggers pre-commit hooks like lint-staged and typecheck to ensure code quality before committing.

```bash
git add .
git commit -m "feat: ..."
```

--------------------------------

### Resolve the most authoritative config file synchronously

Source: https://context7.com/constantiner/yassa/llms.txt

Use `resolveConfigFileSync` for a synchronous counterpart to `resolveConfigFile`. It returns the single most specific existing file path or undefined. Throws if NODE_ENV is missing.

```typescript
import { resolveConfigFileSync } from "yassa";

process.env.NODE_ENV = "development";

const file = resolveConfigFileSync(".env");

if (file) {
  console.log("Active config file:", file);
  // e.g. "/app/.env.development.local"
} else {
  console.log("No config file found — using built-in defaults");
}
```

--------------------------------

### List Recent Release Workflow Runs

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Use the `gh run list` command to view recent executions of the `release.yml` workflow, limited to the last 20 runs.

```bash
gh run list --workflow release.yml --limit 20
```

--------------------------------

### Resolve Config Chain for Explicit Environment

Source: https://github.com/constantiner/yassa/blob/main/README.md

Utilize `resolveConfigChainFor` and `resolveConfigFileFor` to create resolvers for a specific environment, independent of `NODE_ENV`. This is useful for scenarios where you need to manage configurations for different environments explicitly.

```typescript
import { resolveConfigChainFor, resolveConfigFileFor } from "yassa";

const resolveStagingChain = resolveConfigChainFor("staging");
const resolveStagingFile = resolveConfigFileFor("staging");

const chain = await resolveStagingChain(".env");
const top = await resolveStagingFile(".env");
```

--------------------------------

### Resolve Config Chain for Test Mode (Ignore Local)

Source: https://github.com/constantiner/yassa/blob/main/README.md

Employ `resolveConfigChainFor` with an array of ignored environments to exclude local overrides during testing. This ensures team-reproducible test runs by preventing local machine configurations from influencing test results.

```typescript
import { resolveConfigChainFor } from "yassa";

const resolveTestChain = resolveConfigChainFor("test");
const chain = await resolveTestChain(".env", ["test"]);

// For test env, local overrides are excluded:
// ["/app/.env.test", "/app/.env"]
```

--------------------------------

### Push to Origin

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Push your feature branch to the remote origin. This action will typically trigger CI workflows on the pull request.

```bash
git push -u origin feat/short-description
```

--------------------------------

### Yassa: Single Authoritative JSON Config (Async)

Source: https://context7.com/constantiner/yassa/llms.txt

Resolves a single, most specific JSON configuration file based on the current environment using `resolveConfigFileFor`. This is useful for libraries or applications needing a single authoritative config file.

```typescript
// Pattern 2 — single authoritative JSON config (async, explicit environment):
import { readFile } from "node:fs/promises";
import { resolveConfigFileFor } from "yassa";

const resolveAppConfig = resolveConfigFileFor(process.env.NODE_ENV ?? "development");
const configPath = await resolveAppConfig("config/app.json");
if (!configPath) throw new Error("No app config file found");
const appConfig = JSON.parse(await readFile(configPath, "utf8"));
```

--------------------------------

### Manually Trigger Release Workflow

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

For recovery or debugging purposes, manually trigger the `release.yml` workflow on the current main branch using the `gh workflow run` command.

```bash
gh workflow run release.yml
```

--------------------------------

### Resolve Most Authoritative Config File

Source: https://github.com/constantiner/yassa/blob/main/README.md

Use `resolveConfigFile` to find the single most authoritative configuration file based on the `NODE_ENV` environment variable. The result can be a file path or undefined if no suitable file is found.

```typescript
import { resolveConfigFile } from "yassa";

process.env.NODE_ENV = "production";

const file = await resolveConfigFile("config/app.json");
// "/app/config/config/app.production.local.json" | ... | undefined
```

--------------------------------

### Show Merge Commit Metadata for Version Packages PR

Source: https://github.com/constantiner/yassa/blob/main/DEVELOPMENT.md

Retrieve detailed metadata about the merge commit for a 'Version Packages' Pull Request, identified by its `PR_NUMBER`, using `gh pr view`.

```bash
gh pr view PR_NUMBER --json number,title,headRefName,baseRefName,mergedAt,mergeCommit
```

--------------------------------

### TypeScript Types for Yassa Resolvers

Source: https://context7.com/constantiner/yassa/llms.txt

Imports and defines type aliases for Yassa's resolver functions, enabling type-safe dependency injection. Use these types to ensure correct function signatures when passing resolvers as dependencies.

```typescript
import type {
  LocalIgnoredEnvironments,
  ConfigHierarchyFilesResolver,
  ConfigHierarchyFilesResolverSync,
  ConfigHierarchyFileResolver,
  ConfigHierarchyFileResolverSync
} from "yassa";

// Type-safe dependency injection example:
function createConfigLoader(resolver: ConfigHierarchyFileResolver) {
  return async (file: string): Promise<unknown> => {
    const { readFile } = await import("node:fs/promises");
    const path = await resolver(file);
    if (!path) return {};
    return JSON.parse(await readFile(path, "utf8"));
  };
}

// Wire up with a factory:
import { resolveConfigFileFor } from "yassa";
const loader = createConfigLoader(resolveConfigFileFor("production"));
const config = await loader("config/app.json");

// LocalIgnoredEnvironments type for typed localIgnoredEnvironments arrays:
const ignoredEnvs: LocalIgnoredEnvironments = ["test", "ci"];
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.