@happyvertical/smrt-template-sveltekit 0.38.25 → 0.39.0

package/AGENTS.md

@@ -1,31 +1,50 @@
 # template-sveltekit
 
-Base SvelteKit project template used by `smrt init`. Scaffolds a full-stack, multi-tenant app with SMRT integration.
+Minimal SvelteKit project template used by `smrt gnode create --template=sveltekit`.
+It is the ground-up alternative to `smrt-saas-starter`.
 
 ## Exports
 
-- `getTemplatePath()` — returns path to template directory
-- `copyTemplate(destination, options)` — copies template files with project name substitution. Skips internal-only directories (e.g. `.svelte-kit/` tsconfig stub).
-- `templateInfo` — metadata (SvelteKit 2.x, Svelte 5, REST API, SMRT CLI, SQLite, multi-tenant)
-
-## Template Contents
-
-- `template/src/hooks.server.ts` — pre-wires `enableTenancy()`, `createSessionHandler({ enterTenantContext: true })`, and a subdomain → tenantId handle, sequenced in that order
-- `template/src/lib/server/tenancy.ts` — pluggable tenant resolver (`subdomainStrategy`, `pathPrefixStrategy`, `headerStrategy`, `createTenantResolver`)
-- `template/src/lib/server/smrt.ts` — centralized SmrtClassOptions / collection factory; imports the plugin-generated `smrt-register.js` (guarded — the file is gitignored and regenerated on every dev/build run) and seeds `.smrt/manifest.json` so server runtimes get package-qualified registrations + scanned field metadata (without them, writes silently drop domain columns)
-- `template/vite.config.ts` — smrtPlugin() + smrtConsumer(), plus explicit `oxc: { decorator: { legacy: true } }` (Vite 8's oxc transform does not reliably honor `experimentalDecorators` through the SvelteKit tsconfig `extends` chain)
-- `template/src/lib/objects/Item.ts` — example `@smrt()` object
-- `template/src/routes/+page.server.ts` + `+page.svelte` — reference SSR data loading: server load queries collections directly (opt-in read cache via `cache: { ttl }`), declares `depends('smrt:items')`, and a form action + `invalidate('smrt:items')` demonstrates post-mutation refresh
-- `template/src/app.d.ts` — `App.Locals` extends `SessionLocals` from `@happyvertical/smrt-users/sveltekit`
-
-## Test Infrastructure
-
-- Tests live in `__tests__/` at the package root — **not** inside `template/` — because `cpSync` would otherwise scaffold them into consumer projects.
-- The template's `template/tsconfig.json` extends `./.svelte-kit/tsconfig.json` (per SvelteKit convention). To let the package run its tests without first running `svelte-kit sync`, a vitest `globalSetup` hook at `__tests__/setup/svelte-kit-stub.ts` writes a minimal stub at test startup and removes it at teardown. The stub directory is gitignored AND `copyTemplate()` filters it out as defense-in-depth.
-
-## Key Patterns
-
-- **SSR data loading convention**: reference pages load collection data in `+page.server.ts` (serialized into the HTML, hydrated without a duplicate client fetch). Loads declare `depends('smrt:<collection>')` (REST route segment naming: `/api/items` → `smrt:items`); mutations call `invalidate('smrt:<collection>')` to re-run them.
-- **Pluggable tenant resolver**: `tenancy.ts` exports strategy functions + a `createTenantResolver()` factory. Consumers swap strategies by editing one line.
-- **File copying with placeholder substitution**: project name is replaced in template files during generation.
-- **No template-internal test pollution**: `__tests__/` and the `.svelte-kit/` stub are package-level and excluded from `copyTemplate` output.
+- `getTemplatePath()` returns the template directory.
+- `copyTemplate(destination, options)` copies authored files, substitutes the
+  project package name, and skips `.svelte-kit` plus test-fixture directories.
+- `templateInfo` describes the SvelteKit, SQLite, generated-interface, session,
+  tenancy, and permission foundation.
+
+## Current generated-project contract
+
+- Node `>=24.18.0`; pnpm `10.34.4` via `packageManager` and `engines`.
+- Directly used `@happyvertical/smrt-*` packages are pinned to `0.38.25`.
+- `@happyvertical/smrt-cli` is a direct dev dependency because scripts/docs use
+  its binary. `@happyvertical/smrt-web` stays opt-in until a page imports it.
+- `smrtConsumer()` explicitly consumes profiles, tenancy, and users manifests;
+  `smrtPlugin()` scans `src/lib/objects`, generates Vite virtual definitions,
+  SvelteKit routes, runtime registration, and knowledge artifacts.
+- `pnpm db:migrate` builds first to refresh generated artifacts, then runs the
+  current manifest-driven migration command. Do not restore deprecated
+  `smrt db:setup` documentation.
+
+## 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.
+- `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.
+- Initial data comes from `+page.server.ts`; loads declare
+  `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.
+- WebMCP and live browser data examples are opt-in per page and must seed live
+  collections from SSR `initialData` to avoid a duplicate first request.
+
+## Tests
+
+Tests live in package-level `__tests__/`, never under `template/`. Vitest's
+global setup creates a temporary `.svelte-kit/tsconfig.json` stub and removes it
+afterward; `copyTemplate()` filters the directory as defense in depth.

package/README.md

@@ -1,113 +1,151 @@
 # @happyvertical/smrt-template-sveltekit
 
-SvelteKit project template with SMRT framework integration. Scaffolds a full-stack app with auto-generated REST API routes, TypeScript, and SQLite.
+The minimal “learn and build from the ground up” SvelteKit template for
+s-m-r-t 0.38.25. The package exports `copyTemplate()`, `getTemplatePath()`, and
+`templateInfo` and is the `sveltekit` template used by `smrt gnode create`.
 
-## What This Template Provides
+## 1. Install and run
 
-- SvelteKit 2.x with Svelte 5 and TypeScript
-- `smrtPlugin()` Vite integration for automatic REST API route generation
-- Example `@smrt()` object (`Item.ts`) with barrel export
-- Reference SSR data loading: `+page.server.ts` server load with the `depends('smrt:<collection>')` / `invalidate('smrt:<collection>')` refresh convention and opt-in collection read caching
-- Server-side SMRT initialization (`src/lib/server/smrt.ts`)
-- `smrt.config.ts` with SQLite database and optional AI provider
-- `.env.example` with starter environment variables
-- **Multi-tenancy pre-wired**: `src/hooks.server.ts` registers the tenancy interceptor, loads sessions via `createSessionHandler({ enterTenantContext: true })`, and resolves the tenant from a leading subdomain (`acme.demo.local` → `tenantId='acme'`). Strategy is swappable in `src/lib/server/tenancy.ts` — see the template's own README for path-prefix / header-based variants.
-
-## Prerequisites
-
-- Node.js 18+
-- pnpm (recommended) or npm
-
-## Usage
-
-### With smrt CLI (recommended)
+Scaffold through the public CLI:
 
 ```bash
-smrt gnode create my-app --template sveltekit
+node --input-type=module -e "import { copyTemplate } from './packages/template-sveltekit/index.js'; copyTemplate('./my-app', { name: 'my-app' })"
 cd my-app
-npm install
-npm run dev
+pnpm install
+cp .env.example .env
+pnpm db:migrate
+pnpm check
+pnpm build
+pnpm dev
 ```
 
-### Programmatic usage
+Run the copy command from the monorepo root. The public 0.38.25 CLI advertises
+`gnode create`, but its command dispatcher currently rejects `gnode`; this
+package's tested `copyTemplate()` export is the working scaffold path.
 
-```javascript
+Generated projects require Node.js 24.18.0 or newer and pnpm 10.34.4. They pin
+all directly used `@happyvertical/smrt-*` packages to 0.38.25.
+
+For programmatic scaffolding:
+
+```js
 import { copyTemplate } from '@happyvertical/smrt-template-sveltekit';
 
-copyTemplate('./my-new-project', {
+copyTemplate('/absolute/path/to/my-app', {
   name: 'my-app',
   overwrite: false,
 });
 ```
 
-## Getting Started (after scaffolding)
+`copyTemplate()` substitutes the package name and excludes package-internal
+`.svelte-kit` and test fixtures.
+
+## 2. Understand the generated files
+
+The checked-in template contains authored objects, hooks, server helpers,
+pages, and configuration. 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.
+
+## 3. Define the first object
+
+The generated `src/lib/objects/Item.ts` is one optional-tenant object with
+title, description, and status fields. Its small explicit `ItemCollection`
+constructor keeps generated CLI/MCP runtime commands constructible. Its
+`@smrt()` configuration exposes CRUD to REST, MCP, WebMCP definitions, and CLI
+while using an API writable allowlist.
+
+Add objects beside Item and export them from `src/lib/objects/index.ts`.
+`vite.config.ts` already scans that directory.
+
+## 4. Initialize or migrate the database
+
+Generated projects use SQLite at `./app.db` by default:
 
 ```bash
-cd my-app
-npm install
-cp .env.example .env    # Edit with your values
-npm run dev             # Start dev server at http://localhost:5173
+pnpm db:migrate
 ```
 
-## Environment Variables
+The script builds first to refresh manifests, registrations, types, and API
+routes, then runs `smrt db:migrate`. The deprecated `smrt db:setup` command is
+not documented or shipped.
 
-Defined in `.env.example`:
+## 5. Understand tenant context
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DATABASE_URL` | Yes | Database path (default: `./data/app.db`) |
-| `DATABASE_TYPE` | Yes | Database engine (default: `sqlite`) |
-| `PUBLIC_SITE_NAME` | No | Display name for the site |
-| `PUBLIC_SITE_URL` | No | Public URL (default: `http://localhost:5173`) |
-| `OPENAI_API_KEY` | No | OpenAI API key for AI features |
-| `ANTHROPIC_API_KEY` | No | Anthropic API key (alternative AI provider) |
+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.
 
-## Template Structure
+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()`.
 
-```
-template/
-├── .env.example            # Environment variable defaults
-├── .gitignore
-├── package.json            # Dependencies (smrt-core, SvelteKit)
-├── smrt.config.ts          # SMRT configuration (DB, AI, schema migration)
-├── svelte.config.js        # SvelteKit config (adapter-auto)
-├── tsconfig.json
-├── vite.config.ts          # Vite + smrtPlugin() for API route generation
-└── src/
-    ├── app.d.ts            # SvelteKit type declarations (extends SessionLocals)
-    ├── app.html            # HTML shell
-    ├── hooks.server.ts     # Pre-wired auth + tenancy
-    ├── lib/
-    │   ├── objects/
-    │   │   ├── index.ts    # Barrel export
-    │   │   └── Item.ts     # Example @smrt() object
-    │   └── server/
-    │       ├── smrt.ts     # Server-side SMRT initialization + manifest seeding
-    │       ├── smrt-register.ts # Object registration (generated by smrtPlugin, gitignored)
-    │       └── tenancy.ts  # Pluggable tenant resolver
-    └── routes/
-        ├── +page.server.ts # Home page server load + demo mutation (reference pattern)
-        └── +page.svelte    # Home page
-```
+## 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
+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.
 
-## Exports
+The home-page form action calls `assertOperationPermission()` with that exact
+snapshot. Provider-specific login and provisioning remain app-owned extension
+points.
 
-This package exposes three things for programmatic use:
+## 7. Load data into a SvelteKit page
 
-- `getTemplatePath()` -- returns the absolute path to the `template/` directory
-- `copyTemplate(destination, options)` -- copies template files with project name substitution in `package.json`
-- `templateInfo` -- metadata object describing the template
+The home page loads Item rows in `+page.server.ts`, returns plain serialized
+data, and declares `depends('smrt:items')`. The Svelte 5 page reads hydrated
+`$props()` data and calls `invalidate('smrt:items')` after a successful form
+mutation. It does not fetch initial data in `onMount` or `$effect`.
 
-## Placeholder Substitution
+## 8. Use generated REST, MCP, WebMCP, and CLI interfaces
 
-During `smrt gnode create`, these placeholders are replaced in template files:
+REST routes are generated under `src/routes/api`. MCP and WebMCP descriptors
+come from the same action metadata. CLI commands are available through the
+declared dev dependency:
+
+```bash
+pnpm smrt objects
+pnpm smrt schema Item
+pnpm smrt generate-mcp --no-config --no-readme
+```
+
+WebMCP registration is documented as an opt-in, per-page integration using
+`collectionDefinitions` from `@happyvertical/smrt-virt-web` and
+`registerWebMcpTools()` from `@happyvertical/smrt-web`. CRUD is wired in
+0.38.25; custom action execution is not yet wired and is documented as such.
+The CLI's manifest-only `objects` and `schema` commands work in this
+source-first template. Local-object CRUD execution through the generic CLI
+additionally requires a compiled JavaScript project entry point.
+
+## 9. Add optional live browser data
+
+`@happyvertical/smrt-web` is intentionally not a base direct dependency. A
+consumer adds it only when a page imports the live collection or WebMCP runtime:
+
+```bash
+pnpm add @happyvertical/smrt-web@0.38.25
+```
 
-| Placeholder | Value |
-|-------------|-------|
-| `{{PROJECT_NAME}}` | Project name from CLI |
-| `{{PACKAGE_NAME}}` | Lowercase, hyphenated package name |
+The generated-project README shows the current hydration pattern:
+`createSmrtCollection(getCollectionDefinition('items'), { initialData,
+basePath: '/api' })` followed by `liveCollection()`. The root layout does not
+load the browser engine.
 
-## Related
+## 10. Graduate to smrt-saas-starter
 
-- [SMRT Framework](https://github.com/happyvertical/smrt)
-- [SvelteKit](https://kit.svelte.dev/)
+Use this template for learning and focused, ground-up applications. Choose
+`smrt-saas-starter` when the baseline should already contain production-shaped
+onboarding, billing/subscriptions, workers, provider configuration, deployment
+infrastructure, and mobile applications. This package intentionally avoids
+becoming a second SaaS starter.

package/index.js

@@ -22,7 +22,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * vendored `.svelte-kit/tsconfig.json` stub that lets the template's own
  * tests typecheck without first running `svelte-kit sync`).
  */
-const COPY_SKIP = new Set(['.svelte-kit']);
+const COPY_SKIP = new Set(['.svelte-kit', '__tests__', 'test', 'tests']);
 
 /**
  * Get the path to the template directory
@@ -81,14 +81,14 @@ export function copyTemplate(destination, options = {}) {
  */
 export const templateInfo = {
   name: 'sveltekit',
-  description: 'SvelteKit project with SMRT framework integration',
+  description: 'Minimal SvelteKit project with s-m-r-t framework integration',
   features: [
     'SvelteKit 2.x with Svelte 5',
     'Auto-generated REST API routes',
-    'SMRT CLI integration',
+    's-m-r-t CLI integration',
     'TypeScript support',
     'SQLite database (configurable)',
-    'Multi-tenant ready (session + subdomain tenant resolution wired)',
+    'Session-authorized tenancy with separate subdomain selection',
   ],
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.38.25",
-  "description": "SvelteKit project template with SMRT framework integration",
+  "version": "0.39.0",
+  "description": "Minimal SvelteKit project template with s-m-r-t framework integration",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -29,17 +29,19 @@
     "directory": "packages/template-sveltekit"
   },
   "peerDependencies": {
-    "@happyvertical/smrt-core": "0.38.25"
+    "@happyvertical/smrt-core": "workspace:*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
     "vitest": "^4.1.9"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}

package/template/.env.example

@@ -1,11 +1,7 @@
 # Database
-DATABASE_URL=./data/app.db
+DATABASE_URL=./app.db
 DATABASE_TYPE=sqlite
 
-# AI Provider (optional)
-OPENAI_API_KEY=
-# ANTHROPIC_API_KEY=
-
-# Site
-PUBLIC_SITE_NAME=My SMRT App
-PUBLIC_SITE_URL=http://localhost:5173
+# Optional apex used for subdomain tenant selection.
+# The value selects a tenant candidate; session membership still authorizes it.
+TENANT_BASE_DOMAIN=demo.local

package/template/AGENTS.md

@@ -1,34 +1,35 @@
-# SMRT SvelteKit App
+# s-m-r-t SvelteKit app
 
-This project uses SMRT objects to generate REST routes, CLI commands, MCP
-tools, and agent/developer knowledge artifacts.
+This project uses s-m-r-t objects to generate REST routes, CLI commands, MCP
+tools, WebMCP definitions, and agent/developer knowledge artifacts.
 
-## Agent Workflow
+## Agent workflow
 
-- Treat `.smrt/smrt-knowledge.json` as generated local context.
-- Regenerate knowledge by running the app build or dev server with
-  `smrtPlugin()` enabled.
-- Use `smrt knowledge:review-context --format markdown` or the
-  `build-domain-review-context` MCP tool before reviewing SMRT object changes.
-- Use `smrt knowledge:architecture-context --format markdown` or the
-  `build-domain-architecture-context` MCP tool when planning new SMRT objects.
+- Treat `.smrt/`, `src/routes/api/**/+server.ts`,
+  `src/lib/server/smrt-register.ts`, and
+  `src/lib/types/smrt-generated/` as generated.
+- Regenerate them with `pnpm build` or `pnpm dev`; run `pnpm db:migrate` after
+  object schema changes.
 - Keep `CLAUDE.md` as the one-line `@AGENTS.md` shim.
 
-## Package Guidance
+## Data and authorization
 
-- Load page data in `+page.server.ts` server loads that query collections
-  directly (see `src/routes/+page.server.ts`); never fetch `/api/*` from
-  `$effect`/`onMount` for initial page data.
-- Declare `depends('smrt:<collection>')` in loads (route segment naming:
-  `/api/items` → `smrt:items`) and call `invalidate('smrt:<collection>')`
-  after mutations to refresh in place.
-- Opt read-heavy SSR reads into the collection cache with
-  `list({ cache: { ttl } })`; skip it for per-user data and admin editors
-  (see README "Data loading").
-- Keep SMRT object relationship metadata close to the `@smrt()` decorator.
-- Use `knowledge: false` only for objects that should stay out of authored
-  agent context while remaining in the runtime manifest.
-- Use `knowledge: { tags, summary, risks }` for domain objects with important
-  review or architecture constraints.
-- Do not enable `/__smrt/knowledge` HTTP routes in production without explicit
-  admin auth.
+- Load initial page data in `+page.server.ts`, return plain serializable rows,
+  and never fetch initial `/api/*` data from `onMount` or `$effect`.
+- Declare `depends('smrt:<collection>')` in loads and call
+  `invalidate('smrt:<collection>')` after mutations.
+- URL tenant selection lives in `selectedTenantId`/`selectedTenantSlug`; it is
+  not authorization. Only the session-authorized `tenantId` may scope queries.
+- Ignore untrusted tenant headers. Use `switchSessionTenant()` for
+  membership-gated browser tenant changes.
+- Use `assertOperationPermission()` for hand-written server mutations and pass
+  the exact session permission snapshot when available.
+
+## Extension rules
+
+- Keep object relationship metadata close to `@smrt()`.
+- Add human-facing routes explicitly; generated REST routes do not create nav
+  pages.
+- Add `@happyvertical/smrt-web` only when a dedicated page imports live browser
+  data or registers WebMCP tools. Seed live collections with SSR `initialData`.
+- Do not enable knowledge HTTP routes in production without explicit admin auth.