@webjsdev/mcp 0.1.7 → 0.1.9

package/resources/agent-docs/metadata.md

@@ -1,334 +0,0 @@
-# Metadata API: full field reference
-
-Page modules export `metadata` (static) or `generateMetadata(ctx)`
-(request-scoped). Values flow into `<head>` at SSR time and merge across
-nested layouts (deeper wins). Surface is Next.js-compatible.
-
-## Type it with `Metadata`
-
-webjs exports a `Metadata` type covering every field below, so a typo
-(`titel`, `descripton`), wrong nesting, or a wrong-typed value
-(`themeColor: 123`) is a tsserver / checkJs error instead of a silently
-dropped tag. Import it from `@webjsdev/core` (the same isomorphic surface
-a page already imports `html` from). `MetadataContext` types the
-`generateMetadata(ctx)` argument.
-
-```ts
-import type { Metadata, MetadataContext } from '@webjsdev/core';
-
-// static
-export const metadata: Metadata = { title: 'Home', description: 'Welcome' };
-
-// request-scoped
-export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> {
-  return { title: `Post: ${ctx.params.slug}` };
-}
-```
-
-Every field is optional. Where the framework accepts a string OR an
-object (`title`, `viewport`, `robots`, `appleWebApp`, `icons`), the type
-is a union, so both forms type-check. The type lives in
-`packages/core/src/metadata.d.ts` (types-only, zero runtime, no build);
-it mirrors exactly what `packages/server/src/ssr.js` consumes.
-
-```ts
-export const metadata = {
-  // ----- Identity -----
-  title: 'Blog post title',                          // → <title>
-  // OR { template, default, absolute }. The template propagates from
-  // outer layouts, and deeper plain-string titles get wrapped via "%s".
-  // title: { template: '%s | webjs', default: 'webjs', absolute: 'standalone title' },
-  description: 'Short summary',                      // → <meta name="description">
-  keywords: ['ai', 'web components'],                // → <meta name="keywords"> (or single string)
-  authors: [{ name: 'Vivek', url: 'https://...' }],  // → <meta name="author"> (+ optional <link rel="author">)
-  creator: 'Vivek',                                  // → <meta name="creator">
-  publisher: 'My Co',                                // → <meta name="publisher">
-  applicationName: 'webjs',                          // → <meta name="application-name">
-  generator: 'webjs 0.5',                            // → <meta name="generator">
-  referrer: 'origin-when-cross-origin',              // → <meta name="referrer">
-
-  // ----- Base URL for relative metadata URLs -----
-  metadataBase: 'https://example.com',
-  // Any relative URL in openGraph.image, openGraph.url, twitter.image,
-  // alternates.canonical / languages / media / types, icons, authors[].url,
-  // archives / assets / bookmarks gets resolved against this base.
-
-  // ----- Viewport / theme -----
-  viewport: 'width=device-width,initial-scale=1',    // string OR object
-  // viewport: { width: 'device-width', initialScale: 1, maximumScale: 5, userScalable: true },
-  // (or split-export: `export const viewport = { … }`, the Next.js 14+ style)
-  themeColor: '#1c1613',                             // → <meta name="theme-color">
-  colorScheme: 'light dark',                         // → <meta name="color-scheme">
-
-  // ----- Crawler / SEO -----
-  robots: { index: true, follow: true, googleBot: 'index, max-snippet:-1' },
-  // OR robots: 'noindex, nofollow'
-  alternates: {
-    canonical: '/post',                              // → <link rel="canonical">
-    languages: { 'es-ES': '/es', 'fr-FR': '/fr' },   // → hreflang <link>s
-    media: { '(max-width: 600px)': '/mobile' },      // → media alternates
-    types: { 'application/rss+xml': '/rss.xml' },    // → RSS / Atom alternates
-  },
-  verification: {
-    google: 'token',                                 // → <meta name="google-site-verification">
-    yandex: 'token',                                 // → <meta name="yandex-verification">
-    yahoo: 'token',                                  // → <meta name="y_key">
-    me: 'https://me.example',                        // → <meta name="me"> (IndieAuth)
-    other: { 'facebook-domain-verification': 'fb-token' },
-  },
-
-  // ----- Icons + manifest -----
-  icons: {
-    icon: [{ url: '/icon.svg', type: 'image/svg+xml' }, { url: '/icon-32.png', sizes: '32x32' }],
-    apple: '/apple-touch-icon.png',
-    shortcut: '/favicon.ico',
-    other: [{ rel: 'mask-icon', url: '/mask.svg' }],
-  },
-  manifest: '/manifest.webmanifest',                 // → <link rel="manifest">
-
-  // ----- Open Graph -----
-  openGraph: {
-    type: 'website',
-    title: 'OG title',
-    description: 'OG description',
-    url: '/post',                                    // relative resolves via metadataBase
-    image: '/og.png',                                // ditto
-    'image:width': '1200',
-    'image:height': '630',
-    'image:alt': 'Post cover',
-    'site_name': 'My Site',
-  },
-
-  // ----- Twitter -----
-  twitter: {
-    card: 'summary_large_image',                     // required for big-image preview
-    title: 'Twitter title',
-    description: 'Twitter description',
-    image: '/og.png',
-  },
-
-  // ----- iOS / mobile -----
-  appleWebApp: {
-    capable: true,                                   // → apple-mobile-web-app-capable
-    title: 'My App',                                 // → apple-mobile-web-app-title
-    statusBarStyle: 'black-translucent',
-    startupImage: [{ url: '/splash.png', media: '(device-width: 320px)' }],
-  },
-  formatDetection: { telephone: false, email: false },
-  itunes: { appId: '12345', appArgument: 'myapp://open' },
-
-  // ----- Long-tail descriptive -----
-  category: 'tech',
-  classification: 'documentation',
-  abstract: 'A short summary',
-  archives: ['/archive-2024', '/archive-2023'],      // → <link rel="archives">
-  assets: '/assets-cdn',                             // → <link rel="assets">
-  bookmarks: ['/bm-1'],                              // → <link rel="bookmark">
-
-  // ----- Cache-control (response header, not <meta>) -----
-  cacheControl: 'public, max-age=60',                // pages default to no-store
-  preload: [
-    { href: '/public/fonts/Inter.woff2', as: 'font', type: 'font/woff2', crossorigin: 'anonymous' },
-  ],
-
-  // ----- Connection-warming hints (#243) -----
-  preconnect: [                                      // → <link rel="preconnect">
-    'https://api.example.com',                       //   warms DNS + TLS + TCP
-    { url: 'https://fonts.gstatic.com', crossorigin: true },
-  ],
-  dnsPrefetch: 'https://analytics.example.com',      // → <link rel="dns-prefetch"> (DNS only)
-
-  // ----- Catch-all -----
-  other: {
-    'msvalidate.01': 'bing-token',
-    'mobile-web-app-capable': 'yes',
-  },
-
-  // ----- JSON-LD structured data (schema.org) -----
-  jsonLd: {
-    '@context': 'https://schema.org',
-    '@type': 'Article',
-    headline: 'How webjs ships zero dead JS',
-    author: { '@type': 'Person', name: 'Vivek' },
-    datePublished: '2026-06-01',
-  },
-};
-```
-
-## Request-scoped via `generateMetadata`
-
-```ts
-import type { Metadata, MetadataContext } from '@webjsdev/core';
-
-export function generateMetadata(ctx: MetadataContext): Metadata {
-  return {
-    title: `Post: ${ctx.params.slug}`,
-    metadataBase: new URL(ctx.url).origin,
-  };
-}
-```
-
-## Split viewport export (Next.js 14+ pattern)
-
-All fields above under `metadata.viewport` are equally valid here, plus
-`themeColor` and `colorScheme` bubble up to their own meta tags.
-
-```ts
-export const viewport = {
-  width: 'device-width',
-  initialScale: 1,
-  themeColor: '#1c1613',
-  colorScheme: 'light dark',
-};
-```
-
-## Special: `cacheControl`
-
-Emitted as a **response header**, not a `<meta>` tag. Pages default to
-`no-store` for safety. Opt into caching by setting this explicitly.
-
-A **public** value (e.g. `public, max-age=60`) also enables conditional
-GET on the page (#240): the buffered HTML response gets a weak content-hash
-`ETag` (`W/"..."`) and a repeat request whose `If-None-Match` matches it
-returns a `304 Not Modified` with no body. A `no-store` or `private` page
-gets NO ETag and never 304s, so private / per-user content is never
-revalidated across sessions. A streamed Suspense response is not ETagged.
-See the conditional-GET section in the framework root `AGENTS.md`.
-
-## Connection-warming: `preconnect` / `dnsPrefetch` (#243)
-
-Warm a cross-origin connection the page is about to use (an API host, a
-font / image CDN) so the browser pays the DNS + TLS + TCP cost ahead of the
-first real request:
-
-```ts
-export const metadata = {
-  preconnect: [
-    'https://api.example.com',                              // bare URL
-    { url: 'https://fonts.gstatic.com', crossorigin: true },// crossorigin set
-  ],
-  dnsPrefetch: 'https://analytics.example.com',             // a single URL
-};
-```
-
-- **`preconnect`** emits `<link rel="preconnect" href="..." [crossorigin]>`,
-  warming DNS + TLS + TCP. Each entry is a URL string or
-  `{ url, crossorigin? }` (`crossorigin: true` / `''` emits a bare
-  `crossorigin`; a string like `'anonymous'` emits its value). A font CDN
-  needs `crossorigin`.
-- **`dnsPrefetch`** emits `<link rel="dns-prefetch" href="...">`, which
-  resolves DNS only (a lighter-weight precursor; it never carries
-  `crossorigin`).
-- Each field takes a URL string, the object form, or an array of either.
-  Every href is HTML-escaped.
-
-**Auto vendor preconnect.** For an UNPINNED app resolving vendors live from
-a cross-origin CDN, the framework auto-emits ONE
-`<link rel="preconnect" href="<cdn-origin>" crossorigin>` (the resolved
-vendor CDN origin, e.g. `https://ga.jspm.io`, derived from the importmap so
-a `--from jsdelivr` app preconnects to jsdelivr), so the browser warms that
-connection before the importmap resolves. It is DEDUPED against an
-author-declared `preconnect` to the same origin, and NONE is emitted for a
-same-origin pinned app (vendors served from the app's own origin) or an app
-with no cross-origin vendors.
-
-## JSON-LD structured data (`jsonLd`)
-
-`metadata.jsonLd` emits schema.org structured data as one or more
-`<script type="application/ld+json">` blocks in `<head>`. This is the
-highest-leverage modern SEO surface (Google's Article, Product,
-BreadcrumbList, Organization, and FAQ rich results all read it). webjs
-stays true to its no-build identity here. JSON-LD is a web standard
-rendered as a plain script tag, so the framework ONLY serializes and
-escapes. There is no schema library and no validation. **You own the
-schema.org object.**
-
-**Single object** emits one script:
-
-```ts
-import type { Metadata } from '@webjsdev/core';
-
-export const metadata: Metadata = {
-  jsonLd: {
-    '@context': 'https://schema.org',
-    '@type': 'Article',
-    headline: 'How webjs ships zero dead JS',
-    author: { '@type': 'Person', name: 'Vivek' },
-    datePublished: '2026-06-01',
-    image: 'https://example.com/og.png',
-  },
-};
-```
-
-renders:
-
-```html
-<script type="application/ld+json">{"@context":"https://schema.org","@type":"Article",...}</script>
-```
-
-**An array** emits one script PER element. Use it to ship several graphs
-for one page (a Product alongside its BreadcrumbList, say):
-
-```ts
-export const metadata: Metadata = {
-  jsonLd: [
-    {
-      '@context': 'https://schema.org',
-      '@type': 'Product',
-      name: 'Acme Widget',
-      offers: { '@type': 'Offer', price: '19.99', priceCurrency: 'USD' },
-    },
-    {
-      '@context': 'https://schema.org',
-      '@type': 'BreadcrumbList',
-      itemListElement: [
-        { '@type': 'ListItem', position: 1, name: 'Shop', item: 'https://example.com/shop' },
-        { '@type': 'ListItem', position: 2, name: 'Widget', item: 'https://example.com/shop/widget' },
-      ],
-    },
-  ],
-};
-```
-
-**Per-request data** works the same way through `generateMetadata`, so a
-dynamic route can build the Article from the loaded record:
-
-```ts
-import type { Metadata, MetadataContext } from '@webjsdev/core';
-
-export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> {
-  const post = await getPost(ctx.params.slug);   // via a server query
-  return {
-    title: post.title,
-    jsonLd: {
-      '@context': 'https://schema.org',
-      '@type': 'Article',
-      headline: post.title,
-      datePublished: post.publishedAt,
-      author: { '@type': 'Person', name: post.authorName },
-    },
-  };
-}
-```
-
-### Escaping guarantee
-
-The serialized JSON is HTML-safe-escaped automatically. `<`, `>`, `&`,
-and the line separators U+2028 / U+2029 are replaced with their JSON
-Unicode escapes (`<` and friends). A JSON parser decodes those back to
-the original characters, so the embedded data still parses to your exact
-object, while the literal byte sequence `</script>` can never form in the
-served HTML. So a value containing `</script><img src=x onerror=...>`
-cannot break out of the script tag. You do not escape anything yourself.
-
-The block is a NON-EXECUTABLE data island (`type="application/ld+json"`),
-so a Content-Security-Policy `script-src` does not gate it and it carries
-NO nonce.
-
-### Robustness
-
-The framework fails SAFE per element. An entry that is not a plain object,
-or an object with a circular reference that `JSON.stringify` cannot
-serialize, is skipped (with a one-line `console.warn`) and never breaks
-the rest of the head. Absent `jsonLd` emits nothing (the field is purely
-additive).

package/resources/agent-docs/orm.md

@@ -1,198 +0,0 @@
-# ORM: the Drizzle query surface (rc.3)
-
-The scaffold pins **`drizzle-orm@^1.0.0-rc.3`** (`db/columns.server.ts` header
-records this, research #562). rc.3 is the 1.0 release candidate with the new
-Relational Query Builder v2 (RQBv2) wired up in `db/connection.server.ts` via
-`drizzle({ client, relations })`. Several method overloads that older Drizzle
-tutorials rely on do NOT exist in rc.3, so training-data patterns from
-Drizzle 0.29 through 0.36 trip real TypeScript errors here. This page codifies
-the shapes that compile against the installed version.
-
-Ground rules for this version.
-
-1. **Reads go through the relational query API** (`db.query.<table>.findFirst`
-   / `.findMany`), not `db.select().from()`. Relations are pre-registered in
-   `db/connection.server.ts`, so `with` joins work with zero boilerplate.
-2. **`db.select()` takes no argument in rc.3.** The projection overload
-   (`db.select({ ... })`) was removed. Passing a projection object is a
-   `TS2554` compile error.
-3. **`.returning()` takes no argument in rc.3.** It always returns the full
-   inserted / updated / deleted rows (columns only, no relations). Passing a
-   field object is a `TS2554` compile error.
-
-All examples assume the scaffold imports.
-
-```ts
-import { eq, and, inArray, desc } from 'drizzle-orm';
-import { db } from '#db/connection.server.ts';
-import { posts, users } from '#db/schema.server.ts';
-```
-
-These belong in a `*.server.ts` query or action (never a page or component,
-invariant 1). Reads live in `modules/<feature>/queries/*.server.ts`, mutations
-in `modules/<feature>/actions/*.server.ts`, one function per file.
-
----
-
-## Reads: use the relational query API
-
-`db.query.<table>` reads a whole row by default, filters with a **plain object**
-`where` (the RQBv2 shape, not a `sql` expression), orders with an `orderBy`
-object, and pulls relations with `with`. This is the shape every scaffold query
-uses.
-
-```ts
-// RIGHT: single row by a unique column
-const post = await db.query.posts.findFirst({
-  where: { slug: input.slug },
-  with: { author: { columns: { name: true, email: true } } },
-});
-
-// RIGHT: a list, newest first, with a projected column set
-const rows = await db.query.posts.findMany({
-  orderBy: { createdAt: 'desc' },
-  where: { authorId: me.id },
-  columns: { id: true, slug: true, title: true },
-  with: { author: { columns: { name: true } } },
-});
-
-// RIGHT: existence check, pull only the id
-const exists = await db.query.posts.findFirst({
-  where: { slug },
-  columns: { id: true },
-});
-```
-
-The `where` object supports equality directly (`{ slug }`), nested operators
-(`{ createdAt: { gt: cutoff } }`), and `AND` by listing multiple keys. Reach for
-the imported `eq` / `and` / `inArray` operators only on the `db.select` /
-`db.delete` / `db.update` builders below, where the `.where()` clause is an SQL
-expression rather than the RQBv2 object.
-
-### Pitfall: the `db.select({ ... })` projection overload is gone
-
-Older Drizzle let you project columns by passing an object to `select`. rc.3
-removed that overload, so the argument no longer type-checks.
-
-```ts
-// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
-const rows = await db
-  .select({ id: posts.id, title: posts.title })
-  .from(posts);
-```
-
-If you genuinely need the query-builder (a manual join, a `groupBy`, an
-aggregate the RQB does not express), call `select` with **no arguments** to get
-the full row, then narrow in JS.
-
-```ts
-// RIGHT: full-row select, no projection argument
-const rows = await db.select().from(posts).where(eq(posts.authorId, me.id));
-```
-
-For anything the relational API covers (by-id lookups, ordered lists, relation
-joins, column subsets), prefer `db.query.*`. It is the shorter, typed,
-relation-aware path and it sidesteps the removed overload entirely.
-
----
-
-## Mutations: `insert` / `update` / `delete` with a no-arg `.returning()`
-
-Mutations use the query-builder, filter with the imported SQL operators, and
-read back rows with `.returning()`. In rc.3 `.returning()` has **only the
-no-argument overload**, so it yields the full row set every time.
-
-```ts
-// RIGHT: insert, read back the created row
-const [row] = await db
-  .insert(posts)
-  .values({ title, body, slug, authorId: me.id })
-  .returning();
-
-// RIGHT: update by id, read back the updated row
-const [row] = await db
-  .update(posts)
-  .set({ title, body })
-  .where(eq(posts.id, id))
-  .returning();
-
-// RIGHT: delete by id (no read-back needed)
-await db.delete(posts).where(eq(posts.id, id));
-```
-
-### Pitfall: `.returning({ ... })` with a field argument
-
-The older field-selecting `.returning({ id: posts.id })` overload does not exist
-in rc.3.
-
-```ts
-// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
-const [row] = await db
-  .insert(posts)
-  .values({ title, body, slug, authorId: me.id })
-  .returning({ id: posts.id, slug: posts.slug });
-```
-
-Call `.returning()` bare and destructure or map the fields you need in JS.
-
-```ts
-// RIGHT: full row back, then pick fields
-const [row] = await db.insert(posts).values({ ... }).returning();
-const created = { id: row.id, slug: row.slug };
-```
-
-### `.returning()` yields columns only, never relations
-
-A `.returning()` row is the table's own columns. It does NOT carry `with`
-relations the way a `db.query.*` read does. When the caller expects a joined
-shape (an author name alongside the post), insert then re-read, or splice the
-already-known related value in by hand.
-
-```ts
-// RIGHT: insert returns columns; add the known author locally
-const [row] = await db.insert(posts).values({ title, body, slug, authorId: me.id }).returning();
-return { success: true, data: { ...formatPost(row), authorName: me.name } };
-```
-
----
-
-## Column helpers live in `db/columns.server.ts` (the one dialect seam)
-
-The schema is written against helpers (`table`, `pk`, `uuidPk`, `uuid`, `bool`,
-`timestamp`, `createdAt`, `updatedAt`, `index`) rather than raw drizzle
-builders, so the same `db/schema.server.ts` runs on SQLite and Postgres. Only
-`db/columns.server.ts` differs per dialect. Two of those helpers exist because
-rc.3 has not yet exposed a stable no-arg overload.
-
-- **`table`** wraps `sqliteTableCreator((name) => name, 'snake_case')`. In rc.3
-  the snake_case casing lives on the table factory, so column keys map to
-  snake_case SQL names automatically. Do not restate a `snake_case` casing
-  option on `drizzle()`.
-- **`index(...cols)`** wraps rc.3's `index(name)`, which still requires a name
-  argument the runtime auto-fills. The helper synthesizes drizzle-kit's own
-  collision-free name, so schema authors call `index(t.createdAt)` with no name.
-  Replace it with a bare `index()` once 1.0 stable ships the no-arg overload.
-
-When you add a table, use the helpers (`pk()` for an integer autoincrement id,
-`uuidPk()` for an app-generated uuid string id, `createdAt()` for a
-default-to-now timestamp) rather than reaching for raw `integer(...).primaryKey(...)`
-call sites, so the Postgres swap stays a one-file change.
-
----
-
-## Where each query shape belongs
-
-| Task | API | File |
-|---|---|---|
-| Row by unique column | `db.query.t.findFirst({ where })` | `queries/*.server.ts` |
-| Ordered / filtered list | `db.query.t.findMany({ orderBy, where, with })` | `queries/*.server.ts` |
-| Manual join / aggregate | `db.select().from(t)` (no projection arg) | `queries/*.server.ts` |
-| Create | `db.insert(t).values(...).returning()` | `actions/*.server.ts` |
-| Update | `db.update(t).set(...).where(eq(...)).returning()` | `actions/*.server.ts` |
-| Delete | `db.delete(t).where(eq(...))` | `actions/*.server.ts` |
-
-Cross-references. Derived row TYPES and the `ActionResult<T>` envelope belong in
-a browser-safe `modules/<feature>/types.ts` (see `agent-docs/types-and-mutations.md`).
-Full page / action / query recipes live in `agent-docs/recipes.md`. The
-server-only boundary that keeps `db` off the client is in the root `AGENTS.md`
-(invariant 1).