@colixsystems/widget-sdk 0.88.0 → 0.90.0

package/README.md

@@ -61,7 +61,33 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.88.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.90.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.89.0 (contract unchanged)
+
+**New linter rule `write-not-gated-on-user` — a widget that writes must decide what a signed-OUT visitor sees (sc-4985).**
+
+- **`write-not-gated-on-user` (severity `warning`, non-blocking).** A widget that
+  writes with `useDatastoreMutation` but carries no identity guard is flagged. A
+  write needs a signed-in app user, so an anonymous visitor handed a live
+  "Save" / "Book" / "Delete" button can only ever tap it and fail. Author fix:
+  read `useUser()` and branch **before** rendering the control — when `!user.id`
+  keep the affordance as a visibly-inactive signpost with a translated "sign in"
+  line and **no press handler** (a widget cannot open the login surface; that is
+  a built-in Button's `sign-in` action, wired by the page author), and when the
+  user is signed in but not permitted, leave the control out entirely.
+- **Reading `useUser().id` as a VALUE does not satisfy it.** The canonical
+  USER-column write pattern (`create({ [memberField]: user.id })`) calls
+  `useUser()` without ever branching on it — the case most easily mistaken for a
+  gate — so the rule requires an operator after `.id` (a negation, a ternary,
+  `&&`, a comparison) or a `groupIds` / `roles` check.
+- **Why a warning.** It is conservative on purpose: an unrelated `.id`
+  comparison elsewhere in the source silences it. A rule that occasionally stays
+  quiet is far cheaper than one that cries wolf on correct code, and gating is an
+  affordance decision — the server remains the only authority, so the `catch`
+  stays either way.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
 
 ### What's new in 0.88.0 (contract 1.62.0)
 
@@ -146,6 +172,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 - **The colour maths ignores alpha, on purpose.** `hexChannels` reads the R/G/B pair and skips any alpha, so contrast, readable text and the derived accent tints reason about the opaque colour. None of them can composite without knowing the backdrop, which a token table does not have — so transparency lives in the VALUE your widget renders, not in the decision about whether that colour reads as light or dark.
 - **`CONTRACT.version` → `1.61.0`** (additive: `themeTokens.spacingScale` + `widgetStyles` and their bounds, `themeComponents.card.universalFields`, and the `normaliseWidgetStyles` / `deriveSurfaceTokens` host exports). No author-facing export changed signature, and a theme that sets none of it resolves exactly as before.
 
+### What's new in 0.90.0 (contract 1.63.0)
+
+**A manifest action declares `triggerTypes` — a set — and the script learns which one fired (sc-4915).** An action could carry exactly one trigger, so a widget that needed the same work done on create *and* on delete had to ship the script twice: two `actions` entries, two operator bindings, two run histories, and the usual drift between the copies. `triggerTypes` replaces `triggerType`: a non-empty array of unique values from `schedule`, `record_created`, `record_updated`, `record_deleted`, freely combined (`scheduleCron` is required iff the array contains `schedule`). The pre-0.90.0 scalar `triggerType` is still read and normalised into the array, so a widget already published against it keeps validating and nothing needs republishing. What makes the combination useful is the other half: the script's `triggerType` global now names the trigger that **actually fired this run** — including `"manual"` (an operator's Run now) and `"app"` (a button press) — instead of echoing the row's configuration, so one script can branch on whether its record was created or deleted. `CONTRACT.version` → `1.63.0`. Additive for every existing manifest.
+
 ### What's new in 0.85.1 (contract 1.60.1)
 
 **`useWidgetEvent(name)` returns the emitter FUNCTION — the declared contract said otherwise (sc-4753).** `CONTRACT.hooks`'s entry for the hook declared `returnShape: { emit }`, so every surface derived from it — chiefly the Widget Builder Agent's hooks table — told authors the hook resolves to an object. It never did: `useWidgetEvent("slotChosen")` hands back the callable you invoke directly (`emitSlot({ courtId })`), exactly as the typings and the Developer guide have always documented. A widget written against the declared shape destructured a function, got `undefined`, and threw the moment a user interacted — a cross-widget wire that rendered perfectly and only failed on click. The declaration is now a bare callable and the publish-time render harness models the same shape, so a wrong destructure is caught instead of waved through. `CONTRACT.version` → `1.60.1`. Documentation-only correction: no export, signature, or runtime behaviour changed — a widget already calling the result is unaffected.
@@ -593,7 +623,7 @@ Two additive features land in this version.
 
 **A widget may declare server-side actions in its manifest.**
 
-- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerType, scheduleCron?, timeoutMs?, scriptSource }`. `triggerType` is one of `schedule`, `record_created`, `record_updated`, `record_deleted`; `scheduleCron` is required when `triggerType === "schedule"`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `connectors` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). `connectors.call(slug, { method, path, query, body, headers })` resolves a tenant-configured REST connector by slug and returns `{ status, headers, body }` (auth + SSRF handled by the platform; an unknown slug / SSRF / timeout throws a catchable Error). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
+- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerTypes, scheduleCron?, timeoutMs?, scriptSource }`. `triggerTypes` is a non-empty array of unique values from `schedule`, `record_created`, `record_updated`, `record_deleted` — combine them so one script serves several events; `scheduleCron` is required when it contains `schedule`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `connectors` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). `connectors.call(slug, { method, path, query, body, headers })` resolves a tenant-configured REST connector by slug and returns `{ status, headers, body }` (auth + SSRF handled by the platform; an unknown slug / SSRF / timeout throws a catchable Error). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
 - **Operators enable actions per tenant** from the Properties Panel. An enabled action materialises a tenant `Action` row **DISABLED** until the operator binds an integration API key (and, for `record_*` triggers, a target table) in the Actions admin page — those bindings are tenant-local, so `triggerTableId` / `apiKeyId` must **not** appear in the manifest (the validator and linter reject them).
 - **New contract fields** `CONTRACT.actionTriggerTypes`, `CONTRACT.actionScriptGlobals`, `CONTRACT.actionScriptMaxBytes` expose the grammar so the Developer page, the AI agent prompt, and `validateManifest` derive it from one source. `validateManifest` now structurally validates `actions`; the marketplace linter rejects malformed / oversized declarations.
 - **New manifest category `ADMINISTRATION`** for app-administration widgets such as User Management. Added to `CONTRACT.manifestCategories`, `validateManifest`, the `WidgetCategory` type, the marketplace category list, and the master-DB `WidgetCategory` enum.

package/dist/contract.cjs

@@ -1373,6 +1373,34 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+/**
+ * sc-4915 — the trigger set a manifest action declares, canonically ordered.
+ *
+ * `triggerTypes` is the current shape; the pre-sc-4915 scalar `triggerType` is
+ * still read so a widget published before the change keeps validating. Returns
+ * null when the declaration is empty, holds an unknown value, or repeats one —
+ * every caller reports that as a manifest error. ONE reader, so the SDK
+ * validator, the CLI linter and the backend cannot disagree about what a
+ * manifest declared.
+ */
+function normaliseActionTriggerTypes(action) {
+  const a = action !== null && typeof action === "object" ? action : {};
+  const raw = Array.isArray(a.triggerTypes)
+    ? a.triggerTypes
+    : a.triggerTypes === undefined && a.triggerType !== undefined
+      ? [a.triggerType]
+      : null;
+  if (raw === null || raw.length === 0) return null;
+  const seen = new Set();
+  for (const t of raw) {
+    if (typeof t !== "string" || !ACTION_TRIGGER_TYPES.includes(t)) return null;
+    if (seen.has(t)) return null;
+    seen.add(t);
+  }
+  return ACTION_TRIGGER_TYPES.filter((t) => seen.has(t));
+}
+
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -1501,9 +1529,9 @@ const MANIFEST_SCHEMA = {
     type: "object[]",
     required: false,
     description:
-      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerTypes (a non-empty array of unique values from " +
       ACTION_TRIGGER_TYPES.join(", ") +
-      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      "; combine them so one script serves several events — the script's `triggerType` global names the event that actually fired), scheduleCron? (required iff triggerTypes contains 'schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
       ACTION_SCRIPT_GLOBALS.join(", ") +
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
@@ -2787,7 +2815,14 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.62.0",
+  // 1.63.0: additive (sc-4915) — a manifest action declares `triggerTypes`, a
+  //    non-empty ARRAY, so one script can serve a create, an update and a
+  //    delete instead of being copied into three actions. The pre-sc-4915
+  //    scalar `triggerType` is still read and normalised, so an already
+  //    published widget keeps validating. The script's `triggerType` global
+  //    now names the trigger that actually FIRED the run ('manual' and 'app'
+  //    included), which is what makes a multi-trigger script able to branch.
+  version: "1.63.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3073,6 +3108,7 @@ module.exports = {
   CONTRACT,
   clampSpacingScale,
   scaleSpacing,
+  normaliseActionTriggerTypes,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,

package/dist/contract.js

@@ -1373,6 +1373,34 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+/**
+ * sc-4915 — the trigger set a manifest action declares, canonically ordered.
+ *
+ * `triggerTypes` is the current shape; the pre-sc-4915 scalar `triggerType` is
+ * still read so a widget published before the change keeps validating. Returns
+ * null when the declaration is empty, holds an unknown value, or repeats one —
+ * every caller reports that as a manifest error. ONE reader, so the SDK
+ * validator, the CLI linter and the backend cannot disagree about what a
+ * manifest declared.
+ */
+function normaliseActionTriggerTypes(action) {
+  const a = action !== null && typeof action === "object" ? action : {};
+  const raw = Array.isArray(a.triggerTypes)
+    ? a.triggerTypes
+    : a.triggerTypes === undefined && a.triggerType !== undefined
+      ? [a.triggerType]
+      : null;
+  if (raw === null || raw.length === 0) return null;
+  const seen = new Set();
+  for (const t of raw) {
+    if (typeof t !== "string" || !ACTION_TRIGGER_TYPES.includes(t)) return null;
+    if (seen.has(t)) return null;
+    seen.add(t);
+  }
+  return ACTION_TRIGGER_TYPES.filter((t) => seen.has(t));
+}
+
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -1501,9 +1529,9 @@ const MANIFEST_SCHEMA = {
     type: "object[]",
     required: false,
     description:
-      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerTypes (a non-empty array of unique values from " +
       ACTION_TRIGGER_TYPES.join(", ") +
-      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      "; combine them so one script serves several events — the script's `triggerType` global names the event that actually fired), scheduleCron? (required iff triggerTypes contains 'schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
       ACTION_SCRIPT_GLOBALS.join(", ") +
       " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
     default: [],
@@ -2787,7 +2815,14 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.62.0",
+  // 1.63.0: additive (sc-4915) — a manifest action declares `triggerTypes`, a
+  //    non-empty ARRAY, so one script can serve a create, an update and a
+  //    delete instead of being copied into three actions. The pre-sc-4915
+  //    scalar `triggerType` is still read and normalised, so an already
+  //    published widget keeps validating. The script's `triggerType` global
+  //    now names the trigger that actually FIRED the run ('manual' and 'app'
+  //    included), which is what makes a multi-trigger script able to branch.
+  version: "1.63.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3073,6 +3108,7 @@ export {
   CONTRACT,
   clampSpacingScale,
   scaleSpacing,
+  normaliseActionTriggerTypes,
   isHookAllowed,
   requiredContextKeys,
   isHexColor,

package/dist/index.d.ts

@@ -223,18 +223,23 @@ export interface WidgetManifestAction {
   key: string;
   name: string;
   description?: string;
-  triggerType:
-    | "schedule"
-    | "record_created"
-    | "record_updated"
-    | "record_deleted";
-  /** Required iff `triggerType === "schedule"`. node-cron syntax. */
+  /**
+   * sc-4915 — a non-empty set of unique triggers. Combine them so one script
+   * serves several events; the script's `triggerType` global names the one
+   * that actually fired.
+   */
+  triggerTypes: Array<
+    "schedule" | "record_created" | "record_updated" | "record_deleted"
+  >;
+  /** Required iff `triggerTypes` contains `"schedule"`. node-cron syntax. */
   scheduleCron?: string;
   /** 100–300000. Defaults to 30000 on materialise. */
   timeoutMs?: number;
   /**
    * Runs against `datastore`, `fetch`, `console`, `record`, `tenantId`,
    * `triggerType`, `triggerTableId` — NOT the React/SDK surface. ≤ 200 KiB.
+   * `triggerType` is the trigger that fired THIS run — one of the declared
+   * `triggerTypes`, or `"manual"` / `"app"` for an operator or button run.
    */
   scriptSource: string;
 }

package/dist/linter.cjs

@@ -10,7 +10,7 @@
 
 "use strict";
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
 
 function _ruleForIdentifier(identifier, reason) {
@@ -579,10 +579,11 @@ function _manifestActionRules(manifest) {
     if (typeof a.name !== "string" || a.name.length === 0) {
       push("manifest.actions[].name must be a non-empty string");
     }
-    if (!validTriggers.has(a.triggerType)) {
-      push(`manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`);
-    } else if (a.triggerType === "schedule" && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
-      push("manifest.actions[].scheduleCron is required when triggerType is 'schedule'");
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
+      push(`manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`);
+    } else if (triggerTypes.includes("schedule") && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
+      push("manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'");
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
       push("manifest.actions[].scriptSource must be a non-empty string");
@@ -789,6 +790,49 @@ const CURRENCY_LABEL_RES = [
   /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
 ];
 
+// sc-4985 — soft warning: a widget that writes must decide what a signed-OUT
+// visitor sees. A write needs a signed-in app user, so an anonymous visitor
+// handed a live "Save" / "Book" / "Delete" button can only tap it and fail —
+// the failure the gate exists to spare them. Satisfied by any identity guard:
+// a negated or compared `.id`, or a `groupIds` / `roles` check. Reading
+// `useUser().id` purely as a VALUE (the USER-column write pattern) is NOT a
+// guard, which is why an operator has to follow it.
+//
+// Conservative on purpose: an unrelated `.id` comparison elsewhere in the
+// source silences the rule. A warning that occasionally stays quiet is far
+// cheaper than one that cries wolf on correct code.
+const _IDENTITY_GUARD_RES = [
+  // `!user.id` / `!user?.id`
+  /![\s(]*\w+\??\.id\b/,
+  // `user.id ?` / `&&` / `||` / `===` / `!==` / `==` / `!=`
+  /\w+\??\.id\s*(\?[^.]|&&|\|\||===|!==|==|!=)/,
+  // any group / role check the brief asked for
+  /\bgroupIds\b/,
+  /\broles\b/,
+];
+
+function _writeGatedOnUserRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "write-not-gated-on-user",
+      severity: "warning",
+      // Kept under ~210 chars: a finding is truncated at 300 downstream, and
+      // the fix instruction is the half worth keeping.
+      label:
+        `writes with useDatastoreMutation() but never checks who is signed ` +
+        `in - read useUser(), and when !user.id render the action inactive ` +
+        `with a "sign in" line instead of a live button that can only fail.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _hardcodedCurrencyLabelRules(source) {
   const code = _stripNonCode(source, { keepStrings: true });
   if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
@@ -1039,6 +1083,7 @@ function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/dist/linter.js

@@ -6,7 +6,7 @@
 // The banned-identifier list is derived from `CONTRACT.bannedApis` so the
 // system prompt, the linter, and the runtime allowlist agree.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 import { LUCIDE_ICON_NAMES, LUCIDE_VERSION } from "./lucideIconNames.js";
 
 // Per-identifier match rule. Most banned identifiers compile to a
@@ -674,16 +674,17 @@ function _manifestActionRules(manifest) {
     if (typeof a.name !== "string" || a.name.length === 0) {
       push("manifest.actions[].name must be a non-empty string");
     }
-    if (!validTriggers.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       push(
-        `manifest.actions[].triggerType must be one of ${[...validTriggers].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`,
       );
     } else if (
-      a.triggerType === "schedule" &&
+      triggerTypes.includes("schedule") &&
       (typeof a.scheduleCron !== "string" || !a.scheduleCron)
     ) {
       push(
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
@@ -921,6 +922,49 @@ const CURRENCY_LABEL_RES = [
   /(?:\d|\})\s*\b(?:SEK|NOK|DKK|EUR|GBP|USD|CHF|PLN|CZK|HUF|JPY|INR)\b/,
 ];
 
+// sc-4985 — soft warning: a widget that writes must decide what a signed-OUT
+// visitor sees. A write needs a signed-in app user, so an anonymous visitor
+// handed a live "Save" / "Book" / "Delete" button can only tap it and fail —
+// the failure the gate exists to spare them. Satisfied by any identity guard:
+// a negated or compared `.id`, or a `groupIds` / `roles` check. Reading
+// `useUser().id` purely as a VALUE (the USER-column write pattern) is NOT a
+// guard, which is why an operator has to follow it.
+//
+// Conservative on purpose: an unrelated `.id` comparison elsewhere in the
+// source silences the rule. A warning that occasionally stays quiet is far
+// cheaper than one that cries wolf on correct code.
+const _IDENTITY_GUARD_RES = [
+  // `!user.id` / `!user?.id`
+  /![\s(]*\w+\??\.id\b/,
+  // `user.id ?` / `&&` / `||` / `===` / `!==` / `==` / `!=`
+  /\w+\??\.id\s*(\?[^.]|&&|\|\||===|!==|==|!=)/,
+  // any group / role check the brief asked for
+  /\bgroupIds\b/,
+  /\broles\b/,
+];
+
+function _writeGatedOnUserRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "write-not-gated-on-user",
+      severity: "warning",
+      // Kept under ~210 chars: a finding is truncated at 300 downstream, and
+      // the fix instruction is the half worth keeping.
+      label:
+        `writes with useDatastoreMutation() but never checks who is signed ` +
+        `in - read useUser(), and when !user.id render the action inactive ` +
+        `with a "sign in" line instead of a live button that can only fail.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _hardcodedCurrencyLabelRules(source) {
   const code = _stripNonCode(source, { keepStrings: true });
   if (!code.includes(REQUEST_PAYMENT_CALL)) return [];
@@ -1201,6 +1245,7 @@ export function lintSource(source, options) {
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));
+  findings.push(..._writeGatedOnUserRules(source));
   // sc-4650 — soft warning: every payment refusal reported as "try again".
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));

package/dist/manifest.cjs

@@ -4,7 +4,7 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
@@ -152,15 +152,16 @@ function validateManifestActions(actions, errors) {
       seenKeys.add(a.key);
     }
     pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
-    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       errors.push(
-        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
       );
-    } else if (a.triggerType === "schedule") {
+    } else if (triggerTypes.includes("schedule")) {
       pushIf(
         errors,
         isNonEmptyString(a.scheduleCron),
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (!isNonEmptyString(a.scriptSource)) {

package/dist/manifest.js

@@ -4,7 +4,7 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseActionTriggerTypes } from "./contract.js";
 
 const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
 
@@ -152,15 +152,16 @@ function validateManifestActions(actions, errors) {
       seenKeys.add(a.key);
     }
     pushIf(errors, isNonEmptyString(a.name), "manifest.actions[].name must be a non-empty string");
-    if (!VALID_ACTION_TRIGGERS.has(a.triggerType)) {
+    const triggerTypes = normaliseActionTriggerTypes(a);
+    if (triggerTypes === null) {
       errors.push(
-        `manifest.actions[].triggerType must be one of ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...VALID_ACTION_TRIGGERS].join(", ")}`,
       );
-    } else if (a.triggerType === "schedule") {
+    } else if (triggerTypes.includes("schedule")) {
       pushIf(
         errors,
         isNonEmptyString(a.scheduleCron),
-        "manifest.actions[].scheduleCron is required when triggerType is 'schedule'",
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
       );
     }
     if (!isNonEmptyString(a.scriptSource)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.88.0",
+  "version": "0.90.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js"
   },
   "engines": {
     "node": ">=18"