@happyvertical/smrt-template-sveltekit 0.53.3 → 0.54.0

package/AGENTS.md

@@ -17,6 +17,22 @@ It is the ground-up alternative to `smrt-saas-starter`.
   images ship no Corepack, so the Dockerfile installs a pinned copy.
 - `runtime.profile` is the canonical infrastructure selector. Generated apps
   expose deterministic `app:*` operations and keep runtime state outside source.
+- Every lifecycle script is a `smrt app <operation>` one-liner
+  (`packages/cli/agents/app-commands.md`); the template ships no `scripts/`.
+  Never reintroduce copied operator scripts: fix the CLI command instead.
+- Server composition is `createSmrtSvelteKitRuntime()` from
+  `@happyvertical/smrt-app-runtime/sveltekit`, built once in
+  `src/lib/server/smrt.ts`, which holds only `runtime` and its options
+  (provider readiness via `createProviderReadinessProbe`), so the web process
+  never imports the CLI. The runtime takes the local writer lease by default,
+  the `smrt()` plugin injects the generated registration, and each generated
+  route embeds a prelude that imports `$lib/server/smrt` and resolves
+  collections through its exported `runtime.getCollection()` (#3416). A legacy
+  `getCollection`/`getSmrtConfig` export would take precedence (deprecated,
+  honoured for one release): never re-add one, a register import, guard, or
+  manifest hydration.
+  Health, diagnostics, layout session, and owner setup routes mount that
+  package's handlers.
 - The production baseline uses adapter-node with separate web, task-worker, and
   schedule-worker processes. Workers import the build-compiled
   `.smrt/runtime/register.js` (#3117) before creating runners so app-defined
@@ -37,8 +53,9 @@ It is the ground-up alternative to `smrt-saas-starter`.
   different or stale server is never accepted as this app. Deployed health
   responses expose only generic status and profile.
 - Directly used `@happyvertical/smrt-*` packages share one current release range.
-- `@happyvertical/smrt-cli` is a direct dev dependency because scripts/docs use
-  its binary. The template includes `@happyvertical/smrt-web` because the root
+- `@happyvertical/smrt-cli` is a direct dev dependency because every
+  lifecycle script runs its binary; the runtime image keeps dev dependencies so
+  workers and operator commands can. The template includes `@happyvertical/smrt-web` because the root
   Provider wires the generated read-only WebMCP definitions for every page.
 - The generated MCP server resolves its imports from the scaffolded app, not
   from the CLI, so every specifier `generate-mcp` emits must be declared here.
@@ -49,9 +66,10 @@ It is the ground-up alternative to `smrt-saas-starter`.
   for the default worker and tenant surfaces. Do not assume pnpm exposes the
   CLI's or core's transitive dependencies to the app root — its strict layout
   does not (#2297).
-- `smrtConsumer()` explicitly consumes profiles, tenancy, and users manifests;
-  `smrtPlugin()` scans `src/lib/objects`, generates Vite virtual definitions,
-  SvelteKit routes, runtime registration, and knowledge artifacts.
+- `vite.config.ts` is `[sveltekit(), smrt()]`. The preset consumes exactly the
+  packages in `smrt.config.ts` `consumer.packages` (profiles, tenancy, users),
+  scans `src/lib/objects`, and generates Vite virtual definitions, SvelteKit
+  routes, runtime registration, and knowledge artifacts.
 - `pnpm db:migrate` builds first to refresh generated artifacts, then the
   migration wrapper holds the shared operation/writer exclusion for the full
   manifest-driven migration command. Do not restore deprecated `smrt db:setup`
@@ -59,11 +77,11 @@ It is the ground-up alternative to `smrt-saas-starter`.
 
 ## Application patterns
 
-- `src/hooks.server.ts` stores a URL-selected tenant candidate separately, then
-  lets `createSessionHandler({ enterTenantContext: true })` establish the only
-  authorized tenant context. Never turn an untrusted header into authority.
-- `src/lib/server/smrt.ts` imports generated local registrations, loads the
-  generated manifest metadata, and uses the public users request-scoped DB API.
+- `src/hooks.server.ts` re-exports the runtime's `handle`/`init`: URL tenant
+  selection stays a separate candidate and only the verified session
+  establishes tenant context. Never turn an untrusted header into authority.
+- App code uses `runtime.getCollection()`/`runtime.classOptions()`, which are
+  request-scoped (RLS transaction) and must never be retained.
 - `Item` is the single example object and demonstrates optional tenant scope,
   a REST writable allowlist, shared CRUD action metadata, and the explicit
   collection registration required by generated CLI/MCP runtime commands.
@@ -71,18 +89,27 @@ It is the ground-up alternative to `smrt-saas-starter`.
   `depends('smrt:items')`, mutations call `invalidate('smrt:items')`, and
   hand-written writes call `assertOperationPermission()` with the session's
   exact permission snapshot.
-- The root layout uses Provider, the current smrt-ui ThemeProvider, AdminShell,
-  and a small explicit TenantNav. Generated REST routes do not imply page routes.
-- The root Provider registers generated WebMCP read tools with the authenticated
-  page session. Write/destructive effects require an explicit page-owned policy.
+- The root layout is `AppShell` from `@happyvertical/smrt-svelte/app` with a
+  small explicit `nav`; `/setup` and `/settings` mount that package's
+  `OwnerSetupForm` and `ShellSettingsPage`. Generated REST routes do not imply
+  page routes.
+- AppShell's Provider registers generated WebMCP read tools with the
+  authenticated page session. Write/destructive effects require an explicit
+  page-owned policy.
   Live browser collections remain opt-in per page and must seed from SSR
   `initialData` to avoid a duplicate first request.
-- `RuntimeDiagnosticsWebMcp` owns exactly one additional read-only tool,
-  `smrt.runtime.diagnostics.read`. It uses same-origin page-session fetch to the
-  authored `/api/_runtime/diagnostics` route and aborts its registration on
-  unmount. The route requires a direct active tenant membership plus either the
-  owner role or the explicit `runtime_diagnostics.read` permission before any
-  runtime projection/probe; it never calls principal-bound server tools.
+- AppShell's `runtimeDiagnostics` (on for signed-in sessions) owns exactly one
+  additional read-only tool, `smrt.runtime.diagnostics.read`, which fetches the
+  mounted `/api/_runtime/diagnostics` route as the page user. That route
+  (`createRuntimeDiagnosticsHandler`) requires a direct active tenant membership
+  plus the owner role or `runtime_diagnostics.read` before any projection or
+  probe; it never calls principal-bound server tools.
+- The opt-in `mcp-apps-template/` overlay is one `mountMcpAppRoute()` route
+  and the protected-resource metadata route, both using
+  `createHostedMcpResourceAuth({ profile, runtime })` (local owner tokens,
+  hosted membership-backed principals); `pnpm typecheck` checks it against
+  the template. `__tests__/localMcpToken.test.ts` proves mint → real
+  `smrt-mcp-bridge` stdio → route against the real runtime.
 
 ## Tests
 
@@ -126,11 +153,13 @@ own. Never add a mocked REST handler, an in-memory database, or DOM automation
 presented as WebMCP execution.
 
 - `@happyvertical/smrt-cli` is a devDependency **because the gate needs it**:
-  the app's `app:setup` migration step shells out to `pnpm exec smrt db:migrate`,
-  and the copied app deliberately never runs `pnpm install`, so `smrt` has to
-  arrive through the linked `node_modules/.bin`. The harness pins the app's own
-  `.bin` ahead of `PATH` and fails with a named error if that binary is missing,
-  so a host-global `smrt` cannot make a local run pass where CI fails.
+  the harness runs the app's own `smrt app setup` and `smrt app dev` from the
+  linked CLI, and setup's `pnpm build` is `smrt app build`. The copied app
+  deliberately never runs `pnpm install`, so `smrt` has to arrive through the
+  linked `node_modules`. The harness pins the app's own `.bin` ahead of `PATH`
+  and fails with a named error if the binary is missing, so a host-global
+  `smrt` cannot make a local run pass where CI fails. Identity and state-root
+  values it checks come from `@happyvertical/smrt-app-runtime`.
 - `pnpm test:e2e` runs the browser half.
 - `pnpm test:m5` runs the whole aggregate gate through
   `e2e/support/gate.mjs`, which requires a PostgreSQL service and fails when a
@@ -145,8 +174,12 @@ presented as WebMCP execution.
   from `testInfo.project.outputDir` and asserts it is outside the repository.
   The harness gives the copied app a real `node_modules` directory of
   individually symlinked entries rather than one symlink to this package's, so
-  the served app's `node_modules/.vite` cache cannot land in the checkout —
-  never replace that loop with a whole-directory symlink.
+  the served app's `node_modules/.vite` cache cannot land in the checkout.
+  Scope directories (`@happyvertical/`) and `.bin/` are real directories of
+  per-entry links too: the copy ships `pnpm-workspace.yaml` and setup runs
+  `pnpm build` in it, so anything pnpm relinks must land in the copy, never in
+  this package's `node_modules`. Never replace either loop with a
+  whole-directory symlink.
 - `e2e/` is outside `biome.json`'s include globs, as every package's `e2e/` is,
   so a green `Lint` job says nothing about this tree. `pnpm typecheck` covers
   the `.ts` files (`tsconfig.fixture.json` includes `e2e/**/*.ts`) but NOT

package/README.md

@@ -52,17 +52,21 @@ fixtures.
 
 ## 2. Understand the generated files
 
-The checked-in template contains authored objects, hooks, server helpers,
-pages, and configuration. Vite generates `.smrt/manifest.json`,
+The checked-in template contains authored objects, one server module
+(`src/lib/server/smrt.ts`, the runtime and its options), thin hooks and
+routes that mount package handlers, pages, and configuration. It ships no
+operator scripts. Vite generates `.smrt/manifest.json`,
 `.smrt/smrt-knowledge.json`, `.smrt/register.js`,
 `src/lib/server/smrt-register.ts`, `src/lib/types/smrt-generated/`, and
 `src/routes/api/**/+server.ts`. All are ignored and excluded from scaffold
 fixtures.
 
-`smrtPlugin()` scans the local object directory and generates local routes and
-types. `smrtConsumer()` explicitly consumes the profiles, tenancy, and users
-package manifests. `@happyvertical/smrt-cli` is a direct dev dependency because
-the generated package scripts and README invoke its `smrt` binary.
+`vite.config.ts` is `plugins: [sveltekit(), smrt()]`: the
+`@happyvertical/smrt-core/vite` preset applies the decorator transform, scans
+the local object directory, generates local routes and types, and consumes the
+packages `smrt.config.ts` lists under `consumer.packages` (profiles, tenancy,
+users). `@happyvertical/smrt-cli` is a direct dev dependency because every
+lifecycle script is `smrt app <operation>`.
 
 ## 3. Define the first object
 
@@ -85,25 +89,28 @@ pnpm db:migrate
 ```
 
 The script builds first to refresh manifests, registrations, types, and API
-routes, then runs `smrt db:migrate`. The deprecated `smrt db:setup` command is
+routes, then runs `smrt app migrate`, which holds the operation lock and runs
+`smrt db:migrate`. The deprecated `smrt db:setup` command is
 not documented or shipped.
 
 ## 5. Understand tenant context
 
-The template resolves a URL tenant candidate into separate
-`selectedTenantId`/`selectedTenantSlug` locals. It does not establish query
-context from that selection. The session hook runs afterward and only its
-membership-authorized tenant enters the s-m-r-t tenancy context.
+`src/hooks.server.ts` mounts `createSmrtSvelteKitRuntime()` from
+`@happyvertical/smrt-app-runtime/sveltekit`. It resolves a URL tenant candidate
+into separate `selectedTenantId`/`selectedTenantSlug` locals and does not
+establish query context from that selection. The session step runs afterward
+and only its membership-authorized tenant enters the s-m-r-t tenancy context.
 
-Untrusted tenant headers are ignored. Applications may replace
-`src/lib/server/tenancy.ts` with a path, signed-cookie, or trusted-gateway
-selector, but selection must remain separate from authorization and session
-switches must use `switchSessionTenant()`.
+Untrusted tenant headers are ignored. Applications may pass `selectTenant` for
+a path, signed-cookie, or trusted-gateway selector, but selection must remain
+separate from authorization and session switches must use
+`switchSessionTenant()`.
 
 ## 6. Understand users, profiles, memberships, roles, and permissions
 
 The generated project consumes the current profiles and users manifests and
-wires `createSessionHandler({ enterTenantContext: true })`. A User is the auth
+loads the signed session through the runtime, which enters tenant context only
+for a verified active membership. A User is the auth
 identity, Profile is person-facing metadata, Membership joins a User to a
 Tenant and Role, Role maps to Permission records, and Session publishes the
 resolved permission snapshot.

package/mcp-apps-template/package.dependencies.json

@@ -1,4 +1,4 @@
 {
-  "@happyvertical/smrt-app-mcp": "^0.53.3",
-  "@happyvertical/smrt-mcp-openai": "^0.53.3"
+  "@happyvertical/smrt-app-mcp": "^0.54.0",
+  "@happyvertical/smrt-mcp-openai": "^0.54.0"
 }

package/mcp-apps-template/src/routes/.well-known/oauth-protected-resource/api/mcp/+server.ts

@@ -1,7 +1,11 @@
-import { hostedMcpAuth } from '$lib/server/mcp-hosted';
+import { createHostedMcpResourceAuth } from '@happyvertical/smrt-app-mcp/auth';
+import { mountMcpProtectedResourceMetadataRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
 
-/** Serve exactly the RFC 9728 metadata URL advertised by hosted bearer challenges. */
-export function GET() {
-  const auth = hostedMcpAuth();
-  return auth?.metadataResponse() ?? new Response(null, { status: 404 });
-}
+import { runtime } from '$lib/server/smrt';
+
+const { profile } = await runtime.resolvedRuntime();
+
+/** RFC 9728 metadata at exactly the URL hosted bearer challenges advertise (404 locally). */
+export const GET = mountMcpProtectedResourceMetadataRoute(
+  createHostedMcpResourceAuth({ profile, runtime }),
+);

package/mcp-apps-template/src/routes/api/mcp/+server.ts

@@ -1,15 +1,71 @@
-import { mountMcpRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import type { McpWorkflowToolDefinition } from '@happyvertical/smrt-app-mcp';
+import { createHostedMcpResourceAuth } from '@happyvertical/smrt-app-mcp/auth';
+import { mountMcpAppRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import { openAiDisplayMetadata, withOpenAiEntrypoints } from '@happyvertical/smrt-mcp-openai';
 
-import { mcpServer, resolveMcpPrincipal } from '$lib/server/mcp';
-import { hostedMcpAuth } from '$lib/server/mcp-hosted';
+import { Item } from '$lib/objects/Item';
+import { runtime } from '$lib/server/smrt';
 
-/** Stateless SDK-v2 Streamable HTTP MCP endpoint. */
-const localRoute = mountMcpRoute(mcpServer, { resolvePrincipal: resolveMcpPrincipal });
+const ITEM_RESOURCE_URI = 'ui://smrt-app/v1/items.html';
+const itemResourceHtml = `<!doctype html><html lang="en"><head><title>Items</title></head><body><main tabindex="-1"><h1>Items</h1><p>Use the host controls to review your authorized items.</p></main></body></html>`;
 
-export async function POST(event: Parameters<typeof localRoute>[0]) {
-  const auth = hostedMcpAuth();
-  if (!auth) return localRoute(event);
-  const checked = await auth.authenticate(event.request);
-  if (!checked.ok) return checked.response;
-  return mountMcpRoute(mcpServer, { resolvePrincipal: () => checked.principal })(event);
-}
+const itemsOverview: McpWorkflowToolDefinition = withOpenAiEntrypoints(
+  {
+    name: 'items_overview',
+    description: 'Open the authorized item overview.',
+    title: 'Items',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    outputSchema: {
+      type: 'object',
+      properties: { state: { type: 'string' } },
+      required: ['state'],
+      additionalProperties: false,
+    },
+    effect: 'read',
+    idempotent: true,
+    openWorld: false,
+    ui: { resourceUri: ITEM_RESOURCE_URI },
+    async execute() {
+      return {
+        content: [{ type: 'text', text: 'Item overview is ready.' }],
+        structuredContent: { state: 'ready' },
+      };
+    },
+  },
+  ['global'],
+);
+
+const { profile } = await runtime.resolvedRuntime();
+
+/**
+ * Stateless SDK-v2 Streamable HTTP MCP endpoint for this app's own `Item`.
+ * Locally the principal is the signed session (user, authorized tenant, and
+ * permission slugs), or an owner-minted bearer token from `smrt app token`
+ * for a local MCP client such as the `smrt-mcp-bridge` stdio bridge. Hosted
+ * profiles verify a bearer access token and map it through the runtime's
+ * membership-backed `resolveMcpPrincipal` (pass `resolvePrincipal` to
+ * override it). A bearer principal is bound into the request permission
+ * context (under `database-rls`, its own RLS transaction) with its scopes
+ * capped to live permissions. Every principal needs `items.read`, so only
+ * read-only tools are published until per-operation authorization exists;
+ * browser requests from a foreign `Origin` are refused.
+ */
+export const POST = mountMcpAppRoute({
+  models: [Item],
+  requiredScopes: ['items.read'],
+  effects: ['read'],
+  smrtOptions: () => ({ db: runtime.databaseConfig() }),
+  auth: createHostedMcpResourceAuth({ profile, runtime }),
+  bindPrincipal: runtime.runAsPrincipal,
+  workflowTools: [itemsOverview],
+  resources: [
+    {
+      uri: ITEM_RESOURCE_URI,
+      version: 'v1',
+      name: 'Items',
+      html: itemResourceHtml,
+      csp: {},
+      metadata: openAiDisplayMetadata({ availableDisplayModes: ['inline'] }),
+    },
+  ],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.53.3",
+  "version": "0.54.0",
   "description": "Minimal SvelteKit project template with s-m-r-t framework integration",
   "type": "module",
   "main": "index.js",
@@ -32,23 +32,27 @@
     "directory": "packages/template-sveltekit"
   },
   "peerDependencies": {
-    "@happyvertical/smrt-core": "0.53.3"
+    "@happyvertical/smrt-core": "0.54.0"
   },
   "devDependencies": {
-    "@happyvertical/smrt-app-runtime": "0.53.3",
-    "@happyvertical/smrt-assets": "0.53.3",
-    "@happyvertical/smrt-cli": "0.53.3",
-    "@happyvertical/smrt-config": "0.53.3",
-    "@happyvertical/smrt-jobs": "0.53.3",
-    "@happyvertical/smrt-playbooks": "0.53.3",
-    "@happyvertical/smrt-profiles": "0.53.3",
-    "@happyvertical/smrt-scanner": "0.53.3",
-    "@happyvertical/smrt-svelte": "0.53.3",
-    "@happyvertical/smrt-tenancy": "0.53.3",
-    "@happyvertical/smrt-ui": "0.53.3",
-    "@happyvertical/smrt-users": "0.53.3",
-    "@happyvertical/smrt-web": "0.53.3",
+    "@happyvertical/smrt-app-cli": "0.54.0",
+    "@happyvertical/smrt-app-mcp": "0.54.0",
+    "@happyvertical/smrt-app-runtime": "0.54.0",
+    "@happyvertical/smrt-assets": "0.54.0",
+    "@happyvertical/smrt-cli": "0.54.0",
+    "@happyvertical/smrt-config": "0.54.0",
+    "@happyvertical/smrt-jobs": "0.54.0",
+    "@happyvertical/smrt-mcp-openai": "0.54.0",
+    "@happyvertical/smrt-playbooks": "0.54.0",
+    "@happyvertical/smrt-profiles": "0.54.0",
+    "@happyvertical/smrt-scanner": "0.54.0",
+    "@happyvertical/smrt-svelte": "0.54.0",
+    "@happyvertical/smrt-tenancy": "0.54.0",
+    "@happyvertical/smrt-ui": "0.54.0",
+    "@happyvertical/smrt-users": "0.54.0",
+    "@happyvertical/smrt-web": "0.54.0",
     "@happyvertical/sql": "^0.89.12",
+    "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@playwright/test": "^1.63.0",
     "@sveltejs/adapter-node": "^5.5.7",

package/template/AGENTS.md

@@ -18,7 +18,20 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   return only the schema-versioned allowlist; never expose private runtime
   objects, identity fields, paths, URLs, secrets, PII, raw errors, or logs.
 - Never improvise setup internals. Run `pnpm app:install`; use individual
-  `app:*` commands only for recovery or explicit operator control.
+  `app:*` commands only for recovery or explicit operator control. They call
+  `smrt app <operation>` from `@happyvertical/smrt-cli`; do not copy operator
+  scripts into this app.
+- Server composition (profile, storage custody, owner bootstrap, tenant
+  selection, session, health, diagnostics) comes from
+  `@happyvertical/smrt-app-runtime/sveltekit`, configured once in
+  `src/lib/server/smrt.ts`, which holds only `runtime` and its options. Pass
+  app-specific behaviour as options (`selectTenant`, `classOverrides`,
+  `session`, `prepareDatabase`); do not reimplement hooks, re-add the
+  `smrt-register` import (the `smrt()` plugin injects it), or export
+  `getCollection` (generated routes import this module and use its
+  `runtime.getCollection()`; a legacy export would win, deprecated).
+  `runtime.getCollection()`/`runtime.classOptions()` are request-scoped: never
+  keep their result beyond the request.
 - Recover an interrupted unclaimed owner invitation with `pnpm app:stop`, then
   `pnpm app:recover`, `pnpm app:start`, and `pnpm app:open`; never print or copy
   its token.
@@ -48,8 +61,9 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
 - Keep object relationship metadata close to `@smrt()`.
 - Add human-facing routes explicitly; generated REST routes do not create nav
   pages.
-- The root layout includes `@happyvertical/smrt-web` and registers generated
-  WebMCP read tools through Provider when the browser exposes `modelContext`.
+- The root layout is `AppShell` from `@happyvertical/smrt-svelte/app`; it
+  includes `@happyvertical/smrt-web` and registers generated WebMCP read tools
+  through its Provider when the browser exposes `modelContext`.
   Keep the guard in place for SSR and seed live collections with SSR
   `initialData`.
 - Do not enable knowledge HTTP routes in production without explicit admin auth.
@@ -57,8 +71,9 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   imports `.smrt/runtime/register.js` (compiled by `pnpm build`) before any
   runner starts, so jobs can target this app's own `@smrt()` objects; keep that
   import ahead of runner creation and keep domain objects free of SvelteKit
-  virtual modules (`$env/*`, `$app/*`), which a worker cannot load. Extend the
-  portability adapter instead of converting database files. Deployed provider
+  virtual modules (`$env/*`, `$app/*`), which a worker cannot load. Add a
+  `scripts/smrt-portability.mjs` adapter (it overrides the CLI's built-in one)
+  instead of converting database files. Deployed provider
   readiness must come from installed modules that probe the real backing
   services; environment booleans are not readiness evidence.
 - Every supported local web entry point (`app:start` or `pnpm dev`) holds the

package/template/Dockerfile

@@ -17,7 +17,6 @@ ENV NODE_ENV=production
 ENV SMRT_RUNTIME_PROFILE=self-hosted
 COPY --from=build /app/build ./build
 COPY --from=build /app/.smrt ./.smrt
-COPY --from=build /app/scripts ./scripts
 COPY --from=build /app/smrt.config.ts ./smrt.config.ts
 RUN chown -R node:node /app
 USER node

package/template/INSTALL_PROMPT.md

@@ -7,5 +7,5 @@
 > `pnpm app:doctor`, show me its secret-free recovery findings, and ask before
 > changing provider configuration.
 
-The prompt is intentionally thin. `scripts/smrt-app.mjs` owns operations and
-recovery.
+The prompt is intentionally thin. `smrt app` (from `@happyvertical/smrt-cli`)
+owns operations and recovery.