@nexical/cli 0.10.0 → 0.11.1

package/.github/workflows/deploy.yml

@@ -31,4 +31,4 @@ jobs:
       - name: Publish to NPM
         run: npm publish --access public
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.prettierignore

@@ -0,0 +1,8 @@
+dist/
+coverage/
+node_modules/
+.astro/
+.next/
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "printWidth": 100
+}

package/GEMINI.md

@@ -0,0 +1,199 @@
+# Nexical CLI Core Development Guide
+
+This guide details how to build command libraries and CLIs using the `@nexical/cli-core` framework within this project.
+
+## Overview
+
+The project is configured to use `@nexical/cli-core` as its CLI framework. usage entails:
+
+1.  **Entry Point**: `index.ts` initializes the `CLI` instance.
+2.  **Command Discovery**: The CLI automatically scans `src/commands` for command files.
+3.  **Command Implementation**: Commands are TypeScript classes extending `BaseCommand`.
+
+## Directory Structure
+
+Commands are defined in `src/commands`. The file structure directly maps to the command hierarchy.
+
+| File Path                     | Command           | Description                       |
+| :---------------------------- | :---------------- | :-------------------------------- |
+| `src/commands/init.ts`        | `app init`        | Root level command                |
+| `src/commands/user/create.ts` | `app user create` | Subcommand                        |
+| `src/commands/user/index.ts`  | `app user`        | Parent command handler (optional) |
+
+> **Note**: The CLI name (`app`) is configured in `index.ts`.
+
+## Creating a New Command
+
+To create a new command, add a `.ts` file in `src/commands`.
+
+### 1. Basic Command Template
+
+Create `src/commands/hello.ts`:
+
+```typescript
+import { BaseCommand } from '@nexical/cli-core';
+
+export default class HelloCommand extends BaseCommand {
+  // Description displayed in help menus
+  static description = 'Prints a hello message';
+
+  // The main execution method
+  async run(options: any) {
+    this.success('Hello World!');
+  }
+}
+```
+
+**Run it:**
+
+```bash
+npm run cli hello
+```
+
+### 2. Arguments and Options
+
+Use the static `args` property to define inputs.
+
+```typescript
+import { BaseCommand } from '@nexical/cli-core';
+
+export default class GreetCommand extends BaseCommand {
+  static description = 'Greets a user';
+
+  static args = {
+    // Positional Arguments
+    args: [
+      {
+        name: 'name',
+        description: 'Name of the user',
+        required: true,
+      },
+    ],
+    // Options (Flags)
+    options: [
+      {
+        name: '--loud',
+        description: 'Print in uppercase',
+        default: false,
+      },
+      {
+        name: '-c, --count <n>',
+        description: 'Number of times to greet',
+        default: 1,
+      },
+    ],
+  };
+
+  async run(options: any) {
+    // 'name' is mapped from args
+    // 'loud' and 'count' are mapped from options
+    const { name, loud, count } = options;
+
+    let message = `Hello, ${name}`;
+    if (loud) message = message.toUpperCase();
+
+    for (let i = 0; i < count; i++) {
+      this.info(message);
+    }
+  }
+}
+```
+
+**Run it:**
+
+```bash
+npm run cli greet Adrian --loud --count 3
+```
+
+### 3. User Input & Prompts
+
+`BaseCommand` provides built-in methods for interactivity.
+
+```typescript
+export default class InteractiveCommand extends BaseCommand {
+  async run() {
+    // Simple confirmation or input
+    const name = await this.prompt('What is your name?');
+
+    this.success(`Nice to meet you, ${name}`);
+  }
+}
+```
+
+### 4. Output Helpers
+
+Use the built-in helper methods for consistent logging:
+
+- `this.success(msg)`: Green checkmark (✔ Success)
+- `this.error(msg)`: Red cross (✖ Error) - **Exits process**
+- `this.warn(msg)`: Yellow warning (⚠ Warning)
+- `this.info(msg)`: Standard log
+- `this.notice(msg)`: Blue notice (📢 Note)
+- `this.input(msg)`: Cyan input prompt (? Question)
+
+## Subcommands
+
+To create grouped commands (e.g., `user create`, `user list`), use directories.
+
+1.  **Create Directory**: `src/commands/user/`
+2.  **Add Commands**:
+    - `src/commands/user/create.ts` -> `app user create`
+    - `src/commands/user/list.ts` -> `app user list`
+
+### Index Commands (Container Commands)
+
+If you need the parent command `app user` to do something (or just provide a description for the group), create `src/commands/user/index.ts`.
+
+```typescript
+// src/commands/user/index.ts
+import { BaseCommand } from '@nexical/cli-core';
+
+export default class UserCommand extends BaseCommand {
+  static description = 'Manage users';
+
+  async run() {
+    // This runs when user types 'app user' without a subcommand
+    // Often used to show help
+    this.cli.getRawCLI().outputHelp();
+  }
+}
+```
+
+## Internal API Reference
+
+### `BaseCommand`
+
+All commands inherit from `BaseCommand`.
+
+**Properties:**
+
+- `cli`: Access to the main `CLI` instance.
+- `projectRoot`: Path to the project root (if detected).
+- `config`: Loaded configuration from `{cliName}.yml`.
+- `globalOptions`: Global flags passed to the CLI (e.g., `--debug`).
+
+**Methods:**
+
+- `init()`: Called before `run()`. Useful for setup.
+- `run(options)`: Abstract method. Must be implemented.
+- `prompt(message)`: Async, returns string.
+
+**Static Properties:**
+
+- `description`: String. Shown in help.
+- `args`: Object. Defines arguments and options.
+  - `args`: Array of `{ name, description, required, default }`.
+  - `options`: Array of `{ name, description, default }`.
+- `requiresProject`: Boolean. If true, command fails if not run inside a project with a config file.
+
+## Best Practices
+
+1.  **Type Safety**: While `options` is `any` in `run()`, validate inputs early.
+2.  **Error Handling**: Use `this.error()` for fatal errors to ensure proper exit codes.
+3.  **Clean Output**: Use the helper methods (`success`, `info`, etc.) instead of `console.log` for a consistent UI.
+4.  **Async**: The `run` method is async. Always `await` asynchronous operations.
+
+## Troubleshooting
+
+- **Command not found**: Ensure the file exports a class leveraging `export default` and extends `BaseCommand`.
+- **Changes not reflected**: If using `tsup`, ensure you are building or running in dev mode (`npm run dev`). For `npm run cli` using `ts-node` (via `cli.ts` or similar), changes should be instant.

package/README.md

@@ -11,9 +11,9 @@ This project serves as the primary entry point for managing Nexical projects, ha
 - [Getting Started](#getting-started)
 - [Project Structure](#project-structure)
 - [Development Workflow](#development-workflow)
-    - [Prerequisites](#prerequisites)
-    - [Setup](#setup)
-    - [Running Tests](#running-tests)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+  - [Running Tests](#running-tests)
 - [Adding New Commands](#adding-new-commands)
 - [Contributing](#contributing)
 - [License](#license)
@@ -23,6 +23,7 @@ This project serves as the primary entry point for managing Nexical projects, ha
 ## Purpose
 
 The Nexical CLI allows developers to:
+
 1.  **Initialize** new Nexical projects with best practices built-in.
 2.  **Manage** project configuration and dependencies.
 3.  **Extend** the framework functionality through modular commands.
@@ -34,27 +35,30 @@ It acts as a unification layer, bringing together various tools and configuratio
 This CLI is built with **TypeScript** and follows a **Class-Based Command Pattern** to ensure type safety and maintainability.
 
 ### Key Technologies
-*   **[CAC (Command And Conquer)](https://github.com/cacjs/cac)**: A lightweight, robust framework for building CLIs. It handles argument parsing, help generation, and command registration.
-*   **[Consola](https://github.com/unjs/consola)**: Elegant console logging with fallback and structured output capabilities.
-*   **[Lilconfig](https://github.com/antonk52/lilconfig)**: Configuration loading (searching for `nexical.yml`, `nexical.yaml`) akin to `cosmiconfig` but lighter.
-*   **Vitest**: A blazing fast unit test framework powered by Vite.
+
+- **[CAC (Command And Conquer)](https://github.com/cacjs/cac)**: A lightweight, robust framework for building CLIs. It handles argument parsing, help generation, and command registration.
+- **[Consola](https://github.com/unjs/consola)**: Elegant console logging with fallback and structured output capabilities.
+- **[Lilconfig](https://github.com/antonk52/lilconfig)**: Configuration loading (searching for `nexical.yml`, `nexical.yaml`) akin to `cosmiconfig` but lighter.
+- **Vitest**: A blazing fast unit test framework powered by Vite.
 
 ### Core Components
+
 1.  **`CLI` Class** (`src/core/CLI.ts`): The orchestrator. It initializes the CAC instance, discovers commands using the `CommandLoader`, registers them, and handles the execution lifecycle.
 2.  **`CommandLoader`** (`src/core/CommandLoader.ts`): Responsible for dynamically discovering and importing command files from the filesystem. It supports:
-    *   Recursive directory scanning.
-    *   Nested commands (e.g., `module/add.ts` -> `module add`).
-    *   Index files as parent commands (e.g., `module/index.ts` -> `module`).
+    - Recursive directory scanning.
+    - Nested commands (e.g., `module/add.ts` -> `module add`).
+    - Index files as parent commands (e.g., `module/index.ts` -> `module`).
 3.  **`BaseCommand`** (`src/core/BaseCommand.ts`): The abstract base class that all commands MUST extend. It provides:
-    *   Standardized `init()` and `run()` lifecycle methods.
-    *   Built-in access to global options (like `--root-dir`).
-    *   Helper methods for logging (`this.log`, `this.warn`, `this.error`).
-    *   Project root detection (`this.projectRoot`).
+    - Standardized `init()` and `run()` lifecycle methods.
+    - Built-in access to global options (like `--root-dir`).
+    - Helper methods for logging (`this.log`, `this.warn`, `this.error`).
+    - Project root detection (`this.projectRoot`).
 
 ### Design Goals
-*   **Zero-Config Defaults**: It should work out of the box but allow rich configuration via `nexical.yaml`.
-*   **Extensibility**: Adding a command should be as simple as adding a file.
-*   **Testability**: Every component is designed to be unit-testable, with dependency injection where appropriate (e.g., `CommandLoader` importer).
+
+- **Zero-Config Defaults**: It should work out of the box but allow rich configuration via `nexical.yaml`.
+- **Extensibility**: Adding a command should be as simple as adding a file.
+- **Testability**: Every component is designed to be unit-testable, with dependency injection where appropriate (e.g., `CommandLoader` importer).
 
 ---
 
@@ -94,19 +98,23 @@ npx nexical help module add
 Initializes a new Nexical project by cloning a starter repository, setting up dependencies, and preparing a fresh git history.
 
 **Usage:**
+
 ```bash
 npx nexical init <directory> [options]
 ```
 
 **Arguments:**
+
 - `directory` (Required): The directory to initialize the project in. If the directory does not exist, it will be created. If it does exist, it must be empty.
 
 **Options:**
+
 - `--repo <url>` (Default: `https://github.com/nexical/app-core`): The URL of the starter repository to clone.
-    - Supports standard Git URLs (e.g., `https://github.com/user/repo.git`).
-    - Supports GitHub short syntax `gh@owner/repo` (e.g., `gh@nexical/app-core`).
+  - Supports standard Git URLs (e.g., `https://github.com/user/repo.git`).
+  - Supports GitHub short syntax `gh@owner/repo` (e.g., `gh@nexical/app-core`).
 
 **What it does:**
+
 1.  **Clones** the specified starter repository (recursively, including submodules) into the target directory.
 2.  **Updates** all submodules to their latest `main` branch.
 3.  **Installs** dependencies using `npm install`.
@@ -118,6 +126,7 @@ npx nexical init <directory> [options]
     - Removes the `origin` remote to prevent accidental pushes to the starter repo.
 
 **Output:**
+
 - A ready-to-use Nexical project in the specified directory, with fresh git history and installed dependencies.
 
 ---
@@ -127,13 +136,12 @@ npx nexical init <directory> [options]
 Starts the development server in ephemeral mode. It constructs a temporary build environment in `site` and runs the Astro dev server with Hot Module Replacement (HMR).
 
 **Usage:**
+
 ```bash
 npx nexical dev
 ```
 
-**What it does:**
-2.  **Starts** the Astro development server (accessible at `http://localhost:4321` by default).
-3.  **Watches** for changes in your project and updates the ephemeral build automatically.
+**What it does:** 2. **Starts** the Astro development server (accessible at `http://localhost:4321` by default). 3. **Watches** for changes in your project and updates the ephemeral build automatically.
 
 ---
 
@@ -142,16 +150,19 @@ npx nexical dev
 Compiles the project for production. It assembles the final site structure in `site` and generates static assets.
 
 **Usage:**
+
 ```bash
 npx nexical build
 ```
 
 **What it does:**
+
 1.  **Cleans** the `site` directory to ensure a fresh build.
 2.  **Copies** all necessary source files (`src/`, `modules`, `src/content`, `public`) into `site`.
 3.  **Runs** `astro build` to generate the production output in `site/dist`.
 
 **Output:**
+
 - A production-ready static site in `site/dist`.
 
 ---
@@ -161,14 +172,17 @@ npx nexical build
 Previews the locally built production site. This is useful for verifying the output of `nexical build` before deploying.
 
 **Usage:**
+
 ```bash
 npx nexical preview
 ```
 
 **Prerequisites:**
+
 - You must run `nexical build` first.
 
 **What it does:**
+
 - Starts a local web server serving the static files from `site/dist`.
 
 ---
@@ -178,11 +192,13 @@ npx nexical preview
 Removes generated build artifacts and temporary directories to ensure a clean state.
 
 **Usage:**
+
 ```bash
 npx nexical clean
 ```
 
 **What it does:**
+
 - Deletes `site`, `dist`, and `node_modules/.vite`.
 
 ---
@@ -192,17 +208,20 @@ npx nexical clean
 Executes a script within the Nexical environment context. This handles path resolution and environment variable setup for you.
 
 **Usage:**
+
 ```bash
 npx nexical run <script> [args...]
 ```
 
 **Arguments:**
+
 - `script` (Required): The name of the script to run.
-    - Can be a standard `package.json` script (e.g., `test`).
-    - Can be a module-specific script using `module:script` syntax (e.g., `blog:sync`).
+  - Can be a standard `package.json` script (e.g., `test`).
+  - Can be a module-specific script using `module:script` syntax (e.g., `blog:sync`).
 - `args` (Optional): Additional arguments to pass to the script.
 
 **Examples:**
+
 ```bash
 # Run a core project script
 npx nexical run test
@@ -222,16 +241,19 @@ Manages the modular architecture of your Nexical project. Allows you to add, rem
 Adds a new module as a Git submodule.
 
 **Usage:**
+
 ```bash
 npx nexical module add <url> [name]
 ```
 
 **Arguments:**
+
 - `url` (Required): The Git repository URL of the module.
-    - Supports `gh@owner/repo` shorthand.
+  - Supports `gh@owner/repo` shorthand.
 - `name` (Optional): The folder name for the module. Defaults to the repository name.
 
 **What it does:**
+
 1.  Adds the repository as a git submodule in `src/modules/<name>`.
 2.  Installs any new dependencies via `npm install`.
 
@@ -240,11 +262,13 @@ npx nexical module add <url> [name]
 Lists all installed modules in the project.
 
 **Usage:**
+
 ```bash
 npx nexical module list
 ```
 
 **Output:**
+
 - A table showing the name, version, and description of each installed module found in `src/modules`.
 
 ##### `module update`
@@ -252,14 +276,17 @@ npx nexical module list
 Updates one or all modules to their latest remote commit.
 
 **Usage:**
+
 ```bash
 npx nexical module update [name]
 ```
 
 **Arguments:**
+
 - `name` (Optional): The specific module to update. If omitted, all modules are updated.
 
 **What it does:**
+
 1.  Runs `git submodule update --remote --merge` for the target(s).
 2.  Re-installs dependencies to ensure `package-lock.json` is consistent.
 
@@ -268,14 +295,17 @@ npx nexical module update [name]
 Removes an installed module and cleans up references.
 
 **Usage:**
+
 ```bash
 npx nexical module remove <name>
 ```
 
 **Arguments:**
+
 - `name` (Required): The name of the module to remove.
 
 **What it does:**
+
 1.  De-initializes the git submodule.
 2.  Removes the module directory from `src/modules`.
 3.  Cleans up internal git metadata (`.git/modules`).
@@ -298,22 +328,24 @@ graph TD
     utils-->logger.ts
 ```
 
-*   **`src/commands/`**: Contains the implementations of individual CLI commands. File names correspond to command names.
-*   **`src/core/`**: The framework logic (Command loading, Base class, CLI orchestration).
-*   **`src/utils/`**: Shared utilities (Logging, Configuration parsing).
-*   **`test/unit/`**: Co-located unit tests. Mirrors the `src` structure.
+- **`src/commands/`**: Contains the implementations of individual CLI commands. File names correspond to command names.
+- **`src/core/`**: The framework logic (Command loading, Base class, CLI orchestration).
+- **`src/utils/`**: Shared utilities (Logging, Configuration parsing).
+- **`test/unit/`**: Co-located unit tests. Mirrors the `src` structure.
 
 ---
 
 ## Development Workflow
 
 ### Prerequisites
-*   Node.js (v18+ recommended)
-*   NPM
+
+- Node.js (v18+ recommended)
+- NPM
 
 ### Setup
 
 1.  **Install Dependencies**:
+
     ```bash
     npm install
     ```
@@ -347,43 +379,40 @@ To create a new command, add a TypeScript file to `src/commands/`.
 import { BaseCommand } from '../core/BaseCommand.js';
 
 export default class HelloCommand extends BaseCommand {
-    // 1. Define command metadata
-    static description = 'Say hello to the world';
-    
-    static args = {
-        args: [
-            { name: 'name', required: false, description: 'User name' }
-        ],
-        options: [
-            { name: '--shout', description: 'Say it loud', default: false }
-        ]
-    };
-
-    // 2. Implement the run method
-    async run(options: any) {
-        const name = options.name || 'World';
-        
-        if (options.shout) {
-            this.success(`HELLO ${name.toUpperCase()}!`);
-        } else {
-            this.log(`Hello ${name}`);
-        }
+  // 1. Define command metadata
+  static description = 'Say hello to the world';
+
+  static args = {
+    args: [{ name: 'name', required: false, description: 'User name' }],
+    options: [{ name: '--shout', description: 'Say it loud', default: false }],
+  };
+
+  // 2. Implement the run method
+  async run(options: any) {
+    const name = options.name || 'World';
+
+    if (options.shout) {
+      this.success(`HELLO ${name.toUpperCase()}!`);
+    } else {
+      this.log(`Hello ${name}`);
     }
+  }
 }
 ```
 
 **Key Requirement**: The file MUST default export a class extending `BaseCommand`.
 
-*   **File Naming**:
-    *   `hello.ts` -> Command: `hello`
-    *   `users/create.ts` -> Command: `users create`
-    *   `users/index.ts` -> Command: `users` (Parent command)
+- **File Naming**:
+  - `hello.ts` -> Command: `hello`
+  - `users/create.ts` -> Command: `users create`
+  - `users/index.ts` -> Command: `users` (Parent command)
 
 ---
 
 ## Contributing
 
 Contributions are welcome! Please follow these steps:
+
 1.  Fork the repository.
 2.  Create a feature branch.
 3.  Add your changes and **ensure tests pass with 100% coverage**.

package/dist/chunk-AC4B3HPJ.js

@@ -0,0 +1,93 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  init_esm_shims
+} from "./chunk-OYFWMYPG.js";
+
+// src/utils/discovery.ts
+init_esm_shims();
+import { logger } from "@nexical/cli-core";
+import path from "path";
+import fs from "fs";
+function discoverCommandDirectories(projectRoot) {
+  const directories = [];
+  const visited = /* @__PURE__ */ new Set();
+  const isTsEnvironment = process.argv[1]?.endsWith(".ts") || process.argv[1]?.endsWith(".mts") || process.execArgv.some(
+    (arg) => arg.includes("tsx") || arg.includes("ts-node") || arg.includes("vitest")
+  ) || process.env.VITEST === "true" || process.env.NODE_ENV === "test";
+  const addDir = (dir) => {
+    const resolved = path.resolve(dir);
+    if (!fs.existsSync(resolved)) {
+      logger.debug(`Command directory not found (skipping): ${resolved}`);
+      return;
+    }
+    if (visited.has(resolved)) return;
+    const srcPattern = path.join(path.sep, "src", "commands");
+    const distPattern = path.join(path.sep, "dist");
+    const isSrcDir = resolved.endsWith(srcPattern) && !resolved.includes(distPattern);
+    if (isSrcDir) {
+      const distPath1 = resolved.replace(
+        srcPattern,
+        path.join(path.sep, "dist", "src", "commands")
+      );
+      const distPath2 = resolved.replace(srcPattern, path.join(path.sep, "dist", "commands"));
+      if (fs.existsSync(distPath1) || fs.existsSync(distPath2)) {
+        logger.debug(`Skipping src commands at ${resolved} because dist exists`);
+        return;
+      }
+      if (!isTsEnvironment) {
+        logger.debug(`Skipping src commands at ${resolved}: no TS loader detected`);
+        return;
+      }
+    }
+    logger.debug(`Found command directory: ${resolved}`);
+    directories.push(resolved);
+    visited.add(resolved);
+  };
+  const possibleCorePaths = [path.join(projectRoot, "src/commands")];
+  possibleCorePaths.forEach(addDir);
+  const searchRoots = [
+    path.join(projectRoot, "modules"),
+    path.join(projectRoot, "src", "modules"),
+    path.join(projectRoot, "packages")
+  ];
+  searchRoots.forEach((root) => {
+    if (!fs.existsSync(root)) return;
+    try {
+      const entries = fs.readdirSync(root);
+      for (const entry of entries) {
+        if (entry.startsWith(".")) continue;
+        const entryPath = path.join(root, entry);
+        if (!fs.statSync(entryPath).isDirectory()) continue;
+        const possiblePaths = [
+          path.join(entryPath, "dist/src/commands"),
+          path.join(entryPath, "dist/commands"),
+          path.join(entryPath, "src/commands")
+        ];
+        let foundDist = false;
+        for (const p of possiblePaths) {
+          if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
+            if (p.includes(path.sep + "dist" + path.sep)) {
+              addDir(p);
+              foundDist = true;
+              break;
+            }
+          }
+        }
+        if (!foundDist) {
+          const srcPath = path.join(entryPath, "src/commands");
+          if (fs.existsSync(srcPath) && fs.statSync(srcPath).isDirectory()) {
+            addDir(srcPath);
+          }
+        }
+      }
+    } catch (e) {
+      logger.debug(`Error scanning root ${root}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  });
+  return directories;
+}
+
+export {
+  discoverCommandDirectories
+};
+//# sourceMappingURL=chunk-AC4B3HPJ.js.map