charlie: ESM upgrade playbook

[shellscape]

Using #1926 and #1925 as a guide, write a playbook for charlie in .charlie which describes the steps necessary to upgrade a plugin package in this repository to ESM-only. The scope of the playbook should not exceed or be outside a plugin package within the packages/ directory.

[charliecreates]

Expand this to see my work.

• Reviewed packages/alias/package.json as a canonical ESM-only example: type: "module", exports: { types: "./dist/index.d.ts", import: "./dist/index.js" }, top-level types, engines.node: ">=20.19.0", peerDependencies.rollup: "^4.0.0", and no main/CJS exports.
• Examined packages/alias/tsconfig.json and .config/tsconfig.base.json to extract TS requirements: module: "esnext", moduleResolution: "bundler", target: "ES2022", with package overrides enabling noEmit: false, declaration: true, rootDir: "src", outDir: "dist".
• Noted standard scripts and publish files to mirror: prebuild (clean dist), build (tsc --project tsconfig.json), prepare (guard dist), and files publishing dist with !dist/**/*.map.
• Cross-referenced #1926 and #1925 to capture ESM-only rules: remove CJS entry points and require usage, replace __dirname/__filename with import.meta.url + fileURLToPath, constrain exports to import and types, and set the Node floor in engines.node.
• Assembled a concise per-plugin checklist for the playbook: update package.json (type, exports, types, engines.node, peerDependencies.rollup), align TS config to the base, ensure tests run via ESM-friendly vitest (.config/vitest.config.mts), and audit src/ to use ESM APIs.
• Parsed #1925 to extract in-package-only steps and excluded repo-root setup; emphasized linking packages/<name>/tsconfig.json to .config/tsconfig.plugin.json and pointing packages/<name>/rollup.config.mjs to .config/rollup-plugin.mjs.
• Added concrete snippets to the playbook for replacing __dirname/__filename with fileURLToPath(new URL('.', import.meta.url)) and for package.json exports ({ "types": "./dist/index.d.ts", "import": "./dist/index.js" }).
• Drafted .charlie/esm-upgrade-playbook.md with sections: package.json, TS config, Rollup config, source ESM changes, test migration to vitest (keep test/node_modules/current-package symlink), and verification (run tsc -p tsconfig.json, smoke-import dist/index.js, and run vitest)—all scoped to packages/<plugin>.

[charliecreates]

Opened PR #1934 adding a scoped playbook under .charlie/playbooks to guide upgrading a single plugin in packages/ to ESM‑only. It mirrors the alias migration and keeps all changes strictly within the package directory. The PR will close this issue on merge.

Changes

• New file: .charlie/playbooks/upgrade-plugin-to-esm-only.md
  • Package‑only scope: no edits outside packages/
  • Steps cover:
    • package.json: set type: module; ESM‑only exports; engines.node >= 20.19.0; peer rollup >= 4
    • Build: tsc‑only emit to dist (JS + d.ts + maps); keep Rollup only if needed for tests/examples
    • tsconfig: extend ../../.config/tsconfig.base.json; emit declarations to dist
    • Source: convert to ESM; use node: specifiers; inline/export public types
    • Tests: remove CJS branches; ensure bundles are closed in tests
    • Verify + Rollback commands
  • References: PR feat(alias)!: ESM only. Update Node and Rollup minimum versions #1926 and Issue charlie: ESM update of alias package #1925 for the alias migration details

Verification

• Non‑code change; ran a self‑review locally (no findings).
• Branch pushed: ai-1933-charlie-esm-upgrade-playbook
• Assignee/reviewer on PR: @shellscape