[parnexcodes]

Closes #11

What

• file_command_failed and output_truncated now carry status 200; file_too_large stays 0 (matches dock-js and dock-go).
• files.write rejects content over 48 KB before base64-encoding, so a huge input fails fast.
• README: non-UTF-8 names in files.list come back with U+FFFD and cannot be passed back; list on a regular file raises file_command_failed; symlinked dirs list the target; statuses table text updated. There is no changelog file in this repo, so the README carries the notes.
• CI unit step runs pytest -rs and fails if any test is skipped; the symlink skip becomes a failure under CI.
• Review fixes: the unit step sets pipefail (the default Actions shell is bash -e, so pytest | tee hid a failing pytest), the README files.write example no longer splits "hi\n" across two lines, and the status note says file_not_utf8 is Python only.

Why

Cross-SDK consistency (dock-js#9 review) and a cheap guard against encoding hundreds of MB.

How to verify

ruff check . && ruff format --check . && mypy && DOCK_SCENARIOS_DIR=... DOCK_SCENARIOS_REQUIRED=1 pytest -rs: all pass locally (82 passed, 7 skipped: 1 CI-only, 6 live-API scenarios). New tests: 500 MB input fails fast with base64 patched to raise, non-UTF-8 name listing, status assertions 200/200/0.

Risk

Low. Behaviour change: DockError.status for two codes goes from 0 to 200, so callers matching on status 0 for these will change. Follow-up for the dock repo (not touched here): the sdk-scenarios/README.md table could state these statuses.

🤖 Generated with Claude Code

[parnexcodes]

Review: fix: file helper polish (statuses, early size check, docs, CI skips)

Verdict: SHIP (after the fixes in cfa0fe4)

Blocking

1. .github/workflows/ci.yml:29 (fixed in cfa0fe4) - pytest ... | tee unit.log ran under the default Actions shell, which the CI log shows as /usr/bin/bash -e {0} (no pipefail), so the step took tee's exit status. Failure: any failing unit test produced a green "Unit tests" step. Reproduced locally with a scratch failing test: bash -e -c 'pytest test_fail.py | tee unit.log; grep ...' exited 0; with set -o pipefail it exits 1. Fix: set -o pipefail at the top of the step. CI on cfa0fe4 shows the step running it, with 75 passed and nothing skipped.

Non-blocking

1. README.md:30 (fixed in cfa0fe4) - this was already broken before the PR: the files.write example split "hi\n" across two lines, which is a SyntaxError. It is now "hi\n", and every python block in the README compiles.
2. README.md:64 (fixed in cfa0fe4) - "dock-js and dock-go match" sat next to file_not_utf8, which neither of them has. It now says the statuses match for the codes they share and that file_not_utf8 is Python only.
3. src/usedock/client.py read/list - dock-js (assertCommandSize in #run) and dock-go (run) also raise file_too_large for a read or list whose path pushes the command over 64 KB. Python sends that command anyway, and the API rejects it with its own error. This predates the PR and is outside #11. It is worth a follow-up issue.

Verified

• Statuses: dock-js src/client.ts#run uses 200 for file_command_failed and output_truncated, and src/files.ts assertCommandSize uses 0 for file_too_large. dock-go files.go run/checkTruncated uses Status 200 for both and leaves Status unset (0) on file_too_large. Python now matches: 200/200/0. All three check the exit code before truncation.
• Early 48 KB check cannot refuse a write that fits. The fixed template overhead is 86 bytes with an empty path (88 with a one-character path). The largest content that fits in 64 KB is 49086 bytes for either path, which is below the 49152-byte early threshold. Content over 49152 always needs base64 of at least 65540 bytes, which is more than 65536 on its own.
• CI skip grep: it only reads the unit-step log (test_client.py and test_bash_resolver.py). The 6 live-scenario skips (set DOCK_API_URL, ...) happen in the separate "Scenario tests (offline)" step, which the grep does not read, so they do not fail CI. The CI-only bash test runs under CI=true, so the unit step reports 75 passed and 0 skipped.
• Tests cover the new behaviour: a 500 MB input with base64.b64encode patched to raise, a non-UTF-8 name decoded to U+FFFD, and status assertions for all three codes.

Checks

• ruff check .: pass
• ruff format --check .: pass
• mypy: pass
• DOCK_SCENARIOS_DIR=... DOCK_SCENARIOS_REQUIRED=1 pytest -rs (Windows, Git Bash): pass (82 passed, 7 skipped: 1 CI-only, 6 live-API scenarios without credentials)
• GitHub CI on cfa0fe4: test (3.9), test (3.13), gitleaks, cla all pass