systemlink-cli 1.3.1__py3-none-any.whl

slcli/skills/systemlink-webapp/references/deployment.md

@@ -0,0 +1,123 @@
+# Deployment Reference — slcli webapp commands
+
+## Prerequisites
+
+- `slcli` installed and authenticated (`slcli login` or config file present)
+- Angular app built to `dist/<app-name>/browser/`
+
+---
+
+## Build
+
+```bash
+# Run from project root
+node_modules/.bin/ng build --configuration production --output-path dist/<app-name>
+```
+
+**Do NOT pass `--base-href`.** This would reintroduce a `<base>` element that violates SystemLink's CSP.
+
+Angular 19 places the browser output at `dist/<app-name>/browser/` — publish that subdirectory, not the parent.
+
+### Background build (if terminal has heredoc/interrupt issues)
+
+```bash
+nohup node_modules/.bin/ng build --configuration production --output-path dist/<app-name> \
+  > /tmp/ng-build.log 2>&1 &
+echo "Build PID: $!"
+# Check progress:
+tail -f /tmp/ng-build.log
+```
+
+---
+
+## First deploy (no existing webapp)
+
+```bash
+slcli webapp publish dist/<app-name>/browser/ -w <workspace-name>
+```
+
+The command prints the new webapp ID. **Save it** — you need it for every future redeploy and for `slcli webapp open`.
+
+Example output:
+```
+Created webapp: 3727d9ac-86e1-4d6e-820e-d2630c1b28e9
+```
+
+---
+
+## Redeploy (update existing webapp)
+
+```bash
+slcli webapp publish dist/<app-name>/browser/ -w <workspace-name> -i <webapp-id>
+```
+
+---
+
+## Open in browser
+
+```bash
+slcli webapp open -i <webapp-id>
+```
+
+---
+
+## List webapps
+
+```bash
+slcli webapp list -w <workspace-name>
+```
+
+---
+
+## Delete a webapp
+
+```bash
+slcli webapp delete -i <webapp-id>
+```
+
+---
+
+## Deployment checklist
+
+Before publishing, verify:
+
+- [ ] `index.html` has **no** `<base href>` tag
+- [ ] `app.module.ts` provides `{ provide: APP_BASE_HREF, useValue: '/' }`
+- [ ] `app-routing.module.ts` uses `useHash: true`
+- [ ] `angular.json` has `inlineCritical: false` in production optimization
+- [ ] `basePath` is `window.location.origin + '/<service-prefix>'` (not just origin)
+- [ ] `credentials: 'include'` (or equivalent) set on API client
+- [ ] Build succeeded with no errors (warnings about bundle size are OK if within 2MB error limit)
+
+---
+
+## Common deployment errors
+
+### App shows blank/white screen
+
+- Check browser console for NG04002 → `useHash: true` missing
+- Check for CSP `base-uri` error → remove `<base>` tag
+
+### API calls fail with status 0 (CORS)
+
+- `basePath` is pointing to a different origin than where the app is served
+- Fix: use `window.location.origin + '/service-prefix'`
+
+### API calls return 404 on correct paths
+
+- `basePath` is missing the service prefix (e.g., `/nitag`)
+- The generated client's `defaultBasePath` is being overridden by your `Configuration` — make sure your `basePath` value includes the full prefix
+
+### Styles look broken or CSP reports `unsafe-inline`
+
+- Beasties CSS inliner is injecting `onload` handlers
+- Fix: set `inlineCritical: false` in angular.json
+
+### "Budget exceeded" build error
+
+Increase error limits in `angular.json`:
+```json
+"budgets": [
+  { "type": "initial", "maximumWarning": "1MB", "maximumError": "2MB" }
+]
+```

slcli/skills/systemlink-webapp/references/nimble-angular.md

@@ -0,0 +1,380 @@
+# Nimble Angular — Template & Usage Reference
+
+## nimble-theme-provider
+
+Wrap your entire app. Always place at the root component level.
+
+```html
+<nimble-theme-provider [theme]="currentTheme">
+  <router-outlet></router-outlet>
+</nimble-theme-provider>
+```
+
+Themes: `light`, `dark`, `color` (high contrast).
+
+For SystemLink-hosted apps, do not hard-code `theme="light"` unless the user explicitly wants a fixed theme. The common pattern is:
+
+1. Detect initial theme from `?theme=...`, then the parent frame's `nimble-theme-provider`, then local storage, then system preference
+2. If the app is hosted in a same-origin iframe, watch the parent provider's `theme` attribute with `MutationObserver` and update `currentTheme`
+3. Define theme-aware CSS aliases such as colors and shadows on `nimble-theme-provider`, not on `:root`, so token resolution follows the active Nimble theme
+
+When debugging theme mismatches, inspect resolved token values on the provider with `getComputedStyle(provider).getPropertyValue('--ni-nimble-application-background-color')` rather than only checking the `theme` attribute.
+
+---
+
+## nimble-table
+
+Displays tabular data. Data must be an `Observable<TableRecord[]>` bound with `[data$]`.
+
+### Module
+
+```typescript
+import { NimbleTableModule } from "@ni/nimble-angular/table";
+```
+
+### Row type requirement
+
+Your row type must satisfy `TableRecord`. Add an index signature:
+
+```typescript
+interface MyRow {
+  id: string;
+  name: string;
+  value: string | undefined;
+  [key: string]: FieldValue | undefined; // required for TableRecord compatibility
+}
+```
+
+### Template
+
+```html
+<nimble-table
+  [data$]="rows$"
+  id-field-name="id"
+  selection-mode="single"
+  (selection-change)="onSelectionChange($event)"
+>
+  <nimble-table-column-text field-name="name" column-id="col-name"
+    >Name</nimble-table-column-text
+  >
+
+  <nimble-table-column-text field-name="value" column-id="col-value"
+    >Value</nimble-table-column-text
+  >
+</nimble-table>
+```
+
+### Component wiring
+
+```typescript
+import { TableRecord, TableRowSelectionEventDetail } from '@ni/nimble-angular/table';
+import { BehaviorSubject } from 'rxjs';
+
+rows$ = new BehaviorSubject<MyRow[]>([]);
+
+onSelectionChange(event: CustomEvent<TableRowSelectionEventDetail<MyRow>>): void {
+  const selected = event.detail.selectedRecords[0];
+  // ...
+}
+```
+
+---
+
+## nimble-table-column-text
+
+Simple string column. Import: `NimbleTableColumnTextModule` from `@ni/nimble-angular/table-column/text`.
+
+```html
+<nimble-table-column-text field-name="myField" column-id="col-1">
+  Column Header
+</nimble-table-column-text>
+```
+
+---
+
+## nimble-button
+
+```typescript
+import { NimbleButtonModule } from "@ni/nimble-angular";
+```
+
+```html
+<!-- Default -->
+<nimble-button (click)="doSomething()">Click Me</nimble-button>
+
+<!-- Accent/primary style -->
+<nimble-button
+  appearance="block"
+  appearance-variant="accent"
+  (click)="doSomething()"
+>
+  Primary Action
+</nimble-button>
+
+<!-- Ghost / low-emphasis -->
+<nimble-button appearance="ghost" (click)="cancel()">Cancel</nimble-button>
+```
+
+> **Note:** `appearance="accent"` is NOT valid. Use `appearance="block" appearance-variant="accent"`.
+
+---
+
+## nimble-anchor-tabs + nimble-anchor-tab
+
+Use for top-level page navigation. Bind `[activeid]` from component state; update it by tracking `NavigationEnd` router events.
+
+```typescript
+import {
+  NimbleAnchorTabsModule,
+  NimbleAnchorTabModule,
+} from "@ni/nimble-angular";
+```
+
+```html
+<nimble-anchor-tabs [activeid]="activeTabId">
+  <nimble-anchor-tab id="catalog" nimbleRouterLink="/catalog"
+    >Catalog</nimble-anchor-tab
+  >
+  <nimble-anchor-tab id="installed" nimbleRouterLink="/installed"
+    >Installed</nimble-anchor-tab
+  >
+  <nimble-anchor-tab id="settings" nimbleRouterLink="/settings"
+    >Settings</nimble-anchor-tab
+  >
+</nimble-anchor-tabs>
+```
+
+Track active tab in the component (see `SKILL.md → Step 9` for full `NavigationEnd` subscription pattern).
+
+> Do not use `<nimble-tabs>` + `<nimble-tab-panel>` for navigation — that pattern is for tabbed content within a single page, not routing.
+
+---
+
+## nimble-text-field
+
+```typescript
+import { NimbleTextFieldModule } from "@ni/nimble-angular";
+```
+
+```html
+<!-- Basic -->
+<nimble-text-field
+  [(ngModel)]="filterValue"
+  placeholder="Enter filter..."
+  (ngModelChange)="onFilterChange()"
+>
+  Filter
+</nimble-text-field>
+
+<!-- With icon prefix (slot="start") -->
+<nimble-text-field
+  placeholder="Search…"
+  [(ngModel)]="searchTerm"
+  (ngModelChange)="applyFilters()"
+>
+  <nimble-icon-magnifying-glass slot="start"></nimble-icon-magnifying-glass>
+</nimble-text-field>
+```
+
+Import icon modules from the **main `@ni/nimble-angular` barrel** — icon-specific sub-paths do not exist:
+
+```typescript
+import { NimbleIconMagnifyingGlassModule } from "@ni/nimble-angular";
+```
+
+> Use `(ngModelChange)` rather than `(change)` for reactive value handling. `(change)` fires on blur only; `(ngModelChange)` fires on every keystroke.
+
+---
+
+## nimble-select + nimble-list-option
+
+```typescript
+import { NimbleSelectModule, NimbleListOptionModule } from "@ni/nimble-angular";
+```
+
+```html
+<!-- Basic -->
+<nimble-select [(ngModel)]="selectedType" (ngModelChange)="onTypeChange()">
+  <nimble-list-option value="">All types</nimble-list-option>
+  <nimble-list-option value="DOUBLE">Double</nimble-list-option>
+  <nimble-list-option value="STRING">String</nimble-list-option>
+  <nimble-list-option value="BOOLEAN">Boolean</nimble-list-option>
+</nimble-select>
+
+<!-- With built-in filter (useful for long lists) -->
+<nimble-select filter-mode="standard" [(ngModel)]="selectedWorkspace">
+  <nimble-list-option *ngFor="let ws of workspaces" [value]="ws.id"
+    >{{ ws.name }}</nimble-list-option
+  >
+</nimble-select>
+```
+
+> Use `filter-mode="standard"` to add a built-in text filter to the dropdown — no custom search logic needed for long option lists.
+
+---
+
+## nimble-drawer
+
+Side panel for details or config. Control with `#drawerRef` template variable.
+
+```typescript
+import { NimbleDrawerModule } from "@ni/nimble-angular";
+```
+
+```html
+<nimble-drawer #detailDrawer location="right">
+  <h3 slot="header">Detail</h3>
+  <div>{{ selectedItem?.name }}</div>
+  <nimble-button slot="footer" (click)="detailDrawer.hide()"
+    >Close</nimble-button
+  >
+</nimble-drawer>
+
+<nimble-button (click)="detailDrawer.show()">Open Detail</nimble-button>
+```
+
+---
+
+## nimble-spinner
+
+```typescript
+import { NimbleSpinnerModule } from "@ni/nimble-angular";
+```
+
+```html
+<nimble-spinner *ngIf="loading"></nimble-spinner>
+```
+
+---
+
+## nimble-banner
+
+For in-page error/warning/info messages.
+
+```typescript
+import { NimbleBannerModule } from "@ni/nimble-angular";
+```
+
+```html
+<nimble-banner *ngIf="error" severity="error" [open]="!!error">
+  {{ error }}
+</nimble-banner>
+```
+
+---
+
+## nimble-dialog
+
+**Critical:** never put `*ngIf` on a `nimble-dialog`. The `*ngIf="false"` removes the element from the DOM, making `@ViewChild` return `undefined` and `.show()` impossible to invoke.
+
+```typescript
+import { NimbleDialogModule } from "@ni/nimble-angular";
+```
+
+```html
+<!-- Keep the dialog always in the DOM -->
+<nimble-dialog #confirmDialog>
+  <span slot="title">Confirm Action</span>
+  <span slot="subtitle">This cannot be undone.</span>
+
+  <p>Are you sure you want to proceed?</p>
+
+  <!-- Multiple slot="footer" elements are displayed side by side -->
+  <nimble-button slot="footer" (click)="closeDialog()">Cancel</nimble-button>
+  <nimble-button
+    slot="footer"
+    appearance="block"
+    appearance-variant="accent"
+    (click)="confirm()"
+    >Confirm</nimble-button
+  >
+</nimble-dialog>
+```
+
+```typescript
+import { ElementRef, ViewChild } from '@angular/core';
+
+@ViewChild('confirmDialog') private dialogEl?: ElementRef;
+
+openDialog(): void  { this.dialogEl?.nativeElement.show(); }
+closeDialog(): void { this.dialogEl?.nativeElement.close(); }
+```
+
+**Available slots:** `title` (required text), `subtitle` (optional descriptive text), `footer` (action buttons — multiple allowed).
+
+---
+
+## Layout patterns
+
+Nimble doesn't ship a grid/layout component. Use flexbox in SCSS:
+
+```scss
+// component.scss
+:host {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  padding: 16px;
+  box-sizing: border-box;
+}
+
+.toolbar {
+  display: flex;
+  gap: 8px;
+  align-items: flex-end;
+  margin-bottom: 12px;
+  flex-wrap: wrap;
+}
+
+.table-container {
+  flex: 1;
+  min-height: 0; // important — lets flex child shrink below its content height
+}
+
+nimble-table {
+  height: 100%;
+}
+```
+
+### Clickable card / list-row pattern
+
+For any clickable tile or row, use Nimble tokens directly (not the `--sl-app-color-border` alias which is for dividers):
+
+```scss
+.card {
+  border: 1px solid var(--ni-nimble-card-border-color);
+  background: var(--ni-nimble-section-background-color);
+  border-radius: var(--ni-nimble-small-padding, 4px);
+  cursor: pointer;
+  // Transition both shadow and border for a polished hover
+  transition:
+    box-shadow var(--ni-nimble-medium-delay, 0.15s) ease,
+    border-color var(--ni-nimble-medium-delay, 0.15s) ease;
+
+  &:hover {
+    box-shadow: var(
+      --ni-nimble-elevation-2-box-shadow,
+      0 2px 8px rgba(0, 0, 0, 0.12)
+    );
+    border-color: var(--ni-nimble-border-hover-color);
+  }
+}
+
+// For equal-height cards in a CSS grid, the host element must fill the cell:
+:host {
+  display: flex;
+  height: 100%;
+}
+
+.card {
+  flex: 1; // fills the :host flex container
+}
+
+.card-body {
+  flex: 1; // pushes footer to the bottom
+}
+
+.card-description {
+  flex: 1; // equalises description height across cards
+}
+```

slcli/skills/systemlink-webapp/references/systemlink-services.md

@@ -0,0 +1,192 @@
+# SystemLink Services — API Reference
+
+## How to find a service's OpenAPI spec
+
+```
+https://<server>/<service-prefix>/swagger/v2/<service-name>.yaml
+```
+
+Examples:
+- `https://myserver.com/nitag/swagger/v2/nitag.yaml`
+- `https://myserver.com/nitest/swagger/v2/nitest.yaml`
+
+Use the spec URL as the `input` in your `openapi-ts.config.ts`.
+
+---
+
+## Tag Historian (`/nitag`)
+
+**Base URL:** `window.location.origin + '/nitag'`
+
+### Key endpoints
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Query tags with current values | POST | `/nitag/v2/query-tags-with-values` |
+| Get single tag | GET | `/nitag/v2/tags/{path}` |
+| Write tag value | PUT | `/nitag/v2/tags/{path}/values/current` |
+| Query tag history | POST | `/nitag/v2/history-data/query-decimated-data` |
+
+### Query body (`POST /query-tags-with-values`)
+
+```typescript
+{
+  filter: 'path = "system.*" and type = "DOUBLE"',  // LINQ filter string
+  take: 1000,          // max records to return
+  orderBy: 'TIMESTAMP',  // PATH | VALUE | TIMESTAMP | WORKSPACE
+  descending: true,
+  // projection: [...]  // AVOID — flattens the response and breaks tag.path / tag.type access
+}
+```
+
+### Response shape (`TagWithValue`)
+
+```typescript
+{
+  tag: {
+    path: string,
+    type: 'DOUBLE' | 'INT' | 'STRING' | 'BOOLEAN' | 'U_INT64' | 'DATE_TIME',
+    keywords: string[],
+    properties: Record<string, string>,
+    workspace: string,
+    lastUpdated: string,
+  },
+  current: {
+    value: { value: string | number | boolean },
+    timestamp: string,
+  },
+  aggregates: { ... }
+}
+```
+
+> **Gotcha:** If you include `projection` in the query, the response is flattened — `tag` nesting is removed and `path`, `type` etc. lift to the top level. This breaks `twv.tag?.path`. Omit `projection` unless you update all mapping code to match the flat shape.
+
+---
+
+## Test Monitor (`/nitest`)
+
+**Base URL:** `window.location.origin + '/nitest'`
+
+### Key endpoints
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Query results | POST | `/nitest/v2/query-results` |
+| Get result by ID | GET | `/nitest/v2/results/{id}` |
+| Query steps | POST | `/nitest/v2/query-steps` |
+| Get products | GET | `/nitest/v2/products` |
+
+### Query body
+
+```typescript
+{
+  filter: 'startedWithin = "7d"',
+  orderBy: 'startedAt',
+  descending: true,
+  take: 200,
+}
+```
+
+---
+
+## Asset Management (`/niapm`)
+
+**Base URL:** `window.location.origin + '/niapm'`
+
+### Key endpoints
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Query assets | POST | `/niapm/v1/query-assets` |
+| Get asset | GET | `/niapm/v1/assets/{id}` |
+| Get calibration forecast | GET | `/niapm/v1/assets/{id}/policies` |
+
+---
+
+## Systems Management (`/nisysmgmt`)
+
+**Base URL:** `window.location.origin + '/nisysmgmt'`
+
+### Key endpoints
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Get systems | GET | `/nisysmgmt/v1/systems` |
+| Query systems | POST | `/nisysmgmt/v1/query-systems` |
+
+---
+
+## Work Orders (`/niworkorder`)
+
+**Base URL:** `window.location.origin + '/niworkorder'`
+
+### Key endpoints
+
+| Operation | Method | Path |
+|-----------|--------|------|
+| Query work orders | POST | `/niworkorder/v1/query` |
+| Update work order | PATCH | `/niworkorder/v1/work-orders/{id}` |
+
+---
+
+## Authentication patterns
+
+### Same-origin (recommended for deployed webapps)
+
+The app is served by SystemLink and calls SystemLink. Browser session cookies are sent automatically if `credentials: 'include'` is set on fetch requests.
+
+```typescript
+// hey-api client setup
+import { createClient } from '@hey-api/client-fetch';
+
+export const apiClient = createClient({
+  baseUrl: `${window.location.origin}/nitag`,
+  credentials: 'include',
+});
+```
+
+No API key needed. The user must be logged in to SystemLink in that browser tab.
+
+### API key (for dev/remote scenarios)
+
+```typescript
+export const apiClient = createClient({
+  baseUrl: `${window.location.origin}/nitag`,
+  headers: {
+    'x-ni-api-key': localStorage.getItem('sl_api_key') ?? '',
+  },
+});
+```
+
+Let the user enter their API key in a config UI (a Nimble drawer works well). Store in `localStorage`. Never hardcode keys.
+
+---
+
+## LINQ filter syntax (used by tags, test, and other services)
+
+```
+path = "system.cpu.usage"              exact match
+path.StartsWith("system.")             prefix match
+type = "DOUBLE"                        enum match
+lastUpdated > "2024-01-01"             date comparison
+path = "cpu" and type = "DOUBLE"       AND
+path = "cpu" or path = "mem"           OR
+keywords.Contains("production")        array contains
+```
+
+String values must be double-quoted in the filter string. Build filters by joining parts with ` and `.
+
+---
+
+## Error handling
+
+SystemLink APIs return standard HTTP status codes. Common ones:
+
+| Code | Meaning |
+|------|---------|
+| 401 | Not authenticated — user needs to log in, or API key is invalid |
+| 403 | Authenticated but not authorized for this workspace/resource |
+| 404 | Resource not found |
+| 422 | Invalid request body (e.g., bad LINQ filter) |
+
+Show errors in a `<nimble-banner severity="error">` with the status code and message from the response body.