@contractspec/example.workflow-system 1.57.0 → 1.58.0

package/dist/browser/ui/renderers/workflow.markdown.js

@@ -0,0 +1,227 @@
+// src/ui/renderers/workflow.markdown.ts
+var mockWorkflowDefinitions = [
+  {
+    id: "wf-1",
+    name: "Purchase Approval",
+    type: "APPROVAL",
+    steps: [
+      {
+        id: "s1",
+        name: "Manager Review",
+        order: 1,
+        requiredRoles: ["manager"]
+      },
+      {
+        id: "s2",
+        name: "Finance Review",
+        order: 2,
+        requiredRoles: ["finance"]
+      },
+      { id: "s3", name: "Final Approval", order: 3, requiredRoles: ["admin"] }
+    ],
+    status: "ACTIVE"
+  },
+  {
+    id: "wf-2",
+    name: "Leave Request",
+    type: "APPROVAL",
+    steps: [
+      {
+        id: "s1",
+        name: "Supervisor Approval",
+        order: 1,
+        requiredRoles: ["supervisor"]
+      },
+      { id: "s2", name: "HR Review", order: 2, requiredRoles: ["hr"] }
+    ],
+    status: "ACTIVE"
+  },
+  {
+    id: "wf-3",
+    name: "Document Review",
+    type: "SEQUENTIAL",
+    steps: [
+      { id: "s1", name: "Author Review", order: 1, requiredRoles: ["author"] },
+      { id: "s2", name: "Peer Review", order: 2, requiredRoles: ["reviewer"] },
+      { id: "s3", name: "Publish", order: 3, requiredRoles: ["publisher"] }
+    ],
+    status: "DRAFT"
+  }
+];
+var mockWorkflowInstances = [
+  {
+    id: "inst-1",
+    definitionId: "wf-1",
+    definitionName: "Purchase Approval",
+    status: "IN_PROGRESS",
+    currentStepId: "s2",
+    startedAt: "2024-01-15T10:00:00Z",
+    requestedBy: "John Doe"
+  },
+  {
+    id: "inst-2",
+    definitionId: "wf-1",
+    definitionName: "Purchase Approval",
+    status: "COMPLETED",
+    currentStepId: null,
+    startedAt: "2024-01-10T09:00:00Z",
+    completedAt: "2024-01-12T14:00:00Z",
+    requestedBy: "Jane Smith"
+  },
+  {
+    id: "inst-3",
+    definitionId: "wf-2",
+    definitionName: "Leave Request",
+    status: "PENDING",
+    currentStepId: "s1",
+    startedAt: "2024-01-16T08:00:00Z",
+    requestedBy: "Bob Wilson"
+  }
+];
+var workflowDashboardMarkdownRenderer = {
+  target: "markdown",
+  render: async (desc) => {
+    if (desc.source.type !== "component" || desc.source.componentKey !== "WorkflowDashboard") {
+      throw new Error("workflowDashboardMarkdownRenderer: not WorkflowDashboard");
+    }
+    const definitions = mockWorkflowDefinitions;
+    const instances = mockWorkflowInstances;
+    const activeDefinitions = definitions.filter((d) => d.status === "ACTIVE");
+    const pendingInstances = instances.filter((i) => i.status === "PENDING");
+    const inProgressInstances = instances.filter((i) => i.status === "IN_PROGRESS");
+    const completedInstances = instances.filter((i) => i.status === "COMPLETED");
+    const lines = [
+      "# Workflow Dashboard",
+      "",
+      "> Workflow and approval management overview",
+      "",
+      "## Summary",
+      "",
+      "| Metric | Value |",
+      "|--------|-------|",
+      `| Active Workflows | ${activeDefinitions.length} |`,
+      `| Pending Approvals | ${pendingInstances.length} |`,
+      `| In Progress | ${inProgressInstances.length} |`,
+      `| Completed | ${completedInstances.length} |`,
+      "",
+      "## Active Workflow Definitions",
+      ""
+    ];
+    if (activeDefinitions.length === 0) {
+      lines.push("_No active workflow definitions._");
+    } else {
+      lines.push("| Name | Type | Steps | Status |");
+      lines.push("|------|------|-------|--------|");
+      for (const def of activeDefinitions) {
+        lines.push(`| ${def.name} | ${def.type} | ${def.steps.length} | ${def.status} |`);
+      }
+    }
+    lines.push("");
+    lines.push("## Recent Instances");
+    lines.push("");
+    if (instances.length === 0) {
+      lines.push("_No workflow instances._");
+    } else {
+      lines.push("| Workflow | Requested By | Status | Started |");
+      lines.push("|----------|--------------|--------|---------|");
+      for (const inst of instances.slice(0, 10)) {
+        const startedDate = new Date(inst.startedAt).toLocaleDateString();
+        lines.push(`| ${inst.definitionName} | ${inst.requestedBy} | ${inst.status} | ${startedDate} |`);
+      }
+    }
+    return {
+      mimeType: "text/markdown",
+      body: lines.join(`
+`)
+    };
+  }
+};
+var workflowDefinitionListMarkdownRenderer = {
+  target: "markdown",
+  render: async (desc) => {
+    if (desc.source.type !== "component" || desc.source.componentKey !== "WorkflowDefinitionList") {
+      throw new Error("workflowDefinitionListMarkdownRenderer: not WorkflowDefinitionList");
+    }
+    const definitions = mockWorkflowDefinitions;
+    const lines = [
+      "# Workflow Definitions",
+      "",
+      "> Configure automated approval and process workflows",
+      ""
+    ];
+    for (const def of definitions) {
+      lines.push(`## ${def.name}`);
+      lines.push("");
+      lines.push(`**Type:** ${def.type} | **Status:** ${def.status}`);
+      lines.push("");
+      lines.push("### Steps");
+      lines.push("");
+      for (const step of def.steps) {
+        lines.push(`${step.order}. **${step.name}** - Roles: ${step.requiredRoles.join(", ")}`);
+      }
+      lines.push("");
+    }
+    return {
+      mimeType: "text/markdown",
+      body: lines.join(`
+`)
+    };
+  }
+};
+var workflowInstanceDetailMarkdownRenderer = {
+  target: "markdown",
+  render: async (desc) => {
+    if (desc.source.type !== "component" || desc.source.componentKey !== "WorkflowInstanceDetail") {
+      throw new Error("workflowInstanceDetailMarkdownRenderer: not WorkflowInstanceDetail");
+    }
+    const instance = mockWorkflowInstances[0];
+    if (!instance) {
+      return {
+        mimeType: "text/markdown",
+        body: `# No Workflow Instances
+
+No workflow instances available.`
+      };
+    }
+    const definition = mockWorkflowDefinitions.find((d) => d.id === instance.definitionId);
+    const lines = [
+      `# Workflow: ${instance.definitionName}`,
+      "",
+      `**Instance ID:** ${instance.id}`,
+      `**Status:** ${instance.status}`,
+      `**Requested By:** ${instance.requestedBy}`,
+      `**Started:** ${new Date(instance.startedAt).toLocaleString()}`,
+      "",
+      "## Steps Progress",
+      ""
+    ];
+    if (definition) {
+      for (const step of definition.steps) {
+        const isCurrent = step.id === instance.currentStepId;
+        const isCompleted = definition.steps.indexOf(step) < definition.steps.findIndex((s) => s.id === instance.currentStepId);
+        let status = "⬜ Pending";
+        if (isCompleted)
+          status = "✅ Completed";
+        if (isCurrent)
+          status = "\uD83D\uDD04 In Progress";
+        lines.push(`- ${status} **${step.name}**`);
+      }
+    }
+    lines.push("");
+    lines.push("## Actions");
+    lines.push("");
+    lines.push("- **Approve** - Move to next step");
+    lines.push("- **Reject** - Reject and return");
+    lines.push("- **Delegate** - Assign to another approver");
+    return {
+      mimeType: "text/markdown",
+      body: lines.join(`
+`)
+    };
+  }
+};
+export {
+  workflowInstanceDetailMarkdownRenderer,
+  workflowDefinitionListMarkdownRenderer,
+  workflowDashboardMarkdownRenderer
+};

package/dist/browser/workflow/index.js

@@ -0,0 +1,21 @@
+export {
+  WorkflowUpdatedEvent,
+  WorkflowStepModel,
+  WorkflowStatusEnum,
+  WorkflowPublishedEvent,
+  WorkflowDefinitionModel,
+  WorkflowCreatedEvent,
+  UpdateWorkflowInputModel,
+  UpdateWorkflowContract,
+  TriggerTypeEnum,
+  StepTypeEnum,
+  StepAddedEvent,
+  PublishWorkflowContract,
+  ListWorkflowsContract,
+  GetWorkflowContract,
+  CreateWorkflowInputModel,
+  CreateWorkflowContract,
+  ApprovalModeEnum,
+  AddStepInputModel,
+  AddStepContract
+};

package/dist/browser/workflow/workflow.enum.js

@@ -0,0 +1,36 @@
+// src/workflow/workflow.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var WorkflowStatusEnum = defineEnum("WorkflowStatus", [
+  "DRAFT",
+  "ACTIVE",
+  "DEPRECATED",
+  "ARCHIVED"
+]);
+var TriggerTypeEnum = defineEnum("WorkflowTriggerType", [
+  "MANUAL",
+  "EVENT",
+  "SCHEDULED",
+  "API"
+]);
+var StepTypeEnum = defineEnum("StepType", [
+  "START",
+  "APPROVAL",
+  "TASK",
+  "CONDITION",
+  "PARALLEL",
+  "WAIT",
+  "ACTION",
+  "END"
+]);
+var ApprovalModeEnum = defineEnum("ApprovalMode", [
+  "ANY",
+  "ALL",
+  "MAJORITY",
+  "SEQUENTIAL"
+]);
+export {
+  WorkflowStatusEnum,
+  TriggerTypeEnum,
+  StepTypeEnum,
+  ApprovalModeEnum
+};

package/dist/browser/workflow/workflow.event.js

@@ -0,0 +1,6 @@
+export {
+  WorkflowUpdatedEvent,
+  WorkflowPublishedEvent,
+  WorkflowCreatedEvent,
+  StepAddedEvent
+};

package/dist/browser/workflow/workflow.handler.js

@@ -0,0 +1,5 @@
+export {
+  handlePublishWorkflow,
+  handleCreateWorkflow,
+  handleAddStep
+};

package/dist/browser/workflow/workflow.operations.js

@@ -0,0 +1,8 @@
+export {
+  UpdateWorkflowContract,
+  PublishWorkflowContract,
+  ListWorkflowsContract,
+  GetWorkflowContract,
+  CreateWorkflowContract,
+  AddStepContract
+};

package/dist/browser/workflow/workflow.schema.js

@@ -0,0 +1,151 @@
+// src/workflow/workflow.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var WorkflowStatusEnum = defineEnum("WorkflowStatus", [
+  "DRAFT",
+  "ACTIVE",
+  "DEPRECATED",
+  "ARCHIVED"
+]);
+var TriggerTypeEnum = defineEnum("WorkflowTriggerType", [
+  "MANUAL",
+  "EVENT",
+  "SCHEDULED",
+  "API"
+]);
+var StepTypeEnum = defineEnum("StepType", [
+  "START",
+  "APPROVAL",
+  "TASK",
+  "CONDITION",
+  "PARALLEL",
+  "WAIT",
+  "ACTION",
+  "END"
+]);
+var ApprovalModeEnum = defineEnum("ApprovalMode", [
+  "ANY",
+  "ALL",
+  "MAJORITY",
+  "SEQUENTIAL"
+]);
+
+// src/workflow/workflow.schema.ts
+import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+var WorkflowStepModel = defineSchemaModel({
+  name: "WorkflowStepModel",
+  description: "A step in a workflow definition",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    type: { type: StepTypeEnum, isOptional: false },
+    position: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    transitions: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    approvalMode: { type: ApprovalModeEnum, isOptional: true },
+    approverRoles: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var WorkflowDefinitionModel = defineSchemaModel({
+  name: "WorkflowDefinitionModel",
+  description: "A workflow definition",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    version: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: WorkflowStatusEnum, isOptional: false },
+    triggerType: { type: TriggerTypeEnum, isOptional: false },
+    initialStepId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    featureFlagKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    organizationId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    steps: { type: WorkflowStepModel, isArray: true, isOptional: true }
+  }
+});
+var CreateWorkflowInputModel = defineSchemaModel({
+  name: "CreateWorkflowInput",
+  description: "Input for creating a workflow definition",
+  fields: {
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    key: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    triggerType: { type: TriggerTypeEnum, isOptional: true },
+    triggerConfig: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    featureFlagKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    settings: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var UpdateWorkflowInputModel = defineSchemaModel({
+  name: "UpdateWorkflowInput",
+  description: "Input for updating a workflow definition",
+  fields: {
+    workflowId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    triggerType: { type: TriggerTypeEnum, isOptional: true },
+    triggerConfig: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    featureFlagKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    settings: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var AddStepInputModel = defineSchemaModel({
+  name: "AddStepInput",
+  description: "Input for adding a step to a workflow",
+  fields: {
+    workflowId: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    key: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    type: { type: StepTypeEnum, isOptional: false },
+    position: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    transitions: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    approvalMode: { type: ApprovalModeEnum, isOptional: true },
+    approverRoles: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    },
+    approverUserIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    },
+    timeoutSeconds: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    slaSeconds: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+export {
+  WorkflowStepModel,
+  WorkflowDefinitionModel,
+  UpdateWorkflowInputModel,
+  CreateWorkflowInputModel,
+  AddStepInputModel
+};

package/dist/browser/workflow-system.capability.js

@@ -0,0 +1,5 @@
+export {
+  WorkflowCapability,
+  StateMachineCapability,
+  ApprovalCapability
+};

package/dist/browser/workflow-system.feature.js

@@ -0,0 +1,3 @@
+export {
+  WorkflowSystemFeature
+};

package/dist/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './workflow-system.docblock';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC"}

package/dist/docs/index.js

@@ -1 +1,104 @@
-import "./workflow-system.docblock.js";
+// @bun
+// src/docs/workflow-system.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var workflowSystemDocBlocks = [
+  {
+    id: "docs.examples.workflow-system",
+    title: "Workflow / Approval System",
+    summary: "Reference app showing state-machine driven approvals with RBAC, audit trail, notifications, and jobs.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/workflow-system",
+    tags: ["workflow", "approval", "state-machine", "rbac"],
+    body: `## Entities
+
+- WorkflowDefinition, WorkflowStep, WorkflowInstance, Approval.
+- State machine expressed in \`src/state-machine\` with allowed transitions and role gates.
+
+## Contracts
+
+- \`workflow.definition.create\`, \`workflow.instance.start\`, \`workflow.step.approve\`, \`workflow.step.reject\`, \`workflow.instance.comment\`.
+- Policies enforced via Identity/RBAC module; audit trail emitted on each transition.
+
+## Events & Jobs
+
+- Emits \`workflow.instance.started\`, \`workflow.step.completed\`, \`workflow.step.rejected\`, \`workflow.instance.finished\`.
+- Reminder jobs can be scheduled via @contractspec/lib.jobs for pending approvals.
+
+## UI / Presentations
+
+- Dashboard, definition list/editor, instance detail with action buttons derived from state machine.
+- Templates registered in Studio Template Registry under \`workflow-system\`.
+
+## Notes
+
+- Keep transitions declarative to enable safe regeneration; role guards live in spec.
+- Use Notification Center for approval requests and outcomes; attach files via Files module if needed.
+`
+  },
+  {
+    id: "docs.examples.workflow-system.goal",
+    title: "Workflow System \u2014 Goal",
+    summary: "Why the workflow/approval template exists and outcomes it targets.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/goal",
+    tags: ["workflow", "goal"],
+    body: `## Why it matters
+- Provides a regenerable, role-gated approval engine using declarative state machines.
+- Keeps workflow rules consistent across UI/API/events with auditability.
+
+## Business/Product goal
+- Enable approvals with clear transitions, reminders, and notifications.
+- Support compliance via Audit Trail and Feature Flags for staged changes.
+
+## Success criteria
+- State changes are declarative and regenerate cleanly.
+- Every transition emits auditable events and respects RBAC guards.`
+  },
+  {
+    id: "docs.examples.workflow-system.usage",
+    title: "Workflow System \u2014 Usage",
+    summary: "How to configure workflows, transitions, and regenerate safely.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/usage",
+    tags: ["workflow", "usage"],
+    body: `## Setup
+1) Define WorkflowDefinition steps and allowed transitions with role gates in spec.
+2) Seed sample workflows/instances (if provided) or create via UI; enable reminders via Jobs.
+
+## Extend & regenerate
+1) Add steps/transitions or approval conditions in spec; include PII paths if comments/files.
+2) Regenerate to sync UI action buttons and API/state machine behavior.
+3) Use Feature Flags to trial new transitions or escalation rules.
+
+## Guardrails
+- Emit events for every transition; log to Audit Trail.
+- Use Notifications for approvals/rejections; schedule reminders for pending steps.
+- Keep transitions declarative; avoid imperative branching in handlers.`
+  },
+  {
+    id: "docs.examples.workflow-system.constraints",
+    title: "Workflow System \u2014 Constraints & Safety",
+    summary: "Internal guardrails for state machines, RBAC, and regeneration semantics.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/workflow-system/constraints",
+    tags: ["workflow", "constraints", "internal"],
+    body: `## Constraints
+- State machine (steps/transitions) must stay declarative in spec; no hidden code paths.
+- Events to emit: instance.started, step.completed/rejected, instance.finished.
+- Regeneration must not change approval logic without explicit spec diff.
+
+## PII & Compliance
+- Mark any PII in comments/attachments; redact in markdown/JSON.
+- Ensure Audit Trail captures every transition; Notifications for approvals/rejections.
+
+## Verification
+- Add fixtures for transition changes and role gates.
+- Validate reminders (Jobs) stay aligned with pending states after regeneration.
+- Use Feature Flags for new transitions/escalation rules; default safe/off.`
+  }
+];
+registerDocBlocks(workflowSystemDocBlocks);

package/dist/docs/workflow-system.docblock.d.ts

@@ -1 +1,2 @@
-export { };
+export {};
+//# sourceMappingURL=workflow-system.docblock.d.ts.map

package/dist/docs/workflow-system.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-system.docblock.d.ts","sourceRoot":"","sources":["../../src/docs/workflow-system.docblock.ts"],"names":[],"mappings":""}