feat: restore document attachment compatibility

Author: ralfschimmel

graphql/mutations/documents.graphql

@@ -2,8 +2,7 @@
 # GraphQL mutations for Linear documents
 #
 # Documents are standalone entities that can be associated with projects,
-# initiatives, or teams. To link a document to an issue, use the
-# attachments API (see attachments.graphql).
+# initiatives, issues, or teams.
 # ------------------------------------------------------------
 
 # Create a new document mutation

src/commands/attachments.ts

@@ -1,8 +1,12 @@
 import type { Command } from "commander";
 import { createContext, getRootOpts } from "../common/context.js";
+import { invalidParameterError } from "../common/errors.js";
 import { handleCommand, outputSuccess } from "../common/output.js";
 import { type DomainMeta, formatDomainUsage } from "../common/usage.js";
-import type { AttachmentFilter } from "../gql/graphql.js";
+import type {
+  AttachmentCreateInput,
+  AttachmentFilter,
+} from "../gql/graphql.js";
 import { resolveIssueId } from "../resolvers/issue-resolver.js";
 import {
   createAttachment,
@@ -28,16 +32,39 @@ export const ATTACHMENTS_META: DomainMeta = {
 };
 
 interface ListOptions {
+  issue?: string;
   sourceType?: string;
   title?: string;
   createdAfter?: string;
   createdBefore?: string;
 }
 
 interface CreateOptions {
+  issue?: string;
   title: string;
   url: string;
   subtitle?: string;
+  comment?: string;
+  iconUrl?: string;
+}
+
+function resolveIssueArgument(
+  positionalIssue: string | undefined,
+  optionIssue: string | undefined,
+): string {
+  if (positionalIssue && optionIssue) {
+    throw invalidParameterError(
+      "--issue",
+      "cannot be combined with positional issue",
+    );
+  }
+
+  const issue = positionalIssue ?? optionIssue;
+  if (!issue) {
+    throw invalidParameterError("issue", "is required");
+  }
+
+  return issue;
 }
 
 function buildAttachmentFilter(
@@ -71,8 +98,9 @@ export function setupAttachmentsCommands(program: Command): void {
   attachments.action(() => attachments.help());
 
   attachments
-    .command("list <issue>")
+    .command("list [issue]")
     .description("list attachments on an issue")
+    .option("--issue <issue>", "issue identifier (alias for positional issue)")
     .option(
       "--source-type <type>",
       "filter by source type (e.g. github, slack)",
@@ -83,39 +111,47 @@ export function setupAttachmentsCommands(program: Command): void {
     .action(
       handleCommand(async (...args: unknown[]) => {
         const [issue, options, command] = args as [
-          string,
+          string | undefined,
           ListOptions,
           Command,
         ];
+        const issueIdentifier = resolveIssueArgument(issue, options.issue);
         const ctx = createContext(getRootOpts(command));
-        const issueId = await resolveIssueId(ctx.sdk, issue);
+        const issueId = await resolveIssueId(ctx.sdk, issueIdentifier);
         const filter = buildAttachmentFilter(options);
         const result = await listAttachments(ctx.gql, issueId, filter);
         outputSuccess(result);
       }),
     );
 
   attachments
-    .command("create <issue>")
+    .command("create [issue]")
     .description("create an attachment on an issue")
+    .option("--issue <issue>", "issue identifier (alias for positional issue)")
     .requiredOption("--title <title>", "attachment title")
     .requiredOption("--url <url>", "attachment URL")
     .option("--subtitle <text>", "attachment subtitle")
+    .option("--comment <text>", "comment body to create with the attachment")
+    .option("--icon-url <url>", "attachment icon URL")
     .action(
       handleCommand(async (...args: unknown[]) => {
         const [issue, options, command] = args as [
-          string,
+          string | undefined,
           CreateOptions,
           Command,
         ];
+        const issueIdentifier = resolveIssueArgument(issue, options.issue);
         const ctx = createContext(getRootOpts(command));
-        const issueId = await resolveIssueId(ctx.sdk, issue);
-        const result = await createAttachment(ctx.gql, {
+        const issueId = await resolveIssueId(ctx.sdk, issueIdentifier);
+        const input: AttachmentCreateInput = {
           issueId,
           title: options.title,
           url: options.url,
           ...(options.subtitle && { subtitle: options.subtitle }),
-        });
+          ...(options.comment && { commentBody: options.comment }),
+          ...(options.iconUrl && { iconUrl: options.iconUrl }),
+        };
+        const result = await createAttachment(ctx.gql, input);
         outputSuccess(result);
       }),
     );

src/commands/documents.ts

@@ -1,21 +1,18 @@
 import type { Command } from "commander";
 import { createContext, getRootOpts } from "../common/context.js";
+import { invalidParameterError } from "../common/errors.js";
 import { handleCommand, outputSuccess, parseLimit } from "../common/output.js";
 import { type DomainMeta, formatDomainUsage } from "../common/usage.js";
-import type { DocumentUpdateInput } from "../gql/graphql.js";
+import type { DocumentFilter, DocumentUpdateInput } from "../gql/graphql.js";
 import { resolveIssueId } from "../resolvers/issue-resolver.js";
 import { resolveProjectId } from "../resolvers/project-resolver.js";
 import { resolveTeamId } from "../resolvers/team-resolver.js";
-import {
-  createAttachment,
-  listAttachments,
-} from "../services/attachment-service.js";
+import { listAttachments } from "../services/attachment-service.js";
 import {
   createDocument,
   deleteDocument,
   getDocument,
   listDocuments,
-  listDocumentsBySlugIds,
   updateDocument,
 } from "../services/document-service.js";
 
@@ -27,6 +24,7 @@ interface DocumentCreateOptions {
   icon?: string;
   color?: string;
   issue?: string;
+  attachTo?: string;
 }
 
 interface DocumentUpdateOptions {
@@ -66,11 +64,30 @@ export function extractDocumentIdFromUrl(url: string): string | null {
 
     return docSlug.substring(lastHyphenIndex + 1) || null;
   } catch {
-    // URL constructor throws on malformed input — treat as unresolvable
+    // URL constructor throws on malformed input — treat as unresolvable.
     return null;
   }
 }
 
+function buildIssueDocumentFilter(
+  issueId: string,
+  legacyDocumentSlugIds: string[],
+): DocumentFilter {
+  const issueFilter: DocumentFilter = { issue: { id: { eq: issueId } } };
+  if (legacyDocumentSlugIds.length === 0) {
+    return issueFilter;
+  }
+
+  return {
+    or: [
+      issueFilter,
+      ...legacyDocumentSlugIds.map((slugId) => ({
+        slugId: { eq: slugId },
+      })),
+    ],
+  };
+}
+
 export const DOCUMENTS_META: DomainMeta = {
   name: "documents",
   summary: "long-form markdown docs attached to projects or issues",
@@ -115,48 +132,35 @@ export function setupDocumentsCommands(program: Command): void {
 
         const limit = parseLimit(options.limit || "50");
 
+        let projectId: string | undefined;
+        if (options.project) {
+          projectId = await resolveProjectId(ctx.sdk, options.project);
+        }
+
+        let issueId: string | undefined;
         if (options.issue) {
-          const issueId = await resolveIssueId(ctx.sdk, options.issue);
-          const attachments = await listAttachments(ctx.gql, issueId);
+          issueId = await resolveIssueId(ctx.sdk, options.issue);
+        }
 
-          const documentSlugIds = [
+        let filter: DocumentFilter | undefined;
+        if (projectId) {
+          filter = { project: { id: { eq: projectId } } };
+        } else if (issueId) {
+          const attachments = await listAttachments(ctx.gql, issueId);
+          const legacyDocumentSlugIds = [
             ...new Set(
               attachments
                 .map((att) => extractDocumentIdFromUrl(att.url))
                 .filter((id): id is string => id !== null),
             ),
           ];
-
-          if (documentSlugIds.length === 0) {
-            outputSuccess({
-              nodes: [],
-              pageInfo: { hasNextPage: false, endCursor: null },
-            });
-            return;
-          }
-
-          const documents = await listDocumentsBySlugIds(
-            ctx.gql,
-            documentSlugIds,
-          );
-          outputSuccess({
-            nodes: documents,
-            pageInfo: { hasNextPage: false, endCursor: null },
-          });
-          return;
-        }
-
-        let projectId: string | undefined;
-        if (options.project) {
-          projectId = await resolveProjectId(ctx.sdk, options.project);
+          filter = buildIssueDocumentFilter(issueId, legacyDocumentSlugIds);
         }
 
         const documents = await listDocuments(ctx.gql, {
           limit,
           after: options.after,
-          filter: projectId
-            ? { project: { id: { eq: projectId } } }
-            : undefined,
+          filter,
         });
 
         outputSuccess(documents);
@@ -187,9 +191,18 @@ export function setupDocumentsCommands(program: Command): void {
     .option("--icon <icon>", "document icon")
     .option("--color <color>", "icon color")
     .option("--issue <issue>", "also attach document to issue (e.g., ABC-123)")
+    .option("--attach-to <issue>", "alias for --issue")
     .action(
       handleCommand(async (...args: unknown[]) => {
         const [options, command] = args as [DocumentCreateOptions, Command];
+        if (options.issue && options.attachTo) {
+          throw invalidParameterError(
+            "--attach-to",
+            "cannot be combined with --issue",
+          );
+        }
+
+        const issueIdentifier = options.issue ?? options.attachTo;
         const rootOpts = getRootOpts(command);
         const ctx = createContext(rootOpts);
 
@@ -199,36 +212,20 @@ export function setupDocumentsCommands(program: Command): void {
         const teamId = options.team
           ? await resolveTeamId(ctx.sdk, options.team)
           : undefined;
+        const issueId = issueIdentifier
+          ? await resolveIssueId(ctx.sdk, issueIdentifier)
+          : undefined;
 
         const document = await createDocument(ctx.gql, {
           title: options.title,
           content: options.content,
           projectId,
           teamId,
+          issueId,
           icon: options.icon,
           color: options.color,
         });
 
-        if (options.issue) {
-          const issueId = await resolveIssueId(ctx.sdk, options.issue);
-
-          try {
-            await createAttachment(ctx.gql, {
-              issueId,
-              url: document.url,
-              title: document.title,
-            });
-          } catch (attachError) {
-            const errorMessage =
-              attachError instanceof Error
-                ? attachError.message
-                : String(attachError);
-            throw new Error(
-              `Document created (${document.id}) but failed to attach to issue "${options.issue}": ${errorMessage}.`,
-            );
-          }
-        }
-
         outputSuccess(document);
       }),
     );