@nexical/cli 0.1.6 → 0.10.0

package/src/commands/module/list.ts

@@ -0,0 +1,69 @@
+import { BaseCommand, logger } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
+
+export default class ModuleListCommand extends BaseCommand {
+    static usage = 'module list';
+    static description = 'List installed modules.';
+    static requiresProject = true;
+
+    async run() {
+        const projectRoot = this.projectRoot as string;
+        const modulesDir = path.resolve(projectRoot, 'modules');
+        logger.debug(`Scanning for modules in: ${modulesDir}`);
+
+        if (!(await fs.pathExists(modulesDir))) {
+            this.info('No modules installed (modules directory missing).');
+            return;
+        }
+
+        try {
+            const modules = await fs.readdir(modulesDir);
+            const validModules: { name: string; version: string; description: string }[] = [];
+
+            for (const moduleName of modules) {
+                const modulePath = path.join(modulesDir, moduleName);
+                if ((await fs.stat(modulePath)).isDirectory()) {
+                    let version = 'unknown';
+                    let description = '';
+
+                    const pkgJsonPath = path.join(modulePath, 'package.json');
+                    const moduleYamlPath = path.join(modulePath, 'module.yaml');
+                    const moduleYmlPath = path.join(modulePath, 'module.yml');
+
+                    let pkg: any = {};
+                    let modConfig: any = {};
+
+                    if (await fs.pathExists(pkgJsonPath)) {
+                        try {
+                            pkg = await fs.readJson(pkgJsonPath);
+                        } catch (e) { /* ignore */ }
+                    }
+
+                    if (await fs.pathExists(moduleYamlPath) || await fs.pathExists(moduleYmlPath)) {
+                        try {
+                            const configPath = await fs.pathExists(moduleYamlPath) ? moduleYamlPath : moduleYmlPath;
+                            const content = await fs.readFile(configPath, 'utf8');
+                            modConfig = YAML.parse(content) || {};
+                        } catch (e) { /* ignore */ }
+                    }
+
+                    version = pkg.version || 'unknown';
+                    description = modConfig.description || pkg.description || '';
+                    // Optionally use display name from module.yaml if present, but strictly list is usually dir name.
+                    // Let's stick to dir name for "name" column, but description from module.yaml is good.
+                    validModules.push({ name: moduleName, version, description });
+                }
+            }
+
+            if (validModules.length === 0) {
+                this.info('No modules installed.');
+            } else {
+                console.table(validModules);
+            }
+        } catch (error: any) {
+            this.error(`Failed to list modules: ${error.message}`);
+        }
+    }
+}

package/src/commands/module/remove.ts

@@ -0,0 +1,74 @@
+import { type CommandDefinition, BaseCommand, logger, runCommand } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
+
+export default class ModuleRemoveCommand extends BaseCommand {
+    static usage = 'module remove <name>';
+    static description = 'Remove an installed module.';
+    static requiresProject = true;
+
+    static args: CommandDefinition = {
+        args: [
+            { name: 'name', required: true, description: 'Name of the module to remove' }
+        ]
+    };
+
+    async run(options: any) {
+        const projectRoot = this.projectRoot as string;
+        let { name } = options;
+
+        const relativePath = `modules/${name}`;
+        const fullPath = path.resolve(projectRoot, relativePath);
+
+        logger.debug('Removing module at:', fullPath);
+
+        if (!(await fs.pathExists(fullPath))) {
+            this.error(`Module ${name} not found at ${relativePath}.`);
+            return;
+        }
+
+        this.info(`Removing module ${name}...`);
+
+        try {
+            await runCommand(`git submodule deinit -f ${relativePath}`, projectRoot);
+            await runCommand(`git rm -f ${relativePath}`, projectRoot);
+
+            // Clean up .git/modules
+            const gitModulesDir = path.resolve(projectRoot, '.git', 'modules', 'modules', name);
+            if (await fs.pathExists(gitModulesDir)) {
+                await fs.remove(gitModulesDir);
+            }
+
+            this.info('Syncing workspace dependencies...');
+            await runCommand('npm install', projectRoot);
+
+
+            await this.removeFromConfig(name);
+
+            this.success(`Module ${name} removed successfully.`);
+        } catch (e: any) {
+            this.error(`Failed to remove module: ${e.message}`);
+        }
+    }
+
+    private async removeFromConfig(moduleName: string) {
+        const projectRoot = this.projectRoot as string;
+        const configPath = path.join(projectRoot, 'nexical.yaml');
+
+        if (!await fs.pathExists(configPath)) return;
+
+        try {
+            const content = await fs.readFile(configPath, 'utf8');
+            let config = YAML.parse(content) || {};
+
+            if (config.modules && config.modules.includes(moduleName)) {
+                config.modules = config.modules.filter((m: string) => m !== moduleName);
+                await fs.writeFile(configPath, YAML.stringify(config));
+                logger.debug(`Removed ${moduleName} from nexical.yaml modules list.`);
+            }
+        } catch (e: any) {
+            logger.warn(`Failed to update nexical.yaml: ${e.message}`);
+        }
+    }
+}

package/src/commands/module/update.ts

@@ -0,0 +1,50 @@
+import { type CommandDefinition, BaseCommand, logger, runCommand } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+
+export default class ModuleUpdateCommand extends BaseCommand {
+    static usage = 'module update [name]';
+    static description = 'Update a specific module or all modules.';
+    static requiresProject = true;
+
+    static args: CommandDefinition = {
+        args: [
+            { name: 'name', required: false, description: 'Name of the module to update' }
+        ]
+    };
+
+    async run(options: any) {
+        const projectRoot = this.projectRoot as string;
+        let { name } = options;
+
+        this.info(name ? `Updating module ${name}...` : 'Updating all modules...');
+        logger.debug('Update context:', { name, projectRoot: projectRoot });
+
+        try {
+            if (name) {
+                const relativePath = `modules/${name}`;
+                const fullPath = path.resolve(projectRoot, relativePath);
+
+                if (!(await fs.pathExists(fullPath))) {
+                    this.error(`Module ${name} not found.`);
+                    return;
+                }
+
+                // Update specific module
+                // We enter the directory and pull? Or generic submodule update?
+                // Generic submodule update --remote src/modules/name
+                await runCommand(`git submodule update --remote --merge ${relativePath}`, projectRoot);
+            } else {
+                // Update all
+                await runCommand('git submodule update --remote --merge', projectRoot);
+            }
+
+            this.info('Syncing workspace dependencies...');
+            await runCommand('npm install', projectRoot);
+
+            this.success('Modules updated successfully.');
+        } catch (e: any) {
+            this.error(`Failed to update modules: ${e.message}`);
+        }
+    }
+}

package/src/commands/run.ts

@@ -0,0 +1,98 @@
+import { type CommandDefinition, BaseCommand, logger } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+import { spawn } from 'child_process';
+import process from 'node:process';
+
+export default class RunCommand extends BaseCommand {
+    static usage = 'run <script> [args...]';
+    static description = 'Run a script inside the Nexical environment.';
+    static requiresProject = true;
+
+    static args: CommandDefinition = {
+        args: [
+            { name: 'script', required: true, description: 'The script to run (script-name OR module:script-name)' },
+            { name: 'args...', required: false, description: 'Arguments for the script' }
+        ]
+    };
+
+    async run(options: any) {
+        const projectRoot = this.projectRoot as string;
+        const script = options.script;
+        const scriptArgs = options.args || [];
+
+        if (!script) {
+            this.error('Please specify a script to run.');
+            return;
+        }
+
+        logger.debug('Run command context:', { script, args: scriptArgs, projectRoot });
+
+        let execPath = projectRoot;
+        let scriptName = script;
+
+        // Handle module:script syntax
+        if (script.includes(':')) {
+            const [moduleName, name] = script.split(':');
+            execPath = path.resolve(projectRoot, 'modules', moduleName);
+            scriptName = name;
+
+            logger.debug(`Resolving module script: ${moduleName}:${scriptName} at ${execPath}`);
+        } else {
+            logger.debug(`Resolving core script: ${scriptName} at ${execPath}`);
+        }
+
+        // Validate script existence
+        const pkgJsonPath = path.join(execPath, 'package.json');
+        if (!(await fs.pathExists(pkgJsonPath))) {
+            this.error(`Failed to find package.json at ${execPath}`);
+            return;
+        }
+
+        try {
+            const pkg = await fs.readJson(pkgJsonPath);
+            if (!pkg.scripts || !pkg.scripts[scriptName]) {
+                const type = script.includes(':') ? `module ${script.split(':')[0]}` : 'Nexical core';
+                this.error(`Script "${scriptName}" does not exist in ${type}`);
+                return;
+            }
+        } catch (e: any) {
+            this.error(`Failed to read package.json at ${execPath}: ${e.message}`);
+            return;
+        }
+
+        const finalArgs = ['run', scriptName, '--', ...scriptArgs];
+        logger.debug(`Executing: npm ${finalArgs.join(' ')} in ${execPath}`);
+
+        const child = spawn('npm', finalArgs, {
+            cwd: execPath,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                FORCE_COLOR: '1'
+            }
+        });
+
+        // Handle process termination to kill child
+        const cleanup = () => {
+            child.kill();
+            process.exit();
+        };
+
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+
+        await new Promise<void>((resolve) => {
+            child.on('close', (code) => {
+                // Remove listeners to prevent memory leaks if this command is run multiple times in-process (e.g. tests)
+                process.off('SIGINT', cleanup);
+                process.off('SIGTERM', cleanup);
+
+                if (code !== 0) {
+                    process.exit(code || 1);
+                }
+                resolve();
+            });
+        });
+    }
+}

package/src/utils/discovery.ts

@@ -0,0 +1,134 @@
+import { logger } from '@nexical/cli-core';
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * Discovers command directories to load into the CLI.
+ * 
+ * Scans for:
+ * 1. Core commands (projectRoot/src/commands)
+ * 2. Module commands (projectRoot/src/modules/ * /src/commands)
+ * 
+ * @param projectRoot - The root directory of the project
+ * @returns Array of absolute paths to command directories
+ */
+export function discoverCommandDirectories(projectRoot: string): string[] {
+    const directories: string[] = [];
+    const visited = new Set<string>();
+
+    const addDir = (dir: string) => {
+        const resolved = path.resolve(dir);
+        if (visited.has(resolved)) return;
+
+        if (fs.existsSync(resolved)) {
+            // Check if we already have a similar path (e.g. dist/src/commands vs src/commands)
+            // If we are adding src/commands and dist/src/commands already exists in visited, skip it
+            // and vice versa.
+            const isSrc = resolved.endsWith(path.join('src', 'commands'));
+            const isDist = resolved.includes(path.join('dist', 'src', 'commands')) ||
+                resolved.endsWith(path.join('dist', 'commands'));
+
+            if (isSrc) {
+                const distEquivalent1 = resolved.replace(path.sep + 'src' + path.sep, path.sep + 'dist' + path.sep + 'src' + path.sep);
+                const distEquivalent2 = resolved.replace(path.sep + 'src' + path.sep, path.sep + 'dist' + path.sep);
+                if (visited.has(distEquivalent1) || visited.has(distEquivalent2)) {
+                    logger.debug(`Skipping ${resolved} because a dist version is already registered`);
+                    return;
+                }
+            }
+
+            if (isDist) {
+                const srcEquivalent1 = resolved.replace(path.sep + 'dist' + path.sep, path.sep);
+                const srcEquivalent2 = resolved.replace(path.sep + 'dist' + path.sep + 'src' + path.sep, path.sep + 'src' + path.sep);
+                if (visited.has(srcEquivalent1) || visited.has(srcEquivalent2)) {
+                    // If we just added src, and now we find dist, we should actually REPLACE src with dist
+                    // but for now, the loop order prefers dist, so this case shouldn't happen much.
+                    // However, let's keep it simple.
+                    logger.debug(`Skipping ${resolved} because a src version is already registered`);
+                    return;
+                }
+            }
+
+            logger.debug(`Found command directory: ${resolved}`);
+            directories.push(resolved);
+            visited.add(resolved);
+        } else {
+            logger.debug(`Command directory not found (skipping): ${resolved}`);
+        }
+    };
+
+    // 1. Core commands
+    // Search in projectRoot
+    const possibleCorePaths = [
+        path.join(projectRoot, 'src/commands'),
+    ];
+
+    possibleCorePaths.forEach(addDir);
+
+    // 2. Module commands
+    const possibleModuleDirs = [
+        path.join(projectRoot, 'modules'),
+        path.join(projectRoot, 'src', 'modules') // Support both flat and src-nested
+    ];
+
+    possibleModuleDirs.forEach(modulesDir => {
+        if (fs.existsSync(modulesDir)) {
+            try {
+                const modules = fs.readdirSync(modulesDir);
+                for (const mod of modules) {
+                    // exclude system files/dirs like .keep
+                    if (mod.startsWith('.')) continue;
+
+                    const modPath = path.join(modulesDir, mod);
+                    if (!fs.statSync(modPath).isDirectory()) continue;
+
+                    // Check for commands inside the module/package
+                    // Order matters: prefer dist if it exists
+                    const possibleCmdPaths = [
+                        path.join(modPath, 'dist/src/commands'),
+                        path.join(modPath, 'dist/commands'),
+                        path.join(modPath, 'src/commands')
+                    ];
+
+                    for (const cmdPath of possibleCmdPaths) {
+                        if (fs.existsSync(cmdPath) && fs.statSync(cmdPath).isDirectory()) {
+                            addDir(cmdPath);
+                        }
+                    }
+                }
+            } catch (e: any) {
+                logger.debug(`Error scanning modules directory ${modulesDir}: ${e.message}`);
+            }
+        }
+    });
+
+    // 3. Package commands (e.g. packages/*)
+    const packagesDir = path.join(projectRoot, 'packages');
+    if (fs.existsSync(packagesDir)) {
+        try {
+            const packages = fs.readdirSync(packagesDir);
+            for (const pkg of packages) {
+                if (pkg.startsWith('.')) continue;
+
+                const pkgPath = path.join(packagesDir, pkg);
+                if (!fs.statSync(pkgPath).isDirectory()) continue;
+
+                const possibleCmdPaths = [
+                    path.join(pkgPath, 'dist/src/commands'),
+                    path.join(pkgPath, 'dist/commands'),
+                    path.join(pkgPath, 'src/commands')
+                ];
+
+                for (const cmdPath of possibleCmdPaths) {
+                    if (fs.existsSync(cmdPath) && fs.statSync(cmdPath).isDirectory()) {
+                        addDir(cmdPath);
+                    }
+                }
+            }
+        } catch (e: any) {
+            logger.debug(`Error scanning packages directory: ${e.message}`);
+        }
+    }
+
+    return directories;
+}

package/src/utils/git.ts

@@ -0,0 +1,65 @@
+import { logger, runCommand } from '@nexical/cli-core';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+export async function clone(url: string, destination: string, options: { recursive?: boolean; depth?: number } = {}): Promise<void> {
+    const { recursive = false, depth } = options;
+    const cmd = `git clone ${recursive ? '--recursive ' : ''}${depth ? `--depth ${depth} ` : ''}${url} .`;
+    logger.debug(`Git clone: ${url} to ${destination}`);
+    await runCommand(cmd, destination);
+}
+
+export async function getRemoteUrl(cwd: string, remote = 'origin'): Promise<string> {
+    try {
+        const { stdout } = await execAsync(`git remote get-url ${remote}`, { cwd });
+        return stdout.trim();
+    } catch (e) {
+        console.error('getRemoteUrl failed:', e);
+        return '';
+    }
+}
+
+export async function updateSubmodules(cwd: string): Promise<void> {
+    logger.debug(`Updating submodules in ${cwd}`);
+    await runCommand('git submodule foreach --recursive "git checkout main && git pull origin main"', cwd);
+}
+
+export async function checkoutOrphan(branch: string, cwd: string): Promise<void> {
+    await runCommand(`git checkout --orphan ${branch}`, cwd);
+}
+
+export async function addAll(cwd: string): Promise<void> {
+    await runCommand('git add -A', cwd);
+}
+
+export async function commit(message: string, cwd: string): Promise<void> {
+    // Escape quotes in message if needed, for now assuming simple messages
+    await runCommand(`git commit -m "${message}"`, cwd);
+}
+
+export async function deleteBranch(branch: string, cwd: string): Promise<void> {
+    await runCommand(`git branch -D ${branch}`, cwd);
+}
+
+export async function renameBranch(branch: string, cwd: string): Promise<void> {
+    await runCommand(`git branch -m ${branch}`, cwd);
+}
+
+export async function removeRemote(remote: string, cwd: string): Promise<void> {
+    await runCommand(`git remote remove ${remote}`, cwd);
+}
+
+export async function renameRemote(oldName: string, newName: string, cwd: string): Promise<void> {
+    await runCommand(`git remote rename ${oldName} ${newName}`, cwd);
+}
+
+export async function branchExists(branch: string, cwd: string): Promise<boolean> {
+    try {
+        await execAsync(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd });
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/utils/url-resolver.ts

@@ -0,0 +1,57 @@
+/**
+ * Resolves a git URL from various shorthand formats.
+ * 
+ * Supported formats:
+ * - gh@org/repo -> https://github.com/org/repo.git
+ * - gh@org/repo//path -> https://github.com/org/repo.git//path
+ * - https://github.com/org/repo -> https://github.com/org/repo.git
+ * - https://github.com/org/repo.git -> https://github.com/org/repo.git
+ * 
+ * @param url The URL string to resolve
+ * @returns The fully qualified git URL with .git extension
+ */
+export function resolveGitUrl(url: string): string {
+    if (!url) {
+        throw new Error('URL cannot be empty');
+    }
+
+    let resolved = url;
+
+    // Handle gh@ syntax
+    if (resolved.startsWith('gh@')) {
+        resolved = resolved.replace(/^gh@/, 'https://github.com/');
+    }
+
+    // Handle subpaths (split by //)
+    // We must be careful not to split the protocol (e.g. https://)
+    const protocolMatch = resolved.match(/^[a-z0-9]+:\/\//i);
+    let splitIndex = -1;
+
+    if (protocolMatch) {
+        splitIndex = resolved.indexOf('//', protocolMatch[0].length);
+    } else {
+        splitIndex = resolved.indexOf('//');
+    }
+
+    let repoUrl = resolved;
+    let subPath = '';
+
+    if (splitIndex !== -1) {
+        repoUrl = resolved.substring(0, splitIndex);
+        subPath = resolved.substring(splitIndex + 2);
+    }
+
+    // Ensure .git extension, but ONLY for remote URLs (not local paths)
+    const isLocal = repoUrl.startsWith('/') || repoUrl.startsWith('./') || repoUrl.startsWith('../') || repoUrl.startsWith('file:') || repoUrl.startsWith('~');
+
+    if (!isLocal && !repoUrl.endsWith('.git')) {
+        repoUrl += '.git';
+    }
+
+    // Reconstruction
+    if (subPath) {
+        return `${repoUrl}//${subPath}`;
+    }
+
+    return repoUrl;
+}