skills/docs/api-stack/api/create-suaveplan-plugin/README.md

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.

Documentation tree

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

Quick start

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

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 ScaffoldErrors. 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:

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