@happyvertical/smrt-template-sveltekit 0.30.0

package/AGENTS.md

@@ -0,0 +1,28 @@
+# template-sveltekit
+
+Base SvelteKit project template used by `smrt init`. Scaffolds a full-stack, multi-tenant app with SMRT integration.
+
+## 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
+- `template/src/lib/objects/Item.ts` — example `@smrt()` object
+- `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
+
+- **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.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @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.
+
+## What This Template Provides
+
+- 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
+- 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)
+
+```bash
+smrt gnode create my-app --template sveltekit
+cd my-app
+npm install
+npm run dev
+```
+
+### Programmatic usage
+
+```javascript
+import { copyTemplate } from '@happyvertical/smrt-template-sveltekit';
+
+copyTemplate('./my-new-project', {
+  name: 'my-app',
+  overwrite: false,
+});
+```
+
+## Getting Started (after scaffolding)
+
+```bash
+cd my-app
+npm install
+cp .env.example .env    # Edit with your values
+npm run dev             # Start dev server at http://localhost:5173
+```
+
+## Environment Variables
+
+Defined in `.env.example`:
+
+| 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) |
+
+## Template Structure
+
+```
+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
+    │       └── tenancy.ts  # Pluggable tenant resolver
+    └── routes/
+        └── +page.svelte    # Home page
+```
+
+## Exports
+
+This package exposes three things for programmatic use:
+
+- `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
+
+## Placeholder Substitution
+
+During `smrt gnode create`, these placeholders are replaced in template files:
+
+| Placeholder | Value |
+|-------------|-------|
+| `{{PROJECT_NAME}}` | Project name from CLI |
+| `{{PACKAGE_NAME}}` | Lowercase, hyphenated package name |
+
+## Related
+
+- [SMRT Framework](https://github.com/happyvertical/smrt)
+- [SvelteKit](https://kit.svelte.dev/)

package/index.js

@@ -0,0 +1,99 @@
+/**
+ * SMRT SvelteKit Template
+ *
+ * Provides the SvelteKit project template for SMRT framework.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Paths inside `template/` that are not part of the scaffold output. These
+ * exist only to support test-time tooling at the monorepo level (e.g. the
+ * 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']);
+
+/**
+ * Get the path to the template directory
+ */
+export function getTemplatePath() {
+  return join(__dirname, 'template');
+}
+
+/**
+ * Copy the template to a destination directory
+ *
+ * @param {string} destination - Destination directory path
+ * @param {object} options - Options for template copying
+ * @param {string} [options.name] - Project name (updates package.json)
+ * @param {boolean} [options.overwrite=false] - Overwrite existing files
+ */
+export function copyTemplate(destination, options = {}) {
+  const templatePath = getTemplatePath();
+
+  if (!existsSync(templatePath)) {
+    throw new Error('Template directory not found');
+  }
+
+  // Create destination if it doesn't exist
+  if (!existsSync(destination)) {
+    mkdirSync(destination, { recursive: true });
+  }
+
+  // Copy all template files, skipping internal-only directories
+  cpSync(templatePath, destination, {
+    recursive: true,
+    force: options.overwrite || false,
+    filter: (src) => {
+      const relative = src.slice(templatePath.length + 1);
+      if (!relative) return true;
+      const topLevel = relative.split(/[\\/]/)[0];
+      return !COPY_SKIP.has(topLevel);
+    },
+  });
+
+  // Update package.json with project name if provided
+  if (options.name) {
+    const packageJsonPath = join(destination, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      packageJson.name = options.name;
+      writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+    }
+  }
+
+  return destination;
+}
+
+/**
+ * Template metadata
+ */
+export const templateInfo = {
+  name: 'sveltekit',
+  description: 'SvelteKit project with SMRT framework integration',
+  features: [
+    'SvelteKit 2.x with Svelte 5',
+    'Auto-generated REST API routes',
+    'SMRT CLI integration',
+    'TypeScript support',
+    'SQLite database (configurable)',
+    'Multi-tenant ready (session + subdomain tenant resolution wired)',
+  ],
+};
+
+export default {
+  getTemplatePath,
+  copyTemplate,
+  templateInfo,
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@happyvertical/smrt-template-sveltekit",
+  "version": "0.30.0",
+  "description": "SvelteKit project template with SMRT framework integration",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./template/*": "./template/*"
+  },
+  "files": [
+    "CLAUDE.md",
+    "README.md",
+    "index.js",
+    "template",
+    "AGENTS.md"
+  ],
+  "keywords": [
+    "smrt",
+    "sveltekit",
+    "template",
+    "scaffold"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/template-sveltekit"
+  },
+  "peerDependencies": {
+    "@happyvertical/smrt-core": "0.30.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.17"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/template/.env.example

@@ -0,0 +1,11 @@
+# Database
+DATABASE_URL=./data/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

package/template/AGENTS.md

@@ -0,0 +1,25 @@
+# SMRT SvelteKit App
+
+This project uses SMRT objects to generate REST routes, CLI commands, MCP
+tools, and agent/developer knowledge artifacts.
+
+## 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.
+- Keep `CLAUDE.md` as the one-line `@AGENTS.md` shim.
+
+## Package Guidance
+
+- 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.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -0,0 +1,204 @@
+# SMRT SvelteKit App
+
+A SvelteKit application with SMRT framework integration for rapid development of AI-powered, multi-tenant applications.
+
+## Getting Started
+
+1. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+2. **Set up environment**:
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Start development server**:
+   ```bash
+   npm run dev
+   ```
+
+4. **Initialize database** (optional):
+   ```bash
+   smrt db:setup
+   ```
+
+## Project Structure
+
+```
+├── src/
+│   ├── hooks.server.ts        # Auth + tenancy wiring (see "Multi-tenancy" below)
+│   ├── lib/
+│   │   ├── objects/           # SMRT objects (auto-generates API routes)
+│   │   │   ├── index.ts       # Export all objects here
+│   │   │   └── Item.ts        # Example SMRT object
+│   │   └── server/
+│   │       ├── smrt.ts        # SMRT configuration
+│   │       └── tenancy.ts     # Pluggable tenant resolver
+│   └── routes/
+│       ├── api/               # Auto-generated API routes (don't edit!)
+│       └── +page.svelte       # Home page
+├── smrt.config.ts             # Root SMRT config
+├── vite.config.ts             # Vite + SMRT plugin config
+└── svelte.config.js           # SvelteKit config
+```
+
+## Multi-tenancy
+
+This template ships with multi-tenancy pre-wired. Out of the box you get:
+
+- **Session loading + auth** via `createSessionHandler({ enterTenantContext: true })` from `@happyvertical/smrt-users/sveltekit`. After the hook runs, `event.locals` carries `{ user, permissions, tenantId, sessionId }`.
+- **Auto-scoped REST routes**. The tenancy interceptor is registered globally (`enableTenancy()` in `hooks.server.ts`), so any model decorated with `@TenantScoped()` is filtered by the current tenant in `AsyncLocalStorage`. The generated `src/routes/api/**` endpoints inherit this automatically.
+- **Subdomain-based tenant resolution**. By default, the leading subdomain is the tenant slug:
+
+  | URL | Tenant ID |
+  |---|---|
+  | `https://acme.demo.local/dashboard` | `acme` |
+  | `https://www.demo.local/` | `null` (reserved) |
+  | `https://demo.local/` | `null` (no subdomain) |
+  | `http://localhost:5173/` | `null` (root-like host) |
+
+### Local development DNS
+
+Browsers won't resolve subdomains of `demo.local` to your dev server automatically. Pick one:
+
+**Option A — `/etc/hosts` (simplest, fixed list)**
+
+```
+127.0.0.1   demo.local
+127.0.0.1   acme.demo.local
+127.0.0.1   shop.acme.demo.local
+```
+
+**Option B — `dnsmasq` (wildcard, recommended)**
+
+```bash
+# macOS
+brew install dnsmasq
+echo 'address=/demo.local/127.0.0.1' | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
+sudo brew services restart dnsmasq
+# Tell macOS to use dnsmasq for `.local` queries
+sudo mkdir -p /etc/resolver
+echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/local
+```
+
+After either, hit `http://acme.demo.local:5173/` and the tenant will resolve to `acme`.
+
+### Swapping the resolution strategy
+
+`src/lib/server/tenancy.ts` exposes three built-in strategies plus a `createTenantResolver()` factory. Pick whichever matches your routing:
+
+```ts
+// Subdomain (default)
+import {
+  createTenantResolver,
+  subdomainStrategy,
+} from '$lib/server/tenancy';
+export const resolveTenant = createTenantResolver(subdomainStrategy);
+
+// Path prefix:  /t/<slug>/...
+import {
+  createTenantResolver,
+  pathPrefixStrategy,
+} from '$lib/server/tenancy';
+export const resolveTenant = createTenantResolver(pathPrefixStrategy());
+
+// Custom prefix:  /tenant/<slug>/...
+export const resolveTenant = createTenantResolver(
+  pathPrefixStrategy({ prefix: '/tenant/' }),
+);
+
+// HTTP header:  x-tenant-id: acme
+import {
+  createTenantResolver,
+  headerStrategy,
+} from '$lib/server/tenancy';
+export const resolveTenant = createTenantResolver(headerStrategy());
+
+// Compose:  try subdomain, fall back to header
+import {
+  createTenantResolver,
+  headerStrategy,
+  subdomainStrategy,
+} from '$lib/server/tenancy';
+export const resolveTenant = createTenantResolver((event) => {
+  const fromSubdomain = subdomainStrategy(event);
+  if (fromSubdomain.tenantId) return fromSubdomain;
+  return headerStrategy()(event);
+});
+```
+
+Inside a `+server.ts` or `+page.server.ts` you can read the resolved tenant either from `event.locals.tenantId` (set by the session handler) or — for any tenant-scoped model — just call its collection methods and the global interceptor will filter automatically.
+
+## Creating SMRT Objects
+
+1. Create a new file in `src/lib/objects/`:
+
+```typescript
+// src/lib/objects/Product.ts
+import { SmrtObject, smrt } from '@happyvertical/smrt-core';
+import { TenantScoped, tenantId } from '@happyvertical/smrt-tenancy';
+
+@smrt({
+  api: { include: ['list', 'get', 'create', 'update', 'delete'] },
+  cli: { include: ['list', 'get'] },
+})
+@TenantScoped({ mode: 'optional' })
+export class Product extends SmrtObject {
+  @tenantId({ nullable: true })
+  tenantId: string | null = null;
+
+  name: string = '';
+  price: number = 0.0;
+  description: string = '';
+  active: boolean = true;
+}
+```
+
+2. Export it from `src/lib/objects/index.ts`:
+
+```typescript
+export { Item } from './Item.js';
+export { Product } from './Product.js';
+```
+
+3. Run `npm run dev` - API routes are auto-generated! Because `Product` is `@TenantScoped`, listing via `GET /api/products` will only return rows for the request's tenant. (The generator pluralizes each class's `collection` field; see the "Generated API Routes" table below for the general `/api/{collection}` form.)
+
+## CLI Commands
+
+```bash
+# List discovered SMRT objects
+smrt objects
+
+# View object details
+smrt introspect
+
+# Initialize database tables
+smrt db:setup
+
+# Regenerate API routes
+smrt generate-routes
+
+# Run operations on objects
+smrt item list
+smrt item get <id>
+```
+
+## API Endpoints
+
+For each SMRT object, the following endpoints are auto-generated:
+
+- `GET /api/{collection}` - List all items
+- `GET /api/{collection}/[id]` - Get single item
+- `POST /api/{collection}` - Create new item
+- `PUT /api/{collection}/[id]` - Update item
+- `DELETE /api/{collection}/[id]` - Delete item
+
+Custom methods are exposed as:
+- `POST /api/{collection}/[id]/{method}` - Call custom method
+
+## Learn More
+
+- [SMRT Framework Documentation](https://github.com/happyvertical/smrt)
+- [SvelteKit Documentation](https://kit.svelte.dev/)

package/template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "smrt-sveltekit-app",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "typecheck": "svelte-kit sync && tsc --noEmit && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.46.0",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "svelte": "^5.18.0",
+    "svelte-check": "^4.3.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@happyvertical/smrt-core": "^0.25.8",
+    "@happyvertical/smrt-tenancy": "^0.25.8",
+    "@happyvertical/smrt-users": "^0.25.8"
+  }
+}

package/template/smrt.config.ts

@@ -0,0 +1,49 @@
+/**
+ * SMRT Configuration
+ *
+ * This file configures the SMRT framework for your project.
+ * See: https://github.com/happyvertical/smrt
+ */
+
+export default {
+  // Global SMRT settings
+  smrt: {
+    logLevel: 'info',
+    schemaMigration: {
+      strategy: 'auto-add',
+    },
+  },
+
+  // Agent/developer knowledge artifacts are generated by smrtPlugin().
+  // HTTP API routes stay off unless explicitly enabled for a dev/admin-only workflow.
+  knowledge: {
+    enabled: true,
+    api: {
+      enabled: false,
+      basePath: '/__smrt/knowledge',
+      requireAdmin: true,
+      includeDocs: false,
+      includePrompts: false,
+    },
+  },
+
+  // Package-specific configuration
+  packages: {
+    // CLI configuration
+    cli: {
+      database: {
+        type: 'sqlite',
+        url: process.env.DATABASE_URL || './data/app.db',
+      },
+      verbose: false,
+    },
+
+    // AI configuration (optional)
+    ai: process.env.OPENAI_API_KEY
+      ? {
+          provider: 'openai',
+          apiKey: process.env.OPENAI_API_KEY,
+        }
+      : undefined,
+  },
+};

package/template/src/app.d.ts

@@ -0,0 +1,24 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+
+import type { SessionLocals } from '@happyvertical/smrt-users/sveltekit';
+
+declare global {
+  namespace App {
+    // interface Error {}
+    interface Locals extends SessionLocals {
+      /**
+       * Tenant context object set by the smrt-tenancy SvelteKit handle.
+       * `event.locals.tenantId` (from SessionLocals) is the canonical id
+       * string; this object carries the full context (permissions,
+       * superAdminBypass, etc.) when needed.
+       */
+      tenantContext?: import('@happyvertical/smrt-tenancy').MinimalTenantContext;
+    }
+    // interface PageData {}
+    // interface PageState {}
+    // interface Platform {}
+  }
+}
+
+export {};

package/template/src/app.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%sveltekit.assets%/favicon.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>