@adaptabletools/adaptable-mcp 0.1.0-canary.1 → 0.1.0-canary.2

package/dist/skills/adaptable-upgrade/references/apply-order.md

@@ -0,0 +1,171 @@
+---
+sources:
+  docs: [version-240-release-note, dev-guide-adaptable-state-migrating-state, dev-guide-adaptable-state-persistence, handbook-team-sharing-configuring, getting-started-installation]
+  paths: [packages/adaptable-mcp/src/core/migrate/state.ts, packages/adaptable-mcp/src/core/aql/migrate.ts, packages/adaptable/src/setupDevTools.ts]
+---
+
+# Apply order
+
+Apply mode runs in a fresh session from `ADAPTABLE_UPGRADE_SCOPE.md` and
+`ADAPTABLE_UPGRADE_CHANGES.md`. The order matters: packages first so the
+types and the engine are the target's; State before Options because Options
+records reference State shapes; validation after every rewrite, not at the
+end. Record progress in the conversation as each step closes — the plan
+files are not edited in apply mode.
+
+## 1. Packages
+
+1. **AG Grid**, per SCOPE's `## AG Grid plan`:
+   - *ag-update*: apply `AG_UPDATE_*.md` first, with that skill. AdapTable
+     work waits until AG Grid builds.
+   - *bump only*: set every `ag-grid-*` package (and `ag-charts-*` when
+     present) to the version SCOPE names, same version for all of them.
+     AG Grid's own breaking changes are the user's; name the guide, do not
+     run AG Grid's codemod from here.
+   - *already handled*: check `package.json` carries the pairing; if it does
+     not, stop and tell the user — nothing below works against a mismatched
+     AG Grid.
+2. **AdapTable**: every `@adaptabletools/*` package in each project to the
+   same target version — the core package and the framework wrapper
+   (`compat --adaptable <target> --framework <fw>` names it) and any plugin
+   package. A pre-release target is installed by dist-tag (`@canary`); a
+   released target by its `<major>.x` range. One version for all of them;
+   version skew between the core and a wrapper is a `check setup` finding.
+3. Install with the project's package manager; read the peer-dependency
+   output. A missing-peer report is the only reason to add a package the
+   plan does not name.
+4. Where the target's Packages & CSS records say so: the stylesheet import
+   path, the Angular wrapper's version, bundler or sandbox resolver settings.
+
+Do not type-check yet — the source still speaks the former major.
+
+## 2. `BREAKING` records, file by file
+
+Work the plan top to bottom: transition by transition, area by area,
+record by record, match by match. For each match read the matched line
+(and only what is needed around it), apply the record's `after` form with
+its note, and move to the next. A match that is a comment, a string in a
+test fixture or an unrelated identifier is a false positive: skip it and
+say so in the report.
+
+**State records** are applied through `ADAPTABLE_UPGRADE_STATE/`:
+
+1. Replace the `initialState` literal in the source file with the contents
+   of its `.json`. Keep the surrounding code (the variable, the type
+   annotation, the export) and the file's formatting conventions.
+2. Re-attach every `unverifiable` entry from the `.md` report at its path:
+   the functions, imported constants and computed values the extractor
+   stubbed to `null`. The migrated State is only complete when that list is
+   empty in the source.
+3. Re-author every leftover. A leftover is a key the target major's types do
+   not know, left in place by the engine; the record whose `before` column
+   names it says what replaced it (a removed section, a renamed key, a
+   Predicate that is now an Expression). Delete it only when the record says
+   "removed, nothing converted".
+4. State that was not extractable (a `loadState` call, a fetched file) is
+   migrated at run time by `autoMigrateState`; nothing to rewrite, but the
+   run in step 5 shows what it could not convert.
+
+**AdapTableQL strings outside State** — in code, configuration, a server
+payload, a test — are not reached by State migration. Rewrite each one:
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary migrate expression "<expression>" --from <n> --to <m> --module <Module> --columns <columnDefs file>
+```
+
+The output carries `original`, `migrated`, `changed` and, for targets 24
+and later, the validation of the result. `--module` picks the kinds tried;
+pass it whenever the string's owner is known (an Alert rule, a Calculated
+Column expression, a Grid Filter).
+
+**Options, API and Objects records** are plain source edits at the matched
+lines: renamed options, moved keys, changed signatures, union members. The
+inlined release-note section under the record shows the full table when the
+`before → after` rows need context.
+
+## 3. Kept `BEHAVIOUR` / `DEPRECATED` records
+
+These are the records the user chose to mitigate in plan mode: restore the
+former result (an option set back, a default made explicit) or update the
+deprecated form now. Apply each note as written. Then perform the
+`# Validation` double-check the plan ends with: for every such record,
+confirm the mitigation is in the source — compile and tests do not catch a
+missed one, because both forms are valid on the target.
+
+## 4. Validate
+
+The validation loop applies (three rounds at most, then the remaining
+issues verbatim):
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary check state <file with the literal> --major <target> --columns <columnDefs file>
+npx -y @adaptabletools/adaptable-mcp@canary check expression "<rewritten string>" --module <Module> --columns <columnDefs file>
+npx -y @adaptabletools/adaptable-mcp@canary check setup
+```
+
+- `check state` on every rewritten literal — the shape against the target
+  major's own types, the semantic rules, the column references and the
+  AdapTableQL inside it. After the package bump the detected major is the
+  target; `--major` makes that explicit when a project is still mid-way.
+- `check expression` on every string `migrate expression` produced, and on
+  any the user authored by hand, for targets 24 and later.
+- `check setup` once per project: stylesheet, options, version skew between
+  the packages, AG Grid modules, wrapper wiring, ColDef ownership.
+- Then the project's own type-check and build. Type errors at this point are
+  usually a record applied to one match and not another: search the plan
+  for the identifier before reading the codebase.
+
+## 5. Run and read the console
+
+Start the application with a persisted State written by the former version
+when one exists (a developer's own `localStorage` is usually enough). On the
+first load AdapTable migrates persisted State, `initialState` and Team
+Sharing entities and logs each step. Read:
+
+- with a browser tool: `__ADAPTABLE_DEVTOOLS__.listInstances()`, then
+  `getLogs(id, { level: ['warn', 'error'] })`;
+- without one: tell the user to paste
+  `__ADAPTABLE_DEVTOOLS__.getLogs(undefined, { level: ['warn', 'error'] })`
+  into the console and paste the result back.
+
+Objects the runtime could not convert carry the suffix `(needs migration)`
+in their `Name`, and the Settings Panel shows them suspended. List every one
+in the report as a manual leftover with its Module and Name; they are fixed
+in the Settings Panel or in `initialState`, not by the tooling.
+
+## 6. Persisted State — the team's decision
+
+Say this plainly; do not act on it. Nothing in storage is touched without
+explicit confirmation (guards).
+
+- **Automatic migration.** With `stateOptions.autoMigrateState` left `true`
+  (the default) every entry point migrates State on load: start-up,
+  state-key change, Initial State re-apply, DevTools restore, Team Sharing
+  load. An application that sets it `false` must call
+  `AdaptableUpgradeHelper.migrateAdaptableState` itself inside
+  `stateOptions.applyState`.
+- **State keys and remote persistence.** Every state key in use (per user,
+  per `adaptableId`) migrates on that user's first load; a remote
+  persistence store receives the migrated payload on the next save. Decide
+  whether to migrate stored payloads ahead of the release (`migrate state`
+  on an export, `--kind persistent`) or let first-load migration do it.
+- **Team Sharing.** Every client that reads a shared store moves together;
+  a client on the former major cannot import entities written in the
+  target's shape. `teamSharingOptions.persistMigratedSharedEntities`
+  (default `true`) decides whether migrated entities are written back.
+- **Duplicate `Name`s.** Objects of one Module that share a `Name` in
+  persisted or shared State are renamed on the first load of a major that
+  converts Tags to Layout Extensions; rename them in the store beforehand
+  where it can be reached.
+- **Preview.** A real persisted State can be previewed through
+  `migrate state <export.json> --from <n> --to <m> --kind persistent` before
+  any user loads the new build; the report's leftovers are what the console
+  will say.
+
+## 7. Final report
+
+Prose, in this order: the packages moved (from → to, per project); the files
+changed, grouped by record; what was validated and the result of each check;
+the manual leftovers from step 5; the persisted-State decisions still open
+from step 6; and the plan's `Deployment` records verbatim as the release
+gotchas. Close with what remains manual — nothing is silently done.

package/dist/skills/adaptable-upgrade/references/plan-preamble.md

@@ -0,0 +1,151 @@
+---
+sources:
+  docs: [version-240-release-note, release-schedule, dev-guide-adaptable-state-migrating-state, handbook-team-sharing-configuring]
+  paths: [packages/adaptable-mcp/src/core/changes/render-md.ts, packages/adaptable-mcp/src/core/migrate/state.ts]
+---
+
+# Plan files — what each starts with
+
+Three artefacts, all at the repository root, all written by plan mode and
+read by apply mode. Copy the templates as written; the `<…>` fields come
+from the phase that writes the file.
+
+## `ADAPTABLE_UPGRADE_SCOPE.md` (phase 3, appended in phase 4)
+
+```markdown
+# AdapTable upgrade scope
+
+Target: AdapTable <target major> (<exact version or dist-tag, e.g. 24.x / canary>)
+Written: <date> by adaptable-upgrade <skill VERSION.md>
+Repository root: <absolute path>
+
+## Projects
+
+| Project | Framework | Wrapper package | AdapTable (declared → installed) | AG Grid (package, version, edition) | Package manager | Initial State literals | columnDefs files |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <relative path> | <vanilla / react / angular / vue> | <@adaptabletools/… or —> | <range → version> | <ag-grid-enterprise 34.0.0, Enterprise> | <npm / pnpm / yarn> | <files or —> | <files or —> |
+
+Projects found by `detect --all-projects` and left out of scope: <list or none>.
+
+## Target requirements (from `compat --adaptable <target>`)
+
+- AG Grid pairing: <e.g. 36 (documented with 36.2.0)>
+- Environment: <node …, typescript …, framework …>
+- Release note: <URL>
+- Change records cover: <majors>
+
+## Decisions
+
+- Projects in scope: confirmed by the user on <date>.
+- Current versions: <confirmed as detected / corrected to …>.
+- Target: <user's choice / latest>.
+```
+
+Phase 4 appends exactly one of:
+
+```markdown
+## AG Grid plan
+
+No AG Grid change: <installed> satisfies the pairing <required>.
+```
+
+```markdown
+## AG Grid plan
+
+Installed <installed>, required <required>. Decision: <one of>
+- ag-update: plan written to AG_UPDATE_*.md in this repository; apply it before the AdapTable bump.
+- bump only: install AG Grid <exact version>; AG Grid's upgrade guide for <installed major> → <required major> is the user's own checklist.
+- already handled: AG Grid <required> is assumed present when apply mode starts.
+```
+
+## `ADAPTABLE_UPGRADE_CHANGES.md` (phase 5, trimmed in phase 6)
+
+The file opens with this preamble, then the `changes` Markdown verbatim,
+then `## State literals`, then — when the trim keeps any `BEHAVIOUR` /
+`DEPRECATED` record — `# Validation`.
+
+```markdown
+# AdapTable upgrade plan
+
+This file lists the changes to apply to the project(s) in this repository
+to move them to the target AdapTable version recorded in
+ADAPTABLE_UPGRADE_SCOPE.md. Combine it with the project's own conventions
+and verification tools: bump AG Grid per the scope file, then every
+`@adaptabletools/*` package to the same target version, install, apply the
+records below, then validate with `check state`, `check expression` and
+`check setup`, type-check, build and a run of the application with its
+browser console open.
+
+Records are grouped per transition (21 → 22, 22 → 23, 23 → 24) and, inside
+each, ordered Packages & CSS → State → Options → API → Objects → AdapTableQL
+→ Deployment. Each record has a type — `BREAKING` (must change),
+`BEHAVIOUR` (same code, different result; kept here only if the user chose
+to restore the former result) or `DEPRECATED` (still works on the target,
+removed later; kept here only if the user chose to update now) — whether
+State migration handles it, its `before → after` rows, a note with the
+remedy, the release-note anchor and the `file:line` matches in this
+repository. Matches come from a plain text search and can include false
+positives (comments, unrelated identifiers); read the matched line before
+changing it. "Applies to every project" records have no matches to read.
+
+Release-note sections follow each record (`--with-docs`); a section longer
+than 60 lines is collapsed to its heading with the `docs get` command that
+reads it.
+
+State records say what AdapTable migrates on its own when State loads and
+what it leaves `(needs migration)`. `initialState` literals run as they are;
+the migrated copies under ADAPTABLE_UPGRADE_STATE/ bring the source up to
+date and silence the migration log.
+
+See ADAPTABLE_UPGRADE_SCOPE.md for the projects, target and AG Grid plan.
+```
+
+When `--with-docs` was skipped (offline), add under the preamble:
+
+```markdown
+> Release-note sections are not inlined (the docs host was not reachable
+> when this plan was written). Apply mode reads each record's anchor with
+> `adaptable docs get <release note slug> --section "<area heading>"`.
+```
+
+### `## State literals`
+
+One line per `initialState` literal the CLI could extract, and one per file
+it could not:
+
+```markdown
+## State literals
+
+- `<project>/<file>` → `ADAPTABLE_UPGRADE_STATE/<project>--<file>.json` (report: `….md`) — leftovers: <n>, unverifiable: <n>, check state --major <target>: <issues>
+- `<project>/<file>` — not extractable (<reason from the CLI>); migrate at run time or export the built State and migrate the export.
+```
+
+### `# Validation` (phase 6, only when kept records exist)
+
+```markdown
+# Validation
+
+All records marked BEHAVIOUR or DEPRECATED above are optional changes the
+user decided to apply. Double-check, with a sub-agent when one is
+available, that each has been applied: type-checking, the build and the
+tests may all pass when one is missed, because the former behaviour and
+the deprecated form both still compile.
+```
+
+## `ADAPTABLE_UPGRADE_STATE/` (phase 5)
+
+Per extractable literal, two files named `<project>--<file>` with the
+project's and file's path separators replaced by `-`:
+
+- `.json` — `migrate state --out`: the migrated State for the target major,
+  functions and imports replaced by `null` stubs and listed as
+  `unverifiable` in the report.
+- `.md` — the CLI's Markdown report: migration log, `leftovers` with their
+  source positions (keys the target major's types do not know, left in place
+  by the engine and ignored by the runtime), the `unverifiable` list, and
+  the `check state --major <target>` result the engine's output was given.
+
+Apply mode replaces the literal with the `.json`, re-attaches every
+`unverifiable` entry at its path, and re-authors every leftover from the
+record that owns it. A leftover is never deleted blindly: the release-note
+row names what replaced it.

package/dist/skills/adaptable-upgrade/scripts/adaptable.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Argument forwarder (plan §10): runs the `adaptable` CLI pinned to the package and
+// range this skill was built for, passing every argument through unchanged. No logic
+// lives here; `build-skills.ts` fills in the package/range string.
+//
+//   node adaptable.mjs changes --from 23 --to 24 --json
+//
+// `ADAPTABLE_CLI` (plan §7.1) replaces the `npx` invocation for local development and
+// evaluation runs, e.g. ADAPTABLE_CLI="node /path/to/dist/bin.js".
+import { spawnSync } from 'node:child_process';
+
+const windows = process.platform === 'win32';
+const override = process.env.ADAPTABLE_CLI?.trim();
+const [command, ...lead] = override ? override.split(/\s+/) : [windows ? 'npx.cmd' : 'npx', '-y', '@adaptabletools/adaptable-mcp@canary'];
+const result = spawnSync(command, [...lead, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: windows,
+});
+
+if (result.error) {
+  console.error(`Could not start ${command}: ${result.error.message}`);
+  process.exit(3);
+}
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptabletools/adaptable-mcp",
-  "version": "0.1.0-canary.1",
+  "version": "0.1.0-canary.2",
   "description": "AdapTable CLI and MCP server for coding agents: version-matched docs, State and AdapTableQL checks, migration, scaffolding",
   "homepage": "https://www.adaptabletools.com/",
   "license": "contact sales@adaptabletools.com for details",
@@ -25,17 +25,22 @@
     "skills"
   ],
   "scripts": {
-    "build": "rimraf dist && tsc --project tsconfig.json",
+    "build": "rimraf dist && tsc --project tsconfig.json && tsx scripts/build-skills.ts",
+    "build:skills": "tsx scripts/build-skills.ts",
+    "generate": "tsx scripts/build-records.ts && tsx scripts/sync-templates.ts && tsx scripts/generate-bindings.ts",
     "snapshot:manifest": "tsx scripts/snapshot-manifest.ts",
-    "lint": "eslint .",
+    "lint": "eslint . && tsx scripts/lint-skills.ts",
+    "check:reference-sources": "tsx scripts/check-reference-sources.ts",
     "test": "vitest run",
-    "inspect": "npx @modelcontextprotocol/inspector node ./dist/bin.js mcp"
+    "inspect": "npx @modelcontextprotocol/inspector node ./dist/bin.js mcp",
+    "eval": "tsx evals/run.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
     "commander": "14.0.3",
     "esbuild": "0.28.2",
     "json5": "2.2.3",
+    "read-excel-file": "9.3.13",
     "typescript": "5.8.3",
     "zod": "4.6.7"
   },
@@ -47,6 +52,7 @@
     "rimraf": "6.1.3",
     "tsx": "4.23.15",
     "typescript-eslint": "8.72.1",
-    "vitest": "5.0.5"
+    "vitest": "5.0.5",
+    "yaml": "2.8.1"
   }
 }