@taiga-ai/mcp-server 0.25.0-rc.474 → 0.26.0-dev.481

package/src/tools/products.ts

@@ -1,529 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import type { Product, ProductDocumentListItem } from '@taiga/types';
-import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
-import { READ_ONLY } from './annotations.js';
-import { idInput, pagination, productId, remoteUrl, slug } from './inputs.js';
-import {
-  ORIGIN_MEANING,
-  PRODUCT_DOCUMENT_ORIGINS,
-  PRODUCT_DOCUMENT_TYPES,
-  PRODUCT_STATUSES,
-  DISCOVERY_STEP_MEANING,
-  defaultOriginFor,
-  emptyOriginNote,
-  isImportedProduct,
-  productDocumentName,
-  type ProductDocumentOrigin,
-  type ProductSettingsView,
-} from './catalogue.js';
-import {
-  apiFailureCode,
-  apiFailureText,
-  isMissOrRefusal,
-  isNetworkFailure,
-  runTool,
-  toolError,
-  toolResult,
-} from './errors.js';
-import { parseRemote } from './remote.js';
-import { sectionReadResult, sectionsInput, stripProvenance } from './sections.js';
-import { setupReadiness } from './readiness.js';
-import { SEARCH_NOTE, SEARCH_PAGE_SIZE, SEARCH_WITH_CURSOR, page, pickFields, searchPages } from './summarize.js';
-
-type ProductRow = WithoutTenant<Product>;
-type DocumentRow = WithoutTenant<ProductDocumentListItem>;
-
-/** What a product row needs to say for the model to pick one and read it in full. */
-// Not `kind`: it is parked behind a flag that is on nowhere, so every row said null.
-export const PRODUCT_SUMMARY_FIELDS = ['id', 'name', 'slug', 'status', 'factoryId', 'discoveryStep'] as const;
-
-/**
- * Product rows with their factory's name beside its id (PRO-2800): "what
- * products does the organization have" needed a second list to name the
- * factories. One factories read; without factories:read, or when it fails,
- * the rows keep the id alone.
- */
-async function withFactoryNames<T extends { factoryId?: unknown }>(client: TaigaClient, rows: T[]) {
-  if (!client.hasCapability('factories:read') || rows.length === 0) return rows;
-  try {
-    // Every page until the rows' factories are named, up to a bound.
-    const wanted = new Set(rows.map((row) => String(row.factoryId)));
-    const names = new Map<string, string>();
-    let cursor: string | undefined;
-    for (let pageIndex = 0; pageIndex < FACTORY_PAGES; pageIndex += 1) {
-      const result = await client.listFactories({ limit: 100, cursor });
-      for (const factory of result.data) names.set(factory.id, factory.name);
-      if (!result.nextCursor || [...wanted].every((id) => names.has(id))) break;
-      cursor = result.nextCursor;
-    }
-    return rows.map((row) => {
-      const name = names.get(String(row.factoryId));
-      return name === undefined ? row : { ...row, factoryName: name };
-    });
-  } catch (error) {
-    if (error instanceof TaigaApiError || isNetworkFailure(error)) return rows;
-    throw error;
-  }
-}
-
-/** Factory pages read to name products' factories. */
-const FACTORY_PAGES = 10;
-
-/** A list's name search: part of a name, any case. */
-const query = (what: string) =>
-  z.string().trim().min(1).max(200).optional().describe(`Part of the ${what}, any case: only the rows that contain it`);
-
-/**
- * What a document row needs to say for the model to pick one and read it in
- * full: which document, on which timeline, how current. Not the derived-from
- * tree, the data key count or the reviewer's name.
- */
-const DOCUMENT_SUMMARY_FIELDS = [
-  'type',
-  'origin',
-  'version',
-  'isDraft',
-  'hasDraft',
-  'stage',
-  'reviewedAt',
-  'updatedAt',
-] as const;
-
-/** The API's page ceiling (paginationSchema in apps/api). */
-const PAGE_SIZE = 100;
-
-/**
- * Pages the resolver follows before it stops and says so. A repository is
- * linked to one product, or a handful where sharing is allowed; a thousand
- * matches is not a resolution the model can act on anyway.
- */
-const RESOLVE_PAGE_LIMIT = 10;
-
-const originInput = z
-  .enum(PRODUCT_DOCUMENT_ORIGINS)
-  .optional()
-  .describe(
-    `Which timeline. ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} ` +
-      "Omit for the product's own timeline: reality if imported, else plan; always plan for the documents a " +
-      'person writes (Look & Feel, Product Instructions).'
-  );
-
-/**
- * Every product linked to the repository, page by page, until the API runs
- * out or the cap is hit, in which case the list says it is truncated. A page
- * that FAILS is different: it fails the call, like every other tool, rather
- * than being folded into a truncated list that would read as a complete one.
- */
-async function linkedProducts(client: TaigaClient, repository: string, repositoryHost: string) {
-  const products: ProductRow[] = [];
-  let cursor: string | undefined;
-  for (let page = 0; page < RESOLVE_PAGE_LIMIT; page += 1) {
-    const result = await client.listProducts({ repository, repositoryHost, limit: PAGE_SIZE, cursor });
-    products.push(...result.data);
-    if (!result.nextCursor) return { products, truncated: false };
-    cursor = result.nextCursor;
-  }
-  return { products, truncated: true };
-}
-
-/** A document list row as the model sees it: the summary fields plus a display name and the staleness fact. */
-function documentSummaries(rows: DocumentRow[]) {
-  return pickFields(rows, DOCUMENT_SUMMARY_FIELDS).map((picked, index) => {
-    // `outdated` on the wire is the list of sources that moved on; the model
-    // needs the fact, not the tree. Published plan rows carry it: null when
-    // current, a source list when not. A draft has nothing published to be
-    // outdated (the API stamps it null too) and reality rows carry no such
-    // field: no fact for either.
-    const outdated = rows[index]!.outdated;
-    const fact =
-      picked.isDraft !== false
-        ? undefined
-        : outdated === null
-          ? false
-          : Array.isArray(outdated?.sources)
-            ? outdated.sources.length > 0
-            : undefined;
-    return {
-      type: picked.type,
-      name: productDocumentName(String(picked.type)),
-      ...picked,
-      ...(fact === undefined ? {} : { outdated: fact }),
-    };
-  });
-}
-
-type DocumentSummary = ReturnType<typeof documentSummaries>[number];
-
-interface Timelines {
-  projectType: 'greenfield' | 'brownfield';
-  defaultOrigin: ProductDocumentOrigin;
-  /** The side's summaries, or null when the API could not list it (see `unlistable`). */
-  plan: DocumentSummary[] | null;
-  reality: DocumentSummary[] | null;
-  /** Why a null side is null, in the words the notes and a miss message use. */
-  unlistable: Partial<Record<ProductDocumentOrigin, string>>;
-  notes: string[];
-}
-
-/** The one sentence for a side the API would not list, with what it said. */
-function unlistableNote(origin: ProductDocumentOrigin, reason: unknown): string {
-  const said = reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ''}`.trim() : 'the request failed';
-  return `The ${origin} side could not be listed (${said}).`;
-}
-
-/**
- * Both timelines of a product's documents, each a list of summaries, with
- * which one is the product's own and a note for an empty side. The product
- * decides what an empty side means (imported or not, how far its import got),
- * so a caller that already holds it passes it in.
- */
-async function documentTimelines(client: TaigaClient, id: string, product?: ProductSettingsView): Promise<Timelines> {
-  const loaded = product ?? (await client.getProduct(id)).data;
-  // Each side on its own: one side the API cannot list is reported as
-  // unreadable, not as empty, and never hides the side that did answer.
-  // Both failing is the API failing, and that is an error like any other.
-  const settled = await Promise.allSettled(
-    PRODUCT_DOCUMENT_ORIGINS.map((o) => client.listProductDocuments(id, { origin: o, limit: PAGE_SIZE }))
-  );
-  if (settled.every((result) => result.status === 'rejected')) throw settled[0]!.reason;
-  const sides: Partial<Record<ProductDocumentOrigin, DocumentSummary[] | null>> = {};
-  const unlistable: Partial<Record<ProductDocumentOrigin, string>> = {};
-  PRODUCT_DOCUMENT_ORIGINS.forEach((o, index) => {
-    const result = settled[index]!;
-    if (result.status === 'fulfilled') sides[o] = documentSummaries(result.value.data);
-    else {
-      sides[o] = null;
-      unlistable[o] = unlistableNote(o, result.reason);
-    }
-  });
-  const notes = PRODUCT_DOCUMENT_ORIGINS.flatMap((o) => {
-    const side = sides[o];
-    if (!side) return [unlistable[o]!];
-    return side.length === 0 ? [emptyOriginNote(o, loaded)] : [];
-  });
-  return {
-    projectType: isImportedProduct(loaded) ? 'brownfield' : 'greenfield',
-    defaultOrigin: defaultOriginFor(loaded),
-    plan: sides.plan ?? null,
-    reality: sides.reality ?? null,
-    unlistable,
-    notes,
-  };
-}
-
-const isPublished = (row: { isDraft?: boolean }) => row.isDraft === false;
-
-/** `specification (v2), architecture (draft)` for one side. */
-function sideList(rows: DocumentSummary[]): string {
-  return rows
-    .map((row) => `${String(row.type)} (${isPublished(row) ? `v${String(row.version)}` : 'draft'})`)
-    .join(', ');
-}
-
-/** What a missed document read should say: where the type does live, and what each side holds. */
-function describeMiss(
-  type: string,
-  wanted: ProductDocumentOrigin,
-  timelines: Timelines,
-  product: ProductSettingsView
-): string {
-  const name = productDocumentName(type);
-  const other: ProductDocumentOrigin = wanted === 'plan' ? 'reality' : 'plan';
-  const parts = [`No published ${wanted} ${name} (${type}) for this product.`];
-  const rows = (side: ProductDocumentOrigin) => timelines[side] ?? [];
-  if (rows(other).some((row) => row.type === type && isPublished(row))) {
-    parts.push(`It is published on the ${other} side: call again with origin '${other}'.`);
-  } else {
-    for (const side of [wanted, other]) {
-      if (rows(side).some((row) => row.type === type && !isPublished(row))) {
-        parts.push(`A draft of it exists on the ${side} side, unpublished.`);
-      }
-    }
-  }
-  for (const o of PRODUCT_DOCUMENT_ORIGINS) {
-    const side = timelines[o];
-    const label = `${o[0]!.toUpperCase()}${o.slice(1)} documents`;
-    if (side === null) parts.push(timelines.unlistable[o]!);
-    else parts.push(side.length > 0 ? `${label}: ${sideList(side)}.` : emptyOriginNote(o, product));
-  }
-  return parts.join(' ');
-}
-
-/**
- * One product from whichever name the caller has: its ID, its slug (through
- * the list's slug filter) or the git remote of a checkout (through the
- * repository filter). Exactly one of the three; a remote linked to several
- * products is ambiguous and says so.
- */
-export async function resolveProductRef(
-  client: TaigaClient,
-  ref: { productId?: string | undefined; slug?: string | undefined; remoteUrl?: string | undefined },
-  /** The names the calling tool accepts, for the message when none or several were given. */
-  accepted: readonly string[],
-  /** How the caller's arguments are passed, for the message when none was given (a slash command's usage). */
-  usage?: string
-): Promise<{ product: ProductRow } | { refusal: { code: string; message: string } }> {
-  const refusal = (code: string, message: string) => ({ refusal: { code, message } });
-  const given = [ref.productId, ref.slug, ref.remoteUrl].filter((v) => v !== undefined).length;
-  if (given !== 1) {
-    const how =
-      given === 0 ? (usage ?? 'taiga_list_products shows what exists.') : 'Two names could mean two products.';
-    return refusal('VALIDATION_ERROR', `Name the product exactly once: ${accepted.join(' or ')}. ${how}`);
-  }
-  if (ref.productId) {
-    try {
-      return { product: (await client.getProduct(ref.productId)).data };
-    } catch (error) {
-      if (!isMissOrRefusal(error)) throw error;
-      return refusal(
-        apiFailureCode(error),
-        error instanceof TaigaApiError && error.status === 404
-          ? 'No product with that ID the key can see. taiga_list_products (query finds one by name) shows the ones it can; a slug or git remote URL names one too.'
-          : `No product with that ID the key can see (${apiFailureText(error)}); taiga_list_products shows the ones it can.`
-      );
-    }
-  }
-  if (ref.slug) {
-    const [product] = (await client.listProducts({ slug: ref.slug, limit: 1 })).data;
-    if (!product) {
-      return refusal(
-        'NOT_FOUND',
-        `No product you can see has the slug "${ref.slug}". taiga_list_products shows the ones you can.`
-      );
-    }
-    return { product };
-  }
-  const remote = parseRemote(ref.remoteUrl!);
-  if (!remote) {
-    return refusal(
-      'INVALID_REMOTE',
-      `"${ref.remoteUrl}" is not a remote of the form host/owner/repo. Pass the URL git remote get-url origin prints.`
-    );
-  }
-  // `truncated` is dropped on purpose: past the cap the answer is AMBIGUOUS anyway.
-  const { products } = await linkedProducts(client, remote.repository, remote.host);
-  if (products.length === 0) {
-    return refusal(
-      'NOT_FOUND',
-      `No product you can see is linked to ${remote.repository} on ${remote.host}. ` +
-        'Link the repository to its product in Taiga, or find the product with taiga_list_products.'
-    );
-  }
-  if (products.length > 1) {
-    const names = pickFields(products, PRODUCT_SUMMARY_FIELDS)
-      .map((p) => `${String(p.name)} (${String(p.id)})`)
-      .join(', ');
-    return refusal(
-      'AMBIGUOUS',
-      `${remote.repository} is linked to several products: ${names}. Call again with the productId of the one you mean.`
-    );
-  }
-  // The list route returns full product rows, the same shape the single read does.
-  return { product: products[0]! };
-}
-
-/**
- * NOT_FOUND for a factory ID the key cannot see; null when it exists or the read failed. A key that cannot read
- * factories cannot tell an empty factory from a wrong ID, and the answer says so.
- */
-async function factoryMissing(client: TaigaClient, factoryId: string) {
-  if (!client.hasCapability('factories:read')) {
-    return toolResult({
-      data: [],
-      nextCursor: null,
-      note: 'No products here. This key cannot read factories, so whether that factoryId exists was not checked.',
-    });
-  }
-  try {
-    await client.getFactory(factoryId);
-    return null;
-  } catch (error) {
-    if (error instanceof TaigaApiError && error.status === 404) {
-      return toolError('NOT_FOUND', 'Factory not found. taiga_list_factories lists the factories the key can see.');
-    }
-    if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
-    throw error;
-  }
-}
-
-export function registerProductTools(server: McpServer, client: TaigaClient) {
-  if (client.hasCapability('factories:read')) {
-    server.registerTool(
-      'taiga_list_factories',
-      {
-        title: 'List factories',
-        description:
-          "List the organization's factories, the groups that own products, with their IDs; query finds one by " +
-          "name. Read a factory's instructions (domain context, tech preferences, conventions) with " +
-          'taiga_get_factory_document.',
-        inputSchema: z.object({
-          query: query('factory name'),
-          ...pagination,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          if (params.query === undefined) {
-            const result = await client.listFactories(params);
-            return toolResult(page(result.data, result.nextCursor));
-          }
-          if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
-          const found = await searchPages(
-            (cursor) => client.listFactories({ limit: SEARCH_PAGE_SIZE, cursor }),
-            params.query,
-            (row) => [row.name, row.slug],
-            params.limit ?? 25
-          );
-          return toolResult({ ...page(found.rows, null), ...(found.more ? { more: SEARCH_NOTE } : {}) });
-        })
-    );
-  }
-
-  if (client.hasCapability('products:read')) {
-    server.registerTool(
-      'taiga_list_products',
-      {
-        title: 'List products',
-        description:
-          "List the organization's products as summaries (id, name, slug, status, factoryId, factoryName, " +
-          'discoveryStep); query finds one by name. Inside a git checkout, taiga_get_product_context takes the ' +
-          `remote URL instead. ${DISCOVERY_STEP_MEANING}`,
-        inputSchema: z.object({
-          query: query('product name or slug'),
-          factoryId: idInput('factory', 'taiga_list_factories (query finds one by name) gives it')
-            .optional()
-            .describe('Only the products of this factory'),
-          status: z
-            .enum(PRODUCT_STATUSES)
-            .optional()
-            .describe(
-              'Filter by status: draft until the product finishes setup in Taiga, active after that, ' +
-                'archived when retired.'
-            ),
-          ...pagination,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          const { query: text, ...filters } = params;
-          if (text === undefined) {
-            const result = await client.listProducts(filters);
-            // A factory that does not exist is a miss, as everywhere else, not an empty factory (PRO-2800).
-            if (result.data.length === 0 && filters.factoryId && !filters.cursor) {
-              const missing = await factoryMissing(client, filters.factoryId);
-              if (missing) return missing;
-            }
-            return toolResult(
-              page(await withFactoryNames(client, pickFields(result.data, PRODUCT_SUMMARY_FIELDS)), result.nextCursor)
-            );
-          }
-          if (params.cursor !== undefined) return toolError('VALIDATION_ERROR', SEARCH_WITH_CURSOR);
-          const found = await searchPages(
-            (cursor) =>
-              client.listProducts({
-                factoryId: filters.factoryId,
-                status: filters.status,
-                limit: SEARCH_PAGE_SIZE,
-                cursor,
-              }),
-            text,
-            (row) => [row.name, row.slug],
-            params.limit ?? 25
-          );
-          if (found.rows.length === 0 && filters.factoryId) {
-            const missing = await factoryMissing(client, filters.factoryId);
-            if (missing) return missing;
-          }
-          return toolResult({
-            ...page(await withFactoryNames(client, pickFields(found.rows, PRODUCT_SUMMARY_FIELDS)), null),
-            ...(found.more ? { more: SEARCH_NOTE } : {}),
-          });
-        })
-    );
-
-    server.registerTool(
-      'taiga_get_product',
-      {
-        title: 'Get product',
-        description:
-          'Read one product and its settings by ID, slug or git remote URL (git remote get-url origin; a ' +
-          'repository linked to several products is refused with their IDs): name, factory, what Taiga owns ' +
-          '(application, infrastructure, deployment). In setup, readiness says whether it can finish now and what ' +
-          'is missing (repository, import, unpublished documents, unstamped checks), plus nextStep. For ' +
-          'initiatives, runs and findings, use taiga_get_product_context.',
-        inputSchema: z.object({
-          productId: productId.optional(),
-          slug: slug.optional(),
-          remoteUrl: remoteUrl.optional(),
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          const resolved = await resolveProductRef(client, params, ['productId', 'slug', 'remoteUrl']);
-          if ('refusal' in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
-          const readiness = await setupReadiness(client, resolved.product);
-          return toolResult(readiness ? { ...resolved.product, readiness } : resolved.product);
-        })
-    );
-
-    server.registerTool(
-      'taiga_get_product_document',
-      {
-        title: 'Get product document',
-        description:
-          'Read one product document from one timeline, or without type list both timelines (type, version, ' +
-          "draft and review state; defaultOrigin is the product's own; an empty side says why). plan " +
-          '(specification, architecture, threat_model, technology_decisions) says what to build; reality says ' +
-          "what the code does, so read it before changing code. Omit origin for the product's own timeline. " +
-          'sections: [] returns the outline (ids, sizes); then name the sections you need (unknownSections names ' +
-          'missing ids). A miss says which documents exist.',
-        inputSchema: z.object({
-          productId,
-          type: z
-            .enum(PRODUCT_DOCUMENT_TYPES)
-            .optional()
-            .describe('Document type; omit to list what the product has on both timelines'),
-          origin: originInput,
-          sections: sectionsInput,
-        }),
-        annotations: READ_ONLY,
-      },
-      (params) =>
-        runTool(async () => {
-          // Without a type, the list of both timelines (PRO-2800): one tool where a list tool stood beside it.
-          if (params.type === undefined) {
-            if (params.sections || params.origin) {
-              return toolError('VALIDATION_ERROR', 'Name the document (type) to read one timeline or its sections.');
-            }
-            const { unlistable: _unlistable, ...timelines } = await documentTimelines(client, params.productId);
-            return toolResult(timelines);
-          }
-          const type = params.type;
-          // The product's own timeline when none is asked for; the API's
-          // default is plan, which is the wrong side of an imported product.
-          let product: ProductSettingsView | undefined;
-          if (!params.origin) product = (await client.getProduct(params.productId)).data;
-          const origin = params.origin ?? defaultOriginFor(product, type);
-          try {
-            const result = await client.getProductDocument(params.productId, type, origin);
-            const doc = stripProvenance(result.data);
-            if (!params.sections) return toolResult(doc);
-            return sectionReadResult(doc, params.sections, `${origin} ${type}`);
-          } catch (error) {
-            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
-            // A product the key cannot see is a product miss, not a document
-            // miss, so the product read propagates. The lists after it are
-            // best effort per side (documentTimelines); only both failing
-            // propagates, as the API failing.
-            product ??= (await client.getProduct(params.productId)).data;
-            const timelines = await documentTimelines(client, params.productId, product);
-            return toolError('NOT_FOUND', describeMiss(type, origin, timelines, product));
-          }
-        })
-    );
-  }
-}