# create-suaveplan-plugin

Interactive scaffold for new Suaveplan API plugins. Generates a complete,
immediately-testable plugin skeleton — `plugin.json`, `definePlugin`
body, host test, optional integration test wired to the matching
`testing-integration-{postgres,sqlite,surrealdb}` fixture, both vitest
configs, migrations, and a README — tailored to the selected isolation
tier, capability set, and DB engine.

<!-- begin:auto-docs -->
## Documentation tree

- [bin](./src/bin/create-suaveplan-plugin.md) — This module is the executable entry-point for the `create-suaveplan-plugin` scaffolder. It parses argv into a `ParsedAr…
  - [create-suaveplan-plugin](./src/bin/create-suaveplan-plugin.md) — This module is the executable entry-point for the `create-suaveplan-plugin` scaffolder. It parses argv into a `ParsedAr…
- [generator](./src/generator/generator.md) — This module turns a validated `PromptAnswers` record into either an in-memory list of `GeneratedFile` records (`generat…
  - [generator](./src/generator/generator.md) — This module turns a validated `PromptAnswers` record into either an in-memory list of `GeneratedFile` records (`generat…
- [prompt](./src/prompt/prompt.md) — This module defines the closed prompt-answer surface for the scaffold (`PromptAnswers`, `IsolationTier`, `DatabaseEngin…
  - [prompt](./src/prompt/prompt.md) — This module defines the closed prompt-answer surface for the scaffold (`PromptAnswers`, `IsolationTier`, `DatabaseEngin…
- [templates](./src/templates/templates.md) — This module owns the per-file render functions that produce the scaffolded plugin tree. Every output file (manifest, so…
  - [templates](./src/templates/templates.md) — This module owns the per-file render functions that produce the scaffolded plugin tree. Every output file (manifest, so…
- [error-codes](./src/error-codes.md) — This module declares the frozen, namespaced registry of every failure code the `create-suaveplan-plugin` scaffold can r…
<!-- end:auto-docs -->

## Quick start

```bash
bunx create-suaveplan-plugin my-plugin --fixture trusted-postgres-full
cd my-plugin
bun test
```

Three fixtures cover the canonical permutations:

| Fixture | Isolation | Database | Capabilities |
| --- | --- | --- | --- |
| `trusted-postgres-full` | `trusted` | `postgres` | rest, graphql, ws, sse, sagas, twoPhaseCommit, perTenantJobs |
| `isolated-sqlite-rest-only` | `isolated` | `sqlite` | rest |
| `sandboxed-none-rest-only` | `sandboxed` | `none` | rest |

## CLI flags

- `<name>` — positional plugin name (validated against npm rules).
- `--fixture <id>` — one of the three fixtures above (default
  `sandboxed-none-rest-only`).
- `--dir <path>` — explicit target directory (default `<cwd>/<name>`).
- `--force` — overwrite an existing non-empty target.

## Programmatic API

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

scaffold({
    answers: answersForFixture("isolated-sqlite-rest-only", "billing-plugin"),
    targetDir: "./billing-plugin",
    force: false,
});
```

## Error codes

The scaffold raises only typed `ScaffoldError`s. Every code is namespaced
as `SCAFFOLD.*`:

- `SCAFFOLD.INVALID_NAME` — name violates npm-package-name rules.
- `SCAFFOLD.DIRECTORY_EXISTS` — target is non-empty and `--force` was not given.
- `SCAFFOLD.WRITE_FAILED` — fs write failed; original error attached via `cause`.
- `SCAFFOLD.UNKNOWN_ENGINE` — engine outside the closed vocabulary.

## Verification

The package ships three verification surfaces:

1. **Unit tests** — every render branch, every prompt validation case.
2. **Snapshot tests** — byte-for-byte against the committed
   `tests/scaffold-output/snapshots/<fixture>/**` trees.
3. **Scaffold-and-run** — for each fixture, scaffold to a temp dir and
   run `bun test` against it. Exit code must be 0.

Run the full gate via:

```bash
bunx --bun turbo lint typecheck test:coverage --filter=create-suaveplan-plugin
```