fix(project): guard --password-file reads on create/update

[naufalfx805-source]

Closes #79

Scoped per @zeshi-du's 2026-07-18 status correction: the --since half landed in #27, and this PR takes the --password-file half that is still live on main.

The defect

project create and project update resolve --password-file with a bare read:

password = readFileSync(opts.passwordFile, 'utf8').trim();

A path typo is the expected failure mode for a hand-typed flag, but it escapes as an unhandled Node exception rather than the CLI's typed validation error.

Before (origin/main @ fe07bc9):

$ testsprite project create --type backend --name Guarded \
    --password-file /nope/missing.txt --output json
{
  "error": "ENOENT: no such file or directory, open '/nope/missing.txt'"
}
$ echo $?
1

Three things are wrong: exit 1 instead of 5, an error that is a bare string rather than the { code, message, nextAction } envelope every other command emits (so --output json consumers break), and the absolute path plus errno leaked to stderr.

After (this branch):

$ testsprite project create --type backend --name Guarded \
    --password-file /nope/missing.txt --output json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "nextAction": "Flag `--password-file` is invalid: file does not exist: /nope/missing.txt.",
    "requestId": "local",
    "details": {
      "field": "password-file",
      "reason": "file does not exist: /nope/missing.txt"
    }
  }
}
$ echo $?
5

A directory argument (--password-file /tmp) previously crashed with EISDIR; it now returns the same envelope with not a regular file.

The change

New src/lib/secret-file.ts exporting readSecretFileGuarded(flag, path), mirroring readCodeFileGuarded in src/commands/test.ts — statSync first, map ENOENT / EACCES / EPERM / EISDIR and the not-a-regular-file case onto localValidationError, then read. Both call sites (project.ts:213, project.ts:329) route through it.

Errors report the path as typed, not the resolved absolute path, so no directory layout leaks into output.

Scope: deliberately not touching project auto-auth

project.ts:579 (project auto-auth --password-file) is the third bare site, but it belongs to #282 along with --credential-file, --client-secret-file, and --refresh-token-file — that issue is assigned and in progress. Fixing it here would collide.

Instead the helper takes the flag name as its first argument, so #282 can adopt it directly:

credential = readSecretFileGuarded('credential-file', opts.credentialFile);

That is the "split-out password-file guard" @zeshi-du pointed at in #248, available as a reusable unit rather than tangled with that PR's pagination work.

Two judgement calls

• No payload cap. readCodeFileGuarded enforces MAX_INLINE_CODE_BYTES. Secrets are small, and adding a size ceiling to a shipped flag is a behaviour change rather than part of fixing a crash. Happy to add one if you want the parity.
• No explicit BOM strip. U+FEFF is ECMAScript whitespace, so the existing .trim() already removes a BOM written by PowerShell 5.1's default Set-Content -Encoding utf8. There is a regression test pinning that, so it cannot silently regress if the trim is ever refactored.

Dry-run

Unchanged — both commands already return before password resolution, and the existing P7 — dry-run with --password-file does not read the filesystem test still passes.

Tests

15 new tests: 11 unit (src/lib/secret-file.test.ts) covering happy path, trimming, BOM, interior whitespace, relative-path resolution, empty file, missing file (code + exit + message + caller-supplied flag name + no absolute-path leak), and the directory case; 4 command-level (src/commands/project.test.ts) asserting runCreate / runUpdate reject with VALIDATION_ERROR exit 5 before any network call, that nextAction names the flag, and that a valid file is still read and sent.

npm test        → 59 files, 2043 passed | 2 skipped, 0 failing
npm run typecheck → clean
npx eslint      → clean
npx prettier --check → clean

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of password files during project creation and updates.
  • Missing, inaccessible, empty, or invalid password files now produce clear validation errors before any network request.
  • Password files are validated as regular files, with paths resolved consistently.
  • Existing valid password files continue to be read and submitted correctly.

[coderabbitai]

Walkthrough

The change adds guarded password-file reading, converts filesystem failures into VALIDATION_ERROR results, and applies the reader to project creation and update. Tests cover valid files, missing files, directories, content normalization, and prevention of network requests.

Changes

Password-file validation

Layer / File(s)	Summary
Guarded secret-file reader src/lib/secret-file.ts, src/lib/secret-file.test.ts	Adds readSecretFileGuarded with path resolution, regular-file validation, UTF-8 trimming, BOM removal, and typed filesystem error handling.
Project command integration src/commands/project.ts, src/commands/project.test.ts	Project create and update use guarded password-file reads. Tests verify validation before network access and successful password submission.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• fix(project): credential/auto-auth file flags bypass the file-read guard (raw ENOENT, exit 1, malformed --output json) #282 — Both changes update project password-file handling with guarded secret-file validation.

Possibly related PRs

• TestSprite/testsprite-cli#27 — Addresses --password-file error handling in src/commands/project.ts.
• TestSprite/testsprite-cli#139 — Modifies password validation in runCreate and runUpdate.
• TestSprite/testsprite-cli#283 — Replaces raw password-file reads with guarded validation.

Suggested reviewers: zeshi-du

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully addresses issue #79's --password-file requirement by implementing readSecretFileGuarded to return VALIDATION_ERROR (exit code 5) for missing/invalid files.
Out of Scope Changes check	✅ Passed	All changes focus on guarding --password-file reads; the PR explicitly excludes project auto-auth and other credential-file flags as out of scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the guarded --password-file handling added for project create and update.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[zeshi-du]

Approving and merging. This is the right shape: one guarded reader in src/lib/secret-file.ts rather than a try/catch at each call site, mapped onto the same VALIDATION_ERROR envelope as the existing readCodeFileGuarded, with the directory case rejected up front (so EISDIR-vs-empty-read platform divergence can't leak through) and a UTF-8 BOM stripped for files written by PowerShell's default Set-Content -Encoding utf8. The rationale comments are doing real work — thank you for writing them.

Two follow-ups, neither blocking this merge:

1. @OkeyAmy — #283 covers the --credential-file / auto-auth flags. Please rebase onto this and call readSecretFileGuarded() instead of inlining the guard; this helper was written with exactly those flags as the intended next migration, and its own docstring says so. (Your Windows unit test is also failing now that CI has actually run — details on that PR.)

2. The size-cap question stays open and I'll record the decision on #58 rather than settle it in two different places: this PR deliberately omits a cap, #283 proposes PAYLOAD_TOO_LARGE. Whichever way it goes, it belongs in the shared helper so both flag families behave identically.

Sorry this sat 8 days fully green with no review — that was on us, not you.