@taiga-ai/mcp-server 0.18.0-dev.447 → 0.18.0-dev.448

package/src/tools/repositories.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import type { GithubRepository } from '@taiga/types';
+import type { TaigaClient, WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
 import { idInput, pagination, productId } from './inputs.js';
@@ -15,8 +16,6 @@ import { SEARCH_WITH_CURSOR, page, pickFields } from './summarize.js';
  * repositories it can reach to a product is a separate act, per product.
  */
 
-type Row = Record<string, unknown>;
-
 const LINK_FIELDS = [
   'id',
   'provider',
@@ -81,7 +80,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           // The route answers one page of 100 and takes no cursor: past that, the list says it is cut.
           const result = await client.listProductRepositories(params.productId);
           return toolResult({
-            data: pickFields(result.data as Row[], LINK_FIELDS),
+            data: pickFields(result.data, LINK_FIELDS),
             truncated: result.nextCursor !== null,
           });
         })
@@ -135,7 +134,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
       },
       (params) =>
         runTool(async () => {
-          const installations = (await client.listGithubInstallations()).data as Row[];
+          const installations = (await client.listGithubInstallations()).data;
           const accounts = pickFields(installations, INSTALLATION_FIELDS);
           if (installations.length === 0) {
             return toolError(
@@ -167,7 +166,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           // are read: a search answers its ranked matches whatever the page
           // size, and several accounts add up.
           const max = params.limit ?? 25;
-          const rows = (data: unknown[]) => pickFields(data as Row[], GITHUB_REPOSITORY_FIELDS);
+          const rows = (data: WithoutTenant<GithubRepository>[]) => pickFields(data, GITHUB_REPOSITORY_FIELDS);
           if (chosen.length === 1) {
             const result = await client.listInstallationRepositories(String(chosen[0]!.id), {
               q: params.query,
@@ -227,7 +226,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
           githubRepositoryId: params.githubRepositoryId,
           ...(params.replacesRepositoryId ? { replacesRepositoryId: params.replacesRepositoryId } : {}),
         });
-        return toolResult(pickFields([linked.data as Row], LINK_FIELDS)[0]);
+        return toolResult(pickFields([linked.data], LINK_FIELDS)[0]);
       })
   );
 
@@ -265,7 +264,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
             ...(params.baseBranch !== undefined ? { baseBranch: params.baseBranch } : {}),
             ...(params.label !== undefined ? { label: params.label } : {}),
           })
-        ).data as Row;
+        ).data;
         return toolResult({
           ...pickFields([updated], LINK_FIELDS)[0],
           baseBranchProtection: updated.baseBranchProtection ?? null,

package/src/tools/resources.ts

@@ -16,7 +16,6 @@ import {
   productDocumentName,
   type ProductDocumentOrigin,
   type ProductDocumentType,
-  type ProductSettingsView,
 } from './catalogue.js';
 import { productId as productIdInput } from './inputs.js';
 import { mimeTypeOf, renderDocument } from './markdown.js';
@@ -69,9 +68,7 @@ async function served<T>(read: Promise<T>, miss: string): Promise<T> {
 export function registerResources(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('tenant:documents:read')) {
     const published = async () =>
-      ((await client.listTenantDocuments({ limit: 100 })).data as Record<string, unknown>[]).filter(
-        (row) => row.isDraft === false
-      );
+      (await client.listTenantDocuments({ limit: 100 })).data.filter((row) => row.isDraft === false);
 
     server.registerResource(
       'organization-document',
@@ -95,7 +92,7 @@ export function registerResources(server: McpServer, client: TaigaClient) {
           'tone of voice or the standing instructions. Sections rendered as headings.',
       },
       async (uri, variables) => {
-        const type = requireOneOf('Document type', String(variables.type), TENANT_DOCUMENT_TYPES);
+        const type = requireOneOf('Document type', String(variables['type']), TENANT_DOCUMENT_TYPES);
         try {
           return contents(uri.href, (await client.getTenantDocument(type)).data);
         } catch (error) {
@@ -127,7 +124,7 @@ export function registerResources(server: McpServer, client: TaigaClient) {
           'section map, JSON otherwise (the read says which).',
       },
       async (uri, variables) => {
-        const factoryId = requireId('Factory ID', String(variables.factoryId));
+        const factoryId = requireId('Factory ID', String(variables['factoryId']));
         const doc = await served(
           client.getFactoryDocument(factoryId, FACTORY_DOCUMENT_TYPES[0]),
           'This factory has not published instructions, or the key cannot see the factory'
@@ -147,7 +144,7 @@ export function registerResources(server: McpServer, client: TaigaClient) {
         client.getProductDocument(productId, type, origin),
         `No published ${origin} ${type} for this product, or the key cannot see it; taiga_list_product_documents shows what exists`
       );
-      return contents(uri.href, { name: productDocumentName(type), ...(result.data as Record<string, unknown>) });
+      return contents(uri.href, { name: productDocumentName(type), ...result.data });
     };
 
     // The timeline template first: the SDK tries templates in registration
@@ -162,9 +159,9 @@ export function registerResources(server: McpServer, client: TaigaClient) {
           'Markdown for a section map, JSON otherwise (the read says which).',
       },
       async (uri, variables) => {
-        const productId = requireId('Product ID', String(variables.productId));
-        const type = documentType(String(variables.type));
-        const origin = requireOneOf('Origin', String(variables.origin), PRODUCT_DOCUMENT_ORIGINS);
+        const productId = requireId('Product ID', String(variables['productId']));
+        const type = documentType(String(variables['type']));
+        const origin = requireOneOf('Origin', String(variables['origin']), PRODUCT_DOCUMENT_ORIGINS);
         return read(uri, productId, type, origin);
       }
     );
@@ -181,14 +178,14 @@ export function registerResources(server: McpServer, client: TaigaClient) {
           'otherwise (the read says which).',
       },
       async (uri, variables) => {
-        const productId = requireId('Product ID', String(variables.productId));
-        const type = documentType(String(variables.type));
+        const productId = requireId('Product ID', String(variables['productId']));
+        const type = documentType(String(variables['type']));
         const product = (
           await served(
             client.getProduct(productId),
             'No product with that ID the key can see; taiga_list_products shows them'
           )
-        ).data as ProductSettingsView;
+        ).data;
         return read(uri, productId, type, defaultOriginFor(product, type));
       }
     );
@@ -206,7 +203,7 @@ export function registerResources(server: McpServer, client: TaigaClient) {
         mimeType: 'application/json',
       },
       async (uri, variables) => {
-        const itemId = requireId('Backlog item ID', String(variables.itemId));
+        const itemId = requireId('Backlog item ID', String(variables['itemId']));
         const item = (
           await served(
             client.getBacklogItem(itemId),

package/src/tools/sections.test.ts

@@ -50,12 +50,12 @@ describe('applySectionEdit', () => {
   });
 
   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' });
+    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' });
+    expect(applySectionEdit(sections, 'retention', 'keep 90 days')['retention']).toEqual({ content: 'keep 90 days' });
   });
 
   it('does not mutate its input', () => {

package/src/tools/sections.ts

@@ -15,15 +15,42 @@ import type { CallToolResult } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { toolError, toolResult } from './errors.js';
 
-/** A section as stored: an object with `content` and metadata, or (older rows) a bare string. */
+/** 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: Record<string, unknown>): Sections | null {
+export function sectionsOf(data: DocumentData): Sections | null {
   return isRecord(data.sections) ? data.sections : null;
 }
 
@@ -32,7 +59,7 @@ export function sectionContent(sections: Sections, sectionId: string): string |
   const section = sections[sectionId];
   if (section === undefined || section === null) return null;
   if (typeof section === 'string') return section;
-  return isRecord(section) && typeof section.content === 'string' ? section.content : '';
+  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. */
@@ -48,10 +75,12 @@ export function applySectionEdit(sections: Sections, sectionId: string, content:
  * the editor needs and a reader does not; `source` and `priority` stay, the
  * server instructions explain them.
  */
-export function stripProvenance(doc: Record<string, unknown>): Record<string, unknown> {
+export function stripProvenance<T extends StoredDocument>(doc: T): Omit<T, 'derivedFrom' | 'outdated'> {
   const { derivedFrom: _derivedFrom, outdated: _outdated, ...rest } = doc;
-  if (!isRecord(rest.data)) return rest;
-  const sections = sectionsOf(rest.data);
+  // `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]) => {
@@ -60,7 +89,7 @@ export function stripProvenance(doc: Record<string, unknown>): Record<string, un
       return [id, keep];
     })
   );
-  return { ...rest, data: { ...rest.data, sections: stripped } };
+  return { ...rest, data: { ...data, sections: stripped } };
 }
 
 /**
@@ -73,7 +102,7 @@ export function instructionsText(sections: Sections): string | null {
   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 = isRecord(section) ? section.content : undefined;
+    const content = isSectionObject(section) ? section.content : undefined;
     if (typeof content === 'string' && content.trim()) parts.push(content.trim());
   }
   const text = parts.join('\n\n').trim();
@@ -82,15 +111,15 @@ export function instructionsText(sections: Sections): string | null {
 
 /** A document cut to some of its sections, and the ones left out with their sizes. */
 export interface SectionCut {
-  doc: Record<string, unknown>;
+  doc: StoredDocument;
   omittedSections: { id: string; characters: number }[];
 }
 
-function cutTo(doc: Record<string, unknown>, sections: Sections, kept: Sections): SectionCut {
+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 Record<string, unknown>), sections: kept } }, omittedSections };
+  return { doc: { ...doc, data: { ...(doc.data as DocumentData), sections: kept } }, omittedSections };
 }
 
 /**
@@ -100,7 +129,7 @@ function cutTo(doc: Record<string, unknown>, sections: Sections, kept: Sections)
  * 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: Record<string, unknown>, ids: ReadonlySet<string>): SectionCut | null {
+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))));
@@ -115,7 +144,7 @@ export function pickSections(doc: Record<string, unknown>, ids: ReadonlySet<stri
  * and a later, smaller one may still be carried. Null when the document is
  * not made of sections.
  */
-export function budgetSections(doc: Record<string, unknown>, budget: number): SectionCut | null {
+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.
@@ -150,10 +179,10 @@ export const sectionsInput = z
  * real id with its size, so the retry needs nothing else. No ids is the
  * outline.
  */
-export function sectionReadResult(doc: Record<string, unknown>, ids: readonly string[], label: string): CallToolResult {
+export function sectionReadResult(doc: StoredDocument, ids: readonly string[], label: string): CallToolResult {
   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 Record<string, unknown>) ?? {});
+  const all = Object.keys(sectionsOf(doc.data as DocumentData) ?? {});
   const unknownSections = ids.filter((id) => !all.includes(id));
   return toolResult({
     ...cut.doc,

package/src/tools/setup.ts

@@ -1,9 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { DEPLOYMENT_NOTES_MAX_LENGTH, REALITY_DERIVED_DOCUMENT_TYPES } from '@taiga/types';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import type { Product } from '@taiga/types';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
-import { isImportedProduct, setupNextStep, type ProductSettingsView } from './catalogue.js';
+import { isImportedProduct, setupNextStep } from './catalogue.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { withStop } from './hints.js';
 import { idInput, productId } from './inputs.js';
@@ -18,8 +19,6 @@ import { pickFields } from './summarize.js';
  * a product stay in the web.
  */
 
-type Row = Record<string, unknown>;
-
 const PRODUCT_FIELDS = [
   'id',
   'name',
@@ -63,13 +62,15 @@ const MISSING_DOCUMENTS_HOW =
   'specification from the Discovery conversation in the web and the rest from taiga_generate_product_documents. ' +
   'A draft is published with taiga_publish_product_document.';
 
+type ProductRow = WithoutTenant<Product>;
+
 /** A product row the model can act on, saying how it started as the other product tools say it. */
-async function productRow(client: TaigaClient, product: Row): Promise<Row> {
+async function productRow(client: TaigaClient, product: ProductRow) {
   const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
   const nextStep = setupNextStep(await withDiscoveryStep(client, product));
   return {
     ...rest,
-    projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield',
+    projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
     ...(nextStep ? { nextStep } : {}),
   };
 }
@@ -81,12 +82,12 @@ async function productRow(client: TaigaClient, product: Row): Promise<Row> {
  * instead. Best effort: a failed read leaves the product without a nextStep
  * rather than failing the write that already happened.
  */
-async function withDiscoveryStep(client: TaigaClient, product: Row): Promise<Row> {
-  if (product.status !== 'draft' || 'discoveryStep' in product || isImportedProduct(product as ProductSettingsView)) {
+async function withDiscoveryStep(client: TaigaClient, product: ProductRow): Promise<ProductRow> {
+  if (product.status !== 'draft' || 'discoveryStep' in product || isImportedProduct(product)) {
     return product;
   }
   try {
-    return (await client.getProduct(String(product.id))).data as Row;
+    return (await client.getProduct(String(product.id))).data;
   } catch (error) {
     if (error instanceof TaigaApiError || isNetworkFailure(error)) return product;
     throw error;
@@ -98,7 +99,7 @@ async function withDiscoveryStep(client: TaigaClient, product: Row): Promise<Row
  * web asks for the sentence but does not insist), so a warning rather than a
  * refusal: plans then design against a gap.
  */
-function missingNotesWarning(product: Row): string[] {
+function missingNotesWarning(product: ProductRow): string[] {
   const off = product.ownsInfrastructure === false || product.ownsDeployment === false;
   const notes = typeof product.deploymentNotes === 'string' ? product.deploymentNotes.trim() : '';
   return off && !notes
@@ -144,7 +145,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () =>
-          toolResult(pickFields([(await client.createFactory({ name: params.name })).data as Row], FACTORY_FIELDS)[0])
+          toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0])
         )
     );
 
@@ -161,10 +162,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       (params) =>
         runTool(async () =>
           toolResult(
-            pickFields(
-              [(await client.updateFactory(params.factoryId, { name: params.name })).data as Row],
-              FACTORY_FIELDS
-            )[0]
+            pickFields([(await client.updateFactory(params.factoryId, { name: params.name })).data], FACTORY_FIELDS)[0]
           )
         )
     );
@@ -212,7 +210,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
             ...(params.stopLine ? { stopLine: true } : {}),
           });
           return toolResult({
-            product: await productRow(client, moved.data as Row),
+            product: await productRow(client, moved.data),
             changed: moved.changed,
             previousFactoryId: moved.previousFactoryId,
             lineStopped: moved.lineStopped,
@@ -260,7 +258,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
             ...(params.ownsDeployment !== undefined ? { ownsDeployment: params.ownsDeployment } : {}),
             ...(params.deploymentNotes !== undefined ? { deploymentNotes: params.deploymentNotes } : {}),
           })
-        ).data as Row;
+        ).data;
         return toolResult(await productRow(client, product));
       })
   );
@@ -297,7 +295,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         }
         const contradiction = notesWithNothingToDescribe(params);
         if (contradiction) return contradiction;
-        const updated = (await client.updateProduct(id, changes)).data as Row;
+        const updated = (await client.updateProduct(id, changes)).data;
         const warnings = missingNotesWarning(updated);
         return toolResult({ ...(await productRow(client, updated)), ...(warnings.length > 0 ? { warnings } : {}) });
       })
@@ -347,11 +345,11 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         try {
-          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data as Row));
+          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data));
         } catch (error) {
           // The refusal names what is missing; it does not say how a missing
           // document comes to exist, which is what the agent asks next.
-          if (!(error instanceof TaigaApiError) || error.details?.reason !== 'documents_incomplete') throw error;
+          if (!(error instanceof TaigaApiError) || error.details?.['reason'] !== 'documents_incomplete') throw error;
           return toolError(
             error.code ?? 'CONFLICT',
             `${withStop(error.apiMessage ?? 'Required documents are not published yet')} ${MISSING_DOCUMENTS_HOW}`,
@@ -372,9 +370,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       annotations: OPERATE,
     },
     (params) =>
-      runTool(async () =>
-        toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data as Row))
-      )
+      runTool(async () => toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data)))
   );
 
   if (!client.hasCapability('products:read')) return;
@@ -396,8 +392,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const product = (await client.getProduct(params.productId)).data as Row;
-        if (!isImportedProduct(product as ProductSettingsView)) {
+        const product = (await client.getProduct(params.productId)).data;
+        if (!isImportedProduct(product)) {
           return toolError(
             'CONFLICT',
             'This product was started from scratch, so it has no import: the choice is made when a product is created.'

package/src/tools/summarize.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { pickFields } from './summarize.js';
+
+describe('pickFields', () => {
+  const rows: { id: string; name?: string; content?: string }[] = [
+    { id: 'a', name: 'A', content: 'the prose a list leaves out' },
+    { id: 'b' },
+  ];
+
+  it('keeps the named fields and leaves out one an item does not carry', () => {
+    expect(pickFields(rows, ['id', 'name'])).toEqual([{ id: 'a', name: 'A' }, { id: 'b' }]);
+  });
+
+  it('refuses a field the row type does not have', () => {
+    // The *_FIELDS lists are checked against their rows, so a misspelled field
+    // fails to compile instead of silently picking nothing (tsc covers tests).
+    // @ts-expect-error -- 'nmae' is not a field of the row.
+    expect(pickFields([{ id: 'a', name: 'A' }], ['id', 'nmae'])).toEqual([{ id: 'a' }]);
+  });
+});

package/src/tools/summarize.ts

@@ -3,12 +3,13 @@
  * fields a model needs to pick an item) and get tools return everything;
  * this is how a list drops the prose and the provenance trees.
  */
-export function pickFields<T extends Record<string, unknown>>(
-  items: T[],
-  fields: readonly string[]
-): Record<string, unknown>[] {
+export function pickFields<T extends object, K extends keyof T>(
+  items: readonly T[],
+  fields: readonly K[]
+): Partial<Pick<T, K>>[] {
   return items.map((item) => {
-    const picked: Record<string, unknown> = {};
+    // Partial: a field the item does not carry is left out, not set to undefined.
+    const picked: Partial<Pick<T, K>> = {};
     for (const field of fields) {
       if (field in item) picked[field] = item[field];
     }
@@ -26,7 +27,7 @@ export function page<T>(data: T[], nextCursor: string | null | undefined): { dat
  * carry, so "done with two unmet" shows in a list without reading the item.
  * Null while it has none (an unplanned initiative).
  */
-export function criteriaCounts(item: Record<string, unknown>): { met: number; total: number } | null {
+export function criteriaCounts(item: { acceptanceCriteria?: unknown }): { met: number; total: number } | null {
   const criteria = item.acceptanceCriteria;
   if (!Array.isArray(criteria) || criteria.length === 0) return null;
   const met = criteria.filter((c) => typeof c === 'object' && c !== null && (c as { met?: unknown }).met === true);
@@ -38,7 +39,10 @@ export function criteriaCounts(item: Record<string, unknown>): { met: number; to
  * does not carry `acceptanceCriteria` at all gets no count rather than a
  * null that would read as "has none".
  */
-export function itemRows(items: Record<string, unknown>[], fields: readonly string[]): Record<string, unknown>[] {
+export function itemRows<T extends { acceptanceCriteria?: unknown }, K extends keyof T>(
+  items: readonly T[],
+  fields: readonly K[]
+): (Partial<Pick<T, K>> & { criteria?: { met: number; total: number } | null })[] {
   return pickFields(items, fields).map((row, index) =>
     'acceptanceCriteria' in items[index]! ? { ...row, criteria: criteriaCounts(items[index]!) } : row
   );
@@ -53,18 +57,18 @@ const SEARCH_PAGE_LIMIT = 10;
  * told the person's word for a thing ("the Sandbox factory") otherwise pages
  * the whole list to find its ID. `more` is true when it stopped before the end.
  */
-export async function searchPages(
-  fetchPage: (cursor: string | undefined) => Promise<{ data: unknown[]; nextCursor: string | null }>,
+export async function searchPages<T>(
+  fetchPage: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>,
   query: string,
-  text: (row: Record<string, unknown>) => unknown[],
+  text: (row: T) => unknown[],
   limit: number
-): Promise<{ rows: Record<string, unknown>[]; more: boolean }> {
+): Promise<{ rows: T[]; more: boolean }> {
   const needle = query.toLowerCase();
-  const rows: Record<string, unknown>[] = [];
+  const rows: T[] = [];
   let cursor: string | undefined;
   for (let index = 0; index < SEARCH_PAGE_LIMIT; index += 1) {
     const result = await fetchPage(cursor);
-    const page = result.data as Record<string, unknown>[];
+    const page = result.data;
     for (const [at, row] of page.entries()) {
       if (!text(row).some((value) => typeof value === 'string' && value.toLowerCase().includes(needle))) continue;
       rows.push(row);