owox 0.0.0

package/README.md

@@ -0,0 +1,132 @@
+# OWOX Data Marts CLI
+
+A command-line interface for running OWOX Data Marts application. This CLI provides a simple way to start the pre-built OWOX Data Marts server with frontend and backend components.
+
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![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
+
+<!-- usage -->
+
+```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
+...
+```
+
+<!-- usagestop -->
+
+# 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.
+
+## Using `npm link`
+
+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).

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/commands/serve.d.ts

@@ -0,0 +1,91 @@
+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/commands/serve.js

@@ -0,0 +1,265 @@
+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);
+/**
+ * Constants for the serve command
+ */
+const CONSTANTS = {
+    CLEANUP_DELAY_MS: 1000,
+    DEFAULT_PORT: 3000,
+    PROCESS_MARKER: 'owox-app',
+    SHUTDOWN_SIGNALS: ['SIGINT', 'SIGTERM'],
+};
+/**
+ * Command to start the OWOX Data Marts application.
+ * Requires @owox/backend to be installed.
+ */
+export default class Serve extends Command {
+    static description = 'Start the OWOX Data Marts application';
+    static examples = [
+        '<%= config.bin %> serve',
+        '<%= config.bin %> serve --port 8080',
+        '<%= config.bin %> serve -p 3001',
+        '$ PORT=8080 <%= config.bin %> serve',
+    ];
+    static flags = {
+        port: Flags.integer({
+            char: 'p',
+            default: CONSTANTS.DEFAULT_PORT,
+            description: 'Port number for the application',
+            env: 'PORT',
+        }),
+    };
+    childProcess;
+    isShuttingDown = false;
+    /**
+     * Main execution method for the serve command
+     */
+    async run() {
+        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 });
+        }
+        try {
+            await this.killMarkedProcesses();
+            await this.startBackend(backendPath, flags.port);
+        }
+        catch (error) {
+            this.handleStartupError(error);
+        }
+    }
+    /**
+     * Attaches event handlers to the child process
+     */
+    attachProcessEventHandlers() {
+        if (!this.childProcess)
+            return;
+        this.childProcess.on('error', (error) => {
+            if (!this.isShuttingDown) {
+                this.error(`Application process error: ${error.message}`);
+            }
+        });
+        this.childProcess.on('exit', (code, signal) => {
+            if (!this.isShuttingDown) {
+                this.handleProcessExit(code, signal);
+            }
+        });
+    }
+    /**
+     * Creates environment variables for the child process
+     * @param port - Port number to set in environment
+     * @returns Environment variables object
+     */
+    createProcessEnvironment(port) {
+        return { ...process.env, PORT: port.toString() };
+    }
+    /**
+     * Extracts PID from ps command output line
+     */
+    extractPidFromProcessLine(processLine) {
+        const pid = processLine.trim().split(/\s+/)[1];
+        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
+     * @param signal - Exit signal
+     */
+    handleProcessExit(code, signal) {
+        if (code !== null && code !== 0) {
+            this.error(`Application process exited with code ${code}`);
+        }
+        else if (signal) {
+            this.warn(`Application process terminated by signal ${signal}`);
+        }
+    }
+    /**
+     * Handles shutdown signals
+     * @param signal - The received shutdown signal
+     */
+    handleShutdownSignal(signal) {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        this.log(`Received ${signal}, shutting down gracefully...`);
+        if (this.childProcess?.kill()) {
+            this.log('Stopping application...');
+        }
+    }
+    /**
+     * Handles startup errors
+     * @param error - The error that occurred during startup
+     */
+    handleStartupError(error) {
+        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
+     */
+    async killMarkedProcesses() {
+        try {
+            const { stdout } = await execAsync(`ps -ef | grep "${CONSTANTS.PROCESS_MARKER}" | grep -v grep`);
+            if (!stdout.trim()) {
+                this.log(`🔍 No previous zombie processes found`);
+                return;
+            }
+            const processes = stdout.trim().split('\n');
+            this.warn(`🧹 Found ${processes.length} zombie processes, cleaning up...`);
+            const killPromises = processes.map(async (processLine) => {
+                const pid = this.extractPidFromProcessLine(processLine);
+                if (pid) {
+                    await this.killProcess(pid);
+                }
+            });
+            await Promise.all(killPromises);
+            await this.waitForCleanup();
+            this.log(`✅ Zombie cleanup completed`);
+        }
+        catch {
+            // This is normal if no previous processes are found
+            this.log(`🔍 No previous zombie processes found`);
+        }
+    }
+    /**
+     * Kills a process by PID
+     */
+    async killProcess(pid) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            this.log(`💀 Killed zombie process PID: ${pid}`);
+        }
+        catch {
+            this.log(`🔍 Process ${pid} already terminated`);
+        }
+    }
+    /**
+     * Sets up graceful shutdown handlers for system signals
+     */
+    setupGracefulShutdown() {
+        for (const signal of CONSTANTS.SHUTDOWN_SIGNALS) {
+            process.on(signal, () => this.handleShutdownSignal(signal));
+        }
+    }
+    /**
+     * Spawns a child process with the given options
+     * @param options - Process spawn options
+     */
+    async spawnProcess(options) {
+        const env = this.createProcessEnvironment(options.port);
+        this.log(`📦 Starting server on port ${options.port}...`);
+        // Add process marker to arguments
+        const argsWithMarker = [...options.args, `--${CONSTANTS.PROCESS_MARKER}`];
+        this.childProcess = spawn(options.command, argsWithMarker, {
+            env,
+            stdio: 'inherit',
+        });
+        if (this.childProcess.pid) {
+            this.log(`📦 Server process started with PID: ${this.childProcess.pid}`);
+        }
+        else {
+            throw new Error('Failed to start server process');
+        }
+        this.attachProcessEventHandlers();
+        return this.waitForProcessCompletion();
+    }
+    /**
+     * Starts the backend application
+     * @param backendPath - Path to the backend entry point
+     * @param port - Port number to run the application on
+     */
+    async startBackend(backendPath, port) {
+        this.log('Starting backend application...');
+        const options = {
+            args: [backendPath],
+            command: 'node',
+            port,
+        };
+        await this.spawnProcess(options);
+    }
+    /**
+     * Waits for processes to cleanup
+     */
+    async waitForCleanup() {
+        return new Promise(resolve => {
+            setTimeout(() => resolve(), CONSTANTS.CLEANUP_DELAY_MS);
+        });
+    }
+    /**
+     * Waits for the child process to complete
+     * @returns Promise that resolves when process exits successfully
+     */
+    waitForProcessCompletion() {
+        return new Promise((resolve, reject) => {
+            if (!this.childProcess) {
+                reject(new Error('Failed to start child process'));
+                return;
+            }
+            this.childProcess.on('exit', (code) => {
+                if (this.isShuttingDown) {
+                    this.log('Application stopped successfully.');
+                    resolve();
+                }
+                else if (code === 0 || code === null) {
+                    this.log('Application process exited successfully.');
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Application process failed with exit code ${code}`));
+                }
+            });
+        });
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/oclif.manifest.json

@@ -0,0 +1,42 @@
+{
+  "commands": {
+    "serve": {
+      "aliases": [],
+      "args": {},
+      "description": "Start the OWOX Data Marts application",
+      "examples": [
+        "<%= config.bin %> serve",
+        "<%= config.bin %> serve --port 8080",
+        "<%= config.bin %> serve -p 3001",
+        "$ PORT=8080 <%= config.bin %> serve"
+      ],
+      "flags": {
+        "port": {
+          "char": "p",
+          "description": "Port number for the application",
+          "env": "PORT",
+          "name": "port",
+          "default": 3000,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "serve",
+      "pluginAlias": "owox",
+      "pluginName": "owox",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "serve.js"
+      ]
+    }
+  },
+  "version": "0.0.0"
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "owox": "./bin/run.js"
+  },
+  "bugs": "https://github.com/OWOX/owox-data-marts/issues",
+  "dependencies": {
+    "@oclif/core": "^4",
+    "@oclif/plugin-help": "^6",
+    "@oclif/plugin-plugins": "^5",
+    "@owox/backend": "0.0.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1",
+    "@oclif/prettier-config": "^0.2.1",
+    "@oclif/test": "^4",
+    "@types/chai": "^4",
+    "@types/mocha": "^10",
+    "@types/node": "^18",
+    "chai": "^4",
+    "eslint": "^9",
+    "eslint-config-oclif": "^6",
+    "eslint-config-prettier": "^10",
+    "mocha": "^10",
+    "oclif": "^4",
+    "ts-node": "^10",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "files": [
+    "./bin",
+    "./dist",
+    "./oclif.manifest.json"
+  ],
+  "homepage": "https://github.com/OWOX/owox-data-marts",
+  "keywords": [
+    "data-marts",
+    "cli",
+    "server",
+    "nestjs",
+    "backend",
+    "owox",
+    "data-orchestration",
+    "sqlite",
+    "mysql",
+    "bigquery",
+    "athena"
+  ],
+  "license": "ELv2",
+  "main": "dist/index.js",
+  "type": "module",
+  "oclif": {
+    "bin": "owox",
+    "dirname": "owox",
+    "commands": "./dist/commands",
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-plugins"
+    ],
+    "topicSeparator": " "
+  },
+  "repository": "OWOX/owox-data-marts",
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint",
+    "posttest": "npm run lint",
+    "prepack": "oclif manifest",
+    "prepublishOnly": "npm audit && npm run test && npm run lint",
+    "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "version": "oclif readme && git add README.md"
+  },
+  "types": "dist/index.d.ts"
+}