@alcedocore/cli 0.0.1-rc.0

package/src/commands/init.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+
+describe("Init command", () => {
+  const testDir = path.join(os.tmpdir(), `alcedo-test-init-${Date.now()}`);
+
+  beforeAll(() => {
+    fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("validates slug format correctly", () => {
+    // Test the validation logic used by init command
+    const validSlugs = ["my-plugin", "hello-world", "test123"];
+    const invalidSlugs = ["My Plugin", "my_plugin", "", "UPPERCASE"];
+
+    // The validation function requires lowercase alphanumeric + hyphens
+    const isValid = (slug: string): boolean =>
+      slug.length > 0 && /^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug);
+
+    for (const slug of validSlugs) {
+      expect(isValid(slug)).toBe(true);
+    }
+    for (const slug of invalidSlugs) {
+      expect(isValid(slug)).toBe(false);
+    }
+  });
+
+  it("generates valid plugin directory structure", () => {
+    // Verify the expected directory structure matches what init would create
+    const expectedDirs = ["migrations", "pages"];
+    for (const dir of expectedDirs) {
+      const dirPath = path.join(testDir, dir);
+      fs.mkdirSync(dirPath, { recursive: true });
+      expect(fs.existsSync(dirPath)).toBe(true);
+    }
+
+    // Verify key files that init should generate
+    const expectedFiles = ["manifest.json", "Dockerfile", "server.py"];
+    for (const file of expectedFiles) {
+      const filePath = path.join(testDir, file);
+      // Only test structure, not content — init command generates these via templates
+      if (file === "manifest.json") {
+        fs.writeFileSync(filePath, JSON.stringify({
+          slug: "test-plugin",
+          version: "1.0.0",
+          plugin_type: "dynamic",
+        }));
+      }
+      if (file === "Dockerfile") {
+        fs.writeFileSync(filePath, "FROM python:3.11-slim\n");
+      }
+      if (file === "server.py") {
+        fs.writeFileSync(filePath, 'print("hello")\n');
+      }
+      expect(fs.existsSync(filePath)).toBe(true);
+    }
+  });
+
+  it("generates versioned migration filenames correctly", () => {
+    // Migration filenames follow pattern: YYYYMMDD_<name>.up.sql
+    const date = "20260527";
+    const name = "create_users_table";
+    const upFilename = `${date}_${name}.up.sql`;
+    const downFilename = `${date}_${name}.down.sql`;
+
+    expect(upFilename).toMatch(/^\d{8}_.+\.up\.sql$/);
+    expect(downFilename).toMatch(/^\d{8}_.+\.down\.sql$/);
+  });
+
+  it("generates endpoint handler with correct structure", () => {
+    // Endpoint template generates: slug-safe endpoint path + handler stub
+    const endpointName = "user-data";
+    const expectedMethod = "GET";
+
+    // Simulate the manifest endpoint entry format
+    const endpointEntry = {
+      method: expectedMethod,
+      path: `/${endpointName}`,
+      handler: `${endpointName}_handler`,
+    };
+
+    expect(endpointEntry.path).toBe(`/${endpointName}`);
+    expect(endpointEntry.method).toBe(expectedMethod);
+    expect(endpointEntry.handler).toBeTruthy();
+  });
+});

package/src/commands/init.ts

@@ -0,0 +1,171 @@
+import { Command } from "commander";
+import path from "node:path";
+import fs from "node:fs";
+import {
+    createSpinner,
+    success,
+    error as logError,
+    info,
+} from "../utils/logger";
+import { renderAndWrite } from "../utils/ejs-renderer";
+import { loadConfig } from "../config";
+import readline from "node:readline";
+
+export const initCommand = new Command("init")
+    .argument("<name>", "Plugin project name (e.g., my-plugin)")
+    .option("-l, --language <language>", "Plugin language (python or node)")
+    .description("Scaffold a new plugin project")
+    .action(
+        async (name: string, options: { language?: string }, cmd: Command) => {
+            const config = loadConfig(cmd.optsWithGlobals() as any);
+            const pluginDir = config.pluginDir || process.cwd();
+            const targetDir = path.resolve(pluginDir, name);
+            const slug = slugify(name);
+
+            if (fs.existsSync(targetDir)) {
+                logError(`Directory already exists: ${targetDir}`);
+                process.exit(1);
+            }
+
+            const language = options.language
+                ? parseLanguage(options.language)
+                : await promptLanguage();
+
+            const templatesDir = path.resolve(__dirname, "../../templates");
+
+            const registryUrl = config.registryUrl || "localhost:5000";
+            const data = {
+                name,
+                slug,
+                version: "1.0.0",
+                description: `A new AlcedoCore plugin`,
+                language,
+                registryUrl,
+            };
+
+            const spinner = createSpinner(`Scaffolding plugin: ${name}`);
+
+            try {
+                // Create target directory
+                fs.mkdirSync(targetDir, { recursive: true });
+
+                // Generate files from templates
+                // manifest.json
+                renderAndWrite(
+                    path.join(templatesDir, "plugin", "manifest.json.ejs"),
+                    path.join(targetDir, "manifest.json"),
+                    data,
+                );
+
+                // Dockerfile (language-specific)
+                const dockerTemplate =
+                    language === "python"
+                        ? "Dockerfile.ejs"
+                        : "Dockerfile.node.ejs";
+                renderAndWrite(
+                    path.join(templatesDir, "plugin", dockerTemplate),
+                    path.join(targetDir, "Dockerfile"),
+                    data,
+                );
+
+                // Server stub (language-specific)
+                const serverTemplate =
+                    language === "python" ? "server.py.ejs" : "server.js.ejs";
+                renderAndWrite(
+                    path.join(templatesDir, "plugin", serverTemplate),
+                    path.join(
+                        targetDir,
+                        `server.${language === "python" ? "py" : "js"}`,
+                    ),
+                    data,
+                );
+
+                // .gitignore
+                renderAndWrite(
+                    path.join(templatesDir, "plugin", "gitignore.ejs"),
+                    path.join(targetDir, ".gitignore"),
+                    data,
+                );
+
+                // README.md
+                renderAndWrite(
+                    path.join(templatesDir, "plugin", "README.md.ejs"),
+                    path.join(targetDir, "README.md"),
+                    data,
+                );
+
+                copyGitkeep(templatesDir, targetDir, "migrations");
+                copyGitkeep(templatesDir, targetDir, "pages");
+                copyGitkeep(templatesDir, targetDir, "public");
+
+                spinner.succeed();
+
+                success(`Plugin scaffolded: ${targetDir}`);
+                info(`Next steps:
+      cd ${name}
+      # Edit server.${language === "python" ? "py" : "js"} and manifest.json
+      # Build with: docker build -t ${registryUrl}/${slug}:1.0.0 .`);
+            } catch (err: any) {
+                spinner.fail();
+                logError(`Failed to scaffold plugin: ${err.message}`);
+                process.exit(1);
+            }
+        },
+    );
+
+function promptLanguage(): Promise<"python" | "node"> {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+        rl.question("Select plugin language (python/node): ", (answer) => {
+            rl.close();
+            const lang = answer.trim().toLowerCase();
+            if (lang === "python" || lang === "py") {
+                resolve("python");
+            } else if (
+                lang === "node" ||
+                lang === "nodejs" ||
+                lang === "javascript" ||
+                lang === "js"
+            ) {
+                resolve("node");
+            } else {
+                // Default to python on invalid input, matching hello-world
+                info(`Unknown language "${lang}", defaulting to Python`);
+                resolve("python");
+            }
+        });
+    });
+}
+
+function slugify(name: string): string {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+function copyGitkeep(
+    templateDir: string,
+    targetDir: string,
+    subDir: string,
+): void {
+    const src = path.join(templateDir, "plugin", subDir, ".gitkeep");
+    const dest = path.join(targetDir, subDir, ".gitkeep");
+    if (fs.existsSync(src)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, "");
+    }
+}
+
+function parseLanguage(lang: string): "python" | "node" {
+    const v = lang.trim().toLowerCase();
+    if (v === "python" || v === "py") return "python";
+    if (v === "node" || v === "nodejs" || v === "javascript" || v === "js")
+        return "node";
+    throw new Error(`Unknown language "${lang}". Use "python" or "node".`);
+}

package/src/commands/migrate.ts

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { error as logError } from "../utils/logger";
+import { addMigrationAction } from "./add-migration";
+
+const generateCommand = new Command("generate")
+  .argument("<name>", "Migration name (e.g., create_users_table)")
+  .description("Alias for `alcedo add migration` — generate a versioned SQL migration pair")
+  .action(async (name: string) => {
+    try {
+      await addMigrationAction(name);
+    } catch (err: any) {
+      logError(`Generate failed: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+export const migrateCommand = new Command("migrate")
+  .description("Alias for `alcedo add migration`");
+
+migrateCommand.addCommand(generateCommand);

package/src/commands/proxy.ts

@@ -0,0 +1,206 @@
+import { Command } from "commander";
+import http from "node:http";
+import path from "node:path";
+import { loadConfig } from "../config";
+import {
+    success,
+    error as logError,
+    info,
+    warn,
+    createSpinner,
+} from "../utils/logger";
+
+interface ProxyOptions {
+    port?: string;
+    target?: string;
+    apiKey?: string;
+}
+
+export const proxyCommand = new Command("proxy")
+    .description(
+        "Start a dev proxy that forwards requests to a local dev server",
+    )
+    .option("-p, --port <port>", "Proxy listen port", "3099")
+    .option(
+        "-t, --target <url>",
+        "Target dev server URL (e.g., localhost:8080)",
+        "localhost:3000",
+    )
+    .option("-k, --api-key <key>", "Core API key (or ALCEDO_API_KEY env var)")
+    .action(async (opts: ProxyOptions, cmd: Command) => {
+        const config = loadConfig(cmd.optsWithGlobals() as any);
+        const coreUrl = config.coreUrl || "http://localhost:8080";
+        const pluginDir = path.resolve(config.pluginDir || process.cwd());
+        const slug = path.basename(pluginDir);
+        const apiKey =
+            opts.apiKey || config.apiKey || process.env.ALCEDO_API_KEY || "";
+        const proxyPort = parseInt(opts.port || "3099", 10);
+        const target = opts.target || "localhost:3000";
+
+        if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) {
+            logError(`Invalid proxy port: ${opts.port}`);
+            process.exit(1);
+        }
+
+        const parsedTarget = parseTarget(target);
+
+        const validateSpinner = createSpinner("Validating API key...");
+        const testId = await registerRequest(
+            coreUrl,
+            apiKey || undefined,
+            slug,
+        );
+        if (!testId) {
+            validateSpinner.fail();
+            logError(`Failed to connect to core at ${coreUrl}`);
+            logError(
+                "Make sure the AlcedoCore instance is running and API key is correct",
+            );
+            process.exit(1);
+        }
+        validateSpinner.succeed();
+
+        const server = http.createServer(async (clientReq, clientRes) => {
+            const startTime = Date.now();
+
+            const requestId = await registerRequest(
+                coreUrl,
+                apiKey || undefined,
+                slug,
+            );
+            if (!requestId) {
+                logError("Failed to register request ID with core");
+                clientRes.statusCode = 502;
+                clientRes.setHeader("Content-Type", "text/plain");
+                clientRes.end("Bad Gateway: core unavailable");
+                return;
+            }
+
+            // Clone headers and inject X-Request-ID
+            const headers: Record<string, string> = {};
+            for (const [key, value] of Object.entries(clientReq.headers)) {
+                if (value !== undefined) {
+                    headers[key] = Array.isArray(value)
+                        ? value.join(", ")
+                        : value;
+                }
+            }
+            headers["X-Request-ID"] = requestId;
+            headers["host"] = `${parsedTarget.hostname}:${parsedTarget.port}`;
+
+            const options: http.RequestOptions = {
+                hostname: parsedTarget.hostname,
+                port: parsedTarget.port,
+                path: clientReq.url,
+                method: clientReq.method,
+                headers,
+            };
+
+            const proxyReq = http.request(options, (proxyRes) => {
+                const chunks: Buffer[] = [];
+                proxyRes.on("data", (chunk: Buffer) => chunks.push(chunk));
+                proxyRes.on("end", () => {
+                    const duration = Date.now() - startTime;
+                    const statusCode = proxyRes.statusCode || 0;
+
+                    info(
+                        `  ${statusCode} ${clientReq.method} ${duration}ms ${clientReq.url}`,
+                    );
+
+                    const responseHeaders = { ...proxyRes.headers };
+                    clientRes.writeHead(statusCode, responseHeaders);
+                    clientRes.end(Buffer.concat(chunks));
+                });
+            });
+
+            proxyReq.on("error", (err) => {
+                logError(`Proxy request error: ${err.message}`);
+                if (!clientRes.headersSent) {
+                    clientRes.statusCode = 502;
+                    clientRes.setHeader("Content-Type", "text/plain");
+                    clientRes.end(`Bad Gateway: ${err.message}`);
+                }
+            });
+
+            clientReq.pipe(proxyReq);
+        });
+
+        let shuttingDown = false;
+
+        function handleShutdown() {
+            if (shuttingDown) return;
+            shuttingDown = true;
+            console.log("");
+            info("Shutting down proxy...");
+            server.close(() => {
+                success("Proxy stopped");
+                process.exit(0);
+            });
+            setTimeout(() => {
+                warn("Proxy did not close gracefully, forcing exit");
+                process.exit(0);
+            }, 3000);
+        }
+
+        process.on("SIGINT", handleShutdown);
+        process.on("SIGTERM", handleShutdown);
+        process.on("SIGHUP", handleShutdown);
+
+        server.listen(proxyPort, () => {
+            success(`Dev proxy listening on http://localhost:${proxyPort}`);
+            info(`Forwarding to http://${target}`);
+            info(`Plugin slug: ${slug}`);
+            info(`Core URL: ${coreUrl}`);
+            if (apiKey) {
+                info("API key authentication enabled");
+            }
+            info("Press Ctrl+C to stop");
+        });
+    });
+
+async function coreFetch(
+    coreUrl: string,
+    apiKey: string | undefined,
+    endpoint: string,
+    body: Record<string, unknown>,
+): Promise<Response | null> {
+    try {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+        };
+        if (apiKey) {
+            headers["Authorization"] = `Bearer ${apiKey}`;
+        }
+        return await fetch(`${coreUrl.replace(/\/$/, "")}${endpoint}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    } catch {
+        return null;
+    }
+}
+
+async function registerRequest(
+    coreUrl: string,
+    apiKey: string | undefined,
+    slug: string,
+): Promise<string | null> {
+    const res = await coreFetch(coreUrl, apiKey, "/api/dev/request-id", {
+        slug,
+    });
+    if (!res || !res.ok) return null;
+    try {
+        const data = (await res.json()) as { request_id: string };
+        return data.request_id;
+    } catch {
+        return null;
+    }
+}
+
+function parseTarget(target: string): { hostname: string; port: number } {
+    let cleaned = target.replace(/^https?:\/\//, "");
+    const [hostname, portStr] = cleaned.split(":");
+    const port = portStr ? parseInt(portStr, 10) : 3000;
+    return { hostname, port };
+}

package/src/commands/publish.ts

@@ -0,0 +1,106 @@
+import { Command } from "commander";
+import { createSpinner, success, error as logError } from "../utils/logger";
+import path from "path";
+import { loadConfig } from "../config";
+import { existsSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+
+export const publishCommand = new Command("publish")
+    .description("Build and push a plugin to an image registry")
+    .action(async (slug: string, options: any, cmd: Command) => {
+        const spinner = createSpinner(`Preparing build...`);
+        const config = loadConfig();
+
+        const pluginDir = config.pluginDir || process.cwd();
+        const manifestPath = path.resolve(pluginDir, "manifest.json");
+        const dockerFilePath = path.resolve(pluginDir, "Dockerfile");
+
+        if (!existsSync(manifestPath)) {
+            spinner.fail();
+            logError(`Could not build, manifest.json is missing!`);
+            process.exit(1);
+        }
+
+        if (!config.registryUrl) {
+            spinner.fail();
+            logError(`Registery URL not set`);
+            process.exit(1);
+        }
+
+        if (!existsSync(dockerFilePath)) {
+            spinner.fail();
+            logError(`Could not build, Dockerfile is missing!`);
+            process.exit(1);
+        }
+
+        if (!checkDocker) {
+            spinner.fail();
+            logError(`Could not build, Docker is unreachable!`);
+            process.exit(1);
+        }
+
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+        try {
+            spinner.text = "Building Docker image...";
+            await buildDockerImage(
+                pluginDir,
+                config.registryUrl,
+                manifest.name,
+                manifest.version,
+            );
+            success(`Plugin has been build`);
+            spinner.text = "Pushing Docker image...";
+            await pushDockerImage(
+                config.registryUrl,
+                manifest.name,
+                manifest.version,
+            );
+            spinner.succeed();
+            success(
+                `Plugin has been build and pushed under ${manifest.name}:${manifest.version}`,
+            );
+        } catch (err: any) {
+            spinner.fail();
+            logError(`Failed to deploy: ${err.message}`);
+            process.exit(1);
+        }
+    });
+
+function buildDockerImage(
+    pluginDir: string,
+    registryURL: string,
+    image: string,
+    version: string,
+): boolean {
+    execSync(
+        `docker build -t ${registryURL}/${image}:${version} ${pluginDir}`,
+        {
+            stdio: "pipe",
+        },
+    );
+    return true;
+}
+
+function pushDockerImage(
+    registryURL: string,
+    image: string,
+    version: string,
+): boolean {
+    execSync(`docker push ${registryURL}/${image}:${version}`, {
+        stdio: "pipe",
+    });
+    return true;
+}
+
+function checkDocker(): boolean {
+    try {
+        execSync("docker info --format '{{.ServerVersion}}'", {
+            stdio: "pipe",
+            timeout: 5000,
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/commands/serve-frontend.ts

@@ -0,0 +1,103 @@
+import { Command } from "commander";
+import express from "express";
+import EventEmitter from "node:events";
+import { buildFrontendFiles, currentImportsGlobalVue } from "./build-frontend";
+import chokidar from "chokidar";
+
+export const serveFrontendCommand = new Command("serve-frontend")
+    .description("Compile all pages into a dist directory")
+    .action(async (opts: null, cmd: Command) => {
+        const app = express();
+
+        app.use((req, res, next) => {
+            res.header(`Access-Control-Allow-Origin`, `*`);
+            res.header(`Access-Control-Allow-Methods`, `GET`);
+            res.header(`Access-Control-Allow-Headers`, `Content-Type`);
+            next();
+        });
+
+        app.get("/dev/css", async (req, res) => {
+            res.end(lastCSS);
+        });
+        app.get("/dev/js", async (req, res) => {
+            res.json({
+                code: lastJS,
+                currentImportsGlobalVue: [...currentImportsGlobalVue].map((e) =>
+                    e.trim(),
+                ),
+            });
+        });
+
+        const updateEvents = new EventEmitter();
+
+        const watchUpdates = chokidar.watch("./pages");
+
+        app.get("/streaming", (req, res) => {
+            res.setHeader("Cache-Control", "no-cache");
+            res.setHeader("Content-Type", "text/event-stream");
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders(); // flush the headers to establish SSE with client
+
+            updateEvents.on("jsUpdate", () => {
+                res.write(`id:0\nevent:reloadJS\ndata:js\n\n`);
+            });
+            updateEvents.on("cssUpdate", () => {
+                res.write(`id:0\nevent:reloadCSS\ndata:css\n\n`);
+            });
+            // If client closes connection, stop sending events
+            res.on("close", () => {
+                // watcher.
+                res.end();
+            });
+        });
+
+        buildInMemory().then(() => {
+            app.listen(3003, () => {
+                console.log("Dev server is running");
+
+                watchUpdates.on("all", (event, path) => {
+                    let beforeTSJS = tsJS;
+                    let beforeTSCSS = tsCSS;
+
+                    buildInMemory().then(() => {
+                        if (beforeTSCSS != tsCSS) {
+                            updateEvents.emit("cssUpdate");
+                        }
+                        if (beforeTSJS != tsJS) {
+                            updateEvents.emit("jsUpdate");
+                        }
+                    });
+                });
+            });
+        });
+    });
+
+let lastCSS = "",
+    lastJS = "",
+    tsJS = new Date().getTime(),
+    tsCSS = new Date().getTime();
+
+export async function buildInMemory() {
+    console.log("Building...");
+    const result = await buildFrontendFiles(false);
+
+    const js = result
+        .outputFiles!.filter((e) => e.path.endsWith(".js"))
+        .map((e) => e.text)
+        .join("\n");
+    const css = `${result
+        .outputFiles!.filter((e) => e.path.endsWith(".css"))
+        .map((e) => e.text)
+        .join("\n")}\`;`;
+
+    if (js != lastJS) {
+        tsJS = new Date().getTime();
+        lastJS = js;
+    }
+    if (css != lastCSS) {
+        tsCSS = new Date().getTime();
+        lastCSS = css;
+    }
+    console.log("Build done!");
+}