# generator

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module turns a validated `PromptAnswers` record into either an
in-memory list of `GeneratedFile` records (`generate`) or a tree
materialised on disk (`scaffold`). Splitting the two lets snapshot tests
inspect the rendered tree byte-for-byte without touching the filesystem,
and lets the bin entrypoint stream the same tree out to disk through a
single typed failure surface.

## Features

- Pure `generate(options)` returns a deterministic, ordered list of
  files for snapshot comparison.
- `scaffold(options)` writes the tree atomically, raising
  `SCAFFOLD.DIRECTORY_EXISTS` when the target is non-empty (unless
  `force` is set) and `SCAFFOLD.WRITE_FAILED` for every fs error.
- Engine validation raises `SCAFFOLD.UNKNOWN_ENGINE` for any database
  value outside the closed vocabulary.

## Usage

### Basic example

```ts
import { scaffold, answersForFixture } from "create-suaveplan-plugin";

const answers = answersForFixture("isolated-sqlite-rest-only", "my-plugin");
scaffold({ answers, targetDir: "./my-plugin" });
```

### Advanced example

```ts
import { generate, answersForFixture } from "create-suaveplan-plugin";

const tree = generate({
    answers: answersForFixture("trusted-postgres-full", "billing"),
});
for (const file of tree) {
    console.log(file.path, file.content.length);
}
```

## API Reference

- `generate(options: GenerateOptions): readonly GeneratedFile[]` — pure
  in-memory render. Validates answers first.
- `scaffold(options: ScaffoldOptions): ScaffoldResult` — writes to disk.
- `GeneratedFile` — `{ readonly path: string; readonly content: string }`.
- `ScaffoldOptions` — `{ answers, targetDir, force? }`.
- `ScaffoldResult` — `{ files: readonly string[] }` (relative paths).

## Implementation Notes

- `directoryIsNonEmpty` swallows ENOENT — a missing target is treated
  as empty so the first-time path needs no special case.
- Errors during write are wrapped in `ScaffoldError` with `cause` set
  to the original `fs` error, so callers retain the original stack via
  the standard `Error.cause` chain.
- The path order returned by `generate` is stable; snapshot tests rely
  on this when asserting tree equality.
- Coverage is enforced at 100% by the snapshot fixtures plus the
  explicit error-path tests in `generator.test.ts`.