@tailor-platform/erp-kit 0.0.1 → 0.1.1

package/package.json

@@ -1,10 +1,69 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tailor-platform/erp-kit",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+  "version": "0.1.1",
+  "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
+  "license": "MIT",
+  "bin": {
+    "erp-kit": "./dist/cli.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "LICENSE",
+    "schemas",
+    "skills",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./module": "./src/module.ts",
+    "./app": "./src/app.ts",
+    "./testing": "./src/testing.ts"
+  },
+  "dependencies": {
+    "@jackchuka/mdschema": "^0.12.3",
+    "@mockoon/commons": "^9.0.0",
+    "@mockoon/commons-server": "^9.0.0",
+    "chalk": "^5.4.1",
+    "fast-glob": "^3.3.3",
+    "politty": "^0.4.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
+    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/sdk": "1.17.1",
+    "@types/node": "^25.1.0",
+    "eslint": "9.39.2",
+    "kysely": "0.28.10",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.0",
+    "@tailor-platform/eslint-config": "0.0.1"
+  },
+  "peerDependencies": {
+    "@tailor-platform/function-kysely-tailordb": "0.1.3",
+    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/sdk": "1.17.1",
+    "kysely": "0.28.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsup",
+    "generate": "pnpm generate:primitives && pnpm generate:user-management",
+    "generate:primitives": "cd src/modules/primitives && tailor-sdk generate",
+    "generate:user-management": "cd src/modules/user-management && tailor-sdk generate",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache --fix .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:primitives": "vitest run src/modules/primitives/",
+    "test:user-management": "vitest run src/modules/user-management/",
+    "test:shared": "vitest run src/modules/shared/",
+    "mock:start": "node dist/cli.js mock start",
+    "mock:validate": "node dist/cli.js mock validate"
+  }
+}

package/schemas/app-compose/actors.yml

@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "slug(filename) == slug(heading)"
+    children:
+      # Brief context for authorization decisions - REQUIRED
+      - heading: "## Overview"
+        description: |
+          1-2 sentences: who this actor is and their authority level.
+          Not a job description — context for authorization decisions.
+
+      # What flows this actor participates in - REQUIRED
+      - heading: "## Authorized Business Flows"
+        description: |
+          Business flows this actor participates in.
+          Format: [Flow Name](../business-flow/<flow>/README.md) — role
+          Roles: initiator, approver, viewer
+          Add conditions inline when needed, e.g. (< $1000)
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 2

package/schemas/app-compose/business-flow.yml

@@ -0,0 +1,50 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# SPEC TIER 3 (primary navigation structure)
+# Business flow file: business-flow/<flow-name>/README.md
+# Stories are nested: business-flow/<flow-name>/story/<actor>--<story-name>.md
+# Defines end-to-end business processes
+
+structure:
+  - heading:
+      pattern: "# [a-zA-Z0-9_\\-]+"
+    children:
+      # Brief description of this business flow - REQUIRED
+      - heading: "## Overview"
+
+      # Who initiates and participates in this flow - REQUIRED
+      - heading: "## Actors Involved"
+        description: |
+          List actors that participate in this business flow.
+          Link to actor docs. ie. ../../actors/<actor-name>.md
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Diagram representing this flow - REQUIRED
+      - heading: "## Flow Diagram"
+        code_blocks:
+          - min: 1
+            lang: mermaid
+
+      # Links to user stories nested under this flow - REQUIRED
+      - heading: "## Stories"
+        description: |
+          Link to story docs in ./story/ folder that comprise this business flow.
+          Format: ./story/<actor>--<story-name>.md
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/requirements.yml

@@ -0,0 +1,33 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading: "# README"
+    children:
+      # What this application does - REQUIRED
+      - heading: "## Overview"
+
+      # Target industry and domain knowledge - REQUIRED
+      - heading: "## Industry Context"
+        children:
+          - heading: "### Target Industry"
+            description: |
+              The industry sector this application serves
+              (e.g., Manufacturing, Retail, Healthcare, Finance, Logistics)
+
+          - heading: "### Domain Terminology"
+            description: |
+              Key terms and concepts specific to this domain
+            lists:
+              - min: 0
+                type: unordered
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/resolver.yml

@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# IMPLEMENTATION TIER
+# Resolver file: resolver/<resolverName>.md
+# Documents GraphQL operations (queries, mutations, subscriptions)
+
+# TODO: check against resolver implementations via CI/CD pipeline
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    description: |
+      Document the GraphQL operation - mainly mutations.
+    children:
+      # What this Resolver does - REQUIRED
+      - heading: "## Overview"
+
+      # Which modules and what parts are used - REQUIRED
+      - heading: "## Modules Commands Used"
+        description: |
+          List modules and specific features/commands used from each.
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Error Handling
+      - heading: "## Exception Handling"
+        optional: true
+        description: |
+          Document possible errors returned by this operation.
+        tables:
+          - min: 1
+            required_headers:
+              - Error Code
+              - Description
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/app-compose/screen.yml

@@ -0,0 +1,81 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# IMPLEMENTATION TIER
+# Screen file: screen/<screenName>.md
+# TODO: should check existance of screens via CI/CD pipeline
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this screen does - REQUIRED
+      - heading: "## Overview"
+
+      # Screen Type
+      - heading: "## Screen Type"
+        description: |
+          Specify the type of screen (e.g., Form, ListView, DetailView).
+        required_text:
+          - pattern: "(Form|ListView|DetailView)"
+            regex: true
+        children:
+          - heading: "### Form Details"
+            description: |
+              If the screen is a Form provide details about the form fields.
+            optional: true
+            children:
+              - heading: "#### Input Fields"
+                tables:
+                  - min: 1
+                    required_headers:
+                      - Field Name
+                      - Field Type
+                      - Required (Yes/No)
+          - heading: "### ListView Details"
+            description: |
+              If the screen is a ListView provide details about the table displayed.
+            optional: true
+            children:
+              - heading: "#### Required Columns"
+                tables:
+                  - min: 1
+                    required_headers:
+                      - Column Name
+                      - Hideable (Yes/No)
+                      - Sort-able (Yes/No)
+                      - Filter-able (Yes/No)
+                      - Searchable (Yes/No)
+          - heading: "### DetailView Details"
+            description: |
+              If the screen is a DetailView provide actions available on this screen.
+            optional: true
+            children:
+              - heading: "#### Displayed Fields"
+                lists:
+                  - min: 1
+                    type: unordered
+                    min_items: 1
+              - heading: "#### Available Actions"
+                lists:
+                  - min: 1
+                    type: unordered
+                    min_items: 1
+
+      - heading: "## Access Control"
+        description: |
+          Specify the actors that have access to this screen.
+          Use links to actor documents (e.g., [buyer-administrator](../actors/buyer-administrator.md)).
+        lists:
+          - min: 1
+            type: unordered
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/app-compose/story.yml

@@ -0,0 +1,67 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+# SPEC TIER 3 (nested under business-flow)
+# Story filename format: <actor>--<story-name>.md
+# Example: sales-manager--create-sales-order.md
+# Heading must match story name (after --): # Create Sales Order
+# Defines WHAT users accomplish (the requirement)
+
+structure:
+  - heading:
+      # Validates: slug of text after "--" matches heading
+      # trimPrefix removes "actor--" prefix, leaving story name
+      # e.g., "sales-manager--create-sales-order" -> "create-sales-order" -> matches "# Create Sales Order"
+      expr: 'slug(trimPrefix(filename, "^[a-z-]+--")) == slug(heading)'
+    description: |
+      User story defining a specific requirement within a business flow.
+      The name of the story should start with the actor followed by `--` and the story name.
+    children:
+      - heading: "## User Story"
+        description: |
+          Define the user story in the format:
+          As a [role], I want [goal], so that [benefit].
+
+      # Diagram representing this story - REQUIRED
+      - heading: "## Story Diagram"
+        description: |
+          Mermaid sequence diagram showing user interactions with screens.
+          Focus on actors, UI screens, and business outcomes.
+          Avoid technical details (APIs, databases, endpoints).
+        code_blocks:
+          - min: 1
+            lang: mermaid
+
+      # Scenario Patterns, including edge cases - REQUIRED
+      - heading: "## Scenario Patterns"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Test cases must be covered - REQUIRED
+      - heading: "## Test Cases"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Screens that implement this story - REQUIRED
+      # Enables M:N relationship between stories and screens
+      - heading: "## Screens"
+        description: |
+          Link to screen docs that implement this story's UI.
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3

package/schemas/module/command.yml

@@ -0,0 +1,52 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this command does - REQUIRED
+      - heading: "## Overview"
+
+      # Business rules - REQUIRED
+      # Rules, constraints, and validation logic
+      - heading: "## Business Rules"
+        allow_additional: true
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # How it works - REQUIRED
+      # Step-by-step flow or workflow
+      - heading: "## Process Flow"
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # External dependencies - OPTIONAL
+      # Commands from other modules that this command depends on
+      - heading: "## External Dependencies"
+        description: "e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Error handling - REQUIRED
+      # How errors are handled
+      - heading: "## Error Scenarios"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/module/feature.yml

@@ -0,0 +1,58 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "slug(filename) == slug(heading)"
+    children:
+      # ===================
+      # REQUIRED SECTIONS
+      # ===================
+
+      # What this feature does - REQUIRED
+      - heading: "## Overview"
+
+      # Business context - REQUIRED
+      # Why this feature exists and what problem it solves
+      - heading: "## Business Purpose"
+
+      # How it works - REQUIRED
+      # Process flow
+      - heading: "## Process Flow"
+        description: |
+          Describe the end-to-end process flow of this feature.
+          If multiple flows exist, split them into different diagrams and explain each.
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # Scenario Patterns, including edge cases - REQUIRED
+      - heading: "## Scenario Patterns"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Test cases must be covered - REQUIRED
+      - heading: "## Test Cases"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Links to any related references - REQUIRED
+      - heading: "## Reference Links"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/schemas/module/model.yml

@@ -0,0 +1,70 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      - heading: "## Description"
+      - heading: "## Domain Model Definitions"
+        children:
+          - heading: "### Model type"
+            description: |
+              Model type must be one of Standard, AppendOnly, or Stateful
+               - AppendOnly: AppendOnly model where records can be added but not modified or deleted
+               - Stateful: Stateful model with state transitions
+            required_text:
+              - pattern: "(Standard|AppendOnly|Stateful)"
+                regex: true
+            children:
+              - heading: "#### State Transitions"
+                description: |
+                  Define the state transitions for Stateful models.
+                  Commands should correspond to those defined in the "### Command Definitions" section.
+                optional: true
+                code_blocks:
+                  - lang: mermaid
+                    min: 1
+
+          - heading: "### Command Definitions"
+            description: |
+              Definitions of commands this domain model supports.
+              Should match with the commands defined in modules/**/docs/commands/*.md and link to them.
+              Commands heavily influenced by Model type:
+                - Standard: Create, Update, Delete (Some model may choose to not implement Delete)
+                - AppendOnly: Create
+                - Stateful: Create, State Transition Commands
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
+          - heading: "### Models"
+            description: |
+              Actual database models necessary for the domain model.
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+
+          - heading: "### Invariants"
+            description: |
+              Invariants that must always hold true for this domain model.
+              - Assume the model boundary (the unit within which consistency is guaranteed) is already defined, and list what must always be true within that boundary.
+              - Express each invariant as part of the concept’s definition (what makes the concept valid), not as an implementation detail (no DB constraints, computed columns, etc.).
+              - If a constraint depends on lifecycle state, write it explicitly as a state-scoped invariant (state x condition that must always hold).
+
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
+          - heading: "### Relationships"
+
+# Global link validation settings
+links:
+  validate_internal: true # check anchor links (#section-name)
+  validate_files: true # check relative file links (./other.md)
+# Global heading validation rules
+heading_rules:
+  no_skip_levels: true # disallow skipping levels (e.g., h1 -> h3)
+  unique: true # all headings must be unique
+  max_depth: 4 # maximum heading depth (1-6)

package/schemas/module/module.yml

@@ -0,0 +1,50 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading: "# README"
+    children:
+      # ===================
+      # REQUIRED SECTIONS
+      # ===================
+
+      # What this module does - REQUIRED
+      - heading: "## Overview"
+
+      # Main capabilities - REQUIRED
+      - heading: "## Key Features"
+        lists:
+          - min: 1
+            type: unordered
+            min_items: 1
+
+      # Module scope - REQUIRED
+      - heading: "## Module Scope"
+        children:
+          - heading: "### In Scope"
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+          - heading: "### Out of Scope"
+            lists:
+              - min: 1
+                type: unordered
+                min_items: 1
+
+      # Module dependencies - REQUIRED
+      - heading: "## Module Dependencies"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 3