@friehub/blueprint 0.1.0

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { loadCatalogFromRoot } from "./core/load-catalog.js";
+import { registerGenerator } from "./generators/engine.js";
+import { TypeScriptGenerator } from "./generators/typescript/index.js";
+import { parseArguments } from "./utils/args.js";
+import { printHelp } from "./cli/help.js";
+import { checkErrors } from "./cli/commands.js";
+import { handleList, handleInspect, handleGraph, handleSearch, handleResolve, handleAdapters, handleGenerate, handlePrototype, handleSchema, handleBuild, handleVerify, handleImplement, } from "./cli/commands.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve as pathResolve } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getVersion() {
+    try {
+        const pkgPath = pathResolve(__dirname, "../package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+async function main() {
+    registerGenerator(new TypeScriptGenerator());
+    const args = parseArguments(process.argv.slice(2));
+    if (args.unknown.length > 0) {
+        args.unknown.forEach((flag) => console.error(`Unknown option: ${flag}`));
+        process.exit(1);
+    }
+    if (args.help) {
+        printHelp(args.command);
+        return;
+    }
+    if (args.version) {
+        console.log(`@friehub/blueprint@${getVersion()}`);
+        return;
+    }
+    const root = args.root ?? process.cwd();
+    const result = await loadCatalogFromRoot(root, args.strict ? "strict" : "loose");
+    checkErrors(result, args.strict ?? false, args.quiet ?? false);
+    if (!result.value) {
+        console.error("Failed to load catalog.");
+        process.exit(1);
+    }
+    const handlers = {
+        list: handleList,
+        inspect: handleInspect,
+        graph: handleGraph,
+        search: handleSearch,
+        resolve: handleResolve,
+        adapters: handleAdapters,
+        generate: handleGenerate,
+        prototype: handlePrototype,
+        schema: handleSchema,
+        verify: handleVerify,
+        implement: handleImplement,
+        build: handleBuild,
+    };
+    if (args.command === "mcp") {
+        await import("./mcp/server.js");
+        return;
+    }
+    const handler = handlers[args.command] ?? handleBuild;
+    await handler(result, args, root);
+}
+main().catch((error) => {
+    console.error("Unexpected error:", error);
+    process.exit(1);
+});

package/dist/core/adapters/adapter-audit.test.js

@@ -0,0 +1,85 @@
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot } from "../index.js";
+import { loadAdapters } from "./load.js";
+import { validateAdapter } from "./validate.js";
+import { loadSelection, addAdapter } from "./select.js";
+import { resolveAdapters, listAdaptersByModule } from "./resolve.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("adapter system audit", () => {
+    it("loads all adapters without errors", async () => {
+        const { adapters, errors } = await loadAdapters(ADAPTERS_DIR);
+        assert.equal(errors.length, 0, `No load errors: ${errors.join(", ")}`);
+        assert.ok(adapters.length >= 82, `At least 82 adapters, got ${adapters.length}`);
+    });
+    it("every adapter has required fields", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        for (const adapter of adapters) {
+            assert.ok(adapter.name, `${adapter.module}/${adapter.name} has name`);
+            assert.ok(adapter.module, `${adapter.name} has module`);
+            assert.ok(adapter.version, `${adapter.name} has version`);
+            assert.ok(adapter.implements.length > 0, `${adapter.name} implements functions`);
+            assert.ok(adapter.config.required.length > 0, `${adapter.name} has required config`);
+        }
+    });
+    it("every adapter module exists in catalog", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        for (const adapter of adapters) {
+            const mod = result.value.modules.find((m) => m.name === adapter.module);
+            assert.ok(mod, `Module ${adapter.module} exists for adapter ${adapter.name}`);
+        }
+    });
+    it("validates all adapters against their contracts", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        let totalErrors = 0;
+        for (const adapter of adapters) {
+            const validation = validateAdapter(adapter, result.value);
+            const errors = validation.issues.filter((i) => i.severity === "error");
+            totalErrors += errors.length;
+        }
+        assert.equal(totalErrors, 0, `No validation errors across all adapters`);
+    });
+    it("lists adapters by module correctly", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const byModule = listAdaptersByModule(adapters);
+        assert.ok(byModule.payments, "payments has adapters");
+        assert.ok(byModule.payments.includes("stripe"), "payments has stripe");
+        assert.ok(byModule.payments.includes("paystack"), "payments has paystack");
+        assert.ok(byModule.payments.includes("adyen"), "payments has adyen");
+    });
+    it("adapter selection and resolution works", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        await addAdapter(ROOT, "payments", "stripe");
+        await addAdapter(ROOT, "caching", "redis");
+        const { selection } = await loadSelection(ROOT);
+        const resolution = resolveAdapters(selection, adapters, result.value);
+        assert.equal(resolution.selected.payments, "stripe");
+        assert.equal(resolution.selected.caching, "redis");
+    });
+});
+describe("adapter coverage", () => {
+    it("all 35 modules have at least one adapter", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const byModule = listAdaptersByModule(adapters);
+        const expectedModules = [
+            "payments", "billing", "subscriptions", "invoicing", "donations",
+            "payouts", "chargebacks", "emails", "sms", "notifications",
+            "webhooks", "caching", "storage", "search", "queues",
+            "jobs", "feature_flags", "rate_limiting", "auth", "kyc",
+            "analytics", "web_analytics", "fraud_detection", "error_tracking",
+            "incident_management", "trace_query", "ip_intelligence", "media",
+            "customer_support", "crm_leads", "projects", "tasks",
+            "shipping", "taxation", "fulfillment",
+        ];
+        for (const module of expectedModules) {
+            assert.ok(byModule[module], `${module} has adapters`);
+            assert.ok(byModule[module].length >= 2, `${module} has at least 2 adapters`);
+        }
+    });
+});

package/dist/core/adapters/adapter.test.js

@@ -0,0 +1,66 @@
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot } from "../index.js";
+import { loadAdapters, loadAdapter } from "./load.js";
+import { validateAdapter } from "./validate.js";
+import { loadSelection, addAdapter, removeAdapter } from "./select.js";
+import { resolveAdapters, listAdaptersByModule } from "./resolve.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("adapter system", () => {
+    it("loads adapters from directory", async () => {
+        const { adapters, errors } = await loadAdapters(ADAPTERS_DIR);
+        assert.equal(errors.length, 0);
+        assert.ok(adapters.length > 0);
+        assert.ok(adapters.some((a) => a.name === "stripe"));
+        assert.ok(adapters.some((a) => a.name === "redis"));
+        assert.ok(adapters.some((a) => a.name === "bullmq"));
+    });
+    it("loads a single adapter", async () => {
+        const { adapter, error } = await loadAdapter(ADAPTERS_DIR, "payments", "stripe");
+        assert.equal(error, null);
+        assert.notEqual(adapter, null);
+        assert.equal(adapter?.name, "stripe");
+        assert.equal(adapter?.module, "payments");
+    });
+    it("returns error for missing adapter", async () => {
+        const { adapter, error } = await loadAdapter(ADAPTERS_DIR, "payments", "nonexistent");
+        assert.equal(adapter, null);
+        assert.ok(error?.includes("not found"));
+    });
+    it("validates adapter against contract", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const { adapter } = await loadAdapter(ADAPTERS_DIR, "payments", "stripe");
+        assert.notEqual(adapter, null);
+        const validation = validateAdapter(adapter, result.value);
+        assert.ok(validation.issues.length >= 0);
+        assert.ok(typeof validation.valid === "boolean");
+    });
+    it("lists adapters by module", async () => {
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const byModule = listAdaptersByModule(adapters);
+        assert.ok(byModule.payments);
+        assert.ok(byModule.caching);
+        assert.ok(byModule.queues);
+        assert.ok(byModule.payments.includes("stripe"));
+    });
+    it("adds and removes adapter selection", async () => {
+        const { selection: afterAdd, error: addError } = await addAdapter(ROOT, "payments", "stripe");
+        assert.equal(addError, null);
+        assert.equal(afterAdd.adapters.payments, "stripe");
+        const { selection: afterRemove, error: removeError } = await removeAdapter(ROOT, "payments");
+        assert.equal(removeError, null);
+        assert.equal(afterRemove.adapters.payments, undefined);
+    });
+    it("resolves adapters with validation", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const { adapters } = await loadAdapters(ADAPTERS_DIR);
+        const { selection } = await loadSelection(ROOT);
+        const resolution = resolveAdapters(selection, adapters, result.value);
+        assert.ok(resolution.selected);
+    });
+});

package/dist/core/adapters/index.js

@@ -0,0 +1,4 @@
+export { loadAdapters, loadAdapter } from "./load.js";
+export { validateAdapter, validateAdapterSelection } from "./validate.js";
+export { loadSelection, saveSelection, addAdapter, removeAdapter, getAdapterForModule, getPrimaryAdapter } from "./select.js";
+export { resolveAdapters, listAdaptersByModule, findAdapter } from "./resolve.js";

package/dist/core/adapters/load.js

@@ -0,0 +1,131 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export async function loadAdapters(adaptersDir) {
+    const adapters = [];
+    const errors = [];
+    if (!(await dirExists(adaptersDir))) {
+        return { adapters, errors };
+    }
+    const modules = await readdir(adaptersDir, { withFileTypes: true });
+    for (const moduleEntry of modules) {
+        if (!moduleEntry.isDirectory() || moduleEntry.name.startsWith("_")) {
+            continue;
+        }
+        const moduleDir = join(adaptersDir, moduleEntry.name);
+        const files = await readdir(moduleDir);
+        for (const file of files) {
+            if (!file.endsWith(".yaml") && !file.endsWith(".yml")) {
+                continue;
+            }
+            const filePath = join(moduleDir, file);
+            try {
+                const content = await readFile(filePath, "utf8");
+                const parsed = parseYaml(content);
+                const adapter = parseAdapterDefinition(parsed, filePath);
+                if (adapter) {
+                    adapters.push(adapter);
+                }
+            }
+            catch (error) {
+                errors.push(`Failed to load ${filePath}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    }
+    return { adapters, errors };
+}
+export async function loadAdapter(adaptersDir, module, provider) {
+    const filePath = join(adaptersDir, module, `${provider}.yaml`);
+    try {
+        const content = await readFile(filePath, "utf8");
+        const parsed = parseYaml(content);
+        const adapter = parseAdapterDefinition(parsed, filePath);
+        if (!adapter) {
+            return { adapter: null, error: `Invalid adapter definition in ${filePath}` };
+        }
+        return { adapter, error: null };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { adapter: null, error: `Adapter not found: ${module}/${provider}` };
+        }
+        return { adapter: null, error: `Failed to load ${filePath}: ${error instanceof Error ? error.message : error}` };
+    }
+}
+function parseAdapterDefinition(data, filePath) {
+    if (!data || typeof data !== "object") {
+        return null;
+    }
+    const obj = data;
+    if (typeof obj.name !== "string" || typeof obj.module !== "string" || typeof obj.version !== "string") {
+        return null;
+    }
+    if (!Array.isArray(obj.implements)) {
+        return null;
+    }
+    const config = parseConfig(obj.config);
+    const adapter = {
+        name: obj.name,
+        module: obj.module,
+        version: obj.version,
+        implements: obj.implements,
+        config,
+    };
+    if (typeof obj.description === "string") {
+        adapter.description = obj.description;
+    }
+    if (Array.isArray(obj.does_not_implement)) {
+        adapter.does_not_implement = obj.does_not_implement;
+    }
+    if (Array.isArray(obj.dependencies)) {
+        adapter.dependencies = parseDependencies(obj.dependencies);
+    }
+    if (typeof obj.metadata === "object" && obj.metadata !== null) {
+        adapter.metadata = obj.metadata;
+    }
+    return adapter;
+}
+function parseConfig(data) {
+    const config = { required: [], optional: [] };
+    if (!data || typeof data !== "object") {
+        return config;
+    }
+    const obj = data;
+    if (Array.isArray(obj.required)) {
+        config.required = obj.required.filter((f) => {
+            if (!f || typeof f !== "object")
+                return false;
+            const field = f;
+            return typeof field.name === "string" && typeof field.type === "string";
+        });
+    }
+    if (Array.isArray(obj.optional)) {
+        config.optional = obj.optional.filter((f) => {
+            if (!f || typeof f !== "object")
+                return false;
+            const field = f;
+            return typeof field.name === "string" && typeof field.type === "string";
+        });
+    }
+    return config;
+}
+function parseDependencies(data) {
+    if (!Array.isArray(data)) {
+        return [];
+    }
+    return data.filter((d) => {
+        if (!d || typeof d !== "object")
+            return false;
+        const dep = d;
+        return typeof dep.module === "string" && typeof dep.purpose === "string";
+    });
+}
+async function dirExists(dir) {
+    try {
+        const s = await stat(dir);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/adapters/resolve.js

@@ -0,0 +1,78 @@
+import { validateAdapter } from "./validate.js";
+export function resolveAdapters(selection, adapters, catalog) {
+    const selected = {};
+    const fallbacks = {};
+    const issues = [];
+    for (const [module, adapterRef] of Object.entries(selection.adapters)) {
+        if (typeof adapterRef === "string") {
+            selected[module] = adapterRef;
+        }
+        else {
+            selected[module] = adapterRef.primary;
+            if (adapterRef.fallback) {
+                fallbacks[module] = adapterRef.fallback;
+            }
+        }
+    }
+    for (const [module, provider] of Object.entries(selected)) {
+        const adapter = adapters.find((a) => a.module === module && a.name === provider);
+        if (!adapter) {
+            issues.push({
+                adapter: provider,
+                module,
+                message: `Adapter "${provider}" not found for module "${module}"`,
+                severity: "error",
+            });
+            continue;
+        }
+        const result = validateAdapter(adapter, catalog);
+        issues.push(...result.issues);
+    }
+    for (const [module, provider] of Object.entries(fallbacks)) {
+        const adapter = adapters.find((a) => a.module === module && a.name === provider);
+        if (!adapter) {
+            issues.push({
+                adapter: provider,
+                module,
+                message: `Fallback adapter "${provider}" not found for module "${module}"`,
+                severity: "warning",
+            });
+        }
+    }
+    for (const module of catalog.modules) {
+        if (!selected[module.name] && module.hardDeps.length > 0) {
+            const hasAdapterSelection = Object.keys(selected).some((m) => module.hardDeps.includes(m) || m === module.name);
+            if (hasAdapterSelection) {
+                issues.push({
+                    adapter: "",
+                    module: module.name,
+                    message: `Module "${module.name}" is required but has no adapter selected`,
+                    severity: "warning",
+                });
+            }
+        }
+    }
+    return { selected, fallbacks, issues };
+}
+export function listAdaptersByModule(adapters) {
+    const byModule = {};
+    for (const adapter of adapters) {
+        const list = byModule[adapter.module];
+        if (list) {
+            list.push(adapter.name);
+        }
+        else {
+            byModule[adapter.module] = [adapter.name];
+        }
+    }
+    for (const module of Object.keys(byModule)) {
+        const list = byModule[module];
+        if (list) {
+            list.sort();
+        }
+    }
+    return byModule;
+}
+export function findAdapter(adapters, module, provider) {
+    return adapters.find((a) => a.module === module && a.name === provider) ?? null;
+}

package/dist/core/adapters/select.js

@@ -0,0 +1,80 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export async function loadSelection(rootDir) {
+    const configPath = join(rootDir, "blueprint.json");
+    try {
+        const content = await readFile(configPath, "utf8");
+        const config = JSON.parse(content);
+        if (!config.adapters || typeof config.adapters !== "object") {
+            return { selection: { adapters: {} }, error: null };
+        }
+        return { selection: { adapters: config.adapters }, error: null };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { selection: { adapters: {} }, error: null };
+        }
+        return { selection: { adapters: {} }, error: `Failed to load selection: ${error instanceof Error ? error.message : error}` };
+    }
+}
+export async function saveSelection(rootDir, selection) {
+    const configPath = join(rootDir, "blueprint.json");
+    try {
+        let config = {};
+        try {
+            const content = await readFile(configPath, "utf8");
+            config = JSON.parse(content);
+        }
+        catch {
+            // File doesn't exist or is invalid, start fresh
+        }
+        config.adapters = selection.adapters;
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+        return null;
+    }
+    catch (error) {
+        return `Failed to save selection: ${error instanceof Error ? error.message : error}`;
+    }
+}
+export async function addAdapter(rootDir, module, provider) {
+    const { selection, error } = await loadSelection(rootDir);
+    if (error) {
+        return { selection, error };
+    }
+    selection.adapters[module] = provider;
+    const saveError = await saveSelection(rootDir, selection);
+    if (saveError) {
+        return { selection, error: saveError };
+    }
+    return { selection, error: null };
+}
+export async function removeAdapter(rootDir, module) {
+    const { selection, error } = await loadSelection(rootDir);
+    if (error) {
+        return { selection, error };
+    }
+    delete selection.adapters[module];
+    const saveError = await saveSelection(rootDir, selection);
+    if (saveError) {
+        return { selection, error: saveError };
+    }
+    return { selection, error: null };
+}
+export function getAdapterForModule(selection, module) {
+    const adapter = selection.adapters[module];
+    if (!adapter) {
+        return null;
+    }
+    return adapter;
+}
+export function getPrimaryAdapter(selection, module) {
+    const adapter = selection.adapters[module];
+    if (!adapter) {
+        return null;
+    }
+    if (typeof adapter === "string") {
+        return adapter;
+    }
+    return adapter.primary;
+}

package/dist/core/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/adapters/validate.js

@@ -0,0 +1,121 @@
+export function validateAdapter(adapter, catalog) {
+    const issues = [];
+    const module = catalog.modules.find((m) => m.name === adapter.module);
+    if (!module) {
+        issues.push({
+            adapter: adapter.name,
+            module: adapter.module,
+            message: `Module "${adapter.module}" not found in catalog`,
+            severity: "error",
+        });
+        return { valid: false, issues };
+    }
+    for (const fn of adapter.implements) {
+        const contractFn = module.functions.find((f) => f.name === fn);
+        if (!contractFn) {
+            const similar = findSimilarFunction(fn, module);
+            const suggestion = similar ? ` Did you mean "${similar}"?` : "";
+            issues.push({
+                adapter: adapter.name,
+                module: adapter.module,
+                message: `Adapter implements "${fn}" but contract does not define it.${suggestion}`,
+                severity: "warning",
+            });
+        }
+    }
+    for (const fn of module.functions) {
+        if (!adapter.implements.includes(fn.name)) {
+            if (adapter.does_not_implement?.includes(fn.name)) {
+                continue;
+            }
+            const similar = findSimilarFunction(fn.name, adapter);
+            const suggestion = similar ? ` Did you mean "${similar}"?` : "";
+            const params = fn.params.map((p) => `${p.name}${p.optional ? "?" : ""}: ${p.type ?? "unknown"}`).join(", ");
+            issues.push({
+                adapter: adapter.name,
+                module: adapter.module,
+                message: `Contract defines "${fn.name}(${params})" but adapter does not implement it.${suggestion}`,
+                severity: "error",
+            });
+        }
+    }
+    for (const dep of adapter.dependencies ?? []) {
+        const depModule = catalog.modules.find((m) => m.name === dep.module);
+        if (!depModule) {
+            issues.push({
+                adapter: adapter.name,
+                module: adapter.module,
+                message: `Adapter depends on "${dep.module}" but it is not in the catalog`,
+                severity: "warning",
+            });
+        }
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+    };
+}
+function findSimilarFunction(target, source) {
+    let names = [];
+    if ("functions" in source && source.functions) {
+        names = source.functions.map((f) => f.name);
+    }
+    else if ("implements" in source && source.implements) {
+        names = source.implements;
+    }
+    const targetLower = target.toLowerCase();
+    for (const name of names) {
+        if (name.toLowerCase() === targetLower)
+            continue;
+        if (name.toLowerCase().includes(targetLower) || targetLower.includes(name.toLowerCase())) {
+            return name;
+        }
+        if (levenshteinDistance(name.toLowerCase(), targetLower) <= 3) {
+            return name;
+        }
+    }
+    return null;
+}
+function levenshteinDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+            else {
+                dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+            }
+        }
+    }
+    return dp[m][n];
+}
+export function validateAdapterSelection(selected, adapters, catalog) {
+    const issues = [];
+    for (const [module, provider] of Object.entries(selected)) {
+        const adapter = adapters.find((a) => a.module === module && a.name === provider);
+        if (!adapter) {
+            const available = adapters.filter((a) => a.module === module).map((a) => a.name);
+            const suggestion = available.length > 0 ? ` Available adapters: ${available.join(", ")}` : "";
+            issues.push({
+                adapter: provider,
+                module,
+                message: `Adapter "${provider}" not found for module "${module}".${suggestion}`,
+                severity: "error",
+            });
+            continue;
+        }
+        const result = validateAdapter(adapter, catalog);
+        issues.push(...result.issues);
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+    };
+}

package/dist/core/catalog.js

@@ -0,0 +1,3 @@
+export function implicitCores(catalog) {
+    return catalog.core.filter((c) => c.implicit);
+}