Bubble Tea-style ink TUI shipped inside this fork. Three roles:
browser over mcp-mirror/, approve gate for set_pou_code, and selection
beacon (state file) so MCP tools can ground actions in what the user
is looking at.
Phased: v0.1 read-only browser+approve, v0.2 get_user_selection MCP
tool, v0.3 inline live values (gated on connect_to_device fix), v0.4
full online dashboard sketched only.
Decisions locked: bin name phobiCS-tui, approve via two file paths,
inline live values, v0.4 future-only. Open: approve-gate default
on/off.
Previously, '--mode persistent --no-auto-launch' silently downgraded the
reported executionMode to 'headless' until launch_codesys was called.
get_codesys_status would then mislead the user into thinking they were
in headless mode despite having configured persistent.
Now executionMode tracks the configured intent. The deferred-launch
state is communicated via 'State: stopped' instead. Tool calls before
launch_codesys still route through HeadlessExecutor as a best-effort
fallback.
WHY: an unlicensed CODESYS Control runtime drops out of demo mode every 2
hours. systemctl is-active reports "active" even after the binary has
died, so a TCP probe on the runtime port (default 11740) is the only
honest liveness signal. The new tool gives MCP a one-call path to bring
the runtime back without dropping into a terminal.
Implementation choices:
- ssh2 (npm) instead of spawning ssh/sshpass: sshpass is not on the
default Windows path, and the target Pi's sshd 10.x rejects pubkey
signatures from this client environment in practice. ssh2 handles
password auth + remote stdin + exit-code capture cross-platform.
- sudo -S with the password fed on remote stdin -- avoids a NOPASSWD
sudoers entry on the PLC.
- After issuing the restart, polls 'ss -tln | grep :<port>' once per
second until the listen port is up or livenessWaitSeconds expires.
This is what catches a half-dead runtime that systemctl reports as
fine.
Defaults match the only Pi we currently target (codesys-pi.local /
karstein / codesys123 / codesyscontrol / port 11740) but every field
is overridable.
Smoke-tested against codesys-pi.local: restart exit 0, port back up
after ~3s.
Before delegating to CODESYS for the actual open, inspect the
.project's projectinspectiondata.auxiliary (via src/inspect.ts -- pure
offline, ZIP+XML, no CODESYS) and compare its saved SP+patch against
the server's configured --codesys-profile.
Three outcomes:
- exact match -> proceed silently
- same SP, different patch -> proceed with a warning prefix in the
response (CODESYS will pop its patch-difference dialog)
- SP mismatch -> refuse without opening; suggest the user either pick
a different MCP server entry or run --print-config --for-project to
generate one for the project's required SP
If inspection itself fails (file missing, malformed .project, profile
unparseable), pre-flight falls through silently -- the existing CODESYS
open path then produces its original error.
Run --print-config with --for-project pointing at a .project file
and the snippet narrows to just the install(s) that can open it
(exact SP+patch match, or fallback to same-SP-different-patch with
a warning about the conversion dialog). No more eyeballing -- the
project's projectinspectiondata.auxiliary tells us which CODESYS
to route to, and --for-project just looks it up.
Mutually exclusive with --sp. Errors are explicit (no install
matches at all, or both flags supplied).
The default mirror root was hard-coded to <projectDir>/mcp-mirror/,
which collides when two .project files live in the same folder
(e.g. \files\...\Multi plc test\ProjectA.project +
ProjectB.project both default to the same mirror -- each
mirror_export call clobbers the other's output).
New resolution rule (preserves backward-compat -- existing setups
unaffected):
- If <projectDir>/mcp-mirror/ already exists, use it
- Else if exactly one .project sibling, use <projectDir>/mcp-mirror/
- Else (multiple .project) use <projectDir>/<basename>_mcp_mirror/
Implemented as src/mirror-paths.ts (TS helper, used by server.ts
maybeOpenMirrorInVscode and unit-testable) plus the same logic
inlined in the Python scripts that need it (mirror_export.py et al.,
no shared-import infra exists CODESYS-side).
New MCP tool + --ssh-version CLI flag. Bypasses the CODESYS IDE
entirely: SSH to a CODESYS Control Linux PLC, sudo strings the boot
application binary, extract the X.Y.Z.W literal of
_MCP_PROJECT_VERSION.sVersion. Filters out 3.5.x.y CODESYS runtime
versions automatically.
Solves the case where the .project file is locked by another CODESYS
instance, or no CODESYS install is reachable, but the PLC is. Read-
only on the PLC (just strings the boot binary).
Requires SSH key auth + passwordless sudo for /usr/bin/strings on
the PLC. Both error paths surface exact-instructions error messages
(PowerShell key install command, sudoers line) instead of opaque
failures.
Smoke-tested against codesys-pi (RPi running CODESYS Control 3.5.22)
with MCPTest2 v1.5.0.0 downloaded -- correctly extracts 1.5.0.0 and
filters out the 3.5.22.0 runtime version literal.
The 75cf74d scaffold added the helpers; this commit makes them
load-bearing by switching every modifying tool's formatToolResponse
call to formatModifyingResponse. Without --auto-mirror, behaviour is
unchanged. With it: mirror_export runs after each successful edit and
'code --add <mirror>' fires once per project to surface the diff in
VSCode's Source Control panel.
Two pieces of doc lag the source had silently outpaced:
1. The embedded --print-config sample showed the old caveat ('only ONE
can be active at a time') even though the runtime output (in
src/detect.ts) was already updated to the post-0.4.8 wording about
multi-install coexistence. Sync the README sample.
2. The 'Reliability fixes' bullet for the launcher still described the
pre-0.4.8 behaviour (refuses ANY CODESYS.exe). Updated to the
path-filtered version. Also drop the git_* project.save() bullet --
those tools were removed in 5be20a6.
The CODESYS Git plugin wrappers (git_init, git_status, git_commit,
git_remote_add, git_branch_set_upstream_to, git_push) operated on the
binary .project file via CODESYS's IDE-side Git plugin. Drawbacks:
- Required a CODESYS Professional Developer Edition subscription
(HasGitLicense gate). Anyone without PDE got a fail-fast error on
every call -- the tools were dead weight for most users.
- Operated on a separate dual-storage repo (the .project stayed put,
the git repo lived in a sibling directory). Diffs were unreadable
because they're binary serialisations, not source text.
- Couldn't run on UNC paths -- the plugin rejected them.
- Duplicated functionality release_project_version already provides
via the system git binary against the source-mirror tree (which IS
human-readable diff-able .st files).
Removing all 6 tools, all 6 .py templates, and the README section.
Tool count drops 37 -> 31. release_project_version remains the
recommended path for CODESYS-project version control: mirror_export
gives you readable diffs in mcp-mirror/, then standard git commits
+ tags + push, no PDE license required.
In-flight scaffolding for the --auto-mirror feature. Adds:
- ServerConfig.autoMirror flag, wired to --auto-mirror CLI option
- MirrorCtx (autoMirror, scriptManager, executor, workspaceDir,
openedInVscode set, vscodeCli path)
- findVscodeCli() probes PROGRAMFILES/LOCALAPPDATA/PROGRAMFILES(x86)
for the code.cmd shim
- maybeOpenMirrorInVscode() spawns 'code --add <mirror>' detached,
once per mirror dir per session
- maybeAutoMirror() runs mirror_export after a successful edit and
triggers the VSCode add
- formatModifyingResponse() wrapper around formatToolResponse +
maybeAutoMirror
No tool wrappers yet -- this is dead code until the modifying tools
are switched from formatToolResponse to formatModifyingResponse.
Doing that as a separate commit so the diff is reviewable.
Previous guard refused any CODESYS.exe in tasklist regardless of which
exe path the launcher was configured for. This broke the multi-install
setup the README documents (codesys-21 + codesys-22 entries are
supposed to coexist), and refused to launch any time the user had a
manual CODESYS window open from a different install.
Different CODESYS installs (e.g. SP21 + SP22) are designed to run in
parallel -- they're separate processes, separate IPC, separate file
locks. The only genuine conflict is two instances of the SAME exe
trying to attach to the SAME .project file (CODESYS pops 'project is
currently in use'). The same-exe case can't share IPC with us anyway
since we didn't spawn it.
Implementation:
- New findRunningCodesys() returns [{pid, exePath}] via PowerShell
Get-Process (tasklist doesn't expose ExecutablePath; WMIC is
deprecated on modern Windows).
- pathsEqual() exported helper: case-insensitive, slash-normalised,
trims trailing separators.
- Spawn-guard now filters by pathsEqual(p.exePath, config.codesysPath).
Refusal message names the conflicting exe and PIDs explicitly.
- shutdown_codesys orphan-killer also filters by exe path so we never
kill a CODESYS instance the user owns or that belongs to a different
MCP entry.
Tests:
- 6 new pathsEqual cases (identical / case-insensitive / slash-mix /
trailing-sep / different installs / different drives).
- detect test for the new --print-config caveat copy (no longer
warns 'only one at a time'; warns about same-.project conflict).
- 58/58 pass.
Also updates --print-config CAVEAT in src/detect.ts to reflect that
multiple entries can be active simultaneously, with the only hard rule
being don't open the same .project from two CODESYS instances.
Per https://docs.npmjs.com/cli/v11/using-npm/scripts, since npm@7 the
preinstall/install/postinstall scripts run in the background with stdout
AND stderr captured. The only way to surface them is the
`--foreground-scripts` opt-in flag (default false). Three failed
publish cycles (0.4.4, 0.4.5, 0.4.6) couldn't get around this -- the
limitation is by design, not a bug.
Removing src/postinstall.ts and the postinstall script entry from
package.json. The functionality (printing the .mcp.json snippet) is
still available -- it just runs on demand via:
codesys-mcp-sp21-plus --print-config
Updated the README Quick Start to a numbered 4-step flow:
1. npm install -g codesys-mcp-sp21-plus
2. codesys-mcp-sp21-plus --print-config
3. paste into project- or user-scoped .mcp.json
4. restart Claude Code
Plus a footnote explaining why no banner -- so a future maintainer
doesn't try to re-add postinstall and waste another publish cycle.
The previous heuristic checked whether INIT_CWD's package.json had our
name -- but that triggers a false positive when the user runs
`npm install -g codesys-mcp-sp21-plus@latest` from a clone of the
repo (very common -- they're testing the new release). My install
ran from ~/Codesys-MCP and the banner stayed silent.
Right discriminator: does the script's __dirname LIVE INSIDE
INIT_CWD? If yes, this is the dev case (installing yourself into
yourself). If no -- even when INIT_CWD is a clone of this repo --
the script lives in the global prefix and the user is doing a real
install. Print the banner.
Verified:
- INIT_CWD == repo, __dirname == /tmp/...: banner prints
- INIT_CWD == repo, __dirname == repo/dist: silent (dev case)
npm 11 stopped setting npm_config_global=true, so the previous guard
`process.env.npm_config_global !== 'true'` always evaluated true and
the banner was silently skipped on every install -- including the
`npm install -g` case it was supposed to handle.
Replace the global-detection (which is unreliable across npm versions)
with a positive dev-clone detector: only skip if INIT_CWD points at a
checkout of this very package (matched by package.json name). Also
keep the CI skip (CI=true / npm_config_ci=true).
Verified all three paths:
- Real install (no INIT_CWD or INIT_CWD outside repo): banner prints
- Dev clone (INIT_CWD = this repo): silent
- CI: silent
After printing the .mcp.json snippet, also print:
- Project-scoped path: <project>/.mcp.json (recommended, git-shareable)
- User-scoped path: %USERPROFILE%/.claude.json (resolved for the current user)
- 'claude mcp add' CLI alternative
- Restart-Claude-Code reminder
The path interpolation uses USERPROFILE so the printed path matches
the user's actual home, not a generic placeholder.
Runs after `npm install -g codesys-mcp-sp21-plus`. Detects every
CODESYS install on PATH and prints the ready-to-paste .mcp.json
block per install (same output as `--print-config`).
Guards:
- Skipped during local installs / dev clones (npm_config_global != true)
- Skipped in CI (CI=true or npm_config_ci=true)
- Wrapped in try/catch + 'node ... || true' so a banner failure never
blocks the install
- Non-Windows: prints a note and exits cleanly
- Zero CODESYS installs: prints a hint pointing at --print-config
Resolves the awkward 'now run these two commands to verify and get
your config' step from the README.
New flags:
- --print-config: scan installs and emit a JSON block per install with
derived server names (codesys-sp21-patch5, codesys-sp22-patch1, etc.)
- --sp <n>: filter to one SP family; collapses entry name to 'codesys'
when exactly one install matches
- --name <name>: override the entry name (only valid with --sp narrowing
to one)
Side effect: --detect now reuses the same detector and additionally
prints the derived profile name + suggested server entry name per
install, so even users sticking to manual config get the values
without guessing.
Refactored install discovery into src/detect.ts so both --detect and
--print-config share one implementation. New unit test fixture covers
version parsing, missing-exe, dedup, sort order, --sp filter behaviour,
--name override constraints, and verifies the emitted JSON parses back
once // comments are stripped.
The output also surfaces the multi-install caveat from launcher.ts:
the double-spawn guard refuses to start a second CODESYS.exe even on
a different exe path, so only one configured entry can be active at
a time.
Branch was deleted after main caught up. server.ts auto-generates
library.md and pou-dump.md headers in user projects, so the broken
URL was leaking into every consumer of those tools. Now points at
the repo root (main is the only branch).
- Lead with a clear "this is a fork" callout (upstream link, fork link, npm link, maintainer)
- New "What's new in this fork" section grouping all changes:
* Compatibility fixes (SP21+ watcher rewrite, KeyboardInterrupt cancel hardening)
* Upstream tool fixes (create_folder, compile JSON long, connect_to_device LoginMode + auto-login, ensure_project_open switch, set_pou_code wipe, add_library, list_project_libraries)
* New tools (mirror_export, bump_project_version, release_project_version, read_running_version_online, git_remote_add, git_branch_set_upstream_to, git_push)
* Reliability fixes (launcher refuses double-spawn, shutdown kills orphans, git_* persists via project.save)
- Promote npm install to the top of the install section; source install now follows
- MCP Tools tables now mark each tool as **NEW** or **FIXED** so readers can scan what came from this fork
The 'sp21-plus-migration-notes' branch name was shown in code-style
but not linked. Made it a hyperlink to
https://github.com/phobicdotno/Codesys-MCP-SP21-plus/tree/sp21-plus-migration-notes
so a reader landing on the README can click straight through to the
live source state without first navigating to the repo root.
Also added a sibling sentence pointing at the published npm registry
page (https://www.npmjs.com/package/codesys-mcp-sp21-plus) so the
About blurb now exposes the three canonical landing pages: upstream,
fork repo (+ branch), and npm.
Reader feedback: the install line 'npm install -g codesys-mcp-sp21-plus'
didn't make clear that the npm package IS this fork (rather than some
unrelated package or the upstream luke-harriman/Codesys-MCP).
Changes to the Installation section:
- Lead paragraph now states explicitly that the fork is published as
'codesys-mcp-sp21-plus' by phobic, and that this is this fork (not
upstream, not a Python package).
- 'npm install -g' command moved into a clear 'Install the fork from
npm' subsection with a bullet list explaining what -g does, where
the binary lands on PATH, and which deps come along for the ride.
- Added two verification commands (--version, --detect) so a first-time
user has an obvious next step after install.
- Added an upgrade command ('npm install -g codesys-mcp-sp21-plus@latest')
so the post-install workflow is fully documented.
- 'From source' subsection retitled 'Install the fork from source' for
parallel structure.
Package is live on the npm registry as of 2026-04-26 (version 0.4.0,
maintainer phobic). The bare-name install line that was previously
warned-against now actually works, so it's the leading install path
again. The git-clone workflow is demoted to a 'From source' subsection
for users who want to track sp21-plus-migration-notes directly,
contribute patches, or run a specific commit.
Verified live:
npm view codesys-mcp-sp21-plus version -> 0.4.0
User feedback: don't lead with npm registry concepts when the fork
isn't published. Replaced the three-option list (with the misleading
'not currently published' caveat) with a clean two-step git-clone
workflow:
1. git clone + npm install + npm run build (mandatory)
2. wire into .mcp.json via either:
A) command: 'node', args: ['<path>/dist/bin.js', ...]
(simplest -- no global state)
B) command: 'codesys-mcp-sp21-plus' after running 'npm link'
(only useful if you also want the bin on PATH for ad-hoc use)
Plus a short 'Updating' section that documents what to pull / rebuild
when the upstream branch advances.
Removed entirely:
- 'Option 1: npm install -g github:phobicdotno/...' (still works, but
drowns the simpler path)
- The 'Heads-up on npm install -g codesys-mcp-sp21-plus' caveat
paragraph (the new section doesn't mention the registry name at all,
so the warning has no premise)
Three explicit install paths replacing the misleading 'npm install -g codesys-mcp-sp21-plus' top-line (the fork is not published to npm; bare-name install would fail with 404):
1. npm install -g github:phobicdotno/Codesys-MCP-SP21-plus
-- installs directly from this repo, recommended for end users
2. git clone + npm install + npm run build + npm link
-- recommended for development; lets src/ edits take effect after a
build, and Python script edits hot-reload from dist/scripts/ without
one
3. git clone + npm install + npm run build, then node dist/bin.js
-- avoids touching global node_modules; full .mcp.json snippet shown
Also clarifies up-front that this is a Node/npm package, not a Python
package -- the .py files under src/scripts/ are CODESYS IronPython
templates bundled into the npm distribution, not a pypi project. There
is no pip install. Requirements section now lists the supported CODESYS
versions explicitly (SP19 / SP21 3.5.21.x / SP22 3.5.22.x) and notes
the PDE subscription gate on the git_* tools.
Project rename. The 'SP21+' identifier is more accurate than the
previous 'SP22+' label -- this fork specifically carries the SP21+
migration fixes (the upstream's system.execute_on_primary_thread()
removal and downstream API drift), and is forward-compat with later
SPs. The repo on GitHub has been renamed to
phobicdotno/Codesys-MCP-SP21-plus accordingly.
Substitutions (UTF-8 preserved this time -- prior PowerShell pass
mangled em-dashes via a Win-1252 round-trip):
- package.json: name codesys-mcp-sp22-plus -> codesys-mcp-sp21-plus,
bin entry, repository.url, homepage, description, author trailer
- README.md: title, banner, install + clone snippets, CLI invocations
- ARCHITECTURE.md: comparison-table column header + temp-dir prefix
- tests/TEST_OVERVIEW.md: title
- src/bin.ts: header comment + program().name()
- src/launcher.ts: SESSION_DIR_PREFIX
- src/types.ts: header comment
Compatibility phrase 'Works on SP19, SP21, and SP22+' and the technical
identifier 'SP22 Patch 1 fixes' (which name the actual CODESYS version)
were preserved -- those refer to CODESYS, not the project name.
README additions:
- Quick Start example switched from SP21 Patch 3 to SP22 Patch 1 to
match the more common modern install
- New 'Multiple CODESYS installations' subsection with worked
side-by-side example for SP21 (3.5.21.50) and SP22 (3.5.22.10) --
one named MCP server entry per install, called by name from Claude.
Documents the constraint that --codesys-path/--codesys-profile are
bound at server startup, that --detect lists installs, and that
config edits require a Claude Code restart
- Tool count corrected from 28 -> 37 in the Features bullets
- New Tools sections covering 10 previously-undocumented tools:
Version Anchor + Release Pipeline (bump_project_version,
release_project_version, read_running_version_online), Source
Mirror (mirror_export), and CODESYS Git PDE-gated (git_init,
git_status, git_commit, git_remote_add, git_branch_set_upstream_to,
git_push). Each row carries the actual operational gotchas
discovered during this session (UNC localRepoPath rejection,
push-without-upstream failure, optimizer stripping unreferenced
globals from the online symbol table, etc.)
- list_project_libraries + add_library row text updated to reflect
the post-fix behaviour (compiler-version capture; managed-overload
preference + resolution gate)
Local origin URL updated: phobicdotno/Codesys-MCP -> phobicdotno/Codesys-MCP-SP21-plus.
37/37 tests green.
Project identity rename. Concrete changes:
- package.json
- name: codesys-mcp-persistent -> codesys-mcp-sp22-plus (npm-safe;
'+' is not allowed in npm package names)
- description: prepended 'Codesys-MCP-SP22+' branding + brief
summary of the SP22+ fixes carried in this fork
- bin entry: codesys-mcp-persistent -> codesys-mcp-sp22-plus
- repository.url + homepage: now point at
github.com/phobicdotno/Codesys-MCP-SP22-plus (using -plus
spelling on the URL side; '+' would require URL-encoding)
- author: noted upstream + SP22+ fork attribution
- README.md: title + about-this-fork blurb + clone instructions
- tests/TEST_OVERVIEW.md: title
- ARCHITECTURE.md: comparison-table column header + temp-dir path
- src/bin.ts: file header + program().name()
- src/launcher.ts: SESSION_DIR_PREFIX (with note on backwards compat)
- src/types.ts: file header
Display name everywhere: 'Codesys-MCP-SP22+'.
npm package name: 'codesys-mcp-sp22-plus'.
Out of scope for this commit -- need user action:
- Local directory rename (C:/Users/karstein.kvistad/Codesys-MCP ->
...-SP22+) cannot be done while the persistent MCP is using dist/
from the current path; user can rename after shutting down VS Code.
- GitHub repo rename (phobicdotno/Codesys-MCP -> ...-SP22-plus or
...-SP22+) needs the github.com web UI; the package.json URLs
already point at the post-rename name so a 'git remote set-url
origin <new>' lines up after.
- MCP client config in .mcp.json or similar: the bin name changed
from 'codesys-mcp-persistent' to 'codesys-mcp-sp22-plus' -- update
any 'command' field that referenced the old name. (Local sessions
invoking node dist/bin.js directly are unaffected.)
37/37 tests still green after rename.
Three changes after deeper investigation against PLATEA Win V3:
1. The 'symbol' := 'read' attribute experiment didn't help. Reverted
bump_project_version's GVL template to plain VAR_GLOBAL +
qualified_only (matches what shipped originally, minus CONSTANT).
Comment updated to explain both why CONSTANT is wrong (compile-time
inlining) and why the symbol attribute alone wasn't enough (it
requires a Symbol Configuration object to do anything).
2. Real root cause for read_running_version_online's 'Invalid expression':
CODESYS strips unreferenced GVLs from the online symbol table at
compile time, regardless of attribute pragmas. The version anchor by
definition has no IEC code reading it, so the optimizer drops it.
GVL_Test.bRun reads fine despite no references because GVL_Test has
OTHER referenced variables; entire-GVL retention seems to be the
stripping unit, not per-variable.
Verified end-to-end: adding 'sVersionTag := _MCP_PROJECT_VERSION
.sVersion;' in PLC_PRG made the read return '1.4.1.0' on PLATEA.
3. Updated the read_running_version_online error message to surface
BOTH the (now-rare) CONSTANT case AND the (common) unreferenced-GVL
case, with the exact 2-line code snippet a user needs to paste into
their main program. The bump tool intentionally does NOT auto-inject
this -- modifying user code on every release was deemed too invasive.
Documented the requirement in TEST_OVERVIEW.md alongside the v5
sweep notes.
37/37 tests still green. v1.4.2.0 of MCPTest2 carries the working
PLC_PRG reference as the canonical demonstration.
Two related v5-sweep fixes for the online/runtime tool family:
1. Auto-login helper for headless mode
In headless mode each MCP call spawns a fresh CODESYS --noUI process,
so the login state established by connect_to_device dies before the
next call. Pre-fix, only connect_to_device and download_to_device did
their own login(); the other four (start_stop_application,
read_variable, write_variable, read_running_version_online) silently
failed in headless with 'Application not logged in.' (start/stop) or
'Invalid expression' (read/write). They worked in persistent mode
only because the login carried across calls.
Added ensure_logged_in(online_app, login_wait_seconds=30) to
ensure_online_connection.py. Idempotent: short-circuits via
online_app.is_logged_in (persistent mode is a no-op, no extra login
roundtrip). When not logged in, runs the same enum-probe + call-shape
probe + STABLE_STATES settle-wait pattern as connect_to_device.py.
Added to start_stop_application.py, read_variable.py,
write_variable.py, read_running_version_online.py.
2. _MCP_PROJECT_VERSION GVL emitted as plain VAR_GLOBAL, not CONSTANT
CODESYS inlines VAR_GLOBAL CONSTANT scalars at compile time and
strips them from the online symbol table. The whole point of
_MCP_PROJECT_VERSION.sVersion is to be readable live from the
running PLC, so CONSTANT was the wrong storage class.
read_running_version_online failed against EVERY project bumped via
the old template -- 'Invalid expression' on the runtime read.
Dropped CONSTANT from VERSION_GVL_DECLARATION_TEMPLATE in
bump_project_version.py. Existing projects auto-migrate on the next
bump because maintain_version_gvl()'s existing-GVL branch overwrites
textual_declaration with the (now non-CONSTANT) template. The string
is still effectively read-only at runtime -- only the bump tool
updates it.
read_running_version_online.py also got a more precise error message
that explicitly fingerprints the 'Invalid expression' failure mode
and points at the CONSTANT root cause. Useful for any user landing
on a project that pre-dates this fix.
Verified end-to-end against local CODESYS Control Win V3 (PLATEA, port
11740) on MCPTest2 v1.3.4.0:
- connect_to_device, get_application_state, download_to_device,
start_stop_application (both directions), read_variable
(PLC_PRG.watchdog1 = 225 ticking), write_variable (200 -> 204 in 4s
proves write took), disconnect_from_device: all 7 PASS.
- read_running_version_online failure reproduced (CONSTANT inlined),
fix landed -- next bump on MCPTest2 will validate.
37/37 unit/integration tests green. TEST_OVERVIEW.md updated with the
v5 device sweep, with the headless-mode deep-dive, and with the
broken-by-design notes on read_running_version_online.
Prior behaviour: lm.add_library(LIBRARY_NAME) was called with a string,
which always hits the placeholder overload of ScriptLibManObject.add_library
(see helpme-codesys.com "ScriptLibManObject" / local SP22 stub
ScriptLib/Stubs/scriptengine/ScriptLibManObject.pyi). If the named
placeholder is not registered in the IDE, the resulting reference fails
to resolve at load time and the next project open throws
Library Manager: Error: Could not open library 'X'.
(Reason: The placeholder library 'X' could not be resolved.)
after which script_engine.projects.primary returns None and the project
is effectively bricked until the binary is reverted. add_library reported
SUCCESS in this scenario.
Fix:
1. Pre-resolve LIBRARY_NAME via the IDE-level
library_manager.find_library(name) global. If found, pass the
resulting ManagedLib to lm.add_library(...) -- the V3.5.5.0 ManagedLib
overload which produces a managed reference instead of a placeholder.
2. After the add, walk lm.references to locate the new entry and verify
it resolved (managed -> always; placeholder -> non-empty
effective_resolution per ScriptPlaceholderReference in the stub).
3. If the reference did not resolve, call lm.remove_library(name) to back
out the bad reference and refuse to save the project, returning an
actionable error instead.
Also tightened the libman lookup to use the documented
has_library_manager / get_library_manager() container API
(ScriptLibManObjectContainer in the stub) instead of name-searching for
"Library Manager" as a tree node, matching what list_project_libraries.py
already does. The legacy name-search fallback is preserved for older SPs.
Regression test added in tests/integration/e2e.test.ts asserting the
rendered script template carries the resolution gate, the managed-overload
preference, the back-out call, and that primary_project.save() in the
add_library body lives downstream of the _is_resolved gate.
Followup: lm.remove_library(name) is documented for SP22 and is the
clean back-out path. On SPs that lack remove_library (none observed in
the 3.5.21+ docs but possible on truly old branches) the script reports
the constraint and exits non-zero rather than silently saving a bad
reference.
Three changes:
1. Fix the bench harness's set_pou_code case. The previous version
passed POU_PATH / DECLARATION_CODE / IMPLEMENTATION_CODE, but the
script template expects POU_FULL_PATH / DECLARATION_CONTENT /
IMPLEMENTATION_CONTENT. Plus the recently-added SET_DECLARATION /
SET_IMPLEMENTATION boolean flags from 35abc8c. With these
corrections, set_pou_code passes for the first time in the bench.
2. Add bench-results-v5.json from a fresh persistent-mode run on
MCPTest2 v1.3.4.0. All 10 cases PASS.
3. Update TEST_OVERVIEW.md with the v5 numbers alongside the v1
historical numbers. v5 is ~2x faster across the board than v1
(likely the cumulative effect of the ScriptManager cache removal +
SP22 Patch 1 IPC improvements). first-cold open_project is slower
than v1 (10.6 s vs 7.7 s) -- one-shot, noise probably; warm
already-open call dropped from 740 ms to 314 ms.
The v5 set_pou_code pass is the third end-to-end signal that the
omitted-decl wipe fix is good (after the e2e regression test and the
live PLC_PRG restoration earlier today).
