CLI and controlled tooling

BitzOrcas Tooling has three families: generate a customer solution, generate customer-owned source scaffolding, and controlled operations/migration. None belongs in application runtime dependencies, but their risks differ sharply. Templates write a new tree and Codegen writes staging; Schema, Workflow, and Database tools can connect to real databases and need approval plus audit.

Tooling map

The repository ships exactly four distributables: the BitzOrcas.Modern.Templates template package plus three PackAsTool tools — bitz (BitzOrcas.Cli, including the embedded Suite dual-mode studio), bitz-codegen (CodeGeneration.Cli), and bitz-upgrade (Upgrade.Cli). Remaining tools are standalone net10.0 executables run from source at the matching release commit. Short names in documentation are not promises of published global tools.

Capability and risk matrix

Choose by required evidence, not by the fact that all live under src/Tooling.

bitz: the next-generation interactive scaffolder

The bitz CLI replaces the legacy bitzorcas-compose.py static 15-combination matrix with scenario presets and orthogonal dimensions (topology/tenancy/ORM/platform capabilities/business slice/sandbox/frontend). It is the recommended Consumer Solution creation channel: an interactive wizard or pure-flag script mode generates commercial-package composition hosts, SqlSugar/EF Core persistence ORM adapters, per-solution test projects, and the --migrate-schema/--seed-only operational commands, plus bitz add/remove module for mutating existing solutions. It coexists with the dotnet new bitzorcas-host matrix below with a shared contract source (the verified consumer baseline); retirement conditions are tracked in 0004-template-upgrade-map.json.

BitzOrcas Suite: Modern Dual-Mode Architecture Studio

BitzOrcas Suite is the lightweight, visual developer workbench embedded directly within the CLI (launched via bitz suite or bitz suite --web). Purpose-built to eliminate repetitive boilerplate and cognitive overhead in Clean Architecture & DDD slice development, Suite features:

• 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 comprehensive operational guidance, see the dedicated BitzOrcas Suite Studio Guide.

Consumer Solution template chapters

One switch list cannot explain the solution template. Read in order:

The generated Starter Module is consumer-owned; Framework, Workflow, and Licensing come from commercial packages. A template tree is not copied product source.

Code-generation entry

Code generator has exactly one production entry:

# Install from the local commercial feed, or dotnet run from source at the release commit.
dotnet new tool-manifest
dotnet tool install BitzOrcas.CodeGeneration.Cli \
  --version 1.0.0-alpha1 --add-source <commercial-feed>

dotnet bitz-codegen --business-slice ./design/matter-intakes.v1.json \
  --output .codegen-output

The production entry accepts only a strictly validated slice schema (industry-neutral unified aggregate plus one Create command); the legacy --inline/--module/--use-case flags are fail-closed audit entries — zero C#, a diagnostic manifest, exit code 2. Manually wire slnx membership, invariants, authorization resource, tenant/data scope, and real test fixtures afterwards.

Schema and Seed responsibilities

Schema Maintenance compares compiled metadata with SQL Server schema and can validate CSV length offline. Seed Exporter creates owner-local CSV from an approved legacy snapshot.

Seed length validation is not idempotency/dependency/sensitive-data proof; clean schema drift does not prove seed correctness. The chains meet before release but evidence is not interchangeable.

Workflow definition migration

Workflow Migrator moves definitions only. source selects the BitzOrcas five-table set or Saury T_WorkflowDefinition*; when omitted, the tool probes the source catalog. Saury also writes a sidecar report for IBusinessIntegrationCallback. Unknown nodes, untranslated conditions, and missing assignees are warnings only, so every flow needs dry-run review.

Kebab-case command-line switches overlay the bound Migrator section and win over JSON and MIGRATOR_ environment values. Connection strings should still live in gitignored appsettings.local.json.

BitzSaury migration search

BitzSaury migration MCP provides three stdio servers and twelve read-only tools. Environment variables connect them to BitzOrcasVNext, Saury/BitzOrcas legacy repositories, and the migration knowledge base. They establish contract and legacy-behavior evidence before migration; they do not transform code or write a database.

Database Maintenance

Database Maintenance calls SQL Server BACKUP/RESTORE directly and can SELECT * one table. Backup path must be visible to SQL Server and CLI; Restore uses WITH REPLACE with no dry run; Export has no tenant filter or field masking.

Rehearse in isolated restore environments. Passing RESTORE VERIFYONLY is not GA disaster-recovery evidence; real restore, application smoke, RTO/RPO, and chain reconciliation are required.

Common safety workflow

Every tool records source commit, SDK, cwd, configuration source, input snapshot, target identity, command, exit, duration, and omitted risk. A final “success” line is not auditable evidence.

Secrets and logs

• Inject connections from a secret store into gitignored local settings or short-lived environment.
• Never put password/license in PR, shell history, or echoed CI command.
• Password/Pwd masking does not guarantee safe stack traces or driver logs.
• Workflow JSON, Seed CSV, table exports, and backups may contain PII/secrets.
• Temporary directories need least privilege, encryption, expiry, and failed-artifact quarantine.

Working-directory semantics

Executables use Directory.GetCurrentDirectory() for appsettings and relative paths. Running at repository root versus inside a project may load different local configuration/output. Fix cwd in runbooks or use absolute paths.

# Capture execution context before any controlled operation.
pwd
git rev-parse HEAD
dotnet --info | sed -n '1,36p'

# Inspect real Tooling packability and output types.
rg -n '<OutputType>|<IsPackable>|<TargetFramework>' \
  src/Tooling --glob '*.csproj'

Exit codes are not one protocol

Schema, Workflow, and Database tools broadly use 0/1/2/3/99, but code 2 means different business results; Seed Exporter and Codegen have no identical catalog. Automation interprets tool plus mode, never global exit 2 = drift.

Notably, Database Log backup may skip under SIMPLE with code 0; Workflow code 0 may contain warnings; Schema check code 2 is expected drift evidence.

Completion gate

• Tool commit matches target version.
• Documentation does not overstate packability/installability.
• Input snapshot, target database/tenant/path are explicit and double-checked.
• Read-only/preview/dry-run evidence precedes writes.
• Privileged backup/restore identity is separate from export read-only identity.
• Partial success, cancellation, and rerun are in the runbook.
• Generated artifacts pass PII/secret and ownership review.
• Technical validation and business smoke both pass.
• Missing capabilities and manual compensation are explicit.
• Temporary output, local settings, and run logs stay out of Git.

See also

• Testing strategy
• Production configuration
• Disaster recovery
• Commercial GA gate

Chapter Navigation

• 15
  01/14

  bitz Developer Toolchain and Ecosystem Overview

  In-depth guide to the modernized Bitz CLI toolchain: Codeup default unified identity onboarding, anti-drift physical hardware locking, typed client proxies, CQRS vertical slice code generation, visual Suite studio, and automated environment self-healing.

  Read
• 15
  02/14

  BitzOrcas Suite Visual Architecture Studio

  In-depth guide to BitzOrcas Suite (bitz suite) visual workbench: from entity modeling and property grids, in-memory VFS slice diff review, to multi-dialect DDL preview, ER topology export, Git timeline, and double-column diff drawers.

  Read
• 15
  03/14

  Code generator

  Generate industry-neutral unified-aggregate slices through bitz-codegen's business-slice production entry, with atomic placement, the BOCG error-code families, manifest evidence fields, and fail-closed legacy audit inputs.

  Read
• 15
  04/14

  Solution Template and Profile Selection

  Understand the 15 coupled bitzorcas-host Profiles, two ORMs, three base topologies, optional Platform modules, and industry extensions.

  Read
• 15
  05/14

  Create and Run a Consumer Solution

  Use default-business-multi to install the template, generate a project, verify composition, restore commercial packages, run Aspire, and accept the starter slice.

  Read
• 15
  06/14

  Seed data exporter

  Extract fourteen baseline-data categories from approved legacy staging, normalize ownership and business keys, and safely review caret-delimited CSV output.

  Read
• 15
  07/14

  Generated Output, Profiles, and Composition Evidence

  Examine native Consumer Solution output, Host composition, Business Starter, commercial package closure, manifests, plans, and ownership boundaries.

  Read
• 15
  08/14

  Workflow Migrator

  Convert legacy workflow definitions from bitzorcas or saury into the new JSON DSL, write sidecar reports, and Deploy plus Publish on an isolated target.

  Read
• 15
  09/14

  Schema Maintenance

  Detect drift between declared metadata and SQL Server schema, generate or apply safety-tiered migrations, and validate owner-local Seed CSV offline.

  Read
• 15
  10/14

  Template Parameters and Profile Constraints

  Public options, defaults, 15 Profiles, internal derivation, output selection, and verification boundaries for bitzorcas-host 1.0.0-alpha1.

  Read
• 15
  11/14

  Database Maintenance

  Use the standalone SqlSugar/SQL Server operations tool for full, differential, and log backup, VERIFYONLY, guarded restore, and streaming table export.

  Read
• 15
  12/14

  Solution Template Troubleshooting

  Diagnose bitzorcas-host by installation, generation, Feed, restore, build, schema, topology, Platform module, and License stage.

  Read
• 15
  13/14

  Upgrade CLI (bitz-upgrade)

  Plan, apply, and roll back managed BitzOrcas package version upgrades with the bitz-upgrade dotnet tool — Directory.Packages.props only, fail-closed on irreversible steps.

  Read
• 15
  14/14

  BitzSaury migration MCP servers

  Build and configure three BitzSaury migration MCP servers for foundation contracts, legacy code, and migration PRDs.

  Read