suaveplan/openspec/archive/2026-05-25-enterprise-electrobun/proposal.md

Proposal — Migrate @suaveplan/electrobun to genesis

• Design: ./design.md
• Spec delta: ./specs/electrobun/spec.md

Why

Upstream @suaveplan/electrobun (/mnt/s/web/suaveplan/packages/universal/electrobun/) is a thin scaffolder: it prompts the user for an app name and a feature list, runs an iconz-backed icon pipeline, and emits a fixed-template Electrobun project to disk. The genesis enterprise/electrobun.md audit highlights five structural gaps:

1. every failure path is either an Error literal or a console.log, so consumers cannot discriminate between "icon source missing" and "rollup chain blew up";
2. no OpenTelemetry surface for what is the entry point new contributors hit first;
3. the generator is hard-wired to node:fs with no seam for tests or for embedding in CI;
4. only the create step is covered — operators have nothing for dev (watch + restart), build (cross-platform packaging), package (release-bundle assembly), sign (notarization + entitlements), or the auto-update pipeline; and
5. the renderXxxFeature() template functions are inlined-string blobs with no validation of the render input, so a stale ProjectOptions shape silently produces a broken project.

Genesis cleans up the contract: every failure raises a typed ElectrobunError carrying a stable ELECTROBUN.* code; every command and every render-helper takes an injectable seam (FsAdapter, CommandRunner, IconRendererAdapter, Prompter); every public option is Zod-validated; the CLI grows from one command (create) to five (create, dev, build, package, sign); and an OTel surface (5 counters + 2 histograms) makes the package observable in CI.

What

Land @suaveplan/electrobun@0.1.0 at packages/devtools/tooling/electrobun/ with the following feature modules (one folder per feature, sibling .md per implementation file; no electrobun- prefix inside the package):

• error-codes/ — ELECTROBUN_CODES = defineCodes("ELECTROBUN", [...]) and ElectrobunError.
• telemetry/ — OTel counters + histograms (projects_generated_total, icons_generated_total, runner_invocations_total, runner_failures_total, prompts_total, generate_duration_ms, runner_duration_ms).
• types/ — shared interfaces (ProjectOptions, ElectrobunConfig, GeneratedFile, FsAdapter, CommandRunner, CommandInput, CommandResult, IconRendererAdapter, Prompter, every *Report / *Options).
• schemas/ — Zod schemas for every public type; both schema and inferred type exported.
• fs/ — nodeFsAdapter and seam-driven ensureDirectory, directoryExists, directoryIsEmpty, writeFiles, findConfigFile.
• runner/ — CommandRunner contract + nodeCommandRunner default (spawn-based).
• config/ — loadConfig(cliArgs, opts?) consuming the @suaveplan/config 5-layer pipeline (defaults / file / CLI) with the FsAdapter injected for file discovery.
• templates/ — render helpers for every project file (electrobun-config, main-process, package-json, tsconfig, readme, mainview-html, mainview-css, mainview-entry, shared-types) plus templates/features/ for every feature renderer (i18n, network, network-full, api, api-schemas, storage, auth, form-builder, r3f).
• generator/ — collectFiles(options), generate(options, opts?) — orchestrates the renderer table, writes via FsAdapter, returns a GenerateReport.
• icons/ — generateIcons(opts, deps?) — wraps iconz via the IconRendererAdapter seam.
• prompts/ — runPrompts(config, outputDir, prompter?).
• cli/ — five pure functions (createCommand, devCommand, buildCommand, packageCommand, signCommand) and runCli(argv, opts?). Each returns a *Report; none call process.exit.
• bin/ — suaveplan-electrobun binary wiring runCli through process.argv.slice(2).

Parity Checklist

Capability	Upstream	Migrated	Notes
ProjectOptions / ElectrobunConfig types	upstream	yes	Preserved; now Zod-validated.
FEATURE_LABELS, R3F_MODULE_LABELS	upstream	yes	Preserved.
FeatureModule, NetworkingComplexity, R3fModule unions	upstream	yes	Preserved verbatim.
loadConfig(cliArgs) layered loader	upstream	yes	Now consumes @suaveplan/config's 5-layer pipeline; findConfigFile is FsAdapter-driven.
directoryExists / directoryIsEmpty / ensureDirectory / writeFiles	upstream	yes	Preserved; injectable FsAdapter.
collectFiles(options) core file list	upstream	yes	Preserved with deterministic ordering.
generate(options) orchestrator	upstream	enhanced	Returns GenerateReport; emits OTel histogram.
generateIcons(input, outputDir)	upstream	enhanced	Takes an IconRendererAdapter seam; default = real iconz. Returns IconReport.
Project file renderers (9)	upstream	yes	Same outputs, deterministic.
Feature renderers (8)	upstream	yes	Same outputs.
Interactive create command	upstream	yes	Preserved; Zod-validated; --skip-prompts honoured.
dev / build / package / sign commands	none	added	Orchestrate the upstream electrobun binary via CommandRunner; report shape + error classification.
Auto-update bundling	none	added	Surfaced via buildOptions.update → electrobun build --update argv.
Code-signing options	none	added	signCommand exposes identity / entitlements / notarization; the wrapper shapes args + classifies errors.
Error-code registry	none	added	ELECTROBUN.* namespace, eleven codes.
OTel self-telemetry	none	added	5 counters + 2 histograms.
Zod-validated options	none	added	Every public option is Zod-validated.
Subpath exports per feature	none	added	One subpath export per feature module.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/electrobun to enumerate. Net-new package on genesis — no current dependents.

• No dependents (verified by bunx turbo ls --filter=...@suaveplan/electrobun).

Risks

• iconz ESM resolution. Upstream loads iconz/presets dynamically. The genesis port keeps the dynamic-import path behind the IconRendererAdapter seam so tests can swap in a fake renderer without paying the iconz cost.
• electrobun binary availability. dev/build/package/sign shell out to the user's local electrobun binary (installed in the generated project's node_modules). The wrapper probes for it via the CommandRunner seam and raises ELECTROBUN.BINARY_UNAVAILABLE with a remediation hint when missing.
• Signing requires real certs. The sign command's test surface asserts only the argument-shape and error-classification contract; the real signing pipeline runs against the user's keychain / Apple-developer-id / Windows-PFX and is exercised by an opt-in integration scenario that probes the runner.
• Cross-platform packaging. electrobun build produces platform-specific outputs; the wrapper records the requested target triple (mac / linux / windows) in the PackageReport so CI can branch on it.