@alasano/pi-linear 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,18 @@
 # pi-linear
 
-![pi-linear screenshot](assets/screenshot.png)
+<p align="center">
+  <img src="assets/screenshot.png" alt="pi-linear settings overlay" />
+</p>
+
+<p align="center"><em>Configure Linear tools and output defaults from the settings overlay.</em></p>
+
+---
+
+<p align="center">
+  <img src="assets/linear_list_issues.png" alt="Human-readable Linear issue list" />
+</p>
+
+<p align="center"><em>Human-readable issue results keep screenshots clean while full JSON remains available with Ctrl+O.</em></p>
 
 Linear integration for [pi](https://pi.dev) with 55+ tools covering issues, projects, documents, initiatives, comments, relations, and more. Includes multi-workspace auth and a per-tool settings overlay.
 
@@ -46,7 +58,7 @@ Credentials are stored at `~/.pi/agent/state/extensions/linear/credentials.json`
 
 ## Tool settings
 
-Run `/linear-settings` to open an overlay where you can enable or disable tools by category or individually. Disabled tools are removed from the LLM's context entirely. Preferences persist across sessions.
+Run `/linear-settings` to open an overlay where you can choose the default output view and enable or disable tools by category or individually. Linear results default to a human-readable view, with full JSON available via `Ctrl+O`; you can flip the default to full JSON if you prefer. Disabled tools are removed from the LLM's context entirely. Preferences persist across sessions.
 
 ## Tools (55)
 

package/extensions/index.ts

@@ -210,5 +210,5 @@ export default async function linearExtension(pi: ExtensionAPI) {
     pi.registerTool(tool);
   }
 
-  registerLinearSettings(pi);
+  await registerLinearSettings(pi);
 }

package/extensions/renderers/comments.ts

@@ -0,0 +1,323 @@
+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;
+  title?: string | null;
+};
+
+type CommentUser = {
+  id?: string;
+  name?: string | null;
+  email?: string | null;
+};
+
+type CommentLike = {
+  id?: string;
+  body?: string | null;
+  quotedText?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  editedAt?: string | null;
+  resolvedAt?: string | null;
+  url?: string | null;
+  issue?: NamedRef | null;
+  parent?: { id?: string | null } | null;
+  user?: CommentUser | null;
+};
+
+type CommentResultDetails = {
+  comment?: CommentLike | null;
+  comments?: CommentLike[];
+  success?: boolean;
+};
+
+const COMMENT_LIST_PREVIEW_LIMIT = 20;
+const BODY_LIMIT = 180;
+const QUOTED_LIMIT = 90;
+const ISSUE_TITLE_LIMIT = 80;
+const TABLE_BODY_MIN_WIDTH = 24;
+
+function commentDetails(result: AgentToolResult<any>): CommentResultDetails {
+  return (result.details ?? {}) as CommentResultDetails;
+}
+
+function argsObject(context: { args?: unknown }): ToolArgs {
+  return context.args && typeof context.args === 'object' && !Array.isArray(context.args)
+    ? (context.args as ToolArgs)
+    : {};
+}
+
+function dateText(value: unknown): string | undefined {
+  const date = asString(value);
+  if (!date) return undefined;
+  const [datePart] = date.split('T');
+  return datePart || date;
+}
+
+function issueIdentifier(comment: CommentLike): string | undefined {
+  return asString(comment.issue?.identifier) ?? asString(comment.issue?.id);
+}
+
+function issueTitle(comment: CommentLike): string | undefined {
+  const title = asString(comment.issue?.title);
+  return title ? truncate(cleanOneLine(title), ISSUE_TITLE_LIMIT) : undefined;
+}
+
+function issueText(comment: CommentLike): string | undefined {
+  const identifier = issueIdentifier(comment);
+  const title = issueTitle(comment);
+  if (identifier && title) return `${identifier} ${title}`;
+  return identifier ?? title;
+}
+
+function formatIssueText(comment: CommentLike, theme: Theme): string {
+  const identifier = issueIdentifier(comment);
+  const title = issueTitle(comment);
+  if (identifier && title)
+    return `${theme.fg('accent', identifier)} ${theme.fg('toolOutput', title)}`;
+  if (identifier) return theme.fg('accent', identifier);
+  if (title) return theme.fg('toolOutput', title);
+  return theme.fg('dim', 'No issue');
+}
+
+function authorText(comment: CommentLike): string | undefined {
+  return (
+    asString(comment.user?.name) ?? asString(comment.user?.email) ?? asString(comment.user?.id)
+  );
+}
+
+function bodySnippet(comment: CommentLike, limit = BODY_LIMIT): string | undefined {
+  const body = asString(comment.body);
+  if (!body) return undefined;
+  return truncate(cleanOneLine(body), limit);
+}
+
+function quotedSnippet(comment: CommentLike, limit = QUOTED_LIMIT): string | undefined {
+  const quoted = asString(comment.quotedText);
+  if (!quoted) return undefined;
+  return truncate(cleanOneLine(quoted), limit);
+}
+
+function bodyPreview(comment: CommentLike): string {
+  const body = bodySnippet(comment);
+  const quoted = quotedSnippet(comment);
+
+  if (body && quoted && body !== quoted) return truncate(`${body} — quoted: ${quoted}`, BODY_LIMIT);
+  return body ?? (quoted ? `quoted: ${quoted}` : '(empty comment)');
+}
+
+function listMetadataParts(comment: CommentLike): string[] {
+  const issue = issueText(comment);
+  const author = authorText(comment);
+  const updated = dateText(comment.updatedAt);
+
+  return [
+    issue ? `issue: ${issue}` : undefined,
+    author ? `author: ${author}` : undefined,
+    updated ? `updated: ${updated}` : undefined,
+  ].filter((part): part is string => !!part);
+}
+
+function cardMetadataParts(comment: CommentLike): string[] {
+  const author = authorText(comment);
+  const updated = dateText(comment.updatedAt);
+  const edited = dateText(comment.editedAt);
+  const resolved = dateText(comment.resolvedAt);
+
+  return [
+    author ? `author: ${author}` : undefined,
+    updated ? `updated: ${updated}` : undefined,
+    edited ? `edited: ${edited}` : undefined,
+    resolved ? `resolved: ${resolved}` : undefined,
+  ].filter((part): part is string => !!part);
+}
+
+function formatCommentListLine(comment: CommentLike, theme: Theme, width: number): string {
+  const body = bodyPreview(comment);
+  const metadata = listMetadataParts(comment);
+  const suffix = metadata.length ? theme.fg('dim', ` · ${metadata.join(' · ')}`) : '';
+
+  return truncateLine(`  ${theme.fg('toolOutput', body)}${suffix}`, width);
+}
+
+const COMMENT_TABLE_COLUMNS: TableColumn<CommentLike>[] = [
+  {
+    id: 'issue',
+    label: 'Issue',
+    width: 16,
+    value: (comment) => issueText(comment) ?? '—',
+    style: (theme) => accentStyle(theme),
+  },
+  {
+    id: 'author',
+    label: 'Author',
+    width: 18,
+    value: (comment) => authorText(comment) ?? '—',
+    style: (theme) => mutedStyle(theme),
+  },
+  {
+    id: 'updated',
+    label: 'Updated',
+    width: 10,
+    value: (comment) => dateText(comment.updatedAt) ?? '—',
+    style: (theme) => dimStyle(theme),
+  },
+];
+
+function renderCommentTable(comments: CommentLike[], theme: Theme, width: number): string[] {
+  return renderResponsiveTable(comments, theme, width, {
+    columns: COMMENT_TABLE_COLUMNS,
+    primary: {
+      label: 'Body',
+      minWidth: TABLE_BODY_MIN_WIDTH,
+      value: bodyPreview,
+      style: (theme) => toolOutputStyle(theme),
+    },
+    dropOrder: ['updated', 'author', 'issue'],
+    fallback: formatCommentListLine,
+  });
+}
+
+function renderCommentCard(
+  actionLabel: string,
+  comment: CommentLike | null | undefined,
+  theme: Theme,
+): Text {
+  if (!comment) {
+    return new Text(`\n${theme.fg('dim', 'Comment not found')}\n\n${jsonHint()}`, 0, 0);
+  }
+
+  const metadata = cardMetadataParts(comment);
+  const quoted = quotedSnippet(comment);
+  const body = bodySnippet(comment);
+  const url = asString(comment.url);
+
+  let text = `\n${theme.fg('success', `✓ ${actionLabel}`)} ${formatIssueText(comment, theme)}`;
+  if (metadata.length) text += `\n  ${theme.fg('dim', metadata.join(' · '))}`;
+  if (quoted) text += `\n  ${theme.fg('dim', `quoted: ${quoted}`)}`;
+  if (body) text += `\n  ${theme.fg('muted', body)}`;
+  if (url) text += `\n  ${theme.fg('dim', url)}`;
+  text += `\n\n${jsonHint()}`;
+
+  return new Text(text, 0, 0);
+}
+
+export function renderLinearCommentListCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_list_comments', args, theme, [
+    ['first', 'first'],
+    ['last', 'last'],
+    ['orderBy', 'order'],
+    ['includeArchived', 'archived'],
+    ['filter', 'filter'],
+  ]);
+}
+
+export function renderLinearCreateCommentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_create_comment', args, theme, [
+    ['id', 'id'],
+    ['body', 'body'],
+    ['issueId', 'issueId'],
+    ['parentId', 'parentId'],
+    ['quotedText', 'quote'],
+  ]);
+}
+
+export function renderLinearUpdateCommentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_update_comment', args, theme, [
+    ['id', 'id'],
+    ['body', 'body'],
+    ['quotedText', 'quote'],
+  ]);
+}
+
+export function renderLinearDeleteCommentCall(args: ToolArgs | undefined, theme: Theme): Text {
+  return renderLinearToolCall('linear_delete_comment', args, theme, [['id', 'id']]);
+}
+
+export function renderLinearCommentListResult(
+  result: AgentToolResult<any>,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  context: LinearToolRenderContext,
+): Text | LinearListResultComponent<CommentLike> {
+  if (options.isPartial) return new Text(theme.fg('warning', 'Loading comments…'), 0, 0);
+  if (shouldShowJson(options, context)) return expandedJson(result, theme);
+
+  const comments = Array.isArray(commentDetails(result).comments)
+    ? (commentDetails(result).comments as CommentLike[])
+    : [];
+
+  return new LinearListResultComponent(comments, theme, {
+    noun: 'comment',
+    emptyLabel: 'No comments found',
+    previewLimit: COMMENT_LIST_PREVIEW_LIMIT,
+    renderItems: renderCommentTable,
+  });
+}
+
+export function renderLinearCommentResult(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);
+
+    return renderCommentCard(actionLabel, commentDetails(result).comment, theme);
+  };
+}
+
+export function renderLinearDeleteCommentResult(
+  result: AgentToolResult<any>,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  context: { args?: unknown },
+): Text {
+  if (options.isPartial) return new Text(theme.fg('warning', 'Deleting comment…'), 0, 0);
+  if (shouldShowJson(options, context)) return expandedJson(result, theme);
+
+  const details = commentDetails(result);
+  const args = argsObject(context);
+  const id = asString(args.id) ?? 'comment';
+
+  if (details.success !== true) {
+    return new Text(
+      `\n${theme.fg('warning', 'Deleted comment status unknown')}\n\n${jsonHint()}`,
+      0,
+      0,
+    );
+  }
+
+  return new Text(
+    `\n${theme.fg('success', '✓ Deleted comment')} ${theme.fg('accent', id)}\n\n${jsonHint()}`,
+    0,
+    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);
+}