@dimescheduler/setup 0.1.3 → 0.11.4

package/README.md

@@ -1,404 +1,546 @@
-# @dimescheduler/setup
-
-CLI tool to validate, compile, and deploy Dime.Scheduler configurations.
-
-## Installation
-
-```bash
-npm install -g @dimescheduler/setup
-```
-
-Or use with npx:
-
-```bash
-npx @dimescheduler/setup <command>
-```
-
-## Commands
-
-### `validate`
-
-Validate a configuration file against the Dime.Scheduler DSL schema.
-
-```bash
-dimescheduler-setup validate <file>
-```
-
-**Arguments:**
-- `<file>` - Path to the configuration file (.json5 or .json)
-
-**Options:**
-- `--json` - Output results as JSON
-
-**Examples:**
-
-```bash
-# Validate a configuration file
-dimescheduler-setup validate my-profile.json5
-
-# Get validation results as JSON (useful for CI/CD)
-dimescheduler-setup validate my-profile.json5 --json
-```
-
-**Exit codes:**
-- `0` - Configuration is valid
-- `1` - Configuration has errors
-
----
-
-### `compile`
-
-Compile a JSON5 configuration to API-ready JSON format.
-
-```bash
-dimescheduler-setup compile <file> [options]
-```
-
-**Arguments:**
-- `<file>` - Path to the configuration file (.json5)
-
-**Options:**
-- `-o, --output <dir>` - Output directory (default: same as input file)
-- `--stdout` - Output to stdout instead of writing to a file
-- `--skip-validation` - Skip validation before compiling
-
-**Examples:**
-
-```bash
-# Compile to JSON (creates my-profile.json in the same directory)
-dimescheduler-setup compile my-profile.json5
-
-# Compile to a specific directory
-dimescheduler-setup compile my-profile.json5 -o ./dist
-
-# Output to stdout (useful for piping)
-dimescheduler-setup compile my-profile.json5 --stdout
-
-# Skip validation (not recommended)
-dimescheduler-setup compile my-profile.json5 --skip-validation
-```
-
----
-
-### `deploy`
-
-Deploy a configuration directly to a Dime.Scheduler instance.
-
-```bash
-dimescheduler-setup deploy <file> --api-key <key> --env <environment> [options]
-```
-
-**Arguments:**
-- `<file>` - Path to the configuration file (.json5 or .json)
-
-**Options:**
-- `--api-key <key>` - API key for authentication (required, or set `DS_API_KEY` env var)
-- `--env <environment>` - Environment: `production`, `sandbox`, or `test` (required)
-- `--skip-validation` - Skip validation before deploying
-- `--json` - Output results as JSON
-- `--dry-run` - Validate and compile without actually deploying
-- `-y, --yes` - Skip confirmation prompt
-
-**Examples:**
-
-```bash
-# Deploy to sandbox (shows confirmation prompt)
-dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox
-
-# Deploy to production with confirmation
-dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env production
-
-# Skip confirmation prompt (for CI/CD)
-dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox -y
-
-# Use environment variable for API key
-export DS_API_KEY=YOUR_API_KEY
-dimescheduler-setup deploy my-profile.json5 --env sandbox
-
-# Dry run (validate and compile only)
-dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox --dry-run
-
-# Get results as JSON (useful for CI/CD, skips confirmation)
-dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox --json
-```
-
-**Exit codes:**
-- `0` - Deployment successful (or cancelled by user)
-- `1` - Validation or compilation error
-- `2` - Deployment failed (API error)
-
-## Configuration Format
-
-Configuration files use [JSON5](https://json5.org/) format, which supports:
-- Comments (`//` and `/* */`)
-- Trailing commas
-- Unquoted keys
-- Single-quoted strings
-
-### Example Configuration
-
-```json5
-{
-  name: "Service Planning",
-  code: "SERVICE_PLANNING",
-
-  // Optional metadata
-  owner: "admin@example.com",
-  notificationEmail: "notifications@example.com",
-
-  // Visual theme
-  theme: {
-    color: "blue",
-    scheme: "sltl"
-  },
-
-  // Sharing settings
-  shared: {
-    global: false,
-    userGroup: "Planners"
-  },
-
-  // Route calculation settings
-  route: {
-    profile: "default",
-    calculateRoutes: true,
-    showSequenceIndicators: true,
-    unitOfDistance: "km"  // or "mi"
-  },
-
-  // Planning board settings
-  planning: {
-    snapInterval: { mode: "1hour" },  // or "15min", "30min", "day", or 1-10
-    range: { mode: "week" },          // or "day", "month", "year"
-    start: { mode: "today" },         // or "yesterday", "week", "month"
-    hours: { start: 8, end: 18 }
-  },
-
-  // Workspace layout (GoldenLayout structure)
-  workspace: [
-    {
-      type: "row",
-      content: [
-        {
-          type: "column",
-          width: 30,
-          content: [
-            {
-              type: "stack",
-              content: [
-                {
-                  type: "component",
-                  component: "openTasks",
-                  title: "Open Tasks",
-                  id: "openTasks1",
-                  layouts: [{
-                    id: "openTasks1",
-                    code: "OPEN_TASKS",
-                    name: "Default",
-                    default: true,
-                    columns: [
-                      { property: "Job.JobNo" },
-                      { property: "TaskNo" }
-                    ],
-                    sorters: [
-                      { property: "Job.JobNo", direction: "ASC" }
-                    ]
-                  }]
-                }
-              ]
-            }
-          ]
-        },
-        {
-          type: "column",
-          width: 70,
-          content: [
-            {
-              type: "stack",
-              content: [
-                {
-                  type: "component",
-                  component: "planningBoard",
-                  title: "Planning Board",
-                  layouts: [{
-                    id: "planningBoard1",
-                    code: "SCHEDULER",
-                    name: "Default View",
-                    default: true,
-                    viewPreset: "week",
-                    columns: [
-                      { property: "DisplayName" },
-                      { property: "Department" }
-                    ],
-                    grouper: {
-                      property: "ResourceType.DisplayName",
-                      direction: "ASC",
-                      id: "ResourceType.DisplayName"
-                    }
-                  }]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    }
-  ],
-
-  // Optional: User definitions
-  users: [
-    {
-      name: "John Doe",
-      email: "john@example.com",
-      language: "en",
-      timeZone: "America/New_York",
-      profiles: [{ name: "SERVICE_PLANNING", default: true }],
-      roles: ["Administrator"],
-      timeMarkers: ["IN PROCESS"],
-      categories: ["HARDWARE"],
-      filterValues: ["East"]
-    }
-  ]
-}
-```
-
-### Available Components
-
-| Component | Description |
-|-----------|-------------|
-| `openTasks` | Grid showing unplanned tasks |
-| `planningBoard` | Main scheduling board |
-| `map` | Map view |
-| `indicators` | Category indicators |
-| `resourceFilters` | Resource filter panel |
-| `plannedTasks` | Grid showing planned tasks |
-| `details` | Details/properties panel |
-| `datePicker` | Calendar date picker |
-| `gantt` | Gantt chart view |
-| `capacity` | Capacity planning view |
-| `routeSequence` | Route sequence grid |
-| `notifications` | Notifications panel |
-
-### Layout Configuration
-
-Components can include `layouts` for configuring grid columns, sorting, filtering, and grouping:
-
-```json5
-layouts: [{
-  id: "myGrid1",
-  code: "MY_LAYOUT",
-  name: "My Custom Layout",
-  default: true,
-
-  // Column configuration
-  columns: [
-    { property: "Job.JobNo", width: 100 },
-    { property: "Description" }
-  ],
-
-  // Sorting
-  sorters: [
-    { property: "Job.JobNo", direction: "ASC" },
-    { property: "TaskNo", direction: "DESC" }
-  ],
-
-  // Filtering
-  filters: [
-    { property: "Status", operator: "eq", value: "Active" }
-  ],
-
-  // Grouping
-  grouper: {
-    property: "Category",
-    direction: "ASC",
-    id: "Category"
-  },
-
-  // Grid settings
-  pageSize: 50,
-  rowHeight: "2rows",  // "1row", "2rows", "3rows", "4rows", or pixel value
-  viewPreset: "week",  // "day", "week", "workWeek", "month"
-  lockedGridWidth: "30%",
-  fitToScreen: false,
-
-  // Sharing (optional)
-  shared: {
-    public: true,
-    userGroup: "Planners"
-  }
-}]
-```
-
-## CI/CD Integration
-
-### GitHub Actions Example
-
-```yaml
-name: Deploy Configuration
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'configs/*.json5'
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install CLI
-        run: npm install -g @dimescheduler/setup
-
-      - name: Validate
-        run: dimescheduler-setup validate configs/my-profile.json5
-
-      - name: Deploy
-        run: dimescheduler-setup deploy configs/my-profile.json5 --env sandbox --json
-        env:
-          DS_API_KEY: ${{ secrets.DS_API_KEY }}
-```
-
-### Azure DevOps Example
-
-```yaml
-trigger:
-  branches:
-    include:
-      - main
-  paths:
-    include:
-      - configs/*.json5
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '20.x'
-
-  - script: npm install -g @dimescheduler/setup
-    displayName: 'Install CLI'
-
-  - script: dimescheduler-setup validate configs/my-profile.json5
-    displayName: 'Validate Configuration'
-
-  - script: dimescheduler-setup deploy configs/my-profile.json5 --env sandbox -y
-    displayName: 'Deploy Configuration'
-    env:
-      DS_API_KEY: $(DS_API_KEY)
-```
-
-## Requirements
-
-- Node.js 18 or higher
-
-## License
-
-MIT
+# @dimescheduler/setup
+
+CLI tool to validate, compile, and deploy Dime.Scheduler configurations.
+
+## Installation
+
+```bash
+npm install -g @dimescheduler/setup
+```
+
+Or use with npx:
+
+```bash
+npx @dimescheduler/setup <command>
+```
+
+## Commands
+
+### `validate`
+
+Validate a configuration file against the Dime.Scheduler DSL schema.
+
+```bash
+dimescheduler-setup validate <file>
+```
+
+**Arguments:**
+- `<file>` - Path to the configuration file (.json5 or .json)
+
+**Options:**
+- `--json` - Output results as JSON
+
+**Examples:**
+
+```bash
+# Validate a configuration file
+dimescheduler-setup validate my-profile.json5
+
+# Get validation results as JSON (useful for CI/CD)
+dimescheduler-setup validate my-profile.json5 --json
+```
+
+**Exit codes:**
+- `0` - Configuration is valid
+- `1` - Configuration has errors
+
+---
+
+### `compile`
+
+Compile a JSON5 configuration to API-ready JSON format.
+
+```bash
+dimescheduler-setup compile <file> [options]
+```
+
+**Arguments:**
+- `<file>` - Path to the configuration file (.json5)
+
+**Options:**
+- `-o, --output <dir>` - Output directory (default: same as input file)
+- `--stdout` - Output to stdout instead of writing to a file
+- `--skip-validation` - Skip validation before compiling
+
+**Examples:**
+
+```bash
+# Compile to JSON (creates my-profile.json in the same directory)
+dimescheduler-setup compile my-profile.json5
+
+# Compile to a specific directory
+dimescheduler-setup compile my-profile.json5 -o ./dist
+
+# Output to stdout (useful for piping)
+dimescheduler-setup compile my-profile.json5 --stdout
+
+# Skip validation (not recommended)
+dimescheduler-setup compile my-profile.json5 --skip-validation
+```
+
+---
+
+### `deploy`
+
+Deploy a configuration directly to a Dime.Scheduler instance.
+
+```bash
+dimescheduler-setup deploy <file> --api-key <key> --env <environment> [options]
+```
+
+**Arguments:**
+- `<file>` - Path to the configuration file (.json5 or .json)
+
+**Options:**
+- `--api-key <key>` - API key for authentication (required, or set `DS_API_KEY` env var)
+- `--env <environment>` - Environment: `production`, `sandbox`, or `test` (required)
+- `--skip-validation` - Skip validation before deploying
+- `--json` - Output results as JSON
+- `--dry-run` - Validate and compile without actually deploying
+- `-y, --yes` - Skip confirmation prompt
+
+**Examples:**
+
+```bash
+# Deploy to sandbox (shows confirmation prompt)
+dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox
+
+# Deploy to production with confirmation
+dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env production
+
+# Skip confirmation prompt (for CI/CD)
+dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox -y
+
+# Use environment variable for API key
+export DS_API_KEY=YOUR_API_KEY
+dimescheduler-setup deploy my-profile.json5 --env sandbox
+
+# Dry run (validate and compile only)
+dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox --dry-run
+
+# Get results as JSON (useful for CI/CD, skips confirmation)
+dimescheduler-setup deploy my-profile.json5 --api-key YOUR_API_KEY --env sandbox --json
+```
+
+**Exit codes:**
+- `0` - Deployment successful (or cancelled by user)
+- `1` - Validation or compilation error
+- `2` - Deployment failed (API error)
+
+## Configuration Format
+
+Configuration files use [JSON5](https://json5.org/) format, which supports:
+- Comments (`//` and `/* */`)
+- Trailing commas
+- Unquoted keys
+- Single-quoted strings
+
+### Example Configuration
+
+```json5
+{
+  type: "bundle",
+  name: "Field Service Complete Package",
+  version: "1.0.0",
+
+  // Owner and notification email apply to all documents in the bundle
+  owner: "admin@yourdomain.com",
+  notificationEmail: "admin@yourdomain.com",
+
+  // Array of DSL documents to deploy together
+  documents: [
+    // Profile document - defines the workspace layout and settings
+    {
+      type: "profile",
+      payload: {
+        name: "Field Service Planning",
+        code: "FIELD_SERVICE",
+
+        theme: {
+          color: "blue",
+          scheme: "sltl",
+        },
+
+        shared: {
+          global: false,
+          userGroup: "Planners",
+        },
+
+        route: {
+          profile: "car",
+          calculateRoutes: true,
+          showSequenceIndicators: true,
+          unitOfDistance: "km",
+        },
+
+        planning: {
+          snapInterval: "1hour",
+          range: { mode: "week" },
+          start: { mode: "startOfWeek" },
+          hours: { start: 7, end: 18 },
+        },
+
+        // Workspace layout
+        workspace: [
+          {
+            type: "row",
+            content: [
+              {
+                type: "column",
+                width: 25,
+                content: [
+                  {
+                    type: "stack",
+                    content: [
+                      {
+                        type: "component",
+                        component: "openTasks",
+                        title: "Open Tasks",
+                        id: "tasks",
+                        layoutRef: "OPEN_TASKS_DEFAULT",
+                      },
+                    ],
+                  },
+                  {
+                    type: "component",
+                    component: "resourceFilters",
+                    title: "Filters",
+                    id: "filters",
+                  },
+                ],
+              },
+              {
+                type: "column",
+                width: 55,
+                content: [
+                  {
+                    type: "component",
+                    component: "planningBoard",
+                    title: "Planning Board",
+                    id: "scheduler",
+                    layoutRef: "SCHEDULER_DEFAULT",
+                  },
+                ],
+              },
+              {
+                type: "column",
+                width: 20,
+                content: [
+                  {
+                    type: "stack",
+                    content: [
+                      {
+                        type: "component",
+                        component: "details",
+                        title: "Details",
+                        id: "details",
+                      },
+                      {
+                        type: "component",
+                        component: "map",
+                        title: "Map",
+                        id: "map",
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    },
+
+    // Users document - defines users and their permissions
+    {
+      type: "users",
+      payload: [
+        {
+          name: "Planning Manager",
+          email: "manager@yourdomain.com",
+          language: "en",
+          timeZone: "Europe/Brussels",
+          roles: ["Administrator"],
+          profiles: [
+            { name: "FIELD_SERVICE", default: true },
+          ],
+        },
+        {
+          name: "Field Planner",
+          email: "planner@yourdomain.com",
+          language: "en",
+          timeZone: "Europe/Brussels",
+          roles: ["Planner"],
+          profiles: [
+            { name: "FIELD_SERVICE", default: true },
+          ],
+        },
+        {
+          name: "Dispatcher",
+          email: "dispatcher@yourdomain.com",
+          language: "nl",
+          timeZone: "Europe/Brussels",
+          roles: ["Planner"],
+          profiles: [
+            { name: "FIELD_SERVICE", default: true },
+          ],
+          filterValues: ["Dispatch"],
+        },
+      ],
+    },
+
+    // Layouts document - all layouts referenced by components
+    {
+      type: "layouts",
+      payload: [
+        // Default layout for open tasks grid
+        {
+          context: "unplannedTasksGrid",
+          code: "OPEN_TASKS_DEFAULT",
+          name: "Default View",
+          default: true,
+          columns: [
+            { property: "SourceApp" },
+            { property: "SourceType" },
+            { property: "JobNo" },
+            { property: "TaskNo" },
+            { property: "ShortDescription" },
+            { property: "RequestedStart" },
+            { property: "RequestedEnd" },
+          ],
+          sorters: [
+            { property: "RequestedStart", direction: "ASC" },
+          ],
+          pageSize: "50",
+        },
+        // Default layout for scheduler
+        {
+          context: "scheduler",
+          code: "SCHEDULER_DEFAULT",
+          name: "Default",
+          default: true,
+          viewPreset: "week",
+          rowHeight: "2rows",
+          resourcesGridWidth: "20%",
+          columns: [
+            { property: "ResourceNo" },
+            { property: "ResourceName" },
+          ],
+        },
+        // Shared compact tasks view
+        {
+          context: "unplannedTasksGrid",
+          code: "COMPACT_TASKS",
+          name: "Compact View",
+          columns: [
+            { property: "JobNo" },
+            { property: "ShortDescription" },
+            { property: "RequestedStart" },
+          ],
+          sorters: [
+            { property: "RequestedStart", direction: "ASC" },
+          ],
+          pageSize: "100",
+          shared: {
+            public: true,
+          },
+        },
+        // Shared detailed tasks view
+        {
+          context: "unplannedTasksGrid",
+          code: "DETAILED_TASKS",
+          name: "Detailed View",
+          columns: [
+            { property: "SourceApp" },
+            { property: "SourceType" },
+            { property: "JobNo" },
+            { property: "TaskNo" },
+            { property: "ShortDescription" },
+            { property: "Description" },
+            { property: "RequestedStart" },
+            { property: "RequestedEnd" },
+            { property: "Importance" },
+            { property: "Category" },
+            { property: "TimeMarker" },
+          ],
+          sorters: [
+            { property: "Importance", direction: "DESC" },
+            { property: "RequestedStart", direction: "ASC" },
+          ],
+          grouper: {
+            property: "Category",
+            direction: "ASC",
+          },
+          pageSize: "50",
+          shared: {
+            public: true,
+          },
+        },
+        // Monthly scheduler view for managers
+        {
+          context: "scheduler",
+          code: "MONTHLY_VIEW",
+          name: "Monthly Overview",
+          viewPreset: "month",
+          rowHeight: "1row",
+          resourcesGridWidth: "15%",
+          columns: [
+            { property: "ResourceName" },
+          ],
+          shared: {
+            userGroup: "Managers",
+          },
+        },
+      ],
+    },
+  ],
+
+  // Merge strategy for handling conflicts when deploying
+  mergeStrategy: {
+    layouts: "append",
+    users: "append",
+    profiles: "last-wins",
+  },
+}
+```
+
+### Available Components
+
+| Component | Description |
+|-----------|-------------|
+| `openTasks` | Grid showing unplanned tasks |
+| `planningBoard` | Main scheduling board |
+| `map` | Map view |
+| `indicators` | Category indicators |
+| `resourceFilters` | Resource filter panel |
+| `plannedTasks` | Grid showing planned tasks |
+| `details` | Details/properties panel |
+| `datePicker` | Calendar date picker |
+| `gantt` | Gantt chart view |
+| `capacity` | Capacity planning view |
+| `routeSequence` | Route sequence grid |
+| `notifications` | Notifications panel |
+
+### Layout Configuration
+
+Components can include `layouts` for configuring grid columns, sorting, filtering, and grouping:
+
+```json5
+layouts: [{
+  id: "myGrid1",
+  code: "MY_LAYOUT",
+  name: "My Custom Layout",
+  default: true,
+
+  // Column configuration
+  columns: [
+    { property: "Job.JobNo", width: 100 },
+    { property: "Description" }
+  ],
+
+  // Sorting
+  sorters: [
+    { property: "Job.JobNo", direction: "ASC" },
+    { property: "TaskNo", direction: "DESC" }
+  ],
+
+  // Filtering
+  filters: [
+    { property: "Status", operator: "eq", value: "Active" }
+  ],
+
+  // Grouping
+  grouper: {
+    property: "Category",
+    direction: "ASC",
+    id: "Category"
+  },
+
+  // Grid settings
+  pageSize: 50,
+  rowHeight: "2rows",  // "1row", "2rows", "3rows", "4rows", or pixel value
+  viewPreset: "week",  // "day", "week", "workWeek", "month"
+  lockedGridWidth: "30%",
+  fitToScreen: false,
+
+  // Sharing (optional)
+  shared: {
+    public: true,
+    userGroup: "Planners"
+  }
+}]
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Deploy Configuration
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'configs/*.json5'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install CLI
+        run: npm install -g @dimescheduler/setup
+
+      - name: Validate
+        run: dimescheduler-setup validate configs/my-profile.json5
+
+      - name: Deploy
+        run: dimescheduler-setup deploy configs/my-profile.json5 --env sandbox --json
+        env:
+          DS_API_KEY: ${{ secrets.DS_API_KEY }}
+```
+
+### Azure DevOps Example
+
+```yaml
+trigger:
+  branches:
+    include:
+      - main
+  paths:
+    include:
+      - configs/*.json5
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '20.x'
+
+  - script: npm install -g @dimescheduler/setup
+    displayName: 'Install CLI'
+
+  - script: dimescheduler-setup validate configs/my-profile.json5
+    displayName: 'Validate Configuration'
+
+  - script: dimescheduler-setup deploy configs/my-profile.json5 --env sandbox -y
+    displayName: 'Deploy Configuration'
+    env:
+      DS_API_KEY: $(DS_API_KEY)
+```
+
+## Requirements
+
+- Node.js 18 or higher
+
+## License
+
+MIT