@colixsystems/widget-sdk 0.35.0 → 0.36.0

package/README.md

@@ -34,7 +34,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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) |
 | **FILES** (`ctx.files`) | `useFile(id)` | `{ url, file, loading, error, refetch }` | `ctx.files.get` — no scope |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (mutations also `users.write:*`) |
+| **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (edits also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
@@ -47,7 +47,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.35.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.36.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.36.0
+
+**Explicit `users.delete:*` scope for destructive user removal (SC-902).** `useUsers().remove(userId)` now requires `users.delete:*` in the manifest's `requestedScopes` — separated from the edit-style `users.write:*`. The backend gates `DELETE /app/users/:id` on a dedicated SystemAcl `users.delete` capability, so an operator can authorise (or withhold) permanent removal independently of inviting / deactivating. New linter rule **`scope-required-for-user-delete`** flags a widget that calls `.remove()` without declaring `users.delete:*` (`.invite()` / `.deactivate()` / `.reactivate()` still map to `users.write:*`). The built-in **User Management** widget adds the scope. **`CONTRACT.version` → `1.26.0`** (additive: one new scope verb + one linter rule). No hook signature changed.
 
 ### What's new in 0.35.0
 
@@ -375,7 +379,9 @@ The matching manifest declares the scopes:
 ```js
 {
   // ...
-  requestedScopes: ["users.read:*", "users.write:*", "groups.read:*", "groups.write:*"],
+  // `remove(u.id)` above needs `users.delete:*` (SC-902) — the destructive
+  // delete is gated separately from the edit-style `users.write:*`.
+  requestedScopes: ["users.read:*", "users.write:*", "users.delete:*", "groups.read:*", "groups.write:*"],
 }
 ```
 
@@ -448,6 +454,38 @@ import { lintSource } from "@colixsystems/widget-sdk/linter";
 const report = lintSource(source);
 ```
 
+## Local dev loop (`appstudio-widget dev`)
+
+Author a marketplace widget with live reload instead of the publish → submit →
+review → install round-trip:
+
+```sh
+appstudio-widget dev path/to/widget.jsx --port 4400
+```
+
+This transpiles the entry (the **same** Sucrase JSX pass the publish path runs)
+and serves it over `http://127.0.0.1:4400`:
+
+| Route | Purpose |
+| ----- | ------- |
+| `GET /widget.mjs` | the transpiled entry — an ES module the Studio loads exactly like a published `widget.mjs` |
+| `GET /manifest.json` | the manifest (from `--manifest`, else a sibling `manifest.json`); only consulted for a bare-component bundle |
+| `GET /__dev/events` | Server-Sent-Events stream that emits `reload` on every source change |
+| `GET /__dev/health` | `{ ok, manifestId }` |
+
+Then, in the Studio Builder (dev mode only), open the **Dev widgets** panel in
+the palette and paste `http://127.0.0.1:4400`. The widget loads through the
+real runtime loader (same import-rewrite, host-shim, and export-shape gates a
+published bundle hits) and hot-reloads onto the canvas on every save.
+
+- **v1 serves a single-file entry.** Split-impl widgets (`widget.web.jsx` +
+  `widget.native.jsx` with shared `./relative.jsx` helpers) need a real build
+  step; the dev server reports relative imports rather than serving a module
+  the browser can't resolve.
+- `dev` lazily requires the optional `sucrase` dependency. In this monorepo it
+  is already present; in a standalone widget project run `npm i -D sucrase`.
+- Lint findings print to the terminal on each change but never block serving.
+
 ## Why no TypeScript dependency?
 
 The package is plain ESM JavaScript with hand-written `.d.ts` ambient types. Consumers using TypeScript get full IntelliSense; consumers using JavaScript pay nothing.

package/dist/cli.js

@@ -1,21 +1,52 @@
 #!/usr/bin/env node
-// CLI entry for `appstudio-widget lint <path>`.
+// CLI entry for `appstudio-widget`.
+//   appstudio-widget lint <path>                          — validate a widget source
+//   appstudio-widget dev <entry.jsx> [--port N] [--manifest path]
+//                                                          — REQ-WSDK-DEVKIT local dev server
 
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { argv, exit, stderr, stdout } from "node:process";
 import { lintSource } from "./linter.js";
+import { startDevServer } from "./devserver.js";
 
 function usage() {
-  stderr.write("Usage: appstudio-widget lint <path>\n");
+  stderr.write(
+    "Usage:\n" +
+      "  appstudio-widget lint <path>\n" +
+      "  appstudio-widget dev <entry.jsx> [--port <n>] [--manifest <path>]\n",
+  );
   exit(2);
 }
 
-const args = argv.slice(2);
-if (args.length === 0) usage();
-const [cmd, ...rest] = args;
+// Minimal flag parser: pulls `--key value` / `--key=value` out of the args and
+// returns the remaining positionals. No external dependency.
+function parseFlags(args) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          flags[a.slice(2)] = next;
+          i += 1;
+        } else {
+          flags[a.slice(2)] = true;
+        }
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { flags, positionals };
+}
 
-if (cmd === "lint") {
+function runLint(rest) {
   if (rest.length === 0) usage();
   const filePath = resolve(rest[0]);
   let source;
@@ -35,6 +66,58 @@ if (cmd === "lint") {
     stderr.write(`  [${f.rule}] line ${f.line}: ${f.label}\n    ${f.snippet}\n`);
   }
   exit(1);
+}
+
+async function runDev(rest) {
+  const { flags, positionals } = parseFlags(rest);
+  if (positionals.length === 0) usage();
+  const entry = positionals[0];
+  const port = flags.port ? Number(flags.port) : 4400;
+  if (Number.isNaN(port)) {
+    stderr.write(`Invalid --port: ${flags.port}\n`);
+    exit(2);
+  }
+  const manifest = typeof flags.manifest === "string" ? flags.manifest : null;
+
+  let handle;
+  try {
+    handle = await startDevServer({
+      entry,
+      port,
+      manifest,
+      log: (line) => stdout.write(`  ${line}\n`),
+    });
+  } catch (err) {
+    stderr.write(`${err.message}\n`);
+    exit(1);
+  }
+
+  stdout.write(
+    `\nappstudio-widget dev — serving ${resolve(entry)}\n` +
+      `  bundle:   ${handle.url}/widget.mjs\n` +
+      `  manifest: ${handle.url}/manifest.json\n` +
+      `  reload:   ${handle.url}/__dev/events (SSE)\n` +
+      (handle.manifestId ? `  id:       ${handle.manifestId}\n` : "") +
+      `\nIn the Studio Builder (dev mode), open the "Dev widgets" panel and add:\n` +
+      `  ${handle.url}\n` +
+      `Edits to the entry hot-reload the widget on the canvas. Ctrl+C to stop.\n\n`,
+  );
+
+  const shutdown = () => {
+    handle.close().finally(() => exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+const args = argv.slice(2);
+if (args.length === 0) usage();
+const [cmd, ...rest] = args;
+
+if (cmd === "lint") {
+  runLint(rest);
+} else if (cmd === "dev") {
+  runDev(rest);
 } else {
   stderr.write(`Unknown command "${cmd}"\n`);
   usage();

package/dist/contract.cjs

@@ -359,12 +359,14 @@ const HOOKS = [
   },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
-  // Reads need `users.read:*` scope; mutations additionally need
-  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
-  // and returns the resulting AppUserInvite row (the email is sent by the
-  // host). Mutating users from a widget requires the corresponding
-  // SystemAcl `users.write` capability grant in the tenant; widgets that
-  // only call read methods need only `users.read:*`.
+  // Reads need `users.read:*` scope; edit-style mutations (invite /
+  // deactivate / reactivate) additionally need `users.write:*`, and the
+  // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
+  // call accepts `{ email, name, groupIds? }` and returns the resulting
+  // AppUserInvite row (the email is sent by the host). Mutating users from
+  // a widget requires the corresponding SystemAcl capability grant in the
+  // tenant (`users.write` for edits, `users.delete` for removal); widgets
+  // that only call read methods need only `users.read:*`.
   {
     name: "useUsers",
     signature: "useUsers(query?)",
@@ -374,7 +376,9 @@ const HOOKS = [
       "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
-      "scope; mutations need users.write:*. The `invite` call accepts " +
+      "scope; edit-style mutations (invite/deactivate/reactivate) need " +
+      "users.write:*, and the destructive remove() additionally needs " +
+      "users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
       "(the email is sent by the host).",
     returnShape: {
@@ -892,7 +896,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
       "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
     fields: { users: "object", groups: "object", bankid: "object" },
   },
@@ -1447,7 +1451,15 @@ const CONTRACT = deepFreeze({
   //    setVisibility). Both read the existing `ctx.filestore`; the underlying
   //    `filestore-client` 0.5.0 made shares folder-scoped + added
   //    `signatures.roster`. No existing hook changed.
-  version: "1.25.0",
+  //
+  // 1.26.0: additive (SC-902) — new `users.delete:*` scope verb. The
+  //    destructive `useUsers().remove()` now requires `users.delete:*` in
+  //    requestedScopes (backed by the SystemAcl `users.delete` capability
+  //    on DELETE /app/users/:id), separated from the edit-style
+  //    `users.write:*`. New linter rule `scope-required-for-user-delete`
+  //    flags a widget that calls `.remove()` without declaring the scope.
+  //    No hook signature changed; `useUsers().remove` is unchanged.
+  version: "1.26.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -359,12 +359,14 @@ const HOOKS = [
   },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
-  // Reads need `users.read:*` scope; mutations additionally need
-  // `users.write:*`. The `invite` call accepts `{ email, name, groupIds? }`
-  // and returns the resulting AppUserInvite row (the email is sent by the
-  // host). Mutating users from a widget requires the corresponding
-  // SystemAcl `users.write` capability grant in the tenant; widgets that
-  // only call read methods need only `users.read:*`.
+  // Reads need `users.read:*` scope; edit-style mutations (invite /
+  // deactivate / reactivate) additionally need `users.write:*`, and the
+  // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
+  // call accepts `{ email, name, groupIds? }` and returns the resulting
+  // AppUserInvite row (the email is sent by the host). Mutating users from
+  // a widget requires the corresponding SystemAcl capability grant in the
+  // tenant (`users.write` for edits, `users.delete` for removal); widgets
+  // that only call read methods need only `users.read:*`.
   {
     name: "useUsers",
     signature: "useUsers(query?)",
@@ -374,7 +376,9 @@ const HOOKS = [
       "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
-      "scope; mutations need users.write:*. The `invite` call accepts " +
+      "scope; edit-style mutations (invite/deactivate/reactivate) need " +
+      "users.write:*, and the destructive remove() additionally needs " +
+      "users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
       "(the email is sent by the host).",
     returnShape: {
@@ -892,7 +896,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
       "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
     fields: { users: "object", groups: "object", bankid: "object" },
   },
@@ -1447,7 +1451,15 @@ const CONTRACT = deepFreeze({
   //    setVisibility). Both read the existing `ctx.filestore`; the underlying
   //    `filestore-client` 0.5.0 made shares folder-scoped + added
   //    `signatures.roster`. No existing hook changed.
-  version: "1.25.0",
+  //
+  // 1.26.0: additive (SC-902) — new `users.delete:*` scope verb. The
+  //    destructive `useUsers().remove()` now requires `users.delete:*` in
+  //    requestedScopes (backed by the SystemAcl `users.delete` capability
+  //    on DELETE /app/users/:id), separated from the edit-style
+  //    `users.write:*`. New linter rule `scope-required-for-user-delete`
+  //    flags a widget that calls `.remove()` without declaring the scope.
+  //    No hook signature changed; `useUsers().remove` is unchanged.
+  version: "1.26.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/devserver.js

@@ -0,0 +1,350 @@
+// REQ-WSDK-DEVKIT: local widget dev server backing `appstudio-widget dev`.
+//
+// Goal: a tight author loop for marketplace-widget development that mirrors the
+// built-in widgets' Vite-HMR experience WITHOUT the publish → submit → review →
+// install round-trip. The Studio Builder loads the widget this server serves
+// through the EXACT runtime loader path it uses for published bundles (fetch
+// text → rewrite bare imports to host shims → blob `import()` → register), so a
+// widget that renders under `dev` will publish unchanged.
+//
+// What this module owns:
+//   * transpile the single-file entry JSX→JS with the SAME Sucrase pass the
+//     publish path runs (`transforms:["jsx"]`, automatic runtime, production),
+//     so the served `/widget.mjs` is byte-for-byte the shape the loader expects;
+//   * serve it (plus a best-effort `/manifest.json`) over HTTP with permissive
+//     CORS for the Vite dev origin;
+//   * a Server-Sent-Events channel (`/__dev/events`) that emits `reload` on
+//     every source change so the Builder re-fetches + re-registers + re-renders;
+//   * re-lint (reusing `lintSource`) on every change, printing findings without
+//     blocking — the author iterates against the real runtime.
+//
+// Pure Node (node:http / node:fs / node:path) plus a lazily-imported `sucrase`
+// (an optional dependency) — the published SDK's runtime + types carry no extra
+// weight; only the dev command pulls the transform in.
+
+import { createServer } from "node:http";
+import { readFileSync, existsSync, watch } from "node:fs";
+import { resolve, dirname, join, sep } from "node:path";
+import { lintSource } from "./linter.js";
+
+// Bare-import / relative-import detection. The loader rewrites bare specifiers
+// in the ENTRY to client-side blob shims, so they resolve fine. Relative
+// imports do NOT — a sibling fetched over HTTP can't be handed the loader's
+// blob shims for its own bare imports — so v1 refuses them with guidance
+// rather than serving a module the browser silently fails to resolve.
+const RELATIVE_IMPORT_RE =
+  /(?:^|\n)\s*(?:import|export)[^;\n]*?from\s*['"](\.\.?\/[^'"]+)['"]/g;
+
+/**
+ * Lazily resolve `sucrase`'s `transform`. Kept out of the module's static
+ * imports so the published SDK (runtime + types) never forces the dependency;
+ * only `appstudio-widget dev` reaches this path. Throws a friendly install
+ * hint when the package isn't present.
+ *
+ * @returns {Promise<(code: string, opts: object) => { code: string }>}
+ */
+export async function loadTransform() {
+  try {
+    const mod = await import("sucrase");
+    return mod.transform;
+  } catch {
+    throw new Error(
+      "`appstudio-widget dev` needs the optional `sucrase` dependency.\n" +
+        "Install it in your widget project:\n" +
+        "  npm install --save-dev sucrase",
+    );
+  }
+}
+
+/**
+ * Transpile a widget source string JSX→JS using the SAME options the publish
+ * path uses, so the dev bundle and the published bundle are transpiled
+ * identically (automatic jsx-runtime form the loader shims).
+ *
+ * @param {(code: string, opts: object) => { code: string }} transform
+ * @param {string} source
+ * @returns {string}
+ */
+export function transpile(transform, source) {
+  return transform(source, {
+    transforms: ["jsx"],
+    jsxRuntime: "automatic",
+    production: true,
+  }).code;
+}
+
+/**
+ * Find relative (`./` / `../`) import specifiers in a source string. Used to
+ * reject split-impl bundles in v1 with a clear message instead of serving a
+ * module the browser can't resolve.
+ *
+ * @param {string} source
+ * @returns {string[]} unique relative specifiers
+ */
+export function findRelativeImports(source) {
+  const out = new Set();
+  let m;
+  RELATIVE_IMPORT_RE.lastIndex = 0;
+  while ((m = RELATIVE_IMPORT_RE.exec(source))) out.add(m[1]);
+  return Array.from(out);
+}
+
+/**
+ * Best-effort manifest resolution for bare-component bundles (the loader's
+ * shape B, where the manifest does NOT ride in the bundle). Marketplace
+ * widgets authored with `defineWidget({ manifest, component })` (shape A)
+ * carry their manifest inside the bundle and don't need this — so a missing
+ * manifest file is not an error here, just `null`.
+ *
+ * Resolution order: explicit `--manifest` path, then a sibling
+ * `appstudio.manifest.json` / `manifest.json` next to the entry.
+ *
+ * @param {string} entryPath  absolute path to the widget entry
+ * @param {string|null} manifestPath  explicit `--manifest` path (or null)
+ * @returns {object|null} parsed manifest, or null when none found
+ */
+export function resolveManifest(entryPath, manifestPath) {
+  const candidates = [];
+  if (manifestPath) candidates.push(resolve(manifestPath));
+  const dir = dirname(entryPath);
+  candidates.push(join(dir, "appstudio.manifest.json"));
+  candidates.push(join(dir, "manifest.json"));
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, "utf8"));
+      } catch (err) {
+        throw new Error(`Could not parse manifest at ${p}: ${err.message}`);
+      }
+    }
+  }
+  return null;
+}
+
+function setCors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "*");
+}
+
+/**
+ * Create the dev HTTP server (without listening). Exposed separately from
+ * `startDevServer` so tests can inject a `transform` and listen on an
+ * ephemeral port. The returned object carries the `http.Server`, a
+ * `broadcastReload()` the watcher calls, and a `manifestId` getter for the
+ * health route + CLI banner.
+ *
+ * @param {object} opts
+ * @param {string} opts.entryPath  absolute path to the widget entry
+ * @param {string|null} [opts.manifestPath]  explicit `--manifest` path
+ * @param {(code: string, opts: object) => { code: string }} opts.transform
+ * @param {(msg: string) => void} [opts.onLint]  receives lint summary lines
+ */
+export function createDevServer({ entryPath, manifestPath = null, transform, onLint }) {
+  if (!transform) throw new Error("createDevServer: transform is required");
+  const entryDir = dirname(entryPath);
+  const sseClients = new Set();
+  let manifest = null;
+  try {
+    manifest = resolveManifest(entryPath, manifestPath);
+  } catch (err) {
+    // A malformed manifest file shouldn't crash the server — surface it and
+    // serve shape-A bundles (manifest in the bundle) regardless.
+    if (onLint) onLint(`manifest: ${err.message}`);
+  }
+  const manifestId = manifest?.id || null;
+
+  function readEntry() {
+    return readFileSync(entryPath, "utf8");
+  }
+
+  function serveWidget(res) {
+    let source;
+    try {
+      source = readEntry();
+    } catch (err) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end(`Could not read entry ${entryPath}: ${err.message}`);
+      return;
+    }
+    const relatives = findRelativeImports(source);
+    if (relatives.length > 0) {
+      const msg =
+        `Entry imports relative modules (${relatives.join(", ")}). ` +
+        "v1 of `appstudio-widget dev` serves a single-file entry only — " +
+        "bundle split-impl widgets with a real build step (esbuild/rollup) " +
+        "and load the built widget.mjs, or inline the helpers into the entry.";
+      res.writeHead(422, { "Content-Type": "text/plain" });
+      res.end(msg);
+      return;
+    }
+    let code;
+    try {
+      code = transpile(transform, source);
+    } catch (err) {
+      // Surface the transpile error as the module body so the browser console
+      // (and the Builder dev panel) shows the real syntax error, not an opaque
+      // "failed to fetch dynamically imported module".
+      const safe = JSON.stringify(String(err.message || err));
+      res.writeHead(200, { "Content-Type": "text/javascript" });
+      res.end(`throw new Error(${safe});`);
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/javascript" });
+    res.end(code);
+  }
+
+  function serveManifest(res) {
+    // Re-read so an edited sibling manifest.json is picked up live.
+    let m = null;
+    try {
+      m = resolveManifest(entryPath, manifestPath);
+    } catch {
+      m = null;
+    }
+    if (!m) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ code: "MANIFEST_NOT_FOUND" }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(m));
+  }
+
+  function serveEvents(req, res) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "Access-Control-Allow-Origin": "*",
+    });
+    res.write(": connected\n\n");
+    sseClients.add(res);
+    req.on("close", () => sseClients.delete(res));
+  }
+
+  const server = createServer((req, res) => {
+    setCors(res);
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const url = (req.url || "/").split("?")[0];
+    if (url === "/widget.mjs") return serveWidget(res);
+    if (url === "/manifest.json") return serveManifest(res);
+    if (url === "/__dev/events") return serveEvents(req, res);
+    if (url === "/__dev/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, manifestId }));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  });
+
+  function broadcastReload() {
+    for (const res of sseClients) {
+      try {
+        res.write("event: reload\ndata: {}\n\n");
+      } catch {
+        sseClients.delete(res);
+      }
+    }
+  }
+
+  function lintEntry() {
+    let source;
+    try {
+      source = readEntry();
+    } catch {
+      return;
+    }
+    const { ok, findings } = lintSource(source);
+    if (onLint) {
+      if (ok) onLint("lint: clean");
+      else {
+        onLint(`lint: ${findings.length} finding(s)`);
+        for (const f of findings) onLint(`  [${f.rule}] line ${f.line}: ${f.label}`);
+      }
+    }
+  }
+
+  return {
+    server,
+    broadcastReload,
+    lintEntry,
+    entryDir,
+    get manifestId() {
+      return manifest?.id || null;
+    },
+    sseClientCount() {
+      return sseClients.size;
+    },
+  };
+}
+
+/**
+ * Resolve sucrase, create the dev server, start listening, watch the entry's
+ * directory, and wire change → re-lint + reload broadcast. Returns the running
+ * dev-server handle. The caller (the CLI) owns logging the banner.
+ *
+ * @param {object} opts
+ * @param {string} opts.entry  path to the widget entry (relative or absolute)
+ * @param {number} [opts.port]
+ * @param {string|null} [opts.manifest]  explicit manifest path
+ * @param {(line: string) => void} [opts.log]
+ * @returns {Promise<{ server: import("node:http").Server, port: number, url: string, manifestId: string|null, close: () => Promise<void> }>}
+ */
+export async function startDevServer({ entry, port = 4400, manifest = null, log = () => {} }) {
+  const entryPath = resolve(entry);
+  if (!existsSync(entryPath)) {
+    throw new Error(`Entry not found: ${entryPath}`);
+  }
+  const transform = await loadTransform();
+  const dev = createDevServer({
+    entryPath,
+    manifestPath: manifest,
+    transform,
+    onLint: log,
+  });
+
+  await new Promise((res, rej) => {
+    dev.server.once("error", rej);
+    dev.server.listen(port, "127.0.0.1", res);
+  });
+  const actualPort = dev.server.address().port;
+  // Advertise 127.0.0.1, not "localhost": the server binds the IPv4 loopback,
+  // but "localhost" resolves to IPv6 (::1) first on Windows, so a browser/CLI
+  // hitting http://localhost:<port> would fail to connect. 127.0.0.1 is
+  // unambiguous, loopback-only (not LAN-exposed), and works cross-platform.
+  const url = `http://127.0.0.1:${actualPort}`;
+
+  // Watch the entry's directory (non-recursive — reliable cross-platform).
+  // Debounce bursts (editors emit multiple events per save) before linting +
+  // broadcasting a single reload.
+  let timer = null;
+  const watcher = watch(dev.entryDir, (_event, filename) => {
+    if (filename && !/\.(jsx?|json)$/.test(String(filename))) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      dev.lintEntry();
+      dev.broadcastReload();
+      log(`reload → ${dev.sseClientCount()} client(s)`);
+    }, 60);
+  });
+
+  // Guard against the watched path not existing under some sandboxes.
+  watcher.on("error", (err) => log(`watch error: ${err.message}`));
+
+  // Initial lint pass so the author sees findings immediately.
+  dev.lintEntry();
+
+  async function close() {
+    watcher.close();
+    await new Promise((res) => dev.server.close(res));
+  }
+
+  return { server: dev.server, port: actualPort, url, manifestId: dev.manifestId, close };
+}

package/dist/linter.cjs

@@ -196,7 +196,12 @@ function _hostApiUrlRules(source) {
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
 // linter.js for the rationale comment. The two files must stay in
 // lockstep (the contract test asserts behaviour-equivalence).
-const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate", "remove"];
+const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate"];
+// SC-902 — destructive user removal is gated on the dedicated
+// `users.delete` capability, NOT `users.write`. A widget that calls
+// useUsers().remove() must declare `users.delete:*` so the static contract
+// matches the backend gate on DELETE /api/v1/app/users/:userId.
+const USER_DELETE_METHODS = ["remove"];
 const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
 const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
 
@@ -238,6 +243,7 @@ function _scopeRules(source, manifest) {
 
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
+  let firedUsersDelete = false;
   let firedGroupsWrite = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -262,6 +268,28 @@ function _scopeRules(source, manifest) {
         }
       }
     }
+    // SC-902 — destructive removal needs `users.delete:*`, separately from
+    // the edit-style write scope above.
+    if (usesUsersHook && !firedUsersDelete) {
+      for (const m of USER_DELETE_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          if (
+            !declared.has("users.delete:*") &&
+            !declared.has("users.delete")
+          ) {
+            findings.push({
+              rule: "scope-required-for-user-delete",
+              label: `useUsers().${m}() requires \`users.delete:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedUsersDelete = true;
+          break;
+        }
+      }
+    }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
         const re = new RegExp(`\\.${m}\\s*\\(`);

package/dist/linter.js

@@ -252,7 +252,12 @@ function _hostApiUrlRules(source) {
 // AST-free; an author whose code happened to spell `.invite(` for an
 // unrelated reason can opt out with a `// @appstudio-skip-scope-check`
 // trailing comment on the offending line.
-const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate", "remove"];
+const USER_MUTATION_METHODS = ["invite", "deactivate", "reactivate"];
+// SC-902 — destructive user removal is gated on the dedicated
+// `users.delete` capability, NOT `users.write`. A widget that calls
+// useUsers().remove() must declare `users.delete:*` so the static contract
+// matches the backend gate on DELETE /api/v1/app/users/:userId.
+const USER_DELETE_METHODS = ["remove"];
 const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
 const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
 
@@ -294,6 +299,7 @@ function _scopeRules(source, manifest) {
 
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
+  let firedUsersDelete = false;
   let firedGroupsWrite = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -318,6 +324,28 @@ function _scopeRules(source, manifest) {
         }
       }
     }
+    // SC-902 — destructive removal needs `users.delete:*`, separately from
+    // the edit-style write scope above.
+    if (usesUsersHook && !firedUsersDelete) {
+      for (const m of USER_DELETE_METHODS) {
+        const re = new RegExp(`\\.${m}\\s*\\(`);
+        if (re.test(line)) {
+          if (
+            !declared.has("users.delete:*") &&
+            !declared.has("users.delete")
+          ) {
+            findings.push({
+              rule: "scope-required-for-user-delete",
+              label: `useUsers().${m}() requires \`users.delete:*\` in manifest.requestedScopes`,
+              line: i + 1,
+              snippet: line.trim().slice(0, 200),
+            });
+          }
+          firedUsersDelete = true;
+          break;
+        }
+      }
+    }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
         const re = new RegExp(`\\.${m}\\s*\\(`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js"
   },
   "engines": {
     "node": ">=18"
@@ -65,6 +65,9 @@
       "optional": true
     }
   },
+  "optionalDependencies": {
+    "sucrase": "^3.35.0"
+  },
   "keywords": [
     "appstudio",
     "widget",