yargs-file-commands 0.0.1

package/LICENSE

@@ -0,0 +1,9 @@
+# MIT LICENSE
+
+Copyright 2024, Ben Houston
+
+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,142 @@
+# Yargs File Commands
+
+[![NPM Package][npm]][npm-url]
+[![Build Size][build-size]][build-size-url]
+[![NPM Downloads][npm-downloads]][npmtrends-url]
+
+This Yargs helper function lets you define all your commands as individual files and their file names and directory structure defines via implication your nested command structure.
+
+Supports both JavaScript and TypeScript (on Node 22+.)
+
+## Installation
+
+_NOTE: This is an ESM-only package._
+
+```sh
+npm install yargs-file-commands
+```
+
+## Example
+
+```ts
+import { createRequire } from 'module';
+import path from 'path';
+import yargs from 'yargs';
+import { fileCommands } from 'yargs-file-commands';
+
+const require = createRequire(import.meta.url);
+
+export const main = async () => {
+  const rootCommandDir = path.join(
+    import.meta.url.replace('file://', ''),
+    '../commands'
+  );
+
+  return yargs(process.argv)
+    .command(await fileCommands({ rootDirs: [rootCommandDir] }))
+    .help().argv;
+};
+```
+
+You can use any combination of file names and directories. We support either [NextJS](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) or [Remix](https://remix.run/docs/en/main/file-conventions/routes) conventions for interpreting filenames and directories.
+
+```
+/commands
+├── db
+│   ├── migration
+│   │   └── command.ts // the "db migration" command
+│   └── health.ts      // the "db health" command
+└── studio.start.ts    // the "studio start" command
+```
+
+Inside each route handler file, you make the default export the route handler. Here is a simple example:
+
+```ts
+// commands/studio.start.ts
+
+import type { ArgumentsCamelCase, Argv } from 'yargs';
+import type { BaseOptions } from '../options.js';
+
+export interface Options extends BaseOptions {
+  port?: number;
+}
+
+export const describe = 'Studio web interface';
+
+export const builder = (args: Argv): Argv<Options> => {
+  const result = args.option('port', {
+    alias: 'p',
+    type: 'number',
+    describe: 'Port to listen on'
+  });
+  return result;
+};
+
+export const handler = async (args: ArgumentsCamelCase<Options>) => {
+  const config = await getConfig();
+  // Implementation
+};
+```
+
+The above will result in these commands being registered:
+
+```
+db migration
+db health
+studio start
+```
+
+## Options
+
+The "fileCommands" method takes the following options:
+
+**routesDirs**
+
+- An array of directories where the routes are located relative to the build root folder.
+- Required
+
+**extensions**
+
+- An array of file extensions for the route files. Files without matching extensions are ignored
+- Default: `[".js", ".ts"]`
+
+** ignorePatterns?: RegExp[];
+**
+
+- An array of regexs which if matched against a filename or directory, lead it to being ignored/skipped over.
+- Default: `[ /^[\.|_].*/, /\.(test|spec)\.[jt]s$/, /__(test|spec)__/, /\.d\.ts$/ ]`
+
+**logLevel**
+
+- The verbosity level for the plugin, either `debug` or `info`
+- Default: `"info"`
+
+## Plugin Development (for Contributors only)
+
+If you want to contribute, just check out [this git project](https://github.com/bhouston/yargs-file-commands) and run the following commands to get going:
+
+```sh
+# install dependencies
+npm install
+
+# build everything
+npm run build
+
+# prettify
+npm run format
+
+# eslint
+npm run lint
+
+# build and run tests
+npm run test
+
+# clean everything, should be like doing a fresh git checkout of the repo.
+npm run clean
+
+# publish the npm package
+npm run publish
+
+# run example cli
+npx example-cli
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/fileCommands.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './lib/fileCommands.js';

package/dist/lib/Command.d.ts

@@ -0,0 +1,6 @@
+import type { CommandModule } from 'yargs';
+export interface Command {
+    fullPath: string;
+    segments: string[];
+    commandModule: CommandModule;
+}

package/dist/lib/Command.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/buildSegmentTree.d.ts

@@ -0,0 +1,14 @@
+import type { CommandModule } from 'yargs';
+import type { Command } from './Command';
+type CommandTreeNode = {
+    segmentName: string;
+} & ({
+    type: 'internal';
+    children: CommandTreeNode[];
+} | {
+    type: 'leaf';
+    command: Command;
+});
+export declare const buildSegmentTree: (commands: Command[]) => CommandTreeNode[];
+export declare const createCommand: (treeNode: CommandTreeNode) => CommandModule;
+export {};

package/dist/lib/buildSegmentTree.js

@@ -0,0 +1,65 @@
+export const buildSegmentTree = (commands) => {
+    const rootTreeNodes = [];
+    for (const command of commands) {
+        insertIntoTree(rootTreeNodes, command, 0);
+    }
+    return rootTreeNodes;
+};
+function insertIntoTree(treeNodes, command, depth) {
+    // If we've processed all segments, we shouldn't be here
+    if (depth >= command.segments.length) {
+        return;
+    }
+    const currentSegmentName = command.segments[depth];
+    let currentSegment = treeNodes.find((s) => s.segmentName === currentSegmentName);
+    // If this is the last segment, create a leaf node
+    if (depth === command.segments.length - 1) {
+        if (currentSegment == null) {
+            treeNodes.push({
+                type: 'leaf',
+                segmentName: currentSegmentName,
+                command
+            });
+        }
+        else if (currentSegment.type === 'internal') {
+            throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command`);
+        }
+        return;
+    }
+    // Creating or ensuring we have an internal node
+    if (currentSegment == null) {
+        currentSegment = {
+            type: 'internal',
+            segmentName: currentSegmentName,
+            children: []
+        };
+        treeNodes.push(currentSegment);
+    }
+    else if (currentSegment.type === 'leaf') {
+        throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command`);
+    }
+    // Recurse into children
+    insertIntoTree(currentSegment.children, command, depth + 1);
+}
+export const createCommand = (treeNode) => {
+    if (treeNode.type === 'leaf') {
+        return treeNode.command.commandModule;
+    }
+    const name = treeNode.segmentName;
+    // For internal nodes, create a command that registers all children
+    const command = {
+        command: name,
+        describe: `${name} commands`,
+        builder: (yargs) => {
+            // Register all child segments as subcommands
+            yargs.command(treeNode.children.map((child) => createCommand(child)));
+            // Demand a subcommand unless we're at the root
+            yargs.demandCommand(1, `You must specify a ${name} subcommand`);
+            return yargs;
+        },
+        handler: async () => {
+            // Internal nodes don't need handlers as they'll demand subcommands
+        }
+    };
+    return command;
+};

package/dist/lib/fileCommands.d.ts

@@ -0,0 +1,8 @@
+export type FileCommandsOptions = {
+    rootDirs: string[];
+    extensions?: string[];
+    ignorePatterns?: RegExp[];
+    logLevel?: 'info' | 'debug';
+};
+export declare const DefaultFileCommandsOptions: Partial<FileCommandsOptions>;
+export declare const fileCommands: (options: FileCommandsOptions) => Promise<import("yargs").CommandModule<{}, {}>[]>;

package/dist/lib/fileCommands.js

@@ -0,0 +1,33 @@
+import { buildSegmentTree, createCommand } from './buildSegmentTree.js';
+import { importCommandFromFile } from './importCommand.js';
+import { scanDirectory } from './scanDirectory.js';
+import { segmentPath } from './segmentPath.js';
+export const DefaultFileCommandsOptions = {
+    extensions: ['.js', '.ts'],
+    ignorePatterns: [
+        /^[\.|_].*/,
+        /\.(test|spec)\.[jt]s$/,
+        /__(test|spec)__/,
+        /\.d\.ts$/
+    ],
+    logLevel: 'info'
+};
+export const fileCommands = async (options) => {
+    const fullOptions = { ...DefaultFileCommandsOptions, ...options };
+    const commands = [];
+    await Promise.all(options.rootDirs.map(async (rootCommandDir) => {
+        const filePaths = await scanDirectory(rootCommandDir, fullOptions);
+        const rootDirCommands = await Promise.all(filePaths.map(async (filePath) => {
+            const segments = segmentPath(filePath, rootCommandDir);
+            return {
+                fullPath: filePath,
+                segments: segmentPath(filePath, rootCommandDir),
+                commandModule: await importCommandFromFile(filePath, segments[segments.length - 1])
+            };
+        }));
+        commands.push(...rootDirCommands);
+    }));
+    const commandRootNodes = buildSegmentTree(commands);
+    const rootCommands = commandRootNodes.map((node) => createCommand(node));
+    return rootCommands;
+};

package/dist/lib/importCommand.d.ts

@@ -0,0 +1,18 @@
+import { type ArgumentsCamelCase, type CommandBuilder, type CommandModule } from 'yargs';
+export type CommandAlias = readonly string[] | string | undefined;
+export type CommandName = readonly string[] | string | undefined;
+export type CommandDeprecated = boolean | string | undefined;
+export type CommandDescribe = string | false | undefined;
+export type CommandHandler = (args: ArgumentsCamelCase<any>) => void | Promise<any>;
+export interface FileCommandsParams {
+    rootDir: string;
+}
+export interface CommandImportModule {
+    alias?: CommandAlias;
+    builder?: CommandBuilder;
+    command?: CommandName;
+    deprecated?: CommandDeprecated;
+    describe?: CommandDescribe;
+    handler?: CommandHandler;
+}
+export declare const importCommandFromFile: (filePath: string, name: string) => Promise<CommandModule<{}, {}>>;

package/dist/lib/importCommand.js

@@ -0,0 +1,15 @@
+import {} from 'yargs';
+export const importCommandFromFile = async (filePath, name) => {
+    const handlerModule = (await import(filePath));
+    return {
+        command: name,
+        describe: handlerModule.describe,
+        alias: handlerModule.alias,
+        builder: handlerModule.builder,
+        deprecated: handlerModule.deprecated,
+        handler: handlerModule.handler ??
+            (async (args) => {
+                // null implementation
+            })
+    };
+};

package/dist/lib/scanDirectory.d.ts

@@ -0,0 +1,4 @@
+export interface ScanDirectoryOptions {
+    ignorePatterns?: RegExp[];
+}
+export declare const scanDirectory: (dirPath: string, options?: ScanDirectoryOptions) => Promise<string[]>;

package/dist/lib/scanDirectory.js

@@ -0,0 +1,31 @@
+import { readdir, stat } from 'fs/promises';
+import { join } from 'path';
+export const scanDirectory = async (dirPath, options = {}) => {
+    const { ignorePatterns = [] } = options;
+    // Check if path should be ignored
+    const shouldIgnore = ignorePatterns.some((pattern) => pattern.test(dirPath));
+    if (shouldIgnore) {
+        return [];
+    }
+    try {
+        const entries = await readdir(dirPath);
+        const nestedFilesPromises = entries.map(async (entry) => {
+            // apply ignore pattern and early return if matched
+            const shouldIgnore = ignorePatterns.some((pattern) => pattern.test(entry));
+            if (shouldIgnore) {
+                return [];
+            }
+            const fullPath = join(dirPath, entry);
+            const stats = await stat(fullPath);
+            if (stats.isDirectory()) {
+                return scanDirectory(fullPath, options);
+            }
+            return [fullPath];
+        });
+        const nestedFiles = await Promise.all(nestedFilesPromises);
+        return nestedFiles.flat();
+    }
+    catch (error) {
+        throw new Error(`Failed to scan directory ${dirPath}: ${error}`);
+    }
+};

package/dist/lib/segmentPath.d.ts

@@ -0,0 +1 @@
+export declare const segmentPath: (fullPath: string, baseDir: string) => string[];

package/dist/lib/segmentPath.js

@@ -0,0 +1,15 @@
+export const segmentPath = (fullPath, baseDir) => {
+    // Remove base directory and normalize slashes
+    const relativePath = fullPath.replace(baseDir, '').replace(/^[/\\]+/, '');
+    // Split into path segments and filename
+    const allSegments = relativePath.split(/[/\\]/);
+    // Process all segments including filename (without extension)
+    const processedSegments = allSegments
+        // Remove extension from the last segment (filename)
+        .map((segment, index, array) => index === array.length - 1 ? segment.replace(/\.[^/.]+$/, '') : segment)
+        // Split segments containing periods
+        .flatMap((segment) => segment.split('.'))
+        // Filter out empty segments and 'command'
+        .filter((segment) => segment !== '' && segment !== 'command');
+    return processedSegments;
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "yargs-file-commands",
+  "description": "A yargs helper function that lets you define your commands structure via directory and file naming conventions.",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "source": "./src/index.ts",
+  "license": "MIT",
+  "author": "Ben Houston <neuralsoft@gmail.com> (https://benhouston3d.com)",
+  "keywords": [
+    "yargs",
+    "file-router",
+    "files",
+    "directory",
+    "automatic",
+    "commandDir",
+    "helper",
+    "nodejs",
+    "typescript"
+  ],
+  "homepage": "https://github.com/bhouston/yargs-file-commands#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/yargs-file-commands"
+  },
+  "bugs": {
+    "url": "https://github.com/bhouston/yargs-file-commands/issues"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "yargs": "^17"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/yargs": "^17.0.33"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}