From Source

# Clone the repository
git clone https://github.com/luxi78/resolve-stack-cli.git
cd resolve-stack-cli
bun install
bun install -g .

Development Installation

# For development purposes
git clone https://github.com/luxi78/resolve-stack-cli.git
cd resolve-stack-cli
bun install

Development Prerequisites:

• Bun runtime (latest version recommended)
• TypeScript ^5.0.0

Development

Running the Development Version

bun run start

Building

This project uses ES modules and is designed to run directly with Bun:

bun run index.ts

Requirements

• Node.js-compatible runtime (Bun recommended)
• TypeScript ^5.0.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📦 NPM Publishing Guide

Core Concepts

This is a TypeScript CLI project that compiles TS code to Node.js-compatible JavaScript through a build process, then publishes to npm. Users don't need to install bun or TypeScript to use the package.

Project Configuration Essentials

Key package.json Fields

{
  "name": "resolve-stack-cli",
  "version": "1.0.0",
  "description": "A lightweight, fast command-line tool for resolving JavaScript stack traces using source maps",
  "main": "dist/index.js",           // Points to compiled JS file
  "module": "dist/index.js",
  "type": "module",
  "bin": {
    "resolve-stack": "dist/index.js"  // CLI command entry point
  },
  "files": [                         // Files included in publication
    "dist/**/*",
    "README.md", 
    "package.json"
  ],
  "engines": {
    "node": ">=16.0.0"              // Node.js version requirement
  }
}

Build Script Configuration

{
  "scripts": {
    "build": "bun build index.ts --outdir dist --target node --format esm",
    "prepublishOnly": "npm run build",  // Auto-build before publishing
    "test": "echo \"No tests specified\" && exit 0"
  }
}

Pre-Publishing Checklist

1. Complete Project Information

Update in package.json:

{
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourusername/resolve-stack-cli.git"
  },
  "bugs": {
    "url": "https://github.com/yourusername/resolve-stack-cli/issues"
  },
  "homepage": "https://github.com/yourusername/resolve-stack-cli#readme",
  "keywords": [
    "stack-trace",
    "source-map", 
    "cli",
    "debugging",
    "typescript",
    "javascript"
  ]
}

2. Fix Entry Point

Ensure index.ts uses Node.js shebang:

#!/usr/bin/env node
import { main } from './resolve-stack.js';

main().catch(console.error);

Complete Publishing Process

1. Register npm Account

# First-time registration
npm adduser

# Login with existing account
npm login

# Verify login status
npm whoami

2. Check Package Name Availability

npm view resolve-stack-cli
# If shows 404 Not Found, the package name is available

3. Pre-Build Verification

# Build project
npm run build

# Test build result
node dist/index.js --help

# Preview publication content
npm pack --dry-run

4. Publish to npm

# Publish
npm publish

# Verify successful publication
npm view resolve-stack-cli

Version Management

Manual Version Updates

# Modify version field in package.json
# Then republish
npm publish

Using npm Version Commands

# Patch version (1.0.0 → 1.0.1)
npm version patch && npm publish

# Minor version (1.0.0 → 1.1.0) 
npm version minor && npm publish

# Major version (1.0.0 → 2.0.0)
npm version major && npm publish

Technical Details

TypeScript to JavaScript Conversion

• Development Stage: Use bun to run TypeScript directly
• Build Stage: bun build compiles TS to Node.js-compatible JS
• Publishing Stage: Only publish compiled JavaScript
• User Usage: Run through Node.js, no bun required

Build Output Characteristics

• Uses #!/usr/bin/env node shebang
• ES Module format
• All dependencies bundled in single file
• Node.js >=16.0.0 compatible

User Installation Experience

# Global installation
npm install -g resolve-stack-cli

# Direct usage
resolve-stack --help

User system requirements:

• ✅ Node.js >=16.0.0
• ✅ npm
• ❌ No bun required
• ❌ No TypeScript required

Troubleshooting

Common Issues

1. Shebang errors: Ensure built file uses #!/usr/bin/env node
2. File permissions: Built file should have execute permissions
3. Import paths: Ensure import statements use .js extensions
4. Published files: Check files field includes dist/**/*

Verification Steps

# Check build file type
file dist/index.js
# Should display: Node.js script executable

# Check shebang
head -1 dist/index.js  
# Should display: #!/usr/bin/env node

# Test CLI functionality
node dist/index.js --help

Best Practices

1. Pre-publish testing: Always test built files locally
2. Semantic versioning: Follow Semantic Versioning
3. Documentation integrity: Keep README.md synchronized with features
4. License clarity: Choose appropriate open source license
5. Keyword optimization: Add relevant keywords for discoverability