@prorigo/protrak-forge 0.4.0 → 0.4.2

package/bin/protrak-forge.js

@@ -15672,6 +15672,14 @@ var LocalSchemaProvider = class {
   invalidateRules() {
     this._rules = null;
   }
+  /** Force a re-read of types on next access. */
+  invalidateTypes() {
+    this._types = null;
+  }
+  /** Force a re-read of attributes on next access. */
+  invalidateAttributes() {
+    this._attributes = null;
+  }
   // ── Public API ────────────────────────────────────────────────────────────
   listTypes() {
     return Object.entries(this.types).map(([name, typeData]) => ({
@@ -17948,7 +17956,7 @@ function getClient() {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.4.0";
+var PACKAGE_VERSION = "0.4.2";
 
 // src/tools/_schema-write-utils.ts
 var fs4 = __toESM(require("fs"));
@@ -22486,9 +22494,6 @@ function serializeStyle(style) {
       if (!FONT_STYLE_OPTIONS.includes(v)) {
         return { error: `font_style entry '${v}' must be one of: ${FONT_STYLE_OPTIONS.join(", ")}.` };
       }
-      if (seen.has(v)) {
-        return { error: `font_style contains duplicate entry '${v}'.` };
-      }
       seen.add(v);
     }
     if (seen.has("Bold")) tokens.push("fontWeight:bold");
@@ -22599,6 +22604,50 @@ var EXAMPLES = [
         }
       ]
     }
+  },
+  {
+    intent: "Current user's roles include 'Manager'. UserRoles context: attributeName is omitted entirely; Contains takes only firstValue.",
+    rule: {
+      name: "CurrentUserIsManager",
+      attributeFilterGroup: [
+        {
+          operator: "None",
+          attributeFilterConditions: [
+            {
+              attributeContext: "UserRoles",
+              condition: "Contains",
+              firstValue: { valueType: "Static", value: "Manager" },
+              operator: "None"
+            }
+          ]
+        }
+      ]
+    }
+  },
+  {
+    intent: "Visible when current user is the Creator OR has the 'Manager' role. Mixes UserRoles + Instance contexts in a single group joined by Or.",
+    rule: {
+      name: "VisibleToManagerOrCreator",
+      attributeFilterGroup: [
+        {
+          operator: "None",
+          attributeFilterConditions: [
+            {
+              attributeContext: "UserRoles",
+              condition: "Contains",
+              firstValue: { valueType: "Static", value: "Manager" },
+              operator: "Or"
+            },
+            {
+              attributeName: "Creator",
+              attributeContext: "Instance",
+              condition: "ContextUser",
+              operator: "None"
+            }
+          ]
+        }
+      ]
+    }
   }
 ];
 var DYNAMIC_VALUE_RULES = {
@@ -22712,7 +22761,7 @@ var CONDITION_INPUT_SCHEMA = {
     },
     attribute_name: {
       type: "string",
-      description: "PascalCase attribute name. Required for Instance and User contexts. Omit for UserRoles context (it evaluates the current user's roles)."
+      description: "PascalCase attribute name. Required for Instance and User contexts. OMIT this key entirely for UserRoles context (it evaluates the current user's roles). Do NOT send empty string '' \u2014 leave the key out."
     },
     condition: {
       type: "string",
@@ -22720,11 +22769,11 @@ var CONDITION_INPUT_SCHEMA = {
     },
     first_value: {
       ...VALUE_INPUT_SCHEMA,
-      description: "First value. Required when the condition takes a value; omit for IsEmpty/Today/ContextUser/etc."
+      description: "First value of the condition. Required for value-bearing conditions (Equals, Contains, GreaterThan, Between, In, etc.). OMIT this key entirely for valueless conditions: IsEmpty, IsNotEmpty, Today, LastOneWeek, LastOneMonth, LastOneYear, NextWeek, NextOneMonth, NextOneYear, ContextUser. Do NOT send `null` or `{value: ''}` \u2014 leave the key out of the JSON object."
     },
     second_value: {
       ...VALUE_INPUT_SCHEMA,
-      description: "Second value. Required only for 'Between' conditions."
+      description: "Second value. Only valid for 'Between'. OMIT this key entirely for every other condition (including Contains, Equals, In, IsEmpty, ContextUser, etc.). Do NOT send `null` or `{value: ''}` \u2014 leave the key out of the JSON object."
     },
     operator: {
       type: "string",
@@ -22753,7 +22802,7 @@ var GROUP_INPUT_SCHEMA = {
 };
 var TOOL_DEF29 = {
   name: "generate_protrak_rule",
-  description: "Generate and write a Rule JSON file to <workspace>/Rules/<name>.json. Rules express attribute-filter logic used by display conditions, conditional formatting, dependent picklists, and Access Policy. Inputs are strictly structured: the agent should translate natural-language intent into attribute_filter_groups using the schema returned by get_protrak_rule_context. Validates: PascalCase name; Instance-context attribute_name exists in the workspace (or is a recognised basic attribute); the condition is valid for the attribute's type; value presence matches the condition (e.g. Between requires both, IsEmpty rejects values); dynamic values match @Instance.X, @User.X, or $StartOfToday()/$StartOfMonth(\xB1Nd) patterns; @Instance dynamic references resolve to known attributes. Pass error_message only when the rule will be used as an Access Policy. Refuses to overwrite an existing file unless overwrite:true.",
+  description: "Generate and write a Rule JSON file to <workspace>/Rules/<name>.json. Rules express attribute-filter logic used by display conditions, conditional formatting, dependent picklists, and Access Policy. Inputs are strictly structured: the agent should translate natural-language intent into attribute_filter_groups using the schema returned by get_protrak_rule_context. Validates: PascalCase name; Instance-context attribute_name exists in the workspace (or is a recognised basic attribute); the condition is valid for the attribute's type; value presence matches the condition (e.g. Between requires both, IsEmpty rejects values); dynamic values match @Instance.X, @User.X, or $StartOfToday()/$StartOfMonth(\xB1N[d|w|m|y]) patterns; @Instance dynamic references resolve to known attributes. Pass error_message only when the rule will be used as an Access Policy. Refuses to overwrite an existing file unless overwrite:true.",
   inputSchema: {
     type: "object",
     properties: {
@@ -22780,6 +22829,49 @@ var TOOL_DEF29 = {
     required: ["name", "attribute_filter_groups"]
   }
 };
+function normalizeValue(v) {
+  if (v === void 0 || v === null) return void 0;
+  if (typeof v !== "object") return v;
+  const obj = v;
+  if (typeof obj["value"] === "string" && obj["value"].length === 0) return void 0;
+  return obj;
+}
+function normalizeCondition(rc) {
+  const attrName = rc["attribute_name"];
+  return {
+    attribute_context: rc["attribute_context"],
+    attribute_name: typeof attrName === "string" && attrName.length > 0 ? attrName : void 0,
+    condition: rc["condition"],
+    first_value: normalizeValue(rc["first_value"]),
+    second_value: normalizeValue(rc["second_value"]),
+    operator: rc["operator"]
+  };
+}
+function expectedConditionShape(cond) {
+  const shape = {
+    attribute_context: cond.attribute_context
+  };
+  if (cond.attribute_context !== "UserRoles") {
+    shape["attribute_name"] = cond.attribute_name ?? "<AttributeName>";
+  }
+  shape["condition"] = cond.condition;
+  if (RANGE_CONDITIONS.has(cond.condition)) {
+    shape["first_value"] = { value_type: "Static", value: "<from>" };
+    shape["second_value"] = { value_type: "Static", value: "<to>" };
+  } else if (!VALUE_LESS_CONDITIONS.has(cond.condition)) {
+    shape["first_value"] = { value_type: "Static", value: "<value>" };
+  }
+  shape["operator"] = cond.operator;
+  return shape;
+}
+function conditionShapeHints(cond) {
+  return {
+    expected_shape: expectedConditionShape(cond),
+    valueless_conditions: [...VALUE_LESS_CONDITIONS].sort(),
+    range_conditions: [...RANGE_CONDITIONS].sort(),
+    hint: 'Send the value-bearing keys ONLY when needed. To "omit" a key, leave it out of the JSON entirely \u2014 do not send null or { value: "" }.'
+  };
+}
 function validateValueShape(value, label) {
   if (value === void 0) return null;
   if (typeof value !== "object" || value === null) {
@@ -22808,35 +22900,42 @@ function validateDynamicValue(provider, value, label) {
 }
 function validateCondition(provider, cond, prefix) {
   if (!ATTRIBUTE_CONTEXTS.includes(cond.attribute_context)) {
-    return `${prefix}.attribute_context must be one of: ${ATTRIBUTE_CONTEXTS.join(", ")}.`;
+    return { error: `${prefix}.attribute_context must be one of: ${ATTRIBUTE_CONTEXTS.join(", ")}.` };
   }
   if (!GROUP_OPERATORS.includes(cond.operator)) {
-    return `${prefix}.operator must be one of: ${GROUP_OPERATORS.join(", ")}.`;
+    return { error: `${prefix}.operator must be one of: ${GROUP_OPERATORS.join(", ")}.` };
   }
   if (typeof cond.condition !== "string" || !cond.condition) {
-    return `${prefix}.condition is required.`;
+    return { error: `${prefix}.condition is required.` };
   }
-  let validConditions;
   if (cond.attribute_context === "UserRoles") {
     if (cond.attribute_name) {
-      return `${prefix}.attribute_name must be omitted when attribute_context is 'UserRoles'.`;
+      return { error: `${prefix}.attribute_name must be omitted when attribute_context is 'UserRoles'.` };
+    }
+    if (!USER_ROLES_CONDITIONS.includes(cond.condition)) {
+      return {
+        error: `${prefix}.condition '${cond.condition}' is not valid for UserRoles context. Valid: ${USER_ROLES_CONDITIONS.join(", ")}.`
+      };
     }
-    validConditions = USER_ROLES_CONDITIONS;
   } else {
     if (!cond.attribute_name) {
-      return `${prefix}.attribute_name is required for attribute_context='${cond.attribute_context}'.`;
+      return { error: `${prefix}.attribute_name is required for attribute_context='${cond.attribute_context}'.` };
     }
     if (!isPascalCase(cond.attribute_name)) {
-      return `${prefix}.${pascalCaseError("attribute_name", cond.attribute_name)}`;
+      return { error: `${prefix}.${pascalCaseError("attribute_name", cond.attribute_name)}` };
     }
     if (cond.attribute_context === "Instance") {
       const attrType = resolveInstanceAttributeType(provider, cond.attribute_name);
       if (!attrType) {
-        return `${prefix} references Instance attribute '${cond.attribute_name}' which does not exist in the workspace. Add the attribute (or use a basic attribute name like Name/State/Created/Creator) before generating this rule.`;
+        return {
+          error: `${prefix} references Instance attribute '${cond.attribute_name}' which does not exist in the workspace. Add the attribute (or use a basic attribute name like Name/State/Created/Creator) before generating this rule.`
+        };
       }
-      validConditions = CONDITIONS_BY_ATTR_TYPE[attrType] ?? CONDITIONS_BY_ATTR_TYPE["Text"];
+      const validConditions = CONDITIONS_BY_ATTR_TYPE[attrType] ?? CONDITIONS_BY_ATTR_TYPE["Text"];
       if (!validConditions.includes(cond.condition)) {
-        return `${prefix}.condition '${cond.condition}' is not valid for Instance attribute '${cond.attribute_name}' (type=${attrType}). Valid conditions: ${validConditions.join(", ")}.`;
+        return {
+          error: `${prefix}.condition '${cond.condition}' is not valid for Instance attribute '${cond.attribute_name}' (type=${attrType}). Valid conditions: ${validConditions.join(", ")}.`
+        };
       }
     } else {
       const acceptable = /* @__PURE__ */ new Set([
@@ -22847,32 +22946,42 @@ function validateCondition(provider, cond, prefix) {
         ...CONDITIONS_BY_ATTR_TYPE["Boolean"]
       ]);
       if (!acceptable.has(cond.condition)) {
-        return `${prefix}.condition '${cond.condition}' is not recognised for User-context conditions.`;
+        return {
+          error: `${prefix}.condition '${cond.condition}' is not recognised for User-context conditions.`
+        };
       }
-      validConditions = Array.from(acceptable);
     }
   }
-  if (cond.attribute_context === "UserRoles" && !USER_ROLES_CONDITIONS.includes(cond.condition)) {
-    return `${prefix}.condition '${cond.condition}' is not valid for UserRoles context. Valid: ${USER_ROLES_CONDITIONS.join(", ")}.`;
-  }
   const valueless = VALUE_LESS_CONDITIONS.has(cond.condition);
   const ranged = RANGE_CONDITIONS.has(cond.condition);
   const hasFirst = cond.first_value !== void 0;
   const hasSecond = cond.second_value !== void 0;
   if (valueless) {
     if (hasFirst || hasSecond) {
-      return `${prefix}.condition '${cond.condition}' takes no value(s); remove first_value/second_value.`;
+      return {
+        error: `${prefix}.condition '${cond.condition}' takes no value(s); omit first_value and second_value entirely.`,
+        extras: conditionShapeHints(cond)
+      };
     }
   } else if (ranged) {
     if (!hasFirst || !hasSecond) {
-      return `${prefix}.condition '${cond.condition}' requires BOTH first_value and second_value.`;
+      return {
+        error: `${prefix}.condition '${cond.condition}' requires BOTH first_value and second_value.`,
+        extras: conditionShapeHints(cond)
+      };
     }
   } else {
     if (!hasFirst) {
-      return `${prefix}.condition '${cond.condition}' requires first_value.`;
+      return {
+        error: `${prefix}.condition '${cond.condition}' requires first_value.`,
+        extras: conditionShapeHints(cond)
+      };
     }
     if (hasSecond) {
-      return `${prefix}.condition '${cond.condition}' takes only first_value; remove second_value.`;
+      return {
+        error: `${prefix}.condition '${cond.condition}' takes only first_value; omit second_value entirely (do not send null or empty value).`,
+        extras: conditionShapeHints(cond)
+      };
     }
   }
   for (const [v, lbl] of [
@@ -22880,10 +22989,10 @@ function validateCondition(provider, cond, prefix) {
     [cond.second_value, `${prefix}.second_value`]
   ]) {
     const shapeErr = validateValueShape(v, lbl);
-    if (shapeErr) return shapeErr;
+    if (shapeErr) return { error: shapeErr };
     if (v) {
       const dynErr = validateDynamicValue(provider, v, lbl);
-      if (dynErr) return dynErr;
+      if (dynErr) return { error: dynErr };
     }
   }
   return null;
@@ -22942,16 +23051,9 @@ function handle29(provider, args) {
       if (typeof rc !== "object" || rc === null) {
         return errorResponse(`attribute_filter_groups[${gi}].conditions[${ci}] must be an object.`);
       }
-      const cond = {
-        attribute_context: rc["attribute_context"],
-        attribute_name: rc["attribute_name"],
-        condition: rc["condition"],
-        first_value: rc["first_value"],
-        second_value: rc["second_value"],
-        operator: rc["operator"]
-      };
+      const cond = normalizeCondition(rc);
       const err = validateCondition(provider, cond, `attribute_filter_groups[${gi}].conditions[${ci}]`);
-      if (err) return errorResponse(err);
+      if (err) return errorResponse(err.error, err.extras);
       conditions.push(cond);
     }
     groups.push({ operator: raw["operator"], conditions });
@@ -22995,7 +23097,7 @@ var DISPLAY_TARGET_KINDS = ["layout_template", "form"];
 var FORMAT_TARGET_KINDS = ["type_widget", "form"];
 var TOOL_DEF30 = {
   name: "attach_protrak_rule",
-  description: "Attach an existing Rule to a Protrak schema artifact. One polymorphic tool covering five consumer shapes selected by `usage`: 'display_condition' (LayoutTemplate widget displayConditions[] or Form field displayCondition); 'format_condition' (ViewLayout field formatConditions); 'conditional_formatting' (TypeWidget column or Form field conditionalFormatting); 'access_policy' (Type.accessPolicyRule); 'dependent_picklist' (Picklist option.rule). Rule must already exist in Rules/. Target file/widget/attribute/option must exist; the tool refuses to silently create them. Style is structured ({ background_color?, fore_color?, font_style? }) and serialized to the comma-terminated CSS-string the SPA evaluator expects.",
+  description: "Attach an existing Rule to a Protrak schema artifact. One polymorphic tool covering five consumer shapes selected by `usage`: 'display_condition' (LayoutTemplate widget displayConditions[], Form container displayConditions[], or Form field displayCondition); 'format_condition' (ViewLayout field formatConditions); 'conditional_formatting' (TypeWidget column or Form field conditionalFormatting); 'access_policy' (Type.accessPolicyRule); 'dependent_picklist' (Picklist option.rule). Rule must already exist in Rules/. Target file/widget/attribute/option must exist; the tool refuses to silently create them. Style is structured ({ background_color?, fore_color?, font_style? }) and serialized to the comma-terminated CSS-string the SPA evaluator expects.",
   inputSchema: {
     type: "object",
     properties: {
@@ -23028,7 +23130,7 @@ var TOOL_DEF30 = {
       },
       container_id: {
         type: "string",
-        description: "Form target only: formContainerKey to disambiguate when multiple containers exist."
+        description: "Form target only: formContainerKey. For usage='display_condition': when provided WITHOUT attribute_name, attaches the rule to the container itself (plural displayConditions[]). When attribute_name is also provided, disambiguates which container to search for that field. For usage='conditional_formatting': disambiguates which container holds the field. When omitted on a field lookup and the same attribute exists in multiple containers, the first match wins \u2014 pass container_id to disambiguate."
       },
       section_name: {
         type: "string",
@@ -23064,6 +23166,8 @@ var TOOL_DEF30 = {
   }
 };
 function ruleExists(provider, ruleName) {
+  if (provider.rules[ruleName]) return true;
+  provider.invalidateRules();
   return !!provider.rules[ruleName];
 }
 function findFormField(formData, attrName, containerId) {
@@ -23084,7 +23188,6 @@ function findFormField(formData, attrName, containerId) {
       return {
         result: {
           field: fields[idx],
-          index: idx,
           parent: fields,
           containerKey: container["formContainerKey"] ?? ""
         }
@@ -23158,16 +23261,50 @@ function attachDisplayCondition(provider, args) {
     );
   }
   const attrName = args["attribute_name"];
-  if (!attrName) {
-    return errorResponse("attribute_name is required for usage='display_condition' on a form.");
+  const containerId = args["container_id"] ?? void 0;
+  if (!attrName && !containerId) {
+    return errorResponse(
+      "Either attribute_name (to attach to a field) or container_id (to attach to a whole container) is required for usage='display_condition' on a form."
+    );
   }
-  if (!isPascalCase(attrName)) return errorResponse(pascalCaseError("attribute_name", attrName));
   const filePath = path17.join(provider.ws.formsDir, `${targetName}.json`);
   if (!fs21.existsSync(filePath)) {
     return errorResponse(`Form '${targetName}' not found at ${filePath}.`);
   }
   const data = readJsonFile(filePath);
-  const containerId = args["container_id"] ?? void 0;
+  if (!attrName) {
+    const config2 = data["formConfiguration"] ?? {};
+    const containers = Array.isArray(config2["containers"]) ? config2["containers"] : [];
+    const container = containers.find((c) => c["formContainerKey"] === containerId);
+    if (!container) {
+      return errorResponse(`Container '${containerId}' not found in form '${targetName}'.`, {
+        available_containers: containers.map((c) => c["formContainerKey"] ?? "")
+      });
+    }
+    const existing2 = Array.isArray(container["displayConditions"]) ? container["displayConditions"] : [];
+    if (existing2.includes(ruleName)) {
+      if (!replace) {
+        return errorResponse(
+          `Rule '${ruleName}' is already in displayConditions for container '${containerId}'. Pass replace:true to no-op silently.`
+        );
+      }
+    } else {
+      existing2.push(ruleName);
+    }
+    container["displayConditions"] = existing2;
+    writeJsonFilePath(filePath, data);
+    return successResponse(
+      {
+        usage: "display_condition",
+        target_kind: "form",
+        target_path: filePath,
+        container_id: containerId,
+        display_conditions: existing2
+      },
+      { nextSteps: [`Verify by reading Forms/${targetName}.json.`] }
+    );
+  }
+  if (!isPascalCase(attrName)) return errorResponse(pascalCaseError("attribute_name", attrName));
   const lookup2 = findFormField(data, attrName, containerId);
   if (lookup2.error) return errorResponse(lookup2.error, lookup2.available_containers ? { available_containers: lookup2.available_containers } : void 0);
   const field = lookup2.result.field;
@@ -23279,7 +23416,8 @@ function attachFormatCondition(provider, args) {
       usage: "format_condition",
       target_path: filePath,
       attribute_name: attrName,
-      format_conditions: fc
+      entry,
+      total_format_conditions: fc.length
     },
     { nextSteps: [`Verify by reading ViewLayouts/${targetName}.json.`] }
   );
@@ -23371,7 +23509,8 @@ function attachConditionalFormatting(provider, args) {
       target_kind: targetKind,
       target_path: filePath,
       attribute_name: attrName,
-      conditional_formatting: cf
+      entry,
+      total_conditional_formatting: cf.length
     },
     { nextSteps: [`Verify by reading ${path17.basename(filePath)}.`] }
   );

package/data/CLAUDE.md.template

@@ -178,6 +178,9 @@ Call `attach_protrak_rule(usage, rule_name, ...)`. One polymorphic tool covers f
   — 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='display_condition'`, `target_kind='form'`, `target_name`, `container_id`
+  (no `attribute_name`) — appends to the container's **plural** `displayConditions: string[]`
+  (same shape as a LayoutTemplate widget).
 - `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`.

package/package.json

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