Files
webstudio/apps/builder/app/shared/system.ts
Oleg Isonen dde30ffb54 feat: Improve MCP authoring, compact output, and agent onboarding (#5883)
## Summary

This improves how agents discover, author, inspect, and verify Webstudio
projects while reducing unnecessary MCP context usage.

## What changed

- Adds an **Agents** section to Project Settings with ready-to-run setup
commands and client configuration for Claude Code, Codex, Cursor, and VS
Code.
- Makes large list and schema responses compact and paginated by
default, with **verbose** available when complete records or diagnostics
are needed.
- Applies consistent compact output to assets, instances, styles, design
tokens, CLI schemas, and project-session metadata.
- Returns actionable expression warnings for props, resources, and
Collection bindings, including unknown variables and risky render-time
mutation resources.
- Improves Collection expression guidance so agents can bind array items
with the correct scoped variables.
- Reports rendered audit outcomes explicitly as complete, partial,
confirmation-required, or failed.
- Expands runtime output schemas so MCP clients can validate responses
reliably.
- Strengthens the packaged CLI smoke workflow with a realistic
seven-page stdio MCP scenario.

## Architecture

- Consolidates `project-build` from 65 file-oriented entrypoints to 11
architecture-owned surfaces.
- Separates the core model, contracts, runtime authoring, transfer,
state, project sessions, MCP, visual tooling, persistence codecs, and
authenticated server services.
- Isolates Node-only JSX evaluation from browser-safe transfer utilities
and authenticated server modules.
- Keeps persistence codecs independent from authenticated database
services, preventing unrelated module initialization.
- Defines shared instance-path types once and reuses them across runtime
modules.
- Preserves Immer initialization through explicit package side-effect
metadata.
- Adds package tests that prevent a return to source-file entrypoints or
generic exposure of Node-only surfaces.

## Validation

- Full repository checks, tests, typechecks, generated-file checks, and
fixtures
- All 163 Builder test files and 2,141 tests
- All 71 project-build test files and 1,794 tests
- Lint and package-boundary validation
- Full packed CLI release smoke test, including install, preview, agent
setup, seven-page stdio MCP workflow, rendered audit, and structured
commands
2026-07-15 18:11:28 +02:00

107 lines
3.1 KiB
TypeScript

import { atom, computed } from "nanostores";
import { getPagePath, isPage, type Page, type System } from "@webstudio-is/sdk";
import {
compilePathnamePattern,
matchPathnamePattern,
tokenizePathnamePattern,
} from "@webstudio-is/project-build/runtime";
import { $selectedPage } from "./nano-states/pages";
import { $pages } from "./sync/data-stores";
import { $publishedOrigin } from "./nano-states/misc";
import { executeRuntimeMutation } from "./instance-utils/data";
export const $systemDataByPage = atom(
new Map<Page["id"], Pick<System, "search" | "params">>()
);
const extractParams = (
pattern: string,
path?: string,
fallbackPattern?: string
) => {
const params: System["params"] = {};
const tokens = tokenizePathnamePattern(pattern);
// try to match the first item in history to let user
// see the page without manually entering params
// or selecting them in address bar
const matchedParams = path
? (matchPathnamePattern(pattern, path) ??
(fallbackPattern
? matchPathnamePattern(fallbackPattern, path)
: undefined))
: undefined;
for (const token of tokens) {
if (token.type === "param") {
params[token.name] = matchedParams?.[token.name] ?? undefined;
}
}
return params;
};
export const $currentSystem = computed(
[$publishedOrigin, $selectedPage, $pages, $systemDataByPage],
(origin, page, pages, systemByPage) => {
const system: System = {
search: {},
params: {},
pathname: "/",
origin,
};
if (page === undefined || pages === undefined || !isPage(page)) {
return system;
}
const systemData = systemByPage.get(page.id);
const pagePath = getPagePath(page.id, pages);
const extractedParams = extractParams(
pagePath,
page.history?.[0],
page.path
);
const params = { ...extractedParams, ...systemData?.params };
const pathname = compilePath(pagePath, params) || "/";
return {
search: { ...system.search, ...systemData?.search },
params,
pathname,
origin,
};
}
);
const compilePath = (pattern: string, params: System["params"]) => {
const tokens = tokenizePathnamePattern(pattern);
return compilePathnamePattern(tokens, params);
};
/**
* put new path into the beginning of history
* and drop paths in the end when exceeded 20
*/
const savePathInHistory = (pageId: string, path: string) => {
executeRuntimeMutation({
id: "pages.savePathInHistory",
input: {
pageId,
path,
},
});
};
export const updateCurrentSystem = (
update: Partial<Pick<System, "search" | "params">>
) => {
const page = $selectedPage.get();
if (!isPage(page)) {
return;
}
const systemDataByPage = new Map($systemDataByPage.get());
const systemData = systemDataByPage.get(page.id);
const search = update.search ?? systemData?.search ?? {};
const params = update.params ?? systemData?.params ?? {};
systemDataByPage.set(page.id, { search, params });
$systemDataByPage.set(systemDataByPage);
const pages = $pages.get();
const pagePath = pages ? getPagePath(page.id, pages) : page.path;
savePathInHistory(page.id, compilePath(pagePath, params));
};