@mcoda/generators 0.1.9 → 0.1.12

package/dist/__tests__/Generators.test.js

@@ -1,11 +1,13 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
 import { Index } from "../index.js";
 import { DocsScaffolder } from "../scaffolding/docs/DocsScaffolder.js";
 import { WorkspaceScaffolder } from "../scaffolding/workspace/WorkspaceScaffolder.js";
 import { GlobalScaffolder } from "../scaffolding/global/GlobalScaffolder.js";
 import { GenerateTypes } from "../openapi/generateTypes.js";
 import { ValidateSchema } from "../openapi/validateSchema.js";
+import { ValidateSqlSchema } from "../sql/validateSchema.js";
 describe("generators shells", () => {
     it("exports scaffolders and generators", () => {
         assert.ok(new Index());
@@ -14,5 +16,128 @@ describe("generators shells", () => {
         assert.ok(new GlobalScaffolder());
         assert.ok(new GenerateTypes());
         assert.ok(new ValidateSchema());
+        assert.ok(new ValidateSqlSchema());
+    });
+});
+describe("DocsScaffolder deployment blueprint", () => {
+    it("generates deterministic artifacts with ports and env mapping", () => {
+        const scaffolder = new DocsScaffolder();
+        const sds = [
+            "# SDS",
+            "We use MySQL for persistence.",
+            "Redis is used for caching.",
+        ].join("\n");
+        const openapi = [
+            "openapi: 3.1.0",
+            "info:",
+            "  title: Demo",
+            "  version: 1.0.0",
+            "servers:",
+            "  - url: http://localhost:8080",
+            "paths:",
+            "  /health:",
+            "    get:",
+            "      operationId: getHealth",
+            "      responses:",
+            "        '200':",
+            "          description: ok",
+        ].join("\n");
+        const result = scaffolder.generateDeploymentBlueprint({
+            sdsContent: sds,
+            openapiContent: openapi,
+            outputDir: "/tmp/deploy",
+            serviceName: "sample-service",
+        });
+        assert.equal(result.port, 8080);
+        assert.ok(result.services.includes("mysql"));
+        assert.ok(result.services.includes("redis"));
+        const compose = result.files.find((file) => path.basename(file.path) === "docker-compose.yml");
+        assert.ok(compose);
+        assert.match(compose?.content ?? "", /\$\{SERVICE_PORT\}:\$\{SERVICE_PORT\}/);
+        const envExample = result.files.find((file) => path.basename(file.path) === ".env.example");
+        assert.ok(envExample);
+        assert.match(envExample?.content ?? "", /SERVICE_PORT=8080/);
+        assert.match(envExample?.content ?? "", /DATABASE_URL=/);
+        assert.match(envExample?.content ?? "", /REDIS_URL=/);
+        const envDoc = result.files.find((file) => path.basename(file.path) === "env-secrets.md");
+        assert.ok(envDoc);
+        const kustomization = result.files.find((file) => path.basename(file.path) === "kustomization.yaml");
+        assert.ok(kustomization);
+    });
+});
+describe("ValidateSchema", () => {
+    it("flags empty paths and invalid operation ids", () => {
+        const validator = new ValidateSchema();
+        const spec = [
+            "openapi: 2.0.0",
+            "info:",
+            "  title: Demo",
+            "paths:",
+            "  /health:",
+            "    get:",
+            "      operationId: bad id",
+            "      responses:",
+            "        '200':",
+            "          description: ok",
+        ].join("\n");
+        const result = validator.validateContent(spec);
+        assert.ok(result.errors.some((error) => error.includes("Invalid openapi version")));
+        assert.ok(result.errors.some((error) => error.includes("Invalid operationId")));
+        assert.ok(result.errors.some((error) => error.includes("Missing info.version")));
+    });
+    it("passes for a valid spec", () => {
+        const validator = new ValidateSchema();
+        const spec = [
+            "openapi: 3.1.0",
+            "info:",
+            "  title: Demo",
+            "  version: 1.0.0",
+            "paths:",
+            "  /health:",
+            "    get:",
+            "      operationId: getHealth",
+            "      responses:",
+            "        '200':",
+            "          description: ok",
+            "          content:",
+            "            application/json:",
+            "              schema:",
+            "                $ref: '#/components/schemas/Health'",
+            "components:",
+            "  schemas:",
+            "    Health:",
+            "      type: object",
+        ].join("\n");
+        const result = validator.validateContent(spec);
+        assert.equal(result.errors.length, 0);
+    });
+});
+describe("ValidateSqlSchema", () => {
+    it("flags prose lines and unterminated statements", () => {
+        const validator = new ValidateSqlSchema();
+        const schema = [
+            "CREATE TABLE users (",
+            "  id INTEGER PRIMARY KEY,",
+            "  name TEXT",
+            ")",
+            "This is not SQL",
+        ].join("\n");
+        const result = validator.validateContent(schema);
+        assert.ok(result.errors.length > 0);
+        assert.ok(result.errors.some((error) => error.type === "prose" && error.line === 5));
+        assert.ok(result.errors.some((error) => error.type === "unterminated"));
+    });
+    it("passes for valid SQL", () => {
+        const validator = new ValidateSqlSchema();
+        const schema = [
+            "CREATE TABLE users (",
+            "  id INTEGER PRIMARY KEY,",
+            "  name TEXT NOT NULL",
+            ");",
+            "CREATE INDEX idx_users_name ON users(name);",
+            "PRAGMA foreign_keys = ON;",
+        ].join("\n");
+        const result = validator.validateContent(schema);
+        assert.equal(result.errors.length, 0);
     });
 });

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export declare class Index {
 }
+export { DocsScaffolder } from "./scaffolding/docs/DocsScaffolder.js";
+export { ValidateSqlSchema } from "./sql/validateSchema.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAa,KAAK;CAAG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAa,KAAK;CAAG;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,2 +1,4 @@
 export class Index {
 }
+export { DocsScaffolder } from "./scaffolding/docs/DocsScaffolder.js";
+export { ValidateSqlSchema } from "./sql/validateSchema.js";

package/dist/openapi/validateSchema.d.ts

@@ -1,3 +1,8 @@
 export declare class ValidateSchema {
+    validateContent(raw: string): {
+        doc?: any;
+        errors: string[];
+    };
+    validateDocument(doc: any): string[];
 }
 //# sourceMappingURL=validateSchema.d.ts.map

package/dist/openapi/validateSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateSchema.d.ts","sourceRoot":"","sources":["../../src/openapi/validateSchema.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAc;CAAG"}
+{"version":3,"file":"validateSchema.d.ts","sourceRoot":"","sources":["../../src/openapi/validateSchema.ts"],"names":[],"mappings":"AA4BA,qBAAa,cAAc;IACzB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IAqB7D,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE;CA8ErC"}

package/dist/openapi/validateSchema.js

@@ -1,2 +1,130 @@
+import YAML from "yaml";
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+const OPERATION_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const isPlainObject = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const operationUsesJsonSchema = (operation) => {
+    const contentBlocks = [];
+    const requestContent = operation.requestBody?.content;
+    if (isPlainObject(requestContent))
+        contentBlocks.push(requestContent);
+    const responses = operation.responses;
+    if (isPlainObject(responses)) {
+        for (const response of Object.values(responses)) {
+            const responseContent = response?.content;
+            if (isPlainObject(responseContent))
+                contentBlocks.push(responseContent);
+        }
+    }
+    for (const content of contentBlocks) {
+        for (const [contentType, media] of Object.entries(content)) {
+            if (!contentType.toLowerCase().includes("json"))
+                continue;
+            if (media?.schema)
+                return true;
+        }
+    }
+    return false;
+};
 export class ValidateSchema {
+    validateContent(raw) {
+        if (!raw || !raw.trim()) {
+            return { errors: ["OpenAPI spec is empty."] };
+        }
+        let parsed;
+        try {
+            parsed = YAML.parse(raw);
+        }
+        catch (error) {
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return {
+                    errors: [
+                        `OpenAPI parse failed: ${error.message ?? String(error)}`,
+                    ],
+                };
+            }
+        }
+        return { doc: parsed, errors: this.validateDocument(parsed) };
+    }
+    validateDocument(doc) {
+        const errors = [];
+        if (!isPlainObject(doc)) {
+            errors.push("OpenAPI spec is not an object.");
+            return errors;
+        }
+        const version = doc.openapi;
+        if (!version) {
+            errors.push("Missing openapi version.");
+        }
+        else if (typeof version !== "string" || !version.startsWith("3.")) {
+            errors.push(`Invalid openapi version: ${String(version)}.`);
+        }
+        const info = doc.info;
+        if (!isPlainObject(info)) {
+            errors.push("Missing info section.");
+        }
+        else {
+            if (!info.title)
+                errors.push("Missing info.title.");
+            if (!info.version)
+                errors.push("Missing info.version.");
+        }
+        const paths = doc.paths;
+        if (!isPlainObject(paths)) {
+            errors.push("Missing paths section.");
+        }
+        else if (Object.keys(paths).length === 0) {
+            errors.push("paths section is empty.");
+        }
+        const operationIds = new Map();
+        let hasOperations = false;
+        let hasJsonSchemaUsage = false;
+        if (isPlainObject(paths)) {
+            for (const [pathKey, pathItem] of Object.entries(paths)) {
+                if (!isPlainObject(pathItem)) {
+                    errors.push(`Path item for ${pathKey} must be an object.`);
+                    continue;
+                }
+                const methods = HTTP_METHODS.filter((method) => method in pathItem);
+                if (methods.length === 0) {
+                    errors.push(`Path ${pathKey} has no operations.`);
+                    continue;
+                }
+                for (const method of methods) {
+                    const operation = pathItem[method];
+                    if (!isPlainObject(operation)) {
+                        errors.push(`Operation ${method.toUpperCase()} ${pathKey} must be an object.`);
+                        continue;
+                    }
+                    hasOperations = true;
+                    if (operationUsesJsonSchema(operation)) {
+                        hasJsonSchemaUsage = true;
+                    }
+                    const operationId = operation.operationId;
+                    if (!operationId || typeof operationId !== "string") {
+                        errors.push(`Missing operationId for ${method.toUpperCase()} ${pathKey}.`);
+                    }
+                    else if (/\s/.test(operationId) || !OPERATION_ID_PATTERN.test(operationId)) {
+                        errors.push(`Invalid operationId "${operationId}" for ${method.toUpperCase()} ${pathKey}.`);
+                    }
+                    else if (operationIds.has(operationId)) {
+                        errors.push(`Duplicate operationId "${operationId}" detected.`);
+                    }
+                    else {
+                        operationIds.set(operationId, `${method.toUpperCase()} ${pathKey}`);
+                    }
+                }
+            }
+        }
+        const components = doc.components;
+        const schemas = isPlainObject(components) ? components.schemas : undefined;
+        const schemaCount = isPlainObject(schemas) ? Object.keys(schemas).length : 0;
+        const hasSchemaRefs = typeof doc === "object" && JSON.stringify(doc).includes("#/components/schemas/");
+        if ((hasJsonSchemaUsage || hasSchemaRefs || hasOperations) && schemaCount === 0) {
+            errors.push("Missing components.schemas for JSON payloads.");
+        }
+        return errors;
+    }
 }

package/dist/scaffolding/docs/DocsScaffolder.d.ts

@@ -1,3 +1,30 @@
+export interface DeploymentEnvVar {
+    name: string;
+    value: string;
+    secret: boolean;
+    description: string;
+    usedBy: string[];
+}
+export interface DeploymentBlueprintFile {
+    path: string;
+    content: string;
+}
+export interface DeploymentBlueprintInput {
+    sdsContent: string;
+    openapiContent?: string;
+    outputDir: string;
+    serviceName?: string;
+}
+export interface DeploymentBlueprintOutput {
+    baseDir: string;
+    files: DeploymentBlueprintFile[];
+    env: DeploymentEnvVar[];
+    services: string[];
+    port: number;
+}
 export declare class DocsScaffolder {
+    generateDeploymentBlueprint(input: DeploymentBlueprintInput): DeploymentBlueprintOutput;
+    writeDeploymentBlueprint(output: DeploymentBlueprintOutput): Promise<void>;
+    generateDeploymentBlueprintFiles(input: DeploymentBlueprintInput): Promise<DeploymentBlueprintOutput>;
 }
 //# sourceMappingURL=DocsScaffolder.d.ts.map

package/dist/scaffolding/docs/DocsScaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocsScaffolder.d.ts","sourceRoot":"","sources":["../../../src/scaffolding/docs/DocsScaffolder.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAc;CAAG"}
+{"version":3,"file":"DocsScaffolder.d.ts","sourceRoot":"","sources":["../../../src/scaffolding/docs/DocsScaffolder.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACjC,GAAG,EAAE,gBAAgB,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AA4ZD,qBAAa,cAAc;IACzB,2BAA2B,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB;IA+FjF,wBAAwB,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1E,gCAAgC,CACpC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,yBAAyB,CAAC;CAKtC"}

package/dist/scaffolding/docs/DocsScaffolder.js

@@ -1,2 +1,472 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import YAML from "yaml";
+const DEPENDENCY_DEFINITIONS = [
+    {
+        key: "mysql",
+        name: "mysql",
+        keywords: ["mysql", "mariadb"],
+        image: "mysql:8",
+        port: 3306,
+        appEnv: [
+            {
+                name: "DATABASE_URL",
+                value: "mysql://app:${MYSQL_PASSWORD}@mysql:3306/app",
+                secret: true,
+                description: "MySQL connection string for the application.",
+                usedBy: ["app"],
+            },
+        ],
+        serviceEnv: [
+            {
+                name: "MYSQL_DATABASE",
+                value: "app",
+                secret: false,
+                description: "MySQL database name.",
+                usedBy: ["mysql"],
+            },
+            {
+                name: "MYSQL_USER",
+                value: "app",
+                secret: false,
+                description: "MySQL user name.",
+                usedBy: ["mysql"],
+            },
+            {
+                name: "MYSQL_PASSWORD",
+                value: "change-me",
+                secret: true,
+                description: "MySQL user password.",
+                usedBy: ["mysql"],
+            },
+            {
+                name: "MYSQL_ROOT_PASSWORD",
+                value: "change-me",
+                secret: true,
+                description: "MySQL root password.",
+                usedBy: ["mysql"],
+            },
+        ],
+    },
+    {
+        key: "redis",
+        name: "redis",
+        keywords: ["redis"],
+        image: "redis:7",
+        port: 6379,
+        appEnv: [
+            {
+                name: "REDIS_URL",
+                value: "redis://redis:6379",
+                secret: false,
+                description: "Redis connection URL.",
+                usedBy: ["app"],
+            },
+        ],
+        serviceEnv: [],
+    },
+    {
+        key: "nats",
+        name: "nats",
+        keywords: ["nats"],
+        image: "nats:2",
+        port: 4222,
+        appEnv: [
+            {
+                name: "NATS_URL",
+                value: "nats://nats:4222",
+                secret: false,
+                description: "NATS connection URL.",
+                usedBy: ["app"],
+            },
+        ],
+        serviceEnv: [],
+    },
+    {
+        key: "minio",
+        name: "minio",
+        keywords: ["minio", "object storage", "s3"],
+        image: "minio/minio",
+        port: 9000,
+        command: "server /data",
+        appEnv: [
+            {
+                name: "S3_ENDPOINT",
+                value: "http://minio:9000",
+                secret: false,
+                description: "Object storage endpoint.",
+                usedBy: ["app"],
+            },
+            {
+                name: "S3_ACCESS_KEY",
+                value: "minio",
+                secret: false,
+                description: "Object storage access key.",
+                usedBy: ["app"],
+            },
+            {
+                name: "S3_SECRET_KEY",
+                value: "change-me",
+                secret: true,
+                description: "Object storage secret key.",
+                usedBy: ["app"],
+            },
+        ],
+        serviceEnv: [
+            {
+                name: "MINIO_ROOT_USER",
+                value: "minio",
+                secret: false,
+                description: "MinIO root user.",
+                usedBy: ["minio"],
+            },
+            {
+                name: "MINIO_ROOT_PASSWORD",
+                value: "change-me",
+                secret: true,
+                description: "MinIO root password.",
+                usedBy: ["minio"],
+            },
+        ],
+    },
+    {
+        key: "clickhouse",
+        name: "clickhouse",
+        keywords: ["clickhouse"],
+        image: "clickhouse/clickhouse-server:23",
+        port: 8123,
+        appEnv: [
+            {
+                name: "CLICKHOUSE_URL",
+                value: "http://clickhouse:8123",
+                secret: false,
+                description: "ClickHouse HTTP endpoint.",
+                usedBy: ["app"],
+            },
+        ],
+        serviceEnv: [],
+    },
+];
+const normalizeServiceName = (value) => {
+    const raw = value?.trim().toLowerCase() ?? "";
+    const normalized = raw.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return normalized || "app";
+};
+const parseOpenApi = (raw) => {
+    if (!raw || !raw.trim())
+        return undefined;
+    try {
+        return YAML.parse(raw);
+    }
+    catch {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+};
+const extractPortFromUrl = (url) => {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return undefined;
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
+    try {
+        const parsed = new URL(hasScheme ? trimmed : `http://${trimmed}`);
+        if (parsed.port)
+            return Number(parsed.port);
+        if (hasScheme) {
+            if (parsed.protocol === "https:")
+                return 443;
+            if (parsed.protocol === "http:")
+                return 80;
+        }
+    }
+    catch {
+        const portMatch = trimmed.match(/:(\d{2,5})(?:\/|$)/);
+        if (portMatch)
+            return Number(portMatch[1]);
+    }
+    return undefined;
+};
+const resolveServicePort = (openapiContent) => {
+    const doc = parseOpenApi(openapiContent);
+    const servers = Array.isArray(doc?.servers) ? doc.servers : [];
+    for (const server of servers) {
+        if (!server || typeof server.url !== "string")
+            continue;
+        const port = extractPortFromUrl(server.url);
+        if (port)
+            return port;
+    }
+    return 3000;
+};
+const detectDependencies = (sdsContent) => {
+    const normalized = sdsContent.toLowerCase();
+    return DEPENDENCY_DEFINITIONS.filter((dependency) => dependency.keywords.some((keyword) => normalized.includes(keyword)));
+};
+const remapUsedBy = (env, appName) => ({
+    ...env,
+    usedBy: env.usedBy.map((entry) => (entry === "app" ? appName : entry)),
+});
+const mergeEnvVars = (env) => {
+    const map = new Map();
+    for (const item of env) {
+        const existing = map.get(item.name);
+        if (!existing) {
+            map.set(item.name, { ...item, usedBy: Array.from(new Set(item.usedBy)) });
+            continue;
+        }
+        existing.secret = existing.secret || item.secret;
+        existing.description = existing.description || item.description;
+        existing.value = existing.value || item.value;
+        existing.usedBy = Array.from(new Set([...existing.usedBy, ...item.usedBy]));
+    }
+    return Array.from(map.values()).sort((a, b) => a.name.localeCompare(b.name));
+};
+const envRef = (name) => "${" + name + "}";
+const buildEnvExample = (env) => {
+    const lines = env
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((item) => `${item.name}=${item.value}`);
+    return `${lines.join("\n")}\n`;
+};
+const buildEnvMappingDoc = (env) => {
+    const lines = [
+        "# Deployment Environment Variables",
+        "",
+        "| Name | Secret | Used By | Description |",
+        "| --- | --- | --- | --- |",
+        ...env.map((item) => `| ${item.name} | ${item.secret ? "Yes" : "No"} | ${item.usedBy
+            .slice()
+            .sort()
+            .join(", ")} | ${item.description} |`),
+        "",
+    ];
+    return lines.join("\n");
+};
+const buildDockerCompose = (appName, port, env, dependencies) => {
+    const lines = ['version: "3.9"', "services:"];
+    const appEnv = env.filter((item) => item.usedBy.includes(appName));
+    const depNames = dependencies.map((dep) => dep.name).sort();
+    lines.push(`  ${appName}:`);
+    lines.push(`    image: ${appName}`);
+    lines.push("    ports:");
+    lines.push(`      - "${envRef("SERVICE_PORT")}:${envRef("SERVICE_PORT")}"`);
+    if (appEnv.length > 0) {
+        lines.push("    environment:");
+        for (const item of appEnv) {
+            lines.push(`      ${item.name}: "${envRef(item.name)}"`);
+        }
+    }
+    if (depNames.length > 0) {
+        lines.push("    depends_on:");
+        for (const dep of depNames) {
+            lines.push(`      - ${dep}`);
+        }
+    }
+    const sortedDeps = dependencies.slice().sort((a, b) => a.name.localeCompare(b.name));
+    for (const dependency of sortedDeps) {
+        lines.push(`  ${dependency.name}:`);
+        lines.push(`    image: ${dependency.image}`);
+        if (dependency.command) {
+            lines.push(`    command: ${dependency.command}`);
+        }
+        lines.push("    ports:");
+        lines.push(`      - "${dependency.port}:${dependency.port}"`);
+        if (dependency.serviceEnv.length > 0) {
+            lines.push("    environment:");
+            for (const item of dependency.serviceEnv) {
+                lines.push(`      ${item.name}: "${envRef(item.name)}"`);
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};
+const buildConfigMap = (name, env) => {
+    const entries = env.filter((item) => !item.secret);
+    const lines = [
+        "apiVersion: v1",
+        "kind: ConfigMap",
+        "metadata:",
+        `  name: ${name}`,
+        "data:",
+    ];
+    if (entries.length === 0) {
+        lines.push("  {}");
+    }
+    else {
+        for (const item of entries) {
+            lines.push(`  ${item.name}: "${item.value}"`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};
+const buildSecret = (name, env) => {
+    const entries = env.filter((item) => item.secret);
+    const lines = [
+        "apiVersion: v1",
+        "kind: Secret",
+        "metadata:",
+        `  name: ${name}`,
+        "type: Opaque",
+        "stringData:",
+    ];
+    if (entries.length === 0) {
+        lines.push("  {}");
+    }
+    else {
+        for (const item of entries) {
+            lines.push(`  ${item.name}: "${item.value}"`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};
+const buildDeployment = (name, image, port, configName, secretName) => {
+    const lines = [
+        "apiVersion: apps/v1",
+        "kind: Deployment",
+        "metadata:",
+        `  name: ${name}`,
+        "spec:",
+        "  replicas: 1",
+        "  selector:",
+        "    matchLabels:",
+        `      app: ${name}`,
+        "  template:",
+        "    metadata:",
+        "      labels:",
+        `        app: ${name}`,
+        "    spec:",
+        "      containers:",
+        `        - name: ${name}`,
+        `          image: ${image}`,
+        "          ports:",
+        `            - containerPort: ${port}`,
+        "          envFrom:",
+        "            - configMapRef:",
+        `                name: ${configName}`,
+        "            - secretRef:",
+        `                name: ${secretName}`,
+    ];
+    return `${lines.join("\n")}\n`;
+};
+const buildService = (name, port) => {
+    const lines = [
+        "apiVersion: v1",
+        "kind: Service",
+        "metadata:",
+        `  name: ${name}`,
+        "spec:",
+        "  selector:",
+        `    app: ${name}`,
+        "  ports:",
+        `    - port: ${port}`,
+        `      targetPort: ${port}`,
+    ];
+    return `${lines.join("\n")}\n`;
+};
+const buildKustomization = (resources) => {
+    const lines = [
+        "apiVersion: kustomize.config.k8s.io/v1beta1",
+        "kind: Kustomization",
+        "resources:",
+        ...resources.map((resource) => `  - ${resource}`),
+    ];
+    return `${lines.join("\n")}\n`;
+};
 export class DocsScaffolder {
+    generateDeploymentBlueprint(input) {
+        const serviceName = normalizeServiceName(input.serviceName);
+        const port = resolveServicePort(input.openapiContent);
+        const dependencies = detectDependencies(input.sdsContent);
+        const baseEnv = {
+            name: "SERVICE_PORT",
+            value: String(port),
+            secret: false,
+            description: "Port exposed by the service.",
+            usedBy: [serviceName],
+        };
+        const envVars = [
+            baseEnv,
+            ...dependencies.flatMap((dependency) => dependency.appEnv.map((env) => remapUsedBy(env, serviceName))),
+            ...dependencies.flatMap((dependency) => dependency.serviceEnv),
+        ];
+        const mergedEnv = mergeEnvVars(envVars);
+        const baseDir = input.outputDir;
+        const k8sDir = path.join(baseDir, "k8s");
+        const configName = `${serviceName}-config`;
+        const secretName = `${serviceName}-secrets`;
+        const files = [];
+        files.push({
+            path: path.join(baseDir, "docker-compose.yml"),
+            content: buildDockerCompose(serviceName, port, mergedEnv, dependencies),
+        });
+        files.push({
+            path: path.join(baseDir, ".env.example"),
+            content: buildEnvExample(mergedEnv),
+        });
+        files.push({
+            path: path.join(baseDir, "env-secrets.md"),
+            content: buildEnvMappingDoc(mergedEnv),
+        });
+        files.push({
+            path: path.join(k8sDir, "configmap.yaml"),
+            content: buildConfigMap(configName, mergedEnv),
+        });
+        files.push({
+            path: path.join(k8sDir, "secret.yaml"),
+            content: buildSecret(secretName, mergedEnv),
+        });
+        files.push({
+            path: path.join(k8sDir, `${serviceName}-deployment.yaml`),
+            content: buildDeployment(serviceName, serviceName, port, configName, secretName),
+        });
+        files.push({
+            path: path.join(k8sDir, `${serviceName}-service.yaml`),
+            content: buildService(serviceName, port),
+        });
+        const sortedDeps = dependencies.slice().sort((a, b) => a.name.localeCompare(b.name));
+        for (const dependency of sortedDeps) {
+            files.push({
+                path: path.join(k8sDir, `${dependency.name}-deployment.yaml`),
+                content: buildDeployment(dependency.name, dependency.image, dependency.port, configName, secretName),
+            });
+            files.push({
+                path: path.join(k8sDir, `${dependency.name}-service.yaml`),
+                content: buildService(dependency.name, dependency.port),
+            });
+        }
+        const k8sResources = files
+            .filter((file) => path.dirname(file.path) === k8sDir)
+            .map((file) => path.basename(file.path))
+            .filter((name) => name !== "kustomization.yaml")
+            .sort();
+        files.push({
+            path: path.join(k8sDir, "kustomization.yaml"),
+            content: buildKustomization(k8sResources),
+        });
+        const sortedFiles = files.slice().sort((a, b) => a.path.localeCompare(b.path));
+        return {
+            baseDir,
+            files: sortedFiles,
+            env: mergedEnv,
+            services: [serviceName, ...sortedDeps.map((dep) => dep.name)],
+            port,
+        };
+    }
+    async writeDeploymentBlueprint(output) {
+        const dirs = Array.from(new Set(output.files.map((file) => path.dirname(file.path))));
+        for (const dir of dirs) {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        await Promise.all(output.files.map((file) => fs.writeFile(file.path, file.content, "utf8")));
+    }
+    async generateDeploymentBlueprintFiles(input) {
+        const output = this.generateDeploymentBlueprint(input);
+        await this.writeDeploymentBlueprint(output);
+        return output;
+    }
 }

package/dist/sql/validateSchema.d.ts

@@ -0,0 +1,13 @@
+export type SqlValidationIssueType = "empty" | "prose" | "syntax" | "unterminated";
+export interface SqlValidationIssue {
+    line: number;
+    message: string;
+    type: SqlValidationIssueType;
+    excerpt?: string;
+}
+export declare class ValidateSqlSchema {
+    validateContent(raw: string): {
+        errors: SqlValidationIssue[];
+    };
+}
+//# sourceMappingURL=validateSchema.d.ts.map

package/dist/sql/validateSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateSchema.d.ts","sourceRoot":"","sources":["../../src/sql/validateSchema.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEnF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkED,qBAAa,iBAAiB;IAC5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,kBAAkB,EAAE,CAAA;KAAE;CAmF/D"}

package/dist/sql/validateSchema.js

@@ -0,0 +1,142 @@
+const STATEMENT_START = /^(create|alter|drop|insert|update|delete|select|with|pragma|begin|commit|rollback|end|vacuum|analyze|attach|detach)\b/i;
+const CLAUSE_START = /^(from|where|join|left|right|inner|outer|on|group|order|limit|offset|union|values|set|returning)\b/i;
+const CONTINUATION_START = /^(,|\)|constraint\b|primary\b|foreign\b|unique\b|check\b|references\b|index\b|key\b|generated\b|as\b|collate\b|not\b|null\b)/i;
+const COLUMN_DEF = /^(?:`[^`]+`|"[^"]+"|\[[^\]]+]|[A-Za-z_][\w$]*)(?:\s+[A-Za-z_][\w$]*)(?:\s*\([^)]*\))?/i;
+const TYPE_KEYWORDS = /\b(bigint|int|integer|smallint|tinyint|serial|bigserial|uuid|text|varchar|char|character|boolean|bool|date|timestamp|timestamptz|datetime|time|json|jsonb|blob|real|double|float|numeric|decimal|money|bytea)\b/i;
+const CONSTRAINT_KEYWORDS = /\b(primary|foreign|references|unique|check|default|collate|generated|identity)\b/i;
+const NULL_KEYWORDS = /\bnot\s+null\b|\bnull\b/i;
+const stripComments = (line, state) => {
+    let working = line;
+    if (state.inBlockComment) {
+        const end = working.indexOf("*/");
+        if (end === -1)
+            return "";
+        working = working.slice(end + 2);
+        state.inBlockComment = false;
+    }
+    let blockStart = working.indexOf("/*");
+    while (blockStart !== -1) {
+        const blockEnd = working.indexOf("*/", blockStart + 2);
+        if (blockEnd === -1) {
+            working = working.slice(0, blockStart);
+            state.inBlockComment = true;
+            break;
+        }
+        working = `${working.slice(0, blockStart)} ${working.slice(blockEnd + 2)}`;
+        blockStart = working.indexOf("/*", blockStart);
+    }
+    const lineComment = working.indexOf("--");
+    if (lineComment !== -1) {
+        working = working.slice(0, lineComment);
+    }
+    return working.trim();
+};
+const countParens = (line) => {
+    const stripped = line
+        .replace(/'[^']*'/g, "")
+        .replace(/"[^"]*"/g, "")
+        .replace(/\[[^\]]*]/g, "");
+    return {
+        open: (stripped.match(/\(/g) ?? []).length,
+        close: (stripped.match(/\)/g) ?? []).length,
+    };
+};
+const isSqlLine = (line, inStatement) => {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return true;
+    if (STATEMENT_START.test(trimmed))
+        return true;
+    if (!inStatement)
+        return false;
+    if (CLAUSE_START.test(trimmed))
+        return true;
+    if (CONTINUATION_START.test(trimmed))
+        return true;
+    if (trimmed === ");" || trimmed === ")" || trimmed === "," || trimmed === ";")
+        return true;
+    const normalized = trimmed.replace(/[;,)]\s*$/, "").trim();
+    if (COLUMN_DEF.test(normalized)) {
+        return TYPE_KEYWORDS.test(normalized) || CONSTRAINT_KEYWORDS.test(normalized) || NULL_KEYWORDS.test(normalized);
+    }
+    return false;
+};
+export class ValidateSqlSchema {
+    validateContent(raw) {
+        const errors = [];
+        if (!raw || !raw.trim()) {
+            return { errors: [{ line: 1, type: "empty", message: "SQL schema is empty." }] };
+        }
+        const lines = raw.split(/\r?\n/);
+        const state = { inBlockComment: false, inStatement: false, statementStart: 0, parenDepth: 0 };
+        for (let index = 0; index < lines.length; index += 1) {
+            const lineNumber = index + 1;
+            const rawLine = lines[index] ?? "";
+            const code = stripComments(rawLine, state);
+            if (!code)
+                continue;
+            const trimmed = code.trim();
+            const isStart = STATEMENT_START.test(trimmed);
+            if (!state.inStatement && !isStart) {
+                errors.push({
+                    line: lineNumber,
+                    type: "prose",
+                    message: "Non-SQL content detected.",
+                    excerpt: trimmed.slice(0, 140),
+                });
+                continue;
+            }
+            if (state.inStatement && !isSqlLine(trimmed, true)) {
+                errors.push({
+                    line: lineNumber,
+                    type: "prose",
+                    message: "Non-SQL content detected inside a statement.",
+                    excerpt: trimmed.slice(0, 140),
+                });
+            }
+            if (!state.inStatement && isStart) {
+                state.inStatement = true;
+                state.statementStart = lineNumber;
+            }
+            const parenCount = countParens(code);
+            state.parenDepth += parenCount.open - parenCount.close;
+            if (state.parenDepth < 0) {
+                errors.push({
+                    line: lineNumber,
+                    type: "syntax",
+                    message: "Unexpected closing parenthesis in SQL statement.",
+                    excerpt: trimmed.slice(0, 140),
+                });
+                state.parenDepth = 0;
+            }
+            if (code.includes(";") && state.parenDepth > 0) {
+                errors.push({
+                    line: lineNumber,
+                    type: "syntax",
+                    message: "Statement terminates before closing all parentheses.",
+                    excerpt: trimmed.slice(0, 140),
+                });
+            }
+            if (code.includes(";") && state.parenDepth <= 0) {
+                state.inStatement = false;
+                state.statementStart = 0;
+                state.parenDepth = 0;
+            }
+        }
+        if (state.inStatement) {
+            errors.push({
+                line: state.statementStart || lines.length,
+                type: "unterminated",
+                message: `SQL statement starting at line ${state.statementStart} is missing a terminating semicolon.`,
+            });
+        }
+        if (state.parenDepth > 0) {
+            errors.push({
+                line: lines.length,
+                type: "syntax",
+                message: "SQL statement has unbalanced parentheses.",
+            });
+        }
+        return { errors };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/generators",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "private": false,
   "description": "Internal generators and scaffolding for mcoda.",
   "type": "module",
@@ -26,7 +26,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcoda/shared": "0.1.9"
+    "yaml": "^2.4.2",
+    "@mcoda/shared": "0.1.12"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",