@pyreon/mcp 0.7.14 → 0.11.1

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@pyreon/mcp",
-  "version": "0.7.14",
+  "version": "0.11.1",
   "description": "MCP server for Pyreon — AI-powered framework assistance",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/pyreon/pyreon.git",
-    "directory": "packages/mcp"
+    "directory": "packages/tools/mcp"
   },
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/mcp#readme",
   "bugs": {
@@ -42,7 +42,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/compiler": "^0.7.14",
+    "@pyreon/compiler": "^0.11.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^3.25.76"
   },

package/src/api-reference.ts

@@ -570,4 +570,545 @@ hydrateRoot(<App />, document.getElementById("app")!)`,
 .fade-enter-from, .fade-leave-to { opacity: 0 }
 */`,
   },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/store
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "store/defineStore": {
+    signature: "defineStore<T>(id: string, setup: () => T): () => StoreApi<T>",
+    example: `const useCounter = defineStore('counter', () => {
+  const count = signal(0)
+  const increment = () => count.update(n => n + 1)
+  return { count, increment }
+})
+
+const { store } = useCounter()
+store.count()      // 0
+store.increment()  // reactive update`,
+    notes:
+      "Composition-style stores. Singleton by ID. Returns StoreApi with .store, .patch(), .subscribe(), .onAction(), .reset(), .dispose().",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/form
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "form/useForm": {
+    signature:
+      "useForm<T>(options: { initialValues: T, onSubmit: (values: T) => void | Promise<void>, schema?, validateOn?, debounceMs? }): FormInstance<T>",
+    example: `const form = useForm({
+  initialValues: { name: '', email: '' },
+  onSubmit: async (values) => await api.save(values),
+  validateOn: 'blur',
+})
+
+form.handleSubmit()  // triggers validation + onSubmit
+form.reset()         // reset to initial values`,
+    notes:
+      "Signal-based form state. Use useField() for individual field binding, useFieldArray() for dynamic arrays.",
+  },
+
+  "form/useField": {
+    signature: "useField<T>(form: FormInstance<T>, name: keyof T): FieldInstance",
+    example: `const name = useField(form, 'name')
+
+<input {...name.register()} />
+// name.value(), name.error(), name.hasError(), name.showError()`,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/query
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "query/useQuery": {
+    signature:
+      "useQuery<T>(options: { queryKey: unknown[], queryFn: () => Promise<T>, ... }): { data: Signal<T>, error: Signal<Error>, isFetching: Signal<boolean>, ... }",
+    example: `const { data, error, isFetching } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => fetch('/api/users').then(r => r.json()),
+})`,
+    notes:
+      "TanStack Query adapter. Fine-grained signals per field. Reactive options via function getter. Also: useMutation, useInfiniteQuery, useSuspenseQuery, useSubscription (WebSocket).",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/permissions
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "permissions/createPermissions": {
+    signature: "createPermissions<T extends PermissionMap>(initial?: T): PermissionsInstance",
+    example: `const can = createPermissions({
+  'posts.read': true,
+  'posts.delete': (post) => post.authorId === userId,
+  'admin.*': false,
+})
+
+can('posts.read')         // true (reactive)
+can('posts.delete', post) // evaluates predicate
+can.not('admin.dashboard')
+can.all('posts.read', 'posts.create')
+can.any('admin.users', 'posts.read')`,
+    notes:
+      "Reactive permissions. Supports RBAC, ABAC, feature flags, subscription tiers. Wildcard matching with '*'. PermissionsProvider/usePermissions for context.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/machine
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "machine/createMachine": {
+    signature: "createMachine<S, E>(config: MachineConfig<S, E>): Machine<S, E>",
+    example: `const traffic = createMachine({
+  initial: 'red',
+  states: {
+    red:    { on: { NEXT: 'green' } },
+    green:  { on: { NEXT: 'yellow' } },
+    yellow: { on: { NEXT: 'red' } },
+  },
+})
+
+traffic()            // 'red' (reactive)
+traffic.send('NEXT') // 'green'
+traffic.matches('green') // true
+traffic.can('NEXT')  // true`,
+    notes:
+      "Constrained signal with type-safe transitions. Guards: { target, guard: (payload?) => boolean }. No context — use signals alongside.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/storage
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "storage/useStorage": {
+    signature:
+      "useStorage<T>(key: string, defaultValue: T, options?: StorageOptions<T>): StorageSignal<T>",
+    example: `const theme = useStorage('theme', 'light')
+theme()           // 'light'
+theme.set('dark') // persists + cross-tab sync
+theme.remove()    // delete from storage`,
+    notes:
+      "localStorage by default. Also: useSessionStorage, useCookie, useIndexedDB, useMemoryStorage, createStorage(backend). All return StorageSignal<T> extending Signal<T> with .remove().",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/i18n
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "i18n/createI18n": {
+    signature:
+      "createI18n(options: { locale: string, messages: Record<string, Record<string, string>>, loader?, fallbackLocale?, pluralRules? }): I18nInstance",
+    example: `const i18n = createI18n({
+  locale: 'en',
+  messages: { en: { greeting: 'Hello, {{name}}!' } },
+  loader: (locale, ns) => import(\`./locales/\${locale}/\${ns}.json\`),
+})
+
+const { t, locale } = useI18n()
+t('greeting', { name: 'World' }) // "Hello, World!"
+locale.set('fr')                  // switch reactively`,
+    notes:
+      "Interpolation with {{name}}, pluralization with _one/_other suffixes. Namespace lazy loading. <Trans> component for rich JSX interpolation.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/document
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "document/createDocument": {
+    signature: "createDocument(props?: DocumentProps): DocumentBuilder",
+    example: `const doc = createDocument({ title: 'Report' })
+  .heading('Sales Report')
+  .table({ columns: ['Region', 'Revenue'], rows: [['US', '$1M']] })
+
+await doc.toPdf()      // PDF
+await doc.toEmail()    // Outlook-safe HTML
+await doc.toDocx()     // Word document
+await doc.toSlack()    // Slack Block Kit JSON
+await doc.toNotion()   // Notion blocks`,
+    notes:
+      "14+ output formats. JSX primitives: Document, Page, Heading, Text, Table, Image, List, Code, etc. Heavy renderers lazy-loaded.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/flow
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "flow/createFlow": {
+    signature: "createFlow(config: { nodes: FlowNode[], edges: FlowEdge[], ... }): FlowInstance",
+    example: `const flow = createFlow({
+  nodes: [
+    { id: '1', position: { x: 0, y: 0 }, data: { label: 'Start' } },
+    { id: '2', position: { x: 200, y: 100 }, data: { label: 'End' } },
+  ],
+  edges: [{ id: 'e1', source: '1', target: '2' }],
+})
+
+flow.addNode({ id: '3', position: { x: 100, y: 200 }, data: { label: 'New' } })
+await flow.layout('layered')  // auto-layout via elkjs
+
+<Flow instance={flow}><Background /><Controls /><MiniMap /></Flow>`,
+    notes:
+      "Signal-native nodes/edges. Auto-layout via elkjs (lazy-loaded). Pan/zoom via pointer events + CSS transforms. No D3.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/code
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "code/createEditor": {
+    signature:
+      "createEditor(config: { value?: string, language?: string, theme?: string, minimap?: boolean, ... }): EditorInstance",
+    example: `const editor = createEditor({
+  value: '// hello',
+  language: 'typescript',
+  theme: 'dark',
+  minimap: true,
+})
+
+editor.value()       // reactive Signal<string>
+editor.goToLine(42)
+editor.insert('new code')
+
+<CodeEditor instance={editor} />
+<DiffEditor original="old" modified="new" />`,
+    notes:
+      "Built on CodeMirror 6 (~250KB vs Monaco's ~2.5MB). loadLanguage() for lazy grammars. TabbedEditor for multi-file.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/hotkeys
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "hotkeys/useHotkey": {
+    signature:
+      "useHotkey(shortcut: string, handler: (e: KeyboardEvent) => void, options?: HotkeyOptions): void",
+    example: `useHotkey('mod+s', (e) => {
+  e.preventDefault()
+  save()
+})
+
+useHotkey('mod+k', () => openSearch(), { scope: 'global' })
+useHotkeyScope('editor')  // activate scope for component lifetime`,
+    notes:
+      "Component-scoped, auto-unregisters on unmount. 'mod' = ⌘ on Mac, Ctrl elsewhere. Scope-based activation for context-aware shortcuts.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/table
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "table/useTable": {
+    signature: "useTable<T>(options: TableOptions<T>): Table<T>",
+    example: `const table = useTable({
+  data: () => users(),
+  columns: [
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+  ],
+})
+
+// flexRender for column templates:
+flexRender(cell.column.columnDef.cell, cell.getContext())`,
+    notes: "TanStack Table adapter with reactive options and auto state sync.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/virtual
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "virtual/useVirtualizer": {
+    signature:
+      "useVirtualizer(options: VirtualizerOptions): { virtualItems: Signal, totalSize: Signal, scrollToIndex: (i) => void, ... }",
+    example: `const { virtualItems, totalSize } = useVirtualizer({
+  count: 10000,
+  getScrollElement: () => scrollRef.current,
+  estimateSize: () => 35,
+})`,
+    notes: "TanStack Virtual adapter. Also: useWindowVirtualizer for window-scoped virtualization.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/feature
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "feature/defineFeature": {
+    signature:
+      "defineFeature<T>(config: { name: string, schema: FeatureSchema<T>, api: FeatureApi<T> }): Feature<T>",
+    example: `const Posts = defineFeature({
+  name: 'posts',
+  schema: { title: 'string', body: 'string', author: reference('users') },
+  api: { baseUrl: '/api/posts' },
+})
+
+// Auto-generated hooks:
+Posts.useList()    // paginated query
+Posts.useById(id)  // single item query
+Posts.useCreate()  // mutation
+Posts.useForm(id)  // edit form with validation
+Posts.useTable()   // TanStack Table config`,
+    notes:
+      "Schema-driven CRUD. Composes @pyreon/query, @pyreon/form, @pyreon/validation, @pyreon/store, @pyreon/table.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/storybook
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/lint
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "lint/lint": {
+    signature: "lint(options?: LintOptions): LintResult",
+    example: `import { lint } from "@pyreon/lint"
+
+const result = lint({ paths: ["src/"], preset: "recommended" })
+console.log(result.totalErrors, result.totalWarnings)
+
+// With config file auto-loading + rule overrides
+lint({ paths: ["."], ruleOverrides: { "pyreon/no-classname": "off" } })`,
+    notes:
+      "Programmatic API. 55 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Uses oxc-parser with AST caching.",
+  },
+
+  "lint/lintFile": {
+    signature:
+      "lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache): LintFileResult",
+    example: `import { lintFile, allRules, getPreset, AstCache } from "@pyreon/lint"
+
+const cache = new AstCache()
+const config = getPreset("recommended")
+const result = lintFile("app.tsx", source, allRules, config, cache)`,
+    notes: "Low-level single-file API. Optional AstCache for repeat runs (FNV-1a hash keyed).",
+  },
+
+  "lint/cli": {
+    signature:
+      "pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [path...]",
+    example: `pyreon-lint --preset strict --quiet    # CI mode
+pyreon-lint --fix                       # auto-fix
+pyreon-lint --watch src/                # watch mode
+pyreon-lint --list                      # list all 55 rules
+pyreon-lint --format json               # machine-readable`,
+    notes:
+      "CLI entry. Config: .pyreonlintrc.json, package.json 'pyreonlint' field. Ignore: .pyreonlintignore + .gitignore. Watch: fs.watch recursive with 100ms debounce.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/ui-core
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "ui-core/PyreonUI": {
+    signature:
+      "PyreonUI(props: { theme?: Theme; mode?: 'light' | 'dark' | 'system'; inversed?: boolean; children: VNodeChild }): VNodeChild",
+    example: `import { PyreonUI } from "@pyreon/ui-core"
+import { enrichTheme } from "@pyreon/unistyle"
+
+const theme = enrichTheme({ colors: { primary: "#3b82f6" } })
+
+<PyreonUI theme={theme} mode="system">
+  <App />
+</PyreonUI>
+
+// mode="system" auto-detects OS dark mode via prefers-color-scheme
+// inversed flips the resolved mode (light↔dark)`,
+    notes:
+      "Unified provider replacing 3 separate providers (theme, mode, config). Calls init() internally. mode='system' uses matchMedia('(prefers-color-scheme: dark)') and reactively updates.",
+    mistakes: `- Using ThemeProvider + ModeProvider + ConfigProvider separately → Use PyreonUI instead
+- Forgetting enrichTheme() → raw theme objects miss default breakpoints/spacing`,
+  },
+
+  "ui-core/useMode": {
+    signature: "useMode(): Signal<'light' | 'dark'>",
+    example: `import { useMode } from "@pyreon/ui-core"
+
+const mode = useMode()
+// mode() returns "light" or "dark" (resolved, reactive)
+// Reflects OS preference when PyreonUI mode="system"`,
+    notes:
+      "Returns the resolved mode as a reactive signal. When mode='system', reflects the OS preference. When inversed is true, the mode is flipped.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/unistyle
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "unistyle/enrichTheme": {
+    signature: "enrichTheme(theme: PartialTheme): Theme",
+    example: `import { enrichTheme } from "@pyreon/unistyle"
+
+const theme = enrichTheme({
+  colors: { primary: "#3b82f6", secondary: "#6366f1" },
+  fonts: { body: "Inter, sans-serif" },
+})
+
+// Merges user overrides with default breakpoints, spacing, and units`,
+    notes:
+      "Merges a partial theme with the full default theme (breakpoints, spacing, unit utilities). Always use when passing a theme to PyreonUI.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/storybook
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/rx
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "rx/filter": {
+    signature:
+      "filter<T>(source: Signal<T[]> | T[], predicate: (item: T) => boolean): Computed<T[]> | T[]",
+    example: `import { filter } from '@pyreon/rx'
+
+// Signal input → Computed output (auto-tracks):
+const items = signal([1, 2, 3, 4, 5])
+const evens = filter(items, n => n % 2 === 0)  // Computed<number[]>
+evens()  // [2, 4]
+
+// Plain input → plain output:
+const result = filter([1, 2, 3, 4, 5], n => n > 3)  // [4, 5]`,
+    notes:
+      "Every @pyreon/rx function is overloaded: Signal<T[]> input produces Computed<T[]>, plain T[] input produces plain T[]. 24 functions total: filter, map, sortBy, groupBy, keyBy, uniqBy, take, skip, last, chunk, flatten, find, mapValues, count, sum, min, max, average, distinct, scan, combine, debounce, throttle, search.",
+  },
+
+  "rx/pipe": {
+    signature: "pipe<T>(source: Signal<T[]> | T[], ...operators: Operator[]): Computed<T[]> | T[]",
+    example: `import { pipe, filter, sortBy, map } from '@pyreon/rx'
+
+const users = signal([
+  { name: 'Charlie', age: 35 },
+  { name: 'Alice', age: 25 },
+  { name: 'Bob', age: 30 },
+])
+
+// Compose transforms left-to-right:
+const result = pipe(
+  users,
+  filter(u => u.age >= 30),
+  sortBy('name'),
+  map(u => u.name),
+)
+// Computed<string[]> → ["Bob", "Charlie"]`,
+    notes:
+      "Pipe composes operators left-to-right. Signal source produces reactive Computed that re-derives when source changes.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/toast
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "toast/toast": {
+    signature:
+      "toast(message: string, options?: ToastOptions): string\ntoast.success/error/warning/info/loading(message): string\ntoast.update(id, options): void\ntoast.dismiss(id?): void\ntoast.promise(promise, { loading, success, error }): string",
+    example: `import { toast, Toaster } from '@pyreon/toast'
+
+// Basic:
+toast('Hello!')
+toast.success('Saved!')
+toast.error('Failed!')
+
+// Loading → success pattern:
+const id = toast.loading('Saving...')
+await save()
+toast.update(id, { type: 'success', message: 'Done!' })
+
+// Promise helper:
+toast.promise(fetchData(), {
+  loading: 'Loading...',
+  success: 'Loaded!',
+  error: 'Failed to load',
+})
+
+// Dismiss:
+toast.dismiss(id)  // one
+toast.dismiss()    // all
+
+// Mount Toaster once in your app:
+<Toaster />`,
+    notes:
+      "Imperative API — call from anywhere, no context needed. <Toaster /> renders via Portal with CSS transitions, auto-dismiss, pause on hover. Accessible: role='alert', aria-live='polite'.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/url-state
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "url-state/useUrlState": {
+    signature:
+      "useUrlState<T>(key: string, defaultValue: T): UrlStateSignal<T>\nuseUrlState<T extends Record<string, unknown>>(schema: T): UrlStateSchema<T>",
+    example: `import { useUrlState } from '@pyreon/url-state'
+
+// Single param — synced to ?page=:
+const page = useUrlState('page', 1)
+page()       // 1 (auto-coerced number)
+page.set(2)  // URL → ?page=2
+
+// Schema mode — multiple params:
+const filters = useUrlState({ page: 1, sort: 'name', desc: false })
+filters.page()   // 1
+filters.sort()   // "name"
+filters.set({ page: 2, sort: 'date' })`,
+    notes:
+      "Auto type coercion (numbers, booleans, arrays). Uses replaceState (no history spam). Configurable debounce. SSR-safe — reads request URL on server.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/query — useSSE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "query/useSSE": {
+    signature:
+      "useSSE<T>(options: { queryKey: unknown[], url: string, transform?: (event: MessageEvent) => T, ... }): { data: Signal<T>, error: Signal<Error>, status: Signal<string> }",
+    example: `import { useSSE } from '@pyreon/query'
+
+const { data, error, status } = useSSE({
+  queryKey: ['events'],
+  url: '/api/events',
+  transform: (event) => JSON.parse(event.data),
+})
+
+// data() reactively updates on each SSE message
+// Auto-reconnects on disconnect
+// Integrates with QueryClient for cache invalidation`,
+    notes:
+      "Server-Sent Events hook. Same pattern as useSubscription but read-only (no send). Integrates with QueryClient cache.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/router — useIsActive
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "router/useIsActive": {
+    signature: "useIsActive(path: string, exact?: boolean): () => boolean",
+    example: `import { useIsActive } from '@pyreon/router'
+
+const isHome = useIsActive('/')
+const isAdmin = useIsActive('/admin')          // prefix match
+const isExactAdmin = useIsActive('/admin', true)  // exact only
+
+// Reactive — updates when route changes:
+<a class={{ active: isAdmin() }} href="/admin">Admin</a>`,
+    notes:
+      "Returns a reactive boolean. Segment-aware prefix matching: /admin matches /admin/users but not /admin-panel. Pass exact=true for exact-only matching.",
+  },
+
+  "storybook/renderToCanvas": {
+    signature: "renderToCanvas(context: StoryContext, canvasElement: HTMLElement): void",
+    example: `// .storybook/main.ts:
+export default { framework: '@pyreon/storybook' }
+
+// Story file:
+import type { Meta, StoryObj } from '@pyreon/storybook'
+import { Button } from './Button'
+
+const meta: Meta<typeof Button> = { component: Button }
+export default meta
+
+export const Primary: StoryObj<typeof meta> = {
+  args: { variant: 'primary', label: 'Click me' },
+}`,
+    notes:
+      "Storybook renderer for Pyreon components. Re-exports h, Fragment, signal, computed, effect, mount for story convenience.",
+  },
 }