@monolayer/sdk 1.2.0-canary.4

package/dist/esm/packages/docker/df.js

@@ -0,0 +1,381 @@
+/* eslint-disable max-lines */
+import { kebabCase } from "case-anything";
+import { writeFileSync } from "fs";
+export class Dockerfile {
+    #lines = [];
+    /**
+     * Merge multiple Dockerfile instances into one.
+     *
+     * Returns a new Dockerfile instance.
+     */
+    static merge(dockerfiles) {
+        const allLines = dockerfiles.flatMap((df) => df.#lines);
+        const dockerfile = new Dockerfile();
+        dockerfile.#lines.push(...allLines);
+        return dockerfile;
+    }
+    constructor(df) {
+        if (df) {
+            this.#lines = df.#lines;
+        }
+    }
+    /**
+     * Instruction that initializes a new build stage and sets the base image for
+     * subsequent instructions.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#from)
+     */
+    FROM(
+    /**
+     * Image name.
+     *
+     * Formats: `<image>`, `<image>[:<tag>]`, `<image>[@<digest>]`
+     */
+    image, options) {
+        const platform = options?.platform
+            ? `--platform=${options?.platform}`
+            : undefined;
+        const as = options?.as ? `AS ${options.as}` : undefined;
+        this.#pushInstruction(["FROM", platform, image, as].filter(filterUndefined).join(" "));
+        return this;
+    }
+    /**
+     * Sets the environment variable `<key>` to the value `<value>`.
+     * This value will be in the environment for all subsequent instructions
+     * in the build stage.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#env)
+     */
+    ENV(key, value, options) {
+        const keyVal = value.match(/^\${.+}$/)
+            ? `${key}=${value}`
+            : `${key}="${value}"`;
+        this.#pushInstruction([buildOption(options), "ENV", keyVal].filter(filterUndefined).join(" "));
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    LABEL(...args) {
+        const pairs = [args[0]]
+            .flatMap((p) => p)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .map((p) => `"${p.key}"="${p.value}"`)
+            .join(" \\\n      ");
+        this.#pushInstruction([buildOption(args[1]), "LABEL", pairs].filter(filterUndefined).join(" "));
+        return this;
+    }
+    /**
+     * Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions
+     * that follow it in the Dockerfile.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#workdir)
+     */
+    WORKDIR(dir, options) {
+        this.#pushInstruction([buildOption(options), "WORKDIR", `${dir}`]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    /**
+     * Execute any commands to create a new layer on top of the current image.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#run)
+     */
+    RUN(command, options) {
+        let base = [buildOption(options), "RUN"].filter(filterUndefined).join(" ");
+        if (options?.mount) {
+            base += ` ${mountOpts(options?.mount)}${Array.isArray(command) ? "" : " \\\n   "}`;
+        }
+        const instruction = `${base} ${Array.isArray(command)
+            ? ["", ...command].join(" \\\n  ").trimStart()
+            : command}`;
+        this.#pushInstruction(instruction);
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    COPY(...args) {
+        this.#fileInstruction(args, [buildOption(args[2]), "COPY"].filter(filterUndefined).join(" "));
+        return this;
+    }
+    CMD(...args) {
+        this.#pushInstruction(`CMD [${args
+            .flatMap((e) => e)
+            .map((e) => `"${e}"`)
+            .join(", ")}]`);
+        return this;
+    }
+    /**
+     * Configures a container that will run as an executable.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#entrypoint)
+     */
+    ENTRYPOINT(executable, parameters) {
+        this.#pushInstruction(`ENTRYPOINT [${[executable, ...(parameters ?? [])].map((e) => `"${e}"`).join(", ")}]`);
+        return this;
+    }
+    /**
+     * Overrides the default shell used for the shell form of commands.
+     *
+     * The default shell on Linux is `["/bin/sh", "-c"]`,
+     * and on Windows is `["cmd", "/S", "/C"]`.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#shell)
+     */
+    SHELL(executable, parameters, options) {
+        this.#pushInstruction([
+            buildOption(options),
+            `SHELL [${[executable, ...(parameters ?? [])].map((e) => `"${e}"`).join(", ")}]`,
+        ]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    EXPOSE(...args) {
+        const portAndProtocol = [args[0]]
+            .flatMap((p) => p)
+            .map((port) => {
+            switch (typeof port) {
+                case "number":
+                case "string":
+                    return String(port);
+                default:
+                    return `${port.port}/${port.protocol}`;
+            }
+        })
+            .join(" ");
+        this.#pushInstruction([buildOption(args[1]), `EXPOSE ${portAndProtocol}`]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    /**
+     * Sets the user name (or UID) and optionally the user group (or GID) to use
+     * as the default user and group for the remainder of the current stage.
+     *
+     * The specified user is used for RUN instructions and at runtime,
+     * runs the relevant `ENTRYPOINT` and `CMD` commands.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#user)
+     */
+    USER(user, options) {
+        this.#pushInstruction([
+            buildOption(options),
+            "USER",
+            `${Object.values(user).filter(filterUndefined).join(":")}`,
+        ]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    /**
+     * Creates a mount point with the specified name and
+     * marks it as holding externally mounted volumes from native host or other containers.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#volume)
+     */
+    VOLUME(names, options) {
+        const volumes = [names]
+            .flatMap((v) => v)
+            .map((v) => `"${v}"`)
+            .join(", ");
+        this.#pushInstruction([buildOption(options), "VOLUME", `[${volumes}]`]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    /**
+     * Sets the system call signal that will be sent to the container to exit.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#stopsignal)
+     */
+    STOPSIGNAL(signal, options) {
+        this.#pushInstruction([buildOption(options), `STOPSIGNAL ${signal}`]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    /**
+     * Defines a variable that users can pass at build-time to the builder
+     * with the docker build command using the `--build-arg <varname>=<value>` flag.
+     *
+     * @see
+     *
+     * [Docker Docs](https://docs.docker.com/engine/reference/builder/#arg)
+     */
+    ARG(name, options) {
+        this.#pushInstruction([
+            buildOption(options),
+            `ARG ${[name, options?.default ? `"${options.default}"` : undefined].filter((c) => c !== undefined).join("=")}`,
+        ]
+            .filter(filterUndefined)
+            .join(" "));
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ADD(...args) {
+        this.#fileInstruction(args, [buildOption(args[2]), "ADD"].filter(filterUndefined).join(" "));
+        return this;
+    }
+    HEALTHCHECK(command, options) {
+        switch (command) {
+            case "NONE":
+                this.#pushInstruction(`HEALTHCHECK NONE`);
+                break;
+            default:
+                this.#pushInstruction([
+                    buildOption(options),
+                    `HEALTHCHECK ${optionsToString(options)}`.trim(),
+                    `CMD ${command}`,
+                ]
+                    .filter(filterUndefined)
+                    .join(" "));
+        }
+        return this;
+    }
+    #fileInstruction(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    args, kind) {
+        const source = args[0];
+        const destination = args[1];
+        const options = args[2];
+        const base = `${kind} ${optionsToString(options)}`.trim();
+        const files = [source, destination].flatMap((s) => s);
+        const withSpaces = files.some((s) => s.includes(" "));
+        if (withSpaces) {
+            this.#pushInstruction(`${base} [ ${files.map((s) => `"${s}"`).join(", ")} ]`);
+        }
+        else {
+            this.#pushInstruction(`${base} ${files.join(" ")}`);
+        }
+    }
+    /**
+     * Adds a comment.
+     */
+    comment(content) {
+        this.#lines.push(`# ${content}`);
+        return this;
+    }
+    /**
+     * Adds a banner comment
+     */
+    banner(content) {
+        this.#lines.push(`# ---------`);
+        this.#lines.push(`# ${content}`);
+        this.#lines.push(`# ---------`);
+        this.blank();
+        return this;
+    }
+    /**
+     * Adds an empty line.
+     */
+    blank() {
+        this.#lines.push("");
+        return this;
+    }
+    /**
+     * Groups instructions by omitting blank lines between them.
+     */
+    group(callback) {
+        this.#blankAfterInstruction = false;
+        callback();
+        this.blank();
+        this.#blankAfterInstruction = true;
+        return this;
+    }
+    /**
+     * Returns the Dockerfile string.
+     */
+    toString() {
+        return this.#lines.join("\n");
+    }
+    /**
+     * Saves the Dockerfile.
+     */
+    save(filePath) {
+        writeFileSync(filePath, this.toString());
+    }
+    /**
+     * Appends the contents of a Dockerfile instance.
+     */
+    append(dockerfile) {
+        this.#lines.push(...dockerfile.#lines);
+        return this;
+    }
+    #blankAfterInstruction = true;
+    /**
+     * Adds an instruction
+     */
+    #pushInstruction(instruction) {
+        this.#lines.push(`${instruction}`);
+        if (this.#blankAfterInstruction) {
+            this.blank();
+        }
+    }
+}
+function mountOpts(mount) {
+    if (mount === undefined) {
+        return "";
+    }
+    return [mount]
+        .flatMap((m) => m)
+        .map((m) => Object.entries(m)
+        .reduce((acc, val) => {
+        if (val[0] === "type") {
+            return acc;
+        }
+        if (typeof val[1] === "string") {
+            acc.push(`${val[0]}=${val[1]}`);
+        }
+        else {
+            acc.push(val[0]);
+        }
+        return acc;
+    }, [`--mount=type=${m.type}`])
+        .join(","))
+        .join(" \\\n    ");
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function optionsToString(opts) {
+    if (opts === undefined) {
+        return "";
+    }
+    return Object.entries(opts)
+        .reduce((acc, val) => {
+        const optionName = kebabCase(val[0]);
+        if (optionName === "on-build") {
+            return acc;
+        }
+        if (typeof val[1] === "boolean") {
+            acc += `--${optionName} `;
+        }
+        else {
+            acc += `--${optionName}=${val[1]} `;
+        }
+        return acc;
+    }, "")
+        .trimEnd();
+}
+function filterUndefined(value) {
+    return value !== undefined;
+}
+function buildOption(options) {
+    return options?.onBuild ? "ONBUILD" : undefined;
+}

package/dist/esm/packages/docker/validator.d.ts

@@ -0,0 +1,7 @@
+import { Dockerfile } from "~docker/df.js";
+/**
+ * Validates a {@link Dockerfile }.
+ *
+ * @throws `Error` if the Dockerfile is not valid.
+ */
+export declare function validate(dw: Dockerfile): boolean;

package/dist/esm/packages/docker/validator.js

@@ -0,0 +1,14 @@
+import { validate as dockerfileValidate } from "dockerfile-utils";
+/**
+ * Validates a {@link Dockerfile }.
+ *
+ * @throws `Error` if the Dockerfile is not valid.
+ */
+export function validate(dw) {
+    const diagnostic = dockerfileValidate(dw.toString());
+    if (diagnostic.length !== 0) {
+        console.dir(diagnostic);
+        throw new Error("Invalid Dockerfile", { cause: diagnostic });
+    }
+    return true;
+}

package/dist/esm/packages/utils/create-file.d.ts

@@ -0,0 +1 @@
+export declare function createFile(filePath: string, content: string, log?: boolean): void;

package/dist/esm/packages/utils/create-file.js

@@ -0,0 +1,11 @@
+import { existsSync, writeFileSync } from "fs";
+import path from "path";
+import color from "picocolors";
+export function createFile(filePath, content, log = true) {
+    const overwritten = existsSync(filePath);
+    writeFileSync(filePath, content);
+    if (log) {
+        const relativePath = path.relative(process.cwd(), filePath);
+        console.log(`${color.green(overwritten ? "overwritten" : "created")} ${relativePath}`);
+    }
+}

package/dist/esm/packages/utils/date-string.d.ts

@@ -0,0 +1 @@
+export declare function dateStringWithMilliseconds(): string;

package/dist/esm/packages/utils/date-string.js

@@ -0,0 +1,8 @@
+export function dateStringWithMilliseconds() {
+    return new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(".", "")
+        .replace("T", "")
+        .replace("Z", "");
+}

package/dist/esm/packages/utils/exception.d.ts

@@ -0,0 +1 @@
+export declare function isErrnoException(error: unknown): error is NodeJS.ErrnoException;

package/dist/esm/packages/utils/exception.js

@@ -0,0 +1,4 @@
+export function isErrnoException(error) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return error instanceof Error && typeof error.code === "string";
+}

package/dist/esm/packages/utils/hash-value.d.ts

@@ -0,0 +1,16 @@
+export declare function hashValue(value: string): string;
+interface HashDigestOptions {
+    /**
+     * Length of the digest to generate.
+     *
+     * @default 8
+     */
+    length: number;
+}
+/**
+ * Returns a hex digest of a string.
+ * @param value String to generate a digest.
+ * @param options {@link HashDigestOptions}
+ */
+export declare function hashDigest(value: string, options?: HashDigestOptions): import("effect/Effect").Effect<string, never, never>;
+export {};

package/dist/esm/packages/utils/hash-value.js

@@ -0,0 +1,20 @@
+import { gen, succeed } from "effect/Effect";
+import { createHash } from "node:crypto";
+export function hashValue(value) {
+    const hash = createHash("sha256");
+    hash.update(value);
+    return hash.digest("hex").substring(0, 8);
+}
+/**
+ * Returns a hex digest of a string.
+ * @param value String to generate a digest.
+ * @param options {@link HashDigestOptions}
+ */
+export function hashDigest(value, options) {
+    return gen(function* () {
+        const hash = createHash("sha256");
+        hash.update(value);
+        const digest = hash.digest("hex").substring(0, options?.length ?? 8);
+        return yield* succeed(digest);
+    });
+}

package/dist/esm/packages/utils/import-default.d.ts

@@ -0,0 +1 @@
+export declare function importDefault(path: string): import("effect/Effect").Effect<any, NodeJS.ErrnoException | import("effect/Cause").UnknownException, never>;

package/dist/esm/packages/utils/import-default.js

@@ -0,0 +1,10 @@
+import { gen } from "effect/Effect";
+import { importFile } from "./import-file.js";
+export function importDefault(path) {
+    return gen(function* () {
+        const imported = yield* importFile(path);
+        return imported.default && imported.default.default
+            ? imported.default.default
+            : imported.default;
+    });
+}

package/dist/esm/packages/utils/import-file.d.ts

@@ -0,0 +1,8 @@
+import type { UnknownException } from "effect/Cause";
+/**
+ * Dynamically imports a module from the specified path.
+ *
+ * @param path path to file to import.
+ * @typeParam T The expected type of the imported module. Default: `any`
+ */
+export declare const importFile: <T = any>(path: string) => import("effect/Effect").Effect<T, NodeJS.ErrnoException | UnknownException, never>;

package/dist/esm/packages/utils/import-file.js

@@ -0,0 +1,13 @@
+import { tryPromise } from "effect/Effect";
+import { isErrnoException } from "./exception.js";
+/**
+ * Dynamically imports a module from the specified path.
+ *
+ * @param path path to file to import.
+ * @typeParam T The expected type of the imported module. Default: `any`
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const importFile = (path) => tryPromise({
+    try: () => import(path),
+    catch: (e) => (isErrnoException(e) ? e : e),
+});

package/dist/esm/packages/utils/log-with-spinner.d.ts

@@ -0,0 +1 @@
+export declare function logWithSpinner(msg: string, fn: () => Promise<void>): Promise<void>;

package/dist/esm/packages/utils/log-with-spinner.js

@@ -0,0 +1,17 @@
+import ora from "ora";
+import color from "picocolors";
+export async function logWithSpinner(msg, fn) {
+    const spinner = ora();
+    spinner.start(msg);
+    const start = performance.now();
+    try {
+        await fn();
+        const end = performance.now();
+        const milliseconds = Number(end - start).toFixed(3);
+        spinner.succeed(`${msg} ${color.gray(`(${milliseconds}ms)`)}`);
+    }
+    catch (e) {
+        spinner.fail();
+        throw e;
+    }
+}

package/dist/esm/packages/utils/path.d.ts

@@ -0,0 +1,2 @@
+import { Effect } from "effect";
+export declare function pathExists(filePath: string): Effect.Effect<boolean, import("effect/Cause").UnknownException, never>;

package/dist/esm/packages/utils/path.js

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { stat } from "fs/promises";
+export function pathExists(filePath) {
+    return Effect.tryPromise(async () => {
+        try {
+            await stat(filePath);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+        return true;
+    });
+}

package/dist/esm/packages/utils/playground.d.ts

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

package/dist/esm/packages/utils/playground.js

@@ -0,0 +1,11 @@
+async function main() {
+    const filePath = "./2323.js";
+    return await import(filePath);
+}
+main()
+    .then((r) => console.dir(r, { depth: null }))
+    .catch((e) => {
+    console.log("ERROR", e instanceof Error);
+    console.dir(e, { depth: null });
+});
+export {};

package/dist/esm/scaffolding/add-env-var.d.ts

@@ -0,0 +1,6 @@
+export declare function addEnvVar(name: string, value: string): Promise<void>;
+export declare function updateDotenvFile(vars?: {
+    name: string;
+    value: string;
+}[]): Promise<void>;
+export declare function dotenvFile(): Promise<string>;

package/dist/esm/scaffolding/add-env-var.js

@@ -0,0 +1,57 @@
+// ML_PG_KLAMP_DB_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/klamp-db"
+import { createReadStream, existsSync, writeFileSync } from "fs";
+import ora from "ora";
+import path from "path";
+import { cwd } from "process";
+import readline from "readline";
+export async function addEnvVar(name, value) {
+    const spinner = ora();
+    spinner.start("Adding environment variable to .env.local");
+    await updateDotenvFile([
+        {
+            name,
+            value,
+        },
+    ]);
+    spinner.succeed();
+}
+export async function updateDotenvFile(vars = []) {
+    const envFilePath = path.join(cwd(), ".env.local");
+    if (!existsSync(envFilePath)) {
+        writeFileSync(envFilePath, vars
+            .map((v) => {
+            return `${v.name}="${v.value}"`;
+        })
+            .join("\n"));
+        return;
+    }
+    const newContent = [];
+    const file = readline.createInterface({
+        input: createReadStream(".env.local"),
+        output: process.stdout,
+        terminal: false,
+    });
+    const keys = vars.reduce((acc, val) => {
+        acc.push([val.name, new RegExp(`^${val.name}`), val.value]);
+        return acc;
+    }, []);
+    file.on("line", (line) => {
+        const idx = keys.findIndex((key) => line.trim().match(key[1]));
+        if (idx !== -1) {
+            const match = keys.splice(idx, 1)[0];
+            newContent.push(`${match[0]}="${match[2]}"`);
+        }
+        else {
+            newContent.push(line);
+        }
+    });
+    file.on("close", () => {
+        for (const key of keys) {
+            newContent.push(`${key[0]}="${key[2]}"`);
+        }
+        writeFileSync(envFilePath, newContent.join("\n"));
+    });
+}
+export async function dotenvFile() {
+    return ".env.local";
+}

package/dist/esm/scaffolding/add-import.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Adds a named import to a TypeScript file.
+ *
+ * @param filePath The path to the file to modify.
+ * @param moduleSpecifier The module to import from (e.g., "react").
+ * @param namedImport The named import to add (e.g., "useState").
+ */
+export declare function addImport(filePath: string, moduleSpecifier: string, namedImport: string): Promise<void>;
+/**
+ * Adds a named import to a TypeScript file.
+ *
+ * @param filePath The path to the file to modify.
+ * @param moduleSpecifier The module to import from (e.g., "react").
+ * @param defaultImport The default import to add.
+ */
+export declare function addDefaultImport(filePath: string, moduleSpecifier: string, defaultImport: string): Promise<void>;