create-fhevm-example 1.2.3 → 1.3.1

package/dist/scripts/generate-config.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Auto-Discovery Config Generator - Automatically updates project configuration.
+ *
+ * Scans the contracts/ directory and generates scripts/config.ts.
+ * Extracts metadata from @notice tags and infers category structure.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("./utils");
+const picocolors_1 = __importDefault(require("picocolors"));
+const ROOT_DIR = path.resolve(__dirname, "..");
+const CONTRACTS_DIR = path.join(ROOT_DIR, "contracts");
+const TEST_DIR = path.join(ROOT_DIR, "test");
+const OUTPUT_FILE = path.join(ROOT_DIR, "scripts/config.ts");
+// =============================================================================
+// Contract Analysis
+// =============================================================================
+function extractNotice(contractPath) {
+    const content = fs.readFileSync(contractPath, "utf-8");
+    const noticeRegex = /\/\*\*[\s\S]*?@notice\s+([^\n*]+)[\s\S]*?\*\/[\s\S]*?contract\s+\w+/;
+    const match = content.match(noticeRegex);
+    return match && match[1] ? match[1].trim() : null;
+}
+function readExistingConfig() {
+    try {
+        if (!fs.existsSync(OUTPUT_FILE)) {
+            return {};
+        }
+        delete require.cache[require.resolve(OUTPUT_FILE)];
+        const config = require(OUTPUT_FILE);
+        return config.EXAMPLES || {};
+    }
+    catch (error) {
+        console.warn("⚠️  Could not read existing config, starting fresh");
+        return {};
+    }
+}
+function getCategoryFromPath(relativePath) {
+    const parts = relativePath.split("/");
+    parts.pop();
+    if (parts.length === 0)
+        return "Uncategorized";
+    if (parts.length === 1)
+        return (0, utils_1.formatCategoryName)(parts[0]);
+    return parts.map(utils_1.formatCategoryName).join(" - ");
+}
+function findTestFile(contractPath) {
+    const relativePath = path.relative(CONTRACTS_DIR, contractPath);
+    const testPath = path.join(TEST_DIR, relativePath.replace(".sol", ".ts"));
+    return fs.existsSync(testPath)
+        ? `test/${path.relative(TEST_DIR, testPath)}`
+        : null;
+}
+function getDocsOutput(contractPath) {
+    const relativePath = contractPath
+        .replace(/^contracts\//, "")
+        .replace(/\.sol$/, "");
+    return `docs/${(0, utils_1.toKebabCase)(relativePath)}.md`;
+}
+function scanContracts() {
+    const contracts = [];
+    const existingConfig = readExistingConfig();
+    function scan(dir) {
+        const items = fs.readdirSync(dir);
+        for (const item of items) {
+            const fullPath = path.join(dir, item);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory() && item !== "mocks") {
+                scan(fullPath);
+            }
+            else if (stat.isFile() && item.endsWith(".sol")) {
+                const relativePath = path.relative(CONTRACTS_DIR, fullPath);
+                const contractName = item.replace(".sol", "");
+                const exampleName = (0, utils_1.contractNameToExampleName)(contractName);
+                const category = getCategoryFromPath(relativePath);
+                const testPath = findTestFile(fullPath);
+                const description = extractNotice(fullPath);
+                if (!description) {
+                    console.warn(`⚠️  No @notice found in ${relativePath}`);
+                    return;
+                }
+                if (!testPath) {
+                    console.warn(`⚠️  No test file found for ${relativePath}`);
+                    return;
+                }
+                const contractInfo = {
+                    name: exampleName,
+                    contractPath: `contracts/${relativePath}`,
+                    testPath,
+                    description,
+                    category,
+                    title: (0, utils_1.contractNameToTitle)(contractName),
+                    docsOutput: getDocsOutput(`contracts/${relativePath}`),
+                };
+                const existingExample = existingConfig[exampleName];
+                if (existingExample?.npmDependencies) {
+                    contractInfo.npmDependencies = existingExample.npmDependencies;
+                }
+                if (existingExample?.dependencies) {
+                    contractInfo.dependencies = existingExample.dependencies;
+                }
+                contracts.push(contractInfo);
+            }
+        }
+    }
+    scan(CONTRACTS_DIR);
+    return contracts;
+}
+// =============================================================================
+// Config Generation
+// =============================================================================
+function generateExamplesConfig(contracts) {
+    const entries = contracts.map((c) => {
+        const npmDepsField = c.npmDependencies
+            ? `\n    npmDependencies: ${JSON.stringify(c.npmDependencies, null, 2).replace(/\n/g, "\n    ")},`
+            : "";
+        const depsField = c.dependencies
+            ? `\n    dependencies: ${JSON.stringify(c.dependencies, null, 2).replace(/\n/g, "\n    ")},`
+            : "";
+        return `  "${c.name}": {
+    contract: "${c.contractPath}",
+    test: "${c.testPath}",${npmDepsField}${depsField}
+    description:
+      "${c.description}",
+    category: "${c.category}",
+    docsOutput: "${c.docsOutput}",
+    title: "${c.title}"
+  }`;
+    });
+    return `export const EXAMPLES: Record<string, ExampleConfig> = {\n${entries.join(",\n")}\n};`;
+}
+function generateCategoriesConfig(contracts) {
+    const categoryMap = {};
+    for (const contract of contracts) {
+        if (!categoryMap[contract.category]) {
+            categoryMap[contract.category] = [];
+        }
+        categoryMap[contract.category].push(contract);
+    }
+    const categoryEntries = Object.entries(categoryMap).map(([category, items]) => {
+        const categoryKey = category
+            .toLowerCase()
+            .replace(/\s+/g, "")
+            .replace(/-/g, "");
+        const contracts = items
+            .map((c) => `      {
+        sol: "${c.contractPath}",
+        test: "${c.testPath}",
+      }`)
+            .join(",\n");
+        return `  ${categoryKey}: {
+    name: "${category} Examples",
+    contracts: [
+${contracts}
+    ],
+  }`;
+    });
+    return `export const CATEGORIES: Record<string, CategoryConfig> = {\n${categoryEntries.join(",\n")}\n};`;
+}
+function generateConfigFile(contracts) {
+    return `/**
+ * ⚠️ AUTO-GENERATED FILE - DO NOT EDIT MANUALLY ⚠️
+ *
+ * This file is auto-generated by cli/generate-config.ts
+ * Run 'npm run generate:config' to regenerate
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ExampleConfig {
+  /** Path to the Solidity contract file */
+  contract: string;
+  /** Path to the TypeScript test file */
+  test: string;
+  /** Optional additional contract dependencies */
+  dependencies?: string[];
+  /** Optional npm packages to install */
+  npmDependencies?: Record<string, string>;
+  /** Full description for documentation */
+  description: string;
+  /** Category for grouping */
+  category: string;
+  /** Output path for generated documentation */
+  docsOutput: string;
+  /** Title for documentation */
+  title: string;
+}
+
+export interface CategoryConfig {
+  /** Display name */
+  name: string;
+  /** List of contracts in this category */
+  contracts: Array<{ sol: string; test?: string }>;
+}
+
+// =============================================================================
+// GitHub Repository Configuration
+// =============================================================================
+
+export const REPO_URL = "https://github.com/NecipAkgz/fhevm-example-factory";
+export const REPO_BRANCH = "main";
+
+// =============================================================================
+// Example Configurations
+// =============================================================================
+
+${generateExamplesConfig(contracts)}
+
+// =============================================================================
+// Category Configurations
+// =============================================================================
+
+${generateCategoriesConfig(contracts)}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Get list of example names
+ */
+export function getExampleNames(): string[] {
+  return Object.keys(EXAMPLES);
+}
+
+/**
+ * Get list of category names
+ */
+export function getCategoryNames(): string[] {
+  return Object.keys(CATEGORIES);
+}
+
+/**
+ * Get example by name
+ */
+export function getExample(name: string): ExampleConfig | undefined {
+  return EXAMPLES[name];
+}
+
+/**
+ * Get category by name
+ */
+export function getCategory(name: string): CategoryConfig | undefined {
+  return CATEGORIES[name];
+}
+
+/**
+ * Generate consistent docs filename with fhe- prefix
+ */
+export function getDocsFileName(exampleName: string): string {
+  return exampleName.startsWith("fhe-") ? exampleName : \`fhe-\${exampleName}\`;
+}
+`;
+}
+// =============================================================================
+// Main
+// =============================================================================
+function main() {
+    utils_1.log.info(`🔍 Scanning examples in: ${picocolors_1.default.cyan("contracts/")}\n`);
+    const contracts = scanContracts();
+    if (contracts.length === 0) {
+        utils_1.log.error("❌ No valid contracts discovered. Check for @notice tags.");
+        process.exit(1);
+    }
+    utils_1.log.success(`✅ Found ${picocolors_1.default.bold(String(contracts.length))} contracts\n`);
+    const categoryCount = {};
+    for (const c of contracts) {
+        categoryCount[c.category] = (categoryCount[c.category] || 0) + 1;
+    }
+    utils_1.log.message(picocolors_1.default.bold("📊 Discovery Summary:"));
+    for (const [category, count] of Object.entries(categoryCount)) {
+        utils_1.log.message(`   ${picocolors_1.default.dim("•")} ${picocolors_1.default.yellow(category.padEnd(25))} ${picocolors_1.default.cyan(String(count).padStart(2))} examples`);
+    }
+    utils_1.log.message(`\n📝 Generating: ${picocolors_1.default.cyan(path.relative(ROOT_DIR, OUTPUT_FILE))}...`);
+    const configContent = generateConfigFile(contracts);
+    fs.writeFileSync(OUTPUT_FILE, configContent);
+    utils_1.log.success(`\n✨ Configuration updated successfully!`);
+}
+const isMainModule = process.argv[1]?.includes("generate-config");
+if (isMainModule) {
+    main();
+}

package/dist/scripts/generate-docs.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Documentation Generator - Creates GitBook-compatible markdown docs.
+ *
+ * Processes FHEVM examples to produce structured documentation,
+ * including contract descriptions and automated index updates.
+ */
+export declare function handleInteractiveDocs(): Promise<void>;
+export declare function handleDirect(args: string[]): Promise<void>;
+//# sourceMappingURL=generate-docs.d.ts.map

package/dist/scripts/generate-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-docs.d.ts","sourceRoot":"","sources":["../../scripts/generate-docs.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAuEH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiE3D;AAMD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhE"}

package/dist/scripts/generate-docs.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Documentation Generator - Creates GitBook-compatible markdown docs.
+ *
+ * Processes FHEVM examples to produce structured documentation,
+ * including contract descriptions and automated index updates.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleInteractiveDocs = handleInteractiveDocs;
+exports.handleDirect = handleDirect;
+const p = __importStar(require("@clack/prompts"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const utils_1 = require("./utils");
+// =============================================================================
+// Documentation Generator
+// =============================================================================
+async function generateDocumentation(exampleName) {
+    const rootDir = (0, utils_1.getRootDir)();
+    let count = 0;
+    const examples = exampleName === "all" ? Object.keys(config_1.EXAMPLES) : [exampleName];
+    for (const name of examples) {
+        const example = config_1.EXAMPLES[name];
+        if (!example)
+            continue;
+        const contractPath = path.join(rootDir, example.contract);
+        const testPath = path.join(rootDir, example.test);
+        if (!fs.existsSync(contractPath) || !fs.existsSync(testPath))
+            continue;
+        const contractContent = fs.readFileSync(contractPath, "utf-8");
+        const testContent = fs.readFileSync(testPath, "utf-8");
+        const contractName = (0, utils_1.getContractName)(example.contract) || "Contract";
+        const testFileName = path.basename(example.test);
+        const markdown = (0, utils_1.generateGitBookMarkdown)(example.description, contractContent, testContent, contractName, testFileName);
+        const outputPath = example.docsOutput
+            ? path.join(rootDir, example.docsOutput)
+            : path.join(rootDir, "docs", `${(0, config_1.getDocsFileName)(name)}.md`);
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, markdown);
+        count++;
+    }
+    return count;
+}
+// =============================================================================
+// Interactive Mode
+// =============================================================================
+async function handleInteractiveDocs() {
+    console.clear();
+    p.intro(picocolors_1.default.bgCyan(picocolors_1.default.black(" 📚 Generate Documentation ")));
+    const scope = await p.select({
+        message: "Generate documentation for:",
+        options: [
+            {
+                value: "all",
+                label: "All examples",
+                hint: `${Object.keys(config_1.EXAMPLES).length} files`,
+            },
+            { value: "single", label: "Single example" },
+        ],
+    });
+    if (p.isCancel(scope)) {
+        p.cancel("Operation cancelled.");
+        return;
+    }
+    let target = "all";
+    if (scope === "single") {
+        const example = await p.select({
+            message: "Select an example:",
+            options: Object.entries(config_1.EXAMPLES).map(([key, config]) => ({
+                value: key,
+                label: key,
+                hint: config.category,
+            })),
+        });
+        if (p.isCancel(example)) {
+            p.cancel("Operation cancelled.");
+            return;
+        }
+        target = example;
+    }
+    const s = p.spinner();
+    s.start("Generating documentation...");
+    try {
+        const count = await generateDocumentation(target);
+        s.stop(`Generated ${count} documentation file(s)`);
+        p.log.success(`📄 Files: ${picocolors_1.default.green(String(count))} documentation file(s)`);
+        p.log.info(`📁 Location: ${picocolors_1.default.cyan("docs/")}`);
+        if (target !== "all") {
+            const docFileName = (0, config_1.getDocsFileName)(target);
+            p.log.message(`   └─ ${picocolors_1.default.dim(docFileName + ".md")}`);
+        }
+        p.log.message("");
+        p.log.message(picocolors_1.default.dim("💡 Tip: Run 'npm run create:docs' to regenerate all docs"));
+        p.outro(picocolors_1.default.green("🎉 Documentation generated!"));
+    }
+    catch (error) {
+        s.stop("Failed to generate documentation");
+        p.log.error(error instanceof Error ? error.message : String(error));
+    }
+}
+// =============================================================================
+// QUICK MODE (CLI)
+// =============================================================================
+async function handleDirect(args) {
+    const [target] = args;
+    if (!target) {
+        utils_1.log.info("Generating all documentation...");
+        const count = await generateDocumentation("all");
+        utils_1.log.success(`✓ Generated ${count} documentation files`);
+        return;
+    }
+    if (!config_1.EXAMPLES[target]) {
+        utils_1.log.message("Available: " + Object.keys(config_1.EXAMPLES).join(", "));
+        (0, utils_1.handleError)(`Unknown example "${target}"`);
+    }
+    utils_1.log.info(`Generating docs for: ${target}`);
+    await generateDocumentation(target);
+    utils_1.log.success(`✓ Generated: docs/${(0, config_1.getDocsFileName)(target)}.md`);
+}
+// =============================================================================
+// Help
+// =============================================================================
+function showHelp() {
+    utils_1.log.info("📚 FHEVM Documentation Generator");
+    utils_1.log.message("");
+    utils_1.log.message("Usage:");
+    utils_1.log.message("  npm run create:docs              Generate all docs");
+    utils_1.log.message("  npm run create:docs <example>    Generate specific example doc");
+    utils_1.log.message("");
+    utils_1.log.message("Examples:");
+    utils_1.log.dim("  npm run create:docs");
+    utils_1.log.dim("  npm run create:docs fhe-counter");
+}
+// =============================================================================
+// Main Entry Point
+// =============================================================================
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        showHelp();
+        return;
+    }
+    await handleDirect(args);
+}
+const isMainModule = process.argv[1]?.includes("generate-docs");
+if (isMainModule) {
+    main().catch(console.error);
+}

package/dist/scripts/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * create-fhevm-example - CLI for creating FHEVM example projects
+ *
+ * Usage:
+ *   npx create-fhevm-example                    # Interactive mode
+ *   npx create-fhevm-example --example <name>   # Create single example
+ *   npx create-fhevm-example --category <name>  # Create category project
+ *   npx create-fhevm-example --add              # Add to existing project
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/scripts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../scripts/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}