@ctcstack/ctcdocs-core 0.18.0 → 0.20.0

package/dist/corpus-structure.d.ts

@@ -19,6 +19,8 @@ export interface CorpusDocument {
      * on its new chain to be confirmed.
      */
     readonly publishedReaders?: '*' | readonly string[];
+    /** Set while such a move waits, as the manifest's `readersHeld` says. */
+    readonly readersHeld?: true;
     /** The permanent short ID (ADR-022), the title and Drive's modified time. */
     readonly shortId?: string;
     readonly title?: string;

package/dist/corpus-structure.js

@@ -74,6 +74,9 @@ export function parseCorpusStructure(manifest) {
             ...(title ? { title } : {}),
             ...(modified ? { modified } : {}),
             ...(source ? { source } : {}),
+            ...(typeof record.readersHeld === 'object' && record.readersHeld !== null
+                ? { readersHeld: true }
+                : {}),
             ...(published === '*' ||
                 (Array.isArray(published) &&
                     published.every((group) => typeof group === 'string'))

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/project-layout.d.ts

@@ -26,6 +26,8 @@ export declare const PROJECT_LAYOUT: {
     readonly publicDirectory: "public";
     readonly robotsFile: "public/robots.txt";
     readonly headersFile: "public/_headers";
+    /** The pages a project writes by hand; generated ones sit beneath, apart. */
+    readonly documentsDirectory: "src/content/docs";
     /** Generated Markdown, one directory per Drive folder. */
     readonly generatedDocumentsDirectory: "src/content/docs/_generated";
     /** Original images, one directory per Google file identifier. */
@@ -68,6 +70,11 @@ export declare const PLATFORM_ROUTES: {
      * docs/ADR/024-content-health-page.md.
      */
     readonly contentHealth: "content-health";
+    /**
+     * Who may read each folder, for admins. See
+     * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+     */
+    readonly accessReview: "access-review";
 };
 /**
  * The platform's Workers, as a project's Wrangler configuration names them
@@ -100,6 +107,7 @@ export declare const ACCESS_CLASSES_ROUTE = "/_kb/classes";
 export declare const PLATFORM_ROUTE_HREFS: {
     readonly fullIndex: "/documents/";
     readonly contentHealth: "/content-health/";
+    readonly accessReview: "/access-review/";
 };
 export declare const RESERVED_SLUGS: readonly string[];
 /**

package/dist/project-layout.js

@@ -26,6 +26,8 @@ export const PROJECT_LAYOUT = {
     publicDirectory: 'public',
     robotsFile: 'public/robots.txt',
     headersFile: 'public/_headers',
+    /** The pages a project writes by hand; generated ones sit beneath, apart. */
+    documentsDirectory: 'src/content/docs',
     /** Generated Markdown, one directory per Drive folder. */
     generatedDocumentsDirectory: 'src/content/docs/_generated',
     /** Original images, one directory per Google file identifier. */
@@ -68,6 +70,11 @@ export const PLATFORM_ROUTES = {
      * docs/ADR/024-content-health-page.md.
      */
     contentHealth: 'content-health',
+    /**
+     * Who may read each folder, for admins. See
+     * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+     */
+    accessReview: 'access-review',
 };
 /**
  * The platform's Workers, as a project's Wrangler configuration names them
@@ -100,6 +107,7 @@ export const ACCESS_CLASSES_ROUTE = '/_kb/classes';
 export const PLATFORM_ROUTE_HREFS = {
     fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
     contentHealth: `/${PLATFORM_ROUTES.contentHealth}/`,
+    accessReview: `/${PLATFORM_ROUTES.accessReview}/`,
 };
 /**
  * Top-level addresses the platform serves beside the corpus: the Worker's

package/dist/site-configuration.d.ts

@@ -33,6 +33,14 @@ export interface HomeConfiguration {
      * outgrown one page may prefer the home page to stay an entrance.
      */
     readonly corpusIndex: boolean;
+    /**
+     * The address of the hand-authored page the home page sends a newcomer to,
+     * as a slug: `about` for `src/content/docs/about.md`. The link reads that
+     * page's own title, so renaming the page renames the link. Without it the
+     * home page offers no such link: the platform does not know what a
+     * deployment calls its introduction, or whether it has one.
+     */
+    readonly start?: string;
 }
 /**
  * Who a deployment is for.
@@ -177,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
@@ -187,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';
 }
@@ -121,6 +121,21 @@ function flag(source, key, path) {
 function optionalFlag(source, key, path, fallback) {
     return source[key] === undefined ? fallback : flag(source, key, path);
 }
+/**
+ * A page's address as Starlight derives it from a file under
+ * `src/content/docs`: lowercase segments joined by `/`, with no leading or
+ * trailing slash, so it is the same string the content collection knows.
+ */
+function optionalPageSlug(source, key, path) {
+    if (source[key] === undefined) {
+        return {};
+    }
+    const value = text(source, key, path);
+    if (!/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(value)) {
+        fail(path, 'must be a page address such as "about", without slashes at either end');
+    }
+    return { [key]: value };
+}
 /**
  * A list of distinct Unicode script names, as a `\p{Script=…}` property
  * escape spells them. Each name is proved by compiling that escape, so a typo
@@ -231,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) {
@@ -378,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) {
@@ -392,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);
@@ -405,6 +445,7 @@ export function parseSiteConfiguration(input) {
             corpusIndex: optionalFlag(homeSource, 'corpusIndex', 'home.corpusIndex', true),
             lede: text(homeSource, 'lede', 'home.lede'),
             recentLimit: optionalCount(homeSource, 'recentLimit', 'home.recentLimit', 6),
+            ...optionalPageSlug(homeSource, 'start', 'home.start'),
         },
         navigation: {
             landingDocumentTitles: titleList(navigationSource, 'landingDocumentTitles', 'navigation.landingDocumentTitles'),

package/package.json

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

package/src/corpus-structure.ts

@@ -33,6 +33,8 @@ export interface CorpusDocument {
    * on its new chain to be confirmed.
    */
   readonly publishedReaders?: '*' | readonly string[];
+  /** Set while such a move waits, as the manifest's `readersHeld` says. */
+  readonly readersHeld?: true;
   /** The permanent short ID (ADR-022), the title and Drive's modified time. */
   readonly shortId?: string;
   readonly title?: string;
@@ -125,6 +127,9 @@ export function parseCorpusStructure(manifest: unknown): CorpusStructure {
       ...(title ? { title } : {}),
       ...(modified ? { modified } : {}),
       ...(source ? { source } : {}),
+      ...(typeof record.readersHeld === 'object' && record.readersHeld !== null
+        ? { readersHeld: true as const }
+        : {}),
       ...(published === '*' ||
       (Array.isArray(published) &&
         published.every((group) => typeof group === 'string'))

package/src/index.ts

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

package/src/project-layout.ts

@@ -26,6 +26,8 @@ export const PROJECT_LAYOUT = {
   publicDirectory: 'public',
   robotsFile: 'public/robots.txt',
   headersFile: 'public/_headers',
+  /** The pages a project writes by hand; generated ones sit beneath, apart. */
+  documentsDirectory: 'src/content/docs',
   /** Generated Markdown, one directory per Drive folder. */
   generatedDocumentsDirectory: 'src/content/docs/_generated',
   /** Original images, one directory per Google file identifier. */
@@ -69,6 +71,11 @@ export const PLATFORM_ROUTES = {
    * docs/ADR/024-content-health-page.md.
    */
   contentHealth: 'content-health',
+  /**
+   * Who may read each folder, for admins. See
+   * docs/ADR/045-an-access-review-page-shows-admins-who-may-read-each-folder.md.
+   */
+  accessReview: 'access-review',
 } as const;
 
 /**
@@ -104,6 +111,7 @@ export const ACCESS_CLASSES_ROUTE = '/_kb/classes';
 export const PLATFORM_ROUTE_HREFS = {
   fullIndex: `/${PLATFORM_ROUTES.fullIndex}/`,
   contentHealth: `/${PLATFORM_ROUTES.contentHealth}/`,
+  accessReview: `/${PLATFORM_ROUTES.accessReview}/`,
 } as const;
 
 /**

package/src/site-configuration.ts

@@ -55,6 +55,14 @@ export interface HomeConfiguration {
    * outgrown one page may prefer the home page to stay an entrance.
    */
   readonly corpusIndex: boolean;
+  /**
+   * The address of the hand-authored page the home page sends a newcomer to,
+   * as a slug: `about` for `src/content/docs/about.md`. The link reads that
+   * page's own title, so renaming the page renames the link. Without it the
+   * home page offers no such link: the platform does not know what a
+   * deployment calls its introduction, or whether it has one.
+   */
+  readonly start?: string;
 }
 
 /**
@@ -209,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
@@ -219,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). */
@@ -233,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 }),
 });
 
 /**
@@ -253,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;
@@ -380,6 +398,29 @@ function optionalFlag(
   return source[key] === undefined ? fallback : flag(source, key, path);
 }
 
+/**
+ * A page's address as Starlight derives it from a file under
+ * `src/content/docs`: lowercase segments joined by `/`, with no leading or
+ * trailing slash, so it is the same string the content collection knows.
+ */
+function optionalPageSlug(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+): Record<string, string> {
+  if (source[key] === undefined) {
+    return {};
+  }
+  const value = text(source, key, path);
+  if (!/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(value)) {
+    fail(
+      path,
+      'must be a page address such as "about", without slashes at either end',
+    );
+  }
+  return { [key]: value };
+}
+
 /**
  * A list of distinct Unicode script names, as a `\p{Script=…}` property
  * escape spells them. Each name is proved by compiling that escape, so a typo
@@ -570,8 +611,37 @@ 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,
   };
 }
 
@@ -775,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) {
@@ -798,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);
@@ -822,6 +906,7 @@ export function parseSiteConfiguration(input: unknown): SiteConfiguration {
         'home.recentLimit',
         6,
       ),
+      ...optionalPageSlug(homeSource, 'start', 'home.start'),
     },
     navigation: {
       landingDocumentTitles: titleList(