feat(library): let a library ship its C/C++ sources and choose its verify target

docs/CLI.md

@@ -10,6 +10,7 @@ a parallel implementation.
 | Build                         | `openplc-cli compile <project>`    |
 | Build & Upload                | `openplc-cli upload <project>`     |
 | Search / serial-port dropdown | `openplc-cli devices`              |
+| Library Manager               | `openplc-cli library …`            |
 | Debug                         | `openplc-cli debug open …`         |
 | Start / Stop                  | `openplc-cli debug start` / `stop` |
 | Variable poll, force dialog   | `openplc-cli debug read` / `force` |
@@ -289,6 +290,112 @@ OPENPLC_CREDENTIALS=user:pass    # or OPENPLC_USER + OPENPLC_PASSWORD
 
 Prefer the environment form in CI: a flag lands in shell history and job logs.
 
+## Libraries
+
+A library is a `.stlib` archive: blocks, their pin signatures, data types, and
+any C/C++ sources they ship. Building one, installing it and choosing which
+version a project compiles against are all scriptable.
+
+```sh
+openplc-cli library build <library-project> [--clean]   # project -> .stlib
+openplc-cli library install <file.stlib|.lib|.library|.zip>
+openplc-cli library uninstall <name>[@<version>] [--all]
+openplc-cli library info <name>[@<version>]
+openplc-cli library list
+openplc-cli library pin <project> <name>@<version>
+openplc-cli library unpin <project> <name>
+```
+
+A version is named with `@`, not a flag: `--version` is global and prints the
+CLI's own version.
+
+### A ZIP installs every library it holds
+
+`install` takes a `.zip` as well as a single file, and installs every `.stlib`,
+`.lib` and `.library` inside it at any depth — a vendor drop of several
+libraries, or one library built for several versions. Each goes through the
+same preparer it would have on its own, so a CODESYS file in a ZIP is imported
+exactly as picking it directly would. Anything else in the ZIP is ignored,
+including the `__MACOSX` forks Finder adds.
+
+One bad file does not stop the rest: the good ones install and the output names
+each one that did not, so a bundle of eight with one corrupt file installs
+seven.
+
+```sh
+$ openplc-cli library install vendor-libs.zip
+Installed 3 libraries from vendor-libs.zip
+  libtest-basic 0.1.0
+  libtest-basic 0.2.0
+  node-uio 0.0.1
+```
+
+A ZIP that will not open, or holds no library file at all, fails outright —
+that is the wrong file rather than a bad archive.
+
+### Versions live side by side
+
+Installing `0.2.0` does not replace `0.1.0`. Both stay, and each project picks
+one. `list` names the newest and, once anything has more than one, adds a column
+listing them all; the JSON always carries the full array.
+
+```sh
+$ openplc-cli library list
+Name           Version  Installed            Origin
+libtest-basic  0.2.0    0.2.0, 0.1.0         stlib
+```
+
+`uninstall` refuses to choose for you when several are installed — name one, or
+pass `--all`. Bundled libraries cannot be uninstalled; disable them per project
+instead.
+
+### Pinning
+
+The pin lives in the project's `project.json` and decides what the compiler
+resolves against, so changing it changes the generated code:
+
+```sh
+openplc-cli library pin ./my-project libtest-basic@0.1.0
+openplc-cli compile ./my-project          # COUNTER_FB.PV is INT
+
+openplc-cli library pin ./my-project libtest-basic@0.2.0
+openplc-cli compile ./my-project          # COUNTER_FB.PV is REAL
+```
+
+`pin` refuses a version that is not installed rather than writing a reference the
+compiler would quietly substitute later. It rewrites one field of `project.json`
+and leaves the rest of the file alone.
+
+Diagrams already on the canvas are **reported, not rewritten**:
+
+```
+Repinned libtest-basic 0.1.0 → 0.2.0.
+  warning: COUNTER_FB: the library added pin RESET (BOOL). 1 placed block in main does not draw it yet.
+  COUNTER_FB.PV: type INT → REAL — 1 block in main.
+```
+
+Growing a block needs the editor's own layout engine, so the CLI says what
+changed and the GUI applies it the next time the project is opened. A pin type
+that changed is honoured by the compiler immediately either way.
+
+### `info`
+
+`list` carries identity only. `info` opens the archive and prints what is in it —
+which is how you answer "did this pin change between versions" without unpacking
+anything:
+
+```sh
+$ openplc-cli library info libtest-basic@0.2.0
+libtest-basic 0.2.0
+  namespace: libtest_basic
+  installed: 0.2.0, 0.1.0
+
+Function blocks (1)
+  COUNTER_FB
+    in:    CU: BOOL, MODE: TEST_MODE, RESET: BOOL
+    out:   Q: BOOL, CV: INT
+```
+
 ## Debug sessions
 
 A debug session is long-lived; a test step is one process. So `debug open` starts
@@ -332,25 +439,25 @@ point of naming a timeout is that the default was wrong for this run.
 
 ### Flags, by command
 
-| Flag                   | Command                             | Meaning                                                                                             |
-| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `--session <id>`       | any `debug` subcommand              | which session, when several are open                                                                |
-| `--idle-timeout <ms>`  | `debug open`                        | idle budget; `0` disables (see above)                                                               |
-| `--force-new`          | `debug open`                        | start a session even if one is already open for this project and target                             |
-| `--upload-if-needed`   | `debug open`                        | upload first when the target's program does not match                                               |
-| `--var <name>`         | `read`, `force`, `unforce`           | the variable, when you would rather not pass it positionally                                        |
-| `--value <literal>`    | `force`                             | the value — `16#FF`, `TRUE`, `T#5s`, all as the GUI accepts them                                    |
-| `--filter <substring>` | `list-vars`                         | only variables whose path contains it                                                               |
-| `--interval <ms>`      | `watch`                             | sampling cadence; floor 20 ms                                                                       |
-| `--since <seq>`        | `poll`                              | only samples after this sequence number                                                             |
-| `--keep-forces`        | `close`                             | leave forced variables pinned                                                                       |
-| `--all`                | `close`                             | every session, not just one                                                                         |
-| `--keep-going`         | `exec`                              | run the remaining lines after one fails                                                             |
-| `--force`              | `create`                            | overwrite an existing destination                                                                   |
-| `--clean`              | `compile`, `upload`                 | discard the build directory first                                                                   |
-| `--user-data <dir>`    | any command                         | which editor state to use: settings, arduino-cli config, installed packages                         |
-| `-y`, `--yes`          | `upload`                            | skip the confirmation                                                                               |
-| `--create-user`        | `upload`, `debug open`              | permission to create the FIRST user on a fresh runtime v4, using the credentials you already passed |
+| Flag                   | Command                    | Meaning                                                                                             |
+| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
+| `--session <id>`       | any `debug` subcommand     | which session, when several are open                                                                |
+| `--idle-timeout <ms>`  | `debug open`               | idle budget; `0` disables (see above)                                                               |
+| `--force-new`          | `debug open`               | start a session even if one is already open for this project and target                             |
+| `--upload-if-needed`   | `debug open`               | upload first when the target's program does not match                                               |
+| `--var <name>`         | `read`, `force`, `unforce` | the variable, when you would rather not pass it positionally                                        |
+| `--value <literal>`    | `force`                    | the value — `16#FF`, `TRUE`, `T#5s`, all as the GUI accepts them                                    |
+| `--filter <substring>` | `list-vars`                | only variables whose path contains it                                                               |
+| `--interval <ms>`      | `watch`                    | sampling cadence; floor 20 ms                                                                       |
+| `--since <seq>`        | `poll`                     | only samples after this sequence number                                                             |
+| `--keep-forces`        | `close`                    | leave forced variables pinned                                                                       |
+| `--all`                | `close`                    | every session, not just one                                                                         |
+| `--keep-going`         | `exec`                     | run the remaining lines after one fails                                                             |
+| `--force`              | `create`                   | overwrite an existing destination                                                                   |
+| `--clean`              | `compile`, `upload`        | discard the build directory first                                                                   |
+| `--user-data <dir>`    | any command                | which editor state to use: settings, arduino-cli config, installed packages                         |
+| `-y`, `--yes`          | `upload`                   | skip the confirmation                                                                               |
+| `--create-user`        | `upload`, `debug open`     | permission to create the FIRST user on a fresh runtime v4, using the credentials you already passed |
 
 `watch` **records** into a buffer inside the session rather than streaming, so a
 transient that happens between two of your own commands is still there when you

package.json

@@ -18,6 +18,7 @@
     "build:renderer": "cross-env NODE_ENV=production TS_NODE_TRANSPILE_ONLY=true webpack --config ./configs/webpack/webpack.config.renderer.prod.ts",
     "lint": "cross-env NODE_ENV=development eslint ./src/**/*.{ts,tsx}",
     "lint:fix": "cross-env NODE_ENV=development eslint ./src/**/*.{ts,tsx} --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "format": "cross-env NODE_ENV=development prettier --write \"./src/**/*.{ts,tsx}\"",
     "postinstall": "ts-node scripts/download-binaries.ts && ts-node scripts/check-native-dep.js && electron-builder install-app-deps && npm run build:dll",
     "compile:matrix": "ts-node scripts/compile-matrix.ts",

scripts/link-modules.ts

@@ -5,6 +5,15 @@ import webpackPaths from '../configs/webpack/webpack.paths';
 const { srcNodeModulesPath } = webpackPaths;
 const { appNodeModulesPath } = webpackPaths;
 
+// `lstat` rather than `existsSync`, which follows the link: a symlink whose
+// target is gone reads as absent, the guard passes, and `symlinkSync` then
+// throws EEXIST on the link itself. Nothing in the repo recovers from that,
+// so every later `npm install` fails at postinstall.
+const srcLink = fs.lstatSync(srcNodeModulesPath, { throwIfNoEntry: false });
+if (srcLink?.isSymbolicLink() && !fs.existsSync(srcNodeModulesPath)) {
+  fs.unlinkSync(srcNodeModulesPath);
+}
+
 if (!fs.existsSync(srcNodeModulesPath) && fs.existsSync(appNodeModulesPath)) {
   fs.symlinkSync(appNodeModulesPath, srcNodeModulesPath, 'junction');
 }

src/App.tsx

@@ -73,6 +73,16 @@ hydrateLibraries()
 // install/uninstall/CDN change.  Subscriber lives outside React to
 // catch events fired before any component mounts.
 editorPorts.library.onLibrariesChanged(() => hydrateLibraries())
+// And again whenever a project opens. The pool is hydrated once at start-up,
+// so a library installed since by another process — `openplc-cli library
+// install`, or a second editor — is not in it, and a project that uses that
+// library opens reporting it missing; only a restart fixed it. Re-reading is
+// enough on its own: `setSystemLibraries` derives the enabled, missing and
+// outdated lists from the project's own refs each time it runs.
+openPLCStoreBase.subscribe(
+  (state) => state.project.meta.path,
+  () => hydrateLibraries(),
+)
 
 // A provider sign-in finishes in the system browser and lands in the main
 // process; this is how the account hook hears about it without waiting for

src/backend/editor/compiler/compiler-module.spec.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { cp } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 
 import { CompilerModule, mergeStandardFlags, standardFlagsForCore } from './compiler-module'
 
@@ -299,7 +299,18 @@ describe('CompilerModule', () => {
       return null
     }
 
-    const bridge = { loadEnabledArchives: () => ({ archives: [], missing: [] }) }
+    // The verification compile reaches `compileProgram`, whose bridge contract
+    // names the runtime-API pair.  Neither is called here — the build fails on
+    // the missing manifest long before — so a throwing stub documents that.
+    const bridge = {
+      loadEnabledArchives: () => ({ archives: [], missing: [] }),
+      makeRuntimeApiRequest: () => {
+        throw new Error('the library path never talks to a runtime')
+      },
+      makeRuntimeApiUpload: () => {
+        throw new Error('the library path never uploads')
+      },
+    } as unknown as Parameters<CompilerModule['compileLibrary']>[2]
 
     const wellFormed = {
       pous: [],
@@ -317,7 +328,7 @@ describe('CompilerModule', () => {
       const compilerModule = new CompilerModule()
       const { messages, channel } = makeChannel()
 
-      await compilerModule.compileLibrary(['/project', wellFormed, []], channel, bridge)
+      await compilerModule.compileLibrary(['/project', wellFormed, wellFormed, false, []], channel, bridge)
 
       const result = readBuildResult(messages)
       // It still fails — there is no `library.json` on disk at `/project` — but
@@ -337,6 +348,10 @@ describe('CompilerModule', () => {
       [['/project', { pous: [] }, []], 'no configuration'],
       [['/project', { pous: [], configuration: {} }, []], 'no resource'],
       [['/project', { pous: [], configuration: { resource: {} } }, []], 'no task or instance list'],
+      [['/project', wellFormed, null, false, []], 'no verification project data'],
+      // The verification payload is a separate argument and gets the same
+      // shape check as the build payload; an empty object used to pass.
+      [['/project', wellFormed, {}, false, []], 'verification project data has no POU list'],
     ])('rejects %p with a result and a closed port', async (args, expected) => {
       const compilerModule = new CompilerModule()
       const { messages, isClosed, channel } = makeChannel()