### Install and Use Shuji CLI

Source: https://context7.com/paazmaya/shuji/llms.txt

Install Shuji globally to use its command-line interface. Examples show processing single map files, entire directories, filtering by file type, and checking the version.

```bash
npm install --global shuji
```

```bash
# Extract sources from a single .map file into ./output/
shuji stretchy.min.js.map -o ./output
```

```bash
# Process an entire dist/ directory, preserving original folder structure
shuji dist/ -o ./recovered -p -v
```

```bash
# Filter only CSS maps; verbose mode shows each file being processed
shuji ./build -o ./src-recovered --match '\.css\.map$' --verbose
```

```bash
# Check version
shuji --version
# → 0.8.0
```

```bash
# Full help output
shuji --help
# shuji - Reverse engineering JavaScript and CSS sourcemaps
# Usage: shuji [options] <file|directory>
#
#   -h, --help               Help and usage instructions
#   -o, --output-dir String  Output directory - default: .
#   -p, --preserve           Preserve sourcemap's original folder structure.
#   -M, --match String       Regular expression for matching and filtering files -
#                            default: \.map$
#   -v, --verbose            Verbose output, will print which file is currently being processed
#   -V, --version            Version number
```

--------------------------------

### Basic Shuji Usage Example

Source: https://github.com/paazmaya/shuji/blob/master/README.md

A basic command-line usage example for shuji, specifying the input sourcemap file and the output directory.

```bash
shuji file.js.map -o folder
```

--------------------------------

### Install Shuji CLI Globally

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Install the shuji command line utility globally using npm. Elevated privileges might be needed.

```bash
npm install --global shuji
```

--------------------------------

### Shuji CLI Usage

Source: https://context7.com/paazmaya/shuji/llms.txt

Install and run Shuji globally to process files or directories. Options include specifying an output directory, preserving folder structure, filtering files by a regular expression, and enabling verbose output.

```APIDOC
## CLI — `shuji`

**Install globally and run against a file or directory**

The primary interface for shuji. Accepts one or more file paths or directories, recursively discovers matching files, extracts sources, and writes the recovered originals to an output directory. The `--match` flag controls which files are selected; `--preserve` retains the original folder hierarchy embedded in the sourcemap; `--verbose` prints progress details.

```sh
# Install globally
npm install --global shuji

# Extract sources from a single .map file into ./output/
shuji stretchy.min.js.map -o ./output

# Process an entire dist/ directory, preserving original folder structure
shuji dist/ -o ./recovered -p -v

# Filter only CSS maps; verbose mode shows each file being processed
shuji ./build -o ./src-recovered --match '\.css\.map$' --verbose

# Check version
shuji --version
# → 0.8.0

# Full help output
shuji --help
# shuji - Reverse engineering JavaScript and CSS sources from sourcemaps
# Usage: shuji [options] <file|directory>
#
#   -h, --help               Help and usage instructions
#   -o, --output-dir String  Output directory - default: .
#   -p, --preserve           Preserve sourcemap's original folder structure.
#   -M, --match String       Regular expression for matching and filtering files -
#                            default: \.map$
#   -v, --verbose            Verbose output, will print which file is currently being processed
#   -V, --version            Version number
```
```

--------------------------------

### Read Sources from CSS Sourcemap

Source: https://context7.com/paazmaya/shuji/llms.txt

Parses a CSS sourcemap to extract embedded source content. Use `preserve: false` to get basenames as keys.

```javascript
import fs from 'node:fs';
import readSources from 'shuji/lib/read-sources.js';

// --- Basic usage: extract sources from a CSS sourcemap ---
const cssMap = fs.readFileSync('tests/fixtures/stretchy-inline.css.map', 'utf8');
const cssResult = await readSources(cssMap, { verbose: true, preserve: false });
// Verbose: All sources were included in the sourcemap

console.log(Object.keys(cssResult));
// → ['stretchy.scss', '_svg.scss']
console.log(cssResult['stretchy.scss'].substring(0, 80));
// → '@import "svg";

// --- JS sourcemap with embedded sources ---
const jsMap = fs.readFileSync('tests/fixtures/stretchy-with-sources.min.js.map', 'utf8');
const jsResult = await readSources(jsMap, { verbose: true, preserve: false });

console.log(Object.keys(jsResult)); // → ['stretchy.js']
console.log(jsResult['stretchy.js'].length); // → 4521

// --- Webpack bundle map: partial sources (some not embedded) ---
const webpackMap = fs.readFileSync('tests/fixtures/main.931f74c5.js.map', 'utf8');
const webpackResult = await readSources(webpackMap, { verbose: false, preserve: false });
console.log(Object.keys(webpackResult)); // → ['index.js']
```

--------------------------------

### Programmatic API: handleInput and writeSources

Source: https://context7.com/paazmaya/shuji/llms.txt

Use the `handleInput` function as the main programmatic entry point. It returns an array of [filename, content] tuples. Use `writeSources` to write these to disk. Ensure correct imports and specify options like `verbose` and `preserve`.

```javascript
import handleInput from 'shuji';
import writeSources from 'shuji/lib/write-sources.js';
import path from 'node:path';

const OUTPUT_DIR = './recovered';

// --- Process a standalone .map file ---
const entries = await handleInput('dist/stretchy.min.js.map', {
  verbose: true,   // log progress to stdout
  preserve: false  // use basename only (no subdirectory structure)
});
// Verbose output: Processing file "dist/stretchy.min.js.map"
//                 All sources were included in the sourcemap

for (const [filename, content] of entries) {
  console.log(`Recovered: ${filename} (${content.length} chars)`);
  writeSources(filename, content, OUTPUT_DIR, { verbose: true });
}
// → Recovered: stretchy.js (4521 chars)
// → Writing to file "recovered/stretchy.js"
```

```javascript
// --- Process a JS file with an inline Base64 sourcemap ---
const inlineEntries = await handleInput('dist/stretchy-inline-sources.min.js', {
  verbose: false,
  preserve: false
});
// Returns same [filename, content] pairs extracted from the embedded map
```

```javascript
// --- Preserve original source tree (e.g. webpack bundle with deep paths) ---
const preservedEntries = await handleInput('dist/main.931f74c5.js.map', {
  verbose: true,
  preserve: true  // keys will be full paths like "src/components/App.js"
});
for (const [filename, content] of preservedEntries) {
  writeSources(filename, content, OUTPUT_DIR, { verbose: true });
}
```

```javascript
// --- Error case: file has no sourcemap reference ---
const empty = await handleInput('LICENSE', { verbose: false, preserve: false });
// stderr: Could not find sourceMap from "LICENSE"
console.log(empty); // → []
```

--------------------------------

### Shuji Command Line Options

Source: https://github.com/paazmaya/shuji/blob/master/README.md

The output of `shuji --help` displays all available command-line options for the utility.

```bash
shuji - Reverse engineering JavaScript and CSS sources from sourcemaps
Usage: shuji [options] <file|directory>

  -h, --help               Help and usage instructions
  -o, --output-dir String  Output directory - default: .
  -p, --preserve           Preserve sourcemap's original folder structure.
  -M, --match String       Regular expression for matching and filtering files -
                           default: \.map$
  -v, --verbose            Verbose output, will print which file is currently being
                           processed
  -V, --version            Version number

Version 0.8.0
```

--------------------------------

### Run Unit Tests

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Execute the project's unit tests using npm test. This typically involves the tape test runner.

```bash
npm test
```

--------------------------------

### handleInput(inputFilepath, options)

Source: https://context7.com/paazmaya/shuji/llms.txt

The main programmatic entry point for Shuji. This async function locates sourcemaps, extracts sources, and returns file entries. It accepts a path to a sourcemap file, a JS file with an inline sourcemap, or a JS file referencing an external sourcemap.

```APIDOC
## `handleInput(inputFilepath, options)` — `index.js` (default export)

**Main programmatic entry point: locate sourcemap, extract sources, return file entries**

`handleInput` is the top-level async function exposed by `index.js`. It accepts a path to a `.map` file, a JS file with an inline sourcemap, or a JS file referencing an external `.map`, then delegates to `findMap` and `readSources` to recover the original sources. It returns an array of `[filename, content]` tuples, or an empty array when the sourcemap cannot be found or contains no embedded sources.

```js
import handleInput from 'shuji';
import writeSources from 'shuji/lib/write-sources.js';
import path from 'node:path';

const OUTPUT_DIR = './recovered';

// --- Process a standalone .map file ---
const entries = await handleInput('dist/stretchy.min.js.map', {
  verbose: true,   // log progress to stdout
  preserve: false  // use basename only (no subdirectory structure)
});
// Verbose output: Processing file "dist/stretchy.min.js.map"
//                 All sources were included in the sourcemap

for (const [filename, content] of entries) {
  console.log(`Recovered: ${filename} (${content.length} chars)`);
  writeSources(filename, content, OUTPUT_DIR, { verbose: true });
}
// → Recovered: stretchy.js (4521 chars)
// → Writing to file "recovered/stretchy.js"

// --- Process a JS file with an inline Base64 sourcemap ---
const inlineEntries = await handleInput('dist/stretchy-inline-sources.min.js', {
  verbose: false,
  preserve: false
});
// Returns same [filename, content] pairs extracted from the embedded map

// --- Preserve original source tree (e.g. webpack bundle with deep paths) ---
const preservedEntries = await handleInput('dist/main.931f74c5.js.map', {
  verbose: true,
  preserve: true  // keys will be full paths like "src/components/App.js"
});
for (const [filename, content] of preservedEntries) {
  writeSources(filename, content, OUTPUT_DIR, { verbose: true });
}

// --- Error case: file has no sourcemap reference ---
const empty = await handleInput('LICENSE', { verbose: false, preserve: false });
// stderr: Could not find sourceMap from "LICENSE"
console.log(empty); // → []
```
```

--------------------------------

### Generate Minified JS with Source Map (Include Sources)

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Use UglifyJS to create a minified JavaScript file and include original sources in the sourcemap. The sourcemap file is then renamed.

```bash
uglifyjs stretchy.js --compress --mangle \
 --output stretchy.min.js --source-map includeSources
mv stretchy.min.js.map stretchy-with-sources.min.js.map
```

--------------------------------

### writeSources(filename, content, outdir, options)

Source: https://context7.com/paazmaya/shuji/llms.txt

Writes a single recovered source file to disk, ensuring the output directory exists and skipping the write if the file already exists. It also handles stripping query strings from filenames.

```APIDOC
## `writeSources(filename, content, outdir, options)`

### Description
Write a single recovered source file to disk, skipping existing files. `writeSources` takes a recovered source file name, its content string, an output directory, and an options object. It strips any query-string suffix from the file name (common in webpack-generated maps), ensures the output directory exists using `fs-extra`, and writes the file as UTF-8. If the target file already exists it logs an error and skips — it never overwrites. The function uses `fs-extra`'s `ensureDirSync` so nested output paths are created automatically.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **filename** (string) - The name of the source file to write. Query string suffixes will be stripped.
- **content** (string) - The content of the source file.
- **outdir** (string) - The output directory where the file will be written.
- **options** (object) - Optional configuration object.
  - **verbose** (boolean) - Optional - If true, logs verbose output.

### Request Example
```javascript
import writeSources from 'shuji/lib/write-sources.js';

writeSources('stretchy.js', '// original source...', './output', { verbose: true });
writeSources('app.js?abc123', '/* app source */', './output', { verbose: true });
writeSources('src/components/Button.js', '// Button', './output', { verbose: true });
```

### Response
#### Success Response (200)
- **undefined** - This function does not return a meaningful value.
```

--------------------------------

### Compile SCSS to CSS

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Compile a SCSS file to a CSS file using the sass command.

```bash
sass stretchy.scss:stretchy.css
```

--------------------------------

### Write Source File to Disk

Source: https://context7.com/paazmaya/shuji/llms.txt

Writes a single source file to a specified output directory. It automatically creates nested directories and skips writing if the file already exists.

```javascript
import writeSources from 'shuji/lib/write-sources.js';
import fs from 'node:fs';

const opts = { verbose: true };

// --- Write a recovered source to a target directory ---
writeSources('stretchy.js', '// original source...', './output', opts);
// Verbose output: Writing to file "output/stretchy.js"
// Creates: ./output/stretchy.js

// --- File name with query string (webpack asset hash) ---
writeSources('app.js?abc123', '/* app source */', './output', opts);
// Query string stripped → writes to: ./output/app.js
// Verbose output: Writing to file "output/app.js"

// --- Nested path auto-creates subdirectories ---
writeSources('src/components/Button.js', '// Button', './output', opts);
// Verbose output: Writing to file "output/src/components/Button.js"
// Automatically creates ./output/src/components/ if it does not exist

// --- Duplicate protection: existing file is skipped ---
fs.mkdirSync('./output', { recursive: true });
fs.writeFileSync('./output/stretchy.js', 'existing content', 'utf8');

writeSources('stretchy.js', 'new content', './output', opts);
// stderr: File "output/stretchy.js" already exists, skipping!
// Original file is preserved unchanged

// --- Returns undefined (no meaningful return value) ---
const result = writeSources('foo.js', '// foo', './output', { verbose: false });
console.log(result); // → undefined
```

--------------------------------

### Generate Minified JS with External Source Map

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Use UglifyJS to create a minified JavaScript file with an external sourcemap file specified by URL.

```bash
uglifyjs stretchy.js --compress --mangle \
 --output stretchy.min.js --source-map "url=stretchy.min.js.map"
```

--------------------------------

### findFiles(filepath, matcher)

Source: https://context7.com/paazmaya/shuji/llms.txt

Recursively discovers files under a given path whose names match a provided regular expression. It can process both directories (recursing into subdirectories) and individual files.

```APIDOC
## `findFiles(filepath, matcher)`

### Description
Recursively discover files under a path whose names match a regular expression.

`findFiles` accepts a file or directory path and a `RegExp` object. When given a directory, it recurses into all subdirectories and collects every file whose path matches the expression. When given a file path, it returns that file if it matches, or an empty array otherwise. Stat errors (non-existent paths) are caught and logged; the function always returns an array.

### Parameters
#### Path Parameters
- **filepath** (string) - Required - The starting path (file or directory) to search within.
- **matcher** (RegExp) - Required - The regular expression to match file paths against.

### Returns
- (Array<string>) - An array of file paths that match the provided matcher.

### Example
```javascript
import findFiles from 'shuji/lib/find-files.js';

// Find all .map files in a build directory
const mapFiles = findFiles('dist', /\.map$/u);
console.log(mapFiles);
// → ['dist/stretchy.min.js.map', 'dist/stretchy.css.map', 'dist/main.931f74c5.js.map']
```
```

--------------------------------

### Generate Minified JS with Inline Source Map

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Use UglifyJS to create a minified JavaScript file with the source map content embedded directly within the JavaScript file.

```bash
uglifyjs stretchy.js --compress --mangle \
 --output stretchy.min.js --source-map "url=inline"
mv stretchy.min.js stretchy-inline-sources.min.js
```

--------------------------------

### Run Linter

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Execute the ESLint linter to check for JavaScript code style errors. Ensure no errors appear after file changes.

```bash
npm run lint
```

--------------------------------

### readSources(input, options)

Source: https://context7.com/paazmaya/shuji/llms.txt

Parses a sourcemap JSON string and returns a mapping of filenames to their source content. It handles embedded sources and can preserve full paths or use basenames as keys.

```APIDOC
## `readSources(input, options)`

### Description
Parse a sourcemap JSON string and return a filename → source-content mapping. `readSources` is an async function that wraps the `source-map` library's `SourceMapConsumer`. It iterates over all sources listed in the map, retrieves their embedded content, sanitizes the file name (stripping unsafe characters), and returns a plain object keyed by cleaned file name. When `options.preserve` is `true`, the full relative source path is used as the key instead of just the basename.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `options` object
- **verbose** (boolean) - Optional - If true, logs verbose output.
- **preserve** (boolean) - Optional - If true, preserves the full relative source path as the key instead of just the basename.

### Request Example
```javascript
import fs from 'node:fs';
import readSources from 'shuji/lib/read-sources.js';

const cssMap = fs.readFileSync('tests/fixtures/stretchy-inline.css.map', 'utf8');
const cssResult = await readSources(cssMap, { verbose: true, preserve: false });
console.log(Object.keys(cssResult));
console.log(cssResult['stretchy.scss'].substring(0, 80));
```

### Response
#### Success Response (200)
- **object** - An object where keys are source filenames and values are their content strings.
```

--------------------------------

### Run Code Coverage

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Generate code coverage reports by running `npm run coverage` after executing `npm test`. Ensure coverage remains above 90%.

```bash
npm run coverage
```

--------------------------------

### findMap(filepath, options?)

Source: https://context7.com/paazmaya/shuji/llms.txt

Reads and returns raw sourcemap JSON from a .map file, an inline JS/CSS sourcemap, or a file-referenced map. It intelligently handles different input types to locate and parse sourcemap data.

```APIDOC
## `findMap(filepath, options?)`

### Description
Read and return raw sourcemap JSON from a .map file, inline JS/CSS, or file-referenced map.

`findMap` is the sourcemap locator. It handles three input types: (1) a `.map` file — returned as-is; (2) a `.js` or `.css` file with an inline Base64 `sourceMappingURL` — decoded and returned; (3) a `.js` or `.css` file with a file-reference `sourceMappingURL` — the referenced `.map` is read from the same directory. Returns the raw sourcemap JSON string, or `false` when none can be found.

### Parameters
#### Path Parameters
- **filepath** (string) - Required - The path to the file to process.
#### Query Parameters
- **options** (object) - Optional - Configuration options.
  - **verbose** (boolean) - Optional - If true, logs additional information to stderr during processing.

### Returns
- (string | false) - The raw sourcemap JSON string if found, otherwise `false`.

### Example
```javascript
import findMap from 'shuji/lib/find-map.js';

const opts = { verbose: true };

// 1. Standalone .map file — returned directly
const mapFromFile = findMap('tests/fixtures/stretchy.min.js.map', opts);
console.log(typeof mapFromFile); // → 'string'
const parsed = JSON.parse(mapFromFile);
console.log(parsed.sources); // → ['stretchy.js']

// 2. Minified JS with external .map reference
const mapFromJs = findMap('tests/fixtures/stretchy.min.js', opts);
console.log(mapFromJs.length); // → 3286

// 3. Minified JS with inline Base64 sourcemap
const mapFromInlineJs = findMap('tests/fixtures/stretchy-inline-sources.min.js', opts);
console.log(mapFromInlineJs.length); // → 3269

// 4. CSS file with inline sourcemap
const mapFromInlineCss = findMap('tests/fixtures/stretchy-inline.css');
console.log(mapFromInlineCss.length); // → 1243

// 5. Non-map, non-code file — returns false
const result = findMap('LICENSE', opts);
console.log(result); // → false
```
```

--------------------------------

### Compile SCSS to CSS with Embedded Source Map

Source: https://github.com/paazmaya/shuji/blob/master/README.md

Compile a SCSS file to a CSS file and embed the source map directly within the CSS file.

```bash
sass stretchy.scss:stretchy-inline.css --embed-source-map
```

--------------------------------

### Read Sources with Preserve Paths

Source: https://context7.com/paazmaya/shuji/llms.txt

Parses a CSS sourcemap and preserves the full relative source paths as keys when `preserve: true`.

```javascript
// --- preserve: true — keep full paths as keys ---
const preserved = await readSources(cssMap, { verbose: false, preserve: true });
console.log(Object.keys(preserved));
// → ['stretchy.scss', '_svg.scss']  (paths as stored in the map)
```

--------------------------------

### Recursively Find Files Matching a Pattern with `findFiles`

Source: https://context7.com/paazmaya/shuji/llms.txt

Use `findFiles` to search for files within a directory or a specific file path that match a given regular expression. It handles recursion and logs stat errors internally, always returning an array.

```javascript
import findFiles from 'shuji/lib/find-files.js';

// Find all .map files in a build directory
const mapFiles = findFiles('dist', /\.map$/u);
console.log(mapFiles);
// → ['dist/stretchy.min.js.map', 'dist/stretchy.css.map', 'dist/main.931f74c5.js.map']

// Find only minified JS files
const minFiles = findFiles('dist', /\.min\.js$/u);
console.log(minFiles.length); // → 3

// Target a single file directly
const single = findFiles('dist/app.min.js.map', /\.map$/u);
console.log(single); // → ['dist/app.min.js.map']

// Non-existent path returns empty array (logs error internally)
const none = findFiles('does/not/exist', /.*/u);
console.log(none); // → []

// Use a custom pattern to match webpack-hashed bundles
const hashed = findFiles('build', /\.[a-f0-9]{8}\.js\.map$/u);
// → ['build/main.931f74c5.js.map', 'build/vendor.3d48a9a2.js.map']
```

--------------------------------

### Extract Sourcemap JSON with `findMap`

Source: https://context7.com/paazmaya/shuji/llms.txt

Employ `findMap` to read sourcemap JSON from `.map` files, or decode it from inline Base64 strings within `.js` or `.css` files. It also resolves external `sourceMappingURL` references.

```javascript
import findMap from 'shuji/lib/find-map.js';

const opts = { verbose: true };

// 1. Standalone .map file — returned directly
const mapFromFile = findMap('tests/fixtures/stretchy.min.js.map', opts);
console.log(typeof mapFromFile); // → 'string'
console.log(mapFromFile.length); // → 3286
const parsed = JSON.parse(mapFromFile);
console.log(parsed.sources); // → ['stretchy.js']

// 2. Minified JS with external .map reference (sourceMappingURL=stretchy.min.js.map)
// Verbose output: Input file "..." points to "stretchy.min.js.map"
const mapFromJs = findMap('tests/fixtures/stretchy.min.js', opts);
console.log(mapFromJs.length); // → 3286  (same content as the .map file)

// 3. Minified JS with inline Base64 sourcemap
// Verbose output: Input file "..." contains Base64 of N length
const mapFromInlineJs = findMap('tests/fixtures/stretchy-inline-sources.min.js', opts);
console.log(mapFromInlineJs.length); // → 3269

// 4. CSS file with inline sourcemap (URL-encoded or Base64)
const mapFromInlineCss = findMap('tests/fixtures/stretchy-inline.css');
console.log(mapFromInlineCss.length); // → 1243

// 5. Non-map, non-code file — returns false
const result = findMap('LICENSE', opts);
// stderr: Input file "LICENSE" was not a map nor a code file
console.log(result); // → false
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.