systemlink-cli 1.11.0__tar.gz → 1.11.2__tar.gz

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.11.0
+Version: 1.11.2
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.11.0"
+version = "1.11.2"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/slcli/_version.py

@@ -1,4 +1,4 @@
 """Version information for slcli."""
 
 # This file is auto-generated. Do not edit manually.
-__version__ = "1.11.0"
+__version__ = "1.11.2"

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/slcli/skills/nipkg-file-package/SKILL.md

@@ -224,23 +224,25 @@ dependencies, create a Salt state file (`deploy/install.sls`) and apply it throu
 SystemLink Systems Manager. A typical SLS for a Python test package covers:
 
 1. **Download and install Python** — use the official Windows installer with `/quiet`,
-   `InstallAllUsers=1`, `PrependPath=1`. Pass `TargetDir` using a verified-safe pattern:
+   `InstallAllUsers=1`, `PrependPath=1`. For `TargetDir`, pass the full
+   `key=value` as one quoted argument when using `Program Files`:
    ```yaml
-    install-python:
-      cmd.run:
-        - name: >-
-            "C:\Windows\Temp\python-3.12.9-amd64.exe"
-            /quiet InstallAllUsers=1 PrependPath=1
-            TargetDir=C:\PROGRA~1\Python312
-            Include_launcher=1
-        - shell: cmd
-        - unless: >-
-            "C:\Program Files\Python312\python.exe" --version
+   install-python:
+     cmd.run:
+       - name: >-
+           "C:\Windows\Temp\python-3.12.9-amd64.exe"
+           /quiet
+           InstallAllUsers=1
+           PrependPath=1
+           "TargetDir=C:\Program Files\Python312"
+           Include_launcher=1
+       - shell: cmd
+       - unless: >-
+           powershell -Command "$r64 = Get-ChildItem 'HKLM:\SOFTWARE\Python\PythonCore' -ErrorAction SilentlyContinue; if ($r64) { exit 0 }; $r32 = Get-ChildItem 'HKLM:\SOFTWARE\WOW6432Node\Python\PythonCore' -ErrorAction SilentlyContinue; if ($r32) { exit 0 }; if (Test-Path 'C:\Program Files\Python312\python.exe') { exit 0 }; exit 1"
    ```
-   **Critical**: Do not quote the entire `TargetDir=...` pair. Prefer an unquoted
-   key=value argument with a short path (for example,
-   `TargetDir=C:\PROGRA~1\Python312`). If you must use a path with spaces, quote only
-   the value portion (`TargetDir="C:\Program Files\Python312"`).
+   **Critical**: In SystemLink/Salt `cmd.run` contexts, keep `TargetDir` as a single
+   quoted argument (for example `"TargetDir=C:\Program Files\Python312"`) and verify
+   install path checks.
 
 2. **Add Python to PATH** — `win_path.exists` for both the install dir and `Scripts\`.
 
@@ -326,26 +328,69 @@ SystemLink Systems Manager. A typical SLS for a Python test package covers:
 
 ## Auto-Versioning Build Script Pattern
 
-Stamp a datetime-based version into the package on every build so each nipkg uploaded
-to a feed has a unique, sortable version string:
+Use an incrementing build counter stored in `package/build_number.txt` alongside a base
+version in `package/version.txt`. This produces short, valid Debian version strings
+(`major.minor.patch.build`) that NI Package Manager and SystemLink accept reliably.
+
+**Why not timestamps?** A timestamp-based suffix like `1.0.0.20260420083348` exceeds the
+length that SystemLink's `pkg.installed` Salt state can resolve correctly. The feed lookup
+fails silently and the state reports the package as not found. Always use a short numeric
+build counter instead.
+
+### File layout
+
+```text
+package/
+├── version.txt        # base version, e.g. "1.0.1"  (edit when bumping major/minor/patch)
+├── build_number.txt   # next build number to use, e.g. "0"  (auto-incremented by build script)
+├── control
+├── instructions
+├── postinstall.bat
+└── preuninstall.bat
+```
+
+If your build script stamps versions through `control.template`, keep
+`control.template` in source control as the input template and write the stamped
+result to `control` during the build.
+
+### Build script snippet
 
 ```bat
-REM Generate version: 1.0.0.yyyyMMddHHmmss
-for /f "usebackq delims=" %%V in (`powershell -NoProfile -Command "Get-Date -Format '1.0.0.yyyyMMddHHmmss'"`) do set PACKAGE_VERSION=%%V
+set SCRIPT_DIR=%~dp0
+set CONTROL_DIR=%SCRIPT_DIR%build\nipkg\control
+set DEPLOY_SLS=%SCRIPT_DIR%deploy\install.sls
+set VERSION_FILE=%SCRIPT_DIR%package\version.txt
+set BUILD_NUMBER_FILE=%SCRIPT_DIR%package\build_number.txt
+set BASE_VERSION=
+set NEXT_BUILD=
+
+set /p BASE_VERSION=<"%VERSION_FILE%"
+set /p NEXT_BUILD=<"%BUILD_NUMBER_FILE%"
+if "%BASE_VERSION%"=="" (
+    echo Failed to read package\version.txt.
+    exit /b 1
+)
+if "%NEXT_BUILD%"=="" set NEXT_BUILD=0
+set PACKAGE_VERSION=%BASE_VERSION%.%NEXT_BUILD%
+set /a WRITE_BUILD=%NEXT_BUILD%+1
+echo %WRITE_BUILD%>"%BUILD_NUMBER_FILE%"
+echo Version for this build: %PACKAGE_VERSION%
 
 REM Stamp version into control file
 powershell -NoProfile -Command ^
-  "(Get-Content -Raw '%CONTROL_DIR%\control') -replace '(?m)^Version:\s*.*$','Version: %PACKAGE_VERSION%' ^
-  | Set-Content -Encoding ASCII '%CONTROL_DIR%\control'"
+  "$p='%CONTROL_DIR%\control.template'; $o='%CONTROL_DIR%\control'; (Get-Content -Raw $p) -replace '(?m)^Version:\s*.*$','Version: %PACKAGE_VERSION%' | Set-Content -Encoding ASCII $o"
 
 REM Stamp version into deploy\install.sls (keeps SLS in sync with feed)
 powershell -NoProfile -Command ^
-  "(Get-Content -Raw '%DEPLOY_SLS%') -replace '(?m)^\s*-\s*my-package:\s*.*$','      - my-package: %PACKAGE_VERSION%' ^
-  | Set-Content -Encoding ASCII '%DEPLOY_SLS%'"
+  "$p='%DEPLOY_SLS%'; (Get-Content -Raw $p) -replace '(?m)^\s*-\s*my-package:\s*.*$','      - my-package: %PACKAGE_VERSION%' | Set-Content -Encoding ASCII $p"
 ```
 
-This ensures the package version in the feed, the control file, and the SLS are always
-consistent without manual edits.
+### Workflow
+
+1. On the first build: `version.txt` = `1.0.1`, `build_number.txt` = `0` → produces `1.0.1.0`, writes `1` back.
+2. On the next build: reads `1`, produces `1.0.1.1`, writes `2` back, and so on.
+3. To bump major/minor/patch: edit `version.txt` and reset `build_number.txt` to `0`.
+4. Commit both files so the counter is shared across machines / CI runs.
 
 ## Complete Working SLS Example
 
@@ -370,7 +415,7 @@ install-python:
         /quiet
         InstallAllUsers=1
         PrependPath=1
-        TargetDir=C:\PROGRA~1\Python312
+        "TargetDir=C:\Program Files\Python312"
         Include_launcher=1
     - shell: cmd
     - unless: >-
@@ -407,7 +452,7 @@ install-my-test-package:
   pkg.installed:
     - install_recommends: true
     - pkgs:
-      - my-package: 1.0.0.20260420083348
+      - my-package: 1.0.1.0
     - require:
       - module: add-my-test-feed
 
@@ -443,9 +488,9 @@ install-pip-deps:
 ```
 
 **Key rules from testing:**
-- `TargetDir` must use the 8.3 path `C:\PROGRA~1\Python312` — quoting `Program Files`
-  inside `cmd.run` with nested Salt string interpolation truncates at the space even
-  with outer quotes.
+- Pass `TargetDir` as one quoted key/value argument when using `Program Files`
+  (`"TargetDir=C:\Program Files\Python312"`) and keep explicit registry/path checks
+  in `unless` guards.
 - `unless` guards for Python install must check the registry AND the file path; using
   only `python --version` can match the Salt minion's bundled Python, not the system one.
 - The `require` type for `pkg.installed` after `module.run` is `module:`, not `pkgrepo:`.
@@ -464,7 +509,7 @@ file server-side and rejects anything that is not parseable as YAML.
   supported**. Hardcode all values (Python version, paths, URLs) directly.
 - **Validate locally** before uploading: `python -c "import yaml; yaml.safe_load(open('install.sls'))"`
 - **Salt state functions that work**: `cmd.run`, `file.managed`, `file.serialize`,
-  `file.absent`, `win_path.exists`, `system.reboot`, `pkg.installed`, `pkgrepo.managed`
+  `file.absent`, `win_path.exists`, `system.reboot`, `module.run`, `pkg.installed`
   — any valid Salt state module is accepted as long as the YAML parses.
 
 ### Uploading States to SystemLink
@@ -474,8 +519,9 @@ The SystemLink Systems State API (`/nisystemsstate/v1/`) provides two ways to cr
 #### Option 1: JSON API — Package/Feed States Only
 
 `POST /nisystemsstate/v1/states` with a JSON body. This only supports `packages` and
-`feeds` arrays (rendered as `pkg.installed` and `pkgrepo.managed` in the SLS). Use this
-when the state only needs to install nipkg packages.
+`feeds` arrays for package/feed-only workflows. Use this when the state only needs to
+install nipkg packages. For custom SLS uploads, continue using the verified
+`module.run` + `pkg.mod_repo` pattern.
 
 ```python
 state = {

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/slcli/skills/systemlink-notebook/SKILL.md

@@ -71,7 +71,8 @@ in the cell's `.metadata` field for SystemLink to recognize the parameters and o
 
 - `papermill.parameters` keys **must** match the variable names in the code cell
 - `systemlink.parameters[].id` **must** match the variable names in the code cell
-- `systemlink.outputs[].id` **must** match the key used in the result dict passed to `sb.glue`
+- `systemlink.outputs[].id` **must** match the `id` field in each output object in the
+  `result` list passed to `sb.glue('result', result)`
 - `tags: ["parameters"]` is **required** — this is how papermill identifies the cell
 - `systemlink.version` must be `2` for most notebooks, or `1` for **Work Item Automations**
 - Supported parameter types: `string`, `integer`, `float`, `boolean`, `string[]`
@@ -140,6 +141,21 @@ result = [{
 sb.glue('result', result)
 ```
 
+### Output validation guardrails
+
+- Ensure `result` is a list of output objects, not a dict.
+- Ensure each output object has: `display_name`, `id`, `type`, and `data`.
+- Ensure `type` is one of the supported output types and matches metadata.
+- Ensure output `id` exactly matches `systemlink.outputs[].id`.
+- For `data_frame`, ensure `data.columns` and `data.values` are present and aligned.
+
+For Systems Grid notebooks, validate that:
+
+- The first column is exactly `minion id`.
+- The first value in each row is the system ID string.
+- For single-column grid reports, use exactly two columns: `minion id` and the report value column.
+- If the notebook is intended to populate one grid column, avoid extra columns unless explicitly required.
+
 ### Systems Grid reports
 
 When the notebook is used as a Systems Grid column, the `data_frame` output
@@ -152,6 +168,26 @@ df_dict = {
 }
 ```
 
+Common Systems Grid pattern for one metric per system:
+
+```python
+metric_by_system = {item['id']: item['metric_value'] for item in data.data}
+df = pd.DataFrame.from_dict(metric_by_system, orient='index', columns=['metric'])
+
+df_dict = {
+  'columns': ['minion id', 'metric'],
+  'values': df.reset_index().values.tolist()
+}
+
+result = [{
+  'display_name': 'Metric',
+  'id': 'metric_output',
+  'type': 'data_frame',
+  'data': df_dict
+}]
+sb.glue('result', result)
+```
+
 ## Common Imports
 
 ```python
@@ -172,7 +208,6 @@ from nisystemlink.clients.assetmanagement import AssetManagementClient
 
 # Direct HTTP (when no typed client exists)
 import requests
-from nisystemlink.clients.core import HttpConfigurationManager
 config = HttpConfigurationManager.get_configuration()
 base_url = config.server_uri.rstrip("/")
 headers = {"x-ni-api-key": config.api_keys[0]}
@@ -191,7 +226,6 @@ headers = {"x-ni-api-key": config.api_keys[0]}
 
 When using direct HTTP, prefer the OpenAPI docs first to confirm the service base
 path, request body shape, and response schema before writing notebook code.
-
 ## Systems Query Pattern
 
 The `SystemsApi` uses a projection/filter pattern for querying:
@@ -210,6 +244,22 @@ query_result = api.get_systems_by_query(query=query)
 data = await query_result
 ```
 
+### Async and response handling guardrails
+
+- In notebook cells, prefer top-level `await` over `asyncio.run(...)`.
+- Do not call `asyncio.run(...)` inside notebook execution cells; kernels may already have an active event loop.
+- `get_systems_by_query` can return typed response objects (for example `QuerySystemsResponse`). Prefer `data.data` (or `getattr(data, 'data', ...)`) over assuming a plain dict/list.
+
+Safe extraction pattern:
+
+```python
+query_result = api.get_systems_by_query(query=query)
+data = await query_result
+systems = getattr(data, 'data', None)
+if systems is None:
+    systems = data.get('data', data) if isinstance(data, dict) else data
+```
+
 ### Common filter expressions
 
 | Filter | Description |
@@ -318,6 +368,29 @@ the server rejects the update.
 reading the `Workspace` field from the active profile. Do not assume "Default" or
 prompt the user unless `slcli info` shows no workspace configured.
 
+## Execution Validation Checklist
+
+After create/update, always validate with a fresh (non-cached) execution before concluding success:
+
+```bash
+slcli notebook execute sync -n <NOTEBOOK_ID> -w "<WORKSPACE_NAME>" --no-cache -f json
+```
+
+Validation steps:
+
+1. Confirm `status` is `SUCCEEDED` and `errorCode` is `NO_ERROR`.
+2. Confirm output `id` and `type` match parameters-cell metadata.
+3. Confirm `data.columns` and `data.values` shape matches the target interface.
+4. If output still looks old, check `cachedResult`; rerun with `--no-cache`.
+
+## Known Failure Modes and Fixes
+
+- `ValueError: No kernel name found in notebook`: restore notebook-level `metadata.kernelspec`.
+- Notebook output not shown in SystemLink UI: restore parameters-cell `systemlink` metadata and `tags: ["parameters"]`.
+- Systems Grid format mismatch: ensure first column is `minion id` and output is a valid `data_frame` payload.
+- Runtime loop errors (`asyncio.run() cannot be called from a running event loop`): replace `asyncio.run(...)` with top-level `await`.
+- Result appears unchanged after update: rerun with `--no-cache` and re-check returned execution JSON.
+
 ## Example
 
 See [notebook-patterns.md](./references/notebook-patterns.md) for a complete

{systemlink_cli-1.11.0 → systemlink_cli-1.11.2}/slcli/skills/systemlink-notebook/references/notebook-patterns.md

@@ -22,6 +22,7 @@ Import Python modules for executing the notebook.
 
 **Cell 2 — Imports (code)**
 ```python
+import re
 import pandas as pd
 import scrapbook as sb
 
@@ -99,8 +100,32 @@ The cell metadata must include:
 ```python
 api = SystemsApi()
 
-projection = f'new(id, packages.data["{package}"].displayversion, packages.data["{package}"].version)'
-filter = (systems_filter or "!string.IsNullOrEmpty(id)") + f' && packages.data.keys.Contains("{package}")'
+def _escape_filter_value(value: str) -> str:
+    """Escape backslashes first, then quotes, for safe quoted filter literals."""
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+def _validate_package_name(value: str) -> str:
+    normalized = value.strip()
+    if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?", normalized):
+        raise ValueError("package must only contain letters, numbers, dot, dash, or underscore")
+    return normalized
+
+def _validate_filter_fragment(value: str) -> str:
+    normalized = value.strip()
+    if not normalized:
+        return "!string.IsNullOrEmpty(id)"
+    if not re.fullmatch(r'[A-Za-z0-9_ ."\-()\[\],:&|=!<>]*', normalized):
+        raise ValueError("systems_filter contains unsupported characters")
+    return normalized
+
+safe_package = _escape_filter_value(_validate_package_name(package))
+base_filter = _validate_filter_fragment(systems_filter)
+
+projection = (
+    f'new(id, packages.data["{safe_package}"].displayversion, '
+    f'packages.data["{safe_package}"].version)'
+)
+filter = base_filter + f' && packages.data.keys.Contains("{safe_package}")'
 
 query_sys_request = QuerySystemsRequest(skip=0, projection=projection, filter=filter)
 query_result = api.get_systems_by_query(query=query_sys_request)