@taiga-ai/mcp-server 0.25.0-rc.472 → 0.26.0-dev.479

package/src/tools/sections.test.ts

@@ -1,143 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  applySectionEdit,
-  budgetSections,
-  instructionsText,
-  pickSections,
-  sectionContent,
-  sectionsOf,
-  stripProvenance,
-} from './sections.js';
-
-describe('sectionsOf', () => {
-  it('returns the sections map of a section-shaped document', () => {
-    expect(sectionsOf({ sections: { a: { content: 'x' } } })).toEqual({ a: { content: 'x' } });
-  });
-
-  it('returns null for documents that keep their content elsewhere', () => {
-    expect(sectionsOf({ components: {} })).toBeNull();
-    expect(sectionsOf({ sections: 'text' })).toBeNull();
-    expect(sectionsOf({ sections: ['a'] })).toBeNull();
-  });
-});
-
-describe('sectionContent', () => {
-  it('reads object and bare-string sections alike', () => {
-    expect(sectionContent({ a: { content: 'x' } }, 'a')).toBe('x');
-    expect(sectionContent({ a: 'plain' }, 'a')).toBe('plain');
-  });
-
-  it('is empty for a section without text and null for a missing or null one', () => {
-    expect(sectionContent({ a: { priority: 'core' } }, 'a')).toBe('');
-    expect(sectionContent({}, 'a')).toBeNull();
-    expect(sectionContent({ a: null }, 'a')).toBeNull();
-  });
-});
-
-describe('applySectionEdit', () => {
-  const sections = {
-    summary: { source: 'template', priority: 'core', content: 'old', derivedFrom: ['doc-1'] },
-    scope: 'bare string',
-    list: ['not', 'a', 'section'],
-  };
-
-  it('replaces the text and keeps the section metadata and the other sections', () => {
-    expect(applySectionEdit(sections, 'summary', 'new')).toEqual({
-      summary: { source: 'template', priority: 'core', content: 'new', derivedFrom: ['doc-1'] },
-      scope: 'bare string',
-      list: ['not', 'a', 'section'],
-    });
-  });
-
-  it('turns a bare-string or array-valued section into an object with the new text', () => {
-    expect(applySectionEdit(sections, 'scope', 'new')['scope']).toEqual({ content: 'new' });
-    expect(applySectionEdit(sections, 'list', 'new')['list']).toEqual({ content: 'new' });
-  });
-
-  it('adds a section that did not exist', () => {
-    expect(applySectionEdit(sections, 'retention', 'keep 90 days')['retention']).toEqual({ content: 'keep 90 days' });
-  });
-
-  it('does not mutate its input', () => {
-    applySectionEdit(sections, 'summary', 'new');
-
-    expect(sections.summary.content).toBe('old');
-  });
-});
-
-describe('instructionsText', () => {
-  it('joins every non-empty object section and skips bare strings, as the API extractor does', () => {
-    expect(
-      instructionsText({
-        instructions: { content: ' Use pnpm. ' },
-        legacy: 'bare text the agents never receive',
-        empty: { content: '   ' },
-        deploys: { content: 'Deploy on Tuesdays.' },
-      })
-    ).toBe('Use pnpm.\n\nDeploy on Tuesdays.');
-  });
-
-  it('is null when nothing is readable', () => {
-    expect(instructionsText({ empty: { content: '' }, legacy: 'x' })).toBeNull();
-  });
-});
-
-describe('stripProvenance', () => {
-  it('drops the derived-from tree and outdated sources at the top and in every section', () => {
-    const doc = {
-      id: 'd1',
-      type: 'policy_security',
-      derivedFrom: { sources: [{ type: 'business_goals', version: 2 }] },
-      outdated: { sources: [] },
-      data: {
-        version: '1.0.0',
-        sections: {
-          summary: { source: 'template', priority: 'core', content: 'x', derivedFrom: ['business_goals'] },
-          legacy: 'bare text',
-        },
-      },
-    };
-
-    expect(stripProvenance(doc)).toEqual({
-      id: 'd1',
-      type: 'policy_security',
-      data: {
-        version: '1.0.0',
-        sections: { summary: { source: 'template', priority: 'core', content: 'x' }, legacy: 'bare text' },
-      },
-    });
-  });
-
-  it('leaves a document that is not made of sections alone', () => {
-    const doc = { id: 'd2', type: 'ui_direction', data: { picks: { palette: 'ocean' } } };
-
-    expect(stripProvenance(doc)).toEqual(doc);
-  });
-});
-
-describe('budgetSections and pickSections', () => {
-  // Parsed, as the API's JSON arrives: an own "__proto__" key, not a prototype.
-  const doc = JSON.parse(
-    '{"data":{"sections":{"__proto__":{"content":"aaaa"},"constructor":{"content":"bbbb"},"toString":{"content":"cccc"}}}}'
-  ) as Record<string, unknown>;
-
-  it('keeps a section named like an Object.prototype member as an ordinary section', () => {
-    const cut = budgetSections(doc, 8)!;
-    const kept = (cut.doc.data as { sections: Record<string, unknown> }).sections;
-
-    expect(Object.keys(kept)).toEqual(['__proto__', 'constructor']);
-    expect(Object.getPrototypeOf(kept)).toBe(Object.prototype);
-    expect(cut.omittedSections).toEqual([{ id: 'toString', characters: 4 }]);
-  });
-
-  it('lists every section not picked, including one named like a prototype member', () => {
-    const cut = pickSections(doc, new Set(['toString']))!;
-
-    expect(cut.omittedSections.map((s) => s.id)).toEqual(['__proto__', 'constructor']);
-  });
-
-  it('answers null for a document that is not made of sections', () => {
-    expect(budgetSections({ data: { legacy: 'x' } }, 10)).toBeNull();
-    expect(pickSections({ data: { legacy: 'x' } }, new Set(['a']))).toBeNull();
-  });
-});

package/src/tools/sections.ts

@@ -1,287 +0,0 @@
-/**
- * How a section edit changes a document's `data`.
- *
- * Policies, organization instructions and factory instructions keep their
- * content under `data.sections`, one entry per section id. An edit replaces
- * that section's text and nothing else: `priority` (ordering), `source` and
- * `derivedFrom` (which reference documents shaped it, PRO-2158) stay, so the
- * next derivation does not re-add what an earlier one already brought in.
- * Same rule as the web editor (apps/web/src/features/organization/lib/
- * policySectionEdits.ts); the two must agree or a draft saved from one
- * surface loses what the other preserved.
- */
-
-import type { CallToolResult } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import { CONTROL_ID_SOURCE, isControlId, policyNamedByControl, policyTypeForControl } from '@taiga/types';
-import { toolError, toolResult } from './errors.js';
-
-/** A document's section map, keyed by section id: each value a `StoredSection` or (older rows) a bare string. */
-export type Sections = Record<string, unknown>;
-
-/** A section stored as an object: its text and the metadata an edit keeps. */
-export interface StoredSection {
-  content?: unknown;
-  title?: unknown;
-  priority?: unknown;
-  [key: string]: unknown;
-}
-
-/** A document's `data`: a section-shaped document keeps its content under `sections`. */
-export interface DocumentData {
-  sections?: unknown;
-  [key: string]: unknown;
-}
-
-/** A document as these helpers read it: its `data` and the provenance a reader does not need. */
-export interface StoredDocument {
-  data?: unknown;
-  derivedFrom?: unknown;
-  outdated?: unknown;
-  [key: string]: unknown;
-}
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/** A section stored as an object rather than a bare string. */
-export function isSectionObject(value: unknown): value is StoredSection {
-  return isRecord(value);
-}
-
-/** The `sections` map of a document, or null when the document is not section-shaped. */
-export function sectionsOf(data: DocumentData): Sections | null {
-  return isRecord(data.sections) ? data.sections : null;
-}
-
-/** The text of one section, or null when the section does not exist. */
-export function sectionContent(sections: Sections, sectionId: string): string | null {
-  const section = sections[sectionId];
-  if (section === undefined || section === null) return null;
-  if (typeof section === 'string') return section;
-  return isSectionObject(section) && typeof section.content === 'string' ? section.content : '';
-}
-
-/** The map with one section's text replaced (or the section added); every other section untouched. */
-export function applySectionEdit(sections: Sections, sectionId: string, content: string): Sections {
-  const prior = sections[sectionId];
-  return { ...sections, [sectionId]: isRecord(prior) ? { ...prior, content } : { content } };
-}
-
-/**
- * A document for reading, without its provenance: the top-level `derivedFrom`
- * tree and `outdated` source list (PRO-2359), and each section's own
- * `derivedFrom` (PRO-2158). They say which documents shaped this one, which
- * the editor needs and a reader does not; `source` and `priority` stay, the
- * server instructions explain them.
- */
-export function stripProvenance<T extends StoredDocument>(doc: T): Omit<T, 'derivedFrom' | 'outdated'> {
-  const { derivedFrom: _derivedFrom, outdated: _outdated, ...rest } = doc;
-  // `rest` holds the same `data`; read through `doc`, whose type still names it.
-  const { data } = doc;
-  if (!isRecord(data)) return rest;
-  const sections = sectionsOf(data);
-  if (!sections) return rest;
-  const stripped = Object.fromEntries(
-    Object.entries(sections).map(([id, section]) => {
-      if (!isRecord(section)) return [id, section];
-      const { derivedFrom: _sectionDerivedFrom, ...keep } = section;
-      return [id, keep];
-    })
-  );
-  return { ...rest, data: { ...data, sections: stripped } };
-}
-
-/**
- * The free-form text of an instructions document, the way the API hands it
- * to the agents (factory-instructions.ts: every non-empty section, in order,
- * joined by a blank line). Null when there is nothing to read.
- */
-export function instructionsText(sections: Sections): string | null {
-  const parts: string[] = [];
-  for (const section of Object.values(sections)) {
-    // Object sections only, as the API's extractor reads them: a bare-string
-    // row the agents never receive is not handed to the model here either.
-    const content = isSectionObject(section) ? section.content : undefined;
-    if (typeof content === 'string' && content.trim()) parts.push(content.trim());
-  }
-  const text = parts.join('\n\n').trim();
-  return text || null;
-}
-
-/** A document cut to some of its sections, and the ones left out with their sizes. */
-export interface SectionCut {
-  doc: StoredDocument;
-  omittedSections: { id: string; characters: number }[];
-}
-
-function cutTo(doc: StoredDocument, sections: Sections, kept: Sections): SectionCut {
-  const omittedSections = Object.keys(sections)
-    .filter((id) => !Object.hasOwn(kept, id))
-    .map((id) => ({ id, characters: sectionContent(sections, id)?.length ?? 0 }));
-  return { doc: { ...doc, data: { ...(doc.data as DocumentData), sections: kept } }, omittedSections };
-}
-
-/**
- * The named sections of a section-shaped document, in the order the API
- * returns them (a jsonb column: shorter ids first, then by bytes, not the
- * order a person wrote them);
- * every other section is listed with its size so the reader knows what else
- * there is. Null when the document is not made of sections.
- */
-export function pickSections(doc: StoredDocument, ids: ReadonlySet<string>): SectionCut | null {
-  const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
-  if (!sections) return null;
-  return cutTo(doc, sections, Object.fromEntries(Object.entries(sections).filter(([id]) => ids.has(id))));
-}
-
-/**
- * As many whole sections as fit `budget` characters of text, the rest listed
- * with their sizes so the reader can ask for them by id. Whole, never cut: a
- * section's text is one argument, and half of it reads as all of it. Not "the
- * opening": the document's own order is not in the data (a jsonb column
- * hands back shorter ids first), so a section that does not fit is skipped
- * and a later, smaller one may still be carried. Null when the document is
- * not made of sections.
- */
-export function budgetSections(doc: StoredDocument, budget: number): SectionCut | null {
-  const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
-  if (!sections) return null;
-  // Entries, not assignment: a section id is text, and `kept["__proto__"] = x` would set a prototype.
-  const kept: [string, unknown][] = [];
-  let used = 0;
-  for (const id of Object.keys(sections)) {
-    const length = sectionContent(sections, id)?.length ?? 0;
-    if (used + length > budget) continue;
-    kept.push([id, sections[id]]);
-    used += length;
-  }
-  return cutTo(doc, sections, Object.fromEntries(kept));
-}
-
-/**
- * The `sections` input of a document read: some sections by id, none for the
- * outline (every id with its size and no text), or omitted for the whole.
- */
-export const sectionsInput = z
-  .array(z.string().min(1).max(200))
-  .max(50)
-  .optional()
-  .describe(
-    'Only these sections, by id; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
-  );
-
-/** The sections input of a company document, where a policy control id also names the sections that state it. */
-export const policySectionsInput = sectionsInput.describe(
-  'Only these sections, by id, or a policy control id (SEC-5.1) for the sections that state it; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
-);
-
-/**
- * The sections that state each control id asked for (PRO-2800): policy
- * standing cites SEC-5.1, and the section holding it has an id of its own
- * (secretsManagement) an agent could only guess. A control id is found in
- * the sections' text, matched as a whole id so SEC-5.1 is not SEC-5.10.
- */
-function controlSections(sections: Sections, ids: readonly string[]): Record<string, string[]> {
-  const found: Record<string, string[]> = {};
-  for (const id of ids) {
-    // The API's control vocabulary, overlay families included (TEL-TIC-1.1, HC-FI-DATA-1.1).
-    if (!isControlId(id) || Object.hasOwn(sections, id)) continue;
-    // Whole id only: not SEC-5.10, SEC-5.1.2, SEC-5.1A or SEC-5.1-appendix; a sentence's full stop is fine.
-    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`(^|[^A-Za-z0-9.-])${escaped}(?![A-Za-z0-9-]|\\.[A-Za-z0-9])`);
-    const holders = Object.keys(sections).filter((sectionId) =>
-      pattern.test(sectionContent(sections, sectionId) ?? '')
-    );
-    if (holders.length > 0) found[id] = holders;
-  }
-  return found;
-}
-
-/**
- * A policy outline names the controls each section states (PRO-2800): a reviewer guessed secretsManagement from its
- * name, which works for secrets and not for "what covers logging of secret access". Read off each section's text.
- */
-function withControls(outline: { id: string; characters: number }[], sections: Sections, policyType: unknown) {
-  // The first cell of a control table row, as the API reads a policy's controls (policy-controls.ts CONTROL_ROW):
-  // not AES-256 in prose, nor "see SEC-5.1" in a section that only cites it.
-  // A reserved row (_Reserved_) is a retired id, not a control, as heldControlMap skips it.
-  const pattern = new RegExp(`^\\|\\s*(${CONTROL_ID_SOURCE})\\s*\\|\\s*(.*?)\\s*(?:\\||$)`, 'gm');
-  return outline.map((entry) => {
-    const text = sectionContent(sections, entry.id) ?? '';
-    const ids = [
-      ...new Set(
-        [...text.matchAll(pattern)]
-          .filter((match) => !/^_?Reserved_?/i.test(match[2] ?? ''))
-          .map((match) => match[1]!)
-          // A base control belongs to the policy its prefix names: an SEC row in the data policy is a stale mention,
-          // as heldControlMap reads it. An overlay prefix stays where it is written.
-          .filter((id) => {
-            const owner = policyTypeForControl(id);
-            return owner === undefined || owner === policyType;
-          })
-      ),
-    ];
-    return ids.length > 0 ? { ...entry, controls: ids } : entry;
-  });
-}
-
-/**
- * The answer to a read that names sections: the ones the document has, the
- * rest listed with their sizes, and the asked-for ids it lacks under
- * unknownSections. One shape whatever matched (PRO-2778): a wrong id does not
- * throw away the right ones, and an answer with none right still lists every
- * real id with its size, so the retry needs nothing else. No ids is the
- * outline.
- */
-export function sectionReadResult(
-  doc: StoredDocument,
-  asked: readonly string[],
-  label: string,
-  /** Policies are where control ids are stated; elsewhere one is an unknown id with a pointer. */
-  options: { controlIds?: boolean } = {}
-): CallToolResult {
-  const before = sectionsOf(doc.data as DocumentData);
-  const controls = before && options.controlIds ? controlSections(before, asked) : {};
-  // A control id reads the sections that state it; the id is then not unknown.
-  const ids = [...new Set([...asked.filter((id) => !Object.hasOwn(controls, id)), ...Object.values(controls).flat()])];
-  const cut = pickSections(doc, new Set(ids));
-  if (!cut) return toolError('VALIDATION_ERROR', `The ${label} is not made of sections; read it without sections.`);
-  const all = Object.keys(sectionsOf(doc.data as DocumentData) ?? {});
-  const unknownSections = ids.filter((id) => !all.includes(id));
-  const known = ids.filter((id) => all.includes(id));
-  const found = Object.keys(controls).length > 0 ? { controls } : {};
-  // A control id asked of a document that does not state controls: name the policy that does.
-  const asControl = options.controlIds ? undefined : unknownSections.find((id) => isControlId(id));
-  const policy = asControl ? policyNamedByControl(asControl) : undefined;
-  const controlNote = asControl
-    ? {
-        note: policy
-          ? `${asControl} is a control of ${policy}: read it with taiga_get_document (type: ${policy}, sections: ["${asControl}"]).`
-          : `${asControl} looks like a policy control id, which only a policy resolves: taiga_get_document without type lists them.`,
-      }
-    : {};
-  if (known.length === 0) {
-    // The outline, or a read naming only ids the document lacks: no text to
-    // carry, so no empty data.sections beside the ids, which read as a
-    // document with no sections (PRO-2800).
-    const { data: _data, ...meta } = cut.doc;
-    return toolResult({
-      ...meta,
-      outline:
-        options.controlIds && before
-          ? withControls(cut.omittedSections, before, (doc as { type?: unknown }).type)
-          : cut.omittedSections,
-      ...(unknownSections.length > 0 ? { unknownSections } : {}),
-      ...controlNote,
-    });
-  }
-  return toolResult({
-    ...cut.doc,
-    ...found,
-    omittedSections: cut.omittedSections,
-    ...(unknownSections.length > 0 ? { unknownSections } : {}),
-    ...controlNote,
-  });
-}