bitz Developer Toolchain and Ecosystem Overview

In modern microkernel architectures, engineering teams frequently face the twin challenges of toolchain fragmentation and contract fragility:

1. Uncontrolled Developer Environment Admission: Access to internal commercial feeds, hardware machine code locking, and temporary leases lack an automated loop. Developers plugging and unplugging USB docks trigger MAC address drift, resulting in frequent false-positive license lockouts.
2. End-to-End Contract Drift: Frontend developers hand-write Axios calls while backend developers hand-write HttpClient code. Minor field casing or type changes cause silent runtime defects.
3. Mechanical CQRS Boilerplate: Implementing clean vertical slices requires manually creating repetitive commands, queries, DTOs, domain events, repository interfaces, and DI wiring across four separate layer projects.
4. Feed Poisoning and Configuration Chaos: Multi-source NuGet environments lacking Package Source Mapping risk mixing public packages with proprietary packages.

bitz (NuGet global tool package BitzOrcas.Cli, command bitz) is an industrial-grade developer toolchain delivered for BitzOrcas.Modern. As a foundational asset of the micro-kernel architecture, it consolidates unified identity admission, anti-drift hardware locks, OpenAPI client proxy generation, CQRS slice materialization, a visual local studio, and automated self-healing.

Real-World Multi-Step Interactive Terminal Walkthrough

The following steps are captured directly from real terminal executions on developer workstations, covering the end-to-end journey from onboarding to self-healing. Each terminal window supports instant command copying:

Step 1: Default Codeup Unified Identity Onboarding (bitz login)

Run bitz login to trigger device admission. The CLI defaults to Codeup (Alibaba Yunxiao Git Unified Identity) as its primary identity provider (IdP). A local loopback HTTP server automatically launches the default browser for enterprise OAuth2 SSO.

Simultaneously, the underlying hardware engine collects immutable physical machine attributes—bypassing virtual adapters, VPN interfaces, and common USB dock chipsets (e.g. ASIX AX88179, Realtek RTL8153)—to lock strictly onto the primary onboard physical MAC address. This generates an immutable hardware machine code (e.g. BITZ-7E2A-94DF-0C81-561A), eliminating dock-induced lockouts.

Upon handshake completion, LicenseHub issues a trusted developer security license certificate, persisted safely to ~/.bitz/bitz-dev.lic, and configures commercial credentials in user-level NuGet.Config.

Step 2: Host Credential and Hardware Lock Health Inspection (bitz status)

On any workstation, run bitz status to inspect full credential and hardware lock health.

The diagnostic report displays machine hardware traits, credential-bound machine code, 100% match status, developer email, active identity provider source (Codeup (Alibaba Yunxiao Git)), and remaining validity days:

• Soft Expire (default 30 days): Displays a yellow warning advising a refresh via bitz login, but allows local builds to continue.
• Hard Expire (default 90 days): Roslyn compiler guards enforce a fatal block on commercial packages to prevent unauthorized post-employment usage.

Step 3: Typed Client Proxy Generation (bitz generate-proxy)

Eliminate hand-written HTTP calls. Run bitz generate-proxy to parse any OpenAPI 3.0 / 3.1 specification (local JSON or remote URL).

For C# clients, it generates strongly typed DTOs, the I{Service}ApiClient interface, an HttpClient implementation with connection pooling and cancellation tokens, and an Add{Service}ApiClient DI extension. For TypeScript, it converts PascalCase models to camelCase interfaces and generates localized enum label mappings.

Step 4: CQRS Vertical Slice Code Generation (bitz generate-slice)

Developing business features no longer requires repetitive boilerplate. Run bitz generate-slice with the entity name, module, and business properties:

The CLI materializes:

• Clean domain aggregate root inheriting TenantAggregateRoot with [BitzTable] and [BitzColumn];
• Domain events (CreatedDomainEvent / UpdatedDomainEvent);
• Read-model DTOs;
• CQRS commands (Create / Update / Delete) and command handlers;
• CQRS queries (GetById / GetList) and query handlers;
• Minimal API route registration with [GenerateMcpTool] attributes for AI agent compatibility;
• Quality Ratchet: 100% complete XML documentation, zero placeholders, passes <TreatWarningsAsErrors>true</TreatWarningsAsErrors>.

Step 5: Visual Slice Modeling with Suite Studio (bitz suite)

bitz suite provides a dual-mode designer:

• Terminal TUI Mode: Interactive Spectre.Console prompts, property selection, and AST preview;
• Local Web Studio Mode (--web): Launches an embedded HttpListener on 127.0.0.1:5200 with a dark glassmorphism UI, real-time code generation preview, and atomic file disk writing.

Step 6: Deep Environment Diagnostics and Self-Healing (bitz doctor --fix)

Workstation transitions and CI environments often suffer from broken caches or missing configuration.

Run bitz doctor --fix to audit the OS architecture, .NET 10 SDK, Node.js tooling, Docker daemon, machine code stability, license expiration, and packageSourceMapping rules. If any misconfiguration or vulnerability is detected, --fix automatically applies idempotent repairs.

Interactive Terminal Experience

Experience the CLI interactively with the terminal emulator below (switch between tabs to view different workflows):

Core Command Reference

1. Installation & Updates

# Public channel (NuGet.org)
dotnet tool install -g BitzOrcas.Cli

# Commercial private feed
dotnet tool install -g BitzOrcas.Cli --add-source <commercial-feed-url>

# Self-update via fail-silent background notifier
bitz update --self
bitz update check
bitz update packages

2. Identity Admission & License Governance (bitz login / logout / status)

bitz login                                     # Default Codeup browser SSO login
bitz login --provider wecom                    # WeCom QR code login
bitz login --provider saas                     # SaaS Host account login
bitz login --device-code                       # Headless terminal device code flow
bitz login --token pat_sec_xxxx                # CI/CD pipeline token admission
bitz status                                    # Diagnostic report of hardware lock and license
bitz logout                                    # Revoke session and clean credentials

3. Solution Scaffolding (bitz new)

bitz new <ProjectName> [options]

• --preset: enterprise-saas, multi-tenant-cloud, mini-program, portal, headless-api, custom
• --orm: sqlsugar (default), efcore
• --tenancy: single, multi
• --capabilities: identity, auth, masterdata, workflow, website, risk
• --frontend: react-admin, vue-admin, astro-site, taro-mobile, none

4. Client Proxy Generation (bitz generate-proxy)

# Generate C# HttpClient SDK
bitz generate-proxy csharp \
  --spec https://api.internal/swagger/v1/swagger.json \
  --namespace BitzOrcas.Client.Billing \
  --output ./src/Clients/BillingClient

# Generate TypeScript frontend SDK
bitz generate-proxy ts \
  --spec ./swagger.json \
  --output ./frontend/src/api/billing

5. CQRS Vertical Slice Generation (bitz generate-slice)

bitz generate-slice MatterIntake \
  --module CaseManagement \
  --tenant \
  --prop "CaseNo:string,ClientName:string,ClaimAmount:decimal,IsUrgent:bool"

6. Visual Studio Workbench (bitz suite)

bitz suite is the embedded dual-mode architecture studio and review co-pilot, purpose-built to eliminate repetitive boilerplate in Clean Architecture and DDD vertical slices:

bitz suite                                      # Terminal TUI
bitz suite --web --port 5200                   # Embedded Web Studio
bitz suite --web -p 5288 --no-open              # Production/headless port binding without auto-opening browser

Key features include:

• Entity Designer & Property Grid: visually configure schema fields, invariant constraints, foreign keys, and multi-tenant flags;
• Virtual File System (VFS) Memory Review: integrated Monaco Editor for side-by-side Diff between existing disk files and projected code;
• Multi-Dialect DDL Live Preview: dual SQL Server & PostgreSQL script generation with Chinese/English comments, drag-to-reposition, and fullscreen modals;
• Cursor-Centric Smooth ER Topology Canvas: navigate relational networks with smooth mousewheel zoom and export to Retina 2x PNG, SVG, or Mermaid;
• Physical Git Timeline & Comparison Drawer: multi-dimensional commit search, expandable second-tier width drawer with 36px collapsible rails, and two-pane file diffing.

For the complete visual walkthrough and LegalTech domain guide, see: BitzOrcas Suite Studio Comprehensive Guide.

7. Diagnostics and Clean (bitz clean, bitz doctor)

bitz clean                                      # Deep recursive bin/obj/cache cleanup
bitz install-libs                               # Install frontend dependencies
bitz doctor --fix                               # Run probes and auto-heal misconfigurations

The project name is a positional argument (the first token not starting with -). --preset may be specified once; specifying a preset resets every dimension to that preset’s defaults, and later flags then override.

Dependency self-healing: selecting Authorization without Identity adds Identity automatically (a confirmable repair path in the wizard, silent in script mode).

The six scenario presets

On the capability axis, website is the public web surface (public reads, contact forms, Sitemap/SEO, visitor analytics) and risk is human verification and rule-based risk control (captcha providers, risk-factor evaluation pipeline); the portal preset ships both, while mini-program carries only risk for mini-program captchas. headless-api is deliberately slim: it pulls no Identity/Authorization platform modules, and authorization pipeline behaviors stay out of Mediator (the gateway-verification contract).

react-admin shares the product frontend stack (React 19 + Vite + Tailwind). After generation, cd frontend && npm install && npm run dev serves http://localhost:3000, with the dev proxy forwarding /api and /health to the backend.

Persistence ORM adapters

The legal --orm values are exactly the set of supported persistence adapters: sqlsugar and efcore. Anything else is rejected fail-fast (exit 2 — see the ORM adapter panel in the terminal window above); no misconfigured combination is ever generated silently. Dapper today is query-side infrastructure in the framework (BitzOrcas.Infrastructure.Dapper), not a --orm-selectable persistence adapter; FreeSql and other ORMs are not on the list. New adapters graduate through the commercial Adapter Parity gate (the same contract suite green on both adapters).

The EF Core adapter validates drift through the shared history table __BitzOrcasEfSchemaHistory: consumer contributions and the Authorization package contribution must register in one composite host (the CLI-generated composition host already does). Both adapters carry a golden gate (with BITZ_CLI_GOLDEN_BUILD=1 and a commercial feed, a real solution is generated and dotnet test runs to green).

Generated output and operational commands

The generated solution restores from the commercial feed, compiles with TreatWarningsAsErrors=true, and listens on port 5080 by default (avoiding the macOS AirPlay conflict on 5000); the api-with-job topology adds a standalone JobHost (probe on :5081, snowflake WorkerId distinct from the API). It ships with tests/{Name}.Unit.Tests (Testing-profile real-boot composition smoke) and tests/{Name}.Architecture.Tests (csproj reference-graph layering guards). The generated NuGet.Config resolves commercial packages solely from the BITZORCAS_COMMERCIAL_FEED_URL environment variable; when absent, NuGet fails hard with NU1301 and there is no silent fallback.

cd MyApp
dotnet run --project src/Hosts/MyApp.Api -- --migrate-schema plan    # preview schema SQL (plan | status | apply)
dotnet run --project src/Hosts/MyApp.Api -- --migrate-schema apply   # business + Identity + Authorization + MasterData tables
dotnet run --project src/Hosts/MyApp.Api -- --seed-only              # includes the built-in super admin seed
dotnet run --project src/Hosts/MyApp.Api                              # Now listening on :5080

• Seeding provisions the privileged super admin: tenant 1000001 / admin / Admin@2026 (a data-level fact).
• Demo accounts are created only through USER__<NAME>__PASSWORD environment variables — a fail-closed password injection contract (see the generated project README; the privileged super admin is unaffected).
• Development without RabbitMQ falls back to the in-process DevStandalone event dispatcher; production without RabbitMQ fails closed at startup.
• PiiEncryption:SearchHashKey falls back to a 32-byte zero key in development; production must configure it explicitly.

Module add/remove on existing solutions

bitz add module Billing --project ./MyApp         # append a business module (or the DevSandbox playground)
bitz remove module DevSandbox --project ./MyApp   # uninstall the sandbox with zero residue

--project defaults to the current directory and must point to a solution generated by bitz new. Add and remove mutate the same seven wiring points in lockstep: the module project, the Api project reference, the Program Mediator anchor, the schema contribution assembly anchor, the slnx module block, the Unit.Tests reference and domain tests, and the whiteboard fallback handover (the JobHost hands over in lockstep under api-with-job). Edits are deterministic and line-scoped: a missing anchor fails fast (exit 1) rather than emitting half-wired state. blank and DevSandbox are reserved names; the sandbox never participates in schema anchors.

doctor and version

bitz doctor checks the .NET 10 SDK (below 10 warns), Node.js ≥ 22 (missing is informational — it only affects frontend builds), Git, and the local offline commercial package cache (set via BITZORCAS_LOCAL_FEED, falling back to a conventional directory), and points to the BITZORCAS_COMMERCIAL_FEED_URL online restore path. It always exits 0 — the health table is for humans and is not a CI gate. bitz version prints the CLI InformationalVersion (currently 1.0.0-alpha1).

Known limitations

• The HTTP login endpoint group is pending: generated solutions ship seeding plus JWT composition but interactive login HTTP surfaces and identity provider integration remain managed by the enterprise platform host. Tracked in ledger 0014.
• The EF Core adapter is SQL Server dialect only; it cannot build PostgreSQL databases.
• The taro-mobile frontend delegates to the official scaffolder (a pinned @tarojs/cli ^4.2.1 dependency plus a single npx taro init command); the cross-platform build matrix is maintained by that scaffolder.
• Among the frontend options, react-admin, vue-admin, and astro-site are real buildable projects (npm install && npm run build verified).

See also

• BitzOrcas Suite Studio Guide — embedded visual architecture workbench and code review co-pilot
• Template and composition selection — the static 15-combination matrix (the dotnet new bitzorcas-host channel)
• Schema maintenance and seed exporter
• Upgrade CLI — managed package upgrades after generation
• Commercial GA gate
• CLI NuGet Dual-Track Distribution & Publishing Guide