Skip to content

Commit 91d823e

Browse files
0xiskandrew-fleming
0xisk
and
andrew-fleming
authored
refactor: prepare for release (#79)
* refactor: update compiler and builder as in the compact-contracts * chore: fix readme * chore: fix readme * refactor: adding changelog * feat: split the cli and the builder * chore: fix lint * refactor: types depend on the build * refactor: remove the barrel package * chore: ignore .claude/ directory * fix(builder): prevent shell injection by using execFile + shell-quote * fix: address coderabbit review (rethrow build errors, no flag dedup, unwrap CompilationError, parser-error routing) * docs: address review feedback (drop premature changelogs, slim READMEs, generalize toolchain version) - Drop pre-baseline CHANGELOGs for builder/cli/simulator and remove them from package.json file lists (no released baseline yet) - RELEASING.md: drop the changesets-migration TODO section and the CHANGELOG preamble - README.md: remove submodule-consumption section; drop busy "## Packages" walkthrough (each package has its own README); rename "Getting started" -> "Development"; linkify package list - packages/cli/README.md: split em-dash sentence per review; replace hardcoded +0.29.0 with +<version> placeholder - runCompiler.ts: generalize +<version> in help text + JSDoc; update matching test assertions - runBuilder.ts: drop confusing JSDoc @example block; point to cli README for usage examples - Set author = "OpenZeppelin Community <maintainers@openzeppelin.org>" across builder/cli/simulator package.json * chore: fix lint --------- Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com>
1 parent 98cdd16 commit 91d823e

33 files changed

Lines changed: 2034 additions & 1476 deletions

‎.github/workflows/release.yml‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,9 @@ on:
88
required: true
99
type: choice
1010
options:
11-
- compact-tools-cli
12-
- compact-tools-simulator
11+
- compact-builder
12+
- compact-cli
13+
- compact-simulator
1314
version_bump:
1415
description: "Version bump type"
1516
required: true
@@ -46,10 +47,13 @@ jobs:
4647
id: pkg
4748
run: |
4849
case "${{ inputs.package }}" in
49-
"compact-tools-cli")
50+
"compact-builder")
51+
echo "dir=builder" >> $GITHUB_OUTPUT
52+
;;
53+
"compact-cli")
5054
echo "dir=cli" >> $GITHUB_OUTPUT
5155
;;
52-
"compact-tools-simulator")
56+
"compact-simulator")
5357
echo "dir=simulator" >> $GITHUB_OUTPUT
5458
;;
5559
esac

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,5 @@ coverage
4646
*~
4747

4848
*temp
49+
50+
.claude/

‎README.md‎

Lines changed: 33 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
[![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)
1+
[![Generic badge](https://img.shields.io/badge/Compact%20Compiler-0.29.0-1abc9c.svg)](https://docs.midnight.network/relnotes/compact/)
22
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
33
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/compact-tools/badge)](https://api.securityscorecards.dev/projects/github.com/OpenZeppelin/compact-tools)
44

@@ -8,32 +8,38 @@ This project extends the Midnight Network with additional developer tooling.
88

99
Tools for compiling, building, and testing Compact smart contracts. This is a monorepo containing:
1010

11-
- `packages/cli`: CLI utilities to run the Compact compiler and builder
12-
- `packages/simulator`: TypeScript simulator to run and test Compact contracts locally
11+
- [`packages/builder`](./packages/builder) — programmatic library that drives the Compact compiler + builder
12+
- [`packages/cli`](./packages/cli) — thin bin wrapper around the builder library (`compact-compiler`, `compact-builder`)
13+
- [`packages/simulator`](./packages/simulator) — TypeScript simulator to run and test Compact contracts locally
1314

14-
## External usage (via git submodule until npm publish)
15+
See each package's README for usage, options, and examples.
1516

16-
Until packages are published to the npm registry, you can consume this repo from another project using a git submodule:
17+
## Installation
18+
19+
Pick the package that matches what you need:
20+
21+
```bash
22+
# Programmatic library — call the compiler/builder from TypeScript
23+
yarn add --dev @openzeppelin/compact-builder
24+
25+
# CLI bins (compact-compiler, compact-builder) for use in package.json scripts
26+
yarn add --dev @openzeppelin/compact-cli
27+
28+
# Simulator — test Compact contracts locally
29+
yarn add --dev @openzeppelin/compact-simulator
30+
```
31+
32+
`compact-cli` depends transitively on `compact-builder`, so installing the CLI
33+
gives you both the binaries and the underlying library.
1734

1835
```bash
19-
# In your project
20-
git submodule add https://github.com/OpenZeppelin/compact-tools
21-
git submodule update --init --recursive
22-
23-
# Install and build the tools
24-
yarn --cwd tools/compact-tools install
25-
yarn --cwd tools/compact-tools build
26-
27-
# Use the simulator as a local dependency
28-
# package.json
29-
"devDependencies": {
30-
"@openzeppelin/compact-tools-simulator": "file:./compact-tools/packages/simulator"
31-
}
32-
yarn install
33-
34-
# Call the CLIs directly or via scripts
35-
node compact-tools/packages/cli/dist/runCompiler.js --help
36-
node compact-tools/packages/cli/dist/runBuilder.js --help
36+
yarn compact-compiler --help
37+
yarn compact-builder --help
38+
```
39+
40+
```ts
41+
import { CompactCompiler, CompactBuilder } from '@openzeppelin/compact-builder';
42+
import { createSimulator } from '@openzeppelin/compact-simulator';
3743
```
3844

3945
## Requirements
@@ -48,13 +54,13 @@ Confirm your Compact toolchain:
4854
```bash
4955
$ compact compile --version
5056

51-
Compactc version: 0.28.0
52-
0.28.0
57+
Compactc version: 0.29.0
58+
0.29.0
5359
```
5460

55-
## Getting started
61+
## Development
5662

57-
Install dependencies at the repo root:
63+
Clone the repo and install dependencies at the root:
5864

5965
```bash
6066
nvm install
@@ -86,45 +92,6 @@ Clean generated artifacts:
8692
yarn clean
8793
```
8894

89-
## Packages
90-
91-
### `@openzeppelin/compact-tools-cli` ([packages/cli](./packages/cli))
92-
93-
CLI utilities for compiling and building Compact smart contracts.
94-
95-
**Quickstart:**
96-
97-
```bash
98-
# Compile all .compact files
99-
compact-compiler
100-
101-
# Skip ZK proofs for faster development builds
102-
compact-compiler --skip-zk
103-
104-
# Compile specific directory
105-
compact-compiler --dir security
106-
107-
# Full build (compile + TypeScript + copy artifacts)
108-
compact-builder
109-
```
110-
111-
See [packages/cli/README.md](./packages/cli/README.md) for full documentation including all options, programmatic API, and examples.
112-
113-
### `@openzeppelin/compact-tools-simulator` ([packages/simulator](./packages/simulator))
114-
115-
TypeScript simulator for testing Compact contracts locally.
116-
117-
**Quickstart:**
118-
119-
```ts
120-
import { createSimulator } from '@openzeppelin/compact-tools-simulator';
121-
122-
const simulator = createSimulator({});
123-
// Deploy and execute contract circuits, inspect state, etc.
124-
```
125-
126-
See package tests in `packages/simulator/src/integration` and `src/unit` for full examples.
127-
12895
## Contributing
12996

13097
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‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Releasing
22

3+
## Running the workflow
4+
35
1. Go to "Release Package" in Actions.
46
2. Click on the "Run workflow" dropdown menu.
57
3. Choose the package to release and the version bump type.
@@ -14,4 +16,27 @@
1416
- Bump the version.
1517
- Create a git tag.
1618
- Publish the package to npm.
17-
6. Once published, go to "Releases" and create a GitHub release using the generated tag.
19+
6. Once published, go to "Releases" and create a GitHub release using the generated tag.
20+
21+
## First-release order
22+
23+
There's a one-step dependency chain across the three published packages:
24+
25+
```text
26+
compact-cli (bin wrapper)
27+
└─ depends on compact-builder
28+
compact-builder (library)
29+
compact-simulator (library)
30+
```
31+
32+
The `workspace:^` dep is rewritten by yarn into the resolved version at
33+
`yarn pack` time. For the very first release, publish in dependency order so
34+
each dependent finds its deps already on npm:
35+
36+
1. `compact-builder` (no internal deps)
37+
2. `compact-simulator` (no internal deps)
38+
3. `compact-cli` (depends on `compact-builder`; pull `main` first so the bump
39+
commit is present locally before triggering)
40+
41+
After the first release, the three packages version independently — bump any
42+
one of them in isolation without re-publishing the others.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@openzeppelin/compact-tools",
2+
"name": "compact-tools-monorepo",
33
"description": "Tools for compiling, building and testing Compact smart contracts",
44
"private": true,
55
"packageManager": "yarn@4.10.3",

‎packages/builder/README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# @openzeppelin/compact-builder
2+
3+
Programmatic library for compiling and building Compact smart contracts on the
4+
Midnight network. Drives the `compactc` toolchain with progress reporting,
5+
structured error handling, and configurable output layouts.
6+
7+
This is the **library** — it ships no CLI binaries. If you want the bins
8+
(`compact-compiler`, `compact-builder`) for use in `package.json` scripts,
9+
install [`@openzeppelin/compact-cli`](../cli) instead, which is a thin
10+
wrapper around this library.
11+
12+
## Install
13+
14+
```bash
15+
yarn add --dev @openzeppelin/compact-builder
16+
```
17+
18+
## Quick Start
19+
20+
```ts
21+
import { CompactCompiler, CompactBuilder } from '@openzeppelin/compact-builder';
22+
23+
// Compile all .compact files in src/ to artifacts/
24+
await new CompactCompiler({ flags: '--skip-zk' }).compile();
25+
26+
// Or run the full build pipeline (compile + dist assembly)
27+
const builder = new CompactBuilder({
28+
cleanDist: true,
29+
hierarchical: true,
30+
exclude: ['Mock*', '*/archive/*'],
31+
copyToDist: ['package.json', '../README.md'],
32+
});
33+
await builder.build();
34+
```
35+
36+
## Public API
37+
38+
```ts
39+
// Orchestrators
40+
export class CompactCompiler { /* … */ }
41+
export class CompactBuilder { /* … */ }
42+
43+
// Service classes (use for advanced custom pipelines)
44+
export class EnvironmentValidator { /* … */ }
45+
export class FileDiscovery { /* … */ }
46+
export class CompilerService { /* … */ }
47+
export const UIService = { /* … */ };
48+
49+
// Option types
50+
export interface CompilerOptions { /* flags, targetDir, version, hierarchical, srcDir, outDir, exclude */ }
51+
export type BuilderOptions = CompilerOptions & {
52+
cleanDist?: boolean;
53+
copyToDist?: string[];
54+
};
55+
56+
// Errors
57+
export class CompactCliNotFoundError extends Error { /* … */ }
58+
export class CompilationError extends Error { /* … */ }
59+
export class DirectoryNotFoundError extends Error { /* … */ }
60+
```
61+
62+
## See also
63+
64+
- [`@openzeppelin/compact-cli`](https://www.npmjs.com/package/@openzeppelin/compact-cli) — bin wrapper around this library
65+
- [`@openzeppelin/compact-simulator`](https://www.npmjs.com/package/@openzeppelin/compact-simulator) — TypeScript simulator for testing Compact contracts locally
66+
67+
See the [monorepo README](https://github.com/OpenZeppelin/compact-tools#readme) for the full developer guide.
68+
69+
## License
70+
71+
MIT

‎packages/builder/package.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"name": "@openzeppelin/compact-builder",
3+
"description": "Programmatic library for compiling and building Compact smart contracts",
4+
"version": "0.0.1",
5+
"keywords": [
6+
"compact",
7+
"midnight",
8+
"compiler",
9+
"builder",
10+
"library"
11+
],
12+
"author": "OpenZeppelin Community <maintainers@openzeppelin.org>",
13+
"license": "MIT",
14+
"type": "module",
15+
"main": "./dist/index.js",
16+
"types": "./dist/index.d.ts",
17+
"exports": {
18+
".": {
19+
"types": "./dist/index.d.ts",
20+
"import": "./dist/index.js"
21+
}
22+
},
23+
"files": [
24+
"dist",
25+
"README.md",
26+
"LICENSE"
27+
],
28+
"engines": {
29+
"node": ">=20"
30+
},
31+
"scripts": {
32+
"build": "tsc -p .",
33+
"types": "tsc -p tsconfig.json --noEmit",
34+
"test": "yarn vitest run",
35+
"clean": "git clean -fXd"
36+
},
37+
"devDependencies": {
38+
"@tsconfig/node24": "^24.0.3",
39+
"@types/node": "24.10.1",
40+
"@types/shell-quote": "^1.7.5",
41+
"typescript": "^5.9.3",
42+
"vitest": "^4.0.15"
43+
},
44+
"dependencies": {
45+
"chalk": "^5.6.2",
46+
"log-symbols": "^7.0.0",
47+
"ora": "^9.0.0",
48+
"shell-quote": "^1.8.3"
49+
}
50+
}

0 commit comments

Comments
 (0)