CloudsForge shared libraries

Two packages every other CloudsForge component depends on.

Package	What it is
@cloudsforge/shared	zod schemas, API contracts and domain types shared between services and clients
@cloudsforge/ui	the account bar, shared chrome and design tokens the five front-ends render

Both publish to public npm. They are the dependency floor of the platform: nine repositories consume shared, five consume ui.

Why these are built, when nothing else in CloudsForge is

Services run TypeScript directly under tsx with no build step. That works inside a workspace because pnpm symlinks packages, and tsx will transpile TS it reaches through a symlink — but it will not transpile .ts inside node_modules. As registry dependencies these packages must therefore ship real JavaScript, or every consumer crashes at import with a SyntaxError.

They still expose raw TypeScript to anything that consumes them from a workspace. publishConfig rewrites main, types and exports in the packed tarball only:

  in a workspace  ->  packages/shared/src/index.ts
  from npm        ->  dist/index.js + dist/index.d.ts

Publish with pnpm publish, never npm publish. publishConfig field rewriting is a pnpm feature; npm would publish main: src/index.ts and break every consumer.

Working on them

pnpm install
pnpm typecheck
pnpm build          # tsc --noEmit; the real build runs from prepack

To see exactly what would be published:

pnpm --filter @cloudsforge/shared pack --pack-destination /tmp
tar -tzf /tmp/cloudsforge-shared-0.1.0.tgz

Releasing

Both packages are 0.x, where a caret range means patch-only (^0.1.0 allows 0.1.x, not 0.2.0). That is the intended safety while the contracts are still moving. Bump to 1.0.0 when they settle and normal caret behaviour is wanted.

A release is: bump version, tag shared-v<x> or ui-v<x>, and let the release workflow publish. Consumers pick it up on their next install.

Compatibility

shared is the wire contract between services and clients. A breaking change here breaks running deployments, not just builds — services validate requests with these schemas. Treat a field rename as a major bump even at 0.x, and roll the server before the client.

How this was built

Parts of this repository were produced with AI assistance, and it seems worth saying so plainly rather than leaving it to be inferred.

• Code — written with Claude Opus 5 and Claude Opus 4.8 (Anthropic), reviewed and directed by a human, and gated on the same tests and CI as anything else here.
• Artwork — brand marks, icons and in-game art generated with OpenAI's image models (GPT Image 1, 1.5 and 2), driven by the manifest pipeline in asset-forge.

The models were used under paid API access and the output is the project's to use. Nothing here is claimed to be hand-written that is not, and nothing is claimed to work that has not been tested.