@nexical/cli 0.1.6 → 0.10.0

package/.github/workflows/deploy.yml

@@ -17,10 +17,10 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: "https://registry.npmjs.org"
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Install Dependencies
-        run: npm ci
+        run: npm install
 
       - name: Build
         run: npm run build
@@ -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/README.md

@@ -1,183 +1,396 @@
-# Nexical CLI
+# @nexical/cli
 
-The **Nexical CLI** is the official command-line interface for the Nexical Orchestrator. It allows developers, platform engineers, and administrators to interact with the Nexical API directly from their terminal.
+The official Command Line Interface (CLI) for the Nexical framework.
 
-Whether you are managing teams, configuring projects, triggering jobs, or handling authentication tokens, the CLI provides a robust and scriptable interface for all your orchestration needs.
+This project serves as the primary entry point for managing Nexical projects, handling tasks such as project initialization, module management, and development workflows. It is designed to be **extensible**, **fast**, and **developer-friendly**, focusing on a clean architecture that allows for easy addition of new commands.
+
+## Table of Contents
+
+- [Purpose](#purpose)
+- [Architecture & Design](#architecture--design)
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Development Workflow](#development-workflow)
+    - [Prerequisites](#prerequisites)
+    - [Setup](#setup)
+    - [Running Tests](#running-tests)
+- [Adding New Commands](#adding-new-commands)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-## 🚀 Getting Started
+## Purpose
 
-### Prerequisites
+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.
+
+It acts as a unification layer, bringing together various tools and configurations into a cohesive developer experience.
+
+## Architecture & Design
 
-- **Node.js**: v22 or higher
-- **NPM**: v10 or higher
+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.
+
+### 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`).
+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`).
+
+### 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).
+
+---
+
+## Getting Started
 
 ### Installation
 
-Install the package from NPM package repository:
+While currently in development, you can run the CLI from the repository source or link it.
 
 ```bash
-npm install -g @nexical/cli
+# From within the package directory
+npm install
+npm run build
 ```
 
-### Local Development
-
-To run the CLI locally during development, you can use `npm start`. To pass arguments to the CLI, use the `--` separator:
+### Usage
 
 ```bash
-# Example: Running the 'whoami' command
-npm start -- whoami
+# Run the built CLI
+npx nexical <command> [options]
+
+# Example: Initialize a new project
+npx nexical init my-new-project
 
-# Example: Logging in
-npm start -- login
+# Get help
+npx nexical help
+
+# Get help for a specific command
+npx nexical help init
+npx nexical help module add
 ```
 
-Alternatively, you can link the binary globally to use the `nexical` command directly:
+### Command Reference
+
+#### `init`
 
+Initializes a new Nexical project by cloning a starter repository, setting up dependencies, and preparing a fresh git history.
+
+**Usage:**
 ```bash
-npm link
-nexical --help
+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`).
+
+**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`.
+4.  **Resets** Git history:
+    - Creates an orphan branch (`new-main`).
+    - Commits all files as an "Initial commit".
+    - Deletes the old history (removes `main`/`master`).
+    - Renames the branch to `main`.
+    - 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.
+
 ---
 
-## 🔑 Authentication
+#### `dev`
+
+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.
+
+---
 
-The CLI supports a secure **Device Flow** for authentication, making it easy to log in from your terminal without handling sensitive passwords directly.
+#### `build`
 
-### 1. Log In
-Start the authentication process. This will provide a verification URL and a code.
+Compiles the project for production. It assembles the final site structure in `site` and generates static assets.
 
+**Usage:**
 ```bash
-nexical login
+npx nexical build
 ```
-*Follow the on-screen instructions to authorize the device via your browser.*
 
-### 2. Verify Session
-Check your current logged-in status and user details.
+**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`.
+
+---
+
+#### `preview`
+
+Previews the locally built production site. This is useful for verifying the output of `nexical build` before deploying.
+
+**Usage:**
 ```bash
-nexical whoami
+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`.
+
 ---
 
-## 🛠️ Usage & Commands
+#### `clean`
 
-The CLI is structured into resource-based commands. You can always run `nexical <command> --help` to see available subcommands and options.
+Removes generated build artifacts and temporary directories to ensure a clean state.
 
-### 👥 Teams (`team`)
+**Usage:**
+```bash
+npx nexical clean
+```
 
-Manage user teams and memberships.
+**What it does:**
+- Deletes `site`, `dist`, and `node_modules/.vite`.
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `list` | `nexical team list` | List all teams you belong to or own. |
-| `create` | `nexical team create <name> [--slug <slug>]` | Create a new team. |
-| `get` | `nexical team get <teamId>` | View details of a specific team. |
-| `update` | `nexical team update <teamId> [--name <n>] [--slug <s>]` | Update team settings. |
-| `invite` | `nexical team invite <teamId> <email> [--role <role>]` | Invite a user to a team. |
-| `delete` | `nexical team delete <teamId> [--confirm]` | Delete a team permanently. |
+---
 
-### 📂 Projects (`project`)
+#### `run`
 
-Manage projects within your teams.
+Executes a script within the Nexical environment context. This handles path resolution and environment variable setup for you.
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `list` | `nexical project list <teamId>` | List all projects in a team. |
-| `create` | `nexical project create <teamId> <name> [--repo <url>]` | Create a new project. |
-| `get` | `nexical project get <teamId> <projectId>` | Get project details. |
-| `update` | `nexical project update <teamId> <projectId> ...` | Update project configuration. |
-| `delete` | `nexical project delete <teamId> <projectId>` | Delete a project. |
+**Usage:**
+```bash
+npx nexical run <script> [args...]
+```
 
-### 🌿 Branches (`branch`)
+**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`).
+- `args` (Optional): Additional arguments to pass to the script.
 
-Manage development branches for your projects.
+**Examples:**
+```bash
+# Run a core project script
+npx nexical run test
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `list` | `nexical branch list <teamId> <projectId>` | List branches. |
-| `create` | `nexical branch create <teamId> <projectId> <name>` | Create a branch. |
-| `get` | `nexical branch get <teamId> <projectId> <branchId>` | Get branch details. |
-| `delete` | `nexical branch delete ...` | Delete a branch. |
+# Run a script defined in the 'blog' module's package.json
+npx nexical run blog:sync --force
+```
+
+---
 
-### ⚙️ Jobs (`job`)
+#### `module`
 
-Trigger and monitor orchestration jobs.
+Manages the modular architecture of your Nexical project. Allows you to add, remove, update, and list Git-based modules.
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `list` | `nexical job list <teamId> <projectId> <branchId>` | List recent jobs. |
-| `trigger`| `nexical job trigger ... <type> [--input <json>]` | Trigger a new job (e.g., deploy). |
-| `get` | `nexical job get ... <jobId>` | Get job details. |
-| `logs` | `nexical job logs ... <jobId>` | Stream or view logs for a job. |
+##### `module add`
 
-### 🎟️ API Tokens (`token`)
+Adds a new module as a Git submodule.
 
-Manage personal access tokens for scripting and CI/CD.
+**Usage:**
+```bash
+npx nexical module add <url> [name]
+```
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `list` | `nexical token list` | List your active tokens. |
-| `create` | `nexical token create <name> [--scopes <list>]` | Generate a new API token. |
-| `revoke` | `nexical token revoke <id>` | Revoke a token. |
+**Arguments:**
+- `url` (Required): The Git repository URL of the module.
+    - Supports `gh@owner/repo` shorthand.
+- `name` (Optional): The folder name for the module. Defaults to the repository name.
 
-### 🛡️ Admin (`admin`)
+**What it does:**
+1.  Adds the repository as a git submodule in `src/modules/<name>`.
+2.  Installs any new dependencies via `npm install`.
 
-System administration commands (requires elevated permissions).
+##### `module list`
 
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `create-user` | `nexical admin create-user <name> <email> <password>` | Create a system user. |
+Lists all installed modules in the project.
 
----
+**Usage:**
+```bash
+npx nexical module list
+```
 
-## 🏗️ Project Structure
+**Output:**
+- A table showing the name, version, and description of each installed module found in `src/modules`.
 
-The codebase is organized to be modular and extensible:
+##### `module update`
 
+Updates one or all modules to their latest remote commit.
+
+**Usage:**
+```bash
+npx nexical module update [name]
 ```
-src/
-├── commands/           # Command implementations
-│   ├── team/           # Team-related commands
-│   ├── project/        # Project-related commands
-│   └── ...
-├── utils/              # Shared utilities (API client, config)
-└── index.ts            # CLI entry point
+
+**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.
+
+##### `module remove`
+
+Removes an installed module and cleans up references.
+
+**Usage:**
+```bash
+npx nexical module remove <name>
 ```
 
-Each command is a class extending `BaseCommand` from `@nexical/cli-core`, enforcing a consistent structure for arguments, help text, and error handling.
+**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`).
+4.  Updates `npm` dependencies.
 
 ---
 
-## 🧪 Testing
+## Project Structure
+
+```mermaid
+graph TD
+    src-->commands
+    src-->core
+    src-->utils
+    commands-->init.ts
+    core-->CLI.ts
+    core-->BaseCommand.ts
+    core-->CommandLoader.ts
+    utils-->config.ts
+    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.
+
+---
+
+## Development Workflow
+
+### Prerequisites
+*   Node.js (v18+ recommended)
+*   NPM
+
+### Setup
+
+1.  **Install Dependencies**:
+    ```bash
+    npm install
+    ```
 
-We use **Vitest** for testing.
+2.  **Build in Watch Mode**:
+    ```bash
+    npm run dev
+    ```
+    This uses `tsup` to watch for changes and rebuild `dist/`.
+
+### Running Tests
+
+We prioritize **100% Test Coverage**. All logic branches, statements, and lines must be covered.
 
 ```bash
-# Run unit tests
-npm run test:unit
+# Run all unit tests (with coverage report)
+npm run test
 ```
 
+Tests are written using `vitest` and are located in `test/unit/`. When submitting changes, ensure coverage remains at 100%.
+
+---
+
+## Adding New Commands
+
+To create a new command, add a TypeScript file to `src/commands/`.
+
+**Example:** Create `src/commands/hello.ts`
+
+```typescript
+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}`);
+        }
+    }
+}
+```
+
+**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)
+
 ---
 
-## 🤝 Contributing
+## Contributing
 
-1.  **Fork** the repository.
-2.  **Clone** your fork.
-3.  **Install** dependencies (`npm install`).
-4.  **Creating a Command**:
-    - Add a new file in `src/commands/<topic>/<verb>.ts`.
-    - Extend `BaseCommand`.
-    - Define `static description` and `static args`.
-    - Implement `run()`.
-5.  **Test** your changes.
-6.  **Submit** a Pull Request.
+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**.
+4.  Submit a Pull Request.
 
 ---
 
 ## License
 
-Apache-2.0
+This project is licensed under the **Apache License 2.0**.

package/dist/chunk-JYASTIIW.js

@@ -0,0 +1,42 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  init_esm_shims
+} from "./chunk-OYFWMYPG.js";
+
+// src/utils/url-resolver.ts
+init_esm_shims();
+function resolveGitUrl(url) {
+  if (!url) {
+    throw new Error("URL cannot be empty");
+  }
+  let resolved = url;
+  if (resolved.startsWith("gh@")) {
+    resolved = resolved.replace(/^gh@/, "https://github.com/");
+  }
+  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);
+  }
+  const isLocal = repoUrl.startsWith("/") || repoUrl.startsWith("./") || repoUrl.startsWith("../") || repoUrl.startsWith("file:") || repoUrl.startsWith("~");
+  if (!isLocal && !repoUrl.endsWith(".git")) {
+    repoUrl += ".git";
+  }
+  if (subPath) {
+    return `${repoUrl}//${subPath}`;
+  }
+  return repoUrl;
+}
+
+export {
+  resolveGitUrl
+};
+//# sourceMappingURL=chunk-JYASTIIW.js.map

package/dist/chunk-JYASTIIW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/url-resolver.ts"],"sourcesContent":["/**\n * Resolves a git URL from various shorthand formats.\n * \n * Supported formats:\n * - gh@org/repo -> https://github.com/org/repo.git\n * - gh@org/repo//path -> https://github.com/org/repo.git//path\n * - https://github.com/org/repo -> https://github.com/org/repo.git\n * - https://github.com/org/repo.git -> https://github.com/org/repo.git\n * \n * @param url The URL string to resolve\n * @returns The fully qualified git URL with .git extension\n */\nexport function resolveGitUrl(url: string): string {\n    if (!url) {\n        throw new Error('URL cannot be empty');\n    }\n\n    let resolved = url;\n\n    // Handle gh@ syntax\n    if (resolved.startsWith('gh@')) {\n        resolved = resolved.replace(/^gh@/, 'https://github.com/');\n    }\n\n    // Handle subpaths (split by //)\n    // We must be careful not to split the protocol (e.g. https://)\n    const protocolMatch = resolved.match(/^[a-z0-9]+:\\/\\//i);\n    let splitIndex = -1;\n\n    if (protocolMatch) {\n        splitIndex = resolved.indexOf('//', protocolMatch[0].length);\n    } else {\n        splitIndex = resolved.indexOf('//');\n    }\n\n    let repoUrl = resolved;\n    let subPath = '';\n\n    if (splitIndex !== -1) {\n        repoUrl = resolved.substring(0, splitIndex);\n        subPath = resolved.substring(splitIndex + 2);\n    }\n\n    // Ensure .git extension, but ONLY for remote URLs (not local paths)\n    const isLocal = repoUrl.startsWith('/') || repoUrl.startsWith('./') || repoUrl.startsWith('../') || repoUrl.startsWith('file:') || repoUrl.startsWith('~');\n\n    if (!isLocal && !repoUrl.endsWith('.git')) {\n        repoUrl += '.git';\n    }\n\n    // Reconstruction\n    if (subPath) {\n        return `${repoUrl}//${subPath}`;\n    }\n\n    return repoUrl;\n}\n"],"mappings":";;;;;;AAAA;AAYO,SAAS,cAAc,KAAqB;AAC/C,MAAI,CAAC,KAAK;AACN,UAAM,IAAI,MAAM,qBAAqB;AAAA,EACzC;AAEA,MAAI,WAAW;AAGf,MAAI,SAAS,WAAW,KAAK,GAAG;AAC5B,eAAW,SAAS,QAAQ,QAAQ,qBAAqB;AAAA,EAC7D;AAIA,QAAM,gBAAgB,SAAS,MAAM,kBAAkB;AACvD,MAAI,aAAa;AAEjB,MAAI,eAAe;AACf,iBAAa,SAAS,QAAQ,MAAM,cAAc,CAAC,EAAE,MAAM;AAAA,EAC/D,OAAO;AACH,iBAAa,SAAS,QAAQ,IAAI;AAAA,EACtC;AAEA,MAAI,UAAU;AACd,MAAI,UAAU;AAEd,MAAI,eAAe,IAAI;AACnB,cAAU,SAAS,UAAU,GAAG,UAAU;AAC1C,cAAU,SAAS,UAAU,aAAa,CAAC;AAAA,EAC/C;AAGA,QAAM,UAAU,QAAQ,WAAW,GAAG,KAAK,QAAQ,WAAW,IAAI,KAAK,QAAQ,WAAW,KAAK,KAAK,QAAQ,WAAW,OAAO,KAAK,QAAQ,WAAW,GAAG;AAEzJ,MAAI,CAAC,WAAW,CAAC,QAAQ,SAAS,MAAM,GAAG;AACvC,eAAW;AAAA,EACf;AAGA,MAAI,SAAS;AACT,WAAO,GAAG,OAAO,KAAK,OAAO;AAAA,EACjC;AAEA,SAAO;AACX;","names":[]}