@komaci/cli 264.4.0 → 266.3.0

package/build/cmds/analyze/index.js

@@ -2,6 +2,13 @@ import { run } from './lib/run.js';
 export default {
     name: 'analyze',
     alias: 'a',
+    description: 'Run the Komaci static analyzer over one or more LWC bundle directories and print diagnostics. ' +
+        'Exits with code 1 if any diagnostics are reported.',
+    usage: 'yarn komaci analyze <paths...> [options]',
+    examples: [
+        'yarn komaci analyze sandbox/modules/c/komaciAction',
+        'yarn komaci analyze "sandbox/modules/*/*" --raw',
+    ],
     options: [
         {
             name: 'paths',
@@ -10,18 +17,21 @@ export default {
             type: String,
             required: true,
             defaultOption: true,
+            description: 'One or more LWC bundle directories. Glob patterns are supported.',
         },
         {
             name: 'bundleType',
             alias: 't',
             type: String,
             defaultValue: 'internal',
+            description: 'Bundle type passed to @lwc/metadata (e.g. "internal", "platform").',
         },
         {
             name: 'raw',
             alias: 'r',
             type: Boolean,
             defaultValue: false,
+            description: 'Print the raw diagnostic JSON instead of formatted, source-annotated output.',
         },
     ],
     run,

package/build/cmds/modgen/index.js

@@ -2,6 +2,17 @@ import { run } from './lib/run.js';
 export default {
     name: 'modgen',
     alias: 'm',
+    description: 'Generate a Komaci module (ADG) from one or more LWC bundle directories. ' +
+        'Each path must point to a component folder nested under a namespace folder ' +
+        '(e.g. ".../c/myComponent"); the namespace is derived from the parent directory.',
+    usage: 'yarn komaci modgen <paths...> [options]\n' +
+        '  Note: place <paths...> before --only/-o, since --only accepts multiple values\n' +
+        '  and will otherwise greedily consume the path as one of its values.',
+    examples: [
+        'yarn komaci modgen sandbox/modules/c/komaciAction',
+        'yarn komaci modgen sandbox/modules/c/komaciAction --only lwc',
+        'yarn komaci modgen sandbox/modules/lightning/*',
+    ],
     options: [
         {
             name: 'paths',
@@ -10,6 +21,7 @@ export default {
             type: String,
             required: true,
             defaultOption: true,
+            description: 'One or more LWC bundle directories. Glob patterns are supported.',
         },
         {
             name: 'only',
@@ -17,41 +29,48 @@ export default {
             type: String,
             multiple: true,
             defaultValue: ['mod', 'lwc', 'doc'],
+            description: 'Limit which sections to print: "mod" (Komaci module / ADG), "lwc" (LWC metadata), "doc" (Komaci document).',
         },
         {
             name: 'disableKomaci',
             alias: 'd',
             type: Boolean,
+            description: 'Disable Komaci processing during metadata collection.',
         },
         {
             name: 'bundleType',
             alias: 't',
             type: String,
             defaultValue: 'internal',
+            description: 'Bundle type passed to @lwc/metadata (e.g. "internal", "platform").',
         },
         {
             name: 'json',
             alias: 'j',
             type: Boolean,
             defaultValue: false,
+            description: 'Print metadata/doc sections as JSON instead of pretty-printed objects.',
         },
         {
             name: 'raw',
             alias: 'r',
             type: Boolean,
             defaultValue: false,
+            description: 'Suppress section headers in the output. Useful for piping to other tools.',
         },
         {
             name: 'withExceptions',
             alias: 'e',
             type: Boolean,
             defaultValue: false,
+            description: 'Run the alternate generation path that surfaces exceptions instead of producing error ADGs.',
         },
         {
             name: 'luvioMetadata',
             alias: 'l',
             type: Boolean,
             defaultValue: false,
+            description: 'Include Luvio GraphQL metadata in the generator input.',
         },
     ],
     run,

package/build/index.js

@@ -1,16 +1,48 @@
 import commandLineArgs from 'command-line-args';
 import { modgen, analyze } from './cmds/index.js';
 import { commander } from './lib/commander.js';
+import { findCommand, printCommandHelp, printTopLevelHelp } from './lib/help.js';
 import logger from './lib/log.js';
 const { error } = logger;
+const commands = [modgen, analyze];
+const rawArgs = process.argv.slice(2);
+const helpRequest = parseHelpRequest(rawArgs);
+if (helpRequest) {
+    if (helpRequest.commandName) {
+        const cmd = findCommand(commands, helpRequest.commandName);
+        if (cmd) {
+            printCommandHelp(cmd);
+            process.exit(0);
+        }
+        error(`No command "${helpRequest.commandName}" found`);
+        printTopLevelHelp(commands);
+        process.exit(1);
+    }
+    printTopLevelHelp(commands);
+    process.exit(0);
+}
 const optionDefinitions = [{ name: 'command', defaultOption: true }];
 const mainCommand = commandLineArgs(optionDefinitions, { stopAtFirstUnknown: true });
 const { command, _unknown: argv = [] } = mainCommand;
-if (!commander(command, argv, [modgen, analyze])) {
+if (!commander(command, argv, commands)) {
     error(`No command "${command}" found`);
+    printTopLevelHelp(commands);
     process.exit(1);
 }
 else {
     process.exit(0);
 }
+/**
+ * Detect any of: `help`, `help <cmd>`, `--help`, `--help <cmd>`, `-h`, `-h <cmd>`.
+ * Returns null when the user did not request help.
+ */
+function parseHelpRequest(argv) {
+    if (argv.length === 0)
+        return null;
+    const [first, second] = argv;
+    if (first === 'help' || first === '--help' || first === '-h') {
+        return { commandName: second };
+    }
+    return null;
+}
 //# sourceMappingURL=index.js.map

package/build/lib/help.d.ts

@@ -0,0 +1,8 @@
+import type { CommandLineOptions } from 'command-line-args';
+import type { Command } from '../types.js';
+declare type AnyCommand = Command<CommandLineOptions>;
+export declare function printTopLevelHelp(commands: AnyCommand[]): void;
+export declare function printCommandHelp(cmd: AnyCommand): void;
+export declare function findCommand(commands: AnyCommand[], target: string): AnyCommand | undefined;
+export {};
+//# sourceMappingURL=help.d.ts.map

package/build/lib/help.js

@@ -0,0 +1,77 @@
+import chalk from 'chalk';
+import logger from './log.js';
+const { bold, cyan, dim } = chalk;
+const { log } = logger;
+export function printTopLevelHelp(commands) {
+    const lines = [];
+    lines.push(bold('komaci') + ' — CLI utility for the Komaci ESM generator and static analyzer.');
+    lines.push('');
+    lines.push(bold('Usage:'));
+    lines.push('  yarn komaci <command> [options]');
+    lines.push('  yarn komaci help [command]');
+    lines.push('');
+    lines.push(bold('Commands:'));
+    const nameWidth = Math.max(...commands.map((c) => formatCommandLabel(c).length));
+    for (const cmd of commands) {
+        const label = formatCommandLabel(cmd).padEnd(nameWidth);
+        const desc = cmd.description ?? '';
+        lines.push(`  ${cyan(label)}  ${desc}`);
+    }
+    lines.push('');
+    lines.push(`Run ${cyan('yarn komaci help <command>')} for detailed usage of a specific command.`);
+    log(lines.join('\n'));
+}
+export function printCommandHelp(cmd) {
+    const lines = [];
+    lines.push(bold(`komaci ${cmd.name}`) + (cmd.alias ? dim(` (alias: ${cmd.alias})`) : ''));
+    if (cmd.description) {
+        lines.push('');
+        lines.push(cmd.description);
+    }
+    lines.push('');
+    lines.push(bold('Usage:'));
+    lines.push(`  ${cmd.usage ?? `yarn komaci ${cmd.name} [options] <paths...>`}`);
+    if (cmd.options.length > 0) {
+        lines.push('');
+        lines.push(bold('Options:'));
+        const rows = cmd.options.map((opt) => [formatOptionLabel(opt), formatOptionDescription(opt)]);
+        const labelWidth = Math.max(...rows.map(([label]) => label.length));
+        for (const [label, desc] of rows) {
+            lines.push(`  ${cyan(label.padEnd(labelWidth))}  ${desc}`);
+        }
+    }
+    if (cmd.examples && cmd.examples.length > 0) {
+        lines.push('');
+        lines.push(bold('Examples:'));
+        for (const example of cmd.examples) {
+            lines.push(`  ${example}`);
+        }
+    }
+    log(lines.join('\n'));
+}
+function formatCommandLabel(cmd) {
+    return cmd.alias ? `${cmd.name}, ${cmd.alias}` : cmd.name;
+}
+function formatOptionLabel(opt) {
+    const flag = opt.alias ? `-${opt.alias}, --${opt.name}` : `    --${opt.name}`;
+    const valueHint = opt.type === Boolean ? '' : opt.multiple ? ' <values...>' : ' <value>';
+    return `${flag}${valueHint}`;
+}
+function formatOptionDescription(opt) {
+    const parts = [];
+    if (opt.description)
+        parts.push(opt.description);
+    if (opt.defaultOption)
+        parts.push(dim('(default positional argument)'));
+    if (opt.defaultValue !== undefined) {
+        const formatted = Array.isArray(opt.defaultValue)
+            ? `[${opt.defaultValue.join(', ')}]`
+            : String(opt.defaultValue);
+        parts.push(dim(`(default: ${formatted})`));
+    }
+    return parts.join(' ');
+}
+export function findCommand(commands, target) {
+    return commands.find(({ name, alias }) => target === name || target === alias);
+}
+//# sourceMappingURL=help.js.map

package/build/types.d.ts

@@ -1,8 +1,14 @@
 import type { CommandLineOptions, OptionDefinition } from 'command-line-args';
+export declare type CommandOptionDefinition = OptionDefinition & {
+    description?: string;
+};
 export declare type Command<T extends CommandLineOptions> = {
     name: string;
     alias?: string;
+    description?: string;
+    usage?: string;
+    examples?: string[];
     run: (cmdOptions: T) => void;
-    options: OptionDefinition[];
+    options: CommandOptionDefinition[];
 };
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@komaci/cli",
-    "version": "264.4.0",
+    "version": "266.3.0",
     "description": "CLI utility that enables developers to use komaci from the command line.",
     "license": "MIT",
     "type": "module",