test(orchestrator): increase test coverage, dev harness, and contributor docs

workspaces/orchestrator/.changeset/itchy-flowers-smash.md

@@ -0,0 +1,7 @@
+---
+'@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-orchestrator': patch
+'@red-hat-developer-hub/backstage-plugin-orchestrator-backend-module-loki': patch
+'@red-hat-developer-hub/backstage-plugin-orchestrator-backend': patch
+---
+
+Add module wiring tests, a local `dev/` harness, and contributor documentation.

workspaces/orchestrator/plugins/orchestrator-backend-module-loki/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing — Orchestrator Loki backend module
+
+Developer guide for
+`@red-hat-developer-hub/backstage-plugin-orchestrator-backend-module-loki`. For
+operator install and Loki configuration, see [README.md](./README.md).
+
+## Prerequisites
+
+- Node.js **22 or 24** (see workspace `engines` in
+  `workspaces/orchestrator/package.json`)
+- Yarn (this workspace has its own `yarn.lock`; run commands from
+  `workspaces/orchestrator/`)
+- The host
+  [`orchestrator-backend`](../orchestrator-backend) plugin (this module
+  registers against its workflow-logs extension point)
+
+## Development harness
+
+This package has **no** standalone `dev/` harness. Day-to-day work uses package
+tests. To exercise the module in a running backend, load it next to
+`orchestrator-backend` (see [README.md](./README.md) installation), for example
+in a consumer app or the workspace
+[`yarn dev`](../../docs/local-development.md) stack with Loki configured.
+
+Do not add a second full Backstage application under this package.
+
+### Config notes
+
+Required Loki keys live under `orchestrator.workflowLogProvider.loki` (`baseUrl`,
+`token`, and optional hardening flags). Use local-only placeholder values for
+development — do not commit secrets. See [README.md](./README.md) for the full
+config table.
+
+## Validation commands
+
+From the workspace root (`workspaces/orchestrator`):
+
+```bash
+yarn workspace @red-hat-developer-hub/backstage-plugin-orchestrator-backend-module-loki test
+yarn workspace @red-hat-developer-hub/backstage-plugin-orchestrator-backend-module-loki lint
+yarn tsc:full
+```
+
+## What automated tests cover
+
+CI exercises:
+
+- **Module wiring** — `startTestBackend` smoke that the module calls
+  `addWorkflowLogProvider` once with a provider whose id is `loki`
+- **LokiProvider / helpers** — config validation (base URL, hosts, pipeline
+  filters), query URL construction, and HTTP error mapping
+
+CI does **not** replace reading
+[Backstage release notes](https://github.com/backstage/backstage/releases) for
+the `@backstage/*` packages this module depends on. After a dependency bump,
+review those notes and decide whether additional validation is warranted.
+
+Live Loki log-content matrices and production log pipelines are out of scope for
+bump-trust CI.
+
+## Full workspace app evaluation
+
+Bump default for this module is **package tests** (registration smoke + provider
+units). The orchestrator workspace also includes `packages/app` and
+`packages/backend`, started with [`yarn dev`](../../docs/local-development.md)
+when you need SonataFlow + UI + a real Loki endpoint.
+
+End-to-end “view log” flows against a live Loki tenant belong in a consumer
+Backstage / RHDH app or in
+[rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays).
+
+## Optional manual smoke checklist
+
+Use when you change extension-point registration or Loki client wiring, or when
+reviewing a Backstage version bump:
+
+1. Confirm `yarn test` passes, including `src/module.test.ts`.
+2. Optionally load this module with `orchestrator-backend` in a consumer or
+   workspace backend that has `orchestrator.workflowLogProvider.loki` configured,
+   then hit
+   `/api/orchestrator/v2/workflows/instances/<instanceId>/logs` for a known
+   instance.
+3. Playwright / production Loki coverage belongs in overlays or a consumer
+   deployment — not as a required signal for this module’s bump trust.
+
+## Related packages
+
+- [@red-hat-developer-hub/backstage-plugin-orchestrator-backend](../orchestrator-backend)
+  — host plugin that owns `workflowLogsExtensionEndpoint`
+- [@red-hat-developer-hub/backstage-plugin-orchestrator-node](../orchestrator-node)
+  — extension-point and `WorkflowLogProvider` contract

workspaces/orchestrator/plugins/orchestrator-backend-module-loki/README.md

@@ -2,6 +2,8 @@
 
 This is an extension module to the `backstage-plugin-orchestrator-backend` plugin. It provides access to the Loki log provider
 
+For local development and contributor workflows, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Prerequisites
 
 Before installing this module, ensure that the Orchestrator backend plugin is integrated into your Backstage instance. Follow the [Orchestrator README](https://github.com/redhat-developer/rhdh-plugins/tree/main/workspaces/orchestrator) for setup instructions.

workspaces/orchestrator/plugins/orchestrator-backend-module-loki/src/module.test.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { mockServices, startTestBackend } from '@backstage/backend-test-utils';
+import {
+  WorkflowLogProvider,
+  workflowLogsExtensionEndpoint,
+} from '@red-hat-developer-hub/backstage-plugin-orchestrator-node';
+
+import { orchestratorModuleLoki } from './module';
+
+describe('orchestratorModuleLoki', () => {
+  it('registers the Loki workflow log provider on the extension point', async () => {
+    const extensionPoint = {
+      addWorkflowLogProvider: jest.fn(),
+    };
+
+    await startTestBackend({
+      extensionPoints: [[workflowLogsExtensionEndpoint, extensionPoint]],
+      features: [
+        orchestratorModuleLoki,
+        mockServices.rootConfig.factory({
+          data: {
+            orchestrator: {
+              workflowLogProvider: {
+                loki: {
+                  baseUrl: 'http://localhost:3100',
+                  token: 'test-token',
+                  allowInsecureHttp: true,
+                },
+              },
+            },
+          },
+        }),
+      ],
+    });
+
+    expect(extensionPoint.addWorkflowLogProvider).toHaveBeenCalledTimes(1);
+    const provider = extensionPoint.addWorkflowLogProvider.mock
+      .calls[0][0] as WorkflowLogProvider;
+    expect(provider.getProviderId()).toBe('loki');
+  });
+});

workspaces/orchestrator/plugins/orchestrator-backend/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing — Orchestrator backend plugin
+
+Developer guide for
+`@red-hat-developer-hub/backstage-plugin-orchestrator-backend`. For operator
+install and configuration, see [README.md](./README.md) and the workspace
+[Orchestrator frontend README](../orchestrator/README.md).
+
+## Prerequisites
+
+- Node.js **22 or 24** (see workspace `engines` in
+  `workspaces/orchestrator/package.json`)
+- Yarn (this workspace has its own `yarn.lock`; run commands from
+  `workspaces/orchestrator/`)
+
+## Development harness
+
+Start this plugin in isolation:
+
+```bash
+yarn workspace @red-hat-developer-hub/backstage-plugin-orchestrator-backend start \
+  --config app-config.yaml
+```
+
+(`--config` paths are resolved from the plugins directory.)
+
+This runs [`dev/index.ts`](dev/index.ts): a minimal backend with
+`orchestratorPlugin` only. Use it to verify HTTP mount and local API wiring.
+
+The harness listens on the backend port from config (commonly **7007**). Only
+one plugin `dev/` harness should run on that port at a time.
+
+### Config stubs and `autoStart`
+
+[`app-config.yaml`](./app-config.yaml) in this package is the **minimal** config
+for local harness work (data-index URL stub). Prefer starting with
+`--config app-config.yaml` as shown above.
+
+Optional overrides can go in an untracked `app-config.local.yaml` next to the
+config file you pass.
+
+Integration tests and bump-trust CI must keep SonataFlow container launch off:
+
+```yaml
+orchestrator:
+  sonataFlowService:
+    autoStart: false
+  dataIndexService:
+    url: http://localhost:8080 # stub; tests mock service collaborators
+```
+
+`autoStart: true` launches a SonataFlow container via `DevModeService`. That is
+for full workspace local development
+([`docs/local-development.md`](../../docs/local-development.md)), not for
+package unit/integration tests.
+
+Do not commit secrets in package or test config.
+
+### Unauthenticated health check
+
+`GET /api/orchestrator/health` is registered with an unauthenticated auth
+policy. You can smoke it without a bearer token:
+
+```bash
+curl "http://localhost:7007/api/orchestrator/health"
+```
+
+Expect `{ "status": "ok" }`.
+
+## Validation commands
+
+From the workspace root (`workspaces/orchestrator`):
+
+```bash
+yarn workspace @red-hat-developer-hub/backstage-plugin-orchestrator-backend test
+yarn workspace @red-hat-developer-hub/backstage-plugin-orchestrator-backend lint:check
+yarn tsc:full
+```
+
+## What automated tests cover
+
+CI exercises:
+
+- **Plugin wiring (`startTestBackend`)** — `/health` succeeds without auth;
+  health remains open when permissions deny; representative **execute** and
+  **logs** routes return **403** when permission is denied
+- **Router authorization** — deeper ALLOW / DENY / CONDITIONAL matrices in
+  `src/service/router.test.ts` (not re-duplicated at plugin level)
+- **OrchestratorService** — proportional outcome assertions (not mock-call-only)
+  for bump-sensitive paths such as abort and execute
+- **Other unit suites** — SonataFlow client, data index, mappings, permissions
+  rules, etc.
+
+CI does **not** replace reading
+[Backstage release notes](https://github.com/backstage/backstage/releases) for
+the `@backstage/*` packages this plugin depends on. After a dependency bump,
+review those notes and decide whether additional validation is warranted.
+
+## Full workspace app evaluation
+
+Bump default for this package is **plugin `dev/` + package tests**. The
+orchestrator workspace also includes `packages/app` and `packages/backend`,
+started with [`yarn dev`](../../docs/local-development.md) when you need
+SonataFlow container auto-start, workflow clone, and the full UI.
+
+Do **not** add a second full Backstage application under this package for
+day-to-day contributor or CI work. Multi-user / credential-backed /
+production-like e2e belongs in a consumer RHDH deployment or
+[rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays).
+
+## Optional manual smoke checklist
+
+Use when you change HTTP router / auth-policy code or are reviewing a Backstage
+version bump:
+
+1. Start this harness with `--config app-config.yaml` (and local overrides if
+   needed). Ensure `autoStart` is false / unset unless you intentionally want a
+   SonataFlow container.
+2. Hit health:
+
+   ```bash
+   curl "http://localhost:7007/api/orchestrator/health"
+   ```
+
+3. Protected execute/log routes require a running permission policy and (for
+   most paths) a reachable data-index / workflow services. Prefer the automated
+   DENY→403 cases in `src/plugin.test.ts` for bump confidence. Full SonataFlow
+   / Playwright coverage belongs in overlays or a consumer deployment.
+
+## Related packages
+
+- [@red-hat-developer-hub/backstage-plugin-orchestrator](../orchestrator) —
+  frontend plugin
+- [@red-hat-developer-hub/backstage-plugin-orchestrator-backend-module-loki](../orchestrator-backend-module-loki)
+  — workflow log provider module
+- [@red-hat-developer-hub/backstage-plugin-scaffolder-backend-module-orchestrator](../scaffolder-backend-module-orchestrator)
+  — scaffolder actions that call this API

workspaces/orchestrator/plugins/orchestrator-backend/README.md

@@ -3,3 +3,5 @@
 Welcome to the backend package for the Orchestrator plugin!
 
 For more information about the Orchestrator plugin, see the [Orchestrator Plugin documentation](https://github.com/redhat-developer/rhdh-plugins/tree/main/workspaces/orchestrator/plugins/orchestrator) on GitHub.
+
+For local development and contributor workflows, see [CONTRIBUTING.md](./CONTRIBUTING.md).