document: PDFダウンロードサブコマンドを追加 (#18)

GET /api/v1/documents/{docid}/pdf を `xp document download` として実装し、
併せて Claude Code 用のプロジェクト設定 (.claude/CLAUDE.md) と .gitignore
の更新を行う。

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: buty4649

.claude/CLAUDE.md

@@ -0,0 +1,5 @@
+# About the API Specification
+
+* The API is defined using OpenAPI
+* The openapi.yaml file is located at tmp/openapi.yaml
+* If the file is not present, download it from https://atled-workflow.github.io/X-point-doc/api/openapi.yaml

.gitignore

@@ -38,4 +38,5 @@ go.work.sum
 # .vscode/
 
 # Claude Code
-/.claude/
+/.claude/workspace
+/tmp

README.md

@@ -97,6 +97,15 @@ cat search.json | xp document search --body -
 xp document search --size 100 --page 2
 ```
 
+### ドキュメントのPDFダウンロード
+
+```sh
+xp document download 266248                # カレントディレクトリにサーバ提供ファイル名で保存
+xp document download 266248 -o out.pdf     # 指定パスに保存
+xp document download 266248 -o pdfs/       # 指定ディレクトリにサーバ提供ファイル名で保存
+xp document download 266248 -o - > out.pdf # 標準出力に書き出し
+```
+
 ### レスポンススキーマの確認
 
 ```sh

cmd/document.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"text/tabwriter"
@@ -35,6 +36,8 @@ var (
 	docDeleteYes    bool
 	docDeleteOutput string
 	docDeleteJQ     string
+
+	docDownloadOutput string
 )
 
 var documentCmd = &cobra.Command{
@@ -109,13 +112,28 @@ By default the command prompts for confirmation. Pass --yes to skip it.`,
 	RunE: runDocumentDelete,
 }
 
+var documentDownloadCmd = &cobra.Command{
+	Use:   "download <docid>",
+	Short: "Download a document as PDF",
+	Long: `Download a document as PDF via GET /api/v1/documents/{docid}/pdf.
+
+By default the PDF is saved to the current directory using the filename
+provided by the server (Content-Disposition). Use --output to override:
+  --output FILE    save to FILE
+  --output DIR/    save into DIR/ using the server-provided filename
+  --output -       write the PDF to stdout`,
+	Args: cobra.ExactArgs(1),
+	RunE: runDocumentDownload,
+}
+
 func init() {
 	rootCmd.AddCommand(documentCmd)
 	documentCmd.AddCommand(documentSearchCmd)
 	documentCmd.AddCommand(documentCreateCmd)
 	documentCmd.AddCommand(documentGetCmd)
 	documentCmd.AddCommand(documentEditCmd)
 	documentCmd.AddCommand(documentDeleteCmd)
+	documentCmd.AddCommand(documentDownloadCmd)
 
 	f := documentSearchCmd.Flags()
 	f.StringVar(&docSearchBody, "body", "", "search condition JSON: inline, file path, or - for stdin")
@@ -143,6 +161,9 @@ func init() {
 	df.BoolVarP(&docDeleteYes, "yes", "y", false, "skip the interactive confirmation prompt")
 	df.StringVarP(&docDeleteOutput, "output", "o", "", "output format: table|json (default: table on TTY, json otherwise)")
 	df.StringVar(&docDeleteJQ, "jq", "", "apply a gojq filter to the JSON response (forces JSON output)")
+
+	dlf := documentDownloadCmd.Flags()
+	dlf.StringVarP(&docDownloadOutput, "output", "o", "", "output path: FILE, DIR/, or - for stdout (default: server-provided filename in current directory)")
 }
 
 func runDocumentSearch(cmd *cobra.Command, args []string) error {
@@ -312,6 +333,59 @@ func runDocumentDelete(cmd *cobra.Command, args []string) error {
 	})
 }
 
+func runDocumentDownload(cmd *cobra.Command, args []string) error {
+	docID, err := parseDocID(args[0])
+	if err != nil {
+		return err
+	}
+	client, err := newClientFromFlags(cmd.Context())
+	if err != nil {
+		return err
+	}
+
+	filename, data, err := client.DownloadPDF(cmd.Context(), docID)
+	if err != nil {
+		return err
+	}
+
+	out := docDownloadOutput
+	if out == "-" {
+		_, werr := os.Stdout.Write(data)
+		return werr
+	}
+
+	dst := resolveDownloadPath(out, filename, docID)
+	if err := os.WriteFile(dst, data, 0o600); err != nil {
+		return fmt.Errorf("write pdf: %w", err)
+	}
+	fmt.Fprintf(os.Stderr, "saved: %s (%d bytes)\n", dst, len(data))
+	return nil
+}
+
+// resolveDownloadPath decides the on-disk path for a downloaded PDF.
+//
+// When out is empty, the server-provided filename is used in the current
+// directory (falling back to "<docid>.pdf"). When out ends with a path
+// separator or names an existing directory, the server-provided filename is
+// placed inside it. Otherwise out is used verbatim as the file path. The
+// server-provided name is base-name-cleaned to avoid path traversal.
+func resolveDownloadPath(out, serverName string, docID int) string {
+	name := filepath.Base(filepath.Clean(serverName))
+	if name == "." || name == string(filepath.Separator) || name == "" {
+		name = fmt.Sprintf("%d.pdf", docID)
+	}
+	if out == "" {
+		return name
+	}
+	if strings.HasSuffix(out, string(os.PathSeparator)) || strings.HasSuffix(out, "/") {
+		return filepath.Join(out, name)
+	}
+	if info, err := os.Stat(out); err == nil && info.IsDir() {
+		return filepath.Join(out, name)
+	}
+	return out
+}
+
 func parseDocID(s string) (int, error) {
 	n, err := strconv.Atoi(strings.TrimSpace(s))
 	if err != nil || n <= 0 {

cmd/document_test.go

@@ -8,6 +8,50 @@ import (
 	"testing"
 )
 
+func TestResolveDownloadPath_DefaultUsesServerName(t *testing.T) {
+	got := resolveDownloadPath("", "経費.pdf", 42)
+	if got != "経費.pdf" {
+		t.Errorf("got = %q, want 経費.pdf", got)
+	}
+}
+
+func TestResolveDownloadPath_DefaultFallbackWhenEmpty(t *testing.T) {
+	got := resolveDownloadPath("", "", 42)
+	if got != "42.pdf" {
+		t.Errorf("got = %q, want 42.pdf", got)
+	}
+}
+
+func TestResolveDownloadPath_StripsPathTraversal(t *testing.T) {
+	got := resolveDownloadPath("", "../../etc/passwd", 99)
+	if got != "passwd" {
+		t.Errorf("got = %q, want passwd", got)
+	}
+}
+
+func TestResolveDownloadPath_ExplicitFile(t *testing.T) {
+	got := resolveDownloadPath("out.pdf", "server.pdf", 1)
+	if got != "out.pdf" {
+		t.Errorf("got = %q, want out.pdf", got)
+	}
+}
+
+func TestResolveDownloadPath_DirectorySuffix(t *testing.T) {
+	got := resolveDownloadPath("sub/", "doc.pdf", 1)
+	if got != filepath.Join("sub", "doc.pdf") {
+		t.Errorf("got = %q", got)
+	}
+}
+
+func TestResolveDownloadPath_ExistingDirectory(t *testing.T) {
+	dir := t.TempDir()
+	got := resolveDownloadPath(dir, "server.pdf", 1)
+	want := filepath.Join(dir, "server.pdf")
+	if got != want {
+		t.Errorf("got = %q, want %q", got, want)
+	}
+}
+
 func TestLoadSearchBody_Empty(t *testing.T) {
 	b, err := loadSearchBody("")
 	if err != nil {

cmd/schema.go

@@ -24,6 +24,7 @@ Supported aliases map to the CLI's commands:
   document.get      GET    /api/v1/documents/{docid}
   document.update   PATCH  /api/v1/documents/{docid}
   document.delete   DELETE /api/v1/documents/{docid}
+  document.download GET    /api/v1/documents/{docid}/pdf
 
 Run without arguments to list supported aliases.`,
 	Args: cobra.MaximumNArgs(1),

internal/schema/document.download.json

@@ -0,0 +1,19 @@
+{
+  "method": "GET",
+  "path": "/api/v1/documents/{docid}/pdf",
+  "summary": "PDFダウンロード",
+  "description": "指定された ID の書類の PDF をダウンロードする。閲覧権限が必要。OAuth2 認証を利用する場合は対象書類へのアクセス権限が必要。\n",
+  "parameters": [
+    {
+      "name": "docid",
+      "in": "path",
+      "type": "integer",
+      "required": true,
+      "description": "書類ID"
+    }
+  ],
+  "response": {
+    "type": "binary",
+    "description": "PDF バイナリ (Content-Type: application/pdf)。ファイル名は Content-Disposition ヘッダで返却され、RFC 5987 の filename* 形式を含む。"
+  }
+}

internal/schema/schema_test.go

@@ -11,6 +11,7 @@ func TestAliases_Sorted(t *testing.T) {
 		"approval.list",
 		"document.create",
 		"document.delete",
+		"document.download",
 		"document.get",
 		"document.search",
 		"document.update",
@@ -126,6 +127,19 @@ func TestLookup_DocumentUpdate(t *testing.T) {
 	}
 }
 
+func TestLookup_DocumentDownload(t *testing.T) {
+	op, err := Lookup("document.download")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if op["method"] != "GET" {
+		t.Errorf("method = %v", op["method"])
+	}
+	if op["path"] != "/api/v1/documents/{docid}/pdf" {
+		t.Errorf("path = %v", op["path"])
+	}
+}
+
 func TestLookup_DocumentDelete(t *testing.T) {
 	op, err := Lookup("document.delete")
 	if err != nil {

internal/xpoint/client.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"mime"
 	"net/http"
 	"net/url"
 	"os"
@@ -354,6 +355,62 @@ func (c *Client) DeleteDocument(ctx context.Context, docID int) (*DeleteDocument
 	return &out, nil
 }
 
+// DownloadPDF calls GET /api/v1/documents/{docid}/pdf and returns the PDF
+// bytes and the server-provided filename (parsed from Content-Disposition,
+// which may use RFC 5987 encoding). The filename is empty when the server
+// does not provide one.
+func (c *Client) DownloadPDF(ctx context.Context, docID int) (string, []byte, error) {
+	path := fmt.Sprintf("/api/v1/documents/%d/pdf", docID)
+	u := c.baseURL + path
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return "", nil, err
+	}
+	c.auth.apply(req)
+	req.Header.Set("Accept", "application/pdf")
+
+	debug := os.Getenv("XP_DEBUG") != ""
+	if debug {
+		fmt.Fprintf(os.Stderr, "[xp] %s %s\n", req.Method, u)
+	}
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return "", nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", nil, fmt.Errorf("read response body: %w", err)
+	}
+	if debug {
+		fmt.Fprintf(os.Stderr, "[xp] <- %s (%d bytes)\n", resp.Status, len(body))
+		if resp.StatusCode/100 != 2 {
+			fmt.Fprintf(os.Stderr, "[xp]    %s\n", string(body))
+		}
+	}
+	if resp.StatusCode/100 != 2 {
+		return "", nil, fmt.Errorf("xpoint api error: %s: %s", resp.Status, string(body))
+	}
+	return parseContentDispositionFilename(resp.Header.Get("Content-Disposition")), body, nil
+}
+
+// parseContentDispositionFilename extracts a filename from a Content-Disposition
+// header value, preferring the RFC 5987 filename* form when present.
+func parseContentDispositionFilename(cd string) string {
+	if cd == "" {
+		return ""
+	}
+	if _, params, err := mime.ParseMediaType(cd); err == nil {
+		if name := params["filename"]; name != "" {
+			return name
+		}
+	}
+	return ""
+}
+
 // do executes an HTTP request and decodes a JSON response into out.
 func (c *Client) do(ctx context.Context, method, path string, q url.Values, body []byte, out any) error {
 	u := c.baseURL + path