refactor: introduce FileIO extension to abstract file transfer operations

.golangci.yml

@@ -27,6 +27,7 @@ linters:
     - reassign        # checks that package variables are not reassigned
     - unconvert       # removes unnecessary type conversions
     - unused          # checks for unused constants, variables, functions and types
+    - depguard        # blocks forbidden package imports
     - forbidigo       # forbids specific function calls
 
     # To enable later after fixing existing issues:
@@ -45,6 +46,7 @@ linters:
         linters:
           - bodyclose
           - gocritic
+          - depguard
           - forbidigo
       - path-except: (shortcuts/|internal/)
         linters:
@@ -54,67 +56,52 @@ linters:
           - forbidigo
 
   settings:
+    depguard:
+      rules:
+        shortcuts-no-vfs:
+          files:
+            - "**/shortcuts/**"
+          deny:
+            - pkg: "github.com/larksuite/cli/internal/vfs"
+              desc: >-
+                shortcuts must not import internal/vfs directly.
+                Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
+            - pkg: "github.com/larksuite/cli/internal/vfs/localfileio"
+              desc: >-
+                shortcuts must not import internal/vfs/localfileio directly.
+                Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
     forbidigo:
       forbid:
-        # ── Filesystem operations: use internal/vfs instead ──
-        - pattern: os\.Stat\b
-          msg: "use vfs.Stat() from internal/vfs"
-        - pattern: os\.Lstat\b
-          msg: "use vfs.Lstat() from internal/vfs"
-        - pattern: os\.Open\b
-          msg: "use vfs.Open() from internal/vfs"
-        - pattern: os\.OpenFile\b
-          msg: "use vfs.OpenFile() from internal/vfs"
-        - pattern: os\.Create\b
-          msg: "use vfs.OpenFile() from internal/vfs"
-        - pattern: os\.CreateTemp\b
+        # ── os: already wrapped in internal/vfs ──
+        - pattern: os\.(Stat|Lstat|Open|OpenFile|Rename|ReadFile|WriteFile|Getwd|UserHomeDir|ReadDir)\b
+          msg: "use the corresponding vfs.Xxx() from internal/vfs"
+        - pattern: os\.(Create|CreateTemp|MkdirTemp)\b
           msg: >-
-            internal/: use vfs.CreateTemp() from internal/vfs.
-            shortcuts/: avoid temp files entirely — use io.Reader streaming or in-memory buffers instead.
-        - pattern: os\.Mkdir\b
+            internal/: use vfs.CreateTemp() or vfs.OpenFile().
+            shortcuts/: avoid temp files — use io.Reader streaming or in-memory buffers.
+        - pattern: os\.Mkdir(All)?\b
           msg: "use vfs.MkdirAll() from internal/vfs"
-        - pattern: os\.MkdirAll\b
-          msg: "use vfs.MkdirAll() from internal/vfs"
-        - pattern: os\.Remove\b
+        - pattern: os\.Remove(All)?\b
           msg: >-
             internal/: use vfs.Remove() from internal/vfs.
-            shortcuts/: avoid temp files entirely — use io.Reader streaming or in-memory buffers instead.
-        - pattern: os\.RemoveAll\b
+            shortcuts/: avoid temp files — use io.Reader streaming or in-memory buffers.
+        # ── os: not yet in vfs — add to vfs/fs.go first ──
+        - pattern: os\.(Chdir|Chmod|Chown|Lchown|Chtimes|CopyFS|DirFS|Link|Symlink|Readlink|Truncate|SameFile)\b
+          msg: "add this function to internal/vfs/fs.go first, then use vfs.Xxx()"
+        # ── os: IO streams ──
+        - pattern: os\.Std(in|out|err)\b
+          msg: "use IOStreams (In/Out/ErrOut) instead of os.Stdin/Stdout/Stderr"
+        # ── os: process ──
+        - pattern: os\.Exit\b
+          msg: >-
+            Do not use os.Exit in shortcuts/. Return an error instead and let
+            the caller (cmd layer) decide how to terminate.
+        # ── filepath: functions that access the filesystem ──
+        - pattern: filepath\.(EvalSymlinks|Walk|WalkDir|Glob|Abs)\b
           msg: >-
-            internal/: add RemoveAll to internal/vfs/fs.go first, then use vfs.RemoveAll().
-            shortcuts/: avoid temp files entirely — use io.Reader streaming or in-memory buffers instead.
-        - pattern: os\.Rename\b
-          msg: "use vfs.Rename() from internal/vfs"
-        - pattern: os\.ReadFile\b
-          msg: "use vfs.ReadFile() from internal/vfs"
-        - pattern: os\.WriteFile\b
-          msg: "use vfs.WriteFile() from internal/vfs"
-        - pattern: os\.ReadDir\b
-          msg: "add ReadDir to internal/vfs/fs.go first, then use vfs.ReadDir()"
-        - pattern: os\.Getwd\b
-          msg: "use vfs.Getwd() from internal/vfs"
-        - pattern: os\.Chdir\b
-          msg: "add Chdir to internal/vfs/fs.go first, then use vfs.Chdir()"
-        - pattern: os\.UserHomeDir\b
-          msg: "use vfs.UserHomeDir() from internal/vfs"
-        - pattern: os\.Chmod\b
-          msg: "add Chmod to internal/vfs/fs.go first, then use vfs.Chmod()"
-        - pattern: os\.Chown\b
-          msg: "add Chown to internal/vfs/fs.go first, then use vfs.Chown()"
-        - pattern: os\.Lchown\b
-          msg: "add Lchown to internal/vfs/fs.go first, then use vfs.Lchown()"
-        - pattern: os\.Link\b
-          msg: "add Link to internal/vfs/fs.go first, then use vfs.Link()"
-        - pattern: os\.Symlink\b
-          msg: "add Symlink to internal/vfs/fs.go first, then use vfs.Symlink()"
-        - pattern: os\.Readlink\b
-          msg: "add Readlink to internal/vfs/fs.go first, then use vfs.Readlink()"
-        - pattern: os\.Truncate\b
-          msg: "add Truncate to internal/vfs/fs.go first, then use vfs.Truncate()"
-        - pattern: os\.DirFS\b
-          msg: "add DirFS to internal/vfs/fs.go first, then use vfs.DirFS()"
-        - pattern: os\.SameFile\b
-          msg: "add SameFile to internal/vfs/fs.go first, then use vfs.SameFile()"
+            These filepath functions access the filesystem directly.
+            internal/: use vfs helpers or localfileio path validation.
+            shortcuts/: use runtime.ValidatePath() or runtime.FileIO().
         # ── IO streams: use IOStreams from cmdutil instead ──
         - pattern: os\.Stdin\b
           msg: "use IOStreams.In instead of os.Stdin"

cmd/api/api.go

@@ -207,6 +207,7 @@ func apiRun(opts *APIOptions) error {
 		JqExpr:     opts.JqExpr,
 		Out:        out,
 		ErrOut:     f.IOStreams.ErrOut,
+		FileIO:     f.ResolveFileIO(opts.Ctx),
 	})
 	// MarkRaw tells root error handler to skip enrichPermissionError,
 	// preserving the original API error detail (log_id, troubleshooter, etc.).

cmd/service/service.go

@@ -250,6 +250,7 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 		JqExpr:     opts.JqExpr,
 		Out:        out,
 		ErrOut:     f.IOStreams.ErrOut,
+		FileIO:     f.ResolveFileIO(opts.Ctx),
 		CheckError: checkErr,
 	})
 }

extension/fileio/registry.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package fileio
+
+import "sync"
+
+var (
+	mu       sync.Mutex
+	provider Provider
+)
+
+// Register registers a FileIO Provider.
+// Later registrations override earlier ones.
+// Typically called from init() via blank import.
+func Register(p Provider) {
+	mu.Lock()
+	defer mu.Unlock()
+	provider = p
+}
+
+// GetProvider returns the currently registered Provider.
+// Returns nil if no provider has been registered.
+func GetProvider() Provider {
+	mu.Lock()
+	defer mu.Unlock()
+	return provider
+}

extension/fileio/types.go

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package fileio
+
+import (
+	"context"
+	"io"
+	"os"
+)
+
+// Provider creates FileIO instances.
+// Follows the same API style as extension/credential.Provider.
+type Provider interface {
+	Name() string
+	ResolveFileIO(ctx context.Context) FileIO
+}
+
+// FileIO abstracts file transfer operations for CLI commands.
+// The default implementation operates on the local filesystem with
+// path validation, directory creation, and atomic writes.
+// Inject a custom implementation via Factory.FileIOProvider to replace
+// file transfer behavior (e.g. streaming in server mode).
+type FileIO interface {
+	// Open opens a file for reading (upload, attachment, template scenarios).
+	// The default implementation validates the path via SafeInputPath.
+	Open(name string) (File, error)
+
+	// Stat returns file metadata (size validation, existence checks).
+	// The default implementation validates the path via SafeInputPath.
+	// Use os.IsNotExist(err) to distinguish "file not found" from "invalid path".
+	Stat(name string) (os.FileInfo, error)
+
+	// ResolvePath returns the validated, absolute path for the given output path.
+	// The default implementation delegates to SafeOutputPath.
+	// Use this to obtain the canonical saved path for user-facing output.
+	ResolvePath(path string) (string, error)
+
+	// Save writes content to the target path and returns a SaveResult.
+	// The default implementation validates via SafeOutputPath, creates
+	// parent directories, and writes atomically.
+	Save(path string, opts SaveOptions, body io.Reader) (SaveResult, error)
+}
+
+// File is the interface returned by FileIO.Open.
+// It covers the subset of *os.File methods actually used by CLI commands.
+// *os.File satisfies this interface without adaptation.
+type File interface {
+	io.Reader
+	io.ReaderAt
+	io.Closer
+	Stat() (os.FileInfo, error)
+}
+
+// SaveResult holds the outcome of a Save operation.
+type SaveResult interface {
+	Size() int64 // actual bytes written
+}
+
+// SaveOptions carries metadata for Save.
+// The default (local) implementation ignores these fields;
+// server-mode implementations use them to construct streaming response frames.
+type SaveOptions struct {
+	ContentType   string // MIME type
+	ContentLength int64  // content length; -1 if unknown
+}

internal/client/response.go

@@ -9,15 +9,13 @@ import (
 	"fmt"
 	"io"
 	"mime"
-	"path/filepath"
 	"strings"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
 )
 
 // ── Response routing ──
@@ -29,6 +27,7 @@ type ResponseOptions struct {
 	JqExpr     string        // if set, apply jq filter instead of Format
 	Out        io.Writer     // stdout
 	ErrOut     io.Writer     // stderr
+	FileIO     fileio.FileIO // file transfer abstraction; nil falls back to direct os calls
 	// CheckError is called on parsed JSON results. Nil defaults to CheckLarkResponse.
 	CheckError func(interface{}) error
 }
@@ -61,7 +60,7 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 			return apiErr
 		}
 		if opts.OutputPath != "" {
-			return saveAndPrint(resp, opts.OutputPath, opts.Out)
+			return saveAndPrint(opts.FileIO, resp, opts.OutputPath, opts.Out)
 		}
 		if opts.JqExpr != "" {
 			return output.JqFilter(opts.Out, result, opts.JqExpr)
@@ -75,11 +74,11 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 		return output.ErrValidation("--jq requires a JSON response (got Content-Type: %s)", ct)
 	}
 	if opts.OutputPath != "" {
-		return saveAndPrint(resp, opts.OutputPath, opts.Out)
+		return saveAndPrint(opts.FileIO, resp, opts.OutputPath, opts.Out)
 	}
 
 	// No --output: auto-save with derived filename.
-	meta, err := SaveResponse(resp, ResolveFilename(resp))
+	meta, err := SaveResponse(opts.FileIO, resp, ResolveFilename(resp))
 	if err != nil {
 		return output.Errorf(output.ExitInternal, "file_error", "%s", err)
 	}
@@ -88,8 +87,8 @@ func HandleResponse(resp *larkcore.ApiResp, opts ResponseOptions) error {
 	return nil
 }
 
-func saveAndPrint(resp *larkcore.ApiResp, path string, w io.Writer) error {
-	meta, err := SaveResponse(resp, path)
+func saveAndPrint(fio fileio.FileIO, resp *larkcore.ApiResp, path string, w io.Writer) error {
+	meta, err := SaveResponse(fio, resp, path)
 	if err != nil {
 		return output.Errorf(output.ExitInternal, "file_error", "%s", err)
 	}
@@ -119,23 +118,23 @@ func ParseJSONResponse(resp *larkcore.ApiResp) (interface{}, error) {
 // ── File saving ──
 
 // SaveResponse writes an API response body to the given outputPath and returns metadata.
-func SaveResponse(resp *larkcore.ApiResp, outputPath string) (map[string]interface{}, error) {
-	safePath, err := validate.SafeOutputPath(outputPath)
+// It delegates to FileIO.Save for path validation and atomic write; fio must not be nil.
+func SaveResponse(fio fileio.FileIO, resp *larkcore.ApiResp, outputPath string) (map[string]interface{}, error) {
+	result, err := fio.Save(outputPath, fileio.SaveOptions{
+		ContentType:   resp.Header.Get("Content-Type"),
+		ContentLength: int64(len(resp.RawBody)),
+	}, bytes.NewReader(resp.RawBody))
 	if err != nil {
-		return nil, fmt.Errorf("unsafe output path: %s", err)
-	}
-
-	if err := vfs.MkdirAll(filepath.Dir(safePath), 0700); err != nil {
-		return nil, fmt.Errorf("create directory: %s", err)
-	}
-
-	if err := validate.AtomicWrite(safePath, resp.RawBody, 0644); err != nil {
 		return nil, fmt.Errorf("cannot write file: %s", err)
 	}
 
+	resolvedPath, _ := fio.ResolvePath(outputPath)
+	if resolvedPath == "" {
+		resolvedPath = outputPath
+	}
 	return map[string]interface{}{
-		"saved_path":   safePath,
-		"size_bytes":   len(resp.RawBody),
+		"saved_path":   resolvedPath,
+		"size_bytes":   result.Size(),
 		"content_type": resp.Header.Get("Content-Type"),
 	}, nil
 }