86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 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
|
|
```
|
|
|