@figulus/schema 0.4.0-alpha-dev → 0.5.0-alpha-dev-1

package/scripts/generate-openapi-meta.ts

@@ -0,0 +1,540 @@
+import { OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import z from "zod";
+import { OpenAPIMappedSchemaIterable } from "../.openapi-meta";
+
+const fileSchema = z.enum([
+    "core-entities-figspec",
+    "core-entities-figstack",
+    "core-execute",
+    "core-generic",
+    "core-primitives",
+    "core-volumes",
+    "engine-dry-run",
+    "engine-deprecated-run-request",
+    "engine-health",
+    "engine-images",
+    "engine-response",
+    "engine-sessions",
+    "engine-volumes",
+    "engine-paths-health",
+    "engine-paths-containers",
+    "engine-paths-images",
+    "engine-paths-volumes",
+    "engine-paths-dry-run",
+    "engine-paths-sessions",
+    "engine-paths-stacks",
+    "registry-json-schema",
+    "registry-metadata",
+]);
+
+type File = z.infer<typeof fileSchema>;
+
+const openApiFileSchema = z.enum(["core", "registry"]);
+type OpenAPIFileId = z.infer<typeof openApiFileSchema>;
+
+const fileNames: {
+    [file in File]: {
+        camelCase: string,
+        pascalCase: string,
+        kebabCase: string,
+        type: "schema" | "path",
+        dir: string,
+        filename: string,
+        openApiFileId: OpenAPIFileId,
+    }
+} = {
+    "core-entities-figspec": {
+        camelCase: "coreEntitiesFigSpec",
+        pascalCase: "CoreEntitiesFigSpec",
+        kebabCase: "core-entities-figspec",
+        type: "schema",
+        dir: "core/entities",
+        filename: "figspec",
+        openApiFileId: "core",
+    },
+    "core-entities-figstack": {
+        camelCase: "coreEntitiesFigStack",
+        pascalCase: "CoreEntitiesFigStack",
+        kebabCase: "core-entities-figstack",
+        type: "schema",
+        dir: "core/entities",
+        filename: "figstack",
+        openApiFileId: "core",
+    },
+    "core-execute": {
+        camelCase: "coreExecute",
+        pascalCase: "CoreExecute",
+        kebabCase: "core-execute",
+        type: "schema",
+        dir: "core",
+        filename: "execute",
+        openApiFileId: "core",
+    },
+    "core-generic": {
+        camelCase: "coreGeneric",
+        pascalCase: "CoreGeneric",
+        kebabCase: "core-generic",
+        type: "schema",
+        dir: "core",
+        filename: "generic",
+        openApiFileId: "core",
+    },
+    "core-primitives": {
+        camelCase: "corePrimitives",
+        pascalCase: "CorePrimitives",
+        kebabCase: "core-primitives",
+        type: "schema",
+        dir: "core",
+        filename: "primitives",
+        openApiFileId: "core",
+    },
+    "core-volumes": {
+        camelCase: "coreVolumes",
+        pascalCase: "CoreVolumes",
+        kebabCase: "core-volumes",
+        type: "schema",
+        dir: "core",
+        filename: "volumes",
+        openApiFileId: "core",
+    },
+    "engine-deprecated-run-request": {
+        camelCase: "engineDeprecatedRunRequest",
+        pascalCase: "EngineDeprecatedRunRequest",
+        kebabCase: "engine-deprecated-run-request",
+        type: "schema",
+        dir: "engine/deprecated",
+        filename: "run-request",
+        openApiFileId: "core",
+    },
+    "engine-dry-run": {
+        camelCase: "engineDryRun",
+        pascalCase: "EngineDryDry",
+        kebabCase: "engine-dry-run",
+        type: "schema",
+        dir: "engine",
+        filename: "dry-run",
+        openApiFileId: "core",
+    },
+    "engine-health": {
+        camelCase: "engineHealth",
+        pascalCase: "EngineHealth",
+        kebabCase: "engine-health",
+        type: "schema",
+        dir: "engine",
+        filename: "health",
+        openApiFileId: "core",
+    },
+    "engine-images": {
+        camelCase: "engineImages",
+        pascalCase: "EngineImages",
+        kebabCase: "engine-images",
+        type: "schema",
+        dir: "engine",
+        filename: "images",
+        openApiFileId: "core",
+    },
+    "engine-response": {
+        camelCase: "engineResponse",
+        pascalCase: "EngineResponse",
+        kebabCase: "engine-response",
+        type: "schema",
+        dir: "engine",
+        filename: "response",
+        openApiFileId: "core",
+    },
+    "engine-sessions": {
+        camelCase: "engineSessions",
+        pascalCase: "EngineSessions",
+        kebabCase: "engine-sessions",
+        type: "schema",
+        dir: "engine",
+        filename: "sessions",
+        openApiFileId: "core",
+    },
+    "engine-volumes": {
+        camelCase: "engineVolumes",
+        pascalCase: "EngineVolumes",
+        kebabCase: "engine-volumes",
+        type: "schema",
+        dir: "engine",
+        filename: "volumes",
+        openApiFileId: "core",
+    },
+    "engine-paths-health": {
+        camelCase: "pathsHealth",
+        pascalCase: "PathsHealth",
+        kebabCase: "paths-health",
+        type: "path",
+        dir: "engine/paths",
+        filename: "health",
+        openApiFileId: "core",
+    },
+    "engine-paths-containers": {
+        camelCase: "pathsContainers",
+        pascalCase: "PathsContainers",
+        kebabCase: "paths-containers",
+        type: "path",
+        dir: "engine/paths",
+        filename: "containers",
+        openApiFileId: "core",
+    },
+    "engine-paths-images": {
+        camelCase: "pathsImages",
+        pascalCase: "PathsImages",
+        kebabCase: "paths-images",
+        type: "path",
+        dir: "engine/paths",
+        filename: "images",
+        openApiFileId: "core",
+    },
+    "engine-paths-volumes": {
+        camelCase: "pathsVolumes",
+        pascalCase: "PathsVolumes",
+        kebabCase: "paths-volumes",
+        type: "path",
+        dir: "engine/paths",
+        filename: "volumes",
+        openApiFileId: "core",
+    },
+    "engine-paths-dry-run": {
+        camelCase: "pathsDryRun",
+        pascalCase: "PathsDryRun",
+        kebabCase: "paths-dry-run",
+        type: "path",
+        dir: "engine/paths",
+        filename: "dry-run",
+        openApiFileId: "core",
+    },
+    "engine-paths-sessions": {
+        camelCase: "pathsSessions",
+        pascalCase: "PathsSessions",
+        kebabCase: "paths-sessions",
+        type: "path",
+        dir: "engine/paths",
+        filename: "sessions",
+        openApiFileId: "core",
+    },
+    "engine-paths-stacks": {
+        camelCase: "pathsStacks",
+        pascalCase: "PathsStacks",
+        kebabCase: "paths-stacks",
+        type: "path",
+        dir: "engine/paths",
+        filename: "stacks",
+        openApiFileId: "core",
+    },
+    "registry-json-schema": {
+        camelCase: "registryJsonSchema",
+        pascalCase: "RegistryJsonSchema",
+        kebabCase: "registry-json-schema",
+        type: "schema",
+        dir: "registry",
+        filename: "json-schema",
+        openApiFileId: "registry",
+    },
+    "registry-metadata": {
+        camelCase: "registryMetadata",
+        pascalCase: "RegistryMetadata",
+        kebabCase: "registry-metadata",
+        type: "schema",
+        dir: "registry",
+        filename: "metadata",
+        openApiFileId: "registry",
+    },
+};
+
+function getVersion() {
+  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;
+}
+
+const openApiFiles: {
+    [Id in OpenAPIFileId]: {
+    fileName: string,
+    document: OpenAPIObjectConfig,
+}
+} = {
+    core: {
+        fileName: "openapi-new",
+        document: {
+            openapi: "3.1.0",
+            info: {
+                title: "Figulus Schema",
+                version: getVersion(),
+                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: getVersion(),
+                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",
+                },
+            ],
+        }
+    }
+}
+
+function getName(file: File, casing: "camel"|"pascal"|"kebab") {
+    return fileNames[file][`${casing}Case`];
+}
+
+function getType(file: File) {
+    return fileNames[file].type;
+}
+
+function getDir(file: File) {
+    return fileNames[file].dir || "";
+}
+
+function getFilename(file: File) {
+    return fileNames[file].filename || getName(file, "kebab");
+}
+
+function getOpenAPIFileId(file: File) {
+    return fileNames[file].openApiFileId;
+}
+
+const generatedDirPath = ".openapi-meta/generated/";
+
+type IterableBase = OpenAPIMappedSchemaIterable<string>;
+
+function getFileLines(file: File) {
+    const dir = getDir(file);
+    const dirPath = dir ? `${dir}/` : "";
+    const content = readFileSync(path.resolve(`./src/${dirPath}${getFilename(file)}.ts`));
+    return content.toString().split("\n");
+}
+
+function getFileSrc(file: File): IterableBase {
+    const lines = getFileLines(file);
+    const output: IterableBase = [];
+
+    if (getType(file) === "schema") {
+        let currentConst: string = "";
+
+        for (const l of lines) {
+            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 });
+        }
+    } else {
+        const matchPhraseStart = "export const";
+        const matchPhraseEnd = ": RouteConfig";
+
+        const constNames = lines.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;
+}
+
+function generateKeySchema(file: File, refs: IterableBase) {
+    const prefix = `export const ${getName(file, "camel")}OpenAPIKeySchema = z.enum([\n`;
+    const suffix = `\n]);`;
+    return prefix + refs.map((r) => `  "${r.key}",`).join("\n") + suffix;
+}
+
+function generateKeyType(file: File) {
+    return `type ${getName(file, "pascal")}OpenAPIKey = z.infer<typeof ${getName(file, "camel")}OpenAPIKeySchema>;`
+}
+
+function generateMappings(file: File, refs: IterableBase) {
+    const isSchema = getType(file) === "schema";
+    const valueType = isSchema ? "OpenAPIMappedSchemaValue" : "RouteConfig";
+    const prefix = `const ${getName(file, "camel")}OpenAPIMappings: { [key in ${getName(file, "pascal")}OpenAPIKey]: ${valueType} } = {\n`;
+    const suffix = `\n};`;
+    return prefix + refs.map((r) => `  ${r.key}: ${r.obj},`).join("\n") + suffix;
+}
+
+function generateIterable(file: File) {
+    const isSchema = getType(file) === "schema";
+    const valueType = isSchema ? "OpenAPIMappedSchemaValue" : "RouteConfig";
+    return `export const ${getName(file, "camel")}OpenAPIIterable: OpenAPIMappedSchemaIterable<${valueType}> = ${getName(file, "camel")}OpenAPIKeySchema.options.map((key) => ({\n  key,\n  obj: ${getName(file, "camel")}OpenAPIMappings[key],\n}));`
+}
+
+function generateFile(file: File) {
+    const refs = getFileSrc(file);
+    const isSchema = getType(file) === "schema";
+    const dir = getDir(file);
+    const dirPath = dir ? `${dir}/` : "";
+
+    // Calculate relative path depth: for files in subdirs, we need extra ../
+    // File at .openapi-meta/generated/paths/health.ts needs ../../../src
+    // File at .openapi-meta/generated/health.ts needs ../../src
+    const depth = dir ? (dir.split("/").length + 2) : 2;
+    const relativePrefix = "../".repeat(depth);
+
+    const imports = [
+        `import z from "zod";`,
+        `import { OpenAPIMappedSchemaIterable, OpenAPIMappedSchemaValue } from "${"../".repeat(depth - 1)}index.js";`,
+        isSchema ? `` : `import { RouteConfig } from "@asteasolutions/zod-to-openapi";`,
+        `import { ${refs.map((v) => v.obj).join(", ")} } from "${relativePrefix}src/${dirPath}${getFilename(file)}.js";`,
+    ].filter(Boolean).join("\n");
+
+    const keySchema = generateKeySchema(file, refs);
+    const keyType = generateKeyType(file);
+    const mappings = generateMappings(file, refs);
+    const iterable = generateIterable(file);
+
+    return imports + "\n\n" + keySchema + "\n" + keyType + "\n\n" + mappings + "\n\n" + iterable + "\n";
+}
+
+function generateIndex(files: File[]) {
+    const imports = [
+        `import { OpenAPIMappedSchemaIterable, OpenAPIMappedSchemaValue } from "..";\nimport { RouteConfig } from "@asteasolutions/zod-to-openapi";`,
+        ...files.map((f) => {
+            const dir = getDir(f);
+            const dirPath = dir ? `${dir}/` : "";
+            return `import { ${getName(f, "camel")}OpenAPIIterable } from "./${dirPath}${getFilename(f)}.js";`;
+        }),
+        "\n"
+    ].join("\n");
+
+    const schemaFiles = files.filter((f) => getType(f) === "schema");
+    const schemaIterables = () => {
+        const prefix = `export const openApiSchemaIterables: OpenAPIMappedSchemaIterable<OpenAPIMappedSchemaValue> = [\n`;
+        const suffix = `\n];`;
+        return prefix + schemaFiles.map((f) => `  ...${getName(f, "camel")}OpenAPIIterable,`).join("\n") + suffix;
+    }
+
+    const pathFiles = files.filter((f) => getType(f) === "path");
+    const pathIterables = () => {
+        const prefix = `export const openApiPathIterables: OpenAPIMappedSchemaIterable<RouteConfig> = [\n`;
+        const suffix = `\n];`;
+        return prefix + pathFiles.map((f) => `  ...${getName(f, "camel")}OpenAPIIterable,`).join("\n") + suffix;
+    }
+
+    return imports + schemaIterables() + "\n\n" + pathIterables() + "\n";
+}
+
+function writeFile(file: File, content: string) {
+    const dir = getDir(file);
+    const dirPath = dir ? `${dir}/` : "";
+    const fullPath = generatedDirPath + dirPath + getFilename(file) + ".ts";
+
+    if (dir) {
+        mkdirSync(path.resolve(generatedDirPath + dir), { recursive: true });
+    }
+
+    writeFileSync(path.resolve(fullPath), content);
+}
+
+function generateFiles(openApiFileId: OpenAPIFileId) {
+    rmSync(generatedDirPath, { recursive: true, force: true, });
+    mkdirSync(generatedDirPath, { recursive: true });
+
+    const files = fileSchema.options;
+    const filtered = files.filter((f) => getOpenAPIFileId(f) === openApiFileId);
+
+    for (const file of filtered) {
+        const content = generateFile(file);
+        writeFile(file, content);
+    }
+    writeFileSync(path.resolve(generatedDirPath + "index.ts"), generateIndex(filtered));
+    writeFileSync(path.resolve(generatedDirPath + "data.json"), JSON.stringify(openApiFiles[openApiFileId], null, 2));
+}
+
+function parseArgs() {
+    const args = process.argv;
+    if(args.length < 3)
+        throw new Error("openApiFileId argument is missing!");
+
+    const arg = args[2].toLowerCase();
+    if(!arg.startsWith("--openapifileid="))
+        throw new Error(`Invalid argument provided! Expected '--openApiFileId=', received '${arg}'.`);
+
+    const openApiFileId = openApiFileSchema.parse(
+        arg.replace("--openapifileid=", "")
+    );
+
+    return { openApiFileId };
+}
+
+const { openApiFileId } = parseArgs();
+
+generateFiles(openApiFileId);

package/src/core/entities/figspec.ts

@@ -0,0 +1,94 @@
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { z } from 'zod';
+import { buildExecuteStepSchema, executeMainCmdSchema, executeShutdownCmdSchema, executeStartupCmdSchema, scheduledCmdSchema } from '../execute.js';
+import { installGroupSchema, portMappingSchema } from '../generic.js';
+import { buildVolumeMountSchema, runVolumeMountSchema } from '../volumes.js';
+
+extendZodWithOpenApi(z);
+
+// ---------------------------------------------------------------------------
+// Execute model
+// ---------------------------------------------------------------------------
+
+export const figSpecExecuteSchema = z.object({
+  startup: z.array(executeStartupCmdSchema).optional().describe("Commands that run before main (sync commands block main start)"),
+  main: executeMainCmdSchema,
+  shutdown: z.array(executeShutdownCmdSchema).optional().describe("Commands that run before the container stops"),
+  scheduled: z.array(scheduledCmdSchema).optional(),
+}).openapi("FigSpecExecute");
+export type FigSpecExecute = z.infer<typeof figSpecExecuteSchema>;
+
+// ---------------------------------------------------------------------------
+// Build spec
+// ---------------------------------------------------------------------------
+
+export const figSpecBuildBaseSchema = z.object({
+  schemaVersion: z.string().optional(),
+  specName: z.string().optional(),
+  packagesToInstall: z.array(installGroupSchema).optional(),
+  platform: z.string().optional().describe("Target platform, e.g. \"linux/amd64\" or \"linux/arm64\"").openapi({ example: "linux/amd64" }),
+  env: z.record(z.string(), z.string()).optional().describe("Build-time environment variables"),
+  volumes: z.array(buildVolumeMountSchema).optional(),
+  execute: z.array(buildExecuteStepSchema).optional().describe("Ordered list of RUN instructions; each step is a separate cacheable layer"),
+  workDir: z.string().optional().describe("Working directory inside the image"),
+  user: z.string().optional().describe("User to run build commands as (e.g. \"root\")"),
+}).openapi("FigSpecBuildBase");
+
+export const figSpecBuildStandaloneSchema = figSpecBuildBaseSchema.extend({
+  baseImage: z.string(),
+}).openapi("FigSpecBuildStandalone");
+export type FigSpecBuildStandalone = z.infer<typeof figSpecBuildStandaloneSchema>;
+
+export const figSpecBuildWithBaseSpecSchema = figSpecBuildBaseSchema.extend({
+  baseSpec: z.string(),
+  baseImage: z.string().optional(),
+}).openapi("FigSpecBuildWithBaseSpec");
+export type FigSpecBuildWithBaseSpec = z.infer<typeof figSpecBuildWithBaseSpecSchema>;
+
+export const figSpecBuildSchema = z.union([
+  figSpecBuildStandaloneSchema,
+  figSpecBuildWithBaseSpecSchema,
+]);
+export type FigSpecBuild = z.infer<typeof figSpecBuildSchema>;
+
+// ---------------------------------------------------------------------------
+// Run spec
+// ---------------------------------------------------------------------------
+
+export const figSpecRunSchema = z.object({
+  schemaVersion: z.string().optional(),
+  specName: z.string().optional(),
+  execute: figSpecExecuteSchema,
+  env: z.record(z.string(), z.string()).optional(),
+  secrets: z.record(z.string(), z.string()).optional().describe("Secret references: env_name → \"vault:path#field\""),
+  volumes: z.array(runVolumeMountSchema).optional(),
+  workDir: z.string().optional(),
+  user: z.string().optional(),
+  ports: z.array(portMappingSchema).optional(),
+}).openapi("FigSpecRun");
+export type FigSpecRun = z.infer<typeof figSpecRunSchema>;
+
+// ---------------------------------------------------------------------------
+// Top-level Figspec document
+// ---------------------------------------------------------------------------
+
+export const figSpecBuildInputSchema = z.union([
+  figSpecBuildSchema,
+  z.string(),
+  z.array(z.string()),
+]).openapi("FigSpecBuildInput");
+export type FigSpecBuildInput = z.infer<typeof figSpecBuildInputSchema>;
+
+export const figSpecRunInputSchema = z.union([
+  figSpecRunSchema,
+  z.string(),
+]).openapi("FigSpecRunInput");
+export type FigSpecRunInput = z.infer<typeof figSpecRunInputSchema>;
+
+export const figSpecSchema = z.object({
+  schemaVersion: z.string(),
+  specName: z.string().optional(),
+  build: figSpecBuildInputSchema,
+  run: figSpecRunInputSchema.optional(),
+}).openapi("FigSpec");
+export type FigSpec = z.infer<typeof figSpecSchema>;