@versatiles/release-tool 2.0.0 → 2.2.0

package/README.md

@@ -5,12 +5,12 @@
 
 Tools used for:
 
-* creating a graph of the source code as mermaid: [`vrt deps-graph`](#subcommand-vrt-deps-graph)
-* upgrading all package dependencies: [`vrt deps-upgrade`](#subcommand-vrt-deps-upgrade)
-* creating Markdown documentation of executables: [`vrt doc-command`](#subcommand-vrt-doc-command)
-* inserting Markdown into documents: [`vrt doc-insert`](#subcommand-vrt-doc-insert)
-* updating "Table of Content" in Markdown files: [`vrt doc-toc`](#subcommand-vrt-doc-toc)
-* releasing the project as npm package: [`vrt release-npm`](#subcommand-vrt-release-npm)
+- creating a graph of the source code as mermaid: [`vrt deps-graph`](#subcommand-vrt-deps-graph)
+- upgrading all package dependencies: [`vrt deps-upgrade`](#subcommand-vrt-deps-upgrade)
+- creating Markdown documentation of executables: [`vrt doc-command`](#subcommand-vrt-doc-command)
+- inserting Markdown into documents: [`vrt doc-insert`](#subcommand-vrt-doc-insert)
+- updating "Table of Content" in Markdown files: [`vrt doc-toc`](#subcommand-vrt-doc-toc)
+- releasing the project as npm package: [`vrt release-npm`](#subcommand-vrt-release-npm)
 
 # Installation
 
@@ -34,9 +34,9 @@ You need to configure the scripts in the package.json:
 }
 ```
 
-* `scripts.check` is **required** by the release command. Here you can lint, build and test your code.
-* `scripts.prepack` is **recommended** to ensure that all files are up-to-date before releasing. Here you can build code and documentation.
-* `scripts.release` is **recommended** to make it easy to release a new version.
+- `scripts.check` is **required** by the release command. Here you can lint, build and test your code.
+- `scripts.prepack` is **recommended** to ensure that all files are up-to-date before releasing. Here you can build code and documentation.
+- `scripts.release` is **recommended** to make it easy to release a new version.
 
 # Command `vrt`
 
@@ -46,19 +46,34 @@ You need to configure the scripts in the package.json:
 $ vrt
 Usage: vrt [options] [command]
 
-versatiles release and documentaion tool
+CLI tool for releasing packages and generating documentation for
+Node.js/TypeScript projects.
 
 Options:
   -h, --help                                display help for command
 
 Commands:
-  deps-graph                                draws a graph of all files in the project and outputs it as mermaid
-  deps-upgrade                              upgrades all dependencies to the latest version
-  doc-command <command>                     documents a runnable command and outputs it
-  doc-insert <readme> [heading] [foldable]  takes Markdown from stdin and insert it into a Markdown file
-  doc-toc <readme> [heading]                updates the TOC in a Markdown file
-  release-npm [path]                        releases a npm package
+  check-package                             Check package.json for required scripts and other metadata.
+  deps-graph                                Analyze project files and output a dependency graph as Mermaid markup.
+  deps-upgrade                              Upgrade all dependencies in the current project to their latest versions.
+  doc-command <command>                     Generate Markdown documentation for a specified command and output the result.
+  doc-insert <readme> [heading] [foldable]  Insert Markdown from stdin into a specified section of a Markdown file.
+  doc-toc <readme> [heading]                Generate a Table of Contents (TOC) in a Markdown file.
+  doc-typescript [options]                  Generate documentation for a TypeScript project.
   help [command]                            display help for command
+  release-npm [path]                        Publish an npm package from the specified path to the npm registry.
+```
+
+## Subcommand: `vrt check-package`
+
+```console
+$ vrt check-package
+Usage: vrt check-package [options]
+
+Check package.json for required scripts and other metadata.
+
+Options:
+  -h, --help  display help for command
 ```
 
 ## Subcommand: `vrt deps-graph`
@@ -67,7 +82,7 @@ Commands:
 $ vrt deps-graph
 Usage: vrt deps-graph [options]
 
-draws a graph of all files in the project and outputs it as mermaid
+Analyze project files and output a dependency graph as Mermaid markup.
 
 Options:
   -h, --help  display help for command
@@ -79,7 +94,7 @@ Options:
 $ vrt deps-upgrade
 Usage: vrt deps-upgrade [options]
 
-upgrades all dependencies to the latest version
+Upgrade all dependencies in the current project to their latest versions.
 
 Options:
   -h, --help  display help for command
@@ -91,10 +106,10 @@ Options:
 $ vrt doc-command
 Usage: vrt doc-command [options] <command>
 
-documents a runnable command and outputs it
+Generate Markdown documentation for a specified command and output the result.
 
 Arguments:
-  command     command to run
+  command     Command to document (e.g., "npm run build").
 
 Options:
   -h, --help  display help for command
@@ -106,12 +121,14 @@ Options:
 $ vrt doc-insert
 Usage: vrt doc-insert [options] <readme> [heading] [foldable]
 
-takes Markdown from stdin and insert it into a Markdown file
+Insert Markdown from stdin into a specified section of a Markdown file.
 
 Arguments:
-  readme      Markdown file, like a readme.md
-  heading     Heading in the Markdown file (default: "# API")
-  foldable    Make content foldable (default: false)
+  readme      Path to the target Markdown file (e.g., README.md).
+  heading     Heading in the Markdown file where content should be placed.
+              Default is "# API". (default: "# API")
+  foldable    Whether to wrap the inserted content in a foldable section.
+              (default: false)
 
 Options:
   -h, --help  display help for command
@@ -123,26 +140,46 @@ Options:
 $ vrt doc-toc
 Usage: vrt doc-toc [options] <readme> [heading]
 
-updates the TOC in a Markdown file
+Generate a Table of Contents (TOC) in a Markdown file.
 
 Arguments:
-  readme      Markdown file, like a readme.md
-  heading     Heading in the Markdown file (default: "# Table of Content")
+  readme      Path to the Markdown file (e.g., README.md).
+  heading     Heading in the Markdown file where TOC should be inserted. Default
+              is "# Table of Content". (default: "# Table of Content")
 
 Options:
   -h, --help  display help for command
 ```
 
+## Subcommand: `vrt doc-typescript`
+
+```console
+$ vrt doc-typescript
+Usage: vrt doc-typescript [options]
+
+Generate documentation for a TypeScript project.
+
+Options:
+  -f, --format <format>      Allowed are "markdown", "wiki" and "html". Default
+                             is "markdown".
+  -h, --help                 display help for command
+  -i, --input <entryPoint>   Entry point of the TypeScript project. Default is
+                             "./src/index.ts".
+  -o, --output <outputPath>  Output path for the generated documentation.
+                             Default is "./docs".
+```
+
 ## Subcommand: `vrt release-npm`
 
 ```console
 $ vrt release-npm
 Usage: vrt release-npm [options] [path]
 
-releases a npm package
+Publish an npm package from the specified path to the npm registry.
 
 Arguments:
-  path        root path of the Node.js project
+  path        Root path of the Node.js project. Defaults to the current
+              directory.
 
 Options:
   -h, --help  display help for command
@@ -159,32 +196,38 @@ flowchart TB
 
 subgraph 0["src"]
 subgraph 1["commands"]
-2["command.ts"]
-5["dependency-graph.ts"]
-7["markdown.ts"]
-8["release.ts"]
-B["upgrade-dependencies.ts"]
+2["check-package.ts"]
+5["deps-graph.ts"]
+6["deps-upgrade.ts"]
+8["doc-command.ts"]
+A["doc-typescript.ts"]
+B["markdown.ts"]
+C["release-npm.ts"]
 end
 subgraph 3["lib"]
-4["utils.ts"]
-6["log.ts"]
-9["git.ts"]
-A["shell.ts"]
+4["log.ts"]
+7["shell.ts"]
+9["utils.ts"]
+D["git.ts"]
 end
-C["index.ts"]
+E["index.ts"]
 end
 2-->4
-5-->6
-7-->4
+5-->4
+6-->4
+6-->7
 8-->9
-8-->6
-8-->A
-9-->A
-B-->6
-B-->A
-C-->2
-C-->5
+A-->4
+B-->9
+C-->D
+C-->4
 C-->7
-C-->8
-C-->B
+D-->7
+E-->2
+E-->5
+E-->6
+E-->8
+E-->A
+E-->B
+E-->C
 ```

package/dist/commands/check-package.d.ts

@@ -0,0 +1 @@
+export declare function checkPackage(directory: string): void;

package/dist/commands/check-package.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { panic, info, warn } from '../lib/log.js';
+import { resolve } from 'node:path';
+export function checkPackage(directory) {
+    const pack = JSON.parse(readFileSync(resolve(directory, 'package.json'), 'utf8'));
+    const { scripts } = pack;
+    if (!scripts)
+        panic('scripts not found');
+    if (!scripts.test)
+        info('scripts.test is recommended');
+    if (!scripts.doc)
+        info('scripts.doc is recommended');
+    if (!scripts.build)
+        panic('scripts.build is required');
+    if (!scripts.check)
+        panic('scripts.check is required');
+    if (!scripts.check.includes('npm run build')) {
+        warn(`scripts.check should include "npm run build", but is "${scripts.check}"`);
+    }
+    if (!scripts.prepack)
+        panic('scripts.prepack is required');
+    if (scripts.prepack !== 'npm run build') {
+        warn(`scripts.prepack should be "npm run build", but is "${scripts.prepack}"`);
+    }
+    if (!scripts.release)
+        panic('scripts.release is required');
+    if (scripts.release !== 'vrt release-npm') {
+        warn(`scripts.release should be "vrt release-npm", but is "${scripts.release}"`);
+    }
+    if (!scripts.upgrade) {
+        warn('scripts.upgrade is recommended');
+    }
+    else if (scripts.upgrade !== 'vrt deps-upgrade') {
+        info(`scripts.upgrade should be "vrt deps-upgrade", but is "${scripts.upgrade}"`);
+    }
+    if (!scripts['doc-graph']) {
+        info(`scripts.doc-graph could be: "vrt deps-graph | vrt doc-insert README.md '## Dependency Graph'"`);
+    }
+    else {
+        if (scripts.doc && !scripts.doc.includes('npm run doc-graph')) {
+            info('scripts.doc should include "npm run doc-graph"');
+        }
+    }
+    ['npm-check-updates'].forEach((dep) => {
+        if (pack.dependencies?.[dep]) {
+            info(`dependencies "${dep}" is probably not needed`);
+        }
+        if (pack.devDependencies?.[dep]) {
+            info(`devDependencies "${dep}" is probably not needed`);
+        }
+    });
+}
+//# sourceMappingURL=check-package.js.map

package/dist/commands/{dependency-graph.js → deps-graph.js}

@@ -18,4 +18,4 @@ export async function generateDependencyGraph(directory) {
     output = output.replace('flowchart LR', 'flowchart TB');
     process.stdout.write(Buffer.from('```mermaid\n' + output + '```\n'));
 }
-//# sourceMappingURL=dependency-graph.js.map
+//# sourceMappingURL=deps-graph.js.map

package/dist/commands/deps-upgrade.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Upgrades the dependencies in a package.json file to their latest versions, removes existing
+ * installed modules, and reinstalls them in the specified directory.
+ *
+ * This function performs the following steps:
+ * 1. Checks for outdated dependencies by running `npm outdated --all --json`.
+ * 2. Reads the project's package.json file and updates any existing dependencies to their latest versions.
+ * 3. Removes all installed modules (`node_modules`) and the lock file (`package-lock.json`).
+ * 4. Reinstalls and updates all dependencies.
+ * 5. Logs a message indicating that all dependencies are up to date.
+ *
+ * @param directory - The path to the directory containing the Node.js project.
+ * @returns A promise that resolves when the process is complete.
+ */
+export declare function upgradeDependencies(directory: string): Promise<void>;

package/dist/commands/deps-upgrade.js

@@ -0,0 +1,99 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { check, info } from '../lib/log.js';
+import { getShell } from '../lib/shell.js';
+/**
+ * Upgrades the dependencies in a package.json file to their latest versions, removes existing
+ * installed modules, and reinstalls them in the specified directory.
+ *
+ * This function performs the following steps:
+ * 1. Checks for outdated dependencies by running `npm outdated --all --json`.
+ * 2. Reads the project's package.json file and updates any existing dependencies to their latest versions.
+ * 3. Removes all installed modules (`node_modules`) and the lock file (`package-lock.json`).
+ * 4. Reinstalls and updates all dependencies.
+ * 5. Logs a message indicating that all dependencies are up to date.
+ *
+ * @param directory - The path to the directory containing the Node.js project.
+ * @returns A promise that resolves when the process is complete.
+ */
+export async function upgradeDependencies(directory) {
+    const shell = getShell(directory);
+    // Step 1: Check and upgrade all versions
+    await check('Upgrade all versions', async () => {
+        const { stdout } = await shell.run('npm outdated --all --json', false);
+        const outdated = JSON.parse(stdout);
+        const latestVersions = new Map();
+        // Collect the latest version for each dependency
+        for (const [name, entry] of Object.entries(outdated)) {
+            let version = '0.0.0';
+            if (Array.isArray(entry)) {
+                for (const item of entry) {
+                    if (isGreaterSemver(item.latest, version))
+                        version = item.latest;
+                }
+            }
+            else {
+                version = entry.latest;
+            }
+            latestVersions.set(name, version);
+        }
+        // Load package.json
+        const pack = JSON.parse(readFileSync('package.json', 'utf8'));
+        // Update dependencies to their latest versions
+        patch(pack.dependencies);
+        patch(pack.devDependencies);
+        patch(pack.optionalDependencies);
+        patch(pack.peerDependencies);
+        // Write the updated package.json
+        writeFileSync('package.json', JSON.stringify(pack, null, 2) + '\n');
+        /**
+         * Mutates the provided dependency object by updating
+         * each dependency to the latest known version (if available).
+         *
+         * @param dependencies - A mapping of dependency names to their currently specified versions.
+         */
+        function patch(dependencies) {
+            if (!dependencies)
+                return;
+            for (const name of Object.keys(dependencies)) {
+                const version = latestVersions.get(name);
+                if (version)
+                    dependencies[name] = '^' + version;
+            }
+        }
+    });
+    // Step 2: Remove existing dependencies and lock file
+    await check('Remove all dependencies', async () => {
+        await shell.run('rm -rf node_modules');
+        await shell.run('rm -f package-lock.json');
+    });
+    // Step 3: Reinstall/upgrade all dependencies
+    await check('Upgrade all dependencies', shell.stdout('npm update --save'));
+    // Final log message
+    info('All dependencies are up to date');
+}
+/**
+ * Compares two semantic version strings (major.minor.patch) and checks if `a` is greater than `b`.
+ *
+ * @param a - A semantic version string (e.g., "1.2.3").
+ * @param b - Another semantic version string (e.g., "1.2.4").
+ * @returns `true` if `a` is greater than `b`, otherwise `false`.
+ * @throws If either version string is invalid (i.e., not in "x.x.x" format).
+ */
+function isGreaterSemver(a, b) {
+    const pa = a.split('.');
+    const pb = b.split('.');
+    for (let i = 0; i < 3; i++) {
+        const na = Number(pa[i]);
+        const nb = Number(pb[i]);
+        if (isNaN(na))
+            throw new Error('Invalid version number: ' + a);
+        if (isNaN(nb))
+            throw new Error('Invalid version number: ' + b);
+        if (na > nb)
+            return true;
+        if (na < nb)
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=deps-upgrade.js.map

package/dist/commands/{command.js → doc-command.js}

@@ -31,7 +31,13 @@ export async function generateCommandDocumentation(command) {
  */
 async function getCommandResults(command) {
     return new Promise((resolve, reject) => {
-        const env = { ...process.env, NODE_ENV: undefined };
+        const env = {
+            ...process.env,
+            NODE_ENV: undefined,
+            NODE_DISABLE_COLORS: '1',
+            NO_COLORS: '1',
+            FORCE_COLOR: '0'
+        };
         // Spawn a child process to run the command with the '--help' flag.
         const childProcess = cp.spawn('npx', [...command.split(' '), '--help'], { env });
         let output = '';
@@ -81,4 +87,4 @@ function extractSubcommands(result) {
         return [subcommand];
     });
 }
-//# sourceMappingURL=command.js.map
+//# sourceMappingURL=doc-command.js.map

package/dist/commands/doc-typescript.d.ts

@@ -0,0 +1,6 @@
+export declare function generateTypescriptDocs(options: {
+    entryPoint?: string;
+    outputPath?: string;
+    format?: 'markdown' | 'wiki' | 'html';
+    quiet?: boolean;
+}): Promise<void>;

package/dist/commands/doc-typescript.js

@@ -0,0 +1,49 @@
+import * as td from 'typedoc';
+import { panic, warn } from '../lib/log.js';
+export async function generateTypescriptDocs(options) {
+    const { entryPoint, outputPath, quiet } = options;
+    const format = options.format ?? 'markdown';
+    const isMarkdown = format !== 'html';
+    const plugin = [
+        isMarkdown && 'typedoc-plugin-markdown',
+        format === 'wiki' && 'typedoc-github-wiki-theme',
+        format === 'html' && 'typedoc-unhoax-theme',
+    ].filter(Boolean);
+    const app = await td.Application.bootstrapWithPlugins({
+        entryPoints: [entryPoint ?? './src/index.ts'],
+        gitRevision: 'main',
+        out: outputPath ?? './docs',
+        plugin,
+        logLevel: quiet ? 'Warn' : 'Info',
+    }, [
+        new td.TypeDocReader(),
+        new td.PackageJsonReader(),
+        new td.TSConfigReader(),
+    ]);
+    app.options.setValue('readme', 'none');
+    if (isMarkdown) {
+        app.options.setValue('hidePageHeader', true);
+        app.options.setValue('classPropertiesFormat', 'table');
+        app.options.setValue('enumMembersFormat', 'table');
+        app.options.setValue('indexFormat', 'table');
+        app.options.setValue('interfacePropertiesFormat', 'table');
+        app.options.setValue('parametersFormat', 'table');
+        app.options.setValue('propertiesFormat', 'table');
+        app.options.setValue('propertyMembersFormat', 'table');
+        app.options.setValue('typeDeclarationFormat', 'table');
+    }
+    const project = await app.convert();
+    if (!project)
+        panic('Failed to convert project');
+    app.validate(project);
+    if (app.logger.hasWarnings())
+        warn('Warnings found during validation');
+    if (app.logger.hasErrors())
+        panic('Errors found during validation');
+    await app.generateOutputs(project);
+    if (app.logger.hasWarnings())
+        warn('Warnings found during validation');
+    if (app.logger.hasErrors())
+        panic('Errors found during validation');
+}
+//# sourceMappingURL=doc-typescript.js.map

package/dist/commands/markdown.js

@@ -1,5 +1,6 @@
 import { remark } from 'remark';
 import remarkGfm from 'remark-gfm';
+import remarkStringify from 'remark-stringify';
 import { getErrorMessage } from '../lib/utils.js';
 /**
  * Injects a Markdown segment under a specified heading in a Markdown document.
@@ -37,7 +38,16 @@ export function injectMarkdown(document, segment, heading, foldable) {
     // Merge the original document AST with the new segment AST.
     mergeSegments(documentAst, segmentAst, startIndex + 1, endIndex);
     // Convert the modified AST back to a Markdown string and return.
-    return remark().stringify(documentAst);
+    const result = remark()
+        .use(remarkGfm, {
+        tableCellPadding: true,
+    })
+        .use(remarkStringify, {
+        bullet: '-',
+        rule: '-',
+    })
+        .stringify(documentAst);
+    return result;
 }
 /**
  * Updates the Table of Contents (TOC) of a Markdown document.

package/dist/commands/{release.js → release-npm.js}

@@ -126,4 +126,4 @@ export async function release(directory, branch = 'main') {
         }
     }
 }
-//# sourceMappingURL=release.js.map
+//# sourceMappingURL=release-npm.js.map

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env -S node --enable-source-maps
 import { Command } from 'commander';
+/**
+ * Main CLI program, configured with custom text styling for titles, commands, options, etc.
+ */
 export declare const program: Command;

package/dist/index.js

@@ -1,70 +1,141 @@
 #!/usr/bin/env -S node --enable-source-maps
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { styleText } from 'node:util';
 import { injectMarkdown, updateTOC } from './commands/markdown.js';
 import { Command, InvalidArgumentError } from 'commander';
 import { cwd } from 'node:process';
-import { generateCommandDocumentation } from './commands/command.js';
-import { release } from './commands/release.js';
-import { upgradeDependencies } from './commands/upgrade-dependencies.js';
-import { generateDependencyGraph } from './commands/dependency-graph.js';
+import { generateCommandDocumentation } from './commands/doc-command.js';
+import { release } from './commands/release-npm.js';
+import { upgradeDependencies } from './commands/deps-upgrade.js';
+import { generateDependencyGraph } from './commands/deps-graph.js';
+import { checkPackage } from './commands/check-package.js';
+import { generateTypescriptDocs } from './commands/doc-typescript.js';
+/**
+ * Main CLI program, configured with custom text styling for titles, commands, options, etc.
+ */
 export const program = new Command();
+program.configureHelp({
+    styleTitle: (str) => styleText('bold', str),
+    styleCommandText: (str) => styleText('bold', str),
+    styleOptionText: (str) => styleText('cyan', str),
+    styleArgumentText: (str) => styleText('green', str),
+    styleSubcommandText: (str) => styleText('yellow', str),
+    sortOptions: true,
+    sortSubcommands: true,
+});
 program
     .name('vrt')
-    .description('versatiles release and documentaion tool');
+    .description('CLI tool for releasing packages and generating documentation for Node.js/TypeScript projects.');
+/**
+ * Command: check-package
+ * Checks that the project's package.json includes certain required scripts/fields.
+ */
+program.command('check-package')
+    .description('Check package.json for required scripts and other metadata.')
+    .action(() => {
+    void checkPackage(process.cwd());
+});
+/**
+ * Command: deps-graph
+ * Analyzes the project’s files to produce a dependency graph (in Mermaid format).
+ */
 program.command('deps-graph')
-    .description('draws a graph of all files in the project and outputs it as mermaid')
+    .description('Analyze project files and output a dependency graph as Mermaid markup.')
     .action(() => {
     void generateDependencyGraph(process.cwd());
 });
+/**
+ * Command: deps-upgrade
+ * Upgrades project dependencies in package.json to their latest versions and reinstalls them.
+ */
 program.command('deps-upgrade')
-    .description('upgrades all dependencies to the latest version')
+    .description('Upgrade all dependencies in the current project to their latest versions.')
     .action(() => {
     void upgradeDependencies(process.cwd());
 });
+/**
+ * Command: doc-command
+ * Generates Markdown documentation for a given CLI command.
+ */
 program.command('doc-command')
-    .description('documents a runnable command and outputs it')
-    .argument('<command>', 'command to run')
+    .description('Generate Markdown documentation for a specified command and output the result.')
+    .argument('<command>', 'Command to document (e.g., "npm run build").')
     .action(async (command) => {
     const mdDocumentation = await generateCommandDocumentation(command);
     process.stdout.write(mdDocumentation);
 });
+/**
+ * Command: doc-insert
+ * Inserts Markdown content from stdin into a specified Markdown file under a given heading.
+ * Optionally makes the inserted content foldable.
+ */
 program.command('doc-insert')
-    .description('takes Markdown from stdin and insert it into a Markdown file')
-    .argument('<readme>', 'Markdown file, like a readme.md', checkFilename)
-    .argument('[heading]', 'Heading in the Markdown file', '# API')
-    .argument('[foldable]', 'Make content foldable', false)
+    .description('Insert Markdown from stdin into a specified section of a Markdown file.')
+    .argument('<readme>', 'Path to the target Markdown file (e.g., README.md).', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file where content should be placed. Default is "# API".', '# API')
+    .argument('[foldable]', 'Whether to wrap the inserted content in a foldable section.', false)
     .action(async (mdFilename, heading, foldable) => {
     const buffers = [];
-    for await (const data of process.stdin)
+    for await (const data of process.stdin) {
         buffers.push(data);
-    const mdContent = '<!--- This chapter is generated automatically --->\n' + Buffer.concat(buffers).toString();
+    }
+    const mdContent = '<!--- This chapter is generated automatically --->\n'
+        + Buffer.concat(buffers).toString();
     let mdFile = readFileSync(mdFilename, 'utf8');
     mdFile = injectMarkdown(mdFile, mdContent, heading, foldable);
     writeFileSync(mdFilename, mdFile);
 });
+/**
+ * Command: doc-toc
+ * Updates or generates a Table of Contents in a Markdown file under a specified heading.
+ */
 program.command('doc-toc')
-    .description('updates the TOC in a Markdown file')
-    .argument('<readme>', 'Markdown file, like a readme.md', checkFilename)
-    .argument('[heading]', 'Heading in the Markdown file', '# Table of Content')
+    .description('Generate a Table of Contents (TOC) in a Markdown file.')
+    .argument('<readme>', 'Path to the Markdown file (e.g., README.md).', checkFilename)
+    .argument('[heading]', 'Heading in the Markdown file where TOC should be inserted. Default is "# Table of Content".', '# Table of Content')
     .action((mdFilename, heading) => {
     let mdFile = readFileSync(mdFilename, 'utf8');
     mdFile = updateTOC(mdFile, heading);
     writeFileSync(mdFilename, mdFile);
 });
+/**
+ * Command: doc-typescript
+ * Generates documentation for a TypeScript project.
+ * Allows specifying entry point and output location.
+ */
+program.command('doc-typescript')
+    .description('Generate documentation for a TypeScript project.')
+    .option('-i, --input <entryPoint>', 'Entry point of the TypeScript project. Default is "./src/index.ts".')
+    .option('-o, --output <outputPath>', 'Output path for the generated documentation. Default is "./docs".')
+    .option('-f, --format <format>', 'Allowed are "markdown", "wiki" and "html". Default is "markdown".')
+    .action(async (options) => {
+    await generateTypescriptDocs(options);
+});
+/**
+ * Command: release-npm
+ * Releases/publishes an npm package from a specified project path to the npm registry.
+ */
 program.command('release-npm')
-    .description('releases a npm package')
-    .argument('[path]', 'root path of the Node.js project')
+    .description('Publish an npm package from the specified path to the npm registry.')
+    .argument('[path]', 'Root path of the Node.js project. Defaults to the current directory.')
     .action((path) => {
     void release(resolve(path ?? '.', process.cwd()), 'main');
 });
 if (process.env.NODE_ENV !== 'test') {
     await program.parseAsync();
 }
+/**
+ * Validates that the given filename exists.
+ * Throws an InvalidArgumentError if the file cannot be found.
+ *
+ * @param filename - The filename to check.
+ * @returns The resolved full path if the file exists.
+ */
 function checkFilename(filename) {
     const fullname = resolve(cwd(), filename);
     if (!existsSync(fullname)) {
-        throw new InvalidArgumentError('file not found');
+        throw new InvalidArgumentError(`File not found: ${filename}`);
     }
     return fullname;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/release-tool",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "VersaTiles release and documentation tools",
   "bin": {
     "vrt": "./dist/index.js"
@@ -10,7 +10,8 @@
     "dist/**/*.d.ts"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js && npm run doc",
+    "build": "npm run build-node && npm run doc",
+    "build-node": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
     "check": "npm run lint && npm run build && npm run test",
     "dev": "tsx src/index.ts",
     "doc": "npm run doc-command && npm run doc-graph",
@@ -18,7 +19,7 @@
     "doc-graph": "tsx src/index.ts deps-graph | tsx src/index.ts doc-insert README.md '## Dependency Graph'",
     "lint": "eslint . --color",
     "prepack": "npm run build",
-    "release": "npm run build && tsx src/index.ts release-npm",
+    "release": "tsx src/index.ts release-npm",
     "test-coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "upgrade": "tsx src/index.ts deps-upgrade"
@@ -32,6 +33,7 @@
   },
   "homepage": "https://github.com/versatiles-org/node-release-tool",
   "devDependencies": {
+    "@schemastore/package": "^0.0.10",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.13.5",
     "@typescript-eslint/eslint-plugin": "^8.22.0",
@@ -48,6 +50,10 @@
     "commander": "^13.1.0",
     "dependency-cruiser": "^16.10.0",
     "remark": "^15.0.1",
-    "remark-gfm": "^4.0.1"
+    "remark-gfm": "^4.0.1",
+    "typedoc": "^0.27.8",
+    "typedoc-github-wiki-theme": "^2.1.0",
+    "typedoc-plugin-markdown": "^4.4.2",
+    "typedoc-unhoax-theme": "^0.4.6"
   }
 }

package/dist/commands/upgrade-dependencies.d.ts

@@ -1 +0,0 @@
-export declare function upgradeDependencies(directory: string): Promise<void>;

package/dist/commands/upgrade-dependencies.js

@@ -1,12 +0,0 @@
-import { check, info } from '../lib/log.js';
-import { getShell } from '../lib/shell.js';
-export async function upgradeDependencies(directory) {
-    const shell = getShell(directory);
-    await check('Remove all dependencies', async () => {
-        await shell.run('rm -rf node_modules');
-        await shell.run('rm -f package-lock.json');
-    });
-    await check('Upgrade all dependencies', shell.stdout('npm update --save'));
-    info('All dependencies are up to date');
-}
-//# sourceMappingURL=upgrade-dependencies.js.map