netsuite-suitescript-upgrade

What this skill does

# NetSuite SuiteScript Upgrade Skill

**Created by:** Oracle NetSuite

## Description

Complete SuiteScript 1.0, 2.0, and 2.x to 2.1 migration assistant with **4 operating modes**: analyze, convert, explain, and validate. SuiteScript 2.1 is always the target version. This skill provides:

- **Analyze Mode**: Scan SS1.0, SS2.0, and SS2.x scripts and produce migration complexity reports
- **Convert Mode**: Transform SS1.0, SS2.0, and SS2.x scripts to SS2.1 with full API mapping and JavaScript modernization
- **Explain Mode**: Deep dive into specific API mappings, objects, or migration concepts for a full SS2.1 conversion
- **Validate Mode**: Check converted scripts for leftover 1.0 patterns, non-2.1 version tags, and common conversion bugs

Backed by comprehensive reference data:
- **125+ API function mappings** (nlapi\* → N/\* modules) across 26 modules
- **34 object conversions** (nlobj\* → SS2.1 classes) with 331 method mappings
- **13 unmapped APIs** with native JavaScript or alternative workarounds
- **All script type entry point changes** (User Event, Client, Suitelet, RESTlet, Scheduled, Map/Reduce, etc.)
- **16 categories of breaking behavioral changes** with before/after examples

## How to Use This Skill

### Manual Invocation (Slash Command)

Invoke this skill at any time by typing:
```
/netsuite-suitescript-upgrade
```

Or use specific mode commands:
```
/netsuite-suitescript-upgrade analyze [file-path]     # Assess migration complexity for SS1.0/2.0/2.x
/netsuite-suitescript-upgrade convert [file-path]     # Convert SS1.0/2.0/2.x → SS2.1
/netsuite-suitescript-upgrade explain [api-or-concept] # Deep dive into a mapping
/netsuite-suitescript-upgrade validate [file-path]    # Check converted script
```

### Automatic Activation (Recommended for Migration Projects)

For projects undergoing SuiteScript migration, add this skill to your project's `.claude/settings.local.json`:

```json
{
  "permissions": {
    "allow": [
      "Skill(netsuite-suitescript-upgrade)",
      "Skill(netsuite-sdf-leading-practices)",
      "Skill(netsuite-suitescript-reference)"
    ]
  }
}
```

With all three skills enabled, Claude will:
- Detect SS1.0, SS2.0, and SS2.x scripts automatically and offer migration assistance
- Convert APIs using the complete mapping reference
- Generate proper deployment XML via the leading-practices skill
- Look up correct field IDs via the suitescript-reference skill

---

## When to Use This Skill

### Proactive Invocation (Recommended)

This skill should be invoked automatically when:
- User opens or references a SuiteScript 1.0 file (detected by `nlapi*` calls, no `define()`)
- User opens or references a SuiteScript 2.0 or ambiguous 2.x file that needs normalization to SuiteScript 2.1
- User asks about migrating, upgrading, or converting SuiteScript
- User encounters `nlapi*` or `nlobj*` functions and asks what the SS2.1 equivalent is
- User is working on a project with mixed SS1.0, SS2.0, SS2.x, and SS2.1 scripts

### Manual Invocation

- Commands: "analyze this script", "convert to 2.1", "what's the 2.1 version of nlapiSearchRecord?"
- Questions: "How do I migrate this User Event?", "What module replaces nlapi functions?"
- Validation: "Check my converted script", "Did I miss any 1.0 patterns?"

---

## SS1.0 Detection Logic

### How to Identify a SuiteScript 1.0 Script

A file is a SuiteScript 1.0 script if it matches **any** of these patterns:

| Indicator | Pattern | Confidence |
|-----------|---------|------------|
| **Explicit version tag** | `@NApiVersion 1.0` or `@NApiVersion "1.0"` in JSDoc | Definitive |
| **No AMD wrapper** | No `define()` or `require()` call | Strong |
| **Global nlapi\* calls** | `nlapiLoadRecord`, `nlapiSearchRecord`, `nlapiSubmitField`, etc. | Strong |
| **Global nlobj\* constructors** | `new nlobjSearchFilter`, `new nlobjSearchColumn` | Strong |
| **No @NScriptType** | Entry points use function naming conventions, not annotation | Moderate |
| **Entry point as bare function** | `function beforeLoad(type, form, request)` at global scope | Moderate |
| **1-based sublist indexing** | Loop `for (var i = 1; i <= count; i++)` with line item ops | Moderate |
| **var keyword only** | No `const`/`let` usage (ES3 style) | Weak (could be SS2.0) |

### Version Classification

| Version | Characteristics |
|---------|----------------|
| **SS1.0** | Global `nlapi*`/`nlobj*`, no `define()`, no `@NScriptType` |
| **SS2.0** | `define()` wrapper, `@NApiVersion 2.0`, uses `var` (no arrow functions, no template literals) |
| **SS2.1** | `define()` wrapper, `@NApiVersion 2.1`, modern JS (const/let, arrow functions, template literals, async/await) |

### Detection Algorithm

```
1. Scan for @NApiVersion annotation
   → If "1.0": CONFIRMED SS1.0
   → If "2.0" or "2.x": SS2.0/SS2.x input; upgrade to SS2.1 is required
   → If "2.1": Already SS2.1

2. If no @NApiVersion found:
   → Scan for define() or require() wrapper
     → If absent: Likely SS1.0
   → Scan for nlapi*/nlobj* function calls
     → If present: CONFIRMED SS1.0
   → Scan for @NScriptType annotation
     → If absent: Likely SS1.0

3. Count indicators to determine confidence level
```

---

## Usage Syntax

```
/netsuite-suitescript-upgrade [mode] [target] [options]

Modes:
  analyze   - Assess a SS1.0, SS2.0, or SS2.x script's migration complexity
  convert   - Convert a SS1.0, SS2.0, or SS2.x script to SS2.1
  explain   - Explain a specific API mapping or migration concept
  validate  - Check a converted SS2.1 script for leftover issues

Target:
  - File path for analyze/convert/validate mode
  - API name, object name, or concept for explain mode

Options:
  --dry-run    Show what would change without writing files (convert mode)
  --annotated  Include numbered change annotations in output (convert mode)
  --verbose    Include detailed migration notes in reports (all modes)
```

**Examples:**
```
/netsuite-suitescript-upgrade analyze /SuiteScripts/my_ue.js
/netsuite-suitescript-upgrade convert /SuiteScripts/my_ue.js
/netsuite-suitescript-upgrade convert /SuiteScripts/my_ue.js --annotated
/netsuite-suitescript-upgrade explain nlapiSearchRecord
/netsuite-suitescript-upgrade explain nlobjRecord
/netsuite-suitescript-upgrade explain indexing
/netsuite-suitescript-upgrade explain error-handling
/netsuite-suitescript-upgrade validate /SuiteScripts/my_ue_v2.js
```

---

## Core Functionality

### 1. Analyze Mode (`analyze`)

Scan a SuiteScript 1.0 file and produce a migration complexity report.

#### Process

1. **Read the file** and confirm it is SS1.0 (using detection logic above)
2. **Detect script type** from entry point function names or JSDoc annotations
3. **Scan for all `nlapi*` function calls**; categorize by module
4. **Scan for all `nlobj*` object usage**; categorize by class
5. **Check for unmapped APIs** — cross-reference with `references/unmapped-apis.md`
6. **Check for breaking change patterns**; 1-based indexing, positional params, recovery points, etc.
7. **Calculate complexity score** using the scoring matrix
8. **Produce the migration report**

#### Complexity Scoring Matrix

| Factor | Low (1 pt) | Medium (2 pts) | High (3 pts) |
|--------|-----------|----------------|--------------|
| **Line count** | < 100 lines | 100–500 lines | 500+ lines |
| **Unique nlapi\* calls** | < 10 | 10–30 | 30+ |
| **Subrecord usage** | None | Read-only | Create/edit |
| **Date/time with timezone** | None | Body fields | Sublist date fields |
| **Recovery points** | None | `nlapiSetRecoveryPoint` | Recovery + Yield |
| **Custom module includes** | None | 1–2 includes | 3+ includes |
| **Sublist operations** | None | Read-only | Dynamic line manipulation |

**Score interpretation:**
- **7–10 points**: **Low** complexity; straightforward conversion
- **11–15 points**: **Medium** complexity; careful testing needed, some architectural decisions
- **16–21 points**: **High** complexity; plan a staged full conversion to SS2.1
- **21+ with unmapped APIs**: **Critical**;