@nexical/cli 0.1.7 → 0.11.0

package/src/commands/module/add.ts

@@ -0,0 +1,169 @@
+import { type CommandDefinition, BaseCommand, logger, runCommand } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+import { clone, getRemoteUrl } from '../../utils/git.js';
+import { resolveGitUrl } from '../../utils/url-resolver.js';
+import YAML from 'yaml';
+
+export default class ModuleAddCommand extends BaseCommand {
+    static usage = 'module add <url>';
+    static description = 'Add a module and its dependencies as git submodules.';
+    static requiresProject = true;
+
+    static args: CommandDefinition = {
+        args: [
+            { name: 'url', required: true, description: 'Git repository URL or gh@org/repo' }
+        ]
+    };
+
+    private visited = new Set<string>();
+
+    async run(options: any) {
+        const projectRoot = this.projectRoot as string;
+        let { url } = options;
+
+        if (!url) {
+            this.error('Please specify a repository URL.');
+            return;
+        }
+
+        try {
+            await this.installModule(url);
+
+            this.info('Syncing workspace dependencies...');
+            await runCommand('npm install', projectRoot);
+
+            this.success('All modules installed successfully.');
+        } catch (e: any) {
+            this.error(`Failed to add module: ${e.message}`);
+        }
+    }
+
+    private async installModule(url: string) {
+        const projectRoot = this.projectRoot as string;
+
+        // Resolve URL using utility
+        url = resolveGitUrl(url);
+
+        const [repoUrl, subPath] = url.split('.git//');
+        const cleanUrl = subPath ? repoUrl + '.git' : url;
+
+        if (this.visited.has(cleanUrl)) {
+            logger.debug(`Already visited ${cleanUrl}, skipping.`);
+            return;
+        }
+        this.visited.add(cleanUrl);
+
+        this.info(`Inspecting ${cleanUrl}...`);
+
+        // Stage 1: Inspect (Temp Clone)
+        const stagingDir = path.resolve(projectRoot!, '.nexical', 'cache', `staging-${Date.now()}-${Math.random().toString(36).substring(7)}`);
+        let moduleName = '';
+        let dependencies: string[] = [];
+
+        try {
+            await fs.ensureDir(stagingDir);
+
+            // Shallow clone to inspect
+            await clone(cleanUrl, stagingDir, { depth: 1 });
+
+            // Read module.yaml
+            const searchPath = subPath ? path.join(stagingDir, subPath) : stagingDir;
+            const moduleYamlPath = path.join(searchPath, 'module.yaml');
+            const moduleYmlPath = path.join(searchPath, 'module.yml');
+
+            let configPath = '';
+            if (await fs.pathExists(moduleYamlPath)) configPath = moduleYamlPath;
+            else if (await fs.pathExists(moduleYmlPath)) configPath = moduleYmlPath;
+            else {
+                throw new Error(`No module.yaml found in ${cleanUrl}${subPath ? '//' + subPath : ''}`);
+            }
+
+            const configContent = await fs.readFile(configPath, 'utf8');
+            const config = YAML.parse(configContent);
+
+            if (!config.name) {
+                throw new Error(`Module at ${url} is missing 'name' in module.yaml`);
+            }
+            moduleName = config.name;
+            dependencies = config.dependencies || [];
+
+            // Normalize dependencies to array if object (though spec says list of strings, defensiveness is good)
+            if (dependencies && !Array.isArray(dependencies)) {
+                dependencies = Object.keys(dependencies);
+            }
+
+        } catch (e: any) { // Catching as 'any' for error message access
+            throw e;
+        } finally {
+            // Cleanup staging always
+            await fs.remove(stagingDir);
+        }
+
+        // Stage 2: Conflict Detection
+        const targetDir = path.join(projectRoot!, 'modules', moduleName);
+        const relativeTargetDir = path.relative(projectRoot!, targetDir);
+
+        if (await fs.pathExists(targetDir)) {
+            // Check origin
+            const existingRemote = await getRemoteUrl(targetDir);
+            // We compare cleanUrl (the repo root).
+            // normalize both
+            const normExisting = existingRemote.replace(/\.git$/, '');
+            const normNew = cleanUrl.replace(/\.git$/, '');
+
+            if (normExisting !== normNew && existingRemote !== '') {
+                throw new Error(`Dependency Conflict! Module '${moduleName}' exists but remote '${existingRemote}' does not match '${cleanUrl}'.`);
+            }
+
+            this.info(`Module ${moduleName} already installed.`);
+            // Proceed to recurse, but skip add
+        } else {
+            // Stage 3: Submodule Add
+            this.info(`Installing ${moduleName} to ${relativeTargetDir}...`);
+            // We install the ROOT repo.
+            // IMPORTANT: If subPath exists, "Identity is Internal" means we name the folder `moduleName`.
+            // But the CONTENT will be the whole repo.
+            // If the user meant to only have the subdir, we can't do that with submodule add easily without manual git plumbing.
+            // Given instructions, I will proceed with submodule add of root repo to target dir.
+            await runCommand(`git submodule add ${cleanUrl} ${relativeTargetDir}`, projectRoot!);
+        }
+
+        // Update nexical.yaml
+        await this.addToConfig(moduleName);
+
+        // Stage 4: Recurse
+        if (dependencies.length > 0) {
+            this.info(`Resolving ${dependencies.length} dependencies for ${moduleName}...`);
+            for (const depUrl of dependencies) {
+                await this.installModule(depUrl);
+            }
+        }
+    }
+
+    private async addToConfig(moduleName: string) {
+        const projectRoot = this.projectRoot as string;
+        const configPath = path.join(projectRoot, 'nexical.yaml');
+
+        if (!await fs.pathExists(configPath)) {
+            // Not strictly required to exist for all operations, but good to have if we are tracking modules.
+            logger.warn('nexical.yaml not found, skipping module list update.');
+            return;
+        }
+
+        try {
+            const content = await fs.readFile(configPath, 'utf8');
+            let config = YAML.parse(content) || {};
+
+            if (!config.modules) config.modules = [];
+
+            if (!config.modules.includes(moduleName)) {
+                config.modules.push(moduleName);
+                await fs.writeFile(configPath, YAML.stringify(config));
+                logger.debug(`Added ${moduleName} to nexical.yaml modules list.`);
+            }
+        } catch (e: any) {
+            logger.warn(`Failed to update nexical.yaml: ${e.message}`);
+        }
+    }
+}

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/commands/setup.ts

@@ -0,0 +1,74 @@
+import { BaseCommand, logger } from '@nexical/cli-core';
+import fs from 'fs-extra';
+import path from 'path';
+
+export default class SetupCommand extends BaseCommand {
+    static description = 'Setup the application environment by symlinking core assets.';
+
+    async run() {
+        // We assume we are in the project root
+        // But the CLI might be run from anywhere?
+        // findProjectRoot in index.ts handles finding the root.
+        // BaseCommand has this.projectRoot?
+
+        // BaseCommand doesn't expose projectRoot directly in current implementation seen in memory, checking source if possible?
+        // InitCommand used process.cwd().
+
+        // Let's assume process.cwd() is project root if run via `npm run setup` from root.
+        const rootDir = process.cwd();
+
+        // Verify we are in the right place
+        if (!fs.existsSync(path.join(rootDir, 'core'))) {
+            this.error('Could not find "core" directory. Are you in the project root?');
+            process.exit(1);
+        }
+
+        const apps = ['frontend', 'backend'];
+        const sharedAssets = ['prisma', 'src', 'public', 'locales', 'scripts', 'astro.config.mjs', 'tsconfig.json']; // tsconfig might be needed if extended
+
+        for (const app of apps) {
+            const appDir = path.join(rootDir, 'apps', app);
+            if (!fs.existsSync(appDir)) {
+                this.warn(`App directory ${app} not found. Skipping.`);
+                continue;
+            }
+
+            this.info(`Setting up ${app}...`);
+
+            for (const asset of sharedAssets) {
+                const source = path.join(rootDir, 'core', asset);
+                const dest = path.join(appDir, asset);
+
+                if (!fs.existsSync(source)) {
+                    this.warn(`Source asset ${asset} not found in core.`);
+                    continue;
+                }
+
+                try {
+                    // Remove existing destination if it exists (to ensure clean symlink)
+                    // Be careful not to delete real files if they aren't symlinks?
+                    // For now, we assume setup controls these.
+
+                    const destDir = path.dirname(dest);
+                    await fs.ensureDir(destDir);
+
+                    try {
+                        const stats = fs.lstatSync(dest);
+                        fs.removeSync(dest);
+                    } catch (e: any) {
+                        if (e.code !== 'ENOENT') throw e;
+                    }
+
+                    const relSource = path.relative(destDir, source);
+                    await fs.symlink(relSource, dest);
+
+                    logger.debug(`Symlinked ${asset} to ${app}`);
+                } catch (e: any) {
+                    this.error(`Failed to symlink ${asset} to ${app}: ${e.message}`);
+                }
+            }
+        }
+
+        this.success('Application setup complete.');
+    }
+}

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;
+}