@friehub/blueprint 0.1.0

package/dist/core/verify.js

@@ -0,0 +1,156 @@
+import { readFile } from "node:fs/promises";
+export async function verifyImplementation(implementationFile, moduleName, catalog) {
+    const mod = catalog.modules.find((m) => m.name === moduleName);
+    if (!mod) {
+        return {
+            module: moduleName,
+            contractVersion: null,
+            valid: false,
+            implFunctions: [],
+            contractFunctions: [],
+            issues: [{ module: moduleName, kind: "file-not-found", function: "", message: `Module "${moduleName}" not found in catalog` }],
+        };
+    }
+    let content;
+    try {
+        content = await readFile(implementationFile, "utf8");
+    }
+    catch {
+        return {
+            module: moduleName,
+            contractVersion: mod.version,
+            valid: false,
+            implFunctions: [],
+            contractFunctions: mod.functions.map((f) => f.name),
+            issues: [{ module: moduleName, kind: "file-not-found", function: "", message: `File not found: ${implementationFile}` }],
+        };
+    }
+    const issues = [];
+    const implFns = extractFunctions(content);
+    for (const fn of mod.functions) {
+        const implFn = implFns.find((f) => f.name === fn.name);
+        if (!implFn) {
+            const expectedSig = formatSignature(fn);
+            issues.push({
+                module: moduleName,
+                kind: "missing",
+                function: fn.name,
+                expected: expectedSig,
+                message: `Missing: ${expectedSig}`,
+            });
+        }
+        else {
+            const issues = compareReturnTypes(fn, implFn, moduleName);
+            issues.push(...issues);
+        }
+    }
+    return {
+        module: moduleName,
+        contractVersion: mod.version,
+        valid: issues.filter((i) => i.kind === "missing" || i.kind === "mismatch").length === 0,
+        implFunctions: [...implFns.keys()].map((n) => String(n)),
+        contractFunctions: mod.functions.map((f) => f.name),
+        issues,
+    };
+}
+function extractFunctions(content) {
+    const functions = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("//") || line.startsWith("/*") || line.startsWith("*"))
+            continue;
+        // Match: async initPayment(params): ReturnType {
+        // Match: async initPayment(params) {
+        // Match: initPayment(params): ReturnType {
+        // Match: initPayment = async (params): ReturnType => {
+        // Match: private async initPayment(params): ReturnType {
+        const asyncMatch = line.match(/(?:private\s+|public\s+|protected\s+)?(?:async\s+)?(\w+)\s*[=(]\s*(?:async\s*)?[=(]?\s*(?:async\s*)?/);
+        if (asyncMatch && isValidMethodName(asyncMatch[1])) {
+            const name = asyncMatch[1];
+            // Look for return type annotation
+            let returnType = null;
+            let returnTypeLine = i;
+            // Check current line for return type
+            const rtMatch = line.match(/\)\s*:\s*(\S+?)\s*[{=]/);
+            if (rtMatch) {
+                returnType = rtMatch[1].replace(/Promise<|>/g, "").split("|")[0]?.trim() ?? null;
+                returnTypeLine = i;
+            }
+            // Check next lines for return type (multi-line)
+            if (!returnType && i + 1 < lines.length) {
+                const nextLine = lines[i + 1].trim();
+                const nextMatch = nextLine.match(/\)\s*:\s*(\S+?)\s*[{=]/);
+                if (nextMatch) {
+                    returnType = nextMatch[1].replace(/Promise<|>/g, "").split("|")[0]?.trim() ?? null;
+                    returnTypeLine = i + 1;
+                }
+            }
+            // Check for return statements in the body
+            let hasReturn = false;
+            for (let j = i + 1; j < Math.min(lines.length, i + 20); j++) {
+                if (lines[j].trim().startsWith("return ")) {
+                    hasReturn = true;
+                    break;
+                }
+                if (lines[j].trim() === "}")
+                    break;
+            }
+            functions.push({
+                name,
+                returnType,
+                returnTypeLine,
+                hasReturnStatement: hasReturn,
+            });
+        }
+    }
+    return functions;
+}
+function isValidMethodName(name) {
+    const RESERVED = new Set([
+        "constructor", "if", "else", "for", "while", "return", "const", "let", "var", "new",
+        "import", "export", "from", "typeof", "function", "class", "this", "throw", "try",
+        "catch", "finally", "switch", "case", "default",
+    ]);
+    return !RESERVED.has(name) && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}
+function formatSignature(fn) {
+    const params = fn.params.map((p) => `${p.name}${p.optional ? "?" : ""}${p.type ? ": " + p.type : ""}`).join(", ");
+    return `${fn.name}(${params}) → ${fn.returns}`;
+}
+function compareReturnTypes(fn, implFn, moduleName) {
+    const issues = [];
+    if (fn.returns === "void" || fn.returns === "void?") {
+        return issues;
+    }
+    if (!implFn.returnType) {
+        if (!implFn.hasReturnStatement) {
+            issues.push({
+                module: moduleName,
+                kind: "mismatch",
+                function: fn.name,
+                expected: fn.returns,
+                message: `${fn.name}: expected return type "${fn.returns}" but no return type annotation found. Add return type.`,
+            });
+        }
+        return issues;
+    }
+    const expected = fn.returns.toLowerCase().replace("?", "");
+    const actual = implFn.returnType.toLowerCase();
+    if (expected !== actual &&
+        expected !== actual.replace("[]", "") &&
+        !expected.includes(actual) &&
+        !actual.includes(expected) &&
+        actual !== "unknown" &&
+        actual !== "any") {
+        issues.push({
+            module: moduleName,
+            kind: "mismatch",
+            function: fn.name,
+            expected: fn.returns,
+            actual: implFn.returnType,
+            message: `${fn.name}: expected return type "${fn.returns}" but found "${implFn.returnType}"`,
+        });
+    }
+    return issues;
+}

package/dist/generators/engine.js

@@ -0,0 +1,86 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const generators = new Map();
+export function registerGenerator(generator) {
+    generators.set(generator.language, generator);
+}
+export function getGenerator(language) {
+    return generators.get(language);
+}
+export function getAvailableLanguages() {
+    return [...generators.keys()];
+}
+export async function generate(catalog, adapters, options) {
+    const generator = generators.get(options.language);
+    if (!generator) {
+        return {
+            files: [],
+            errors: [`Generator for language "${options.language}" not registered`],
+        };
+    }
+    const context = {
+        catalog,
+        adapters,
+        module: options.module,
+        provider: options.provider,
+    };
+    let result;
+    switch (options.type) {
+        case "interfaces":
+            result = generator.generateInterfaces(context);
+            break;
+        case "adapters":
+            result = generator.generateAdapter(context);
+            break;
+        case "tests":
+            result = generator.generateTests(context);
+            break;
+        case "all":
+            result = mergeResults(generator.generateInterfaces(context), generator.generateAdapter(context), generator.generateTests(context));
+            break;
+        default:
+            result = { files: [], errors: [`Unknown generation type: ${options.type}`] };
+    }
+    return result;
+}
+export async function generateAndWrite(catalog, adapters, options) {
+    const result = await generate(catalog, adapters, options);
+    let written = 0;
+    const errors = [...result.errors];
+    for (const file of result.files) {
+        try {
+            const fullPath = join(options.outputDir, file.path);
+            await mkdir(dirname(fullPath), { recursive: true });
+            await writeFile(fullPath, file.content, "utf8");
+            written++;
+        }
+        catch (error) {
+            errors.push(`Failed to write ${file.path}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    return { written, errors };
+}
+function mergeResults(...results) {
+    const files = [];
+    const errors = [];
+    for (const result of results) {
+        files.push(...result.files);
+        errors.push(...result.errors);
+    }
+    return { files, errors };
+}
+export function filterModules(catalog, moduleName) {
+    if (!moduleName) {
+        return catalog.modules;
+    }
+    return catalog.modules.filter((m) => m.name === moduleName);
+}
+export function filterAdapters(adapters, moduleName, provider) {
+    return adapters.filter((a) => {
+        if (moduleName && a.module !== moduleName)
+            return false;
+        if (provider && a.name !== provider)
+            return false;
+        return true;
+    });
+}

package/dist/generators/generator.test.js

@@ -0,0 +1,112 @@
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot } from "../core/index.js";
+import { loadAdapters } from "../core/adapters/load.js";
+import { registerGenerator, generate, getAvailableLanguages } from "./engine.js";
+import { TypeScriptGenerator } from "./typescript/index.js";
+import { pascalCase, camelCase, snakeCase, mapType, inferType } from "./types.js";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+const ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const ADAPTERS_DIR = join(ROOT, "adapters");
+describe("generator engine", () => {
+    it("registers TypeScript generator", () => {
+        registerGenerator(new TypeScriptGenerator());
+        const languages = getAvailableLanguages();
+        assert.ok(languages.includes("typescript"));
+    });
+    it("generates interfaces for all 108 modules", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const genResult = await generate(result.value, adapters, {
+            language: "typescript",
+            type: "interfaces",
+            module: undefined,
+            provider: undefined,
+            outputDir: "/tmp/test",
+        });
+        assert.equal(genResult.errors.length, 0, `No errors: ${genResult.errors.join(", ")}`);
+        assert.ok(genResult.files.length >= 108, `At least 108 interface files, got ${genResult.files.length}`);
+    });
+    it("generates adapters for all 82 adapters", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const genResult = await generate(result.value, adapters, {
+            language: "typescript",
+            type: "adapters",
+            module: undefined,
+            provider: undefined,
+            outputDir: "/tmp/test",
+        });
+        assert.equal(genResult.errors.length, 0, `No errors: ${genResult.errors.join(", ")}`);
+        assert.ok(genResult.files.length >= 82, `At least 82 adapter files, got ${genResult.files.length}`);
+    });
+    it("generates tests for all 82 adapters", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const genResult = await generate(result.value, adapters, {
+            language: "typescript",
+            type: "tests",
+            module: undefined,
+            provider: undefined,
+            outputDir: "/tmp/test",
+        });
+        assert.equal(genResult.errors.length, 0, `No errors: ${genResult.errors.join(", ")}`);
+        assert.ok(genResult.files.length >= 82, `At least 82 test files, got ${genResult.files.length}`);
+    });
+    it("generates for specific module", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const genResult = await generate(result.value, adapters, {
+            language: "typescript",
+            type: "all",
+            module: "billing",
+            provider: undefined,
+            outputDir: "/tmp/test",
+        });
+        assert.ok(genResult.files.some((f) => f.path.includes("billing")));
+    });
+    it("generates for specific adapter", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const genResult = await generate(result.value, adapters, {
+            language: "typescript",
+            type: "adapters",
+            module: "payments",
+            provider: "stripe",
+            outputDir: "/tmp/test",
+        });
+        assert.ok(genResult.files.some((f) => f.path.includes("stripe")));
+    });
+});
+describe("type utilities", () => {
+    it("pascalCase converts correctly", () => {
+        assert.equal(pascalCase("billing"), "Billing");
+        assert.equal(pascalCase("user_management"), "UserManagement");
+        assert.equal(pascalCase("api-keys"), "ApiKeys");
+    });
+    it("camelCase converts correctly", () => {
+        assert.equal(camelCase("billing"), "billing");
+        assert.equal(camelCase("user_management"), "userManagement");
+        assert.equal(camelCase("api-keys"), "apiKeys");
+    });
+    it("snakeCase converts correctly", () => {
+        assert.equal(snakeCase("billing"), "billing");
+        assert.equal(snakeCase("userManagement"), "user_management");
+        assert.equal(snakeCase("api-keys"), "api_keys");
+    });
+    it("mapType converts correctly", () => {
+        assert.equal(mapType("string", "typescript"), "string");
+        assert.equal(mapType("number", "rust"), "f64");
+        assert.equal(mapType("boolean", "python"), "bool");
+        assert.equal(mapType("string[]", "typescript"), "string[]");
+        assert.equal(mapType("string?", "typescript"), "string | undefined");
+    });
+    it("inferType infers correctly", () => {
+        assert.equal(inferType("id", "typescript"), "string");
+        assert.equal(inferType("user_id", "typescript"), "string");
+        assert.equal(inferType("created_at", "typescript"), "Timestamp");
+        assert.equal(inferType("is_active", "typescript"), "boolean");
+        assert.equal(inferType("amount", "typescript"), "unknown");
+    });
+});

package/dist/generators/index.js

@@ -0,0 +1,3 @@
+export { mapType, pascalCase, camelCase, snakeCase, kebabCase, createTemplateData, TYPE_MAPPINGS, } from "./types.js";
+export { registerGenerator, getGenerator, getAvailableLanguages, generate, generateAndWrite, filterModules, filterAdapters, } from "./engine.js";
+export { renderTemplate } from "./render.js";

package/dist/generators/prototype/index.js

@@ -0,0 +1,242 @@
+import { pascalCase, camelCase } from "../types.js";
+export function generatePrototype(catalog, adapters, options) {
+    const files = [];
+    const errors = [];
+    try {
+        files.push(generatePackageJson(options, adapters));
+        files.push(generateTsConfig());
+        files.push(generateGitignore());
+        files.push(generateReadme(options, adapters));
+        files.push(generateEnvExample(adapters));
+        files.push(generateConfig(options, adapters, catalog));
+        files.push(generateEntryPoint(options, adapters, catalog));
+    }
+    catch (error) {
+        errors.push(`Failed to generate prototype: ${error instanceof Error ? error.message : error}`);
+    }
+    return { files, errors };
+}
+function generatePackageJson(options, adapters) {
+    const dependencies = {};
+    const devDependencies = {
+        "typescript": "^5.0.0",
+        "@types/node": "^20.0.0",
+    };
+    for (const adapterName of Object.values(options.adapters)) {
+        const adapter = adapters.find((a) => a.name === adapterName);
+        if (adapter) {
+            const pkg = getAdapterPackage(adapterName);
+            if (pkg) {
+                dependencies[pkg.name] = pkg.version;
+            }
+        }
+    }
+    const packageJson = {
+        name: options.name,
+        version: "1.0.0",
+        type: "module",
+        scripts: {
+            build: "tsc",
+            dev: "tsx src/index.ts",
+        },
+        dependencies,
+        devDependencies,
+    };
+    return {
+        path: "package.json",
+        content: JSON.stringify(packageJson, null, 2) + "\n",
+    };
+}
+function generateTsConfig() {
+    const tsConfig = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            outDir: "dist",
+            rootDir: "src",
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ["src/**/*.ts"],
+    };
+    return {
+        path: "tsconfig.json",
+        content: JSON.stringify(tsConfig, null, 2) + "\n",
+    };
+}
+function generateGitignore() {
+    return {
+        path: ".gitignore",
+        content: `node_modules/
+dist/
+.env
+*.log
+`,
+    };
+}
+function generateReadme(options, adapters) {
+    const moduleList = options.modules.map((m) => `- ${m}`).join("\n");
+    const adapterList = Object.entries(options.adapters)
+        .map(([module, adapter]) => `- ${module}: ${adapter}`)
+        .join("\n");
+    return {
+        path: "README.md",
+        content: `# ${options.name}
+
+Generated scaffold from Engineering Blueprinter contracts.
+
+## Modules
+
+${moduleList}
+
+## Adapters
+
+${adapterList}
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run build
+npm run dev
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+src/
+├── interfaces/     # TypeScript interfaces from contracts
+├── adapters/       # Adapter implementations (fill in TODOs)
+├── config/         # Adapter configuration
+└── index.ts        # Entry point
+\`\`\`
+
+## Next Steps
+
+1. Fill in adapter implementations in \`src/adapters/\`
+2. Configure environment variables in \`.env\`
+3. Implement business logic in \`src/index.ts\`
+`,
+    };
+}
+function generateEnvExample(adapters) {
+    const lines = ["# Environment Variables", ""];
+    for (const adapter of adapters) {
+        lines.push(`# ${adapter.description || adapter.name}`);
+        for (const field of adapter.config.required) {
+            if (field.secret) {
+                lines.push(`${field.name.toUpperCase()}=your_${field.name}_here`);
+            }
+        }
+        lines.push("");
+    }
+    return {
+        path: ".env.example",
+        content: lines.join("\n"),
+    };
+}
+function generateConfig(options, adapters, catalog) {
+    const lines = [
+        "// Adapter configuration",
+        "// Fill in your API keys in .env file",
+        "",
+    ];
+    const imports = [];
+    const adapterConfigs = [];
+    for (const [module, adapterName] of Object.entries(options.adapters)) {
+        const adapter = adapters.find((a) => a.name === adapterName && a.module === module);
+        if (!adapter)
+            continue;
+        const className = `${pascalCase(adapterName)}Adapter`;
+        const importPath = `../adapters/${module}/${adapterName}`;
+        imports.push(`import { ${className} } from '${importPath}';`);
+        const configFields = adapter.config.required
+            .map((f) => {
+            if (f.secret) {
+                return `  ${f.name}: process.env.${f.name.toUpperCase()}!,`;
+            }
+            return `  ${f.name}: process.env.${f.name.toUpperCase()} || '',`;
+        })
+            .join("\n");
+        adapterConfigs.push(`export const ${module}Adapter = new ${className}({`);
+        adapterConfigs.push(configFields);
+        adapterConfigs.push(`});`);
+        adapterConfigs.push("");
+    }
+    lines.push(...imports);
+    lines.push("");
+    lines.push(...adapterConfigs);
+    return {
+        path: "src/config/adapters.ts",
+        content: lines.join("\n"),
+    };
+}
+function generateEntryPoint(options, adapters, catalog) {
+    const lines = [
+        "// Application entry point",
+        "// Implement your business logic here",
+        "",
+    ];
+    for (const [module, adapterName] of Object.entries(options.adapters)) {
+        const mod = catalog.modules.find((m) => m.name === module);
+        if (!mod)
+            continue;
+        lines.push(`// ${module} functions:`);
+        for (const fn of mod.functions.slice(0, 3)) {
+            lines.push(`//   ${camelCase(fn.name)}(${fn.params.map((p) => p.name).join(', ')})`);
+        }
+        lines.push("");
+    }
+    lines.push("async function main() {");
+    lines.push("  // TODO: Initialize adapters");
+    lines.push("  // TODO: Implement business logic");
+    lines.push("}");
+    lines.push("");
+    lines.push("main().catch(console.error);");
+    lines.push("");
+    return {
+        path: "src/index.ts",
+        content: lines.join("\n"),
+    };
+}
+function getAdapterPackage(adapterName) {
+    const packageMap = {
+        stripe: { name: "stripe", version: "^14.0.0" },
+        paystack: { name: "paystack", version: "^3.0.0" },
+        adyen: { name: "@adyen/api-library", version: "^15.0.0" },
+        redis: { name: "redis", version: "^4.0.0" },
+        memcached: { name: "memjs", version: "^1.3.0" },
+        resend: { name: "resend", version: "^3.0.0" },
+        sendgrid: { name: "@sendgrid/mail", version: "^8.0.0" },
+        twilio: { name: "twilio", version: "^5.0.0" },
+        bullmq: { name: "bullmq", version: "^5.0.0" },
+        sqs: { name: "@aws-sdk/client-sqs", version: "^3.0.0" },
+        algolia: { name: "algoliasearch", version: "^5.0.0" },
+        sentry: { name: "@sentry/node", version: "^8.0.0" },
+        clerk: { name: "@clerk/clerk-sdk-node", version: "^2.0.0" },
+        auth0: { name: "auth0", version: "^4.0.0" },
+        launchdarkly: { name: "launchdarkly-node-server-sdk", version: "^8.0.0" },
+        flagsmith: { name: "flagsmith-nodejs", version: "^3.0.0" },
+        unleash: { name: "@unleash/nextjs", version: "^5.0.0" },
+        mixpanel: { name: "mixpanel", version: "^0.18.0" },
+        segment: { name: "@segment/analytics-node", version: "^2.0.0" },
+        amplitude: { name: "@amplitude/analytics-node", version: "^2.0.0" },
+        sift: { name: "sift", version: "^16.0.0" },
+        bugsnag: { name: "@bugsnag/node", version: "^8.0.0" },
+        pagerduty: { name: "pagerduty", version: "^3.0.0" },
+        cloudinary: { name: "cloudinary", version: "^2.0.0" },
+        zendesk: { name: "node-zendesk", version: "^3.0.0" },
+        hubspot: { name: "@hubspot/api-client", version: "^10.0.0" },
+        linear: { name: "@linear/sdk", version: "^12.0.0" },
+        jira: { name: "jira.js", version: "^4.0.0" },
+        shipengine: { name: "@shipengine/sdk", version: "^2.0.0" },
+        taxjar: { name: "taxjar", version: "^3.0.0" },
+        datadog: { name: "datadog-api-client", version: "^2.0.0" },
+        jaeger: { name: "@opentelemetry/sdk-node", version: "^1.0.0" },
+        plaid: { name: "plaid", version: "^30.0.0" },
+        svix: { name: "svix", version: "^1.0.0" },
+    };
+    return packageMap[adapterName] || null;
+}