@colixsystems/widget-sdk 0.114.0 → 0.115.0

package/README.md

@@ -49,7 +49,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options?)` | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
-| **DATASTORE** | `useCanWrite(tableId, options?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "is this caller signed in AND permitted", reading the same table-ACL answer the write endpoint enforces. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
+| **DATASTORE** | `useCanWrite(tableId, options?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type? })` | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
@@ -72,6 +72,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.112.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.115.0 (contract unchanged)
+
+**`write-not-gated-on-user` now accepts a `useCanWrite()` gate — a widget may be opened to logged-out visitors (sc-6593).** The rule (added in 0.89.0, below) flagged any `useDatastoreMutation` write that carried no identity guard, and only a `.id` / `groupIds` / `roles` check counted as one. That encoded "a write needs a signed-in app user" as a platform fact, which it is not: a table whose permissions grant **Create** to *Everyone (anonymous + signed-in)* accepts a write from a logged-out visitor, and `useCanWrite(tableId)` answers `true` for them.
+
+So a widget gated on `useCanWrite` alone — the correct shape for a public tally, a guest sign-up sheet, or an open feedback form — used to trip the warning that steers the AI widget agent's repair loop back to identity gating, making the sign-in requirement impossible for an author to remove. It is now recognised as a gate, and its finding label names it first.
+
+Nothing else changes: a widget with **no** gate at all is still flagged, `useUser().id` read purely as a VALUE still does not satisfy the rule, and the severity is still `warning` (never publish-blocking). Identity gating remains the right default for almost every write — this only stops the linter from arguing against the one case where it isn't.
+
+When you take the `useCanWrite`-only route, omit the USER column for a guest (`if (user.id) payload[byField] = user.id;`) — an anonymous row records no author, so per-person limits and "my entries" views cannot work for one.
+
 ### What's new in 0.113.0 (contract 1.86.0)
 
 **New `useCamera()` hook — take a photo or pick one from the device library.** A new CORE hook reading a new `camera` capability on the existing `ctx.device` slice. Returns `{ asset, loading, error, supported, capture, pick, reset }`. Capture is **imperative** — call `capture()` or `pick()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the permission prompt on a gesture, so it NEVER opens on mount. `options` (`{ allowsEditing, quality }`) pass through to the host. It needs **no manifest scope** and **no `requestedScopes` entry**.

package/dist/linter.cjs

@@ -928,12 +928,17 @@ const CURRENCY_LABEL_RES = [
 ];
 
 // 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.
+// visitor sees. A visitor handed a live "Save" / "Book" / "Delete" button the
+// table will refuse 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 follows.
+//
+// sc-6593 — `useCanWrite(tableId)` satisfies it too, and answers better: it
+// reads the ACL the write endpoint enforces, so it goes live for whoever may
+// write. Since a table granting Create to EVERYONE accepts an anonymous write
+// (sc-5229), demanding identity here would flag the only correct way to build
+// the logged-out-friendly widget an author explicitly asked for.
 //
 // Conservative on purpose: an unrelated `.id` comparison elsewhere in the
 // source silences the rule. A warning that occasionally stays quiet is far
@@ -952,6 +957,7 @@ function _writeGatedOnUserRules(source) {
   const code = _stripNonCode(source);
   const call = /\buseDatastoreMutation\s*\(/.exec(code);
   if (!call) return [];
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
   if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
   const line = code.slice(0, call.index).split(/\r?\n/).length;
   return [
@@ -961,9 +967,9 @@ function _writeGatedOnUserRules(source) {
       // 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.`,
+        `writes with useDatastoreMutation() but never checks who may write ` +
+        `- gate on useCanWrite(tableId), or useUser() when the action needs ` +
+        `a signed-in user, and render the control inactive, never live-but-doomed.`,
       line,
       snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
     },

package/dist/linter.js

@@ -1077,12 +1077,17 @@ const CURRENCY_LABEL_RES = [
 ];
 
 // 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.
+// visitor sees. A visitor handed a live "Save" / "Book" / "Delete" button the
+// table will refuse 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 follows.
+//
+// sc-6593 — `useCanWrite(tableId)` satisfies it too, and answers better: it
+// reads the ACL the write endpoint enforces, so it goes live for whoever may
+// write. Since a table granting Create to EVERYONE accepts an anonymous write
+// (sc-5229), demanding identity here would flag the only correct way to build
+// the logged-out-friendly widget an author explicitly asked for.
 //
 // Conservative on purpose: an unrelated `.id` comparison elsewhere in the
 // source silences the rule. A warning that occasionally stays quiet is far
@@ -1101,6 +1106,7 @@ function _writeGatedOnUserRules(source) {
   const code = _stripNonCode(source);
   const call = /\buseDatastoreMutation\s*\(/.exec(code);
   if (!call) return [];
+  if (/\buseCanWrite\s*\(/.test(code)) return [];
   if (_IDENTITY_GUARD_RES.some((re) => re.test(code))) return [];
   const line = code.slice(0, call.index).split(/\r?\n/).length;
   return [
@@ -1110,9 +1116,9 @@ function _writeGatedOnUserRules(source) {
       // 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.`,
+        `writes with useDatastoreMutation() but never checks who may write ` +
+        `- gate on useCanWrite(tableId), or useUser() when the action needs ` +
+        `a signed-in user, and render the control inactive, never live-but-doomed.`,
       line,
       snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.114.0",
+  "version": "0.115.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",