plccheck 2.9.0 → 2.11.0

package/README.md

@@ -15,7 +15,10 @@ npx plccheck check ./path/to/project
 - `plccheck serve` (LSP server over stdio)
 - `plccheck check <files-or-folders...>`
 - `plccheck emit --target <language> <file>`
+- `plccheck compile --out <exe> <file-or-folder>`
+- `plccheck run <file-or-folder> [-- runtime args...]`
 - `plccheck test [--filter <text>] [--events-json] [--coverage-json <file>] [--coverage-lcov <file>] <file-or-folder>`
+- `plccheck tia <list|export|import|repair-library-dependencies|online|offline|snapshot|compile|download|trust> ...`
 - `plccheck version`
 
 ## Testing and Coverage
@@ -39,3 +42,45 @@ npx plccheck test ./my-plc-project --coverage-json coverage.json --coverage-lcov
 ```
 
 Note: `--events-json` prints a stream of execution events to stdout, while `--coverage-json` writes a finalized coverage report to a file. Coverage artifacts include statement, function, and branch data where runtime data is available. For AI analysis, use the file artifact from `--coverage-json`.
+
+## Compile and Run PLC Runtime
+
+Build a runnable PLC runtime executable:
+
+```bash
+npx plccheck compile --out plc-run.exe ./my-plc-project
+```
+
+Build and run it immediately, forwarding runtime flags after `--`:
+
+```bash
+npx plccheck run ./my-plc-project -- --opcua-port 4849 --scan-period 24h
+```
+
+## TIA Portal Openness
+
+On Windows x64 machines with TIA Portal Openness V21 or newer, `plccheck tia` can attach to a running TIA project or open an explicit `.ap21`/`.zap21` path.
+
+```bash
+npx plccheck tia trust --json
+npx plccheck tia export --project Demo.ap21 --out exported --plc PLC_1 --delete-stale
+npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks/Main.scl" --create
+npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks/Main.scl" --overwrite-remote-changes
+npx plccheck tia import --project Demo.ap21 --root exported --skip-library-instances "exported/PLC_1"
+npx plccheck tia import --project Demo.ap21 --root exported "exported/PLC_1/Program blocks"
+npx plccheck tia repair-library-dependencies --project Demo.ap21 --plc PLC_1 --owner CA
+npx plccheck tia compile --project Demo.ap21 --plc PLC_1 --json
+npx plccheck tia online --project Demo.ap21 --plc PLC_1
+npx plccheck tia online --project Demo.ap21 --plc PLC_1 --online-auth-type ProjectUser --online-user engineer --online-password-env TIA_PROJECT_PASSWORD
+npx plccheck tia offline --project Demo.ap21 --plc PLC_1
+npx plccheck tia snapshot --project Demo.ap21 --plc PLC_1 --json
+npx plccheck tia download --project Demo.ap21 --plc PLC_1 --json
+```
+
+`export` writes PLC roots with `.plc.json` files and the TIA folder structure. `import` accepts one or more source files or folders, expands folders recursively, and needs `--create` before creating missing TIA folders or blocks. Supported direct import sources are `.scl`, `.s7dcl`, `.db`, `.udt`, `.xml`, `.awl`, `.lad`, and `.fbd`; pass the owning source file instead of `.s7res` resource sidecars or `.meta.json` metadata sidecars. By default, import skips unchanged local files, skips local files whose TIA object changed while the local source stayed unchanged, and rejects files changed both locally and in TIA since the last metadata refresh. Pass `--overwrite` to import when both sides changed, or `--overwrite-remote-changes` to import when only the TIA object changed. Import refuses to overwrite an existing project-library type instance or one of its project-library dependencies by default; pass `--skip-library-instances` to leave those library-owned targets unchanged and continue importing the rest, or pass `--allow-library-instance-overwrite` only for an intentional mutation run. `repair-library-dependencies` is the safe repair path for that failure class: it recreates the named library instance's project-local dependency objects from the project library. `snapshot` uses TIA's online DB snapshot before moving retained values to start values, skipping safety DBs and DBs without retained members. `download` compiles first, uses the project-configured target, reports the selected target in JSON, and falls back to software-only changes when Siemens Openness rejects a full load because of fail-safe data.
+
+If `tia list --json` shows `projectPath` but project commands report that TIA Openness did not expose the project, close that TIA Portal instance and rerun a verification export with `npx plccheck tia export --project <path> --out <dir>` to surface TIA's native open error. This often means the machine is missing a TIA product or add-on required by the project.
+
+Device actions automatically accept non-secret TLS and online-authentication modes. If the PLC requires a project/global/password user, pass `--online-auth-type`, `--online-user` where applicable, and `--online-password-env <env>` so the password is read from an environment variable. Without flags, the bridge also reads `PLCCHECK_TIA_ONLINE_USER_TYPE` or `PLCCHECK_TIA_ONLINE_AUTH_TYPE`, `PLCCHECK_TIA_ONLINE_USER`, and `PLCCHECK_TIA_ONLINE_PASSWORD`.
+
+Use `tia trust --install` to install the Siemens Openness AllowList entry for the packaged bridge after reviewing the `tia trust --json` output. Installation writes HKLM and ensures the current Windows user is a member of the local `Siemens TIA Openness` group, so it may require Windows administrator approval through UAC. If the UAC relaunch path is blocked, run the same command from an already elevated shell.

package/bin/plccheck.js

@@ -10,10 +10,7 @@ const os = require('node:os');
 const path = require('node:path');
 const zlib = require('node:zlib');
 
-function platformPackageName() {
-  const platform = process.platform;
-  const arch = process.arch;
-
+function platformPackageName(platform = process.platform, arch = process.arch) {
   if (platform === 'win32' && arch === 'x64') return '@danielv123/plccheck-win-x64';
   if (platform === 'win32' && arch === 'arm64') return '@danielv123/plccheck-win-arm64';
 
@@ -52,13 +49,16 @@ const commandValueFlags = {
   check: ['--jobs', '-jobs'],
   emit: ['--target', '-target'],
   transpile: ['--from', '-from', '--to', '-to'],
-  'go-gen': ['--out', '-out', '--module', '-module', '--entry-ob', '-entry-ob'],
+  generate: ['--out', '-out', '--module', '-module', '--entry-ob', '-entry-ob'],
+  compile: ['--out', '-out', '--workdir', '-workdir', '--module', '-module', '--entry-ob', '-entry-ob'],
+  run: ['--out', '-out', '--workdir', '-workdir', '--module', '-module', '--entry-ob', '-entry-ob'],
   test: testValueFlags,
 };
 
 const pathValueFlags = [
   ...coverageValueFlags,
   '--out', '-out',
+  '--workdir', '-workdir',
 ];
 
 function cacheRoot() {
@@ -215,6 +215,27 @@ function readOptionalDepVersion(pkgName) {
   }
 }
 
+function windowsBridgeArtifactsPresent(binDir) {
+  return fs.existsSync(path.join(binDir, 'tia-openness-bridge.exe'))
+    && fs.existsSync(path.join(binDir, 'tia-openness-bridge.exe.config'));
+}
+
+function platformRequiresWindowsBridge(platform = process.platform, arch = process.arch) {
+  return platform === 'win32' && arch === 'x64';
+}
+
+function requireWindowsBridgeArtifacts(binDir, platform = process.platform, arch = process.arch) {
+  if (!platformRequiresWindowsBridge(platform, arch) || windowsBridgeArtifactsPresent(binDir)) {
+    return;
+  }
+  throw new Error(`platform package is missing required TIA Openness bridge artifacts in ${binDir}`);
+}
+
+function validateResolvedBinaryPath(binaryPath, platform = process.platform, arch = process.arch) {
+  requireWindowsBridgeArtifacts(path.dirname(binaryPath), platform, arch);
+  return binaryPath;
+}
+
 function isRepoDevelopmentMode(rootDir = path.join(__dirname, '..', '..', '..')) {
   const repoRoot = path.resolve(rootDir);
   const localGoMod = path.join(repoRoot, 'go_lsp', 'go.mod');
@@ -235,7 +256,7 @@ async function resolveBinaryPath() {
   if (isRepoDevelopmentMode()) return 'go';
 
   try {
-    return require(pkg);
+    return validateResolvedBinaryPath(require(pkg));
   } catch (err) {
     if (err && err.code !== 'MODULE_NOT_FOUND') throw err;
   }
@@ -248,7 +269,9 @@ async function resolveBinaryPath() {
   const binaryName = process.platform === 'win32' ? 'plccheck.exe' : 'plccheck';
   const binDir = path.join(cacheRoot(), 'bin', version, `${process.platform}-${process.arch}`);
   const binPath = path.join(binDir, binaryName);
-  if (fs.existsSync(binPath)) return binPath;
+  if (fs.existsSync(binPath) && (!platformRequiresWindowsBridge() || windowsBridgeArtifactsPresent(binDir))) {
+    return binPath;
+  }
 
   const metaUrl = `https://registry.npmjs.org/${registryPackagePath(pkg)}`;
   const meta = await httpsGetJson(metaUrl);
@@ -266,6 +289,19 @@ async function resolveBinaryPath() {
   verifyIntegrity(tgzPath, v.dist.integrity, v.dist.shasum);
 
   extractFileFromTgz(tgzPath, `package/${binaryName}`, binPath);
+  if (process.platform === 'win32') {
+    try {
+      extractFileFromTgz(tgzPath, 'package/tia-openness-bridge.exe', path.join(binDir, 'tia-openness-bridge.exe'));
+    } catch {
+      // Older platform packages do not include the optional TIA bridge.
+    }
+    try {
+      extractFileFromTgz(tgzPath, 'package/tia-openness-bridge.exe.config', path.join(binDir, 'tia-openness-bridge.exe.config'));
+    } catch {
+      // Older platform packages do not include the optional TIA bridge config.
+    }
+  }
+  requireWindowsBridgeArtifacts(binDir);
   if (process.platform !== 'win32') {
     await fsp.chmod(binPath, 0o755);
   }
@@ -318,9 +354,15 @@ function resolveGoRunPaths(args, cwd) {
   if (nextArgs.length === 0) {
     return nextArgs;
   }
+  if (nextArgs[0] === 'tia') {
+    return resolveTiaGoRunPaths(nextArgs, cwd);
+  }
   const valueFlags = commandValueFlags[nextArgs[0]] || [];
   for (let i = 1; i < nextArgs.length; i++) {
     const arg = nextArgs[i];
+    if (nextArgs[0] === 'run' && arg === '--') {
+      break;
+    }
     if (arg.startsWith('-')) {
       const baseFlag = arg.split('=')[0];
       if (arg.includes('=')) {
@@ -345,6 +387,80 @@ function resolveGoRunPaths(args, cwd) {
   return nextArgs;
 }
 
+function looksLikeTiaProjectPath(value) {
+  if (!value) {
+    return false;
+  }
+  if (path.isAbsolute(value) || value.includes('/') || value.includes('\\')) {
+    return true;
+  }
+  const extension = path.extname(value).toLowerCase();
+  return extension.startsWith('.ap') || extension.startsWith('.zap');
+}
+
+function resolveTiaPathFlagValue(baseFlag, value, cwd) {
+  if (!value || path.isAbsolute(value)) {
+    return value;
+  }
+  if ((baseFlag === '--project' || baseFlag === '-project') && !looksLikeTiaProjectPath(value)) {
+    return value;
+  }
+  return path.resolve(cwd, value);
+}
+
+function resolveTiaGoRunPaths(args, cwd) {
+  const nextArgs = args.slice();
+  const valueFlags = [
+    '--project', '-project',
+    '--plc', '-plc',
+    '--out', '-out',
+    '--root', '-root',
+    '--bridge', '-bridge',
+    '--owner', '-owner',
+    '--online-auth-type', '-online-auth-type',
+    '--online-user', '-online-user',
+    '--online-password-env', '-online-password-env',
+  ];
+  const pathFlags = [
+    '--project', '-project',
+    '--out', '-out',
+    '--root', '-root',
+    '--bridge', '-bridge',
+  ];
+  const action = nextArgs[1] || '';
+  let hasRoot = false;
+  for (let i = 2; i < nextArgs.length; i++) {
+    const arg = nextArgs[i];
+    if (arg.startsWith('-')) {
+      const baseFlag = arg.split('=')[0];
+      if (baseFlag === '--root' || baseFlag === '-root') {
+        hasRoot = true;
+      }
+      if (arg.includes('=')) {
+        const value = arg.slice(arg.indexOf('=') + 1);
+        if (value && pathFlags.includes(baseFlag)) {
+          nextArgs[i] = `${baseFlag}=${resolveTiaPathFlagValue(baseFlag, value, cwd)}`;
+        }
+        continue;
+      }
+      if (valueFlags.includes(baseFlag) && i + 1 < nextArgs.length) {
+        if (pathFlags.includes(baseFlag) && !nextArgs[i + 1].startsWith('-')) {
+          nextArgs[i + 1] = resolveTiaPathFlagValue(baseFlag, nextArgs[i + 1], cwd);
+        }
+        i++;
+      }
+      continue;
+    }
+    if ((action === 'import' || action === 'diff') && !path.isAbsolute(arg)) {
+      nextArgs[i] = path.resolve(cwd, arg);
+    }
+  }
+  if ((action === 'import' || action === 'diff') && !hasRoot) {
+    nextArgs.push('--root', cwd);
+  }
+  return nextArgs;
+}
+
 function reorderTestArgs(args) {
   if (args[0] !== 'test' && !(args[0] === 'run' && args[1] === './cmd/siemens-lsp' && args[2] === 'test')) {
     return args.slice();
@@ -411,10 +527,17 @@ async function main(argv = process.argv.slice(2)) {
 
 module.exports = {
   isRepoDevelopmentMode,
+  platformPackageName,
   reorderTestArgs,
   resolveCoverageOutputPaths,
   resolveGoRunPaths,
+  resolveTiaGoRunPaths,
   resolveTestPositionals,
+  looksLikeTiaProjectPath,
+  platformRequiresWindowsBridge,
+  requireWindowsBridgeArtifacts,
+  validateResolvedBinaryPath,
+  windowsBridgeArtifactsPresent,
 };
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plccheck",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Siemens PLC language checker + LSP CLI (SCL/ST/LAD/FBD, etc.)",
   "license": "CC-BY-NC-4.0",
   "bin": {
@@ -11,15 +11,16 @@
     "README.md"
   ],
   "scripts": {
+    "test": "node --test bin/plccheck.test.js",
     "version": "node ../scripts/plccheck-npm-version-hook.mjs"
   },
   "optionalDependencies": {
-    "@danielv123/plccheck-win-x64": "2.9.0",
-    "@danielv123/plccheck-win-arm64": "2.9.0",
-    "@danielv123/plccheck-linux-x64": "2.9.0",
-    "@danielv123/plccheck-linux-arm64": "2.9.0",
-    "@danielv123/plccheck-darwin-x64": "2.9.0",
-    "@danielv123/plccheck-darwin-arm64": "2.9.0"
+    "@danielv123/plccheck-win-x64": "2.11.0",
+    "@danielv123/plccheck-win-arm64": "2.11.0",
+    "@danielv123/plccheck-linux-x64": "2.11.0",
+    "@danielv123/plccheck-linux-arm64": "2.11.0",
+    "@danielv123/plccheck-darwin-x64": "2.11.0",
+    "@danielv123/plccheck-darwin-arm64": "2.11.0"
   },
   "repository": {
     "type": "git",