yargs-file-commands 0.0.14 → 0.0.17

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # yargs-file-commands
 
+## 0.0.17
+
+### Patch Changes
+
+- Throw if a command exports unrecognized names, catches a lot of bugs.
+- More explicit exceptions when bad parameters are passed in
+- Validate that provided command directories are aboslute
+- More robust parameter checking and logging
+- Improved debugging logging
+- added support for default commands and optional command names to support position arguments
+- More robust debug messages
+
+## 0.0.15
+
+### Patch Changes
+
+- Throw if a command exports unrecognized names, catches a lot of bugs.
+- More explicit exceptions when bad parameters are passed in
+- Validate that provided command directories are aboslute
+- More robust parameter checking and logging
+- Improved debugging logging
+- More robust debug messages
+
 ## 0.0.14
 
 ### Patch Changes

package/README.md

@@ -39,13 +39,14 @@ You can use any combination of file names and directories. We support either [Ne
 │   ├── migration
 │   │   └── command.ts // the "db migration" command
 │   └── health.ts      // the "db health" command
+├── $default.ts        // the default 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:
+Inside each route handler file, you define your command configuration. The command name defaults to the filename, but you can explicitly specify it using the `command` export to support positional arguments. Here are some examples:
 
 ```ts
-// commands/studio.start.ts
+// commands/studio.start.ts - Basic command using filename as command name
 
 import type { ArgumentsCamelCase, Argv } from 'yargs';
 import type { BaseOptions } from '../options.js';
@@ -54,6 +55,8 @@ export interface Options extends BaseOptions {
   port?: number;
 }
 
+export const command = 'start'; // this is optional, it will use the filename if this isn't specified
+
 export const describe = 'Studio web interface';
 
 export const builder = (args: Argv): Argv<Options> => {
@@ -71,6 +74,35 @@ export const handler = async (args: ArgumentsCamelCase<Options>) => {
 };
 ```
 
+```ts
+// Command with positional arguments
+
+export const command = 'create [name]';
+export const describe = 'Create a new migration';
+
+export const builder = (args: Argv): Argv<Options> => {
+  return args.positional('name', {
+    describe: 'Name of the migration',
+    type: 'string',
+    demandOption: true
+  });
+};
+
+export const handler = async (args: ArgumentsCamelCase<Options>) => {
+  // Implementation
+};
+```
+
+```ts
+// Must be named $default.ts - Default command (runs when no command is specified)
+
+export const describe = 'Default command';
+
+export const handler = async (args: ArgumentsCamelCase<Options>) => {
+  console.log('Running default command');
+};
+```
+
 The above will result in these commands being registered:
 
 ```

package/dist/lib/Command.d.ts

@@ -10,4 +10,6 @@ export interface Command {
     segments: string[];
     /** The Yargs command module implementation */
     commandModule: CommandModule;
+    /** Whether this is the default command */
+    isDefault?: boolean;
 }

package/dist/lib/buildSegmentTree.js

@@ -38,7 +38,7 @@ function insertIntoTree(treeNodes, command, depth) {
             });
         }
         else if (currentSegment.type === 'internal') {
-            throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command`);
+            throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command ${JSON.stringify(currentSegment)},${JSON.stringify(command)}`);
         }
         return;
     }
@@ -52,7 +52,7 @@ function insertIntoTree(treeNodes, command, depth) {
         treeNodes.push(currentSegment);
     }
     else if (currentSegment.type === 'leaf') {
-        throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command`);
+        throw new Error(`Conflict: ${currentSegmentName} is both a directory and a command ${JSON.stringify(currentSegment)}, ${JSON.stringify(command)}`);
     }
     // Recurse into children
     insertIntoTree(currentSegment.children, command, depth + 1);

package/dist/lib/fileCommands.test.js

@@ -1,43 +1,36 @@
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-import { fileURLToPath } from 'node:url';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { fileCommands } from '../lib/fileCommands.js';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-describe('fileCommands', async () => {
-    await it('should load commands from directory structure', async () => {
-        const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-        const commands = await fileCommands({
-            commandDirs: [commandsDir],
-            extensions: ['.js'],
-            logLevel: 'debug'
-        });
-        assert.equal(commands.length, 1, 'Should have one root command');
-        const rootCommand = commands[0];
-        assert(rootCommand, 'Root command should exist');
-        assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
-        // Create a new yargs instance
-        const yargsInstance = yargs(hideBin(process.argv));
-        if (typeof rootCommand.builder === 'function') {
-            rootCommand.builder(yargsInstance);
-        }
-        // Check that the command has subcommands by checking its description
-        const description = rootCommand.describe;
-        assert(typeof description === 'string' && description.includes('db'), 'Command should have correct description');
+import path from 'path';
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { fileCommands } from './fileCommands.js';
+// get __dirname in ESM style
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+test('should load commands from directory structure', async () => {
+    const commands = await fileCommands({
+        commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+        logLevel: 'debug'
     });
-    await it('should respect ignore patterns', async () => {
-        const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-        const commands = await fileCommands({
-            commandDirs: [commandsDir],
-            extensions: ['.js'],
-            ignorePatterns: [/health/],
-            logLevel: 'debug'
-        });
-        assert.equal(commands.length, 1, 'Should have one root command');
-        const rootCommand = commands[0];
-        assert(rootCommand, 'Root command should exist');
-        assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
+    assert.ok(commands.length > 0);
+});
+test('should respect ignore patterns', async () => {
+    const commands = await fileCommands({
+        commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+        ignorePatterns: [/health/, /.d.ts/],
+        logLevel: 'debug'
+    });
+    assert.ok(commands.length > 0);
+});
+test('should handle explicit commands and default command', async () => {
+    const commands = await fileCommands({
+        commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+        logLevel: 'debug'
     });
+    console.log('commands', JSON.stringify(commands.map((c) => c.command), null, 2));
+    // Find the explicit command
+    const explicitCommand = commands.find((cmd) => cmd.command?.toString().includes('create [name]'));
+    assert.ok(explicitCommand, 'Should find explicit command');
+    assert.equal(explicitCommand?.describe, 'Create something with a name');
+    // Find the default command
+    const defaultCommand = commands.find((cmd) => cmd.command === '$0');
+    assert.ok(defaultCommand, 'Should find default command');
+    assert.equal(defaultCommand?.describe, 'Default command');
 });

package/dist/lib/fixtures/commands/$default.d.ts

@@ -0,0 +1,2 @@
+export declare const describe = "Default command";
+export declare const handler: () => Promise<void>;

package/dist/lib/fixtures/commands/$default.js

@@ -0,0 +1,4 @@
+export const describe = 'Default command';
+export const handler = async () => {
+    // Default command implementation
+};

package/dist/lib/fixtures/commands/create.d.ts

@@ -0,0 +1,3 @@
+export declare const command = "create [name]";
+export declare const describe = "Create something with a name";
+export declare const handler: () => Promise<void>;

package/dist/lib/fixtures/commands/create.js

@@ -0,0 +1,5 @@
+export const command = 'create [name]';
+export const describe = 'Create something with a name';
+export const handler = async () => {
+    // Create command implementation
+};

package/dist/lib/importCommand.js

@@ -18,8 +18,10 @@ export const importCommandFromFile = async (filePath, name, options) => {
     }
     const handlerModule = (await import(filePath));
     const { logLevel = 'info' } = options;
+    // Check if this is the default command
+    const isDefault = name === '$default';
     const command = {
-        command: name,
+        command: handlerModule.command ?? (isDefault ? '$0' : name),
         describe: handlerModule.describe,
         alias: handlerModule.alias,
         builder: handlerModule.builder,
@@ -29,6 +31,19 @@ export const importCommandFromFile = async (filePath, name, options) => {
                 // null implementation
             })
     };
+    const supportedNames = [
+        'command',
+        'describe',
+        'alias',
+        'builder',
+        'deprecated',
+        'handler'
+    ];
+    const module = handlerModule;
+    const unsupportedExports = Object.keys(module).filter((key) => !supportedNames.includes(key));
+    if (unsupportedExports.length > 0) {
+        throw new Error(`Command module ${name} in ${filePath} has some unsupported exports, probably a misspelling: ${unsupportedExports.join(', ')}`);
+    }
     if (logLevel === 'debug') {
         console.debug('Importing command from', filePath, 'as', name, 'with description', command.describe);
     }

package/dist/lib/importCommand.test.js

@@ -1,21 +1,42 @@
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-import { fileURLToPath } from 'node:url';
-import { importCommandFromFile } from '../lib/importCommand.js';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-describe('importCommandFromFile', async () => {
-    await it('should import command module correctly', async () => {
-        const commandPath = path.join(__dirname, 'fixtures', 'commands', 'db', 'health.js');
-        const command = await importCommandFromFile(commandPath, 'health', {});
-        assert(command.describe, 'Should have describe property');
-        assert(typeof command.builder === 'function', 'Should have builder function');
-        assert(typeof command.handler === 'function', 'Should have handler function');
+import path from 'path';
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { importCommandFromFile } from './importCommand.js';
+// get __dirname in ESM style
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+test('should import command module correctly', async () => {
+    const filePath = path.join(__dirname, 'fixtures', 'commands', 'db', 'health.js');
+    const command = await importCommandFromFile(filePath, 'health', {
+        logLevel: 'info'
     });
-    await it('should handle non-existent files', async () => {
-        const nonExistentPath = path.join(__dirname, 'fixtures', 'commands', 'non-existent.ts');
-        await assert.rejects(async () => {
-            await importCommandFromFile(nonExistentPath, 'non-existent', {});
-        }, Error, 'Should throw error for non-existent file');
+    assert.equal(command.describe, 'Database health check');
+});
+test('should handle non-existent files', async () => {
+    const filePath = path.join(__dirname, 'fixtures', 'commands', 'non-existent.js');
+    try {
+        await importCommandFromFile(filePath, 'non-existent', {
+            logLevel: 'info'
+        });
+        assert.fail('Should have thrown an error');
+    }
+    catch (error) {
+        assert.ok(error instanceof Error);
+        assert.ok(error.message.includes('Can not import command from non-existence'));
+    }
+});
+test('should handle explicit command names', async () => {
+    const filePath = path.join(__dirname, 'fixtures', 'commands', 'create.js');
+    const command = await importCommandFromFile(filePath, 'create', {
+        logLevel: 'info'
+    });
+    assert.equal(command.command, 'create [name]');
+    assert.equal(command.describe, 'Create something with a name');
+});
+test('should handle default commands', async () => {
+    const filePath = path.join(__dirname, 'fixtures', 'commands', '$default.js');
+    const command = await importCommandFromFile(filePath, '$default', {
+        logLevel: 'info'
     });
+    assert.equal(command.command, '$0');
+    assert.equal(command.describe, 'Default command');
 });

package/dist/lib/scanDirectory.test.js

@@ -12,7 +12,7 @@ describe('scanDirectory', async () => {
             extensions: ['.js'],
             logLevel: 'debug'
         });
-        assert.equal(files.length, 2, `Should find two command files, instead found: ${files.join(', ')}`);
+        assert.equal(files.length, 4, `Should find two command files, instead found: ${files.join(', ')}`);
         assert(files.some((f) => f.includes('health.js')), `Should find health.js, instead found: ${files.join(', ')}`);
         assert(files.some((f) => f.includes('command.js')), `Should find command.js, instead found: ${files.join(', ')}`);
     });
@@ -21,10 +21,10 @@ describe('scanDirectory', async () => {
         console.log('Scan Directory: ', commandsDir);
         const files = await scanDirectory(commandsDir, commandsDir, {
             extensions: ['.js'],
-            ignorePatterns: [/health/],
+            ignorePatterns: [/health/, /.d.ts/],
             logLevel: 'debug'
         });
-        assert.equal(files.length, 1, `Should find one command file, instead found: ${files.join(', ')}`);
+        assert.equal(files.length, 3, `Should find one command file, instead found: ${files.join(', ')}`);
         assert(files.some((f) => f.includes('command.js')), `Should find command.js, instead found: ${files.join(', ')}`);
         assert(!files.some((f) => f.includes('health.js')), `Should not find health.js, instead found: ${files.join(', ')}`);
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.14",
+  "version": "0.0.17",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/lib/Command.ts

@@ -11,4 +11,6 @@ export interface Command {
   segments: string[];
   /** The Yargs command module implementation */
   commandModule: CommandModule;
+  /** Whether this is the default command */
+  isDefault?: boolean;
 }

package/src/lib/buildSegmentTree.ts

@@ -75,7 +75,9 @@ function insertIntoTree(
       });
     } else if (currentSegment.type === 'internal') {
       throw new Error(
-        `Conflict: ${currentSegmentName} is both a directory and a command`
+        `Conflict: ${currentSegmentName} is both a directory and a command ${JSON.stringify(
+          currentSegment
+        )},${JSON.stringify(command)}`
       );
     }
     return;
@@ -91,7 +93,9 @@ function insertIntoTree(
     treeNodes.push(currentSegment);
   } else if (currentSegment.type === 'leaf') {
     throw new Error(
-      `Conflict: ${currentSegmentName} is both a directory and a command`
+      `Conflict: ${currentSegmentName} is both a directory and a command ${JSON.stringify(
+        currentSegment
+      )}, ${JSON.stringify(command)}`
     );
   }
 

package/src/lib/fileCommands.test.ts

@@ -1,57 +1,55 @@
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-import { fileURLToPath } from 'node:url';
-
-import type { CommandModule } from 'yargs';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-
-import { fileCommands } from '../lib/fileCommands.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-describe('fileCommands', async () => {
-  await it('should load commands from directory structure', async () => {
-    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-    const commands = await fileCommands({
-      commandDirs: [commandsDir],
-      extensions: ['.js'],
-      logLevel: 'debug'
-    });
-
-    assert.equal(commands.length, 1, 'Should have one root command');
-    const rootCommand = commands[0] as CommandModule;
-    assert(rootCommand, 'Root command should exist');
-    assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
-
-    // Create a new yargs instance
-    const yargsInstance = yargs(hideBin(process.argv));
-
-    if (typeof rootCommand.builder === 'function') {
-      rootCommand.builder(yargsInstance);
-    }
-
-    // Check that the command has subcommands by checking its description
-    const description = rootCommand.describe;
-    assert(
-      typeof description === 'string' && description.includes('db'),
-      'Command should have correct description'
-    );
+import path from 'path';
+import { test } from 'node:test';
+import assert from 'node:assert';
+import type { Command } from './Command.js';
+
+import { fileCommands } from './fileCommands.js';
+
+// get __dirname in ESM style
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+test('should load commands from directory structure', async () => {
+  const commands = await fileCommands({
+    commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+    logLevel: 'debug'
+  });
+
+  assert.ok(commands.length > 0);
+});
+
+test('should respect ignore patterns', async () => {
+  const commands = await fileCommands({
+    commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+    ignorePatterns: [/health/, /.d.ts/],
+    logLevel: 'debug'
   });
 
-  await it('should respect ignore patterns', async () => {
-    const commandsDir = path.join(__dirname, 'fixtures', 'commands');
-    const commands = await fileCommands({
-      commandDirs: [commandsDir],
-      extensions: ['.js'],
-      ignorePatterns: [/health/],
-      logLevel: 'debug'
-    });
-
-    assert.equal(commands.length, 1, 'Should have one root command');
-    const rootCommand = commands[0] as CommandModule;
-    assert(rootCommand, 'Root command should exist');
-    assert.equal(rootCommand.command, 'db', 'Root command should be "db"');
+  assert.ok(commands.length > 0);
+});
+
+test('should handle explicit commands and default command', async () => {
+  const commands = await fileCommands({
+    commandDirs: [path.join(__dirname, 'fixtures', 'commands')],
+    logLevel: 'debug'
   });
+
+  console.log(
+    'commands',
+    JSON.stringify(
+      commands.map((c) => c.command),
+      null,
+      2
+    )
+  );
+  // Find the explicit command
+  const explicitCommand = commands.find((cmd) =>
+    cmd.command?.toString().includes('create [name]')
+  );
+  assert.ok(explicitCommand, 'Should find explicit command');
+  assert.equal(explicitCommand?.describe, 'Create something with a name');
+
+  // Find the default command
+  const defaultCommand = commands.find((cmd) => cmd.command === '$0');
+  assert.ok(defaultCommand, 'Should find default command');
+  assert.equal(defaultCommand?.describe, 'Default command');
 });

package/src/lib/fixtures/commands/$default.ts

@@ -0,0 +1,5 @@
+export const describe = 'Default command';
+
+export const handler = async () => {
+  // Default command implementation
+};

package/src/lib/fixtures/commands/create.ts

@@ -0,0 +1,6 @@
+export const command = 'create [name]';
+export const describe = 'Create something with a name';
+
+export const handler = async () => {
+  // Create command implementation
+};

package/src/lib/importCommand.test.ts

@@ -1,48 +1,65 @@
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-import { fileURLToPath } from 'node:url';
-
-import { importCommandFromFile } from '../lib/importCommand.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-describe('importCommandFromFile', async () => {
-  await it('should import command module correctly', async () => {
-    const commandPath = path.join(
-      __dirname,
-      'fixtures',
-      'commands',
-      'db',
-      'health.js'
-    );
-    const command = await importCommandFromFile(commandPath, 'health', {});
+import path from 'path';
+import { test } from 'node:test';
+import assert from 'node:assert';
 
-    assert(command.describe, 'Should have describe property');
-    assert(
-      typeof command.builder === 'function',
-      'Should have builder function'
-    );
-    assert(
-      typeof command.handler === 'function',
-      'Should have handler function'
-    );
+import { importCommandFromFile } from './importCommand.js';
+
+// get __dirname in ESM style
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+test('should import command module correctly', async () => {
+  const filePath = path.join(
+    __dirname,
+    'fixtures',
+    'commands',
+    'db',
+    'health.js'
+  );
+  const command = await importCommandFromFile(filePath, 'health', {
+    logLevel: 'info'
   });
 
-  await it('should handle non-existent files', async () => {
-    const nonExistentPath = path.join(
-      __dirname,
-      'fixtures',
-      'commands',
-      'non-existent.ts'
-    );
+  assert.equal(command.describe, 'Database health check');
+});
 
-    await assert.rejects(
-      async () => {
-        await importCommandFromFile(nonExistentPath, 'non-existent', {});
-      },
-      Error,
-      'Should throw error for non-existent file'
+test('should handle non-existent files', async () => {
+  const filePath = path.join(
+    __dirname,
+    'fixtures',
+    'commands',
+    'non-existent.js'
+  );
+  try {
+    await importCommandFromFile(filePath, 'non-existent', {
+      logLevel: 'info'
+    });
+    assert.fail('Should have thrown an error');
+  } catch (error) {
+    assert.ok(error instanceof Error);
+    assert.ok(
+      (error as Error).message.includes(
+        'Can not import command from non-existence'
+      )
     );
+  }
+});
+
+test('should handle explicit command names', async () => {
+  const filePath = path.join(__dirname, 'fixtures', 'commands', 'create.js');
+  const command = await importCommandFromFile(filePath, 'create', {
+    logLevel: 'info'
   });
+
+  assert.equal(command.command, 'create [name]');
+  assert.equal(command.describe, 'Create something with a name');
+});
+
+test('should handle default commands', async () => {
+  const filePath = path.join(__dirname, 'fixtures', 'commands', '$default.js');
+  const command = await importCommandFromFile(filePath, '$default', {
+    logLevel: 'info'
+  });
+
+  assert.equal(command.command, '$0');
+  assert.equal(command.describe, 'Default command');
 });

package/src/lib/importCommand.ts

@@ -95,8 +95,11 @@ export const importCommandFromFile = async (
   const handlerModule = (await import(filePath)) as CommandImportModule;
   const { logLevel = 'info' } = options;
 
+  // Check if this is the default command
+  const isDefault = name === '$default';
+  
   const command = {
-    command: name,
+    command: handlerModule.command ?? (isDefault ? '$0' : name),
     describe: handlerModule.describe,
     alias: handlerModule.alias,
     builder: handlerModule.builder,
@@ -108,6 +111,26 @@ export const importCommandFromFile = async (
       })
   } as CommandModule;
 
+  const supportedNames = [
+    'command',
+    'describe',
+    'alias',
+    'builder',
+    'deprecated',
+    'handler'
+  ];
+  const module = handlerModule as Record<string, any>;
+  const unsupportedExports = Object.keys(module).filter(
+    (key) => !supportedNames.includes(key)
+  );
+  if (unsupportedExports.length > 0) {
+    throw new Error(
+      `Command module ${name} in ${filePath} has some unsupported exports, probably a misspelling: ${unsupportedExports.join(
+        ', '
+      )}`
+    );
+  }
+
   if (logLevel === 'debug') {
     console.debug(
       'Importing command from',
@@ -118,5 +141,6 @@ export const importCommandFromFile = async (
       command.describe
     );
   }
+
   return command;
 };

package/src/lib/scanDirectory.test.ts

@@ -18,7 +18,7 @@ describe('scanDirectory', async () => {
 
     assert.equal(
       files.length,
-      2,
+      4,
       `Should find two command files, instead found: ${files.join(', ')}`
     );
     assert(
@@ -36,13 +36,13 @@ describe('scanDirectory', async () => {
     console.log('Scan Directory: ', commandsDir);
     const files = await scanDirectory(commandsDir, commandsDir, {
       extensions: ['.js'],
-      ignorePatterns: [/health/],
+      ignorePatterns: [/health/, /.d.ts/],
       logLevel: 'debug'
     });
 
     assert.equal(
       files.length,
-      1,
+      3,
       `Should find one command file, instead found: ${files.join(', ')}`
     );
     assert(