Resolve Stack CLI

🤖 AI-Powered Development Project
This project was created through Vibe Coding using Gemini CLI + Claude 4 collaboration. The primary goal is to solve real-world problems while exploring the feasibility and capability boundaries of AI-assisted development workflows.

A lightweight, fast command-line tool for resolving JavaScript stack traces using source maps.

Features

• 🚀 Fast: Built with Bun runtime for optimal performance
• 📁 TOML Configuration: Support for TOML-based configuration files
• 🛠️ CLI Interface: Easy-to-use command-line interface
• 📊 Stack Trace Resolution: Resolve minified stack traces to original source code locations
• ⚡ TypeScript: Written in TypeScript with full type safety

Installation

From npm (Recommended)

# Install globally to use as a CLI tool
npm install -g resolve-stack-cli

Prerequisites

• Node.js >=16.0.0
• npm

Alternative Installation Methods

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

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

Usage

Overview

Resolve Stack CLI helps you convert minified production stack traces back to their original source code locations using source maps. There are two main ways to use the tool:

Method 1: Interactive Input

Run the command with your configuration file, then paste the production stack trace:

resolve-stack -c config.toml

After running the command, paste your production stack trace (for example):

TypeError: Invalid name
    at nG._onHeadersReceived (https://cdn.xuante.top:44300/cdns1.bangnimang.net/fapiao-ng/_next/static/chunks/9b0008ae-271aa26b9a487cb1.js:1:176771)
    at nj.onStateChange (https://cdn.xuante.top:44300/cdns1.bangnimang.net/fapiao-ng/_next/static/chunks/9b0008ae-271aa26b9a487cb1.js:1:174923)

Then press Ctrl+D (Linux/Mac) or Ctrl+Z (Windows) to finish input. You'll get the resolved stack trace:

TypeError: Invalid name
    at _onHeadersReceived (webpack://_N_E/pdf.js/src/display/network.js:276:28)
    const responseHeaders = new Headers();
                            ^
    at onStateChange (webpack://_N_E/pdf.js/src/display/network.js:119:21)
    pendingRequest.onHeadersReceived();
                   ^

Method 2: File Input with Pipe

Save your production stack trace to a file and pipe it to the tool:

# Save stack trace to a file
echo "TypeError: Invalid name
    at nG._onHeadersReceived (https://cdn.xuante.top:44300/cdns1.bangnimang.net/fapiao-ng/_next/static/chunks/9b0008ae-271aa26b9a487cb1.js:1:176771)
    at nj.onStateChange (https://cdn.xuante.top:44300/cdns1.bangnimang.net/fapiao-ng/_next/static/chunks/9b0008ae-271aa26b9a487cb1.js:1:174923)" > stack.txt

# Process the file
cat stack.txt | resolve-stack -c config.toml

Both methods produce the same resolved output with original source locations.

Command Line Options

• -c, --config: Path to a TOML config file
• --app-url-base: The base URL of your deployed application
• --source-map-root: The local root directory of your source maps
• -h, --help: Show help
• --version: Show version number

Quick Start

# Install globally
npm install -g resolve-stack-cli

# Get help
resolve-stack --help

# Use with config file (interactive)
resolve-stack -c your-config.toml

# Use with piped input
cat error-log.txt | resolve-stack -c your-config.toml

# If running from source:
bun run index.ts [options]
bun run index.ts --help

Configuration

Resolve Stack CLI supports TOML configuration files for advanced usage scenarios. Create a configuration file in your project directory:

# example.toml
appUrlBase = "https://cdn.xuante.top:44300/cdns1.bangnimang.net/fapiao-ng"
sourceMapRoot = "out"

Dependencies

• @iarna/toml: TOML parser for configuration files
• source-map: Core source map processing library for stack trace resolution
• yargs: Command-line argument parsing

License

MIT License

For Developers and Contributors

bun run start

bun run index.ts

{
  "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
  }
}

{
  "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"
  }
}

{
  "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"
  ]
}

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

main().catch(console.error);

# First-time registration
npm adduser

# Login with existing account
npm login

# Verify login status
npm whoami

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

# Build project
npm run build

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

# Preview publication content
npm pack --dry-run

# Publish
npm publish

# Verify successful publication
npm view resolve-stack-cli

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

# 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

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

# Direct usage
resolve-stack --help

# 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

Built with ❤️ using Bun runtime.