tools tooling

A scaffold generator plus a conformance runner for adding a new Bellona remote-control command (task 180.C.29.14, per the header docs in tools/bellona/new-command/src/index.ts). src/spec.ts defines the input contract as a strict Zod NewCommandSpecSchema (namespace, dotted commandName, pascalName, risk class, timeout class, required permission scopes, and typed args) with superRefine cross-checks — e.g. the command name must begin with its namespace, and a read-only command may not request a mutation/destructive execute scope. src/generate.ts (generateCommandScaffold / renderCommandScaffold) renders and writes the coordinated touchpoint files only after the spec validates, while src/conformance.ts (runCommandConformance) checks a command is wired across seven touchpoints — schema-registry, fixture, policy, sdk, adapter-handler, cli-verb, docs — by exercising the real @bellona/remote-protocol registry, fixtures, and policy at runtime (notably requiring a dedicated literal *CommandName registry entry, not a broad regex match) rather than by grepping. The apps-layer touchpoints come through injected ConformanceProviders supplied by src/repo-providers.ts. Fully implemented, with a CLI in src/cli.ts and *.test.ts coverage.

A unified, drift-checking code-generation CLI (tools/codegen). src/index.ts is a thin dispatcher that spawns one of four sub-scripts: openapi-types.ts generates deterministic TypeScript types from the OpenAPI 3.1 specs in libs/openapi/src/specs into libs/openapi/src/generated using openapi-typescript (with a --check mode that fails CI on drift); proto-artifacts.ts produces a normalised Buf image JSON snapshot from libs/proto; v2-grpc-stubs.ts parses libs/proto/src and emits Unreal-facing C++ gRPC service descriptors (V2GeneratedGrpcStubs.h/.cpp) into V2/ue/Source/V2Services/Generated; and schema-artifacts.ts emits deterministic SQL snapshots from the twelve Prisma datamodels listed in its SCHEMA_PATHS. Each generator pairs a write mode with a --check verification mode, so the committed generated files are guarded against silent drift. Fully implemented (the Nx targets openapi-types, openapi-types-check, v2-grpc-stubs, and v2-grpc-stubs-check expose them).

An operator CLI application (tools/hathor-migration, type:tool, scope:hathor) that imports existing world data into the Hathor schema. The Migrator class in src/migrator.ts loads a JSON or YAML source, auto-detects its format, and parses it against the Zod schemas in src/types/legacy.ts (VeilbornWorldSchema, GenericWorldSchema, WorldAnvilExportSchema), then runs the matching transformer in src/transformers/{veilborn,generic,worldanvil}.ts to build a Hathor MigrationPlan, and executes it inside a Hathor Prisma $transaction that creates world / branch / entity / entityRelation / worldVersion rows. It supports a dry-run mode and emits MigrationResults with typed errors and warnings. Depends on @hathor/database and @prisma/client, ships a hathor-migrate bin (src/cli.ts), and has tests for the migrator and two transformers. Fully implemented.

The workspace-generators collection (sourceRoot tools/generators). generators.json registers three @nx/devkit generators: python-service (scaffolds a FastAPI service), iris-library (a TypeScript library for the Iris platform), and cybele-library (a TypeScript library for the Cybele platform). Each generator's index.ts is a real Tree generator that renders the sibling files/*.template tree via generateFiles, renames __name__ placeholders, strips the .template suffix, drops __gitkeep markers, and — in the iris-library case — also patches tsconfig.base.json path mappings and appends libs/iris/* to pnpm-workspace.yaml (updateTsConfigBase / updateWorkspaceConfig). The Nx build target compiles the generators with tsc and copies each generator's files/ template directory (and the Cybele schema.json) into dist. Fully implemented; the generators are template-driven scaffolders, so they emit real, ready-to-build project skeletons rather than finished domain code.

A CLI application (tools/v3/fallback-bake, scope:v3, type:cli) that bakes a web-renderer fallback asset bundle from a V3 cooked-asset manifest (its implicitDependency is @oshun/lilith-engine-web-fallback). src/index.ts createV3FallbackBakePlan reduces the manifest's meshes (Nanite-aware triangle decimation capped at 80 K), materials (simplified PBR with virtual-texture and parallax stripping), lightmaps, and audio (96 kbps stereo Opus) into a list of artifacts (gltf / draco / ktx2-texture / ktx2-lightmap / opus-audio / manifest), each with a byte budget, a SHA-256 integrity value, and an S3 URI; it then estimates venue load against a 30 MB budget and computes a renderer round-trip cost against a per-mode FPS budget (webgpu 60 / webgl2 30). validateV3FallbackBakePlan enforces all of those budgets, and createV3FallbackBakeFiles / writeV3FallbackBakeFiles emit a real glTF 2.0 JSON document plus the manifest. Fully implemented and tested (src/index.test.ts), deterministic, and budget-driven — note it produces the bake plan plus glTF and manifest JSON, writing the binary artifacts (Draco/KTX2/Opus) as kind:integrity:byteBudget placeholder content lines rather than performing the actual mesh/texture/audio transcode.

A CLI application (tools/model-sync, type:cli) for synchronising AI model files between an S3 bucket and a local directory (the RunPod volume mount point). src/sync.ts ModelSyncEngine uses the real @aws-sdk/client-s3 (ListObjectsV2Command / GetObjectCommand) to list and stream-download objects with a concurrency limit, computes a diff (toSync / upToDate / orphaned) by normalised key, infers model type from path or extension (checkpoint / lora / controlnet / vae / embedding / upscaler / custom, mapped to directories in MODEL_TYPE_DIRS), supports glob include/exclude filters, and can verify downloads against the S3 ETag via an MD5 checksum. src/index.ts is a Commander CLI exposing sync, diff, and list with a progress bar (ora / cli-progress / table). Fully implemented as an S3↔local sync engine; RunPodVolumeConfig is a defined type describing the target volume, but the engine itself operates on a local target directory (RunPod is the deployment context, not a separate API path here).

A collection of five standalone tsx content-pipeline scripts for the Tara meditation app (tools/tara, scope:tara, type:tools), each wired as its own Nx run-commands target rather than exported through a barrel. process-audio.ts shells out to ffmpeg/ffprobe to normalise audio to -16 LUFS and emit quality tiers; process-images.ts resizes/optimises images and generates WebP + thumbnails + a dominant colour via a dynamically-imported sharp; validate-content.ts validates meditation/course/teacher/collection/sound/lesson content against per-type REQUIRED_FIELDS and file-existence/cross-reference rules; upload-content.ts uploads processed content to S3/CDN and syncs metadata; and content-versioning.ts manages version history, rollback, A/B traffic splits, and a draft→review→live promotion workflow. These are real, domain-specific pipeline scripts invoked via npx tsx (e.g. nx run tara-tools:validate-content); there is no programmatic src/index.ts and no *.test.ts coverage in the directory.