refactor: prepare for release

.github/workflows/release.yml

@@ -8,8 +8,9 @@ on:
         required: true
         type: choice
         options:
-          - compact-tools-cli
-          - compact-tools-simulator
+          - compact-builder
+          - compact-cli
+          - compact-simulator
       version_bump:
         description: "Version bump type"
         required: true
@@ -46,10 +47,13 @@ jobs:
         id: pkg
         run: |
           case "${{ inputs.package }}" in
-            "compact-tools-cli")
+            "compact-builder")
+              echo "dir=builder" >> $GITHUB_OUTPUT
+              ;;
+            "compact-cli")
               echo "dir=cli" >> $GITHUB_OUTPUT
               ;;
-            "compact-tools-simulator")
+            "compact-simulator")
               echo "dir=simulator" >> $GITHUB_OUTPUT
               ;;
           esac

.gitignore

@@ -46,3 +46,5 @@ coverage
 *~
 
 *temp
+
+.claude/

README.md

@@ -1,4 +1,4 @@
-[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.26.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/minokawa-0-18-26-0)
+[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.29.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/compact-tools/badge)](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/compact-tools)
 
@@ -8,32 +8,38 @@ This project extends the Midnight Network with additional developer tooling.
 
 Tools for compiling, building, and testing Compact smart contracts. This is a monorepo containing:
 
-- `packages/cli`: CLI utilities to run the Compact compiler and builder
-- `packages/simulator`: TypeScript simulator to run and test Compact contracts locally
+- [`packages/builder`](./packages/builder) — programmatic library that drives the Compact compiler + builder
+- [`packages/cli`](./packages/cli) — thin bin wrapper around the builder library (`compact-compiler`, `compact-builder`)
+- [`packages/simulator`](./packages/simulator) — TypeScript simulator to run and test Compact contracts locally
 
-## External usage (via git submodule until npm publish)
+See each package's README for usage, options, and examples.
 
-Until packages are published to the npm registry, you can consume this repo from another project using a git submodule:
+## Installation
+
+Pick the package that matches what you need:
+
+```bash
+# Programmatic library — call the compiler/builder from TypeScript
+yarn add --dev @openzeppelin/compact-builder
+
+# CLI bins (compact-compiler, compact-builder) for use in package.json scripts
+yarn add --dev @openzeppelin/compact-cli
+
+# Simulator — test Compact contracts locally
+yarn add --dev @openzeppelin/compact-simulator
+```
+
+`compact-cli` depends transitively on `compact-builder`, so installing the CLI
+gives you both the binaries and the underlying library.
 
 ```bash
-# In your project
-git submodule add https://github.com/OpenZeppelin/compact-tools
-git submodule update --init --recursive
-
-# Install and build the tools
-yarn --cwd tools/compact-tools install
-yarn --cwd tools/compact-tools build
-
-# Use the simulator as a local dependency
-# package.json
-"devDependencies": {
-  "@openzeppelin/compact-tools-simulator": "file:./compact-tools/packages/simulator"
-}
-yarn install
-
-# Call the CLIs directly or via scripts
-node compact-tools/packages/cli/dist/runCompiler.js --help
-node compact-tools/packages/cli/dist/runBuilder.js --help
+yarn compact-compiler --help
+yarn compact-builder --help
+```
+
+```ts
+import { CompactCompiler, CompactBuilder } from '@openzeppelin/compact-builder';
+import { createSimulator } from '@openzeppelin/compact-simulator';
 ```
 
 ## Requirements
@@ -48,13 +54,13 @@ Confirm your Compact toolchain:
 ```bash
 $ compact compile --version
 
-Compactc version: 0.28.0
-0.28.0
+Compactc version: 0.29.0
+0.29.0
 ```
 
-## Getting started
+## Development
 
-Install dependencies at the repo root:
+Clone the repo and install dependencies at the root:
 
 ```bash
 nvm install
@@ -86,45 +92,6 @@ Clean generated artifacts:
 yarn clean
 ```
 
-## Packages
-
-### `@openzeppelin/compact-tools-cli` ([packages/cli](./packages/cli))
-
-CLI utilities for compiling and building Compact smart contracts.
-
-**Quickstart:**
-
-```bash
-# Compile all .compact files
-compact-compiler
-
-# Skip ZK proofs for faster development builds
-compact-compiler --skip-zk
-
-# Compile specific directory
-compact-compiler --dir security
-
-# Full build (compile + TypeScript + copy artifacts)
-compact-builder
-```
-
-See [packages/cli/README.md](./packages/cli/README.md) for full documentation including all options, programmatic API, and examples.
-
-### `@openzeppelin/compact-tools-simulator` ([packages/simulator](./packages/simulator))
-
-TypeScript simulator for testing Compact contracts locally.
-
-**Quickstart:**
-
-```ts
-import { createSimulator } from '@openzeppelin/compact-tools-simulator';
-
-const simulator = createSimulator({});
-// Deploy and execute contract circuits, inspect state, etc.
-```
-
-See package tests in `packages/simulator/src/integration` and `src/unit` for full examples.
-
 ## Contributing
 
 Before opening a PR, please read `CODE_OF_CONDUCT.md`. Use the root scripts to build, test, and format. For targeted work inside a package, run the scripts in that package directory.

RELEASING.md

@@ -1,5 +1,7 @@
 # Releasing
 
+## Running the workflow
+
 1. Go to "Release Package" in Actions.
 2. Click on the "Run workflow" dropdown menu.
 3. Choose the package to release and the version bump type.
@@ -14,4 +16,27 @@
    - Bump the version.
    - Create a git tag.
    - Publish the package to npm.
-6. Once published, go to "Releases" and create a GitHub release using the generated tag.
+6. Once published, go to "Releases" and create a GitHub release using the generated tag.
+
+## First-release order
+
+There's a one-step dependency chain across the three published packages:
+
+```text
+compact-cli (bin wrapper)
+  └─ depends on compact-builder
+compact-builder (library)
+compact-simulator (library)
+```
+
+The `workspace:^` dep is rewritten by yarn into the resolved version at
+`yarn pack` time. For the very first release, publish in dependency order so
+each dependent finds its deps already on npm:
+
+1. `compact-builder` (no internal deps)
+2. `compact-simulator` (no internal deps)
+3. `compact-cli` (depends on `compact-builder`; pull `main` first so the bump
+   commit is present locally before triggering)
+
+After the first release, the three packages version independently — bump any
+one of them in isolation without re-publishing the others.

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@openzeppelin/compact-tools",
+  "name": "compact-tools-monorepo",
   "description": "Tools for compiling, building and testing Compact smart contracts",
   "private": true,
   "packageManager": "yarn@4.10.3",

packages/builder/README.md

@@ -0,0 +1,71 @@
+# @openzeppelin/compact-builder
+
+Programmatic library for compiling and building Compact smart contracts on the
+Midnight network. Drives the `compactc` toolchain with progress reporting,
+structured error handling, and configurable output layouts.
+
+This is the **library** — it ships no CLI binaries. If you want the bins
+(`compact-compiler`, `compact-builder`) for use in `package.json` scripts,
+install [`@openzeppelin/compact-cli`](../cli) instead, which is a thin
+wrapper around this library.
+
+## Install
+
+```bash
+yarn add --dev @openzeppelin/compact-builder
+```
+
+## Quick Start
+
+```ts
+import { CompactCompiler, CompactBuilder } from '@openzeppelin/compact-builder';
+
+// Compile all .compact files in src/ to artifacts/
+await new CompactCompiler({ flags: '--skip-zk' }).compile();
+
+// Or run the full build pipeline (compile + dist assembly)
+const builder = new CompactBuilder({
+  cleanDist: true,
+  hierarchical: true,
+  exclude: ['Mock*', '*/archive/*'],
+  copyToDist: ['package.json', '../README.md'],
+});
+await builder.build();
+```
+
+## Public API
+
+```ts
+// Orchestrators
+export class CompactCompiler { /* … */ }
+export class CompactBuilder  { /* … */ }
+
+// Service classes (use for advanced custom pipelines)
+export class EnvironmentValidator { /* … */ }
+export class FileDiscovery        { /* … */ }
+export class CompilerService      { /* … */ }
+export const UIService = { /* … */ };
+
+// Option types
+export interface CompilerOptions { /* flags, targetDir, version, hierarchical, srcDir, outDir, exclude */ }
+export type BuilderOptions = CompilerOptions & {
+  cleanDist?: boolean;
+  copyToDist?: string[];
+};
+
+// Errors
+export class CompactCliNotFoundError extends Error { /* … */ }
+export class CompilationError        extends Error { /* … */ }
+export class DirectoryNotFoundError  extends Error { /* … */ }
+```
+
+## See also
+
+- [`@openzeppelin/compact-cli`](https://www.npmjs.com/package/@openzeppelin/compact-cli) — bin wrapper around this library
+- [`@openzeppelin/compact-simulator`](https://www.npmjs.com/package/@openzeppelin/compact-simulator) — TypeScript simulator for testing Compact contracts locally
+
+See the [monorepo README](https://github.com/OpenZeppelin/compact-tools#readme) for the full developer guide.
+
+## License
+
+MIT

packages/builder/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@openzeppelin/compact-builder",
+  "description": "Programmatic library for compiling and building Compact smart contracts",
+  "version": "0.0.1",
+  "keywords": [
+    "compact",
+    "midnight",
+    "compiler",
+    "builder",
+    "library"
+  ],
+  "author": "OpenZeppelin Community <maintainers@openzeppelin.org>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "types": "tsc -p tsconfig.json --noEmit",
+    "test": "yarn vitest run",
+    "clean": "git clean -fXd"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.3",
+    "@types/node": "24.10.1",
+    "@types/shell-quote": "^1.7.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "log-symbols": "^7.0.0",
+    "ora": "^9.0.0",
+    "shell-quote": "^1.8.3"
+  }
+}