@lssm/lib.workflow-composer 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,32 @@
+# @lssm/lib.workflow-composer
+
+Compose base WorkflowSpecs with tenant-, role-, or device-specific extensions. The composer lets teams inject steps, hide portions of a workflow, and attach tenant-scoped metadata without duplicating base definitions.
+
+## Highlights
+
+- Type-safe `extendWorkflow` helper.
+- Registry for extension templates (tenant, role, device scopes).
+- Validation to ensure injected steps reference valid anchors.
+- Merge utilities to combine overlays coming from tenant + user.
+
+Refer to `docs/tech/personalization/workflow-composition.md` for more.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/dist/composer.d.ts

@@ -0,0 +1,12 @@
+import { ComposeParams, WorkflowExtension } from "./types.js";
+import { WorkflowSpec } from "@lssm/lib.contracts/workflow/spec";
+
+//#region src/composer.d.ts
+declare class WorkflowComposer {
+  private readonly extensions;
+  register(extension: WorkflowExtension): this;
+  registerMany(extensions: WorkflowExtension[]): this;
+  compose(params: ComposeParams): WorkflowSpec;
+}
+//#endregion
+export { WorkflowComposer };

package/dist/composer.js

@@ -0,0 +1 @@
+import{applyWorkflowExtension as e}from"./injector.js";var t=class{extensions=[];register(e){return this.extensions.push(e),this}registerMany(e){return e.forEach(e=>this.register(e)),this}compose(t){return this.extensions.filter(e=>n(t,e)).sort((e,t)=>(e.priority??0)-(t.priority??0)).reduce((t,n)=>e(t,n),t.base)}};function n(e,t){return!(t.workflow!==e.base.meta.name||t.baseVersion&&t.baseVersion!==e.base.meta.version||t.tenantId&&t.tenantId!==e.tenantId||t.role&&t.role!==e.role||t.device&&t.device!==e.device)}export{t as WorkflowComposer};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { ComposeParams, StepInjection, WorkflowExtension, WorkflowExtensionScope } from "./types.js";
+import { StepTemplateOptions, approvalStepTemplate } from "./templates.js";
+import { applyWorkflowExtension } from "./injector.js";
+import { WorkflowComposer } from "./composer.js";
+import { WorkflowExtensionValidationIssue, validateExtension } from "./validator.js";
+import { mergeExtensions } from "./merger.js";
+export { ComposeParams, StepInjection, StepTemplateOptions, WorkflowComposer, WorkflowExtension, WorkflowExtensionScope, WorkflowExtensionValidationIssue, applyWorkflowExtension, approvalStepTemplate, mergeExtensions, validateExtension };

package/dist/index.js

@@ -0,0 +1 @@
+import{approvalStepTemplate as e}from"./templates.js";import{validateExtension as t}from"./validator.js";import{applyWorkflowExtension as n}from"./injector.js";import{WorkflowComposer as r}from"./composer.js";import{mergeExtensions as i}from"./merger.js";export{r as WorkflowComposer,n as applyWorkflowExtension,e as approvalStepTemplate,i as mergeExtensions,t as validateExtension};

package/dist/injector.d.ts

@@ -0,0 +1,7 @@
+import { WorkflowExtension } from "./types.js";
+import { WorkflowSpec } from "@lssm/lib.contracts/workflow/spec";
+
+//#region src/injector.d.ts
+declare function applyWorkflowExtension(base: WorkflowSpec, extension: WorkflowExtension): WorkflowSpec;
+//#endregion
+export { applyWorkflowExtension };

package/dist/injector.js

@@ -0,0 +1 @@
+import{validateExtension as e}from"./validator.js";function t(t,r){e(r,t);let s=o(t),c=[...s.definition.steps],l=[...s.definition.transitions],u=new Set(r.hiddenSteps??[]);return u.forEach(e=>{let t=c.findIndex(t=>t.id===e);t!==-1&&c.splice(t,1)}),u.size&&(l=l.filter(e=>!u.has(e.from)&&!u.has(e.to))),r.customSteps?.forEach(e=>{n(c,e),i(l,e)}),s.definition.steps=c,s.definition.transitions=a(l),s.meta={...s.meta,version:s.meta.version},s}function n(e,t){let n=r(e,t);if(n===-1)throw Error(`Unable to place injected step "${t.inject.id}"`);e.splice(n,0,{...t.inject})}function r(e,t){if(t.after){let n=e.findIndex(e=>e.id===t.after);return n===-1?-1:n+1}if(t.before){let n=e.findIndex(e=>e.id===t.before);return n===-1?-1:n}return e.length}function i(e,t){t.inject.id&&(t.transitionFrom&&e.push({from:t.transitionFrom,to:t.inject.id,condition:t.when}),t.transitionTo&&e.push({from:t.inject.id,to:t.transitionTo,condition:t.when}))}function a(e){let t=new Set,n=[];return e.forEach(e=>{let r=`${e.from}->${e.to}:${e.condition??``}`;t.has(r)||(t.add(r),n.push(e))}),n}function o(e){return JSON.parse(JSON.stringify(e))}export{t as applyWorkflowExtension};

package/dist/merger.d.ts

@@ -0,0 +1,6 @@
+import { WorkflowExtension } from "./types.js";
+
+//#region src/merger.d.ts
+declare function mergeExtensions(extensions: WorkflowExtension[]): WorkflowExtension[];
+//#endregion
+export { mergeExtensions };

package/dist/merger.js

@@ -0,0 +1 @@
+function e(e){return e.sort((e,t)=>(e.priority??0)-(t.priority??0))}export{e as mergeExtensions};

package/dist/templates.d.ts

@@ -0,0 +1,14 @@
+import { Step, StepAction, StepType } from "@lssm/lib.contracts/workflow/spec";
+
+//#region src/templates.d.ts
+interface StepTemplateOptions {
+  id: string;
+  label: string;
+  type?: StepType;
+  description?: string;
+  action?: StepAction;
+  guardExpression?: string;
+}
+declare function approvalStepTemplate(options: StepTemplateOptions): Step;
+//#endregion
+export { StepTemplateOptions, approvalStepTemplate };

package/dist/templates.js

@@ -0,0 +1 @@
+function e(e){return{id:e.id,label:e.label,type:e.type??`human`,description:e.description??`Tenant-specific approval`,action:e.action,guard:e.guardExpression?{type:`expression`,value:e.guardExpression}:void 0}}export{e as approvalStepTemplate};

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+import { Step, WorkflowSpec } from "@lssm/lib.contracts/workflow/spec";
+
+//#region src/types.d.ts
+interface WorkflowExtensionScope {
+  tenantId?: string;
+  role?: string;
+  device?: string;
+}
+interface StepInjection {
+  id?: string;
+  after?: string;
+  before?: string;
+  inject: Step;
+  when?: string;
+  transitionTo?: string;
+  transitionFrom?: string;
+}
+interface WorkflowExtension extends WorkflowExtensionScope {
+  workflow: string;
+  baseVersion?: number;
+  priority?: number;
+  customSteps?: StepInjection[];
+  hiddenSteps?: string[];
+  metadata?: Record<string, unknown>;
+  annotations?: Record<string, unknown>;
+}
+interface ComposeParams extends WorkflowExtensionScope {
+  base: WorkflowSpec;
+}
+//#endregion
+export { ComposeParams, StepInjection, WorkflowExtension, WorkflowExtensionScope };

package/dist/validator.d.ts

@@ -0,0 +1,11 @@
+import { WorkflowExtension } from "./types.js";
+import { WorkflowSpec } from "@lssm/lib.contracts/workflow/spec";
+
+//#region src/validator.d.ts
+interface WorkflowExtensionValidationIssue {
+  code: string;
+  message: string;
+}
+declare function validateExtension(extension: WorkflowExtension, base: WorkflowSpec): void;
+//#endregion
+export { WorkflowExtensionValidationIssue, validateExtension };

package/dist/validator.js

@@ -0,0 +1 @@
+function e(e,t){let n=[],r=new Set(t.definition.steps.map(e=>e.id));if(e.customSteps?.forEach((e,t)=>{e.inject.id||n.push({code:`workflow.extension.step.id`,message:`customSteps[${t}] is missing an id`}),!e.after&&!e.before&&n.push({code:`workflow.extension.step.anchor`,message:`customSteps[${t}] must set after or before`}),e.after&&!r.has(e.after)&&n.push({code:`workflow.extension.step.after`,message:`customSteps[${t}] references unknown step "${e.after}"`}),e.before&&!r.has(e.before)&&n.push({code:`workflow.extension.step.before`,message:`customSteps[${t}] references unknown step "${e.before}"`})}),e.hiddenSteps?.forEach(e=>{r.has(e)||n.push({code:`workflow.extension.hidden-step`,message:`hidden step "${e}" does not exist`})}),n.length){let t=n.map(e=>`${e.code}: ${e.message}`).join(`; `);throw Error(`Invalid workflow extension for ${e.workflow}: ${t}`)}}export{e as validateExtension};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@lssm/lib.workflow-composer",
+  "version": "0.0.0-canary-20251206160926",
+  "description": "Tenant-aware workflow composition helpers for ContractSpec.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@lssm/lib.contracts": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}