npm - @wabot-dev/framework - Versions diffs - 0.9.80 → 2.0.0-beta.0 - Mend

@wabot-dev/framework 0.9.80 → 2.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/bin/skills.mjs +151 -0
package/bin/wabot-skills.mjs +120 -0
package/dist/build/build.js +1031 -8
package/dist/src/addon/chat-bot/in-memory/InMemoryChatMemory.js +1 -3
package/dist/src/addon/chat-bot/xai/XAIChatAdapter.js +180 -0
package/dist/src/addon/chat-controller/cmd/cmdChannelSocketPath.js +1 -5
package/dist/src/addon/chat-controller/hubspot/@hubspot.js +28 -0
package/dist/src/addon/chat-controller/hubspot/HubSpotChannel.js +81 -0
package/dist/src/addon/chat-controller/hubspot/HubSpotChannelConfig.js +20 -0
package/dist/src/addon/chat-controller/hubspot/HubSpotReceiver.js +42 -0
package/dist/src/addon/chat-controller/hubspot/HubSpotSender.js +118 -0
package/dist/src/addon/chat-controller/hubspot/HubSpotWebhookController.js +122 -0
package/dist/src/addon/chat-controller/hubspot/downloadHubSpotAttachments.js +45 -0
package/dist/src/addon/chat-controller/hubspot/hubspotChannelName.js +3 -0
package/dist/src/addon/chat-controller/hubspot/verifyHubSpotSignatureV3.js +28 -0
package/dist/src/addon/chat-controller/{telegram/markdownToTelegramHtml.js → markdown/markdownToChatHtml.js} +5 -8
package/dist/src/addon/chat-controller/slack/@slack.js +22 -0
package/dist/src/addon/chat-controller/slack/SlackChannel.js +187 -0
package/dist/src/addon/chat-controller/slack/SlackChannelConfig.js +12 -0
package/dist/src/addon/chat-controller/slack/markdownToSlackMrkdwn.js +38 -0
package/dist/src/addon/chat-controller/slack/slackChannelName.js +3 -0
package/dist/src/addon/chat-controller/telegram/TelegramChannel.js +2 -2
package/dist/src/addon/ui/preact/PreactRenderer.js +86 -0
package/dist/src/addon/ui/preact/outlet.js +22 -0
package/dist/src/addon/ui/preact/preactClientRuntime.js +67 -0
package/dist/src/core/repository/CrudRepository.js +7 -7
package/dist/src/feature/async/computeDedupKey.js +1 -1
package/dist/src/feature/pg/@pgExtension.js +2 -4
package/dist/src/feature/project-runner/ProjectRunner.js +62 -10
package/dist/src/feature/project-runner/scanner.js +1 -1
package/dist/src/feature/repository/@memExtension.js +1 -2
package/dist/src/feature/ui-controller/actions.js +35 -0
package/dist/src/feature/ui-controller/bundler/UiBundler.js +191 -0
package/dist/src/feature/ui-controller/bundler/devMiddleware.js +41 -0
package/dist/src/feature/ui-controller/bundler/index.js +4 -0
package/dist/src/feature/ui-controller/bundler/manifest.js +34 -0
package/dist/src/feature/ui-controller/bundler/navRuntime.js +236 -0
package/dist/src/feature/ui-controller/bundler/pageAssets.js +30 -0
package/dist/src/feature/ui-controller/document/escape.js +17 -0
package/dist/src/feature/ui-controller/document/helpers.js +13 -0
package/dist/src/feature/ui-controller/document/renderDocument.js +43 -0
package/dist/src/feature/ui-controller/island/IslandRegistry.js +68 -0
package/dist/src/feature/ui-controller/island/island.js +40 -0
package/dist/src/feature/ui-controller/island/serialize.js +35 -0
package/dist/src/feature/ui-controller/metadata/@action.js +18 -0
package/dist/src/feature/ui-controller/metadata/@uiController.js +19 -0
package/dist/src/feature/ui-controller/metadata/@uiMiddleware.js +20 -0
package/dist/src/feature/ui-controller/metadata/@view.js +18 -0
package/dist/src/feature/ui-controller/metadata/UiControllerMetadataStore.js +107 -0
package/dist/src/feature/ui-controller/renderer/UiRendererRegistry.js +42 -0
package/dist/src/feature/ui-controller/runUiControllers.js +285 -0
package/dist/src/index.d.ts +632 -3
package/dist/src/index.js +30 -1
package/dist/src/testing/index.d.ts +43 -1
package/dist/src/testing/index.js +1 -0
package/dist/src/testing/uiHarness.js +102 -0
package/dist/src/ui/client.js +6 -0
package/dist/src/ui/index.d.ts +427 -0
package/dist/src/ui/index.js +29 -0
package/dist/src/ui/jsx-dev-runtime.d.ts +1 -0
package/dist/src/ui/jsx-dev-runtime.js +1 -0
package/dist/src/ui/jsx-runtime.d.ts +1 -0
package/dist/src/ui/jsx-runtime.js +1 -0
package/package.json +33 -13
package/skills/wabot-async/SKILL.md +143 -0
package/skills/wabot-auth/SKILL.md +153 -0
package/skills/wabot-chat/SKILL.md +140 -0
package/skills/wabot-di-config/SKILL.md +117 -0
package/skills/wabot-framework/SKILL.md +81 -0
package/skills/wabot-framework/references/quickstart.md +85 -0
package/skills/wabot-mindset/SKILL.md +159 -0
package/skills/wabot-ops/SKILL.md +151 -0
package/skills/wabot-persistence/SKILL.md +159 -0
package/skills/wabot-rest-socket/SKILL.md +167 -0
package/skills/wabot-testing/SKILL.md +214 -0
package/skills/wabot-ui/SKILL.md +201 -0
package/skills/wabot-validation/SKILL.md +108 -0

package/skills/wabot-ui/SKILL.md ADDED Viewed

@@ -0,0 +1,201 @@
+---
+name: wabot-ui
+description: Use when building server-rendered web pages, forms, or interactive UI from a Wabot app. Covers @uiController, @view, @action, @uiMiddleware, the one validated-DTO handler arg, redirect(), islands (island() in *.island.tsx, callAction/actionUrl), signals vs hooks, boosted navigation (app: true) with layout/<Outlet/> and swr, head resource hints, CSS modules, the tsconfig JSX setup, and custom UiRenderer. Argument validation is shared with wabot-validation.
+---
+# UI controllers
+Wabot's UI layer server-renders Preact and ships JavaScript only for the interactive parts ("islands"). You write `@uiController` classes with `@view` (GET → HTML) and `@action` (POST → JSON) methods; the runner discovers them from `src/`, SSRs each view inside a default HTML document, and — in dev/prod — bundles islands for client hydration. Everything works without JS; islands are a progressive enhancement.
+Everything ships from `@wabot-dev/framework/ui`. Never import from internal paths.
+## Setup
+Importing `@wabot-dev/framework/ui` registers the Preact renderer as a side effect. Configure JSX in `tsconfig.json`:
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@wabot-dev/framework/ui"
+  }
+}
+```
+No manual registration: `run(config)` discovers `@uiController` classes, loads the Preact renderer, and sets up the island bundler automatically. `config.ui.bundlerAlias` is only needed when islands import the framework UI through a non-package specifier (path alias in a monorepo/in-repo dev) — regular consumers never set it.
+## Controller
+```tsx
+import { isNotEmpty, isString } from '@wabot-dev/framework'
+import { uiController, view, action, redirect } from '@wabot-dev/framework/ui'
+import { HomePage } from './ui/pages/HomePage'
+import { addMessage, messages } from './ui/store'
+class AddMessageDto {
+  @isString()
+  @isNotEmpty()
+  text?: string
+}
+@uiController('/board')
+export class BoardController {
+  // GET /board  — empty/omitted path is the controller index.
+  @view({ title: 'Message board' })
+  index() {
+    return <HomePage messages={messages} />
+  }
+  // GET /board/archive
+  @view({ path: 'archive', title: 'Archive' })
+  archive() {
+    return <HomePage messages={messages} archived />
+  }
+  // POST /board/_action/add  — path defaults to the method name.
+  @action()
+  add(input: AddMessageDto) {
+    addMessage(input.text!)
+    return redirect('/board') // post/redirect/get for no-JS forms
+  }
+  // POST /board/_action/postMessage — returns JSON for callAction() from an island.
+  @action()
+  postMessage(input: AddMessageDto) {
+    addMessage(input.text!)
+    return { messages }
+  }
+}
+```
+- **`@uiController(path | { path, middlewares?, app?, layout?, head? })`** — `path` is the base every view/action mounts under.
+- **`@view(subpath | { path?, title?, meta?, swr? })`** → `GET <controllerPath>/<path>`. Returns a JSX node (SSR'd) or `redirect(...)`. `title`/`meta` fill the document `<head>`.
+- **`@action(subpath | { path? })`** → `POST <controllerPath>/_action/<path>` (path defaults to the method name). Returns a JSON-serializable value (circular refs stripped) or `redirect(...)`.
+- **Handler args:** at most **one** parameter — a class the framework validates exactly like a rest-controller request DTO (see `wabot-validation`). The request object is `body`, `query`, and route `params` merged. Omit the parameter for handlers that need no input.
+- **`redirect(location, status = 302)`** — return it from a view or action to send an HTTP redirect instead of rendering.
+## Middlewares / guards
+Same `IMiddleware` contract as REST (see `wabot-rest-socket` / `wabot-auth`).
+```tsx
+import { injectable, type IMiddleware } from '@wabot-dev/framework'
+import { uiController, uiMiddleware } from '@wabot-dev/framework/ui'
+@injectable()
+class RequireAuth implements IMiddleware {
+  async handle(req: unknown, res: unknown) {
+    /* throw or write a response to block */
+  }
+}
+@uiController({ path: '/admin', middlewares: [RequireAuth] }) // whole controller
+export class AdminController {
+  @uiMiddleware(RequireAuth) // …or a single view/action
+  @view()
+  index() {
+    return <Dashboard />
+  }
+}
+```
+Middlewares run before the handler; if one sends a response, the handler is skipped.
+## Islands (client interactivity)
+Only islands ship JS and hydrate; the rest of the page is static SSR HTML. An island **must** be the default export of a `*.island.tsx` file so the bundler can give it a stable id.
+```tsx
+// Counter.island.tsx
+import { island, useSignal } from '@wabot-dev/framework/ui'
+function Counter({ start = 0 }: { start?: number }) {
+  const count = useSignal(start)
+  return <button onClick={() => count.value++}>{count}</button>
+}
+export default island(Counter)
+```
+Render an island like any component from a view or another component: `<Counter start={3} />`. Props must be JSON-serializable (they are sent to the client for hydration). Islands may use **signals** (`signal`, `useSignal`, `useComputed`, `useSignalEffect`) or **hooks** (`useState`, `useEffect`, `useRef`, …) — both re-exported from `@wabot-dev/framework/ui`.
+### Calling actions from an island
+```tsx
+// MessageBoard.island.tsx
+import { island, useSignal, callAction, actionUrl } from '@wabot-dev/framework/ui'
+const POST_URL = actionUrl('/board', 'postMessage') // -> /board/_action/postMessage
+function MessageBoard({ initial = [] }) {
+  const messages = useSignal(initial)
+  async function send(text: string) {
+    const res = await callAction<{ messages: any[] }>(POST_URL, { text })
+    messages.value = res.messages
+  }
+  // …form that calls send()…
+}
+export default island(MessageBoard)
+```
+- **`actionUrl(controllerPath, actionName)`** builds the action URL.
+- **`callAction<T>(url, data?, { headers?, signal? })`** POSTs JSON and returns the parsed result; it throws on non-2xx with the server-provided error message.
+- Both are client-safe (no Node imports) so they bundle into islands. A plain `<form method="post" action="/board/_action/add">` also works for no-JS progressive enhancement.
+## App shell & boosted navigation
+`app: true` opts a controller into client-side ("boosted") navigation between its own views: in-scope links are swapped in without a full reload, backed by a stale-while-revalidate cache. Views still SSR and work without JS.
+```tsx
+import { uiController, view, Outlet } from '@wabot-dev/framework/ui'
+function AppLayout() {
+  return (
+    <div class="app">
+      <nav>{/* … */}</nav>
+      <main><Outlet /></main>{/* current view renders here */}
+    </div>
+  )
+}
+@uiController({ path: '/panel', app: true, layout: AppLayout })
+export class PanelController {
+  @view({ path: '', title: 'Home', swr: { maxAge: 30 } })
+  home() { return <HomeView /> }
+  @view({ path: ':id', title: 'Detail', swr: { version: ({ id }) => revisionOf(id) } })
+  detail(input: DetailParams) { return <DetailView id={input.id} /> }
+}
+```
+- **`layout: Component`** — a persistent shell rendered once around every view; it renders `<Outlet/>` where the current view goes. During boosted nav only the outlet swaps, so the shell and its islands keep their state. Full loads render inside the layout; boosted-nav fragments render just the view.
+- **`swr: { maxAge?, version? }`** on `@view` tunes the boosted-nav cache. `maxAge` (seconds) serves a revisit from cache without revalidating. `version(request)` returns a short deterministic string; boosted-nav revalidation answers `304` from it *without running the handler or SSR*. Parameterized `app` views should declare `swr.version` keyed off their route params.
+- **`head: { preconnect?, preload? }`** on `@uiController` emits `<link rel="preconnect|preload">` hints on full loads (the natural home for app-wide fonts — the head persists across boosted nav).
+## Styling
+CSS modules are supported in islands and components:
+```tsx
+import styles from './styles.module.css'
+export default island(() => <div class={styles.box}>styled</div>)
+```
+Inline `<style dangerouslySetInnerHTML={{ __html: css }} />` works too (as in a layout that injects a design-system stylesheet once).
+## Advanced
+- **`renderDocument(options)`** produces the default HTML shell (`bodyHtml`, `title`, `meta`, `styles`, `links`, `scripts`, `headHtml`, `bodyEndHtml`, `lang`). The runner calls it for you; use it directly only for a custom document.
+- **Custom renderer:** implement the `UiRenderer` interface and register it with `UiRendererRegistry.setDefault(myRenderer)` instead of importing the Preact entry. The default id is `"preact"`.
+## Hard rules
+- Import everything from `@wabot-dev/framework/ui` (server decorators + client helpers + Preact/signals re-exports). Never import from `preact` / `@preact/signals` directly, and never from framework internal paths.
+- Islands live in `*.island.tsx` files and are the file's default export via `island()`. A component used interactively but not wrapped this way will render but never hydrate.
+- View/action handlers take at most one parameter, and it is a validated class — not raw `req`/`res`.
+- `@preact/signals`' `action` is re-exported as **`signalAction`** to avoid clashing with the `@action` controller decorator.
+## Testing
+`createUiHarness({ controllers, register? })` from `@wabot-dev/framework/testing` mounts `@uiController` classes on a private ephemeral-port server and exercises the real pipeline (middlewares/guards, validation, SSR, actions). `harness.get(path)` returns the rendered HTML document; `harness.action(path, body?)` POSTs to an action route and `res.json()` parses the reply. Islands render as static SSR HTML — no client bundling needed. See the `wabot-testing` skill.

package/skills/wabot-validation/SKILL.md ADDED Viewed

@@ -0,0 +1,108 @@
+---
+name: wabot-validation
+description: Use when defining request DTOs, mindset module argument classes, or any class that must be validated and transformed by Wabot — including REST/socket inputs and tool function parameters. Covers the validator decorators (@isString, @isNumber, @isBoolean, @isDate, @isIn, @isNotEmpty, @isPresent, @isRecord, @isOptional, @isModel, @isArray, @min, @max), @description, validateAndTransform, and Mapper.
+---
+# Validation, description, mapping
+Wabot validates request shapes through decorator-driven metadata. The same metadata feeds:
+- REST endpoint argument binding (`@onPost`, etc.).
+- Socket event payloads (`@onSocketEvent`).
+- Mindset tool function parameters (the LLM sees the validator type and the `@description`).
+- `Async.runCommand` / `Async.scheduleCommand` payloads (validated against the `@command` class).
+## Field validators
+All decorators are exported from `@wabot-dev/framework`. Apply them to public class fields.
+| Decorator | Effect |
+| --- | --- |
+| `@isString()` | Value must be `string` |
+| `@isNumber()` | Value must be `number` |
+| `@isBoolean()` | Value must be `boolean` |
+| `@isDate()` | Value must parse as `Date` (ISO 8601 input) |
+| `@isIn([...values])` | Value must be one of the listed literals |
+| `@isNotEmpty()` | String must be non-empty after trim |
+| `@isPresent()` | Field must be present (not `undefined`) |
+| `@isRecord(keyType, valueType)` | Plain object with typed keys/values; `keyType: 'number' \| 'string'`, `valueType: 'number' \| 'string' \| 'boolean'` |
+| `@isOptional()` | Skip remaining validators when the value is null/undefined |
+| `@isModel(OtherClass)` | Nested model validated against `OtherClass` |
+| `@isArray({ minLength?, maxLength? })` | Field must be an array |
+| `@min(n)` | Numeric / length minimum |
+| `@max(n)` | Numeric / length maximum |
+Validators chain top-to-bottom. Put `@isOptional()` **above** the type validator if the field is optional.
+```typescript
+import { description, isIn, isNotEmpty, isNumber, isOptional, isString, max, min } from '@wabot-dev/framework'
+export class ListGamesRequest {
+  @isString()
+  @isIn(['backlog', 'playing', 'finished', 'abandoned'])
+  @description('Filter by status')
+  status: 'backlog' | 'playing' | 'finished' | 'abandoned' = 'backlog'
+  @isNumber()
+  @min(1)
+  @max(20)
+  @description('Maximum number of games to return')
+  limit: number = 5
+  @isOptional()
+  @isString()
+  cursor?: string
+}
+```
+The `default` value on the field becomes the value when the input is missing and the field is optional.
+## `@description`
+`@description('...')` annotates a field or method. Two roles:
+1. On a request-class field: it becomes the LLM-facing parameter description for mindset tool functions.
+2. On a `@mindsetModule()` method: it becomes the tool's description (without it the function is not exposed as a tool).
+Mindset module functions **must** have a single request-object parameter (or no parameter), and every property of that request class must have both a type validator (e.g. `@isString()`) and a `@description(...)`. The framework throws at boot otherwise.
+## `validateAndTransform`
+```typescript
+import { validateAndTransform } from '@wabot-dev/framework'
+const { value, error } = validateAndTransform(rawInput, ListGamesRequest)
+if (error) {
+  // error.description + error.properties (per-field errors)
+}
+```
+Use this when you receive a payload outside a framework-managed boundary (e.g. a manually parsed file or queue message). Inside a REST/socket controller or a command handler the framework already validates the parameter for you.
+## `Mapper`
+`Mapper` is an injectable utility that combines deep-copy + `validateAndTransform`. It is useful when you need to convert a database row, a remote response, or a Storable into a typed model and you want a hard failure on shape mismatch (it throws `CustomError` with `httpCode: 500`).
+```typescript
+import { container, Mapper } from '@wabot-dev/framework'
+const mapper = container.resolve(Mapper)
+const game: GameDto = mapper.map(rawRow, GameDto)
+```
+`Mapper.map(data, ctor)` will:
+- Deep-copy `data` (Storables → plain objects, Dates → epoch ms).
+- Run all validators on the target class.
+- Return a typed instance, or throw.
+## Rules
+- Every public DTO/Request field needs at least one type validator. Without it, the framework can't introspect the type at runtime (TypeScript types are erased).
+- Always pair `@description` with a type validator on mindset module request fields.
+- Prefer field defaults over `@isOptional()` when you have a sensible default; reserve `@isOptional()` for fields that may genuinely be absent.
+- Don't subclass `RestRequest` unless you want the raw Express `Request` injected into the endpoint — see `wabot-rest-socket`.
+## Testing
+`assertValid(Model, data)`, `assertInvalid(Model, data, { path? })` and `validateFixture(Model, data)` from `@wabot-dev/framework/testing` test decorated models directly, with issues flattened to `{ path: 'items[0].name', message }`. See the `wabot-testing` skill.