feat(tools/compiler): introduce artifacts manifest, and strict the types

packages/cli/README.md

@@ -51,6 +51,7 @@ compact-compiler [options]
 | `--src <directory>` | Source directory containing `.compact` files | `src` |
 | `--out <directory>` | Output directory for compiled artifacts | `artifacts` |
 | `--hierarchical` | Preserve source directory structure in output | `false` |
+| `--force`, `-f` | Force delete existing artifacts on structure mismatch | `false` |
 | `--skip-zk` | Skip zero-knowledge proof generation | `false` |
 | `+<version>` | Use specific toolchain version (e.g., `+0.26.0`) | (default) |
 
@@ -86,6 +87,89 @@ artifacts/           # Hierarchical output
     Token/
 ```
 
+### Structure Mismatch Detection
+
+The compiler tracks which structure type was used via a `manifest.json` file in the output directory. When switching between flattened and hierarchical structures:
+
+- **Interactive mode (TTY):** Prompts for confirmation before deleting existing artifacts
+- **Non-interactive mode (CI/CD):** Requires `--force` flag to proceed
+
+```bash
+$ compact-compiler --hierarchical
+
+⚠ [COMPILE] Existing artifacts use "flattened" structure.
+⚠ [COMPILE] You are compiling with "hierarchical" structure.
+? Delete existing artifacts and recompile? (y/N)
+```
+
+To skip the prompt in scripts or CI/CD:
+
+```bash
+compact-compiler --hierarchical --force
+```
+
+### Manifest File
+
+The compiler generates a `manifest.json` in the output directory containing build metadata and artifact information. This file is used for structure mismatch detection and build reproducibility.
+
+#### Manifest Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `structure` | `"flattened"` \| `"hierarchical"` | Artifact output structure used during compilation |
+| `compactcVersion` | `CompactcVersion` | Supported compiler version (e.g., `"0.25.0"` \| `"0.26.0"`) |
+| `compactToolVersion` | `CompactToolVersion` | Supported CLI version (e.g., `"0.2.0"` \| `"0.3.0"`) |
+| `createdAt` | `string` | ISO 8601 timestamp (e.g., `"2025-12-11T10:09:46.023Z"`) |
+| `buildDuration` | `number` | Total compilation duration in milliseconds |
+| `nodeVersion` | `NodeVersion` | Node.js major version (`"18"` \| `"20"` \| `"21"` \| `"22"` \| `"23"` \| `"24"` \| `"25"`) |
+| `platform` | `Platform` | Platform identifier (`"linux-x64"` \| `"linux-arm64"` \| `"darwin-x64"` \| `"darwin-arm64"` \| `"win32-x64"` \| `"win32-arm64"`) |
+| `sourcePath` | `string` | Path to source directory containing `.compact` files |
+| `outputPath` | `string` | Path to output directory where artifacts were written |
+| `compilerFlags` | `CompilerFlag[]` | Compiler flags (`"--skip-zk"` \| `"--vscode"` \| `"--no-communications-commitment"` \| `"--trace-passes"` \| `"--sourceRoot <value>"`) |
+| `artifacts` | `string[]` \| `HierarchicalArtifacts` | Compiled contracts (format depends on structure, see below) |
+
+#### Artifacts Format
+
+The `artifacts` format depends on the output structure:
+
+- **Flattened structure**: A flat array of contract names
+
+```json
+"artifacts": ["Counter", "Boolean", "Bytes", "Field"]
+```
+
+- **Hierarchical structure**: An object where keys are source subdirectory names and values are arrays of contract names compiled from that subdirectory
+
+```json
+"artifacts": {
+  "ledger": ["Counter"],
+  "reference": ["Boolean", "Bytes", "Field"]
+}
+```
+
+This corresponds to source files like `src/ledger/Counter.compact` and `src/reference/Boolean.compact`.
+
+#### Example Manifest
+
+```json
+{
+  "structure": "hierarchical",
+  "compactcVersion": "0.26.0",
+  "compactToolVersion": "0.3.0",
+  "createdAt": "2025-12-11T10:35:09.916Z",
+  "buildDuration": 2445,
+  "nodeVersion": "22",
+  "platform": "linux-x64",
+  "sourcePath": "src",
+  "outputPath": "artifacts",
+  "compilerFlags": ["--skip-zk"],
+  "artifacts": {
+    "ledger": ["Counter"],
+    "reference": ["Boolean", "Bytes", "Field"]
+  }
+}
+```
+
 ### Examples
 
 ```bash
@@ -110,6 +194,9 @@ compact-compiler --src contracts --out build
 # Combine options
 compact-compiler --dir access --skip-zk --hierarchical
 
+# Force structure change without prompt
+compact-compiler --hierarchical --force
+
 # Use environment variable
 SKIP_ZK=true compact-compiler
 ```
@@ -153,7 +240,7 @@ import { CompactCompiler } from '@openzeppelin/compact-tools-cli';
 
 // Using options object
 const compiler = new CompactCompiler({
-  flags: '--skip-zk',
+  flags: ['--skip-zk'],
   targetDir: 'security',
   version: '0.26.0',
   hierarchical: true,
@@ -194,13 +281,25 @@ class CompactBuilder {
 
 // Options interface
 interface CompilerOptions {
-  flags?: string;           // Compiler flags (e.g., '--skip-zk --verbose')
+  flags?: CompilerFlag[];   // Compiler flags (e.g., ['--skip-zk'])
   targetDir?: string;       // Subdirectory within srcDir to compile
-  version?: string;         // Toolchain version (e.g., '0.26.0')
+  version?: CompactcVersion; // 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')
+  force?: boolean;          // Force delete on structure mismatch
 }
+
+// Compiler flags (passed to compactc)
+type CompilerFlag =
+  | '--skip-zk'
+  | '--vscode'
+  | '--no-communications-commitment'
+  | '--trace-passes'
+  | `--sourceRoot ${string}`;
+
+// Supported compactc versions
+type CompactcVersion = '0.23.0' | '0.24.0' | '0.25.0' | '0.26.0';
 ```
 
 ### Error Types
@@ -210,6 +309,7 @@ import {
   CompactCliNotFoundError,  // Compact CLI not in PATH
   CompilationError,         // Compilation failed (includes file path)
   DirectoryNotFoundError,   // Target directory doesn't exist
+  StructureMismatchError,   // Artifact structure mismatch (flattened vs hierarchical)
 } from '@openzeppelin/compact-tools-cli';
 ```
 
@@ -235,13 +335,11 @@ yarn clean
 
 ```
 ℹ [COMPILE] Compact compiler started
-ℹ [COMPILE] Compact developer tools: compact 0.1.0
-ℹ [COMPILE] Compact toolchain: Compactc version: 0.26.0
+ℹ [COMPILE] compact-tools: 0.3.0
+ℹ [COMPILE] compactc: 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