feat: add `flatten` option to copy directory contents without parent folder

[ayyadurai-k]

Summary

Adds a new flatten parameter to automatically copy directory contents without including the parent folder structure in the target destination. This solves the common issue where source: "build/*" creates an unwanted build/ subdirectory on the remote server.

Context

Fixes common user pain point where deploying build outputs (e.g., build/*, dist/*) creates unnecessary parent folders on the target server. Users previously had to manually calculate strip_components values or restructure their deployment process.

Problem:

• Users expect source: "build/*" to copy only contents
• Currently creates target/build/file.html instead of target/file.html
• Manual strip_components calculation is error-prone and non-intuitive

Changes Made

• action.yml:

  • Added new flatten input parameter (default: false)
  • Added INPUT_FLATTEN environment variable
  • Full backward compatibility maintained

• entrypoint.sh:

  • Implemented process_flatten() function with intelligent path parsing
  • Auto-calculates directory depth for wildcard patterns (folder/*)
  • Handles directory paths (folder/) correctly
  • Automatically sets strip_components when flatten is enabled
  • Respects user-provided strip_components (no override if manually set)
  • Supports multiple comma-separated source paths

• Documentation (README.md, README.zh-cn.md, README.zh-tw.md):

  • Added flatten to File Transfer Settings configuration table
  • Added Example 6: "Flatten Directory Structure" with clear before/after demonstration
  • Updated Scenario Guide with new use case link
  • Added comprehensive FAQ entry explaining flatten usage
  • Complete translations for all language variants

Usage Example

Before (Problem):

source: "build/*"
target: "/www/htdocs/production/"
# Result: /www/htdocs/production/build/index.html ❌

After (Solution):

source: "build/*"
target: "/www/htdocs/production/"
flatten: true
# Result: /www/htdocs/production/index.html ✅

How It Works

The flatten feature intelligently analyzes source paths and automatically calculates the correct strip_components value:

Source Path	Flatten	Strip Components	Behavior
build/*	true	1 (auto)	Removes build/ parent
test-flatten/build/*	true	2 (auto)	Removes both levels
src/components/ui/*	true	3 (auto)	Removes all 3 levels
build/*,dist/*	true	2 (auto)	Uses max depth
build/*	false	(not set)	Preserves structure

Testing

✅ All tests passed successfully!

Unit Tests :

• [x] Default behavior (flatten=false) - strip_components not set
• [x] Single-level path (build/*) - correctly sets strip=1
• [x] Two-level path (test-flatten/build/*) - correctly sets strip=2
• [x] Three-level path (src/components/build/*) - correctly sets strip=3
• [x] Directory without wildcard (build/) - correctly handles
• [x] Multiple sources (build/*,dist/*) - uses max depth
• [x] Manual override - respects user-provided strip_components

Documentation

Complete documentation provided:

• [x] English README.md updated
• [x] Simplified Chinese (README.zh-cn.md) updated
• [x] Traditional Chinese (README.zh-tw.md) updated
• [x] Usage examples added to all versions
• [x] FAQ section updated in all languages
• [x] Configuration table updated
• [x] TESTING.md with comprehensive test guide