59 lines
4.3 KiB
Markdown
59 lines
4.3 KiB
Markdown
# `create-suaveplan-plugin` — interactive scaffold for new plugins
|
|
|
|
**Package**: `create-suaveplan-plugin`
|
|
**Status**: PROPOSED
|
|
**Type**: new-package
|
|
**Stage**: 8 — see umbrella `openspec/changes/api-plugin-foundation/`
|
|
|
|
## Why
|
|
|
|
Per design doc §13.7, plugin authors should never start from an empty directory. `create-suaveplan-plugin <name>` generates a complete, immediately-testable plugin skeleton with `plugin.json`, `definePlugin` body, host-test, integration test (with real Postgres when DB is selected), both vitest configs, migrations, and a README. The author runs `bun test`, sees green, then replaces the skeleton.
|
|
|
|
The scaffold ships AS a plugin loaded by `@suaveplan/installer` — consistent with how `install-agent-skills` works. The binary entrypoint is `bunx create-suaveplan-plugin <name>` (or `bun create suaveplan-plugin <name>`).
|
|
|
|
## What changes
|
|
|
|
- ADDED: Bin `create-suaveplan-plugin` mounted under `@suaveplan/installer` plugin host.
|
|
- ADDED: Interactive prompt asking about: plugin name, isolation tier, capabilities selected (multi-select), DB engine (postgres / sqlite / surrealdb / none), whether to scaffold GraphQL / WS / SSE / sagas / 2PC / per-tenant jobs.
|
|
- ADDED: Template output, generated atomically into a fresh directory:
|
|
- `plugin.json` — every section commented with explanatory text AND populated with minimal viable values for selected capabilities.
|
|
- `src/index.ts` — `definePlugin({ ... })` skeleton hitting every selected capability with TODO-marked handler bodies that compile + pass type-check on day one.
|
|
- `src/index.test.ts` — `createTestHost` against the skeleton; one `it(...)` per capability declaring "host wires the capability + calls a no-op handler".
|
|
- `tests/integration/example.integration.test.ts` — uses `testing-integration-postgres` (or sqlite / surrealdb per prompt). Runs only when `INTEGRATION=1`.
|
|
- `vitest.config.ts` and `vitest.integration.config.ts` — pre-wired with `createTestConfig` from `@suaveplan/testing`.
|
|
- `migrations/<engine>/0001-init.sql` — empty boilerplate matching the DB engine.
|
|
- `README.md` — manifest + lifecycle + capability docs filled in for the selected surface.
|
|
- `package.json` — version 0.0.0, deps for selected capabilities, scripts (`test`, `test:integration`, `test:coverage`, `lint`, `typecheck`, `build`).
|
|
- `tsconfig.json` — extends `@suaveplan/typescript-config/library-node`.
|
|
- `.gitignore`, biome config inheritance.
|
|
- ADDED: Snapshot test of the generated tree — `tests/scaffold-output/scaffold-output.test.ts` runs the generator against a fixture prompt set and asserts the produced files match a committed snapshot byte-for-byte.
|
|
- ADDED: Error codes (`SCAFFOLD_*`): `INVALID_NAME`, `DIRECTORY_EXISTS`, `WRITE_FAILED`, `UNKNOWN_ENGINE`.
|
|
|
|
## Out of scope
|
|
|
|
- Publishing the scaffolded plugin to a registry — author's job.
|
|
- Continuous-update flow (re-running scaffold to add a capability later) — separate change.
|
|
- Web UI for the scaffold — CLI only in v1.
|
|
|
|
## Source mapping
|
|
|
|
Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
|
|
|
|
| Requirement | Design doc section |
|
|
|---|---|
|
|
| `create-suaveplan-plugin <name>` scaffold | §13.7 |
|
|
| Generated files compile + `bun test` green immediately | §13.7 |
|
|
| Integration test wired with `testing-integration-postgres` when DB selected | §13.7 |
|
|
|
|
## Verification approach
|
|
|
|
- `src/prompt/prompt.test.ts` — every prompt branch produces the right capability set; invalid names raise `SCAFFOLD_INVALID_NAME`.
|
|
- `src/generator/generator.test.ts` — each template file renders with the right substitutions for a given prompt set.
|
|
- `tests/scaffold-output/scaffold-output.test.ts` — snapshot test: run the generator against three fixture prompt sets (trusted+postgres+full, isolated+sqlite+REST-only, sandboxed+none+REST-only) and assert the produced tree matches `tests/scaffold-output/snapshots/<fixture>/**` byte-for-byte.
|
|
- `tests/scaffold-output/runs-bun-test.test.ts` — for each fixture, run `bun test` against the generated tree AND assert exit code 0 (proves the scaffold is immediately green).
|
|
- `tests/dep-graph.test.ts` — runtime deps.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only. The scaffold is published as a separate npm package consumable via `bunx create-suaveplan-plugin <name>`.
|