ts-repo-utils 5.3.0 → 6.0.0

package/dist/functions/should-run.d.mts

@@ -1,20 +1,60 @@
 import '../node-global.mjs';
 /**
- * Checks if TypeScript type checks should run based on the diff from
- * origin/main. Skips type checks if all changed files are documentation files,
- * spell check config, or other non-TypeScript files that don't affect type
- * checking.
+ * Checks if TypeScript type checks should run based on the diff from a base
+ * branch. Skips type checks if all changed files match the ignored patterns.
  *
- * Ignored file patterns:
+ * This function is typically used in CI/CD pipelines to determine whether
+ * expensive type checking operations should be performed. If all changed files
+ * are documentation, configuration, or other non-TypeScript files, type checks
+ * can be safely skipped to improve build performance.
  *
- * - '.cspell.json'
- * - '**.md'
- * - '**.txt'
- * - 'docs/**'
+ * @example
+ *   ```typescript
+ *   // Use default settings (compare against origin/main, ignore docs/md/txt files)
+ *   await checkShouldRunTypeChecks();
  *
- * @returns A promise that resolves when the check is complete. Sets
- *   GITHUB_OUTPUT environment variable with should_run=true/false if running in
- *   GitHub Actions.
+ *   // Custom ignore patterns
+ *   await checkShouldRunTypeChecks({
+ *     pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],
+ *   });
+ *
+ *   // Custom base branch
+ *   await checkShouldRunTypeChecks({
+ *     baseBranch: 'origin/develop',
+ *   });
+ *   ```;
+ *
+ * @example
+ *   GitHub Actions usage
+ *   ```yaml
+ *   - name: Check if type checks should run
+ *   id: check_diff
+ *   run: npx check-should-run-type-checks
+ *
+ *   - name: Run type checks
+ *   if: steps.check_diff.outputs.should_run == 'true'
+ *   run: npm run type-check
+ *   ```
+ *
+ * @param options - Configuration options
+ * @param options.pathsIgnore - Array of patterns to ignore when determining if
+ *   type checks should run. Supports three pattern types:
+ *
+ *   - **Exact file matches**: e.g., `.cspell.json` matches only that file
+ *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory
+ *   - **File extensions**: e.g., `**.md` matches any markdown file Defaults to:
+ *       `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json',
+ *       '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore',
+ *       '.prettierrc', 'docs/', '**.md', '**.txt']`
+ *
+ * @param options.baseBranch - Base branch to compare against for determining
+ *   changed files. Defaults to `'origin/main'`
+ * @returns A promise that resolves when the check is complete. The function
+ *   will set the GITHUB_OUTPUT environment variable with `should_run=true` or
+ *   `should_run=false` if running in GitHub Actions environment.
  */
-export declare const checkShouldRunTypeChecks: () => Promise<void>;
+export declare const checkShouldRunTypeChecks: (options?: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+}>) => Promise<void>;
 //# sourceMappingURL=should-run.d.mts.map

package/dist/functions/should-run.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CA4B7D,CAAC"}
+{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,IAAI,CAmDd,CAAC"}

package/dist/functions/should-run.mjs

@@ -1,39 +1,98 @@
-import { Result, pipe } from 'ts-data-forge';
+import { Result } from 'ts-data-forge';
 import '../node-global.mjs';
 import { getDiffFrom } from './diff.mjs';
 
 /**
- * Checks if TypeScript type checks should run based on the diff from
- * origin/main. Skips type checks if all changed files are documentation files,
- * spell check config, or other non-TypeScript files that don't affect type
- * checking.
+ * Checks if TypeScript type checks should run based on the diff from a base
+ * branch. Skips type checks if all changed files match the ignored patterns.
  *
- * Ignored file patterns:
+ * This function is typically used in CI/CD pipelines to determine whether
+ * expensive type checking operations should be performed. If all changed files
+ * are documentation, configuration, or other non-TypeScript files, type checks
+ * can be safely skipped to improve build performance.
  *
- * - '.cspell.json'
- * - '**.md'
- * - '**.txt'
- * - 'docs/**'
+ * @example
+ *   ```typescript
+ *   // Use default settings (compare against origin/main, ignore docs/md/txt files)
+ *   await checkShouldRunTypeChecks();
  *
- * @returns A promise that resolves when the check is complete. Sets
- *   GITHUB_OUTPUT environment variable with should_run=true/false if running in
- *   GitHub Actions.
+ *   // Custom ignore patterns
+ *   await checkShouldRunTypeChecks({
+ *     pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],
+ *   });
+ *
+ *   // Custom base branch
+ *   await checkShouldRunTypeChecks({
+ *     baseBranch: 'origin/develop',
+ *   });
+ *   ```;
+ *
+ * @example
+ *   GitHub Actions usage
+ *   ```yaml
+ *   - name: Check if type checks should run
+ *   id: check_diff
+ *   run: npx check-should-run-type-checks
+ *
+ *   - name: Run type checks
+ *   if: steps.check_diff.outputs.should_run == 'true'
+ *   run: npm run type-check
+ *   ```
+ *
+ * @param options - Configuration options
+ * @param options.pathsIgnore - Array of patterns to ignore when determining if
+ *   type checks should run. Supports three pattern types:
+ *
+ *   - **Exact file matches**: e.g., `.cspell.json` matches only that file
+ *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory
+ *   - **File extensions**: e.g., `**.md` matches any markdown file Defaults to:
+ *       `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json',
+ *       '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore',
+ *       '.prettierrc', 'docs/', '**.md', '**.txt']`
+ *
+ * @param options.baseBranch - Base branch to compare against for determining
+ *   changed files. Defaults to `'origin/main'`
+ * @returns A promise that resolves when the check is complete. The function
+ *   will set the GITHUB_OUTPUT environment variable with `should_run=true` or
+ *   `should_run=false` if running in GitHub Actions environment.
  */
-const checkShouldRunTypeChecks = async () => {
-    // paths-ignore:
-    //   - '.cspell.json'
-    //   - '**.md'
-    //   - '**.txt'
-    //   - 'docs/**'
+const checkShouldRunTypeChecks = async (options) => {
+    const pathsIgnore = options?.pathsIgnore ?? [
+        'LICENSE',
+        '.editorconfig',
+        '.gitignore',
+        '.cspell.json',
+        '.markdownlint-cli2.mjs',
+        '.npmignore',
+        '.prettierignore',
+        '.prettierrc',
+        'docs/',
+        '**.md',
+        '**.txt',
+    ];
+    const baseBranch = options?.baseBranch ?? 'origin/main';
     const GITHUB_OUTPUT = process.env['GITHUB_OUTPUT'];
-    const files = await getDiffFrom('origin/main');
+    const files = await getDiffFrom(baseBranch);
     if (Result.isErr(files)) {
         console.error('Error getting diff:', files.value);
         process.exit(1);
     }
-    const shouldRunTsChecks = !files.value.every((file) => file === '.cspell.json' ||
-        file.startsWith('docs/') ||
-        pipe(path.basename(file)).map((filename) => filename.endsWith('.md') || filename.endsWith('.txt')).value);
+    const shouldRunTsChecks = !files.value.every((file) => pathsIgnore.some((pattern) => {
+        // Exact file match
+        if (pattern === file) {
+            return true;
+        }
+        // Directory prefix match (pattern ends with '/')
+        if (pattern.endsWith('/') && file.startsWith(pattern)) {
+            return true;
+        }
+        // File extension pattern match (pattern starts with '**.')
+        if (pattern.startsWith('**.')) {
+            const extension = pattern.slice(2); // Remove '**'
+            return path.basename(file).endsWith(extension);
+        }
+        return false;
+    }));
     if (GITHUB_OUTPUT !== undefined) {
         await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}\n`);
     }

package/dist/functions/should-run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,wBAAwB,GAAG,YAA0B;;;;;;IAOhE,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,aAAa,CAAC;AAE9C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACjB;AAEA,IAAA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CACnD,CAAC,IAAI,KACH,IAAI,KAAK,cAAc;AACvB,QAAA,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;AACxB,QAAA,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAC3B,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CACpE,CAAC,KAAK,CACV;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;IACzE;AACF;;;;"}
+{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDG;MACU,wBAAwB,GAAG,OACtC,OAGE,KACe;AACjB,IAAA,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI;QAC1C,SAAS;QACT,eAAe;QACf,YAAY;QACZ,cAAc;QACd,wBAAwB;QACxB,YAAY;QACZ,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,QAAQ;KACT;AAED,IAAA,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,aAAa;IAEvD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC;AAE3C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACjB;IAEA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,KACzD,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,KAAI;;AAE3B,QAAA,IAAI,OAAO,KAAK,IAAI,EAAE;AACpB,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;AACrD,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;YAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAChD;AAEA,QAAA,OAAO,KAAK;IACd,CAAC,CAAC,CACH;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;IACzE;AACF;;;;"}

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAEA,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "5.3.0",
+  "version": "6.0.0",
   "private": false,
   "keywords": [
     "typescript"
@@ -23,6 +23,13 @@
   },
   "module": "./dist/index.mjs",
   "types": "./dist/type.d.mts",
+  "bin": {
+    "assert-repo-is-clean": "./src/cmd/assert-repo-is-clean.mts",
+    "check-should-run-type-checks": "./src/cmd/check-should-run-type-checks.mts",
+    "format-diff-from": "./src/cmd/format-diff-from.mts",
+    "format-untracked": "./src/cmd/format-untracked.mts",
+    "gen-index-ts": "./src/cmd/gen-index-ts.mts"
+  },
   "files": [
     "src",
     "dist",
@@ -35,12 +42,14 @@
     "check:ext": "tsx ./scripts/cmd/check-ext.mjs",
     "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
     "doc": "tsx ./scripts/cmd/gen-docs.mjs",
-    "fmt": "tsx ./scripts/cmd/fmt-diff.mjs",
+    "fmt": "npm exec -- format-diff-from origin/main",
     "fmt:full": "prettier --write .",
-    "gi": "tsx ./scripts/cmd/gi.mjs",
+    "gi": "npm exec -- gen-index-ts ./src/functions --index-ext .mts --export-ext .mjs --target-ext .mts --target-ext .tsx --fmt 'npm run fmt'",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "md": "markdownlint-cli2",
+    "prepare-release": "run-s sync-cli-versions fmt build doc",
+    "sync-cli-versions": "tsx scripts/cmd/sync-cli-versions.mts",
     "test": "npm run z:vitest -- run",
     "test:cov": "npm run z:vitest -- run --coverage",
     "test:cov:ui": "vite preview --outDir ./coverage",
@@ -54,10 +63,12 @@
   },
   "dependencies": {
     "@types/micromatch": "^4.0.9",
+    "cmd-ts": "^0.13.0",
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
     "prettier": "^3.6.2",
-    "ts-data-forge": "^3.0.5"
+    "ts-data-forge": "^3.0.5",
+    "tsx": "^4.20.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.31.0",
@@ -88,6 +99,7 @@
     "eslint-plugin-unicorn": "60.0.0",
     "eslint-plugin-vitest": "0.5.4",
     "markdownlint-cli2": "^0.18.1",
+    "npm-run-all2": "^8.0.4",
     "prettier-plugin-jsdoc": "^1.3.3",
     "prettier-plugin-organize-imports": "^4.2.0",
     "prettier-plugin-packagejson": "^2.5.19",
@@ -95,7 +107,6 @@
     "semantic-release": "^24.2.7",
     "ts-type-forge": "^2.1.1",
     "tslib": "^2.8.1",
-    "tsx": "^4.20.3",
     "typedoc": "^0.28.7",
     "typedoc-plugin-markdown": "^4.8.0",
     "typescript": "^5.8.3",

package/src/cmd/assert-repo-is-clean.mts

@@ -0,0 +1,28 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+import { assertRepoIsClean } from '../functions/index.mjs';
+
+const cmdDef = cmd.command({
+  name: 'assert-repo-is-clean-cli',
+  version: '6.0.0',
+  args: {
+    silent: cmd.flag({
+      long: 'silent',
+      type: cmd.optional(cmd.boolean),
+      description: 'If true, suppresses output messages (default: false)',
+    }),
+  },
+  handler: (args) => {
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async (args: Readonly<{ silent?: boolean }>): Promise<void> => {
+  await assertRepoIsClean({ silent: args.silent });
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));

package/src/cmd/check-should-run-type-checks.mts

@@ -0,0 +1,43 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+import { checkShouldRunTypeChecks } from '../functions/index.mjs';
+
+const cmdDef = cmd.command({
+  name: 'check-should-run-type-checks-cli',
+  version: '6.0.0',
+  args: {
+    pathsIgnore: cmd.multioption({
+      long: 'paths-ignore',
+      type: cmd.optional(cmd.array(cmd.string)),
+      description:
+        'Patterns to ignore when checking if type checks should run. Supports exact file matches, directory prefixes (ending with "/"), and file extensions (starting with "**.")',
+    }),
+    baseBranch: cmd.option({
+      long: 'base-branch',
+      type: cmd.optional(cmd.string),
+      description:
+        'Base branch to compare against for determining changed files. Defaults to "origin/main"',
+    }),
+  },
+  handler: (args) => {
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async (
+  args: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+  }>,
+): Promise<void> => {
+  await checkShouldRunTypeChecks({
+    pathsIgnore: args.pathsIgnore,
+    baseBranch: args.baseBranch,
+  });
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));

package/src/cmd/format-diff-from.mts

@@ -0,0 +1,49 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+import { formatDiffFrom } from '../functions/index.mjs';
+
+const cmdDef = cmd.command({
+  name: 'format-diff-from-cli',
+  version: '6.0.0',
+  args: {
+    base: cmd.positional({
+      type: cmd.string,
+      displayName: 'base',
+      description: 'Base branch name or commit hash to compare against',
+    }),
+    includeUntracked: cmd.flag({
+      long: 'include-untracked',
+      type: cmd.optional(cmd.boolean),
+      description:
+        'Include untracked files in addition to diff files (default: true)',
+    }),
+    silent: cmd.flag({
+      long: 'silent',
+      type: cmd.optional(cmd.boolean),
+      description: 'If true, suppresses output messages (default: false)',
+    }),
+  },
+  handler: (args) => {
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async (
+  args: Readonly<{
+    base: string;
+    includeUntracked?: boolean;
+    silent?: boolean;
+  }>,
+): Promise<void> => {
+  const result = await formatDiffFrom(args.base, args);
+
+  if (result === 'err') {
+    process.exit(1);
+  }
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));

package/src/cmd/format-untracked.mts

@@ -0,0 +1,31 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+import { formatUntracked } from '../functions/index.mjs';
+
+const cmdDef = cmd.command({
+  name: 'format-untracked-cli',
+  version: '6.0.0',
+  args: {
+    silent: cmd.flag({
+      long: 'silent',
+      type: cmd.optional(cmd.boolean),
+      description: 'If true, suppresses output messages (default: false)',
+    }),
+  },
+  handler: (args) => {
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async (args: Readonly<{ silent?: boolean }>): Promise<void> => {
+  const result = await formatUntracked({ silent: args.silent });
+  if (result === 'err') {
+    process.exit(1);
+  }
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));

package/src/cmd/gen-index-ts.mts

@@ -0,0 +1,147 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+
+// eslint-disable-next-line import/no-internal-modules
+import { type InputOf, type OutputOf } from 'cmd-ts/dist/esm/from.js';
+import { expectType } from 'ts-data-forge';
+import { genIndex } from '../functions/index.mjs';
+
+type Ext = `.${string}`;
+
+const extensionType = cmd.extendType(cmd.string, {
+  from: (s) => {
+    if (!s.startsWith('.')) {
+      throw new Error(`ext should start with '.'`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Promise.resolve(s as Ext);
+  },
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const nonEmptyArray = <T extends cmd.Type<any, any>>(
+  t: T,
+  commandName: string,
+): cmd.Type<InputOf<T>[], NonEmptyArray<OutputOf<T>>> =>
+  cmd.extendType(cmd.array(t), {
+    from: (arr) => {
+      if (arr.length === 0) {
+        throw new Error(
+          `No value provided for --${commandName}. At least one value is required.`,
+        );
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return Promise.resolve(arr as unknown as NonEmptyArray<OutputOf<T>>);
+    },
+  });
+
+const cmdDef = cmd.command({
+  name: 'gen-index-ts-cli',
+  version: '6.0.0',
+  args: {
+    // required args
+    targetDirectory: cmd.positional({
+      type: cmd.string,
+      displayName: 'target-directory',
+      description:
+        'Directory where the index file will be generated  (Comma-separated list can be used)',
+    }),
+
+    targetExtensions: cmd.multioption({
+      long: 'target-ext',
+      type: nonEmptyArray(extensionType, 'target-ext'),
+      description: 'File extensions to include in the index file',
+    }),
+    indexFileExtension: cmd.option({
+      long: 'index-ext',
+      type: extensionType,
+      description: 'Extension of the index file to be generated',
+    }),
+    exportStatementExtension: cmd.option({
+      long: 'export-ext',
+      type: cmd.union([
+        extensionType,
+        cmd.extendType(cmd.string, {
+          from: (s) => {
+            if (s !== 'none') {
+              throw new Error(
+                `export-ext should be 'none' or a valid extension`,
+              );
+            }
+            return Promise.resolve('none' as const);
+          },
+        }),
+      ]),
+      description: 'Extension of the export statements in the index file',
+    }),
+
+    // optional args
+    exclude: cmd.multioption({
+      long: 'exclude',
+      type: cmd.optional(cmd.array(cmd.string)),
+      description:
+        'Glob patterns of files to exclude from the index file (e.g., "*.d.mts", "*.test.mts")',
+    }),
+    formatCommand: cmd.option({
+      long: 'fmt',
+      type: cmd.optional(cmd.string),
+      description:
+        'Command to format after generating the index file (e.g., "npm run fmt")',
+    }),
+    silent: cmd.flag({
+      long: 'silent',
+      type: cmd.optional(cmd.boolean),
+      description: 'If true, suppresses output messages (default: false)',
+    }),
+  },
+  handler: (args) => {
+    console.log(args);
+
+    expectType<typeof args.targetDirectory, string>('=');
+    expectType<typeof args.targetExtensions, NonEmptyArray<Ext>>('=');
+    expectType<typeof args.exportStatementExtension, Ext | 'none'>('=');
+    expectType<typeof args.indexFileExtension, Ext>('=');
+
+    expectType<typeof args.exclude, string[] | undefined>('=');
+    expectType<typeof args.formatCommand, string | undefined>('=');
+    expectType<typeof args.silent, boolean | undefined>('=');
+
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async ({
+  targetDirectory,
+  targetExtensions,
+  exportStatementExtension,
+  indexFileExtension,
+  exclude,
+  formatCommand,
+  silent,
+}: Readonly<{
+  targetDirectory: string;
+  targetExtensions: readonly Ext[];
+  exportStatementExtension: Ext | 'none';
+  indexFileExtension: Ext;
+  exclude?: readonly string[] | undefined;
+  formatCommand?: string | undefined;
+  silent?: boolean | undefined;
+}>): Promise<void> => {
+  await genIndex({
+    targetDirectory: targetDirectory.includes(',')
+      ? targetDirectory.split(',').map((dir) => dir.trim())
+      : targetDirectory,
+    exportStatementExtension,
+    targetExtensions,
+    exclude,
+    indexFileExtension,
+    formatCommand,
+    silent,
+  });
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));