@adaptabletools/adaptable-mcp 0.0.0-stage → 0.1.0-canary.1

package/dist/core/docs/search.js

@@ -0,0 +1,92 @@
+const STOP_WORDS = new Set('a an and are as at be by can do does for from how i in is it of on or should that the this to use using what when where which with you your'.split(' '));
+/**
+ * Identifiers are indexed whole (`layoutapi`, `group_by`) and split
+ * (`layout`, `api`, `group`, `by`), so exact API tokens rank highest while
+ * prose queries still match.
+ */
+export function tokenize(text) {
+    const tokens = [];
+    for (const raw of text.match(/[A-Za-z_$][A-Za-z0-9_$]*|\d+/g) ?? []) {
+        const whole = raw.toLowerCase();
+        if (!STOP_WORDS.has(whole)) {
+            tokens.push(whole);
+        }
+        const parts = raw
+            .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+            .split(/[\s_$]+/)
+            .map((p) => p.toLowerCase())
+            .filter((p) => p && p !== whole && !STOP_WORDS.has(p));
+        tokens.push(...parts);
+    }
+    return tokens;
+}
+const K1 = 1.2;
+const B = 0.75;
+const TITLE_WEIGHT = 3;
+const HEADING_WEIGHT = 2;
+export class SectionIndex {
+    docs = [];
+    documentFrequency = new Map();
+    averageLength = 0;
+    constructor(sections) {
+        let totalLength = 0;
+        for (const section of sections) {
+            const termFrequencies = new Map();
+            const add = (text, weight) => {
+                for (const token of tokenize(text)) {
+                    termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
+                }
+            };
+            add(section.pageTitle, TITLE_WEIGHT);
+            add(section.headings.join(' '), HEADING_WEIGHT);
+            add(section.text, 1);
+            let length = 0;
+            for (const [term, count] of termFrequencies) {
+                length += count;
+                this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+            }
+            totalLength += length;
+            this.docs.push({ section, length, termFrequencies });
+        }
+        this.averageLength = this.docs.length ? totalLength / this.docs.length : 0;
+    }
+    search(query, options = {}) {
+        const terms = [...new Set(tokenize(query))];
+        if (!terms.length) {
+            return [];
+        }
+        const total = this.docs.length;
+        const hits = [];
+        for (const doc of this.docs) {
+            const { section } = doc;
+            if (options.framework &&
+                section.frameworks &&
+                !section.frameworks.includes(options.framework)) {
+                continue;
+            }
+            if (options.categories?.length
+                ? !options.categories.includes(section.category)
+                : options.excludeCategories?.includes(section.category)) {
+                continue;
+            }
+            let score = 0;
+            for (const term of terms) {
+                const tf = doc.termFrequencies.get(term);
+                if (!tf) {
+                    continue;
+                }
+                const df = this.documentFrequency.get(term) ?? 0;
+                const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));
+                score +=
+                    (idf * tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * doc.length) / this.averageLength));
+            }
+            if (score > 0) {
+                hits.push({ section, score });
+            }
+        }
+        hits.sort((a, b) => b.score - a.score);
+        return hits.slice(0, options.limit ?? 8);
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/core/docs/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/core/docs/search.ts"],"names":[],"mappings":"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"}

package/dist/core/envelope.js

@@ -0,0 +1,79 @@
+export const SCHEMA_VERSION = 1;
+export const ERROR_CODES = [
+    'USAGE',
+    'NOT_FOUND',
+    'NO_ADAPTABLE_DEPENDENCY',
+    'MULTIPLE_PROJECTS',
+    'VERSION_NOT_SUPPORTED',
+    'UNSUPPORTED_FOR_MAJOR',
+    'PACKAGE_REQUIRED',
+    'DOCS_NOT_AVAILABLE',
+    'INPUT_TOO_LARGE',
+    'NETWORK_REQUIRED',
+    'NOT_AVAILABLE_OVER_MCP',
+    'NOT_AVAILABLE_REMOTELY',
+    'EXTRACTION_FAILED',
+    'RECORDS_INVALID',
+];
+export function ok(data, extra = {}) {
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        ...(extra.resolvedContext ? { resolvedContext: extra.resolvedContext } : {}),
+        warnings: extra.warnings ?? [],
+        issues: extra.issues ?? [],
+        data,
+    };
+}
+export function fail(code, message, hint, details) {
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: false,
+        error: { code, message, hint, ...(details ? { details } : {}) },
+    };
+}
+/** Thrown inside a capability (or context resolution); `runCapability` turns it into a failure envelope. */
+export class CapabilityError extends Error {
+    code;
+    hint;
+    details;
+    constructor(code, message, hint, details) {
+        super(message);
+        this.name = 'CapabilityError';
+        this.code = code;
+        this.hint = hint;
+        this.details = details;
+    }
+    toEnvelope() {
+        return fail(this.code, this.message, this.hint, this.details);
+    }
+}
+export const EXIT_CODES = { ok: 0, findings: 1, usage: 2, environment: 3 };
+/** Which exit class each error code belongs to (plan §7.1: 2 usage, 3 environment) */
+export const ERROR_EXIT_CLASS = {
+    USAGE: 'usage',
+    NOT_FOUND: 'usage',
+    INPUT_TOO_LARGE: 'usage',
+    EXTRACTION_FAILED: 'usage',
+    NOT_AVAILABLE_OVER_MCP: 'usage',
+    NOT_AVAILABLE_REMOTELY: 'usage',
+    NO_ADAPTABLE_DEPENDENCY: 'environment',
+    MULTIPLE_PROJECTS: 'environment',
+    VERSION_NOT_SUPPORTED: 'environment',
+    UNSUPPORTED_FOR_MAJOR: 'environment',
+    PACKAGE_REQUIRED: 'environment',
+    DOCS_NOT_AVAILABLE: 'environment',
+    NETWORK_REQUIRED: 'environment',
+    RECORDS_INVALID: 'environment',
+};
+/** Issue severities that make a successful call a "findings" exit (1); `info` does not. */
+export const FINDING_SEVERITIES = ['error', 'warning'];
+export function exitCodeFor(envelope) {
+    if (!envelope.ok) {
+        return EXIT_CODES[ERROR_EXIT_CLASS[envelope.error.code]];
+    }
+    return envelope.issues.some((issue) => FINDING_SEVERITIES.includes(issue.severity))
+        ? EXIT_CODES.findings
+        : EXIT_CODES.ok;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/core/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/core/envelope.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO;IACP,WAAW;IACX,yBAAyB;IACzB,mBAAmB;IACnB,uBAAuB;IACvB,uBAAuB;IACvB,kBAAkB;IAClB,oBAAoB;IACpB,iBAAiB;IACjB,kBAAkB;IAClB,wBAAwB;IACxB,wBAAwB;IACxB,mBAAmB;IACnB,iBAAiB;CACT,CAAC;AA+DX,MAAM,UAAU,EAAE,CAChB,IAAO,EACP,QAAsF,EAAE;IAExF,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,EAAE,EAAE,IAAI;QACR,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;QAC1B,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,IAAI,CAClB,IAAe,EACf,OAAe,EACf,IAAY,EACZ,OAAiC;IAEjC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;KAChE,CAAC;AACJ,CAAC;AAED,4GAA4G;AAC5G,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAY;IAChB,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YAAY,IAAe,EAAE,OAAe,EAAE,IAAY,EAAE,OAAiC;QAC3F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;CACF;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAW,CAAC;AAGpF,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAA+C;IAC1E,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,OAAO;IAClB,eAAe,EAAE,OAAO;IACxB,iBAAiB,EAAE,OAAO;IAC1B,sBAAsB,EAAE,OAAO;IAC/B,sBAAsB,EAAE,OAAO;IAC/B,uBAAuB,EAAE,aAAa;IACtC,iBAAiB,EAAE,aAAa;IAChC,qBAAqB,EAAE,aAAa;IACpC,qBAAqB,EAAE,aAAa;IACpC,gBAAgB,EAAE,aAAa;IAC/B,kBAAkB,EAAE,aAAa;IACjC,gBAAgB,EAAE,aAAa;IAC/B,eAAe,EAAE,aAAa;CAC/B,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAA6B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAEjF,MAAM,UAAU,WAAW,CAAC,QAA2B;IACrD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,UAAU,CAAC,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjF,CAAC,CAAC,UAAU,CAAC,QAAQ;QACrB,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;AACpB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * The only import surface for `src/cli` and `src/mcp` (plan Appendix H).
+ * Runtime exports are the Appendix H eight — `listCapabilities`, `getCapability`,
+ * `runCapability`, `CLI_PACKAGE`, `CLI_RANGE`, `RECORDS_FLOOR`, `MIGRATION_FLOOR`,
+ * `SCHEMA_VERSION` — plus two reviewed additions for the bindings (A0.3):
+ * `exitCodeFor` (the §7.1 exit mapping the CLI applies) and `CLI_VERSION`
+ * (reported by `--version`, `--capabilities` and the MCP server info).
+ * Adding an export is a reviewed change.
+ */
+import './register.js';
+export { CLI_PACKAGE, CLI_RANGE, MIGRATION_FLOOR, PACKAGE_VERSION as CLI_VERSION, RECORDS_FLOOR, SCHEMA_VERSION, getCapability, listCapabilities, runCapability, } from './capabilities.js';
+export { exitCodeFor } from './envelope.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,SAAS,EACT,eAAe,EACf,eAAe,IAAI,WAAW,EAC9B,aAAa,EACb,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/packages/cache.js

@@ -0,0 +1,138 @@
+/**
+ * The on-disk cache (plan §7.1): `~/.cache/adaptable-mcp/` — `$XDG_CACHE_HOME`
+ * honoured, `ADAPTABLE_MCP_CACHE_DIR` overrides — with
+ *   pkgs/@adaptabletools/adaptable@<version>/   extracted library packages (§7.3)
+ *   entries/<version>/<entry>.mjs               esbuild bundles of a package's entries
+ *   docs/<host>/<manifest hash>/                docs corpora (A1.1)
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { LIBRARY_PACKAGE } from '../constants.js';
+import { compareSemver } from './versions.js';
+export function getCacheRoot() {
+    return (process.env.ADAPTABLE_MCP_CACHE_DIR ||
+        join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'adaptable-mcp'));
+}
+/** A cache folder, created on demand */
+export function getCacheDir(...segments) {
+    const dir = join(getCacheRoot(), ...segments);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export const PKGS_DIR = 'pkgs';
+export const ENTRIES_DIR = 'entries';
+export const DOCS_DIR = 'docs';
+/** Folder a cached library version lives in (its `package.json` is directly inside) */
+export function packageCacheDir(version) {
+    return join(getCacheRoot(), PKGS_DIR, `${LIBRARY_PACKAGE}@${version}`);
+}
+export function entriesCacheDir(version) {
+    return join(getCacheRoot(), ENTRIES_DIR, version);
+}
+/** Cached library packages, oldest first */
+export function listCachedPackages() {
+    const scopeDir = join(getCacheRoot(), PKGS_DIR, LIBRARY_PACKAGE.split('/')[0]);
+    const prefix = `${LIBRARY_PACKAGE.split('/')[1]}@`;
+    let names;
+    try {
+        names = readdirSync(scopeDir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.startsWith(prefix) && existsSync(join(scopeDir, name, 'package.json')))
+        .map((name) => ({ version: name.slice(prefix.length), dir: join(scopeDir, name) }))
+        .sort((a, b) => compareSemver(a.version, b.version));
+}
+function folderSize(dir) {
+    let total = 0;
+    const walk = (path) => {
+        let entries;
+        try {
+            entries = readdirSync(path, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(path, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += statSync(full).size;
+                }
+                catch {
+                    // removed meanwhile
+                }
+            }
+        }
+    };
+    walk(dir);
+    return total;
+}
+function ageDays(path) {
+    try {
+        return Math.floor((Date.now() - statSync(path).mtimeMs) / 86_400_000);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What `cache list` shows: packages, entry bundles and docs corpora with sizes and ages */
+export function summarizeCache() {
+    const root = getCacheRoot();
+    const packages = listCachedPackages().map(({ version, dir }) => ({
+        version,
+        bytes: folderSize(dir),
+        ageDays: ageDays(dir),
+    }));
+    const entriesRoot = join(root, ENTRIES_DIR);
+    const entries = (existsSync(entriesRoot) ? readdirSync(entriesRoot) : [])
+        .filter((version) => statSync(join(entriesRoot, version)).isDirectory())
+        .sort(compareSemver)
+        .map((version) => ({
+        version,
+        files: readdirSync(join(entriesRoot, version)).sort(),
+        bytes: folderSize(join(entriesRoot, version)),
+    }));
+    const docsRoot = join(root, DOCS_DIR);
+    const docs = [];
+    if (existsSync(docsRoot)) {
+        for (const host of readdirSync(docsRoot).sort()) {
+            const hostDir = join(docsRoot, host);
+            if (!statSync(hostDir).isDirectory()) {
+                continue;
+            }
+            for (const hash of readdirSync(hostDir).sort()) {
+                const dir = join(hostDir, hash);
+                if (statSync(dir).isDirectory()) {
+                    docs.push({ host, hash, bytes: folderSize(dir), ageDays: ageDays(dir) });
+                }
+            }
+        }
+    }
+    return { root, packages, entries, docs };
+}
+/** Removes docs corpora and/or packages (with their entry bundles); everything when neither flag is set */
+export function clearCache(options = {}) {
+    const all = !options.docs && !options.pkgs;
+    const root = getCacheRoot();
+    const removed = [];
+    const targets = [
+        ...(all || options.docs ? [DOCS_DIR] : []),
+        ...(all || options.pkgs ? [PKGS_DIR, ENTRIES_DIR] : []),
+    ];
+    for (const target of targets) {
+        const dir = join(root, target);
+        if (existsSync(dir)) {
+            rmSync(dir, { recursive: true, force: true });
+            removed.push(target);
+        }
+    }
+    return { removed };
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/packages/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/core/packages/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,UAAU,YAAY;IAC1B,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,uBAAuB;QACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,eAAe,CAAC,CAC/E,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,WAAW,CAAC,GAAG,QAAkB;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;IAC9C,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE/B,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,GAAG,eAAe,IAAI,OAAO,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAOD,4CAA4C;AAC5C,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnD,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;SAC7F,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;SAClF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE;QAC5B,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;gBAC/B,CAAC;gBAAC,MAAM,CAAC;oBACP,oBAAoB;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AASD,4FAA4F;AAC5F,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/D,OAAO;QACP,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC;QACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC;KACtB,CAAC,CAAC,CAAC;IAEJ,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SACvE,IAAI,CAAC,aAAa,CAAC;SACnB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACjB,OAAO;QACP,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE;QACrD,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;KAC9C,CAAC,CAAC,CAAC;IAEN,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtC,MAAM,IAAI,GAAyB,EAAE,CAAC;IACtC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;gBACrC,SAAS;YACX,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;gBAChC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;oBAChC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAOD,2GAA2G;AAC3G,MAAM,UAAU,UAAU,CAAC,UAAwB,EAAE;IACnD,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3C,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG;QACd,GAAG,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/core/packages/capabilities.js

@@ -0,0 +1,95 @@
+/**
+ * `adaptable cache add <major|version|tag>` · `cache list` · `cache clear [--docs|--pkgs]` (plan §8.13).
+ * CLI only: an MCP client has no business filling a user's cache.
+ */
+import { z } from 'zod';
+import { registerCapability } from '../capabilities.js';
+import { LIBRARY_PACKAGE } from '../constants.js';
+import { CapabilityError, ok } from '../envelope.js';
+import { clearCache, listCachedPackages, summarizeCache } from './cache.js';
+import { npmRegistry } from './registry.js';
+import { pickVersion } from './resolve.js';
+/** Tests swap the registry; production uses npm */
+let registryFactory = (cwd) => npmRegistry({ cwd });
+export function setPackageRegistryFactory(factory) {
+    registryFactory = factory;
+}
+const formatBytes = (bytes) => bytes >= 1_048_576 ? `${(bytes / 1_048_576).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} kB`;
+registerCapability({
+    name: 'cache-add',
+    description: `Downloads a ${LIBRARY_PACKAGE} version into the cache so checks and migrations for that major work offline.`,
+    cli: { command: ['cache', 'add'], positionals: ['spec'] },
+    mcp: null,
+    input: z.object({
+        spec: z.string().describe('A major (23), an exact version (23.1.1) or a dist-tag (canary)'),
+    }),
+    output: z.object({
+        version: z.string(),
+        dir: z.string(),
+        status: z.enum(['downloaded', 'already-cached']),
+    }),
+    run: async (input, ctx) => {
+        if (ctx.globals.offline) {
+            throw new CapabilityError('NETWORK_REQUIRED', '`cache add` downloads from the npm registry and cannot run with --offline.', 'Drop --offline, or run the command on a connected machine and copy the cache folder.');
+        }
+        const registry = registryFactory(ctx.cwd);
+        const view = await registry.view();
+        const version = pickVersion(input.spec, view);
+        if (!version) {
+            throw new CapabilityError('VERSION_NOT_SUPPORTED', `The npm registry has no ${LIBRARY_PACKAGE} matching "${input.spec}".`, `Pass a published major (${[...new Set(view.versions.map((v) => v.split('.')[0]))].slice(-4).join(', ')}), an exact version or a dist-tag (${Object.keys(view.distTags).join(', ')}).`);
+        }
+        const cached = listCachedPackages().find((p) => p.version === version);
+        if (cached) {
+            return ok({ version, dir: cached.dir, status: 'already-cached' });
+        }
+        const dir = await registry.fetch(version);
+        return ok({ version, dir, status: 'downloaded' });
+    },
+    markdown: (data) => data.status === 'downloaded'
+        ? `Cached ${LIBRARY_PACKAGE}@${data.version} at \`${data.dir}\`.`
+        : `${LIBRARY_PACKAGE}@${data.version} was already cached at \`${data.dir}\`.`,
+});
+registerCapability({
+    name: 'cache-list',
+    description: 'Shows cached library packages, bundled entries and docs corpora with sizes and ages.',
+    cli: { command: ['cache', 'list'] },
+    mcp: null,
+    input: z.object({}),
+    output: z.object({
+        root: z.string(),
+        packages: z.array(z.object({ version: z.string(), bytes: z.number(), ageDays: z.number().optional() })),
+        entries: z.array(z.object({ version: z.string(), files: z.array(z.string()), bytes: z.number() })),
+        docs: z.array(z.object({ host: z.string(), hash: z.string(), bytes: z.number(), ageDays: z.number().optional() })),
+    }),
+    run: async () => ok(summarizeCache()),
+    markdown: (data) => {
+        const lines = [`Cache: \`${data.root}\``, ''];
+        lines.push(`## Packages (${data.packages.length})`, '');
+        for (const p of data.packages) {
+            lines.push(`- ${LIBRARY_PACKAGE}@${p.version} — ${formatBytes(p.bytes)}${p.ageDays !== undefined ? `, ${p.ageDays} d old` : ''}`);
+        }
+        lines.push('', `## Entry bundles (${data.entries.length})`, '');
+        for (const e of data.entries) {
+            lines.push(`- ${e.version}: ${e.files.join(', ')} — ${formatBytes(e.bytes)}`);
+        }
+        lines.push('', `## Docs corpora (${data.docs.length})`, '');
+        for (const d of data.docs) {
+            lines.push(`- ${d.host} (${d.hash}) — ${formatBytes(d.bytes)}${d.ageDays !== undefined ? `, ${d.ageDays} d old` : ''}`);
+        }
+        return lines.join('\n');
+    },
+});
+registerCapability({
+    name: 'cache-clear',
+    description: 'Removes cached docs corpora and/or library packages (with their entry bundles); everything when no flag is given.',
+    cli: { command: ['cache', 'clear'] },
+    mcp: null,
+    input: z.object({
+        docs: z.boolean().optional().describe('Remove docs corpora only'),
+        pkgs: z.boolean().optional().describe('Remove packages and entry bundles only'),
+    }),
+    output: z.object({ removed: z.array(z.string()) }),
+    run: async (input) => ok(clearCache(input)),
+    markdown: (data) => (data.removed.length ? `Removed: ${data.removed.join(', ')}.` : 'Nothing to remove.'),
+});
+//# sourceMappingURL=capabilities.js.map

package/dist/core/packages/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/core/packages/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/core/packages/entry-types.js

@@ -0,0 +1,13 @@
+export const EXPRESSION_MODULES = [
+    'Alert',
+    'CalculatedColumn',
+    'ColumnFilter',
+    'Export',
+    'FlashingCell',
+    'FormatColumn',
+    'GridFilter',
+    'NamedQuery',
+    'PlusMinus',
+    'StyledColumn',
+];
+//# sourceMappingURL=entry-types.js.map

package/dist/core/packages/entry-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-types.js","sourceRoot":"","sources":["../../../src/core/packages/entry-types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO;IACP,kBAAkB;IAClB,cAAc;IACd,QAAQ;IACR,cAAc;IACd,cAAc;IACd,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,cAAc;CACN,CAAC"}

package/dist/core/packages/exec.js

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+/** Runs a command and resolves with its stdout; rejects with stderr on a non-zero exit */
+export function exec(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            shell: process.platform === 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, NO_UPDATE_NOTIFIER: '1', npm_config_update_notifier: 'false' },
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        const timer = options.timeoutMs
+            ? setTimeout(() => {
+                child.kill();
+                reject(new Error(`${command} ${args.join(' ')} timed out after ${options.timeoutMs} ms`));
+            }, options.timeoutMs)
+            : undefined;
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve(Buffer.concat(out).toString('utf8'));
+            }
+            else {
+                reject(new Error(`${command} ${args.join(' ')} exited with ${code}: ${Buffer.concat(err).toString('utf8').trim()}`));
+            }
+        });
+    });
+}
+export const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+//# sourceMappingURL=exec.js.map

package/dist/core/packages/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../src/core/packages/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAO3C,0FAA0F;AAC1F,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,IAAc,EAAE,UAAuB,EAAE;IAC7E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACjC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;YACnC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;YACjC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,0BAA0B,EAAE,OAAO,EAAE;SACtF,CAAC,CAAC;QACH,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5D,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS;YAC7B,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE;gBACd,KAAK,CAAC,IAAI,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,OAAO,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC;YAC5F,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC;YACvB,CAAC,CAAC,SAAS,CAAC;QACd,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/C,CAAC;iBAAM,CAAC;gBACN,MAAM,CACJ,IAAI,KAAK,CAAC,GAAG,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAC7G,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC"}

package/dist/core/packages/load-entry.js

@@ -0,0 +1,123 @@
+/**
+ * Loads a library entry (`aql`, `upgrade`) from a resolved package. The
+ * published package is bundler-only ESM (extensionless relative imports), so
+ * each entry is bundled once per version with esbuild into
+ * `entries/<version>/<entry>.mjs` and imported from there (plan §7.3).
+ *
+ * `ADAPTABLE_MCP_ADAPTABLE_SRC` points at an AdapTable source folder instead
+ * (e.g. `packages/adaptable` in the AdapTable repo); source bundles are never
+ * cached because they change with every edit.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+import { entriesCacheDir } from './cache.js';
+import { entryNodePaths } from './prepare.js';
+export const SOURCE_ENV = 'ADAPTABLE_MCP_ADAPTABLE_SRC';
+/** The source override, when `ADAPTABLE_MCP_ADAPTABLE_SRC` is set */
+export function sourceOverride() {
+    const dir = process.env[SOURCE_ENV];
+    return dir ? { kind: 'source', dir } : undefined;
+}
+export const packageLocation = (pkg) => ({
+    kind: 'package',
+    version: pkg.version,
+    dir: pkg.dir,
+});
+function entryFile(location, name) {
+    if (location.kind === 'source') {
+        const entry = join(location.dir, `${name}.ts`);
+        const tsconfig = join(location.dir, 'tsconfig.cjs.json');
+        return existsSync(entry) ? { entry, tsconfig: existsSync(tsconfig) ? tsconfig : undefined } : undefined;
+    }
+    const entry = join(location.dir, `${name}.js`);
+    return existsSync(entry) ? { entry } : undefined;
+}
+function sourceStamp(dir) {
+    // a source entry changes with every edit to the files it imports: never reuse a bundle
+    return createHash('sha256').update(dir).update(`${process.pid}-${Date.now()}`).digest('hex').slice(0, 16);
+}
+function packageVersionAt(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function bundle(entry, outfile, tsconfig, nodePaths) {
+    mkdirSync(join(outfile, '..'), { recursive: true });
+    await build({
+        entryPoints: [entry],
+        bundle: true,
+        platform: 'node',
+        format: 'esm',
+        outfile,
+        tsconfig,
+        nodePaths,
+        logLevel: 'silent',
+    });
+}
+const loaded = new Map();
+async function loadUncached(location, name) {
+    const found = entryFile(location, name);
+    if (!found) {
+        const where = location.kind === 'source' ? location.dir : `${location.dir} (version ${location.version})`;
+        return {
+            ok: false,
+            reason: `${where} has no ${name} entry point; it ships with @adaptabletools/adaptable 24 and later.`,
+        };
+    }
+    let outfile;
+    let cacheable;
+    if (location.kind === 'source') {
+        outfile = join(tmpdir(), `adaptable-${name}-${sourceStamp(location.dir)}.mjs`);
+        cacheable = false;
+    }
+    else {
+        // the folder is keyed by the declared version; the file name also carries the
+        // entry's mtime so a re-fetched or edited package of the same version is rebundled
+        const version = packageVersionAt(location.dir) ?? location.version;
+        const stamp = createHash('sha256')
+            .update(found.entry)
+            .update(String(statSync(found.entry).mtimeMs))
+            .digest('hex')
+            .slice(0, 8);
+        outfile = join(entriesCacheDir(version), `${name}-${stamp}.mjs`);
+        cacheable = true;
+    }
+    try {
+        if (!cacheable || !existsSync(outfile)) {
+            await bundle(found.entry, outfile, found.tsconfig, location.kind === 'package' ? entryNodePaths(location.dir) : undefined);
+        }
+        const module = await import(pathToFileURL(outfile).href);
+        return { ok: true, module, source: found.entry, bundle: outfile };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const unresolved = [...message.matchAll(/Could not resolve "([^"]+)"/g)].map((m) => m[1]);
+        const hint = unresolved.length && location.kind === 'package'
+            ? ` The package folder lacks ${[...new Set(unresolved)].join(', ')}; re-run \`adaptable cache add ${location.version}\` on a connected machine to install the entry dependencies.`
+            : '';
+        return { ok: false, reason: `Could not load ${found.entry}: ${message}${hint}` };
+    }
+}
+/** Loads `name` from `location`, bundling it first when needed; memoised per process */
+export function loadEntry(location, name) {
+    const key = `${location.kind}:${location.dir}:${name}`;
+    let result = loaded.get(key);
+    if (!result) {
+        result = loadUncached(location, name);
+        result.then((r) => {
+            if (!r.ok) {
+                loaded.delete(key);
+            }
+        });
+        loaded.set(key, result);
+    }
+    return result;
+}
+//# sourceMappingURL=load-entry.js.map