← Back to all projects
⌨️

Open source · vishwajit-vm Designed · Phase 1

Strutvane CLI & starter

npm create strutvane@latest, the sv CLI and the devkit SDK

The developer-experience layer of Strutvane, across three repositories: create-strutvane scaffolds a new project, the sv CLI runs everyday work (generators, migrations, packages, upgrades), and the devkit SDK powers every installer and generator with staged, transactional file writes — so a failed command never leaves your project half-changed.

3 repositories~14 generators3-way merge · 47 tests

Built for: Every Strutvane developer — and package and plugin authors building installers.

Packages on npm

↓ Scroll to explore the problem, architecture and stack

😩

The problem

Scaffolding tools generate a project once and then abandon you: adding a package means editing configs by hand, generators clobber your changes, and upgrading means re-applying weeks of edits.

💡

Why it matters

Every Strutvane command previews its changes, applies them as one transaction, and upgrades ejected code with a three-way merge — so automation never costs you your own edits.

What you can do with it

01Create a project with presets (full, api, ui) and choices for database, auth methods, tenancy and package manager.
02Add or remove packages with sv add / sv remove; installers write config, env vars, migrations and routes.
03Generate models, resources and more with about 14 make:* generators — each with --dry-run --diff.
04Run migrations, seeds, db:pull, routes, permissions, doctor (including a row-level-security audit) and env:check.
05Start local Postgres, Valkey and Mailpit with sv up.
06Eject code and upgrade safely with a three-way merge; script everything with --json and defined exit codes.

How it’s built

A simplified view of the architecture — follow the dots as a request moves down the layers.

You
npm create strutvanecreate-strutvane
sv …global launcher
CLI
@strutvane/cliproject-local
SDK
devkitstaged writes · env · AST · merge
Packages
Package installersframework · auth · ui · logs

A request, step by step

  1. The global strutvane launcher walks up from the current folder to find node_modules/@strutvane/cli.
  2. It hands off to that project-local CLI, so the CLI version always matches the project.
  3. The CLI loads the installed packages’ installers and commands.
  4. Commands run through devkit: every file change is staged, previewable and committed as one transaction.
  5. When a second package is installed, its installer “enhances” the first, so install order never matters.

Tech stack

Runtime
Node.jsTypeScript
Tooling
pnpmtsdownBiomeVitest
Codegen
magicastts-morphthree-way merge
Platform
DockerGitHub Actions

What I built

  • Designed the CLI command set, exit codes and the global-launcher → local-CLI delegation that keeps the CLI version in step with each project.
  • Proved the upgrade merge in spike 06 (47 tests, 8,000 property cases): merging runs on normalised keys with line endings, BOM and final newline merged three-way, sha256-verified base copies, and a journaled apply (ADR-0012).
  • Designed devkit: defineInstaller (idempotent, reversible, previewable), defineGenerator, a staged transactional file system, an env editor that keeps .env and .env.example in sync, and an AST config patcher.
  • Designed create-strutvane’s templates to be tested by generate → typecheck → lint → test on Windows, macOS and Linux; the Phase 1 gate is an external developer building a 5-model API from the tutorial in under 30 minutes.

Hard problems & how I solved them

❓ Upgrades that never lose your edits.

✅ Raw diff3 turned CRLF files into whole-file conflicts, so merging works on normalised content with line endings merged separately, verified base copies and a journaled apply (ADR-0012).

❓ A failed command must not break the project.

✅ devkit stages every write and commits them together; it is git-aware and warns on a dirty working tree.