@alasano/pi-linear 0.1.1 → 0.3.0

package/extensions/renderers/common.ts

@@ -0,0 +1,305 @@
+import {
+  keyHint,
+  type AgentToolResult,
+  type Theme,
+  type ToolRenderResultOptions,
+} from '@mariozechner/pi-coding-agent';
+import { Text, truncateToWidth, visibleWidth } from '@mariozechner/pi-tui';
+import {
+  getDefaultJsonView,
+  registerLinearResultRenderer,
+  type LinearToolRenderContext,
+} from './state';
+
+export type { LinearToolRenderContext } from './state';
+
+export type ToolArgs = Record<string, unknown>;
+export type CellStyle = (text: string) => string;
+
+export type TableColumn<T> = {
+  id: string;
+  label: string;
+  width: number;
+  value: (item: T) => string;
+  style?: (theme: Theme, value: string, item: T) => CellStyle;
+};
+
+export type PrimaryTableColumn<T> = {
+  label: string;
+  minWidth?: number;
+  value: (item: T) => string;
+  style?: (theme: Theme, value: string, item: T) => CellStyle;
+};
+
+export type ResponsiveTableOptions<T> = {
+  columns: TableColumn<T>[];
+  primary: PrimaryTableColumn<T>;
+  dropOrder?: string[];
+  fallback: (item: T, theme: Theme, width: number) => string;
+  minWidth?: number;
+};
+
+export type ToolCallField = [key: string, label: string];
+
+const TABLE_SEPARATOR = '  ';
+const DEFAULT_TABLE_MIN_WIDTH = 28;
+const DEFAULT_PRIMARY_MIN_WIDTH = 24;
+const FALLBACK_PRIMARY_MIN_WIDTH = 10;
+const TOOL_ARG_STRING_LIMIT = 48;
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+export function cleanOneLine(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+export function truncate(value: string, maxLength: number): string {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+export function truncateLine(value: string, width: number): string {
+  return truncateToWidth(value, width);
+}
+
+export function textContent(result: AgentToolResult<any>): string {
+  const textBlock = result.content.find((block) => block.type === 'text');
+  if (textBlock?.type === 'text' && textBlock.text) return textBlock.text;
+  return JSON.stringify(result.details ?? null, null, 2);
+}
+
+export function expandedJson(result: AgentToolResult<any>, theme: Theme): Text {
+  const text = `\n${theme.fg('muted', 'Full JSON response')}\n${textContent(result)}\n\n${keyHint(
+    'app.tools.expand',
+    'show summary',
+  )}`;
+  return new Text(text, 0, 0);
+}
+
+export function shouldShowJson(
+  options: ToolRenderResultOptions,
+  context?: LinearToolRenderContext,
+): boolean {
+  registerLinearResultRenderer(context);
+  return options.expanded !== getDefaultJsonView();
+}
+
+export function jsonHint(): string {
+  return `(${keyHint('app.tools.expand', 'show full JSON')})`;
+}
+
+export function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function truncatePlainToWidth(value: string, width: number, ellipsis = '...'): string {
+  if (width <= 0) return '';
+  if (visibleWidth(value) <= width) return value;
+
+  const ellipsisWidth = visibleWidth(ellipsis);
+  if (ellipsisWidth >= width) return ellipsis.slice(0, width);
+
+  const targetWidth = width - ellipsisWidth;
+  let output = '';
+  let outputWidth = 0;
+
+  for (const character of Array.from(value)) {
+    const characterWidth = visibleWidth(character);
+    if (outputWidth + characterWidth > targetWidth) break;
+    output += character;
+    outputWidth += characterWidth;
+  }
+
+  return `${output.trimEnd()}${ellipsis}`;
+}
+
+export function formatCell(rawValue: string, width: number, style: CellStyle): string {
+  const cleanValue = cleanOneLine(rawValue || '—');
+  const truncated = truncatePlainToWidth(cleanValue, width);
+  const padding = ' '.repeat(Math.max(0, width - visibleWidth(truncated)));
+  return `${style(truncated)}${padding}`;
+}
+
+export function accentStyle(theme: Theme): CellStyle {
+  return (text) => theme.fg('accent', text);
+}
+
+export function dimStyle(theme: Theme): CellStyle {
+  return (text) => theme.fg('dim', text);
+}
+
+export function mutedStyle(theme: Theme): CellStyle {
+  return (text) => theme.fg('muted', text);
+}
+
+export function toolOutputStyle(theme: Theme): CellStyle {
+  return (text) => theme.fg('toolOutput', text);
+}
+
+function fitTableLayout<T>(
+  width: number,
+  columns: TableColumn<T>[],
+  primaryMinWidth: number,
+  dropOrder?: string[],
+  minWidth = DEFAULT_TABLE_MIN_WIDTH,
+): { columns: TableColumn<T>[]; primaryWidth: number } | undefined {
+  if (width < minWidth) return undefined;
+
+  const idsToDrop = dropOrder ?? columns.map((column) => column.id).reverse();
+  let visibleColumns = [...columns];
+
+  const primaryWidthFor = (candidateColumns: TableColumn<T>[]) => {
+    const separatorWidth = TABLE_SEPARATOR.length * candidateColumns.length;
+    const fixedWidth = candidateColumns.reduce((sum, column) => sum + column.width, 0);
+    return width - fixedWidth - separatorWidth;
+  };
+
+  let primaryWidth = primaryWidthFor(visibleColumns);
+  for (const columnToDrop of idsToDrop) {
+    if (primaryWidth >= primaryMinWidth) break;
+    visibleColumns = visibleColumns.filter((column) => column.id !== columnToDrop);
+    primaryWidth = primaryWidthFor(visibleColumns);
+  }
+
+  if (primaryWidth < FALLBACK_PRIMARY_MIN_WIDTH) return undefined;
+  return { columns: visibleColumns, primaryWidth };
+}
+
+function tableLine(cells: string[], width: number): string {
+  return truncateToWidth(cells.join(TABLE_SEPARATOR), width);
+}
+
+export function renderResponsiveTable<T>(
+  items: T[],
+  theme: Theme,
+  width: number,
+  options: ResponsiveTableOptions<T>,
+): string[] {
+  const layout = fitTableLayout(
+    width,
+    options.columns,
+    options.primary.minWidth ?? DEFAULT_PRIMARY_MIN_WIDTH,
+    options.dropOrder,
+    options.minWidth,
+  );
+
+  if (!layout) {
+    return items.map((item) => options.fallback(item, theme, width));
+  }
+
+  const headerCells = [
+    ...layout.columns.map((column) =>
+      formatCell(column.label, column.width, (text) => theme.fg('dim', text)),
+    ),
+    formatCell(options.primary.label, layout.primaryWidth, (text) => theme.fg('dim', text)),
+  ];
+
+  const lines = [tableLine(headerCells, width)];
+  for (const item of items) {
+    const cells = [
+      ...layout.columns.map((column) => {
+        const value = column.value(item);
+        const style = column.style?.(theme, value, item) ?? mutedStyle(theme);
+        return formatCell(value, column.width, style);
+      }),
+      (() => {
+        const value = options.primary.value(item);
+        const style = options.primary.style?.(theme, value, item) ?? toolOutputStyle(theme);
+        return formatCell(value, layout.primaryWidth, style);
+      })(),
+    ];
+    lines.push(tableLine(cells, width));
+  }
+
+  return lines;
+}
+
+export class LinearListResultComponent<T> {
+  constructor(
+    private readonly items: T[],
+    private readonly theme: Theme,
+    private readonly options: {
+      noun: string;
+      pluralNoun?: string;
+      emptyLabel: string;
+      previewLimit?: number;
+      renderItems: (items: T[], theme: Theme, width: number) => string[];
+    },
+  ) {}
+
+  render(width: number): string[] {
+    const lines: string[] = [''];
+
+    if (this.items.length === 0) {
+      lines.push(this.theme.fg('dim', this.options.emptyLabel));
+      lines.push('');
+      lines.push(jsonHint());
+      return lines.map((line) => truncateToWidth(line, width));
+    }
+
+    const previewLimit = this.options.previewLimit ?? 20;
+    const shown = this.items.slice(0, previewLimit);
+    lines.push(
+      this.theme.fg(
+        'success',
+        `✓ ${plural(this.items.length, this.options.noun, this.options.pluralNoun)} returned`,
+      ),
+    );
+    lines.push('');
+    lines.push(...this.options.renderItems(shown, this.theme, width));
+
+    if (shown.length < this.items.length) {
+      lines.push(
+        this.theme.fg(
+          'dim',
+          `… ${plural(this.items.length - shown.length, `more ${this.options.noun}`)}`,
+        ),
+      );
+    }
+
+    lines.push('');
+    lines.push(jsonHint());
+
+    return lines.map((line) => truncateToWidth(line, width));
+  }
+
+  invalidate(): void {}
+}
+
+export function formatToolArgValue(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) return undefined;
+    return trimmed.includes(' ')
+      ? `"${truncate(trimmed, TOOL_ARG_STRING_LIMIT)}"`
+      : truncate(trimmed, TOOL_ARG_STRING_LIMIT);
+  }
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'boolean') return value ? 'true' : undefined;
+  if (Array.isArray(value)) return value.length ? `[${value.length}]` : undefined;
+  if (value && typeof value === 'object') return '{…}';
+  return undefined;
+}
+
+export function renderLinearToolCall(
+  toolName: string,
+  args: ToolArgs | undefined,
+  theme: Theme,
+  fields: ToolCallField[],
+): Text {
+  let text = theme.fg('toolTitle', theme.bold(toolName));
+  const parts = fields
+    .map(([key, label]) => {
+      const value = formatToolArgValue(args?.[key]);
+      return value ? `${label}=${value}` : undefined;
+    })
+    .filter((part): part is string => !!part);
+
+  if (parts.length) {
+    text += ` ${theme.fg('dim', parts.join('  '))}`;
+  }
+
+  return new Text(text, 0, 0);
+}

package/extensions/renderers/documents.ts

@@ -0,0 +1,326 @@
+import {
+  type AgentToolResult,
+  type Theme,
+  type ToolRenderResultOptions,
+} from '@mariozechner/pi-coding-agent';
+import { Text } from '@mariozechner/pi-tui';
+import {
+  accentStyle,
+  asString,
+  cleanOneLine,
+  dimStyle,
+  expandedJson,
+  shouldShowJson,
+  jsonHint,
+  LinearListResultComponent,
+  mutedStyle,
+  renderLinearToolCall,
+  renderResponsiveTable,
+  toolOutputStyle,
+  truncate,
+  truncateLine,
+  type LinearToolRenderContext,
+  type TableColumn,
+  type ToolArgs,
+} from './common';
+
+type NamedRef = {
+  id?: string;
+  identifier?: string | null;
+  key?: string | null;
+  name?: string | null;
+  title?: string | null;
+};
+
+type DocumentLike = {
+  id?: string;
+  title?: string | null;
+  content?: string | null;
+  summary?: string | null;
+  hiddenAt?: string | null;
+  archivedAt?: string | null;
+  trashed?: boolean | null;
+  updatedAt?: string | null;
+  url?: string | null;
+  team?: NamedRef | null;
+  project?: NamedRef | null;
+  issue?: NamedRef | null;
+  initiative?: NamedRef | null;
+};
+
+type DocumentResultDetails = {
+  document?: DocumentLike | null;
+  documents?: DocumentLike[];
+  success?: boolean;
+};
+
+const DOCUMENT_LIST_PREVIEW_LIMIT = 20;
+const TITLE_LIMIT = 90;
+const SNIPPET_LIMIT = 180;
+const TABLE_TITLE_MIN_WIDTH = 24;
+
+function documentDetails(result: AgentToolResult<any>): DocumentResultDetails {
+  return (result.details ?? {}) as DocumentResultDetails;
+}
+
+function documentTitle(document: DocumentLike): string {
+  return truncate(cleanOneLine(asString(document.title) ?? '(untitled)'), TITLE_LIMIT);
+}
+
+function contextText(document: DocumentLike): string | undefined {
+  const issue = document.issue;
+  if (issue) {
+    return asString(issue.identifier) ?? asString(issue.title) ?? asString(issue.id);
+  }
+
+  const project = document.project;
+  if (project) return asString(project.name) ?? asString(project.id);
+
+  const initiative = document.initiative;
+  if (initiative) return asString(initiative.name) ?? asString(initiative.id);
+
+  return undefined;
+}
+
+function teamText(document: DocumentLike): string | undefined {
+  const team = document.team;
+  if (!team) return undefined;
+  return asString(team.key) ?? asString(team.name) ?? asString(team.id);
+}
+
+function dateText(value: unknown): string | undefined {
+  const date = asString(value);
+  if (!date) return undefined;
+  return date.includes('T') ? date.split('T')[0] : date;
+}
+
+function documentFlags(document: DocumentLike): string[] {
+  return [
+    asString(document.hiddenAt) ? 'hidden' : undefined,
+    asString(document.archivedAt) ? 'archived' : undefined,
+    document.trashed === true ? 'trashed' : undefined,
+  ].filter((flag): flag is string => !!flag);
+}
+
+function flagsText(document: DocumentLike): string {
+  return documentFlags(document).join(', ') || '—';
+}
+
+function documentSnippet(document: DocumentLike): string | undefined {
+  const summary = asString(document.summary);
+  if (summary) return truncate(cleanOneLine(summary), SNIPPET_LIMIT);
+
+  const content = asString(document.content);
+  if (content) return truncate(cleanOneLine(content), SNIPPET_LIMIT);
+
+  return undefined;
+}
+
+function formatDocumentTitle(document: DocumentLike, theme: Theme): string {
+  return theme.fg('toolOutput', documentTitle(document));
+}
+
+function metadataParts(document: DocumentLike): string[] {
+  const context = contextText(document);
+  const team = teamText(document);
+  const updated = dateText(document.updatedAt);
+  const flags = flagsText(document);
+
+  return [
+    context ? `context: ${context}` : undefined,
+    team ? `team: ${team}` : undefined,
+    updated ? `updated: ${updated}` : undefined,
+    flags !== '—' ? flags : undefined,
+  ].filter((part): part is string => !!part);
+}
+
+function formatDocumentListLine(document: DocumentLike, theme: Theme, width: number): string {
+  const title = documentTitle(document);
+  const metadata = metadataParts(document);
+  const suffix = metadata.length ? theme.fg('dim', ` · ${metadata.join(' · ')}`) : '';
+
+  return truncateLine(`  ${theme.fg('toolOutput', title)}${suffix}`, width);
+}
+
+function flagsStyle(theme: Theme, value: string): (text: string) => string {
+  if (value === '—') return dimStyle(theme);
+  return (text) => theme.fg('warning', text);
+}
+
+const DOCUMENT_TABLE_COLUMNS: TableColumn<DocumentLike>[] = [
+  {
+    id: 'context',
+    label: 'Context',
+    width: 18,
+    value: (document) => contextText(document) ?? '—',
+    style: (theme) => accentStyle(theme),
+  },
+  {
+    id: 'team',
+    label: 'Team',
+    width: 12,
+    value: (document) => teamText(document) ?? '—',
+    style: (theme) => mutedStyle(theme),
+  },
+  {
+    id: 'updated',
+    label: 'Updated',
+    width: 10,
+    value: (document) => dateText(document.updatedAt) ?? '—',
+    style: (theme) => dimStyle(theme),
+  },
+  {
+    id: 'flags',
+    label: 'Flags',
+    width: 18,
+    value: flagsText,
+    style: flagsStyle,
+  },
+];
+
+function renderDocumentTable(documents: DocumentLike[], theme: Theme, width: number): string[] {
+  return renderResponsiveTable(documents, theme, width, {
+    columns: DOCUMENT_TABLE_COLUMNS,
+    primary: {
+      label: 'Title',
+      minWidth: TABLE_TITLE_MIN_WIDTH,
+      value: documentTitle,
+      style: (theme) => toolOutputStyle(theme),
+    },
+    dropOrder: ['flags', 'updated', 'team', 'context'],
+    fallback: formatDocumentListLine,
+  });
+}
+
+export function renderLinearDocumentListCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_list_documents', args, theme, [
+    ['first', 'first'],
+    ['last', 'last'],
+    ['orderBy', 'order'],
+    ['includeArchived', 'archived'],
+    ['filter', 'filter'],
+  ]);
+}
+
+export function renderLinearGetDocumentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_get_document', args, theme, [['documentId', 'documentId']]);
+}
+
+export function renderLinearCreateDocumentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_create_document', args, theme, [
+    ['title', 'title'],
+    ['teamKey', 'team'],
+    ['teamId', 'teamId'],
+    ['projectId', 'projectId'],
+    ['issueId', 'issueId'],
+    ['initiativeId', 'initiativeId'],
+  ]);
+}
+
+export function renderLinearUpdateDocumentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_update_document', args, theme, [
+    ['documentId', 'documentId'],
+    ['title', 'title'],
+    ['teamKey', 'team'],
+    ['teamId', 'teamId'],
+    ['projectId', 'projectId'],
+    ['issueId', 'issueId'],
+    ['initiativeId', 'initiativeId'],
+  ]);
+}
+
+export function renderLinearDeleteDocumentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_delete_document', args, theme, [
+    ['documentId', 'documentId'],
+  ]);
+}
+
+export function renderLinearUnarchiveDocumentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_unarchive_document', args, theme, [
+    ['documentId', 'documentId'],
+  ]);
+}
+
+export function renderLinearDocumentListResult(
+  result: AgentToolResult<any>,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  context: LinearToolRenderContext,
+): Text | LinearListResultComponent<DocumentLike> {
+  if (options.isPartial) return new Text(theme.fg('warning', 'Loading documents…'), 0, 0);
+  if (shouldShowJson(options, context)) return expandedJson(result, theme);
+
+  const documents = Array.isArray(documentDetails(result).documents)
+    ? (documentDetails(result).documents as DocumentLike[])
+    : [];
+
+  return new LinearListResultComponent(documents, theme, {
+    noun: 'document',
+    emptyLabel: 'No documents found',
+    previewLimit: DOCUMENT_LIST_PREVIEW_LIMIT,
+    renderItems: renderDocumentTable,
+  });
+}
+
+export function renderLinearDocumentResult(actionLabel: string) {
+  return (
+    result: AgentToolResult<any>,
+    options: ToolRenderResultOptions,
+    theme: Theme,
+    context: LinearToolRenderContext,
+  ): Text => {
+    if (options.isPartial) return new Text(theme.fg('warning', `${actionLabel}…`), 0, 0);
+    if (shouldShowJson(options, context)) return expandedJson(result, theme);
+
+    const document = documentDetails(result).document;
+    if (!document) {
+      return new Text(`\n${theme.fg('dim', 'Document not found')}\n\n${jsonHint()}`, 0, 0);
+    }
+
+    const metadata = metadataParts(document);
+    const snippet = documentSnippet(document);
+    const url = asString(document.url);
+
+    let text = `\n${theme.fg('success', `✓ ${actionLabel}`)} ${formatDocumentTitle(document, theme)}`;
+    if (metadata.length) text += `\n  ${theme.fg('dim', metadata.join(' · '))}`;
+    if (url) text += `\n  ${theme.fg('dim', url)}`;
+    if (snippet) text += `\n  ${theme.fg('muted', snippet)}`;
+    text += `\n\n${jsonHint()}`;
+
+    return new Text(text, 0, 0);
+  };
+}
+
+export function renderLinearDocumentSuccessResult(defaultActionLabel: string) {
+  return (
+    result: AgentToolResult<any>,
+    options: ToolRenderResultOptions,
+    theme: Theme,
+    context: { args?: unknown },
+  ): Text => {
+    if (options.isPartial)
+      return new Text(theme.fg('warning', `${defaultActionLabel} document…`), 0, 0);
+    if (shouldShowJson(options, context)) return expandedJson(result, theme);
+
+    const details = documentDetails(result);
+    const args = (context.args ?? {}) as ToolArgs;
+    const documentId = asString(args.documentId) ?? 'document';
+
+    if (details.success !== true) {
+      return new Text(
+        `\n${theme.fg('warning', `${defaultActionLabel} status unknown`)}\n\n${jsonHint()}`,
+        0,
+        0,
+      );
+    }
+
+    return new Text(
+      `\n${theme.fg('success', `✓ ${defaultActionLabel}`)} ${theme.fg(
+        'accent',
+        documentId,
+      )}\n\n${jsonHint()}`,
+      0,
+      0,
+    );
+  };
+}