@alcedocore/cli 0.0.1-rc.0

package/src/config.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { loadConfig, findAlcedorc } from "./config";
+import os from "node:os";
+
+describe("loadConfig", () => {
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("returns defaults when no config sources are present", () => {
+    const config = loadConfig({});
+    expect(config.registryUrl).toBe("localhost:5000");
+    expect(config.coreUrl).toBe("http://localhost:8080");
+    expect(config.pluginDir).toBe(process.cwd());
+  });
+
+  it("prefers CLI flags over env vars", () => {
+    process.env.ALCEDO_CORE_URL = "http://env-url:8080";
+    const config = loadConfig({ coreUrl: "http://cli-url:8080" });
+    expect(config.coreUrl).toBe("http://cli-url:8080");
+  });
+
+  it("prefers env vars over defaults", () => {
+    process.env.ALCEDO_CORE_URL = "http://env-url:8080";
+    const config = loadConfig({});
+    expect(config.coreUrl).toBe("http://env-url:8080");
+  });
+
+  it("reads ALCEDO_REGISTRY_URL from env", () => {
+    process.env.ALCEDO_REGISTRY_URL = "my-registry:5000";
+    const config = loadConfig({});
+    expect(config.registryUrl).toBe("my-registry:5000");
+  });
+
+  it("reads ALCEDO_PLUGIN_DIR from env", () => {
+    process.env.ALCEDO_PLUGIN_DIR = "/custom/plugin/path";
+    const config = loadConfig({});
+    expect(config.pluginDir).toBe("/custom/plugin/path");
+  });
+});
+
+describe("findAlcedorc", () => {
+  it("returns null when no .alcedorc file exists", () => {
+    // Use system temp dir where no .alcedorc should exist
+    const result = findAlcedorc(os.tmpdir());
+    expect(result).toBeNull();
+  });
+});

package/src/config.ts

@@ -0,0 +1,125 @@
+import { cosmiconfigSync } from "cosmiconfig";
+import path from "node:path";
+import fs from "node:fs";
+import { parse as parseEnv } from "dotenv";
+
+export interface ConfigSchema {
+    registryUrl?: string;
+    coreUrl?: string;
+    pluginDir?: string;
+    apiKey?: string;
+}
+
+const DEFAULTS: ConfigSchema = {
+    registryUrl: "localhost:5000",
+    coreUrl: "http://localhost:8080",
+    pluginDir: process.cwd(),
+};
+
+/**
+ * Load config with priority: CLI flags highest → env vars → .alcedorc → defaults lowest.
+ * `cliFlags` is the parsed Commander.js flags object (already processed by Commander).
+ */
+export function loadConfig(cliFlags: Partial<ConfigSchema> = {}): ConfigSchema {
+    // Start with defaults
+    const config: ConfigSchema = { ...DEFAULTS };
+
+    // Override with .alcedorc (lowest priority override)
+    const rcConfig = loadAlcedorc();
+    if (rcConfig) {
+        Object.assign(config, rcConfig);
+    }
+
+    // Override with .alcedocore.dev.env (set by `alcedocore connect`)
+    const devEnvConfig = loadDevEnv();
+    Object.assign(config, devEnvConfig);
+
+    // Override with env vars (medium priority)
+    const envConfig = loadEnvConfig();
+    Object.assign(config, envConfig);
+
+    // Override with CLI flags (highest priority)
+    Object.assign(config, cliFlags);
+
+    return config;
+}
+
+/**
+ * Walk up directory tree from startDir (default: cwd) to find .alcedorc JSON file.
+ * Returns the parsed config or null if no file found.
+ */
+function loadAlcedorc(): ConfigSchema | null {
+    const explorer = cosmiconfigSync("alcedo", {
+        searchPlaces: [".alcedorc", ".alcedorc.json"],
+        stopDir: path.parse(process.cwd()).root,
+    });
+
+    // cosmiconfig's search walks up automatically
+    const result = explorer.search();
+    if (result && !result.isEmpty) {
+        return result.config as ConfigSchema;
+    }
+    return null;
+}
+
+/**
+ * Read .alcedocore.dev.env from the current directory (set by `alcedocore connect`).
+ */
+function loadDevEnv(): Partial<ConfigSchema> {
+    const config: Partial<ConfigSchema> = {};
+    const envPath = path.join(process.cwd(), ".alcedocore.dev.env");
+    if (!fs.existsSync(envPath)) return config;
+    const envConfig = parseEnv(fs.readFileSync(envPath));
+
+    if (envConfig.CORE_URL) config.coreUrl = envConfig.CORE_URL;
+    if (envConfig.API_KEY) config.apiKey = envConfig.API_KEY;
+
+    return config;
+}
+
+/**
+ * Read environment variables with ALCEDO_ prefix.
+ * e.g., ALCEDO_REGISTRY_URL → registryUrl, ALCEDO_CORE_URL → coreUrl
+ */
+function loadEnvConfig(): Partial<ConfigSchema> {
+    const config: Partial<ConfigSchema> = {};
+
+    const envMapping: Record<string, keyof ConfigSchema> = {
+        ALCEDO_REGISTRY_URL: "registryUrl",
+        ALCEDO_CORE_URL: "coreUrl",
+        ALCEDO_PLUGIN_DIR: "pluginDir",
+        ALCEDO_API_KEY: "apiKey",
+    };
+
+    for (const [envKey, configKey] of Object.entries(envMapping)) {
+        const value = process.env[envKey];
+        if (value) {
+            (config as any)[configKey] = value;
+        }
+    }
+
+    return config;
+}
+
+/**
+ * Explicit directory tree walk for .alcedorc discovery (CLI-06).
+ * Used when cosmiconfig's auto-search isn't desired and we need
+ * manual control over the walk.
+ */
+export function findAlcedorc(startDir: string = process.cwd()): string | null {
+    let currentDir = path.resolve(startDir);
+
+    while (true) {
+        const candidate = path.join(currentDir, ".alcedorc");
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) {
+            // Reached filesystem root
+            return null;
+        }
+        currentDir = parent;
+    }
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { loadConfig, ConfigSchema } from "./config";
+import { error as logError } from "./utils/logger";
+import { initCoreCommand } from "./commands/init-core";
+import { initCommand } from "./commands/init";
+import { deployCommand } from "./commands/deploy";
+import { addMigrationCommand } from "./commands/add-migration";
+import { migrateCommand } from "./commands/migrate";
+import { addEndpointCommand } from "./commands/add-endpoint";
+import { addPageCommand } from "./commands/add-page";
+import { addNavItemCommand } from "./commands/add-nav-item";
+import { connectCommand } from "./commands/connect";
+import fs from "node:fs";
+import path from "node:path";
+import { devCommand } from "./commands/dev";
+import { publishCommand } from "./commands/publish";
+
+// Read version from package.json
+function getVersion(): string {
+    const pkgPath = path.resolve(__dirname, "../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return pkg.version;
+}
+
+const program = new Command();
+
+program
+    .name("alcedo")
+    .version(getVersion(), "-V, --version", "Output the version number")
+    .description(
+        "Alcedo plugin development CLI - scaffold, develop, and test plugins",
+    )
+    .hook("preAction", (thisCommand) => {
+        // Parse config before any action runs
+        // Walk parent chain to collect all options (including global flags)
+        const opts: Partial<ConfigSchema> = {};
+        let cmd: Command | null = thisCommand;
+        while (cmd) {
+            Object.assign(opts, cmd.opts());
+            cmd = cmd.parent as Command | null;
+        }
+        const config = loadConfig(opts);
+        // Store config on the command for subcommands to access
+        (thisCommand as any)._alcedoConfig = config;
+    });
+
+// Global options
+program.option(
+    "-r, --registry-url <url>",
+    "Docker registry URL (default: localhost:5000)",
+);
+program.option(
+    "-c, --core-url <url>",
+    "core API URL (default: http://localhost:8080)",
+);
+program.option(
+    "-d, --plugin-dir <path>",
+    "Plugin project directory (default: current directory)",
+);
+
+program.addCommand(initCommand);
+program.addCommand(initCoreCommand);
+program.addCommand(deployCommand);
+program.addCommand(publishCommand);
+
+const addCommand = new Command("add").description(
+    "Generate plugin components (migrations, endpoints, pages, nav-items)",
+);
+
+addCommand.addCommand(addMigrationCommand);
+addCommand.addCommand(addEndpointCommand);
+addCommand.addCommand(addPageCommand);
+addCommand.addCommand(addNavItemCommand);
+
+program.addCommand(addCommand);
+program.addCommand(migrateCommand);
+program.addCommand(connectCommand);
+program.addCommand(devCommand);
+
+// Error handling: non-zero exit on errors (CLI-04)
+// Catch unhandled promise rejections and exceptions
+process.on("unhandledRejection", (reason) => {
+    logError(`Unhandled error: ${reason}`);
+    process.exit(1);
+});
+
+process.on("uncaughtException", (err) => {
+    logError(`Fatal error: ${err.message}`);
+    process.exit(1);
+});
+
+async function main(): Promise<void> {
+    await program.parseAsync(process.argv);
+}
+
+main().catch((err) => {
+    logError(`Fatal error: ${err.message}`);
+    process.exit(1);
+});

package/src/integration/cli-api.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeAll } from "vitest";
+
+const CORE_URL = process.env.CORE_URL || "http://localhost:8080";
+const TEST_SLUG = process.env.TEST_PLUGIN_SLUG || "hello-world";
+
+// ---------------------------------------------------------------------------
+// Health check — skip all tests if AlcedoCore is not reachable
+// ---------------------------------------------------------------------------
+
+let coreReachable = false;
+
+beforeAll(async () => {
+    try {
+        const res = await fetch(`${CORE_URL}/health`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        coreReachable = res.ok;
+    } catch {
+        coreReachable = false;
+    }
+});
+
+// ---------------------------------------------------------------------------
+// Test helpers — replicate CLI patterns without Commander overhead
+// ---------------------------------------------------------------------------
+
+async function apiCall<T>(
+    apiPath: string,
+    options?: { method?: string; body?: unknown },
+): Promise<T> {
+    const url = `${CORE_URL.replace(/\/$/, "")}${apiPath}`;
+    const res = await fetch(url, {
+        method: options?.method || "GET",
+        headers: { "Content-Type": "application/json" },
+        body: options?.body ? JSON.stringify(options.body) : undefined,
+    });
+    if (!res.ok) {
+        const errBody = (await res
+            .json()
+            .catch(() => ({ error: res.statusText }))) as { error?: string };
+        throw new Error(
+            errBody.error || `HTTP ${res.status}: ${res.statusText}`,
+        );
+    }
+    return res.json() as Promise<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Migration API tests (used by `alcedo migrate` command)
+// ---------------------------------------------------------------------------
+
+describe("Migration API", () => {
+    it("lists migrations for a plugin via GET /api/plugins/:slug/migrations", async () => {
+        if (!coreReachable) return;
+
+        const migrations = await apiCall<
+            Array<{ version: string; name: string; status: string }>
+        >(`/api/plugins/${TEST_SLUG}/migrations`);
+
+        expect(Array.isArray(migrations)).toBe(true);
+        // Migration list should always return an array (possibly empty)
+        for (const m of migrations) {
+            expect(m.version).toBeTruthy();
+            expect(m.name).toBeTruthy();
+            expect(["applied", "pending"]).toContain(m.status);
+        }
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Request log detail API tests (used by `alcedo dev replay` command)
+// ---------------------------------------------------------------------------
+
+describe("Request log detail API", () => {
+    it("returns 404 for non-existent request ID", async () => {
+        if (!coreReachable) return;
+
+        const url = `${CORE_URL.replace(/\/$/, "")}/api/plugins/${TEST_SLUG}/logs/nonexistent-id/detail`;
+        const res = await fetch(url);
+        expect(res.status).toBe(404);
+
+        const body = (await res.json()) as { error?: string };
+        expect(body.error).toBeTruthy();
+    });
+
+    it("returns log entries listing via GET /api/plugins/:slug/logs", async () => {
+        if (!coreReachable) return;
+
+        // The API wraps logs under { data: { logs: [...] } }
+        const res = await apiCall<{
+            data: {
+                logs: Array<{
+                    request_uuid: string;
+                    method: string;
+                    path: string;
+                }>;
+            };
+        }>(`/api/plugins/${TEST_SLUG}/logs`);
+
+        expect(res.data).toBeDefined();
+        expect(Array.isArray(res.data.logs)).toBe(true);
+        if (res.data.logs.length > 0) {
+            const entry = res.data.logs[0];
+            expect(entry.request_uuid).toBeTruthy();
+            expect(entry.method).toBeTruthy();
+            expect(entry.path).toBeDefined();
+        }
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Error handling tests
+// ---------------------------------------------------------------------------
+
+describe("Error handling", () => {
+    it("returns 404 for non-existent plugin slug", async () => {
+        if (!coreReachable) return;
+
+        const url = `${CORE_URL.replace(/\/$/, "")}/api/plugins/nonexistent-plugin/logs`;
+        const res = await fetch(url);
+        expect(res.status).toBe(404);
+    });
+
+    it("handles network errors gracefully", async () => {
+        // Use a non-routable address to simulate network failure
+        const badUrl = "http://192.0.2.1:9999/api/dev/start";
+        try {
+            await fetch(badUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    slug: "test",
+                    url: "http://localhost:3000",
+                }),
+                signal: AbortSignal.timeout(1000),
+            });
+            // Should not reach here
+            expect(true).toBe(false);
+        } catch (err: unknown) {
+            expect(err).toBeTruthy();
+        }
+    });
+});

package/src/utils/ejs-renderer.ts

@@ -0,0 +1,55 @@
+import ejs from "ejs";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Render an EJS template string with the given data.
+ * Returns the rendered string.
+ */
+export function renderTemplate(
+    templateContent: string,
+    data: Record<string, any>,
+): string {
+    return ejs.render(templateContent, data);
+}
+
+/**
+ * Read an EJS template file, render it with data, and write to the target path.
+ * Creates parent directories if they don't exist.
+ * ONLY creates new files — never overwrites (GEN-05 compliance).
+ * Returns the target path on success, throws on error.
+ */
+export function renderAndWrite(
+    templatePath: string,
+    targetPath: string,
+    data: Record<string, any>,
+): string {
+    if (fs.existsSync(targetPath)) {
+        throw new Error(
+            `Target file already exists: ${targetPath}. ` +
+                `Refusing to overwrite existing code (GEN-05).`,
+        );
+    }
+
+    const templateContent = fs.readFileSync(templatePath, "utf-8");
+    const rendered = renderTemplate(templateContent, data);
+
+    const dir = path.dirname(targetPath);
+    fs.mkdirSync(dir, { recursive: true });
+
+    fs.writeFileSync(targetPath, rendered, "utf-8");
+    return targetPath;
+}
+
+/**
+ * Read an EJS template file and return the rendered content as a string
+ * (without writing to disk). Used for content that gets appended to existing files
+ * like manifest.json updates.
+ */
+export function renderToString(
+    templatePath: string,
+    data: Record<string, any>,
+): string {
+    const templateContent = fs.readFileSync(templatePath, "utf-8");
+    return renderTemplate(templateContent, data);
+}

package/src/utils/formatting.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared naming/convention utilities used by CLI generator commands.
+ */
+
+/**
+ * Convert a name to PascalCase for display labels and class names.
+ * "dashboard" -> "Dashboard"
+ * "user-management" -> "UserManagement"
+ * "get_users" -> "GetUsers"
+ */
+export function toPascalCase(name: string): string {
+  return name
+    .split(/[_-]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Convert a name to camelCase for function/variable names.
+ * "get_users" -> "getUsers"
+ */
+export function toCamelCase(name: string): string {
+  const pascal = toPascalCase(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/**
+ * Derive a URL path from an endpoint name.
+ * "get_users" -> "/api/get_users"
+ * "health" -> "/health"
+ */
+export function derivePath(name: string): string {
+  const normalized = name.replace(/[_-]/g, "_");
+  if (normalized.startsWith("get_") || normalized.startsWith("post_") ||
+      normalized.startsWith("put_") || normalized.startsWith("delete_") ||
+      normalized.startsWith("patch_")) {
+    return "/" + normalized.replace(/_/g, "/");
+  }
+  return "/api/" + normalized.replace(/_/g, "/");
+}
+
+/**
+ * Derive HTTP method from endpoint name.
+ * "get_users" -> "GET"
+ * "create_user" -> "POST"
+ * "health" -> "GET" (default)
+ */
+export function deriveMethod(name: string): string {
+  const prefix = name.split("_")[0].toLowerCase();
+  const methodMap: Record<string, string> = {
+    get: "GET",
+    post: "POST",
+    create: "POST",
+    put: "PUT",
+    update: "PUT",
+    delete: "DELETE",
+    remove: "DELETE",
+    patch: "PATCH",
+    list: "GET",
+  };
+  return methodMap[prefix] || "GET";
+}

package/src/utils/generateTimestamp.ts

@@ -0,0 +1,16 @@
+
+/**
+ * Generate a timestamp string (same format as migration command).
+ */
+export function generateTimestamp(): string {
+  const now = new Date();
+  const pad = (n: number, d = 2) => String(n).padStart(d, "0");
+  return (
+    `${now.getFullYear()}` +
+    `${pad(now.getMonth() + 1)}` +
+    `${pad(now.getDate())}` +
+    `${pad(now.getHours())}` +
+    `${pad(now.getMinutes())}` +
+    `${pad(now.getSeconds())}`
+  );
+}

package/src/utils/logger.ts

@@ -0,0 +1,27 @@
+import chalk from "chalk";
+import ora from "ora";
+
+export function success(msg: string): void {
+  console.log(chalk.green("✔"), msg);
+}
+
+export function error(msg: string): void {
+  console.error(chalk.red("✖"), msg);
+}
+
+export function info(msg: string): void {
+  console.log(chalk.blue("ℹ"), msg);
+}
+
+export function warn(msg: string): void {
+  console.warn(chalk.yellow("⚠"), msg);
+}
+
+/**
+ * Create an ora spinner with the given text.
+ * Starts immediately. Call `.succeed()`, `.fail()`, or `.stop()` on the returned instance.
+ * Ora auto-detects CI/non-TTY environments and disables spinners appropriately.
+ */
+export function createSpinner(text: string): ora.Ora {
+  return ora({ text, color: "cyan" }).start();
+}

package/src/utils/validation.ts

@@ -0,0 +1,13 @@
+/**
+ * Validate that a name contains only safe characters for use in filenames.
+ * Rejects names containing path separators (/ or \), null bytes, or "..".
+ * Allowed: letters, digits, hyphens, underscores (regex: /^[\w-]+$/).
+ * Throws an error with the given label if the name is invalid.
+ */
+export function assertSafeName(name: string, label: string): void {
+  if (!/^[\w-]+$/.test(name)) {
+    throw new Error(
+      `Invalid ${label} "${name}". Use only letters, digits, hyphens, and underscores.`
+    );
+  }
+}

package/templates/endpoint/handler.js.ejs

@@ -0,0 +1,23 @@
+// Endpoint: <%- name %>
+// Generated: <%- timestamp %>
+// This file was auto-generated by `alcedo add endpoint <%- name %>`
+// DO NOT EDIT the imports section — add your logic below.
+
+/**
+ * Handler for <%- method %> <%- path %>
+ */
+function <%- camelName %>Handler(req, res) {
+  const sendJson = (data, status = 200) => {
+    const body = JSON.stringify(data);
+    res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) });
+    res.end(body);
+  };
+
+  sendJson({
+    status: "ok",
+    endpoint: "<%- path %>",
+    message: "<%- camelName %> handler ready",
+  });
+}
+
+module.exports = { <%- camelName %>Handler };

package/templates/endpoint/handler.py.ejs

@@ -0,0 +1,23 @@
+# Endpoint: <%- name %>
+# Generated: <%- timestamp %>
+# This file was auto-generated by `alcedo add endpoint <%- name %>`
+# DO NOT EDIT the imports section — add your logic below.
+import json
+from http.server import BaseHTTPRequestHandler
+
+
+class <%- className %>Handler(BaseHTTPRequestHandler):
+    """Handler for <%- method %> <%- path %>"""
+
+    def do_<%- method %>(self):
+        self._json({
+            "status": "ok",
+            "endpoint": "<%- path %>",
+            "message": "<%- className %> handler ready"
+        })
+
+    def _json(self, data, status=200):
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(data).encode())

package/templates/migration/down.sql.ejs

@@ -0,0 +1,6 @@
+-- Migration: <%- name %>
+-- Generated: <%- timestamp %>
+-- Down Migration
+-- Write your rollback SQL here.
+
+DROP TABLE IF EXISTS <%- tableName %>;

package/templates/migration/up.sql.ejs

@@ -0,0 +1,11 @@
+-- Migration: <%- name %>
+-- Generated: <%- timestamp %>
+-- Up Migration
+-- Write your migration SQL here.
+
+CREATE TABLE IF NOT EXISTS <%- tableName %> (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);