selection, configuration and settings of CLI local development

Author: Meldiron

src/SDK/Language/CLI.php

@@ -182,6 +182,11 @@ public function getFiles(): array
                 'destination'   => 'lib/commands/push.js',
                 'template'      => 'cli/lib/commands/push.js.twig',
             ],
+            [
+                'scope'         => 'default',
+                'destination'   => 'lib/commands/run.js',
+                'template'      => 'cli/lib/commands/run.js.twig',
+            ],
             [
                 'scope'         => 'service',
                 'destination'   => '/lib/commands/{{service.name | caseDash}}.js',

templates/cli/index.js.twig

@@ -13,6 +13,7 @@ const { client } = require("./lib/commands/generic");
 {% if sdk.test != "true" %}
 const { login, logout, whoami } = require("./lib/commands/generic");
 const { pull } = require("./lib/commands/pull");
+const { run } = require("./lib/commands/run");
 const { push } = require("./lib/commands/push");
 {% endif %}
 {% for service in spec.services %}
@@ -40,6 +41,7 @@ program
   .addCommand(login)
   .addCommand(pull)
   .addCommand(push)
+  .addCommand(run)
   .addCommand(logout)
 {% endif %}
 {% for service in spec.services %}

templates/cli/lib/commands/run.js.twig

@@ -0,0 +1,121 @@
+const inquirer = require("inquirer");
+const { Command } = require("commander");
+const { localConfig, globalConfig } = require("../config");
+const { paginate } = require('../paginate');
+const { questionsRunFunctions } = require("../questions");
+const { actionRunner, success, log, error, commandDescriptions, drawTable } = require("../parser");
+const { systemHasCommand, isPortTaken } = require('../utils');
+
+const systemTools = {
+    'node': {
+        commands: [
+            { command: "node", docs: "https://nodejs.org/en/download/package-manager" },
+            { command: "npm", docs: "https://nodejs.org/en/download/package-manager" },
+        ],
+        dependencyFiles: [ "package.json", "package-lock.json" ]
+    },
+    // TODO: Add all runtime needs
+};
+
+const runFunction = async ({ port, engine, functionId } = {}) => {
+    // Selection
+    if(!functionId) {
+        const answers = await inquirer.prompt(questionsRunFunctions[0]);
+        functionId = answers.function;
+    }
+
+    const functions = localConfig.getFunctions();
+    const func = functions.find((f) => f.$id === functionId);
+    if (!func) {
+        throw new Error("Function '" + functionId + "' not found.")
+    }
+
+    // Configuration: Port
+    if(port) {
+        port = +port;
+    }
+
+    if(isNaN(port)) {
+        port = null;
+    }
+
+    if(port) {
+        const taken = await isPortTaken(port);
+
+        if(taken) {
+            log(`Port ${port} is already used.`);
+            port = null;
+        }
+    }
+
+    if(!port) {
+        const answers = await inquirer.prompt(questionsRunFunctions[1]);
+        port = answers.port;
+    }
+
+    // Configuration: Engine
+    if(engine !== "system" && engine !== "docker") {
+        engine = null;
+    }
+
+    if(!engine) {
+        const answers = await inquirer.prompt(questionsRunFunctions[2]);
+        engine = answers.engine;
+    }
+
+    if(engine === 'docker') {
+        log('💡 Hint: Using system is faster, but using Docker simulates the production environment precisely.');
+
+        if(!systemHasCommand('docker')) {
+            return error("Please install Docker first: https://docs.docker.com/engine/install/");
+        }
+    } else if(engine === 'system') {
+        log('💡 Hint: Docker simulates the production environment precisely, but using system is faster');
+
+        const runtimeName = func.runtime.split('-')[0];
+        const tool = systemTools[runtimeName];
+
+        for(const command of tool.commands) {
+            if(!systemHasCommand(command.command)) {
+                return error(`Your system is missing command "${command.command}". Please install it first: ${command.docs}`);
+            }
+        }
+    }
+
+    // Settings
+    const settings = {
+        runtime: func.runtime,
+        entrypoint: func.entrypoint,
+        path: func.path,
+        commands: func.commands,
+    };
+    log("Local function configuration:");
+    drawTable([settings]);
+    log('If you wish to change local settings, update appwrite.json file and rerun the command. To deploy the function, run: appwrite push function');
+
+    childProcess.execSync('where ' + command, { stdio: 'pipe' })
+
+}
+
+const run = new Command("run")
+    .alias("dev")
+    .description(commandDescriptions['run'])
+    .configureHelp({
+        helpWidth: process.stdout.columns || 80
+    })
+    .action(actionRunner(async (_options, command) => {
+        command.help();
+    }));
+
+run
+    .command("function")
+    .alias("functions")
+    .description("Run functions in the current directory.")
+    .option(`--functionId <functionId>`, `Function ID`)
+    .option(`--port <port>`, `Local port`)
+    .option(`--engine <engine>`, `Local engine, "system" or "docker"`)
+    .action(actionRunner(runFunction));
+
+module.exports = {
+    run
+}

templates/cli/lib/parser.js.twig

@@ -157,6 +157,7 @@ const commandDescriptions = {
     "avatars": `The avatars command aims to help you complete everyday tasks related to your app image, icons, and avatars.`,
     "databases": `The databases command allows you to create structured collections of documents, query and filter lists of documents.`,
     "push": `The push command provides a convenient wrapper for pushing your functions, collections, buckets, teams and messaging.`,
+    "run": `The dev command allows you to run project locally to allow easy development and quick debugging.`,
     "functions": `The functions command allows you view, create and manage your Cloud Functions.`,
     "health": `The health command allows you to both validate and monitor your {{ spec.title|caseUcfirst }} server's health.`,
     "pull": `The pull command helps you pull your {{ spec.title|caseUcfirst }} project, functions, collections, buckets, teams and messaging`,

templates/cli/lib/questions.js.twig

@@ -6,6 +6,7 @@ const { accountListMfaFactors } = require("./commands/account");
 const { sdkForConsole } = require("./sdks");
 const { validateRequired } = require("./validations");
 const { paginate } = require('./paginate');
+const { isPortTaken } = require('./utils');
 
 const { databasesList } = require('./commands/databases');
 const JSONbig = require("json-bigint")({ storeAsString: false });
@@ -515,6 +516,76 @@ const questionsMfaChallenge = [
     }
 ];
 
+const questionsRunFunctions = [
+    {
+        type: "list",
+        name: "function",
+        message: "Which function would you like to develop locally?",
+        validate: (value) => validateRequired('function', value),
+        choices: () => {
+            let functions = localConfig.getFunctions();
+            if (functions.length === 0) {
+                throw new Error("No functions found in the current directory.");
+            }
+            let choices = functions.map((func, idx) => {
+                return {
+                    name: `${func.name} (${func.$id})`,
+                    value: func.$id
+                }
+            })
+            return choices;
+        }
+    },
+    {
+        type: "number",
+        name: "port",
+        message: 'Which port would you like function to listen on?',
+        default: async () => {
+            let port = 3000;
+            while(port < 3100) {
+                const taken = await isPortTaken(port);
+                if(!taken) {
+                    return port;
+                }
+
+                port++;
+            }
+
+            return 3000;
+        },
+        validate: function(value) {
+            const done = this.async();
+
+            (async () => {
+                const taken = await isPortTaken(value);
+
+                if(taken) {
+                    throw Error(`Port ${value} is taken. Pick another one.`);
+                }
+            })().then(() => {
+                done(null, true);
+            }).catch((err) => {
+                done(err.message);
+            });
+        },
+    },
+    {
+        type: "list",
+        name: "engine",
+        message: "Which engine would you like to use?",
+        choices: [
+            {
+                name: "Docker",
+                value: "docker",
+            },
+            {
+                name: "System",
+                value: "system",
+            },
+        ],
+    },
+];
+
 module.exports = {
     questionsPullProject,
     questionsLogin,
@@ -528,5 +599,6 @@ module.exports = {
     questionsPushTeams,
     questionsGetEntrypoint,
     questionsListFactors,
-    questionsMfaChallenge
+    questionsMfaChallenge,
+    questionsRunFunctions
 };

templates/cli/lib/utils.js.twig

@@ -1,5 +1,7 @@
 const fs = require("fs");
 const path = require("path");
+const net = require("net");
+const childProcess = require('child_process');
 
 function getAllFiles(folder) {
     const files = [];
@@ -14,6 +16,42 @@ function getAllFiles(folder) {
     return files;
 }
 
+async function isPortTaken(port) {
+    const taken = await new Promise((res, rej) => {
+        const tester = net.createServer()
+        .once('error', function (err) {
+            if (err.code != 'EADDRINUSE') return rej(err)
+                res(true)
+            })
+            .once('listening', function() {
+                tester.once('close', function() { res(false) })
+                .close()
+            })
+            .listen(port);
+    });
+
+    return taken;
+}
+
+function systemHasCommand(command) {
+    const isUsingWindows = process.platform == 'win32'
+
+     try {
+        if(isUsingWindows) {
+            childProcess.execSync('where ' + command, { stdio: 'pipe' })
+        } else {
+            childProcess.execSync(`[[ $(${command} --version) ]] || { exit 1; } && echo "OK"`, { stdio: 'pipe', shell: '/bin/bash' });
+        }
+    } catch (error) {
+        console.log(error);
+        return false;
+    }
+
+    return true;
+}
+
 module.exports = {
-    getAllFiles
+    getAllFiles,
+    isPortTaken,
+    systemHasCommand
 };