managing-apps/scripts/README.md

# Scripts

This directory contains utility scripts for the project.

## Add JS Extensions Script

The `add-js-extensions.mjs` script adds `.js` extensions to import statements in JavaScript and TypeScript files, and also adds the required JSON import assertions.

### Why This Script?

When working with ES Modules in Node.js:
1. Imports of local files require explicit file extensions
2. JSON imports require an `assert { type: 'json' }` assertion

This script automates both processes to ensure your code is ESM-compatible.

### Usage

Run the script with npm:

```bash
# Fix imports in the src directory (default)
npm run fix-imports

# Fix imports in a specific directory
npm run fix-imports-dir -- path/to/directory
```

Or run the script directly:

```bash
# Fix imports in the src directory (default)
node scripts/add-js-extensions.mjs

# Fix imports in a specific directory
node scripts/add-js-extensions.mjs path/to/directory
```

### What This Script Does

1. Recursively scans all JavaScript and TypeScript files in the specified directory
2. Identifies import statements with relative paths (starting with `./` or `../`) that don't have extensions and adds `.js` extensions
3. Identifies JSON imports that are missing the required assertion and adds `assert { type: 'json' }`
4. Provides a summary of files modified and any errors encountered

### Examples

Before:
```javascript
import { bigMath } from "./bigmath";
import data from "./data.json";
```

After:
```javascript
import { bigMath } from "./bigmath.js";
import data from "./data.json" assert { type: 'json' };
```

### Important Notes

- The script only modifies imports with relative paths (starting with `./` or `../`)
- It skips imports that already have a file extension (except for JSON files)
- It adds `.js` extensions to extensionless imports
- It adds `assert { type: 'json' }` to JSON imports that don't already have it
- It handles regular imports, dynamic imports, and exports

## Remove JSON Assertions Script

The `remove-json-assertions.mjs` script removes `assert { type: 'json' }` assertions from JSON imports.

### Why This Script?

Different JavaScript environments have different requirements for JSON imports:
1. Some newer environments require the `assert { type: 'json' }` assertion
2. Others don't support or need these assertions

This script removes these assertions to improve compatibility with environments that don't need them.

### Usage

Run the script with npm:

```bash
# Remove JSON assertions
npm run remove-json-assertions

# Run both import fixes and assertion removal in one command
npm run prepare-code
```

Or run the script directly:

```bash
node scripts/remove-json-assertions.mjs
```

### What This Script Does

1. Recursively scans all JavaScript and TypeScript files in the project
2. Identifies JSON imports with `assert { type: 'json' }` assertions
3. Removes the assertions while preserving the import statements
4. Provides a summary of files modified

### Examples

Before:
```javascript
import data from "./data.json" assert { type: 'json' };
```

After:
```javascript
import data from "./data.json";
```

### Important Notes

- The script only modifies JSON imports with assertions
- It preserves all other import statements
- It works in conjunction with the add-js-extensions script
- These scripts can be run in sequence to first fix imports then remove assertions

## Update JSON Imports Script

The `update-json-imports.mjs` script updates JSON imports to use the modern `with { type: "json" }` syntax.

### Why This Script?

Different JavaScript environments have different requirements for JSON imports:
1. Older environments used `assert { type: 'json' }` for JSON imports
2. Modern JavaScript environments now use the `with { type: "json" }` syntax

This script updates your codebase to use the newer, more standardized approach.

### Usage

Run the script with npm:

```bash
# Update JSON import syntax
npm run update-json-imports

# Run both import fixing and JSON import updating in one command
npm run prepare-code
```

Or run the script directly:

```bash
node scripts/update-json-imports.mjs
```

### What This Script Does

1. Recursively scans all JavaScript and TypeScript files in the project
2. Identifies JSON imports using either:
   - The older `assert { type: 'json' }` syntax
   - No type assertion at all
   - Erroneous dual syntax (`assert { type: 'json' } with { type: "json" }`)
3. Updates them to use the modern `with { type: "json" }` syntax
4. Provides a summary of files modified

### Examples

Before (old assert syntax):
```javascript
import data from "./data.json" assert { type: 'json' };
```

Before (no type assertion):
```javascript
import data from "./data.json";
```

Before (erroneous dual syntax):
```javascript
import data from "./data.json" assert { type: 'json' } with { type: "json" };
```

After (in all cases):
```javascript
import data from "./data.json" with { type: "json" };
```

### Important Notes

- The script updates all JSON imports to use the modern syntax
- It properly fixes cases where both old and new syntax are present
- It preserves all other import statements
- Files with properly formatted imports are not modified