@tsplc/build 0.1.0 → 0.2.1

package/package.json

@@ -15,7 +15,7 @@
     "url": "git+https://github.com/livingforjesus/tsplc.git",
     "directory": "packages/build"
   },
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "exports": {
     ".": {
@@ -43,8 +43,8 @@
   },
   "dependencies": {
     "zod": "4.3.6",
-    "@tsplc/config": "0.1.0",
-    "@tsplc/typegen": "0.1.0"
+    "@tsplc/config": "0.2.1",
+    "@tsplc/typegen": "0.2.1"
   },
   "bin": {
     "tsplc-build": "./dist/cli.js"

package/python/build.py

@@ -77,12 +77,17 @@ def diagnostic(message, category):
 	return result
 
 
-def fail_on_errors(engine):
+def reported_errors(engine):
 	errors = []
 	for category in engine.system.get_message_categories():
 		errors.extend(diagnostic(message, category) for message in engine.system.get_message_objects(
 			category, engine.Severity.Error | engine.Severity.FatalError,
 		))
+	return errors
+
+
+def fail_on_errors(engine):
+	errors = reported_errors(engine)
 	if errors:
 		raise CompilerError(errors)
 

package/python/codesys_login.py

@@ -0,0 +1,100 @@
+"""A long-lived login to the downloaded application; executed by CODESYS's IronPython engine."""
+from __future__ import print_function
+
+from codesys_online import (connect_controller, controller_ids, controller_state, core_application,
+                            load_downloaded_reference, session_login)
+
+
+def open_login(engine, request):
+    """Log in to the controller's running application without changing it.
+
+    The project is a copy of the downloaded baseline, so the login never offers
+    a download: the controller and the compiler reference must both match it.
+    """
+    baseline = request['baseline']
+    project = engine.projects.open(request['project'], primary=True)
+    online_app = None
+    try:
+        application = project.active_application
+        if application is None or str(application.guid) != baseline['applicationGuid']:
+            raise RuntimeError('The saved project does not contain the downloaded application')
+        connect_controller(engine, application, request['online'])
+        online_app = engine.online.create_online_application(application)
+        core = core_application(online_app)
+        session_login(core)
+        try:
+            if controller_ids(core) != baseline['controllerIds']:
+                raise RuntimeError('The controller runs a different application than the last deployment')
+            if load_downloaded_reference(application) != baseline['controllerIds']:
+                raise RuntimeError('Downloaded compiler reference differs from the controller')
+        finally:
+            core.Logout()
+        # The core login, unlike the scripting wrapper's, never creates or downloads an application.
+        if not core.Login(True):
+            raise RuntimeError('Controller application disappeared before login')
+    except Exception:
+        if online_app is not None:
+            online_app.Dispose()
+        project.close()
+        raise
+    return {'project': project, 'online': online_app, 'core': core}
+
+
+def apply_prepared(online_app, prepared, operation):
+    try:
+        operation()
+    except Exception as error:
+        failed = getattr(error, 'failed_expressions', None)
+        if failed is None:
+            raise
+        raise RuntimeError('The controller rejected ' + ', '.join(str(expression) for expression in failed))
+    finally:
+        # An unapplied preparation would otherwise ride along with the next write or force.
+        for expression in prepared:
+            online_app.set_prepared_value(expression, None)
+
+
+def run_command(engine, login, command):
+    online_app = login['online']
+    name = command['command']
+    if name == 'read':
+        return {'values': {expression: online_app.read_value(expression) for expression in command['expressions']}}
+    if name in ('write', 'force'):
+        values = command['values']
+        if name == 'write':
+            # The controller rejects writing a forced variable with only a generic error.
+            forced = set(str(expression).lower() for expression in online_app.get_forced_expressions())
+            blocked = [expression for expression in values if expression.lower() in forced]
+            if blocked:
+                raise RuntimeError(', '.join(blocked) + ' is forced; unforce it before writing')
+        for expression, value in values.items():
+            online_app.set_prepared_value(expression, value)
+        apply_prepared(online_app, values.keys(),
+                       online_app.write_prepared_values if name == 'write' else online_app.force_prepared_values)
+    elif name == 'unforce':
+        expressions = command['expressions']
+        if expressions:
+            for expression in expressions:
+                online_app.set_unforce_value(expression, command['restore'])
+            # CODESYS applies prepared unforces with its force command.
+            apply_prepared(online_app, expressions, online_app.force_prepared_values)
+        else:
+            apply_prepared(online_app, [], online_app.unforce_all_values)
+    elif name == 'start':
+        online_app.start()
+    elif name == 'stop':
+        online_app.stop()
+    elif name == 'reset':
+        online_app.reset(getattr(engine.ResetOption, command['kind']))
+    elif name != 'state':
+        raise ValueError('Unknown login command: ' + name)
+    return {'state': controller_state(login['core']),
+            'forced': [str(expression) for expression in online_app.get_forced_expressions()]}
+
+
+def close_login(login):
+    try:
+        login['online'].logout()
+        login['online'].Dispose()
+    finally:
+        login['project'].close()

package/python/codesys_online.py

@@ -4,8 +4,9 @@ from __future__ import print_function
 import io
 import json
 import os
+import re
 import time
-from build import apply_controller, fail_on_errors, import_objects, unique_child
+from build import CompilerError, apply_controller, fail_on_errors, import_objects, reported_errors, unique_child
 from System import Activator, AppDomain, Array, Enum, Environment, Object
 from System.Net import Dns, IPAddress
 from System.Reflection import BindingFlags, TargetInvocationException
@@ -145,6 +146,47 @@ def reconcile(application, previous, current):
         remove_deleted(parent, [old], [fresh] if fresh else [])
 
 
+def fail_on_errors_after_transfer(engine, progress):
+    """Like fail_on_errors, once the controller runs the verified application.
+
+    Logging in to a Linux SL controller loads its device's visualization placeholders, which
+    nothing in a tsPLC project resolves. The application compiled without them, so the
+    engineering session reports them rather than failing a completed transfer.
+    """
+    errors, unresolved = [], []
+    for error in reported_errors(engine):
+        placeholder = re.match(r"Could not open library '(#[^']+)'.*could not be resolved", error['text'])
+        if placeholder:
+            unresolved.append(placeholder.group(1))
+        else:
+            errors.append(error)
+    if unresolved:
+        progress('Ignoring library placeholders the login loaded but nothing resolves: ' + ', '.join(unresolved))
+    if errors:
+        raise CompilerError(errors)
+
+
+def connect_controller(engine, application, settings):
+    """Route the application's controller through the configured gateway; returns it and its credentials."""
+    device = application.parent
+    while device is not None and not getattr(device, 'is_device', False):
+        device = device.parent
+    if device is None:
+        raise RuntimeError('Application has no controller device')
+    gateway_ip = str(Dns.GetHostAddresses(settings['gateway']['host'])[0])
+    device_ip = str(Dns.GetHostAddresses(settings['device']['host'])[0])
+    gateway = engine.online.gateways.add_new_gateway('codesys-build', {0: gateway_ip, 1: settings['gateway']['port']})
+    device.set_gateway_and_ip_address(gateway.guid, IPAddress.Parse(device_ip), settings['device']['port'])
+    credentials = settings.get('credentials')
+    if not credentials:
+        return device, None
+    username, password = (os.environ.get(credentials[key]) for key in ('usernameEnv', 'passwordEnv'))
+    if not username or not password:
+        raise RuntimeError('CODESYS online credential environment variables are required')
+    engine.online.set_specific_credentials(device, username, password)
+    return device, (username, password)
+
+
 def run_online(engine, request):
     progress_path = request.get('progress')
     def progress(stage):
@@ -163,27 +205,12 @@ def run_online(engine, request):
         progress('Project opened; configuring controller connection')
         if application is None:
             raise RuntimeError('Project has no active Application')
-        device = application.parent
-        while device is not None and not getattr(device, 'is_device', False):
-            device = device.parent
-        if device is None:
-            raise RuntimeError('Application has no controller device')
-        settings = request['online']
-        gateway_ip = str(Dns.GetHostAddresses(settings['gateway']['host'])[0])
-        device_ip = str(Dns.GetHostAddresses(settings['device']['host'])[0])
-        gateway = engine.online.gateways.add_new_gateway('codesys-build', {0: gateway_ip, 1: settings['gateway']['port']})
-        device.set_gateway_and_ip_address(gateway.guid, IPAddress.Parse(device_ip), settings['device']['port'])
-        credentials = settings.get('credentials')
-        if credentials:
-            username, password = (os.environ.get(credentials[key]) for key in ('usernameEnv', 'passwordEnv'))
-            if not username or not password:
-                raise RuntimeError('CODESYS online credential environment variables are required')
-            engine.online.set_specific_credentials(device, username, password)
+        device, credentials = connect_controller(engine, application, request['online'])
         online_device = engine.online.create_online_device(device)
         if request.get('initializeUser'):
             if request['operation'] != 'download' or not credentials:
                 raise RuntimeError('Initial controller user requires an explicit download and credentials')
-            online_device.set_credentials_for_initial_user(username, password)
+            online_device.set_credentials_for_initial_user(*credentials)
         progress('Controller connection configured')
         previous = request.get('baseline')
         if request['operation'] != 'download':
@@ -255,7 +282,7 @@ def run_online(engine, request):
             expected = controller_ids(core)
             if not application.is_uptodate:
                 if not application.is_online_change_possible:
-                    raise RuntimeError('CODESYS requires a full download for this source; online change was refused')
+                    raise RuntimeError('CODESYS cannot apply this source as an online change; use an explicit download')
                 progress('Generating online-change code')
                 generate_online_code(application)
                 fail_on_errors(engine)
@@ -275,7 +302,7 @@ def run_online(engine, request):
         session_login(core)
         if controller_ids(core) != expected:
             raise RuntimeError('Controller did not retain the downloaded code/data identity')
-        fail_on_errors(engine)
+        fail_on_errors_after_transfer(engine, progress)
         ids = controller_ids(core)
         state = controller_state(core)
         if state != 'run':

package/python/test_codesys_login.py

@@ -0,0 +1,120 @@
+import sys
+import unittest
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+# Only .NET imports are unavailable in CPython.
+with patch.dict(sys.modules, {
+    'System': SimpleNamespace(Activator=None, AppDomain=None, Array=None, Object=None, Enum=None,
+                              Environment=None),
+    'System.Net': SimpleNamespace(Dns=None, IPAddress=None),
+    'System.Reflection': SimpleNamespace(BindingFlags=None, TargetInvocationException=Exception),
+}):
+    import codesys_login
+
+
+class ValuesFailed(Exception):
+    def __init__(self, failed_expressions):
+        super().__init__('values failed')
+        self.failed_expressions = failed_expressions
+
+
+class LoginTests(unittest.TestCase):
+    def setUp(self):
+        self.ids = {'codeId': 'code', 'dataId': 'data'}
+        self.application = SimpleNamespace(guid='application-guid')
+        self.project = SimpleNamespace(active_application=self.application, close=Mock())
+        self.core = SimpleNamespace(Login=Mock(return_value=True), Logout=Mock())
+        self.prepared = {}
+        self.online = SimpleNamespace(
+            Dispose=Mock(), logout=Mock(), start=Mock(), stop=Mock(), reset=Mock(),
+            read_value=Mock(side_effect=lambda expression: 'TRUE'),
+            set_prepared_value=Mock(side_effect=self.prepare),
+            set_unforce_value=Mock(side_effect=lambda expression, restore: self.prepare(expression, '<unforce>')),
+            write_prepared_values=Mock(), force_prepared_values=Mock(), unforce_all_values=Mock(),
+            get_forced_expressions=Mock(return_value=['Line.enabled']),
+        )
+        self.engine = SimpleNamespace(
+            projects=SimpleNamespace(open=Mock(return_value=self.project)),
+            online=SimpleNamespace(create_online_application=Mock(return_value=self.online)),
+            ResetOption=SimpleNamespace(Warm='warm', Cold='cold'),
+        )
+        patcher = patch.multiple(
+            codesys_login,
+            connect_controller=Mock(),
+            core_application=Mock(return_value=self.core),
+            session_login=Mock(),
+            controller_ids=Mock(return_value=self.ids),
+            controller_state=Mock(return_value='run'),
+            load_downloaded_reference=Mock(return_value=self.ids),
+        )
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.request = {
+            'project': 'Application.project',
+            'online': {},
+            'baseline': {'applicationGuid': 'application-guid', 'controllerIds': self.ids},
+        }
+
+    def prepare(self, expression, value):
+        if value is None:
+            self.prepared.pop(expression, None)
+        else:
+            self.prepared[expression] = value
+
+    def test_open_logs_in_to_the_running_application_after_checking_its_identity(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        self.core.Logout.assert_called_once()
+        self.core.Login.assert_called_once_with(True)
+        self.assertIs(login['online'], self.online)
+
+    def test_open_refuses_a_controller_running_another_application(self):
+        codesys_login.controller_ids.return_value = {'codeId': 'other', 'dataId': 'data'}
+        with self.assertRaisesRegex(RuntimeError, 'different application'):
+            codesys_login.open_login(self.engine, self.request)
+        self.core.Login.assert_not_called()
+        self.online.Dispose.assert_called_once()
+        self.project.close.assert_called_once()
+
+    def test_force_applies_prepared_values_and_reports_forced_expressions(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        seen = {}
+        self.online.force_prepared_values.side_effect = lambda: seen.update(self.prepared)
+        result = codesys_login.run_command(
+            self.engine, login, {'command': 'force', 'values': {'Line.enabled': 'TRUE'}})
+        self.assertEqual(seen, {'Line.enabled': 'TRUE'})
+        self.assertEqual(self.prepared, {})
+        self.assertEqual(result, {'state': 'run', 'forced': ['Line.enabled']})
+
+    def test_rejected_write_names_the_expressions_and_clears_preparation(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        self.online.write_prepared_values.side_effect = ValuesFailed(['Line.speed'])
+        with self.assertRaisesRegex(RuntimeError, 'rejected Line.speed'):
+            codesys_login.run_command(
+                self.engine, login, {'command': 'write', 'values': {'Line.speed': '200'}})
+        self.assertEqual(self.prepared, {})
+
+    def test_writing_a_forced_expression_names_the_force(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        with self.assertRaisesRegex(RuntimeError, 'line.ENABLED is forced'):
+            codesys_login.run_command(
+                self.engine, login, {'command': 'write', 'values': {'line.ENABLED': 'TRUE'}})
+        self.online.write_prepared_values.assert_not_called()
+
+    def test_unforce_releases_named_expressions_or_everything(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        codesys_login.run_command(
+            self.engine, login, {'command': 'unforce', 'expressions': ['Line.enabled'], 'restore': True})
+        self.online.set_unforce_value.assert_called_once_with('Line.enabled', True)
+        self.online.force_prepared_values.assert_called_once()
+        codesys_login.run_command(self.engine, login, {'command': 'unforce', 'expressions': [], 'restore': False})
+        self.online.unforce_all_values.assert_called_once()
+
+    def test_reset_uses_the_named_reset_kind(self):
+        login = codesys_login.open_login(self.engine, self.request)
+        codesys_login.run_command(self.engine, login, {'command': 'reset', 'kind': 'Cold'})
+        self.online.reset.assert_called_once_with('cold')
+
+
+if __name__ == '__main__':
+    unittest.main()

package/python/test_codesys_online.py

@@ -1,4 +1,6 @@
+import os
 import sys
+import tempfile
 import unittest
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
@@ -151,6 +153,18 @@ class OnlineLifecycleTests(unittest.TestCase):
         self.core.CreateBootProject.assert_called_once()
         self.project.close.assert_called_once()
 
+    def test_full_download_reports_device_placeholders_a_login_cannot_resolve(self):
+        def report_unresolved_placeholder(core):
+            self.messages.append(SimpleNamespace(text="Could not open library '#System_VisuInputs'. "
+                                                 "(Reason: The placeholder library 'System_VisuInputs' could not be resolved.)"))
+        codesys_online.session_login.side_effect = report_unresolved_placeholder
+        with tempfile.TemporaryDirectory() as directory:
+            self.request['progress'] = os.path.join(directory, 'progress.log')
+            result = codesys_online.run_online(self.engine, self.request)
+            with open(self.request['progress']) as log:
+                self.assertIn('nothing resolves: #System_VisuInputs', log.read())
+        self.assertEqual(result['state'], 'run')
+
     def test_boot_failure_preserves_vendor_clr_stack_and_never_confirms_completion(self):
         stack = ('System.ArgumentException: The path is not of a legal form.\n'
                  '   at System.IO.Path.GetFullPath(String path)\n'

package/python/worker.py

@@ -58,6 +58,19 @@ def serve(engine, directory):
 				with io.open(os.path.join(root, "request.json"), encoding="utf-8") as source:
 					request = json.load(source)
 				write_json(os.path.join(root, "result.json"), run_online(engine, request))
+			elif command["action"] == "login":
+				from codesys_login import close_login, open_login, run_command
+				arguments = command["arguments"]
+				if arguments["command"] == "open":
+					if loaded.get("project") is not None:
+						loaded["project"].close()
+					loaded.clear()
+					loaded["login"] = open_login(engine, arguments)
+					response["result"] = run_command(engine, loaded["login"], {"command": "state"})
+				elif arguments["command"] == "close":
+					close_login(loaded.pop("login"))
+				else:
+					response["result"] = run_command(engine, loaded["login"], arguments)
 			elif command["action"] not in ("ping", "stop"):
 				raise ValueError("Unknown worker action")
 		except Exception as error:

package/src/controller-online.ts

@@ -1,11 +1,14 @@
 import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
 import { z } from "zod";
 import { controllerSchema, dockerImage, type ResolvedConfig } from "./config";
+import { controllerFailureFile } from "./diagnostics.ts";
 import { prepareContainerRun, runDocker } from "./docker-run.ts";
 
 const execute = promisify(execFile);
@@ -42,11 +45,8 @@ export type ControllerUpdateOptions = {
   read?: string[];
 };
 
-const controllerOperation = async (
-  config: ResolvedConfig,
-  operation: ControllerResult["operation"],
-  options: ControllerUpdateOptions,
-): Promise<ControllerResult> => {
+/** Checks the settings every engineering connection needs and names its builder image and target. */
+const controllerConnection = async (config: ResolvedConfig) => {
   if (!config.docker || !config.online) {
     throw new Error(
       "Docker image and online gateway/device configuration are required for controller operations",
@@ -70,23 +70,38 @@ const controllerOperation = async (
       { cause },
     );
   });
-  const imageId = imageIdSchema.parse(stdout.trim());
-  const templateHash = createHash("sha256")
-    .update(await readFile(config.template))
-    .digest("hex");
-  const operationId = randomUUID();
-  const target = {
-    network: config.online.network,
-    gateway: config.online.gateway,
-    device: config.online.device,
-    controller: config.controller,
+  return {
+    environmentNames,
+    imageId: imageIdSchema.parse(stdout.trim()),
+    templateHash: createHash("sha256")
+      .update(await readFile(config.template))
+      .digest("hex"),
+    target: {
+      network: config.online.network,
+      gateway: config.online.gateway,
+      device: config.online.device,
+      controller: config.controller,
+    },
   };
+};
+
+const controllerOperation = async (
+  config: ResolvedConfig,
+  operation: ControllerResult["operation"],
+  options: ControllerUpdateOptions,
+): Promise<ControllerResult> => {
+  const { environmentNames, imageId, templateHash, target } = await controllerConnection(config);
+  const operationId = randomUUID();
   const requestDirectory = await mkdtemp(resolve(tmpdir(), "codesys-controller-"));
   const diagnostics = resolve(config.outDir, ".codesys/controller");
+  const failure = resolve(config.outDir, controllerFailureFile);
   try {
     await mkdir(config.outDir, { recursive: true });
+    await rm(failure, { force: true });
     await runDocker(
       [
+        "run",
+        "--rm",
         ...(await prepareContainerRun(config, requestDirectory, {
           network: target.network,
           environment: environmentNames,
@@ -105,7 +120,12 @@ const controllerOperation = async (
       ],
       (status) =>
         `Docker controller operation failed (${status}). Inspect ${diagnostics} for diagnostics`,
-    );
+    ).catch(async (cause: unknown) => {
+      if (!existsSync(failure)) throw cause;
+      // A CODESYS failure arrives as a Python traceback, whose last line names it.
+      const reason = (await readFile(failure, "utf8")).trim().split("\n").at(-1);
+      throw new Error(`${reason}. Inspect ${diagnostics} for diagnostics`, { cause });
+    });
     const result = await readFile(resolve(diagnostics, "result.json"), "utf8")
       .then((content) => controllerResultSchema.parse(JSON.parse(content)))
       .catch((cause: unknown) => {
@@ -141,3 +161,137 @@ export const updateController = (
 /** Read the controller using the runner's saved compilation baseline. */
 export const inspectController = (config: ResolvedConfig, read?: string[]) =>
   controllerOperation(config, "inspect", { read });
+
+/**
+ * Ends every refusal that only a full download resolves, so callers can offer one. The Python
+ * online operations end theirs with the same words.
+ */
+export const explicitDownload = "use an explicit download";
+
+export const loginCommandSchema = z.discriminatedUnion("command", [
+  z.strictObject({ command: z.literal("state") }),
+  z.strictObject({
+    command: z.literal("read"),
+    expressions: z.array(z.string().nonempty()).nonempty(),
+  }),
+  z.strictObject({
+    command: z.enum(["write", "force"]),
+    values: z.record(z.string().nonempty(), z.string().nonempty()),
+  }),
+  // No expressions unforces everything; `restore` puts back the value from before forcing.
+  z.strictObject({
+    command: z.literal("unforce"),
+    expressions: z.array(z.string().nonempty()),
+    restore: z.boolean(),
+  }),
+  z.strictObject({ command: z.enum(["start", "stop"]) }),
+  z.strictObject({ command: z.literal("reset"), kind: z.enum(["Warm", "Cold"]) }),
+]);
+export type LoginCommand = z.infer<typeof loginCommandSchema>;
+export const loginResultSchema = z.union([
+  z.strictObject({ values: z.record(z.string(), z.string()) }),
+  z.strictObject({ state: z.string(), forced: z.array(z.string()) }),
+]);
+export type LoginResult = z.infer<typeof loginResultSchema>;
+const loginReplySchema = z.discriminatedUnion("ok", [
+  z.strictObject({ ok: z.literal(true), result: z.unknown() }),
+  z.strictObject({ ok: z.literal(false), error: z.string() }),
+]);
+
+/** The port a login container serves its commands on, published to the host's loopback only. */
+const loginPort = 4851;
+
+const docker = (args: string[], timeout: number) =>
+  execute("docker", args, { timeout }).then(({ stdout }) => stdout.trim());
+
+const isRunning = async (name: string, timeout: number) =>
+  (await docker(["container", "ls", "--quiet", "--filter", `name=^${name}$`], timeout)) !== "";
+
+/** A login held open in builder container `name`; it ends with `close` or when the container stops. */
+const attachLogin = async (name: string, timeout: number) => {
+  const published = await docker(["port", name, String(loginPort)], timeout);
+  const url = `http://${published.split("\n")[0]}`;
+  const call = async (init: RequestInit) => {
+    const reply = loginReplySchema.parse(await (await fetch(url, init)).json());
+    if (!reply.ok) throw new Error(reply.error);
+    return reply.result;
+  };
+  return {
+    name,
+    /** The relay answers only once CODESYS has logged in. */
+    ready: () =>
+      fetch(url)
+        .then((response) => response.ok)
+        .catch(() => false),
+    send: async (command: LoginCommand) =>
+      loginResultSchema.parse(
+        await call({
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(command),
+        }),
+      ),
+    /** Logs out and waits for the container to stop. */
+    close: async () => {
+      await call({ method: "DELETE" });
+      await docker(["wait", name], timeout);
+      await docker(["rm", name], timeout);
+    },
+  };
+};
+export type ControllerLogin = Awaited<ReturnType<typeof attachLogin>>;
+
+/** The login in container `name`, if one is running; it outlives the process that opened it. */
+export const findControllerLogin = async (name: string) =>
+  (await isRunning(name, 15_000)) ? attachLogin(name, 15_000) : undefined;
+
+/**
+ * Logs in to the running application from the saved download baseline, in a detached builder
+ * container named `name`. Commands then take seconds instead of a CODESYS start each.
+ */
+export const openControllerLogin = async (config: ResolvedConfig, name: string) => {
+  const { environmentNames, imageId, target } = await controllerConnection(config);
+  const timeout = config.timeouts.hostCommand;
+  // A login that failed to open leaves its stopped container for diagnostics until the next one.
+  await docker(["rm", "--force", name], timeout);
+  // The request is overwritten in place: a bind mount of a recreated directory can still show
+  // Docker Desktop's cached, empty view of the deleted one.
+  const requestDirectory = resolve(config.outDir, ".codesys/login-request");
+  await mkdir(requestDirectory, { recursive: true });
+  await docker(
+    [
+      "run",
+      "--detach",
+      "--name",
+      name,
+      "--publish",
+      `127.0.0.1::${loginPort}`,
+      ...(await prepareContainerRun(config, requestDirectory, {
+        network: target.network,
+        environment: environmentNames,
+        sources: false,
+      })),
+      imageId,
+      "login",
+      "--request",
+      "/input/config.json",
+      "--image-id",
+      imageId,
+      "--port",
+      String(loginPort),
+    ],
+    timeout,
+  );
+  const deadline = Date.now() + config.timeouts.startup + config.timeouts.build;
+  while (Date.now() < deadline) {
+    if (!(await isRunning(name, timeout))) {
+      const logs = await execute("docker", ["logs", "--tail", "40", name], { timeout });
+      throw new Error(`The controller login failed:\n${logs.stdout}${logs.stderr}`);
+    }
+    const login = await attachLogin(name, timeout);
+    if (await login.ready()) return login;
+    await delay(2000);
+  }
+  await docker(["rm", "--force", name], timeout);
+  throw new Error("The controller login did not open in time");
+};