first commit
This commit is contained in:
151
docs/devtools/tooling/electrobun/README.md
Normal file
151
docs/devtools/tooling/electrobun/README.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user