Development

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 for what each of these steps does from the caller’s side.

Running builds and tests

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.