owox 0.0.0 → 0.1.0

package/README.md

@@ -6,127 +6,35 @@ A command-line interface for running OWOX Data Marts application. This CLI provi
 [![Version](https://img.shields.io/npm/v/owox.svg)](https://npmjs.org/package/owox)
 [![Downloads/week](https://img.shields.io/npm/dw/owox.svg)](https://npmjs.org/package/owox)
 
-<!-- toc -->
 
-- [Usage](#usage)
-- [Local Development: npm link](#local-development-npm-link)
-- [Commands](#commands)
-- [FAQ: Understanding the `bin` Folder](#faq-understanding-the-bin-folder)
-<!-- tocstop -->
 
-# Usage
+# Quick Start 🚀 (no-code setup)
 
-<!-- usage -->
+0. **Make sure Node.js ≥ 22.16.0 is installed**
 
-```sh-session
-$ npm install -g owox
-$ owox serve
-Starting OWOX Data Marts...
-Starting in production mode...
-Starting server on port 3000...
-$ owox --help
-USAGE
-  $ owox COMMAND
-...
-```
+   If you don't have it installed, [download it here](https://nodejs.org/en/download)   
+   <sub>(Windows / macOS / Linux installers are all listed there)</sub>
 
-<!-- usagestop -->
+2. **Open your terminal** and run **one** command  
+   ```bash
+   npm install -g owox
+   ```
+ 
+   <sub>You’ll see a list of added packages. Some warns are possible — just ignore them.</sub>
 
-# Local Development: npm link
 
-For local development and testing of this CLI, especially when it's not published to a public npm registry, you can use `npm link`. This command creates a symbolic link from your local package to the global npm directory, allowing you to run `owox` from any directory on your system as if it were globally installed.
+3. **Start OWOX Data Marts** locally
+   ```bash
+   owox serve
+   ```
+ 
+   <sub>Expected output:
+🚀 Starting OWOX Data Marts...
+📦 Starting server on port 3000...</sub>
 
-## Using `npm link`
+4. **Open** your browser at **http://localhost:3000** and explore! 🎉
 
-To link your local `owox` CLI globally, navigate to the `apps/owox` directory and execute:
+---
 
-```sh-session
-$ npm link
-```
-
-After successfully linking, you can run `owox` commands from any directory:
-
-```sh-session
-$ owox serve --port 8080
-```
-
-## Using `npm unlink -g owox`
-
-If you need to remove the global symbolic link to your local `owox` CLI, navigate to the `apps/owox` directory and execute:
-
-```sh-session
-$ npm unlink -g owox
-```
-
-This will remove the global link, and `owox` will no longer be accessible globally unless re-linked or installed through an npm registry.
-
-# Commands
-
-<!-- commands -->
-
-- [`owox serve`](#owox-serve)
-- [`owox help [COMMAND]`](#owox-help-command)
-
-## `owox serve`
-
-Start the OWOX Data Marts application in production mode
-
-```
-USAGE
-  $ owox serve [-p <value>]
-
-FLAGS
-  -p, --port=<value>  [default: 3000] Port number for the application
-
-DESCRIPTION
-  Start the OWOX Data Marts application in production mode
-
-EXAMPLES
-  $ owox serve
-  $ owox serve --port 8080
-  $ owox serve -p 3001
-  $ PORT=8080 owox serve
-```
-
-_See code: [src/commands/serve.ts](https://github.com/OWOX/owox-data-marts/blob/v0.0.0/src/commands/serve.ts)_
-
-## `owox help [COMMAND]`
-
-Display help for owox.
-
-```
-USAGE
-  $ owox help [COMMAND...] [-n]
-
-ARGUMENTS
-  COMMAND...  Command to show help for.
-
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
-
-DESCRIPTION
-  Display help for owox.
-```
-
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.0.21/src/commands/help.ts)_
-
-<!-- commandsstop -->
-
-# FAQ
-
-This section explains the purpose of the files located in the `bin` directory of the CLI.
-
-### Why are there files in the `bin` folder (`dev.cmd`, `run.js`, `dev.js`, `run.cmd`)? Why do some have a `.cmd` format?
-
-The `bin` folder contains the executable entry points for your CLI. Their presence and format are designed to support different operating systems and operational modes (development/production).
-
-- **`run.js` (and `run.cmd`)**: These are the primary "production" entry points for your CLI.
-
-  - **`run.js`**: This is the main executable file for Unix-based systems (Linux, macOS). The `#!/usr/bin/env node` (shebang) line at the beginning tells the operating system to execute this file using Node.js. This file launches the compiled version of your CLI (from the `dist` folder).
-  - **`run.cmd`**: This is the equivalent of `run.js` for Windows operating systems. Windows does not understand shebangs, so a separate `.cmd` (or `.bat`) file is required to explicitly instruct the system to execute the Node.js script using the `node` interpreter.
-
-- **`dev.js` (and `dev.cmd`)**: These are entry points specifically designed for **development**.
-  - **`dev.js`**: This executable file is for Unix-based systems when running in development mode. Notice the shebang line `#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning`. This allows Node.js to run your TypeScript code **without prior compilation** by using the `ts-node/esm` loader. This significantly speeds up development as you don't need to wait for compilation every time you make changes. The `development: true` flag is passed to `@oclif/core` to enable development-specific features.
-  - **`dev.cmd`**: This is the Windows equivalent of `dev.js`, also used for running in development mode with `ts-node/esm`.
-
-In summary, the `.cmd` files ensure compatibility with Windows, while the `run` and `dev` pairs provide distinct entry points for the "production-ready" (compiled) CLI version and the active development version (directly from TypeScript source files).
+👉 Ready to contribute or run in development mode? 
+Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for advanced setup and CLI commands.

package/dist/commands/serve.js

@@ -2,7 +2,6 @@ import { Command, Flags } from '@oclif/core';
 import { exec, spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
 import { promisify } from 'node:util';
 const execAsync = promisify(exec);
 const require = createRequire(import.meta.url);
@@ -44,11 +43,7 @@ export default class Serve extends Command {
         const { flags } = await this.parse(Serve);
         this.log('🚀 Starting OWOX Data Marts...');
         this.setupGracefulShutdown();
-        const backendPath = this.getBackendPath();
-        if (!this.isBackendAvailable(backendPath)) {
-            this.error('@owox/backend package not found. Please ensure it is installed:\n' +
-                'npm install @owox/backend', { exit: 1 });
-        }
+        const backendPath = this.validateBackendAvailability();
         try {
             await this.killMarkedProcesses();
             await this.startBackend(backendPath, flags.port);
@@ -90,20 +85,6 @@ export default class Serve extends Command {
         const numericPid = Number.parseInt(pid, 10);
         return !Number.isNaN(numericPid) && numericPid > 0 ? numericPid : null;
     }
-    /**
-     * Gets the path to the backend package
-     * @returns The full path to the backend entry point
-     */
-    getBackendPath() {
-        try {
-            // Try to resolve using Node.js module resolution
-            return require.resolve('@owox/backend');
-        }
-        catch {
-            // Fallback to node_modules path for ESM compatibility
-            return join(this.config.root, 'node_modules', '@owox/backend', 'dist', 'main.js');
-        }
-    }
     /**
      * Handles child process exit events
      * @param code - Exit code
@@ -138,14 +119,6 @@ export default class Serve extends Command {
         const message = error instanceof Error ? error.message : String(error);
         this.error(`Failed to start application: ${message}`, { exit: 1 });
     }
-    /**
-     * Checks if the backend package is available
-     * @param backendPath - Path to the backend entry point
-     * @returns True if backend package exists and is accessible
-     */
-    isBackendAvailable(backendPath) {
-        return existsSync(backendPath);
-    }
     /**
      * Kills all processes marked with PROCESS_MARKER
      */
@@ -229,6 +202,25 @@ export default class Serve extends Command {
         };
         await this.spawnProcess(options);
     }
+    /**
+     * Validates that the backend package is available and accessible
+     * @returns The resolved path to the backend entry point
+     * @throws Error if backend is not available or accessible
+     */
+    validateBackendAvailability() {
+        let backendPath;
+        try {
+            backendPath = require.resolve('@owox/backend');
+        }
+        catch {
+            this.error('@owox/backend package not found. Please ensure it is installed:\n' +
+                'npm install @owox/backend', { exit: 1 });
+        }
+        if (!existsSync(backendPath)) {
+            this.error('@owox/backend entry point not found', { exit: 1 });
+        }
+        return backendPath;
+    }
     /**
      * Waits for processes to cleanup
      */

package/oclif.manifest.json

@@ -38,5 +38,5 @@
       ]
     }
   },
-  "version": "0.0.0"
+  "version": "0.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "owox",
   "description": "OWOX Data Marts CLI: Simple command-line interface to start the OWOX Data Marts application with backend and frontend components.",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -13,7 +13,7 @@
     "@oclif/core": "^4",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-plugins": "^5",
-    "@owox/backend": "0.0.0"
+    "@owox/backend": "0.1.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -36,7 +36,7 @@
   },
   "files": [
     "./bin",
-    "./dist",
+    "./dist/**/*.js",
     "./oclif.manifest.json"
   ],
   "homepage": "https://github.com/OWOX/owox-data-marts",
@@ -70,6 +70,8 @@
   "scripts": {
     "build": "tsc -b",
     "lint": "eslint",
+    "lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.mjs",
+    "lint:md:fix": "markdownlint-cli2 --config ../../.markdownlint-cli2.mjs --fix",
     "posttest": "npm run lint",
     "prepack": "oclif manifest",
     "prepublishOnly": "npm audit && npm run test && npm run lint",

package/dist/commands/serve.d.ts

@@ -1,91 +0,0 @@
-import { Command } from '@oclif/core';
-/**
- * Command to start the OWOX Data Marts application.
- * Requires @owox/backend to be installed.
- */
-export default class Serve extends Command {
-    static description: string;
-    static examples: string[];
-    static flags: {
-        port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    private childProcess?;
-    private isShuttingDown;
-    /**
-     * Main execution method for the serve command
-     */
-    run(): Promise<void>;
-    /**
-     * Attaches event handlers to the child process
-     */
-    private attachProcessEventHandlers;
-    /**
-     * Creates environment variables for the child process
-     * @param port - Port number to set in environment
-     * @returns Environment variables object
-     */
-    private createProcessEnvironment;
-    /**
-     * Extracts PID from ps command output line
-     */
-    private extractPidFromProcessLine;
-    /**
-     * Gets the path to the backend package
-     * @returns The full path to the backend entry point
-     */
-    private getBackendPath;
-    /**
-     * Handles child process exit events
-     * @param code - Exit code
-     * @param signal - Exit signal
-     */
-    private handleProcessExit;
-    /**
-     * Handles shutdown signals
-     * @param signal - The received shutdown signal
-     */
-    private handleShutdownSignal;
-    /**
-     * Handles startup errors
-     * @param error - The error that occurred during startup
-     */
-    private handleStartupError;
-    /**
-     * Checks if the backend package is available
-     * @param backendPath - Path to the backend entry point
-     * @returns True if backend package exists and is accessible
-     */
-    private isBackendAvailable;
-    /**
-     * Kills all processes marked with PROCESS_MARKER
-     */
-    private killMarkedProcesses;
-    /**
-     * Kills a process by PID
-     */
-    private killProcess;
-    /**
-     * Sets up graceful shutdown handlers for system signals
-     */
-    private setupGracefulShutdown;
-    /**
-     * Spawns a child process with the given options
-     * @param options - Process spawn options
-     */
-    private spawnProcess;
-    /**
-     * Starts the backend application
-     * @param backendPath - Path to the backend entry point
-     * @param port - Port number to run the application on
-     */
-    private startBackend;
-    /**
-     * Waits for processes to cleanup
-     */
-    private waitForCleanup;
-    /**
-     * Waits for the child process to complete
-     * @returns Promise that resolves when process exits successfully
-     */
-    private waitForProcessCompletion;
-}

package/dist/index.d.ts

@@ -1 +0,0 @@
-export { run } from '@oclif/core';