@ni-kismet/sl-webapp-nipkg 0.2.2 → 1.0.0

package/README.md

@@ -10,6 +10,9 @@ A flexible tool for packaging web applications into SystemLink WebApp `.nipkg` f
 
 - 🚀 **Easy Integration**: Works seamlessly with any web application
 - 📦 **Automated Packaging**: Builds and packages your app in one command  
+- 🏪 **App Store Ready**: Embed rich catalog metadata — display name, icon, screenshots, category, license, and more
+- 🚢 **SystemLink Deployment**: Create/update WebApps and upload `.nipkg` content from CLI
+- 🔐 **Secure Authentication**: `login`/`logout` commands store credentials per-host — no secrets in config files
 - ⚙️ **Flexible Configuration**: Optional config files - use CLI flags or JSON config
 - 🎯 **TypeScript Support**: Written in TypeScript with full type definitions
 - 🌈 **Beautiful CLI**: Colorful, informative command-line interface
@@ -20,7 +23,7 @@ A flexible tool for packaging web applications into SystemLink WebApp `.nipkg` f
 
 ## Prerequisites
 
-- Node.js 16 or higher (only to run the packaging tool)
+- Node.js 20 or higher (only to run the packaging tool)
 
 ## Installation
 
@@ -71,15 +74,19 @@ sl-webapp-nipkg build \
 
    ```json
    {
+     "package": "my-webapp",
      "maintainer": "John Doe <john.doe@company.com>",
      "displayName": "My WebApp",
+     "section": "WebApps",
+     "license": "MIT",
+     "appStoreCategory": "Dashboard",
+     "appStoreType": "webapp",
      "buildDir": "dist",
-     "buildCommand": "npm run build",
-     "userVisible": true
+     "buildCommand": "npm run build"
    }
    ```
 
-   **Note:** The `name`, `version`, and `description` are auto-detected from your `package.json` if present.
+   **Note:** The `package`, `version`, `description`, `homepage`, and `license` are auto-populated from your `package.json` when using `init`. Other fields must be specified explicitly in `nipkg.config.json` if needed.
 
 4. **Build and package**:
 
@@ -161,7 +168,210 @@ sl-webapp-nipkg build \
 
 ### `sl-webapp-nipkg init`
 
-Initialize a `nipkg.config.json` file in the current directory.
+Initialize a `nipkg.config.json` file in the current directory. Auto-populates `package`, `maintainer`, `homepage`, and `license` from `package.json`, and sets `section: "WebApps"` and `appStoreType: "webapp"` as defaults.
+
+### `sl-webapp-nipkg generate-manifest`
+
+Generate a `manifest.json` for App Store submission from `nipkg.config.json`. Copies all metadata fields while excluding build-only fields (`buildDir`, `buildCommand`, `outputDir`, `buildSuffix`, `deployment`).
+
+#### Options
+
+- `--config <path>` - Path to nipkg config file (default: `nipkg.config.json`)
+- `--output <path>` - Output path for manifest file (default: `manifest.json`)
+- `--nipkg-file <filename>` - Filename of the `.nipkg` to reference in the manifest
+
+#### Example
+
+```bash
+# Generate manifest after build
+sl-webapp-nipkg build
+sl-webapp-nipkg generate-manifest --nipkg-file my-app_1.0.0_all.nipkg
+```
+
+### `sl-webapp-nipkg login`
+
+Authenticate with a SystemLink host and store credentials locally so you don't need to pass `--api-key` on every command.
+
+```bash
+# Interactive — prompts for host and API key
+sl-webapp-nipkg login
+
+# Non-interactive — prompts only for API key
+sl-webapp-nipkg login --host https://systemlink.example.com
+```
+
+Credentials are verified against the SystemLink API before being stored. A `401` response means the key was wrong and nothing is saved.
+
+- Credentials are stored in `~/.sl-webapp-nipkg/credentials.json` (permissions set to `0600` on Unix)
+- Multiple hosts can be stored side by side
+- The `deploy` and `delete` commands automatically use the stored credential when no explicit key is provided
+
+#### Login Options
+
+- `--host <url>` - SystemLink host URL (prompted interactively if omitted)
+- `--timeout <ms>` - Verification request timeout in milliseconds (default `30000`)
+
+### `sl-webapp-nipkg logout`
+
+Remove the stored credential for a host.
+
+```bash
+# Interactive — prompts for host
+sl-webapp-nipkg logout
+
+# Non-interactive
+sl-webapp-nipkg logout --host https://systemlink.example.com
+```
+
+#### Logout Options
+
+- `--host <url>` - SystemLink host URL (prompted interactively if omitted)
+
+### `sl-webapp-nipkg deploy`
+
+Deploy a `.nipkg` to SystemLink WebApps.
+
+Create mode performs two API calls:
+
+1. `POST {host}/niapp/v1/webapps` (creates WebApp and returns `id`)
+2. `PUT {host}/niapp/v1/webapps/{id}/content` (uploads `.nipkg`)
+
+Update mode performs three API calls:
+
+1. `GET {host}/niapp/v1/webapps/{id}` (fetches current data to preserve unchanged fields)
+2. `PUT {host}/niapp/v1/webapps/{id}` (updates only provided metadata fields)
+3. `PUT {host}/niapp/v1/webapps/{id}/content` (uploads `.nipkg`)
+
+The tool can automatically discover and select `.nipkg` files from your build directory. For updates, you only need to provide the `--app-id` and any fields you want to change; current values are fetched from SystemLink.
+
+#### Deploy Options
+
+- `--nipkg <path>` - Path to a `.nipkg` file **or** a directory to search for `.nipkg` files (optional - see auto-discovery below)
+- `-b, --build [command]` - Run build command before deploying (optionally specify custom command)
+- `--latest` - Skip interactive selection and auto-pick the newest `.nipkg` (useful for CI/CD)
+- `--build-suffix <suffix>` - Suffix appended to nipkg filename when `--build` is used (e.g., CI build ID)
+- `--skip-cleanup` - Skip cleanup of existing nipkg files when `--build` is used
+- `--host <url>` - SystemLink host URL
+- `--api-key <key>` - API key used as `x-ni-api-key`
+- `--name <name>` - WebApp name (optional for update; falls back to top-level `displayName` from config)
+- `--workspace-id <id>` - Workspace UUID (required for create, optional for update)
+- `--policy-ids <ids>` - Comma-separated policy IDs (optional)
+- `--properties <json>` - JSON properties object (optional, include `version` field if desired)
+- `--update` - Update existing WebApp instead of creating new
+- `--app-id <id>` - Existing WebApp ID (required with `--update`)
+- `--timeout <ms>` - Request timeout in milliseconds (default `30000`)
+- `--config <path>` - Config path (default `nipkg.config.json`)
+- `-v, --verbose` - Verbose output
+
+#### Auto-discovery of nipkg Files
+
+If `--nipkg` is not provided, the tool will search for `.nipkg` files in:
+
+1. The output directory from the `--build` step (if `--build` was used)
+2. The `outputDir` from `nipkg.config.json` (defaults to `dist/nipkg`)
+
+When `--nipkg` points to a **directory**, the newest `.nipkg` inside it is selected automatically.
+
+**Default behavior (interactive selection):**
+
+```bash
+sl-webapp-nipkg deploy --update --app-id <id>
+# If multiple .nipkg files are found, prompts you to pick one
+```
+
+**Auto-select latest (non-interactive, for CI/CD):**
+
+```bash
+sl-webapp-nipkg deploy --update --app-id <id> --latest
+# Always picks the newest .nipkg without prompting
+```
+
+#### Build Before Deploy
+
+Build and deploy in a single command:
+
+```bash
+# Build with default build command from config, then deploy
+sl-webapp-nipkg deploy \
+  --update --app-id "35075240-68a1-431b-afe1-9ce76da46de3" \
+  --build \
+  --latest
+
+# Build with custom command, then deploy
+sl-webapp-nipkg deploy \
+  --update --app-id "35075240-68a1-431b-afe1-9ce76da46de3" \
+  --build "npm run build:prod" \
+  --latest
+```
+
+#### Smart Updates (Fetch Current Data)
+
+For update operations, the tool fetches current WebApp data from SystemLink. You only need to provide the fields you want to change:
+
+```bash
+# Update only the properties, keep name/workspace/policyIds unchanged
+sl-webapp-nipkg deploy \
+  --update --app-id "35075240-68a1-431b-afe1-9ce76da46de3" \
+  --nipkg ./dist/nipkg/my-app_1.0.1_all.nipkg \
+  --host "$SYSTEMLINK_HOST" \
+  --api-key "$SYSTEMLINK_API_KEY" \
+  --properties '{"version":"1.0.1","description":"Updated version"}'
+
+# Update only the policy IDs, keep other metadata
+sl-webapp-nipkg deploy \
+  --update --app-id "35075240-68a1-431b-afe1-9ce76da46de3" \
+  --nipkg ./dist/nipkg/my-app_1.0.1_all.nipkg \
+  --host "$SYSTEMLINK_HOST" \
+  --api-key "$SYSTEMLINK_API_KEY" \
+  --policy-ids "policy-1,policy-2"
+```
+
+#### Deploy Examples
+
+**Create new WebApp:**
+
+```bash
+sl-webapp-nipkg deploy \
+  --nipkg ./dist/nipkg/my-app_1.0.0_all.nipkg \
+  --host https://test.lifecyclesolutions.ni.com \
+  --api-key "$SYSTEMLINK_API_KEY" \
+  --name "My WebApp" \
+  --workspace-id "45bc27cf-85c6-485c-945d-a51e664f511d" \
+  --policy-ids "policy-1,policy-2" \
+  --properties '{"description":"my app","version":"1.0.0"}'
+```
+
+**Update existing WebApp (minimal - only app-id required):**
+
+```bash
+sl-webapp-nipkg deploy \
+  --nipkg ./dist/nipkg/my-app_1.0.1_all.nipkg \
+  --host https://test-api.lifecyclesolutions.ni.com \
+  --api-key "$SYSTEMLINK_API_KEY" \
+  --update \
+  --app-id "35075240-68a1-431b-afe1-9ce76da46de3"
+```
+
+**Build and deploy in single command:**
+
+```bash
+sl-webapp-nipkg deploy \
+  --build \
+  --update --app-id "35075240-68a1-431b-afe1-9ce76da46de3" \
+  --latest \
+  --host https://test-api.lifecyclesolutions.ni.com \
+  --api-key "$SYSTEMLINK_API_KEY" \
+  --properties '{"version":"1.0.1"}'
+```
+
+Environment variable fallback:
+
+- `SYSTEMLINK_HOST`
+- `SYSTEMLINK_API_KEY`
+
+Precedence: CLI flags > environment variables > stored login credential (`sl-webapp-nipkg login`) > defaults (where applicable).
+
+> **Security note:** The API key is intentionally **not** a `nipkg.config.json` field. The recommended workflow is to run `sl-webapp-nipkg login` once per host — credentials are stored in `~/.sl-webapp-nipkg/credentials.json` with restricted permissions. For CI/CD pipelines, use the `SYSTEMLINK_API_KEY` environment variable or the `--api-key` flag.
 
 ## Configuration
 
@@ -171,39 +381,76 @@ Initialize a `nipkg.config.json` file in the current directory.
 
 | Property | Type | Required | Description |
 | -------- | ---- | -------- | ----------- |
-| `name` | string | ❌ | Package name (auto-detected from package.json or directory name) |
+| `package` | string | ❌ | Unique package identifier — lowercase with hyphens/dots/underscores (auto-detected from package.json) |
+| `name` | string | ❌ | **Deprecated.** Use `package` instead |
 | `version` | string | ❌ | Package version (auto-detected from package.json, defaults to 1.0.0) |
-| `description` | string | ❌ | Package description (auto-detected from package.json, defaults to empty) |
+| `displayName` | string | ❌ | Human-readable display name shown in the catalog card |
+| `description` | string | ❌ | Short description (auto-detected from package.json) |
+| `section` | string | ❌ | Package section (e.g. `'WebApps'`) |
 | `maintainer` | string | ❌ | Maintainer information (defaults to 'Unknown') |
-| `architecture` | string | ❌ | Target architecture (default: 'all') |
-| `displayName` | string | ❌ | Display name for the package |
-| `buildDir` | string | ❌* | Build output directory (e.g., 'dist', 'build') - *Required if not provided via CLI |
-| `buildCommand` | string | ❌ | Custom build command (default: 'npm run build') |
-| `outputDir` | string | ❌ | Custom nipkg output directory (default: 'dist/nipkg') |
+| `homepage` | string | ❌ | Homepage / repository URL (auto-detected from package.json) |
+| `license` | string | ❌ | SPDX license identifier — **required for App Store submissions** (auto-detected from package.json) |
+| `appStoreCategory` | string | ❌ | App Store category (e.g. `'Dashboard'`, `'Data Analysis'`) |
+| `appStoreType` | string | ❌ | Resource type: `'webapp'`, `'notebook'`, or `'dashboard'` |
+| `appStoreAuthor` | string | ❌ | Author / company name shown in the catalog |
+| `appStoreTags` | string | ❌ | Comma-separated search tags (e.g. `'assets,calibration'`) |
+| `appStoreRepo` | string | ❌ | Source repository URL |
+| `appStoreMinServerVersion` | string | ❌ | Minimum SystemLink server version (e.g. `'2024 Q4'`) |
+| `iconFile` | string | ❌ | Path to app icon (SVG or PNG, max 128×128 px) — base64-embedded in package |
+| `screenshotFiles` | string[] | ❌ | Paths to up to 3 screenshot files (PNG, max 800×600 px) — base64-embedded in package |
+| `tags` | string | ❌ | Standard nipkg `Tags:` field (falls back to `appStoreTags` if omitted) |
+| `extraControlFields` | object | ❌ | Arbitrary extra control file fields written verbatim as `Key: value` lines |
+| `architecture` | string | ❌ | Target architecture (default: `'windows_all'` for App Store packages) |
+| `userVisible` | boolean \| `'yes'` \| `'no'` | ❌ | Whether the package appears in the App Store catalog (default: `'yes'`) |
+| `buildDir` | string | ❌* | Build output directory (e.g., `'dist'`, `'build'`) — *Required if not provided via CLI |
+| `buildCommand` | string | ❌ | Custom build command (default: `'npm run build'`) |
+| `outputDir` | string | ❌ | Custom nipkg output directory (default: `'dist/nipkg'`) |
 | `buildSuffix` | string | ❌ | Optional suffix for package filename (e.g., build ID for CI/CD) |
 | `depends` | string[] | ❌ | Package dependencies |
-| `userVisible` | boolean | ❌ | Whether package is user visible |
+| `deployment` | object | ❌ | SystemLink deployment defaults used by `deploy` command |
 
 ### Example Configuration
 
 ```json
 {
-  "name": "my-webapp",
+  "package": "my-webapp",
   "version": "1.2.3",
-  "description": "A SystemLink WebApp for National Instruments", 
+  "description": "A SystemLink WebApp for National Instruments",
+  "displayName": "My WebApp",
+  "section": "WebApps",
   "maintainer": "John Doe <john.doe@company.com>",
+  "homepage": "https://github.com/org/my-webapp",
+  "license": "MIT",
+  "appStoreCategory": "Dashboard",
+  "appStoreType": "webapp",
+  "appStoreAuthor": "Acme Corp",
+  "appStoreTags": "assets,calibration",
+  "appStoreMinServerVersion": "2024 Q4",
+  "iconFile": "assets/icon.svg",
   "architecture": "all",
-  "displayName": "My WebApp",
+  "userVisible": "yes",
   "buildDir": "dist",
   "buildCommand": "npm run build",
-  "userVisible": true,
   "depends": [
     "ni-systemlink-server >= 2023.1"
   ],
-  "outputDir": "packages"
+  "outputDir": "packages",
+  "deployment": {
+    "host": "https://test.lifecyclesolutions.ni.com",
+    "name": "my-webapp",
+    "workspaceId": "45bc27cf-85c6-485c-945d-a51e664f511d",
+    "policyIds": [],
+    "properties": {
+      "description": "my webapp",
+      "version": "1.2.3"
+    },
+    "timeout": 30000
+  }
 }
 ```
 
+**Note:** The `outputDir` is used by the `deploy` command for automatic `.nipkg` file discovery.
+
 ## Framework Examples
 
 ### Non-Node.js Projects
@@ -312,12 +559,16 @@ npm run package:nipkg
 import { SystemLinkNipkgBuilder, NipkgConfig, BuildOptions } from '@ni-kismet/sl-webapp-nipkg';
 
 const config: NipkgConfig = {
-  name: 'my-app',
+  package: 'my-app',
   version: '1.0.0',
   description: 'My SystemLink WebApp',
+  displayName: 'My App',
+  section: 'WebApps',
   maintainer: 'John Doe <john@example.com>',
+  license: 'MIT',
+  appStoreCategory: 'Dashboard',
+  appStoreType: 'webapp',
   buildDir: 'dist',
-  userVisible: true
 };
 
 const options: BuildOptions = {
@@ -359,7 +610,7 @@ jobs:
     - name: Setup Node.js
       uses: actions/setup-node@v3
       with:
-        node-version: '18'
+        node-version: '20'
         cache: 'npm'
     
     - name: Install dependencies
@@ -392,7 +643,7 @@ pool:
 steps:
 - task: NodeTool@0
   inputs:
-    versionSpec: '18.x'
+    versionSpec: '20.x'
 
 - script: npm ci
   displayName: 'Install dependencies'
@@ -432,7 +683,7 @@ your-webapp-project/
 
 ## Requirements
 
-- Node.js 16+
+- Node.js 20+
 
 ## Development
 
@@ -460,6 +711,12 @@ sl-webapp-nipkg --help
 
 ### Common Issues
 
+#### "API key is required"
+
+- Run `sl-webapp-nipkg login --host <url>` to store credentials for this host, **or**
+- Pass `--api-key "$SYSTEMLINK_API_KEY"` on the command line, **or**
+- Set the `SYSTEMLINK_API_KEY` environment variable
+
 #### "Build directory not found"
 
 - Provide build directory via CLI: `--build-dir ./dist`

package/dist/builder.d.ts

@@ -1,4 +1,8 @@
 import { NipkgConfig, BuildOptions } from './types.js';
+/**
+ * Read a file from disk and return it as a base64-encoded data URI.
+ */
+export declare function encodeFileAsBase64(filePath: string): string;
 export declare class SystemLinkNipkgBuilder {
     private readonly config;
     private readonly options;
@@ -8,6 +12,10 @@ export declare class SystemLinkNipkgBuilder {
      * Build the complete nipkg package
      */
     build(): Promise<void>;
+    /**
+     * Build the complete control file content with all standard and custom fields.
+     */
+    buildControlFileContent(): string;
     /**
      * Get the package name from CLI options, config, or package.json
      */
@@ -36,5 +44,9 @@ export declare class SystemLinkNipkgBuilder {
      * Package the application into .nipkg format
      */
     private packageApplication;
+    /**
+     * Resolve userVisible to 'yes' or 'no' string for the control file.
+     */
+    private resolveUserVisible;
 }
 //# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAMvD,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB;IAM3D;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BnC;;OAEG;IACH,OAAO,CAAC,OAAO;IA4Bf;;OAEG;IACH,OAAO,CAAC,cAAc;IA0BtB;;OAEG;IACH,OAAO,CAAC,UAAU;IA2BlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,eAAe;IAqCvB;;OAEG;YACW,sBAAsB;IAwCpC;;OAEG;YACW,kBAAkB;CAkEnC"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA0FvD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3D;AAoBD,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB;IAM3D;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BnC;;OAEG;IACI,uBAAuB,IAAI,MAAM;IA2ExC;;OAEG;IACH,OAAO,CAAC,OAAO;IAgCf;;OAEG;IACH,OAAO,CAAC,cAAc;IA0BtB;;OAEG;IACH,OAAO,CAAC,UAAU;IA2BlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,OAAO,CAAC,eAAe;IAqCvB;;OAEG;YACW,sBAAsB;IAwCpC;;OAEG;YACW,kBAAkB;IA0EhC;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAU7B"}