@ctcstack/ctcdocs-core 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export type { AccessClass, AccessModel, ChainReaders, PublishedReaders, Readers,
 export { accessFindings } from './access-findings.js';
 export type { AccessFinding } from './access-findings.js';
 export { fetchCharacterLimit, loadSiteConfiguration, MCP_DEFAULTS, parseSiteConfiguration, SiteConfigurationError, } from './site-configuration.js';
-export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, McpConfiguration, McpSearchConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';
+export type { AddressPolicy, BrandConfiguration, DeploymentConfiguration, DeploymentEnvironmentConfiguration, DeploymentEnvironmentConfigurations, DeploymentVisibility, HomeConfiguration, McpConfiguration, McpRecentConfiguration, McpSearchConfiguration, NavigationConfiguration, SignInConfiguration, SiteConfiguration, SyncConfigurationDefaults, } from './site-configuration.js';

package/dist/published-markdown.js

@@ -4,9 +4,13 @@ import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 import { markdownProjectionPath, resolvePermanentLink, } from './project-layout.js';
+/*
+ * Tables are written without padding: one long cell would otherwise pad every
+ * row of its column, and an assistant would read the spaces (ADR-046).
+ */
 const processor = unified()
     .use(remarkParse)
-    .use(remarkGfm)
+    .use(remarkGfm, { tablePipeAlign: false })
     .use(remarkStringify, {
     bullet: '-',
     emphasis: '*',
@@ -43,8 +47,68 @@ function markdownUrl(value, stableSlugs, permanentLinks) {
     }
     return `${markdownProjectionPath(slug)}${url.search}${url.hash}`;
 }
-function rewriteInternalLinks(body, stableSlugs, permanentLinks) {
+/** A table longer than this is split into parts (ADR-046). */
+const SPLIT_TABLE_CHARACTERS = 3_000;
+/** About as long as each part of a split table is, header included. */
+const TABLE_PART_CHARACTERS = 2_000;
+function textLength(node) {
+    if ('value' in node) {
+        return node.value.length;
+    }
+    if ('children' in node) {
+        return node.children.reduce((sum, child) => sum + textLength(child), 0);
+    }
+    return 0;
+}
+/** About how many characters a table row takes, with its pipes. */
+function rowLength(row) {
+    return row.children.reduce((sum, cell) => sum + textLength(cell) + 3, 2);
+}
+/**
+ * Splits each long table into consecutive tables that repeat its header row,
+ * so that a passage search returns from the middle of one still says what each
+ * column is (ADR-046). A table that fits stays whole.
+ */
+function splitLongTables(node) {
+    const children = [];
+    for (const child of node.children) {
+        if ('children' in child && child.type !== 'table') {
+            splitLongTables(child);
+        }
+        if (child.type !== 'table') {
+            children.push(child);
+            continue;
+        }
+        const [header, ...rows] = child.children;
+        const lengths = child.children.map(rowLength);
+        const total = lengths.reduce((sum, length) => sum + length, 0);
+        if (!header || rows.length < 2 || total <= SPLIT_TABLE_CHARACTERS) {
+            children.push(child);
+            continue;
+        }
+        const headerLength = lengths[0] ?? 0;
+        let part = [];
+        let partLength = headerLength;
+        const flush = () => {
+            children.push({ ...child, children: [header, ...part] });
+            part = [];
+            partLength = headerLength;
+        };
+        rows.forEach((row, index) => {
+            const length = lengths[index + 1] ?? 0;
+            if (part.length > 0 && partLength + length > TABLE_PART_CHARACTERS) {
+                flush();
+            }
+            part.push(row);
+            partLength += length;
+        });
+        flush();
+    }
+    node.children = children;
+}
+function projectBody(body, stableSlugs, permanentLinks) {
     const tree = processor.parse(body);
+    splitLongTables(tree);
     walk(tree, (node) => {
         if (node.type === 'link') {
             node.url = markdownUrl(node.url, stableSlugs, permanentLinks) ?? node.url;
@@ -104,7 +168,7 @@ export function inlineMarkdown(value) {
  * `fetch` (ADR-042), so it is also what the sync measures (ADR-043).
  */
 export function publishedMarkdownBody(input) {
-    const body = rewriteInternalLinks(cleanBody(input.body, input.ownershipHeader), input.stableSlugs, input.permanentLinks);
+    const body = projectBody(cleanBody(input.body, input.ownershipHeader), input.stableSlugs, input.permanentLinks);
     return [
         `# ${inlineMarkdown(input.title)}`,
         '',

package/dist/site-configuration.d.ts

@@ -185,6 +185,13 @@ export interface McpSearchConfiguration {
     /** Characters of passage text one search returns at most, in all. */
     readonly passageCharacters: number;
 }
+/** What `recent` lists (ADR-044). */
+export interface McpRecentConfiguration {
+    /** Documents it lists when a call does not ask for a number. */
+    readonly defaultResults: number;
+    /** Documents a call may ask for at most. */
+    readonly results: number;
+}
 /**
  * The MCP server through which AI assistants read the site as the person who
  * connected them (ADR-041). It needs the Worker's sign-in, so it is accepted
@@ -195,6 +202,9 @@ export interface McpConfiguration {
     readonly search: McpSearchConfiguration;
     /** Characters `fetch` returns at most; a longer document is cut there. */
     readonly fetchCharacters: number;
+    /** Characters of JSON a `browse` tree takes at most (ADR-044). */
+    readonly browseCharacters: number;
+    readonly recent: McpRecentConfiguration;
 }
 /** What `mcp` holds when a project sets only `enabled` (ADR-042). */
 export declare const MCP_DEFAULTS: Omit<McpConfiguration, 'enabled'>;

package/dist/site-configuration.js

@@ -27,11 +27,13 @@ export const MCP_DEFAULTS = Object.freeze({
             model: '@cf/baai/bge-reranker-base',
             threshold: 0,
         }),
-        results: 10,
+        results: 15,
         passagesPerResult: 3,
         passageCharacters: 24_000,
     }),
     fetchCharacters: 100_000,
+    browseCharacters: 24_000,
+    recent: Object.freeze({ defaultResults: 20, results: 50 }),
 });
 /**
  * The characters an assistant reads of a document: the cut `fetch` makes
@@ -44,8 +46,6 @@ export function fetchCharacterLimit(mcp) {
 }
 /** About 10,000 tokens of English: a starting value, not a measured one. */
 const LARGE_DOCUMENT_CHARACTERS = 40_000;
-/** A passage of fewer characters than this says too little to judge by. */
-const SHORTEST_PASSAGE = 100;
 export class SiteConfigurationError extends Error {
     name = 'SiteConfigurationError';
 }
@@ -246,7 +246,24 @@ function mcpSearch(value) {
         reranking,
         results,
         passagesPerResult: optionalNumber(source, 'passagesPerResult', 'mcp.search.passagesPerResult', defaults.passagesPerResult, { min: 1, whole: true }),
-        passageCharacters: optionalNumber(source, 'passageCharacters', 'mcp.search.passageCharacters', defaults.passageCharacters, { min: results * SHORTEST_PASSAGE, whole: true }),
+        passageCharacters: optionalNumber(source, 'passageCharacters', 'mcp.search.passageCharacters', defaults.passageCharacters, 
+        // Chunks are shown whole, so the budget answers to the chunk size, not
+        // to the results: those it cannot hold are listed without text.
+        { min: 1_000, whole: true }),
+    };
+}
+function mcpRecent(value) {
+    const defaults = MCP_DEFAULTS.recent;
+    if (value === undefined) {
+        return defaults;
+    }
+    const source = record(value, 'mcp.recent');
+    knownKeys(source, 'mcp.recent', Object.keys(defaults));
+    const results = optionalNumber(source, 'results', 'mcp.recent.results', defaults.results, { min: 1, whole: true });
+    // The default, like a set value, is no more than a call may ask for.
+    return {
+        defaultResults: optionalNumber(source, 'defaultResults', 'mcp.recent.defaultResults', Math.min(defaults.defaultResults, results), { min: 1, max: results, whole: true }),
+        results,
     };
 }
 function optionalMegabytes(source, key, path, fallback) {
@@ -393,7 +410,13 @@ export function parseSiteConfiguration(input) {
     let mcp;
     if (root.mcp !== undefined) {
         const source = record(root.mcp, 'mcp');
-        knownKeys(source, 'mcp', ['enabled', 'search', 'fetchCharacters']);
+        knownKeys(source, 'mcp', [
+            'enabled',
+            'search',
+            'fetchCharacters',
+            'browseCharacters',
+            'recent',
+        ]);
         const enabled = flag(source, 'enabled', 'mcp.enabled');
         if (enabled) {
             if (!signIn) {
@@ -407,6 +430,8 @@ export function parseSiteConfiguration(input) {
             enabled,
             search: mcpSearch(source.search),
             fetchCharacters: optionalNumber(source, 'fetchCharacters', 'mcp.fetchCharacters', MCP_DEFAULTS.fetchCharacters, { min: 1_000, whole: true }),
+            browseCharacters: optionalNumber(source, 'browseCharacters', 'mcp.browseCharacters', MCP_DEFAULTS.browseCharacters, { min: 1_000, whole: true }),
+            recent: mcpRecent(source.recent),
         };
     }
     const fetchLimit = fetchCharacterLimit(mcp);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctcstack/ctcdocs-core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Configuration schema, project layout, generated-path allowlist and the published Markdown form shared by the CTCDocs platform packages.",
   "keywords": [
     "ctcdocs",

package/src/index.ts

@@ -80,6 +80,7 @@ export type {
   DeploymentVisibility,
   HomeConfiguration,
   McpConfiguration,
+  McpRecentConfiguration,
   McpSearchConfiguration,
   NavigationConfiguration,
   SignInConfiguration,

package/src/published-markdown.ts

@@ -1,4 +1,4 @@
-import type { Root, RootContent } from 'mdast';
+import type { Parents, Root, RootContent, Table } from 'mdast';
 import * as cheerio from 'cheerio';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
@@ -10,9 +10,13 @@ import {
   resolvePermanentLink,
 } from './project-layout.js';
 
+/*
+ * Tables are written without padding: one long cell would otherwise pad every
+ * row of its column, and an assistant would read the spaces (ADR-046).
+ */
 const processor = unified()
   .use(remarkParse)
-  .use(remarkGfm)
+  .use(remarkGfm, { tablePipeAlign: false })
   .use(remarkStringify, {
     bullet: '-',
     emphasis: '*',
@@ -83,12 +87,76 @@ function markdownUrl(
   return `${markdownProjectionPath(slug)}${url.search}${url.hash}`;
 }
 
-function rewriteInternalLinks(
+/** A table longer than this is split into parts (ADR-046). */
+const SPLIT_TABLE_CHARACTERS = 3_000;
+/** About as long as each part of a split table is, header included. */
+const TABLE_PART_CHARACTERS = 2_000;
+
+function textLength(node: Root | RootContent): number {
+  if ('value' in node) {
+    return node.value.length;
+  }
+  if ('children' in node) {
+    return node.children.reduce((sum, child) => sum + textLength(child), 0);
+  }
+  return 0;
+}
+
+/** About how many characters a table row takes, with its pipes. */
+function rowLength(row: Table['children'][number]): number {
+  return row.children.reduce((sum, cell) => sum + textLength(cell) + 3, 2);
+}
+
+/**
+ * Splits each long table into consecutive tables that repeat its header row,
+ * so that a passage search returns from the middle of one still says what each
+ * column is (ADR-046). A table that fits stays whole.
+ */
+function splitLongTables(node: Parents): void {
+  const children: RootContent[] = [];
+  for (const child of node.children) {
+    if ('children' in child && child.type !== 'table') {
+      splitLongTables(child);
+    }
+    if (child.type !== 'table') {
+      children.push(child);
+      continue;
+    }
+    const [header, ...rows] = child.children;
+    const lengths = child.children.map(rowLength);
+    const total = lengths.reduce((sum, length) => sum + length, 0);
+    if (!header || rows.length < 2 || total <= SPLIT_TABLE_CHARACTERS) {
+      children.push(child);
+      continue;
+    }
+    const headerLength = lengths[0] ?? 0;
+    let part: Table['children'] = [];
+    let partLength = headerLength;
+    const flush = () => {
+      children.push({ ...child, children: [header, ...part] });
+      part = [];
+      partLength = headerLength;
+    };
+    rows.forEach((row, index) => {
+      const length = lengths[index + 1] ?? 0;
+      if (part.length > 0 && partLength + length > TABLE_PART_CHARACTERS) {
+        flush();
+      }
+      part.push(row);
+      partLength += length;
+    });
+    flush();
+  }
+  node.children = children as Parents['children'];
+}
+
+function projectBody(
   body: string,
   stableSlugs: ReadonlySet<string>,
   permanentLinks: Readonly<Record<string, string>>,
 ): string {
   const tree = processor.parse(body) as Root;
+  splitLongTables(tree);
   walk(tree, (node) => {
     if (node.type === 'link') {
       node.url = markdownUrl(node.url, stableSlugs, permanentLinks) ?? node.url;
@@ -164,7 +232,7 @@ export function publishedMarkdownBody(
     'title' | 'ownershipHeader' | 'body' | 'stableSlugs' | 'permanentLinks'
   >,
 ): string {
-  const body = rewriteInternalLinks(
+  const body = projectBody(
     cleanBody(input.body, input.ownershipHeader),
     input.stableSlugs,
     input.permanentLinks,

package/src/site-configuration.ts

@@ -217,6 +217,14 @@ export interface McpSearchConfiguration {
   readonly passageCharacters: number;
 }
 
+/** What `recent` lists (ADR-044). */
+export interface McpRecentConfiguration {
+  /** Documents it lists when a call does not ask for a number. */
+  readonly defaultResults: number;
+  /** Documents a call may ask for at most. */
+  readonly results: number;
+}
+
 /**
  * The MCP server through which AI assistants read the site as the person who
  * connected them (ADR-041). It needs the Worker's sign-in, so it is accepted
@@ -227,6 +235,9 @@ export interface McpConfiguration {
   readonly search: McpSearchConfiguration;
   /** Characters `fetch` returns at most; a longer document is cut there. */
   readonly fetchCharacters: number;
+  /** Characters of JSON a `browse` tree takes at most (ADR-044). */
+  readonly browseCharacters: number;
+  readonly recent: McpRecentConfiguration;
 }
 
 /** What `mcp` holds when a project sets only `enabled` (ADR-042). */
@@ -241,11 +252,13 @@ export const MCP_DEFAULTS: Omit<McpConfiguration, 'enabled'> = Object.freeze({
       model: '@cf/baai/bge-reranker-base',
       threshold: 0,
     }),
-    results: 10,
+    results: 15,
     passagesPerResult: 3,
     passageCharacters: 24_000,
   }),
   fetchCharacters: 100_000,
+  browseCharacters: 24_000,
+  recent: Object.freeze({ defaultResults: 20, results: 50 }),
 });
 
 /**
@@ -261,9 +274,6 @@ export function fetchCharacterLimit(mcp: McpConfiguration | undefined): number {
 /** About 10,000 tokens of English: a starting value, not a measured one. */
 const LARGE_DOCUMENT_CHARACTERS = 40_000;
 
-/** A passage of fewer characters than this says too little to judge by. */
-const SHORTEST_PASSAGE = 100;
-
 export interface SiteConfiguration {
   /** Required to serve a private environment through the platform's Worker. */
   readonly signIn?: SignInConfiguration;
@@ -601,11 +611,40 @@ function mcpSearch(value: unknown): McpSearchConfiguration {
       'passageCharacters',
       'mcp.search.passageCharacters',
       defaults.passageCharacters,
-      { min: results * SHORTEST_PASSAGE, whole: true },
+      // Chunks are shown whole, so the budget answers to the chunk size, not
+      // to the results: those it cannot hold are listed without text.
+      { min: 1_000, whole: true },
     ),
   };
 }
 
+function mcpRecent(value: unknown): McpRecentConfiguration {
+  const defaults = MCP_DEFAULTS.recent;
+  if (value === undefined) {
+    return defaults;
+  }
+  const source = record(value, 'mcp.recent');
+  knownKeys(source, 'mcp.recent', Object.keys(defaults));
+  const results = optionalNumber(
+    source,
+    'results',
+    'mcp.recent.results',
+    defaults.results,
+    { min: 1, whole: true },
+  );
+  // The default, like a set value, is no more than a call may ask for.
+  return {
+    defaultResults: optionalNumber(
+      source,
+      'defaultResults',
+      'mcp.recent.defaultResults',
+      Math.min(defaults.defaultResults, results),
+      { min: 1, max: results, whole: true },
+    ),
+    results,
+  };
+}
+
 function optionalMegabytes(
   source: Record<string, unknown>,
   key: string,
@@ -806,7 +845,13 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
   let mcp: McpConfiguration | undefined;
   if (root.mcp !== undefined) {
     const source = record(root.mcp, 'mcp');
-    knownKeys(source, 'mcp', ['enabled', 'search', 'fetchCharacters']);
+    knownKeys(source, 'mcp', [
+      'enabled',
+      'search',
+      'fetchCharacters',
+      'browseCharacters',
+      'recent',
+    ]);
     const enabled = flag(source, 'enabled', 'mcp.enabled');
     if (enabled) {
       if (!signIn) {
@@ -829,6 +874,14 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         MCP_DEFAULTS.fetchCharacters,
         { min: 1_000, whole: true },
       ),
+      browseCharacters: optionalNumber(
+        source,
+        'browseCharacters',
+        'mcp.browseCharacters',
+        MCP_DEFAULTS.browseCharacters,
+        { min: 1_000, whole: true },
+      ),
+      recent: mcpRecent(source.recent),
     };
   }
   const fetchLimit = fetchCharacterLimit(mcp);