refactor(cli): introduce cli options including --hierarchical flag

README.md

@@ -86,64 +86,47 @@ yarn clean
 
 ## Packages
 
-### `@openzeppelin/compact-tools-cli` (packages/cli)
+### `@openzeppelin/compact-tools-cli` ([packages/cli](./packages/cli))
 
-Utilities and CLIs around the Compact compiler and builder.
+CLI utilities for compiling and building Compact smart contracts.
 
-- Binaries provided:
-  - `compact-compiler` → `packages/cli/dist/runCompiler.js`
-  - `compact-builder` → `packages/cli/dist/runBuilder.js`
-
-Useful commands:
+**Quickstart:**
 
 ```bash
-# From repo root (via Turbo filters)
-yarn compact
-
-# Or inside the package
-cd packages/cli
-yarn build           # compile TypeScript
-yarn test            # run unit tests
-yarn types           # type-check only
-```
+# Compile all .compact files
+compact-compiler
 
-After building, you can invoke the CLIs directly, for example:
+# Skip ZK proofs for faster development builds
+compact-compiler --skip-zk
 
-```bash
-node dist/runCompiler.js --help
-node dist/runBuilder.js --help
-```
+# Compile specific directory
+compact-compiler --dir security
 
-### `@openzeppelin/compact-tools-simulator` (packages/simulator)
+# Full build (compile + TypeScript + copy artifacts)
+compact-builder
+```
 
-A local simulator to execute Compact contracts in tests.
+See [packages/cli/README.md](./packages/cli/README.md) for full documentation including all options, programmatic API, and examples.
 
-Build and test:
+### `@openzeppelin/compact-tools-simulator` ([packages/simulator](./packages/simulator))
 
-```bash
-cd packages/simulator
-yarn build
-yarn test
-```
+TypeScript simulator for testing Compact contracts locally.
 
-Minimal usage example:
+**Quickstart:**
 
 ```ts
 import { createSimulator } from '@openzeppelin/compact-tools-simulator';
 
-// Create a simulator instance (see package docs and tests for full examples)
 const simulator = createSimulator({});
-
-// Use simulator to deploy/execute contract circuits, inspect state, etc.
-// (Refer to `packages/simulator/src/integration` and `src/unit` tests.)
+// 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.
 
 ## License
 
 MIT
-
-

packages/cli/README.md

@@ -0,0 +1,250 @@
+# @openzeppelin/compact-tools-cli
+
+CLI utilities for compiling and building Compact smart contracts.
+
+## Installation
+
+Until published to npm, use via git submodule or local path:
+
+```bash
+# As a local dependency
+yarn add @openzeppelin/compact-tools-cli@file:./compact-tools/packages/cli
+
+# Or invoke directly after building
+node compact-tools/packages/cli/dist/runCompiler.js
+```
+
+## Requirements
+
+- Node.js >= 20
+- Midnight Compact toolchain installed and available in `PATH`
+
+Verify your Compact installation:
+
+```bash
+$ compact compile --version
+Compactc version: 0.26.0
+```
+
+## Binaries
+
+This package provides two CLI binaries:
+
+| Binary | Script | Description |
+|--------|--------|-------------|
+| `compact-compiler` | `dist/runCompiler.js` | Compile `.compact` files to artifacts |
+| `compact-builder` | `dist/runBuilder.js` | Compile + build TypeScript + copy artifacts |
+
+## Compiler CLI
+
+### Usage
+
+```bash
+compact-compiler [options]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--dir <directory>` | Compile specific subdirectory within src | (all) |
+| `--src <directory>` | Source directory containing `.compact` files | `src` |
+| `--out <directory>` | Output directory for compiled artifacts | `artifacts` |
+| `--hierarchical` | Preserve source directory structure in output | `false` |
+| `--skip-zk` | Skip zero-knowledge proof generation | `false` |
+| `+<version>` | Use specific toolchain version (e.g., `+0.26.0`) | (default) |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SKIP_ZK=true` | Equivalent to `--skip-zk` flag |
+
+### Artifact Output Structure
+
+**Default (flattened):** All contract artifacts go directly under the output directory.
+
+```
+src/
+  access/
+    AccessControl.compact
+  token/
+    Token.compact
+
+artifacts/           # Flattened output
+  AccessControl/
+  Token/
+```
+
+**Hierarchical (`--hierarchical`):** Preserves source directory structure.
+
+```
+artifacts/           # Hierarchical output
+  access/
+    AccessControl/
+  token/
+    Token/
+```
+
+### Examples
+
+```bash
+# Compile all contracts (flattened output)
+compact-compiler
+
+# Compile with hierarchical artifact structure
+compact-compiler --hierarchical
+
+# Compile specific directory only
+compact-compiler --dir security
+
+# Skip ZK proof generation (faster, for development)
+compact-compiler --skip-zk
+
+# Use specific toolchain version
+compact-compiler +0.26.0
+
+# Custom source and output directories
+compact-compiler --src contracts --out build
+
+# Combine options
+compact-compiler --dir access --skip-zk --hierarchical
+
+# Use environment variable
+SKIP_ZK=true compact-compiler
+```
+
+## Builder CLI
+
+The builder runs the compiler as a prerequisite, then executes additional build steps:
+
+1. Compile `.compact` files (via `compact-compiler`)
+2. Compile TypeScript (`tsc --project tsconfig.build.json`)
+3. Copy artifacts to `dist/artifacts/`
+4. Copy and clean `.compact` files to `dist/`
+
+### Usage
+
+```bash
+compact-builder [options]
+```
+
+Accepts all compiler options except `--skip-zk` (builds always include ZK proofs).
+
+### Examples
+
+```bash
+# Full build
+compact-builder
+
+# Build specific directory
+compact-builder --dir token
+
+# Build with custom directories
+compact-builder --src contracts --out build
+```
+
+## Programmatic API
+
+The compiler can be used programmatically:
+
+```typescript
+import { CompactCompiler } from '@openzeppelin/compact-tools-cli';
+
+// Using options object
+const compiler = new CompactCompiler({
+  flags: '--skip-zk',
+  targetDir: 'security',
+  version: '0.26.0',
+  hierarchical: true,
+  srcDir: 'src',
+  outDir: 'artifacts',
+});
+
+await compiler.compile();
+
+// Using factory method (parses CLI-style args)
+const compiler = CompactCompiler.fromArgs([
+  '--dir', 'security',
+  '--skip-zk',
+  '+0.26.0'
+]);
+
+await compiler.compile();
+```
+
+### Classes and Types
+
+```typescript
+// Main compiler class
+class CompactCompiler {
+  constructor(options?: CompilerOptions, execFn?: ExecFunction);
+  static fromArgs(args: string[], env?: NodeJS.ProcessEnv): CompactCompiler;
+  static parseArgs(args: string[], env?: NodeJS.ProcessEnv): CompilerOptions;
+  compile(): Promise<void>;
+  validateEnvironment(): Promise<void>;
+}
+
+// Builder class
+class CompactBuilder {
+  constructor(options?: CompilerOptions);
+  static fromArgs(args: string[], env?: NodeJS.ProcessEnv): CompactBuilder;
+  build(): Promise<void>;
+}
+
+// Options interface
+interface CompilerOptions {
+  flags?: string;           // Compiler flags (e.g., '--skip-zk --verbose')
+  targetDir?: string;       // Subdirectory within srcDir to compile
+  version?: string;         // Toolchain version (e.g., '0.26.0')
+  hierarchical?: boolean;   // Preserve directory structure in output
+  srcDir?: string;          // Source directory (default: 'src')
+  outDir?: string;          // Output directory (default: 'artifacts')
+}
+```
+
+### Error Types
+
+```typescript
+import {
+  CompactCliNotFoundError,  // Compact CLI not in PATH
+  CompilationError,         // Compilation failed (includes file path)
+  DirectoryNotFoundError,   // Target directory doesn't exist
+} from '@openzeppelin/compact-tools-cli';
+```
+
+## Development
+
+```bash
+cd packages/cli
+
+# Build
+yarn build
+
+# Type-check only
+yarn types
+
+# Run tests
+yarn test
+
+# Clean
+yarn clean
+```
+
+## Output Example
+
+```
+ℹ [COMPILE] Compact compiler started
+ℹ [COMPILE] Compact developer tools: compact 0.1.0
+ℹ [COMPILE] Compact toolchain: Compactc version: 0.26.0
+ℹ [COMPILE] Found 2 .compact file(s) to compile
+✔ [COMPILE] [1/2] Compiled AccessControl.compact
+    Compactc version: 0.26.0
+✔ [COMPILE] [2/2] Compiled Token.compact
+    Compactc version: 0.26.0
+```
+
+## License
+
+MIT
+