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

package/dist/core/docs/get-page.js

@@ -0,0 +1,182 @@
+/** Accepts a slug, a route path or a docs URL (with or without `.md` / `/index.md`) */
+export function findPage(corpus, page) {
+    const routePath = page
+        .trim()
+        .replace(/^https?:\/\/[^/]+/, '')
+        .replace(/[?#].*$/, '')
+        .replace(/\/index\.md$|\.md$/, '')
+        .replace(/\/+$/, '');
+    const candidates = /^\/(docs|support)(\/|$)/.test(routePath)
+        ? [routePath]
+        : [`/docs/${routePath}`, `/docs/reference/${routePath.toLowerCase()}`, `/support/${routePath}`];
+    for (const candidate of candidates) {
+        const found = corpus.pages.get(candidate) ?? corpus.pages.get(candidate.toLowerCase());
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+/** The slug skills use: the route path without `/docs/` (`/support/...` keeps its prefix) */
+export const slugOf = (routePath) => routePath.replace(/^\/docs\//, '');
+/**
+ * Closest slugs for a request that matched no page: slugs or titles sharing
+ * words with the request, then the search index's best sections.
+ */
+export function suggestSlugs(corpus, request, limit = 5) {
+    const words = request
+        .toLowerCase()
+        .replace(/^https?:\/\/[^/]+/, '')
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length >= 3 && w !== 'docs');
+    const scored = [];
+    for (const page of corpus.pages.values()) {
+        const slug = slugOf(page.routePath);
+        const haystack = `${slug} ${page.title}`.toLowerCase();
+        let score = 0;
+        for (const word of words) {
+            if (haystack.includes(word)) {
+                score += word.length;
+            }
+            else if (word.length >= 5 && haystack.includes(word.slice(0, -1))) {
+                score += word.length - 2; // one trailing character off (`layoutz`)
+            }
+        }
+        if (score > 0) {
+            scored.push({ slug, score });
+        }
+    }
+    const bySlug = scored.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug)).map((s) => s.slug);
+    const byIndex = corpus.index.search(words.join(' '), { limit }).map((h) => slugOf(h.section.routePath));
+    return [...new Set([...bySlug, ...byIndex])].slice(0, limit);
+}
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+function parseLines(markdown) {
+    let inFence = false;
+    return markdown.split('\n').map((text) => {
+        if (FENCE.test(text)) {
+            inFence = !inFence;
+            return { text };
+        }
+        if (inFence) {
+            return { text };
+        }
+        const match = text.match(HEADING);
+        return match ? { text, level: match[1].length, heading: match[2] } : { text };
+    });
+}
+/** The section under the first heading containing `heading` (case-insensitive), up to the next heading of the same or a higher level */
+export function extractHeading(markdown, heading) {
+    const lines = parseLines(markdown);
+    const target = heading.trim().toLowerCase();
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.level === undefined) {
+            continue;
+        }
+        if (start < 0 && line.heading.toLowerCase().includes(target)) {
+            start = i;
+            level = line.level;
+        }
+        else if (start >= 0 && line.level <= level) {
+            return lines
+                .slice(start, i)
+                .map((l) => l.text)
+                .join('\n')
+                .trimEnd();
+        }
+    }
+    return start >= 0
+        ? lines
+            .slice(start)
+            .map((l) => l.text)
+            .join('\n')
+            .trimEnd()
+        : undefined;
+}
+/** The page's `##`–`####` headings, skipping code fences */
+export function outline(markdown) {
+    return parseLines(markdown)
+        .filter((l) => l.level !== undefined && l.level >= 2 && l.level <= 4)
+        .map((l) => l.text);
+}
+/** Rough token count (≈ 4 characters per token) */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+const DEMO_START = /^Demo project \(([^)]+)\);?/;
+/**
+ * Replaces every embedded demo (the "Demo project (…)" paragraph, its file tree and
+ * the per-file code blocks, up to the next heading) with one line naming the demo's
+ * own files, so a page costs a fraction of its tokens; `docs demo` returns the code.
+ */
+export function trimDemos(markdown) {
+    const lines = parseLines(markdown);
+    const out = [];
+    let trimmed = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const start = lines[i].text.match(DEMO_START);
+        if (!start) {
+            out.push(lines[i].text);
+            continue;
+        }
+        // collect until the next heading
+        let end = i + 1;
+        while (end < lines.length && lines[end].level === undefined) {
+            end++;
+        }
+        const block = lines.slice(i, end).map((l) => l.text);
+        // the demo's own files are the ones whose code follows, introduced as **`src/file.ts`**
+        const files = block.map((l) => l.match(/^\*\*`([^`]+)`\*\*\s*$/)?.[1]).filter((f) => !!f);
+        const names = files.length ? files.join(', ') : 'its files';
+        out.push(`_Demo project (${start[1]}): ${names} — run \`adaptable docs demo <name>\` for the code, or \`docs get --full\` to inline it._`);
+        trimmed++;
+        // keep a blank line before the next heading
+        out.push('');
+        i = end - 1;
+    }
+    return { markdown: out.join('\n').replace(/\n{3,}/g, '\n\n'), trimmed };
+}
+/**
+ * Cuts the Markdown at a heading boundary: whole sections (a heading and the text
+ * up to the next heading) are kept while the running total stays within
+ * `maxTokens`; the preamble before the first heading is always kept. The headings
+ * of the dropped sections are listed in `omitted` so `--section` can fetch one.
+ */
+export function truncateAtHeadings(markdown, maxTokens) {
+    if (estimateTokens(markdown) <= maxTokens) {
+        return { markdown, truncated: false, omitted: [] };
+    }
+    const lines = parseLines(markdown);
+    const sections = [];
+    let current = { lines: [] };
+    for (const line of lines) {
+        if (line.level !== undefined && (current.lines.length || current.heading)) {
+            sections.push({ heading: current.heading, text: current.lines.join('\n') });
+            current = { heading: line, lines: [line.text] };
+        }
+        else {
+            current.lines.push(line.text);
+        }
+    }
+    sections.push({ heading: current.heading, text: current.lines.join('\n') });
+    const kept = [];
+    const omitted = [];
+    let tokens = 0;
+    let cutting = false;
+    sections.forEach((section, index) => {
+        const cost = estimateTokens(section.text) + 1;
+        if (index > 0 && (cutting || tokens + cost > maxTokens)) {
+            cutting = true;
+            if (section.heading && section.heading.level <= 3) {
+                omitted.push(section.heading.text);
+            }
+            return;
+        }
+        kept.push(section.text);
+        tokens += cost;
+    });
+    return { markdown: kept.join('\n').trimEnd(), truncated: true, omitted };
+}
+//# sourceMappingURL=get-page.js.map

package/dist/core/docs/get-page.js.map

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

package/dist/core/docs/hosts.js

@@ -0,0 +1,74 @@
+/**
+ * Which docs host serves a major (plan §7.4): the override, the manifest's
+ * `docsHosts`, the current host for the current major, else the archived-host
+ * pattern. The host's own manifest is then fetched (§8.3 freshness) so the
+ * corpus loader knows which files to read.
+ */
+import { fetchManifest, getManifestInfo, ManifestUnavailable, } from '../compat/manifest.js';
+import { CURRENT_DOCS_HOST, DOCS_HOST_ENV } from '../constants.js';
+import { CapabilityError } from '../envelope.js';
+/**
+ * The docs host for a major: the override (`--docs-host` / `ADAPTABLE_MCP_DOCS_HOST`) when
+ * given; the manifest's `docsHosts` entry; the current host for the current (or an unknown)
+ * major; else the archived-host pattern.
+ */
+export function docsHostFor(major, info = {}, override = process.env[DOCS_HOST_ENV]) {
+    if (override) {
+        return override.replace(/\/+$/, '');
+    }
+    if (major === undefined) {
+        return CURRENT_DOCS_HOST;
+    }
+    const mapped = info.docsHosts?.[String(major)];
+    if (mapped) {
+        return mapped.replace(/\/+$/, '');
+    }
+    if (info.latestMajor === undefined || major >= info.latestMajor) {
+        return CURRENT_DOCS_HOST;
+    }
+    return major >= 21 ? `https://v${major}.adaptabletools.com` : `https://v${major}.docs.adaptabletools.com`;
+}
+export function pageUrl(baseUrl, routePath, framework) {
+    return `${baseUrl}${routePath}${framework && framework !== 'vanilla' ? `?framework=${framework}` : ''}`;
+}
+export const docsNotAvailable = (host, reason) => new CapabilityError('DOCS_NOT_AVAILABLE', `${reason} (${host}).`, `Read the HTML documentation at ${host}/docs, pass --docs-host <url> for a host with machine-readable docs, or retry with network access.`);
+/**
+ * Resolves the host for `major` and fetches that host's manifest. The current
+ * host's manifest is consulted first (for `docsHosts`) unless an override is given.
+ */
+export async function resolveDocsSource(options = {}) {
+    const warnings = [];
+    const override = options.docsHost ?? process.env[DOCS_HOST_ENV];
+    let current;
+    if (!override) {
+        current = await getManifestInfo({ offline: options.offline, maxAgeMs: options.revalidateTtlMs });
+    }
+    const host = docsHostFor(options.major, current ? { latestMajor: current.latest.adaptableMajor, docsHosts: current.docsHosts } : {}, override);
+    const isCurrentHost = host === (current?.host ?? CURRENT_DOCS_HOST);
+    let fetched;
+    try {
+        fetched =
+            current && host === current.host
+                ? { manifest: current.manifest, source: current.source, warning: current.warning }
+                : await fetchManifest({
+                    docsHost: host,
+                    offline: options.offline,
+                    maxAgeMs: options.revalidateTtlMs,
+                    allowSnapshot: isCurrentHost,
+                });
+    }
+    catch (error) {
+        if (error instanceof ManifestUnavailable) {
+            throw docsNotAvailable(host, `No machine-readable docs could be read: ${error.message}`);
+        }
+        throw error;
+    }
+    if (fetched.warning) {
+        warnings.push(fetched.warning);
+    }
+    if (options.major !== undefined && fetched.manifest.major !== options.major) {
+        warnings.push(`The docs at ${host} are for AdapTable ${fetched.manifest.major}, not ${options.major}; pass --docs-host for a host that serves ${options.major}.`);
+    }
+    return { host, manifest: fetched.manifest, manifestSource: fetched.source, current, warnings };
+}
+//# sourceMappingURL=hosts.js.map

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

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

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":"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"}

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":"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"}

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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"}