Repository navigation
Description
Summary
POST /api/file/save cannot create a new file, and the route no longer has a caller in this public projection. Reporting both facts together because the second one changes how the first should be handled.
This follows #149, which was closed on 2026-10-19 as a backlog cleanup against an older release. The request in that closure was to re-open against the current version, so this is that report: verified against v0.7.2, source commit 3c21163 (2026-11-04), Node 24.18.0, pnpm 9.12.0, Windows 11 x64 (build 26200), PowerShell 5.1.
Product or interface
Source build or repository tooling — packages/local-runtime.
Issue area
File / workspace / path / encoding.
The route has no caller left
packages/local-runtime/src/http/ and packages/local-runtime-v2/src/http/ are listed in scripts/lib/retired-sources.mjs:20-21 as retired source roots, so the HTTP front door that exposed these routes is gone from this projection.
routeLocalFileApi is defined at packages/local-runtime/src/files/api.ts:276 and is not re-exported from the package: packages/local-runtime/src/index.ts:86-90 exports only createLocalWorkspaceGitFacade, listFileTree and searchFiles from ./files/api.js. A search of every tracked file finds exactly two references to routeLocalFileApi — the definition and its test — and packages/local-runtime/src/api/routes/ contains no file route. docs/ never mentions the endpoint.
So the route is unreachable in this projection. If the internal source still wires an HTTP surface to it, the bug below is live there and the fix ports back; if it does not, the leftover should be retired like http/ itself.
The bug
routeFileApi hands the save route the existence-requiring resolver:
// packages/local-runtime/src/files/api.ts:558
return routeFileSave(request, { readJsonBody, resolveBodyPath, readString, json });resolveBodyPath resolves through resolveExistingWorkspacePath (api.ts:1975), which calls realpath(target) (api.ts:1999) and maps the failure with classifyExistingPathError(error, 'file') (api.ts:2001). For a target that does not exist yet, realpath raises ENOENT, and packages/local-runtime/src/files/path-error.ts:14-22 maps that to:
{ status: 404, error: 'File not found', code: 'NOT_FOUND' }The handler in packages/local-runtime/src/files/save.ts — which does mkdir(dirname(target), { recursive: true }) and then writeFile — is therefore never reached for a new file. Only overwrites of an existing path work.
Steps to reproduce
At the HTTP-handler level, against a real workspace directory:
- Create an empty workspace directory.
POST /api/file/savewith{ "workspace": "<dir>", "path": "nested/new.txt", "content": "hello" }.- Observe the response.
Expected and actual behavior
- Expected:
200and the file exists at<dir>/nested/new.txt. - Actual:
404 File not found(NOT_FOUND), and no file is written.
The same request with an existing path returns 200 and overwrites, which is why the failure looks selective.
Fix
A create-tolerant resolver wired only into the save route: fix/file-save-create (50bb168, plus 112452a).
resolveCreateWorkspacePath mirrors the traversal and symlink-escape guards of the existing resolver — lexical traversal rejection, realpath on every existing prefix so a symlinked parent that leaves the workspace is denied with PATH_TRAVERSAL, and an explicit PATH_UNRESOLVABLE denial when an existing prefix cannot be resolved, so a write can never land through a dangling link. The missing remainder is created literally by the handler. Every other route keeps the existence-requiring resolver.
Verification
Test-first against the real route with a real filesystem (Windows 11 x64, Node 24.18.0):
- RED on
main:AssertionError: expected 404 to be 200— 2 failed / 1 passed / 2 skipped. - GREEN with the change: 3 passed / 2 skipped.
- Gates:
check:sourcePASS;typecheckPASS.
The two skipped cases are the symlink guards. This host has no Developer Mode, so symlink() fails with EPERM; the probe in packages/local-runtime/test/unit/file-api-save.test.ts reports them as skipped rather than letting them pass without exercising the guard. They are the first coverage for this route — the file API had no test at all.
NOT RUN: a POSIX host, and a host with the symlink privilege (Windows Developer Mode or elevated), which is where the two guard cases execute.
Question
Does the internal source still mount an HTTP surface on routeLocalFileApi? If yes, I will re-run the two symlink guard cases on a privileged host and report the result. If no, the route is dead code in this projection and retiring it — rather than fixing it — is the cleaner outcome, in which case I withdraw the fix branch and keep only the test file if that is still useful.
Activity