@prorigo/protrak-forge 0.3.4 → 0.4.0

package/data/CLAUDE.md.template

@@ -72,7 +72,7 @@ These are **Protrak-specific gotchas you cannot catch by reading the code**. Alw
 
 ### Understanding the workspace:
 - `list_protrak_schema_elements` (optionally with `kind`: `type`, `attribute`, `lifecycle`,
-  `relation_type`) catalogs what's defined.
+  `relation_type`, `rule`) catalogs what's defined.
 - `read_protrak_schema_element` (with `kind` and `name`) returns the full JSON of any one
   element — for `kind='type'` you get the resolved schema with attributes, lifecycle, and
   relations hydrated.
@@ -124,6 +124,102 @@ These are **Protrak-specific gotchas you cannot catch by reading the code**. Alw
 - Return `ProgramResult { IsSuccess = false, Message = "..." }` to block operations in
   Pre-triggers (style rule).
 
+## How to write notification templates
+
+Notification templates define the email/push content sent by Protrak. They use **Razor syntax**
+(`@Model.*`), not `{{}}` placeholders.
+
+### Writing a new notification template:
+1. Call `get_protrak_notification_context(type_name?)` — returns existing templates and the full
+   `@Model` variable reference for all target types.
+2. Write the Razor HTML body using `@Model.*` variables.
+3. Call `generate_protrak_notification_template(name='<Title> Body', target='PromoteNotification', email_html='<Razor HTML>')`.
+4. Call again for the subject: `generate_protrak_notification_template(name='<Title> Subject', target='PromoteNotification', email_html='<subject line>')`.
+
+```
+get_protrak_notification_context(type_name='Invoice')
+# ... agent writes the Razor HTML ...
+generate_protrak_notification_template(name='Invoice Sent Body', target='PromoteNotification', email_html='<p>Hi @Model.AttributeValues["Manager"].UserValues[0].UserName,...</p>')
+generate_protrak_notification_template(name='Invoice Sent Subject', target='PromoteNotification', email_html='Invoice @Model.InstanceName has been sent')
+```
+
+Each call creates `NotificationTemplates/<name>.json` (metadata) and `NotificationTemplates/<name>.html`
+(email body). `hashCode` is left empty — Protrak recomputes it on import.
+
+Valid `target` values: `PromoteNotification`, `AccountNotification`, `WorkflowNotification`,
+`WorkflowTaskNotification`.
+
+## How to write Rules
+
+Rules express attribute-filter logic used by display conditions, conditional formatting,
+dependent picklists, and Access Policy. They are file-based: `Rules/<Name>.json`.
+
+### Writing a new rule:
+1. Call `get_protrak_rule_context(type_name?)` — returns the supported-conditions-per-
+   attribute-type table, value-less / range conditions, dynamic-value formats
+   (`@Instance.X`, `@User.X`, `$StartOfToday(±Nd)`), date mnemonics, basic-attribute map,
+   existing rule names, and canonical examples. Pass `type_name` to include that type's
+   resolved attribute schema (rules are not type-bound, but most rules reference one type).
+2. Translate the natural-language intent into `attribute_filter_groups[]`. Each group has
+   an `operator` joining it to the **next** group; each condition has an `operator` joining
+   it to the **next** condition in the same group. The final group / condition uses `None`.
+3. Instance-context `attribute_name` must exist in `Attributes/` or be a basic attribute
+   (`Name`, `State`, `Created`, `Creator`, `Modifier`, `Lifecycle`, ...). User-context names
+   refer to user-profile attributes (not workspace-validated). For `UserRoles`, omit
+   `attribute_name`.
+4. Call `generate_protrak_rule(name, attribute_filter_groups, error_message?)`. Pass
+   `error_message` **only** when the rule will be selected as a Type's Access Policy —
+   it appears in the access-denied response.
+
+### Attaching a rule to a layout / type / picklist:
+Call `attach_protrak_rule(usage, rule_name, ...)`. One polymorphic tool covers five shapes:
+
+- `usage='display_condition'`, `target_kind='layout_template'`, `target_name`, `widget_id?`
+  — appends to the widget's `displayConditions: string[]`.
+- `usage='display_condition'`, `target_kind='form'`, `target_name`, `attribute_name`,
+  `container_id?` — sets the **singular** `displayCondition` on the form field.
+- `usage='format_condition'`, `target_name=<ViewLayout>`, `attribute_name`, `section_name?`,
+  `widget_name?`, `style`, `order_index?` — appends `{ rule:{name}, orderIndex, style }`
+  to the ViewLayout field's `formatConditions`.
+- `usage='conditional_formatting'`, `target_kind='type_widget'|'form'`, `target_name`,
+  `attribute_name`, `style`, `order_index?` — appends `{ ruleName, orderIndex, style }`
+  to the column/field's `conditionalFormatting`.
+- `usage='access_policy'`, `type_name` — sets `accessPolicyRule` on `Types/<name>.json`.
+- `usage='dependent_picklist'`, `attribute_name=<PicklistAttr>`, `option_name` — sets the
+  `rule` field on that picklist option.
+
+Style is structured: `{ background_color?: '#RRGGBB', fore_color?: '#RRGGBB',
+font_style?: ('Bold'|'Italic'|'Underline'|'Strikethrough')[] }`. The tool serializes it
+to the comma-terminated CSS-string the SPA evaluator expects (`backgroundColor`, `color`,
+`fontWeight`, `fontStyle`, `textDecorationLine`). Both `Underline` and `Strikethrough`
+collapse into a single `textDecorationLine` token.
+
+```
+get_protrak_rule_context(type_name='ProjectAllocation')
+# ... agent picks attributes, condition, dynamic values ...
+generate_protrak_rule(
+  name='OverdueAllocation',
+  attribute_filter_groups=[{
+    operator: 'None',
+    conditions: [{
+      attribute_context: 'Instance',
+      attribute_name: 'AllocationEndDate',
+      condition: 'LessThanOrEqual',
+      first_value: { value_type: 'Static', value: '$StartOfToday()' },
+      operator: 'None',
+    }],
+  }],
+)
+attach_protrak_rule(
+  usage='conditional_formatting',
+  rule_name='OverdueAllocation',
+  target_kind='type_widget',
+  target_name='ProjectActiveAllocationsRelationWidget',
+  attribute_name='AllocationEndDate',
+  style={ background_color: '#ee8bb6' },
+)
+```
+
 ## Project structure
 - `Types/` — entity type JSON definitions
 - `Attributes/` — attribute JSON definitions
@@ -131,3 +227,8 @@ These are **Protrak-specific gotchas you cannot catch by reading the code**. Alw
 - `Programs/` — C# program source + JSON metadata (paired files; use
   `generate_protrak_program` to keep them in sync)
 - `RelationTypes/` — relation definitions between types
+- `NotificationTemplates/` — notification template files (paired `.json` + `.html`; use
+  `generate_protrak_notification_template` to keep them in sync)
+- `Rules/` — business-rule JSON definitions (attribute filter groups). Use
+  `generate_protrak_rule` to author and `attach_protrak_rule` to wire into layouts /
+  type access policies / picklist dependencies.

package/data/patterns/index.md

@@ -37,7 +37,6 @@ instance.SetPicklistAttributeValue("Status", "Active");
 | [Create and Connect Child Instances](./create-and-connect-pattern.md) | Create related instances and link them                                                                   | PostCreate, PostConnect                       |
 | [Cascade Promote](./cascade-promote-pattern.md)                       | Propagate a lifecycle transition to related instances; aggregate-all-approvers check                     | PromoteActionCommand, PostCreate, Scheduler   |
 | [Query and Filter](./query-filter-pattern.md)                         | Query instances using InstanceQuery and RelatedInstanceQuery                                             | All program types                             |
-| [Aggregate Related Instances](./aggregate-related-instances.md)       | Parent → related fan-out + roll-up; uses `RelatedQueryBuilder.Select(...)` to avoid N+1 GetInstance calls | Scheduler, PostCreate, PromoteActionCommand   |
 | [Invoke Common Program](./invoke-common-program.md)                   | Call reusable logic encapsulated in a Common Program                                                     | All program types                             |
 | [Manage Instance Access](./manage-instance-access-pattern.md)         | Grant or revoke per-instance user access; create users; manage roles                                     | PostConnect, PostCreate, PromoteActionCommand |
 | [Delete Related Data](./delete-related-data-pattern.md)               | Delete or unlink child instances before parent deletion                                                  | PreDelete                                     |
@@ -94,16 +93,6 @@ Scheduler
   → [Cascade Promote] — promote when all approvers are done
 ```
 
-### Scheduler: Roll up an aggregate from related instances onto the parent
-
-```
-Scheduler
-  → [Query and Filter] — pick the parent set (e.g. all Active Projects)
-  → [Aggregate Related Instances] — for each parent, fetch related rows with
-    RelatedQueryBuilder.Select(...) in a SINGLE call, sum/count/aggregate, and
-    write back via InstanceBuilder.ForUpdate + UpdateInstanceAsync.
-```
-
 ---
 
 ## Service Injection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prorigo/protrak-forge",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Protrak domain context for coding agents — MCP server for GitHub Copilot, Claude, and Cursor",
   "bin": {
     "protrak-forge": "./bin/protrak-forge.js"

package/data/patterns/attribute-copy.md

@@ -1,89 +0,0 @@
-# Attribute Copy / Auto-populate Pattern
-
-## When to Use
-Use this pattern to automatically copy or compute attribute values when an instance is created or updated. Common uses:
-- Copy a field from a parent/related instance
-- Auto-fill a date field (e.g. start date = today)
-- Compute a derived value from other attributes
-- Propagate changes from parent to children
-
-## Program Types
-Applies to: `PostCreate`, `PostUpdate`, `PreCreate`, `PreUpdate`
-
-## Services Used
-- `IInstanceService` — to fetch and update instances
-- `IQueryBuilderService` — to filter related instances
-
-## Code Example: Copy on Create
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using System;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class AutoPopulateStartDate : IPostCreateTriggerProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-
-        public async Task RunAsync(Guid instanceId)
-        {
-            var instance = await InstanceService.GetInstanceAsync(
-                instanceId, new[] { "StartDate" });
-
-            if (instance == null) return;
-
-            instance.Attributes = new[]
-            {
-                new Attribute { Name = "StartDate", Value = DateTime.UtcNow.ToString("o") }
-            };
-
-            await InstanceService.UpdateInstanceAsync(instance, null);
-        }
-    }
-}
-```
-
-## Code Example: Copy from Related Instance
-
-```csharp
-public class CopyCustomerRegionToProject : IPostCreateTriggerProgramAsync
-{
-    public IInstanceService InstanceService { get; set; }
-
-    public async Task RunAsync(Guid instanceId)
-    {
-        var project = await InstanceService.GetInstanceAsync(
-            instanceId, new[] { "Customer", "Region" });
-
-        if (project == null) return;
-
-        // Get related customer ID from reference attribute
-        var customerIds = project.Attributes?
-            .FirstOrDefault(a => a.Name == "Customer")?.ReferenceValues;
-
-        if (customerIds == null || customerIds.Length == 0) return;
-
-        var customer = await InstanceService.GetInstanceAsync(
-            customerIds[0], new[] { "Region" });
-
-        var region = customer?.Attributes?
-            .FirstOrDefault(a => a.Name == "Region")?.Value?.ToString();
-
-        if (string.IsNullOrEmpty(region)) return;
-
-        project.Attributes = new[]
-        {
-            new Attribute { Name = "Region", Value = region }
-        };
-        await InstanceService.UpdateInstanceAsync(project, null);
-    }
-}
-```
-
-## Key Rules
-- Use `PostCreate`/`PostUpdate` (not `PreCreate`) when you need the instance ID to perform updates
-- Null-check `ReferenceValues` before accessing related instances
-- Pass `null` for `lastModified` in `UpdateInstanceAsync` to skip optimistic concurrency check
-- Only set the attributes you want to change in `instance.Attributes`

package/data/patterns/batch-update.md

@@ -1,72 +0,0 @@
-# Batch Update Pattern
-
-## When to Use
-Use this pattern to update multiple related instances efficiently in parallel. Common uses:
-- Update all child instances when a parent changes
-- Recalculate a field across all instances of a type
-- Cascade attribute changes
-
-## Program Types
-Applies to: `PostUpdate`, `PromoteActionCommand`, `Scheduler`
-
-## Services Used
-- `IInstanceService` — to fetch and update instances in bulk
-- `IQueryBuilderService` — to filter instances for batch processing
-
-## Code Example
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using System;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class UpdateAllTaskPrioritiesOnProjectChange : IPostUpdateTriggerProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-        public IQueryBuilderService QueryBuilderService { get; set; }
-
-        public async Task<ProgramResult> RunAsync(Guid instanceId)
-        {
-            var project = await InstanceService.GetInstanceAsync(
-                instanceId, new[] { "Priority" });
-
-            var priority = project?.Attributes?
-                .FirstOrDefault(a => a.Name == "Priority")?.Value?.ToString();
-
-            if (string.IsNullOrEmpty(priority))
-                return new ProgramResult { IsSuccess = true };
-
-            // Find all tasks for this project
-            var filter = QueryBuilderService.CreateRelatedInstanceFilterExpression(
-                "Project", instanceId);
-            var query = new InstanceQuery { TypeName = "Task", Filter = filter, Take = 500 };
-            var tasks = await InstanceService.GetInstancesAsync(query);
-
-            if (tasks?.Data == null || tasks.Data.Length == 0)
-                return new ProgramResult { IsSuccess = true };
-
-            // Update all tasks in parallel
-            var updates = tasks.Data.Select(async task =>
-            {
-                task.Attributes = new[]
-                {
-                    new Attribute { Name = "Priority", Value = priority }
-                };
-                await InstanceService.UpdateInstanceAsync(task, null);
-            });
-
-            await Task.WhenAll(updates);
-            return new ProgramResult { IsSuccess = true };
-        }
-    }
-}
-```
-
-## Key Rules
-- Use `Task.WhenAll` for parallel updates — much faster than sequential `await` in a loop
-- Limit batch size with `Take` (max 500 recommended)
-- Pass `null` for `lastModified` in `UpdateInstanceAsync` to skip concurrency check
-- Only include changed attributes in `instance.Attributes` to avoid overwriting other fields

package/data/patterns/reference-navigation.md

@@ -1,76 +0,0 @@
-# Reference Navigation Pattern
-
-## When to Use
-Use this pattern to navigate from one instance to a related instance via a reference attribute. Common uses:
-- Get the parent project of a task
-- Get the customer linked to an order
-- Follow a chain of relations (task → project → customer)
-
-## Program Types
-Applies to: `PreCreate`, `PostCreate`, `PreUpdate`, `PostUpdate`, `PromoteActionCommand`
-
-## Services Used
-- `IInstanceService` — to fetch related instances by GUID
-
-## Code Example
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using System;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class ValidateEquipmentStatus : IPreCreateTriggerProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-
-        public async Task<ProgramResult> RunAsync(Instance instance)
-        {
-            // Navigate: Process → Equipment (via reference attribute)
-            var equipmentIds = instance.Attributes?
-                .FirstOrDefault(a => a.Name == "Equipment")?.ReferenceValues;
-
-            if (equipmentIds == null || equipmentIds.Length == 0)
-                return new ProgramResult { IsSuccess = false, Message = "Equipment is required." };
-
-            var equipment = await InstanceService.GetInstanceAsync(
-                equipmentIds[0], new[] { "Status", "AvailableFrom" });
-
-            if (equipment == null)
-                return new ProgramResult { IsSuccess = false, Message = "Equipment not found." };
-
-            var status = equipment.Attributes?
-                .FirstOrDefault(a => a.Name == "Status")?.Value?.ToString();
-
-            if (status != "Available")
-            {
-                return new ProgramResult
-                {
-                    IsSuccess = false,
-                    Message = $"Equipment is not available (current status: {status})."
-                };
-            }
-
-            return new ProgramResult { IsSuccess = true };
-        }
-    }
-}
-```
-
-## Key Rules
-- Reference attributes expose related instance IDs via `ReferenceValues` (array of Guids)
-- Always null-check `ReferenceValues` and verify length before accessing index 0
-- Fetch only the attributes you need in the `GetInstanceAsync` attributes parameter
-- For multi-valued references, iterate or use `ReferenceValues[0]` for the first
-
-## When NOT to use this pattern (anti-pattern callout)
-
-This pattern is for **navigating to a single related instance via a Reference attribute**. It is **not** the right approach when you have many related instances and want to read attributes from each.
-
-> ❌ **DO NOT** call `GetRelatedInstancesAsync` to get a list of related ids and then call `GetInstanceAsync` once per id to fetch their attributes. That's an N+1 round-trip — one extra DB hit per related instance.
->
-> ✅ **DO** use `RelatedQueryBuilder.Select(attr1, attr2, ...)` so the related instances come back **with attributes populated in a single call**. Read the values off the `RelatedInstance` directly with `GetDateAttributeValue`, `GetTextAttributeValue`, etc.
-
-For collection-level fan-out (sums, counts, rollups), see [Aggregate Related Instances](./aggregate-related-instances.md).

package/data/patterns/report.md

@@ -1,73 +0,0 @@
-# Report Program Pattern
-
-## When to Use
-Use this pattern to generate dynamic reports from Protrak data. Report programs provide both the data and the configuration (columns, charts) for the report UI.
-
-## Program Types
-Applies to: `Report`
-
-## Services Used
-- `IInstanceService` — to query data for the report
-- `IQueryBuilderService` — to filter data
-
-## Code Example
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class EquipmentUtilizationReport : IReportProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-        public IQueryBuilderService QueryBuilderService { get; set; }
-
-        public async Task<ReportData> GetReportDataAsync(ReportQuery query)
-        {
-            var instanceQuery = new InstanceQuery
-            {
-                TypeName = "Equipment",
-                Take = 500
-            };
-
-            var equipment = await InstanceService.GetInstancesAsync(instanceQuery);
-
-            var rows = equipment?.Data?.Select(e => new ReportRow
-            {
-                Values = new Dictionary<string, object>
-                {
-                    ["Name"] = e.Attributes?.FirstOrDefault(a => a.Name == "Name")?.Value ?? "",
-                    ["Status"] = e.Attributes?.FirstOrDefault(a => a.Name == "Status")?.Value ?? "",
-                    ["UtilizationHours"] = e.Attributes?.FirstOrDefault(a => a.Name == "UtilizationHours")?.Value ?? 0,
-                }
-            }).ToList() ?? new List<ReportRow>();
-
-            return new ReportData { Rows = rows };
-        }
-
-        public async Task<ReportConfig> GetReportConfigAsync()
-        {
-            return new ReportConfig
-            {
-                Title = "Equipment Utilization",
-                Columns = new[]
-                {
-                    new ReportColumn { Name = "Name", DisplayName = "Equipment Name" },
-                    new ReportColumn { Name = "Status", DisplayName = "Status" },
-                    new ReportColumn { Name = "UtilizationHours", DisplayName = "Hours Used" },
-                }
-            };
-        }
-    }
-}
-```
-
-## Key Rules
-- Implement both `GetReportDataAsync` and `GetReportConfigAsync`
-- `ReportQuery` may contain filter parameters set by the user in the UI
-- Return an empty `ReportData` (not null) if no data matches
-- Keep queries efficient — reports run on demand, avoid slow full-table scans

package/data/patterns/scheduler.md

@@ -1,77 +0,0 @@
-# Scheduler Program Pattern
-
-## When to Use
-Use this pattern for background jobs that run on a schedule (cron). Common uses:
-- Send daily reminder notifications
-- Auto-close overdue instances
-- Compute/recalculate aggregate values from related instances (see [Aggregate Related Instances](./aggregate-related-instances.md) for the canonical roll-up shape)
-- Sync data with external systems
-
-## Program Types
-Applies to: `Scheduler`
-
-## Services Used
-- `IInstanceService` — to query and update instances
-- `INotificationService` — to send scheduled notifications
-- `IQueryBuilderService` — to filter instances
-
-## Code Example
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using System;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class SendDailyOverdueReminders : ISchedulerProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-        public INotificationService NotificationService { get; set; }
-        public IQueryBuilderService QueryBuilderService { get; set; }
-
-        public async Task RunAsync()
-        {
-            var today = DateTime.UtcNow.Date;
-            var filter = QueryBuilderService.CreateAttributeFilterExpression(
-                "DueDate", today.ToString("yyyy-MM-dd"), FilterOperator.LessThanOrEqual);
-
-            var query = new InstanceQuery
-            {
-                TypeName = "WorkOrder",
-                Filter = filter,
-                StateName = "Open",
-                Take = 500
-            };
-
-            var overdueItems = await InstanceService.GetInstancesAsync(query);
-            if (overdueItems?.Data == null || overdueItems.Data.Length == 0)
-                return;
-
-            foreach (var item in overdueItems.Data)
-            {
-                var assignee = item.Attributes?
-                    .FirstOrDefault(a => a.Name == "AssignedEngineer")?.Value?.ToString();
-
-                if (string.IsNullOrEmpty(assignee)) continue;
-
-                await NotificationService.SendNotificationAsync(
-                    new[] { assignee },
-                    "Overdue Work Order",
-                    $"Work Order {item.TrackingId} is overdue. Please take action.",
-                    item.Id
-                );
-            }
-        }
-    }
-}
-```
-
-## Key Rules
-- The `Run()` / `RunAsync()` method takes no parameters
-- Use `ISchedulerProgramAsync` for async operations
-- Avoid long-running loops — use `Take` to limit batch sizes
-- Log or notify on errors so failures are visible
-- Consider idempotency: what happens if the scheduler runs twice?
-- When the scheduler walks parent → related instances and reads attributes off each child, use `RelatedQueryBuilder.Select(...)` in a single `GetRelatedInstancesAsync` call. **Do not** fan out to `GetInstanceAsync` per related id — that's an N+1 anti-pattern. See [Aggregate Related Instances](./aggregate-related-instances.md).