Node ESM Migration skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Node ESM Migration"
  short_description: "From require to import without breaking consumers"
  default_prompt: "$node-esm-migration Convert this Node library from CommonJS to ESM-only"

#!/usr/bin/env node
// Checks a package's package.json "exports" map for common ESM/CJS mistakes.
//
// Usage: node check_exports.mjs [packageDir] [--load]
//
// Checks (errors exit 1, warnings only print):
//   - every target file in "exports" (and "main"/"module"/"types") exists
//   - "types" is the first key in any condition object that has it
//   - "default" is the last key in any condition object that has it
//   - a "require" target is not ESM by extension/type (.mjs, or .js in a "type":"module" package)
//   - an "import" target is not a .cjs file
//   - a ".d.ts" types file is not shared by both import and require branches (warn)
// With --load, each import target is loaded with import() and each require target with
// require(), proving the files parse and evaluate in this Node version. Only use --load on
// code you trust: it executes the package.
import { existsSync, readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { join, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';

const args = process.argv.slice(2);
const load = args.includes('--load');
const dir = resolve(args.find((a) => !a.startsWith('--')) ?? '.');
const pkgPath = join(dir, 'package.json');
if (!existsSync(pkgPath)) {
  console.error(`no package.json in ${dir}`);
  process.exit(2);
}
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
const isModule = pkg.type === 'module';
const errors = [];
const warnings = [];
const targets = []; // { subpath, conditions: string[], file }

function walk(node, subpath, conds) {
  if (node === null) return; // explicit block of a subpath
  if (typeof node === 'string') {
    targets.push({ subpath, conditions: conds, file: node });
    return;
  }
  if (Array.isArray(node)) {
    node.forEach((n) => walk(n, subpath, conds));
    return;
  }
  const keys = Object.keys(node);
  const isSubpathMap = keys.every((k) => k.startsWith('.'));
  if (isSubpathMap) {
    for (const k of keys) walk(node[k], k, []);
    return;
  }
  if (keys.includes('types') && keys[0] !== 'types') {
    errors.push(`${subpath} [${conds.join(' > ') || 'root'}]: "types" must be the first condition (found order: ${keys.join(', ')})`);
  }
  if (keys.includes('default') && keys.at(-1) !== 'default') {
    errors.push(`${subpath} [${conds.join(' > ') || 'root'}]: "default" must be the last condition`);
  }
  for (const k of keys) walk(node[k], subpath, [...conds, k]);
}

if (pkg.exports === undefined) {
  warnings.push('no "exports" field: every file in the package is importable and no conditions apply');
} else {
  walk(pkg.exports, '.', []);
}
for (const field of ['main', 'module', 'types', 'typings']) {
  if (typeof pkg[field] === 'string') targets.push({ subpath: `(${field})`, conditions: [field], file: pkg[field] });
}

const isTypes = (t) => t.conditions.includes('types') || t.conditions.includes('typings') || /\.d\.[cm]?ts$/.test(t.file);
const typesByFile = new Map();

for (const t of targets) {
  const label = `${t.subpath} [${t.conditions.join(' > ') || 'default'}] -> ${t.file}`;
  if (t.file.includes('*')) {
    warnings.push(`${label}: pattern export, files not checked individually`);
    continue;
  }
  if (!t.file.startsWith('./') && t.subpath.startsWith('.')) {
    errors.push(`${label}: export targets must start with "./"`);
  }
  const abs = join(dir, t.file);
  if (!existsSync(abs)) {
    errors.push(`${label}: file does not exist (build first?)`);
    continue;
  }
  if (isTypes(t)) {
    const branch = t.conditions.includes('require') ? 'require' : t.conditions.includes('import') ? 'import' : 'other';
    const set = typesByFile.get(t.file) ?? new Set();
    set.add(branch);
    typesByFile.set(t.file, set);
    continue;
  }
  const esmFile = t.file.endsWith('.mjs') || (t.file.endsWith('.js') && isModule);
  const cjsFile = t.file.endsWith('.cjs') || (t.file.endsWith('.js') && !isModule);
  if (t.conditions.includes('require') && esmFile) {
    warnings.push(`${label}: "require" points at an ES module; works only on Node 20.19+/22.12+ and fails if it uses top-level await`);
  }
  if (t.conditions.includes('import') && cjsFile) {
    warnings.push(`${label}: "import" points at a CommonJS file; named imports depend on cjs-module-lexer detection`);
  }
}
for (const [file, branches] of typesByFile) {
  if (branches.has('import') && branches.has('require') && !/\.d\.[cm]ts$/.test(file)) {
    warnings.push(`types file ${file} is shared by import and require branches; ship .d.cts for CJS (types will "masquerade")`);
  }
}

if (load && errors.length === 0) {
  const req = createRequire(pkgPath);
  for (const t of targets) {
    if (isTypes(t) || t.file.includes('*') || !/\.[cm]?js$/.test(t.file)) continue;
    const abs = join(dir, t.file);
    try {
      if (t.conditions.includes('require')) req(abs);
      else await import(pathToFileURL(abs).href);
      console.log(`loaded   ${t.subpath} [${t.conditions.join(' > ') || 'default'}]`);
    } catch (err) {
      errors.push(`${t.subpath} [${t.conditions.join(' > ')}]: failed to load: ${err.code ?? ''} ${err.message.split('\n')[0]}`);
    }
  }
}

console.log(`package ${pkg.name ?? '(unnamed)'} type=${pkg.type ?? 'commonjs'} targets=${targets.length}`);
for (const w of warnings) console.log(`warning  ${w}`);
for (const e of errors) console.log(`error    ${e}`);
console.log(`${errors.length} error(s), ${warnings.length} warning(s)`);
process.exit(errors.length ? 1 : 0);