@magentrix-corp/magentrix-cli 1.0.0

package/actions/create.js

@@ -0,0 +1,329 @@
+import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+import { createEntity } from "../utils/magentrix/api/createEntity.js";
+import { search, select, input } from "@inquirer/prompts";
+import { listEntities } from "../utils/magentrix/api/retrieveEntity.js";
+import { getClassTemplate, getControllerTemplate, getPageTemplate, getTriggerTemplate } from "../utils/template.js";
+import { withSpinner } from "../utils/spinner.js";
+import { EXPORT_ROOT, TYPE_DIR_MAP } from "../vars/global.js";
+import path from "path";
+import fs from 'fs';
+import chalk from 'chalk';
+import { setFileTag } from "../utils/filetag.js";
+import { updateBase } from "../utils/updateFileBase.js";
+
+// Credentials and entity cache (module-scope for re-use during prompt session)
+let credentials = {};
+let triggerEntities = [];
+
+/**
+ * Loads all entities from the Magentrix API and prepares them
+ * for searchable selection in the CLI.
+ * Populates the `triggerEntities` array.
+ * 
+ * @async
+ * @returns {Promise<void>}
+ */
+const loadEntities = async () => {
+    const entities = await listEntities(credentials.instanceUrl, credentials.token.value);
+    // Map to inquirer-friendly objects: { name, value }
+    triggerEntities = entities.map(entity => ({
+        label: entity.Label,
+        value: entity.Id,
+        name: entity.Name
+    }));
+};
+
+/**
+ * Search function for entity selection using @inquirer/prompts.
+ * Filters `triggerEntities` array based on the user's input term.
+ * 
+ * @async
+ * @param {string} term - User's search input.
+ * @returns {Promise<Array>} Filtered entity choices for prompt.
+ */
+const searchEntities = async (term = '') => {
+    // Case-insensitive substring match against entity names
+    const filteredEntities = triggerEntities.filter(entity =>
+        entity.name.toLowerCase().includes(term.toLowerCase())
+    );
+
+    // Format for inquirer searchable prompt
+    return filteredEntities.map(entity => ({
+        name: `${entity.label} (${entity.value})`,
+        value: entity.value,
+        // Optionally: description: `Entity ID ${entity.value}`
+    }));
+};
+
+/**
+ * CLI prompt flow for creating an ActiveClass record.
+ * 
+ * - Prompts for type (Controller, Utility, or Trigger)
+ * - For Trigger, also prompts for target entity selection (searchable)
+ * - Prompts for class name and optional description
+ * 
+ * @async
+ * @returns {Promise<Object>} The creation payload for ActiveClass.
+ */
+const createActiveClass = async () => {
+    const classType = await select({
+        message: "Select ActiveClass type:",
+        choices: [
+            { name: "Controller", value: "Controller" },
+            { name: "Class", value: "Utility" },
+            { name: "Trigger", value: "Trigger" }
+        ]
+    });
+
+    if (classType === "Trigger") {
+        // Ensure entity list is loaded for search prompt
+        await loadEntities();
+
+        const entityId = await search({
+            message: "Search and select entity for this Trigger:",
+            source: searchEntities,
+            pageSize: 8
+        });
+
+        const className = await input({
+            message: "Trigger class name:",
+            validate: (input) => input.length > 0 || "Please enter a class name"
+        });
+
+        const description = await input({
+            message: "Description (optional):"
+        });
+
+        return {
+            type: "ActiveClass",
+            classType,
+            triggerEntityId: entityId,
+            className,
+            description,
+        };
+    }
+
+    const hint = classType === "Controller" ? "(without controller keyword)" : ""
+
+    // Flow for Controller or Utility
+    const className = await input({
+        message: `${classType} class name ${hint}:`,
+        validate: (input) => input.length > 0 || "Please enter a class name"
+    });
+
+    const description = await input({
+        message: "Description (optional):"
+    });
+
+    return {
+        type: "ActiveClass",
+        classType,
+        className,
+        description,
+    };
+};
+
+/**
+ * CLI prompt flow for creating an ActivePage record.
+ * 
+ * - Prompts for page name and optional description.
+ * 
+ * @async
+ * @returns {Promise<Object>} The creation payload for ActivePage.
+ */
+const createActivePage = async () => {
+    const pageType = await select({
+        message: "Select ActivePage type:",
+        choices: [
+            { name: "Page", value: "Page" },
+            { name: "Template", value: "Template" }
+        ]
+    });
+
+    const pageName = await input({
+        message: `${pageType} name:`,
+        validate: (input) => input.length > 0 || `Please enter a ${pageType.toLowerCase()} name`
+    });
+
+    const description = await input({
+        message: "Description (optional):"
+    });
+
+    return {
+        type: pageType,
+        pageName,
+        description,
+    };
+};
+
+/**
+ * Saves the generated file content to the appropriate local folder.
+ * @param {string} entityType
+ * @param {object} formattedData
+ * @param {string} recordId
+ * @returns {Promise<string>} Full path of created file.
+ */
+const saveToFile = async (entityType, formattedData, recordId) => {
+    let fileDir, fileExt, fileName, fileContent;
+
+    let mapKey; // fallback to Page
+    if (entityType === "ActivePage") {
+        mapKey = formattedData.Type || "Active Page";
+        fileDir = TYPE_DIR_MAP[mapKey].directory;
+        fileExt = TYPE_DIR_MAP[mapKey].extension;
+        fileName = `${formattedData.Name}.${fileExt}`;
+        fileContent = formattedData.Content || "";
+    } else {
+        mapKey = formattedData.Type || "Class"; // fallback to Class
+        fileDir = TYPE_DIR_MAP[mapKey].directory;
+        fileExt = TYPE_DIR_MAP[mapKey].extension;
+        fileName = `${formattedData.Name}.${fileExt}`;
+        fileContent = formattedData.Body || "";
+    }
+
+    // Ensure directory exists
+    const outputDir = path.join(process.cwd(), EXPORT_ROOT, fileDir);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    // Full file path
+    const filePath = path.join(outputDir, fileName);
+
+    // Write file
+    fs.writeFileSync(filePath, fileContent);
+
+    // Add a file tag so we can keep track of file changes
+    await setFileTag(filePath, recordId);
+    updateBase(filePath, { Id: recordId, Type: mapKey }); // Update base
+
+    return filePath;
+};
+
+/**
+ * Main CLI handler for `magentrix create`.
+ * 
+ * - Ensures valid Magentrix credentials.
+ * - Prompts user to choose entity type (ActiveClass or ActivePage).
+ * - Runs the appropriate prompt flow to gather data.
+ * - Logs (or sends) the resulting payload.
+ * 
+ * @async
+ * @function create
+ * @returns {Promise<void>}
+ */
+export const create = async () => {
+    // Clear the terminal
+    process.stdout.write('\x1Bc');
+
+    // 1. Prompt for and validate Magentrix credentials
+    credentials = await withSpinner('Authenticating...', async () => {
+        return await ensureValidCredentials();
+    });
+
+    // 2. Prompt user to select the type of entity to create
+    const entityType = await select({
+        message: "What would you like to create?",
+        choices: [
+            { name: "ActiveClass (Controller, Class, Trigger)", value: "ActiveClass" },
+            { name: "ActivePage (ASPX Page)", value: "ActivePage" },
+        ]
+    });
+
+    // 3. Build payload via relevant prompt flow
+    let result;
+    if (entityType === 'ActiveClass') {
+        result = await createActiveClass();
+    } else if (entityType === 'ActivePage') {
+        result = await createActivePage();
+    } else {
+        // Unknown
+        throw new Error("Unknown type selected.");
+    }
+
+    // 4. Display or send payload to Magentrix API
+    let formattedData;
+
+    if (entityType === "ActivePage") {
+        formattedData = {
+            Label: result.pageName,
+            Name: result.pageName,
+            Description: result.description || "",
+            Type: `Active ${result.type}`,
+            Content: getPageTemplate(result.pageName, result.pageName)
+        };
+    } else if (entityType === "ActiveClass") {
+        let name = result.className;
+
+        if (result.classType === "Controller") {
+            if (!name.endsWith("Controller")) name += "Controller";
+            formattedData = {
+                Name: name,
+                Body: getControllerTemplate(name),
+                Description: result.description || "",
+                Type: "Controller"
+            };
+        } else if (result.classType === "Utility" || result.classType === "Class") {
+            formattedData = {
+                Name: name,
+                Body: getClassTemplate(name),
+                Description: result.description || "",
+                Type: "Class"
+            };
+        } else if (result.classType === "Trigger") {
+            const selectedTriggerEntity = triggerEntities.find(entity => entity.value === result.triggerEntityId);
+
+            formattedData = {
+                Name: name,
+                Body: getTriggerTemplate(name, selectedTriggerEntity.name),
+                Description: result.description || "",
+                Type: "Trigger",
+                EntityId: result.triggerEntityId
+            };
+        }
+    }
+
+    console.log();
+
+    // Uncomment to perform creation via API:
+    const creationResponse = await withSpinner('Creating file...', async () => {        
+        return await createEntity(
+            credentials.instanceUrl, 
+            credentials.token.value, 
+            entityType, 
+            formattedData
+        ).catch(err => {
+            return { ...err?.response, hasErrors: true };
+        });
+    });
+
+    if (creationResponse?.hasErrors) {
+        console.log();
+        console.log(chalk.bgRed.bold.white('  ✖ Creation Failed  '));
+        console.log(chalk.redBright('─'.repeat(48)));
+        const errors = creationResponse.errors || [];
+
+        if (errors.length > 0) {
+            errors.forEach((err, i) => {
+                const code = err.code ? chalk.gray(`[${err.code}] `) : '';
+                const status = err.status ? chalk.yellow(`[${err.status}] `) : '';
+                const msg = chalk.whiteBright(err.message);
+                console.log(`${chalk.redBright('  •')} ${status}${code}${msg}`);
+            });
+        } else {
+            console.log(chalk.red('An unknown error occurred during deletion.'));
+        }
+
+        return;
+    }
+
+    console.log(`✅ File successfully created on Magentrix server.`);
+
+    try {
+        const filePath = await saveToFile(entityType, formattedData, creationResponse.id);
+        console.log(`📄 Local copy saved at: ${filePath}`);
+        console.log('✨ You can now edit this file locally. Don\'t forget to push changes when ready!');
+    } catch (err) {
+        console.error(`🚨 Error: Unable to save file locally (${err.message}).`);
+        console.error('You may need to check directory permissions or disk space.');
+    }
+
+};

package/actions/help.js

@@ -0,0 +1,165 @@
+import chalk from "chalk";
+import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+
+/* ─────────────────────────────
+   🎨  COLOR & STYLE SHORTCUTS
+   ───────────────────────────── */
+const style = {
+    header: chalk.bold.magenta,
+    section: chalk.underline.bold,
+    label: chalk.gray,
+    command: chalk.cyan,
+    highlight: chalk.yellow,
+    bullet: chalk.green("●"),
+    dim: chalk.dim,
+};
+
+/* ─────────────────────────────
+   📋  DATA SOURCES
+   ───────────────────────────── */
+
+/** All CLI commands with their one-line descriptions.  */
+const COMMANDS = [
+    { command: "magentrix", description: "Show current environment and status" },
+    { command: "magentrix setup", description: "Configure / update URL & API key" },
+    { command: "magentrix pull", description: "Fetch all code into this folder" },
+    { command: "magentrix lint", description: "Check for stale files or conflicts" },
+    { command: "magentrix autopublish", description: "Automatically push local file changes safely to Magentrix" },
+    { command: "magentrix status", description: "Show local vs remote differences" },
+    { command: "magentrix create", description: "Interactive wizard for new files" },
+    { command: "magentrix --help", description: "Show this comprehensive help guide" },
+];
+
+/** Key folders that appear after a successful `magentrix pull`. */
+const FOLDERS = [
+    { path: "src/pages", note: "Active Pages (.aspx)" },
+    { path: "src/controllers", note: "Controller_*.cls files" },
+    { path: "src/classes", note: "Utility / helper .cls files" },
+    { path: "src/triggers", note: "Trigger_*.cls files" },
+    { path: ".magentrix/index.json", note: "Mapping & metadata" },
+];
+
+/* ─────────────────────────────
+   🖨️  PRINT HELPERS
+   ───────────────────────────── */
+
+/**
+ * Renders the comprehensive help header with current environment info.
+ *
+ * @param {string} maskedKey  – API key with only last 4 chars visible.
+ * @param {string} hostname   – Magentrix instance hostname.
+ */
+const printHelpHeader = (maskedKey, hostname) => {
+    console.log(style.header("\n📚  Magentrix CLI - Help & Usage Guide"));
+    console.log(style.dim("─────────────────────────────────────────────"));
+    console.log(
+        `${style.label("API Key:")} ${style.highlight(maskedKey)}    ` +
+        `${style.label("Environment:")} ${style.highlight(hostname)}\n`,
+    );
+};
+
+/** Prints a comprehensive description of what this tool does. */
+const printDescription = () => {
+    console.log(
+        style.section("What is Magentrix CLI?"),
+        "\n" +
+        chalk.cyanBright(
+            "Sync Active Pages & Classes between Magentrix and your editor—",
+        ) +
+        "edit locally, lint, then publish back safely.\n" +
+        style.dim("No built-in Git hooks—manage Git however you like.\n"),
+    );
+};
+
+/** Prints the 5-step recommended workflow. */
+const printWorkflow = () => {
+    console.log(style.section("Typical Workflow:"));
+    const STEPS = [
+        { label: "Setup", cmd: "magentrix setup", detail: "Enter URL & API key (one-time)" },
+        { label: "Pull", cmd: "magentrix pull", detail: "Fetch code locally" },
+        { label: "Edit", cmd: "—", detail: "Use any code editor" },
+        { label: "Lint", cmd: "magentrix lint", detail: "Check for conflicts" },
+        { label: "Publish", cmd: "magentrix publish", detail: "Push changes safely" },
+    ];
+    STEPS.forEach(({ label, cmd, detail }) => {
+        console.log(
+            `  ${style.bullet} ${label.padEnd(7)}  ${style.command(cmd.padEnd(20))} ${style.dim(detail)}`,
+        );
+    });
+    console.log(); // blank line
+};
+
+/** Prints the local folder overview in an uncluttered list. */
+const printFolders = () => {
+    console.log(style.section("Local Folder Structure:"));
+    FOLDERS.forEach(({ path, note }) => {
+        console.log(`  ${style.command(path.padEnd(22))} ${style.dim(note)}`);
+    });
+    console.log();
+};
+
+/** Prints the full command table. */
+const printCommands = () => {
+    console.log(style.section("Available Commands:"));
+    COMMANDS.forEach(({ command, description }) => {
+        console.log(`  ${style.command(command.padEnd(22))} ${description}`);
+    });
+    console.log();
+};
+
+/** Prints quick best-practice reminders. */
+const printTips = () => {
+    console.log(style.section("Best Practices:"));
+    [
+        "Always pull before editing.",
+        "Lint before publishing.",
+        "Optional: enable auto-publish on save during setup.",
+        "Magentrix is the source of truth; Git lives beside it.",
+    ].forEach(tip => console.log(`  ${style.bullet} ${tip}`));
+    console.log();
+};
+
+/** Prints additional resources and support info. */
+const printFooter = () => {
+    console.log(
+        style.dim("Need more details? See the project README or documentation.\n"),
+    );
+};
+
+/* ─────────────────────────────
+   🚀  HELP ENTRY POINT
+   ───────────────────────────── */
+
+/**
+ * Magentrix CLI comprehensive help display.
+ *
+ * 1. Ensure credentials are configured (to show current environment).
+ * 2. Display detailed usage guide, commands, workflow, and best practices.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+export const showHelp = async () => {
+    const { apiKey, instanceUrl } = await ensureValidCredentials();
+
+    /* Mask the key except last 4 chars */
+    const maskedKey = `****${apiKey.slice(-4)}`;
+
+    /* Extract hostname from URL—for display only */
+    const hostname = (() => {
+        try {
+            return new URL(instanceUrl).hostname;
+        } catch {
+            return instanceUrl.replace(/^https?:\/\//, "").split("/")[0];
+        }
+    })();
+
+    /* Render comprehensive help sections */
+    printHelpHeader(maskedKey, hostname);
+    printDescription();
+    printWorkflow();
+    printFolders();
+    printCommands();
+    printTips();
+    printFooter();
+};

package/actions/main.js

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+import { withSpinner } from "../utils/spinner.js";
+
+/* ─────────────────────────────
+   🎨  COLOR & STYLE SHORTCUTS
+   ───────────────────────────── */
+const style = {
+    header: chalk.bold.magenta,
+    label: chalk.gray,
+    highlight: chalk.yellow,
+    dim: chalk.dim,
+    command: chalk.cyan,
+};
+
+/* ─────────────────────────────
+   🖨️  PRINT HELPERS
+   ───────────────────────────── */
+
+/**
+ * Renders a simple welcome header with current environment info.
+ *
+ * @param {string} maskedKey  – API key with only last 4 chars visible.
+ * @param {string} hostname   – Magentrix instance hostname.
+ */
+const printWelcomeHeader = (maskedKey, hostname) => {
+    console.log(style.header("\n🎉  Magentrix CLI"));
+    console.log(style.dim("─────────────────────────────────────────────"));
+    console.log(
+        `${style.label("API Key:")} ${style.highlight(maskedKey)}    ` +
+        `${style.label("Environment:")} ${style.highlight(hostname)}\n`,
+    );
+};
+
+/**
+ * Prints a brief status message and help prompt.
+ */
+const printStatusMessage = () => {
+    console.log("✅ Connected and ready to sync with Magentrix.");
+    console.log(
+        style.dim("Run ") +
+        style.command("magentrix --help") +
+        style.dim(" to see all available commands and workflow guidance.\n"),
+    );
+};
+
+/* ─────────────────────────────
+   🚀  MAIN ENTRY POINT
+   ───────────────────────────── */
+
+/**
+ * Magentrix CLI main entry point.
+ *
+ * 1. Ensure valid credentials are configured.
+ * 2. Display current environment and connection status.
+ * 3. Prompt user to run help for detailed usage.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+export const main = async () => {
+    const { apiKey, instanceUrl } = await withSpinner('Authenticating...', async () => {
+        return await ensureValidCredentials();
+    });
+
+    /* Mask the key except last 4 chars */
+    const maskedKey = `****${apiKey.slice(-4)}`;
+
+    /* Extract hostname from URL—for display only */
+    const hostname = (() => {
+        try {
+            return new URL(instanceUrl).hostname;
+        } catch {
+            return instanceUrl.replace(/^https?:\/\//, "").split("/")[0];
+        }
+    })();
+
+    /* Show current environment and status */
+    printWelcomeHeader(maskedKey, hostname);
+    printStatusMessage();
+};