@nexical/cli 0.11.23 → 0.12.0

package/README.md

@@ -78,238 +78,142 @@ npm run build
 
 ```bash
 # Run the built CLI
-npx nexical <command> [options]
+nexical <command> [options]
 
 # Example: Initialize a new project
-npx nexical init my-new-project
+nexical init my-new-project
 
 # Get help
-npx nexical help
+nexical help
 
 # Get help for a specific command
-npx nexical help init
-npx nexical help module add
+nexical help init
+nexical help module add
 ```
 
 ### Command Reference
 
 #### `init`
 
-Initializes a new Nexical project by cloning a starter repository, setting up dependencies, and preparing a fresh git history.
+Initializes a new Nexical project. It clones a starter repository, sets up submodules, installs dependencies, and resets the Git history to provide a clean starting point.
 
 **Usage:**
 
 ```bash
-npx nexical init <directory> [options]
+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.
+- `--repo <url>`: The Git repository URL of the starter template (Default: `https://github.com/nexical/app-core`).
 
 ---
 
-#### `dev`
+#### `deploy`
 
-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).
+Orchestrates the deployment of your applications by interacting with cloud providers and configuring your repository's CI/CD environment.
 
 **Usage:**
 
 ```bash
-npx nexical dev
+nexical deploy [options]
 ```
 
-**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.
-
----
-
-#### `build`
-
-Compiles the project for production. It assembles the final site structure in `site` and generates static assets.
-
-**Usage:**
+**Options:**
 
-```bash
-npx nexical build
+- `--env <environment>`: Deployment environment (e.g., `production`, `staging`). Defaults to `production`.
+- `--apps <apps>`: Comma separated list of applications to deploy (e.g., `backend,frontend`). If omitted, all applications are deployed.
+- `--dry-run`: Simulate the deployment process without making API calls to providers or modifying repository secrets.
+
+**Process:**
+
+1.  **Load Config**: Reads `nexical.yaml` and validates the schema.
+2.  **Provision**: Concurrently calls providers to ensure resources exist.
+3.  **Sync Secrets**: Collects necessary API tokens and credentials, syncing them to the repository (e.g., GitHub Secrets).
+4.  **Generate Workflows**: Renders CI/CD workflow files into `.github/workflows/` using standard templates.
+
+**Configuration (`nexical.yaml`):**
+
+```yaml
+deploy:
+  repository:
+    provider: github
+  apps:
+    backend:
+      provider: railway
+      projectName: my-api
+      target: apps/backend
+      artifactPath: dist
+      buildCommand: npm run build --workspace=@app/backend
+      secrets:
+        DB_PASSWORD: DATABASE_PASSWORD_ENV # Maps provider secret to local ENV var
+      env:
+        NODE_ENV: production # Literal value
+    frontend:
+      provider: cloudflare
+      projectName: my-web
+      target: apps/frontend
+      artifactPath: dist
+      buildCommand: npm run build --workspace=@app/frontend
 ```
 
-**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`
+#### `prompt`
 
-Previews the locally built production site. This is useful for verifying the output of `nexical build` before deploying.
+Packages the project context using `repomix` and runs AI-powered analysis or generation.
 
 **Usage:**
 
 ```bash
-npx nexical preview
+nexical prompt [options]
 ```
 
-**Prerequisites:**
-
-- You must run `nexical build` first.
-
-**What it does:**
+**Options:**
 
-- Starts a local web server serving the static files from `site/dist`.
+- `--output <path>`: Path to save the packed context file.
+- `--config <path>`: Custom configuration for the prompt runner.
 
 ---
 
-#### `clean`
+#### `setup`
 
-Removes generated build artifacts and temporary directories to ensure a clean state.
+Prepares the local development environment, ensuring all necessary tools and configurations are in place.
 
 **Usage:**
 
 ```bash
-npx nexical clean
+nexical setup
 ```
 
-**What it does:**
-
-- Deletes `site`, `dist`, and `node_modules/.vite`.
-
 ---
 
 #### `run`
 
-Executes a script within the Nexical environment context. This handles path resolution and environment variable setup for you.
+Executes a command or script within the Nexical project context, handling environment variables and path resolution.
 
 **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`).
-- `args` (Optional): Additional arguments to pass to the script.
-
-**Examples:**
-
-```bash
-# Run a core project script
-npx nexical run test
-
-# Run a script defined in the 'blog' module's package.json
-npx nexical run blog:sync --force
+nexical run <script> [args...]
 ```
 
 ---
 
 #### `module`
 
-Manages the modular architecture of your Nexical project. Allows you to add, remove, update, and list Git-based modules.
-
-##### `module add`
-
-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.
-- `name` (Optional): The folder name for the module. Defaults to the repository name.
-
-**What it does:**
+Manages the modular components of your project.
 
-1.  Adds the repository as a git submodule in `src/modules/<name>`.
-2.  Installs any new dependencies via `npm install`.
+- **`module add <url> [name]`**: Adds a new Git-based module as a submodule.
+- **`module list`**: Displays a table of all installed modules.
+- **`module update [name]`**: Updates a specific module or all modules to their latest remote versions.
+- **`module remove <name>`**: Safely removes a module and cleans up Git metadata.
 
-##### `module list`
-
-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`
-
-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.
-
-##### `module remove`
-
-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:**
+#### `dev` / `build` / `preview`
 
-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.
+Standard development cycle commands inherited from the underlying app structure (typically Astro).
 
 ---
 
@@ -318,20 +222,21 @@ npx nexical module remove <name>
 ```mermaid
 graph TD
     src-->commands
+    src-->deploy
     src-->core
     src-->utils
+    commands-->deploy.ts
     commands-->init.ts
-    core-->CLI.ts
-    core-->BaseCommand.ts
-    core-->CommandLoader.ts
-    utils-->config.ts
-    utils-->logger.ts
+    commands-->module
+    deploy-->providers
+    deploy-->schema.ts
+    deploy-->template-manager.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/`**: Command implementation classes.
+- **`src/deploy/`**: Core logic for the deployment orchestration system.
+- **`src/core/`**: CLI framework (base classes, loader).
+- **`src/utils/`**: Helper utilities.
 
 ---
 
@@ -339,87 +244,37 @@ graph TD
 
 ### Prerequisites
 
-- Node.js (v18+ recommended)
-- NPM
+- Node.js (v18+)
+- NPM/PNPM
 
 ### Setup
 
-1.  **Install Dependencies**:
-
-    ```bash
-    npm install
-    ```
-
-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 all unit tests (with coverage report)
-npm run test
+npm install
+npm run build # Required to generate dist/ for local execution
 ```
 
-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 }],
-  };
+### Running Tests
 
-  // 2. Implement the run method
-  async run(options: any) {
-    const name = options.name || 'World';
+We maintain strict **100% test coverage** for all logic.
 
-    if (options.shout) {
-      this.success(`HELLO ${name.toUpperCase()}!`);
-    } else {
-      this.log(`Hello ${name}`);
-    }
-  }
-}
+```bash
+npm run test           # All tests
+npm run test:unit      # Unit tests
+npm run test:integration # Integration tests
 ```
 
-**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
 
-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.
+1.  Fork the repo and create a branch.
+2.  Implement changes with accompanying tests.
+3.  Ensure 100% coverage: `npm run test:unit`.
+4.  Submit a PR.
 
 ---
 
 ## License
 
-This project is licensed under the **Apache License 2.0**.
+Apache License 2.0

package/dist/{chunk-OYFWMYPG.js → chunk-6DE5Q66O.js}

@@ -17,6 +17,10 @@ var __esm = (fn, res) => function __init() {
 var __commonJS = (cb, mod) => function __require2() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -46,7 +50,8 @@ var init_esm_shims = __esm({
 export {
   __require,
   __commonJS,
+  __export,
   __toESM,
   init_esm_shims
 };
-//# sourceMappingURL=chunk-OYFWMYPG.js.map
+//# sourceMappingURL=chunk-6DE5Q66O.js.map

package/dist/{chunk-OYFWMYPG.js.map → chunk-6DE5Q66O.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../node_modules/tsup/assets/esm_shims.js"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAF9B;AAAA;AAAA;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../node_modules/tsup/assets/esm_shims.js"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAF9B;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/chunk-G66GMEFE.js

@@ -0,0 +1,31 @@
+import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  init_esm_shims
+} from "./chunk-6DE5Q66O.js";
+
+// src/deploy/template-manager.ts
+init_esm_shims();
+import fs from "fs/promises";
+import path from "path";
+import YAML from "yaml";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var TemplateManager = class {
+  templatesDir;
+  constructor() {
+    this.templatesDir = path.join(__dirname, "templates");
+  }
+  async loadWorkflow(name, data) {
+    const templatePath = path.join(this.templatesDir, `${name}.yaml`);
+    let content = await fs.readFile(templatePath, "utf-8");
+    for (const [key, value] of Object.entries(data)) {
+      content = content.split(`\${${key}}`).join(value);
+    }
+    return YAML.parse(content);
+  }
+};
+
+export {
+  TemplateManager
+};
+//# sourceMappingURL=chunk-G66GMEFE.js.map

package/dist/chunk-G66GMEFE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/deploy/template-manager.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport YAML from 'yaml';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nexport interface WorkflowTemplateData {\n  APP_NAME: string;\n  PROVIDER_NAME: string;\n  [key: string]: string;\n}\n\nexport class TemplateManager {\n  private templatesDir: string;\n\n  constructor() {\n    this.templatesDir = path.join(__dirname, 'templates');\n  }\n\n  async loadWorkflow(name: string, data: WorkflowTemplateData): Promise<unknown> {\n    const templatePath = path.join(this.templatesDir, `${name}.yaml`);\n    let content = await fs.readFile(templatePath, 'utf-8');\n\n    // Simple placeholder replacement\n    for (const [key, value] of Object.entries(data)) {\n      content = content.split(`\\${${key}}`).join(value);\n    }\n\n    return YAML.parse(content);\n  }\n}\n"],"mappings":";;;;;;AAAA;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AACjB,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAE9B,IAAM,YAAY,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AAQtD,IAAM,kBAAN,MAAsB;AAAA,EACnB;AAAA,EAER,cAAc;AACZ,SAAK,eAAe,KAAK,KAAK,WAAW,WAAW;AAAA,EACtD;AAAA,EAEA,MAAM,aAAa,MAAc,MAA8C;AAC7E,UAAM,eAAe,KAAK,KAAK,KAAK,cAAc,GAAG,IAAI,OAAO;AAChE,QAAI,UAAU,MAAM,GAAG,SAAS,cAAc,OAAO;AAGrD,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,gBAAU,QAAQ,MAAM,MAAM,GAAG,GAAG,EAAE,KAAK,KAAK;AAAA,IAClD;AAEA,WAAO,KAAK,MAAM,OAAO;AAAA,EAC3B;AACF;","names":[]}

package/dist/{chunk-2FKDEDDE.js → chunk-HOVS7SCD.js}

@@ -1,13 +1,17 @@
 import { createRequire } from "module"; const require = createRequire(import.meta.url);
+import {
+  DeploymentSchema
+} from "./chunk-JGAMEJTL.js";
 import {
   init_esm_shims
-} from "./chunk-OYFWMYPG.js";
+} from "./chunk-6DE5Q66O.js";
 
 // src/deploy/config-manager.ts
 init_esm_shims();
 import fs from "fs/promises";
 import path from "path";
 import YAML from "yaml";
+import { logger } from "@nexical/cli-core";
 var ConfigManager = class {
   configPath;
   constructor(cwd) {
@@ -16,7 +20,16 @@ var ConfigManager = class {
   async load() {
     try {
       const content = await fs.readFile(this.configPath, "utf-8");
-      return YAML.parse(content);
+      const parsed = YAML.parse(content);
+      const result = DeploymentSchema.safeParse(parsed);
+      if (!result.success) {
+        logger.error("Invalid nexical.yaml configuration:");
+        result.error.issues.forEach((err) => {
+          logger.error(`  - ${err.path.join(".")}: ${err.message}`);
+        });
+        throw new Error("Configuration validation failed.");
+      }
+      return result.data;
     } catch (error) {
       if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
         return {};
@@ -36,4 +49,4 @@ var ConfigManager = class {
 export {
   ConfigManager
 };
-//# sourceMappingURL=chunk-2FKDEDDE.js.map
+//# sourceMappingURL=chunk-HOVS7SCD.js.map

package/dist/chunk-HOVS7SCD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/deploy/config-manager.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport YAML from 'yaml';\nimport { NexicalConfig } from './types';\nimport { DeploymentSchema } from './schema';\nimport { logger } from '@nexical/cli-core';\n\nexport class ConfigManager {\n  private configPath: string;\n\n  constructor(cwd: string) {\n    this.configPath = path.join(cwd, 'nexical.yaml');\n  }\n\n  async load(): Promise<NexicalConfig> {\n    try {\n      const content = await fs.readFile(this.configPath, 'utf-8');\n      const parsed = YAML.parse(content);\n\n      const result = DeploymentSchema.safeParse(parsed);\n      if (!result.success) {\n        logger.error('Invalid nexical.yaml configuration:');\n        result.error.issues.forEach((err) => {\n          logger.error(`  - ${err.path.join('.')}: ${err.message}`);\n        });\n        throw new Error('Configuration validation failed.');\n      }\n\n      return result.data as NexicalConfig;\n    } catch (error: unknown) {\n      if (\n        error &&\n        typeof error === 'object' &&\n        'code' in error &&\n        (error as { code: unknown }).code === 'ENOENT'\n      ) {\n        return {};\n      }\n      throw error;\n    }\n  }\n\n  async save(config: NexicalConfig): Promise<void> {\n    const content = YAML.stringify(config);\n    await fs.writeFile(this.configPath, content, 'utf-8');\n  }\n\n  exists(): Promise<boolean> {\n    return fs\n      .access(this.configPath)\n      .then(() => true)\n      .catch(() => false);\n  }\n}\n"],"mappings":";;;;;;;;;AAAA;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AACjB,OAAO,UAAU;AAGjB,SAAS,cAAc;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACjB;AAAA,EAER,YAAY,KAAa;AACvB,SAAK,aAAa,KAAK,KAAK,KAAK,cAAc;AAAA,EACjD;AAAA,EAEA,MAAM,OAA+B;AACnC,QAAI;AACF,YAAM,UAAU,MAAM,GAAG,SAAS,KAAK,YAAY,OAAO;AAC1D,YAAM,SAAS,KAAK,MAAM,OAAO;AAEjC,YAAM,SAAS,iBAAiB,UAAU,MAAM;AAChD,UAAI,CAAC,OAAO,SAAS;AACnB,eAAO,MAAM,qCAAqC;AAClD,eAAO,MAAM,OAAO,QAAQ,CAAC,QAAQ;AACnC,iBAAO,MAAM,OAAO,IAAI,KAAK,KAAK,GAAG,CAAC,KAAK,IAAI,OAAO,EAAE;AAAA,QAC1D,CAAC;AACD,cAAM,IAAI,MAAM,kCAAkC;AAAA,MACpD;AAEA,aAAO,OAAO;AAAA,IAChB,SAAS,OAAgB;AACvB,UACE,SACA,OAAO,UAAU,YACjB,UAAU,SACT,MAA4B,SAAS,UACtC;AACA,eAAO,CAAC;AAAA,MACV;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,KAAK,QAAsC;AAC/C,UAAM,UAAU,KAAK,UAAU,MAAM;AACrC,UAAM,GAAG,UAAU,KAAK,YAAY,SAAS,OAAO;AAAA,EACtD;AAAA,EAEA,SAA2B;AACzB,WAAO,GACJ,OAAO,KAAK,UAAU,EACtB,KAAK,MAAM,IAAI,EACf,MAAM,MAAM,KAAK;AAAA,EACtB;AACF;","names":[]}

package/dist/{chunk-GUUPSHWC.js → chunk-JEMIKBGX.js}

@@ -1,11 +1,11 @@
 import { createRequire } from "module"; const require = createRequire(import.meta.url);
 import {
   require_lib
-} from "./chunk-OUGA4CB4.js";
+} from "./chunk-JS6WL5NS.js";
 import {
   __toESM,
   init_esm_shims
-} from "./chunk-OYFWMYPG.js";
+} from "./chunk-6DE5Q66O.js";
 
 // src/commands/setup.ts
 init_esm_shims();
@@ -67,4 +67,4 @@ var SetupCommand = class extends BaseCommand {
 export {
   SetupCommand
 };
-//# sourceMappingURL=chunk-GUUPSHWC.js.map
+//# sourceMappingURL=chunk-JEMIKBGX.js.map