# Tools — Systems Deep Dive

> The `tools/` area: seven tracked Nx projects that are the monorepo's developer
> and build-time machinery — code generators, scaffold generators, drift
> checkers, content pipelines, and asset/model sync CLIs — rather than runtime
> domain services.

## What this area is

Everything under `tools/` is build-time or operator-time tooling: code that a
developer, a generator, or a CI job runs to produce, validate, or move other
artifacts. None of these projects is a long-running runtime service. They divide
into a few recognisable families:

- **Generators** that emit new code from templates — `@oshun/tools`
  (`tools/generators`) is a collection of Nx workspace generators, and
  `@bellona/new-command` (`tools/bellona/new-command`) scaffolds a coordinated
  set of touchpoints for a new remote-control command.
- **Code-generation / drift checkers** — `@oshun/codegen` (`tools/codegen`)
  turns canonical sources (OpenAPI specs, `.proto` files, Prisma datamodels)
  into deterministic generated artifacts and verifies they have not drifted.
- **Content & asset pipelines** — `tara-tools` (`tools/tara`) processes,
  validates, uploads, and versions meditation content for the Tara app;
  `@oshun/v3-fallback-bake` (`tools/v3/fallback-bake`) bakes a web-renderer
  fallback bundle from a V3 cooked-asset manifest.
- **Data / model movers** — `@oshun/hathor-migration` (`tools/hathor-migration`)
  imports legacy world data into the Hathor schema, and `model-sync`
  (`tools/model-sync`) synchronises AI model files between S3 and a local/RunPod
  volume.

These projects are largely independent of one another — they do not form a
single dependency chain. What unites them is the `scope:tools` (or a
domain-plus-tools) tag and the fact that each is wired through Nx
`run-commands`/`@nx/js:tsc` targets and invoked via `nx run <project>:<target>`
or directly through `tsx`. Most depend downward on a domain library
(`@bellona/remote-protocol`, `@hathor/database`,
`@oshun/lilith-engine-web-fallback`) or on third-party SDKs
(`@aws-sdk/client-s3`, `@nx/devkit`, `openapi-typescript`), never on each other.

## How it fits the wider system

Consumers are developers and CI, not end users. `@oshun/codegen` is the
canonical generator for the OpenAPI TypeScript types in
`libs/openapi/src/generated`, the Buf image snapshot under `libs/proto`, the
Prisma SQL snapshots, and the Unreal-facing C++ gRPC stubs in
`V2/ue/Source/V2Services/Generated`; its `--check` modes are the drift gates
those artifacts pass through in CI. `@oshun/tools` and `@bellona/new-command`
are run by hand when someone adds a new library, service, or command.
`tara-tools` and `@oshun/v3-fallback-bake` are content/asset build steps that
feed the Tara app and the V3 web renderer respectively.
`@oshun/hathor-migration` and `model-sync` are operator CLIs run against live
data stores (a Hathor database, an S3 bucket). The boundary is clean: tools read
canonical sources and write generated or migrated artifacts, and the runtime
domains consume those artifacts — the tools themselves are not imported by any
service at runtime.

## Entity reference

### @bellona/new-command

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.

### @oshun/codegen

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).

### @oshun/tools

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.

### @oshun/hathor-migration

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 `MigrationResult`s 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.

### model-sync

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).

### tara-tools

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.

### @oshun/v3-fallback-bake

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.