# Muse

_Bind data into anything_

## Overview

**Muse** is a CLI and toolchain for operating on data collected from
json, yaml, toml, and markdown files.

Muse scans included files, parses them into data, and streams
the loaded data through plugins.

Each plugin can modify the data as well as enact side effects
such as writing files to disk.

## Usage

```plaintext
Usage:
  muse [/path/to/binding.yaml] <options>

Options:
  --stdout    -s  Output final data to stdout
  --verbose,  -v  Enable verbose logging
  --help,     -h  Show this help message
```

## Binding File

Each Muse project should specify a `binding` file with the following shape:
```yaml
sources:                    # Optional
  - file: "**/*.yaml"
  - web: "https://example.com/data.json"
contentKey: "content"       # Optional
options:                    # Optional
  someOption: someValue
processors:
  - first-processor
  - second-processor
```

The `binding` file can be any of the supported file types for Muse and can
be named anything. If the CLI is invoked with a directory instead of a file,
Muse will look for a binding file in the directory with the following order:

1. `binding.json`
2. `binding.yaml`
3. `binding.toml`
4. `binding.md`

## Markdown Files

Muse supports loading and parsing Markdown files with optional YAML frontmatter.

```
---
someKey: someValue
---

Your markdown content here
```

When loading markdown files, Muse will load the content of the file
into a key called `content` by default. This can be changed in the binding
configuration by setting a `contentKey` value as an override.

## Plugin API

Muse plugins are written in TypeScript/JavaScript and expose information
describing the plugin, as well as the functions to operate with:

```typescript
export const name = "Plugin Name";
export const description = "Plugin Description";
export async function step(binding: Binding): Promise<Binding> {}
```

The main function of a plugin is `step`, which takes a `Binding` object
and returns a modified `Binding` object.

When returning a new Binding object, it is best practice to make immutable
changes:

```typescript
export async function step(binding: Binding): Promise<Binding> {
  const newBinding = { ...binding };
  newBinding.options.someOption = "newValue";
  return {
    ...binding,
    meta: {
      ...binding.meta,
      customValue: true,
    }
  };
}
```