omnitrans-conta-cli Developer Documentation

Overview

omnitrans-conta-cli is a Node.js-based command-line tool for selecting months and creating directory structures. This README provides instructions for developers who want to modify, build, and deploy the CLI tool, as well as manage global installation in their development environment.

Table of Contents

• Changing the CLI Tool Name

• Understanding package.json Properties

• Development Workflow

  • Updating the Version Number
  • Building the CLI Tool
  • Testing Locally
  • Linking the CLI Tool Globally
  • Unlinking the CLI Tool
  • Redeploying after Changes

• Troubleshooting

Changing the CLI Tool Name

To change the command name used in the terminal, modify the bin field in your package.json:

"bin": {
  "omnitrans-conta": "dist/cli.js"
}

• The key (omnitrans-conta) is the command you type in the terminal.
• The value (dist/cli.js) is the script that runs.

If you change the project name (the name property in package.json), also update it to reflect the new CLI tool identity.

Understanding package.json Properties

| Property | Purpose | | ----------------- | ---------------------------------------------------------------------- | | name | The npm package name and identifier for the CLI tool | | version | The version number; update this for each new release | | bin | Maps the command-line executable to your JS entry point | | main | Entry point for usage as a Node.js library (not used by CLI execution) | | scripts | Scripts for building, starting, and testing the CLI tool | | devDependencies | Lists dev-only packages (TypeScript, Commander, etc.) | | type | Module system (module or commonjs) |

Development Workflow

1. Updating the Version Number

Edit the version field in package.json before publishing or redeploying:

"version": "1.0.1"

2. Building the CLI Tool

Transpile TypeScript to JavaScript:

pnpm build

(This runs the tsc command as defined in scripts.build.)

3. Testing Locally

You can run the CLI directly via Node.js:

pnpm start

Or:

node dist/cli.js

4. Linking the CLI Tool Globally

To use the CLI command anywhere in your terminal:

pnpm link --global

This creates a symlink so you can run your CLI command (as set in bin) globally.

To verify the global link:

which omnitrans-conta

5. Unlinking the CLI Tool

To remove the global CLI command:

pnpm remove --global omnitrans-conta-cli

This cleans up the symlink and removes the binary from your path.

6. Redeploying after Changes

1. Make your code changes.

2. Bump the version number in package.json.

3. Rebuild:

   pnpm build

4. If already linked globally, run:

   pnpm remove --global omnitrans-conta-cli
   pnpm link --global

   This ensures you are running the latest build globally.

Troubleshooting

• Unlink not working?

  • Ensure you run pnpm remove --global <package-name> from outside the project directory.
  • Manually check and remove the binary using which omnitrans-conta and rm if needed.

• Binary not updating?

  • Always unlink and re-link after rebuilding for changes to take effect globally.

Contribution Notes

• Make sure to keep dependencies up to date and regularly update the devDependencies as needed.
• Use semantic versioning for releases.
• Test CLI changes locally before deploying or sharing with others.