---
title: "Development"
description: "How the Nuabase source is organized, and how to build, test, and release it."
canonical: "https://nuabase.com/docs/development/"
---

> Documentation index: https://nuabase.com/llms.txt

How the Nuabase source is organized, and how to build, test, and release it.

## Repository layout

The `nuabase/nua-llm` repository is a pnpm workspace containing two packages:

- **`nua-client` (published as `nuabase`):** The public TypeScript SDK with Zod integration.
- **`nua-llm-core` (private, bundled into `nuabase`):** The underlying execution engine. It has no build of its own: its package exports point at its TypeScript source, which `nua-client` type-checks, tests, and bundles directly. Internally:
  1. The client's **engine router** resolves the requested model or alias (via the CLI's alias table for local agents, or the provider alias table for HTTP APIs).
  2. `runCast` checks whether the selected engine supports native schema enforcement, formats the prompt accordingly, executes the attempt, parses the output with the caller's Zod schema, and triggers retries when needed.
  3. Each engine attempt executes a single CLI process or a single HTTP request.

See [How It Works](/docs/how-it-works.md) for what each of these steps does from the caller's side.

## Running builds and tests

```bash
pnpm install
pnpm --filter nuabase build                # bundle nuabase, with nua-llm-core inlined
pnpm --filter nua-llm-core test            # fast unit tests (mocked providers, no keys needed)
mise exec -- pnpm --filter nuabase test    # real integration tests
```

- `nua-llm-core` includes both mocked unit tests and live integration tests (`pnpm test:integration`, which automatically skips providers without keys).
- `nuabase` tests are full end-to-end integration tests with no stubs. They run once against an HTTP provider (the first key found, unless `SKIP_DIRECT_TESTS` is set) and once for each local agent listed in `NUA_LOCAL_AGENTS` (`claude-code`, `codex`, `auto`).
- API keys and `NUA_LOCAL_AGENTS` are loaded from an uncommitted `mise.toml` at the repo root via `mise exec --`.

## Contributor guidelines

- **Keep the main entry point edge-compatible:** Neither package's main entry point may import `node:` built-in modules. Node built-ins are only permitted inside `nuabase/local-agent` (enforced by automated tests).
- **No build step for `nua-llm-core`:** A change to it is in `nuabase`'s next type check, test run, and bundle without rebuilding anything.
- **Pinned prompt templates:** In-prompt schema instructions are pinned by tests; update them only intentionally.

## Releases

Record version bumps with `pnpm changeset`, apply them with `pnpm release:version`, and run the release train (which commits, publishes via `pnpm release:publish`, and pushes). Check pending changesets anytime with `pnpm release:status`.