@owlmeans/create-app 0.1.18-rc.13 → 0.1.18-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.18-rc.13",
+  "version": "0.1.18-rc.14",
   "license": "MIT",
   "description": "Scaffold a minimal fullstack OwlMeans Common app — common + api + web workspaces, shadcn UI navigation/layout, no auth, and a session-scoped in-memory resource. Deploys agent skills via @owlmeans/agent-skills by default.",
   "type": "module",
@@ -29,7 +29,7 @@
     "template"
   ],
   "dependencies": {
-    "@owlmeans/agent-skills": "^0.1.18-rc.10"
+    "@owlmeans/agent-skills": "^0.1.18-rc.11"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/_agents/skills/getting-started/SKILL.md

@@ -14,8 +14,11 @@ A minimal OwlMeans app is a **bun-workspace monorepo with three packages**:
 ```
 sources/
 ├── common/   # shared entrypoints (routes), AJV schemas, types, config — the single source of truth
+│             #   entrypoints.ts
 ├── api/      # @owlmeans/server-app backend; handlers attached to the shared entrypoints
+│             #   context.ts, entrypoints.ts, app/<area>/*, index.ts
 └── web/      # @owlmeans/web-panel + shadcn UI; screens attached to the same entrypoints
+              #   context.ts, entrypoints.ts, nav.ts, layout/, screens/, index.tsx
 ```
 
 The full, runnable walkthrough (scaffolded **and** manual) lives in
@@ -27,8 +30,8 @@ The full, runnable walkthrough (scaffolded **and** manual) lives in
 Declare each route once in `common` as an **entrypoint**, then `elevate()` it on each side:
 
 ```ts
-// common/modules.ts — declaration + validation, no implementation
-export const sessionModules = [
+// common/entrypoints.ts — declaration + validation, no implementation
+export const sessionEntrypoints = [
   entrypoint(route(session.base, '/session')),
   entrypoint(route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
     filter(params<SessionParams>(SessionParamsSchema))),
@@ -38,17 +41,25 @@ export const sessionModules = [
 ```
 
 ```ts
-// api/modules.ts — attach handlers
-elevate(sessionModules, session.list, handlers.list)
-export const appModules = [...modules, ...sessionModules]        // `modules` = framework defaults
+// api/entrypoints.ts — attach handlers
+elevate(sessionEntrypoints, session.list, handlers.list)
+export const appEntrypoints = [...entrypoints, ...sessionEntrypoints]   // `entrypoints` = framework defaults
 ```
 
 ```ts
-// web/modules.ts — attach screen components, plus call-only elevation for backend routes
-elevate(modules, session.list)                                    // callable from the client
-modules.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
+// web/entrypoints.ts — attach screen components, plus call-only elevation for backend routes
+const entrypoints = [...baseEntrypoints, ...sessionEntrypoints]   // `baseEntrypoints` from web-panel
+elevate(entrypoints, session.list)                                // callable from the client
+entrypoints.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
+export const appEntrypoints = entrypoints
 ```
 
+A route declaration is plain data: its `path` is the SEGMENT it contributes under its `parent`, and
+nothing ever rewrites it. `session.list` reads `/:sid/items` under `session.base`'s `/session`,
+under the api service's `base: 'api'` — so the address is `GET /api/session/:sid/items`, computed
+on demand by whoever asks. `elevate` is idempotent, so re-elevating an alias is allowed and guards
+given at elevation are added to the declared ones.
+
 Change a route or schema in `common` and both sides stay in sync. See [[entrypoint]], [[route]],
 [[server-app]], [[web-client]], [[web-panel]].
 
@@ -61,6 +72,8 @@ prefixes API routes with `/api`:
 const cfg = service({ type: AppType.Frontend, service: APP_WEB, host: 'localhost', port: 3001 })
 service({ type: AppType.Backend, service: APP_API, host: 'localhost', port: 3000, base: 'api' }, cfg)
 cfg.debug = { all: true }
+cfg.alias = APP
+cfg.security = { unsecure: true }   // local dev serves the API over plain HTTP
 export const commonConfig = cfg
 ```
 
@@ -75,9 +88,20 @@ appendStaticResource(context, SESSION_ITEMS)    // @owlmeans/static-resource —
 ```
 
 Handlers use `handleRequest` / `handleBody` / `handleParams` (validated payload, then context, then
-req). Read/write `ctx.getStaticResource<T>(alias)` — full CRUD (`get/load/list/create/save/delete`).
-**`static-resource.list()` takes no criteria** — list all and filter in JS (e.g. by `sessionId`).
-`main(context, appModules)` starts the server. See [[static-resource]], [[server-app]], [[resource]].
+req). Read/write `ctx.getStaticResource<T>(alias)` — the full resource contract
+(`get/load/list/count/create/update/save/delete/take/purge`), so the resource answers the whole
+question rather than the handler filtering afterwards:
+
+```ts
+const { items } = await resource.list(
+  { sessionId: params.sid },
+  { sort: [{ field: 'createdAt', order: 'desc' }] }
+)
+```
+
+`list` returns `{ items, total }`; the in-memory backends are unpaged unless a `size` is asked for.
+`main(context, appEntrypoints)` starts the server. See [[static-resource]], [[server-app]],
+[[resource]].
 
 Swap `@owlmeans/static-resource` for [[mongo-resource]] / [[redis-resource]] when you need
 persistence — the handler shape is identical.
@@ -86,19 +110,36 @@ persistence — the handler shape is identical.
 
 `@owlmeans/web-panel`'s `PanelApp` is shadcn/Tailwind v4 (no MUI). The **app provides** the shadcn
 primitives at the `@` alias — `web-panel` references `@/lib/utils` and
-`@/components/ui/{alert,button,card,input,label,progress}`; copy those into `src/`. Render with
-`provide` from `@owlmeans/web-client`:
+`@/components/ui/{alert,button,card,input,label,navigation-menu,progress}`; copy those into `src/`.
+Routing resolves itself from the active router plugin, so `PanelApp` takes no router prop:
 
 ```tsx
-basicRender(<PanelApp context={context} provide={provide} />)
+basicRender(<PanelApp context={context} />)
 ```
 
 `vite.config.ts` sets `@`→`src`, `@tailwindcss/vite`, and dedupes the owlmeans/react singletons.
 `index.css` is `@import "tailwindcss";` + a shadcn `@theme` token block (replaces `@owlmeans/owl-theme`).
 A parent `BASE` route renders the layout via `handler(LayoutComponent)`; `HOME` is its default child.
-Screens call the backend with `context.entrypoint(alias).call({ params, body })` → `[data, outcome]`.
+`index.tsx` calls `context.registerEntrypoints(appEntrypoints)` and `context.serviceRoute(...)` for
+each service, then renders.
+
+Screens address the backend through three explicit verbs on the entrypoint:
+
+```tsx
+const items = await ctx.entrypoint<ClientEntrypoint<Item[]>>(session.list).call({ params: { sid } })
+const { value, outcome } = await ctx.entrypoint<ClientEntrypoint<Item>>(session.add).invoke({ body })
+const href = await ctx.entrypoint<ClientEntrypoint<string>>(web.about).url()
+```
+
+`call` resolves to the VALUE and throws the reply's error; `invoke` gives `{ value, outcome }` when
+the outcome decides what happens next; `url` gives the address (`{ absolute: true }` forces a fully
+qualified one). A screen entrypoint answers `url()` and refuses `call()` — a screen is navigated to.
 See [[web-panel]], [[web-client]], [[shadcn-web]], [[client-entrypoint]].
 
+The screen keeps nothing in component state: `makeContext` registers a `@owlmeans/state` resource,
+the fetch writes what came back into it with `store.replace(items)`, and `useStoreList` renders the
+live subscription. See [[state]].
+
 ## Authentication
 
 This shape is intentionally **auth-free**. To add it: `@owlmeans/server-auth` + `@owlmeans/client-auth`

package/template/sources/api/src/app/session/list.ts

@@ -7,9 +7,11 @@ export const list = handleParams<SessionParams>(async (params, context) => {
   const ctx = context as Context
   const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
 
-  // The static resource lists every record; filter to this session and sort newest first.
-  const { items } = await resource.list<SessionItem>()
+  // The resource answers the whole question — this session's items, newest first.
+  const { items } = await resource.list(
+    { sessionId: params.sid },
+    { sort: [{ field: 'createdAt', order: 'desc' }] }
+  )
+
   return items
-    .filter(item => item.sessionId === params.sid)
-    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
 })

package/template/sources/api/src/app/session/remove.ts

@@ -7,7 +7,7 @@ export const remove = handleParams<ItemParams>(async (params, context) => {
   const ctx = context as Context
   const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
 
-  const existing = await resource.load<SessionItem>(params.id)
+  const existing = await resource.load(params.id)
   // Only remove the item if it belongs to the requesting session.
   if (existing == null || existing.sessionId !== params.sid) {
     return { removed: false }

package/template/sources/api/src/context.ts

@@ -10,9 +10,5 @@ export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =
   // data lives in process memory and is cleared when the api restarts.
   appendStaticResource<C, T>(context, SESSION_ITEMS)
 
-  // A child context has to inherit THIS factory, not the layer's — otherwise a derived context
-  // is built without the resource registered above and every lookup on it throws.
-  context.makeContext = makeContext as typeof context.makeContext
-
   return context
 }

package/template/sources/api/src/entrypoints.ts

@@ -0,0 +1,11 @@
+import { elevate, entrypoints } from '@owlmeans/server-app'
+import { session, sessionEntrypoints } from '__APP_SLUG__-common'
+import * as handlers from './app/session/index.js'
+
+// Attach handler implementations to the shared entrypoint declarations.
+elevate(sessionEntrypoints, session.base)
+elevate(sessionEntrypoints, session.list, handlers.list)
+elevate(sessionEntrypoints, session.add, handlers.add)
+elevate(sessionEntrypoints, session.remove, handlers.remove)
+
+export const appEntrypoints = [...entrypoints, ...sessionEntrypoints]

package/template/sources/api/src/index.ts

@@ -1,9 +1,9 @@
 import { main } from '@owlmeans/server-app'
 import config from './config.js'
 import { makeContext } from './context.js'
-import { appModules } from './modules.js'
+import { appEntrypoints } from './entrypoints.js'
 import type { Config, Context } from './types.js'
 
 const context = makeContext<Config, Context>(config)
 
-main<{}, Config, Context>(context, appModules)
+main<{}, Config, Context>(context, appEntrypoints)

package/template/sources/common/src/{modules.ts → entrypoints.ts}

@@ -9,7 +9,7 @@ import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
  * elevates them with screen components and calls them. Routes resolve under the
  * api service `base` (`/api`), so e.g. `session.list` → `GET /api/session/:sid/items`.
  */
-export const sessionModules = [
+export const sessionEntrypoints = [
   entrypoint(route(session.base, '/session')),
   entrypoint(
     route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),

package/template/sources/common/src/index.ts

@@ -2,4 +2,4 @@ export * from './consts.js'
 export * from './types.js'
 export * from './schemas.js'
 export * from './config.js'
-export * from './modules.js'
+export * from './entrypoints.js'

package/template/sources/web/src/context.ts

@@ -15,9 +15,5 @@ export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =
   // the app in a module of its own.
   appendStateResource<C, T>(context, SESSION_STATE)
 
-  // A child context has to inherit THIS factory, not the layer's. Without the line, a derived
-  // context is built without the resource registered above and every lookup on it throws.
-  context.makeContext = makeContext as typeof context.makeContext
-
   return context
 }

package/template/sources/web/src/entrypoints.ts

@@ -0,0 +1,22 @@
+import { BASE, elevate, entrypoint, entrypoints as baseEntrypoints, frontend, handler, HOME, route } from '@owlmeans/web-panel'
+import { session, sessionEntrypoints, web } from '__APP_SLUG__-common'
+import { MainLayout } from './layout/main.js'
+import { AboutScreen } from './screens/about.js'
+import { HomeScreen } from './screens/home.js'
+import { SessionScreen } from './screens/session.js'
+
+const entrypoints = [...baseEntrypoints, ...sessionEntrypoints]
+
+// Backend entrypoints — elevated without a component so the client can call them.
+elevate(entrypoints, session.base)
+elevate(entrypoints, session.list)
+elevate(entrypoints, session.add)
+elevate(entrypoints, session.remove)
+
+// Frontend layout + screens. BASE renders the shared layout; HOME is its default child.
+entrypoints.push(entrypoint(route(BASE, '/', frontend()), handler(MainLayout)))
+entrypoints.push(entrypoint(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(HomeScreen)))
+entrypoints.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
+entrypoints.push(entrypoint(route(web.about, '/about', frontend({ parent: BASE })), handler(AboutScreen)))
+
+export const appEntrypoints = entrypoints

package/template/sources/web/src/index.tsx

@@ -2,12 +2,12 @@ import './index.css'
 import { APP_API, APP_WEB } from '__APP_SLUG__-common'
 import config from './config.js'
 import { makeContext } from './context.js'
-import { appModules } from './modules.js'
+import { appEntrypoints } from './entrypoints.js'
 import { render } from './render.js'
 import type { Config, Context } from './types.js'
 
 const context = makeContext<Config, Context>(config)
-context.registerEntrypoints(appModules)
+context.registerEntrypoints(appEntrypoints)
 
 context.serviceRoute(APP_WEB, true)
 context.serviceRoute(APP_API, true)

package/template/sources/web/src/screens/session.tsx

@@ -33,15 +33,15 @@ export const SessionScreen: FC = () => {
    */
   const items = useStoreList<SessionItem>({ query: {}, resource: SESSION_STATE })
 
-  // The server is the source of truth; the store is what the screen reads. Fetch once, write
-  // what came back into the store, and let the subscription render it.
+  // The server is the source of truth; the store is what the screen reads. Fetch once, install
+  // what came back, and let the subscription render it. `replace` rather than a save per item:
+  // the endpoint answers with the session's whole set, so an item removed on another tab has to
+  // leave the store too, and one write wakes the subscribers once instead of once per record.
   const load = async () => {
-    const [data] = await ctx
+    const data = await ctx
       .entrypoint<ClientEntrypoint<SessionItem[]>>(session.list)
       .call({ params: { sid } })
-    for (const item of data ?? []) {
-      await store.save(item)
-    }
+    await store.replace(data ?? [])
   }
 
   useEffect(() => { void load() }, [])
@@ -50,7 +50,7 @@ export const SessionScreen: FC = () => {
     if (text.trim() === '') return
     setBusy(true)
     try {
-      const [item] = await ctx
+      const item = await ctx
         .entrypoint<ClientEntrypoint<SessionItem>>(session.add)
         .call({ params: { sid }, body: { text } })
       setText('')

package/template/sources/api/src/modules.ts

@@ -1,11 +0,0 @@
-import { elevate, modules } from '@owlmeans/server-app'
-import { session, sessionModules } from '__APP_SLUG__-common'
-import * as handlers from './app/session/index.js'
-
-// Attach handler implementations to the shared entrypoint declarations.
-elevate(sessionModules, session.base)
-elevate(sessionModules, session.list, handlers.list)
-elevate(sessionModules, session.add, handlers.add)
-elevate(sessionModules, session.remove, handlers.remove)
-
-export const appModules = [...modules, ...sessionModules]

package/template/sources/web/src/modules.ts

@@ -1,22 +0,0 @@
-import { BASE, elevate, entrypoint, frontend, handler, HOME, modules as baseModules, route } from '@owlmeans/web-panel'
-import { session, sessionModules, web } from '__APP_SLUG__-common'
-import { MainLayout } from './layout/main.js'
-import { AboutScreen } from './screens/about.js'
-import { HomeScreen } from './screens/home.js'
-import { SessionScreen } from './screens/session.js'
-
-const modules = [...baseModules, ...sessionModules]
-
-// Backend entrypoints — elevated without a component so the client can call them.
-elevate(modules, session.base)
-elevate(modules, session.list)
-elevate(modules, session.add)
-elevate(modules, session.remove)
-
-// Frontend layout + screens. BASE renders the shared layout; HOME is its default child.
-modules.push(entrypoint(route(BASE, '/', frontend()), handler(MainLayout)))
-modules.push(entrypoint(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(HomeScreen)))
-modules.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
-modules.push(entrypoint(route(web.about, '/about', frontend({ parent: BASE })), handler(AboutScreen)))
-
-export const appModules = modules