@framingui/mcp-server 0.6.19 → 0.6.21

package/dist/prompts/screen-workflow.js

@@ -1,9 +1,6 @@
 /**
  * MCP Prompts: Screen Generation Workflow
- * Step-by-step guide for the production screen generation process
- */
-/**
- * Screen Workflow prompt with guarded direct-write process
+ * Current production workflow for guarded direct-write screen generation
  */
 export function getScreenWorkflowPrompt() {
     return {
@@ -12,124 +9,86 @@ export function getScreenWorkflowPrompt() {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `# Framingui Screen Generation Workflow
+                    text: `# FramingUI Screen Generation Workflow
 
-This is the **recommended production workflow** for generating screens with Framingui.
+This is the current production workflow for building screens with FramingUI.
 
 Prerequisite: authenticate with \`framingui-mcp login\` or provide \`FRAMINGUI_API_KEY\`.
-Optional: call \`whoami\` if you want to inspect the current session and licensed themes before starting.
+Optional: call \`whoami\` to inspect licensed themes before starting.
 
 ## Overview
 
-The workflow ensures:
-- ✅ Correct component-first usage with inline props/variants
-- ✅ Validated screen structure with auto-fix patches
-- ✅ Theme recipes and component contracts are visible before code is written
-- ✅ All dependencies installed
-- ✅ Tailwind CSS properly configured
-- ✅ Style contract compatibility checked before relying on FramingUI component defaults
+The production workflow is **guarded direct write**:
+- ✅ Gather component contracts, theme context, layout hints, and starter structure
+- ✅ Validate the Screen Definition before writing code
+- ✅ Write React code directly using FramingUI components and props from context
+- ✅ Verify dependencies, Tailwind setup, and raw HTML/style escapes before delivery
 
-## Step 0: Detect Style Contract
+This is **not** the old \`generate_screen\`-first workflow.
+\`generate_screen\` may still be used as an optional helper, but the default production path is:
 
-Before generating or integrating a screen, determine which styling contract the target project already uses.
+\`preview-theme\` → \`get-screen-generation-context\` → \`preview-component\` / \`list-icon-libraries\` when needed → \`validate-screen-definition\` → write code directly → \`validate-environment\`
 
-- \`framingui-native\`: project imports FramingUI styles or defines the full FramingUI variable contract
-- \`host-utility\`: project styles screens with direct Tailwind utilities and does not expose FramingUI variables
-- \`mixed\`: project defines only some FramingUI variables, which is the highest-risk state for broken component styling
+## Step 1/4: Gather Context
 
-**Rule:** do not silently mix a utility-first host page with FramingUI component default variants in the same screen. Either:
-- stay utility-first and use explicit classes, or
-- migrate the page to the FramingUI variable contract after confirming with the user
+**Primary tool:** \`get-screen-generation-context\`
 
-**Mandatory decision:** choose one path before writing code:
-- \`host-utility\`: preserve the host utility stack and keep FramingUI usage explicit with reviewed utility classes
-- \`framingui-native\`: import \`@framingui/ui/styles\` from the global stylesheet and rely on FramingUI variables/variants
-- \`migrate\`: stop and ask for a migration decision before continuing
+Use this at the start of every screen task.
 
-**Enforcement:** if \`projectPath\` is known, Step 0 preflight is required before \`/screen\` or \`/section\` generation.
-Use:
+**Recommended input:**
 \`\`\`json
 {
-  "projectPath": "/path/to/project",
-  "requiredPackages": [],
-  "checkTailwind": true,
-  "checkStyles": true
+  "description": "Blog main page with square-minimalism theme, mobile optimized",
+  "themeId": "square-minimalism",
+  "includeExamples": false
 }
 \`\`\`
-Block generation when:
-- \`styles.styleContract === "mixed"\`
-- \`styles.styleContract === "host-utility"\` and the user did not explicitly choose \`--style-contract host-utility\`
-
-If \`styles.styleContract === "framingui-native"\` or the user explicitly chooses \`--style-contract framingui-native\`, verify that the app imports:
-\`\`\`css
-@import '@framingui/ui/styles';
-\`\`\`
-from a global stylesheet such as \`app/globals.css\` or \`styles/globals.css\`.
 
-## Step 1/4: Get Screen Generation Context
+Set \`includeExamples: false\` when you want a smaller response and do not need example screen definitions.
 
-**Tool:** \`get-screen-generation-context\`
+**What to review from the response:**
+- \`templateMatch\` as a layout hint only
+- \`components\` as the source of truth for imports, props, and variants
+- \`schema.screenDefinition\`
+- \`themeRecipes\`
+- \`hints\`
+- \`workflow\`
 
-**Purpose:** Gather all context needed to create a Screen Definition
+**Escalate to discovery tools when needed:**
+- Call \`preview-theme\` if theme application is still unclear
+- Call \`preview-component\` when a component contract is ambiguous
+- Call \`list-icon-libraries\` if the screen needs icons and the icon set is still undecided
 
-**Input:**
-\`\`\`json
-{
-  "description": "User dashboard with profile card and recent activity",
-  "themeId": "minimal-workspace",
-  "includeExamples": true
-}
-\`\`\`
+## Critical Handling Rule
 
-**Output:**
-- Template hints for inspiration
-- A component plan and section plan for guided drafting
-- Available components with **inline props and variants**
-- A definition starter object for the first draft
-- Screen Definition JSON schema
-- Example definitions
-- Theme recipes
-- Warnings when component metadata could not be loaded cleanly
+Treat MCP tool responses as structured tool output, not as shell text.
 
-**When to use:**
-- Beginning of every screen generation
-- When you need component suggestions
-- When you want template inspiration without hard-coding the screen to a template
+- Do **not** copy MCP transcript text into a file and run \`python\`, \`node\`, \`jq\`, or \`json.loads(...)\` against it
+- Do **not** parse rendered transcript blocks such as \`⎿ { ... }\`, truncation markers, or console summaries
+- Do **not** treat UI-expanded output or chat transcript text as canonical JSON
+- Use the tool result directly in the agent context
 
-**Guardrail:** if the response includes \`warnings\`, do not guess missing props. Resolve the warning first with \`preview-component\` or by retrying the context fetch.
-**Guardrail:** treat \`templateHints\` as inspiration only. \`componentPlan\`, \`components\`, and the validated definition are the contract.
+If you must persist data, write **only the raw JSON object** from the tool result, with no surrounding transcript text.
 
-### Step 1A: Resolve Discovery Gaps Before Drafting
-
-Do not proceed from Step 1 directly into drafting if any of these are still ambiguous:
-
-- **Component ambiguity:** call \`preview-component\` for every component whose props, variants, or availability are uncertain
-- **Theme ambiguity:** call \`preview-theme\` whenever a theme is selected and visual recipes or variable-backed defaults matter
-- **Icon ambiguity:** call \`list-icon-libraries\` before introducing icons or icon-only actions
-
-**Hard rule:** do not claim that FramingUI lacks a component unless you inspected the catalog with \`list-components\` or \`preview-component\`.
-For example, form controls such as \`Input\` must not fall back to raw \`<input>\` without an explicit reason.
-
----
-
-## Step 2/4: Validate Screen Definition
+## Step 2/4: Create and Validate a Screen Definition
 
 **Tool:** \`validate-screen-definition\`
 
-**Purpose:** Ensure your Screen Definition JSON is correct before generating code
+Create a Screen Definition JSON object using the schema and starter guidance from Step 1, then validate it before writing React code.
 
-**Input:**
+**Validation input:**
 \`\`\`json
 {
   "definition": {
-    "id": "user-dashboard",
-    "shell": "shell.web.dashboard",
-    "page": "page.dashboard",
+    "id": "blog-home",
+    "shell": "shell.web.marketing",
+    "page": "page.blog",
+    "themeId": "square-minimalism",
     "sections": [
       {
-        "id": "header",
+        "id": "hero",
         "pattern": "section.container",
-        "components": [...]
+        "components": []
       }
     ]
   },
@@ -137,168 +96,59 @@ For example, form controls such as \`Input\` must not fall back to raw \`<input>
 }
 \`\`\`
 
-**Output:**
-- \`valid\`: true/false
-- \`errors\`: Array of validation errors with suggestions and **autoFix patches**
-- \`warnings\`: Potential issues
-- \`suggestions\`: Improvement recommendations with **autoFix patches**
-- \`autoFixPatches\`: Aggregated JSON Patch operations to fix all issues
-
-**When to use:**
-- Always before generating code (Step 3)
-- When fixing validation errors (apply autoFixPatches)
-- When exploring screen structure improvements
+**Expect from validation:**
+- \`valid\`
+- \`errors\`
+- \`warnings\`
+- \`suggestions\`
+- \`autoFixPatches\`
 
----
+Always apply validation fixes before writing code.
 
 ## Step 3/4: Write React Code Directly
 
-**Purpose:** Write production-ready React code using the validated Screen Definition and the component contracts from Step 1.
-
-**Required constraints:**
-- Preserve the validated \`shell\`, \`page\`, \`section\`, and slot structure from Step 2
-- Use only components returned in Step 1 unless you explicitly inspect more with \`preview-component\`
-- Use documented props and variants; do not invent props
-- Prefer \`@framingui/ui\` components over raw HTML when an equivalent FramingUI primitive exists
-- Prefer tokens, theme recipes, and existing FramingUI primitives over raw design values
-- Semantic wrappers such as \`header\`, \`nav\`, \`section\`, and \`footer\` may stay as HTML, but interactive and form primitives must use FramingUI components when available
-- If a screen needs custom JSX beyond the contract, keep it local and explain why FramingUI primitives were insufficient
+Write production React code directly after validation passes.
 
-**Style-contract constraints:**
-- If the chosen contract is \`framingui-native\`, ensure the project imports \`@framingui/ui/styles\` before relying on component default variants
-- If the chosen contract is \`host-utility\`, prefer reviewed token-aligned utility classes and theme recipes; avoid ad-hoc raw styling when a FramingUI component prop or recipe already covers the need
+**Required rules:**
+- Prefer FramingUI components from \`@framingui/ui\`
+- Use the exact import statements, props, and variants provided in the Step 1 context
+- Use semantic HTML wrappers like \`header\`, \`main\`, \`section\`, and \`footer\` only for document structure
+- Do not replace available FramingUI interactive or form primitives with raw HTML
+- Do not claim a component is unavailable unless the catalog or preview tools confirmed that
 
-**Optional helper:** \`generate_screen\` may still be used as a codegen assistant or reference output, but it is not the default production workflow.
+**Styling rules:**
+- Respect the detected style contract
+- If the project is using FramingUI native styles, ensure \`@import '@framingui/ui/styles';\` is present in global CSS
+- If the project is preserving host utilities, still prefer token-backed utilities and theme recipes over arbitrary raw values
+- Avoid hardcoded design values when FramingUI tokens, variants, or recipes already exist
 
----
-
-## Step 4/4: Validate Environment (Optional but Recommended)
+## Step 4/4: Validate the Target Environment and Output
 
 **Tool:** \`validate-environment\`
 
-**Purpose:** Verify project has required packages and Tailwind is configured correctly
-
-**Input:**
-\`\`\`json
-{
-  "projectPath": "/path/to/package.json",
-  "requiredPackages": ["@radix-ui/react-slot", "@radix-ui/react-avatar"],
-  "sourceFiles": ["app/page.tsx"],
-  "checkTailwind": true,
-  "checkStyles": true
-}
-\`\`\`
-
-**Output:**
-- \`installed\`: Packages already in package.json
-- \`missing\`: Packages that need installation
-- \`installCommands\`: Commands for npm/yarn/pnpm/bun
-- \`tailwind\`: Tailwind config validation results
-  - \`issues\`: Problems found
-  - \`fixes\`: How to fix each issue
-- \`styles\`: Style contract validation results
-  - \`styleContract\`: framingui-native, host-utility, mixed, or unknown
-  - \`issues\`: CSS contract mismatch risks
-  - \`fixes\`: Recommended next actions before integration
-- \`codegen\`: Optional scan of generated React source files for raw HTML primitives that should use \`@framingui/ui\`
-
-**Tailwind Validation Checks:**
-- ✅ tailwind.config.{ts,js,mjs,cjs} exists
-- ✅ @framingui/ui content paths included
-- ✅ tailwindcss-animate plugin configured
-
-**When to use:**
-- After writing code (Step 3), when user's package.json path is known
-- Before delivering code to user
-- When user reports missing styles or animations
-
----
-
-## Complete Example
+Run this after writing code when the target package path is known.
 
-\`\`\`
-User: "Create a login page with email/password fields"
+Use it to verify:
+- missing dependencies
+- install commands
+- Tailwind setup
+- raw HTML primitives or styling escapes in generated source files
 
-0. Call validate-environment({ projectPath: "...", requiredPackages: [], checkStyles: true })
-   -> Classify style contract and decide host-utility vs framingui-native before generation
-   -> If framingui-native, confirm global CSS imports @framingui/ui/styles
+If the tool reports missing setup or raw primitive drift, fix the code before delivery.
 
-1. Call get-screen-generation-context({ description: "login page..." })
-   → Receive template hints, component plan, section plan, definition starter, and component contracts
-   → If any form control, icon, or theme usage is ambiguous, call preview-component / list-icon-libraries / preview-theme before drafting
-
-2. Generate Screen Definition JSON based on definitionStarter + componentPlan
-   → Call validate-screen-definition({ definition: {...} })
-   → Apply autoFixPatches if any, re-validate if needed
-
-3. Write React code directly from the validated definition and Step 1 component contracts
-   → Preserve the validated layout structure
-   → Use documented props instead of guessing
-
-4. Call validate-environment({ projectPath: "...", requiredPackages: [...], sourceFiles: ["app/page.tsx"] })
-   → Show user missing packages and install commands
-   → Warn about Tailwind config issues if any
-   → Fail the handoff if codegen scan finds raw HTML primitives that should use FramingUI components
-
-5. Deliver code to user with complete setup instructions
-\`\`\`
+## Best Practices
 
-## Troubleshooting
-
-**Validation fails in Step 2:**
-- Read error messages carefully - they include suggestions and autoFix patches
-- Apply autoFixPatches to auto-correct common issues
-- Check token names match SPEC-LAYOUT-001
-- Verify component IDs exist (use list-components)
-- Prefer componentPlan before exploring optional alternatives
-
-**Code writing is blocked in Step 3:**
-- Ensure Screen Definition passed validation in Step 2
-- Resolve any Step 1 metadata warnings before guessing props
-- Use \`preview-component\` when a component contract is incomplete
-- Use \`preview-theme\` before relying on theme defaults you have not inspected
-- Use \`list-icon-libraries\` before adding icons that were not explicitly chosen
-
-**Missing dependencies:**
-- Always run Step 4 to verify environment
-- Show install commands to user
-- Check Tailwind config includes @framingui/ui paths
-
-**Components render without styles:**
-- Verify Tailwind content paths include @framingui/ui
-- Check tailwindcss-animate plugin is configured
-- Check whether the target project is \`host-utility\`, \`mixed\`, or \`framingui-native\`
-- If the project is \`framingui-native\`, verify the global stylesheet imports \`@framingui/ui/styles\`
-- If the project is utility-first, prefer explicit reviewed classes instead of relying on FramingUI component defaults
-- Run validate-environment to diagnose
-
----
+1. Start with \`get-screen-generation-context\`
+2. Use \`includeExamples: false\` unless examples are actually needed
+3. Treat \`templateMatch\` as a hint, not a hard constraint
+4. Treat \`components\` as the source of truth
+5. Validate the definition before writing JSX
+6. Never parse MCP transcript text with shell or Python JSON tooling
+7. Run \`validate-environment\` before handoff
 
-## Best Practices
+## Optional Helper Path
 
-1. ✅ Always run Step 0 preflight before generation when projectPath is known
-2. ✅ Validate before writing code (Step 2)
-3. ✅ Write code from the validated definition and component contracts (Step 3)
-4. ✅ Use \`generate_screen\` only as an optional helper, not as a required workflow step
-5. ✅ Check environment before delivering code (Step 4)
-6. ✅ Use strict validation mode for production
-7. ✅ Include theme recipes for visual consistency
-8. ✅ Use inline props from context instead of guessing
-9. ✅ Use template hints only as inspiration, not as structural constraints
-10. ✅ Confirm the target style contract before relying on CSS variables or component defaults
-11. ✅ Call \`preview-component\`, \`preview-theme\`, or \`list-icon-libraries\` whenever Step 1 leaves an ambiguity
-12. ✅ Run post-generation \`validate-environment\` with \`sourceFiles\` to catch raw HTML primitives and style-contract drift
-
-## Alternative Workflows
-
-**Legacy prototyping helper:**
-- \`generate-blueprint\` → \`export-screen\` remains available for backward compatibility, but new agent flows should prefer \`get-screen-generation-context\`
-
-**Production (recommended):**
-- Follow complete 4-step workflow above
-
-**Optional codegen assist:**
-- \`generate_screen\` can be used after validation when you want a reference implementation or a starting point`,
+\`generate_screen\` remains available as an optional helper for reference code generation, but it is not the default production workflow and should not replace validation plus direct writing.`,
                 },
             },
         ],

package/dist/prompts/screen-workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"screen-workflow.js","sourceRoot":"","sources":["../../src/prompts/screen-workflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gHA8RgG;iBACvG;aACF;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"screen-workflow.js","sourceRoot":"","sources":["../../src/prompts/screen-workflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gMA2IgL;iBACvL;aACF;SACF;KACF,CAAC;AACJ,CAAC"}