@prorigo/protrak-forge 0.3.3 → 0.3.4

package/data/CLAUDE.md.template

@@ -7,23 +7,80 @@ that implement Protrak interfaces (PreCreate, PostCreate, PreUpdate, PromoteActi
 
 ## How to write Protrak programs
 
-**ALWAYS use the Protrak Forge MCP tools when working with Protrak programs.**
+Default to the Protrak Forge MCP tools, not the filesystem. The cost-of-skipping table at the end
+of this section makes the trade-off concrete; the workflows below tell you which tools to call.
 
-### Writing a new program:
-1. Call `get_protrak_program_context` with the type name, program type, and description —
-   it returns the type schema, interface contract, relevant patterns, and similar programs
-   in ONE call.
-2. Write the C# program following the interface and patterns returned.
-3. Call `validate_protrak_program` to check for errors before committing.
+### Writing a NEW program:
+1. Call `get_protrak_program_context(type_name, program_type, description)` — returns type
+   schema, C# interface contract, coding patterns, similar programs, and available query
+   definitions in ONE call.
+2. Write the C# source.
+3. Call `validate_protrak_program(code, program_type)` — see "What this catches" below.
+4. Call `generate_protrak_program(program_name, program_type, source)` — writes BOTH
+   `Programs/<name>.cs` AND `Programs/<name>.json` (companion metadata required by Protrak's
+   import flow). **Do NOT use the Write tool here** — you will skip the .json companion and
+   the program will not import.
+
+```
+get_protrak_program_context(type_name='Project', program_type='PreUpdate', description='block status change when invoice unpaid')
+# ... agent writes the C# source ...
+validate_protrak_program(code='<source>', program_type='PreUpdate')
+generate_protrak_program(program_name='ProjectPreUpdate', program_type='PreUpdateTrigger', source='<source>')
+```
+
+### Editing an EXISTING program:
+1. Call `get_protrak_program_context(type_name, program_type, program_name='<ExistingName>')`.
+   Passing `program_name` switches the tool to refactor mode — response includes
+   `existing_source`, `existing_services_used`, `existing_patterns_detected`, and
+   `existing_class_name` alongside the usual schema/interface/patterns context.
+   **One call** — no need to chain `read_protrak_program` separately.
+2. Edit the C# source.
+3. Call `validate_protrak_program(code, program_type)` on the edited source.
+4. Write the edited source back to the existing `Programs/<name>.cs` file. Do NOT call
+   `generate_protrak_program` for refactors — the companion .json already exists.
+
+```
+get_protrak_program_context(type_name='Project', program_type='PreUpdate', program_name='CalculateNextInvoiceDate')
+# ... agent edits existing_source ...
+validate_protrak_program(code='<edited source>', program_type='PreUpdate')
+# Write edited source to existing_file_path
+```
+
+### What `validate_protrak_program` catches (and what you skip if you don't run it):
+
+| Check                         | What breaks if you ship it                       |
+| ----------------------------- | ------------------------------------------------ |
+| `.Result` / `.Wait()`         | Deadlock under Protrak's async context           |
+| `async void`                  | Exceptions escape silently                       |
+| Service as private/readonly   | Protrak DI requires PUBLIC PROPERTIES — won't inject |
+| Missing interface             | PreCreate without `IPreCreateTriggerProgramAsync<T>` — Protrak can't bind it |
+| `*Async()` without `await`    | Silent fire-and-forget                           |
+| Service not declared as prop  | Runtime null-ref on first use                    |
+| Missing namespace             | Protrak import rejects the file                  |
+
+These are **Protrak-specific gotchas you cannot catch by reading the code**. Always run
+`validate_protrak_program` after writing or editing.
+
+### Cost of skipping the MCP tools:
+
+| Skip                          | What you miss                                                  |
+| ----------------------------- | -------------------------------------------------------------- |
+| `get_protrak_program_context` | Wrong interface, wrong service injection, wrong query patterns |
+| Refactor mode (`program_name`)| Re-derive existing source from disk; miss `services_used` and `patterns_detected` |
+| `validate_protrak_program`    | Deadlocks, async-void bugs, DI shape mismatches in production  |
+| `generate_protrak_program`    | No companion `.json` — Protrak won't import the program        |
 
 ### Understanding the workspace:
-- Call `list_protrak_schema_elements` (optionally with `kind`: `type`, `attribute`,
-  `lifecycle`, or `relation_type`) to catalog what's defined.
-- Call `read_protrak_schema_element` (with `kind` and `name`) for the full JSON of any one
-  element — for `kind='type'` you get the resolved schema with attributes, lifecycle and
+- `list_protrak_schema_elements` (optionally with `kind`: `type`, `attribute`, `lifecycle`,
+  `relation_type`) 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.
-- Call `list_protrak_programs` for the program catalog; call `search_protrak_knowledge`
-  with `scope='programs'` for relevance-ranked search by description.
+- `list_protrak_programs` lists all programs; `read_protrak_program(program_name)` returns
+  source + metadata for one (but for refactor work, prefer `get_protrak_program_context`
+  with `program_name` — it returns source AND full context together).
+- `search_protrak_knowledge(query, scope)` runs relevance-ranked search across patterns,
+  C# API docs, and workspace programs.
 
 ### Scaffolding schema elements (Types, Lifecycles, Attributes, RelationTypes):
 - For a brand-new entity, call `scaffold_protrak_entity` once with the type name, the
@@ -49,17 +106,28 @@ that implement Protrak interfaces (PreCreate, PostCreate, PreUpdate, PromoteActi
 - All schema names must be PascalCase. Aliases for `attribute_type`: `Number`→`Numeric`,
   `File`→`Attachment`.
 
-### Key Protrak rules:
-- Services are **public properties**, never constructor parameters
-- Always null-check attributes: `instance.Attributes?["Name"]?.Value`
-- Use typed accessors: `GetTextAttributeValue`, `GetDateAttributeValue`, `GetPicklistAttributeValue`
-- Use `SetAttributeValue(name, AttributeType, value)` to write attributes
-- Prefer async interface variants (`RunAsync` not `Run`)
-- Return `ProgramResult { IsSuccess = false, Message = "..." }` to block operations in Pre-triggers
+### Key Protrak rules (each cross-references a `validate_protrak_program` check):
+- Services are **public properties**, never constructor parameters — checked by
+  `service_as_public_property`.
+- Implement the exact program-type interface — checked by `interface_compliance`.
+- Prefer async interface variants (`RunAsync` not `Run`); never call `.Result` / `.Wait()`
+  — checked by `no_dot_result`.
+- Never write `async void` — checked by `no_async_void`.
+- `await` or `return` every `*Async()` call — checked by `missing_await`.
+- Declare every service used as a public property — checked by `undeclared_service`.
+- Declare a `namespace` — checked by `missing_namespace`.
+- Always null-check attributes: `instance.Attributes?["Name"]?.Value` (style rule, not
+  validated by static analysis).
+- Use typed accessors: `GetTextAttributeValue`, `GetDateAttributeValue`,
+  `GetPicklistAttributeValue` (style rule).
+- Use `SetAttributeValue(name, AttributeType, value)` to write attributes (style rule).
+- Return `ProgramResult { IsSuccess = false, Message = "..." }` to block operations in
+  Pre-triggers (style rule).
 
 ## Project structure
 - `Types/` — entity type JSON definitions
 - `Attributes/` — attribute JSON definitions
 - `Lifecycles/` — lifecycle state machine definitions
-- `Programs/` — C# program source + JSON metadata
+- `Programs/` — C# program source + JSON metadata (paired files; use
+  `generate_protrak_program` to keep them in sync)
 - `RelationTypes/` — relation definitions between types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prorigo/protrak-forge",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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/aggregate-related-instances.md

@@ -1,140 +0,0 @@
-
-# Aggregate Related Instances Pattern
-
-## When to Use
-Use this pattern whenever a parent instance needs a value computed from its related child instances. Common uses:
-- Sum/total an attribute across related records (consumed effort, total cost, hours logged)
-- Count related instances by state (open subtasks, overdue items)
-- Roll up a max/min/latest date from related records
-- Calculate completion percentages from related deliverables
-
-This pattern is the canonical replacement for the **N+1 fan-out anti-pattern** (calling `GetInstanceAsync` once per related id just to read attributes — see "Anti-Pattern" below).
-
-## Program Types
-Applies to: `Scheduler`, `PostCreate`, `PromoteActionCommand`, `Common`
-
-## Services Used
-- `IInstanceService` — query parents, fetch related instances, write the aggregate back
-- `IQueryBuilderService` — filter the parent set by state/attribute (optional)
-
-## Key Idiom: `RelatedQueryBuilder.Select(...)`
-
-The single most important rule for this pattern:
-
-> **Always use `RelatedQueryBuilder.Select(...)` to fetch the attributes you need from related instances in the same call — do not call `GetInstanceAsync` per related id.**
-
-`GetRelatedInstancesAsync` returns `RelatedInstance` objects that already carry the attributes you `.Select()`-ed. Calling `GetInstanceAsync` afterwards is an N+1 round-trip per parent and is strictly worse.
-
-## Code Example
-
-Scheduler that, for each Project in `Active` state, sums "consumed effort" across all related Allocations (weekdays between AllocationStartDate and AllocationEndDate, today if end is blank/future) and writes back to `ConsumedEffort` and `ConsumedEffortCalculatedOn` on the Project.
-
-```csharp
-using Prorigo.Protrak.API.Contracts;
-using Prorigo.Protrak.API.Contracts.Builders;
-using Prorigo.Protrak.API.Contracts.Extensions;
-using System;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace MyProject.Customization
-{
-    public class CalculateProjectConsumedEffort : ISchedulerProgramAsync
-    {
-        public IInstanceService InstanceService { get; set; }
-        public IQueryBuilderService QueryBuilderService { get; set; }
-
-        public async Task RunAsync()
-        {
-            var projects = await InstanceService.GetInstancesAsync(new InstanceQuery
-            {
-                TypeName = "Project",
-                StateName = "Active",
-                Take = int.MaxValue,
-            });
-            if (projects?.Data == null) return;
-
-            var today = DateTime.UtcNow.Date;
-
-            foreach (var project in projects.Data)
-            {
-                // ✅ Fetch only the attributes we need from related Allocations,
-                //    in a SINGLE call. Do NOT loop GetInstanceAsync per id.
-                var allocationQuery = RelatedQueryBuilder.Create()
-                    .ForRelation("ProjectToAllocation", "Allocation", RelationDirection.From)
-                    .Select("AllocationStartDate", "AllocationEndDate")
-                    .TakeAll()
-                    .Build();
-
-                var allocations = await InstanceService.GetRelatedInstancesAsync(
-                    project.Id, allocationQuery);
-
-                double totalWeekdays = 0;
-                foreach (var allocation in allocations.SafeItems())
-                {
-                    var start = allocation.GetDateAttributeValue("AllocationStartDate");
-                    var end = allocation.GetDateAttributeValue("AllocationEndDate");
-                    if (start == null) continue;
-
-                    var effectiveEnd = (end == null || end.Value.Date > today)
-                        ? today
-                        : end.Value.Date;
-
-                    totalWeekdays += CountWeekdays(start.Value.Date, effectiveEnd);
-                }
-
-                var update = InstanceBuilder.ForUpdate(project.Id, "Project")
-                    .SetNumericAttributeValue("ConsumedEffort", totalWeekdays)
-                    .SetDateAttributeValue("ConsumedEffortCalculatedOn", today)
-                    .Build();
-
-                await InstanceService.UpdateInstanceAsync(update, null);
-            }
-        }
-
-        private static int CountWeekdays(DateTime fromInclusive, DateTime toInclusive)
-        {
-            if (toInclusive < fromInclusive) return 0;
-            int count = 0;
-            for (var d = fromInclusive; d <= toInclusive; d = d.AddDays(1))
-            {
-                if (d.DayOfWeek != DayOfWeek.Saturday && d.DayOfWeek != DayOfWeek.Sunday)
-                    count++;
-            }
-            return count;
-        }
-    }
-}
-```
-
-## Anti-Pattern (DO NOT DO THIS)
-
-```csharp
-// ❌ Wrong: N+1 round-trips. One DB hit per related allocation.
-var allocationsRef = await InstanceService.GetRelatedInstancesAsync(
-    project.Id, RelatedQueryBuilder.Create()
-        .ForRelation("ProjectToAllocation", "Allocation", RelationDirection.From)
-        .TakeAll().Build());
-
-foreach (var ref in allocationsRef.SafeItems())
-{
-    var full = await InstanceService.GetInstanceAsync(
-        ref.Id, new[] { "AllocationStartDate", "AllocationEndDate" });  // ← extra call per id
-    var start = full.GetDateAttributeValue("AllocationStartDate");
-    // ...
-}
-```
-
-The fix is to add `.Select("AllocationStartDate", "AllocationEndDate")` to the builder and read the attributes off the `RelatedInstance` directly. `RelatedInstance` exposes the same `GetTextAttributeValue` / `GetDateAttributeValue` / `GetNumericAttributeValue` accessors as `Instance` — see [Instance Accessor Methods](./instance-accessor-methods.md#on-relatedinstance).
-
-## Key Rules
-
-- Always pre-select the attributes you need with `.Select(name1, name2, ...)`. Omitting `.Select()` returns instances without their attribute values populated; adding `GetInstanceAsync` calls afterwards is the N+1 anti-pattern.
-- Use `.TakeAll()` (or `Skip`/`Take` for pagination) — the default page size truncates large parents.
-- Use `RelatedInstance` accessors directly (`GetDateAttributeValue`, etc.) — same syntax as `Instance`.
-- Iterate with `.SafeItems()` to avoid manual null checks.
-- Write the rolled-up value back with `InstanceBuilder.ForUpdate(...)` + `UpdateInstanceAsync`. Do not mutate the parent in-place inside a Scheduler — Scheduler programs receive no incoming Instance.
-- For schedulers, prefer `Take = int.MaxValue` on the parent query to ensure all parents are processed; for *very* large datasets, paginate explicitly.
-
-## Related Patterns
-- [Query and Filter](./query-filter-pattern.md) — filtering the parent set