@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/mcp-reports.mjs

@@ -1,130 +1,130 @@
-// The MCP server's `analytics_reports` tool: which reports app.analytics.report() can call, read from the HawkSearch
-// Analytics API's own OpenAPI spec (the developer portal), so a new report is known as soon as the analytics API
-// documents it. The dev spec, as the MCP only works against the dev platform, which calls the dev analytics API; the
-// prod spec only to mark the reports prod doesn't have yet, which an app can't use once it's live. The platform's
-// rules (mcp-rules.mjs) mark the reports it blocks. The specs are public: no key, no client data.
-import { parse } from 'yaml';
-import { FALLBACK } from './mcp-rules.mjs';
-
-export const SPEC_URL = 'https://developers.analytics.hawksearch.com/dev/openapi.yaml';
-export const PROD_SPEC_URL = 'https://developers.analytics.hawksearch.com/openapi.yaml';
-const PORTAL_URL = 'https://developers.analytics.hawksearch.com/';
-const CACHE_MS = 10 * 60_000;
-const TIMEOUT_MS = 10_000;
-const DEV_ONLY = 'dev only: not on prod yet, so an app using it fails once it is live';
-const BLOCKED = 'blocked by the platform: apps get 404 report_not_allowed';
-
-/** The notes on one report: dev only, blocked. */
-const marks = (name, prod, blocked) => [prod && !prod.has(name) ? DEV_ONLY : null, blocked.includes(name) ? BLOCKED : null].filter(Boolean);
-
-async function fetchSpec(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
-    return response.text();
-}
-
-/** The reports in a parsed spec: one per POST path, by the name app.analytics.report() takes ("" for the root). */
-export function reportsIn(spec) {
-    return Object.entries(spec?.paths ?? {})
-        .filter(([, item]) => item?.post)
-        .map(([path, item]) => ({ name: path.replace(/^\/+|\/+$/g, ''), tag: item.post.tags?.[0] ?? 'Other', summary: item.post.summary ?? '', operation: item.post }));
-}
-
-const call = (name) => `app.analytics.report(${JSON.stringify(name)}`;
-const title = (name) => (name === '' ? '"" (the root)' : name);
-
-function list(reports, url, prod, blocked) {
-    const groups = new Map();
-    for (const r of reports) groups.set(r.tag, [...(groups.get(r.tag) ?? []), r]);
-    const lines = [`Analytics reports app.analytics.report(name, request) can call (scope reports:read), from ${url}. Call again with report: "<name>" for its columns, filters and an example.`];
-    for (const [tag, items] of groups) {
-        lines.push('', `## ${tag}`);
-        for (const r of items) {
-            const notes = marks(r.name, prod, blocked);
-            lines.push(`- ${title(r.name)}${notes.length ? ` (${notes.join('; ')})` : ''}: ${r.summary}`);
-        }
-    }
-    return lines.join('\n');
-}
-
-/** A request body's examples: inline, or through a $ref to components.requestBodies. */
-function requestExamples(op, spec) {
-    const body = op.requestBody?.$ref ? spec.components?.requestBodies?.[op.requestBody.$ref.split('/').pop()] : op.requestBody;
-    return body?.content?.['application/json']?.examples;
-}
-
-function detail(report, spec, prod, blocked) {
-    const op = report.operation;
-    const example = op.responses?.['200']?.content?.['application/json']?.example;
-    // x-report is the spec's checked list (the analytics API's tests keep it in step); examples can be out of date.
-    const x = op['x-report'];
-    const columns = (x?.columns ?? example?.columns ?? []).map((c) => `${c.name} (${c.type})`);
-    const fields = x && x.kind !== 'write'
-        ? [`filters takes: ${Object.keys(x.filters ?? {}).join(', ') || 'none'}; having takes: ${(x.having ?? []).join(', ') || 'none'}.`]
-        : [];
-    const bodyExamples = requestExamples(op, spec);
-    const sample = report.name === '' ? { query: 'top 10 keywords by searches last week' } : { startDate: '2026-06-01', endDate: '2026-06-30', page: 1, limit: 50 };
-    return [
-        `# ${title(report.name)}: ${report.summary}`,
-        ...marks(report.name, prod, blocked).flatMap((note) => ['', `Note: ${note}.`]),
-        '',
-        (op.description ?? '').trim(),
-        ...(columns.length ? ['', `Columns: ${columns.join(', ')}.`] : []),
-        ...fields,
-        '',
-        'From an app:',
-        `const result = await ${call(report.name)}, ${JSON.stringify(sample)});`,
-        report.name === ''
-            ? ''
-            : x
-              ? '// result: { columns, data, totalRecords, page, hasMore }, data typed by the bridge (numbers and booleans converted). startDate/endDate default to the host\'s date range.'
-              : '// result: { columns, data, totalRecords, page, hasMore }. startDate/endDate default to the host\'s date range; numbers and booleans can come back as strings.',
-        ...(bodyExamples ? ['', 'Request examples:', ...Object.values(bodyExamples).map((e) => `- ${e.summary ?? ''}: ${JSON.stringify(e.value)}`)] : []),
-        ...(example?.data?.length ? ['', `Example row: ${JSON.stringify(example.data[0])}`] : []),
-    ]
-        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
-        .join('\n');
-}
-
-/**
- * describe({ report }) for the tool: the list of reports, or one report in full. The specs are cached for a while; when
- * the portal can't be reached, an earlier copy is used if there is one. Without the prod spec, nothing is marked dev only.
- * `rules` is mcp-rules.mjs's createPlatformRules(); without it, no report is marked blocked (the platform's default).
- */
-export function createReportCatalog({ url = SPEC_URL, prodUrl = PROD_SPEC_URL, load = fetchSpec, now = Date.now, rules = async () => ({ rules: FALLBACK }) } = {}) {
-    let cached;
-    async function specs() {
-        if (cached && now() - cached.at < CACHE_MS) return cached;
-        const [dev, prod] = await Promise.allSettled([load(url), load(prodUrl)]);
-        try {
-            if (dev.status === 'rejected') throw dev.reason;
-            const prodNames = prod.status === 'fulfilled' ? new Set(reportsIn(parse(prod.value)).map((r) => r.name)) : cached?.prod;
-            cached = { spec: parse(dev.value), prod: prodNames, at: now() };
-            return cached;
-        } catch (error) {
-            if (cached) return { ...cached, stale: `(The portal couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
-            throw error;
-        }
-    }
-
-    return async function describe({ report } = {}) {
-        let loaded;
-        try {
-            loaded = await specs();
-        } catch (error) {
-            return { ok: false, text: `Couldn't read the analytics API's spec (${error.message}). The reports are documented at ${PORTAL_URL}.` };
-        }
-        const reports = reportsIn(loaded.spec);
-        const platform = await rules();
-        const blocked = platform.rules.analytics.blockedReports;
-        const stale = [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
-        if (report === undefined) return { ok: true, text: list(reports, url, loaded.prod, blocked) + stale };
-
-        const wanted = report.trim().replace(/^\/+|\/+$/g, '').toLowerCase();
-        const found = reports.find((r) => r.name === wanted);
-        if (found) return { ok: true, text: detail(found, loaded.spec, loaded.prod, blocked) + stale };
-        const words = wanted.split('-').filter(Boolean);
-        const close = reports.filter((r) => r.name && words.some((w) => r.name.includes(w))).map((r) => r.name);
-        return { ok: false, text: `No report "${report}" in the analytics API's spec.${close.length ? ` Close: ${close.join(', ')}.` : ''} Call without report for the list.` };
-    };
-}
+// The MCP server's `analytics_reports` tool: which reports app.analytics.report() can call, read from the HawkSearch
+// Analytics API's own OpenAPI spec (the developer portal), so a new report is known as soon as the analytics API
+// documents it. The dev spec, as the MCP only works against the dev platform, which calls the dev analytics API; the
+// prod spec only to mark the reports prod doesn't have yet, which an app can't use once it's live. The platform's
+// rules (mcp-rules.mjs) mark the reports it blocks. The specs are public: no key, no client data.
+import { parse } from 'yaml';
+import { FALLBACK } from './mcp-rules.mjs';
+
+export const SPEC_URL = 'https://developers.analytics.hawksearch.com/dev/openapi.yaml';
+export const PROD_SPEC_URL = 'https://developers.analytics.hawksearch.com/openapi.yaml';
+const PORTAL_URL = 'https://developers.analytics.hawksearch.com/';
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+const DEV_ONLY = 'dev only: not on prod yet, so an app using it fails once it is live';
+const BLOCKED = 'blocked by the platform: apps get 404 report_not_allowed';
+
+/** The notes on one report: dev only, blocked. */
+const marks = (name, prod, blocked) => [prod && !prod.has(name) ? DEV_ONLY : null, blocked.includes(name) ? BLOCKED : null].filter(Boolean);
+
+async function fetchSpec(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.text();
+}
+
+/** The reports in a parsed spec: one per POST path, by the name app.analytics.report() takes ("" for the root). */
+export function reportsIn(spec) {
+    return Object.entries(spec?.paths ?? {})
+        .filter(([, item]) => item?.post)
+        .map(([path, item]) => ({ name: path.replace(/^\/+|\/+$/g, ''), tag: item.post.tags?.[0] ?? 'Other', summary: item.post.summary ?? '', operation: item.post }));
+}
+
+const call = (name) => `app.analytics.report(${JSON.stringify(name)}`;
+const title = (name) => (name === '' ? '"" (the root)' : name);
+
+function list(reports, url, prod, blocked) {
+    const groups = new Map();
+    for (const r of reports) groups.set(r.tag, [...(groups.get(r.tag) ?? []), r]);
+    const lines = [`Analytics reports app.analytics.report(name, request) can call (scope reports:read), from ${url}. Call again with report: "<name>" for its columns, filters and an example.`];
+    for (const [tag, items] of groups) {
+        lines.push('', `## ${tag}`);
+        for (const r of items) {
+            const notes = marks(r.name, prod, blocked);
+            lines.push(`- ${title(r.name)}${notes.length ? ` (${notes.join('; ')})` : ''}: ${r.summary}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/** A request body's examples: inline, or through a $ref to components.requestBodies. */
+function requestExamples(op, spec) {
+    const body = op.requestBody?.$ref ? spec.components?.requestBodies?.[op.requestBody.$ref.split('/').pop()] : op.requestBody;
+    return body?.content?.['application/json']?.examples;
+}
+
+function detail(report, spec, prod, blocked) {
+    const op = report.operation;
+    const example = op.responses?.['200']?.content?.['application/json']?.example;
+    // x-report is the spec's checked list (the analytics API's tests keep it in step); examples can be out of date.
+    const x = op['x-report'];
+    const columns = (x?.columns ?? example?.columns ?? []).map((c) => `${c.name} (${c.type})`);
+    const fields = x && x.kind !== 'write'
+        ? [`filters takes: ${Object.keys(x.filters ?? {}).join(', ') || 'none'}; having takes: ${(x.having ?? []).join(', ') || 'none'}.`]
+        : [];
+    const bodyExamples = requestExamples(op, spec);
+    const sample = report.name === '' ? { query: 'top 10 keywords by searches last week' } : { startDate: '2026-06-01', endDate: '2026-06-30', page: 1, limit: 50 };
+    return [
+        `# ${title(report.name)}: ${report.summary}`,
+        ...marks(report.name, prod, blocked).flatMap((note) => ['', `Note: ${note}.`]),
+        '',
+        (op.description ?? '').trim(),
+        ...(columns.length ? ['', `Columns: ${columns.join(', ')}.`] : []),
+        ...fields,
+        '',
+        'From an app:',
+        `const result = await ${call(report.name)}, ${JSON.stringify(sample)});`,
+        report.name === ''
+            ? ''
+            : x
+              ? '// result: { columns, data, totalRecords, page, hasMore }, data typed by the bridge (numbers and booleans converted). startDate/endDate default to the host\'s date range.'
+              : '// result: { columns, data, totalRecords, page, hasMore }. startDate/endDate default to the host\'s date range; numbers and booleans can come back as strings.',
+        ...(bodyExamples ? ['', 'Request examples:', ...Object.values(bodyExamples).map((e) => `- ${e.summary ?? ''}: ${JSON.stringify(e.value)}`)] : []),
+        ...(example?.data?.length ? ['', `Example row: ${JSON.stringify(example.data[0])}`] : []),
+    ]
+        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
+        .join('\n');
+}
+
+/**
+ * describe({ report }) for the tool: the list of reports, or one report in full. The specs are cached for a while; when
+ * the portal can't be reached, an earlier copy is used if there is one. Without the prod spec, nothing is marked dev only.
+ * `rules` is mcp-rules.mjs's createPlatformRules(); without it, no report is marked blocked (the platform's default).
+ */
+export function createReportCatalog({ url = SPEC_URL, prodUrl = PROD_SPEC_URL, load = fetchSpec, now = Date.now, rules = async () => ({ rules: FALLBACK }) } = {}) {
+    let cached;
+    async function specs() {
+        if (cached && now() - cached.at < CACHE_MS) return cached;
+        const [dev, prod] = await Promise.allSettled([load(url), load(prodUrl)]);
+        try {
+            if (dev.status === 'rejected') throw dev.reason;
+            const prodNames = prod.status === 'fulfilled' ? new Set(reportsIn(parse(prod.value)).map((r) => r.name)) : cached?.prod;
+            cached = { spec: parse(dev.value), prod: prodNames, at: now() };
+            return cached;
+        } catch (error) {
+            if (cached) return { ...cached, stale: `(The portal couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
+            throw error;
+        }
+    }
+
+    return async function describe({ report } = {}) {
+        let loaded;
+        try {
+            loaded = await specs();
+        } catch (error) {
+            return { ok: false, text: `Couldn't read the analytics API's spec (${error.message}). The reports are documented at ${PORTAL_URL}.` };
+        }
+        const reports = reportsIn(loaded.spec);
+        const platform = await rules();
+        const blocked = platform.rules.analytics.blockedReports;
+        const stale = [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
+        if (report === undefined) return { ok: true, text: list(reports, url, loaded.prod, blocked) + stale };
+
+        const wanted = report.trim().replace(/^\/+|\/+$/g, '').toLowerCase();
+        const found = reports.find((r) => r.name === wanted);
+        if (found) return { ok: true, text: detail(found, loaded.spec, loaded.prod, blocked) + stale };
+        const words = wanted.split('-').filter(Boolean);
+        const close = reports.filter((r) => r.name && words.some((w) => r.name.includes(w))).map((r) => r.name);
+        return { ok: false, text: `No report "${report}" in the analytics API's spec.${close.length ? ` Close: ${close.join(', ')}.` : ''} Call without report for the list.` };
+    };
+}

package/src/mcp-rules.mjs

@@ -1,109 +1,109 @@
-// What apps may call, for the MCP server's hawksearch_api and analytics_reports tools: the platform's own
-// GET /meta/rules (the rules in effect there, configuration included), read from the dev platform the MCP deploys to.
-// FALLBACK is the platform's built-in defaults, for when the platform can't be reached (or predates /meta/rules);
-// test/mcp-hawksearch.test.mjs checks it against platform/src. Public: no key, no client data.
-import { PLATFORMS } from './env.mjs';
-
-const CACHE_MS = 10 * 60_000;
-const TIMEOUT_MS = 10_000;
-
-const index = (method, operation, path, scope) => ({ method, operation, path, scope });
-const READ = 'hawksearch:index';
-const ITEMS = 'hawksearch:index:items';
-const MANAGE = 'hawksearch:index:manage';
-
-/** The platform's defaults (HawkSearchOptions, IndexingApiRules, AnalyticsOptions), in /meta/rules' shape. */
-export const FALLBACK = {
-    version: 1,
-    dashboard: {
-        apiVersion: 'v11',
-        writeResources: ['banner', 'boostbury', 'campaign', 'visibility', 'visitortarget', 'redirect', 'synonym', 'spellcheck', 'paginationset', 'sortingset', 'recommendationvisibility', 'landingpagelayout', 'facet', 'landingpage'],
-        maxBulkItems: 1000,
-        maxWriteRequestBytes: 5 * 1024 * 1024,
-        writesPerMinute: 120,
-    },
-    search: { perMinute: 600, maxRequestBytes: 64 * 1024 },
-    recommendations: { available: true, maxBulkWidgets: 10, perMinute: 600 },
-    indexing: {
-        operations: [
-            index('GET', 'indexes', 'api/v2/indexing', READ),
-            index('GET', 'current', 'api/v2/indexing/current', READ),
-            index('GET', 'inactive', 'api/v2/indexing/get-inactive-index', READ),
-            index('POST', 'hierarchy', 'api/hierarchy', READ),
-            index('POST', 'mappings', 'api/mapping', READ),
-            index('GET', 'embedding/progress', 'api/embedding/progress', READ),
-            index('POST', 'index-items', 'api/v2/indexing/index-items', ITEMS),
-            index('POST', 'update-items', 'api/v2/indexing/update-items', ITEMS),
-            index('POST', 'delete', 'api/v2/indexing/delete', ITEMS),
-            index('POST', 'delete-items', 'api/v2/indexing/delete-items', ITEMS),
-            index('POST', 'add-attributes-to-items', 'api/v2/indexing/add-attributes-to-items', ITEMS),
-            index('POST', 'update-attributes-of-items', 'api/v2/indexing/update-attributes-of-items', ITEMS),
-            index('POST', 'remove-attributes-from-items', 'api/v2/indexing/remove-attributes-from-items', ITEMS),
-            index('POST', 'update-nested', 'api/v2/indexing/update-nested', ITEMS),
-            index('POST', 'remove-nested', 'api/v2/indexing/remove-nested', ITEMS),
-            index('POST', 'bulk-update-nested', 'api/v2/indexing/bulk-update-nested', ITEMS),
-            index('POST', 'bulk-remove-nested', 'api/v2/indexing/bulk-remove-nested', ITEMS),
-            index('POST', 'bulk-item-operations', 'api/v2/indexing/bulk-item-operations', ITEMS),
-            index('POST', 'create', 'api/v2/indexing/create', MANAGE),
-            index('POST', 'set-current', 'api/v2/indexing/set-current', MANAGE),
-            index('POST', 'swap', 'api/v2/indexing/swap', MANAGE),
-            index('POST', 'delete-index', 'api/v2/indexing/delete-index', MANAGE),
-            index('POST', 'rebuild-all', 'api/v2/indexing/rebuild-all', MANAGE),
-            index('POST', 'rebuild-autocomplete', 'api/v2/indexing/rebuild-autocomplete', MANAGE),
-            index('POST', 'rebuild-percolator', 'api/v2/indexing/rebuild-percolator', MANAGE),
-            index('POST', 'rebuild-learning', 'api/v2/indexing/rebuild-learning', MANAGE),
-            index('POST', 'rebuild-related', 'api/v2/indexing/rebuild-related', MANAGE),
-            index('POST', 'rebuild-embedding', 'api/v2/indexing/rebuild-embedding', MANAGE),
-            index('POST', 'hierarchy/upsert', 'api/hierarchy/upsert', MANAGE),
-            index('POST', 'hierarchy/rebuild', 'api/hierarchy/rebuild', MANAGE),
-            index('POST', 'hierarchy/delete-items', 'api/hierarchy/delete-items', MANAGE),
-            index('POST', 'hierarchy/delete-all', 'api/hierarchy/delete-all', MANAGE),
-            index('POST', 'mappings/upsert', 'api/mapping/upsert', MANAGE),
-            index('POST', 'mappings/invalidate-cache', 'api/mapping/invalidate-cache', MANAGE),
-            index('GET', 'embedding/status/{id}', 'api/embedding/status/{id}', READ),
-        ],
-        maxItemsPerCall: 125,
-        maxIdsPerCall: 1000,
-        maxRequestBytes: 5 * 1024 * 1024,
-        itemWritesPerMinute: 120,
-        managePerMinute: 10,
-        rebuildsPerMinute: 2,
-    },
-    analytics: { blockedReports: [] },
-};
-
-/** The platform's answer over the fallback, section by section, so a field it doesn't send keeps its default. */
-function merge(rules) {
-    if (!rules || typeof rules !== 'object' || !(rules.version >= 1)) throw new Error('not a rules document');
-    const merged = { ...FALLBACK };
-    for (const [section, defaults] of Object.entries(FALLBACK)) {
-        if (rules[section] && typeof rules[section] === 'object' && typeof defaults === 'object') merged[section] = { ...defaults, ...rules[section] };
-    }
-    return { ...merged, scopes: rules.scopes, version: rules.version };
-}
-
-async function fetchJson(url) {
-    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS), headers: { accept: 'application/json' } });
-    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
-    return response.json();
-}
-
-/**
- * rules() for the tools: { rules, from } from the platform (cached for a while), else the earlier answer, else
- * { rules: FALLBACK, from, note } saying why.
- */
-export function createPlatformRules({ url = PLATFORMS.dev, load = fetchJson, now = Date.now } = {}) {
-    const endpoint = `${url.replace(/\/+$/, '')}/meta/rules`;
-    let cached;
-    return async function rules() {
-        if (cached && now() - cached.at < CACHE_MS) return cached.answer;
-        try {
-            cached = { answer: { rules: merge(await load(endpoint)), from: endpoint }, at: now() };
-            return cached.answer;
-        } catch (error) {
-            if (cached) return { ...cached.answer, note: `(${endpoint} couldn't be read just now: ${error.message}. These are its rules from earlier.)` };
-            // Not cached: the platform is tried again on the next call.
-            return { rules: FALLBACK, from: 'the CLI', note: `(${endpoint} couldn't be read: ${error.message}. These are the platform's default rules, which its configuration can change.)` };
-        }
-    };
-}
+// What apps may call, for the MCP server's hawksearch_api and analytics_reports tools: the platform's own
+// GET /meta/rules (the rules in effect there, configuration included), read from the dev platform the MCP deploys to.
+// FALLBACK is the platform's built-in defaults, for when the platform can't be reached (or predates /meta/rules);
+// test/mcp-hawksearch.test.mjs checks it against platform/src. Public: no key, no client data.
+import { PLATFORMS } from './env.mjs';
+
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+
+const index = (method, operation, path, scope) => ({ method, operation, path, scope });
+const READ = 'hawksearch:index';
+const ITEMS = 'hawksearch:index:items';
+const MANAGE = 'hawksearch:index:manage';
+
+/** The platform's defaults (HawkSearchOptions, IndexingApiRules, AnalyticsOptions), in /meta/rules' shape. */
+export const FALLBACK = {
+    version: 1,
+    dashboard: {
+        apiVersion: 'v11',
+        writeResources: ['banner', 'boostbury', 'campaign', 'visibility', 'visitortarget', 'redirect', 'synonym', 'spellcheck', 'paginationset', 'sortingset', 'recommendationvisibility', 'landingpagelayout', 'facet', 'landingpage'],
+        maxBulkItems: 1000,
+        maxWriteRequestBytes: 5 * 1024 * 1024,
+        writesPerMinute: 120,
+    },
+    search: { perMinute: 600, maxRequestBytes: 64 * 1024 },
+    recommendations: { available: true, maxBulkWidgets: 10, perMinute: 600 },
+    indexing: {
+        operations: [
+            index('GET', 'indexes', 'api/v2/indexing', READ),
+            index('GET', 'current', 'api/v2/indexing/current', READ),
+            index('GET', 'inactive', 'api/v2/indexing/get-inactive-index', READ),
+            index('POST', 'hierarchy', 'api/hierarchy', READ),
+            index('POST', 'mappings', 'api/mapping', READ),
+            index('GET', 'embedding/progress', 'api/embedding/progress', READ),
+            index('POST', 'index-items', 'api/v2/indexing/index-items', ITEMS),
+            index('POST', 'update-items', 'api/v2/indexing/update-items', ITEMS),
+            index('POST', 'delete', 'api/v2/indexing/delete', ITEMS),
+            index('POST', 'delete-items', 'api/v2/indexing/delete-items', ITEMS),
+            index('POST', 'add-attributes-to-items', 'api/v2/indexing/add-attributes-to-items', ITEMS),
+            index('POST', 'update-attributes-of-items', 'api/v2/indexing/update-attributes-of-items', ITEMS),
+            index('POST', 'remove-attributes-from-items', 'api/v2/indexing/remove-attributes-from-items', ITEMS),
+            index('POST', 'update-nested', 'api/v2/indexing/update-nested', ITEMS),
+            index('POST', 'remove-nested', 'api/v2/indexing/remove-nested', ITEMS),
+            index('POST', 'bulk-update-nested', 'api/v2/indexing/bulk-update-nested', ITEMS),
+            index('POST', 'bulk-remove-nested', 'api/v2/indexing/bulk-remove-nested', ITEMS),
+            index('POST', 'bulk-item-operations', 'api/v2/indexing/bulk-item-operations', ITEMS),
+            index('POST', 'create', 'api/v2/indexing/create', MANAGE),
+            index('POST', 'set-current', 'api/v2/indexing/set-current', MANAGE),
+            index('POST', 'swap', 'api/v2/indexing/swap', MANAGE),
+            index('POST', 'delete-index', 'api/v2/indexing/delete-index', MANAGE),
+            index('POST', 'rebuild-all', 'api/v2/indexing/rebuild-all', MANAGE),
+            index('POST', 'rebuild-autocomplete', 'api/v2/indexing/rebuild-autocomplete', MANAGE),
+            index('POST', 'rebuild-percolator', 'api/v2/indexing/rebuild-percolator', MANAGE),
+            index('POST', 'rebuild-learning', 'api/v2/indexing/rebuild-learning', MANAGE),
+            index('POST', 'rebuild-related', 'api/v2/indexing/rebuild-related', MANAGE),
+            index('POST', 'rebuild-embedding', 'api/v2/indexing/rebuild-embedding', MANAGE),
+            index('POST', 'hierarchy/upsert', 'api/hierarchy/upsert', MANAGE),
+            index('POST', 'hierarchy/rebuild', 'api/hierarchy/rebuild', MANAGE),
+            index('POST', 'hierarchy/delete-items', 'api/hierarchy/delete-items', MANAGE),
+            index('POST', 'hierarchy/delete-all', 'api/hierarchy/delete-all', MANAGE),
+            index('POST', 'mappings/upsert', 'api/mapping/upsert', MANAGE),
+            index('POST', 'mappings/invalidate-cache', 'api/mapping/invalidate-cache', MANAGE),
+            index('GET', 'embedding/status/{id}', 'api/embedding/status/{id}', READ),
+        ],
+        maxItemsPerCall: 125,
+        maxIdsPerCall: 1000,
+        maxRequestBytes: 5 * 1024 * 1024,
+        itemWritesPerMinute: 120,
+        managePerMinute: 10,
+        rebuildsPerMinute: 2,
+    },
+    analytics: { blockedReports: [] },
+};
+
+/** The platform's answer over the fallback, section by section, so a field it doesn't send keeps its default. */
+function merge(rules) {
+    if (!rules || typeof rules !== 'object' || !(rules.version >= 1)) throw new Error('not a rules document');
+    const merged = { ...FALLBACK };
+    for (const [section, defaults] of Object.entries(FALLBACK)) {
+        if (rules[section] && typeof rules[section] === 'object' && typeof defaults === 'object') merged[section] = { ...defaults, ...rules[section] };
+    }
+    return { ...merged, scopes: rules.scopes, version: rules.version };
+}
+
+async function fetchJson(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS), headers: { accept: 'application/json' } });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.json();
+}
+
+/**
+ * rules() for the tools: { rules, from } from the platform (cached for a while), else the earlier answer, else
+ * { rules: FALLBACK, from, note } saying why.
+ */
+export function createPlatformRules({ url = PLATFORMS.dev, load = fetchJson, now = Date.now } = {}) {
+    const endpoint = `${url.replace(/\/+$/, '')}/meta/rules`;
+    let cached;
+    return async function rules() {
+        if (cached && now() - cached.at < CACHE_MS) return cached.answer;
+        try {
+            cached = { answer: { rules: merge(await load(endpoint)), from: endpoint }, at: now() };
+            return cached.answer;
+        } catch (error) {
+            if (cached) return { ...cached.answer, note: `(${endpoint} couldn't be read just now: ${error.message}. These are its rules from earlier.)` };
+            // Not cached: the platform is tried again on the next call.
+            return { rules: FALLBACK, from: 'the CLI', note: `(${endpoint} couldn't be read: ${error.message}. These are the platform's default rules, which its configuration can change.)` };
+        }
+    };
+}