@nexical/cli 0.1.7 → 0.10.0

package/dist/src/commands/run.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand, CommandDefinition } from '@nexical/cli-core';
+
+declare class RunCommand extends BaseCommand {
+    static usage: string;
+    static description: string;
+    static requiresProject: boolean;
+    static args: CommandDefinition;
+    run(options: any): Promise<void>;
+}
+
+export { RunCommand as default };

package/dist/src/commands/run.js

@@ -0,0 +1,93 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  require_lib
+} from "../../chunk-LZ3YQWAR.js";
+import {
+  __toESM,
+  init_esm_shims
+} from "../../chunk-OYFWMYPG.js";
+
+// src/commands/run.ts
+init_esm_shims();
+var import_fs_extra = __toESM(require_lib(), 1);
+import { BaseCommand, logger } from "@nexical/cli-core";
+import path from "path";
+import { spawn } from "child_process";
+import process from "process";
+var RunCommand = class extends BaseCommand {
+  static usage = "run <script> [args...]";
+  static description = "Run a script inside the Nexical environment.";
+  static requiresProject = true;
+  static args = {
+    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) {
+    const projectRoot = this.projectRoot;
+    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;
+    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}`);
+    }
+    const pkgJsonPath = path.join(execPath, "package.json");
+    if (!await import_fs_extra.default.pathExists(pkgJsonPath)) {
+      this.error(`Failed to find package.json at ${execPath}`);
+      return;
+    }
+    try {
+      const pkg = await import_fs_extra.default.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) {
+      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"
+      }
+    });
+    const cleanup = () => {
+      child.kill();
+      process.exit();
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    await new Promise((resolve) => {
+      child.on("close", (code) => {
+        process.off("SIGINT", cleanup);
+        process.off("SIGTERM", cleanup);
+        if (code !== 0) {
+          process.exit(code || 1);
+        }
+        resolve();
+      });
+    });
+  }
+};
+export {
+  RunCommand as default
+};
+//# sourceMappingURL=run.js.map

package/dist/src/commands/run.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/commands/run.ts"],"sourcesContent":["import { type CommandDefinition, BaseCommand, logger } from '@nexical/cli-core';\nimport fs from 'fs-extra';\nimport path from 'path';\nimport { spawn } from 'child_process';\nimport process from 'node:process';\n\nexport default class RunCommand extends BaseCommand {\n    static usage = 'run <script> [args...]';\n    static description = 'Run a script inside the Nexical environment.';\n    static requiresProject = true;\n\n    static args: CommandDefinition = {\n        args: [\n            { name: 'script', required: true, description: 'The script to run (script-name OR module:script-name)' },\n            { name: 'args...', required: false, description: 'Arguments for the script' }\n        ]\n    };\n\n    async run(options: any) {\n        const projectRoot = this.projectRoot as string;\n        const script = options.script;\n        const scriptArgs = options.args || [];\n\n        if (!script) {\n            this.error('Please specify a script to run.');\n            return;\n        }\n\n        logger.debug('Run command context:', { script, args: scriptArgs, projectRoot });\n\n        let execPath = projectRoot;\n        let scriptName = script;\n\n        // Handle module:script syntax\n        if (script.includes(':')) {\n            const [moduleName, name] = script.split(':');\n            execPath = path.resolve(projectRoot, 'modules', moduleName);\n            scriptName = name;\n\n            logger.debug(`Resolving module script: ${moduleName}:${scriptName} at ${execPath}`);\n        } else {\n            logger.debug(`Resolving core script: ${scriptName} at ${execPath}`);\n        }\n\n        // Validate script existence\n        const pkgJsonPath = path.join(execPath, 'package.json');\n        if (!(await fs.pathExists(pkgJsonPath))) {\n            this.error(`Failed to find package.json at ${execPath}`);\n            return;\n        }\n\n        try {\n            const pkg = await fs.readJson(pkgJsonPath);\n            if (!pkg.scripts || !pkg.scripts[scriptName]) {\n                const type = script.includes(':') ? `module ${script.split(':')[0]}` : 'Nexical core';\n                this.error(`Script \"${scriptName}\" does not exist in ${type}`);\n                return;\n            }\n        } catch (e: any) {\n            this.error(`Failed to read package.json at ${execPath}: ${e.message}`);\n            return;\n        }\n\n        const finalArgs = ['run', scriptName, '--', ...scriptArgs];\n        logger.debug(`Executing: npm ${finalArgs.join(' ')} in ${execPath}`);\n\n        const child = spawn('npm', finalArgs, {\n            cwd: execPath,\n            stdio: 'inherit',\n            env: {\n                ...process.env,\n                FORCE_COLOR: '1'\n            }\n        });\n\n        // Handle process termination to kill child\n        const cleanup = () => {\n            child.kill();\n            process.exit();\n        };\n\n        process.on('SIGINT', cleanup);\n        process.on('SIGTERM', cleanup);\n\n        await new Promise<void>((resolve) => {\n            child.on('close', (code) => {\n                // Remove listeners to prevent memory leaks if this command is run multiple times in-process (e.g. tests)\n                process.off('SIGINT', cleanup);\n                process.off('SIGTERM', cleanup);\n\n                if (code !== 0) {\n                    process.exit(code || 1);\n                }\n                resolve();\n            });\n        });\n    }\n}\n"],"mappings":";;;;;;;;;;AAAA;AACA,sBAAe;AADf,SAAiC,aAAa,cAAc;AAE5D,OAAO,UAAU;AACjB,SAAS,aAAa;AACtB,OAAO,aAAa;AAEpB,IAAqB,aAArB,cAAwC,YAAY;AAAA,EAChD,OAAO,QAAQ;AAAA,EACf,OAAO,cAAc;AAAA,EACrB,OAAO,kBAAkB;AAAA,EAEzB,OAAO,OAA0B;AAAA,IAC7B,MAAM;AAAA,MACF,EAAE,MAAM,UAAU,UAAU,MAAM,aAAa,wDAAwD;AAAA,MACvG,EAAE,MAAM,WAAW,UAAU,OAAO,aAAa,2BAA2B;AAAA,IAChF;AAAA,EACJ;AAAA,EAEA,MAAM,IAAI,SAAc;AACpB,UAAM,cAAc,KAAK;AACzB,UAAM,SAAS,QAAQ;AACvB,UAAM,aAAa,QAAQ,QAAQ,CAAC;AAEpC,QAAI,CAAC,QAAQ;AACT,WAAK,MAAM,iCAAiC;AAC5C;AAAA,IACJ;AAEA,WAAO,MAAM,wBAAwB,EAAE,QAAQ,MAAM,YAAY,YAAY,CAAC;AAE9E,QAAI,WAAW;AACf,QAAI,aAAa;AAGjB,QAAI,OAAO,SAAS,GAAG,GAAG;AACtB,YAAM,CAAC,YAAY,IAAI,IAAI,OAAO,MAAM,GAAG;AAC3C,iBAAW,KAAK,QAAQ,aAAa,WAAW,UAAU;AAC1D,mBAAa;AAEb,aAAO,MAAM,4BAA4B,UAAU,IAAI,UAAU,OAAO,QAAQ,EAAE;AAAA,IACtF,OAAO;AACH,aAAO,MAAM,0BAA0B,UAAU,OAAO,QAAQ,EAAE;AAAA,IACtE;AAGA,UAAM,cAAc,KAAK,KAAK,UAAU,cAAc;AACtD,QAAI,CAAE,MAAM,gBAAAA,QAAG,WAAW,WAAW,GAAI;AACrC,WAAK,MAAM,kCAAkC,QAAQ,EAAE;AACvD;AAAA,IACJ;AAEA,QAAI;AACA,YAAM,MAAM,MAAM,gBAAAA,QAAG,SAAS,WAAW;AACzC,UAAI,CAAC,IAAI,WAAW,CAAC,IAAI,QAAQ,UAAU,GAAG;AAC1C,cAAM,OAAO,OAAO,SAAS,GAAG,IAAI,UAAU,OAAO,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK;AACvE,aAAK,MAAM,WAAW,UAAU,uBAAuB,IAAI,EAAE;AAC7D;AAAA,MACJ;AAAA,IACJ,SAAS,GAAQ;AACb,WAAK,MAAM,kCAAkC,QAAQ,KAAK,EAAE,OAAO,EAAE;AACrE;AAAA,IACJ;AAEA,UAAM,YAAY,CAAC,OAAO,YAAY,MAAM,GAAG,UAAU;AACzD,WAAO,MAAM,kBAAkB,UAAU,KAAK,GAAG,CAAC,OAAO,QAAQ,EAAE;AAEnE,UAAM,QAAQ,MAAM,OAAO,WAAW;AAAA,MAClC,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK;AAAA,QACD,GAAG,QAAQ;AAAA,QACX,aAAa;AAAA,MACjB;AAAA,IACJ,CAAC;AAGD,UAAM,UAAU,MAAM;AAClB,YAAM,KAAK;AACX,cAAQ,KAAK;AAAA,IACjB;AAEA,YAAQ,GAAG,UAAU,OAAO;AAC5B,YAAQ,GAAG,WAAW,OAAO;AAE7B,UAAM,IAAI,QAAc,CAAC,YAAY;AACjC,YAAM,GAAG,SAAS,CAAC,SAAS;AAExB,gBAAQ,IAAI,UAAU,OAAO;AAC7B,gBAAQ,IAAI,WAAW,OAAO;AAE9B,YAAI,SAAS,GAAG;AACZ,kBAAQ,KAAK,QAAQ,CAAC;AAAA,QAC1B;AACA,gBAAQ;AAAA,MACZ,CAAC;AAAA,IACL,CAAC;AAAA,EACL;AACJ;","names":["fs"]}

package/dist/src/utils/discovery.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+declare function discoverCommandDirectories(projectRoot: string): string[];
+
+export { discoverCommandDirectories };

package/dist/src/utils/discovery.js

@@ -0,0 +1,9 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  discoverCommandDirectories
+} from "../../chunk-OKXOCNXP.js";
+import "../../chunk-OYFWMYPG.js";
+export {
+  discoverCommandDirectories
+};
+//# sourceMappingURL=discovery.js.map

package/dist/src/utils/git.d.ts

@@ -0,0 +1,16 @@
+declare function clone(url: string, destination: string, options?: {
+    recursive?: boolean;
+    depth?: number;
+}): Promise<void>;
+declare function getRemoteUrl(cwd: string, remote?: string): Promise<string>;
+declare function updateSubmodules(cwd: string): Promise<void>;
+declare function checkoutOrphan(branch: string, cwd: string): Promise<void>;
+declare function addAll(cwd: string): Promise<void>;
+declare function commit(message: string, cwd: string): Promise<void>;
+declare function deleteBranch(branch: string, cwd: string): Promise<void>;
+declare function renameBranch(branch: string, cwd: string): Promise<void>;
+declare function removeRemote(remote: string, cwd: string): Promise<void>;
+declare function renameRemote(oldName: string, newName: string, cwd: string): Promise<void>;
+declare function branchExists(branch: string, cwd: string): Promise<boolean>;
+
+export { addAll, branchExists, checkoutOrphan, clone, commit, deleteBranch, getRemoteUrl, removeRemote, renameBranch, renameRemote, updateSubmodules };

package/dist/src/utils/git.js

@@ -0,0 +1,29 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  addAll,
+  branchExists,
+  checkoutOrphan,
+  clone,
+  commit,
+  deleteBranch,
+  getRemoteUrl,
+  removeRemote,
+  renameBranch,
+  renameRemote,
+  updateSubmodules
+} from "../../chunk-WKERTCM6.js";
+import "../../chunk-OYFWMYPG.js";
+export {
+  addAll,
+  branchExists,
+  checkoutOrphan,
+  clone,
+  commit,
+  deleteBranch,
+  getRemoteUrl,
+  removeRemote,
+  renameBranch,
+  renameRemote,
+  updateSubmodules
+};
+//# sourceMappingURL=git.js.map

package/dist/src/utils/git.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/src/utils/url-resolver.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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
+ */
+declare function resolveGitUrl(url: string): string;
+
+export { resolveGitUrl };

package/dist/src/utils/url-resolver.js

@@ -0,0 +1,9 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  resolveGitUrl
+} from "../../chunk-JYASTIIW.js";
+import "../../chunk-OYFWMYPG.js";
+export {
+  resolveGitUrl
+};
+//# sourceMappingURL=url-resolver.js.map

package/dist/src/utils/url-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/index.ts

@@ -1,14 +1,38 @@
 #!/usr/bin/env node
-import { CLI } from "@nexical/cli-core";
-import { fileURLToPath } from "node:url";
+import { CLI, findProjectRoot } from '@nexical/cli-core';
+import { fileURLToPath } from 'node:url';
+import { discoverCommandDirectories } from './src/utils/discovery.js';
 import pkg from './package.json';
 import path from 'node:path';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const commandName = 'nexical';
+const projectRoot = await findProjectRoot(commandName, process.cwd()) || process.cwd();
+const coreCommandsDir = path.resolve(__dirname, './src/commands');
+const additionalCommands = discoverCommandDirectories(projectRoot);
+
+// Filter out the source version of core commands if we are running from dist
+const filteredAdditional = additionalCommands.filter(dir => {
+    if (dir === coreCommandsDir) return false;
+
+    // Handle the case where we are running from dist/ and it finds src/commands in projectRoot
+    if (coreCommandsDir.includes(path.join(path.sep, 'dist', 'src', 'commands'))) {
+        const srcVersion = coreCommandsDir.replace(
+            path.join(path.sep, 'dist', 'src', 'commands'),
+            path.join(path.sep, 'src', 'commands')
+        );
+        if (dir === srcVersion) return false;
+    }
+    return true;
+});
+
 const app = new CLI({
-  version: pkg.version,
-  commandName: "nexical",
-  searchDirectories: [path.resolve(__dirname, "./src/commands")],
+    version: pkg.version,
+    commandName: commandName,
+    searchDirectories: [...new Set([
+        coreCommandsDir,
+        ...filteredAdditional
+    ])]
 });
 app.start();

package/package.json

@@ -1,32 +1,34 @@
 {
-  "name": "@nexical/cli",
-  "version": "0.1.7",
-  "type": "module",
-  "bin": {
-    "nexical": "./dist/index.js"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "start": "node dist/index.js",
-    "test": "npm run test:unit && npm run test:integration && npm run test:e2e",
-    "test:unit": "vitest run --config vitest.config.ts --coverage",
-    "test:integration": "vitest run --config vitest.integration.config.ts",
-    "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@nexical/cli-core": "^0.1.12",
-    "@nexical/sdk": "^0.4.2"
-  },
-  "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^4.0.15",
-    "execa": "^9.6.1",
-    "fs-extra": "^11.3.2",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^4.0.15"
-  }
-}
+    "name": "@nexical/cli",
+    "version": "0.10.0",
+    "type": "module",
+    "bin": {
+        "nexical": "./dist/index.js"
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "start": "node dist/index.js",
+        "test": "npm run test:unit && npm run test:integration && npm run test:e2e",
+        "test:unit": "vitest run --config vitest.config.ts --coverage",
+        "test:integration": "vitest run --config vitest.integration.config.ts",
+        "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "@nexical/cli-core": "^0.1.12",
+        "yaml": "^2.3.4",
+        "fast-glob": "^3.3.3"
+    },
+    "devDependencies": {
+        "@types/fs-extra": "^11.0.4",
+        "@types/node": "^20.10.0",
+        "@vitest/coverage-v8": "^4.0.15",
+        "execa": "^9.6.1",
+        "fs-extra": "^11.3.2",
+        "tsup": "^8.0.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.3.3",
+        "vitest": "^4.0.15"
+    }
+}

package/src/commands/init.ts

@@ -0,0 +1,85 @@
+import { type CommandDefinition, BaseCommand, logger, runCommand } from '@nexical/cli-core';
+import * as git from '../utils/git.js';
+import { resolveGitUrl } from '../utils/url-resolver.js';
+import fs from 'fs-extra';
+import path from 'path';
+
+export default class InitCommand extends BaseCommand {
+    static usage = 'init';
+    static description = 'Initialize a new Nexical project.';
+    static requiresProject = false;
+
+    static args: CommandDefinition = {
+        args: [
+            { name: 'directory', required: true, description: 'Directory to initialize the project in' }
+        ],
+        options: [
+            {
+                name: '--repo <url>',
+                description: 'Starter repository URL (supports gh@owner/repo syntax)',
+                default: 'gh@nexical/app-core'
+            }
+        ]
+    };
+
+    async run(options: any) {
+        const directory = options.directory;
+        const targetPath = path.resolve(process.cwd(), directory);
+        let repoUrl = resolveGitUrl(options.repo);
+
+        logger.debug('Init options:', { directory, targetPath, repoUrl });
+
+        this.info(`Initializing project in: ${targetPath}`);
+        this.info(`Using starter repository: ${repoUrl}`);
+
+        if (await fs.pathExists(targetPath)) {
+            if ((await fs.readdir(targetPath)).length > 0) {
+                this.error(`Directory ${directory} is not empty.`);
+                process.exit(1);
+            }
+        } else {
+            await fs.mkdir(targetPath, { recursive: true });
+        }
+
+        try {
+            this.info('Cloning core repository...');
+            await git.clone(repoUrl, targetPath, { recursive: true });
+
+            this.info('Updating submodules...');
+            await git.updateSubmodules(targetPath);
+
+            this.info('Installing dependencies...');
+            await runCommand('npm install', targetPath);
+
+            this.info('Setting up upstream remote...');
+            await git.renameRemote('origin', 'upstream', targetPath);
+
+            // Ensure module directory
+            await fs.ensureDir(path.join(targetPath, 'modules'));
+
+            // Check for nexical.yaml, if not present create a default one
+            const configPath = path.join(targetPath, 'nexical.yaml');
+            if (!await fs.pathExists(configPath)) {
+                this.info('Creating default nexical.yaml...');
+                await fs.writeFile(configPath, 'name: ' + path.basename(targetPath) + '\nmodules: []\n');
+            }
+
+            // Create VERSION file
+            const versionPath = path.join(targetPath, 'VERSION');
+            // Check if version file exists, if not create it
+            if (!await fs.pathExists(versionPath)) {
+                this.info('Creating VERSION file with 0.1.0...');
+                await fs.writeFile(versionPath, '0.1.0');
+            }
+
+            await git.addAll(targetPath);
+            await git.commit('Initial site commit', targetPath);
+
+            this.success(`Project initialized successfully in ${directory}!`);
+
+        } catch (error: any) {
+            this.error(`Failed to initialize project: ${error.message}`);
+            process.exit(1);
+        }
+    }
+}

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