create-fhevm-example 1.0.3 → 1.0.6

package/README.md

@@ -2,317 +2,145 @@
 
 Create FHEVM example projects with a single command.
 
-## Usage
-
-### Interactive Mode
+## Quick Start
 
 ```bash
 npx create-fhevm-example
 ```
 
-This will launch an interactive CLI that guides you through:
-
-1. Choosing between a single example or category project
-2. **For single examples**: First selecting a category, then choosing an example from that category
-3. **For category projects**: Selecting the category directly
-4. Setting the project name and output directory
-5. Optionally installing dependencies and running tests
-
-### Direct Mode
+This launches an interactive CLI that guides you through creating a project.
 
-Create a single example:
+## Direct Mode
 
 ```bash
+# Create single example
 npx create-fhevm-example --example fhe-counter
-```
-
-Create a category project:
 
-```bash
+# Create category project
 npx create-fhevm-example --category basic
-```
-
-With custom output directory:
 
-```bash
-npx create-fhevm-example --example fhe-counter --output ./my-project
+# With options
+npx create-fhevm-example --example fhe-counter --output ./my-project --install
 ```
 
-Auto-install dependencies and run tests:
+## CLI Options
 
-```bash
-npx create-fhevm-example --example fhe-counter --install --test
-```
+| Option | Description |
+|--------|-------------|
+| `--example <name>` | Create a single example project |
+| `--category <name>` | Create a category project |
+| `--output <dir>` | Output directory |
+| `--install` | Auto-install dependencies |
+| `--test` | Auto-run tests |
+| `--help` | Show help |
 
 ## Available Examples
 
-- `fhe-counter` - Confidential counter demonstration
-- `encrypt-single-value` - FHE encryption mechanism
-- `encrypt-multiple-values` - Multiple value encryption
-- `user-decrypt-single-value` - User decryption mechanism
-- `user-decrypt-multiple-values` - Multiple value decryption
-- `public-decrypt-single-value` - Public decryption
-- `public-decrypt-multiple-values` - Multiple public decryption
-- `fhe-add` - Addition operations on encrypted values
-- `fhe-if-then-else` - Conditional operations with FHE
-- `fhe-arithmetic` - All arithmetic operations
-- `fhe-comparison` - All comparison operations
-- `fhe-access-control` - Access control patterns
-- `fhe-input-proof` - Input proof validation
-- `fhe-handles` - FHE handle lifecycle
-- `fhe-anti-patterns` - Common mistakes and solutions
-- `erc7984` - Confidential token standard
-- `erc7984-erc20-wrapper` - ERC20 to ERC7984 wrapper
-- `swap-erc7984-to-erc20` - Token swap example
-- `swap-erc7984-to-erc7984` - Confidential token swap
-- `vesting-wallet` - Token vesting example
-- `blind-auction` - Encrypted blind auction
-- `hidden-voting` - Encrypted voting system
+**Basic**: `fhe-counter`, `encrypt-single-value`, `encrypt-multiple-values`, `user-decrypt-single-value`, `user-decrypt-multiple-values`, `public-decrypt-single-value`, `public-decrypt-multiple-values`
 
-## Available Categories
+**FHE Operations**: `fhe-add`, `fhe-if-then-else`, `fhe-arithmetic`, `fhe-comparison`
 
-- `basic` - Basic FHEVM Examples (9 contracts)
-- `concepts` - Critical Concepts (4 contracts)
-- `operations` - FHE Operations (4 contracts)
-- `openzeppelin` - OpenZeppelin Confidential Contracts (5 contracts)
-- `advanced` - Advanced Examples (2 contracts)
+**Concepts**: `fhe-access-control`, `fhe-input-proof`, `fhe-handles`, `fhe-anti-patterns`
 
-## CLI Options
+**OpenZeppelin**: `erc7984`, `erc7984-erc20-wrapper`, `swap-erc7984-to-erc20`, `swap-erc7984-to-erc7984`, `vesting-wallet`
 
-- `--example <name>` - Create a single example project
-- `--category <name>` - Create a category project
-- `--output <dir>` - Output directory (default: `./<project-name>`)
-- `--install` - Auto-install dependencies
-- `--test` - Auto-run tests (requires `--install`)
-- `--help`, `-h` - Show help message
+**Advanced**: `blind-auction`, `hidden-voting`
 
-## What Gets Created
+## Available Categories
+
+| Category | Description |
+|----------|-------------|
+| `basic` | Encryption, decryption, basic operations (9 contracts) |
+| `concepts` | Access control, proofs, handles (4 contracts) |
+| `operations` | Arithmetic, comparison operations (4 contracts) |
+| `openzeppelin` | ERC7984, wrappers, swaps (5 contracts) |
+| `advanced` | Blind auction, voting (2 contracts) |
 
-Each generated project includes:
+## What Gets Created
 
 - ✅ Hardhat configuration for FHEVM
-- ✅ Smart contracts from the selected example(s)
-- ✅ Comprehensive test files
+- ✅ Smart contracts and test files
 - ✅ Deployment scripts
-- ✅ README with getting started instructions
-- ✅ All necessary dependencies configured
+- ✅ All dependencies configured
 
 ## Requirements
 
 - Node.js >= 20
-- Git (for cloning templates)
-
-## Configuration
-
-### Repository Settings
+- Git
 
-The CLI is configured to use a specific GitHub repository for templates and examples. You can customize this in [`src/config.ts`](./src/config.ts):
+---
 
-```typescript
-export const REPO_URL = "https://github.com/NecipAkgz/fhevm-example-factory";
-export const REPO_BRANCH = "main";
-export const TEMPLATE_SUBMODULE_PATH = "fhevm-hardhat-template";
-```
-
-**Important**: If you fork this repository or want to use a different source:
-
-1. Update `REPO_URL` to your repository URL
-2. Ensure the repository has the same structure (contracts, test, fhevm-hardhat-template submodule)
-3. Rebuild the package: `npm run build`
+## Developer Only
 
-## Adding New Examples
+>This section is for contributors and maintainers of the package.
 
-To add a new example to the CLI:
-
-### 1. Add Example Configuration
-
-Edit [`src/config.ts`](./src/config.ts) and add your example to the `EXAMPLES` object:
+### Configuration
 
-```typescript
-export const EXAMPLES: Record<string, ExampleConfig> = {
-  // ... existing examples
-  "my-new-example": {
-    contract: "contracts/path/to/MyContract.sol",
-    test: "test/path/to/MyContract.ts",
-    description: "Description of what this example demonstrates",
-    category: "Basic", // or "Concepts", "Operations", "OpenZeppelin", "Advanced"
-    title: "My New Example",
-  },
-};
-```
+The CLI uses a configuration file that defines all available examples and categories. This file is **auto-generated** from the main repository.
 
-### 2. Add to Category (Optional)
+**Source of Truth**: [`scripts/shared/config.ts`](https://github.com/NecipAkgz/fhevm-example-factory/blob/main/scripts/shared/config.ts)
+**Generated File**: `src/config.ts` (do not edit manually)
 
-If you want the example to appear in a category project, add it to the relevant category in `CATEGORIES`:
+To customize the repository URL or branch:
 
 ```typescript
-export const CATEGORIES: Record<string, CategoryConfig> = {
-  basic: {
-    name: "Basic FHEVM Examples",
-    description: "...",
-    contracts: [
-      // ... existing contracts
-      {
-        sol: "contracts/path/to/MyContract.sol",
-        test: "test/path/to/MyContract.ts",
-      },
-    ],
-  },
-};
+// In src/config.ts (after sync)
+export const REPO_URL = "https://github.com/YourUsername/your-repo";
+export const REPO_BRANCH = "main";
 ```
 
-### 3. Ensure Files Exist in Repository
-
-Make sure the contract and test files exist in your repository at the specified paths:
+### Adding New Examples
 
-- `contracts/path/to/MyContract.sol`
-- `test/path/to/MyContract.ts`
+To add a new example to the CLI:
 
-### 4. Rebuild and Test
+1. **Edit the source config** in the main repository:
+   ```bash
+   # Edit scripts/shared/config.ts
+   # Add your example to EXAMPLES and CATEGORIES
+   ```
 
-```bash
-npm run build
-create-fhevm-example --example my-new-example --output /tmp/test-my-example
-```
+2. **Publish**:
+   ```bash
+   npm version patch  # Increments version
+   npm publish        # Auto-runs: sync:config → build → publish
+   ```
 
-## Development
+   The `prepublishOnly` hook automatically:
+   - Syncs config from `scripts/shared/config.ts` to `src/config.ts`
+   - Builds TypeScript to `dist/`
+   - Publishes to NPM
 
-### Local Development Setup
+### Local Development
 
 ```bash
-# Clone the repository
+# Clone and setup
 git clone https://github.com/NecipAkgz/fhevm-example-factory.git
 cd fhevm-example-factory/packages/create-fhevm-example
-
-# Install dependencies
 npm install
 
-# Build the package
+# Build
 npm run build
 
-# Link for local testing
+# Test locally
 npm link
-
-# Now you can use it globally
 create-fhevm-example --help
-```
-
-### Making Changes
 
-1. **Edit source files** in `src/`
-2. **Rebuild**: `npm run build`
-3. **Test locally**: `create-fhevm-example --example fhe-counter --output /tmp/test`
-
-### File Structure
-
-```
-src/
-├── index.ts      # Main CLI entry point (interactive + direct modes)
-├── config.ts     # Examples and categories configuration
-└── utils.ts      # Helper functions (GitHub download, file ops, README generation)
-```
-
-## Publishing to NPM
-
-### Pre-publish Checklist
-
-- [ ] Update version in `package.json`
-- [ ] Test locally with `npm link`
-- [ ] Verify all examples work
-- [ ] Update README if needed
-- [ ] Commit all changes
-
-### Publish Steps
-
-```bash
-# Dry run to see what will be published
-npm publish --dry-run
-
-# Check package contents
-npm pack
-tar -xvzf create-fhevm-example-*.tgz
-rm -rf package create-fhevm-example-*.tgz
-
-# Publish to NPM
-npm publish
-```
-
-### Post-publish Verification
-
-```bash
-# Test from NPM in a clean directory
-cd /tmp
-npx create-fhevm-example@latest --example fhe-counter
-```
-
-## Troubleshooting
-
-### "Repository not found" Error
-
-**Problem**: Git clone fails with repository not found.
-
-**Solution**: Check `REPO_URL` in `src/config.ts`. Make sure:
-
-- The repository exists and is public
-- The URL is correct (without trailing slash)
-- You have internet connection
-
-### "Failed to download" Error
-
-**Problem**: File download from GitHub fails.
-
-**Solution**:
-
-- Verify the file paths in `config.ts` match actual files in the repository
-- Check that `REPO_BRANCH` is correct (usually "main" or "master")
-- Ensure the repository is public or you have access
-
-### Build Errors
-
-**Problem**: TypeScript compilation fails.
-
-**Solution**:
-
-```bash
-# Clean and rebuild
-rm -rf dist
-npm run build
+# Unlink when done
+npm unlink -g create-fhevm-example
 ```
 
-### Examples Not Showing Up
-
-**Problem**: New example doesn't appear in the CLI.
-
-**Solution**:
-
-- Make sure you added it to `EXAMPLES` in `config.ts`
-- Rebuild: `npm run build`
-- If using `npm link`, unlink and relink:
-  ```bash
-  npm unlink -g create-fhevm-example
-  npm link
-  ```
-
-## Maintenance
-
-### Updating Template Repository
-
-When the `fhevm-hardhat-template` submodule is updated:
-
-1. No changes needed in this package - it clones fresh each time
-2. Users will automatically get the latest template
-
-### Syncing Examples
+### Scripts
 
-When new examples are added to the main repository:
+- `npm run build` - Compile TypeScript
+- `npm run dev` - Watch mode
+- `npm run sync:config` - Sync config from main repo
+- `npm run prepublishOnly` - Auto-runs sync + build before publish
 
-1. Update `src/config.ts` with new example definitions
-2. Increment version in `package.json`
-3. Rebuild and publish: `npm run build && npm publish`
+---
 
 ## Learn More
 
-- [FHEVM Documentation](https://docs.zama.ai/fhevm)
+- [FHEVM Documentation](https://docs.zama.org/protocol)
 - [Example Repository](https://github.com/NecipAkgz/fhevm-example-factory)
 - [Zama](https://www.zama.ai/)
 

package/dist/config.d.ts

@@ -1,7 +1,11 @@
 /**
- * Shared configuration for FHEVM examples
+ * ⚠️ AUTO-GENERATED FILE - DO NOT EDIT MANUALLY ⚠️
  *
- * This configuration is used by the CLI to provide available examples and categories
+ * This file is auto-generated from scripts/shared/config.ts
+ * Run 'npm run sync:config' to update it.
+ *
+ * Source: scripts/shared/config.ts
+ * Generated: 2025-12-09T16:46:12.589Z
  */
 export interface ExampleConfig {
     /** Path to the Solidity contract file */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,uDAAuD,CAAC;AAC7E,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,uBAAuB,2BAA2B,CAAC;AAMhE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAiLlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAkIrD,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD;AAMD,eAAO,MAAM,QAAQ,uDAAuD,CAAC;AAC7E,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,uBAAuB,2BAA2B,CAAC;AAMhE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA2JlD,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CA+HrD,CAAC"}