@genomic/utils 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Constructive <developers@constructive.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @genomic/utils
+
+CLI lifecycle utilities for building command-line applications.
+
+## Installation
+
+```bash
+npm install @genomic/utils
+```
+
+## Features
+
+### extractFirst
+
+Extracts the first positional argument from argv for command routing:
+
+```typescript
+import { extractFirst } from '@genomic/utils';
+
+const { first, newArgv } = extractFirst(argv);
+// first = 'init' (the subcommand)
+// newArgv = remaining arguments with first positional removed
+```
+
+### cliExitWithError
+
+Exits the CLI with an error message and optional cleanup:
+
+```typescript
+import { cliExitWithError } from '@genomic/utils';
+
+await cliExitWithError(error, {
+  beforeExit: async () => {
+    await closeConnections();
+  }
+});
+```
+
+### checkForUpdates
+
+Checks for package updates with caching:
+
+```typescript
+import { checkForUpdates } from '@genomic/utils';
+
+const result = await checkForUpdates({
+  pkgName: '@my/cli',
+  pkgVersion: '1.0.0',
+  registryBaseUrl: 'https://registry.npmjs.org'
+});
+
+if (result.hasUpdate) {
+  console.log(result.message);
+}
+```
+
+### getSelfPackageJson
+
+Gets the package.json for the current package:
+
+```typescript
+import { getSelfPackageJson, getSelfVersion, getSelfName } from '@genomic/utils';
+
+const pkg = getSelfPackageJson(__dirname);
+const version = getSelfVersion(__dirname);
+const name = getSelfName(__dirname);
+```
+
+## License
+
+MIT
+
+---
+
+## Development
+
+### Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/constructive-io/dev-utils.git
+```
+
+2. Install dependencies:
+
+```bash
+cd dev-utils
+pnpm install
+pnpm build
+```
+
+3. Test the package of interest:
+
+```bash
+cd packages/<packagename>
+pnpm test:watch
+```
+
+## Credits
+
+Built for developers, with developers.  
+👉 https://launchql.com | https://hyperweb.io
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/argv.d.ts

@@ -0,0 +1,13 @@
+import { ParsedArgs } from 'minimist';
+/**
+ * Extracts the first positional argument from argv and returns it along with the remaining argv.
+ * This is useful for command routing in CLI applications where the first argument is a subcommand.
+ */
+export declare const extractFirst: (argv: Partial<ParsedArgs>) => {
+    first: string;
+    newArgv: {
+        _: string[];
+        "--"?: string[] | undefined;
+    };
+};
+export type { ParsedArgs } from 'minimist';

package/argv.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFirst = void 0;
+/**
+ * Extracts the first positional argument from argv and returns it along with the remaining argv.
+ * This is useful for command routing in CLI applications where the first argument is a subcommand.
+ */
+const extractFirst = (argv) => {
+    const first = argv._?.[0];
+    const newArgv = {
+        ...argv,
+        _: argv._?.slice(1) ?? []
+    };
+    return { first, newArgv };
+};
+exports.extractFirst = extractFirst;

package/cli-error.d.ts

@@ -0,0 +1,14 @@
+export interface CliExitOptions {
+    context?: Record<string, any>;
+    beforeExit?: () => Promise<void>;
+    logger?: {
+        error: (message: string, ...args: any[]) => void;
+        debug: (message: string, ...args: any[]) => void;
+        warn: (message: string, ...args: any[]) => void;
+    };
+}
+/**
+ * Exits the CLI with an error message and optional cleanup.
+ * Supports a beforeExit hook for cleanup operations (e.g., closing database connections).
+ */
+export declare const cliExitWithError: (error: Error | string, options?: CliExitOptions) => Promise<never>;

package/cli-error.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cliExitWithError = void 0;
+/**
+ * Exits the CLI with an error message and optional cleanup.
+ * Supports a beforeExit hook for cleanup operations (e.g., closing database connections).
+ */
+const cliExitWithError = async (error, options = {}) => {
+    const { context, beforeExit, logger = console } = options;
+    if (error instanceof Error) {
+        logger.error(`Error: ${error.message}`);
+        if (context) {
+            logger.debug('Context:', context);
+        }
+    }
+    else if (typeof error === 'string') {
+        logger.error(`Error: ${error}`);
+        if (context) {
+            logger.debug('Context:', context);
+        }
+    }
+    if (beforeExit) {
+        try {
+            await beforeExit();
+            logger.debug('Cleanup completed');
+        }
+        catch (cleanupError) {
+            logger.warn('Failed to complete cleanup:', cleanupError);
+        }
+    }
+    process.exit(1);
+};
+exports.cliExitWithError = cliExitWithError;

package/esm/argv.d.ts

@@ -0,0 +1,13 @@
+import { ParsedArgs } from 'minimist';
+/**
+ * Extracts the first positional argument from argv and returns it along with the remaining argv.
+ * This is useful for command routing in CLI applications where the first argument is a subcommand.
+ */
+export declare const extractFirst: (argv: Partial<ParsedArgs>) => {
+    first: string;
+    newArgv: {
+        _: string[];
+        "--"?: string[] | undefined;
+    };
+};
+export type { ParsedArgs } from 'minimist';

package/esm/argv.js

@@ -0,0 +1,12 @@
+/**
+ * Extracts the first positional argument from argv and returns it along with the remaining argv.
+ * This is useful for command routing in CLI applications where the first argument is a subcommand.
+ */
+export const extractFirst = (argv) => {
+    const first = argv._?.[0];
+    const newArgv = {
+        ...argv,
+        _: argv._?.slice(1) ?? []
+    };
+    return { first, newArgv };
+};

package/esm/cli-error.d.ts

@@ -0,0 +1,14 @@
+export interface CliExitOptions {
+    context?: Record<string, any>;
+    beforeExit?: () => Promise<void>;
+    logger?: {
+        error: (message: string, ...args: any[]) => void;
+        debug: (message: string, ...args: any[]) => void;
+        warn: (message: string, ...args: any[]) => void;
+    };
+}
+/**
+ * Exits the CLI with an error message and optional cleanup.
+ * Supports a beforeExit hook for cleanup operations (e.g., closing database connections).
+ */
+export declare const cliExitWithError: (error: Error | string, options?: CliExitOptions) => Promise<never>;

package/esm/cli-error.js

@@ -0,0 +1,29 @@
+/**
+ * Exits the CLI with an error message and optional cleanup.
+ * Supports a beforeExit hook for cleanup operations (e.g., closing database connections).
+ */
+export const cliExitWithError = async (error, options = {}) => {
+    const { context, beforeExit, logger = console } = options;
+    if (error instanceof Error) {
+        logger.error(`Error: ${error.message}`);
+        if (context) {
+            logger.debug('Context:', context);
+        }
+    }
+    else if (typeof error === 'string') {
+        logger.error(`Error: ${error}`);
+        if (context) {
+            logger.debug('Context:', context);
+        }
+    }
+    if (beforeExit) {
+        try {
+            await beforeExit();
+            logger.debug('Cleanup completed');
+        }
+        catch (cleanupError) {
+            logger.warn('Failed to complete cleanup:', cleanupError);
+        }
+    }
+    process.exit(1);
+};

package/esm/index.d.ts

@@ -0,0 +1,8 @@
+export { extractFirst } from './argv';
+export type { ParsedArgs } from './argv';
+export { cliExitWithError } from './cli-error';
+export type { CliExitOptions } from './cli-error';
+export { checkForUpdates } from './update-check';
+export type { UpdateCheckOptions, UpdateCheckResult } from './update-check';
+export { getSelfPackageJson, getSelfVersion, getSelfName } from './package-json';
+export type { PackageJsonInfo } from './package-json';

package/esm/index.js

@@ -0,0 +1,8 @@
+// Argv utilities
+export { extractFirst } from './argv';
+// CLI error handling
+export { cliExitWithError } from './cli-error';
+// Update checking
+export { checkForUpdates } from './update-check';
+// Package.json utilities
+export { getSelfPackageJson, getSelfVersion, getSelfName } from './package-json';

package/esm/package-json.d.ts

@@ -0,0 +1,18 @@
+export interface PackageJsonInfo {
+    name: string;
+    version: string;
+    [key: string]: any;
+}
+/**
+ * Gets the package.json for the current package by searching up from the given directory.
+ * This is useful for CLIs to get their own version information.
+ */
+export declare const getSelfPackageJson: (dirname: string) => PackageJsonInfo;
+/**
+ * Gets the version from the package.json for the current package.
+ */
+export declare const getSelfVersion: (dirname: string) => string;
+/**
+ * Gets the name from the package.json for the current package.
+ */
+export declare const getSelfName: (dirname: string) => string;

package/esm/package-json.js

@@ -0,0 +1,20 @@
+import { findAndRequirePackageJson } from 'find-and-require-package-json';
+/**
+ * Gets the package.json for the current package by searching up from the given directory.
+ * This is useful for CLIs to get their own version information.
+ */
+export const getSelfPackageJson = (dirname) => {
+    return findAndRequirePackageJson(dirname);
+};
+/**
+ * Gets the version from the package.json for the current package.
+ */
+export const getSelfVersion = (dirname) => {
+    return getSelfPackageJson(dirname).version;
+};
+/**
+ * Gets the name from the package.json for the current package.
+ */
+export const getSelfName = (dirname) => {
+    return getSelfPackageJson(dirname).name;
+};

package/esm/update-check.d.ts

@@ -0,0 +1,18 @@
+export interface UpdateCheckOptions {
+    pkgName: string;
+    pkgVersion: string;
+    registryBaseUrl?: string;
+    toolName?: string;
+    ttl?: number;
+}
+export interface UpdateCheckResult {
+    hasUpdate: boolean;
+    currentVersion: string;
+    latestVersion: string | null;
+    message: string | null;
+}
+/**
+ * Checks for updates to a package and caches the result.
+ * Uses appstash for configuration storage.
+ */
+export declare const checkForUpdates: (options: UpdateCheckOptions) => Promise<UpdateCheckResult>;

package/esm/update-check.js

@@ -0,0 +1,76 @@
+import { appstash } from 'appstash';
+import * as fs from 'fs';
+import * as path from 'path';
+const DEFAULT_TTL = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/**
+ * Checks for updates to a package and caches the result.
+ * Uses appstash for configuration storage.
+ */
+export const checkForUpdates = async (options) => {
+    const { pkgName, pkgVersion, registryBaseUrl = DEFAULT_REGISTRY, toolName = pkgName, ttl = DEFAULT_TTL } = options;
+    const dirs = appstash(toolName);
+    const cacheFile = path.join(dirs.cache, 'update-check.json');
+    // Check cache first
+    try {
+        if (fs.existsSync(cacheFile)) {
+            const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+            if (Date.now() - cached.timestamp < ttl) {
+                return {
+                    hasUpdate: cached.latestVersion !== pkgVersion && cached.latestVersion > pkgVersion,
+                    currentVersion: pkgVersion,
+                    latestVersion: cached.latestVersion,
+                    message: cached.latestVersion > pkgVersion
+                        ? `Update available: ${pkgVersion} -> ${cached.latestVersion}`
+                        : null
+                };
+            }
+        }
+    }
+    catch {
+        // Cache read failed, continue to fetch
+    }
+    // Fetch latest version from registry
+    try {
+        const response = await fetch(`${registryBaseUrl}/${pkgName}/latest`);
+        if (!response.ok) {
+            return {
+                hasUpdate: false,
+                currentVersion: pkgVersion,
+                latestVersion: null,
+                message: null
+            };
+        }
+        const data = await response.json();
+        const latestVersion = data.version;
+        // Cache the result
+        try {
+            if (!fs.existsSync(dirs.cache)) {
+                fs.mkdirSync(dirs.cache, { recursive: true });
+            }
+            fs.writeFileSync(cacheFile, JSON.stringify({
+                latestVersion,
+                timestamp: Date.now()
+            }));
+        }
+        catch {
+            // Cache write failed, continue anyway
+        }
+        return {
+            hasUpdate: latestVersion !== pkgVersion && latestVersion > pkgVersion,
+            currentVersion: pkgVersion,
+            latestVersion,
+            message: latestVersion > pkgVersion
+                ? `Update available: ${pkgVersion} -> ${latestVersion}`
+                : null
+        };
+    }
+    catch {
+        return {
+            hasUpdate: false,
+            currentVersion: pkgVersion,
+            latestVersion: null,
+            message: null
+        };
+    }
+};

package/index.d.ts

@@ -0,0 +1,8 @@
+export { extractFirst } from './argv';
+export type { ParsedArgs } from './argv';
+export { cliExitWithError } from './cli-error';
+export type { CliExitOptions } from './cli-error';
+export { checkForUpdates } from './update-check';
+export type { UpdateCheckOptions, UpdateCheckResult } from './update-check';
+export { getSelfPackageJson, getSelfVersion, getSelfName } from './package-json';
+export type { PackageJsonInfo } from './package-json';

package/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSelfName = exports.getSelfVersion = exports.getSelfPackageJson = exports.checkForUpdates = exports.cliExitWithError = exports.extractFirst = void 0;
+// Argv utilities
+var argv_1 = require("./argv");
+Object.defineProperty(exports, "extractFirst", { enumerable: true, get: function () { return argv_1.extractFirst; } });
+// CLI error handling
+var cli_error_1 = require("./cli-error");
+Object.defineProperty(exports, "cliExitWithError", { enumerable: true, get: function () { return cli_error_1.cliExitWithError; } });
+// Update checking
+var update_check_1 = require("./update-check");
+Object.defineProperty(exports, "checkForUpdates", { enumerable: true, get: function () { return update_check_1.checkForUpdates; } });
+// Package.json utilities
+var package_json_1 = require("./package-json");
+Object.defineProperty(exports, "getSelfPackageJson", { enumerable: true, get: function () { return package_json_1.getSelfPackageJson; } });
+Object.defineProperty(exports, "getSelfVersion", { enumerable: true, get: function () { return package_json_1.getSelfVersion; } });
+Object.defineProperty(exports, "getSelfName", { enumerable: true, get: function () { return package_json_1.getSelfName; } });

package/package-json.d.ts

@@ -0,0 +1,18 @@
+export interface PackageJsonInfo {
+    name: string;
+    version: string;
+    [key: string]: any;
+}
+/**
+ * Gets the package.json for the current package by searching up from the given directory.
+ * This is useful for CLIs to get their own version information.
+ */
+export declare const getSelfPackageJson: (dirname: string) => PackageJsonInfo;
+/**
+ * Gets the version from the package.json for the current package.
+ */
+export declare const getSelfVersion: (dirname: string) => string;
+/**
+ * Gets the name from the package.json for the current package.
+ */
+export declare const getSelfName: (dirname: string) => string;

package/package-json.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSelfName = exports.getSelfVersion = exports.getSelfPackageJson = void 0;
+const find_and_require_package_json_1 = require("find-and-require-package-json");
+/**
+ * Gets the package.json for the current package by searching up from the given directory.
+ * This is useful for CLIs to get their own version information.
+ */
+const getSelfPackageJson = (dirname) => {
+    return (0, find_and_require_package_json_1.findAndRequirePackageJson)(dirname);
+};
+exports.getSelfPackageJson = getSelfPackageJson;
+/**
+ * Gets the version from the package.json for the current package.
+ */
+const getSelfVersion = (dirname) => {
+    return (0, exports.getSelfPackageJson)(dirname).version;
+};
+exports.getSelfVersion = getSelfVersion;
+/**
+ * Gets the name from the package.json for the current package.
+ */
+const getSelfName = (dirname) => {
+    return (0, exports.getSelfPackageJson)(dirname).name;
+};
+exports.getSelfName = getSelfName;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@genomic/utils",
+  "version": "2.0.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "CLI lifecycle utilities for building command-line applications",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/dev-utils",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/dev-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/dev-utils/issues"
+  },
+  "scripts": {
+    "copy": "makage assets",
+    "clean": "makage clean",
+    "prepublishOnly": "npm run build",
+    "build": "makage build",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "appstash": "0.2.6",
+    "find-and-require-package-json": "0.8.2",
+    "minimist": "^1.2.8"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5",
+    "makage": "0.1.8"
+  },
+  "keywords": [],
+  "gitHead": "59317e6ae9ba291aebdee3098e456d4ef4e1a5dc"
+}

package/update-check.d.ts

@@ -0,0 +1,18 @@
+export interface UpdateCheckOptions {
+    pkgName: string;
+    pkgVersion: string;
+    registryBaseUrl?: string;
+    toolName?: string;
+    ttl?: number;
+}
+export interface UpdateCheckResult {
+    hasUpdate: boolean;
+    currentVersion: string;
+    latestVersion: string | null;
+    message: string | null;
+}
+/**
+ * Checks for updates to a package and caches the result.
+ * Uses appstash for configuration storage.
+ */
+export declare const checkForUpdates: (options: UpdateCheckOptions) => Promise<UpdateCheckResult>;

package/update-check.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkForUpdates = void 0;
+const appstash_1 = require("appstash");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const DEFAULT_TTL = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/**
+ * Checks for updates to a package and caches the result.
+ * Uses appstash for configuration storage.
+ */
+const checkForUpdates = async (options) => {
+    const { pkgName, pkgVersion, registryBaseUrl = DEFAULT_REGISTRY, toolName = pkgName, ttl = DEFAULT_TTL } = options;
+    const dirs = (0, appstash_1.appstash)(toolName);
+    const cacheFile = path.join(dirs.cache, 'update-check.json');
+    // Check cache first
+    try {
+        if (fs.existsSync(cacheFile)) {
+            const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+            if (Date.now() - cached.timestamp < ttl) {
+                return {
+                    hasUpdate: cached.latestVersion !== pkgVersion && cached.latestVersion > pkgVersion,
+                    currentVersion: pkgVersion,
+                    latestVersion: cached.latestVersion,
+                    message: cached.latestVersion > pkgVersion
+                        ? `Update available: ${pkgVersion} -> ${cached.latestVersion}`
+                        : null
+                };
+            }
+        }
+    }
+    catch {
+        // Cache read failed, continue to fetch
+    }
+    // Fetch latest version from registry
+    try {
+        const response = await fetch(`${registryBaseUrl}/${pkgName}/latest`);
+        if (!response.ok) {
+            return {
+                hasUpdate: false,
+                currentVersion: pkgVersion,
+                latestVersion: null,
+                message: null
+            };
+        }
+        const data = await response.json();
+        const latestVersion = data.version;
+        // Cache the result
+        try {
+            if (!fs.existsSync(dirs.cache)) {
+                fs.mkdirSync(dirs.cache, { recursive: true });
+            }
+            fs.writeFileSync(cacheFile, JSON.stringify({
+                latestVersion,
+                timestamp: Date.now()
+            }));
+        }
+        catch {
+            // Cache write failed, continue anyway
+        }
+        return {
+            hasUpdate: latestVersion !== pkgVersion && latestVersion > pkgVersion,
+            currentVersion: pkgVersion,
+            latestVersion,
+            message: latestVersion > pkgVersion
+                ? `Update available: ${pkgVersion} -> ${latestVersion}`
+                : null
+        };
+    }
+    catch {
+        return {
+            hasUpdate: false,
+            currentVersion: pkgVersion,
+            latestVersion: null,
+            message: null
+        };
+    }
+};
+exports.checkForUpdates = checkForUpdates;