Plan, tasks, tracker and estimates
A cross-platform (Linux + Windows) Qt frontend over WinSCP’s protocol core, built so that upstream WinSCP remains trackable with near-zero merge cost.
| File | Purpose |
|---|---|
| PLAN.md | Architecture, strategy, repo/branch model, risks |
| TASKS.md | Work breakdown with stable task IDs |
| TRACKER.md | Live status per task |
| ESTIMATES.md | Effort model, including AI-assisted estimate |
One codebase. Qt UI. Builds and runs on Linux and Windows. No Embarcadero C++Builder in the toolchain.
Phase 0 is 23 of 34 done; Phase 1 is 9 of 30. Upstream is pinned to
the latest stable release, 6.5.8.
source/core/Option.cpp compiles cleanly against
the shim on Linux and Windows — the first real WinSCP
core translation unit to build, on both platforms. Across the nine
tracked units, with nothing aborting on either target, the counts are
1,334 errors on Windows and 1,575 on Linux, ratcheted in CI per target
so neither platform can drift ahead unnoticed.
The shim covers UnicodeString, the byte-string family
with a UTF-8 codec, TDateTime, the Delphi exception
hierarchy, TCriticalSection,
TStrings/TStringList, directory search,
TClosure for __closure, the free
string/number/path routines, TVarRec/Format,
and a Win32 subset for POSIX. 15 test binaries pass on Linux and on
Windows under Wine.
__property is emulatable. clang
supports __declspec(property) under
-fms-extensions, verified on this machine (Debian clang 19)
for every form WinSCP uses: field-backed r/o, field-backed r/w,
method-backed with validating setter, read-modify-write, and indexed.
GCC does not — clang is mandatory. WinSCP’s own
compiler is already clang-based, so this is not a compiler-family
change.
Windows binaries can be produced on Linux. clang
emits valid x86-64 COFF for x86_64-w64-mingw32, lld
static-links it, and the result runs under Wine — the full test suite
does exactly that on every build.
The de-VCL’d core already exists and is
maintained. Far-NetBox (last commit 2026-07-24,
tracking WinSCP 6.5.6 — one minor behind our pin) builds WinSCP core
with MSVC/CMake over a hand-written ~16.3k-line VCL replacement in
src/base/. It is Win32-targeted and its frontend is useless
to us, but it is a proven reference for the hardest subsystem.
diff -u upstream gen
stays reviewable with zero offsets; it is asserted by a test rather than
defended at any cost.Two different questions, with two different answers.
Today’s VCL WinSCP: no. It requires Embarcadero
C++Builder 11 (bcc64) plus MSBuild, the VCL runtime, and
.dfm form compilation. The toolchain is Windows-only,
proprietary, and has no cross-compiler. There is no path to building the
current WinSCP.groupproj on Linux, and this will never
change.
The Qt branch: yes. Verified on this machine:
clang++ --target=x86_64-w64-windows-gnu -fms-extensions -> x86-64 COFF OK
clang++ --target=x86_64-pc-windows-msvc -fms-extensions -> x86-64 COFF OK
clang++ --target=x86_64-pc-linux-gnu -fms-extensions -> ELF 64-bit OK
All three with __declspec(property) emulation working.
So one compiler (clang) covers all targets, which matters because GCC
cannot compile the property shim at all.
Toolchain decision: clang + mingw-w64
(*-windows-gnu), not clang-cl. Rationale: no MSVC
licence or xwin SDK download needed, a single
libc++/libstdc++ story, and Debian ships the full mingw-w64
sysroot in apt. Keep the windows-msvc target as a later
option if MSVC ABI interop is ever required.
Two real gaps, both solvable:
g++-mingw-w64 is in apt but is useless to
us — GCC rejects __declspec(property). We need the
mingw-w64 headers, libs and binutils and then drive them with
clang++ --target=x86_64-w64-mingw32.Testing: Wine 10.0 is in apt. Good enough for CLI smoke tests and most Qt GUI behaviour. It is not sufficient to certify a Windows release — a real Windows CI runner is required before shipping binaries.
See §3 Upstream tracking model. Short version: the port never contains a modified copy of WinSCP source. A committed script transforms the pinned submodule into a generated tree at build time.
Endorsed as the end state, with one consequence worth stating plainly: Windows users lose the native-feeling VCL UI in exchange for a Qt one. That is the real cost of this project and the reason upstream would never undertake it. It also means C++Builder — a paid, proprietary, Windows-only compiler, and today the single largest barrier to outside contributors — leaves the toolchain entirely.
This is the one place the plan diverges from the brief. Three corrections.
(a) Most shims are not scaffolding — they are the permanent
portability layer. The UnicodeString /
TStrings / TDateTime shim is not a temporary
adapter; it is the cross-platform RTL. Deleting it means
replacing 5,178 UnicodeString and 497 TStrings
uses across the core with std::wstring/QString
and STL containers — a second project comparable in size to the first,
with no user-visible benefit and a large regression risk.
Recommendation: keep it permanently. A stable,
well-tested 16k-line shim nobody has to look at is a feature, not
debt.
What should eventually be deleted is different and much
cheaper: the VCL frontend, the Windows-only Pascal packages, and the
dual-target #ifdef __BORLANDC__ branches. That is Phase 4,
and it is weeks of work.
(b) Do not couple cleanup to 100% UI parity. These are independent axes, and coupling them creates a trap: you would carry the dual-build burden for an extra year waiting on the last few preference dialogs. The correct trigger for retiring the VCL build is parity on the features users actually depend on, which lands well short of all 48 dialogs. Decoupling them also means a stall in UI work never blocks toolchain cleanup.
(c) Do not make an architectural decision contingent on a social outcome. The maintainer has publicly called a Qt rewrite an “inconceivable task”. Plan for this fork to stand alone and be sustainable indefinitely; treat upstream adoption as upside. The “keep the VCL build green” discipline in §3 is what maximises the chance of adoption — but the architecture must not depend on it.
┌─────────────────────────────────────────────────────────────┐
│ qt/ Qt 6 frontend (ours, new) │
│ vcl-frontend/ existing VCL UI (upstream, frozen) │
├─────────────────────────────────────────────────────────────┤
│ core/Interface.h — the frontend contract (upstream, as-is) │
├─────────────────────────────────────────────────────────────┤
│ WinSCP core: SFTP SCP FTP WebDAV S3 (upstream, as-is) │
│ PuTTY 0.85 · FileZilla FTP engine (upstream, patched)│
├─────────────────────────────────────────────────────────────┤
│ port/shim/ VCL RTL replacement (ours, permanent) │
│ port/platform/ POSIX + Win32 helpers (ours, permanent) │
├─────────────────────────────────────────────────────────────┤
│ OpenSSL · expat · neon · libs3 (system packages) │
└─────────────────────────────────────────────────────────────┘
core/Interface.h already is a clean abstract frontend
contract — free functions and virtuals
(ShowExtendedException, CopyToClipboard,
ProcessGUI, CreateConfiguration,
StartThread). The core never calls the GUI directly.
ProcessGUI is virtual on TSessionUI, so a
headless frontend no-ops it. Config storage is already abstracted behind
THierarchicalStorage with both registry and INI backends;
Linux uses the INI path. We are filling in an existing seam, not
cutting a new one.
The __property rewrite expands to native VCL syntax
on C++Builder and to __declspec(property) everywhere
else:
#ifdef __BORLANDC__
#define PROP_RW_GS(T, Name, G, S) __property T Name = { read = G, write = S }
#else
#define PROP_RW_GS(T, Name, G, S) __declspec(property(get=G, put=S)) T Name
#endifThis makes the transformation non-destructive: the same transformed header compiles under C++Builder and under clang. That single property is what lets the VCL build stay green, what makes the diff theoretically acceptable upstream, and what keeps the port honest.
Property forms in core, all mechanically rewritable:
| Form | Count |
|---|---|
read = FField |
576 |
write = SetX |
362 |
read = GetX |
246 |
write = FField |
182 |
index = … (4 hand-written wrappers) |
4 |
default / nodefault /
stored |
0 |
591 declarations across core headers; four exceptions. Everything else is a one-line-in, one-line-out substitution.
Other Embarcadero extensions: __fastcall (5,277 sites)
becomes an empty #define — zero diff.
__closure (45 sites) becomes a macro over a
std::function-alike. ARRAYOFCONST (29) needs a
variadic shim. Delphi Set<> appears once in core.
Roughly 200 direct Win32 calls across ~40 distinct functions
(CreateFile, ReadFile,
GetFileAttributes, FindFirstFile,
WSAEventSelect, CreateEvent, one
RegQueryValueEx, one SHGetFolderPath). Rather
than edit core, implement that subset in
port/platform/win32-on-posix/. This keeps the core diff at
zero at the cost of a contained, well-understood compatibility module.
WSAEventSelect semantics are the awkward part; everything
else is routine.
Stored-password crypto is not DPAPI — core uses its
own Cryptography.cpp, so it ports cleanly.
Generated-tree model. This repo contains zero modified WinSCP source.
linscp/
├── 3rd-party/winscp/ submodule, pristine upstream, pinned to a tag
├── port/
│ ├── tools/transform.py committed, re-runnable, line-preserving
│ ├── patches/*.patch small series for what cannot be mechanised
│ ├── shim/ VCL RTL replacement (first-class source)
│ └── platform/ POSIX + Win32-on-POSIX (first-class source)
├── qt/ Qt 6 frontend (first-class source)
├── cmake/
└── build/gen/ generated transformed tree (gitignored)
Build = transform.py reads the submodule → writes
build/gen/ → compile build/gen/ +
port/ + qt/.
Updating to a new WinSCP release:
git -C 3rd-party/winscp fetch && checkout <new tag>transform.pyYour diff against upstream is structurally empty, so there is nothing to conflict. The maintenance burden is the script and the patch series, not 77k lines of forked code. Anything the script cannot express mechanically is a deliberate decision recorded as a patch — which keeps the patch series small by construction, because a growing series is an immediate, visible warning sign.
This is exactly what the submodule you asked for is good for: a pristine upstream reference, not a vendored copy to edit.
Branches
| Branch | Role |
|---|---|
main |
the port: port/, qt/, doc/,
submodule pin |
upstream-pin/* |
tags recording which WinSCP commit each release was built against |
No long-lived divergent branch is needed, because there is no forked
source to diverge. This is the structural reason to prefer this model
over forking winscp/winscp outright.
Do not mix VCL and Qt in one process. It is technically possible on Windows and a maintenance disaster, and it is impossible on Linux where VCL does not exist. “Incremental” must mean something else.
The workable model: two independent frontends over one ported core.
vcl-frontend/ — the existing UI, untouched, builds only
on Windows with C++Builder. Stays shippable throughout.qt/ — starts minimal and grows feature by feature on
both platforms.The Qt app becomes the default when it is good enough; the VCL build is retired in Phase 4. Users are never handed a half-ported UI, and UI work can stop and restart at any point without breaking anything.
The .dfm designer files are an asset here, not an
obstacle: each is a declarative spec of a dialog’s layout, widgets,
captions and tab order, which makes .dfm → .ui
conversion unusually tractable and reviewable.
The 121k lines of Pascal component packages are deleted, not ported — all seven map onto functionality Qt already ships:
| Deleted | Replaced by |
|---|---|
| Toolbar2000 + TBX (32k) | QToolBar / QMenuBar |
filemng shell tree (14k) |
QFileSystemModel |
| JCL (59k) | utility code; drop |
| PngComponents (4.6k) | Qt native image support |
dragndrop (3.6k) |
Qt native drag & drop |
Translations in translations/ should be reused rather
than rewritten; mapping WinSCP’s string tables onto Qt’s
tr()/.ts pipeline is a task in its own right
(P3-07) and is worth doing early enough to avoid hardcoded strings
accumulating.
The thing that makes this port tractable to verify, not just write:
Golden-output differential testing. WinSCP’s
scripting frontend emits deterministic XML session logs — the same
protocol the netstandard2.0 .NET assembly already consumes.
So:
This gives a regression suite over the core port for a fraction of the cost of writing unit tests for 77k lines, and it is the single highest-leverage item in Phase 0. Protocol servers come from containers (OpenSSH, vsftpd, ProFTPD, Apache/WebDAV, MinIO) so the matrix runs in CI.
Corollary benefit: the existing .NET assembly targets
netstandard2.0 already, so it will drive the Linux port
unchanged once the CLI speaks the same protocol.
| # | Risk | Severity | Mitigation |
|---|---|---|---|
| R1 | C++Builder rejects __property produced by macro
expansion, killing the dual-target keystone |
High | Cheap to test — one header, one person with a licence, Phase 0.
Macros expand before parsing and bcc64 is clang-based, so
confidence is high but it is unverified here. If it
fails, the VCL build cannot stay green and §3’s upstream story weakens
considerably. Test this first. |
| R2 | FileZilla WSAAsyncSelect → epoll rewrite introduces
subtle async bugs |
High | ~1,700 lines of hidden-window message-pump state machine. Golden-output suite + a real FTP server zoo. Budget generously; this is the least mechanical task in Phase 1. |
| R3 | No C++Builder licence and no Windows machine available locally | Medium | Windows CI runner; R1 needs a collaborator or a trial licence |
| R4 | Qt6-for-mingw not packaged; must be built once | Medium | Scripted, cached CI artifact; blocks only Phase 2+ |
| R5 | Qt UI parity is the dominant cost and may stall | Medium | Decouple from Phase 4 per Q4(b); ship a useful subset early |
| R6 | WSAEventSelect emulation on POSIX proves awkward |
Medium | Core’s socket use is mostly mediated by PuTTY/FileZilla; scope is small |
| R7 | Upstream churn outpaces the transform script | Low | Script is declarative and line-preserving; patch-series growth is the early-warning signal |
| R8 | Protocol regressions reach users | Medium | Golden suite is a merge gate, not an afterthought |
R1 is the project’s pivot point. Everything in §3 — the zero-diff upstream story, the green VCL build, the plausible path to maintainer adoption — rests on it. It is also among the cheapest things to test. Do it first, before any shim code is written.
| Phase | Outcome | Gate to exit |
|---|---|---|
| P0 Foundation | Transform script, CMake skeleton, CI on both platforms, golden harness | core/Common.cpp compiles on Linux clang; VCL build
still green (R1 resolved) |
| P1 Headless core | Core + CLI on Linux and Windows, one codebase | Real SFTP/FTP/S3/WebDAV sessions pass the golden suite on both platforms |
| P2 Qt shell | Minimal usable GUI client: connect, browse, transfer, queue | A user can do a day’s work in it |
| P3 Qt parity | Commander, sync, editor, dialogs, i18n | Parity on features users depend on |
| P4 Cleanup | VCL frontend retired, dual-target #ifdefs
collapsed |
Single-toolchain build; C++Builder gone |
P0 targets Windows first, because Far-NetBox already proves the de-VCL’d core compiles for Windows. That separates “does the shim work” from “does POSIX work” instead of hitting both risks simultaneously.
Stable IDs. Never renumber — append. Status lives in TRACKER.md.
Size: S ≤ 2 days · M ≤ 1 week · L ≤ 1 month · XL > 1 month (split before starting)
Goal: prove the keystone works, with no behaviour change anywhere.
| ID | Task | Size | Depends | Notes |
|---|---|---|---|---|
| P0-01 | Repo layout: port/, qt/,
cmake/, build/gen/ gitignored |
S | — | Per PLAN §3 |
| P0-02 | Pin submodule to a release tag, not master |
S | P0-01 | Done: 6.5.8, the latest stable. The 6.6.x line is all RC/beta |
| P0-03 | Dual-target property macro header
(port/shim/vcl_property.h) |
S | — | The keystone; PLAN §2. Every form routes through a public wrapper so private accessors stay reachable, as Borland’s do |
| P0-04 | Verify C++Builder accepts macro-expanded
__property |
S | P0-03 | R1. Do this first. Needs a licence + Windows. Blocks the zero-diff story |
| P0-05 | transform.py: __property rewriter,
line-preserving |
M | P0-03 | 591 decls, 4 forms + 4 manual |
| P0-06 | transform.py: __fastcall,
ARRAYOFCONST |
S | P0-05 | Done. __fastcall is an empty define;
ARRAYOFCONST pastes onto a variadic call |
| P0-06d | __closure: inline parameter form |
S | P0-06b | Done. Two sites in SessionInfo; declaration and
definition must agree or nothing links |
| P0-06b | __closure: TClosure type + typedef
transform |
M | P0-06 | Done. 44 typedefs rewritten to TClosure<Sig>;
contract measured from core (!= NULL 62,
== NULL 31, = NULL 51) |
| P0-06c | __closure: bind the bare-member-name call sites |
M | P0-06b | Done. 62 sites, compiler-discovered and committed to
port/patches/closure_sites.json; resolving macro expansions
to their definitions collapsed 118 reports to 62 |
| P0-07 | Transform idempotence + line-count assertion tests | S | P0-05 | Guards against silent drift |
| P0-08 | CMake skeleton: generate → compile one TU | M | P0-01, P0-05 | |
| P0-09 | Minimal shim to compile core/Common.cpp on Linux
clang |
M | P0-08 | The real measurement of shim cost |
| P0-10 | Install + script mingw-w64 sysroot; clang --target
toolchain file |
S | P0-08 | GCC is unusable — clang only |
| P0-11 | CI matrix: Linux native + Windows cross, both clang | M | P0-10 | From the first commit |
| P0-12 | Wine in CI for Windows smoke tests | S | P0-11 | Not release certification |
| P0-13 | Golden-output harness: runner, XML normaliser, differ | M | — | PLAN §5; highest leverage in P0 |
| P0-14 | Protocol server containers (OpenSSH, vsftpd, ProFTPD, WebDAV, MinIO) | M | P0-13 | |
| P0-15 | Capture golden XML corpus from real WinSCP on Windows | M | P0-13, P0-14 | Needs a Windows host |
| P0-16 | ADR log (doc/qt/adr/) |
S | — | Record toolchain/ABI choices as made |
| P0-17 | check_properties.py: compile-test every transformed
declaration |
S | P0-05 | Validates macro arity across the real corpus without the full shim |
| P0-18 | HTML render of the plan docs (build-html.sh) |
S | — | pandoc, self-contained, light/dark |
| P0-19 | Publish repository with licence and root README | S | — | Public, GPL-3.0; main released, qt
active |
| P0-20 | Generator for a PR-able branch against a winscp/winscp
fork |
M | P1-19 | Defer until there is something worth proposing (Q-7) |
| P0-21 | verify_transform.py: audit the generated tree against
upstream |
S | P0-05 | Byte-exactness is the invariant the whole model rests on |
| P0-22 | Rehearse history import into a winscp/winscp fork |
S | P0-05 | Validates Q-7 and measures the real conflict cost |
| P0-23 | check_docs.py: keep TASKS and TRACKER consistent |
S | — | Enforces the tracker rule mechanically rather than by discipline |
| P0-24 | Measure the VCL surface the core requires
(census.py) |
S | P0-05 | Resolves core identifiers against real mingw/OpenSSL/stdlib headers |
| P0-25 | ADR 0001: character width for UnicodeString |
S | P0-24 | Accepted: -fshort-wchar, std::u16string
storage |
| P0-26 | check_wide_abi.py: enforce ADR 0001 mechanically |
S | P0-25 | Wrong-ABI code links cleanly then misbehaves, so grep it |
| P0-27 | compile_census.py: classify what a real core TU still
needs |
S | P0-09 | Lets the compiler enumerate the shim gap instead of grep |
| P0-29 | Shim stubs for the unqualified legacy RTL header names | S | P0-27 | Classes.hpp etc.; their absence was aborting most TUs
early |
| P0-30 | Undo Win32 A/W name macros that collide with RTL names | S | P0-29 | ReplaceText broke this way: header declared it,
<windows.h> renamed the definition, link failed.
Guarded by a link-time test |
| P0-31 | Ratchet both targets and track early aborts | S | P0-28 | Linux compiles core now; an aborting unit reports a floor, which once read as progress |
| P0-32 | port/compat for headers missing from upstream
itself |
S | — | Withdrawn: the one case, help.h, is compiled out by
upstream’s WINSCP define, which the census was not
setting |
| P0-28 | census_ratchet.py: pin the census so progress cannot
slip back |
S | P0-27 | Nothing in core compiles cleanly yet, so a reintroduced type would look like a passing build |
Goal: one codebase, core + CLI, Linux and Windows. No GUI.
| ID | Task | Size | Depends | Notes |
|---|---|---|---|---|
| P1-01 | Shim: UnicodeString class |
L | P0-25 | 6,248 uses. Class done; 1-based API from measured usage |
| P1-01b | Shim: free string, number and path routines | L | P1-01 | Done. Option.cpp reaches 0 errors |
| P1-01d | Shim: TVarRec + Format +
ARRAYOFCONST |
M | P1-01b | Done. Behind FORMAT (438 uses) and FMTLOAD
(252) |
| P1-01e | Resource strings | M | P1-01d | Done with zero core changes: core’s
LoadStr is implemented in terms of Win32
LoadString, so only that is supplied, over a table
generated from upstream’s .rc files |
| P1-01c | Shim: AnsiString / UTF8String /
RawByteString + UTF-8 codec |
M | P1-01 | Distinct code-page types; wire-format correctness lives here |
| P1-02 | Shim: TObject, TStrings,
TStringList |
L | P1-01 | Done. 17 of the 30 Common.cpp errors |
| P1-02b | Shim: TList, TObjectList, Delphi sets |
M | P1-02 | Done. Notify is virtual and core overrides it |
| P1-03 | Shim: TDateTime + date/time RTL |
L | P1-01 | Done. 30 of 70 Common.cpp errors |
| P1-03b | Shim: SysUtils / IOUtils /
StrUtils file and path routines |
L | P1-03 | IncludeTrailingBackslash 39,
ExtractFileName 29 |
| P1-04 | Shim: Exception hierarchy + Delphi exception
semantics |
M | P1-01 | Done. Full C++Builder constructor set; descendants inherit it |
| P1-05 | Shim: TCriticalSection + SyncObjs |
M | P1-02 | Done; recursive, as Delphi’s is |
| P1-05b | Shim: TThread / StartThread |
M | P1-05 | Interface.h already abstracts thread creation |
| P1-08b | Shim: Masks, TPath,
TTimeSpan, TEncoding,
TNotifyEvent, env/version globals |
M | P1-01b | Done. The long tail the census named after the big groups cleared |
| P1-08c | Shim: XML DOM over vendored expat | M | P1-08b | Done. Real parsing, not a stub: a stub would silently import no sessions |
| P1-07c | port/platform: wide-character functions |
S | P1-07 | Done. glibc’s take a 4-byte wint_t, so they cannot be
called under -fshort-wchar |
| P1-09b | try/__finally for POSIX |
L | P1-08b | Done. All 179 blocks transformed, 0 unhandled, patch series still empty. Same expansion on both targets, so neither can rely on SEH |
| P1-06 | Shim:
TStream/THandleStream/TMemoryStream |
M | P1-02 | ~31 uses each; now the largest non-closure group |
| P1-06b | Shim:
TCustomIniFile/TMemIniFile/TRegistry |
M | P1-06 | Done. Real registry on Windows; on POSIX every key reports absent |
| P1-06c | Shim: DynamicArray, Delphi handle-based file API |
S | P1-06 | Done. Reference-counted, as core’s by-value Read
requires |
| P1-07 | port/platform: Win32 types, time and error subset |
L | P1-06 | Done for the compiling surface: Option.cpp builds on
Linux too |
| P1-07b | port/platform: Win32 file and handle functions |
L | P1-07 | CreateFile/ReadFile/WriteFile/CloseHandle
etc., as the census asks |
| P1-06d | Frontend decision: select the INI storage backend on Linux | S | P1-06b | TRegistryStorage cannot work there; core already
supports the INI path |
| P1-08 | WSAEventSelect / socket-event emulation |
M | P1-07 | R6 |
| P1-09 | PuTTY: re-import upstream unix/ backend |
M | P1-03 | Upstream maintains it; reconcile WinSCP’s patches |
| P1-10 | PuTTY: reconcile WinSCP deltas against vanilla 0.85 | M | P1-09 | |
| P1-11 | FileZilla: replace vendored MFC subset
(CString/CFile/CTime) |
M | P1-01 | Only 4 files in libs/mfc |
| P1-12 | FileZilla: WSAAsyncSelect hidden-window pump →
epoll/poll |
L | P1-11 | R2. ~1,700 lines; least mechanical task in P1 |
| P1-13 | Build libs/ from the submodule, not system copies |
M | P0-08 | expat done: the mingw sysroot has no expat, and upstream vendors it for exactly this reason. OpenSSL, neon, libs3 to follow |
| P1-14 | Drop puttyvs (MSVC wrapper, obsolete) |
S | P1-09 | |
| P1-15 | winscp.com shared-memory IPC → plain stdio |
M | P1-06 | Both platforms |
| P1-16 | Headless frontend implementing Interface.h |
L | P1-05, P1-15 | Derive from ConsoleRunner.cpp — it has zero
forms/ deps |
| P1-17 | First link + first real SFTP session on Linux | M | P1-16 | Expect a long tail of link/ABI issues |
| P1-18 | Same core + CLI cross-built for Windows, Wine-smoked | M | P1-17, P0-12 | Proves “one codebase” |
| P1-19 | Golden suite green across all six protocols, both platforms | L | P1-18, P0-15 | P1 exit gate |
| P1-20 | Verify stock netstandard2.0 .NET assembly drives the
Linux CLI |
S | P1-19 | Should work unchanged |
| P1-21 | #ifdef out dragext,
Setup.cpp, jump lists, file associations |
M | P1-16 | Windows-only or dropped |
| ID | Task | Size | Depends | Notes |
|---|---|---|---|---|
| P2-01 | Build Qt6 for mingw; cache as CI artifact | M | P0-10 | R4; not in Debian repos |
| P2-02 | Qt app skeleton, CMake integration, both platforms | M | P2-01, P1-19 | |
| P2-03 | Qt implementation of the Interface.h contract |
L | P2-02 | Prompts, errors, progress, busy, ProcessGUI |
| P2-04 | Session storage + site manager UI | L | P2-03 | INI-backed |
| P2-05 | Login / authentication dialogs (incl. host key, keyboard-interactive) | M | P2-03 | |
| P2-06 | Remote file panel: model/view, columns, sorting | L | P2-03 | QAbstractItemModel over
TRemoteFileList |
| P2-07 | Transfer engine wiring + queue UI | L | P2-06 | Over TTerminalQueue |
| P2-08 | Local file panel | M | P2-06 | QFileSystemModel |
| P2-09 | i18n pipeline: WinSCP string tables → Qt .ts |
M | P2-03 | Do early — avoids hardcoded strings |
| P2-10 | Packaging: AppImage/Flatpak + Windows installer | M | P2-07 | |
| P2-11 | P2 exit gate: a user can do a day’s work in it | S | P2-07, P2-10 |
| ID | Task | Size | Depends | Notes |
|---|---|---|---|---|
| P3-01 | .dfm → .ui assisted converter |
M | P2-02 | .dfm is a declarative layout spec — very tractable |
| P3-02 | Commander dual-pane: keyboard semantics, inline rename, custom columns | L | P2-08 | The main draw for most users |
| P3-03 | Synchronization UI + TSynchronizeChecklist view |
L | P2-07 | |
| P3-04 | Preferences dialogs (largest single cluster) | XL → split | P3-01 | Split per page before starting |
| P3-05 | Internal editor | L | P2-06 | Or delegate to $EDITOR / system editor |
| P3-06 | Remaining dialogs, batched in groups of ~8 of the 48 | XL → split | P3-01 | Track as P3-06a…f |
| P3-07 | Drag & drop: Qt native + XDS on Linux | M | P3-02 | |
| P3-08 | Shell integration: “open in terminal”, file associations | M | P3-02 | Per-platform |
| P3-09 | Accessibility pass | M | P3-06 | |
| P3-10 | P3 exit gate: parity on features users depend on | S | P3-02, P3-03, P3-04 | Explicitly not 100% of 48 dialogs |
| ID | Task | Size | Depends | Notes |
|---|---|---|---|---|
| P4-01 | Retire the VCL frontend; drop Pascal packages | M | P3-10 | 176k lines deleted |
| P4-02 | Collapse #ifdef __BORLANDC__ dual-target branches |
M | P4-01 | Simplifies the transform script |
| P4-03 | Fold the transform output into first-class source (optional) | L | P4-02 | Only once upstream tracking is no longer a goal — one-way door |
| P4-04 | Evaluate full de-shimming | S | P4-02 | Recommendation: do not. PLAN §1 Q4(a) — write the evaluation down and close it |
Last updated: 2026-10-11
Legend: todo · wip · blocked ·
done · dropped
| Phase | Done | Total | Gate |
|---|---|---|---|
| P0 Foundation | 25 | 35 | core/Common.cpp compiles on Linux clang; VCL build
green (R1) |
| P1 Headless core | 21 | 36 | Golden suite green, six protocols, both platforms |
| P2 Qt shell | 0 | 11 | A user can do a day’s work in it |
| P3 Qt parity | 0 | 10 | Parity on features users depend on |
| P4 Cleanup | 0 | 4 | Single toolchain; C++Builder gone |
| Total | 46 | 95 |
Driven by compile_census.py rather than by grep counts —
the compiler names what is actually blocking each unit, in dependency
order.
The whole core library compiles for Windows – all 33
units in upstream’s ScpCore.cbproj, 0 errors – and now not
only in the syntax-only census but as a real library:
linscp-core, built by CMake with the cross toolchain.
Linux: 558 errors, 14/33 clean, 4 aborting.
Link check (--target linscp-core-link,
every core object forced into one executable): 197 undefined
symbols on Windows, none of them the VCL shim’s or PuTTY’s.
WinSCP’s PuTTY (176 units) and the crypto it builds a second time with
MSVC (libs/puttyvs) both build with clang from the
submodule. What remains:
| Missing | Symbols | Task |
|---|---|---|
neon, OpenSSL, libs3 from libs/ |
~150 | P1-13 |
| FileZilla | 28 | P1-11 |
The frontend half of Interface.h
(StartThread, ProcessGUI, …) |
17 | P1-16 |
FileZilla.cbproj), with UNICODE.| Date | Decision | Rationale |
|---|---|---|
| 2026-10-10 | clang everywhere; GCC unsupported | GCC cannot compile __declspec(property); verified
locally |
| 2026-10-10 | mingw-w64 (*-windows-gnu) over clang-cl/MSVC |
No MSVC licence or SDK download; sysroot is in Debian apt |
| 2026-10-10 | Generated-tree model, not a source fork | Keeps the upstream diff structurally empty |
| 2026-10-10 | Keep the VCL RTL shim permanently | De-shimming is a second project of similar size with no user benefit |
| 2026-10-10 | Decouple shim cleanup from 100% UI parity | Coupling them would add ~a year of dual-build burden |
| 2026-10-10 | Two frontends over one core; never mix VCL and Qt in-process | Impossible on Linux, unmaintainable on Windows |
| 2026-10-10 | Windows target first in P0 | Far-NetBox already proves the core compiles for Windows; separates the two risks |
| 2026-10-10 | Line-preserving transform kept, but demoted from “constraint” to asserted property | It costs nothing — all 591 core declarations are already single-line
— and its real payoff is a reviewable zero-offset diff
against upstream, not debugger ergonomics. Asserted by a test; abandon
if it ever conflicts with something substantive |
| 2026-10-10 | index= properties handled by a PROP_R_GI
macro rather than a patch |
Removes the last 4 manual cases, so the transform covers 613/613 with an empty patch series |
| 2026-10-10 | Far-NetBox used as reference; verbatim reuse deferred pending licence clarification | Its README says GPLv3 but it ships the GPLv2 text (Q-6) |
| 2026-10-10 | Published as 99ecarvalho/linscp, public, GPL-3.0 | main is the released state; active work happens on
qt |
| 2026-10-11 | Compute cost recorded as measured token usage, not an estimate | The branch so far cost $297 of Opus 5 inference (99% of tokens are cache reads). Confirms compute is not the constraint, and shows Opus 5.5 would halve it — see ESTIMATES.md |
| 2026-10-11 | VCL’s TThread class not shimmed |
Its only user, KeyGen.cpp, is in none of upstream’s
.cbproj files and TKeyGenerator is referenced
nowhere else — dead code upstream. Core’s own TSimpleThread
uses StartThread and Win32 directly |
| 2026-10-11 | P1-05b scoped as Win32 kernel objects on POSIX, plus Delphi
BeginThread/EndThread on both targets |
That is what core actually calls: 28 CloseHandle, 6
waits, 5 CreateEvent, 10 GetCurrentThreadId.
BeginThread is written once over CreateThread,
so upstream’s frontend StartThread ports unchanged |
| 2026-10-11 | POSIX kernel objects share one handle table, one lock and one condition variable; handle values are never reused | Makes WaitForMultipleObjects over mixed threads and
events — including atomic WaitAll — correct by
construction. Core has a handful of threads, so the coarse lock costs
nothing measurable. Never reusing values turns use-after-close into
ERROR_INVALID_HANDLE |
| 2026-10-11 | Shim XML interfaces live in Xml::Xmlintf; only the
_di_ aliases are global |
Embarcadero’s own layout. At global scope ours collided on Windows
with the COM IXMLDocument from
<msxml.h>. Core names them only through
_di_ aliases and Xmlintf:: |
| 2026-10-11 | Closure-site discovery compiles a separately transformed, unbound tree | Compiling the ordinary tree saw the known sites already wrapped and “rediscovered” only new ones — it cut 62 sites to 2. Now idempotent: a second run is byte-identical |
| 2026-10-11 | VCL’s implicit SysUtils::LoadStr and
Vcl.Menus::StripHotkey supplied by the shim, not by
patching core |
Core receives both through <vcl.h> and never
declares them. LoadStr is built on the existing
LoadString table, so there is still one resource path |
| 2026-10-11 | Core is compiled with upstream’s own preprocessor configuration,
read from ScpCore.cbproj by
port/tools/upstream_defines.py |
Copying the list would drift. Applied by the census, closure
discovery and CMake alike, shim included, because UNICODE
decides which Win32 A/W function every macro names. Windows-only names
are dropped on POSIX; _CRTIMP= is dropped everywhere, as
C++Builder’s CRT linkage |
| 2026-10-11 | Census and discovery build the Debug configuration | Its DebugAssert expressions are code that must compile
too; Release compiles them out, which hid ten closure comparisons |
| 2026-10-11 | port/compat withdrawn; supersedes the 2026-10-10
decision creating it |
help.h was compensating for the missing
WINSCP define, not a gap in upstream: with
WINSCP set, PuTTY’s platform.h never includes
it |
| 2026-10-11 | Closure binding covers Borland’s four shapes: Name,
&Name, obj.Name /
&obj.Name, p->Name /
&p->Name |
Recorded as the method name’s column; the transform recovers the
shape from the text and refuses longer chains or a call as the object.
The verifier recomputes the rewrite with an independent regex, so a bug
in either is caught by the other. The old binder had been emitting
obj.CLOSURE(Name), invalid C++, in two units nothing yet
compiled |
| 2026-10-11 | Win32 APIs core calls under the bare name get forwarding functions, not their A/W macros | vcl_win32_undef.h removes the macros so they cannot
rename the shim’s VCL functions; it had also removed
CreateFile and four others core calls as the API, leaving
those calls nothing to bind to. Exact signatures, so core’s
NULL arguments still convert |
| 2026-10-11 | __int64 is clang’s MS-extension keyword, never a
macro |
A long long macro – ours, and mingw’s own – breaks
core’s __int64(x) functional casts |
| 2026-10-11 | Random is Delphi’s own generator |
It reproduces the published Turbo Pascal / Delphi sequence from a zero seed exactly, which the test pins |
| 2026-10-11 | C++Builder’s static class properties become static
const pointers (TEncoding::UTF8) |
clang accepts static __declspec(property) but compiles
it as a plain static member, failing only at link (see verified facts).
Pointers serve both of core’s spellings, as a value and through
->;
[[clang::require_constant_initialization]] guarantees no
static-init-order exposure |
| 2026-10-11 | Win32MajorVersion() and friends are functions, read
from RtlGetVersion |
Core calls them as functions. GetVersionEx reports 6.2
to an unmanifested executable, which would turn core’s
IsWin10() false on 10 and 11. Computed on first use, which
also removes a dynamic-initialiser hazard |
| 2026-10-11 | StaticArray<T, N> keeps one slack element, filled
by its owner with a value no input matches |
Core passes Size() as an open array’s high
index (ParseShortEngMonthName) and reads one past the
end. In C++Builder that is whatever follows; here it is defined and
means “not found” |
| 2026-10-11 | The census measures every core unit in ScpCore.cbproj,
read from the project, in parallel |
Ten units were a sample. Reading the list from upstream means a unit it adds fails the ratchet until baselined, rather than going unmeasured. 66 compiles take about 5 s |
| 2026-10-11 | Case-mismatched upstream includes get checked-in forwarding headers
in port/casefold |
They resolve only on case-insensitive file systems, so a Linux host
fails even when cross-compiling for Windows. Explicit, not generated: a
basename match would have mapped putty/windows/gss.c’s
security.h – the Windows SDK header – onto core’s
Security.h. check_include_case.py applies a
same-directory rule and fails on drift either way |
| 2026-10-11 | ARRAYOFCONST expands to C++Builder’s two arguments, a
TVarRec pointer and the high index |
Core’s own functions take open arrays that way
(ExecCommand, ExtException), so a single
container argument cannot reach them. The count comes from
sizeof over an unevaluated call, so each value is evaluated
once – C++Builder’s macro evaluates them twice |
| 2026-10-11 | The XML DOM follows Delphi’s model: text and comment nodes as children, Null attribute variants, raising loaders | FileZilla keeps a site’s name as a text node among element children,
found by NodeType; core tests absent attributes with
IsNull(); and ImportFromFilezilla has no
handler around LoadFromFile, so a malformed file must raise
rather than import nothing. The earlier bool loaders were a
divergence justified by a wrong reading of core |
| 2026-10-11 | TCustomIniFile’s virtuals take parameters by value, and
its abstract set is Delphi’s eight |
C++Builder declares Delphi virtuals that way and core’s
TOptionsIniFile overrides with exactly those signatures;
by-reference parameters made its methods new functions and left the
class abstract |
| 2026-10-11 | TStrings::Text uses CRLF on both platforms |
Delphi’s POSIX RTL uses LF. Core builds configuration and
server-facing text through Text, and identical output
everywhere matters more |
| 2026-10-11 | try/__finally brace depth is measured over code only | A } inside a comment in a __finally body
put LINSCP_END_FINALLY one brace early in
ScpFileSystem.cpp. Comments and string/character literals are now
blanked before counting; still 179 blocks |
| 2026-10-11 | The transform finds its patch series relative to itself, and a missing one is an error | CMake runs it from the build tree, where the relative path found
nothing: every CMake-built tree had no closure bindings at
all, and the verifier, loading the same way, agreed. The census
ran from the repo root and never saw it.
bind_closures.py --require-bound now checks the tree the
build compiles |
| 2026-10-11 | Header function definitions at namespace scope get
inline (transform rule, verified) |
Common.h defines IsWideChar without it:
one definition per including unit, 31 in all, which C++Builder’s linker
tolerates and the standard forbids. A rule rather than a patch, so a new
one upstream is handled too; a global
--allow-multiple-definition would have hidden real
duplicates |
| 2026-10-11 | The shim’s ExpandEnvironmentVariables removed |
Core defines it itself, with Windows %VAR% semantics
through ExpandEnvironmentStrings. The shim’s was an
invented POSIX $VAR variant, a duplicate the syntax-only
census could not see. Linux gets ExpandEnvironmentStrings
with Windows semantics instead (P1-07b) |
| 2026-10-11 | Include paths with backslashes are normalised to /
(transform rule, verified) |
Only Windows resolves #include "ssh\gss.h"; clang
accepts it when targeting Windows and not otherwise. Six such includes,
five in core: part of why units abort on Linux. A forwarding file named
with a backslash would break Windows checkouts |
| 2026-10-11 | The patch series exists, applied before the rules, strictly: exact context, line counts preserved | First patch: putty-64bit-conf-defaults.patch. WinSCP
stores string option defaults as (int)"..." in an int-first
union, which truncates pointers on x86-64; the first union member
becomes intptr_t. Upstream is built 32-bit only, so this is
new territory for its code |
| 2026-10-11 | Defines are per project, not global | PuTTY is built without UNICODE, core and FileZilla with
it, and UNICODE decides which Win32 A/W function each macro
names. Core’s are public on the shim, so everything built against it
sees them |
| 2026-10-11 | Core’s overrides of PuTTY symbols are expressed by weakening PuTTY’s copies in the archive | PuttyIntf.cpp redefines appname and
get_remote_username, relying on C++Builder’s linker keeping
the first definition. GNU objcopy marks PuTTY’s weak (llvm-objcopy
cannot for COFF); check_overrides.py keeps
overrides.txt exact. Sources untouched, and dual-target,
which a weak attribute in a patch would not be |
| 2026-10-11 | aes-ni.c is compiled with -msse4.1 -maes,
its CPU check verified free of those instructions |
WinSCP dropped PuTTY’s per-function target attributes, which MSVC
does not need; restoring them would break the MSVC build of the same
file. check_isa_free.py disassembles
aes_ni_available and fails on any SSE4.1 or AES-NI
instruction |
| 2026-10-11 | Case-mismatched includes are respelled in the generated tree
(transform rule); port/casefold withdrawn |
Supersedes the forwarding headers: once FileZilla compiles from the generated tree, a forwarder to the pristine header would mix untransformed code into a transformed unit. Same same-directory rule, now a verified transform rule; core, PuTTY and FileZilla all include from the generated tree |
| 2026-10-11 | FileZilla and WinSCP’s MFC subset join the transform’s scope; two more patches | mfc-x86-64.patch: the subset keys off
_X86_ where it means “not 32-bit”, so it wants an
unvendored afxv_cpu.h, withholds GetLength64
and asserts on I64.
filezilla-ws2tcpip-case.patch:
<Ws2tcpip.h>, the only system include whose case only
Windows forgives |
| 2026-10-11 | MFC and FileZilla units are compiled with a forced prelude:
<windows.h> without its A/W macros |
FileZilla includes afx.h before any core header, so
MFC’s members were declared under the macros
(CString::LoadString became LoadStringW) and
then called without them. The prelude drops windows.h’s outer guard
after removing the macros, so afx.h’s include-order check
passes and its re-include brings nothing back. MFC’s
CString::LoadString then reaches the shim’s resource table,
which already holds FileZilla’s strings |
| 2026-10-10 | A PR-able branch against winscp/winscp will be
generated, not hand-maintained |
linscp shares no history with upstream, so its qt
branch is not directly mergeable. Since the port is mechanical, the fork
branch can be produced on demand (Q-7). Rehearsed end to end — see facts
below |
| 2026-10-10 | Transform must be byte-exact outside property lines | A full-file rewrite (CRLF loss) turned a 613-line change into
76,551. Now asserted by verify_transform.py |
| 2026-10-10 | Field/accessor classification is convention-first, parens only as fallback | The parens heuristic false-positives on constructor initialiser
lists; WinSCP’s F<Upper> /
Get*/Set* convention is airtight. Truly
unclassifiable names now fail the run instead of producing a wrong-arity
macro |
| 2026-10-10 | Windows releases link statically via lld | -fuse-ld=lld -static -L/usr/x86_64-w64-mingw32/lib;
leaves only KERNEL32 and msvcrt as deps |
| 2026-10-10 | CMake hard-fails on non-clang compilers | A clear configure-time error beats a confusing failure in the first transformed header |
| 2026-10-10 | The transform stamp lives outside the generated tree | verify_transform.py treats any extra file as a
violation, which is the behaviour we want; the stamp was the first thing
it caught |
| 2026-10-10 | Accepted (Q-8): -fshort-wchar with
std::u16string storage; std::wstring banned in
port/ |
Only option leaving upstream’s thousands of L"..."
literals untouched. Enforced by check_wide_abi.py and a
static_assert. ADR 0001 |
| 2026-10-10 | -fshort-wchar set globally, not per-target |
One translation unit without it is an ABI landmine that links cleanly |
| 2026-10-10 | UnicodeString case folding is ASCII-only for now |
Delphi’s is locale-aware; core uses it on protocol tokens and switch names. Recorded as a known limitation, not silently equivalent |
| 2026-10-10 | vcl.h transitively exposes the Win32 API |
Matches C++Builder, which upstream’s CorePCH.h depends
on: it includes <vcl.h> and core’s headers before
<Winapi.Windows.hpp>. Fixing this alone removed 9 of
24 missing types |
| 2026-10-10 | UTF-8 decoding substitutes one U+FFFD per maximal subpart | Unicode’s recommended practice. The first implementation emitted one per byte; a test on truncated input caught it |
| 2026-10-10 | Byte strings keep C++Builder’s code-page template shape | Core relies on RawByteString and
UTF8String being distinct types; collapsing them would let
byte reinterpretation happen silently |
| 2026-10-10 | Date and time are combined only through
ComposeDateTime |
Delphi keeps the time of day positive for negative dates, so
Date + Time lands a day late at the mirrored time. Correct
for file timestamps, wrong in general and wrong silently |
| 2026-10-10 | TCriticalSection wraps
std::recursive_mutex |
Delphi’s is re-entrant; a plain std::mutex would
deadlock on core’s re-entrant paths rather than fail a test |
| 2026-10-10 | Compile-census numbers are ratcheted in CI | No core TU compiles cleanly yet, so a reintroduced missing type would otherwise present as a passing build |
| 2026-10-10 | TStrings is 0-based while UnicodeString is
1-based |
Both match their Delphi originals. Two bases in one codebase is a hazard, so each is pinned by a boundary test rather than left to memory |
| 2026-10-10 | TStrings references objects, never owns them |
Delphi does not free them and core owns them elsewhere; freeing here would be a double-free. Asserted by a test that outlives the list |
| 2026-10-10 | Chained subscripts on indexed properties are unsupported | clang reads Prop[i][j] as a two-argument getter call.
Core has 0 occurrences; check_properties.py fails if an
upstream change adds one |
| 2026-10-10 | Win32 A/W name macros are undone in
vcl_win32_undef.h |
<windows.h> renamed the definition of
ReplaceText to ReplaceTextW while the header
still declared ReplaceText. Both compiled; only the link
failed, and only because a test called it. A link-time guard now
references every colliding name |
| 2026-10-10 | ARRAYOFCONST pastes its parenthesised list onto a
variadic call |
C++Builder builds an open array of TVarRec, which needs
compound literals. ARRAYOFCONST((a, b)) becoming
MakeFormatArgs(a, b) is ordinary C++ |
| 2026-10-11 | XML is parsed for real, using the expat upstream vendors, rather than stubbed | A stub would silently import no FileZilla sessions. The mingw sysroot has no expat, so the vendored source is compiled for both targets, which also keeps them on one version |
| 2026-10-11 | Wide-character functions are renamed and the CRT names redirected by macro | They cannot be redeclared – <string> pulls in
<cwchar>, whose wcschr differs from ours
only in return type – and a macro also guarantees core’s calls reach
ours rather than glibc’s |
| 2026-10-11 | towlower/towupper fold ASCII only, on both
platforms |
The Windows CRT folds only ASCII in the default locale, confirmed by running the test against it. Folding Latin-1 on POSIX alone would make the platforms disagree, which is worse than being narrow |
| 2026-10-11 | try/__finally uses the same lambda
expansion on both targets |
SEH would work on mingw, but one code path on both platforms is worth more than relying on it, and it removes a way for the two to diverge in behaviour |
| 2026-10-11 | The try/__finally transform measures brace
depth on the pristine lines and applies every edit
afterwards |
LINSCP_END_FINALLY replaces a } with text
containing no brace, so editing in place miscounted the depth of any
enclosing block – and core nests these |
| 2026-10-11 | One bare return inside a guarded body is permitted, by
checked condition |
Returning from the lambda runs the cleanup through the guard and then falls off the end of the function, which is what Borland does – but only when the block ends the function and the return carries no value. Both are verified rather than assumed |
| 2026-10-11 | Every property form routes through a generated public wrapper | Borland’s __property grants access to a private
accessor from outside the class and ignores constness;
__declspec(property) does neither, because it expands to an
ordinary member call at the use site. The wrappers restore both
behaviours, and the getter casts its result to the declared type because
C++Builder is lax where the two differ in constness |
| 2026-10-11 | UnicodeString accepts numbers implicitly, yielding
their decimal text |
C++Builder does, and core depends on it. The hazard is real –
UnicodeString s = 0; gives "0" – but diverging
would mean editing core |
| 2026-10-11 | Globals that need dynamic initialisation are declared before the object that initialises them | Within a translation unit, dynamic initialisation runs in
declaration order. Putting the initialiser first had its constructor
assign to a UnicodeString that was not yet constructed,
which segfaulted rather than failing to compile |
| 2026-10-11 | TMask matching is case-insensitive |
Delphi’s is, and core uses it for file masks users type without regard to case |
| 2026-10-11 | Closure call sites are compiler-discovered, committed, then replayed | The sites cannot be inferred by regex: whether an argument is a
closure depends on the callee’s signature. clang names each one exactly,
so discovery records them to
port/patches/closure_sites.json and
transform.py replays that list, failing loudly if a
recorded site no longer holds the expected identifier |
| 2026-10-11 | A diagnostic inside a macro expansion is resolved to the macro definition | clang reports it at the expansion point, so
SessionInfo.cpp’s ADSTR macro alone produced
61 duplicate reports. Binding the definition once fixes every call site,
and cut the work from 118 sites to 62 |
| 2026-10-11 | TRegistry on POSIX reports every key absent rather than
empty |
There is no registry, and returning defaults for settings a user had actually set would look to them like their configuration had vanished. The INI backend, which core already supports, is the correct one there (P1-06d) |
| 2026-10-11 | INI section and key names match case-insensitively | Delphi’s do, and files written by WinSCP on Windows have inconsistent casing |
| 2026-10-11 | INI sections and keys keep their file order | Sorting them would churn the user’s configuration on every save and make diffs useless |
| 2026-10-11 | DynamicArray shares its buffer on copy, as Delphi’s
does |
Core declares TSafeHandleStream::Read as taking one
by value and fills it for the caller. A deep-copying version
would compile and silently return no data |
| 2026-10-11 | win32_on_posix.h exposes <string.h>,
<stdlib.h> and <stdio.h> |
<windows.h> does transitively, and core calls
strlen, strcmp and memmove
unqualified |
| 2026-10-10 | Resource strings: supply Win32 LoadString, not
a .res loader, and do not patch core |
core’s LoadStr is already implemented, in terms of
HInstance, LibModuleList and Win32
LoadString. Supplying those three means no
.res binary format to parse, no core edits, and a purely
additive change — the kind upstream could take rather than a fork of its
own code. The table is generated from upstream’s .rc files,
so the strings track the submodule automatically |
| 2026-10-10 | UnicodeString::c_str() has a non-const overload
returning a writable buffer |
C++Builder’s does, and core depends on it:
DoLoadStrFrom calls SetLength and then passes
c_str() to LoadString as the destination to
fill |
| 2026-10-10 | TList::Notify is virtual and fires before a removal,
after an addition |
Core overrides it. TObjectList frees owned objects from
inside it, so a wrong Action means a leak or a double free,
neither of which announces itself |
| 2026-10-10 | Extract reports lnExtracted, never
lnDeleted |
That is how Delphi lets a caller take ownership back without the list freeing the object |
| 2026-10-10 | TList::Sort is stable, where Delphi’s quicksort is
not |
Relying on an unstable order would be a latent caller bug either way, and stable is the safer guarantee to provide |
| 2026-10-10 | Derived streams re-expose the base’s legacy Seek with a
using-declaration |
Overriding one overload hides the other. Core calls both on derived streams, so without this the legacy origins would stop resolving |
| 2026-10-10 | Stream exceptions follow Delphi’s shape exactly | EFilerError, EFOpenError and
EFCreateError are siblings under EStreamError,
with EReadError/EWriteError beneath
EFilerError. Core catches at both levels |
| 2026-10-10 | port/platform headers refuse to compile on Windows, and
are POSIX-only on the include path |
Putting them on a Windows target shadowed the genuine mingw headers,
which presented as a 1,220 -> 783 “improvement”. The
#error makes that mistake loud |
| 2026-10-10 | port/compat is separate from
port/platform |
help.h is missing from upstream itself rather than
being a platform difference, so it is needed on every target |
| 2026-10-10 | The ratchet records whether a unit aborted | An aborted parse reports a floor. Treating that as a distinct state stops a new abort from reading as sudden progress |
| 2026-10-10 | Format keeps malformed input visible |
Delphi raises on a missing argument. Core routes user- and
server-supplied text through these into logs, so an unknown specifier is
echoed and a missing argument renders as <missing>
rather than throwing from a log path |
Until upstream_defines.py, every compile of core here
used none of the defines upstream builds it with – not
WINSCP, not UNICODE, not _DEBUG.
So the census measured a configuration upstream never builds. Two
effects:
_DEBUG alone exposed
ten closure comparisons in Queue.cpp, which had been
reported clean; they needed Borland closure equality, which did
not exist.port/compat/help.h stood in for a header that
WINSCP compiles out.It also surfaced a shim bug that only _DEBUG reaches:
the POSIX TEXT() was one-level, so
TEXT(__FILE__) pasted the token into
L__FILE__.
The corrected census is 159 / 303. Earlier figures are not comparable with it; the trend they showed was real, the absolute numbers were not.
Recorded because the mistake is instructive, not just to log it.
compile_census.py filtered clang diagnostics on
': error:', which does not match
': fatal error:'. A missing header emits only a
fatal error and aborts the parse, so a translation unit that
never got past its first include was reported as having
zero problems. The progression logged earlier for
Common.cpp (109 -> 83 -> 70 -> 30 -> 13 ->
5) was real for the portion that parsed, but it was a floor, not a
total: the parse was stopping at
#include <Classes.hpp>.
Two fixes. The census now counts fatal errors and prints
ABORTED EARLY with the cause, so an aborted unit can never
again look like a clean one. And port/shim now stubs the
unqualified legacy RTL header names (Classes.hpp,
SysUtils.hpp, Contnrs.hpp, …) alongside the
System.* spellings, since core uses both.
The honest figure for Common.cpp is 417 errors
across 29 missing types, and the ratchet now covers nine
translation units rather than one, precisely so a single unit cannot
give a falsely rosy picture again.
Recorded deliberately, so they are findable when something behaves oddly.
| Area | Divergence | Why |
|---|---|---|
UnicodeString::LowerCase / CompareIC,
AnsiLowerCase / AnsiUpperCase |
ASCII-only case folding | Delphi’s is locale-aware. Core uses these on protocol tokens and switch names. Must not be relied on for user-facing text |
FindFirst pattern matching |
Case-sensitive on Linux, case-insensitive on Windows | Each matches its host filesystem. A pattern that matches on Windows may not on Linux |
faHidden on Linux |
Set from a leading dot in the name | POSIX has no hidden attribute; the dot convention is what users expect |
TFormatSettings defaults |
ISO-8601 rather than system locale | Deterministic across machines. Anything user-facing should set them explicitly |
| Null arguments to the Win32 time functions | Rejected on POSIX; real Win32 dereferences and faults | The hardening is deliberate, so the null-argument assertions run only on POSIX |
| Winsock error codes on POSIX | Keep their Winsock numeric values rather than mapping to
errno |
Core and the FileZilla layer compare them by name and store them in their own state |
TRegistry on Linux |
Every key reports absent; nothing can be read or written | No registry exists. The INI backend is the correct one there, and failing visibly beats returning defaults for settings the user had set |
| INI share modes | Windows share modes are ignored on POSIX rather than approximated | Advisory locking would change behaviour rather than match it |
SetThreadPriority on POSIX |
Recorded and reported back by GetThreadPriority, but no
scheduling effect |
Core only lowers background queue threads; running them at normal priority is harmless |
ExitThread / EndThread on POSIX |
Unwinds to the entry point by exception, so destructors run; Win32 skips them | A catch (...) between the call and the entry point
would intercept it. Core calls it only as the last statement of a thread
entry point |
| Named events on POSIX | CreateEvent with a name fails with
ERROR_NOT_SUPPORTED |
Would need to be cross-process. Core never names one; refusing beats quietly creating a private event |
StripHotkey in East Asian locales |
The whole-(&X) suffix removal Delphi does under
SysLocale.FarEast is not reproduced |
Only the & is removed. Affects only CJK system
locales |
ParamStr(n) splitting on Windows |
Follows Delphi’s GetParamStr rules as documented in the
shim – quotes toggle and are dropped, no backslash escapes, empty
"" skipped – but has not been compared against a Delphi
binary |
Wine cannot check it: CommandLineToArgvW implements the
MSVC rules, which differ deliberately. Core itself only uses
ParamStr(0) |
TPath::IsDriveRooted on POSIX |
Always false | As in Delphi’s POSIX RTL. Core uses it only to locate Windows’ UAC VirtualStore |
| Calling a closure through a type it was cast to | Stops the program with a message | Borland reinterprets the (code, data) pair, so the call is undefined behaviour there. Core only casts to launder a closure and back, which round-trips exactly |
TFile::ReadAllText without a BOM |
Decodes UTF-8 on both platforms | Delphi uses TEncoding.Default, ANSI on Windows. Core
reads only authorized_keys this way and writes it back as
UTF-8, so ANSI would double-encode non-ASCII comments. ASCII files are
identical either way |
FileSetAttr on POSIX |
Only faReadOnly acts, on the write permission bits;
archive, hidden and system are ignored |
They have no POSIX counterpart. Read-only mirrors how
FileGetAttr reports it |
FindData.ftCreationTime on POSIX |
The modification time | POSIX has no creation time |
Variant |
Only one-dimensional integer variant arrays | Core’s only use. Anything wider raises EVariantError so
a new use is noticed |
ParseShortEngMonthName("January") |
Returns 0, “not found” | Upstream reads past ShortMonthNames into
LongMonthNames[0] and returns 13, an invalid month. Every
other input agrees |
TFormatSettings::Create(locale) |
Every locale yields the shim’s deterministic defaults, with English month and day names | Core asks by LCID 1033 for protocol parsing, which this matches; user-facing formatting should set fields explicitly |
TEncoding::Default |
UTF-8 on both platforms | Delphi’s is ANSI on Windows |
FileGetSymLinkTarget |
Resolves the whole chain to an absolute path | Delphi returns the immediate target. Core only reads the target’s attributes |
ExtractShortPathName on POSIX |
The name unchanged | No 8.3 names exist |
ExceptAddr / ExceptionErrorMessage |
No addresses are recorded: ExceptAddr is null and the
module is the executable |
The class name and message, the useful part, are exact |
FormatFloat |
Digits, grouping, decimals, literals and sections only; scientific
notation raises EConvertError |
Core’s one use is "#,##0" |
Element Text with mixed content |
Concatenates the element’s text children | Delphi raises when an element holds more than a single text node. Leaf elements, which is what core reads, agree |
RawByteString to another code page |
Bytes pass through | C++Builder’s RawByteString carries a run-time code page
and would transcode out of it; this one has none |
ISO8601ToDate without a zone designator |
Taken as UTC | Delphi’s handling of a zoneless time is not established here; every
value core parses (S3) carries Z |
TStrings::Text on POSIX |
CRLF, not LF | See the decisions table |
SuspendThread on POSIX |
Not declared | A running pthread cannot be suspended. A missing declaration fails
at compile time; a stub would fail silently.
CREATE_SUSPENDED + ResumeThread is
supported |
| # | Question | Blocks | Owner |
|---|---|---|---|
| Q-1 | P3 scope: faithful parity, or a deliberately narrower client? | P3 estimate (swings ~2 years) | — |
| Q-2 | Access to a C++Builder 11 licence + Windows host? | P0-04, P0-15, R1, R3 | — |
| Q-3 | Internal editor, or delegate to the system editor? | P3-05 | — |
| Q-4 | Ship 32-bit Windows, or x86-64 and arm64 only? | P0-10, packaging | — |
| Q-5 | Approach the maintainer early for feedback, or after P1 lands? | social strategy, not architecture | — |
| Q-6 | Far-NetBox licence: README says GPLv3, LICENSE.txt is
the GPLv2 text |
verbatim reuse of its shim (reference use is unaffected) | — |
| Q-7 | Build the fork-branch generator now, or when there is something worth proposing upstream? | nothing today; recommend deferring until P1 lands | — |
| — | — |
| Fact | Evidence | Date |
|---|---|---|
| Upstream WinSCP is built for 32-bit Windows only | PuTTYVS.vcxproj has only Win32
configurations, and PuTTY’s option defaults cast string addresses to
int, which only fits in 32 bits |
2026-10-11 |
clang accepts static __declspec(property(...))
syntactically but treats it as an ordinary static data member |
-fsyntax-only passes; linking fails with an undefined
reference to the “property” on both targets |
2026-10-11 |
clang 19 supports __declspec(property) on Linux under
-fms-extensions |
Local test: field r/o, field r/w, method+validating setter, read-modify-write, indexed — all pass | 2026-10-10 |
| GCC 14 rejects it outright | error: 'property' has not been declared |
2026-10-10 |
clang cross-emits x86-64 COFF for windows-gnu and
windows-msvc |
Local test, property emulation intact | 2026-10-10 |
| Qt6 present on this host; Qt6-for-mingw absent from Debian | apt-cache search returns nothing for mingw+qt |
2026-10-10 |
| Wine 10.0 installable from apt | apt-cache policy wine |
2026-10-10 |
Core has 591 __property decls; 0 use
default/nodefault/stored |
grep over source/core/*.h |
2026-10-10 |
Core has no __try/__except |
grep | 2026-10-10 |
ConsoleRunner.cpp has zero forms/
dependencies |
include analysis | 2026-10-10 |
| Stored-password crypto is not DPAPI | no DPAPI symbols in core | 2026-10-10 |
| WinSCP’s own compiler is already clang-based | #ifdef __clang__ in
source/core/Global.h:37 |
2026-10-10 |
| Far-NetBox tracks WinSCP 6.5.6, last commit 2026-07-24, ~16.3k-line VCL shim | repo inspection | 2026-10-10 |
Core has 613 __property declarations across 69 files
(.h and .cpp) |
transform.py --check |
2026-10-10 |
| 0 of 613 span multiple lines; 0 have comma-bearing or template types | AST-free scan of core/*.h |
2026-10-10 |
| All 613 transform to 9 macro forms with 0 unhandled | transform.py |
2026-10-10 |
| All 613 transformed declarations compile under clang | check_properties.py, exit 0 |
2026-10-10 |
| Transform is idempotent and line-count-preserving across all 69 files | transform.py, second pass is a no-op |
2026-10-10 |
| All 8 property shapes behave correctly at runtime (incl. validating setters, read-modify-write, indexed) | vcl_property.h self-test, assertions pass |
2026-10-10 |
| Cross-built Windows PE32+ binary passes the full property suite under Wine | clang --target=x86_64-w64-mingw32, exit 0 |
2026-10-10 |
Static Windows link needs lld plus explicit -L for
libwinpthread |
GNU ld fails; lld leaves only KERNEL32 + msvcrt | 2026-10-10 |
Dynamic Wine runs need two DLL dirs on
WINEPATH |
libwinpthread-1.dll lives apart from
libstdc++/libgcc |
2026-10-10 |
| Importing linscp history into a winscp fork merges with zero conflicts | git merge --allow-unrelated-histories; 10,602 commits,
both roots, all port commits preserved |
2026-10-10 |
| Applied in-tree, the core transform is a 613-line diff across 23 files | measured on the rehearsal fork | 2026-10-10 |
| After conversion, an upstream release touching a property line conflicts in 1 file, resolvable mechanically | simulated release; checkout --theirs + re-run
transform; new upstream property transformed automatically |
2026-10-10 |
| Transform is byte-exact outside property lines; CRLF fully preserved | 76,551 CRLF, 0 bare LF; Terminal.h 1003 = 1003 |
2026-10-10 |
| linscp tracks 0 WinSCP source files; only the submodule gitlink | git ls-files |
2026-10-10 |
| Both targets build and pass 4/4 tests; Windows runs under Wine via CTest | ctest on build/linux and
build/win |
2026-10-10 |
VCL surface the core needs: ~45 real types, dominated by
UnicodeString (6,248), TStrings (521),
Exception (438), TDateTime (250) |
census.py, resolved against real mingw/OpenSSL/stdlib
headers |
2026-10-10 |
Core’s Win32 headers (shlobj, psapi,
winioctl…) are satisfied free on the mingw target |
only VCL needs shimming for Windows | 2026-10-10 |
-fshort-wchar yields sizeof(wchar_t) == 2
on both linux-gnu and mingw32 |
static_assert compiled for both targets |
2026-10-10 |
char_traits<wchar_t> really does call
wmemcmp/wcslen/wmemchr;
char_traits<char16_t> does not |
/usr/include/c++/14/bits/char_traits.h:512,522,534 |
2026-10-10 |
UnicodeString API scoped from measured use:
IsEmpty 594, Length 444, c_str
247, SubString 184, Pos 86,
Delete 79 |
grep over the generated core | 2026-10-10 |
6/6 tests pass on Linux and on Windows under Wine, including
UnicodeString |
ctest both build trees |
2026-10-10 |
| A real core TU compiles against the shim with 70 errors from 12 distinct missing VCL types (was 109 / 24) | compile_census.py on core/Common.cpp,
mingw target |
2026-10-10 |
| On the mingw target every remaining diagnostic is a VCL gap, not a platform one | Win32 types all resolve via the real mingw headers | 2026-10-10 |
| 7/7 tests pass on both targets after the byte-string family | ctest |
2026-10-10 |
Common.cpp down to 30 errors / 5 distinct
missing types (from 109 / 24) |
compile_census.py |
2026-10-10 |
| 10/10 tests pass on Linux and on Windows under Wine | ctest both trees |
2026-10-10 |
| The ratchet detects a regression: baseline 25 against actual 30 fails | simulated baseline, exit 1 | 2026-10-10 |
TDateTime matches Delphi’s four documented anchors,
including -1.25 = 1899-12-29 06:00 |
test_datetime |
2026-10-10 |
Delphi’s DayOfWeek offset verified independently
against five known dates |
standalone cross-check, k=6 | 2026-10-10 |
Common.cpp: 109 -> 5 errors |
see the correction above | 2026-10-10 |
| Upstream pinned to 6.5.8, the latest stable release | git tag; 6.6.x is entirely RC/beta |
2026-10-10 |
| The transform handled the version change with no script edits: 624 declarations across 70 files, 0 unhandled | transform.py on 6.5.8, which differs from the old pin
by ~2,500 lines across 58 core files |
2026-10-10 |
| All 624 transformed declarations compile on 6.5.8 | check_properties.py, exit 0 |
2026-10-10 |
| Honest aggregate census: 2,409 errors across 9 core TUs, ratcheted | census_ratchet.py |
2026-10-10 |
| 12/12 tests pass on both targets after the version change | ctest both trees |
2026-10-10 |
All 44 __closure typedefs rewrite to
TClosure<Sig>; 16 single-line, 28 spanning lines, 0
unhandled |
transform.py |
2026-10-10 |
| Changed lines now fully accounted for: 624 property + 44 closure + 28 template-end = 696 | verify_transform.py |
2026-10-10 |
CLOSURE() binds the enclosing instance correctly on
both targets, including non-void returns and reference arguments |
test_closure on Linux and under Wine |
2026-10-10 |
Aggregate census 2,409 -> 1,924 across 9 TUs;
Terminal.cpp missing types 51 -> 20 |
census_ratchet.py |
2026-10-10 |
| 116 call sites pass a bare member-function name where a closure is expected | clang diagnostic count across all core TUs | 2026-10-10 |
| 13/13 tests pass on both targets | ctest |
2026-10-10 |
core/Option.cpp compiles clean on mingw: exit
0, 0 errors, 0 fatal |
direct clang run, verified rather than inferred from the census | 2026-10-10 |
| The same TU still fails on Linux with 10 Win32-type errors | the deferred P1-07 gap | 2026-10-10 |
| Aggregate census 1,924 -> 1,220 across 9 TUs | census_ratchet.py |
2026-10-10 |
Format handles width, alignment, precision and explicit
argument indices; unknown specifiers and missing arguments stay visible
instead of dropping text |
test_strutils |
2026-10-10 |
161 narrow string literals in core require
UnicodeString(const char *) |
grep over generated core | 2026-10-10 |
| 14/14 tests pass on both targets | ctest |
2026-10-10 |
core/Option.cpp compiles clean on Linux
and Windows: 0 errors each |
direct clang runs on both targets | 2026-10-10 |
| FILETIME conversions validated against the real Win32 API under Wine, using epoch anchors fixed by the format | test_win32_posix on both targets |
2026-10-10 |
Real Win32 FileTimeToSystemTime faults on a null
argument; the POSIX version rejects it |
Wine crash dump, cmpq $0, (%rcx) |
2026-10-10 |
| Honest totals with 0 units aborting: mingw 1,334, Linux 1,575 | census_ratchet.py, both targets |
2026-10-10 |
| 15/15 tests pass on both targets | ctest |
2026-10-10 |
| Census after streams: mingw 1,242, Linux 1,483, 0 aborting | census_ratchet.py |
2026-10-10 |
| 16/16 tests pass on both targets | ctest |
2026-10-10 |
Option.cpp and NamedObjs.cpp both
compile clean on both targets |
compile_census.py, 0 errors each |
2026-10-10 |
| Census after containers: mingw 1,070, Linux 1,299, 2/9 units clean | census_ratchet.py |
2026-10-10 |
| 17/17 tests pass on both targets | ctest |
2026-10-10 |
Resource strings resolved with no core changes: 608
strings generated from upstream’s .rc, all ids matched, 0
unknown, 0 duplicates |
gen_resources.py |
2026-10-10 |
| 18/18 tests pass on both targets | ctest |
2026-10-10 |
FileBuffer.cpp joins the clean set: 3/9 units
at 0 errors on both targets |
compile_census.py |
2026-10-11 |
| Census after storage and arrays: mingw 963, Linux 1,182, 0 aborting | census_ratchet.py |
2026-10-11 |
TRegistry round-trips against the real Windows registry
under Wine |
test_storage on the mingw target |
2026-10-11 |
| 20/20 tests pass on both targets | ctest |
2026-10-11 |
| Closure call sites: 62, not 118 — resolving macro-expansion diagnostics to their definitions collapsed the duplicates | bind_closures.py --discover |
2026-10-11 |
DynamicArray::Length is a read/write property, not a
method; 56 of the original 118 reports were this, not closures |
Buffer.Length = 10*1024 in core |
2026-10-11 |
| All 758 changed lines accounted for: 624 property + 44 closure typedef + 28 template end + 62 binding | verify_transform.py |
2026-10-11 |
| Census after closure binding: mingw 933, Linux 1,152 | census_ratchet.py |
2026-10-11 |
| 21/21 tests pass on both targets | ctest |
2026-10-11 |
| Census after the long tail: mingw 619, Linux 863 (from 933 / 1,152) | census_ratchet.py |
2026-10-11 |
Every __closure in core converted: 44 typedefs, 2
inline parameters, 62 bound sites |
transform.py, 0 remaining |
2026-10-11 |
| 22/22 tests pass on both targets | ctest |
2026-10-11 |
| Census after the property-access fix: mingw 342, Linux 586; 4/9 clean on mingw | census_ratchet.py |
2026-10-11 |
Borland’s __property reaches private
accessors; __declspec(property) does not |
TBookmark declares public properties over private
setters |
2026-10-11 |
__finally in core: 182 blocks, 0
__try, 0 __except; only 2 bodies contain a
return |
grep plus brace analysis | 2026-10-11 |
UnicodeString has implicit numeric constructors in
C++Builder |
EXT_EXCEPTION_METHODS calls
ExtException(E, Ident) with an int, and the
only viable overload takes a string |
2026-10-11 |
All 179 try/__finally
blocks transformed, 0 unhandled; the patch series is still empty |
transform.py |
2026-10-11 |
| Changed lines: 1,297, every one accounted for — 624 property, 46 closure, 28 template end, 62 binding, 537 try/finally (179 x 3) | verify_transform.py |
2026-10-11 |
| Census after try/finally: mingw 314, Linux 496; 4/9 clean on both targets | census_ratchet.py |
2026-10-11 |
| 23/23 tests pass on both targets | ctest |
2026-10-11 |
FileMasks.cpp clean on both targets; 5/9 units
clean on both |
compile_census.py |
2026-10-11 |
| Census: mingw 266, Linux 441 | census_ratchet.py |
2026-10-11 |
| Vendored expat compiles for both targets; the mingw sysroot has no expat | cmake/expat.cmake |
2026-10-11 |
The Windows CRT’s towlower folds only ASCII in the
default locale |
the same test run against the real CRT under Wine | 2026-10-11 |
| 24/24 tests pass on both targets | ctest |
2026-10-11 |
| 12/12 tests pass on Linux and on Windows under Wine | ctest both trees |
2026-10-10 |
Directory search validated against both backends: real
FindFirstFileW under Wine, and dirent +
fnmatch on Linux |
test_sysutils on both targets |
2026-10-10 |
__closure scope: 44 distinct closure types, 16
typedefs; call sites pass bare member-function names |
grep over generated core | 2026-10-10 |
| ID | Task | Status | Note |
|---|---|---|---|
| P0-01 | Repo layout | done | port/{shim,platform,tools,patches}, qt/,
cmake/ |
| P0-02 | Pin submodule to a release tag | done | 6.5.8, latest stable; 6.6.x is all RC/beta |
| P0-03 | Dual-target property macro header | done | port/shim/vcl_property.h; 9 forms, self-tested |
| P0-04 | Verify C++Builder accepts the macro | blocked | Q-2: needs licence + Windows |
| P0-05 | transform.py property rewriter |
done | 613/613, 0 unhandled |
| P0-06 | transform.py fastcall/ARRAYOFCONST |
done | __closure handled by P0-06b/c/d |
| P0-06b | __closure type + typedef transform |
done | 44 typedefs; CLOSURE() macro verified on both
targets |
| P0-06c | __closure call-site binding |
done | 62 sites; verified as a test |
| P0-06d | __closure inline parameter form |
done | 2 sites in SessionInfo |
| P0-07 | Transform idempotence tests | done | idempotent + line-count parity asserted |
| P0-08 | CMake skeleton | done | transform+verify wired as a build step; CTest on both targets |
| P0-09 | Minimal shim for core/Common.cpp |
wip | 224 errors; Option.cpp is the first TU at 0 |
| P0-10 | mingw-w64 sysroot + clang toolchain file | done | cmake/toolchain-mingw-w64.cmake; clang + lld + Wine
emulator |
| P0-11 | CI matrix Linux + Windows cross | todo | |
| P0-12 | Wine smoke tests in CI | wip | wired into CTest via CMAKE_CROSSCOMPILING_EMULATOR;
GitHub Actions pending |
| P0-13 | Golden-output harness | todo | highest leverage in P0 |
| P0-14 | Protocol server containers | todo | |
| P0-15 | Capture golden corpus from real WinSCP | blocked | Q-2: needs Windows host |
| P0-16 | ADR log | wip | doc/qt/adr/ started with ADR 0001 |
| P0-17 | Property compile-check harness | done | check_properties.py, 613 declarations, clang exit
0 |
| P0-18 | HTML render of plan docs | done | doc/qt/plan.html via build-html.sh |
| P0-19 | Publish repository, licence, root README | done | public at 99ecarvalho/linscp; work on
qt |
| P0-20 | Fork-branch generator | todo | deferred to P1-19 (Q-7); rehearsed manually in P0-22 |
| P0-21 | verify_transform.py upstream-diff audit |
done | asserts line parity, byte-exactness and 1 macro per changed line |
| P0-22 | Rehearse history import into a winscp fork | done | zero-conflict merge; 613-line in-tree diff; mechanical conflict resolution |
| P0-23 | check_docs.py TASKS/TRACKER consistency |
done | found 3 drifts on first run |
| P0-24 | VCL surface census | done | ~45 types; build/shim_spec.txt |
| P0-25 | ADR 0001 character width | done | accepted: -fshort-wchar +
std::u16string |
| P0-26 | check_wide_abi.py ADR enforcement |
done | shim_no_wide_abi test |
| P0-27 | compile_census.py |
done | classifies clang diagnostics into shim gaps |
| P0-29 | Legacy unqualified RTL header stubs | done | Classes.hpp etc.; absence was aborting most TUs |
| P0-30 | Win32 A/W macro collisions undone | done | link-time guard test |
| P0-31 | Ratchet both targets, track aborts | done | an abort is a distinct state, not a low number |
| P0-32 | port/compat for upstream gaps |
dropped | help.h was compensating for the missing
WINSCP define; withdrawn 2026-10-11 |
| P0-28 | census_ratchet.py |
done | both targets; aborts tracked separately |
| ID | Task | Status | Note |
|---|---|---|---|
| P1-01 | Shim: UnicodeString class |
done | 1-based API, UTF-16, 9 test groups incl. surrogate pairs |
| P1-01b | Shim: free string routines | done | Option.cpp reaches 0 errors |
| P1-01d | Shim:
TVarRec/Format/ARRAYOFCONST |
done | FORMAT 438 + FMTLOAD 252 call sites |
| P1-01e | Resource strings | done | 608 strings generated from upstream .rc; no core
changes |
| P1-01c | Shim: byte-string family + UTF-8 codec | done | malformed-input behaviour tested explicitly |
| P1-02 | Shim:
TObject/TStrings/TStringList |
done | 0-based indexing, case-insensitive default, CommaText round trip |
| P1-02b | Shim: TList/TObjectList/sets |
done | ownership and Notify semantics tested |
| P1-03 | Shim: TDateTime + date/time RTL |
done | documented anchors, negative composition,
FormatDateTime |
| P1-03b | Shim:
SysUtils/IOUtils/StrUtils
paths |
done | everything core calls from those units compiles for Windows; POSIX file calls are P1-07b |
| P1-04 | Shim: exceptions | done | 17 Delphi classes; base and sibling matching tested |
| P1-05 | Shim: TCriticalSection/SyncObjs |
done | recursive; thread exclusion tested |
| P1-05b | Shim: TThread/StartThread |
done | Win32 threads, events and waits on POSIX;
BeginThread/EndThread on both. Tested against
the real kernel under Wine. TThread itself dropped — dead
upstream |
| P1-08b | Shim: masks, paths, timespan, encoding, env | done | the census long tail |
| P1-08c | Shim: XML DOM over expat | done | real parsing; FileZilla-shaped fixtures |
| P1-07c | port/platform wide-char functions |
done | ASCII folding, matching the Windows CRT |
| P1-09b | try/__finally for POSIX |
done | 179 blocks, 0 unhandled; same expansion on both targets |
| P1-06 | Shim: streams | done | TStream/THandleStream/TFileStream/TMemoryStream |
| P1-06b | Shim: INI/registry storage | done | INI parses real-world files; registry real on Windows |
| P1-06c | Shim: DynamicArray + file API |
done | sharing semantics tested |
| P1-06d | Select INI backend on Linux | todo | frontend decision |
| P1-07 | port/platform Win32 subset |
done | types, FILETIME/SYSTEMTIME, errors, winsock names |
| P1-07b | port/platform Win32 file/handle functions |
todo | as the census asks |
| P1-08 | Socket-event emulation | todo | R6 |
| P1-09 | PuTTY unix backend re-import | todo | |
| P1-10 | PuTTY delta reconciliation | todo | |
| P1-11 | FileZilla MFC subset replacement | todo | |
| P1-12 | FileZilla epoll rewrite | todo | R2 — budget generously |
| P1-13 | System libs | wip | PuTTY and its MSVC-built crypto build for Windows from the submodule; neon, OpenSSL, libs3 next |
| P1-14 | Drop puttyvs |
done | the MSVC build is replaced by clang building the same files with the
same defines, from PuTTYVS.vcxproj |
| P1-15 | Console IPC → stdio | todo | |
| P1-16 | Headless Interface.h frontend |
todo | |
| P1-17 | First SFTP session on Linux | todo | long tail expected |
| P1-18 | Windows cross-build + Wine | todo | |
| P1-19 | Golden suite green, both platforms | todo | P1 gate |
| P1-20 | .NET assembly drives Linux CLI | todo | |
| P1-21 | #ifdef out Windows-only subsystems |
todo |
| ID | Task | Status | Note |
|---|---|---|---|
| P2-01 | Qt6 for mingw | todo | R4 |
| P2-02 | Qt app skeleton | todo | |
| P2-03 | Qt Interface.h implementation |
todo | |
| P2-04 | Site manager | todo | |
| P2-05 | Login/auth dialogs | todo | |
| P2-06 | Remote file panel | todo | |
| P2-07 | Transfer + queue UI | todo | |
| P2-08 | Local file panel | todo | |
| P2-09 | i18n pipeline | todo | do early |
| P2-10 | Packaging | todo | |
| P2-11 | P2 exit gate | todo |
| ID | Task | Status | Note |
|---|---|---|---|
| P3-01 | .dfm → .ui converter |
todo | |
| P3-02 | Commander dual-pane | todo | the main draw |
| P3-03 | Synchronization UI | todo | |
| P3-04 | Preferences | todo | XL — split first |
| P3-05 | Internal editor | todo | Q-3 |
| P3-06 | Remaining 48 dialogs, batched | todo | XL — split into P3-06a…f |
| P3-07 | Drag & drop | todo | |
| P3-08 | Shell integration | todo | |
| P3-09 | Accessibility | todo | |
| P3-10 | P3 exit gate | todo |
| ID | Task | Status | Note |
|---|---|---|---|
| P4-01 | Retire VCL frontend | todo | |
| P4-02 | Collapse dual-target #ifdefs |
todo | |
| P4-03 | Fold generated tree into source | todo | optional, one-way door |
| P4-04 | De-shimming evaluation | todo | recommendation: do not |
The multiplier is highly uneven across this project, and the uneven parts are what the estimate turns on.
| Work | Why |
|---|---|
transform.py (P0-05/06) |
Mechanical, 4 regular forms, immediately self-testable by re-running |
| VCL RTL shim (P1-01…06) | Well-specified APIs, a maintained reference to crib from (Far-NetBox
src/base/), and unit-testable in isolation. The single
largest chunk of P1 is also the best-suited |
win32-on-posix (P1-07) |
~40 functions with precise documented semantics |
| CMake / CI / toolchain files (P0-08…12) | High boilerplate, fast feedback |
PuTTY unix/ re-import (P1-09) |
Mostly reconciling two known trees |
.dfm → .ui + dialog port
(P3-01/04/06) |
.dfm is a declarative spec of layout, widgets,
captions and tab order. This is the biggest single AI win in the
project, and it sits in the most expensive phase |
| Work | Why |
|---|---|
Qt Interface.h implementation, file panels, queue UI
(P2-03…08) |
Real interaction logic and design judgment; AI drafts well, polish is human |
| Commander dual-pane semantics (P3-02) | Deep keyboard-driven interaction behaviour users will notice immediately |
| First successful link (P1-17) | AI is excellent per-fix, but the iteration count is high and each cycle is gated on a working build |
| Work | Why |
|---|---|
| FileZilla epoll rewrite (P1-12) | ~1,700 lines of subtle async state machine. Correctness is established by testing against real servers, not by reading code. Verification-bound |
| Protocol correctness (P0-15, P1-19) | The FTP server zoo, SFTP extension quirks, S3 and WebDAV edge cases. Wall-clock bound by test infrastructure and real-world behaviour |
| C++Builder / Windows-native tasks (P0-04, P0-15) | No local access; bound on a collaborator or licence |
| UX parity judgment | Deciding what “parity” means is not a code task |
| Phase | Human (mo) | + Opus 5 (mo) | Multiplier | Confidence |
|---|---|---|---|---|
| P0 Foundation | 2 – 3 | 0.5 – 1.0 | ~3–4× | High — scope is well understood and the keystone is already tested |
| P1 Headless core | 6 – 12 | 2.5 – 4.0 | ~2.4–3× | Medium — dominated by the shim (strong fit), dragged by P1-12 and P1-19 (weak fit) |
| P2 Qt shell | 6 – 9 | 2.0 – 3.0 | ~3× | Medium |
| P3 Qt parity | 18 – 36 | 6.0 – 12.0 | ~3× | Low — scope is undecided (Q-1) and this phase dominates the total |
| P4 Cleanup | 1 – 2 | 0.25 – 0.5 | ~4× | High |
| Total | 33 – 62 | 11 – 21 | ~3× |
One developer + Opus 5: roughly 11–21 months, against 2.8–5.2 years unassisted.
P3 parallelises well — dialogs are largely independent — and P2 moderately. P0 and P1-17 do not parallelise much, being serialised on a single build bring-up.
| Config | Total |
|---|---|
| 1 dev + Opus 5 | 11 – 21 months |
| 3 devs + Opus 5 | 6 – 11 months |
Unlike the rest of this document, this section is measured,
not estimated. Every commit on the qt branch so
far was produced by claude-opus-5, and the session
transcripts carry per-turn token usage. Figures below are for the branch
state at c801756 (2026-10-11): 22 commits, 16,960 lines
added, 24 shim tests green on both targets, 5 of 9 tracked core units
compiling clean on both.
| Category | Tokens |
|---|---|
| Base input | 2,160 |
| Cache writes (1h TTL) | 1,922,665 |
| Cache reads | 473,255,696 |
| Output (incl. reasoning) | 1,654,640 |
| Total | 476,835,161 |
Cache reads are 99.2% of all tokens. That is the signature of this kind of work: a long-lived session re-reading a large working context (a 400k-line C++ tree, the shim, the plan docs) on every turn. It dominates the bill, so the cache-read rate — not the output rate — is what the cost turns on.
List prices per million tokens, from platform.claude.com/docs/en/about-claude/pricing as of 2026-10-11.
| Opus 5 | Opus 5.5 | |
|---|---|---|
| Base input | $5.00 | $4.00 |
| Cache write, 5 min | $6.25 | $5.00 |
| Cache write, 1 hour | $10.00 | $8.00 |
| Cache read (hit/refresh) | $0.50 (0.1× input) | $0.20 (0.05× input) |
| Output | $25.00 | $20.00 |
| Batch input / output | $2.50 / $12.50 | $2.00 / $10.00 |
| Fast mode input / output | $10.00 / $50.00 | $8.00 / $40.00 |
Batch halves the base rates but is unusable here — the work is interactive and each step depends on the previous build result.
The same measured token mix, priced under both sheets:
| Line item | Opus 5 | Opus 5.5 |
|---|---|---|
| Base input | $0.01 | $0.01 |
| Cache writes | $19.23 | $15.38 |
| Cache reads | $236.63 | $94.65 |
| Output | $41.37 | $33.09 |
| Total | $297.23 | $143.13 |
| Share of bill that is cache reads | 80% | 66% |
| Per commit (22) | $13.51 | $6.51 |
| Per 1,000 lines landed | $17.53 | $8.44 |
Opus 5.5 is 52% cheaper on this workload, not the 20% the headline list price suggests. The reason is the cache-read multiplier: 0.05× base input instead of 0.1×, which on a session that is 99% cache reads is the only number that matters. Any workload shaped like this one — long sessions over a large fixed codebase — should expect the same disproportionate saving.
Caveat on reasoning effort: price per token does not vary with effort. Effort changes how many reasoning tokens are produced, not the rate they are billed at. So the Opus 5 column is a bill, but the Opus 5.5 column is this session’s token mix re-priced — not Opus 5.5 actually doing the work. If 5.5 reaches the same result in fewer tokens the real figure is lower; if it deliberates more, higher.
Progress is ~14% of the plan by month-weighted task completion (P0 26/35 and P1 18/36 against the per-phase Opus 5 budgets above). Scaling the measured spend:
| Scenario | Plan progress | Opus 5 | Opus 5.5 |
|---|---|---|---|
| Full parity, optimistic (11 mo) | 19.8% | $1,498 | $722 |
| Full parity, midpoint (15.9 mo) | 13.7% | $2,162 | $1,041 |
| Full parity, pessimistic (21 mo) | 10.4% | $2,860 | $1,377 |
| Narrow Qt client (Q-1), 8–14 mo | 15–27% | $1,090 – $1,907 | $525 – $918 |
Order of magnitude only. The extrapolation assumes cost per unit of
plan progress stays flat, and it will not: P3 generates Qt UI from
.dfm declarative specs, writing more and searching a huge
C++ tree less, so the cache-read share that dominates today should fall
as the project moves into the UI phases.
The figures above are API list prices. On a Claude subscription seat (Pro, Max, or a Team / seat-based Enterprise seat) none of it is billed per token: usage is included up to the plan’s rolling 5-hour and weekly limits. Spend beyond those limits is only possible if usage credits (formerly “extra usage”) are enabled — on Team and seat-based Enterprise that is an Owner / Primary Owner decision, with optional monthly spend caps per organisation, per seat tier and per member. With credits disabled, hitting the limit pauses work until it resets; it cannot generate a surprise invoice. See Max plan limits and extra usage for Team and seat-based Enterprise plans.
The practical consequence for planning this port: on a subscription seat the limit is wall-clock throughput, not money. That reinforces the conclusion below rather than changing it.
Code generation is not the bottleneck; human review and real-world verification throughput are.
This matters for planning:
The estimate is dominated by one undecided question.
| Variable | Effect |
|---|---|
| P3 scope (Q-1) | A deliberately narrower Qt client cuts P3 from 6–12 to ~3–5 months → total 8–14 months. This is the single largest lever in the plan |
| R1 fails (C++Builder rejects the macro) | P0 +0.5 mo, and the zero-diff upstream story weakens — higher ongoing merge cost, not a higher build cost |
| R2 worse than expected (FileZilla rewrite) | P1 +1–2 mo. Mitigation: ship SFTP/SCP/S3/WebDAV first and treat FTP as a later deliverable |
| No Windows host available | P0-04 and P0-15 stay blocked; the dual-target guarantee becomes unverified and Windows releases cannot be certified |