@alcedocore/cli 0.0.1-rc.0

package/dist/utils/logger.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.success = success;
+exports.error = error;
+exports.info = info;
+exports.warn = warn;
+exports.createSpinner = createSpinner;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+function success(msg) {
+    console.log(chalk_1.default.green("✔"), msg);
+}
+function error(msg) {
+    console.error(chalk_1.default.red("✖"), msg);
+}
+function info(msg) {
+    console.log(chalk_1.default.blue("ℹ"), msg);
+}
+function warn(msg) {
+    console.warn(chalk_1.default.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.
+ */
+function createSpinner(text) {
+    return (0, ora_1.default)({ text, color: "cyan" }).start();
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/validation.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeName = assertSafeName;
+/**
+ * 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.
+ */
+function assertSafeName(name, label) {
+    if (!/^[\w-]+$/.test(name)) {
+        throw new Error(`Invalid ${label} "${name}". Use only letters, digits, hyphens, and underscores.`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@alcedocore/cli",
+    "version": "0.0.1-rc.0",
+    "description": "Alcedo plugin development CLI - scaffold, develop, and test plugins",
+    "main": "dist/index.js",
+    "bin": {
+        "alcedo": "dist/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "start": "node dist/index.js",
+        "dev": "tsx src/index.ts",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "@chialab/esbuild-plugin-postcss": "^1.0.1",
+        "@types/express": "^5.0.6",
+        "chalk": "^4.1.2",
+        "check-disk-space": "^3.4.0",
+        "chokidar": "^5.0.0",
+        "commander": "^11.1.0",
+        "cosmiconfig": "^8.3.6",
+        "detect-port": "^2.1.0",
+        "dotenv": "^17.4.2",
+        "ejs": "^3.1.9",
+        "express": "^5.2.1",
+        "inquirer": "^8.2.7",
+        "ora": "^5.4.1",
+        "unplugin-vue": "^7.2.0"
+    },
+    "devDependencies": {
+        "@types/detect-port": "^1.3.5",
+        "@types/ejs": "^3.1.5",
+        "@types/inquirer": "^8.2.12",
+        "@types/node": "^20.11.0",
+        "tsx": "^4.7.0",
+        "typescript": "^5.3.0",
+        "vitest": "^3.2.4"
+    }
+}

package/src/commands/add-endpoint.ts

@@ -0,0 +1,157 @@
+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, ConfigSchema } from "../config";
+import { assertSafeName } from "../utils/validation";
+import {
+    toPascalCase,
+    toCamelCase,
+    derivePath,
+    deriveMethod,
+} from "../utils/formatting";
+import { generateTimestamp } from "../utils/generateTimestamp";
+
+export const addEndpointCommand = new Command("endpoint")
+    .argument("<name>", "Endpoint name (e.g., get_users)")
+    .option(
+        "-m, --method <method>",
+        "HTTP method (GET, POST, PUT, DELETE, PATCH)",
+    )
+    .option("-p, --path <path>", "URL path (e.g., /api/users)")
+    .description("Generate a handler stub and update manifest.json endpoints")
+    .action(
+        async (
+            name: string,
+            options: { method?: string; path?: string },
+            cmd: Command,
+        ) => {
+            const config = loadConfig(
+                cmd.optsWithGlobals() as Partial<ConfigSchema>,
+            );
+
+            assertSafeName(name, "endpoint name");
+
+            const pluginDir = config.pluginDir || process.cwd();
+            const manifestPath = path.resolve(pluginDir, "manifest.json");
+
+            // Derive endpoint metadata
+            const VALID_METHODS = [
+                "GET",
+                "POST",
+                "PUT",
+                "DELETE",
+                "PATCH",
+                "HEAD",
+                "OPTIONS",
+            ];
+            const method = (options.method || deriveMethod(name)).toUpperCase();
+            if (!VALID_METHODS.includes(method)) {
+                throw new Error(
+                    `Invalid HTTP method "${method}". Valid methods: ${VALID_METHODS.join(", ")}`,
+                );
+            }
+            const urlPath = options.path || derivePath(name);
+            const className = toPascalCase(name);
+            const camelName = toCamelCase(name);
+            const timestamp = generateTimestamp();
+
+            // Detect language from existing server files
+            let language: "python" | "node" = "python";
+            if (fs.existsSync(path.join(pluginDir, "server.js"))) {
+                language = "node";
+            }
+
+            const templatesDir = path.resolve(__dirname, "../../templates");
+            const endpointsDir = path.resolve(pluginDir, "endpoints");
+
+            const spinner = createSpinner(`Generating endpoint: ${name}`);
+
+            try {
+                // Create endpoints directory
+                fs.mkdirSync(endpointsDir, { recursive: true });
+
+                // Generate handler stub file
+                const handlerTemplate =
+                    language === "python" ? "handler.py.ejs" : "handler.js.ejs";
+                const handlerFilename = `${name}.${language === "python" ? "py" : "js"}`;
+
+                renderAndWrite(
+                    path.join(templatesDir, "endpoint", handlerTemplate),
+                    path.join(endpointsDir, handlerFilename),
+                    {
+                        name,
+                        className,
+                        camelName,
+                        method,
+                        path: urlPath,
+                        timestamp,
+                        language,
+                    },
+                );
+
+                // Update manifest.json endpoints array
+                if (!fs.existsSync(manifestPath)) {
+                    throw new Error(
+                        `No manifest.json found at ${manifestPath} — skipping manifest update.`,
+                    );
+                }
+
+                const manifest = JSON.parse(
+                    fs.readFileSync(manifestPath, "utf-8"),
+                );
+
+                // Initialize endpoints array if it doesn't exist
+                if (!manifest.endpoints) {
+                    manifest.endpoints = [];
+                }
+
+                // Append new endpoint entry (never modify existing entries — GEN-05)
+                const newEntry = {
+                    method,
+                    path: urlPath,
+                    description: `${camelName} endpoint`,
+                    group: "api",
+                };
+
+                // Check for duplicate before appending (GEN-05 "never modify existing entries"
+                // also implies no duplicate entries for the same method + path)
+                const isDuplicate = manifest.endpoints.some(
+                    (e: any) => e.method === method && e.path === urlPath,
+                );
+
+                if (isDuplicate) {
+                    throw new Error(
+                        `Endpoint ${method} ${urlPath} already exists in manifest.json — skipping.`,
+                    );
+                }
+                manifest.endpoints.push(newEntry);
+
+                // Write updated manifest.json back (preserving existing data)
+                fs.writeFileSync(
+                    manifestPath,
+                    JSON.stringify(manifest, null, 2) + "\n",
+                    "utf-8",
+                );
+
+                spinner.succeed();
+
+                success(`Endpoint created:`);
+                info(`  endpoints/${handlerFilename}`);
+                info(`  manifest.json ← ${method} ${urlPath}`);
+                info(
+                    `Import the handler in your main server file and add the route.`,
+                );
+            } catch (err: any) {
+                spinner.fail();
+                logError(`Failed to generate endpoint: ${err.message}`);
+                process.exit(1);
+            }
+        },
+    );

package/src/commands/add-migration.ts

@@ -0,0 +1,102 @@
+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 { assertSafeName } from "../utils/validation";
+import { generateTimestamp } from "../utils/generateTimestamp";
+
+/**
+ * Derive a table name from migration name.
+ * Converts "create_users_table" → "users", "add_category_to_items" → "category"
+ * Falls back to a safe default if pattern doesn't match.
+ */
+function deriveTableName(migrationName: string): string {
+    // Pattern: create_{table_name}_table -> table_name
+    const createMatch = migrationName.match(/^create_(.+)_table$/);
+    if (createMatch) return createMatch[1];
+
+    // Pattern: add_{column}_to_{table} -> table
+    const addMatch = migrationName.match(/^add_\w+_to_(.+)$/);
+    if (addMatch) return addMatch[1];
+
+    // Fallback: use the migration name itself (already validated as safe by assertSafeName)
+    return migrationName;
+}
+
+/**
+ * Shared migration generation action. Creates a versioned SQL migration file pair
+ * (.up.sql + .down.sql) in the plugin's migrations/ directory.
+ * Can be used by both `alcedo add migration` and `alcedo migrate generate`.
+ */
+export async function addMigrationAction(name: string): Promise<void> {
+    const config = loadConfig();
+
+        assertSafeName(name, "migration name");
+
+    const pluginDir = config.pluginDir || process.cwd();
+    const migrationsDir = path.resolve(pluginDir, "migrations");
+
+    if (!fs.existsSync(migrationsDir)) {
+        throw new Error(
+            `No migrations/ directory found in ${pluginDir}. Run \`alcedo init\` first or create the directory.`,
+        );
+    }
+
+    const timestamp = generateTimestamp();
+    const tableName = deriveTableName(name);
+    const templatesDir = path.resolve(__dirname, "../../templates");
+
+    const data = {
+        name,
+        timestamp,
+        tableName,
+    };
+
+    const upFilename = `${timestamp}_${name}.up.sql`;
+    const downFilename = `${timestamp}_${name}.down.sql`;
+
+    const spinner = createSpinner(`Generating migration: ${name}`);
+
+    try {
+        // Generate up migration
+        renderAndWrite(
+            path.join(templatesDir, "migration", "up.sql.ejs"),
+            path.join(migrationsDir, upFilename),
+            data,
+        );
+
+        // Generate down migration
+        renderAndWrite(
+            path.join(templatesDir, "migration", "down.sql.ejs"),
+            path.join(migrationsDir, downFilename),
+            data,
+        );
+
+        spinner.succeed();
+
+        success(`Migration created:`);
+        info(`  ${upFilename}`);
+        info(`  ${downFilename}`);
+        info(`Edit these files to add your SQL logic.`);
+    } catch (err: any) {
+        spinner.fail();
+        logError(`Failed to generate migration: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+export const addMigrationCommand = new Command("migration")
+    .argument("<name>", "Migration name (e.g., create_users_table)")
+    .description(
+        "Generate a versioned SQL migration file pair (.up.sql + .down.sql)",
+    )
+    .action(async (name: string) => {
+        await addMigrationAction(name);
+    });

package/src/commands/add-nav-item.ts

@@ -0,0 +1,106 @@
+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 { loadConfig, ConfigSchema } from "../config";
+import { assertSafeName } from "../utils/validation";
+import { toPascalCase } from "../utils/formatting";
+
+export const addNavItemCommand = new Command("nav-item")
+    .argument("<name>", "Nav item name (e.g., settings, user-management)")
+    .option("-p, --path <path>", "Destination URL path (default: /{name})")
+    .option("-i, --icon <icon>", "Material Symbol icon name (default: page)")
+    .option("--parent <parent>", "Parent nav-item path for nesting")
+    .option("-b, --badge <badge>", "Badge text for the nav item")
+    .description(
+        "Add a sidebar navigation entry to manifest.json (no file created)",
+    )
+    .action(
+        async (
+            name: string,
+            options: {
+                path?: string;
+                icon?: string;
+                parent?: string;
+                badge?: string;
+            },
+            cmd: Command,
+        ) => {
+            const config = loadConfig(
+                cmd.optsWithGlobals() as Partial<ConfigSchema>,
+            );
+
+            assertSafeName(name, "nav-item name");
+
+            const pluginDir = config.pluginDir || process.cwd();
+            const manifestPath = path.resolve(pluginDir, "manifest.json");
+
+            // Derive nav-item metadata
+            const label = toPascalCase(name);
+            const targetPath = options.path || "/" + name;
+            const icon = options.icon || "page";
+            const parent = options.parent;
+            const badge = options.badge;
+
+            const spinner = createSpinner(`Adding nav-item: ${name}`);
+
+            try {
+                // Nav-item is manifest-only — no file created
+                if (!fs.existsSync(manifestPath)) {
+                    throw new Error(
+                        `No manifest.json found at ${manifestPath} — skipping.`,
+                    );
+                }
+                const manifest = JSON.parse(
+                    fs.readFileSync(manifestPath, "utf-8"),
+                );
+
+                // Initialize pages array if it doesn't exist
+                if (!manifest.pages) {
+                    manifest.pages = [];
+                }
+
+                // Check for duplicate before appending
+                const isDuplicate = manifest.pages.some(
+                    (e: any) => e.path === targetPath,
+                );
+
+                if (isDuplicate) {
+                    throw new Error(
+                        `Nav-item at ${targetPath} already exists in manifest.json — skipping.`,
+                    );
+                }
+                // Construct nav-entry as a plain JS object (avoids JSON injection via EJS)
+                const navEntry: Record<string, any> = {
+                    label,
+                    path: targetPath,
+                    icon,
+                    sidebar: true,
+                };
+                if (parent) navEntry.parent = parent;
+                if (badge) navEntry.badge = badge;
+                manifest.pages.push(navEntry);
+
+                // Write updated manifest.json back (preserving existing data)
+                fs.writeFileSync(
+                    manifestPath,
+                    JSON.stringify(manifest, null, 2) + "\n",
+                    "utf-8",
+                );
+
+                spinner.succeed();
+
+                success(`Nav-item added:`);
+                info(`  manifest.json ← ${label} (${targetPath})`);
+            } catch (err: any) {
+                spinner.fail();
+                logError(`Failed to add nav-item: ${err.message}`);
+                process.exit(1);
+            }
+        },
+    );

package/src/commands/add-page.ts

@@ -0,0 +1,100 @@
+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, ConfigSchema } from "../config";
+import { assertSafeName } from "../utils/validation";
+import { toPascalCase } from "../utils/formatting";
+
+export const addPageCommand = new Command("page")
+    .argument("<name>", "Page name (e.g., dashboard)")
+    .option("-r, --route <path>", "URL path (e.g., /my-page)")
+    .option("-i, --icon <icon>", "Material Symbol icon name")
+    .description("Generate a Vue 3 page component and update manifest.json")
+    .action(
+        async (
+            name: string,
+            options: { route?: string; icon?: string },
+            cmd: Command,
+        ) => {
+            const config = loadConfig(
+                cmd.optsWithGlobals() as Partial<ConfigSchema>,
+            );
+
+            assertSafeName(name, "page name");
+
+            const pluginDir = config.pluginDir || process.cwd();
+            const manifestPath = path.resolve(pluginDir, "manifest.json");
+
+            // Derive page metadata
+            const label = toPascalCase(name);
+            const route = options.route || "/" + name;
+            const icon = options.icon || "page";
+
+            const templatesDir = path.resolve(__dirname, "../../templates");
+            const pagesDir = path.resolve(pluginDir, "pages");
+
+            const spinner = createSpinner(`Generating page: ${name}`);
+
+            try {
+                if (!fs.existsSync(manifestPath)) {
+                    throw new Error(
+                        `No manifest.json found at ${manifestPath} — skipping manifest update.`,
+                    );
+                }
+                renderAndWrite(
+                    path.join(templatesDir, "page", "page.vue.ejs"),
+                    path.join(pagesDir, `${name}.vue`),
+                    { name, label, route, icon },
+                );
+                const manifest = JSON.parse(
+                    fs.readFileSync(manifestPath, "utf-8"),
+                );
+
+                // Initialize pages array if it doesn't exist
+                if (!manifest.pages) {
+                    manifest.pages = [];
+                }
+
+                // Check for duplicate before appending (GEN-05)
+                const isDuplicate = manifest.pages.some(
+                    (e: any) => e.path === route,
+                );
+
+                if (isDuplicate) {
+                    spinner.succeed();
+                    info(
+                        `Page ${route} already exists in manifest.json — skipping.`,
+                    );
+                    return;
+                }
+                manifest.pages.push({ label, path: route, sidebar: true });
+
+                // Write updated manifest.json back (preserving existing data)
+                fs.writeFileSync(
+                    manifestPath,
+                    JSON.stringify(manifest, null, 2) + "\n",
+                    "utf-8",
+                );
+
+                spinner.succeed();
+
+                success(`Page created:`);
+                info(`  pages/${name}.vue`);
+                info(`  manifest.json ← ${label} (${route})`);
+                info(
+                    `Register this page in pages/main.ts by importing and adding to the pages array.`,
+                );
+            } catch (err: any) {
+                spinner.fail();
+                logError(`Failed to generate page: ${err.message}`);
+                process.exit(1);
+            }
+        },
+    );