@stacksjs/defaults 0.75.34 → 0.75.35

package/ai/skills/stacks-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 647 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 648 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-auth/SKILL.md

@@ -161,8 +161,12 @@ routes: minting and revoking both carry semantics a generic route does not.
 The authorization server is opt-in through `config/auth.ts` under
 `oauthProvider`. It is separate from social sign-in, where Stacks is the OAuth
 client. The provider profile is Authorization Code with S256 PKCE and rotating
-refresh tokens. It does not support implicit, password, or client-credentials
-grants. It also does not implement token introspection or OpenID Connect.
+refresh tokens. Confidential client credentials are opt-in through
+`oauthProvider.clientCredentials` and mint access-only tokens without refresh
+tokens. Protected resource-server introspection is separately opt-in through
+`oauthProvider.introspection`; it authenticates a confidential client and
+requires that client to share a configured resource audience with the token.
+It does not support implicit or password grants or OpenID Connect.
 
 When enabled, the default auth route bundle registers:
 
@@ -178,6 +182,11 @@ Resource audiences are absolute URIs and redirect URIs use exact matching.
 The consent view is `auth/oauth/consent` by default and can be overridden with
 `oauthProvider.consent.view`. Use `oauthProvider.consent.resolveWorkspace` when
 the application must bind consent to current server-owned workspace authority.
+Use `oauthProvider.subjectEligibility` when account status is represented by
+application data that is not simply the presence of a user row. The callback
+is rechecked before consent approval, delegated code exchange and refresh, and
+by introspection; returning false revokes the affected grant and reports the
+token inactive.
 
 Provider actions return 404 while `oauthProvider.enabled` is false. The token
 and revocation endpoints use protocol credentials and intentionally skip

package/ai/skills/stacks-buddy/SKILL.md

@@ -611,7 +611,7 @@ buddy ai:context             # compact deterministic project context for coding
   -o/--output [path]         # write to a file instead of stdout
   --max-chars [characters]   # prompt payload character budget (default: 4000)
   --model [model]            # model family for heuristic token estimates
-buddy doctor                 # health checks (Bun version, Node, package.json, .env, APP_KEY)
+buddy doctor                 # health checks (Bun version, Node, package.json, .env, APP_KEY, mail DNS)
 buddy tinker                 # interactive REPL with Stacks preloaded
   -e/--eval [expr]           # evaluate expression and exit
   --print [expr]             # evaluate, print, and exit

package/ai/skills/stacks-cms/SKILL.md

@@ -190,6 +190,8 @@ email. Moderate without a dashboard with `buddy comments:list [--status] [--type
 | GET | `/blog/feed.xml` | RSS 2.0 feed (20 recent) |
 | GET | `/blog/sitemap.xml` | XML sitemap for SEO |
 
+The site-wide `/sitemap.xml` merges the published posts in, so crawlers find them from the root sitemap too (see `stacks-server`, "Sitemap and robots.txt").
+
 ## Post Bodies: Images, Grids, Zoom and Embeds
 
 Blog post HTML goes through `renderPostHtml` from `@stacksjs/cms/article`, built on ts-medium-editor's article renderer. The BunPress blog (`core/actions/src/blog.ts`) does this already; an stx-native blog calls it from its post view:

package/ai/skills/stacks-config/SKILL.md

@@ -65,7 +65,7 @@ they name: `defineEvents` and `defineListener` from `@stacksjs/events`,
 ### Core App
 | File | Type | Key Settings |
 |------|------|-------------|
-| `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale |
+| `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale, seo (sitemap.xml / robots.txt) |
 | `auth.ts` | AuthConfig | guards, providers, token and browser-session lifetimes, passwordReset |
 | `database.ts` | DatabaseConfig | default driver, connections (sqlite/mysql/postgres/dynamodb), queryLogging |
 | `cache.ts` | CacheConfig | driver('memory'), ttl(3600), maxKeys(-1), redis config |

package/ai/skills/stacks-email/SKILL.md

@@ -244,6 +244,8 @@ With `server.enabled`, `buddy deploy` reconciles the mail domain's DNS through w
 
 Postmaster Tools is the only view of why Gmail files mail as spam when SPF, DKIM and DMARC all pass. Its value is issued per Google account and cannot be generated: add the domain at https://postmaster.google.com, copy the TXT value, set `server.postmaster.google`, deploy, then press Verify in Postmaster Tools. Until it is set the deploy prints where to get it; `postmaster: false` silences that.
 
+When no configured provider can write the zone (no credentials for the provider its nameservers name, e.g. a Cloudflare zone with no `CLOUDFLARE_API_TOKEN`), nothing is published, on this deploy or any later one. The deploy warns with the exact fix (`buddy env:set CLOUDFLARE_API_TOKEN <value> -f .env.production`) and the records to add by hand. `buddy doctor` reports the same without deploying: "Mail DNS provider" (which provider the nameservers name, and whether its keys are in `.env.production`, by name only), "Mail DNS records" (MX, SPF, DKIM at `mail._domainkey`, DMARC in public DNS, each exactly once, the DMARC policy against config, SPF against the MX host's address) and "Postmaster Tools". Code: `core/buddy/src/mail-dns-health.ts`, `core/buddy/src/dns-credentials.ts`.
+
 ## Application Mail Example
 
 ```typescript

package/ai/skills/stacks-env/SKILL.md

@@ -106,6 +106,70 @@ provider        // 'github-actions' | 'gitlab-ci' | 'circleci' | 'travis' | 'jen
 providerInfo    // { name: string, ... }
 ```
 
+## Remote integration environments
+
+Gate anything that transmits off the box - error reporting, analytics, log
+shipping - through `@stacksjs/env`, rather than inventing a policy per adapter.
+Without a shared gate, every developer machine and CI run reports into the same
+project as production, and a local startup failure reads as a live incident
+(stacksjs/stacks#2792).
+
+```typescript
+import { initializeIntegration } from '@stacksjs/env'
+
+// The callback does not run when the gate is closed, so constructing a client,
+// registering hooks or starting a flush timer inside it is safe.
+const result = initializeIntegration(config.bughq, ({ environment }) =>
+  installBugHq({ key: config.bughq.key, environment }))
+
+if (!result.initialized)
+  log.debug(`BugHQ not installed: ${result.gate.reason}`)
+```
+
+An application declares **only** `environments`. Do not add a sibling
+`environment` option and do not ask the app to repeat `env.APP_ENV`: the gate
+resolves the effective label once and hands it to the adapter for event
+metadata.
+
+Extend `EnvironmentGatedIntegration` from the adapter's own options type so
+the application gets `enabled` and `environments` and nothing else. Analytics
+is the adapter shipping this today:
+
+```typescript
+// config/analytics.ts
+export default {
+  driver: 'analyticshq',
+  environments: ['production', 'staging'], // omit to get exactly this
+  drivers: { analyticshq: { siteId: '...' } },
+} satisfies AnalyticsConfig
+```
+
+| Configuration | Result |
+|---|---|
+| `environments` omitted | `REMOTE_TELEMETRY_ENVIRONMENTS`, which is `production` and `staging` |
+| `environments: []` | off everywhere, the explicit way to disable without removing credentials |
+| `enabled: false` | off, always; checked before the allowlist so it is the last word |
+| `enabled: true` | does **not** bypass the allowlist |
+| `APP_ENV` unset or malformed | off, with `reason: 'environment-unknown'` |
+
+The gate reads `APP_ENV` only, and reads it at call time. It does not fall back
+to `NODE_ENV` the way `appEnv()` does, because an absent `APP_ENV` must not be
+guessed into a label an allowlist might admit. Call time rather than import time
+matters because a test harness or a CLI resolving `--env` routinely sets it
+after the module graph has loaded (stacksjs/stacks#2581).
+
+`prod`, `stage` and `dev` fold onto `production`, `staging` and `development`.
+`local`, `development` and `test` are deliberately **not** folded together:
+allowing your own machine must not also allow CI.
+
+The answer is the same in a web or API server, the dashboard, a worker and a
+Buddy command, because all of them read the same variable. Browser integrations
+receive only the resolved public label, never server credentials.
+
+`APP_ENV` is a configuration label, not proof of deployment identity: a local
+command launched with `APP_ENV=production` qualifies. It prevents accidents; it
+is not a security boundary.
+
 ## .env File Loading
 
 ```typescript

package/ai/skills/stacks-server/SKILL.md

@@ -349,6 +349,51 @@ if (await isDownForMaintenance()) {
 await up()
 ```
 
+## Sitemap and robots.txt (core/actions/src/seo.ts)
+
+The views server answers `/sitemap.xml` and `/robots.txt` for every app, generated from
+`resources/views` at request time. `buddy dev` (`core/actions/src/dev/views.ts`) and `buddy serve`
+(`core/buddy/src/production-server.ts`) call the same `createSiteSeoHandler()` at the same point in
+`onRequest` (after redirects and rewrites), so dev and production answer identically. No route, no
+build step, no app code. Do not add `route.get('/sitemap.xml')` to `routes/`: the views server does
+not forward root GETs to the API.
+
+- **Listed**: every static route under `resources/views`, with `lastmod` from the file, plus the
+  blog's published posts (`content/blog`, or a CMS-built `dist/blog/sitemap.xml`) merged into the
+  same file. `/blog/sitemap.xml` is still served too.
+- **Not listed**: dynamic routes (`[slug].stx`), error and holding pages (`404`, `errors/*`,
+  `coming-soon`), `components/`, `layouts/`, `partials/`, `emails/`, `_`-prefixed files, pages behind
+  `definePageMeta({ middleware: ['auth'] })`, paths in `seo.sitemap.exclude`, paths robots.txt
+  disallows, and any page that says **noindex**. The framework's default views (`/login`, ...) are
+  never listed.
+- **noindex**, the one signal, read from the page source: `<meta name="robots" content="noindex">`,
+  `robots: 'noindex'` in a head object, or `const noindex = true` in the server script (the flag a
+  shared head partial turns into the tag - the scan cannot follow an `@include`, so spell it that
+  way). `definePageMeta({ sitemap: false })` also keeps a page out.
+- **robots.txt**: `User-agent: *`, `Allow: /`, `Disallow: /api/` plus `seo.robots.disallow`, extra
+  groups from `seo.robots.rules`, and `Sitemap: <origin>/sitemap.xml`. Never disallow a page just to
+  hide it: a crawler that cannot fetch it never sees its noindex.
+- **Hand-written files win**: `public/sitemap.xml` / `public/robots.txt` are served instead, and the
+  server warns at boot when the hand-written sitemap misses a page it would list. Delete the file to
+  switch, or set `seo.handwritten: 'replace'`.
+- **Origin**: `seo.origin`, else `app.url` (APP_URL), else the request origin (local dev only).
+- **Config** (`config/app.ts`, type `SeoOptions` in `core/types/src/seo.ts`):
+
+```ts
+seo: {
+  sitemap: {
+    include: ['/products/blue-mug'],            // instances of dynamic routes
+    entries: async () => (await Product.all()).map(p => `/products/${p.slug}`),
+    exclude: ['/styleguide', '/internal/'],     // trailing / or * = subtree
+  },
+  robots: { disallow: ['/checkout/', '/thanks'], rules: [{ userAgent: 'GPTBot', disallow: ['/'] }] },
+  // sitemap: false / robots: false turn either off
+}
+```
+
+Production caches each file for ten minutes (for `entries()`); development regenerates per request.
+Static frontend builds (`buddy build views`) use stx's own SSG sitemap instead.
+
 ## Docker Build Pipeline (server/build.ts)
 
 The build process (`bun build.ts` from `storage/framework/server/`):

package/ai/skills/stacks-stx/SKILL.md

@@ -240,6 +240,30 @@ function showSearch(): void {
 - **Markdown** — Markdown rendering with syntax highlighting
 - **A11y** — Accessibility checking and auto-fixing
 
+### SEO directives
+
+Every argument is an expression evaluated against the template context (`<script server>` variables, the render context, and, inside an `@include` partial, the partial's own `<script server>`). A quoted string is literal text.
+
+```html
+<script server>
+const seo = { title: post.title, description: post.excerpt, canonical: url, openGraph: { image: post.cover } }
+</script>
+
+@seo(seo)                              <!-- or @seo({ ...seo, title }), @seo(buildSeo(post)), @seo({ title: 'Literal' }) -->
+@seo(page.seo ?? {})                   <!-- a variable only some pages define -->
+@meta('author', post.author)           <!-- unquoted value: an expression -->
+@meta('description', 'Plain text')     <!-- quoted value: literal, never looked up -->
+@meta('keywords', tags)                <!-- an array joins with ", " -->
+@meta('og:title')                      <!-- one argument: reads `title`, then `openGraph.title` -->
+@metaTag({ httpEquiv: 'refresh', content: '30' })
+@structuredData(product)               <!-- object or array of objects; @context defaults to schema.org -->
+```
+
+- `@seo` reads only `title`, `description`, `keywords`, `robots`, `canonical`, `openGraph`, `twitter`, `structuredData`. `image`, `url` and `type` are not top-level keys (use `openGraph.image`, `canonical`, `openGraph.type`); stray keys are ignored with a warning.
+- A directive that cannot produce its tag (a variable that is not defined, a value of the wrong type, a syntax error, an unclosed call) leaves `<!-- [SEO Error ...] -->` in its place and logs `[stx] @seo(seo) in <file>: ...`. A defined variable holding `null` renders nothing, quietly. Read those warnings; they are the only sign a page shipped without its preview card.
+- `@meta` in a page is staged into `<head>`. `@seo`, `@metaTag` and `@structuredData` write where they sit, so put them inside `<head>` (a layout or head partial). In a page body use `useSeoMeta({ title, description, ogImage })` in `<script server>`, which always reaches `<head>`.
+- Requires `@stacksjs/stx` >= 0.2.343. Older versions only matched `@seo({ ... })` literally and sent unquoted `@meta` values such as `post.author` as text, without a warning.
+
 ### Dev Tools
 - **Dev server** with HMR (Hot Module Replacement)
 - **Image optimization**
@@ -291,4 +315,5 @@ await addLayout('admin', { nav: true, footer: true })
 - **Script block restrictions** — only stx-compatible code (signals, composables, directives), no vanilla DOM APIs
 - **Pre-paint state** - use `@appearanceBootstrap`, never a raw browser script in the template
 - **Components go in `resources/`** — not in `app/` or `storage/`
+- **SEO directives take expressions** - `@seo(seo)`, `@meta('author', post.author)` and `@structuredData(product)` are evaluated; a failure shows up as an inline `<!-- [... Error] -->` comment plus a `[stx]` console warning naming the file, never as silent emptiness. Keep `@seo` inside `<head>`
 - **118+ modules** — STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more

package/app/Actions/Auth/OAuthClientStoreAction.ts

@@ -26,10 +26,13 @@ export default new Action({
     const body = await request.all() as Record<string, unknown>
     const name = typeof body.name === 'string' ? body.name : null
     const type = body.type === 'public' || body.type === 'confidential' ? body.type : null
-    const redirectUris = oauthStringList(body.redirect_uris)
+    const redirectUris = body.redirect_uris === undefined ? [] : oauthStringList(body.redirect_uris)
+    const grantTypes = body.grant_types === undefined
+      ? ['authorization_code', 'refresh_token']
+      : oauthStringList(body.grant_types)
     const scopes = oauthStringList(body.scopes)
     const resources = oauthStringList(body.resources)
-    if (!name || !type || !redirectUris || !scopes || !resources)
+    if (!name || !type || !redirectUris || !grantTypes || !scopes || !resources)
       return response.badRequest('OAuth client registration metadata is invalid')
 
     try {
@@ -38,7 +41,7 @@ export default new Action({
         type,
         tokenEndpointAuthMethod: type === 'public' ? 'none' : 'client_secret_basic',
         redirectUris,
-        grantTypes: ['authorization_code', 'refresh_token'],
+        grantTypes,
         scopes,
         resources,
       })

package/app/Actions/Auth/OAuthClientUpdateAction.ts

@@ -30,17 +30,20 @@ export default new Action({
 
     const body = await request.all() as Record<string, unknown>
     const name = typeof body.name === 'string' ? body.name : null
-    const redirectUris = oauthStringList(body.redirect_uris)
+    const redirectUris = body.redirect_uris === undefined ? [] : oauthStringList(body.redirect_uris)
+    const grantTypes = body.grant_types === undefined
+      ? ['authorization_code', 'refresh_token']
+      : oauthStringList(body.grant_types)
     const scopes = oauthStringList(body.scopes)
     const resources = oauthStringList(body.resources)
-    if (!name || !redirectUris || !scopes || !resources)
+    if (!name || !redirectUris || !grantTypes || !scopes || !resources)
       return response.badRequest('OAuth client update metadata is invalid')
 
     try {
       const client = await updateOAuthClient(provider, ownerId, clientId, {
         name,
         redirectUris,
-        grantTypes: ['authorization_code', 'refresh_token'],
+        grantTypes,
         scopes,
         resources,
       })

package/app/Actions/Auth/OAuthIntrospectionAction.ts

@@ -0,0 +1,25 @@
+import { Action } from '@stacksjs/actions'
+import { handleOAuthIntrospectionRequest, resolveOAuthProviderConfig } from '@stacksjs/auth'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+
+export default new Action({
+  name: 'OAuthIntrospectionAction',
+  description: 'Introspect a delegated OAuth token',
+  method: 'POST',
+  // Resource servers authenticate with their registered OAuth client instead
+  // of a browser session, so this protocol endpoint does not use CSRF.
+  skipCsrf: true,
+
+  async handle(request: RequestInstance) {
+    const provider = resolveOAuthProviderConfig(config.auth.oauthProvider)
+    if (!provider || !provider.introspection)
+      return response.notFound('OAuth introspection is not enabled')
+
+    return handleOAuthIntrospectionRequest(provider, {
+      body: (await request.rawBody?.()) ?? '',
+      contentType: request.headers.get('content-type'),
+      authorization: request.headers.get('authorization'),
+    })
+  },
+})

package/app/Actions/Auth/OAuthTokenAction.ts

@@ -15,7 +15,7 @@ const isSubjectEligible: OAuthSubjectEligibility = async (subject) => {
 
 export default new Action({
   name: 'OAuthTokenAction',
-  description: 'Exchange OAuth authorization codes and refresh tokens',
+  description: 'Exchange OAuth authorization codes, refresh tokens, and machine credentials',
   method: 'POST',
   // OAuth clients authenticate with PKCE or HTTP Basic and cannot obtain the
   // browser CSRF cookie. The protocol boundary validates its own credentials.
@@ -26,10 +26,12 @@ export default new Action({
     if (!provider)
       return response.notFound('OAuth provider is not enabled')
 
+    const eligible = provider.subjectEligibility ?? isSubjectEligible
+
     return handleOAuthTokenRequest(provider, {
       body: (await request.rawBody?.()) ?? '',
       contentType: request.headers.get('content-type'),
       authorization: request.headers.get('authorization'),
-    }, { isSubjectEligible })
+    }, { isSubjectEligible: eligible })
   },
 })

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.34",
+  "version": "0.75.35",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.34",
+  "version": "0.75.35",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.75.34",
+    "@stacksjs/mobile": "^0.75.35",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/routes/auth.ts

@@ -31,6 +31,7 @@ const oauthProvider = resolveOAuthProviderConfig(config.auth.oauthProvider)
 const oauthAuthorizationPath = oauthProvider ? new URL(oauthProvider.endpoints.authorization).pathname : '/oauth/authorize'
 const oauthTokenPath = oauthProvider ? new URL(oauthProvider.endpoints.token).pathname : '/oauth/token'
 const oauthRevocationPath = oauthProvider ? new URL(oauthProvider.endpoints.revocation).pathname : '/oauth/revoke'
+const oauthIntrospectionPath = oauthProvider ? new URL(oauthProvider.endpoints.introspection).pathname : '/oauth/introspect'
 const oauthMetadataPath = oauthProvider
   ? oauthAuthorizationServerMetadataPath(oauthProvider.issuer)
   : '/.well-known/oauth-authorization-server'
@@ -49,6 +50,7 @@ route.post('/register', 'Actions/Auth/RegisterAction').rateLimit(3, 'minute')
 // the endpoint's credential boundary, so the action opts out of browser CSRF.
 route.post(oauthTokenPath, 'Actions/Auth/OAuthTokenAction').rateLimit(30, 'minute')
 route.post(oauthRevocationPath, 'Actions/Auth/OAuthRevocationAction').rateLimit(30, 'minute')
+route.post(oauthIntrospectionPath, 'Actions/Auth/OAuthIntrospectionAction').rateLimit(30, 'minute')
 route.get(oauthAuthorizationPath, 'Actions/Auth/OAuthAuthorizationAction').rateLimit(60, 'minute')
 route.post(oauthAuthorizationPath, 'Actions/Auth/OAuthConsentAction').middleware('auth').rateLimit(30, 'minute')
 route.get(oauthMetadataPath, 'Actions/Auth/OAuthMetadataAction')