@plitzi/sdk-mcp 0.38.14 → 0.38.15

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @plitzi/sdk-mcp
 
+## 0.38.15
+
+### Patch Changes
+
+- 6cdd5cf: ## Security
+
+  - **A write another site caused is refused, cookie or none** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): the page
+    server guarded nothing it answers past `/auth` — a server action (`/_action`), a realtime publish, a space's `/fn/`
+    route, its runtime's endpoints, the deployment's own `data` stages, the adapter-only `loginPath`, `logoutPath` and
+    `exchangePath`. A plain `text/plain` POST from any page open in the same browser ran them, with the visitor's session
+    cookie when there was one (`SameSite=None` off this machine) and, in a project nobody signs in to, as whoever holds
+    the server's own credentials. Every unsafe request a browser says another site caused (`Sec-Fetch-Site: cross-site`,
+    or a foreign `Origin`) is now refused `403 reason: 'foreign'`, saying how to allow it: `crossSiteWrites.origins`
+    (with `auth`, `identity.platformOrigins` too) and `crossSiteWrites.paths` for a form other sites post to by design.
+    `Authorization`, and callers that are not browsers — webhooks, scripts — pass as before. One rule for this and the
+    sign-in check (`crossSiteRequest`, `csrf.ts`). A self-hosted runtime's endpoints now sit where the platform forwards a
+    space's — after the auth chain and this guard (`data`, was `preAuth`).
+
+  ## Testing
+  - **`page check` and `page shot` anywhere the project is served** (`@plitzi/cli`): `--url <origin>` for a second server
+    of it, staging or a deploy, instead of `npm start`'s port; `page check --space <module>` holds the pages to that space
+    instead of the project's — an agent's page — authored with `authorIsolated`.
+  - **A route with a query is checked as its page** (`@plitzi/cli`): `page check "/?v=2"` matched the query as part of
+    the path, found no page, and checked the space's "not found" page in its place.
+
+  - **What an element that chooses its children draws is checked** (`@plitzi/sdk-authoring`, `@plitzi/cli`): with
+    `choosesChildren`, the page checks owed none of its children — and checked none of them either: a dashboard drawing
+    three panels reported `checked: 1`. Each child it may draw, and what is inside one under no condition of its own,
+    now carries `shownWith` (the child it comes with) on its handle: once that child is on screen it and everything
+    named in it are owed like the rest of the page, and `checked` counts them. `onScreenIfChosen(handles, page)` lists
+    them.
+  - **A page that met a server error is looked at once more** (`@plitzi/cli`): `page check` and `verify` failed a page
+    for a `500` from somebody else's service having a bad second (`/fn/<space>/weather`), and passed on the next run with
+    nothing changed. A page whose requests got a `5xx` is checked again once; its report is the second look, and says
+    what failed the first time (`retriedAfter`). A `4xx` fails the same way twice, and is never retried.
+
+  ## Plugins
+  - **`useNotify`** (`@plitzi/plitzi-sdk`): a plugin shows the page's notifications — `notify('Deleted 79 recordings', {
+appearance: 'danger' })` — the same toasts an `addNotification` step shows, in the space's theme and `notifications`
+    look, with no trigger, flow or `window` event of the space's to wire. The step's vocabulary (`NOTIFICATION_PLACEMENTS`,
+    `NOTIFICATION_APPEARANCES`, `NOTIFICATION_DEFAULTS`) is one list in `@plitzi/sdk-shared`, read by both.
+  - **`appearance: 'danger'` looks like one** (`@plitzi/plitzi-sdk`): it reached the toast library as a type it does not
+    know, so a danger notification showed neither the error icon nor the colour `notifications.danger` sets.
+    A value a notification does not take — from a flow, or a plugin in plain JavaScript — is set aside by name and said
+    in the console, rather than shown as the default in silence (`readNotificationOptions`, `@plitzi/sdk-shared`).
+  - **`useServerAction`** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-authoring`, `@plitzi/sdk-interactions`,
+    `@plitzi/sdk-server`): a plugin runs one of the space's server actions, awaited —
+    `useServerAction<typeof habitDone>('habits-done')({ id })` answers `{ ok, output }` or `{ ok: false, reason, error }`
+    — through the `runServerAction` step itself: the same access, refusals, session handling and dev-tools entry.
+    `defineAction` keeps the literal types of its `call` way in, so the input is typed by the fields it declares (the
+    required ones required); `taskAction` types both ends from the task's `run`, and `FunctionTask<T, R>` takes what
+    `run` answers. `CallInputOf` / `CallOutputOf` read them. One operation is one action, never a `case` in one route.
+    What a run answers is typed (`ServerActionStatus`): a status the server never uses reads as a run that did not
+    complete, never as one that did.
+    The key those types ride under (`CALL_TYPES`) is exported, by `@plitzi/sdk-shared` and `@plitzi/sdk-authoring` with
+    `TypedActionEntry`, `CallInputOf` and `CallOutputOf`: a package that emits declarations could not write the type of an
+    action it exports (`TS4023` on every `export const actions = [defineAction(…)]`).
+  - **A plugin is drawn on the server first** (docs): a preference per device belongs in kept state (`keepState`,
+    `paintedState`) as a bound prop, never read from `localStorage` while rendering — React discards the whole tree on the
+    mismatch, and only in the browser of whoever saved something. `@plitzi/plitzi-ui` is not the page's: a plugin
+    importing it bundles its own copy, with its own contexts and its own look. The authoring skill's `plugin-reach.md`
+    says what a plugin says and to whom: a notification, another element (an event and the space's flow), a server
+    action, shared state, other pages.
+
+  ## Realtime
+  - **A channel that retains** (`@plitzi/sdk-shared`, `@plitzi/sdk-server`, `@plitzi/sdk-elements`): declared
+    `retain: true` (with `publish: 'server'`, which authoring requires), the server keeps the latest message of each type
+    on a topic — said by `ctx.publish` or a flow's `realtime.publish` — and hands them to every page that joins, marked
+    `retained`. A page reads them as `<channel>.retained.<type>`, a plugin as `useChannel(topic).retained`, the newest of
+    a type holding whichever order they arrive in; `null` forgets a type. Kept in the store the actions' `kv` uses (beside
+    the grants, by compare-and-swap), so every replica hands out the same; a topic keeps at most 64 types and 512 KB, and
+    a publish past that is refused before anything is sent. State every screen shares is one publish and one binding —
+    no kv key, initial read or copy in `state` of the project's own. The fleet store `realtime.grants` is now
+    `realtime.kv`.
+  - **The MCP writes every field a channel takes** (`@plitzi/sdk-mcp`): `patchSettings`'s channel had no `grant` — which
+    the guide taught — nor `retain` or the limits, so an agent could not declare a private channel at all. All are there
+    now, and the guide says what `retain` is for and that `channel_<id>.retained` holds it.
+
+  ## Authoring
+  - **`plitzi explain` knows every `@plitzi` package installed** (`@plitzi/cli`): a name that was not
+    `@plitzi/sdk-authoring`'s (`createServer`, `createJsonAdapters`, `useChannel`) was answered as the project's own code,
+    to `grep` in `src/`. It is read from the published types of every one installed, through their re-exports and entry
+    points (`@plitzi/sdk-server/handlers`), and a name two packages export — `createServer` is sdk-server's and sdk-mcp's
+    — is answered with both.
+
+  - **A space module somebody else wrote, authored where it reaches nothing** (`@plitzi/sdk-authoring`):
+    `authorIsolated(file, { timeoutMs })` of `@plitzi/sdk-authoring/node` runs `authorSpace` on it in a process Node's
+    permission model holds to reading the module's folder and its packages — no file written, no process started, no
+    variable of the caller's environment — kills one that runs too long, and validates what it answers again, so a forged
+    answer gains nothing. A refusal comes back as `authorSpace` says it, with the problems as data.
+  - **Pages an agent writes, served** (`@plitzi/sdk-server`): `createAuthoringHost({ dir, frameAncestors })` serves each
+    space it is handed at an address of its own (`put(space, { id }) → /?__pt=<id>`) as a draft of its one space, kept in
+    `dir` across restarts; `drop(id)` forgets one, and anything else answers `404` saying where the pages are.
+  - **A space is chosen by host or credential** (`@plitzi/sdk-server`, docs): `getSpaceDeployment` is asked on every
+    request, and what a page fetches after it carries nothing of its address but the host — a space chosen by the page's
+    query or path lost everything it asked for, and `/_plitzi/space/<hash>.json` answered a bare `404`. The contract and
+    the README say so (the README offered "by path prefix"), and that `404` says why.
+
+  - **`plitzi explain on` says how to read what a trigger carries** (`@plitzi/sdk-authoring`): its doc sat above a
+    helper, so `explain` printed only the signature. It now leads with `[named('picked', on('onPick')), …('{{ picked.seat
+}}')]`, and the CLI skill's plugin section says the same.
+
+- Updated dependencies [6cdd5cf]
+  - @plitzi/plitzi-sdk@0.38.15
+  - @plitzi/sdk-server@0.38.15
+  - @plitzi/sdk-authoring@0.38.15
+  - @plitzi/sdk-schema@0.38.15
+  - @plitzi/sdk-shared@0.38.15
+  - @plitzi/sdk-style@0.38.15
+
 ## 0.38.14
 
 ### Patch Changes

package/dist/modules/mcp/helpers/guide.js

@@ -797,7 +797,7 @@ Pages that see each other — cursors, presence, a shared board, a game. Three p
    \`publish: "server"\` is for what must be validated and saved first; \`"clients"\` (the default) for what pages send
    directly — add \`presence: true\` for who-is-here.
 2. **Subscribe** with a \`channel\` element whose \`topic\` a pattern matches (\`board:{{ id }}\`, a route param).
-   Its descendants bind \`channel_<id>\`: \`connected\`, \`members\`, \`messages\`, \`last\`; flows use its \`onMessage\`,
+   Its descendants bind \`channel_<id>\`: \`connected\`, \`members\`, \`messages\`, \`last\`, \`retained\`; flows use its \`onMessage\`,
    \`onJoin\`, \`onLeave\` triggers (\`from\`, \`user\` and the \`state\` the member announced — \`onJoin\` only for who
    came after this page) and its \`publish\` / \`setPresence\` callbacks.
 3. **Announce from the server**: an action whose last step is the \`realtime.publish\` task — validate, save, then say so.
@@ -809,6 +809,11 @@ decides the visitor may be there ends with \`realtime.grant { topic }\` and answ
 element binds \`grant\` to it. Without one the topic is refused however well its name is known (\`channel-grant\`).
 \`realtime.revoke { topic, grant }\` takes one back — or all, naming none — and lets go whoever is on it with it.
 
+**State every screen shares** (a dashboard's lists, a board's settings): declare the pattern \`retain: true\` with
+\`publish: "server"\`. The server keeps the latest message of each type it says (\`realtime.publish\`) and hands them to
+every page that joins — and to its \`onMessage\` flows, as if just said; the page binds \`desk.retained.lists\`, with no
+read of its own and no copy in \`state\`. \`data: null\` forgets a type; a topic keeps at most 64 types and 512 KB.
+
 **Two writers at once**: read-change-write with \`kv.setIf\` (written only if the value is still the one read — empty
 \`expected\` = only if nothing is there yet), ordered lists with \`list.put\` / \`list.range\`, and put
 \`flow.rateLimit\` first in any public action that writes.

package/dist/modules/mcp/server.js

@@ -72,7 +72,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.14"
+		version: "0.38.15"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);

package/dist/modules/mcp/tools/apply/index.d.ts

@@ -292,6 +292,10 @@ export declare const applyShape: {
                 clients: "clients";
             }>>;
             presence: z.ZodOptional<z.ZodBoolean>;
+            grant: z.ZodOptional<z.ZodBoolean>;
+            retain: z.ZodOptional<z.ZodBoolean>;
+            maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+            messagesPerSecond: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"upsertComponent">;

package/dist/modules/mcp/tools/operations/index.d.ts

@@ -288,6 +288,10 @@ export declare const documentOperation: z.ZodDiscriminatedUnion<readonly [z.ZodO
             clients: "clients";
         }>>;
         presence: z.ZodOptional<z.ZodBoolean>;
+        grant: z.ZodOptional<z.ZodBoolean>;
+        retain: z.ZodOptional<z.ZodBoolean>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        messagesPerSecond: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"upsertComponent">;
@@ -1710,6 +1714,10 @@ export declare const operation: z.ZodDiscriminatedUnion<[z.ZodObject<{
             clients: "clients";
         }>>;
         presence: z.ZodOptional<z.ZodBoolean>;
+        grant: z.ZodOptional<z.ZodBoolean>;
+        retain: z.ZodOptional<z.ZodBoolean>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        messagesPerSecond: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"upsertComponent">;
@@ -3411,6 +3419,10 @@ export declare const operations: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject
             clients: "clients";
         }>>;
         presence: z.ZodOptional<z.ZodBoolean>;
+        grant: z.ZodOptional<z.ZodBoolean>;
+        retain: z.ZodOptional<z.ZodBoolean>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        messagesPerSecond: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"upsertComponent">;
@@ -5107,6 +5119,10 @@ export declare const documentOperations: z.ZodArray<z.ZodDiscriminatedUnion<read
             clients: "clients";
         }>>;
         presence: z.ZodOptional<z.ZodBoolean>;
+        grant: z.ZodOptional<z.ZodBoolean>;
+        retain: z.ZodOptional<z.ZodBoolean>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        messagesPerSecond: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"upsertComponent">;

package/dist/modules/mcp/tools/operations/schema/operations.d.ts

@@ -307,6 +307,10 @@ export declare const elementOps: {
                 clients: "clients";
             }>>;
             presence: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            grant: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            retain: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            maxMessageBytes: import('zod').ZodOptional<import('zod').ZodNumber>;
+            messagesPerSecond: import('zod').ZodOptional<import('zod').ZodNumber>;
         }, import('zod/v4/core').$strip>>>>;
     }, import('zod/v4/core').$strip>;
     upsertComponent: import('zod').ZodObject<{

package/dist/modules/mcp/tools/operations/schema/settings/patchSettings.d.ts

@@ -48,6 +48,10 @@ export declare const patchSettingsOp: z.ZodObject<{
             clients: "clients";
         }>>;
         presence: z.ZodOptional<z.ZodBoolean>;
+        grant: z.ZodOptional<z.ZodBoolean>;
+        retain: z.ZodOptional<z.ZodBoolean>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        messagesPerSecond: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type PatchSettings = z.infer<typeof patchSettingsOp>;

package/dist/modules/mcp/tools/operations/schema/settings/patchSettings.js

@@ -20,7 +20,11 @@ var channel = z.object({
 		permissions: z.array(z.string()).optional()
 	}),
 	publish: z.enum(["clients", "server"]).optional(),
-	presence: z.boolean().optional()
+	presence: z.boolean().optional(),
+	grant: z.boolean().optional().describe("A page needs a grant from realtime.grant to open a topic"),
+	retain: z.boolean().optional().describe("The server keeps the latest message of each type for pages that join"),
+	maxMessageBytes: z.number().int().positive().optional(),
+	messagesPerSecond: z.number().int().positive().optional()
 });
 var notifications = z.record(z.string(), z.string().nullable());
 var patchSettingsOp = z.object({

package/dist/modules/mcp/tools/render.d.ts

@@ -290,6 +290,10 @@ export declare const renderShape: {
                 clients: "clients";
             }>>;
             presence: z.ZodOptional<z.ZodBoolean>;
+            grant: z.ZodOptional<z.ZodBoolean>;
+            retain: z.ZodOptional<z.ZodBoolean>;
+            maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+            messagesPerSecond: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"upsertComponent">;

package/dist/modules/mcp/tools/renderWidget.d.ts

@@ -295,6 +295,10 @@ export declare const renderWidgetShape: {
                 clients: "clients";
             }>>;
             presence: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            grant: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            retain: import('zod').ZodOptional<import('zod').ZodBoolean>;
+            maxMessageBytes: import('zod').ZodOptional<import('zod').ZodNumber>;
+            messagesPerSecond: import('zod').ZodOptional<import('zod').ZodNumber>;
         }, import('zod/v4/core').$strip>>>>;
     }, import('zod/v4/core').$strict>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"upsertComponent">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.38.14",
+  "version": "0.38.15",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -35,12 +35,12 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "@plitzi/plitzi-sdk": "0.38.14",
-    "@plitzi/sdk-authoring": "0.38.14",
-    "@plitzi/sdk-schema": "0.38.14",
-    "@plitzi/sdk-server": "0.38.14",
-    "@plitzi/sdk-shared": "0.38.14",
-    "@plitzi/sdk-style": "0.38.14",
+    "@plitzi/plitzi-sdk": "0.38.15",
+    "@plitzi/sdk-authoring": "0.38.15",
+    "@plitzi/sdk-schema": "0.38.15",
+    "@plitzi/sdk-server": "0.38.15",
+    "@plitzi/sdk-shared": "0.38.15",
+    "@plitzi/sdk-style": "0.38.15",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"