@interopio/iocd-cli 1.0.1 → 1.0.2

package/changelog.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2](https://github.com/InteropIO/iocd-cli/compare/iocd-cli-v1.0.1...iocd-cli-v1.0.2) (2026-08-18)
+
+
+### Bug Fixes
+
+* **templates:** pin wdio service 1.0.0-next.3 and document sso startup login in the skill ([fa49dc1](https://github.com/InteropIO/iocd-cli/commit/fa49dc15f541cfa79437f78c1fd5647d6dfd4aea))
+
 ## [1.0.1](https://github.com/InteropIO/iocd-cli/compare/iocd-cli-v1.0.0...iocd-cli-v1.0.1) (2026-08-16)
 
 

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/SKILL.md

@@ -57,6 +57,17 @@ cd tests && npm run typecheck                 # type-check without launching the
   window and switch by `workspaceWindow.getGdWindow().id` for its DOM. Refresh the Workspace
   reference after structural changes before reading its updated tree.
 - **Keep the seed's config**: the `platform-wdio` runner and `binary: process.env.BINARY_PATH`.
+- **Keep the test config layer minimal.** `config/system.json` is merged over the config the seed
+  already ships. Use it for test plumbing (fixture app store, `folders.userData`, log locations),
+  not to change platform behavior — that belongs in the seed's `modifications/`.
+- **A test that needs different platform settings needs its own launch.** Platform-wide settings
+  (Channel mode, group type, dialogs) can't change mid-process: add a delta
+  `config/system.<variant>.json` and a second capability in `wdio.config.ts` with its own
+  `configOverrides` + `wdio:specs`, and `wdio:exclude` those specs from the default capability so
+  they don't also run under it. See [configuration](./references/configuration.md).
+- **A seed with an SSO login page needs the service's `login` option** — the platform blocks startup
+  on the login window, so without it `npm test` hangs until the startup timeout. Credentials come
+  from env vars, never from specs or config. See [configuration](./references/configuration.md).
 - **Prefer service models for built-in UI.** Check the installed `models/index.d.ts`; model exports
   vary by `@interopio/wdio-iocd-service` version. Use ordinary WebdriverIO selectors for app UI.
 - **Preserve user files.** Never put the license (or `user-data`) in specs, logs, or CI artifacts.
@@ -67,5 +78,5 @@ cd tests && npm run typecheck                 # type-check without launching the
 - [authoring](./references/authoring.md) — spec shape, fixtures, synchronization, isolation.
 - [commands](./references/commands.md) — the IOCD-specific WebdriverIO commands (for the rest, read the service `.d.ts`).
 - [models](./references/models.md) — built-in IOCD UI page objects, current exports, and version rules.
-- [configuration](./references/configuration.md) — env vars, overrides, optional libraries, runners, CI.
+- [configuration](./references/configuration.md) — env vars, overrides, per-capability extra config for tests that need other platform settings, SSO startup login automation, optional libraries, runners, CI.
 - [troubleshooting](./references/troubleshooting.md) — executable, license, startup, IO API, dead window handles, flaky tests.

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/authoring.md

@@ -34,7 +34,9 @@ describe("behavior under test", () => {
 
 Arrange platform state with the io.Connect API (`io`); exercise and assert user-visible behavior with
 WebdriverIO (`$`, `browser`). For config-dependent suites, read `globalThis.ioCDPlatformConfig` at
-describe time (the API isn't available then).
+describe time (the API isn't available then) — and when the behavior needs *different* platform
+settings, give it its own capability and config override, see
+[configuration](./configuration.md).
 
 ## The generated specs are your templates
 
@@ -51,7 +53,8 @@ Each demonstrates a pattern worth copying — read the one closest to your goal:
   second app received an Interop invocation.
 - `notifications.spec.ts` — raise a notification and assert it in the Notification Panel.
 - `workspace-add-app.spec.ts` — add an app through the Workspaces add-application popup (UI clicks).
-  The popup flow assumes universal mode (`config/system.json` sets `"advancedMode": false`).
+  In universal mode the popup renders inside the frame window; check the mode the seed ships and
+  adapt the spec instead of forcing `advancedMode` in the test override.
 
 ## Fixtures
 
@@ -66,8 +69,8 @@ For a Channel-enabled fixture, initialize the client API with `IODesktop({ chann
 enable `details.channelSelector` in its app definition. The built-in selector belongs to the Web
 Group, not the client app DOM: use `Group` and its frame caption model from
 `@interopio/wdio-iocd-service/models`, then switch to the selector popup before querying its DOM.
-See [models](./models.md), `channel-selector.spec.ts`, and the deterministic Channel definitions in
-`config/system.json`.
+See [models](./models.md) and `channel-selector.spec.ts`. Read the configured Channels at runtime
+with `io.channels.all()` — don't hard-code names or redefine Channels in the test override.
 Register membership changes with `io.channels.onChannelsChanged()` — it isn't a window API. Expose
 an app readiness signal and wait for it before changing the Channel through the UI, so the test
 can't act before the app has initialized Channels and registered its listener.

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/configuration.md

@@ -10,8 +10,143 @@ Read `tests/wdio.config.ts` — it composes `IOCDBaseConfiguration` + `IOCDServi
 | `iocd:options.configOverrides` | Extra platform config (absolute paths) applied only to tests. |
 | `iocd:options.ioInitOptions` | APIs + optional `libraries` used to build the test API. |
 
-`config/system.json` registers `tests/tests/config/apps.json` as a path app store and isolates
-`folders.userData` to `tests/user-data` (disposable — never commit it or reuse its state).
+## Configuration layers
+
+The config the platform runs with is three layers, each deep-merged over the previous:
+
+| Layer | Owner | Where |
+|-------|-------|-------|
+| Default `system.json` | io.Connect Desktop | inside the installed `iocd` component |
+| Seed modifications | the seed | `modifications/**/iocd/config/system.json.merge` — dev *and* packed build |
+| Test overrides | the test package | `config/system.json`, merged on top for the test process only |
+
+**Keep the test layer minimal.** Whatever the seed configures is already in effect during a test
+run — don't restate it. Override only what makes the run isolated and reproducible: the fixture app
+store, `folders.userData`, log/crash output locations, and similar plumbing. Changing platform
+behavior here (window mode, Channels, gateway, auth, themes) means the tests no longer exercise the
+platform the seed ships — you'd be testing something else. Behavior changes belong in
+`modifications/`; another *supported* configuration belongs in its own capability (below).
+
+The generated `config/system.json` registers `tests/tests/config/apps.json` as a path app store and
+isolates `folders.userData` to `tests/user-data` (disposable — never commit it or reuse its state).
+
+## Tests that need extra config
+
+Platform-wide settings (Channel mode, group type, default dialogs, gateway) are fixed for the life
+of a process — a spec can't switch them at run time. Tests that need a configuration other than the
+one the seed ships therefore need **their own platform launch**: one capability per configuration in
+the single `tests/wdio.config.ts`.
+
+1. Add a **delta** file next to the base one — `tests/config/system.<variant>.json`, containing only
+   the keys that differ.
+2. Put the specs that need it in their own folder — `tests/tests/<variant>/`.
+3. Add a capability for it: same `binary`, `iocd:runner` and `ioInitOptions` as the default one,
+   different `configOverrides` and `wdio:specs`.
+
+```ts
+// tests/wdio.config.ts
+const ioInitOptions = { appManager: "full", layouts: "full", channels: true, libraries: ["@interopio/workspaces-api"] };
+
+const capability = (specs: string[], extraConfig: string[] = [], exclude: string[] = []) => ({
+  browserName: "iocd",
+  "iocd:runner": "platform-wdio" as const,
+  "iocd:options": {
+    binary,
+    ioInitOptions,
+    // Merged in order over the platform + seed config; the last file wins.
+    configOverrides: [path.resolve(rootDir, "config/system.json"), ...extraConfig],
+  },
+  // Nested array = all matching specs in ONE worker, so the platform starts once per capability.
+  "wdio:specs": [specs],
+  "wdio:exclude": exclude,
+});
+
+capabilities: [
+  capability(["./tests/**/*.spec.ts"], [], ["./tests/multi-channel/**/*.spec.ts"]),
+  capability(
+    ["./tests/multi-channel/**/*.spec.ts"],
+    [path.resolve(rootDir, "config/system.multi-channel.json")]
+  ),
+],
+```
+
+Rules:
+
+- **Exclude the variant specs from the default capability** (`wdio:exclude`). Without it they run
+  twice — once under a configuration they weren't written for.
+- **The default capability keeps the seed's shipped configuration.** A variant covers another
+  configuration your seed genuinely supports; it's not a way to make a failing test pass. Behavior
+  your users always get belongs in the seed's `modifications/`.
+- **One launch per capability, run sequentially** (`IOCDBaseConfiguration` sets `maxInstances: 1`).
+  Budget a full platform startup + shutdown for each — group specs by configuration; never add a
+  capability per spec.
+- **`npm test -- --spec <file>` overrides capability spec patterns**, so a single-spec run executes
+  that spec under *every* capability. Config-dependent specs must read the live config and skip when
+  it doesn't apply (below).
+
+### Read the live config in a spec
+
+`globalThis.ioCDPlatformConfig` is the resolved system config, available **synchronously at describe
+time** (the IO API is not) — so it can drive `describe.skip`/`this.skip()` or per-mode test
+generation:
+
+```ts
+type PlatformConfigView = { windows?: { channelSelector?: { type?: "single" | "multi" } } };
+const selectorType = (globalThis as { ioCDPlatformConfig?: PlatformConfigView }).ioCDPlatformConfig
+  ?.windows?.channelSelector?.type;
+
+describe("multi-Channel selection", function () {
+  before(function () {
+    if (selectorType !== "multi") {
+      this.skip();
+    }
+  });
+});
+```
+
+Never treat a missing value as `false`/absent: a spec asserting "nothing happens" would then pass
+under every configuration — green for the wrong reason. Skip explicitly, or throw a message naming
+the configuration that was actually found.
+
+## Platform with an SSO login at startup
+
+A seed configured with an interactive login (`ssoAuth` in the system config) reports readiness only
+**after** someone signs in — without automation, `npm test` sits on the login window until the
+startup timeout and no spec runs. The service's `login` option drives that window while the
+platform boots. Requires `@interopio/wdio-iocd-service` 1.0.0-next.3+ (the version currently
+generated); older test packages must update `tests/package.json` first.
+
+```ts
+// tests/wdio.config.ts
+services: IOCDService({
+  login: {
+    window: { url: /login\.mycompany\.com/ }, // substring or RegExp; `title` also works
+    handler: async (browser) => {
+      await browser.$("#username").setValue(process.env.IOCD_TEST_USER!);
+      await browser.$("#password").setValue(process.env.IOCD_TEST_PASSWORD!);
+      await browser.$("button[type=submit]").click();
+    },
+  },
+}),
+```
+
+Rules:
+
+- **The handler runs before the platform is ready.** No `browser.io()`, no models — plain
+  WebdriverIO against the login page only. The WDIO globals (`browser`, `$`, `$$`) are set while it
+  runs, so page objects work.
+- **The signed-in session belongs to the platform process**, so the apps under test are
+  authenticated exactly as in production.
+- **Credentials come from env vars / CI secrets** — never from specs or config files.
+- **A still-valid session skips the phase** (no login window appears; `onNoLoginWindow` defaults to
+  `"skip"`, set `"fail"` to require one). Budgets: `timeoutMs` (find window + handler) and
+  `readyTimeoutMs` (readiness after the handler), both defaulting to 120000.
+- **Any login failure stops the run** — no window, a handler error/timeout, or no readiness after
+  the handler. The platform is destroyed and the capability's specs are reported failed. The login
+  is never retried.
+- **MFA prompts and native OS dialogs can't be driven by WebDriver** — use an exempt test account or
+  a non-interactive auth configuration for the test platform.
+- `login` also accepts `(capability) => LoginOptions | undefined` for per-capability variants.
 
 ## Add an optional IO library
 

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/models.md

@@ -11,7 +11,7 @@ over copying internal IOCD selectors into a spec.
 
 ## Current Generated Version
 
-The generated test package currently pins `@interopio/wdio-iocd-service@1.0.0-next.2`. Its
+The generated test package currently pins `@interopio/wdio-iocd-service@1.0.0-next.3`. Its
 `@interopio/wdio-iocd-service/models` subpath exports:
 
 | Area | Models and types |

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/troubleshooting.md

@@ -18,9 +18,13 @@ the license via secrets. Never hard-code a license in a spec or fixture.
 ## Startup timeout
 
 Temporarily set `iocd:options.enableLogging: true` in `tests/wdio.config.ts` and read the platform
-output. Check for invalid config/app paths, license failures, gateway port conflicts (the generated
-`config/system.json` pins the test gateway to port 8385), and stale test user-data before raising
-`startupTimeoutMs`.
+output. Check for invalid config/app paths, license failures, gateway port conflicts (the port comes
+from the seed's own config — another running instance holds it), and stale test user-data before
+raising `startupTimeoutMs`.
+
+If a login window appears and stays open, the seed configures an interactive SSO login and startup
+is blocked until someone signs in. Automate it with the service's `login` option — see
+[configuration](./configuration.md).
 
 ## Missing IO API
 

package/dist/templates/tests/tests/README.md

@@ -29,12 +29,54 @@ npm run typecheck
 ## Layout
 
 - `wdio.config.ts` — WebdriverIO + `IOCDService` configuration (the `platform-wdio` runner).
-- `config/system.json` — platform overrides applied only to the test process.
+- `config/system.json` — test-only overrides applied to the test process.
 - `tests/common/iocd.ts` — polling, event-waiting, and cleanup-registry helpers.
 - `tests/config/apps.json` — fixture app definitions.
 - `tests/assets/applications/` — static fixture app HTML.
 - `tests/*.spec.ts` — the specifications below.
 
+`config/system.json` is merged over the platform configuration the seed already ships (the io.Connect
+Desktop defaults plus the seed's `modifications/`). Keep it minimal — the fixture app store and the
+isolated `folders.userData` — so the tests exercise the same platform behavior as the built app.
+Change platform behavior in the seed's `modifications/` instead.
+
+## Tests that need extra configuration
+
+Platform-wide settings (Channel mode, group type, default dialogs) can't change while the platform
+runs, so specifications that need a different configuration need their own platform launch. Add one
+capability per configuration in `wdio.config.ts`:
+
+```typescript
+capabilities: [
+  // Default configuration: everything except the multi-Channel specifications.
+  {
+    ...baseCapability,
+    "iocd:options": { ...baseOptions, configOverrides: [path.resolve(rootDir, "config/system.json")] },
+    "wdio:specs": [["./tests/**/*.spec.ts"]],
+    "wdio:exclude": ["./tests/multi-channel/**/*.spec.ts"],
+  },
+  // Extra configuration: only the specifications written for it.
+  {
+    ...baseCapability,
+    "iocd:options": {
+      ...baseOptions,
+      configOverrides: [
+        path.resolve(rootDir, "config/system.json"),
+        path.resolve(rootDir, "config/system.multi-channel.json"),
+      ],
+    },
+    "wdio:specs": [["./tests/multi-channel/**/*.spec.ts"]],
+  },
+],
+```
+
+Capabilities run one after another (`maxInstances` is `1`), each starting and stopping its own
+platform, so group specifications by configuration rather than adding a capability per file. Exclude
+the variant specifications from the default capability so they don't run twice, keep the default
+capability on the configuration the seed ships, and let a configuration-dependent specification read
+`globalThis.ioCDPlatformConfig` at `describe` time to skip when it isn't running under its own
+capability (`npm test -- --spec` overrides the capability spec patterns).
+
 ## Sample specifications
 
 | Specification | What it demonstrates |

package/dist/templates/tests/tests/config/system.json

@@ -1,12 +1,4 @@
 {
-  "advancedMode": false,
-  "channels": {
-    "enabled": true,
-    "definitions": [
-      { "name": "Red", "meta": { "color": "red" } },
-      { "name": "Green", "meta": { "color": "green" } }
-    ]
-  },
   "appStores": [
     {
       "type": "path",
@@ -15,21 +7,6 @@
       }
     }
   ],
-  "gw": {
-    "configuration": {
-      "port": 8385,
-      "ip": "127.0.0.1",
-      "authentication": {
-        "available": ["basic"],
-        "default": "basic"
-      }
-    }
-  },
-  "windowManagement": {
-    "group": {
-      "type": "Web"
-    }
-  },
   "folders": {
     "userData": "%WDIO_ROOT_DIR%/user-data"
   }

package/dist/templates/tests/tests/package-lock.json

@@ -10,7 +10,7 @@
       "license": "MIT",
       "devDependencies": {
         "@interopio/desktop": "^6.21.0",
-        "@interopio/wdio-iocd-service": "1.0.0-next.2",
+        "@interopio/wdio-iocd-service": "1.0.0-next.3",
         "@interopio/workspaces-api": "^4.5.0",
         "@types/chai": "^5.2.3",
         "@types/mocha": "^10.0.10",
@@ -1141,9 +1141,9 @@
       }
     },
     "node_modules/@interopio/wdio-iocd-service": {
-      "version": "1.0.0-next.2",
-      "resolved": "https://registry.npmjs.org/@interopio/wdio-iocd-service/-/wdio-iocd-service-1.0.0-next.2.tgz",
-      "integrity": "sha512-ZjWJ4CQSQIcLLmlPhXT0BSKp5Gn+4NAMp4ybHGmghW3v3h8Wi0ip0VNQvmrqpTj5/gily9USmRXByJu2Ls2FnQ==",
+      "version": "1.0.0-next.3",
+      "resolved": "https://registry.npmjs.org/@interopio/wdio-iocd-service/-/wdio-iocd-service-1.0.0-next.3.tgz",
+      "integrity": "sha512-BR4yqnf888cp9IRiSusCXPPn5v1eJhdTQPSrv6CIth1NBVx9XH08UexopNcgLl8dqh6NCeEWbXoAivuTFFQ4bg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {

package/dist/templates/tests/tests/package.json

@@ -10,7 +10,7 @@
   },
   "devDependencies": {
     "@interopio/desktop": "^6.21.0",
-    "@interopio/wdio-iocd-service": "1.0.0-next.2",
+    "@interopio/wdio-iocd-service": "1.0.0-next.3",
     "@interopio/workspaces-api": "^4.5.0",
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interopio/iocd-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "CLI tool for setting up, building and packaging io.Connect Desktop platforms",
   "engines": {
     "node": ">=22.0.0",