feat: support compiling a specific tex file as the root document

[SomeBottle]

Why

Currently, olcli only supports compiling a project's main document. In practice, however, a project may contain multiple documents that need to be compiled specifically, such as appendix.tex or reproducibility_checklist.tex.

The Overleaf API supports specifying the document to compile by setting the rootResourcePath field in the request body. Therefore, this PR adds support for selecting the compilation target in olcli using the -r / --resource option.

Changes

This change mainly affects the pdf, compile, and output commands.

A new command-line option, --resource <path>, along with its shorthand -r, has been added. The change is fully backward-compatible with previous versions, including the Library API.

New Test Cases

Test	What it verifies
upload test tex file to subfolder	Uploads sub/<TEST_ID>.tex using a relative path
compile project with --resource	Verifies that olcli compile -r 'sub/<TEST_ID>.tex' succeeds
compile with nonexistent --resource fails gracefully	Verifies that using -r with a nonexistent file exits with a non-zero status
download PDF with --resource	Verifies that olcli pdf -r ... produces a valid PDF file
output --list with --resource	Lists artifacts such as log, aux, and PDF files for the resource-specific compilation
download log output with --resource	Downloads the .log file for the resource-specific compilation and verifies that it is non-empty

E2E Test Results

• Command:

  OLCLI_E2E_PROJECT_NAME='TestProject' bash test/e2e.sh

• Result:

  ═══════════════════════════════════════════════════════════════
  Test Results
  ═══════════════════════════════════════════════════════════════
  
     Total tests:  68
     Passed:       68
     Failed:       0
  
  [PASS] All tests passed! 🎉
  

Issue Discovered While Running the Tests

The upload command may not handle absolute paths correctly.

olcli/test/e2e.sh

Lines 252 to 254 in 7dd9d73

	TEST_FILE="$TEST_DIR/${TEST_ID}.txt"
	echo "$TEST_CONTENT" > "$TEST_FILE"
	CLEANUP_REMOTE_FILES+=("${TEST_ID}.txt")

$TEST_DIR is an absolute path. Therefore, if TEST_ID=123, $TEST_FILE will look something like this:

/tmp/tmp.xxx/123.txt

In cli.ts, olcli upload normalizes the file path using the following logic:

olcli/src/cli.ts

Lines 745 to 750 in 7dd9d73

	// Preserve the relative path (e.g. 'figures/fig01.png') so the file lands
	// in the correct subfolder, not in project root. uploadFile() will
	// lazy-resolve the folder tree when no folderId/tree is supplied.
	// Normalize: strip leading './' and any leading slashes.
	const fileName = file.replace(/^(\.\/)+/, '').replace(/^\/+/, '');

As a result, $TEST_FILE is uploaded to a remote path such as:

tmp/tmp.xxx/123.txt

However, the download single file test attempts to download the file using only ${TEST_ID}.txt. The file therefore cannot be found, causing the test to fail:

olcli/test/e2e.sh

Lines 267 to 277 in 7dd9d73

	#######################################
	# Test: File Download (single file)
	#######################################
	log_section "File Download Tests"
	DOWNLOAD_FILE="$TEST_DIR/downloaded_${TEST_ID}.txt"
	run_test "download single file" \
	"olcli download '${TEST_ID}.txt' '$PROJECT_ID' -o '$DOWNLOAD_FILE'"

As a temporary workaround, the affected test cases now enter $TEST_DIR first (using cd) before running the upload command.

To address this path-resolution issue in cli.ts, one possible solution would be to introduce a --to option. This would allow users to explicitly specify the destination-relative path when uploading a file:

olcli upload /tmp/xxx/file.txt --to xxx/file.txt

What do you think? Looking forward to your reply.