@figulus/schema 0.5.0-alpha-dev-2 → 0.5.0-alpha-dev-4

package/.openapi-meta/generator/generation-mode.ts

@@ -0,0 +1,41 @@
+import z from "zod";
+
+export const generationModeIdSchema = z.enum(["openapi-meta", "clean-src"]);
+export type GenerationModeId = z.infer<typeof generationModeIdSchema>;
+
+interface GenerationModeData {
+    topLevelOutputDir: string;
+    successMsg: string;
+    failureMsg: string;
+}
+
+const generationModeMappings: { [Id in GenerationModeId]: GenerationModeData } = {
+    "openapi-meta": {
+        topLevelOutputDir: ".openapi-meta/generated/",
+        successMsg: "✅ Generated OpenAPI spec at",
+        failureMsg: "❌ Failed to generate OpenAPI spec",
+    },
+    "clean-src": {
+        topLevelOutputDir: "src-clean/",
+        successMsg: "✅ Generated clean src",
+        failureMsg: "❌ Failed to generate clean src",
+    },
+}
+
+export class GenerationMode {
+    private data: GenerationModeData;
+
+    constructor(public id: GenerationModeId) {
+        this.data = generationModeMappings[this.id];
+    }
+
+    public getTopLevelOutputDir() {
+        return this.data.topLevelOutputDir;
+    }
+
+    public getCompletionMsg(success: boolean, args?: any[]) {
+        const msg = success ? this.data.successMsg : this.data.failureMsg;
+        const argsStr = args ? ": " + args.join(" ") : "";
+        return msg + argsStr;
+    }
+}

package/.openapi-meta/generator/output/cleaned-src-dir.ts

@@ -0,0 +1,40 @@
+import { OutputFile } from "./output-file.js";
+import { GenerationMode } from "../generation-mode.js";
+import { OutputDir } from "./output-dir.js";
+import { allSrcFiles, SrcFile } from "../src-file.js";
+
+export class CleanedSrcDir extends OutputDir {
+    mode: GenerationMode;
+    private srcFiles: SrcFile[];
+
+    constructor() {
+        super();
+        this.mode = new GenerationMode("clean-src");
+        this.srcFiles = allSrcFiles;
+    }
+
+    private generateCleanedSrcFile(file: SrcFile) {
+        const noOAPIImports = file.getInputFileLines().filter((l) =>
+            !l.includes("extendZodWithOpenApi(z)") &&
+            !l.includes(`from "@asteasolutions/zod-to-openapi"`)
+        );
+        const noGaps = noOAPIImports.filter((l, i) => l.length > 0 || noOAPIImports[i-1].length > 0);
+        const noRefs = noGaps.map((l) => l.replace(/\.openapi\(.*\)/, ""));
+        const noTypes = noRefs.map((l) => l.replace(": RouteConfig", ""));
+        return noTypes.join("\n");
+    }
+
+    public generateFiles(dryRun?: boolean) {
+        this.recreateDir();
+
+        for(const file of this.srcFiles) {
+            const outputFile = new OutputFile(file, this.mode);
+            const content = this.generateCleanedSrcFile(file);
+
+            if(!dryRun) {
+                outputFile.write(content);
+                console.log(`Wrote ${file.id} to ${outputFile.getPath().fullPath}`);
+            } else console.log(content);
+        }
+    }
+}

package/{scripts/fix-openapi-3.1.ts → .openapi-meta/generator/output/lib/fix-generated-openapi.ts}

@@ -1,43 +1,6 @@
-import { parse, stringify } from "yaml";
-import { readFileSync, writeFileSync } from "fs";
-
-const inputPath = process.argv[2];
-const outputPath = process.argv[3] ?? inputPath;
-
-if (!inputPath) {
-  console.error("Usage: npx tsx fix-nullable.ts <input.yaml> [output.yaml]");
-  process.exit(1);
-}
-
-/**
- * Recursively walks a parsed YAML/JSON object and fixes OpenAPI 3.1 schema issues
- * produced by @asteasolutions/zod-to-openapi when generating from Zod schemas.
- *
- * Fixes:
- *
- * 1. Standalone nullable member in anyOf/oneOf/allOf:
- *    { anyOf: [..., { nullable: true }] }
- *    → { anyOf: [..., { type: "null" }] }
- *
- * 2. Sibling nullable on a schema object:
- *    { type: "string", nullable: true }
- *    → { anyOf: [{ type: "string" }, { type: "null" }] }
- *
- * 3. OpenAPI 3.0-style exclusiveMinimum as boolean:
- *    { minimum: 0, exclusiveMinimum: true }
- *    → { exclusiveMinimum: 0 }
- *
- * 4. Zod unions generated as anyOf when they should be oneOf:
- *    { anyOf: [{ $ref: ... }, { $ref: ... }, { type: "string" }] }
- *    → { oneOf: [{ $ref: ... }, { $ref: ... }, { type: "string" }] }
- *    (when items are mutually exclusive: all have different types, or all are refs, etc)
- *
- * All are produced by @asteasolutions/zod-to-openapi when handling z.null(),
- * z.nullable(), z.union(), or numeric constraints in Zod schemas.
- */
-function fixNullable(node: unknown): unknown {
+export function fixGeneratedOpenAPI(node: unknown): unknown {
   if (Array.isArray(node)) {
-    const fixed = node.map(fixNullable);
+    const fixed = node.map(fixGeneratedOpenAPI);
 
     // Pattern 1: replace { nullable: true } entries in anyOf/oneOf/allOf arrays
     // with { type: "null" }
@@ -61,7 +24,7 @@ function fixNullable(node: unknown): unknown {
     // Recurse into all child values first
     const result: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(obj)) {
-      result[key] = fixNullable(value);
+      result[key] = fixGeneratedOpenAPI(value);
     }
 
     // Pattern 2: sibling nullable: true on a schema with a type field
@@ -137,47 +100,3 @@ function fixNullable(node: unknown): unknown {
 
   return node;
 }
-
-const raw = readFileSync(inputPath, "utf-8");
-const parsed = parse(raw);
-const fixed = fixNullable(parsed);
-const output = stringify(fixed, { lineWidth: 0 });
-
-writeFileSync(outputPath, output, "utf-8");
-
-const inputLines = raw.split("\n").length;
-const outputLines = output.split("\n").length;
-
-// Count how many replacements were made by diffing nullable occurrences
-const nullableCountBefore = (raw.match(/nullable:\s*true/g) ?? []).length;
-const nullableCountAfter = (output.match(/nullable:\s*true/g) ?? []).length;
-const fixed_count = nullableCountBefore - nullableCountAfter;
-
-const exclusiveMinBefore = (raw.match(/exclusiveMinimum:\s*true/g) ?? []).length;
-const exclusiveMinAfter = (output.match(/exclusiveMinimum:\s*true/g) ?? []).length;
-const exclusiveMinFixed = exclusiveMinBefore - exclusiveMinAfter;
-
-const anyOfBefore = (raw.match(/anyOf:/g) ?? []).length;
-const anyOfAfter = (output.match(/anyOf:/g) ?? []).length;
-const anyOfToOneOfFixed = anyOfBefore - anyOfAfter;
-
-console.log(`Input:   ${inputPath} (${inputLines} lines)`);
-console.log(`Output:  ${outputPath} (${outputLines} lines)`);
-console.log(`Fixed:   ${fixed_count} nullable: true → type: "null" replacements`);
-console.log(`Fixed:   ${exclusiveMinFixed} exclusiveMinimum: true → numeric replacements`);
-console.log(`Fixed:   ${anyOfToOneOfFixed} anyOf → oneOf conversions`);
-if (nullableCountAfter > 0) {
-  console.warn(
-    `Warning: ${nullableCountAfter} nullable: true occurrences remain — manual review needed`
-  );
-}
-if (exclusiveMinAfter > 0) {
-  console.warn(
-    `Warning: ${exclusiveMinAfter} exclusiveMinimum: true occurrences remain — manual review needed`
-  );
-}
-if (anyOfAfter > 0) {
-  console.log(
-    `ℹ️  ${anyOfAfter} anyOf schemas remain (may be intentional for overlapping unions)`
-  );
-}

package/.openapi-meta/generator/output/openapi-file.ts

@@ -0,0 +1,141 @@
+import { OpenApiGeneratorV3, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import { OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator";
+import { readFileSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import YAML from "yaml";
+import z from "zod";
+import { registerAll } from "../../index.js";
+import { OpenAPIMetaDir } from "./openapi-meta-dir.js";
+import { fixGeneratedOpenAPI } from "./lib/fix-generated-openapi.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const outputDir = path.join(__dirname, "..", "..", "..", "..", "..", "api");
+
+export const openApiFileIdSchema = z.enum(["core", "registry"]);
+export type OpenAPIFileId = z.infer<typeof openApiFileIdSchema>;
+
+function getPackageVersion() {
+  const packageJsonPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..", "..", "..",
+    "package.json"
+);
+  const packageJsonData = readFileSync(packageJsonPath);
+  const parsed = z.object({ version: z.string() }).parse(
+    JSON.parse(packageJsonData.toString())
+);
+  return parsed.version;
+}
+
+interface OpenAPIFileData {
+    fileName: string;
+    document: OpenAPIObjectConfig;
+}
+
+const openApiFileMappings: {
+    [Id in OpenAPIFileId]: OpenAPIFileData
+} = {
+    core: {
+        fileName: "openapi-new",
+        document: {
+            openapi: "3.1.0",
+            info: {
+                title: "Figulus Schema",
+                version: getPackageVersion(),
+                description:
+                    "Schemas and types for the Figulus ecosystem",
+                contact: {
+                    name: "Figulus Project",
+                    url: "https://github.com/figulusproject/figulus",
+                },
+            },
+            servers: [
+                {
+                    url: "http://localhost",
+                    description: "Local Unix socket (connect via /run/figulus/figulus.sock)",
+                },
+            ],
+            tags: [
+                {
+                    name: "health",
+                    description: "Engine and Docker health checks",
+                },
+                {
+                    name: "containers",
+                    description: "Container job execution and lifecycle management",
+                },
+                {
+                    name: "images",
+                    description: "Docker image build and garbage collection",
+                },
+                {
+                    name: "volumes",
+                    description: "Docker volume management",
+                },
+                {
+                    name: "sessions",
+                    description: "Persistent session container management",
+                },
+                {
+                    name: "stacks",
+                    description: "FigStack multi-container orchestration",
+                },
+            ]
+        }
+    },
+    registry: {
+        fileName: "openapi-registry",
+        document: {
+            openapi: "3.1.0",
+            info: {
+                title: "Figulus Registry Schema",
+                version: getPackageVersion(),
+                description:
+                "Schemas and types for the Figulus Registry",
+                contact: {
+                    name: "Figulus Project",
+                    url: "https://github.com/figulusproject/figulus",
+                },
+            },
+            servers: [
+                {
+                    url: "https://github.com/figulusproject/registry",
+                    description: "Official GitHub repository for the registry",
+                },
+            ],
+        }
+    }
+}
+
+export class OpenAPIFile {
+    private data: OpenAPIFileData;
+
+    constructor(public id: OpenAPIFileId) {
+        this.data = openApiFileMappings[this.id];
+    }
+
+    public getPath() {
+        return path.join(outputDir, `${this.data.fileName}.yaml`);
+    }
+
+    public async generate(dryRun?: boolean) {
+        const dir = new OpenAPIMetaDir(this);
+        dir.generateFiles();
+
+        const registry = await registerAll(new OpenAPIRegistry());
+        const generator = new OpenApiGeneratorV3(registry.definitions);
+        const openApiDoc = generator.generateDocument(this.data.document);
+
+        if (openApiDoc.components?.schemas) {
+            openApiDoc.components.schemas = Object.fromEntries(
+                Object.entries(openApiDoc.components.schemas).sort(([a], [b]) => a.localeCompare(b))
+            );
+        }
+
+        const yamlContent = YAML.stringify(fixGeneratedOpenAPI(openApiDoc), { lineWidth: 0 });
+        if(!dryRun) writeFileSync(this.getPath(), yamlContent);
+        else console.log(yamlContent);
+    }
+}

package/.openapi-meta/generator/output/openapi-meta-dir.ts

@@ -0,0 +1,214 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { OpenAPIMappedSchemaIterable } from "../../index.js";
+import { OutputFile } from "./output-file.js";
+import { GenerationMode } from "../generation-mode.js";
+import { OpenAPIFile } from "./openapi-file.js";
+import { OutputDir } from "./output-dir.js";
+import { allSrcFiles, srcDir, SrcFile } from "../src-file.js";
+
+type IterableBase = OpenAPIMappedSchemaIterable<string>;
+
+class OpenAPIMetaDirFile {
+    private srcLines: string[];
+    private refs: IterableBase;
+    private isSchema: boolean;
+    private iterableValueType: string;
+    public names: {
+        keyConst: string;
+        keyType: string;
+        mapping: string;
+        iterable: string;
+    };
+
+    constructor(public srcFile: SrcFile) {
+        this.srcLines = this.srcFile.getInputFileLines();
+
+        this.isSchema = this.srcFile.getType() === "schema";
+        this.iterableValueType = this.isSchema ? "OpenAPIMappedSchemaValue" : "RouteConfig";
+        
+        const camel = this.srcFile.getName("camel");
+        const pascal = this.srcFile.getName("pascal");
+        const oapi = "OpenAPI";
+        this.names = {
+            keyConst: camel + oapi + "KeySchema",
+            keyType: pascal + oapi + "Key",
+            mapping: camel + oapi + "Mappings",
+            iterable: camel + oapi + "Iterable",
+        };
+
+        this.refs = this.getRefs();
+    }
+
+    private getIterableSchemas(): IterableBase {
+        const output: IterableBase = [];
+        let currentConst: string = "";
+        
+        for (const l of this.srcLines) {
+            const isConst = l.includes("export const");
+            const isOpenAPIRef = /\.openapi\("[^"]+"\)/.test(l);
+            if (!isConst && !isOpenAPIRef) continue;
+
+            const matchAndSlice = (matchPhraseStart: string, matchPhraseEnd: string) => {
+                const start = l.slice(l.indexOf(matchPhraseStart) + matchPhraseStart.length);
+                const end = start.slice(0, start.indexOf(matchPhraseEnd) + matchPhraseEnd.length - 1);
+                return end;
+            }
+
+            if (isConst) {
+                const start = l.slice(l.indexOf("export const ") + "export const ".length);
+                const match = start.match(/^([a-zA-Z_$][a-zA-Z0-9_$]*)/);
+                currentConst = match ? match[1] : "";
+                continue;
+            }
+
+            output.push({ key: matchAndSlice(`openapi("`, `"`), obj: currentConst });
+        }
+
+        return output;
+    }
+
+    private getIterablePaths(): IterableBase {
+        const output: IterableBase = [];
+
+        const matchPhraseStart = "export const";
+        const matchPhraseEnd = ": RouteConfig";
+
+        const constNames = this.srcLines.filter((l) => l.startsWith(matchPhraseStart)).map((l) => {
+            const start = l.slice(l.indexOf(matchPhraseStart) + matchPhraseStart.length + 1);
+            const end = start.slice(0, start.indexOf(matchPhraseEnd));
+            return end;
+        });
+
+        constNames.forEach((name) => {
+            output.push({ key: name, obj: name });
+        });
+
+        return output;
+    }
+
+    private getRefs(): IterableBase {
+        if (this.isSchema)
+            return this.getIterableSchemas();
+        return this.getIterablePaths();
+    }
+
+    private generateImports() {
+        const dir = this.srcFile.getInputDir();
+        const dirPath = dir ? `${dir}/` : "";
+        const depth = dir ? (dir.split("/").length + 2) : 2;
+        const relativePrefix = "../".repeat(depth);
+
+        return [
+            `import z from "zod";`,
+            `import { OpenAPIMappedSchemaIterable, OpenAPIMappedSchemaValue } from "${"../".repeat(depth - 1)}index.js";`,
+            this.isSchema ? `` : `import { RouteConfig } from "@asteasolutions/zod-to-openapi";`,
+            `import { ${this.refs.map((v) => v.obj).join(", ")} } from "${relativePrefix + srcDir + dirPath + this.srcFile.getInputFileName()}.js";`,
+        ].filter(Boolean).join("\n");
+    }
+
+    private generateKeySchema() {
+        const prefix = `export const ${this.names.keyConst} = z.enum([\n`;
+        const suffix = `\n]);`;
+        return prefix + this.refs.map((r) => `  "${r.key}",`).join("\n") + suffix;
+    }
+
+    private generateKeyType() {
+        return `type ${this.names.keyType} = z.infer<typeof ${this.names.keyConst}>;`;
+    }
+
+    private generateMappings() {
+        const prefix = `const ${this.names.mapping}: { [key in ${this.names.keyType}]: ${this.iterableValueType} } = {\n`;
+        const suffix = `\n};`;
+        return prefix + this.refs.map((r) => `  ${r.key}: ${r.obj},`).join("\n") + suffix;
+    }
+
+    private generateIterable() {
+        return `export const ${this.names.iterable}: OpenAPIMappedSchemaIterable<${this.iterableValueType}> = ${this.names.keyConst}.options.map((key) => ({\n  key,\n  obj: ${this.names.mapping}[key],\n}));`
+    }
+
+    public generateContent() {
+        const imports = this.generateImports();
+        const keySchema = this.generateKeySchema();
+        const keyType = this.generateKeyType();
+        const mappings = this.generateMappings();
+        const iterable = this.generateIterable();
+
+        return imports + "\n\n" +
+            keySchema + "\n" +
+            keyType + "\n\n" +
+            mappings + "\n\n" +
+            iterable + "\n";
+    }
+}
+
+export class OpenAPIMetaDir extends OutputDir {
+    mode: GenerationMode;
+
+    private srcFiles: SrcFile[];
+    private generatedFiles: {
+        metaDirFile: OpenAPIMetaDirFile,
+        outputFile: OutputFile
+    }[];
+
+    constructor(private openAPIFile: OpenAPIFile) {
+        super();
+        this.mode = new GenerationMode("openapi-meta");
+        this.srcFiles = allSrcFiles.filter((f) => f.isInOpenAPIFile(this.openAPIFile.id));
+        this.generatedFiles = this.srcFiles.map((f) => ({
+            metaDirFile: new OpenAPIMetaDirFile(f),
+            outputFile: new OutputFile(f, this.mode),
+        }));
+    }
+
+    private generateIndex() {
+        const files = this.generatedFiles;
+        
+        const imports = [
+            `import { OpenAPIMappedSchemaIterable, OpenAPIMappedSchemaValue } from "..";\nimport { RouteConfig } from "@asteasolutions/zod-to-openapi";`,
+            ...files.map((f) => {
+                const importName = f.metaDirFile.names.iterable;
+                const dirName = f.outputFile.getPath().innerDir;
+                const fileName = f.metaDirFile.srcFile.getInputFileName() + ".js";
+                return `import { ${importName} } from "./${dirName + fileName}";`;
+            }),
+            "\n"
+        ].join("\n");
+
+        const schemaIterables = () => {
+            const schemaFiles = files.filter((f) => f.metaDirFile.srcFile.getType() === "schema");
+            
+            const prefix = `export const openApiSchemaIterables: OpenAPIMappedSchemaIterable<OpenAPIMappedSchemaValue> = [\n`;
+            const iterableNames = schemaFiles.map((f) => f.metaDirFile.names.iterable);
+            const suffix = `\n];`;
+
+            return prefix + iterableNames.map((n) => `  ...${n},`).join("\n") + suffix;
+        }
+        
+        const pathIterables = () => {
+            const pathFiles = files.filter((f) => f.metaDirFile.srcFile.getType() === "path");
+
+            const prefix = `export const openApiPathIterables: OpenAPIMappedSchemaIterable<RouteConfig> = [\n`;
+            const iterableNames = pathFiles.map((f) => f.metaDirFile.names.iterable);
+            const suffix = `\n];`;
+
+            return prefix + iterableNames.map((n) => `  ...${n},`).join("\n") + suffix;
+        }
+
+        return imports + schemaIterables() + "\n\n" + pathIterables() + "\n";
+    }
+
+    public generateFiles() {
+        this.recreateDir();
+
+        for(const { metaDirFile, outputFile } of this.generatedFiles) {
+            outputFile.write(metaDirFile.generateContent());
+            console.log(`Wrote ${metaDirFile.srcFile.id} to ${outputFile.getPath().fullPath}`);
+        }
+
+        writeFileSync(
+            path.resolve(this.getTopLevelDir() + "index.ts"),
+            this.generateIndex()
+        );
+    }
+}

package/.openapi-meta/generator/output/output-dir.ts

@@ -0,0 +1,16 @@
+import { mkdirSync, rmSync } from "fs";
+import { GenerationMode } from "../generation-mode.js";
+
+export abstract class OutputDir {
+    abstract mode: GenerationMode;
+
+    public getTopLevelDir() {
+        return this.mode.getTopLevelOutputDir();
+    }
+
+    public recreateDir() {
+        const path = this.getTopLevelDir();
+        rmSync(path, { recursive: true, force: true });
+        mkdirSync(path, { recursive: true });
+    }
+}

package/.openapi-meta/generator/output/output-file.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { GenerationMode } from "../generation-mode.js";
+import { SrcFile } from "../src-file.js";
+import path from "node:path";
+
+export class OutputFile {
+    constructor(private src: SrcFile, private mode: GenerationMode) {}
+
+    private isInSubDir() {
+        return this.src.getInputDir() !== undefined;
+    }
+
+    public getPath() {
+        const inputDir = this.src.getInputDir();
+        const innerDir = inputDir ? `${inputDir}/` : "";
+        const topLevelDir = this.mode.getTopLevelOutputDir();
+        const outputDir = topLevelDir + innerDir;
+        const fileName = this.src.getInputFileName() + ".ts";
+        const fullPath = outputDir + fileName;
+        return {
+            innerDir,
+            outputDir: path.resolve(outputDir),
+            fullPath: path.resolve(fullPath),
+        };
+    }
+
+    public write(content: string) {
+        const { outputDir, fullPath } = this.getPath();
+        if(this.isInSubDir())
+            mkdirSync(outputDir, { recursive: true });
+        writeFileSync(fullPath, content);
+    }
+}