@stone-js/starters 0.8.3 → 0.8.5

package/full-service-imperative/package.json

@@ -22,14 +22,14 @@
   },
   "dependencies": {
     "@libsql/client": "^0.14.0",
-    "@stone-js/core": "^0.8.3",
-    "@stone-js/env": "^0.8.3",
-    "@stone-js/filesystem": "^0.8.3",
-    "@stone-js/http-core": "^0.8.3",
-    "@stone-js/node-cli-adapter": "^0.8.3",
-    "@stone-js/node-http-adapter": "^0.8.3",
-    "@stone-js/pipeline": "^0.8.3",
-    "@stone-js/router": "^0.8.3",
+    "@stone-js/core": "^0.8.5",
+    "@stone-js/env": "^0.8.5",
+    "@stone-js/filesystem": "^0.8.5",
+    "@stone-js/http-core": "^0.8.5",
+    "@stone-js/node-cli-adapter": "^0.8.5",
+    "@stone-js/node-http-adapter": "^0.8.5",
+    "@stone-js/pipeline": "^0.8.5",
+    "@stone-js/router": "^0.8.5",
     "bcryptjs": "^3.0.2",
     "drizzle-orm": "^0.44.2",
     "jsonwebtoken": "^9.0.2"
@@ -38,11 +38,14 @@
     "@babel/plugin-proposal-decorators": "^7.25.9",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
-    "@stone-js/cli": "^0.8.3",
+    "@stone-js/cli": "^0.8.5",
     "@types/jsonwebtoken": "^9.0.8",
     "@types/node": "^24.0.3",
     "@vitest/coverage-v8": "^3.0.9",
     "drizzle-kit": "^0.31.1",
     "vitest": "^3.0.9"
+  },
+  "overrides": {
+    "glob": "^11.0.0"
   }
 }

package/full-service-imperative/tests/PostService.spec.ts

@@ -0,0 +1,47 @@
+import { NotFoundError } from '@stone-js/http-core'
+import { factoryPostService } from '../app/services/PostService'
+import { IPostService } from '../app/services/contracts/IPostService'
+import { IPostRepository } from '../app/repositories/contracts/IPostRepository'
+import { Post } from '../app/models/Post'
+
+describe('factoryPostService', () => {
+  let service: IPostService
+  let postRepository: IPostRepository
+
+  beforeEach(() => {
+    postRepository = {
+      list: vi.fn(),
+      findById: vi.fn(),
+    } as unknown as IPostRepository
+
+    service = factoryPostService({ postRepository })
+  })
+
+  it('should delegate list() to the repository with the given limit', async () => {
+    // Arrange
+    const posts = [{ id: 1, title: 'Hello' }] as unknown as Post[]
+    ;(postRepository.list as any).mockResolvedValue(posts)
+
+    // Act
+    const result = await service.list(5)
+
+    // Assert
+    expect(result).toBe(posts)
+    expect(postRepository.list).toHaveBeenCalledWith({ limit: 5 })
+  })
+
+  it('should return the post when found and throw NotFoundError otherwise', async () => {
+    // Arrange
+    const post = { id: 42, title: 'Answer' } as unknown as Post
+    ;(postRepository.findById as any).mockResolvedValueOnce(post)
+
+    // Act & Assert (found)
+    await expect(service.findById(42)).resolves.toBe(post)
+
+    // Arrange (not found)
+    ;(postRepository.findById as any).mockResolvedValueOnce(undefined)
+
+    // Act & Assert (not found)
+    await expect(service.findById(99)).rejects.toBeInstanceOf(NotFoundError)
+  })
+})

package/full-service-imperative/tests/WelcomeEventHandler.spec.ts

@@ -0,0 +1,31 @@
+import { IncomingHttpEvent } from '@stone-js/http-core'
+import { factoryWelcomeEventHandler, WelcomePayload } from '../app/handlers/WelcomeEventHandler'
+
+describe('factoryWelcomeEventHandler', () => {
+  const makeEvent = (name?: string): IncomingHttpEvent => ({
+    get: vi.fn((_key: string, fallback: string) => name ?? fallback),
+  }) as unknown as IncomingHttpEvent
+
+  it('should return a branded Stone.js payload greeting the given name', () => {
+    // Act
+    const handler = factoryWelcomeEventHandler()
+    const payload = handler(makeEvent('Ada')) as unknown as WelcomePayload
+
+    // Assert
+    expect(payload.message).toBe('Hello Ada! Welcome to Stone.js.')
+    expect(payload.framework.name).toBe('Stone.js')
+    expect(payload.framework.tagline).toBe('The continuum framework')
+    expect(payload.framework.docs).toBe('https://stonejs.dev')
+    expect(payload.framework.github).toBe('https://github.com/stone-foundation/stone-js-framework')
+  })
+
+  it('should fall back to the default name when none is provided', () => {
+    // Act
+    const handler = factoryWelcomeEventHandler()
+    const payload = handler(makeEvent()) as unknown as WelcomePayload
+
+    // Assert
+    expect(payload.message).toBe('Hello Stone! Welcome to Stone.js.')
+    expect(payload.framework.name).toBe('Stone.js')
+  })
+})

package/full-service-imperative/vitest.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig } from 'vitest/config.js'
+import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stone-js/starters",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "This repository contains official **starter templates** for Stone.js applications.",
   "author": "Mr. Stone <evensstone@gmail.com>",
   "license": "MIT",

package/standard-react-declarative/app/pages/welcome/WelcomePage.tsx

@@ -1,6 +1,7 @@
 import { JSX } from 'react'
+import { Promiseable } from '@stone-js/core'
 import { WelcomeService } from '../../services/WelcomeService'
-import { Page, ReactIncomingEvent, PageRenderContext, IPage } from '@stone-js/use-react'
+import { Page, ReactIncomingEvent, PageRenderContext, PageHeadContext, HeadContext, IPage } from '@stone-js/use-react'
 
 /**
  * WelcomePage Options
@@ -42,6 +43,22 @@ export class WelcomePage implements IPage<ReactIncomingEvent> {
     return this.welcomeService.welcome(event.get<string>('name', 'World'))
   }
 
+  /**
+   * Set the page head tags, like title, meta, link, script, style.
+   *
+   * @returns The head context.
+   */
+  head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+    return {
+      title: `${String(event.get<string>('name', 'World'))} · Welcome to Stone.js`,
+      description: 'A universal Stone.js application. Write your domain once; Stone.js is the context that runs it anywhere.',
+      metas: [
+        { name: 'author', content: 'Stone.js' },
+        { name: 'keywords', content: 'stonejs,continuum,react,universal,framework' }
+      ]
+    }
+  }
+
   /**
    * Render the component.
    *
@@ -49,9 +66,25 @@ export class WelcomePage implements IPage<ReactIncomingEvent> {
    */
   render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
     return (
-      <section className='container'>
-        <h1 className='h1 text-center mt-64'>{data?.message}</h1>
-      </section>
+      <main className='stone-welcome'>
+        <div className='glow' aria-hidden='true' />
+        <section className='hero'>
+          <img className='mark' src='/logo.svg' alt='Stone.js' width={104} height={104} />
+          <p className='eyebrow'>Welcome to</p>
+          <h1 className='title'>Stone.js</h1>
+          <p className='lead'>{data?.message}</p>
+          <p className='tagline'>
+            Your app is running. Write your domain once, Stone.js is the context that runs it
+            anywhere: server, serverless, browser, CLI and the edge.
+          </p>
+          <nav className='links'>
+            <a href='https://stonejs.dev/docs' target='_blank' rel='noreferrer noopener'>Documentation</a>
+            <a href='https://github.com/stone-foundation/stone-js-framework' target='_blank' rel='noreferrer noopener'>GitHub</a>
+            <span className='edit'>Edit <b>app/pages/welcome/WelcomePage.tsx</b></span>
+          </nav>
+        </section>
+        <footer className='brand'><span className='dot'>●</span> Stone.js — the continuum framework</footer>
+      </main>
     )
   }
 }

package/standard-react-declarative/assets/css/index.css

@@ -1,26 +1,171 @@
-body {
-  margin: 0;
-  padding: 0;
-  color: #333;
-  font-size: 14px;
-  line-height: 1.5;
-  background-color: #fff;
-  font-family: 'Roboto', sans-serif;
+/**
+ * Stone.js starter — brand welcome screen.
+ * Identity: "Obsidienne & Braise" — obsidian ground, ember (braise) accent, the Portal mark.
+ * Theme-aware: dark by default, light under prefers-color-scheme: light.
+ */
+:root {
+  --ink: #14100E;
+  --ink-2: #1E1815;
+  --cream: #F4EFE6;
+  --cream-dim: #B8AE9E;
+  --ember-1: #FFC46B;
+  --ember-2: #FF5A1F;
+  --line: rgba(244, 239, 230, 0.10);
+  --card: rgba(244, 239, 230, 0.04);
+  --bg: radial-gradient(1200px 600px at 50% -10%, #241C17 0%, var(--ink) 55%);
 }
-.h1 {
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --ink: #F4EFE6;
+    --ink-2: #ffffff;
+    --cream: #1B1613;
+    --cream-dim: #6B6154;
+    --line: rgba(27, 22, 19, 0.10);
+    --card: rgba(27, 22, 19, 0.03);
+    --bg: radial-gradient(1200px 600px at 50% -10%, #FFFFFF 0%, #F1E9DC 60%);
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
   margin: 0;
-  font-weight: 500;
-  font-size: 3rem;
-  font-weight: bold;
+  min-height: 100vh;
+  color: var(--cream);
+  background: var(--ink);
+  font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
 }
-.container {
-  width: 100vw;
+
+.stone-welcome {
+  position: relative;
+  min-height: 100vh;
   display: flex;
+  flex-direction: column;
+  align-items: center;
   justify-content: center;
+  padding: 48px 24px;
+  background: var(--bg);
+  overflow: hidden;
+}
+
+/* Ember glow behind the mark. */
+.stone-welcome .glow {
+  position: absolute;
+  top: 8%;
+  left: 50%;
+  width: 520px;
+  height: 520px;
+  transform: translateX(-50%);
+  background: radial-gradient(circle, rgba(255, 90, 31, 0.22) 0%, rgba(255, 90, 31, 0) 68%);
+  filter: blur(8px);
+  pointer-events: none;
+  z-index: 0;
 }
-.text-center {
+
+.stone-welcome .hero {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  max-width: 680px;
   text-align: center;
+  animation: rise 0.7s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+}
+
+.stone-welcome .mark {
+  width: 104px;
+  height: 104px;
+  filter: drop-shadow(0 8px 28px rgba(255, 90, 31, 0.35));
+}
+
+.stone-welcome .eyebrow {
+  margin: 22px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.28em;
+  text-transform: uppercase;
+  color: var(--cream-dim);
+}
+
+.stone-welcome .title {
+  margin: 8px 0 0;
+  font-size: clamp(44px, 8vw, 76px);
+  font-weight: 800;
+  letter-spacing: -0.03em;
+  line-height: 1.02;
+  background: linear-gradient(92deg, var(--ember-1), var(--ember-2));
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+.stone-welcome .lead {
+  margin: 18px auto 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--cream);
+}
+
+.stone-welcome .tagline {
+  margin: 10px auto 0;
+  max-width: 46ch;
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--cream-dim);
+}
+
+.stone-welcome .links {
+  margin-top: 34px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  justify-content: center;
+}
+
+.stone-welcome .links a,
+.stone-welcome .links .edit {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 11px 18px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--card);
+  color: var(--cream);
+  font-size: 14px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: border-color 0.2s, transform 0.2s, background 0.2s;
+}
+
+.stone-welcome .links a:hover {
+  transform: translateY(-2px);
+  border-color: rgba(255, 90, 31, 0.6);
+  background: rgba(255, 90, 31, 0.08);
+}
+
+.stone-welcome .links .edit {
+  font-family: ui-monospace, 'SF Mono', Menlo, Monaco, Consolas, monospace;
+  color: var(--cream-dim);
+}
+.stone-welcome .links .edit b { color: var(--ember-1); font-weight: 700; }
+
+.stone-welcome .brand {
+  position: relative;
+  z-index: 1;
+  margin-top: 56px;
+  font-size: 13px;
+  letter-spacing: 0.02em;
+  color: var(--cream-dim);
+}
+.stone-welcome .brand .dot { color: var(--ember-2); }
+
+@keyframes rise {
+  from { opacity: 0; transform: translateY(14px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .stone-welcome .hero { animation: none; }
 }
-.mt-64 {
-  margin-top: 64px;
-}

package/standard-react-declarative/package.json

@@ -20,23 +20,26 @@
   "dependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@stone-js/use-react": "^0.8.3",
-    "@stone-js/browser-adapter": "^0.8.3",
-    "@stone-js/pipeline": "^0.8.3",
-    "@stone-js/http-core": "^0.8.3",
-    "@stone-js/node-http-adapter": "^0.8.3",
-    "@stone-js/router": "^0.8.3",
-    "@stone-js/core": "^0.8.3"
+    "@stone-js/use-react": "^0.8.5",
+    "@stone-js/browser-adapter": "^0.8.5",
+    "@stone-js/pipeline": "^0.8.5",
+    "@stone-js/http-core": "^0.8.5",
+    "@stone-js/node-http-adapter": "^0.8.5",
+    "@stone-js/router": "^0.8.5",
+    "@stone-js/core": "^0.8.5"
   },
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^7.25.9",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
-    "@stone-js/cli": "^0.8.3",
+    "@stone-js/cli": "^0.8.5",
     "@types/node": "^24.0.7",
     "@types/react": "^19.0.7",
     "@types/react-dom": "^19.0.3",
     "@vitest/coverage-v8": "^3.0.9",
     "vitest": "^3.0.9"
+  },
+  "overrides": {
+    "glob": "^11.0.0"
   }
 }

package/standard-react-declarative/public/logo.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="Stone.js">
+  <title>Stone.js</title>
+  <style>
+    .ink { stroke: #1B1613; }
+    @media (prefers-color-scheme: dark) { .ink { stroke: #EFE8DC; } }
+  </style>
+  <defs>
+    <linearGradient id="braise" gradientUnits="userSpaceOnUse" x1="22" y1="14" x2="74" y2="26.1">
+      <stop offset="0" stop-color="#FFC46B" />
+      <stop offset="1" stop-color="#FF5A1F" />
+    </linearGradient>
+  </defs>
+  <path class="ink" d="M 79.96 36.4 A 34 34 0 0 1 53.9 81.5" fill="none" stroke-width="11" stroke-linecap="round" opacity=".85" />
+  <path class="ink" d="M 42.1 81.5 A 34 34 0 0 1 16.05 36.4" fill="none" stroke-width="11" stroke-linecap="round" opacity=".85" />
+  <path d="M 22 26.1 A 34 34 0 0 1 74 26.1" fill="none" stroke="url(#braise)" stroke-width="11" stroke-linecap="round" />
+</svg>

package/standard-react-declarative/tests/WelcomePage.spec.ts

@@ -0,0 +1,71 @@
+import { ILogger } from '@stone-js/core'
+import { renderToString } from 'react-dom/server'
+import { ReactIncomingEvent } from '@stone-js/use-react'
+import { WelcomePage } from '../app/pages/welcome/WelcomePage'
+import { WelcomeService } from '../app/services/WelcomeService'
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/use-react', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    Page: vi.fn(() => vi.fn()),
+  }
+})
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/core', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    Service: vi.fn(() => vi.fn()),
+  }
+})
+
+describe('WelcomePage', () => {
+  let page: WelcomePage
+  let mockedLogger: ILogger
+
+  beforeEach(() => {
+    mockedLogger = {
+      info: vi.fn(),
+    } as unknown as ILogger
+
+    page = new WelcomePage({ welcomeService: new WelcomeService({ logger: mockedLogger }) })
+  })
+
+  it('should handle incoming events', () => {
+    // Arrange
+    const expectedMessage = 'Hello World!'
+    const event = { get: () => 'World' } as unknown as ReactIncomingEvent
+
+    // Act
+    const response = page.handle(event)
+
+    // Assert
+    expect(response.message).toBe(expectedMessage)
+    expect(mockedLogger.info).toHaveBeenCalledWith('Welcome World')
+  })
+
+  it('should render the message', () => {
+    // Arrange
+    const message = 'Hello World!'
+
+    // Act
+    const response = renderToString(page.render({ data: { message } } as any))
+
+    // Assert
+    expect(response).toContain(message)
+  })
+
+  it('should render the Stone.js logo', () => {
+    // Act
+    const response = renderToString(page.render({ data: { message: 'Hello World!' } } as any))
+
+    // Assert
+    expect(response).toContain('/logo.svg')
+    expect(response).toContain('alt="Stone.js"')
+    expect(response).toContain('Welcome')
+    expect(response).toContain('Stone.js')
+  })
+})

package/standard-react-imperative/app/pages/welcome/WelcomePage.tsx

@@ -1,6 +1,7 @@
 import { JSX } from 'react'
+import { Promiseable } from '@stone-js/core'
 import { WelcomeService } from '../../services/WelcomeService'
-import { definePage, IPage, PageRenderContext, ReactIncomingEvent } from '@stone-js/use-react'
+import { definePage, IPage, PageRenderContext, PageHeadContext, HeadContext, ReactIncomingEvent } from '@stone-js/use-react'
 
 /**
  * WelcomePage Options
@@ -30,6 +31,22 @@ export const WelcomePage = ({ welcomeService }: WelcomePageOptions): IPage<React
     return welcomeService.welcome(event.get<string>('name', 'World'))
   },
 
+  /**
+   * Set the page head tags, like title, meta, link, script, style.
+   *
+   * @returns The head context.
+   */
+  head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+    return {
+      title: `${String(event.get<string>('name', 'World'))} · Welcome to Stone.js`,
+      description: 'A universal Stone.js application. Write your domain once; Stone.js is the context that runs it anywhere.',
+      metas: [
+        { name: 'author', content: 'Stone.js' },
+        { name: 'keywords', content: 'stonejs,continuum,react,universal,framework' }
+      ]
+    }
+  },
+
   /**
    * Render the component.
    *
@@ -37,9 +54,25 @@ export const WelcomePage = ({ welcomeService }: WelcomePageOptions): IPage<React
    */
   render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
     return (
-      <section className='container'>
-        <h1 className='h1 text-center mt-64'>{data?.message}</h1>
-      </section>
+      <main className='stone-welcome'>
+        <div className='glow' aria-hidden='true' />
+        <section className='hero'>
+          <img className='mark' src='/logo.svg' alt='Stone.js' width={104} height={104} />
+          <p className='eyebrow'>Welcome to</p>
+          <h1 className='title'>Stone.js</h1>
+          <p className='lead'>{data?.message}</p>
+          <p className='tagline'>
+            Your app is running. Write your domain once, Stone.js is the context that runs it
+            anywhere: server, serverless, browser, CLI and the edge.
+          </p>
+          <nav className='links'>
+            <a href='https://stonejs.dev/docs' target='_blank' rel='noreferrer noopener'>Documentation</a>
+            <a href='https://github.com/stone-foundation/stone-js-framework' target='_blank' rel='noreferrer noopener'>GitHub</a>
+            <span className='edit'>Edit <b>app/pages/welcome/WelcomePage.tsx</b></span>
+          </nav>
+        </section>
+        <footer className='brand'><span className='dot'>●</span> Stone.js — the continuum framework</footer>
+      </main>
     )
   }
 })