152 lines
8.0 KiB
Markdown
152 lines
8.0 KiB
Markdown
# @suaveplan/electrobun - Electrobun desktop-app generator + orchestrator: scaffolds projects, generates icons, drives dev/build/package/sign commands via an injectable runner. Typed ELECTROBUN_CODES, Zod-validated options, OTel self-telemetry.
|
||
|
||
Electrobun desktop-app generator and orchestrator for the SuavePlan
|
||
ecosystem. Scaffolds a fresh Electrobun project from a layered config +
|
||
prompt flow, drives the upstream `electrobun` binary for dev / build /
|
||
package / sign, and emits structured reports + OpenTelemetry metrics for
|
||
every operation.
|
||
|
||
<!-- begin:auto-docs -->
|
||
## Documentation tree
|
||
|
||
- [bin](./src/bin/suaveplan-electrobun.md) — Single-file binary that wires `process.argv` into the pure `runCli` dispatcher and translates the resolved exit code in…
|
||
- [suaveplan-electrobun](./src/bin/suaveplan-electrobun.md) — Single-file binary that wires `process.argv` into the pure `runCli` dispatcher and translates the resolved exit code in…
|
||
- [cli](./src/cli/cli.md) — Owns the five command surfaces — `createCommand`, `devCommand`, `buildCommand`, `packageCommand`, `signCommand` — plus…
|
||
- [cli](./src/cli/cli.md) — Owns the five command surfaces — `createCommand`, `devCommand`, `buildCommand`, `packageCommand`, `signCommand` — plus…
|
||
- [config](./src/config/config.md) — `loadConfig(cliArgs, deps?)` builds an `ElectrobunConfig` by layering hard-coded defaults, an optional on-disk `.suavep…
|
||
- [config](./src/config/config.md) — `loadConfig(cliArgs, deps?)` builds an `ElectrobunConfig` by layering hard-coded defaults, an optional on-disk `.suavep…
|
||
- [error-codes](./src/error-codes/error-codes.md) — Owns the stable `ELECTROBUN.*` error-code namespace and the `ElectrobunError` class that every public entry point throw…
|
||
- [error-codes](./src/error-codes/error-codes.md) — Owns the stable `ELECTROBUN.*` error-code namespace and the `ElectrobunError` class that every public entry point throw…
|
||
- [fs](./src/fs/fs.md) — Owns the `FsAdapter` seam and the synchronous `ConfigDiscoveryAdapter` used by the layered-config loader. Every IO-touc…
|
||
- [fs](./src/fs/fs.md) — Owns the `FsAdapter` seam and the synchronous `ConfigDiscoveryAdapter` used by the layered-config loader. Every IO-touc…
|
||
- [generator](./src/generator/generator.md) — Owns the two-call surface that scaffolds an Electrobun project on disk. `collectFiles(options, overrides?)` is pure — i…
|
||
- [generator](./src/generator/generator.md) — Owns the two-call surface that scaffolds an Electrobun project on disk. `collectFiles(options, overrides?)` is pure — i…
|
||
- [icons](./src/icons/icons.md) — Wraps the upstream `iconz` library behind an `IconRendererAdapter` seam so the generator can run the icon-generation pi…
|
||
- [icons](./src/icons/icons.md) — Wraps the upstream `iconz` library behind an `IconRendererAdapter` seam so the generator can run the icon-generation pi…
|
||
- [prompts](./src/prompts/prompts.md) — Owns the interactive scaffolder that backs the CLI's `create` command. `runPrompts(config, outputDir, prompter)` walks…
|
||
- [prompts](./src/prompts/prompts.md) — Owns the interactive scaffolder that backs the CLI's `create` command. `runPrompts(config, outputDir, prompter)` walks…
|
||
- [runner](./src/runner/runner.md) — Owns the `CommandRunner` seam that every electrobun shell-out flows through, plus the `probeElectrobun` and `invokeElec…
|
||
- [runner](./src/runner/runner.md) — Owns the `CommandRunner` seam that every electrobun shell-out flows through, plus the `probeElectrobun` and `invokeElec…
|
||
- [schemas](./src/schemas/schemas.md) — Owns the Zod schemas that gate every public boundary of `@suaveplan/electrobun`. Each interface in `src/types/electrobu…
|
||
- [schemas](./src/schemas/schemas.md) — Owns the Zod schemas that gate every public boundary of `@suaveplan/electrobun`. Each interface in `src/types/electrobu…
|
||
- [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry surface for `@suaveplan/electrobun`. Every public entry point that does observable work (project…
|
||
- [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry surface for `@suaveplan/electrobun`. Every public entry point that does observable work (project…
|
||
- [templates](./src/templates/templates.md) — Owns every renderer that produces a project-level file in the scaffolded output: `electrobun.config.ts`, `package.json`…
|
||
- [features](./src/templates/features.md) — Owns every renderer that produces a per-feature file in the scaffolded output: `i18n`, `networking` (basic + full), `ap…
|
||
- [templates](./src/templates/templates.md) — Owns every renderer that produces a project-level file in the scaffolded output: `electrobun.config.ts`, `package.json`…
|
||
<!-- end:auto-docs -->
|
||
|
||
## Features
|
||
|
||
- **Five-command CLI**: `create`, `dev`, `build`, `package`, `sign`.
|
||
- **Layered config**: defaults + `.suaveplan-electrobun.json` + CLI args
|
||
via `@suaveplan/config`.
|
||
- **Injectable seams**: `FsAdapter`, `CommandRunner`,
|
||
`IconRendererAdapter`, `Prompter` — every IO path is testable without
|
||
`vi.mock`.
|
||
- **Zod-validated options** at every public boundary; bad input fails as
|
||
`ELECTROBUN.INVALID_OPTIONS`.
|
||
- **Eleven typed error codes** under the `ELECTROBUN.*` namespace.
|
||
- **OpenTelemetry**: five counters + two histograms on the
|
||
`@suaveplan/electrobun` meter.
|
||
- **iconz integration** for `.icns` / `.ico` / `.png` icon generation.
|
||
- **Auto-update bundling** via the `--update` flag on `build`.
|
||
- **Code-signing pipeline** via `sign --identity --entitlements
|
||
--notarize` (the wrapper shapes argv; signing certificates remain in
|
||
the user's keychain).
|
||
- **Eight feature renderers** (`i18n`, `networking` × basic/full, `api`,
|
||
`api-schemas`, `storage`, `auth`, `form-builder`, `r3f` with five
|
||
modules).
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
bun add @suaveplan/electrobun
|
||
```
|
||
|
||
The package ships a `suaveplan-electrobun` binary:
|
||
|
||
```bash
|
||
suaveplan-electrobun --help
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Scaffold a new project
|
||
|
||
```bash
|
||
suaveplan-electrobun create my-app --skip-prompts \
|
||
--name my-app --id com.example.my-app --icon ./assets/icon.png
|
||
```
|
||
|
||
### Interactive scaffold
|
||
|
||
```bash
|
||
suaveplan-electrobun create ./my-app
|
||
```
|
||
|
||
### Dev / build / package / sign
|
||
|
||
```bash
|
||
suaveplan-electrobun dev --cwd ./my-app
|
||
suaveplan-electrobun build --cwd ./my-app --target mac --update
|
||
suaveplan-electrobun package --cwd ./my-app --target mac
|
||
suaveplan-electrobun sign --cwd ./my-app \
|
||
--identity "Developer ID Application: ..." \
|
||
--entitlements ./entitlements.plist --notarize
|
||
```
|
||
|
||
### Programmatic use
|
||
|
||
```ts
|
||
import {
|
||
buildCommand,
|
||
createCommand,
|
||
generate,
|
||
runCli,
|
||
} from "@suaveplan/electrobun";
|
||
|
||
const report = await generate({
|
||
name: "my-app",
|
||
identifier: "com.example.my-app",
|
||
description: "A demo",
|
||
version: "0.1.0",
|
||
outputDir: "./my-app",
|
||
features: ["i18n", "api"],
|
||
networkingComplexity: "basic",
|
||
r3fModules: [],
|
||
});
|
||
```
|
||
|
||
## Subpath exports
|
||
|
||
| Subpath | Surface |
|
||
|---|---|
|
||
| `@suaveplan/electrobun` | Full barrel |
|
||
| `@suaveplan/electrobun/cli` | Five command functions + `runCli` |
|
||
| `@suaveplan/electrobun/config` | `loadConfig`, defaults |
|
||
| `@suaveplan/electrobun/error-codes` | `ELECTROBUN_CODES`, `ElectrobunError` |
|
||
| `@suaveplan/electrobun/fs` | `FsAdapter`, `nodeFsAdapter`, file helpers |
|
||
| `@suaveplan/electrobun/generator` | `collectFiles`, `generate` |
|
||
| `@suaveplan/electrobun/icons` | `generateIcons`, `iconzRendererAdapter` |
|
||
| `@suaveplan/electrobun/prompts` | `runPrompts` |
|
||
| `@suaveplan/electrobun/runner` | `CommandRunner`, `probeElectrobun`, `invokeElectrobun` |
|
||
| `@suaveplan/electrobun/schemas` | Zod schemas + `parseOrThrow` |
|
||
| `@suaveplan/electrobun/telemetry` | OTel counters + histograms |
|
||
| `@suaveplan/electrobun/templates` | Project + feature renderers |
|
||
| `@suaveplan/electrobun/types` | Shared types + `FEATURE_ORDER` |
|
||
|
||
## Error codes
|
||
|
||
The full `ELECTROBUN.*` registry:
|
||
|
||
`INVALID_OPTIONS`, `OUTPUT_NOT_EMPTY`, `CONFIG_PARSE_FAILED`,
|
||
`ICON_SOURCE_MISSING`, `ICON_RENDER_FAILED`, `TEMPLATE_RENDER_FAILED`,
|
||
`FS_WRITE_FAILED`, `BINARY_UNAVAILABLE`, `RUNNER_FAILED`,
|
||
`PROMPT_ABORTED`, `UNKNOWN_FLAG`.
|
||
|
||
## License
|
||
|
||
MIT — see the repository root.
|
||
|